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

对比/逐项深挖

01

哲学:删掉,还是长出来

πpi:先假设「不需要」
"My philosophy in all of this was: if I don't need it, it won't be built. And I don't need a lot of things."
如果我不需要它,它就不会被造出来。而我不需要的东西很多。
目标是把自己从「飞船式工具」里解放出来:功能膨胀、接口每次发版都变、渲染会闪。
Ddsh:先假设「都会被替换」
"There is no privileged core to patch: you extend dsh by mounting a plugin beside the others."
没有可打补丁的特权核心:你通过在同一层旁边再挂一个插件来扩展 dsh。
目标是让第三方能在上面长出产品:插件、桌面端、SDK、发行版。

这不是「极简 vs 复杂」的品味之争。pi 的哲学来自一个人对自己工作流的观察; dsh 的哲学来自一个组织对生态的判断。前者把不确定性消灭在源头(少做), 后者把不确定性转移给组合层(可换)。两者都自洽,但要求的信任方向相反: pi 要你信任作者删得对,dsh 要你信任框架组合得对。

想确认 pi 这边的「少做」是怎么自我论证的,可以直接读官方博客的 16 篇原文—— 我们按主题做了摘要,并把可验证的技术断言逐条回仓库核对: pi 手册 · 第 12 章「作者自述:16 篇博客」。

02

核心循环:代码,还是配置

pidsh
循环在哪packages/agent(8 文件 / 6,929 行)——就是代码packages/core/agent-loop,注册为 ctx.agentLoop 的一个实现(class AgentLoop extends Service,index.ts:291)
能换吗不能。改循环 = fork 仓库能。web/headless/sdk 都是「组合」,换一行配置即换驱动器
状态在哪循环持有状态,事件流向外发状态是日志的投影:AgentRegistry 持有 turn/step 状态并暴露 turnBoundaryOf(session)
好处读得完、改得动、行为可预测同一核心挂四种外壳,商用产品与 SDK 共享一份逻辑
代价任何新形态都要改核心读循环前先理解 Cordis 范式与 scope/isolate 语义
判断依据:如果你的 harness 只需要服务一种入口,pi 的结构更优——它把「组合」这件事的成本降到了零。 如果你需要 Web + 桌面 + CLI + SDK + ACP 五种入口共享一份内核,dsh 的抽象才有回报。
03

上下文:短到能背下来,还是有闸门

πpi:把 prompt 压到 <1000 token
system prompt 与工具定义合计不到 1000 token;4 个默认工具。 system-prompt.ts 用 buildSystemPromptSections 把内容拆成 preamble/tools/rules/docs/project_context/skills/addendum。 目标:你能看见模型看到的每一样东西。
Ddsh:组装 + 准入闸门
SystemPrompt(core/system-prompt/src/index.ts:434)按 section 组装, 工具 schema 要「被 step 准入」才进入请求; agent/pre-step 是 waterfall,监听者可以接受、改写或拒绝已认领的消息。 目标:让策略能在请求发出前动手。

pi 的记录是「我注入的少」,dsh 的记录是「谁在哪一步可以改注入」。 前者靠克制,后者靠可审计的拦截点。有意思的是两者共享同一个前提—— 都认为「背后偷偷注入上下文」是 harness 的头号恶习,只是防法不同。

一个诚实的补充:dsh 的插件树意味着上下文来源可能是你不认识的插件。 它有 request/context 这样的日志事件让来源可追溯,但「可追溯」不等于「可预期」。 pi 在这个维度上赢在结构简单,不是赢在实现更好。
04

工具:一道边界,还是三道闸

pidsh
管线prepare → validate → beforeToolCall → execute → afterToolCall,五段但在一处tools/pre-execute → tools/execute → tools/post-execute 三道 waterfall 事件(core/tools/src/pipeline.ts:200)
谁能插手扩展能挂钩,但边界是实现内的函数任何插件都能在事件上挂策略,不需 import 循环
策略写在哪工具实现内部或扩展里独立的 policy 插件(含 approval、sandbox 包装 argv)
批量与并发循环内自己控制ctx.tools.execute() 接收原始批次与并发上限,统一调度

两者都把工具当唯一信任边界,但 pi 把边界画在代码里,dsh 把边界画在事件上。 前者更省事、更好读;后者让「企业策略」可以作为一个插件存在,而不是 fork 工具。

05

会话:文件即真相,还是日志即契约

