ruflo-autopilot 完全指南：基于 /loop 的持久化自主任务闭环与学习预测

ruflo-autopilot 完全指南：基于 /loop 的持久化自主任务闭环与学习预测

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

ruflo-autopilot 是 Ruflo 生态中的自主任务完成插件，它将 Ruflo 的 10 个autopilot_*MCP 工具与 Claude Code 原生的/loop+ScheduleWakeup机制组合起来，构建出持久化、缓存感知（cache-aware）的任务完成循环。本文基于插件 README 与源码、契约（ADR-0001）与验证脚本，完整讲解安装方式、命令与技能用法、10 个 MCP 工具的底层实现、缓存唤醒的 270 秒设计依据、AgentDB 命名空间协调原则，以及如何通过结构冒烟测试把插件行为固化为可验证的契约。读完本文，你将掌握如何用 ruflo-autopilot 开启跨会话的自主迭代、用学习与预测驱动"下一最优动作"、并自行验证插件契约是否完好。

一、插件定位：为"长期目标"补上缺失的自主循环调度器

从 autopilot-tools.ts 的源码注释可以确认插件的核心动机：Claude Code 本身没有原生的自主循环调度器（"Claude Code has no native autonomous-loop scheduler"），在跨会话的长期目标（long-horizon goals）场景下，任务完成后缺少自动"重新唤醒"的机制。ruflo-autopilot 正是为此而生：

• 自主循环（Autonomous loops）：启用 autopilot 后，/loop驱动迭代式任务完成；
• 进度追踪（Progress tracking）：监控 team-tasks、swarm-tasks 与文件清单（file-checklist）三类任务来源；
• 学习（Learning）：通过 AgentDB 从已完成任务中发现成功模式；
• 预测（Prediction）：基于当前状态与已学模式预测最优下一步动作；
• 缓存感知（Cache-aware）：以 270 秒的ScheduleWakeup心跳保持 prompt cache 在迭代间保持温热。

插件元数据位于 plugin.json，当前版本0.2.1，关键词覆盖autopilot、loop、autonomous、learning、prediction、progress-tracking、cache-aware、mcp。

二、安装与启用

1. 从市场安装插件

/plugin marketplace add ruvnet/ruflo /plugin install ruflo-autopilot@ruflo

2. 快速上手三步

1. 启用 autopilot：执行/autopilot enable，或通过 MCP 调用autopilot_enable；
2. 配置限制：/autopilot config --maxIterations 50 --timeoutMinutes 30（参数名与autopilot_configMCP 工具签名一致）；
3. 开启循环：启用后，以autopilot-loop技能启动一个/loop开始自主迭代；每次迭代用ScheduleWakeup以 270 秒延迟做缓存温热的调度。

3. 兼容性要求

• CLI 锁定：固定到@claude-flow/cliv3.6 的 major+minor 版本；
• MCP 表面：即下文 10 个autopilot_*工具；
• 验证契约：bash plugins/ruflo-autopilot/scripts/smoke.sh是行为契约（详见第六节）。

三、命令与技能：两种驱动方式

1. 两个斜杠命令

/autopilot— 启用、配置或禁用自主任务完成（见 commands/autopilot.md）：

无参数时，命令通过autopilot_status展示当前状态。启用后即进入/loop迭代，并以 270s 延迟的ScheduleWakeup做缓存温热调度。

/autopilot-status— 快速进度摘要（见 commands/autopilot-status.md），内部调用autopilot_status与autopilot_progress两个 MCP 工具，展示：

• 启用/禁用状态；
• 迭代数 vs 最大迭代数；
• 已耗时间 vs 超时限制；
• 按来源（team-tasks、swarm-tasks、file-checklist）统计的任务完成情况；
• 整体完成百分比。

2. 两个技能（Skills）

autopilot-loop（SKILL.md）— 单次自主迭代的标准流程：

1. 检查状态：autopilot_status；
2. 若全部任务完成或达到最大迭代数：调用autopilot_disable并停止；
3. 获取预测：autopilot_predict得到最优下一步动作；
4. 执行预测任务（派生 Agent、编辑代码、运行测试等）；
5. 记录日志：autopilot_log；
6. 调度下一轮：ScheduleWakeup({ delaySeconds: 270, reason: "next autopilot iteration" })。

