所以我想搞清楚一个问题：这一轮换代，为什么是 Playwright？

趋势本身很清楚：2025 年的行业调查里，它的使用率第一次超过 Cypress（50% 对 47%），而最新的周下载量是它的 17 倍。但数字只能说明趋势，说明不了原因。

功能表也回答不了，得往下一层看：那一行 click() 在真的落下之前，究竟检查了什么。我拿一颗 600 毫秒之后才可点的按钮当尺子，把它拆成四道关：怎么找到元素、怎么判断能点、怎么把动作送进浏览器、失败之后留下什么。四道关看完，再回头说这两年的事。

被测的页面很小，存成 HTML 双击就能打开：一个标题、一颗 600 毫秒之后才可点的按钮、一行结果。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!doctype html>
<html lang="zh">
<body>
  <h1>下单</h1>
  <button id="submit" disabled>提交订单</button>
  <p id="result"></p>

  <script>
    // 模拟一个 600 毫秒才回来的接口：这期间按钮是禁用的
    setTimeout(() => { document.getElementById('submit').disabled = false; }, 600);

    document.getElementById('submit').addEventListener('click', () => {
      document.getElementById('result').textContent = '已提交';
    });
  </script>
</body>
</html>

判断成没成功只看一件事：最后那行 <p id="result"> 里有没有出现「已提交」。

被测页面就长这样（Playwright 1.57.0 + Chromium，2026-10-01 实拍，360 像素宽视口）：同一个脚本的三种状态，下面四道关对着的都是这一张页面

同一颗按钮，三种点法，结果却各不相同：

1
2
3

await page.mouse.click(320, 210);                             // ① 按坐标点
await page.locator('#submit').dispatchEvent('click');         // ② 直接派发事件
await page.getByRole('button', { name: '提交订单' }).click();   // ③ 正常点

只有 ③ 会等。① 什么也没发生：按钮还禁用着，浏览器把那次鼠标事件吞了。② 结果栏变绿了，可那其实是假的，按钮当时根本点不动。这篇文章里的四道关，拆的就是 ③ 的那一行。

一、第一关：它怎么知道“找到了”

我们习惯说“拿到一个元素”，但在 Playwright 里，page.getByRole('button', { name: '提交订单' }) 拿到的不是一个元素，而是一句描述。官方管它叫 locator，定义是“一种在任何时刻都能找到元素的方式”（见 Locators）。

这句话听着像修辞，其实有个很实在的后果：每次要动手之前，它会拿这句描述重新解析一遍。所以我那个实验才有意义。把 class 从构建哈希 btn-primary-9f2c1a 改成 btn-primary-4b8e77，模拟一次重新构建，page.click('.btn-primary-9f2c1a') 当场超时，报 Timeout 1200ms exceeded；那句按角色和名字写的描述照样命中。

解析出来之后其实还有一道更严的检查：必须恰好命中一个。这就是“找到”在这套实现里的定义。一句描述如果同时匹配到 20 个元素，它不会随便挑一个，而是停下来告诉你匹配到了 20 个。（这个决定的好处，第四关会看到。）

那“角色是 button、名字是提交订单”这些词从哪儿来？来自浏览器的可访问性树：浏览器会把页面另外解析成一棵树，每个节点带三样东西，角色（role）、名字（name）和状态（state）。屏幕阅读器读的就是它，getByRole 读的也是它，第六节那个 ARIA 快照还是它。

原生标签自带隐式的 role（<button>、<a href>、<input type="checkbox"> 都有），自定义组件就得自己补上：aria-label、aria-labelledby，或者 <label for>。我拿一个只用 <div onclick> 拼的按钮试过：getByRole('button').count() 是 0，它在快照里降级成了一行普通文本；补上 role="button" 之后才是 1。

所以第一关交出来的东西，其实是一句“此刻唯一命中的描述”。反过来，那种“真的抓到一个元素”的用法（ElementHandle）被官方标上了 Discouraged。

二、第二关：它怎么判断“能点了”

找到了不等于能点。这一关是 Playwright 最出名的地方，官方叫 actionability，原话是：

It auto-waits for all the relevant checks to pass and only then performs the requested action.

翻成人话：动手之前，它会把下面四条逐个等到成立。

四条里我最喜欢第二条。“连续两帧不变”这种抠到帧的定义，等于把老工程师嘴里那句“等它别动了再点”直接写成了代码。这一关干的就是这件事：把人的经验变成可判定的条件。

回到那颗按钮，这一关跑完是 858 毫秒。它倒不是睡得久，是一直在等条件成立。

这里得补一句公道话，不然容易被读成 Playwright 的独家本事：自动等待其实不是它发明的。Cypress 早就有，检查项比这四个还多（多出 detached、readonly、covering 三项），它也会盯着 DOM 不断重跑查询（官方原文：*”Cypress will watch the DOM - re-running the queries that yielded the current subject…”*）。我实测过，一条完全不带等待的 Cypress 用例照样通过，耗时 846 毫秒，和 Playwright 的 858 毫秒几乎一样。

真正没有它的是上一代那两家。Selenium 的文档把话说得很直白：显式等待是“loops added to the code that poll the application for a specific condition”，说白了就是一段写在代码里、反复轮询到条件成立的循环；它那一页自己还摆了个 sleep() 的例子，里面写的是 Thread.sleep(1000)。Puppeteer 也一样，判据得自己写：

1
2
3
4
5

await page.waitForFunction(() => {          // 判据得自己写
  const btn = document.querySelector('#submit');
  return btn && !btn.disabled;
});
await page.click('#submit');

把中间这三行删掉会怎样？我倒是真跑了一遍：脚本不报错，输出是空的。按钮还禁用着，浏览器把那次点击吞了。

所以第一关和第二关合起来说的是一件事：“什么时候能动”这件判断，从使用者的代码里搬进了工具里。 差别不在“等不等”，而在那一行 click() 里到底有没有检查。

三、回头说开篇那个“假成功”

开篇那三种点法里，② 为什么能“成功”？因为 actionability 有四条检查，但也留了后门。官方文档写得倒是很直白：给 click() 传 force: true，就会跳过“非必要”的检查，比如“这个点上真的能收到点击事件吗”这一条。dispatchEvent('click') 更彻底，它连点击都不模拟，直接把事件塞给元素。

三种点法摆在一起是这样：

录制自真实运行（Playwright 1.57 + Chromium）：① 按坐标点，按钮还在禁用态，什么也没发生；② dispatchEvent 把事件直接发进去，结果栏变绿，其实是假成功；③ click() 等到按钮可用才动手

我把这三条路都跑了一遍。按钮还禁用时，按坐标点没反应，用 DOM 自己的 element.click() 也没反应，唯独 dispatchEvent('click') 让结果栏变成了「已提交」。

原因是浏览器的“禁用”只拦两样东西：真实的指针事件，和元素自己的 click()。它拦不住直接用事件接口投递的那一下。所以这个“假成功”不是“什么都没发生”：监听器执行了，DOM 也变了（这个页面里没有表单，“已提交”就是结果栏那行字被改了），只不过它走的是一条真实用户走不到的路。真实用户那一刻点不动这颗按钮，你的用例却认为点成功了。

不做检查的自动化，最危险的地方不是失败，而是它能给你一个假成功。 一条“禁用状态也照样点进去”的用例会在 CI 里一直绿着，直到上线被真实用户教做人。

四、第三关：动作怎么送进浏览器

判断完了，动作得真的送出去。这一段路平时看不见，但它决定了这个工具最后能长成什么样：动作经由什么送出去，最后又落在哪个浏览器上。

先说 Cypress，它走的是另一条路。装完 node_modules/cypress 只有 7.3 MB，可真正的执行体是它下载到缓存里的 641 MB 应用：测试是被这个应用带着跑的，而不是被一行 require 拉起来的库。官方文档把原因说得很清楚：*”Cypress is executed in the same run loop as your application.”*（见 Why Cypress）

1
2
3
4

Cypress 应用（一个自带浏览器）
├── 测试代码 + Cypress 驱动
└── iframe：被测应用
    （两者共用一个事件循环）

一个浏览器里同时住着测试代码和被测应用，两者共用一个事件循环。这个设计的确换来了很好的调试体验（后面会替它说话），代价是它只能以“一个应用”的形式存在：模块 API 文档里一共只有三个函数，cypress.run()、cypress.open()、cypress.cli.parseRunArguments()（见 Module API）。你能用 Node 启动一次运行，但拿不到一个页面：没有 page，也没有任何能在自己进程里操作的对象。

Playwright 反过来。@playwright/test 是一个测试 runner，但它建在 playwright-core 这个库上，chromium.launch() 在任何 Node 进程里都能跑起来：你可以在自己的脚本里开一个浏览器，做完事再关掉，全程不进 runner。

1
2
3
4
5
6
7
8

你的进程（测试，或任意脚本）
   └── browser / page 对象
        │  Playwright 自有协议
        ▼
   浏览器进程（三选一）
   ├── Chromium
   ├── Firefox
   └── WebKit

（Python、Java 这类绑定中间还会多一个 driver 进程。）

那三个内核可以只装一个，也可以一起用。我本机上装着的的确就是三个：

1
2
3
4

~/Library/Caches/ms-playwright/
├── chromium-1200
├── firefox-1497
└── webkit-2227     # 真 WebKit，不是换皮

这里的“一视同仁”指三个内核都由同一套 API 支持，而不是“能不能跑起来”：Cypress 的 WebKit 至今标着 experimental，Puppeteer 干脆没有 WebKit。

三个内核共用一套 API 这件事，看着像开个 flag 就行，其实翻一遍是三层叠起来的。

第一层，语言绑定和浏览器之间隔了一层协议。JS、Python、Java 里调的是同一份实现，通过 Playwright 自有协议（仓库里的 packages/protocol/spec/*.yml）跟浏览器说话。

第二层，三个内核走三条通道，要的东西却不一样。这张表是整件事的关键：

第三层，也是最关键的一层：它自己编译并维护内核。上面那两个 flag 不是“开关”，而是只有打过补丁的构建里才存在的通道。Playwright 每次发版同步更新三个内核的版本，npx playwright install 下载的就是这些自定义构建，我本机这份缓存已经 1.0 GB：chromium 324 MB、webkit 275 MB、firefox 253 MB，另有 headless shell 与 ffmpeg。

只跑一个内核其实不必这么重。npx playwright install chromium 的下载量约 250 MB，CI 上加个 --only-shell 能压到 90 MB；一个字节都不下也行：配上 channel: 'chrome'，直接用机器上现成的 Chrome。

那为什么别人做不到？其实不是开不了 flag，是改不了内核。

• Cypress 把驱动注入浏览器、与测试同处一个事件循环，内核不许注入它就没办法，自带不了打过补丁的 WebKit（反过来，这也是它的 devtools 联动调试更顺手的原因。Gleb Bahmutov 的个人观点，不是官方结论）。
• Puppeteer 是 CDP 的参考实现，不需要改内核。不过这里还有段前情：Firefox 那边当年就有一条专门为 Puppeteer 做的自动化协议（puppeteer/juggler，2020 年 3 月之后就停了），Puppeteer 还据此发过一个自带 Firefox 构建的原型包，后来标注废弃；正经的 Firefox 支持等到 2024 年的 v23，用的还是 W3C 标准的 WebDriver BiDi。能不能做是一回事，要不要长年养两个内核的分支是另一回事。
• Selenium 走的是相反的路线：它从一段跑在浏览器里的 JavaScript 起家（官方 History），因为出不了同源策略那道墙，才改成把浏览器当远端、中间放一台代理 server（Selenium RC），最后把这条路走成了公共契约（WebDriver，Level 1 在 2018 年成了 W3C Recommendation）：覆盖面不由任何一家供给，代价是契约不替你管会话和等待。

代价倒也说清楚：这套“连内核一起维护”的赌注，换来了三内核一致和额外的自动化能力，付出的是每次升级重下几百 MB 的自定义浏览器，外加内核补丁的长年维护。

能当零件用，还是只能当整机用，这是 Cypress 和 Playwright 的分界线。 所谓“一层能力”，不是 API 多，而是它可以脱离原来的应用形态，被另一个程序直接拿起来、观察、调用、组合、复现。这一关最要紧的产出就是这个：动作经由一条自有通道送出去，而这条通道可以被任何进程调用。

口径：架构部分来自官方文档与仓库源码。“Juggler”这个词官方文档从不使用，只出现在源码与补丁目录里，属于源码级证据，别当成官方术语引用。

五、第四关：失败留下了什么

前三关讲的是动作怎么成功。可在 CI 上，你更常面对的是失败。

测试失败时，Playwright 会给你一个 trace.zip，里面装着每一步的动作与耗时、动作前后的全量 DOM 快照、截图、源码、日志和网络记录（见 Trace Viewer）。它把“一次性现象”变成了一个文件：能塞进 CI 产物，能在别人机器上打开，从 1.59 起还能直接用命令读（npx playwright trace）。

这里不妨先说人的收益，因为它跟 AI 没关系：以前 CI 挂了，你得把那台机器复现出来；现在工件跟着失败一起被存下来。至于模型也能读它，那是顺带的。

Trace Viewer 实拍（Playwright 1.57.0，2026-09-19）：左边那步失败的 Click 被标红选中，右边是当时的页面快照，底部 Errors 面板给出报错正文与 Copy prompt 按钮

然后是我最喜欢的那段报错原文。我构造了一个 20 行订单列表，故意用模糊定位去点它：

1
2
3
4
5

locator.click: Error: strict mode violation: getByRole('button', { name: '查看' }) resolved to 20 elements:
    1) <button aria-label="查看订单 SO-1001 详情" ...> aka getByRole('button', { name: '查看订单 SO-1001 详情' })
    2) <button aria-label="查看订单 SO-1002 详情" ...> aka getByRole('button', { name: '查看订单 SO-1002 详情' })
    3) <button aria-label="查看订单 SO-1003 详情" ...> aka getByRole('button', { name: '查看订单 SO-1003 详情' })
    ...

第一关那道“必须恰好命中一个”的检查，在这里的确显出价值了。它不只是说“你错了”：它说明了为什么错（匹配到 20 个），给出了每个候选的真实身份，最关键的是那句 aka，把改正后的 locator 写法一条条列给你了。这不是给人看的礼貌提示，这是一份写好的补丁。而且这大概不是巧合：从 1.51 起，Playwright 在 HTML 报告、Trace Viewer 和 UI Mode 的报错旁都放了一个按钮，叫 Copy prompt（见发布说明）。

修复的前提是复现：一个失败如果只活在那台机器上，换个人（或者换个 agent）就只能靠猜。好在它现在有了载体，现场在 trace.zip 里，该点哪儿写在 locator 里。于是同一个失败能在 CI 上产生，在本地打开，也能被另一个程序读。

可序列化不是“能被自动修复”的保证，但它是前提。

六、为什么是这两年

四道关讲完了。这四件事其实 2020 年就做完了，只不过那时它们的读者只有人。为什么会用的机器多起来之后，它们突然都变得重要？

换句话说，技术的价值常常要等另一个时代来证明。Playwright 不是为 agent 发明的，但它恰好把这四样东西都备齐了。

先把官方自己的动作排一排（来源：发布说明，日期取自 npm registry 的发布时间）：

2025 年 3 月，微软把 Playwright 包成了一个 MCP server（playwright-mcp，建仓到 2026-10-03 已 37,776 star）。它的 README 第一段就把立场说透了：

“enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.”

再看它给模型的工具描述：browser_snapshot 的说明是 *”this is better than screenshot”*，而 browser_take_screenshot 是 *”You can’t perform actions based on the screenshot”*。（视觉能力要显式开：--caps=vision。）

那“结构化”到底省了多少？官方其实没有给过量化声明，所以我自己量了一次：同一张组件库风格的页面（20 行表格、class 哈希、内联 style、__NEXT_DATA__），page.content() 出来是 12,805 个字符，locator.ariaSnapshot()（ARIA snapshots）出来是 2,286 个，17.9%。

但体积其实只是副产品，形态才是重点。不妨看一眼 ARIA 快照长什么样：

1
2
3
4
5
6
7

- heading "订单工作台" [level=1]
- form "筛选":
  - textbox "关键词":
    - /placeholder: 输入订单号
  - combobox "状态":
    - option "全部" [selected]
- row "SO-1001 张三 ¥1,280.00 待发货"

没有 css-1x1q7，没有 ant-table-cell，没有构建产物留下的哈希。模型拿到的是词汇表（role、name、state），而不是渲染残渣，这恰好就是 getByRole 需要的输入：同一个抽象层，人和模型都能读。人看的是渲染出来的界面，模型看的是同一棵树，换的是观察方式，不是那一层。

同一个页面、同一时刻的两种表示：左边是人看到的像素，右边是模型读到的结构（Playwright 1.57.0，2026-10-01 复现并截图；左图是 620 像素宽视口的页面顶部 8 行）

不过这里有个反转得说。同样是官方 README，在 2026 年给出了一个降温的说法：playwright-mcp 现在推荐 coding agent 改用 CLI + Skills（microsoft/playwright-cli），理由是 *”…avoid loading large tool schemas and verbose accessibility trees into the model context.”*。连 accessibility tree 都会被嫌啰嗦。

这句话其实反而让整篇文章的论点更稳，但得说清楚它稳在哪：前面我量出 ARIA 快照比 HTML 小 5.6 倍，官方现在又说它依然太占地方。两件事不矛盾，因为被时代选中的从来不是“小”，而是可裁剪：2,286 个字符照样塞不进上下文，但它可以被切片、按需取一部分，HTML 那 12,805 个字符不行。

所以这两年真正稀缺的东西，其实是好的工具接口：能描述、能观察、能行动、能验证、能留下现场，还能被另一个程序重新消费。

当“给模型消费”这几个字开始出现在发布说明里，剩下的就不用我多说了。

七、什么时候我不换

第六节说的是 Playwright 拿到了什么。但“一层能力”这个说法有个副作用：容易被读成“应用的形态过时了”。所以这里得把边界补上。

组件测试，我仍然会先看 Cypress。 它有官方的 mounting library 和 bundler 集成（React、Vue、Angular、Svelte 都有）。Playwright 的组件测试到 1.62 才换成 mount() fixture 加自建 dev server 的 stories 模型，1.63 又宣布三个 experimental-ct-* 包不再更新。对以组件为主的团队来说，迁移成本是实打实的。

调试联动性，是 Playwright 的真实短板。 Cypress 的测试和应用跑在同一个 JS 事件循环里，在 devtools 里下一个断点，两边会一起停住；Playwright 的 runner 和应用则是两个进程，联动调试要麻烦得多。（口径：这是 Gleb Bahmutov 的个人观点，不是官方结论，但的确是内行话。）

另外两类场景也别硬换：Selenium 的六种语言绑定加 Grid 编排，是多语言或企业遗留团队的结构性优势；纯抓取和轻量脚本，谁也不想先装一个测试运行器，Puppeteer 在这条路上仍然稳。

还有一件得坦白说：Playwright 不会自动消灭 flaky 测试。我手头那个用 @playwright/test 的项目里就留着反面教材：

1
2

const firstHistoryItem = page.locator('.home-history-item').first();
await page.waitForTimeout(1000);

waitForTimeout(1000) 和开头那个 sleep(800) 是同一种东西，只是换了个更时髦的名字。换工具不会消灭 flake，它只是把 flake 从“语言层面”挪到了“用法层面”。 换一副鞍具也不会自动让马跑得更快（“鞍具”这个说法来自上一篇横评《给大脑配一副好鞍具》，再往前那篇《积木，而非成品》拆的是同一个问题的另一个样本）。

所以这一节的结论是：Cypress 不是被打败的，是被“换了用法”绕过去的。 你如果只写给人看的组件测试，它仍然是好选择；你要的如果是一层能被别的程序消费的能力，那现在只有 Playwright 够用。这两件事不是同一个问题的两个答案，是两个问题。

八、把数字摆齐

坦白说，机制讲完了还得看采用。以下数据都是 2026-10-03 抓的。它们证明不了 Playwright 在所有测试场景都更好，只说明一件事：浏览器自动化正在往一处集中。

State of JS 2025（13,002 人，调查期 2025-09-24 到 11-11）：

比使用率更值得看的倒是留存：94% 对 57%。同一周（2026-09-26 到 10-02，取自 npm registry API），playwright 的下载量是 1.09 亿，Puppeteer 1,200 万，Cypress 621 万，Selenium 的 JS 绑定 187 万，也就是 9 倍、17 倍和 58 倍。按 star 看，playwright 97,029 颗，puppeteer 95,644 颗，几乎打平。star 数是“多少人觉得它值得收藏”，不是“多少人在用”，星标打平、下载量差 9 倍，这个剪刀差就是“工具定位不同”最直观的证据：Puppeteer 还是抓取和脚本的第一选择，只是那条赛道上没有测试。

说“Cypress 完了”，其实既不准确也不厚道。它在下滑，但没停：2024 年裁员 11 人，2026-09-01 照常发布 Cypress 16；这两年它一直在 AI 上押注，甚至出了一份《Playwright → Cypress 迁移指南》。守势是真的，停更不是。

还有一条数字倒是反过来的，得摆在这儿：按 ecosyste.ms 统计，cypress 被 6,559 个包反向依赖，playwright 只有 1,947 个。下载量赢了 17 倍，但“嵌进别人项目里”这件事 Cypress 仍然更多，这是存量与增量的差别，不写出来就是选择性取证。

Selenium 也还在跑（4.50，2026-09-30 发布），只是 24% 的留存率把痛点写在了脸上：正是“等待和会话”这两件它当年留给用户的事。

有几条流传很广的说法，我顺手核了一遍：

口径与免责：npm 下载量含 CI 里的重复安装、镜像同步和间接依赖，它是量级指标而不是用户数，playwright 这个包还被大量用于抓取，不全是测试。正文里的耗时、报错、ARIA 比例都是我自己在本机量的；版本号与下载量都只是 2026-10-03 的快照，引用请以当时为准。

结语

把全文收进一张表，方便你直接贴到团队文档里：

一句话总结这篇长文：浏览器自动化从“一个应用”变成了一层“可以被调用的能力”。Playwright 赢的不是测试，它赢的是这一层。 至于 AI，它不是这场换代的原因，它是把这件事的价值放大了一档的那阵风。

这篇里的数据我其实核了两遍，但开源世界变化快，难免有疏漏；我对 Playwright 的用法也还在摸索，谈不上什么最佳实践。如果你在迁移路上踩到了不一样的坑，或者发现文中哪里写错了，欢迎指出、欢迎交流。也不妨拿自己项目里最 flaky 的那条用例试一遍，再回来说说体会。权当这篇是一次公开的读书笔记，能对你有点用，就算是额外的收益了。

彩蛋

第三关引过的那份 2020 年的 FAQ 里，有一节专门回答“Playwright 用哪些浏览器版本”，开头第一句是：

Playwright does not patch the rendering engines. It either uses stock versions of the browsers (Chromium) or extends remote debugging protocols of the respective browsers (WebKit, Firefox) for better automation. Our browsers are as pure as they can be.

同一节里，他们给补丁安排了一个期限：补丁会持续往上游提，等关键改动能落地，就切回“上游优先”的模式；在那之前，WebKit 和 Firefox 的补丁“for now”放在 browser_patches/ 下。六年后的今天，官方文档写的是“Playwright 依赖补丁，用不了品牌版 Firefox”，第三关那张表里的 Firefox 走的还是打过补丁的 -juggler-pipe，而 browser_patches/ 这个目录还在，两套都在。那个“for now”，用了六年。

还有个更小的。当年团队判断“能不能上生产”，靠的是挂在维护者 aslushnikov 个人域名下的一个页面：Is Playwright Ready?（那份 FAQ 里点名推荐过它），逐内核列出还没通过的测试。我今天打开，整页倒只剩一句：Is Playwright ready? YES! 六年的测试矩阵，被收进这两个词里。

承诺会过期，目录不会。

参考

官方文档与发布说明：

• Playwright - Actionability（可操作性判定）
• Playwright - Locators / ElementHandle（已标注不推荐）
• Playwright - ARIA snapshots / Trace Viewer
• Playwright - Test Agents（planner / generator / healer） / Release notes
• microsoft/playwright-mcp（README） / microsoft/playwright-cli（CLI + Skills）
• Puppeteer - FAQ（定位与浏览器支持）
• puppeteer/juggler（已归档：Firefox 为 Puppeteer 写的自动化协议） / puppeteer-firefox（已废弃的原型，自带 Firefox 构建）
• Cypress - Module API（只有 run / open / parseRunArguments） / Why Cypress（同一事件循环）
• Cypress - Interacting with elements（七项检查）
• Cypress 16 发布 / Update on Cypress’s Workforce
• Selenium - History（同源策略与 driven 模式） / Waits（显式等待即轮询循环）
• W3C WebDriver Level 1（2018 Recommendation） / Level 2（Working Draft） / WebDriver BiDi（Working Draft）

数据与观点来源：

• State of JavaScript 2025 - Testing
• npm registry downloads API（对比 cypress、puppeteer）
• ecosyste.ms（反向依赖统计）
• Cypress vs Playwright; Browser Included — Gleb Bahmutov（个人观点）

延伸阅读（我自己的前几篇）：

• 《给大脑配一副好鞍具：五款 Agent Harness 的解剖与实测》：同一个“形态决定上限”的问题，看的是模型外面那层壳
• 《积木，而非成品：Pi Agent Harness 的克制与精妙》：同一套拆解方法的另一个样本

版本与核实说明：数据（下载量、调查、star、反向依赖）与彩蛋里那个页面的状态都核于 2026-10-03；文中代码都在本机实跑过：Playwright 1.57.0 + Node 24.13.0、Puppeteer 25.12.0 + Chrome for Testing 154、Cypress 16.1.1，输出是当时的终端原文，不是手写示意。（Playwright 本机锁在 1.57，撰写时最新是 1.63，1.60 之后的能力都以官方发布说明为准。）Selenium 那段沿革来自官方 History 页，没有实跑（跑它要另装 JDK、Maven 和 ChromeDriver）。四张图都在本机实拍：三种点法的动图与 Trace Viewer 实拍摄于 2026-09-19，ARIA 对比图与按钮三态图摄于 2026-10-01（字符数与 9 月 19 日那次一致）。凡官方没有量化声明的地方，文中都写明了那是我自己量的。

这篇文章想把 Pi 拆开看看，把内部机制往深里挖一层。我想搞清楚两个问题：它是怎么一步步长成今天这样的，以及我们敲下一行命令之后，它内部究竟发生了什么。

第一个问题的答案不在文档里，在 git 历史里。所以先去翻它的提交记录。

一、它一开始只有三个包

1.1 首提交里的三件套

翻到 2025-08-09 的第一个 commit，里面只有三个包：pi-tui（差分渲染的终端 UI 库）、pi-agent（带会话持久化的 agent 库），以及一个叫 pi 的 CLI。第三个 pi 跟 coding agent 毫无关系，它的 README 第一段是：

Deploy and manage LLMs on GPU pods with automatic vLLM configuration for agentic workloads.

用法是 pi start Qwen/Qwen2.5-Coder-32B-Instruct。“Pi” 这个名字最早属于一个在 GPU 机器上部署模型的工具。后来编码 agent 越长越大，反过来继承了这个名字。所以别问它是不是圆周率，它更像“某台跑模型的机器”的昵称（官方从没解释过，这是我的考古推测）。

一周之后，pi-ai 被抽了出来。2025-08-17 的 commit 写着：feat(ai): Create unified AI package with OpenAI, Anthropic, and Gemini support。这是 Pi 的第一次分层，把“模型怎么接”从 agent 里剥出去，单独成了一个包。

两个月后，2025-10-17，coding-agent 出现。产品层有了。

1.2 一年之后，十一个包

把每个包第一次出现的日子排一排：

一年时间，三个包长到十一个。中间有进出，pods 被删了，storage 改名成了 session-backends，表里都标了。这条时间线基本是被需求推着走的，很少看到先画一套架构再落地。模型要统一，就抽 pi-ai。要有产品，就长出 coding-agent。会话要能被别人接进来，就有了 server 和 protocol。

也有例外：上下文压缩在动手前两天先写了研究文档，pi-tui 至今留着一份 tui-plan.md，开头就说它记的是设计讨论里定下来的东西。

那些机制也是这么长出来的：

连“Pi 是什么”也是长出来的。它对自己的称呼改过好几轮：2025 年 11 月中旬叫 “a radically simple and opinionated coding agent”，2026 年 1 月底换成 “minimal terminal coding harness”，2026 年 5 月第一次把 “Pi Agent Harness” 写进标题（当时标题里还拖着一个尾巴：“# Pi Agent Harness Mono Repo”），到 2026 年 6 月才精简成今天这句。

长到最后，形状是这样。箭头从使用方指向被使用方，被依赖的那一方对上面一无所知。

1
2
3
4
5
6
7

pi-coding-agent（CLI：interactive / print · json / rpc / SDK）
   │
   ├─ pi-agent-core（agent 循环、会话树、压缩、状态机）
   │    └─ pi-ai（统一多 provider LLM API）
   │         └─ OpenAI / Anthropic / Google / DeepSeek 等
   │
   └─ pi-tui（自研终端 UI：差分渲染）

pi-tui 是这张图里唯一的旁支：它不依赖任何其他内部包，只是被产品层拿去渲染界面。

每一层都切在自己的 package 边界上，多数层在 npm 上能单独装，只有 evals 没发布。有意思的是 commit message 里给的理由全是内部需要，统一多 provider、把遥测抽出来、给目录改名，没有一条写着“方便别人复用”。但结果摆在那里：想要 agent 循环就拿 pi-agent-core，想要终端渲染再带上 pi-tui，产品层自己写就行。这也是它敢管自己叫“库”的底气。

说完它是怎么长成的，回到第二个问题：敲下一行命令之后，里面究竟发生了什么。

二、一次请求的旅程

还是上一篇那条命令：

1
2

pi -p "修复这个仓库里的 bug，让 npm test 全部通过" \
   --provider deepseek --model deepseek/deepseek-v4-flash

-p 是非交互模式，跑完就退出。按下回车之后，我们跟着这行字走一趟，看它每一步变成了什么。

2.1 它把 prompt 变成了什么

按下去之后的第一件事，是把上面那行字变成一份发给模型的东西。下面这份是真抓的：把 provider 地址指到本机一个假服务，让 pi 照常发请求，落在磁盘上的请求体原样抄下来。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

You are an expert coding assistant operating inside pi, a coding agent
  harness. You help users by reading files, executing commands, editing
  code, and writing new files.

Available tools:
- read: Read file contents
- bash: Execute bash commands (ls, grep, find, etc.)
- edit: Make precise file edits with exact text replacement, including
  multiple disjoint edits in one call
- write: Create or overwrite files

In addition to the tools above, you may have access to other custom tools
  depending on the project.

Guidelines:
- Use bash for file operations like ls, rg, find
- Use read to examine files instead of cat or sed.
- You can inspect PI_* environment variables for current model and session
  details.
- Use edit for precise changes (edits[].oldText must match exactly)
- When changing multiple separate locations in one file, use one edit call
  with multiple entries in edits[] instead of multiple edit calls
- Each edits[].oldText is matched against the original file, not after
  earlier edits are applied. Do not emit overlapping or nested edits. Merge
  nearby changes into one edit.
- Keep edits[].oldText as small as possible while still being unique in the
  file. Do not pad with large unchanged regions.
- Use write only for new files or complete rewrites.
- Be concise in your responses
- Show file paths clearly when working with files

Pi documentation (read only when the user asks about pi itself, its SDK,
  extensions, themes, skills, or TUI):
- Main documentation: <安装目录>/pi-coding-agent/README.md
- Additional docs: <安装目录>/pi-coding-agent/docs
- Examples: <安装目录>/pi-coding-agent/examples
  (extensions, custom tools, SDK)
- 另有 5 条说明，讲怎么顺着这些文档和交叉引用往下读（此处省略）
Current working directory: /tmp/demo-repo

就这么短。真实的提示词是 31 行、2600 个字符，其中工具清单占 4 行，行为准则占 10 行。

准则那一节，10 条里有 7 条是工具自己带上来的：read 要求“用我，别用 cat 和 sed”，edit 交代“多处改动用一次调用”，write 声明“只用于新文件或整篇重写”。剩下三条是框架补的——一条按当前装了哪些工具生成，一条要求回答简洁，一条要求写清文件路径。这一节不是 Pi 手写的。

剩下的绝大部分是路径，指向已安装包里的文档。这一点 4.2 还会再提，它是 Pi 最有趣的设计之一。

（为了页面上不横向滚动，上面这块长行按 76 列折过，安装路径换成了 <安装目录>；文档那一节原有 8 行，折成 4 行并标了省略。所以看着是 39 行，正文说的 31 行是原始行数。）

一份请求在 pi-ai 里叫 Context，只有三样东西：上面这段 system prompt、一份消息列表、一份工具 schema。此刻消息列表里只有一条：

1
2
3
4
5
6
7
8
9

[
  {
    "role": "user",
    "content": [
      { "type": "text", "text": "修复这个仓库里的 bug，让 npm test 全部通过" }
    ],
    "timestamp": 1789795481937
  }
]

模型能看到的除了历史，还有一份工具清单。coding-agent 内置的工具一共 8 个：read、bash、edit、write、grep、find、ls，外加一个可选、文档标注为 Windows 用的 powershell。默认激活的只有 read、bash、edit、write 四个。

工具 schema 也一样朴素。四个默认工具里，bash 真正的参数只有两个（type 和 required 是骨架，参数本体在 properties 里），一个必填、一个可选：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "type": "object",
  "required": ["command"],
  "properties": {
    "command": {
      "type": "string",
      "description": "Shell command to execute"
    },
    "timeout": {
      "type": "number",
      "description": "Timeout in seconds (optional, no default timeout)"
    }
  }
}

任意命令，没有白名单。这个“吓人”的细节先记下，4.3 会解释它为什么是故意的。

还有两个选择不好一眼带过。一个是没有 system 消息类型——系统提示是 Context 的独立字段，不混进历史，所以历史能原样存下来、原样续跑；另一个是这段提示词写死在代码里，本地拼装，不靠远程下发。

2.2 它怎么发出去

同一份东西，到了 DeepSeek 那边长这样。这是这一趟的第一次请求，也是最轻的一次：一个系统提示、一份工具清单、一条用户消息。除了 system 那句和工具描述用 ... 缩掉，其余逐字来自真实请求（工具清单里只留了 bash，实际是四个）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

POST https://api.deepseek.com/chat/completions

{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "system",
      "content": "You are an expert coding assistant operating inside pi, ..."
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "修复这个仓库里的 bug，让 npm test 全部通过"
        }
      ]
    }
  ],
  "stream": true,
  "stream_options": { "include_usage": true },
  "max_tokens": 384000,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "bash",
        "description": "Execute a bash command in the current ...",
        "parameters": {
          "type": "object", "required": ["command"],
          "properties": { "command": { "type": "string" } }
        },
        "strict": false
      }
    }
  ],
  "thinking": { "type": "enabled" },
  "reasoning_effort": "high"
}

形状先对一下。Pi 的 Context 还是三样东西：系统提示、消息列表、工具清单。到了这里，系统提示变成 messages 里的第一条 role: "system" 消息，工具清单每条都要套一层 function，用户那句话本来就是文本块数组（2.1 里那个形状），搬过来还是原样。名字和嵌套都换了，三样还是那三样。

这份报文里还缺一样东西：缓存标记，一个都没有。DeepSeek 的上下文缓存是自动的，前缀一样就命中，不用你标什么；换个协议就得手动打断点，第三章会讲。

请求发出去之后，回来的是一条统一的事件流：

1
2
3
4
5
6

start
 ├── text      → text_start / delta / end
 ├── thinking  → thinking_start / delta / end
 ├── toolcall  → toolcall_start / delta / end
 ├── done
 └── error

text、thinking、toolcall 各自展开成 start / delta / end，加上 start、done、error，一共 12 个变体。中间那三条各自成流，思考、正文、每个工具调用都有自己的增量。这个流容器既是 AsyncIterable，又承诺一个 result()：同一段流既能逐字渲染，也能等它给出最终消息。

2.3 模型开口要工具

流里出现了 toolcall 事件，意思是“我要执行 npm test”。控制权交回给 harness。

Pi 里一个回合（turn）的定义很干净：一次 assistant 响应，加上它引发的所有工具调用与结果。驱动它的 runLoop 是“双层 while”。它本身是模块私有函数，对外入口有四个：agentLoop / agentLoopContinue / runAgentLoop / runAgentLoopContinue。形状大致是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// 双层循环的形状（示意，省去错误处理与截断保护）
while (true) {                                    // 外层：follow-up
  let hasMoreToolCalls = true;
  while (hasMoreToolCalls) {                      // 内层
    const msg = await streamAssistantResponse(ctx, config); // think
    const calls = msg.content.filter((c) => c.type === "toolCall");

    if (calls.length === 0) break;                // 没有工具要调，内层结束

    const batch = await executeToolCalls(ctx, msg, config);  // act
    ctx.messages.push(...batch.messages);         // observe

    hasMoreToolCalls = !batch.terminate;          // 全员喊停才停
  }

  const followUps = await config.getFollowUpMessages?.() ?? [];
  if (followUps.length === 0) break;
}

内层那一圈就是 think、act、observe：让模型说一段，取出它想调的工具，执行完把结果写回上下文，再回到开头。外层只管一件事：这一圈走完，如果还有排队中的 follow-up，就带着新上下文再来一圈。

真实的 runLoop 有 118 行（packages/agent/src/agent-loop.ts:156-273），比上面这个形状多出来的部分几乎全是边界处理。那些分支平时不显眼，每一处却都对应一个真会踩到的坑：

1. 模型一直要工具，谁来踩刹车？ 循环里没有“跑到第 N 轮就停”这种保险丝，刹车被分散到三个地方：工具自己可以返回 terminate: true 说“我干完了”，宿主可以随时用 AbortSignal 打断它，扩展也可以拦下某个工具调用，顺手带上同一个 terminate 标记。读下来像是在说：什么时候该停，交给正在干活的那一层判断。至少循环自己没有替它们做这个主。
2. 一批工具里只有一个说“停”，算不算停？ 不算。要这一批全部返回 terminate: true，循环才跳过紧接着的那次模型调用。这个标记最典型的用法是收尾工具：官方示例里的 structured_output，模型最后调一次它把结果交出来，它标上 terminate: true，循环就此收工，省掉一次完整的模型往返。反过来，同一批里如果还混着一个普通工具（比如刚跑完 npm test），它的输出模型还没看过，这一批就不能停，得再问一轮。
3. 输出被截断，参数只剩半截，还执行吗？ 不执行。模型这次响应如果撞上了输出上限（stopReason 是 length），它吐出来的工具参数很可能是被腰斩的，Pi 把这批工具调用全部判错，让模型把参数重发一遍。宁可这一轮什么都不干，也不能拿着半截参数去改文件。

模型那句“我要跑 npm test”到了 Pi 这里，被记成一条 assistant 消息。harness 执行完命令，把输出记成一条工具结果消息。下一趟请求把这两条一起带上去：Pi 内部的消息列表从一条变成三条，到了报文里再加上 system，一共四条：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

"messages": [
  { "role": "system", "content": "You are an expert coding assistant ..." },
  {
    "role": "user",
    "content": [
      { "type": "text", "text": "修复这个仓库里的 bug，让 npm test 全部通过" }
    ]
  },
  {
    "role": "assistant", "content": null,
    "tool_calls": [
      {
        "id": "call_1", "type": "function",
        "function": {
          "name": "bash",
          "arguments": "{\"command\":\"npm test\"}"
        }
      }
    ],
    "reasoning_content": ""
  },
  { "role": "tool", "content": "3 failing", "tool_call_id": "call_1" }
]

有两处对着看更有意思。

模型要调工具这件事，翻译过去是 tool_calls 数组，而且参数是序列化好的 JSON 字符串，不是对象。Pi 内部那个 arguments 是 { command: "npm test" }，到了这里变成 "{\"command\":\"npm test\"}"。谁负责这一下转换，就是这一层的事，上一层的循环不用管。

工具结果到了这里自己占一个角色，role: "tool"，用 tool_call_id 指回原来那次调用。换个协议就不一样了：在 Anthropic 那边，工具结果不能单独占角色，只能挂在一条 role: "user" 消息里。这套差异全在这一层消化掉，上一层的循环对此一无所知。

2.4 结果回到树上

这一趟只调了一个工具，真实的修复任务不会这么简单。上一篇文章那次任务里，模型和工具来回走了 6 轮，每一轮都在会话文件里留下记录。6 轮在文件里怎么排布，看文件本身最直接。

我让 Pi 真的写了一个会话文件。真实文件是每行一条记录的 JSONL：每条记录一层外壳，消息本体挂在外壳里。这一节只关心树怎么长出来，所以下面把外壳里与树无关的字段都收起来，只留每条的身份和它的父节点——被收起来的 usage 和 cost 后面还要回来交代，先放一放。完整文件长得多，下面这四条只是其中一段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// 第 1 行：header，整个文件只有这一条
{ "type": "session", "version": 3, "cwd": "/tmp/demo-repo",
  "id": "01a0b81f-b94f-7559-bfee-67609da12709" }

// 第 2 行 / m1：用户消息，parentId 为 null，所以它是根
{ "type": "message", "id": "a5c1c471", "parentId": null,
  "message": { /* 消息本体，形状同 2.1 */ } }

