Skill: seepine/self-improving-x (version 1.0.0)

--- name: self-improvement description: | 捕获学习成果、错误和纠正，以实现持续改进，当出现以下情况，使用本技能： (1) 命令或操作意外失败， (2) 用户纠正 '不，那是错的...'，'实际上...'）， (3) 用户请求不存在的功能， (4) 外部 API 或工具失败， (5) 意识到其知识已过时或不正确， (6) 发现更好的方法处理重复任务。在执行重要任务前也要回顾学习记录。" metadata: version: 0.1.0 --- # 自我改进技能 将学习成果和错误记录到 markdown 文件中以实现持续改进。编码智能体稍后可以将这些处理成修复补丁，重要的学习内容会被提升到项目记忆中。 ## 快速参考 ### 工作区结构 将这些文件注入每个会话： ``` <workspace-dir> ├── AGENTS.md # 多智能体工作流，委托模式 ├── SOUL.md # 行为准则，人格，原则 ├── TOOLS.md # 工具能力，集成注意事项 ├── MEMORY.md # 长期记忆（仅主会话） ├── memory/ # 每日记忆文件 │ └── YYYY-MM-DD.md └── .learnings/ # 此技能的学习记录文件 ├── LEARNINGS.md ├── ERRORS.md └── FEATURE_REQUESTS.md ``` ### 创建学习文件 创建目录 `.learnings`，然后从 `assets/` 复制： - `LEARNINGS.md` — 纠正、知识差距、最佳实践 - `ERRORS.md` — 命令失败、异常 - `FEATURE_REQUESTS.md` — 用户请求的功能 ### 自我改进工作流 当发生错误或纠正时： 1. 记录到 `.learnings/ERRORS.md`、`.learnings/LEARNINGS.md` 或 `.learnings/FEATURE_REQUESTS.md` 2. 回顾并将广泛适用的学习内容提升到： - `AGENTS.md` - 工作流和自动化 ### 场景示例 | 场景 | 操作 | |-----------|--------| | 命令/操作失败 | 记录到 `.learnings/ERRORS.md` | | 用户纠正你 | 记录到 `.learnings/LEARNINGS.md`，类别为 `correction` | | 用户需要缺失的功能 | 记录到 `.learnings/FEATURE_REQUESTS.md` | | API/外部工具失败 | 记录到 `.learnings/ERRORS.md`，包含集成详情 | | 知识已过时 | 记录到 `.learnings/LEARNINGS.md`，类别为 `knowledge_gap` | | 发现更好的方法 | 记录到 `.learnings/LEARNINGS.md`，类别为 `best_practice` | | 简化/强化重复模式 | 记录/更新 `.learnings/LEARNINGS.md`，来源 `simplify-and-harden`，带稳定的 `Pattern-Key` | | 与现有条目相似 | 用 `**See Also**` 链接，考虑提升优先级 | | 广泛适用的学习内容 | 提升到 `CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md` | | 工作流改进 | 提升到 `AGENTS.md` | | 工具陷阱 | 提升到 `TOOLS.md` | | 行为模式 | 提升到 `SOUL.md` | --- ## 日志格式 ### 学习条目 > 完整示例可查看 `./examples/LEARNINGS_example.md` 追加到 `.learnings/LEARNINGS.md`： ```markdown ## [LRN-YYYYMMDD-XXX] 类别 **记录时间**: ISO-8601 时间戳 **优先级**: low | medium | high | critical **状态**: pending **领域**: frontend | backend | infra | tests | docs | config ### 摘要 一句话描述学到的内容 ### 详情 完整上下文：发生了什么、哪里错了、正确的是什么 ### 建议操作 具体的修复或改进 ### 元数据 - 来源: conversation | error | user_feedback - 相关文件: path/to/file.ext - 标签: tag1, tag2 - 另请参阅: LRN-20250110-001（如果与现有条目相关） - Pattern-Key: simplify.dead_code | harden.input_validation（可选，用于重复模式跟踪） - Recurrence-Count: 1（可选） - First-Seen: 2025-01-15（可选） - Last-Seen: 2025-01-15（可选） --- ``` ### 错误条目 > 完整示例可查看 `./examples/ERRORS_example.md` 追加到 `.learnings/ERRORS.md`： ```markdown ## [ERR-YYYYMMDD-XXX] skill_or_command_name **记录时间**: ISO-8601 时间戳 **优先级**: high **状态**: pending **领域**: frontend | backend | infra | tests | docs | config ### 摘要 失败内容的简要描述 ### 错误 实际错误消息或输出 ### 上下文 - 尝试的命令/操作 - 使用的输入或参数 - 相关环境详情 ### 建议修复 如果可以识别，可能解决此问题的方法 ### 元数据 - 可复现: yes | no | unknown - 相关文件: path/to/file.ext - 另请参阅: ERR-20250110-001（如果重复） --- ``` ### 功能请求条目 > 完整示例可查看 `./examples/FEATURE_REQUESTS_example.md` 追加到 `.learnings/FEATURE_REQUESTS.md`： ```markdown ## [FEAT-YYYYMMDD-XXX] capability_name **记录时间**: ISO-8601 时间戳 **优先级**: medium **状态**: pending **领域**: frontend | backend | infra | tests | docs | config ### 请求的功能 用户想要做什么 ### 用户上下文 为什么需要它，正在解决什么问题 ### 复杂度估计 simple | medium | complex ### 建议实现方式 如何构建，可以扩展什么 ### 元数据 - 频率: first_time | recurring - 相关功能: existing_feature_name --- ``` ## ID 生成 格式：`TYPE-YYYYMMDD-XXX` - TYPE: `LRN`（学习）、`ERR`（错误）、`FEAT`（功能） - YYYYMMDD: 当前日期 - XXX: 序列号或随机3个字符（例如 `001`、`A7B`） 示例：`LRN-20250115-001`、`ERR-20250115-A3F`、`FEAT-20250115-002` ## 解析条目 当问题被修复时，更新条目： 1. 将 `**状态**: pending` → `**状态**: resolved` 2. 在元数据后添加解析块： ```markdown ### 解析 - **已解决**: 2025-01-16T09:00:00Z - **提交/PR**: abc123 或 #42 - **备注**: 所做工作的简要描述 ``` 其他状态值： - `in_progress` - 正在积极处理 - `wont_fix` - 决定不处理（在解析备注中添加原因） - `promoted` - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md ## 提升到项目记忆 当学习内容具有广泛适用性（不是一次性修复）时，将其提升到永久项目记忆。 ### 何时提升 - 学习内容适用于多个文件/功能 - 任何贡献者（人类或 AI）都应该知道的知识 - 防止重复犯错 - 记录项目特定的约定 ### 提升目标 | 目标 | 属于那里的内容 | |--------|-------------------| | `AGENTS.md` | 智能体特定工作流、工具使用模式、自动化规则 | | `SOUL.md` | 行为准则、沟通风格、原则 | | `TOOLS.md` | 工具能力、使用模式、集成注意事项 | ### 如何提升 1. **提炼**学习内容为简洁的规则或事实 2. **添加**到目标文件的适当部分（需要时创建文件） 3. **更新**原始条目： - 将 `**状态**: pending` → `**状态**: promoted` - 添加 `**已提升**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md` ### 提升示例 **学习**（详细）： > 项目使用 pnpm workspaces。尝试 `npm install` 但失败了。 > 锁文件是 `pnpm-lock.yaml`。必须使用 `pnpm install`。 **在 CLAUDE.md 中**（简洁）： ```markdown ## 构建和依赖 - 包管理器: pnpm（不是 npm）- 使用 `pnpm install` ``` **学习**（详细）： > 修改 API 端点时，必须重新生成 TypeScript 客户端。 > 忘记这一点会导致运行时类型不匹配。 **在 AGENTS.md 中**（可操作）： ```markdown ## API 变更后 1. 重新生成客户端: `pnpm run generate:api` 2. 检查类型错误: `pnpm tsc --noEmit` ``` ## 重复模式检测 如果记录的内容与现有条目相似： 1. **首先搜索**: `grep -r "keyword" .learnings/` 2. **链接条目**: 在元数据中添加 `**另请参阅**: ERR-20250110-001` 3. **提升优先级** 如果问题持续出现 4. **考虑系统性修复**: 重复问题通常表示： - 缺少文档（→ 提升到 CLAUDE.md 或 .github/copilot-instructions.md） - 缺少自动化（→ 添加到 AGENTS.md） - 架构问题（→ 创建技术债务工单） ## 简化和强化反馈 使用此工作流来吸收来自 `simplify-and-harden` 技能的重复模式，并将它们转化为持久的提示指导。 ### 吸收工作流 1. 从任务摘要中读取 `simplify_and_harden.learning_loop.candidates` 2. 对于每个候选，使用 `pattern_key` 作为稳定的去重键 3. 搜索 `.learnings/LEARNINGS.md` 中具有该键的现有条目： - `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md` 4. 如果找到： - 增加 `Recurrence-Count` - 更新 `Last-Seen` - 添加 `See Also` 链接到相关条目/任务 5. 如果未找到： - 创建新的 `LRN-...` 条目 - 设置 `来源: simplify-and-harden` - 设置 `Pattern-Key`、`Recurrence-Count: 1` 和 `First-Seen`/`Last-Seen` ### 提升规则（系统提示反馈） 当满足以下所有条件时，将重复模式提升到智能体上下文/系统提示文件： - `Recurrence-Count >= 3` - 在至少 2 个不同任务中看到 - 在 30 天窗口内发生 提升目标： - `CLAUDE.md` - `AGENTS.md` - `.github/copilot-instructions.md` - `SOUL.md` / `TOOLS.md`（适用于 OpenClaw 工作区级指导） 将提升的规则写为简短的预防规则（编码前/编码期间要做什么）， 而不是长的事故报告。 ## 定期回顾 在自然断点时回顾 `.learnings/`： ### 何时回顾 - 开始新的重要任务前 - 完成功能后 - 在有过去学习内容的领域工作时 - 活跃开发期间每周 ### 快速状态检查 ```bash # 统计待处理项目 grep -h "状态**: pending" .learnings/*.md | wc -l # 列出待处理的高优先级项目 grep -B5 "优先级**: high" .learnings/*.md | grep "^## \[" # 查找特定领域的学习内容 grep -l "领域**: backend" .learnings/*.md ``` ### 回顾操作 - 解决已修复的项目 - 提升适用的学习内容 - 链接相关条目 - 升级重复问题 ## 检测触发器 当你注意到以下情况时自动记录： **纠正**（→ 类别为 `correction` 的学习）： - "不，那是不对的..." - "实际上，应该是..." - "你错了..." - "那已经过时了..." **功能请求**（→ 功能请求）： - "你也可以..." - "我希望你能..." - "有没有办法..." - "为什么你不能..." **知识差距**（→ 类别为 `knowledge_gap` 的学习）： - 用户提供了你不知道的信息 - 你引用的文档已过时 - API 行为与你的理解不同 **错误**（→ 错误条目）： - 命令返回非零退出码 - 异常或堆栈跟踪 - 意外输出或行为 - 超时或连接失败 ## 优先级指南 | 优先级 | 何时使用 | |----------|-------------| | `critical` | 阻止核心功能、数据丢失风险、安全问题 | | `high` | 重大影响、影响常见工作流、重复问题 | | `medium` | 中等影响，存在变通方法 | | `low` | 小麻烦、边缘情况、可有可无 | ## 领域标签 用于按代码库区域过滤学习内容： | 领域 | 范围 | |------|-------| | `frontend` | UI、组件、客户端代码 | | `backend` | API、服务、服务器端代码 | | `infra` | CI/CD、部署、Docker、云 | | `tests` | 测试文件、测试工具、覆盖率 | | `docs` | 文档、注释、README | | `config` | 配置文件、环境、设置 | ## 最佳实践 1. **立即记录** - 上下文在问题发生后最清晰 2. **要具体** - 未来的智能体需要快速理解 3. **包含复现步骤** - 特别是对于错误 4. **链接相关文件** - 使修复更容易 5. **建议具体修复** - 不要只是"调查" 6. **使用一致的类别** - 便于过滤 7. **积极提升** - 如果有疑问，添加到 CLAUDE.md 或 .github/copilot-instructions.md 8. **定期回顾** - 过时的学习内容会失去价值 ## Gitignore 选项 **保持学习内容本地化**（每个开发者）： ```gitignore .learnings/ ``` **在仓库中跟踪学习内容**（团队范围）： 不要添加到 .gitignore - 学习内容成为共享知识。 **混合**（跟踪模板，忽略条目）： ```gitignore .learnings/*.md !.learnings/.gitkeep ``` ## 自动技能提取 当学习内容有价值到可以成为可重用技能时，使用提供的辅助工具进行提取。 ### 技能提取标准 当满足以下任何条件时，学习内容有资格进行技能提取： | 标准 | 描述 | |-----------|-------------| | **重复** | 有到 2+ 类似问题的 `另请参阅` 链接 | | **已验证** | 状态为 `resolved`，修复有效 | | **非显而易见** | 需要实际调试/调查才能发现 | | **广泛适用** | 不是项目特定的；对代码库有用 | | **用户标记** | 用户说"保存为技能"或类似的话 | ### 提取工作流 1. **识别候选**: 学习内容满足提取标准 2. **创建技能**: ``` .agents/skills/<skill-name>/SKILL.md ``` 3. **自定义 SKILL.md**: 用学习内容填充模板，模版可查看 `./assets/SKILL-TEMPLATE.md` 4. **更新学习**: 将状态设置为 `promoted_to_skill`，添加 `Skill-Path` 5. **验证**: 在新会话中读取技能以确保它是独立的 ### 提取检测触发器 注意以下表示学习内容应该成为技能的信号： **在对话中：** - "保存为技能" - "我一直在遇到这个问题" - "这对其他项目也有用" - "记住这个模式" **在学习条目中：** - 多个 `另请参阅` 链接（重复问题） - 高优先级 + 已解决状态 - 类别: `best_practice`，广泛适用 - 用户反馈称赞解决方案 ### 技能质量门 提取前，验证： - [ ] 解决方案已测试并有效 - [ ] 描述清晰，不需要原始上下文 - [ ] 代码示例是独立的 - [ ] 没有项目特定的硬编码值 - [ ] 遵循技能命名约定（小写，连字符）

