解决方案捕获

概述

目的：让 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 格式编写，必须包含：

---
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 的索引风格，不用表格以免拥挤）：

# 解决方案索引

> 由 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：目录名就是解决方案的唯一标识，不可改名（改名需删除重建）