Expert Lookup

---
name: expert-lookup
description: 查找并复用已沉淀的"业务专家"资产包（由 expert-team 生成，落盘于 .module-experts/）。通过 INDEX.md 的匹配关键词提升命中率，并在使用中自动追加新关键词。支持多专家同时加载（最多3个），按使用意图分层加载（使用→契约层，深入→实现层+源码）。支持子专家查找和专题查找（专题→专家→子专家三级结构），使用中发现不一致时可受限增量更新契约层。触发短语："有没有这个模块的专家"、"找一下告警相关的专家"、"这个模块有现成资料吗"、"查专家"、"expert lookup"，或在 AI 接手某业务模块、排查某领域问题时自动触发。
---

# 业务专家查找

## 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-使用总览.md`~`C3-代码示例-{topic}.md`、`C4-数据流向与消费.md`）+ `implementation/`（实现层：`01-架构.md`~`07-运维.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-跨专家契约 如有）+ 专家清单

**共同核对流程**：

2. **核对是否覆盖当前需求**：将当前问题与"一句话职责 / 负责的模块 / 何时找这个专家/专题"比对
   - **agent.md / topic.md 不存在、为空或缺关键字段** → 跳过并记录原因
   - **符合** → 标记为采用候选
   - **不符合** → 跳过，继续核对下一个
3. 核对完毕，按结果分流：
   - **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. 排查解决后，可建议使用 `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）差异不修改契约内容，在对应契约条目末尾追加内联标注：

```markdown
> ⚠️ [疑似与代码不一致，待确认] {date}：{一句话差异描述，如"代码中返回类型疑为 Optional<List>，与本条约定的 List 不符"}
```

> 后续确认：属实 → 按 Step 6 修正契约并移除标注；不属实 → 直接移除标注。

## 输出格式

### 找到专家/专题

```markdown
## 查找到业务专家/专题

**匹配类型**：专家 / 专题
**匹配名称**：{专家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-跨专家契约 如有）+ 专家清单

是否深入阅读某文档，或需要动态扩展其他专家？[列出可选项]
```

### 未找到专家

```markdown
## 未找到匹配的业务专家

已搜索：
- 项目级 .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 轻量调研 |
| 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")`