自动进化模式

自动进化模式（Auto-Evolution Mode）是 DevOps Hand 的可选能力：让 daemon 周期性地监视 GitHub 仓库并自主行动——review 打开的 PR、triage 打开的 issue，并通过 Brainstorm → Architect → PRD → Implement（BMAD）流水线，把已归类的 bug 修复或功能需求产出为草稿 PR。

目录

• 它做什么
• 它在平台中的定位
• 安装与配置
• GitHub Token 权限
• 配置项参考
• 安全模型
• BMAD 流水线四阶段
• 可观察性
• 故障排查
• 它不做什么

它做什么

每过 evolution_check_interval（默认 15 分钟），Hand 进入 Phase 7，对 evolution_repos 里每个 owner/repo 对：

1. Review 打开的 PR —— 拉 diff，调用现有的 code-reviewer sub-agent 生成结构化判定，把单条 COMMENT review（或对阻塞性问题用 REQUEST_CHANGES，绝不自动 APPROVE）发回 GitHub。当前 head_sha 已 review 过的 PR 自动跳过。
2. Triage 打开的 issue —— 优先用 label（bug / feature / question / wontfix），label 缺失时回退到一次性单轮 LLM 分类。结果限定为 bug-fix | feature | needs-info | skip。
3. 实现可行动的 issue —— 把 bug-fix 与 feature 分发给 implementer sub-agent，跑 BMAD 流水线（深度由 bmad_strictness 决定）并提一个 draft PR。

机器人作者（dependabot、renovate 等）的 PR 走 token-cheap 短路：记录但不做深度 review。变更超过 200 个文件的 PR 直接交人审，不浪费 token 去 review 一个 reviewer agent 根本 ground 不住的 diff。

它在平台中的定位

LibreFang 内置三套自治型自我改进子系统，设计上互补不重复：

三者构成平台「代码进化 / memory 整合 / 工作流提炼」三件套。每一个都可独立 gate、独立关闭。同样的设计模式可参考 docs/architecture/skill-workshop.md（应用在 skill 捕获上）。

安装与配置

Hand 定义托管在 librefang/librefang-registry 的 hands/devops/ 目录。安装、配置、激活：

# 1. 安装或更新 DevOps Hand
librefang hand install devops
# 或，已安装时：
librefang hand update devops

# 2. 提供 GitHub Personal Access Token（权限见下节）
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# 或在 ~/.librefang/.env 中写 GITHUB_TOKEN=...

# 3. 配置 4 个进化相关设置
librefang hand config devops auto_evolve=true
librefang hand config devops evolution_repos=librefang/librefang,librefang/librefang-registry
librefang hand config devops evolution_check_interval=15min
librefang hand config devops bmad_strictness=standard
# 可选：调整单 PR 文件改动上限
librefang hand config devops max_changed_files=30

# 4. 激活（已激活则重启）
librefang hand activate devops

Hand 层面完整的配置矩阵（每个选项的作用与默认值）见 registry 的 hands/devops/README.md。本页聚焦平台行为，不重复 Hand 文档。

GitHub Token 权限

公共仓库 —— fine-grained token 需要：

• Pull requests —— read & write（发 review、开 draft PR）
• Issues —— read & write（triage 评论、在原 issue 上交叉链接）
• Contents —— read & write（推送实现分支）
• Metadata —— read（解析 default_branch 用于建 PR）

私有仓库 —— 追加 classic repo 作用域，并确保目标 repo 在 evolution_repos 中显式列出。私有 fork 仍按私有仓库对待。

配置项参考

安全模型

自动进化运行在三道无法被运维人员误关的护栏下：

1. 仅 draft PR。 implementer 创建的 PR 都是 draft: true。Hand 永不把 PR 标 ready-for-review，永不 merge。人始终是 ready 标识与合并按钮的唯一执行者。

2. 绝不写保护分支。 implementer 不向 main、master、trunk 或任何受 GitHub ruleset 保护的分支推送；不使用 --force、--no-verify、--no-gpg-sign、--amend 对远程分支操作。上游的 pre-commit / pre-push / commit-msg 钩子通过 git config core.hooksPath 发现并执行，钩子失败直接 abort 任务，不重试。

3. 路径安全底线。 以下情况 implementer 不提交，而是写入 devops_queue.json 交人审：

