# DeepSeek Harness 架构分析（Archify v3.2 流水线）

> 对 `deepseek-ai/deepseek-harness` 做与 `earendil-works/pi` 同规格的分析：**冻结 revision、逐条 path:line 证据、可校验图表**。
> 本文是分析结论；图表与回执在各子目录；面向读者的对比站点在 `../../harness-compare/`。

---

## 1. 方法与冻结面

| 项 | 值 |
|---|---|
| 仓库 | `https://github.com/deepseek-ai/deepseek-harness.git` |
| revision | `22ddee3792402c3e70ec5f86a63c3e3e895a2f60`（2026-10-23 19:48:59 +0800） |
| 克隆方式 | `git clone --depth 1`（分析不需要历史；对比用的历史在 pi 侧） |
| 仓库规模 | 19,188 个受版本管理文件、218 MB |
| 工具 | Archify v3.2（`bin/archify.mjs`)，`doctor` 全 `[ok]` |
| 门禁 | `validate` → `finalize --browser-check` → `visual-check --require-provenance`，三道全过 |

**证据纪律**：每个组件/参与者/断言都绑定 `path:line`，行号在写入前用 `sed -n "${l}p"` 逐条核对过（本次核出并修正 3 处：`docs/architecture.md` 的 7→11、96→81，`executor.ts:1` → `pipeline.ts:200`）。

---

## 2. 事实基线

**口径**：`.ts` / `.tsx`，排除 `*.test.*` / `*.spec.*` / `__tests__` / `fixtures` / `e2e`，不含 `node_modules`（下称「不含测试」）。

| 范围 | 行数 | 文件数 |
|---|---:|---:|
| `packages/` | **504,068** | 3,079 |
| `apps/` | 100,536 | 475 |
| `scripts/` | 45,252 | 189 |
| `packages/`（**含**测试口径） | 1,112,305 | 5,123 |

复现：`find packages -type f \( -name '*.ts' -o -name '*.tsx' \) ! -path '*/node_modules/*' ! -name '*.test.*' ! -name '*.spec.*' ! -path '*/__tests__/*' ! -path '*/fixtures/*' ! -path '*/e2e/*' -print0 | xargs -0 cat | wc -l`

主要单元（不含测试）：

| 单元 | 文件 | 行数 | 备注 |
|---|---:|---:|---|
| `packages/client` | 1,242 | 174,489 | Web 前端（React），最大单包 |
| `packages/experimental` | 590 | 73,185 | 实验性功能 |
| `apps/web` | 234 | 66,299 | Web 应用装配 |
| `scripts` | 189 | 45,252 | 构建/校验脚本 |
| `packages/api` | 123 | 24,381 | 网关与控制器 |
| `packages/extensions` | 42 | 23,964 | 内置扩展 |
| `packages/session` | 125 | 20,491 | 会话与投影 |
| `apps/desktop` | 153 | 17,926 | Electron |
| `packages/llm` | 90 | 16,490 | 含多个适配器包 |
| **`packages/core`** | **59** | **14,991** | 会话/工具/prompt/agent/循环/scope |
| `packages/boot` | 59 | 12,807 | profile 解析与挂载 |

包数量：`packages/*/*` **363 个（52 组）** + `apps/*` **5 个**（cli / desktop / desktop-host / web / plugin-market-generator）+ `native/system` + `python/sdk`。
文档量：**4,763 个 Markdown**（几乎每篇都有 `.zh.md` 与 `.i18n.yaml` 镜像）。

---

## 3. 架构判决

### 3.1 没有特权核心

`docs/architecture.md:11`：

> "There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads."

这不是修辞。插件的最小形态就是两个导出（`packages/mcp/mcp-client/src/index.ts:31-34`）：

```ts
export const name = 'mcp-client'
export const inject = ['tools']
```

