self-improving-agent

自我改进 Agent

将已完成工作中的证据转化为小幅、可审计的行为变更。默认结果是候选项或不做变更，而不是自动改写技能。

在以下情况下使用此技能

• 工具或工作流发生了可能再次出现的故障。
• 用户纠正了假设、要求或操作规则。
• 同一种变通方法出现了不止一次。
• 有针对性的测试证明了更好的可复用方法。
• 用户要求审核或整合学习候选项。

不要将其用于常规会话摘要、原始对话记录存储、没有证据支持的推测性想法，或应归入项目文档的项目事实。

必需结果

每次运行最终都必须处于以下一种状态：

1. candidate：可复用，但尚未验证。
2. validated：代表性证据支持该经验，但尚未声称已更改任何所属项。
3. applied：已验证的经验已应用到一个指定的持久所属项，并附有变更引用。
4. rejected：已被证伪、不安全、过于具体或已过时。
5. superseded 或 rolled_back：已应用或已验证的经验被替换或回退。
6. no-delta：未发现可复用的行为变更。
7. open-question：证据不足，并已指出缺少的证明。

产物本身不能证明改进。已应用的经验必须改变未来行为，并通过代表性检查来证明这种改变。

启动包

在编辑持久指导内容之前，说明：

• 未来行为：Agent 下次应做出哪些不同的行为。
• 代表性任务：一个现在应能成功完成的具体场景。
• 证据：当前来源、失败输出、用户纠正或有针对性的测试。
• 所属项：负责该行为的单个技能、指令文件、脚本或运行时组件。
• 写入边界：允许更改的文件，以及必须保留在本地的信息。
• 证明：用于确认新行为的命令、评估或审核。

如果任何一项未知，则记录为候选项，并在验证或应用之前停止。

生命周期

1. 捕获信号

优先记录事实，而非解读。只记录最少量的可复用摘要；不要复制对话记录、工具输入、凭据、私有路径或客户数据。

使用 apb init --hooks 显式启用的 Claude Code 故障钩子可以调用：

agent-playbook self-improve

手动纠正或成功案例需使用明确的摘要和证据标签：

apb self-improve capture \
  --kind correction \
  --summary "Verify the current source before relying on cached state" \
  --evidence "focused-test"

CLI 会将脱敏事件和去重后的候选项存储在 ~/.agent-playbook/self-improvement/ 下。可通过 AGENT_PLAYBOOK_DATA_DIR 或 --data-dir 覆盖根目录。

2. 评估可复用性

只有在以下条件全部满足时才保留候选项：

• 描述的是未来行为，而不只是已经发生的事。
• 不仅对某个私有任务或代码仓库有用。
• 不与当前权威来源冲突。
• 存在范围明确的所属项和切实可行的验证路径。

使用 apb behavior inbox 检查按优先级排列的队列。重复证据会增加出现次数，但不会自动提高真实性。使用 apb behavior owners <candidate-id> --repo . 获取本地建议，但应将每条结果视为待审核候选项，而不是归属决定。

3. 验证

选择能够证伪候选项的最小证明，将其编码为可执行产物，并使用 apb self-improve eval 运行。有关架构和安全边界，请参阅 references/eval-artifact.md。

候选项	最低证明要求
提示词或工作流规则	代表性提示词加评估标准
CLI/运行时行为	有针对性的自动化测试
外部集成	根据当前文档/运行时进行实时能力检查
安全规则	证明不安全路径会被阻止的反向测试
重复出现的启发式规则	多次独立事件或明确的人工确认

区分事实、假设和缺失证据。仅通过结构验证，无法证明指导内容在语义上仍然有效，或可由宿主执行。

4. 验证、应用或拒绝

先运行产物。如果可以安全地复现先前行为，建议使用基线场景；至少需要一个候选场景：

apb self-improve eval cand-123 --artifact behavior-eval.json

apb self-improve review cand-123 \
  --decision validate \
  --reason "baseline reproduced and candidate scenarios passed" \
  --eval-result /path/printed/by/the/eval/command.json

验证仅接受针对同一候选项、由 CLI 生成且通过的评测结果。验证并不声称运行时行为发生了变化。

在编辑所属对象之前，先生成本地行为变更提案：

apb behavior proposal cand-123 \
  --owner "skill:self-improving-agent" \
  --output behavior-proposal.md

提案包含行为差异意图、评测证据、验收标准、隐私边界和回滚计划。它不会编辑所属对象，也不会创建远程拉取请求。

仅更改一个持久所属对象后，单独记录应用情况：

apb self-improve review cand-123 \
  --decision apply \
  --reason "installed after the focused test passed" \
  --owner "skill:self-improving-agent" \
  --change-ref "commit:abc123"

其他决策：

apb self-improve review cand-123 --decision observe --reason "needs a second episode"
apb self-improve review cand-123 --decision reject --reason "project-specific exception"

将更改应用到范围最小的所属对象：

1. 当行为可以通过执行进行约束时，使用可执行测试、脚本或验证器。
2. 当需要 Agent 判断时，使用所属技能或其参考资料。
3. 仅在项目范围的约束下使用项目说明。
4. 将应检索而非始终加载的持久事实记录在知识笔记中。

绝不要在捕获信息时，暗中修改仓库规则、发布软件包或触发外部操作。

5. 证明闭环

应用后运行代表性任务。报告：

• 候选项 ID 和最终状态；
• 使用的证据及仍存疑之处；
• 更改的持久所属对象；
• 可执行评测结果和产物哈希；
• 回滚路径。

如果新规则未改变代表性行为，请将其还原或拒绝。

知识导出

将已应用规则和未关闭的候选项导出为 Markdown，供 Obsidian 或其他本地知识系统使用：

apb self-improve export --output /path/to/vault/Agent/Learning.md

导出仅是输出端，而非事实来源。候选项和有效规则的状态仍以 CLI 数据目录中的结构化、可审计数据为准。

宿主边界

技能描述判断；宿主适配器提供事件和操作。声称支持之前，请检查当前宿主：

• Claude Code：仅通过明确执行 apb init --hooks 安装确定性失败钩子。
• Codex、Gemini、DeepSeek Harness：支持技能分发；学习事件的接线方式取决于各宿主当前的扩展 API。
• 不受支持的钩子必须保持手动操作或采用特定适配器，绝不能通过未公开说明的行为进行模拟。

使用 apb conformance 检查本地静态契约。已证明的分发或钩子配置并不能证明宿主发现或运行时调用；在观测到的宿主运行提供范围明确的证据之前，这些状态仍为未验证。

模式和适配器契约请参阅 references/learning-lifecycle.md。更改此技能时，请使用 evals/cases.json 和 evals/rubric.md。

完成检查清单

• 已明确作出候选项／无变化的决策。
• 存储的文本精简、已脱敏且便于迁移。
• 在相关情况下，已检查当前权威来源。
• 验证使用了针对同一候选项、通过的可执行评测结果。
• 应用记录了一个持久所属对象和具体变更引用。
• 应用后已测试代表性行为。
• 未将任何私有项目信息纳入公开技能资源。