接手一家新公司,摆在我面前的是 72 个子系统。

后端、前端、Android、iOS、小程序,全在里面。老板要我评估系统现状,给出重构建议。如果靠人工摸排——翻代码、问人、画架构图——一个月也摸不出一个可信的全貌。而我又必须在一周一次的周会上,持续给出有依据的判断。

于是有了这套系统扫描 Skill。它的目标不是「让 AI 帮我看代码」,而是回答一个更难的问题:

AI 生成的系统分析,凭什么可信?

AI 看代码最大的风险不是看不懂,是看得太像懂了。它会把「目录里有个 client 包」写成「生产调用了某系统」,把「我还没查」写成「不存在」,把一份自己刚写完的文档宣布为「已完成」。所以这套 Skill 的全部设计,都在解决同一件事:让结论可复核,而不是让输出更好看。

核心原则就一句话:

系统级定世界观,项目级定工程画像;模块专题横向看能力,代码链路纵向追执行。

系统级(先修事实底座)
   │  主 Agent 单写,统一术语、仲裁冲突
   ▼
项目级(每个项目一个独立 subagent)
   │  工程画像 + 契约校验,过了门禁才能深入
   ├─→ 项目内部地图(可选导航)
   ├─→ 模块专题(横向:一组能力怎么实现)
   └─→ 代码链路(纵向:一个接口/异常怎么跑)

这篇直接读源码,看这套协议是怎么把「尽量遵守」变成「可校验」的。

一、固定句式:故意不给「意图识别」

做这套 Skill 时,很多 AI 劝我:触发方式应该做意图识别,用户说「帮我看看系统」就能启动。我全部拒绝了——这套 Skill 只认固定句式,没有极简触发:

层级 唯一合法句式
系统级 使用 wantwant-project-scan 做系统级分析
项目级 使用 wantwant-project-scan 做项目级分析,分析一下 <项目目录名>
全部项目并行 使用 wantwant-project-scan 做全部项目级并行分析
模块专题 使用 wantwant-project-scan 做模块级分析,分析一下 <项目目录名> 的 <模块名>
代码链路 使用 wantwant-project-scan 做代码级分析,分析一下 <项目目录名> 的 <链路或问题>

为什么故意反人性化?因为它已经脱离了「提示词」的范畴:一次全量扫描要跑几个小时、烧掉可观的 token,涉及几十个仓库的索引和上百份文档。如果用户随口一句「帮我看看这个项目」就启动,等于给一台重型机器装了一个头发丝开关。

固定句式就是成本闸门:用户必须明确知道自己在启动什么、愿意为它付费。轻量的生产排查 Skill 我就用了意图识别——重的用固定句式,轻的用意图识别,触发方式是成本设计,不是交互设计。

二、门禁:不许模型自己宣布「已完成」

AI 有个根深蒂固的毛病:活干到八成,就宣布「完成了」。如果你只要求它「完成后说一声」,它会给你一份格式漂亮的半成品。

所以这套 Skill 的第一条硬规则就是:

不要通过搜索裸 完成状态:已完成 放行。

「完成」不能是模型的一句话,必须是机器可判定的四个独立字段:

契约字段 回答的问题 可选值(示例)
文档状态 模板和必填事实全不全 完整 / 草稿
证据状态 结论的可信边界到哪 运行态已确认 / 源码视角已完成,运行态待确认 / …
下层门禁 能不能进入下一层 READY / BLOCKED
校验状态 机器校验过没过 PASSED / FAILED / NOT_RUN / NOT_APPLICABLE

注意这里有一个反直觉的设计:「证据状态」和「下层门禁」是分开的。一份报告即使「运行态待确认」(没有生产环境材料),只要源码分析完整、契约校验通过,照样可以 下层门禁=READY——可信度不够,不等于不许深入;但如果文档不完整或校验失败,就是不能走。四个维度各管各的,谁也不能顶替谁。

而「能不能进下一层」的判定,不交给模型自己读状态表,而是交给一个 58 行的脚本:

# scripts/check_layer_gate.py(节选)
def evaluate(transition: str, document: Path) -> list[str]:
    contract = load_contract("layer-state-machine-v1.json")
    rule = contract["transitions"][transition]
    text = document.read_text(encoding="utf-8")
    values = metadata_values(text, list(FIELD_MAP.values()))
    failures: list[str] = []
    for machine_field, allowed in rule.items():
        label = FIELD_MAP[machine_field]
        value = values[label]
        if value not in allowed:
            failures.append(f"{label}={value or 'MISSING'}; allowed={','.join(allowed)}")
    return failures

逻辑简单到「原始」:读契约 → 取字段 → 比对允许值 → 有违例就 BLOCKED。但它把「放行」从模型的自我感觉,变成了一次确定性的机器检查。 对应的契约是版本化的 JSON,白纸黑字:

"system_to_project": {
  "protocol_version": ["wantwant-project-scan/system-doc/v1"],
  "document_status": ["完整"],
  "downstream_gate": ["READY"],
  "validation_status": ["PASSED"]
}

这就是整套 Skill 的骨架:模型负责生产内容,契约负责定义什么叫合格,脚本负责判决。

三、证据纪律:先给断言分级,再给措辞上锁

AI 分析系统最危险的动作,是把「源码里存在」说成「生产里运行」。这套 Skill 把这件事拆成了两套正交的字段,然后给每级措辞上了锁:

证据强度分四级:

断言强度 允许措辞 最低证据要求
运行态已确认 生产运行已确认 注册中心、部署清单、运行日志、监控、人工确认
源码视角确认 源码中存在、具备该能力 构建文件、配置、注解、接口定义、代码调用
技术推测 推测、疑似、待确认 包名、类名、依赖名等单一弱信号
当前未发现 当前未发现稳定证据 已按范围查找,但没有稳定证据