path: README.md
content: # self-improving skill

自我提升技能中文版，纯提示词无脚本，模型能力越强效果越好

## 安装

执行命令安装
```sh
npx skills add https://github.com/seepine/self-improving
```

## 添加内容到 AGENTS.md

因有些 Agent 未必会默认加载所有技能，所以可添加以下内容到 AGENTS.md 最末尾，提高触发概率

```md
## 自我改进技能

### 工作区结构

workspace-dir              # 工作空间目录
├── AGENTS.md                # 智能体说明文件
└── .learnings/              # 此技能的学习记录文件目录
    ├── LEARNINGS.md         # 纠正、知识差距、最佳实践的文件
    ├── ERRORS.md            # 命令失败、异常
    └── FEATURE_REQUESTS.md  # 用户请求的功能

### 何时改进

在以下情况下应用自我改进：

1. **发现非显而易见的东西** - 解决方案不是立即的
2. **纠正自己** - 最初的方法是错误的
3. **学习项目约定** - 发现未记录的模式
4. **遇到意外错误** - 特别是诊断困难时
5. **找到更好的方法** - 改进了原始解决方案

### 如何改进

具体查看 `self-improving` 这个技能

```

path: assets/FEATURE_REQUESTS.md
content: # 功能请求日志

_wait append_