MCP 客户端整个的接线就是 `inject` 一行——外部工具因此和内置工具走**同一道执行管线**，不存在「MCP 专用路径」。

### 3.2 产品形态是配置出来的

`docs/architecture.md:13` 起：一个运行中的 dsh 是**由有序层在 boot 时组合成的插件树**。

- **profile**（:17）：具名组合，出厂 5 个模板 `web` / `headless` / `sdk` / `sdk-minimal` / `acp`
- **bundle**（:19）：Cordis 配置行 + 代码的分发格式，插进去仍可被上层 patch 覆盖
- **patch**（:25）：按行 `id` 整块替换 config，层序为 profile bundles → `cordis.patch.yml` → home patch → `--patch`

`dsh --profile web --dump-config` 打印出的每一行都可被用户 patch 替换。HMR 也由 YAML 控制（`dsh-base` 开、headless/SDK/ACP 关）。

### 3.3 seam 三角色

seam = **Service Definition** + **Service Provider** + **Consumer**，只占一个角色不算 seam（`docs/architecture.md:134`）。

| seam | 定义锚点 |
|---|---|
| `ctx.llm` | `packages/llm/llm/src/index.ts:208`（`abstract class LlmAdapter`）、`:401`（`registerAdapter`） |
| `ctx.tools` | `packages/core/tools/src/index.ts:99`（`ToolsService`） |
| `ctx.sessions` | `packages/core/session/src/index.ts:525`（`Session`）、`:1064`（`SessionStore`） |
| `ctx.fs` | `packages/fs/fs/src/index.ts:87`（`abstract class FileSystem`） |
| `ctx.subprocess` | `packages/subprocess/subprocess/src/index.ts:117`（`abstract class SubprocessRuntime`） |
| `ctx.sandbox` | `packages/sandbox/sandbox-policy/src/index.ts:134`（`SandboxPolicyService`） |

**最重要的一条推论**：fs 与 subprocess 共享同一个执行世界，所以把文件系统指向远端沙箱时，Bash / PTY / LSP 会一起搬走，provider 无需分叉（`docs/architecture.md:137`）。

### 3.4 三个事件域

`docs/architecture.md:67`：

- **Session 事件**：持久事实，追加进日志并经 `session/event` 广播
- **Agent 事件** `agent/*`：携带活着的 `Agent`（inbox/step/status/request/validation/continuation）
- **Capability 事件** `fs/*` `tools/*` `telemetry/*`：给 seam 挂策略，不必 import 循环

waterfall（必须调 `next()`）与 serial（无 `next()`）是显式区分的：前者是 `agent/pre-step`、`agent/request`、`llm/stream`、`tools/*`，后者是 `agent/turn-stopping`。

---

## 4. turn 契约

定义在 `docs/architecture.md:81`：**step = 一次模型请求 + 它调用的工具；turn = 0 个或多个 step**。

关键顺序（与 pi 的最大实现差异）：**日志先行**。