// 第 3 行 / m2：assistant，挂在 m1 下面
{ "type": "message", "id": "678f354f", "parentId": "a5c1c471",
  "message": { /* 消息本体：内容 + usage + cost */ } }

// 第 4 行 / m3：工具结果，挂在 m2 下面
{ "type": "message", "id": "423c01c8", "parentId": "678f354f",
  "message": { /* 消息本体：工具输出 */ } }

外壳里只剩 type、id、parentId 三样，但这棵树已经在里面了。

第一行是 header，之后每一行是一个 entry，每个 entry 都指向自己的 parentId，null 表示它是根。所以一个文件里天然长着一棵树，而不是一条线：

1
2
3

m1 ─ m2 ─ m3 ─┬─ m4 ─ m5   ← 叶子 A
              │
              └─ m6 ─ m7   ← 叶子 B

id 是 8 位 hex，比如 a5c1c471，只用来定位，不参与语义。被收起来的 usage 挂在每条 assistant 记录上，缓存命中量是其中独立的一个字段——这次实录里是 cacheRead: 1080。这份文件是我用假模型在本地写的，所以 cost 全是 0、usage 里那几个数字也只是示意值，真实会话里会填上真金白银和真实计量。这一趟花了多少缓存，会话文件里就记着多少。

图里的 m1 到 m3 就是上面那三条记录，再往后是这次实录之外的部分。当前对话位置永远是树的某片叶子，我们刚才那 6 次工具调用，是在这棵树上走出的一条路径。想回到历史里的某个岔路口，那就是一次“切分支”。对应的命令有三个：

• /tree：查看整棵树，在文件内跳转、切换分支。
• /fork：选中某条 user 消息，把它之前的路径复制成一个新的会话文件，并把那条 prompt 放回输入框供我们改写。
• /clone：把当前分支复制到新文件。

这些文件就躺在 ~/.pi/agent/sessions/ 下，按工作目录分文件夹，而且是只追加的：entry 一旦写下就不能改也不能删，只有迁移旧格式时会整体重写一次。所以“重写历史”在 Pi 里不是修改，而是开新枝，就像 git 一样，历史不可变，想走另一条路就 branch。对 agent 来说这太重要了：我们 fork 出去让模型试一个激进方案，不满意，切回原来的叶子继续，两边的记忆都还在。

2.5 出错、插话、太长

真实的请求不会一路顺风。模型调用会遇到超时、报错和上下文溢出。

出错时的恢复原语叫 agent.continue()，注释写得很直白：

Continue an agent loop from the current context without adding a new message.Used for retries - context already has user message or tool results.

不加新消息，从当前上下文接着跑。产品层在它之上套了一层自动恢复：

1
2
3
4
5
6
7
8
9
10
11
12
13

可重试错误（过载 / 限流 / 5xx）
  → 指数退避重试：2s → 4s → 8s，至多 3 次

上下文溢出，且这一步的响应是失败的
  → 从 agent state 摘掉末尾那条失败的 assistant
  → 自动压缩，把历史折成摘要
  → continue() 接着跑，只给一次机会

上下文溢出，但响应本身正常结束了
  → 只压缩，不重试

上下文用量越过阈值
  → 只压缩，不重试

出错之外，还有两件事是往循环里追加输入，Pi 把它们做成了两个队列：

• steering（转向）：循环正在跑的时候想插一句话，投进 steer 队列，它会在当前工具执行完、模型下一次思考之前注入。
• follow-up（续尾）：循环已经决定要停了，补一句“顺便把测试也跑了”，投进 follow-up 队列，它会再多跑一轮。

一个插在“还在干活时”，一个插在“正要收工时”。这两种时机对应完全不同的体验，所以是两个队列，不是一个。

还有太长的时候。上下文快装不下时，一种常见做法是把最旧的几条消息丢掉。Pi 用摘要替换，而且原文一条不删地留在文件里：

1
2
3
4
5
6
7
8
9

会话文件（档案：一行都不删）
 m1  m2  m3  m4  m5  m6  m7  m8
 └───────┬───────┘  └────┬───┘
         │                │
    compaction          保留的原文
     摘要 entry        （keepRecent）
         │                │
         ▼                ▼
模型输入 [ 摘要 ][ m6 m7 ][ 新消息 ]

触发条件是一行公式：上下文估算的 token 超过“窗口减去预留量”。这个预留量的默认值是 16384，留给提示词和模型回复。切点则用另一个数，20000，表示压缩后至少要保留的近期内容预算。两者分工不同：一个管什么时候压，一个管压到哪儿。切点有一个硬规矩，绝不允许切在工具结果上，否则模型会看到“调了工具却没结果”。

至于那批被摘要覆盖掉的旧消息，一条都没有删。它们只是不再进模型窗口，永远留在文件里，用 /tree 跳回去还能看到原文。

2.6 这一趟的证据

讲到这里，你可能会问：这些机制，我怎么确认它们真的在跑？

Pi 自己给了一个办法。它内置了一个 faux provider（packages/ai/src/providers/faux.ts，共 708 行），一个零网络的假模型：把调用方排队的响应脚本，按真实的 delta 事件流吐出来。它能限速来模拟慢模型，也能模拟 abort 和 deferred 异步响应，甚至能按 sessionId 前缀命中来仿真 prompt cache 的读写。

1
2

npm i @earendil-works/pi-ai@0.85.1
node faux-demo.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// faux-demo.mjs
import {
  fauxAssistantMessage, fauxText, fauxThinking, fauxToolCall,
} from "@earendil-works/pi-ai";
import { registerFauxProvider, streamSimple }
  from "@earendil-works/pi-ai/compat";

const faux = registerFauxProvider({
  models: [{ id: "faux-1", contextWindow: 100000 }],
});
faux.setResponses([fauxAssistantMessage([
  fauxThinking("先看看工作目录里有什么，再决定改哪个文件。"),
  fauxText("我先列一下目录。"),
  fauxToolCall("bash", { command: "ls -la" }, { id: "call_1" }),
], { stopReason: "toolUse" })]);

const stream = streamSimple(faux.getModel(), {
  systemPrompt: "You are an expert coding assistant operating inside pi.",
  messages: [
    { role: "user", content: "帮我看看这个目录", timestamp: Date.now() },
  ],
  tools: [
    { name: "bash", description: "Run a shell command", parameters: {} },
  ],
});

const seen = [];
for await (const ev of stream) {
  seen.push(ev.type);
  const payload = ev.type.endsWith("_delta") ? JSON.stringify(ev.delta) : "";
  console.log(ev.type, payload);
}
console.log(`共 ${seen.length} 个事件，事件类型种类 ${new Set(seen).size}`);
const final = await stream.result();
console.log(final.stopReason, final.content.map((c) => c.type).join(", "));

跑起来是这样（GIF 是真实终端输出录的，不是手绘）：

控制台里的原始输出（Node 24，2026-09-19）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

event  start
event  thinking_start
event  thinking_delta   "先看看工作目录里有什么，再决定改"
event  thinking_delta   "哪个文件。"
event  thinking_end
event  text_start
event  text_delta       "我先列一下目录。"
event  text_end
event  toolcall_start
event  toolcall_delta   "{\"command\":\"ls -"
event  toolcall_delta   "la\"}"
event  toolcall_end
event  done             stopReason=toolUse

共 13 个事件，事件类型种类 11
toolUse  thinking, text, toolCall

delta 是按 token 块切的，所以一句话会被切成几段，逐字渲染靠的就是这个。事件类型一共 12 种，这一趟没出现 error，所以最后那行只数到 11 种。

（faux 的切块大小是随机取的，所以每次跑出来的条数和切分点都略有不同，上面这份是其中一次。）

这件事看着小，却是工程上的分水岭：当“模型”可以被一个确定性脚本替代，整个循环的测试就从碰运气变成了可复现。 上一篇文章里那个 9 秒的成绩是真实 API 跑出来的，但同样的路径可以拿 faux 反复走，不必再花钱。仓库的开发守则里写得很硬：packages/coding-agent/test/suite/ 这套回归测试只准用 faux，不许用真实 API key 和付费 token。

三、为什么它快

现在回到开头那张成绩单：9 秒，3375 个 token，0.00007 美元。便宜和快是两回事，背后的机制也不一样，分开看下。

3.1 缓存这本账

先说便宜。那 0.00007 美元。

很多模型 API 对上下文缓存计费。如果这次请求的前缀和之前某次完全相同，命中的那部分就按远低于正常输入的价格算。这个差价有多大，看 pi 自己模型清单里的数字最直接：flash 档的缓存读价和输入价分别是 0.0028 和 0.14 每百万 token，差了 50 倍。（清单是随包发布的快照，未必等于官方页当下的挂牌价，但量级的一致性是它成立的前提。）

所以 harness 的功课很像前端压榨 HTTP 缓存：让请求前缀尽量稳定。能命中的，永远是“从头开始、一字不差的那一段”：

1
2
3
4

两次请求的前缀：
[tools][sys][u1][call][result1]
[tools][sys][u1][call][result1][u2]
└─────── 前缀一字不差 ───────┘

Pi 在这件事上做的事分两类：一类让命中真的发生，一类让命中看得见。

能不能命中，前提是两次请求的前缀逐字节相同，所以下面这三条都在维护那个不变的前缀。

• 请求级的 cacheRetention 默认就是 "short"，也就是缓存默认开着。听着不起眼，但它是前提，关着的话后面两条都无从谈起。
• system prompt 是请求级顶层字段，每轮原样重发，工具集和插件不变时逐字节一致。所以最贵的那一段（系统提示加工具清单）永远不变，对话在它后面怎么长都不影响它。
• 打标记这件事，各家要求不一样，交给适配层去管。DeepSeek 这类是自动的，什么都不用标，前缀一样就命中（2.2 那份报文里一个缓存字段都没有，就是这个原因）。Anthropic 那类要手动打断点，标记打在哪儿、活多久，都得自己算。

手动打的那一套，看 Anthropic 最清楚。所谓断点，就是在请求体里标一个位置，等于告诉服务端：从开头到这里的内容请存下来，下次前缀一样就能直接复用。标记本身就是 cache_control，它出现在哪个块上，断点就在哪。它的值是 {"type": "ephemeral"}，ephemeral 是“临时的”，这是目前唯一的缓存类型，默认寿命 5 分钟，想延长到一小时要额外加 ttl: "1h"，写入按输入两倍计费。

OpenAI Responses 侧是另一套，靠一个缓存键，prompt_cache_key，把 sessionId 截到 64 字符。Fireworks 这类靠副本路由命中的，得加一个 session-affinity 头，让请求尽量落到同一个缓存副本上。harness 要做的不是挑一种，而是各家都照顾到。

让命中看得见的那一半在 usage 里：cacheRead 和 cacheWrite 是两个独立字段，成本按每家 provider 的缓存价单独算，连上面那种一小时缓存的写入按输入两倍计费，模型里也照样分开算。省了多少，账上明明白白。

上一篇文章实测里，Pi 的缓存命中率是 91% 到 93%。算一下：九成多的输入按 1/50 计价，剩下不到一成按原价，两项加起来约为完全未命中时的十分之一。缓存把输入这一项压掉了大约九成。

但 0.00007 美元不是缓存一家的功劳。那笔账里至少还有两件事：总额只有 3375 个 token，而且用的是最便宜的 Flash 档。缓存是其中最大的一项，不是全部。上一篇也交代过，成本是各工具自己上报的数值，只宜做量级参考。

缓存也不是纯赚的：读取便宜，写入要按输入价另算（Anthropic 是 1.25 倍）。所以一次性请求不值得缓存，Pi 会把它们的 cacheRetention 设成 "none"，写摘要那次调用就是。

3.2 不添乱

再说快。9 秒里有很大一部分是模型自己在想、加上那 6 次命令跑掉的时间，harness 替不了这个忙。它能做的是别往上添东西，而 Pi 在这点上克制得有点反常：

• 整个 system prompt 只有 2600 个字符，默认只挂 4 个工具，也就是 4 段 schema。这些东西每一轮都要原样重发，短一点，请求就轻一点。
• 一批工具默认并行执行。同一次模型响应里要调的几个工具会一起发出去，而不是排队一个个来。基准那一趟看不出这条省了多少，因为那 6 次调用大多是串的（跑测试、改、再跑测试）。
• 工具本身没有确认弹窗，该跑就跑。这里说的是工具层——第一次在一个带 .pi 资源（这个项目自己的扩展、提示词、技能）的目录里启动时，仍会有一次项目信任询问。

这几条都不是什么发明，说到底只是没有被加上去。而忍住不加，本身也是一个设计决定。

3.3 只重画变化的行

界面这一层也是同一路数。Pi 没有用现成的终端 UI 框架，自己写了一个 pi-tui：

1
2
3
4
5
6
7

重绘派：整块重写       Pi：只更新变化的行
┌────────────┐        ┌────────────┐
│  aaaaa     │        │  aaaaa     │
│  bbbbb     │        │  bbbbb     │  ← 没变
│  ccccc     │        │  CCCCC     │  ← 只发这行
│  dddddd    │        │  dddddd    │
└────────────┘        └────────────┘

严格说它是区间语义：每帧先全量重算出整个行数组，再求出第一处和最后一处变化的行，中间没变的也跟着这一段一起写出去。只变一行时，才是图里画的最省情形。配合 CSI 2026 同步输出，终端先把一整帧攒齐再一次渲染，杜绝半帧闪烁。

这和 3.1 那笔账是一回事的两面：把会变的部分和不会变的部分分开处理——缓存盯的是请求前缀，尽量让它不变；渲染盯的是屏幕，只把变了的行发出去。

作者是游戏圈出身（libGDX 的作者），这套做法直接来自游戏渲染管线。仓库里还有个用它跑 DOOM 的示例，在 overlay 里以 35 FPS 实时渲染，算是这套思路的一个旁证。

四、它到底做对了什么

拆到这里，可以说结论了。三件事，一件比一件反直觉。

4.1 循环是个函数

前端的发展史告诉我们：“框架”替我们决定控制流，“库”把控制流还给我们。 jQuery 是库，Angular 是框架，React 一度被争论到底算哪个。