技能声明了最小工具集（allowed-tools），只开放autopilot_status、autopilot_predict、autopilot_log、autopilot_progress、autopilot_disable、ScheduleWakeup、Agent，杜绝通配符授权。

autopilot-predict（SKILL.md）— 用已学模式挑选下一个任务：

1. 调用autopilot_predict获取推荐动作；
2. 置信度 > 0.7 → 直接执行预测；
3. 置信度 < 0.7 → 查autopilot_progress的任务明细，挑选最高优先级的未完成任务；
4. 完成后调用autopilot_learn更新模式。

在/loop内运行时：高置信度立即执行，低置信度回退到任务列表优先级，无任务剩余则禁用 autopilot 并退出循环。

3. 配套 Agent：autopilot-coordinator

插件还附带 autopilot-coordinator.md（模型推荐 sonnet），其完整工作流为：autopilot_enable→autopilot_config设限 →autopilot_progress查看任务明细 →autopilot_predict智能选任务 → 执行（必要时委派专业 Agent）→ 每任务后 270sScheduleWakeup→ 全部完成或达限后autopilot_disable。决策逻辑覆盖"全部完成 / 达最大迭代 / 超时 / 高置信度 / 低置信度"五种分支，并给出跨会话记忆集成方式：

npx @claude-flow/cli@latest memory store --namespace patterns --key "autopilot-PATTERN" --value "WHAT_WORKED" npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true npx @claude-flow/cli@latest memory search --query "TASK_TYPE patterns" --namespace patterns

四、MCP 表面：10 个 autopilot_* 工具的源码级剖析

全部 10 个工具定义并导出在 autopilot-tools.ts，共享同一套autopilot-state.ts状态机与事件日志。

1. 状态与进度：autopilot_status/autopilot_progress

两个工具都基于loadState()+discoverTasks(state.taskSources)，通过isTerminal(t.status)判定任务是否进入终态。autopilot_status返回enabled、sessionId、iterations、maxIterations、timeoutMinutes、elapsedMs、按来源聚合的任务完成百分比；autopilot_progress则把任务按source字段分组，输出overall（总数/完成数/百分比）与bySource（每类来源的完成数、总数与任务明细）。

2. 启停与重置：autopilot_enable/autopilot_disable/autopilot_reset

• enable置enabled = true、重置startTime与iterations，并向事件日志追加enabled事件；
• disable置enabled = false，记录disabled事件及当时的迭代数；
• reset清空iterations、history、lastCheck并重启动计时器——README 明确其用途是测试（清空已学模式与进度）。

3. 配置：autopilot_config

可配置三项参数，均有严格校验：

• maxIterations：1–1000，超出范围由validateNumber拒绝并回退到旧值；
• timeoutMinutes：1–1440；
• taskSources：必须是 autopilot-state.ts 中VALID_TASK_SOURCES集合（team-tasks、swarm-tasks、file-checklist）的非空子集，非法来源会返回isError: true及错误原因和合法来源列表。

默认任务来源为三者全开（见 autopilot-state.ts）。

4. 学习与预测：autopilot_learn/autopilot_history/autopilot_predict

这三个工具通过tryLoadLearning()接入 AgentDB 的AutopilotLearning组件：

• learn：并行调用getMetrics()与discoverSuccessPatterns()，返回学习指标与发现的成功模式；若 AgentDB 未初始化则返回available: false；
• history：以query（必填，经validateText校验）与limit（默认 10，1–100）调用recallSimilarTasks(query, limit)检索历史完成回合；
• predict：优先用predictNextAction(state)做模型预测；无学习组件时走启发式回退——无未完成任务返回{ action: 'none', confidence: 1.0 }，否则返回"下一个待办任务"动作，置信度固定 0.5 并标注Heuristic (learning not available)。

五、缓存感知的 /loop 集成：为什么是 270 秒

README 给出了明确的数值依据（README.md）：

