<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>工程化 on 吕炘嵘的博客</title>
    <link>https://blog.lvxinrong.com/tags/%E5%B7%A5%E7%A8%8B%E5%8C%96/</link>
    <description>Recent content in 工程化 on 吕炘嵘的博客</description>
    <image>
      <title>吕炘嵘的博客</title>
      <url>https://blog.lvxinrong.com/og-default.jpg</url>
      
      <link>https://blog.lvxinrong.com/tags/%E5%B7%A5%E7%A8%8B%E5%8C%96/</link>
    </image>
    <generator>Hugo</generator>
    <language>zh-CN</language>
    <lastBuildDate>Mon, 26 Oct 2026 12:00:00 +0800</lastBuildDate>
    <atom:link href="https://blog.lvxinrong.com/tags/%E5%B7%A5%E7%A8%8B%E5%8C%96/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>手搓 LLM 笔记 08：重写 lvllm，按工程结构再串一遍</title>
      <link>https://blog.lvxinrong.com/llm/llm-08-rewrite-lvllm/</link>
      <pubDate>Mon, 26 Oct 2026 12:00:00 +0800</pubDate>
      <guid>https://blog.lvxinrong.com/llm/llm-08-rewrite-lvllm/</guid>
      <description>终极回炉：不按章节收拢，按工程结构重写全书代码。data 三任务、train 分工、LoRA 接线、eval 评委链，最后用 23.6 vs 23.9 的回归收官。</description>
      <content:encoded><![CDATA[<blockquote>
<p>施工图是 <a href="https://blog.lvxinrong.com/nanochat/lvchat-roadmap/">lvchat 实现导图</a> 的 M0。10 月 20 日立项，10 月 26 日回归通过，本篇为收官正文。原始踩坑记录保留在文末「素材积累」。</p>
</blockquote>
<h2 id="为什么重写">为什么重写</h2>
<p>书读完的时候，我手里有一整个仓库的代码，但它们是按章节长的：ch03 一份、ch05 一份、ch07 一份，互相复制，配置散落，device 满天飞。能跑，但不是工程。</p>
<p>更关键的问题：这些代码是“跟着书写出来的”，合上书，我能不能按自己的结构重新组织一遍？这就是 M0 的由来——<strong>不按章节收拢，按工程结构重写</strong>。目标不是拥有一个新的仓库，是拥有“能写出这个仓库”的能力。</p>
<p>新仓库叫 squid-llms。军规两条：能手写就手写，AI 只当导航；每一处偏离书的设计，都要说得出理由。</p>
<h2 id="最后的结构">最后的结构</h2>
<pre tabindex="0"><code>src/squid/
├── config.py        # 单一配置入口
├── device.py        # 单一 device 入口
├── tokenizer/       # SquidTokenizer 协议 + tiktoken 实现
├── model/           # layers / gpt / lora
├── data/            # pretrain / classify / instruct + common
├── train/           # common / pretrain / classify / sft
├── generate/        # 纯 id 引擎 + 文本壳
├── eval/            # 批量生成 + DeepSeek 评委
└── checkpoints/     # 进口 / 自用 / 附加 三层
</code></pre><p>两个“单一入口”是最先定的：配置和 device 只有一个出处。后面所有层都不许自己造词表知识、自己判断设备——比如 pad_id 一律从 <code>tokenizer.eos_id</code> 进，不许写死 50256（GPT-2 ≠ Qwen，07-2 已经踩过）。</p>
<h2 id="data按任务分不按格式分">data：按任务分，不按格式分</h2>
<p>三种任务的数据组织方式根本不同，所以分三个文件：</p>
<ul>
<li><strong>pretrain</strong>：定长滑窗。<code>input = ids[i:i+max_len]</code>，<code>target = ids[i+1:i+max_len+1]</code>，+1 偏移在 dataset 里做完，默认 collate 直接 stack。stride 是“窗口每次滑动的步长”不是窗口大小，取 max_length 一半就是 50% 重叠，抗上下文割裂。</li>
<li><strong>classify</strong>：变长文本 + 类别标签。pad 到 <strong>batch 内最长</strong>，所以 pad 必须在 collate——dataset 阶段看不到邻居，不知道要补多长。书里是补到全集最长，一条离群长文会让所有短文本陪着补，这里有意改掉了。</li>
<li><strong>instruct</strong>：最重的一条流水线，五步手术：</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">full</span> <span class="o">=</span> <span class="n">prompt_ids</span> <span class="o">+</span> <span class="n">response_ids</span> <span class="o">+</span> <span class="p">[</span><span class="n">eos_id</span><span class="p">]</span>   <span class="c1"># 1. 追加 EOS</span>
</span></span><span class="line"><span class="cl"><span class="n">padded</span> <span class="o">=</span> <span class="n">pad_to_length</span><span class="p">(</span><span class="n">full</span><span class="p">,</span> <span class="n">max_len</span><span class="p">,</span> <span class="n">eos_id</span><span class="p">)</span> <span class="c1"># 2. pad 到 batch 最长</span>
</span></span><span class="line"><span class="cl"><span class="n">inputs</span>  <span class="o">=</span> <span class="n">padded</span><span class="p">[:</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>                         <span class="c1"># 3. +1 错位</span>
</span></span><span class="line"><span class="cl"><span class="n">targets</span> <span class="o">=</span> <span class="n">padded</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span><span class="o">.</span><span class="n">clone</span><span class="p">()</span>                  <span class="c1">#    （clone：切片是视图）</span>
</span></span><span class="line"><span class="cl"><span class="n">targets</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">prompt_ids</span><span class="p">)</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="mi">100</span>          <span class="c1"># 4. prompt 位不计分</span>
</span></span><span class="line"><span class="cl"><span class="n">targets</span><span class="p">[</span><span class="n">eos_pos</span><span class="p">[</span><span class="mi">1</span><span class="p">:]]</span> <span class="o">=</span> <span class="o">-</span><span class="mi">100</span>                   <span class="c1"># 5. 除第一个 EOS 外全遮</span>
</span></span></code></pre></div><p>掩码要分两笔账记：<strong>pad 掩码是卫生</strong>（不做就污染 loss），<strong>prompt 掩码是战术</strong>（只做指令跟随时用）。一句话版：prompt 是考场，response 是答卷，遮盖是“不计分”，不是“拆考场”——模型始终看得到完整 prompt，只是不为它的预测打分。</p>
<p>还有三个对齐可以当口诀：<strong>pad 对齐形状，+1 对齐时间，-100 对齐计分范围。</strong></p>
<h2 id="traincommon-提供能力循环决定节奏">train：common 提供能力，循环决定节奏</h2>
<p>三个训练循环 80% 相同，所以公共件沉到 common（loss 三件套、评估、LR 调度），任务文件只留差异。</p>
<p>最大的一个认知点是 <code>cross_entropy</code> 的契约：logits <code>(N, C)</code>、targets <code>(N,)</code>，<strong>N 是预测点个数</strong>。pretrain/SFT 每个位置都预测，N=B×T，所以要 <code>logits.flatten(0, 1)</code>；classify 只在最后一个位置预测，<code>logits[:, -1, :]</code> 出来就是 (B, C)，天然对齐，不需要 flatten。所以 classify 有自己的 <code>calc_loss_batch</code>，同名不同身，各放各家，不搞参数开关。</p>
<p>第二条是<strong>函数自足</strong>：<code>calc_loss_loader</code> 自己包 <code>no_grad</code>，不依赖调用方记得规矩（Java 直觉的胜利）。但反过来，训练用的 <code>calc_loss_batch</code> 绝不能包 no_grad——我包过一次，backward 直接没有梯度可回传。</p>
<p>第三条是 <strong>prepare 归调用前，循环归循环</strong>。换分类头、冻结、包 LoRA 都是训练前的模型手术，训练循环闭着眼跑，给它什么模型它训什么。</p>
<p><code>lr_at_step</code> 抽成纯函数的理由只有两个字：<strong>可测</strong>。warmup 公式出过一次 bug（多乘了 total_steps），抽出来之后三个锚点断言（起点 initial_lr、warmup 顶点 peak_lr、终点 min_lr）三秒钟验尸。如果不写测试，抽它就没有意义。</p>
<h2 id="lora手术合并存档">LoRA：手术、合并、存档</h2>
<p>给模型换 LoRA 层的递归手术有个必须记住的招式：<strong><code>named_modules</code> 用来遍历，<code>named_children</code> 用来手术</strong>。替换要拿“爹”的句柄才能 <code>setattr</code>，而 named_modules 会 yield 模块自身，拿它递归就是原地套娃——我用 RecursionError 实测过。</p>
<p>另外两条硬规矩：</p>
<ul>
<li>forward 和 merge 的缩放必须同一把尺：都是 <code>α/r</code>（论文原版）。书里只用 α，换 rank 时两种写法的强度差一个 1/r，对比实验时别混。</li>
<li>生命周期：<strong>训练并联省显存，部署 merge 省计算</strong>。<code>merged_weight()</code> 把 ΔW 折回主权重，之后保存的就是普通 GPT 的 state_dict，加载方不需要知道 LoRA 存在过。存档因此有两条路线：adapter 小而专用（保留继续训练的灵活），merged 大而通用（部署零开销）。</li>
</ul>
<h2 id="eval生成和打分分开烧">eval：生成和打分分开烧</h2>
<p><code>generate/</code> 是生成能力，<code>eval/generate.py</code> 是测试集传送带：格式化 prompt（与训练同模板）→ 调 generate_text → 裁掉 prompt → 落盘 json。<code>eval/judge.py</code> 拿这个 json 去请 DeepSeek 打分。拆开的原因很实际：生成烧 GPU，打分烧 API 额度，两边失败重跑的成本完全不同。</p>
<p>judge 这边几个工程决定：API key 走 <code>.env</code> / 环境变量（不进 git）；有 score 的条目跳过，断点续跑不重复烧额度；每 10 条落盘一次；统计（均值、分位、直方图）抽成独立函数。</p>
<h2 id="回归236-vs-239">回归：23.6 vs 23.9</h2>
<p>M0 的收官动作：拿旧仓库训练好的 LoRA 权重（355M，rank=16 alpha=16，4 epoch 那版），squid 负责加载、生成、打分，和旧仓库同权重基线对比。同权重是为了隔离变量——差异只剩管线本身。</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th></th>
        <th>squid 回归</th>
        <th>旧仓库基线</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>均分</td>
        <td><strong>23.6</strong></td>
        <td>23.9</td>
      </tr>
      <tr>
        <td>0 分条数</td>
        <td>73</td>
        <td>70</td>
      </tr>
      <tr>
        <td>81-100 分条数</td>
        <td>18</td>
        <td>19</td>
      </tr>
    </tbody>
  </table>
</div>
<p>均分差 0.3，分布形态一致，在评委噪声范围内。加上 13 个单元测试全绿，M0 验收通过。</p>
<p>另一个好用的 sanity check 记在这：<strong>初始 loss ≈ ln(vocab_size)</strong>。50257 词表随机猜的 baseline 是 10.83，训练起点贴着它才正常，之后掉得动才说明学习是真的。</p>
<h2 id="这一遍重写我练到的是什么">这一遍重写，我练到的是什么</h2>
<p>代码只是产出之一，更重要的是三条工作法：</p>
<ol>
<li><strong>手写优先，AI 当导航。</strong> AI 五分钟能写完整个仓库，但那是 AI 写的。collate 那几个坑（list 思维切 tensor、视图污染、BPE 接缝），只有亲手踩过才算学分。纯机械的搬运可以交给 AI，概念密集的地方必须手写。</li>
<li><strong>验收标准是“每行能讲清楚”，不是“脱稿默写”。</strong> 看懂和写出之间隔着正常的鸿沟，读是再认，写是回忆。第二遍学习，读流畅、写磕绊就是这个阶段的样子。</li>
<li><strong>错处入笔记。</strong> 每天的翻车现场当天记进素材库（见文末），写正文的时候全成了弹药。</li>
</ol>
<p>下一步是 M1：自己训一个 BPE tokenizer，不调用 tiktoken，配套读 diy-llm 第 2 章。作品线和理论线从这里开始双轨并行。</p>
<h2 id="素材积累原始记录">素材积累（原始记录）</h2>
<p><strong>Day 1（10-20）</strong>：</p>
<ul>
<li>MHA 重写：骨架对、细节丢四个（多头拆解、√d_k、logits/权重命名、out_proj）；抓到两个致命 bug（<code>foward</code> 拼写、mask 切片错写成 <code>[:T, T:]</code>，正确是 <code>[:T, :T]</code>）</li>
<li>「张量的第一维永远是 batch」幻觉拔除——generate 的一维切法 bug 全源于此</li>
<li>LayerNorm vs BatchNorm：「BatchNorm 统计别人，LayerNorm 只管自己」</li>
<li>pre-norm 的「干净通道」：残差主干恒等直通，warmup 与 pre-norm 是同一问题的两代武器</li>
<li>checkpoints 三层设计：gpt2.py（进口）/ store.py（自用）/ lora.py（附加）；键名映射吸收旧格式</li>
<li>LoRA merge 验收的双重计数坑：merge 是搬家不是复制</li>
<li>竖切终点：355M 权重加载，squid 第一次开口</li>
</ul>
<p><strong>Day 2（10-23）</strong>：</p>
<ul>
<li>data 层按任务分不按格式分：pretrain（定长滑窗，dataset 内偏移）/ classify（collate 补 batch 内最长）/ instruct（掩码五连）</li>
<li>collate 职责钉死：「定长的活 dataset 干，变长的活 collate 干，pad 永远在偏移前面」</li>
<li>instruct collate 五步手术：追加 EOS → pad → +1 错位 → prompt 位 -100 → 除第一个 EOS 外全 -100</li>
<li>掩码两笔账：pad 掩码是卫生（必做），prompt 掩码是战术（看目标）；「prompt 是考场，response 是答卷，遮盖是不计分不是拆考场」</li>
<li>pad_id 不许写死 50256：词表知识只从 tokenizer.eos_id 一个口进（GPT-2 ≠ Qwen，07-2 的前科）</li>
<li>list 思维切 tensor 三坑：tensor 没有 .index、切片是视图要 clone、标量广播代替 list 赋值</li>
<li>cross_entropy 契约 (N,C)+(N,)：N=预测点数。pretrain 要 flatten（N=B×T），classify 取 last-token 天然对齐（N=B）——同名不同身，各放各家</li>
<li>函数自足原则：no_grad 内收进 calc_loss_loader，不依赖调用方记得规矩（Java 直觉的胜利）；但训练用 loss 函数绝不能包 no_grad</li>
<li>训练层分工：common 提供能力，循环决定节奏；prepare（模型手术）归调用前，循环闭着眼跑</li>
<li>lr_at_step 抽纯函数的意义 = 可测性：给出过 bug 的 warmup 公式配三锚点断言当验尸官</li>
<li>named_modules 遍历、named_children 手术：替换要拿爹的句柄；named_modules 会 yield 自身，递归即套娃（RecursionError 实锤）</li>
<li>LoRA：α/r 缩放 forward 与 merge 必须同尺；merged_weight 生命周期 = 训练并联省显存 → 部署 merge 省计算；存档两路线（adapter 小而专用 / merged 大而通用）</li>
<li>sanity check：初始 loss ≈ ln(vocab_size)，一眼辨训练真假</li>
<li>stride 语义钉死：窗口滑动的步长，不是窗口大小；stride=max_length/2 → 50% 重叠抗上下文割裂</li>
<li>Kimi 翻车帧：出考题忘了等长样本没有 pad 路径；「我的时间来自对话时间戳，不是真的钟」</li>
</ul>
]]></content:encoded>
    </item>
    <item>
      <title>系统扫描 Skill 深解：把「尽量遵守」变成「可校验」</title>
      <link>https://blog.lvxinrong.com/scan-skill/introduction/</link>
      <pubDate>Thu, 15 Oct 2026 19:10:00 +0800</pubDate>
      <guid>https://blog.lvxinrong.com/scan-skill/introduction/</guid>
      <description>72 个子系统，人工摸排不可能。于是我把「看懂一个系统」写成了一套协议：固定句式防误触、机器门禁代替自我声明、断言强度分级防止幻觉、任务快照隔离上下文。本文直接读源码。</description>
      <content:encoded><![CDATA[<p>接手一家新公司，摆在我面前的是 <strong>72 个子系统</strong>。</p>
<p>后端、前端、Android、iOS、小程序，全在里面。老板要我评估系统现状，给出重构建议。如果靠人工摸排——翻代码、问人、画架构图——一个月也摸不出一个可信的全貌。而我又必须在一周一次的周会上，持续给出有依据的判断。</p>
<p>于是有了这套系统扫描 Skill。它的目标不是「让 AI 帮我看代码」，而是回答一个更难的问题：</p>
<blockquote>
<p><strong>AI 生成的系统分析，凭什么可信？</strong></p>
</blockquote>
<p>AI 看代码最大的风险不是看不懂，是<strong>看得太像懂了</strong>。它会把「目录里有个 client 包」写成「生产调用了某系统」，把「我还没查」写成「不存在」，把一份自己刚写完的文档宣布为「已完成」。所以这套 Skill 的全部设计，都在解决同一件事：<strong>让结论可复核，而不是让输出更好看。</strong></p>
<p>核心原则就一句话：</p>
<blockquote>
<p><strong>系统级定世界观，项目级定工程画像；模块专题横向看能力，代码链路纵向追执行。</strong></p>
</blockquote>
<pre tabindex="0"><code>系统级（先修事实底座）
   │  主 Agent 单写，统一术语、仲裁冲突
   ▼
项目级（每个项目一个独立 subagent）
   │  工程画像 + 契约校验，过了门禁才能深入
   ├─→ 项目内部地图（可选导航）
   ├─→ 模块专题（横向：一组能力怎么实现）
   └─→ 代码链路（纵向：一个接口/异常怎么跑）
</code></pre><p>这篇直接读源码，看这套协议是怎么把「尽量遵守」变成「可校验」的。</p>
<h2 id="一固定句式故意不给意图识别">一、固定句式：故意不给「意图识别」</h2>
<p>做这套 Skill 时，很多 AI 劝我：触发方式应该做意图识别，用户说「帮我看看系统」就能启动。我全部拒绝了——<strong>这套 Skill 只认固定句式，没有极简触发</strong>：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>层级</th>
        <th>唯一合法句式</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>系统级</td>
        <td><code>使用 wantwant-project-scan 做系统级分析</code></td>
      </tr>
      <tr>
        <td>项目级</td>
        <td><code>使用 wantwant-project-scan 做项目级分析，分析一下 &lt;项目目录名&gt;</code></td>
      </tr>
      <tr>
        <td>全部项目并行</td>
        <td><code>使用 wantwant-project-scan 做全部项目级并行分析</code></td>
      </tr>
      <tr>
        <td>模块专题</td>
        <td><code>使用 wantwant-project-scan 做模块级分析，分析一下 &lt;项目目录名&gt; 的 &lt;模块名&gt;</code></td>
      </tr>
      <tr>
        <td>代码链路</td>
        <td><code>使用 wantwant-project-scan 做代码级分析，分析一下 &lt;项目目录名&gt; 的 &lt;链路或问题&gt;</code></td>
      </tr>
    </tbody>
  </table>
</div>
<p>为什么故意反人性化？因为<strong>它已经脱离了「提示词」的范畴</strong>：一次全量扫描要跑几个小时、烧掉可观的 token，涉及几十个仓库的索引和上百份文档。如果用户随口一句「帮我看看这个项目」就启动，等于给一台重型机器装了一个头发丝开关。</p>
<p><strong>固定句式就是成本闸门</strong>：用户必须明确知道自己在启动什么、愿意为它付费。轻量的生产排查 Skill 我就用了意图识别——重的用固定句式，轻的用意图识别，<strong>触发方式是成本设计，不是交互设计</strong>。</p>
<h2 id="二门禁不许模型自己宣布已完成">二、门禁：不许模型自己宣布「已完成」</h2>
<p>AI 有个根深蒂固的毛病：活干到八成，就宣布「完成了」。如果你只要求它「完成后说一声」，它会给你一份格式漂亮的半成品。</p>
<p>所以这套 Skill 的第一条硬规则就是：</p>
<blockquote>
<p><strong>不要通过搜索裸 <code>完成状态：已完成</code> 放行。</strong></p>
</blockquote>
<p>「完成」不能是模型的一句话，必须是<strong>机器可判定的四个独立字段</strong>：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>契约字段</th>
        <th>回答的问题</th>
        <th>可选值（示例）</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>文档状态</td>
        <td>模板和必填事实全不全</td>
        <td><code>完整 / 草稿</code></td>
      </tr>
      <tr>
        <td>证据状态</td>
        <td>结论的可信边界到哪</td>
        <td><code>运行态已确认 / 源码视角已完成，运行态待确认 / …</code></td>
      </tr>
      <tr>
        <td>下层门禁</td>
        <td>能不能进入下一层</td>
        <td><code>READY / BLOCKED</code></td>
      </tr>
      <tr>
        <td>校验状态</td>
        <td>机器校验过没过</td>
        <td><code>PASSED / FAILED / NOT_RUN / NOT_APPLICABLE</code></td>
      </tr>
    </tbody>
  </table>
</div>
<p>注意这里有一个反直觉的设计：<strong>「证据状态」和「下层门禁」是分开的</strong>。一份报告即使「运行态待确认」（没有生产环境材料），只要源码分析完整、契约校验通过，照样可以 <code>下层门禁=READY</code>——<strong>可信度不够，不等于不许深入</strong>；但如果文档不完整或校验失败，就是不能走。四个维度各管各的，谁也不能顶替谁。</p>
<p>而「能不能进下一层」的判定，不交给模型自己读状态表，而是交给一个 58 行的脚本：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># scripts/check_layer_gate.py（节选）</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">evaluate</span><span class="p">(</span><span class="n">transition</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">document</span><span class="p">:</span> <span class="n">Path</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">    <span class="n">contract</span> <span class="o">=</span> <span class="n">load_contract</span><span class="p">(</span><span class="s2">&#34;layer-state-machine-v1.json&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">rule</span> <span class="o">=</span> <span class="n">contract</span><span class="p">[</span><span class="s2">&#34;transitions&#34;</span><span class="p">][</span><span class="n">transition</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">    <span class="n">text</span> <span class="o">=</span> <span class="n">document</span><span class="o">.</span><span class="n">read_text</span><span class="p">(</span><span class="n">encoding</span><span class="o">=</span><span class="s2">&#34;utf-8&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">values</span> <span class="o">=</span> <span class="n">metadata_values</span><span class="p">(</span><span class="n">text</span><span class="p">,</span> <span class="nb">list</span><span class="p">(</span><span class="n">FIELD_MAP</span><span class="o">.</span><span class="n">values</span><span class="p">()))</span>
</span></span><span class="line"><span class="cl">    <span class="n">failures</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">machine_field</span><span class="p">,</span> <span class="n">allowed</span> <span class="ow">in</span> <span class="n">rule</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="n">label</span> <span class="o">=</span> <span class="n">FIELD_MAP</span><span class="p">[</span><span class="n">machine_field</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">        <span class="n">value</span> <span class="o">=</span> <span class="n">values</span><span class="p">[</span><span class="n">label</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">value</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">allowed</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="n">failures</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="n">label</span><span class="si">}</span><span class="s2">=</span><span class="si">{</span><span class="n">value</span> <span class="ow">or</span> <span class="s1">&#39;MISSING&#39;</span><span class="si">}</span><span class="s2">; allowed=</span><span class="si">{</span><span class="s1">&#39;,&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">allowed</span><span class="p">)</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">failures</span>
</span></span></code></pre></div><p>逻辑简单到「原始」：读契约 → 取字段 → 比对允许值 → 有违例就 <code>BLOCKED</code>。<strong>但它把「放行」从模型的自我感觉，变成了一次确定性的机器检查。</strong> 对应的契约是版本化的 JSON，白纸黑字：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="s2">&#34;system_to_project&#34;</span><span class="err">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;protocol_version&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;wantwant-project-scan/system-doc/v1&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;document_status&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;完整&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;downstream_gate&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;READY&#34;</span><span class="p">],</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;validation_status&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;PASSED&#34;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></div><p>这就是整套 Skill 的骨架：<strong>模型负责生产内容，契约负责定义什么叫合格，脚本负责判决。</strong></p>
<h2 id="三证据纪律先给断言分级再给措辞上锁">三、证据纪律：先给断言分级，再给措辞上锁</h2>
<p>AI 分析系统最危险的动作，是把「源码里存在」说成「生产里运行」。这套 Skill 把这件事拆成了两套正交的字段，然后给每级措辞上了锁：</p>
<p><strong>证据强度分四级</strong>：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>断言强度</th>
        <th>允许措辞</th>
        <th>最低证据要求</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>运行态已确认</td>
        <td><code>生产运行已确认</code></td>
        <td>注册中心、部署清单、运行日志、监控、人工确认</td>
      </tr>
      <tr>
        <td>源码视角确认</td>
        <td><code>源码中存在</code>、<code>具备该能力</code></td>
        <td>构建文件、配置、注解、接口定义、代码调用</td>
      </tr>
      <tr>
        <td>技术推测</td>
        <td><code>推测</code>、<code>疑似</code>、<code>待确认</code></td>
        <td>包名、类名、依赖名等单一弱信号</td>
      </tr>
      <tr>
        <td>当前未发现</td>
        <td><code>当前未发现稳定证据</code></td>
        <td>已按范围查找，但没有稳定证据</td>
      </tr>
    </tbody>
  </table>
</div>
<p><strong>高风险断言默认降级</strong>：<code>生产启用</code>、<code>全部配置</code>、<code>所有入口</code>、<code>完整链路</code>、<code>实际调用</code>、<code>已完成</code>——没有运行态材料或人工确认，一个都不许写。改写示例直接进了规范：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>不推荐</th>
        <th>推荐</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>所有配置通过 Nacos 下发</td>
        <td>当前源码未包含本地配置；结合 Nacos 依赖，<strong>推测</strong>配置主要由 Nacos 或部署环境注入，<strong>运行态待确认</strong></td>
      </tr>
      <tr>
        <td>生产使用 MySQL + Redis + MQ</td>
        <td>源码存在 MySQL/Redis/MQ 依赖或配置，<strong>生产使用待运行态确认</strong></td>
      </tr>
      <tr>
        <td>调用 sfa-base</td>
        <td>源码存在 client/依赖，<strong>具备调用能力，实际流量待确认</strong></td>
      </tr>
      <tr>
        <td>完整调用链如下</td>
        <td><strong>核心调用链候选</strong>如下，待代码级 trace 确认</td>
      </tr>
    </tbody>
  </table>
</div>
<p>注意最后一条：连「调用链」都要降级成「候选」，除非你做了代码级 trace。<strong>这套措辞规范防的不是 AI 说错话，是防「听起来很对」</strong>——外行看不出区别，但每一份报告的使用者都不会被过度断言误导。</p>
<p>还有两条配套纪律：</p>
<ul>
<li><strong>冲突不许抹平</strong>：工具之间结论冲突时，写 <code>冲突待复核</code> 并列出冲突来源，不许自动合并成单一事实；下层发现与上层冲突，回传上层文档，<strong>不要静默改写上层世界观</strong></li>
<li><strong>证据分优先级</strong>：运行态材料 &gt; 人工确认 &gt; 部署发布材料 &gt; 代码图谱 &gt; 源码 &gt; 历史文档；历史文档必须标日期，日期不明写 <code>待确认</code></li>
</ul>
<p>「没查到」和「不存在」是两回事，「源码里有」和「生产在用」是两回事——<strong>AI 分不清，就用契约替它分清</strong>。</p>
<h2 id="四多-agent单写者隔离不可变任务信封">四、多 Agent：单写者、隔离、不可变任务信封</h2>
<p>72 个项目，不可能在一个上下文里跑完：会串味、会超限、会互相污染。这套 Skill 的协作设计有三条硬规则。</p>
<p><strong>主 Agent 单写者。</strong> 系统级世界观只能由主 Agent 写——子 Agent 可以并行采集原始证据，但<strong>术语统一、冲突仲裁、最终写入只能一个人干</strong>。否则十个 worker 写出十套术语，世界观就散了。</p>
<p><strong>上下文硬隔离。</strong> 每个项目的项目级分析，都在独立的 child session 里执行，任务信封由脚本统一生成：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">./scripts/build-project-task.sh &lt;当前根目录&gt; &lt;项目目录名&gt; &lt;MCP project&gt;
</span></span></code></pre></div><p>规范里写死了不许带什么：</p>
<blockquote>
<p>禁止把其他项目源码、报告、child session 输出或历史总结传入 worker。</p>
</blockquote>
<p><strong>每个 worker 只看自己的项目 + 系统级事实底座</strong>，谁也别想看别人的答案。并行结果合并时，只合并状态、输出路径、校验结果和冲突计数——<strong>合的是账，不是内容</strong>。</p>
<p><strong>不可变任务快照。</strong> 批量模式下，任务不是一句 prompt 甩过去的，而是先冻结成不可变计划：批次计划、运行状态、任务快照都落在 <code>project-batches/&lt;run-id&gt;/</code> 目录里，<strong>Task prompt 里只有快照路径、SHA-256 和任务 ID</strong>。worker 先校验引用，再读快照——prompt 短了，意图无法被中途改写，跑到一半断了还能按 run-id 续跑。默认并发度 4 的滑动窗口，防止几十个任务一起把机器打爆。</p>
<p>这些规则和「提示词写得好不好」已经没关系了，<strong>这是分布式系统的工程纪律搬到了 Agent 编排上</strong>。</p>
<h2 id="五交付校验不过不算完成">五、交付：校验不过，不算完成</h2>
<p>扫描的产物全部落在统一目录，不散写进业务工程：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">wantwant_scan_docs/
</span></span><span class="line"><span class="cl">├── system/00-系统级事实底座.md
</span></span><span class="line"><span class="cl">├── portal/index.html          ← 零依赖静态系统门户
</span></span><span class="line"><span class="cl">└── projects/&lt;项目目录名&gt;/
</span></span><span class="line"><span class="cl">    ├── &lt;项目目录名&gt;.md
</span></span><span class="line"><span class="cl">    ├── internal-map/project-internal-map.md
</span></span><span class="line"><span class="cl">    ├── module-analysis/modules/&lt;模块名&gt;/模块级说明.md
</span></span><span class="line"><span class="cl">    └── code/&lt;链路名&gt;/代码级链路.md
</span></span></code></pre></div><p><strong>文档写完不算完，校验通过才算完。</strong> 项目级文档必须过 <code>validate-project-docs.sh</code>——校验器以 <code>contracts/project-doc-v1.json</code> 为唯一契约，检查标题、章节顺序、重复或额外章节、机器状态、统计口径、证据引用和敏感值。模板的顶级章节和必填二级章节是<strong>固定输出契约</strong>：不得删除、改名、重排、新增；缺证据的项保留原文，写 <code>不适用</code>、<code>当前未发现稳定证据</code> 或 <code>待确认</code>。</p>
<p>注意最后这句：<strong>缺证据也得保留章节并如实标注</strong>。这和生产排查 Skill 的「未确认是合法答案」是同一个灵魂——<strong>模板允许空着，但不许撒谎</strong>。</p>
<p>全部项目收口后，<code>generate_architecture_portal.py</code> 生成一个<strong>零依赖的静态系统门户</strong>：类似 Draw.io 的单张画布，按后端、前端、客户端、小程序分区，每个项目一个可点击节点，点进去是技术栈、入口、依赖、风险和原始报告。72 个系统的全貌，从「没人说得清」变成「一张图」。</p>
<h2 id="六这套-skill-真正想证明的事">六、这套 Skill 真正想证明的事</h2>
<p>很多人问我，这套东西和「帮我分析一下这个项目」的 prompt 有什么区别。区别不在结果，在<strong>能不能被人复核</strong>：</p>
<ul>
<li>触发有成本闸门，不会误启动</li>
<li>完成有机器门禁，不是模型自报</li>
<li>措辞有证据分级，不靠语感</li>
<li>上下文有硬隔离，不会串味</li>
<li>文档有契约校验，不靠自觉</li>
</ul>
<p>一个 prompt 也能生成漂亮的系统分析，<strong>但你无法知道哪句是事实、哪句是想象</strong>。这套 Skill 做的，就是把「事实、推断、待确认」焊死在每一个交付物里——和生产排查 Skill 是同一个哲学：</p>
<blockquote>
<p><strong>过程交给 AI，验收交给契约。</strong></p>
</blockquote>
<p>系统会越来越复杂，人不会越来越多。接手系统的尽头，不是更多的「老员工讲给你听」，而是<strong>一套能复核、能交接、能重跑的事实底座</strong>。</p>
<hr>
<blockquote>
<p>系列说明：本文是「系统扫描 Skill 诞生记」系列导读。后续章节会逐篇展开：分层模型为什么这样切、不同类型工程的画像怎么做、契约校验器怎么写、多 Agent 协作的血泪史，以及一次完整的 72 系统扫描回放。</p>
</blockquote>
]]></content:encoded>
    </item>
    <item>
      <title>生产排查 Skill 深解：不教 AI 排查，只给它现场和纪律</title>
      <link>https://blog.lvxinrong.com/incident-skill/introduction/</link>
      <pubDate>Thu, 15 Oct 2026 18:30:00 +0800</pubDate>
      <guid>https://blog.lvxinrong.com/incident-skill/introduction/</guid>
      <description>这套 Skill 里没有一句话教 AI 怎么排查生产问题。本文直接读源码：11 个脚本如何把「环境就绪」做成门禁，白名单如何把「只读」做成结构，210 行输出规范如何把「不许糊弄」写成清单。</description>
      <content:encoded><![CDATA[<p>这套 Skill 有 187 行指令、11 个脚本、4 份规范文档。翻遍整个仓库，<strong>你不会找到一句话教 AI「怎么排查生产问题」</strong>——没有「第一步查日志、第二步看监控」，没有根因树，没有决策表。</p>
<p>它只有三样东西：<strong>现场、边界、验收</strong>。这篇不谈理念，直接读源码，看这三样东西是怎么长成的。</p>
<pre tabindex="0"><code>                 一起事故进来
                      │
        ┌─────────────┴─────────────┐
        │  ① 环境就绪：门禁不通过，不许开查  │
        │  check-environment.sh 状态机     │
        │  源码新鲜度 await-freshness.sh  │
        └─────────────┬─────────────┘
                      ▼
        ┌─────────────────────────┐
        │  ② 过程自由：AI 自己决定怎么查    │
        │  不规定顺序、不规定工具、不规定框架  │
        │  （但所有云端调用必须走只读包装脚本）│
        └─────────────┬───────────┘
                      ▼
        ┌─────────────────────────┐
        │  ③ 输出契约：20 条质量检查      │
        │  incident-analysis-output.md │
        │  结论卡 + 证据链 + 状态分级      │
        └─────────────────────────┘
</code></pre><h2 id="一环境就绪装了和能用是两回事">一、环境就绪：「装了」和「能用」是两回事</h2>
<p>AI 排查失败的头号原因不是模型不行，是现场不行：日志没配、源码是旧的、图谱没索引。而模型面对残缺现场时不会说「我查不了」，它会直接开编。所以 Skill 把环境做成<strong>强制门禁</strong>。</p>
<h3 id="1-一次检查全部状态摆出来">1. 一次检查，全部状态摆出来</h3>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">scripts/check-environment.sh
</span></span></code></pre></div><p>这个脚本不是检查「命令存在」，而是<strong>真的去读一次</strong>：SLS 实际读取、ARMS 实际读取、本地源码同步状态、全部托管仓库的索引状态。最后汇总只有两种结果：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>汇总状态</th>
        <th>含义</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>ENVIRONMENT_CHECK_READY</code></td>
        <td>全部必选能力实际可用，且无刷新进行中</td>
      </tr>
      <tr>
        <td><code>ENVIRONMENT_CHECK_PARTIAL</code></td>
        <td>至少一项未就绪，按状态逐项修复后重查</td>
      </tr>
    </tbody>
  </table>
</div>
<p>关键在于<strong>状态必须分层</strong>，因为「部分就绪」最容易被 AI 说成「一切正常」：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>状态</th>
        <th>真实含义</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>CODEBASE_MEMORY_LOCAL_READY</code></td>
        <td>只是本地程序装好了。<strong>不代表</strong>会话里有 MCP 工具，<strong>不代表</strong>相关仓库有索引</td>
      </tr>
      <tr>
        <td><code>CODEBASE_MEMORY_RESTART_REQUIRED</code></td>
        <td>配置写入了，但当前会话没加载，需要重启 Agent</td>
      </tr>
      <tr>
        <td><code>CODEBASE_MEMORY_READY</code></td>
        <td>全部托管仓库索引存在，<strong>且与当前源码 Commit 一致</strong></td>
      </tr>
      <tr>
        <td><code>SOURCE_REFRESH_IN_PROGRESS</code></td>
        <td>源码正在刷新，<strong>禁止读源码、禁止调图谱</strong></td>
      </tr>
    </tbody>
  </table>
</div>
<p>注意 <code>LOCAL_READY</code> 和 <code>READY</code> 的天壤之别：一个是「装了」，一个是「能用」。所以 SKILL.md 里还有一条硬性规定：</p>
<blockquote>
<p>Shell 脚本无法证明当前 Agent 会话已经加载 MCP 工具。脚本返回 <code>ENVIRONMENT_CHECK_READY</code> 后，<strong>Agent 必须在当前会话调用一次 <code>list_projects</code></strong>；调用不可用时，将最终环境状态覆盖为 <code>CODEBASE_MEMORY_RESTART_REQUIRED</code> 和 <code>ENVIRONMENT_CHECK_PARTIAL</code>，不得声称代码图谱可用。</p>
</blockquote>
<p><strong>环境验证以「真的调了一次」为准，不以「理论上应该有」为准。</strong></p>
<h3 id="2-源码新鲜度一个-marker-文件实现的读写锁">2. 源码新鲜度：一个 marker 文件实现的读写锁</h3>
<p>生产事故最常见的弯路，是拿最新代码分析旧事故。Skill 的对策是「先刷新，再准入」：</p>
<ul>
<li>排查开始：<code>refresh-sources.sh</code> <strong>后台</strong>全量对齐 70 多个仓库和图谱索引，不阻塞其他证据收集，同时写入 <code>source-refresh-in-progress</code> 标记文件</li>
<li>读取源码前：必须过 <code>await-freshness.sh</code> 这道门禁，拿到 <code>SOURCE_FRESHNESS_READY</code> 才放行</li>
</ul>
<p>这个门禁脚本不到 100 行，但有一个我很喜欢的细节——<strong>它会识别「刷新进程已经死了、但标记还残留」的僵死状态</strong>：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="k">while</span> <span class="o">[</span> -f <span class="s2">&#34;</span><span class="nv">$MARKER_FILE</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">running_pid</span><span class="o">=</span><span class="s2">&#34;</span><span class="k">$(</span>awk -F <span class="s1">&#39;\t&#39;</span> <span class="s1">&#39;{print $1; exit}&#39;</span> <span class="s2">&#34;</span><span class="nv">$MARKER_FILE</span><span class="s2">&#34;</span><span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -z <span class="s2">&#34;</span><span class="nv">$running_pid</span><span class="s2">&#34;</span> <span class="o">]</span> <span class="o">||</span> ! <span class="nb">kill</span> -0 <span class="s2">&#34;</span><span class="nv">$running_pid</span><span class="s2">&#34;</span> 2&gt;/dev/null<span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        rm -f <span class="s2">&#34;</span><span class="nv">$MARKER_FILE</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="nb">printf</span> <span class="s1">&#39;%s\n&#39;</span> <span class="s1">&#39;SOURCE_REFRESH_STALE: refresh process is gone; rerun scripts/refresh-sources.sh&#39;</span> &gt;<span class="p">&amp;</span><span class="m">2</span>
</span></span><span class="line"><span class="cl">        <span class="nb">exit</span> <span class="m">1</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    sleep <span class="m">2</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span></code></pre></div><p>标记文件里存着刷新进程的 PID，门禁用 <code>kill -0</code> 探活：进程还在就等，进程死了清掉残留标记、报 <code>SOURCE_REFRESH_STALE</code> 要求重跑。<strong>没有数据库、没有消息队列，一个文件加一个 PID，就是一套可读写的状态机。</strong></p>
<p>刷新完成后，各仓库当时的 <strong>HEAD Commit 就是本次排查的源码基线</strong>，排查期间不再二次刷新。报告里每个仓库都要记录精确 Commit；对齐不了事故版本时，必须写：</p>
<blockquote>
<p>当前源码已检查，事故版本尚未确认。</p>
</blockquote>
<p>「我查过源码」和「我查过<strong>那个版本</strong>的源码」，是两份完全不同的证据。</p>
<h2 id="二只读不靠嘱咐靠结构">二、只读：不靠「嘱咐」，靠「结构」</h2>
<p>让 AI 碰生产，我最担心的不是它查得慢，是<strong>它顺手做点什么</strong>。提示词里写「请不要修改生产数据」是一句废话，只读必须长在结构里。</p>
<h3 id="1-最内层拒绝一切环境覆盖">1. 最内层：拒绝一切环境覆盖</h3>
<p>所有云端调用最后都汇聚到 <code>aliyun-prod.sh</code>，它只有 35 行，但每一行都在挡人：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="k">for</span> argument in <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">  <span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$argument</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">    --profile<span class="p">|</span>--profile<span class="o">=</span>*<span class="p">|</span>--mode<span class="p">|</span>--mode<span class="o">=</span>*<span class="p">|</span>--region<span class="p">|</span>--region<span class="o">=</span>* <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="p">|</span>--access-key-id<span class="p">|</span>--access-key-id<span class="o">=</span>*<span class="p">|</span>--access-key-secret<span class="p">|</span>--access-key-secret<span class="o">=</span>*<span class="p">|</span>--sts-token<span class="p">|</span>--sts-token<span class="o">=</span>*<span class="o">)</span>
</span></span><span class="line"><span class="cl">      <span class="nb">printf</span> <span class="s1">&#39;ALIYUN_ENV_INVALID: forbidden production credential override: %s\n&#39;</span> <span class="s2">&#34;</span><span class="nv">$argument</span><span class="s2">&#34;</span> &gt;<span class="p">&amp;</span><span class="m">2</span>
</span></span><span class="line"><span class="cl">      <span class="nb">exit</span> <span class="m">2</span>
</span></span><span class="line"><span class="cl">      <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  <span class="k">esac</span>
</span></span><span class="line"><span class="cl"><span class="k">done</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">ALIBABA_CLOUD_IGNORE_PROFILE</span><span class="o">=</span><span class="s1">&#39;TRUE&#39;</span>
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> aliyun <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span>
</span></span></code></pre></div><p>两层防护：<strong>参数层面</strong>，任何 profile、region、ak/sk、token 的覆盖直接退出；<strong>环境层面</strong>，<code>ALIBABA_CLOUD_IGNORE_PROFILE='TRUE'</code> 让 CLI 彻底忽略本机其他 profile——这台机器上就算还配着别人的高权限账号，也轮不到它上场。Skill 的阿里云配置是独立目录里单独一份，用的是架构专门开的只读账号，<strong>不碰用户日常那把什么都能干的钥匙</strong>。</p>
<h3 id="2-中间层api-白名单">2. 中间层：API 白名单</h3>
<p><code>aliyun-arms.sh</code> 在调用前把 API 名放进 <code>case</code> 里过一遍：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$OPERATION</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">  ListTraceApps<span class="p">|</span>SearchTraceAppByName<span class="p">|</span>SearchTraceAppByPage<span class="p">|</span>SearchTraces<span class="p">|</span>SearchTracesByPage<span class="p">|</span>GetTrace<span class="p">|</span>GetMultipleTrace<span class="p">|</span>GetStack<span class="p">|</span>GetTraceApp<span class="p">|</span>GetAppApiByPage<span class="p">|</span>GetAppJVMConfig<span class="p">|</span>QueryAppTopology<span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">INJECT_REGION</span><span class="o">=</span><span class="s1">&#39;true&#39;</span>
</span></span><span class="line"><span class="cl">    <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  GetTraceAppConfig<span class="p">|</span>QueryMetricByPage<span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">INJECT_REGION</span><span class="o">=</span><span class="s1">&#39;false&#39;</span>
</span></span><span class="line"><span class="cl">    <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  *<span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nb">printf</span> <span class="s1">&#39;ARMS_READ_OPERATION_NOT_ALLOWED: %s\n&#39;</span> <span class="s2">&#34;</span><span class="nv">$OPERATION</span><span class="s2">&#34;</span> &gt;<span class="p">&amp;</span><span class="m">2</span>
</span></span><span class="line"><span class="cl">    <span class="nb">exit</span> <span class="m">2</span>
</span></span><span class="line"><span class="cl">    <span class="p">;;</span>
</span></span><span class="line"><span class="cl"><span class="k">esac</span>
</span></span></code></pre></div><p><strong>不在名单里的 API，根本到不了云端。</strong> ARMS 的写操作、管理操作不是「被警告」，是「不存在」。SLS 那边同理，<code>--project</code>、<code>--endpoint</code> 出现在参数里就直接报错——想临时换个环境查一下？参数层面就不允许。</p>
<p>这就是我说的：<strong>让「只读」成为默认路径，让「能写」成为不存在的路径。</strong></p>
<h3 id="3-数据库fail-closed宁可不查">3. 数据库：fail closed，宁可不查</h3>
<p>数据库是可选能力，闸门最严。<code>dbx-readonly-policy.md</code> 立了三道闸：</p>
<p><strong>工具面</strong>：只许出现 <code>dbx_list_connections</code>、<code>dbx_list_tables</code>、<code>dbx_describe_table</code>、<code>dbx_get_schema_context</code>、<code>dbx_execute_query</code> 这几个查询工具。只要发现任何连接管理、数据修改、DDL、导入导出工具，立即报 <code>DBX_PERMISSION_SCOPE_INVALID</code> 并停止全部 DBX 调用。</p>
<p><strong>SQL 面</strong>：只接受 <code>SELECT</code> / <code>SHOW</code> / <code>DESCRIBE</code> / <code>EXPLAIN</code> 开头的单条语句，其他前缀一律拒绝，禁止 <code>SELECT *</code>，返回最多 100 行，大表先 EXPLAIN，<strong>禁止 <code>EXPLAIN ANALYZE</code></strong>（它会真的执行查询，可能造成负载）。</p>
<p><strong>最硬的一条</strong>：</p>
<blockquote>
<p>Never test permissions by attempting a write, even inside a transaction or rollback.</p>
</blockquote>
<p><strong>不许用「试写一下再回滚」来验证权限</strong>——验证权限这件事本身就可能造成事故。权限不明，就不查；数据库证据没拿到，报告里就写「未纳入」，其他证据继续，但不许把数据库假设写成根因。这就是 fail closed：任何一环存疑，闸门自动落下。</p>
<h2 id="三过程自由为什么不教排查">三、过程自由：为什么不教排查</h2>
<p>刚做这套东西时，我也想过把排查流程写细：先查 SLS，再拉 Trace，再定位服务，再翻代码。真写下去就会发现这条路是死的——<strong>每起事故都是新的</strong>。一次资源耗尽和一次证书失效，证据的位置、查询的顺序完全不同。把流程写死，轻则让 AI 做无用功，重则它在「第一步」找不到证据时，硬编一个答案交差。</p>
<p>所以 SKILL.md 里只有一句原则：</p>
<blockquote>
<p>本 Skill 只提供现场、工具和必要的安全约束。Agent 可以根据具体事故自主决定排查思路、工具组合和证据顺序。</p>
</blockquote>
<p>甚至「不要因为某项工具可用，就强制 Agent 使用该工具」也写进去了——代码图谱好用，但不许为了形式完整强行拿它下结论。<strong>过程自由，契约刚性。</strong></p>
<h2 id="四输出契约210-行规范只干一件事不许糊弄">四、输出契约：210 行规范，只干一件事——不许糊弄</h2>
<p>最后交出来的报告，必须过 <code>incident-analysis-output.md</code>。这份规范是整套 Skill 里我最得意的部分，它不管你怎么查，只管你怎么说。</p>
<h3 id="1-结论状态只有四种没有80-确定">1. 结论状态只有四种，没有「80% 确定」</h3>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>状态</th>
        <th>判定标准</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>已确认</code></td>
        <td>直接证据闭合关键因果链，且无冲突证据</td>
      </tr>
      <tr>
        <td><code>高置信</code></td>
        <td>多个独立证据一致支持，只剩非关键环节未直接验证</td>
      </tr>
      <tr>
        <td><code>待验证</code></td>
        <td>有可检验的假设，关键环节还没证据</td>
      </tr>
      <tr>
        <td><code>证据不足</code></td>
        <td>撑不起可靠判断，或关键数据源不可用</td>
      </tr>
    </tbody>
  </table>
</div>
<p>规范明确禁止「缺乏依据的百分比置信度」——「80% 确定」是把证据缺口包装成数字。还有一条很狠的：<strong>总体状态不得高于最弱的关键环节</strong>。「服务端链路已确认、端到端根因待验证」必须分开写，下游查清不等于整件事查清。</p>
<p>对「死锁、行锁等待、内存溢出」这类机制级判断，只有日志、Trace、监控<strong>直接呈现</strong>该机制时才能标「已确认」；时间顺序和源码语义都吻合但没直接证据，只能是「高置信」。<strong>推测出来的机制，不能享受目击者的待遇。</strong></p>
<h3 id="2-原因分四层不许一个根本原因包打天下">2. 原因分四层，不许一个「根本原因」包打天下</h3>
<p>举个通用例子：用户看到「下单接口大面积超时」。</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>层级</th>
        <th>定义</th>
        <th>例子里分别是什么</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>直接原因</td>
        <td>直接导致告警的系统行为</td>
        <td>数据库连接池耗尽，请求排队超时</td>
      </tr>
      <tr>
        <td>上游触发</td>
        <td>让直接原因成立的条件</td>
        <td>全量分析任务与高峰期业务查询叠加，打满数据库 CPU</td>
      </tr>
      <tr>
        <td>缺陷或放大因素</td>
        <td>没拦住异常的缺陷</td>
        <td>分析库与业务库没有隔离、没有限流降级</td>
      </tr>
      <tr>
        <td>最终根因</td>
        <td>异常最初为什么产生</td>
        <td>待验证：为什么全量任务被安排在业务高峰期？</td>
      </tr>
    </tbody>
  </table>
</div>
<p><strong>保护性校验缺失，不等于异常最初产生的原因。</strong> 没有隔离是「放大因素」，不是「最终根因」——把这两层混写，复盘就会停在「加个限流」而不是「改掉调度」。</p>
<h3 id="3-事故结论卡第一屏就能独立阅读">3. 事故结论卡：第一屏就能独立阅读</h3>
<p>所有阶段性结论和最终报告，都必须先给这张卡：</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gu">## 事故结论
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">-</span> 结论状态：已确认 / 高置信 / 待验证 / 证据不足
</span></span><span class="line"><span class="cl"><span class="k">-</span> 已确认范围：已经闭合的因果链或结论对象
</span></span><span class="line"><span class="cl"><span class="k">-</span> 未确认范围：尚缺证据的关键环节；无则写「无」
</span></span><span class="line"><span class="cl"><span class="k">-</span> 故障应用：
</span></span><span class="line"><span class="cl"><span class="k">-</span> 发生时间：
</span></span><span class="line"><span class="cl"><span class="k">-</span> 用户现象：
</span></span><span class="line"><span class="cl"><span class="k">-</span> 影响范围：已确认范围及其查询窗口/数据源边界；未确认范围
</span></span><span class="line"><span class="cl"><span class="k">-</span> 原因摘要：无法确认时写「未确认」，并给出当前最重要的证据缺口
</span></span><span class="line"><span class="cl"><span class="k">-</span> 故障位置：仓库 / Commit / 文件 / 符号 / 行号；未定位时写「未定位」
</span></span><span class="line"><span class="cl"><span class="k">-</span> 处置状态：未执行 / 处理中 / 已执行
</span></span><span class="line"><span class="cl"><span class="k">-</span> 下一步：只列当前最有价值的验证或处置动作
</span></span></code></pre></div><p>注意两个细节：<strong>「未确认」是合法答案</strong>——模板允许空着，不许编；<strong>「处置状态」只能依据用户或外部系统的明确反馈填写</strong>——AI 不许把「我建议修复」写成「已修复」。</p>
<h3 id="4-证据表事实和判断分开放">4. 证据表：事实和判断分开放</h3>
<p>完整报告里的关键证据表长这样：</p>
<div class="table-scroll" tabindex="0" role="region" aria-label="表格，可横向滚动">
  <table>
    <thead>
      <tr>
        <th>编号</th>
        <th>类型</th>
        <th>来源与定位</th>
        <th>客观事实</th>
        <th>支持的判断</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>E1</td>
        <td>SLS</td>
        <td>Project / Logstore / 时间窗 / traceId</td>
        <td>14:03:21 起连续出现连接超时</td>
        <td>异常起始时间不晚于 14:03</td>
      </tr>
      <tr>
        <td>E2</td>
        <td>源码</td>
        <td>仓库 / Commit / 文件 / 行号</td>
        <td>该接口未设置查询超时上限</td>
        <td>推断：慢查询可无限占用连接</td>
      </tr>
    </tbody>
  </table>
</div>
<p>「客观事实」列只写直接观测，「支持的判断」列写能推出什么。<strong>时间相关性不能写成因果，源码语义不能写成线上事实，用户描述不能写成系统事实。</strong></p>
<p>还有一条几乎是为 AI 复盘量身定制的：<strong>所有否定性、穷尽性判断，都必须带查询边界</strong>。「无其他影响」「未发现异常」「全部正常」——必须附上哪个数据源、哪个应用、哪个时间窗口。<strong>「查询窗口内未检出」不等于「整个生产不存在」。</strong></p>
<h3 id="5-质量检查20-条不许">5. 质量检查：20 条「不许」</h3>
<p>规范最后是一份 checklist，输出前逐条过。随手摘几条：</p>
<ul>
<li>没有把工具调用成功，等同于根因已经确认</li>
<li>没有把「尚未检查」写成「源码未纳入」</li>
<li>没有使用「已自愈」「无残留」「数据正常」等没有当前状态证据的表述</li>
<li>没有把建议描述为已经执行</li>
<li>本地最新源码无法与事故版本对齐时，没有把当前源码行为直接当作线上事实</li>
<li>没有泄露凭据、私钥、Token 或数据库连接密钥</li>
</ul>
<p><strong>它约束的不是能力，是诚实。</strong></p>
<h2 id="五这套-skill-真正固化的是什么">五、这套 Skill 真正固化的是什么</h2>
<p>回到开头：不写排查流程，那这套 Skill 的价值在哪？</p>
<p><strong>它固化的不是方法，是纪律。</strong></p>
<p>方法属于 AI——它比人更会在几十个服务、几千条日志里找关联，固化流程反而是束缚。但纪律必须属于工程：现场不齐不许开查、只读路径不许绕过、没有证据不许下结论、结论不全不许写「已确认」。</p>
<blockquote>
<p><strong>过程自由，环境可复现，权限只读，结论可审计。</strong></p>
</blockquote>
<p>一个 Agent 聪不聪明，决定它排查的上限；这套纪律在不在，决定它排查的下限。<strong>上限给老板看，下限才给生产用。</strong></p>
<hr>
<blockquote>
<p>系列说明：本文是「生产排查 Skill 诞生记」系列导读。后续章节会逐篇展开：四维证据源怎么接、代码图谱怎么建、只读门禁怎么实现、以及一次真实事故的完整排查回放。</p>
</blockquote>
]]></content:encoded>
    </item>
  </channel>
</rss>