Pi 把这条审美写进了产品 README（packages/coding-agent/README.md）：

Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals.

翻译过来是：让 Pi 适应你的工作流，而不是让你去适应它，而且你不需要 fork 它的源码就能做到。

很多 coding agent 把循环藏在产品内部，你能调用的是它的命令行或者界面，循环本身不对外。Pi 是“库”，agent 循环是一个可以 import 进自己程序的 async 函数。CLI、批处理、RPC、SDK，都只是这个函数的不同宿主。

看完第二章那一趟旅程，你会发现这有多实在：那套 runLoop 不认终端，不认 stdin，也不认任何界面。它只认一个 Context 和一份配置。所以它今天能跑在 CLI 里，明天就能跑在别人的 IDE 里。

同一个内核对外有四种出口：交互式 TUI，一次性的 print 模式（可以选 JSON 事件流），跑在 stdin/stdout 上的 RPC 协议（给非 Node 的编辑器集成用），以及 SDK。同一个循环，四个出口，无数种驾驶舱。

4.2 把一切做成数据

会话是数据，所以可以 fork。压缩记录是数据，所以旧消息一条不丢。token 和缓存是消息上的一等字段，所以成本全程透明。

前端工程师对这套东西不陌生：它就是不可变状态加时间旅行调试——把状态的变化存成数据，把回到过去变成一次指针操作。

Pi 把说明书也放进了模型够得着的地方：系统提示词里给了三个指向已安装包内 README、docs、examples 的路径，并写明只在用户问起 Pi 本身时才读。意思是你可以直接问它“你自己是怎么工作的”，它会翻开自己的说明书作答。

仓库 README 里有一句自我介绍：

This is the home of the Pi agent harness project including our self extensible coding agent.

“self extensible” 是它给自己贴的标签，而且贴得住。仓库根目录的 .pi/ 里就是它自己用的扩展、提示词和技能，它拿自己开发自己。

4.3 敢不做

Pi 的产品 README 里有一节叫 Philosophy，通篇是一个接一个的“No”，而且一个比一个反直觉：不做 MCP（不接外部工具与数据源那套协议），不做子代理（不派生分身去干活），不做权限弹窗，不做计划模式（不先出方案再动手），不做内置待办清单，不做后台 bash（不把命令丢到后台慢慢跑）。

第 2.1 节那个没有白名单的 bash，就是这条清单最直接的样子。它不替你判断哪条命令危险，只负责把命令原样交给 shell。

官网首页给这套减法起了个名字，叫 “Primitives, not features”。直译是“原语，而非功能”，也就是这篇文章标题里“积木，而非成品”的出处。

最容易被误解的是“不做权限”。它的理由写得很清楚：

Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it.

安全文档里说得更绝：

Real isolation needs to come from the operating system or a virtualization/container boundary.

它的论证是：一个进程内的半吊子沙箱，容易被误当成真正的安全边界，因为它自己还得依赖宿主 shell、文件系统、包管理器和凭证。所以与其给一个让人误以为安全的假边界，不如明说没有边界，边界请到操作系统或容器层面去画。

它给出的安全方案在进程外面：

1
2
3
4
5
6
7
8

┌─────────────────────────────────────────┐
│  pi-ai / pi-agent-core / pi-coding-agent │
└────────────────────┬────────────────────┘
                     │ Pi 核心以你的用户权限运行
                     │ 想要更强的边界？套一层壳
       ┌─────────────┼─────────────┐
       ▼             ▼             ▼
   Gondolin       纯 Docker    OpenShell

这几种边界都不在 Pi 里面，来源各不相同，隔离范围也不一样（官方文档列了四种，除了下面三个还有 Docker Sandboxes）：

这条清单的说法一直在调。2025 年 11 月这一节叫 “Security (YOLO by default)”，12 月 9 日改成 “No Permission System (YOLO Mode)”，八天之后整节被删，只剩一句 “No permission popups. Security theater.”。那句“安全表演”自己也没留住——2026 年 1 月底被删，今天同一条换成了“要么进容器，要么自己拿扩展拼一套确认流程”。严肃表述是 2026 年 6 月才补上的。立场没变，措辞一直在变。

不做权限弹窗，那想要权限系统的人怎么办？自己拼一个。扩展系统里有现成的样板：permission-gate.ts 拦危险命令并弹确认，protected-paths.ts 保护 .env 和 .git。照 permission-gate.ts 抄一个自己的权限门，大概二十分钟的事。这就是“积木，而非成品”的注脚。

不做的东西由谁来补？官方给的第一层是样板：examples/extensions/ 里就躺着子代理、计划模式、待办清单这些现成例子，只是不装进核心。钩子也给得足，ExtensionAPI 一共 36 个事件，从输入到回合起止、压缩之前都有挂载点，日常用得上的四个就够：拦个工具、加个命令、改改提示词、压缩前插一手。

再往外一层才是生态：npm 上每一层都能单独装，别人完全可以只取一层去拼自己的东西；官方不做的能力由第三方补上，连公开的会话数据集、第三方解读和教学仓库都已经有了。本篇参考里那几条，就是这份生态地图的入口。

3.3 里那个自研的 pi-tui 也是这条清单的产物。现成的终端框架不是没有，但要按自己的方式渲染，就只能自己写。

结语

先把拆开的东西收进一张表，方便和上一篇那套“五件套”对照：

一年时间，三个包长到十一个，每一层都是被需求催出来的，所以多数层能单独拿走；会话、分支、压缩、缓存全是数据，所以历史能被 fork、被摘要、被续跑；别人标配的功能它一个不做，把工作流那一层的决定权留给我们自己拼。

这三件事指向同一句话：工作流那一层，它不替你做决定。 官网首页那句 “Primitives, not features”，还有那个曾经叫 shittycodingagent.ai 的域名，说的都是这件事。

当然，默认值还是它替你选的。默认只开四个工具，压缩的两个阈值默认 16384 和 20000，项目信任默认要问一句。它让出来的不是“从不做选择”，而是“选择可以被改”。这两件事不一样，前面几章的例子也只在说后一件。

它当然不是给所有人准备的。如果你要的是开箱即用的安全与周全，Claude Code 们更合适。但如果你想亲手掌控自己那副鞍具的每一颗螺丝，Pi 是这个品类里把选择权还回来还得最彻底的一个。上一篇文章结尾我说“马是谁不重要了，重要的是鞍具合不合手”，这篇的结尾想补一句：最好的鞍具，是你随时能拆开、能续上、还能请马自己讲讲它怎么跑的那一副。

还有一件正文没展开的事。第一章那张表里的 server、protocol、client 三个包，加上它们都依赖的 chord 运行时（chord 本身是个独立的插件组装框架，不依赖任何 Pi 包），是正在成型的另一套运行时：它把 agent 循环从进程内的函数，改造成可以落盘、可以跨进程接续的服务，目标是一个会话能被多个客户端同时接进来。这套东西目前只在 coding-agent 的 experimental/ 路线里，官方文档把它标成 development-only，要 PI_EXPERIMENTAL=1 才启用，默认 CLI 走的仍是经典架构。写这篇文章时它的定位是演进方向，不是当前行为。

想亲自上手验证这篇里的论断，最快的一条路是：装上 Pi，把官方 examples/extensions/ 目录翻一遍，照着抄一个自己的扩展，再跑一次 2.6 节那段 faux demo。这比读十篇解剖文章都管用。别忘了上篇的提醒：给工具用独立的目录副本，别让它们互相剧透。

该警惕的地方

1. 没有内置权限就是安全自负。这是设计，也是风险：让 Pi 在我们不完全信任的目录上裸奔，等于让任意提示词驱动我们的 shell。它的安全文档自己也认这一点：仓库文件、注释、文档、上下文文件、构建产物里的提示词注入属于本地 agent 的预期风险，“cannot be reliably prevented by pi”，Pi 只把你本人和 Pi 进程当同一个信任边界。在共享机器、CI、处理敏感数据时，先套壳。（顺带一提，它确实修过一个本地提权问题，CVE-2026-54328，影响 0.74.0 至 0.78.0，0.78.1 修掉；这个和权限模型无关，成因是临时扩展目录可预测。）
2. 版本与文档有代差。经典 API 和新 harness 并存，教学材料往往只讲其一。写代码、看文档前先确认自己在哪一代上。
3. “不做 MCP、不做子代理、不做计划模式”的取舍不是免费的。这些能力要么靠社区包补，要么得自己写。对开箱即用党来说，它比 Claude Code 这类工具糙不少。
4. 仓库默认自动关闭新贡献者的 issue 和 PR，维护者每日人工复查。项目红火但门槛不低，别被拒了一次就以为是在针对自己。

彩蛋

2026 年 1 月，Pi 的官网长这样：

Wayback Machine 对 shittycodingagent.ai 的存档，抓取时间 2026-01-09

那句 “There are many shitty coding agents, but this one is mine” 是冲着美国海军陆战队的步枪手誓词（Rifleman’s Creed）来的。原话是 “This is my rifle. There are many like it, but this one is mine”，《全金属外壳》里新兵齐声念的就是它。翻译过来大概是：烂编码 agent 有很多，但这一个是我的。

安装命令里还留着当时的 scope，@mariozechner/pi-coding-agent，包名后来才挪到 @earendil-works 下。

三个月后，README 顶上那个指向 shittycodingagent.ai 的 logo 链接被换成了 pi.dev。动手的那次提交，message 写的是 “feat(branding): corporate said we’re professionals”，意思是公司说我们得专业一点，提交人是 Armin Ronacher。pi.dev 这个域名是 exe.dev 友情捐赠的，致谢至今还写在 README 页脚里。

那个老域名今天还活着，访问它会 301 跳到 pi.dev。存档页显示这段历史一共有 38 次抓取，跨度从 2025 年 12 月 17 日到 2026 年 9 月 14 日。

一个敢把自己官网叫“烂编码 agent”的项目，大概也配得上“克制”这两个字。

参考

• 仓库：earendil-works/pi（pi.dev 官网与文档）
• 作者博客：《What I learned building an opinionated and minimal coding agent》、《What if you don’t need MCP at all?》
• 我上一篇的横评：《给大脑配一副好鞍具：五款 Agent Harness 的解剖与实测》（复现实测用同一提示词即可，命令见其附录）
• 中文教学仓库：cellinlab/how-pi-agent-works
• 第三方解读：walkinglabs 的 harness 工程设计系列（Pi 篇）
• 真实会话数据集：badlogicgames/pi-mono on Hugging Face

版本与核实说明：本文基于仓库 HEAD 9767ba2（各包版本 0.85.1，2026-09-06 抓取）撰写，演进时间线里的日期与 commit 均取自仓库 git 历史，可按 commit 复核。版本号与生态数据随时间变化，引用请以当时为准。文中实跑的证据（faux 输出、会话文件）产生于 2026-09-19，比基于 HEAD 9767ba2 的源码核对晚两周，是为了让它们和这一版正文对齐才重新跑的。文中的 faux 事件流 demo 是实跑输出（Node 24 + @earendil-works/pi-ai@0.85.1），不是手写示意。掌故类内容（名字来历、YOLO Mode、域名变更）同样按 git 历史核验，其中域名那条重定向在浏览器里可以直接复现。

按理说不该这样。同一件工具、同一类任务，所有人都能用；工具对每个人是公平的。那差额是从哪来的？

我的答案是：来自我们怎么解释自己的处境。

说得再直接一点：向内归因能解决更多问题。

这不是一句道德劝告，而是一个效率判断。同一个处境落到两个人手里，会向内归因的那个人，手里永远多出几个选项；而习惯向外归因的人，会先把选项一个个划掉，最后得出”我没什么可做的”。

这篇文章想说清三件事：为什么它在今天比过去更管用，怎么才算真正做好它，以及我自己就是它的受益者。

我看到的几种状态

先说让我决定写下这篇文章的那些事。

大部分人的产出都在往上走，但也有人原地踏步，个别甚至有所回落。我留意到的信号通常是这几样：不主动同步进展，一件事推一下动一下。坐下来聊原因，听到的说法大致是这几类：

• 没有工单就没办法开始开发，而且工单里的需求必须非常明确
• 决策都在美国那边，自己不在场，拿到的信息也不完整
• 受时差和协作方式的限制，重要的事情本来就轮不到自己；既然不重要，那也就不着急

这些说法单拎出来，每一条都不算离谱。但合在一起，就构成了一个完整的、自洽的、几乎无法反驳的世界模型：问题都在外面，我没什么可做的。

还有一类不满，是关于自己的发展速度，常见于两种处境：

一类是组织一直在动，汇报线换了几轮，投入很久的项目最后没能掀起什么水花，人会慢慢觉得使不上劲；一类是长期做支撑性、独立性较强的工作，这类工作不太容易被看见，身边的人陆续上去了，落差感就出来了。

前者容易滑向”很不爽，但也没办法”，后者容易滑向”这不公平”。两种情绪方向不同，落点却一样：都倾向于把问题放到外面去。

最后是一个反向的例子：也有人换过好几任老板，每个重点项目却都干得相当出色，非常主动，沟通到位，而且很自信。

不瞒你说，上面这几种状态，其实每个人身上都或多或少出现过，包括我自己。它们真正的分岔点，从来不在起点，而在每一个岔路口的选择：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

成长 / 产出
  ▲
  │                                          ╱ 换了好几任老板
  │                                       ╱     每个项目都出色
  │                                    ╱
  │                                 ╱ 补短板，重新往上走
  │                           ╱────╯
  │  ──────────────────────●
  │                        │╲
  │                        │ ╲ 很不爽但没办法
  │                        │  ╲───────────────  停在平台期
  │                        │   ╲
  │                        │    ╲ 归因于外 → 投入下降
  │                        │     ╲              → 产出下滑
  └────────────────────────┴──────────────────────────────► 时间
                        同一个起点

为什么这个时代它更管用

要理解这件事为什么现在格外重要，得先看清 AI 到底改变了什么。

过去，一个想法从”看到问题”到”做出来”之间，隔着几周甚至几个月的实现成本。所以大部分时候，你能做什么不取决于你看到了什么，而取决于有没有人批准、有没有排期、有没有资源。

AI 很大程度上拆掉了这道墙。实现成本被压下去之后，”我先试一版”第一次变成了一个人可以自己决定的事。

所以 AI 给个人带来的最大变化不是”更快”，是”更自由”：你第一次可以不太依赖授权，直接去解决你看到的真问题。

这也意味着，向外归因的理由在变弱。以前”没人给我工单，所以我做不了”是真的，因为成本摆在那儿；现在不是了。

同一件工具落到不同的人手里，走向完全不同：

所以在当下这个阶段，有几件事的回报率被显著抬高了：

• 主观能动性：工具把动手成本压得很低，”我先做一版试试”变得空前便宜；而”等条件齐全再动手”的相对成本就变高了
• 积极沟通：当每个人都能更快产出时，瓶颈就从”做得出来”移到了”知道该做什么”，信息差成了主要矛盾，主动同步的价值因此上升
• 判断力：工具能帮你实现方案，但”这个方案该不该做””这段代码能不能进生产”仍然只能由人判断。被贬值的是打字，升值的是取舍
• 面向业务价值的取向：既然”做出来”变容易了，那”做什么值得做”就成了更稀缺的能力

反过来讲，这也意味着停滞的代价变高了。以前”按部就班、不出错”是一种安全策略；现在它变成了一个相对落后的策略：因为你身边的人正在被同一件工具加速。

为什么外归因会把选项关掉

外归因和向内归因不是我的发明。Rotter 在 1966 年提出”控制点”（Locus of Control）：内控型的人倾向于认为结果取决于自己的行为，外控型倾向于认为取决于运气、环境和他人。

这个区分最有价值的地方，是它能预测下一步行动。如果你认定问题在外面，逻辑上的必然结论就是”我无需改变”。短期内也的确舒服，它保护了自尊，也省去了面对自身短板的痛苦。但代价是长久的：你把自己人生的遥控器交了出去。

有一句总结我很认同，讲得很扎心：

外归因最省力：出事先找替罪羊，过错全推给外界，短期心理平衡，不用跟自己的短处较劲。但代价是永久丧失进化的可能——既然问题都在外面，自己自然无需改变。——知乎答主「起风了」

外归因有不少精巧的变体，不妨逐一拆开看，因为它们全都披着”客观陈述”的外衣。在《The Oz Principle》里，作者用”水平线”区分两种状态：线以上的人对结果负责，线以下的人则把精力用在推责上，比如”这不是我的工作”、指责他人、坐等指令、坐等观望。这些面孔和我下面要列的，倒也几乎一一对应。

第一种，「这不归我管」。没有工单就没法开发：流程确实有缺失，但从”缺一个工单”跳到”这件事做不了”，中间那个跳跃没有依据。

第二种，「我怎么会知道」。潜台词是：信息应该被分发给我。但在分布式团队里，信息不会自动落到每个人手上，要么自己去争，要么推到能建通道的人那里。

第三种，「反正不重要，那就不着急」。这是最危险的一种，因为它把外部的不可控，直接用来给自己的投入程度背书，于是形成一个自我实现的闭环：

1
2
3
4
5
6
7
8
9
10
11

① 觉得「重要的事反正轮不到自己」
     │
     │ 于是不全力投入
     ▼
② 确实拿不出重要产出
     │
     │ 于是更确信
     ▼
③ 更确信「轮不到自己」
     │
     └────────────────► 回到 ①，闭环成立

这个闭环一旦形成，别人再想给机会也接不住了。它和”时差”没有关系，这件事两边都有责任。后面我会专门说管理者的那一半。

第四种，「不公平」。这种要格外小心，因为它可能是真的。评价体系确实会青睐某些能力（比如沟通、跨部门影响力），而冷落另一些能力（比如把支撑性的服务做深做透），这对当事人来说确实构成结构性的不利。承认这一点，是讨论的前提。但关键在于，别卡在”不公平”这个结论上不动。这种委屈里其实藏着一道判断题，我在下一节说。

向内归因不是自责

写到这里得先泼一盆冷水，否则上面这些很容易被读成”凡事多反省自己”。

向内归因 ≠ 自责，更 ≠ 认命。 有三条边界必须守住：

1. 归因要尽量准确，而不是尽量向内。 内归因最大的陷阱，是把一个具体问题迅速升级为人格问题：不是”这次方案没写好”，而是”我天生就写不好方案”。久而久之，人就活成一台职场自责机器，能量全耗在自我否定上，反而没力气改进。这种”过度内归因”和外归因一样有害。在资深工程师身上它尤其隐蔽，经常伪装成”高标准”和”owner 意识”，所以特别难自查。
2. 归因 ≠ 归责。 向内归因的对象是”我能改变的那部分”，而不是”全部责任”。承认环境确实占了一部分、自己也占了一部分，然后专注在自己那一部分上。这不叫认领全部罪责，这叫找到着力点。
3. 向内归因不等于否认环境的约束。 有些外因是真实存在的，制度可能确实失衡。成熟的认知不做非黑即白的二元判断。先承认大环境的力量，再问一句：在这个约束之下，我还能做什么？

回到「不公平」那一种。

在选路之前，得先分清一件事：你遇到的到底是哪一种限制。

1. 假性瓶颈：它看起来像能力不足，其实界是自己划的。

   “我天生内向，这种要去说服别人的事我做不来。”“我英文不行，跨时区的讨论我就不掺和了。”

   这类话听起来像在陈述自己的短板，但它们往往是预测，不是结论。你还没试过，就先替自己判了。”我性格就是这样”本身也是一种外归因：它把结果归给了一个固定、不可改变的特质，而不是归给选择。

   这一种的解药不是”补短板”，是先去试一次。而且很多时候试完会发现：它没有想象中那么难，只是不太舒服罢了。

2. 真的通道瓶颈：路是通的，只是你缺一样东西才能走过去。

   比如技术很强但不会写方案、不会同步，贡献就没人看见；或者确实试过了，跟人打交道每次都很吃力、但能推进，只是还不熟练。这一类是可以补的，补了就有用。

3. 身份冲突：走通这条路的前提，是放弃自己最擅长、也最看重的那部分。

   试过了，也做成了，但每一次都像在扮演别人，做完了只剩消耗。那可能不是短板问题，而是这条路本身不适合你。

这三种用两个问题就能分开：

1. 我试过吗？ 没试过就认定”我不行”，那是第一种，先去试
2. 试过了：我是在增长，还是在磨损？ 在增长，哪怕不舒服，是第二种，值得补；只剩磨损，是第三种，该认真考虑换道

这里有一句不太讨喜的话，但我认为必须说：”我不想成为那种人”可以是最诚实的判断，也可以是最舒服的借口。两者的区别，只在于你有没有真的试过。

所以按这个分法，第一步是先试一次，把第一种和第二种分开，别急着选”补”还是”换”。分开之后，三条路都成立：

1. 补短板：认清体系看重什么，然后去补。这条路最省力，也确实有人正在这么走
2. 换赛道：清醒地判断”我不想成为那种人”，然后去一个真正看重自己优势的环境
3. 接受现状，但停止情绪消耗：承认代价，也接受代价

唯独”持续苦闷且不行动”不可取。前面那类不满里的两种走向，差别就在这里：同样是委屈，一种停在”不爽但没办法”，一种已经开始动了。时间会把这个差别无限放大。

你负责的任务，和你负责的问题

前面几节讲的，都是”在我认领的范围内，我能做什么”。这里我想把范围本身往外推一点：它不关于你怎么做事，而关于你认领多大的问题。

在工程师团队里，有个非常普遍的默认分工：PM 负责想清楚要做什么，工程师负责把它做出来。

于是大家习惯了让 PM 去定义方案、评估效果，自己专注在明确被要求的那一小部分。这样的团队里，一个人完全可以把开发任务做得很漂亮，但你要是问他：

• 这个功能到底在解决用户的什么痛点？
• 现在这个方案是不是最好的？有没有更简单的做法？
• 上线之后怎么迭代？下一版该动哪里？
• 效果评估怎么保证是准的？我们看的到底是不是真正的信号？

这几个问题问下来，他大概答不上来。不是能力不够，是这块地盘他从没认领过。

这就是”向外归因”最隐蔽的一种形式：把问题的定义权让出去，只保留执行权。 它不像”这不归我管”那么刺耳，因为它披着”专业分工”的外衣。

这正是向内归因在这个时代最该做的一个动作：把”我的问题”的边界往外推一点。

我见过真正优秀的人，做法几乎都一样：他们穿过自己的合作方，走到真实的使用场景里去。这里说的不是越过谁去替 PM 做调研。PRD 和项目讨论通常都是必要的起点，绝大多数人也都是从那里开始的。区别在拿到之后：停在文档上就只是执行，而他们会拿这份文档去对照真实场景，想想这个功能到底在解决谁的什么痛点、有没有更简单的做法，再带着自己的判断回来跟 PM 讨论。

问”这个为什么要做”本身没有错，那是该问的；区别只在于问完之后，去不去找答案。

差别不在于谁更聪明，而在于谁认领的是一件事，谁认领的只是一个动作。

这件事在今天就更加要紧了。前面说过，AI 把”实现”的成本压得很低。那么”我只负责实现”这份分工的稀缺性，也就跟着变低了。工具能帮你把方案做出来，但”该做什么方案、做完怎么验证有效”仍然只能由人判断。判断的前提，是你真的到过现场。

说到这里得补一句：这道坎是真实存在的，我不想绕过去。这确实不是每个人都舒服做的事：工程师群体整体偏内敛，主动去找关键合作方聊，意味着要准备很多、要说服别人、有时还要正面辩论；如果是跨时区的团队，还得用一门不完全是母语的语言去完成这些事。这些都是实打实的成本。但也正因为它是成本、而不是不可能，才需要一个判断。

所以这道坎到底要不要迈，是个需要诚实面对自己的判断。它和前面「不公平」那种委屈，本质上是同一道题，用的也是同一套判据：试过了吗？是在增长，还是在磨损？

怎么做好向内归因

这是我最想说清楚的一节，因为它最容易被误解。

向内归因常被理解成”凡事都往自己身上揽”。恰恰相反，真正会向内归因的人，是外部因素识别得最清楚的人。 因为他要精确回答”我能动的那部分在哪”，就必须先把外部因素看准。反倒是外归因的人看得最粗：一句”环境不行”就把全部原因打了包。

所以第一步不是自责，是分拣：

三类的处理方式完全不同。把第三类当成第一类，会白白自责；把第一类当成第三类，会白白停摆。分拣错了，两个方向都要付代价。

注意中间那一类：识别出真外部因素之后的动作，不是认命，是找到能解决它的人，把这件事变成他的工单。这是一项能力，不是一句让步。”流程没人管”这件事，你完全可以主动写一版提案，推着把它变成某个人的待办。

然后是那条我自己一直在用的原则：看这件事做完之后，能不能留下可见的东西。

没工单的事其实有两类。一类会留下资产：一个新的方案、一套能复用的工具、一条被打通的流程、别人对你的信任。另一类什么也不留：救火、补位、替别人扛一段，做完之后没有任何沉淀，下次还得从头再来。这两类表面上都是”主动”，回报却完全相反。

所以我的界是：能留下可见的东西，就值得做；如果只是让你在没有权限的情况下反复替别人兜底，那就该把责任还回去，而不是自己扛。把”缺工单”无差别地当成个人执行力问题，是管理者的偷懒。

分拣完，我还会按可控性把这件事再摆一遍。这是从柯维的关注圈（我关心但控制不了的事）和影响圈（我能实际施加影响的事）那儿借来的，只是我又拆细了一档：

这一步最常见的错误，是把前两种当成了第三种。

几个门槛最低、收益最实在的动作，我自己一直在用：

1. 做一次语言转换。 外归因有非常明显的语言特征：”都是因为……”、”如果不是他……”、”这个公司就是……”。内归因的特征同样鲜明：”在这件事里，我的责任是什么？”、”我能从中学到什么？”、”在我能控制的范围里，我能先做哪一件事？”不用强迫自己改变想法，先改变造句方式就行。语言会倒逼思维。
2. 主动同步。 每周更新一次进展、卡点和下一步，写下遇到的困难，也写下你打算怎么处理。在分布式团队里，可见度本身就是产出的一部分。很多人把汇报当负担，其实它是最低成本的存在感投资。
3. 从约束里挑一件小事做完。 不要等条件齐全才动手。缺工单，就先写一版草稿需求；跨时区信息拿不到，就主动去找参与过前序讨论的人把背景补齐，或者先把整理好的已知信息发出去请人补充。完成一件小事带来的信任额度，比十次抱怨管用。
4. 每个季度做一次”工单审计”。 回头数一数：过去三个月我做的事里，有多少是别人派的，有多少是我自己找的？这个数字很粗糙，但它是唯一能衡量的东西：衡量你还在积累资产，还是只是在原地执行。
5. 重要任务要争取，不要等。 这类事很少是被分配的，绝大多数得靠自己争取。争取的方式是先做一件超出预期的小事，换来一点信任额度，再靠它去拿更大的机会。
6. 把锚点放在成果上，别放在某个人身上。 老板会走，你在流程文档、项目成果、可迁移能力上留下的痕迹不会走。

同一个问题，两种视角

“向内归因”在 IC 和管理者身上，含义其实不一样。

作为 IC，它是问：在我能动的范围里，我能做什么？ 把手上的事做到超出预期、主动同步、从约束里挑一件小事先做完。

作为管理者，它是问：他的卡点里，有多少是我造成的？ 需求有没有人转成工单？跨时区的信息通道我建了没有？派活时我有没有偏好，把某些人一直留在很难被看见的位置上？

这中间没有互相免责，而是各自把自己那一半认下来。

而且这里还有一个常被忽略的区分：有一类”外归因”根本不是态度问题，而是习得性无助。 塞利格曼的经典实验说明，当一个个体反复经历”无论怎么努力都无法改变结果”之后，他会彻底放弃尝试。哪怕后来环境变了、机会来了，他也不动了。

