L1ngg's Home

Harness 是 Agent 减去 LLM#

Harness 负责上下文怎么组装、工具怎么暴露、loop 怎么转、session 怎么存、失败怎么回、权限怎么卡、UI 怎么呈现。模型只负责想和说。

这层以前藏在 Claude Code、Codex、Cursor 的产品内部，容易让人以为模型变强了 agent 就变强了。2026 年的一次对照把这个拆开了。

Composio 用同一个 DeepSeek V4 Flash，在多个 harness 上跑 30 道高难度任务：

同一模型，换一层壳，成功率差 20 个百分点，成本差一个数量级。

Databricks 在自家百万行仓库上做过同类实验：同样的模型、同样的 thinking effort，不同 harness 的单轮上下文能差到 3 倍，总成本超过 2 倍。简单 harness（Pi）在他们的负载上表现最好。

真正要看的是两种对编排层的世界观。

Pi：给你原子，不给你功能#

作者 Mario Zechner（badlogic，libGDX）早期是 Claude Code 重度用户。受不了两件事：功能加得越快，行为越不可预测；他想要一个能看清、能改、能审计的 harness，市面上几乎没有。原则是：If I don’t need it, it won’t be built.

仓库从 badlogic/pi-mono 迁到 earendil-works/pi。pi.dev 第一句是：There are many agent harnesses but this one is yours.

Armin Ronacher 写过 Pi: The Minimal Agent Within OpenClaw。OpenClaw 建在 Pi 之上。薄核心加自扩展，能长出完全不同的产品。

「没做的事」比功能列表更重要：

• 没有 MCP。去做带 README 的 CLI，或自己写加 MCP 的 extension。
• 没有 sub-agent。用 tmux，或自己装包。
• 没有确认弹窗。跑容器，或自己写权限门。
• 没有 plan mode。写 PLAN.md，或装一个包。
• 没有内置 todo。用 TODO.md。
• 没有 background bash。用 tmux，可观察、可交互。

每往核心里加一个便利功能，就是在替所有用户决定工作流，并且给模型一份永远付费的上下文税。Mario 写过，Claude Code 的系统提示动辄 7k–10k token，打第一个字之前就已经在烧钱。Pi 把系统提示加四个工具定义压在 1000 token 以内。

grep / find / ls 存在，默认关。文件枚举 bash 已经会；再暴露一遍只是多一份 schema。默认没有权限弹窗：agent 能写代码并且跑代码之后，安全边界基本就没了。隔离丢给容器，比安检剧场诚实。

Harness 应该像一把锤子，不应该像一个 IDE。Pi 的产品不是「编码 agent」，是让你造出自己那把锤子的底座。

四层都可以单独拿走#

1
@earendil-works/pi-ai            统一多厂商 LLM API
2
@earendil-works/pi-agent-core    Agent loop + 工具执行 + 事件流
3
@earendil-works/pi-tui           差分渲染的终端 UI
4
@earendil-works/pi-coding-agent  把上面焊成 CLI
5
@earendil-works/pi-telemetry     厂商中立的可观测契约

pi-ai 处理 OpenAI Completions / Responses、Anthropic Messages、Google GenAI 对不齐的那一层：思考痕迹、工具调用、token 记账、中途 abort、跨厂商切模型。Pi 把 Anthropic 的 thinking 转成 <thinking> 再交给别的模型。

pi-agent-core 是那个 loop。社区拆过，大约 418 行 TypeScript：用户消息 → 模型 → 工具调用 → 结果回灌，直到模型说做完。没有 max-steps 人工上限。事件驱动，支持在 assistant 回复前插入 steering / follow-up。

pi-tui 是自己写的 retained-mode + 差分渲染 + CSI ?2026 同步输出。Ronacher 的评价：不闪、不占内存、不随机坏。

pi-coding-agent 才是用户摸到的一层：session 树、AGENTS.md / SYSTEM.md、slash 命令、主题热加载、HTML 导出。四种运行模式从第一天就没锁成终端玩具：

观测契约本身不带 exporter：

扩展看起来也像插件：extension / skill / prompt template / theme / package。第一选择不是去下一个别人写好的包，而是：没有的功能让 agent 给自己写，/reload 继续干。

