<?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>系统扫描 Skill 诞生记 on 吕炘嵘的博客</title>
    <link>https://blog.lvxinrong.com/scan-skill/</link>
    <description>Recent content in 系统扫描 Skill 诞生记 on 吕炘嵘的博客</description>
    <image>
      <title>吕炘嵘的博客</title>
      <url>https://blog.lvxinrong.com/og-default.jpg</url>
      
      <link>https://blog.lvxinrong.com/scan-skill/</link>
    </image>
    <generator>Hugo</generator>
    <language>zh-CN</language>
    <lastBuildDate>Thu, 15 Oct 2026 19:10:00 +0800</lastBuildDate>
    <atom:link href="https://blog.lvxinrong.com/scan-skill/index.xml" rel="self" type="application/rss+xml" />
    <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>
  </channel>
</rss>
