Agent 工厂体检：幽灵注册、版本漂移、文档失联，AI 体系的三种病
AI 健康三部曲 · 第 3 篇（Agent 工厂体检）
第一篇，体检"单个 Skill 写得好不好"------看的是文件。
第二篇，体检"一个 Agent 系统架构得好不好"------看的是结构。
这一篇，视角拉到最高：几十个 Skill、10 个域、上千个文件、横跨多个工具的整个体系。
三种失控，全都发生在你眼皮底下：
注册表里有个域------文件系统里没有它；
同一个 Skill------三个地方写着两个版本号；
刚建的 Skill------文档站里搜不到。
没有一个是"报错"的。
一、体系的失控，为什么最难发现
三级视角，三种体检对象，难度是递增的。
微观：单个 Skill。 就是一堆 markdown 文件，扫一遍逐项打勾，谁好谁坏一目了然。
中观：一个 Agent 系统。 它动态执行、错误会传递，但好歹有运行轨迹可查------它跑起来什么样，你盯着看就知道。
宏观：整个体系。 几十个 Skill、10 个域、上千个文件、跨多个工具的调用链。这时候麻烦变了：不是某个东西"坏了"，而是没人能一眼看完所有东西。
体系失控有三个特征，一个比一个隐蔽：
特征一：每个局部都是对的。
注册表里那个域的元数据齐全，写得没毛病；文件系统里也确实没有那个目录，干干净净。两边各自都"对"------只有把它们放在一起对照，才能看出问题。
单个 Skill 坏掉，是"写错了"；体系失控，是"两边都对，但对不上"。前者的敌人是错误，后者的敌人是差异。
特征二：全部不报错。
跑了不存在的域，路由不会给你弹错误框------它只会静默地找不到东西。
版本号打架，没有任何进程会崩溃------它只会让你在某个脚本里拿到错误的"新旧判断"。
文档站里少了一页，不会 404------因为根本没有页面会去"请求"那一页。
不报错的不一致，才是体系里最贵的债。 因为没有任何机制会提醒你，你只能主动去数。
特征三：它会撒谎，而且你会信。
这是最要命的一条。你把路由交给注册表、把统计交给索引、把导航交给文档站------它们是你的"事实来源"。当这些来源本身开始漂移，你拿到的每个数字都是错的，而你没有理由怀疑。
体系体检要做的，就是定期把这些"事实来源"和现实对一次账。
三种最常见的失控，先给它们起个名字：
- 幽灵注册------注册表说"这里有个域"，文件系统说"没有"；
- 版本漂移------同一个东西，多个地方写着不同的版本号；
- 文档失联------东西存在，但你的导航系统里找不到它。
今天这台体检器：system-health，全体系健康大总管。下面用一个真实体系（我自己这套：37 个自研 Skill、10 个域）开箱跑一遍。
二、11 项检测，一项都不能跳
体检器的宏观检测有 11 项，每一项盯的都是一个"可能对不上"的位置：
| # | 检测项 | 盯什么 | 这次体检的结果 |
|---|---|---|---|
| M1 | 版本同步 | 注册表版本 vs SKILL.md frontmatter | ⚠️ 3 处漂移 |
| M2 | 文档站覆盖 | 文档条目 vs 实际 Skill 清单 | ⚠️ 缺 3 个 |
| M3 | 架构完整性 | 每个域的三层结构是否齐 | ❌ 幽灵注册 1 个 |
| M4 | 知识库一致性 | 索引统计 vs 实际文件数 | ⚠️ 统计过时 |
| M5 | 跨域引用完整性 | extends / 引用的目标是否存在 | ⚠️ 断链 2 条 |
| M6 | 文档发布状态 | 滞留超 14 天的草稿 | ✅ |
| M7 | intents 完整性 | 每个域的路由意图是否为空 | ✅ |
| M8 | 自评一致性 | 已知局限表 vs 实际模块（防自评过期） | ✅ |
| M9 | 市场页面同步 | 展示页列表 vs 注册表 | ⚠️ 缺 1 冗余 13 |
| M10 | 质量评分扫描 | 100 分制自动化评分 | ⚠️ 低分 2 个 |
| M11 | 文章投喂数据同步 | 浏览页数据 vs 实际文章数 | ✅ |
首检通过率 4/11，其余 7 项全部带着修复项收尾。这个数字看起来不太好看------但记住，体检的价值不在分数，在"把差异摆到台面上"。7 个 ⚠️ 里有 6 个是几分钟就能修的小问题，唯一真正危险的（M3）藏在最里面。
体检流程分 5 步：
vbnet
┌──────────────────────────────────────────────────────┐
│ system-health 体检工作流 │
├──────────────────────────────────────────────────────┤
│ │
│ Step 0 触发 手动发起 / 距上次 >7 天自动提醒 │
│ │ │
│ Step 1 宏观扫描 M1~M11 十一项必检，一项不能跳 │
│ │ 版本 / 文档 / 架构 / 一致性 / 评分 │
│ │ │
│ Step 2 域深度 专员在 → 派单；专员缺 → 亲自动手 │
│ │ │
│ Step 3 出报告 一句话结论 + 与上次的增量对比 │
│ │ │
│ Step 4 存档 latest 覆盖 + history 永久归档 │
│ │
└──────────────────────────────────────────────────────┘两个设计细节单独说。
Step 0 的提醒，不阻断。 距上次体检超过 7 天，体检器只提醒，不强制执行------你可以忽略它。为什么？体检这件事如果变成"强制拦截"，你会开始绕过它，然后它就死了。能被忽略的提醒，才能活得久。
Step 4 的存档，只增不减。 每次体检报告同时写两份：latest.md 覆盖更新，history/{日期}.md 永久归档。历史报告永远不删------因为体系健康的判断标准是"跟上次比"，没有历史，就没有趋势。
体检器还立了一条硬规矩：11 项宏观检测，任何触发方式下都不允许跳过。 慢一点没关系，漏项的体检等于没检。
三、现场一：幽灵注册------注册表里有个域，现实中没这个东西
先把最危险的说了。
病例： M3 架构完整性检测扫过一个域：business-hub。注册表里它存在------版本号写着 0.2.0，状态标着 stable，模块列表、描述，一应俱全。但文件系统里，business-hub/SKILL.md 不存在。
一个标着"stable"的域，其实从未诞生。
为什么这是检测项里最危险的一个？
因为路由不会报错。用户在对话里说"帮我管理客户交付"，meta-hub 查注册表 → 命中 business 域 → 去加载它的 SKILL.md → 撞墙。整个过程没有任何一方会主动喊"这里有问题"------注册表觉得自己信息很全，文件系统觉得自己很干净。
类比一下：户籍系统里有一个完整档案的公民------身份证号、住址、照片齐全------但现实中查无此人。 更迷惑的是他的状态还标着"正常"。
覆盖度雷达图也印证了它的危害：business 域均值 1.0/5，全体系最低------因为它整个是虚的。
修复路径（这个案例里花的时间比想象中多）：
- 补建
agent/business-hub/：SKILL.md + 4 个模块（交付管理 / Skill 市场 / MCP 集成 / CI-CD 流水线）； - 建立软链部署；
- 更新注册表（从幽灵变成实体）；
- 补上市场页面展示；
- 全量测试验证：vitest 54/54 通过。
这个病例的心法一句话：注册表和文件系统之间没有"自动对齐"------不查，就永远对不上。
注意最后一步：幽灵注册修复后，是拿测试兜的底。别信"我补完了"，信"54 个用例全绿"。
四、现场二：版本漂移------同一个 Skill，三个地方两个版本号
病例： M1 版本同步检测。同一个 meta-hub：
skill-registry.json里写着 2.0.0；hub-registry.json里写着 2.2.0；- 根目录 SKILL.md 的 frontmatter 里也写着 2.2.0。
三个地方，两个版本号。而且这三处没有一处是"错"的------每一处单独看都像刚更新过。
同一次检测还扫出两个更极端的：soul-hub 连 frontmatter 都没有（不存在版本号）；test-base-skill 的 SKILL.md 无 version 字段，注册表里却标着 0.1.0。
为什么版本漂移危险？
版本号是所有自动化判断的"第一依据"：
- 你写个脚本盘点"哪些 Skill 三个月没更新了"------版本号漂移，盘点结果全错；
- 你判断"这个域还是不是活跃维护"------版本号打架，你连信哪个都不知道；
- 未来做依赖解析（A 需要 B ≥ 2.1）------版本是假的，依赖管理就是假的。
版本是任何入口、任何脚本拿来判断新旧的第一依据。两处打架时，谁也不知道该信哪个------于是所有依赖它的判断，全部失效。
根因不复杂：手工维护 + 多处副本 = 必然漂移。 不是谁粗心，是结构问题。同一个事实存在三个地方，就注定有一天会对不上------就像上一篇文章说的：结构上让错误有路可走。
修复： 统一为 2.2.0；给 soul-hub 补上 frontmatter（version 1.0.0）并同步到注册表；顺带把另一个漂移的（investment-research-assistant 0.1.0 → 1.1.0）一并统一。
心法一句话：版本只在一处维护，其他地方引用它------单一事实源，不是洁癖，是止损。
五、现场三：文档失联------东西存在，但你的导航里没有它
病例： M2 文档站覆盖 + M5 跨域引用，两把尺子同时量，量出两类失联。
第一类：该有的页面不存在。
文档站里 46 个文档，对照实际 Skill 清单，缺 3 个：soul-hub、pm-skill-inspector、design-skill-inspector。其中后两个是同一天刚创建的域专员------建了 Skill，忘了建文档。
另一把尺子（M9 市场页面同步）量出同样的毛病：用户能看到的 Skill 市场页面里，soul-hub 也是缺的。
第二类：地图上有路标，路是断的。
M5 扫出 2 条断链：fe-hub 引用 retrieval-skill-cards、引用 tech-stack-matrix------两个目标文件都不存在。也就是说 fe-hub 的工作流里写着"去找 XX"，但 XX 不在那。
为什么文档失联危险？
文档和导航是用户（包括未来的你）唯一的入口。文档失联 = 这个 Skill 对用户来说等于不存在。 功能都在、测试全绿、但它就是"看不见"------而看不见的东西，不会被任何人使用。
顺带说第三类失联：数字和现实失联。
同一次体检的 M4 扫出一个细节：知识库索引的头部统计写着"453 篇"，实际数出来是 455 篇；raw 状态声明 8 篇，实际 2 篇。数字不是手写坏的------是手写的，然后文件变了。
数字是最容易被相信的东西，也是漂移后最没人怀疑的东西。 统计口径如果靠手写，每次新增内容都是一次对账风险。
修复： 补建 3 个缺失文档（46 → 49）；2 条断链改指向（补占位文件 + 引用改指绝对路径）；索引头部统计全量刷新（455 篇逐一验证登记）。
心法一句话：失联不会报 404------没有一个页面会去"请求"那个不存在的页面。只有主动数一遍"该有的 vs 实际有的"，才能发现。
六、这台体检器的三个设计
三个现场拆完，说说体检器本身。三个设计点，都是被真实问题逼出来的。
设计 1：动态分工------有专科医生就转诊，没有就全科坐诊。
体检器对每个域先查一件事：这个域有没有自己的专员（域体检 Skill）？
- 有 → 派单：把深度体检任务发给域专员，等它汇报，体检器负责汇总；
- 没有 → 亲自动手：体检器自己执行简化版深度检查。
这次的实际情况：10 个域，4 个有专员（元层、前端、产品、设计），其余 6 个由体检器亲自跑。
这个设计的好处不在省事，在于专员的检测标准比"外人"更准------前端域的问题是 fe-skill-inspector 最清楚，让 system-health 隔着域去猜，不如派单。而对没有专员的域，体检器兜底，不留检查盲区。
设计 2：增量审计------只查"变了的东西"。
第一次体检全量扫。但第二次开始，体检器只扫"变更集"：两次体检之间动过的文件（git diff 上次体检 commit..HEAD，圈定改动范围内的 skill/agent/knowledge 目录），没动过的部分直接继承上次结论。
为什么？因为体检过一次之后，绝大多数文件在两次体检之间根本没变------全量重扫 90% 的机器时间花在了没变的东西上。这个优化的思路来自代码审查里的"爆炸半径"分析：变更的文件才是审计焦点。
设计 3：报告纪律------不虚构、有对比、说到做到。
三条：
- 一句话结论必须最先出现------用户可能只看这一句，它必须能独立成立；
- 必须和上次对比------新增了什么、修好了什么、新出了什么问题、分数怎么动的，四行表格说清楚"这周体系是变好还是变坏"；
- 无法检测就标"无法检测"------不猜、不编、不留白给想象。体检报告的信誉，靠"不确定的地方明确说不确定"积累。
七、体检器自己的坑
按这个系列的规矩，最后自曝。这台体检器有两个坑，都挺典型的。
第一跤：第一次体检，最先查出的问题是"这个体系从来没有体检过"。
首检报告里有一行小字最扎心：health-log/ 此前不存在，本次为首次体检。
也就是说------这个体系功能一直在加、Skill 一直在涨、域一直在扩，但"这个体系健不健康"这个问题，从来没有被问过一次。第一次跑体检，第一件发现的事是体检本身缺席。
像一个人活了三十年，第一次进医院------最大的检查结果，是"你从来没做过检查"。
这个坑的启示：健康是"管理出来的"，不是"自然状态"。 你不主动测量，它不会自己好，也不会自己坏------它会自己漂。
第二跤：第一版每次全量重扫，第二次体检时才发现有多蠢。
第一版体检器很实诚：每次从零扫描所有 Skill、所有依赖、所有注册表。第一次跑，15 分钟，感觉很值。
第二次跑的时候发现问题了：两次体检之间，整个体系只改了 6 个文件------剩下的 50 多个文件和 60 多条依赖引用，跟上次一模一样。全量重扫，等于把 90% 的时间花在确认"没变的东西还是没变"。
于是引入增量审计（设计 2）。体检器自己进入了"体检器需要被优化"的循环。
这两个坑的共同点，也是这个系列最想说的那句话：
体检器自己也会腐化，所以它必须接受"被体检"。健康不是一个状态，是一个持续动作。
八、你也能跑一次：三种用法
体检器可以跑任意 AI 体系------多 Skill 的、多域的、跨工具的。三种用法：
1. 完整体检（默认）
你：体系自检
或：全体系健康检查输出：一句话结论 → 11 项宏观检测明细 → 各域深度检测 → 与上次的增量对比 → 建议操作清单（P1/P2/P3 分级）。
2. 定期自动提醒
每次 meta-hub 被唤醒时，自动对比"距上次体检多少天"。超过 7 天 → 提醒你一句，不强制。适合把体检做成习惯，而不是事故后的补救。
3. 专项深挖
你：前端域深度体检指定域直接触发域深度检测（有专员的域走派单模式），输出该域的执行流程 + 架构对照 + 覆盖度评分。
适用 / 不适用
| 适合 | 不适合 |
|---|---|
| 体检整个 AI 体系（多域、多 Skill、跨工具链的账实核对） | 体检单个 Skill 写得怎么样（用 skill-inspector，第 1 篇） |
| 大改前 / 大改后做基线对比（"这次重构到底动了什么"） | 审查一个 Agent 系统的架构设计（用 agent-arch-inspector，第 2 篇） |
| 定期健康巡检，发现"静默漂移" | 修 Bug、写功能------那是开发，不是体检 |
| 新接手一个 Skill 体系，快速摸清家底 | 代码级性能优化、安全渗透 |
九、速记表
| 你想做什么 | 用什么 |
|---|---|
| 体检整个 AI 体系 | system-health（11 项宏观 + 域深度 + 增量对比） |
| 查"注册了但不存在" | M3 架构完整性（幽灵注册检测） |
| 查版本号打没打架 | M1 版本同步 |
| 查文档失没失联 | M2 文档站覆盖 + M5 引用完整性 + M9 市场页面 |
| 查统计数字准不准 | M4 知识库一致性 + M11 文章数据同步 |
| 体检单个 Skill | skill-inspector（第 1 篇） |
| 审查 Agent 系统架构 | agent-arch-inspector（第 2 篇） |
| 让体系定期自检 | 7 天提醒机制（超期只提醒，不阻断） |
这次体检的核心结论一句话 ：体系的三种失控------幽灵注册、版本漂移、文档失联------全都是"两边都对，但对不上"；治理的起点不是修 Bug，是定期把"事实来源"和现实对一次账。
避坑指南
| 问题现象 | 原因 | 解决方法 |
|---|---|---|
| 路由命中一个"不存在的域" | 注册表有、文件系统没有（幽灵注册） | 定期对齐"注册表 ↔ 文件系统"，用检测项兜底 |
| 同一个 Skill 两个版本号 | 手工维护多处副本，必然漂移 | 单一事实源：版本只在一处维护，其他地方引用 |
| 新 Skill 文档站搜不到 | 建了 Skill 忘了建文档 | 把"文档存在"写进新增 Skill 的完成标准 |
| 统计数字对不上实际 | 数字是手写的，文件是自动变的 | 统计用脚本生成，永不手写 |
| 体检报告没人执行 | 报告只有问题，没有优先级和后果 | 一句话结论 + P0/P1/P2 + 每项写"为什么" |
| 每次体检都像第一次 | 全量重扫、无历史对比 | 增量审计（只扫变更集）+ 与上次对比表 |
| 体检报告越写越多没人看 | 报告不可独立阅读 | 一句话结论必须最先出现，能独立成立 |
十、常见问题（Q&A）
Q1：体系体检和 Skill/Agent 体检有什么区别？
Skill 体检看"单个文件写得怎么样"，Agent 体检看"一个系统的架构有没有病"，体系体检看"整个仓库的账对不对得上"。三者是嵌套关系：体系体检发现问题后，往往会落到某个 Skill 或某个 Agent 上再深查。
Q2：11 项检测必须每次都全跑吗？
必须。这是体系体检的硬规矩------漏一项就可能漏掉一种"不报错的债"。但第二次以后可以用增量审计：只重扫变更集内的域，未变更的项继承上次结论，既全跑又省时间。
Q3：多久体检一次？
手动触发建议每月一次；日常可以打开"7 天提醒"------超过 7 天没体检，入口被唤醒时提醒一句，不强制。频率取决于体系变化速度：大改后立刻跑一次，稳定期每月一次。
Q4：首检通过率很低怎么办？
正常。首检的价值就是"第一次把问题摆到台面上"。4/11 通过不丢人，丢人的是一直不体检。按 P0 修，修完复检，分数会很好看。
Q5：小团队只有十几个 Skill，也需要体系体检吗？
需要，但可以 lightweight。小团队最大的风险不是"问题多"，而是"问题发现得太晚"。体系体检帮你建立"事实来源必须和现实对账"的意识，这个意识比任何工具都值钱。
Q6：发现幽灵注册后怎么修？
三步：补建实际文件/目录、更新注册表、补测试或验证命令。不要只改注册表------那就把幽灵注册变成了"合法但不可用"的状态。修完必须能跑通。
写在最后
三部曲的最后，把三级视角合起来看：
第 1 篇（微观）：单个 Skill。 腐化在文件里------8 个"假 0 分"，评分器自己的盲区。
第 2 篇（中观）：Agent 系统。 腐化在结构里------错误有路可走，每一环都在正常工作，整体是错的。
第 3 篇（宏观）：整个体系。 腐化在"两本账"之间------注册表和文件系统、版本号和版本号、导航和现实，各自都"对"，对不上。
三级体检，同一个立场：
你的 AI 资产（Skill、Agent、知识库、工作流）和代码一样会腐化、会漂移、会负债。区别是代码的债有 CI 盯着你，AI 资产的债只有主动体检才能发现。
所以这个系列从头到尾，教的其实不是"三个工具"，是一件事：
定期测量你自己搭的东西。
- 15 分钟，11 项检测，你可以知道"一个体系的家底"------注册表是不是真的、版本是不是一致的、文档是不是找得到的；
- 5 个窗口，你可以知道"一个 Agent 系统错在哪里"------它会不会编、错误传不传、记忆贵不贵；
- 41 项检查，你可以知道"一个 Skill 写得好不好"------边界清不清、护栏有没有、能不能被搬运。
工具都会进化，会像文里写的那样自己摔跤、自己爬起来。但"主动测量"这个习惯，是你自己的。
三部曲到这里收尾。三件工具都在这个体系仓库里开源，愿你的一套 AI 资产，经得起对账。
本文相关产出：
- 体检器：
modules/system-health.md（meta-hub 内置模块：11 项宏观检测 + 域深度分派 + 报告模板）- 本次完整体检报告：
health-log/latest.md（37 个自研 Skill、10 个域、11 项全量数据）- 域专员：4 个（meta / frontend / product / design 各自的 skill-inspector）
- 系列前篇：skill-inspector（第 1 篇）、agent-arch-inspector（第 2 篇）
想要本文的完整体检脚本？
体系体检器（system-health：11 项宏观检测 + 域深度分派 + 报告模板）+ 本次全量体检数据------都已打包好，评论区留言或私信我，直接发你。
三部曲三件套（Skill / Agent / 体系三个体检器）也可以打包，评论区留言或私信我，一起发你。