πpi:JSONL 追加,12 种 entry
一行一条 entry,id/parentId 组成树; 三段上下文算法 buildContextEntries() / buildSessionProjection() / buildSessionContext()。 用 jq 就能分析,格式坏了你自己修。
Ddsh:日志即契约,还带迁移链
append-only SessionEvent;deriveMessages() 从日志投影模型历史; 格式分代(session.vN.jsonl),每相邻两代恰好一个迁移包,已提交代际永不改写。 「Model-visible means logged」是硬规则。

这是两个项目差别最大的地方,也是最容易被低估的。pi 的会话是「产品功能」, dsh 的会话是「协议」。协议要处理版本、迁移、互斥发布、未来版本拒绝解码—— 这些在 pi 里全都不存在,因为 pi 的选择是「你升级,旧会话你自己处理」。

判断依据:会话只服务你和你的脚本 → pi 够用; 会话要活过多次版本升级、要被别的系统消费 → dsh 的代际设计不是过度工程,是必需品。

06

安全:交给你,还是交给策略

πpi:明说不做
"pi runs in full YOLO mode and assumes you know what you're doing…"
pi 以完全 YOLO 模式运行,并假设你知道自己在做什么……
没有内置权限系统;安全靠容器 / VM / 沙箱这类外部手段。 扩展与工具同进程、同权限——这在架构图里被单独圈成一个边界框。
Ddsh:多层策略
ctx.sandbox 后端 + approval policy 属于 dsh-base 层(默认装上); 消费方在 spawn 前包装 argv;单列 SAFETY.md 要求运行前先读。 策略是可替换的插件,而不是散落各处的 if。

这里有一个值得说清的利益差别:pi 的 YOLO 是面向单机自用的合理默认, dsh 的沙箱是面向分发的必需品——一旦有第三方插件市场,就不能假设所有人都是作者本人。

07

扩展:一个文件,还是一棵树

pidsh
最小扩展一个 TS 文件,export default function (pi: ExtensionAPI),再 pi.registerCommand()一个 Cordis 插件:export const name + export const inject
装载方式--extension ./review.ts 或 pi install在 profile 里叠加 bundle,或用 cordis.patch.yml 插一行
分发格式npm 包bundle(配置行 + 代码),可被上层 patch 覆盖
卸载进程退出注册是可逆副作用,插件卸载即回滚
生态证据作者自己的扩展(如 review 流程)awesome-dsh-plugin、dsh-desktop、插件市场生成器 apps/plugin-market-generator

pi 的扩展模型解决的是「我一个人想加个命令」;dsh 的插件模型解决的是 「别人想在我的 harness 上卖/发一个产品」。两者根本不是同一层的问题, 所以 dsh 的 profile/bundle/patch 三层在 pi 的语境里是纯浪费,反之亦然。

08

互操作:一个不对称的发现

对比两个项目时最容易被漏掉的一条:dsh 把 pi 的模型层当成自己的一个适配器用了。

证据 packages/llm/llm-pi-ai/package.json 的 description: “pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (design-verification twin of dsh-llm-deepseek)” ——读作:「用于 dsh LLM seam 的、由 pi-ai 支撑的适配器(dsh-llm-deepseek 的设计验证孪生体)」。

这段话信息量很大:

  1. pi-ai 是可复用的。它 8 万行的多协议适配层(4 种 API 协议、跨 provider 上下文交接) 能作为组件塞进别人的架构,而不是只能整体使用。
  2. dsh 的 seam 设计经得起对照验证。他们用 pi-ai 写了一个「孪生适配器」来验证 LlmAdapter 这层抽象是否成立——两个完全不同的实现能落在同一个接口上。
  3. 关系不是替代。在组件层面,pi 的产出被 dsh 消费;在产品层面,两者竞争同一批用户。 这在基础设施项目里很常见,但很少有人会写在对比表里。

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

09

收束:一句话各自

→选 pi,如果
你要一个能被一个人完全理解的 harness;你在意每次发版后行为不变; 你愿意用「少功能」换「可预测」;你的会话只服务自己。
→选 dsh,如果
你要在 harness 上长出一个产品;你需要多种外壳共享内核; 你要把会话当长期资产;你需要企业级策略挂点;你能接受破坏性变更。

最后一句:它们对「harness 该有多大」的回答是相反的,而这恰恰是唯一重要的分歧。 其余所有差异——包数、代码量、MCP、沙箱、插件——都是这个分歧的下游结果。

本章学习记录

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