deepseek-harness/missions/tasks/20260721-1520-web-plugin-rfc/clientcontext-audit.md

tsconfig host/client 拆分实施细案（fw-react 起草 2026-07-22；只方案不实施）

终态修订（2026-07-22 收敛刀）：用户裁定不设 tsconfig.host.json——根 tsconfig.json 恢复 host 聚合原职（含 exclude packages/client），新增文件只有 tsconfig.client.json；typecheck=tsc -b tsconfig.json tsconfig.client.json；verify-cordis-config 双聚合并列种子。下文 §1 的 host.json/根壳化描述为拆分期中间形态，已被此终态取代；其余结论（A 类切断/归属表/刀序）不变。

背景：client 与 host 对 cordis Context 的 declare merge 撞名（sessions：SessionStore vs SessionsService；loader：vendor Loader vs ClientLoader）。用户已拍板多 tsconfig 拆分方向；v3 §4.0 ClientContext 裁决作废待删。本文=可执行细案，执行者按刀序照做。 现状确诊（盘上核实）：撞名发生在两层——①根聚合 program（tsconfig.json 的 include 把全仓 tests 聚成单 program，127 个 references 的 d.ts 同室，llm-retry/app-boot 两处红即此）；②client leaf program 内部也撞（packages/client/runtime/src/index.ts:48 FIXME 实证：runtime 自己的 sessions: SessionsService merge 与经 connection→dsh-session index d.ts 链进来的 host merge 同 program）。拆聚合只治①；②必须切类型链（见 §4）。

1. 拆分后 tsconfig 文件清单

1.1 文件表

