仓库与包总览

这一层我们离开概念，进入真实代码。本章先建立目录地图与命名约定，让你知道任何一块功能住在哪。依据 packages/README.md、AGENTS.md、docs/architecture.md。

顶层布局

packages/ 的 group 划分

group 持有 packages/<group>/<pkg>/，包名保持 @deepseek-ai/dsh-<pkg>。按职责归类：

核心脊柱（stable API）

能力族（capability families，stable）

每个能力族通常是一个完整接缝（Service Definition + Provider + Consumer）：shell、terminal、subprocess、sandbox、fs、lsp、skill、compaction、context、subagent、jobs、workflow、web、attachment、spill、code-runtime、e2b。

运行时与数据平面

核心包与 ctx 键

整条 turn 流经这六个包，它们构成脊柱：

命名与产物约定

• 每个 npm 包是 @deepseek-ai/dsh-<name>；vendored 包 rescope 成 @deepseek-ai/cordis 等、private: true。@deepseek-ai/cordis 是每个 harness 包的 peerDependency（+dev）。
• 全 ESM（"type": "module"）。跨包用包名，本地相对导入用 .ts。
• 每个包有 src/types.ts（仅类型，无运行时代码）、./invariant（事件/数据关系检查或空安装器的理由）、README（含 Model Experience 与 Known Limitations）。

两个跨包类型模式

…Map → derived-union（声明合并扩展）

几乎所有可扩展的联合类型都用同一种模式：一个按键分判的 interface（…Map），用 keyof 派生联合。插件不改源包就能加变体：

interface ThingMap {
  'a': { kind: 'a'; /* … */ }
  'b': { kind: 'b'; /* … */ }
}
type ThingKind = keyof ThingMap          // 'a' | 'b'
type Thing = ThingMap[keyof ThingMap]    // 判别联合

// 别的插件扩展它，不动源包：
declare module '@deepseek-ai/dsh-llm' {
  interface ThingMap { 'c': { kind: 'c'; /* … */ } }
}

六个规范 map：ContentBlockMap、MessageSourceMap、FinishReasonMap（都在 dsh-llm）、TurnTriggerMap、TurnEndReasonMap、SessionEventMap（都在 dsh-session）。switch 联合类型时按 tag 走，别用 if 链——这样每个分支能收窄，写错 tag 编译就报错。

Branded IDs

跨包传递的 id 是带品牌的——结构上是 string，但类型层不可互换（一个 SessionId 塞不进要 CallId 的地方）。构造走每类型一个工厂；比较/日志/JSON 当普通 string。Branded<B> 在零依赖的 dsh-brand。

依赖图是生成的

完整的包依赖图见 docs/module-graph.md，由 pnpm run gen-module-graph 生成并在 CI 里做新鲜度门禁。扩展插件依赖 Service Definition，从不依赖具体 provider。