Session 是树不是线。可以 fork 一条旁路去修坏掉的工具，修完 rewind 回主线，Pi 把旁路上发生的事摘要回来。这是为软件改软件准备的，不是为多开几个 chat tab。

社区已经长出 sub-agent、plan mode、MCP、沙箱、SSH、路径保护、状态栏，甚至等模型时在终端里跑 Doom。全部可选，不进核心、不进默认系统提示。Playwright MCP 21 个工具大约 13.7k token，Chrome DevTools MCP 26 个大约 18k。真需要浏览器，写一个带 README 的 CLI 或 skill，按需加载。

极简前缀碰巧打中 prefix cache#

DeepSeek API 是 prefix KV cache：下一轮必须从第一个 token 起字节级相同，缓存才命中。前缀越早被改，后面作废得越多。

Agent 请求的前缀通常是系统提示 + 工具 schema + 对话历史。多数 harness 在这里埋雷：每轮改日期和工作目录、按需装卸工具导致 schema 抖动、重写摘要、注入时间戳。有记录的事故是 Qwen Code 加 ToolSearch 之后，DeepSeek 缓存命中从约 98% 掉到约 81%，日账单翻 3 倍。

Pi 的系统提示几乎静态，工具集合几乎不变，compaction 走扩展且可以做成确定性（temperature 0 + hash）。开发者 0xEvan 用 Pi 调 V4 Flash，处理近 10 亿 input token，缓存命中 99.93%，账单 $2.65；无缓存估$132。

这不是 Pi 为 DeepSeek 定制。是极简前缀打中了 prefix cache 的物理约束。本地模型同样受益：前缀稳，prefill 才能复用。

DSH：没有特权核心#

2026 年 8 月 13 日前后，DeepSeek 以 MIT 开源 deepseek-ai/deepseek-harness。写作时约 0.1.0-rc.8 的 developer preview，官方明确会有破坏性变更，暂不收外部 PR。启动：npx @deepseek-ai/dsh web。

官网上的定义干净：Agent = Model + Harness。两句原则：Everything is a plugin；Every run is traceable。

底层是 Cordis——Shigma 从 Koishi 里长出来的元框架。理论文章是北大 + DeepSeek 的 A Programming Paradigm for Spatiotemporal Composability。内核基因是「聊天机器人要热插拔插件」，不是「程序员要一个稳的 CLI」。后面所有过度抽象的争议，根子都在这里。

Pi 说核心要薄、外围可插。DSH 说没有不可替换的核心。模型适配器、工具注册表、session 日志、沙箱、UI、Agent Loop 本身（ctx.agentLoop）都是插件。官方原话：There is no privileged core to patch。

默认 Coding Agent 只是用这些插件拼出来的一个答案。四种 mode 是同一袋插件的不同组合：

Minimal 用来跑官方评测——承认 scaffolding 会污染模型分数，先提供一个几乎裸的对照面。Claude Code / Codex 可以整颗当成 subagent 插件挂进来：编排层是 DSH，脏活可以外包。这是平台思维。

Cordis 在形式化什么#

时间可组合：组件离开时，做过的事能不能撤销。答案是 revertible effects，卸载按 LIFO 回放：

1
ctx.effect(() => {
2
  registerSomething()
3
  return () => unregisterSomething()
4
})

fiber.ts 大约 750 行，管 PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED、并发卸载、disposer 失败、热替换回滚。

空间可组合：系统能不能知道这个组件依赖什么。插件用 inject: ["llm", "tools", "sessions"] 声明。服务到了就启动，走了就停，不靠手写 boot 顺序。

事件契约写进类型：

agent/pre-step、agent/request、llm/stream、tools/pre-execute|execute|post-execute 都是 waterfall。不调 next() 就是否决。

理论成立的前提：每个 effect 真的可逆，且互不破坏。发邮件、删库、打款没有逆操作。Cordis 也不能证明 cleanup 真的撤销了 startServer()。契约一旦被 LLM 卷进来，上下文窗口会引入框架保证不了的隐式依赖。

运行时怎么拼#

一次启动是有序插件树，不是扫一遍 plugin 目录：

1
bundle（按 profile 列出的顺序）
2
  → profile 自己的 cordis.patch.yml
3
    → 用户 home 级 patch
4
      → --patch 覆盖

