expert-lookup

查找并复用已沉淀的"业务专家"资产包(.module-experts/):按使用意图分层加载(使用 → 契约层,深入 → 实现层 + 源码),支持子专家与专题查找。触发:"有没有这个模块的专家"、"查专家"、"expert lookup",或 AI 接手/排查某业务模块时。

SKILL.md

GitHub

业务专家查找

AI 说明层

目的:在 AI 或用户需要了解/使用某个业务模块时,快速查找是否已有沉淀的"业务专家"资产包,支持多专家同时加载协同工作(最多3个),按使用意图分层加载避免无谓读实现代码,并在使用中发现契约过期或缺漏时增量更新资产(即时级需用户确认),形成"使用即维护"的闭环。支持专题(专题→专家→子专家三级结构)的查找和加载。同时关注测试健康度——加载测试信息(测试位置/可执行性/已知失败),支持排查测试侧问题与维护 known-failures。

功能:

  1. 查找专家/专题:读取 INDEX.md → 关键词匹配(含 INDEX 中的匹配关键词字段、子专家、专题下专家)→ 读 agent.md(专家)或 topic.md(专题)确认 → 加载资产
  2. 多专家协同(最多3个):任务涉及多个域时,同时加载多个专家的契约层协同工作;独立子任务可并行派子 agent
  3. 按意图分层加载:使用/调用→契约层(根目录 C0~C4);诊断/排查→C0+已知坑+implementation/03-数据流转(导航)+读源代码确认,数据类问题(丢失/不一致/没生效)先看 C4 消费链;修改/扩展→C0+implementation/01-架构+02-实现(导航)+读源代码修改;专题→T0-专题总览(跨专家架构)+按需深入专家契约层
  4. 三层递进:契约层用于"使用"(不需要看代码);implementation/ 用于"导航"(深入模块前先看架构/数据流,知道去哪读代码);源代码用于"确认"(实际改代码时读具体文件)
  5. 增量更新:使用中发现契约与代码不一致→即时修正(严重)或延迟补充(轻微);疑似差异在契约条目处内联标注
  6. 关键词自动更新:求解结束时,若本次任务的关键词命中了专家但不在其 INDEX 关键词列表中,自动追加(只增不删,单次 ≤ 5 个),提升后续匹配率
  7. 测试健康度支持:诊断/排查意图时加载 06-测试.md 与 test/known-failures.md(测试位置/可执行性/已知失败),辅助判断问题是否来自测试侧;使用中发现测试失败或可执行性问题时可增量更新(Step 6 权限内)
  8. 专题记忆检索:查找顺序含"查 ki 专题记忆"(expert-team 落盘的路标),命中即知晓有此专家+关键入口;跳转前校验专家路径存在,失效回退正常查找;使用中可受限修正记忆路标字段(Step 6 权限内)
  9. 资产新鲜度检查:命中专家后比对资产基线 commit 与当前 HEAD(Step 4.5),基线落后时用 git diff --name-only {基线}..HEAD -- {模块根} 定位变更文件,判断资产是否过期并定向核对,替代全量读代码核对;基线不可用时降级跳过

使用场景:

  • AI 需要使用/调用某模块的能力完成任务(优先契约层,不读实现代码)
  • AI 接手 / 排查某个业务模块,需要先判断是否有现成专家资产可复用
  • 任务跨多个业务域,需要多专家(最多3个)同时协同
  • 需要了解超大模块的全局架构(命中专题,加载 T0-专题总览)
  • 用户问"有没有这个模块的专家""这个模块有现成资料吗""找一下告警相关的专家"
  • 找到专家后希望 AI 直接以专家身份接手解决当前问题
  • 需要使用子专家(父专家下某功能子域的专家)

