deepseek-harness/missions/tasks/20260721-p1-rt-core/notes.md

rt-core 实现计划（connection + runtime + host 侧刀）

开工前档案（2026-07-21）。契约=api-contracts v3 §0.3/§3+§3.1/§4/§9.1/§9.2；等「T0 完成」广播后动 packages/。

0. 范围回述

1. connection：T0 把 web-runtime 的 wire 消费层 git mv 过来，接口零变化对账，导出清单附 v3 §3 尾；§3.1 纯度对账清单（见 §2）。不 import cordis（运行时值层面；类型 import type 允许）。
2. runtime：SlotsService / SessionsService（list store+scope 树+binding/ancestry/create）/ Session 两行加法 / scopeOf / ClientLoader（实现归我，boot 挂载归 ui-shell）。
3. host 侧刀：HostWebPluginRegistry（webserver 属地）+ GET /plugins/<id>/client.js + GET / 注入 DSH_BOOT；全新实现，不看其他 worktree。

1. connection 对账（预勘，T0 落地后按实际盘面修订）

1.1 迁入文件与导出面草稿（= 附到 v3 §3 尾的清单底稿）

文件	导出	处置
api.ts	类型 re-export（ApiProxy/SessionsApi/SessionSummary/HostApi/EventsApi/MuxFrame/HostFrame/ApprovalResponsePayload/QuestionResponsePayload/HistoryEntry/ToolEventView/ToolCallView/ToolResultView/Rpc* 族/IApiClient/SessionId/SessionEvent/ContentBlock/StreamChunk）+ 值导出 RpcId/AbstractApiClient + resultOf/transportError	原样
connection.ts	ConnectionController/ConnectionConfig/ConnectionSinks/ConnectionState	原样（契约文字写的 "connect/ConnectionHandle" 是旧稿措辞，现状实体即此四件，对账清单按实际写）
web-api-client.ts	WebApiClient	原样
fixture.ts	createFixtureApi/FixtureApiClient	原样
events.ts	WEB_EVENTS/WebEventName	原样（cordis 迁移的事件名锚点，零 cordis 运行时依赖）
intents.ts	不留在 connection：rpc-log 五 intent 随 D18 死；pingHost 死（面板供数）；refreshSessions/createSession 被 SessionsService 吸收。文件不迁入 connection 导出面	溶解
store.ts / rpc-log.ts / boot.ts	不属 connection（store 随迁 runtime 评估并入 sessions；rpc-log D18 删；boot 迁 runtime/kernel 改造）	—

注：ConnectionSlice（connection 状态可见性）原挂 zustand store；新去处=runtime 侧（connection 状态进 SessionsService 伴生 store 或 ctx.connection 挂载面），实现时定，不进 connection 包（connection 保持纯 wire 层）。

1.2 ctx.connection 服务（architecture §8）与「不 import cordis」的相容

connection 包源码（lib 面）零 cordis；其 client 半边（src/client/index.ts 的 apply）只用 import type { Context } + 运行时经 loader require 表拿实体，apply 内用 ctx.set('connection', handle) 挂载（不继承 cordis Service 类，避免值依赖）。若实现中发现必须要 Service 类，改从 require('cordis') 取（DI 表有 cordis 实体）。

2. §3.1 纯度对账清单（初稿；判据=换个消费面还需要吗）

盘点位置：packages/host/runtime/src/api-proxy.ts（存量全在此，apiproxy 包本体只有契约+fetch 胶水，干净）。

存量	位置	判决（v3 §3.1）	执行
agentFor（隐式 resume-on-prompt/history + in-flight 表去重 + assertServable 门）	api-proxy.ts:243	下沉 host 能力位	P-I 原样用；TODO(P-II)：下沉到 agents/host 能力层（如 ctx.agents.resolveOrResume），api-proxy 只留窄形胶水
summarizeCold（cold 列表合并 + mtime 兜底）	api-proxy.ts:123	下沉 host 能力位	P-I 原样用；TODO(P-II)：归 persistence/sessions 能力层
paginate（消息边界分页，sourceEventSeqs 组界）	api-proxy.ts:31	留（wire 契约的读投影）	不动
viewFor / backscanArgs（ToolEventView 呈现计算，含 events.mux 内 openCalls 配对表）	api-proxy.ts:167/195 + mux 流内表	P-I 随 toolviews 迁移整体删除（呈现归 client）	⚠涉 wire 面：HistoryEntry.view / session-event 帧 view 字段 / ToolEventView 类型族都要随删——wire 契约定义面=三不改，此刀需 main 协调排期（toolviews 真实现落地=触发点）；client 侧我这边的 api.ts re-export（ToolEventView/ToolCallView/ToolResultView）搬家时先保零变化，wire 面删时同步删
history 隐式 resume（看历史拉起 agent）	agentFor 被 history 调用	可议项，P-I 不改：应改纯持久化读（cold 历史不该实例化 agent；隐式 resume 只该留给 prompt）	记清单待 P-II 裁决