path: assets/ERRORS.md
content: # 错误日志

_wait append_


path: assets/SKILL-TEMPLATE.md
content: # 技能模板

从学习内容创建技能的模板。复制并自定义。

---

## SKILL.md 模板

```markdown
---
name: skill-name-here
description: "关于何时以及为何使用此技能的简洁描述。包括触发条件。"
---

# 技能名称

简要介绍此技能解决的问题及其来源。

## 快速参考

| 场景 | 操作 |
|-----------|--------|
| [触发 1] | [操作 1] |
| [触发 2] | [操作 2] |

## 背景

为什么这些知识很重要。它防止什么问题。来自原始学习内容的上下文。

## 解决方案

### 步骤

1. 带代码或命令的第一步
2. 第二步
3. 验证步骤

### 代码示例

\`\`\`language
// 演示解决方案的示例代码
\`\`\`

## 常见变体

- **变体 A**: 描述及如何处理
- **变体 B**: 描述及如何处理

## 陷阱

- 警告或常见错误 #1
- 警告或常见错误 #2

## 相关

- 相关文档链接
- 相关技能链接

## 来源

从学习条目中提取。
- **学习 ID**: LRN-YYYYMMDD-XXX
- **原始类别**: correction | insight | knowledge_gap | best_practice
- **提取日期**: YYYY-MM-DD
```