核心原则

  1. 查找优先:接手业务模块 / 使用模块能力时,先查专家库,再从头读代码
  2. 双库搜索:同时查项目级和用户级,项目级优先
  3. 两级过滤:先用 INDEX.md 做专家/专题级粗筛,再读 agent.md(专家)或 topic.md(专题)做职责 / 场景精判
  4. 必须实读:不能仅凭 INDEX 标题就断言命中,必须读 agent.md(专家)或 topic.md(专题)获取职责与适用场景
  5. 多专家协同:任务涉及多个域时,同时加载多个匹配专家(最多3个)的契约层协同工作,不必只选一个
  6. 按意图分层加载:变身时根据使用意图决定加载契约层还是实现层
  7. 三层递进,各司其职:契约层(C0~C4)用于"使用"——知道怎么调用,不需要看代码;implementation/ 用于"导航"——深入模块(诊断/改造)时先看架构全貌、数据流、依赖关系,知道该去哪读代码,是代码的"地图",不替代代码但节省追踪时间;源代码用于"确认"——实际修改时读具体文件确认细节,永远权威。三者递进不竞争:用 → 导航 → 确认
  8. 结果非阻塞:找不到专家不阻塞后续工作,可建议用 expert-team 创建(公共 / 横切知识除外,转存项目记忆)
  9. 变身求解:找到目标专家后,自动加载相关资产并以专家视角直接着手解决问题
  10. 使用即维护:使用中发现契约与实际不一致或缺漏时,对契约层做受限增量更新,更新回流资产
  11. 子专家支持:查找时同时匹配父专家与子专家,子专家匹配更精准时优先加载子专家
  12. 专题支持:查找时同时匹配专题与专家;命中专题时先加载 T0-专题总览.md 了解跨专家架构,再按需深入专题下具体专家的契约层;专题下专家的查找路径为 {专题名}/{专家名}/agent.md
  13. 测试健康度关注:诊断/排查测试侧问题时加载测试信息(06-测试.md + test/known-failures.md),辅助判断问题是否来自测试侧;使用中发现测试问题可增量维护 known-failures
  14. 项目全局上下文:查找/使用前先读 .module-experts/PROJECT.md(如存在)获取项目全局信息(项目信息/技术栈/服务清单/配套关系/代码位置/运行环境),校准匹配意图,提升命中准确度;不存在时提示用户是否优先创建(走 expert-team),不阻塞查找
  15. 专题记忆检索:查找顺序含"查 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:

  1. 存在 → 读取 PROJECT.md,获取项目全局信息(项目信息/技术栈/架构形态/核心功能/核心服务清单含代码位置/配套服务关系/运行环境),用于校准 Step 3 的关键词匹配意图
  2. 不存在 → 提示用户「项目尚未创建 PROJECT.md 全局资产,是否优先创建(走 expert-team)?」——提示不阻塞查找,继续正常流程
  3. 使用中发现全局信息变化(如发现新服务/代码位置不符)→ 受限更新 PROJECT.md 对应条目(Step 6 权限内)
  4. 测试可执行性预判:PROJECT.md 服务清单中标注目标服务「❌ 无法运行 / 无测试」时,本次使用跳过该服务的测试侧加载(不加载 06-测试.md + test/known-failures.md,测试相关排查直接说明跳过);标注「✅ 可跑 / ⚠️ 依赖外部环境」时正常加载

Step 2:读取 INDEX.md

同时读取两个层级的 INDEX.md:

  1. 项目级:.module-experts/INDEX.md(不存在则 list_dir .module-experts/ 枚举专家子目录,逐个读 agent.md 作为粗筛来源)
  2. 用户级:~/.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:

  1. 必须实读该候选的 agent.md 全文(专题下专家路径:{专题名}/{专家名}/agent.md;子专家路径:{专家名}/sub-experts/{子专家名}/agent.md):
    • 一句话职责:负责的业务领域
    • 负责的模块:模块根路径与职责
    • 何时找这个专家:典型使用场景
    • 契约层就绪:C0+C1 / C0+C1+C2+C3+C4 / 暂无
    • 测试状态(如有):测试目录位置 + 测试可执行性(✅ 可跑 / ⚠️ 依赖外部环境 / ❌ 无法运行 / 无测试)+ known-failures 引用
    • 所属专题(如有):专题名 + T0 链接
    • 子专家清单(父专家):子专家名 + 职责 + 功能子域
    • 包含的资产:契约层 + 实现层文档清单

候选为专题时——读 topic.md:

  1. 必须实读该候选的 topic.md 全文(路径:{专题名}/topic.md):
    • 一句话职责:该专题覆盖的超大模块/业务域
    • 专题范围:模块根路径与功能域划分
    • 何时找这个专题:典型使用场景
    • 专家清单:专家名 + 一句话职责 + 契约层就绪状态
    • 专题就绪:T0 就绪 / T0+T1 就绪 / 暂无
    • 包含的资产:T0-专题总览(+ T1-跨专家契约 如有)+ 专家清单

共同核对流程:

  1. 核对是否覆盖当前需求:将当前问题与"一句话职责 / 负责的模块 / 何时找这个专家/专题"比对
    • agent.md / topic.md 不存在、为空或缺关键字段 → 跳过并记录原因
    • 符合 → 标记为采用候选
    • 不符合 → 跳过,继续核对下一个
  2. 核对完毕,按结果分流:
    • 1 个符合 → 进入 Step 5 单专家/专题加载
    • 多个符合 → 进入 Step 5 多专家协同加载(最多取前 3 个,按匹配度排序)
    • 0 个符合 → 进入 Step 5「未采用任何专家时」

专题命中后的深入:如果命中的是专题,且任务需要具体专家的能力,在 Step 5 中先加载 T0 了解全局,再根据 T0 中的专家导航深入具体专家的契约层。