语义边界重申：隐式 resume 保留（cold→live 是 host 内政）；永不隐式 create。

3. runtime 设计

3.1 SlotsService（小件）

class SlotsService extends Service（provide='slots'，cordis 真 Service），内持 new SlotCore()（ui-slots），构造时 core.onMutate(k => this.ctx.emit('slots/changed', k))；define/register/entries/spec/subscribe/getVersion 纯代理。declare merge Events['slots/changed'] + Context.slots。T0 后先对桩编码，T1 ui-slots 真实现落库换真。

3.2 SessionsService + scope 树

• manager: SessionManager 现有类原样迁入（runtime/src/sessions/）。
• list: SnapshotStore<SessionListState>（{ids, byId}）：createSnapshotStore（web-react），数据源=订 manager（list RPC 快照+host 流增量已在 manager 内闭环，重连重拉=handleConnected 现有路径），manager 通知 → 映射进 store.update。title 字段 wire 无供数：P-I 派生占位（cwd basename 或 id 短形），记台账。
• create(opts) → manager.create(cwd)。
• ancestry(id)：list store 内沿 parentId 回溯，含自身，根在前；断链（父不在表）即止。
• scope 树（dsh-scope mintScope 模式客户端照搬，不 import 服务端包）：ctx.plugin(noop) 得 Fiber + fiber.ctx.extend({[kScope]: id})；scopeOf(ctx) 读 symbol。
  • 惰性建：首次 scope(id)/binding(id) 解析时建；实例表 Map<SessionId, {fiber, ctx, binding}>。
  • frozen 保留：host 死（running 停/host/session-removed 未到）≠ scope 死。
  • removed 拆：list 增量出 removed 且无人观看才 fiber.dispose。观看侦测方案（runtime 不认识 layout，不能读选中态）：记「最近一次 binding(id) 解析的 id」为在看者；removed 时若非在看者→立拆；是在看者→挂起，等下一次 binding(其他 id) 解析时补拆。SessionProvider key={id} 重挂语义保证切走必有新解析，故不漏。此方案零新增 API，作为 P-I 实现口径写进 JSDoc。
• binding(id)：恒等引用缓存 {sessionId, session: {useSelector}, ctx: scopedCtx}；session 实例=manager.get(id)（常驻，天然恒等）。

3.3 Session 两行加法

implements ObservableSnapshot<ConversationSnapshot>（subscribe/getSnapshot 本就同形）+ 构造尾 readonly useSelector = bindSnapshotSelector(this)。其余核心逻辑零触碰（三不改）。

3.4 ClientLoader（最大新件；代码家=runtime，实例=web 壳静态持有）

消费面拆两半：壳静态 import（runtime 包常规入口导出 createClientLoader(deps)，vite 打进壳）；runtime 自身的 client bundle（dist/client.js）只含 slots/sessions apply，不含 loader 机件。

createClientLoader({ ctx, modules: seedTable, boot: window.__DSH_BOOT__ })
  ├ DSHClientProxy 单槽 handoff：window.DSHClientProxy = { loadPlugin(def) }
  │   pending: Map<id, resolve>；loadPlugin 按 def.id 对号入座；查无此 id=fail loud
  ├ start()：读 boot.plugins；分组 immediately / rest
  │   immediately 组：全组并行注 <script>（fetch 并行天然成立——script 执行只是把
  │   factory 存进 pending，apply 时机由 loader 控），组内按 inject 拓扑序逐个
  │   factory(require)→ctx.plugin(apply)→导出面登记模块表；全组就位（屏障）
  │   → rest 按 inject 拓扑逐个 load（依赖就绪即装，不整体串行）
  ├ load(id)：注 script → 等 handoff → factory(require) → ctx.plugin(exports.apply)
  │   → modules.set(包名, exports)（后装者 require 先装者）→ style 归属登记
  │   （bundle 执行时自注 <style data-plugin="<id>">，loader 按属性收账备 unload）
  ├ require(spec)：查模块表；查无=throw 明确报「<id> 缺依赖 <spec>」
  ├ unload(id)：P-I throw not-implemented
  ├ settled()：全清单 active 后 resolve；任一 failed → reject（AppRoot loading 页 fail loud）
  └ status: SnapshotStore<Record<id, 'loading'|'active'|'failed'>>

