接手一家新公司,摆在我面前的是 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 系统扫描回放。
评论