dsh-base 是每一棵树的第一层。dsh --profile web --dump-config 能把本机真正启动的树打出来，任何一行都可以被 patch 换掉。

真正不能换、还被不变量钉死的，是 append-only session log。官方：Model-visible means logged。 Fork、resume、replay、transcript、遥测、UI 都是这条流的投影。

Pi 的 session 树在使用者工作流上更强（旁路修工具再 rewind）。DSH 的 event log 在系统可观测性上更强。

Turn 状态机：

1
turn/start
2
  claim 下一步输入 + 一条排队消息
3
  组装 prompt sections + tool schemas
4
  → agent/pre-step          拒绝 | enter(messages)
5
     step/start
6
     从 log derive 模型历史
7
     agent/request → llm/stream → assistant/chunk* → assistant/message
8
     tool/call* → tools/pre-execute → execute → post-execute → tool/result*
9
     step/end
10
     工具还欠一轮，或新输入到了 → 下一 step
11
  → agent/turn-stopping
12
turn/end

Capability seam 必须同时有 Service Definition、Provider、Consumer。文件系统和 subprocess 共享同一个 execution world——指到远程沙箱，Bash / PTY / LSP 一起走。

沙箱按 OS 落地：Linux Landlock、macOS Seatbelt、Windows ACL token。网络和进程可见性不在这套词汇里。danger-full-access 这种预设存在。预览期产品，别当隔离边界。

热插拔、可卸载、loop 可换，对每天写业务的人几乎没有刚需。Markdown + CLI + 重启两秒能解决 95% 的扩展问题。这些能力只有在一个前提下才突然合理：模型要亲手改自己的运行环境。 官方现在还克制：动态插件只活在内存里，重启就没了。方向已经做成架构里的一等公民。

Pi 是 To Dev 的现在时。DSH 是 To LLM 的将来时。

信人还是信契约#

Pi 信任坐在键盘前的人：四个工具，一个 loop，YOLO，失败时看终端里每一步。

DSH 信任运行时契约：没有默认立场，profile 说了算；失败时看 trajectory 和按源检查的 event stream。人仍然可以控制，但控制面从「读 418 行 loop」变成「读一棵插件树 + 一张事件表」。

这是 Unix 对 Eclipse 的重演。抽象层级不同，不是谁对谁错。

Pi 消灭复杂度。核心越薄，模型越不容易被噪音带跑，缓存越稳，一个人能把整个 loop 装进脑子。代价是 plan mode、权限门、多 agent 得自己装或自己写。开箱即用的完整工作流不是它的目标。

DSH 结构化复杂度。理论上能换掉任何一层。代价是认知从「读一个小 loop」变成「Cordis + seam + profile/bundle/patch + 四种事件模式」。把 Agent Loop 和 Memory 这种性质完全不同的东西压成同类插件，是「一切皆文件」反复犯过的错。理论优美，对接成本经常高于抽象本身的价值。

诚实的方向也不同。Pi：人眼可观测，你看见模型看见的东西。DSH：机器可重建，六个月后回放这次 run，并证明当时模型看到了什么。审计、RL 数据、harness 自进化更吃后者。

社区有一组同任务对比（单一样本，方向可信、精度当参考）：

估算未缓存 input 大约差 10 倍。Standard mode 工具多、流程长，和「完整默认答案」一致。Minimal mode 会好很多——那基本上在向 Pi 的形状靠拢。

Prefix cache 是 2026 年 agent 成本的第一物理定律。DSH 架构允许把 prompt 组装做成前面冻住、只在后面追加（system-prompt 是插件），默认配置现在显然还没做。

两边都不能当生产隔离边界。Pi 至少不假装有。可替换不等于已治理。

Pi 可以当 SDK 嵌进 OpenClaw 这种完全不同的产品；DSH 可以反过来把 Claude Code、Codex 当成工人。Pi 卖的是一个稳定、可读的 loop。DSH 卖的是一棵能把别的 loop 也挂上去的插件树。

主要来源：

• pi.dev / earendil-works/pi
• Mario Zechner，What I learned building an opinionated and minimal coding agent
• Armin Ronacher，Pi: The Minimal Agent Within OpenClaw
• Pragmatic Engineer 访谈
• DeepSeek Harness / docs/architecture.md
• Cordis / Spatiotemporal Composability
• Composio 对照、0xEvan 的缓存数据