---

## 最小模板

对于不需要所有部分的简单技能：

```markdown
---
name: skill-name-here
description: "此技能的作用及何时使用。"
---

# 技能名称

[一句话的问题陈述]

## 解决方案

[直接解决方案及代码/命令]

## 来源

- 学习 ID: LRN-YYYYMMDD-XXX
```

---

## 带脚本的模板

对于包含可执行辅助工具的技能：

```markdown
---
name: skill-name-here
description: "此技能的作用及何时使用。"
---

# 技能名称

[介绍]

## 快速参考

| 命令 | 用途 |
|---------|---------|
| `./scripts/helper.sh` | [它的作用] |
| `./scripts/validate.sh` | [它的作用] |

## 使用

### 自动化（推荐）

\`\`\`bash
./skills/skill-name/scripts/helper.sh [args]
\`\`\`

### 手动步骤

1. 第一步
2. 第二步

## 脚本

| 脚本 | 描述 |
|--------|-------------|
| `scripts/helper.sh` | 主要工具 |
| `scripts/validate.sh` | 验证检查器 |

## 来源

- 学习 ID: LRN-YYYYMMDD-XXX
```

---

## 命名约定

- **技能名称**: 小写，空格用连字符
  - 好: `docker-m1-fixes`、`api-timeout-patterns`
  - 坏: `Docker_M1_Fixes`、`APITimeoutPatterns`

