123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
---
|
||
name: pitfall-journal
|
||
description: >-
|
||
踩坑经验记录系统。在调试完成或发现非显而易见的坑后记录根因和解决方式，
|
||
后续遇到同类问题时自动检索匹配，避免重复踩坑。
|
||
当 debug 完成、问题反复出现、或用户提到"踩坑"、"之前遇到过"、"坑"时触发。
|
||
---
|
||
|
||
# Pitfall Journal
|
||
|
||
记录开发过程中遇到的"坑"——那些不看代码逻辑觉得应该没问题、但实际运行时才暴露的问题。
|
||
与 dev-changelog 互补：changelog 记"做了什么"，pitfall-journal 记"踩了什么坑、怎么爬出来的"。
|
||
|
||
## 数据文件
|
||
|
||
所有记录存放在 `.opencode/data/pitfalls/pitfalls.md`。
|
||
|
||
## 条目格式
|
||
|
||
```markdown
|
||
### [PF-YYYYMMDD-HHMM] 一句话标题
|
||
- **症状**: 用户/系统看到的错误表现
|
||
- **根因**: 技术层面的真正原因
|
||
- **解法**: 具体怎么修的
|
||
- **防御**: 以后如何避免（可选，如果有通用性的话）
|
||
- **关联**: 相关文件、模块、技术栈标签
|
||
```
|
||
|
||
## 操作 A：写入记录
|
||
|
||
### 触发条件
|
||
|
||
以下任一场景触发：
|
||
|
||
1. **调试完成后** — 经历了 debug 过程并找到了非显而易见的根因
|
||
2. **用户主动提及** — "记录一下这个坑"、"以后别再犯"
|
||
3. **Agent 识别到经验价值** — 问题涉及框架/库的隐式行为、配置陷阱、环境差异等
|
||
|
||
以下情况**不触发**：
|
||
- 纯拼写错误、简单语法错误
|
||
- 问题原因一目了然（如变量名打错）
|
||
- 纯业务逻辑调整（不涉及"坑"的语义）
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 生成条目 ID：PF-YYYYMMDD-HHMM
|
||
2. 从调试过程中提取：症状、根因、解法
|
||
3. 归纳防御措施（如果有通用性）
|
||
4. 读取 pitfalls.md，在顶部追加新条目
|
||
5. 在回复末尾附：[已记录到踩坑日志]
|
||
```
|
||
|
||
### 静默写入原则
|
||
|
||
与 dev-changelog 一致——Agent 自己调试出来的问题，不需要用户确认就可以记录。
|
||
|
||
## 操作 B：自动匹配检索
|
||
|
||
### 触发条件
|
||
|
||
当 Agent 在当前任务中遇到以下情况时，应主动检索 pitfalls.md：
|
||
|
||
1. **进入 Debug mode** — 读取 pitfalls.md，扫描是否有与当前错误症状匹配的记录
|
||
2. **同类错误再现** — 错误信息关键词与已有条目的"症状"匹配
|
||
3. **涉及已知高危区域** — 当前操作涉及的模块/技术栈在已有条目的"关联"中出现
|
||
|
||
### 匹配策略
|
||
|
||
```
|
||
1. 提取当前问题的关键信号：
|
||
- 错误信息关键词
|
||
- 涉及的文件/模块
|
||
- 涉及的技术栈/框架
|
||
|
||
2. 在 pitfalls.md 中匹配：
|
||
- 硬匹配：错误信息关键词出现在条目的"症状"中
|
||
- 软匹配：涉及的模块/技术栈出现在条目的"关联"中
|
||
|
||
3. 命中时，在分析中优先考虑已有经验：
|
||
> 注意：之前遇到过类似问题 [PF-xxx]：[一句话描述]。
|
||
> 上次的根因是 [xxx]，先排查这个方向。
|
||
```
|
||
|
||
## 操作 C：手动检索
|
||
|
||
### 触发条件
|
||
|
||
用户主动要求回顾踩坑记录。典型话语：
|
||
- "之前那个坑是什么来着"
|
||
- "看看踩坑日志"
|
||
- "有遇到过类似的问题吗"
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 读取 pitfalls.md
|
||
2. 根据用户描述匹配相关条目
|
||
3. 展示匹配结果
|
||
```
|
||
|
||
## 与其他系统的协作
|
||
|
||
| 系统 | 关系 | 说明 |
|
||
|------|------|------|
|
||
| `dev-changelog` | 互补 | changelog 记改动事实，pitfall 记经验教训 |
|
||
| AGENTS.md | 下游消费者 | 进入 Debug mode 或遇到错误时自动触发检索 |
|
||
| `epee-orchestrator` Skill | 注册 | 在 registry.md 中注册本 Skill |
|
||
|
||
## 自迭代日志
|
||
|
||
本节记录使用本 Skill 过程中发现的必要检查项。
|
||
|
||
### 已知必要检查
|
||
|
||
1. **顶部插入必须保持旧首条目完整性** — 使用编辑工具在文件顶部插入新条目时（操作 A 第 4 步），anchor（`old_string`）有且仅有两种合法选择：
|
||
(a) 只包含新条目之前的"稳定前缀"（如 `---\n\n` 或整个文件头部说明段），**不触及任何已有条目的任何一行**；然后 `new_string` = 稳定前缀 + 新条目完整内容 + 空行。
|
||
(b) 把旧首条目的**完整多行内容**（标题行 + 全部字段行）都纳入 `old_string`；然后 `new_string` = 新条目完整内容 + 空行 + 旧首条目完整内容。
|
||
|
||
**绝对禁止**：把旧首条目的"标题行"单独当 anchor 而不带上它紧跟的字段行——编辑工具是精确替换，这样做会删掉标题、让字段"无主"残留在新条目之后，造成半损坏状态。
|
||
|
||
**写入后自检**：Read 文件头 25 行，确认看到 `### [PF-新ID]` 后紧跟其 5 字段，再往下能看到 `### [PF-旧首条目ID]` 标题行且字段完整跟随。
|