放到职场里就很清楚了：如果他主动提的方案被驳回、多做的额外工作没被看见、出了问题还要独自担责，那么”不主动”就是他学到的、最理性的自我保护。这一类不是靠讲道理能谈通的，你需要先给他一次完整的正向闭环：主动 → 被看见 → 有回报。

但同情环境不能变成免检。要先把卡点拆开，因为对策完全不同：

1
2
3
4
5
6
7
8

                 他没产出，看是哪一类卡点
                             │
     ┌─────────────────┬─────┴───────────┬─────────────┐
     ▼                 ▼                 ▼             ▼
 能力不够          意愿不足          信息不够      资源不够
培训 / 结对      谈动机与期望        补上下文       给资源
 调整岗位       胜任感 · 自主性     建信息通道      清障碍
                    归属感

其中「意愿不足」这一类，自我决定理论说得最清楚：胜任感（我做得了吗）、自主性（这是我的选择吗）、归属感（我和团队有关系吗），三者缺一不可。

然后是坐下来开口。上面这些都还是原则，真正难的是那场谈话。我自己试过有用的一组问题，思路只有一条：把”你为什么不主动”换成具体的提问。

• 最近哪件事让你觉得卡住了？当时你想做什么？
• 你试过什么？结果怎么样？
• 如果这件事由你定，你会怎么排优先级？
• 我能帮你清掉哪个障碍？

这组问题的用意很实在：把一次关于态度的审判，变成一次关于障碍的共谋。

至于”试多久算够”，我的做法是先把环境侧的三件事做完：流程（工单该谁负责）、信息（跨时区通道）、机会（派活有没有偏好）。这三件事都有明确的负责人，也就是我。然后给一个明确的观察周期，我的经验是一个季度。

这个顺序不能颠倒。先修环境再谈人，不是因为管理者要宽容，而是因为不这样做，你根本分不清问题在人还是在环境。

如果都做过了，一个人依然把所有结果归于外部，既不沟通也不改善，那这就是一个需要直面的绩效问题了。原因很简单：团队里其他人看得见。我在 Fire Fast 里写过一句话：”容忍低绩效者是对大多数人的惩罚”。同样地，如果一个团队慢慢默认了”归因于外是可以被接受的”，这种默认会像传染病一样稀释掉整个团队的进取心。这比某一个人的产出下滑要严重得多。

这一节和 Just Culture 里那件事是同一个道理：出了状况，先问”哪里出了问题”，而不是”谁出了问题”。

我见过的那些发展比较快的人

前面讲的多半是停滞的样子，我想再说说另一面。这一面我看到的样本更多，也更稳定。

这些年我见过不少发展得比较快的人，他们的背景、方向、路径各不相同，但有一些共同点几乎反复出现：他们不等指令，主动同步，敢把不确定的事接过来。

项目做到一半黄了，他们的第一反应是”还剩什么能做”，而不是”这不是我的问题”；老板换了，他们先去摸清新老板在意什么，而不是先抱怨又要重来；遇到没人认领的空白地带，他们倾向于先占住，而不是先问这归谁管。

最极端的一个例子，是那位换过好几任老板的同事。每一任的风格、偏好、考核重点都不一样，按前面那些逻辑，他完全有理由抱怨：新老板上来就推翻旧方案，努力反复被打回，站队风险极高。但他没有。每一任老板到岗，他主动同步现状、风险和待决策事项；不管怎么换，他手上的重点项目永远做到超出预期。

于是他的履历上写的不是”我服务过好几位老板”，而是”我做成过 N 件事”。老板会走，成果不会走。

我把这些共同点归纳成三条，它们其实都是”向内”的外显：

• 主动 是”不等指令”，是自己给自己下工单
• 沟通好 是主动缩小信息差，主动管理对方的预期，而不是等对方来问
• 稳定 是一种”我能把事情推进下去”的预期。它看起来像天赋，但我更愿意把它看成前两条的副产品：主动同步带来更快的反馈，更快的反馈让判断更准，判断更准就更容易做成事。做成的事多了，预期自然就稳了

德鲁克在《卓有成效的管理者》里反复强调一件事：知识工作者必须自己管理自己，必须不断问自己”我能贡献什么”。当一个人把目光从”老板是谁”移开，转向”我贡献了什么”，他就获得了某种任何人事变动都夺不走的东西。

我知道这套观察会被这样反驳：样本太小、因果可能是反的、有人就是靠亮点项目和顺风局上来的、评价体系本身也未必公平。这四条我都认。

但它们全都成立，也不影响我的结论。因为我不是在论证”向内归因必然带来晋升”，那个我证明不了。我说的是：面对同一个处境，向内归因的人手里会多出几个选项。 这一条不需要因果论证，你回头翻一翻自己的经历就能验证。

我自己就是受益者

最后说说我自己，因为我大概是这篇文章最直接的样本。

这一路走得还算顺。回头看我做成的那些事：把播放方案重写一遍、接上 DRM、搭起监控、写一个让原生容器更好用的 JS bridge、做一套调试工具。没有一件是别人派给我的工单。都是我先看到问题，然后自己去填那块空白。

更典型的是”让国内团队和美国的资深管理者真正协作起来”这件事。它更不会有人给我开工单，而且一点都不轻松。我自己在介绍里写过一句：这件事难得超出预期。

当然，我也赶上了顺风。我加入现在公司的时候，国内团队刚刚成立，不过业务发展得不错。等老板们发现国内工程师质量高、性价比好，就开始逐渐扩大规模。后来的很多机会，确实也是这种扩张本身创造出来的。在前东家，我也赶上了团购外卖行业蓬勃发展的几年，从一个刚刚毕业的萌新逐渐成为技术管理者，推动了不少事情。

但顺风解释的是”机会为什么出现”，解释不了”机会出现时我接没接住”。 同一个位置上换个人，结果不会一样。

所以我是向内归因的受益者，而且我不打算假装这只是运气。

结语

回到开头那个反直觉的现象：AI 把每个人的产出杠杆都放大了，差距反而在拉大。

我现在很确定，差距的主要来源不是”会不会写代码”，而是你怎么解释自己的处境，以及你因此做了什么。工具可以让一个主动的人产出翻倍，也可以让一个被动的人继续原地不动。它只是放大了你原本的样子。

归因方式不是道德评价。向内归因的人并不比向外归因的人更高尚，这只是一个效率问题：它决定你把有限的精力投向哪里。

它最终给你的回报，也不只是升职加薪。向内归因真正让人获得的东西是：无论环境怎么变，你手里始终有得选。

这些话我只能说对自己管用，未必对别人也一样。如果对你也还算是有所启发，那就是额外的大收益了。

参考文献

• Locus of Control - Wikipedia
• Learned Helplessness - Wikipedia
• Habit 1: Be Proactive - FranklinCovey
• Understanding the Circle of Influence and the Circle of Concern
• The Oz Principle: Getting Results Through Individual and Organizational Accountability
• 什么是顶级的思维？- 知乎答主「起风了」
• 在单位感到委屈和不公平，是时候改变”归因模式”了
• 职场人最该戒掉的认知：过度反思自己
• 同事升职了你没升：把”凭什么是他”换成”我缺什么”

邓小平在《党和国家领导制度的改革》里说过一段很重的话：

我们过去发生的各种错误，固然与某些领导人的思想、作风有关，但是组织制度、工作制度方面的问题更重要。这些方面的制度好可以使坏人无法任意横行，制度不好可以使好人无法充分做好事，甚至会走向反面。

这段话虽然是针对国家治理讲的，放到组织管理里同样成立。好的制度设计，能够最大限度释放生产力、优化资源配置；坏的制度设计，则会让好人做不了好事。 这篇文章想把我这些年读到、听到、实践过的一些制度案例整理成六个原则。案例尽量真实可查，文末附有出处，供大家批判性参考。

原则一：让规则的制定者承担后果 —— 分金的人最后拿

先说一个最经典的设计。

一伙强盗分金子，如果规定”负责分金的人最后一个拿”，会发生什么？很简单：为了自己不亏，分金的人只能尽可能把金子分得均匀。这里不需要任何监督、任何道德说教，规则本身就让分配者”不得不公平”。管理上有一个同款的老故事叫”七人分粥”：七个人分一锅粥，轮流分、轮流挑，怎么分都有人觉得不公平，最后采用的方案是”轮流分粥，但分粥的人要等别人先挑完、拿最后剩下的那份”——从此再没有人抱怨。

（注：这里说的”分金的人最后拿”，和博弈论里著名的”海盗分金”问题不是一回事。后者是五个海盗按”提案+投票”规则分 100 枚金币的逆向归纳题，标准解里提案者独得 98 枚——因为它只需各花 1 枚金币买通两名关键支持者，就能以多数票通过提案。同一个”分金”场景，只因为规则细节不同（谁提案、投票门槛多高、顺序怎么排），结果天差地别：制度细节即命运。）

这套思想在学术上叫机制设计（Mechanism Design）——经济学里研究”如何设计规则，让参与者在追求个人利益的同时，恰好达成设计者想要的结果”的一个分支，核心概念是激励相容（Incentive Compatibility）：把规则设计成”个人怎么做对自己最有利，恰好也是组织希望他做的”，就不需要外部监督。机制设计的奠基人之一、2007 年诺贝尔经济学奖得主马斯金（Eric Maskin），2019 年到访海尔时讲解这门理论，用的第一个例子就是”分蛋糕”——怎么保证两个孩子都觉得分到的蛋糕不比对方小，标准答案正是”切的人最后拿”（新浪财经）。连诺奖得主讲机制设计都要从”分蛋糕”讲起，可见这个朴素原则的分量。

落到日常管理上，我自己的体会是：凡是涉及分配的场景，都值得问一句——**”定规则的人，自己最后拿吗？”** 排班的人自己先上夜班、分活的人自己先挑硬骨头、定 KPI 的人自己先被这套 KPI 考核……把这些”对称性”写进规则，比任何动员讲话都管用。

原则二：让资源必须流动起来 —— 用完才能再拿

另一种常见病是”囤积”。资源一旦”抢到就是我的”，大家就会拼命多占、占着不用，等真正需要的人想用的时候已经没有了。要治这个病，最有效的设计是**”用完才能再拿”（use it or lose it）**。

最直观的例子在消费领域：迪士尼度假俱乐部（Disney Vacation Club）的积分采用”用进废退”规则，年度积分到期清零（仅允许有限次数的”存点”，且有严格限制，见 planDisney 官方解答），防止会员囤积积分造成旺季挤兑。有趣的是 Netflix 走了相反的路：干脆不设年假制度，想休就休——没有”攒假”的概念，自然也没有”囤假”和”突击休假”的问题。两种设计殊途同归：消灭囤积。

不过这类机制要小心设计：如果”用不完就收回”做得太粗暴——比如预算当年不用完就作废——反而会催生”年底突击花钱”式的浪费。防囤积的关键不是简单”过期作废”，而是”可以结转 + 按浪费问责”。

落到日常管理上：凡是”名额、预算、项目、人力”类资源，都值得设计一个”用不完就回收”的机制，否则一定会有人以囤积代替使用、用占有代替产出。

原则三：让创造价值的人分享价值 —— 分钱的制度

第三类优秀实践，是”分钱”的制度。

华为被研究最多的不是技术，而是它的价值分配体系，概括起来是三根支柱（华夏基石）：ESOP 虚拟受限股——员工按内部股价认购的虚拟股份，只有分红权和增值权、没有所有权，离职时由公司回购，让知识劳动者的长期贡献资本化；TUP 时间单位计划——按绩效免费授予、不花员工一分钱，让新人和外籍员工也能零门槛参与；饱和配股——按职级设定持股上限，防止老员工持股越积越多、躺平吃分红，给新人留出上升空间。创始人任正非个人持股长期只有约 1%，其余由员工持股平台持有；华为内部的原则是**”劳动回报优先于资本回报”**——分钱时先保证干活的人拿够，再谈资本收益。这套制度把成千上万的知识员工从”打工人”变成了”合伙人”。

三根支柱里最值得琢磨的是 TUP：公司根据你的绩效和贡献，白送你一批”分红收益权”，期限 5 年——第 1 年只确认额度，第 2 年解锁 1/3、第 3 年 2/3，第 4–5 年全额分红，第 5 年结算（当年分红 + 内部股价涨幅对应的增值收益）后整批清零。而且只要绩效持续达标，每年都会再授予新批次，多批叠加、错开到期：

1
2
3
4

批次1:  [确认]  1/3    2/3    全额    结算清零
批次2:          [确认]  1/3    2/3    全额    结算清零
批次3:                  [确认]  1/3    2/3    全额    结算清零
年份:   1       2       3       4       5       6       7

TUP 不是资产，而是限时收益窗口：它不像股票那样拿了就永远是你的，每一批到期清零；但它也不会没收已到手的收益——躺平只意味着新批次断供，已授予的旧批次仍会按原计划兑现完整个周期，收入随之渐进下滑，短则一两年、长则五年明显缩水甚至归零——制度上不存在”吃老本”的稳态。

而奋斗者和躺平者的差距是复利式的：一个年年叠加新批次，一个只出不进，几年下来收入差出好几倍。这不是偶然，而是华为的制度意图——任正非说得直白：**”让拉车人比坐车人拿得多”**（C114）。TUP 把”奋斗溢价”做成了可预期的长期复利，而不是靠领导拍脑袋打分。

胖东来是另一个把”分钱”做得很彻底的企业。2026 年 3 月，创始人于东来公布了胖东来约 40 亿元资产利润的分配标准：管理团队约 50%、员工约 50%（每年利润的一半给团队发奖金、一半归股东收益），创始人于东来个人在股本中的占比仅约 5%（凤凰财经/第一财经）。于东来自己说，这是胖东来”已经持续二十多年的分配体制”，靠的是”制度和股份制的运营模式”。胖东来员工的工资长期显著高于当地零售业同行——不过于东来近年也坦言在薪资上”太溺爱员工”（界面新闻），可见这个模式同样有它的争议和成本。

这个思路在国际上也不新鲜。美国林肯电气（Lincoln Electric）一百多年前就建立了一套组合：计件工资 + 年终利润分享 + 承诺不裁员，被管理学界视为”激励性管理”的教科书案例（搜狐财经）。Costco 则用”显著高于行业的工资 + 远低于同行的员工流失率”证明了善待员工就是最好的生意（Cheers）。

海底捞的”师徒制”是服务业的变体：店长培养出合格的徒弟、帮徒弟开出新店，就可以从徒弟店的利润中持续分成，形成”徒子徒孙”的利益链条。创始人张勇说得直白：”自己不想去开店，就想尽一切办法让别人去开”（凤凰网）。让培养人的人分享被培养者创造的价值，人才自然能源源不断地被培养出来。

这些案例背后的道理，古人已经总结过了——财聚人散，财散人聚。但要注意，分钱不是平均主义，而是”按贡献分、可核算地分”：华为的饱和配股、林肯电气的计件、海底捞的师徒分成，都建立在贡献可以被计量的前提上，否则分着分着就变成大锅饭。

原则四：用高薪买高产出 —— 少人高薪

第四个原则，是”人少一点、钱多一点、活干多一点”。

任正非 2013 年在内部讲话里说得很直白（钛媒体/TechWeb）：

我不眼红年轻人拿高工资，贡献很大才能拿到这么高的工资……三个人拿四个人的钱，干五个人的活，就是我们未来的期望。

这话翻译成大白话，就是”两个人干四个人的活、拿三个人的钱”（网上俗称”234 付薪”；任正非原话是另一个比例——3 个人拿 4 份钱、干 5 个人的活，逻辑完全一致）：员工人均收入高于同行，公司总人力成本反而低于同行，因为产出密度上去了。算一笔账（以 2:4:3 为例）：同样的活过去要付 4 份工资，现在 2 个人干完、只付 3 份钱——两个人各拿 1.5 份，人均收入涨了 50%；公司总支出从 4 份降到 3 份，省了 25%。员工多拿、公司少付，双赢。

把这件事做到极致的，是 Netflix。它的文化手册写得很直白：只招”顶级人才”，付行业最高薪，不搞绩效排名，靠”留任测试（keeper test）”——管理者要问自己”如果这个员工明天提离职，我会拼命挽留吗？”答案是否定的，就体面地请走。它的逻辑是：与其养 10 个平庸的人，不如花同样的钱养 3 个顶尖的人，后者的产出和创造力远高于前者（详见 Patty McCord 的 《How Netflix Reinvented HR》）。

当然，这条路有严格的前提，业内也不乏质疑——营销人”老苗”就专门写过文章吐槽”三个人拿四个人的钱干五个人的活”容易变成画饼（销售与市场）。我认为这个模式成立至少需要三个条件：① 产出可以衡量（干多干少看得见）；② 招聘标准足够高（人少必须精）；③ 有体面的淘汰机制（不合适的人能体面离开，而不是大家一起磨洋工）。缺了这些，”高薪高效”就会退化成”高薪低效”。

原则五：划小核算单元，把权力交给一线

第五个原则，是把组织划小，让”听得见炮声的人”做决策。

稻盛和夫在京瓷推行的阿米巴经营，是把公司切成一个个几十人的小单元，每个单元独立核算、自负盈亏，全员参与经营，目标是”销售最大化、经费最小化”（京瓷官网）。日本航空破产重组时，稻盛和夫也是靠这套”让每个小单元都算账”的制度，一年多就实现扭亏为盈。

海尔从 2005 年开始搞人单合一：”人”是员工（海尔称之为”创客”），”单”是用户的需求和价值，”合一”就是让每个员工直接对用户负责、从自己创造的用户价值中获取报酬（”用户付薪”），而不是听命于上级、从企业领固定工资（海尔官网）。配套的组织变革是把科层制拆成”平台 + 小微”，张瑞敏的口号是：”企业里每个人都应该成为自己的 CEO。”

国内电商圈有一个更轻巧的版本：韩都衣舍的三人小组制。每个小组由设计、运营、货品三人组成，对单款产品的企划、定价、库存全权负责、自负盈亏——卖不掉的库存由小组自己消化，收益直接和利润挂钩。责任、权力、利益在最小的单元里统一了，公司层面只做平台和赋能（大众日报；界面新闻）。

制造业里最动人的设计是丰田的安灯（Andon）：任何一线工人发现质量问题，都可以拉绳停掉整条生产线，直到问题解决（《丰田模式》）。把”叫停权”交给最基层的人，看起来是放弃了控制，实际上是把纠错成本降到了最低——问题在源头被消灭，而不是流到下游变成事故。亚马逊的”两个披萨团队”（团队小到两个披萨够吃，百度百科）也是同一个思路：规模小、自治强、沟通成本低。

华为内部那句著名的”让听得见炮声的人呼唤炮火“，说的也是权力要跟着信息和责任走。我自己的经验印证了这一点：核算单元越小、责权利越统一的地方，人的主观能动性越强。

原则六：制度也要做减法 —— 砍掉反激励

最后一条容易被忽略：好制度不只是加法，更是减法。

微软在 2013 年取消了臭名昭著的员工强制排名（stack ranking）——每个团队强制按曲线排名、末位淘汰，结果是团队内耗、人人自保、优秀员工流失。放弃这套排名后，微软的绩效体系转向”协作 + 成长”导向，外界普遍认为这是微软后来重新崛起的重要人事变革之一（人民网）。

更极端的案例是晨星公司（Morning Star），全球最大的番茄加工商之一：没有 CEO、没有管理层，每个员工通过”同事谅解书（CLOU）”自己定目标、自己申请采购预算、自己评估同事，靠自我管理运转了几十年（界面新闻）。

我之前写过一篇《Just Culture》的文章，讲”公正文化”：处理事故时问”哪里出了问题”而不是”谁出了问题”。制度做减法，本质上也是这个态度——把惩罚导向、控制导向的制度，换成信任导向、学习导向的制度。坏的制度（末位排名、无休止审批、问责文化）看起来是在”管理”，实际上每一条都在悄悄消耗人的主动性。

小结：制度设计的六个检查点

把上面的原则压缩成一张给管理者的自查清单：

1. 定规则的人承担后果吗？——谁定规则，谁最后拿（分金的人最后拿）；
2. 资源会流动吗？——有没有”用完才能再拿、用不完就回收”的机制，防止囤积；
3. 钱分对了吗？——分钱是否与可核算的贡献挂钩？劳动回报是否优先于资本回报？
4. 薪酬买到的是产出还是时间？——是在养”人”还是在养”岗位”？有没有配套的淘汰机制？
5. 核算单元够小吗？——一线有没有决策权、叫停权？责权利是否在最小单元统一？
6. 有没有该砍的制度？——哪些规则正在制造内耗、官僚和反激励？

这六个检查点背后其实只有一个问题：制度是否让每个人的”个人利益”与”组织目标”激励相容，让资源在流动中增值，让创造价值的人分享价值。 如果答案是肯定的，组织会像有了自己的发动机；如果是否定的，再多的会议、再多的监督、再多的口号，都只是给一台失灵的机器打补丁。

我以前写过一篇《管理的杠杆》，讲注入使命、盘活资源、分享利益。现在回头看，制度设计才是那根最硬的杠杆——使命、资源、利益，最终都要落到规则上才能被放大和固化。与其抱怨人心不古，不如把规则设计好。这大概也是管理者最值得投入的方向。

（如果你也对制度设计感兴趣，或者见过什么好机制、坏机制，欢迎交流指正。）

参考资料

1. 邓小平：《党和国家领导制度的改革》（1980 年 8 月 18 日）
2. 马斯金：机制设计是理论，人单合一是实践（新浪财经）
3. 华为 ESOP、TUP 与饱和配股如何打造知识型企业命运共同体（华夏基石）
4. 任正非谈华为内部激励：让拉车人比坐车人拿得多（C114，2014）
5. 任正非：三个人拿四个人的钱干五个人的活是公司的期望（钛媒体/TechWeb，2013）
6. “40 亿资产利润分配给员工”，于东来再次回应（第一财经/凤凰财经，2026-03）
7. 于东来称薪资上太溺爱员工，其实不值这么多钱（界面新闻）
8. 衡量一个 CEO 是否伟大，就看他能否激发组织活力与个人潜能——林肯电气激励系统（搜狐财经）
9. 曾在仓库开堆高机，他 40 年后成好市多 CEO：善待员工就是最好的生意（Cheers）
10. 对话海底捞 CEO：从张勇到杨利娟（凤凰网）
11. 老苗撕营销｜”三个人拿四个人的钱干五个人的活”，咱能不扯吗？（销售与市场）
12. Netflix 文化手册（Jobs at Netflix）；Patty McCord，《How Netflix Reinvented HR》（Harvard Business Review，2014-01）
13. 阿米巴经营带来企业持续发展（京瓷官网）
14. 人单合一：20 年的颠覆，20 年的坚守（海尔官网）
15. 从淘宝小店到互联网品牌生态运营集团：韩都衣舍（大众日报）
16. 传统企业转型案例之一：韩都衣舍——走近柔性供应链（界面新闻）
17. 暂停流程以内建质检（自动化）——安灯机制（《丰田模式》节选）
18. 双比萨团队（百度百科）
19. 微软自救绝招：放弃绩效评比制度（人民网，2013）
20. 没有 CEO 更没有管理层：它是全球最大的西红柿加工厂（界面新闻）
21. 迪士尼度假俱乐部积分规则官方问答（planDisney）
22. 从”海盗分金”聊聊：利益博弈中的生存法则（虎嗅）

答案藏在 harness 里。

“Harness” 的英文原意是马具、鞍具——套在牲口身上，让它的力气能变成拉车、耕地这些实际用途的那套东西。AI 语境下，Anthropic 官方文档给这类工具起过一个很准确的名字：agentic harness（Agent 鞍具）。大模型本身只会”说话”——从概率里吐出下一段 token；是 harness 给它装上了”手脚”（读写文件、跑命令）、”眼睛”（观察执行结果）、”红绿灯”（权限审批），它才真正能干起活来。

所以，你买的从来不是模型，而是”模型 + 一整套鞍具”。 这篇文章想做的事很朴素：拿一把解剖刀，把五款有代表性的 agent harness——Claude Code、Codex、OpenCode、Pi、DeepSeek Harness——按同一套框架拆开，看看它们各自把”身体”装成了什么样；再把我亲手实测的记录摆上来，让结论都落在事实上。

为了拆得干净，我给自己配了一套统一的解剖框架。先讲框架，再拆标本。

一、解剖学：Agent Harness 的五件套

把几款 agent harness 拆开来看，最终都会得到同一张地图：无论哪一款，拆到底都是这五件套的不同配法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

+--------------------------------------------+
| 模型 LLM（大脑）                           |
| 只会"说话"，不会"干活"                     |
+--------------------------------------------+
                      | system prompt + 工具 schema
                      v
+--------------------------------------------+
| agent harness（鞍具）                      |
|                                            |
| 1. 循环 Loop   思考 -> 行动 -> 观察        |
| 2. 工具 Tools  bash / fs / edit            |
| 3. 记忆 Memory 上下文 / 压缩 / 会话持久化  |
| 4. 权限 Sandbox 能自动做 vs 要问人         |
| 5. 界面 UI     TUI / Web / headless        |
|                                            |
| + 扩展点  MCP / 插件 / subagent / hooks    |
+--------------------------------------------+

这五件套，每一件的职责都很清楚：

① 循环（Loop）——agent 的”反射弧”。大模型不会自己反复思考，是 harness 在它外面套了一层 think → act → observe 的循环：让模型生成一段思考（要不要调用工具？调哪个？），harness 执行工具，把结果喂回去，再让模型接着想。这一圈一圈转下来，才叫”自主干活”。ReAct 循环本身并不神秘，几十行代码就能写出来；**麻烦的是循环的”质量”**——什么时候该停、出错怎么恢复、多轮工具调用怎么组织，这些才是 harness 的功夫。

② 工具（Tools）——agent 的”手脚”。读写文件、执行命令、搜索、编辑……每个工具都是一块肌肉。五件套里它最容易理解，但也是最容易”失血”的地方：工具怎么描述给模型（schema 写得好不好）、参数怎么校验、结果怎么截断，直接决定模型”手脚灵不灵活”。

③ 记忆（Memory）——上下文窗口是模型唯一的”工作台面”，而它又小又贵（哪怕 1M 上下文也装不下一个大型仓库）。harness 的功课是：往窗口里放什么、不放什么、装不下时怎么压缩、会话结束后怎么持久化。”记忆”这一件套，是五款工具差异最大的地方之一。

④ 权限/沙箱（Permissions & Sandbox）——agent 的”红绿灯”。文件能不能随便改？命令能不能随便跑？网络能不能访问？有的 harness 默认全放行（信任用户），有的默认全拦截（信任沙箱），大部分在这两者之间划了一条”需要问人”的线。这一件套的配法，直接决定了工具给人的”安全感”和”爽快感”，也最能看出一个团队的工程哲学。

⑤ 界面/入口（UI）——驾驶舱长什么样。终端 TUI、浏览器 Web、无头 headless、API/SDK……同一个引擎可以配不同的驾驶舱，这也是后文 DSH 的 profile 玩法。

还有一个横切的扩展点（Extensibility）：MCP 服务器、插件、subagent、hooks。它不是独立的第六件套，而是”这五件套都允许你改装”的能力。

有了这张地图，再看五款 harness，就不需要记一堆功能列表了——只需要问：它的五件套，各自是怎么配的？哪些是焊死的，哪些是能换的？ 下面五个角色登场，然后我们逐个解剖。

二、五个角色登场

先给五款工具各发一张”身份卡”，顺便配上拟人化的印象。注意，所有数字都标注了抓取日期，因为开源项目的 star 数每天都在变。

拟人化的第一印象是这样的：

