DeepSeek Harness 学习手册 第 09 / 11 章 总目录 单页全本 架构图 GitHub

手册/第 09 章

09

与 pi 的对照,以及一个不对称的事实

dsh 和 pi 常被放在一起讨论,因为它们对「harness 该有多大」给出了相反答案。 这一章把分歧落到数字和代码上,不靠印象。

规模:两种口径,结论同向

规模对比最容易被写错的地方是口径:算不含算测试、「包」怎么数、统计到哪一层。 下表把两种口径都列出来,左右两侧用**同一条 `find` 命令**跑出,可以自己复现。

指标pidsh倍数
workspace 包11363(52 组)+ 5 apps33×
packages/ 下 TS/TSX,含测试419,908 行1,112,305 行2.65×
packages/ 下 TS/TSX,不含测试217,943 行504,068 行2.31×
agent 内核(*/src,不含测试)packages/agent/src 6 文件 / 2,541 行packages/core/*/src 10 包 / 14,562 行5.73×
agent 内核(整包,含测试)16 文件 / 6,929 行133 文件 / 49,142 行7.09×
最大单包(含测试)coding-agent 164,445 行client(Web 前端)363,080 行2.21×
Markdown 篇数1424,76333.5×
revision531340f(2026-10-27)22ddee3(2026-10-23)—

复现命令:find <repo>/packages -type f \( -name '*.ts' -o -name '*.tsx' \) ! -path '*/node_modules/*' | xargs cat | wc -l; 不含测试再追加 ! -name '*.test.*' ! -name '*.spec.*' ! -path '*/__tests__/*' ! -path '*/fixtures/*' ! -path '*/e2e/*'。 包数取 packages/*/package.json(pi 扁平)与 packages/*/*/package.json(dsh 两层)。

读懂这张表的关键:几种口径给出同一个故事——总量差 2.3–2.7 倍, 内核差 5.7–7.1 倍。也就是说 dsh 的体积不在循环里,而在外围: Web 前端 17.4 万行、实验区 7.3 万行、脚本 4.5 万行(均不含测试)。

方向:一个往下删,一个往外长

pidsh
核心循环就是代码,12 个文件(不含测试)读得完class AgentLoop extends Service,可换实现
上下文静态短 prompt(<1000 token)+ 4 工具section 组装 + 工具 schema 准入 + agent/pre-step 闸门
工具一处五段管线三道 waterfall,任何插件可挂策略
会话JSONL + 12 种 entry,jq 可分析append-only 事件 + 投影 seam + 代际迁移链
安全明写 YOLO,不做权限系统ctx.sandbox + 审批策略,但明确不保证隔离
稳定承诺为保住工作流而稳定明写会破坏兼容
扩展成本一个 TS 文件一个 Cordis 插件 + 理解三层组合
失败模式想要的功能它没有能做的太多,不知道哪个在起作用

一个不对称的事实

这条在对比文章里几乎没人写,但它是 dsh 仓库里的一行依赖:

json · packages/llm/llm-pi-ai/package.json
"name": "@deepseek-ai/dsh-llm-pi-ai",
"version": "0.2.1-rc.3",
"description": "pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (design-verification twin of dsh-llm-deepseek)",
"dependencies": {
  "@earendil-works/pi-ai": "^1.3.0"
}

dsh 把 pi 的模型层当成自己的一个 LLM 适配器在用。这段 description 里的 「design-verification twin」值得逐字读:它是 dsh-llm-deepseek 的设计验证孪生体—— 用一个完全独立的实现(pi-ai)落在同一个 LlmAdapter 接口上, 来证明这层抽象是真的成立,而不是为某一家厂商量身定做。

Ⅰ说明 pi-ai 是可复用的
那套多协议适配层(4 种 API 协议、跨 provider 上下文交接)能作为组件塞进别人的架构, 而不是只能整体使用。
Ⅱ说明 seam 设计经得起对照
两个毫不相关的实现能落在同一个接口上——这是「seam 不是装饰」的最硬证据。

反方向不成立:pi 不会用 dsh 的任何东西,它的设计前提就是「不引入别人的框架」。 这条不对称,恰好就是两种哲学最纯粹的体现。

怎么选:四个问题

如果你的答案是选
我要能被一个人完全理解,发版后行为不变pi
我要在 harness 上长出一个产品,多种外壳共享内核dsh
我的会话要活过多次版本升级,还要被别的系统消费dsh(代际设计)
我不能接受破坏性变更,也不想要插件市场pi
一句提醒:不要因为 dsh 的 star 数高就假设它更「正确」。 两者的代码量差 2.3–2.7 倍,差 33 倍的是文档与生态。 它们的差别不是成熟度,是目标函数不同。

llm-pi-ai/package.json · 依赖 pi-ai llm/src/index.ts:208 · LlmAdapter README.md:13

本章学习记录

记录仅保存在当前浏览器。