pi × DeepSeek Harness 对比总览 读懂 dsh 逐项深挖 读书指南 故障与恢复 dsh 学习手册 pi 学习手册 dsh GitHub
00

一句话结论

这两个项目在解决同一个问题时,给出了相反方向的答案: pi 用「删到只剩一个循环」换取可预测性,dsh 用「万物皆插件」换取可替换性。 它们不是同一赛道上的两个竞品,而是两种关于谁该拥有控制权的立场。

πpi:把 harness 缩成你能读完的规模
单人维护、11 个包、4 个默认工具、system prompt 与工具定义合计不到 1000 token。 没有权限系统,没有内置 MCP(后来加了),没有插件树—— 「如果我不需要它,它就不会被造出来。」
Ddsh:把 harness 做成一个平台
DeepSeek 官方出品、363 个包、五种运行外壳(web / headless / sdk / sdk-minimal / acp)、 桌面端与 Python SDK。基于 Cordis 插件树, 「没有可打补丁的特权核心」——模型适配器、工具、日志、循环本身都是插件。
最反直觉的一条事实:dsh 里有一个包叫 @deepseek-ai/dsh-llm-pi-ai,它把 pi 的 pi-ai 当作自己的 LLM 适配器实现之一。 也就是说,两者不是替代关系——pi 的模型层被 dsh 吸收成了插件树上的一个叶子。 证据 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)”
01

基本盘:先把数字摆平

所有数字都在各自的仓库里用 wc -l 实测(排除 *.test.*/*.spec.*/__tests__/fixtures/e2e), 版本钉在两个固定 commit 上,可复现。

