Solution Capture

---
name: solution-capture
description: AI 解决非平凡问题后，评估是否值得沉淀为可复用的解决方案 skill，若值得则按 skill 标准格式写入 .solutions/ 目录并更新索引。触发短语包括："记录这个解决方案"、"沉淀一下"、"保存解决方案"、"这个值得记录"、"solution capture"，或在 AI 解决了一个需要多步推理、调试、配置的问题后自动触发。
---

# 解决方案捕获

## 概述

**目的**：让 AI 在解决非平凡问题后，自动将"问题→解决步骤"沉淀为可复用的 skill，下次遇到类似问题可直接加载执行，避免重复踩坑。

**功能**：评估问题是否值得记录 → 提炼为标准 skill 格式 → 写入 .solutions/ 目录 → 更新 INDEX.md 索引。

**使用场景**：
- AI 解决了一个需要多步调试的问题后
- AI 完成了一套复杂配置后
- AI 解决了一个反复出现的问题后
- 用户说"记录这个解决方案"、"沉淀一下"、"这个值得记录"时

## 核心原则

1. **只记录非平凡的**：一行能说完的不记，常规操作不记，只有"花了不少步骤才搞定"的才记
2. **skill 格式**：每个解决方案就是一个标准 skill 目录（含 SKILL.md），可直接被加载执行
3. **双存储层**：项目级（`.solutions/`）优先，用户级（`~/.solutions/`）兜底
4. **索引同步**：写入解决方案后必须更新 INDEX.md
5. **去重**：记录前先查 INDEX.md，避免重复记录相同问题
6. **路由优先**：若 `loop-discovery` skill 可用且本次沉淀未经过路由，先走它做证据门与载体检查；其结论为"新建 solution"时跳过下方 Step 1（评估已由路由完成），直接从 Step 2 开始

## 存储结构

```
# 项目级（跟项目走，版本控制）
.solutions/
├── INDEX.md                         # 索引文件
├── debugging/
│   ├── jwt-token-expiry/            # 解决方案 = skill 目录
│   │   ├── SKILL.md                 # 主体（标准 skill 格式）
│   │   ├── scripts/                 # 可选脚本
│   │   │   └── fix_jwt.py
│   │   └── reference.md             # 可选参考资料
│   └── cors-policy-fix/
│       └── SKILL.md
├── configuration/
│   └── nginx-reverse-proxy/
│       └── SKILL.md
└── deployment/
    └── docker-multi-stage/
        └── SKILL.md

# 用户级（跨项目共享）
~/.solutions/
├── INDEX.md
└── general/
    └── git-force-push-recovery/
        └── SKILL.md
```

## 分类目录

使用以下标准分类，不确定时归入 `general`：

| 分类 | 说明 | 典型场景 |
|------|------|----------|
| `debugging` | 调试问题 | bug 排查、错误修复、异常定位 |
| `configuration` | 配置问题 | 环境配置、中间件配置、CI/CD 配置 |
| `deployment` | 部署问题 | Docker、K8s、服务器部署 |
| `integration` | 集成问题 | 第三方 API 对接、SDK 集成 |
| `architecture` | 架构问题 | 设计模式、技术选型、重构 |
| `performance` | 性能问题 | 性能优化、内存泄漏、慢查询 |
| `general` | 通用问题 | 不属于上述分类的 |

## 执行流程

### Step 1：评估是否值得记录

解决问题后，对照以下标准判断：

**值得记录（满足任一即可）**：
- 解决过程涉及 3 个以上步骤
- 需要查找文档、试错、调试才能解决
- 问题具有复现性，可能再次遇到
- 解决方案包含非显而易见的技巧或注意事项
- 涉及特定工具/框架的坑或最佳实践

**不值得记录**：
- 一行命令就能解决
- 常规 CRUD 操作
- 一次性、不会再现的问题
- AI 自身知识库中已覆盖的标准操作

### Step 2：确定存储位置

按以下优先级确定存储层和分类：

1. **存储层选择**：
   - 与当前项目强相关（如项目特定配置、项目代码 bug）→ **项目级** `.solutions/`
   - 跨项目通用（如通用工具使用、语言级问题）→ **用户级** `~/.solutions/`
   - 不确定 → 默认项目级

2. **分类选择**：参照上方分类表

### Step 3：去重检查

读取目标存储层的 `INDEX.md`，检查是否已有类似解决方案：

- **关键词重叠**：INDEX.md 中的触发关键词与当前问题高度重合
- **标题相似**：已有标题描述的是同一个问题

**如果已存在**：
- 若新方案更优 → 更新已有解决方案（覆盖 SKILL.md + 更新 INDEX.md 条目）
- 若已有方案足够 → 跳过记录，告知用户已存在

### Step 4：确定解决方案 ID 和目录名

