全域项目 Auto-Research 持续运行模式实施指南

执行摘要

研究目标：探索如何将 auto-research 持续运行模式引入全域项目，覆盖研究报告生成、系统优化、产品迭代等多种场景，并在 pi-agent、Claude Code、CodeBuddy、OpenCode 等多平台环境中实现可靠运行。

核心发现：

1. 方案可行性：Auto-research 持续运行模式在技术上完全可行，已有成熟的 Ralph Loop 模式可供参考，需要根据目标平台的特性进行适配

2. 实施路径：

   • 方案 A（原生集成）：适用于支持 Stop Hook 机制的平台（如 Claude Code），实施周期 1-2 天
   • 方案 B（外部循环）：适用于所有平台，实施周期 5-7 天，完全可控

3. 跨平台适配：不同平台（OpenCode、CodeBuddy、pi-agent）在 Stop Hook 支持、会话管理、输出格式等方面存在差异，需要针对性设计

4. 防中断机制：通过双重退出检测、断路器保护、状态持久化、会话连续性四层机制，可实现 ≥95% 的中断恢复成功率

5. 防循环陷阱：五层保护策略（双重条件检测、断路器、速率限制、最大迭代限制、会话过期）可有效防止无限循环

推荐实施路径：

关键成功因素：

• 平台能力验证必须在实施前完成
• 双重退出检测机制是防过早退出的核心
• 断路器是防成本失控的关键
• 状态持久化是中断恢复的保障

报告结构

01-context-and-goals.md - 背景与目标

• Auto-research 模式的演进历程（从 Ralph Loop 到现代实现）
• 全域项目应用场景（研究报告、系统优化、产品迭代）
• 多平台环境概览（pi-agent、Claude Code、CodeBuddy、OpenCode）
• 核心挑战：中断恢复与循环陷阱

02-technical-architecture.md - 技术架构对比

• Ralph Loop 核心技术机制详解
• 四大平台能力对比矩阵
• Stop Hook 机制在各平台的支持情况
• 会话管理与状态持久化差异分析

03-implementation-solutions.md - 实施方案详解

• 方案 A：原生集成（含完整代码示例）
• 方案 B：外部循环控制（含完整代码示例）
• 跨平台适配策略
• 各平台具体实施步骤

04-safety-mechanisms.md - 安全机制设计

• 防中断机制：状态持久化、会话恢复、错误处理
• 防循环陷阱：双重退出检测、断路器、速率限制
• 监控与告警体系
• 故障恢复流程

05-risk-and-conclusion.md - 风险评估与结论

• 各平台实施风险分析
• 成本与效益评估
• 实施路线图建议
• 后续研究方向

核心技术机制概览

flowchart TB
    subgraph "Stop Hook 机制"
        A[AI 执行任务] --> B{尝试退出?}
        B -->|是| C[Stop Hook 拦截]
        C --> D{双重条件检测}
        D -->|满足| E[允许退出]
        D -->|不满足| F[重新注入提示词]
        F --> A
    end
    
    subgraph "双重退出检测"
        G[启发式指标<br/>≥2 完成关键词] --> H{逻辑与}
        I[显式信号<br/>EXIT_SIGNAL: true] --> H
        H -->|两者满足| J[判定完成]
        H -->|任一不满足| K[继续循环]
    end
    
    subgraph "断路器保护"
        L[监控循环状态] --> M{停滞检测}
        M -->|3 次无进展| N[打开断路器]
        M -->|5 次相同错误| N
        N --> O[暂停循环<br/>通知用户]
    end
    
    subgraph "状态持久化"
        P[会话 ID<br/>.ralph_session] --> Q[状态 JSON<br/>.current_status.json]
        R[输出归档<br/>outputs/loop_*.txt] --> S[历史记录<br/>.ralph_session_history]
    end

平台能力对比

快速决策树

开始
  ↓
目标平台是否支持 Stop Hook?
  ├─ 是 → 实施方案 A（原生集成）
  │        ↓
  │    1. 配置 Stop Hook
  │    2. 初始化项目结构
  │    3. 启动 Ralph 循环
  │        ↓
  │    完成（1-2 天）
  │
  └─ 否 → 实施方案 B（外部循环）
           ↓
       1. 编写 Shell 循环控制器
       2. 实现状态管理器
       3. 创建提示词生成器
       4. 启动监控面板
           ↓
       完成（5-7 天）

参考资料

核心参考

1. frankbria/ralph-claude-code - Ralph Loop 官方实现
2. Ralph Wiggum 技术详解 - Stop Hook 机制深度解析
3. OpenCode 文档 - OpenCode CLI 使用指南

本报告前置研究

4. Ralph-Loop 可行性研究 - 本项目的 Ralph-Loop 可行性分析基础

报告版本：v1.0
生成日期：2026-03-20
研究方法：技术文献分析、代码审查、架构设计、跨平台对比
文档语言：中文（技术术语保留英文）