11 KiB
三省六部 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 返回空字符串。插件卸载时释放注册。
模型配置最小路线
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、跨项目拒绝。真实宿主验证须另行获授权,本轮未执行。