本技能提供知识管理最佳实践与格式规范参考，涵盖去重、Scope 分类、修复优先、触发即记等规则。流程由 /session-* 命令驱动。
收到本技能内容时视为活动指令立即执行（无论通过 skill() 工具注入还是用户输入 /self-improve），不反问不分析，不提"加载技能"。
以下情况自动调用 /session-learn，不等用户开口：
| 触发条件 | 识别方式 |
|---|---|
| --------- | --------- |
| 用户纠正 | "不对"、"应该这样"、"你错了" |
| 错误/崩溃 | MCP 报错、401/403/5xx、超时 |
| 学到新知识 | 预期不符、框架/工具怪癖、沉没成本 |
| 更好的做法 | 连续 2+ 次用非标准操作绕问题 |
| 会话结束 | /session-end 中自动触发 |
| 约束 | 规则 |
|---|---|
| ------ | ------ |
| 去重 | 写前 grep Pattern-Key，命中则递增 Recurrence-Count，不另起条目。使用规范化抽象键（去掉具体路径/端口/版本号，只保留错误本质） |
| Scope 分类 | project-specific（计入限额 ✅ / 可归档 ✅）· cross-project（不限 🚫 / 永不归档 🚫）· opencode-self（不限 🚫 / 永不归档 🚫） |
| 修复优先于新增 | 遇错时先审视已有表述是否为根因，直接改进 |
详见 references/templates.md。各文件结构有别：
| 文件 | 用途 | 关键字段 | 生命周期 |
|---|---|---|---|
| ------ | ------ | --------- | --------- |
.opencode/learnings/LEARNINGS.md | 纠正 / 洞见 / 最佳实践 | Status + Scope + Pattern-Key | new → fixed → verified → recurrent/archived |
.opencode/learnings/ERRORS.md | 环境/命令/MCP 失败 | Exit-Code + Reproducible | 手动清理 |
FEATURE_REQUESTS.md | 用户提出的缺失功能 | Complexity Estimate | 可选 |
所有 LEARNINGS 条目标注 Scope（project-specific / cross-project / opencode-self），详见本 SKILL.md「核心约束」。
Session 内知识检索遵循本 SKILL.md「核心约束」规则，初始化由 /session-start 命令驱动，不再赘述。
| 任务 | 操作 |
|---|---|
| ------ | ------ |
| 加载技能 | skill: opencode-self-improve |
| 初始化 | /session-start |
| 记录 learning | /session-learn |
| 结束会话 | /session-end |
| 记录模板 | references/templates.md |
| 去重 | grep Pattern-Key 后追加 Recurrence-Count |
| Pattern-Key 设计 | 规范化抽象键，弃用原文（见 templates.md 指南） |
| Scope 分类 | project-specific（计入限额） / cross-project（不限） / opencode-self（不限） |
| 生命周期状态 | new → fixed → verified → recurrent / archived |
| 自动化预防 | Recurrence≥3 时加 lint/guard/test 从机制上拦截 |
| 权限 | 用途 |
|---|---|
| ------ | ------ |
filesystem.write | 写入 .opencode/learnings/LEARNINGS.md / ERRORS.md / FEATURE_REQUESTS.md |
filesystem.read | 读取已有记录做去重检查 |
grep | 搜索 Pattern-Key 防重复 |
.opencode/learnings/ 下：LEARNINGS.md（纠正/洞见）、ERRORS.md（环境/命令失败）、FEATURE_REQUESTS.md（功能建议）、ARCHIVED_LEARNINGS.md（冷知识）、session-state.json（跨会话上下文）
| 陷阱 | 原因 | 解决 |
|---|---|---|
| ------ | ------ | ------ |
| 忘记录入 | 事后想不起来细节 | 触发即记自动调用 /session-learn，收到本 SKILL.md 时立即执行知识管理流程 |
| 重复条目 | 同事件记了多次 | 写前先搜 Pattern-Key；用规范化键而非原文减少碰撞 |
| 记录无关信息 | 太琐碎 | 只记"下次 session 值得知道"的，其余跳过 |
| Pattern-Key 碰撞 | 不同事件选了相同键 | 键名要足够具体，含范畴前缀（如 ts-、network-、git-） |
| ERRORS.md 膨胀 | 无自动归档 | 定期检查 Status=resolved 的条目，手动清理或标记 wont_fix |
| 冷知识失联 | 归档后遗忘可 grep | 在本 SKILL.md 常见陷阱中保留概括性提示，含 ARCHIVED 条目 ID |
| 成本失控 | 频繁全文搜索 | 限制到 2-3 个关键词、单条子任务 grep ≤1 次 |
| 漏标 Scope | 不区分条目类型，跨项目经验被归档 | 写入时检查 Scope 字段；cross-project/opencode-self 永不归档 |
| 跳过 verified | 标记 fixed 后未验证修复有效性 | 必须走 new → fixed → verified，fixed 后描述验证方法 |
| 以记录替代修复 | 用户说"修复 X"时直接记录 learning 而非修源码 | 先修源码/配置，再（可选）记录 learning，不可用记录替代修复 |
commands/session-*.md 部署到目标项目的 .opencode/commands/ 下，提供 session 生命周期管理。核心命令：
/session-start — 初始化项目上下文/session-learn — 记录 learnings（含去重/Scope/晋升/归档）/session-end — 结束会话并补记在 opencode-skill-suite 提交 Issue 或 PR。
共 2 个版本