- **ID 命名规则**：小写字母 + 连字符，简洁描述问题，如 `jwt-token-expiry`、`cors-policy-fix`
- **目录结构**：`{分类}/{ID}/SKILL.md`

### Step 5：编写 SKILL.md

按标准 skill 格式编写，必须包含：

```markdown
---
name: {solution-id}
description: {一句话描述问题+解决方案，包含触发关键词}
category: {分类}
tags: [{逗号分隔标签}]
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
---

# {解决方案标题}

## 场景
{什么情况下会遇到这个问题，描述触发条件和症状}

## 问题
{问题的详细描述，包括错误信息、现象等}

## 解决方案
{分步骤的解决方法，清晰可执行}

## 关键代码
\`\`\`{语言}
{代码片段或命令}
\`\`\`

## 注意事项
{需要避开的坑、前置条件、副作用等}
```

**编写要求**：
- `description` 必须包含触发关键词，便于查找时匹配
- 解决方案步骤必须具体可执行，不要泛泛而谈
- 如有脚本辅助，放入 `scripts/` 子目录并在 SKILL.md 中引用

### Step 6：创建目录和文件

```
1. 创建目录：{存储层}/{分类}/{ID}/
2. 写入 SKILL.md
3. 如有脚本，创建 scripts/ 子目录并写入
4. 如有参考资料，写入 reference.md
```

### Step 7：更新 INDEX.md

读取现有 INDEX.md（不存在则创建），在对应分类下追加条目（**列表式格式**，参考 expert-team 的索引风格，不用表格以免拥挤）：

```markdown
# 解决方案索引

> 由 solution-capture 自动维护

## debugging

### jwt-token-expiry：JWT Token 过期时间设置
- **描述**：解决 JWT Token 过期时间设置不当导致登录态提前失效的问题
- **触发关键词**：jwt, token, 过期, 登出, expiry
- **目录**：debugging/jwt-token-expiry/

### cors-policy-fix：CORS 跨域策略修复
- **描述**：解决跨域请求被浏览器拦截、CORS 配置不生效的问题
- **触发关键词**：cors, 跨域, cross-origin
- **目录**：debugging/cors-policy-fix/

## configuration

### nginx-reverse-proxy：Nginx 反向代理配置
- **描述**：解决 Nginx 反向代理配置错误导致服务不可访问的问题
- **触发关键词**：nginx, 反向代理, proxy, reverse
- **目录**：configuration/nginx-reverse-proxy/
```

**INDEX.md 更新规则**：
- **描述字段必填**：一句话说明该方案用于解决什么问题（触发查找时帮助快速判断是否相关）
- 新增解决方案：在对应分类下追加一条记录（`### {ID}：{标题}` + 描述/触发关键词/目录三行）
- 更新解决方案：修改对应记录的标题、描述或触发关键词（目录名不变）
- 分类不存在：新增 `## {分类}` 标题，再追加记录
- 触发关键词：从问题的描述、症状、技术栈中提取 3-6 个关键词

### Step 7.5：同步写入 ki 错误库

INDEX.md 更新完成后，调用 `use_skill("ki-memory-write")` 的**错误库策略**写一条原子（报错原文片段 / 现象 / 根因 / 解法 / 验证方式 / 关联方案）。

- **内容从已写好的 SKILL.md 提炼**，不重复劳动
- **只存路标 + 指向**：错误库存"报错 → 根因/解法"入口，关联方案指向 `.solutions/{分类}/{ID}/`，**不复制 `.solutions/` 方案正文**——完整方案仍留在 `.solutions/`，二者不互相复制
- **查重前置**：写入前先查重，命中则更新不新建，避免重复爆炸
- **ki 不可用则跳过**，不阻塞主流程

### Step 8：验证

```
1. 确认目录结构正确：{存储层}/{分类}/{ID}/SKILL.md 存在
2. 确认 INDEX.md 已更新，新条目可见
3. 确认 SKILL.md 的 frontmatter 格式正确
```

## 更新已有解决方案

当发现已有解决方案需要更新时：

1. 读取现有 SKILL.md
2. 合并新信息（补充步骤、修正错误、添加注意事项）
3. 更新 `updated` 日期
4. 如分类或触发关键词需要调整，同步更新 INDEX.md
5. 版本号递增（在 frontmatter 中添加 `version` 字段，初始为 1，每次更新 +1）

## 行为边界

- **不记录平凡问题**：一行能解决的不记，常规操作不记
- **不替代 memory**：简单事实用 `update_memory`，代码级知识用 ki 知识库，完整解决方案才用本 skill
- **不自动触发落盘**：必须评估通过后才写入，避免污染解决方案库
- **必须更新索引**：写入解决方案后必须更新 INDEX.md，否则查找时无法发现
- **目录名即 ID**：目录名就是解决方案的唯一标识，不可改名（改名需删除重建）