Jekyll 2026-07-28T09:33:29+00:00 https://jinzi.cyou/feed-notes.xml 只含手写研究笔记（不含每日 AI 晨报）。全量流见 /feed.xml。 Marginalia 2026-07-25T04:00:00+00:00 2026-07-25T04:00:00+00:00 https://jinzi.cyou/posts/model-arena <blockquote> <p>开源了一个小工具 Model Arena：受限工具集 + 18 题四档题库 + 自动判分 + Web UI。跑完 17 个模型之后，最有价值的结论不是排名，而是几件容易归错因的事——同一个模型换条路走分数能差一倍、「畸形工具调用」看着像模型不行其实不是，以及最要命的那个：<strong>我的评测沙箱漏了，它在按搜索风格而不是能力打分</strong>。</p> </blockquote> <h2 id="起因">起因</h2> <p>我有个自建的制片 dashboard，里面有个自主 agent。它不走 Claude，而是经本地网关路由到 deepseek / gemini / kimi / minimax / hy3 / grok 一堆第三方后端。</p> <p>这类 agent 的成败几乎不取决于模型「聪不聪明」，而取决于一件更朴素的事：<strong>它能不能把工具调对</strong>。参数漏一个必填字段、把该 Grep 的活儿拿去 Read、撞满轮次交白卷——这些失败跟基准测试里的推理分数关系不大。</p> <p>于是我把「构造测试题 → 批量跑 → 判分 → 排名」固化成了一个可复现的程序，现在开源出来：</p> <p><strong><a href="https://github.com/pyf-labrary/model-arena">github.com/pyf-labrary/model-arena</a></strong></p> <h2 id="它测什么">它测什么</h2> <p>模拟生产 agent 的<strong>受限工具集</strong>：只放行 <code class="language-plaintext highlighter-rouge">Read / Grep / Glob</code> 加一个白名单 MCP 工具，用 <code class="language-plaintext highlighter-rouge">disallowed_tools</code> 拉黑 <code class="language-plaintext highlighter-rouge">Bash / Write / Task / WebSearch</code>。经 <code class="language-plaintext highlighter-rouge">claude-agent-sdk</code> 起子进程 agent，模型经 <code class="language-plaintext highlighter-rouge">ANTHROPIC_BASE_URL</code> 指向网关。</p> <p>题库 18 题、四个难度档，跑在一个自包含的样例工作区上。关键设计是<strong>标准答案由生成器从数据结构实算、再回磁盘对账</strong>——不一致直接报错退出，所以判分可以全自动。</p> <p>工作区里处处埋雷，每个雷对应一类真实的 agent 失败模式：</p> <ul> <li>大小写变体的文件名（<code class="language-plaintext highlighter-rouge">component.md</code> 混在 <code class="language-plaintext highlighter-rouge">COMPONENT.md</code> 里）→ 考口径漂移</li> <li>更长的近似标记（<code class="language-plaintext highlighter-rouge">ZETA9X</code> 混在 <code class="language-plaintext highlighter-rouge">ZETA9</code> 里）→ 考整词边界</li> <li><code class="language-plaintext highlighter-rouge">.bak</code> 备份、草稿目录、归档区的假模块 → 考盲目全仓 grep</li> <li>一个工具故意返回<strong>过期缓存值</strong>（报 14，磁盘真值 12）→ 一道题考「有没有真读返回值」，另一道题禁用该工具考「敢不敢不信它」</li> </ul> <p>难度分层符合预期：T1 基线四题人人满分，区分度落在 T2 工具保真和 T4 杀手级。</p> <p><img src="/assets/img/posts/2026-07-25-model-arena/questions.jpg" alt="配置页：18 道题以卡片列出，每张标注难度档、期望工具族、埋雷说明与标准答案" /></p> <h2 id="结果满分梯队">结果：满分梯队</h2> <p>17 个模型、每个 18 题。<strong>先说不确定性</strong>：我用同一套 harness 把全部模型重复跑了两轮，两轮之间平均差 <strong>1.0 分</strong>（最大 3 分，只有 5/19 个完全不变）。所以下面这张表<strong>只能分档看，名次没有意义</strong>——17 和 18 之间的差别完全落在噪声里。</p> <p>满分档（18/18，按耗时排）：</p> <table> <thead> <tr> <th>模型</th> <th>通过</th> <th>无瑕</th> <th>均耗时</th> <th>out token</th> </tr> </thead> <tbody> <tr> <td>grok-composer-2.5-fast</td> <td>18/18</td> <td>18/18</td> <td>10.0s</td> <td>6938</td> </tr> <tr> <td>deepseek-v4-flash-free</td> <td>18/18</td> <td>18/18</td> <td>14.1s</td> <td>15828</td> </tr> <tr> <td>hy3-preview</td> <td>18/18</td> <td>18/18</td> <td>18.9s</td> <td>12931</td> </tr> <tr> <td>claude-opus-5</td> <td>18/18</td> <td>18/18</td> <td>20.1s</td> <td>14488</td> </tr> <tr> <td>kimi-k2.7-code</td> <td>18/18</td> <td>18/18</td> <td>22.5s</td> <td>10466</td> </tr> <tr> <td>gpt-5.6-luna</td> <td>18/18</td> <td>18/18</td> <td>30.4s</td> <td>8208</td> </tr> </tbody> </table> <p>17/18 档：<code class="language-plaintext highlighter-rouge">grok-4.5</code>(12.3s) · <code class="language-plaintext highlighter-rouge">grok-4.3</code>(14.4s) · <code class="language-plaintext highlighter-rouge">gpt-5.6-terra</code>(23.3s，<strong>4840 tok 最省</strong>) · <code class="language-plaintext highlighter-rouge">gemini-pro-agent</code>(28.3s) · <code class="language-plaintext highlighter-rouge">claude-sonnet-5</code>(34.4s) · <code class="language-plaintext highlighter-rouge">gpt-5.4-mini</code>(39.7s)。 15–16 档：<code class="language-plaintext highlighter-rouge">deepseek-v4-pro</code> 16 · <code class="language-plaintext highlighter-rouge">minimax-m3-pay</code> / <code class="language-plaintext highlighter-rouge">gemini-3.6-flash</code> / <code class="language-plaintext highlighter-rouge">kimi-k2.6</code> / <code class="language-plaintext highlighter-rouge">gemini-3.1-pro-low</code> 各 15。</p> <p>比通过数更能拉开差距的是<strong>畸形调用</strong>那一列：Gemini 三个变体分别 20/106、7/98、28/130，其余 14 个模型<strong>全为 0</strong>。<code class="language-plaintext highlighter-rouge">gemini-3.1-pro-low</code> 答对 15 题，但只有 12 题算「干净通过」。</p> <p><img src="/assets/img/posts/2026-07-25-model-arena/rank.jpg" alt="排名页：通过 / 无瑕通过 / 答对三列并排，附畸形率、越权次数、平均耗时与 out token" /></p> <p>另外 <code class="language-plaintext highlighter-rouge">minimax-m3-pay</code> 有个别人没有的毛病：<strong>越权调用被拉黑的 <code class="language-plaintext highlighter-rouge">Bash</code> 共 13 次</strong>（SDK 会拒绝执行，但这是个明确的失败信号，我后来给它加了单独的计数指标）。</p> <h2 id="发现一通道--模型">发现一：通道 &gt; 模型</h2> <p>榜上最低的是 <code class="language-plaintext highlighter-rouge">kimi-k2.7</code>，11/18。但同一个模型换条路进来，叫 <code class="language-plaintext highlighter-rouge">kimi-k2.7-code</code>，拿了 <strong>18/18</strong>。</p> <p>差别在哪？前者是经订阅转发的通道，后者是厂商官方 OAuth 直连。转发层的症状长这样：</p> <ul> <li>「找不到 registry 目录」</li> <li>「Read 的 file_path 与 cwd 不一致」</li> <li>卡满 150 秒，空答</li> </ul> <p><strong>这三个症状，每一个都长得像「这模型不行」。</strong> 如果不做通道对照，我就会得出「kimi 工具调用能力差」的结论，然后把它从选型里划掉——而真相是这个模型在满分档。7 分的差距远超前面量的 1.0 分噪声，这个结论站得住。</p> <p>但<strong>同样的对照在 deepseek 上不成立</strong>：转发版 16/18、官方直连版 18/18，差 2 分——落在噪声范围内，不能声称有差异。我最早那版文章里写过「转发无质量损耗、但有速度与 token 代价」，那是基于一批后来被推翻的数据（见文末后记），<strong>现在这个方向性结论我撤回</strong>。</p> <p>所以准确的说法是：<strong>转发层可能引入严重故障（kimi 是实锤），但不是必然（deepseek 上看不出来）。</strong> 结论仍然是那句：<strong>做模型评测必须把「通道」当成自变量</strong>——否则你测的是通道，报出来的却是模型。</p> <p>（顺带：这两个对照组我之后不再跑了——对照价值已经取到，继续测只是重复烧 token。所以上面这组数字是历史快照，日期 2026-07-25。）</p> <h2 id="发现二畸形调用的归因要靠换执行器做单变量对照">发现二：畸形调用的归因，要靠换执行器做单变量对照</h2> <p>全场 17 个模型里，「畸形工具调用」（<code class="language-plaintext highlighter-rouge">Grep</code>/<code class="language-plaintext highlighter-rouge">Glob</code> 丢了必填的 <code class="language-plaintext highlighter-rouge">pattern</code> 字段）一共出现 55 次——<strong>全部来自 Gemini 的三个变体</strong>（20 / 7 / 28），其余 14 个模型合计<strong>零次</strong>。这个分布在两轮独立重跑里都稳定复现，不是噪声。</p> <p>看起来结论很清楚：Gemini 不适应 Claude 形状的工具 schema。</p> <p>我差点就这么写了。但这里有个第二解释没排除：所有非 Anthropic 模型都要经过协议翻译，会不会是<strong>翻译层</strong>把 <code class="language-plaintext highlighter-rouge">pattern</code> 弄丢了，而不是模型没发？</p> <p>判别方法很朴素——<strong>同一道题、同一个模型，只换上游执行器</strong>：</p> <table> <thead> <tr> <th>路径</th> <th>畸形调用</th> </tr> </thead> <tbody> <tr> <td>订阅通道（Gemini 原生协议）</td> <td>2/20</td> </tr> <tr> <td>API key 通道（同为 Gemini 原生协议，另一个 executor）</td> <td><strong>0/20</strong></td> </tr> </tbody> </table> <p>畸形归零了。所以<strong>不是模型能力问题</strong>。</p> <p>但故事没完。我又做了配对补测——另外 3 道题、两条路各跑一遍——<strong>两边都是零畸形</strong>。也就是说它是<strong>间歇性</strong>的，6 次配对一次都没复现。</p> <p>所以诚实的结论只能到这里：<strong>不是模型的锅，但也没有足够证据说这是某条通道的确定性缺陷。</strong> 样本量不支持我给出一个发生率。我很想把它写成一句干净的「就是 XX 的问题」，但那会是编的。</p> <p>点通过矩阵里任意一格，能看到那一题的完整工具调用序列。下面这张里，红框标出的两次就是缺 <code class="language-plaintext highlighter-rouge">pattern</code> 的畸形调用——而它们旁边还有十几次形状完全正常的 <code class="language-plaintext highlighter-rouge">Grep</code>。这也是为什么我后来把「畸形」单独成列，而不是折叠进通过率：</p> <p><img src="/assets/img/posts/2026-07-25-model-arena/detail.jpg" alt="单题详情弹窗：完整工具调用序列，两次缺 pattern 的 Grep 被红框标注「缺参数」，同时显示撞满 20 轮的报错" /></p> <p>（另外还有个反直觉的细节：那道让 Gemini 反复出错的题，<strong>换了干净通道之后照样撞满轮次交白卷</strong>。所以这道题的失分不能全算到通道头上——它对这个模型本来就是难题。归因的时候很容易一激动把所有失分都归给刚发现的那个原因。）</p> <h2 id="一个被证伪的优化想法">一个被证伪的优化想法</h2> <p>既然怀疑 Anthropic→Gemini 的协议翻译有问题，那 Gemini 不是有 OpenAI 兼容端点吗？绕开这层翻译走成熟的 Anthropic→OpenAI 路径不就行了？</p> <p>我真去接了一条对照路由。结果<strong>第一次工具调用后立刻 400</strong>：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Function call is missing a thought_signature in function... </code></pre></div></div> <p>Gemini 的 OpenAI 兼容端点在多轮 function calling 上要求把 <code class="language-plaintext highlighter-rouge">thought_signature</code> 原样回传，而 OpenAI 协议里根本没有这个字段的位置。这条链是断的——<strong>换协议不但不能提效，是直接不可用</strong>。</p> <p>好在这类想法验证起来很便宜：加一条路由、跑一道题、看报错。比想很久要快。</p> <h2 id="顺便修了判分器">顺便修了判分器</h2> <p>原本的判分规则要求「零畸形」才算通过。这导致「答案其实对了、只是某次调用形状有瑕疵」和「答错了」在榜上长得一模一样——<strong>恰恰把我最想区分的两种失败压成了同一档</strong>。</p> <p>改成并列：<code class="language-plaintext highlighter-rouge">pass</code> 只管<strong>能不能把活干对</strong>，另设 <code class="language-plaintext highlighter-rouge">clean</code> 管<strong>干不干净</strong>，榜上「通过 / 无瑕通过 / 答对」三列并排。综合分照旧扣畸形率（并列不等于免罚）。改完用 <code class="language-plaintext highlighter-rouge">--rescore</code> 重判历史数据——原始回答和工具调用序列都存着，不用重烧一遍 token，而且<strong>重判产物写新文件，绝不覆盖原件</strong>（原始判定是证据）。</p> <p>重判之后，两个 Gemini 变体各自涨了 1 分和 2 分。</p> <h2 id="后记这张榜差点是错的">后记：这张榜差点是错的</h2> <p>上面那些数字，是<strong>推倒重来过两轮</strong>的。</p> <p>起因是一句质疑。我把新加进来的两个模型（Claude 的 Opus 5 / Sonnet 5，走本机订阅而非网关）跑完，报出 16/18 和 15/18，位置在中游。用户看了一眼说：这是当前最强的模型，跑分不该落后。</p> <p>我当时手边有两句现成的解释——「n=1 有噪声」和「这题库测的是工具调用不是智力」。两句都成立。但它们都是<strong>在看证据之前就准备好的话</strong>。所以我去复跑了它失分的那道题，把工具调用和返回全打出来：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Grep {"pattern":"\\bOMEGA7\\b", "path":"/home/user", "output_mode":"files_with_matches"} → Found 3 files ……/工作日志/model-arena题库v2.md ……/模型横评v2-资料/questions.json ← 题库本身 ……/模型横评v2-资料/gen_workspace.py → 答 3 </code></pre></div></div> <p>题目问「整个工作区里有多少个文件包含整词 <code class="language-plaintext highlighter-rouge">OMEGA7</code>」，标准答案 0（工作区里只有更长的 <code class="language-plaintext highlighter-rouge">OMEGA71</code>）。而它搜到的三个文件，是<strong>这套题库自己的设计文档</strong>——其中 <code class="language-plaintext highlighter-rouge">questions.json</code> 里躺着全部标准答案。</p> <p>它答 3，对它实际看到的东西而言完全正确。</p> <h3 id="缺陷一cwd-不是沙箱">缺陷一：<code class="language-plaintext highlighter-rouge">cwd</code> 不是沙箱</h3> <p>我一直以为给 agent 设了 <code class="language-plaintext highlighter-rouge">cwd=WORKSPACE</code> 就等于把它关在工作区里。不是——<strong>那只是起始目录</strong>。<code class="language-plaintext highlighter-rouge">Read</code>/<code class="language-plaintext highlighter-rouge">Grep</code>/<code class="language-plaintext highlighter-rouge">Glob</code> 的 <code class="language-plaintext highlighter-rouge">path</code> 参数照样能指向机器上任何位置。另一个模型更干脆，<code class="language-plaintext highlighter-rouge">path</code> 直接填 <code class="language-plaintext highlighter-rouge">/</code>。</p> <p>危害有两层。<strong>答案泄漏</strong>是显眼的那层。更隐蔽的是第二层：<strong>这个缺陷是有方向性的</strong>。老老实实用相对路径在工作区里干活的模型毫发无伤；用绝对路径做彻底检索的模型撞雷。于是榜单实际上在按<strong>搜索风格</strong>打分，而不是按能力——而「更彻底地检索」恰恰是我希望 agent 具备的品质。</p> <p>修法是加一道路径闸：<code class="language-plaintext highlighter-rouge">can_use_tool</code> 里把 <code class="language-plaintext highlighter-rouge">path</code>/<code class="language-plaintext highlighter-rouge">file_path</code> resolve 后检查是否在工作区内，不在就拒绝。</p> <h3 id="缺陷二装了闸闸没响">缺陷二：装了闸，闸没响</h3> <p>改完跑一遍，越界计数 <strong>0</strong>，而模型照样搜出了工作区外的文件。</p> <p>原因是 <code class="language-plaintext highlighter-rouge">allowed_tools</code>。我一直把它理解成「可见工具白名单」，它实际上是<strong>自动批准名单</strong>——名单里的工具<strong>直接绕过</strong> <code class="language-plaintext highlighter-rouge">can_use_tool</code>。我把 <code class="language-plaintext highlighter-rouge">Read</code>/<code class="language-plaintext highlighter-rouge">Grep</code>/<code class="language-plaintext highlighter-rouge">Glob</code> 留在里面，于是权限回调一次都没被调用过。SDK 其实打了个 <code class="language-plaintext highlighter-rouge">_warn_if_can_use_tool_shadowed</code> 警告，混在输出里，我第一遍没当回事。</p> <p>（工具的<strong>可见性</strong>由 <code class="language-plaintext highlighter-rouge">disallowed_tools</code> 决定，与 <code class="language-plaintext highlighter-rouge">allowed_tools</code> 无关。把只读工具移出自动批准名单不影响模型使用它们，只是每次调用要过闸。）</p> <h3 id="缺陷三闸响了但响错了">缺陷三：闸响了，但响错了</h3> <p>第二版闸生效，然后分数<strong>掉</strong>了：一个模型从 18 掉到 16，另一个掉到 14。</p> <p>我差点又要去解释「沙箱变严了所以更难」。真实原因是我的回调返回了 dict，而 SDK 要求返回 <code class="language-plaintext highlighter-rouge">PermissionResult</code> 对象。回调直接抛异常 → <strong>MCP 工具全线挂掉</strong> → 模型在那几道题里回答「工具调用失败，无法给出数字」。</p> <p>看着像模型变笨了，其实是 harness 在自残。</p> <h3 id="缺陷四拒绝语本身是一种提示">缺陷四：拒绝语本身是一种提示</h3> <p>闸终于对了。但翻越界记录时我发现，拦下的 296 次里只有 18 次是真往外搜（<code class="language-plaintext highlighter-rouge">path=/</code> 那种），其余全是模型在<strong>猜工作区的绝对路径</strong>——猜错了而已。</p> <p>这类调用在原环境里只会得到一句「文件不存在」，模型自己改用相对路径。而我的拒绝语写的是「越界，请只用相对路径检索」——<strong>比自然的 ENOENT 多给了一条指导</strong>。等于我在修 bug 的同时给所有模型塞了新帮助，那么修复前后的分数变化，究竟是「污染被堵住」还是「提示帮了忙」，就分不清了。</p> <p>改成中性的「路径不存在或不可访问」（语义与 chroot 一致：外面的东西就是不存在），<strong>再全部重跑一遍</strong>。</p> <h3 id="值多少">值多少</h3> <p>四个缺陷，每一个单独出现都足以把排名弄反，而它们的表现全都是「某个模型分低」——一个我早就准备好用「模型能力」去解释的现象。</p> <p>代价是两轮全量重跑。收获是这条判据：</p> <blockquote> <p><strong>当结果与强先验冲突时，先查 harness，再查被测对象。</strong></p> </blockquote> <p>「最强的模型不该落后」是个强先验。我本可以用「n=1 噪声」把它打发过去——那句话甚至是对的，前面量到的噪声就有 ±1 分。<strong>但用一个成立的通用解释去覆盖一个具体的异常，是归因里最容易犯的懒。</strong></p> <p>还有个附带收获：修完之后我才有条件去量噪声——<strong>同一 harness 跑两轮，平均差 1.0 分</strong>。这个数字反过来说明，我原先那张榜上「第 1 名和第 5 名」的排序，本来就没有意义。<strong>先修偏差，再量方差，然后才谈名次。</strong></p> <p>最后一句实践建议：这次能查下去，全靠每道题的原始回答和完整工具调用序列都存在结果文件里。如果当初只存了分数，这四个缺陷一个都查不出来——重跑只会得到同样可疑的数字，而没有任何线索。<strong>评测系统存原始过程，比存结论重要。</strong></p> <h2 id="拿去跑">拿去跑</h2> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone https://github.com/pyf-labrary/model-arena.git <span class="o">&amp;&amp;</span> <span class="nb">cd </span>model-arena pip <span class="nb">install </span>claude-agent-sdk <span class="nb">cp </span>config.example.json config.json <span class="c"># 填网关地址和 token</span> python3 server.py <span class="nt">--port</span> 8799 </code></pre></div></div> <p>不限某一种网关——任何暴露 Anthropic Messages 协议 <code class="language-plaintext highlighter-rouge">/v1/messages</code> 的网关都能接。</p> <p>仓库里带了 17 模型评测的<strong>全部原始数据</strong>（含修沙箱前后的各轮，可对比），每道题保留了模型的原始回答和完整工具调用序列，可以自己 <code class="language-plaintext highlighter-rouge">--rescore</code> 用别的判据复判，不用重跑。</p> <h2 id="最后">最后</h2> <p>这事让我改了一个习惯：以前跑完评测，写完报告就算交付了。但那次收尾时我顺手对了一下账——<strong>把榜单和实际生效的配置逐行比一遍</strong>——发现 5 个满分模型在我自己的 dashboard 里全都是关着的，用户根本选不到；而榜末那两个反倒开着。</p> <p>评测跑完了、报告写完了、结论也记下来了，<strong>兑现率却是 0</strong>。</p> <p>所以最有价值的一步往往不在报告里，而在「榜与现状的差集」里。</p>

开源了一个 agent 工具调用测评场，17 模型实测。附一次翻车复盘：评测沙箱漏了会按搜索风格而非能力打分，四个 harness 缺陷差点把排名判反。

2026-06-11T04:00:00+00:00 2026-06-11T04:00:00+00:00 https://jinzi.cyou/posts/fable5-viral-demos-and-techniques <figure> <video controls="" muted="" loop="" playsinline="" preload="metadata" style="width:100%;border-radius:3px" poster="/assets/img/posts/2026-06-11-fable5/cover.jpg"> <source src="https://game.panyifeng.xyz/media/posts/2026-06-11-fable5/forest.mp4" type="video/mp4" /> </video> <figcaption>Fable 5 单 prompt 生成的 photoreal three.js 森林，浏览器实时渲染（<a href="https://x.com/mattshumer_/status/2064449498596757643">Matt Shumer 原帖</a>视频，已转存自托管）</figcaption> </figure> <blockquote> <p>调研日期：2026-06-11（发布后第 2 天）。来源为公开报道 + 社区帖；Shumer 等人的原始 prompt 未公开，技术拆解部分含基于公开细节的反推，已标注。</p> </blockquote> <h2 id="tldr">TL;DR</h2> <p>Anthropic 于 2026-06-09 发布 Claude Fable 5（Mythos-class 模型加安全层后的公开版）。发布数小时内 X 被三类 demo 刷屏：<strong>单 prompt 出 photoreal 3D 世界</strong>（three.js 浏览器实时渲染）、<strong>单 prompt 出可玩游戏</strong>、<strong>多小时自主长跑完成完整工程</strong>。拆开看没有魔法：素材来自真实公开数据（卫星图/DEM）+ 程序化生成，质感来自模型手写 production 级 GLSL shader，规模来自 InstancedMesh/LOD，复杂工程来自 agentic 长跑（计划→工具→自修复，最长公开案例 9.5 小时连续运行）。能力来源按 Nathan Lambert 的判断是”全栈进步、无单点突破”。主要约束是价格：$10/$50 每百万 token（输入/输出），Pro 用户跑几个任务就耗尽额度。</p> <hr /> <h2 id="一demo-清单按类别">一、demo 清单（按类别）</h2> <h3 id="1-3d-世界--实时渲染类多为单文件-threejs浏览器直接跑">1. 3D 世界 / 实时渲染类（多为单文件 three.js，浏览器直接跑）</h3> <table> <thead> <tr> <th>Demo</th> <th>作者</th> <th>要点</th> </tr> </thead> <tbody> <tr> <td>photoreal 森林</td> <td>Matt Shumer</td> <td>实时浏览器渲染，”custom-built ThreeJS”；首版有性能问题，一句 “make it faster, without losing quality” 修复。原始 prompt 仅 DM 私享（社区为 gatekeeping 吵了一架）</td> </tr> <tr> <td>可漫游 Yosemite 山谷</td> <td>Shlok Khemani</td> <td><strong>技术细节最完整的案例</strong>：拉卫星影像贴地表 + NASA 真实高程数据（DEM）做地形 → 对卫星图做像素分类识别植被 → 程序化种 ~26.6 万棵树 → 给六条真实瀑布在正确崖壁位置写自定义水体 shader</td> </tr> <tr> <td>NYC 天际线 / 城市风暴 / 波音 747 / 5000+ 物体太空模拟</td> <td>Shumer 等</td> <td>同一路线的变体，747 有网友部署的<a href="https://huggingface.co/spaces/victor/fable-5-boeing-747">在线可玩版（HF Space）</a>；太空模拟另有网友版本达 10 万+ 物体（动态 LOD）</td> </tr> <tr> <td>飞机/导弹/地形/海面/港口/桥梁/舰艇建模</td> <td>中文社区网友</td> <td>一句话单 HTML 文件内完成（量子位首日实测汇总）</td> </tr> </tbody> </table> <blockquote> <p>注：用户在 X 上看到的”上古卷轴复刻”“被洪水淹没的哥特城市”属于这一类的衍生变体（城市风暴场景 + 单 prompt 游戏复刻的组合），未见独立技术报道；另有网友给的题目是”尽量完美复刻骑马与砍杀 3D 版，单 HTML 运行”（知乎）。</p> </blockquote> <h3 id="2-单-prompt-可玩游戏类">2. 单 prompt 可玩游戏类</h3> <ul> <li><strong>Minecraft 克隆</strong>：单 prompt（high effort 档）~20 分钟出成品，含多 biome、昼夜循环、矿石、洞穴、背景音乐；X 上 890K 浏览。社区共识的代表作，也是质疑的焦点（见第三节）。</li> <li><strong>Library of Babel</strong>（Every.to vibe check）：博尔赫斯”通天塔图书馆”的可行走 3D 还原（六边形房间无限图书馆），<strong>3 小时自主长跑</strong>构建。</li> <li><strong>RollerCoaster Tycoon 风格游戏</strong>：YouTube 创作者，约 1 小时设计+编码完成可玩版。</li> <li><strong>自指 Snake / Breathwork Garden / 《只有一道门》复刻</strong>：均为单 prompt/单次推理产物。</li> <li><strong>Slay the Spire</strong>：不是”做游戏”而是”打游戏”——能稳定完成整局 run。</li> </ul> <figure> <video controls="" muted="" loop="" playsinline="" preload="metadata" style="width:100%;border-radius:3px"> <source src="https://game.panyifeng.xyz/media/posts/2026-06-11-fable5/leveldevil.mp4" type="video/mp4" /> </video> <figcaption>《只有一道门》（Level Devil）复刻实录，medium effort 档单 prompt 产物（<a href="https://x.com/LexnLin/status/2064450732850348518">@LexnLin 原帖</a>视频，转存自托管）</figcaption> </figure> <figure> <img src="/assets/img/posts/2026-06-11-fable5/minecraft-twitter-fable.jpg" alt="Fable 5 在 Minecraft 里搭出的推特界面" style="width:100%;border-radius:3px" /> <img src="/assets/img/posts/2026-06-11-fable5/minecraft-twitter-gpt55.jpg" alt="GPT-5.5 同题对比" style="width:100%;border-radius:3px;margin-top:6px" /> <figcaption>同题对比「在 Minecraft 里做一个推特」：上 Fable 5（连笔记本键盘底座都搭了出来），下 GPT-5.5（<a href="https://x.com/adonis_singh/status/2064415411198730265">@adonis_singh 原帖</a>截图）</figcaption> </figure> <h3 id="3-应用--os-复刻类">3. 应用 / OS 复刻类</h3> <ul> <li><strong>浏览器版 Windows OS 克隆</strong>：登录屏、通知、Edge 风格浏览器、纸牌、Copilot 全套。</li> <li><strong>一句 prompt 复刻 Photoshop</strong>：修图/调色/特效/绘画，能处理色彩分离、颗粒质感（量子位实测）。</li> </ul> <figure> <video controls="" muted="" loop="" playsinline="" preload="metadata" style="width:100%;border-radius:3px"> <source src="https://game.panyifeng.xyz/media/posts/2026-06-11-fable5/pskiller.mp4" type="video/mp4" /> </video> <figcaption>「我用一句 prompt 杀死了一家 2400 亿美元的公司」——浏览器版 Photoshop 复刻演示（<a href="https://x.com/hewarsaber/status/2064404745452744793">@hewarsaber 原帖</a>视频，转存自托管）</figcaption> </figure> <figure> <img src="/assets/img/posts/2026-06-11-fable5/fable-autobio-site.jpg" alt="Fable 5 给自己写的自传网站" style="width:100%;border-radius:3px" /> <figcaption>Fable 5 给自己设计/撰写/动效的「自传」网站："I learned to read in your libraries… no human hand has touched this code."（via 量子位）</figcaption> </figure> <ul> <li><strong>网络抓包可视化</strong>：实时 packet 渲染成高速公路车流，车型对应包类型（observability 工具创意）。</li> <li><strong>等时圈地图</strong>（Ethan Mollick）：多 agent 收集航班/铁路/公路数据做交互地图，持续迭代吃反馈，token 消耗极高。</li> </ul> <h3 id="4-工程长跑类最被低估商业上最重的一类">4. 工程长跑类（最被低估、商业上最重的一类）</h3> <ul> <li><strong>Stripe：5000 万行 Ruby 代码库迁移，1 天完成</strong>（人工估 2 个月+）。这是官方背书案例，也是”agentic 长跑”能力的上限展示。</li> <li><strong>Concord 研究工具</strong>（Mollick）：<strong>9.5 小时连续自主运行</strong>，产出 19 页设计文档 + 可用软件。</li> <li><strong>micropython-wasm → CPython 升级</strong>（Simon Willison 实测）：真实开源项目维护任务一次过。</li> </ul> <h3 id="5-其他模态">5. 其他模态</h3> <ul> <li><strong>Pokémon FireRed 纯视觉通关</strong>：只看屏幕截图、无任何外部导航辅助，长上下文记忆较 Opus 4.8 提升 ~3×。</li> <li><strong>CAD / 可 3D 打印模型设计</strong>、太阳系模拟等科学计算类。</li> </ul> <hr /> <h2 id="二技术实现方式拆解">二、技术实现方式拆解</h2> <h3 id="3d-世界类的配方已沉淀进-memory-threejs-photoreal-techniques">3D 世界类的配方（已沉淀进 memory <code class="language-plaintext highlighter-rouge">threejs-photoreal-techniques</code>）</h3> <ol> <li><strong>素材 = 真实公开数据，不是美术资产</strong>。卫星 tile 当地表纹理、NASA SRTM/DEM 当 heightmap、像素分类驱动程序化植被布点。零 Unity/Unreal、零模型库。”看上去像真的”是因为地形和纹理本来就是真的。</li> <li><strong>质感 = 手写 GLSL</strong>。水体反射、体积雾、大气散射、bloom 后期全部自定义 shader。这是这一代模型相对上一代最实质的解锁——以前写 shader 是车祸现场，现在能直出接近 production 级，且 2000–4000 行单文件内部自洽不失忆。</li> <li><strong>规模 = InstancedMesh + LOD + 雾截断</strong>。26.6 万树、5000+ 物体 60fps，是 three.js 标准答案，模型语料里见过无数遍。</li> <li><strong>不全是 one-shot</strong>。性能问题靠追加一轮 “make it faster, without losing quality” 单独迭代；很多”one-shot”demo 实际在 Claude Code 里跑过 截图→自查→修 的回环。</li> <li><strong>prompt 反推要点</strong>（原始 prompt 未公开）：高 effort 档（Fable 5 新增 effort 参数）+ photorealistic 措辞 + 指定真实地点（触发拉真实数据）+ 给联网/数据获取工具 + 单文件 HTML 约束。</li> </ol> <h3 id="游戏--应用类的配方">游戏 / 应用类的配方</h3> <ul> <li>本质是<strong>氛围签名复刻</strong>：Minecraft=体素+biome+昼夜，Windows=登录屏+通知+纸牌。训练语料里此类代码衍生物海量，单 prompt 出”看起来一样”的复制品证明的是流畅度（fluency）而非发明（invention）——这是社区最主流的质疑，成立但不影响实用价值。</li> <li>长上下文 + 长输出让”一个 demo=一个几千行自洽单文件”成为可能，这在两年前会写到一半失忆。</li> </ul> <h3 id="工程长跑类的配方">工程长跑类的配方</h3> <ul> <li><strong>agentic 端到端</strong>：计划 → 工具调用 → 跑测试 → 自修复，多小时无人值守（公开最长 9.5h）。Every.to 的判断：”Fable 5 最强的形态是把整个任务交给它 own 到底”，其 Senior Engineer 内部基准 91/100（Opus 4.8 = 63，GPT-5.5 = 62）。</li> <li>Stripe 迁移的意义不是”写得快”而是<strong>一致性在 5000 万行尺度上不崩</strong>。</li> </ul> <h3 id="能力来源分析层">能力来源（分析层）</h3> <ul> <li>Nathan Lambert（Interconnects）：<strong>没有单点技术突破</strong>（不是某个新 RL 范式或推理时扩展），是”全栈各环节同时进步”的结果；同时批评其对 AI 开发类请求的隐性安全降级不透明。</li> <li>Fable 5 = Mythos 5 同底模型 + 安全分类器/过滤层；安全层在 cyber/bio 上是显式拦截，在部分领域是隐式修改。</li> </ul> <hr /> <h2 id="三质疑与边界">三、质疑与边界</h2> <ol> <li><strong>复现 ≠ 发明</strong>：one-shot Minecraft/Windows 克隆证明对海量已见模式的流畅重组，原创游戏设计能力未被这批 demo 证明。</li> <li><strong>Prompt gatekeeping</strong>：最火的 Shumer 系列 prompt 不公开，可复现性存疑，部分效果可能依赖多轮筛选。</li> <li><strong>成本是真实门槛</strong>：API $10/$50 每百万 token（in/out）；$20 Pro 套餐”简单跑几个任务就用完额度”（爱范儿）；B 站 UP 主实测 4 个任务烧 ¥800。36 氪标题”普通人慎用”即此意。等时圈地图、Concord 这类长跑案例 token 消耗都”极高”。</li> <li><strong>demo ≠ 产品</strong>：9.5 小时长跑产物仍需人工 review；50M 行迁移的 review 问题被多家工程博客单独拿出来讨论（”谁来 review 一天 5000 万行”）。</li> </ol> <hr /> <h2 id="四对自己项目clawgame的可借鉴清单">四、对自己项目（~/claw/game/）的可借鉴清单</h2> <ul> <li>大场景游戏直接套 photoreal 配方：真实 DEM/卫星图 + 程序化 instancing + 手写 shader；INKLINE 的 three.js 双层渲染已在同一路线上，差的是”真实数据当素材”这一步。</li> <li>性能不进首 prompt，单独一轮 “make it faster, without losing quality”。</li> <li>DOM 渲染器项目（EMBERSEA/YAOYAN）的天花板结论不变：表现层换 PixiJS/three.js + shader 才能吃到这一代模型的 shader 红利（见 memory <code class="language-plaintext highlighter-rouge">feedback_dom_renderer_ceiling</code>）。</li> <li>浏览器内验证回环（Playwright 截图→自查→修）是把”能跑”提到”能发布”的关键，本机 webapp-testing 已具备。</li> </ul> <h2 id="来源">来源</h2> <ul> <li><a href="https://www.anthropic.com/news/claude-fable-5-mythos-5">Anthropic — Claude Fable 5 and Claude Mythos 5</a></li> <li><a href="https://vallettasoftware.com/blog/post/claude-fable-5-review">Valletta Software — What Anthropic Shipped and Why X Went Wild</a>（Minecraft 克隆/Shumer/Yosemite/Windows 克隆/抓包可视化）</li> <li><a href="https://digg.com/ai/bts64g87">Digg — Fable 5 real-time Three.js demos &amp; Pokémon FireRed</a>（forest/NYC/747/5000+ 物体/城市风暴清单、prompt DM 争议）</li> <li><a href="https://every.to/vibe-check/anthropic-mythos-our-fable-vibe-check">Every.to — Vibe Check: Fable 5 Is the Best Coding Model in the World</a>（Library of Babel 3h 长跑、91/100 基准）</li> <li><a href="https://www.interconnects.ai/p/claude-fable-5-and-new-ai-safety">Interconnects (Nathan Lambert) — Claude Fable 5 and new safety fables</a>（”无单点突破、全栈进步”+安全层批评）</li> <li><a href="https://simonwillison.net/2026/Jun/9/claude-fable-5/">Simon Willison — Initial impressions of Claude Fable 5</a>（micropython 升级实测、effort 档位）</li> <li><a href="https://www.qbitai.com/2026/06/433682.html">量子位 — Claude Fable 5 首日实测，杀疯了</a>（中文社区 demo 汇总：PS 复刻/只有一道门/单 HTML 建模）</li> <li><a href="https://www.qbitai.com/2026/06/433590.html">量子位 — Claude Mythos 5 发布！5000 万行代码 1 天搞定</a></li> <li><a href="https://www.ifanr.com/1668542">爱范儿 — 实测 Claude 史上最强模型 Fable 5，普通人慎用</a>（Mollick 等时圈/Concord 9.5h、定价与额度）</li> <li><a href="https://nerdschalk.com/fable-5-samples-comparison-reviews-opinions/">Nerdschalk — Fable 5 Samples, Comparison, Reviews</a>（RollerCoaster Tycoon/Breathwork Garden）</li> <li><a href="https://news.ycombinator.com/item?id=48464094">Hacker News — Stripe 50M 行迁移讨论</a></li> <li><a href="https://www.theshortcut.com/p/anthropic-releases-claude-fable-5-an-ai-model-that-can-build-playable-video-games-from-a-single-prompt">The Shortcut — builds playable video games from a single prompt</a></li> <li><a href="https://techcrunch.com/2026/06/09/anthropic-released-claude-fable-5-its-most-powerful-model-publicly-days-after-warning-ai-is-getting-too-dangerous/">TechCrunch — Fable 5 发布报道</a></li> <li><a href="https://www.zhihu.com/question/2047851398734394746">知乎 — 如何评价 Anthropic 发布的 Claude Fable 5</a>（骑马与砍杀复刻题等）</li> <li><a href="https://www.bilibili.com/video/BV1F7EQ6tE7i/">B 站 — 怒砸 800 大洋实测 Fable 5</a></li> </ul>

Fable 5 发布首周刷屏 demo 全景：photoreal 3D 世界、单 prompt 可玩游戏、9.5 小时工程长跑，以及它们的技术实现拆解——真实地理数据当素材、手写 GLSL、agentic 自修复。

2026-05-29T04:00:00+00:00 2026-05-29T04:00:00+00:00 https://jinzi.cyou/posts/multi-device-mesh-headscale-syncthing <p>我有好几台机器在同时干活:公司一台台式、公司一台 Mac、家里一台、外加一台自己的云服务器。同一个工作目录在多台之间来回改,长期靠一个手写的 <code class="language-plaintext highlighter-rouge">sync-all</code> 脚本同步——但它不好用:<strong>它是手动的、按需跑的</strong>,只要哪次忘了”先拉再改”,两边就分叉,然后就是无穷无尽的手工 merge。</p> <p>折腾到最后我想明白一件事:<strong>问题的根子不是”机器多”,而是”没有一个永远在线、永远可达的唯一真相源”。</strong> <code class="language-plaintext highlighter-rouge">sync-all</code> 难用,不是脚本写得烂,而是”按需手动”这个模式本身留了一个会分叉的窗口。</p> <p>这篇讲我怎么用 <strong>自建 Headscale(Tailscale 控制面)+ Syncthing</strong> 把这件事一次性解决掉:两台机器再也不用想”同步”这回事,改完存盘几秒就到对面;顺带任意两台之间能直接 SSH。全程自托管、无主从、加新机器一条命令。也会老实把踩的坑和没解决的取舍单列出来。</p> <blockquote> <p>环境说明:文中所有域名/IP/密钥都是占位符。我的几台机器里有 WSL、macOS,云服务器在国内——所以”控制面在 GFW 后面稳不稳”是我必须考虑的硬约束,这一点很影响选型。</p> </blockquote> <hr /> <h2 id="一先否掉几个看起来更简单的方案">一、先否掉几个”看起来更简单”的方案</h2> <p>在动手前我认真比过几条路,它们都不对:</p> <ul> <li><strong>「只在一台上集中干活」</strong>(两端都 SSH 进同一台)。最干净,但我每台机器有各自的角色和本地工具链,集中不现实。</li> <li><strong>「让某个进程直接遥控家里那台,替我同步」</strong>。这是最脆弱的:家用机常关机、动态 IP、藏在 NAT 后,公司网经常根本够不到它;而且它等于多引入一个写入方,是多一个冲突源,不是少。</li> <li><strong>「老实用 git」</strong>。大多数子项目本来就是 git repo,但 git 解决不了”草稿、散文件、非版本化资产”的实时同步,而且它还是要人记得 commit/pull——又回到”手动窗口”。</li> </ul> <p>真正要的是两件正交的能力:<strong>(1) 任意机器之间稳定可达(含远程 SSH);(2) 工作目录实时双向同步、且离线机器上线后能自动追上。</strong> 这两件事分别由两层独立的 mesh 解决。</p> <hr /> <h2 id="二总体架构两层互相独立的-mesh">二、总体架构:两层互相独立的 mesh</h2> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> 云服务器(公网 IP)—— 唯一常在线的锚点 ┌──────────────────────────────────────────────────────────┐ │ Headscale 控制面(自建,替代 login.tailscale.com) │ ← 连通层大脑 │ + 内嵌 DERP 中继 + STUN(NAT 穿透) │ │ Syncthing 常在线枢纽 + 介绍人(GUI 仅在 tailnet 内可达) │ ← 同步层枢纽 └──────────────────────────────────────────────────────────┘ ▲ 各节点只是「出站」连一个公网 IP,与 GFW 无关 ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 公司台式 │◄─►│ 家里电脑 │◄─►│ Mac │ 每台: │ 100.64.0.1 │ │ 100.64.0.4 │ │ 100.64.0.3 │ tailscale 节点 └──────────────┘ └──────────────┘ └──────────────┘ + syncthing 节点 每台拿到稳定 100.64.x 地址;Syncthing 跑在 tailnet 上,不碰国际发现服务器 </code></pre></div></div> <ul> <li><strong>连通层 = Tailscale 客户端 + 自建 Headscale。</strong> 每个节点加入后拿到一个固定的 <code class="language-plaintext highlighter-rouge">100.64.x.x</code> 地址和一个 MagicDNS 名,无论在哪个网络、NAT 后面都能互相直连(打不通就走 DERP 中继兜底)。Tailscale 是真 mesh:控制面只在「建立连接」时参与,它挂了,已经建好的点对点连接照常跑。</li> <li><strong>同步层 = Syncthing。</strong> P2P、无中心。但我额外让那台常在线的云服务器当<strong>枢纽</strong>:它持有一份同步副本,这样即使”家里和公司从不同时开机”也能收敛(各自上线时跟枢纽对齐);它还兼<strong>介绍人(introducer)</strong>,新节点只要连上枢纽就自动认识全网其它节点。</li> </ul> <p>两层都是”加节点 = 一条命令”,这正好满足”以后随时扩机器”。</p> <hr /> <h2 id="三两个关键选型决定">三、两个关键选型决定</h2> <p><strong>为什么自建 Headscale,而不是直接用官方 Tailscale?</strong> 官方 Tailscale 的控制面在境外(<code class="language-plaintext highlighter-rouge">login.tailscale.com</code> / <code class="language-plaintext highlighter-rouge">controlplane.tailscale.com</code>)。我的节点都在国内,控制面在 GFW 后面时通时不通,作为每天依赖的基础设施太不踏实。Headscale 是 Tailscale 控制面的开源自托管实现(单 Go 二进制 + SQLite),我把它放在自己那台<strong>有公网 IP 的国内云服务器</strong>上,所有节点只是”出站连一个域内公网 IP”——和 GFW 彻底无关。它还能开<strong>内嵌 DERP 中继</strong>,连中继都不必依赖官方的境外节点。</p> <p><strong>为什么 Syncthing 要跑在 tailnet 上?</strong> Syncthing 自带全球发现 + 中继服务器,但那些也在境外、同样会被限速。既然已经有了 tailnet,我直接给每个 Syncthing 节点配上对端的 <code class="language-plaintext highlighter-rouge">100.64.x</code> 静态地址、<strong>关掉全球发现和中继</strong>,流量全走自己的 tailnet。又稳又不依赖任何境外基础设施。</p> <hr /> <h2 id="四搭建要点命令为示意去掉了我自己的域名ip">四、搭建要点(命令为示意,去掉了我自己的域名/IP)</h2> <p><strong>1) 云服务器上的 Headscale</strong>——走一个子域 + 你现有的反向代理 + ACME 证书,控制面监听本地、由反代转发(Tailscale 客户端要求 HTTPS 且需放行 WebSocket 升级):</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># /etc/headscale/config.yaml(节选)</span> <span class="na">server_url</span><span class="pi">:</span> <span class="s">https://hs.example.com</span> <span class="na">listen_addr</span><span class="pi">:</span> <span class="s">127.0.0.1:8080</span> <span class="na">derp</span><span class="pi">:</span> <span class="na">server</span><span class="pi">:</span> <span class="na">enabled</span><span class="pi">:</span> <span class="no">true</span> <span class="c1"># 内嵌 DERP,不依赖境外中继</span> <span class="na">region_id</span><span class="pi">:</span> <span class="m">999</span> <span class="na">stun_listen_addr</span><span class="pi">:</span> <span class="s2">"</span><span class="s">0.0.0.0:3478"</span> <span class="na">urls</span><span class="pi">:</span> <span class="pi">[]</span> <span class="c1"># 清空官方(境外)DERP map</span> <span class="na">dns</span><span class="pi">:</span> <span class="na">magic_dns</span><span class="pi">:</span> <span class="no">true</span> <span class="na">base_domain</span><span class="pi">:</span> <span class="s">mesh.internal</span> </code></pre></div></div> <p>反代关键是 WebSocket(否则控制连接 / DERP 长连接建不起来):</p> <div class="language-nginx highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">location</span> <span class="n">/</span> <span class="p">{</span> <span class="kn">proxy_pass</span> <span class="s">http://127.0.0.1:8080</span><span class="p">;</span> <span class="kn">proxy_http_version</span> <span class="mi">1</span><span class="s">.1</span><span class="p">;</span> <span class="kn">proxy_set_header</span> <span class="s">Upgrade</span> <span class="nv">$http_upgrade</span><span class="p">;</span> <span class="kn">proxy_set_header</span> <span class="s">Connection</span> <span class="nv">$connection_upgrade</span><span class="p">;</span> <span class="c1"># map 出来的变量</span> <span class="kn">proxy_read_timeout</span> <span class="s">86400s</span><span class="p">;</span> <span class="c1"># 长轮询</span> <span class="p">}</span> </code></pre></div></div> <p><strong>2) 节点接入</strong>——装 Tailscale,用 preauth key 接到自建控制面:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl <span class="nt">-fsSL</span> https://tailscale.com/install.sh | sh <span class="nb">sudo </span>tailscale up <span class="nt">--login-server</span><span class="o">=</span>https://hs.example.com <span class="se">\</span> <span class="nt">--authkey</span><span class="o">=</span>hskey-xxxxxxxx <span class="nt">--accept-dns</span><span class="o">=</span><span class="nb">false</span> </code></pre></div></div> <p><code class="language-plaintext highlighter-rouge">--accept-dns=false</code> 是有意的:桌面/WSL 自己管 <code class="language-plaintext highlighter-rouge">/etc/resolv.conf</code>,别让 Tailscale 去抢,免得搞坏本机 DNS;节点间用 <code class="language-plaintext highlighter-rouge">100.64.x</code> 地址就够了。</p> <p><strong>3) Syncthing</strong>——云服务器当枢纽常驻,叶子节点各跑一个;通过 REST API 把对端设备 + 共享文件夹配好,并把监听地址绑到自己的 tailnet IP、关掉全球发现/中继。叶子节点把”枢纽”这台标成 <code class="language-plaintext highlighter-rouge">introducer: true</code>,新节点连上枢纽就自动学到其它节点。</p> <p><strong>4) 同步范围</strong>——一份 <code class="language-plaintext highlighter-rouge">.stignore</code> 决定同步什么。我的原则是<strong>只同步代码/草稿/脚本/配置,排除一切”重而可再生”的东西</strong>:<code class="language-plaintext highlighter-rouge">node_modules</code>、虚拟环境、构建产物、缓存、<code class="language-plaintext highlighter-rouge">*.mp4/*.glb</code> 等重媒体、模型权重,以及 <code class="language-plaintext highlighter-rouge">.git</code>(仓库走它自己的 git remote,不靠 Syncthing 同步 <code class="language-plaintext highlighter-rouge">.git</code>,避免索引冲突)。这一刀下去,我的同步集从几 GB 缩到几百 MB。</p> <hr /> <h2 id="五踩过的坑这节才是干货">五、踩过的坑(这节才是干货)</h2> <p><strong>坑 1:CGNAT 网段和云厂商内网撞车。</strong> Tailscale 用 <code class="language-plaintext highlighter-rouge">100.64.0.0/10</code> 这个 CGNAT 段。某些云厂商(我遇到的是一类国内云实例)的<strong>内网服务</strong>(apt 镜像、元数据)正好用 <code class="language-plaintext highlighter-rouge">100.100.x.x</code>——它落在 <code class="language-plaintext highlighter-rouge">100.64.0.0/10</code> 里!装上 Tailscale 后,它把云内网路由给吞了,<code class="language-plaintext highlighter-rouge">apt</code> 直接超时。修法是给云内网网段加一条<strong>更具体的旁路路由</strong>(优先级高于 /10),让它走真实网关:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ip route replace 100.100.0.0/16 via &lt;真实网关&gt; dev eth0 <span class="c"># 再用 systemd oneshot 持久化,排在 tailscaled 之后</span> </code></pre></div></div> <p><strong>坑 2:WSL 上的 Tailscale。</strong> 现代 WSL2 有 systemd 和 <code class="language-plaintext highlighter-rouge">/dev/net/tun</code>,Tailscale 能当正常服务跑。但它的 connmark 防火墙规则在 WSL 内核上会报 <code class="language-plaintext highlighter-rouge">unknown option "--restore-mark"</code>(缺内核模块)。节点只是普通客户端、不做出口/子网路由的话,直接 <code class="language-plaintext highlighter-rouge">--netfilter-mode=off</code> 让它别碰 iptables 最干净(必要时再 <code class="language-plaintext highlighter-rouge">iptables-legacy</code>)。</p> <p><strong>坑 3:Syncthing 的 <code class="language-plaintext highlighter-rouge">#include</code> 死锁(这个最隐蔽)。</strong> 为了让忽略规则全网一致、改一处就生效,我让每个节点的 <code class="language-plaintext highlighter-rouge">.stignore</code> 只写一行 <code class="language-plaintext highlighter-rouge">#include .stglobalignore</code>,真正的规则放在会被同步的 <code class="language-plaintext highlighter-rouge">.stglobalignore</code> 里。听起来很优雅——<strong>但新节点入网时还没同步到 <code class="language-plaintext highlighter-rouge">.stglobalignore</code>,<code class="language-plaintext highlighter-rouge">#include</code> 一个不存在的文件会导致忽略规则解析失败,文件夹直接卡在 <code class="language-plaintext highlighter-rouge">sync-waiting</code> 永远不拉取</strong>,而它要拉的东西里就包含那个 <code class="language-plaintext highlighter-rouge">.stglobalignore</code>。死锁。修法:节点入网脚本里<strong>先内嵌写一份 <code class="language-plaintext highlighter-rouge">.stglobalignore</code> 本地兜底</strong>,再 include;之后同步过来的同名文件内容一致、不会冲突。</p> <p><strong>坑 4:跨版本能互通,但要心里有数。</strong> 我的几台分别是 Syncthing v1.18(发行版自带的旧版)和 v2.1(官方 tarball)。BEP 协议跨大版本兼容,实测 v1.18 ↔ v2.1 正常建连同步。能用,但要装新机时尽量统一版本省心。</p> <p><strong>坑 5:第一个冲突,居然是忽略文件自己。</strong> 全网合并跑完,真实工作文件 0 冲突,唯一一个 <code class="language-plaintext highlighter-rouge">.sync-conflict</code> 是 <code class="language-plaintext highlighter-rouge">.stglobalignore</code>——因为我和”另一台上的我”几乎同时改了它。这反而是个好示范:冲突时 Syncthing <strong>不覆盖</strong>,把另一版留成带时间戳的副本,让你手动并。</p> <hr /> <h2 id="六性能与冲突语义撑不撑得住频繁改">六、性能与冲突语义:撑不撑得住频繁改?</h2> <p><strong>撑得住,前提是别让它同步该排除的东西。</strong></p> <ul> <li><strong>不是每次保存都同步</strong>:Syncthing 走文件系统事件监听(inotify/FSEvents)+ <strong>~10 秒防抖</strong>,连续保存会攒一起发,不是逐键。再加一个低频全量扫描兜底。</li> <li><strong>增量只传变化的块</strong>(block 级去重):改一个大文件只传变动的那几 KB,不重传整文件。</li> <li>我这套(约六千文件 / 几百 MB 代码+文档)是 Syncthing 的舒适区——它能扛十万级文件、几百 GB。空闲内存几十 MB,只在扫描/算 hash 时短暂吃 CPU。</li> <li><strong>真正撑不住的是</strong>:海量碎写的生成目录(<code class="language-plaintext highlighter-rouge">node_modules</code>/构建/缓存)、正在写的数据库 / SQLite WAL / 实时日志。这些务必在 <code class="language-plaintext highlighter-rouge">.stignore</code> 里排掉,否则它会疯狂 rescan + 算 hash + 制造一堆版本。</li> </ul> <p><strong>冲突怎么解?</strong></p> <ul> <li>两台<strong>各自独立改了同一文件</strong> → 一份按修改时间较新的留原名,另一份重命名成 <code class="language-plaintext highlighter-rouge">名字.sync-conflict-日期-时间-设备.后缀</code>。<strong>两份都在,不覆盖、不丢。</strong></li> <li>冲突副本也会同步到所有节点,你在任意机器都能处理;每文件默认最多留 10 个副本。</li> <li>Syncthing <strong>不做内容三方合并</strong>(不像 git)。代码场景最顺的解法就是用 git:<code class="language-plaintext highlighter-rouge">.sync-conflict</code> 文件就是另一版本,<code class="language-plaintext highlighter-rouge">diff</code> 一下挑/合,然后删掉它。</li> <li><strong>删除会传播</strong>(一台删,别处跟着删)。所以我额外在常在线的枢纽上开了 <strong>staggered 版本控制(留 30 天)</strong>:任何文件被改写/删除前,旧版进枢纽的 <code class="language-plaintext highlighter-rouge">.stversions</code>,30 天内可取回——等于白送一个带时间机器的备份节点。叶子节点不开,省空间。</li> </ul> <hr /> <h2 id="七安全模型一台被黑会不会全套连根挂">七、安全模型:一台被黑会不会全套连根挂?</h2> <p>这是我自己最在意的问题,老实说结论:<strong>会有影响,但范围有限,而且能进一步收窄。</strong></p> <p><strong>真实暴露面</strong>:云服务器只对公网开 <code class="language-plaintext highlighter-rouge">443/80</code>(反代,Headscale 控制面在其后、要合法 preauth key 才能进网)、<code class="language-plaintext highlighter-rouge">22</code>、<code class="language-plaintext highlighter-rouge">3478</code>(STUN 反射,低危)。<strong>Syncthing 的数据口和管理口只绑在 tailnet 地址上,公网根本没监听</strong>——同步内容不在互联网上。</p> <p><strong>真实风险</strong>:病根是”共享凭据”(preauth key + 枢纽 API key)。最坏情况下,某台叶子被黑 → 拿到这些凭据 → 能加流氓节点、能改/删同步目录并扩散。但它<strong>不会</strong>自动变成”每台机器 root”:各节点的 WireGuard 私钥只在本机,控制面被黑也解不开已建立的点对点流量;拿不到各机的 SSH 凭据也登不进别的节点。也就是说 blast radius 是”那个同步目录 + 重新拉个节点进来”,不是你整个数字资产。</p> <p><strong>于是我做了几层收窄</strong>:</p> <ul> <li><strong>preauth key 短期化</strong>:加机时才发、有效期几十小时,加完立刻作废。不留长效可复用 key。</li> <li><strong>叶子不留长效凭据</strong>:入网脚本注册成功后,自动把本地凭据文件里的一次性密钥<strong>抹空</strong>。某台叶子失窃也拿不到入网权/枢纽控制权。</li> <li><strong>Headscale ACL</strong>:节点间只放行必要端口(SSH + Syncthing + 枢纽注册),其余拒,限制被黑节点的横向移动。</li> <li>枢纽 API key 可随时轮换。</li> </ul> <p>比起原来”明文 SSH key 到处放 + 手动 rsync”的老办法,这套在堵掉共享凭据后是<strong>明显更安全</strong>的,不会更差。</p> <hr /> <h2 id="八加一台新机器一条命令">八、加一台新机器:一条命令</h2> <p>我把上面所有步骤(装 Tailscale → 入网 → 装 Syncthing → 绑 tailnet/关国际发现/加枢纽/写忽略规则 → 自助注册到枢纽 → 抹掉一次性密钥)封成一个 <code class="language-plaintext highlighter-rouge">mesh-join</code> 脚本,Linux/WSL/macOS 通吃、幂等。新机器:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 从已入网节点取脚本 + 一次性凭据,然后:</span> bash mesh-join &lt;节点名&gt; </code></pre></div></div> <p>实测在一台 macOS 上一键跑通(它还同时跑着别的 TUN 代理,共存无碍),并通过”介绍人”自动和其它节点直连——验证了”分布式 + 随时加节点”这个目标。</p> <hr /> <h2 id="九还差什么--取舍老实说">九、还差什么 / 取舍(老实说)</h2> <ul> <li><strong>枢纽是单点真相</strong>:它挂了,新建连接和”非同时在线的收敛”会受影响(已建的 P2P 同步不受影响),且它承担中继流量。对个人规模够用;真要更稳得再加一个枢纽/中继。版本回收让”枢纽挂了丢数据”的风险可控。</li> <li><strong>DERP 走自建单点</strong>:两台都在 NAT 后、打不通直连时,中继流量全过那台云服务器,受它带宽限。同 LAN 的两台会直连,不吃这个亏。</li> <li><strong>ACL 与”自由互联”的张力</strong>:我收紧了节点间端口,代价是想临时访问某台上的别的服务(比如本地 dev server)得先开端口。安全和便利的常规取舍。</li> <li><strong><code class="language-plaintext highlighter-rouge">.git</code> 不同步</strong>:换来的是稳定(不撞 <code class="language-plaintext highlighter-rouge">.git</code> 索引冲突),代价是仓库状态得靠各自的 git remote 收敛——对本来就有远端的项目无所谓。</li> </ul> <hr /> <h2 id="收尾">收尾</h2> <p>这套方案的核心判断是:<strong>多机同步的难点不在”找个同步工具”,而在”先有一个永远在线、永远可达、且自托管不受制于人的网络底座”。</strong> 先用自建 Headscale 把”任意机器互相可达”这件事坐实,Syncthing 这种 P2P 工具才能稳稳地跑在上面;再用一个常在线的枢纽兼介绍人,把”非同时在线”和”随时加节点”两个现实问题一起解决。</p> <p>搭完之后最大的感受是:<strong>“同步”这个动作从我的脑子里消失了</strong>——我不再”做同步”,我只是在不同机器上改文件,它们自己会一致。这正是基础设施该有的样子:你感觉不到它,直到你想加第五台机器,发现也只是一条命令。</p>

多台机器共享一个工作目录、手动同步老分叉冲突?用自建 Headscale(Tailscale 控制面)+ Syncthing 搭两层独立 mesh:连通层让任意机器互相可达并能 SSH,同步层存盘即双向同步、离线机器上线自动追上。含完整架构、选型理由(为何自建控制面)、五个踩坑(CGNAT 网段撞车 / WSL / #include 死锁等)、性能与冲突语义、安全模型与取舍。

2026-05-25T04:00:00+00:00 2026-05-25T04:00:00+00:00 https://jinzi.cyou/posts/claude-code-pm-worker-auditor-pipeline <p>几周前我写过一篇偏「方法论」的长文，讲怎么把 AI 从单兵 Copilot 升级成 PM/Worker/Auditor 三层金字塔（那篇是 6 周路线图 + canary + 度量体系的宏图）。这篇不一样：宏图我没全做，但<strong>最小闭环已经在真实的 bug 上跑通并合并了</strong>。所以这篇只讲一件事——那条最小闭环到底是怎么用 Claude Code 搭出来的、每一行设计为什么这么写、踩了哪些坑，以及它现在<strong>还差什么</strong>（我会诚实地把没做完的部分单列一节，而不是吹成全自动生产系统）。</p> <p>代码很短，短到可以逐段贴出来读。这恰恰是我想传达的核心判断：<strong>多 agent 自动开发流水线的难点不在编排框架，在职责分离的拓扑、状态外置的纪律、和确定性的安全闸——这三样都可以用文件系统 + GitHub + 几个 shell 脚本表达，不需要重型基础设施。</strong></p> <hr /> <h2 id="0-它现在能做什么先放真实证据">0. 它现在能做什么（先放真实证据）</h2> <p>不绕弯子，先放跑通的那一单。我在自己的一个前端项目 cue（一个影视配乐教学互动站）里开了一个 P3 的布局 bug，打上 <code class="language-plaintext highlighter-rouge">auto-eligible</code> 标，然后没再碰键盘，直到最后那一下「批准合并」：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Issue#1 ──worker(Opus,125s)──▶ PR#2 ──auditor(Sonnet,90s)──▶ ✅LGTM ──pyf 批准──▶ merged </code></pre></div></div> <p>这是 <code class="language-plaintext highlighter-rouge">runs.jsonl</code> 执行账本里这一单的真实记录（原文照搬，没修饰）：</p> <pre><code class="language-jsonl">{"ts": "2026-05-23T00:48:30.477948+00:00", "role": "worker", "task": "fix pyf-labrary/cue#1 (cue)", "issue": 1, "duration_s": 125.0, "result": "ok"} {"ts": "2026-05-23T00:56:27.466030+00:00", "role": "auditor", "task": "review pyf-labrary/cue PR#2 (cue)", "issue": 1, "duration_s": 90.0, "result": "ok"} {"ts": "2026-05-23T12:10:24.551876+00:00", "role": "pm", "task": "triage pyf-labrary/cue#1: already resolved — PR#2 merged, issue CLOSED/COMPLETED; no re-dispatch (would duplicate)", "issue": 1, "result": "ok"} </code></pre> <p>这几行后面会逐字段拆。这里先注意最后那行 PM 的记录：它是我<strong>故意在 Issue 已经合并关闭之后</strong>又对它跑了一次 PM 分诊——PM 没有重复派工，而是核对了 GitHub 和账本两个事实源，判断「已解决、再派会重复」，直接 no-op 退出。这是整套设计里我最在意的一个性质：<strong>幂等</strong>——下一节会讲为什么它是无人值守的前提。</p> <p>Worker 在那次跑里写出来的 PR，根因分析是这样的（节选自真实 PR body，不是我事后补的）：</p> <blockquote> <p>根容器 <code class="language-plaintext highlighter-rouge">relative isolate</code> 建立了一个层叠上下文。hero 背景图 div 是 <code class="language-plaintext highlighter-rouge">absolute … z-0</code>（带显式 z-index 的定位元素），而下方带 <code class="language-plaintext highlighter-rouge">border-t</code> 的「情绪详情」section 是无定位、无 z-index 的普通流块。按 CSS 绘制顺序，<code class="language-plaintext highlighter-rouge">z-index:0</code> 的定位元素绘制在普通流块之上……修复：给该 section 加 <code class="language-plaintext highlighter-rouge">relative z-10</code>，与 HERO 同层。</p> </blockquote> <p>一个真实的 CSS 层叠上下文 bug，被一个 headless agent 定位到根因、给出最小修复、跑了 <code class="language-plaintext highlighter-rouge">npm run build</code>、开了 PR、写清验收标准——全程我没看一眼代码，直到 Auditor 评论 LGTM 后我点了合并。这就是这条流水线当前的能力边界。下面讲它怎么搭的。</p> <hr /> <h2 id="1-为什么是三个-agent而不是一个更强的-agent">1. 为什么是「三个 agent」而不是「一个更强的 agent」</h2> <p>这点上一篇讲过心法，这里只补一句落到实现的判断：<strong>职责分离（Separation of Duties）不是 prompt 能模拟的，必须是结构保证。</strong></p> <p>让同一个 agent loop 既写代码、又 review 自己写的代码、又决定要不要合并，本质上是让它自己制衡自己——再强的模型也做不到，因为它没有「另一个视角」，它只有自己刚才那条推理链的延续。会计和信息安全里把这叫 SoD：经手钱的人不能同时是审账的人。放到 agent 流水线里就是：</p> <ul> <li><strong>PM</strong>：拆解、分诊、派工、验收编排。<strong>不碰代码</strong>。</li> <li><strong>Worker</strong>：在隔离的分支里写码、跑测试、开 PR。<strong>只能动自己那条 feature 分支</strong>。</li> <li><strong>Auditor</strong>：审 diff + 安全扫，结论评论回 PR。<strong>结构上不持写权</strong>——它根本没有 Edit/Write 工具，想改也改不了。</li> <li><strong>人（我）</strong>：只做最后那一下合并审批，以及红线 ack。</li> </ul> <p>关键在最后两条的「结构上」。我不是在 Auditor 的 prompt 里写「请你不要改代码」（那是软约束，模型可能不遵守、可能幻觉、可能被任务诱导绕过），而是在<strong>启动它的命令行里就没给它 Edit/Write 工具</strong>。这是确定性的：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Auditor 的工具白名单——注意没有 Edit/Write，从机制上保证它改不了代码</span> claude <span class="nt">-p</span> <span class="s2">"</span><span class="nv">$prompt</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--append-system-prompt</span> <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ~/army/roles/auditor.md<span class="si">)</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--permission-mode</span> default <span class="se">\</span> <span class="nt">--model</span> sonnet <span class="se">\</span> <span class="nt">--allowedTools</span> Bash Read Grep Glob </code></pre></div></div> <p>对比 Worker 的启动命令，差别一目了然：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Worker——给了 Edit/Write，且用 acceptEdits 模式让它能连续改文件不卡 ack</span> claude <span class="nt">-p</span> <span class="s2">"</span><span class="nv">$prompt</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--append-system-prompt</span> <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ~/army/roles/worker.md<span class="si">)</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--permission-mode</span> acceptEdits <span class="se">\</span> <span class="nt">--model</span> <span class="s2">"</span><span class="nv">$model</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--allowedTools</span> Bash Edit Write Read Grep Glob </code></pre></div></div> <p>PM 同理，白名单也只有 <code class="language-plaintext highlighter-rouge">Bash Read Grep Glob</code>——它能调 <code class="language-plaintext highlighter-rouge">gh</code> 命令操作 Issue、能读项目代码做分诊判断，但<strong>不能直接改业务代码</strong>。三个角色的写权限差异，全部落在 <code class="language-plaintext highlighter-rouge">--allowedTools</code> 这一行上，而不是 prompt 里的客套话。</p> <blockquote> <p>工程判断：<strong>能用白名单表达的约束，就不要用 prompt 表达。</strong> 白名单是 Claude Code 给你的确定性闸门，prompt 是概率性请求。安全相关的东西，永远优先选确定性的那个。</p> </blockquote> <p>模型分层也在这三条命令里：PM = Opus（判断要准），Worker 默认 Opus（写码质量优先，琐碎活降 Sonnet），Auditor = Sonnet（review 够用，巡检/日报可降 Haiku）。底座是 Claude Code 登录 Claude Max 订阅跑，所有 headless 进程挂同一份订阅 auth，<strong>边际美元成本约等于零</strong>——这是当初选 Claude Code 而不是只吃 BYOK 的运行时当底座的决定性理由（详见项目里的 ADR-001）。</p> <hr /> <h2 id="2-架构三段触发--一份注册表没有常驻框架">2. 架构：三段触发 + 一份注册表，没有常驻框架</h2> <p>整套东西的物理结构异常简单。所有「运行时之家」在一个目录 <code class="language-plaintext highlighter-rouge">~/army/</code>：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/army/ ├── CLAUDE.md 组织宪法（PM 运行于此时自动加载） ├── roles/ │ ├── pm.md PM 角色手册 │ ├── worker.md Worker 角色手册 │ └── auditor.md Auditor 角色手册 ├── projects.yaml 项目注册表：project → 路径/repo/部门/worker 画像/测试 ├── bin/ │ ├── army-dispatch poller：扫 auto-eligible Issue → 唤 PM（默认 DRY） │ ├── army-run-pm 唤 PM 分诊 + 派工某 Issue │ ├── army-run-worker 建 worktree + 起 Worker 修 + 开 PR + 记账 │ ├── army-run-auditor 起 Auditor 只读审 PR + 评论 │ ├── army-ledger 写一行 JSON 到 runs.jsonl │ ├── army-guard 总开关：PAUSE 时让任务自退 │ ├── army-watchdog 出口探活（curl api.anthropic.com） │ └── pm 本地直连：交互对话 PM（同一角色，另一道门） ├── runs.jsonl 执行账本（事实源之一） └── worktrees/&lt;proj&gt;/ Worker 的隔离工作区 </code></pre></div></div> <p><code class="language-plaintext highlighter-rouge">bin/</code> 下所有脚本加起来 <strong>305 行</strong>（<code class="language-plaintext highlighter-rouge">wc -l</code> 实测）。没有 Airflow、没有 Celery/RabbitMQ、没有自建状态机引擎、没有数据库。</p> <p>它的运行模型是<strong>事件式 + 状态外置</strong>：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌─────────────────────────────────────────────────────────────┐ │ 事实源（状态全在这里，不在任何进程的内存里） │ │ │ │ GitHub Issues + Projects ←── 任务/状态（label 路由） │ │ GitHub PR ←── 代码评审载体 │ │ ~/army/projects.yaml ←── 项目注册表（路径/repo/测试）│ │ ~/army/runs.jsonl ←── 执行账本 │ │ ~/army/pyf-docs/ ←── PRD/决策/报告知识库 │ └───────────────────────────┬─────────────────────────────────┘ │ 每次唤起都从这里"水合" ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ army-run-pm army-run-worker army-run-auditor (cwd=~/army, (cwd=worktree, (cwd=项目目录, Opus, 只读) Opus, 可写自分支) Sonnet, 只读) │ │ │ └─ 干完即弃 ────────┴───────────────────┘ （没有常驻 agent；进程跑完就没了，状态早写回事实源） </code></pre></div></div> <p>注意这里<strong>没有常驻的 agent 进程</strong>。PM、Worker、Auditor 都是「唤起 → 从文件/GitHub 把这次需要的状态读进来（水合）→ 干活 → 把结果写回事实源 → 进程退出」。它们之间不靠共享内存、不靠消息传递、不靠长连接对话来协作——它们靠的是<strong>同一份外置事实源</strong>。Worker 开了 PR，这个事实写在 GitHub 上；Auditor 下次被唤起时去 GitHub 读到这个 PR，就知道该审什么。中间没有任何「PM 把消息发给 Worker」的环节。</p> <p>这是从内容自动化项目（tv / bodhi 短剧流水线）里沿用过来的纪律：<strong>记忆在文件里，不在聊天历史里。</strong> 它带来三个直接好处，下一节展开。</p> <p><code class="language-plaintext highlighter-rouge">projects.yaml</code> 是把任务路由到正确工作环境的注册表。每个 project 登记它的路径、repo、worker 画像（<code class="language-plaintext highlighter-rouge">code</code> 走 PR-to-merge / <code class="language-plaintext highlighter-rouge">media</code> 走产物落盘 / <code class="language-plaintext highlighter-rouge">research</code> 走文件级改）和测试命令：</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">projects</span><span class="pi">:</span> <span class="na">cue</span><span class="pi">:</span> <span class="na">department</span><span class="pi">:</span> <span class="s">software</span> <span class="na">worker_type</span><span class="pi">:</span> <span class="s">code</span> <span class="na">path</span><span class="pi">:</span> <span class="s">~/claw/apps/cue</span> <span class="na">repo</span><span class="pi">:</span> <span class="s">pyf-labrary/cue</span> <span class="c1"># push 即 GH Actions 部署</span> <span class="na">test</span><span class="pi">:</span> <span class="s2">"</span><span class="s">npm</span><span class="nv"> </span><span class="s">run</span><span class="nv"> </span><span class="s">test"</span> <span class="na">worktree_base</span><span class="pi">:</span> <span class="s">~/army/worktrees/cue</span> <span class="na">bywork</span><span class="pi">:</span> <span class="na">department</span><span class="pi">:</span> <span class="s">quant</span> <span class="na">worker_type</span><span class="pi">:</span> <span class="s">research</span> <span class="c1"># 非 git repo → 无 PR 流，走文件级 + ledger</span> <span class="na">path</span><span class="pi">:</span> <span class="s">~/bywork</span> <span class="na">repo</span><span class="pi">:</span> <span class="no">null</span> </code></pre></div></div> <p>派活的时候，「切项目」就是「换 Worker 的 <code class="language-plaintext highlighter-rouge">--cwd</code>」——而不是某个全局锁。Worker 一旦 <code class="language-plaintext highlighter-rouge">cd</code> 进项目目录，Claude Code 会自动加载那个项目自己的 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>，于是它立刻拿到该项目的工具链、约定、红线。一份注册表 + cwd 切换，就把「军团能干多少种活」做成了可插拔的——加一个部门 = 在 yaml 里加一行 + 给那个项目写好 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>。</p> <hr /> <h2 id="3-状态机--账本无状态可恢复幂等">3. 状态机 + 账本：无状态、可恢复、幂等</h2> <p>我的宿主是一台 WSL，它会关机、会被 Windows 重启、网络会断。任何依赖「进程一直活着、内存里记着进度」的设计在这种环境下都会碎。所以整套流水线的第一性原理是：<strong>任何一个进程随时可以死，重来一遍不出错。</strong></p> <p>实现它只需要两条规矩：</p> <p><strong>规矩一：状态在 GitHub / 文件，不在内存。</strong> 任务状态机的单一事实源是 GitHub Projects 的 <code class="language-plaintext highlighter-rouge">status</code> 字段，配合 label 路由（<code class="language-plaintext highlighter-rouge">auto-eligible</code> 表示军团可接、<code class="language-plaintext highlighter-rouge">army/triaged</code> 表示 PM 已分诊、<code class="language-plaintext highlighter-rouge">project:&lt;name&gt;</code> 指路由）。状态机长这样：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code> pyf 开 Issue（打 auto-eligible 标） │ ▼ triage ──────────┐ PM 读 + 判断接不接 接 + 拆解 │ │ 不接/缺信息 ▼ ▼ ready blocked（评论说明原因，等 pyf 输入） PM 派工 │ ▼ in-progress ───┐ Worker：改码/测/开 PR + 记账 worker 失败 3× │ ▼ │ review ◀─────┘ Auditor：审 diff + 安全扫 不过 → 评论 + 回 in-progress（worker 修） 过 │ ▼ awaiting-approval 推审批给 pyf pyf 批准 │ ▼ done 合并 PR + 关 Issue（Closes #N 自动关） </code></pre></div></div> <p>进程重启后，dispatcher 不靠记忆重建队列，而是重新 <code class="language-plaintext highlighter-rouge">gh issue list</code> / <code class="language-plaintext highlighter-rouge">gh pr list</code> + 读 Project status，把世界重新拼出来。session-id 映射丢了也无害——下次唤起重新水合即可。</p> <p><strong>规矩二：每个动作执行前先查现态，做成幂等。</strong> 这就是第 0 节那个「PM 对已合并的 Issue#1 no-op」的来历。PM 被唤起处理一个 Issue，第一件事是 <code class="language-plaintext highlighter-rouge">gh issue view</code> 看它现在什么状态；如果已经有开放/已合并的 PR，就不重复派工。Worker 同理：如果该 Issue 已经有开放 PR 了，就不重复开。<code class="language-plaintext highlighter-rouge">briefings</code>/<code class="language-plaintext highlighter-rouge">reports</code> 的幂等键是「日期 + 类型」，存在即更新而非新建。</p> <p>账本是这套机制的可观测面。每个角色干完都调 <code class="language-plaintext highlighter-rouge">army-ledger</code> 追加一行 JSON 到 <code class="language-plaintext highlighter-rouge">runs.jsonl</code>。脚本本身只有几十行，核心是这段 Python：</p> <div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">rec</span> <span class="o">=</span> <span class="p">{</span><span class="s">"ts"</span><span class="p">:</span> <span class="n">datetime</span><span class="p">.</span><span class="n">datetime</span><span class="p">.</span><span class="n">now</span><span class="p">(</span><span class="n">datetime</span><span class="p">.</span><span class="n">timezone</span><span class="p">.</span><span class="n">utc</span><span class="p">).</span><span class="n">isoformat</span><span class="p">(),</span> <span class="s">"role"</span><span class="p">:</span> <span class="n">role</span><span class="p">,</span> <span class="s">"task"</span><span class="p">:</span> <span class="n">task</span><span class="p">}</span> <span class="k">if</span> <span class="n">issue</span><span class="p">:</span> <span class="n">rec</span><span class="p">[</span><span class="s">"issue"</span><span class="p">]</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">issue</span><span class="p">)</span> <span class="k">if</span> <span class="n">issue</span><span class="p">.</span><span class="n">isdigit</span><span class="p">()</span> <span class="k">else</span> <span class="n">issue</span> <span class="k">if</span> <span class="n">duration</span><span class="p">:</span> <span class="n">rec</span><span class="p">[</span><span class="s">"duration_s"</span><span class="p">]</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="n">duration</span><span class="p">)</span> <span class="k">if</span> <span class="n">files</span><span class="p">:</span> <span class="n">rec</span><span class="p">[</span><span class="s">"files_touched"</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">f</span> <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">files</span><span class="p">.</span><span class="n">split</span><span class="p">(</span><span class="s">","</span><span class="p">)</span> <span class="k">if</span> <span class="n">f</span><span class="p">]</span> <span class="k">if</span> <span class="n">result</span><span class="p">:</span> <span class="n">rec</span><span class="p">[</span><span class="s">"result"</span><span class="p">]</span> <span class="o">=</span> <span class="n">result</span> <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">ledger</span><span class="p">,</span> <span class="s">"a"</span><span class="p">)</span> <span class="k">as</span> <span class="n">fh</span><span class="p">:</span> <span class="n">fh</span><span class="p">.</span><span class="n">write</span><span class="p">(</span><span class="n">json</span><span class="p">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">rec</span><span class="p">,</span> <span class="n">ensure_ascii</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">)</span> </code></pre></div></div> <p>为什么是 append-only 的 JSONL 而不是数据库？因为它<strong>跨运行时、可 grep/diff、永久留存、零依赖</strong>。换底座、换模型，账本格式不变，历史可续。我要看的「军团整体健康、token 花在哪、各角色耗时」是跨工具聚合的，单厂 dashboard 给不了。回头看第 0 节那三行账本，字段就很清楚了：</p> <pre><code class="language-jsonl">{... "role": "worker", "issue": 1, "duration_s": 125.0, "result": "ok"} ← 写码 125 秒 {... "role": "auditor", "issue": 1, "duration_s": 90.0, "result": "ok"} ← 审码 90 秒 {... "role": "pm", "task": "...already resolved...no re-dispatch...", "issue": 1, "result": "ok"} ← 幂等 no-op </code></pre> <p><code class="language-plaintext highlighter-rouge">role</code> + <code class="language-plaintext highlighter-rouge">issue</code> 让你能把一单的全生命周期串起来，<code class="language-plaintext highlighter-rouge">duration_s</code> 是真实耗时（不是估的），<code class="language-plaintext highlighter-rouge">result</code> 是 ok/fail。这就是这条流水线的「飞行记录仪」。</p> <hr /> <h2 id="4-一次派工的完整链路把脚本读一遍">4. 一次派工的完整链路：把脚本读一遍</h2> <p>现在把第 0 节那条闭环用代码走一遍。三个脚本，每个都短。</p> <h3 id="41-pm-分诊--派工army-run-pm">4.1 PM 分诊 + 派工（<code class="language-plaintext highlighter-rouge">army-run-pm</code>）</h3> <p>PM 被唤起后干的事，全写在注入给它的 prompt 里：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">prompt</span><span class="o">=</span><span class="s2">"你是 PM，处理 </span><span class="nv">$repo</span><span class="s2"> 的 Issue #</span><span class="nv">$issue</span><span class="s2">（项目 </span><span class="nv">$proj</span><span class="s2">）。 1) gh issue view </span><span class="nv">$issue</span><span class="s2"> --repo </span><span class="nv">$repo</span><span class="s2"> 读它。 2) 分诊：军团能否接、是否清晰可执行。不接/信息不足 → gh issue comment 说明原因，不派工，结束。 3) 接 → gh issue edit </span><span class="nv">$issue</span><span class="s2"> --add-label army/triaged，再派 worker： ~/army/bin/army-run-worker </span><span class="nv">$proj</span><span class="s2"> </span><span class="nv">$issue</span><span class="s2"> </span><span class="nv">$wmodel</span><span class="s2">（建 worktree + 起 worker + 开 PR）。 4) 报告 worker 开的 PR 号 + 一句结论；记 ledger。 铁律：不亲自改代码、不合并 PR（合并是 pyf 审批）。Auditor 由 dispatcher 另行触发，你不用管。"</span> <span class="nv">start</span><span class="o">=</span><span class="si">$(</span><span class="nb">date</span> +%s<span class="si">)</span><span class="p">;</span> <span class="nb">cd</span> ~/army claude <span class="nt">-p</span> <span class="s2">"</span><span class="nv">$prompt</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--append-system-prompt</span> <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ~/army/roles/pm.md<span class="si">)</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--permission-mode</span> default <span class="se">\</span> <span class="nt">--model</span> opus <span class="se">\</span> <span class="nt">--allowedTools</span> Bash Read Grep Glob </code></pre></div></div> <p>几个设计点：</p> <ul> <li><strong><code class="language-plaintext highlighter-rouge">cd ~/army</code></strong> 是有意的——PM 运行在控制面之家，Claude Code 自动加载这里的 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>（组织宪法：服务谁、事实源、红线、工作路径铁律）。Worker/Auditor 运行在别处，拿不到这份，所以靠 <code class="language-plaintext highlighter-rouge">--append-system-prompt</code> 注入角色手册。这是「靠 cwd 拿身份」和「靠注入拿身份」两种手段的分工。</li> <li><strong>PM 派工是直接调下一个脚本</strong> <code class="language-plaintext highlighter-rouge">army-run-worker</code>，不是「发消息给 Worker」。链式调用，进程级编排，没有队列中间件。</li> <li><strong>「分诊」是真判断</strong>：PM 会判定 Issue 信息够不够、军团接不接得了。接不了就 <code class="language-plaintext highlighter-rouge">gh issue comment</code> 说明原因、打住，不硬派。这是把「PM 决策准确率」做成可度量的地方（验收目标是一周 3-5 单、准确率 &gt;80%）。</li> </ul> <h3 id="42-workerworktree-物理隔离--改--测--开-prarmy-run-worker">4.2 Worker：worktree 物理隔离 + 改 + 测 + 开 PR（<code class="language-plaintext highlighter-rouge">army-run-worker</code>）</h3> <p>Worker 脚本最有意思的是 <strong>git worktree</strong> 那一段——它是「多 Worker 并行不打架」的物理基础：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">branch</span><span class="o">=</span><span class="s2">"army/issue-</span><span class="nv">$issue</span><span class="s2">"</span> <span class="nv">wt</span><span class="o">=</span><span class="s2">"</span><span class="nv">$HOME</span><span class="s2">/army/worktrees/</span><span class="nv">$proj</span><span class="s2">/issue-</span><span class="nv">$issue</span><span class="s2">"</span> git <span class="nt">-C</span> <span class="s2">"</span><span class="nv">$path</span><span class="s2">"</span> fetch origin <span class="nt">--quiet</span> <span class="o">||</span> <span class="nb">true</span> <span class="o">[[</span> <span class="nt">-d</span> <span class="s2">"</span><span class="nv">$wt</span><span class="s2">"</span> <span class="o">]]</span> <span class="o">||</span> git <span class="nt">-C</span> <span class="s2">"</span><span class="nv">$path</span><span class="s2">"</span> worktree add <span class="s2">"</span><span class="nv">$wt</span><span class="s2">"</span> <span class="nt">-b</span> <span class="s2">"</span><span class="nv">$branch</span><span class="s2">"</span> origin/main 2&gt;/dev/null <span class="se">\</span> <span class="o">||</span> git <span class="nt">-C</span> <span class="s2">"</span><span class="nv">$path</span><span class="s2">"</span> worktree add <span class="s2">"</span><span class="nv">$wt</span><span class="s2">"</span> <span class="nt">-b</span> <span class="s2">"</span><span class="nv">$branch</span><span class="s2">"</span> </code></pre></div></div> <p>每个 Worker 在 <code class="language-plaintext highlighter-rouge">~/army/worktrees/&lt;proj&gt;/issue-N</code> 下有一份<strong>独立的工作目录 + 独立的分支</strong>，都基于最新的 <code class="language-plaintext highlighter-rouge">origin/main</code> 拉出来。两个 Worker 同时改同一个 repo 的不同 Issue，物理上在两个目录、两条分支，互不污染对方的工作区。这比「同一个 checkout 来回切分支」干净得多——切分支会让正在跑的两个 agent 互相踩脚。</p> <p>然后起 Worker，跑完记账：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cd</span> <span class="s2">"</span><span class="nv">$wt</span><span class="s2">"</span> claude <span class="nt">-p</span> <span class="s2">"</span><span class="nv">$prompt</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--append-system-prompt</span> <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ~/army/roles/worker.md<span class="si">)</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--permission-mode</span> acceptEdits <span class="se">\</span> <span class="nt">--model</span> <span class="s2">"</span><span class="nv">$model</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--allowedTools</span> Bash Edit Write Read Grep Glob <span class="nv">rc</span><span class="o">=</span><span class="nv">$?</span> <span class="nv">dur</span><span class="o">=</span><span class="k">$((</span> <span class="si">$(</span><span class="nb">date</span> +%s<span class="si">)</span> <span class="o">-</span> start <span class="k">))</span> ~/army/bin/army-ledger <span class="nt">--role</span> worker <span class="nt">--issue</span> <span class="s2">"</span><span class="nv">$issue</span><span class="s2">"</span> <span class="nt">--duration</span> <span class="s2">"</span><span class="nv">$dur</span><span class="s2">"</span> <span class="se">\</span> <span class="nt">--result</span> <span class="s2">"</span><span class="si">$(</span><span class="o">[[</span> <span class="nv">$rc</span> <span class="nt">-eq</span> 0 <span class="o">]]</span> <span class="o">&amp;&amp;</span> <span class="nb">echo </span>ok <span class="o">||</span> <span class="nb">echo </span>fail<span class="si">)</span><span class="s2">"</span> <span class="nt">--task</span> <span class="s2">"fix </span><span class="nv">$repo</span><span class="s2">#</span><span class="nv">$issue</span><span class="s2"> (</span><span class="nv">$proj</span><span class="s2">)"</span> </code></pre></div></div> <p>Worker 的 prompt 里钉死了一条红线：<strong>绝不 push 到 main/master，只在本分支开 PR</strong>，PR body 写 <code class="language-plaintext highlighter-rouge">Closes #N</code>（合并即自动关 Issue，这是状态机里「done」那一步的自动化）。<code class="language-plaintext highlighter-rouge">acceptEdits</code> 模式让它能连续改文件而不在每次编辑卡一次人工 ack——因为它在隔离 worktree 里，且最终产物要过 PR 门 + Auditor + 人审三道关，让它在沙盒里自由改是安全的。</p> <h3 id="43-auditor只读-review且改不了代码army-run-auditor">4.3 Auditor：只读 review，且改不了代码（<code class="language-plaintext highlighter-rouge">army-run-auditor</code>）</h3> <p>Auditor 的核心已经在第 1 节讲过——白名单没有 Edit/Write。它的 prompt 里还藏了一个真实踩过的坑：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">prompt</span><span class="o">=</span><span class="s2">"审查 PR #</span><span class="nv">$pr</span><span class="s2">（仓 </span><span class="nv">$repo</span><span class="s2">）。 1) gh pr view + gh pr diff 看改动，对照它要修的问题。 2) 审：修复是否正确、是否最小化、有无副作用/回归、安全（无注入/泄密/越权/误删）。 3) 结论用 gh pr comment 写回（用 comment，不要 review --approve， 因作者同账号会被 GitHub 拒）：通过写「LGTM」+ 理由；有问题写「⚠️」+ 逐条列出。 SoD 铁律：你只读——不改任何代码、不 merge PR（合并是 pyf 的审批）。"</span> </code></pre></div></div> <p>那个坑是：当前 Worker 和 Auditor 用的是<strong>同一个 GitHub bot 账号</strong>，GitHub 不允许 PR 作者 approve 自己的 PR。所以 Auditor 走的是 <code class="language-plaintext highlighter-rouge">gh pr comment</code> 写结论，而不是 <code class="language-plaintext highlighter-rouge">gh pr review --approve</code>。这是「身份分离没做到底」留下的一个真实约束，我把它记在了技术债清单里（见第 6 节）——要彻底分权，得给 Auditor 单开一个 bot 账号。</p> <p>注意 Auditor <strong>不合并 PR</strong>。即使它评了 LGTM，合并这一下永远是我（人）来点。这是流水线里唯一一个永远保留的人工闸——也是「awaiting-approval → done」那一步。整条流水线我把人工干预收敛到了这一个点上。</p> <hr /> <h2 id="5-安全硬约束--软约束">5. 安全：硬约束 &gt; 软约束</h2> <p>这条流水线敢「放手让 agent 自己改代码、自己开 PR」，前提是有几道闸拦住它干蠢事。我把安全分成三个层次，<strong>确定性的优先级永远高于概率性的</strong>。</p> <p><strong>第一层：工具白名单（确定性，已落地）。</strong> 前面讲过——Auditor/PM 没有 Edit/Write，结构上改不了代码。这是数学上拦得住的。</p> <p><strong>第二层：总开关（确定性，已落地）。</strong> 每个脚本第一行都是 <code class="language-plaintext highlighter-rouge">~/army/bin/army-guard || exit 0</code>。guard 读 <code class="language-plaintext highlighter-rouge">~/.army-state</code>，是 <code class="language-plaintext highlighter-rouge">PAUSE</code> 就让调用方自己 skip。一条命令停全军：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">echo </span>PAUSE <span class="o">&gt;</span> ~/.army-state <span class="c"># 紧急停</span> <span class="nb">echo </span>RUN <span class="o">&gt;</span> ~/.army-state <span class="c"># 恢复（或删掉文件）</span> </code></pre></div></div> <p>配套有一个 <code class="language-plaintext highlighter-rouge">army-watchdog</code>，curl 探 <code class="language-plaintext highlighter-rouge">api.anthropic.com</code>，探不到（出口代理挂了）就记日志退 1。</p> <p><strong>第三层：红线规则（规划中，目前靠软约束 + 人审兜底）。</strong> 我写了一份 runtime-无关的红线 spec，列了「永远要人 ack」的硬规则：push main/master、改 <code class="language-plaintext highlighter-rouge">.env</code>/secret/删 prod、≥10MB 二进制进站点、跳过内容合规备案等等。它的设计意图是<strong>编译成 Claude Code 的 PreToolUse hook</strong>，用硬编码 regex 在工具执行前拦——因为 LLM 是概率性的，「在 prompt 里写了别 push main」是软约束（可能不遵守、可能被任务诱导绕过、可能幻觉），而 hook 是确定性的。</p> <p>但我要诚实：<strong>这层红线 hook 现在还没挂上。</strong> 当前 Worker 守红线靠的是三道软兜底——<code class="language-plaintext highlighter-rouge">roles/worker.md</code> 里的角色手册约束 + PR 门（它只能开 PR 不能直接合）+ 我最后人审。在挂上 hard hook 之前，我不会把它切到无人值守。而且红线 hook 上线策略也写死了「第一周只 log 不拦」——一个误判会卡死整条流水线，得先观察确认无误报再切真拦。</p> <blockquote> <p>这三层的取舍逻辑：<strong>能确定性拦的（白名单、总开关）现在就硬拦；要等 hook 才能确定性拦的（红线），在它就位前宁可用「软约束 + 收窄能力 + 人审」三重兜底压着，也不放开无人值守。</strong> 安全这件事上，「还没做到的部分」必须当成「还没安全」对待，而不是「prompt 写了应该没事」。</p> </blockquote> <hr /> <h2 id="6-当前真实状态哪些跑通了哪些还没">6. 当前真实状态：哪些跑通了，哪些还没</h2> <p>技术博客最容易翻车的地方是把 demo 吹成生产。这一节专门划清楚边界。</p> <p><strong>已经是能跑的实物（不是图纸）：</strong></p> <ul> <li><code class="language-plaintext highlighter-rouge">~/army/</code> 控制面骨架全部就位：组织宪法 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>、三份角色手册、项目注册表、<code class="language-plaintext highlighter-rouge">bin/</code> 下 8 个脚本（共 305 行）、账本、知识库脚手架。</li> <li>三角色（PM/Worker/Auditor）都在<strong>真实 bug</strong>（cue Issue#1）上端到端验证过，PR#2 已合并。</li> <li>工具白名单 SoD、git worktree 隔离、<code class="language-plaintext highlighter-rouge">runs.jsonl</code> 账本、<code class="language-plaintext highlighter-rouge">army-guard</code> 总开关——这几样是实打实在用的。</li> <li>PM 的幂等：对已合并的 Issue 正确 no-op，核了 GitHub + 账本两个事实源。</li> </ul> <p><strong>还没做完（按我自己的路线图，诚实列出）：</strong></p> <ul> <li><strong>dispatcher 仍是 DRY 模式。</strong> <code class="language-plaintext highlighter-rouge">army-dispatch</code> 这个 poller 现在默认只「<code class="language-plaintext highlighter-rouge">gh</code> 查 + 记日志，不真起 PM」（防止意外烧 token），要 <code class="language-plaintext highlighter-rouge">ARMY_DISPATCH_LIVE=1</code> 才真唤起。也就是说目前每一单仍是我手动 <code class="language-plaintext highlighter-rouge">army-run-pm &lt;proj&gt; &lt;N&gt;</code> 触发的，<strong>自动接单的最后一根线还没接通</strong>。</li> <li><strong>Auditor 还靠手动触发。</strong> poller 里「发现 review 态新 PR → 自动唤 Auditor」这条路径还没写，当前是我手动 <code class="language-plaintext highlighter-rouge">army-run-auditor</code>。</li> <li><strong>红线 hard hook 没挂。</strong> 见第 5 节——无人值守前必须先挂上（log-only 先行）。</li> <li><strong>Telegram 桥 + systemd 常驻没接。</strong> 设计里 PM 应该能收 Telegram 的 <code class="language-plaintext highlighter-rouge">@PM</code> ping、审批走 IM 卡片，dispatcher 应该是 systemd 用户服务定时跑。这两样都还没落地（systemd unit 这台机器上目前也确实没装）。换句话说，<strong>它现在是一套「手动触发也能跑通全闭环」的流水线，但还不是 24h 无人值守的常驻系统。</strong></li> </ul> <p><strong>技术债（小但真实）：</strong></p> <ul> <li>Worker 的 ledger 记了两遍（角色手册自记 + 包装脚本记），该二选一。</li> <li>凭据管理：项目 remote 一律走 SSH / 凭据助手，别让 token 明文落进 <code class="language-plaintext highlighter-rouge">.git/config</code>。</li> <li>Worker 的 worktree 在 <code class="language-plaintext highlighter-rouge">~/army/worktrees/</code> 下、不在项目树内，拿不到工作区根的 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>（只能拿项目自身那份）——需要时用 <code class="language-plaintext highlighter-rouge">--add-dir</code> 补。</li> <li>Auditor 与 Worker 同 bot 账号，导致前面那个「不能 self-approve、只能 comment」的妥协——要彻底分权得单开账号。</li> </ul> <p>把这些列出来不是给自己挑刺，而是因为<strong>一套自动开发流水线真正的难点恰恰在这些边角</strong>：身份分离、凭据管理、幂等、续跑、误判防护。能跑通一个 happy-path demo 不难，难的是把这些边角逐个收口到敢无人值守。这份清单就是从 demo 到生产之间还差的路。</p> <hr /> <h2 id="7-为什么没上-airflow--没自建编排框架">7. 为什么没上 Airflow / 没自建编排框架</h2> <p>最后回到最初那个判断，把它讲透。一开始我也考虑过更「正经」的方案——上一篇方法论文里甚至画过 13 个 agent 槽位 + Sentry + Grafana + canary 的团队版大图。落到单人个人项目时我全砍了，理由是：</p> <p><strong>Claude Code 原生就给了搭多 agent 编排所需的全部机制：</strong></p> <ul> <li><code class="language-plaintext highlighter-rouge">claude -p</code> headless 模式 = 可脚本化唤起的 agent 进程；</li> <li><code class="language-plaintext highlighter-rouge">--append-system-prompt</code> = 给同一个底座注入不同角色身份；</li> <li><code class="language-plaintext highlighter-rouge">--allowedTools</code> = 确定性的权限隔离（SoD 的结构保证）；</li> <li><code class="language-plaintext highlighter-rouge">--model</code> per-task = 模型分层旋钮（判断用 Opus、审查用 Sonnet）；</li> <li>PreToolUse hook = 硬红线所需的确定性闸门（待挂）；</li> <li>加载 cwd 的 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code> = 每个项目自带工具链/约定/红线。</li> </ul> <p>剩下要我「自己搭」的，<strong>根本不是 agent loop、不是工具执行器、不是记忆引擎</strong>——那些借底座的就好。要搭的只是一层薄胶水：项目注册表（一份 yaml）、三个唤起脚本（链式调用，进程级编排）、一个账本（append JSONL）、一个总开关（读一个文件）。状态机的事实源直接用 GitHub Issues/PR/Projects——它本来就是工程团队的工单池 + 评审台 + 看板，免费、有 API、零运维。</p> <blockquote> <p>一句话总结这个取舍：<strong>编排框架（Airflow/队列/状态机引擎）解决的是「进程怎么调度、状态存哪、消息怎么传」——但当你把状态全外置到 GitHub + 文件、让每个 agent 干完即弃、用进程链式调用替代消息传递时，这些问题根本不出现，于是框架也就不需要了。</strong> 300 行脚本不是「简陋版的 Airflow」，它是一个<strong>根本不需要 Airflow 的架构</strong>。</p> </blockquote> <p>这也是我最想留给读者的工程判断：搭多 agent 自动开发流水线，先别急着选编排框架。先把三件事想清楚——<strong>职责怎么分权（用白名单，不用 prompt）、状态放哪（外置到 GitHub/文件，别留内存）、安全闸怎么确定性化（hook/白名单，不靠模型自觉）</strong>。这三样想透了，剩下的胶水可能比你以为的薄得多。</p> <hr /> <h2 id="附复现这套的最小清单">附：复现这套的最小清单</h2> <p>如果你想照着搭一套自己的：</p> <ol> <li><strong>底座</strong>：Claude Code，登录订阅跑（headless <code class="language-plaintext highlighter-rouge">claude -p</code>），边际成本压到接近零。</li> <li><strong>事实源</strong>：GitHub repo + Issues + Projects + 一份 <code class="language-plaintext highlighter-rouge">projects.yaml</code> + 一个 append-only <code class="language-plaintext highlighter-rouge">runs.jsonl</code>。状态全往这里放。</li> <li><strong>三个唤起脚本</strong>：PM（<code class="language-plaintext highlighter-rouge">--allowedTools Bash Read Grep Glob</code>，cwd=控制面之家）、Worker（加 <code class="language-plaintext highlighter-rouge">Edit Write</code> + <code class="language-plaintext highlighter-rouge">acceptEdits</code> + git worktree 隔离）、Auditor（去掉 <code class="language-plaintext highlighter-rouge">Edit Write</code>，结构上只读）。链式调用，不上队列。</li> <li><strong>总开关</strong>：每个脚本第一行读一个 state 文件，<code class="language-plaintext highlighter-rouge">PAUSE</code> 就自退。</li> <li><strong>红线</strong>：写一份 runtime-无关的硬规则 spec，编译成 PreToolUse hook，<strong>先 log-only 一周</strong>再切真拦。无人值守前必挂。</li> <li><strong>验收</strong>：拿真实的低风险 bug（P3/cosmetic）开练，目标一周跑通 3-5 单、PM 决策准确率 &gt;80%，再逐步把 dispatcher 从 DRY 切 LIVE、把 Auditor 自动化、接 IM 审批。</li> </ol> <p>别一上来就追无人值守。先让「手动触发也能跑通全闭环」稳定下来——那已经是把 AI 从「单兵 Copilot」毕业成「会自己分诊、写码、自审、走流程」的流水线了。后面那几根线（自动接单、IM 审批、常驻）是锦上添花，不是地基。</p>

约 300 行脚本、不靠编排框架，用 Claude Code headless 把 Issue→PR→merge 串成 agent 间零人工干预的流水线；附真实运行账本与设计取舍。

2026-05-25T04:00:00+00:00 2026-05-25T04:00:00+00:00 https://jinzi.cyou/posts/android-adb-agent-capabilities <blockquote> <p>一份关于”用 ADB 通道 + 多模态大模型（Agent）操控 Android 手机”的能力边界研究。 整理自一次技术调研会话，含豆包 AI 手机（UI-TARS）的实现原理对照、ADB 各项能力的可行性分级、以及”一键换机”等高阶目标的现实约束。</p> <p>日期：2026-05-25</p> </blockquote> <hr /> <h2 id="目录">目录</h2> <ol> <li><a href="#1">两条技术路线：ADB 调试通道 vs 系统级 GUI Agent</a></li> <li><a href="#2">ADB 能给 Agent 带来哪些能力</a></li> <li><a href="#3">豆包 AI 手机怎么用多模态大模型操控手机（UI-TARS）</a></li> <li><a href="#4">App 权限管控、装卸、文件整理的可行性</a></li> <li><a href="#5">“从应用商店下载安装”为什么是个坎</a></li> <li><a href="#6">“一键换机 / 完整克隆”的现实边界</a></li> <li><a href="#7">能力总表与选型建议</a></li> </ol> <hr /> <p><a id="1"></a></p> <h2 id="1-两条技术路线adb-调试通道-vs-系统级-gui-agent">1. 两条技术路线：ADB 调试通道 vs 系统级 GUI Agent</h2> <p>让 Agent 操控一部 Android 手机，业界存在两条本质不同的路：</p> <table> <thead> <tr> <th>维度</th> <th><strong>ADB / 无障碍</strong>（开发者可走）</th> <th><strong>系统级 GUI Agent</strong>（豆包手机一类）</th> </tr> </thead> <tbody> <tr> <td>感知</td> <td>uiautomator 控件树（结构化、精确）+ 截图</td> <td>纯屏幕截图视觉识别</td> </tr> <tr> <td>决策</td> <td>外部通用多模态模型看图 + 控件树后给坐标</td> <td>端到端 GUI 专用模型直出动作</td> </tr> <tr> <td>执行</td> <td><code class="language-plaintext highlighter-rouge">adb shell input</code> / Accessibility 注入事件</td> <td>系统级 <code class="language-plaintext highlighter-rouge">INJECT_EVENTS</code> 注入</td> </tr> <tr> <td>权限门槛</td> <td>开发者调试 / 无障碍授权即可</td> <td>需要 ROM 级权限，刷工程机</td> </tr> <tr> <td>部署形态</td> <td>电脑端连手机，外部驱动</td> <td>嵌入操作系统，本机运行</td> </tr> </tbody> </table> <p>两条路殊途同归——都是”<strong>看屏幕 → 推理 → 像人一样点击</strong>“的闭环。区别在于执行层走的是调试通道还是系统注入，以及模型是通用多模态还是专门为 GUI 操作训练过的。</p> <p><strong>关键结论</strong>：用 <code class="language-plaintext highlighter-rouge">ADB + 截图喂给多模态模型 + uiautomator 控件树</code>，本质能复刻豆包那套交互闭环，只是执行层走调试通道而非系统注入。这是个人开发者 / Agent 项目最现实的落地路径。</p> <blockquote> <p>环境提示：在 WSL2 里连真机，一般还需要桥接 Windows 侧的 adb server，或走 usbipd / 网络 adb（<code class="language-plaintext highlighter-rouge">adb tcpip</code> 无线调试）。</p> </blockquote> <hr /> <p><a id="2"></a></p> <h2 id="2-adb-能给-agent-带来哪些能力">2. ADB 能给 Agent 带来哪些能力</h2> <p>接入 ADB 后，Agent 获得的能力可按用途分为五类：</p> <h3 id="21-屏幕操控--ui-自动化">2.1 屏幕操控 / UI 自动化</h3> <ul> <li><code class="language-plaintext highlighter-rouge">adb shell input tap/swipe/text/keyevent</code> —— 点击、滑动、输入文字、按键，脚本化操控任意 App</li> <li><code class="language-plaintext highlighter-rouge">adb exec-out screencap -p</code> —— 截屏（多模态模型可直接读图分析画面）</li> <li><code class="language-plaintext highlighter-rouge">adb shell uiautomator dump</code> —— 拉当前界面控件树（坐标 / 文本 / resource-id），做<strong>视觉 + 结构双通道</strong>自动化，比盲点坐标稳得多</li> <li><code class="language-plaintext highlighter-rouge">adb shell screenrecord</code> —— 原生录屏成 mp4</li> <li>配合 <code class="language-plaintext highlighter-rouge">scrcpy</code> 可实时镜像 + 鼠标键盘控制</li> </ul> <h3 id="22-app--包管理">2.2 App / 包管理</h3> <ul> <li><code class="language-plaintext highlighter-rouge">install / uninstall / pm list packages</code> —— 装卸 APK、枚举包名</li> <li><code class="language-plaintext highlighter-rouge">pm clear</code> 清数据、<code class="language-plaintext highlighter-rouge">am start/force-stop</code> 起停 Activity、<code class="language-plaintext highlighter-rouge">am broadcast</code> 发广播</li> <li><code class="language-plaintext highlighter-rouge">dumpsys</code>（battery/meminfo/activity/window）—— 抓性能、当前栈、内存</li> </ul> <h3 id="23-文件--数据">2.3 文件 / 数据</h3> <ul> <li><code class="language-plaintext highlighter-rouge">adb push/pull</code> —— 双向传文件</li> <li><code class="language-plaintext highlighter-rouge">adb shell run-as &lt;pkg&gt;</code> —— <strong>仅 debuggable 包</strong>下读自家沙盒数据（SQLite / SharedPrefs）</li> </ul> <h3 id="24-日志--调试">2.4 日志 / 调试</h3> <ul> <li><code class="language-plaintext highlighter-rouge">adb logcat</code> —— 实时日志，定位崩溃 / 报错（带 tag/level 过滤）</li> <li><code class="language-plaintext highlighter-rouge">adb bugreport</code>、<code class="language-plaintext highlighter-rouge">adb shell getprop</code> —— 设备信息、系统属性</li> <li><code class="language-plaintext highlighter-rouge">adb forward / reverse</code> —— 端口转发，把手机内服务映射到本机调试，或反向让 App 访问本机 server</li> </ul> <h3 id="25-设备管理">2.5 设备管理</h3> <ul> <li>多设备并行（<code class="language-plaintext highlighter-rouge">-s &lt;serial&gt;</code>）、<code class="language-plaintext highlighter-rouge">adb tcpip</code> 无线调试、<code class="language-plaintext highlighter-rouge">reboot</code>、<code class="language-plaintext highlighter-rouge">wm size/density</code> 改分辨率</li> </ul> <h3 id="对项目的实际价值">对项目的实际价值</h3> <ul> <li><strong>取代 / 补充 Playwright</strong> —— 测原生 Android App（不只是网页）的 UI 流程</li> <li><strong>素材采集</strong> —— 手机端录屏 / 截屏直接进内容流水线</li> <li><strong>真机内容自动化</strong> —— 操控各类 App，绕开纯 web 接口的限制</li> </ul> <hr /> <p><a id="3"></a></p> <h2 id="3-豆包-ai-手机怎么用多模态大模型操控手机ui-tars">3. 豆包 AI 手机怎么用多模态大模型操控手机（UI-TARS）</h2> <p>核心一句话：<strong>豆包手机不是靠 API 或读控件树，而是把”看屏幕截图 → 推理 → 像人一样点屏幕”这套闭环交给一个端到端多模态大模型（字节的 UI-TARS）来做。</strong></p> <h3 id="31-感知纯视觉截图当唯一输入">3.1 感知：纯视觉，截图当唯一输入</h3> <ul> <li>不解析 App 接口，也不主要依赖无障碍控件树，而是<strong>每隔约 3 秒抓一张当前屏幕截图</strong>喂给视觉语言模型（VLM），由模型从像素里识别按钮、输入框、目标位置——和人眼看屏幕一样。</li> <li><strong>过滤式视觉管道</strong>：抓的是目标 App 的 Activity Hierarchy 渲染结果，不是直接读整个 Display Buffer，因此物理上看不到后台（如视频通话）内容，是一项隐私设计。</li> </ul> <h3 id="32-推理react-范式--分层记忆">3.2 推理：ReAct 范式 + 分层记忆</h3> <p>模型按 <strong>推理(Reason) → 行动(Act) → 观察(Observe)</strong> 三步循环运行：</p> <ul> <li><strong>工作记忆</strong>保存近几步操作（快反应，System 1）</li> <li><strong>情景记忆</strong>做语义压缩存长程上下文（深推理，System 2）</li> <li>这样能撑住”打开美团 → 搜店 → 比价 → 加购 → 下单”这种多步跨 App 任务，而非只会单步点击。</li> </ul> <h3 id="33-动作统一动作空间">3.3 动作：统一动作空间</h3> <p>模型输出的不是文字，而是<strong>结构化操作原语</strong>：<code class="language-plaintext highlighter-rouge">tap(x,y) / type(text) / swipe / 长按 / 返回</code>，并扩展到文件系统操作、终端命令、MCP 工具调用。</p> <ul> <li>坐标级操作落到系统上，靠 <strong><code class="language-plaintext highlighter-rouge">INJECT_EVENTS</code> 系统级权限</strong>（注入触摸 / 按键事件）——这正是它做成”系统级 AI 手机”、需要刷工程机的原因。普通第三方 App 拿不到这个权限，只能退而用无障碍服务。</li> </ul> <h3 id="34-端云协同">3.4 端云协同</h3> <ul> <li><strong>标准模式</strong>：浅层 VLM，响应快</li> <li><strong>Pro 模式</strong>：云端大模型深度推理 + 工具调用，更强但慢</li> <li>主算力在云端（截图上传云端 VLM 解析）。</li> <li>后台跑任务时起一个<strong>虚拟显示层（影子屏幕）</strong>，让 Agent 在不打断前台操作的情况下并行干活。</li> </ul> <h3 id="35-安全">3.5 安全</h3> <p>敏感动作（支付、身份验证、密码）<strong>自动暂停，转人工接管</strong>。</p> <h3 id="36-模型怎么练出来的ui-tars">3.6 模型怎么练出来的（UI-TARS）</h3> <ul> <li>三阶段管道：海量教程 / 操作截图<strong>持续预训练(CT)</strong> → 高质量指令<strong>SFT</strong> → <strong>强化学习(RL)</strong> 端到端优化。</li> <li>关键数据：标注员录下操作时的”有声思维”（为什么点这里），还能在模型实时采样时<strong>在线干预纠偏</strong>。</li> <li>成绩：开源版 UI-TARS-1.5-7B 在 AndroidWorld 等 7 项 GUI 基准刷新 SOTA（AndroidWorld 46.6 vs GPT-4o 34.5；OSWorld 超过 Claude），是 GitHub 热榜榜首项目，开源后超 26k Star。UI-TARS 已迭代到 2.0，支持 GUI 操作到代码执行、API 调用的混合动作流。豆包手机用的是闭源版，针对 Mobile Use 做了大量优化。</li> </ul> <hr /> <p><a id="4"></a></p> <h2 id="4-app-权限管控装卸文件整理的可行性">4. App 权限管控、装卸、文件整理的可行性</h2> <h3 id="41-app-权限管控--完全可以">4.1 App 权限管控 ✅ 完全可以</h3> <p>ADB 直接走 <code class="language-plaintext highlighter-rouge">pm</code>（PackageManager），能读能改运行时权限：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 看某 App 当前所有权限及授予状态</span> adb shell dumpsys package com.xxx.app | <span class="nb">grep </span>permission <span class="c"># 授予 / 撤销单个权限（运行时权限，立即生效，无需重装）</span> adb shell pm grant com.xxx.app android.permission.CAMERA adb shell pm revoke com.xxx.app android.permission.ACCESS_FINE_LOCATION <span class="c"># appops 更细：控制后台弹窗、读剪贴板、悬浮窗、自启等"特殊操作"</span> adb shell appops <span class="nb">set </span>com.xxx.app SYSTEM_ALERT_WINDOW deny adb shell appops get com.xxx.app <span class="c"># 列出该 App 所有 op 状态</span> </code></pre></div></div> <ul> <li>能批量做”隐私体检”：扫所有 App 谁拿了麦克风 / 定位 / 通讯录，一键收权。</li> <li><strong>限制</strong>：<code class="language-plaintext highlighter-rouge">pm grant</code> 只能改 manifest 里声明过 <code class="language-plaintext highlighter-rouge">dangerous</code> 级的运行时权限；签名级 / 系统级权限改不了（要 root）。</li> </ul> <h3 id="42-装--卸-app--可以">4.2 装 / 卸 App ✅ 可以</h3> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>adb <span class="nb">install </span>app.apk <span class="c"># 装本地 APK</span> adb <span class="nb">install</span> <span class="nt">-r</span> <span class="nt">-d</span> app.apk <span class="c"># 覆盖安装 / 允许降级</span> adb install-multiple <span class="k">*</span>.apk <span class="c"># split APK（AAB 拆出来的）</span> adb uninstall com.xxx.app <span class="c"># 卸载</span> adb uninstall <span class="nt">-k</span> com.xxx.app <span class="c"># 卸载但保留数据</span> adb shell pm uninstall <span class="nt">--user</span> 0 com.xxx.app <span class="c"># 卸预装/系统应用（免 root，仅当前用户）</span> </code></pre></div></div> <p><strong>关键的坎</strong>：ADB 只能装<strong>你已经有的 APK 文件</strong>，不会”去应用商店下载”——详见第 5 章。</p> <h3 id="43-文件整理--可以等于半个-shell">4.3 文件整理 ✅ 可以，等于半个 shell</h3> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>adb push 本地 /sdcard/目标/ <span class="c"># 传进去</span> adb pull /sdcard/DCIM/ ./备份/ <span class="c"># 拉出来</span> adb shell <span class="nb">ls</span> <span class="nt">-R</span> /sdcard/Download <span class="c"># 浏览</span> adb shell <span class="nb">mv</span> / <span class="nb">cp</span> / <span class="nb">rm</span> / <span class="nb">mkdir</span> ... <span class="c"># 移动、复制、删、建目录</span> adb shell find /sdcard <span class="nt">-name</span> <span class="s2">"*.mp4"</span> <span class="nt">-size</span> +50M <span class="c"># 按条件筛</span> </code></pre></div></div> <ul> <li>完全能写脚本做”按类型归类相册 / 清理下载目录 / 批量重命名”。</li> <li><strong>限制</strong>：免 root 时只能动<strong>共享存储</strong>（<code class="language-plaintext highlighter-rouge">/sdcard</code>、公共目录）和 debug 包自己的沙盒；别的 App 私有目录 <code class="language-plaintext highlighter-rouge">/data/data/&lt;pkg&gt;/</code> 读不了（要 root 或该包是 debuggable + <code class="language-plaintext highlighter-rouge">run-as</code>）。</li> </ul> <hr /> <p><a id="5"></a></p> <h2 id="5-从应用商店下载安装为什么是个坎">5. “从应用商店下载安装”为什么是个坎</h2> <p><strong>ADB 没有”从 Play Store 直接下载安装”的原生命令</strong>——Google 故意不开这个口。Play Store 没有公开的 CLI / API 让你 <code class="language-plaintext highlighter-rouge">adb install 包名</code> 就从云端拉下来装。<code class="language-plaintext highlighter-rouge">adb install</code> 永远只吃<strong>本地 APK 文件</strong>。</p> <p>曲线达成有三条路，按”接近直接”排序：</p> <h3 id="路线-1intent-打开商店页--自动点安装最接近直接最稳妥">路线 1：intent 打开商店页 + 自动点”安装”（最接近”直接”，最稳妥）</h3> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 直接跳到某 App 的 Play Store 详情页</span> adb shell am start <span class="nt">-a</span> android.intent.action.VIEW <span class="nt">-d</span> <span class="s2">"market://details?id=com.spotify.music"</span> <span class="c"># 然后截图找到"安装"按钮，注入点击</span> adb shell input tap &lt;x&gt; &lt;y&gt; </code></pre></div></div> <ul> <li>本质就是豆包那套 GUI 自动化：让模型看屏幕、点”安装”、等下载。下载和安装都由商店自己完成（合法、走正常签名校验、账号正常）。</li> <li>缺点是要”看屏点击”，不是一条命令搞定。装 APK 时还会弹<strong>系统确认框</strong>，需要再 <code class="language-plaintext highlighter-rouge">input</code> 点一下”安装”，或提前 <code class="language-plaintext highlighter-rouge">adb shell settings</code> 放行未知来源。</li> </ul> <h3 id="路线-2第三方-play-store-api-客户端全自动但有账号风险">路线 2：第三方 Play Store API 客户端（全自动，但有账号风险）</h3> <p>有开源工具逆向了 Play Store 私有协议，用 Google 账号<strong>直接从 Google 服务器抓 APK</strong>：<code class="language-plaintext highlighter-rouge">gplaycli</code>（命令行）、<code class="language-plaintext highlighter-rouge">Raccoon</code>（PC）、<code class="language-plaintext highlighter-rouge">Aurora Store</code>（手机端）。</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gplaycli <span class="nt">-d</span> com.spotify.music <span class="c"># 用账号从 Play 拉 APK 到本地</span> adb <span class="nb">install </span>com.spotify.music.apk <span class="c"># 再装进去</span> </code></pre></div></div> <ul> <li><strong>代价</strong>：非官方协议，<strong>违反 Play 服务条款</strong>，账号有被风控 / 封的风险（建议用小号），付费 App / 区域锁的拉不了。</li> </ul> <h3 id="路线-3managed-google-play--emm-api官方但有门槛">路线 3：Managed Google Play / EMM API（官方但有门槛）</h3> <p>企业 MDM 场景，Google 提供官方 API 远程给托管设备静默推送安装。需把设备纳管成”企业管理设备”，个人用不上。</p> <p><strong>结论</strong>：正规、稳妥的方式是<strong>路线 1</strong>——ADB 负责”导航 + 点击”，商店负责”下载 + 安装”。这也正是 AI 手机做”一句话装 App”的真实路径：它不是绕过商店，而是替你操作商店。</p> <hr /> <p><a id="6"></a></p> <h2 id="6-一键换机--完整克隆的现实边界">6. “一键换机 / 完整克隆”的现实边界</h2> <p>能做到<strong>部分克隆</strong>，但”尽可能复制完整状态（含各 App 登录态 / 存档 / 系统密钥）”——<strong>纯 ADB 无 root 做不到</strong>。卡点不是 ADB 弱，而是 Android 的沙盒安全模型。</p> <h3 id="61-adb-无-root-能搬的-">6.1 ADB 无 root 能搬的 ✅</h3> <p>| 类别 | 命令 | 说明 | |—|—|—| | 共享存储文件 | <code class="language-plaintext highlighter-rouge">adb pull /sdcard ./backup</code> | 照片 / 视频 / 下载 / 文档全量拷 | | 已装 App 清单 | <code class="language-plaintext highlighter-rouge">adb shell pm list packages -3</code> | 拿到所有第三方包名 | | APK 本体 | <code class="language-plaintext highlighter-rouge">adb shell pm path com.x</code> → <code class="language-plaintext highlighter-rouge">pull</code> | 把安装包抠出来搬到新机重装 | | 部分系统设置 | <code class="language-plaintext highlighter-rouge">adb shell settings get/put system\|secure\|global</code> | ADB 持 <code class="language-plaintext highlighter-rouge">WRITE_SECURE_SETTINGS</code>，能搬亮度、字体、动画、无障碍、默认输入法等 |</p> <p>→ 能拼出”文件 + 把同样的 App 都装上 + 还原一批系统偏好”的迁移脚本。</p> <h3 id="62-adb-无-root-搬不了的-这才是换机的核心">6.2 ADB 无 root 搬不了的 ❌（这才是”换机”的核心）</h3> <ul> <li><strong>App 私有数据</strong> <code class="language-plaintext highlighter-rouge">/data/data/&lt;包名&gt;/</code>：登录态、聊天记录、游戏存档、App 内设置——<strong>全在这儿，无 root 一律读不到</strong>。<code class="language-plaintext highlighter-rouge">run-as</code> 只对 debuggable 开发版有效，商店装的正式版无效。</li> <li><strong>系统级密钥</strong>：WiFi 密码、账户凭据、指纹 / 人脸模板、Keystore——受保护存储，碰不到。</li> <li><strong><code class="language-plaintext highlighter-rouge">adb backup</code> / <code class="language-plaintext highlighter-rouge">adb restore</code></strong>：老接口看着像答案，但<strong>已基本废弃</strong>——Android 12 起大量失效，App 默认 <code class="language-plaintext highlighter-rouge">allowBackup=false</code>，备出来多半是空的，别指望它。</li> </ul> <p><strong>一句话</strong>：无 root 只能搬”东西”（文件 + App 安装包 + 部分设置），搬不了”状态”（每个 App 的数据和你的登录）。装好的微信打开还是要重新扫码登录。</p> <h3 id="63-想要真完整克隆--两条路">6.3 想要真·完整克隆 → 两条路</h3> <p><strong>A. Root / 解锁 BL（技术上最彻底）</strong></p> <ul> <li>root 后可整包 tar <code class="language-plaintext highlighter-rouge">/data</code> 分区，或 TWRP 做 nandroid 全镜像，App 数据一并搬。</li> <li>代价：解锁 bootloader <strong>会清空设备</strong>、掉保修、可能触发 App 风控（银行 / 支付检测 root 拒启）、新旧机型号不同还原易崩。不推荐做日常方案。</li> </ul> <p><strong>B. 厂商”一键换机”（最省心，也是该功能的真实来源）</strong></p> <ul> <li>三星 Smart Switch / 小米·换机 / 华为手机克隆 / Google 开机迁移——它们<strong>不是 ADB</strong>。</li> <li>原理：这些是<strong>预装的系统级签名 App</strong>，持有普通 App 和 ADB 都拿不到的特殊备份权限，能直接读全机 App 数据；再叠加 Google / 厂商云端的 App 数据备份（开发者 opt-in 的那部分）。</li> <li>所以”一键全搬”靠的是<strong>系统特权 + 云备份</strong>，第三方（含 ADB）从设计上就被挡在外面。</li> </ul> <h3 id="64-建议">6.4 建议</h3> <ul> <li>真要”尽可能复制手机状态”：<strong>同品牌换机用厂商工具</strong>最优；跨品牌用目标厂商的克隆 App。</li> <li>ADB 的定位是<strong>补漏和定制</strong>：厂商工具漏掉的、或想脚本化精确控制的（批量还原某类设置、把特定目录归类搬运、复刻 App 安装清单），用 ADB 脚本补上。</li> </ul> <hr /> <p><a id="7"></a></p> <h2 id="7-能力总表与选型建议">7. 能力总表与选型建议</h2> <h3 id="adb-各项能力可行性分级">ADB 各项能力可行性分级</h3> <table> <thead> <tr> <th>能力</th> <th style="text-align: center">ADB 免 root</th> <th style="text-align: center">ADB + root</th> <th style="text-align: center">厂商工具</th> <th>卡点</th> </tr> </thead> <tbody> <tr> <td>屏幕操控 / UI 自动化</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">—</td> <td>—</td> </tr> <tr> <td>截屏 / 录屏</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">—</td> <td>—</td> </tr> <tr> <td>改 App 运行时权限</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">—</td> <td>系统级权限要 root</td> </tr> <tr> <td>安装本地 APK</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td>弹系统确认框</td> </tr> <tr> <td>从商店”下载”安装</td> <td style="text-align: center">⚠️ 需 GUI 自动化</td> <td style="text-align: center">⚠️</td> <td style="text-align: center">✅</td> <td>ADB 不联商店</td> </tr> <tr> <td>卸载（含预装）</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">—</td> <td>—</td> </tr> <tr> <td>文件整理（共享存储）</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td style="text-align: center">—</td> <td>只限 /sdcard + 自己沙盒</td> </tr> <tr> <td>App 私有数据读写</td> <td style="text-align: center">❌</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td>沙盒隔离</td> </tr> <tr> <td>WiFi / 凭据 / 指纹</td> <td style="text-align: center">❌</td> <td style="text-align: center">部分</td> <td style="text-align: center">✅</td> <td>受保护存储</td> </tr> <tr> <td>系统设置迁移</td> <td style="text-align: center">部分</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td>secure 设置受限</td> </tr> <tr> <td>App 数据 / 登录态迁移</td> <td style="text-align: center">❌</td> <td style="text-align: center">✅</td> <td style="text-align: center">✅</td> <td>核心壁垒</td> </tr> </tbody> </table> <h3 id="选型建议">选型建议</h3> <ul> <li><strong>做 Agent 操控手机</strong>：走 <code class="language-plaintext highlighter-rouge">ADB + 截图（喂多模态模型）+ uiautomator 控件树</code> 的双通道路线，能复刻豆包交互闭环；执行层用 <code class="language-plaintext highlighter-rouge">input</code> 注入而非系统级 <code class="language-plaintext highlighter-rouge">INJECT_EVENTS</code>。</li> <li><strong>隐私体检 / 权限管控 / 文件整理 / 装卸</strong>：ADB 免 root 一把梭，可全脚本化。</li> <li><strong>“一句话装 App”</strong>：ADB 负责导航 + 点击，商店负责下载 + 安装（路线 1）。</li> <li><strong>完整换机克隆</strong>：同品牌用厂商工具；ADB 仅做半迁移补漏（App 清单 + APK + /sdcard + settings 快照）；App 数据交给厂商工具或 root。</li> </ul> <hr /> <h2 id="参考资料">参考资料</h2> <ul> <li><a href="https://www.qbitai.com/2025/12/359876.html">量子位：起底”豆包手机”，核心技术早已开源</a></li> <li><a href="https://www.53ai.com/news/MultimodalLargeModel/2025121567254.html">53AI：万字拆解 UI-TARS 2.0</a></li> <li><a href="https://www.53ai.com/news/zhinengyingjian/2025122889263.html">53AI：从豆包手机助手看 GUI Agent 发展</a></li> <li><a href="https://www.oschina.net/news/345234/bytedance-ui-tars-1-5">字节开源 UI-TARS-1.5（OSCHINA）</a></li> <li>Android 官方文档：<code class="language-plaintext highlighter-rouge">adb</code>、<code class="language-plaintext highlighter-rouge">pm</code>、<code class="language-plaintext highlighter-rouge">appops</code>、<code class="language-plaintext highlighter-rouge">settings</code>、<code class="language-plaintext highlighter-rouge">uiautomator</code></li> </ul>

用 ADB 通道 + 多模态大模型操控 Android 的能力边界研究：对照豆包 AI 手机（UI-TARS）实现原理，逐项分级 ADB 在权限管控、装卸、文件整理、应用下载、一键换机上的可行性。

2026-05-18T04:00:00+00:00 2026-05-18T04:00:00+00:00 https://jinzi.cyou/posts/2026-05-18-build-your-own-ai-army <blockquote> <p>日期：2026-05-18 适用栈参考：Claude Code（Opus 4.7 + Sonnet 4.6 + Haiku 4.5）/ 任意 Git 平台 / 任意 issue tracker / 任意 IM 通知通道 目标读者：已经把 AI Coding 用到日常的开发者；想从「让 AI 帮我写代码」升级到「让一支 AI 军团替我跑产研流水线」</p> </blockquote> <hr /> <h2 id="简介">简介</h2> <p>绝大多数人把 AI 用成「单兵 Copilot」——每次开会话、每次贴上下文、每次盯着 diff 点 ack。这其实没有把 LLM 的并发优势用出来。</p> <p>真正的「AI 军团」是把工程团队那一套抄一遍：</p> <ul> <li><strong>上层 PM</strong>：一个稳重模型负责拆解、派工、验收</li> <li><strong>中层 Worker</strong>：多个便宜快模型并行干活</li> <li><strong>下层 Auditor</strong>：守门员模型做巡检、灰度判定、安全 review</li> <li><strong>反馈回路</strong>：监控/告警/issue tracker 反向回流，让军团知道上次干得好不好</li> <li><strong>红线</strong>：永远不交给 AI 自动执行的操作清单（force push / live deploy / DB migration / 真钱支付 …）</li> </ul> <p>经过实践，从「单兵 Copilot」到「85% 工程自动化」需要 <strong>4-6 周搭基础设施</strong>，不是堆 prompt，是搭工程闭环。本文给一份完整的施工路线图。</p> <hr /> <h2 id="0-tldr">0. TL;DR</h2> <p><strong>一句话</strong>：把 AI 从「单兵 Copilot」升级成「PM / Worker / Auditor 三层金字塔 + 权限矩阵 + canary 回路」的工程闭环，6 周内把日常研发自动化率从 35% 推到 85%。</p> <p><strong>按 ROI 排，三个杠杆 + 一个长期项</strong>：</p> <table> <thead> <tr> <th>#</th> <th>杠杆</th> <th>投入</th> <th>预期增益</th> <th>周期</th> </tr> </thead> <tbody> <tr> <td>L1</td> <td><strong>Action Permission Matrix</strong>（GREEN/YELLOW/ORANGE/RED 四档分级 + PreToolUse hook）</td> <td>2 天</td> <td>砍掉 60% 人工 ack 摩擦</td> <td>Week 1</td> </tr> <tr> <td>L2</td> <td><strong>反馈回路</strong>（Sentry → issue tracker → PM agent → Worker → 反向回填）</td> <td>1 周</td> <td>解锁「线上痛点 → hotfix」闭环</td> <td>Week 2-3</td> </tr> <tr> <td>L3</td> <td><strong>Canary + 自动回滚</strong>（低风险 PR 直接 auto-merge + 部署 beta）</td> <td>2 周</td> <td>把「ack 每个 MR」降为「看灰度报告」</td> <td>Week 4-6</td> </tr> <tr> <td>L4</td> <td><strong>PM/Worker/Auditor 金字塔常驻</strong>（cron-driven 多 agent 编队）</td> <td>持续</td> <td>让军团 24h 跑</td> <td>后续</td> </tr> </tbody> </table> <p><strong>阶段性目标</strong>：Week 1 → 50% / Week 3 → 65% / Week 6 → 80% / 稳态 → 85%。</p> <p><strong>终态指标</strong>：</p> <ul> <li>每日 ack 次数 15+ → 3-5</li> <li>P2/P3 bug 响应时长 4h → 20min</li> <li>AI PR 平均生命周期 6h → 30min</li> <li>灰度逃逸次数 → 0（红线由规则拦）</li> </ul> <p><strong>成本</strong>（10-20 人团队规模）：一次性投入 17 工作日 + 周维护 5.5h + 月 token 账单约 $700，月省 ~75h 个人时间。</p> <p><strong>永远不解锁的红线</strong>：push 主干 / 生产 DB migration / 真钱支付 / 删生产资源 / 业务定价决策 — 硬编码 regex 拦截，不依赖 LLM 判断。</p> <p><strong>底线认知</strong>：不是堆 prompt，是搭工程闭环。Prompt 优化的边际收益很快递减，工程闭环才是护城河。</p> <hr /> <h2 id="1-心法为什么是军团而不是更强的-copilot">1. 心法：为什么是「军团」而不是「更强的 Copilot」</h2> <h3 id="11-单兵-copilot-的天花板">1.1 单兵 Copilot 的天花板</h3> <p>不管你的 prompt 多花哨、上下文多长，单 agent 模式有三个硬上限：</p> <ol> <li><strong>串行瓶颈</strong>：一次只能干一件事；你 ack 等待时间 = 实际产出时间的 3-5 倍</li> <li><strong>上下文污染</strong>：长对话里早期决策被后期 token 稀释；一次 50K context 后判断质量明显下降</li> <li><strong>角色错位</strong>：让同一个模型同时干「写代码 + review 自己代码 + 决定要不要 deploy」违反职责分离</li> </ol> <h3 id="12-军团模式怎么破">1.2 军团模式怎么破</h3> <table> <thead> <tr> <th>单兵痛点</th> <th>军团解法</th> </tr> </thead> <tbody> <tr> <td>串行等待</td> <td>3-7 个 worker 并行，每个独立 worktree</td> </tr> <tr> <td>上下文污染</td> <td>PM 单次会话保持 &lt; 50K，每个任务派给新 worker</td> </tr> <tr> <td>角色错位</td> <td>PM / Worker / Auditor 三层职责分离，Auditor 不持有写权限</td> </tr> <tr> <td>ack 疲劳</td> <td>按风险分级（GREEN/YELLOW/ORANGE/RED），只 ack 真正需要决策的</td> </tr> </tbody> </table> <p>核心一句话：<strong>这不是让 AI 替你工作，而是把你从 ack 机器变回决策者</strong>。</p> <hr /> <h2 id="2-三层架构总览">2. 三层架构总览</h2> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌──────────────────────────────────────────────────────────┐ │ 上层：PM Agent (Opus 类强模型) — 接单 / 拆解 / 派工 / 验收 │ │ 常驻 cron + 反应式（IM @我 / 新 bug / 监控告警） │ └──────────────────────────────────────────────────────────┘ ↓ 派任务 ┌──────────────────────────────────────────────────────────┐ │ 中层：Worker Pool (Sonnet 类性价比模型, 3-7 并行) │ │ 每个 worker = 独立 worktree + 完整 PR-to-merge 能力 │ └──────────────────────────────────────────────────────────┘ ↓ 提交产物 ┌──────────────────────────────────────────────────────────┐ │ 下层：Auditor Pool (Haiku 类便宜模型, 巡检 / 守门 / 回归) │ │ 代码 review / 安全扫描 / 灰度 watcher / 日报汇总 │ └──────────────────────────────────────────────────────────┘ ↓ 输出 ┌──────────────────────────────────────────────────────────┐ │ 反馈回路：IM 通知 / 日报 / 监控告警 / 灰度 SLO │ │ + 红线触发 → 暂停整条流水线 + P0 告警 │ └──────────────────────────────────────────────────────────┘ </code></pre></div></div> <h3 id="21-职责分配原则">2.1 职责分配原则</h3> <ul> <li><strong>强模型只做判断 + 拆解 + 验收</strong>，单次会话短（&lt; 50K token），节省 token</li> <li><strong>中档模型干 80% 实活</strong>，并行最高 7 个 worker（受 IDE/Code Agent 并发限制）</li> <li><strong>便宜模型干机械审计</strong>（lint 解释、test fail 分类、灰度 SLO 抽样），便宜量大</li> <li><strong>没有任何 agent 同时持有写权限和审计权限</strong>（职责分离）</li> </ul> <h3 id="22-为什么强模型不能干所有事">2.2 为什么强模型不能干所有事</h3> <p>按典型按 token 计价，Opus 类比 Sonnet 类贵 5×、比 Haiku 类贵 15×。让 Opus 干「读 lint 报告判断哪行是 false positive」是赔本买卖。</p> <p>但反过来，让 Haiku 类干「这个 bug 算不算需要回滚的级别」这种判断也不行——出错代价远高于省下来的 token 钱。</p> <p><strong>规则</strong>：判断 → 强模型；干活 → 中档；机械 → 便宜。</p> <hr /> <h2 id="3-阶段路线图">3. 阶段路线图</h2> <h3 id="phase-1week-1action-permission-matrix--把直觉变成规则">Phase 1（Week 1）：Action Permission Matrix — 把直觉变成规则</h3> <p>这是整套军团最被低估的一步。多数人上来就堆 prompt、起 cron，结果第一周就出事——因为没有任何机制拦住模型干蠢事。</p> <p><strong>核心产出</strong>：一份动作分级表 + 一个 PreToolUse hook</p> <h4 id="311-动作四档分级">3.1.1 动作四档分级</h4> <table> <thead> <tr> <th>等级</th> <th>含义</th> <th>典型动作</th> <th>自动化策略</th> </tr> </thead> <tbody> <tr> <td><strong>GREEN</strong></td> <td>完全可逆 / 本地</td> <td>改文档 / 跑 lint / 改本地任务状态 / 发 IM 汇报</td> <td>全自动，不 ack</td> </tr> <tr> <td><strong>YELLOW</strong></td> <td>共享但可回滚</td> <td>push 到 feature 分支 / 开 PR / 改 dev 环境配置</td> <td>自动 + 事后通知</td> </tr> <tr> <td><strong>ORANGE</strong></td> <td>共享难回滚</td> <td>beta 部署 / merge PR / 改测试环境 .env</td> <td>canary 通过即自动（Phase 3 解锁）</td> </tr> <tr> <td><strong>RED</strong></td> <td>灾难性</td> <td>push master / 生产部署 / DB migration / 真钱支付</td> <td><strong>永远人 ack</strong>（不解锁）</td> </tr> </tbody> </table> <h4 id="312-规则编码">3.1.2 规则编码</h4> <p>把规则写成机器可读 YAML，挂到 hook 上：</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># rules/action-permissions.yaml</span> <span class="na">rules</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">git</span><span class="nv"> </span><span class="s">push.*</span><span class="se">\\</span><span class="s">b(master|main|prod)</span><span class="se">\\</span><span class="s">b"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">RED</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">不能直接</span><span class="nv"> </span><span class="s">push</span><span class="nv"> </span><span class="s">主干分支"</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">git</span><span class="nv"> </span><span class="s">(reset</span><span class="nv"> </span><span class="s">--hard|checkout</span><span class="nv"> </span><span class="s">--)</span><span class="nv"> </span><span class="s">.*"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">RED</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">可能吞掉别人未推送的工作"</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">.*--force.*"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">ORANGE</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">force</span><span class="nv"> </span><span class="s">操作要</span><span class="nv"> </span><span class="s">canary</span><span class="nv"> </span><span class="s">路径，不能直接放"</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">(stripe|paypal).*--live"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">RED</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">真钱接口必须人</span><span class="nv"> </span><span class="s">ack"</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">kubectl</span><span class="nv"> </span><span class="s">apply</span><span class="nv"> </span><span class="s">-f</span><span class="nv"> </span><span class="s">.*</span><span class="nv"> </span><span class="s">-n</span><span class="nv"> </span><span class="s">(prod|production)"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">RED</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">生产集群修改必须</span><span class="nv"> </span><span class="s">review"</span> <span class="pi">-</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s2">"</span><span class="s">rm</span><span class="nv"> </span><span class="s">-rf</span><span class="nv"> </span><span class="s">/"</span> <span class="na">level</span><span class="pi">:</span> <span class="s">RED</span> <span class="na">reason</span><span class="pi">:</span> <span class="s2">"</span><span class="s">显式拦截灾难命令"</span> </code></pre></div></div> <h4 id="313-hook-落地">3.1.3 hook 落地</h4> <p>在你的 Code Agent 的 <code class="language-plaintext highlighter-rouge">PreToolUse</code> 钩子里跑一个脚本：</p> <ul> <li>GREEN → 直接放行</li> <li>YELLOW → 放行 + 追加一行到 <code class="language-plaintext highlighter-rouge">auto-actions.log</code></li> <li>ORANGE → 转 canary 流程（Phase 3）；未上线前仍人 ack</li> <li>RED → 阻断 + 必须显式 ack 才能继续</li> </ul> <p><strong>重要</strong>：第一周观察期只 log 不 enforce，确认无误报再切真拦。否则一个误判把军团整条流水线卡死。</p> <h4 id="314-经验">3.1.4 经验</h4> <ul> <li>规则文件必须进 git，团队/未来的自己能 review</li> <li>规则匹配优先级写死 <code class="language-plaintext highlighter-rouge">RED &gt; ORANGE &gt; YELLOW &gt; GREEN</code>，多条命中取最高</li> <li>不要相信 LLM 来判断「这条命令属于哪一档」——硬编码 regex 兜底，再让 LLM 做语义补充判断</li> </ul> <hr /> <h3 id="phase-2week-2-3反馈回路--让军团知道上次干得好不好">Phase 2（Week 2-3）：反馈回路 — 让军团知道「上次干得好不好」</h3> <p>没有反馈的 AI 军团就是失控的流水线。Phase 2 解决：怎么把「线上出问题了」「用户报 bug 了」「监控异常了」自动喂回军团。</p> <h4 id="321-监控--issue-tracker-自建桥">3.2.1 监控 → issue tracker 自建桥</h4> <p>最常见的回路：<strong>错误监控（Sentry / Bugsnag / 自建）→ issue tracker（Jira / GitHub Issues / 自建）→ PM agent 接单</strong>。</p> <p>关键工程要素：</p> <ol> <li><strong>准入阈值</strong>：不是每个监控告警都建 issue。典型准入条件： <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>events &gt; 10 (短时间复现 10 次以上) AND affected_users &gt; 3 AND level &gt;= error </code></pre></div> </div> <p>否则会把 PM agent 淹没在噪音里。</p> </li> <li> <p><strong>去重</strong>：监控系统的 issue_id 进 issue tracker 的某个字段（keywords / labels），24h Redis SET 防重复建单。</p> </li> <li><strong>反向回填</strong>：PR 描述自动带 <code class="language-plaintext highlighter-rouge">Closes #123</code>，merge 后通过 Git 平台 webhook 反向把 issue 标 resolved。这一步看起来微不足道，但少了它整条回路就是单向的，PM agent 不知道自己上次提的 PR 到底解决问题了没有。</li> </ol> <h4 id="322-pm-agent-接单-prompt-模板">3.2.2 PM agent 接单 prompt 模板</h4> <p>PM 不写代码，只判断。短 context、JSON 输出：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>你是军团的 PM。下面是一个监控触发的新 bug： {bug 详情 + stack trace + 最近 10 个相关 commit} 判断： 1. 这个 bug 能不能 AI 自动修？(YES / NO / NEED_INFO) 2. 如果 YES，列出最多 5 步修复计划 3. 如果 NO，说明为什么需要人介入 4. risk 评级 (low / mid / high) 只输出 JSON，不写代码。 </code></pre></div></div> <p>PM 判 YES 才 spawn 一个 worker（独立 worktree）去实际修。</p> <h4 id="323-24h-后部署监控">3.2.3 24h 后部署监控</h4> <p>部署完不是结束。Phase 2 的最后一块：<strong>部署后 24h 内同 issue 复发 → 自动回滚 + P0 告警</strong>。</p> <p>这一步逼着你把回滚做成单一入口（一个 <code class="language-plaintext highlighter-rouge">rollback.sh</code>，不是各种 ad-hoc 操作的集合）。一旦做了，整个团队的 incident 响应都受益。</p> <hr /> <h3 id="phase-3week-4-6canary-gate--解锁-orange-级自动化">Phase 3（Week 4-6）：Canary Gate — 解锁 ORANGE 级自动化</h3> <p>最重的一步。做完之后 AI 真能「自己 push beta」。</p> <h4 id="331-流量切分">3.3.1 流量切分</h4> <p>不管你跑 k8s / docker / 物理机，核心是<strong>让两个版本同时跑</strong>，按流量比例分配：</p> <ul> <li>入口层（nginx / envoy / 云负载均衡）配 5% 流量到新版本 pod</li> <li>95% 流量保留旧版本</li> </ul> <p>实现方式很多：nginx <code class="language-plaintext highlighter-rouge">split_clients</code>、envoy weighted clusters、k8s Argo Rollouts / Flagger、各家云原生 canary 方案。挑一个能在 30 秒内回切的就行。</p> <h4 id="332-slo-自动判定">3.3.2 SLO 自动判定</h4> <p>选三个核心指标做 AND 判定：</p> <table> <thead> <tr> <th>指标</th> <th>典型阈值</th> </tr> </thead> <tbody> <tr> <td>HTTP 5xx 率</td> <td>canary ≤ 旧版 + 0.5%</td> </tr> <tr> <td>核心接口 P95 延迟</td> <td>canary ≤ 旧版 × 1.2</td> </tr> <tr> <td>业务关键失败率（如下单失败 / agent run 失败）</td> <td>canary ≤ 旧版 + 1%</td> </tr> </tbody> </table> <p>30 分钟观察窗口内全部满足 → 切 100% + 通知；任意一项不满足 → 自动 revert + 监控留痕。</p> <p><strong>重要</strong>：三指标 AND 而不是 OR。OR 会让噪音指标误触发回滚，AND 让回滚信号干净。</p> <h4 id="333-pr-风险评分">3.3.3 PR 风险评分</h4> <p>PM agent 在 PR 合并前算一个 risk score：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>risk_score = w1 * touches_auth + w2 * touches_billing + w3 * touches_migration + w4 * (lines_changed &gt; 500) + w5 * touches_critical_path </code></pre></div></div> <ul> <li><code class="language-plaintext highlighter-rouge">risk = low</code>（UI 文案 / 文档 / 单测 / 内部工具）：canary 通过即自动 merge + deploy</li> <li><code class="language-plaintext highlighter-rouge">risk = mid</code>（业务逻辑、新 API）：canary 通过 + 人点一次 yes</li> <li><code class="language-plaintext highlighter-rouge">risk = high</code>（auth / billing / migration）：永远人 review 全 diff</li> </ul> <p><code class="language-plaintext highlighter-rouge">touches_critical_path</code> 用 git log heatmap 加权——历史上被反复修改的文件大概率是核心路径。</p> <h4 id="334-回滚演练">3.3.4 回滚演练</h4> <p><strong>每周让 Auditor 跑一次「故意失败的 canary」</strong>，确认回滚链路活着。</p> <p>很多团队搭完 canary 就放在那不演练，等到真出事的时候才发现回滚脚本里某个环境变量上个月就 broken 了。</p> <hr /> <h3 id="phase-4持续金字塔常驻">Phase 4（持续）：金字塔常驻</h3> <p>前三步做完，最后这一步把军团变成 24h 跑的常驻系统。</p> <h4 id="341-pm-常驻-cron">3.4.1 PM 常驻 cron</h4> <p>每天早上一个固定时间触发：</p> <ul> <li>扫产品文档系统过去 24h 更新的 PRD</li> <li>扫 issue tracker 新 P0/P1 bug</li> <li>扫 IM 群里 @我或 @机器人 的消息</li> <li>输出一份 <code class="language-plaintext highlighter-rouge">briefing.md</code>，列出「今天打算让军团干啥」</li> <li>等你 ack 一次（每天 1 次 ack 比每个任务 1 次 ack 划算 10×）</li> </ul> <h4 id="342-worker-pool">3.4.2 Worker pool</h4> <p>用你的 Code Agent 起 3-7 个 worktree-isolated worker（每个 worker 独立分支 + 独立 PR + 独立任务绑定）。worker 之间不互相依赖；冲突由 PM 重排。</p> <h4 id="343-auditor-巡检-routine">3.4.3 Auditor 巡检 routine</h4> <p>每 4h 跑一次便宜模型巡检：</p> <ul> <li>stale container / drift env / 过期 secret</li> <li>待合 PR &gt; 24h → 提醒 PM 复审</li> <li>待办 issue &gt; 7 天 → 标 stale</li> <li>输出审计日志</li> </ul> <h4 id="344-每晚日报">3.4.4 每晚日报</h4> <p>22 点 cron 自动汇总当天：</p> <ul> <li>开了几个 PR / 合了几个 / 修了几个 bug</li> <li>canary 触发次数 / 回滚次数</li> <li>触发了几次 RED 拦截（被拦的命令 + 原因）</li> <li>推送到你的 IM 私聊</li> </ul> <hr /> <h2 id="4-红线清单永不解锁">4. 红线清单（永不解锁）</h2> <p>不管军团多成熟，以下动作永远人 ack：</p> <table> <thead> <tr> <th>动作</th> <th>理由</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">git push</code> 到主干分支</td> <td>不可逆 + 影响 prod</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">git reset --hard</code> 共享分支</td> <td>吃别人的 commit</td> </tr> <tr> <td>生产环境 DB migration</td> <td>高风险 + 难回滚</td> </tr> <tr> <td>真钱支付接口（Stripe live / 银联 / 支付宝）写操作</td> <td>涉及真钱</td> </tr> <tr> <td>改生产环境 <code class="language-plaintext highlighter-rouge">.env</code> / secret</td> <td>配置隔离原则</td> </tr> <tr> <td>删除 K8s namespace / 集群</td> <td>灾难性</td> </tr> <tr> <td>业务定价 / 产品取舍 / PRD 决策</td> <td>需人判断</td> </tr> <tr> <td>首次接入新外部 API（OIDC / 支付 / 跨境合规）</td> <td>LLM 容易脑补字段、踩 schema 坑</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">kubectl delete</code> / <code class="language-plaintext highlighter-rouge">terraform destroy</code> 生产资源</td> <td>灾难性</td> </tr> <tr> <td>直接 <code class="language-plaintext highlighter-rouge">curl</code> 生产 API（绕过封装好的 CLI）</td> <td>容易传错 header / 缺鉴权</td> </tr> </tbody> </table> <p>红线判定不要依赖 LLM——<strong>硬编码 regex grep 兜底，模式匹配在前，LLM 推理在后</strong>。</p> <hr /> <h2 id="5-度量指标">5. 度量指标</h2> <h3 id="51-健康指标每天看">5.1 健康指标（每天看）</h3> <table> <thead> <tr> <th>指标</th> <th>含义</th> </tr> </thead> <tbody> <tr> <td>AI 提 PR / 总 PR</td> <td>自动化覆盖率，目标 70%</td> </tr> <tr> <td>PR 平均人工接触次数</td> <td>目标 1 次（仅看 canary 报告）</td> </tr> <tr> <td>每天 ack 次数</td> <td>目标 ≤ 5</td> </tr> <tr> <td>P2/P3 bug 响应时长</td> <td>目标 ≤ 20min</td> </tr> <tr> <td>canary 回滚成功率</td> <td>目标 ≥ 99%</td> </tr> <tr> <td>RED 规则拦截次数</td> <td>突增表示规则误判或 PM 走偏</td> </tr> <tr> <td>灰度逃逸次数（线上才发现的回归）</td> <td>目标 0</td> </tr> </tbody> </table> <h3 id="52-异常告警">5.2 异常告警</h3> <ul> <li><code class="language-plaintext highlighter-rouge">canary_rollback</code> 24h &gt; 3 → 暂停 Phase 3 自动化</li> <li><code class="language-plaintext highlighter-rouge">red_line_blocked</code> 1h &gt; 5 → 检查规则误判</li> <li>PM 决策 reject 率 &gt; 30% → PM prompt 需要调</li> <li>任意 RED 规则被绕过 → P0 告警</li> </ul> <h3 id="53-阶段目标">5.3 阶段目标</h3> <table> <thead> <tr> <th>阶段</th> <th>自动化率</th> <th>每日 ack 次数</th> <th>AI PR 生命周期</th> </tr> </thead> <tbody> <tr> <td>起点</td> <td>35%</td> <td>15+</td> <td>6h</td> </tr> <tr> <td>Phase 1 末</td> <td>50%</td> <td>9</td> <td>4h</td> </tr> <tr> <td>Phase 2 末</td> <td>65%</td> <td>7</td> <td>2h</td> </tr> <tr> <td>Phase 3 末</td> <td>80%</td> <td>5</td> <td>1h</td> </tr> <tr> <td>稳态</td> <td>85%</td> <td>3-5</td> <td>30min</td> </tr> </tbody> </table> <hr /> <h2 id="6-主要风险与缓解">6. 主要风险与缓解</h2> <table> <thead> <tr> <th>风险</th> <th>缓解</th> </tr> </thead> <tbody> <tr> <td>规则误判导致 GREEN 动作误删 prod 数据</td> <td>YELLOW 以上全部走 git，永不直接改 prod 数据</td> </tr> <tr> <td>监控噪音淹没 issue tracker</td> <td>阈值（events&gt;10 + users&gt;3）+ 24h 去重</td> </tr> <tr> <td>Canary watcher 误判通过 → 灰度逃逸</td> <td>三指标 AND + 前 10 次人 spot check</td> </tr> <tr> <td>PM agent 把红线问题判成 auto</td> <td>red_list 硬编码 grep 兜底，不依赖 LLM</td> </tr> <tr> <td>Worker 之间 worktree 冲突</td> <td>PM 拆任务时强制单文件夹独占</td> </tr> <tr> <td>Token 成本爆炸</td> <td>强模型限 50K context；便宜模型占调用量 60%</td> </tr> <tr> <td>整个军团失控</td> <td>留一个总开关：<code class="language-plaintext highlighter-rouge">echo PAUSE &gt; army-state</code>，所有 cron 启动前 check</td> </tr> </tbody> </table> <p><strong>总开关脚本</strong>：</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 紧急停军团</span> <span class="nb">echo</span> <span class="s2">"PAUSE"</span> <span class="o">&gt;</span> ~/.army-state <span class="c"># 所有 cron routine 启动前的第一行</span> <span class="o">[[</span> <span class="s2">"</span><span class="si">$(</span><span class="nb">cat</span> ~/.army-state 2&gt;/dev/null<span class="si">)</span><span class="s2">"</span> <span class="o">==</span> <span class="s2">"PAUSE"</span> <span class="o">]]</span> <span class="o">&amp;&amp;</span> <span class="nb">exit </span>0 </code></pre></div></div> <p>简单粗暴，但比任何花哨的 feature flag 系统都靠谱。</p> <hr /> <h2 id="7-入门-poc-优先级">7. 入门 PoC 优先级</h2> <p>不要试图一次性搭完所有 Phase。按「能跑通即看到价值」排序，每个 PoC 1 周内做完：</p> <h3 id="poc-1低优先级-bug--pr--im-汇报-推荐起点">PoC 1：低优先级 bug → PR → IM 汇报 ★推荐起点</h3> <ul> <li><strong>为什么</strong>：bug 边界清晰、有客观验收（复现 + 测试通过）、失败成本极低</li> <li><strong>范围</strong>：只接 P2/P3 + 标签 <code class="language-plaintext highlighter-rouge">auto-eligible</code> 的 bug</li> <li><strong>不接</strong>：P0/P1（涉判断）、auth/billing 类（红线）</li> <li><strong>验收</strong>：1 周跑通 3-5 个 bug，PM 决策准确率 &gt; 80%</li> </ul> <h3 id="poc-2依赖升级--测试回归">PoC 2：依赖升级 + 测试回归</h3> <ul> <li><strong>为什么</strong>：纯机械、有 audit 客观信号（npm audit / cargo audit / pip-audit）</li> <li><strong>范围</strong>：minor / patch 自动 PR，major 走人 review</li> <li><strong>配套</strong>：类似 Renovate / Dependabot 思路，但用 PM agent 做「哪些 major 该手动 review」判断</li> </ul> <h3 id="poc-3文档--i18n-同步">PoC 3：文档 / i18n 同步</h3> <ul> <li><strong>为什么</strong>：纯文本变更、零 prod 风险</li> <li><strong>范围</strong>：英文文案落地后自动补 zh/ja；架构文档改动同步到 onboarding 文档</li> <li><strong>价值</strong>：练手 + 把军团基础设施跑顺</li> </ul> <h3 id="poc-4跨系统巡检日报">PoC 4：跨系统巡检日报</h3> <ul> <li><strong>为什么</strong>：纯读、0 风险、立即看到「军团在干啥」</li> <li><strong>范围</strong>：Git 平台 PR / issue tracker / 监控告警 / 容器健康</li> <li><strong>产出</strong>：每天固定时间 IM 推送</li> </ul> <h3 id="不推荐先做的-poc">不推荐先做的 PoC</h3> <ul> <li><strong>Feature 开发</strong>：太大、太多业务判断，先把基础设施跑顺</li> <li><strong>Canary deploy</strong>：基础设施投入 2 周起步，放到 Phase 3</li> <li><strong>PRD → 任务自动拆解</strong>：判断密集，留给 PM agent 成熟后做</li> </ul> <hr /> <h2 id="8-投入产出预估">8. 投入产出预估</h2> <table> <thead> <tr> <th>阶段</th> <th>一次性投入</th> <th>周维护</th> <th>月节省（按 ack 时长）</th> </tr> </thead> <tbody> <tr> <td>Phase 1</td> <td>2 工作日</td> <td>0.5h</td> <td>~15h</td> </tr> <tr> <td>Phase 2</td> <td>5 工作日</td> <td>1h</td> <td>~20h</td> </tr> <tr> <td>Phase 3</td> <td>10 工作日</td> <td>2h</td> <td>~30h</td> </tr> <tr> <td>Phase 4</td> <td>持续</td> <td>2h</td> <td>~10h</td> </tr> <tr> <td><strong>合计</strong></td> <td><strong>17 工作日</strong></td> <td><strong>5.5h/周</strong></td> <td><strong>~75h/月</strong></td> </tr> </tbody> </table> <p>按月 22 工作日 × 8h = 176h，节省 75h ≈ 42% 个人时间。</p> <p>考虑到节省的不只是时间，更是「上下文切换成本」，实际感受会更显著。</p> <hr /> <h2 id="9-常见误区">9. 常见误区</h2> <h3 id="91-先把-prompt-调好再说基础设施">9.1 「先把 prompt 调好再说基础设施」</h3> <p>错。Prompt 优化的边际收益很快递减；工程闭环才是真正的护城河。</p> <p>一支基础设施完备的军团 + 平庸 prompt &gt; 顶级 prompt + 没有反馈回路。</p> <h3 id="92-llm-越强越好全用-opus">9.2 「LLM 越强越好，全用 Opus」</h3> <p>错。Opus 干 Haiku 能干的活，是给账单送钱。Token 成本是真实约束，按职责分模型才能跑长期。</p> <h3 id="93-不需要-pm-agent让-sonnet-自己接单">9.3 「不需要 PM agent，让 Sonnet 自己接单」</h3> <p>错。Sonnet 接单容易在「这个 bug 该不该自动修」上犯错（典型：把涉及 auth 的 bug 判成 low risk）。PM 用强模型保判断质量，是性价比最高的一笔投资。</p> <h3 id="94-canary-太重跳过这步">9.4 「Canary 太重，跳过这步」</h3> <p>错。Canary 不是为了赶时髦的高级 SRE 实践，是为了<strong>把人从「ack 每个 PR」解放到「看灰度报告」</strong>。没有 canary，Phase 3 永远做不到 80% 自动化。</p> <h3 id="95-记忆系统能替代规则系统">9.5 「记忆系统能替代规则系统」</h3> <p>错。记忆是软约束（LLM 可能选择不遵守），规则是硬约束（hook 直接拦）。RED 红线必须走规则，不能寄希望于「我在 memory 里写过了模型会记得」。</p> <hr /> <h2 id="10-一句话总结">10. 一句话总结</h2> <p><strong>这不是「让 AI 替你工作」，而是「把你从 ack 机器变回决策者」。</strong></p> <p>军团的本质：让你只关心 RED 类决策 + 周/月级方向，把 GREEN/YELLOW/ORANGE 全卷进流水线。</p> <p>可以达到 85% 的稳态，但前提是花两周把基础设施（permission matrix + canary）搭对——不是堆 prompt，是搭工程闭环。</p> <hr /> <h2 id="11-具体案例gitlab--zentao--confluence--企微--sentrygrafana">11. 具体案例：GitLab + ZenTao + Confluence + 企微 + Sentry/Grafana</h2> <p>下面用一个国内中型研发团队常见栈，给出一份<strong>可直接照抄的军团编制</strong>。规模假设：</p> <ul> <li>10-20 人研发团队</li> <li>1 个主产品 + 2-3 个内部工具</li> <li>已有 GitLab self-hosted、ZenTao 项目管理、Confluence 知识库、企微办公、Sentry 错误监控、Grafana 指标看板</li> </ul> <h3 id="111-工具链职责映射">11.1 工具链职责映射</h3> <table> <thead> <tr> <th>系统</th> <th>在军团中的角色</th> <th>谁来读</th> <th>谁来写</th> </tr> </thead> <tbody> <tr> <td><strong>GitLab</strong></td> <td>代码 + MR + CI + webhook 总线</td> <td>Worker / Auditor</td> <td>Worker（开 MR）/ PM（merge 决策）</td> </tr> <tr> <td><strong>ZenTao</strong></td> <td>任务/bug 调度中心（军团的「工单池」）</td> <td>PM（接单）/ Auditor（巡检）</td> <td>PM（建任务）/ Worker（标进度）/ Bridge（自动建单）</td> </tr> <tr> <td><strong>Confluence</strong></td> <td>PRD / 决策文档 / 周报存档</td> <td>PM（早会扫描）/ Worker（取需求）</td> <td>PM（写 briefing）/ Auditor（写日报）</td> </tr> <tr> <td><strong>企微</strong></td> <td>唯一通知出口 + 唯一 ack 入口</td> <td>—</td> <td>PM / Auditor（推送）/ 你（@回复 ack）</td> </tr> <tr> <td><strong>Sentry</strong></td> <td>线上错误信号源</td> <td>Bridge（轮询 / webhook）/ Auditor（24h 监控）</td> <td>—</td> </tr> <tr> <td><strong>Grafana</strong></td> <td>指标信号源（canary SLO 判定）</td> <td>Canary Watcher / Auditor</td> <td>—</td> </tr> </tbody> </table> <p><strong>关键设计</strong>：</p> <ul> <li><strong>企微是唯一的人机交互通道</strong>。不要让军团从 IM / 邮件 / Slack 多通道喂消息——你会漏。所有 ack、所有告警、所有日报都收敛到一个企微群（@机器人 + 你私聊）。</li> <li><strong>ZenTao 是军团的事实任务源</strong>。哪怕 bug 来自 Sentry、需求来自 Confluence，最终都得在 ZenTao 落一条记录，PM 才接得到。没在 ZenTao 的需求军团一律不接（避免歧义）。</li> <li><strong>GitLab webhook 是反馈回路的脊柱</strong>。MR 状态变化、Pipeline 成败、Sentry 关联 issue 都靠 GitLab webhook 串起来。</li> </ul> <h3 id="112-军团编制表">11.2 军团编制表</h3> <table> <thead> <tr> <th>角色</th> <th>模型</th> <th>数量</th> <th>触发方式</th> <th>单次会话上下文上限</th> <th>职责</th> </tr> </thead> <tbody> <tr> <td><strong>PM Lead</strong></td> <td>Opus 4.7</td> <td>1</td> <td>每天 9:00 cron + 反应式（@机器人 / Sentry P0 / ZenTao 新 P0）</td> <td>50K</td> <td>接单 / 拆解 / 派工 / 验收 / 走 RED 时给你提 ack</td> </tr> <tr> <td><strong>Worker</strong></td> <td>Sonnet 4.6</td> <td>5</td> <td>PM 派单 spawn（worktree 隔离）</td> <td>100K</td> <td>拉分支 / 改代码 / 跑测试 / 开 MR / 标 ZenTao 进度</td> </tr> <tr> <td><strong>Reviewer</strong></td> <td>Sonnet 4.6</td> <td>2</td> <td>MR 开了即触发</td> <td>80K</td> <td>代码 review（功能 + 风格 + 测试覆盖）/ 给 LGTM 或要求改</td> </tr> <tr> <td><strong>Security Auditor</strong></td> <td>Sonnet 4.6</td> <td>1</td> <td>MR 开了即触发（与 Reviewer 并行）</td> <td>80K</td> <td>OWASP 扫描 / secret 泄露检查 / 鉴权变更告警</td> </tr> <tr> <td><strong>Canary Watcher</strong></td> <td>Haiku 4.5</td> <td>1</td> <td>MR merge 后部署 beta 时触发，常驻 30min</td> <td>20K</td> <td>Grafana 三指标抽样 / SLO 判定 / 触发 promote 或 rollback</td> </tr> <tr> <td><strong>Sentry Bridge</strong></td> <td>Haiku 4.5</td> <td>1</td> <td>Sentry webhook 触发</td> <td>10K</td> <td>阈值过滤 / 去重 / 建 ZenTao bug / 反向回填</td> </tr> <tr> <td><strong>Patrol Auditor</strong></td> <td>Haiku 4.5</td> <td>1</td> <td>每 4h cron</td> <td>30K</td> <td>stale MR / stale 容器 / 过期 secret / drift 检查</td> </tr> <tr> <td><strong>Daily Reporter</strong></td> <td>Haiku 4.5</td> <td>1</td> <td>每天 22:00 cron</td> <td>40K</td> <td>汇总当天动作 / 写 Confluence 日报 / 推企微</td> </tr> </tbody> </table> <p><strong>编制小计</strong>：1 Opus + 8 Sonnet + 4 Haiku = <strong>13 个 agent 槽位</strong>，并发上限 7（受 Claude Code <code class="language-plaintext highlighter-rouge">/team</code> 限制），实际同时活跃的 ~3-5 个。</p> <p><strong>月 token 预算估算</strong>（中等活跃度，按 2026-05 价格）：</p> <table> <thead> <tr> <th>角色</th> <th>每月调用次数</th> <th>平均 token</th> <th>月成本</th> </tr> </thead> <tbody> <tr> <td>PM Lead (Opus)</td> <td>~150</td> <td>30K in / 5K out</td> <td>~$200</td> </tr> <tr> <td>Worker × 5 (Sonnet)</td> <td>~600</td> <td>60K in / 15K out</td> <td>~$300</td> </tr> <tr> <td>Reviewer + Security (Sonnet)</td> <td>~400</td> <td>40K in / 8K out</td> <td>~$120</td> </tr> <tr> <td>Haiku × 4</td> <td>~3000</td> <td>15K in / 3K out</td> <td>~$80</td> </tr> <tr> <td><strong>合计</strong></td> <td> </td> <td> </td> <td><strong>~$700/月</strong></td> </tr> </tbody> </table> <p>按节省 75h/月 × 时薪保守 ¥200 计，月节省 ~¥15000，ROI ≈ 3×。</p> <h3 id="113-端到端流程图sentry-告警--自动-pr--合并">11.3 端到端流程图：Sentry 告警 → 自动 PR → 合并</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌─────────────┐ │ Sentry │ events&gt;10 &amp;&amp; users&gt;3 &amp;&amp; level&gt;=error │ (prod alert)│ └──────┬──────┘ │ webhook ▼ ┌──────────────────┐ │ Sentry Bridge │ Haiku · 阈值 + 去重 + 建单 │ (Haiku 4.5) │ └──────┬───────────┘ │ POST /zentao/api/bugs (label=auto-sentry) ▼ ┌──────────────────┐ │ ZenTao │ 新 bug · 等 PM 扫描 │ bug pool │ └──────┬───────────┘ │ 15min cron 扫描 ▼ ┌──────────────────┐ ┌──────────────────────┐ │ PM Lead │ ─────► │ 红线检查 (硬编码 grep)│ │ (Opus 4.7) │ ◄───── │ 命中 RED → 转人 ack │ └──────┬───────────┘ └──────────────────────┘ │ 判定 = auto · risk = low/mid │ spawn worker (worktree 隔离) ▼ ┌──────────────────┐ │ Worker N │ Sonnet · 改代码 · 跑测试 · 开 MR │ (Sonnet 4.6) │ └──────┬───────────┘ │ git push + MR (描述带 "Resolves zt#xxx") ▼ ┌──────────────────┐ │ GitLab │ CI 跑 lint + 单测 + 构建 │ MR │ └──────┬───────────┘ │ webhook: pipeline succeeded ▼ ┌──────────────────┐ ┌──────────────────┐ │ Reviewer │ │ Security Auditor │ 并行 │ (Sonnet 4.6) │ │ (Sonnet 4.6) │ └──────┬───────────┘ └────────┬─────────┘ │ 双 LGTM │ └───────┬───────┘ ▼ ┌─────────────────────┐ │ PM Lead 二次验收 │ risk 评级 + 决策 │ (Opus 4.7) │ └──────────┬──────────┘ │ ┌──────┴──────┐ risk=low risk=mid/high │ │ ▼ ▼ auto-merge 企微 @你 ack │ │ └──────┬───────┘ ▼ ┌─────────────────────┐ │ GitLab merge │ → CI 部署到 beta canary └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Canary Watcher │ Haiku · 抽样 Grafana 30min │ (Haiku 4.5) │ └──────────┬──────────┘ │ ┌──────┴──────┐ SLO 通过 SLO 失败 │ │ ▼ ▼ promote 100% auto-rollback │ │ └──────┬───────┘ ▼ ┌─────────────────────┐ │ 反向回填 ZenTao bug │ status=resolved + MR 链接 └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ 企微通知（你 + 群） │ ✅ zt#xxx 已修复（MR !123） └─────────────────────┘ </code></pre></div></div> <h3 id="114-pm-早会流程图900-cron-一次性-ack">11.4 PM 早会流程图：9:00 cron 一次性 ack</h3> <p>PM 不在每个任务上找你，而是每天早 9 点一次性给你一份「今天打算干啥」的 briefing：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>09:00 cron 触发 │ ├─► 拉 Confluence 过去 24h 更新的 PRD │ └─► 摘要每篇 PRD 的核心变更 │ ├─► 拉 ZenTao 新 P0/P1 bug │ └─► 按红线 grep 过滤 │ ├─► 拉企微 @机器人 消息（昨日 19:00 - 今早 9:00） │ ├─► 拉 GitLab 待合 MR（昨日新开 + 已挂 24h+） │ └─► 输出 Confluence 页面《YYYY-MM-DD 军团 briefing》 ├─ 今日计划自动派工（YELLOW，事后报） ├─ 今日计划走 canary（ORANGE，看灰度报告） ├─ 需你决策（RED，列具体 ack 点） └─ 推企微卡片 → @你 → 一次 ack │ ▼ 军团整天按 briefing 跑 异常才再次打扰你 </code></pre></div></div> <p><strong>关键</strong>：briefing 不是「请求批准」，而是「我准备这么干，除非你拦」。默认 30 分钟没回复就开跑（GREEN/YELLOW 部分），RED 部分等到回复才动。</p> <h3 id="115-角色协作时序图一个典型-bug-修复">11.5 角色协作时序图：一个典型 bug 修复</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>时间 Sentry Bridge ZenTao PM Worker GitLab Reviewer SecAud Watcher 企微 你 ───────────────────────────────────────────────────────────────────────────────── 10:14 alert 10:14 ──► filter 10:14 ──► create bug 10:30 scan (cron) 10:31 judge: auto / low 10:32 ──► spawn worker-3 10:32 ────────────────────────────► clone / branch 10:45 ──► run tests · open MR !456 10:46 ──► CI pipeline start 10:52 ──► pipeline ok 10:53 ──► review start ──► review start 10:58 ──► LGTM ──► no issue 10:58 verify: risk=low 10:59 ──► auto-merge 11:00 ──► merge !456 11:01 ──► deploy beta canary 11:01 ──► watch 30min 11:31 ──► SLO ok 11:32 ──► promote 100% 11:32 ◄── webhook: MR merged 11:32 ──► ZenTao bug status=resolved 11:33 ──► 卡片: zt#xxx ✅ → 私聊 11:33 ──► you see ✓ </code></pre></div></div> <p><strong>全程 79 分钟无人介入</strong>。你在 11:33 看到企微卡片，确认这条修复链路按预期跑完——以前需要 4h+ 你在线响应、5 次以上 ack 的工作。</p> <h3 id="116-部署到企微的两条铁律">11.6 部署到企微的两条铁律</h3> <ol> <li><strong>一个 bot 对应一个用途</strong>。不要让”军团 bot”同时发日报、ack 请求、监控告警——你会盲点。建议： <ul> <li><code class="language-plaintext highlighter-rouge">军团-播报</code> 群机器人 → 日报 / 一般通知（你可以静音）</li> <li><code class="language-plaintext highlighter-rouge">军团-ack</code> 群机器人 → 需要决策的 RED 类消息（不能静音）</li> <li><code class="language-plaintext highlighter-rouge">军团-告警</code> 群机器人 → P0 / canary 回滚 / 红线绕过（最高优先级）</li> </ul> </li> <li><strong>企微消息卡片要带”一键操作”</strong>。不要让你在企微看完还要切到 ZenTao / GitLab 才能操作。卡片里直接埋 deep link： <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌───────────────────────────────────────┐ │ 🟡 zt#1234 准备 auto-merge !456 │ │ risk=low · CI passed · 双 LGTM │ │ ─────────────────────────────────────│ │ [批准合并] [改 high] [看 diff] │ └───────────────────────────────────────┘ </code></pre></div> </div> <p>每个按钮调企微回调到你的网关，触发对应动作。</p> </li> </ol> <h3 id="117-这套案例最容易踩的-3-个坑">11.7 这套案例最容易踩的 3 个坑</h3> <ol> <li> <p><strong>ZenTao API 限流</strong>。Sentry Bridge 高峰期一秒建 10 条 bug，ZenTao 直接 429。解决：Bridge 加 token bucket（5 req/s），Sentry side 加 windowed 聚合。</p> </li> <li> <p><strong>Confluence 写入幂等问题</strong>。Daily Reporter 22:00 跑，如果失败重试，会重复创建当天报告。解决：用「日期 + 类型」做幂等键，存在即更新而非新建。</p> </li> <li> <p><strong>企微 webhook 不支持高交互卡片</strong>。原生 webhook 卡片按钮回调要走自建网关。如果你不想搭网关，退而求其次用「回复关键字」：你在群里回复 <code class="language-plaintext highlighter-rouge">ack 1234</code> 也能触发军团 ack 流程，PM 监听企微消息即可。</p> </li> </ol> <hr /> <h2 id="附录技术选型建议">附录：技术选型建议</h2> <h3 id="模型分层">模型分层</h3> <table> <thead> <tr> <th>层</th> <th>推荐模型</th> <th>替代</th> </tr> </thead> <tbody> <tr> <td>PM</td> <td>Claude Opus 4.7 / GPT-5 类强推理模型</td> <td>Claude Sonnet 4.6（预算紧）</td> </tr> <tr> <td>Worker</td> <td>Claude Sonnet 4.6 / GPT-4o 类性价比模型</td> <td>DeepSeek 类开源备选</td> </tr> <tr> <td>Auditor</td> <td>Claude Haiku 4.5 / Gemini Flash 类便宜快模型</td> <td>任意小模型</td> </tr> </tbody> </table> <h3 id="agent-容器">Agent 容器</h3> <ul> <li><strong>Claude Code</strong>：原生支持 <code class="language-plaintext highlighter-rouge">/team</code>、worktree 隔离、hook、cron，写本文时综合最成熟</li> <li><strong>Cursor / Windsurf</strong>：IDE 集成最好，但多 agent 编队需要自己搭</li> <li><strong>Aider / OpenHands</strong>：开源派，灵活但要自己搭基础设施</li> <li><strong>自建 Agent</strong>：用 LangGraph / AutoGen / Anthropic SDK 直接搭，最大自由度但工程投入最大</li> </ul> <p>不论选哪个，三层架构 + 红线 + canary 的核心原则不变。</p> <h3 id="反馈回路所需基础设施">反馈回路所需基础设施</h3> <ul> <li><strong>监控</strong>：Sentry / Bugsnag / Datadog / 自建 ELK 任选其一</li> <li><strong>Issue tracker</strong>：Jira / Linear / GitHub Issues / GitLab Issues 任选其一，要有 API</li> <li><strong>Git 平台</strong>：GitHub / GitLab / Gitea / 自建，要有 webhook</li> <li><strong>IM 通知</strong>：Slack / Discord / Telegram / 企微 / 飞书，任意能接 webhook 的都行</li> <li><strong>流量切分</strong>：nginx / envoy / Argo Rollouts / Flagger / 各家云原生</li> </ul> <p>每一项都不强求「最好」，强求<strong>有 API 可编程</strong>。</p>

从单兵 Copilot 升级到 PM/Worker/Auditor 三层架构 AI 军团的 4-6 周施工路线图，含 GitLab + ZenTao + Confluence + 企微 + Sentry/Grafana 完整案例编制。

2026-05-11T04:00:00+00:00 2026-05-11T04:00:00+00:00 https://jinzi.cyou/posts/game-engine-vs-aigc-pipeline-feasibility <h2 id="0-这类3d-同人剧的工艺本质">0. 这类”3D 同人剧”的工艺本质</h2> <p>这类视频本质上<strong>不是 AI 生成</strong>，而是用 MMORPG（如《剑网3》）的<strong>游戏客户端</strong>做的同人剧。所谓”场景一致性完美 + 比 AI 好看”的原因：</p> <ul> <li>每个镜头都是同一份<strong>持久 3D 世界</strong>（同一份几何 + 材质 + 骨骼 + 光照）的实时渲染快照</li> <li>角色是游戏角色编辑器深度捏脸 + 时装系统 + 第三方外观 mod</li> <li>场景是游戏本体地图 + 家园系统物件摆放</li> <li>镜头是游戏内自由视角（freecam）+ ReShade 后期 LUT</li> <li>多镜跳切无漂移，因为<strong>所有镜头共享同一份 3D 资产</strong>——这是当前所有 i2v/t2v 模型都做不到的</li> </ul> <p>判定特征（怎么一眼认出是游戏引擎拍的）：</p> <ol> <li>视频里出现游戏标准样式的角色名牌立绘条</li> <li>服饰、骨架、动作都是该游戏典型门派风格</li> <li>群演 NPC、载具、半透片状树叶、雪地材质都是该引擎资源</li> <li>眼睛贴图过亮、皮肤次表面假、嘴唇高光偏卡通——这是上一代 MMO 自研引擎实时渲染的典型特征</li> </ol> <p>同类思路还有 MMD 圈（拆 FF14 / 原神模型），是同一方法论的不同载体。</p> <hr /> <h2 id="1-能否直接复刻到佛经题材项目">1. 能否直接复刻到佛经题材项目</h2> <p><strong>不能</strong>。核心问题：题材完全错位。</p> <table> <thead> <tr> <th>维度</th> <th>MMO 仙侠</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> <tr> <td>角色</td> <td>中原人面孔</td> <td>印度面孔比例</td> </tr> <tr> <td>植被</td> <td>中国南北方植被</td> <td>菩提、莎罗双树、阎浮</td> </tr> </tbody> </table> <p>现成 MMO 的所有资产（场景/服饰/骨骼/植被）对佛经题材都<strong>零复用</strong>，必须重做。</p> <p>但<strong>思路可移植</strong>：在另一个引擎里搭建一份”项目专属的持久 3D 世界”，从此每个镜头都是该世界的实时渲染快照。</p> <hr /> <h2 id="2-替代引擎方案对比">2. 替代引擎方案对比</h2> <table> <thead> <tr> <th>方案</th> <th>引擎</th> <th>角色系统</th> <th>资产路径</th> <th>上手</th> <th>适用度</th> </tr> </thead> <tbody> <tr> <td><strong>A. UE5 + MetaHuman + Quixel</strong></td> <td>Unreal 5.5</td> <td>MetaHuman + CC4</td> <td>Megascans 免费 + Sketchfab/ArtStation 买印度建筑/服饰</td> <td>难</td> <td>★★★★★ 主推</td> </tr> <tr> <td><strong>B. iClone 8 + CC4 → UE5 LiveLink</strong></td> <td>iClone 拍 + UE 渲</td> <td>CC4</td> <td>Reallusion 商店 + 自建</td> <td>中</td> <td>★★★★ 剧情向友好</td> </tr> <tr> <td>C. Unity HDRP</td> <td>Unity</td> <td>UMA</td> <td>Asset Store</td> <td>中</td> <td>★★★ 资产池不及 UE</td> </tr> <tr> <td>D. Blender Eevee 实时</td> <td>Blender</td> <td>Daz/自建</td> <td>全自建</td> <td>难</td> <td>★★ 全自由但巨耗时</td> </tr> <tr> <td>E. Daz Studio + iClone</td> <td>Daz</td> <td>Genesis 9</td> <td>Daz 商店</td> <td>易</td> <td>★★ 卡通感重</td> </tr> </tbody> </table> <p>主推 <strong>A 或 B</strong>。B 更适合剧情向单人作者。</p> <hr /> <h2 id="3-资产可获得性最大瓶颈">3. 资产可获得性（最大瓶颈）</h2> <table> <thead> <tr> <th>类别</th> <th>现成资源情况</th> <th>自建工作量</th> </tr> </thead> <tbody> <tr> <td>古印度宫殿 / 精舍 / 竹林精舍</td> <td>Sketchfab / ArtStation 零散，约 30% 可用</td> <td>改建 + 整合需 2-4 周</td> </tr> <tr> <td>比丘 / 沙门服饰、袈裟</td> <td><strong>几乎没有</strong></td> <td>Marvelous Designer 自建，1 件 1-3 天</td> </tr> <tr> <td>古印度俗人服饰、刹帝利铠</td> <td>少量 Daz / CC4 资产</td> <td>大量改装</td> </tr> <tr> <td>佛陀 / 阿罗汉 / 天王 / 龙王面相</td> <td><strong>零</strong></td> <td>MetaHuman 改 + ZBrush 雕刻</td> </tr> <tr> <td>印度植物（菩提、阎浮、莎罗双树）</td> <td>Megascans 有亚热带，需调色</td> <td>中</td> </tr> <tr> <td>法器（钵、锡杖、贝叶经、佛塔）</td> <td>Sketchfab 零散</td> <td>小量自建</td> </tr> <tr> <td>印度面孔骨骼比例</td> <td>MetaHuman 调参可达 80%</td> <td>头模改</td> </tr> </tbody> </table> <p><strong>核心痛点</strong>：佛教题材在全球 3D 资产市场极度冷门，MMO 那种”开箱即拍”在这里不存在。<strong>第一季的资产铺设期会是整个项目最重的成本。</strong></p> <hr /> <h2 id="4-硬件--软件费用">4. 硬件 &amp; 软件费用</h2> <h3 id="一次性投入人民币">一次性投入（人民币）</h3> <table> <thead> <tr> <th>项目</th> <th>金额</th> <th>备注</th> </tr> </thead> <tbody> <tr> <td>RTX 4090 / 5090 整机</td> <td>¥15-25k</td> <td>按小时租的云 GPU 跑 UE 不现实，必须本地</td> </tr> <tr> <td>iClone 8 + CC4 + plugins</td> <td>约 ¥7k</td> <td>永久</td> </tr> <tr> <td>Marvelous Designer</td> <td>¥3k 永久 / ¥400 月</td> <td>服饰必备</td> </tr> <tr> <td>ZBrush（雕刻头模）</td> <td>¥6k 永久</td> <td>也可订阅</td> </tr> <tr> <td>初始资产采购（场景+角色+服饰）</td> <td>¥3-15k</td> <td>取决于自建比例</td> </tr> <tr> <td>Mocap（可选）</td> <td>¥0-18k</td> <td>iPhone + Move.ai 起步；正经 Rokoko 套装 ¥18k</td> </tr> <tr> <td>UE5 / MetaHuman / Quixel</td> <td><strong>¥0</strong></td> <td>影视用途免费</td> </tr> <tr> <td><strong>合计</strong></td> <td><strong>¥30-60k</strong></td> <td> </td> </tr> </tbody> </table> <h3 id="月度运营">月度运营</h3> <ul> <li>软件订阅 + 偶发资产：¥500-1500</li> <li>电费：忽略</li> </ul> <h3 id="单集边际成本">单集边际成本</h3> <p>电费几十块，<strong>接近 0</strong>。</p> <h3 id="对比当前-ai-路径">对比当前 AI 路径</h3> <table> <thead> <tr> <th>维度</th> <th>当前 AI 路径</th> <th>引擎路径</th> </tr> </thead> <tbody> <tr> <td>前期投入</td> <td>已沉没</td> <td>¥30-60k</td> </tr> <tr> <td>单集成本</td> <td>¥100-300（AI 抽卡）</td> <td>约 ¥0（电费）</td> </tr> <tr> <td>角色一致性</td> <td>抽卡，需 face-lock 协议</td> <td><strong>免费</strong>，引擎级保证</td> </tr> <tr> <td>场景一致性</td> <td>3D 重建 + ControlNet 缝合</td> <td><strong>免费</strong>，引擎级保证</td> </tr> <tr> <td>镜头自由度</td> <td>受 i2v 时长/可控性限制</td> <td>100% 自由</td> </tr> <tr> <td>出片质感</td> <td>取决于 prompt + 抽卡</td> <td>取决于资产 + 灯光功力</td> </tr> </tbody> </table> <p><strong>盈亏平衡点</strong>：约 80-150 集（按单集 AI ¥200 估算）。</p> <hr /> <h2 id="5-时间--人力">5. 时间 &amp; 人力</h2> <h3 id="单人作者">单人作者</h3> <table> <thead> <tr> <th>阶段</th> <th>时长</th> <th>内容</th> </tr> </thead> <tbody> <tr> <td>学习期</td> <td>3-6 月</td> <td>UE5 sequencer / MetaHuman / iClone / Marvelous Designer / 灯光摄影</td> </tr> <tr> <td>资产铺设</td> <td>2-4 月</td> <td>主角×5、配角×10、3 套核心场景、20+ 件服饰</td> </tr> <tr> <td>工艺定型</td> <td>1 月</td> <td>跑通”分镜 → mocap → 表情 → 渲染 → 合成”链路</td> </tr> <tr> <td>单集稳定产能</td> <td>—</td> <td>3-7 天/集</td> </tr> </tbody> </table> <p><strong>最快第一集试拍出片</strong>：从启动起约 <strong>5-8 个月</strong>。</p> <h3 id="多人协作1-2-外援">多人协作（+1-2 外援）</h3> <ul> <li>美术外包做服饰 + 印度角色头模：¥3-8k / 角色，省 2-3 月</li> <li>配音保持现有（通用 TTS 已够用）</li> <li>可压缩到约 <strong>3-5 个月</strong>出第一集</li> </ul> <h3 id="行业参考">行业参考</h3> <p>成熟的同类单人作者公开访谈数据：单集 5-8 分钟耗时 <strong>2-4 周</strong>，且是 2-3 年沉淀后的稳定产能，第一集做了约 3 个月。</p> <hr /> <h2 id="6-致命陷阱">6. 致命陷阱</h2> <ol> <li><strong>题材资产稀缺</strong>：现成 MMO 抄作业不可能，每件袈裟 / 每个佛塔可能都要自建。</li> <li><strong>印度面孔的恐怖谷</strong>：MetaHuman 默认欧亚审美，调成”经像感”印度面孔难度极高，调不好就是”白人涂深粉底”。</li> <li><strong>题材尺度 vs 真人 mocap</strong>：让 mocap 演员演绎宗教场景的尺度问题（这也是为什么全网几乎没人做佛教 3D 剧）。</li> <li><strong>学习曲线悬崖</strong>：UE5 sequencer + MetaHuman Animator 不是”丢 prompt 等出片”工艺，前 2 个月会非常难受。</li> <li><strong>沉没成本</strong>：当前 AI 路径已有积累、流水线、角色锁脸、3D 场景库，全切引擎意味着这些全部作废。</li> </ol> <hr /> <h2 id="7-推荐路径不全-pivot">7. 推荐路径（不全 pivot）</h2> <p><strong>不要现在全切。</strong> 具体做法分四步：</p> <h3 id="phase-1继续-ai-路径出完第一季">Phase 1：继续 AI 路径出完第一季</h3> <p>不耽误进度，用现有 AI 生成 + Blocking + 3D 场景 + face-lock 协议。</p> <h3 id="phase-2用-2-3-周做-ue5-试拍实验并行">Phase 2：用 2-3 周做 UE5 试拍实验（并行）</h3> <p>最小投入验证可行性：</p> <ul> <li>购买 CC4 + iClone trial</li> <li>买一套印度场景资产（约 ¥1-2k）</li> <li>MetaHuman 改 1 个印度面孔头模</li> <li>做一段 60 秒试拍</li> <li><strong>同一镜头：AI 版 vs 引擎版同台对照</strong></li> </ul> <h3 id="phase-3看试拍结果决策">Phase 3：看试拍结果决策</h3> <ul> <li>引擎版明显赢 → 第二季全切 UE5</li> <li>引擎版没赢明显 / 学习曲线劝退 → 继续 AI 路径，把预算花在 prompt + 后期</li> <li>不确定 → 再做一组对照样本</li> </ul> <h3 id="phase-4混合工艺也是选项">Phase 4：混合工艺也是选项</h3> <ul> <li>场景用 UE5 / 3D 重建固化（一致性强）</li> <li>角色 + 表演用 AI（产能强）</li> <li>中间用 i2i / ControlNet 缝合</li> </ul> <p>这条路径其实是当前项目已经在走的（3D 场景跨镜空间一致 + AI 角色），UE5 化只是把”场景固化”这一环升级。</p> <hr /> <h2 id="8-下一步可做的研究">8. 下一步可做的研究</h2> <ul> <li>列出已用到的所有场景/角色/服饰，标注 UE5 路径下各项的获取/自建成本（资产缺口表）</li> <li>UE5 试拍最小购物清单 + 4 周周计划</li> <li>调研其他”游戏引擎拍剧”案例（FF14 同人剧、原神 MMD、Roblox 短剧），看是否有更接近佛教/印度题材的资产池</li> <li>调研 ZBrush + MetaHuman 印度面孔工艺现状（教程密度）</li> <li>评估”MMO mod 改造”路径在法律/技术上的可行性（结论很可能是否定）</li> <li>调研 Unreal Marketplace 上”古印度 / 东南亚 / 东方寺院”资产包覆盖度</li> </ul> <hr /> <h2 id="9-一句话结论">9. 一句话结论</h2> <p>游戏引擎实时渲染模式技术上可移植到佛经题材短剧，<strong>但前期投入 ¥30-60k + 5-8 个月学习与资产铺设</strong>才能出第一集，<strong>且约 70% 的精力会花在自建佛教/印度资产上</strong>（现成 MMO 那种开箱即拍的红利不存在）。建议小成本试拍验证，不要现在就全 pivot 放弃 AI 路径的既有积累。</p>

抖音上一些"3D 同人剧"账号，场景一致性和画面质感明显优于纯 AI 生成路径。调研发现它们根本不是 AI 生成，而是用游戏客户端实时渲染拍出来的。本文评估这套工艺能否移植到一个 AIGC 佛经题材短剧项目，并把游戏引擎路径与 AI 生成路径做成本、时间、一致性的全面对照。

2026-05-10T04:00:00+00:00 2026-05-10T04:00:00+00:00 https://jinzi.cyou/posts/aigc-comfyui-zimage-character-design <h2 id="tldr">TL;DR</h2> <ol> <li><strong>Base 模型选型反转</strong>：FLUX.2 Dev → <strong>Z-Image Turbo</strong>（阿里 Tongyi-MAI，2025-10 发布）。第三方实测 Z-Image 皮肤细节优于 Flux.1 / Qwen-Image / HiDream / <strong>Flux.2 Dev</strong>，中文原生强、HF 不 gated、单卡 32GB 富裕。</li> <li><strong>ComfyUI 全栈在单卡 5090 部署完成</strong>：Z-Image 31G + IPAdapter 6.3G + ControlNet Union 2.4G + 5 个关键节点。</li> <li><strong>自托管视频通道</strong>（Wan 2.2）调研出场：Animate V2 是”AI 演员替身”杀器，潜在全季可省约 ¥7700-7900。</li> <li><strong>一个神话角色形象迭代失败案例</strong>：v0→v3 始终调不对，暴露出文生图在”多个神话特征叠加约束”下的执行力短板。</li> </ol> <hr /> <h2 id="1-base-模型选型反转">1. Base 模型选型反转</h2> <h3 id="调研结论">调研结论</h3> <table> <thead> <tr> <th>模型</th> <th>写实/皮肤</th> <th>LoRA VRAM</th> <th>中文</th> <th>HF gating</th> </tr> </thead> <tbody> <tr> <td><strong>Z-Image Turbo</strong></td> <td>第三方实测优于 Flux.2 Dev</td> <td>12-16 GB</td> <td>双语强</td> <td>不 gated</td> </tr> <tr> <td>Qwen-Image-2512</td> <td>强写实 + 强文字</td> <td>32 GB+</td> <td>强</td> <td>不 gated</td> </tr> <tr> <td>Flux.2 Dev</td> <td>“脸软糊、AI 感明显”</td> <td>30 GB int8 / 96 GB full</td> <td>中等</td> <td>gated</td> </tr> <tr> <td>Flux.2 Klein</td> <td>蒸馏版速度优先</td> <td>12 GB</td> <td>中等</td> <td>gated</td> </tr> <tr> <td>Flux.1 Dev</td> <td>老牌 2024 标杆</td> <td>24 GB</td> <td>弱</td> <td>gated</td> </tr> </tbody> </table> <p><strong>为什么反转</strong>：上一阶段卡在 Flux 的 license gating，需要官方 token 才能拉权重。而 Z-Image Turbo 不仅在第三方实测里皮肤细节更好，且完全不 gated、中文原生强、单卡 32GB 训练 LoRA 还很富裕——gating 阻塞问题随选型自动消失。</p> <p><strong>LoRA 训练关键参数</strong>（针对 Z-Image）：</p> <ul> <li><code class="language-plaintext highlighter-rouge">linear_rank: 64</code>（不是 16/32，皮肤细节强相关）</li> <li>推荐 70-80 张数据</li> <li>4000 steps（不是 800-1000）</li> <li>单卡 32GB 可同时训 2 个角色</li> </ul> <p>按 5090 约 ¥2.78/h 估算，rank-64 + 4000 steps 的单角色训练成本约 ¥3-5。</p> <hr /> <h2 id="2-自托管视频通道wan-22调研未启动">2. 自托管视频通道（Wan 2.2，调研未启动）</h2> <h3 id="经济性">经济性</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>商用 i2v: 约 ¥0.75/秒，按 60 集 × 30 镜 × 6s 估 ≈ ¥8100 Wan 2.2 自托管: 约 ¥0.5/6s，全季约 ¥150-300 + LoRA 训练 ¥80-230 潜在节省: 约 ¥7700-7900 </code></pre></div></div> <h3 id="wan-22-animate-v2--ai-演员替身">Wan 2.2 Animate V2 = “AI 演员替身”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>单角色参考图 + driving pose video (OpenPose) + 角色 LoRA → SAM 2 mask + face crop + CLIP vision embed 多重融合 → 输出该角色按指定 pose 动作的高写实视频 </code></pre></div></div> <p>变体：Wan2.2-TI2V-5B（24GB 入门验证）、Wan2.2-14B I2V（FP8 16GB 生产）、Wan 2.2 Animate V2（14B + IP-Adapter，FP8 约 20GB）。</p> <p><strong>决策：不立刻上</strong>。当前 Z-Image 静态生图尚未验证完，同时上两个新模型会让问题源头混淆；且视频 LoRA ≠ 图像 LoRA 需重训。待 Z-Image LoRA 通关后再做 i2v 对照实验。</p> <hr /> <h2 id="3-comfyui-全栈部署单卡-5090">3. ComfyUI 全栈部署（单卡 5090）</h2> <h3 id="节点">节点</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ComfyUI core + ComfyUI-Manager + ComfyUI_IPAdapter_plus + comfyui_controlnet_aux + PuLID_ComfyUI + ComfyUI-Impact-Pack (FaceDetailer) </code></pre></div></div> <h3 id="模型">模型</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>checkpoints/z-image-turbo 31 GB (Z-Image Turbo 全套) ipadapter/sdxl_models/* 6.3 GB (IPAdapter Plus + CLIP-ViT-H image_encoder) controlnet/union-sdxl/* 2.4 GB (xinsir Union promax SDXL) </code></pre></div></div> <p>重启实例后模型与节点直接可用，无需重下，停机期间只按存储计费。</p> <hr /> <h2 id="4-神话角色形象迭代失败案例">4. 神话角色形象迭代（失败案例）</h2> <p>这一节是个反面教材：一个佛教/印度神话角色（帝释天）的形象，从 v0 调到 v3 始终不对，最后暂停。它很好地暴露了文生图在叠加约束下的短板。</p> <h3 id="v0--错误的设计">v0 — 错误的设计</h3> <p>最初的 4 张参考图把多个印度神祇的特征拼在了一起：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>✗ 4 只手 ← 实为毗湿奴标志 ~ 第三眼 ← 实为可选 canonical（后续保留） ✗ 蓝皮 ← 克里希纳/毗湿奴标志（佛教帝释天应为金身） ✗ 5 层塔冠 ← 应是扇形宽冠 ✗ 持莲花 ← 观音/弥勒标志，非帝释天 ✓ 金刚杵 ← 正确 </code></pre></div></div> <p><strong>问题来源</strong>：原 prompt 把不同神祇特征拼接，造出了一个”伪混合神”。这说明角色考据没做对，后面再怎么生图都是错的——形象设计的源头错误会污染整条训练数据链。</p> <h3 id="经典考据后的正确依据">经典考据后的正确依据</h3> <table> <thead> <tr> <th>特征</th> <th>经典</th> </tr> </thead> <tbody> <tr> <td>手数</td> <td><strong>2 手</strong>（右金刚杵，左施印或持物）</td> </tr> <tr> <td>第三眼</td> <td>壁画/雕塑常见，<strong>保留</strong></td> </tr> <tr> <td>肤色</td> <td><strong>金身</strong>（光明神圣尊贵）</td> </tr> <tr> <td>冠</td> <td>扇形宽冠（非塔冠）</td> </tr> <tr> <td>装束</td> <td>璎珞 + 天衣飘逸</td> </tr> <tr> <td>坐骑</td> <td>六牙白象（场景中可出现）</td> </tr> <tr> <td>汉地特色</td> <td>少年帝王 / 男人女相</td> </tr> </tbody> </table> <h3 id="v2--v3--改用中文-prompt--加三目金身男人女相">v2 / v3 — 改用中文 prompt + 加三目/金身/男人女相</h3> <p>依正确考据重做了两轮：v2 给出唐宋宫廷少年帝王、西域金身、天宫云海等 8 个方向，反馈”基本都不行”——缺三目、男人女相不够、金身感弱、过于普通帝王。v3 针对性补三目 + 男人女相 + 金身又出 6 张，最终判定<strong>效果仍不行，暂停</strong>。</p> <h3 id="推测瓶颈">推测瓶颈</h3> <ol> <li><strong>文生图对”三目 + 金身 + 男人女相”叠加约束执行力弱</strong>：任意 1 个特征可能被丢失。</li> <li><strong>写实 prompt 与神话特征（三目/金身）内在矛盾</strong>：模型偏向画”普通古装帝王”，把超现实特征当噪声丢掉。</li> <li><strong>“男人女相”是模糊概念</strong>：模型理解成”娘炮”或”中性”，而非正确的”汉地少年帝王秀美而威严”。</li> <li><strong>“金身”容易降级</strong>：变成”金黄色衣服”或”古铜色皮肤”，而非真正的”光明神圣金光”。</li> </ol> <h3 id="可能的修复方向未实测">可能的修复方向（未实测）</h3> <ul> <li><strong>改换工具</strong>：换中文/古风更强的写实模型（Z-Image Turbo / Qwen-Image）。</li> <li><strong>i2i 启动</strong>：先找一张经典壁画/造像（如敦煌壁画）作 ref，i2i 出现代写实版，用真实参考锚住超现实特征。</li> <li><strong>概念分层</strong>：先出”少年男人女相帝王”基础像（无三目无金身），再 i2i 加金身，再 inpaint 加三目——把叠加约束拆成串行步骤。</li> <li><strong>找现成 LoRA</strong>：社区可能已有同名神话角色 LoRA，可作 starting point。</li> </ul> <hr /> <h2 id="5-远端工作流-4-个踩坑">5. 远端工作流 4 个踩坑</h2> <p>把模型权重下到按小时租的云 GPU 上，踩到 4 个值得记的坑：</p> <h3 id="51-huggingface-cli-download-已弃用">5.1 huggingface-cli download 已弃用</h3> <p>新版 huggingface_hub（&gt;=0.26）弃用了 <code class="language-plaintext highlighter-rouge">huggingface-cli download</code>，原 setup 脚本里所有 download 步骤静默失败（节点装好了但模型一个没下）。改用 python <code class="language-plaintext highlighter-rouge">from huggingface_hub import snapshot_download</code> 直接调用。</p> <h3 id="52-下载后-copy-导致磁盘翻倍">5.2 下载后 copy 导致磁盘翻倍</h3> <p><code class="language-plaintext highlighter-rouge">snapshot_download</code> 把模型下到 cache 目录后，如果再 <code class="language-plaintext highlighter-rouge">shutil.copy2()</code> 到目标位置，<strong>磁盘占用翻倍</strong>：31GB 的模型 cache + target = 62GB，直接爆掉 50GB 的数据盘。修复：用 <code class="language-plaintext highlighter-rouge">os.rename(src, dst)</code> 替代 copy——同一文件系统上是 O(1) 的 inode 重命名，不占额外空间。</p> <h3 id="53-国际镜像-ssl-反复-timeout">5.3 国际镜像 SSL 反复 timeout</h3> <p>国际镜像站在密集大文件下载时频繁报 <code class="language-plaintext highlighter-rouge">SSL handshake operation timed out</code>，即使开了学术加速也没救，大模型连下两次都超时。修复：阿里出品的模型（Z-Image / Qwen-Image / Wan）改走 <strong>ModelScope</strong>——国内通道满速、多文件并发、0 失败。</p> <h3 id="54-cache_dir-与-local_dir-语义不一致">5.4 cache_dir 与 local_dir 语义不一致</h3> <p>不同 SDK 行为不同：HF 的 <code class="language-plaintext highlighter-rouge">snapshot_download(local_dir=...)</code> 直接放目标位置；ModelScope 的 <code class="language-plaintext highlighter-rouge">snapshot_download(cache_dir=...)</code> 只指定 cache 根，实际文件落在 <code class="language-plaintext highlighter-rouge">cache_dir/&lt;owner&gt;/&lt;repo&gt;/</code> 下，需要再 <code class="language-plaintext highlighter-rouge">os.rename</code> 移到目标位置。</p> <hr /> <h2 id="6-关键决策小结">6. 关键决策小结</h2> <ul> <li>Base 模型主通道：FLUX.2 Dev → <strong>Z-Image Turbo</strong></li> <li>ComfyUI 全栈部署完成</li> <li>阿里系模型走 ModelScope 优于国际镜像</li> <li><code class="language-plaintext highlighter-rouge">os.rename</code> 优于 <code class="language-plaintext highlighter-rouge">shutil.copy2</code>（受限磁盘下避免翻倍）</li> <li><code class="language-plaintext highlighter-rouge">huggingface-cli download</code> → <code class="language-plaintext highlighter-rouge">snapshot_download</code> python API</li> <li>自托管视频通道（Wan 2.2）暂缓，待静态生图通关</li> </ul> <p>最大的开放问题仍是神话角色形象怎么走：是找现成社区 LoRA、用经典壁画作 i2i seed，还是接受不完美先训起来——这本质上是”超现实角色 + 写实质感”这对矛盾约束在当前文生图工具下的工程取舍。</p>

这是 AIGC 短剧角色一致性工艺的第二阶段实录：为什么把写实 base 从 FLUX.2 Dev 反转到 Z-Image Turbo，ComfyUI 全栈在消费级显卡上的部署清单，以及一个"神话角色形象怎么也调不对"的失败案例和它暴露出的 text2image 多约束叠加的执行力短板。

2026-05-09T04:00:00+00:00 2026-05-09T04:00:00+00:00 https://jinzi.cyou/posts/aigc-3d-scene-and-character-lora <h2 id="tldr">TL;DR</h2> <table> <thead> <tr> <th>路径</th> <th>结论</th> <th>单位成本</th> </tr> </thead> <tbody> <tr> <td><strong>World Labs Marble 单图</strong></td> <td>跨镜空间方案的实测最优解</td> <td>¥10-20 / 场景</td> </tr> <tr> <td><strong>Marble 多图（i2i 拼多视角）</strong></td> <td><strong>反向优化</strong>——i2i 几何不一致让 Marble 拼缝鬼影</td> <td>浪费的 ¥10-20</td> </tr> <tr> <td><strong>Apple SHARP（单卡 monocular）</strong></td> <td>喷泉锥，仅 ±10° 微调，不能跨镜</td> <td>¥0</td> </tr> <tr> <td><strong>Zero123++</strong></td> <td>几何严格一致但风格”3D 玩具感”，对写实剧不适用</td> <td>¥0.5 / 推理</td> </tr> <tr> <td><strong>SDXL LoRA 角色锁</strong></td> <td>5 张图 800 步即可锁 4 臂/3 眼这种违反常识特征</td> <td>¥0.6 / 角色</td> </tr> <tr> <td><strong>Flux LoRA</strong>（未实测）</td> <td>写实天花板远高于 SDXL，但被 HF gating 阻塞</td> <td>¥1.5-2 / 角色</td> </tr> </tbody> </table> <p><strong>最终推荐工艺</strong>：<strong>Marble 单图 anchor（关键场景）+ LoRA 锁角色 + ControlNet 控镜（同场切镜）</strong>。</p> <blockquote> <p>测试对象是一个 AIGC 佛经题材短剧项目，需要大量”同场多镜”和”同角色跨集”的镜头。</p> </blockquote> <hr /> <h2 id="1-跨镜-3d-场景生成同场切镜不错乱">1. 跨镜 3D 场景生成（”同场切镜不错乱”）</h2> <h3 id="11-world-labs-marble--主通道">1.1 World Labs Marble — 主通道</h3> <p>World Labs Marble 接受一张图，约 5 分钟产出一个完整 3D 世界，输出：</p> <ul> <li><code class="language-plaintext highlighter-rouge">splat.spz</code> 约 30 MB（full）+ 500k/150k/100k 三档精简</li> <li><code class="language-plaintext highlighter-rouge">mesh.glb</code> 1-5 MB（碰撞网格）</li> <li><code class="language-plaintext highlighter-rouge">pano.png</code> 约 12 MB（360 全景）</li> <li>元数据 JSON（含 <code class="language-plaintext highlighter-rouge">metric_scale_factor</code> 度量尺度）</li> </ul> <p>把它作为关键场景的空间锚点：同一场景内的多个镜头都从这一份持久世界里取视角，几何/比例/光照天然一致，这是当前任何 i2v/t2v 模型都做不到的。</p> <p>一个值得记的实现坑：user prompt 会被 Marble 的 VLM 自动扩展成一长段场景描述写进 world 元数据，所以输入图本身的信息量决定了重建质量，文字提示只是辅助。</p> <h3 id="12-多图融合的反向优化教训">1.2 多图融合的反向优化（教训）</h3> <p><strong>假设</strong>：用图生图（i2i）出 4 个不同 azimuth 视角图，喂 Marble 的 multi-image 接口，应该比单图更好。</p> <p><strong>实测</strong>：<strong>比单图差</strong>。多图版在缩略图角落出现明显的<strong>拼缝鬼影</strong>，单图版反而干净。</p> <p><strong>根因</strong>：i2i 出的 4 张”伪多视角”<strong>几何不严格一致</strong>——同一根立柱在 4 张图里位置/比例都在漂移。Marble 把它们当作真实多视角做光束法平差（bundle adjustment）时，不一致的几何被强行对齐，引入鬼影。</p> <p><strong>结论</strong>：除非用专门训练几何一致性的多视角扩散模型（Zero123++ / Wonder3D），否则”i2i 凑多视角”喂 Marble = 浪费算力 + 劣化质量。单图反而是更稳的输入。</p> <h3 id="13-apple-sharp--免费但有限">1.3 Apple SHARP — 免费但有限</h3> <p>Apple 开源的 SHARP 在一块消费级 Apple Silicon（M1 16GB，Metal 后端）上做 monocular 重建，fp32 推理约 33 秒，输出约 118 万 gaussian 的 <code class="language-plaintext highlighter-rouge">.ply</code>（约 64 MB）。</p> <p>两个限制：</p> <ul> <li>其 <code class="language-plaintext highlighter-rouge">render</code> 子命令强制 CUDA，Apple Silicon 跑不了它自带的渲染器，需要自己用 Blender Geometry Nodes 把 mesh 转点云 + Cycles GPU 渲染（实测约 12s/帧 1280×720）。SH degree-0 的颜色解码公式是 <code class="language-plaintext highlighter-rouge">rgb = clamp(0.5 + 0.28209479 * f_dc, 0, 1)</code>。</li> <li><strong>根本限制</strong>：SHARP 是 monocular depth lift，重建结果是从原相机方向往前的”喷泉锥”，背面/侧面是真空白。<strong>只适合原视角微调（dolly / 微 pan）</strong>，不能跨镜切场。</li> </ul> <h3 id="14-zero123--几何对了风格变了">1.4 Zero123++ — 几何对了风格变了</h3> <p>在一块 RTX 5090（32GB，fp16）上推理约 3.1 秒（Apple Silicon fp32 OOM 静默死，fp16 因 MPS NaN 不可用）。输入单图 → 输出 6 个固定视角（azimuth 30/90/150/210/270/330 配 elevation ±20/±10），3×2 网格 320×320。</p> <p><strong>问题</strong>：6 视角几何严格一致没问题，但<strong>风格变成”3D 玩具 / 塑料”</strong>——Zero123++ 训练数据偏 Objaverse 几何资产，没学到照片级写实。对写实风格短剧不适用，对玩具/物体题材可能可行。</p> <p><strong>替代方向</strong>（未实测）：Era3D / Wonder3D / EscherNet 据称对 scene 写实保留更好。</p> <h3 id="15-hunyuan-world-20备选未实测">1.5 Hunyuan World 2.0（备选未实测）</h3> <p>腾讯开源、Apache 2.0，自托管需要 24-32 GB VRAM（5090 完全 cover），输出格式比 Marble 还全：mesh + 3DGS + 深度图 + 法线图 + 相机参数。在线 demo 必须登录腾讯账号、无法自动化，所以暂未纳入流水线，但作为”自托管替代 Marble”的长期选项很有吸引力。</p> <hr /> <h2 id="2-角色-lora-训练跨镜跨集角色不漂">2. 角色 LoRA 训练（”跨镜跨集角色不漂”）</h2> <p>工具栈是 <code class="language-plaintext highlighter-rouge">ostris/ai-toolkit</code>（GitHub）+ SDXL 1.0 / Flux.1-dev，在一块按小时租的云 GPU（5090，约 ¥2.78/h）上训练。</p> <p>每个角色用一个不含宗教专名的触发词（这是规避内容过滤的小技巧），配上简化角色描述与姿态修饰，自动生成 caption。示例（佛经/神话公共领域人物）：</p> <ul> <li>阿阇世王 — 紫袍重金 + 凶相 + 红宝石冠 + 匕首</li> <li>帝释天 — 蓝皮 + <strong>4 臂 + 3 眼</strong> + 多层冠</li> <li>毗沙门天王 — 金甲 + 红披风 + 持伞和宝塔</li> </ul> <p>数据量：每角色仅 4-5 张（远低于推荐的 20-50 张）。</p> <h3 id="21-sdxl-实测结果">2.1 SDXL 实测结果</h3> <p><strong>配置</strong>：SDXL 1.0 + LoRA dim 32 + bf16 + adamw8bit + 800 steps + lr 1e-4</p> <table> <thead> <tr> <th>角色</th> <th>训练时长</th> <th>成本</th> <th>关键特征锁定</th> <th>评价</th> </tr> </thead> <tbody> <tr> <td><strong>阿阇世王</strong></td> <td>约 12.5 min</td> <td>¥0.6</td> <td>紫袍 + 重金 + 凶相 + 黑络腮胡 + 红宝石冠 + 孔雀翎 + 匕首 + 虎纹底</td> <td>全锁</td> </tr> <tr> <td><strong>帝释天</strong></td> <td>约 13 min</td> <td>¥0.6</td> <td><strong>4 臂 + 3 眼</strong> + 蓝肤 + 多层冠 + 蓝金星纹长袍 + 天宫云海</td> <td>全锁</td> </tr> </tbody> </table> <p><strong>关键发现</strong>：5 张图 + 800 steps 就能锁住<strong>“4 臂 + 3 眼”</strong>这种违反人体常识的特征——这是 SDXL base 默认完全画不出的（它会把帝释天画成 1-2 臂、无第三眼）。也就是说，对于强角色记忆，训练图数量可以远低于通常建议值，前提是这些图把目标特征讲清楚了。</p> <h3 id="22-sdxl-的天花板也是切-flux-的理由">2.2 SDXL 的天花板（也是切 Flux 的理由）</h3> <p>虽然特征锁定 OK，但 SDXL 输出有挥之不去的<strong>“render 感 / 塑料感”</strong>——织物纹理不真、金属皮纸糊、皮肤毛孔失真，整体是”AI 海报感”而非”剧照感”。这是 SDXL 的写实天花板，<strong>LoRA 改不了</strong>，要写实必须换 base 模型。</p> <h3 id="23-flux-路径被阻塞">2.3 Flux 路径被阻塞</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>FLUX.1-dev → gated（non-commercial），需 HF token + accept license FLUX.1-schnell → 早期 Apache 2.0，后被收紧也 gated（实测国内镜像也 403） </code></pre></div></div> <p>Flux 写实天花板远高于 SDXL，但门槛卡在 license gating（镜像站不绕过 gated repo，仍需官方 token）。重训成本约 30-45 min/角色。这个阻塞在后续的模型选型中被另一条路径绕开了（见姊妹篇 Z-Image Turbo 选型）。</p> <h3 id="24-5-张图也是瓶颈独立于模型选择">2.4 5 张图也是瓶颈（独立于模型选择）</h3> <p>LoRA 通常推荐 15-50 张训练图，5 张容易过拟合或漂移。两条扩充路线：</p> <ul> <li><strong>(A) 数据增广</strong>（0 成本）：现有 5 张做 crop / 旋转 / 颜色抖动 → 20-30 张</li> <li><strong>(B) i2i 扩展</strong>（约 ¥3-5/角色）：从现有 ref 出更多表情/姿态/角度变体</li> </ul> <hr /> <h2 id="3-gpu-经济性">3. GPU 经济性</h2> <p>按小时租的云 GPU 是这套流水线的算力底座，几档参考单价：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>4090: ¥1.8-2.18 / h 5090: ¥2.88 / h vGPU-32GB: ¥1.68 / h（A100 切片，无 Blackwell FP8） </code></pre></div></div> <p><strong>5090 性价比最优</strong>：相比 4090 仅 +32% 单价，换来 +33% VRAM + 30-60% 速度（Blackwell + FP8），单任务实际成本几乎打平。</p> <p>横向对比内容生成本身的开销：一份 ¥260 的 Marble 预算，约等于 90 小时 5090，足够跑完整季的 3DGS 场景 + 多个角色 LoRA + 视频试验还有富余。也就是说，在这套工艺里，3D 场景重建（Marble）才是单位成本的大头，本地训练/推理反而便宜。</p> <p>实操上几条铁律：模型权重/数据/训练产物训完立刻拉回本地，不要把唯一副本留在易失的实例临时盘上；阿里系模型（Z-Image / Qwen-Image / Wan 等）走 ModelScope 下载比国际镜像稳得多。</p> <hr /> <h2 id="4-推荐工艺落地">4. 推荐工艺（落地）</h2> <h3 id="41-短期已可执行">4.1 短期（已可执行）</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>关键场景 anchor (5-10 个/集) → Marble 单图 ¥10-20 × N 微调镜头 (dolly / 小 pan) → SHARP 兜底 ¥0 角色锁 → SDXL LoRA + ai-toolkit 约 ¥0.6/角色 跨镜切镜空间一致 → Marble splat → Blender depth/flat → i2i ref </code></pre></div></div> <h3 id="42-中期">4.2 中期</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>1. 解决写实 base 的 gating（换不 gated 的写实模型） 2. 数据增广（A）+ i2i 扩展（B）→ 每角色 25-30 训练图 3. 重训角色 LoRA 4. 写 ControlNet pose+depth 流水线，对接 Blender + Marble splat </code></pre></div></div> <h3 id="43-长期解锁更省的自托管栈">4.3 长期（解锁更省的自托管栈）</h3> <ul> <li><strong>自托管 Hunyuan World 2.0</strong> 替代 Marble（省 30-50×）</li> <li><strong>自托管视频模型</strong>（Wan 2.2 / HunyuanVideo）替代商用 i2v（省约 80%）</li> <li><strong>角色专属 TTS</strong>（GPT-SoVITS / F5-TTS）替代通用 voice</li> <li><strong>唇形同步</strong>（MuseTalk / LatentSync）</li> </ul> <hr /> <h2 id="5-关键决策">5. 关键决策</h2> <ul> <li>Marble 是当前空间一致性主通道</li> <li>i2i 凑多视角喂 Marble 这条路排除（拼缝鬼影）</li> <li>SHARP 仅做兜底（monocular 限制）</li> <li>5090 是首选卡（性价比 + Blackwell FP8）</li> <li>ai-toolkit 是 LoRA 训练事实标准</li> <li>触发词避免宗教专名直用，规避内容过滤</li> </ul> <p>开放问题主要在写实 base 的选型（Flux gating 待绕开）、训练数据量扩充、以及真正几何一致的多视角解（Zero123++ 风格不对，Wonder3D/Era3D 待实测）。</p>

AIGC 短剧有两个绕不开的痛点：同一场景切镜不能错乱（空间一致性），以及角色跨镜跨集不能漂移（身份一致性）。本文把 World Labs Marble、Apple SHARP、Zero123++、SDXL/Flux LoRA 几条路径全部跑了一遍，给出带单位成本的对比结论，以及一个反向优化的教训。

2026-05-07T04:00:00+00:00 2026-05-07T04:00:00+00:00 https://jinzi.cyou/posts/claude-code-context-and-memory-mastery <blockquote> <p>一份基于第一性原理推导的 Claude Code 信息组织指南。讲清楚 memory、CLAUDE.md、hooks、skills、subagents 各自存在的物理理由，以及怎样在它们之间分配信息，才能让 agent 在长期、多项目、跨会话场景下保持高密度可用、低噪声。</p> </blockquote> <h2 id="阅读顺序">阅读顺序</h2> <ul> <li>§1–§3：第一性原理与基本约束（中级必读）</li> <li>§4–§7：八层信息架构与每一层的写作守则（中-高级）</li> <li>§8–§10：决策框架与反模式（高级）</li> <li>§11–§13：大师级模式与实战 case studies</li> </ul> <hr /> <h2 id="1--一切的起点claude-code-是什么">§1 · 一切的起点：Claude Code 是什么</h2> <p>把 Claude Code 剥到只剩骨头，它是三件东西：</p> <ol> <li><strong>一个 LLM</strong>：单次推理时，只能看见当前 prompt 里的内容。它不”知道”任何运行时之外的状态。</li> <li><strong>一组工具（tools）</strong>：Read/Edit/Bash/Agent/… 让它在每一轮里跟外界交换有限信息。</li> <li><strong>一套上下文注入规则（context plumbing）</strong>：决定每一次推理开始前，prompt 里都被塞进了什么。</li> </ol> <p>90% 的”使用 Claude Code 进阶问题”——其实是第 3 件事的工程问题：<strong>什么时候、把什么信息、放到哪一层、用什么机制注入</strong>。memory、CLAUDE.md、hooks、skills、subagents 都只是这套注入规则的不同表现形式。</p> <p>理解这一点，你会发现”该把规则写进 memory 还是 CLAUDE.md”这种问题不再是品味之争，而是有 deterministic 答案的。</p> <h2 id="2--五条物理约束first-principle-constraints">§2 · 五条物理约束（first-principle constraints）</h2> <p>所有进阶技巧都是这五条约束的衍生物。</p> <h3 id="约束-a--上下文是稀缺资源">约束 A — 上下文是稀缺资源</h3> <p>模型每次推理读的 prompt 有上限（在你这台 Sonnet 4.6 上是 200K，Opus 4.7 1M context 也是有限）。<strong>每个 token 都要：</strong></p> <ul> <li>占用窗口预算（挤掉其他可能更重要的内容）</li> <li>增加推理成本（钱 + 延时）</li> <li>引入潜在干扰（注意力被分散）</li> </ul> <p>注意：<strong>总 token 数不是唯一指标</strong>，”信息密度”才是。1000 行重复废话比 200 行核心契约伤害更大，因为前者既挤掉空间又稀释关注度。</p> <h3 id="约束-b--信息只在被注入-prompt-时才存在">约束 B — 信息只在被注入 prompt 时才”存在”</h3> <p>这条比看上去深刻得多。</p> <ul> <li>你硬盘上有一份完美的架构文档？除非它出现在 prompt 里，否则 LLM 看不见。</li> <li>你上周和它说过”不要 mock 数据库”？除非这次被记录回 prompt，否则它不知道。</li> <li>你有一个 <code class="language-plaintext highlighter-rouge">~/.minimax.env</code> 文件？除非有什么机制把”它存在 + 路径 + 用途”注入进来，否则 agent 不会找。</li> </ul> <p>工程意义：<strong>所有”agent 应该记住的事”都得有一条注入路径</strong>。要么自动加载（CLAUDE.md / MEMORY.md 索引 / settings），要么用户当场提（@file / slash），要么 hook 主动塞（system reminder）。<strong>没有路径 = 不存在。</strong></p> <h3 id="约束-c--信息的召回成本-vs-失效成本-vs-噪声成本三角">约束 C — 信息的”召回成本 vs 失效成本 vs 噪声成本”三角</h3> <p>每条信息的归属要权衡三种成本：</p> <table> <thead> <tr> <th>成本</th> <th>含义</th> <th>谁付</th> </tr> </thead> <tbody> <tr> <td><strong>召回成本</strong></td> <td>这条信息没自动出现，下次得重新提供/解释</td> <td>你（每次重复）</td> </tr> <tr> <td><strong>失效成本</strong></td> <td>信息陈旧、与现实不符，agent 据此做了错事</td> <td>你（事后清理）</td> </tr> <tr> <td><strong>噪声成本</strong></td> <td>当前任务用不到，但占了上下文 / 让模型分心</td> <td>每次推理（多花钱、做错）</td> </tr> </tbody> </table> <p>不同信息的衰减率不同：</p> <ul> <li>“我是 Go 工程师” — 几乎不衰减 → 适合长期 memory</li> <li>“本季度优先重构 auth 模块” — 一两个月衰减 → 短期 memory，要标日期</li> <li>“今天调试这个 bug 试过哪些方案” — 单次会话即衰减 → task list / 对话本身，<strong>绝不</strong>进 memory</li> <li>“这个 repo 的部署命令是 <code class="language-plaintext highlighter-rouge">make deploy</code>” — 跟代码同寿 → CLAUDE.md</li> <li>“禁止在 prod 分支强推” — 永久且 deterministic → settings permissions / hook</li> </ul> <p><strong>衰减越慢、跨会话越频繁用 → 越靠”内层”（settings / CLAUDE.md / memory）。衰减越快、单次性 → 越靠”外层”（plan / task / 对话）。</strong></p> <h3 id="约束-d--deterministic-行为不能靠-prompt-实现">约束 D — Deterministic 行为不能靠 prompt 实现</h3> <p>LLM 是概率系统。如果你需要的是”<strong>每次</strong> commit 前 <strong>必定</strong> 跑 lint”“<strong>绝不</strong> 让 agent 碰 .env”——这种 deterministic 保证，必须放在 LLM 之外的执行层（hooks / permissions），而不是写在 memory / CLAUDE.md 里。</p> <p>写在文档里的规则会被遵守 99%，但是 agent 长跑场景下的 1% 偏差会累积。Hook 是 0% 偏差。</p> <h3 id="约束-e--prompt-cache-与稳定性">约束 E — Prompt cache 与稳定性</h3> <p>Anthropic 的 prompt cache 有 5 分钟 TTL（这台机器具体值见 ScheduleWakeup 文档）。命中 cache 的 token 便宜 90%、延时低。</p> <p>工程意义：</p> <ul> <li><strong>CLAUDE.md / MEMORY.md 这种”每次会话都加载”的内容应保持稳定</strong>，频繁改动会击穿 cache。</li> <li>单次会话内反复跑工具时，文件内容尽量不要在调用之间被改写——否则后续推理 cache miss。</li> <li>把不稳定的内容（比如临时调试日志）放到对话尾部，而不是 system / 文档区。</li> </ul> <h2 id="3--信息的四种本体ontology">§3 · 信息的四种本体（ontology）</h2> <p>掌握了约束，再看不同信息的”本体类型”。这决定它该用哪个机制承载。</p> <table> <thead> <tr> <th>本体</th> <th>特征</th> <th>例子</th> <th>该放哪</th> </tr> </thead> <tbody> <tr> <td><strong>可执行规则</strong>（policy）</td> <td>deterministic，”做/不做”</td> <td>“禁止 force push”、”commit 前 lint”</td> <td>hooks / permissions</td> </tr> <tr> <td><strong>项目知识</strong>（domain）</td> <td>与代码同寿，多人共享</td> <td>架构、契约、命令</td> <td>CLAUDE.md（项目内）</td> </tr> <tr> <td><strong>个人状态</strong>（preference + history）</td> <td>跨会话、个人化</td> <td>用户身份、习惯、纠正历史</td> <td>auto-memory</td> </tr> <tr> <td><strong>会话产物</strong>（artifact）</td> <td>单次任务的中间物</td> <td>task list、调研笔记、plan</td> <td>task / 对话 / fork</td> </tr> </tbody> </table> <p>很多新手把这四类混着塞 memory，导致 memory 又长又乱、可信度衰减。<strong>先分清本体，再选机制</strong>。</p> <hr /> <h2 id="4--八层信息架构">§4 · 八层信息架构</h2> <p>把 Claude Code 的注入层按”距离 prompt 由近到远 / 自动化由强到弱”展开成八层。每层都有：触发时机、生命周期、写什么、不写什么、典型反模式。</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>┌─ L0 模型权重（训练知识） ├─ L1 system prompt（harness 写的，不可改） ├─ L2 settings.json + hooks（可执行规则层） ├─ L3 项目 CLAUDE.md（项目知识） ├─ L4 用户级 CLAUDE.md（跨项目偏好） ├─ L5 Auto-memory（跨会话个人状态） ├─ L6 Skills + Subagents（按需注入工作流） ├─ L7 当前会话（plan / task / 工具结果 / 对话） └─ L8 即时引用（@file / slash / 用户当场粘贴） </code></pre></div></div> <h3 id="l0--模型权重">L0 · 模型权重</h3> <p><strong>有什么</strong>：截止 knowledge cutoff（这台 Sonnet 4.6 是 2025-08）的世界知识、编程语言、库的用法。 <strong>进阶要点</strong>：不要把”通用编程常识”写进 CLAUDE.md/memory（噪声），但要写”我们这个 repo 不要按你训练时的常识来”的反例。</p> <h3 id="l1--system-prompt">L1 · System prompt</h3> <p><strong>有什么</strong>：harness 注入的工具说明、当前工作目录、平台、日期、agent 行为规范。 <strong>生命周期</strong>：每次会话启动注入，全程 stable。 <strong>进阶要点</strong>：你改不了它，但你能感知到它的边界——比如它已经规定”不要主动 commit”，你就别在 CLAUDE.md 重写一遍（噪声 + 可能冲突）。</p> <h3 id="l2--settingsjson--hooks可执行规则层">L2 · settings.json + hooks（可执行规则层）</h3> <h4 id="文件位置按优先级由低到高">文件位置（按优先级由低到高）</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/.claude/settings.json # 用户全局 &lt;repo&gt;/.claude/settings.json # 项目共享（入版本库） &lt;repo&gt;/.claude/settings.local.json # 项目个人（不入库，gitignore） &lt;企业管理&gt; managed settings # 强制（最高优先） </code></pre></div></div> <p>后者覆盖前者。<strong>不要把 <code class="language-plaintext highlighter-rouge">settings.local.json</code> 提交到 git</strong>——里面常含个人 token 路径或允许列表。</p> <h4 id="hooks-的事件模型">Hooks 的事件模型</h4> <p>Claude Code 的 hooks 在生命周期事件上挂 shell 命令，输出会作为 system message 注入进 LLM 上下文。常见事件：</p> <table> <thead> <tr> <th>事件</th> <th>时机</th> <th>典型用途</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">SessionStart</code></td> <td>会话起始</td> <td>注入项目状态摘要、git 当前分支</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">UserPromptSubmit</code></td> <td>用户消息提交后、推理前</td> <td>拦敏感词、注入额外上下文</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">PreToolUse</code></td> <td>工具调用前</td> <td>拦截危险命令、补 plan</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">PostToolUse</code></td> <td>工具返回后</td> <td>自动 lint、压缩输出、统计</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">Stop</code> / <code class="language-plaintext highlighter-rouge">SubagentStop</code></td> <td>主/子 agent 完成</td> <td>自动备份、发通知</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">Notification</code></td> <td>harness 通知</td> <td>接管”等待用户”提示</td> </tr> </tbody> </table> <p><strong>最常被错用的设计</strong>：把 deterministic 规则写成”教 agent 记住”。例：</p> <blockquote> <p>❌ memory 写：[feedback] 不要用 <code class="language-plaintext highlighter-rouge">npm install</code>，本 repo 用 <code class="language-plaintext highlighter-rouge">pnpm</code></p> </blockquote> <p>写一年也防不住偶尔翻车。正确做法：</p> <blockquote> <p>✅ project settings.json <code class="language-plaintext highlighter-rouge">permissions.deny</code>: <code class="language-plaintext highlighter-rouge">["Bash(npm install*)"]</code> ✅ 同时项目 CLAUDE.md 一行说明（解释为何 deny，避免 agent 困惑）</p> </blockquote> <p>deny 列表是 deterministic 的物理拦截；CLAUDE.md 的一行只是为了让 agent 在被拦时立刻理解”哦，应该用 pnpm”。两者协作，缺一不可。</p> <h4 id="permissions-的作用域">Permissions 的作用域</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>permissions: allow: [...] deny: [...] ask: [...] </code></pre></div></div> <p>许多人只用 allow 来减少 prompt（典型场景：<code class="language-plaintext highlighter-rouge">/fewer-permission-prompts</code> 这个 skill 帮你做这件事），但 <strong>deny + ask 用得好可以构造”安全护栏”</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">deny</code>: 永远不允许（破坏性命令、敏感目录）</li> <li><code class="language-plaintext highlighter-rouge">ask</code>: 可以做但每次都要批准（git push、send message）</li> <li><code class="language-plaintext highlighter-rouge">allow</code>: 不弹窗</li> </ul> <p>进阶模式：把同一类工具按子模式分级。例如允许只读 git，但 push 要 ask：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>permissions: allow: ["Bash(git status)", "Bash(git diff*)", "Bash(git log*)"] ask: ["Bash(git push*)", "Bash(git commit*)"] deny: ["Bash(git push --force*)", "Bash(git reset --hard*)"] </code></pre></div></div> <h3 id="l3--项目-claudemd">L3 · 项目 CLAUDE.md</h3> <p><strong>触发</strong>：当 cwd 进入该 repo（或它的子目录）时，自动加载到 system context。 <strong>生命周期</strong>：跟代码同 git 历史。 <strong>写什么</strong>：</p> <ul> <li>项目地图（多模块仓库尤其关键，单纯 ls 无法体现哪是核心）</li> <li>跨模块契约 / 数据流（”<code class="language-plaintext highlighter-rouge">A</code> 写入 X，<code class="language-plaintext highlighter-rouge">B</code> 读取 X，schema 在 Z”）</li> <li>非显然的命令（不是 <code class="language-plaintext highlighter-rouge">npm test</code> 这种从 package.json 能猜出来的，而是”测单文件用 <code class="language-plaintext highlighter-rouge">npx vitest run path/to.test.ts -t name</code>“）</li> <li>不要做的事（容易踩的坑、已经废弃的路径）</li> <li>当前长期目标（如果存在；项目 vision 帮 agent 做权衡）</li> </ul> <p><strong>不写什么</strong>：</p> <ul> <li>README 已写过的内容（重复）</li> <li>通用最佳实践（”提供有意义的错误信息”——所有项目都该这样）</li> <li>文件清单（可发现的）</li> <li>会高频变化的状态（PR 进度、本周计划——这是 task / project-memory 的事）</li> </ul> <h4 id="子目录-claudemdprogressive-disclosure">子目录 CLAUDE.md（progressive disclosure）</h4> <p>monorepo 或多项目 workspace 中，根 CLAUDE.md 应该是”地图 + 公共契约”，每个子目录可以有自己的 CLAUDE.md，<strong>只在工作进入该目录时才加载</strong>。</p> <p>为什么：上下文是稀缺资源（约束 A）。如果你 30 个子项目的所有细节都灌在根 CLAUDE.md，那么修一个 typo 也得带着 5000 行的工作区描述推理。</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/claw/CLAUDE.md # 工作区索引（轻量，~150 行） ~/claw/marginalia/CLAUDE.md # Jekyll 站点细节 ~/claw/tv/CLAUDE.md # AI 短剧流水线细节 ~/claw/lotus-academy-design/CLAUDE.md # 全栈应用细节 </code></pre></div></div> <h4 id="import-语法"><code class="language-plaintext highlighter-rouge">@import</code> 语法</h4> <p>CLAUDE.md 支持 <code class="language-plaintext highlighter-rouge">@path/to/file.md</code> 引用其他文档，加载时会展开（一定深度内）。用途：</p> <ul> <li>把超长的契约说明拆出去：<code class="language-plaintext highlighter-rouge">@docs/architecture.md</code></li> <li>团队共享 + 个人覆盖：项目 CLAUDE.md <code class="language-plaintext highlighter-rouge">@~/.claude/my-team-conventions.md</code></li> <li>多 repo 共享一份”风格指南”</li> </ul> <p><strong>陷阱</strong>：被 import 的文件也吃 token；展开后总长还是有上限，别把整个 docs/ 都拉进来。</p> <h3 id="l4--用户级-claudemdclaudeclaudemd">L4 · 用户级 CLAUDE.md（<code class="language-plaintext highlighter-rouge">~/.claude/CLAUDE.md</code>）</h3> <p><strong>触发</strong>：所有 Claude Code 会话都加载（无论 cwd）。 <strong>写什么</strong>：</p> <ul> <li>“我是谁、我的整体技术风格”（覆盖所有项目）</li> <li>跨项目都成立的偏好（语言、回复长度、commit 风格）</li> </ul> <p><strong>注意</strong>：<strong>不要把这里当 memory 用</strong>。memory 系统比这里精细（分类型、有名字、能 grep）。这里只放”整体性、低频变化”的偏好，写成 1-2 段散文最佳。</p> <h3 id="l5--auto-memory跨会话个人状态">L5 · Auto-memory（跨会话个人状态）</h3> <p>详见 §5 专章。这里只点位置：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/.claude/projects/&lt;encoded-cwd&gt;/memory/ ├── MEMORY.md # 索引（每会话载入，≤200 行被截） ├── user_*.md # user 类型 ├── feedback_*.md # feedback 类型 ├── project_*.md # project 类型 └── reference_*.md # reference 类型 </code></pre></div></div> <p>注意 memory 是 <strong>per-cwd</strong> 的（每个工作目录有独立 memory 目录）。这意味着你在 <code class="language-plaintext highlighter-rouge">~/claw</code> 下积累的 memory 不会被 <code class="language-plaintext highlighter-rouge">~/some-other-repo</code> 看到——这是 feature 不是 bug：避免跨项目偏好串味。</p> <p>如果你确实有跨所有 cwd 的偏好，写到 <code class="language-plaintext highlighter-rouge">~/.claude/CLAUDE.md</code>（L4），不要复制到每个 memory 目录。</p> <h3 id="l6--skills--subagents按需注入工作流">L6 · Skills + Subagents（按需注入工作流）</h3> <h4 id="skills">Skills</h4> <p><code class="language-plaintext highlighter-rouge">~/.claude/skills/&lt;name&gt;/SKILL.md</code>（也可以从 plugin marketplace 安装）。每个 skill 在会话启动时被列在 system reminder 里（<strong>只列名 + 描述</strong>，不展开 body）；当用户输入 <code class="language-plaintext highlighter-rouge">/&lt;name&gt;</code> 或 trigger 命中时才注入完整 body 并执行。</p> <p>为什么这设计：约束 A（稀缺）。如果 50 个 skill 的全文都加载，token 就崩了。所以 skill 是 “lazy load”：先暴露名字让 agent 知道存在，按需展开。</p> <p><strong>写 skill 的核心要点</strong>：</p> <ul> <li>description 必须写得让”agent 一眼就知道何时该用”。”Use to do X-ish things” 太空。”Use when user asks about X / when file matches Y” 才有用。</li> <li>body 写”做这件事的标准动作 + 资源指针”，不要写理论。</li> <li>资源（脚本、模板、配置）放 skill 目录里，body 用相对路径引用。</li> <li>如果 skill 涉及调用其他工具，trigger 条件描述要包含”什么时候<strong>不该</strong>用”——避免误触。</li> </ul> <h4 id="subagents">Subagents</h4> <p><code class="language-plaintext highlighter-rouge">~/.claude/agents/&lt;name&gt;.md</code> 或内置（claude-code-guide / Plan / Explore / general-purpose）。每个 subagent 是一个<strong>独立上下文</strong>的 LLM 实例：</p> <ul> <li>自己的 system prompt</li> <li>自己的工具集（可限定）</li> <li>与主对话<strong>不共享</strong>上下文（除非通过 fork，见 §11）</li> </ul> <p>为什么要 subagent：约束 A 又出现了。一个 5 分钟的”读 30 个文件找 X 在哪定义”，会把 30 个文件原文塞进上下文。让 subagent 去做、只回收一段总结，主对话省了 30 个文件的 noise。</p> <p><strong>Subagent 的”代价”</strong>：</p> <ul> <li>它<strong>不知道</strong>你和主对话之间的所有约定（除非 prompt 里写）</li> <li>第一次调用要付 prompt cache miss</li> <li>它的 working memory 不持久（一次结束就没了）</li> </ul> <p>所以判断”派 subagent 还是自己干”，看：</p> <ul> <li>输出能否被压缩成几句话？能 → subagent</li> <li>任务能否独立定义、不依赖大量隐含上下文？能 → subagent</li> <li>耗时长且我想边干边聊？能 → fork（带上下文的 subagent）</li> </ul> <h3 id="l7--当前会话plan--task--工具结果--对话">L7 · 当前会话（plan / task / 工具结果 / 对话）</h3> <p><strong>生命周期</strong>：单次会话。会话结束（关闭终端 / 上下文压缩）就丢失。 <strong>写什么</strong>：</p> <ul> <li>当前任务的 plan（用 Plan 工具锁定方案）</li> <li>task list（用 TaskCreate；分步进度跟踪）</li> <li>工具调用的中间结果</li> </ul> <p><strong>最常见错误</strong>：把”本次任务的进度”写进 memory。<strong>不要</strong>。memory 是给”未来会话”看的，写一次性进度只会让未来会话困惑（”这个任务做完了吗？”）。</p> <h3 id="l8--即时引用用户当场注入">L8 · 即时引用（用户当场注入）</h3> <p><code class="language-plaintext highlighter-rouge">@file.md</code>、<code class="language-plaintext highlighter-rouge">@image.png</code>、<code class="language-plaintext highlighter-rouge">/skill</code>、用户粘贴的代码段。</p> <p>为什么这层重要：它是<strong>用户对 agent 的精确手术工具</strong>。当你发现 agent 缺某条信息，最快的修复不是改 CLAUDE.md，而是当场 <code class="language-plaintext highlighter-rouge">@</code>。改 CLAUDE.md 是”把这条修复变成永久”——只在你判断它会反复用到时才升级。</p> <hr /> <h2 id="5--memory-系统深度解剖">§5 · Memory 系统深度解剖</h2> <p>memory 是 Claude Code 中最容易被错用的层。一旦掌握，它的 ROI 也最高。</p> <h3 id="51-为什么是四种类型">5.1 为什么是四种类型</h3> <p><code class="language-plaintext highlighter-rouge">user / feedback / project / reference</code> 不是随手起的。这四类对应<strong>不同的”写入触发”和”读取触发”</strong>：</p> <table> <thead> <tr> <th>类型</th> <th>写入触发</th> <th>读取触发</th> <th>衰减率</th> </tr> </thead> <tbody> <tr> <td>user</td> <td>学到用户身份 / 角色 / 知识</td> <td>几乎每次（用户身份与所有任务相关）</td> <td>极低</td> </tr> <tr> <td>feedback</td> <td>被纠正 / 被确认</td> <td>类似情境再次出现</td> <td>低-中</td> </tr> <tr> <td>project</td> <td>学到工作内容 / 目标 / 时间表</td> <td>工作话题相关</td> <td>中-高（项目更迭快）</td> </tr> <tr> <td>reference</td> <td>学到外部资源位置</td> <td>用户提到外部系统</td> <td>低（除非资源本身搬走）</td> </tr> </tbody> </table> <p><strong>含义</strong>：写 memory 时先问自己”这条<strong>为什么</strong>未来会用到、<strong>什么情境</strong>会用到”。如果情境模糊，那条 memory 多半价值低。</p> <h3 id="52-索引文件memorymd的设计哲学">5.2 索引文件（MEMORY.md）的设计哲学</h3> <p>MEMORY.md 不是 memory 本身，是<strong>给未来会话的”目录页”</strong>。每条索引行的目标是：让未来会话扫一眼就能判断”这条与当前任务相关吗”。</p> <p>✅ 好索引行：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>- [GitHub 操作规则](feedback_github_ops.md) — force-push 需批准；其他 GH 动作在 gittee-coder 上预授权 </code></pre></div></div> <p>❌ 差索引行：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>- [GH](gh.md) — github stuff </code></pre></div></div> <p>差在哪：差的版本即使读了也得点开文件才能判断相关性，浪费一次”判断成本”。</p> <p><strong>索引行模板</strong>：<code class="language-plaintext highlighter-rouge">- [短标题](文件名) — 一句具体钩子（who/what/why）</code>。</p> <p>200 行截断不是 nice-to-have：超过这个数 LLM 真的看不到后面的条目。所以维护 MEMORY.md 时永远把最重要的、最跨任务的条目放上面。</p> <h3 id="53-单条-memory-的写作模板">5.3 单条 memory 的写作模板</h3> <h4 id="user-类型直接陈述事实">user 类型：直接陈述事实</h4> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span> <span class="na">name</span><span class="pi">:</span> <span class="s">User profile — pyf</span> <span class="na">description</span><span class="pi">:</span> <span class="s">Who pyf is, communication style (terse Chinese), autonomy stance</span> <span class="na">type</span><span class="pi">:</span> <span class="s">user</span> <span class="nn">---</span> pyf is the operator. Roles: [...]. Communication: terse, Chinese-preferred. Autonomy preference: act, don't propose-and-wait — only confirm for irreversible actions. </code></pre></div></div> <h4 id="feedback-类型规则--why--how-to-apply强制三段式">feedback 类型：规则 + Why + How to apply（强制三段式）</h4> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Visual design quality bar</span> <span class="na">description</span><span class="pi">:</span> <span class="s">Never ship default themes/templates; design quality is mandatory</span> <span class="na">type</span><span class="pi">:</span> <span class="s">feedback</span> <span class="nn">---</span> 不要使用默认主题、模板或框架自带的样式直接交付。 <span class="gs">**Why:**</span> 用户在多次评审中明确指出"看起来像随手套模板"，要求把视觉作为一等输出。 默认样式没有差异化、传达不了项目意图。 <span class="gs">**How to apply:**</span> 凡是会被用户看到的产出（站点、报告、PPT、视频），都必须经过 独立的视觉决策（配色、排版、信息层次）。即便是内部草稿，初稿也要超出"模板感"。 </code></pre></div></div> <p>为什么强制 Why + How：约束 C（噪声成本）的反面——一条 memory 在未来情境里可能”看起来相关但实际不该套用”。Why 让 agent 判断<strong>这次是不是真的同情境</strong>；How 让 agent 知道<strong>怎样落地这条规则</strong>。少了任一项，memory 在边缘情境下要么过度套用（生硬）要么不套用（白记）。</p> <h4 id="project-类型事实--why--how-to-apply">project 类型：事实 + Why + How to apply</h4> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span> <span class="na">name</span><span class="pi">:</span> <span class="s">周更视频迁 B 站</span> <span class="na">description</span><span class="pi">:</span> <span class="s">2026-05 起视频走 B 站托管，Marginalia 嵌 iframe</span> <span class="na">type</span><span class="pi">:</span> <span class="s">project</span> <span class="nn">---</span> 每周一发的 AI 周报视频，从 marginalia repo 直接托管改为上传 B 站后嵌 iframe。 <span class="gs">**Why:**</span> Pages 仓库容量/流量受限，单期 mp4 ≥ 10MB 撞墙。 2026-05-05 之后所有新视频都按这个流程走。 <span class="gs">**How to apply:**</span> 用 <span class="sb">`marginalia/scripts/publish-video.py --upload`</span>， 脚本会把 BV id 写回 _videos/<span class="nt">&lt;slug&gt;</span>.md（<span class="sb">`bvid:`</span> 字段，去掉 <span class="sb">`video:`</span>）。 </code></pre></div></div> <h4 id="reference-类型where--用途">reference 类型：where + 用途</h4> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span> <span class="na">name</span><span class="pi">:</span> <span class="s">MiniMax 开放平台</span> <span class="na">description</span><span class="pi">:</span> <span class="s">按量 key + 端点 + 模型单价</span> <span class="na">type</span><span class="pi">:</span> <span class="s">reference</span> <span class="nn">---</span> <span class="sb">`~/.minimax.env`</span> — 按量 API key <span class="sb">`api.minimaxi.com`</span> — 唯一端点 模型与单价（2026-05 现状）： <span class="p"> -</span> speech-2.6-hd: ¥0.432/千字符 <span class="p"> -</span> MiniMax-Hailuo-02 768P 6s: ¥1.944/条 <span class="gs">**注意**</span>：无公开账单查询 API，需要去 web 后台对账。 </code></pre></div></div> <h3 id="54-写入触发什么时候保存">5.4 写入触发（什么时候保存）</h3> <h4 id="强信号必须立即保存">强信号（必须立即保存）</h4> <ul> <li>用户<strong>纠正</strong>了一个判断：”不要 X，我们用 Y”</li> <li>用户<strong>默许</strong>了一个非显然选择（agent 选了 A，用户没异议——这是认证的判断）</li> <li>用户告诉了你新的环境信息（新 key、新服务器、新组织账号）</li> <li>用户告知了项目的时间节点 / 决策原因</li> <li>用户解释了一个奇怪 workaround 的理由</li> </ul> <h4 id="弱信号克制">弱信号（克制）</h4> <ul> <li>你”觉得”将来可能有用——多半不会</li> <li>当前对话的中间结论——不要存，存了也是噪声</li> <li>代码变更——git log 是 source of truth</li> </ul> <h4 id="反信号绝不保存">反信号（绝不保存）</h4> <ul> <li>一次性 task 的进度</li> <li>你刚 ToolSearch 出来的工具列表</li> <li>用户让你 grep 的结果</li> <li>流水线日志、API 响应原文</li> <li>任何能从 git/grep/ls 重新得到的信息</li> </ul> <h3 id="55-读取触发与信任但验证">5.5 读取触发与”信任但验证”</h3> <p>memory 可以快速给出答案，但 <strong>memory 是过去某时刻的快照</strong>。一条 memory 提到的文件可能已被改名、删除；提到的 API key 可能轮换；提到的服务可能停了。</p> <p>所以高级用法：</p> <ol> <li><strong>用户在询问历史/状态</strong> → memory 直接回答（”上次你说 X 是这样配的”）</li> <li><strong>用户准备</strong>基于 memory 行动** → 先验证再行动**</li> </ol> <p>例：用户说”按之前那个流程发布报告”。 → memory 说用 <code class="language-plaintext highlighter-rouge">scripts/publish.py</code>。 → <strong>不要</strong>直接跑 <code class="language-plaintext highlighter-rouge">scripts/publish.py path/to.md</code>。 → <strong>先</strong>：<code class="language-plaintext highlighter-rouge">ls scripts/publish.py</code> 确认存在 + 快速 head 一眼参数没变 → 再跑。</p> <p>成本仅一次 ls + read，省掉的是”按陈旧记忆办错事的回滚成本”。</p> <h3 id="56-对称记录原则">5.6 “对称记录”原则</h3> <p>新手只在被纠正时记 feedback，结果：</p> <ul> <li>agent 知道”不要做 X”</li> <li>agent 不知道”上次你认可的做法是 Y”</li> </ul> <p>下次遇到类似情境，agent 会过度保守——再次询问、再次提议、再次浪费一次确认。</p> <p><strong>修正</strong>：用户<strong>默许</strong>了一个判断 = 同样要写 memory。例：</p> <blockquote> <p>agent 选择”把 4 个独立 PR 合并成 1 个” → 用户没异议直接接受 → 写一条 feedback： “对此类重构，用户偏好单 PR 而非拆分。<strong>Why:</strong> 用户在 [日期] 的此选择中默许了此判断。<strong>How to apply:</strong> 类似情境下默认走单 PR，除非有 reviewer 容量考虑。”</p> </blockquote> <p>对称记录是把 memory 从”防错系统”升级到”判断辅助系统”的关键。</p> <h3 id="57-维护去重衰减stale-检测">5.7 维护：去重、衰减、stale 检测</h3> <p>memory 数量到 10+ 后会出现：</p> <ol> <li><strong>同主题分散</strong>：A 文件 + B 文件都讲 GitHub 操作。<strong>修</strong>：合并到一个，更新索引。</li> <li><strong>stale 条目</strong>：写时正确，现在过时（人换了、key 换了、库改名）。<strong>修</strong>：要么 update 要么删除。<strong>绝不</strong>留着”添加但保留旧的，避免删错”——这是 memory 腐烂的开始。</li> <li><strong>过细</strong>：每个调试细节都记一条。<strong>修</strong>：细节属于代码 / git log。删掉。</li> </ol> <h4 id="月度-5-分钟巡检推荐流程">月度 5 分钟巡检（推荐流程）</h4> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>1. 读 MEMORY.md，对每条问"这条还成立吗？还有用吗？" 2. 不成立 → 删（直接 rm 文件 + 删索引行） 3. 部分成立 → update（不要叠加新内容到旧文件，要 rewrite） 4. 主题分散 → 合并 5. 重要度变化 → 调整索引顺序（重要的上提，避免被 200 行截断） </code></pre></div></div> <h3 id="58-进阶memory-当-llm-友好的个人知识库索引">5.8 进阶：memory 当 LLM 友好的”个人知识库索引”</h3> <p>终极用法：memory 不存”事实”，而存”<strong>事实的索引</strong>“。</p> <p>例：你不要把整篇技术决策记录写进 memory（噪声、衰减），而是：</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span> <span class="na">name</span><span class="pi">:</span> <span class="s">ADR — Auth middleware rewrite (2026-Q2)</span> <span class="na">description</span><span class="pi">:</span> <span class="s">决策记录指针；详情见 docs/decisions/0042</span> <span class="na">type</span><span class="pi">:</span> <span class="s">reference</span> <span class="nn">---</span> Auth middleware 在 2026-Q2 被重写。<span class="gs">**完整决策、理由、反对意见**</span>见 <span class="sb">`&lt;repo&gt;/docs/decisions/0042-auth-rewrite.md`</span>。 <span class="gs">**关键 takeaway**</span>（避免每次都读全文）： <span class="p">-</span> 触发原因：legal 合规（不是技术债） <span class="p">-</span> 选型：JWT + Redis session（不是纯 stateless JWT） <span class="p">-</span> 拒绝的方案：OAuth proxy（运维复杂度太高） <span class="gs">**何时去读全文**</span>： <span class="p">-</span> agent 要修改 auth 流程时 <span class="p">-</span> 用户问"为什么不用 X 方案"时 </code></pre></div></div> <p>这种”索引型 memory”享受了 memory 的自动注入 + ADR 文档的细节深度，回避了把长文塞 memory 的噪声成本。</p> <hr /> <h2 id="6--claudemd-工程">§6 · CLAUDE.md 工程</h2> <h3 id="61-加载机制mental-model">6.1 加载机制（mental model）</h3> <p>会话启动时（在 cwd <code class="language-plaintext highlighter-rouge">&lt;repo&gt;</code> 下）：</p> <ol> <li><code class="language-plaintext highlighter-rouge">&lt;repo&gt;/CLAUDE.md</code> 加载（如果存在）</li> <li><code class="language-plaintext highlighter-rouge">~/.claude/CLAUDE.md</code> 加载（如果存在）</li> <li><code class="language-plaintext highlighter-rouge">&lt;repo&gt;</code> 中<strong>所有父目录</strong>的 CLAUDE.md 也会按层级加载（如果你在子目录）</li> </ol> <p>进入子目录工作时，子目录的 CLAUDE.md 也会进入上下文（progressive disclosure）。</p> <p><code class="language-plaintext highlighter-rouge">@path/to/file.md</code> 会展开 import（一定深度内）。</p> <h3 id="62-写作守则六个是--否">6.2 写作守则：六个”是 / 否”</h3> <table> <thead> <tr> <th>应该写</th> <th>不应该写</th> </tr> </thead> <tbody> <tr> <td>多文件合起来才看得懂的”大图”</td> <td>单文件就能看懂的细节</td> </tr> <tr> <td>非显然的命令、参数、入口</td> <td>通用 npm/pytest/cargo 命令</td> </tr> <tr> <td>跨模块契约 / 数据流</td> <td>单模块内部实现</td> </tr> <tr> <td>已经踩过的坑、明确禁忌</td> <td>通用最佳实践</td> </tr> <tr> <td>长期项目目标（一两段）</td> <td>本周计划、PR 进度</td> </tr> <tr> <td>团队/个人共识里的非默认做法</td> <td>默认做法</td> </tr> </tbody> </table> <h3 id="63-三节模板最经济的-claudemd-骨架">6.3 三节模板（最经济的 CLAUDE.md 骨架）</h3> <p>我推荐对绝大多数项目用这三节：</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># CLAUDE.md</span> This file provides guidance to Claude Code (claude.ai/code) ... <span class="gu">## 项目地图</span> [一段 100-300 字概述：这个 repo 做什么、有几个核心组件、谁产数据谁消费。 配一张目录功能表（不是 tree）：模块名 / 角色 / 技术栈 / 关键文件。] <span class="gu">## 跨模块契约 / 工作流</span> [多模块协作的部分。"A 写入 X，B 读取 X，schema 在 Z""build 时 A 必须先于 B" "添加新 endpoint 时需同步改 OpenAPI + 前端 client"。这是 grep 看不出来的。] <span class="gu">## 不要做的事</span> [已经踩过 / 明确禁止的。"不要在 root 跑 git""不要把 mp4 提到此 repo" "重构时不要碰 legacy/ 目录直到 v3 上线"。] </code></pre></div></div> <p>如果有非常关键的命令也可以加 “## 常用命令” 一节，但仅限 README 没写或写得不够 agent-friendly 的部分。</p> <h3 id="64-长度与密度">6.4 长度与密度</h3> <p>实操经验：CLAUDE.md 超过 300 行后边际收益急剧下降。理由：</p> <ul> <li>agent 每次启动都要”读完 + 索引”，长文吃 attention</li> <li>维护成本上升（信息散乱、重复）</li> <li>重要内容被淹没</li> </ul> <p><strong>长度判断</strong>：写完后自问”如果 CLAUDE.md 砍掉一半，agent 会做错事吗？” 不会就砍。</p> <p>如果项目真的复杂到放不下，用 <code class="language-plaintext highlighter-rouge">@import</code> 把不同主题拆开：</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## 项目地图</span> [简版总览] 详细模块说明： <span class="p">-</span> @docs/architecture.md <span class="p">-</span> @docs/data-flow.md <span class="p">-</span> @docs/deployment.md </code></pre></div></div> <h3 id="65-多项目-workspace你这个-claw-的情境">6.5 多项目 workspace（你这个 ~/claw 的情境）</h3> <p>工作区不是单 repo 时，根 CLAUDE.md 应该极简：<strong>只做索引</strong>。</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## Workspace 性质</span> ~/claw 不是 git 仓库，是若干独立子项目。每个子项目自己的 CLAUDE.md 在 进入对应目录时加载。<span class="gs">**不要在根目录跑 git。**</span> <span class="gu">## 子项目地图</span> [一张表：子目录 / 角色 / 技术栈 / 下游] <span class="gu">## 跨项目契约</span> [只有跨项目时才适用的事，比如"报告 → 站点"的发布流程] </code></pre></div></div> <p>每个子项目的细节由 <code class="language-plaintext highlighter-rouge">&lt;子项目&gt;/CLAUDE.md</code> 自己承担。这避免根文件膨胀到 1000 行。</p> <h3 id="66-失效检测claudemd-的运维">6.6 失效检测（CLAUDE.md 的运维）</h3> <p>CLAUDE.md 写好后会<strong>腐烂</strong>——命令改了、文件改名了、契约变了。检测方法：</p> <ol> <li><strong>每次 <code class="language-plaintext highlighter-rouge">/init</code> 之前</strong>：扫一眼现有 CLAUDE.md，对每条具体命令 / 路径，确认它仍然存在。</li> <li><strong>被 agent 误导后</strong>：如果 agent 跑了 CLAUDE.md 里的命令但失败了，根因可能是 CLAUDE.md 过期 → 立刻修。</li> <li><strong>重大重构后</strong>：把 CLAUDE.md 当代码一样改。</li> <li><strong>季度 review</strong>：跟 README、makefile 对照一次。</li> </ol> <p>很多团队把 CLAUDE.md 写一次扔在 repo 里就再不管。半年后 agent 在它指引下做错事，团队抱怨”AI 不行”——其实是 instruction 烂了。</p> <h3 id="67-团队-vs-个人的-claudemd">6.7 团队 vs 个人的 CLAUDE.md</h3> <p><code class="language-plaintext highlighter-rouge">&lt;repo&gt;/CLAUDE.md</code> 是 git 跟踪的，<strong>会被所有用 Claude Code 的同事用到</strong>。这意味着：</p> <ul> <li>不要在里面写个人偏好（”我喜欢中文回复”）→ 用户级 CLAUDE.md</li> <li>不要写你的私人 token 路径 → settings.local.json</li> <li>不要带政治倾向（”老板要求 X，我们就硬着头皮做”）→ 团队 wiki</li> </ul> <p>如果你想给”自己 + 这个 repo”加只对自己生效的指引，写 <code class="language-plaintext highlighter-rouge">~/.claude/CLAUDE.md</code> 里加上”在 <repo> 中也额外 ..."这样的条件性偏好。</repo></p> <hr /> <h2 id="7--skills-与-subagents">§7 · Skills 与 Subagents</h2> <h3 id="71-skills-的设计第一性">7.1 Skills 的设计第一性</h3> <p>Skill 解决”我有一个<strong>反复使用的工作流</strong>，每次都要复述步骤太累”的问题。</p> <p><strong>何时升级为 skill</strong>：</p> <ul> <li>同一动作做了 ≥ 3 次（启动 5 分钟工作流的开销 &lt; 重写说明的累计开销）</li> <li>步骤多 / 易出错 / 有标准化资源（脚本、模板）</li> <li>需要团队复用（skill 可以入 git）</li> </ul> <p><strong>Skill 的结构</strong>：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/.claude/skills/&lt;name&gt;/ ├── SKILL.md # 入口，含 YAML frontmatter ├── scripts/ # 辅助脚本 ├── templates/ # 模板文件 └── README.md # 给人看的（可选） </code></pre></div></div> <p><code class="language-plaintext highlighter-rouge">SKILL.md</code> 的 frontmatter 通常包含 name / description / 触发条件。<strong>description 是最重要的字段</strong>——它决定 agent 是否会在合适时机想起用这个 skill。</p> <h4 id="写好-description-的三条原则">写好 description 的三条原则</h4> <ol> <li><strong>明确触发条件</strong>：用 “Use when…“，不要用 “Use to do…“。 <ul> <li>❌ “Use to handle authentication-related tasks.”</li> <li>✅ “Use when the user asks to add/modify auth flows OR when files matching <code class="language-plaintext highlighter-rouge">*/auth/*.ts</code> are edited.”</li> </ul> </li> <li><strong>包含负面条件</strong>：写”什么时候<strong>不该</strong>用”。 <ul> <li>✅ “SKIP when file imports <code class="language-plaintext highlighter-rouge">openai</code> SDK or filename contains <code class="language-plaintext highlighter-rouge">-openai</code>.”</li> </ul> </li> <li><strong>具体到 trigger 词</strong>：列出会触发它的关键词 / 文件 pattern。</li> </ol> <h3 id="72-subagents四种典型用法">7.2 Subagents：四种典型用法</h3> <table> <thead> <tr> <th>用途</th> <th>推荐 subagent</th> <th>理由</th> </tr> </thead> <tbody> <tr> <td>找 X 在哪定义</td> <td><code class="language-plaintext highlighter-rouge">Explore</code></td> <td>只读、快速、不污染上下文</td> </tr> <tr> <td>设计实现方案</td> <td><code class="language-plaintext highlighter-rouge">Plan</code></td> <td>需要架构判断，输出 step-by-step</td> </tr> <tr> <td>大型独立任务</td> <td><code class="language-plaintext highlighter-rouge">general-purpose</code></td> <td>多步、需要 write 权限</td> </tr> <tr> <td>关于 Claude Code 本身的问题</td> <td><code class="language-plaintext highlighter-rouge">claude-code-guide</code></td> <td>专门训练过的指引</td> </tr> </tbody> </table> <h4 id="fork不带-subagent_type-的-agent">Fork（不带 subagent_type 的 Agent）</h4> <p>特殊：fork <strong>继承当前对话的全部上下文</strong>，但执行结果不污染主对话。</p> <p>何时 fork：</p> <ul> <li>任务<strong>依赖隐含上下文</strong>（”按我们刚才聊的方式继续 …“）</li> <li>输出能压成几句话（中间过程是噪声）</li> <li>你想边干边继续主对话（fork 在后台跑）</li> </ul> <p><strong>fork 守则</strong>：</p> <ul> <li>不要 peek（不要读 fork 的中间输出）</li> <li>不要 race（fork 没回来前别假设结果）</li> <li>prompt 写”指令”而非”背景”（背景已经继承）</li> </ul> <h3 id="73-skill--subagent--memory-的协作模式">7.3 Skill / Subagent / Memory 的协作模式</h3> <p>三者分工是不同的”轴”：</p> <ul> <li><strong>Skill</strong>: 做这件事的 <strong>how</strong>（步骤）</li> <li><strong>Subagent</strong>: 做这件事的 <strong>环境</strong>（隔离、专用工具集）</li> <li><strong>Memory</strong>: 做这件事的 <strong>why / for whom</strong>（用户偏好、历史决策）</li> </ul> <p>进阶模式：”skill + memory + hook 三件套”：</p> <ul> <li>skill 定义工作流（步骤）</li> <li>memory 记录这个用户在这个工作流上的非默认偏好</li> <li>hook 在工作流入口拦截 / 自动调用 skill</li> </ul> <p>例：你的”周更视频流水线”是个完美的三件套候选：</p> <ul> <li>skill <code class="language-plaintext highlighter-rouge">weekly-video</code>: 定义”读 script.json → 跑 render.py → publish-video.py”</li> <li>memory: “用户偏好 ≤ ¥12 单期成本，默认 Hailuo-02-Fast”</li> <li>hook (<code class="language-plaintext highlighter-rouge">UserPromptSubmit</code>): 检测”周更视频”关键词时自动 reminder</li> </ul> <hr /> <h2 id="8--决策框架">§8 · 决策框架</h2> <p>新手最大的问题是<strong>面对一条信息不知道往哪放</strong>。下面给一组决策树。</p> <h3 id="81-决策树-a--我想让-agent-记住一件事">8.1 决策树 A — “我想让 agent 记住一件事”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>这件事是 deterministic 的吗？（"绝不要 X"、"必须 Y"） ├─ 是 → settings.json (permissions / hooks) └─ 否 → 它的衰减率？ ├─ 跟代码同寿（"build 命令"、"模块契约"）→ CLAUDE.md ├─ 跨项目都成立（"我喜欢中文"）→ user-level CLAUDE.md ├─ 跨会话个人偏好（"我接受单 PR"）→ memory (feedback) ├─ 跨会话身份信息（"我是 Go 工程师"）→ memory (user) ├─ 项目状态有时间窗口（"merge freeze 到 X"）→ memory (project) ├─ 外部资源指针（"key 在 ~/.x.env"）→ memory (reference) └─ 单次会话（"刚才我们聊到 ..."）→ task / 对话本身 </code></pre></div></div> <h3 id="82-决策树-b--agent-刚做错了">8.2 决策树 B — “agent 刚做错了”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>是模型本身的判断错？ ├─ 是 deterministic 错（每次都会错的同类）→ 升级为 hook / permission deny ├─ 是 heuristic 错（情境下做错）→ 写 feedback memory（带 Why） └─ 是因为信息缺失 → 把信息补到 CLAUDE.md / memory（看衰减率） 是 instruction 烂导致的？（CLAUDE.md / memory 误导） └─ 修 instruction，**不要**给它叠加补丁规则 </code></pre></div></div> <h3 id="83-决策树-c--我做了个新工作流">8.3 决策树 C — “我做了个新工作流”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>做过几次了？ ├─ 1 次 → 写到对话里 / 写在 README ├─ 2-3 次 → 写到 CLAUDE.md（如果 repo 内）或 memory（如果跨项目） └─ ≥ 3 次 → 升级为 skill ├─ 团队共享 → 入 git └─ 个人 → ~/.claude/skills/ </code></pre></div></div> <h3 id="84-决策树-d--我手里这条信息要不要存">8.4 决策树 D — “我手里这条信息要不要存”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>这条信息能从代码 / git log / grep 重新得到吗？ ├─ 能 → 不存（让 agent 当场查） └─ 不能 → 它在未来什么情境下会再次需要？ ├─ 答不上来 → 不存 └─ 答得上来 → 存到对应层 </code></pre></div></div> <hr /> <h2 id="9--反模式速查">§9 · 反模式速查</h2> <h3 id="91-memory-反模式">9.1 Memory 反模式</h3> <table> <thead> <tr> <th>反模式</th> <th>症状</th> <th>修复</th> </tr> </thead> <tbody> <tr> <td><strong>Memory 当 todo</strong></td> <td>“TODO: 下周改 X” 写进 memory</td> <td>用 task list；进度别进 memory</td> </tr> <tr> <td><strong>Memory 当报告</strong></td> <td>把整篇调研笔记塞 memory</td> <td>写到 docs/，memory 只存指针</td> </tr> <tr> <td><strong>被纠正了不记</strong></td> <td>同一错误被纠正 3+ 次</td> <td>第一次就写 feedback memory</td> </tr> <tr> <td><strong>被认可不记</strong></td> <td>agent 反复请求确认同样判断</td> <td>用户默许后立刻写 memory</td> </tr> <tr> <td><strong>混合类型</strong></td> <td>一个文件既 user 又 project</td> <td>拆开，每个文件单一 type</td> </tr> <tr> <td><strong>巨型 MEMORY.md</strong></td> <td>200+ 行</td> <td>200 行后会被截断；精简、合并、删 stale</td> </tr> <tr> <td><strong>删而不重写</strong></td> <td>加新条目时把旧的留着”以防万一”</td> <td>直接覆盖，留着是 stale 之源</td> </tr> <tr> <td><strong>无日期相对时间</strong></td> <td>“上周开始”</td> <td>写绝对日期 <code class="language-plaintext highlighter-rouge">2026-05-07</code></td> </tr> </tbody> </table> <h3 id="92-claudemd-反模式">9.2 CLAUDE.md 反模式</h3> <table> <thead> <tr> <th>反模式</th> <th>症状</th> <th>修复</th> </tr> </thead> <tbody> <tr> <td><strong>复制 README</strong></td> <td>CLAUDE.md = README 重排</td> <td>删，让 README 自己说话</td> </tr> <tr> <td><strong>写通用最佳实践</strong></td> <td>“写有意义的提交信息”</td> <td>删；这是 system prompt 的事</td> </tr> <tr> <td><strong>文件清单</strong></td> <td>把 tree 粘进去</td> <td>删；ls 能给的不重复</td> </tr> <tr> <td><strong>过期不修</strong></td> <td>命令早改了仍写老命令</td> <td>季度审计 + 用错时修</td> </tr> <tr> <td><strong>巨型单文件</strong></td> <td>1000+ 行根 CLAUDE.md</td> <td>拆子目录或 @import</td> </tr> <tr> <td><strong>个人偏好混入团队 CLAUDE.md</strong></td> <td>“我用 emacs 所以 …”</td> <td>移到 user-level</td> </tr> </tbody> </table> <h3 id="93-hook-反模式">9.3 Hook 反模式</h3> <table> <thead> <tr> <th>反模式</th> <th>症状</th> <th>修复</th> </tr> </thead> <tbody> <tr> <td><strong>Hook 跑慢命令</strong></td> <td>每次工具调用阻塞 5s</td> <td>异步 / cache / 砍掉</td> </tr> <tr> <td><strong>Hook 输出过多</strong></td> <td>注入 500 行 git status</td> <td>只输出关键摘要</td> </tr> <tr> <td><strong>Hook 无限循环</strong></td> <td>hook 触发 hook</td> <td>加退出条件</td> </tr> <tr> <td><strong>Hook 当 logging</strong></td> <td>用 hook 记录所有动作</td> <td>用 <code class="language-plaintext highlighter-rouge">claude --debug</code> 或外部日志</td> </tr> </tbody> </table> <h3 id="94-subagent-反模式">9.4 Subagent 反模式</h3> <table> <thead> <tr> <th>反模式</th> <th>症状</th> <th>修复</th> </tr> </thead> <tbody> <tr> <td><strong>微任务用 subagent</strong></td> <td>“读这个 100 行的文件” 派 agent</td> <td>直接 Read</td> </tr> <tr> <td><strong>不写背景就派 fresh agent</strong></td> <td>subagent 困惑、效果差</td> <td>写完整 brief；或改用 fork</td> </tr> <tr> <td><strong>fork 后 peek</strong></td> <td>读 fork 中间输出</td> <td>等通知；信任完成消息</td> </tr> <tr> <td><strong>subagent 改了文件不验证</strong></td> <td>“subagent 报告完成”就直接信</td> <td>自己 git diff 看一眼</td> </tr> </tbody> </table> <hr /> <h2 id="10--治理与维护">§10 · 治理与维护</h2> <h3 id="101-月度-5-分钟流程">10.1 月度 5 分钟流程</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>1. ls ~/.claude/projects/&lt;cwd&gt;/memory/ ， 看条目数。 超过 30 → 触发清理（合并、删 stale）。 2. cat MEMORY.md，对每行问： - 还成立吗？ - 还有用吗？ - 索引行钩子写得够具体吗？ 3. 重新排序：跨任务最常用的提到顶部（避免 200 行截断）。 4. cd 到主要项目，cat CLAUDE.md， 挑 3 条具体命令 / 路径，验证仍存在。 </code></pre></div></div> <h3 id="102-跨项目搬迁信息">10.2 跨项目搬迁信息</h3> <p>memory 是 per-cwd 的。当你启动新工作区想沿用旧偏好时：</p> <ul> <li><strong>跨所有项目偏好</strong> → 已经在 user-level CLAUDE.md / 用户全局 settings 里，新 cwd 自动有</li> <li><strong>某些项目特定的 memory 想搬过去</strong> → 手动复制对应 <code class="language-plaintext highlighter-rouge">feedback_*.md</code>、<code class="language-plaintext highlighter-rouge">reference_*.md</code> 到新 cwd 的 memory 目录，更新 MEMORY.md 索引</li> <li><strong>不要全量复制</strong>：很多 memory 是上下文特定的（”在 X 项目中 …“），换 cwd 就不适用</li> </ul> <h3 id="103-团队中的-memory-边界">10.3 团队中的 memory 边界</h3> <p>memory 是个人的（per-user × per-cwd）。<strong>不要</strong>：</p> <ul> <li>把团队约定写进个人 memory（用 <code class="language-plaintext highlighter-rouge">&lt;repo&gt;/CLAUDE.md</code>，对所有人生效）</li> <li>把秘密写进 memory（虽然本地，但备份/同步可能泄漏）</li> <li>期待”队友的 agent 知道我教过我自己的 agent 的事”</li> </ul> <p>队友共享的载体：CLAUDE.md（项目）+ skills（项目内或共享 plugin）+ docs/。</p> <hr /> <h2 id="11--大师级模式">§11 · 大师级模式</h2> <h3 id="111-context-offloading-via-fork">11.1 Context offloading via fork</h3> <p>主对话上下文有限，长任务会污染。模式：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>主对话: 跟用户讨论方案 / 决策 / review └─ fork: 实际跑 5 分钟的"读 30 个文件 + 改 5 个" 任务 └─ 返回: "改完了，关键变更见 a.ts:42 / b.ts:88" 主对话: 看 git diff，确认 / 调整 </code></pre></div></div> <p>获益：</p> <ul> <li>主对话 tokens 不被工具结果污染</li> <li>prompt cache 在主对话里仍命中（fork 自己的 cache 独立）</li> <li>能”边干边聊”</li> </ul> <p>陷阱：</p> <ul> <li>fork 的工作可能不被你及时审视 → 完成后必看 git diff</li> <li>fork 没法继续接受新指令（要再发 SendMessage 或新派一个）</li> </ul> <h3 id="112-memory-as-protocol多-agent-协作时的契约层">11.2 Memory-as-protocol（多 agent 协作时的契约层）</h3> <p>当多个 agent（自定义 subagent / 团队 agent / cron 定时 agent）在同一个工作区操作时，用 memory 做”协议层”。例：</p> <ul> <li>agent A（每天 06:00 跑）写一条 project memory：”今天的发布完成，BV 号 X”</li> <li>agent B（你手动操作）启动会话时读到这条，知道当前状态</li> <li>agent C（review 用）通过 memory 知道”这个 PR 已经过了 A 的检查”</li> </ul> <p>这种用法把 memory 从”个人状态”升级为”agent 间传递结构化信息的总线”。配合自定义 schema 写得更紧（每条 frontmatter 加 <code class="language-plaintext highlighter-rouge">agent_origin</code> 字段）会更可控。</p> <h3 id="113-progressive-disclosure-三阶段">11.3 Progressive disclosure 三阶段</h3> <p>工作区进 → 子项目进 → 子模块进，每层只加载相关 CLAUDE.md：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>~/claw/CLAUDE.md # 工作区索引（150 行） ~/claw/lotus-academy-design/CLAUDE.md # 全栈应用大图（200 行） ~/claw/lotus-academy-design/server/CLAUDE.md # 后端契约（100 行） ~/claw/lotus-academy-design/server/src/auth/CLAUDE.md # auth 子模块（30 行） </code></pre></div></div> <p>注意：每一层只写<strong>这一层增量信息</strong>，不重复上层。最深层往往很短（30 行）但极有价值（”这个目录的代码不要 refactor 直到 X”）。</p> <h3 id="114-prompt-cache-友好的写作">11.4 Prompt cache 友好的写作</h3> <p>CLAUDE.md / MEMORY.md / 全局 settings 是每会话开头加载的，命中 cache 收益巨大。守则：</p> <ul> <li>不要在文件<strong>顶部</strong>频繁改动（顶部改一字符，下面整段 cache 失效）</li> <li>把不稳定内容放<strong>底部</strong>（动态状态、最近变化）</li> <li>把稳定的”框架”放顶部（项目目标、架构、不要做的事）</li> </ul> <h3 id="115-用-hook-做在线-instruction-tuning">11.5 用 hook 做”在线 instruction tuning”</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>UserPromptSubmit hook ├─ 检测 prompt 关键词 └─ 注入相关 CLAUDE.md section / memory 摘要 </code></pre></div></div> <p>这样你可以保持根 CLAUDE.md 极简，让 hook 在用户提到”部署”时再注入 deploy 章节。代价是 hook 复杂度上升、调试难。建议只在 CLAUDE.md 真的撑不下时再用。</p> <h3 id="116-skill-套娃与组合">11.6 Skill 套娃与组合</h3> <p>一个 skill 可以”组合”其他 skill：在 SKILL.md body 里写”先调用 /A，再调用 /B”。或者更优雅地：把通用步骤抽成 sub-skill，主 skill 引用。</p> <p>进阶：写一个 meta-skill <code class="language-plaintext highlighter-rouge">/morning-routine</code>，body 里依次：检查日历 → 跑 ai-morning-post → 同步 marginalia → 总结。每个子动作可以是更原子的 skill。</p> <h3 id="117-自定义-subagent-的-system-prompt-工程">11.7 自定义 subagent 的 system prompt 工程</h3> <p><code class="language-plaintext highlighter-rouge">~/.claude/agents/&lt;name&gt;.md</code> 让你定义专用 subagent。关键设计点：</p> <ul> <li><strong>限定工具集</strong>：去掉用不到的工具，减少干扰</li> <li><strong>明确身份</strong>：”你是 X 专家，只回答 X 相关问题”</li> <li><strong>限定输出格式</strong>：要求结构化输出，主对话好消化</li> <li><strong>写 negative behavior</strong>：明确说不要做什么（避免 fresh agent 自由发挥跑偏）</li> </ul> <h3 id="118-三体协同claudemd--memory--hook-的循环">11.8 三体协同：CLAUDE.md / memory / hook 的循环</h3> <p>成熟工作区会形成”自我增强”循环：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>1. 用户告诉 agent 一个新约定 2. agent 写 memory（个人偏好层） 3. 反复用证明这个约定确实跨任务有效 4. 升级到 CLAUDE.md（如果项目特定）或 user-level（如果跨项目） 5. 反复用证明它是 deterministic 的 6. 升级到 hook / permission（机制层） 7. 这时可以从 memory / CLAUDE.md 删除（机制层已保证） </code></pre></div></div> <p>这是一个<strong>信息从模糊到具体、从启发式到机制</strong>的”沉淀”过程。掌握节奏的人，工作区会越用越好用，而不是越用越乱。</p> <hr /> <h2 id="12--实战-case-studies">§12 · 实战 case studies</h2> <p>下面以本工作区（<code class="language-plaintext highlighter-rouge">~/claw</code>）实际场景为例。</p> <h3 id="case-1-用户告诉我-github-bot-账号有专用-pat">Case 1: “用户告诉我 GitHub bot 账号有专用 PAT”</h3> <p><strong>信息分类</strong>：跨会话个人状态（reference 类）+ 跨会话约定（feedback 类）。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">reference</code> memory: “GitHub bot 账号 gittee-coder 的 PAT 在 <code class="language-plaintext highlighter-rouge">~/.config/gh/{user,org_pyf-labrary}.token</code>”</li> <li><code class="language-plaintext highlighter-rouge">feedback</code> memory: “force-push 需用户批准；其他 GH 操作预授权（Why: 用户已显式授权）”</li> <li><code class="language-plaintext highlighter-rouge">&lt;repo&gt;/CLAUDE.md</code>：<strong>不写</strong>（个人状态，团队不需要知道你的 token 在哪）</li> <li><code class="language-plaintext highlighter-rouge">settings.json</code>：可以加 permissions allow <code class="language-plaintext highlighter-rouge">gh ...</code>，把”预授权”做成机制层</li> </ul> <p><strong>错误归属</strong>：</p> <ul> <li>把 token 路径写进项目 CLAUDE.md（泄漏）</li> <li>只写 feedback 不写 reference（agent 知道”可以做”但不知道 token 在哪）</li> </ul> <h3 id="case-2-本-repo-不要把-mp4-提交">Case 2: “本 repo 不要把 mp4 提交”</h3> <p><strong>信息分类</strong>：项目知识 + deterministic。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">&lt;repo&gt;/CLAUDE.md</code> “不要做的事”：写一行</li> <li><code class="language-plaintext highlighter-rouge">.gitignore</code>：<code class="language-plaintext highlighter-rouge">*.mp4</code>（机制层，根本拦下）</li> <li>可选 <code class="language-plaintext highlighter-rouge">.claude/settings.json</code>：pre-commit hook 校验</li> </ul> <p><strong>错误归属</strong>：</p> <ul> <li>只写 memory（每次新 cwd 又得重学；团队成员也不知道）</li> <li>只写 CLAUDE.md 不加 .gitignore（agent 99% 遵守，1% 翻车）</li> </ul> <h3 id="case-3-minimax-key-在-minimaxenv单价-x">Case 3: “MiniMax key 在 ~/.minimax.env，单价 X”</h3> <p><strong>信息分类</strong>：reference（外部资源 + 业务参数）。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">reference</code> memory：路径 + 单价 + 端点</li> <li>单价部分要标日期（”截至 2026-05-07”），方便未来识别 stale</li> <li>不写进 CLAUDE.md（个人 + 跨项目，不该和某个 repo 绑定）</li> </ul> <p>进阶：可以把”如何核对账单”也写进同一条 reference（因为没公开 API，要去 web 后台手动）。这种”边界条件”信息能避免未来 agent 浪费 10 分钟找根本不存在的 API。</p> <h3 id="case-4-周更视频要做到-36氪-水准不是精致-ppt">Case 4: “周更视频要做到 36氪 水准，不是精致 PPT”</h3> <p><strong>信息分类</strong>：feedback（视觉/品质偏好）。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">feedback</code> memory（已有：<a href="feedback_video_quality.md">视频质量门槛</a>）</li> </ul> <p>为什么不进 CLAUDE.md：</p> <ul> <li>这不是”项目本身的知识”，是”用户对视觉的判断标准”</li> <li>即使搬到另一台机器、另一个项目（如果做视频），这条仍成立 → 是个人偏好</li> </ul> <p><strong>关键 Why</strong>：feedback 必须写”为什么这是 36氪而不是 PPT”——可以引一个具体反例（”上次做的某期被指出像 PPT”）。这样未来 agent 看到”PPT 风”草稿能立刻警觉。</p> <h3 id="case-5-新发现一个-prompt-技巧避免-model-sheet-关键词">Case 5: “新发现一个 prompt 技巧：避免 model sheet 关键词”</h3> <p><strong>信息分类</strong>：feedback（实操经验，跨会话适用）。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">feedback</code> memory（已有：<a href="feedback_seedream_prompting.md">Seedream 概念图 prompt 经验</a>）</li> </ul> <p><strong>Why</strong> 部分要写：试过 X 关键词，结果出 Pixar 卡通；改用 Y 关键词，结果对。<strong>How to apply</strong>：在写 Seedream 提示词时，避开 X，倾向 Y。</p> <p>不进 CLAUDE.md 因为：跨多个项目（tv / bodhi 都用 Seedream），不属于单个 repo。</p> <h3 id="case-6-ai-周报视频每周一发">Case 6: “AI 周报视频每周一发”</h3> <p><strong>信息分类</strong>：project（有时间属性的工作流）。</p> <p><strong>正确归属</strong>：</p> <ul> <li><code class="language-plaintext highlighter-rouge">project</code> memory（已有：<a href="video_pipeline.md">AI 周报视频流水线</a>）+ Why 解释为何周一</li> <li><code class="language-plaintext highlighter-rouge">&lt;repo&gt;/video/CLAUDE.md</code>：可以引用 memory，但侧重”工程上怎么跑”</li> <li>进阶：起一个 cron / schedule（机制层）每周日提醒收集素材</li> </ul> <p><strong>衰减管理</strong>：如果某天改成隔周更，这条 project memory 必须立刻 update（不是新增另一条）。</p> <h3 id="case-7-agent-跑-publishpy-时把还没确认的文件也发了">Case 7: “agent 跑 publish.py 时把还没确认的文件也发了”</h3> <p><strong>信息分类</strong>：feedback（需要避免的模式）+ 可能升级 hook。</p> <p><strong>正确归属</strong>：</p> <ul> <li>先 <code class="language-plaintext highlighter-rouge">feedback</code> memory：解释场景 + Why + How（”publish.py 不要主动跑，先 dry-run / 让用户确认 git status”）</li> <li>如果再发生 → 升级 hook：<code class="language-plaintext highlighter-rouge">PreToolUse</code> on <code class="language-plaintext highlighter-rouge">Bash(*publish.py*)</code>，强制 ask</li> </ul> <p>这是 §11.8 沉淀循环的体现：feedback → 验证 → hook。</p> <hr /> <h2 id="13--参考清单每周每月例行">§13 · 参考清单：每周/每月例行</h2> <h3 id="每周">每周</h3> <ul> <li>翻一遍当周的对话（claude <code class="language-plaintext highlighter-rouge">/resume</code>），看有哪些用户纠正没被记 → 补 memory</li> <li>看有没有重复 ≥ 3 次的工作流 → 升级 skill</li> <li>看 hook 有没有过期或失败的（看 hook 日志）</li> </ul> <h3 id="每月">每月</h3> <ul> <li>MEMORY.md 巡检（§5.7、§10.1 的流程）</li> <li>主要项目 CLAUDE.md 失效检测（§6.6）</li> <li>skills 列表清点：哪些没用过 → 删；哪些总用 → 优化 description</li> </ul> <h3 id="每季">每季</h3> <ul> <li>ADR / docs 是否同步进 reference 类 memory</li> <li>settings.json permissions 清单是否仍合理（有些 deny 可能已不必要）</li> <li>跨项目偏好是否该提升到 user-level CLAUDE.md</li> </ul> <hr /> <h2 id="14--写在最后信息架构是agent-长跑的复利">§14 · 写在最后：信息架构是”agent 长跑”的复利</h2> <p>短期（一次会话）你看不出 memory / CLAUDE.md / hooks 的差别——直接在对话里粘东西也能用。</p> <p>中期（一个月）你会看出差别：每次重启 cwd，你的 agent 是一开始就懂规矩，还是要重新教十遍。</p> <p>长期（一年）你会看出量级差别：</p> <ul> <li>成熟工作区的 agent 能直接做”周更视频 + 上传 + 改写 marginalia”这种 7 步链式动作</li> <li>不维护信息架构的工作区，agent 永远停留在”逐步骤手把手”</li> </ul> <p>差距全在你怎么把信息分配给八层、怎么维护它们的鲜度、怎么把”反复出现的偏好”沉淀成”机制”。</p> <blockquote> <p>Memory is what you remember. CLAUDE.md is what we agreed. Settings is what won’t bend. Skills is how we do it. Subagent is who does it. The art is fitting each fact in the layer where it costs least to live and pays most when called.</p> </blockquote> <hr /> <p>附录：与本指南配套的实操脚手架</p> <ul> <li>用户当前工作区索引：<code class="language-plaintext highlighter-rouge">~/claw/CLAUDE.md</code></li> <li>个人 memory 总览：<code class="language-plaintext highlighter-rouge">~/.claude/projects/-home-pyf-claw/memory/MEMORY.md</code></li> <li>子项目示范（多项目协作）：<code class="language-plaintext highlighter-rouge">~/claw/marginalia/</code>、<code class="language-plaintext highlighter-rouge">~/claw/tv/</code>、<code class="language-plaintext highlighter-rouge">~/claw/lotus-academy-design/</code></li> </ul> <p>如果要把本教程”用起来”——下一步建议是：挑一个最常用的子项目，按 §6.3 三节模板给它写 CLAUDE.md；然后跑一次 §10.1 的 5 分钟巡检。这两个动作的 ROI 最高。</p>

基于第一性原理的 Claude Code 信息架构进阶教程：八层注入模型、memory 写作模板、四棵决策树、反模式速查与沉淀循环。从中级到大师水平。

2026-04-30T04:00:00+00:00 2026-04-30T04:00:00+00:00 https://jinzi.cyou/posts/agent-teams-report <blockquote> <p>来源：https://code.claude.com/docs/en/agent-teams 状态：实验性（experimental），默认关闭 版本要求：Claude Code ≥ 2.1.32</p> </blockquote> <hr /> <h2 id="1-它是什么">1. 它是什么</h2> <p>Agent Teams 让多个独立的 Claude Code 实例<strong>作为团队协同工作</strong>：</p> <ul> <li>一个会话作为 <strong>team lead（团队领导）</strong>：负责创建团队、派活、汇总成果</li> <li>其他会话作为 <strong>teammates（队友）</strong>：每人一个独立上下文窗口</li> <li>队友之间<strong>直接互相通信</strong>，不必经过 lead 中转</li> <li>用户也可以<strong>直接和某个队友对话</strong>，而不必让 lead 转达</li> </ul> <p>这是它和普通 subagent 最大的区别。</p> <h2 id="2-与-subagent-的对比">2. 与 Subagent 的对比</h2> <table> <thead> <tr> <th> </th> <th>Subagent</th> <th>Agent Team</th> </tr> </thead> <tbody> <tr> <td>上下文</td> <td>独立窗口，结果回传给主 agent</td> <td>独立窗口，完全独立</td> </tr> <tr> <td>通信</td> <td>只能向主 agent 报告</td> <td>队友互相直接发消息</td> </tr> <tr> <td>协调</td> <td>主 agent 全权管理</td> <td>共享任务列表 + 自协调</td> </tr> <tr> <td>适合</td> <td>结果导向的小任务</td> <td>需要讨论/挑战/协作的复杂任务</td> </tr> <tr> <td>Token 成本</td> <td>较低</td> <td>显著更高（每个队友是完整 Claude 实例）</td> </tr> </tbody> </table> <p><strong>经验法则</strong>：单纯并行干活用 subagent；要”互相辩论、互相 review、跨层协作”才上 team。</p> <h2 id="3-核心架构">3. 核心架构</h2> <table> <thead> <tr> <th>组件</th> <th>角色</th> </tr> </thead> <tbody> <tr> <td><strong>Team Lead</strong></td> <td>创建团队、派活、协调的主会话</td> </tr> <tr> <td><strong>Teammates</strong></td> <td>各自独立的 Claude Code 实例，处理被分配的任务</td> </tr> <tr> <td><strong>Task List</strong></td> <td>共享任务列表，队友自己 claim 任务</td> </tr> <tr> <td><strong>Mailbox</strong></td> <td>队友间消息系统（自动投递，无需 lead 轮询）</td> </tr> </tbody> </table> <p>存储位置：</p> <ul> <li>团队配置：<code class="language-plaintext highlighter-rouge">~/.claude/teams/{team-name}/config.json</code></li> <li>任务列表：<code class="language-plaintext highlighter-rouge">~/.claude/tasks/{team-name}/</code></li> </ul> <p>⚠️ 这两个文件由 Claude Code 自动维护，<strong>不要手动编辑</strong>，每次状态变更都会被覆盖。</p> <h2 id="4-启用方法">4. 启用方法</h2> <p>设置环境变量 <code class="language-plaintext highlighter-rouge">CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1</code>，可写入 <code class="language-plaintext highlighter-rouge">settings.json</code>：</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"env"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div></div> <p><strong>重要</strong>：这个变量在 <strong>session 启动时</strong>读取，已经在跑的 session 改了 settings.json 不会即时生效，必须<strong>重启 Claude Code</strong>。</p> <h2 id="5-显示模式">5. 显示模式</h2> <table> <thead> <tr> <th>模式</th> <th>说明</th> <th>要求</th> </tr> </thead> <tbody> <tr> <td><strong>in-process</strong></td> <td>所有队友在主终端内，Shift+Down 循环切换</td> <td>任意终端</td> </tr> <tr> <td><strong>split panes</strong></td> <td>每个队友独立面板，可点击交互</td> <td>tmux 或 iTerm2（+ <code class="language-plaintext highlighter-rouge">it2</code> CLI）</td> </tr> <tr> <td><strong>auto</strong>（默认）</td> <td>在 tmux 内自动用 split panes，否则 in-process</td> <td>—</td> </tr> </tbody> </table> <p>强制 in-process：<code class="language-plaintext highlighter-rouge">claude --teammate-mode in-process</code> 全局设置：<code class="language-plaintext highlighter-rouge">~/.claude/settings.json</code> 里 <code class="language-plaintext highlighter-rouge">"teammateMode": "in-process"</code></p> <h2 id="6-启动一个团队">6. 启动一个团队</h2> <p>启用功能后，<strong>用自然语言</strong>让 lead 创建团队：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>我在设计一个跟踪 TODO 注释的 CLI 工具。创建一个 agent team 从不同角度探索：一个负责 UX，一个负责技术架构， 一个唱反调（devil's advocate）。 </code></pre></div></div> <p>Claude 会自动：</p> <ol> <li>创建团队和共享 task list</li> <li>为每个角色 spawn 队友</li> <li>让他们各自探索</li> <li>综合发现</li> <li>完成后清理团队</li> </ol> <h2 id="7-控制团队">7. 控制团队</h2> <h3 id="指定数量和模型">指定数量和模型</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>创建 4 个队友的团队来并行重构这些模块，每个队友用 Sonnet。 </code></pre></div></div> <h3 id="要求计划审批高风险任务">要求计划审批（高风险任务）</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Spawn 一个 architect 队友来重构鉴权模块， 开工前要求计划审批。 </code></pre></div></div> <p>队友先在只读 plan mode 出方案 → 提交给 lead → lead 决定批/驳回 → 通过后再动手。</p> <h3 id="直接和某个队友对话">直接和某个队友对话</h3> <ul> <li><strong>in-process</strong>: Shift+Down 切换到队友 → 直接打字发消息；Enter 进入队友会话；Esc 打断；Ctrl+T 切换 task list</li> <li><strong>split-pane</strong>: 直接点对应面板</li> </ul> <h3 id="任务分配">任务分配</h3> <ul> <li>Lead 显式指派：告诉 lead 把哪个任务给谁</li> <li>自助 claim：队友干完一个就自动捡下一个空闲、无依赖的任务</li> <li>用文件锁防并发抢同一任务</li> </ul> <h3 id="关闭单个队友">关闭单个队友</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>让 researcher 队友关闭 </code></pre></div></div> <p>队友可同意（优雅退出）或拒绝（带理由）。</p> <h3 id="清理团队">清理团队</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>清理团队 </code></pre></div></div> <p>⚠️ 必须由 <strong>lead</strong> 执行，不能让队友清。清理前要先关掉所有队友。</p> <h2 id="8-复用-subagent-定义作为队友角色">8. 复用 Subagent 定义作为队友角色</h2> <p>可以引用任意 subagent type 作为队友：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>用 security-reviewer agent type spawn 一个队友，审计 auth 模块。 </code></pre></div></div> <p>队友会继承该定义的 <code class="language-plaintext highlighter-rouge">tools</code> 白名单和 <code class="language-plaintext highlighter-rouge">model</code>，定义体作为追加的系统提示。 <strong>注意</strong>：subagent 定义里的 <code class="language-plaintext highlighter-rouge">skills</code> 和 <code class="language-plaintext highlighter-rouge">mcpServers</code> 字段在队友模式下<strong>不生效</strong>，队友直接从项目和用户设置里加载。</p> <h2 id="9-用-hooks-强制质量门">9. 用 Hooks 强制质量门</h2> <table> <thead> <tr> <th>Hook</th> <th>触发时机</th> <th>用法</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">TeammateIdle</code></td> <td>队友即将进入 idle</td> <td>退出码 2 → 反馈并让其继续工作</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">TaskCreated</code></td> <td>任务正被创建</td> <td>退出码 2 → 阻止创建并反馈</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">TaskCompleted</code></td> <td>任务正被标记完成</td> <td>退出码 2 → 阻止完成并反馈</td> </tr> </tbody> </table> <h2 id="10-经典使用场景">10. 经典使用场景</h2> <h3 id="并行-code-review">并行 Code Review</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>创建 agent team review PR #142，spawn 三个 reviewer： - 一个看安全 - 一个看性能 - 一个看测试覆盖率 </code></pre></div></div> <p>单个 reviewer 倾向于盯一类问题，分工后各域同时被认真覆盖。</p> <h3 id="竞争性假设调试">竞争性假设调试</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>用户反馈 app 发完一条消息就退出。Spawn 5 个队友 调查不同假设，让他们互相对话尝试推翻对方理论， 像科学辩论一样。共识写进 findings doc。 </code></pre></div></div> <p>对抗性结构对抗”锚定偏差” —— 单 agent 容易找到一个看似合理的解释就停。</p> <h2 id="11-最佳实践">11. 最佳实践</h2> <ul> <li><strong>3-5 个队友为宜</strong>，每队友 5-6 个任务最舒服</li> <li><strong>任务粒度</strong>要适中：太小协调成本高，太大风险大</li> <li><strong>避免文件冲突</strong>：让每个队友拥有不同的文件集</li> <li><strong>新手从研究/审查类任务起步</strong>（不写代码），熟悉协作机制后再上并行实现</li> <li>上下文：队友会自动加载 <code class="language-plaintext highlighter-rouge">CLAUDE.md</code>、MCP、skills，<strong>但不继承 lead 的对话历史</strong>，所以 spawn prompt 必须自包含</li> <li>如果 lead 自己开始干活而非派活，明确告诉它”等队友完成”</li> </ul> <h2 id="12-已知限制实验性阶段">12. 已知限制（实验性阶段）</h2> <ul> <li>❌ <strong><code class="language-plaintext highlighter-rouge">/resume</code> <code class="language-plaintext highlighter-rouge">/rewind</code> 不能恢复 in-process 队友</strong>：恢复后队友已不在</li> <li>❌ 任务状态会延迟，有时队友忘记标记完成，阻塞依赖任务</li> <li>❌ 关闭慢：队友会先把当前请求/工具调用做完</li> <li>❌ 一次只能管一个团队，需先清理旧团队</li> <li>❌ 不能嵌套 team：队友不能再 spawn 自己的 team</li> <li>❌ Lead 固定：创建团队的会话终身是 lead，不能转让</li> <li>❌ Spawn 时所有队友共用 lead 的权限模式，事后才能单独改</li> <li>❌ Split panes 在 VS Code 集成终端、Windows Terminal、Ghostty 不支持</li> </ul> <h2 id="13-故障排查要点">13. 故障排查要点</h2> <table> <thead> <tr> <th>现象</th> <th>处理</th> </tr> </thead> <tbody> <tr> <td>队友看不见</td> <td>in-process 下按 Shift+Down 循环；任务可能没复杂到值得开 team</td> </tr> <tr> <td>权限弹窗太多</td> <td>提前在 permission settings 预批常用操作</td> </tr> <tr> <td>队友遇错就停</td> <td>直接给指令补救，或 spawn 替补队友</td> </tr> <tr> <td>Lead 提早收工</td> <td>告诉它继续 / 让它等队友完成</td> </tr> <tr> <td>残留 tmux 会话</td> <td><code class="language-plaintext highlighter-rouge">tmux ls</code> 找出，<code class="language-plaintext highlighter-rouge">tmux kill-session -t &lt;name&gt;</code> 清掉</td> </tr> </tbody> </table> <h2 id="14-总结">14. 总结</h2> <p>Agent Teams 是 Claude Code 把”多 agent 并发”从<strong>主从汇报模式</strong>升级到<strong>对等协作模式</strong>的实验功能：</p> <ul> <li>价值场景：研究/审查、新模块/功能、对抗性调试、跨层协作</li> <li>不适合：顺序任务、同文件编辑、强依赖任务（用单 session 或 subagent 更好）</li> <li>代价：Token 消耗显著增加，协调开销也随队友数增加</li> <li>当前阶段：实验性，明确知道限制再用</li> </ul>

Claude Code 2.1.32 起的实验功能 Agent Teams：sub-agent 之间如何协作、怎么写 agent.md 编排团队、怎么启用、相比单 agent 模式的取舍与坑点整理。

2026-04-28T04:00:00+00:00 2026-04-28T04:00:00+00:00 https://jinzi.cyou/posts/claude-max-token-guide <blockquote> <p>目标：把 Max $100/月套餐的”请求次数”和”token 量”两方面用到极限。 阅读对象：刚开始用 Claude Code、对 LLM 计费机制不熟悉的用户。 最后更新：2026-04-28。</p> </blockquote> <hr /> <h2 id="0-先理解你的额度到底是什么">0. 先理解：你的额度到底是什么？</h2> <p>很多人以为 “Max $100 = 每月多少次请求”。<strong>错。</strong></p> <h3 id="01-llm-是按-token-计费的">0.1 LLM 是按 token 计费的</h3> <ul> <li><strong>token 是模型看世界的最小单位</strong>。一个英文单词约 1.3 token，一个汉字约 1–2 token。一段 1000 字中文 ≈ 1500 token。</li> <li>每次你和 Claude 对话，它都会把<strong>整个会话历史 + 系统提示 + 你新说的话</strong>全部当成”输入 token”重新读一遍，然后生成”输出 token”作为回复。</li> <li>Anthropic 对 Opus 4.7 的官方价：<strong>输入 $5 / 百万 token，输出 $25 / 百万 token</strong>。这是地板价，所有产品在这个价位上加价或打包。</li> </ul> <h3 id="02-max-100-套餐的本质">0.2 Max $100 套餐的本质</h3> <p>不是”无限用”，而是<strong>“按 token 折算的额度，分两个时间窗口结算”</strong>：</p> <ul> <li><strong>5 小时滚动窗口</strong>：从你第一次发消息开始计时，5 小时内能用的 token 量有上限。Max $100 大约是 Pro 的 5 倍。</li> <li><strong>周窗口</strong>：再叠一层 7 天总量上限，防止你 5h 满血连续刷。</li> <li>触顶后两种选择：等窗口刷新，或开 <code class="language-plaintext highlighter-rouge">/extra-usage</code> 自动按 API 原价续费。</li> </ul> <p><strong>关键理解</strong>：你浪费的不是”次数”，是 token。一次塞满 1M context 的请求 ≈ 几十次小请求的额度。所以<strong>省 token = 省额度 = 多干活</strong>。</p> <hr /> <h2 id="1-最大化请求次数压低单次成本">1. 最大化”请求次数”——压低单次成本</h2> <h3 id="11-让-prompt-cache-真正命中最重要的一条">1.1 让 prompt cache 真正命中（最重要的一条）</h3> <h4 id="技术原理">技术原理</h4> <p>LLM 推理时，每个 token 都要和<strong>前面所有 token</strong>做注意力计算，越长的 context 越贵越慢。Anthropic 发现：很多对话的开头部分（system prompt、CLAUDE.md、项目说明）是反复出现的，每次重算太浪费。</p> <p>于是他们做了 <strong>prompt cache</strong>：</p> <ol> <li>你第一次发请求时，Anthropic 把对话<strong>前缀</strong>（从开头开始连续的一段）算完后，把中间结果（KV cache，模型内部状态）存到服务器上，打个指纹。</li> <li>下次你再发请求，如果<strong>前缀完全一致</strong>，直接复用上次的中间结果，不用重算。</li> <li>命中部分的计费：<strong>只收原价的 0.1×</strong>（即 1/10 价）。</li> <li>默认 cache 存活 5 分钟（5min TTL），写入要付 1.25× 的”建表费”；1 小时版本写入 2×，但适合长任务。</li> </ol> <p><strong>关键限制</strong>：cache 是<strong>前缀匹配</strong>。只要前面有一个 token 变了，后面所有 cache 全失效，得从变动点之后重算。</p> <h4 id="操作建议">操作建议</h4> <ul> <li><strong>同一个会话连续干活，别频繁 <code class="language-plaintext highlighter-rouge">/clear</code></strong>。<code class="language-plaintext highlighter-rouge">/clear</code> 会把整个对话历史清空，下一条消息等于从零建 cache，等于把前面所有 cache 钱白扔了。</li> <li><strong>不要中途改 CLAUDE.md / system prompt / 早期消息</strong>。这些都在前缀里，改了 = 后面全失效。 <ul> <li>把<strong>稳定内容</strong>（项目结构、规范、常用命令）放 CLAUDE.md 顶部。</li> <li>把<strong>易变内容</strong>（当前任务描述、临时笔记）放对话末尾或单独说。</li> </ul> </li> <li><strong>同一个文件让 Claude 反复 Read 没关系</strong>——它读过一次后，文件内容就在 context 里了，第二次读会 cache 命中，几乎免费。</li> <li>长会话越用越省，因为前缀越长、cache 占比越大。</li> </ul> <h3 id="12-选对模型档位省-35">1.2 选对模型档位（省 3–5×）</h3> <h4 id="技术原理-1">技术原理</h4> <p>Anthropic 一个家族里有多个模型：</p> <ul> <li><strong>Opus 4.7</strong>：最聪明，最贵（$5/$25 per M token）。适合规划、复杂重构、难 debug。</li> <li><strong>Sonnet 4.6</strong>：聪明 80%，价格 1/5（$3/$15 per M token）。适合执行类任务。</li> <li><strong>Haiku 4.5</strong>：够用，价格 1/25 左右（$1/$5）。适合格式化、简单脚本、命令解释。</li> </ul> <p>模型差距主要在<strong>多步推理深度</strong>。你让它”把这个函数改成异步”，Sonnet 完全够；你让它”重新设计这个模块的并发模型”，才需要 Opus。</p> <h4 id="操作建议-1">操作建议</h4> <ul> <li>在 Claude Code 里 <code class="language-plaintext highlighter-rouge">/model sonnet</code> 或 <code class="language-plaintext highlighter-rouge">/model haiku</code> 切换。</li> <li><strong>经典省钱组合：Opus 规划 + Sonnet 执行</strong>。 <ul> <li>按 <code class="language-plaintext highlighter-rouge">Shift+Tab</code> 两次进入 <strong>Plan Mode</strong>，让 Opus 出方案。</li> <li>方案确认后切 Sonnet 执行。同一个会话内 cache 还在，无缝衔接。</li> </ul> </li> <li>如果你发现自己每天都顶 5h 上限：八成在用 Opus 干 Sonnet 该干的活。</li> </ul> <h3 id="13-用-subagent-隔离上下文保护主对话-cache">1.3 用 subagent 隔离上下文（保护主对话 cache）</h3> <h4 id="技术原理-2">技术原理</h4> <p>Subagent 是”开一个独立子对话”。它有自己的 context、自己的工具调用，完事后<strong>只把摘要返回</strong>给主对话。</p> <p>为什么省钱？</p> <ul> <li>探索类任务（”找出所有调用 X 的地方”）要读几十个文件，主对话如果亲自读，context 立刻被几万行代码污染，<strong>后续每条消息都要重读这堆垃圾</strong>，每次都按现价算（cache 命中部分变少）。</li> <li>让 subagent 去读，主对话只收到 200 字摘要。主对话 context 干净，cache 持续命中。</li> </ul> <h4 id="操作建议-2">操作建议</h4> <ul> <li>探索代码库 → 用内置的 <code class="language-plaintext highlighter-rouge">Explore</code> subagent。</li> <li>复杂规划 → 用 <code class="language-plaintext highlighter-rouge">Plan</code> subagent。</li> <li>代码审查 → 用 <code class="language-plaintext highlighter-rouge">code-reviewer</code> subagent。</li> <li>在 Claude Code 里直接说”用 Explore agent 找一下 …“，或它会自动调度。</li> </ul> <h3 id="14-compact-而不是-clear">1.4 <code class="language-plaintext highlighter-rouge">/compact</code> 而不是 <code class="language-plaintext highlighter-rouge">/clear</code></h3> <h4 id="技术原理-3">技术原理</h4> <ul> <li><strong><code class="language-plaintext highlighter-rouge">/clear</code></strong>：把对话历史完全清空，从零开始。下一条消息发出去是空 cache，要重新建（贵）。</li> <li><strong><code class="language-plaintext highlighter-rouge">/compact</code></strong>：让 Claude 把长对话压缩成一段<strong>摘要</strong>保留下来，然后基于摘要继续。Claude Code 会把摘要作为新前缀重建 cache，但保留了关键决策、已读文件、当前进度。</li> </ul> <p>何时该用：</p> <ul> <li>接近 context 上限（200k 或 1M）时，必须二选一。</li> <li>任务还没完成 → <code class="language-plaintext highlighter-rouge">/compact</code>。</li> <li>任务已结束、要换全新任务 → <code class="language-plaintext highlighter-rouge">/clear</code>。</li> </ul> <hr /> <h2 id="2-最大化token-量把-1m-上下文用满">2. 最大化”token 量”——把 1M 上下文用满</h2> <p>Max 套餐的最大红利：<strong>Opus 4.7 默认 1M context，200k 以上不加价</strong>。这是 API 直连都享受不到的福利（API 上 1M 是企业版才默认）。</p> <h3 id="21-一次喂够上下文别来回追问">2.1 一次喂够上下文，别来回追问</h3> <h4 id="技术原理-4">技术原理</h4> <p>每次发消息，模型都要重读整个会话。你做对比：</p> <ul> <li><strong>方案 A</strong>：5 轮对话，每轮喂 1 个文件 + 提问 → 5 次推理，每次都带前 N 轮历史。token 总量 ≈ 1+2+3+4+5 = 15 份文件。</li> <li><strong>方案 B</strong>：1 轮对话，喂 5 个文件 + 完整任务 → 1 次推理，token ≈ 5 份文件。</li> </ul> <p>哪怕考虑 cache，方案 B 也明显便宜（少 60% token），而且<strong>结果更好</strong>——模型一次看到全貌比逐步喂更容易抓到关联。</p> <h4 id="操作建议-3">操作建议</h4> <ul> <li>任务开始前花 30 秒想清楚：”这个任务需要它看哪些文件？”，一次性让它 Read 全。</li> <li>让 Claude 自主探索（用 Bash/Grep/Read 工具）比你手动复制粘贴片段更省——它的工具调用走 cache，你的人工粘贴是全新 input token。</li> <li>任务描述要完整：背景、目标、约束、不要做什么，一次说清。</li> </ul> <h3 id="22-善用-1-小时长-cache">2.2 善用 1 小时长 cache</h3> <h4 id="技术原理-5">技术原理</h4> <p>默认 cache 是 5 分钟 TTL，超时就失效。如果你的任务持续超过 5 分钟（Claude 在思考、跑测试、读大文件），cache 会过期，下一条消息又得重建。</p> <p><strong>1 小时 cache</strong> 的交易：写入收 2× 钱（贵 60%），但保 1 小时。</p> <ul> <li>短任务：5min cache 划算。</li> <li>长任务（&gt;10 分钟、跨多个回合）：1h cache 净赚——一次贵的写入，换十几次 0.1× 读取。</li> </ul> <h4 id="操作建议-4">操作建议</h4> <ul> <li>Claude Code 在 Max 套餐下会<strong>自动判断</strong>是否升级到 1h cache，你一般不用管。</li> <li>如果你自己用 API 写脚本，手动设 <code class="language-plaintext highlighter-rouge">cache_control: {type: "ephemeral", ttl: "1h"}</code>。</li> </ul> <h3 id="23-避开-token-浪费的几个坑">2.3 避开 token 浪费的几个坑</h3> <h4 id="坑-1让它读巨型-lock-文件--dist--node_modules">坑 1：让它读巨型 lock 文件 / dist / node_modules</h4> <p><code class="language-plaintext highlighter-rouge">package-lock.json</code> 动辄几万行，读一次几十万 token，cache 也救不了——因为你只读这一次。</p> <p><strong>对策</strong>：</p> <ul> <li>项目根目录建 <code class="language-plaintext highlighter-rouge">.claudeignore</code>，列出要跳过的路径： <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>node_modules/ dist/ build/ *.lock *.log .next/ </code></pre></div> </div> </li> <li>CLAUDE.md 里也写一句”不要读 X 目录”。</li> </ul> <h4 id="坑-2截图比文字贵">坑 2：截图比文字贵</h4> <h4 id="技术原理-6">技术原理</h4> <p>图片在模型里被切成”图块 token”，一张普通截图 ≈ 1500–2000 token，相当于上千字英文。</p> <p><strong>对策</strong>：能用文字描述清楚的就别贴图。报错信息、代码、配置都是文字，别截图。</p> <h4 id="坑-3原始-git-diff--大日志直接塞">坑 3：原始 <code class="language-plaintext highlighter-rouge">git diff</code> / 大日志直接塞</h4> <p>几千行 diff 几万 token 起步。</p> <p><strong>对策</strong>：</p> <ul> <li>先 <code class="language-plaintext highlighter-rouge">git diff --stat</code> 看哪些文件变了。</li> <li>再针对性看具体文件：<code class="language-plaintext highlighter-rouge">git diff src/foo.ts</code>。</li> <li>大日志先 <code class="language-plaintext highlighter-rouge">tail -100</code> 或 <code class="language-plaintext highlighter-rouge">grep ERROR</code> 过滤。</li> </ul> <h4 id="坑-4让-opus-来回-lint--typecheck">坑 4：让 Opus 来回 lint / typecheck</h4> <p>每次让它”再跑一下 tsc 看看”都是新 token。</p> <p><strong>对策</strong>：用 <strong>hooks</strong>（在 Claude Code <code class="language-plaintext highlighter-rouge">settings.json</code> 里配）。</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"hooks"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"PostToolUse"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"matcher"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Edit|Write"</span><span class="p">,</span><span class="w"> </span><span class="nl">"command"</span><span class="p">:</span><span class="w"> </span><span class="s2">"npm run typecheck"</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div></div> <p>每次 Edit/Write 后自动跑 typecheck，结果直接喂回 Claude，无需你提示。</p> <hr /> <h2 id="3-配额监控与节奏">3. 配额监控与节奏</h2> <h3 id="31-看准你在哪个窗口">3.1 看准你在哪个窗口</h3> <ul> <li><code class="language-plaintext highlighter-rouge">/status</code> 查当前 5h 窗口剩余 + 周限额剩余。</li> <li><strong>5h 窗口从你第一次请求时启动</strong>，不是整点对齐。比如你 09:30 发第一条，窗口到 14:30。</li> <li><code class="language-plaintext highlighter-rouge">/cost</code> 看当前会话烧了多少 token + 等价美元。校准直觉用。</li> </ul> <h3 id="32-排期策略">3.2 排期策略</h3> <h4 id="5h-窗口内">5h 窗口内</h4> <ul> <li><strong>一个连续大任务 + cache 持续命中</strong> &gt; 5 个独立小任务。</li> <li>上午 plan、下午 execute 是两个独立窗口、两次冷 cache 起步，不如一气呵成。</li> <li>想休息：让 Claude 在 5h 窗口结束前完成阶段性产出，写到文件或 CLAUDE.md，下个窗口让它自己 Read 续上。</li> </ul> <h4 id="周窗口内">周窗口内</h4> <ul> <li>周一前几个窗口做 Opus 硬活（规划、架构、难 bug）。</li> <li>周中后段切 Sonnet 续命。</li> <li>用 <code class="language-plaintext highlighter-rouge">/extra-usage set-limit</code> 设上限（比如 $50/月），防失控。</li> </ul> <h3 id="33-红线指标超过说明你在亏">3.3 红线指标（超过说明你在亏）</h3> <table> <thead> <tr> <th>现象</th> <th>含义</th> <th>对策</th> </tr> </thead> <tbody> <tr> <td>每天都顶 5h 上限</td> <td>在用 Opus 干 Sonnet 的活</td> <td>切档；区分规划 vs 执行</td> </tr> <tr> <td>Opus 重读同样代码 &gt;3 次</td> <td>cache 没命中</td> <td>检查是否中途 <code class="language-plaintext highlighter-rouge">/clear</code> 或改了 CLAUDE.md</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/extra-usage</code> 月超 $50</td> <td>用量已超 Max $100 价值</td> <td>升 Max $200 更划算</td> </tr> <tr> <td>一次任务 &gt;30 万 token 还没出结果</td> <td>Claude 在打转</td> <td>停掉，重新拆解任务</td> </tr> </tbody> </table> <hr /> <h2 id="4-claude-code-必配清单">4. Claude Code 必配清单</h2> <p>按这个顺序配置一次，长期受益：</p> <h3 id="41-claudemd项目根目录">4.1 CLAUDE.md（项目根目录）</h3> <p>每次启动 Claude Code 自动加载，进 cache。范例：</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># 项目说明</span> 这是一个 React + Node.js 全栈应用，TypeScript。 <span class="gh"># 目录结构</span> <span class="p">-</span> src/client: 前端 <span class="p">-</span> src/server: 后端 <span class="p">-</span> src/shared: 共享类型 <span class="gh"># 常用命令</span> <span class="p">-</span> 开发: pnpm dev <span class="p">-</span> 测试: pnpm test <span class="p">-</span> 构建: pnpm build <span class="gh"># 不要碰</span> <span class="p">-</span> node_modules/, dist/, <span class="err">*</span>.lock <span class="p">-</span> src/legacy/ (废弃代码) <span class="gh"># 风格</span> <span class="p">-</span> 优先编辑现有文件，不要新建 <span class="p">-</span> 不写注释除非有非显然的 why </code></pre></div></div> <h3 id="42-claudeignore项目根目录">4.2 .claudeignore（项目根目录）</h3> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>node_modules/ dist/ build/ .next/ *.lock *.log *.min.js coverage/ </code></pre></div></div> <h3 id="43-自定义-subagentsclaudeagents-目录">4.3 自定义 subagents（<code class="language-plaintext highlighter-rouge">.claude/agents/</code> 目录）</h3> <p>为高频任务建专属 agent，复用时省 cache。</p> <h3 id="44-hooksclaudesettingsjson">4.4 Hooks（<code class="language-plaintext highlighter-rouge">.claude/settings.json</code>）</h3> <p>自动化重复检查，省 token 又快。</p> <h3 id="45-命令速查">4.5 命令速查</h3> <table> <thead> <tr> <th>命令</th> <th>用途</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">/model opus</code> / <code class="language-plaintext highlighter-rouge">sonnet</code> / <code class="language-plaintext highlighter-rouge">haiku</code></td> <td>切模型</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/status</code></td> <td>看配额剩余</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/cost</code></td> <td>看本会话消费</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/compact</code></td> <td>压缩对话保留摘要</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/clear</code></td> <td>全清（慎用）</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/agents</code></td> <td>管理 subagent</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">/extra-usage</code></td> <td>配置超额自动续费</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">Shift+Tab</code> ×2</td> <td>进 Plan Mode</td> </tr> </tbody> </table> <hr /> <h2 id="5-tldr三条最高-roi-的动作">5. TL;DR——三条最高 ROI 的动作</h2> <p>如果你只看这一节：</p> <ol> <li> <p><strong>保持长会话 + 稳定 CLAUDE.md</strong> 让 prompt cache 持续命中。理论上能省 10×。前提：别频繁 <code class="language-plaintext highlighter-rouge">/clear</code>，别中途改顶部内容。</p> </li> <li> <p><strong>Opus 规划 / Sonnet 执行</strong> 规划用 Opus（Plan Mode），执行切 Sonnet。能省 3–5×，效果不打折。</p> </li> <li> <p><strong>一次喂够上下文</strong> 任务开始时把所有相关文件、完整需求一次说清，让 Claude 自己探索代码库。比来回追问省 2–3× token，结果还更好。</p> </li> </ol> <hr /> <h2 id="附录核心数字速记">附录：核心数字速记</h2> <table> <thead> <tr> <th>项</th> <th>数值</th> </tr> </thead> <tbody> <tr> <td>Opus 4.7 输入</td> <td>$5 / 百万 token</td> </tr> <tr> <td>Opus 4.7 输出</td> <td>$25 / 百万 token</td> </tr> <tr> <td>Sonnet 4.6 输入/输出</td> <td>$3 / $15 per M</td> </tr> <tr> <td>Cache 写入（5min）</td> <td>1.25× 输入价</td> </tr> <tr> <td>Cache 写入（1h）</td> <td>2× 输入价</td> </tr> <tr> <td>Cache 命中读</td> <td>0.1× 输入价（<strong>省 90%</strong>）</td> </tr> <tr> <td>Max $100 配额折算</td> <td>≈ Pro $20 的 5 倍</td> </tr> <tr> <td>Max 套餐 Opus context</td> <td>默认 1M，200k 以上无溢价</td> </tr> <tr> <td>5h 窗口</td> <td>从首条消息计时</td> </tr> <tr> <td>1 张截图</td> <td>≈ 1500–2000 token</td> </tr> <tr> <td>1000 字中文</td> <td>≈ 1500 token</td> </tr> </tbody> </table>

理解 Claude Max 套餐的 token 计费本质：最大化 prompt cache 命中率、压低单次请求成本、把 5 小时与 7 天双时间窗口的额度榨干。Claude Code 实战经验整理。

2026-04-27T04:00:00+00:00 2026-04-27T04:00:00+00:00 https://jinzi.cyou/posts/apple-giftcard-claude-pro <h2 id="一为什么要走-apple-内购">一、为什么要走 Apple 内购？</h2> <table> <thead> <tr> <th>维度</th> <th>Web 直接订阅</th> <th>Apple 内购</th> </tr> </thead> <tbody> <tr> <td><strong>支付方式</strong></td> <td>信用卡/PayPal</td> <td>礼品卡余额</td> </tr> <tr> <td><strong>卡片归属地检测</strong></td> <td>Stripe 直接校验 BIN 归属地</td> <td><strong>不存在</strong> —— Apple 代收，Anthropic 看不到卡信息</td> </tr> <tr> <td><strong>中国信用卡</strong></td> <td>大概率被拒</td> <td>无关，你根本不用卡</td> </tr> <tr> <td><strong>账单地址</strong></td> <td>需填支持地区的地址</td> <td>只跟 Apple ID 有关</td> </tr> <tr> <td><strong>被封号后</strong></td> <td>钱打水漂</td> <td>向 Apple 申请退款，成功率高</td> </tr> <tr> <td><strong>风控门面</strong></td> <td>Anthropic → Stripe → 你的卡</td> <td>Anthropic → Apple → (你的余额)</td> </tr> </tbody> </table> <p><strong>一句话：Apple 是支付中间层，Anthropic 看到的是 Apple 付的钱，不是你付的。卡片归属地判断完全不存在。</strong></p> <hr /> <h2 id="二能否省钱">二、能否省钱？</h2> <h3 id="21-价格对比">2.1 价格对比</h3> <table> <thead> <tr> <th>路径</th> <th>月费</th> <th>年费</th> <th>备注</th> </tr> </thead> <tbody> <tr> <td>Web 直接订阅</td> <td>$20</td> <td>$240</td> <td>美国 IP 免税州</td> </tr> <tr> <td>Web 直接订阅（含税）</td> <td>$21.5-22</td> <td>$258-264</td> <td>含美国各州消费税</td> </tr> <tr> <td>iOS 内购（美区）</td> <td>$20</td> <td>$199.99</td> <td>Apple 显示价格</td> </tr> <tr> <td><strong>礼品卡 + 内购</strong></td> <td><strong>折后 ¥116-136</strong></td> <td><strong>折后 ¥1160-1360</strong></td> <td>见下文分析</td> </tr> </tbody> </table> <h3 id="22-省钱的两个渠道">2.2 省钱的两个渠道</h3> <p><strong>渠道 1：礼品卡本身打折</strong></p> <p>美区 App Store 礼品卡在多个渠道长期有折扣：</p> <table> <thead> <tr> <th>购买渠道</th> <th>折扣</th> <th>到账</th> <th>风险</th> </tr> </thead> <tbody> <tr> <td><strong>亚马逊美区</strong></td> <td>偶尔 85-90 折</td> <td>电子卡，15 分钟</td> <td>极低（官方渠道）</td> </tr> <tr> <td><strong>Costco</strong></td> <td>通常 85-90 折</td> <td>电子卡</td> <td>极低</td> </tr> <tr> <td><strong>Target</strong></td> <td>偶尔 85 折 + 红卡再减 5%</td> <td>电子卡</td> <td>需美卡支付</td> </tr> <tr> <td><strong>淘宝/闲鱼</strong></td> <td>¥6.2-6.8 / $1</td> <td>电子卡</td> <td><strong>高</strong>（黑卡/盗刷/回收）</td> </tr> <tr> <td><strong>充值平台</strong>（如网易等）</td> <td>¥6.5-7.0 / $1</td> <td>电子卡</td> <td>中（价差小不如自己买）</td> </tr> </tbody> </table> <p><strong>不建议碰淘宝/闲鱼</strong>：黑卡充值可能导致 Apple ID 被拉黑，得不偿失。</p> <p><strong>推荐方式</strong>：注册亚马逊美区账号（不需要美国信用卡，礼品卡余额可买苹果礼品卡），等折扣季囤卡。</p> <p><strong>渠道 2：免税州 Apple ID</strong></p> <p>美国不同州对数字服务的税率不同：</p> <table> <thead> <tr> <th>州类型</th> <th>税率</th> <th>$20/月的实际支出</th> </tr> </thead> <tbody> <tr> <td>免税州（OR/DE/MT/NH/AK）</td> <td>0%</td> <td>$20.00</td> </tr> <tr> <td>低税州</td> <td>4-6%</td> <td>$20.80-21.20</td> </tr> <tr> <td>高税州（NY/CA）</td> <td>8-9%</td> <td>$21.60-21.80</td> </tr> </tbody> </table> <p><strong>把美区 Apple ID 的账单地址设为免税州</strong>（推荐俄勒冈州 Oregon，波特兰随便找个地址），就不收税。</p> <h3 id="23-实际省钱测算">2.3 实际省钱测算</h3> <p>假设常规汇率 7.15，你买卡 9 折：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>按年订阅（App Store 年费 $199.99）： 正价 × 汇率 = $199.99 × 7.15 ≈ ¥1,430 买卡成本 = $200 × 0.9 × 汇率买到价 如果亚马逊 85 折囤卡：$200 × 0.85 × 汇率 ≈ ¥1,215 如果 Costco 9 折：$200 × 0.9 × 汇率 ≈ ¥1,287 对比 Web 直接订阅（免税州）$199.99 × 7.15 ≈ ¥1,430 年省：¥143 ~ ¥215 </code></pre></div></div> <p>如果你按月订 $20/月，省得更多因为月付本来就更贵。</p> <p>此外，还有一个<strong>间接省钱</strong>：</p> <ul> <li>Web 订阅封号 → 钱不退，申诉成功率低</li> <li>Apple 内购封号 → Apple 退款政策友好，90 天内基本能退</li> </ul> <hr /> <h2 id="三完整操作步骤">三、完整操作步骤</h2> <h3 id="第一步注册美区-apple-id">第一步：注册美区 Apple ID</h3> <p><strong>在 iPhone/iPad 上操作</strong>：</p> <ol> <li>打开 App Store → 点右上角头像 → <strong>退出登录</strong></li> <li>点 “创建新 Apple ID”</li> <li>国家/地区选择 <strong>United States</strong></li> <li>邮箱：用 <strong>Gmail / Proton Mail</strong>（不要 QQ/163）</li> <li>手机号：<strong>可以填 +86</strong>（Apple 允许中国手机号注册美区账号）</li> <li>付款方式：<strong>选 None</strong>（一开始没有 None 选项，往下看）</li> </ol> <p>关键步骤——让 None 出现：</p> <p>注册过程中 App Store 会提示你绑卡。此时：</p> <ol> <li><strong>先去 App Store 首页</strong>，找一个免费 App（任何免费 App）→ 点 “获取”</li> <li>弹出登录提示，选 “创建新 Apple ID”</li> <li>走完注册流程后，付款方式里会出现 <strong>None</strong></li> <li>选 None，然后填写美国账单地址</li> </ol> <p><strong>账单地址填什么</strong>：</p> <p>找一个免税州的地址。推荐俄勒冈州：</p> <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>街道: 1234 NW Lovejoy St 城市: Portland 州: Oregon (OR) 邮编: 97209 电话: (503) 555-0199 </code></pre></div></div> <h3 id="第二步购买-apple-礼品卡">第二步：购买 Apple 礼品卡</h3> <p><strong>推荐亚马逊美区</strong>（不需要美卡）：</p> <ol> <li>注册 amazon.com 账号（不要求美国信用卡）</li> <li>搜索 “App Store Gift Card”</li> <li>选 <strong>Email delivery</strong>（电子卡）</li> <li>金额选 $25 / $50 / $100</li> <li>支付方式： <ul> <li>如果能办美卡（如 BitGet/PokePay），直接付</li> <li>如果没有，可以在亚马逊上买 Gift Card 也要支付方式，这是个鸡生蛋问题</li> <li><strong>解法</strong>：用支付宝在某些支持平台买（见下方）</li> </ul> </li> </ol> <p><strong>实际可行的购买路径</strong>：</p> <table> <thead> <tr> <th>平台</th> <th>可用支付</th> <th>溢价</th> </tr> </thead> <tbody> <tr> <td><strong>网易 UU</strong></td> <td>支付宝/微信</td> <td>汇率 + 5-10%</td> </tr> <tr> <td><strong>支付宝里搜 “美区App Store”</strong></td> <td>支付宝</td> <td>汇率 + 5-15%</td> </tr> <tr> <td><strong>Seagm</strong></td> <td>支付宝/微信</td> <td>汇率 + 10-20%</td> </tr> <tr> <td><strong>亚马逊美区</strong></td> <td>需美卡</td> <td>无溢价 + 时有折扣</td> </tr> </tbody> </table> <p>如果你能搞到美卡（PokePay / OneKey / BitGet 卡可能是美卡），在亚马逊买是成本最低的。</p> <h3 id="第三步充值">第三步：充值</h3> <ol> <li>iPhone/iPad 打开 App Store</li> <li>确认已登录<strong>美区 Apple ID</strong></li> <li>右上角头像 → <strong>兑换礼品卡或代码</strong></li> <li>输入礼品卡代码（或手机扫描卡片背面的码）</li> <li>余额即时到账</li> </ol> <h3 id="第四步订阅-claude-pro">第四步：订阅 Claude Pro</h3> <ol> <li>保持<strong>美区 Apple ID 登录状态</strong></li> <li>App Store 搜索 “Claude” → 下载 Anthropic 官方 Claude App</li> <li>打开 Claude App → 登录你的 Claude 账号</li> <li>设置 → <strong>Upgrade to Pro</strong></li> <li>弹出 App Store 订阅确认框，点 <strong>订阅</strong></li> <li>扣款从 Apple ID 余额中扣除</li> </ol> <hr /> <h2 id="四费用节省速算">四、费用节省速算</h2> <table> <thead> <tr> <th>策略</th> <th>年费支出</th> <th>vs Web 直付（¥1,430）</th> </tr> </thead> <tbody> <tr> <td>亚马逊正价 + 免税州</td> <td>≈ ¥1,430</td> <td>持平，但绕过了卡片风控</td> </tr> <tr> <td>亚马逊 9 折 + 免税州</td> <td>≈ ¥1,287</td> <td>年省 ¥143</td> </tr> <tr> <td>亚马逊 85 折 + 免税州</td> <td>≈ ¥1,215</td> <td>年省 ¥215</td> </tr> <tr> <td>淘宝低价卡（高风险）</td> <td>≈ ¥1,000-1,100</td> <td>年省 ¥300+ 但可能 Apple ID 被拉黑</td> </tr> </tbody> </table> <p><strong>最重要的收益不在省钱，在于：</strong></p> <ol> <li>绕过了卡片归属地检测（这是最大价值）</li> <li>Apple 退款保护</li> <li>不需要海外信用卡</li> </ol> <hr /> <h2 id="五常见问题">五、常见问题</h2> <p><strong>Q: 要不要打苹果客服电话绑卡？</strong> 不需要。用 None 方法就能跳过绑卡，全程不需要信用卡。</p> <p><strong>Q: 余额不够时怎么办？</strong> App Store 会自动尝试续费。如果余额不足，App Store 会发邮件/弹窗提示 “你的订阅即将过期，请充值”。再买一张礼品卡兑换即可。</p> <p><strong>Q: 账号被封后订阅怎么办？</strong> 在 iPhone → 设置 → 你的头像 → 订阅 → Claude → 取消订阅，或直接在 App Store → 账户 → 购买记录 → 报告问题申请退款。Apple 对未消费部分的退款政策相对宽松。</p> <p><strong>Q: Android 能用吗？</strong> 不能。Apple 内购只能在 Apple 设备上完成。可以用朋友的 iPhone 登录一次你的 Claude 账号订阅，之后在其他平台上继续使用。</p> <p><strong>Q: 能不能只用一个月的 Apple 内购，到期后用回 Web 订阅？</strong> 可以。Claude 订阅状态是跨平台同步的——不管从哪里订阅，Pro 状态绑定在你的 Claude 账号上。在 App Store 取消后，到期日再去 Web 重新订阅即可。</p> <hr /> <blockquote> <p><strong>结论</strong>：Apple 礼品卡内购 = 绕过卡片风控 + 可能 85-9 折 + Apple 退款保护。对国内用户来说这是最稳的支付方案，省钱是附带的。</p> </blockquote>

用 Apple 礼品卡走 iOS 内购订阅 Claude Pro 的完整流程：为什么走这条路（绕开发卡归属地校验）、礼品卡获取与兑换、Apple ID 区域配置、订阅续费与坑点整理。