Solution Lookup

---
name: solution-lookup
description: 查找并复用已沉淀的解决方案 skill（项目级 .solutions/ 与用户级 ~/.solutions/，按 INDEX.md 关键词匹配，加载后按其步骤执行）。触发："有没有类似解决方案"、"之前怎么解决的"、"查找解决方案"、"solution lookup"，或遇到调试/配置/部署等问题时。
---

# 解决方案查找

## 概述

**目的**：在 AI 遇到问题时，快速查找是否已有沉淀的解决方案，避免重复踩坑，直接复用已有经验。

**功能**：读取项目级和用户级的 INDEX.md → 关键词匹配 → 加载对应解决方案 skill → 按步骤复用。

**使用场景**：
- AI 遇到调试、配置、部署等非平凡问题时
- AI 开始排查错误前，先查是否有现成方案
- 用户说"有没有类似解决方案"、"之前怎么解决的"、"查找解决方案"时
- 用户遇到一个似曾相识的问题时

## 核心原则

1. **查找优先**：遇到非平凡问题时，先查解决方案库，再开始从头排查
2. **双库搜索**：同时查项目级和用户级，项目级优先
3. **关键词匹配**：通过 INDEX.md 的触发关键词匹配当前问题
4. **直接复用**：找到匹配方案后，加载 SKILL.md 按步骤执行，而非仅作参考

## 存储位置

| 层级 | 路径 | 说明 |
|------|------|------|
| 项目级 | `.solutions/` | 与当前项目相关的解决方案，跟项目版本控制 |
| 用户级 | `~/.solutions/` | 跨项目通用的解决方案 |

两个层级各自维护独立的 `INDEX.md`。

## 执行流程

### Step 1：提取当前问题的关键词

从当前问题中提取搜索关键词：

- **技术栈关键词**：涉及的技术、框架、库（如 `jwt`、`nginx`、`docker`）
- **问题症状关键词**：错误现象、报错信息中的关键术语（如 `过期`、`跨域`、`OOM`）
- **操作关键词**：正在进行的操作类型（如 `部署`、`配置`、`调试`）

提取 3-6 个关键词。

### Step 2：读取 INDEX.md

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

1. **项目级**：`.solutions/INDEX.md`（可能不存在，不存在则跳过）
2. **用户级**：`~/.solutions/INDEX.md`（可能不存在，不存在则跳过）

### Step 3：关键词匹配

将提取的关键词与 INDEX.md 中每条记录的"触发关键词"字段进行匹配：

**匹配规则**：
- 精确匹配优先：关键词完全一致
- 包含匹配：当前问题关键词包含某条记录的触发关键词
- 多关键词命中：命中的关键词越多，匹配度越高

**匹配结果**：
- **高匹配**：命中 2 个以上关键词 → 强烈推荐
- **中匹配**：命中 1 个关键词 → 建议参考
- **无匹配**：未命中任何关键词 → 无现成方案

### Step 4：加载解决方案

对于匹配的解决方案：

1. 读取对应目录下的 `SKILL.md`
2. 读取 `scripts/` 下的脚本（如有）
3. 读取 `reference.md`（如有且需要更多细节）

### Step 5：复用方案

**找到匹配方案时**：

1. 向用户展示匹配的解决方案概要：
   ```
   找到匹配的解决方案：

   【项目级】jwt-token-expiry — JWT Token 过期时间设置
   匹配关键词：jwt, token, 过期
   路径：.solutions/debugging/jwt-token-expiry/

   是否按此方案执行？
   ```

2. 用户确认后，按 SKILL.md 中的解决方案步骤执行
3. 执行过程中注意 SKILL.md 中的"注意事项"
4. 如方案不完全适用，结合实际情况调整

**未找到匹配方案时**：

1. 告知用户未找到现成方案
2. 正常排查问题
3. 排查解决后，可建议使用 `solution-capture` 沉淀方案

## 查找策略

### 遇到错误时的查找顺序

```
1. 提取错误信息关键词
2. 查 solution-lookup（本 skill）→ 有则复用
3. solution-lookup 命中率低（报错文本变体多，INDEX.md 关键词匹配易漏）→ 先贴报错原文查 ki 错误库（use_skill("ki-memory-lookup") 错误库策略，整段堆栈语义命中）→ 有则复用
4. 查 ki 记忆索引 → 有则参考
5. 查代码库 → 有则定位
6. 从头排查
```

### 常见匹配场景

| 问题类型 | 提取关键词示例 | 可能命中的分类 |
|----------|---------------|---------------|
| 报错排查 | `错误码`、`技术栈`、`操作` | debugging |
| 环境配置 | `工具名`、`配置项`、`现象` | configuration |
| 部署失败 | `平台`、`错误现象`、`步骤` | deployment |
| API 对接 | `服务名`、`API`、`错误` | integration |
| 性能问题 | `指标`、`技术栈`、`现象` | performance |

## 输出格式

### 找到方案

```markdown
## 查找到解决方案

**匹配方案**：{ID} — {标题}
**存储层级**：项目级 / 用户级
**匹配关键词**：{命中的关键词}
**路径**：{目录路径}

### 方案概要
{SKILL.md 中"场景"和"解决方案"的摘要}

是否按此方案执行？[是/否]
```

### 未找到方案

```markdown
## 未找到匹配的解决方案

已搜索：
- 项目级 .solutions/INDEX.md（{N} 条记录）
- 用户级 ~/.solutions/INDEX.md（{M} 条记录）

提取的关键词：{关键词列表}

未命中任何已有解决方案。将正常排查问题。
解决后可使用 solution-capture 沉淀本次解决方案。
```

## 行为边界

- **查找非阻塞**：找不到方案不阻塞后续工作，正常排查即可
- **不修改方案**：查找阶段只读取和复用，不修改已有解决方案（修改用 solution-capture 的更新流程）
- **项目级优先**：同时命中时，项目级方案优先于用户级
- **不替代排查**：方案是参考和加速，非绝对正确。执行时仍需验证步骤是否适用于当前环境
- **必须实际读取**：不能仅凭 INDEX.md 的标题就执行，必须读取 SKILL.md 获取完整步骤