233 lines
8.1 KiB
Markdown
233 lines
8.1 KiB
Markdown
---
|
||
name: problem-distillery
|
||
description: >-
|
||
从顽固问题中蒸馏方法论的渐进式知识系统。追踪反复出现且未被彻底解决的问题，
|
||
记录解决过程和弯路，定期提炼精炼认知，经实践验证后自动升级为常规注入。
|
||
当用户表达"还有问题"、"没解决"、"还是一样"、"又出现了"等语义，
|
||
或 Agent 自身意识到同一问题已尝试 2 次以上仍未解决时触发。
|
||
---
|
||
|
||
# Problem Distillery
|
||
|
||
从反复出现的顽固问题中，经过"追踪 → 解决 → 蒸馏 → 验证 → 注入"的完整生命周期，
|
||
蒸馏出经过实践验证的精炼认知和方法论。
|
||
|
||
与其他系统的区别：
|
||
- **pitfall-journal**：互补。pitfall 是事后快照（debug 完记一笔），distillery 是过程追踪 + 知识提炼
|
||
- **dev-changelog**：不重叠。changelog 记事实改动，distillery 记问题解决过程和认知沉淀
|
||
|
||
## 数据文件
|
||
|
||
```
|
||
.opencode/data/distillery/
|
||
problems.md -- 问题记录（open + resolved），操作 A/B 写入
|
||
insights.md -- 蒸馏后的精炼方法论，操作 C 写入
|
||
golden-rules.md -- 权重达标后升级的条目，操作 D 管理，新会话自动注入
|
||
```
|
||
|
||
## 条目格式
|
||
|
||
### problems.md 条目
|
||
|
||
```markdown
|
||
### [PD-YYYYMMDD-HHMM] 一句话标题
|
||
- **status**: open | resolved
|
||
- **fingerprint**: 关键特征词列表（用于匹配同一问题）
|
||
- **category**: tech | workflow | decision | other
|
||
- **first_seen**: YYYY-MM-DD HH:MM
|
||
- **attempts**:
|
||
1. [YYYY-MM-DD HH:MM] 尝试了什么 → 结果如何
|
||
2. [YYYY-MM-DD HH:MM] 又尝试了什么 → 结果如何
|
||
- **resolution**: （解决后填写）最终解决方案
|
||
- **dead_ends**: （解决后填写）走过的弯路及其失败原因
|
||
- **spark**: （解决后填写）一句话启发——这个问题教会了什么
|
||
- **distilled**: （蒸馏后填写）IN-xxx
|
||
```
|
||
|
||
### insights.md 条目
|
||
|
||
```markdown
|
||
### [IN-YYYYMMDD-NN] 一句话方法论
|
||
- **source_problems**: [PD-xxx, PD-yyy]
|
||
- **weight**: 0
|
||
- **promoted**: false | true | demoted
|
||
- **content**: 2-3 句精炼认知
|
||
```
|
||
|
||
文件尾部保留元数据：
|
||
|
||
```markdown
|
||
---
|
||
last_distill_date: YYYY-MM-DD
|
||
```
|
||
|
||
### golden-rules.md
|
||
|
||
```markdown
|
||
# Golden Rules
|
||
|
||
经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
|
||
|
||
1. [GR-001] 一句话认知（来源: IN-xxx, 累计验证 N 次）
|
||
2. [GR-002] ...
|
||
```
|
||
|
||
硬上限 15 条。超出时按权重排序保留 top-15，被淘汰的条目降回 insights.md（promoted 改为 demoted）。
|
||
|
||
## 操作 A：追踪记录（问题进行中）
|
||
|
||
### 触发条件
|
||
|
||
以下**任一**场景触发：
|
||
|
||
1. **用户明确表达**问题未解决：
|
||
- "还有问题"、"问题没有解决"、"还是一样"、"又出现了"
|
||
- "试了好多次了"、"这个问题反复出现"、"不行"、"没用"
|
||
- 以及其他表达"问题反复发生、Agent 没有完全解决"的语义
|
||
2. **Agent 自身意识到**同一问题已经尝试了 2 次以上仍未解决
|
||
|
||
### 适用范围
|
||
|
||
不限于技术问题——工作流设计、产品决策等各类反复纠结的问题均适用。
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 提取当前问题的指纹：
|
||
- 技术问题：错误信息关键词、涉及文件/模块、症状描述
|
||
- 非技术问题：核心矛盾点、涉及领域、反复出现的决策困境
|
||
|
||
2. 读取 problems.md，用指纹匹配 status=open 的条目
|
||
|
||
3. 匹配到已有条目 → 在 attempts 中追加本次尝试记录
|
||
|
||
4. 无匹配 → 创建新条目：
|
||
- 生成 ID：PD-YYYYMMDD-HHMM
|
||
- status: open
|
||
- 记录首次尝试
|
||
|
||
5. 告知用户："已开始追踪这个问题 [PD-xxx]"（首次）
|
||
或 "已更新追踪记录 [PD-xxx]，这是第 N 次尝试"（后续）
|
||
```
|
||
|
||
### 与 pitfall-journal 的衔接
|
||
|
||
当 pitfall-journal 中某个条目的同一问题反复出现（用户再次报告相同症状），
|
||
Agent 应意识到这已超出 pitfall 的"一次性记录"范畴，主动触发操作 A 建立追踪。
|
||
|
||
## 操作 B：解决记录
|
||
|
||
### 触发条件
|
||
|
||
存在 status=open 的追踪条目，且满足以下**任一**：
|
||
- 用户确认问题已解决："好了"、"解决了"、"终于可以了"
|
||
- Agent 判断问题已解决（测试通过、错误消失等）
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 填写 resolution：最终的解决方案
|
||
2. 填写 dead_ends：走过的弯路及其失败原因（从 attempts 中归纳）
|
||
3. 填写 spark：一句话启发——这个问题教会了什么
|
||
4. status 改为 resolved
|
||
5. 回复末尾附 [顽固问题已解决并记录]
|
||
```
|
||
|
||
### 注意
|
||
|
||
- 如果问题在当前会话中从发现到解决只花了 1-2 次尝试，不需要走 distillery 流程
|
||
（那是 pitfall-journal 的范畴）
|
||
- 只有经历了"反复尝试"的问题才值得 distillery 追踪
|
||
|
||
## 操作 C：定期蒸馏
|
||
|
||
### 触发条件
|
||
|
||
由 AGENTS.md 中的"蒸馏提醒检查"在每次会话开头检查：
|
||
- 读取 insights.md 尾部的 `last_distill_date`
|
||
- 如果距今超过 7 天，且 problems.md 中有未标记 `distilled` 的 resolved 条目
|
||
- 则提醒用户："你有 N 个已解决的顽固问题尚未总结，要花几分钟蒸馏一下吗？"
|
||
- 每次会话最多提醒一次
|
||
|
||
### 流程（用户同意后）
|
||
|
||
```
|
||
1. 读取所有 status=resolved 且无 distilled 标记的条目
|
||
2. Agent 分析这些问题的共性，提出归纳建议：
|
||
- 哪些问题有共同的根因模式？
|
||
- 能提炼出什么通用的认知或方法论？
|
||
- 建议的表述（2-3 句精炼认知）
|
||
3. 用户确认/修改后：
|
||
- 写入 insights.md（ID 格式：IN-YYYYMMDD-NN，NN 为当日序号）
|
||
- weight 初始为 0
|
||
- promoted: false
|
||
4. 更新 insights.md 尾部的 last_distill_date
|
||
5. 在对应 problems.md 条目上标记 distilled: IN-xxx
|
||
```
|
||
|
||
## 操作 D：验证与升级
|
||
|
||
### 被动验证
|
||
|
||
当操作 A 触发时（遇到新的或再次出现的顽固问题），额外执行：
|
||
|
||
```
|
||
1. 读取 insights.md，对当前问题做语义匹配
|
||
2. 如有相关条目，向用户展示：
|
||
"之前总结过一条相关经验 [IN-xxx]: [内容摘要]，可能对当前问题有帮助。"
|
||
3. 在问题解决流程中，跟踪该经验是否发挥了作用：
|
||
- 用户确认"这个提示有用"
|
||
- 或 Agent 判断解决方案与该 insight 的方向一致
|
||
4. 确认有用 → weight += 1，在 insights.md 中更新
|
||
5. 确认无用 → 不扣分（weight 只增不减，避免偶然失误惩罚好经验）
|
||
```
|
||
|
||
### 升级为 Golden Rule
|
||
|
||
```
|
||
1. 当某条 insight 的 weight >= 5：
|
||
a. 检查 golden-rules.md 当前条目数
|
||
b. 如 < 15 → 直接升级：
|
||
- 在 golden-rules.md 中追加条目（ID: GR-NNN，NNN 为递增序号）
|
||
- insights.md 中 promoted 改为 true
|
||
c. 如 = 15 → 比较权重：
|
||
- 新条目权重 > golden-rules.md 中最低权重条目 → 替换
|
||
- 被替换的条目降回 insights.md（promoted 改为 demoted）
|
||
- 否则不升级
|
||
2. 升级后告知用户：
|
||
"经验 [IN-xxx] 已累计验证 N 次，升级为 Golden Rule [GR-NNN]，后续新会话将自动注入。"
|
||
```
|
||
|
||
### 新会话注入
|
||
|
||
由 AGENTS.md 的"Golden Rules 注入"规则负责：
|
||
- 每次会话开头读取 `golden-rules.md`
|
||
- 如果非空，将全部条目作为背景知识注入上下文
|
||
- 注入方式与 `changelog-headlines` 同级别——轻量、不显式提及来源
|
||
|
||
## 容量与性能控制
|
||
|
||
| 文件 | 策略 | 阈值 |
|
||
|------|------|------|
|
||
| problems.md | resolved 且已 distilled 的条目超过 50 条时，归档到 problems-archive.md | 50 条 |
|
||
| insights.md | 无上限（条目本身是精炼的，每条 3-5 行） | — |
|
||
| golden-rules.md | 硬上限，按权重淘汰 | 15 条 |
|
||
| 新会话注入成本 | 只读 golden-rules.md（预期 < 30 行） | 极轻量 |
|
||
|
||
## 与其他系统的协作
|
||
|
||
| 系统 | 关系 | 说明 |
|
||
|------|------|------|
|
||
| `pitfall-journal` | 上游来源 | pitfall 条目反复出现时，升级为 distillery 追踪 |
|
||
| `dev-changelog` | 不重叠 | changelog 记事实改动，distillery 记过程和认知 |
|
||
| AGENTS.md | 下游消费者 | 负责 golden-rules 注入和蒸馏提醒 |
|
||
| `epee-orchestrator` Skill | 注册 | 在 registry.md 中注册本 Skill |
|
||
|
||
## 自迭代日志
|
||
|
||
本节记录使用本 Skill 过程中发现的必要检查项。
|
||
|
||
### 已知必要检查
|
||
|
||
（暂无）
|