高风险断言默认降级:生产启用、全部配置、所有入口、完整链路、实际调用、已完成——没有运行态材料或人工确认,一个都不许写。改写示例直接进了规范:

不推荐 推荐
所有配置通过 Nacos 下发 当前源码未包含本地配置;结合 Nacos 依赖,推测配置主要由 Nacos 或部署环境注入,运行态待确认
生产使用 MySQL + Redis + MQ 源码存在 MySQL/Redis/MQ 依赖或配置,生产使用待运行态确认
调用 sfa-base 源码存在 client/依赖,具备调用能力,实际流量待确认
完整调用链如下 核心调用链候选如下,待代码级 trace 确认

注意最后一条:连「调用链」都要降级成「候选」,除非你做了代码级 trace。这套措辞规范防的不是 AI 说错话,是防「听起来很对」——外行看不出区别,但每一份报告的使用者都不会被过度断言误导。

还有两条配套纪律:

  • 冲突不许抹平:工具之间结论冲突时,写 冲突待复核 并列出冲突来源,不许自动合并成单一事实;下层发现与上层冲突,回传上层文档,不要静默改写上层世界观
  • 证据分优先级:运行态材料 > 人工确认 > 部署发布材料 > 代码图谱 > 源码 > 历史文档;历史文档必须标日期,日期不明写 待确认

「没查到」和「不存在」是两回事,「源码里有」和「生产在用」是两回事——AI 分不清,就用契约替它分清。

四、多 Agent:单写者、隔离、不可变任务信封

72 个项目,不可能在一个上下文里跑完:会串味、会超限、会互相污染。这套 Skill 的协作设计有三条硬规则。

主 Agent 单写者。 系统级世界观只能由主 Agent 写——子 Agent 可以并行采集原始证据,但术语统一、冲突仲裁、最终写入只能一个人干。否则十个 worker 写出十套术语,世界观就散了。

上下文硬隔离。 每个项目的项目级分析,都在独立的 child session 里执行,任务信封由脚本统一生成:

./scripts/build-project-task.sh <当前根目录> <项目目录名> <MCP project>

规范里写死了不许带什么:

禁止把其他项目源码、报告、child session 输出或历史总结传入 worker。

每个 worker 只看自己的项目 + 系统级事实底座,谁也别想看别人的答案。并行结果合并时,只合并状态、输出路径、校验结果和冲突计数——合的是账,不是内容。

不可变任务快照。 批量模式下,任务不是一句 prompt 甩过去的,而是先冻结成不可变计划:批次计划、运行状态、任务快照都落在 project-batches/<run-id>/ 目录里,Task prompt 里只有快照路径、SHA-256 和任务 ID。worker 先校验引用,再读快照——prompt 短了,意图无法被中途改写,跑到一半断了还能按 run-id 续跑。默认并发度 4 的滑动窗口,防止几十个任务一起把机器打爆。

这些规则和「提示词写得好不好」已经没关系了,这是分布式系统的工程纪律搬到了 Agent 编排上。

五、交付:校验不过,不算完成

扫描的产物全部落在统一目录,不散写进业务工程:

wantwant_scan_docs/
├── system/00-系统级事实底座.md
├── portal/index.html          ← 零依赖静态系统门户
└── projects/<项目目录名>/
    ├── <项目目录名>.md
    ├── internal-map/project-internal-map.md
    ├── module-analysis/modules/<模块名>/模块级说明.md
    └── code/<链路名>/代码级链路.md

文档写完不算完,校验通过才算完。 项目级文档必须过 validate-project-docs.sh——校验器以 contracts/project-doc-v1.json 为唯一契约,检查标题、章节顺序、重复或额外章节、机器状态、统计口径、证据引用和敏感值。模板的顶级章节和必填二级章节是固定输出契约:不得删除、改名、重排、新增;缺证据的项保留原文,写 不适用、当前未发现稳定证据 或 待确认。

注意最后这句:缺证据也得保留章节并如实标注。这和生产排查 Skill 的「未确认是合法答案」是同一个灵魂——模板允许空着,但不许撒谎。

全部项目收口后,generate_architecture_portal.py 生成一个零依赖的静态系统门户:类似 Draw.io 的单张画布,按后端、前端、客户端、小程序分区,每个项目一个可点击节点,点进去是技术栈、入口、依赖、风险和原始报告。72 个系统的全貌,从「没人说得清」变成「一张图」。

六、这套 Skill 真正想证明的事

很多人问我,这套东西和「帮我分析一下这个项目」的 prompt 有什么区别。区别不在结果,在能不能被人复核:

  • 触发有成本闸门,不会误启动
  • 完成有机器门禁,不是模型自报
  • 措辞有证据分级,不靠语感
  • 上下文有硬隔离,不会串味
  • 文档有契约校验,不靠自觉

一个 prompt 也能生成漂亮的系统分析,但你无法知道哪句是事实、哪句是想象。这套 Skill 做的,就是把「事实、推断、待确认」焊死在每一个交付物里——和生产排查 Skill 是同一个哲学:

过程交给 AI,验收交给契约。

系统会越来越复杂,人不会越来越多。接手系统的尽头,不是更多的「老员工讲给你听」,而是一套能复核、能交接、能重跑的事实底座。


系列说明:本文是「系统扫描 Skill 诞生记」系列导读。后续章节会逐篇展开:分层模型为什么这样切、不同类型工程的画像怎么做、契约校验器怎么写、多 Agent 协作的血泪史,以及一次完整的 72 系统扫描回放。