Step 4.5:资产新鲜度检查(资产基线 commit 比对)

候选核对通过后、加载资产前,检查资产是否可能过期:

  1. 读取基线:从 INDEX 记录(或 agent.md 出处行)读取 git commit——资产基线 = 创建/全量更新时代码的 commit(由 expert-team 维护,语义见 expert-team「文档说明·资产基线 commit」)
  2. 比对 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 文件清单定向核对契约(精确命中"该改哪几条",替代全量读代码核对),使用/调用意图可先正常加载、遇到可疑处再按清单核对
  3. 降级规则(任一命中即跳过本检查,不阻塞):
    • 非 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 个符合):

  1. 按意图加载该专家资产
  2. 声明「已切换为 {专家名} 视角,识别为{意图}类任务,已加载{资产清单}」
  3. 基于专家资产直接求解

多专家协同(多个符合,最多取前 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:求解流程

  1. 加载专家资产(按意图 + 单/多专家模式)
  2. 向用户声明加载情况
  3. 基于专家资产直接解决问题
  4. 求解过程中注意 C0 中的"已知问题""常见坑"
  5. 若契约不够用 → 按"导航→确认"递进:先看 implementation/ 对应文档(如 03-数据流转追踪路径),再读具体源代码确认
  6. 若求解中发现契约与实际代码不一致或缺漏 → 进入 Step 6 增量更新
  7. 若求解中发现需要其他未加载专家的领域 → 回到 Step 2 查找并加载(动态扩展,但总加载专家数不超过 3 个)

未采用任何专家时:

  1. 告知用户未找到匹配的专家资产
  2. 不使用专家,正常排查 / 阅读代码
  3. 可先用代码索引兜底:仓库已有 .fe-index/ 时,use_skill("index-lookup") 拿该模块边界 / 依赖 / 数据表(后端)或页面 / 接口(前端)缩小排查域;索引只给"去哪看",结论仍回源码确认;无索引 / 未命中 / 过期 → 照常直读,不阻塞
  4. 排查解决后,可建议使用 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:执行流程

  1. 求解中读到实际代码行为
  2. 与已加载契约比对
  3. 发现差异 → 定级
  4. 即时级:暂停 → 声明并确认 → 修正契约 → 继续
  5. 延迟级:记录 → 继续 → 完成后批量补充 → 展示清单
  6. 疑似级:在契约条目处内联标注 ⚠️ [疑似与代码不一致,待确认] → 不改契约内容本身 → 继续

Step 6.4:范围联动

契约修正时,判断差异来源:

  • 代码变更导致契约过期 → 联动修正涉及的 implementation/ 文档对应条目
  • 原始契约就写错 → 仅修契约
  • 无法判断 → 仅修契约,并在该条目处标注「根因未确认」

Step 6.5:旧专家无契约层时

首次增量更新自动创建 C0-使用总览.md + C1-能力契约.md 骨架(放在专家根目录):

  • 标注「由增量更新自动生成,未经 expert-team 全量校验,建议后续补全」
  • 同步更新 agent.md 的"契约层就绪"字段

Step 7:动态扩展(求解中发现需要其他专家时)

若求解过程中发现需要当前未加载的其他专家领域:

  1. 回到 Step 1 提取新的关键词(针对新发现的领域)
  2. Step 2-4 查找并核对新的候选专家
  3. 命中后加载到当前上下文(协同模式),或派子 agent(并行模式)
  4. 总加载专家数不超过 3 个——若已达上限,按匹配度替换最低的
  5. 继续求解

这与最初的多专家加载不同:Step 5 是初始就多专家,Step 7 是求解中动态发现需要扩展。

Step 8:关键词自动更新(求解结束时)

求解结束后,对本次实际使用过的每个专家/专题(含子专家),对比 Step 1 提取的任务关键词与其 INDEX 记录的「匹配关键词」列表:

  1. 筛选新关键词:本次任务关键词中,与该专家职责相关(确实因它命中/使用了该专家)但不在其「匹配关键词」列表中的词
  2. 自动追加:追加到 INDEX.md 对应记录的「匹配关键词」行(只增不删,单次每条记录 ≤ 5 个;单条记录总量软上限 30 个,达到后不再自动追加,提示走 expert-team 重整关键词)
  3. 旧记录补建:记录无「匹配关键词」行时(旧版 INDEX),基于专家名/职责/本次命中词补建该行(8~15 个)
  4. 去重与质量:追加前去重(含近义重复,如已有"告警"不再追加"告警系统",除非有区分价值);不追加与专家职责无关的任务噪声词(如"排查""帮我")
  5. 静默执行:关键词追加属白名单低风险操作(见 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")