• 拓扑排序：inject 引用不在清单内=fail loud；环=fail loud。
• 模块表种子（壳递入）：react/react-dom/cordis/ui-slots/web-react/ui-primitives。
• 双模式验收：真 bundle（tsdown 产物过一遍）+ fixture 注入（手造 DSH_BOOT + 假 bundle 脚本）。
• 与 ui-shell 对界：deps 形状（ctx、种子表、boot 对象）+「AppRoot await settled()」；对象由我定义类型导出，壳只管构造与挂 ctx.loader。

4. host 侧刀设计

4.1 Loader 订阅方案（vendor/loader 实勘结论）

vendor/loader（@cordisjs/plugin-loader）事件面：loader/entry-init（Entry 构造期，早于 import/apply）、loader/partial-dispose（option-diff/组禁用拆除）、loader/config-update；cordis 核心另有 internal/plugin（Fiber 创建与销毁各发一次；loader 自己的 handler 会把 fiber.entry 连上）、internal/status（状态迁移）。没有「加载完成」单事件 → 采用契约预设的兜底：registry 遍历 + update 事件重扫——初扫 ctx.loader.entries()（entry.options.name=包名 specifier，entry.fiber!==undefined=已加载），订 internal/plugin（微任务去抖）触发全量重扫重建表。八条量级，重扫零成本；P-I 装/卸=重启生效，订阅只是保表新鲜的廉价保险。

4.2 装配缺口（要报 main 的对界问题）

现 dsh web 链=apps/cli/web.ts → startHost → bootHost：纯 ctx.plugin 编程式装配，无 Loader 实例，而契约 §0.3 说「host cordis.yml 全列八包」+ registry 订 host Loader。最小闭合方案（我拟实施）：host/runtime 装配层加一步 web 插件装载（挂 @cordisjs/plugin-loader + loader.create({name}) × 八包，内存树），骨干 spine 保持编程式；cordis.yml 文件形态后置。备选=web 形态整体改 Loader boot（动静大，非我属地）。待 main 拍板：①内存 Loader 树是否满足「config 同源」P-I 口径；②apps/cli/web.ts 的接线改动（构造 registry 递给 webserver）按跨属地报备处理。

4.3 HostWebPluginRegistry（webserver 包内，类归属地、实例归装配）

• new HostWebPluginRegistry(ctx)（cordis 仅 import type；订阅走传入对象方法，webserver 保零 workspace 依赖）。
• 表构建：遍历 entries → 对每个已加载 entry 解析 <name>/package.json（createRequire 以 loader baseUrl/进程根为锚）→ 有 dshClient 且 platform==='web' → 入表 {id=包名, inject, immediately?, clientPath}；clientPath=解析 exports["./client"]（string 或 {default} 条件形都接）为绝对路径。无 dshClient=跳过（非 web 插件）；有声明但 exports 缺 "./client"=fail loud（误配置早爆）。
• 消费面：snapshot(): { plugins: BootPluginEntry[] }（生成 DSH_BOOT）+ clientPath(id): string | undefined（分发端点）。声明式，无 serve() 调用面。

4.4 webserver 两端点

• GET /plugins/<id>/client.js：id 含 scope 斜杠（@deepseek-ai/dsh-client-xxx），路由取 /plugins/ 与 /client.js 之间整段 decode；查表 → readFile(clientPath)，content-type js；查无=404。
• GET /（含 SPA fallback 出 index.html 的路径）：读 index.html 后注入 <script>window.__DSH_BOOT__={...}</script>（JSON 序列化时 < 转义 < 防 </script> 截断）。
• startWebServer options 增可选 webPlugins?: { snapshot(); clientPath(id) } 形注入（不传=行为不变，现有测试零扰动）。

4.5 e2e 验收

真 host 起服 → GET / 断言 DSH_BOOT 八包清单与 immediately 标志；GET /plugins/<id>/client.js 断言 200+js；未知 id 404。fixture 侧同协议注入由 loader 测试盖。

5. 实现顺序（T0 后）