- **描述**: 以动作动词开头，提到触发条件
  - 好: "处理 Apple Silicon 上的 Docker 构建失败。当构建因平台不匹配而失败时使用。"
  - 坏: "Docker 东西"

- **文件**:
  - `SKILL.md` - 必需，主要文档
  - `scripts/` - 可选，可执行代码
  - `references/` - 可选，详细文档
  - `assets/` - 可选，模板

---

## 提取检查清单

从学习内容创建技能之前：

- [ ] 学习内容已验证（状态: resolved）
- [ ] 解决方案广泛适用（不是一次性的）
- [ ] 内容完整（有所有需要的上下文）
- [ ] 名称符合约定
- [ ] 描述简洁但有信息量
- [ ] 快速参考表可操作
- [ ] 代码示例已测试
- [ ] 来源学习 ID 已记录

创建后：

- [ ] 用 `promoted_to_skill` 状态更新原始学习内容
- [ ] 在学习元数据中添加 `技能路径: skills/skill-name`
- [ ] 在新会话中测试技能以确保它是独立的


path: assets/LEARNINGS.md
content: # 学习日志

## 前言

在开发过程中捕获的纠正、见解和知识差距。

**类别**: correction | insight | knowledge_gap | best_practice
**领域**: frontend | backend | infra | tests | docs | config
**状态**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

### 类别和领域

根据实际情况取名

### 状态定义

固定以下枚举

| 状态 | 含义 |
|--------|---------|
| `pending` | 尚未处理 |
| `in_progress` | 正在积极处理 |
| `resolved` | 问题已修复或知识已整合 |
| `wont_fix` | 决定不处理（在解析中注明原因） |
| `promoted` | 已提升到 CLAUDE.md、AGENTS.md 或 copilot-instructions.md |
| `promoted_to_skill` | 已提取为可重用技能 |

