在 Agent 开发工具快速演进的阶段，许多项目都在强调“连接模型、调用工具、执行命令、管理会话”等能力。DeepSeek Harness 与 Pi 的表面功能看起来相似，但从源码结构看，两者并不属于同一层级的工程产物。前者更接近一个插件化 Agent 平台，后者则更像可嵌入的轻量 Agent 内核与 Coding Agent 组件集。
从入口看定位：Web 页面之外与可嵌入内核
DeepSeek Harness 常见入口是 npx @deepseek-ai/dsh web，容易让人把它理解成一个开源 Web 聊天页面。但源码显示，Web 只是宿主形态之一。它通过 Profile 组织可运行的产品组合，官方提供 web 和 headless 模板，Agent、Session、Tool、LLM、Sandbox 等能力并不绑定在 React 页面中。同一套 Runtime 可以被 Web、CLI、测试程序甚至未来的桌面壳驱动。
Pi 的稳定主链路则分为 Provider、Agent Core、Coding Agent Runtime 等层。终端里，它可以作为完整 Coding Agent 使用；代码里，它也可以只作为 Provider 层或 Agent Core 被其他产品嵌入。一个值得注意的源码事实是，DeepSeek Harness 的多 Provider 适配器 dsh-llm-pi-ai 底层依赖 Pi 的 pi-ai，也就是说，DeepSeek Harness 可以把 Pi 的模型接入层装进自己的插件树中。
执行机制：插件容器与直接控制流
DeepSeek Harness 的架构文档强调 “Everything is a plugin”。其底层使用 Cordis，插件向共享 Context 注册服务、生命周期和扩展点。模型适配器、工具注册表、Session Log、Agent Loop 乃至 Web UI，都可以作为插件存在。官方说明中提到，没有一个需要修改的“特权核心”，扩展行为通常是将新插件挂到已有插件旁边。
在执行粒度上，DeepSeek Harness 区分了 Turn 与 Step。一个 Turn 可以包含多个 Step。以“修改支付模块并运行测试”为例，第一次模型请求可能调用 read，读取结果回填后第二次请求调用 edit，审批并修改后第三次请求调用 bash，测试结果回填后第四次请求才给出总结。这是一个 Turn、四个 Step。
Pi 的 Agent Loop 则更直接。packages/agent/src/agent-loop.ts 中包含两个循环，处理模型请求、工具调用、结果回填和继续推理。同一条 Assistant Message 中的多个工具可以顺序执行，也可以并行执行；并行模式仍按模型原始顺序生成 Tool Result Message，保证回填上下文的顺序稳定。Pi 还处理了一类细节问题：如果模型因输出 Token 上限被截断，可能留下“可以解析但参数不完整”的 Tool Call，Pi 会将其全部标为失败，而不是继续执行。
会话与持久化：事件源投影与树形 JSONL
DeepSeek Harness 的 Session 是 append-only 的 SessionEvent 日志。核心事件包括 turn、step、message、tool call、tool result 等。其设计约束是：只要内容会进入模型，就必须能从日志重建。模型历史不是另一份独立保存的 messages[]，而是通过 deriveMessages() 从 Session Log 投影出来。会话恢复、Fork、Transcript、Telemetry、持久化和 UI 重放也基于同一条事件流。
这种事件源设计可以减少 Agent 产品中常见的“多份真相”问题：模型看到一份消息，Web 保存一份消息，工具卡片又维护另一份状态，断线恢复后彼此对不上。代价也存在：事件协议需要版本治理，投影器需要兼容历史事件，原始 chunk 会增加存储体积，新的模型可见输入也必须先定义可持久化事件。
Pi 的 Session 同样使用 JSONL，但结构不同。每个 Entry 有 id 和 parentId，所有 Entry 在一个文件里构成树；当前 leaf 指向正在使用的分支。追加消息是在当前 leaf 下增加子节点，跳转历史节点后继续工作则形成新分支。因此，Pi 更自然地支持对话分支、回退和轻量本地持久化。
扩展与权限：平台化治理与轻量扩展点
DeepSeek Harness 的工具执行被拆成受控流水线。Tool Call 在执行前就被记录，UI 可以先出现“等待执行”的卡片，崩溃恢复时也能知道系统停在什么位置。权限与审批不是散落在每个工具里的条件判断，而是由 tools/pre-execute、Guard、ctx.approval、Sandbox 和 tools/post-execute 共同形成治理链。需要审批但没有可用回答者时，系统不会放行。
Pi 的 Extension 可以注册工具、命令、上下文转换等能力，TypeScript 文件可以通过 Jiti 直接加载。对于个人工作流或团队 Coding Agent，这种机制更容易上手。但 Pi 的 Extension 主要围绕 pi-coding-agent 预设的扩展点工作，AgentSession、Session Manager、TUI 等仍是明确的核心对象，不像 Cordis 那样把 Agent Loop、Session 服务、LLM 服务和 UI 组件全部放进同一种可装卸插件模型。
Pi README 也明确说明，Pi 不内置限制文件系统、进程、网络或凭据访问的权限系统，默认继承启动它的用户与进程权限。需要强隔离时，应使用容器、微型虚拟机或外部 Sandbox。Pi 提供 Project Trust，用于决定是否加载项目本地设置、扩展和资源。
从架构上看，DeepSeek Harness 覆盖从 Provider 到 Product Host 的大部分层次，强调平台化装配、事件持久化和执行治理；Pi 则把能力拆成可按需组合的包，重点落在 Provider、Agent Core 和 Coding Agent Runtime。两者都服务于 Agent 工程，但一个更像承载产品形态的插件容器，一个更像供开发者组合使用的轻量内核。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/tong-wei-agent-kuang-jia-deepseek-harness-yu-pi-de-jia-gou
