dsh-sansheng-liubu/docs/host-contract-research.md

85 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 三省六部 v0.0.1 宿主公开契约调研
日期:2026-11-14。对象:本机 DSH Desktop runtime 0.2.2-rc.3。只读研究,没有创建、恢复、配置真实会话,没有读取凭据,没有修改宿主/profile/node_modules。唯一写入为本笔记。安装包 ASAR 可由 read 读取,但 glob 无法遍历,声明入口列在 package exports 中、实际声明文件未随安装包提供;因此以下为公开包运行时实现和 DS Bot 调用交叉核实的 JS 调用签名,不冒充完整 TypeScript 声明。原 10–15 次读取预算未守住:ASAR/声明失败探测及重复读取导致超额,此处明确记录。
## 结论
采用一个独立轻量插件,直接使用宿主注入服务。每个项目绑定独立 canonical cwd/workspaceId 和固定十个 roleId → sessionId。不要装载 DS Bot,也不要调用历史 dsbot-runtime;不需要任何群 session。原型可以只做十个普通 root session + 项目配置存储 + 一个动态 systemPrompt section。
尤其不能把 sessionController.create 当恢复;不能调用 sessionController.selectModel 达成“不写 profile”,因为它会后台保存全局默认。无 profile 模型切换是 agent.model.select(selection),前置用 llm 验证路由。不存在已证实的通用 session.configure 或 agents.find 方法;不要从名字猜接口。
## 可直接用的调用契约
下列 C 代表公开包 @deepseek-ai/dsh-api-session-controller 的 lib/index.js;A 代表 @deepseek-ai/dsh-agent 的 lib/index.js;W 代表 @deepseek-ai/dsh-workspace 的 lib/index.js。源码绝对根为 C:/Users/qyh15/AppData/Local/Programs/DeepSeek Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/。应用代码只能 import 公开包名字或使用 ctx 服务,不能硬编码此安装路径。
- ctx.workspaceRegistry.get(workspaceId) → Workspace | undefined,同步。W:445。
- ctx.workspaceRegistry.list() → Workspace[],同步、durable registry order。W:454。
- await ctx.workspaceRegistry.resolveByPath(path) → Workspace | undefined,realpath 规范化。W:643。
- await ctx.workspaceRegistry.create(path, title?) → Workspace,目录须存在且为目录,相同 canonical path 重用。W:408,647。
- await workspace.attachSession(sessionId),第一次绑定读取 header.cwd、realpath 后必须等于 workspace.path;不是随意移动会话。W:111–124。workspace.sessionIds 是已有索引过滤后的成员列表。
- await ctx.sessionController.create({sessionId?, workspaceId?, cwd?, agentPreset?}) → {sessionId, agentPreset?}。workspaceId 与 cwd 互斥;使用 workspaceId 时从 workspace.path 得到 cwd。C:724–755,4017。
- await ctx.sessionController.resolveAgent(sessionId) → {agent} | {error},DS Bot 的 delivery.js:10–11 使用此方法;宿主 resolver 会恢复冷会话并按 ID 合并并发 resume,拒绝 subagent 所有的会话。C:175–203。error 必须传播,不能把所有错误当不存在。
- ctx.agents.get(sessionId) → Agent | undefined,只查询活跃内存实例,不恢复;ctx.agents.list() → Agent[]。A:720–728。
- await ctx.agents.create(options)、await ctx.agents.resume(options) 是公开底层工厂入口,但需要正确 preset/setup 生命周期;v0.0.1 优先用 controller,避免手工组成 Agent。A:582–600。
- await ctx.sessionController.rename({sessionId,title}) → {title,seq},内部恢复 Agent 后经 sessionTitle.rename 记录标题。C:792–805。
- await ctx.sessionController.modelCatalog() 返回提供者分组模型、deployment default、isolated provider failures;不要假设模型目录中存在即有可用余额/凭据。C:4044–4049。
- await ctx.llm.resolveCallConfig({provider,model,reasoningEffort?}) 验证路由/effort;controller 用它先校验再 select。C:772。
- agent.model.current() → {provider,model,reasoningEffort?} | undefined;agent.model.select(selection) → void,同步追加 model/selection 事件,相同完整选择不重复追加。A:190–202。
- ctx.systemPrompt.section({name,order,interpolate:false,text: context => string}) → disposer。DS Bot prompt.js:67–72 使用,返回文本按 context.agent.id 查角色;不属于本项目的 session 返回空字符串。插件卸载时释放注册。
### 模型配置最小路线
```js
const resolved = await ctx.sessionController.resolveAgent(sessionId)
if ('error' in resolved) throw resolved.error
const agent = resolved.agent
const selection = { provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) }
await ctx.llm.resolveCallConfig(selection)
// 再次核对对象仍是此 ID 的活跃 Agent,以及项目映射/版本未发生变化。
if (ctx.agents.get(sessionId) !== agent) throw new Error('Agent changed during configuration')
agent.model.select(selection)
return agent.model.current()
```
select 自身仅记录会话事件,不验证字符串的业务合法性,因此不能省略验证。controller 另外会 requireModel 并检查目录可用性;自建 adapter 应从 modelCatalog 检查 provider/model/effort 后调用 resolveCallConfig。不要调用任何 credentials.get/read,不要为检测可用性发真实模型请求。
## 恢复、去重和生命周期
创建前持久化项目十个 roleId、计划 sessionId 和 provisioning 状态,每角色串行锁(跨进程需持久锁/唯一约束)。然后对计划 ID 查询/resolve;只有明确 session/not-found 才尝试创建。网络/持久层/迁移/preset 错误保留 pending,不生成新 ID。
controller.create 的 request.sessionId 是“空会话复用意图”,不是永久幂等键:内部 claim 可因为已有 turn/start、归档、workspace 不可复用等情况改为 createMinted,并返回另一个随机 ID(C:229, claim 分支,414)。因此调用后必须比较 returned.sessionId 与 plannedId;不一致应记录实际返回 ID 和异常、停止后续创建,不能悄悄覆盖映射或删除记录。workspace attach 失败返回 session/workspace-attach-failed 并附已创建 sessionId(C:744–750),同样须保留并在恢复时修复归属,不能再次创建。
若 session 已存在则核对 header.cwd、root 身份(无 subagent ownership)、预期 workspace 和本地项目/角色映射,随后恢复该 ID。不要用标题匹配身份,不要调用 create 恢复已有聊天。发现用户归档或移走角色会话时提示修复,不自动补造第十一个会话。
新建普通 controller 会话通过 agents.create({sessionId, agentOptions, meta:{cwd,agentPreset?},setup}) 创建(C:423–431),没有 parent/subagent 参数;因此是 root session,不继承某个对话父代理。初始模型从 agentDefaultModel.currentSelection getter 读取(C:433–445),故每角色必须在允许首轮发送前固定自己的 model/selection。
持久角色文字保存在插件项目状态,而不是只存内存 closure。启动先加载映射再注册 prompt section;配置更新后按 sessionId 读取最新版。宿主保留普通会话日志/模型事件;插件保留 roleId、身份、配置版本。禁止 DS Bot 的“上下文满则新 part session”行为,否则固定十个约束被破坏。
## 运行中修改模型
A:137–172 的 projection 保留 lastUsed 与 pending;current 返回 pending ?? lastUsed;request/header 只在匹配时消耗 pending。A:224–237 明确每一步的 route 已固定,并在下一 step 比较模型变化生成提示。因此新选择不会替换已经发出的模型请求;影响后续取样的 step,可能在同一个 turn 内发生。UI 应说明“后续步骤生效”,不能显示为当前请求已切换。
最小产品建议更保守:运行中把配置留作待应用,idle 后验证并 select,再允许下一次发送;避免与图像输入准入及 hosted engine 差异冲突。如支持即时配置,则按会话串行化并复核版本;不要通过 cancel 当前请求实现静默切换。更换 loop engine 的特殊迁移需求未在此次研究完全验证,v0.0.1 可限制为当前可用普通模型路由。
## 权限和项目隔离
独立 root session 并不自动继承当前用户聊天/调用 agent 的权限。DS Bot permissions.js:32–38 明确未设置时保留 DSH 默认;:25–28 通过 ctx.permissionPresets.set(agent.session,name) 设置 session;:17 使用 catalog() 读取 options/defaultPreset;:46 使用 resolve(name) 验证。Auto review 是 session-only,不能作为持久角色权限(:5–6,45)。这些调用是在 DS Bot 源码确认的使用契约,未完整审计 permission-presets 包内部授权实现。
v0.0.1 不替用户升权:不在 provisioning 时写 permission preset;在 UI 清楚展示宿主默认或会话实际权限。若将来允许修改,必须通过宿主正式人类授权入口而不是角色提示词或后台 set 绕过审批。workspace 的 canonical cwd 校验提供归属一致性,不构成安全沙箱;danger-full-access 会话仍可能跨项目读写。要承诺文件级隔离,需另行验证并采用宿主 sandbox/permission 机制。项目业务数据、角色映射、提示词均必须以 projectId/workspaceId/sessionId 校验访问。
## DS Bot 和历史代码能否单独复用
roster.js install(rt) 依赖 state/store、模型、权限、群组、parts、welcome/bootstrap、浏览器 grants 等;它在一个 team workspace 内构建 bot/room,不是独立 session provision 库。agents.js 是 DS Bot 自己的另一类“DSH Agent”记录管理器,依赖 rt.ensureWorkspace/save/index 等,只建普通聊天、并没有持久角色配置。两者不宜直接 import。
models.js 混合 llm 流重试、目录缓存、凭据状态、模型选择同步;:319–327 先 sessionController.selectModel 再恢复默认,仍然会写 profile,且存在异步保存竞争。不能原样复用。可借鉴目录呈现和同 session 序列化设计,但重新写几行独立 adapter。
prompt.js 最小可借鉴点仅 section 注册形式;其 promptFor 依赖 selfOf/botOf 和群组映射,角色正文含 DS Bot 产品语义,不适合直接 install。
历史 Git 233ee76:sansheng/src/provision.js 使用 ctx.get('dsbot-runtime',false)、rt.createBot + rt.createRoom,注释写明三 Bot + 项目群,且提示需要 ctx.provide 基线补丁。这是旧 DS Bot 集成方案,不满足十 root、无群 session、公开原生接口、不改宿主。只保留“项目记录/角色绑定/错误记录”的设计思路,不搬其创建与回滚代码。
## 最小交付建议
一个项目状态 schema(十角色固定枚举、sessionId、模型完整 tuple、instructions、版本、provision status)加一个薄 host adapter 即可。adapter 暴露 project(id)、session(id)、createSession、configureSession、models、onSystemPrompt。project(id) 只代理 workspaceRegistry.get;session(id) 用 resolveAgent;createSession 强校验计划 ID 回执;configureSession 走上文无 profile 路线;models 读 catalog;onSystemPrompt 返回 disposer。
不注册 DS Bot 插件、不引入其前端/浏览器/群、不给角色创建新角色/新会话的工具。UI 首次显式创建,重启仅恢复既有映射。测试用 fake ctx 验证严格十个 ID、创建中断恢复、returned ID mismatch、已存在有历史会话不重建、选择模型不调用 saveSelection、跨项目拒绝。真实宿主验证须另行获授权,本轮未执行。