### 技能提取字段

当学习内容被提升为技能时，添加以下字段：

```markdown
**状态**: promoted_to_skill
**技能路径**: .agents/skills/skill-name
```

---

_wait append_



path: examples/FEATURE_REQUESTS_example.md
content: # 功能请求日志

## [FEAT-20250115-001] export_to_csv

**记录时间**: 2025-01-15T16:45:00Z
**优先级**: medium
**状态**: pending
**领域**: backend

### 请求的功能
将分析结果导出为 CSV 格式

### 用户上下文
用户运行每周报告，需要与非技术
利益相关者分享 Excel 格式的结果。目前手动复制输出。

### 复杂度估计
简单

### 建议实现方式
为 analyze 命令添加 `--output csv` 标志。使用标准 csv 模块。
可以扩展现有的 `--output json` 模式。

### 元数据
- 频率: recurring
- 相关功能: analyze 命令，json 输出

---

## [FEAT-20250110-002] dark_mode

**记录时间**: 2025-01-10T14:00:00Z
**优先级**: low
**状态**: resolved
**领域**: frontend

### 请求的功能
仪表板的深色模式支持

### 用户上下文
用户工作到很晚，觉得明亮的界面很刺眼。
其他几位用户也非正式地提到过这一点。

### 复杂度估计
中等

### 建议实现方式
使用 CSS 变量管理颜色。在用户设置中添加切换。
考虑系统偏好检测。

### 元数据
- 频率: recurring
- 相关功能: 用户设置，主题系统

### 解析
- **已解决**: 2025-01-18T16:00:00Z
- **提交/PR**: #142
- **备注**: 通过系统偏好检测和手动切换实现

---

path: examples/LEARNINGS_example.md
content: # 学习日志

在开发过程中捕获的纠正、见解和知识差距。

**类别**: correction | insight | knowledge_gap | best_practice
**领域**: frontend | backend | infra | tests | docs | config
**状态**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

## 前言

### 状态定义

| 状态 | 含义 |
|--------|---------|
| `pending` | 尚未处理 |
| `in_progress` | 正在积极处理 |
| `resolved` | 问题已修复或知识已整合 |
| `wont_fix` | 决定不处理（在解析中注明原因） |
| `promoted` | 已提升到 CLAUDE.md、AGENTS.md 或 copilot-instructions.md |
| `promoted_to_skill` | 已提取为可重用技能 |

### 技能提取字段

当学习内容被提升为技能时，添加以下字段：

```markdown
**状态**: promoted_to_skill
**技能路径**: skills/skill-name
```

---

## [LRN-20250115-001] 纠正

**记录时间**: 2025-01-15T10:30:00Z
**优先级**: high
**状态**: pending
**领域**: tests

### 摘要
错误地假设 pytest fixtures 默认是函数作用域的

### 详情
在编写测试 fixtures 时，我假设所有 fixtures 都是函数作用域的。
用户纠正说，虽然函数作用域是默认值，但代码库
约定使用模块作用域的 fixtures 用于数据库连接以
提高测试性能。

### 建议操作
创建涉及昂贵设置（数据库、网络）的 fixtures 时，
在默认使用函数作用域之前，检查现有 fixtures 的作用域模式。

### 元数据
- 来源: user_feedback
- 相关文件: tests/conftest.py
- 标签: pytest, testing, fixtures

---


## [LRN-20250115-002] 知识差距

**记录时间**: 2025-01-15T14:22:00Z
**优先级**: medium
**状态**: resolved
**领域**: config

### 摘要
项目使用 pnpm 而不是 npm 进行包管理

### 详情
尝试运行 `npm install`，但项目使用 pnpm workspaces。
锁文件是 `pnpm-lock.yaml`，不是 `package-lock.json`。

### 建议操作
在假设使用 npm 之前，检查 `pnpm-lock.yaml` 或 `pnpm-workspace.yaml`。
为此项目使用 `pnpm install`。

