expert-audit
站在使用者视角审查 expert-team 产出的专家资产:零上下文用户能否看懂照用、格式是否合规(R1–R7 / CR1–CR9 / INDEX),格式问题自动修复、可读性问题给修复路径。触发:"核对专家团"、"审查专家资产"、"expert audit",或 expert-team 产出后自动触发。
SKILL.mdskills/expert-audit/SKILL.md
GitHub专家资产审查(使用者视角)
AI 说明层
目的:expert-team 的资产由 AI 生成,生成者自检(Step 5/6)有天然盲区——格式都对,但内容可能"作者自己懂、别人看不懂"。本 skill 提供独立的、使用者视角的验收环节。
功能:双轨审查——轨道A 使用者冷读测试(能看懂吗/能照用吗,核心),轨道B 格式合规(结构清点 + R/CR 规则 + INDEX 格式)。产出 P0/P1/P2 分级报告;格式类问题自动修复,可读性问题给出修复路径。
使用场景:
- expert-team 创建 / 合并补全一个专家(或专题)完成后自动触发
- 用户说"核对专家团"、"审查专家资产"、"这个专家文档能看懂吗"
- 使用专家资产时反复看不懂,怀疑资产质量
核心判据
假设使用者是一个只拿到这份文档、完全没有代码上下文的用户——他能看得懂吗?能照着用吗?
一切审查围绕这一句话。格式合规是底线,"看得懂、照着能用"才是目标:格式全对但冷读不过,仍判不合格。
与相邻 skill 的边界
| skill | 关系 |
|---|---|
| expert-team | 生成资产并做生成者自检(R/CR 自查 + auto-review);本 skill 是独立的使用者视角事后验收。内容级问题的重建/补全走 expert-team。项目全局资产 PROJECT.md 由 expert-team 维护,本 skill 默认不审查,仅用户显式声明时审查 |
| expert-lookup | 查找复用资产;契约层小范围内容修正走其"受限增量更新"。本 skill 报告中的契约层 P0/P1 修复路径多指向它 |
| challenger | 通用对抗质疑,不了解专家资产结构;本 skill 是领域专项审查,内置资产结构与规则知识 |
| auto-review | 写文件后的通用质量闭环;本 skill 审查的是已落盘的存量资产,不依赖写入动作触发 |
输入与范围
- 默认单专家:用户指定专家名(或从上下文推断,如 expert-team 刚完成的专家);含子专家时一并审查
- 专题:指定专题名时,审查专题层(topic.md / T0 / T1)+ 其下全部专家
- 全量:用户说"全部核对一遍"时,遍历
.module-experts/下所有专家/专题,逐个出报告 - PROJECT.md(默认不审):
.module-experts/PROJECT.md(项目级共享资产)默认不纳入审查范围;仅用户显式声明(如"连 PROJECT.md 一起核对")时才纳入审查 - 资产位置:默认项目级
.module-experts/;用户明确要求时才审查用户级~/.module-experts/
执行流程
Step 0:定位资产与确认范围
- 读
.module-experts/INDEX.md,定位目标专家/专题的记录与目录 - 确认模块根路径(从 INDEX / agent.md 读取)——后续 grep 验证以此为源码范围
- 目标不存在 → 终止并提示可用专家清单
Step 1:结构清点
对照 expert-team 的组织模型逐项核对(规范原文见 use_skill("expert-team")):
| 检查项 | 要求 | 级别 |
|---|---|---|
| 必出文件 | agent.md + C0-使用总览.md + C1-能力契约.md + implementation/01-架构.md + 02-实现.md 存在且非空 |
P0 |
| 条件必出 | 有数据落地 → C4-数据流向与消费.md 存在;模块有测试时 → implementation/06-测试.md + test/known-failures.md 存在(PROJECT.md 标注「❌ 无法运行 / 无测试」的服务除外——按「测试不可运行跳过」规则不强制必出) |
P1 |
| 层级规则 | 子专家仅一级(sub-experts/ 下无嵌套);专题不嵌套、不含 implementation/、含 topic.md + T0-专题总览.md |
P1 |
| INDEX 记录 | 该专家/专题在 INDEX.md 有记录,且含匹配关键词行(8~15 个)与 git commit 基线行(语义见 expert-team「文档说明·资产基线 commit」;旧资产缺失不判违规,建议合并补全时刷新补上) | P1 |
| 命名规范 | 契约层 C 前缀、专题层 T 前缀、实现层数字前缀、目录中文业务名 | P2 |
| 无 CHANGELOG | 资产目录内不应存在 CHANGELOG(已废止机制) | P2 |
| 项目共享资产 | PROJECT.md(存在时):含项目信息/技术栈/架构形态/核心功能/核心服务清单(含代码位置/测试可执行性)/配套服务关系/架构图/数据流向图/运行环境 |
P2(仅显式声明时检查) |
Step 2:轨道A——使用者冷读测试(核心)
冷读纪律:本步骤分两遍。第一遍只读文档、禁止看源码,以零上下文用户身份记录所有"看不懂 / 存疑 / 没法照做"的点;第二遍对照源码验证,区分是文档问题还是初读误解。跳过第一遍直接对照源码 = 生成者视角复检,审查失效。
五项测试:
| # | 测试 | 方法 | 不过的典型信号 |
|---|---|---|---|
| 1 | 冷读三问(C0) | 只读 C0,尝试回答:这模块是干嘛的?怎么调用核心能力?会踩什么坑? | 能力清单是文件名罗列而非能力描述;边界/坑一句没有或全是套话 |
| 2 | 术语自足 | 通读契约层,标出所有内部术语/黑话,检查首次出现处是否有解释 | "走 XX 通道时需先挂 YY 钩子"——XX/YY 全文无解释 |
| 3 | 示例照做(C1/C2/C3) | 模拟"照抄示例写调用代码":签名、参数、导入是否齐全可抄;第二遍抽样 ≥3 个示例 grep 源码验证 API 签名真实存在,并顺带核对该 API 的契约描述(参数行为语义/约束)与源码分支或测试是否矛盾 | 伪代码、... 省略关键参数、签名与源码不符、契约描述的行为与代码矛盾、写的是被调用方实现而非使用方代码 |
| 4 | 导航可达(implementation/) | 每篇抽样 ≥3 个章节来源的关键符号,grep 源码验证命中 | 符号不存在(笔误/已重命名)、只标了路径但文件数千行无从下手 |
| 5 | 视角污染 | 契约层是否混入实现细节(算法/私有方法/内部结构/DB schema/实现模式名,即 CR3);实现层是否复述契约而非引用 | C1 里讲"内部用跳表实现所以快" |
判定:测试 1/3 不过 → P0(用户会用错或根本用不起来);测试 2/4 不过 → P1(能用但费劲);测试 5 → 按 CR3 级别定 P1。
Step 3:轨道B——格式合规
按 expert-team 内嵌规则逐篇自检,只判定不重复规则原文:
- 实现层:R1–R7(cite 块 / 中文锚点目录 / 章节来源含 file:// 路径 + 关键符号 / 图表来源 / file:// 前缀 / 符号真实可 grep / ≥2 设计维度 + Mermaid)
- 契约层:CR1–CR9(C0 四要素 / C1 六要素含行为语义与真实示例 / 无实现细节 / 契约来源为类名方法签名 / 已知坑三要素 / C4 黑盒消费视角)
- INDEX:记录格式与 expert-team Step 7 的模板一致,关键词行齐全;基线一致性:INDEX 的 git commit 与 agent.md/topic.md 出处行的基线一致(不一致 → P1,修复路径:expert-team 合并补全时刷新;禁止本 skill 代改——基线须真实对应资产创建/更新时刻,代填 HEAD 会掩盖未核对变更)
- 测试信息:
06-测试.md含测试可执行性(运行命令/环境依赖/已知失败);test/known-failures.md切面级标注(子专家/功能域各自标注)且每条含执行方式(运行该测试的完整命令) - error 级违规 → P1;warning 级违规 → P2(与轨道A 重叠的项不重复计,如 R6 符号真实性已由测试 4 覆盖)
Step 4:问题分级与自动修复
分级:
| 级别 | 判据 | 处理 |
|---|---|---|
| P0 | 用户会用错或完全看不懂:冷读三问答不出、示例签名与源码不符、必出文档缺失/空壳、契约与代码行为矛盾 | 必须处理;在报告置顶 |
| P1 | 能用但低效:术语不自足、符号 grep 不中、结构/INDEX 违规、error 级格式违规 | 建议处理 |
| P2 | 瑕疵:warning 级格式违规、命名不规范、措辞 | 可选处理 |
自动修复白名单(仅限不需要重新调研源码即可完成的机械修正,静默执行、报告中一并列出):
- 目录锚点与章节不对应 → 修正锚点
- 引用路径缺
file://前缀 → 补前缀 - Mermaid 图缺
图表来源→ 从所在章节的章节来源补 - INDEX 记录缺字段行(如匹配关键词行)→ 从 agent.md / C0 提取补建
- 无内容章节未标「该模块无此项」→ 补标注
- 文件命名不规范 → 重命名并同步 INDEX / 交叉引用
禁止自动修复(报告 + 修复路径,不代改):
- 一切内容级问题:冷读不过、术语缺解释、示例失真、符号错误的正确值、契约缺失/编造——修复需要重新调研源码,路径:契约层小修 → expert-lookup 受限增量更新;结构性缺失/实现层问题 → expert-team 合并补全或重建
- 理由:审查者当场编内容 = 用一个未经调研的答案掩盖问题,比留着问题更危险
Step 5:输出审查报告
默认在对话中输出;用户要求落盘时写 review/expert-audit-{专家名}-{date}.md。
# 专家资产审查报告:{专家名}
**核心判据结论**:✅ 零上下文用户可看懂并照用 / ⚠️ 部分可用(见 P0/P1) / ❌ 不可用
**统计**:P0 ×N / P1 ×N / P2 ×N 自动修复 ×N
## 冷读三问回答(轨道A 测试 1 的实际回答,作为证据)
- 这模块是干嘛的:{凭 C0 给出的回答,答不出则写"答不出——{缺什么}"}
- 怎么调用核心能力:{...}
- 会踩什么坑:{...}
## P0(必须处理)
| # | 位置 | 问题 | 证据 | 修复路径 |
|---|------|------|------|----------|
## P1(建议处理)/ P2(可选)
(同表结构)
## 已自动修复
- {文件}:{修复内容}
行为边界
- 只审查不重建:内容级修复一律指路 expert-team / expert-lookup,本 skill 不代写内容
- 冷读纪律不可跳:第一遍禁止看源码;全量模式下每个专家同样两遍
- 抽样即可:示例与符号验证抽样 ≥3(不足则全查),不逐条穷举;报告注明抽样范围
- 全量/大专题可并行:待审专家 ≥2 时可用 task-dispatch 派子 agent 并行审查,每子 agent 负责一个专家——子 agent 天然零上下文,更贴合冷读纪律;主 agent 合并各报告
- 不审查源代码质量:源码问题(bug/坏味道)不在范围,只审"文档是否如实、可懂地描述了它"
- 旧格式资产:遇到旧行号标注(
#Lx-Ly)不判违规、不迁移,仅在测试 4 中按"过期快照"对待并建议重建时切换 - 自动修复达 3 处以上时在报告中汇总提示,异常多(>10)说明资产可能是旧格式,建议走 expert-team 合并补全而非零碎修
- PROJECT.md 默认不审:
.module-experts/PROJECT.md(项目级共享资产)默认不纳入审查范围;仅用户显式声明时才审查其内容完整性(服务清单与专家资产对应、配套关系、图是否齐全等),其维护/更新由 expert-team 与 expert-lookup 负责
验证(测试方式)
- 对一个刚生成的合格专家审查 → 冷读三问可答,P0 为 0
- 人为删掉 C0 的"已知坑"章节 → 测试 1 报 P0
- 人为把 C1 某示例参数改错 → 测试 3 抽样 grep 报 P0
- 人为改坏一个章节来源符号 → 测试 4 报 P1
- 删掉 INDEX 关键词行 → Step 1 报 P1 且自动补建
- 对专题审查 → 覆盖专题层 + 其下全部专家,层级违规可检出
- 显式声明审查 PROJECT.md 时 → 内容完整性可检出(服务清单/配套关系/架构图/数据流向图/运行环境);默认不审时不被触发
- INDEX 缺 git commit 基线行 / INDEX 与 agent.md·topic.md 基线不一致 → 可检出(P1)且修复路径指向 expert-team 刷新,本 skill 不代改