• Claude Code = 五星酒店的全能管家。 服务周到，门禁森严，会自己安排小团队（subagents），还会在你进门时记住你的喜好（CLAUDE.md）。代价是：默认得住他家酒店（模型绑定偏软，Anthropic 兼容 API 也能换 DeepSeek/MiniMax，见 3.1 实测），菜单是后厨定的（闭源）。
• Codex = 学院派的实验室主任。 纪律严明——先沙箱再动手，审批分级一丝不苟；论文公开（架构文档、AGENTS.md 公约），连实验设备都开源了（CLI 开源、2026 年连整套 Harness 也开源了）。
• OpenCode = 开源美食广场。 谁家模型都能来摆摊，摊位多到挑花眼；不站队是它最大的卖点，也是它最大的压力（二十万 star 的社区治理）。
• Pi = 极客的改装车手。 车是自己焊的（自研 TUI），默认不装安全带（没有内置权限系统），随时能拆开看（可自我扩展）。开得快，但安全自负。
• DeepSeek Harness = 乐高工厂。 一切皆插件，配置靠 patch 一层层叠汉堡；web、headless、TUI 是同一个引擎换外壳。缺点是还在施工（developer preview），图纸会改。

下面进入正题，逐个解剖。每节都用同一把刀：循环怎么跑、记忆怎么管、权限怎么设、怎么扩展，外加一节实测记录。实测的方法和局限，我会在最后一节统一交代，这里先看结果。

三、逐个解剖

3.1 Claude Code：管家的服务体系

Claude Code 是 2025 年把”AI 编程”这个词从演示变成日常的工具，也是整个品类的参照系。它的五件套配法，可以用一个词概括：服务周全。

循环：最典型的 agent loop + hooks。 它的主循环和其他家没有本质区别（think → act → observe），但它给循环装上了挂钩点（hooks）——这是它最精巧的设计之一。你可以把 hook 理解成”在循环的特定阶段插一脚”：模型调用工具之前、之后、用户提交输入时、会话结束时……都能挂一段你自己的脚本，用来拦截、改写，或在一旁记录。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

用户输入
  │
  ▼
[UserPromptSubmit hook]  ← 可在此改写输入
  │
  ▼
模型思考 / 计划
  │
  ▼
[PreToolUse hook] ──► 工具执行 ──► [PostToolUse hook]
   │                              │
   ▼                              ▼
观察结果 ◄────────────────────────┘
  │
  ▼
继续循环 或 收尾 ──► [Stop hook] ──► [SessionEnd hook]

其他挂点：SessionStart / PreCompact（压缩前）/ SubagentStop（子 agent 结束）
/ Notification（后台任务完成提醒）

举个最实用的例子：团队想让”提交代码前自动跑 lint 和测试”，不需要改任何产品代码，只需要在 PreToolUse 或 Stop 阶段挂一个 hook，让 Claude Code 在动手前/收尾时强制执行 npm run lint && npm test。这相当于把公司流程写进了鞍具里——官方文档把这套机制开放给了所有用户，这也是它生态粘性的来源之一。

记忆：CLAUDE.md 是长期记忆，上下文裁剪是短期记忆。 CLAUDE.md（项目级 + 用户级）是给 agent 的”入职手册”，每次会话自动读入；配合 .claude/ 目录下的子 agent 定义（subagents），相当于给管家配了”部门手册”和”下属名单”。上下文管理则交给内置的压缩策略，用户一般不用操心。

权限：默认要问，可以授权。 第一次跑危险命令，它会停下来问你要不要允许；你可以记下”允许这条规则”，也可以整段放开。--dangerously-skip-permissions 这种 flag 的存在，说明它把”放权”也做成了显式操作——管家不会自作主张，但你说放行它就放行。

扩展：MCP + 插件 + hooks + subagents，四件套齐全。 2025 年下半年开始支持插件生态，配合 MCP 服务器接入外部工具，可扩展性是五家里最完整的之一——当然，这一切都发生在一个闭源的壳里，你能改的是”挂什么”，不能改的是”引擎本身”。

实测记录。 我这台机器上 Claude Code 2.1.3 的配置很有意思：~/.claude/settings.json 里把 ANTHROPIC_BASE_URL 指到了 DeepSeek 的 Anthropic 兼容端点（https://api.deepseek.com/anthropic），模型换成了 deepseek-v4-flash——Claude Code 跑着 DeepSeek 模型。这说明”模型绑定”这一格其实是软的：只要厂商提供 Anthropic Messages 兼容端点，鞍具就能换马（DeepSeek 的路径是 /anthropic/v1/messages，MiniMax 也提供同款）。本次实测里，五款工具因此统一用上了 deepseek-v4-flash，对比完全落在 harness 本身（详见第五节）。实测任务一（修复 3 个注入 bug 并让测试全过）：37 秒完成，11 轮对话，输入 2.2 万 + 缓存读取 14 万 + 输出 0.1 万 token（合计约 16.3 万），成本 0.216 美元——五家里最贵的一趟（它偏好”多轮多确认”的风格 + 大量缓存读取）。它的修复过程很”管家”：先读全文件，明确列出三个 bug，一次性精准编辑，再跑测试验证。

3.2 Codex：学院派的纪律与沙箱

Codex 的开源 CLI（Rust，Apache-2.0）是 2025-04 发布的。如果说 Claude Code 的五件套关键词是”服务”，Codex 的关键词是纪律——尤其是权限/沙箱这一件，它做得最重、最认真。

权限：审批模式分级 + 沙箱层层设防。 这是 Codex 最值得讲的部分。它把”模型想执行命令”这件事拆成两级关卡：先是审批策略（什么时候需要问人），再是沙箱（命令在什么隔离环境里跑）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

模型想执行命令
     │
     ▼
┌────────────────────────────────┐
│ 1. 审批策略                    │ deny ──► 命令不执行，错误回给模型
│ auto（默认，视命令而定）       │
│ never（从不询问）              │
│ on-request（由模型决定）       │
└────────────────────────────────┘
                │ allow
                ▼
┌────────────────────────────────┐
│ 2. 沙箱选择                    │
│ read-only：只读，连写都拦      │
│ workspace-write：工作区可写    │
│ full-access：完全放行          │
└────────────────────────────────┘
                │
                ▼
┌────────────────────────────────┐
│ 底层沙箱实现（按平台自动选）   │
│ macOS: Seatbelt(sandbox-exec)  │
│ Linux: Landlock + seccomp      │
│ 可选: Docker / Nix+Bubblewrap  │
└────────────────────────────────┘
                │
                ▼
           执行命令

值得注意的细节：Codex 的沙箱不是”建议”，而是默认开启。--sandbox read-only 模式下它连写文件都要经过沙箱；macOS 上每个 shell 命令都包一层 sandbox-exec（Seatbelt），Linux 上用 Landlock + seccomp。命令的”工作区权限”和”网络权限”是分开管的，需要联网的操作（比如装依赖）会明确触发更高权限的请求。这套设计在五家里最接近”企业级”。

记忆：AGENTS.md 公约 + 项目记忆。 它推动的 AGENTS.md 约定 是一个跨工具的”项目入职手册”标准——写一次，多个 agent 工具都能读。这算是它给行业留下的一个”公共品”。

扩展：MCP 支持 + config.toml 换 provider。 我的实测配置就是证据：~/.codex/config.toml 里把 model_provider 换成了 DeepSeek（base_url: api.deepseek.com），跑的是 deepseek-v4-flash。Codex CLI 换非 OpenAI 模型，改几行配置就行——它的 harness 层和模型层解耦得很干净。

2026-08 的大动作：Codex Harness 开源。 OpenAI 在 8 月把整套 Codex Harness 开源了（Apache-2.0，官方博客），包含三件东西：codex exec 命令行、TypeScript/Python SDK、以及 app-server（通过 JSON-RPC 连到本地 Codex 进程，提供持久会话、事件流、人在环审批）。最震撼的是一组数据：两个 harness 设计改动，把 GPT-5.6 Sol 在 ARC-AGI-3 上的成绩从 13.3% 提到 38.3%，输出 token 降了 6 倍——“是 harness 设计，而不是模型大小，驱动了 agent 的收益”（报道）。这句话，几乎是整篇文章的题眼：当模型越来越同质化、越来越便宜，鞍具本身成了决定”一匹马能拉多少货”的关键变量。

实测记录。 Codex CLI 0.146.0 + deepseek-v4-flash 跑同一个修复任务：25 秒，只用 1762 个 token 就完成了——五家里最省，比我预期的少一个数量级。它读代码 → 定位 → 一次编辑 → 跑测试，节奏干净利落，没有任何多余的来回。这跟”纪律”的设定完全一致：不废话，干完就停。

我还在一个”外层已有沙箱”的环境里跑了它，收获了一个意外但绝佳的观察：当 macOS 的 sandbox-exec 无法嵌套启动时，Codex 宁可失败也不绕过——它试了不同 shell、不同目录，确认是环境问题后，0 改动地退出，并如实汇报”审批策略是 never，我不能擅自提权”。13,339 个 token 全花在诊断和诚实汇报上。这就是”纪律”两个字在工程上的样子：安全边界是硬约束，不是建议。

3.3 OpenCode：美食广场的兼容性

OpenCode 从 sst 团队手里长出来（现在归 anomalyco 维护），TypeScript 全开源，MIT，是五家里 star 最高的（20 万）。它的五件套关键词：兼容。

循环：标准 loop，但”中场”特别多。 OpenCode 的会话模型支持中途插入权限确认、在 TUI 里切换 agent（Tab 键在 build/plan 之间切换）、把 LSP（语言服务器）接进来给 agent 提供实时的类型信息——这是它区别于其他家的一个亮点：让 agent 的”眼睛”更专业，不止看文本，还看符号、类型、引用关系。

模型：五件套里它把”模型层”做成了多面插座。 这是它安身立命的本事：

1
2
3
4
5
6
7
8
9
10

┌───────────────────────────────────────────────────┐
│ Agent Loop（一套循环）                            │
│ tools / sessions / LSP / MCP                      │
└───────────────────────────────────────────────────┘
                          │ 同一套 tool-call 协议
┌───────────────────────────────────────────────────┐
│ provider 适配层（多面插座）                       │
└───────────────────────────────────────────────────┘
 │         │      │      │        │       │
 Anthropic OpenAI Google DeepSeek MiniMax Ollama(本地)

实测里我的 OpenCode 1.14.18 配的是 deepseek-v4-flash（同一个 auth.json 里同时存着 MiniMax 国际版、国内版和 DeepSeek 三把钥匙）。同一套代码，今天接云端、明天接本地 Ollama，不用改业务逻辑——这是”美食广场”的底气：你不站队，所以你永远有得选。

记忆与配置：opencode.json 一站管理。 规则、agent、模型、权限、工具，全在一个配置文件里；还内置了”权限策略”（permissions/policies）体系，可以给不同工具、不同目录设不同规则。

扩展：插件 + MCP + 桌面 App + 分享。 opencode 还能 --share 把会话分享出来；桌面 App 和 IDE 扩展让它可以不只在终端里用。

实测记录。 任务一（单文件三 bug）：11 秒完成，8 次工具调用，约 1.3 万 token——上来先用 bash 看了 ls/git log/git status 摸清仓库，再读文件、分三次 edit、跑测试，节奏稳当。任务二（多文件）：19 秒，13 次工具调用，约 1.5 万 token，这次它改动了全部三个文件（含把 subtractStock() 改成防御式），和 codex/pi 同属”下沉派”。值得注意的一个细节：它默认 agent 叫 build，另外内置了一个只读的 plan agent——把”先看后动”做成了产品级的两个模式，这在五家里是独一份的设计（其他家大多靠用户自己口头约束）。

3.4 Pi：极客的手工改装车

Pi 是 Earendil Works（作者是游戏圈出身的 badlogic，Mario Zechner）做的。TypeScript monorepo，MIT，96k star，用 Bun 打包成单文件可执行。它的五件套关键词：极简与信任。

权限：五家里唯一”默认不设防”的。 Pi 的 README 里写得很直白：它没有内置权限系统来限制文件系统、进程、网络或凭据访问，默认以启动它的用户的权限运行。这在五家里是独一份的激进选择——其他家至少有一层”要问人”的机制，Pi 直接说：我信任你，你自己负责自己的安全。

但”不设防”不等于”没法防”，它给了三种容器化方案（文档）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

┌──────────────────────────────────────┐
│ Pi 核心（Bun 单文件）                │
│ pi-ai        统一多 provider API     │
│ pi-agent-core  循环 + 状态管理       │
│ pi-coding-agent  CLI                 │
│ pi-tui       自研 TUI（差分渲染）    │
└──────────────────────────────────────┘
                   │ 默认：以你的用户权限"裸奔"
                   ▼
┌──────────────────────────────────────┐
│ 可选安全壳（按需挑一个）             │
│ 1. Gondolin：微 VM，宿主保留         │
│    凭证，内置工具/命令路由进 VM      │
│ 2. Docker：整进程装进容器            │
│ 3. OpenShell：策略控制的沙箱         │
└──────────────────────────────────────┘

这套哲学的价值在于：把”安全”从产品里拿出来，还给用户和环境。 你在自己的机器上跑，裸奔最顺手；你在 CI 里跑，套 Docker 最干净；你给别人的机器用，上 OpenShell。相比”产品替你决定安全边界”，Pi 选择”边界由你画”。

记忆：会话即文件 + 主动分享。 Pi 的会话是文件（可以 --export 成 HTML），还推了一个很有意思的机制：把开源工作里的真实 agent 会话发布到 Hugging Face（pi-share-hf），用真实世界的工具调用、失败、修复数据来改进 agent，而不是靠玩具 benchmark。作者本人就定期公开自己的会话——这大概是五家里对”真实数据”最激进也最坦诚的做法。

扩展：可自我解释。 Pi 的文档里有一句很酷的话：**”你甚至可以问 agent 它自己是怎么工作的”**——因为它是开源的，agent 可以直接读自己的源码来回答。它还支持订阅制 OAuth（ChatGPT、Claude Pro、GitHub Copilot、xAI、OpenRouter 都能登录），把”用别人的订阅跑自己的 harness”做成了特性。

实测记录。 Pi 0.84.2 + deepseek/deepseek-v4-flash 跑同一个修复任务：9 秒完成，6 次工具调用（3 次 bash、2 次 read、1 次 edit），3375 token，成本 0.00007 美元——五家里最快、最便宜，便宜到可以忽略不计。它的风格非常”动手派”：上来就是 bash 一通 ls/find，然后 read、edit、npm test，行云流水。没有确认、没有多余的礼貌，就像改装车手直接掀开发动机盖。当然，这趟之所以这么顺，也是因为任务本身简单、不需要任何权限判断——如果任务需要联网或动敏感目录，裸奔的代价就要另算了。

3.5 DeepSeek Harness：插件流水线

最后拆的是 DeepSeek Harness（dsh）——需要声明一下，这篇文章就运行在它上面，我会尽量用解剖刀而不是滤镜说话。它的五件套关键词：一切皆插件（”Everything is a Plugin”）。

架构：没有”特权核心”。 dsh 建立在 Cordis 这个插件框架之上（设计论文）：模型适配器、工具注册表、会话日志、甚至 agent 循环本身，全都是插件。官方架构文档里有一句很硬的话：”没有需要 patch 的特权核心——你扩展 dsh 的方式，就是把它旁边的插件挂上去。”（架构文档）这意味着它的五件套，每一件理论上都能换。

装配方式：配置层叠（叠汉堡）。 dsh 的”profile”（配置档案）是核心概念。一个 profile = 一组”组合包（bundle）” + 你自己的覆盖配置，按顺序叠起来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

┌────────────────────────────────────────────────────┐
│ 1. 空配置根                                        │
├────────────────────────────────────────────────────┤
│ 2. dsh.profile.bundles 里各组合包的 patch（按序）  │
│    dsh-base（模型/工具/沙箱/权限/持久化/遥测）     │
│    dsh-web-app（浏览器 UI）                        │
├────────────────────────────────────────────────────┤
│ 3. profile 自己的 cordis.patch.yml（你的覆盖）     │
├────────────────────────────────────────────────────┤
│ 4. $DSH_HOME/cordis.patch.yml（全局覆盖）          │
├────────────────────────────────────────────────────┤
│ 5. --patch 参数（一次性覆盖）                      │
└────────────────────────────────────────────────────┘
每一层按 id 替换/插入"插件行"，后层可覆盖前层任意一行

这套”叠汉堡”机制解决的是 agent 领域的一个真问题：agent 系统太容易变成”配置地狱”——几十个开关互相打架。dsh 用”层”来建立秩序：基础能力（dsh-base）是一层，模式（web/headless）是一层，你的个性化是一层，谁在上谁说了算，清清楚楚。dsh web（浏览器 UI）和 dsh --profile headless "任务"（一次性无头执行）就是同一个引擎的两个 profile——换驾驶舱不用换引擎，这正是五件套里”界面”这一件被做成可插拔的样子。

循环：官方文档给了完整的 turn flow。 它的循环设计里我最想提的一点是”模型可见即记录“（model-visible means logged）这个不变量：任何到达模型请求的内容，都必须能从会话日志里重建出来。这保证了 replay、fork、持久化、遥测全都从一条真实的事件流派生，而不是各存各的副本。

1
2
3
4
5
6
7
8
9
10
11
12
13

turn/start
  claim 下一条输入
  组装 prompt 段 + 工具 schema
  → agent/pre-step                    拒绝 | 进入
     step/start
     追加输入为 user/message
     从日志推导模型历史
     agent/request → llm/stream → assistant/chunk* → assistant/message
     tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*
     step/end
     还有未清账的工具 → 下一个 step
  → agent/turn-stopping
turn/end

（此图摘自官方架构文档，turn = 一次”欠债还清”的完整回合，step = 一次模型请求 + 它调用的工具。）

权限：沙箱与 fs 分离。 dsh-base 里同时挂了 bash 沙箱（macOS/Linux 用 sandbox，Windows 用 ACL 受限令牌）和文件策略层，但两者是分开的——这带来一个实测里非常有意思的差异，见下面的记录。

实测记录。 DeepSeek Harness 0.1.1-rc.2（headless profile）跑同一个任务：26 秒完成，修复正确（事后验证 4/4 通过）。但过程很有戏剧性：它的 bash 沙箱在我这个”外层已有沙箱”的环境里同样启动失败（sandbox-exec: sandbox_apply: Operation not permitted），按理说它和 codex 一样寸步难行——但它没有停。因为它的 fs 工具（读、写、编辑）走的是独立的文件策略层，不受 bash 沙箱故障影响，于是 agent 照常读代码、照常编辑、修完全部 bug，然后发现 npm test 跑不了，就手动逐用例做了数学验证，并在汇报里诚实说明：”沙箱后端不可用，提权通道被拒，拒绝是最终的，所以我改为仔细检查验证。”（原话大意）

这组对照非常能说明问题：

• Codex：所有操作都经过沙箱体系 → 沙箱挂了 → 整个 agent 停摆（安全优先，失败即停）。
• DSH：fs 和 shell 分属两套机制 → 一个挂了另一个照常 → 任务完成（可用性优先，降级继续）。

没有谁对谁错，这是两种工程哲学：把安全做成一堵墙（墙倒了，什么都过不去）vs 把安全做成一道道闸（闸坏了，别的路还能走）。 对”只读分析”这类任务，DSH 的降级能力是优点；对”必须确保命令被隔离”的场景，Codex 的宁可停摆是优点。顺便说一句，dsh 现在还明确标注是 developer preview——接口随时可能破坏性变更，这一点文章里必须如实交代。

四、横向对比：同一张表，五种配法

先交代一下测试任务（完整方法见第五节，任务源码都在复现仓库的 tasks/ 下）：任务一是一个 4 个测试的小仓库，故意注入 3 处 bug（税率重复计算、缺失四舍五入、硬编码税率），起步状态 1 过 3 挂；任务二升级成多文件订单服务（inventory.js/pricing.js/checkout.js 三个文件），同样注入 3 处 bug（折扣码大小写、缺库存检查、空订单不报错），其中”库存不足要报错”这条横跨两个文件，起步 3 过 3 挂。两个任务提示词完全一致，五家各自跑在独立副本上，不允许修改测试文件。

先回放任务一的”名场面”：五家各自的工具轨迹。下面这些不是示意图，是从各家会话日志里摘出来的真实记录（DSH 的轨迹来自它的 session 日志，Pi 和 OpenCode 来自各自的 JSON 输出，Claude Code 与 Codex 的无头模式不导出工具明细，所以用它们自述的流程）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Claude Code（11 轮对话，37s）：
  读全文件 → 列出 3 个 bug → 一次 edit 全部修复 → npm test
  风格：先看全，再动手，多轮确认

Codex（25s，仅 1762 tokens）：
  读代码 → 定位 → 一次编辑 → 跑测试
  风格：一把梭，不废话（这是它自己汇报的流程）

OpenCode（8 次工具调用，11s）：
  bash（ls + git log + git status）→ bash（cat + ls -R）→ read×2 → edit×3 → npm test
  风格：先摸清仓库（连 git 历史都看了），再动手

Pi（6 次工具调用，9s）：
  bash ls → bash find → read×2 → edit → npm test
  风格：bash 开路，跑得飞快

DSH（12 次工具调用，26s）：
  bash ls → glob → bash → read×3 → edit×3 → read → bash×2
  风格：读得多、改得稳；bash 沙箱不可用就改用 fs 工具 + 数学验证
  （其中 bash 调用都尝试过但被沙箱拦下——见 3.5 节的对照实验）

同一个任务（任务一）、同样的三处 bug，五家的”解题姿势”各不相同：有先看后动的、有先测后改的、有一把梭的、有 bash 开路的。这就是五件套配法差异最直观的样子。

进阶任务（任务二）：任务变难后，修法开始分派

我又加跑了一档更复杂的任务，看看差距会不会拉开。结果很有意思：五家全部修复通过（6/6），”能不能修好”依然拉不开差距，”怎么修”却明显分成了两派。

1
2
3
4
5

claude（29s，11 轮，$0.197）   ：checkout 接上 hasStock() 前置检查 → 只改 2 个文件
dsh（17s，13 次工具调用）      ：同上，checkout + pricing（这次 bash 环境正常，跑通了 npm test）
codex（23s，6,030 tokens）     ：除 checkout 检查外，还把 subtractStock() 改成防御式 → 改全部 3 个文件
opencode（19s，13 次工具调用，1.5 万 tokens）：同 codex，改全部 3 个文件
pi（16s，12 次工具调用，5,394 tokens，$0.0001）：同 codex，改全部 3 个文件

一派只在”入口”设卡（claude、dsh）：在 checkout 里调用 hasStock() 前置检查，库存不足就抛错，inventory 原样不动；**另一派把防线下沉到”数据层”**（codex、opencode、pi）：让 subtractStock() 自己拒绝扣成负数，从根上保证库存不会变负。两种修法都让测试通过，但防御的边界画在了不同的位置——这跟它们在权限/沙箱上的哲学（Codex/Pi 更”底层兜底”）隐隐呼应。

这里还有个有趣的细节：修法不只看 harness，也看模型。OpenCode 第一轮（用 MiniMax-M2.7）跑任务二时只改了 checkout + pricing，属于”入口派”；换成 deepseek-v4-flash 重跑后，它改动了全部三个文件，变成了”下沉派”。同一个 harness、不同的模型，解题姿势都会变——这也是为什么我坚持把四家统一到同一个模型再对比。

顺带一提：任务一里 DSH 因为 bash 沙箱起不来只能”数学验证”，这一轮环境正常后它顺利跑通了 npm test——印证了 3.5 节的结论：那是环境问题，不是能力问题。

把五件套和五款工具放进一张表：

再画一张光谱图，把五款工具放到两个坐标轴上——横轴是”开箱即用 ↔ 自己组装”，纵轴是”模型锁定 ↔ 模型中立”：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

模型锁定
  │
Claude Code（Anthropic 兼容 API 可换）
  │
  │                     Codex（config 可换模型）
  │
  │                          DSH（默认 DeepSeek，provider 可插拔）
  │
  │                               OpenCode
  │
  │                                    Pi
  └──────────────────────────────────────────────> 模型中立
  开箱即用                                         自己组装
  （batteries included）                           （BYO）

资源占用：安装体积与内存

选型时还有一个实在的维度：磁盘和内存。我把五款工具的安装体积和运行时峰值内存都量了一遍（同样跑任务一，macOS /usr/bin/time -l 抓主进程峰值 RSS）：

这里有一个很反直觉的结果：Codex（Rust）的安装体积其实是五家里第二大的（258.5 MB），但运行时内存却是五家里最低的（85 MB）——“Rust 省内存”的印象成立，”Rust 体积小”的印象在它身上不成立。拆开看原因：258.5 MB 基本全是二进制本体（安装目录里其余资源加起来不到 5 MB）。需要澄清的是，桌面 App 本身（.dmg）和 app-server 是独立的 release 资产，装 CLI 不会带上它们——这个二进制就是 CLI 自己，只是大得惊人：__TEXT 段 252 MB，其中机器码 __text 约 185 MB（整个 agent 运行时——沙箱实现、协议客户端、MCP、TUI、内嵌 webview/字体等 UI 资源——被静态链接进了一个文件），且没有 debug 符号可剥。所有安装渠道（brew cask、npm、官方脚本、GitHub release）装的都是这同一个二进制（官方 gzip 压缩包 84 MB，解压即此），不存在更小的”纯 CLI”版本。反过来，两个”内存大户”是 Claude Code（385 MB）和 OpenCode（374 MB）——Node/Bun 运行时本身就有不小的底座，再加上推理时的上下文缓冲。

几点说明：内存测的是主进程的峰值 RSS，工具派生的 bash 子进程不计入；安装体积口径不同（单二进制 vs npm 全家桶），Pi 和 DSH 如果只算真正跑起来的文件会更小；这些数字随版本变化，仅供参考——但对”这台机器装得下吗、跑得起吗”这类问题，量级是有用的。

换个角度说结论：

• 想省心、要生态，选 Claude Code——服务最周全，代价是闭源；模型绑定是软的（Anthropic 兼容端点即可换 DeepSeek/MiniMax 等，见 3.1 实测）。
• 重视安全和可审计性，选 Codex——沙箱最硬、最省 token，而且连 harness 本体都开源了。
• 要模型自由、要社区，选 OpenCode——中立插座 + 20 万 star，怎么接都行。
• 追求速度和极简，且自己掌控环境，选 Pi——快得离谱、便宜得离谱，安全自负。
• 想深度定制 harness 本身，选 DSH——一切皆插件，五件套全都能换；但要接受 developer preview 的不稳定。

五、实测方法论与免责声明

为了让上面这些结论站得住，我交代一下怎么测的。完整的复现材料——两档任务源码、测试环境说明、五款工具的运行脚本、全部原始会话记录（工具轨迹/token/成本）与结果汇总——已开源在 github.com/springuper/agent-harness-bench，任何人可以自行查证或重跑。

1. 同一任务，两档难度：任务一是一个 4 个测试的小仓库，故意注入 3 个 bug（税率重复计算、缺失四舍五入、硬编码税率），起步状态 1 过 3 挂；任务二是多文件订单服务（inventory.js/pricing.js/checkout.js），注入 3 个 bug（折扣码大小写、缺库存检查、空订单不报错），其中”库存不足要报错”横跨两个文件，起步 3 过 3 挂。两档提示词完全一致：”修复 bug，让 npm test 全过，不改测试文件，跑测试确认。”
2. 隔离环境：五款工具各自跑在独立的仓库副本里，避免”先跑完的改好了代码，后跑的捡现成”这种污染（第一轮我就踩了这个坑，五家共享一个目录，结果 Pi 8 秒修完后，其他家全在”验证已通过的代码”）。
3. 版本与模型：Claude Code 2.1.3、Codex CLI 0.146.0、OpenCode 1.14.18、Pi 0.84.2、DSH 0.1.1-rc.2，五款全部使用同一个模型 deepseek-v4-flash——对比完全落在 harness 本身的差异上。Claude Code 是通过 DeepSeek 的 Anthropic 兼容端点（https://api.deepseek.com/anthropic）接入的，这本身就是”模型与 harness 解耦”的一个例证（详见 3.1 节）。token 数和成本虽然同模型，但各家计费口径与缓存策略不同，仍只宜做量级参考。
4. 日期：所有 star 数、版本号、实测数据均为 2026-08-23 抓取，开源世界变化快，引用时请以当时为准。
5. 坦白：作者深度使用 DSH（这篇文章就是在 DSH 里写的），文章尽量用解剖刀而不是滤镜；但如果你发现哪里偏了，欢迎在评论区指出来。

