expert-lookup
查找并复用已沉淀的"业务专家"资产包(.module-experts/):按使用意图分层加载(使用 → 契约层,深入 → 实现层 + 源码),支持子专家与专题查找。触发:"有没有这个模块的专家"、"查专家"、"expert lookup",或 AI 接手/排查某业务模块时。
SKILL.mdskills/expert-lookup/SKILL.md
GitHub业务专家查找
AI 说明层
目的:在 AI 或用户需要了解/使用某个业务模块时,快速查找是否已有沉淀的"业务专家"资产包,支持多专家同时加载协同工作(最多3个),按使用意图分层加载避免无谓读实现代码,并在使用中发现契约过期或缺漏时增量更新资产(即时级需用户确认),形成"使用即维护"的闭环。支持专题(专题→专家→子专家三级结构)的查找和加载。同时关注测试健康度——加载测试信息(测试位置/可执行性/已知失败),支持排查测试侧问题与维护 known-failures。
功能:
- 查找专家/专题:读取 INDEX.md → 关键词匹配(含 INDEX 中的匹配关键词字段、子专家、专题下专家)→ 读 agent.md(专家)或 topic.md(专题)确认 → 加载资产
- 多专家协同(最多3个):任务涉及多个域时,同时加载多个专家的契约层协同工作;独立子任务可并行派子 agent
- 按意图分层加载:使用/调用→契约层(根目录 C0~C4);诊断/排查→C0+已知坑+implementation/03-数据流转(导航)+读源代码确认,数据类问题(丢失/不一致/没生效)先看 C4 消费链;修改/扩展→C0+implementation/01-架构+02-实现(导航)+读源代码修改;专题→T0-专题总览(跨专家架构)+按需深入专家契约层
- 三层递进:契约层用于"使用"(不需要看代码);implementation/ 用于"导航"(深入模块前先看架构/数据流,知道去哪读代码);源代码用于"确认"(实际改代码时读具体文件)
- 增量更新:使用中发现契约与代码不一致→即时修正(严重)或延迟补充(轻微);疑似差异在契约条目处内联标注
- 关键词自动更新:求解结束时,若本次任务的关键词命中了专家但不在其 INDEX 关键词列表中,自动追加(只增不删,单次 ≤ 5 个),提升后续匹配率
- 测试健康度支持:诊断/排查意图时加载
06-测试.md与test/known-failures.md(测试位置/可执行性/已知失败),辅助判断问题是否来自测试侧;使用中发现测试失败或可执行性问题时可增量更新(Step 6 权限内) - 专题记忆检索:查找顺序含"查 ki 专题记忆"(expert-team 落盘的路标),命中即知晓有此专家+关键入口;跳转前校验专家路径存在,失效回退正常查找;使用中可受限修正记忆路标字段(Step 6 权限内)
- 资产新鲜度检查:命中专家后比对资产基线 commit 与当前 HEAD(Step 4.5),基线落后时用
git diff --name-only {基线}..HEAD -- {模块根}定位变更文件,判断资产是否过期并定向核对,替代全量读代码核对;基线不可用时降级跳过
使用场景:
- AI 需要使用/调用某模块的能力完成任务(优先契约层,不读实现代码)
- AI 接手 / 排查某个业务模块,需要先判断是否有现成专家资产可复用
- 任务跨多个业务域,需要多专家(最多3个)同时协同
- 需要了解超大模块的全局架构(命中专题,加载 T0-专题总览)
- 用户问"有没有这个模块的专家""这个模块有现成资料吗""找一下告警相关的专家"
- 找到专家后希望 AI 直接以专家身份接手解决当前问题
- 需要使用子专家(父专家下某功能子域的专家)
核心原则
- 查找优先:接手业务模块 / 使用模块能力时,先查专家库,再从头读代码
- 双库搜索:同时查项目级和用户级,项目级优先
- 两级过滤:先用
INDEX.md做专家/专题级粗筛,再读agent.md(专家)或topic.md(专题)做职责 / 场景精判 - 必须实读:不能仅凭 INDEX 标题就断言命中,必须读
agent.md(专家)或topic.md(专题)获取职责与适用场景 - 多专家协同:任务涉及多个域时,同时加载多个匹配专家(最多3个)的契约层协同工作,不必只选一个
- 按意图分层加载:变身时根据使用意图决定加载契约层还是实现层
- 三层递进,各司其职:契约层(C0~C4)用于"使用"——知道怎么调用,不需要看代码;
implementation/用于"导航"——深入模块(诊断/改造)时先看架构全貌、数据流、依赖关系,知道该去哪读代码,是代码的"地图",不替代代码但节省追踪时间;源代码用于"确认"——实际修改时读具体文件确认细节,永远权威。三者递进不竞争:用 → 导航 → 确认 - 结果非阻塞:找不到专家不阻塞后续工作,可建议用 expert-team 创建(公共 / 横切知识除外,转存项目记忆)
- 变身求解:找到目标专家后,自动加载相关资产并以专家视角直接着手解决问题
- 使用即维护:使用中发现契约与实际不一致或缺漏时,对契约层做受限增量更新,更新回流资产
- 子专家支持:查找时同时匹配父专家与子专家,子专家匹配更精准时优先加载子专家
- 专题支持:查找时同时匹配专题与专家;命中专题时先加载
T0-专题总览.md了解跨专家架构,再按需深入专题下具体专家的契约层;专题下专家的查找路径为{专题名}/{专家名}/agent.md - 测试健康度关注:诊断/排查测试侧问题时加载测试信息(
06-测试.md+test/known-failures.md),辅助判断问题是否来自测试侧;使用中发现测试问题可增量维护 known-failures - 项目全局上下文:查找/使用前先读
.module-experts/PROJECT.md(如存在)获取项目全局信息(项目信息/技术栈/服务清单/配套关系/代码位置/运行环境),校准匹配意图,提升命中准确度;不存在时提示用户是否优先创建(走 expert-team),不阻塞查找 - 专题记忆检索:查找顺序含"查 ki 专题记忆"路标(expert-team 落盘),命中即知晓有此专家;跳转前校验专家路径存在,失效回退正常查找;记忆只存路标不存专家本体,避免双源漂移
存储位置
| 层级 | 路径 | 说明 |
|---|---|---|
| 项目级 | .module-experts/ |
由 expert-team 生成,随项目版本控制 |
| 用户级 | ~/.module-experts/ |
跨项目通用的业务专家(可选扩展) |
.module-experts/PROJECT.md 是项目级共享资产(非专家/专题):描述项目全局信息(项目信息/技术栈/架构形态/核心功能/核心服务清单/配套服务关系/架构图/数据流向图/运行环境),供所有专家共享。由 expert-team 创建/更新,本 skill 使用时加载,发现全局信息变化时可受限更新。
每个专家子目录含 agent.md(名片)+ 契约层文档(根目录:C0-使用总览.mdC3-代码示例-{topic}.md、C4-数据流向与消费.md)+ implementation/(实现层:01-架构.md07-运维.md)。父专家可含 sub-experts/(子专家,仅一级)。专题含 topic.md(名片)+ T0-专题总览.md(+ 按需 T1-跨专家契约.md),专题下挂专家,专家下可挂子专家(三级结构:专题 → 专家 → 子专家)。无 CHANGELOG——资产变更不单独记录,项目级资产的 git 历史即变更记录(用户级 ~/.module-experts/ 不受版本控制,其变更无追溯,属可接受损失;旧专家目录中如残留 CHANGELOG.md,忽略即可)。
执行流程
Step 1:提取当前需求的关键词
从当前需求 / 问题中提取搜索关键词:
- 业务域关键词:业务领域、功能分类(如
告警、日志、支付、权限) - 模块名关键词:模块根路径、包名、目录名(如
pkg/alert、alert-service) - 功能子域关键词:子功能、子模块名(如
规则管理、通知、查询) - 问题 / 操作关键词:正在排查的现象或要做的操作(如
不触发、新增规则、查询历史)
提取 3-8 个关键词。
Step 1.5:项目全局上下文(PROJECT.md)
查找前先检查项目级共享资产 .module-experts/PROJECT.md:
- 存在 → 读取 PROJECT.md,获取项目全局信息(项目信息/技术栈/架构形态/核心功能/核心服务清单含代码位置/配套服务关系/运行环境),用于校准 Step 3 的关键词匹配意图
- 不存在 → 提示用户「项目尚未创建 PROJECT.md 全局资产,是否优先创建(走 expert-team)?」——提示不阻塞查找,继续正常流程
- 使用中发现全局信息变化(如发现新服务/代码位置不符)→ 受限更新 PROJECT.md 对应条目(Step 6 权限内)
- 测试可执行性预判:PROJECT.md 服务清单中标注目标服务「❌ 无法运行 / 无测试」时,本次使用跳过该服务的测试侧加载(不加载
06-测试.md+test/known-failures.md,测试相关排查直接说明跳过);标注「✅ 可跑 / ⚠️ 依赖外部环境」时正常加载
Step 2:读取 INDEX.md
同时读取两个层级的 INDEX.md:
- 项目级:
.module-experts/INDEX.md(不存在则list_dir .module-experts/枚举专家子目录,逐个读agent.md作为粗筛来源) - 用户级:
~/.module-experts/INDEX.md(不存在则降级枚举)
INDEX.md 顶部含项目全局资产引用(由 expert-team 维护):
## 项目全局(共享资产)
- 资产:PROJECT.md(项目信息/技术栈/核心服务清单/配套服务关系/架构图/数据流向图/运行环境)
- 说明:所有专家共享的项目全局上下文,创建/使用专家前建议先读
读取 INDEX.md 时同步识别该引用;无该引用时以 Step 1.5 的 PROJECT.md 检查为准。
INDEX.md 中每条记录形如(由 expert-team Step 7 维护):
专家记录:
## {中文专家名}(普通专家,职责摘要见 agent.md)
- 模块根:{path}
- 生成日期:{date} git commit:{hash}(资产基线,见 Step 4.5 新鲜度检查)
- 匹配关键词:{关键词1}, {关键词2}, ...(8~15 个,中英混合)
- 契约层:C0-使用总览, C1-能力契约, C2-使用流程, C3-代码示例-xxx, C4-数据流向与消费(或「暂无」)
- 实现层:implementation/01-架构, 02-实现, 03-数据流转, ...
- 子专家(如有):
- {子专家1名}({一句话职责}),匹配关键词:{...}
- {子专家2名}({一句话职责}),匹配关键词:{...}
专题记录:
## {中文专题名}(专题)
- 模块根:{path}
- 生成日期:{date} git commit:{hash}(资产基线,见 Step 4.5 新鲜度检查)
- 匹配关键词:{关键词1}, {关键词2}, ...(8~15 个,中英混合)
- 专题层:T0-专题总览, T1-跨专家契约(或「暂无」)
- 专家清单:
- {专家1名}({一句话职责})
- 匹配关键词:{该专家的关键词}
- 契约层:C0-使用总览, C1-能力契约, ...
- 实现层:implementation/01-架构, 02-实现, ...
- 子专家(如有):{子专家1名}({职责}), {子专家2名}({职责})
- {专家2名}({一句话职责})
- ...
旧版 INDEX 记录可能无「匹配关键词」行——不阻塞匹配,降级用专家名/模块根/文档名匹配;命中后可在 Step 8 为其补建关键词行。旧记录无 git commit 行时同样降级——跳过 Step 4.5 基线检查,不阻塞。
Step 3:关键词匹配(专家/专题级粗筛,含子专家)
将 Step 1 的关键词与 INDEX.md 中每条记录的匹配关键词字段 / 专家名 / 专题名 / 模块根 / 契约层 / 专题层 / 实现层文档 / 子专家名 / 专题下专家名进行匹配:
匹配规则:
- 匹配关键词字段优先:关键词命中记录的「匹配关键词」字段(含近义包含,如"通知发送"命中"通知")——这是主匹配面,每命中一个关键词计一次
- 精确匹配:关键词与专家名 / 专题名 / 模块根 / 子专家名完全一致
- 包含匹配:当前关键词包含某记录的专家名 / 专题名 / 模块根 / 子专家名
- 多关键词命中:命中的关键词越多,匹配度越高
- 子专家匹配:关键词命中子专家名、子专家职责描述或子专家关键词时,该子专家为候选
- 专题下专家匹配:关键词命中专题记录中的专家名或其关键词时,该专家为候选(路径:
{专题名}/{专家名})
匹配结果:
- 高匹配:命中 2 个以上关键词 → 强候选
- 中匹配:命中 1 个关键词 → 弱候选
- 无匹配:未命中任何关键词 → 无现成专家
一个父专家下可能有多个子专家同时命中——均列为候选,Step 5 可多专家加载。 一个专题下可能有多个专家同时命中——均列为候选,Step 5 可多专家加载。命中专题本身时,先加载 T0 了解全局,再按需深入具体专家。
Step 4:读 agent.md / topic.md 核对(必须实读,逐个核对)
对 Step 3 命中的候选(专家/专题/子专家),按匹配度从高到低逐个核对:
候选为专家/子专家时——读 agent.md:
- 必须实读该候选的
agent.md全文(专题下专家路径:{专题名}/{专家名}/agent.md;子专家路径:{专家名}/sub-experts/{子专家名}/agent.md):- 一句话职责:负责的业务领域
- 负责的模块:模块根路径与职责
- 何时找这个专家:典型使用场景
- 契约层就绪:C0+C1 / C0+C1+C2+C3+C4 / 暂无
- 测试状态(如有):测试目录位置 + 测试可执行性(✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行 / 无测试)+ known-failures 引用
- 所属专题(如有):专题名 + T0 链接
- 子专家清单(父专家):子专家名 + 职责 + 功能子域
- 包含的资产:契约层 + 实现层文档清单
候选为专题时——读 topic.md:
- 必须实读该候选的
topic.md全文(路径:{专题名}/topic.md):- 一句话职责:该专题覆盖的超大模块/业务域
- 专题范围:模块根路径与功能域划分
- 何时找这个专题:典型使用场景
- 专家清单:专家名 + 一句话职责 + 契约层就绪状态
- 专题就绪:T0 就绪 / T0+T1 就绪 / 暂无
- 包含的资产:T0-专题总览(+ T1-跨专家契约 如有)+ 专家清单
共同核对流程:
- 核对是否覆盖当前需求:将当前问题与"一句话职责 / 负责的模块 / 何时找这个专家/专题"比对
- agent.md / topic.md 不存在、为空或缺关键字段 → 跳过并记录原因
- 符合 → 标记为采用候选
- 不符合 → 跳过,继续核对下一个
- 核对完毕,按结果分流:
- 1 个符合 → 进入 Step 5 单专家/专题加载
- 多个符合 → 进入 Step 5 多专家协同加载(最多取前 3 个,按匹配度排序)
- 0 个符合 → 进入 Step 5「未采用任何专家时」
专题命中后的深入:如果命中的是专题,且任务需要具体专家的能力,在 Step 5 中先加载 T0 了解全局,再根据 T0 中的专家导航深入具体专家的契约层。
Step 4.5:资产新鲜度检查(资产基线 commit 比对)
候选核对通过后、加载资产前,检查资产是否可能过期:
- 读取基线:从 INDEX 记录(或 agent.md 出处行)读取
git commit——资产基线 = 创建/全量更新时代码的 commit(由 expert-team 维护,语义见 expert-team「文档说明·资产基线 commit」) - 比对 HEAD:
git rev-parse HEAD与基线比较- 相同 → 资产基线与当前代码一致,正常进入 Step 5
- 不同 → 统计落后数量(
git rev-list --count {基线}..HEAD)并定位变更:git diff --name-only {基线}..HEAD -- {模块根}- 无变更文件 → 基线后的变更不涉及该模块,资产仍有效,正常进入 Step 5
- 有变更文件 → 向用户声明:「{专家名} 资产基线落后 {N} 个 commit,模块内 {M} 个文件有变更」并列出变更文件清单,清单带入 Step 5 使用;Step 5.1 判定为深度意图(诊断/修改/扩展)时按 diff 文件清单定向核对契约(精确命中"该改哪几条",替代全量读代码核对),使用/调用意图可先正常加载、遇到可疑处再按清单核对
- 降级规则(任一命中即跳过本检查,不阻塞):
- 非 git 仓库或 git 命令不可用
- INDEX 记录与 agent.md 出处行均无 commit 基线(旧资产)
- 用户级
~/.module-experts/专家(不受版本控制,无可比基线)
基线刷新归属:仅 expert-team 创建/全量更新(合并补全/重建)时刷新基线;本 skill 增量更新不刷新基线——增量只核对本次遇到的差异,推进基线会掩盖其余未核对变更,靠每次使用前的本检查持续兜底。
Step 5:多专家加载 + 按意图分层 + 变身求解
Step 5.1:判断使用意图
从当前任务中推断使用意图(AI 自动推断,向用户声明,用户可纠正):
候选为专家/子专家时:
| 意图 | 判定信号 | 加载资产 |
|---|---|---|
| 使用/调用模块 | "调用""使用""集成""对接""怎么用模块X做Y" | 契约层:C0 + C1(按需 C2/C3;写入类调用按需加载 C4 理解数据去向与业务后果),不需要 implementation/ |
| 诊断/排查 | "为什么不""报错""排查""异常""不触发" | C0 + 已知坑 + implementation/03-数据流转(导航:追踪数据流路径)+ 按需读源代码确认;数据类问题(数据丢失/不一致/写了没生效)先加载 C4 沿消费链定位;测试侧问题(测试失败/不通过/CI 红)加载 06-测试.md + test/known-failures.md(测试位置/可执行性/已知失败)——若 PROJECT.md 标注该服务「❌ 无法运行 / 无测试」则跳过测试加载 |
| 修改/扩展模块 | "修改""扩展""重构""新增功能到模块X" | C0(了解能力边界)+ implementation/01-架构+02-实现(导航:知道去哪改)+ 读源代码修改 |
| 意图不明确 | 无法判断 | 默认加载 C0(使用总览),让用户确认方向 |
候选为专题时:
| 意图 | 判定信号 | 加载资产 |
|---|---|---|
| 了解专题全局 | "支付系统整体""专题概览""跨专家架构" | T0-专题总览(跨专家架构图 + 专家导航),按需 T1 |
| 使用/调用专题下某专家 | "调用支付流程""使用退款功能" | T0(快速定位到哪个专家)→ 该专家的 C0 + C1 |
| 诊断/排查专题下某专家 | "支付流程为什么不触发""退款报错" | T0(定位专家)→ 该专家的 C0 + 已知坑 + implementation/03 + 按需读源代码 |
| 跨专家问题 | "支付到退款的数据流""支付和退款的一致性" | T0(跨专家架构图)+ 涉及的多个专家的 C0(多专家协同模式) |
| 意图不明确 | 无法判断 | 默认加载 T0(专题总览),让用户确认方向 |
三层递进:契约层用于"使用"(不需要看代码);
implementation/用于"导航"(深入模块前先看架构/数据流,知道去哪读代码);源代码用于"确认"(实际改代码时读具体文件)。三者递进不竞争。专题的递进:T0 用于"了解全局"(跨专家架构 + 专家导航)→ 专家的 C0/C1 用于"使用具体能力"→ 专家的 implementation/ 用于"导航代码"→ 源代码用于"确认"。专题不替代专家,而是提供跨专家的全局视角。
降级处理:旧专家无契约层(仅有 implementation/01-架构.md~`07-运维.md`,无根目录 C0/C1):
- 提示用户"该专家未含契约层,将加载实现文档,建议用 expert-team 补全契约层"
- 按原有方式加载实现层文档,不阻塞使用
Step 5.2:单专家 vs 多专家协同
单专家(仅 1 个符合):
- 按意图加载该专家资产
- 声明「已切换为 {专家名} 视角,识别为{意图}类任务,已加载{资产清单}」
- 基于专家资产直接求解
多专家协同(多个符合,最多取前 3 个):
两种模式,根据任务耦合度自动选择:
| 模式 | 适用场景 | 判断启发式 | 做法 |
|---|---|---|---|
| 协同模式 | 任务需要跨域知识交叉推理 | 任务需要"边查A边查B交叉推理" | 主 agent 同时加载多个专家的契约层,综合使用所有域的知识求解 |
| 并行模式 | 任务有独立的域特定子任务 | 任务可以"各自独立完成再汇总" | 用 task-dispatch 为每个专家派一个子 agent,各干各的,主 agent 整合 |
- 默认优先协同模式(加载多个契约层到主 agent 上下文,成本低)
- 当子任务明确独立且工作量较大时切换并行模式
- 上下文预算:加载前估算总 token 数,若 3 个专家的 C0+C1 加起来过大(如超过上下文窗口的 30%),降级为只加载 C0(总览)+ 按需精读 C1 条目,或切换并行模式
- 向用户声明「已加载 {N} 个专家:{专家清单},采用{协同/并行}模式」
多专家加载示例:
任务:"告警不触发时查日志"
→ 命中:告警处理专家 + 日志查询专家(2个,≤3 ✅)
→ 意图:诊断(告警)+ 使用(日志查询)
→ 协同模式:主 agent 同时加载
- 告警处理专家的 C0 + 已知坑
- 日志查询专家的 C0 + C1
→ 主 agent 综合两个专家的知识排查,必要时读实际源代码
Step 5.3:求解流程
- 加载专家资产(按意图 + 单/多专家模式)
- 向用户声明加载情况
- 基于专家资产直接解决问题
- 求解过程中注意 C0 中的"已知问题""常见坑"
- 若契约不够用 → 按"导航→确认"递进:先看 implementation/ 对应文档(如 03-数据流转追踪路径),再读具体源代码确认
- 若求解中发现契约与实际代码不一致或缺漏 → 进入 Step 6 增量更新
- 若求解中发现需要其他未加载专家的领域 → 回到 Step 2 查找并加载(动态扩展,但总加载专家数不超过 3 个)
未采用任何专家时:
- 告知用户未找到匹配的专家资产
- 不使用专家,正常排查 / 阅读代码
- 可先用代码索引兜底:仓库已有
.fe-index/时,use_skill("index-lookup")拿该模块边界 / 依赖 / 数据表(后端)或页面 / 接口(前端)缩小排查域;索引只给"去哪看",结论仍回源码确认;无索引 / 未命中 / 过期 → 照常直读,不阻塞 - 排查解决后,可建议使用
expert-team沉淀该模块专家资产包;若目标模块属公共 / 横切知识(工具库、通用封装、代码风格约定等),不建专家,推荐存入项目记忆
Step 6:增量更新——资产自我维护(使用中发现不一致时)
当求解过程中进入代码理解阶段,发现实际代码与契约层或其他文档存在不一致或不够详细时,触发增量更新。
Step 6.1:权限边界(受限增量更新)
| 操作 | 允许 | 说明 |
|---|---|---|
| 修正单条契约的参数/返回/异常字段 | ✅ | 字段级修正 |
| 补充单条契约缺失的约束/前置条件 | ✅ | 补充 |
| 补充/修正代码示例 | ✅ | 使示例更真实完整 |
| 新增一条已知坑 | ✅ | 追加到 C0 |
| 新增一条使用流程 | ✅ | 追加到 C2 |
| 新增一个遗漏的公开方法契约 | ✅ | 补充到 C1(标注"增量补充") |
| 补充/修正 C4 数据实体的消费方或用途条目 | ✅ | 条目级补充/修正(如验证了「基于引用扫描」的消费方、发现新消费方) |
追加/更新 test/known-failures.md 条目 |
✅ | 使用中发现测试失败/已知问题时写入(切面级,必须含执行方式——运行该测试的完整命令,供 code-review 阶段 8 复用) |
修正/补充 06-测试.md 测试可执行性条目 |
✅ | 运行命令/环境依赖/可执行性状态(已验证的修正) |
| 追加匹配关键词到 INDEX.md(只增不删) | ✅ | Step 8 自动执行,无需确认 |
修正/补充 PROJECT.md 全局条目(服务清单/代码位置/配套关系/技术栈) |
✅ | 使用中发现全局信息变化时(已验证的修正,粒度止于服务级) |
| 同步/修正 ki 专题记忆的路标字段(核心能力/高频坑/关键代码位置/数据落地) | ✅ | 使用中确认与资产不一致时(字段级,与 expert-team Step 8 的 8 字段对齐;职责/路径大改走 expert-team) |
| 删除整条契约 | ❌ | 走 expert-team |
| 重写整篇文档 | ❌ | 走 expert-team |
| 新增/删除切面文件 | ❌ | 走 expert-team |
| 修改 agent.md 专家职责 | ❌ | 走 expert-team |
安全机制:
- 单次增量更新不超过 5 条修正/补充
- 即时更新需向用户声明并征求确认
- 更新不单独记录——资产随项目版本控制,git 历史即变更记录
- 并发保护:同一专家同时只允许一个更新者;多专家并行模式下各子 agent 只更新各自专家的资产,不交叉更新
- 基线不推进:增量更新不刷新资产基线 commit(仅 expert-team 创建/全量更新时刷新),防止未核对的代码变更被基线掩盖;过期检测由每次使用前的 Step 4.5 持续兜底
Step 6.2:触发分级
| 级别 | 判定标准 | 处理方式 |
|---|---|---|
| 即时(P0) | 照契约使用一定出错:参数类型/数量不符、返回结构不符、方法不存在、约束缺失导致必踩坑 | 求解中暂停,向用户声明并征求确认后修正,继续求解 |
| 延迟(P1) | 契约能用但不完整:缺可选参数说明、缺边界值行为、缺使用流程、发现新坑、代码示例不够真实 | 求解完成后汇总,批量补充,展示清单 |
| 疑似(P2) | AI 对差异理解不确定 | 不自动改,在对应契约条目处内联标注 ⚠️ [疑似与代码不一致,待确认](见「疑似差异内联标注格式」) |
Step 6.3:执行流程
- 求解中读到实际代码行为
- 与已加载契约比对
- 发现差异 → 定级
- 即时级:暂停 → 声明并确认 → 修正契约 → 继续
- 延迟级:记录 → 继续 → 完成后批量补充 → 展示清单
- 疑似级:在契约条目处内联标注
⚠️ [疑似与代码不一致,待确认]→ 不改契约内容本身 → 继续
Step 6.4:范围联动
契约修正时,判断差异来源:
- 代码变更导致契约过期 → 联动修正涉及的
implementation/文档对应条目 - 原始契约就写错 → 仅修契约
- 无法判断 → 仅修契约,并在该条目处标注「根因未确认」
Step 6.5:旧专家无契约层时
首次增量更新自动创建 C0-使用总览.md + C1-能力契约.md 骨架(放在专家根目录):
- 标注「由增量更新自动生成,未经 expert-team 全量校验,建议后续补全」
- 同步更新
agent.md的"契约层就绪"字段
Step 7:动态扩展(求解中发现需要其他专家时)
若求解过程中发现需要当前未加载的其他专家领域:
- 回到 Step 1 提取新的关键词(针对新发现的领域)
- Step 2-4 查找并核对新的候选专家
- 命中后加载到当前上下文(协同模式),或派子 agent(并行模式)
- 总加载专家数不超过 3 个——若已达上限,按匹配度替换最低的
- 继续求解
这与最初的多专家加载不同:Step 5 是初始就多专家,Step 7 是求解中动态发现需要扩展。
Step 8:关键词自动更新(求解结束时)
求解结束后,对本次实际使用过的每个专家/专题(含子专家),对比 Step 1 提取的任务关键词与其 INDEX 记录的「匹配关键词」列表:
- 筛选新关键词:本次任务关键词中,与该专家职责相关(确实因它命中/使用了该专家)但不在其「匹配关键词」列表中的词
- 自动追加:追加到
INDEX.md对应记录的「匹配关键词」行(只增不删,单次每条记录 ≤ 5 个;单条记录总量软上限 30 个,达到后不再自动追加,提示走 expert-team 重整关键词) - 旧记录补建:记录无「匹配关键词」行时(旧版 INDEX),基于专家名/职责/本次命中词补建该行(8~15 个)
- 去重与质量:追加前去重(含近义重复,如已有"告警"不再追加"告警系统",除非有区分价值);不追加与专家职责无关的任务噪声词(如"排查""帮我")
- 静默执行:关键词追加属白名单低风险操作(见 Step 6.1),无需用户确认,完成后一句话带过(如「已为 {专家名} 追加关键词:xxx, yyy」)
目的:使用即维护——每次真实使用都让 INDEX 的匹配面更贴近真实提问方式,持续提升后续匹配命中率。
查找策略
遇到业务模块任务时的查找顺序
1. 提取需求关键词
2. 查 expert-lookup(本 skill)
→ 读取 PROJECT.md 获取项目全局上下文(Step 1.5,缺失则提示不阻塞)
→ 命中专题 → 先加载 T0-专题总览,再按需深入专题下专家
→ 命中多个专家 → 多专家协同加载(Step 5,最多3个)
→ 命中单个专家 → 单专家按意图加载(Step 5)
→ 命中后先做新鲜度检查(Step 4.5):比对资产基线 commit 与 HEAD,基线落后时 diff 定位模块内变更文件,深度意图定向核对
→ 求解中契约不够 → 先看 implementation/ 导航代码路径,再读源代码确认
→ 求解中发现不一致 → 增量更新(Step 6)
→ 求解中发现需要其他领域 → 动态扩展(Step 7,总数≤3)
→ 求解结束 → 关键词自动更新(Step 8,只增不删)
3. 查 solution-lookup → 有则复用具体问题解法
4. 查 ki 专题记忆(expert-team Step 8 落盘的路标)→ 调用 `use_skill("ki-memory-lookup")` 的专题记忆策略检索,命中即知晓"有此专家 + 关键入口"
→ **跳转前校验目标专家路径存在**(`.module-experts/{名}/` 真实存在);路径失效 → 记忆已过时,不做误导性跳转,回退 Step 5 正常查找,并按需清理/更新记忆
→ 路径有效 → 据此跳回本 skill 加载对应专家资产(若记忆已含答案且无需深挖,可直接参考记忆,不强制加载专家)
→ 命中记忆但无对应专家资产(僵尸记忆)→ 提示并清理该记忆
→ 存量专家无记忆(旧资产未落盘记忆)→ 首次命中时提示可用 expert-team 补建专题记忆(可选,不阻塞)
→ 使用中确认记忆路标字段与资产不符 → 同步修正(Step 6 权限内)
5. 查代码库 / 调 expert-team 创建专家资产
常见匹配场景
| 需求类型 | 关键词 | 命中专家/专题 | 意图 → 加载层 | 模式 |
|---|---|---|---|---|
| 使用模块完成某事 | 模块名、调用 |
同名专家 | 使用 → C0+C1(不读 implementation/) | 单专家 |
| 排查告警不触发 | 告警、不触发 |
告警处理专家(或其子专家) | 诊断 → C0+已知坑+按需读代码 | 单专家 |
| 告警不触发时查日志 | 告警、不触发、日志、查询 |
告警处理专家 + 日志查询专家(2个) | 诊断+使用 → 混合 | 多专家协同 |
| 新增业务规则到模块 | 模块名、新增 |
该模块专家 | 修改 → C0+按需读代码 | 单专家 |
| 排查数据写入后丢失/没生效 | 数据、丢失、没生效 |
该模块专家 | 诊断 → C0+C4(消费链)+implementation/03 | 单专家 |
| 跨模块功能对接 | 模块A、模块B、对接 |
模块A专家 + 模块B专家(2个) | 使用 → C0+C1 | 多专家协同 |
| 了解支付系统整体 | 支付系统、整体、架构 |
支付系统专题 | 了解全局 → T0-专题总览 | 单专题 |
| 排查支付流程问题 | 支付、支付流程、不触发 |
支付系统专题 → 支付流程专家 | 诊断 → T0(定位)+ 该专家 C0+已知坑+按需读代码 | 专题→专家 |
| 支付到退款的数据流 | 支付、退款、数据流 |
支付系统专题 → 支付流程专家 + 退款专家 | 跨专家 → T0 + 多专家 C0 | 多专家协同 |
疑似差异内联标注格式
疑似(P2)差异不修改契约内容,在对应契约条目末尾追加内联标注:
> ⚠️ [疑似与代码不一致,待确认] {date}:{一句话差异描述,如"代码中返回类型疑为 Optional<List>,与本条约定的 List 不符"}
后续确认:属实 → 按 Step 6 修正契约并移除标注;不属实 → 直接移除标注。
输出格式
找到专家/专题
## 查找到业务专家/专题
**匹配类型**:专家 / 专题
**匹配名称**:{专家1名}(+ {专家2名},... 如多专家,最多3个)/ {专题名}
**存储层级**:项目级 / 用户级
**匹配关键词**:{命中的关键词}
**识别意图**:使用/调用 | 诊断/排查 | 修改/扩展 | 了解全局 | 跨专家 | 待确认
**加载模式**:单专家 / 多专家协同 / 多专家并行 / 专题→专家
**加载资产**:{按意图加载的资产清单}
**项目全局上下文**:{PROJECT.md 存在/缺失;已加载/未加载}
**路径**:{专家/专题目录路径}
### 专家概要(候选为专家时)
- 一句话职责:{agent.md 中职责}
- 契约层就绪:是(C0+C1+C2+C3+C4)/ 部分 / 否
- 测试状态:{✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行 / 无测试}(有测试时含 known-failures 引用)
- 所属专题(如有):{专题名}
- 子专家:{子专家清单或「无」}
- 负责的模块:{模块根} — {职责}
- 何时找他:{典型场景}
### 专题概要(候选为专题时)
- 一句话职责:{topic.md 中职责}
- 专题就绪:T0 就绪 / T0+T1 就绪 / 暂无
- 专家清单:{专家名 + 一句话职责}
- 专题范围:{模块根} — {功能域划分}
- 何时找它:{典型场景}
### 包含的资产
- 专家:契约层 C0~C4 + 实现层 implementation/01~07(或「暂无」)
- 专题:T0-专题总览(+ T1-跨专家契约 如有)+ 专家清单
是否深入阅读某文档,或需要动态扩展其他专家?[列出可选项]
未找到专家
## 未找到匹配的业务专家
已搜索:
- 项目级 .module-experts/INDEX.md({N} 位专家)
- 用户级 ~/.module-experts/INDEX.md({M} 位专家)
提取的关键词:{关键词列表}
未命中任何专家资产包。可使用 expert-team 为「{目标模块}」生成专家资产包(若属公共 / 横切知识如工具库、代码风格约定,则不建专家,存入项目记忆)。
与相邻 skill 的边界
| skill | 关系 |
|---|---|
| expert-team | 本 skill 查找其产出的专家/专题资产(含契约层 + 实现层 + test/known-failures.md + 专题层);找不到时建议调用它创建。本 skill 可对契约层与测试信息(known-failures/06-测试可执行性)做受限增量更新,大改仍走 expert-team。项目全局资产 PROJECT.md 由 expert-team 首次创建、本 skill 与 expert-team 共同维护(使用中发现全局信息变化时受限更新) |
| code-review | 与 code-review 阶段 8 共用 test/known-failures.md:本 skill 使用中发现测试问题时写入;阶段 8 单测失败无法低成本修复时也写入;修复后任一方移除对应条目 |
| solution-lookup | 互补:本 skill 查"业务领域专家(模块知识包)",solution-lookup 查"问题解法 skill" |
| code-survey | 互补:本 skill 复用既有深度资产;无资产时可先走 code-survey 轻量调研 |
index-lookup(+ frontend-index / backend-index) |
互补:专家资产答"是什么 / 怎么用"(模块级,覆盖稀疏);代码索引答"去哪看 / 动了谁"(全量、可随时重建)。未命中专家资产时先用索引拿模块边界 / 依赖作兜底线索(见"未采用任何专家时"第 3 条) |
| task-dispatch | 多专家并行模式时,用其创建基于不同专家资产的子 agent 并行工作 |
行为边界
- 查找非阻塞:找不到专家/专题不阻塞后续工作
- 多专家协同:任务涉及多域时可同时加载多个专家,最多3个;紧耦合用协同模式,松耦合用并行模式
- 三层递进:契约层用于"使用"(不需要看代码);implementation/ 用于"导航"代码(深入模块前先看地图);源代码用于"确认"行为(实际改代码时读具体文件)。三者递进不竞争
- 专题支持:查找时同时匹配专题与专家;命中专题时先加载 T0 了解全局,再按需深入专题下具体专家的契约层;专题路径为
{专题名}/{专家名}/agent.md - 受限增量更新:仅允许补充/修正单条契约或流程条目(含代码示例),禁止删除/重写整篇、新增/删除切面文件、修改 agent.md/topic.md 职责;大改走 expert-team
- 并发保护:同一专家同时只允许一个更新者;多专家并行模式下各子 agent 只更新各自专家的资产
- 即时更新需确认:即时级(P0)修正需向用户声明并征求确认
- 单次上限:单次增量更新不超过 5 条修正/补充
- 更新可追溯:资产随项目版本控制,增量更新通过 git 历史追溯,不单独记录;疑似差异在契约条目处内联标注
- 项目级优先:同时命中时,项目级专家/专题优先于用户级
- 必须实读:不能仅凭 INDEX.md 标题就断言命中
- 子专家匹配:查找时同时匹配父专家与子专家;子专家匹配更精准时优先加载子专家
- 测试信息切面级:测试可执行性/known-failures 按子专家/功能域各自标注(父专家汇总);诊断/排查测试侧问题时按命中切面加载对应测试信息
- known-failures 维护:仅允许追加/更新/移除条目(Step 6 权限内),不做历史归档;修复后移除对应条目;与 code-review 阶段 8 共用同一文件
- 符号导航:实现层文档以关键符号(类名 / 方法名 / 类.方法)标注来源,定位时直接 grep/LSP 搜索符号;符号因重命名失效时回退全文搜索。旧版文档中残留的
#Lx-Ly行号为生成时快照,不可信任——无论哪种标注,implementation/ 均用于“导航”而非“确认”,确认行为以源代码为准 - 用户级为可选扩展:通常为空,勿因用户级为空而误判"无专家"
- 变身不篡改资产:变身为目标专家/专题仅加载其资产用于求解;增量更新仅限契约层受限范围
- 子 agent 只读:并行模式派生的子 agent 只读取其所基于的专家资产,不修改
- 关键词只增不删:Step 8 关键词自动更新只追加不删除,单次每条记录 ≤ 5 个(单条记录总量软上限 30 个),不追加与专家职责无关的噪声词
- PROJECT.md 共享维护:查找/使用前先读(存在则加载校准,缺失则提示不阻塞);使用中发现全局信息变化(新服务/代码位置不符)时受限更新(Step 6 权限内);粒度止于"服务 → 代码位置 → 一句话职责",不写契约/实现细节
- 专题记忆同步:expert-team 落盘专家后写 ki 专题记忆(8 字段路标);本 skill 使用中可受限修正其路标字段(Step 6 权限内,字段级),职责/路径大改走 expert-team;记忆只存路标不存专家本体,避免双源漂移;修正记忆时遵守 ki-memory-write 的格式硬约束(禁用 yaml 元数据、
##/###等 md 标题,统一纯文本 +-列表,防污染 ki-search 检索) - 记忆路径校验:命中记忆后跳转前先校验目标专家路径真实存在;路径失效/僵尸记忆则不做误导性跳转、回退正常查找并清理;存量专家无记忆时首次命中可提示补建(可选不阻塞)
- 资产新鲜度检查:命中专家后执行基线 commit 比对(Step 4.5),基线落后时 diff 定位模块内变更文件并按意图定向核对;降级条件(非 git / 无基线 / 用户级)命中即跳过不阻塞;增量更新不推进基线
更多资源
- 专家资产的生成与结构规范(含子专家机制),参见
use_skill("expert-team") - 契约层文档模板(C0/C1/C2/C3/C4)与 CR1-CR9 规则、实现层切面 Wiki 格式,参见
use_skill("expert-team")→ 其reference.md - 项目全局资产(PROJECT.md)模板独立存储,参见
use_skill("expert-team")→ 其templates/PROJECT.md.template(了解 PROJECT.md 应包含的字段与结构) - 多专家并行模式创建子 agent 的调度能力,参见
use_skill("task-dispatch")