- `turn/start` 通过 `session.append` 落盘（`packages/core/agent-loop/src/agent.ts:329`），不是内存状态
- `agent/pre-step` 是 waterfall，监听者可接受/改写/**拒绝**已认领消息；拒绝或首条被改写为空 → 该 turn 关闭且**没有 step**
- 工具调用过三道拦截：`tools/pre-execute` → `tools/execute` → `tools/post-execute`（`packages/core/tools/src/pipeline.ts:200` 发出 `pre-execute`）
- `assistant/message` 内嵌产生它的**紧凑带时序流**；`assistant/attempt` 保留失败/重试/取消但**不进模型历史**；落定前硬死 → 不留半条 attempt

### 硬规则

`docs/architecture.md:122`：

> "**Model-visible means logged.** Every model request must be reconstructable from the log. New model-visible inputs require session events."

推论：会话格式必须能演化。dsh 用**代际**解决——`session.jsonl[.zstd]`（v0）→ `session.vN.jsonl[.zstd]`，相邻两代恰好一个迁移包负责 `vN → vN+1`，已提交代际路径永不重命名/替换/删除。

---

## 5. 与 pi 的对照

### 5.1 规模：两种口径同向，内核差 5–7 倍

| | pi | dsh | 倍数 |
|---|---:|---:|---:|
| workspace 包数 | 11 | 363（52 组）+ 5 apps | 33× |
| `packages/` TS/TSX（**含**测试） | 419,908 | 1,112,305 | **2.65×** |
| `packages/` TS/TSX（**不含**测试） | 217,943 | 504,068 | **2.31×** |
| agent 内核（含测试） | `packages/agent` 6,929 / 16 文件 | `packages/core` 49,142 / 133 文件 | **7.09×** |
| agent 内核（不含测试） | 2,879 / 12 文件 | 14,991 / 59 文件 | **5.21×** |
| Markdown | 142 | 4,763 | **33.5×** |
| revision | `531340f`（2026-10-27） | `22ddee3`（2026-10-23） | — |

两种口径给出同一结论：总量差 **2.3–2.7×**，内核差 **5.2–7.1×**。
dsh 的体积不在循环里，花在 Web 前端（17.4 万行，不含测试）、实验区（7.3 万行）、脚本（4.5 万行）与文档（4,763 篇）上。

> 口径修正记录：本文件早期版本写「560,442 行 / 3,319 文件」「49 个包」「内核 14,650 / 55 文件」「1.33×」。
> 复核时发现这些数字来自混用的统计口径（且 pi 侧的 419,908 实际是**含测试**口径，而标签写的是「非测试」）。
> 上表已用同一条 `find` 命令对两侧重算，两种口径并列，均可复现。

### 5.2 一句话对照

| 维度 | pi | dsh |
|---|---|---|
| 控制权归谁 | 作者本人（删掉不需要的） | 平台方与第三方（替换每个能力） |
| 核心可换 | 否，改循环 = fork | 是，`ctx.agentLoop` 换实现 |
| 扩展模型 | 同进程 TS 扩展 | profile → bundle → patch + seam 三角色 |
| 上下文 | 静态短 prompt（<1000 token）+ 4 工具 | section 组装 + 工具 schema 准入 + `agent/pre-step` 闸门 |
| 会话 | JSONL 即真相，12 种 entry | append-only `SessionEvent` + 代际迁移链 + 投影 |
| 安全 | 明写 YOLO，不做权限系统 | `ctx.sandbox` + approval policy + `SAFETY.md` |
| 稳定承诺 | 为保工作流而稳定 | developer preview，明写破坏性变更 |
| star/生态 | 单作者工具 | 263,724 star，`awesome-dsh-plugin`、桌面端生态 |

### 5.3 一个不对称事实

dsh 把 **pi 的 pi-ai 当成自己的一个 LLM 适配器**：

`packages/llm/llm-pi-ai/package.json`
> "pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (**design-verification twin** of dsh-llm-deepseek)"

读作：pi 的模型层被吸收为插件树上的一个叶子，且被用作「验证 seam 抽象是否成立」的对照实现。反方向不成立——pi 的设计前提就是不引入别人的框架。

---

## 6. 代价与风险

| 复杂度 | 换来了什么 | 谁付账 |
|---|---|---|
| 插件树 + 作用域注册 + 可逆副作用 | 每一层都能从配置替换 | 要换循环/存储/执行世界的平台方 |
| profile/bundle/patch 三层 | 5 种出厂外壳靠配置组合 | 要分发插件、打包桌面端的人 |
| 会话代际 + 迁移链 | 格式能演进而不丢历史会话 | 把会话当长期资产的人 |
| 三事件域 + waterfall/serial | 策略挂在正确位置而非塞进工具 | 要企业策略/审计的人 |
| Web 17 万行 + Electron + Python SDK | 一份内核四种外壳 | 要 GUI/桌面/非 Node 调用方的人 |

**风险**：`README.md` 明写 developer preview 与 `THERE WILL BE COMPATIBILITY-BREAKING CHANGES`；理解门槛不在代码量，而在必须先接受 Cordis 范式（primer + arXiv 2608.25512）。

---

## 7. 已知盲区（本轮未覆盖）

1. **未做 `durable`/`chord` 式的子系统深挖**：`packages/client`（17.1 万行）内部结构、`packages/experimental` 的 6.7 万行均未展开。
2. **图表只覆盖主干**：架构图 14 组件、时序图 8 参与者 14 消息；`agent-team`、`goal`、`schedule`、`jobs`、`spill` 等 20+ 包未上图。
3. **未跑起来**：全部分析基于源码与文档，未 `pnpm install` / 未启动 `dsh web`；运行时行为（如 HMR 实际表现、插件卸载回滚）未经实测。
4. **未覆盖 Python SDK 与 native**：`python/sdk`、`native/system` 只做了目录级确认。
5. **star 数与生态为观测值**：2026-10-28 通过 GitHub API 取得，非仓库内事实。

---

## 8. 交付物

### 8.1 图表（本目录）

| 产物 | 规模 | 门禁 |
|---|---|---|
| `architecture-dsh-runtime-20261028-094225/dsh-runtime-architecture.html` | 14 组件 / 16 连接 / 5 卡片 / 2 边界 | validate 0 error 0 warning，finalize + browser-check pass，visual-check pass |
| `sequence-dsh-turn-20261028-094225/dsh-turn-sequence.html` | 8 参与者 / 14 消息 / 4 段 | 同上（viewBox 1080×680） |

**重跑记录（2026-10-28 10:23）**：架构图「代价」卡片里的规模数字原为「56 万行非测试 TS/TSX、49 个包、4,761 个 Markdown —— 是 pi 的 1.3 倍代码、100 倍文档」，复核发现口径混用。已改 `candidate.json` 后重跑
`finalize architecture candidate.json dsh-runtime-architecture.html --repo-root <dsh> --browser-check`，
四门禁 `validate:pass deliver:pass check:pass browser-check:pass`，产物字节数 866,741（几何与布局未变，仅卡片文字），
并已同步到 `learn/diagrams/architecture.html` 与 `../../harness-compare/diagrams/`（重新注入 `--archify-reader-width` 覆盖）。

> 重跑踩坑：首次 finalize 报 `viewer/evidence-path-conflict`，因为旧的 `.browser-check.json` 是「无主证据」不允许被覆盖。
> 先把旧证据文件移走再跑即通过。

### 8.2 对比站点（`../../harness-compare/`）

- `index.html` — 总览：一句话结论、基本盘数字、12 维度对比表、两张架构图、选型四问
- `dsh.html` — 读懂 dsh：插件树、turn 契约、seam 三角色、扩展点表、规模代价
- `compare.html` — 八项深挖：哲学、核心循环、上下文、工具、会话、安全、扩展、互操作

### 8.3 内嵌可读性实测（沿用「度量而非假设」标准）

栏宽 898px，测法：`svg 渲染宽 / viewBox 宽 × 图内最小框字号`。探针先在 pi 图上复现历史值（3.22 / 6.81 / 10.4 ≈ 记录的 3.2 / 6.7 / 10.3），再测 dsh：

| 图 | viewBox | 1× | 2× | 3× |
|---|---|---:|---:|---:|
| dsh 架构图 | 1510×698 | **3.73px** | **7.89px** | **12.05px** |
| dsh 时序图 | 1080×680 | **5.21px** | **11.03px** | **16.85px** |

结论：架构图 1× 不可读（<7px），**2× 才过可读线**；时序图 1× 勉强、2× 舒适。图侧仍注入 `--archify-reader-width:2900px !important` 以消除 Artifact JS 赋值竞态。