推荐的兜底心跳（fallback heartbeat）是270 秒——低于 5 分钟（300 秒）的 prompt-cache TTL，因此下一次唤醒可以直接命中缓存的对话上下文。超过 300 秒会产生 cache-miss；而取整到 5 分钟恰恰是"最坏情况"（worst-of-both case）。

在事件驱动型循环中，可以挂载一个Monitor作为事件触发，让 270 秒唤醒仅充当安全网（safety net）。autopilot-loop技能中的调度语句即为此模式：

ScheduleWakeup({ delaySeconds: 270, reason: "next autopilot iteration" })

六、命名空间协调：autopilot-patterns 的所有权

为避免跨插件记忆冲突，插件声明了对 AgentDBautopilot-patterns命名空间的所有权（kebab-case，遵循 ruflo-agentdb ADR-0001 中的 "Namespace convention"）。保留命名空间pattern、claude-memories、default不得被遮蔽（MUST NOT be shadowed）。

autopilot_learn通过agentdb_pattern-store语义写入该命名空间，其输出接入 ruflo-intelligence ADR-0001 描述的 4 步流水线：RETRIEVE → JUDGE → DISTILL → CONSOLIDATE。

七、验证契约：smoke.sh 的 10 项结构检查

插件的核心工程实践是以冒烟测试作为行为契约。运行：

bash plugins/ruflo-autopilot/scripts/smoke.sh # Expected: "10 passed, 0 failed"

smoke.sh 的 10 项检查覆盖插件的全部契约要素：

1. plugin.json声明版本 0.2.1，且包含prediction、progress-tracking、cache-aware、mcp关键词；
2. 10 个autopilot_*工具名全部在插件 Markdown 文档中被引用；
3. autopilot-loop与autopilot-predict两个技能存在，且 frontmatter 含name:、description:、allowed-tools:；
4. /autopilot与/autopilot-status两个命令文件存在；
5. README 固定@claude-flow/cli到 v3.6；
6. README 含命名空间协调块（引用 ruflo-agentdb 与 "Namespace convention"）；
7. README 记录 270 秒缓存感知 ScheduleWakeup；
8. README 声明autopilot-patterns命名空间所有权；
9. ADR-0001 存在且状态为Accepted；
10. 技能文件中没有通配符工具授权（allowed-tools: *不允许）。

八、架构决策：ADR-0001 契约要点

ADR-0001 — ruflo-autopilot plugin contract（状态Accepted，2026-05-09 更新）把上述实践固化为决策记录，核心决策包括：补全 README 的 Compatibility / Namespace coordination / Verification / Architecture Decisions 章节；版本从 0.1.0 升至 0.2.0 并扩充关键词；以 10 项结构检查的smoke.sh作为契约门槛；将 270 秒缓存温热心跳模式契约化，供其他插件的循环指南引用。其积极影响是插件进入统一的契约节奏；中性影响是"不新增 MCP 工具、不新增技能，仅文档 + 冒烟测试"；行为上无实质变化。

九、一次完整的自主迭代复盘

综合命令、技能与协调 Agent 的逻辑，一次典型闭环如下：

1. /autopilot enable或autopilot_enable开启持久化完成模式；
2. autopilot_config({ maxIterations: 50, timeoutMinutes: 30 })设定安全边界；
3. autopilot_progress按 team-tasks / swarm-tasks / file-checklist 分组查看任务分布；
4. autopilot_predict输出推荐动作——若置信度 > 0.7 直接执行，否则按任务优先级手动挑选；
5. 执行任务（可委派给专业 Agent）；
6. autopilot_log追加结构化日志，完成后调用autopilot_learn更新模式；
7. ScheduleWakeup({ delaySeconds: 270 })安排下一轮，利用 prompt cache 温热避免上下文丢失；
8. 全部完成或触达限制时autopilot_disable收尾，输出完成摘要。

该循环的三大支柱——持久化状态（autopilot-state.ts）、10 工具 MCP 表面（autopilot-tools.ts）、契约化验证（smoke.sh + ADR-0001）——共同保证了跨会话长期目标可以被可靠地、可预测地、可持续地推进。

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo