name: compound-docs description: 将已解决的问题捕获为可搜索的文档，并具备模式检测功能。当用户确认修复有效时（如“这解决了”、“已修复”、“现在正常了”）或通过/compound命令手动触发时，此技能会自动启动。 version: 0.1.0-beta license: MIT compatibility: opencode

知识复利文档

每个被记录的解决方案都在复利式地增长团队的知识。第一次解决问题需要研究。记录下来，下一次再遇到就只需要几分钟。知识会复利增长。

此技能灵感来源于 Every.to 的 compound-engineering 插件。

自动触发条件

当用户说出以下短语时，此技能会自动触发：

“这解决了”
“已修复”
“现在正常了”
“问题解决了”
“搞定了”

手动命令：/compound

工作流程

步骤 1：检测触发

当检测到触发短语或调用 /compound 时：

确认问题确实已解决（而非仍在处理中）
检查此修复是否值得记录

跳过记录简单修复：

简单的拼写错误
明显的语法错误（缺少分号、括号）
显而易见的单行修复

如果跳过，简要说明原因：“这是一个简单的拼写错误修复 - 跳过记录。”

步骤 2：收集上下文

读取 schema.yaml 获取有效的枚举值，然后从对话中提取：

字段	必填	描述
症状	是	错误信息或可观察到的行为
类别	是	来自 schema.yaml 的 `category.values`（或添加新的）
组件	否	来自 schema.yaml 的 `component.values`（或添加新的）
根本原因	否	来自 schema.yaml 的 `root_cause.values`（或添加新的）
解决方案	是	有效的修复方法
预防措施	否	未来如何避免此问题

如果某个值在 schema.yaml 中不存在：

将新值添加到 schema.yaml 中相应的枚举中
如果是新类别，创建目录：mkdir -p {output_dir}/{new-category}

如果缺少关键信息，询问：

为了记录此修复，我需要一些详细信息：

1. 类别：这是什么类型的问题？
   [列出 schema.yaml 中的当前值]
   如果没有合适的，请建议一个新类别

步骤 3：检查类似问题

在创建新文档之前，搜索现有的类似问题：

关键词匹配 - 在 {output_dir}/ 中搜索错误信息片段或关键症状短语
文件路径匹配 - 检查现有文档是否涉及相同的文件
导入/依赖匹配 - 检查是否提及相同的库或模块

# 搜索示例
grep -rl "错误信息" docs/solutions/
grep -l "路径/到/文件" docs/solutions/**/*.md

如果找到潜在匹配项：

找到可能相关的问题：
- docs/solutions/integration/api-timeout-20250102.md
- docs/solutions/integration/auth-header-missing-20250105.md

这些是相同或相关的问题吗？(y/n)

如果相关，添加到 frontmatter 的 related 字段中。

步骤 4：创建文档

根据 schema.yaml 进行验证：

读取 schema.yaml 获取当前有效的枚举值
确保所有必填字段都存在
确保枚举值存在（或先添加它们）

生成文件名：

格式：{sanitized-symptom}-{YYYYMMDD}.md
清理：小写，空格替换为连字符，移除特殊字符，截断至 80 个字符

在以下位置创建文件： {output_dir}/{category}/{filename}

确保目录存在：

mkdir -p {output_dir}/{category}

使用下面的解决方案文档模板。

步骤 5：模式提升

创建文档后，检查此问题是否已多次发生。

如果类似问题 >= 阈值（默认：2）：

此问题已发生 {N} 次：
- {链接到问题 1}
- {链接到问题 2}
- {链接到当前问题}

提升到 patterns.md？这将使其在未来会话中显著展示。
1. 是 - 添加到模式
2. 否 - 仅保留为常规文档

如果选择是： 使用下面的模式模板追加到 {output_dir}/patterns.md。

解决方案文档模板

---
date: {YYYY-MM-DD}
category: {category}
symptoms:
  - {症状 1}
  - {症状 2}
component: {component}
root_cause: {root_cause}
tags: [{关键词1}, {关键词2}]
related: []
---

# {问题标题}

## 问题

{1-2 句话描述出错的地方}

## 症状

- {观察到的现象 - 错误信息、行为等}

## 无效的尝试

- {尝试的解决方案 1} - {失败原因}
- {尝试的解决方案 2} - {失败原因}

## 解决方案

{修复方法的描述}

```{语言}
# 之前（有问题的）
{修复前的代码}

# 之后（修复后的）
{修复后的代码}

为什么有效

{对根本原因以及解决方案为何能解决它的技术性解释}

预防措施

{未来如何避免 - 测试、代码检查规则、应遵循的模式}


## 模式模板

当添加到 `patterns.md` 时：

```markdown
## {模式名称}

**发生次数：** {N} 次 ({链接1}, {链接2}, ...)

### 错误做法

```{语言}
{导致问题的代码}

正确做法

{修复它的代码}

原因： {技术性解释}

适用场景： {此模式相关的上下文或条件}


## 集成

### 在 AGENTS.md 中引用

添加到项目的 AGENTS.md 中，以确保检查已知模式：

```markdown
## 必读内容

在进行更改之前，请查阅已知模式：
- [解决方案模式](docs/solutions/patterns.md)

使用解决方案

其他工作流可以发现并应用已记录的解决方案：

按关键词搜索：

grep -rl "关键词" docs/solutions/

按类别搜索：

ls docs/solutions/deployment/

按标签搜索：

grep -l "tags:.*docker" docs/solutions/**/*.md

patterns.md 是主要的集成点 - 在进行更改之前，首先检查它以获取关键模式。

示例场景

用户： “搞定了！Docker 构建失败是因为缓存问题。”

代理响应：

太好了！我来记录这个修复。

**正在读取 schema.yaml...**
当前类别：developer-experience, deployment, ui, integration, performance, testing
当前组件：(暂无)
当前根本原因：(暂无)

**正在收集上下文...**

根据我们的对话：
- 症状：Docker 构建失败，出现“layer not found”错误
- 类别：deployment
- 组件：docker (添加到 schema.yaml)
- 根本原因：stale-cache (添加到 schema.yaml)
- 解决方案：添加了 `--no-cache` 标志并更新了基础镜像标签
- 预防措施：固定基础镜像版本，定期使用 `docker system prune`

**正在更新 schema.yaml...**
已将 'docker' 添加到 component.values
已将 'stale-cache' 添加到 root_cause.values

**正在检查类似问题...**
未找到相关问题。

**正在创建文档...**
已创建：docs/solutions/deployment/docker-layer-not-found-20250106.md

文档记录完成。