self-improving-agent: Cross-Project

# 自改进 Agent 技能 ## 概述 本技能让 AI 从错误和反馈中持续学习，经验可在**项目间贯通**。采用**用户级（跨项目）+ 项目级（当前工作区）**双层记忆架构。 ### 核心特性 - **智能分类**：晋升时根据内容自动分类到5个核心文件 - 性格、信念、行为边界 → `SOUL.md` - 身份、角色、使命 → `IDENTITY.md` - 主人偏好、互动规则 → `USER.md` - 工作流、操作规范、权限 → `AGENTS.md` - 工具环境、技术经验、项目背景 → `memory.md` - **安全备份**：写入目标文件前自动备份到 `F:\小师妹（龙虾）\` - **两级晋升**：项目级→用户级→全局，逐级验证 ### 工作空间自动发现 通过 `workbuddy.db` 数据库自动获取所有工作空间，无需手动维护注册表： ```python import sqlite3 db = sqlite3.connect(r'C:\Users\May\.workbuddy\workbuddy.db') workspaces = db.execute('SELECT path, last_opened_at FROM workspaces ORDER BY last_opened_at DESC').fetchall() ``` **数据来源**：`~/.workbuddy/workbuddy.db` 的 `workspaces` 表 - `path`：工作空间绝对路径 - `last_opened_at`：最后活跃时间（Unix 毫秒时间戳） **使用场景**： - 审查时自动扫描所有工作空间的项目级记录 - 跨工作空间汇总相似经验 - 识别哪些工作空间缺少 self-improve 目录 --- ## 一、操作模式配置 在 `SOUL.md` 中定义操作模式： ```yaml ## 自改进模式 模式: Active 选项: - Passive: 仅记录用户主动纠正或明确反馈 - Active: 同一模式出现 3 次后主动询问用户是否晋升（默认） - Strict: 每条记录都需要用户确认后才写入 ``` ### 环境变量配置 可通过环境变量自定义路径： ```bash # 备份目录（默认：F:/小师妹（龙虾）） SELF_IMPROVE_BACKUP_DIR="F:/小师妹（龙虾）" # 目标文件路径 SOUL_FILE="C:/Users/May/.workbuddy/SOUL.md" AGENTS_FILE="C:/Users/May/.workbuddy/AGENTS.md" ``` --- ## 二、记忆目录结构 ### 用户级（跨项目 · 全局有效） ``` C:\Users\May\.workbuddy\self-improve\ ├── LEARNINGS.md ← 通用学习记录 ├── ERRORS.md ← 通用错误记录 └── FEATURE_REQUESTS.md ← 功能请求 ``` ### 项目级（当前工作区 · 项目专属） ``` .workbuddy/self-improve\ ├── LEARNINGS.md ← 项目专属学习记录 ├── ERRORS.md ← 项目专属错误记录 └── FEATURE_REQUESTS.md ← 功能请求 .workbuddy/memory\ ├── MEMORY.md ← 长期记忆（提炼的核心经验） ├── 2026-05-13.md ← 日期记忆（日常工作记录） ├── 2026-05-12.md └── ... ``` ### 审查扫描范围 `review.py` 会扫描以下内容： | 文件类型 | 位置 | 统计方式 | |---------|------|----------| | LEARNINGS.md | `.workbuddy/self-improve/` | 统计 `- **ID**:` 条目 | | ERRORS.md | `.workbuddy/self-improve/` | 统计 `- **ID**:` 条目 | | FEATURE_REQUESTS.md | `.workbuddy/self-improve/` | 统计 `- **ID**:` 条目 | | MEMORY.md | `.workbuddy/memory/` | 统计 `##` 章节 | | YYYY-MM-DD.md | `.workbuddy/memory/` | 统计 `##` 章节（最近7天） | ### 检索优先级 1. 先查**用户级** `C:\Users\May\.workbuddy\self-improve\`（跨项目通用经验） 2. 再查**项目级** `.workbuddy/self-improve\`（当前项目特定经验） 3. 最后查 `MEMORY.md` 和 `memory.md`（长期记忆） ### 自动初始化 运行初始化脚本可自动为所有工作空间创建 `self-improve` 目录和标准模板： ```bash # 预览模式（不实际创建） python init_workspaces.py --dry-run # 正常初始化（只补充缺失的文件） python init_workspaces.py # 强制重新初始化（覆盖现有文件） python init_workspaces.py --force ``` **模板文件**： - `LEARNINGS.md` — 学习记录模板 - `ERRORS.md` — 错误记录模板 - `FEATURE_REQUESTS.md` — 功能请求模板 **注意**：模板文件使用 HTML 注释包含格式示例，审查脚本会自动排除注释内容，只统计实际记录。 --- ## 三、记录格式 每条记录统一格式： ```markdown - **ID**: LRN-YYYYMMDD-NNN **类型**: correction | insight | knowledge_gap | best_practice **内容**: [具体描述] **来源**: [任务/场景描述] **日期**: YYYY-MM-DD **优先级**: low | medium | high | critical **状态**: pending | in_progress | resolved | wont_fix | promoted **标签**: [标签1, 标签2] **关联**: [See Also 链接，可选] ``` > **ID 规则**: 类型前缀（LRN/ERR/FRQ）+ 日期 + 三位序号，如 `LRN-20260508-001` --- ## 四、自动检测与记录 ### 4.1 纠正检测 当用户说出以下关键词时，**自动记录到项目级 LEARNINGS.md**： | 关键词 | 记录类型 | |--------|---------| | "不对"、"不是"、"错了"、"实际上应该是…" | correction | | "我说的是…"、"更正一下"、"应该是" | correction | | "正确的做法是"、"你搞错了" | correction | | "不是这样"、"理解错了"、"方向不对" | correction | **记录内容**：错误的理解 vs 正确的做法，以及正确的参考来源 ### 4.2 错误检测 当遇到以下情况时，**自动记录到项目级 ERRORS.md**： | 场景 | 记录内容 | |------|---------| | Bash/PowerShell 命令退出码非 0 | 命令、错误信息、修复方案 | | Python 脚本抛出异常 | 异常堆栈、根因、修复方案 | | MCP 工具调用失败 | 工具名、错误信息、替代方案 | | API 返回错误 | 接口、错误码、处理方法 | ### 4.3 功能请求检测 当用户说出以下话时，**自动记录到项目级 FEATURE_REQUESTS.md**： - "你能不能…"、"我希望你能…"、"有没有办法…" - "加个功能"、"能加一个…吗"、"要是能…就好了" ### 4.4 最佳实践检测 在以下场景主动记录到 LEARNINGS.md： - 发现更高效的方案/工具/流程 - 用户表示"这样做很好"、"对，就这样" - 发现常用的固定模式或模板 - 用户告知某个特定规则或偏好 ### 4.5 知识过时检测 当用户说出以下话时，记录到 LEARNINGS.md（类型：knowledge_gap）： - "过时了"、"已经不适用了"、"现在改用…" - "旧版是…新版是…" --- ## 五、执行前检查 在执行**重要或高风险操作前**，必须： 1. **扫描用户级 ERRORS.md**：是否有同类错误的记录？若有，输出警告并在操作中避开 2. **扫描项目级 ERRORS.md**：是否有本项目特有的错误记录？ 3. **扫描用户级 LEARNINGS.md**：是否有最佳实践或偏好的提示？ 4. **将相关经验**以 "💡 提示：根据过往经验…" 的格式提醒用户 **重要操作**包括：文件删除/批量修改、程序安装/卸载、系统配置变更、数据迁移等。 --- ## 六、自我反思 ### 6.1 反思时机 每次完成以下任务**最后一个步骤时**，自动执行三步反思： - 多步骤任务完成后（生成报告、批量处理文件、数据分析等） - 用户给予纠正反馈后 - 修复错误后 - 发现可改进的常规做法时 ### 6.2 反思流程 ``` 步骤 1: 评估 → 本次任务的结果是否符合用户预期？ → 用户有没有给出明确反馈（认可还是纠正）？ → 有没有出现意外错误或异常？ 步骤 2: 识别改进点 → 如果有问题：下次如何避免？ → 如果顺利：有没有可以固化为最佳实践的做法？ → 有没有发现新的工具、方法或流程值得记录？ 步骤 3: 判断模式 → 这个问题以前是否出现过？（检查 self-improve/ 目录） → 如果是重复出现，是否达到了晋升条件？ → 如果不是新模式，只更新已有记录的"关联"字段 ``` ### 6.3 记录决策 | 反思结果 | 操作 | |---------|------| | 首次出现的问题 | 写入项目级对应日志文件 | | 重复出现的问题 | 更新现有记录的"关联"和"出现次数" | | 达到晋升条件 | 触发晋升流程，询问用户确认 | | 无价值内容 | 不记录 | --- ## 七、自动记录机制（SessionEnd Hook） ### 7.1 Hook 配置 在 `settings.json` 中配置 SessionEnd Hook，实现会话结束时自动记录经验： **用户级配置**（推荐）：`~/.workbuddy/settings.json` ```json { "hooks": { "SessionEnd": [ { "matcher": "other", "hooks": [ { "type": "command", "command": "python C:/Users/May/.workbuddy/skills/self-improving-agent/scripts/session_end_hook.py", "timeout": 30 } ] } ] } } ``` **项目级配置**：`<workspace>/.workbuddy/settings.json` ```json { "hooks": { "SessionEnd": [ { "matcher": "other", "hooks": [ { "type": "command", "command": "python C:/Users/May/.workbuddy/skills/self-improving-agent/scripts/session_end_hook.py", "timeout": 30 } ] } ] } } ``` ### 7.2 Hook 工作原理 1. **触发时机**：会话结束时（切换新会话、删除会话、清空会话等） 2. **输入数据**：通过 stdin 接收 JSON（包含 session_id、transcript_path、cwd） 3. **处理逻辑**： - 解析对话记录，分离用户和AI的发言 - **只分析用户消息**，忽略AI回复 - 用正则表达式检测纠正、错误、最佳实践等模式 - **去重机制**：同一对话只记录一次 - **上下文清理**：移除代码块、行内代码、特殊字符 4. **输出结果**：通过 stdout 返回 JSON（包含 systemMessage） 5. **记录保存**：自动写入当前工作空间的 `.workbuddy/self-improve/` 目录 ### 7.3 检测模式 | 类型 | 检测关键词 | 记录文件 | 说明 | |------|-----------|----------|------| | correction | "不对"、"错了"、"应该是"、"你搞错了" | LEARNINGS.md | 只检测用户发言 | | error | "失败了"、"报错了"、"出错了"、"不行"、"不能用" | ERRORS.md | 只检测用户发言 | | best_practice | "这样做很好"、"对，就这样"、"不错"、"完美"、"可以"、"好的" | LEARNINGS.md | 只检测用户发言 | **优化特性**： - **去重**：使用 `seen_contents` 集合，避免重复记录 - **排除AI发言**：只分析用户消息，避免误检测AI的"搞定"等 - **上下文清理**：移除代码块、行内代码、特殊字符，保留有意义的内容 ### 7.4 调试与测试 ```bash # 手动测试 Hook 脚本 echo '{"session_id":"test123","transcript_path":"/path/to/transcript.txt","cwd":"/path/to/workspace"}' | python scripts/session_end_hook.py # 查看调试输出（stderr） python scripts/session_end_hook.py 2>&1 ``` ### 7.5 动态工作空间支持 Hook 脚本自动处理工作空间的增减变化： | 场景 | 处理方式 | |------|----------| | 新增工作空间 | 自动创建 `.workbuddy/self-improve/` 目录和模板文件 | | 删除工作空间 | review.py 扫描时自动跳过不存在的目录 | | 临时目录 | 同样会创建记录（不影响主流程） | **实现机制**： - `ensure_template()` 函数在首次写入时自动创建带头部的模板文件 - 目录和文件都是惰性创建，无需提前运行初始化脚本 ### 7.6 注意事项 - **超时设置**：建议 30 秒，避免阻塞会话关闭 - **路径格式**：使用正斜杠 `/` 或双反斜杠 `\\`，避免转义问题 - **编码问题**：对话记录文件应为 UTF-8 编码 - **误报处理**：自动检测可能有误报，建议定期人工审核 --- ## 八、晋升机制 ### 7.1 第一级：项目级 → 用户级（跨项目晋升） **条件**（同时满足）： 1. 同一学习内容在项目级 `self-improve/` 中出现 **3 次以上** 2. 跨 **2 个以上不同任务** 3. 内容已标记为 `resolved` 且有可用修复方案 4. 内容具有**跨项目适用性**（非项目特有规则） **操作**： 1. 晋升前**询问用户确认**："📈 发现一条重复出现的经验，建议晋升到全局记忆，是否同意？" 2. 用户同意后，格式化为用户级格式，追加到用户级对应文件 3. 添加晋升标记：`promoted: YYYY-MM-DD to user-level` 4. 将项目级条目状态更新为 `promoted` ### 7.2 第二级：用户级 → 全局（最终沉淀） **条件**（同时满足）： 1. 同一内容在用户级 `LEARNINGS.md` 中状态为 `resolved` 2. 出现 **5 次以上** 且时间跨度超过 **7 天** 3. 内容具有高度通用性（工具使用习惯、通用工作流、普遍规范） **分类写入规则（5个核心文件）**： | 内容类型 | 关键词示例 | 目标文件 | 用途 | |---------|-----------|---------|------| | 性格、信念、行为边界 | 性格、信念、边界、态度、风格、语气 | `SOUL.md` | 灵魂文件 | | 身份、角色、使命 | 身份、角色、使命、名称、定位 | `IDENTITY.md` | 身份设定 | | 主人偏好、互动规则 | 主人、称呼、偏好、互动、沟通 | `USER.md` | 主人档案 | | 工作流、操作规范、权限 | 流程、步骤、规范、操作、权限、安全 | `AGENTS.md` | 工作规范 | | 工具环境、技术经验、项目背景 | 工具、环境、配置、项目、技术、经验 | `memory.md` | 全局记忆 | **操作**： 1. 晋升前**询问用户确认**："📈 发现 X 条经验可沉淀到全局，是否同意？" 2. 用户同意后，根据内容关键词自动分类 3. **写入前备份目标文件**到 `F:\小师妹（龙虾）\`（带时间戳） 4. 格式化为规则形式，写入对应目标文件 5. 添加晋升标记：`promoted: YYYY-MM-DD to global` 6. 将用户级条目状态更新为 `promoted` ### 7.3 定期审查 通过 Automation 定时任务触发审查脚本： - **每日**：扫描项目级 `self-improve/`，检查可晋升条目 - **每周**：扫描用户级 `self-improve/`，检查可沉淀到 memory.md 的条目 - **每月**：运行清理脚本，归档过期条目 --- ## 八、手动管理命令 | 命令 | 功能 | |------|------| | `📖 我记住了什么` | 显示你从我这里学到了哪些经验 | | `📖 查看学习记录` | 显示用户级和所有工作空间的学习记录摘要 |