项piDeepSeek Harness (dsh)
维护者个人项目(Mario Zechner / earendil-works)DeepSeek AI 官方
冻结 revision531340f · 2026-10-2722ddee3 · 2026-10-23
包数量11363 个 packages/*/*(52 组)+ 5 个 apps/*
TS/TSX 行数(含测试)419,908 行1,112,305 行(2.65×)
TS/TSX 行数(不含测试)217,943 行504,068 行(2.31×)
最大单包(含测试)coding-agent 164,445 行client(Web 前端)363,080 行
核心循环规模(含测试)packages/agent 16 文件 / 6,929 行packages/core 133 文件 / 49,142 行(7.09×)
核心循环规模(不含测试)12 文件 / 2,879 行59 文件 / 14,991 行(5.21×)
Markdown 文件142 篇4,763 个(几乎每篇都有 .zh.md + .i18n.yaml)
仓库文件数约 1,02519,188
稳定度承诺接口稳定(作者为保住自己的工作流)developer preview,README 明写 «THERE WILL BE COMPATIBILITY-BREAKING CHANGES»
语言TypeScript + 自有 TUI 渲染引擎TypeScript + React Web 前端 + Electron + Python SDK

dsh 的 56 万行里有 17 万行是 Web 前端(packages/client)、6.7 万行 experimental、4.3 万行构建脚本。 若只比「agent 内核」,两者差距远小于总数给人的印象:6,929 行 vs 14,650 行,dsh 约 2.1 倍—— 多出来的部分主要花在插件生命周期、作用域注册与事件总线上。

02

12 个维度:同一个问题,两种答案

维度piDeepSeek Harness
架构范式 直接调用 + 依赖注入到构造参数。单一模型出口 streamFn,工具是唯一信任边界。 Cordis 插件树:服务、类型化事件、可逆副作用都注册在共享 ctx 上,卸载即回滚。
核心是否可替换 不可。循环写在 packages/agent 里,改它就得 fork。 可以。AgentLoop 是 ctx.agentLoop 的一个实现,profiles 里换一行配置即可。
扩展机制 同进程 TypeScript 扩展:pi.registerCommand() / 注册工具,与核心同权限。 三层:profile(组合)→ bundle(分发)→ patch(YAML 按行 id 覆盖),外加 seam 三角色。
上下文控制 极短静态 prompt(<1000 token),4 个默认工具。你能看见全部注入内容。 system-prompt 按 section 组装 + 工具 schema 准入;agent/pre-step 是 waterfall,监听者可改写或拒绝。
会话与持久化 JSONL 追加,一行一条 entry(12 种类型),id/parentId 组成树。 append-only SessionEvent 日志 + 格式代际迁移(session.vN.jsonl,每代一个迁移包)。
「什么算真相」 会话文件就是真相,UI 是它的渲染。 写进架构文档的硬规则:Model-visible means logged——每个模型请求必须能从日志重建。
界面接入 自带 TUI(自研差分渲染)+ print / json / rpc / SDK 五种出口。 Web 前端只消费 session/event 的投影;同一核心挂 Web、桌面、ACP、SDK 四种外壳。
安全模型 明写「full YOLO mode」,不做权限系统,安全交给容器/VM/沙箱。 内置 ctx.sandbox 后端 + approval policy(dsh-base 层),并单列 SAFETY.md。
MCP 最初明确不做,后来补上 packages/mcp,工具名 mcp__<server>__<tool>,仍受 --tools 过滤。 一等公民:mcp-client 插件声明 inject = ['tools'],把外部工具直接注入工具注册表。
多模型 packages/ai(8 万行)统一 4 种 API 协议,跨 provider 上下文交接是设计目标。 ctx.llm + LlmAdapter 注册表;官方适配器走 DeepSeek,同时提供 pi-ai 适配器做设计对照。
成败判据 作者能不能每天用它干活、且不被发版打断。 能不能让第三方在插件树上长出一个产品(已有 awesome-dsh-plugin 与桌面端生态)。
你的成本 一个下午能读完核心,改动要理解 4 个文件。 先读 Cordis primer 与一篇 arXiv 论文,改动要先想清楚「这属于哪个 seam」。
03

两张架构图:同一个视角下的两个世界

两张图用的是同一套流水线(Archify v3.2),同样钉死 revision、同样每个组件绑定 path:line 证据、同样通过 schema / 布局 / 浏览器渲染三重校验。 所以它们的差异不是画法差异,是架构差异。

pi 运行时架构 · 14 components / 15 connections / 4 cards 新窗口 ↗

读法:从左到右是主路径,向下是副作用。1× 只是缩略图——画布 1750px 挤进 898px 栏位,最小字号只剩 3.2px;点 2× / 3× 后在框内拖动,实测 3.2 → 6.8 → 10.4px。

dsh 运行时架构 · 14 components / 16 connections / 5 cards 新窗口 ↗

dsh 的画布窄一些(1510px),所以 1× 略好一点但依然不可读:3.7px; 2× / 3× 实测 3.7 → 7.9 → 12.1px,2× 即达到可读线(≥7px)。 注意图里那个 region 边界框的标签——它框住的是整个插件树,而不是「进程」。

04

怎么选:把问题换成三个提问

1你要「可预测」,还是「可替换」?
想让模型每次看到的东西都不变、能自己读完整个 harness、改动可控 → pi。
想让第三方能在你的 harness 上装插件、换模型层、接自己的 UI → dsh。
2你接受多大的「理解税」?
pi 的门槛是 4 个文件;dsh 的门槛是一套 DI 范式(Cordis)+ 一篇 arXiv 论文。 后者不是难,是贵——它要求你先接受一整套世界观,才看得懂第一行代码。
3你要单机自用,还是要分发?
dsh 有 bundle/patch 分发格式、插件市场生成器、桌面端打包、Python wheel, 这是「产品」的基础设施;pi 只有 npm 包与 pi install。
4稳定性能不能换功能?
dsh 明写会破坏兼容——它赌的是迭代速度;pi 的整个存在理由就是 「发版不要改变我的工作流」。这在选型上不是细节,是前提。
一句提醒:不要因为 dsh 有 26 万 star 就假设它更「正确」。 它们的代码量差 2.3–2.7 倍(两种口径),差一个半数量级的是文档(4,763 vs 142 篇)与生态; 而两者对「harness 应该有多大」这个问题的回答是相反的——这才是选型时唯一重要的分歧。

本章学习记录

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