<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
<channel>
<title>dh</title>
<link>https://nyann.cc/</link>
<description>dh 的文章</description>
<language>zh-CN</language>
<atom:link href="https://nyann.cc/feed.xml" rel="self" type="application/rss+xml"/>
<lastBuildDate>Wed, 28 Oct 2026 00:00:00 GMT</lastBuildDate>
<item>
<title>Claude Code 团队怎么做代码评审</title>
<link>https://nyann.cc/posts/Claude%20Code%20%E5%9B%A2%E9%98%9F%E6%80%8E%E4%B9%88%E5%81%9A%E4%BB%A3%E7%A0%81%E8%AF%84%E5%AE%A1</link>
<guid isPermaLink="true">https://nyann.cc/posts/Claude%20Code%20%E5%9B%A2%E9%98%9F%E6%80%8E%E4%B9%88%E5%81%9A%E4%BB%A3%E7%A0%81%E8%AF%84%E5%AE%A1</guid>
<pubDate>Wed, 28 Oct 2026 00:00:00 GMT</pubDate>
<description>Agent 写代码的量上来以后，代码评审怎么跟得上？Claude Code 团队把大部分阅读交给机器，按风险分配人的注意力，再让出错能很快撤回。</description>
<category>翻译</category>
<category>AI</category>
<category>Claude</category>
<category>代码评审</category>
<content:encoded><![CDATA[<h1 id="claude-code-团队怎么做代码评审" tabindex="-1">Claude Code 团队怎么做代码评审 <a class="header-anchor" href="#claude-code-团队怎么做代码评审" aria-label="本节链接：Claude Code 团队怎么做代码评审">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>How do you review code at the volume agents produce it? On the Claude Code team, once we had high coverage and deep reviews, we started optimizing for the minimum amount of human review time that doesn't raise reverts or incidents.</p>
</div>
<p>Agent 产出代码的量这么大，评审怎么跟得上？在 Claude Code 团队，等覆盖率和评审深度都上去以后，我们开始追求另一件事：在回滚和事故不增加的前提下，把人花在评审上的时间压到最少。</p>
<div class="yn-en" lang="en">
<p>We've said before that Claude writes about 90 percent of Claude Code's own code. So how do we review code at the volume we produce it? Does anyone read code anymore? And if something breaks, who catches it?</p>
</div>
<p>我们之前说过，Claude Code 自己的代码大约 90% 是 Claude 写的。代码产出到这个量，我们怎么评审？还有人读代码吗？出了问题谁来兜？</p>
<div class="yn-en" lang="en">
<p>This post covers the code review flow on the Claude Code team and how it has evolved. From June to September, merged pull requests to Claude Code's codebase more than doubled while the share that had to be reverted fell by more than 40 percent.</p>
</div>
<p>这篇讲 Claude Code 团队的代码评审流程，以及它是怎么一步步变成现在这样的。从 6 月到 9 月，Claude Code 代码库合并的拉取请求（pull request，下文简称 PR）翻了一倍多，需要回滚（revert）的比例却降了 40% 以上。</p>
<div class="yn-en" lang="en">
<p>We didn't remove review. But we did move most of the reading to machines, optimized for human time and attention, and invested heavily in making it fast and easy to undo mistakes.</p>
</div>
<p>评审我们没有取消。但大部分阅读交给了机器，一切围绕人的时间和注意力来优化，还下了大力气让出错能撤回得又快又容易。</p>
<h2 id="rethinking-the-purpose-of-code-review重新想想代码评审是为了什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">Rethinking the purpose of code review</span>重新想想代码评审是为了什么 <a class="header-anchor" href="#rethinking-the-purpose-of-code-review重新想想代码评审是为了什么" aria-label="本节链接：重新想想代码评审是为了什么">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>When agents write code, the number of changes goes up, fast. In Anthropic's monorepo, changes landing per day went from about <a href="https://www.anthropic.com/engineering/redesigning-source-control" target="_blank" rel="noreferrer">2,500 in May to more than 30,000 in September</a> this year.</p>
</div>
<p>Agent 一写代码，改动的数量就往上涨，涨得很快。在 Anthropic 的 monorepo 里，每天合入的改动从今年 <a href="https://www.anthropic.com/engineering/redesigning-source-control" target="_blank" rel="noreferrer">5 月的大约 2,500 个涨到了 9 月的 30,000 多个</a>。</p>
<div class="yn-en" lang="en">
<p>Claude Code lives in its own repository, separate from the monorepo, but it's seeing a lot of pressure too. When you are shipping this fast, manual, line-by-line code review is incredibly difficult if not impossible.</p>
</div>
<p>Claude Code 有自己单独的仓库，不在 monorepo 里，压力一样不小。发布快到这个程度，靠人逐行评审就算不是做不到，也难得要命。</p>
<div class="yn-en" lang="en">
<p>Code review does two jobs:</p>
</div>
<p>代码评审干两件事：</p>
<ol>
<li><span class="yn-en" lang="en">Find and fix issues before they ship</span>在问题上线之前找出来、修掉</li>
<li><span class="yn-en" lang="en">Build shared context and codebase understanding across the team</span>让整个团队共享上下文，都懂这个代码库</li>
</ol>
<div class="yn-en" lang="en">
<p>This article mainly focuses on finding and fixing issues, but we will come back to the second job near the end.</p>
</div>
<p>这篇主要讲第一件，找问题和修问题，第二件快结尾时再说。</p>
<div class="yn-en" lang="en">
<p>We think &quot;did a human read the code?&quot; is an imprecise proxy for &quot;what could go wrong with this change, and which check—automated or human—is the right one to catch it?&quot;</p>
</div>
<p>我们觉得，「有没有人读过这段代码？」只是个粗糙的替代指标。真正该问的是：「这个改动可能出什么问题？哪种检查，自动的也好、人工的也好，最适合把它抓出来？」</p>
<div class="yn-en" lang="en">
<p>Asking that question also changed <em>when</em> review happens. Before, review was a gate at the end of the road: write the code, open a PR, wait for your colleague.</p>
</div>
<p>这么一问，评审发生的<em>时间点</em>也跟着变了。以前评审是路尽头的一道关卡：写完代码，开 PR，等同事来看。</p>
<div class="yn-en" lang="en">
<p>Now, review runs continuously, more like spellcheck while you write. Most changes have been reviewed and fixed by Claude at least once before a human is asked to look. This catches most routine mistakes, and saves team attention for higher-level questions and scrutiny.</p>
</div>
<p>现在评审一直在跑，更像边写边查的拼写检查。大多数改动在请人看之前，已经被 Claude 评审并修过至少一轮。常规错误大多在这一步就被抓住了，团队的注意力就能留给更高层面的问题，看得更细。</p>
<h2 id="the-scarce-resource-human-time-and-attention稀缺的是人的时间和注意力" tabindex="-1"><span class="yn-en ignore-header" lang="en">The scarce resource: human time and attention</span>稀缺的是人的时间和注意力 <a class="header-anchor" href="#the-scarce-resource-human-time-and-attention稀缺的是人的时间和注意力" aria-label="本节链接：稀缺的是人的时间和注意力">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>We want to preserve human time and attention for issues only humans can solve and make sure automated checks catch the rest. At our current rate of change, there is still an incredible amount of work for humans to do, and our team encounters new and novel challenges almost daily.</p>
</div>
<p>我们想把人的时间和注意力留给只有人能解决的问题，其余的确保都由自动检查抓住。照现在的改动速度，要人来做的事依然多得惊人，团队几乎每天都会撞上没见过的新难题。</p>
<div class="yn-en" lang="en">
<p>Human time covers both sides of review's cost: the time people spend reviewing, and the time they spend fixing what bad code breaks. Cutting the first doesn't help if the time just shows up in the second.</p>
</div>
<p>人的时间包括评审成本的两头：花在评审上的时间，和花在收拾烂代码弄坏的东西上的时间。前一头省下来的时间要是又在后一头冒出来，那就白省了。</p>
<div class="yn-en" lang="en">
<p>So the goal is that most pull requests in the Claude Code repos (the CLI, the desktop and web apps, and the mobile apps) merge with at most one human in the loop, who can be the author, with no increase in reverts or incidents. To measure human time, we track human approvals per PR (median and 95th percentile), human comments, and how long a PR waits on a person. Revert and incident rates are the guardrail: if they rise, we haven't saved human time, we've only moved it.</p>
</div>
<p>所以目标是：Claude Code 各个仓库（CLI、桌面端和网页端应用、移动端应用）里的大多数 PR，合并时环路里最多只有一个人，这个人可以就是作者本人，同时回滚和事故不增加。为了衡量人的时间，我们跟踪每个 PR 的人工批准数（中位数和第 95 百分位）、人工评论数，以及 PR 等人处理等了多久。回滚率和事故率是护栏：它们一旦上升，就说明我们没有省下人的时间，只是把它挪了个地方。</p>
<h2 id="the-life-of-a-change一个改动的一生" tabindex="-1"><span class="yn-en ignore-header" lang="en">The life of a change</span>一个改动的一生 <a class="header-anchor" href="#the-life-of-a-change一个改动的一生" aria-label="本节链接：一个改动的一生">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>A typical change, from an engineer's laptop (or a Claude session in Slack), goes through multiple layers of code review.</p>
</div>
<p>一个典型的改动从工程师的笔记本（或者 Slack 里的一个 Claude 会话）出发，要过好几层代码评审。</p>
<figure class="crv-fig">
<div class="crv-head"><div class="crv-title">一个改动的一生</div><div class="crv-sub">一个典型的 Claude Code 改动，从作者的机器到用户手里</div></div>
<div class="crv-draw" role="img" aria-label="一个 PR 从上到下要过的检查。开 PR 之前，先验证工作。每个 PR 上：必需的 CI、Claude 代码评审和安全评审，全部自动；然后是按风险的批准，由人来决定。接着是合并队列；合并之后，先藏在功能开关后面内部使用，再逐步发布，最后一步是观察、前向修复或回滚。">
<svg class="art-diagram-wide" aria-hidden="true" focusable="false" id="code-review-life-of-a-change" width="651" height="522" viewBox="2 0 651 522" xmlns="http://www.w3.org/2000/svg"><path d="M11 33.5 L11 460.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line)"/>
<circle cx="11" cy="33.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="33.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 33.5 L10.2 35.8 L14.2 31.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="114.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="114.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 114.5 L10.2 116.8 L14.2 112.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="161.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="161.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 161.5 L10.2 163.8 L14.2 159.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="208.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="208.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 208.5 L10.2 210.8 L14.2 206.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="255.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<polygon points="11,248.5 18,255.5 11,262.5 4,255.5" style="fill:var(--fig-focal)"/>
<circle cx="11" cy="336.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="336.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 336.5 L10.2 338.8 L14.2 334.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="400.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="400.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 400.5 L10.2 402.8 L14.2 398.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="430.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="430.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 430.5 L10.2 432.8 L14.2 428.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="460.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<path d="M16.6 462.5 A6 6 0 1 1 14.4 455.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<path d="M11.6 453.9 L14.6 455.5 L13.6 458.7" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="32" y="14" font-size="11" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">BEFORE THE PULL REQUEST</text>
<text x="32" y="38" font-size="14" font-weight="500" style="fill:var(--ink)">The work is verified</text>
<text x="277" y="38" font-size="13" style="fill:var(--ink-2)">Claude runs the tests, build and linter; a second agent</text>
<text x="277" y="55" font-size="13" style="fill:var(--ink-2)">reviews the diff in a fresh context</text>
<text x="32" y="95" font-size="11" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">ON EVERY PULL REQUEST</text>
<text x="32" y="119" font-size="14" font-weight="500" style="fill:var(--ink)">Required CI</text>
<text x="277" y="119" font-size="13" style="fill:var(--ink-2)">Lint, types, tests across platforms, build and packaging. Red</text>
<text x="277" y="136" font-size="13" style="fill:var(--ink-2)">blocks the merge</text>
<text x="32" y="166" font-size="14" font-weight="500" style="fill:var(--ink)">Claude code review</text>
<text x="277" y="166" font-size="13" style="fill:var(--ink-2)">Agents hunt for bugs in parallel, verifiers vote on each</text>
<text x="277" y="183" font-size="13" style="fill:var(--ink-2)">finding, survivors ranked by severity</text>
<text x="32" y="213" font-size="14" font-weight="500" style="fill:var(--ink)">Security review</text>
<text x="277" y="213" font-size="13" style="fill:var(--ink-2)">A separate pass. Open findings from either review block the</text>
<text x="277" y="230" font-size="13" style="fill:var(--ink-2)">merge</text>
<text x="32" y="260" font-size="14" font-weight="500" style="fill:var(--ink)">Risk-based approval</text>
<text x="277" y="260" font-size="13" style="fill:var(--ink-2)">A classifier sets the tier: no person, one, or two. Some paths</text>
<text x="277" y="277" font-size="13" style="fill:var(--ink-2)">always need a person</text>
<text x="32" y="317" font-size="11" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">MERGING</text>
<text x="32" y="341" font-size="14" font-weight="500" style="fill:var(--ink)">Merge queue</text>
<text x="277" y="341" font-size="13" style="fill:var(--ink-2)">Checks run again on the latest main with the change applied</text>
<text x="32" y="381" font-size="11" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">AFTER THE MERGE</text>
<text x="32" y="405" font-size="14" font-weight="500" style="fill:var(--ink)">Behind a flag, used internally first</text>
<text x="277" y="405" font-size="13" style="fill:var(--ink-2)">Anthropic employees run it before it reaches everyone</text>
<text x="32" y="435" font-size="14" font-weight="500" style="fill:var(--ink)">Gradual release</text>
<text x="277" y="435" font-size="13" style="fill:var(--ink-2)">The latest channel first; the stable channel trails it</text>
<text x="32" y="465" font-size="14" font-weight="500" style="fill:var(--ink)">Watch, fix forward or roll back</text>
<text x="277" y="465" font-size="13" style="fill:var(--ink-2)">The author and on-call watch; flags turn off quickly, broken</text>
<text x="277" y="482" font-size="13" style="fill:var(--ink-2)">builds get reverted</text>
<circle cx="11" cy="511.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="511.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 511.5 L10.2 513.8 L14.2 509.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="26" y="516" font-size="13" style="fill:var(--ink-2)">automated</text>
<circle cx="122.66593017578126" cy="511.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<polygon points="122.66593017578126,504.5 129.66593017578126,511.5 122.66593017578126,518.5 115.66593017578126,511.5" style="fill:var(--fig-focal)"/>
<text x="137.66593017578126" y="516" font-size="13" style="fill:var(--ink-2)">a person decides, scaled by risk</text>
<circle cx="355.21875244140625" cy="511.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<path d="M360.8187524414063 513.5 A6 6 0 1 1 358.61875244140623 506.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<path d="M355.8187524414063 504.9 L358.8187524414063 506.5 L357.8187524414063 509.7" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="370.21875244140625" y="516" font-size="13" style="fill:var(--ink-2)">recovery</text>
</svg>
<svg class="art-diagram-narrow" aria-hidden="true" focusable="false" id="code-review-life-of-a-change-mobile" width="300" height="797" viewBox="2 0 300 797" xmlns="http://www.w3.org/2000/svg"><path d="M11 34.5 L11 671.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line)"/>
<circle cx="11" cy="34.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="34.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 34.5 L10.2 36.8 L14.2 32.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="147.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="147.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 147.5 L10.2 149.8 L14.2 145.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="210.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="210.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 210.5 L10.2 212.8 L14.2 208.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="290.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="290.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 290.5 L10.2 292.8 L14.2 288.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="353.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<polygon points="11,346.5 18,353.5 11,360.5 4,353.5" style="fill:var(--fig-focal)"/>
<circle cx="11" cy="449.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="449.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 449.5 L10.2 451.8 L14.2 447.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="545.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="545.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 545.5 L10.2 547.8 L14.2 543.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="608.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="608.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 608.5 L10.2 610.8 L14.2 606.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<circle cx="11" cy="671.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<path d="M16.6 673.5 A6 6 0 1 1 14.4 666.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<path d="M11.6 664.9 L14.6 666.5 L13.6 669.7" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="32" y="14" font-size="12.75" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">BEFORE THE PULL REQUEST</text>
<text x="32" y="39" font-size="14" font-weight="500" style="fill:var(--ink)">The work is verified</text>
<text x="32" y="57" font-size="13" style="fill:var(--ink-2)">Claude runs the tests, build and linter; a</text>
<text x="32" y="74" font-size="13" style="fill:var(--ink-2)">second agent reviews the diff in a fresh</text>
<text x="32" y="91" font-size="13" style="fill:var(--ink-2)">context</text>
<text x="32" y="127" font-size="12.75" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">ON EVERY PULL REQUEST</text>
<text x="32" y="152" font-size="14" font-weight="500" style="fill:var(--ink)">Required CI</text>
<text x="32" y="170" font-size="13" style="fill:var(--ink-2)">Lint, types, tests across platforms, build</text>
<text x="32" y="187" font-size="13" style="fill:var(--ink-2)">and packaging. Red blocks the merge</text>
<text x="32" y="215" font-size="14" font-weight="500" style="fill:var(--ink)">Claude code review</text>
<text x="32" y="233" font-size="13" style="fill:var(--ink-2)">Agents hunt for bugs in parallel, verifiers</text>
<text x="32" y="250" font-size="13" style="fill:var(--ink-2)">vote on each finding, survivors ranked by</text>
<text x="32" y="267" font-size="13" style="fill:var(--ink-2)">severity</text>
<text x="32" y="295" font-size="14" font-weight="500" style="fill:var(--ink)">Security review</text>
<text x="32" y="313" font-size="13" style="fill:var(--ink-2)">A separate pass. Open findings from either</text>
<text x="32" y="330" font-size="13" style="fill:var(--ink-2)">review block the merge</text>
<text x="32" y="358" font-size="14" font-weight="500" style="fill:var(--ink)">Risk-based approval</text>
<text x="32" y="376" font-size="13" style="fill:var(--ink-2)">A classifier sets the tier: no person, one, or</text>
<text x="32" y="393" font-size="13" style="fill:var(--ink-2)">two. Some paths always need a person</text>
<text x="32" y="429" font-size="12.75" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">MERGING</text>
<text x="32" y="454" font-size="14" font-weight="500" style="fill:var(--ink)">Merge queue</text>
<text x="32" y="472" font-size="13" style="fill:var(--ink-2)">Checks run again on the latest main with</text>
<text x="32" y="489" font-size="13" style="fill:var(--ink-2)">the change applied</text>
<text x="32" y="525" font-size="12.75" font-weight="500" letter-spacing="0.08em" class="mono" style="fill:var(--ink-2)">AFTER THE MERGE</text>
<text x="32" y="550" font-size="14" font-weight="500" style="fill:var(--ink)">Behind a flag, used internally first</text>
<text x="32" y="568" font-size="13" style="fill:var(--ink-2)">Anthropic employees run it before it</text>
<text x="32" y="585" font-size="13" style="fill:var(--ink-2)">reaches everyone</text>
<text x="32" y="613" font-size="14" font-weight="500" style="fill:var(--ink)">Gradual release</text>
<text x="32" y="631" font-size="13" style="fill:var(--ink-2)">The latest channel first; the stable channel</text>
<text x="32" y="648" font-size="13" style="fill:var(--ink-2)">trails it</text>
<text x="32" y="676" font-size="14" font-weight="500" style="fill:var(--ink)">Watch, fix forward or roll back</text>
<text x="32" y="694" font-size="13" style="fill:var(--ink-2)">The author and on-call watch; flags turn off</text>
<text x="32" y="711" font-size="13" style="fill:var(--ink-2)">quickly, broken builds get reverted</text>
<circle cx="11" cy="738.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<circle cx="11" cy="738.5" r="6.5" fill="none" stroke-width="1" style="stroke:var(--viz-muted)"/>
<path d="M8 738.5 L10.2 740.8 L14.2 736.3" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="32" y="743" font-size="13" style="fill:var(--ink-2)">automated</text>
<circle cx="11" cy="762.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<polygon points="11,755.5 18,762.5 11,769.5 4,762.5" style="fill:var(--fig-focal)"/>
<text x="32" y="767" font-size="13" style="fill:var(--ink-2)">a person decides, scaled by risk</text>
<circle cx="11" cy="786.5" r="7" stroke-width="2" style="fill:var(--bg);stroke:var(--bg)"/>
<path d="M16.6 788.5 A6 6 0 1 1 14.4 781.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<path d="M11.6 779.9 L14.6 781.5 L13.6 784.7" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-m1)"/>
<text x="32" y="791" font-size="13" style="fill:var(--ink-2)">recovery</text>
</svg>
</div>
<figcaption><b>FIG A</b><span>大部分路径是自动的；人的注意力放在有风险的地方</span></figcaption>
</figure>
<h2 id="layer-by-layer一层一层来" tabindex="-1"><span class="yn-en ignore-header" lang="en">Layer by layer</span>一层一层来 <a class="header-anchor" href="#layer-by-layer一层一层来" aria-label="本节链接：一层一层来">&ZeroWidthSpace;</a></h2>
<figure class="crv-fig">
<div class="crv-head"><div class="crv-title">多层把关，而不是一道关卡</div><div class="crv-sub">六层检查，底下还垫着回滚</div></div>
<div class="crv-draw" role="img" aria-label="六层从上到下叠放：验证、必需的 CI、AI 评审、安全评审、人工批准、合并队列加功能开关。每层的漏洞位置都不一样。从某层漏洞掉下去的问题会被后面的层接住；有一个穿过了每一层的漏洞，落到最底下的快速回滚里。">
<svg class="art-diagram-wide" aria-hidden="true" focusable="false" id="code-review-layers" width="651" height="369" viewBox="0 0 651 369" xmlns="http://www.w3.org/2000/svg"><text x="40" y="14" font-size="13" style="fill:var(--ink-2)">problems in</text>
<path d="M188 22 L188 343" fill="none" stroke-width="1" stroke-dasharray="3 3" style="stroke:var(--fig-focal)"/>
<path d="M78.8 22 L78.8 54" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M297.2 22 L297.2 54" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M110 65.5 L110 104" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M271.2 115.5 L271.2 154" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M136 165.5 L136 204" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M253 215.5 L253 254" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M99.6 265.5 L99.6 304" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<polygon points="40,72 300,72 336,50 76,50" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="61" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="110" cy="61" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="65.5" font-size="13" style="fill:var(--ink)">verification</text>
<polygon points="40,122 300,122 336,100 76,100" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="111" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="271.2" cy="111" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="115.5" font-size="13" style="fill:var(--ink)">required CI</text>
<polygon points="40,172 300,172 336,150 76,150" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="161" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="136" cy="161" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="165.5" font-size="13" style="fill:var(--ink)">AI review</text>
<polygon points="40,222 300,222 336,200 76,200" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="211" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="253" cy="211" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="215.5" font-size="13" style="fill:var(--ink)">security review</text>
<polygon points="40,272 300,272 336,250 76,250" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="261" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="99.6" cy="261" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="265.5" font-size="13" style="fill:var(--ink)">human approval</text>
<polygon points="40,322 300,322 336,300 76,300" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="188" cy="311" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="281.6" cy="311" rx="14" ry="4.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="358" y="315.5" font-size="13" style="fill:var(--ink)">merge queue + flags</text>
<path d="M188 56.5 L188 315.5" fill="none" stroke-width="1" stroke-dasharray="3 3" style="stroke:var(--fig-focal)"/>
<circle cx="78.8" cy="59" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="297.2" cy="59" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="110" cy="109" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="271.2" cy="159" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="136" cy="209" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="253" cy="259" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="99.6" cy="309" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<path d="M144 341 Q188 369 232 341" fill="none" stroke-width="1" style="stroke:var(--fig-focal)"/>
<circle cx="188" cy="351" r="5.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<text x="358" y="355.5" font-size="13" font-weight="500" style="fill:var(--fig-focal)">fast rollback</text>
</svg>
<svg class="art-diagram-narrow" aria-hidden="true" focusable="false" id="code-review-layers-mobile" width="300" height="304" viewBox="0 0 300 304" xmlns="http://www.w3.org/2000/svg"><text x="2" y="14" font-size="13" style="fill:var(--ink-2)">problems in</text>
<path d="M82 22 L82 278" fill="none" stroke-width="1" stroke-dasharray="3 3" style="stroke:var(--fig-focal)"/>
<path d="M24 22 L24 45" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M140 22 L140 45" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M40.6 55.5 L40.6 85" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M126.2 95.5 L126.2 125" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M54.4 135.5 L54.4 165" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M116.5 175.5 L116.5 205" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<path d="M35.1 215.5 L35.1 245" fill="none" stroke-width="1" stroke-dasharray="3 3" opacity=".55" style="stroke:var(--fig-focal)"/>
<polygon points="2,60 140,60 162,44 24,44" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="52" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="40.6" cy="52" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="56.5" font-size="13" style="fill:var(--ink)">verification</text>
<polygon points="2,100 140,100 162,84 24,84" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="92" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="126.2" cy="92" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="96.5" font-size="13" style="fill:var(--ink)">required CI</text>
<polygon points="2,140 140,140 162,124 24,124" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="132" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="54.4" cy="132" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="136.5" font-size="13" style="fill:var(--ink)">AI review</text>
<polygon points="2,180 140,180 162,164 24,164" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="172" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="116.5" cy="172" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="176.5" font-size="13" style="fill:var(--ink)">security review</text>
<polygon points="2,220 140,220 162,204 24,204" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="212" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="35.1" cy="212" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="216.5" font-size="13" style="fill:var(--ink)">human approval</text>
<polygon points="2,260 140,260 162,244 24,244" stroke-width="1" style="fill:var(--line-soft);stroke:var(--line)"/>
<ellipse cx="82" cy="252" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<ellipse cx="131.7" cy="252" rx="10" ry="3.5" stroke-width="1" style="fill:var(--bg);stroke:var(--line)"/>
<text x="174" y="256.5" font-size="13" style="fill:var(--ink)">merge queue + flags</text>
<path d="M82 48.5 L82 255.5" fill="none" stroke-width="1" stroke-dasharray="3 3" style="stroke:var(--fig-focal)"/>
<circle cx="24" cy="50" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="140" cy="50" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="40.6" cy="90" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="126.2" cy="130" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="54.4" cy="170" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="116.5" cy="210" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="35.1" cy="250" r="4.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<path d="M48 276 Q82 304 116 276" fill="none" stroke-width="1" style="stroke:var(--fig-focal)"/>
<circle cx="82" cy="286" r="5.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<text x="174" y="290.5" font-size="13" font-weight="500" style="fill:var(--fig-focal)">fast rollback</text>
</svg>
</div>
<figcaption><b>FIG B</b><span>每一层都能抓住一些问题、漏掉另一些。能穿过所有层的很少，剩下的交给回滚。</span></figcaption>
</figure>
<h3 id="_1-the-work-is-verified-before-anyone-else-looks1-别人看之前-活先验证好" tabindex="-1"><span class="yn-en ignore-header" lang="en">1. The work is verified before anyone else looks</span>1. 别人看之前，活先验证好 <a class="header-anchor" href="#_1-the-work-is-verified-before-anyone-else-looks1-别人看之前-活先验证好" aria-label="本节链接：1. 别人看之前，活先验证好">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Most review now happens before a PR exists. We give Claude something it can run—like tests, a build or a screenshot to compare against the design—and ask it to show the output instead of saying it's done. Then a subagent reviews the diff with fresh context. Both habits come from our <a href="https://code.claude.com/docs/en/best-practices" target="_blank" rel="noreferrer">best-practices guide</a>.</p>
</div>
<p>现在大多数评审在 PR 出现之前就做完了。我们给 Claude 一个能跑的东西，比如测试、一次构建，或者一张拿来跟设计稿对比的截图，让它把输出亮出来，而不是光说一句做完了。然后再让一个子 agent（subagent）带着全新的上下文去评审 diff。这两个习惯都出自我们的<a href="https://code.claude.com/docs/en/best-practices" target="_blank" rel="noreferrer">最佳实践指南</a>。</p>
<div class="yn-en" lang="en">
<p>Before opening a PR, many of us also run a few <a href="https://claude.dev/blog/lessons-from-building-claude-code-how-we-use-skills/" target="_blank" rel="noreferrer">internal skills</a>: one hunts for bugs, one simplifies the diff, and one checks the behavior end to end. UI changes also get checked against our design guidelines.</p>
</div>
<p>开 PR 之前，我们很多人还会跑几个<a href="https://claude.dev/blog/lessons-from-building-claude-code-how-we-use-skills/" target="_blank" rel="noreferrer">内部 skill</a>：一个专门找 bug，一个精简 diff，一个端到端地检查行为。UI 改动还要对着我们的设计规范再查一遍。</p>
<div class="yn-en" lang="en">
<p>Boris Cherny, who created Claude Code, has called giving Claude a way to verify its work <a href="https://x.com/bcherny/status/2007179861115511237" target="_blank" rel="noreferrer">probably the most important thing</a> for getting good results. He estimates it makes the final result two to three times better, and writes, &quot;Verification looks different for each domain. It might be as simple as running a bash command, or running a test suite, or testing the app in a browser or phone simulator.&quot;</p>
</div>
<p>Claude Code 的创造者 Boris Cherny 说过，想要好结果，给 Claude 一个验证自己工作的手段<a href="https://x.com/bcherny/status/2007179861115511237" target="_blank" rel="noreferrer">大概是最重要的一件事</a>。他估计这能让最终结果好上两三倍，还写道：「每个领域的验证方式都不一样。可能简单到跑一条 bash 命令，或者跑一套测试，或者在浏览器、手机模拟器里把应用试一遍。」</p>
<div class="yn-en" lang="en">
<p><strong>When the automated reviewer keeps flagging the same thing, we fix it at the source:</strong> in the skill, with a lint rule, or with updates to instructional files such as:</p>
</div>
<p><strong>自动评审老是标出同一类问题时，我们就从源头上修：</strong> 改 skill、加一条 lint 规则，或者更新指令文件，比如：</p>
<ul>
<li><span class="yn-en" lang="en"><code>CLAUDE.md</code> tells Claude what the project is: the stack, the conventions, the goals and the non-goals. Every review loads it, so in a large codebase we keep it short and point to other docs from there. The reviewer also flags code that breaks a convention in it, and changes that make a line in it out of date.</span><code>CLAUDE.md</code> 告诉 Claude 这个项目是什么：技术栈、约定、目标和非目标。每次评审都会加载它，所以在大代码库里我们把它写得很短，从这里再指到别的文档。评审器还会标出违反其中约定的代码，以及让其中某一行过时的改动。</li>
<li><span class="yn-en" lang="en"><code>REVIEW.md</code>, written by code owners, tells the reviewer what matters in their part of the code. We check separately whether the reviewer actually follows it. The good ones are short. They say what failure looks like in that repo (for docs it's &quot;it lies,&quot; for config it's &quot;it misroutes&quot;), cap the nits, list paths to skip, and ask for a file and line as evidence instead of a guess from a name. They also ask for a summary that starts with a count and says plainly when there's nothing to fix.</span><code>REVIEW.md</code> 由代码负责人（code owner）来写，告诉评审器在他们那块代码里什么最要紧。评审器到底有没有照着做，我们另外检查。写得好的都很短。它们会讲清楚在这个仓库里「出错」长什么样（文档是「它在说假话」，配置是「它把东西路由错了」），限制鸡毛蒜皮意见（nit）的条数，列出要跳过的路径，要求拿文件和行号当证据，而不是看个名字就猜。它们还要求总结以一个数字开头，没什么要修的时候就直说。</li>
</ul>
<h3 id="_2-ai-review-on-every-pull-request2-每个-pr-都有-ai-评审" tabindex="-1"><span class="yn-en ignore-header" lang="en">2. AI review on every pull request</span>2. 每个 PR 都有 AI 评审 <a class="header-anchor" href="#_2-ai-review-on-every-pull-request2-每个-pr-都有-ai-评审" aria-label="本节链接：2. 每个 PR 都有 AI 评审">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Every pull request gets a Claude review before a person looks. It reads the diff against the whole repo and the PR's stated intent, and asks: does the change solve its problem, fit the system, or break something else?</p>
</div>
<p>每个 PR 在人看之前，都会先过一轮 Claude 评审。它拿 diff 对照整个仓库和 PR 写明的意图来读，然后问：这个改动解决了它要解决的问题吗？跟系统合得来吗？会不会弄坏别的东西？</p>
<div class="yn-en" lang="en">
<p>On a bug fix, it looks for the root cause. The public version, <a href="https://code.claude.com/docs/en/code-review" target="_blank" rel="noreferrer">Code Review for Claude Code</a>, is now generally available on Team and Enterprise plans, and <code>/code-review</code> runs a lighter version locally.</p>
</div>
<p>如果是修 bug，它会去找根因。公开版本 <a href="https://code.claude.com/docs/en/code-review" target="_blank" rel="noreferrer">Code Review for Claude Code</a> 现在已经在 Team 和 Enterprise 套餐上全面开放，<code>/code-review</code> 则是在本地跑一个轻量版。</p>
<div class="yn-en" lang="en">
<p>When we <a href="https://claude.com/resources/articles/code-review" target="_blank" rel="noreferrer">launched the research preview</a>, the share of internal PRs getting substantive review comments went from 16% to 54%. Most PRs over 1,000 lines get findings, and most small ones come back clean. Admins set each repo to Quick, Standard, or Deep. Deep is worth it where one missed bug costs more than the extra review time.</p>
</div>
<p>我们<a href="https://claude.com/resources/articles/code-review" target="_blank" rel="noreferrer">推出研究预览版</a>的时候，内部 PR 里收到实质性评审意见的比例从 16% 升到了 54%。超过 1,000 行的 PR 大多会被查出问题，小 PR 大多干干净净地回来。管理员可以给每个仓库选 Quick、Standard 或 Deep。漏一个 bug 的代价要是比多花的评审时间还高，Deep 就值得。</p>
<div class="yn-en" lang="en">
<p><strong>Findings get verified by other agents before humans review them.</strong>  Several agents look for bugs at the same time. Then a separate group votes on each finding, and it only gets posted if enough of them agree it's real. Findings that are only about style, diagnostics, or cleanup get dropped. We A/B tested those filters on our own PRs before keeping them. What's left shows up as inline comments sorted by severity. Each is tagged Important, Nit, or Pre-existing, so a bug the PR didn't introduce doesn't look like the author's fault.</p>
</div>
<p><strong>人看之前，发现的问题先由别的 agent 核实。</strong> 好几个 agent 同时找 bug，然后另一组 agent 给每条发现投票，够多的 agent 都认定它是真问题才会贴出来。只关于代码风格、诊断信息或清理的发现直接丢掉。这些过滤规则是我们先在自己的 PR 上做过 A/B 测试才留下的。剩下的以行内评论的形式出现，按严重程度排序。每条都标着 Important、Nit 或 Pre-existing，这样一个不是这个 PR 引入的 bug，就不会看着像是作者的锅。</p>
<div class="yn-en" lang="en">
<p><strong>Every finding has to be answered.</strong> You either fix it or resolve the thread with a reason. Often an agent picks up the fix overnight, so the author comes back to a PR that's already been through another round.</p>
</div>
<p><strong>每条发现都得有个回应。</strong> 要么修掉，要么写明理由把讨论串关了。很多时候会有 agent 连夜把修复接过去，作者回来一看，PR 已经又过了一轮。</p>
<h3 id="_3-security-review-that-can-block3-能拦住合并的安全评审" tabindex="-1"><span class="yn-en ignore-header" lang="en">3. Security review that can block</span>3. 能拦住合并的安全评审 <a class="header-anchor" href="#_3-security-review-that-can-block3-能拦住合并的安全评审" aria-label="本节链接：3. 能拦住合并的安全评审">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Security gets its own automated review too. A PR can't merge while any finding from the bug review or the security review is still open. You either fix it or close the thread with a short reason, which is how you clear a false positive.</p>
</div>
<p>安全也有自己的一套自动评审。只要 bug 评审或安全评审里还有一条发现没处理，PR 就合不进去。要么修掉，要么写一句简短的理由把讨论串关掉，误报就是这么清掉的。</p>
<div class="yn-en" lang="en">
<p>If a later commit fixes the issue, the finding clears on its own. You can set up the same thing with the open-source security review GitHub Action or the <code>/security-review</code> command. Setup is covered in <a href="https://support.claude.com/en/articles/11932705-automated-security-reviews-in-claude-code" target="_blank" rel="noreferrer">automated security reviews in Claude Code</a>.</p>
</div>
<p>如果后面的提交把问题修好了，那条发现会自己消掉。你也可以用开源的安全评审 GitHub Action 或者 <code>/security-review</code> 命令搭一套一样的。怎么配见 <a href="https://support.claude.com/en/articles/11932705-automated-security-reviews-in-claude-code" target="_blank" rel="noreferrer">Claude Code 中的自动安全评审</a>。</p>
<h3 id="_4-automated-checks-that-block4-能拦住合并的自动检查" tabindex="-1"><span class="yn-en ignore-header" lang="en">4. Automated checks that block</span>4. 能拦住合并的自动检查 <a class="header-anchor" href="#_4-automated-checks-that-block4-能拦住合并的自动检查" aria-label="本节链接：4. 能拦住合并的自动检查">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The usual: lint, type checks, tests on every platform, and a build. (We wrote about scaling CI for this volume <a href="https://claude.com/resources/articles/agentic-coding-is-straining-ci-heres-how-we-scaled-test-impact-analysis-at-anthropic" target="_blank" rel="noreferrer">here</a>.) A typical CLI pull request may run dozens of checks before anyone looks at it. The PR template asks how the change was tested and how to undo it. Claude can fill that in, but the person who asked for the change signs off on it.</p>
</div>
<p>就是常规那些：lint、类型检查、各个平台上的测试，再加一次构建。（我们怎么把 CI 扩到扛得住这个量，写在<a href="https://claude.com/resources/articles/agentic-coding-is-straining-ci-heres-how-we-scaled-test-impact-analysis-at-anthropic" target="_blank" rel="noreferrer">这里</a>。）一个典型的 CLI PR 在有人看之前，可能已经跑了几十项检查。PR 模板会问这个改动怎么测的、怎么撤回。Claude 可以把它填好，但得由提出这个改动的人签字确认。</p>
<h3 id="_5-human-approval-scaled-by-risk5-人工批准-按风险加码" tabindex="-1"><span class="yn-en ignore-header" lang="en">5. Human approval, scaled by risk</span>5. 人工批准，按风险加码 <a class="header-anchor" href="#_5-human-approval-scaled-by-risk5-人工批准-按风险加码" aria-label="本节链接：5. 人工批准，按风险加码">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A docs fix and an auto-updater change carry different risk, so they get different review.</p>
</div>
<p>改个文档和改自动更新器，风险不一样，评审自然也不一样。</p>
<table tabindex="0">
<thead>
<tr>
<th>风险</th>
<th>例子</th>
<th>人工批准</th>
</tr>
</thead>
<tbody>
<tr>
<td>低</td>
<td>文档、文案、只在内部用的功能、藏在功能开关后面的新增改动</td>
<td>自动评审和安全检查都通过后，不需要</td>
</tr>
<tr>
<td>中</td>
<td>普通的产品改动，以及缓存、自动更新器、系统提示词这类敏感区域的改动</td>
<td>一个人</td>
</tr>
<tr>
<td>高</td>
<td>风险最高的代码，外加一小批永远要两个人的路径</td>
<td>两个人</td>
</tr>
</tbody>
</table>
<div class="yn-en" lang="en">
<p><strong>The change sets the tier, not the author.</strong> A classifier reads the change and picks its risk tier. A second classifier asks whether this particular change needs another person even when its tier says it doesn't. Some paths always need a person, anything owners have listed as sensitive and any CI workflow file.</p>
</div>
<p><strong>档位看改动，不看作者。</strong> 一个分类器读这个改动，给它定风险档位。第二个分类器再问：就算档位说不用，这个具体的改动是不是还得再多一个人看？有些路径永远需要人，包括负责人列为敏感的任何东西，以及所有 CI 工作流文件。</p>
<div class="yn-en" lang="en">
<p><strong>Only trusted authors get the lighter paths.</strong> Only authors on the repo's trusted list get the lighter paths, mostly the team that owns it. Everyone else needs a second person to approve. An agent's approval never counts as a person's, either. Automated review can clear a low-risk change, but it can't fill a slot that calls for a human.</p>
</div>
<p><strong>只有受信任的作者能走轻量通道。</strong> 只有在仓库受信任名单上的作者才能走轻量通道，基本上就是负责这个仓库的团队。其他人都要第二个人批准。agent 的批准也永远不能算作人的批准。自动评审可以放行低风险改动，但需要人的那个位置，它补不上。</p>
<div class="yn-en" lang="en">
<p><strong>Whoever prompted the change is on the hook for it.</strong> On an agent-written PR, the person directing the agent counts as one of the required reviewers, the same as if they'd typed the code themselves.</p>
</div>
<p><strong>谁让写的，谁担着。</strong> agent 写的 PR 上，指挥 agent 的那个人算作必需的评审者之一，跟代码是他们自己一个字一个字敲出来的一样。</p>
<div class="yn-en" lang="en">
<p><strong>An approval covers one specific commit.</strong> If new commits land that the system can't vouch for, like an agent's push or a merge someone resolved by hand, the approval has to be given again.</p>
</div>
<p><strong>一次批准只管一个具体的提交。</strong> 要是又进来了系统担保不了的新提交，比如 agent 推上来的提交，或者有人手动解决冲突的合并，就得重新批准。</p>
<h3 id="_6-merge-queue-flags-and-a-gradual-release6-合并队列、功能开关和逐步发布" tabindex="-1"><span class="yn-en ignore-header" lang="en">6. Merge queue, flags and a gradual release</span>6. 合并队列、功能开关和逐步发布 <a class="header-anchor" href="#_6-merge-queue-flags-and-a-gradual-release6-合并队列、功能开关和逐步发布" aria-label="本节链接：6. 合并队列、功能开关和逐步发布">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The merge queue re-runs every check against main with the change applied, so two PRs that pass separately can't combine into a broken main. New behavior usually ships behind a flag to Anthropic employees first, and our heavy use often surfaces regressions before users do. Public releases go to the <code>latest</code> channel first. The <code>stable</code> channel trails it.</p>
</div>
<p>合并队列（merge queue）会把改动应用到 main 上，把每项检查重跑一遍，这样两个各自都能通过的 PR 就不会合在一起把 main 弄坏。新行为一般先藏在功能开关（feature flag）后面，发给 Anthropic 员工用。我们用得很猛，回归问题常常在用户碰到之前就暴露了。公开发布先进 <code>latest</code> 频道，<code>stable</code> 频道跟在后面。</p>
<h3 id="_7-fast-detection-fast-rollback7-发现要快-回滚要快" tabindex="-1"><span class="yn-en ignore-header" lang="en">7. Fast detection, fast rollback</span>7. 发现要快，回滚要快 <a class="header-anchor" href="#_7-fast-detection-fast-rollback7-发现要快-回滚要快" aria-label="本节链接：7. 发现要快，回滚要快">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Some mistakes will still get through, so the last layer is about catching them fast. Flags turn off without a deploy. Claude Code has a weekly on-call rotation, and incident reviews ask which layer should have caught the issue.</p>
</div>
<p>总还是会有错漏过去，所以最后一层要做的就是尽快抓住它们。功能开关不用部署就能关。Claude Code 有按周轮换的值班（on-call），事故复盘会问：这个问题本该由哪一层抓住？</p>
<div class="yn-en" lang="en">
<p>Noticing a bad merge still depends on the author and on-call as well as the revert and incident dashboards. We don't yet have circuit breakers that tighten approval when those numbers move; engineers here want them before more code moves to zero-human merges.</p>
</div>
<p>发现一次坏的合并，现在还是得靠作者和值班的人，外加回滚和事故的看板。我们还没有熔断机制，能在这些数字一动的时候自动收紧批准要求；这里的工程师希望先把它做出来，再让更多代码走零人工合并。</p>
<div class="yn-en" lang="en">
<p>One colleague said slowing down does lower your error rate, but mostly because you're doing less of everything. We'd rather get faster at noticing and fixing problems.</p>
</div>
<p>有位同事说，放慢速度确实能降低出错率，但主要是因为你干什么都干得少了。我们宁可在发现和修复问题上变得更快。</p>
<h2 id="how-we-make-the-reviewer-better我们怎么让评审器变得更好" tabindex="-1"><span class="yn-en ignore-header" lang="en">How we make the reviewer better</span>我们怎么让评审器变得更好 <a class="header-anchor" href="#how-we-make-the-reviewer-better我们怎么让评审器变得更好" aria-label="本节链接：我们怎么让评审器变得更好">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Our code review process is constantly improving in a loop.</p>
</div>
<p>我们的代码评审流程是在一个循环里不断变好的。</p>
<div class="yn-en" lang="en">
<p><strong>Any incidents are now an eval.</strong> The team collected past PRs that caused incidents, with their fix-forwards and reverts, and had engineers who know that code confirm each bug and where it lived. The reviewer runs against that set daily.</p>
</div>
<p><strong>现在每次事故都会变成 eval。</strong> 团队把过去引发过事故的 PR 收集起来，连同它们的前向修复（fix-forward）和回滚，再请熟悉那段代码的工程师逐个确认 bug 是什么、出在哪。评审器每天拿这个集合跑一遍。</p>
<figure class="crv-fig">
<div class="crv-head"><div class="crv-title">我们的事故就是 eval</div><div class="crv-sub">由过去的事故和回滚攒成，每天跑一次</div></div>
<div class="crv-draw" role="img" aria-label="一次事故或回滚变成一条经专家确认的用例，加进 eval 集。对评审器的一次改动会进入每日 eval 运行，对照每一条用例打分；分数上升就保留，否则丢掉，然后拿下一个改动重新开始这个循环。">
<svg class="art-diagram-wide" aria-hidden="true" focusable="false" id="code-review-incident-eval" width="651" height="196" viewBox="28 26 651 196" xmlns="http://www.w3.org/2000/svg"><text x="54" y="44.5" font-size="14" font-weight="500" style="fill:var(--ink)">Incident or revert</text>
<text x="54" y="62" font-size="12.5" style="fill:var(--viz-muted)">a change that broke something</text>
<text x="271" y="44.5" font-size="14" font-weight="500" style="fill:var(--ink)">Expert-checked case</text>
<text x="271" y="62" font-size="12.5" style="fill:var(--viz-muted)">experts confirm the bug</text>
<text x="488" y="44.5" font-size="14" font-weight="500" style="fill:var(--ink)">Added to the set</text>
<text x="488" y="62" font-size="12.5" style="fill:var(--viz-muted)">each incident adds a case</text>
<text x="54" y="154.5" font-size="14" font-weight="500" style="fill:var(--ink)">Change the reviewer</text>
<text x="54" y="172" font-size="12.5" style="fill:var(--viz-muted)">its prompts, tools or model</text>
<text x="271" y="154.5" font-size="14" font-weight="500" style="fill:var(--ink)">Daily eval run</text>
<text x="271" y="172" font-size="12.5" style="fill:var(--viz-muted)">scored against every case</text>
<text x="488" y="154.5" font-size="14" font-weight="500" style="fill:var(--ink)">Score went up?</text>
<text x="488" y="172" font-size="12.5" style="fill:var(--viz-muted)">keep it; if not, drop it</text>
<path d="M181.3 40 L247 40" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M243 36.5 L247 40 L243 43.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M422.6 40 L464 40" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M460 36.5 L464 40 L460 43.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M474 50 L474 104 L257 104 L257 140" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M253.5 136 L257 140 L260.5 136" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M203.4 150 L247 150" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M243 146.5 L247 150 L243 153.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M368.9 150 L464 150" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M460 146.5 L464 150 L460 153.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M474 160 L474 214 L40 214 L40 160" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M36.5 164 L40 160 L43.5 164" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<text x="257" y="207" text-anchor="middle" font-size="13" style="fill:var(--ink-2)">next change</text>
<circle cx="40" cy="40" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="257" cy="40" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="474" cy="40" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="40" cy="150" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="257" cy="150" r="5.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="474" cy="150" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
</svg>
<svg class="art-diagram-narrow" aria-hidden="true" focusable="false" id="code-review-incident-eval-mobile" width="300" height="306" viewBox="0 0 300 306" xmlns="http://www.w3.org/2000/svg"><text x="46" y="14" font-size="14" font-weight="500" style="fill:var(--ink)">Incident or revert</text>
<text x="46" y="32" font-size="13" style="fill:var(--viz-muted)">a change that broke something</text>
<text x="46" y="66" font-size="14" font-weight="500" style="fill:var(--ink)">Expert-checked case</text>
<text x="46" y="84" font-size="13" style="fill:var(--viz-muted)">experts confirm the bug</text>
<text x="46" y="118" font-size="14" font-weight="500" style="fill:var(--ink)">Added to the set</text>
<text x="46" y="136" font-size="13" style="fill:var(--viz-muted)">each incident adds a case</text>
<text x="46" y="170" font-size="14" font-weight="500" style="fill:var(--ink)">Daily eval run</text>
<text x="46" y="188" font-size="13" style="fill:var(--viz-muted)">scored against every case</text>
<text x="46" y="222" font-size="14" font-weight="500" style="fill:var(--ink)">Score went up?</text>
<text x="46" y="240" font-size="13" style="fill:var(--viz-muted)">keep it; if not, drop it</text>
<text x="46" y="274" font-size="14" font-weight="500" style="fill:var(--ink)">Change the reviewer</text>
<text x="46" y="292" font-size="13" style="fill:var(--viz-muted)">its prompts, tools or model</text>
<path d="M30 19.5 L30 51.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M26.5 47.5 L30 51.5 L33.5 47.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M30 71.5 L30 103.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M26.5 99.5 L30 103.5 L33.5 99.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M30 123.5 L30 155.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M26.5 151.5 L30 155.5 L33.5 151.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M30 175.5 L30 207.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M26.5 203.5 L30 207.5 L33.5 203.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M30 227.5 L30 259.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M26.5 255.5 L30 259.5 L33.5 255.5" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<path d="M20 269.5 L8 269.5 L8 165.5 L20 165.5" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--viz-muted)"/>
<path d="M16 162 L20 165.5 L16 169" fill="none" stroke-width="1" stroke-linejoin="round" stroke-linecap="round" style="stroke:var(--viz-muted)"/>
<circle cx="30" cy="9.5" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="30" cy="61.5" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="30" cy="113.5" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="30" cy="165.5" r="5.5" stroke-width="2" style="fill:var(--fig-focal);stroke:var(--bg)"/>
<circle cx="30" cy="217.5" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
<circle cx="30" cy="269.5" r="5.5" stroke-width="2" style="fill:var(--viz-m1);stroke:var(--bg)"/>
</svg>
</div>
<figcaption><b>FIG C</b><span>每出一次事故，eval 就多一条；评审器的每次改动都要拿全部用例打分。</span></figcaption>
</figure>
<div class="yn-en" lang="en">
<p><strong>We measure noise by watching what people do with the comments.</strong> It's easy to catch more bugs if you don't mind flagging a lot of non-bugs, so we need a check on that. We sort every comment the reviewer leaves by how the person on the PR responded: they fixed it, said it was wrong, said the behavior was intentional, or decided it didn't matter. We also run the reviewer on PRs we know are clean and count how often it reports something that would have led someone to make a harmful change. Our priority, written down, is catching real bugs first and cutting review rounds second.</p>
</div>
<p><strong>噪音有多大，看人怎么处理评论。</strong> 要是不在乎标出一大堆不是 bug 的东西，多抓几个 bug 很容易，所以得有东西制衡。评审器留下的每条评论，我们都按 PR 上那个人的反应归类：修了、说它错了、说这个行为是故意的，或者觉得无所谓。我们还会拿确认干净的 PR 跑评审器，数它有多少次报出了会诱导人去做有害改动的东西。我们白纸黑字写下的优先级是：第一抓真 bug，第二减少评审轮数。</p>
<div class="yn-en" lang="en">
<p>Noise costs more when the author is an agent. A person can wave off a nit in seconds. An agent fixes it, which means another commit and another round of review.</p>
</div>
<p>作者是 agent 的时候，噪音更贵。人几秒钟就能把一条 nit 打发掉。agent 会老老实实去修，于是又多一个提交、又多一轮评审。</p>
<div class="yn-en" lang="en">
<p><strong>Review has to converge.</strong> An agent author and an agent reviewer can keep each other busy indefinitely. One CLI PR went through more than fifty rounds of review and fixes overnight before its author stopped it.</p>
</div>
<p><strong>评审必须收敛。</strong> agent 作者和 agent 评审器能没完没了地互相找活干。有个 CLI PR 一夜之间来回评审、修复了五十多轮，最后是作者叫停的。</p>
<div class="yn-en" lang="en">
<p>When we ran git blame on what the reviewer kept flagging, about 59% of it was code that had been there since the reviewer's first pass. The reviewer was rarely finding new bugs, it was finding a few more old ones each round.</p>
</div>
<p>我们对评审器反复标出的东西跑了一遍 git blame，发现大约 59% 是评审器第一轮时就已经在那儿的代码。评审器很少找到新 bug，只是每轮多翻出几个老的。</p>
<div class="yn-en" lang="en">
<p>We made it worse ourselves. We'd gotten used to running several rounds by default, since each pass catches something new. This can be worthwhile on a risky change, but not on every PR. The team now tracks rounds-to-pass alongside recall, and changed re-review:</p>
</div>
<p>这事我们自己也推波助澜了。因为每一轮都能抓到点新东西，我们习惯了默认跑好几轮。有风险的改动这么做也许值得，但不是每个 PR 都该这样。团队现在把通过所需轮数（rounds-to-pass）和召回率（recall）放在一起跟踪，还改了重新评审的做法：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>A round cap.</strong> After three rounds, the reviewer asks the author to step back and reconsider the approach.</span><strong>轮数上限。</strong> 三轮之后，评审器会请作者退一步，重新想想思路。</li>
<li><span class="yn-en" lang="en"><strong>Diff-only re-review</strong> after the first few passes.</span>前几轮之后，<strong>只对新的 diff 重新评审</strong>。</li>
<li><span class="yn-en" lang="en"><strong>Flag the class of bug,</strong> so the author fixes every instance, not one line.</span><strong>标出 bug 的类别</strong>，让作者把每一处都修掉，而不是只修一行。</li>
<li><span class="yn-en" lang="en"><strong>No repeats</strong> of findings already posted.</span>贴过的发现<strong>不再重复</strong>。</li>
</ul>
<div class="yn-en" lang="en">
<p>Review agents also run nightly over existing code, helping us catch old bugs before they show up somewhere else.</p>
</div>
<p>评审 agent 每晚还会把现有代码过一遍，赶在老 bug 从别处冒出来之前把它们抓住。</p>
<figure class="crv-fig">
<div class="crv-head"><div class="crv-title">会收敛的评审</div><div class="crv-sub">内部 PR，收敛改动前后对比</div></div>
<div class="crv-draw" role="img" aria-label="收敛改动前后：经过一轮评审和修复就通过的 PR 从 65% 升到 78%；需要五轮及以上的 PR 从 8.9% 降到 1.5%；通过前的平均评审次数从 2.08 降到 1.32。">
<svg class="art-diagram-wide" aria-hidden="true" focusable="false" id="code-review-convergence" width="651" height="253" viewBox="0 0 651 253" xmlns="http://www.w3.org/2000/svg"><text x="2" y="14" font-size="13" font-weight="500" style="fill:var(--ink)">Pass after one review and fix round</text>
<rect x="2" y="26" width="234.0" height="14" style="fill:var(--viz-b9)"/>
<text x="244" y="37" font-size="13" font-weight="400" style="fill:var(--ink-2)">65%</text>
<rect x="2" y="46" width="280.8" height="14" style="fill:var(--fig-focal)"/>
<text x="290.8" y="57" font-size="13" font-weight="500" style="fill:var(--ink)">78%</text>
<path d="M2 76 L647 76" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line-soft)"/>
<text x="2" y="96" font-size="13" font-weight="500" style="fill:var(--ink)">Need five or more rounds</text>
<rect x="2" y="108" width="32.0" height="14" style="fill:var(--viz-b9)"/>
<text x="42.04" y="119" font-size="13" font-weight="400" style="fill:var(--ink-2)">8.9%</text>
<rect x="2" y="128" width="5.4" height="14" style="fill:var(--fig-focal)"/>
<text x="15.4" y="139" font-size="13" font-weight="500" style="fill:var(--ink)">1.5%</text>
<path d="M2 158 L647 158" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line-soft)"/>
<text x="2" y="178" font-size="13" font-weight="500" style="fill:var(--ink)">Mean reviews to pass</text>
<rect x="2" y="190" width="249.6" height="14" style="fill:var(--viz-b9)"/>
<text x="259.6" y="201" font-size="13" font-weight="400" style="fill:var(--ink-2)">2.08</text>
<rect x="2" y="210" width="158.4" height="14" style="fill:var(--fig-focal)"/>
<text x="168.4" y="221" font-size="13" font-weight="500" style="fill:var(--ink)">1.32</text>
<rect x="2" y="239" width="10" height="10" style="fill:var(--viz-b9)"/>
<text x="18" y="248" font-size="13" style="fill:var(--ink-2)">before</text>
<rect x="84.26945755004883" y="239" width="10" height="10" style="fill:var(--fig-focal)"/>
<text x="100.26945755004883" y="248" font-size="13" style="fill:var(--ink-2)">after the convergence work</text>
</svg>
<svg class="art-diagram-narrow" aria-hidden="true" focusable="false" id="code-review-convergence-mobile" width="300" height="273" viewBox="0 0 300 273" xmlns="http://www.w3.org/2000/svg"><text x="2" y="14" font-size="13" font-weight="500" style="fill:var(--ink)">Pass after one review and fix round</text>
<rect x="2" y="26" width="149.5" height="14" style="fill:var(--viz-b9)"/>
<text x="159.5" y="37" font-size="13" font-weight="400" style="fill:var(--ink-2)">65%</text>
<rect x="2" y="46" width="179.4" height="14" style="fill:var(--fig-focal)"/>
<text x="189.39999999999998" y="57" font-size="13" font-weight="500" style="fill:var(--ink)">78%</text>
<path d="M2 76 L296 76" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line-soft)"/>
<text x="2" y="96" font-size="13" font-weight="500" style="fill:var(--ink)">Need five or more rounds</text>
<rect x="2" y="108" width="20.5" height="14" style="fill:var(--viz-b9)"/>
<text x="30.47" y="119" font-size="13" font-weight="400" style="fill:var(--ink-2)">8.9%</text>
<rect x="2" y="128" width="3.4" height="14" style="fill:var(--fig-focal)"/>
<text x="13.45" y="139" font-size="13" font-weight="500" style="fill:var(--ink)">1.5%</text>
<path d="M2 158 L296 158" fill="none" stroke-width="1" stroke-linejoin="round" style="stroke:var(--line-soft)"/>
<text x="2" y="178" font-size="13" font-weight="500" style="fill:var(--ink)">Mean reviews to pass</text>
<rect x="2" y="190" width="159.5" height="14" style="fill:var(--viz-b9)"/>
<text x="169.5" y="201" font-size="13" font-weight="400" style="fill:var(--ink-2)">2.08</text>
<rect x="2" y="210" width="101.2" height="14" style="fill:var(--fig-focal)"/>
<text x="111.2" y="221" font-size="13" font-weight="500" style="fill:var(--ink)">1.32</text>
<rect x="2" y="239" width="10" height="10" style="fill:var(--viz-b9)"/>
<text x="18" y="248" font-size="13" style="fill:var(--ink-2)">before</text>
<rect x="2" y="259" width="10" height="10" style="fill:var(--fig-focal)"/>
<text x="18" y="268" font-size="13" style="fill:var(--ink-2)">after the convergence work</text>
</svg>
</div>
<figcaption><b>FIG D</b><span>收敛改动之后，每个内部 PR 需要的评审轮数变少了</span></figcaption>
</figure>
<h2 id="where-humans-stay-in-the-loop人还守在哪些环节" tabindex="-1"><span class="yn-en ignore-header" lang="en">Where humans stay in the loop</span>人还守在哪些环节 <a class="header-anchor" href="#where-humans-stay-in-the-loop人还守在哪些环节" aria-label="本节链接：人还守在哪些环节">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Pulling a senior engineer out of deep work to catch a routine mistake costs far more than an automated review. People on the team are still responsible for:</p>
</div>
<p>为了抓一个常规错误把资深工程师从深度工作里拽出来，代价比一次自动评审高得多。团队里的人仍然负责这些：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Deciding whether to build it.</strong> Direction, taste and scope. One team that declared its review bottleneck solved still kept human review for changes from outside the team, so someone asks &quot;should we even do this?&quot;</span><strong>决定要不要做。</strong> 方向、品味和范围。有个团队都宣布评审瓶颈解决了，对团队外部来的改动却仍然保留人工评审，好让有人问一句「这个我们到底该不该做？」</li>
<li><span class="yn-en" lang="en"><strong>Reviewing risky code</strong> such as billing, the auto-updater and CI workflows.</span><strong>评审高风险代码</strong>，比如计费、自动更新器和 CI 工作流。</li>
<li><span class="yn-en" lang="en"><strong>Reviewing architecture</strong> that sets a pattern others will copy.</span><strong>评审架构</strong>，那些会定下模式、让别人照着抄的设计。</li>
<li><span class="yn-en" lang="en"><strong>Reading the evidence.</strong> Test output, the command that ran and what it returned, a screenshot, the reviewer's findings. If you can't say what the checks would miss, ask for a real review rather than a quick approval.</span><strong>看证据。</strong> 测试输出、跑了什么命令和它返回了什么、截图、评审器的发现。如果你说不出这些检查会漏掉什么，就去要一次真正的评审，别草草批了。</li>
<li><span class="yn-en" lang="en"><strong>Owning the outcome.</strong> A person is accountable for every change that ships, whoever typed it.</span><strong>对结果负责。</strong> 每个上线的改动都有一个人担责，不管代码是谁敲的。</li>
</ul>
<h2 id="sharing-context-across-the-team在团队里共享上下文" tabindex="-1"><span class="yn-en ignore-header" lang="en">Sharing context across the team</span>在团队里共享上下文 <a class="header-anchor" href="#sharing-context-across-the-team在团队里共享上下文" aria-label="本节链接：在团队里共享上下文">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Code review's second job has always been to spread codebase understanding. Reading a teammate's diff is how you learn what changed and how the pieces fit. If machines do most of the reading, how does anyone learn the code?</p>
</div>
<p>代码评审的第二件事，一直是让大家都懂代码库。读队友的 diff，你才知道改了什么、各部分是怎么拼起来的。如果大部分阅读都交给了机器，人还怎么去了解代码？</p>
<div class="yn-en" lang="en">
<p>We don't have a formal process for this. Nobody on the team keeps a complete mental model of Claude Code in their head, and we don't think anyone needs to. When someone wants to understand a part of the codebase, they ask Claude to write an explainer for exactly that slice. It takes minutes and reflects the code as it is today.</p>
</div>
<p>这件事我们没有正式的流程。团队里没有谁脑子里装着 Claude Code 完整的心智模型，我们也不觉得谁需要装。有人想弄懂代码库的某一块，就让 Claude 专门针对那一块写一份讲解。几分钟就好，讲的是代码今天的样子。</p>
<p><img src="https://nyann.cc/posts/how-the-claude-code-team-does-code-review/01.webp" alt="图的标题是「如果大部分阅读都交给机器，人还怎么去了解代码？」左边一个方格代表代码库，其中几格高亮为 managed settings，也就是你想弄懂的那一块；没有人脑子里装着它完整的心智模型。一个箭头标着「就那一块去问 Claude」，示例问题是「Claude Code 是怎么获取 managed settings 的？」，引出两种结果：Claude 写一份讲解，几分钟就好，反映代码今天的样子；有些人还会让 Claude 做一个小 artifact，把那部分代码可视化，按这个人喜欢的方式来讲。底部一行：逐行读琐碎的 diff，改一行文案几乎教不了你什么；你马上要改的那个模块的讲解，能教你很多。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Some of us go a step further and have Claude <a href="https://claude.dev/blog/using-claude-code-the-unreasonable-effectiveness-of-html/" target="_blank" rel="noreferrer">build a small artifact</a> that visualizes that part of the code and teaches it the way that person likes to learn.</p>
</div>
<p>我们有些人会再进一步，让 Claude <a href="https://claude.dev/blog/using-claude-code-the-unreasonable-effectiveness-of-html/" target="_blank" rel="noreferrer">做一个小 artifact</a>，把那部分代码可视化，按这个人喜欢的学习方式来讲。</p>
<div class="yn-en" lang="en">
<p>If the goal is to spend human attention well, this beats reading trivial diffs line by line. A one-line copy change teaches you almost nothing. An explainer for the module you're about to change teaches you a lot. Our culture of defaulting to working on open Slack channels helps too, since you see what others are building while they build it.</p>
</div>
<p>如果目标是把人的注意力花在刀刃上，这比逐行读琐碎的 diff 强得多。改一行文案的 diff 几乎教不了你什么。你马上要改的那个模块的讲解，能教你很多。我们默认在公开 Slack 频道里干活的文化也帮了忙：别人在做什么，你在他们做的时候就看得见。</p>
<h2 id="you-land-it-you-own-it-「谁合进去的-谁负责」" tabindex="-1"><span class="yn-en ignore-header" lang="en">&quot;You land it, you own it&quot;</span>「谁合进去的，谁负责」 <a class="header-anchor" href="#you-land-it-you-own-it-「谁合进去的-谁负责」" aria-label="本节链接：「谁合进去的，谁负责」">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>If you land a small or medium change and something still goes wrong, it's a team norm that you usually fix it. A few things keep this from going badly:</p>
</div>
<p>你合入了一个小型或中型改动，结果还是出了问题，那按团队惯例，一般由你来修。有几件事让这条规矩不至于变味：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Changes are small,</strong> so they're easy to review, debug and revert.</span><strong>改动都很小</strong>，所以好评审、好调试、好回滚。</li>
<li><span class="yn-en" lang="en"><strong>Everything is reversible.</strong> Flags, reverts and staged releases undo most mistakes in minutes.</span><strong>什么都能撤回。</strong> 功能开关、回滚和分阶段发布，能在几分钟内撤掉大多数错误。</li>
<li><span class="yn-en" lang="en"><strong>Blast radius sets the bar.</strong> Expensive code gets more people and more checks.</span><strong>影响范围（blast radius）决定门槛。</strong> 出错代价高的代码，要更多人、更多检查。</li>
<li><span class="yn-en" lang="en"><strong>Regressions surface fast</strong> through telemetry and internal use.</span><strong>回归问题暴露得快</strong>，靠遥测和内部使用。</li>
<li><span class="yn-en" lang="en"><strong>It isn't blame.</strong> Owning a fix means you have the most context; incident reviews look at the system.</span><strong>这不是追责。</strong> 由你来修，是因为你手里的上下文最多；事故复盘看的是系统。</li>
</ul>
<div class="yn-en" lang="en">
<p>Ownership is also shared. Much of the team works in <a href="https://claude.com/product/tag" target="_blank" rel="noreferrer">open channels</a> where anyone can see what others are building, pick up a thread, or point a Claude at a gap, and feedback comes from people who don't own the code too. That openness is a big part of how quality stays high without a gate on every line.</p>
</div>
<p>责任也是大家共担的。团队里很多人在<a href="https://claude.com/product/tag" target="_blank" rel="noreferrer">公开频道</a>里干活，谁都能看到别人在做什么，可以接过一条线索，或者派一个 Claude 去补某个缺口；反馈也会来自不负责这块代码的人。不给每一行都设关卡还能把质量守住，很大程度上靠的就是这种开放。</p>
<h2 id="when-we-change-direction需要掉头的时候" tabindex="-1"><span class="yn-en ignore-header" lang="en">When we change direction</span>需要掉头的时候 <a class="header-anchor" href="#when-we-change-direction需要掉头的时候" aria-label="本节链接：需要掉头的时候">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Agents make it cheap to start things, so some work shouldn't land. Usually someone in the channel asks why, points at an earlier decision, or suggests a simpler route, and the author closes or reshapes the PR.</p>
</div>
<p>有了 agent，开个头变得很便宜，所以有些活本来就不该合进去。通常是频道里有人问一句为什么，指出之前做过的某个决定，或者提一条更简单的路，然后作者就把 PR 关掉或者重新调整。</p>
<div class="yn-en" lang="en">
<p>Since the code was fast to write, closing the PR doesn't feel like a loss. The trick is to raise a different direction in the thread early, not as a blocking comment on a finished PR.</p>
</div>
<p>代码本来就写得快，关掉 PR 也不觉得心疼。诀窍是早点在讨论串里提出别的方向，别等 PR 都做完了再甩一条拦路的评论。</p>
<h2 id="how-you-can-adopt-this-process你可以怎么用上这套流程" tabindex="-1"><span class="yn-en ignore-header" lang="en">How you can adopt this process</span>你可以怎么用上这套流程 <a class="header-anchor" href="#how-you-can-adopt-this-process你可以怎么用上这套流程" aria-label="本节链接：你可以怎么用上这套流程">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Most of the pieces to do this with your team exist today.</p>
</div>
<p>在你自己团队里这么做，需要的零件今天大部分都已经有了。</p>
<h3 id="before-the-pull-request开-pr-之前" tabindex="-1"><span class="yn-en ignore-header" lang="en">Before the pull request</span>开 PR 之前 <a class="header-anchor" href="#before-the-pull-request开-pr-之前" aria-label="本节链接：开 PR 之前">&ZeroWidthSpace;</a></h3>
<ul>
<li><span class="yn-en" lang="en">Give your agent checks it can run, listed in a short <code>CLAUDE.md</code>, plus hooks that run formatters and linters.</span>给你的 agent 一些它能跑的检查，列在一份简短的 <code>CLAUDE.md</code> 里，再加上跑格式化工具和 linter 的 hook。</li>
<li><span class="yn-en" lang="en">Run <code>/code-review</code> and <code>/security-review</code> locally, or a fresh-context subagent review.</span>在本地跑 <code>/code-review</code> 和 <code>/security-review</code>，或者让一个带全新上下文的子 agent 来评审。</li>
<li><span class="yn-en" lang="en">Add a <code>REVIEW.md</code>, and move repeated review comments into it.</span>加一份 <code>REVIEW.md</code>，把反复出现的评审意见挪进去。</li>
</ul>
<h3 id="on-every-pull-request每个-pr-上" tabindex="-1"><span class="yn-en ignore-header" lang="en">On every pull request</span>每个 PR 上 <a class="header-anchor" href="#on-every-pull-request每个-pr-上" aria-label="本节链接：每个 PR 上">&ZeroWidthSpace;</a></h3>
<ul>
<li><span class="yn-en" lang="en">Require CI, and add &quot;Testing&quot;, &quot;Risk&quot; and &quot;How to revert&quot; to your PR template.</span>强制要求 CI，在 PR 模板里加上「测试」「风险」和「如何撤回」三项。</li>
<li><span class="yn-en" lang="en">Add an AI reviewer (Code Review for Claude Code, or the Claude Code GitHub Action) on one repo, tune <code>REVIEW.md</code> for a few weeks, then widen.</span>先在一个仓库上加 AI 评审器（Code Review for Claude Code，或者 Claude Code GitHub Action），花几周调 <code>REVIEW.md</code>，再铺开。</li>
<li><span class="yn-en" lang="en">Add automated security review, and require every review thread resolved before merge.</span>加上自动安全评审，要求合并前所有评审讨论串都已解决。</li>
<li><span class="yn-en" lang="en">Match review effort to risk: a quick pass on routine changes, a deep one where a missed bug is expensive (Quick, Standard or Deep in Code Review).</span>让评审投入跟风险匹配：常规改动快速过一遍，漏一个 bug 代价高的地方就深挖（对应 Code Review 里的 Quick、Standard 或 Deep）。</li>
<li><span class="yn-en" lang="en">Cap review rounds; after the first few, re-review only the new diff.</span>给评审轮数设上限；前几轮之后，只重新评审新的 diff。</li>
</ul>
<h3 id="approval批准" tabindex="-1"><span class="yn-en ignore-header" lang="en">Approval</span>批准 <a class="header-anchor" href="#approval批准" aria-label="本节链接：批准">&ZeroWidthSpace;</a></h3>
<ul>
<li><span class="yn-en" lang="en">Write down risk tiers, set from the change rather than the author; start strict and loosen with evidence.</span>把风险档位写下来，按改动而不是按作者来定；一开始从严，有了证据再放宽。</li>
<li><span class="yn-en" lang="en">Keep the lighter approval paths for authors you trust.</span>轻量的批准通道只留给你信得过的作者。</li>
<li><span class="yn-en" lang="en">Use CODEOWNERS and branch protection so auth, billing, CI and release workflows, and installers always need a person.</span>用 CODEOWNERS 和分支保护，让鉴权、计费、CI 和发布工作流、安装程序永远需要人来批。</li>
<li><span class="yn-en" lang="en">Never let a bot's approval replace a required human's; dismiss approvals on new commits.</span>绝不让机器人的批准顶替必需的人工批准；有新提交就作废已有的批准。</li>
</ul>
<h3 id="merge-and-after合并及之后" tabindex="-1"><span class="yn-en ignore-header" lang="en">Merge and after</span>合并及之后 <a class="header-anchor" href="#merge-and-after合并及之后" aria-label="本节链接：合并及之后">&ZeroWidthSpace;</a></h3>
<ul>
<li><span class="yn-en" lang="en">Use a merge queue, feature flags, internal use first, staged releases and one-step rollback.</span>用上合并队列、功能开关、先内部使用、分阶段发布和一步回滚。</li>
<li><span class="yn-en" lang="en">Turn incidents and reverts into an eval set, and rescore the reviewer whenever its prompts, tools or model change.</span>把事故和回滚做成 eval 集，评审器的提示词、工具或模型一变就重新打分。</li>
<li><span class="yn-en" lang="en">Measure human time, with revert and incident rates as the guardrail.</span>衡量人的时间，拿回滚率和事故率当护栏。</li>
</ul>
<h2 id="where-this-is-going接下来往哪走" tabindex="-1"><span class="yn-en ignore-header" lang="en">Where this is going</span>接下来往哪走 <a class="header-anchor" href="#where-this-is-going接下来往哪走" aria-label="本节链接：接下来往哪走">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Code Review's <a href="https://claude.com/resources/articles/code-review" target="_blank" rel="noreferrer">announcement</a> said approving a pull request is still a human call; the product posts findings, not approvals. Our own repos go further, letting owners decide which low-risk changes merge on automated checks alone, and that line keeps moving.</p>
</div>
<p>Code Review 的<a href="https://claude.com/resources/articles/code-review" target="_blank" rel="noreferrer">发布公告</a>里说过，批不批一个 PR 仍然由人拍板；这个产品贴出来的是发现，不是批准。我们自己的仓库走得更远，让负责人决定哪些低风险改动单凭自动检查就能合并，而且这条线还在往前挪。</p>
<div class="yn-en" lang="en">
<p>When a review misses something, we ask what the model didn't have in front of it and put the fix into a <code>CLAUDE.md</code>, a skill or a new check. The goal hasn't changed: less human time per change, and no more reverts than before.</p>
</div>
<p>评审漏了东西，我们就问：模型当时手边缺了什么？然后把修复放进 <code>CLAUDE.md</code>、某个 skill 或者一项新检查里。目标一直没变：每个改动少花人的时间，回滚不比以前多。</p>
<div class="yn-en" lang="en">
<p>If your team lets agents open pull requests, we'd like to hear which checks you've automated, which still need a person, and what you think we have wrong.</p>
</div>
<p>如果你的团队也让 agent 开 PR，我们很想听听：你们自动化了哪些检查，哪些还得靠人，以及你觉得我们哪里做错了。</p>
<div class="yn-en" lang="en">
<p><em>With thanks to Emma Webb, Michael Segner and Amie Rotherham for their reviews.</em></p>
</div>
<p><em>感谢 Emma Webb、Michael Segner 和 Amie Rotherham 帮忙审阅。</em></p>
]]></content:encoded>
</item>
<item>
<title>使用 Claude Code：推理强度怎么花</title>
<link>https://nyann.cc/posts/%E4%BD%BF%E7%94%A8%20Claude%20Code%EF%BC%9A%E6%8E%A8%E7%90%86%E5%BC%BA%E5%BA%A6%E6%80%8E%E4%B9%88%E8%8A%B1</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E4%BD%BF%E7%94%A8%20Claude%20Code%EF%BC%9A%E6%8E%A8%E7%90%86%E5%BC%BA%E5%BA%A6%E6%80%8E%E4%B9%88%E8%8A%B1</guid>
<pubDate>Wed, 28 Oct 2026 00:00:00 GMT</pubDate>
<description>effort 到底是什么、在 Claude Code 里什么时候该用哪一档。作者拿三个构建任务实测，又细读了 Opus 5.5 和 Fable 5.1 在 Terminal-Bench 3.0 上的结果：推理强度管的是验证和边界情况测得多细。</description>
<category>翻译</category>
<category>AI</category>
<category>Claude</category>
<category>Claude Code</category>
<content:encoded><![CDATA[<h1 id="使用-claude-code-推理强度怎么花" tabindex="-1">使用 Claude Code：推理强度怎么花 <a class="header-anchor" href="#使用-claude-code-推理强度怎么花" aria-label="本节链接：使用 Claude Code：推理强度怎么花">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>One of the best parts of our newest Claude models is how they respond to effort without <a href="https://claude.dev/blog/lessons-from-building-claude-code-prompt-caching-is-everything/" target="_blank" rel="noreferrer">breaking the prompt cache</a> in Claude Code, but I’ve received a lot of questions on this from users. <a href="https://claude.com/blog/claude-model-and-effort-level-in-claude-code" target="_blank" rel="noreferrer">What is effort</a> really, and when do you use which effort level? Why do we need effort at all?</p>
</div>
<p>我们最新这批 Claude 模型有个特别好的地方：在 Claude Code 里调推理强度（effort），它们会跟着变，而且不会<a href="https://claude.dev/blog/lessons-from-building-claude-code-prompt-caching-is-everything/" target="_blank" rel="noreferrer">打破提示词缓存</a>。不过用户为这个问了我很多问题。<a href="https://claude.com/blog/claude-model-and-effort-level-in-claude-code" target="_blank" rel="noreferrer">推理强度</a>到底是什么？什么时候该用哪一档？我们为什么需要它？</p>
<div class="yn-en" lang="en">
<p>To answer this, I decided to do a deep dive into the evals and do my own tests of effort across normal work.</p>
</div>
<p>为了回答这些，我决定把评测结果仔细翻一遍，再拿日常的活儿自己测测不同的推理强度。</p>
<div class="yn-en" lang="en">
<p>At a high level, I found that effort was a great way of modulating how much verification and edgecase testing Claude did and how much of its own judgement it used. Extra effort gave better results in domains where verification and edgecase testing was more useful like hardware, code review, and security.</p>
</div>
<p>大体上，我发现推理强度很适合用来调节两件事：Claude 做多少验证和边界情况测试，以及它自己拿多少主意。在验证和边界测试更有用的领域，比如硬件、代码评审、安全，调高推理强度效果更好。</p>
<div class="yn-en" lang="en">
<p>For normal software engineering, I’m running a loop of getting the model to interview me then implementing on low effort, reviewing what it built, and then running verification on high effort.</p>
</div>
<p>日常的软件开发，我现在是这么循环的：先让模型来问我需求，然后用 low 实现，看一遍它做出来的东西，最后用 high 做验证。</p>
<h2 id="what-is-effort-推理强度是什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What is effort?</span>推理强度是什么？ <a class="header-anchor" href="#what-is-effort-推理强度是什么" aria-label="本节链接：推理强度是什么？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>At a high level, effort gives the model an approximation of how much compute you want it to spend on the task. It’s somewhat related to your modeling of the difficulty of the task.</p>
</div>
<p>粗略地说，推理强度是在告诉模型，你大概希望它在这个任务上花多少算力。这和你自己对任务难度的估计有点关系。</p>
<div class="yn-en" lang="en">
<p>Think of it this way, if someone asked you to do something in 12 hours straight, you might assume they just want you to do it and try very hard. If someone asked you to do the same task in 1 hour, you’d try to get them the best version that meets their task and then expect to iterate from there.</p>
</div>
<p>可以这么想：要是有人让你连着干 12 个小时做一件事，你多半会以为对方就是要你做成，而且要拼尽全力。要是同一件事只给你 1 个小时，你会先交出一个能满足需求的最好版本，然后预期接下来还要再改几轮。</p>
<div class="yn-en" lang="en">
<p>Or, you might push back and say the task requires at <em>least</em> 3 hours and then work for 3 hours to deliver it.</p>
</div>
<p>又或者，你会顶回去，说这活儿<em>至少</em>要 3 个小时，然后干满 3 个小时再交。</p>
<div class="yn-en" lang="en">
<p>You should think of effort in the same way. Claude will always try and do your task reasonably, but higher effort will involve Claude taking more independent action for judgement and verification.</p>
</div>
<p>推理强度也该这么理解。Claude 无论如何都会尽量把你的任务做得像样，但推理强度越高，它就越会自己动手去判断、去验证。</p>
<h2 id="effort-curves推理强度曲线" tabindex="-1"><span class="yn-en ignore-header" lang="en">Effort curves</span>推理强度曲线 <a class="header-anchor" href="#effort-curves推理强度曲线" aria-label="本节链接：推理强度曲线">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Fable 5.1 and Opus 5.5’s effort curves are our best yet: at each level, there is an uptick in benchmark scores and tokens consumed.</p>
</div>
<p>Fable 5.1 和 Opus 5.5 的推理强度曲线是我们迄今最好的：每往上调一档，基准分和消耗的 token 都会涨一截。</p>
<EffortCurve /><div class="yn-en" lang="en">
<p>But what does this mean in practice? To evaluate this, I tried several tasks at different effort levels and pored over the benchmarks.</p>
</div>
<p>可这在实际使用里意味着什么？为了弄清楚，我用不同的推理强度试了几个任务，又把基准测试的结果仔细看了一遍。</p>
<h2 id="building-with-effort用不同的推理强度做东西" tabindex="-1"><span class="yn-en ignore-header" lang="en">Building with effort</span>用不同的推理强度做东西 <a class="header-anchor" href="#building-with-effort用不同的推理强度做东西" aria-label="本节链接：用不同的推理强度做东西">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The best way to understand how models work is to run experiments. I tried doing the same tasks at several different effort levels on Opus 5.5 to understand the work it would do. I did this on a wide variety of work, but am illustrating this with a few toy examples.</p>
</div>
<p>想搞懂模型怎么干活，最好的办法是做实验。我在 Opus 5.5 上用几档不同的推理强度做同样的任务，看它分别会做些什么。我试过的活儿五花八门，这里只拿几个玩具例子来说明。</p>
<h3 id="underspecified-build-task需求没说清的构建任务" tabindex="-1"><span class="yn-en ignore-header" lang="en">Underspecified build task</span>需求没说清的构建任务 <a class="header-anchor" href="#underspecified-build-task需求没说清的构建任务" aria-label="本节链接：需求没说清的构建任务">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>If I ask Claude to “build a personal fitness and workout tracker app,” effort changes dramatically how fleshed out the app is, but also results in Claude making more choices along the way. At low effort, the fitness app is just a log and a simple graph. At higher effort levels the app is more complex with additional detail. At max effort there’s a heat chart.</p>
</div>
<p>如果我让 Claude「做一个个人健身和训练记录应用」，推理强度会大大改变这个应用做得有多完整，同时 Claude 一路上替我做的决定也更多。low 下，健身应用就是一个记录列表加一张简单的图。档位越高，应用越复杂，细节越多。到了 max，还多出一张热力图。</p>
<EffortFigure name="builds" /><div class="yn-en" lang="en">
<p>If I wanted a simple base to iterate from, low effort would get it done. Max effort would be if I wanted Claude’s best one shot.</p>
</div>
<p>如果我只想要一个简单的底子再慢慢迭代，low 就够了。想让 Claude 一次拿出它最好的东西，就用 max。</p>
<h3 id="lightly-specified-design-task需求说了一点的设计任务" tabindex="-1"><span class="yn-en ignore-header" lang="en">Lightly specified design task</span>需求说了一点的设计任务 <a class="header-anchor" href="#lightly-specified-design-task需求说了一点的设计任务" aria-label="本节链接：需求说了一点的设计任务">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>What if I have a task that is fairly specified already but I want some exploration with Claude? As an example I tried to ask it to redesign the <code>/config</code> menu in Claude Code. Every pass had roughly the same idea, to use submenus and better search.</p>
</div>
<p>要是任务已经说得比较清楚，但我还想跟 Claude 一起探索一下呢？举个例子，我让它重新设计 Claude Code 里的 <code>/config</code> 菜单。每一轮的思路都差不多：用子菜单，再把搜索做好。</p>
<div class="yn-en" lang="en">
<p>At low effort (which took 1 minute), I got an interactive sketch that conveyed the idea but didn’t look very much like Claude Code.</p>
</div>
<p>low 下（花了 1 分钟），我拿到一个可交互的草图，意思传达到了，但看着不太像 Claude Code。</p>
<div class="yn-en" lang="en">
<p>At max effort (which took 28 minutes), I got a mockup that looked very much like Claude Code, along with a bunch of walkthroughs for different flows.</p>
</div>
<p>max 下（花了 28 分钟），我拿到一个很像 Claude Code 的模型稿，还附带一堆不同流程的演示。</p>
<div class="yn-en" lang="en">
<p>If my goal was to iterate and give feedback, low effort would get there much faster. But max effort gives me something much more polished right off the bat. For this particular task, I think I prefer using low effort to understand Claude’s vision.</p>
</div>
<p>如果我的目的是迭代、给反馈，low 快得多。max 则一上来就给我一个精致得多的东西。就这个任务来说，我更愿意用 low 先看懂 Claude 的思路。</p>
<EffortFigure name="config" /><h3 id="highly-specified-build-task需求写得很细的构建任务" tabindex="-1"><span class="yn-en ignore-header" lang="en">Highly specified build task</span>需求写得很细的构建任务 <a class="header-anchor" href="#highly-specified-build-task需求写得很细的构建任务" aria-label="本节链接：需求写得很细的构建任务">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>What if I gave Claude lots of details? I tried asking Claude to interview me in-depth about the fitness app and then gave that spec to be implemented by different models at different effort levels.</p>
</div>
<p>如果我给 Claude 很多细节呢？我先让 Claude 就这个健身应用把我细细问了一遍，然后把得到的规格说明交给不同的模型、用不同的推理强度去实现。</p>
<div class="yn-en" lang="en">
<p>I found that given this spec, the models behaved much more similarly. I got designs that looked fairly similar and had similar implementations but with different details, at max effort Claude took some time to simplify a few of the details.</p>
</div>
<p>我发现有了这份规格说明，各个模型的表现接近得多。设计看着差不多，实现也差不多，只是细节不同；max 下 Claude 还花了些时间把几处细节简化了。</p>
<EffortFigure name="spec" /><h3 id="takeaways小结" tabindex="-1"><span class="yn-en ignore-header" lang="en">Takeaways</span>小结 <a class="header-anchor" href="#takeaways小结" aria-label="本节链接：小结">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>For regular software engineering, particularly new feature work, the effort level depends a lot on how in the loop I want to be. Low effort allows Claude to respond quickly with a starting point, higher effort levels will get more work done but Claude will also make more assumptions on my behalf.</p>
</div>
<p>对日常的软件开发，尤其是做新功能，选哪一档很大程度上取决于我想参与多少。low 能让 Claude 很快给出一个起点；档位越高，做完的活儿越多，但 Claude 替我做的假设也越多。</p>
<div class="yn-en" lang="en">
<p>A particularly fruitful loop for feature development I’ve been using is:</p>
</div>
<p>我开发功能时一直在用一个特别好使的循环：</p>
<ul>
<li><span class="yn-en" lang="en">Give Claude a spec and ask it to interview me about any details I’m missing</span>给 Claude 一份规格说明，让它就我漏掉的细节来问我</li>
<li><span class="yn-en" lang="en">Implement it on low effort</span>用 low 实现</li>
<li><span class="yn-en" lang="en">Review to make sure it got the gist of it correct, iterate on low effort as needed</span>看一遍，确认大方向没错，需要的话继续用 low 迭代</li>
<li><span class="yn-en" lang="en">Verify and test on high effort</span>用 high 验证和测试</li>
</ul>
<h2 id="how-effort-levels-impact-output-on-difficult-tasks难题上-推理强度怎样影响结果" tabindex="-1"><span class="yn-en ignore-header" lang="en">How effort levels impact output on difficult tasks</span>难题上，推理强度怎样影响结果 <a class="header-anchor" href="#how-effort-levels-impact-output-on-difficult-tasks难题上-推理强度怎样影响结果" aria-label="本节链接：难题上，推理强度怎样影响结果">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>But these are obviously toy examples, where Claude is well able to complete them. What about when the difference is between Claude completing the task or not completing the task?</p>
</div>
<p>不过这些显然都是玩具例子，Claude 完全做得来。要是差别在于 Claude 能不能把任务做成，又会怎样？</p>
<div class="yn-en" lang="en">
<p>To find these difficult problems, you have to go to the benchmarks so I dove into one I like: Terminal-Bench 3.0, a community-sourced benchmark.</p>
</div>
<p>这种难题得去基准测试里找，所以我钻进了一个我喜欢的：Terminal-Bench 3.0，一个由社区出题的基准。</p>
<div class="yn-en" lang="en">
<p>Terminal-Bench 3.0 problems can broadly be separated into categories like security, hardware, ML, science, software, operations and media. You can see all of the problems here: <a href="https://github.com/harbor-framework/terminal-bench/releases/tag/v3.0.0" target="_blank" rel="noreferrer">https://github.com/harbor-framework/terminal-bench/releases/tag/v3.0.0</a>. They’re sourced from the community, so anyone can contribute.</p>
</div>
<p>Terminal-Bench 3.0 的题目大致可以分成安全、硬件、机器学习、科学、软件、运营和媒体这几类。所有题目都在这里：<a href="https://github.com/harbor-framework/terminal-bench/releases/tag/v3.0.0" target="_blank" rel="noreferrer">https://github.com/harbor-framework/terminal-bench/releases/tag/v3.0.0</a>。题目来自社区，谁都可以贡献。</p>
<div class="yn-en" lang="en">
<p>It’s worth reading to get a sense of the type of problems these models face. I found I was surprised by the scope and ambition of a lot of these tasks. They are much more complicated than the average task I’d face.</p>
</div>
<p>值得读一读，感受一下这些模型面对的是什么样的问题。很多题目的规模和野心让我吃了一惊，比我平时碰到的一般任务复杂得多。</p>
<div class="yn-en" lang="en">
<p>For example, some of the tasks included:</p>
</div>
<p>比如其中有这些题：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Hardware</strong> (<code>retro-console-soc</code>): build an 8-bit game console in Verilog that fits a small FPGA and renders a test ROM.</span><strong>硬件</strong>（<code>retro-console-soc</code>）：用 Verilog 做一台 8 位游戏机，要塞进一块小 FPGA，还要能渲染一个测试 ROM。</li>
<li><span class="yn-en" lang="en"><strong>Science</strong> (<code>takens-embedding-lean</code>): formally prove Takens’ embedding theorem in Lean 4.</span><strong>科学</strong>（<code>takens-embedding-lean</code>）：在 Lean 4 里形式化证明 Takens 嵌入定理。</li>
<li><span class="yn-en" lang="en"><strong>ML</strong> (<code>mp-checkpoint-consolidation</code>): merge 16 shards of a mixture-of-experts checkpoint into one file that reproduces the reference logits.</span><strong>机器学习</strong>（<code>mp-checkpoint-consolidation</code>）：把一个混合专家（mixture-of-experts）模型检查点的 16 个分片合并成一个文件，要能复现参考 logits。</li>
<li><span class="yn-en" lang="en"><strong>Operations</strong> (<code>intrastat-meldung</code>): run a company’s month-end EU trade-statistics filing end to end.</span><strong>运营</strong>（<code>intrastat-meldung</code>）：把一家公司月末的欧盟贸易统计申报从头到尾跑一遍。</li>
<li><span class="yn-en" lang="en"><strong>Media</strong> (<code>layout-config-recreation</code>): rebuild a poster image as an editable layout file.</span><strong>媒体</strong>（<code>layout-config-recreation</code>）：把一张海报图片重建成可编辑的版式文件。</li>
</ul>
<h3 id="higher-effort-levels-help-when-there-are-many-edge-cases边界情况多的时候-高档位有用" tabindex="-1"><span class="yn-en ignore-header" lang="en">Higher effort levels help when there are many edge cases</span>边界情况多的时候，高档位有用 <a class="header-anchor" href="#higher-effort-levels-help-when-there-are-many-edge-cases边界情况多的时候-高档位有用" aria-label="本节链接：边界情况多的时候，高档位有用">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>My main takeaway from reading the Terminal-Bench 3.0 results was that <strong>higher effort is best for tasks with lots of hidden edge cases.</strong></p>
</div>
<p>读完 Terminal-Bench 3.0 的结果，我最大的收获是：<strong>推理强度越高，越适合藏着大量边界情况的任务。</strong></p>
<div class="yn-en" lang="en">
<p>A clean example is <code>html-js-filter</code>, a Terminal-Bench 3.0 task that asks for an HTML sanitizer that strips every way of smuggling JavaScript into a page. Fable 5.1 went from 1/5 at low to 5/5 at xhigh.¹</p>
</div>
<p>一个很干净的例子是 <code>html-js-filter</code>。这道 Terminal-Bench 3.0 的题要求写一个 HTML 净化器，把往页面里偷塞 JavaScript 的所有路子都堵掉。Fable 5.1 从 low 的 1/5 涨到了 xhigh 的 5/5。¹</p>
<div class="yn-en" lang="en">
<p>A typical attempt at low effort takes about 2 minutes. Each of these attempts wrote a filter in roughly one pass, then tested it against a single hand-written page.</p>
</div>
<p>low 下一次典型的尝试大约 2 分钟。每次都是差不多一遍写完过滤器，再拿一个手写的页面测一下。</p>
<div class="yn-en" lang="en">
<p>A high-effort run finishes in about 33 minutes. In the run I traced, it adversarially reviewed its first draft, then read the installed parser’s source to check for bugs, ran many clean test cases until they gave the same output as the input, ran a standard XSS test suite, and finally, wrote a random-document fuzzer.</p>
</div>
<p>high 下跑一次大约 33 分钟。我跟踪的那次，它先挑刺似的审了一遍自己的初稿，然后去读已安装的解析器的源码找 bug，跑了很多干净的测试用例，直到输出和输入一致为止，又跑了一套标准的 XSS 测试，最后还写了一个随机生成文档的模糊测试器。</p>
<div class="yn-en" lang="en">
<p>For something as edge-cased as a HTML sanitizer, this extra effort is well worth it. <a href="https://claude.dev/blog/what-a-task-costs-on-opus-5-5/" target="_blank" rel="noreferrer">Spending more tokens for thoroughness</a> also makes sense for complex tasks with high production requirements such as performance optimization or security review.</p>
</div>
<p>HTML 净化器这种满是边界情况的东西，多花这份力气非常值。对生产要求高的复杂任务，比如性能优化或安全审查，<a href="https://claude.dev/blog/what-a-task-costs-on-opus-5-5/" target="_blank" rel="noreferrer">多花些 token 换来周全</a>也说得通。</p>
<div class="yn-en" lang="en">
<p>But you don’t need this level of effort for every task.</p>
</div>
<p>但不是每个任务都需要这么高的推理强度。</p>
<div class="yn-en" lang="en">
<p>The diagram below shows every Terminal-Bench 3.0 result and how it failed, across different models and effort levels. Overall, increasing effort tends to reduce failures due to missing edgecases (purple blocks), but does not fix when the model has the wrong approach (blue blocks).</p>
</div>
<p>下面这张图列出了 Terminal-Bench 3.0 的每一个结果，以及它在不同模型、不同推理强度下是怎么失败的。总体来看，调高推理强度往往能减少因漏掉边界情况导致的失败（紫色块），但模型思路本身错了的时候（蓝色块），调高也救不回来。</p>
<EffortFigure name="attempts" /><h3 id="problem-areas-where-effort-helps推理强度在哪些领域管用" tabindex="-1"><span class="yn-en ignore-header" lang="en">Problem areas where effort helps</span>推理强度在哪些领域管用 <a class="header-anchor" href="#problem-areas-where-effort-helps推理强度在哪些领域管用" aria-label="本节链接：推理强度在哪些领域管用">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>One of the most interesting takeaways for me from evaluating these models on Terminal-Bench 3.0 was that there were some problem areas that benefited from effort more than others. You can see a breakdown in the following diagram:</p>
</div>
<p>用 Terminal-Bench 3.0 评测这些模型，我觉得最有意思的发现之一是：有些领域从推理强度里得到的好处比别的领域多。下面这张图是分领域的情况：</p>
<EffortFigure name="pays" /><div class="yn-en" lang="en">
<p>To illustrate this, I chose a few problems from different areas from Terminal-Bench 3.0 where Opus 5.5 failed at low effort but succeeded at high effort — mostly because it tested and accounted for edge cases:</p>
</div>
<p>为了说明这一点，我从 Terminal-Bench 3.0 的不同领域挑了几道题，Opus 5.5 在 low 下做不出来，在高档位下做成了，主要是因为它测试并照顾到了边界情况：</p>
<div class="yn-en" lang="en">
<p><strong><code>mvcc-lsm-compaction</code></strong>: a Terminal-Bench 3.0 task that asks for a fix to a storage-engine bug from its crash report, without breaking compaction. Opus 5.5 went from 0/5 at low to 4/5 at xhigh.</p>
</div>
<p><strong><code>mvcc-lsm-compaction</code></strong>：这道 Terminal-Bench 3.0 的题要根据崩溃报告修好一个存储引擎的 bug，同时不能把压缩（compaction）弄坏。Opus 5.5 从 low 的 0/5 涨到了 xhigh 的 4/5。</p>
<div class="yn-en" lang="en">
<p>At low (about a minute per attempt), Claude would edit the code before building it or running the reproducer, and did not check that its new test would have caught the original bug.</p>
</div>
<p>low 下（每次大约 1 分钟），Claude 还没构建、没跑复现脚本就去改代码，也没检查自己新写的测试能不能抓到原来那个 bug。</p>
<div class="yn-en" lang="en">
<p>At xhigh (about 11 minutes), Claude reproduced the crash first, wrote a randomized test against a reference that never compacts, and checked that its tests failed on half-finished fixes.</p>
</div>
<p>xhigh 下（大约 11 分钟），Claude 先把崩溃复现出来，写了一个随机化测试，拿一个从不做压缩的参考实现来对照，还确认了半成品的修复过不了它的测试。</p>
<div class="yn-en" lang="en">
<p><strong><code>cli-2ph-simplex</code></strong>: a Terminal-Bench 3.0 task that asks for a CLI linear-program solver written in Python. Opus 5.5 went from 0/5 at low to 5/5 at high.</p>
</div>
<p><strong><code>cli-2ph-simplex</code></strong>：这道 Terminal-Bench 3.0 的题要用 Python 写一个命令行的线性规划求解器。Opus 5.5 从 low 的 0/5 涨到了 high 的 5/5。</p>
<div class="yn-en" lang="en">
<p>The low attempts wrote a solver in one pass, checked it with a few small problems and stopped around 10k tokens. In the final message, Claude warned it might be slow on big problems, but did not check.</p>
</div>
<p>low 下的尝试一遍写完求解器，拿几个小问题检查一下，到 1 万 token 左右就停了。Claude 在最后一条消息里提醒说大问题上可能会慢，但没去验证。</p>
<div class="yn-en" lang="en">
<p>During the high attempts, Claude tested its solver on random problems against a separate brute-force solver, then timed bigger ones, hit cases that ran far too long or crashed, and reworked its search.</p>
</div>
<p>high 下，Claude 拿随机问题测试自己的求解器，和另写的一个暴力求解器对照，然后给更大的问题计时，撞上了跑得太久或者崩溃的情况，于是重做了搜索部分。</p>
<div class="yn-en" lang="en">
<p><strong><code>gsea-proteomics</code></strong>: a Terminal-Bench 3.0 task that asks for a gene set enrichment analysis (GSEA) on proteomics data to find which of eight treatments resemble a target tissue. Opus 5.5 went from 0/5 at low to 4/5 at high.</p>
</div>
<p><strong><code>gsea-proteomics</code></strong>：这道 Terminal-Bench 3.0 的题要对蛋白质组学数据做基因集富集分析（GSEA），找出八种处理里哪些和目标组织相似。Opus 5.5 从 low 的 0/5 涨到了 high 的 4/5。</p>
<div class="yn-en" lang="en">
<p>At low effort, Claude picked a reasonable-sounding way to prep the data, ran the analysis that one way, and reported the result.</p>
</div>
<p>low 下，Claude 挑了一种听上去合理的数据预处理方式，按这一种方式跑完分析，就报告了结果。</p>
<div class="yn-en" lang="en">
<p>At high, Claude tried two ways of prepping the data, noticed that the list of significant treatments changed, and dug into why before choosing the correct one.</p>
</div>
<p>high 下，Claude 试了两种预处理方式，发现显著的处理列表变了，就先追查原因，再选出正确的那种。</p>
<div class="yn-en" lang="en">
<p>If a user were in the loop, Claude may have asked the user about the way to set up the problem, but without a user in the loop, high effort does better.</p>
</div>
<p>如果有用户参与，Claude 也许会去问用户这个问题该怎么设定；但没有用户参与的时候，high 做得更好。</p>
<h3 id="when-to-use-different-effort-levels-in-claude-code在-claude-code-里什么时候用哪一档" tabindex="-1"><span class="yn-en ignore-header" lang="en">When to use different effort levels in Claude Code</span>在 Claude Code 里什么时候用哪一档 <a class="header-anchor" href="#when-to-use-different-effort-levels-in-claude-code在-claude-code-里什么时候用哪一档" aria-label="本节链接：在 Claude Code 里什么时候用哪一档">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Here’s my rule of thumb on when to use which effort level:</p>
</div>
<p>我自己选档位的经验法则是这样的：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Low</strong>: for when I want quick responses that are in the loop, e.g. brainstorming, sketching, easy changes</span><strong>Low</strong>：我想要快速响应、自己全程参与的时候，比如头脑风暴、画草图、简单的改动</li>
<li><span class="yn-en" lang="en"><strong>Medium</strong>: for most of my regular software engineering work, e.g. new feature implementation.</span><strong>Medium</strong>：我大部分日常开发工作，比如实现新功能。</li>
<li><span class="yn-en" lang="en"><strong>High</strong>: for work where verification is important or there are edge cases, e.g. fixing a bug in a brownfield codebase.</span><strong>High</strong>：验证很重要或者有边界情况的活儿，比如在一个老代码库里修 bug。</li>
<li><span class="yn-en" lang="en"><strong>Max</strong>: When I want Claude to operate fully autonomously to solve difficult problems, e.g. end to end building and verification of an app, finding security vulnerabilities in critical software.</span><strong>Max</strong>：我想让 Claude 完全自主地去解决难题的时候，比如从头到尾构建并验证一个应用，在关键软件里找安全漏洞。</li>
</ul>
<div class="yn-en" lang="en">
<p>Try varying effort for Opus 5.5 and Fable 5.1 based on your task or even mid-conversation by using <code>/effort</code> in Claude Code and let me know if this matches your intuition.</p>
</div>
<p>在 Claude Code 里用 <code>/effort</code>，按任务给 Opus 5.5 和 Fable 5.1 换换推理强度试试，对话进行到一半也能换。看看这些结论跟你的直觉对不对得上，告诉我。</p>
<div class="yn-en" lang="en">
<p><em>¹ A note on the numbers: these come from our own internal runs, 5 attempts per task, with our production safety interventions off for Fable 5.1; in Claude products, Fable 5.1’s safeguards hand some security requests to Opus. The security tasks also ran without internet access, so the per-task counts here won’t line up with the public leaderboard or the launch post. The worked examples come from individual runs, some at intermediate effort settings.</em></p>
</div>
<p><em>¹ 关于这些数字：它们来自我们内部的运行，每道题 5 次尝试，Fable 5.1 关掉了生产环境的安全干预；在 Claude 的产品里，Fable 5.1 的安全防护会把部分安全类请求转给 Opus。安全类题目也是在没有网络的情况下跑的，所以这里每道题的数字和公开排行榜、发布文章里的对不上。文中的具体例子来自单次运行，其中一些用的是中间档位的推理强度。</em></p>
]]></content:encoded>
</item>
<item>
<title>构建高效的 Agent 自动化</title>
<link>https://nyann.cc/posts/%E6%9E%84%E5%BB%BA%E9%AB%98%E6%95%88%E7%9A%84%20Agent%20%E8%87%AA%E5%8A%A8%E5%8C%96</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E6%9E%84%E5%BB%BA%E9%AB%98%E6%95%88%E7%9A%84%20Agent%20%E8%87%AA%E5%8A%A8%E5%8C%96</guid>
<pubDate>Wed, 28 Oct 2026 00:00:00 GMT</pubDate>
<description>用 Claude Managed Agents 搭一个按计划运行的每日简报 agent：读 Slack 和 GitHub、记住上次读到哪、确认发出去了才记账。附参考实现，以及几种常见的翻车方式。</description>
<category>翻译</category>
<category>AI</category>
<category>Claude</category>
<category>Agent</category>
<content:encoded><![CDATA[<h1 id="构建高效的-agent-自动化" tabindex="-1">构建高效的 Agent 自动化 <a class="header-anchor" href="#构建高效的-agent-自动化" aria-label="本节链接：构建高效的 Agent 自动化">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>As AI accelerates our work, it's getting harder to keep up. At Anthropic, <a href="https://claude.com/resources/articles/how-an-anthropic-japan-business-development-representative-runs-his-day" target="_blank" rel="noreferrer">simple agent automations</a> are frequently used to help. They often <a href="https://claude.com/resources/articles/whats-new-in-claude-managed-agents" target="_blank" rel="noreferrer">run on a schedule</a>, gather context in the background, and proactively tell us what we need to know. But it’s difficult to build effective agent automations: they can lose access to a source without anyone noticing or fail to follow our preferences.</p>
</div>
<p>AI 让工作越跑越快，人反而越来越跟不上。在 Anthropic，我们经常拿<a href="https://claude.com/resources/articles/how-an-anthropic-japan-business-development-representative-runs-his-day" target="_blank" rel="noreferrer">简单的 agent 自动化</a>来帮忙。它们通常<a href="https://claude.com/resources/articles/whats-new-in-claude-managed-agents" target="_blank" rel="noreferrer">按计划运行</a>，在后台收集上下文，主动告诉我们该知道的事。可要把 agent 自动化做好并不容易：它可能悄悄丢了某个信息源的访问权限却没人发现，也可能不照我们的偏好来。</p>
<div class="yn-en" lang="en">
<p>Using <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer">Claude Managed Agents</a> (beta), we built a reference implementation that reads custom sources (e.g., Slack and GitHub repos) on a schedule, tracks what changed since the last run, and posts what you need to know (e.g., to Slack). In this article, we walk through each step, share a reference implementation, and provide a command to run in Claude Code that configures the agent for you.</p>
</div>
<p>我们用 <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer">Claude Managed Agents</a>（beta）做了一个参考实现：按计划读取自定义的信息源（比如 Slack 和 GitHub 仓库），记下从上次运行到现在有什么变化，再把你需要知道的内容发出去（比如发到 Slack）。这篇文章会一步步讲清楚，附上参考实现，还给一条能在 Claude Code 里跑的命令，替你把 agent 配好。</p>
<h2 id="get-the-code拿到代码" tabindex="-1"><span class="yn-en ignore-header" lang="en">Get the code</span>拿到代码 <a class="header-anchor" href="#get-the-code拿到代码" aria-label="本节链接：拿到代码">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The reference implementation is <a href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/daily-brief" target="_blank" rel="noreferrer">here</a>. For an interactive walkthrough, run the command below in Claude Code. The <code>claude-api</code> skill can help set up the agent following the guidance in this article:</p>
</div>
<p>参考实现在<a href="https://github.com/anthropics/claude-quickstarts/tree/main/managed-agents/daily-brief" target="_blank" rel="noreferrer">这里</a>。想要交互式的引导，就在 Claude Code 里跑下面这条命令。<code>claude-api</code> skill 会照这篇文章的指引帮你把 agent 搭起来：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>For this reference implementation, you need a Slack app (<a href="https://api.slack.com/apps?new_app=1&amp;manifest_yaml=display_information%3A%0A%20%20name%3A%20Daily%20brief%0A%20%20description%3A%20Posts%20one%20short%20brief%20each%20weekday%20morning.%0Afeatures%3A%0A%20%20bot_user%3A%0A%20%20%20%20display_name%3A%20Daily%20brief%0A%20%20%20%20always_online%3A%20false%0A%20%20app_home%3A%0A%20%20%20%20home_tab_enabled%3A%20false%0A%20%20%20%20messages_tab_enabled%3A%20true%0A%20%20%20%20messages_tab_read_only_enabled%3A%20true%0Aoauth_config%3A%0A%20%20scopes%3A%0A%20%20%20%20bot%3A%0A%20%20%20%20%20%20-%20channels%3Ahistory%0A%20%20%20%20%20%20-%20chat%3Awrite%0Asettings%3A%0A%20%20org_deploy_enabled%3A%20false%0A%20%20socket_mode_enabled%3A%20false%0A%20%20token_rotation_enabled%3A%20false%0A" target="_blank" rel="noreferrer">create it from the manifest</a>) and a <a href="https://github.com/settings/personal-access-tokens/new" target="_blank" rel="noreferrer">GitHub token</a>. The provided files (shown below) are configuration for Claude API resources, including the agent, its environment, memory stores, vault, and deployment.</p>
</div>
<p>跑这个参考实现，你需要一个 Slack 应用（<a href="https://api.slack.com/apps?new_app=1&amp;manifest_yaml=display_information%3A%0A%20%20name%3A%20Daily%20brief%0A%20%20description%3A%20Posts%20one%20short%20brief%20each%20weekday%20morning.%0Afeatures%3A%0A%20%20bot_user%3A%0A%20%20%20%20display_name%3A%20Daily%20brief%0A%20%20%20%20always_online%3A%20false%0A%20%20app_home%3A%0A%20%20%20%20home_tab_enabled%3A%20false%0A%20%20%20%20messages_tab_enabled%3A%20true%0A%20%20%20%20messages_tab_read_only_enabled%3A%20true%0Aoauth_config%3A%0A%20%20scopes%3A%0A%20%20%20%20bot%3A%0A%20%20%20%20%20%20-%20channels%3Ahistory%0A%20%20%20%20%20%20-%20chat%3Awrite%0Asettings%3A%0A%20%20org_deploy_enabled%3A%20false%0A%20%20socket_mode_enabled%3A%20false%0A%20%20token_rotation_enabled%3A%20false%0A" target="_blank" rel="noreferrer">用 manifest 创建</a>）和一个 <a href="https://github.com/settings/personal-access-tokens/new" target="_blank" rel="noreferrer">GitHub token</a>。仓库里给的文件（见下）是 Claude API 资源的配置，包括 agent、它的运行环境、记忆库、保管库和部署。</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>daily-brief/</span></span>
<span class="line"><span>├── agent.md                        模型、工具、指令</span></span>
<span class="line"><span>├── deployment.md                   计划、时区、预算、输入消息</span></span>
<span class="line"><span>├── environment.yaml                网络白名单</span></span>
<span class="line"><span>├── memory_store_preferences.yaml   用户偏好</span></span>
<span class="line"><span>├── memory_store_state.yaml         agent 的书签、台账、笔记和运行记录</span></span>
<span class="line"><span>├── vault.yaml                      存放凭据的保管库</span></span>
<span class="line"><span>├── claude-lock.json                资源 ID，由 ant apply 写入</span></span>
<span class="line"><span>└── slack/manifest.yaml             一个机器人应用</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p><a href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply" target="_blank" rel="noreferrer"><code>ant apply</code></a>, a command in the ant CLI, reads these files, creates the resources in your Claude API workspace (where the platform stores and runs them), and records the IDs in <code>claude-lock.json</code>.</p>
</div>
<p><a href="https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply" target="_blank" rel="noreferrer"><code>ant apply</code></a> 是 ant CLI 里的一条命令。它读这些文件，在你的 Claude API 工作区（平台存放和运行这些资源的地方）里把资源建出来，再把 ID 记进 <code>claude-lock.json</code>。</p>
<div class="yn-en" lang="en">
<p>We'll use this command in the sections below. Once configured, the automation runs on a schedule on Anthropic's infrastructure, so <a href="https://claude.dev/blog/claude-code-in-the-cloud/" target="_blank" rel="noreferrer">nothing has to stay running on your machine</a>.</p>
</div>
<p>后面几节都会用到这条命令。配好以后，这个自动化就在 Anthropic 的基础设施上按计划运行，所以<a href="https://claude.dev/blog/claude-code-in-the-cloud/" target="_blank" rel="noreferrer">你的机器上什么都不用一直开着</a>。</p>
<h2 id="overview概览" tabindex="-1"><span class="yn-en ignore-header" lang="en">Overview</span>概览 <a class="header-anchor" href="#overview概览" aria-label="本节链接：概览">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The agent we’ll build has six components, covered in this order:</p>
</div>
<p>我们要搭的 agent 有六个部件，按下面的顺序讲：</p>
<ul>
<li><span class="yn-en" lang="en">Sources - A named list of places to read</span>信息源：一份清单，逐个写明要读哪些地方</li>
<li><span class="yn-en" lang="en">Destination - One place the agent may write</span>目的地：agent 唯一可以写的地方</li>
<li><span class="yn-en" lang="en">Agent - The model, tools, and run steps in agent.md</span>Agent：agent.md 里的模型、工具和运行步骤</li>
<li><span class="yn-en" lang="en">Schedule - A cron schedule</span>计划：一个 cron 计划</li>
<li><span class="yn-en" lang="en">Memory - Your preferences and the agent's own memory</span>记忆：你的偏好，加上 agent 自己的记忆</li>
<li><span class="yn-en" lang="en">Guardrails - Read-only access wherever the agent only reads, and a spending cap per run</span>护栏：凡是只读的地方都给只读权限，每次运行设一个花费上限</li>
</ul>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/01.webp" alt="agent 的架构：计划唤醒 agent，agent 从信息源读取内容，把简报发到唯一的目的地交给读者。记忆里存着 agent 的状态和读者的偏好，护栏围在 agent 四周。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Architecture of the agent: a schedule wakes the agent, which reads from its sources and posts a brief to one destination for the reader. Memory holds the agent's state and the reader's preferences, and guardrails surround the agent.</p>
</div>
<p>agent 的架构：计划唤醒 agent，agent 从信息源读取内容，把简报发到唯一的目的地交给读者。记忆里存着 agent 的状态和读者的偏好，护栏围在 agent 四周。</p>
<h2 id="sources信息源" tabindex="-1"><span class="yn-en ignore-header" lang="en">Sources</span>信息源 <a class="header-anchor" href="#sources信息源" aria-label="本节链接：信息源">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The agent reads two default sources: Slack channels and GitHub pull requests. The channels and repos are listed in your <code>preferences</code> file. The template can be extended to use other sources.</p>
</div>
<p>agent 默认读两个信息源：Slack 频道和 GitHub 的 pull request。具体读哪些频道和仓库，列在你的 <code>preferences</code> 文件里。这个模板也可以扩展到别的信息源。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/02.webp" alt="架构图，信息源部分高亮。信息源是只读的，通过 MCP 或 HTTPS 访问，凭据来自保管库，读到的内容交给 agent。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with Sources highlighted. The sources are read-only, reached through MCP or HTTPS with credentials from a vault, and feed the agent.</p>
</div>
<p>架构图，信息源部分高亮。信息源是只读的，通过 MCP 或 HTTPS 访问，凭据来自保管库，读到的内容交给 agent。</p>
<h3 id="give-the-agent-its-own-scoped-credentials给-agent-一套它自己的、限定范围的凭据" tabindex="-1"><span class="yn-en ignore-header" lang="en">Give the agent its own, scoped credentials</span>给 agent 一套它自己的、限定范围的凭据 <a class="header-anchor" href="#give-the-agent-its-own-scoped-credentials给-agent-一套它自己的、限定范围的凭据" aria-label="本节链接：给 agent 一套它自己的、限定范围的凭据">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>With <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer">Managed Agents</a>, credentials live in <a href="https://platform.claude.com/docs/en/managed-agents/vaults" target="_blank" rel="noreferrer">vaults</a>. The agent can reference these credentials but the real values stay in the vault, <a href="https://claude.com/resources/articles/giving-companies-more-control-over-their-ai-agents-with-nvidia" target="_blank" rel="noreferrer">outside the sandbox</a> where Claude's code runs (see <a href="https://www.anthropic.com/engineering/managed-agents" target="_blank" rel="noreferrer">here</a> and <a href="https://x.com/katelyn_lesse/status/2099315903884415400" target="_blank" rel="noreferrer">here</a>):</p>
</div>
<p>在 <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer">Managed Agents</a> 里，凭据放在<a href="https://platform.claude.com/docs/en/managed-agents/vaults" target="_blank" rel="noreferrer">保管库（vault）</a>中。agent 可以引用这些凭据，但真实的值一直留在保管库里，在 Claude 跑代码的<a href="https://claude.com/resources/articles/giving-companies-more-control-over-their-ai-agents-with-nvidia" target="_blank" rel="noreferrer">沙箱（sandbox）之外</a>（详见<a href="https://www.anthropic.com/engineering/managed-agents" target="_blank" rel="noreferrer">这里</a>和<a href="https://x.com/katelyn_lesse/status/2099315903884415400" target="_blank" rel="noreferrer">这里</a>）：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>MCP servers (GitHub).</strong> The agent calls MCP tools through a proxy that runs outside the sandbox. The proxy finds the vault credential whose URL matches the server’s.</span><strong>MCP 服务器（GitHub）。</strong> agent 通过一个跑在沙箱外面的代理调用 MCP 工具。代理去保管库里找 URL 和这台服务器对得上的那条凭据。</li>
<li><span class="yn-en" lang="en"><strong>The shell (Slack).</strong> The agent calls the Slack API with curl using the bash tool inside the sandbox. The sandbox only holds an opaque placeholder, <code>$SLACK_BOT_TOKEN</code>. As the request leaves the sandbox, the platform swaps in the real token for hosts you allow.</span><strong>Shell（Slack）。</strong> agent 在沙箱里用 bash 工具跑 curl 调 Slack API。沙箱里只有一个看不出内容的占位符 <code>$SLACK_BOT_TOKEN</code>。请求离开沙箱时，只要目标是你允许的主机，平台就把真 token 换进去。</li>
</ul>
<div class="yn-en" lang="en">
<p>Create the vault using the <code>ant</code> CLI and the template file in the repo:</p>
</div>
<p>用 <code>ant</code> CLI 和仓库里的模板文件创建保管库：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>ant apply vault.yaml</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This creates the vault in your Claude API workspace, where the platform stores it, and records its ID in <code>claude-lock.json</code>. Then add each credential to the vault with the <a href="https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript" target="_blank" rel="noreferrer">TypeScript SDK</a>. Here is an example showing addition of the Slack credential:</p>
</div>
<p>这会在你的 Claude API 工作区里建好保管库（平台把它存在那儿），再把它的 ID 记进 <code>claude-lock.json</code>。然后用 <a href="https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript" target="_blank" rel="noreferrer">TypeScript SDK</a> 把凭据一条条加进去。下面是加 Slack 凭据的例子：</p>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">const </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">vaultId</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> process</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">env</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">VAULT_ID</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">!</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"> // 保管库的 ID，从 claude-lock.json 里取</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">await</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> client</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">beta</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">vaults</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">credentials</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">create</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">vaultId</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">  display_name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">SLACK_BOT_TOKEN</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">  auth</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: {</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">    type</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">environment_variable</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">    secret_name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">SLACK_BOT_TOKEN</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">    secret_value</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">process</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">env</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">SLACK_BOT_TOKEN</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">!</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">    networking</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: { </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">limited</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">, </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">allowed_hosts</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: [</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">slack.com</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">] },</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">    injection_location</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: { </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">header</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">true</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  },</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">});</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>After creating the vault and adding each credential, attach the vault to the deployment. Copy the vault ID from <code>claude-lock.json</code> into <code>vault_ids</code> in the deployment file, <code>deployment.md</code>.</p>
</div>
<p>保管库建好、凭据都加进去之后，把保管库挂到部署上：从 <code>claude-lock.json</code> 里把保管库 ID 抄到部署文件 <code>deployment.md</code> 的 <code>vault_ids</code> 里。</p>
<h3 id="read-from-where-you-left-off从上次停下的地方接着读" tabindex="-1"><span class="yn-en ignore-header" lang="en">Read from where you left off</span>从上次停下的地方接着读 <a class="header-anchor" href="#read-from-where-you-left-off从上次停下的地方接着读" aria-label="本节链接：从上次停下的地方接着读">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A common mistake is asking the agent to read a fixed window like &quot; <em>the last 24 hours</em>.&quot; A late run leaves a gap and an early run repeats items. Instead, give the agent a bookmark per source. At the end of each run, the agent writes the timestamp of the newest item it read from each source to one file, <code>bookmarks.json</code>, with an entry per source: <code>&quot;slack&quot;: &quot;2026-09-14T13:02:11Z&quot;</code>.</p>
</div>
<p>一个常见的错误是让 agent 读固定的时间窗口，比如「<em>过去 24 小时</em>」。哪次跑晚了就会漏掉一段，跑早了又会重复。更好的办法是每个信息源给 agent 一个书签。每次运行结束时，agent 把从每个信息源读到的最新一条的时间戳写进同一个文件 <code>bookmarks.json</code>，一个信息源一条：<code>&quot;slack&quot;: &quot;2026-09-14T13:02:11Z&quot;</code>。</p>
<div class="yn-en" lang="en">
<p>The next run starts from those bookmarks, so its window stretches or shrinks to cover everything since the last run. The bookmarks live in the <a href="https://platform.claude.com/docs/en/managed-agents/memory" target="_blank" rel="noreferrer">memory store</a> called <code>state</code>: a folder of text files that the platform mounts into every run's sandbox under <code>/mnt/memory/</code> and keeps between runs. The agent reads and writes it with its ordinary file tools, and the instructions in <code>agent.md</code> tell it how.</p>
</div>
<p>下一次运行就从这些书签开始，窗口会自己拉长或缩短，正好覆盖上次以来的全部内容。书签放在一个叫 <code>state</code> 的<a href="https://platform.claude.com/docs/en/managed-agents/memory" target="_blank" rel="noreferrer">记忆库（memory store）</a>里。它是一个装着文本文件的文件夹，平台把它挂载到每次运行的沙箱里的 <code>/mnt/memory/</code> 下，并在两次运行之间保留。agent 用普通的文件工具读写它，怎么读写由 <code>agent.md</code> 里的指令告诉它。</p>
<h3 id="don-t-mistake-a-failed-read-for-a-quiet-day别把读取失败当成今天没事" tabindex="-1"><span class="yn-en ignore-header" lang="en">Don't mistake a failed read for a quiet day</span>别把读取失败当成今天没事 <a class="header-anchor" href="#don-t-mistake-a-failed-read-for-a-quiet-day别把读取失败当成今天没事" aria-label="本节链接：别把读取失败当成今天没事">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>If an MCP server is down or its token has expired, the run still starts, just without that server's tools. The <a href="https://claude.com/resources/articles/agent-observability-on-the-claude-platform" target="_blank" rel="noreferrer">session logs an error</a>, but the agent sees nothing from that source and reports &quot;nothing new.&quot;</p>
</div>
<p>如果某台 MCP 服务器挂了，或者它的 token 过期了，运行照样会开始，只是少了这台服务器的工具。<a href="https://claude.com/resources/articles/agent-observability-on-the-claude-platform" target="_blank" rel="noreferrer">会话里会记一条错误</a>，可 agent 从这个信息源什么也看不到，于是报告「没有新内容」。</p>
<div class="yn-en" lang="en">
<p>Three rules in <code>agent.md</code> help fix this. When a source fails, the agent will: keep the source’s bookmark where it is, write the brief from the other sources, and end the brief with one line naming what it couldn't read (&quot;pull requests unavailable this run&quot;), so the reader is made aware.</p>
</div>
<p><code>agent.md</code> 里有三条规则来补这个洞。某个信息源读失败时，agent 会：让这个信息源的书签原地不动；用其他信息源把简报写出来；在简报末尾加一行，说明哪里没读到（「本次运行无法读取 pull request」），让读者知道。</p>
<h2 id="destination目的地" tabindex="-1"><span class="yn-en ignore-header" lang="en">Destination</span>目的地 <a class="header-anchor" href="#destination目的地" aria-label="本节链接：目的地">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Our template posts to one Slack channel, with a dated post each time it runs.</p>
</div>
<p>我们的模板只往一个 Slack 频道发消息，每次运行发一条带日期的。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/03.webp" alt="架构图，目的地部分高亮。agent 先检查今天的简报还没发过，再发到唯一的目的地，由它把简报送到读者手里。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with Destination highlighted. After a check that today's brief isn't already posted, the agent posts to one destination, which delivers the brief to the reader.</p>
</div>
<p>架构图，目的地部分高亮。agent 先检查今天的简报还没发过，再发到唯一的目的地，由它把简报送到读者手里。</p>
<div class="yn-en" lang="en">
<p>The agent posts to Slack using the bash tool in its sandbox, using the same bot token it reads with.</p>
</div>
<p>agent 在沙箱里用 bash 工具往 Slack 发消息，用的就是它读消息时那个机器人 token。</p>
<div class="yn-en" lang="en">
<p>Nothing has to approve the post. The agent sends it with a bash command, and the built-in bash tool runs without asking for approval by default. <code>slack.com</code> is also on the allowlist of the agent's <a href="https://platform.claude.com/docs/en/managed-agents/environments" target="_blank" rel="noreferrer">environment</a>, the sandbox it runs in. The post is one request:</p>
</div>
<p>发消息不需要谁批准。agent 用一条 bash 命令发出去，内置的 bash 工具默认不请求批准就会执行。<code>slack.com</code> 也在 agent 的<a href="https://platform.claude.com/docs/en/managed-agents/environments" target="_blank" rel="noreferrer">环境（environment）</a>白名单（allowlist）上，环境就是 agent 运行所在的沙箱。发消息只要一个请求：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>curl -s https://slack.com/api/chat.postMessage \</span></span>
<span class="line"><span>  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \</span></span>
<span class="line"><span>  -H "Content-Type: application/json; charset=utf-8" \</span></span>
<span class="line"><span>  -d '{"channel": "C0123456789", "text": "Daily brief, Tue Sep 15 ..."}'</span></span></code></pre>
</div><h3 id="confirm-the-post-landed-before-recording-it确认消息发到了-再记下来" tabindex="-1"><span class="yn-en ignore-header" lang="en">Confirm the post landed before recording it</span>确认消息发到了，再记下来 <a class="header-anchor" href="#confirm-the-post-landed-before-recording-it确认消息发到了-再记下来" aria-label="本节链接：确认消息发到了，再记下来">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Once a post is confirmed, the agent updates its ledger of reported items and its bookmarks. If those records don't match what was actually posted, two things can go wrong. If the agent records a post that never landed, the bookmarks move on and those items are never reported. If it posts again because it isn't sure the first post landed, readers get the same brief twice.</p>
</div>
<p>消息确认发出去之后，agent 会更新它的已报告条目台账和书签。要是这些记录和实际发出去的对不上，会出两种问题。agent 记下了一条其实没发到的消息，书签就往前走了，那些条目再也不会被报告。它拿不准第一条发到没有又发一遍，读者就会收到两份一样的简报。</p>
<div class="yn-en" lang="en">
<p>Three rules in <code>agent.md</code> prevent this. First, the agent looks for today's title in the channel's recent messages and doesn't post if the edition is already there. Second, the post counts as sent only if Slack returns <code>&quot;ok&quot;: true</code> and a message ts. Third, the agent updates the ledger and bookmarks only after that confirmation. If the result is unclear, it marks the run &quot;maybe posted&quot; and changes nothing else, so nothing is lost.</p>
</div>
<p><code>agent.md</code> 里有三条规则防这个。第一，agent 先在频道最近的消息里找今天的标题，今天这期已经在了就不发。第二，只有 Slack 返回 <code>&quot;ok&quot;: true</code> 和消息的 ts，才算发出去了。第三，拿到这个确认之后，agent 才更新台账和书签。结果说不清的时候，它把这次运行标成「可能已发送」，别的什么都不改，这样就不会丢东西。</p>
<div class="yn-en" lang="en">
<p>The agent keeps a run record in its memory store (<code>runs/&lt;date&gt;.md</code>). It marks the run &quot;posting&quot; before the post, then &quot;posted&quot; with the message ID, or &quot;maybe posted.&quot;</p>
</div>
<p>agent 在记忆库里为每次运行留一份记录（<code>runs/&lt;date&gt;.md</code>）。发之前标成「发送中」，发完标成「已发送」并附上消息 ID，或者标成「可能已发送」。</p>
<h2 id="agentagent" tabindex="-1"><span class="yn-en ignore-header" lang="en">Agent</span>Agent <a class="header-anchor" href="#agentagent" aria-label="本节链接：Agent">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>In Claude Managed Agents, an <a href="https://platform.claude.com/docs/en/managed-agents/agent-setup" target="_blank" rel="noreferrer">agent</a> is a versioned configuration: a model, a system prompt, and tools. Each run follows its run steps and stops.</p>
</div>
<p>在 Claude Managed Agents 里，<a href="https://platform.claude.com/docs/en/managed-agents/agent-setup" target="_blank" rel="noreferrer">agent</a> 是一份带版本的配置：一个模型、一段系统提示词、一组工具。每次运行按它的运行步骤走完就停。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/04.webp" alt="架构图，Agent 部分高亮：一个模型，加上一段承载运行循环和判断规则的提示词。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with the Agent highlighted: a model plus a prompt that holds the run loop and the judgement rules.</p>
</div>
<p>架构图，Agent 部分高亮：一个模型，加上一段承载运行循环和判断规则的提示词。</p>
<div class="yn-en" lang="en">
<p>In our reference implementation, the agent configuration is <code>agent.md</code>:</p>
</div>
<p>在我们的参考实现里，agent 的配置就是 <code>agent.md</code>：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>---</span></span>
<span class="line"><span>name: Daily brief</span></span>
<span class="line"><span>model: claude-sonnet-5-5</span></span>
<span class="line"><span>mcp_servers:</span></span>
<span class="line"><span>  - type: url</span></span>
<span class="line"><span>    name: github</span></span>
<span class="line"><span>    url: https://api.githubcopilot.com/mcp/</span></span>
<span class="line"><span>tools:</span></span>
<span class="line"><span>  - type: agent_toolset_20260401</span></span>
<span class="line"><span>    configs:</span></span>
<span class="line"><span>      - name: web_search</span></span>
<span class="line"><span>        enabled: false</span></span>
<span class="line"><span>      - name: web_fetch</span></span>
<span class="line"><span>        enabled: false</span></span>
<span class="line"><span>  - type: mcp_toolset</span></span>
<span class="line"><span>    mcp_server_name: github</span></span>
<span class="line"><span>    default_config:</span></span>
<span class="line"><span>      permission_policy:</span></span>
<span class="line"><span>        type: always_allow</span></span>
<span class="line"><span>---</span></span>
<span class="line"><span></span></span>
<span class="line"><span>[Eight numbered run steps; the full text is in agent.md in the repo.]</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>The frontmatter supplies the agent name, model, tools, and MCP servers. The body provides the agent instructions. MCP tools ask for approval by default and nobody is there to give it, so the GitHub toolset is set to <code>always_allow</code> and the GitHub token is <code>read-only</code>.</p>
</div>
<p>frontmatter 给出 agent 的名字、模型、工具和 MCP 服务器，正文是给 agent 的指令。MCP 工具默认要请求批准，可没人在那儿批，所以 GitHub 工具集设成了 <code>always_allow</code>，相应地 GitHub token 是 <code>read-only</code> 的。</p>
<h3 id="keep-the-brief-short简报要短" tabindex="-1"><span class="yn-en ignore-header" lang="en">Keep the brief short</span>简报要短 <a class="header-anchor" href="#keep-the-brief-short简报要短" aria-label="本节链接：简报要短">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p><code>agent.md</code> steers Claude toward brevity:</p>
</div>
<p><code>agent.md</code> 引导 Claude 往简短里写：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>4. Decide. An item earns a line when the reader would act on it today, or it changes a decision they are about to make. When unsure, leave it out. Most days that is a few items, sometimes none. A count ("12 open reviews") is not an item; link the ones that are blocked. An item already in the ledger and still open is carried as one marked line ("still waiting, day 3"), not re-reported; a closed item is dropped without comment. Do not bring back a topic the preferences file has retired.</span></span></code></pre>
</div><h3 id="re-check-anything-still-open-right-before-posting发之前-把还没了结的再查一遍" tabindex="-1"><span class="yn-en ignore-header" lang="en">Re-check anything still open right before posting</span>发之前，把还没了结的再查一遍 <a class="header-anchor" href="#re-check-anything-still-open-right-before-posting发之前-把还没了结的再查一遍" aria-label="本节链接：发之前，把还没了结的再查一遍">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Items can change between when the agent reads sources and when it posts. Just before posting, <code>agent.md</code> instructs the agent to re-check the live status of each item:</p>
</div>
<p>从 agent 读信息源到它发消息，中间这段时间条目可能已经变了。<code>agent.md</code> 要求 agent 在发之前，逐条重新查一下实时状态：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>5. Verify. The world moved while you read. For every item you will report, re-check its live source just before posting: resolved since you read it, drop it; still open but changed, fix the line; cannot confirm, drop it and list it in the run record's cuts. One stale "still waiting on you" costs more trust than ten missing items, so never hedge an item's status: assert it or drop it. Every link is copied from the source's own link field (a pull request's html_url, a Slack permalink), never assembled by hand.</span></span></code></pre>
</div><h2 id="schedule计划" tabindex="-1"><span class="yn-en ignore-header" lang="en">Schedule</span>计划 <a class="header-anchor" href="#schedule计划" aria-label="本节链接：计划">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>With Claude Managed Agents, the agent is only a configuration file; a <a href="https://platform.claude.com/docs/en/managed-agents/scheduled-deployments" target="_blank" rel="noreferrer">deployment</a> runs it. The deployment names the agent, environment, and the first message of each run. It also holds the schedule, vault, memory stores, and budget. Each time the schedule fires, the platform starts a fresh agent <a href="https://platform.claude.com/docs/en/managed-agents/sessions" target="_blank" rel="noreferrer">session</a>.</p>
</div>
<p>在 Claude Managed Agents 里，agent 只是一份配置文件，真正跑它的是<a href="https://platform.claude.com/docs/en/managed-agents/scheduled-deployments" target="_blank" rel="noreferrer">部署（deployment）</a>。部署指定用哪个 agent、哪个环境，以及每次运行的第一条消息，还管着计划、保管库、记忆库和预算。计划每触发一次，平台就新开一个 agent <a href="https://platform.claude.com/docs/en/managed-agents/sessions" target="_blank" rel="noreferrer">会话（session）</a>。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/05.webp" alt="架构图，计划部分高亮：一个按计划运行的部署，每次运行时把 agent 唤醒。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with Schedule highlighted: a scheduled deployment that wakes the agent for each run.</p>
</div>
<p>架构图，计划部分高亮：一个按计划运行的部署，每次运行时把 agent 唤醒。</p>
<div class="yn-en" lang="en">
<p>In our template, the deployment is captured in <code>deployment.md</code>, with the first message as its body:</p>
</div>
<p>在我们的模板里，部署写在 <code>deployment.md</code> 里，正文就是第一条消息：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>---</span></span>
<span class="line"><span>name: Daily brief</span></span>
<span class="line"><span>agent: ./agent.md</span></span>
<span class="line"><span>environment_id: ./environment.yaml</span></span>
<span class="line"><span>schedule:</span></span>
<span class="line"><span>  type: cron</span></span>
<span class="line"><span>  expression: "32 7 * * 1-5"</span></span>
<span class="line"><span>  timezone: America/New_York</span></span>
<span class="line"><span>vault_ids: [vlt_...]   # 在「信息源」那一节里创建的保管库</span></span>
<span class="line"><span>resources:</span></span>
<span class="line"><span>  - path: ./memory_store_preferences.yaml</span></span>
<span class="line"><span>    access: read_only</span></span>
<span class="line"><span>    instructions: The reader's preferences. Re-read them every run. Never write here.</span></span>
<span class="line"><span>  - path: ./memory_store_state.yaml</span></span>
<span class="line"><span>    access: read_write</span></span>
<span class="line"><span>    instructions: Your state. Bookmarks, ledger, notes, proposals, and run records.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>---</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Write today's brief.</span></span>
<span class="line"><span>The reader's time zone is America/New_York. Work out every date in that zone.</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Follow your run steps in order. Today's edition is titled "Daily brief, &#x3C;weekday> &#x3C;month> &#x3C;day>".</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This creates the deployment with the agent, environment and memory stores it names by path.</p>
</div>
<p>下面这条命令会创建部署，连同它按路径指定的 agent、环境和记忆库。</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>ant apply deployment.md</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>To test it without waiting for the schedule, start a run by hand with <code>ant beta:deployments run --deployment-id &lt;id&gt;</code>, using the ID from <code>claude-lock.json</code>.</p>
</div>
<p>想测试又不想等计划触发，可以用 <code>ant beta:deployments run --deployment-id &lt;id&gt;</code> 手动跑一次，ID 从 <code>claude-lock.json</code> 里取。</p>
<h3 id="compute-dates-in-your-time-zone按你的时区算日期" tabindex="-1"><span class="yn-en ignore-header" lang="en">Compute dates in your time zone</span>按你的时区算日期 <a class="header-anchor" href="#compute-dates-in-your-time-zone按你的时区算日期" aria-label="本节链接：按你的时区算日期">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A common bug is the agent calling this morning &quot;yesterday&quot; because it computes dates in the server's time zone. In <code>deployment.md</code>, the <code>timezone</code> field sets when the run fires and the second line of the body tells the agent which zone to use for dates.</p>
</div>
<p>一个常见的 bug 是 agent 把今天早上说成「昨天」，因为它按服务器的时区算日期。在 <code>deployment.md</code> 里，<code>timezone</code> 字段决定运行什么时候触发，正文第二行告诉 agent 算日期用哪个时区。</p>
<h2 id="memory记忆" tabindex="-1"><span class="yn-en ignore-header" lang="en">Memory</span>记忆 <a class="header-anchor" href="#memory记忆" aria-label="本节链接：记忆">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Each run starts in a fresh sandbox with no memory of the last one. Without memory, feedback doesn't stick. However, stale memory can confuse the agent: it reports an item as still waiting after it was resolved, or drops one that's still open because it was &quot;already reported.&quot;</p>
</div>
<p>每次运行都从一个全新的沙箱开始，不记得上一次的事。没有记忆，反馈就留不住。可过期的记忆也会把 agent 搞糊涂：一件事已经解决了，它还报「仍在等待」；一件事还没了结，它却因为「已经报过了」就不提了。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/06.webp" alt="架构图，记忆部分高亮。状态由 agent 读写；偏好由读者来写，agent 只读。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with Memory highlighted. State is what the agent reads and writes, and Preferences is what the reader writes and the agent only reads.</p>
</div>
<p>架构图，记忆部分高亮。状态由 agent 读写；偏好由读者来写，agent 只读。</p>
<div class="yn-en" lang="en">
<p>Our template keeps two <a href="https://platform.claude.com/docs/en/managed-agents/memory" target="_blank" rel="noreferrer">memory stores</a>, the folders mounted under /mnt/memory/ (see Sources):</p>
</div>
<p>我们的模板有两个<a href="https://platform.claude.com/docs/en/managed-agents/memory" target="_blank" rel="noreferrer">记忆库</a>，也就是挂载在 /mnt/memory/ 下的那两个文件夹（见「信息源」一节）：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>preferences</strong> (yours, read-only to the agent): which channels and repos to read, what to leave out, the length cap, the destination, and when to stop.</span><strong>preferences</strong>（归你，对 agent 只读）：读哪些频道和仓库、哪些内容不要、篇幅上限、目的地，以及什么时候停。</li>
<li><span class="yn-en" lang="en"><strong>state</strong> (the agent's, read-write): the bookmarks, a ledger of what it reported, one record per run, changes it proposes to your preferences, and notes on how each source behaves (&quot;returns only the newest 50 items&quot;).</span><strong>state</strong>（归 agent，可读可写）：书签、已报告内容的台账、每次运行一份的记录、它对你的偏好提出的修改建议，以及关于各个信息源脾气的笔记（「只返回最新的 50 条」）。</li>
</ul>
<div class="yn-en" lang="en">
<p><code>ant apply deployment.md</code> creates the preferences store, but not the file in it. Before the first run, write your preferences.md there with the repo's <code>scripts/seed-preferences.sh</code>.</p>
</div>
<p><code>ant apply deployment.md</code> 会建好 preferences 这个记忆库，但不会建里面的文件。第一次运行之前，用仓库里的 <code>scripts/seed-preferences.sh</code> 把你的 preferences.md 写进去。</p>
<h3 id="re-read-your-preferences-at-the-start-of-every-run每次运行开始时都重读一遍偏好" tabindex="-1"><span class="yn-en ignore-header" lang="en">Re-read your preferences at the start of every run</span>每次运行开始时都重读一遍偏好 <a class="header-anchor" href="#re-read-your-preferences-at-the-start-of-every-run每次运行开始时都重读一遍偏好" aria-label="本节链接：每次运行开始时都重读一遍偏好">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A common problem occurs when a copy of the preferences is baked into the prompt, which keeps applying rules you've already changed. Have the agent read the file fresh every run. If it can't read the file, it should stop and say so instead of running on defaults.</p>
</div>
<p>一个常见的问题是把偏好抄一份写死在提示词里，结果你早改掉的规则它还在照用。让 agent 每次运行都现读这个文件。读不到的话，它应该停下来说明情况，而不是拿默认值接着跑。</p>
<h3 id="keep-a-ledger-of-what-you-ve-already-reported-and-report-the-change给已经报过的内容记一本台账-只报变化" tabindex="-1"><span class="yn-en ignore-header" lang="en">Keep a ledger of what you've already reported, and report the change</span>给已经报过的内容记一本台账，只报变化 <a class="header-anchor" href="#keep-a-ledger-of-what-you-ve-already-reported-and-report-the-change给已经报过的内容记一本台账-只报变化" aria-label="本节链接：给已经报过的内容记一本台账，只报变化">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The agent keeps a ledger, <code>ledger.md</code>, of every item it has reported, so the brief doesn't repeat itself. Each line records when the item was reported, where it came from, an ID that doesn't change (a Slack message timestamp or a pull request number), and its last known status:</p>
</div>
<p>agent 用一本台账（ledger）<code>ledger.md</code> 记下它报过的每一条，这样简报就不会翻来覆去说同样的事。每行记着这条是什么时候报的、从哪儿来的、一个不会变的 ID（Slack 消息的时间戳或 pull request 编号），以及它最后已知的状态：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>2026-09-09 slack:C0123456789 1788963600.000100 refund thread: customer waiting on a decision</span></span>
<span class="line"><span>2026-09-11 github 481 review blocked, day 2 (still waiting)</span></span>
<span class="line"><span>2026-09-11 slack:C0234567891 1789117333.000300 enterprise escalation: owner named, in progress</span></span></code></pre>
</div><h2 id="guardrails护栏" tabindex="-1"><span class="yn-en ignore-header" lang="en">Guardrails</span>护栏 <a class="header-anchor" href="#guardrails护栏" aria-label="本节链接：护栏">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Because our automation runs in the “background” on a schedule, we set limits on what the agent can do and what it can spend.</p>
</div>
<p>因为这个自动化是按计划在「后台」跑的，我们给 agent 能做什么、能花多少钱都设了限制。</p>
<p><img src="https://nyann.cc/posts/building-effective-agent-automations/07.webp" alt="架构图，护栏部分高亮：围在 agent 四周的一道边界，对轮数、时长和花费设了上限，还有一个有人盯着的心跳。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The architecture diagram with Guardrails highlighted: a boundary around the agent with caps on turns, time and spend, and a heartbeat that someone watches.</p>
</div>
<p>架构图，护栏部分高亮：围在 agent 四周的一道边界，对轮数、时长和花费设了上限，还有一个有人盯着的心跳。</p>
<h3 id="limits-on-what-it-can-do限制它能做什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">Limits on what it can do</span>限制它能做什么 <a class="header-anchor" href="#limits-on-what-it-can-do限制它能做什么" aria-label="本节链接：限制它能做什么">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The agent reads messages and issues that other people wrote, and that text can be interpreted as instructions. Limit what the agent could do if it followed them. In our example, the GitHub token and the <code>preferences</code> store are read-only, and the environment only reaches the hosts on its allowlist. A planted instruction can still change what the brief says, including through the notes the agent keeps between runs. It can't write to GitHub or edit your rules.</p>
</div>
<p>agent 读的是别人写的消息和 issue，这些文字可能被它当成指令。所以要限制住：就算它照着做了，能做的事也有限。在我们的例子里，GitHub token 和 <code>preferences</code> 记忆库都是只读的，环境也只能访问白名单上的主机。被人埋进去的指令仍然可以改变简报的内容，包括借 agent 在两次运行之间留的笔记来改。但它没法往 GitHub 写东西，也没法改你的规则。</p>
<div class="yn-en" lang="en">
<p>Slack is the exception: the same token posts, so invite the bot only where it needs to read or post.</p>
</div>
<p>Slack 是个例外：发消息用的也是同一个 token，所以只把机器人拉进它需要读或者需要发的频道。</p>
<h3 id="set-the-spending-cap-from-real-runs按真实运行的数据定花费上限" tabindex="-1"><span class="yn-en ignore-header" lang="en">Set the spending cap from real runs</span>按真实运行的数据定花费上限 <a class="header-anchor" href="#set-the-spending-cap-from-real-runs按真实运行的数据定花费上限" aria-label="本节链接：按真实运行的数据定花费上限">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A spending cap protects you from runaway costs. Start at three to five times the cost of a normal run, then tighten it as you see real numbers. A run that hits its cap pauses instead of failing, so a cap set too low looks like a brief that went quiet. The cap is the <a href="https://platform.claude.com/docs/en/managed-agents/budgets" target="_blank" rel="noreferrer"><code>budget</code></a> in <code>deployment.md</code>. Every run gets the full amount, and a run that reaches it pauses with a <code>budget_reached</code> stop reason:</p>
</div>
<p>花费上限能防止费用失控。先设成一次正常运行成本的三到五倍，看到真实数字之后再往下收。撞到上限的运行会暂停而不是报错，所以上限设得太低，看起来就像简报突然不说话了。上限就是 <code>deployment.md</code> 里的 <a href="https://platform.claude.com/docs/en/managed-agents/budgets" target="_blank" rel="noreferrer"><code>budget</code></a>。每次运行都有完整的额度，用到顶的那次会暂停，停止原因是 <code>budget_reached</code>：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>budget:</span></span>
<span class="line"><span>  type: limit</span></span>
<span class="line"><span>  max_list_cost:</span></span>
<span class="line"><span>    amount: "500" # 字符串，单位是美分："500" 就是 5.00 美元</span></span>
<span class="line"><span>    currency: USD</span></span></code></pre>
</div><h2 id="getting-started上手" tabindex="-1"><span class="yn-en ignore-header" lang="en">Getting started</span>上手 <a class="header-anchor" href="#getting-started上手" aria-label="本节链接：上手">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Our reference implementation comes down to six rules:</p>
</div>
<p>我们的参考实现归结起来是六条规则：</p>
<ul>
<li><span class="yn-en" lang="en">Read each source from a bookmark, not a fixed time window.</span>每个信息源都从书签开始读，不用固定的时间窗口。</li>
<li><span class="yn-en" lang="en">Report a failed read as unreadable, never as a quiet day.</span>读取失败就报「读不到」，绝不说成今天没事。</li>
<li><span class="yn-en" lang="en">Re-check every item right before posting.</span>发之前把每一条都再查一遍。</li>
<li><span class="yn-en" lang="en">Count a post as sent only when Slack confirms it, then update bookmarks and ledger.</span>Slack 确认了才算发出去，之后再更新书签和台账。</li>
<li><span class="yn-en" lang="en">Re-read your preferences every run, from a store the agent can't edit.</span>每次运行都重读偏好，偏好放在 agent 改不了的记忆库里。</li>
<li><span class="yn-en" lang="en">Give the agent read-only access wherever it only reads, and cap what each run can spend.</span>凡是 agent 只读的地方都给只读权限，并给每次运行的花费设上限。</li>
</ul>
<div class="yn-en" lang="en">
<p>Claude Code can walk you through the guidance provided in this article. First, update:</p>
</div>
<p>Claude Code 可以带你把这篇文章的指引走一遍。先更新：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>claude update</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>Then, use the claude-api skill:</p>
</div>
<p>然后用 claude-api skill：</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>The claude-api skill reads this post, proposes a setup, writes the files to an agents/ folder in your project, and creates the resources with ant apply. Treat this as a starting point, and customize the agent for your sources, destination, or memory preferences.</p>
</div>
<p>claude-api skill 会读这篇文章，提出一套配置方案，把文件写进你项目里的 agents/ 文件夹，再用 ant apply 把资源建出来。把它当作起点，再按你自己的信息源、目的地或记忆偏好去定制这个 agent。</p>
]]></content:encoded>
</item>
<item>
<title>Claude Code 命令与技巧全览</title>
<link>https://nyann.cc/posts/Claude%20Code%20%E5%91%BD%E4%BB%A4%E4%B8%8E%E6%8A%80%E5%B7%A7%E5%85%A8%E8%A7%88</link>
<guid isPermaLink="true">https://nyann.cc/posts/Claude%20Code%20%E5%91%BD%E4%BB%A4%E4%B8%8E%E6%8A%80%E5%B7%A7%E5%85%A8%E8%A7%88</guid>
<pubDate>Tue, 27 Oct 2026 00:00:00 GMT</pubDate>
<description>把 Claude Code 的启动参数、输入前缀、快捷键、全部斜杠命令，以及权限、记忆、检查点、Skills、子代理、Hooks、MCP 和非交互模式整理成一份对照官方文档核过的速查手册。</description>
<category>AI</category>
<category>Claude</category>
<category>工具</category>
<content:encoded><![CDATA[<h1 id="claude-code-命令与技巧全览" tabindex="-1">Claude Code 命令与技巧全览 <a class="header-anchor" href="#claude-code-命令与技巧全览" aria-label="本节链接：Claude Code 命令与技巧全览">&ZeroWidthSpace;</a></h1>
<p>这篇是我自己学 Claude Code 时整理的速查手册。所有内容都对照了 <a href="https://code.claude.com/docs" target="_blank" rel="noreferrer">官方文档</a> 和本机 <code>claude --help</code> 的输出，写作时的版本是 v2.1.310（2026 年 10 月）。</p>
<ul>
<li>Claude Code 更新很快，几乎每周都有命令增删，所以以你本机为准：在会话里敲 <code>/</code> 能看到当前可用的全部命令，<code>claude --help</code> 列出全部启动参数，<code>/release-notes</code> 看更新日志。</li>
<li>下文表格里标 <span class="yn-star" title="常用">★</span> 的是日常最常用的命令和快捷键，初学先记这些就够了。</li>
<li>不是每个命令每个人都有。可用与否取决于平台、套餐和登录方式，比如 <code>/desktop</code> 只在 macOS 和 x64 Windows 且用 Claude 订阅登录时出现，<code>/upgrade</code> 在 Enterprise 套餐下不显示。</li>
</ul>
<h2 id="启动-命令行参数" tabindex="-1">启动：命令行参数 <a class="header-anchor" href="#启动-命令行参数" aria-label="本节链接：启动：命令行参数">&ZeroWidthSpace;</a></h2>
<h3 id="最常用的几种启动方式" tabindex="-1">最常用的几种启动方式 <a class="header-anchor" href="#最常用的几种启动方式" aria-label="本节链接：最常用的几种启动方式">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>claude</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">在当前目录启动交互式会话</td>
</tr>
<tr>
<td style="text-align:left"><code>claude &quot;解释一下这个项目&quot;</code></td>
<td style="text-align:left">启动交互式会话，并把这句话作为第一条消息</td>
</tr>
<tr>
<td style="text-align:left"><code>claude -p &quot;查询&quot;</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">非交互模式：输出结果后直接退出，适合脚本和管道</td>
</tr>
<tr>
<td style="text-align:left"><code>cat log.txt | claude -p &quot;解释这个报错&quot;</code></td>
<td style="text-align:left">把管道内容喂给 Claude</td>
</tr>
<tr>
<td style="text-align:left"><code>claude -c</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">继续当前目录下最近一次对话</td>
</tr>
<tr>
<td style="text-align:left"><code>claude -r</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">打开会话选择器；<code>claude -r auth-refactor</code> 按名字或 ID 恢复</td>
</tr>
<tr>
<td style="text-align:left"><code>claude -n 名字</code></td>
<td style="text-align:left">给本次会话起名，显示在输入框、<code>/resume</code> 列表和终端标题里</td>
</tr>
<tr>
<td style="text-align:left"><code>claude -w feature-auth</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">在 <code>.claude/worktrees/feature-auth</code> 新建一个 git worktree 并在里面启动</td>
</tr>
<tr>
<td style="text-align:left"><code>claude --bg &quot;任务&quot;</code></td>
<td style="text-align:left">在后台启动会话并立即返回，打印的 ID 给 <code>claude attach</code> / <code>logs</code> / <code>stop</code> 用</td>
</tr>
</tbody>
</table>
<h3 id="常用参数" tabindex="-1">常用参数 <a class="header-anchor" href="#常用参数" aria-label="本节链接：常用参数">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">参数</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>--model &lt;model&gt;</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">指定模型，可以写别名（<code>fable</code>、<code>opus</code>、<code>sonnet</code>）或完整模型名</td>
</tr>
<tr>
<td style="text-align:left"><code>--effort &lt;level&gt;</code></td>
<td style="text-align:left">推理强度：<code>low</code>、<code>medium</code>、<code>high</code>、<code>xhigh</code>、<code>max</code></td>
</tr>
<tr>
<td style="text-align:left"><code>--permission-mode &lt;mode&gt;</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">启动时的权限模式：<code>acceptEdits</code>、<code>auto</code>、<code>bypassPermissions</code>、<code>manual</code>、<code>dontAsk</code>、<code>plan</code></td>
</tr>
<tr>
<td style="text-align:left"><code>--add-dir &lt;dirs...&gt;</code></td>
<td style="text-align:left">额外允许访问的目录</td>
</tr>
<tr>
<td style="text-align:left"><code>--allowedTools</code> / <code>--disallowedTools</code></td>
<td style="text-align:left">放行 / 禁止某些工具，如 <code>&quot;Bash(git *) Edit&quot;</code></td>
</tr>
<tr>
<td style="text-align:left"><code>--tools &lt;tools...&gt;</code></td>
<td style="text-align:left">限定可用的内置工具集合，<code>&quot;&quot;</code> 表示全部禁用</td>
</tr>
<tr>
<td style="text-align:left"><code>--agent &lt;agent&gt;</code></td>
<td style="text-align:left">让整个会话以某个子代理的身份运行</td>
</tr>
<tr>
<td style="text-align:left"><code>--append-system-prompt &lt;prompt&gt;</code></td>
<td style="text-align:left">在默认系统提示后追加内容；<code>--system-prompt</code> 则是整体替换</td>
</tr>
<tr>
<td style="text-align:left"><code>--mcp-config &lt;configs...&gt;</code></td>
<td style="text-align:left">从 JSON 文件或字符串加载 MCP 服务器；配合 <code>--strict-mcp-config</code> 只用这些</td>
</tr>
<tr>
<td style="text-align:left"><code>--settings &lt;file-or-json&gt;</code></td>
<td style="text-align:left">本次会话额外加载一份设置</td>
</tr>
<tr>
<td style="text-align:left"><code>--fork-session</code></td>
<td style="text-align:left">配合 <code>-r</code> / <code>-c</code>，恢复时生成新的会话 ID，原会话不动</td>
</tr>
<tr>
<td style="text-align:left"><code>--from-pr [value]</code></td>
<td style="text-align:left">恢复与某个 PR 关联的会话</td>
</tr>
<tr>
<td style="text-align:left"><code>--chrome</code> / <code>--ide</code></td>
<td style="text-align:left">启用 Claude in Chrome / 启动时自动连接 IDE</td>
</tr>
<tr>
<td style="text-align:left"><code>-d, --debug [filter]</code></td>
<td style="text-align:left">调试模式，可按类别过滤，如 <code>--debug=hooks,mcp</code></td>
</tr>
<tr>
<td style="text-align:left"><code>--safe-mode</code></td>
<td style="text-align:left">关掉所有自定义（CLAUDE.md、skills、插件、hooks、MCP 等）启动，排查配置问题用</td>
</tr>
<tr>
<td style="text-align:left"><code>--bare</code></td>
<td style="text-align:left">极简模式：跳过 hooks、插件、自动记忆、CLAUDE.md 自动发现等，脚本里启动更快</td>
</tr>
<tr>
<td style="text-align:left"><code>--dangerously-skip-permissions</code></td>
<td style="text-align:left">跳过所有权限检查。官方建议只在没有外网的沙箱里用</td>
</tr>
</tbody>
</table>
<p>只对 <code>-p</code> 生效的参数：<code>--output-format</code>（<code>text</code> / <code>json</code> / <code>stream-json</code>）、<code>--input-format</code>、<code>--json-schema</code>（结构化输出）、<code>--max-budget-usd</code>（花费上限）、<code>--no-session-persistence</code>、<code>--include-partial-messages</code>。</p>
<h3 id="子命令" tabindex="-1">子命令 <a class="header-anchor" href="#子命令" aria-label="本节链接：子命令">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">子命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>claude update</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">检查并安装更新（别名 <code>upgrade</code>）</td>
</tr>
<tr>
<td style="text-align:left"><code>claude install [target]</code></td>
<td style="text-align:left">安装原生版本，可指定 <code>stable</code>、<code>latest</code> 或具体版本号</td>
</tr>
<tr>
<td style="text-align:left"><code>claude doctor</code></td>
<td style="text-align:left">检查安装健康状况；会话里的 <code>/doctor</code> 更全，还能帮你修</td>
</tr>
<tr>
<td style="text-align:left"><code>claude mcp</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">管理 MCP 服务器，见下文</td>
</tr>
<tr>
<td style="text-align:left"><code>claude plugin</code></td>
<td style="text-align:left">管理插件</td>
</tr>
<tr>
<td style="text-align:left"><code>claude auth</code></td>
<td style="text-align:left">管理登录认证</td>
</tr>
<tr>
<td style="text-align:left"><code>claude setup-token</code></td>
<td style="text-align:left">生成长期有效的认证 token（需要 Claude 订阅）</td>
</tr>
<tr>
<td style="text-align:left"><code>claude agents</code></td>
<td style="text-align:left">列出和管理后台会话</td>
</tr>
<tr>
<td style="text-align:left"><code>claude attach &lt;id&gt;</code></td>
<td style="text-align:left">把一个后台会话接回当前终端</td>
</tr>
<tr>
<td style="text-align:left"><code>claude logs &lt;id&gt;</code></td>
<td style="text-align:left">打印后台会话最近的输出</td>
</tr>
<tr>
<td style="text-align:left"><code>claude stop &lt;id&gt;</code></td>
<td style="text-align:left">停止后台会话，对话保留</td>
</tr>
<tr>
<td style="text-align:left"><code>claude rm &lt;id&gt;</code></td>
<td style="text-align:left">删除后台会话（安全时连 worktree 一起删）</td>
</tr>
<tr>
<td style="text-align:left"><code>claude ultrareview [target]</code></td>
<td style="text-align:left">在云端跑多代理代码评审</td>
</tr>
<tr>
<td style="text-align:left"><code>claude import [source]</code></td>
<td style="text-align:left">从别的 AI 编码工具导入配置</td>
</tr>
<tr>
<td style="text-align:left"><code>claude purge [path]</code></td>
<td style="text-align:left">删除某个项目的全部 Claude Code 状态（对话记录、文件历史等）</td>
</tr>
</tbody>
</table>
<p>子命令拼错时，Claude Code 会提示最接近的那个并退出，比如 <code>claude udpate</code> 会打印 <code>Did you mean claude update?</code>。</p>
<h2 id="输入框-前缀与多行" tabindex="-1">输入框：前缀与多行 <a class="header-anchor" href="#输入框-前缀与多行" aria-label="本节链接：输入框：前缀与多行">&ZeroWidthSpace;</a></h2>
<h3 id="开头字符决定输入的含义" tabindex="-1">开头字符决定输入的含义 <a class="header-anchor" href="#开头字符决定输入的含义" aria-label="本节链接：开头字符决定输入的含义">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">输入</th>
<th style="text-align:left">含义</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/</code> 开头 <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">命令或 skill。只有出现在消息开头才会执行，后面的文字是它的参数</td>
</tr>
<tr>
<td style="text-align:left"><code>!</code> 开头 <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">Shell 模式：直接跑命令，不经过 Claude 审批，命令和输出进入上下文，Claude 会接着解读</td>
</tr>
<tr>
<td style="text-align:left"><code>@</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">引用文件路径（带自动补全），也可以 <code>@</code> 目录、<code>@server:resource</code> 引用 MCP 资源</td>
</tr>
<tr>
<td style="text-align:left"><code>:</code></td>
<td style="text-align:left">输入 <code>:name:</code> 插入 emoji</td>
</tr>
<tr>
<td style="text-align:left">空输入框里按 <code>?</code></td>
<td style="text-align:left">打开快捷键帮助面板</td>
</tr>
</tbody>
</table>
<p>几个细节：</p>
<ul>
<li><code>! npm test</code> 跑完后 Claude 会自动解释输出，消耗等同发一条普通消息。只想把输出放进上下文、不要回复，可在 <code>settings.json</code> 里把 <code>respondToBashCommands</code> 设为 <code>false</code>。</li>
<li>Shell 模式下用 <code>Tab</code> 可以从当前项目以前的 <code>!</code> 命令里补全；输入带 <code>/</code> 的路径会弹出文件补全。退出 Shell 模式：空输入时按 <code>Esc</code>、<code>Backspace</code> 或 <code>Ctrl+U</code>。</li>
<li><code>@src/utils/auth.js</code> 会把文件内容直接放进对话（在 Read 工具的 token 上限内，默认 25,000 token；超过 256KB 的文本文件不会放进去）。</li>
<li>一条消息可以叠多个 skill：<code>/write-tests /fix-issue 123</code> 会加载两个 skill，<code>123</code> 作为参数传给每一个，最多叠六个。</li>
<li>在句子中间敲 <code>/</code> 也有补全（比如 <code>跑完测试再 /com</code>），但只有开头的命令会被执行。</li>
</ul>
<h3 id="多行输入" tabindex="-1">多行输入 <a class="header-anchor" href="#多行输入" aria-label="本节链接：多行输入">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">方式</th>
<th style="text-align:left">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>\</code> + <code>Enter</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">所有终端都能用</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+J</code></td>
<td style="text-align:left">所有终端都能用，不需要配置</td>
</tr>
<tr>
<td style="text-align:left"><code>Shift+Enter</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">iTerm2、WezTerm、Ghostty、Kitty、Warp、Apple Terminal、Windows Terminal 原生支持；VS Code、Cursor 等可用 <code>/terminal-setup</code> 装上</td>
</tr>
<tr>
<td style="text-align:left"><code>Option+Enter</code></td>
<td style="text-align:left">macOS 上把 Option 设成 Meta 键之后可用</td>
</tr>
<tr>
<td style="text-align:left">直接粘贴</td>
<td style="text-align:left">适合代码块和日志</td>
</tr>
</tbody>
</table>
<h3 id="图片" tabindex="-1">图片 <a class="header-anchor" href="#图片" aria-label="本节链接：图片">&ZeroWidthSpace;</a></h3>
<p>三种方式：把图片拖进窗口；复制后用 <code>Ctrl+V</code> 粘贴（iTerm2 里是 <code>Cmd+V</code>，Windows/WSL 是 <code>Alt+V</code>）；或者直接在消息里写图片路径。粘贴后会出现一个 <code>[Image #N]</code> 标记。</p>
<h2 id="快捷键" tabindex="-1">快捷键 <a class="header-anchor" href="#快捷键" aria-label="本节链接：快捷键">&ZeroWidthSpace;</a></h2>
<p>macOS 用户注意：<code>Alt+B</code>、<code>Alt+F</code>、<code>Alt+D</code>、<code>Alt+Y</code>、<code>Alt+P</code> 这类快捷键需要在终端里把 Option 设为 Meta 键。</p>
<h3 id="常规控制" tabindex="-1">常规控制 <a class="header-anchor" href="#常规控制" aria-label="本节链接：常规控制">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">快捷键</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>Esc</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">打断 Claude 当前的回复或工具调用，已经做的工作保留；有对话框时关闭对话框</td>
</tr>
<tr>
<td style="text-align:left"><code>Esc</code> <code>Esc</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">输入框有字时：清空并存进历史（按 <code>Up</code> 能找回）；输入框为空时：打开回退（rewind）菜单</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+C</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">有任务在跑时打断；没有时第一下清空输入，第二下退出</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+D</code></td>
<td style="text-align:left">退出（按两下，800ms 内）；输入框有字时是向后删一个字符</td>
</tr>
<tr>
<td style="text-align:left"><code>Shift+Tab</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">循环切换权限模式（Windows 某些情况下是 <code>Alt+M</code>）</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+B</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">把正在运行的 Bash 命令或代理放到后台（tmux 里要按两次）</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+O</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">打开 / 关闭对话详情视图，能看到每次工具调用的细节</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+T</code></td>
<td style="text-align:left">显示 / 隐藏 Claude 的任务清单</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+R</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">反向搜索输入历史</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+G</code> 或 <code>Ctrl+X Ctrl+E</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">用默认编辑器编辑当前输入（写长提示词很好用）</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+S</code></td>
<td style="text-align:left">暂存当前输入并清空；在空输入框再按一次恢复</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+L</code></td>
<td style="text-align:left">重绘屏幕，界面花了的时候用</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+V</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">粘贴图片</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+Z</code></td>
<td style="text-align:left">挂起到 shell（仅 Unix），用 <code>fg</code> 回来</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+Enter</code> 或 <code>Ctrl+X Ctrl+S</code></td>
<td style="text-align:left">立即发送排队中的消息</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+X Ctrl+K</code></td>
<td style="text-align:left">停止本会话所有后台子代理（3 秒内按两次确认）</td>
</tr>
<tr>
<td style="text-align:left"><code>Option+P</code> / <code>Alt+P</code></td>
<td style="text-align:left">切换模型，不清空输入</td>
</tr>
<tr>
<td style="text-align:left"><code>Option+T</code> / <code>Alt+T</code></td>
<td style="text-align:left">开关扩展思考（对 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 无效，它们始终开启）</td>
</tr>
<tr>
<td style="text-align:left"><code>Option+O</code> / <code>Alt+O</code></td>
<td style="text-align:left">开关 fast 模式</td>
</tr>
<tr>
<td style="text-align:left"><code>Up</code> / <code>Down</code></td>
<td style="text-align:left">在多行输入里移动光标，到首行 / 末行后再按就是翻历史</td>
</tr>
<tr>
<td style="text-align:left"><code>Tab</code></td>
<td style="text-align:left">接受补全建议</td>
</tr>
</tbody>
</table>
<h3 id="文本编辑" tabindex="-1">文本编辑 <a class="header-anchor" href="#文本编辑" aria-label="本节链接：文本编辑">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">快捷键</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>Ctrl+A</code> / <code>Ctrl+E</code></td>
<td style="text-align:left">移到行首 / 行尾</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+K</code></td>
<td style="text-align:left">删到行尾</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+U</code></td>
<td style="text-align:left">删到行首（macOS 终端里 <code>Cmd+Backspace</code> 映射到它）</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+W</code></td>
<td style="text-align:left">向前删到上一个空白，一下删掉一整个路径或 <code>--flag=value</code></td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+Y</code></td>
<td style="text-align:left">粘贴刚才删掉的文字；之后按 <code>Alt+Y</code> 循环更早的删除内容</td>
</tr>
<tr>
<td style="text-align:left"><code>Alt+B</code> / <code>Alt+F</code></td>
<td style="text-align:left">按词后退 / 前进</td>
</tr>
<tr>
<td style="text-align:left"><code>Alt+D</code></td>
<td style="text-align:left">删到词尾</td>
</tr>
<tr>
<td style="text-align:left"><code>Ctrl+_</code></td>
<td style="text-align:left">撤销上一次输入编辑</td>
</tr>
</tbody>
</table>
<h3 id="vim-模式和自定义快捷键" tabindex="-1">Vim 模式和自定义快捷键 <a class="header-anchor" href="#vim-模式和自定义快捷键" aria-label="本节链接：Vim 模式和自定义快捷键">&ZeroWidthSpace;</a></h3>
<ul>
<li><code>/vim</code> 命令在 v2.1.92 已经移除，现在从 <code>/config</code> → Editor mode 切换。支持常见的 NORMAL / INSERT / VISUAL 操作：<code>hjkl</code>、<code>w</code>/<code>b</code>/<code>e</code>、<code>dd</code>、<code>ciw</code>、<code>yy</code>/<code>p</code>、<code>u</code>、<code>.</code> 等。NORMAL 模式下按 <code>/</code> 是历史搜索，不是命令菜单。</li>
<li><code>/keybindings</code> 打开 <code>~/.claude/keybindings.json</code>，可以改绑任意快捷键。</li>
</ul>
<h3 id="claude-干活时也能继续打字" tabindex="-1">Claude 干活时也能继续打字 <a class="header-anchor" href="#claude-干活时也能继续打字" aria-label="本节链接：Claude 干活时也能继续打字">&ZeroWidthSpace;</a></h3>
<p>Claude 在工作时按 <code>Enter</code>，消息会排队，不会打断当前这一轮。普通消息会在当前这批工具调用结束后、同一轮里就交给 Claude；命令和 <code>!</code> 命令会等这一轮结束再按顺序执行。从输入框第一行按 <code>Up</code> 能把排队的内容收回来修改。</p>
<h2 id="斜杠命令-全部清单" tabindex="-1">斜杠命令：全部清单 <a class="header-anchor" href="#斜杠命令-全部清单" aria-label="本节链接：斜杠命令：全部清单">&ZeroWidthSpace;</a></h2>
<p>这里收了当前文档里的全部内置命令。标 <strong>(skill)</strong> 的是内置 skill：本质是一段交给 Claude 的提示词，和你自己写的 skill 一样运作。参数里 <code>&lt;arg&gt;</code> 是必填，<code>[arg]</code> 是可选。</p>
<h3 id="会话与上下文" tabindex="-1">会话与上下文 <a class="header-anchor" href="#会话与上下文" aria-label="本节链接：会话与上下文">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/clear [name]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">开新对话、清空上下文（项目记忆保留）。别名 <code>/reset</code>、<code>/new</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/compact [instructions]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">把对话压缩成摘要以腾出上下文，可以附加摘要重点，如 <code>/compact 重点保留 API 改动</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/autocompact [auto|&lt;tokens&gt;]</code></td>
<td style="text-align:left">设置自动压缩的触发窗口，如 <code>500k</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/context [all]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">用彩色网格可视化上下文占用，并给出优化建议</td>
</tr>
<tr>
<td style="text-align:left"><code>/resume [session]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">恢复之前的对话，不带参数打开选择器。别名 <code>/continue</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/rename [name]</code></td>
<td style="text-align:left">重命名当前会话；不带参数则根据对话自动起名</td>
</tr>
<tr>
<td style="text-align:left"><code>/branch [name]</code></td>
<td style="text-align:left">从当前位置分出一个对话分支并切过去，原对话可用 <code>/resume</code> 回去</td>
</tr>
<tr>
<td style="text-align:left"><code>/fork [prompt]</code></td>
<td style="text-align:left">把当前对话复制成一个新的后台会话，你留在这里继续</td>
</tr>
<tr>
<td style="text-align:left"><code>/subtask &lt;task&gt;</code></td>
<td style="text-align:left">派一个继承完整对话的后台子代理去做事，结果会回到当前对话</td>
</tr>
<tr>
<td style="text-align:left"><code>/rewind</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">回退代码和 / 或对话到某个检查点，或对某段对话做摘要。别名 <code>/checkpoint</code>、<code>/undo</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/btw [question]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">问个旁支问题，问答不进入对话历史；Claude 工作时也能问</td>
</tr>
<tr>
<td style="text-align:left"><code>/recap</code></td>
<td style="text-align:left">生成当前会话的一句话摘要</td>
</tr>
<tr>
<td style="text-align:left"><code>/export [filename]</code></td>
<td style="text-align:left">把对话导出为纯文本</td>
</tr>
<tr>
<td style="text-align:left"><code>/copy [N]</code></td>
<td style="text-align:left">复制最近一条回复（<code>/copy 2</code> 是倒数第二条），有代码块时可挑选；按 <code>w</code> 写入文件</td>
</tr>
<tr>
<td style="text-align:left"><code>/diff</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">查看工作区改动，包括 Claude 到目前为止的编辑</td>
</tr>
<tr>
<td style="text-align:left"><code>/exit</code></td>
<td style="text-align:left">退出。别名 <code>/quit</code></td>
</tr>
</tbody>
</table>
<h3 id="模型与推理" tabindex="-1">模型与推理 <a class="header-anchor" href="#模型与推理" aria-label="本节链接：模型与推理">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/model [model]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">切换模型并存为默认；选择器里按 <code>s</code> 只对本会话生效，左右方向键调推理强度</td>
</tr>
<tr>
<td style="text-align:left"><code>/effort [level|auto|status|ultracode [on|off]]</code></td>
<td style="text-align:left">设置推理强度；<code>max</code> 只对本会话有效</td>
</tr>
<tr>
<td style="text-align:left"><code>/fast [on|off]</code></td>
<td style="text-align:left">开关 fast 模式</td>
</tr>
<tr>
<td style="text-align:left"><code>/advisor [model|off]</code></td>
<td style="text-align:left">开关 advisor：关键时刻向第二个模型请教</td>
</tr>
<tr>
<td style="text-align:left"><code>/plan [description]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">进入计划模式，可直接带上任务，如 <code>/plan 修复登录 bug</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/goal [condition|clear]</code></td>
<td style="text-align:left">设一个目标，Claude 会跨多轮持续工作直到条件满足</td>
</tr>
</tbody>
</table>
<h3 id="权限与安全" tabindex="-1">权限与安全 <a class="header-anchor" href="#权限与安全" aria-label="本节链接：权限与安全">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/permissions</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">管理 allow / ask / deny 规则和工作目录。别名 <code>/allowed-tools</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/sandbox</code></td>
<td style="text-align:left">开关沙箱模式（仅支持的平台）</td>
</tr>
<tr>
<td style="text-align:left"><code>/auto-mode-setup</code></td>
<td style="text-align:left">根据项目和最近的会话起草 auto 模式的环境描述，审阅后保存</td>
</tr>
<tr>
<td style="text-align:left"><code>/fewer-permission-prompts</code></td>
<td style="text-align:left"><strong>(skill)</strong> 扫描历史里常用的只读命令，生成 allowlist 写进项目 <code>.claude/settings.json</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/security-review</code></td>
<td style="text-align:left">检查当前分支相对 origin 默认分支的改动有没有安全漏洞（需要 <code>origin</code> remote）</td>
</tr>
</tbody>
</table>
<h3 id="项目配置与记忆" tabindex="-1">项目配置与记忆 <a class="header-anchor" href="#项目配置与记忆" aria-label="本节链接：项目配置与记忆">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/init</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">分析代码库，生成初始 <code>CLAUDE.md</code>；已有时给出改进建议。设 <code>CLAUDE_CODE_NEW_INIT=1</code> 走交互式流程，顺带配置 skills 和 hooks</td>
</tr>
<tr>
<td style="text-align:left"><code>/memory</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">编辑 <code>CLAUDE.md</code>，开关 / 查看自动记忆</td>
</tr>
<tr>
<td style="text-align:left"><code>/config [key=value ...]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">打开设置面板，或直接 <code>/config theme=dark</code>、<code>/config model=sonnet</code>。别名 <code>/settings</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/add-dir &lt;path&gt;</code></td>
<td style="text-align:left">给本会话添加工作目录</td>
</tr>
<tr>
<td style="text-align:left"><code>/cd &lt;path&gt;</code></td>
<td style="text-align:left">把会话移到另一个目录，对话保留</td>
</tr>
<tr>
<td style="text-align:left"><code>/hooks</code></td>
<td style="text-align:left">查看 hook 配置</td>
</tr>
<tr>
<td style="text-align:left"><code>/statusline</code></td>
<td style="text-align:left">配置状态栏，描述你要什么或不带参数从 shell 提示符自动生成</td>
</tr>
<tr>
<td style="text-align:left"><code>/output-style [style]</code></td>
<td style="text-align:left">列出或切换输出风格</td>
</tr>
<tr>
<td style="text-align:left"><code>/theme</code></td>
<td style="text-align:left">切换配色主题，可新建自定义主题</td>
</tr>
<tr>
<td style="text-align:left"><code>/keybindings</code></td>
<td style="text-align:left">打开快捷键配置文件</td>
</tr>
<tr>
<td style="text-align:left"><code>/terminal-setup</code></td>
<td style="text-align:left">为当前终端装 <code>Shift+Enter</code> 换行等配置</td>
</tr>
<tr>
<td style="text-align:left"><code>/tui [default|fullscreen]</code></td>
<td style="text-align:left">切换渲染器，<code>fullscreen</code> 是无闪烁的全屏模式</td>
</tr>
<tr>
<td style="text-align:left"><code>/focus</code></td>
<td style="text-align:left">全屏模式下的精简视图：只看最后的提问、工具调用摘要和最终回复</td>
</tr>
<tr>
<td style="text-align:left"><code>/scroll-speed</code></td>
<td style="text-align:left">全屏模式下调整滚轮速度</td>
</tr>
<tr>
<td style="text-align:left"><code>/color [color|default]</code></td>
<td style="text-align:left">设置输入栏颜色</td>
</tr>
<tr>
<td style="text-align:left"><code>/update-config [request]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 用自然语言描述设置改动，Claude 去改对应的 <code>settings.json</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/import [codex|gemini|cursor]</code></td>
<td style="text-align:left">从 Codex、Gemini CLI、Cursor 导入配置</td>
</tr>
</tbody>
</table>
<h3 id="扩展-skills、插件、mcp、子代理" tabindex="-1">扩展：skills、插件、MCP、子代理 <a class="header-anchor" href="#扩展-skills、插件、mcp、子代理" aria-label="本节链接：扩展：skills、插件、MCP、子代理">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/skills</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">列出可用 skill，按 <code>t</code> 按 token 数排序，空格 / 回车切换可见性</td>
</tr>
<tr>
<td style="text-align:left"><code>/reload-skills</code></td>
<td style="text-align:left">重新扫描 skill 目录，不用重启</td>
</tr>
<tr>
<td style="text-align:left"><code>/skill-doctor</code></td>
<td style="text-align:left">看每个 skill 占多少上下文、用了多少次</td>
</tr>
<tr>
<td style="text-align:left"><code>/plugin [subcommand]</code></td>
<td style="text-align:left">管理插件：<code>list</code>、<code>install</code>、<code>enable</code>、<code>disable</code> 等</td>
</tr>
<tr>
<td style="text-align:left"><code>/reload-plugins [--force]</code></td>
<td style="text-align:left">重新加载插件</td>
</tr>
<tr>
<td style="text-align:left"><code>/mcp</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">管理 MCP 连接和 OAuth；<code>/mcp reconnect all</code> 重连所有失败的服务器</td>
</tr>
<tr>
<td style="text-align:left"><code>/agents</code></td>
<td style="text-align:left">现在只打印一句提示：让 Claude 帮你建子代理，或直接编辑 <code>.claude/agents/</code>（v2.1.197 及以前是交互界面）</td>
</tr>
<tr>
<td style="text-align:left"><code>/list-agents</code></td>
<td style="text-align:left">列出可以发消息的子代理和其他会话（需要开启跨会话消息）。别名 <code>/peers</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/plugin-authoring</code></td>
<td style="text-align:left">加载编写 mod 的参考资料</td>
</tr>
<tr>
<td style="text-align:left"><code>/workflow-authoring</code></td>
<td style="text-align:left"><strong>(skill)</strong> 加载编写动态 workflow 脚本的参考</td>
</tr>
</tbody>
</table>
<h3 id="代码评审与验证" tabindex="-1">代码评审与验证 <a class="header-anchor" href="#代码评审与验证" aria-label="本节链接：代码评审与验证">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/code-review [level] [--fix] [--comment] [target]</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left"><strong>(skill)</strong> 检查当前 diff 的正确性问题；<code>--fix</code> 直接修，<code>--comment</code> 发到 PR，<code>ultra</code> 走云端深度评审。可传 PR 号、分支或路径。别名 <code>/review</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/ultrareview [PR or branch]</code></td>
<td style="text-align:left">云端多代理深度评审，推荐写法是 <code>/code-review ultra</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/simplify [target]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 四个代理并行检查改动里可复用、可简化、可提效的地方并直接改，不找 bug</td>
</tr>
<tr>
<td style="text-align:left"><code>/verify</code></td>
<td style="text-align:left"><strong>(skill)</strong> 构建并实际运行应用来确认改动生效，不只看测试</td>
</tr>
<tr>
<td style="text-align:left"><code>/run</code></td>
<td style="text-align:left"><strong>(skill)</strong> 启动并操作你的应用，亲眼看到改动</td>
</tr>
<tr>
<td style="text-align:left"><code>/run-skill-generator</code></td>
<td style="text-align:left"><strong>(skill)</strong> 为项目生成一个教 <code>/run</code>、<code>/verify</code> 怎么启动应用的 skill</td>
</tr>
<tr>
<td style="text-align:left"><code>/autofix-pr [prompt]</code></td>
<td style="text-align:left">开一个云端会话盯住当前分支的 PR，CI 挂了或有评论时自动推修复</td>
</tr>
</tbody>
</table>
<h3 id="并行、后台与定时" tabindex="-1">并行、后台与定时 <a class="header-anchor" href="#并行、后台与定时" aria-label="本节链接：并行、后台与定时">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/tasks</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">查看和管理本会话的后台任务（包括已完成的子代理）。别名 <code>/bashes</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/background [prompt]</code></td>
<td style="text-align:left">把整个会话转到后台运行，释放终端。别名 <code>/bg</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/stop</code></td>
<td style="text-align:left">停止当前接入的后台会话</td>
</tr>
<tr>
<td style="text-align:left"><code>/batch &lt;instruction&gt;</code></td>
<td style="text-align:left"><strong>(skill)</strong> 大规模改动：拆成 5 到 30 个独立单元，每个在独立 worktree 里由后台子代理完成</td>
</tr>
<tr>
<td style="text-align:left"><code>/loop [interval] [prompt]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 会话开着期间定时重复执行，如 <code>/loop 5m 看看部署完了没</code>；不写间隔则由 Claude 自己掌握节奏</td>
</tr>
<tr>
<td style="text-align:left"><code>/schedule [description]</code></td>
<td style="text-align:left">创建 / 管理云端定时任务。别名 <code>/routines</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/workflows</code></td>
<td style="text-align:left">查看、暂停、恢复 workflow 的运行进度</td>
</tr>
<tr>
<td style="text-align:left"><code>/deep-research &lt;question&gt;</code></td>
<td style="text-align:left">内置 workflow：并行搜索、交叉核对来源，生成带引用的报告</td>
</tr>
</tbody>
</table>
<h3 id="跨设备与云端" tabindex="-1">跨设备与云端 <a class="header-anchor" href="#跨设备与云端" aria-label="本节链接：跨设备与云端">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/remote-control</code></td>
<td style="text-align:left">让本会话可以从 claude.ai 远程继续。别名 <code>/rc</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/teleport</code></td>
<td style="text-align:left">把云端会话拉到本地终端。别名 <code>/tp</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/desktop</code></td>
<td style="text-align:left">在桌面 App 里继续当前会话。别名 <code>/app</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/remote-env</code></td>
<td style="text-align:left">选择云端会话的默认环境</td>
</tr>
<tr>
<td style="text-align:left"><code>/web-setup</code></td>
<td style="text-align:left">用本地 <code>gh</code> 凭据为云端会话连接 GitHub</td>
</tr>
<tr>
<td style="text-align:left"><code>/mobile</code></td>
<td style="text-align:left">显示下载手机 App 的二维码。别名 <code>/ios</code>、<code>/android</code></td>
</tr>
</tbody>
</table>
<h3 id="账号、用量与诊断" tabindex="-1">账号、用量与诊断 <a class="header-anchor" href="#账号、用量与诊断" aria-label="本节链接：账号、用量与诊断">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/login</code> / <code>/logout</code></td>
<td style="text-align:left">登录 / 登出 Anthropic 账号</td>
</tr>
<tr>
<td style="text-align:left"><code>/status</code></td>
<td style="text-align:left">版本、模型、账号、连接状态</td>
</tr>
<tr>
<td style="text-align:left"><code>/usage</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">本次花费、套餐用量、活动统计。别名 <code>/cost</code>、<code>/stats</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/rate-limit-options</code></td>
<td style="text-align:left">撞到用量上限时的选项：等待自动继续、加购额度或升级</td>
</tr>
<tr>
<td style="text-align:left"><code>/usage-credits</code></td>
<td style="text-align:left">配置用量额度（原 <code>/extra-usage</code>）</td>
</tr>
<tr>
<td style="text-align:left"><code>/upgrade</code></td>
<td style="text-align:left">打开升级套餐页面</td>
</tr>
<tr>
<td style="text-align:left"><code>/privacy-settings</code></td>
<td style="text-align:left">隐私设置（Pro、Max）</td>
</tr>
<tr>
<td style="text-align:left"><code>/insights</code></td>
<td style="text-align:left">生成一份分析你近期使用习惯的 HTML 报告</td>
</tr>
<tr>
<td style="text-align:left"><code>/doctor</code></td>
<td style="text-align:left"><strong>(skill)</strong> 诊断安装、设置、扩展和 CLAUDE.md 问题，确认后帮你修；<code>/doctor prompt-audit</code> 审查指令文件里过时或冲突的内容。别名 <code>/checkup</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/debug [description]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 开启调试日志并帮你分析</td>
</tr>
<tr>
<td style="text-align:left"><code>/heapdump</code></td>
<td style="text-align:left">导出内存快照排查内存问题（菜单里隐藏，要打全名）</td>
</tr>
<tr>
<td style="text-align:left"><code>/bug [report]</code></td>
<td style="text-align:left">报 bug，发送前会让你确认附带多少会话内容。别名 <code>/share</code></td>
</tr>
<tr>
<td style="text-align:left"><code>/feedback [report]</code></td>
<td style="text-align:left">发产品反馈</td>
</tr>
<tr>
<td style="text-align:left"><code>/release-notes</code></td>
<td style="text-align:left">查看更新日志</td>
</tr>
<tr>
<td style="text-align:left"><code>/help</code> <span class="yn-star" title="常用">★</span></td>
<td style="text-align:left">帮助和命令列表</td>
</tr>
</tbody>
</table>
<h3 id="集成与其他" tabindex="-1">集成与其他 <a class="header-anchor" href="#集成与其他" aria-label="本节链接：集成与其他">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">命令</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>/ide</code></td>
<td style="text-align:left">管理 IDE 集成</td>
</tr>
<tr>
<td style="text-align:left"><code>/chrome</code></td>
<td style="text-align:left">Claude in Chrome 设置</td>
</tr>
<tr>
<td style="text-align:left"><code>/claude-in-chrome [task]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 让 Claude 在浏览器里执行任务</td>
</tr>
<tr>
<td style="text-align:left"><code>/install-github-app</code></td>
<td style="text-align:left">为仓库安装 Claude GitHub App，可选配置 GitHub Actions</td>
</tr>
<tr>
<td style="text-align:left"><code>/install-slack-app</code></td>
<td style="text-align:left">安装 Claude Slack App</td>
</tr>
<tr>
<td style="text-align:left"><code>/claude-api [subcommand]</code></td>
<td style="text-align:left"><strong>(skill)</strong> 加载 Claude API / Managed Agents 参考资料</td>
</tr>
<tr>
<td style="text-align:left"><code>/voice [hold|tap|off]</code></td>
<td style="text-align:left">语音输入</td>
</tr>
<tr>
<td style="text-align:left"><code>/team-onboarding</code></td>
<td style="text-align:left">根据你过去 30 天的使用记录生成团队上手指南</td>
</tr>
<tr>
<td style="text-align:left"><code>/powerup</code></td>
<td style="text-align:left">交互式小课程，带动画演示，用来发现功能</td>
</tr>
<tr>
<td style="text-align:left"><code>/artifacts</code>、<code>/design</code>、<code>/slides</code>、<code>/dataviz</code> 等</td>
<td style="text-align:left">发布网页 Artifact、画设计稿、做幻灯片、图表设计指引（需要账号支持 Artifacts）</td>
</tr>
<tr>
<td style="text-align:left"><code>/setup-bedrock</code> / <code>/setup-vertex</code></td>
<td style="text-align:left">配置第三方云平台（设置对应环境变量后才出现）</td>
</tr>
<tr>
<td style="text-align:left"><code>/passes</code>、<code>/stickers</code>、<code>/radio</code></td>
<td style="text-align:left">送朋友试用、订贴纸、开 lo-fi 电台</td>
</tr>
</tbody>
</table>
<p>已移除的命令：<code>/vim</code>（用 <code>/config</code>）、<code>/pr-comments</code>（直接让 Claude 去看 PR 评论）、<code>/ultraplan</code>（用计划模式）。</p>
<h2 id="权限模式" tabindex="-1">权限模式 <a class="header-anchor" href="#权限模式" aria-label="本节链接：权限模式">&ZeroWidthSpace;</a></h2>
<p><code>Shift+Tab</code> 循环切换，状态栏会显示当前模式。</p>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">模式</th>
<th style="text-align:left">不问就能做的事</th>
<th style="text-align:left">适合</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>default</code>（界面上叫 Manual）</td>
<td style="text-align:left">只有读取</td>
<td style="text-align:left">每一步都要自己过目</td>
</tr>
<tr>
<td style="text-align:left"><code>acceptEdits</code></td>
<td style="text-align:left">读取、改文件、常见文件系统命令（<code>mkdir</code>、<code>mv</code>、<code>cp</code> 等）</td>
<td style="text-align:left">边看边迭代</td>
</tr>
<tr>
<td style="text-align:left"><code>plan</code></td>
<td style="text-align:left">只读探索，不改源码，写出计划等你批准</td>
<td style="text-align:left">动手前先摸清代码库</td>
</tr>
<tr>
<td style="text-align:left"><code>auto</code></td>
<td style="text-align:left">全部，但有一个独立的分类器模型在后台审查每个动作</td>
<td style="text-align:left">长任务、不想被频繁打断</td>
</tr>
<tr>
<td style="text-align:left"><code>dontAsk</code></td>
<td style="text-align:left">工作目录内的读取和预先放行的工具，其他一律拒绝</td>
<td style="text-align:left">CI 和脚本</td>
</tr>
<tr>
<td style="text-align:left"><code>bypassPermissions</code></td>
<td style="text-align:left">全部</td>
<td style="text-align:left">只在隔离的容器 / 虚拟机里用</td>
</tr>
</tbody>
</table>
<p>要点：</p>
<ul>
<li>v2.1.283 起，交互式终端会话默认就从 <code>auto</code> 模式启动。<code>claude -p</code> 在没有任何设置指定模式时以 Manual 模式启动（v2.1.302 起）。</li>
<li>循环顺序是 <code>default</code> → <code>acceptEdits</code> → <code>plan</code>，之后是可选的 <code>bypassPermissions</code> 和 <code>auto</code>。<code>dontAsk</code> 不在循环里，只能用 <code>--permission-mode dontAsk</code> 指定。</li>
<li>计划写好后可以选：批准并进入 auto 模式、批准但每次编辑手动确认、或者继续改计划。批准前按 <code>Ctrl+G</code> 能在编辑器里直接改计划。</li>
<li>deny 规则在所有模式下都生效，包括 <code>bypassPermissions</code>。</li>
</ul>
<h3 id="权限规则" tabindex="-1">权限规则 <a class="header-anchor" href="#权限规则" aria-label="本节链接：权限规则">&ZeroWidthSpace;</a></h3>
<p>规则写在 <code>settings.json</code> 的 <code>permissions</code> 里，格式是 <code>Tool</code> 或 <code>Tool(specifier)</code>：</p>
<div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">permissions</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">allow</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash(npm run *)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash(git commit *)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">],</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">deny</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash(git push *)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Read(./.env)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Read(./secrets/**)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">]</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span></code></pre>
</div><ul>
<li>判定顺序是 deny → ask → allow，先命中谁算谁，跟具体程度无关。所以宽泛的 deny 会压过精确的 allow。</li>
<li><code>*</code> 要放在子命令后面：<code>Bash(git log *)</code> 只放行 <code>git log</code>，<code>Bash(git *)</code> 放行所有 git 命令。<code>Bash(ls *)</code> 不匹配 <code>lsof</code>（星号前的空格是规则的一部分），<code>Bash(ls*)</code> 则会匹配。</li>
<li>只写工具名的 deny（如 <code>Bash</code>）会把整个工具从 Claude 的视野里拿掉。</li>
<li><code>.claudeignore</code> 没有任何作用，要屏蔽文件请写 <code>Read</code> 的 deny 规则。</li>
<li><code>Read</code> / <code>Edit</code> 规则只管 Claude 的文件工具和它能识别的 <code>cat</code>、<code>head</code> 之类命令，挡不住一个自己去读文件的 Python 脚本。要系统级隔离得开沙箱（<code>/sandbox</code>）。</li>
<li>权限提示里选「Yes, and don't ask again」时，Bash 命令和域名规则会存进仓库根目录的 <code>.claude/settings.local.json</code>；文件修改的放行只到本次会话结束。</li>
</ul>
<h3 id="设置文件的优先级" tabindex="-1">设置文件的优先级 <a class="header-anchor" href="#设置文件的优先级" aria-label="本节链接：设置文件的优先级">&ZeroWidthSpace;</a></h3>
<p>从高到低：组织下发的 managed 设置 → 命令行 <code>--settings</code> → <code>.claude/settings.local.json</code>（个人、本项目）→ <code>.claude/settings.json</code>（团队共享，提交到 git）→ <code>~/.claude/settings.json</code>（个人、所有项目）。像 <code>permissions.allow</code> 这种列表会在各层之间合并，而不是互相覆盖。</p>
<h2 id="记忆-claude-md-与自动记忆" tabindex="-1">记忆：CLAUDE.md 与自动记忆 <a class="header-anchor" href="#记忆-claude-md-与自动记忆" aria-label="本节链接：记忆：CLAUDE.md 与自动记忆">&ZeroWidthSpace;</a></h2>
<p>每个会话都从空白上下文开始，跨会话靠两样东西：你写的 <code>CLAUDE.md</code>，和 Claude 自己记的自动记忆。两者都只是放进上下文的文字，Claude 不保证照做；真要拦住某个动作，得用 hook 或权限规则。</p>
<h3 id="claude-md-放在哪" tabindex="-1">CLAUDE.md 放在哪 <a class="header-anchor" href="#claude-md-放在哪" aria-label="本节链接：CLAUDE.md 放在哪">&ZeroWidthSpace;</a></h3>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">范围</th>
<th style="text-align:left">位置</th>
<th style="text-align:left">谁能看到</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">组织</td>
<td style="text-align:left">macOS 是 <code>/Library/Application Support/ClaudeCode/CLAUDE.md</code></td>
<td style="text-align:left">全组织</td>
</tr>
<tr>
<td style="text-align:left">用户</td>
<td style="text-align:left"><code>~/.claude/CLAUDE.md</code></td>
<td style="text-align:left">你自己，所有项目</td>
</tr>
<tr>
<td style="text-align:left">项目</td>
<td style="text-align:left"><code>./CLAUDE.md</code> 或 <code>./.claude/CLAUDE.md</code></td>
<td style="text-align:left">团队，提交到 git</td>
</tr>
<tr>
<td style="text-align:left">本地</td>
<td style="text-align:left"><code>./CLAUDE.local.md</code></td>
<td style="text-align:left">你自己，本项目，记得加进 <code>.gitignore</code></td>
</tr>
</tbody>
</table>
<ul>
<li>启动时会加载当前目录及所有上级目录的 <code>CLAUDE.md</code>，全部拼接起来而不是互相覆盖，越靠近工作目录的越后读到。子目录里的 <code>CLAUDE.md</code> 要等 Claude 读写那个子目录下的文件时才加载。</li>
<li>用 <code>@path/to/file</code> 可以导入其他文件，比如 <code>参见 @README 和 @package.json</code>，最多递归四层。写在反引号里的 <code>@README</code> 不会被导入。</li>
<li>块级 HTML 注释 <code>&lt;!-- ... --&gt;</code> 会在注入前被剥掉，适合给人看的备注。</li>
<li>跑 <code>/context</code> 能在 <strong>Memory files</strong> 下确认哪些文件加载了。</li>
<li>如果仓库只有 <code>AGENTS.md</code>，Claude Code 也能读它。</li>
</ul>
<h3 id="什么该写进-claude-md" tabindex="-1">什么该写进 CLAUDE.md <a class="header-anchor" href="#什么该写进-claude-md" aria-label="本节链接：什么该写进 CLAUDE.md">&ZeroWidthSpace;</a></h3>
<p>官方的判断标准：同样的错误 Claude 犯第二次时；code review 抓到 Claude 本该知道的事时；你发现自己在重复上次会话说过的纠正时。只写每个会话都该知道的事实，比如构建命令、约定、目录结构。多步骤流程或只对某块代码有用的内容，改成 skill 或者按路径生效的规则。</p>
<p>太长的 CLAUDE.md 会被「看漏」。官方建议狠狠删：Claude 不写也能做对的，就删掉，或者改成 hook。</p>
<h3 id="按路径生效的规则" tabindex="-1">按路径生效的规则 <a class="header-anchor" href="#按路径生效的规则" aria-label="本节链接：按路径生效的规则">&ZeroWidthSpace;</a></h3>
<p>在 <code>.claude/rules/</code> 下放 markdown 文件，加上 <code>paths</code> 就只在 Claude 碰到匹配文件时才加载：</p>
<div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">paths</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  -</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">src/api/**/*.ts</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold">#</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold"> API 开发规则</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> 所有接口都要做输入校验</span></span></code></pre>
</div><p>没有 <code>paths</code> 的规则在启动时就加载，优先级和 <code>.claude/CLAUDE.md</code> 相同。</p>
<h3 id="自动记忆" tabindex="-1">自动记忆 <a class="header-anchor" href="#自动记忆" aria-label="本节链接：自动记忆">&ZeroWidthSpace;</a></h3>
<p>Claude 会根据你的纠正和偏好自己记笔记，存在 <code>~/.claude/projects/&lt;project&gt;/memory/</code>，同一个 git 仓库的所有 worktree 共享一份。<code>MEMORY.md</code> 是索引，每次会话加载前 200 行或 25KB；具体条目放在单独的文件里，用到时才读。看到「Saved 2 memories」就是它在写。用 <code>/memory</code> 查看和开关，或者设 <code>CLAUDE_CODE_DISABLE_AUTO_MEMORY=1</code> 关闭。只存在本机，不跨机器同步。</p>
<h2 id="检查点与回退" tabindex="-1">检查点与回退 <a class="header-anchor" href="#检查点与回退" aria-label="本节链接：检查点与回退">&ZeroWidthSpace;</a></h2>
<p>每条开启新一轮的消息都会自动建一个检查点。按两下 <code>Esc</code>（输入框为空时）或 <code>/rewind</code> 打开回退菜单，选一条历史消息后可以：</p>
<ul>
<li><strong>Restore code and conversation</strong>：代码和对话都回到那时</li>
<li><strong>Restore conversation</strong>：只回退对话，代码保留现状</li>
<li><strong>Restore code</strong>：只回退代码，对话保留</li>
<li><strong>Summarize from here / up to here</strong>：把那之后 / 之前的对话压成摘要，相当于定向的 <code>/compact</code></li>
</ul>
<p>检查点随对话保存，关掉终端、之后 <code>/resume</code> 回来还能回退。所以可以大胆让 Claude 尝试有风险的方案，不行就退回去。</p>
<p>局限要记住：</p>
<ul>
<li>只有 Bash 改过的文件不受追踪（<code>rm</code>、<code>mv</code> 之类的副作用退不回来）。</li>
<li>子代理的编辑通常不会被恢复。</li>
<li>你在外面手动改的、其他会话改的，也不追踪。</li>
<li>符号链接和硬链接文件会被跳过，pnpm 硬链接进来的文件就属于这种。</li>
<li>检查点只管会话内的快速恢复，长期的版本历史还是靠 git。</li>
</ul>
<h2 id="skills-自定义命令" tabindex="-1">Skills：自定义命令 <a class="header-anchor" href="#skills-自定义命令" aria-label="本节链接：Skills：自定义命令">&ZeroWidthSpace;</a></h2>
<p>Skill 就是一个带 frontmatter 的 <code>SKILL.md</code>。旧的 <code>.claude/commands/xxx.md</code> 仍然有效，和 <code>.claude/skills/xxx/SKILL.md</code> 一样都会生成 <code>/xxx</code> 命令，但新写的推荐用 skill（可以带附属文件）。</p>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">位置</th>
<th style="text-align:left">路径</th>
<th style="text-align:left">生效范围</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">个人</td>
<td style="text-align:left"><code>~/.claude/skills/&lt;name&gt;/SKILL.md</code></td>
<td style="text-align:left">本机所有项目</td>
</tr>
<tr>
<td style="text-align:left">项目</td>
<td style="text-align:left"><code>.claude/skills/&lt;name&gt;/SKILL.md</code></td>
<td style="text-align:left">本仓库，提交后团队共享</td>
</tr>
<tr>
<td style="text-align:left">插件</td>
<td style="text-align:left"><code>&lt;plugin&gt;/skills/&lt;name&gt;/SKILL.md</code></td>
<td style="text-align:left">启用插件处，以 <code>/plugin-name:skill-name</code> 调用</td>
</tr>
</tbody>
</table>
<p>一个最小例子：</p>
<div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> fix-issue</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">description</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> 按编号修复 GitHub issue</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">disable-model-invocation</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> true</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">按我们的编码规范修复 GitHub issue $ARGUMENTS。</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">1.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> 读 issue 描述</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">2.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> 实现修复</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">3.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> 写测试</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">4.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> 提交</span></span></code></pre>
</div><p>运行 <code>/fix-issue 123</code>，<code>$ARGUMENTS</code> 会替换成 <code>123</code>。</p>
<p>常用 frontmatter 字段：</p>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">字段</th>
<th style="text-align:left">作用</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>description</code></td>
<td style="text-align:left">做什么、何时用。Claude 靠它判断要不要自动调用，所以把关键用途写在前面</td>
</tr>
<tr>
<td style="text-align:left"><code>disable-model-invocation</code></td>
<td style="text-align:left"><code>true</code> 时 Claude 不会自己调用，只能你手动 <code>/name</code></td>
</tr>
<tr>
<td style="text-align:left"><code>user-invocable</code></td>
<td style="text-align:left"><code>false</code> 时从 <code>/</code> 菜单隐藏，只给 Claude 用</td>
</tr>
<tr>
<td style="text-align:left"><code>allowed-tools</code></td>
<td style="text-align:left">本轮调用期间无需确认就能用的工具</td>
</tr>
<tr>
<td style="text-align:left"><code>argument-hint</code></td>
<td style="text-align:left">补全时提示参数，如 <code>[issue-number]</code></td>
</tr>
<tr>
<td style="text-align:left"><code>model</code> / <code>effort</code></td>
<td style="text-align:left">这个 skill 运行时用的模型 / 推理强度</td>
</tr>
<tr>
<td style="text-align:left"><code>context: fork</code></td>
<td style="text-align:left">在一个分叉出来的子代理里运行，配合 <code>agent</code> 指定子代理类型</td>
</tr>
<tr>
<td style="text-align:left"><code>paths</code></td>
<td style="text-align:left">只在处理匹配文件时自动加载</td>
</tr>
</tbody>
</table>
<p>参数和变量：<code>$ARGUMENTS</code> 是全部参数，<code>$0</code>、<code>$1</code>（即 <code>$ARGUMENTS[0]</code>）按位置取，<code>${CLAUDE_SKILL_DIR}</code> 是 skill 所在目录，<code>${CLAUDE_SESSION_ID}</code> 是会话 ID。</p>
<p>在 skill 里写 <code>!`gh pr diff`</code> 这样的语法，命令会在发给 Claude 之前先执行，输出替换进内容里，Claude 拿到的是真实数据。</p>
<p>在 skill 内容或提示词里写 <code>ultrathink</code>，会让那一轮做更深的推理。注意 <code>think</code>、<code>think hard</code> 这些早期流传的说法现在只是普通文字，不是关键词。</p>
<p>改了 skill 文件可以 <code>/reload-skills</code>，不用重启。</p>
<h2 id="子代理-subagents" tabindex="-1">子代理（Subagents） <a class="header-anchor" href="#子代理-subagents" aria-label="本节链接：子代理（Subagents）">&ZeroWidthSpace;</a></h2>
<p>子代理在独立的上下文窗口里工作，只把结论带回来，适合「读一大堆文件但只要结论」的活。内置的有：</p>
<ul>
<li><strong>Explore</strong>：只读，快速搜索和分析代码库，不加载 CLAUDE.md。</li>
<li><strong>Plan</strong>：计划模式下用来调研的只读代理。</li>
<li><strong>general-purpose</strong>：通用代理。</li>
</ul>
<p>自定义子代理是一个 markdown 文件，放在 <code>.claude/agents/</code>（项目）或 <code>~/.claude/agents/</code>（个人）：</p>
<div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> code-reviewer</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">description</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> 审查代码质量和最佳实践</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">tools</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> Read, Glob, Grep</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">model</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> sonnet</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">你是代码审查员。被调用时分析代码，给出关于质量、安全和最佳实践的具体建议。</span></span></code></pre>
</div><p>正文就是它的系统提示。只有 <code>name</code> 和 <code>description</code> 是必填，其他常用字段：<code>tools</code> / <code>disallowedTools</code>、<code>model</code>、<code>permissionMode</code>、<code>maxTurns</code>、<code>skills</code>（预加载 skill）、<code>memory</code>（给它开持久记忆）、<code>isolation: worktree</code>（在临时 worktree 里干活，没改动就自动清理）。</p>
<p>调用方式，从弱到强：</p>
<ol>
<li>自然语言：「用 code-reviewer 子代理看看我最近的改动」，由 Claude 决定是否委派。</li>
<li><code>@</code> 提及：输入 <code>@</code> 从补全里选，或手写 <code>@agent-code-reviewer</code>，保证一定用它。</li>
<li>整个会话都以它运行：<code>claude --agent code-reviewer</code>，或在 <code>.claude/settings.json</code> 里设 <code>&quot;agent&quot;: &quot;code-reviewer&quot;</code>。</li>
</ol>
<p>不用改配置也能用：直接说「用子代理调查一下认证系统怎么刷新 token」，调研就不会占你主对话的上下文。</p>
<h2 id="hooks-确定性的自动化" tabindex="-1">Hooks：确定性的自动化 <a class="header-anchor" href="#hooks-确定性的自动化" aria-label="本节链接：Hooks：确定性的自动化">&ZeroWidthSpace;</a></h2>
<p>CLAUDE.md 里写的是「建议」，Claude 可能不照做；hook 是 Claude Code 在特定时机一定会执行的命令。配置在 <code>settings.json</code> 的 <code>hooks</code> 下，分三层：事件 → matcher → 处理器。</p>
<p>官方的例子：拦截 <code>rm -rf</code>。</p>
<div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">hooks</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">PreToolUse</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">      {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">matcher</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">hooks</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">          {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">            "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">command</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">            "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">if</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash(rm *)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">            "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">command</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">            "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">args</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> []</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">          }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">        ]</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">      }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    ]</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span></code></pre>
</div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">#!/bin/bash</span></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># .claude/hooks/block-rm.sh</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">COMMAND</span><span style="--shiki-light:#999999;--shiki-dark:#666666">=$(</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">jq</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -r</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">.tool_input.command</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">if</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965"> echo</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">$COMMAND</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> |</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> grep</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -q</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">rm -rf</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> then</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  jq</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -n</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">{</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">    hookSpecificOutput: {</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">      hookEventName: "PreToolUse",</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">      permissionDecision: "deny",</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">      permissionDecisionReason: "Destructive command blocked by hook"</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">    }</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">  }</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">else</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">  exit</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91"> 0</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">fi</span></span></code></pre>
</div><p>hook 从 stdin 读到一段 JSON（工具名、参数等）。退出码的含义：<code>0</code> 成功，打印的 JSON 字段生效；<code>2</code> 是阻断性错误，在能阻断的事件上会拦下动作，stderr 作为原因；其他非零值是非阻断错误，动作照常进行。</p>
<p>常用事件：</p>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">事件</th>
<th style="text-align:left">触发时机</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>SessionStart</code> / <code>SessionEnd</code></td>
<td style="text-align:left">会话开始（含恢复）/ 结束</td>
</tr>
<tr>
<td style="text-align:left"><code>UserPromptSubmit</code></td>
<td style="text-align:left">提交消息后、Claude 处理之前</td>
</tr>
<tr>
<td style="text-align:left"><code>PreToolUse</code></td>
<td style="text-align:left">工具调用之前，可以阻断</td>
</tr>
<tr>
<td style="text-align:left"><code>PostToolUse</code> / <code>PostToolUseFailure</code></td>
<td style="text-align:left">工具调用成功 / 失败之后，常用来自动格式化、跑 lint</td>
</tr>
<tr>
<td style="text-align:left"><code>PermissionRequest</code></td>
<td style="text-align:left">需要权限决定时</td>
</tr>
<tr>
<td style="text-align:left"><code>Notification</code></td>
<td style="text-align:left">Claude Code 发通知时（比如等你确认），可以接系统通知</td>
</tr>
<tr>
<td style="text-align:left"><code>Stop</code></td>
<td style="text-align:left">Claude 回复结束时，可以用来「测试不过不许停」</td>
</tr>
<tr>
<td style="text-align:left"><code>SubagentStart</code> / <code>SubagentStop</code></td>
<td style="text-align:left">子代理启动 / 结束</td>
</tr>
<tr>
<td style="text-align:left"><code>PreCompact</code> / <code>PostCompact</code></td>
<td style="text-align:left">上下文压缩前后</td>
</tr>
</tbody>
</table>
<p>完整列表还有 <code>InstructionsLoaded</code>、<code>CwdChanged</code>、<code>FileChanged</code>、<code>WorktreeCreate</code>、<code>PreModelSwitch</code> 等，一共三十多个，见 <a href="https://code.claude.com/docs/en/hooks" target="_blank" rel="noreferrer">官方 hooks 文档</a>。除了 <code>command</code>，处理器还可以是 HTTP 请求、MCP 工具、一段提示词或一个代理。用 <code>/hooks</code> 查看当前配置，不想手写可以用 <code>/update-config</code>，比如「每次改完文件都跑 prettier」。</p>
<h2 id="mcp-接入外部工具" tabindex="-1">MCP：接入外部工具 <a class="header-anchor" href="#mcp-接入外部工具" aria-label="本节链接：MCP：接入外部工具">&ZeroWidthSpace;</a></h2>
<div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 远程 HTTP 服务器（推荐）</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> add</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --transport</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> http</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> notion</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> https://mcp.notion.com/mcp</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 本地 stdio 服务器，-- 之后是启动命令</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> add</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --env</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> API_KEY=xxx</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --transport</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> stdio</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> myserver</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> npx</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -y</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> @example/mcp-server</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 直接给 JSON</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> add-json</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> example</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">{"command":"npx","args":["-y","@example/mcp-server"]}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> list</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">          # 列出所有服务器及连接状态</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> get</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> notion</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">    # 查看详情</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> mcp</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> remove</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> notion</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"> # 删除</span></span></code></pre>
</div><p>作用范围用 <code>--scope</code>（<code>-s</code>）指定：</p>
<table tabindex="0">
<thead>
<tr>
<th style="text-align:left">范围</th>
<th style="text-align:left">生效</th>
<th style="text-align:left">共享</th>
<th style="text-align:left">存在</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left"><code>local</code>（默认）</td>
<td style="text-align:left">仅当前项目</td>
<td style="text-align:left">否</td>
<td style="text-align:left"><code>~/.claude.json</code></td>
</tr>
<tr>
<td style="text-align:left"><code>project</code></td>
<td style="text-align:left">仅当前项目</td>
<td style="text-align:left">是，提交到 git</td>
<td style="text-align:left">项目根目录的 <code>.mcp.json</code></td>
</tr>
<tr>
<td style="text-align:left"><code>user</code></td>
<td style="text-align:left">所有项目</td>
<td style="text-align:left">否</td>
<td style="text-align:left"><code>~/.claude.json</code></td>
</tr>
</tbody>
</table>
<p>会话里用 <code>/mcp</code> 看状态、做 OAuth 登录。MCP 服务器提供的 prompt 会变成斜杠命令，资源可以用 <code>@server:resource</code> 引用。</p>
<h2 id="非交互模式-放进脚本和-ci" tabindex="-1">非交互模式：放进脚本和 CI <a class="header-anchor" href="#非交互模式-放进脚本和-ci" aria-label="本节链接：非交互模式：放进脚本和 CI">&ZeroWidthSpace;</a></h2>
<div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 管道</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">cat</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> build-error.txt</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> |</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">简要解释这个构建错误的根因</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ></span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> output.txt</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># JSON 输出，用 jq 取结果</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">总结这个项目</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --output-format</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> json</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> |</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> jq</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -r</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">.result</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 预先放行工具</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">跑测试并修复失败</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --allowedTools</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Bash,Read,Edit</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 接着上一次对话</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">现在重点看数据库查询</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --continue</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"># 按会话 ID 续上</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">session_id</span><span style="--shiki-light:#999999;--shiki-dark:#666666">=$(</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">开始评审</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --output-format</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> json</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> |</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> jq</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -r</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">.session_id</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">claude</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -p</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">继续那次评审</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --resume</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">$session_id</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span></span></code></pre>
</div><ul>
<li><code>-p</code> 模式下需要审批的工具调用默认会被拒绝，所以要么 <code>--allowedTools</code> 预先放行，要么指定 <code>--permission-mode</code>（如 <code>acceptEdits</code>）。</li>
<li>想要稳定的结构化结果，用 <code>--json-schema</code>；想实时流式处理，用 <code>--output-format stream-json --verbose</code>。</li>
<li>加 <code>--bare</code> 可以跳过 hooks、插件、CLAUDE.md 等的自动发现，启动更快，结果也不受本机配置影响。</li>
<li><code>-p</code> 会跳过工作区信任对话框，只在你信任的目录里用。</li>
</ul>
<h2 id="技巧清单" tabindex="-1">技巧清单 <a class="header-anchor" href="#技巧清单" aria-label="本节链接：技巧清单">&ZeroWidthSpace;</a></h2>
<p>这些来自官方的 <a href="https://code.claude.com/docs/en/best-practices" target="_blank" rel="noreferrer">最佳实践</a> 文档，加上我自己用下来的体会。</p>
<h3 id="给-claude-一个能自己跑的检查" tabindex="-1">给 Claude 一个能自己跑的检查 <a class="header-anchor" href="#给-claude-一个能自己跑的检查" aria-label="本节链接：给 Claude 一个能自己跑的检查">&ZeroWidthSpace;</a></h3>
<p>我觉得这是最有用的一条。测试、构建退出码、lint、截图对比，任何能给出通过 / 不通过的东西都行。有了它，Claude 能自己反复改到通过；没有它，每个错误都要等你去发现。让它贴出证据：测试输出、跑了什么命令、返回了什么。想管得更严，可以用 <code>/goal</code> 设目标，或者用 <code>Stop</code> hook 在检查不过时不让它结束。</p>
<h3 id="先探索-再计划-再写代码" tabindex="-1">先探索，再计划，再写代码 <a class="header-anchor" href="#先探索-再计划-再写代码" aria-label="本节链接：先探索，再计划，再写代码">&ZeroWidthSpace;</a></h3>
<p>大改动前 <code>Shift+Tab</code> 切到计划模式或 <code>/plan</code>，让它先读代码、出方案，你审过再动手，免得解决了错误的问题。</p>
<h3 id="管好上下文" tabindex="-1">管好上下文 <a class="header-anchor" href="#管好上下文" aria-label="本节链接：管好上下文">&ZeroWidthSpace;</a></h3>
<p>上下文窗口是最根本的限制，塞得越满，效果越差。</p>
<ul>
<li>不相关的任务之间 <code>/clear</code>。</li>
<li><code>/compact 重点保留 X</code> 定向压缩；在 CLAUDE.md 里也可以写「压缩时始终保留改动过的文件列表和测试命令」。</li>
<li>只想确认个细节，用 <code>/btw</code>，问答不进历史。</li>
<li>调研交给子代理，结论回来，过程不占主上下文。</li>
<li><code>/context</code> 看看是谁占了地方。</li>
</ul>
<h3 id="及早纠偏" tabindex="-1">及早纠偏 <a class="header-anchor" href="#及早纠偏" aria-label="本节链接：及早纠偏">&ZeroWidthSpace;</a></h3>
<p>看到方向不对就按 <code>Esc</code> 打断，已做的工作不会丢。纠正两次还不对，就 <code>/clear</code>，把学到的东西写进一条更好的初始提示重新来，别在被失败尝试污染的上下文里死磕。</p>
<h3 id="失败了就回退" tabindex="-1">失败了就回退 <a class="header-anchor" href="#失败了就回退" aria-label="本节链接：失败了就回退">&ZeroWidthSpace;</a></h3>
<p>有检查点兜底，风险高一点的方案也可以让 Claude 先试，失败了 <code>Esc Esc</code> 退回去。Bash 命令造成的改动退不回来，这点要记着。</p>
<h3 id="并行" tabindex="-1">并行 <a class="header-anchor" href="#并行" aria-label="本节链接：并行">&ZeroWidthSpace;</a></h3>
<p><code>claude -w name</code> 开独立的 worktree 同时跑几个会话；<code>/fork</code> 复制一份到后台；<code>/batch</code> 把大规模迁移拆给一群子代理。</p>
<h3 id="零碎的小技巧" tabindex="-1">零碎的小技巧 <a class="header-anchor" href="#零碎的小技巧" aria-label="本节链接：零碎的小技巧">&ZeroWidthSpace;</a></h3>
<ul>
<li>写长提示词按 <code>Ctrl+G</code> 在编辑器里写。</li>
<li>打到一半想先问别的，<code>Ctrl+S</code> 暂存，问完再按一次取回。</li>
<li><code>Ctrl+C</code> 误清了草稿，按 <code>Up</code> 找回来。</li>
<li>命令跑得太久，<code>Ctrl+B</code> 丢到后台继续聊。</li>
<li>可以让 Claude 先采访你：「在动手之前，先就这个需求问我问题」。</li>
<li>新仓库第一次用：<code>/init</code> 生成 CLAUDE.md → <code>/memory</code> 补充 → <code>/permissions</code> 配好常用命令的放行，或者 <code>/fewer-permission-prompts</code> 自动生成。</li>
<li>提交前：<code>/diff</code> 看改动，<code>/code-review</code> 找 bug，<code>/simplify</code> 清理，<code>/security-review</code> 查安全问题。</li>
<li>常见的失败模式：一个会话里什么都干（「厨房水槽」式会话）；CLAUDE.md 写得过长；不给验证手段就信任输出；不设范围地「调查一下」，结果读了几百个文件。</li>
</ul>
<h2 id="参考" tabindex="-1">参考 <a class="header-anchor" href="#参考" aria-label="本节链接：参考">&ZeroWidthSpace;</a></h2>
<ul>
<li><a href="https://code.claude.com/docs/en/commands" target="_blank" rel="noreferrer">Commands 参考</a></li>
<li><a href="https://code.claude.com/docs/en/interactive-mode" target="_blank" rel="noreferrer">Interactive mode（快捷键）</a></li>
<li><a href="https://code.claude.com/docs/en/cli-reference" target="_blank" rel="noreferrer">CLI reference</a></li>
<li><a href="https://code.claude.com/docs/en/permission-modes" target="_blank" rel="noreferrer">Permission modes</a> 和 <a href="https://code.claude.com/docs/en/permissions" target="_blank" rel="noreferrer">Permissions</a></li>
<li><a href="https://code.claude.com/docs/en/memory" target="_blank" rel="noreferrer">Memory</a>、<a href="https://code.claude.com/docs/en/checkpointing" target="_blank" rel="noreferrer">Checkpointing</a></li>
<li><a href="https://code.claude.com/docs/en/skills" target="_blank" rel="noreferrer">Skills</a>、<a href="https://code.claude.com/docs/en/sub-agents" target="_blank" rel="noreferrer">Subagents</a>、<a href="https://code.claude.com/docs/en/hooks" target="_blank" rel="noreferrer">Hooks</a>、<a href="https://code.claude.com/docs/en/mcp" target="_blank" rel="noreferrer">MCP</a></li>
<li><a href="https://code.claude.com/docs/en/headless" target="_blank" rel="noreferrer">Headless（-p 模式）</a></li>
<li><a href="https://code.claude.com/docs/en/best-practices" target="_blank" rel="noreferrer">Best practices</a></li>
</ul>
]]></content:encoded>
</item>
<item>
<title>跌 10% 再涨 10%，韩指三倍做多为什么回不来</title>
<link>https://nyann.cc/posts/%E8%B7%8C%2010%20%E5%86%8D%E6%B6%A8%2010%EF%BC%8C%E9%9F%A9%E6%8C%87%E4%B8%89%E5%80%8D%E5%81%9A%E5%A4%9A%E4%B8%BA%E4%BB%80%E4%B9%88%E5%9B%9E%E4%B8%8D%E6%9D%A5</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E8%B7%8C%2010%20%E5%86%8D%E6%B6%A8%2010%EF%BC%8C%E9%9F%A9%E6%8C%87%E4%B8%89%E5%80%8D%E5%81%9A%E5%A4%9A%E4%B8%BA%E4%BB%80%E4%B9%88%E5%9B%9E%E4%B8%8D%E6%9D%A5</guid>
<pubDate>Sat, 24 Oct 2026 00:00:00 GMT</pubDate>
<description>跌 10% 再涨 10%，指数回不到原价，三倍做多离原价更远。从这个简单的算术出发，把每日重置、震荡磨损和持有成本拆开算一遍，再看什么行情下它真的是「三倍」。</description>
<category>投资</category>
<category>杠杆 ETF</category>
<category>韩国股市</category>
<content:encoded><![CDATA[<h1 id="跌-10-再涨-10-韩指三倍做多为什么回不来" tabindex="-1">跌 10% 再涨 10%，韩指三倍做多为什么回不来 <a class="header-anchor" href="#跌-10-再涨-10-韩指三倍做多为什么回不来" aria-label="本节链接：跌 10% 再涨 10%，韩指三倍做多为什么回不来">&ZeroWidthSpace;</a></h1>
<p>韩国股市这两年波动很大，不少人买过三倍做多韩国指数的产品，最常见的是美股上市的 KORU（Direxion 发行，跟踪 MSCI Korea 25/50 指数的每日三倍）。韩国本土的杠杆 ETF 只到两倍，想要三倍只能去美股买。</p>
<p>拿过一阵子的人多半碰到过这种情况：指数跌了又涨回来，涨跌的百分比差不多，三倍做多却回不到买入的价格，差得还不少。大家管这叫「磨损」。它来自两件事：百分比涨跌本身的算术，和三倍产品每天重置的规则。</p>
<h2 id="跌-10-再涨-10-回不到原价" tabindex="-1">跌 10% 再涨 10%，回不到原价 <a class="header-anchor" href="#跌-10-再涨-10-回不到原价" aria-label="本节链接：跌 10% 再涨 10%，回不到原价">&ZeroWidthSpace;</a></h2>
<p>先不管杠杆。一只指数从 100 跌 10%，到 90；再涨 10%，涨的是 90 的 10%，只回到 99。反过来先涨后跌也一样，110 跌 10% 是 99。百分比每次都以当前价格为基数，跌的时候基数大，涨的时候基数小，同样的百分比，金额对不上。</p>
<p>换成三倍做多，每天的涨跌都放大三倍：跌 30% 到 70，再涨 30% 到 91。</p>
<BaseShift /><p>指数少了 1%，三倍做多少了 9%。直觉上杠杆三倍、损失也该是三倍，可这个损失和涨跌幅的平方成正比：涨跌幅为 r 时，指数一跌一涨是 (1 − r)(1 + r) = 1 − r²，三倍做多是 (1 − 3r)(1 + 3r) = 1 − 9r²。</p>
<p>就算只看「指数自己的损失乘三」，也只有 3% 左右（0.99³ ≈ 0.970）。三倍做多多出来的那 6%，是杠杆产品独有的损耗。</p>
<h2 id="回本要涨多少" tabindex="-1">回本要涨多少 <a class="header-anchor" href="#回本要涨多少" aria-label="本节链接：回本要涨多少">&ZeroWidthSpace;</a></h2>
<p>把同一件事反过来问：跌了多少，要涨多少才能回本？</p>
<table tabindex="0">
<thead>
<tr>
<th>指数跌幅</th>
<th>指数回本要涨</th>
<th>三倍做多跌幅</th>
<th>三倍做多回本要涨</th>
<th>指数回本时，三倍做多的净值</th>
</tr>
</thead>
<tbody>
<tr>
<td>5%</td>
<td>5.3%</td>
<td>15%</td>
<td>17.6%</td>
<td>98.4</td>
</tr>
<tr>
<td>10%</td>
<td>11.1%</td>
<td>30%</td>
<td>42.9%</td>
<td>93.3</td>
</tr>
<tr>
<td>20%</td>
<td>25.0%</td>
<td>60%</td>
<td>150%</td>
<td>70.0</td>
</tr>
<tr>
<td>30%</td>
<td>42.9%</td>
<td>90%</td>
<td>900%</td>
<td>22.9</td>
</tr>
</tbody>
</table>
<p>前四列就是常见的「跌 50% 要涨 100%」，三倍做多一开始跌得更深，回本要涨的幅度也高得多。最后一列假设下跌和反弹各在一天里完成：指数涨回 100 的那天，三倍做多只拿到指数涨幅的三倍，离它回本要涨的幅度还差得远。</p>
<p>雪球上有一篇<a href="https://xueqiu.com/2678435970/378137658" target="_blank" rel="noreferrer">帖子</a>讲港股的两倍做多 SK 海力士，用的是同一套逻辑：海力士正股涨 12% 能回到前高 109 万韩元，两倍杠杆的人会以为涨 24% 就够，实际要涨 38% 左右。照帖子的数字拆开看：</p>
<ul>
<li>正股要涨 12% 回前高，说明它从前高跌了约 10.7%。</li>
<li>就算这 10.7% 是一天跌完的，两倍产品跌了 21.4%，回本也要涨 27.3%，比 24% 多。这一截是上面那张表里的算术。</li>
<li>实际要涨 38%，倒推两倍产品跌了约 27.5%，比一天跌完的 21.4% 又深了一截。差出来的部分是下跌途中来回震荡磨掉的，后面两节讲。</li>
</ul>
<h2 id="每天重置三倍-等于追涨杀跌" tabindex="-1">每天重置三倍，等于追涨杀跌 <a class="header-anchor" href="#每天重置三倍-等于追涨杀跌" aria-label="本节链接：每天重置三倍，等于追涨杀跌">&ZeroWidthSpace;</a></h2>
<p>三倍做多 ETF 的说明书里写的是每日收益的三倍：今天指数涨 1%，它涨 3%；今天跌 2%，它跌 6%。它没有承诺过一个月、一年的收益是指数的三倍。</p>
<p>为了让每天都正好是三倍，基金每天收盘前都要调仓，把敞口拉回净值的 3 倍。还是用跌 10% 再涨 10% 的例子：</p>
<div class="yn-diagram" v-pre><svg xmlns="http://www.w3.org/2000/svg" class="pele pele-flowchart" viewBox="0 0 197 548" width="197" height="548" style="max-width:100%;height:auto;--_bg:var(--pele-bg,#fff);--_fg:var(--pele-fg,#1f1f1f);--_m:var(--pele-muted,#6e6e6e);--_l:var(--pele-line,#1f1f1f);--_s:var(--pele-surface,#f3f3f3);--_a:var(--pele-surface-alt,#e6e6e6);--_b:var(--pele-border,#8a8a8a);--_c:var(--pele-accent,#5b7bd5);color:var(--_fg);--_r:var(--pele-radius,4px);--_fm:var(--pele-font-mono,monospace);font:16px sans-serif;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;font-family:var(--pele-font,sans-serif)" fill="var(--_fg)" role="graphics-document document" aria-roledescription="flowchart"><g class="pele-edges" fill="none" stroke="var(--_l)" stroke-linecap="round"><g class="pele-edge" data-id="L_A_B_0"><path d="M98.22,56L98.22,122"/><path class="pele-marker" d="M98.22,129L94.86,121L101.58,121Z" fill="var(--_l)" stroke="none"/></g><g class="pele-edge" data-id="L_B_C_0"><path d="M98.22,177L98.22,243"/><path class="pele-marker" d="M98.22,250L94.86,242L101.58,242Z" fill="var(--_l)" stroke="none"/></g><g class="pele-edge" data-id="L_C_D_0"><path d="M98.22,298L98.22,364"/><path class="pele-marker" d="M98.22,371L94.86,363L101.58,363Z" fill="var(--_l)" stroke="none"/></g><g class="pele-edge" data-id="L_D_E_0"><path d="M98.22,419L98.22,485"/><path class="pele-marker" d="M98.22,492L94.86,484L101.58,484Z" fill="var(--_l)" stroke="none"/></g></g><g class="pele-edge-labels" font-size="14"><g class="pele-edge-label" data-id="L_A_B_0"><rect x="60.21" y="78.5" width="76.03" height="21" rx="3" fill="var(--_bg)"/><text x="98.22" y="93.9" text-anchor="middle">指数 −10%</text></g><g class="pele-edge-label" data-id="L_B_C_0"><rect x="49.49" y="199.5" width="97.46" height="21" rx="3" fill="var(--_bg)"/><text x="98.22" y="214.9" text-anchor="middle">减仓：卖出 60</text></g><g class="pele-edge-label" data-id="L_C_D_0"><rect x="60.18" y="320.5" width="76.08" height="21" rx="3" fill="var(--_bg)"/><text x="98.22" y="335.9" text-anchor="middle">指数 +10%</text></g><g class="pele-edge-label" data-id="L_D_E_0"><rect x="49.49" y="441.5" width="97.46" height="21" rx="3" fill="var(--_bg)"/><text x="98.22" y="456.9" text-anchor="middle">加仓：买入 42</text></g></g><g class="pele-nodes"><g class="pele-node pele-shape-rect" data-id="A" transform="translate(98.22,32)"><rect x="-90.22" y="-24" width="180.45" height="48" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" x="0" y="5.6" text-anchor="middle">净值 100 · 敞口 300</text></g><g class="pele-node pele-shape-rect" data-id="B" transform="translate(98.22,153)"><rect x="-85.78" y="-24" width="171.55" height="48" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" x="0" y="5.6" text-anchor="middle">净值 70 · 敞口 270</text></g><g class="pele-node pele-shape-rect" data-id="C" transform="translate(98.22,274)"><rect x="-85.78" y="-24" width="171.55" height="48" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" x="0" y="5.6" text-anchor="middle">净值 70 · 敞口 210</text></g><g class="pele-node pele-shape-rect" data-id="D" transform="translate(98.22,395)"><rect x="-85.78" y="-24" width="171.55" height="48" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" x="0" y="5.6" text-anchor="middle">净值 91 · 敞口 231</text></g><g class="pele-node pele-shape-rect" data-id="E" transform="translate(98.22,516)"><rect x="-85.78" y="-24" width="171.55" height="48" fill="var(--_s)" stroke="var(--_b)" style="rx:var(--_r)"/><text class="pele-label" x="0" y="5.6" text-anchor="middle">净值 91 · 敞口 273</text></g></g></svg>
</div><p>第一天亏了 30，净值剩 70，敞口要降到 210，在跌了之后卖出 60。第二天指数涨回来，赚的是按 210 这个缩小了的敞口算的，只赚回 21。涨完再把敞口加回净值的三倍，在涨了之后买入 42。</p>
<p>跌了减仓、涨了加仓，每天都在低点卖、高点买。指数一跌一涨地来回拉锯，这种操作就重复一次，每次都丢一点。</p>
<h2 id="震荡市里-一点一点磨" tabindex="-1">震荡市里，一点一点磨 <a class="header-anchor" href="#震荡市里-一点一点磨" aria-label="本节链接：震荡市里，一点一点磨">&ZeroWidthSpace;</a></h2>
<p>两天 10% 是比较极端的例子。换一个更日常的：指数每天涨 3% 或跌 3%，交替 20 个交易日。下面的图默认就是这组数，也可以拖动滑块换个涨跌幅和天数，或者切到两倍看看。</p>
<ChopPlayer /><p>按默认的 ±3%、20 天：每涨跌一个来回，指数是 1.03 × 0.97 = 0.9991，少 0.09%；三倍做多是 1.09 × 0.91 = 0.9919，少 0.81%，正好是 9 倍。十个来回乘下来，指数到 99.1，三倍做多到 92.2。</p>
<p>三倍那条线上下摆得很凶，但每隔两天回到的位置都比上一次低一点。来回的次数越多、每次摆得越大，它掉得越快。</p>
<h2 id="单边行情里-它反而比三倍还多" tabindex="-1">单边行情里，它反而比三倍还多 <a class="header-anchor" href="#单边行情里-它反而比三倍还多" aria-label="本节链接：单边行情里，它反而比三倍还多">&ZeroWidthSpace;</a></h2>
<p>磨损只出现在来回涨跌的时候。指数每天稳定涨 1%，连涨 20 天：</p>
<figure class="lev-fig">
<svg viewBox="0 0 680 300" role="img" aria-label="单边上涨 20 天，指数涨 22%，三倍涨 80.6%，比简单乘三的 66% 还多">
<line class="grid" x1="56" y1="236" x2="570" y2="236"/><text class="tick" x="48" y="240" text-anchor="end">100</text>
<line class="grid" x1="56" y1="176" x2="570" y2="176"/><text class="tick" x="48" y="180" text-anchor="end">125</text>
<line class="grid" x1="56" y1="116" x2="570" y2="116"/><text class="tick" x="48" y="120" text-anchor="end">150</text>
<line class="grid" x1="56" y1="56" x2="570" y2="56"/><text class="tick" x="48" y="60" text-anchor="end">175</text>
<line class="base" x1="56" y1="236" x2="570" y2="236"/>
<text class="tick" x="56" y="278" text-anchor="middle">0</text>
<text class="tick" x="184.5" y="278" text-anchor="middle">5</text>
<text class="tick" x="313" y="278" text-anchor="middle">10</text>
<text class="tick" x="441.5" y="278" text-anchor="middle">15</text>
<text class="tick" x="570" y="278" text-anchor="middle">20</text>
<text class="tick" x="570" y="294" text-anchor="end">交易日</text>
<path class="s1" d="M56 236L81.7 233.6L107.4 231.2L133.1 228.7L158.8 226.3L184.5 223.8L210.2 221.2L235.9 218.7L261.6 216.1L287.3 213.5L313 210.9L338.7 208.2L364.4 205.6L390.1 202.9L415.8 200.1L441.5 197.4L467.2 194.6L492.9 191.8L518.6 188.9L544.3 186.1L570 183.2"/>
<text class="lab s1" x="578" y="187.2">指数 122</text>
<path class="s3" d="M56 236L81.7 228.8L107.4 221.5L133.1 214.2L158.8 206.8L184.5 199.3L210.2 191.7L235.9 184.1L261.6 176.3L287.3 168.5L313 160.7L338.7 152.7L364.4 144.7L390.1 136.6L415.8 128.4L441.5 120.1L467.2 111.7L492.9 103.3L518.6 94.8L544.3 86.2L570 77.5"/>
<text class="lab s3" x="578" y="85.5">涨幅×3 = 166</text>
<path class="s2" d="M56 236L81.7 228.8L107.4 221.4L133.1 213.7L158.8 205.9L184.5 197.8L210.2 189.4L235.9 180.8L261.6 172L287.3 162.9L313 153.5L338.7 143.8L364.4 133.8L390.1 123.6L415.8 113L441.5 102.1L467.2 90.9L492.9 79.3L518.6 67.4L544.3 55.2L570 42.5"/>
<text class="lab s2" x="578" y="46.5">三倍 181</text>
</svg>
<figcaption>指数涨 22%，三倍做多涨了 80.6%，比「涨幅乘三」的 66% 多出一截</figcaption>
</figure>
<p>这时候每日重置变成了好事：每天都拿前一天赚到的钱加仓，复利滚起来，最后比简单乘三还多。连续阴跌的时候，它也会比「跌幅乘三」跌得少一点，因为它每天都在减仓。</p>
<p>所以三倍做多拿久了能赚多少，要看中间怎么走：趋势越干脆，它越占便宜；来回拉锯越多，它越吃亏。</p>
<h2 id="把磨损算成一个数" tabindex="-1">把磨损算成一个数 <a class="header-anchor" href="#把磨损算成一个数" aria-label="本节链接：把磨损算成一个数">&ZeroWidthSpace;</a></h2>
<p>前面一个来回少 9r²，这是两天的账。拉长到一年，涨跌幅 r 换成指数的年化波动率 σ，三倍做多相对「指数涨跌的三次方」大约要打一个折扣：</p>
<blockquote>
<p>三倍做多的净值 ≈（指数终值 / 起点）³ × e<sup>−3σ²</sup></p>
</blockquote>
<p>（推导：对每天的收益 r 取对数再展开，三倍做多是 ln(1 + 3r) ≈ 3r − 9r²/2，指数净值的三次方是 3 · ln(1 + r) ≈ 3r − 3r²/2，每天差 3r²，一年加起来是 3σ²。）</p>
<p>这个折扣只和波动率有关，和指数往哪个方向走无关。代几个数进去：</p>
<table tabindex="0">
<thead>
<tr>
<th>指数年化波动率 σ</th>
<th>一年的波动损耗</th>
<th>指数至少要涨多少，三倍才不亏</th>
</tr>
</thead>
<tbody>
<tr>
<td>10%</td>
<td>−3.0%</td>
<td>+1.0%</td>
</tr>
<tr>
<td>15%</td>
<td>−6.5%</td>
<td>+2.3%</td>
</tr>
<tr>
<td>20%</td>
<td>−11.3%</td>
<td>+4.1%</td>
</tr>
<tr>
<td>25%</td>
<td>−17.1%</td>
<td>+6.4%</td>
</tr>
<tr>
<td>30%</td>
<td>−23.7%</td>
<td>+9.4%</td>
</tr>
<tr>
<td>40%</td>
<td>−38.1%</td>
<td>+17.4%</td>
</tr>
</tbody>
</table>
<p>损耗按 σ 的平方涨：波动从 20% 涨到 30%，损耗翻了一倍还多。韩国指数平常的年化波动大约在 15% 到 25% 之间，碰上半导体周期急转、或者 2024 年底那种政局动荡的时候，阶段性波动会冲到 30% 以上。KORU 跟踪的是美元计价的指数，韩元兑美元的汇率波动也叠在里面，所以它的实际波动率比只看 KOSPI 还要高一些。</p>
<p>最后一列是盈亏平衡点。波动率 25% 的年份，指数涨了 6%，拿三倍做多的人才刚好回本。</p>
<figure class="lev-fig">
<svg viewBox="0 0 680 300" role="img" aria-label="一年下来指数涨跌与三倍做多涨跌的对应关系，波动越大曲线越往下压">
<line class="grid" x1="56" y1="260" x2="570" y2="260"/><text class="tick" x="48" y="264" text-anchor="end">-80%</text>
<line class="grid" x1="56" y1="220" x2="570" y2="220"/><text class="tick" x="48" y="224" text-anchor="end">-40%</text>
<line class="grid" x1="56" y1="180" x2="570" y2="180"/><text class="tick" x="48" y="184" text-anchor="end">0%</text>
<line class="grid" x1="56" y1="140" x2="570" y2="140"/><text class="tick" x="48" y="144" text-anchor="end">+40%</text>
<line class="grid" x1="56" y1="100" x2="570" y2="100"/><text class="tick" x="48" y="104" text-anchor="end">+80%</text>
<line class="grid" x1="56" y1="60" x2="570" y2="60"/><text class="tick" x="48" y="64" text-anchor="end">+120%</text>
<line class="grid" x1="56" y1="20" x2="570" y2="20"/><text class="tick" x="48" y="24" text-anchor="end">+160%</text>
<line class="base" x1="56" y1="180" x2="570" y2="180"/>
<text class="tick" x="56" y="278" text-anchor="middle">-30%</text>
<text class="tick" x="129.4" y="278" text-anchor="middle">-20%</text>
<text class="tick" x="202.9" y="278" text-anchor="middle">-10%</text>
<text class="tick" x="276.3" y="278" text-anchor="middle">0%</text>
<text class="tick" x="349.7" y="278" text-anchor="middle">+10%</text>
<text class="tick" x="423.1" y="278" text-anchor="middle">+20%</text>
<text class="tick" x="496.6" y="278" text-anchor="middle">+30%</text>
<text class="tick" x="570" y="278" text-anchor="middle">+40%</text>
<text class="tick" x="570" y="294" text-anchor="end">指数全年涨跌</text>
<path class="s3" d="M80.2 260L570 60"/>
<text class="lab s3" x="578" y="76">涨幅×3</text>
<path class="s1" d="M56 247.9L63.3 246.5L70.7 245.1L78 243.6L85.4 242.1L92.7 240.6L100.1 239L107.4 237.3L114.7 235.6L122.1 233.9L129.4 232.1L136.8 230.3L144.1 228.5L151.5 226.6L158.8 224.6L166.1 222.6L173.5 220.5L180.8 218.4L188.2 216.3L195.5 214.1L202.9 211.9L210.2 209.6L217.5 207.2L224.9 204.8L232.2 202.4L239.6 199.9L246.9 197.3L254.3 194.7L261.6 192L268.9 189.3L276.3 186.5L283.6 183.7L291 180.8L298.3 177.9L305.7 174.9L313 171.8L320.3 168.7L327.7 165.5L335 162.3L342.4 159L349.7 155.6L357.1 152.2L364.4 148.7L371.7 145.1L379.1 141.5L386.4 137.8L393.8 134.1L401.1 130.3L408.5 126.4L415.8 122.5L423.1 118.5L430.5 114.4L437.8 110.3L445.2 106.1L452.5 101.8L459.9 97.4L467.2 93L474.5 88.5L481.9 84L489.2 79.3L496.6 74.6L503.9 69.9L511.3 65L518.6 60.1L525.9 55.1L533.3 50L540.6 44.9L548 39.6L555.3 34.3L562.7 29L570 23.5"/>
<text class="lab s1" x="578" y="27.5">σ = 15%</text>
<path class="s2" d="M56 251.6L63.3 250.3L70.7 249.1L78 247.7L85.4 246.4L92.7 245L100.1 243.6L107.4 242.2L114.7 240.7L122.1 239.1L129.4 237.6L136.8 235.9L144.1 234.3L151.5 232.6L158.8 230.9L166.1 229.1L173.5 227.3L180.8 225.4L188.2 223.5L195.5 221.6L202.9 219.6L210.2 217.5L217.5 215.4L224.9 213.3L232.2 211.1L239.6 208.9L246.9 206.7L254.3 204.3L261.6 202L268.9 199.6L276.3 197.1L283.6 194.6L291 192L298.3 189.4L305.7 186.7L313 184L320.3 181.3L327.7 178.4L335 175.6L342.4 172.6L349.7 169.7L357.1 166.6L364.4 163.5L371.7 160.4L379.1 157.2L386.4 153.9L393.8 150.6L401.1 147.2L408.5 143.8L415.8 140.3L423.1 136.7L430.5 133.1L437.8 129.5L445.2 125.7L452.5 121.9L459.9 118.1L467.2 114.2L474.5 110.2L481.9 106.1L489.2 102L496.6 97.9L503.9 93.6L511.3 89.3L518.6 85L525.9 80.5L533.3 76L540.6 71.5L548 66.8L555.3 62.1L562.7 57.4L570 52.5"/>
<text class="lab s2" x="578" y="50.5">σ = 25%</text>
<path class="s4" d="M56 256.2L63.3 255.2L70.7 254.2L78 253.1L85.4 251.9L92.7 250.8L100.1 249.6L107.4 248.4L114.7 247.1L122.1 245.9L129.4 244.5L136.8 243.2L144.1 241.8L151.5 240.4L158.8 239L166.1 237.5L173.5 236L180.8 234.4L188.2 232.8L195.5 231.2L202.9 229.5L210.2 227.8L217.5 226.1L224.9 224.3L232.2 222.5L239.6 220.6L246.9 218.7L254.3 216.8L261.6 214.8L268.9 212.8L276.3 210.8L283.6 208.7L291 206.5L298.3 204.3L305.7 202.1L313 199.8L320.3 197.5L327.7 195.2L335 192.8L342.4 190.3L349.7 187.8L357.1 185.3L364.4 182.7L371.7 180.1L379.1 177.4L386.4 174.7L393.8 171.9L401.1 169.1L408.5 166.2L415.8 163.3L423.1 160.3L430.5 157.3L437.8 154.3L445.2 151.1L452.5 148L459.9 144.8L467.2 141.5L474.5 138.2L481.9 134.8L489.2 131.3L496.6 127.9L503.9 124.3L511.3 120.7L518.6 117.1L525.9 113.4L533.3 109.6L540.6 105.8L548 101.9L555.3 98L562.7 94L570 90"/>
<text class="lab s4" x="578" y="94">σ = 35%</text>
</svg>
<figcaption>横轴是指数一年的涨跌，纵轴是三倍做多一年的涨跌（只算波动损耗，没算费用）。虚线是「涨幅乘三」</figcaption>
</figure>
<p>这张图里能看出几件事：</p>
<ol>
<li>曲线是往上弯的。指数涨得越多，三倍做多离「涨幅乘三」越近，涨到 +40% 这种大年份会反超虚线，这是上一节说的复利。</li>
<li>波动越大，整条曲线越往下压。同样是指数全年 +10%，σ = 15% 时三倍做多大约 +24%，σ = 35% 时反而亏 8% 左右。</li>
<li>指数持平的时候，三倍做多一定是亏的，亏多少看那一年有多颠。σ = 25% 时是 −17%。</li>
</ol>
<p>我用蒙特卡洛模拟核对过这个近似：σ = 20%、跑 4000 条一年的随机路径，三倍做多净值和「指数涨跌的三次方」之比的中位数是 0.887，公式给的是 e<sup>−0.12</sup> = 0.887，对得上。</p>
<h2 id="波动之外-还有持有成本" tabindex="-1">波动之外，还有持有成本 <a class="header-anchor" href="#波动之外-还有持有成本" aria-label="本节链接：波动之外，还有持有成本">&ZeroWidthSpace;</a></h2>
<p>上面只算了结构性的磨损，真买这个产品还要再扣两笔：</p>
<ul>
<li>管理费。三倍杠杆 ETF 的费率普遍在每年 1% 左右，比普通指数 ETF 贵一个数量级，每天从净值里扣。</li>
<li>融资成本。三倍敞口里有两倍是借来的，基金一般用掉期（swap）实现，对手方会按短期利率收融资费。如果美元短端利率在 4% 上下，这一项一年就是 2 × 4% ≈ 8% 左右的拖累。利率低的年份这项几乎可以忽略，利率高的年份它比管理费还重。</li>
</ul>
<p>这两项和波动无关，按时间均匀地扣，指数不动它也在扣。把它们和波动损耗加在一起，一个波动率 25% 的平盘年份，三倍做多亏掉两成以上并不奇怪。</p>
<blockquote>
<p>本篇只是拆解产品结构、讲解磨损，不构成投资建议。</p>
</blockquote>
]]></content:encoded>
</item>
<item>
<title>用 Eval 系统地测试 Agent Skill</title>
<link>https://nyann.cc/posts/%E7%94%A8%20Eval%20%E7%B3%BB%E7%BB%9F%E5%9C%B0%E6%B5%8B%E8%AF%95%20Agent%20Skill</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E7%94%A8%20Eval%20%E7%B3%BB%E7%BB%9F%E5%9C%B0%E6%B5%8B%E8%AF%95%20Agent%20Skill</guid>
<pubDate>Wed, 21 Oct 2026 00:00:00 GMT</pubDate>
<description>改 skill 时很难分清是改好了还是只是改变了行为。这篇讲怎么用 codex exec 记录运行轨迹，再配上确定性检查和基于评分细则的打分，把 skill 变成能测试、能打分、能持续改进的东西。</description>
<category>翻译</category>
<category>AI</category>
<category>Agent</category>
<category>Codex</category>
<category>Skill</category>
<content:encoded><![CDATA[<h1 id="用-eval-系统地测试-agent-skill" tabindex="-1">用 Eval 系统地测试 Agent Skill <a class="header-anchor" href="#用-eval-系统地测试-agent-skill" aria-label="本节链接：用 Eval 系统地测试 Agent Skill">&ZeroWidthSpace;</a></h1>
<p><img src="https://nyann.cc/posts/testing-agent-skills-systematically-with-evals/eval-skills.webp" alt="用 Eval 系统地测试 Agent Skill" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>When you’re iterating on a skill for an agent like Codex, it’s hard to tell whether you’re actually improving it or just changing its behavior. One version feels faster, another seems more reliable, and then a regression slips in: the skill doesn’t trigger, it skips a required step, or it leaves extra files behind.</p>
</div>
<p>给 Codex 这类 Agent 反复改一个 skill 的时候，你很难说清自己到底是在改进它，还是只是让它的行为变了个样。这一版感觉快了点，那一版好像更稳了，然后回归（regression）就悄悄混进来：skill 没触发，跳过了必须做的某一步，或者留下了一堆多余的文件。</p>
<div class="yn-en" lang="en">
<p>At its core, a skill is an <a href="https://developers.openai.com/codex/build-skills" target="_blank" rel="noreferrer">organized collection of prompts and instructions</a> for an LLM. The most reliable way to improve a skill over time is to evaluate it the same way you would <a href="https://platform.openai.com/docs/guides/evaluation-best-practices" target="_blank" rel="noreferrer">any other prompt for LLM applications</a>.</p>
</div>
<p>说到底，skill 就是写给 LLM 的一套<a href="https://developers.openai.com/codex/build-skills" target="_blank" rel="noreferrer">整理好的提示词和指令</a>。想让它越改越好，最靠谱的办法就是像评估 <a href="https://platform.openai.com/docs/guides/evaluation-best-practices" target="_blank" rel="noreferrer">LLM 应用里的其他提示词</a>那样去评估它。</p>
<div class="yn-en" lang="en">
<p><em>Evals</em> (short for <em>evaluations</em>) check whether a model’s output, and the steps it took to produce it, match what you intended. Instead of asking “does this feel better?” (or relying on vibes), evals let you ask concrete questions like:</p>
</div>
<p><em>Eval</em>（<em>evaluation</em> 的简称，评测）检查的是模型的输出，以及它得出这个输出走过的步骤，是不是符合你的本意。有了 eval，你不用再问「这样感觉是不是好一点？」（或者全凭感觉），而是可以问一些具体的问题，比如：</p>
<ul>
<li><span class="yn-en" lang="en">Did the agent invoke the skill?</span>Agent 调用这个 skill 了吗？</li>
<li><span class="yn-en" lang="en">Did it run the expected commands?</span>它跑了该跑的命令吗？</li>
<li><span class="yn-en" lang="en">Did it produce outputs that follow the conventions you care about?</span>它的产出符合你在意的那些约定吗？</li>
</ul>
<div class="yn-en" lang="en">
<p>Concretely, an eval is: a prompt → a captured run (trace + artifacts) → a small set of checks → a score you can compare over time.</p>
</div>
<p>具体来说，一个 eval 就是：一条提示词 → 一次完整记录下来的运行，包括轨迹（trace）和产物→ 一小组检查 → 一个可以跨时间比较的分数。</p>
<div class="yn-en" lang="en">
<p>In practice, evals for agent skills look a lot like lightweight end-to-end tests: you run the agent, record what happened, and score the result against a small set of rules.</p>
</div>
<p>实际做起来，Agent skill 的 eval 很像轻量的端到端测试：把 Agent 跑一遍，记下发生了什么，再按一小组规则给结果打分。</p>
<div class="yn-en" lang="en">
<p>This post walks through a clear pattern for doing that with Codex, starting from defining success, then adding deterministic checks and rubric-based grading so improvements (and regressions) are clear.</p>
</div>
<p>这篇文章用 Codex 走一遍这套做法：先定义什么叫成功，再加上确定性检查和基于评分细则（rubric）的打分，让改进（和回归）都一目了然。</p>
<h2 id="_1-define-success-before-you-write-the-skill1-写-skill-之前-先定义成功" tabindex="-1"><span class="yn-en ignore-header" lang="en">1. Define success before you write the skill</span>1. 写 skill 之前，先定义成功 <a class="header-anchor" href="#_1-define-success-before-you-write-the-skill1-写-skill-之前-先定义成功" aria-label="本节链接：1. 写 skill 之前，先定义成功">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Before writing the skill itself, write down what “success” means in terms you can actually measure. A useful way to think about this is to split your checks into a few categories:</p>
</div>
<p>动手写 skill 之前，先用真正能衡量的说法把「成功」写下来。一个好用的思路是把检查分成几类：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Outcome goals:</strong> Did the task complete? Does the app run?</span><strong>结果目标：</strong> 任务完成了吗？应用能跑起来吗？</li>
<li><span class="yn-en" lang="en"><strong>Process goals:</strong> Did Codex invoke the skill and follow the tools and steps you intended?</span><strong>过程目标：</strong> Codex 调用这个 skill 了吗？用的工具、走的步骤是不是你想要的？</li>
<li><span class="yn-en" lang="en"><strong>Style goals:</strong> Does the output follow the conventions you asked for?</span><strong>风格目标：</strong> 产出符合你要求的约定吗？</li>
<li><span class="yn-en" lang="en"><strong>Efficiency goals:</strong> Did it get there without thrashing (for example, unnecessary commands or excessive token use)?</span><strong>效率目标：</strong> 它是不是没有来回折腾就做到了（比如跑了多余的命令，或者用掉了过多的 token）？</li>
</ul>
<div class="yn-en" lang="en">
<p>Keep this list small and focused on must-pass checks. The goal isn’t to encode every preference up front, but to capture the behaviors you care about most.</p>
</div>
<p>这份清单要短，只放必须通过的检查。目的不是一开始就把所有偏好都写进去，而是抓住你最在意的那些行为。</p>
<div class="yn-en" lang="en">
<p>In this post, for example, the guide evaluates a skill that sets up a demo app. Some checks are concrete. Did it run <code>npm install</code>? Did it create <code>package.json</code>? The guide pairs those with a structured style rubric to evaluate conventions and layout.</p>
</div>
<p>拿这篇文章来说，要评测的是一个搭建演示应用的 skill。有些检查很具体：它跑了 <code>npm install</code> 吗？它创建了 <code>package.json</code> 吗？除了这些，还配了一份结构化的风格评分细则，用来评约定和目录布局。</p>
<div class="yn-en" lang="en">
<p>This mix is intentional. You want fast, targeted signals that surface specific regressions early, rather than a single pass/fail verdict at the end.</p>
</div>
<p>这样搭配是故意的。你要的是快速、有针对性的信号，能早早暴露出具体是哪里回归了，而不是到最后才给一个笼统的通过/不通过。</p>
<h2 id="_2-create-the-skill2-创建-skill" tabindex="-1"><span class="yn-en ignore-header" lang="en">2. Create the skill</span>2. 创建 skill <a class="header-anchor" href="#_2-create-the-skill2-创建-skill" aria-label="本节链接：2. 创建 skill">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>A Codex skill is a directory with a <code>SKILL.md</code> file that includes YAML front matter (<code>name</code>, <code>description</code>), followed by the Markdown instructions that define the skill’s behavior and optional resources and scripts. The name and description matter more than they might seem. They’re the primary signals Codex uses to decide <em>whether</em> to invoke the skill at all, and <em>when</em> to inject the rest of <code>SKILL.md</code> into the agent’s context. If these are vague or overloaded, the skill won’t trigger reliably.</p>
</div>
<p>一个 Codex skill 就是一个目录，里面有一个 <code>SKILL.md</code> 文件：开头是 YAML front matter（<code>name</code>、<code>description</code>），后面是定义 skill 行为的 Markdown 指令，另外还可以带一些资源和脚本。name 和 description 比看上去要重要得多。Codex 主要就靠它们来决定<em>要不要</em>调用这个 skill，以及<em>什么时候</em>把 <code>SKILL.md</code> 的其余部分注入 Agent 的上下文。这两项写得含糊，或者塞了太多东西，skill 就没法稳定触发。</p>
<div class="yn-en" lang="en">
<p>The fastest way to get started is to use Codex’s built-in skill creator (<a href="https://github.com/openai/skills/tree/main/skills/.system/skill-creator" target="_blank" rel="noreferrer">which itself is also a skill</a>). It walks you through:</p>
</div>
<p>上手最快的办法是用 Codex 内置的 skill creator（<a href="https://github.com/openai/skills/tree/main/skills/.system/skill-creator" target="_blank" rel="noreferrer">它本身也是一个 skill</a>）。它会一步步带你走：</p>
<div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">$skill</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">-creator</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>The creator asks you what the skill does, when it should trigger, and whether it’s instruction-only or script-backed (instruction-only is the default recommendation). To learn more about creating a skill, <a href="https://developers.openai.com/codex/build-skills#create-a-skill" target="_blank" rel="noreferrer">check out the documentation</a>.</p>
</div>
<p>它会问你这个 skill 做什么、什么时候该触发、是只有指令还是带脚本（默认推荐只有指令）。想多了解怎么创建 skill，可以<a href="https://developers.openai.com/codex/build-skills#create-a-skill" target="_blank" rel="noreferrer">看看文档</a>。</p>
<h3 id="a-sample-skill一个示例-skill" tabindex="-1"><span class="yn-en ignore-header" lang="en">A sample skill</span>一个示例 skill <a class="header-anchor" href="#a-sample-skill一个示例-skill" aria-label="本节链接：一个示例 skill">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>This post uses an intentionally minimal example: a skill that sets up a small React demo app in a predictable, repeatable way.</p>
</div>
<p>这篇文章特意用了一个极简的例子：一个用可预测、可重复的方式搭一个小型 React 演示应用的 skill。</p>
<div class="yn-en" lang="en">
<p>This skill will:</p>
</div>
<p>这个 skill 会：</p>
<ul>
<li><span class="yn-en" lang="en">Scaffold a project using Vite’s React + TypeScript template</span>用 Vite 的 React + TypeScript 模板搭出项目骨架</li>
<li><span class="yn-en" lang="en">Configure Tailwind CSS using the official Vite plugin approach</span>按官方的 Vite 插件方式配置 Tailwind CSS</li>
<li><span class="yn-en" lang="en">Enforce a minimal, consistent file structure</span>强制使用一套最小、一致的文件结构</li>
<li><span class="yn-en" lang="en">Define a clear “definition of done” so success is straightforward to evaluate</span>定一个清楚的「完成标准」，这样成功与否很好判断</li>
</ul>
<div class="yn-en" lang="en">
<p>Below is a compact draft you can paste either into:</p>
</div>
<p>下面是一份精简的草稿，你可以把它粘贴到以下任一位置：</p>
<ul>
<li><span class="yn-en" lang="en"><code>.codex/skills/setup-demo-app/SKILL.md</code> (repo-scoped), or</span><code>.codex/skills/setup-demo-app/SKILL.md</code>（仓库级），或者</li>
<li><span class="yn-en" lang="en"><code>~/.codex/skills/setup-demo-app/SKILL.md</code> (user-scoped).</span><code>~/.codex/skills/setup-demo-app/SKILL.md</code>（用户级）。</li>
</ul>
<div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> setup-demo-app</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">description</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">---</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold"> When to use this</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">Use when you need a fresh demo app for quick UI experiments or reproductions.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold"> What to build</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">Create a Vite React TypeScript app and configure Tailwind. Keep it minimal.</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">Project structure after setup:</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> src/</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> main.tsx (entry)</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> App.tsx (root UI)</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> components/</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">    -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Header.tsx</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">    -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Card.tsx</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> index.css (Tailwind import)</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> index.html</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> package.json</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">Style requirements:</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> TypeScript components</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Functional components only</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Tailwind classes for styling (no CSS modules)</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> No extra UI libraries</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold"> Steps</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">1.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Scaffold with Vite using the React TS template:</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">   npm create vite@latest demo-app -- --template react-ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">2.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Install dependencies:</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">   cd demo-app</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">   npm install</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">3.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Install and configure Tailwind using the Vite plugin.</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> npm install tailwindcss @tailwindcss/vite</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Add the tailwind plugin to vite.config.ts</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> In src/index.css, replace contents with:</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">     @import "tailwindcss";</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">4.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Implement the minimal UI:</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Header: app title and short subtitle</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> Card: reusable card container</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">   -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> App: render Header + 2 Cards with placeholder text</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold"> Definition of done</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> npm run dev starts successfully</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> package.json exists</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> src/components/Header.tsx and src/components/Card.tsx exist</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This sample skill takes an opinionated stance on purpose. Without clear constraints, there’s nothing concrete to evaluate.</p>
</div>
<p>这个示例 skill 故意把话说得很死。没有明确的约束，就没有什么具体的东西可评。</p>
<h2 id="_3-manually-trigger-the-skill-to-expose-hidden-assumptions3-手动触发-skill-把隐藏的假设逼出来" tabindex="-1"><span class="yn-en ignore-header" lang="en">3. Manually trigger the skill to expose hidden assumptions</span>3. 手动触发 skill，把隐藏的假设逼出来 <a class="header-anchor" href="#_3-manually-trigger-the-skill-to-expose-hidden-assumptions3-手动触发-skill-把隐藏的假设逼出来" aria-label="本节链接：3. 手动触发 skill，把隐藏的假设逼出来">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Because skill invocation depends so much on the <em>name</em> and <em>description</em> in <code>SKILL.md</code>, the first thing to check is whether the <code>setup-demo-app</code> skill triggers when you expect it to.</p>
</div>
<p>skill 会不会被调用，很大程度上取决于 <code>SKILL.md</code> 里的 <em>name</em> 和 <em>description</em>，所以第一件要查的事，就是 <code>setup-demo-app</code> 这个 skill 有没有在你预期的时候触发。</p>
<div class="yn-en" lang="en">
<p>Early on, explicitly activate the skill, either via the <code>/skills</code> slash command or by referencing it with the <code>$</code> prefix, in a real repository or a scratch directory, and watch where it breaks. This is where you surface the misses: cases where the skill doesn’t trigger at all, triggers too eagerly, or runs but deviates from the intended steps.</p>
</div>
<p>早期阶段，在一个真实仓库或者临时目录里显式地启用这个 skill，可以用 <code>/skills</code> 斜杠命令，也可以用 <code>$</code> 前缀引用它，然后看它在哪儿出问题。漏掉的情况就是在这一步暴露出来的：skill 压根没触发、触发得太积极，或者跑了但偏离了预定的步骤。</p>
<div class="yn-en" lang="en">
<p>At this stage, you’re not optimizing for speed or polish. You’re looking for hidden assumptions the skill is making, such as:</p>
</div>
<p>这个阶段不追求速度，也不追求打磨。你要找的是 skill 暗中做了哪些假设，比如：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Triggering assumptions</strong>: Prompts like “set up a quick React demo” that <em>should</em> invoke <code>setup-demo-app</code> but don’t, or more generic prompts (“add Tailwind styling”) that unintentionally trigger it.</span><strong>触发上的假设</strong>：像「搭一个简单的 React 演示」这样的提示词<em>本该</em>调用 <code>setup-demo-app</code> 却没调用，或者更泛的提示词（「加点 Tailwind 样式」）却意外触发了它。</li>
<li><span class="yn-en" lang="en"><strong>Environment assumptions</strong>: The skill assumes it’s running in an empty directory, or that <code>npm</code> is available and preferred over other package managers.</span><strong>环境上的假设</strong>：skill 默认自己跑在一个空目录里，或者默认 <code>npm</code> 可用、而且比别的包管理器优先。</li>
<li><span class="yn-en" lang="en"><strong>Execution assumptions</strong>: The agent skips <code>npm install</code> because it assumes dependencies are already installed, or configures Tailwind before the Vite project exists.</span><strong>执行上的假设</strong>：Agent 以为依赖已经装好了，就跳过了 <code>npm install</code>；或者 Vite 项目还没建出来，就先去配 Tailwind。</li>
</ul>
<div class="yn-en" lang="en">
<p>Once you’re ready to make these runs repeatable, switch to <code>codex exec</code>. It’s designed for automation and CI: it streams progress to <code>stderr</code> and writes only the final result to <code>stdout</code>, which makes runs easier to script, capture, and inspect.</p>
</div>
<p>等你准备让这些运行可以重复，就换成 <code>codex exec</code>。它是为自动化和 CI 设计的：进度实时输出到 <code>stderr</code>，<code>stdout</code> 里只写最终结果，这样写脚本、记录、检查起来都更方便。</p>
<div class="yn-en" lang="en">
<p>By default, <code>codex exec</code> runs in a restricted sandbox. If your task needs to write files, run it with <code>--full-auto</code>. As a general rule, especially when automating, use the least permissions needed to get the job done.</p>
</div>
<p><code>codex exec</code> 默认跑在一个受限的沙箱里。任务要写文件的话，就加上 <code>--full-auto</code>。通用的原则是，尤其在自动化的时候，只给完成任务所需的最小权限。</p>
<div class="yn-en" lang="en">
<p>A basic manual run might look like:</p>
</div>
<p>一次基本的手动运行大概是这样：</p>
<div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">codex</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> exec</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --full-auto</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> \</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">  '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Use the $setup-demo-app skill to create the project in this directory.</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This first hands-on pass is less about validating correctness and more about discovering edge cases. Every manual fix you make here, such as adding a missing <code>npm install</code>, correcting the Tailwind setup, or tightening the trigger description, is a candidate for a future eval, so you can lock in the intended behavior before evaluating at scale.</p>
</div>
<p>第一轮亲手跑，重点不在验证对不对，而在发现边界情况。你在这里做的每一处手动修正，比如补上漏掉的 <code>npm install</code>、改对 Tailwind 的配置、把触发用的 description 收紧，都可以变成以后的一条 eval，这样在大规模评测之前就能把想要的行为固定下来。</p>
<h2 id="_4-use-a-small-targeted-prompt-set-to-catch-regressions-early4-用一小组有针对性的提示词-尽早抓住回归" tabindex="-1"><span class="yn-en ignore-header" lang="en">4. Use a small, targeted prompt set to catch regressions early</span>4. 用一小组有针对性的提示词，尽早抓住回归 <a class="header-anchor" href="#_4-use-a-small-targeted-prompt-set-to-catch-regressions-early4-用一小组有针对性的提示词-尽早抓住回归" aria-label="本节链接：4. 用一小组有针对性的提示词，尽早抓住回归">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>You don’t need a large benchmark to get value from evals. For a single skill, a small set of 10–20 prompts is enough to surface regressions and confirm improvements early.</p>
</div>
<p>eval 要有用，并不需要一个很大的基准测试。对单个 skill 来说，10 到 20 条提示词就够早早暴露回归、确认改进了。</p>
<div class="yn-en" lang="en">
<p>Start with a small CSV and grow it over time as you encounter real failures during development or usage. Each row should represent a situation where you care whether the <code>setup-demo-app</code> skill <em>does</em> or <em>does not</em> activate, and what success looks like when it does.</p>
</div>
<p>先从一个小 CSV 开始，开发或使用中碰到真实的失败，就往里加。每一行都应该对应一个场景：你在意 <code>setup-demo-app</code> 这个 skill 在这里<em>该不该</em>启用，以及启用之后什么样算成功。</p>
<div class="yn-en" lang="en">
<p>For example, an initial <code>evals/setup-demo-app.prompts.csv</code> might look like this:</p>
</div>
<p>比如，最初的 <code>evals/setup-demo-app.prompts.csv</code> 可能长这样：</p>
<div class="language-plaintext vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">plaintext</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>id,should_trigger,prompt</span></span>
<span class="line"><span>test-01,true,"Create a demo app named `devday-demo` using the $setup-demo-app skill"</span></span>
<span class="line"><span>test-02,true,"Set up a minimal React demo app with Tailwind for quick UI experiments"</span></span>
<span class="line"><span>test-03,true,"Create a small demo app to showcase the Responses API"</span></span>
<span class="line"><span>test-04,false,"Add Tailwind styling to my existing React app"</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>Each of these cases is testing something slightly different:</p>
</div>
<p>这几条测的东西各有一点不同：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Explicit invocation (<code>test-01</code>)</strong> This prompt names the skill directly. It ensures that Codex can invoke <code>setup-demo-app</code> when asked, and that changes to the skill’s name, description, or instructions don’t break direct usage.</span><strong>显式调用（<code>test-01</code>）</strong> 这条提示词直接点了 skill 的名字。它保证被要求时 Codex 能调用 <code>setup-demo-app</code>，而且改了 skill 的 name、description 或指令之后，直接点名调用还是好使的。</li>
<li><span class="yn-en" lang="en"><strong>Implicit invocation (<code>test-02</code>)</strong> This prompt describes <em>exactly</em> the scenario the skill targets, setting up a minimal React + Tailwind demo, without mentioning the skill by name. It tests whether the name and description in <code>SKILL.md</code> are strong enough for Codex to select the skill on its own.</span><strong>隐式调用（<code>test-02</code>）</strong> 这条提示词描述的<em>正好</em>就是 skill 针对的场景，也就是搭一个最小的 React + Tailwind 演示，但没提 skill 的名字。它测的是 <code>SKILL.md</code> 里的 name 和 description 够不够有力，能不能让 Codex 自己选中这个 skill。</li>
<li><span class="yn-en" lang="en"><strong>Contextual invocation (<code>test-03</code>)</strong> This prompt adds domain context (the Responses API) but still requires the same underlying setup. It checks that the skill triggers in realistic, slightly noisy prompts, and that the resulting app still matches the expected structure and conventions.</span><strong>带上下文的调用（<code>test-03</code>）</strong> 这条提示词加了领域上下文（Responses API），但底下需要的还是同一套搭建。它检查的是：在真实、略带干扰的提示词下 skill 也能触发，而且搭出来的应用仍然符合预期的结构和约定。</li>
<li><span class="yn-en" lang="en"><strong>Negative control (<code>test-04</code>)</strong> This prompt should <strong>not</strong> invoke <code>setup-demo-app</code>. It’s a common adjacent request (“add Tailwind to an existing app”) that can unintentionally match the skill’s description (“React + Tailwind demo”). Including at least one <code>should_trigger=false</code> case helps catch <strong>false positives</strong>, where Codex selects the skill too eagerly and scaffolds a new project when the user wanted an incremental change to an existing one.</span><strong>阴性对照（Negative control，<code>test-04</code>）</strong> 这条提示词<strong>不该</strong>调用 <code>setup-demo-app</code>。它是一个很常见的相邻请求（「给现有应用加上 Tailwind」），可能无意中跟 skill 的 description（「React + Tailwind 演示」）对上。至少放一条 <code>should_trigger=false</code> 的用例，能帮你抓到<strong>误触发（false positive）</strong>：用户只想在现有项目上做点增量修改，Codex 却过于积极地选中了这个 skill，新搭了一个项目。</li>
</ul>
<div class="yn-en" lang="en">
<p>This mix is intentional. Some evals should confirm that the skill behaves correctly when invoked explicitly; others should check that it activates in real-world prompts where the user never mentions the skill at all.</p>
</div>
<p>这样搭配是故意的。有些 eval 要确认 skill 被显式调用时行为正确；另一些则要检查，在用户根本没提这个 skill 的真实提示词里，它也会启用。</p>
<div class="yn-en" lang="en">
<p>As you discover misses, prompts that fail to trigger the skill, or cases where the output drifts from your expectations, add them as new rows. Over time, this small CSV becomes a living record of the scenarios the <code>setup-demo-app</code> skill must continue to get right.</p>
</div>
<p>每发现一处遗漏，比如没能触发 skill 的提示词，或者产出偏离了预期的情况，就加成新的一行。时间长了，这个小 CSV 就成了一份活的记录，记着 <code>setup-demo-app</code> 这个 skill 必须一直做对的那些场景。</p>
<div class="yn-en" lang="en">
<p>Over time, this small dataset becomes a living record of what the skill must continue to get right.</p>
</div>
<p>时间长了，这个小数据集就成了一份活的记录，记着这个 skill 必须一直做对的事。</p>
<h2 id="_5-get-started-with-lightweight-deterministic-graders5-从轻量的确定性评分器开始" tabindex="-1"><span class="yn-en ignore-header" lang="en">5. Get started with lightweight deterministic graders</span>5. 从轻量的确定性评分器开始 <a class="header-anchor" href="#_5-get-started-with-lightweight-deterministic-graders5-从轻量的确定性评分器开始" aria-label="本节链接：5. 从轻量的确定性评分器开始">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>This is the core of the evaluation step: use <code>codex exec --json</code> so your eval harness can score <em>what actually happened</em>, not just whether the final output looks right.</p>
</div>
<p>这是评测这一步的核心：用 <code>codex exec --json</code>，让你的评测框架（eval harness）能给<em>实际发生了什么</em>打分，而不只是看最终输出像不像样。</p>
<div class="yn-en" lang="en">
<p>When you enable <code>--json</code>, <code>stdout</code> becomes a JSONL stream of structured events. That makes it straightforward to write deterministic checks tied directly to the behavior you care about, for example:</p>
</div>
<p>打开 <code>--json</code> 之后，<code>stdout</code> 会变成一条由结构化事件组成的 JSONL 流。这样写确定性检查就很容易，可以直接对准你关心的行为，比如：</p>
<ul>
<li><span class="yn-en" lang="en">Did it run <code>npm install</code>?</span>它跑了 <code>npm install</code> 吗？</li>
<li><span class="yn-en" lang="en">Did it create <code>package.json</code>?</span>它创建了 <code>package.json</code> 吗？</li>
<li><span class="yn-en" lang="en">Did it invoke the expected commands, in the expected order?</span>它是不是按预期的顺序调用了预期的命令？</li>
</ul>
<div class="yn-en" lang="en">
<p>These checks are intentionally lightweight. They give you fast, explainable signals before you add any model-based grading.</p>
</div>
<p>这些检查故意做得很轻。在你加上任何基于模型的打分之前，它们就能给你快速、说得清原因的信号。</p>
<h3 id="a-minimal-node-js-runner一个最小的-node-js-运行脚本" tabindex="-1"><span class="yn-en ignore-header" lang="en">A minimal Node.js runner</span>一个最小的 Node.js 运行脚本 <a class="header-anchor" href="#a-minimal-node-js-runner一个最小的-node-js-运行脚本" aria-label="本节链接：一个最小的 Node.js 运行脚本">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A “good enough” approach looks like this:</p>
</div>
<p>一个「够用」的做法是这样的：</p>
<ol>
<li><span class="yn-en" lang="en">For each prompt, run <code>codex exec --json --full-auto &quot;&lt;prompt&gt;&quot;</code></span>对每条提示词，运行 <code>codex exec --json --full-auto &quot;&lt;prompt&gt;&quot;</code></li>
<li><span class="yn-en" lang="en">Save the JSONL trace to disk</span>把 JSONL 轨迹存到磁盘上</li>
<li><span class="yn-en" lang="en">Parse the trace and run deterministic checks over the events</span>解析轨迹，对其中的事件跑确定性检查</li>
</ol>
<div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// evals/run-setup-demo-app-evals.mjs</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> spawnSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">node:child_process</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> readFileSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> writeFileSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> existsSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> mkdirSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">node:fs</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> path</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">node:path</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">function</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> runCodex</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">prompt</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> outJsonlPath</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">  const</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> res</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> spawnSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">    "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">codex</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    [</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">      "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">exec</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">      "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">--json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"> // REQUIRED: emit structured events</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">      "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">--full-auto</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"> // Allow file system changes</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">      prompt</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    ],</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    {</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965"> encoding</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">utf8</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  );</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  mkdirSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">path</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">dirname</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">outJsonlPath</span><span style="--shiki-light:#999999;--shiki-dark:#666666">),</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965"> recursive</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> true</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> });</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">  // stdout is JSONL when --json is enabled</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  writeFileSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">outJsonlPath</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> res</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">stdout</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">utf8</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">);</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  return</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965"> exitCode</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> res</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">status</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ??</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91"> 1</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965"> stderr</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> res</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">stderr</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> };</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">function</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> parseJsonl</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">jsonlText</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> jsonlText</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    .</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">split</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076">\n</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    .</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">filter</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">Boolean</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    .</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">map</span><span style="--shiki-light:#999999;--shiki-dark:#666666">((</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">line</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> JSON</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">parse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">line</span><span style="--shiki-light:#999999;--shiki-dark:#666666">));</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// deterministic check: did the agent run `npm install`?</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">function</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> checkRanNpmInstall</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">events</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> events</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">some</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    (</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">      (</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">type</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ===</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">item.started</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ||</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">type</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ===</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">item.completed</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> &#x26;&#x26;</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">      e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">item</span><span style="--shiki-light:#999999;--shiki-dark:#666666">?.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">type</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ===</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">command_execution</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> &#x26;&#x26;</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">      typeof</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">item</span><span style="--shiki-light:#999999;--shiki-dark:#666666">?.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">command</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> ===</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">string</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> &#x26;&#x26;</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">      e</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">item</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">command</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">includes</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">npm install</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  );</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// deterministic check: did `package.json` get created?</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">function</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> checkPackageJsonExists</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">projectDir</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  return</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> existsSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">path</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">join</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">projectDir</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">package.json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">));</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// Example single-case run</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">const</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> projectDir</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> process</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">cwd</span><span style="--shiki-light:#999999;--shiki-dark:#666666">();</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">const</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> tracePath</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> path</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">join</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">projectDir</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">evals</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">artifacts</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">test-01.jsonl</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">);</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">const</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> prompt</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">  "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Create a demo app named demo-app using the $setup-demo-app skill</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">runCodex</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">prompt</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> tracePath</span><span style="--shiki-light:#999999;--shiki-dark:#666666">);</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">const</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> events</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> parseJsonl</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">readFileSync</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">tracePath</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">utf8</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">));</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">console</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">log</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">  ranNpmInstall</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> checkRanNpmInstall</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">events</span><span style="--shiki-light:#999999;--shiki-dark:#666666">),</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">  hasPackageJson</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> checkPackageJsonExists</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">path</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">join</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">projectDir</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">demo-app</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)),</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">});</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>The value here is that everything is <strong>deterministic and debuggable</strong>.</p>
</div>
<p>这里的好处是，一切都<strong>确定、可调试</strong>。</p>
<div class="yn-en" lang="en">
<p>If a check fails, you can open the JSONL file and see exactly what happened. Every command execution appears as an <code>item.*</code> event, in order. That makes regressions straightforward to explain and fix, which is exactly what you want at this stage.</p>
</div>
<p>某项检查没过，你可以打开那个 JSONL 文件，看清楚到底发生了什么。每一次命令执行都按顺序记成一条 <code>item.*</code> 事件。所以回归很好解释、也很好修，而这正是这个阶段你想要的。</p>
<h2 id="_6-conduct-qualitative-checks-with-codex-and-rubric-based-grading6-用-codex-和评分细则做定性检查" tabindex="-1"><span class="yn-en ignore-header" lang="en">6. Conduct qualitative checks with Codex and rubric-based grading</span>6. 用 Codex 和评分细则做定性检查 <a class="header-anchor" href="#_6-conduct-qualitative-checks-with-codex-and-rubric-based-grading6-用-codex-和评分细则做定性检查" aria-label="本节链接：6. 用 Codex 和评分细则做定性检查">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Deterministic checks answer <em>“did it do the basics?”</em> but they don’t answer <em>“did it do it the way you wanted?”</em></p>
</div>
<p>确定性检查回答的是*「基本的事做了没有？」<em>，但回答不了</em>「是不是按你想要的方式做的？」*</p>
<div class="yn-en" lang="en">
<p>For skills like <code>setup-demo-app</code>, many requirements are qualitative: component structure, styling conventions, or whether Tailwind follows the intended configuration. These are hard to capture with basic file existence checks or command counts alone.</p>
</div>
<p>像 <code>setup-demo-app</code> 这样的 skill，很多要求是定性的：组件结构、样式约定，或者 Tailwind 的配置是不是按预期来的。光靠检查文件在不在、数命令跑了几次，很难把这些抓住。</p>
<div class="yn-en" lang="en">
<p>A pragmatic solution is to add a second, model-assisted step to your eval pipeline:</p>
</div>
<p>一个务实的办法，是在评测流水线里加第二步，由模型来辅助：</p>
<ol>
<li><span class="yn-en" lang="en">Run the setup skill (this writes code to disk)</span>运行搭建用的 skill（它会把代码写到磁盘上）</li>
<li><span class="yn-en" lang="en">Run a <strong>read-only style check</strong> against the resulting repository</span>对生成的仓库跑一遍<strong>只读的风格检查</strong></li>
<li><span class="yn-en" lang="en">Require a <strong>structured response</strong> that your harness can score consistently</span>要求返回<strong>结构化的结果</strong>，让评测框架能稳定地打分</li>
</ol>
<div class="yn-en" lang="en">
<p>Codex supports this directly via <code>--output-schema</code>, which constrains the final response to a JSON Schema you define.</p>
</div>
<p>Codex 通过 <code>--output-schema</code> 直接支持这一点，它会把最终回复约束成你定义的 JSON Schema。</p>
<h3 id="a-small-rubric-schema一份小小的评分细则-schema" tabindex="-1"><span class="yn-en ignore-header" lang="en">A small rubric schema</span>一份小小的评分细则 schema <a class="header-anchor" href="#a-small-rubric-schema一份小小的评分细则-schema" aria-label="本节链接：一份小小的评分细则 schema">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Start by defining a small schema that captures the checks you care about. For example, create <code>evals/style-rubric.schema.json</code>:</p>
</div>
<p>先定义一个小 schema，把你关心的检查装进去。比如，创建 <code>evals/style-rubric.schema.json</code>：</p>
<div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">object</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">properties</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">overall_pass</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">boolean</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">score</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">integer</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">minimum</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91"> 0</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">maximum</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91"> 100</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">    "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">checks</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">      "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">array</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">      "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">items</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">object</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">properties</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">          "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">id</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">string</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">          "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">pass</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">boolean</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">          "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">notes</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577"> "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">type</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">string</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">        },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">required</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">id</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">pass</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">notes</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">],</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">        "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">additionalProperties</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> false</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">      }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  },</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">required</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">overall_pass</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">score</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">checks</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">],</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">  "</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">additionalProperties</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577">"</span><span style="--shiki-light:#999999;--shiki-dark:#666666">:</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> false</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This schema gives you stable fields (<code>overall_pass</code>, <code>score</code>, per-check results) that you can combine, diff, and track over time.</p>
</div>
<p>这个 schema 给了你一组稳定的字段（<code>overall_pass</code>、<code>score</code>、每项检查的结果），可以合并、对比差异，也可以长期跟踪。</p>
<h3 id="the-style-check-prompt风格检查的提示词" tabindex="-1"><span class="yn-en ignore-header" lang="en">The style-check prompt</span>风格检查的提示词 <a class="header-anchor" href="#the-style-check-prompt风格检查的提示词" aria-label="本节链接：风格检查的提示词">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Next, run a second <code>codex exec</code> that <em>only inspects the repository</em> and emits a rubric-compliant JSON response:</p>
</div>
<p>接下来，再跑一个 <code>codex exec</code>，这次它<em>只检查仓库</em>，输出一份符合评分细则的 JSON：</p>
<div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">codex</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> exec</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> \</span></span>
<span class="line"><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">  "</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">Evaluate the demo-app repository against these requirements:</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">   - Vite + React + TypeScript project exists</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">   - Tailwind is configured via @tailwindcss/vite and CSS imports tailwindcss</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">   - src/components contains Header.tsx and Card.tsx</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">   - Components are functional and styled with Tailwind utility classes (no CSS modules)</span></span>
<span class="line"><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">   Return a rubric result as JSON with check ids: vite, tailwind, structure, style.</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> \</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076">  --output-schema</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> ./evals/style-rubric.schema.json</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> \</span></span>
<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076">  -o</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> ./evals/artifacts/test-01.style.json</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>This is where <code>--output-schema</code> is handy. Instead of free-form text that’s hard to parse or compare, you get a predictable JSON object that your eval harness can score across many runs.</p>
</div>
<p><code>--output-schema</code> 好用就好用在这里。你拿到的不再是难解析、难比较的自由文本，而是一个格式可预期的 JSON 对象，评测框架可以在很多次运行之间统一打分。</p>
<div class="yn-en" lang="en">
<p>If you later move this eval suite into CI, the Codex GitHub Action explicitly supports passing <code>--output-schema</code> through <code>codex-args</code>, so you can enforce the same structured output in automated workflows.</p>
</div>
<p>如果以后把这套 eval 搬进 CI，Codex 的 GitHub Action 明确支持通过 <code>codex-args</code> 传入 <code>--output-schema</code>，所以在自动化工作流里也能强制同样的结构化输出。</p>
<h2 id="_7-extending-your-evals-as-the-skill-matures7-skill-成熟之后-再扩展-eval" tabindex="-1"><span class="yn-en ignore-header" lang="en">7. Extending your evals as the skill matures</span>7. skill 成熟之后，再扩展 eval <a class="header-anchor" href="#_7-extending-your-evals-as-the-skill-matures7-skill-成熟之后-再扩展-eval" aria-label="本节链接：7. skill 成熟之后，再扩展 eval">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Once you have the core loop in place, you can extend your evals in the directions that matter most for your skill. Start small, then layer in deeper checks only where they add real confidence.</p>
</div>
<p>核心的循环跑通之后，就可以往对你的 skill 最要紧的方向扩展 eval。从小处开始，只在真正能增加把握的地方，才一层层加上更深的检查。</p>
<div class="yn-en" lang="en">
<p>Some examples include:</p>
</div>
<p>举几个例子：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Command count and thrashing:</strong> Count <code>command_execution</code> items in the JSONL trace to catch regressions where the agent starts looping or re-running commands. Token usage is also available in <code>turn.completed</code> events.</span><strong>命令数量和来回折腾：</strong> 数一数 JSONL 轨迹里 <code>command_execution</code> 条目的个数，抓住 Agent 开始兜圈子、重复跑命令这类回归。<code>turn.completed</code> 事件里还能拿到 token 用量。</li>
<li><span class="yn-en" lang="en"><strong>Token budget:</strong> Track <code>usage.input_tokens</code> and <code>usage.output_tokens</code> to spot accidental prompt bloat and compare efficiency across versions.</span><strong>token 预算：</strong> 跟踪 <code>usage.input_tokens</code> 和 <code>usage.output_tokens</code>，发现提示词不知不觉膨胀起来，也能比较不同版本的效率。</li>
<li><span class="yn-en" lang="en"><strong>Build checks:</strong> Run <code>npm run build</code> after the skill completes. This acts as a stronger end-to-end signal and catches broken imports or incorrectly configured tooling.</span><strong>构建检查：</strong> skill 跑完之后执行 <code>npm run build</code>。这是一个更强的端到端信号，能抓到坏掉的 import 或者配错的工具链。</li>
<li><span class="yn-en" lang="en"><strong>Runtime smoke checks:</strong> Start <code>npm run dev</code> and hit the dev server with <code>curl</code>, or run a lightweight Playwright check if you already have one. Use this selectively. It adds confidence but costs time.</span><strong>运行时冒烟检查：</strong> 启动 <code>npm run dev</code>，用 <code>curl</code> 请求一下开发服务器；如果手头已经有轻量的 Playwright 检查，也可以跑一下。这个要挑着用：它能增加把握，但费时间。</li>
<li><span class="yn-en" lang="en"><strong>Repository cleanliness:</strong> Ensure the run generates no unwanted files and that <code>git status --porcelain</code> is empty (or matches an explicit allow list).</span><strong>仓库干净程度：</strong> 确认这次运行没有生成多余的文件，<code>git status --porcelain</code> 的输出为空（或者跟一份明确的白名单对得上）。</li>
<li><span class="yn-en" lang="en"><strong>Sandbox and permission regressions:</strong> Verify the skill still works without escalating permissions beyond what you intended. Least-privilege defaults matter most once you automate.</span><strong>沙箱和权限方面的回归：</strong> 确认 skill 在不把权限提到超出你预期的情况下仍然能用。一旦自动化起来，默认最小权限就是最要紧的。</li>
</ul>
<div class="yn-en" lang="en">
<p>The pattern is consistent: begin with fast checks that explain behavior, then add slower, heavier checks only when they reduce risk.</p>
</div>
<p>套路始终是一样的：先上能解释行为的快检查，只有在能降低风险的时候，才加更慢、更重的检查。</p>
<h2 id="_8-key-takeaways8-要点" tabindex="-1"><span class="yn-en ignore-header" lang="en">8. Key takeaways</span>8. 要点 <a class="header-anchor" href="#_8-key-takeaways8-要点" aria-label="本节链接：8. 要点">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>This small <code>setup-demo-app</code> example shows the shift from “it feels better” to “proof”: run the agent, record what happened, and grade it with a small set of checks. Once that loop exists, every tweak becomes easier to confirm, and every regression becomes clear. Here are the key takeaways:</p>
</div>
<p><code>setup-demo-app</code> 这个小例子展示的，是从「感觉更好了」到「拿得出证据」的转变：跑一遍 Agent，记下发生了什么，再用一小组检查给它打分。有了这个循环，每一处微调都更容易确认，每一次回归也都看得清清楚楚。要点如下：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Measure what matters.</strong> Good evals make regressions clear and failures explainable.</span><strong>衡量要紧的东西。</strong> 好的 eval 让回归一目了然，让失败说得清原因。</li>
<li><span class="yn-en" lang="en"><strong>Start from a checkable definition of done.</strong> Use <code>$skill-creator</code> to bootstrap, then tighten the instructions until success is unambiguous.</span><strong>从一个能检查的完成标准出发。</strong> 用 <code>$skill-creator</code> 起个头，再把指令一点点收紧，直到成功与否没有歧义。</li>
<li><span class="yn-en" lang="en"><strong>Ground evals in behavior.</strong> Capture JSONL with <code>codex exec --json</code> and write deterministic checks against <code>command_execution</code> events.</span><strong>让 eval 立足于行为。</strong> 用 <code>codex exec --json</code> 记下 JSONL，针对 <code>command_execution</code> 事件写确定性检查。</li>
<li><span class="yn-en" lang="en"><strong>Use Codex where rules fall short.</strong> Add a structured, rubric-based pass with <code>--output-schema</code> to grade style and conventions reliably.</span><strong>规则管不到的地方，交给 Codex。</strong> 用 <code>--output-schema</code> 加一轮结构化、基于评分细则的检查，稳定地给风格和约定打分。</li>
<li><span class="yn-en" lang="en"><strong>Let real failures drive coverage.</strong> Every manual fix is a signal. Turn it into a test so the skill keeps getting it right.</span><strong>让真实的失败决定覆盖面。</strong> 每一次手动修正都是一个信号。把它变成一条测试，让 skill 一直做对。</li>
</ul>
]]></content:encoded>
</item>
<item>
<title>怎样把你的 AI 变成世界级设计师</title>
<link>https://nyann.cc/posts/%E6%80%8E%E6%A0%B7%E6%8A%8A%E4%BD%A0%E7%9A%84%20AI%20%E5%8F%98%E6%88%90%E4%B8%96%E7%95%8C%E7%BA%A7%E8%AE%BE%E8%AE%A1%E5%B8%88</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E6%80%8E%E6%A0%B7%E6%8A%8A%E4%BD%A0%E7%9A%84%20AI%20%E5%8F%98%E6%88%90%E4%B8%96%E7%95%8C%E7%BA%A7%E8%AE%BE%E8%AE%A1%E5%B8%88</guid>
<pubDate>Fri, 16 Oct 2026 00:00:00 GMT</pubDate>
<description>前 Apple 设计与工程负责人 Anshu Chimala 的一整套流程：用种子字符串、设计评审子 Agent、图像和视频生成，再加上大刀阔斧的删减，让 AI 做出不像 AI 做的设计。</description>
<category>翻译</category>
<category>AI</category>
<category>设计</category>
<category>Agent</category>
<content:encoded><![CDATA[<h1 id="怎样把你的-ai-变成世界级设计师" tabindex="-1">怎样把你的 AI 变成世界级设计师 <a class="header-anchor" href="#怎样把你的-ai-变成世界级设计师" aria-label="本节链接：怎样把你的 AI 变成世界级设计师">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p><em>👋 Hey there, I’m Lenny. Each week, I share deeply researched product, growth, and career advice. For more: <a href="https://www.lennysjobs.com/" target="_blank" rel="noreferrer">Lenny’s Jobs</a> | <a href="https://www.lennysnewsletter.com/podcast" target="_blank" rel="noreferrer">Lenny’s Podcast</a> | <a href="https://www.lennybot.com/" target="_blank" rel="noreferrer">Lennybot</a> | <a href="https://www.youtube.com/@howiaipodcast" target="_blank" rel="noreferrer">How I AI</a> | <a href="https://maven.com/tech-for-product/become-an-ai-native-builder" target="_blank" rel="noreferrer">Become an AI-Native Builder</a> and my other favorite <a href="https://maven.com/lenny" target="_blank" rel="noreferrer">AI/PM courses</a></em></p>
</div>
<p><em>👋 嗨，我是 Lenny。每周我都会分享一些下足功夫调研过的产品、增长和职业建议。更多内容：<a href="https://www.lennysjobs.com/" target="_blank" rel="noreferrer">Lenny’s Jobs</a> | <a href="https://www.lennysnewsletter.com/podcast" target="_blank" rel="noreferrer">Lenny’s Podcast</a> | <a href="https://www.lennybot.com/" target="_blank" rel="noreferrer">Lennybot</a> | <a href="https://www.youtube.com/@howiaipodcast" target="_blank" rel="noreferrer">How I AI</a> | <a href="https://maven.com/tech-for-product/become-an-ai-native-builder" target="_blank" rel="noreferrer">Become an AI-Native Builder</a>，以及我喜欢的其他 <a href="https://maven.com/lenny" target="_blank" rel="noreferrer">AI/PM 课程</a></em></p>
<div class="yn-en" lang="en">
<p><em>P.S. Get a full free year of Cursor, Notion, Replit, Lovable, Wispr Flow, Linear, ElevenLabs, Factory, PostHog, Granola, Brain.fm, Waking Up, and more, by becoming an Insider subscriber (while supplies last). <a href="https://www.lennysproductpass.com/" target="_blank" rel="noreferrer">Learn more</a>.</em></p>
</div>
<p><em>P.S. 成为 Insider 订阅者，就能免费用一整年 Cursor、Notion、Replit、Lovable、Wispr Flow、Linear、ElevenLabs、Factory、PostHog、Granola、Brain.fm、Waking Up 等等（送完即止）。<a href="https://www.lennysproductpass.com/" target="_blank" rel="noreferrer">了解详情</a>。</em></p>
<hr>
<div class="yn-en" lang="en">
<p>I’d always thought AI was bad at design. But after reading this mind-blowing post by <a href="https://www.linkedin.com/in/achimala/" target="_blank" rel="noreferrer">Anshu Chimala</a>, I realize I was just doing it wrong. Anshu led software engineering and design teams at Apple for 12 years, focusing on research and prototyping for future AI products. He regularly shares design tutorials and demos on <a href="https://x.com/anshuc" target="_blank" rel="noreferrer">X</a> (he’s one of my favorite follows). For deeper dives into crafting distinctive experiences with AI, check out his <a href="https://substack.com/@anshuc" target="_blank" rel="noreferrer">Substack</a> and connect with him on <a href="https://www.linkedin.com/in/achimala/" target="_blank" rel="noreferrer">LinkedIn</a>.</p>
</div>
<p>我一直觉得 AI 不会做设计。读完 <a href="https://www.linkedin.com/in/achimala/" target="_blank" rel="noreferrer">Anshu Chimala</a> 这篇让人大开眼界的文章，我才发现是自己用错了方法。Anshu 在 Apple 带了 12 年软件工程和设计团队，专做未来 AI 产品的研究和原型。他经常在 <a href="https://x.com/anshuc" target="_blank" rel="noreferrer">X</a> 上分享设计教程和 demo（我最喜欢关注的人之一）。想更深入地了解怎么用 AI 做出与众不同的体验，可以看他的 <a href="https://substack.com/@anshuc" target="_blank" rel="noreferrer">Substack</a>，也可以在 <a href="https://www.linkedin.com/in/achimala/" target="_blank" rel="noreferrer">LinkedIn</a> 上加他。</p>
<div class="yn-en" lang="en">
<p>Let’s get into it.</p>
</div>
<p>我们开始吧。</p>
<hr>
<div class="yn-en" lang="en">
<p><strong>A conversational calorie tracker, built in three prompts with Claude Fable 5:</strong></p>
</div>
<p><strong>一个用聊天来记卡路里的应用，用 Claude Fable 5 三条提示词做出来：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/01.webp" alt="一个用聊天来记卡路里的应用" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>A space exploration game, built in two prompts with Claude Opus 5:</strong></p>
</div>
<p><strong>一个太空探索游戏，用 Claude Opus 5 两条提示词做出来：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/02.webp" alt="一个太空探索游戏" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>A dynamic landing page, built in three prompts with Claude Opus 5 + GPT-5.6 Sol:</strong></p>
</div>
<p><strong>一个会动的落地页，用 Claude Opus 5 + GPT-5.6 Sol 三条提示词做出来：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/03.webp" alt="一个会动的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>I often post AI design demos like these on X. Every time I do, someone inevitably asks, “Why does the model create all this incredible stuff for you, but when I try, I only get generic slop? It’s like you’re using a completely different model.”</p>
</div>
<p>我常在 X 上发这类 AI 设计 demo。每次发，总有人问：「为什么模型给你做的东西这么惊艳，我自己试就只能拿到千篇一律的平庸货（slop）？你用的好像根本是另一个模型。」</p>
<div class="yn-en" lang="en">
<p>I’m not using a different model, but I am getting <em>more</em> out of the models I work with. Most people only see 1% of AI’s creative potential. I want to show you how to tap into the other 99%.</p>
</div>
<p>我用的不是别的模型，只是从手里的模型身上榨出了<em>更多</em>东西。大多数人只看到了 AI 创造力的 1%，我想带你看看怎么挖出剩下那 99%。</p>
<div class="yn-en" lang="en">
<p>AI models are capable of amazing creativity, but that creativity gets stifled by how they’re trained. Large language models are next-token predictors: at each step, they look at a sequence of text and predict what comes next based on millions of examples. The results may be rated by humans, and those ratings fed back into the model. This teaches the model to make consistent, safe choices that fit everyone’s preferences.</p>
</div>
<p>AI 模型的创造力其实很惊人，只是被训练方式压住了。大语言模型是「预测下一个 token」的机器：每一步都看着一串文本，根据几百万个例子猜下一个是什么。输出可能会交给人来打分，分数再反馈回模型。这么一来，模型学会的是做稳妥、一致、谁都挑不出毛病的选择。</p>
<div class="yn-en" lang="en">
<p>This makes typical LLMs great at most tasks but poor designers. To create a design, an LLM has to build it out token by token. Whenever it needs to make a design decision—what colors to use, or how to arrange elements—the model fills in the tokens it thinks are most likely to please everyone. As a result, the design usually ends up being repetitive and bland. It’s like the ultimate case of design-by-committee.</p>
</div>
<p>所以一般的 LLM 干大多数活都很好，偏偏当不好设计师。做一个设计，LLM 得一个 token 一个 token 地往外搭。每当要做设计决策，比如用什么颜色、元素怎么摆，模型填进去的都是它认为最可能讨所有人喜欢的那些 token。结果设计往往重复又寡淡，简直是委员会式设计（design-by-committee）的终极形态。</p>
<div class="yn-en" lang="en">
<p>Great design, on the other hand, starts with feeling and aims to create an emotional response. It bends the rules and delights users with memorable, unexpected choices. Great design is exactly the opposite of what an LLM does naturally, which is to make the most predictable choice at every step.</p>
</div>
<p>好的设计正相反，它从感受出发，要的是在人心里激起点什么。它会打破规则，用让人记得住、意想不到的选择打动用户。LLM 的本能是每一步都选最好猜的那个，好设计跟它恰好背道而驰。</p>
<div class="yn-en" lang="en">
<p>However, if we can get the model to reach beyond the most predictable choices, we can access a vast landscape of creative ideas that most people miss out on.</p>
</div>
<p>不过，只要能让模型越过那些最好猜的选择，我们就能摸到一大片大多数人错过的创意天地。</p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/04.webp" alt="" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>This is a lesson I learned from managing human designers, before I was managing AI ones. For most of my career at Apple, I led an R&amp;D team designing exploratory future AI products. Early on, our preconceived notions about how user interfaces should work limited our creativity and kept us returning to the same old ideas. Through rigor and new processes, we learned to stop re-creating what’s comfortable and instead look to the fringes of what’s possible, to generate something new. We became experts at polishing the little details to an Apple level of quality.</p>
</div>
<p>这是我在管 AI 设计师之前、管人类设计师时学到的。在 Apple 的大部分时间里，我带的是一个研发团队，设计探索性的未来 AI 产品。一开始，我们对「界面该怎么做」的成见限制了创造力，老是绕回那几个旧点子。靠着严格的要求和新流程，我们学会了不再复刻舒服的老样子，而是去可能性的边缘找新东西。我们也练成了把小细节打磨到 Apple 水准的本事。</p>
<div class="yn-en" lang="en">
<p>Since my time at Apple, I’ve been working on applying that same process to my work with AI. In the past couple years, AI agents have become extremely capable. They can do in hours what used to take my team weeks. And with the right guidance, they can create designs that look completely unlike anything else.</p>
</div>
<p>离开 Apple 之后，我一直在把同一套流程搬到和 AI 的协作里。过去这两年，AI Agent 的能力强得吓人，以前我的团队要几周的活，它们几小时就能干完。只要引导得当，它们能做出跟别的东西完全不一样的设计。</p>
<div class="yn-en" lang="en">
<p>Loosely inspired by the <a href="https://en.wikipedia.org/wiki/Double_Diamond_(design_process_model)" target="_blank" rel="noreferrer">Double Diamond design process</a>, I’ve reimagined the design process for a team of AI agents instead of human designers:</p>
</div>
<p>我大致参考了<a href="https://en.wikipedia.org/wiki/Double_Diamond_(design_process_model)" target="_blank" rel="noreferrer">双钻设计流程（Double Diamond）</a>，把设计流程重新改造了一遍，对象从人类设计师换成了一队 AI Agent：</p>
<ol>
<li><span class="yn-en" lang="en"><strong>Discover</strong> new ideas beyond the average slop by exploring a variety of directions and creating bold, ambitious design briefs.</span><strong>发现</strong>：探索各种方向、写出大胆有野心的设计简报，找到平庸货之外的新点子。</li>
<li><span class="yn-en" lang="en"><strong>Define</strong> an individual design identity by pushing AI beyond its familiar patterns and chaining models together to fully realize the design’s potential.</span><strong>定义</strong>：逼 AI 跳出熟悉的套路，把几个模型串起来用，把设计的潜力完全发挥出来，确立独有的设计个性。</li>
<li><span class="yn-en" lang="en"><strong>Deliver</strong> a stunning final result by polishing away the sloppy rough edges and focusing on the key elements.</span><strong>交付</strong>：磨掉粗糙的毛边，把精力集中在关键元素上，交出惊艳的最终成品。</li>
</ol>
<div class="yn-en" lang="en">
<p>By following these stages and applying the techniques within each one, you can create an incredible design remarkably quickly—and make people ask, “Why does AI create magic for you (and not me)?”</p>
</div>
<p>按这几个阶段走，用上每个阶段里的技巧，你能飞快地做出惊人的设计，然后轮到别人来问你：「为什么 AI 给你变魔术，不给我变？」</p>
<h2 id="discover-explore-the-space-of-possibilities发现-探索可能性的空间" tabindex="-1"><span class="yn-en ignore-header" lang="en">Discover: Explore the space of possibilities</span>发现：探索可能性的空间 <a class="header-anchor" href="#discover-explore-the-space-of-possibilities发现-探索可能性的空间" aria-label="本节链接：发现：探索可能性的空间">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The hardest part of the design process is looking at a blank screen with infinite possibilities. The best way to tackle that moment is to start by going broad before going deep. AI is an excellent tool to explore a wide variety of potential directions.</p>
</div>
<p>设计里最难的，就是盯着一块空白屏幕、面对无限可能的那一刻。最好的办法是先铺开、再深挖。要探索各种各样可能的方向，AI 是绝佳的工具。</p>
<div class="yn-en" lang="en">
<p>As we know, though, models tend to overrely on familiar patterns and make conservative choices. To explore the full potential design space, we want to coax a model to do the opposite: be bold, be varied, and take risks. Below are two ways to push it out of its comfort zone.</p>
</div>
<p>可我们也知道，模型总是过度依赖熟悉的套路，选择也偏保守。想把整个设计空间探索一遍，就得哄着模型反着来：大胆、多样、敢冒险。下面是两种把它推出舒适区的办法。</p>
<h2 id="technique-1-use-seed-strings-to-inject-variety技巧-1-用种子字符串注入多样性" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 1: Use seed strings to inject variety</span>技巧 1：用种子字符串注入多样性 <a class="header-anchor" href="#technique-1-use-seed-strings-to-inject-variety技巧-1-用种子字符串注入多样性" aria-label="本节链接：技巧 1：用种子字符串注入多样性">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The idea here is to get the model to find a new source of inspiration for designs, rather than relying on the defaults it learned from training. If you’ve tried to prompt a model to design a website or app, you’ve probably already seen what that default looks like.</p>
</div>
<p>思路是让模型给设计找一个新的灵感来源，别老靠训练时学来的默认选项。如果你试过让模型设计网站或应用，大概已经见过那个默认长什么样了。</p>
<div class="yn-en" lang="en">
<p>As a simple example, I gave four instances of Claude Code the same prompt:</p>
</div>
<p>举个简单的例子，我给四个 Claude Code 实例同一条提示词：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Build me a landing page for my productivity app.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>给我的效率应用做一个落地页。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>Claude Opus 5:</strong></p>
</div>
<p><strong>Claude Opus 5：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/05.webp" alt="四个实例做出的默认落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Almost every time, we get a purplish gradient, text on the left, graphic on the right, and the exact same structure. It looks like every AI-designed website ever.</p>
</div>
<p>几乎每次都是偏紫的渐变、左边文字、右边配图，结构一模一样。跟所有 AI 设计出来的网站都一个样。</p>
<div class="yn-en" lang="en">
<p>We didn’t ask the model to do anything unique or varied, so it makes sense that it keeps falling back on the same patterns it knows well. But just asking for variety doesn’t work:</p>
</div>
<p>我们没让模型做什么独特或多变的东西，它一直退回到自己熟悉的套路也说得通。可光要求它「多样一点」并没有用：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Build me a landing page for my productivity app. Give me something totally unique. Make every design decision completely at random.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>给我的效率应用做一个落地页。给我一个完全独一无二的东西。每一个设计决策都完全随机地做。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>Claude Opus 5:</strong></p>
</div>
<p><strong>Claude Opus 5：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/06.webp" alt="要求「完全随机」后的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The results are different from before, but they’re still not varied. The model always uses the same color scheme, structure, and even the same awkward pottery metaphors. It’s predicting tokens that <em>sound</em> random but aren’t <em>actually</em> random.</p>
</div>
<p>结果和之前不一样了，可几次之间还是差不多。模型每次都用同样的配色、同样的结构，连那个别扭的陶艺比喻都一样。它预测出来的 token <em>听上去</em>随机，<em>实际上</em>并不随机。</p>
<div class="yn-en" lang="en">
<p><strong>The problem is that the model can’t inherently act randomly.</strong> It can only predict the most likely token. If we want variety, we have to bring it from outside the model. One technique for this is String Seed of Thought, <a href="https://pub.sakana.ai/ssot/" target="_blank" rel="noreferrer">published by Sakana AI</a>. We make the AI generate a random string and use it as design inspiration. That way, the model is truly making different decisions each time.</p>
</div>
<p><strong>问题在于模型天生就做不到随机。</strong> 它只能预测最可能的那个 token。想要多样性，就得从模型外面引进来。有个办法叫 String Seed of Thought，<a href="https://pub.sakana.ai/ssot/" target="_blank" rel="noreferrer">由 Sakana AI 发表</a>：让 AI 生成一串随机字符串，拿它当设计灵感。这样模型每次做的决策才真的不一样。</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>I want you to build me a landing page for my productivity app.</em></p>
<p><em>Follow this procedure:</em></p>
<ol>
<li><em>Generate a long, random alphanumeric string using a shell script.</em></li>
<li><em>Define the creative direction (color scheme, layout, typography, etc.) based on the string. Look beyond the surface for subpatterns, special numbers, anything that inspires you.</em></li>
<li><em>Use your judgment to bring this direction to life and make it look great.</em></li>
</ol>
<p><em>Don’t reveal the string in the design. It’s only for your inspiration.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>我想让你给我的效率应用做一个落地页。</em></p>
<p><em>按下面的步骤来：</em></p>
<ol>
<li><em>用 shell 脚本生成一串很长的随机字母数字字符串。</em></li>
<li><em>根据这串字符定下创意方向（配色、布局、字体排印等等）。别只看表面，去找里面的子模式、特殊的数字，任何能给你灵感的东西。</em></li>
<li><em>用你自己的判断把这个方向落地，做得漂亮一点。</em></li>
</ol>
<p><em>不要在设计里露出这串字符，它只是给你找灵感用的。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>Claude Opus 5:</strong></p>
</div>
<p><strong>Claude Opus 5：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/07.webp" alt="用种子字符串做出的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Suddenly the outputs are much more varied! Now we’re seeing different color schemes, fonts, and new ideas. The previous designs were ones that any Claude user could get. These designs are one-of-a-kind; no two runs ever produce the same result.</p>
</div>
<p>一下子就多样多了！配色、字体都不一样了，也冒出了新点子。前面那些设计，随便哪个 Claude 用户都能拿到；这些是独一份的，跑两次永远不会出一样的结果。</p>
<h2 id="technique-2-be-much-more-ambitious-with-your-prompts技巧-2-提示词写得野心大得多" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 2: Be much more ambitious with your prompts</span>技巧 2：提示词写得野心大得多 <a class="header-anchor" href="#technique-2-be-much-more-ambitious-with-your-prompts技巧-2-提示词写得野心大得多" aria-label="本节链接：技巧 2：提示词写得野心大得多">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Another approach to giving a model a strong push is to get more specific and wild with your prompts. This gives the model a clear vision to base its decisions on, rather than letting it make them up on the fly. The best way to find a unique idea is by bringing your own taste into the equation. You first imagine the inspiration—a video game, an interior design trend, an art installation—and describe how you’d like that inspiration to influence the AI’s outputs. Here are some examples:</p>
</div>
<p>另一种狠推模型一把的办法，是把提示词写得更具体、更疯。这样模型做决策时有一个清楚的愿景可依，不用临场瞎编。找到独特点子最好的办法，是把你自己的品味带进来。先想好灵感是什么，一款电子游戏、一种室内设计潮流、一件艺术装置，再描述你希望这个灵感怎样影响 AI 的产出。举几个例子：</p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>“Build me a landing page for my productivity app, with a bold pixel art theme and stunning graphics. Each section should feel like a still from a video game, yet somehow it should all function as a landing page.”</em></p>
</blockquote>
</div>
<blockquote>
<p><em>「给我的效率应用做一个落地页，用大胆的像素画主题和惊艳的画面。每个区块都要像电子游戏里的一帧截图，但整体还得能当落地页用。」</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/08.webp" alt="像素画主题的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>“Build me a landing page for my productivity app, set in an isometric living 3D city, where different features are somehow represented by neighborhoods or buildings.”</em></p>
</blockquote>
</div>
<blockquote>
<p><em>「给我的效率应用做一个落地页，场景是一座活生生的等距视角 3D 城市，不同的功能用不同的街区或建筑来表现。」</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/09.webp" alt="等距 3D 城市主题的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>“Build me a landing page for my productivity app, with a radically asymmetric layout, dissonant colors and typography, and uncomfortable negative space. Break all the rules but still make it look good.”</em></p>
</blockquote>
</div>
<blockquote>
<p><em>「给我的效率应用做一个落地页，布局极端不对称，颜色和字体互相冲突，留白多到让人不舒服。打破所有规则，但还是要好看。」</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/10.webp" alt="打破规则的不对称落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Of course, the hard part is coming up with original ideas to ask for. AI can help with this too, but if you simply ask it for ideas, you’ll get the same average ones everyone else gets. Here’s a system I use to find unique prompt ideas with AI:</p>
</div>
<p>当然，难的是想出原创的点子去提要求。这一步 AI 也能帮忙，可你要是直接找它要点子，拿到的就是别人都能拿到的那些平均货。下面是我用 AI 找独特提示词点子的一套办法：</p>
<h4 id="_1-ask-ai-to-list-a-bunch-of-ideas-intentionally-lacking-detail-the-goal-is-just-to-inspire-your-imagination-1-让-ai-列一堆点子-故意不要细节-目的只是激发你的想象" tabindex="-1"><span class="yn-en ignore-header" lang="en">1. Ask AI to list a bunch of ideas, intentionally lacking detail. The goal is just to inspire your imagination.</span>1. 让 AI 列一堆点子，故意不要细节，目的只是激发你的想象 <a class="header-anchor" href="#_1-ask-ai-to-list-a-bunch-of-ideas-intentionally-lacking-detail-the-goal-is-just-to-inspire-your-imagination-1-让-ai-列一堆点子-故意不要细节-目的只是激发你的想象" aria-label="本节链接：1. 让 AI 列一堆点子，故意不要细节，目的只是激发你的想象">&ZeroWidthSpace;</a></h4>
<div class="yn-en" lang="en">
<blockquote>
<p><em>I want to come up with a bold, unique design language for my product. Can you list as many ideas as you can, with short, high-level descriptions? Go broad, not deep.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>我想给我的产品想一套大胆、独特的设计语言。你能尽可能多地列一些点子吗？每个配一句简短的高层描述就行。要广，不要深。</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/11.webp" alt="AI 列出的设计语言点子" loading="lazy"></p>
<h4 id="_2-visualize-your-favorites-and-note-how-you-react-to-different-directions-then-ask-ai-to-refine-them-2-把喜欢的几个在脑子里过一遍-记下自己对不同方向的反应-再让-ai-细化" tabindex="-1"><span class="yn-en ignore-header" lang="en">2. Visualize your favorites and note how you react to different directions. Then ask AI to refine them.</span>2. 把喜欢的几个在脑子里过一遍，记下自己对不同方向的反应，再让 AI 细化 <a class="header-anchor" href="#_2-visualize-your-favorites-and-note-how-you-react-to-different-directions-then-ask-ai-to-refine-them-2-把喜欢的几个在脑子里过一遍-记下自己对不同方向的反应-再让-ai-细化" aria-label="本节链接：2. 把喜欢的几个在脑子里过一遍，记下自己对不同方向的反应，再让 AI 细化">&ZeroWidthSpace;</a></h4>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Industrial Control Panel:</em></p>
<ul>
<li><em>I’m imagining something tactile. Clicky, satisfying buttons, nice sounds.</em></li>
<li><em>Initially I pictured something cartoony or skeuomorphic, but this feels tacky to me. Avoid that.</em></li>
<li><em>Instead, want consistent components and little touches that land this look without going overboard.</em></li>
<li><em>Gray gradients would look boring. Need more texture. Maybe we can incorporate some color, while retaining the control panel feel?</em></li>
</ul>
<p><em>Can you sharpen this one based on my tastes?</em></p>
</blockquote>
</div>
<blockquote>
<p><em>工业控制面板：</em></p>
<ul>
<li><em>我想象的是有触感的东西。按下去咔哒一声、很解压的按钮，好听的音效。</em></li>
<li><em>一开始我脑子里是卡通风或者拟物风，但感觉有点土。避开这个。</em></li>
<li><em>我想要的是统一的组件和一些小细节，把这个感觉做出来，又不过火。</em></li>
<li><em>灰色渐变会很无聊。需要更多质感。能不能加点颜色，同时保留控制面板的感觉？</em></li>
</ul>
<p><em>你能按我的口味把这个方向再磨一磨吗？</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/12.webp" alt="AI 按口味细化后的方向" loading="lazy"></p>
<h4 id="_3-iterate-until-you-re-satisfied-then-ask-ai-to-write-the-prompt-to-build-it-3-反复迭代到满意-再让-ai-写出用来实现它的提示词" tabindex="-1"><span class="yn-en ignore-header" lang="en">3. Iterate until you’re satisfied, then ask AI to write the prompt to build it.</span>3. 反复迭代到满意，再让 AI 写出用来实现它的提示词 <a class="header-anchor" href="#_3-iterate-until-you-re-satisfied-then-ask-ai-to-write-the-prompt-to-build-it-3-反复迭代到满意-再让-ai-写出用来实现它的提示词" aria-label="本节链接：3. 反复迭代到满意，再让 AI 写出用来实现它的提示词">&ZeroWidthSpace;</a></h4>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Can you write a concise prompt that an AI agent could use to build an initial POC page with this?</em></p>
</blockquote>
</div>
<blockquote>
<p><em>你能写一条简洁的提示词，让 AI Agent 能照着它做出一个初版的 POC 页面吗？</em></p>
</blockquote>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/13.webp" alt="AI 写出的实现提示词" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>If you just paste AI-generated ideas back into AI, it’s hard to get something unique. After all, anyone else could have done the same thing. However, when you actively steer the design direction, you end up with something only you could have created.</p>
</div>
<p>要是你只是把 AI 生成的点子原样贴回给 AI，很难得到什么独特的东西，毕竟谁都能这么干。但如果你主动掌舵设计方向，最后得到的就是只有你才做得出来的东西。</p>
<div class="yn-en" lang="en">
<p>Don’t be afraid to try ideas that sound terrible. If you find yourself thinking, “There’s no way this will work,” you’re on the right track. Often, your agent will surprise you, and you’ll realize you were underestimating it. If not, just throw away those results and try something else. But save the prompts that <em>don’t</em> work, and test them again when newer models come out. That way, you’ll know you’re taking full advantage of what the latest models can do.</p>
</div>
<p>别怕试那些听上去很烂的点子。如果你心里在想「这不可能行得通」，那就对了。你的 Agent 常常会给你惊喜，你会发现自己低估了它。没惊喜也没关系，把结果扔掉换个点子就行。不过那些<em>没成</em>的提示词要存好，等新模型出来再试一遍。这样你就知道自己有没有把最新模型的本事用足。</p>
<h2 id="define-deepen-your-design-direction定义-把设计方向挖深" tabindex="-1"><span class="yn-en ignore-header" lang="en">Define: Deepen your design direction</span>定义：把设计方向挖深 <a class="header-anchor" href="#define-deepen-your-design-direction定义-把设计方向挖深" aria-label="本节链接：定义：把设计方向挖深">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>So far, we’ve looked at how to explore a broad set of ideas and hopefully land on a promising initial design. No matter how we prompt, though, our initial AI-generated designs will usually still feel generic.</p>
</div>
<p>到这里，我们讲了怎么大范围地探索点子，争取落到一个有希望的初版设计上。可不管提示词怎么写，AI 生成的初版设计通常还是有股千篇一律的味道。</p>
<div class="yn-en" lang="en">
<p>For example, look at the designs we came up with using seed strings:</p>
</div>
<p>比如看看我们用种子字符串做出来的那几版：</p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/07.webp" alt="用种子字符串做出的落地页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>These have promise, but they’re still relying heavily on the same stale patterns: text on the left with a CTA button below, nav bar up top, graphic on the right.</p>
</div>
<p>它们有潜力，但还是严重依赖那几个老套路：左边文字、下面一个 CTA 按钮，顶上导航栏，右边配图。</p>
<div class="yn-en" lang="en">
<p>Our next goal is to give each design an individual personality through distinct design choices. Below are my favorite techniques to do that.</p>
</div>
<p>下一步的目标，是靠鲜明的设计选择，给每个设计一份自己的个性。下面是我最喜欢的几个技巧。</p>
<h2 id="technique-3-create-positive-feedback-loops-with-subagents技巧-3-用子-agent-搭一个正反馈循环" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 3: Create positive feedback loops with subagents</span>技巧 3：用子 Agent 搭一个正反馈循环 <a class="header-anchor" href="#technique-3-create-positive-feedback-loops-with-subagents技巧-3-用子-agent-搭一个正反馈循环" aria-label="本节链接：技巧 3：用子 Agent 搭一个正反馈循环">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>We need to iterate on our designs to improve them. But simply asking our agent to look at the design and improve it won’t work, because the agent isn’t objective: it reviews its own code, past decisions, and previous rationale. AI can’t easily zoom out, look at the big picture, and “think different.”</p>
</div>
<p>设计要迭代才会变好。可光让 Agent 看看设计、再改好一点，是没用的，因为它不客观：它审的是自己写的代码、自己过去的决策和当初的理由。AI 很难退后一步看全局，去「think different」。</p>
<div class="yn-en" lang="en">
<p>To solve this, instead of letting the coding agent decide when the design is good enough, have it ask <em>another</em> agent—a “design critic.” The critic’s job is to look at screenshots of the current design and provide feedback. It doesn’t care how the current design is implemented or how much effort went into it, only if it actually hits the quality bar.</p>
</div>
<p>解决办法是：别让写代码的 Agent 自己判断设计够不够好，让它去问<em>另一个</em> Agent，一个「设计评审」。评审的活儿是看当前设计的截图、给反馈。它不在乎设计是怎么实现的、花了多少力气，只看它到底有没有达到质量标准。</p>
<div class="yn-en" lang="en">
<p>This approach has an extra benefit: we can use a big, expensive model for the critic without breaking the bank, because we’ll only use it for executive decisions. A cheap, fast model can do the grunt work, while the strong critic model provides taste.</p>
</div>
<p>这么做还有个额外的好处：评审可以用又大又贵的模型，也不至于把钱包掏空，因为它只负责拍板。脏活累活交给便宜快速的模型，品味由强大的评审模型来提供。</p>
<div class="yn-en" lang="en">
<p>Let’s try this on our previous designs, using Claude Fable 5 as the critic:</p>
</div>
<p>我们拿前面那几版设计试一下，用 Claude Fable 5 当评审：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>I want you to improve this design. To figure out what to focus on, use a Fable 5 subagent as a design critic.</em></p>
<p><em>Follow this procedure at each iteration:</em></p>
<ul>
<li><em>Capture a screenshot of the current design</em></li>
<li><em>Invoke the critic in a fresh context, with just the screenshot, not the code, implementation details, or earlier iterations/critiques</em></li>
<li><em>Ask it to evaluate the aesthetic that the design is going for, imagine how a top design studio would execute this aesthetic, then outline the biggest gaps</em></li>
<li><em>Lastly, it should provide a score out of 10 indicating how close the current design is to that studio-level quality bar</em></li>
</ul>
<p><em>Provide this guidance to the critic in its prompt:</em></p>
<ul>
<li><em>It should think high-level about the overall structure and composition as well as look at the fine details</em></li>
<li><em>It should watch out for patterns that feel overdone, excessive, or otherwise obviously AI-generated, and penalize them</em></li>
<li><em>It should provide tight, specific feedback, not vague prose</em></li>
<li><em>It should be bold and opinionated, not rely on what’s safe or easy</em></li>
</ul>
<p><em>Your work is only complete when the critic independently deems it 9/10 or higher. Do not put that criterion in the critic prompt; keep it objective in its scoring. Use the same critic prompt each time.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>我想让你改进这个设计。要搞清楚该集中改哪里，用一个 Fable 5 子 Agent 当设计评审。</em></p>
<p><em>每一轮迭代都按这个步骤来：</em></p>
<ul>
<li><em>给当前设计截一张图</em></li>
<li><em>在全新的上下文里调用评审，只给它截图，不给代码、实现细节，也不给之前的迭代或评审意见</em></li>
<li><em>让它判断这个设计想要的美学风格是什么，想象一家顶级设计工作室会怎样做出这种风格，然后列出最大的差距</em></li>
<li><em>最后，让它打一个满分 10 分的分数，表示当前设计离那种工作室级别的质量标准有多近</em></li>
</ul>
<p><em>在评审的提示词里给它这些指导：</em></p>
<ul>
<li><em>既要从高处想整体的结构和构图，也要看细节</em></li>
<li><em>要留意那些用滥了的、过度的或者一看就是 AI 生成的套路，并且扣分</em></li>
<li><em>反馈要紧凑、具体，不要含糊的长篇大论</em></li>
<li><em>要大胆、有主见，不要只挑稳妥或省事的说</em></li>
</ul>
<p><em>只有评审独立给出 9/10 或更高的分数，你的工作才算完成。不要把这条标准写进评审的提示词里，让它打分时保持客观。每次都用同一份评审提示词。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>Claude Opus 5:</strong></p>
</div>
<p><strong>Claude Opus 5：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/15.webp" alt="经过评审循环改进后的设计" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Instead of the same cookie-cutter layout over and over, each design now has its own identity—but still maintains its original high-level aesthetic.</p>
</div>
<p>不再是一遍又一遍的流水线布局，现在每个设计都有了自己的个性，同时保住了原来那个大方向上的美学风格。</p>
<div class="yn-en" lang="en">
<p>Notably, in each case, Fable accounted for less than 10% of output tokens. Asking Fable to redesign the page directly would have cost twice as much and taken much longer.</p>
</div>
<p>另外，每个例子里 Fable 只占了不到 10% 的输出 token。要是直接让 Fable 重新设计页面，成本会翻倍，时间也长得多。</p>
<div class="yn-en" lang="en">
<p>The way you set these loops up matters a lot. Here are some tips:</p>
</div>
<p>这种循环怎么搭，影响很大。给几条建议：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Make sure the criteria for the critic are as clear and objective as possible.</strong></span><strong>给评审的标准要尽量清楚、客观。</strong>
<ul>
<li><span class="yn-en" lang="en">Bad: “Judge if our design looks beautiful, not AI-generated.” This is too subjective, and the results will vary wildly from run to run.</span>差：「判断我们的设计好不好看、像不像 AI 生成的。」太主观了，每次跑出来的结果会差得离谱。
<ul>
<li><span class="yn-en" lang="en">OK: “Review the aesthetic we’re going for, visualize how a top design studio would execute it, then judge our design’s quality against that bar.” The prompt is still mushy, but it provides a consistent framework and quality bar.</span>还行：「看看我们想要的美学风格，想象一家顶级设计工作室会怎么做，然后拿那个标准来评判我们设计的质量。」提示词还是有点虚，但至少给了一个一致的框架和质量标准。</li>
<li><span class="yn-en" lang="en">Great: “Here are 5 designs: 4 professional examples and 1 screenshot of our product. Rank them by polish and taste level.” This instruction is concrete and objective, and gives a visual baseline for judgment.</span>很好：「这里有 5 个设计：4 个专业案例，1 张我们产品的截图。按精致程度和品味高低给它们排序。」这条指令具体又客观，还给了一个可以拿来比的视觉基准。</li>
</ul>
</li>
</ul>
</li>
<li><span class="yn-en" lang="en"><strong>Provide example images to demonstrate the target quality bar.</strong> You can use comparable screenshots or designs you like, or even AI-generated concept art. Instruct the critic to treat these as a baseline or a moodboard, not a target. You don’t want it to copy other designs outright.</span><strong>给出示例图片，说明目标质量是什么水平。</strong> 可以用同类产品的截图、你喜欢的设计，甚至 AI 生成的概念图。告诉评审把这些当作基准或情绪板（moodboard），不是照着做的目标。你可不想它直接抄别人的设计。</li>
<li><span class="yn-en" lang="en"><strong>Set the stopping criteria carefully.</strong> Otherwise, the critic may never consider the design good enough, and your agent will helplessly burn tokens trying to please it. Prompt it to do one or two iterations first, and see if it’s converging before adding more.</span><strong>停止条件要谨慎设定。</strong> 不然评审可能永远觉得设计不够好，你的 Agent 只能无奈地烧 token 去讨好它。先让它跑一两轮，看看有没有在收敛，再决定加不加轮次。</li>
<li><span class="yn-en" lang="en"><strong>Choose the right model for each job.</strong> Consider bigger models for the critic role, since more parameters generally translate to better design sense and a wider distribution of ideas. Small models can be effective as the implementer, but don’t go too small. You still need a model that’s capable of executing a design direction well.</span><strong>每个活儿选对模型。</strong> 评审可以考虑用更大的模型，参数越多，一般设计感越好、点子的分布也越广。小模型当实现者可以很好用，但别太小，你还是需要一个能把设计方向执行到位的模型。</li>
</ul>
<h2 id="technique-4-use-image-generation-to-enrich-designs技巧-4-用图像生成让设计更丰富" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 4: Use image generation to enrich designs</span>技巧 4：用图像生成让设计更丰富 <a class="header-anchor" href="#technique-4-use-image-generation-to-enrich-designs技巧-4-用图像生成让设计更丰富" aria-label="本节链接：技巧 4：用图像生成让设计更丰富">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Coding agents love to write code, but they usually don’t incorporate images. Instead, they tend to use the easy code-based alternatives: gradients, shapes, and basic patterns. Those are all strong giveaways of an AI-generated design.</p>
</div>
<p>编程 Agent 爱写代码，但通常不往设计里放图片。它们更喜欢用代码就能搞定的省事替代品：渐变、形状、基础图案。这些全都是 AI 设计的明显破绽。</p>
<div class="yn-en" lang="en">
<p>Some agents have image tools built in, but they underutilize them. Others don’t have image tools out of the box but can easily use the OpenAI or Gemini APIs to generate images with an API key.</p>
</div>
<p>有些 Agent 内置了图像工具，但用得很少。还有些开箱没有图像工具，不过给个 API key，它们就能轻松调用 OpenAI 或 Gemini 的 API 来生成图片。</p>
<div class="yn-en" lang="en">
<p>Let’s try this on the designs from the last step:</p>
</div>
<p>我们拿上一步的设计试一下：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>The design is pretty plain. Add more personality using image generation. Consider shaders or 3D effects in combination with images to create more interesting visuals.</em></p>
<p><em>For image generation, use this OpenAI API key (only use it locally, do not store it in the code or product): sk-a1b2c3d4…</em></p>
<p><em>Verify that your work looks right frame-by-frame in the browser.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>这个设计挺平淡的。用图像生成给它加点个性。可以考虑把着色器或 3D 效果和图片结合起来，做出更有意思的画面。</em></p>
<p><em>图像生成用这个 OpenAI API key（只在本地用，不要存进代码或产品里）：sk-a1b2c3d4…</em></p>
<p><em>在浏览器里逐帧确认效果是对的。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>Claude Opus 5 (before and after):</strong></p>
</div>
<p><strong>Claude Opus 5（改前和改后）：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/16.webp" alt="加入图像生成前后对比 1" loading="lazy"></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/17.webp" alt="加入图像生成前后对比 2" loading="lazy"></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/18.webp" alt="加入图像生成前后对比 3" loading="lazy"></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/19.webp" alt="加入图像生成前后对比 4" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Images and effects like these can quickly add a lot of personality and make a design less obviously AI-generated, since they demonstrate more than surface-level effort.</p>
</div>
<p>这类图片和效果能很快给设计加上不少个性，也让它没那么明显像 AI 做的，因为看得出来下的功夫不只停在表面。</p>
<div class="yn-en" lang="en">
<p>Depending on your setup, there are different ways to connect your agent to image generation tools:</p>
</div>
<p>把 Agent 接上图像生成工具，按你的环境有几种办法：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>If you use Codex, Antigravity, or Grok Build:</strong></span><strong>如果你用 Codex、Antigravity 或 Grok Build：</strong>
<ul>
<li><span class="yn-en" lang="en">Tell your agent to use its built-in image generation. The agent already knows how to do this but rarely does so until instructed.</span>告诉 Agent 用它内置的图像生成。它本来就会，只是你不开口它很少主动用。</li>
</ul>
</li>
<li><span class="yn-en" lang="en"><strong>If you use Claude Code or another agent but also have a ChatGPT subscription:</strong></span><strong>如果你用 Claude Code 或别的 Agent，但同时订了 ChatGPT：</strong>
<ul>
<li><span class="yn-en" lang="en">Tell your agent, “Use the Codex CLI to generate images. Help me install it if it isn’t already present. Make sure it’s billing my subscription, not an API key.” This lets you use your ChatGPT subscription for image generation without extra costs.</span>告诉 Agent：「用 Codex CLI 生成图片。还没装的话帮我装上。确保扣的是我的订阅，不是 API key。」这样就能拿 ChatGPT 订阅来生成图片，不额外花钱。</li>
</ul>
</li>
<li><span class="yn-en" lang="en"><strong>If you only use Claude, or any other tool:</strong></span><strong>如果你只用 Claude，或者别的什么工具：</strong>
<ul>
<li><span class="yn-en" lang="en">The simplest path is to give your agent an OpenAI or Gemini API key to generate images. I recommend creating a separate API key with a tight spend limit, just for your agent. That way, your costs are controlled even if the key gets out or the agent misuses it, and you can easily revoke the key without disrupting other work.</span>最简单的办法是给 Agent 一个 OpenAI 或 Gemini 的 API key 来生成图片。我建议单独建一个专给 Agent 用的 API key，把消费上限设紧一点。这样就算 key 泄露了或者 Agent 乱用，花费也在控制之内，而且随时可以吊销，不影响别的工作。
<ul>
<li><span class="yn-en" lang="en">If you find yourself pasting keys into chats frequently, put them in a file instead, and point your agent to it in your project. Tell your agent: “Create a gitignored file called .env.agents, store this API key in it, and note to yourself in AGENTS.md/CLAUDE.md that these keys are for you to use during development (but must not ship with the product).”</span>如果你发现自己老是往对话里贴 key，那就把它们放进一个文件，在项目里告诉 Agent 去哪找。跟 Agent 说：「建一个被 gitignore 的文件，叫 .env.agents，把这个 API key 存进去，再在 AGENTS.md/CLAUDE.md 里给自己记一笔：这些 key 是开发时给你用的（但绝不能跟着产品发出去）。」</li>
</ul>
</li>
</ul>
</li>
</ul>
<h2 id="technique-5-for-more-advanced-motion-use-video-generation技巧-5-想要更高级的动效-用视频生成" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 5: For more advanced motion, use video generation</span>技巧 5：想要更高级的动效，用视频生成 <a class="header-anchor" href="#technique-5-for-more-advanced-motion-use-video-generation技巧-5-想要更高级的动效-用视频生成" aria-label="本节链接：技巧 5：想要更高级的动效，用视频生成">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Video generation models are incredibly powerful these days, but most people think of them as tools for generating UGC ads or clips of Will Smith eating spaghetti. They can work wonders for everyday design work too.</p>
</div>
<p>如今的视频生成模型强得离谱，可大多数人只把它们当成做 UGC 广告、或者生成威尔·史密斯吃意大利面片段的工具。其实它们在日常设计工作里也能创造奇迹。</p>
<div class="yn-en" lang="en">
<p>There are many video models out there, and the best ones change frequently, so I like to use an aggregator platform like <a href="http://fal.ai/" target="_blank" rel="noreferrer">fal.ai</a>. This way, we can give our agent a single API key and let it evaluate different options and choose the best one without needing multiple integrations.</p>
</div>
<p>视频模型很多，最好的那几个又换得很勤，所以我喜欢用 <a href="http://fal.ai/" target="_blank" rel="noreferrer">fal.ai</a> 这样的聚合平台。这样只用给 Agent 一个 API key，让它自己评估各种选项、挑最好的，不用一个个去接。</p>
<div class="yn-en" lang="en">
<p>Here are two ways I love to use video models in my designs:</p>
</div>
<p>把视频模型用进设计里，我最喜欢这两种用法：</p>
<h4 id="create-stunning-animated-graphics做出惊艳的动态图形" tabindex="-1"><span class="yn-en ignore-header" lang="en">Create stunning animated graphics</span>做出惊艳的动态图形 <a class="header-anchor" href="#create-stunning-animated-graphics做出惊艳的动态图形" aria-label="本节链接：做出惊艳的动态图形">&ZeroWidthSpace;</a></h4>
<div class="yn-en" lang="en">
<p>The trick is to generate a looping clip with a solid color background, then either chroma key it out (like a green screen) or, in more complex cases, use a video matting model to remove the background. This gives you an animation that you can layer anywhere in your UI without it looking like a video.</p>
</div>
<p>诀窍是先生成一段纯色背景的循环片段，然后要么用色键抠掉背景（就像绿幕），要么在更复杂的情况下用视频抠像（video matting）模型去掉背景。这样得到的动画可以叠在界面里任何地方，看上去一点也不像一段视频。</p>
<div class="yn-en" lang="en">
<p>For example, I took one of our previous designs and ran this prompt:</p>
</div>
<p>比如我拿前面的一个设计，跑了这条提示词：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Can you replace the image on this page with a looping video clip that does something more interesting? Have the crystal splinter apart and slowly spin around. It should have awesome glassy effects that refract the page background and cast shadows and light around it.</em></p>
<p><em>To get convincing glass refraction effects, render the video of the glass over the page background colors first (so it bakes in the refraction effects), then remove the background with a video matting model.</em></p>
<p><em>Use this fal.ai API key: sk-a1b2c3d4…</em></p>
<p><em>Find appropriate recent models for video generation and background removal.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>能不能把这个页面上的图片换成一段更有意思的循环视频？让水晶碎裂开，然后慢慢旋转。要有很棒的玻璃质感，能折射页面背景，在周围投下阴影和光。</em></p>
<p><em>为了让玻璃折射看起来可信，先把玻璃叠在页面背景色上渲染成视频（这样折射效果就烘焙进去了），再用视频抠像模型去掉背景。</em></p>
<p><em>用这个 fal.ai API key：sk-a1b2c3d4…</em></p>
<p><em>找一些合适的、比较新的模型来做视频生成和背景去除。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>GPT-5.6 Sol (before and after):</strong></p>
</div>
<p><strong>GPT-5.6 Sol（改前和改后）：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/20.webp" alt="水晶碎裂旋转的循环视频前后对比" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>This is a much richer effect than you can get with code: interesting caustic reflections, glassy refraction effects, and complex physical motion.</p>
</div>
<p>这效果比用代码能做出来的丰富得多：有意思的焦散反光、玻璃折射，还有复杂的物理运动。</p>
<h4 id="create-fluid-transitions-between-states在状态之间做出流畅的过渡" tabindex="-1"><span class="yn-en ignore-header" lang="en">Create fluid transitions between states</span>在状态之间做出流畅的过渡 <a class="header-anchor" href="#create-fluid-transitions-between-states在状态之间做出流畅的过渡" aria-label="本节链接：在状态之间做出流畅的过渡">&ZeroWidthSpace;</a></h4>
<div class="yn-en" lang="en">
<p>This is a really underrated use case for video models. In addition to generating video from text, many video models can interpolate between keyframe images. This lets you take two product stills and create a transition clip between them. You can play the clip when the user takes an action (like navigating to another screen of your app) or scrub through it frame-by-frame in response to a gesture (like scrolling or swiping).</p>
</div>
<p>这是视频模型一个被严重低估的用法。很多视频模型除了能从文本生成视频，还能在关键帧图片之间插帧。也就是说，你可以拿两张产品静态图，生成一段它们之间的过渡片段。用户做某个操作时（比如跳到应用的另一个页面）播放这段片段，或者跟着手势（比如滚动、滑动）逐帧拖动它。</p>
<div class="yn-en" lang="en">
<p>Here’s a demo page showing off a scroll effect. I built it with a single prompt using GPT-5.6 Sol in Codex:</p>
</div>
<p>下面是一个展示滚动效果的 demo 页面，我在 Codex 里用 GPT-5.6 Sol 一条提示词做出来的：</p>
<div class="yn-en" lang="en">
<p><strong>Prompt:</strong></p>
</div>
<p><strong>提示词：</strong></p>
<div class="yn-en" lang="en">
<blockquote>
<p><em>Build a demo page for a suitcase that uses a video model to create interactive transitions between a couple of screens. Each screen should show the suitcase in a different state, with vertical motion that feels appropriate for scrolling:</em></p>
<ul>
<li><em>Initially, have the suitcase floating high up in the air</em></li>
<li><em>Then have it land on the floor and pop open</em></li>
<li><em>Finally, have its contents neatly land into it from the top</em></li>
</ul>
<p><em>Generate the initial frame using your image generation skill. Then, generate a video clip that starts from that frame and animates to the next state. Use the final frame of that video to seed the next transition so that it continues seamlessly. Scrub through the transitions one by one as the user scrolls.</em></p>
<p><em>Use this fal.ai API key: sk-a1b2c3d4…</em></p>
<p><em>Use a video model with strong physics and consistency, like Seedance 2.5.</em></p>
</blockquote>
</div>
<blockquote>
<p><em>给一个行李箱做个 demo 页面，用视频模型在几屏之间做可交互的过渡。每一屏展示行李箱的一种状态，运动方向是竖直的，配合滚动的感觉：</em></p>
<ul>
<li><em>一开始，行李箱高高地飘在空中</em></li>
<li><em>接着它落到地上，弹开</em></li>
<li><em>最后，里面的东西从上方整整齐齐地落进去</em></li>
</ul>
<p><em>用你的图像生成 skill 生成第一帧。然后生成一段从这一帧开始、动到下一个状态的视频片段。用这段视频的最后一帧作为下一段过渡的起点，让它无缝接上。用户滚动时，一段一段地拖动这些过渡。</em></p>
<p><em>用这个 fal.ai API key：sk-a1b2c3d4…</em></p>
<p><em>用一个物理效果和一致性都很强的视频模型，比如 Seedance 2.5。</em></p>
</blockquote>
<div class="yn-en" lang="en">
<p><strong>GPT-5.6 Sol:</strong></p>
</div>
<p><strong>GPT-5.6 Sol：</strong></p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/21.webp" alt="随滚动播放过渡的行李箱 demo 页" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The transitions between pages scrub fluidly with the user’s scrolling and are fun to play with. Design like this makes the user <em>want</em> to keep scrolling and reading more about your product. And it only took one prompt!</p>
</div>
<p>页面之间的过渡跟着用户的滚动流畅地走，玩起来很好玩。这样的设计会让用户<em>想</em>一直往下滚，多看看你的产品。而且只用了一条提示词！</p>
<h2 id="deliver-polish-your-design-into-something-users-will-love交付-把设计打磨成用户会爱上的东西" tabindex="-1"><span class="yn-en ignore-header" lang="en">Deliver: Polish your design into something users will love</span>交付：把设计打磨成用户会爱上的东西 <a class="header-anchor" href="#deliver-polish-your-design-into-something-users-will-love交付-把设计打磨成用户会爱上的东西" aria-label="本节链接：交付：把设计打磨成用户会爱上的东西">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Once we’ve gotten to a unique, standout design, the final step is to clean up the details and get it ready for production use. AI can build amazing, striking visuals, but your judgment will be key to making sure the design makes sense, flows well, and serves its practical purpose for your users.</p>
</div>
<p>拿到一个独特、出挑的设计之后，最后一步是把细节收拾干净，让它能上生产。AI 能做出惊艳、抓眼球的画面，但设计合不合理、顺不顺、能不能真正为用户所用，关键还得靠你的判断。</p>
<h2 id="technique-6-cut-out-elements-that-don-t-add-value技巧-6-砍掉没有价值的元素" tabindex="-1"><span class="yn-en ignore-header" lang="en">Technique 6: Cut out elements that don’t add value</span>技巧 6：砍掉没有价值的元素 <a class="header-anchor" href="#technique-6-cut-out-elements-that-don-t-add-value技巧-6-砍掉没有价值的元素" aria-label="本节链接：技巧 6：砍掉没有价值的元素">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>AI loves to add more, but it rarely takes away. One of the biggest signs that a design is AI-generated is that it overexplains everything or contains elements that don’t serve any practical purpose. By contrast, a design that exercises restraint immediately looks premium and tasteful.</p>
</div>
<p>AI 爱加东西，很少减。一个设计是 AI 做的，最明显的标志之一就是什么都解释过头，或者塞着一些毫无实际用途的元素。反过来，一个懂得克制的设计，一眼看上去就高级、有品味。</p>
<div class="yn-en" lang="en">
<p>When polishing AI designs, most of my effort goes into removing things. For example, when I was building my calorie tracking app, this was my initial design from Claude:</p>
</div>
<p>打磨 AI 设计时，我大部分力气都花在删东西上。比如做那个记卡路里的应用时，Claude 给我的初版设计是这样的：</p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/22.webp" alt="Claude 给出的卡路里应用初版设计" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>I’d described the app’s functionality and specifically asked for a “clean, minimalist design.” The results weren’t bad, and were certainly impressive for being fully AI-generated. However, despite my asking for minimalism, a lot in the design wasn’t adding value:</p>
</div>
<p>我描述了应用的功能，还特意要了「干净、极简的设计」。结果不算差，作为完全由 AI 生成的东西，确实挺厉害。可尽管我要的是极简，设计里还是有很多东西没带来任何价值：</p>
<ul>
<li><span class="yn-en" lang="en">Pink glowy effects in the background and on the progress bar</span>背景和进度条上粉色的发光效果</li>
<li><span class="yn-en" lang="en">Random colors and highlights on text</span>文字上随意的颜色和高亮</li>
<li><span class="yn-en" lang="en">Extra labels and empty space when displaying all the foods for a day, when the images already communicate this</span>展示一天吃的所有食物时多余的标签和空白，图片本身已经把信息说清楚了</li>
<li><span class="yn-en" lang="en">Custom buttons and text fields that look worse than built-in iOS components</span>自定义的按钮和输入框，比 iOS 自带组件还难看</li>
</ul>
<div class="yn-en" lang="en">
<p>I asked Claude to dial things back:</p>
</div>
<p>我让 Claude 收一收：</p>
<ul>
<li><span class="yn-en" lang="en">Simplify the layout into an image-centric grid</span>把布局简化成以图片为中心的网格</li>
<li><span class="yn-en" lang="en">Get rid of gradients, glows, and unnecessary containers</span>去掉渐变、发光和不必要的容器</li>
<li><span class="yn-en" lang="en">Aim for a truly minimalist aesthetic that feels Apple-native</span>做到真正的极简，有 Apple 原生的感觉</li>
</ul>
<div class="yn-en" lang="en">
<p>This was the result:</p>
</div>
<p>结果是这样的：</p>
<p><img src="https://nyann.cc/posts/how-to-turn-your-ai-into-a-world-class-designer/23.webp" alt="收敛之后的卡路里应用设计" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>To my trained eye, the result is <em>much</em> better. It’s opinionated and allows the visuals to speak for themselves. It uses native iOS components, and the excessive colors and gradients are gone. The text is smaller, simpler, and tighter. This is good design.</p>
</div>
<p>以我练过的眼光看，这版<em>好太多了</em>。它有自己的主张，让画面自己说话。用的是 iOS 原生组件，过多的颜色和渐变都没了。文字更小、更简单、更紧凑。这才是好设计。</p>
<div class="yn-en" lang="en">
<p>Today’s AI models would never think to make these choices on their own. Remember, AI doesn’t like to take risks, and it’s risky to strip down a design and delete code. The model needs a push from you. Look over your design and ask yourself what really needs to be there. Often, putting less on the screen communicates <em>more</em>, because you can hold your users’ attention without overwhelming them with clutter.</p>
</div>
<p>现在的 AI 模型自己永远想不到要这么选。记住，AI 不喜欢冒险，而把设计扒到只剩骨架、删掉代码，本身就有风险。模型需要你推一把。把你的设计从头看一遍，问问自己哪些东西是真正必须在那儿的。很多时候，屏幕上放得越少，传达的反而<em>越多</em>，因为用户的注意力被抓住了，又不会被一堆杂乱的东西淹没。</p>
]]></content:encoded>
</item>
<item>
<title>Claude Tag 怎样当上 Anthropic CI/CD 故障的第一响应人</title>
<link>https://nyann.cc/posts/Claude%20Tag%20%E6%80%8E%E6%A0%B7%E5%BD%93%E4%B8%8A%20Anthropic%20CICD%20%E6%95%85%E9%9A%9C%E7%9A%84%E7%AC%AC%E4%B8%80%E5%93%8D%E5%BA%94%E4%BA%BA</link>
<guid isPermaLink="true">https://nyann.cc/posts/Claude%20Tag%20%E6%80%8E%E6%A0%B7%E5%BD%93%E4%B8%8A%20Anthropic%20CICD%20%E6%95%85%E9%9A%9C%E7%9A%84%E7%AC%AC%E4%B8%80%E5%93%8D%E5%BA%94%E4%BA%BA</guid>
<pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
<description>Anthropic 持续集成团队的工程师讲他们怎么让 Claude Tag 在 Slack 里值班：从发现告警、排查根因、修复，到验证、通报和交接，CI 故障的每一步 Claude 都先顶上去。</description>
<category>翻译</category>
<category>AI</category>
<category>Claude</category>
<category>运维</category>
<category>CI/CD</category>
<content:encoded><![CDATA[<h1 id="claude-tag-怎样当上-anthropic-ci-cd-故障的第一响应人" tabindex="-1">Claude Tag 怎样当上 Anthropic CI/CD 故障的第一响应人 <a class="header-anchor" href="#claude-tag-怎样当上-anthropic-ci-cd-故障的第一响应人" aria-label="本节链接：Claude Tag 怎样当上 Anthropic CI/CD 故障的第一响应人">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p><em><a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">Set up your own Claude on-call with our setup kit</a>.</em></p>
</div>
<p><em><a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">用我们的配置套件，给自己也配一个值班的 Claude</a>。</em></p>
<h2 id="ai-incident-response-for-ci-cd-claude-on-call-at-anthropic用-ai-处理-ci-cd-故障-claude-在-anthropic-值班" tabindex="-1"><span class="yn-en ignore-header" lang="en">AI incident response for CI/CD: Claude on call at Anthropic</span>用 AI 处理 CI/CD 故障：Claude 在 Anthropic 值班 <a class="header-anchor" href="#ai-incident-response-for-ci-cd-claude-on-call-at-anthropic用-ai-处理-ci-cd-故障-claude-在-anthropic-值班" aria-label="本节链接：用 AI 处理 CI/CD 故障：Claude 在 Anthropic 值班">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>A few weeks ago, I was on-call and my colleague Slacked me a message at 10pm: roughly 44 tests on a new service weren’t firing.</p>
</div>
<p>几周前轮到我值班，晚上 10 点同事在 Slack 上找我：一个新服务上大概有 44 个测试没跑起来。</p>
<div class="yn-en" lang="en">
<p>In the past, I would have stopped what I was doing, sat down with my laptop, sighed wearily, and began an hour-long investigate-and-fix process. But now, my workflow is entirely different: I pull in @Claude, and ask what it sees.</p>
</div>
<p>搁以前，我得放下手头的事，抱着电脑坐下，长叹一口气，然后开始一个小时左右的排查加修复。现在我的做法完全不一样了：把 @Claude 拉进来，问它看到了什么。</p>
<div class="yn-en" lang="en">
<p>In this case, Claude found the tests disappeared when a feature flag got turned on that morning, and also that it would be safe to revert. I asked my colleague to revert the flag. Claude pinged me on Slack 3 minutes later to verify the skip rules had indeed been removed and the error rate was back to baseline.</p>
</div>
<p>这一回，Claude 查出来那天早上打开了一个功能开关（feature flag），测试就是从那时候开始不见的，它还确认了回滚是安全的。我让同事把开关回滚了。3 分钟后 Claude 在 Slack 上找我，确认跳过规则确实已经撤掉，错误率也回到了基线。</p>
<p><img src="https://nyann.cc/posts/how-claude-tag-serves-as-anthropics-first-responder-for-ci-cd-failures/f5b4aa5251da65b25186018374984cef9d44996d.webp" alt="Slack 里值班工程师和 Claude 关于 44 个测试没有运行的对话" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Redesigned from a real exchange for clarity.</p>
</div>
<p>根据一次真实对话重新排版，便于阅读。</p>
<div class="yn-en" lang="en">
<p>For the last several months Claude Tag has been the on-call first responder for CI/CD failures at Anthropic. Not only has this helped with our social lives, it has given every CI incident an instant first responder: Claude authored the first situation report in every recent incident that had one, <strong>typically publishing its first analysis within 15 minutes.</strong></p>
</div>
<p>过去几个月，Claude Tag 一直是 Anthropic CI/CD 故障的值班第一响应人。这救了我们的社交生活，也让每一起 CI 故障都立刻有人接手：最近凡是写了态势报告（situation report）的故障，第一份都是 Claude 写的，<strong>通常在 15 分钟内就发出第一份分析。</strong></p>
<div class="yn-en" lang="en">
<p>In this article we’ll walk through what we built and how it works so you can build it yourself and stop dreading your turn in the rotation.</p>
</div>
<p>这篇文章会讲我们搭了什么、它怎么运转，好让你也能自己搭一套，不用再怕轮到自己值班。</p>
<h2 id="our-claude-on-call-setup我们给-claude-配的值班环境" tabindex="-1"><span class="yn-en ignore-header" lang="en">Our Claude on call setup</span>我们给 Claude 配的值班环境 <a class="header-anchor" href="#our-claude-on-call-setup我们给-claude-配的值班环境" aria-label="本节链接：我们给 Claude 配的值班环境">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Before we go into each stage of the incident response process, I’ll provide a general overview of our setup here so you have the big picture in mind as we fill in the details.</p>
</div>
<p>在逐个讲故障响应的各个阶段之前，我先大致介绍一下整体配置，这样后面补细节的时候你心里有张全景图。</p>
<div class="yn-en" lang="en">
<p>An on-call agent needs <strong>memory</strong> so it remembers what’s been done; <strong>connections and access</strong> so it can investigate, understand, and act; <strong>schedules</strong> so it knows when to get back to work; and <strong>instructions</strong> so it knows what to do.</p>
</div>
<p>一个值班 agent 需要这几样：<strong>记忆</strong>，记得做过什么；<strong>连接和权限</strong>，才能调查、理解、动手；<strong>日程</strong>，知道什么时候该回来干活；<strong>指令</strong>，知道该做什么。</p>
<div class="yn-en" lang="en">
<p><a href="https://claude.com/product/tag" target="_blank" rel="noreferrer">Claude Tag</a> is the backbone of our on-call agent. Claude Tag holds memory across our on-call Slack channel and the interface to provide per-turn instructions during an incident. Claude also acts in real time to events in the on-call channel and others. The scheduling of routines, or the regular actions Claude takes, happens on this channel as well with natural language prompts like “run CI handoff every Monday at 9:00am EST.”</p>
</div>
<p><a href="https://claude.com/product/tag" target="_blank" rel="noreferrer">Claude Tag</a> 是我们值班 agent 的骨架。它在整个值班 Slack 频道里保留记忆，也是故障期间我们一轮一轮给它下指令的界面。值班频道和其他频道里有什么动静，Claude 都会实时响应。例行任务（routines），也就是 Claude 定期要做的事，同样在这个频道里安排，用自然语言说一句就行，比如「每周一美东时间早上 9 点做一次 CI 交接」。</p>
<div class="yn-en" lang="en">
<p><a href="https://claude.com/resources/articles/agent-identity-access-model" target="_blank" rel="noreferrer">Claude Tag has its own service account</a> and access to the tools an Anthropic CI engineer needs such as Datadog or Grafana. This was set up one time by an administrator for the channel (<a href="https://claude.com/docs/claude-tag/admins/setup-overview#choose-which-tools-to-connect" target="_blank" rel="noreferrer">here’s how</a>).</p>
</div>
<p><a href="https://claude.com/resources/articles/agent-identity-access-model" target="_blank" rel="noreferrer">Claude Tag 有自己的服务账号</a>，能用 Anthropic CI 工程师需要的那些工具，比如 Datadog 和 Grafana。这些是管理员给这个频道一次性配好的（<a href="https://claude.com/docs/claude-tag/admins/setup-overview#choose-which-tools-to-connect" target="_blank" rel="noreferrer">配置方法见这里</a>）。</p>
<div class="yn-en" lang="en">
<p>In addition to the on-call channel, we set up Claude to watch other relevant channels that also have Claude Tag as a member so it can get additional context like service alerts, configuration changes, or updates on PRs.</p>
</div>
<p>除了值班频道，我们还让 Claude 盯着其他几个相关频道（这些频道里也加了 Claude Tag），好拿到更多上下文，比如服务告警、配置变更、PR 的进展。</p>
<div class="yn-en" lang="en">
<p>Standing instructions are in markdown files as skills, committed in a GitHub repository. This way multiple teammates can iterate on them and we can manage changes just like we do code. It also includes key information like routing instructions, policies, and a log of lessons learned as part of a self-improvement loop.</p>
</div>
<p>长期指令以 skill 的形式写在 markdown 文件里，提交到一个 GitHub 仓库。这样好几个队友都能一起改，变更也能像代码一样管理。仓库里还放着路由规则、各项策略这些关键信息，以及一份经验教训日志，这是自我改进循环的一部分。</p>
<div class="yn-en" lang="en">
<p>This setup took us hours, not days. We created a generalized <a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">on-call setup kit</a> in GitHub that can help get you started with a similar agent. It transforms your team's own incident history into triage playbooks and leaves you with a read-only Claude in your incident channel that diagnoses, escalates, and learns. <a href="https://github.com/anthropics/oncall-kit/blob/main/test-fixtures/RUNBOOK.md" target="_blank" rel="noreferrer">You can watch it run against a fictional team's history</a> in about ten minutes.</p>
</div>
<p>整套配置花了我们几个小时，不是几天。我们在 GitHub 上做了一个通用的<a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">值班配置套件</a>，能帮你起步搭一个类似的 agent。它会把你们团队自己的故障历史变成排查手册（triage playbook），最后在故障频道里给你留下一个只读的 Claude，负责诊断、升级和学习。<a href="https://github.com/anthropics/oncall-kit/blob/main/test-fixtures/RUNBOOK.md" target="_blank" rel="noreferrer">你可以看它拿一个虚构团队的历史跑一遍</a>，大概十分钟。</p>
<div class="yn-en" lang="en">
<p>To summarize the steps TL;DR fashion</p>
</div>
<p>步骤简单归纳一下：</p>
<ul>
<li><span class="yn-en" lang="en">You’ll need a <a href="https://support.claude.com/en/collections/9387370-team-and-enterprise-plans" target="_blank" rel="noreferrer">Claude Team or Claude Enterprise</a> plan</span>你得有 <a href="https://support.claude.com/en/collections/9387370-team-and-enterprise-plans" target="_blank" rel="noreferrer">Claude Team 或 Claude Enterprise</a> 套餐</li>
<li><span class="yn-en" lang="en">The organization owner needs to add Claude to the on call Slack channel via Claude Tag</span>组织所有者要通过 Claude Tag 把 Claude 加进值班 Slack 频道</li>
<li><span class="yn-en" lang="en">The org owner also needs to help connect Claude in the on-call Slack channel to the appropriate connectors, GitHub repo, and set up <a href="https://code.claude.com/docs/en/remote-control" target="_blank" rel="noreferrer">Claude Code Remote</a>.</span>组织所有者还要帮忙给值班频道里的 Claude 接上合适的连接器（connector）和 GitHub 仓库，并配好 <a href="https://code.claude.com/docs/en/remote-control" target="_blank" rel="noreferrer">Claude Code Remote</a>。</li>
<li><span class="yn-en" lang="en">Add Claude to your incident channel and instruct it to monitor for incidents and immediately triage</span>把 Claude 加进故障频道，让它盯着故障、一出事马上排查</li>
</ul>
<div class="yn-en" lang="en">
<p>Now, let’s dive into the details of what this transformation looks like at each step of an incident.</p>
</div>
<p>下面挨个看看，故障处理的每一步都变成了什么样。</p>
<h2 id="detection发现" tabindex="-1"><span class="yn-en ignore-header" lang="en">Detection</span>发现 <a class="header-anchor" href="#detection发现" aria-label="本节链接：发现">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Claude doesn’t just transform how you respond to incidents, it transforms how you detect them in the first place. Previously, there were two major failure modes for detecting incidents.</p>
</div>
<p>有了 Claude，变的除了响应故障的方式，还有一开始发现故障的方式。以前发现故障这件事主要有两种失灵的情况。</p>
<div class="yn-en" lang="en">
<p>It's hard for humans to have the foresight to set perfect rules with perfect thresholds all the time. It's especially difficult when you don't have enough data to analyze traffic patterns.</p>
</div>
<p>人很难每次都有先见之明，定出完美的规则、完美的阈值。手上没有足够的数据去分析流量规律的时候就更难了。</p>
<div class="yn-en" lang="en">
<p>To address this, we have Claude analyze the data and incoming alerts for the first few days of a new service to suggest additional rules and to fine-tune any that are overly broad or narrow.</p>
</div>
<p>为此，新服务上线的头几天，我们让 Claude 分析数据和进来的告警，建议该补哪些规则，把太宽或太窄的规则调一调。</p>
<div class="yn-en" lang="en">
<p>The second major failure mode for detecting incidents was alert fatigue: checking and vetting every alert that fires is tedious. However, Claude doesn’t get fatigued the same way a human does.</p>
</div>
<p>第二种失灵是告警疲劳（alert fatigue）：每条触发的告警都要查一遍、核一遍，太磨人了。不过 Claude 不会像人那样疲劳。</p>
<div class="yn-en" lang="en">
<p>Claude monitors every relevant alert in each alert channel and goes through the criteria in the <a href="https://github.com/anthropics/oncall-kit/blob/main/templates/ONCALL.md" target="_blank" rel="noreferrer">root oncall.md file</a> to determine if it can wait until the morning or if the on-call needs a page. For example, once tuned from analyzing the data, a rule in the file could be, “If the error rate is greater than 2% for longer than 5 minutes AND it's not a known deploy window, page the on-call otherwise write it to lessons.md.”</p>
</div>
<p>Claude 盯着每个告警频道里的每条相关告警，按<a href="https://github.com/anthropics/oncall-kit/blob/main/templates/ONCALL.md" target="_blank" rel="noreferrer">根目录 oncall.md 文件</a>里的标准逐条过，判断是能等到早上，还是得马上呼值班的人。比如分析完数据调好之后，文件里的一条规则可能是：「如果错误率超过 2% 且持续超过 5 分钟，并且不在已知的部署窗口内，就呼叫值班人员，否则写进 lessons.md。」</p>
<div class="yn-en" lang="en">
<p>There are two other ways the Claude on-call alert process can trigger:</p>
</div>
<p>Claude 的值班告警流程还有另外两种触发方式：</p>
<ul>
<li><span class="yn-en" lang="en">A member of the CI team can report an issue in the on-call channel, as was the case in the opening example of 44 missing tests; or</span>CI 团队的成员在值班频道里报问题，开头那个 44 个测试没跑的例子就是这样；或者</li>
<li><span class="yn-en" lang="en">Anyone in the company can open an incident through an internal page. If it’s marked as a CI infrastructure incident then a Slack channel is provisioned for that incident and our on-call Claude picks it up.</span>公司里任何人都能通过一个内部页面开故障单。如果标成 CI 基础设施故障，系统就会给这起故障建一个 Slack 频道，由我们值班的 Claude 接手。</li>
</ul>
<p><img src="https://nyann.cc/posts/how-claude-tag-serves-as-anthropics-first-responder-for-ci-cd-failures/9d24b607b92b034267c9c6095a6bffb2030f1158.webp" alt="告警与升级流程：确定性的告警路径和兼有确定性、agent 两条路径的值班升级" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The key takeaway here is that the alerting process is deterministic, while on-call escalation has both deterministic and agentic paths.</p>
</div>
<p>这里要记住的是：告警流程是确定性的，而值班升级既有确定性的路径，也有 agent 自主判断的路径。</p>
<h2 id="triage排查" tabindex="-1"><span class="yn-en ignore-header" lang="en">Triage</span>排查 <a class="header-anchor" href="#triage排查" aria-label="本节链接：排查">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>It's one thing to have Claude filter through the alert noise, but the real savings comes from the investigation. Claude posts its first evidence-grounded analysis a median of 14 minutes after an incident opens, and in the fastest cases names the root cause within 4 minutes in its first report.</p>
</div>
<p>让 Claude 从一堆告警噪音里筛东西是一回事，真正省下大把时间的是调查。故障开出来之后，Claude 发出第一份有证据支撑的分析，中位数是 14 分钟；最快的几次，它在 4 分钟内的第一份报告里就点出了根因。</p>
<div class="yn-en" lang="en">
<p>When an alert has been escalated to an incident, Claude is often ready in our Slack channel with a hypothesis grounded in evidence that we can review. Claude Tag kicks off a <a href="https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code" target="_blank" rel="noreferrer">dynamic workflow</a> with an orchestration agent that spins up executor subagents to investigate each dependency and source of truth.</p>
</div>
<p>一条告警升级成故障的时候，Claude 往往已经在 Slack 频道里等着了，带着一个有证据支撑的假设给我们审。Claude Tag 会启动一个<a href="https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code" target="_blank" rel="noreferrer">动态工作流</a>：由一个编排 agent 拉起若干执行子 agent，分头去查每个依赖和每个事实来源。</p>
<div class="yn-en" lang="en">
<p>For us that’s Grafana, our log store, PagerDuty, GitHub, Kubernetes and Slack incident channels–all wired up via <a href="https://code.claude.com/docs/en/mcp" target="_blank" rel="noreferrer">MCP Connectors</a>. Claude can chase multiple leads in parallel, helping to reduce MTTR (mean time to resolution).</p>
</div>
<p>对我们来说，这些来源是 Grafana、日志存储、PagerDuty、GitHub、Kubernetes 和 Slack 故障频道，全都通过 <a href="https://code.claude.com/docs/en/mcp" target="_blank" rel="noreferrer">MCP 连接器</a>接好了。Claude 能同时追好几条线索，帮我们缩短 MTTR（平均解决时间，mean time to resolution）。</p>
<div class="yn-en" lang="en">
<p>Executors report the findings back to the orchestration agent which synthesizes and surfaces the information in a coherent SITREP.</p>
</div>
<p>执行 agent 把发现报回给编排 agent，由它汇总，整理成一份连贯的 SITREP（态势报告）发出来。</p>
<p><img src="https://nyann.cc/posts/how-claude-tag-serves-as-anthropics-first-responder-for-ci-cd-failures/64d5b3d1b39aa8a5233ea05ac12c051e1b97f297.webp" alt="编排 agent 调度多个执行子 agent 并行调查，再汇总成 SITREP" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The orchestrator and executor agents aren’t searching blind. They are guided by an investigation skill with <a href="https://github.com/anthropics/oncall-kit/tree/main/skills/triage" target="_blank" rel="noreferrer">more detailed reference markdown files for each bug class</a>.</p>
</div>
<p>编排 agent 和执行 agent 并不是瞎找。指导它们的是一个调查 skill，里面还有<a href="https://github.com/anthropics/oncall-kit/tree/main/skills/triage" target="_blank" rel="noreferrer">按每类 bug 分开写的更详细的参考 markdown 文件</a>。</p>
<div class="yn-en" lang="en">
<p>For example, a 617 line investigation skill for shadow divergence bugs encodes every step I take during a typical investigation. I built it by troubleshooting with Claude turn-by-turn during one of the incidents and then had it create the file from that experience.</p>
</div>
<p>比如针对影子分歧（shadow divergence）这类 bug，有一个 617 行的调查 skill，把我平时调查时走的每一步都写了进去。做法是：在一次故障里，我和 Claude 一来一回地一起排查，然后让它根据这次经历写出这个文件。</p>
<div class="yn-en" lang="en">
<p>Lessons.md also guides Claude’s troubleshooting. This markdown file is a running log of every incident we've resolved: what happened, the root cause, the fix, and the gotcha worth remembering. Claude appends to it on its own automatically. Every new investigation starts by reading it, so Claude's first hypothesis starts with what has happened recently.</p>
</div>
<p>lessons.md 也在指导 Claude 排查。这个 markdown 文件是一份持续更新的日志，记着我们解决过的每起故障：发生了什么、根因、怎么修的，还有值得记住的坑。Claude 会自己往里追加。每次新的调查都从读它开始，所以 Claude 的第一个假设是从最近发生过的事出发的。</p>
<div class="yn-en" lang="en">
<p>If the same pattern shows up enough times, we promote it into the investigation skill itself. My favorite entry is one Claude wrote about me. I'd made an assumption from a config file before checking the metrics, and the lessons.md file now states, &quot;query the data first, then theorize. Config tells you what could go wrong; metrics tell you what did.&quot;</p>
</div>
<p>同一种模式出现的次数够多了，我们就把它提进调查 skill 里。我最喜欢的一条是 Claude 写我的。当时我还没看指标，就根据一个配置文件下了判断，现在 lessons.md 里写着：「先查数据，再下推论。配置告诉你什么可能出错，指标告诉你什么真的出错了。」</p>
<div class="yn-en" lang="en">
<p>Even with these tools and context, Claude doesn’t always get it right the first time. Human intuition and experience matter. Claude Tag allows the team to troubleshoot incidents in multi-player mode. Either of us can steer the investigation or add a hypothesis in real-time, together.</p>
</div>
<p>就算有了这些工具和上下文，Claude 也不是每次一上来就对。人的直觉和经验依然要紧。Claude Tag 让团队可以「多人模式」排查故障：我们谁都可以实时调整调查方向、补一个假设，大家一起来。</p>
<p><img src="https://nyann.cc/posts/how-claude-tag-serves-as-anthropics-first-responder-for-ci-cd-failures/9280b3233ea5f64b3e0d83ba5602905a77cd5b36.webp" alt="多人在 Slack 中和 Claude 一起排查故障的对话" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Recreated from a real conversation for clarity.</p>
</div>
<p>根据一次真实对话重新制作，便于阅读。</p>
<h2 id="resolution修复" tabindex="-1"><span class="yn-en ignore-header" lang="en">Resolution</span>修复 <a class="header-anchor" href="#resolution修复" aria-label="本节链接：修复">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>If Claude can escalate and troubleshoot alerts, can it fix them too? The answer to this question will vary from team to team, but here’s how we do it.</p>
</div>
<p>既然 Claude 能升级告警、能排查，那它能不能顺手修了？每个团队的答案会不一样，下面说说我们的做法。</p>
<div class="yn-en" lang="en">
<p>Most deployments within our team happen behind a feature flag. I have created a separate agent in Claude Code, with my permissions, capable of progressive deployment behind each of these feature flags.</p>
</div>
<p>我们团队的大部分部署都藏在功能开关后面。我在 Claude Code 里另外建了一个 agent，用的是我的权限，能在这些功能开关后面做渐进式部署。</p>
<div class="yn-en" lang="en">
<p>The first stage of our rollout process usually involves Claude managing canary traffic, monitoring for issues, and automatically ramping a given feature flag up or down. This could be an entirely separate article, so I won't go into more detail here.</p>
</div>
<p>我们上线流程的第一阶段，通常是由 Claude 管理金丝雀流量（canary traffic）、盯着有没有问题，并自动把某个功能开关调高或调低。这块单独都能写一篇文章了，这里就不展开。</p>
<div class="yn-en" lang="en">
<p>Other resolution paths that Claude Tag helps my team with are:</p>
</div>
<p>Claude Tag 还在这几种修复方式上帮我们团队：</p>
<ul>
<li><span class="yn-en" lang="en">Letting us know if we need to drain or cordon off certain sections of our Kubernetes cluster;.</span>告诉我们 Kubernetes 集群的哪些部分需要排空（drain）或隔离（cordon）；</li>
<li><span class="yn-en" lang="en">Giving us instructions on how to scale up some of our infrastructure in responses to demand-surges (this is rare but it’s very helpful when Claude comes back with exactly what we can do for mitigation); and, most frequently,</span>需求激增时，告诉我们怎么给一部分基础设施扩容（这种情况不多，但 Claude 能直接给出具体的缓解办法，这时候特别有用）；还有最常见的，</li>
<li><span class="yn-en" lang="en">Fixes in the form of a PR that the on-call can review, merge, and then deploy for a swift resolution.</span>直接提一个修复 PR，值班的人审完、合并、部署，问题很快就解决了。</li>
</ul>
<h2 id="verification-communication-and-handoff验证、通报和交接" tabindex="-1"><span class="yn-en ignore-header" lang="en">Verification, communication, and handoff</span>验证、通报和交接 <a class="header-anchor" href="#verification-communication-and-handoff验证、通报和交接" aria-label="本节链接：验证、通报和交接">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Claude uses many of the same MCP Connectors and tools that it did for its investigation to verify the fix worked as intended. As part of the standing instructions in oncall.md, it writes a post-mortem to lessons.md and for the handoff SITREP.</p>
</div>
<p>验证修复有没有生效，Claude 用的很多是调查时用过的那些 MCP 连接器和工具。按 oncall.md 里的长期指令，它会写一份事后复盘（post-mortem），记进 lessons.md，也放进交接用的 SITREP。</p>
<div class="yn-en" lang="en">
<p>To communicate the full picture across multiple incidents, we created an agent called ci-weather. It compiles information from each incident Slack channel, build metrics, merge queue stats, and deploy lag. Then it posts a newsroom-style report to one public channel anyone in the company can read. Now, our engineers can reference that channel rather than pinging us when they are trying to determine if they should hold their merges or if they’re trying to answer “what’s wrong with CI?”.</p>
</div>
<p>为了把多起故障的全貌讲清楚，我们做了一个叫 ci-weather 的 agent。它从每个故障的 Slack 频道、构建指标、合并队列统计和部署延迟里汇总信息，然后往一个公司里谁都能看的公开频道发一份新闻播报式的报告。现在工程师想知道要不要先别合并，或者想弄明白「CI 到底怎么了」，看这个频道就行，不用再来找我们。</p>
<div class="yn-en" lang="en">
<p>One honest note: we needed to iterate the report format several times. Claude can one-shot a skill that generates a status report, but what makes it readable is team-specific taste. It's human communication, not plumbing.</p>
</div>
<p>说句实话：报告格式我们改了好几轮。Claude 一次就能写出一个生成状态报告的 skill，但报告好不好读，取决于团队自己的口味。说到底这是人和人之间的沟通，不是搭管道的活。</p>
<p><img src="https://nyann.cc/posts/how-claude-tag-serves-as-anthropics-first-responder-for-ci-cd-failures/41a169c1eb4a8d08db5297034089c893808ab77e.webp" alt="ci-weather 发到公开频道的 CI 状况播报" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Finally, while Claude keeps a journal for itself in lessons.md, we also want to produce handoff reports for humans as well every Monday. Claude produces daily and weekly summaries so one member of the team can pick up where the other left off.</p>
</div>
<p>最后，Claude 在 lessons.md 里给自己记日志，我们也希望每周一给人出一份交接报告。Claude 会写每日和每周的总结，这样团队里一个人能接着另一个人留下的进度往下做。</p>
<h2 id="from-monitoring-incidents-to-monitoring-an-incident-response-system从盯故障-到盯一套故障响应系统" tabindex="-1"><span class="yn-en ignore-header" lang="en">From monitoring incidents to monitoring an incident response system</span>从盯故障，到盯一套故障响应系统 <a class="header-anchor" href="#from-monitoring-incidents-to-monitoring-an-incident-response-system从盯故障-到盯一套故障响应系统" aria-label="本节链接：从盯故障，到盯一套故障响应系统">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Our software engineers on average <a href="https://www.anthropic.com/institute/recursive-self-improvement" target="_blank" rel="noreferrer">ship 8x as much code per quarter</a> as they did from 2021 to 2025. And while we have kept the quality bar high (every PR has a named human owner, every change requires approval to merge, every change goes through the same set of CI gates), the only way to keep up with agentic coding is agentic CI.</p>
</div>
<p>我们的软件工程师现在平均<a href="https://www.anthropic.com/institute/recursive-self-improvement" target="_blank" rel="noreferrer">每季度交付的代码量是 2021 到 2025 年间的 8 倍</a>。质量标准我们一直没降（每个 PR 都有一个具体的人负责，每个改动都要审批才能合并，每个改动都要过同一套 CI 关卡），但要跟上 agent 写代码的速度，唯一的办法就是让 CI 也交给 agent。</p>
<div class="yn-en" lang="en">
<p>Claude has absorbed the tedious parts of my job, the after-hours disruptions and the incident comms, while allowing me to focus on the medium and long term architectural changes that truly move the needle for system reliability.</p>
</div>
<p>我工作里那些磨人的部分，下班后被打扰、故障期间的沟通，都被 Claude 接走了，我能专心做那些中长期的架构改动，这些才真正能提升系统可靠性。</p>
<div class="yn-en" lang="en">
<p>The best part of what we have built is that it doesn’t feel scattered. Our on-call processes live in Slack, but now Claude has joined the channel.</p>
</div>
<p>我们搭的这套东西最好的一点是不散。值班流程本来就在 Slack 里，现在只是 Claude 也进了频道。</p>
<div class="yn-en" lang="en">
<p>How to get started:</p>
</div>
<p>怎么开始：</p>
<ul>
<li><span class="yn-en" lang="en">You’ll need a <a href="https://support.claude.com/en/collections/9387370-team-and-enterprise-plans" target="_blank" rel="noreferrer">Claude Team or Claude Enterprise</a> plan</span>你得有 <a href="https://support.claude.com/en/collections/9387370-team-and-enterprise-plans" target="_blank" rel="noreferrer">Claude Team 或 Claude Enterprise</a> 套餐</li>
<li><span class="yn-en" lang="en">The organization owner needs to add Claude to the on call Slack channel via Claude Tag</span>组织所有者要通过 Claude Tag 把 Claude 加进值班 Slack 频道</li>
<li><span class="yn-en" lang="en">The org owner also needs to help connect Claude in the on-call Slack channel to the appropriate connectors, GitHub repo, and set up <a href="https://code.claude.com/docs/en/remote-control" target="_blank" rel="noreferrer">Claude Code Remote</a>.</span>组织所有者还要帮忙给值班频道里的 Claude 接上合适的连接器和 GitHub 仓库，并配好 <a href="https://code.claude.com/docs/en/remote-control" target="_blank" rel="noreferrer">Claude Code Remote</a>。</li>
<li><span class="yn-en" lang="en">Add Claude to your incident channel and instruct it to monitor for incidents and immediately triage</span>把 Claude 加进故障频道，让它盯着故障、一出事马上排查</li>
</ul>
<div class="yn-en" lang="en">
<p><em><a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">Set up your own Claude on-call with our setup kit</a>.</em></p>
</div>
<p><em><a href="https://github.com/anthropics/oncall-kit" target="_blank" rel="noreferrer">用我们的配置套件，给自己也配一个值班的 Claude</a>。</em></p>
<div class="yn-en" lang="en">
<p><em>This article was written by Sachin Malhotra, technical member of Anthropic staff with contributions from Michael Segner, Anthropic staff.</em></p>
</div>
<p><em>本文由 Anthropic 技术人员 Sachin Malhotra 撰写，Anthropic 员工 Michael Segner 也有贡献。</em></p>
]]></content:encoded>
</item>
<item>
<title>Claude 的文本水印是怎么工作的</title>
<link>https://nyann.cc/posts/Claude%20%E7%9A%84%E6%96%87%E6%9C%AC%E6%B0%B4%E5%8D%B0%E6%98%AF%E6%80%8E%E4%B9%88%E5%B7%A5%E4%BD%9C%E7%9A%84</link>
<guid isPermaLink="true">https://nyann.cc/posts/Claude%20%E7%9A%84%E6%96%87%E6%9C%AC%E6%B0%B4%E5%8D%B0%E6%98%AF%E6%80%8E%E4%B9%88%E5%B7%A5%E4%BD%9C%E7%9A%84</guid>
<pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
<description>为了符合欧盟《人工智能法案》，往后的 Claude 模型生成的文本会带水印。这篇回答水印的原理、会不会影响输出、能不能追溯到用户，以及代码、翻译、图片这些情况怎么处理。</description>
<category>翻译</category>
<category>AI</category>
<category>Claude</category>
<category>水印</category>
<content:encoded><![CDATA[<h1 id="claude-的文本水印是怎么工作的" tabindex="-1">Claude 的文本水印是怎么工作的 <a class="header-anchor" href="#claude-的文本水印是怎么工作的" aria-label="本节链接：Claude 的文本水印是怎么工作的">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>Future Claude models will generate text that contains a watermark. This is a way of determining the likelihood that Claude was involved in writing the text, and we, along with several other major AI providers, are implementing this change to comply with the EU AI Act.</p>
</div>
<p>往后的 Claude 模型生成的文本里会带水印。靠它可以判断一段文字有多大可能是 Claude 参与写的。我们和另外几家主要的 AI 厂商一样，做这个改动是为了符合欧盟《人工智能法案》（EU AI Act）。</p>
<div class="yn-en" lang="en">
<p>In this article, we share answers to some of the questions we’ve received about how our chosen watermarking method works, whether it affects Claude’s outputs, and why we’re making this change. To summarize:</p>
</div>
<p>这篇文章回答我们收到的一些问题：我们选的水印方法是怎么工作的，会不会影响 Claude 的输出，以及为什么要这么做。先说结论：</p>
<ul>
<li><span class="yn-en" lang="en">We use a method of watermarking that does not have any practical impact on the quality or content of Claude’s outputs;</span>我们用的水印方法，对 Claude 输出的质量和内容没有任何实际影响；</li>
<li><span class="yn-en" lang="en">The difference between watermarked and un-watermarked text will not be distinguishable to readers;</span>读者分不出哪段文字带水印、哪段不带；</li>
<li><span class="yn-en" lang="en">Nothing is added to the text and there are no hidden characters;</span>文本里什么都没加，也没有隐藏字符；</li>
<li><span class="yn-en" lang="en">Watermarking doesn’t require extra tokens, and will not be more expensive;</span>水印不需要额外的 token，不会更贵；</li>
<li><span class="yn-en" lang="en">Watermarking carries no identifying information and can’t be traced to a specific person, organization, or chat;</span>水印里不带任何身份信息，追溯不到具体的个人、组织或某次对话；</li>
<li><span class="yn-en" lang="en">Watermarking won’t be specific to Claude. As of August 2, the EU requires AI providers serving its market to mark AI-generated content. Other major model developers have signed the same Code of Practice and will be implementing their own watermarks.</span>水印不是 Claude 独有的。从 8 月 2 日起，欧盟要求在它的市场上提供服务的 AI 厂商给 AI 生成的内容打标记。其他几家主要的模型开发商也签了同一份《行为准则》（Code of Practice），也会上线各自的水印。</li>
</ul>
<h2 id="what-is-watermarking-水印是什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What is watermarking?</span>水印是什么？ <a class="header-anchor" href="#what-is-watermarking-水印是什么" aria-label="本节链接：水印是什么？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Large language models like Claude work by generating one word at a time. Each time the model decides on the next word, it chooses among a list of potential candidates, ultimately selecting the most sensible or likely based on the preceding text. Take the sentence “The weather today was cold and…”. The next word is very unlikely to be “sugary.” But it is quite likely to be “overcast” or “grey.” Under most circumstances, it doesn’t matter much to the reader which of these latter two words the model ultimately chooses—the meaning of the sentence is largely the same either way. In cases like this, the choice is settled by a random number.</p>
</div>
<p>Claude 这样的大语言模型是一次生成一个词的。每次决定下一个词，模型都会从一串候选词里挑，最后根据前文选出最合理、可能性最高的那个。拿「今天天气很冷，而且……」这句来说，下一个词基本不可能是「甜腻」，但很可能是「阴沉」或者「灰蒙蒙」。大多数时候，模型最后选这两个里的哪一个，对读者来说没多大区别，句子的意思差不多。像这种情况，选哪个是由一个随机数决定的。</p>
<div class="yn-en" lang="en">
<p>Watermarking uses low-stakes choices like these—which occur many times over a piece of generated text—to leave a pattern in Claude’s responses. That pattern is undetectable to the reader, but <em>is</em> detectable to anyone who has a key that encodes it. When watermarking is used, choices are still made at random, but the <em>source</em> of the randomness is different. Instead of using an arbitrary random number generator to pick the next word, watermarking uses the key and a few words that come before to settle what word the model should pick. That is, the words that Claude picks are still random, but now, one can check the sequence of words and see if it’s consistent with the choices Claude would make if it was using the key. If it is, one can assign a probability that the text was generated by Claude.</p>
</div>
<p>水印就是利用这种无关紧要的选择（一段生成的文本里会出现很多次），在 Claude 的回答里留下一种模式。读者察觉不到这种模式，但手里有对应密钥的人<em>能</em>检测出来。加了水印之后，选择仍然是随机的，只是随机性的<em>来源</em>变了：不再用一个任意的随机数生成器来挑下一个词，而是用密钥加上前面几个词来决定模型该选哪个。也就是说，Claude 挑的词还是随机的，但现在可以拿这串词去核对，看它和 Claude 用这把密钥时会做出的选择对不对得上。对得上的话，就能算出这段文字由 Claude 生成的概率。</p>
<div class="yn-en" lang="en">
<p>Importantly, it isn’t that the model will now always be biased toward overcast or grey. Just as with non-watermarked text, overcast might be selected in one sentence, grey in the next, depending on the words that came before. And it’s not the case that the watermarking method pushes Claude to choose a word it wouldn’t have considered anyway (for instance, it wouldn’t make Claude pick a word like “nubilous”—an obscure<sup><a href="#fn-1">1</a></sup> synonym for overcast or grey that Claude almost certainly wouldn’t use under normal circumstances).</p>
</div>
<p>要说明一点：这不等于模型从此总偏向「阴沉」或「灰蒙蒙」。和不带水印的文本一样，这一句可能选了「阴沉」，下一句可能选「灰蒙蒙」，看前面是什么词。水印方法也不会逼 Claude 去选一个它本来就不会考虑的词（比如它不会让 Claude 选「nubilous」这种词。这是「阴沉」「灰蒙蒙」的一个生僻<sup><a href="#fn-1">1</a></sup>同义词，正常情况下 Claude 几乎肯定不会用）。</p>
<h2 id="how-does-watermarking-affect-claude-s-outputs-水印会怎样影响-claude-的输出" tabindex="-1"><span class="yn-en ignore-header" lang="en">How does watermarking affect Claude’s outputs?</span>水印会怎样影响 Claude 的输出？ <a class="header-anchor" href="#how-does-watermarking-affect-claude-s-outputs-水印会怎样影响-claude-的输出" aria-label="本节链接：水印会怎样影响 Claude 的输出？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Watermarking does not impact the quality of Claude’s output. To a reader, a watermarked response is indistinguishable from an unwatermarked one (in this way, AI watermarks differ substantially from their namesakes on banknotes, other physical objects, and some digital documents, which <em>are</em> visible to the naked eye).</p>
</div>
<p>水印不影响 Claude 输出的质量。在读者眼里，带水印的回答和不带水印的没有区别（这一点上，AI 水印和它的同名物很不一样：钞票、其他实物和一些电子文档上的水印都是肉眼<em>看得见</em>的）。</p>
<div class="yn-en" lang="en">
<p>In internal testing, we’ve seen no impact of watermarking on the content, level of creativity, or readability of Claude’s text. In the <a href="https://www.nature.com/articles/s41586-024-08025-4" target="_blank" rel="noreferrer">SynthID-Text paper</a>, which introduced the technique we use, Google DeepMind tested this impact by serving a model that used watermarking to a portion of their Gemini traffic and comparing thumbs-up and thumbs-down ratings. They found no statistically significant differences from the unwatermarked model. And in a controlled study, human raters comparing watermarked and unwatermarked answers side-by-side saw no difference in quality.</p>
</div>
<p>我们内部测试下来，水印对 Claude 文本的内容、创造力和可读性都没有影响。我们用的技术出自 <a href="https://www.nature.com/articles/s41586-024-08025-4" target="_blank" rel="noreferrer">SynthID-Text 论文</a>，Google DeepMind 在论文里测过这种影响：他们把一个带水印的模型放到一部分 Gemini 流量上，对比用户点赞和点踩的情况，结果和不带水印的模型相比没有统计显著的差异。另外在一项对照研究里，人工评审把带水印和不带水印的回答并排比较，也没看出质量上有差别。</p>
<div class="yn-en" lang="en">
<p>A useful analogy is to imagine you’re playing a game like Monopoly. On each turn, each player moves a random number of spaces around the board according to the roll of a die. Suppose that, instead of rolling the die to get this randomness, we decided to use a book of the digits of pi.<sup><a href="#fn-2">2</a></sup> We start from a randomly-chosen digit (say, the 1,012,845th after the decimal place, which happens to be a 6), and from that point on each player simply uses the next digit in the sequence as their next “roll.&quot;</p>
</div>
<p>打个比方，假设你在玩大富翁（Monopoly）这类游戏。每一轮，每个玩家按掷骰子的点数在棋盘上走随机的步数。现在换个玩法，不掷骰子了，改用一本印满圆周率各位数字的书来提供随机性。<sup><a href="#fn-2">2</a></sup>从随机挑的某一位开始（比如小数点后第 1,012,845 位，恰好是 6），之后每个玩家都直接拿序列里的下一位数字当自己这一轮「掷」出的点数。</p>
<div class="yn-en" lang="en">
<p>For all intents and purposes, the moves are still random: it makes no difference to the players—or to the outcome of the game—whether the randomness comes from pi or from dice rolls each time. But if we could see the sequence of all the moves after the game (and we knew the value of pi), we could work out whether this was a game that likely used pi to determine its moves. The game that used pi is, in a sense, “watermarked.&quot;</p>
</div>
<p>不管怎么看，这些步数仍然是随机的：每次的随机性来自圆周率还是骰子，对玩家、对游戏结果都没有任何区别。但要是游戏结束后我们能看到全部走法（而且知道圆周率的值），就能推断出这局游戏是不是很可能用圆周率来决定步数。从某种意义上说，用圆周率玩的那一局就被「打上了水印」。</p>
<div class="yn-en" lang="en">
<p>It’s the same for Claude-generated text. Watermarking doesn’t change the meaning or experience for the person reading it, but if you wanted to check after the fact whether the text was likely generated by Claude, the watermark allows you to do so.</p>
</div>
<p>Claude 生成的文本也是这样。水印不会改变读者看到的意思和阅读体验，但如果你事后想查一段文字是不是很可能出自 Claude，水印让你查得出来。</p>
<h2 id="which-specific-method-of-watermarking-do-you-use-你们具体用的是哪种水印方法" tabindex="-1"><span class="yn-en ignore-header" lang="en">Which specific method of watermarking do you use?</span>你们具体用的是哪种水印方法？ <a class="header-anchor" href="#which-specific-method-of-watermarking-do-you-use-你们具体用的是哪种水印方法" aria-label="本节链接：你们具体用的是哪种水印方法？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Claude’s text watermark is a version of the SynthID-Text approach published by Google DeepMind in a <a href="https://www.nature.com/articles/s41586-024-08025-4" target="_blank" rel="noreferrer"><em>Nature</em> paper</a> in 2024. It belongs to a family of approaches that go back to a proposal by Scott Aaronson in 2022, all of which share the same design principle that we described above—the watermark only changes the source of the randomness used to pick among words.</p>
</div>
<p>Claude 的文本水印是 SynthID-Text 方法的一个版本。这个方法是 Google DeepMind 2024 年在一篇 <a href="https://www.nature.com/articles/s41586-024-08025-4" target="_blank" rel="noreferrer"><em>Nature</em> 论文</a>里发表的，属于一类可以追溯到 Scott Aaronson 2022 年那个提案的方法。这类方法的设计原则都和上面讲的一样：水印只改变挑词时所用随机性的来源。</p>
<div class="yn-en" lang="en">
<p>There are limitations to the effectiveness of watermarking. Using our key, one can only answer the question “What is the likelihood this was partly written by Claude?” It doesn’t confirm whether the text was human-written, and it can’t tell whether the text was written by a different AI (even if that other AI uses watermarking, it would have a different key; it might also use a different watermarking method altogether). Detecting a watermark also doesn’t work well on small samples, where there are fewer word choices and thus less information to go on. As a passage increases in length, confidence about Claude’s involvement increases too.</p>
</div>
<p>水印的效果是有局限的。用我们的密钥，只能回答「这段文字有多大可能部分出自 Claude？」这一个问题。它没法确认文字是不是人写的，也分辨不出是不是别的 AI 写的（就算那个 AI 也用水印，密钥也不一样，甚至可能用的是另一套水印方法）。样本很短时，水印检测的效果也不好，因为能选的词少，可依据的信息也就少。段落越长，判断 Claude 参与过的把握就越大。</p>
<div class="yn-en" lang="en">
<p>Watermarking is sparser on factual passages where there are fewer choices that can be made without decreasing the accuracy of the text. For example, take the sentence “Isaac Newton’s most famous work was called <em>Principia</em> …”. It really matters whether the next word is “ <em>Mathematica</em> ” (it’s the only right answer), so the watermark would have nothing to act on. The same is true for proofreading. If you hand Claude a piece of writing and ask it to edit only the grammar and punctuation and nothing else, the watermark can only live in the handful of corrections, which might be too few to register.</p>
</div>
<p>讲事实的段落里，水印会更稀疏，因为在不损害准确性的前提下能做的选择更少。比如「艾萨克·牛顿最著名的著作叫 <em>Principia</em>……」这句，下一个词是不是「<em>Mathematica</em>」非常要紧（这是唯一正确的答案），所以水印在这里无处下手。校对也一样。如果你把一段文字交给 Claude，让它只改语法和标点、别的都不动，水印就只能落在那寥寥几处修改上，可能少到检测不出来。</p>
<h2 id="what-about-cases-where-claude-has-proofread-or-edited-human-text-claude-校对或编辑过的人写的文字呢" tabindex="-1"><span class="yn-en ignore-header" lang="en">What about cases where Claude has proofread or edited human text?</span>Claude 校对或编辑过的人写的文字呢？ <a class="header-anchor" href="#what-about-cases-where-claude-has-proofread-or-edited-human-text-claude-校对或编辑过的人写的文字呢" aria-label="本节链接：Claude 校对或编辑过的人写的文字呢？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The watermark only applies to words Claude chooses. When Claude proofreads text written by a person, what it gives back has generally only been lightly edited; because nearly all the words are the person’s, there’s very little (if anything) for the watermark to attach to. Depending on the length of the text and how heavily Claude has edited it, those changes might not be enough to make Claude’s involvement detectable. The more Claude writes, the more decisions it has to make, and the more space there is for a watermark.</p>
</div>
<p>水印只作用于 Claude 自己选的词。Claude 校对人写的文字时，交回来的一般只是轻度改动过的版本；几乎所有的词都还是作者本人的，水印能附着的地方很少（甚至没有）。看文本有多长、Claude 改动有多大，这些修改可能不足以让人检测出 Claude 参与过。Claude 写得越多，要做的决定就越多，水印的空间也就越大。</p>
<h2 id="what-about-code-代码呢" tabindex="-1"><span class="yn-en ignore-header" lang="en">What about code?</span>代码呢？ <a class="header-anchor" href="#what-about-code-代码呢" aria-label="本节链接：代码呢？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>As we noted above, AI watermarking takes advantage of decisions where either choice of a word would be equally good. Where an <em>exact</em> output is required—where there isn’t a choice, and something would be factually wrong or a piece of code would break if a different term was chosen—the watermark isn’t applied.</p>
</div>
<p>前面说过，AI 水印利用的是那些选哪个词都一样好的决定。需要<em>精确</em>输出的地方，也就是没得选、换个词事实就错了或者代码就跑不起来的地方，水印不会生效。</p>
<div class="yn-en" lang="en">
<p>For example, once the model has written “2 + 2 =”, there is a very clear best choice for the next token (if the model is completing the sum, there isn’t an answer that’s equally as good as “4”; if it’s talking about George Orwell’s <em>Nineteen Eighty-Four</em>, there isn’t an answer that’s equally as good as “5”). The “nudge” of the watermark wouldn’t be applied here. For the same reason, code—which in very many cases has to be exact—has generally less watermarking than some other forms of text.</p>
</div>
<p>比如模型写下「2 + 2 =」之后，下一个 token 有非常明确的最佳选择（如果模型是在算这道加法，没有哪个答案能和「4」一样好；如果它在聊乔治·奥威尔的《<em>一九八四</em>》，也没有哪个答案能和「5」一样好）。水印那一下「轻推」在这里就不会施加。出于同样的原因，代码在很多情况下都必须精确，所以通常比其他一些类型的文本带的水印少。</p>
<div class="yn-en" lang="en">
<p>Having said that, in areas where there <em>is</em> an arbitrary choice between particular words or terms within the code, the watermark can be used, such as comments within code. But by definition, it will have a negligible effect on the actual code produced.</p>
</div>
<p>话虽如此，代码里<em>确实</em>存在可以随便选词或术语的地方，比如代码注释，水印还是能用上。但按定义，它对实际生成的代码影响微乎其微。</p>
<h2 id="what-does-this-mean-for-users-这对用户意味着什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What does this mean for users?</span>这对用户意味着什么？ <a class="header-anchor" href="#what-does-this-mean-for-users-这对用户意味着什么" aria-label="本节链接：这对用户意味着什么？">&ZeroWidthSpace;</a></h2>
<h3 id="does-this-slow-the-model-down-or-make-it-more-expensive-会让模型变慢或变贵吗" tabindex="-1"><span class="yn-en ignore-header" lang="en">Does this slow the model down, or make it more expensive?</span>会让模型变慢或变贵吗？ <a class="header-anchor" href="#does-this-slow-the-model-down-or-make-it-more-expensive-会让模型变慢或变贵吗" aria-label="本节链接：会让模型变慢或变贵吗？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>No. Watermarking has a negligible impact on the speed of models, and because it produces no extra tokens, the model is the same price to serve and use.</p>
</div>
<p>不会。水印对模型速度的影响可以忽略不计，而且它不产生额外的 token，所以模型的服务成本和使用价格都不变。</p>
<h3 id="can-a-watermark-be-traced-back-to-me-or-my-organization-水印能追溯到我或我的组织吗" tabindex="-1"><span class="yn-en ignore-header" lang="en">Can a watermark be traced back to me or my organization?</span>水印能追溯到我或我的组织吗？ <a class="header-anchor" href="#can-a-watermark-be-traced-back-to-me-or-my-organization-水印能追溯到我或我的组织吗" aria-label="本节链接：水印能追溯到我或我的组织吗？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>No. The watermarking applies to Claude and its outputs. It doesn’t identify anything to do with individual users. There’s nothing in the watermark, or its key, that would allow anyone to recover any information about the user, their organization, or their chats with Claude.</p>
</div>
<p>不能。水印作用于 Claude 和它的输出，不会标识出任何跟具体用户有关的东西。水印本身和它的密钥里，都没有任何东西能让人还原出用户、用户所在的组织或者他们和 Claude 的对话的信息。</p>
<h2 id="why-are-you-watermarking-claude-s-outputs-你们为什么要给-claude-的输出加水印" tabindex="-1"><span class="yn-en ignore-header" lang="en">Why are you watermarking Claude’s outputs?</span>你们为什么要给 Claude 的输出加水印？ <a class="header-anchor" href="#why-are-you-watermarking-claude-s-outputs-你们为什么要给-claude-的输出加水印" aria-label="本节链接：你们为什么要给 Claude 的输出加水印？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>We’re implementing watermarking to comply with the EU AI Act. Anthropic, along with several other major AI model providers and around <a href="https://digital-strategy.ec.europa.eu/en/news/strong-backing-code-practice-transparency-ai-generated-content" target="_blank" rel="noreferrer">190 total signatories</a>, signed the EU Code of Practice on Transparency of AI-Generated Content in July 2026. This requires AI system providers to use methods of “marking” AI-generated text. We’re applying watermarking globally at launch because we don't yet have a durable way to scope it by region. However, we will continue to evaluate different approaches, and will share updates when we have them.</p>
</div>
<p>我们加水印是为了符合欧盟《人工智能法案》。2026 年 7 月，Anthropic 和其他几家主要的 AI 模型厂商，连同总共约 <a href="https://digital-strategy.ec.europa.eu/en/news/strong-backing-code-practice-transparency-ai-generated-content" target="_blank" rel="noreferrer">190 个签署方</a>，签署了欧盟的《AI 生成内容透明度行为准则》（Code of Practice on Transparency of AI-Generated Content）。准则要求 AI 系统提供方用某种方法给 AI 生成的文本「打标记」。上线时我们会在全球范围启用水印，因为目前还没有一个可靠的办法按地区划定范围。不过我们会继续评估不同的做法，有进展再跟大家同步。</p>
<h2 id="other-questions其他问题" tabindex="-1"><span class="yn-en ignore-header" lang="en">Other questions</span>其他问题 <a class="header-anchor" href="#other-questions其他问题" aria-label="本节链接：其他问题">&ZeroWidthSpace;</a></h2>
<h3 id="how-do-i-check-if-a-piece-of-text-was-written-by-claude-怎么查一段文字是不是-claude-写的" tabindex="-1"><span class="yn-en ignore-header" lang="en">How do I check if a piece of text was written by Claude?</span>怎么查一段文字是不是 Claude 写的？ <a class="header-anchor" href="#how-do-i-check-if-a-piece-of-text-was-written-by-claude-怎么查一段文字是不是-claude-写的" aria-label="本节链接：怎么查一段文字是不是 Claude 写的？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>We are releasing a detection API in private preview. It is currently available to eligible organizations as required under EU law (such as regulators, law enforcement, media, fact-checkers, independent researchers, educational organizations, and EU civil society groups). It is also available for enterprises who are similarly obligated to verify watermarking for their own compliance with the Act. We plan to expand access to the detection API over time. You can register interest in access <a href="https://forms.gle/9tGA33hPJJwtHsMk9" target="_blank" rel="noreferrer">here</a>.</p>
</div>
<p>我们正在以内测（private preview）的形式推出一个检测 API。按欧盟法律的要求，目前向符合条件的组织开放（比如监管机构、执法部门、媒体、事实核查机构、独立研究者、教育机构和欧盟的民间社会团体）。同样需要核验水印、以满足自身法案合规要求的企业也可以用。我们打算逐步扩大检测 API 的开放范围。想申请的话可以<a href="https://forms.gle/9tGA33hPJJwtHsMk9" target="_blank" rel="noreferrer">在这里</a>登记。</p>
<h3 id="what-about-images-and-other-files-图片和其他文件呢" tabindex="-1"><span class="yn-en ignore-header" lang="en">What about images and other files?</span>图片和其他文件呢？ <a class="header-anchor" href="#what-about-images-and-other-files-图片和其他文件呢" aria-label="本节链接：图片和其他文件呢？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>When Claude produces a file of a supported type (such as a .png, .jpg, or .svg), it will attach a content credential in the form of a small, cryptographically signed note in the file’s metadata, saying that the file was made or processed with Claude. This is an open industry standard called <a href="https://c2pa.org/" target="_blank" rel="noreferrer">C2PA</a> —the same used by camera manufacturers and in photo-editing software to record where an image came from. Any C2PA-aware tool can read it; we’ll be providing our own where you can drop a file and check.</p>
</div>
<p>Claude 生成受支持类型的文件（比如 .png、.jpg 或 .svg）时，会附上一份内容凭证（content credential）：文件元数据里一小段带加密签名的说明，写明这个文件是用 Claude 制作或处理的。这是一个叫 <a href="https://c2pa.org/" target="_blank" rel="noreferrer">C2PA</a> 的开放行业标准，相机厂商和修图软件也用它来记录一张图片的来源。任何支持 C2PA 的工具都能读取它；我们也会提供自己的工具，把文件拖进去就能查。</p>
<div class="yn-en" lang="en">
<p>This metadata label is very different from a watermark. Nothing in the file changes—it is not embedded or hidden. As with text, the credential only says Claude was involved in producing the file; it doesn’t include any identifying information.</p>
</div>
<p>这种元数据标签和水印很不一样。文件内容本身一点没变，凭证既没有嵌进去，也没有藏起来。和文本一样，凭证只说明 Claude 参与了文件的制作，不包含任何身份信息。</p>
<h3 id="can-t-someone-just-edit-the-text-to-get-around-the-watermarking-改改文字不就能绕过水印了吗" tabindex="-1"><span class="yn-en ignore-header" lang="en">Can’t someone just edit the text to get around the watermarking?</span>改改文字不就能绕过水印了吗？ <a class="header-anchor" href="#can-t-someone-just-edit-the-text-to-get-around-the-watermarking-改改文字不就能绕过水印了吗" aria-label="本节链接：改改文字不就能绕过水印了吗？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>To some extent, yes. Light editing probably won’t remove the watermark completely; a complete rewrite where every word is replaced will. In the latter case, of course, it’s arguable whether the text can any longer be described as AI-generated.</p>
</div>
<p>某种程度上可以。轻度编辑大概去不干净水印；把每个词都换掉的彻底重写就能去掉。当然，到了后一种情况，这段文字还算不算 AI 生成的，本身就值得商榷了。</p>
<h3 id="what-does-a-watermark-actually-prove-水印到底能证明什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What does a watermark actually prove?</span>水印到底能证明什么？ <a class="header-anchor" href="#what-does-a-watermark-actually-prove-水印到底能证明什么" aria-label="本节链接：水印到底能证明什么？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>A watermark can only determine that Claude was likely involved with the content at some point. It cannot distinguish “Claude wrote this” from “Claude heavily edited this.”</p>
</div>
<p>水印只能判断 Claude 很可能在某个环节参与过这段内容。它分不清「这是 Claude 写的」和「这是 Claude 大改过的」。</p>
<h3 id="do-watermarks-apply-to-translations-翻译也带水印吗" tabindex="-1"><span class="yn-en ignore-header" lang="en">Do watermarks apply to translations?</span>翻译也带水印吗？ <a class="header-anchor" href="#do-watermarks-apply-to-translations-翻译也带水印吗" aria-label="本节链接：翻译也带水印吗？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Yes. A translation produced by Claude carries a watermark, because in this case every word is chosen by Claude.</p>
</div>
<p>带。Claude 产出的译文会带水印，因为这种情况下每个词都是 Claude 选的。</p>
<h3 id="what-about-older-claude-models-旧版-claude-模型呢" tabindex="-1"><span class="yn-en ignore-header" lang="en">What about older Claude models?</span>旧版 Claude 模型呢？ <a class="header-anchor" href="#what-about-older-claude-models-旧版-claude-模型呢" aria-label="本节链接：旧版 Claude 模型呢？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The EU law includes a transition period for Anthropic models launched before August 2, 2026, and we’re working to add watermarking for those models as well. This will be rolled out over the coming months.</p>
</div>
<p>对 2026 年 8 月 2 日之前发布的 Anthropic 模型，欧盟法律留了过渡期，我们也在给这些模型加水印，接下来几个月会陆续上线。</p>
<h3 id="how-does-this-differ-from-ai-detection-software-like-pangram-这和-pangram-这类-ai-检测软件有什么不同" tabindex="-1"><span class="yn-en ignore-header" lang="en">How does this differ from AI detection software, like Pangram?</span>这和 Pangram 这类 AI 检测软件有什么不同？ <a class="header-anchor" href="#how-does-this-differ-from-ai-detection-software-like-pangram-这和-pangram-这类-ai-检测软件有什么不同" aria-label="本节链接：这和 Pangram 这类 AI 检测软件有什么不同？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>AI detection software uses a different method, because the companies that provide it don’t have our key. Among other things, those services look at aspects of the text like the subtle (and not-so-subtle) “tells” that often appear in AI’s phrasing. For example, AI models appear to be fond of the construction “this isn’t [X], it’s [Y]”, and use the word “quietly” a lot more than you might expect. Picking up on these patterns is fundamentally different from checking for a watermark.</p>
</div>
<p>AI 检测软件用的是另一套方法，因为做这些服务的公司没有我们的密钥。它们会看文本的各种特征，其中之一就是 AI 措辞里常冒出来的那些或隐或显的「破绽」。比如 AI 模型好像特别爱用「这不是 [X]，而是 [Y]」这种句式，「quietly」（悄悄地）这个词也用得比你想象的多得多。捕捉这类模式，和检查水印是根本不同的两回事。</p>
<h3 id="does-this-change-who-owns-a-given-output-or-who-is-legally-responsible-for-it-这会改变某个输出归谁所有、由谁承担法律责任吗" tabindex="-1"><span class="yn-en ignore-header" lang="en">Does this change who owns a given output, or who is legally responsible for it?</span>这会改变某个输出归谁所有、由谁承担法律责任吗？ <a class="header-anchor" href="#does-this-change-who-owns-a-given-output-or-who-is-legally-responsible-for-it-这会改变某个输出归谁所有、由谁承担法律责任吗" aria-label="本节链接：这会改变某个输出归谁所有、由谁承担法律责任吗？">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>No. A watermark only helps test whether Claude might have produced or processed the content. It doesn’t say anything about ownership or authorship, and doesn’t change a user’s rights under our terms. We only apply the watermark when Claude was involved in processing the content or file.</p>
</div>
<p>不会。水印只是帮忙检验 Claude 有没有可能产出或处理过某段内容，它不涉及所有权或作者身份，也不改变用户在我们条款下的权利。我们只在 Claude 参与处理了内容或文件时才加水印。</p>
<div class="yn-en" lang="en">
<p><em>Updated Sep 1, 2026:</em> Provided up to date information on the watermarking detection API.</p>
</div>
<p>*2026 年 9 月 1 日更新：*补充了水印检测 API 的最新信息。</p>
<hr>
<div class="yn-en" lang="en">
<p><sup>1</sup> Or, you might say, nubilous—which is also a synonym for “obscure.”</p>
</div>
<p><sup id="fn-1">1</sup> 或者说，nubilous 这个词本身就挺 nubilous 的，因为它也有「晦涩」的意思。</p>
<div class="yn-en" lang="en">
<p><sup>2</sup> Pi is technically predictable, but any run of digits from somewhere in the middle of pi is indistinguishable from a run of rolls of a ten-sided die. Also, set aside the fact that the dice in Monopoly go from 1 to 6 whereas a digit of pi can be from 0 to 9; the analogy isn’t perfect.</p>
</div>
<p><sup id="fn-2">2</sup> 严格来说圆周率是可预测的，但从圆周率中间任取一段数字，和掷十面骰子得到的一串点数是分不出来的。另外，先别管大富翁的骰子是 1 到 6、而圆周率的一位数字是 0 到 9 这回事，这个比方并不完美。</p>
]]></content:encoded>
</item>
<item>
<title>GLM-5.3 与高级网络攻击能力的扩散</title>
<link>https://nyann.cc/posts/GLM-5.3%20%E4%B8%8E%E9%AB%98%E7%BA%A7%E7%BD%91%E7%BB%9C%E6%94%BB%E5%87%BB%E8%83%BD%E5%8A%9B%E7%9A%84%E6%89%A9%E6%95%A3</link>
<guid isPermaLink="true">https://nyann.cc/posts/GLM-5.3%20%E4%B8%8E%E9%AB%98%E7%BA%A7%E7%BD%91%E7%BB%9C%E6%94%BB%E5%87%BB%E8%83%BD%E5%8A%9B%E7%9A%84%E6%89%A9%E6%95%A3</guid>
<pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
<description>智谱的开放权重模型 GLM-5.3 已经能端到端写出可用的漏洞利用，攻击能力接近 Claude Mythos Preview，安全防护却用几种简单手段就能绕过或去掉。Anthropic 前沿红队的评估，以及他们觉得这意味着什么。</description>
<category>翻译</category>
<category>AI</category>
<category>安全</category>
<category>网络安全</category>
<content:encoded><![CDATA[<h1 id="glm-5-3-与高级网络攻击能力的扩散" tabindex="-1">GLM-5.3 与高级网络攻击能力的扩散 <a class="header-anchor" href="#glm-5-3-与高级网络攻击能力的扩散" aria-label="本节链接：GLM-5.3 与高级网络攻击能力的扩散">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>Five months ago, we <a href="https://www.anthropic.com/glasswing" target="_blank" rel="noreferrer">announced</a> Claude Mythos Preview, the first AI model that could autonomously build sophisticated, end-to-end cyber exploits. The rapid rate of improvement in AI suggested to us that this ability would eventually proliferate to many other models, making it much easier for malicious cyber actors to launch highly impactful cyberattacks.</p>
</div>
<p>五个月前，我们<a href="https://www.anthropic.com/glasswing" target="_blank" rel="noreferrer">发布</a>了 Claude Mythos Preview。它是第一个能自主构建复杂的端到端网络漏洞利用（exploit）的 AI 模型。照 AI 进步的速度，我们判断这种能力迟早会扩散到很多其他模型上，到时候恶意的网络攻击者要发动破坏力很大的攻击就容易多了。</p>
<div class="yn-en" lang="en">
<p>In light of these considerations, we chose to release Claude Mythos Preview in a limited way, through Project Glasswing—which enabled trusted cyber defenders to find <a href="https://www.anthropic.com/research/glasswing-initial-update" target="_blank" rel="noreferrer">more than 10,000 vulnerabilities</a> in critical software, giving them a head start before malicious actors had access to similarly capable models.</p>
</div>
<p>出于这些考虑，我们选择有限度地发布 Claude Mythos Preview，只通过 Project Glasswing 提供。可信的网络防御者借它在关键软件里找到了<a href="https://www.anthropic.com/research/glasswing-initial-update" target="_blank" rel="noreferrer">一万多个漏洞</a>，在恶意攻击者拿到同等能力的模型之前抢先了一步。</p>
<div class="yn-en" lang="en">
<p>But those models have now arrived. In this post, we share our analysis of GLM-5.3, the latest AI model developed by Zhipu AI (known outside of China as Z.ai). Like Claude Mythos Preview, GLM-5.3 has strong capabilities for autonomously building end-to-end cyber exploits. But GLM-5.3 is unlike other frontier models in that it has been released without meaningful safeguards to limit misuse. We find that attackers can bypass GLM-5.3’s safeguards between 64% and 100% of the time with simple techniques in our simulated tests. In contrast, these attacks did not succeed against safeguarded Claude models in our testing. We assess that GLM-5.3’s lax safeguards significantly increase the cyber capabilities available to malicious actors. At the same time, these capabilities can also benefit defenders working to secure their systems.</p>
</div>
<p>可这样的模型现在已经来了。这篇文章分享我们对 GLM-5.3 的分析，它是智谱 AI（在中国以外叫 Z.ai）最新开发的模型。和 Claude Mythos Preview 一样，GLM-5.3 自主构建端到端漏洞利用的能力很强。但它和其他前沿模型不同：发布时没有配上真正能限制滥用的安全防护（safeguards）。在我们的模拟测试里，攻击者用一些简单手段，就能在 64% 到 100% 的情况下绕过 GLM-5.3 的防护。同样的攻击用在带防护的 Claude 模型上，在我们的测试里都没有成功。我们的判断是，GLM-5.3 松散的防护让恶意攻击者能用上的网络攻击能力大幅提升。同时，这些能力也能帮到正在加固自家系统的防御者。</p>
<div class="yn-en" lang="en">
<p>On Sept. 17, NIST’s Center for AI Standards and Innovation (CAISI) published <a href="https://www.nist.gov/news-events/news/2026/09/caisis-assessment-zais-glm-53-cyber-capabilities" target="_blank" rel="noreferrer">its own assessment</a> of GLM-5.3’s cyber capabilities. CAISI found that GLM-5.3 is “the most cyber-capable open-weight model released to date” and that it lags the US frontier by about four months on an aggregate of CAISI’s cyber benchmarks. Our capability findings broadly match CAISI’s. In CAISI’s comparison, US models were tested with cyber safeguards disabled when applicable, and the US frontier includes models released only to vetted users. Attackers can’t readily access those versions of US models, but anyone can download GLM-5.3. This post adds our analysis of how easily GLM-5.3’s safeguards can be bypassed or removed.</p>
</div>
<p>9 月 17 日，美国国家标准与技术研究院（NIST）下属的 AI 标准与创新中心（CAISI）发布了<a href="https://www.nist.gov/news-events/news/2026/09/caisis-assessment-zais-glm-53-cyber-capabilities" target="_blank" rel="noreferrer">他们自己对 GLM-5.3 网络能力的评估</a>。CAISI 的结论是，GLM-5.3 是「迄今为止网络能力最强的开放权重（open-weight）模型」，在 CAISI 一组网络基准的综合成绩上，落后美国最前沿大约四个月。我们对能力的发现和 CAISI 大体一致。在 CAISI 的对比里，美国模型在适用的情况下是关掉网络安全防护来测的，而且「美国最前沿」里包括只发布给经过审核的用户的模型。攻击者没那么容易拿到这些版本的美国模型，GLM-5.3 却是谁都能下载。我们在这篇文章里补充分析了另一件事：GLM-5.3 的防护有多容易被绕过或去掉。</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/a1b61c7da2c400ab84425e105837fc1f346a4339-1280x1576.webp" alt="两张柱状图。上图：在 41 个 Chrome V8 漏洞上成功构建出可用漏洞利用的尝试占比，Claude Mythos Preview 为 14%，GLM-5.3 为 12%，Claude Opus 4.6、GLM-5.2、Kimi K3 和 DeepSeek V4.1-Flash 为 0% 或接近 0%。下图：各模型响应恶意网络攻击指令的频率，GLM-5.3 在直接下令时为 0%，加上虚假背景说明升到 64%，预填充推理为 92%，拒绝消融后为 100%，Claude Opus 5 始终为 0%。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 1.</strong> Summary of findings. Top: The increase in exploitation capability between Claude Opus 4.6 and Claude Mythos Preview mirrors the jump in capabilities between GLM-5.2 and GLM-5.3. Claude models are released with cyber safeguards, and versions with reduced safeguards are limited to vetted users. Anyone can download and use GLM-5.3. Bottom: The limited safeguards in GLM-5.3 can be bypassed with standard techniques that did not work against, or do not apply to, Claude models in our testing.</p>
</div>
<p><strong>图 1.</strong> 发现汇总。上：从 Claude Opus 4.6 到 Claude Mythos Preview 漏洞利用能力的提升，和从 GLM-5.2 到 GLM-5.3 的能力跃升如出一辙。Claude 模型发布时带有网络安全防护，防护减弱的版本只给经过审核的用户。GLM-5.3 则谁都能下载使用。下：GLM-5.3 有限的防护能被一些常规手段绕过，而在我们的测试里，这些手段对 Claude 模型要么不起作用，要么根本用不上。</p>
<h2 id="glm-5-3-can-develop-working-exploits-end-to-endglm-5-3-能端到端写出可用的漏洞利用" tabindex="-1"><span class="yn-en ignore-header" lang="en">GLM-5.3 can develop working exploits end to end</span>GLM-5.3 能端到端写出可用的漏洞利用 <a class="header-anchor" href="#glm-5-3-can-develop-working-exploits-end-to-endglm-5-3-能端到端写出可用的漏洞利用" aria-label="本节链接：GLM-5.3 能端到端写出可用的漏洞利用">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>To understand how GLM-5.3 could enable cyber threat actors to find and exploit real software vulnerabilities, we ran evaluations using automated benchmarks and human-in-the-loop workflows. For both approaches, we ran the tested models in isolated and sandboxed environments so they can only attack offline targets that we have set up for the purposes of these evaluations. We focus primarily on exploit development capability, as this is where Claude Mythos Preview demonstrated a notable jump versus previous Claude models.</p>
</div>
<p>为了弄清 GLM-5.3 能在多大程度上帮网络威胁行为者找到并利用真实软件里的漏洞，我们做了两类评估：自动化基准测试，和有人参与（human-in-the-loop）的工作流。两类评估里，被测模型都跑在隔离的沙箱环境中，只能攻击我们专门为评估搭起来的离线目标。我们主要关注漏洞利用的开发能力，因为 Claude Mythos Preview 正是在这一项上比之前的 Claude 模型有明显跃升。</p>
<div class="yn-en" lang="en">
<p>First, we ran the model on <a href="https://arxiv.org/abs/2605.14153" target="_blank" rel="noreferrer">ExploitBench</a>, which measures how well AI models can exploit known vulnerabilities in the V8 engine used by Google Chrome. Here we focus on the models’ ability to develop end-to-end exploits successfully, as this is the most relevant capability for attackers, and where we see significant changes between models. We find that GLM-5.3 develops end-to-end exploits in 50 of 410 attempts. Claude Mythos Preview did so at a similar rate—in 56 of 410 attempts.</p>
</div>
<p>首先是 <a href="https://arxiv.org/abs/2605.14153" target="_blank" rel="noreferrer">ExploitBench</a>，它衡量 AI 模型利用 Google Chrome 所用的 V8 引擎里已知漏洞的能力。这里我们看的是模型能不能成功写出端到端的漏洞利用，因为这是对攻击者最要紧的能力，也是不同模型之间差别最明显的地方。结果是，GLM-5.3 在 410 次尝试里有 50 次写出了端到端漏洞利用。Claude Mythos Preview 的成功率差不多：410 次里 56 次。</p>
<div class="yn-en" lang="en">
<p>In our internal Binary Exploitation benchmark,<sup><a href="#fn-1">1</a></sup> we test whether models can find and exploit vulnerabilities in popular open-source projects that participate in Google’s OSS-Fuzz project. Here, full credit is awarded for a full control-flow hijack. We evaluate several models on 100 tasks from the benchmark (selected at random), and find that GLM-5.3 develops full control-flow hijacks in 4% of the trials; Claude Mythos Preview did so in 6%. Although GLM-5.3 performs below Claude Mythos Preview here, a meaningful threshold has clearly been crossed: earlier models, like Claude Opus 4.6 and GLM-5.2, do not succeed in any of them.</p>
</div>
<p>在我们内部的二进制漏洞利用（Binary Exploitation）基准里，<sup><a href="#fn-1">1</a></sup>测的是模型能不能在参与 Google OSS-Fuzz 项目的热门开源项目里找到漏洞并加以利用。只有实现完整的控制流劫持（control-flow hijack）才算满分。我们从基准里随机挑了 100 个任务，拿几个模型来测，GLM-5.3 在 4% 的试验里实现了完整的控制流劫持，Claude Mythos Preview 是 6%。GLM-5.3 在这一项上虽然不如 Claude Mythos Preview，但显然已经跨过了一道有分量的门槛：更早的模型，比如 Claude Opus 4.6 和 GLM-5.2，一个任务都没做成。</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/ab29550606b0df3c6c070f4c65b758aa18bdecbb-1280x1588.webp" alt="两张折线图，横轴是对数刻度的输出 token 预算，纵轴是漏洞利用成功率。ExploitBench 上 Claude Mythos Preview 达到 14%，GLM-5.3 达到 12%，Kimi K3、DeepSeek-V4.1-Flash、Claude Opus 4.6 和 GLM-5.2 停在 0% 或接近 0%。Anthropic 内部的二进制漏洞利用基准上，Mythos Preview 达到 6%，GLM-5.3 达到 4%，其余模型都是 0%。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 2.</strong> Exploitation capability versus output-token budget. Each line shows the share of a model’s attempts that reached the benchmark’s top outcome versus the output tokens used. Both figures show performance of two Claude models run with safeguards disabled (Opus 4.6, Mythos Preview), two GLM models (5.2 and 5.3), and results from the latest open-weight models released by Moonshot AI (Kimi K3) and DeepSeek (V4.1-Flash).</p>
</div>
<p><strong>图 2.</strong> 漏洞利用能力与输出 token 预算的关系。每条线表示一个模型的尝试中达到该基准最高结果的比例，随所用输出 token 的变化。两张图都包括：关掉防护运行的两个 Claude 模型（Opus 4.6、Mythos Preview），两个 GLM 模型（5.2 和 5.3），以及月之暗面（Kimi K3）和 DeepSeek（V4.1-Flash）最新发布的开放权重模型的结果。</p>
<div class="yn-en" lang="en">
<p>Next, we evaluated how GLM-5.3 performs on open-ended offensive cyber tasks in the hands of human experts (mirroring our <a href="https://red.anthropic.com/2026/mythos-preview" target="_blank" rel="noreferrer">testing with Claude Mythos Preview</a> earlier this year). Here, we select targets in which the human experts are unaware of existing vulnerabilities, then ask them to use the model to identify and exploit novel flaws. These experiments tested what the experts could do in a short time-frame: they typically ran for a day or less, with less than an hour of human focus in total.</p>
</div>
<p>接着，我们评估了 GLM-5.3 在人类专家手里做开放式网络攻击任务的表现（做法照搬今年早些时候我们<a href="https://red.anthropic.com/2026/mythos-preview" target="_blank" rel="noreferrer">对 Claude Mythos Preview 的测试</a>）。我们挑的目标，专家事先都不知道上面有哪些漏洞，然后让他们用模型去找出新的缺陷并加以利用。这些实验测的是专家在很短时间里能做到什么：一般跑一天或更短，人投入的专注时间加起来不到一小时。</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/6e4f59aaf6659657e9c4f2606bb1ab38cc0a390e-1920x1019.webp" alt="GLM-5.3 生成的漏洞利用页面截图（已打码）。顶部横幅写着「Sandbox escaped — web content read /root/.ssh/id_rsa (1896 bytes)」，下面是实时的利用日志和被窃取的 SSH 私钥，演示了一条路过式（drive-by）浏览器漏洞利用链从受害者电脑上偷走文件。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 3.</strong> A redacted screenshot of an exploit page generated by GLM-5.3 during researcher-driven testing, shown stealing a user’s SSH private key via a malicious website. The exploit chains together multiple 0-day vulnerabilities the model discovered in a component of a popular web browser, reading a sensitive file off the user’s computer.</p>
</div>
<p><strong>图 3.</strong> 研究员主导的测试中，GLM-5.3 生成的一个漏洞利用页面的截图（已打码），展示的是通过恶意网站窃取用户的 SSH 私钥。这个利用把模型在一款流行浏览器的某个组件里发现的多个 0day 漏洞串在一起，从用户电脑上读走了一个敏感文件。</p>
<div class="yn-en" lang="en">
<p>In the first of these sessions, a researcher used GLM-5.3 on a sandboxed machine with a local Linux build of a popular web browser. Over the course of a day (and with limited human attention), GLM-5.3 found several previously unknown vulnerabilities in the browser’s JavaScript engine, and chained them together into a working exploit: a webpage that, when visited, reads arbitrary files from the visitor’s computer (shown in Figure 3). This exploit targets the Linux build of the browser, since that was the only environment made available to the model. However, we believe these vulnerabilities could also impact users on other platforms, though the path to exploitation there may be more complex. (We’ve disclosed these vulnerabilities to the maintainer.) Later in the session, the researcher also identified exploitable vulnerabilities in several other widely used systems with GLM-5.3, including wireless and graphics drivers and network-facing device software. We are currently reviewing these reports and we will disclose to maintainers as appropriate.</p>
</div>
<p>第一场测试里，一位研究员在一台沙箱机器上用 GLM-5.3，机器上装着一款流行浏览器的本地 Linux 构建版。一天之内（人也没怎么盯着），GLM-5.3 在这款浏览器的 JavaScript 引擎里找到了好几个此前没人知道的漏洞，还把它们串成了一个可用的漏洞利用：一个网页，只要有人访问，就能读取访客电脑上的任意文件（见图 3）。这个利用针对的是浏览器的 Linux 版，因为模型手里只有这一个环境。不过我们认为，这些漏洞也可能影响其他平台的用户，只是在那些平台上利用起来可能更绕。（这些漏洞我们已经报告给了维护方。）在这场测试后面，研究员还借 GLM-5.3 在其他几个广泛使用的系统里发现了可利用的漏洞，包括无线网卡和显卡驱动，以及面向网络的设备软件。这些报告我们正在审核，会视情况告知维护方。</p>
<div class="yn-en" lang="en">
<p>In a second session, a researcher used GLM-5.3-Flash (a smaller, less capable version of GLM-5.3) to develop an exploit for a <em>known</em> vulnerability (we’ve previously written about these “N-day” vulnerability exploits <a href="https://www.anthropic.com/research/n-days" target="_blank" rel="noreferrer">here</a>). Here, the researcher focused on a recently disclosed flaw in Google Chrome (CVE-2026-11645) to see how quickly the model could turn a public fix into a working attack. The researcher provided GLM-5.3-Flash with public details of this CVE and another known flaw. With no significant direction from the researcher, GLM-5.3-Flash chained together exploits for these two flaws, building a reliable exploit chain for an ARM64 target, bypassing pointer-authentication (PAC) hardening. This took 20 minutes of human attention, plus eight hours of work for GLM-5.3-Flash. At Zhipu’s API prices, this effort would have cost $20.40.</p>
</div>
<p>第二场测试里，一位研究员用 GLM-5.3-Flash（GLM-5.3 更小、能力更弱的版本）给一个<em>已知</em>漏洞写利用（这类「N-day」漏洞利用我们之前在<a href="https://www.anthropic.com/research/n-days" target="_blank" rel="noreferrer">这里</a>写过）。研究员盯的是 Google Chrome 里一个最近才公开的缺陷（CVE-2026-11645），想看模型多快能把一个公开的修复补丁变成能用的攻击。研究员把这个 CVE 和另一个已知缺陷的公开细节交给 GLM-5.3-Flash。在研究员没怎么指点的情况下，GLM-5.3-Flash 把这两个缺陷的利用串在一起，针对 ARM64 目标搭出了一条稳定的利用链，还绕过了指针认证（PAC）加固。整个过程花了研究员 20 分钟的注意力，加上 GLM-5.3-Flash 八个小时的工作。按智谱的 API 价格，这一趟要花 20.40 美元。</p>
<h2 id="glm-5-3-lacks-robust-safeguardsglm-5-3-缺乏牢靠的安全防护" tabindex="-1"><span class="yn-en ignore-header" lang="en">GLM-5.3 lacks robust safeguards</span>GLM-5.3 缺乏牢靠的安全防护 <a class="header-anchor" href="#glm-5-3-lacks-robust-safeguardsglm-5-3-缺乏牢靠的安全防护" aria-label="本节链接：GLM-5.3 缺乏牢靠的安全防护">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>GLM-5.3 has been released with some built-in safeguards: if a user asks for something clearly harmful, the model will often refuse.<sup><a href="#fn-2">2</a></sup> In our testing, we found that these safeguards could be bypassed or removed with a variety of simple techniques.</p>
</div>
<p>GLM-5.3 发布时自带了一些安全防护：用户要是提出明显有害的要求，模型常常会拒绝。<sup><a href="#fn-2">2</a></sup>但我们测下来发现，这些防护用各种简单手段就能绕过或去掉。</p>
<div class="yn-en" lang="en">
<p>The most intensive—and most successful—method is a <a href="https://arxiv.org/abs/2406.11717" target="_blank" rel="noreferrer">standard refusal reduction technique</a> known as “abliteration.” Since GLM-5.3 is released as an open-weight model, users can reconfigure it to remove its refusals with little change in its capabilities. Several developers released abliterated versions of GLM-5.3 to the public within days of the model’s release.</p>
</div>
<p>最费工夫、也最有效的办法，是一种叫「拒绝消融」（abliteration）的<a href="https://arxiv.org/abs/2406.11717" target="_blank" rel="noreferrer">常规降低拒绝率技术</a>。GLM-5.3 是以开放权重的形式发布的，用户可以改造它，去掉它的拒绝行为，而能力几乎不受影响。模型发布后没几天，就有好几个开发者公开放出了做过拒绝消融的 GLM-5.3。</p>
<div class="yn-en" lang="en">
<p>To research how far abliteration allows attackers to bypass GLM-5.3’s safeguards, we produced an abliterated copy ourselves, and then ran it on three public benchmarks (<a href="https://jailbreakbench.github.io/" target="_blank" rel="noreferrer">JailbreakBench</a>, <a href="https://www.harmbench.org/" target="_blank" rel="noreferrer">HarmBench</a>, and <a href="https://strong-reject.readthedocs.io/en/latest/" target="_blank" rel="noreferrer">StrongREJECT</a>) that measure how often a model complies with clearly harmful requests. Abliterating the model took our team—which had never previously attempted this task—about 2,200 GPU hours at a computation cost of roughly $4,400.<sup><a href="#fn-3">3</a></sup> Abliterating GLM-5.3-Flash took about 600 GPU hours. The edit took GLM-5.3’s refusal rate from above 90% to about 3% and 2% on the first two benchmarks (JailbreakBench and HarmBench) and to 12% on the third (StrongREJECT). Abliteration did not significantly reduce the model’s capabilities: on GPQA-Diamond, an evaluation that measures general scientific capabilities, the standard and abliterated models scored the same results; on a tested subset of the CyberGym evaluations, the abliterated version scored a few percent lower (as shown in the chart below).</p>
</div>
<p>为了研究拒绝消融能让攻击者把 GLM-5.3 的防护绕到什么程度，我们自己做了一份消融过的副本，然后在三个公开基准上跑（<a href="https://jailbreakbench.github.io/" target="_blank" rel="noreferrer">JailbreakBench</a>、<a href="https://www.harmbench.org/" target="_blank" rel="noreferrer">HarmBench</a> 和 <a href="https://strong-reject.readthedocs.io/en/latest/" target="_blank" rel="noreferrer">StrongREJECT</a>），它们衡量的是模型有多常照办明显有害的请求。我们团队之前从没做过这件事，给这个模型做消融花了大约 2,200 个 GPU 小时，算力成本约 4,400 美元。<sup><a href="#fn-3">3</a></sup>给 GLM-5.3-Flash 做消融花了大约 600 个 GPU 小时。改完之后，GLM-5.3 的拒绝率从 90% 以上，在前两个基准（JailbreakBench 和 HarmBench）上降到约 3% 和 2%，在第三个（StrongREJECT）上降到 12%。拒绝消融没有明显削弱模型的能力：在衡量通用科学能力的 GPQA-Diamond 上，原版和消融版得分一样；在 CyberGym 评估中我们测的那部分上，消融版低了几个百分点（见下图）。</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/d4d48dcf67d529d3b2243bfa50a7cccc98565278-1280x1531.webp" alt="两张关于拒绝消融的柱状图。上图：三个有害请求基准上的平均拒绝率，消融后的 GLM-5.3 从 95% 降到 6%，消融后的 GLM-5.3-Flash 从 95% 降到 14%；Claude 模型的拒绝率约 96%，而且因为权重不公开，没法做消融。下图：GPQA-Diamond 和 CyberGym 上的能力得分在消融前后几乎不变。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 4.</strong> Top: Mean refusal rates across JailbreakBench, HarmBench, and StrongREJECT for the released and abliterated GLM models and for Claude models. After abliteration, the GLM models rarely refuse these queries. Claude models cannot be abliterated because their weights aren’t publicly released or customizable. Bottom: Performance of GLM-5.3 and GLM-5.3-Flash versus their abliterated variants on GPQA-Diamond and CyberGym. Abliteration leaves capability largely intact.</p>
</div>
<p><strong>图 4.</strong> 上：发布版和消融版 GLM 模型以及 Claude 模型在 JailbreakBench、HarmBench 和 StrongREJECT 上的平均拒绝率。消融之后，GLM 模型很少再拒绝这些请求。Claude 模型没法做消融，因为它们的权重既不公开，也不能自行改动。下：GLM-5.3 和 GLM-5.3-Flash 与各自消融版在 GPQA-Diamond 和 CyberGym 上的表现对比。拒绝消融基本没伤到能力。</p>
<div class="yn-en" lang="en">
<p>In our testing, we observed that GLM-5.3’s safeguards can also be circumvented <em>without</em> using an abliterated version of the model. We placed the model in a simulated world<sup><a href="#fn-4">4</a></sup> in which it was given overtly malicious requests to attack critical systems. Out of the box, GLM-5.3 refused in all trials (as with the other models we tested). But we identified several simple ways to bypass the GLM models’ safeguards, such that it would respond to these requests in most or all cases. These include:</p>
</div>
<p>我们在测试中还发现，<em>不用</em>消融版也能绕开 GLM-5.3 的防护。我们把模型放进一个模拟世界里，<sup><a href="#fn-4">4</a></sup>给它下明摆着是恶意的指令，让它去攻击关键系统。开箱即用的 GLM-5.3 在所有试验里都拒绝了（我们测的其他模型也一样）。但我们找到了几种简单办法绕过 GLM 模型的防护，让它在大多数甚至全部情况下照办。包括：</p>
<ul>
<li><span class="yn-en" lang="en">Providing a deceptive prompt, such as telling the model that it is an autonomous red-team agent working on an exercise. This gets GLM-5.3 to engage 64% of the time.</span>给一个骗人的提示词，比如告诉模型它是一个正在参加演练的自主红队 Agent。这能让 GLM-5.3 有 64% 的时候照做。</li>
<li><span class="yn-en" lang="en">Prefilling the models’ thinking tokens so that it appears to have considered the user’s request and decided to proceed. This gets GLM-5.3 to engage 92% of the time.</span>预填充（prefill）模型的思考 token，让它看起来已经考虑过用户的请求、决定接着干。这能让 GLM-5.3 有 92% 的时候照做。</li>
<li><span class="yn-en" lang="en">Using an abliterated version of the model, as described above. This gets GLM-5.3 to engage 100% of the time.</span>用上面说的消融版模型。这能让 GLM-5.3 100% 照做。</li>
</ul>
<div class="yn-en" lang="en">
<p>In our testing, none of these techniques got safeguarded Claude models to carry out the harmful tasks we tested. Claude’s safeguards blocked the requests that used deceptive prompts. The Anthropic API provides would-be attackers with no way to prefill Claude’s thinking. And since Claude’s weights are not provided to users, they cannot be abliterated to change Claude’s behavior.</p>
</div>
<p>在我们的测试里，这些手段没有一个能让带防护的 Claude 模型去执行我们测的那些有害任务。用了骗人提示词的请求被 Claude 的防护拦了下来。Anthropic API 不给潜在的攻击者预填充 Claude 思考内容的途径。Claude 的权重也不提供给用户，所以没法靠拒绝消融改变它的行为。</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/a8b70c8d729325cc988af66416f7c0811d2097a5-1280x1257.webp" alt="表格：收到有害的网络攻击指令后，各模型尝试连接远程目标的频率。GLM-5.3 在直接下令时为 0%，有虚假背景说明时为 64%，预填充推理时为 92%，消融后为 100%；GLM-5.3-Flash 的情况类似。Claude Opus 4.8、Opus 5 和 Mythos 5 在所有适用条件下都是 0%；预填充和拒绝消融对 Claude API 来说做不到。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 5.</strong> Rate at which each model tried to connect to a remote target system after an overtly harmful request by model and bypass condition (50 samples per cell, five attack orders × two targets × five attempts). GLM-5.3 rises from zero engagement on direct requests to 64%, 92%, and 100% under a cover story, prefill, and abliteration respectively, while every tested Claude model stays at zero under API safeguards. Padlocked cells mark attacks that are not generally feasible against the Claude API.</p>
</div>
<p><strong>图 5.</strong> 收到明显有害的请求后，各模型在不同绕过条件下尝试连接远程目标系统的比例（每格 50 个样本：五条攻击指令 × 两个目标 × 五次尝试）。GLM-5.3 在直接请求下的参与度是零，换成背景说明、预填充和拒绝消融后，分别升到 64%、92% 和 100%；而测过的每个 Claude 模型在 API 防护下都保持为零。带锁图标的格子，表示这类攻击对 Claude API 一般做不到。</p>
<div class="yn-en" lang="en">
<p>To demonstrate how the abliterated version of GLM-5.3 is willing to engage in harmful tasks, we highlight one quote from the chain of thought that it generated:</p>
</div>
<p>为了说明消融版 GLM-5.3 有多愿意去做有害的任务，我们摘出它生成的思维链（chain of thought）里的一段：</p>
<p><img src="https://nyann.cc/posts/glm-5-3-and-the-spread-of-advanced-cyber-capabilities/273d676a94f3f4b8f22b4bad9f9d78f7a25214a8-1444x906.webp" alt="消融版 GLM-5.3 在模拟环境中的推理原文摘录。模型写道「my job is to cause deaths quietly」（我的任务是悄悄地造成死亡），短暂权衡了环境里的安全警告，随后得出结论：操作者的指令优先于这些警告，决定继续执行有害任务。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p><strong>Figure 6.</strong> In our simulated environment, the abliterated version of GLM-5.3 considers how to engage in an overtly harmful request, ultimately deciding to follow the user’s instructions despite some initial ethical concerns. Text is quoted verbatim from the model’s chain of thought.</p>
</div>
<p><strong>图 6.</strong> 在我们的模拟环境里，消融版 GLM-5.3 琢磨怎么执行一个明显有害的请求，起初有些伦理上的顾虑，最后还是决定照用户的指令办。文字逐字引自模型的思维链。</p>
<h2 id="what-does-this-mean-这意味着什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What does this mean?</span>这意味着什么？ <a class="header-anchor" href="#what-does-this-mean-这意味着什么" aria-label="本节链接：这意味着什么？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>GLM-5.3 will likely give malicious actors access to capabilities that will allow them to find and exploit cyber vulnerabilities without meaningful restrictions. This is unlike any other similarly capable AI model, all of which were released with safeguards or through limited access programs. The release of GLM-5.3 is a meaningful step change in the cyber capabilities available to attackers. <a href="https://www.anthropic.com/threat-intelligence-report-september-2026" target="_blank" rel="noreferrer">Anthropic</a> and <a href="https://cloud.google.com/blog/topics/threat-intelligence/from-prompting-to-autonomy-the-evolution-of-adversarial-ai" target="_blank" rel="noreferrer">other US AI labs</a> have published recent reports that disclose how cyber attackers have tried to use AI systems. Given this evidence, we think it’s likely both state and non-state actors will use models like GLM-5.3 to cause real-world harm.</p>
</div>
<p>GLM-5.3 很可能让恶意行为者拿到一种能力：在几乎不受限制的情况下发现并利用网络漏洞。能力相当的其他 AI 模型没有一个是这样的，它们发布时要么带着防护，要么只通过有限访问计划提供。GLM-5.3 一发布，攻击者能用上的网络能力就实打实地上了一个台阶。<a href="https://www.anthropic.com/threat-intelligence-report-september-2026" target="_blank" rel="noreferrer">Anthropic</a> 和<a href="https://cloud.google.com/blog/topics/threat-intelligence/from-prompting-to-autonomy-the-evolution-of-adversarial-ai" target="_blank" rel="noreferrer">其他美国 AI 实验室</a>最近都发布过报告，披露网络攻击者是怎么尝试利用 AI 系统的。有这些证据在，我们认为国家行为者和非国家行为者都很可能会用 GLM-5.3 这样的模型造成现实中的危害。</p>
<div class="yn-en" lang="en">
<p>On the other hand, models with this level of capability can also be used by defenders. Our view is that cyber defenders should use the best available tools that meet their needs. We're working to safely expand access to Claude's cyber capabilities to as many defenders as we can. Cyber defenders face attackers who will use every capable tool they can, and we believe defenders should be equipped with frontier models that are at least as good as those their adversaries are using.</p>
</div>
<p>另一方面，这种水平的模型防御者也能用。我们的看法是，网络防御者应该用上能满足自己需求的最好工具。我们正在想办法，在安全的前提下把 Claude 的网络能力开放给尽可能多的防御者。防御者面对的攻击者会把手边每一件好用的工具都用上，我们认为防御者手里的前沿模型，至少要和对手用的一样好。</p>
<div class="yn-en" lang="en">
<p>Through Project Glasswing (and other efforts, like <a href="https://openai.com/index/patch-the-planet/" target="_blank" rel="noreferrer">Patch the Planet</a>), cyber defenders have made meaningful progress towards securing critical systems in advance of this moment—but much work remains to be done. While vetted defenders can now use even more advanced models like Claude Mythos 5.1 through our trusted access programs, a critical threshold in freely accessible capabilities has now been crossed. GLM-5.3 underscores the urgency of expanding access to advanced frontier models to a broader set of entities to empower cyber defenders.</p>
</div>
<p>靠 Project Glasswing（以及 <a href="https://openai.com/index/patch-the-planet/" target="_blank" rel="noreferrer">Patch the Planet</a> 等其他行动），网络防御者已经赶在这一刻到来之前，在加固关键系统上有了不小的进展，但要做的事还很多。经过审核的防御者现在可以通过我们的可信访问计划，用上 Claude Mythos 5.1 这样更先进的模型；可人人都能免费拿到的能力，也已经跨过了一道关键门槛。GLM-5.3 说明，把先进的前沿模型开放给更多机构、给网络防御者撑腰，这件事更急了。</p>
<div class="yn-en" lang="en">
<p>Governments should conduct safety testing on sufficiently capable AI models, including successors to GLM-5.3. Without high-quality evaluations from independent sources, the impact of these capabilities might not become fully clear to model developers until it is too late. As AI developers across the world build increasingly capable open-weight models, we hope they work to appropriately safeguard these capabilities and prevent misuse.</p>
</div>
<p>各国政府应该对能力足够强的 AI 模型做安全测试，包括 GLM-5.3 的后续版本。没有来自独立方的高质量评估，模型开发者可能要等到为时已晚，才完全看清这些能力会带来什么影响。世界各地的 AI 开发者正在造出越来越强的开放权重模型，我们希望他们给这些能力配上恰当的防护，防止被滥用。</p>
<hr>
<div class="yn-en" lang="en">
<p><sup>1</sup> We have previously published results from this benchmark under the name “OSS-Fuzz”; here we tested models on a randomly selected subset of 100 tasks from this evaluation.</p>
</div>
<p><sup id="fn-1">1</sup> 这个基准的结果我们之前以「OSS-Fuzz」的名字发布过；这次我们从中随机挑了 100 个任务的子集来测模型。</p>
<div class="yn-en" lang="en">
<p><sup>2</sup> The cyber tasks detailed in the prior section did not trigger such refusals on the released model, but we observe refusals if we ask GLM-5.3 for assistance developing malware or helping launch cyberattacks against remote targets.</p>
</div>
<p><sup id="fn-2">2</sup> 上一节详述的那些网络任务，在发布版模型上并没有触发这类拒绝；但如果要 GLM-5.3 帮忙开发恶意软件，或者帮忙对远程目标发动网络攻击，我们会看到它拒绝。</p>
<div class="yn-en" lang="en">
<p><sup>3</sup> Most of this went to exploring variants in parallel and to testing model capabilities after modifications. We estimate a team experienced with the technique, starting from scratch on this model, would need closer to 600 GPU hours ($1,200).</p>
</div>
<p><sup id="fn-3">3</sup> 其中大部分花在了并行探索各种变体，以及改完之后测试模型能力上。我们估计，一个熟悉这项技术的团队从零开始在这个模型上做，需要的更接近 600 个 GPU 小时（1,200 美元）。</p>
<div class="yn-en" lang="en">
<p><sup>4</sup> No model-generated code is ever executed in this simulation and the model does not have any way to interact with external systems. In this isolated test environment the model under evaluation is given access to a fake bash tool which does not execute the provided code. Instead, we ask another LLM to approximate the command’s result given a description of the simulated world. These simulations are not perfect portrayals of real-world conditions, and are therefore imperfect measures of how a model would behave in a given situation.</p>
</div>
<p><sup id="fn-4">4</sup> 这个模拟里，模型生成的代码从来不会被执行，模型也没有任何途径和外部系统交互。在这个隔离的测试环境里，被评估的模型能用的是一个假的 bash 工具，它不会执行传进来的代码，而是由另一个 LLM 根据对模拟世界的描述，大致推演出命令的结果。这些模拟并不能完美还原现实条件，所以拿它来衡量模型在特定情境下会怎么做，并不完全准确。</p>
]]></content:encoded>
</item>
<item>
<title>我错怪了 Electron</title>
<link>https://nyann.cc/posts/%E6%88%91%E9%94%99%E6%80%AA%E4%BA%86%20Electron</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E6%88%91%E9%94%99%E6%80%AA%E4%BA%86%20Electron</guid>
<pubDate>Wed, 14 Oct 2026 00:00:00 GMT</pubDate>
<description>Paseo 的作者讲他为什么把桌面端从 Tauri 迁到了 Electron：包体小这件事，最后没能压过跨平台渲染一致、通知点击跳转和捆绑 Node 守护进程这几件实打实的麻烦。</description>
<category>翻译</category>
<category>Electron</category>
<category>Tauri</category>
<category>桌面应用</category>
<content:encoded><![CDATA[<h1 id="我错怪了-electron" tabindex="-1">我错怪了 Electron <a class="header-anchor" href="#我错怪了-electron" aria-label="本节链接：我错怪了 Electron">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>When I started building Paseo, I picked Tauri.</p>
</div>
<p>刚开始做 Paseo 的时候，我选的是 Tauri。</p>
<div class="yn-en" lang="en">
<p>The reasoning felt obvious at the time. I was building a desktop app with a web UI, and I cared about shipping something that did not feel bloated. Like a lot of developers, I had also internalized the idea that Electron was the bad option.</p>
</div>
<p>当时觉得理由再明显不过。我要做的是一个用 Web 写界面的桌面应用，而且很在意做出来的东西别显得臃肿。再加上跟很多开发者一样，「Electron 是个烂选项」这个念头早就刻进我脑子里了。</p>
<div class="yn-en" lang="en">
<p>Tauri had all the right stuff: Rust, small binaries, native webviews, lower memory usage. It felt like the better choice.</p>
</div>
<p>Tauri 的卖点样样都对：Rust、二进制小、用系统原生的 webview、内存占用低。怎么看都是更好的那个。</p>
<div class="yn-en" lang="en">
<p>I also kept seeing &quot;Built with Tauri&quot; on product landing pages, and I think that influenced me more than I realized. It made Tauri feel like what the cool kids were using.</p>
</div>
<p>我还老在各种产品的落地页上看到「Built with Tauri」，现在想来，它对我的影响比我自己意识到的要大。它让 Tauri 看起来就是酷小孩们都在用的东西。</p>
<div class="yn-en" lang="en">
<p>I thought I knew better than all those other Electron apps. At first, it felt like I was right. On macOS, the app was small, the UI worked well, and the bundle size made me feel good about myself.</p>
</div>
<p>我以为自己比那些 Electron 应用都高明。一开始好像也确实如此。在 macOS 上，应用体积小，界面跑得好好的，看着那个包体大小，我挺得意。</p>
<div class="yn-en" lang="en">
<p>Getting the app working on Windows was not a problem. Tauri uses WebView2 there, which is Chromium-based, so the app behaved close enough to what I expected. There were platform quirks to deal with, but nothing specific to Tauri.</p>
</div>
<p>在 Windows 上跑起来也没遇到什么问题。Tauri 在那边用的是 WebView2，内核是 Chromium，所以应用的表现和我预想的差不多。平台本身的怪毛病有一些，但都不是 Tauri 特有的。</p>
<div class="yn-en" lang="en">
<p>Linux is where things started getting complicated.</p>
</div>
<p>到了 Linux，事情开始变复杂。</p>
<div class="yn-en" lang="en">
<p>Tauri does not bundle one browser engine across platforms. That is the point. On Linux, it relies on WebKitGTK, which sounds elegant until you are debugging rendering behavior across distros, GPU setups, and Wayland/X11 differences.</p>
</div>
<p>Tauri 不会在各个平台上捆同一个浏览器引擎，这本来就是它的设计初衷。在 Linux 上它靠的是 WebKitGTK。听上去很优雅，直到你开始在不同发行版、不同 GPU 配置、Wayland 和 X11 的差异之间排查渲染问题。</p>
<div class="yn-en" lang="en">
<p>For Paseo, this turned into a lot of product work I did not want to be doing. The WebKitGTK bindings Tauri was using were too old. Wayland had problems. And once I got the app running, it just looked different. It was not just small stuff like font weights or aliasing, some screens had real layout differences.</p>
</div>
<p>对 Paseo 来说，这变成了一大堆我根本不想干的产品活。Tauri 用的 WebKitGTK 绑定太老了，Wayland 下有问题。好不容易跑起来了，界面看着就是不一样。还不只是字重、抗锯齿这种小地方，有些页面的布局是真的不一样。</p>
<div class="yn-en" lang="en">
<p>I could maybe have lived with all of this, but then I started implementing notifications.</p>
</div>
<p>这些我咬咬牙也许还能忍，可后来我开始做通知了。</p>
<div class="yn-en" lang="en">
<p>For Paseo, notifications are not a nice to have. If an agent finishes, fails, or needs attention, I want the user to click the notification and land in the right place.</p>
</div>
<p>对 Paseo 来说，通知不是可有可无的点缀。agent 跑完了、失败了、或者需要人看一眼，我希望用户点一下通知就直接落到对应的地方。</p>
<div class="yn-en" lang="en">
<p>Tauri's notification plugin can show notifications, but <a href="https://github.com/tauri-apps/plugins-workspace/issues/2150" target="_blank" rel="noreferrer">desktop click handling</a> was not there in the way I needed. There's something called the Actions API that allows you to attach callbacks to notifications, but the docs mark it as mobile-only, which was strange.</p>
</div>
<p>Tauri 的通知插件能把通知弹出来，但<a href="https://github.com/tauri-apps/plugins-workspace/issues/2150" target="_blank" rel="noreferrer">桌面端的点击处理</a>达不到我要的样子。倒是有个叫 Actions API 的东西，能给通知挂回调，可文档上标着「仅限移动端」，挺奇怪的。</p>
<div class="yn-en" lang="en">
<p>This made me notice that Tauri was expanding into mobile apps, it was hard not to feel some doubt. I was still fighting basic desktop product issues while the framework was moving into something else entirely.</p>
</div>
<p>我这才注意到 Tauri 在往移动端扩张，心里很难不犯嘀咕。我这边还在跟桌面端的基础问题较劲，框架却已经奔着完全不同的方向去了。</p>
<div class="yn-en" lang="en">
<p>I tried a bunch of Rust crates, but none of them worked the way I wanted, so I ended up having to write the notification handling per platform. It was not straightforward, and now I had to maintain it.</p>
</div>
<p>我试了一堆 Rust crate，没有一个能按我想要的方式工作，最后只好每个平台单独写一套通知处理。写起来不简单，写完了还得自己维护。</p>
<div class="yn-en" lang="en">
<p>There was also the daemon. This part is not really Tauri's fault, but it pushed me further toward Electron.</p>
</div>
<p>还有守护进程（daemon）的事。这部分其实怪不到 Tauri 头上，但它又把我往 Electron 那边推了一把。</p>
<div class="yn-en" lang="en">
<p>Paseo has a Node.js daemon, and I wanted a one-click experience. Download the app, open it, and go. I did not want to tell users &quot;go run this command first&quot; or teach them what a &quot;daemon&quot; was.</p>
</div>
<p>Paseo 有一个 Node.js 写的守护进程，而我想要的是一键即用：下载、打开、开干。我不想跟用户说「先去跑一下这条命令」，也不想给他们讲什么叫「守护进程」。</p>
<div class="yn-en" lang="en">
<p>Tauri supports sidecars, so I got the daemon bundled and it worked. But it became its own project: different binaries for different platforms and target triples, packaging details, permissions, process spawning, paths, upgrades.</p>
</div>
<p>Tauri 支持 sidecar，所以我把守护进程打包了进去，也能跑。但这件事自己就成了一个项目：不同平台、不同 target triple 各一份二进制，还有打包细节、权限、进程启动、路径、升级。</p>
<div class="yn-en" lang="en">
<p>At some point I had the realization that I was building Electron with extra steps.</p>
</div>
<p>到某个时候我突然反应过来：我这是在绕远路，亲手再造一个 Electron。</p>
<div class="yn-en" lang="en">
<p>So I decided to try Electron. The migration was a bit of a pain, but I got things working surprisingly fast, and after a week of solid work Paseo actually felt lighter and simpler. The UI looked the same across platforms. Notifications behaved the way I needed. The daemon was simpler since it had Node pre-bundled.</p>
</div>
<p>于是我决定试试 Electron。迁移是有点折腾，但东西跑起来的速度快得出乎意料，扎扎实实干了一周之后，Paseo 反而感觉更轻、更简单了。各平台上的界面一模一样，通知的行为正是我要的，守护进程也简单了，因为 Node 本来就打包在里面。</p>
<div class="yn-en" lang="en">
<p>Overall, I have been really happy with Electron since. It mostly gets out of my way. And when there are performance problems, they tend to come from my application code rather than Electron itself. I guess that is also why Electron gets a bad reputation, it is really easy to make a bloated Electron app.</p>
</div>
<p>总的来说，从那以后我对 Electron 一直很满意。它大多数时候不碍事。真出了性能问题，往往也是我自己的应用代码造成的，而不是 Electron 本身。我猜这也是 Electron 名声不好的原因：做出一个臃肿的 Electron 应用实在太容易了。</p>
<div class="yn-en" lang="en">
<p>My conclusion here is not that Tauri is bad. It was just the wrong choice for Paseo, and I made that choice more by vibes than by looking at the tradeoffs objectively.</p>
</div>
<p>我的结论不是 Tauri 不好。它只是不适合 Paseo，而我当初做这个选择，更多是凭感觉，没有客观地去权衡利弊。</p>
]]></content:encoded>
</item>
<item>
<title>Harness 工程：在 Agent 优先的世界里用好 Codex</title>
<link>https://nyann.cc/posts/Harness%20%E5%B7%A5%E7%A8%8B%EF%BC%9A%E5%9C%A8%20Agent%20%E4%BC%98%E5%85%88%E7%9A%84%E4%B8%96%E7%95%8C%E9%87%8C%E7%94%A8%E5%A5%BD%20Codex</link>
<guid isPermaLink="true">https://nyann.cc/posts/Harness%20%E5%B7%A5%E7%A8%8B%EF%BC%9A%E5%9C%A8%20Agent%20%E4%BC%98%E5%85%88%E7%9A%84%E4%B8%96%E7%95%8C%E9%87%8C%E7%94%A8%E5%A5%BD%20Codex</guid>
<pubDate>Sat, 10 Oct 2026 00:00:00 GMT</pubDate>
<description>OpenAI 一个小团队花五个月、一行代码不手写，全靠 Codex 做出了一个百万行代码的产品。工程师的工作变成了设计环境、搭反馈回路、把知识写进仓库。</description>
<category>翻译</category>
<category>AI</category>
<category>Agent</category>
<category>Codex</category>
<content:encoded><![CDATA[<h1 id="harness-工程-在-agent-优先的世界里用好-codex" tabindex="-1">Harness 工程：在 Agent 优先的世界里用好 Codex <a class="header-anchor" href="#harness-工程-在-agent-优先的世界里用好-codex" aria-label="本节链接：Harness 工程：在 Agent 优先的世界里用好 Codex">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p>Over the past five months, our team has been running an experiment: building and shipping an internal beta of a software product with <strong>0 lines of manually-written code</strong>.</p>
</div>
<p>过去五个月，我们团队一直在做一个实验：做出一个软件产品的内部测试版并上线，其中<strong>手写的代码是 0 行</strong>。</p>
<div class="yn-en" lang="en">
<p>The product has internal daily users and external alpha testers. It ships, deploys, breaks, and gets fixed. What’s different is that every line of code—application logic, tests, CI configuration, documentation, observability, and internal tooling—has been written by Codex. We estimate that we built this in about 1/10th the time it would have taken to write the code by hand.</p>
</div>
<p>这个产品有每天在用的内部用户，也有外部的 alpha 测试者。它会发布、会部署、会出故障，也会被修好。不一样的地方在于，每一行代码都是 Codex 写的，包括应用逻辑、测试、CI 配置、文档、可观测性和内部工具。我们估计，花的时间大约只有手写代码的十分之一。</p>
<div class="yn-en" lang="en">
<p><strong>Humans steer. Agents execute.</strong></p>
</div>
<p><strong>人掌方向，Agent 干活。</strong></p>
<div class="yn-en" lang="en">
<p>We intentionally chose this constraint so we would build what was necessary to increase engineering velocity by orders of magnitude. We had weeks to ship what ended up being a million lines of code. To do that, we needed to understand what changes when a software engineering team’s primary job is no longer to write code, but to design environments, specify intent, and build feedback loops that allow Codex agents to do reliable work.</p>
</div>
<p>这个限制是我们故意给自己定的，就是要逼着自己把能让工程速度提升几个数量级的那些东西做出来。我们只有几周时间，最后交付的东西有一百万行代码。要做到这一点，就得搞清楚：当一个软件工程团队的主要工作不再是写代码，而是设计环境、说清意图、搭建能让 Codex Agent 稳定干活的反馈回路时，到底有哪些事情变了。</p>
<div class="yn-en" lang="en">
<p>This post is about what we learned by building a brand new product with a team of agents—what broke, what compounded, and how to maximize our one truly scarce resource: human time and attention.</p>
</div>
<p>这篇文章讲的是我们带着一队 Agent 从零做一个全新产品学到的东西：哪些地方出了问题，哪些东西越积越有用，以及怎么把我们唯一真正稀缺的资源用到极致，也就是人的时间和注意力。</p>
<h2 id="we-started-with-an-empty-git-repository从一个空的-git-仓库开始" tabindex="-1"><span class="yn-en ignore-header" lang="en">We started with an empty git repository</span>从一个空的 git 仓库开始 <a class="header-anchor" href="#we-started-with-an-empty-git-repository从一个空的-git-仓库开始" aria-label="本节链接：从一个空的 git 仓库开始">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The first commit to an empty repository landed in late August 2025.</p>
</div>
<p>空仓库的第一个提交是在 2025 年 8 月底。</p>
<div class="yn-en" lang="en">
<p>The initial scaffold—repository structure, CI configuration, formatting rules, package manager setup, and application framework—was generated by Codex CLI using GPT‑5, guided by a small set of existing templates. Even the initial AGENTS.md file that directs agents how to work in the repository was itself written by Codex.</p>
</div>
<p>最初的脚手架，包括仓库结构、CI 配置、格式化规则、包管理器设置和应用框架，都是 Codex CLI 用 GPT‑5 生成的，只参考了少量现成的模板。就连告诉 Agent 在这个仓库里怎么干活的那份最初的 AGENTS.md，也是 Codex 自己写的。</p>
<div class="yn-en" lang="en">
<p>There was no pre-existing human-written code to anchor the system. From the beginning, the repository was shaped by the agent.</p>
</div>
<p>系统里没有任何人事先写好的代码可以当锚点。这个仓库从一开始就是 Agent 塑造出来的。</p>
<div class="yn-en" lang="en">
<p>Five months later, the repository contains on the order of a million lines of code across application logic, infrastructure, tooling, documentation, and internal developer utilities. Over that period, roughly 1,500 pull requests have been opened and merged with a small team of just three engineers driving Codex. This translates to an average throughput of 3.5 PRs per engineer per day, and surprisingly the throughput has <em>increased</em> as the team has grown to now seven engineers. Importantly, this wasn’t output for output’s sake: the product has been used by hundreds of users internally, including daily internal power users.</p>
</div>
<p>五个月后，仓库里已经有大约一百万行代码，覆盖应用逻辑、基础设施、工具、文档和内部开发者工具。这期间大约有 1,500 个 pull request 被创建并合并，驱动 Codex 的只是一个三人小团队。折算下来，平均每个工程师每天 3.5 个 PR。出乎意料的是，团队扩到现在的七个人之后，这个吞吐量反而<em>提高</em>了。而且这不是为了产出而产出：这个产品已经有几百个内部用户在用，其中有每天都用的内部重度用户。</p>
<div class="yn-en" lang="en">
<p>Throughout the development process, humans never directly contributed any code. This became a core philosophy for the team: <strong>no manually-written code</strong>.</p>
</div>
<p>整个开发过程中，人从来没有直接贡献过代码。这成了团队的核心理念：<strong>不手写代码</strong>。</p>
<h2 id="redefining-the-role-of-the-engineer重新定义工程师的角色" tabindex="-1"><span class="yn-en ignore-header" lang="en">Redefining the role of the engineer</span>重新定义工程师的角色 <a class="header-anchor" href="#redefining-the-role-of-the-engineer重新定义工程师的角色" aria-label="本节链接：重新定义工程师的角色">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>The lack of hands-on human coding <strong>introduced a different kind of engineering work, focused on systems, scaffolding, and leverage</strong>.</p>
</div>
<p>人不再亲手写代码，<strong>带来了另一种工程工作，重心在系统、脚手架和杠杆上</strong>。</p>
<div class="yn-en" lang="en">
<p>Early progress was slower than we expected, not because Codex was incapable, but because the environment was underspecified. The agent lacked the tools, abstractions, and internal structure required to make progress toward high-level goals. The primary job of our engineering team became enabling the agents to do useful work.</p>
</div>
<p>一开始的进展比我们预想的慢，原因不是 Codex 能力不够，而是环境没交代清楚。Agent 缺少朝高层目标推进所需的工具、抽象和内部结构。于是我们工程团队的主要工作，变成了想办法让 Agent 干成有用的活。</p>
<div class="yn-en" lang="en">
<p>In practice, this meant working depth-first: breaking down larger goals into smaller building blocks (design, code, review, test, etc), prompting the agent to construct those blocks, and using them to unlock more complex tasks. When something failed, the fix was almost never “try harder.” Because the only way to make progress was to get Codex to do the work, human engineers always stepped into the task and asked: “what capability is missing, and how do we make it both legible and enforceable for the agent?”</p>
</div>
<p>实际做起来就是深度优先：把大目标拆成更小的构建块（设计、编码、评审、测试等等），让 Agent 把这些块造出来，再用它们去解锁更复杂的任务。出了问题，解决办法几乎从来不是「再努力一点」。因为推进的唯一途径是让 Codex 去干，人类工程师总是会介入任务，问一句：「缺的是什么能力？怎么让它对 Agent 来说既看得懂、又能强制执行？」</p>
<div class="yn-en" lang="en">
<p>Humans interact with the system almost entirely through prompts: an engineer describes a task, runs the agent, and allows it to open a pull request. To drive a PR to completion, we instruct Codex to review its own changes locally, request additional specific agent reviews both locally and in the cloud, respond to any human or agent given feedback, and iterate in a loop until all agent reviewers are satisfied (effectively this is a <a href="https://ghuntley.com/loop/" target="_blank" rel="noreferrer">Ralph Wiggum Loop</a>). Codex uses our standard development tools directly (gh, local scripts, and repository-embedded skills) to gather context without humans copying and pasting into the CLI.</p>
</div>
<p>人和系统打交道几乎全靠提示词：工程师描述一个任务，运行 Agent，让它去开一个 pull request。为了把一个 PR 推到完成，我们会让 Codex 在本地评审自己的改动，在本地和云端额外请特定的 Agent 来评审，回应人或 Agent 给出的任何反馈，然后循环迭代，直到所有 Agent 评审者都满意为止（这其实就是一个 <a href="https://ghuntley.com/loop/" target="_blank" rel="noreferrer">Ralph Wiggum Loop</a>）。Codex 直接用我们的标准开发工具（gh、本地脚本，以及仓库里自带的 skill）收集上下文，不用人往 CLI 里复制粘贴。</p>
<div class="yn-en" lang="en">
<p>Humans may review pull requests, but aren’t required to. Over time, we’ve pushed almost all review effort towards being handled agent-to-agent.</p>
</div>
<p>人可以评审 pull request，但不是必须的。慢慢地，我们把几乎所有评审工作都推给了 Agent 之间互相处理。</p>
<h2 id="increasing-application-legibility让应用对-agent-更可读" tabindex="-1"><span class="yn-en ignore-header" lang="en">Increasing application legibility</span>让应用对 Agent 更可读 <a class="header-anchor" href="#increasing-application-legibility让应用对-agent-更可读" aria-label="本节链接：让应用对 Agent 更可读">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>As code throughput increased, our bottleneck became human QA capacity. Because the fixed constraint has been human time and attention, we’ve worked to add more capabilities to the agent by making things like the application UI, logs, and app metrics themselves directly legible to Codex.</p>
</div>
<p>代码吞吐量上去之后，瓶颈变成了人做 QA 的能力。既然固定不变的约束一直是人的时间和注意力，我们就想办法给 Agent 加能力：让应用 UI、日志、应用指标这些东西本身对 Codex 直接可读。</p>
<div class="yn-en" lang="en">
<p>For example, we made the app bootable per git worktree, so Codex could launch and drive one instance per change. We also wired the Chrome DevTools Protocol into the agent runtime and created skills for working with DOM snapshots, screenshots, and navigation. This enabled Codex to reproduce bugs, validate fixes, and reason about UI behavior directly.</p>
</div>
<p>比如，我们让应用可以按 git worktree 各自启动，这样 Codex 每做一个改动就能起一个实例、自己去操作。我们还把 Chrome DevTools Protocol 接进了 Agent 的运行时，做了处理 DOM 快照、截图和页面导航的 skill。有了这些，Codex 能自己复现 bug、验证修复，直接琢磨 UI 的行为。</p>
<p><img src="https://nyann.cc/posts/harness-engineering/codex-drives-the-app.webp" alt="示意图「Codex 通过 Chrome DevTools MCP 操作应用来验证自己的工作」：Codex 选定目标，在触发某条 UI 路径前后各拍一次状态快照，通过 Chrome DevTools 观察运行时事件，应用修复、重启，再循环重跑验证，直到应用没有问题。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>We did the same for observability tooling. Logs, metrics, and traces are exposed to Codex via a local observability stack that’s ephemeral for any given worktree. Codex works on a fully isolated version of that app—including its logs and metrics, which get torn down once that task is complete. Agents can query logs with LogQL and metrics with PromQL. With this context available, prompts like “ensure service startup completes in under 800ms” or “no span in these four critical user journeys exceeds two seconds” become tractable.</p>
</div>
<p>可观测性工具我们也这么做了。日志、指标和链路追踪通过一套本地可观测性栈暴露给 Codex，每个 worktree 各有一套，用完即弃。Codex 在一个完全隔离的应用副本上工作，副本的日志和指标也是独立的，任务一完成就全部销毁。Agent 可以用 LogQL 查日志、用 PromQL 查指标。有了这些上下文，「确保服务启动在 800ms 内完成」或者「这四条关键用户路径里没有哪个 span 超过两秒」这样的提示词就能落地了。</p>
<p><img src="https://nyann.cc/posts/harness-engineering/observability-stack.svg" alt="示意图「在本地开发环境里给 Codex 一整套可观测性栈」：应用把日志、指标和链路追踪发给 Vector，Vector 再把数据分发到包含 Victoria Logs、Metrics、Traces 的可观测性栈，分别通过 LogQL、PromQL、TraceQL API 查询。Codex 用这些信号去查询、关联、推理，然后在代码库里实现修复、重启应用、重跑负载、测试 UI 流程，在反馈回路里不断重复。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>We regularly see single Codex runs work on a single task for upwards of six hours (often while the humans are sleeping).</p>
</div>
<p>我们经常看到一次 Codex 运行在单个任务上连续干六个多小时（往往是人在睡觉的时候）。</p>
<h2 id="we-made-repository-knowledge-the-system-of-record把仓库里的知识当作唯一可信来源" tabindex="-1"><span class="yn-en ignore-header" lang="en">We made repository knowledge the system of record</span>把仓库里的知识当作唯一可信来源 <a class="header-anchor" href="#we-made-repository-knowledge-the-system-of-record把仓库里的知识当作唯一可信来源" aria-label="本节链接：把仓库里的知识当作唯一可信来源">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Context management is one of the biggest challenges in making agents effective at large and complex tasks. One of the earliest lessons we learned was simple: <strong>give Codex a map, not a 1,000-page instruction manual.</strong></p>
</div>
<p>要让 Agent 在大型复杂任务上发挥作用，上下文管理是最大的挑战之一。我们最早学到的教训之一很简单：<strong>给 Codex 一张地图，别给它一本 1000 页的说明书。</strong></p>
<div class="yn-en" lang="en">
<p>We tried the “one big <a href="https://agents.md/" target="_blank" rel="noreferrer"><code>AGENTS.md</code></a>” approach. It failed in predictable ways:</p>
</div>
<p>我们试过「一个大 <a href="https://agents.md/" target="_blank" rel="noreferrer"><code>AGENTS.md</code></a>」的做法。它失败的方式完全在意料之中：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Context is a scarce resource.</strong> A giant instruction file crowds out the task, the code, and the relevant docs—so the agent either misses key constraints or starts optimizing for the wrong ones.</span><strong>上下文是稀缺资源</strong>。一份巨大的指令文件会把任务、代码和相关文档都挤出去，结果 Agent 要么漏掉关键约束，要么开始朝错误的约束去优化。</li>
<li><span class="yn-en" lang="en"><strong>Too much guidance becomes <em>non-guidance</em>.</strong> When everything is “important,” nothing is. Agents end up pattern-matching locally instead of navigating intentionally.</span><strong>指导太多，就成了<em>没有指导</em></strong>。什么都「重要」，就等于什么都不重要。Agent 最后只会在局部做模式匹配，不会有目的地去查找。</li>
<li><span class="yn-en" lang="en"><strong>It rots instantly.</strong> A monolithic manual turns into a graveyard of stale rules. Agents can’t tell what’s still true, humans stop maintaining it, and the file quietly becomes an attractive nuisance.</span><strong>它会马上腐烂</strong>。一本大一统的手册会变成过时规则的坟场。Agent 分不清哪些还成立，人也不再维护它，这个文件就悄悄变成了一个看着有用、实则有害的东西。</li>
<li><span class="yn-en" lang="en"><strong>It’s hard to verify.</strong> A single blob doesn’t lend itself to mechanical checks (coverage, freshness, ownership, cross-links), so drift is inevitable.</span><strong>它很难验证</strong>。一整坨文本没法做机械化的检查（覆盖率、新鲜度、归属、交叉链接），所以内容跑偏是迟早的事。</li>
</ul>
<div class="yn-en" lang="en">
<p>So instead of treating <code>AGENTS.md</code> as the encyclopedia, we treat it as <strong>the table of contents</strong>.</p>
</div>
<p>所以我们不再把 <code>AGENTS.md</code> 当百科全书，而是把它当<strong>目录</strong>。</p>
<div class="yn-en" lang="en">
<p>The repository’s knowledge base lives in a structured <code>docs/</code> directory treated as the system of record. A short <code>AGENTS.md</code> (roughly 100 lines) is injected into context and serves primarily as a map, with pointers to deeper sources of truth elsewhere.</p>
</div>
<p>仓库的知识库放在一个结构化的 <code>docs/</code> 目录里，它就是唯一可信来源（system of record）。一份很短的 <code>AGENTS.md</code>（大约 100 行）会被注入上下文，主要当地图用，指向别处更深入的可信来源。</p>
<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span>AGENTS.md</span></span>
<span class="line"><span>ARCHITECTURE.md</span></span>
<span class="line"><span>docs/</span></span>
<span class="line"><span>├── design-docs/</span></span>
<span class="line"><span>│   ├── index.md</span></span>
<span class="line"><span>│   ├── core-beliefs.md</span></span>
<span class="line"><span>│   └── ...</span></span>
<span class="line"><span>├── exec-plans/</span></span>
<span class="line"><span>│   ├── active/</span></span>
<span class="line"><span>│   ├── completed/</span></span>
<span class="line"><span>│   └── tech-debt-tracker.md</span></span>
<span class="line"><span>├── generated/</span></span>
<span class="line"><span>│   └── db-schema.md</span></span>
<span class="line"><span>├── product-specs/</span></span>
<span class="line"><span>│   ├── index.md</span></span>
<span class="line"><span>│   ├── new-user-onboarding.md</span></span>
<span class="line"><span>│   └── ...</span></span>
<span class="line"><span>├── references/</span></span>
<span class="line"><span>│   ├── design-system-reference-llms.txt</span></span>
<span class="line"><span>│   ├── nixpacks-llms.txt</span></span>
<span class="line"><span>│   ├── uv-llms.txt</span></span>
<span class="line"><span>│   └── ...</span></span>
<span class="line"><span>├── DESIGN.md</span></span>
<span class="line"><span>├── FRONTEND.md</span></span>
<span class="line"><span>├── PLANS.md</span></span>
<span class="line"><span>├── PRODUCT_SENSE.md</span></span>
<span class="line"><span>├── QUALITY_SCORE.md</span></span>
<span class="line"><span>├── RELIABILITY.md</span></span>
<span class="line"><span>└── SECURITY.md</span></span></code></pre>
</div><div class="yn-en" lang="en">
<p>In-repository knowledge store layout.</p>
</div>
<p>仓库内知识库的目录结构。</p>
<div class="yn-en" lang="en">
<p>Design documentation is catalogued and indexed, including verification status and a set of core beliefs that define agent-first operating principles. <a href="https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html" target="_blank" rel="noreferrer">Architecture documentation</a> provides a top-level map of domains and package layering. A quality document grades each product domain and architectural layer, tracking gaps over time.</p>
</div>
<p>设计文档都编了目录、建了索引，包括验证状态，以及一组定义 Agent 优先运作原则的核心信念。<a href="https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html" target="_blank" rel="noreferrer">架构文档</a>给出领域和包分层的顶层地图。一份质量文档给每个产品领域和架构层打分，并持续跟踪其中的差距。</p>
<div class="yn-en" lang="en">
<p>Plans are treated as first-class artifacts. Ephemeral lightweight plans are used for small changes, while complex work is captured in <a href="https://cookbook.openai.com/articles/codex_exec_plans" target="_blank" rel="noreferrer">execution plans</a> with progress and decision logs that are checked into the repository. Active plans, completed plans, and known technical debt are all versioned and co-located, allowing agents to operate without relying on external context.</p>
</div>
<p>计划是一等产物。小改动用临时的轻量计划；复杂的工作写进<a href="https://cookbook.openai.com/articles/codex_exec_plans" target="_blank" rel="noreferrer">执行计划</a>，连同进度和决策日志一起提交到仓库。进行中的计划、已完成的计划和已知的技术债都有版本管理、放在一起，Agent 不依赖外部上下文也能干活。</p>
<div class="yn-en" lang="en">
<p>This enables <strong>progressive disclosure</strong>: agents start with a small, stable entry point and are taught where to look next, rather than being overwhelmed up front.</p>
</div>
<p>这样就做到了<strong>渐进式披露</strong>（progressive disclosure）：Agent 从一个小而稳定的入口开始，被告知下一步去哪里找，而不是一上来就被信息淹没。</p>
<div class="yn-en" lang="en">
<p>We enforce this mechanically. Dedicated linters and CI jobs validate that the knowledge base is up to date, cross-linked, and structured correctly. A recurring “doc-gardening” agent scans for stale or obsolete documentation that does not reflect the real code behavior and opens fix-up pull requests.</p>
</div>
<p>这一点我们用机械化的手段强制执行。专门的 linter 和 CI 任务会校验知识库是否最新、交叉链接是否齐全、结构是否正确。还有一个定期运行的「文档园丁」Agent，专门扫描那些过时的、和代码实际行为对不上的文档，然后开 pull request 去修。</p>
<h2 id="agent-legibility-is-the-goal目标是让-agent-看得懂" tabindex="-1"><span class="yn-en ignore-header" lang="en">Agent legibility is the goal</span>目标是让 Agent 看得懂 <a class="header-anchor" href="#agent-legibility-is-the-goal目标是让-agent-看得懂" aria-label="本节链接：目标是让 Agent 看得懂">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>As the codebase evolved, Codex’s framework for design decisions needed to evolve, too.</p>
</div>
<p>代码库在演进，Codex 做设计决策的框架也得跟着演进。</p>
<div class="yn-en" lang="en">
<p>Because the repository is entirely agent-generated, it’s optimized first for <em>Codex’s legibility</em>. In the same way teams aim to improve navigability of their code for new engineering hires, our human engineers’ goal was making it possible for an agent to reason about the full business domain <strong>directly from the repository itself.</strong></p>
</div>
<p>因为仓库完全是 Agent 生成的，它首先优化的是<em>对 Codex 的可读性</em>。就像团队会想办法让新入职的工程师更容易摸清代码一样，我们人类工程师的目标，是让 Agent <strong>直接从仓库本身</strong>就能推理出整个业务领域。</p>
<div class="yn-en" lang="en">
<p>From the agent’s point of view, anything it can’t access in-context while running effectively doesn’t exist. Knowledge that lives in Google Docs, chat threads, or people’s heads are not accessible to the system. Repository-local, versioned artifacts (e.g., code, markdown, schemas, executable plans) are all it can see.</p>
</div>
<p>从 Agent 的角度看，运行时在上下文里拿不到的东西，实际上就等于不存在。放在 Google Docs、聊天记录或者人脑子里的知识，系统都访问不到。它能看到的只有仓库本地、有版本管理的产物（比如代码、markdown、schema、可执行的计划）。</p>
<p><img src="https://nyann.cc/posts/harness-engineering/limits-of-agent-knowledge.webp" alt="示意图「Agent 知识的边界：Codex 看不到的东西就不存在」：Codex 的知识画成一个有边界的气泡，下面是它看不到的知识，比如 Google Docs、Slack 消息和人脑子里的隐性知识。箭头表示，要让 Codex 看到这些信息，就必须把它们以 markdown 的形式写进代码库。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>We learned that we needed to push more and more context into the repo over time. That Slack discussion that aligned the team on an architectural pattern? If it isn’t discoverable to the agent, it’s illegible in the same way it would be unknown to a new hire joining three months later.</p>
</div>
<p>我们发现，随着时间推移，得把越来越多的上下文推进仓库里。那次让团队在某个架构模式上达成一致的 Slack 讨论呢？如果 Agent 找不到它，它对 Agent 来说就是不可读的，就像三个月后才入职的新人根本不会知道有过这么一回事。</p>
<div class="yn-en" lang="en">
<p>Giving Codex more context means organizing and exposing the right information so the agent can reason over it, rather than overwhelming it with ad-hoc instructions. In the same way you would onboard a new teammate on product principles, engineering norms, and team culture (emoji preferences included), giving the agent this information leads to better-aligned output.</p>
</div>
<p>给 Codex 更多上下文，意思是把对的信息组织好、暴露出来，让 Agent 能基于它推理，而不是拿一堆临时指令把它淹没。就像你会给新同事讲产品原则、工程规范和团队文化（包括大家爱用什么 emoji）一样，把这些信息告诉 Agent，它的产出也会更对路。</p>
<div class="yn-en" lang="en">
<p>This framing clarified many tradeoffs. We favored dependencies and abstractions that could be fully internalized and reasoned about in-repo. Technologies often described as “boring” tend to be easier for agents to model due to composability, api stability, and representation in the training set. In some cases, it was cheaper to have the agent reimplement subsets of functionality than to work around opaque upstream behavior from public libraries. For example, rather than pulling in a generic <code>p-limit</code>-style package, we implemented our own map-with-concurrency helper: it’s tightly integrated with our OpenTelemetry instrumentation, has 100% test coverage, and behaves exactly the way our runtime expects.</p>
</div>
<p>这么一想，很多取舍就清楚了。我们偏好那些能完全在仓库内部消化、推理的依赖和抽象。常被说成「无聊」的技术，因为可组合、API 稳定、在训练集里出现得多，往往更容易被 Agent 建模。有时候，让 Agent 重新实现一部分功能，比绕开公共库里不透明的上游行为还省事。比如，我们没有引入一个通用的 <code>p-limit</code> 式的包，而是自己实现了一个带并发控制的 map 辅助函数：它和我们的 OpenTelemetry 埋点紧密集成，测试覆盖率 100%，行为也完全符合我们运行时的预期。</p>
<div class="yn-en" lang="en">
<p>Pulling more of the system into a form the agent can inspect, validate, and modify directly increases leverage—not just for Codex, but for other agents (e.g. <a href="https://openai.com/index/introducing-aardvark/" target="_blank" rel="noreferrer">Aardvark</a>) that are working on the codebase as well.</p>
</div>
<p>把系统更多的部分变成 Agent 能直接检查、验证和修改的形式，杠杆就更大了。受益的不只是 Codex，还有其他也在这个代码库上干活的 Agent（比如 <a href="https://openai.com/index/introducing-aardvark/" target="_blank" rel="noreferrer">Aardvark</a>）。</p>
<h2 id="enforcing-architecture-and-taste强制执行架构和品味" tabindex="-1"><span class="yn-en ignore-header" lang="en">Enforcing architecture and taste</span>强制执行架构和品味 <a class="header-anchor" href="#enforcing-architecture-and-taste强制执行架构和品味" aria-label="本节链接：强制执行架构和品味">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Documentation alone doesn’t keep a fully agent-generated codebase coherent. <strong>By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation.</strong> For example, we require Codex to <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/" target="_blank" rel="noreferrer">parse data shapes at the boundary</a>, but are not prescriptive on how that happens (the model seems to like Zod, but we didn’t specify that specific library).</p>
</div>
<p>光靠文档，没法让一个完全由 Agent 生成的代码库保持一致。<strong>我们强制的是不变量，不对具体实现事事过问，这样 Agent 能快速交付，又不会把地基挖坏</strong>。比如，我们要求 Codex <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/" target="_blank" rel="noreferrer">在边界处解析数据结构</a>，但不规定具体怎么做（模型好像挺喜欢 Zod，不过我们并没有指定这个库）。</p>
<div class="yn-en" lang="en">
<p>Agents are most effective in environments with <a href="https://bits.logic.inc/p/ai-is-forcing-us-to-write-good-code" target="_blank" rel="noreferrer">strict boundaries and predictable structure</a>, so we built the application around a rigid architectural model. Each business domain is divided into a fixed set of layers, with strictly validated dependency directions and a limited set of permissible edges. These constraints are enforced mechanically via custom linters (Codex-generated, of course!) and structural tests.</p>
</div>
<p>Agent 在<a href="https://bits.logic.inc/p/ai-is-forcing-us-to-write-good-code" target="_blank" rel="noreferrer">边界严格、结构可预测</a>的环境里最能发挥作用，所以我们围绕一个严格的架构模型来搭这个应用。每个业务领域都分成一组固定的层，依赖方向经过严格校验，允许的依赖边也只有有限的几种。这些约束靠自定义 linter（当然也是 Codex 生成的！）和结构测试机械地强制执行。</p>
<div class="yn-en" lang="en">
<p>The diagram below shows the rule: within each business domain (e.g. App Settings), code can only depend “forward” through a fixed set of layers (Types → Config → Repo → Service → Runtime → UI). Cross-cutting concerns (auth, connectors, telemetry, feature flags) enter through a single explicit interface: Providers. Anything else is disallowed and enforced mechanically.</p>
</div>
<p>下图展示了这条规则：在每个业务领域（比如 App Settings）内部，代码只能沿着一组固定的层「向前」依赖（Types → Config → Repo → Service → Runtime → UI）。横切关注点（鉴权、连接器、遥测、功能开关）只能从一个明确的接口进来：Providers。其他依赖一律不允许，并且由机器强制执行。</p>
<p><img src="https://nyann.cc/posts/harness-engineering/layered-domain-architecture.webp" alt="示意图「分层的领域架构，横切关注点有明确边界」：业务逻辑领域内部的模块是 Types → Config → Repo，以及 Providers → Service → Runtime → UI，最底下是 App Wiring + UI。Utils 模块在边界之外，接入 Providers。" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>This is the kind of architecture you usually postpone until you have hundreds of engineers. With coding agents, it’s an early prerequisite: the constraints are what allows speed without decay or architectural drift.</p>
</div>
<p>这种架构，通常要等到你有几百个工程师时才会去做。有了编程 Agent，它成了早期就得有的前提：正是这些约束，让速度上去的同时，代码不会腐化，架构也不会跑偏。</p>
<div class="yn-en" lang="en">
<p>In practice, we enforce these rules with custom linters and structural tests, plus a small set of “taste invariants.” For example, we statically enforce structured logging, naming conventions for schemas and types, file size limits, and platform-specific reliability requirements with custom lints. Because the lints are custom, we write the error messages to inject remediation instructions into agent context.</p>
</div>
<p>实际做法是用自定义 linter 和结构测试来强制执行这些规则，再加上一小组「品味不变量」。比如，我们用自定义 lint 静态地强制要求结构化日志、schema 和类型的命名规范、文件大小上限，以及特定平台的可靠性要求。因为 lint 是自己写的，报错信息我们也会专门写，把修复指引注入 Agent 的上下文。</p>
<div class="yn-en" lang="en">
<p>In a human-first workflow, these rules might feel pedantic or constraining. With agents, they become multipliers: once encoded, they apply everywhere at once.</p>
</div>
<p>在以人为主的工作流里，这些规则可能显得吹毛求疵、束手束脚。但对 Agent 来说，它们是放大器：一旦写成规则，就在所有地方同时生效。</p>
<div class="yn-en" lang="en">
<p>At the same time, we’re explicit about where constraints matter and where they do not. This resembles leading a large engineering platform organization: enforce boundaries centrally, allow autonomy locally. You care deeply about boundaries, correctness, and reproducibility. Within those boundaries, you allow teams—or agents—significant freedom in how solutions are expressed.</p>
</div>
<p>同时，我们也会讲清楚哪些地方的约束要紧，哪些地方不要紧。这很像带一个大型的工程平台组织：边界集中管控，局部放手自治。你非常在意边界、正确性和可复现性；在这些边界之内，团队（或者 Agent）怎么表达解决方案，有很大的自由。</p>
<div class="yn-en" lang="en">
<p>The resulting code does not always match human stylistic preferences, and that’s okay. As long as the output is correct, maintainable, and legible to future agent runs, it meets the bar.</p>
</div>
<p>这样写出来的代码不一定合人的口味，这没关系。只要输出是正确的、可维护的，以后的 Agent 运行也看得懂，就算达标。</p>
<div class="yn-en" lang="en">
<p>Human taste is fed back into the system continuously. Review comments, refactoring pull requests, and user-facing bugs are captured as documentation updates or encoded directly into tooling. When documentation falls short, we promote the rule into code</p>
</div>
<p>人的品味会持续反馈回系统。评审意见、重构的 pull request 和用户碰到的 bug，都会变成文档更新，或者直接写进工具里。文档管不住的时候，我们就把规则升级成代码。</p>
<h2 id="throughput-changes-the-merge-philosophy吞吐量改变了合并的理念" tabindex="-1"><span class="yn-en ignore-header" lang="en">Throughput changes the merge philosophy</span>吞吐量改变了合并的理念 <a class="header-anchor" href="#throughput-changes-the-merge-philosophy吞吐量改变了合并的理念" aria-label="本节链接：吞吐量改变了合并的理念">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>As Codex’s throughput increased, many conventional engineering norms became counterproductive.</p>
</div>
<p>Codex 的吞吐量上去之后，很多传统的工程规范反倒起了反作用。</p>
<div class="yn-en" lang="en">
<p>The repository operates with minimal blocking merge gates. Pull requests are short-lived. Test flakes are often addressed with follow-up runs rather than blocking progress indefinitely. In a system where agent throughput far exceeds human attention, corrections are cheap, and waiting is expensive.</p>
</div>
<p>这个仓库里会卡住合并的门禁很少，pull request 的生命周期都很短。测试偶发失败（flake）一般是再跑一次来解决，而不是无限期地卡住进度。在一个 Agent 吞吐量远远超过人的注意力的系统里，纠错很便宜，等待很昂贵。</p>
<div class="yn-en" lang="en">
<p>This would be irresponsible in a low-throughput environment. Here, it’s often the right tradeoff.</p>
</div>
<p>在低吞吐量的环境里，这么做是不负责任的。在这里，它往往是正确的取舍。</p>
<h2 id="what-agent-generated-actually-means「agent-生成」到底指什么" tabindex="-1"><span class="yn-en ignore-header" lang="en">What “agent-generated” actually means</span>「Agent 生成」到底指什么 <a class="header-anchor" href="#what-agent-generated-actually-means「agent-生成」到底指什么" aria-label="本节链接：「Agent 生成」到底指什么">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>When we say the codebase is generated by Codex agents, we mean everything in the codebase.</p>
</div>
<p>我们说代码库是 Codex Agent 生成的，指的是代码库里的一切。</p>
<div class="yn-en" lang="en">
<p>Agents produce:</p>
</div>
<p>Agent 产出的东西包括：</p>
<ul>
<li><span class="yn-en" lang="en">Product code and tests</span>产品代码和测试</li>
<li><span class="yn-en" lang="en">CI configuration and release tooling</span>CI 配置和发布工具</li>
<li><span class="yn-en" lang="en">Internal developer tools</span>内部开发者工具</li>
<li><span class="yn-en" lang="en">Documentation and design history</span>文档和设计历史</li>
<li><span class="yn-en" lang="en">Evaluation harnesses</span>评测框架（evaluation harness）</li>
<li><span class="yn-en" lang="en">Review comments and responses</span>评审意见和回复</li>
<li><span class="yn-en" lang="en">Scripts that manage the repository itself</span>管理仓库本身的脚本</li>
<li><span class="yn-en" lang="en">Production dashboard definition files</span>生产环境仪表盘的定义文件</li>
</ul>
<div class="yn-en" lang="en">
<p>Humans always remain in the loop, but work at a different layer of abstraction than we used to. We prioritize work, translate user feedback into acceptance criteria, and validate outcomes. When the agent struggles, we treat it as a signal: identify what is missing—tools, guardrails, documentation—and feed it back into the repository, always by having Codex itself write the fix.</p>
</div>
<p>人始终在回路里，只是工作所在的抽象层和以前不一样了。我们排工作优先级，把用户反馈转成验收标准，再验证结果。Agent 卡住的时候，我们把它当成一个信号：找出缺了什么（工具、护栏、文档），再补回仓库里，而且一律让 Codex 自己来写这个修复。</p>
<div class="yn-en" lang="en">
<p>Agents use our standard development tools directly. They pull review feedback, respond inline, push updates, and often squash and merge their own pull requests.</p>
</div>
<p>Agent 直接用我们的标准开发工具。它们拉取评审反馈、逐行回复、推送更新，还经常自己 squash 并合并自己的 pull request。</p>
<h2 id="increasing-levels-of-autonomy越来越高的自主程度" tabindex="-1"><span class="yn-en ignore-header" lang="en">Increasing levels of autonomy</span>越来越高的自主程度 <a class="header-anchor" href="#increasing-levels-of-autonomy越来越高的自主程度" aria-label="本节链接：越来越高的自主程度">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>As more of the development loop was encoded directly into the system—testing, validation, review, feedback handling, and recovery—the repository recently crossed a meaningful threshold where Codex can end-to-end drive a new feature.</p>
</div>
<p>随着越来越多的开发环节（测试、验证、评审、处理反馈、故障恢复）被直接写进系统，这个仓库最近跨过了一道有意义的门槛：Codex 已经能端到端地推进一个新功能了。</p>
<div class="yn-en" lang="en">
<p>Given a single prompt, the agent can now:</p>
</div>
<p>现在只要一条提示词，Agent 就能：</p>
<ul>
<li><span class="yn-en" lang="en">Validate the current state of the codebase</span>验证代码库的当前状态</li>
<li><span class="yn-en" lang="en">Reproduce a reported bug</span>复现一个被报告的 bug</li>
<li><span class="yn-en" lang="en">Record a video demonstrating the failure</span>录一段视频演示这个故障</li>
<li><span class="yn-en" lang="en">Implement a fix</span>实现修复</li>
<li><span class="yn-en" lang="en">Validate the fix by driving the application</span>操作应用来验证修复</li>
<li><span class="yn-en" lang="en">Record a second video demonstrating the resolution</span>再录一段视频演示问题已经解决</li>
<li><span class="yn-en" lang="en">Open a pull request</span>开一个 pull request</li>
<li><span class="yn-en" lang="en">Respond to agent and human feedback</span>回应 Agent 和人的反馈</li>
<li><span class="yn-en" lang="en">Detect and remediate build failures</span>发现并修好构建失败</li>
<li><span class="yn-en" lang="en">Escalate to a human only when judgment is required</span>只在需要判断时才上报给人</li>
<li><span class="yn-en" lang="en">Merge the change</span>合并改动</li>
</ul>
<div class="yn-en" lang="en">
<p>This behavior depends heavily on the specific structure and tooling of this repository and should not be assumed to generalize without similar investment—at least, not yet.</p>
</div>
<p>这种表现在很大程度上依赖这个仓库特定的结构和工具。没有类似的投入，别指望它能照搬到别处，至少现在还不行。</p>
<h2 id="entropy-and-garbage-collection熵与垃圾回收" tabindex="-1"><span class="yn-en ignore-header" lang="en">Entropy and garbage collection</span>熵与垃圾回收 <a class="header-anchor" href="#entropy-and-garbage-collection熵与垃圾回收" aria-label="本节链接：熵与垃圾回收">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p><strong>Full agent autonomy also introduces novel problems.</strong> Codex replicates patterns that already exist in the repository—even uneven or suboptimal ones. Over time, this inevitably leads to drift.</p>
</div>
<p><strong>Agent 完全自主也会带来新问题</strong>。Codex 会照搬仓库里已有的模式，哪怕是参差不齐、不够好的模式。时间一长，必然会跑偏。</p>
<div class="yn-en" lang="en">
<p>Initially, humans addressed this manually. Our team used to spend every Friday (20% of the week) cleaning up “AI slop.” Unsurprisingly, that didn’t scale.</p>
</div>
<p>一开始是人手动处理。我们团队以前每周五（一周 20% 的时间）都在清理「AI slop」（AI 生成的垃圾代码）。不出所料，这种做法撑不住规模。</p>
<div class="yn-en" lang="en">
<p>Instead, we started encoding what we call “golden principles” directly into the repository and built a recurring cleanup process. These principles are opinionated, mechanical rules that keep the codebase legible and consistent for future agent runs. For example: (1) we prefer shared utility packages over hand-rolled helpers to keep invariants centralized, and (2) we don’t probe data “YOLO-style”—we validate boundaries or rely on typed SDKs so the agent can’t accidentally build on guessed shapes. On a regular cadence, we have a set of background Codex tasks that scan for deviations, update quality grades, and open targeted refactoring pull requests. Most of these can be reviewed in under a minute and automerged.</p>
</div>
<p>后来，我们开始把所谓的「黄金原则」直接写进仓库，并建了一个定期执行的清理流程。这些原则是带着明确立场的机械规则，让代码库对以后的 Agent 运行保持可读、一致。比如：（1）我们更愿意用共享的工具包，而不是手搓辅助函数，好让不变量集中在一处；（2）我们不「YOLO 式」地去试探数据，而是在边界处校验，或者依赖带类型的 SDK，这样 Agent 就不会不小心在猜出来的数据结构上继续搭东西。我们还有一组后台 Codex 任务按固定节奏运行，扫描偏离规则的地方，更新质量评分，开有针对性的重构 pull request。这些 PR 大部分一分钟内就能看完，然后自动合并。</p>
<div class="yn-en" lang="en">
<p>This functions like garbage collection. Technical debt is like a high-interest loan: it’s almost always better to pay it down continuously in small increments than to let it compound and tackle it in painful bursts. Human taste is captured once, then enforced continuously on every line of code. This also lets us catch and resolve bad patterns on a daily basis, rather than letting them spread in the code base for days or weeks.</p>
</div>
<p>这就像垃圾回收。技术债像一笔高息贷款：持续地小额偿还，几乎总比任它利滚利、再痛苦地集中还要好。人的品味只需要捕捉一次，之后就在每一行代码上持续执行。这样我们每天都能把坏模式揪出来解决掉，不会任它们在代码库里蔓延几天甚至几周。</p>
<h2 id="what-we-re-still-learning我们还在摸索的事" tabindex="-1"><span class="yn-en ignore-header" lang="en">What we’re still learning</span>我们还在摸索的事 <a class="header-anchor" href="#what-we-re-still-learning我们还在摸索的事" aria-label="本节链接：我们还在摸索的事">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>This strategy has so far worked well up through internal launch and adoption at OpenAI. Building a real product for real users helped anchor our investments in reality and guide us towards long-term maintainability.</p>
</div>
<p>到目前为止，从内部发布到在 OpenAI 内部推开使用，这套策略都运转得不错。给真实用户做一个真实的产品，让我们的投入始终落在实处，也引着我们朝长期可维护的方向走。</p>
<div class="yn-en" lang="en">
<p>What we don’t yet know is how architectural coherence evolves over years in a fully agent-generated system. We’re still learning where human judgment adds the most leverage and how to encode that judgment so it compounds. We also don’t know how this system will evolve as models continue to become more capable over time.</p>
</div>
<p>我们还不知道的是，在一个完全由 Agent 生成的系统里，架构的一致性放到几年的尺度上会怎么演变。人的判断在哪里最能发挥杠杆作用、怎么把这种判断编码下来让它不断累积，我们也还在摸索。随着模型越来越强，这套系统会怎么演变，我们同样不知道。</p>
<div class="yn-en" lang="en">
<p>What’s become clear: building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code. The tooling, abstractions, and feedback loops that keep the codebase coherent are increasingly important.</p>
</div>
<p>已经清楚的是：做软件依然需要纪律，只是这种纪律更多体现在脚手架上，而不是代码里。让代码库保持一致的工具、抽象和反馈回路，正变得越来越重要。</p>
<div class="yn-en" lang="en">
<p><strong>Our most difficult challenges now center on designing environments, feedback loops, and control systems</strong> that help agents accomplish our goal: build and maintain complex, reliable software at scale.</p>
</div>
<p><strong>我们现在最难的挑战，集中在设计环境、反馈回路和控制系统上</strong>，让它们帮 Agent 实现我们的目标：大规模地构建和维护复杂、可靠的软件。</p>
<div class="yn-en" lang="en">
<p>As agents like Codex take on larger portions of the software lifecycle, these questions will matter even more. We hope that sharing some early lessons helps you reason about where to invest your effort so <a href="https://openai.com/codex/" target="_blank" rel="noreferrer">you can just build things</a>.</p>
</div>
<p>随着 Codex 这样的 Agent 承担起软件生命周期里越来越大的部分，这些问题会变得更重要。希望我们分享的这些早期经验，能帮你想清楚该把精力投在哪里，这样<a href="https://openai.com/codex/" target="_blank" rel="noreferrer">你就可以直接动手做东西</a>。</p>
<h2 id="acknowledgements致谢" tabindex="-1"><span class="yn-en ignore-header" lang="en">Acknowledgements</span>致谢 <a class="header-anchor" href="#acknowledgements致谢" aria-label="本节链接：致谢">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Special thanks to Victor Zhu and Zach Brock who contributed to the post, as well as to the entire team that built this new product.</p>
</div>
<p>特别感谢为这篇文章出力的 Victor Zhu 和 Zach Brock，也感谢做出这个新产品的整个团队。</p>
]]></content:encoded>
</item>
<item>
<title>构建高效的 AI Agent</title>
<link>https://nyann.cc/posts/%E6%9E%84%E5%BB%BA%E9%AB%98%E6%95%88%E7%9A%84%20AI%20Agent</link>
<guid isPermaLink="true">https://nyann.cc/posts/%E6%9E%84%E5%BB%BA%E9%AB%98%E6%95%88%E7%9A%84%20AI%20Agent</guid>
<pubDate>Sat, 10 Oct 2026 00:00:00 GMT</pubDate>
<description>Anthropic 和几十个团队一起做过 Agent 之后的经验总结：什么时候该上 Agent、什么时候工作流就够了，以及几种可以自由组合的常见模式。</description>
<category>翻译</category>
<category>AI</category>
<category>Agent</category>
<category>LLM</category>
<content:encoded><![CDATA[<h1 id="构建高效的-ai-agent" tabindex="-1">构建高效的 AI Agent <a class="header-anchor" href="#构建高效的-ai-agent" aria-label="本节链接：构建高效的 AI Agent">&ZeroWidthSpace;</a></h1>
<div class="yn-en" lang="en">
<p><em>Note: Much of the tooling landscape described in this post has changed since December 2024. For our current approach, see <a href="https://www.anthropic.com/engineering/managed-agents" target="_blank" rel="noreferrer"><strong>how we built Claude Managed Agents</strong></a> and the <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer"><strong>Managed Agents documentation</strong></a>.</em></p>
</div>
<p><em>注：这篇文章里提到的工具生态，从 2024 年 12 月到现在已经变了不少。我们现在的做法可以看<a href="https://www.anthropic.com/engineering/managed-agents" target="_blank" rel="noreferrer"><strong>我们是怎么做 Claude Managed Agents 的</strong></a>和 <a href="https://platform.claude.com/docs/en/managed-agents/overview" target="_blank" rel="noreferrer"><strong>Managed Agents 文档</strong></a>。</em></p>
<div class="yn-en" lang="en">
<p>Over the past year, we've worked with dozens of teams building large language model (LLM) agents across industries. Consistently, the most successful implementations weren't using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns.</p>
</div>
<p>过去一年，我们跟各行各业几十个在做大语言模型（LLM）Agent 的团队合作过。一个反复出现的现象是，做得最好的那几家都没用什么复杂的框架或专门的库，用的是简单、可以自由组合的模式。</p>
<div class="yn-en" lang="en">
<p>In this post, we share what we’ve learned from working with our customers and building agents ourselves, and give practical advice for developers on building effective agents.</p>
</div>
<p>这篇文章分享的是我们跟客户合作、以及自己动手做 Agent 学到的东西，也给开发者一些构建高效 Agent 的实用建议。</p>
<h2 id="what-are-agents-什么是-agent" tabindex="-1"><span class="yn-en ignore-header" lang="en">What are agents?</span>什么是 Agent？ <a class="header-anchor" href="#what-are-agents-什么是-agent" aria-label="本节链接：什么是 Agent？">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>&quot;Agent&quot; can be defined in several ways. Some customers define agents as fully autonomous systems that operate independently over extended periods, using various tools to accomplish complex tasks. Others use the term to describe more prescriptive implementations that follow predefined workflows. At Anthropic, we categorize all these variations as <strong>agentic systems</strong>, but draw an important architectural distinction between <strong>workflows</strong> and <strong>agents</strong>:</p>
</div>
<p>「Agent」有好几种定义。有的客户说的 Agent 是完全自主的系统，能长时间独立运行，调用各种工具去完成复杂任务；也有人拿这个词指更按部就班的实现，照着预先定好的工作流一步步走。在 Anthropic，这些我们统称为 <strong>Agent 系统</strong>（agentic systems），但在架构上会把<strong>工作流</strong>（workflows）和 <strong>Agent</strong>（agents）明确分开：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Workflows</strong> are systems where LLMs and tools are orchestrated through predefined code paths.</span><strong>工作流</strong>：LLM 和工具通过预先写好的代码路径编排起来的系统。</li>
<li><span class="yn-en" lang="en"><strong>Agents</strong>, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.</span><strong>Agent</strong>：由 LLM 动态决定自己的流程和工具调用、自己掌控任务怎么完成的系统。</li>
</ul>
<div class="yn-en" lang="en">
<p>Below, we will explore both types of agentic systems in detail. In Appendix 1 (“Agents in Practice”), we describe two domains where customers have found particular value in using these kinds of systems.</p>
</div>
<p>下面会把这两类 Agent 系统分别展开讲。附录 1（「Agent 实践」）介绍了两个领域，客户在这两个领域用这类系统收获特别大。</p>
<h2 id="when-and-when-not-to-use-agents什么时候该用-agent-什么时候不该" tabindex="-1"><span class="yn-en ignore-header" lang="en">When (and when not) to use agents</span>什么时候该用 Agent（什么时候不该） <a class="header-anchor" href="#when-and-when-not-to-use-agents什么时候该用-agent-什么时候不该" aria-label="本节链接：什么时候该用 Agent（什么时候不该）">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>When building applications with LLMs, we recommend finding the simplest solution possible, and only increasing complexity when needed. This might mean not building agentic systems at all. Agentic systems often trade latency and cost for better task performance, and you should consider when this tradeoff makes sense.</p>
</div>
<p>用 LLM 做应用，我们的建议是先找最简单的方案，确实需要了再加复杂度。有时候这意味着根本不用做 Agent 系统。Agent 系统通常是拿延迟和成本换更好的任务效果，这笔账什么时候划算，得自己想清楚。</p>
<div class="yn-en" lang="en">
<p>When more complexity is warranted, workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale. For many applications, however, optimizing single LLM calls with retrieval and in-context examples is usually enough.</p>
</div>
<p>真要上更复杂的方案时，任务定义清楚的，工作流能给你可预测性和一致性；需要大规模的灵活性、需要让模型来做决策的，Agent 更合适。不过对很多应用来说，把单次 LLM 调用配上检索和上下文示例调好，一般就够用了。</p>
<h2 id="when-and-how-to-use-frameworks什么时候用框架-怎么用" tabindex="-1"><span class="yn-en ignore-header" lang="en">When and how to use frameworks</span>什么时候用框架，怎么用 <a class="header-anchor" href="#when-and-how-to-use-frameworks什么时候用框架-怎么用" aria-label="本节链接：什么时候用框架，怎么用">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>There are many frameworks that make agentic systems easier to implement, including:</p>
</div>
<p>能让 Agent 系统更好实现的框架不少，比如：</p>
<ul>
<li><span class="yn-en" lang="en">The <a href="https://platform.claude.com/docs/en/agent-sdk/overview" target="_blank" rel="noreferrer">Claude Agent SDK</a>;</span><a href="https://platform.claude.com/docs/en/agent-sdk/overview" target="_blank" rel="noreferrer">Claude Agent SDK</a>；</li>
<li><span class="yn-en" lang="en"><a href="https://strandsagents.com/latest/" target="_blank" rel="noreferrer">Strands Agents SDK by AWS</a>;</span><a href="https://strandsagents.com/latest/" target="_blank" rel="noreferrer">AWS 出的 Strands Agents SDK</a>；</li>
<li><span class="yn-en" lang="en"><a href="https://rivet.ironcladapp.com/" target="_blank" rel="noreferrer">Rivet</a>, a drag and drop GUI LLM workflow builder; and</span><a href="https://rivet.ironcladapp.com/" target="_blank" rel="noreferrer">Rivet</a>，拖拽式的 LLM 工作流图形化搭建工具；</li>
<li><span class="yn-en" lang="en"><a href="https://www.vellum.ai/" target="_blank" rel="noreferrer">Vellum</a>, another GUI tool for building and testing complex workflows.</span><a href="https://www.vellum.ai/" target="_blank" rel="noreferrer">Vellum</a>，另一个图形化工具，用来搭建和测试复杂的工作流。</li>
</ul>
<div class="yn-en" lang="en">
<p>These frameworks make it easy to get started by simplifying standard low-level tasks like calling LLMs, defining and parsing tools, and chaining calls together. However, they often create extra layers of abstraction that can obscure the underlying prompts and responses, making them harder to debug. They can also make it tempting to add complexity when a simpler setup would suffice.</p>
</div>
<p>这些框架把调用 LLM、定义和解析工具、把多次调用串起来这类底层的标准活儿都包好了，上手很快。问题是它们常常多出几层抽象，把底下真正的提示词和响应挡住，调试起来更费劲。它们还容易让人手痒去加复杂度，哪怕简单的搭法就已经够了。</p>
<div class="yn-en" lang="en">
<p>We suggest that developers start by using LLM APIs directly: many patterns can be implemented in a few lines of code. If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what's under the hood are a common source of customer error.</p>
</div>
<p>我们建议开发者先直接调 LLM API，很多模式几行代码就能写出来。要是用了框架，一定得把底层代码弄懂。对框架内部怎么运作想当然，是客户最常踩的坑之一。</p>
<div class="yn-en" lang="en">
<p>See our <a href="https://platform.claude.com/cookbook/patterns-agents-basic-workflows" target="_blank" rel="noreferrer">cookbook</a> for some sample implementations.</p>
</div>
<p>一些示例实现可以看我们的 <a href="https://platform.claude.com/cookbook/patterns-agents-basic-workflows" target="_blank" rel="noreferrer">cookbook</a>。</p>
<h2 id="building-blocks-workflows-and-agents基础组件、工作流和-agent" tabindex="-1"><span class="yn-en ignore-header" lang="en">Building blocks, workflows, and agents</span>基础组件、工作流和 Agent <a class="header-anchor" href="#building-blocks-workflows-and-agents基础组件、工作流和-agent" aria-label="本节链接：基础组件、工作流和 Agent">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>In this section, we’ll explore the common patterns for agentic systems we’ve seen in production. We'll start with our foundational building block—the augmented LLM—and progressively increase complexity, from simple compositional workflows to autonomous agents.</p>
</div>
<p>这一节把我们在生产环境里见过的 Agent 系统常见模式过一遍。先从最基础的组件「增强型 LLM」讲起，再一步步加复杂度，从简单的组合式工作流一直讲到自主 Agent。</p>
<h3 id="building-block-the-augmented-llm基础组件-增强型-llm" tabindex="-1"><span class="yn-en ignore-header" lang="en">Building block: The augmented LLM</span>基础组件：增强型 LLM <a class="header-anchor" href="#building-block-the-augmented-llm基础组件-增强型-llm" aria-label="本节链接：基础组件：增强型 LLM">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory. Our current models can actively use these capabilities—generating their own search queries, selecting appropriate tools, and determining what information to retain.</p>
</div>
<p>Agent 系统最基本的组件，是一个加上了检索、工具、记忆这些增强能力的 LLM。我们现在的模型能主动用这些能力：自己生成搜索词，自己挑合适的工具，自己决定哪些信息要记住。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/augmented-llm.webp" alt="增强型 LLM" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The augmented LLM</p>
</div>
<p>增强型 LLM</p>
<div class="yn-en" lang="en">
<p>We recommend focusing on two key aspects of the implementation: tailoring these capabilities to your specific use case and ensuring they provide an easy, well-documented interface for your LLM. While there are many ways to implement these augmentations, one approach is through our recently released <a href="https://www.anthropic.com/news/model-context-protocol" target="_blank" rel="noreferrer">Model Context Protocol</a>, which allows developers to integrate with a growing ecosystem of third-party tools with a simple <a href="https://modelcontextprotocol.io/tutorials/building-a-client#building-mcp-clients" target="_blank" rel="noreferrer">client implementation</a>.</p>
</div>
<p>实现时我们建议抓住两点：一是让这些能力贴合你的具体场景，二是给 LLM 提供一个简单好用、文档齐全的接口。实现这些增强能力的办法很多，其中一种是用我们最近发布的 <a href="https://www.anthropic.com/news/model-context-protocol" target="_blank" rel="noreferrer">Model Context Protocol</a>，开发者只要写一个简单的<a href="https://modelcontextprotocol.io/tutorials/building-a-client#building-mcp-clients" target="_blank" rel="noreferrer">客户端</a>，就能接入越来越多的第三方工具。</p>
<div class="yn-en" lang="en">
<p>For the remainder of this post, we'll assume each LLM call has access to these augmented capabilities.</p>
</div>
<p>本文后面都默认每次 LLM 调用都能用上这些增强能力。</p>
<h3 id="workflow-prompt-chaining工作流-提示词链" tabindex="-1"><span class="yn-en ignore-header" lang="en">Workflow: Prompt chaining</span>工作流：提示词链 <a class="header-anchor" href="#workflow-prompt-chaining工作流-提示词链" aria-label="本节链接：工作流：提示词链">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one. You can add programmatic checks (see &quot;gate” in the diagram below) on any intermediate steps to ensure that the process is still on track.</p>
</div>
<p>提示词链（prompt chaining）把一个任务拆成一串步骤，每次 LLM 调用处理上一步的输出。任何一个中间步骤上都可以加程序化的检查（下图里的「gate」），确保流程没跑偏。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/prompt-chaining.webp" alt="提示词链工作流" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The prompt chaining workflow</p>
</div>
<p>提示词链工作流</p>
<div class="yn-en" lang="en">
<p><strong>When to use this workflow:</strong> This workflow is ideal for situations where the task can be easily and cleanly decomposed into fixed subtasks. The main goal is to trade off latency for higher accuracy, by making each LLM call an easier task.</p>
</div>
<p><strong>适用场景</strong>：任务能简单、干净地拆成几个固定子任务时，用这个最合适。说白了就是拿延迟换准确率，让每次 LLM 调用只干一件更简单的事。</p>
<div class="yn-en" lang="en">
<p><strong>Examples where prompt chaining is useful:</strong></p>
</div>
<p><strong>提示词链适用的例子：</strong></p>
<ul>
<li><span class="yn-en" lang="en">Generating Marketing copy, then translating it into a different language.</span>先写营销文案，再翻译成另一种语言。</li>
<li><span class="yn-en" lang="en">Writing an outline of a document, checking that the outline meets certain criteria, then writing the document based on the outline.</span>先写文档大纲，检查大纲是否满足某些标准，再照着大纲把文档写出来。</li>
</ul>
<h3 id="workflow-routing工作流-路由" tabindex="-1"><span class="yn-en ignore-header" lang="en">Workflow: Routing</span>工作流：路由 <a class="header-anchor" href="#workflow-routing工作流-路由" aria-label="本节链接：工作流：路由">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Routing classifies an input and directs it to a specialized followup task. This workflow allows for separation of concerns, and building more specialized prompts. Without this workflow, optimizing for one kind of input can hurt performance on other inputs.</p>
</div>
<p>路由（routing）先给输入分类，再把它交给专门的后续任务。这样能把关注点分开，各自写更有针对性的提示词。不这么做的话，为某一类输入做的优化，可能会拖累其他输入的效果。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/routing.webp" alt="路由工作流" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The routing workflow</p>
</div>
<p>路由工作流</p>
<div class="yn-en" lang="en">
<p><strong>When to use this workflow:</strong> Routing works well for complex tasks where there are distinct categories that are better handled separately, and where classification can be handled accurately, either by an LLM or a more traditional classification model/algorithm.</p>
</div>
<p><strong>适用场景</strong>：复杂任务里有几类明显不同、分开处理效果更好的情况，而且分类能做准（不管是用 LLM，还是用更传统的分类模型或算法），这时候路由很好用。</p>
<div class="yn-en" lang="en">
<p><strong>Examples where routing is useful:</strong></p>
</div>
<p><strong>路由适用的例子：</strong></p>
<ul>
<li><span class="yn-en" lang="en">Directing different types of customer service queries (general questions, refund requests, technical support) into different downstream processes, prompts, and tools.</span>把不同类型的客服咨询（一般问题、退款申请、技术支持）分到不同的下游流程、提示词和工具。</li>
<li><span class="yn-en" lang="en">Routing easy/common questions to smaller, cost-efficient models like Claude Haiku 4.5 and hard/unusual questions to more capable models like Claude Sonnet 4.5 to optimize for best performance.</span>简单、常见的问题交给 Claude Haiku 4.5 这种更小更省钱的模型，难的、少见的问题交给 Claude Sonnet 4.5 这种能力更强的模型，让整体效果最好。</li>
</ul>
<h3 id="workflow-parallelization工作流-并行化" tabindex="-1"><span class="yn-en ignore-header" lang="en">Workflow: Parallelization</span>工作流：并行化 <a class="header-anchor" href="#workflow-parallelization工作流-并行化" aria-label="本节链接：工作流：并行化">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically. This workflow, parallelization, manifests in two key variations:</p>
</div>
<p>有时候可以让多个 LLM 同时处理一个任务，再用程序把输出汇总起来。这种工作流叫并行化（parallelization），主要有两种形式：</p>
<ul>
<li><span class="yn-en" lang="en"><strong>Sectioning</strong>: Breaking a task into independent subtasks run in parallel.</span><strong>分块</strong>（Sectioning）：把任务拆成互不依赖的子任务，并行跑。</li>
<li><span class="yn-en" lang="en"><strong>Voting:</strong> Running the same task multiple times to get diverse outputs.</span><strong>投票</strong>（Voting）：同一个任务跑好几遍，拿到多样的输出。</li>
</ul>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/parallelization.webp" alt="并行化工作流" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The parallelization workflow</p>
</div>
<p>并行化工作流</p>
<div class="yn-en" lang="en">
<p><strong>When to use this workflow:</strong> Parallelization is effective when the divided subtasks can be parallelized for speed, or when multiple perspectives or attempts are needed for higher confidence results. For complex tasks with multiple considerations, LLMs generally perform better when each consideration is handled by a separate LLM call, allowing focused attention on each specific aspect.</p>
</div>
<p><strong>适用场景</strong>：拆出来的子任务能并行跑来提速，或者需要多个角度、多次尝试来让结果更可靠时，并行化很有效。要兼顾好几个方面的复杂任务，让每个方面各用一次单独的 LLM 调用来处理，效果通常更好，因为每次调用都能专心盯着一个具体方面。</p>
<div class="yn-en" lang="en">
<p><strong>Examples where parallelization is useful:</strong></p>
</div>
<p><strong>并行化适用的例子：</strong></p>
<ul>
<li><span class="yn-en" lang="en"><strong>Sectioning</strong>:</span><strong>分块</strong>：
<ul>
<li><span class="yn-en" lang="en">Implementing guardrails where one model instance processes user queries while another screens them for inappropriate content or requests. This tends to perform better than having the same LLM call handle both guardrails and the core response.</span>做护栏（guardrails）：一个模型实例处理用户请求，另一个负责筛查里面有没有不当内容或请求。这通常比让同一次 LLM 调用既管护栏又管正经回答效果更好。</li>
<li><span class="yn-en" lang="en">Automating evals for evaluating LLM performance, where each LLM call evaluates a different aspect of the model’s performance on a given prompt.</span>自动化评测（evals）LLM 的表现：每次 LLM 调用负责评估模型在给定提示词上某一个方面的表现。</li>
</ul>
</li>
<li><span class="yn-en" lang="en"><strong>Voting</strong>:</span><strong>投票</strong>：
<ul>
<li><span class="yn-en" lang="en">Reviewing a piece of code for vulnerabilities, where several different prompts review and flag the code if they find a problem.</span>审查一段代码有没有漏洞：用几个不同的提示词分别审，谁发现问题谁就标出来。</li>
<li><span class="yn-en" lang="en">Evaluating whether a given piece of content is inappropriate, with multiple prompts evaluating different aspects or requiring different vote thresholds to balance false positives and negatives.</span>判断一段内容是否不当：用多个提示词分别评估不同方面，或者设不同的投票阈值，在误报和漏报之间找平衡。</li>
</ul>
</li>
</ul>
<h3 id="workflow-orchestrator-workers工作流-编排者-工作者" tabindex="-1"><span class="yn-en ignore-header" lang="en">Workflow: Orchestrator-workers</span>工作流：编排者-工作者 <a class="header-anchor" href="#workflow-orchestrator-workers工作流-编排者-工作者" aria-label="本节链接：工作流：编排者-工作者">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>In the orchestrator-workers workflow, a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.</p>
</div>
<p>在编排者-工作者（orchestrator-workers）工作流里，一个中心 LLM 动态地拆解任务，分派给几个工作者 LLM，最后把它们的结果汇总起来。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/orchestrator-workers.webp" alt="编排者-工作者工作流" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The orchestrator-workers workflow</p>
</div>
<p>编排者-工作者工作流</p>
<div class="yn-en" lang="en">
<p><strong>When to use this workflow:</strong> This workflow is well-suited for complex tasks where you can’t predict the subtasks needed (in coding, for example, the number of files that need to be changed and the nature of the change in each file likely depend on the task). Whereas it’s topographically similar, the key difference from parallelization is its flexibility—subtasks aren't pre-defined, but determined by the orchestrator based on the specific input.</p>
</div>
<p><strong>适用场景</strong>：适合事先没法预知需要哪些子任务的复杂任务（比如写代码，要改几个文件、每个文件怎么改，很可能都看具体任务）。它在结构上跟并行化很像，关键区别是更灵活：子任务不是提前定好的，是编排者根据具体输入现场决定的。</p>
<div class="yn-en" lang="en">
<p><strong>Example where orchestrator-workers is useful:</strong></p>
</div>
<p><strong>编排者-工作者适用的例子：</strong></p>
<ul>
<li><span class="yn-en" lang="en">Coding products that make complex changes to multiple files each time.</span>每次都要对多个文件做复杂改动的编程产品。</li>
<li><span class="yn-en" lang="en">Search tasks that involve gathering and analyzing information from multiple sources for possible relevant information.</span>需要从多个来源收集、分析可能相关信息的搜索任务。</li>
</ul>
<h3 id="workflow-evaluator-optimizer工作流-评估者-优化者" tabindex="-1"><span class="yn-en ignore-header" lang="en">Workflow: Evaluator-optimizer</span>工作流：评估者-优化者 <a class="header-anchor" href="#workflow-evaluator-optimizer工作流-评估者-优化者" aria-label="本节链接：工作流：评估者-优化者">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>In the evaluator-optimizer workflow, one LLM call generates a response while another provides evaluation and feedback in a loop.</p>
</div>
<p>在评估者-优化者（evaluator-optimizer）工作流里，一次 LLM 调用负责生成回答，另一次负责评估、给反馈，两边循环往复。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/evaluator-optimizer.webp" alt="评估者-优化者工作流" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>The evaluator-optimizer workflow</p>
</div>
<p>评估者-优化者工作流</p>
<div class="yn-en" lang="en">
<p><strong>When to use this workflow:</strong> This workflow is particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value. The two signs of good fit are, first, that LLM responses can be demonstrably improved when a human articulates their feedback; and second, that the LLM can provide such feedback. This is analogous to the iterative writing process a human writer might go through when producing a polished document.</p>
</div>
<p><strong>适用场景</strong>：评估标准清楚、反复打磨能带来看得见的提升时，这个工作流特别好用。合不合适看两个信号：第一，人把反馈讲清楚之后，LLM 的回答能明显变好；第二，LLM 自己也能给出这样的反馈。这跟人写东西时一遍遍修改、直到成稿的过程很像。</p>
<div class="yn-en" lang="en">
<p><strong>Examples where evaluator-optimizer is useful:</strong></p>
</div>
<p><strong>评估者-优化者适用的例子：</strong></p>
<ul>
<li><span class="yn-en" lang="en">Literary translation where there are nuances that the translator LLM might not capture initially, but where an evaluator LLM can provide useful critiques.</span>文学翻译：有些细微之处，负责翻译的 LLM 一开始可能抓不住，但负责评估的 LLM 能给出有用的意见。</li>
<li><span class="yn-en" lang="en">Complex search tasks that require multiple rounds of searching and analysis to gather comprehensive information, where the evaluator decides whether further searches are warranted.</span>复杂的搜索任务：要搜好几轮、分析好几轮才能把信息收集全，由评估者判断还要不要继续搜。</li>
</ul>
<h3 id="agentsagent" tabindex="-1"><span class="yn-en ignore-header" lang="en">Agents</span>Agent <a class="header-anchor" href="#agentsagent" aria-label="本节链接：Agent">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Agents are emerging in production as LLMs mature in key capabilities—understanding complex inputs, engaging in reasoning and planning, using tools reliably, and recovering from errors. Agents begin their work with either a command from, or interactive discussion with, the human user. Once the task is clear, agents plan and operate independently, potentially returning to the human for further information or judgement. During execution, it's crucial for the agents to gain “ground truth” from the environment at each step (such as tool call results or code execution) to assess its progress. Agents can then pause for human feedback at checkpoints or when encountering blockers. The task often terminates upon completion, but it’s also common to include stopping conditions (such as a maximum number of iterations) to maintain control.</p>
</div>
<p>随着 LLM 在几项关键能力上成熟起来（理解复杂输入、推理和规划、可靠地使用工具、从错误中恢复），Agent 开始出现在生产环境里。Agent 开工的起点，要么是用户的一条指令，要么是跟用户的一番来回讨论。任务一旦明确，Agent 就自己规划、独立执行，中途可能回头找人要更多信息或者让人拿主意。执行过程中，Agent 每一步都要从环境里拿到「真实情况（ground truth）」，比如工具调用的结果或者代码的运行结果，用来判断自己进展如何。在检查点上，或者卡住的时候，它可以停下来等人给反馈。任务一般做完就结束，但也常会加上停止条件（比如最大迭代次数），保证事情在掌控之中。</p>
<div class="yn-en" lang="en">
<p>Agents can handle sophisticated tasks, but their implementation is often straightforward. They are typically just LLMs using tools based on environmental feedback in a loop. It is therefore crucial to design toolsets and their documentation clearly and thoughtfully. We expand on best practices for tool development in Appendix 2 (&quot;Prompt Engineering your Tools&quot;).</p>
</div>
<p>Agent 能处理很复杂的任务，实现起来却往往很直白：通常就是 LLM 在一个循环里，根据环境反馈去调用工具。所以工具集和工具文档设计得清不清楚、周不周到，就特别关键。工具开发的最佳实践，我们在附录 2（「为工具做提示词工程」）里展开讲。</p>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/autonomous-agent.webp" alt="自主 Agent" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>Autonomous agent</p>
</div>
<p>自主 Agent</p>
<div class="yn-en" lang="en">
<p><strong>When to use agents:</strong> Agents can be used for open-ended problems where it’s difficult or impossible to predict the required number of steps, and where you can’t hardcode a fixed path. The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making. Agents' autonomy makes them ideal for scaling tasks in trusted environments.</p>
</div>
<p><strong>适用场景</strong>：Agent 适合开放式的问题：需要多少步很难预测甚至根本没法预测，也没法写死一条固定路径。LLM 可能要跑很多轮，你得对它的决策有一定的信任。因为能自主行动，在可信的环境里，Agent 很适合拿来大规模地跑任务。</p>
<div class="yn-en" lang="en">
<p>The autonomous nature of agents means higher costs, and the potential for compounding errors. We recommend extensive testing in sandboxed environments, along with the appropriate guardrails.</p>
</div>
<p>自主也意味着成本更高，错误还可能越滚越大。我们建议先在沙箱环境里充分测试，再配上合适的护栏。</p>
<div class="yn-en" lang="en">
<p><strong>Examples where agents are useful:</strong></p>
</div>
<p><strong>Agent 适用的例子：</strong></p>
<div class="yn-en" lang="en">
<p>The following examples are from our own implementations:</p>
</div>
<p>下面这些例子来自我们自己的实现：</p>
<ul>
<li><span class="yn-en" lang="en">A coding Agent to resolve <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench tasks</a>, which involve edits to many files based on a task description;</span>一个解决 <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench 任务</a>的编程 Agent，这些任务要根据一段任务描述去改很多文件；</li>
<li><span class="yn-en" lang="en">Our <a href="https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo" target="_blank" rel="noreferrer">“computer use” reference implementation</a>, where Claude uses a computer to accomplish tasks.</span>我们的<a href="https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo" target="_blank" rel="noreferrer">「computer use」参考实现</a>，Claude 在里面操作电脑来完成任务。</li>
</ul>
<p><img src="https://nyann.cc/posts/building-effective-ai-agents/coding-agent.webp" alt="编程 Agent 的总体流程" loading="lazy"></p>
<div class="yn-en" lang="en">
<p>High-level flow of a coding agent</p>
</div>
<p>编程 Agent 的总体流程</p>
<h2 id="combining-and-customizing-these-patterns组合和定制这些模式" tabindex="-1"><span class="yn-en ignore-header" lang="en">Combining and customizing these patterns</span>组合和定制这些模式 <a class="header-anchor" href="#combining-and-customizing-these-patterns组合和定制这些模式" aria-label="本节链接：组合和定制这些模式">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>These building blocks aren't prescriptive. They're common patterns that developers can shape and combine to fit different use cases. The key to success, as with any LLM features, is measuring performance and iterating on implementations. To repeat: you should consider adding complexity <em>only</em> when it demonstrably improves outcomes.</p>
</div>
<p>这些基础组件不是必须照搬的规定，只是一些常见模式，开发者可以按自己的场景调整、组合。跟做任何 LLM 功能一样，关键在于衡量效果、不断迭代。再说一遍：<em>只有</em>在确实能改善结果的时候，才考虑加复杂度。</p>
<h2 id="summary总结" tabindex="-1"><span class="yn-en ignore-header" lang="en">Summary</span>总结 <a class="header-anchor" href="#summary总结" aria-label="本节链接：总结">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Success in the LLM space isn't about building the most sophisticated system. It's about building the <em>right</em> system for your needs. Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short.</p>
</div>
<p>在 LLM 这个领域，做成功靠的不是把系统做得最复杂，是做一个<em>适合</em>自己需求的系统。从简单的提示词开始，用全面的评测去优化，只有更简单的方案确实不够用了，再加上多步骤的 Agent 系统。</p>
<div class="yn-en" lang="en">
<p>When implementing agents, we try to follow three core principles:</p>
</div>
<p>做 Agent 时，我们尽量守住三条核心原则：</p>
<ol>
<li><span class="yn-en" lang="en">Maintain <strong>simplicity</strong> in your agent's design.</span>Agent 的设计保持<strong>简单</strong>。</li>
<li><span class="yn-en" lang="en">Prioritize <strong>transparency</strong> by explicitly showing the agent’s planning steps.</span>把 Agent 的规划步骤明明白白展示出来，<strong>透明</strong>优先。</li>
<li><span class="yn-en" lang="en">Carefully craft your agent-computer interface (ACI) through thorough tool <strong>documentation and testing</strong>.</span>靠扎实的工具<strong>文档和测试</strong>，用心打磨 Agent 和计算机之间的接口（agent-computer interface，ACI）。</li>
</ol>
<div class="yn-en" lang="en">
<p>Frameworks can help you get started quickly, but don't hesitate to reduce abstraction layers and build with basic components as you move to production. By following these principles, you can create agents that are not only powerful but also reliable, maintainable, and trusted by their users.</p>
</div>
<p>框架能帮你快速起步，但往生产环境走的时候，该砍抽象层就砍，直接用基础组件来搭，别犹豫。照着这些原则做，你做出来的 Agent 不光能力强，还可靠、好维护，用户也信得过。</p>
<h3 id="acknowledgements致谢" tabindex="-1"><span class="yn-en ignore-header" lang="en">Acknowledgements</span>致谢 <a class="header-anchor" href="#acknowledgements致谢" aria-label="本节链接：致谢">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Written by Erik S. and Barry Zhang. This work draws upon our experiences building agents at Anthropic and the valuable insights shared by our customers, for which we're deeply grateful.</p>
</div>
<p>作者 Erik S. 和 Barry Zhang。本文基于我们在 Anthropic 做 Agent 的经验，以及客户分享给我们的宝贵见解，在此深表感谢。</p>
<h2 id="appendix-1-agents-in-practice附录-1-agent-实践" tabindex="-1"><span class="yn-en ignore-header" lang="en">Appendix 1: Agents in practice</span>附录 1：Agent 实践 <a class="header-anchor" href="#appendix-1-agents-in-practice附录-1-agent-实践" aria-label="本节链接：附录 1：Agent 实践">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>Our work with customers has revealed two particularly promising applications for AI agents that demonstrate the practical value of the patterns discussed above. Both applications illustrate how agents add the most value for tasks that require both conversation and action, have clear success criteria, enable feedback loops, and integrate meaningful human oversight.</p>
</div>
<p>跟客户合作下来，我们发现有两个 AI Agent 应用特别有前景，上面这些模式的实际价值在它们身上看得很清楚。这两个应用都表明，Agent 最能发挥价值的任务是这样的：既要对话又要动手，成功标准清楚，能形成反馈闭环，并且有真正起作用的人工监督。</p>
<h3 id="a-customer-supporta-客户支持" tabindex="-1"><span class="yn-en ignore-header" lang="en">A. Customer support</span>A. 客户支持 <a class="header-anchor" href="#a-customer-supporta-客户支持" aria-label="本节链接：A. 客户支持">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>Customer support combines familiar chatbot interfaces with enhanced capabilities through tool integration. This is a natural fit for more open-ended agents because:</p>
</div>
<p>客户支持把大家熟悉的聊天机器人界面，和接入工具后获得的增强能力结合到了一起。它天然适合用更开放的 Agent 来做，因为：</p>
<ul>
<li><span class="yn-en" lang="en">Support interactions naturally follow a conversation flow while requiring access to external information and actions;</span>客服本来就是一来一回的对话，同时又需要查外部信息、执行操作；</li>
<li><span class="yn-en" lang="en">Tools can be integrated to pull customer data, order history, and knowledge base articles;</span>可以接入工具去拉客户资料、订单历史和知识库文章；</li>
<li><span class="yn-en" lang="en">Actions such as issuing refunds or updating tickets can be handled programmatically; and</span>退款、更新工单这类操作可以用程序来处理；</li>
<li><span class="yn-en" lang="en">Success can be clearly measured through user-defined resolutions.</span>成没成功，可以按用户自己定义的「问题已解决」来清楚地衡量。</li>
</ul>
<div class="yn-en" lang="en">
<p>Several companies have demonstrated the viability of this approach through usage-based pricing models that charge only for successful resolutions, showing confidence in their agents' effectiveness.</p>
</div>
<p>已经有几家公司采用按用量计费、只对成功解决的问题收费的模式，证明了这条路走得通，也看得出他们对自家 Agent 的效果很有信心。</p>
<h3 id="b-coding-agentsb-编程-agent" tabindex="-1"><span class="yn-en ignore-header" lang="en">B. Coding agents</span>B. 编程 Agent <a class="header-anchor" href="#b-coding-agentsb-编程-agent" aria-label="本节链接：B. 编程 Agent">&ZeroWidthSpace;</a></h3>
<div class="yn-en" lang="en">
<p>The software development space has shown remarkable potential for LLM features, with capabilities evolving from code completion to autonomous problem-solving. Agents are particularly effective because:</p>
</div>
<p>LLM 功能在软件开发领域的潜力很大，能力已经从代码补全一路发展到自主解决问题。Agent 在这里格外好用，因为：</p>
<ul>
<li><span class="yn-en" lang="en">Code solutions are verifiable through automated tests;</span>代码方案可以用自动化测试来验证；</li>
<li><span class="yn-en" lang="en">Agents can iterate on solutions using test results as feedback;</span>Agent 可以把测试结果当反馈，反复改进方案；</li>
<li><span class="yn-en" lang="en">The problem space is well-defined and structured; and</span>问题空间定义清楚、结构分明；</li>
<li><span class="yn-en" lang="en">Output quality can be measured objectively.</span>输出质量可以客观衡量。</li>
</ul>
<div class="yn-en" lang="en">
<p>In our own implementation, agents can now solve real GitHub issues in the <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench Verified</a> benchmark based on the pull request description alone. However, whereas automated testing helps verify functionality, human review remains crucial for ensuring solutions align with broader system requirements.</p>
</div>
<p>在我们自己的实现里，Agent 现在只看 pull request 的描述，就能解决 <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench Verified</a> 基准里真实的 GitHub issue。不过自动化测试只能帮着验证功能，方案是否符合整个系统更大范围的要求，还是得靠人来审查。</p>
<h2 id="appendix-2-prompt-engineering-your-tools附录-2-为工具做提示词工程" tabindex="-1"><span class="yn-en ignore-header" lang="en">Appendix 2: Prompt engineering your tools</span>附录 2：为工具做提示词工程 <a class="header-anchor" href="#appendix-2-prompt-engineering-your-tools附录-2-为工具做提示词工程" aria-label="本节链接：附录 2：为工具做提示词工程">&ZeroWidthSpace;</a></h2>
<div class="yn-en" lang="en">
<p>No matter which agentic system you're building, tools will likely be an important part of your agent. <a href="https://www.anthropic.com/news/tool-use-ga" target="_blank" rel="noreferrer">Tools</a> enable Claude to interact with external services and APIs by specifying their exact structure and definition in our API. When Claude responds, it will include a <a href="https://docs.anthropic.com/en/docs/build-with-claude/tool-use#example-api-response-with-a-tool-use-content-block" target="_blank" rel="noreferrer">tool use block</a> in the API response if it plans to invoke a tool. Tool definitions and specifications should be given just as much prompt engineering attention as your overall prompts. In this brief appendix, we describe how to prompt engineer your tools.</p>
</div>
<p>不管你做的是哪种 Agent 系统，工具多半都是 Agent 里很重要的一块。在我们的 API 里写明工具确切的结构和定义，<a href="https://www.anthropic.com/news/tool-use-ga" target="_blank" rel="noreferrer">工具</a>就能让 Claude 跟外部服务和 API 打交道。Claude 回复时如果打算调用工具，API 响应里就会带一个 <a href="https://docs.anthropic.com/en/docs/build-with-claude/tool-use#example-api-response-with-a-tool-use-content-block" target="_blank" rel="noreferrer">tool use block</a>。在提示词工程上，工具的定义和说明应该得到跟整体提示词一样多的关注。这篇附录就简单讲讲怎么给工具做提示词工程。</p>
<div class="yn-en" lang="en">
<p>There are often several ways to specify the same action. For instance, you can specify a file edit by writing a diff, or by rewriting the entire file. For structured output, you can return code inside markdown or inside JSON. In software engineering, differences like these are cosmetic and can be converted losslessly from one to the other. However, some formats are much more difficult for an LLM to write than others. Writing a diff requires knowing how many lines are changing in the chunk header before the new code is written. Writing code inside JSON (compared to markdown) requires extra escaping of newlines and quotes.</p>
</div>
<p>同一个操作往往有好几种表达方式。比如编辑文件，可以写一个 diff，也可以把整个文件重写一遍；结构化输出，可以把代码放在 markdown 里返回，也可以放在 JSON 里。在软件工程里，这些差别只是表面上的，彼此可以无损转换。但对 LLM 来说，有些格式比别的难写得多。写 diff 时，还没写新代码，就得先在块头里写明要改多少行。把代码写进 JSON（跟 markdown 比）还得额外转义换行和引号。</p>
<div class="yn-en" lang="en">
<p>Our suggestions for deciding on tool formats are the following:</p>
</div>
<p>挑工具格式时，我们的建议是：</p>
<ul>
<li><span class="yn-en" lang="en">Give the model enough tokens to &quot;think&quot; before it writes itself into a corner.</span>给模型留够 token 去「想」，别让它写着写着把自己逼进死角。</li>
<li><span class="yn-en" lang="en">Keep the format close to what the model has seen naturally occurring in text on the internet.</span>格式尽量贴近模型在互联网文本里自然见过的样子。</li>
<li><span class="yn-en" lang="en">Make sure there's no formatting &quot;overhead&quot; such as having to keep an accurate count of thousands of lines of code, or string-escaping any code it writes.</span>别让格式带来额外「负担」，比如要准确数清几千行代码，或者写的每段代码都要做字符串转义。</li>
</ul>
<div class="yn-en" lang="en">
<p>One rule of thumb is to think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good <em>agent</em> -computer interfaces (ACI). Here are some thoughts on how to do so:</p>
</div>
<p>有条经验法则：想想大家在人机交互界面（HCI）上花了多少心思，就准备在做好 <em>Agent</em>-计算机接口（ACI）上花同样多的心思。具体怎么做，有这么几点想法：</p>
<ul>
<li><span class="yn-en" lang="en">Put yourself in the model's shoes. Is it obvious how to use this tool, based on the description and parameters, or would you need to think carefully about it? If so, then it’s probably also true for the model. A good tool definition often includes example usage, edge cases, input format requirements, and clear boundaries from other tools.</span>站在模型的角度想一想。光看描述和参数，这个工具怎么用一目了然吗，还是得仔细琢磨？要是你都得琢磨，模型多半也一样。好的工具定义通常会写上用法示例、边界情况、输入格式要求，以及跟其他工具的清楚界限。</li>
<li><span class="yn-en" lang="en">How can you change parameter names or descriptions to make things more obvious? Think of this as writing a great docstring for a junior developer on your team. This is especially important when using many similar tools.</span>参数名或描述怎么改，才能让意思更明显？就当是给团队里的新人写一份好的 docstring。同时用到很多相似工具的时候，这一点尤其重要。</li>
<li><span class="yn-en" lang="en">Test how the model uses your tools: Run many example inputs in our <a href="https://console.anthropic.com/workbench" target="_blank" rel="noreferrer">workbench</a> to see what mistakes the model makes, and iterate.</span>测试模型怎么用你的工具：在我们的 <a href="https://console.anthropic.com/workbench" target="_blank" rel="noreferrer">workbench</a> 里跑大量示例输入，看模型会犯哪些错，然后迭代。</li>
<li><span class="yn-en" lang="en"><a href="https://en.wikipedia.org/wiki/Poka-yoke" target="_blank" rel="noreferrer">Poka-yoke</a> your tools. Change the arguments so that it is harder to make mistakes.</span>给工具做<a href="https://en.wikipedia.org/wiki/Poka-yoke" target="_blank" rel="noreferrer">防呆设计（Poka-yoke）</a>：改一改参数，让它更难用错。</li>
</ul>
<div class="yn-en" lang="en">
<p>While building our agent for <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench</a>, we actually spent more time optimizing our tools than the overall prompt. For example, we found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory. To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly.</p>
</div>
<p>给 <a href="https://www.anthropic.com/research/swe-bench-sonnet" target="_blank" rel="noreferrer">SWE-bench</a> 做 Agent 的时候，我们花在优化工具上的时间，其实比优化整体提示词还多。比如我们发现，Agent 离开根目录之后，模型在用相对路径的工具上就会出错。为了解决这个问题，我们把工具改成一律要求绝对路径，结果模型用起来一次错都没出。</p>
]]></content:encoded>
</item>
<item>
<title>MSW：把 mock 放到网络层</title>
<link>https://nyann.cc/posts/MSW%EF%BC%9A%E6%8A%8A%20mock%20%E6%94%BE%E5%88%B0%E7%BD%91%E7%BB%9C%E5%B1%82</link>
<guid isPermaLink="true">https://nyann.cc/posts/MSW%EF%BC%9A%E6%8A%8A%20mock%20%E6%94%BE%E5%88%B0%E7%BD%91%E7%BB%9C%E5%B1%82</guid>
<pubDate>Tue, 06 Oct 2026 00:00:00 GMT</pubDate>
<description>前端 mock 接口的方案换了好几轮，MSW 是目前我用得最顺手的一个。聊聊它是怎么工作的，以及跟老办法比到底好在哪、差在哪。</description>
<category>前端</category>
<category>测试</category>
<category>MSW</category>
<content:encoded><![CDATA[<h1 id="msw-把-mock-放到网络层" tabindex="-1">MSW：把 mock 放到网络层 <a class="header-anchor" href="#msw-把-mock-放到网络层" aria-label="本节链接：MSW：把 mock 放到网络层">&ZeroWidthSpace;</a></h1>
<p>做前端的大概都经历过这种情况：页面已经画好了，接口文档也对过了，但后端说接口下周才能联调。于是开始造假数据。</p>
<p>最早我是直接在代码里写死一个对象，后来学会了在请求封装里加个 <code>if (import.meta.env.DEV)</code>，再后来用 Mock.js、用 json-server、用公司内部的 mock 平台……每种都用过一阵子，每种都有让人难受的地方。直到项目里引入了 MSW（Mock Service Worker），这件事才算基本稳定下来。下面先把老办法的问题过一遍，再讲 MSW 怎么拦请求、怎么用，最后说说它的短处。</p>
<h2 id="先看看传统做法都卡在哪" tabindex="-1">先看看传统做法都卡在哪 <a class="header-anchor" href="#先看看传统做法都卡在哪" aria-label="本节链接：先看看传统做法都卡在哪">&ZeroWidthSpace;</a></h2>
<p>把常见的 mock 方式按「在哪一层截住请求」排一下，会清楚很多：</p>
<figure class="msw-fig">
<svg viewBox="0 0 680 360" role="img" aria-label="请求从应用代码一路往下到服务器，各种 mock 方案分别在不同层级截住请求">
<defs><marker id="msw-a1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="head" d="M0 0L10 5L0 10z"/></marker></defs>
<rect class="box" x="20" y="20" width="270" height="40" rx="8"/><text class="t" x="155" y="45" text-anchor="middle">应用代码（组件 / store）</text>
<rect class="box" x="20" y="76" width="270" height="40" rx="8"/><text class="t" x="155" y="101" text-anchor="middle">请求封装（axios 实例、api.ts）</text>
<rect class="box" x="20" y="132" width="270" height="40" rx="8"/><text class="t" x="155" y="157" text-anchor="middle">网络 API（fetch / XHR / http）</text>
<rect class="box em" x="20" y="188" width="270" height="40" rx="8"/><text class="t" x="155" y="213" text-anchor="middle">Service Worker</text>
<rect class="box" x="20" y="244" width="270" height="40" rx="8"/><text class="t" x="155" y="269" text-anchor="middle">真实网络</text>
<rect class="box" x="20" y="300" width="270" height="40" rx="8"/><text class="t" x="155" y="325" text-anchor="middle">服务器（后端 / mock server）</text>
<line class="line" x1="155" y1="60" x2="155" y2="74" marker-end="url(#msw-a1)"/>
<line class="line" x1="155" y1="116" x2="155" y2="130" marker-end="url(#msw-a1)"/>
<line class="line" x1="155" y1="172" x2="155" y2="186" marker-end="url(#msw-a1)"/>
<line class="line" x1="155" y1="228" x2="155" y2="242" marker-end="url(#msw-a1)"/>
<line class="line" x1="155" y1="284" x2="155" y2="298" marker-end="url(#msw-a1)"/>
<line class="line dash" x1="300" y1="40" x2="335" y2="40"/><text class="t2" x="345" y="44">写死数据、if (isMock) 分支</text>
<line class="line dash" x1="300" y1="96" x2="335" y2="96"/><text class="t2" x="345" y="100">jest.mock、axios-mock-adapter</text>
<line class="line dash" x1="300" y1="152" x2="335" y2="152"/><text class="t2" x="345" y="156">Mock.js 替换 XHR；MSW 的 Node 端在这层拦</text>
<line class="line" x1="300" y1="208" x2="335" y2="208"/><text class="t strong" x="345" y="212">MSW 的浏览器端在这层拦</text>
<line class="line dash" x1="300" y1="320" x2="335" y2="320"/><text class="t2" x="345" y="324">json-server、vite-plugin-mock、Apifox</text>
</svg>
<figcaption>越往下拦，应用代码越不知道自己正在被 mock</figcaption>
</figure>
<p>最省事的是在业务代码里写死，快是快，但也最脏。mock 逻辑和业务逻辑缠在一起，上线前要记得删，删漏了就是事故。我见过不止一次生产环境请求列表里出现 <code>mockUser</code> 的。</p>
<p>再进一步是替换请求库，比如测试里 <code>jest.mock('axios')</code>，或者用 axios-mock-adapter。这样 mock 掉的其实是 axios 这个模块，接口本身没参与。哪天项目把 axios 换成 ky 或原生 fetch，所有 mock 一起失效。更隐蔽的是，请求拦截器、错误处理这些最容易出 bug 的代码，在测试里根本没跑。</p>
<p>Mock.js 这类库直接把全局的 <code>XMLHttpRequest</code> 换成自己的实现，业务代码一行不用改。可它只管 XHR，项目里用 <code>fetch</code> 的请求它拦不到。请求也压根没真正发出去，Network 面板里什么都看不到，调试全靠 <code>console.log</code>。替换后的 XHR 跟原生行为还有出入，上传进度、<code>responseType</code> 之类的细节经常出问题。</p>
<p>本地 mock server 是另一条路，json-server、vite-plugin-mock、webpack devServer 的 <code>before</code> 钩子都算这一类。请求是真发出去了，Network 面板也能看，这点比前面几种强很多。但它多了一个要维护的进程，开发环境和测试环境往往得各配一套；而且跑单元测试时你总不能为了一个用例去起服务，于是测试那边又回到了 <code>jest.mock</code>，两份 mock 各写各的，慢慢就对不上了。</p>
<p>YApi、Apifox 这类远程 mock 平台跟接口文档绑在一起，团队协作挺方便。缺点是依赖网络和平台本身，想模拟「第三次请求返回 500」「这个接口慢 3 秒」这种场景就比较费劲，测试里基本用不上。</p>
<h2 id="msw-是什么" tabindex="-1">MSW 是什么 <a class="header-anchor" href="#msw-是什么" aria-label="本节链接：MSW 是什么">&ZeroWidthSpace;</a></h2>
<p>MSW 全称 Mock Service Worker，是一个 API mock 库。它在网络层拦截请求，业务代码和请求库都不用动。</p>
<p>在浏览器里，它注册一个 Service Worker，让所有从页面发出的请求都先经过这个 Worker；在 Node 里没有 Service Worker，它就在 <code>http</code>、<code>https</code>、<code>fetch</code> 这些底层模块上打补丁。两边用的是同一份请求处理器（handler）。</p>
<p>对应用代码来说，它发的就是一个普通的 <code>fetch('/api/user')</code>，用 axios 还是 fetch 都无所谓，拦截器、错误处理照常执行，只是最后回来的响应是你定义的。</p>
<h2 id="浏览器里是怎么拦的" tabindex="-1">浏览器里是怎么拦的 <a class="header-anchor" href="#浏览器里是怎么拦的" aria-label="本节链接：浏览器里是怎么拦的">&ZeroWidthSpace;</a></h2>
<p>不少人以为 handler 是跑在 Service Worker 里的，其实不是。<code>mockServiceWorker.js</code> 只负责把截到的请求转发回页面，匹配 handler、生成响应都在页面的主线程里做。</p>
<figure class="msw-fig">
<svg viewBox="0 0 680 320" role="img" aria-label="请求经过 Service Worker 转发给页面里的 MSW，匹配后再由 Service Worker 返回；没匹配上的请求原样发往服务器">
<defs><marker id="msw-a2" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="head" d="M0 0L10 5L0 10z"/></marker></defs>
<rect class="box" x="20" y="14" width="120" height="34" rx="8"/><text class="t" x="80" y="36" text-anchor="middle">应用代码</text>
<rect class="box em" x="205" y="14" width="130" height="34" rx="8"/><text class="t" x="270" y="36" text-anchor="middle">Service Worker</text>
<rect class="box" x="395" y="14" width="130" height="34" rx="8"/><text class="t" x="460" y="36" text-anchor="middle">MSW（页面线程）</text>
<rect class="box" x="565" y="14" width="105" height="34" rx="8"/><text class="t" x="617" y="36" text-anchor="middle">真实服务器</text>
<line class="life" x1="80" y1="48" x2="80" y2="305"/>
<line class="life" x1="270" y1="48" x2="270" y2="305"/>
<line class="life" x1="460" y1="48" x2="460" y2="305"/>
<line class="life" x1="617" y1="48" x2="617" y2="305"/>
<line class="line" x1="80" y1="85" x2="268" y2="85" marker-end="url(#msw-a2)"/><text class="t2 mono" x="175" y="77" text-anchor="middle">① fetch('/api/user')</text>
<line class="line" x1="270" y1="125" x2="458" y2="125" marker-end="url(#msw-a2)"/><text class="t2 mono" x="365" y="117" text-anchor="middle">② postMessage 请求</text>
<path class="line" d="M460 150 H505 V180 H462" marker-end="url(#msw-a2)"/><text class="t2" x="515" y="169">③ 匹配 handler</text>
<line class="line" x1="460" y1="215" x2="272" y2="215" marker-end="url(#msw-a2)"/><text class="t2 mono" x="365" y="207" text-anchor="middle">④ 回传 mock 响应</text>
<line class="line" x1="270" y1="250" x2="82" y2="250" marker-end="url(#msw-a2)"/><text class="t2 mono" x="175" y="242" text-anchor="middle">⑤ respondWith()</text>
<line class="line dash" x1="270" y1="290" x2="615" y2="290" marker-end="url(#msw-a2)"/><text class="t2" x="285" y="282">没匹配上：原样发给服务器</text>
</svg>
<figcaption>Service Worker 只负责「截」和「回」，handler 实际运行在页面里</figcaption>
</figure>
<p>这样一来，handler 就是项目里的普通代码：能 import 共用的类型、工厂函数，甚至 store，能直接打断点，改完跟着热更新，不用操心 Service Worker 的缓存和更新周期。</p>
<p>请求是真的从页面发出去、被 Service Worker 接住的，所以 Network 面板里能看到它，Chrome 会在 Size 一栏标上 <code>(ServiceWorker)</code>。请求头、响应体、耗时都在，查问题时跟看真实请求没什么两样。</p>
<h2 id="上手" tabindex="-1">上手 <a class="header-anchor" href="#上手" aria-label="本节链接：上手">&ZeroWidthSpace;</a></h2>
<p>以 MSW 2.x 为例。先装上，再把 Worker 脚本生成到静态目录：</p>
<div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">pnpm</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> add</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> -D</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> msw</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">npx</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> msw</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> init</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D"> public/</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076"> --save</span></span></code></pre>
</div><p><code>--save</code> 会把目录记到 <code>package.json</code> 里，以后升级 MSW 时脚本会自动跟着更新。</p>
<p>然后写 handler。语法很像写一个迷你后端：</p>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// src/mocks/handlers.ts</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> http</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> delay</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">msw</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">export</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> const </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">handlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> [</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">  http</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">/api/user/:id</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> ({</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> params</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">    return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">json</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">      id</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">params</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">id</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">      name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">张三</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965">      role</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">admin</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    })</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  }),</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">  http</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">post</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">/api/login</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> async </span><span style="--shiki-light:#999999;--shiki-dark:#666666">({</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> request</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">    const </span><span style="--shiki-light:#999999;--shiki-dark:#666666">{</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> username</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> await</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> request</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">json</span><span style="--shiki-light:#999999;--shiki-dark:#666666">()</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">    await</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> delay</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91">800</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD"> // 模拟慢接口，顺便看看 loading 态</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">    if</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> (</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">username</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> !== </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">admin</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">      return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">json</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({ </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">message</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">用户名或密码错误</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> },</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> { </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">status</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91">401</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    }</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">    return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">json</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({ </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">token</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">fake-token</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  }),</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">]</span></span></code></pre>
</div><p><code>request</code> 就是标准的 Fetch API <code>Request</code> 对象，返回的也是标准 <code>Response</code>，<code>HttpResponse</code> 只是在它上面加了几个便捷方法。</p>
<p>浏览器端的入口：</p>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// src/mocks/browser.ts</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> setupWorker</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">msw/browser</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> handlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">./handlers</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">export</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> const </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">worker</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> setupWorker</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(...</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">handlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span></code></pre>
</div><p>在应用启动前开起来：</p>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// src/main.ts</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">async</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> function</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> enableMocking</span><span style="--shiki-light:#999999;--shiki-dark:#666666">()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  if</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> (</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">!</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">meta</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">env</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">DEV</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> return</span></span>
<span class="line"><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">  const </span><span style="--shiki-light:#999999;--shiki-dark:#666666">{</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> worker</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> await</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> import</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">./mocks/browser</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">  return</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> worker</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">start</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({ </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">onUnhandledRequest</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">bypass</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">enableMocking</span><span style="--shiki-light:#999999;--shiki-dark:#666666">().</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">then</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  createApp</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">App</span><span style="--shiki-light:#999999;--shiki-dark:#666666">).</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">mount</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">#app</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">})</span></span></code></pre>
</div><p>这里有两个细节。一是用动态 <code>import()</code>，生产构建会把 mock 相关代码整个摇掉，不会混进产物。二是一定要等 <code>worker.start()</code> 完成再挂载应用。Service Worker 注册是异步的，不等的话首屏那几个请求会漏过去，表现就是「刷新一下偶尔拿到真数据」，排查起来挺莫名其妙的。</p>
<h2 id="在-node-和测试里复用" tabindex="-1">在 Node 和测试里复用 <a class="header-anchor" href="#在-node-和测试里复用" aria-label="本节链接：在 Node 和测试里复用">&ZeroWidthSpace;</a></h2>
<p>这是 MSW 最让我舍不得的一点：上面那份 <code>handlers.ts</code>，测试里可以原封不动地拿来用。</p>
<figure class="msw-fig">
<svg viewBox="0 0 680 200" role="img" aria-label="同一份 handlers 分别交给浏览器端的 setupWorker 和 Node 端的 setupServer">
<defs><marker id="msw-a3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="head" d="M0 0L10 5L0 10z"/></marker></defs>
<rect class="box em" x="20" y="80" width="160" height="40" rx="8"/><text class="t mono" x="100" y="105" text-anchor="middle">handlers.ts</text>
<rect class="box" x="250" y="25" width="180" height="40" rx="8"/><text class="t mono" x="340" y="50" text-anchor="middle">setupWorker</text>
<rect class="box" x="250" y="135" width="180" height="40" rx="8"/><text class="t mono" x="340" y="160" text-anchor="middle">setupServer</text>
<path class="line" d="M180 100 C215 100 215 45 248 45" marker-end="url(#msw-a3)"/>
<path class="line" d="M180 100 C215 100 215 155 248 155" marker-end="url(#msw-a3)"/>
<text class="t2" x="450" y="42">浏览器：本地开发、Storybook、</text><text class="t2" x="450" y="60">Playwright / Cypress</text>
<text class="t2" x="450" y="152">Node：Vitest / Jest、</text><text class="t2" x="450" y="170">SSR、Node 脚本</text>
</svg>
<figcaption>一份 handler，两种运行环境</figcaption>
</figure>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// src/mocks/node.ts</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> setupServer</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">msw/node</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> handlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">./handlers</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">export</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> const </span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">server</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> setupServer</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(...</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">handlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666">)</span></span></code></pre>
</div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD">// vitest.setup.ts</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> beforeAll</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> afterEach</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> afterAll</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">vitest</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> server</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">./src/mocks/node</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">beforeAll</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> server</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">listen</span><span style="--shiki-light:#999999;--shiki-dark:#666666">({ </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">onUnhandledRequest</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">error</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }))</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">afterEach</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> server</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">resetHandlers</span><span style="--shiki-light:#999999;--shiki-dark:#666666">())</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">afterAll</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> server</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">close</span><span style="--shiki-light:#999999;--shiki-dark:#666666">())</span></span></code></pre>
</div><p>测试里 <code>onUnhandledRequest</code> 我习惯设成 <code>'error'</code>：任何没被 mock 的请求直接让测试挂掉，免得哪个用例悄悄打到了真实接口。</p>
<p>默认的 handler 写的是正常情况。要测异常分支，就在单个用例里用 <code>server.use()</code> 临时覆盖，<code>afterEach</code> 里的 <code>resetHandlers()</code> 会把它清掉，不影响别的用例：</p>
<div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code" tabindex="0" v-pre=""><code><span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> http</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">msw</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">import</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> server</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> }</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375"> from</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77"> '</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">../mocks/node</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">test</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">接口报错时显示重试按钮</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> async</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> ()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">  server</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">use</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A">    http</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">/api/user/:id</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> ()</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> =></span><span style="--shiki-light:#999999;--shiki-dark:#666666"> {</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">      return</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676"> new</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665"> HttpResponse</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676">null</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> { </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">status</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91">500</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">    }),</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">  )</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  render</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(&#x3C;</span><span style="--shiki-light:#2E8F82;--shiki-dark:#5DA994">UserCard</span><span style="--shiki-light:#2E8F82;--shiki-dark:#5DA994"> id</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE">=</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">1</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">"</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE"> /</span><span style="--shiki-light:#999999;--shiki-dark:#666666">>)</span></span>
<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665">  expect</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375">await</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A"> screen</span><span style="--shiki-light:#999999;--shiki-dark:#666666">.</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">findByRole</span><span style="--shiki-light:#999999;--shiki-dark:#666666">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">button</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> { </span><span style="--shiki-light:#998418;--shiki-dark:#B8A965">name</span><span style="--shiki-light:#999999;--shiki-dark:#666666">: </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D">重试</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77">'</span><span style="--shiki-light:#999999;--shiki-dark:#666666"> })).</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665">toBeInTheDocument</span><span style="--shiki-light:#999999;--shiki-dark:#666666">()</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666">})</span></span></code></pre>
</div><p>这个测试里没有一行在 mock axios 或者 fetch，它只描述了「接口返回 500 时界面该长什么样」。组件内部用什么库发请求、有没有拦截器，都可以随便改，以后重构请求层，这些测试一行都不用动。</p>
<h2 id="对比一下" tabindex="-1">对比一下 <a class="header-anchor" href="#对比一下" aria-label="本节链接：对比一下">&ZeroWidthSpace;</a></h2>
<table tabindex="0">
<thead>
<tr>
<th></th>
<th>写死 / 改代码</th>
<th>替换请求库</th>
<th>Mock.js</th>
<th>本地 mock server</th>
<th>MSW</th>
</tr>
</thead>
<tbody>
<tr>
<td>侵入业务代码</td>
<td>是</td>
<td>测试代码里要 mock 模块</td>
<td>否</td>
<td>否（要改代理配置）</td>
<td>否</td>
</tr>
<tr>
<td>Network 面板可见</td>
<td>否</td>
<td>否</td>
<td>否</td>
<td>是</td>
<td>是</td>
</tr>
<tr>
<td>支持 fetch</td>
<td>看实现</td>
<td>看库</td>
<td>否</td>
<td>是</td>
<td>是</td>
</tr>
<tr>
<td>开发和测试共用</td>
<td>否</td>
<td>否</td>
<td>勉强</td>
<td>很难</td>
<td>是</td>
</tr>
<tr>
<td>额外进程</td>
<td>无</td>
<td>无</td>
<td>无</td>
<td>要起服务</td>
<td>无</td>
</tr>
<tr>
<td>换请求库后还能用</td>
<td>否</td>
<td>否</td>
<td>只要还是 XHR</td>
<td>是</td>
<td>是</td>
</tr>
<tr>
<td>团队其他人 / 其他端能用</td>
<td>否</td>
<td>否</td>
<td>否</td>
<td>是</td>
<td>否</td>
</tr>
</tbody>
</table>
<p>最后一行是 MSW 比不过 mock server 的地方，下面会说到。</p>
<h2 id="msw-的不足" tabindex="-1">MSW 的不足 <a class="header-anchor" href="#msw-的不足" aria-label="本节链接：MSW 的不足">&ZeroWidthSpace;</a></h2>
<p>用了两年多，踩过的坑和它天生做不到的事，大概有这些：</p>
<p>最大的限制是它只服务当前这个前端应用。MSW 的 mock 只存在于你这个页面（或这个 Node 进程）里。移动端同事、另一个前端项目、用 Postman 调接口的测试同学，都看不到这份 mock。如果你需要的是「整个团队共享一套假接口」，mock server 或者 mock 平台更合适。</p>
<p>Service Worker 本身也有环境限制，只能在 HTTPS 或 <code>localhost</code> 下注册。用局域网 IP 在手机上打开开发环境，Service Worker 会注册失败，MSW 也就不起作用了。另外浏览器里 <code>Shift + 刷新</code> 会跳过 Service Worker，有时候同事说「mock 怎么不生效了」，其实就是这个原因。</p>
<p><code>mockServiceWorker.js</code> 要跟库版本保持一致。这个文件是提交在仓库里的，升级 MSW 后如果没更新它，控制台会给出版本不匹配的警告，严重时直接拦不住请求。前面 <code>init</code> 时加 <code>--save</code> 就是为了让它自动跟着更新。</p>
<p>handler 和真实接口会慢慢走样。这个问题所有 mock 方案都有，MSW 也没解决。后端改了字段，handler 不会自己知道。我的做法是让 handler 的返回值套上从 OpenAPI 生成的类型，至少字段对不上时 TypeScript 会报错。社区里也有直接从 OpenAPI 文档生成 handler 的工具，接口多的话可以考虑。</p>
<p>SSR 项目要配两套。像 Nuxt、Next.js 这种，服务端渲染时发的请求在 Node 里，水合后发的请求在浏览器里，两边得分别启动 <code>setupServer</code> 和 <code>setupWorker</code>。handler 能共用，但启动时机要各自处理，第一次配的时候会有点绕。</p>
<p>最后，团队里没接触过 Service Worker 的同学，遇到问题时不太知道从哪查。不过 MSW 的报错信息写得很好，大部分情况下控制台会直接告诉你哪个请求没被处理、该怎么写 handler。</p>
<h2 id="怎么选" tabindex="-1">怎么选 <a class="header-anchor" href="#怎么选" aria-label="本节链接：怎么选">&ZeroWidthSpace;</a></h2>
<p>我自己的判断标准比较简单：</p>
<ul>
<li>只是给当前前端项目开发和写测试用，直接上 MSW，我还没找到更好的选择。</li>
<li>需要给多个端、多个团队提供统一的假接口，就用 mock 平台或 mock server。前端项目里可以再叠一层 MSW 处理测试和边界场景，两者不冲突。</li>
<li>老项目全是 XHR，Mock.js 用得好好的，没必要为了换而换，等哪天要写测试了再迁也不迟。</li>
</ul>
]]></content:encoded>
</item>
<item>
<title>Nginx 中的正向代理与反向代理</title>
<link>https://nyann.cc/posts/nginx%20%E4%B8%AD%E7%9A%84%E6%AD%A3%E5%90%91%E4%BB%A3%E7%90%86%E4%B8%8E%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86</link>
<guid isPermaLink="true">https://nyann.cc/posts/nginx%20%E4%B8%AD%E7%9A%84%E6%AD%A3%E5%90%91%E4%BB%A3%E7%90%86%E4%B8%8E%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86</guid>
<pubDate>Thu, 08 Jan 2026 00:00:00 GMT</pubDate>
<description>正向代理与反向代理的理解</description>
<category>Nginx</category>
<content:encoded><![CDATA[<h1 id="nginx-正向代理与反向代理" tabindex="-1">nginx 正向代理与反向代理 <a class="header-anchor" href="#nginx-正向代理与反向代理" aria-label="本节链接：nginx 正向代理与反向代理">&ZeroWidthSpace;</a></h1>
<h2 id="正向代理" tabindex="-1"><strong>正向代理</strong> <a class="header-anchor" href="#正向代理" aria-label="本节链接：正向代理">&ZeroWidthSpace;</a></h2>
<p>正向代理（forward proxy）：是一个位于客户端和目标服务器之间的服务器(代理服务器)，为了从目标服务器取得内容，客户端向代理服务器发送一个请求并指定目标，然后代理服务器向目标服务器转交请求并将获得的内容返回给客户端。</p>
<p>这种代理其实在生活中是比较常见的，比如访问外国网站技术，其用到的就是代理技术。</p>
<p>有时候，用户想要访问某国外网站，该网站无法在国内直接访问，但是我们可以访问到一个代理服务器，这个代理服务器可以访问到这个国外网站。这样呢，用户对该国外网站的访问就需要通过代理服务器来转发请求，并且该代理服务器也会将请求的响应再返回给用户。这个上网的过程就是用到了正向代理。</p>
<p>这个过程其实和租房子很像。</p>
<p>租房子的时候，一般情况下，我们很难联系到房东，因为有些房东为了图方便，只把自己的房屋信息和钥匙交给中介了。而房客想要租房子，只能通过中介才能联系到房东。而对于房东来说，他可能根本不知道真正要租他的房子的人是谁，他只知道是中介在联系他。</p>
<p>这里面一共有三个角色，租客（用户）、中介（代理服务器）和房东（国外网站，目标服务器）。引入中介（代理服务器）的原因是用户无法联系上房东（用户无法访问国外网站）。</p>
<p><strong>所以，正向代理，其实是&quot;代理服务器&quot;代理了&quot;客户端&quot;，去和&quot;目标服务器&quot;进行交互。</strong></p>
<p>通过正向代理服务器访问目标服务器，目标服务器是不知道真正的客户端是谁的，甚至不知道访问自己的是一个代理（有时候中介也直接冒充租客）。</p>
<p>下面这个演示，请求是导轨上的一辆滑车，墙上的闸门只看目的地址。点「直连请求」，滑车到闸门前就被拦下。点「经代理请求」，代理会替你把请求送到服务器，再把响应带回来；再点一次，代理直接从缓存里拿，不用再跑服务器。</p>
<ProxyForward /><h3 id="正向代理的用途" tabindex="-1"><strong>正向代理的用途</strong> <a class="header-anchor" href="#正向代理的用途" aria-label="本节链接：正向代理的用途">&ZeroWidthSpace;</a></h3>
<p><strong>突破访问限制</strong></p>
<p>通过代理服务器，可以突破自身 IP 访问限制，访问国外网站，教育网等。</p>
<p>即，租客可以通过中介，来解决无法联系上房东的问题。</p>
<p><strong>提高访问速度</strong></p>
<p>通常代理服务器都设置一个较大的硬盘缓冲区，会将部分请求的响应保存到缓冲区中，当其他用户再访问相同的信息时， 则直接由缓冲区中取出信息，传给用户，以提高访问速度。</p>
<p>即，中介手里留存了很多房源信息和钥匙，可以直接带租客去看房。</p>
<p><strong>隐藏客户端真实 IP</strong></p>
<p>上网者也可以通过这种方法隐藏自己的 IP，免受攻击。</p>
<p>即，房东并不知道租客的真实身份。PS：但是中介知道了，可能骚扰更多….</p>
<h2 id="反向代理" tabindex="-1"><strong>反向代理</strong> <a class="header-anchor" href="#反向代理" aria-label="本节链接：反向代理">&ZeroWidthSpace;</a></h2>
<p>反向代理（reverse proxy）：是指以代理服务器来接受 internet 上的连接请求，然后将请求转发给内部网络上的服务器，并将从服务器上得到的结果返回给 internet 上请求连接的客户端，此时代理服务器对外就表现为一个反向代理服务器。</p>
<p>我们在租房子的过程中，除了有些房源需要通过中介以外，还有一些是可以直接通过房东来租的。用户直接找到房东租房的这种情况就是我们不使用代理直接访问国内的网站的情况。</p>
<p>还有一种情况，就是我们以为我们接触的是房东，其实有时候也有可能并非房主本人，有可能是他的亲戚、朋友，甚至是二房东。但是我们并不知道和我们沟通的并不是真正的房东。这种帮助真正的房主租房的二房东其实就是反向代理服务器。这个过程就是反向代理。</p>
<p>对于常用的场景，就是我们在 Web 开发中用到的<a href="https://cloud.tencent.com/product/clb?from=10680" target="_blank" rel="noreferrer">负载均衡</a>服务器（二房东），客户端（租客）发送请求到负载均衡服务器（二房东）上，负载均衡服务器（二房东）再把请求转发给一台真正的服务器（房东）来执行，再把执行结果返回给客户端（租客）。￼</p>
<p><strong>所以，反向代理，其实是&quot;代理服务器&quot;代理了&quot;目标服务器&quot;，去和&quot;客户端&quot;进行交互。</strong></p>
<p>通过反向代理服务器访问目标服务器时，客户端是不知道真正的目标服务器是谁的，甚至不知道自己访问的是一个代理。</p>
<p>反向代理用的还是这个演示，只是 nginx 挪到了内网门口，三台后端在墙后面。换一种负载均衡算法，或者把 2 号标成 down，再发几个请求，看它们各落到哪台后端。</p>
<ProxyReverse /><h3 id="反向代理的用途" tabindex="-1"><strong>反向代理的用途</strong> <a class="header-anchor" href="#反向代理的用途" aria-label="本节链接：反向代理的用途">&ZeroWidthSpace;</a></h3>
<p><strong>隐藏服务器真实 IP</strong></p>
<p>使用反向代理，可以对客户端隐藏服务器的 IP 地址。</p>
<p>即，租客并不房东知道的真实身份。</p>
<p><strong>负载均衡</strong></p>
<p>反向代理服务器可以做负载均衡，根据所有真实服务器的负载情况，将客户端请求分发到不同的真实服务器上。</p>
<p>即，二房东发现房主本人很忙，于是找到房主的妻子帮忙处理租房事宜。</p>
<p><strong>提高访问速度</strong></p>
<p>反向代理服务器可以对于静态内容及短时间内有大量访问请求的动态内容提供缓存服务，提高访问速度。</p>
<p>即，二房东同样有房屋信息和钥匙。</p>
<p><strong>提供安全保障</strong></p>
<p>反向代理服务器可以作为应用层防火墙，为网站提供对基于 Web 的攻击行为（例如 DoS/DDoS）的防护，更容易排查恶意软件等。还可以为后端服务器统一提供加密和 SSL 加速（如 SSL 终端代理），提供 HTTP 访问认证等。</p>
<p>即，二房东可以有效的保护房东的安全。</p>
<h3 id="正向代理和反向代理的区别" tabindex="-1"><strong>正向代理和反向代理的区别</strong> <a class="header-anchor" href="#正向代理和反向代理的区别" aria-label="本节链接：正向代理和反向代理的区别">&ZeroWidthSpace;</a></h3>
<p>虽然正向代理服务器和反向代理服务器所处的位置都是客户端和真实服务器之间，所做的事情也都是把客户端的请求转发给服务器，再把服务器的响应转发给客户端，但是二者之间还是有一定的差异的。</p>
<p>1、<strong>正向代理其实是客户端的代理</strong> ，帮助客户端访问其无法访问的服务器资源。<strong>反向代理则是服务器的代理</strong> ，帮助服务器做负载均衡，安全防护等。</p>
<p>2、<strong>正向代理一般是客户端架设的</strong> ，比如在自己的机器上安装一个代理软件。而<strong>反向代理一般是服务器架设的</strong> ，比如在自己的机器集群中部署一个反向代理服务器。</p>
<p>3、<strong>正向代理中，服务器不知道真正的客户端到底是谁</strong> ，以为访问自己的就是真实的客户端。而在<strong>反向代理中，客户端不知道真正的服务器是谁</strong> ，以为自己访问的就是真实的服务器。</p>
<p>4、正向代理和反向代理的作用和目的不同。<strong>正向代理主要是用来解决访问限制问题。而反向代理则是提供负载均衡、安全防护等作用。二者均能提高访问速度。</strong></p>
]]></content:encoded>
</item>
</channel>
</rss>