把两档任务的实测放到一起对照。先看任务一：

（说明：五家同模型，但各家 token 计费口径与缓存策略不同，”成本”是各工具自己上报的数值，仅供参考。）

任务二同样全绿，关键数字：

（任务二的 codex 与 dsh 是在无外层沙箱的正常环境下跑的——任务一里它们的 bash 沙箱启动失败是环境限制，不是能力问题，见 3.5 节。缓存命中率 = 缓存读取 token / 总 token，反映 harness 复用上下文的程度。它和任务形态强相关：长会话里系统提示词与历史前缀稳定，命中率可以到 99% 以上（本文写作时的长会话实测 99.8%）；基准里 7 步的短任务上下文变化大、冷启动占比高，命中率低属正常，横向对比看相对差异即可。Codex 无头输出不提供缓存明细。）

六、结尾：鞍具的时代

写这篇文章的过程中，最触动我的数据是 Codex Harness 开源时的那个结果：两个 harness 设计改动，让同一个模型的成绩从 13.3% 涨到 38.3%，token 还省了 6 倍。 这意味着什么？

意味着模型正在变成商品，鞍具正在变成差异。 当大模型的能力越来越同质化、价格越来越便宜，”选哪个模型”的答案会越来越不重要；而”怎么把模型的力气变成实际产出”——循环怎么设计、上下文怎么管理、安全边界怎么划、怎么扩展——会越来越值钱。2026 年回头看，这五款工具几乎在同一件事上押注，只是姿势不同：Anthropic 押服务与生态，OpenAI 押纪律与开源，OpenCode 押中立与社区，Pi 押极简与信任，DeepSeek 押插件化与可组合性。

还有一件小事我想留作彩蛋：我这台机器上，五款工具现在跑着同一个引擎——deepseek-v4-flash。 Claude Code 是通过 DeepSeek 的 Anthropic 兼容端点接入的，另外四家各有各的连法，但没有一行业务代码是为”某个模型”写的，全是 harness 在替我干活。这大概就是鞍具时代最好的注脚——马是谁不重要了，重要的是鞍具合不合手。

最后，如果你也想亲自感受”同一副大脑、五副鞍具”的差别，可以这样复现这轮实测：在 agent-harness-bench 的 tasks/ 下任选一个任务，复制到独立目录（比如 cp -R tasks/task1 /tmp/my-run && cd /tmp/my-run），再用附录里任何一款工具的无头命令跑下面这段提示词——提示词里的”这个仓库”指的就是你复制出来的那个目录：

1

修复这个仓库里的 bug，让 npm test 全部通过。不要修改 test/ 目录下的测试文件。完成后运行测试确认。

（提醒：给每款工具用独立的副本，别让它们共享一个目录——否则先跑完的会”剧透”给后跑的，这正是我在方法论里踩过的坑。）

附：五款工具的无头模式一行命令

本文的实测全部走的是各家的”无头（headless）”模式——不打开交互界面，把任务当作参数丢进去，跑完退出。这也是把 agent 接进 CI、批处理脚本的标准姿势。五款工具全都提供无头模式，所以”能不能接 CI”这个问题的答案是：都可以——差异只在输出格式（有的给 JSON 事件流，有的给纯文本）和权限/沙箱参数（见下方小提示）。以下命令都是我这次实测真实用过的（2026-08-23），复制即用——先到 agent-harness-bench 的 tasks/ 复制一个任务到独立目录再运行，提示词里的”这个仓库”指的就是你运行命令所在的目录：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Claude Code：-p 无头模式；通过 DeepSeek 的 Anthropic 兼容端点接引擎（CI 常用）
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic ANTHROPIC_AUTH_TOKEN=sk-你的key \
  ANTHROPIC_MODEL=deepseek-v4-flash \
  claude -p "修复这个仓库里的 bug，让 npm test 全部通过" --dangerously-skip-permissions

# Codex CLI：exec 非交互执行，--sandbox workspace-write 用工作区沙箱
codex exec --sandbox workspace-write --skip-git-repo-check "修复这个仓库里的 bug，让 npm test 全部通过"

# OpenCode：run 非交互执行，-m 指定 provider/模型（这里用 DeepSeek）
opencode run -m deepseek/deepseek-v4-flash --dangerously-skip-permissions "修复这个仓库里的 bug，让 npm test 全部通过"

# Pi：-p 非交互模式，--provider/--model 指定引擎（这里用 DeepSeek）
pi -p "修复这个仓库里的 bug，让 npm test 全部通过" --provider deepseek --model deepseek/deepseek-v4-flash

# DeepSeek Harness：headless profile，一次性任务，打印最终答案后退出
dsh --profile headless "修复这个仓库里的 bug，让 npm test 全部通过"

几个小提示：

• 换引擎（模型）只改对应参数：Claude Code 看 ANTHROPIC_BASE_URL/ANTHROPIC_MODEL，Codex 看 config.toml 的 model_provider，OpenCode 看 -m provider/model，Pi 看 --provider/--model，DSH 看 settings 里的模型配置——五款工具的”鞍具”和”马”都是可以分开换的，这正是本文想让你带走的核心印象。唯一的前提是协议兼容：Claude Code 需要对方提供 Anthropic Messages 兼容端点（DeepSeek 的 https://api.deepseek.com/anthropic、MiniMax 的 /anthropic 都行），其余四家走 OpenAI/Responses 兼容协议，选择面更大。
• 各家都支持把输出格式化成 JSON（--output-format json / --format json / --mode json 等），方便脚本解析。
• 沙箱和权限开关的名字各不相同：--dangerously-skip-permissions（Claude Code/OpenCode）、--sandbox（Codex）、无权限系统（Pi）、profile 内权限策略（DSH）。接 CI 前，请一定先搞清楚你在哪一档权限上跑。

本文想和你聊聊这个方向的代表方案 Ink。文章分两层：先是「怎么用」——组件、Flexbox、Hooks，几乎不用换脑子；再是「为什么」——我会把 Ink 拆开，读它的源码（reconciler、Yoga 布局、2D buffer 渲染、终端写入），再跑真实的例子把输出摆上来，让结论都落在事实上。当「前端之美」的心智迁移到终端这块看似受限的介质时，会发生什么？值得亲眼看一下。

一、为什么 Terminal UI 突然「变美」了？

从 print 到应用

很长一段时间里，命令行工具给人的印象是：黑窗口，白字或灰字，偶尔加点颜色，输出靠 console.log 或 printf 堆叠。交互靠一问一答的 prompt。复杂一点的用 ncurses 画表格，但开发和维护成本都很高，和现代前端的组件化、声明式思路相去甚远。

2025 年前后，情况变了。Claude Code、Gemini CLI、Codex CLI 等一系列 AI 编程助手把终端当成了主战场。它们需要展示：多轮对话、工具调用结果、文件变更、进度状态……信息量大、结构复杂，纯文本流完全不够用。于是，终端被当作一块真正的 UI 画布来对待。

技术选型的共识：React + Ink

这些工具不约而同地选用了同一条技术栈：Ink——一个把 React 渲染到终端的 renderer。Ink 的 README 里有一份官方的「Who’s Using Ink?」名单：Claude Code、Gemini CLI、GitHub Copilot CLI、Canva CLI、Cloudflare Wrangler、Prisma、Terraform CDK、Gatsby、tap……几乎每一个主流 AI 编程助手的 TUI 层都长在 Ink 上。（顺带纠正一个流传很广的说法：Shopify CLI 并不在名单上，它新版本已经用 Rust 重写了。）

这背后的逻辑很直观：这些团队大多有丰富的 React 经验。与其用传统方式（ncurses、readline、手写 ANSI 转义）从零搭一套终端 UI，不如复用已有的前端心智——组件、状态、Hooks、声明式渲染。Ink 恰好提供了这一层抽象。

二、Ink 的核心：React + Flexbox，心智零迁移

Ink 的 slogan 很干脆：「React for CLIs」。你写的就是 React 组件，只是渲染目标从 DOM 变成了终端。

Yoga 布局：终端里的 Flexbox

Ink 使用 Yoga 作为布局引擎——这也是 React Native 用的那套。所以：

• 每一个 Box 默认就是 display: flex 的容器
• flexDirection、justifyContent、alignItems、padding、margin、flexGrow 等属性，和你在 CSS 里写的几乎一一对应
• 百分比宽高（如 width="70%"）也支持，可以做出响应式布局

如果你已经会用 Flexbox 做 Web 布局，那在 Ink 里做终端布局，几乎没有额外学习成本。

基础组件：Box 与 Text

Ink 提供两个最核心的组件：

• **Text**：承载所有文本，支持 chalk 风格的颜色、粗体、下划线等样式
• **Box**：布局容器，相当于浏览器里的 div，支持上述 Flexbox 属性

所有可见文本必须包在 Text 里，所有布局结构用 Box 搭。下面是一个最简单的例子：

1
2
3
4
5
6
7
8
9
10
11

import React from 'react';
import { render, Box, Text } from 'ink';

const App = () => (
  <Box flexDirection="column" padding={1}>
    <Text color="green" bold>✓ 任务完成</Text>
    <Text color="gray">已处理 42 个文件</Text>
  </Box>
);

render(<App />);

实际输出：

一个「迷你 Claude Code」布局示例

我们可以用 Box 和 flexDirection 快速搭出一个类似 Claude Code 的三栏布局：左侧主内容、右侧边栏、底部输入区。代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

import React, { useState } from 'react';
import { render, Box, Text, useInput } from 'ink';

const App = () => {
  const [input, setInput] = useState('');

  useInput((char, key) => {
    if (key.return) {
      // 处理提交
      return;
    }
    if (key.backspace) {
      setInput((prev) => prev.slice(0, -1));
      return;
    }
    if (char) setInput((prev) => prev + char);
  });

  return (
    <Box flexDirection="column" width="100%" height="100%">
      {/* 主内容区：左 70% + 右 30% */}
      <Box flexDirection="row" flexGrow={1}>
        <Box flexDirection="column" width="70%" padding={1} borderStyle="single">
          <Text bold>对话区</Text>
          <Text color="gray">Assistant: 你好，有什么我可以帮忙的？</Text>
        </Box>
        <Box flexDirection="column" width="30%" padding={1} borderStyle="single">
          <Text bold>工具面板</Text>
          <Text color="cyan">Read, Edit, Bash...</Text>
        </Box>
      </Box>
      {/* 底部输入区 */}
      <Box padding={1} borderStyle="single">
        <Text color="yellow">&gt; </Text>
        <Text>{input || ' '}</Text>
      </Box>
    </Box>
  );
};

render(<App />);

这里的结构完全是「前端式」的：外层 flexDirection="column" 分上下两块，上面再用 flexDirection="row" 分左右。borderStyle="single" 画出边框，padding、width 控制间距和占比。熟悉 React 和 Flexbox 的人一眼能看懂。

真实运行效果（渲染帧序列合成的 GIF，固定 60 列宽便于展示；输入是脚本模拟的——真实的 useInput 在终端里就长这样）：

注意两个细节：中文按双倍宽度排版，70%/30% 在 60 列下被 Yoga 精确换算成 42/18 列；gap、marginTop、borderStyle 这些「前端属性」在终端里原样生效。这段动图是真实运行结果，不是示意图。

Hooks：状态与输入

Ink 支持完整的 React Hooks。除了 useState、useEffect，还提供了针对终端的专用 Hooks：

• **useInput**：监听键盘输入，处理方向键、回车、Ctrl+C 等
• useFocus / **useFocusManager**：管理焦点，实现 Tab 切换、不同区域的键盘导航
• **useWindowSize**：获取终端宽高，做响应式布局

这些 API 让「交互式」TUI 的开发体验和写 Web 应用非常接近：状态驱动视图，事件驱动状态更新。

三、Ink 的架构：React 的另一种 renderer

很多人好奇：Ink 到底是怎么把 React 画到终端里的？答案其实很直接：Ink 是 React 的一个自定义 renderer，和 react-dom 平级。React 负责调度和协调，renderer 负责把组件树「画」到宿主环境里。浏览器里是 DOM，终端里就是 stdout。

终端渲染的两块基石：字符网格与 ANSI 转义

在讲 Ink 怎么做之前，先花两分钟搞清楚「终端到底是怎么把字画出来的」。做 Web 的读者可能从来没想过这个问题——浏览器替你封装了一切，但终端里没有这样的封装。

终端是一张字符网格。 终端模拟器（Terminal.app、iTerm2、VS Code 里的 xterm.js）维护一个「宽 × 高」的字符矩阵（比如 80 列 × 24 行），外加一个光标位置。程序往 stdout 输出的字节会被按顺序填进网格：字符写到光标处，光标右移一格；\n 让光标换行。没有「元素」、没有树、没有样式表——只有「当前位置 + 覆盖写」。所以终端程序想「更新界面」，手段只有三种：