文件	性质	内容
tsconfig.base.json	不动	paths/编译选项唯一源（两侧共用）
tsconfig.host.json	新增（= 现 tsconfig.json 改名收缩）	noEmit 聚合：include=现 root include 全部 + "exclude": ["packages/client/**"]；references=现 127 条减去 12 条 packages/client/（vendor/cordis 等保留——host 本来就用）
tsconfig.client.json	新增	noEmit 聚合：include=packages/client/*/tests/**/*.ts + **/*.tsx；compilerOptions 加 "jsx": "react-jsx"、lib 加 DOM；references=12 条 packages/client/*（传递闭包由各包自身 tsconfig references 供给，聚合不重复列 host leaf）
tsconfig.json	保留为纯壳	{ "extends": "./tsconfig.base.json", "files": [], "references": [{host},{client}] }——编辑器/工具的目录锚点；不再有 include（单 program 聚合就此消灭）
tsconfig.vitest.json	改 extends	见 §3
tsconfig.build.json	不动	build 走各 leaf 项目自身 program，与聚合无关（但受 §4 A 类切断的益处：client leaf 不再见 host merge）

要点：

• 12 条 client references 名单（从现 tsconfig.json 平移）：ui-slots/ui-primitives/web-react/connection/runtime/ui-layout/ui-sidebar/ui-conversation/ui-trajectory/ui-theme/i18n/web。
• client 聚合不列 vendor/cordis、host leaf（llm/session/tools/brand/apiproxy/user-approval/user-interaction/invariants）——tsc -b 自动沿各包 references 建传递闭包；聚合只列直接被 include 文件 import 的项目根。若 client specs 直接 import 'cordis'（web-react specs 不用，ui-* client specs 会），再补 vendor/cordis 一条即可，执行时以报错为准。
• client 聚合首次纳管 .tsx specs（现 root include 只到 .ts，全部 tsx spec 至今零 tsc 检查）——预期首跑翻出存量 tsx 类型错，属还债，修在同刀。
• 编辑器行为不回退：VS Code 对 tests 文件本就取最近包级 tsconfig（不含 tests），现状=inferred project，拆后相同。

1.2 typecheck 两跑接线

// package.json
"typecheck": "tsc -b tsconfig.host.json tsconfig.client.json"

• tsc -b 原生支持多入口，两入口各成独立 build graph（共享 leaf 的 .tsbuildinfo，重复 leaf 只 build 一次）；一条命令仍是一个 pnpm script。
• scripts/run-gates.ts 零改动：所有 pnpmScript('typecheck', 'typecheck') 调用点（ci-primary/node-compat/pre-push）走 pnpm script 间接层，脚本名不变即全链生效。
• clean:build 的 *.tsbuildinfo glob 已覆盖新聚合的增量文件，不用动。

2. 横跨面归属判定表

判定依据三条（按序适用）：A=运行宿主（node→host / 浏览器→client）；B=类型链是否需要见 client declare merge（需要→client）；C=tests 归其 src 所在侧。

范围	归属	依据
packages/client/* 12 包（src 经 references，tests 经 include）	client	A+B
vendor/*（cordis/cosmokit/schemastery…）	两侧闭包共享 leaf，tests（如有）归 host	cordis 是双方 peer；leaf project 单 build 无冲突（cordis 自身不 merge sessions/loader）
packages/host/apiproxy	双侧闭包共享 leaf；tests 归 host	协议同构测试跑 node（InProcessApiClient）；client 只经 /api、/client 两子路径吃类型
packages/host/runtime、host/webserver	host	A（node 载体）
packages/hooks/*	host	A（Claude/Codex hook 桥全是 node 进程件）
packages/ui/*（acp/tui/jsonrpc/app-boot/commands/permission/tool-ask-user）	host	A（node 侧 UI 桥；「ui」前缀勿与 client/ui-* 混淆）
packages/ui/user-approval、user-interaction	双侧闭包共享 leaf（apiproxy api 引其 id/answer 类型）；tests 归 host	B（§4 切断后 client 只见其 /types）
packages/core/session、llm/llm、core/tools、util/brand	双侧闭包共享 leaf；tests 归 host	同上（wire 词汇表供方）
packages/support/*（invariants/testkit/llm-replay/acp-snapshot/loader-smoke）	host；invariants 兼双侧闭包 leaf	client 各包 src/invariant.ts import dsh-invariants（其 cordis merge key 不撞 client，容忍，见 §4 C 类）
packages/web/*（web-search 能力座——≠ packages/client/web，命名雷区）	host	A
其余全部 packages/*（core/bash/fs/lsp/skill/compact/context/subagent/workflow/todo/guard/cordis/session-persistence/sdk/examples…）	host	A
examples/*（根目录 cordis.yml leaves）	host	A（node 启动）
apps/cli	host	对 client 的唯一触点是 require.resolve('@deepseek-ai/dsh-client-web/dist/index.html')（apps/cli/src/web.ts:33）——运行时资产路径，非类型依赖；执行时核实 apps/cli 是否本就在根 graph 内（现 references 未见其条目），不在则维持现状
scripts/、website/	host	A（node 工具与站点构建；verify-client-closure 等脚本读 client 包是当数据读，非 import）

无「双跑」条目：所有共享包都是 leaf project 单 build、两聚合各自引用，不存在同一 tests 进两个 program 的情形。

3. tsconfig.vitest.json 拆不拆：不拆，改挂靠

结论：不拆。该文件只是 vite-tsconfig-paths 的路径映射范围（文件头注释自证「never a tsc -b target」），vitest 只转译不 typecheck——specs 的类型隔离由 §1 两聚合负责，不由 vitest 面负责；运行时不存在 declare merge 冲突问题。

唯一必要改动：现 "extends": "./tsconfig.json" 在根壳化（files:[] 无 include）后仍能继承 paths（paths 住 base，经 extends 链传递），但为了不依赖壳的形态，直接改 "extends": "./tsconfig.base.json"，include 原样保留。验收：pnpm exec vitest run packages/client/web-react/tests/store.spec.ts（映射面探针）照过。

4. A 类残余：拆聚合后 client program 仍见 host declare 的链路与最小切断点

4.1 确诊链路

TS 规则：import 某模块即装载其文件级 module augmentation。client 侧现存两条进水管：

① connection/src/api.ts ──→ '@deepseek-ai/dsh-session' index ──→ declare module 'cordis' { sessions: SessionStore }   ★撞 runtime 的 SessionsService
② connection ──→ '@deepseek-ai/dsh-host-apiproxy/{api,client}' ──→ apiproxy 内部 import session/llm/user-approval/user-interaction 的 index ──→ 同上循环

loader 撞名无 A 类残余：client 侧零 import @cordisjs/plugin-loader（执行时 grep 复核），拆聚合即断根。 C 类（容忍不切）：dsh-invariants、dsh-llm/dsh-tools 等的 cordis merge key（invariants/llm/tools）不与 client key 撞——是类型宇宙污染但不报错；浏览器产物纯度另由 verify-client-closure 把守，本案不扩大。

4.2 最小切断点（精确到文件+行；原则=新增类型子路径出口，绕开 index 的 augmentation 装载）

新增出口四件（各包 package.json exports + tsconfig.base.json paths 各一条）。闭包纯度已盘上复核：三份 types/presentation 文件自身零 augmentation；但 session/src/types.ts:2 与 tools/src/presentation.ts:8 都 import '@deepseek-ai/dsh-llm' 主入口——llm index 的 merge key=llm 属 C 类不撞，A 类切断不受影响；将来要清 C 类时改这两行指 llm/types 即可（本案不做）。plugin-loader 已复核 client src 零 import，loader 撞名拆聚合即断根（§4.1 结论盘上证实）：

包	新子路径	指向	供出类型
dsh-session	./types	src/types.ts（已存在）	SessionId、SessionEvent 族
dsh-llm	./types	src/types.ts（已存在）	ContentBlock、StreamChunk、CallId
dsh-tools	./presentation	src/presentation.ts（已存在）	ToolCallView、ToolResultView
dsh-user-approval / dsh-user-interaction	./types	新建 src/types.ts（现纯类型窝在 index.ts，先抽出、index 再 re-export——两包仅 index+invariant，抽取量小）	ApprovalRequestId/ApprovalOutcome；AskUserQuestionItem/AskUserQuestionAnswer

改写点清单（import specifier 机械替换，逻辑零改）：

client 侧：

• packages/client/connection/src/api.ts:12（dsh-tools→/presentation）、:20（dsh-session→/types）、:21（dsh-llm→/types）
• packages/client/connection/src/fixture.ts:8（llm）、:9（session）
• packages/client/runtime/src/sessions/：conversation.ts:6、partial.ts:5、session.ts:6-7、fold-adapter.ts:6（执行时以 grep -rn "'@deepseek-ai/dsh-\(session\|llm\|tools\)'" packages/client/{connection,runtime}/src 取全量，防列漏）

apiproxy 内部（②管的根治点）：

• src/api/rpc.ts:11、events.ts:9-12、approvals.ts:8-9、approvals.schema.ts:8、sessions.ts:7-8、sessions.schema.ts:9、questions.ts:8、questions.schema.ts:8、events.schema.ts:8（同样以 grep 取全量）

augmentation 靶点保持不动：apiproxy src/api/sessions.ts:12 的 declare module '@deepseek-ai/dsh-llm'（ContentBlockMap 扩块）继续指向主入口不改——它是 host program 的合法 merge，client program 不装载该文件即不受影响；执行时以 host 聚合绿+client 聚合绿双验。

验收探针（④专属）：切断后在 client 聚合跑一个负样本文件（临时 spec：const s: import('cordis').Context['sessions'] = null as never 的类型应解析为 SessionsService 而非 union/error），加 grep -rn "from '@deepseek-ai/dsh-session'" packages/client --include='*.ts' 应零命中（/types 除外）。

5. 执行刀序（每刀独立绿、可停可续）

刀	内容	验收命令
刀1	四件类型子路径出口（session/llm/tools 加 exports+paths；user-approval/user-interaction 抽 types.ts+出口）。纯加法	pnpm run typecheck（现单 program 仍绿）+ pnpm run build（exports 面有效）
刀2	apiproxy 内部 9 处 import 切 /types（②管根治）	pnpm run typecheck + pnpm exec vitest run packages/host/apiproxy
刀3	client 侧 connection/runtime 全量 import 切换（§4.2 清单+grep 兜底）	pnpm exec tsc -b packages/client/runtime packages/client/connection + 该两包 vitest
刀4	client/runtime 复原契约 merge：删 index.ts:48 FIXME、sessions: SessionsService 落 declare（rt-core 属地，由 rt-core 执行，本刀序仅排位）	pnpm exec tsc -b packages/client/runtime 绿（此刻 host merge 已不可见）
刀5	两聚合落地：新增 tsconfig.host.json/tsconfig.client.json、根壳化 tsconfig.json、package.json typecheck 两跑、tsconfig.vitest.json 改 extends	pnpm run typecheck（两 program 各绿）+ llm-retry/app-boot 红消失复核 + vitest 映射探针
刀6	tsx specs 还债（刀5 首跑翻出的存量 tsx 类型错，按包分派属地 owner 修）	pnpm exec tsc -b tsconfig.client.json 绿
刀7	文档收尾：v3 §4.0 ClientContext 裁决删除+architecture §2 分层表补两聚合一行（main 属地，契约文档只有 main 可改）	pnpm run doc-sync（免门禁期可缓）

刀1-3 与刀5 可并行推进后合流（1-3 不动聚合、5 不动包内 import），但刀4 必须在 3 之后、刀5 的 client 聚合绿依赖 3+4 齐。风险位：①types.ts 闭包不纯（暗 import index）→ 执行刀1 时 grep 即知，若不纯先做同包内类型下沉小刀；②tsx 还债量未知 → 刀6 独立成刀就是为了不阻塞主链。

—— 以上。执行前待 main 审：§2 归属表（尤其 apps/cli 维持现状项）、§5 刀4 的 rt-core 排程。