• Cargo.toml 中的 workspace members = [...] 改动
• 迁移文件（任何 */migrations/*、*/migrate/* 或 *.sql）
• 秘密相关路径（.env*、*.pem、*.p12、id_rsa、id_ed25519、credentials*、secrets*、vault_*.key）
• 超过 max_changed_files（默认 30）个文件

此外每个进化 tick 主动控制在每 turn token 预算的约 70% 内，给后续 tick 留出 headroom，避免某次流水线狂飙拖死 Hand 其余工作。

BMAD 流水线四阶段

implementer 被分发到可行动 issue（bug-fix 或 feature）时，跑 4 阶段流水线，深度随 bmad_strictness 变化：

每阶段的产物追加到与实现一同提交的 BMAD.md，让 reviewer 看到推导出 diff 的过程。

修 bug 时实现阶段 严格 test-first：可复现的失败测试在修复之前先 commit（在同一个 PR 内）。新功能时测试与代码同提。

strict 模式 queue 卡口。 每阶段之间，implementer 把产物写进 devops_queue.json（status: "pending"），然后结束当前 turn。下一个 continuous tick 会重新读取 queue：若用户已 out-of-band 把 status 翻成 approved，从下一阶段继续；否则跳过这个 issue，下一 tick 再查。turn 内没有任何 polling 或 sleep——queue 设计上跨 turn 持久化。

可观察性

dashboard（http://127.0.0.1:4545）新增三个指标：

• PRs Reviewed —— 成功发出的 review 总数（devops_hand_prs_reviewed）
• Issues Processed —— triage 过的 issue 总数，不论结果（devops_hand_issues_processed）
• Draft PRs Opened —— 自动生成的 draft PR 总数（devops_hand_draft_prs_opened）

Hand 同时发布 4 个 advisory 事件，订阅方（dashboard、审计日志、下游 Hand）可按需消费：

每个 PR / issue 的状态存在 memory 中（devops_pr_review_<owner>_<repo>_<num> 与 devops_issue_state_<owner>_<repo>_<num> 等键），daemon 重启后进度仍在。

故障排查

「没动静」

按顺序查：

1. auto_evolve 真的开了吗 —— librefang hand config devops 看 setting 是否为 true。
2. evolution_repos 非空且格式正确 —— owner/repo 对，不带 https://，不带末尾斜杠。
3. GITHUB_TOKEN 在 daemon 的环境里，不只是当前交互 shell。若 daemon 启动早于 export，重启 daemon。
4. 频率 gate 还没到 —— 看 memory 中的 devops_evolution_cursor_<owner>_<repo>，若 last_tick_at 距现在还不到 evolution_check_interval，下一 tick 尚未到。

「review 发出去了但 verdict 怪怪的」

reviewer sub-agent 返回 approve | request_changes | block | comment_only 之一。GitHub 事件映射：

• approve → 发为 COMMENT（Hand 永不自动 APPROVE，得由人来）
• request_changes → REQUEST_CHANGES
• block → REQUEST_CHANGES，body 前置 **Reviewer flagged as BLOCKING — escalate to a maintainer**
• comment_only / 未知值 → COMMENT

如果 REQUEST_CHANGES 比预期多，查 review body 里的 summary 字段或 memory 中的 devops_pr_review_<owner>_<repo>_<num>。

「draft PR 提了但 CI 里 cargo 失败」

implementer 推送前会跑本地 lint/test gate（通常是 cargo clippy --workspace --all-targets -- -D warnings 与 cargo test -p <crate>）。仅 CI 失败通常是：

• 项目 CI 跑了 implementer 没跑的命令（自定义 integration、xtask 任务）—— 通过 justfile 或 CONTRIBUTING.md runbook 给 agent 看到这些命令
• implementer 本地缓存与 CI 干净构建不同 —— 多半是 implementer 没 commit Cargo.lock 的再生成；BMAD 流水线在依赖相关改动后应重新 stage Cargo.lock

「Hand 想动 Cargo.toml / migration / secrets 然后停下来了」

是路径安全底线在工作。查 devops_queue.json；如果改动确实必要，手动从队列取出、out-of-band 完成编辑，implementer 下次 tick 会基于干净 tree 继续。

「钩子拒绝 implementer 的 push」

最常见的是上游禁止 Co-Authored-By: Claude 之类的 AI 归属。implementer 的 prompt 禁止 LLM 厂商归属（Claude / GPT / 🤖 等），但流程归属（Generated by DevOps Hand → implementer）允许，用于可追溯性。如果上游连后者也拒绝，定制 Hand 定义里的 commit-message 模板——不要加 --no-verify（Hand 的安全底线本身会拒绝）。

它不做什么

为了设定合理预期：

• 不 merge PR。永远人来 merge。
• 不 把 draft PR 标 ready-for-review。
• 不 推送 main / master / 保护分支。
• 不 处理私有 repo —— 除非 PAT 有 repo 作用域且 repo 在 evolution_repos 中。
• 不 改 Cargo.toml workspace members、迁移文件、秘密路径，或单 PR 改动超过 max_changed_files。
• 不 在单 tick 内消耗超过约 70% 每 turn token 预算。

Hand 级完整规范与每个 sub-agent 的提示词源码：hands/devops/HAND.toml 与 hands/devops/SKILL.md，均在 registry 仓库里。