1. connection 对账刀：导出清单实测（tsc 盘面）→ 附 v3 §3 尾 + 本文件 §2 清单定稿。
2. host 侧刀（不依赖 client 桩，可先行）：registry → 端点 → 注入 → 装配接线 → e2e。
3. runtime 服务：SlotsService（对桩）→ Session 两行 → SessionsService+scope 树 → 存量 spec 从 attic 捞回平移绿（connection/session/manager/notifier/partial/fold/lineage/fixture 族；boot-intents/preinit/rpc-log 退役记档）。
4. ClientLoader：核心态机+拓扑 → fixture 注入测试 → 真 bundle 冒烟（等 T0 tsdown preset 产物）→ 与 ui-shell 对接 deps 形状。

6. 台账 / 开问 main

• [问 main] §4.2 装配缺口两问（内存 Loader 树口径 + apps/cli/web.ts 跨属地接线报备）。
• [问 main] Context.sessions merge 冲突：v3 §4 的 client sessions: SessionsService 与 host dsh-session sessions: SessionStore 同名 merge 相撞（connection→apiproxy 类型链拉入 host d.ts）=TS2717。建议 a) client 侧改名；备选 c) P-I ctx.get('sessions')（现状实现，FIXME 在 runtime/src/index.ts）。
• [台账] SessionSummary.title wire 无供数，P-I 客户端派生占位。
• [台账] viewFor/backscanArgs 删除刀涉 wire 面，等 toolviews 迁移触发、main 排期。
• [台账] history 隐式 resume 改纯持久化读，P-II 议。
• [台账] scope「无人观看」= 最近解析 binding 者近似，口径写 JSDoc。
• [台账] intents.ts 溶解（rpc-log 五件+pingHost 死；refresh/create 归 SessionsService）。
• [规矩→全员] client 半边 bundle 要用 ctx. 必须 export const inject=[...]——loader 以 object-plugin 整面递 cordis，fiber 依赖检查生效（apply-only 丢 inject=postmortem 0001 同型）。
• [规矩→全员] dist/client.js 是 build 产物不进 git；改 client/ 源码后必须重跑 tsdown，否则 loader e2e 吃旧产物。

7. 进度（冷启动锚点）

刀	commit	状态
connection 对账（index 精确清单+intents 溶解+v3 §3.2 附录）	3102c99a4+b4ce5c137	✅
host 侧刀属地半（registry+分发端点+DSH_BOOT 注入+11 测）	ba9768e90	✅
spec 平移（connection 3+runtime 6+api-helpers 拆分）	dd8b37809	✅
runtime 服务（SlotsService/SessionsService+scope 树/Session 两行/scopeOf/invariant×2）	e2ea1b99b	✅
ClientLoader（handoff/DI require/immediately 屏障/双模式验收/./loader 子路径）	be0261eb5+f94085878	✅
双入口拆分吸收（connection/runtime client 半边 apply+tsdown noExternal+双 specifier 回登记）	a05e28b5c	✅
host 装配刀（mountWebPlugins 内存 Loader 树×八包+invariant 伴生+built e2e）	93b954c4d	✅
apps/cli/web.ts 接线（跨属地备案单独成刀）	e4661e7b0	✅
装配真链修缮（baseUrl 锚/tsdown preset lib 半/strip-only 内联/trajectory 空 apply）	9c6f41c47	✅

真链验收实录（2026-07-22 02:26，apps/cli 语境 plain node）：mountWebPlugins→registry→startWebServer 起服→GET / 出 DSH_BOOT（plugins=8，immediately=4，序=connection,runtime,ui-theme,i18n,ui-layout,ui-sidebar,ui-conversation,ui-trajectory）→GET /plugins/@deepseek-ai/dsh-client-runtime/client.js 200 且含 DSHClientProxy.loadPlugin→未知 id 404。web-plugins.e2e 2/2 绿（lib 未构建自跳）。

排坑记录（后人别再踩）：①Loader 裸名 import 需 ctx.baseUrl 锚，否则静默失败全员 fiber-less；②包级 tsdown.config.ts 会整体替换根 workspace 形状——clientBundle preset 必须双 config（lib 半+client 半）；③apiproxy 浏览器子路径与 dsh-session/surface 的 runtime default 指 src/*.ts，plain-node 消费必须内联（strip-only 模式炸 parameter property）；④ctx.loader 每次访问是新 traced proxy，不可做恒等断言。