1. 覆盖写：把光标移回去，用新字符盖住旧字符。最简单的例子是进度条——\r（回车但不换行）回到行首，重写这一行；
2. 擦除重写：\x1b[2K 擦掉当前行、\x1b[2J 清屏，然后把内容重新写一遍；
3. 移动光标：\x1b[nA / \x1b[nB 上下移 n 行，\x1b[nC / \x1b[nD 左右移，\x1b[H 回到左上角。

这些 \x1b[ 开头的字节序列就是 ANSI 转义序列（escape sequence）。颜色也是它：\x1b[31m 之后输出的字符变红，\x1b[0m 恢复默认。这套字节协议就是终端的「API」——没有 document.querySelector，没有 textContent，只有「把光标挪到某处，写一些字符」。

对比一下你熟悉的世界：浏览器里改一个数字，countEl.textContent = '1'，浏览器只重绘那一处；终端里没有「那一处」的句柄，你只能把光标移过去覆盖，或者擦掉整块重新画。Ink 的核心工作，就是把你用 React 声明出来的画面，翻译成这一串 ANSI 指令。理解了这一点，后面看 Ink 为什么每次更新都「重新生成整帧」，就顺理成章了。

提醒：这类带中文的 ASCII 线框图，在浏览器里是否对齐取决于代码块的字体是不是等宽 CJK 字体（本站主题已做处理）。如果在你那边看到线框错位，通常是字体回退导致的，不是图本身的问题——本文所有线框图都按「中文占 2 格、其他字符占 1 格」的规则逐行校验过。

react-reconciler：同一套调度，不同的宿主

React 在 16 之后把「协调逻辑」和「宿主渲染」解耦了。react-dom 用的是 react-reconciler 提供的 API，实现了一套「createInstance、appendChild、commitUpdate……」的 host config，把 React 元素变成 DOM 节点。Ink 做的是一样的事，只不过宿主不是 DOM，而是终端。

Ink 和 Yoga 的关系可以这么理解：Ink 是 React 的 Terminal renderer，Yoga 是 Ink 内部使用的布局引擎。Ink 在创建 Box 等节点时，会同步创建对应的 Yoga 节点；协调完成后，调用 Yoga 计算布局，再根据布局结果生成输出。Yoga 是 Ink 的依赖，不作为独立进程或服务存在。

Ink 的实现大致分几层：

1. Reconciler 层：用 react-reconciler 注册一套 host config，告诉 React「如何创建/更新/删除一个终端节点」。这里的「节点」不是 DOM 元素，而是 Ink 内部的节点结构，每个 Box 会绑定一个 Yoga 节点。

2. 布局层：commit 完成后，Ink 调用 Yoga 对整棵布局树做 Flexbox 计算。flexDirection、padding 等属性在创建时已映射到 Yoga 节点，Yoga 算出每个节点的 x、y、width、height。

3. 输出层：根据 Yoga 输出的布局结果，把每个 Text 节点的内容、样式转换成 ANSI 转义序列，按行列写入一个 2D 字符 buffer。最后通过 process.stdout.write 输出，必要时先清屏再重绘。

整体架构可以用下面的字符图概括：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

┌──────────────────────────────────────────────────────────────────────────┐
│                           React (调度 + 协调)                            │
│                 你的 JSX: <Box><Text>Hello</Text></Box>                  │
└──────────────────────────────────────┬───────────────────────────────────┘
                                      │                                   
                                      ▼                                   
┌──────────────────────────────────────────────────────────────────────────┐
│                             react-reconciler                             │
│提供 createContainer、updateContainer、commitUpdate 等 API                │
│不关心宿主是 DOM 还是 Terminal，只负责 diff 和调度                        │
└──────────────────────────────────────┬───────────────────────────────────┘
                                      │ host config 回调                  
                                      ▼                                   
┌──────────────────────────────────────────────────────────────────────────┐
│                           Ink (Host Renderer)                            │
│  │createInstance     │──▶│Ink 节点树         │───▶│Yoga 布局计算      │  │
│  │appendChild        │──▶│Box↔YogaNode       │───▶│(C/WASM)           │  │
│  │commitUpdate       │──▶│Text               │───▶│flexDirection,     │  │
│  │                   │──▶│                   │───▶│padding, margin    │  │
│  └───────────────────┘──▶└─────────┬─────────┘───▶└─────────┬─────────┘  │
│                                    │                        │            │
│                                    │   布局结果 (x,y,w,h)   │            │
│                                    ▼                        │            │
│                              ┌────────────────┐             │            │
│                              │2D 字符 buffer  │◀────────────┘            │
│                              │+ ANSI 样式     │                          │
│                              └───────┬────────┘                          │
│                                      │                                   │
│                                      ▼                                   │
└──────────────────────────────────────┬───────────────────────────────────┘
                                      │ process.stdout.write              
                                      ▼                                   
┌──────────────────────────────────────────────────────────────────────────┐
│                        Terminal (stdout / stdin)                         │
└──────────────────────────────────────────────────────────────────────────┘

简要来说：React 负责「要渲染什么」，react-reconciler 负责「何时、如何调度更新」，Ink 负责「在终端里怎么画」——而「怎么画」又分两步：Yoga 算位置，Ink 把位置 + 文本转成 ANSI 输出。

源码里的证据：host config 长什么样

示意图毕竟只是示意，还是把 Ink 拆开看。以下均来自 Ink 7.1.1（npm 当前最新版，配 React 19）。build/reconciler.js 的开头就是答案——它用 react-reconciler 的 createReconciler 注册了一套 host config：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// ink/build/reconciler.js（节选，Ink 7.1.1）
import createReconciler from 'react-reconciler';
import Yoga from 'yoga-layout';
import { createNode, appendChildNode, ... } from './dom.js';

export default createReconciler({
  getRootHostContext: () => ({ isInsideText: false }),
  shouldSetTextContent: () => false,          // 文本不走 content 属性，用独立文本节点

  createInstance(type, props, rootNode, hostContext) {
    // 每个 <Box>/<Text> 创建一个 Ink 节点；dom.js 里同步创建 Yoga 节点
    const node = createNode(type);            // dom.js: Yoga.Node.create()
    // ...
  },
  createTextInstance(text, _root, hostContext) { /* ... */ },

  appendChild: appendChildNode,               // 同时把 Yoga 子节点挂到父节点上
  insertBefore: insertBeforeNode,
  removeChild: removeChildNode,

  commitUpdate(node, _type, oldProps, newProps) {
    const props = diff(oldProps, newProps);
    // ...
    setStyle(node, value);                    // 样式直接映射到 Yoga 节点
  },

  resetAfterCommit(rootNode) {
    rootNode.onComputeLayout();               // → yogaNode.calculateLayout()
    // ...
    rootNode.onRender();                      // → 整帧渲染
  },
});

逐条对应前面的分层：

• createInstance / appendChild / commitUpdate……就是第 1 层说的 host config。注意 dom.js 里每个节点创建时都调 Yoga.Node.create()，appendChildNode 会同步 insertChild 到父节点的 Yoga 节点——Box ↔ YogaNode 一一对应，不是概念上的类比。
• resetAfterCommit 是 commit 阶段的收尾钩子：先 onComputeLayout()（ink.js 里就是一行 this.rootNode.yogaNode.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR)，对整棵布局树做 Flexbox 计算），再 onRender() 走渲染。
• 渲染在 renderer.js：new Output({ width, height }) 建一张 2D 字符画布，renderNodeToOutput 把每个节点的文本和 ANSI 样式画进去，最后产出一帧完整的字符串。

这就是第 2、3 层说的「Yoga 算位置，Ink 把位置 + 文本转成 ANSI 输出」——不是比喻，是源码里真实存在的调用链。

用 Counter 串起全过程：原地变化时会发生什么？

用一个最简单的 Counter 来串起整个流程，尤其看看「只有数字原地变化」时，背后发生了什么：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import React, { useState, useEffect } from 'react';
import { render, Text } from 'ink';

const Counter = () => {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => setCount(c => c + 1), 100);
    return () => clearInterval(timer);
  }, []);

  return (
    <Text color="green">
      计数: {count}
    </Text>
  );
};

render(<Counter />);

这段代码在真实终端里长这样（渲染帧序列合成的 GIF，每 100ms 数字 +1）：

首次渲染（count = 0）：

1. React 渲染 <Counter>，得到 {count: 0} 的虚拟树
2. react-reconciler 调用 Ink 的 host config：createInstance(Text), appendChild(text “计数: 0”)
3. Ink 构建节点树，为布局创建 Yoga 节点（这里只有一个 Text，布局很简单）
4. Yoga 计算：这一行占多少宽、多高
5. Ink 把 “计数: 0” + 绿色 ANSI 写入 buffer，stdout.write 输出
6. 终端显示：计数: 0

100ms 后，setCount(1) 触发更新：

1. React 调度一次更新，reconciler 做 diff，发现只有 Text 的 children 变了（”0” → “1”）
2. reconciler 调用 commitUpdate / commitTextUpdate，告诉 Ink：这个 Text 的内容要改成 “计数: 1”
3. 关键点：Ink 不会只更新终端里「数字那一格」。React 的 diff 只标记了这一处，但 Ink 没有 DOM 那种「改一个 textNode」的能力——resetAfterCommit 会触发 Yoga 对整棵布局树再算一次布局（结果可能一样），然后 renderer.js 把整棵树重新渲染成一张完整的 2D buffer。全量重绘发生在「帧生成」这一层。
4. 写入终端时又是另一回事：Ink 的 log-update 会把新帧和上一帧做比较。默认模式下，内容没变就一行都不写；变了就擦掉旧帧的行数、写入新帧。如果开启 incrementalRendering: true，它进一步按行比较、只重写变化的行——源码注释写得很直白：”We do not write lines if the contents are the same. This prevents flickering during renders.”
5. 至于「清屏再重绘」，只发生在少数特殊场景：帧超出终端高度（overflow）、全屏/非全屏切换、Windows 控制台。ink.js 里有个 shouldClearTerminalForFrame 函数，专门判断「这一帧要不要清屏」。

所以准确的图景是：组件树的 diff 是增量的（React 只标记了 Text 的 children 变了），帧的生成是全量的（整棵树重新渲染成一张新帧），终端的写入是 diff 的（新帧和旧帧逐行比较，没变就不写）。浏览器里 react-dom 可以只 textNode.textContent = '1' 改那一处；终端里 Ink 没有这个选项，但也不至于每次清屏——它用「全帧生成 + 行级擦写」在正确性和性能之间取平衡。

与 react-dom 的对比

同一套 React 心智，换了一个宿主环境，就能从浏览器「平移」到终端。这种抽象能力，正是 Ink 的核心价值。

四、Terminal 特有的问题，Ink 怎么应对？

终端和浏览器差异很大：没有鼠标、没有滚动条、内容可能无限增长、窗口可能被 resize。Ink 针对这些场景提供了一些机制。

无鼠标：键盘优先的交互模型

终端里没有可靠的「点击」语义，交互主要靠键盘。Ink 用 useInput 监听 stdin 的按键事件，把 key.upArrow、key.downArrow、key.return、key.tab 等暴露出来。焦点切换则依赖 useFocus 和 useFocusManager：你声明哪些区域是可聚焦的，用户用 Tab 在它们之间切换，当前焦点区域才能接收 useInput 的事件。

这种「键盘 + 焦点」的模型和 Web 的「鼠标 + 键盘」不同，需要你显式设计 Tab 顺序和快捷键。例如用 useFocus 声明可聚焦区域，Tab 在它们之间切换，当前焦点用边框高亮：

1
2
3
4
5
6
7
8
9

const Pane = ({ label }) => {
  const { isFocused } = useFocus();
  return (
    <Box borderStyle="single" padding={1} borderColor={isFocused ? 'green' : 'gray'}>
      <Text>{isFocused ? '▶ ' : '  '}{label}</Text>
    </Box>
  );
};
// 多个 Pane 时，Tab 按渲染顺序切换焦点；聚焦中的 Pane 才能收到 useInput 事件

实际效果（两个 Pane，左侧聚焦：边框高亮 + ▶ 标记；右侧未聚焦为灰色边框。按 Tab 焦点在两者间切换）：

一些终端支持鼠标事件（如 xterm 的 SGR 协议），但跨终端兼容性差，Ink 的设计以键盘为中心，这也是大多数 CLI 工具的共识。

不断增长的内容：Static 与 overflow

AI 对话、日志输出这类场景的特点是：新内容不断追加，旧的不会消失。如果每次都全树重绘，历史消息会被重复渲染，而且可能超出终端高度。

Ink 提供了 <Static> 组件专门处理这种「只增不减」的内容。Static 接收一个 items 数组，用 render 函数渲染每一项。关键是：已经渲染过的 item 不会被重新渲染，只会把新 item 追加到输出里。这样历史消息「钉」在终端上方，新的往下长，底部的动态区（比如输入框、进度条）照常更新。Gatsby 的构建输出、Tap 的测试列表都是这么做的——这不是我编的，Ink 源码 Static.js 的注释里自己就是这么举例的。

1
2
3
4
5
6
7
8
9
10
11

<Static items={messages}>
  {msg => (
    <Box key={msg.id}>
      <Text color="gray">{msg.role}: </Text>
      <Text>{msg.content}</Text>
    </Box>
  )}
</Static>
<Box marginTop={1}>
  <Text>输入: {input}</Text>  {/* 动态区，每次更新都重绘 */}
</Box>

上面这段的渲染效果（messages 是模拟数据）：

对于有固定高度的区域，Box 支持 overflow="hidden" 或 overflow="visible"，可以裁掉超出部分。但 Ink 目前**没有 overflow="scroll"**，也就是没有内置的「滚动视窗」——你不能在一个固定高度的 Box 里用方向键滚动查看超长内容。社区有 ink-scroll-view 等库做类似事情，但需要自己实现 windowing 逻辑（只渲染可见区域 + 维护 scroll offset）。

终端尺寸变化与光标

useWindowSize 可以拿到当前终端的行数和列数，配合 stdout.on('resize') 能在用户拖拽窗口时重新布局。useCursor 则用于控制光标的显示和位置，比如在输入框里让光标出现在正确的位置。

另外，当输出行数超过终端高度时，Ink 会清屏再重绘（这正是前面说的 shouldClearTerminalForFrame 要处理的 overflow 场景），而不是像 docker-compose logs -f 那样让内容自然向上卷动。这是 Ink 的设计选择：它假设你是「应用式」的全屏 TUI，而不是流式日志查看器。

五、为什么 React 心智适合 Terminal UI？

1. 组件化天然契合面板式布局

TUI 的典型结构就是多块「面板」：对话区、日志区、状态栏、输入框……每一块都可以抽成组件，用 props 控制展示内容，用 state 控制展开/折叠、选中项等。这和我们在 Web 里拆 Sidebar、ChatArea、InputBar 的思路完全一致。

2. 状态复杂时声明式更可控

AI 工具要展示的内容非常动态：对话在增长、工具在运行、进度在更新。用命令式的 process.stdout.write + 光标控制，很容易写出难以维护的意大利面。而 React 的「state → view」单向数据流，让每次渲染都是当前状态的完整快照，逻辑清晰得多。

3. 生态与调试

Ink 是 React renderer，所以可以用 React DevTools 检查组件树——devtools.js 会探测 ws://localhost:8097，发现 DevTools 在跑就连上去。测试也可以用 React Testing Library 的思路，对组件做快照或行为测试。对已经深度使用 React 的团队来说，这是巨大的效率加成。

六、在受限介质中坚持审美

终端没有像素级自由，没有阴影和圆角（除非用 Unicode 和块字符模拟），色彩也受限于 256 色或真彩。但「前端之美」的本质不是特效堆砌，而是信息层次、留白、对齐、一致性。这些在终端里同样可以做到。

留白与间距

Ink 的 padding、margin、gap 和 Flexbox 的 justifyContent、alignItems 让你可以精确控制空白。不要塞满每一列，适当的留白能让界面更易读。例如：

1
2
3
4

<Box flexDirection="row" gap={2}>
  <Box padding={1}><Text>左</Text></Box>
  <Box padding={1}><Text>右</Text></Box>
</Box>

实际输出（gap={2} 让两个内容块之间留出两格空白，配合 padding 让文字不贴边）：

色彩与层次

Text 的 color、backgroundColor、bold、dimColor 可以建立清晰的视觉层次。一个简单约定：标题用亮色 + 粗体，次要信息用 dimColor，成功/错误/警告分别用绿/红/黄。例如：

1
2
3
4
5
6

<Box flexDirection="column" gap={1}>
  <Text bold color="cyan"># 构建完成</Text>
  <Text color="green">  ✓ 编译通过</Text>
  <Text color="red">  ✗ 测试失败: spec/a.test.js</Text>
  <Text dimColor>  耗时 2.3s</Text>
</Box>

实际输出：

Ink 底层用 chalk，支持 green、#005cc5、rgb(232, 131, 136) 等写法。避免到处高亮，保持克制的配色，终端里的层次感会明显提升。

动效与反馈

终端里没有 CSS 动画，但可以借助状态驱动的重绘，做出「活着」的感觉。这里举几个具体例子。

Spinner：用社区库 ink-spinner，几行代码就能在加载时显示旋转动画：

1
2
3
4
5
6
7
8
9
10
11

import React from 'react';
import { render, Text } from 'ink';
import Spinner from 'ink-spinner';

const Loading = () => (
  <Text>
    <Text color="green"><Spinner type="dots" /></Text>
    {' 正在拉取...'}
  </Text>
);
render(<Loading />);

实际效果：

Spinner 内部用 setInterval 切换不同字符（如 ⠋ ⠙ ⠹ …），触发 React 重绘，视觉上就是旋转。type 可选 dots、line、arrow 等，来自 cli-spinners。

进度条：用 Box 的 width 配合百分比，就能模拟进度条宽度变化：

1
2
3
4
5
6

const ProgressBar = ({ percent = 50 }) => (
  <Box width={20} flexDirection="row">
    <Box width={`${percent}%`} backgroundColor="green"><Text> </Text></Box>
    <Text color="gray"> {percent}%</Text>
  </Box>
);

效果：

每次 percent 变化，Ink 会重绘，绿色区域「长」一截。这是很多 CLI（如 npm install）的常见模式。

光标：useCursor 可以控制光标位置和显隐。输入框里让光标出现在正确位置、等待输入时让光标闪烁，都能增强交互反馈。Gatsby 构建时的进度条 + 已完成页列表，就是 Static + 动效组合的典型。

七、动手试试：资源与示例

如果你对 Ink 产生了兴趣，官方和社区有大量现成资源可以快速上手。

Useful Components

Ink 官方文档整理了 Useful Components，都是经过验证的社区库，可直接 npm install 使用：

这些组件覆盖了 TUI 里最常见的交互模式。比如做一个「选择模板」的 CLI，用 ink-select-input 几分钟就能搭起来；展示代码片段用 ink-syntax-highlight，和 IDE 的终端预览体验类似。

官方 Examples

Ink 仓库的 examples 目录提供了可运行的示例，用 npm run example examples/[name] 即可体验：

• Counter：每 100ms 自增的数字，就是前文用来解释渲染流程的那个
• Jest：模拟 Jest 的测试输出 UI，Static + 动态进度
• Table：多列表格，感受 Flexbox 在终端里的对齐
• Focus management：用 useFocus 做 Tab 切换，多个可聚焦区域
• User input：useInput 监听键盘，实现简单输入
• Static：Gatsby 风格的「已完成项在上方累积 + 底部动态更新」
• Suspense：异步数据加载 + Suspense 边界
• Router：用 React Router 的 MemoryRouter 做「页面」切换

这些示例都是完整的、可运行的，建议克隆 ink 仓库后逐个跑一遍，比读文档直观得多。

5 分钟上手路径

1. npx create-ink-app my-cli 或 npx create-ink-app --typescript my-cli
2. 在 ui.tsx 里把默认组件改成前文的 Counter 或迷你布局
3. npm run build && npm start 看效果
4. 装上 ink-spinner，加一个 Loading 组件
5. 打开 examples 挑一个感兴趣的，对照源码改一改

八、Ink 的局限（选型参考）

了解这些，有助于你在「是否用 Ink」和「如何设计」时做出更合适的决策。它们不影响 Ink 作为 TUI 方案的价值，但值得在选型时纳入考量。

全量重绘与性能

每次 state 变化，帧都要整帧重新生成——组件树越深、节点越多，这一趟越贵；好在写入终端是 diff 的，且 maxFps（默认 30）会节流渲染频率。组件树深、更新频繁时，仍可能出现卡顿。建议：用 Static 分离只增不减的内容、对昂贵计算用 useMemo、必要时调低渲染频率。Ink 提供 incrementalRendering（按行增量写入）和 maxFps 两个旋钮，可以按需开启。

内存占用

Ink 依赖 Node、React、Yoga（含 WASM），内存比纯原生 CLI 高一截。我在 Node 24 上实测：空跑 node 本身 RSS 约 40MB，加载 Ink 7.1.1 + React 19 跑一个最小 Counter 应用后，RSS 约 100MB。网上常说的「打包后 32MB」其实是指安装体积，不是内存。对比 Go 的 Bubble Tea：编译产物是一个几 MB 的静态二进制，跑起来内存通常也小一个数量级。对本地 CLI、AI 工具通常可接受；资源受限环境需权衡。

功能边界

• 无 overflow: scroll：长列表滚动需自己实现或借助 ink-scroll-view
• CJK / IME：中文输入法下可能有延迟或光标错位
• Windows：部分终端 ANSI 支持不完整

九、结语：介质在变，美感永恒

前端之美的初心，是追求更好的人机交互——清晰的视觉层次、流畅的反馈、符合直觉的操作。这份追求并不局限于浏览器。当 AI 工具、DevTools、云开发环境越来越依赖终端时，Terminal UI 就成了新的战场。

Ink 的价值在于：它让 React 开发者无需切换心智，就能在终端里延续同样的设计语言和工程实践。Flexbox、组件、Hooks——这些你早已掌握的前端技艺，在终端里依然有效。

还有一件小事，我想留作彩蛋：这篇文章里每一处标注「实测」的地方——那张 60 列宽的真实渲染帧、reconciler.js 里的 host config、还有那串 102MB 的内存数字——都是我在终端里一条命令一条命令跑出来的。 而你现在读到的这篇文章，同样是在终端里写完、构建、发布的；连帮我写它的 AI 工具，界面本身也是 Ink 画的。一个关于终端的故事，正坐在终端里被讲述——这大概就是「介质在变，美感永恒」最好的注脚：终端从来不是限制，它只是另一块画布。

如果你对 Terminal UI 感兴趣，不妨从 Ink 开始。用你熟悉的 React，在 80x24 的字符画布上，做一点既实用又好看的东西。这也是前端之美的一种延续。

参考文献与延伸阅读

• Ink - React for CLIs
• Ink - Who’s Using Ink?（README 官方用户名单）
• Ink 源码（src 目录：reconciler / dom / renderer / ink / log-update）
• Ink - Useful Components
• Ink - Examples
• react-reconciler - React 的协调器
• Yoga - Cross-platform layout engine
• Claude Code - Anthropic’s agentic coding tool
• Building rich command-line interfaces with Ink and React

本文源码引用与实测数据基于 Ink 7.1.1 + React 19.2.8（Node 24），版本不同时实现细节可能有出入。

这个问题从 AI Coding 工具开始真正进入工程实践以来，就一直萦绕在很多程序员的心头。虽然 GitHub Copilot 早在 2021 年就已发布，Cursor 也在 2023 年面世，但 2024 年大家并没有很认真地对待 AI coding，主要还停留在代码补全和测试用例生成等简单场景。然而到了 2025 年，随着 Claude Code 等新工具的推出，AI 在编程辅助上的应用真的变得广泛起来，从最初只能做简单的代码补全，到现在可以连续数小时不间断地生成相对完善的实现，这种变化让程序员的焦虑也在不断加剧。

作为一个在技术行业摸爬滚打多年的程序员，我想分享一个可能和主流焦虑不太一样的观点：AI 时代不仅不会让程序员失业，反而会需要更多的程序员——但前提是，我们必须学会与新的生产力工具共舞，升级自己的技能和思维方式。

背景：AI Coding 的快速发展与程序员的焦虑

正如前面提到的，AI Coding 工具在 2025 年迎来了快速发展，进步速度超出了很多人的预期。根据公开的数据，微软内部已经有约 20-30% 的代码由 AI 模型生成，而且这个比例还在快速上升。

与此同时，程序员的焦虑也在不断加剧。很多人在担心：

• 初级程序员的工作会不会被完全替代？
• 只会写代码的程序员还有没有价值？
• 我应该学习什么技能才能不被淘汰？

这种焦虑并非空穴来风。美国劳工统计局的数据显示，在过去两年里，”程序员”（programmers）这一被定义为专门执行编码任务的岗位数量下降了超过 25%。而那些更偏向”开发者”（developer）、”系统设计”、”架构”、”产品工程”的岗位减少得要少得多。

但我想说的是，这个数据背后隐藏的，可能不是”程序员被淘汰”的故事，而是”程序员角色正在重塑”的故事。

我的观点：AI 会让程序员有更多问题可解决

一句话总结我的观点：AI 时代会让程序员有更多的问题可以去解决，技术普惠会激发出远比之前软件行业大得多的场景，不过编程技能需要匹配新的 AI 生产力。

马车到汽车时代的跃迁

让我用一个形象的比喻来说明这个观点。

在汽车出现之前，马车是主要的交通工具。马车车夫需要掌握驾驭马的技能：如何让马听话、如何喂马、如何护理马车等等。当汽车出现后，虽然马车并没有立刻消失，但整个交通行业发生了翻天覆地的变化：

• 出行需求指数级增长：因为汽车让出行变得便捷，越来越多的人有了出行的需求。旅游、物流、通勤、商业活动，这些在马车时代只有少数人能享受的服务，在汽车时代变成了大众需求。
• 新职业和新机会涌现：汽车司机、汽车修理工、加油站员工、道路建设者、交通规划师……这些在马车时代不存在的职业，在汽车时代大量涌现。
• 技能要求的转变：那些固守驾驭马技能、拒绝学习开车的人，最终被淘汰。而那些学会驾驶汽车、理解引擎原理、懂得交通规则的人，迎来了新的机会。

AI Coding 工具的出现，就像汽车替代马车一样，正在重塑整个软件行业：

• 重复性、模板化的代码编写（就像驾驭马的技能）正在被 AI 工具大量替代
• 但新的需求正在爆发：因为写代码的门槛降低，更多行业、更多场景、更多个人和组织开始需要软件解决方案
• 程序员需要掌握的技能在转变：从”写代码”转向”定义问题、设计方案、确保质量、理解业务”

为什么会有更多问题需要解决？

这个观点听起来可能有些反直觉，但让我用几个例子来说明：

1. 技术普惠带来的需求爆发

当写代码的门槛大幅降低后，许多之前因为成本太高而无法实现的需求，现在变得可行了。比如：

• 企业内部的小工具、自动化脚本、数据报表，这些在以前需要专门立项、分配开发资源的工作，现在可能一个懂业务的员工用 AI 工具就能快速实现
• 传统行业的数字化转型：农业、制造业、服务业等传统行业，现在可以更容易地用软件来改造自己的业务流程
• 个人和小团队的创意项目：一个想法可以快速用 AI 工具做出原型，验证市场需求

这些需求的爆发，意味着需要更多的程序员来：

• 将这些原型工程化、产品化
• 设计系统架构，确保可扩展性和可维护性
• 处理性能、安全、合规等复杂问题
• 理解业务需求，将技术方案转化为商业价值

2. 质量、安全、可维护性的要求提升

AI 工具可以快速生成代码，但这些代码往往存在一些问题：

• 代码质量参差不齐，需要人工审查和重构
• 边界条件和异常处理可能不完善
• 安全漏洞和性能问题需要专业人员的识别和修复
• 代码的可维护性和可理解性需要架构师和资深工程师来保证

实际的研究数据也印证了这一点：即使是当前最先进的 AI Coding 工具（如 Claude Code），虽然让开发者写代码的速度大幅提升，但经验丰富的开发者在代码审查、重构和维护上的负担也显著增加。这说明，AI 生成代码的”量”在增加，但”质”的把关仍然需要人类程序员（具体案例见后文的详细分析）。

3. 新场景和新问题的涌现

AI 工具本身也带来了新的问题和挑战：

• 如何评估 AI 生成代码的正确性？
• 如何设计 prompt 让 AI 生成更好的代码？
• 如何将 AI 工具集成到现有的开发流程中？
• 如何处理 AI 工具带来的法律、伦理、安全等问题？

这些问题都需要程序员来解决，而且这些问题的复杂度和重要性，可能比传统的”写代码”更高。

深刻例子：知名程序员的思考

让我分享一些知名程序员和技术领袖的观点，这些观点帮助我们更好地理解这个变化。

Redis 之父 Antirez 的观察

Antirez 在最近的文章中分享了他的观察。他承认自己广泛使用 LLM 来提升编程速度、减少重复性劳动，但他也强调：

“AI 在创造性、打破常规和设想非常规解法方面，还远远落后于人类程序员。”

Antirez 提到，在面对一些需要跳出框架思考的问题时，AI 往往无法像人类程序员那样设想出那些”奇特但高效”的解决方案。这说明，虽然 AI 可以处理很多常规的编程任务，但在创新和解决复杂问题方面，人类程序员仍然有不可替代的价值。

同时，Antirez 也指出：”在绝大多数情况下，写代码本身已经不再是必要的工作了。”这个判断指向了一个重要的转变：程序员的工作重点正在从”写代码”转向”定义问题、设计方案、确保质量”。

微软 CTO 的预测

微软 CTO Kevin Scott 预测，在未来五年内，大约 95% 的代码将由 AI 来生成。但他强调，这并不意味着”程序员将被淘汰”。相反，程序员的任务将从”写每一行代码”转向：

• 设定目标和需求
• 设计方案和架构
• 监督代码质量
• 负责系统整体和边界把控

这个预测和 Antirez 的观察不谋而合：代码的”写”这个动作可能会被 AI 大量替代，但”设计”、”审查”、”优化”、”维护”这些更高层次的工作，仍然需要人类程序员。

OpenAI 前研究负责人的观点

Bob McGrew（OpenAI 前研究负责人）提出了”vibe coding”的概念，指的是通过自然语言提示让 AI 生成代码原型的方式。他发现，虽然这种方式让产品经理等非技术人员能够快速做出原型，但这些原型往往需要被重写，因为：

• 代码的可维护性不足
• 架构设计不够合理
• 边界条件和异常处理不完善
• 性能和安全性问题

这说明，AI 可以快速生成”能跑”的代码，但要生成”能用”、”好用”、”可靠”的代码，仍然需要经验丰富的程序员来把关和重构。

历史类比：从汇编语言到高级语言的转变

回顾编程语言的发展历史，我们也能看到类似的模式。早期程序员需要用汇编语言编写代码，直接操作寄存器、内存地址等底层细节。随着高级语言（如 C、Java、Python）的出现，很多底层的”写代码”工作被抽象化了。

但结果是什么呢？程序员并没有消失，反而数量大幅增加。因为：

• 需求爆发：高级语言降低了编程门槛，更多行业、更多场景开始需要软件
• 新角色涌现：编译器工程师、运行时工程师、框架开发者、架构师等新角色大量出现
• 技能要求提升：程序员需要理解更高层次的抽象，设计更复杂的系统

从汇编到高级语言的转变，和从手写代码到 AI Coding 的转变，本质上是相似的：都是生产力的跃升，都带来了需求的爆发和角色的重塑。

一个真实的案例：Claude Code 和 Cursor 的当前实践

在 2026 年初，Claude Code 和 Cursor 代表了当前 AI Coding 工具的最前沿水平。这些工具的实际应用情况，更能说明 AI Coding 对程序员工作的真实影响。

以 Claude Sonnet 4.5 为例，这是 Anthropic 在 2025 年 9 月发布的最新版本。它在软件工程基准测试（如 SWE-Bench Verified）上表现显著提升，尤其在可靠性、重构和生产环境准备任务上有很大进步。更重要的是，它能够连续自主运作长达 30 小时，这意味着在处理大型、跨文件、跨模块的复杂任务时，Claude Code 比早期工具更稳定、更强大。

实际使用中，开发者发现：

• 速度和质量的双重提升：Claude Code 在原型开发速度上远超早期工具。描述完整功能（如认证系统、支付集成、Dashboard 界面）后，Claude Code 可以在几分钟内生成可工作的代码原型，而且代码结构清晰、带有注释和边界情况考虑
• 跨文件重构能力：Claude Code 在上下文保持和跨多个文件重构方面表现突出，能在保持整个项目结构理解的情况下处理大型重构任务，这是早期工具因上下文窗口限制而难以做到的
• 审查负担仍然存在：虽然 AI 生成的代码质量更高，但经验丰富的开发者仍然需要在代码审查、架构设计、性能优化等方面投入大量时间。Anthropic 内部的数据显示，虽然约 90% 的普通、重复性代码由 AI 撰写，但那些最复杂、有创新性、需要判断的部分仍然需要人类开发者

这个案例揭示了一个重要的事实：即使是最先进的 AI Coding 工具，也提升了代码的”产量”和”质量”，但仍然增加了代码”质量把关”和”架构设计”的需求。那些能够审查、优化、重构 AI 生成代码，并设计整体系统的程序员，反而变得更加重要。

我的实践：从数据看工作流程的转变

作为一个在技术行业工作多年的程序员，我也想分享一些自己的实践数据，这些数据可能更能说明 AI Coding 工具对实际工作的影响。

在过去的 2025 年下半年，我写了十五万行代码，同比增长 30 多倍，其中 95% 以上是 Coding Agent 写的。这个数据背后反映的，不是”我变懒了”，而是工作流程的根本性转变：

• 更多时间花在定义问题和设计方案：我更多关注在定义问题，然后先做 tech design 文档，而在 coding 阶段主要交给 coding agent，这部分能够帮我省掉大量时间。
• Code review 的重要性提升：虽然大部分代码由 AI 生成，但 code review 我会和 AI 一起来做，尤其是核心模块。目前坦白来说，coding agent 还没有完全达到资深工程师的水准，产出不太稳定，需要持续反馈。

这个实践印证了前面提到的观点：AI 工具确实大幅提升了代码的”产量”，但同时也让”定义问题”、”设计方案”、”质量把关”这些工作变得更加重要。那些能够与 AI 协作、持续反馈、确保代码质量的程序员，反而能够产出更多、更有价值的代码。

对程序员的建议：如何适应 AI Coding 时代

结合我自己的观察和思考，我想给正在焦虑的程序员一些真诚的建议。这些建议不是空泛的鼓励，而是基于实际观察和思考得出的实用方向。

1. 从”写代码”转向”定义问题”

AI 工具很擅长执行你明确说清楚的任务，但如果你定义不清，AI 的输出往往也不理想。因此，定义问题的能力变得前所未有的重要。

具体来说：

• 参与需求调研：不要只是等需求明确后再开始编码，而是要主动参与需求讨论，理解业务背景和用户痛点
• 写清晰的验收标准：在开始编码前，明确功能边界、成功标准、错误处理方式等
• 问正确的问题：这个功能为什么要做？用户真正需要什么？如果失败了会怎样？这些问题能帮助你更好地定义问题，也能让 AI 工具生成更符合需求的代码

我观察到，在过去一年里，那些更容易适应 AI Coding 的程序员，往往都是那些更善于定义问题、理解需求的人。Tech Lead、架构师、hands-on manager、从程序员转产品的同事，他们之所以更容易适应，很大程度上是因为他们离真实需求更近，能够更好地判断 AI 生成代码是否符合需求。

2. 提升架构设计和系统思维能力

随着很多”写代码”的工作被 AI 自动化，系统设计和架构思维成为了程序员的核心竞争力。

具体来说：

• 学习经典架构模式：微服务、事件驱动、领域驱动设计等
• 理解系统权衡：性能 vs 可维护性 vs 安全性 vs 扩展性，如何在不同的场景下做出合适的权衡
• 阅读优秀项目源码：理解大型开源项目的组织结构和设计思路
• 参与设计评审：在团队中承担或参与架构设计评审，学习如何从全局视角思考问题
• 培养全栈能力：在 AI 的助力下，学习和掌握与当前方向技术关联的新领域变得更加容易。后端开发者可以借助工具做出不错的前端或移动应用，前端开发者也可以轻松地做一些后端和数据库功能。各工种之间的边界变得更加模糊，具备能够交付整体方案能力的程序员会更有竞争力，因为避免了大量的跨团队沟通和协调成本

AI 工具可以帮你写单个模块的代码，但如何将这些模块组合成一个可靠、可扩展、可维护的系统，如何跨越前后端、移动端等不同技术栈的边界，交付完整的解决方案，这仍然需要人类的系统思维、架构能力和全栈视野。

3. 掌握与 AI 工具协作的能力

既然 AI 工具已经成为新的生产力工具，那么掌握如何与 AI 工具有效协作就成为了必备技能。

具体来说：

• 学习 prompt engineering：如何写出能让 AI 生成高质量代码的 prompt，如何根据反馈不断调整
• 理解 AI 工具的局限：当前的 AI 工具依然基于大量现有代码实现来训练和模拟，对于特定领域的新问题、创新性需求或缺乏训练数据的场景，可能不具备很好的适配性，需要大量人工介入和调整。了解不同 AI 工具的能力边界，知道什么时候该用 AI，什么时候该自己写，这是有效协作的关键
• 建立审查和验证机制：不要盲目信任 AI 生成的代码，要建立代码审查、测试、静态分析等质量保障机制
• 实践 AI 工具链：将 AI 工具集成到你的工作流程中，但不要让流程完全依赖 AI，保持人类的主导权

我建议每个程序员都应该主动尝试不同的 AI 编程工具，记录哪些 prompt 效果好，哪些场景下 AI 容易出错，这样你就能更好地利用这些工具，而不是被工具牵着走。

4. 加强质量意识和测试能力

AI 生成的代码虽然速度快，但质量往往参差不齐。因此，质量把关和测试能力变得尤为重要。

具体来说：

• 编写全面的测试用例：单元测试、集成测试、端到端测试，确保 AI 生成的代码在各种场景下都能正确工作
• 建立代码审查流程：重点关注边界条件、异常处理、性能瓶颈、安全隐患等 AI 容易忽略的地方
• 学习测试驱动开发：先写测试，再让 AI 生成代码，这样可以更好地验证代码的正确性
• 关注非功能性需求：性能、安全、可维护性、可扩展性等，这些往往是 AI 生成代码的薄弱环节

正如前面提到的 Claude Code 案例所示，AI 辅助编程虽然提升了代码的生成速度和质量，但也增加了代码审查和维护的负担。这说明，质量把关的工作不仅没有减少，反而变得更加重要。

5. 向高阶角色和跨职能方向发展

在过去一年里，我发现Tech Lead、架构师、hands-on manager、从程序员转产品的同事，他们更容易适应 AI Coding 时代。这是因为：

• 他们有代码背景，能够判断 AI 生成代码的质量和正确性
• 他们离真实需求更近，能够更好地定义问题和验收标准
• 他们具备系统思维和架构能力，能够设计整体方案
• 他们理解业务，能够将技术方案转化为商业价值

因此，我建议程序员可以：

• 争取参与或主持设计评审：学习如何从全局视角思考问题
• 理解产品策略和业务逻辑：不只是实现功能，还要理解为什么要做这个功能
• 学习业务知识：了解你所在行业的痛点和需求，这样你才能更好地定义问题
• 积累跨职能协作经验：与产品、设计、运营等角色协作，理解不同角色的视角和需求

6. 保持学习的心态

最后，也是最重要的一点：保持学习的心态。AI Coding 工具还在快速迭代，新的工具、新的模式、新的最佳实践不断涌现。只有保持学习，才能跟上这个变化的时代。

具体来说：

• 关注行业动态：了解最新的 AI 工具和技术趋势
• 实践新技术：不要只是看，要动手实践，在实际项目中尝试新的工具和方法
• 分享和交流：与同事分享使用 AI 工具的经验和教训，共同成长
• 不要忽视基础：数据结构、算法、系统原理等基础知识仍然重要，当系统复杂、性能要求高、安全性敏感时，这些基础知识能帮助你做出正确的判断

总结

回顾整篇文章，我的核心观点其实很简单：AI 时代不仅不会让程序员失业，反而会需要更多的程序员。技术普惠会激发出远比之前软件行业大得多的场景和需求，但前提是，我们必须学会与新的生产力工具共舞，升级自己的技能和思维方式。

就像马车到汽车的跃迁一样，那些固守旧技能的人会被淘汰，但那些学会驾驭新工具、理解新规则的人，会迎来更大的机会。从汇编语言到高级语言的转变，也证明了这一点：生产力的跃升带来的是需求的爆发和角色的重塑，而不是职业的消失。

对于正在阅读这篇文章的程序员同行们，我想说的是：这个时代的变化确实很快，焦虑是正常的。但与其担心被 AI 取代，不如主动拥抱变化。从今天开始，尝试用 AI 工具解决实际问题，练习定义问题和设计方案，提升架构思维和全栈能力，向高阶角色发展。这些技能不会一夜之间掌握，但每一步的努力，都会让你在这个新时代中更有竞争力。

我相信，那些愿意学习、愿意适应、愿意成长的程序员，不仅不会被淘汰，反而会成为这个时代最稀缺和最重要的人才。让我们一起，成为新时代的”汽车司机”，而不是被淘汰的马车车夫。

参考文献

• Antirez on AI and Programming
• Microsoft CTO on AI-Generated Code
• Bob McGrew on Vibe Coding
• Will AI replace Software Engineers?
• Claude Sonnet 4.5 Extends Coding Lead
• Anthropic Teams Coding with Claude
• Claude Code vs GitHub Copilot Comparison

读完后的感受颇多，很多人都写过主人公自己的背叛和救赎，这篇我想聚焦在另一个主要的角色上：Baba，主人公 Amir 的父亲。

善于经营

文章开篇就介绍了 Amir 家境的优越，而这一切都可以归功于 Baba：

Everyone agreed that my father, my Baba, had built the most beautiful house in the Wazir Akbar Khan district, a new and affluent neighborhood in the northern part of Kabul. Some thought it was the prettiest house in all of Kabul.

Baba proved them all wrong by not only running his own business but becoming one of the richest merchants in Kabul. Baba and Rahim Khan built a wildly successful carpet-exporting business, two pharmacies, and a restaurant.

Baba 不但是一位成功的商人，而且他还非常乐善好施。一个具体的例子就是他投入了巨大的精力和财力，花费了三年时间建设了一座孤儿院。在开业典礼上，Baba 做了一场精心准备的演讲，虽然还有些滑稽的场面，但最终赢得了大家经久不息的热烈掌声。

此外，Baba 还是一位非常活跃的社交家，这一点在 Amir 10 岁生日聚会上体现得淋漓尽致。

Baba’s motto about throwing parties was this: Invite the whole world or it’s not a party. I remember scanning over the invitation list a week before my birthday party and not recognizing at least three-quarters of the four hundred-plus Kakas and Khalas who were going to bring me gifts and congratulate me for having lived to thirteen. Then I realized they weren’t really coming for me. It was my birthday, but I knew who the real star of the show was.

The night before the big party Baba’s friend Del-Muhammad, who owned a kabob house in Shar-e-Nau, came to the house with his bags of spices. Like the butcher, Del-Muhammad – or Dello, as Baba called him – refused payment for his services. He said Baba had done enough for his family already. It was Rahim Khan who whispered to me, as Dello marinated the meat, that Baba had lent Dello the money to open his restaurant. Baba had refused repayment until Dello had shown up one day in our driveway in a Benz and insisted he wouldn’t leave until Baba took his money.

第一次读到这段内容的时候，我脑中浮现的是教父在女儿婚礼上的那一幕幕经典场景，众人环绕，德高望重。

毫无疑问，有如此一位成功的父亲，Amir 是十足幸运的。

思想开明且深刻

作为一个穆斯林国家，那时的阿富汗还认为喝酒是一种罪过，会在将来的审判日受到惩罚。不过 Baba 并不这么认为：

“They do nothing but thumb their prayer beads and recite a book written in a tongue they don’t even understand.” He took a sip. “God help us all if Afghanistan ever falls into their hands.”

他对于这些只会对着古兰经牵强附会的教条主义者嗤之以鼻。同时，他对于罪有一种更深的洞见：

“Good,” Baba said, but his eyes wondered. “Now, no matter what the mullah teaches, there is only one sin, only one. And that is theft. Every other sin is a variation of theft. Do you understand that?”

“When you kill a man, you steal a life,” Baba said. “You steal his wife’s right to a husband, rob his children of a father. When you tell a lie, you steal someone’s right to the truth. When you cheat, you steal the right to fairness. Do you see?”

“There is no act more wretched than stealing, Amir,” Baba said. “A man who takes what’s not his to take, be it a life or a loaf of naan… I spit on such a man. And if I ever cross paths with him, God help him. Do you understand?”

“If there’s a God out there, then I would hope he has more important things to attend to than my drinking scotch or eating pork. Now, hop down. All this talk about sin has made me thirsty again.”

我自己出生在一个天主教家庭，祖上因为过于贫穷接受了教会的救济后入了教。对于圣经上的很多内容，还有时不时一些人宣扬的类似月亮后面有个巨大的十字架之类的圣迹，我个人也是持类似的态度。不过我也认为如果真的有神明，而且人真的有死后的生活，那么应该会公正地奖惩分明些吧。

对少时儿子的隐忧

作为父亲，Baba 非常疼爱 Amir，甚至有时候对他有些严格。并且，像所有父亲一样，Baba 也观察到儿子的一些不足之处：

“Sometimes I look out this window and I see him playing on the street with the neighborhood boys. I see how they push him around, take his toys from him, give him a shove here, a whack there. And, you know, he never fights back. Never. He just… drops his head and…”

“So he’s not violent,” Rahim Khan said.

“That’s not what I mean, Rahim, and you know it,” Baba shot back. “There is something missing in that boy.”

“You just need to let him find his way,” Rahim Khan said.

“And where is he headed?” Baba said. “A boy who won’t stand up for himself becomes a man who can’t stand up to anything.”

从一再出现的懦弱表现来看，Baba 开始对 Amir 的性格有些担忧，因为他觉得不能为自己挺身而出的人也不会为任何其他事情去奋争。这也预示了 Amir 未来必须面对的挑战。Baba 的这一评价对 Amir 产生了深远的影响，成为他成长过程中不断反思和努力改变的动力。

疼爱 Hassan

Amir 年少时对于 Hassan 是有一些羡慕嫉妒恨的，这其中极大一部分原因来自于 Baba 对 Hassan 不合逻辑的疼爱，远超一般主仆关系的界限。

一个典型的例子就是：Baba 从来不会忘记 Hassan 的生日：

Baba never missed Hassan’s birthday. For a while, he used to ask Hassan what he wanted, but he gave up doing that because Hassan was always too modest to actually suggest a present. So every winter Baba picked something out himself.

另一个例子是在 Amir 跟父亲提及是不是用新仆人换掉 Ali 的时候，Baba 怒不可遏，说了很严厉的一些话：

“Hassan’s not going anywhere,” Baba snapped. He dug a new hole with the trowel, striking the dirt harder than he had to. “He’s staying right here with us, where he belongs. This is his home and we’re his family. Don’t you ever ask me that question again!”

这些行为让 Amir 感到了深深的不安和嫉妒，进一步导致了后面的诬陷 Hassan 的事件。

逃亡路上的英勇之举

在阿富汗战乱中，Baba 不得不带着 Amir 开始了逃亡之旅。在经过一个检查站的时候，面对一个俄国士兵的无理要求，Baba 奋不顾身地挺身而出：

That was when Baba stood up. It was my turn to clamp a hand on his thigh, but Baba pried it loose, snatched his leg away. When he stood, he eclipsed the moonlight. “I want you to ask this man something,” Baba said. He said it to Karim, but looked directly at the Russian officer. “Ask him where his shame is.”

在对方威胁要枪毙他的时候，Baba 仍然据理力争：

“Tell him I’ll take a thousand of his bullets before I let this indecency take place,” Baba said. My mind flashed to that winter day six years ago. Me, peering around the corner in the alley. Kamal and Wali holding Hassan down. Assef’s buttock muscles clenching and unclenching, his hips thrusting back and forth. Some hero I had been, fretting about the kite. Sometimes, I too wondered if I was really Baba’s son.

这样的举动让懦弱的 Amir 深深触动，他不禁想到六年前 Assef 他们欺辱 Hassan 的时候，如果他更勇敢一些会怎么样，他甚至怀疑自己是不是 Baba 的亲生骨肉。我相信这样惊心动魄的经历也是让 Amir 后面踏上救赎之路的重要因素，Baba 的精神激励和鼓舞了他。

努力支撑在美国的移民生活

为了让 Amir 享受到更好的教育，父子俩移民到美国。一开始的生活并不容易，Baba 在大家的帮助下找到了加油站的工作，工作非常努力，即便是 996 也绝无抱怨。

“It’s not so bad now,” he said, meaning since he had become the day manager at the gas station. But I’d seen the way he winced and rubbed his wrists on damp days. The way sweat erupted on his forehead as he reached for his bottle of antacids after meals. “Besides, I didn’t bring us here for me, did I?”

对美国有更多熟悉后，Baba 善于经营的头脑再次发挥了重要作用。他找到了周末做二手货生意的好路子：

On Saturdays, Baba woke me up at dawn. As he dressed, I scanned the classifieds in the local papers and circled the garage sale ads. We mapped our route – Fremont, Union City, Newark, and Hayward first, then San Jose, Milpitas, Sunnyvale, and Campbell if time permitted. Baba drove the bus, sipping hot tea from the thermos, and I navigated. We stopped at garage sales and bought knickknacks that people no longer wanted. We haggled over old sewing machines, one-eyed Barbie dolls, wooden tennis rackets, guitars with missing strings, and old Electrolux vacuum cleaners. By midafternoon, we’d filled the back of the VW bus with used goods. Then early Sunday mornings, we drove to the San Jose flea market off Berryessa, rented a spot, and sold the junk for a small profit: a Chicago record that we’d bought for a quarter the day before might go for $1, or $4 for a set of five; a ramshackle Singer sewing machine purchased for $10 might, after some bargaining, bring in $25.

也就是在这样很多阿富汗移民的跳蚤市场上，Baba 开始慢慢找回在 Kabul 生活的感觉，结交了越来越多的朋友。

从他后面跟老相识介绍儿子的自豪中，我们可以感受到 Baba 对于儿子热烈的爱：

“Amir is going to be a great writer,” Baba said. I did a double take at this. “He has finished his first year of college and earned A’s in all of his courses.”

对儿子最后的付出

在跳蚤市场上，Amir 结识了 Soraya。两个年轻人非常投缘。Baba 明显看出了端倪，他这样评价 Soraya：

“I hear she is a decent girl, hardworking and kind. But no khastegars, no suitors, have knocked on the general’s door since.” Baba sighed. “It may be unfair, but what happens in a few days, sometimes even a single day, can change the course of a whole lifetime, Amir,” he said.

不知道是不是刻意地安排，这样的叙述让 Amir 在追求 Soraya 上变得更加主动积极了一些。

随后 Baba 被诊断出了小细胞肺癌，他不愿让任何其他人知道，免得大家出于同情而怜悯他。

面对越来越虚弱的父亲，在 Soraya 一家探望之后，Amir 终于鼓足勇气，做出了一个无比正确的决定：

I sat beside him. “Then I wonder if you’ll do something for me. If you’re not too exhausted.”

“What?”

“I want you to go khastegari. I want you to ask General Taheri for his daughter’s hand.”

Baba’s dry lips stretched into a smile. A spot of green on a wilted leaf. “Are you sure?”

“More sure than I’ve ever been about anything.”

Baba 对待儿子的方式一直是尊重，然后让孩子自己做决定，轻易绝不插手。所以，虽然明显看出老人明显想撮合两个年轻人，还是难以想象老父亲听到儿子这一请求时的激动。Amir 开始有一些可以为之而战的事情了，他的儿子，在 22 岁的这一时刻，终于迈出了勇敢的一步。

尽管体力虚弱，Baba 还是精心打扮一番后去上门提亲，并成功地完成了这一作为父亲的重要使命。

“Thank you, Baba. Are you all right? Do you feel up to this?”

“Up to this? It’s the happiest day of my life, Amir,” he said, smiling tiredly.

在婚礼后一个月，Baba 在睡梦中离世。

Hassan 的身世

父亲离世十多年后的 2001 年，他的挚友 Rahim 打来电话，从此 Amir 踏上了营救 Hassan 儿子的救赎之旅。在一封写给 Amir 的信中，Rahim 清晰阐述了 Baba 为何小时候对待 Amir 如此严厉：

Amir jan, I know how hard your father was on you when you were growing up. I saw how you suffered and yearned for his affections, and my heart bled for you. But your father was a man torn between two halves, Amir jan: you and Hassan. He loved you both, but he could not love Hassan the way he longed to, openly, and as a father. So he took it out on you instead – Amir, the socially legitimate half, the half that represented the riches he had inherited and the sin-with-impunity privileges that came with them. When he saw you, he saw himself. And his guilt. You are still angry and I realize it is far too early to expect you to accept this, but maybe someday you will see that when your father was hard on you, he was also being hard on himself. Your father, like you, was a tortured soul, Amir jan.

想必彼时彼刻，Amir 对父亲的理解会更深一个层次吧。Baba 也是在努力救赎自己。

写在最后

为了建立一个对 Baba 更加具象的理解，我后面去看了 Kite Runner 的电影版。里面的 Baba 非常符合我对书中这一角色的印象，聪明、英勇、坚毅、关爱家人。他希望 Amir 和 Hassan 都能成长为有所作为的人，能够为自己而战的男人。他很幸运，在人生的终点之前看到了 Amir 的蜕变。可惜的是，更像他的 Hassan 在战乱中不幸罹难，在一个英勇的举动之后。但这就是人生，只要你去努力了，结果并无所谓。

当师父对我说出这句话的时候，我的第一反应是吃惊和委屈。根据我的了解，Case Study 一般是在发生较大的线上故障后才由当事人总结的。由于我们技术部门刚刚推行这个制度不久，当时只有很少的人写过。因此，我下意识地认为这更多是一种羞辱和惩罚，觉得本来一个不太大的问题会被所有人都知道，自己的面子都挂不住。

师父对我们一直都非常好，幽默风趣，善于授人以渔。他对技术和界面都有着极致的追求。虽然觉得写 Case Study 对这次线上故障有些小题大做，但我还是硬着头皮打开文档平台，开始着手写总结。首先，我简单了解了 Case Study 的文档结构，一般包含：

• 关键事件时间线。主要记录线上故障的发生、发现、处理和解决过程；
• 预估损失。不同的故障所造成的损失也不不尽相同。不过一般可以分为直接损失和间接损失。间接损失主要和 KPI 挂钩；
• 原因分析。要求采用 5 Why 准则来层层递进地分析问题的本源；
• 改进措施。根据之前的分析罗列出来具体的改进措施和负责人。

写完总结后，师父很满意，同时也给了一些建议，并嘱咐我一定要抓紧落实改进措施。这时我开始有些新的认识：他是想让更多人避免类似的问题，而不仅仅是惩罚我。

写 Case Study 最多的人

随着时间的推移，我们之前引入的一些代码检查等措施，提前发现了一些即将上线代码的问题。这让大家对之前的改进有了更多积极的评价。同时，其他业务线上的一些问题也引起老板的关注，他也提出了类似的要求。这些变化让我更深层次地理解了他的动机：让团队变得更强，系统更健壮。至于当事人的声誉，这是见仁见智的。但老板最终还是给我升职加薪了，说明至少在他看来，我的输出还可以，之前线上的问题并没有明显影响我的绩效。

有了这样的经验后，我对 Case Study 的看法逐渐有了转变，认为它不再是一种惩罚，而更多的是一种深入分析问题原因并加以改进的重要手段。这种自我批评、持续迭代的能力对于一个工程师或者一个技术团队来说至关重要。

后来我开始带人，再后来开始带团队，我除了自己也会主动去写 Case Study 以外，也会像我师父一样鼓励团队成员更多地去写。我本人甚至成为技术部门写 Case Study 最多的人之一。相应的，我们的代码质量、开发效率也在稳步提升，团队逐渐形成了一种学习进步的氛围。神奇的是，我们小组的声誉并没有因为写的 Case Study 多就备受诟病。

这里的 Post Mortem 居然连当事人名字都不写

在 Tubi 工作后，我发现这里大家也会去写类似 Cast Study 的文档，名字叫 Post Mortem，中文是“事后剖析”。总体形式和目的都很相像，只有两点不太一样：

• 引入了 Time To Detect, Time To Aware, Time To Engage, Time To Fix 等故障生命周期指标，可以监控和逐步改进故障响应效率；
• 不再提及任何具体的当事人名字。

第一点很容易理解。第二点一开始挺让我吃惊的，整个时间线都在描述具体的事实，没有任何一个公司同事的名字。即便有些地方非常有必要用一个人物作为主语或者宾语，也会用 A Engineer 或者其它方式来指代。后来通过和大家的接触我慢慢理解了这样的用意：避免指责具体的个人，把主要的焦点放在故障本身。联想到之前第一次写 Case Study 的情境，如果我只作为文档的书写者而不必在时间线和责任人里写上自己名字的话，大概也不会感到那么难堪吧。这的确是一个好办法！

公正文化 Just Culture

后来有美国同事跟我推荐了一篇 Just Culture 的文章，顿时有种相见恨晚的感觉，之前模糊的认知被这套已经在航空、医疗等高风险行业实施了很多年的经验一下子变得清晰和深刻起来。

Just culture is a concept related to systems thinking which emphasizes that mistakes are generally a product of faulty organizational cultures, rather than solely brought about by the person or persons directly involved. In a just culture, after an incident, the question asked is, “What went wrong?” rather than “Who caused the problem?”.

Just Culture 是一种组织文化的理念，其核心思想是鼓励组织在处理错误和事故时采取一种公正和合理的态度，而不是简单地追究责任。和 Blame Culture 相对立，这一理念认为事故通常是由多个因素的复杂互动引起的，而不仅仅是个别人员的责任。因此，对于无意的错误和系统性问题，应该以学习和改进为导向，而不是惩罚个别员工。

具体来说，这种文化包含如下要素：

• 采用共享责任的模型：鼓励建立一种共享责任的模型，使整个组织都参与到错误和事故的处理中。这意味着不仅仅是个别人员负责，而是整个团队和组织共同分享责任；
• 从错误中学习而不是责怪个体：强调将错误视为学习的机会，而不是简单地追究责任。通过分析错误的根本原因，组织可以制定改进措施，以防止将来类似的错误发生；
• 管理行为选择：关注并区分人为错误、有风险的行为和鲁莽行为。鼓励组织采取不同的方法来处理这些不同类型的行为，以确保适当的反应和学习；
• 将安全设计纳入系统和流程：强调将安全性集成到组织的所有系统和流程中，而不是仅仅依赖于个体的注意力和警觉。通过设计安全性，可以减少系统性的错误和事故；
• 组织、领导层对共同目标的承诺：这种承诺在组织层面上奠定了文化基石，使得处理错误和事故成为一个合作和学习的过程，而不是惩罚的手段。

总体而言，在 Just Culture 下，团队成员能够更好地理解和接受自己的责任。他们知道他们的行动和决策对整个团队和项目的结果产生影响。这种责任感激励着他们更加谨慎和专注地工作，以减少错误和失误的发生。团队成员之间建立了更强的信任和合作关系，因为他们知道即使犯错，他们也会得到支持和帮助。

对于管理者的挑战

从 Blame Culture 转变到 Just Culture 绝非易事。一方面，人的本性是趋利避害的，大多数人不会轻易地去提出各种潜在的问题。另一方面，准确地区分系统问题、人为失误、鲁莽行为等不同类型的错误极具挑战，团队不同人的认识层次也较难统一。这些挑战都是现实存在的，需要管理者认真思考和应对。

结合我自身的经验，在这里分享几个给管理者的建议：

• 以身作则。作为管理者，是团队成员的标杆。如果能够更多地去认真剖析自己的过失，在系统和流程层面做出改进，就会向大家传达一个强烈的信号：领导也是人，也会犯错，而且愿意和大家分享他当时的经历，并从中汲取教训。领导如果只说不做，大家会有些踌躇、将信将疑。只有领导这样做了，大家才会更加信服，认为这是一种真真切切的鼓励；
• 建立透明的沟通机制：建立一个开放、透明、安全的沟通环境对于 Just Culture 来说至关重要，只有让大家畅所欲言才能把事实越辩越明、挖到足够多足够深入的细节，也让大家参与到团队文化的构建中来。事实上，这对于一个团队的成长来说几乎是最为重要的，需要每个管理者足够重视；
• 平衡责任与学习：在处理错误时，要确保适当的责任被追究，同时也要强调学习和改进。区分人为错误、有风险的行为和鲁莽行为非常有难度，管理者需要制定清晰的标准和流程，以便在面临不同类型的行为时能够做出一致的决策。培训团队成员以更好地理解和评估这些行为也是关键的一步。

总之，Just Culture 在团队建设方面具有重要的益处。它为团队成员提供了一个安全的环境，鼓励他们积极报告错误和失误，并从中学习和改进。同时，实施 Just Culture 也面临不少挑战，需要确保公正和平衡，并培养团队成员的自我反思和学习能力。通过领导者的支持和示范，Just Culture 可以在技术团队中发挥其潜力，促进构建一个持续学习、表现卓越的优秀团队。

参考文献

• Just Culture - Wikipedia
• Just Culture: Balancing Accountability with Quality and Safety
• The Power of Just Culture: Killing the Blame Game

本文尝试由浅入深的介绍 Svelte，希望更多人在适合的场景下可以考虑尝试它。

缘起

Rich 非常喜欢 React 等前端库和框架带来的更加声明式、低心智负担的开发方式，这让前端工程师可以更好地控制复杂度、提升开发效率和质量。然而他也敏锐地洞察到了一些不那么尽如人意之处。

Virtual DOM 真的快吗？

React、Vue 都引入了 Virtual DOM 的概念，从而能够进行现有 DOM 以及期望 DOM 的对比，然后再执行相对较重的 DOM 操作使得两者一致。

在 Virtual DOM is pure overhead 一文中， Rich 指出 Virtual DOM 其实更多的是一种实现声明式、状态驱动 UI 开发的一种手段，并非不可或缺。它主要的问题在于有很多没有必要的 Diff。

举个例子，假设我们有如下一个 React App：

1
2
3
4
5
6
7
8
9
10

function App() {
  const [count, setCount] = useState(0);
  const handleClick = () => setCount(count + 1);
  return (
    <div className="app">
       <p>Count: {count}</p>
       <button onClick={handleClick}>+1</button>
    </div>
  );
}

如果点击一次按钮，新旧 Virtual DOM 对比如下：

虽然只有 p 节点下的文本需要更新，然而，实际上 React 会遍历上述所有的节点，造成不必要的额外开销。

或许很多人觉得纯粹的 JS 运算不会有很显著的开销，不过在页面内容和逻辑足够复杂的情况下这个问题会愈加明显。因此，React 才提供了 useMemo, useCallback 等 Hooks 来避免一些耗时操作的重复执行或者不必要的重复渲染。但这些其实可以视作为一种错误设计的副作用：让开发者需要关注一些本是实现原理层面的技巧，增加了额外的心智负担。

那么是否有一种新的方式，可以在count 变化的时候仅仅更新那一个引用它的 DOM 文本节点呢？ 如果能够做到这一点，那岂不是更加响应式？

Runtime 真的有必要吗？

React、Angular、Vue 等前端框架都有运行时，用以处理用户操作或者数据请求等情况下引发的组件状态变化，尽可能高效率地更新相应 DOM 节点。因此，运行时代码也会被打包到最终产物中。以典型的 TodoMVC 应用举例，我们看一下几种方案下的 JS 包体积：

如果我们以 JavaScript ES6 为基准来衡量其它方案因为运行时而带来的额外包体积来看，那么 Vue 大概是 10 倍，React 大约为 18 倍，Angular 则达到了近 27 倍。

诚然，这些优秀的框架为我们提供了更为便捷和高效的开发方式，而且现在动辄上兆的中大型前端应用比比皆是，更快的网络条件下这区区几十 K 压缩后的 JS 包并不是那么关键。不过，退一步想，如果有一个新的方案可以提供比肩主流框架的特性但是最终包体积接近原生 JavaScript，鱼和熊掌兼得，那岂不是更好？

基本原理

基于以上两点洞见，Rich 开始从另一个全新的角度来重新理解和思考前端框架：

Instead, the reason that ideas like React are so wildly and deservedly successful is that they make it easier to manage the complexity of your concepts. Frameworks are primarily a tool for structuring your thoughts, not your code.
Given that, what if the framework didn’t actually run in the browser? What if, instead, it converted your application into pure vanilla JavaScript, just like Babel converts ES2016+ to ES5? You’d pay no upfront cost of shipping a hefty runtime, and your app would get seriously fast, because there’d be no layers of abstraction between your app and the browser.
Frameworks without the framework: why didn’t we think of this sooner?

他认为前端框架应该是主要用来结构化想法而非代码，它们使得一个应用的种种复杂度能够受到合理的控制。如果我们有办法能够在提供结构化想法的种种功能的同时，在编译阶段将应用源代码转换为接近原生 JS 实现的最终代码，那么就不再需要浏览器和源代码之间的中间抽象层，我们的应用也会运行的更快。

知易行难，虽然有了一个崭新的思路，但是落实在实现层面还会有众多挑战。接下来我们简要介绍下 Svelte 的具体实现。

基于模板的组件

为了能够最大限度地理解和推断开发者的意图，Svelte 采用了模板为先的组件封装方案。每个组件都存储在.svelte 文件中，语法是 HTML 的超集。

下面这个示例把前面的计数器 App 用 Svelte 来重新实现：

1
2
3
4
5
6
7
8
9
10
11
12
13

<script>
  let count = 0;
  const handleClick = () => count += 1;
</script>

<div class="app">
  <p>Count: {count}</p>
  <button on:click={handleClick}>+1</button>
</div>

<style>
  .app { text-align: center }
</style>

完整示例见 Counter App • REPL • Svelte。

看起来真的非常像 Vue，组件的 JS、CSS、HTML 都写在同一文件中集中管理。因此从开发者的角度来看， Svelte 编程方式十分熟悉、自然。

选择模板而非灵活的 JSX 的原因也可以在这个例子中有所体现。编译器很容易发现结构化的视图中 p 元素有一部分文本需要用到count，以及点击按钮时需要调用一个回调函数，其它的部分都是确定的。因此只需在count变更时刷新相应的 DOM 文本节点即可。

为了在有一定约束的情况下提供足够多的功能，Svelte 也提供了一系列的模板语法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<!-- if block -->
{#if answer === 42}
  <p>what was the question?</p>
{/if}

<!-- each block -->
<ul>
  {#each items as item}
    <li>{item.name} x {item.qty}</li>
  {/each}
</ul>

<!-- bind events -->
<form on:submit|preventDefault={handleSubmit}>
  <!-- the `submit` event's default is prevented, so the page won't reload -->
</form>

<!-- bind properties -->
<input bind:value={name} />
<!-- same as <input on:input={e => name = e.target.value} value={name} /> -->

<!-- nested components -->
<script>
  import Widget from './Widget.svelte';
</script>
<div>
  <Widget />
</div> 

Compiler as Framework

在介绍 Svelte 编译器如何工作之前，我们不妨设想：如果让我们自己使用原生 JS 实现上面的计数器 App 的话，会是什么样的呢？

一个可供参考的实现如下（暂时忽略 CSS）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

function App() {
  // Step 1: Declare variables and functions in script tag
  let count = 0;
  const handleClick = () => {
    count += 1;
    lifecycle.update("count"); // Update the DOM nodes related to `count`
  };

  // Step 2: Declare HTML elements
  let div;
  let p;
  let text1;
  let text2;
  let button;
  let text3;

  // Step 3: Declare component lifecycle
  const lifecycle = {
    // Create DOM nodes and mount them under the target node
    create: (target) => {
      div = document.createElement("div");
      p = document.createElement("p");
      text1 = document.createTextNode("Count: ");
      text2 = document.createTextNode(count);
      button = document.createElement("button");
      text3 = document.createTextNode("+1");

      p.appendChild(text1);
      p.appendChild(text2);
      div.appendChild(p);
      button.addEventListener("click", handleClick);
      button.appendChild(text3);
      div.appendChild(button);
      target.appendChild(div);
    },
    // Update DOM nodes referring to some variable which has changed
    update: (changed) => {
      if (changed === "count") { // If the changed variable is `count`, only update `text2` then
        text2.data = count;
      }
    },
    // Clean DOM nodes created in this component
    destroy: () => {
      div.removeChild(p);
      button.removeEventListener("click", handleClick);
      div.removeChild(button);
      div.parentNode.removeChild(div);
    },
  };

  return lifecycle;
}

可运行的完整示例见 Naive Compiled App。

上述实现有如下特点：

• 组件模板 script 中的部分基本原封不动，放在 App 组件函数的头部，因为一般这里会声明一些 DOM 中会用到的变量、回调等
• App 组件返回的是其生命周期对象，具体包括如下三个阶段：
• 为了能够在count变量发生变化时更新对应 DOM 节点，一个可以考虑的方案是通过静态分析找到所有count变量更新的地方，然后插入lifecycle.update('count')语句

下面让我们看一下使用 Svelte 生成的 JS 结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42