### 元数据
- 来源: error
- 相关文件: pnpm-lock.yaml, pnpm-workspace.yaml
- 标签: package-manager, pnpm, setup

### 解析
- **已解决**: 2025-01-15T14:30:00Z
- **提交/PR**: N/A - 知识更新
- **备注**: 已添加到 CLAUDE.md 以供将来参考

---

## [LRN-20250115-003] 最佳实践

**记录时间**: 2025-01-15T16:00:00Z
**优先级**: high
**状态**: promoted
**领域**: backend
**已提升**: AGENTS.md

### 摘要
API 响应必须包含请求头中的 correlation ID

### 详情
所有 API 响应都应该回显请求中的 X-Correlation-ID 头。
这是分布式追踪所必需的。没有此头的响应
会破坏可观察性管道。

### 建议操作
始终在 API 处理器中包含 correlation ID 直通。

### 元数据
- 来源: user_feedback
- 相关文件: src/middleware/correlation.ts
- 标签: api, observability, tracing

---

## [LRN-20250116-001] 最佳实践

**记录时间**: 2025-01-16T09:00:00Z
**优先级**: high
**状态**: promoted
**领域**: backend
**已提升**: AGENTS.md

### 摘要
OpenAPI 规范更改后必须重新生成 API 客户端

### 详情
修改 API 端点时，必须重新生成 TypeScript 客户端。
忘记这一点会导致运行时才出现的类型不匹配。
生成脚本也会运行验证。

### 建议操作
添加到智能体工作流：任何 API 更改后，运行 `pnpm run generate:api`。

### 元数据
- 来源: error
- 相关文件: openapi.yaml, src/client/api.ts
- 标签: api, codegen, typescript

---

## [LRN-20250118-001] 最佳实践

**记录时间**: 2025-01-18T11:00:00Z
**优先级**: high
**状态**: promoted_to_skill
**领域**: infra
**技能路径**: skills/docker-m1-fixes

### 摘要
Docker build 在 Apple Silicon 上因平台不匹配而失败

### 详情
在 M1/M2 Mac 上构建 Docker 镜像时，构建失败，因为
基础镜像没有 ARM64 变体。这是一个常见问题
影响许多开发者。

### 建议操作
在 docker build 命令中添加 `--platform linux/amd64`，或在 Dockerfile 中使用
`FROM --platform=linux/amd64`。

### 元数据
- 来源: error
- 相关文件: Dockerfile
- 标签: docker, arm64, m1, apple-silicon
- 另请参阅: ERR-20250115-A3F, ERR-20250117-B2D

---


path: examples/ERRORS_example.md
content: 
# 错误日志

## [ERR-20250115-A3F] docker_build

**记录时间**: 2025-01-15T09:15:00Z
**优先级**: high
**状态**: pending
**领域**: infra

### 摘要
Docker build 在 M1 Mac 上因平台不匹配而失败

### 错误

error: failed to solve: python:3.11-slim: no match for platform linux/arm64

### 上下文
- 命令: `docker build -t myapp .`
- Dockerfile 使用 `FROM python:3.11-slim`
- 在 Apple Silicon（M1/M2）上运行

### 建议修复
添加平台标志: `docker build --platform linux/amd64 -t myapp .`
或更新 Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`

### 元数据
- 可复现: yes
- 相关文件: Dockerfile

---

## [ERR-20250120-B2C] api_timeout

**记录时间**: 2025-01-20T11:30:00Z
**优先级**: critical
**状态**: pending
**领域**: backend


### 摘要
结账时第三方支付 API 超时

### 错误

TimeoutError: Request to payments.example.com timed out after 30000ms

### 上下文
- 命令: POST /api/checkout
- 超时设置为 30 秒
- 在高峰时间发生（午餐、傍晚）

### 建议修复
实现指数退避重试。考虑断路器模式。

### 元数据
- 可复现: yes（在高峰时间）
- 相关文件: src/services/payment.ts
- 另请参阅: ERR-20250115-X1Y, ERR-20250118-Z3W

---


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)