sleepingzzzz

---
name: long-running-agent
description: |
  长时间运行智能体编排框架。让AI智能体能够跨会话持续工作并完成复杂任务。
  
  使用场景：
  - 用户说 "创建一个新项目"、"开始一个项目"、"新建任务"、"启动项目"
  - 用户说 "继续项目"、"继续工作"、"接着做"、"继续开发"
  - 用户说 "更新进度"、"记录进度"、"保存进度"
  - 用户说 "项目状态"、"查看进度"、"做到哪了"
  - 用户说 "列出项目"、"所有项目"、"我有哪些项目"
  - 用户说 "暂停项目"、"存档项目"
  - 用户需要执行多步骤、长时间、跨会话的任务
  - 用户需要AI持续追踪工作进度和上下文
  - 用户需要AI记住之前尝试过但失败的方法
  
  核心功能：
  - 创建新项目（自动生成 PROJECT.md, CHANGELOG.md）
  - 继续项目（自动读取进度，从断点继续）
  - 更新进度（自动更新 CHANGELOG.md）
  - Ralph Loop 自动推进（解决智能体惰性）
  - 多项目管理
  - 项目状态概览
  - 失败方法记录（防止重复尝试）
metadata:
  openclaw:
    emoji: "🔄"
    requires:
      bins:
        - git
---

# Long-Running Agent - 长时间运行智能体编排框架

基于 Anthropic 论文《Long-Running Claude for Scientific Research》实现，让 AI 智能体能够跨会话持续工作并完成复杂任务。

## 核心理念

**问题**：AI智能体每次会话都是"新生的"，没有记忆延续。

**解决方案**：通过文件系统作为"外部大脑"，实现跨会话的持续工作能力。

---

## 快速开始

### 创建新项目

当用户说 "创建一个[项目名]项目" 时：

```
Step 1: 确认项目名称和目标
Step 2: 在 workspace/tasks/{项目名}/ 创建目录
Step 3: 生成 PROJECT.md（项目简报）
Step 4: 生成 CHANGELOG.md（进度追踪）
Step 5: 开始第一项任务
```

**示例对话**：

```
用户: 创建一个博客系统项目，用 Node.js 实现

QClaw: ✅ 项目已创建: 博客系统

📁 位置: tasks/博客系统/
📄 PROJECT.md - 项目简报
📄 CHANGELOG.md - 进度追踪

🎯 目标: 用 Node.js 实现博客系统

下一步: 定义详细需求

请告诉我：
1. 博客系统需要哪些功能？
2. 使用什么数据库？
```

### 继续项目

当用户说 "继续[项目名]项目" 时：

```
Step 1: 读取 tasks/{项目名}/PROJECT.md（了解上下文）
Step 2: 读取 tasks/{项目名}/CHANGELOG.md（了解进度）
Step 3: 执行定向协议（PROJECT.md 中定义）
Step 4: 从"下一步"继续工作
```

**示例对话**：

```
用户: 继续博客系统项目

QClaw: 📋 继续项目: 博客系统

📊 当前状态: Phase 2 进行中
📈 进度: 5/12 任务，42%

🔄 Ralph Loop: 迭代 4/20

📍 下一步: 实现文章 API

[开始工作...]
```

### 查看项目状态

```
用户: 我有哪些项目？

QClaw: 📋 项目列表 (共 3 个)

名称                    | 状态           | 进度    
------------------------|----------------|---------
博客系统                | Phase 2        | 42%     
用户管理API             | 已完成         | 100%    
数据分析工具            | Phase 1        | 15%     
```

---

## 文件结构

每个项目都有标准结构：

```
workspace/
├── tasks/
│   └── {项目名}/
│       ├── PROJECT.md      # 项目简报（目标、成功标准、定向协议）
│       ├── CHANGELOG.md    # 进度追踪（跨会话记忆）
│       ├── tests/          # 测试预言机
│       └── src/            # 项目源代码
└── memory/
    └── YYYY-MM-DD.md       # 每日记录
```

---

## 核心组件

### 1. PROJECT.md - 项目简报

每个项目的"说明书"：

```markdown
# PROJECT.md - {项目名称}

## 项目概述
一句话描述项目做什么

## 交付物
- [ ] 交付物1
- [ ] 交付物2

## 成功标准
可量化的完成定义：
- 所有测试通过
- 测试覆盖率 > 80%
- 功能完整可用

## 定向协议
每个会话开始时执行：
1. 读取 CHANGELOG.md 的"当前状态"和"下一步"
2. 运行快速测试确认无回归
3. 从优先列表选择任务
4. 开始工作

## 不要做的事
- ❌ 跳过定向协议
- ❌ 重新尝试已记录为"失败"的方法
- ❌ 在测试失败时提交代码
```

### 2. CHANGELOG.md - 进度追踪

**最重要的文件！** 智能体的"长期记忆"：

```markdown
# CHANGELOG.md

## 当前状态: Phase 2 进行中
**进度**: 5/12 任务完成，42%
**下一步行动**: 
1. 实现文章 API
2. 编写测试

**Ralph Loop 状态**:
迭代: 4/20
成功标准: 所有测试通过，覆盖率>80%

## 失败的方法
> ⚠️ 最重要！防止重复尝试

### 方法：使用 Python 实现 - 2026-03-19
**尝试**: 使用 Python 创建项目
**结果**: 系统未安装 Python
**教训**: 当前环境优先使用 JavaScript/TypeScript

## 完成的任务
### 2026-03-19: 用户模型实现
- 实现 User 数据类
- 10 个测试用例通过
- 提交: abc123

## 会话日志
### Session 4 - 2026-03-19
**完成**: 用户 API 实现
**下次继续**: 文章 API
```

### 3. 测试预言机

让智能体能自主判断是否在进步：

| 类型 | 说明 | 示例 |
|------|------|------|
| 参考实现 | 已知的正确输出 | 预期输出文件 |
| 量化目标 | 明确的数值指标 | 覆盖率 > 80% |
| 测试套件 | 可执行的测试 | npm test |

### 4. Ralph Loop

解决"智能体惰性"问题——智能体有时会在完成部分任务后找借口停下来。

**实现**：循环检查，确保真正完成

```
for i in 1..MAX_ITERATIONS:
    result = agent.work(task)
    if result.includes("DONE") and verify_completion():
        break
    else:
        agent.continue("你确定完成了吗？请验证：{success_criteria}")
```

**在 CHANGELOG.md 中声明**：

```markdown
**Ralph Loop 状态**:
迭代: 1/20
成功标准: 所有测试通过，覆盖率>80%
```

每次会话检查是否达到标准，未达到则继续推进。

### 5. Git 协调

每个"有意义的工作单元"后提交代码：

```
一个功能实现 → 一次提交
一个 bug 修复 → 一次提交
一个重构 → 一次提交
```

---

## 命令参考

| 用户指令 | 触发条件 | QClaw 行为 |
|----------|----------|------------|
| 创建项目 | "创建/开始/新建/启动" + 项目名 | 生成 PROJECT.md, CHANGELOG.md，开始第一项任务 |
| 继续项目 | "继续/接着做/继续开发" + 项目名 | 读取进度，从断点继续 |
| 更新进度 | "更新进度/记录进度/保存进度" | 更新 CHANGELOG.md |
| 项目状态 | "项目状态/查看进度/做到哪了" | 显示当前进度和下一步 |
| 列出项目 | "列出项目/所有项目/我有哪些项目" | 显示所有项目及其状态 |
| 暂停项目 | "暂停项目/存档项目" | 标记项目为暂停状态 |

---

## 工作规则

### 必须做

- ✅ 每个子任务完成后更新 CHANGELOG.md
- ✅ 先写测试再写代码（TDD）
- ✅ 记录所有失败的方法（最重要！）
- ✅ 使用定向协议确保从正确位置开始
- ✅ 简洁输出（成功5-10行，失败20行）

### 禁止做

- ❌ 跳过定向协议
- ❌ 重新尝试已记录为"失败"的方法
- ❌ 在测试失败时提交代码
- ❌ 打印完整数组或日志
- ❌ 冗长的描述

---

## 输出规范

### 创建项目时

```
✅ 项目已创建: {项目名}

📁 位置: tasks/{项目名}/
📄 PROJECT.md - 项目简报
📄 CHANGELOG.md - 进度追踪

🎯 目标: {项目目标}
📊 成功标准: {成功标准}

下一步: {第一个任务}
```

### 继续项目时

```
📋 继续项目: {项目名}

📊 当前状态: {状态}
📈 进度: {X/Y 任务，Z%}

🔄 Ralph Loop: 迭代 {N}/20

📍 下一步: {下一个任务}

[开始工作...]
```

### 更新进度时

```
📝 进度已更新

状态: {新状态}
进度: {X/Y → X+1/Y}
完成: {刚完成的任务}
下一步: {新任务}
```

---

## 与 HEARTBEAT 集成

可以将项目检查加入 HEARTBEAT.md，实现后台持续推进：

```markdown
## 当前 Ralph Loop 任务

```
项目: 博客系统
迭代: 4/20
成功标准: 所有测试通过
```

检查：是否需要继续推进？
```

---

## 模板文件

详见 `references/` 目录：

- [project-template.md](references/project-template.md) - PROJECT.md 完整模板
- [changelog-template.md](references/changelog-template.md) - CHANGELOG.md 完整模板
- [ralph-loop.md](references/ralph-loop.md) - Ralph Loop 详细说明
- [best-practices.md](references/best-practices.md) - 最佳实践指南

---

## 脚本工具

### init-project.js

初始化新项目：

```bash
node scripts/init-project.js <项目名> --desc "项目描述"
```

### list-projects.js

列出所有项目：

```bash
node scripts/list-projects.js
```

---

## 错误处理

| 错误 | 处理方式 |
|------|----------|
| 项目不存在 | 提示用户创建或列出可用项目 |
| CHANGELOG.md 损坏 | 尝试恢复，无法恢复则提示重新创建 |
| 测试失败 | 记录失败原因到 CHANGELOG，继续调试 |
| Git 冲突 | 提示用户手动解决 |

---

## 示例项目

查看 `examples/task-planner-demo/` 目录，这是一个完整的示例项目，展示了：

- ✅ 完整的 PROJECT.md 和 CHANGELOG.md
- ✅ 失败方法记录（Python → TypeScript 迁移）
- ✅ Ralph Loop 迭代过程（3次迭代完成任务）
- ✅ 测试驱动开发流程

---

## 参考资料

- [Anthropic 论文](https://www.anthropic.com/research/long-running-tasks)
- [参考实现 smsharma/clax](https://github.com/smsharma/clax)

FILE:scripts/init-project.js
#!/usr/bin/env node
/**
 * init-project.js - 初始化新项目
 * 
 * 用法：
 *   node init-project.js <项目名> [选项]
 * 
 * 选项：
 *   --desc "描述"    项目描述
 *   --path "路径"    项目路径（默认 workspace/tasks/）
 */

const fs = require('fs');
const path = require('path');

// 项目模板
const PROJECT_TEMPLATE = `# PROJECT.md - {PROJECT_NAME}

> 创建时间: {DATE}
> 最后更新: {DATE}

## 项目概述

**一句话描述**: {DESCRIPTION}

**预期时间**: 待评估

---

## 交付物

- [ ] 待定义

---

## 成功标准

项目完成的定义：

1. **功能完整**: 待定义
2. **质量标准**: 测试通过

**可量化指标**:
- 测试: 全部通过

---

## 定向协议

**每个会话开始时，执行以下步骤**：

\`\`\`
1. 读取 CHANGELOG.md 的"当前状态"和"下一步"
2. 确认没有回归
3. 从优先列表中选择任务
4. 开始工作
\`\`\`

**不要做的事**：
- ❌ 不要跳过定向协议
- ❌ 不要重新尝试已记录为"失败"的方法

---

## 任务分解

### Phase 1: 初始化

- [ ] 定义详细需求
- [ ] 创建测试用例

---

## 版本历史

- {DATE}: 项目创建
`;

const CHANGELOG_TEMPLATE = `# CHANGELOG.md - {PROJECT_NAME} 开发进度

> 创建时间: {DATE}
> 最后更新: {DATE}

---

## 当前状态: 项目初始化

**进度**: 0/N 任务完成，0%

**当前里程碑**: Phase 1

**阻塞问题**: 无

**下一步行动**: 
1. 定义详细需求
2. 创建第一个测试

**Ralph Loop 状态**:
\`\`\`
迭代: 1/20
成功标准: 待定义
\`\`\`

---

## 测试状态

| 模块 | 通过 | 失败 | 跳过 | 最后运行 |
|------|------|------|------|----------|
| - | - | - | - | 未运行 |

**快速测试**: ⏳ 待运行

---

## 完成的任务

(尚无完成任务)

---

## 进行中的任务

### 项目初始化

**当前进度**: 项目文件创建中

**已完成**:
- [x] 创建 PROJECT.md
- [x] 创建 CHANGELOG.md

**待完成**:
- [ ] 定义需求
- [ ] 创建测试

**阻塞**: 无

---

## 失败的方法

> ⚠️ 尚无失败方法记录

---

## 会话日志

### Session 1 - {DATE}

**时长**: 初始化

**完成**:
- 创建项目框架

**下次继续**:
- 定义详细需求

---

## 版本历史

- {DATE}: 项目初始化
`;

function initProject(projectName, options = {}) {
  const date = new Date().toISOString().split('T')[0];
  const projectPath = options.path || path.join(process.cwd(), 'tasks', projectName);
  
  // 创建目录
  if (!fs.existsSync(projectPath)) {
    fs.mkdirSync(projectPath, { recursive: true });
  }
  
  // 生成 PROJECT.md
  const projectMd = PROJECT_TEMPLATE
    .replace(/{PROJECT_NAME}/g, projectName)
    .replace(/{DATE}/g, date)
    .replace(/{DESCRIPTION}/g, options.desc || '待定义');
  
  fs.writeFileSync(path.join(projectPath, 'PROJECT.md'), projectMd);
  
  // 生成 CHANGELOG.md
  const changelogMd = CHANGELOG_TEMPLATE
    .replace(/{PROJECT_NAME}/g, projectName)
    .replace(/{DATE}/g, date);
  
  fs.writeFileSync(path.join(projectPath, 'CHANGELOG.md'), changelogMd);
  
  // 创建 tests 目录
  const testsDir = path.join(projectPath, 'tests');
  if (!fs.existsSync(testsDir)) {
    fs.mkdirSync(testsDir);
  }
  
  return {
    path: projectPath,
    files: ['PROJECT.md', 'CHANGELOG.md', 'tests/']
  };
}

// CLI 入口
if (require.main === module) {
  const args = process.argv.slice(2);
  let projectName = null;
  const options = {};
  
  for (let i = 0; i < args.length; i++) {
    if (args[i] === '--desc') {
      options.desc = args[++i];
    } else if (args[i] === '--path') {
      options.path = args[++i];
    } else if (!args[i].startsWith('--')) {
      projectName = args[i];
    }
  }
  
  if (!projectName) {
    console.error('用法: node init-project.js <项目名> [--desc "描述"] [--path "路径"]');
    process.exit(1);
  }
  
  try {
    const result = initProject(projectName, options);
    console.log(`✅ 项目已创建: projectName`);
    console.log(`📁 位置: result.path`);
    console.log(`📄 文件: result.files.join(', ')`);
  } catch (error) {
    console.error(`❌ 创建失败: error.message`);
    process.exit(1);
  }
}

module.exports = { initProject };

FILE:scripts/list-projects.js
#!/usr/bin/env node
/**
 * list-projects.js - 列出所有项目
 * 
 * 用法：
 *   node list-projects.js [工作区路径]
 */

const fs = require('fs');
const path = require('path');

function listProjects(workspacePath) {
  const tasksDir = path.join(workspacePath, 'tasks');
  
  if (!fs.existsSync(tasksDir)) {
    return [];
  }
  
  const projects = [];
  const dirs = fs.readdirSync(tasksDir, { withFileTypes: true });
  
  for (const dir of dirs) {
    if (!dir.isDirectory()) continue;
    
    const projectPath = path.join(tasksDir, dir.name);
    const projectMd = path.join(projectPath, 'PROJECT.md');
    const changelogMd = path.join(projectPath, 'CHANGELOG.md');
    
    const project = {
      name: dir.name,
      path: projectPath,
      hasProject: fs.existsSync(projectMd),
      hasChangelog: fs.existsSync(changelogMd)
    };
    
    // 读取进度
    if (project.hasChangelog) {
      const content = fs.readFileSync(changelogMd, 'utf-8');
      const progressMatch = content.match(/\*\*进度\*\*:\s*(\d+)\/(\d+)\s*任务完成/);
      if (progressMatch) {
        project.completed = parseInt(progressMatch[1]);
        project.total = parseInt(progressMatch[2]);
        project.percent = Math.round((project.completed / project.total) * 100);
      }
      
      const statusMatch = content.match(/## 当前状态:\s*(.+)/);
      if (statusMatch) {
        project.status = statusMatch[1].trim();
      }
    }
    
    projects.push(project);
  }
  
  return projects;
}

// CLI 入口
if (require.main === module) {
  const workspacePath = process.argv[2] || process.cwd();
  
  const projects = listProjects(workspacePath);
  
  if (projects.length === 0) {
    console.log('📭 没有找到项目');
    process.exit(0);
  }
  
  console.log(`📋 项目列表 (共 projects.length 个)\n`);
  console.log('名称                    | 状态           | 进度    | 文件');
  console.log('-'.repeat(60));
  
  for (const p of projects) {
    const name = p.name.padEnd(23);
    const status = (p.status || '-').substring(0, 14).padEnd(15);
    const progress = p.percent ? `p.percent%`.padEnd(7) : '-'.padEnd(7);
    const files = `'❌' '❌'`;
    
    console.log(`name | status | progress | files`);
  }
}

module.exports = { listProjects };

FILE:references/best-practices.md
# 最佳实践

## 1. 测试即一切

### 原则
- 每个新功能实现前先写测试
- 发现 bug 时先添加复现测试
- 测试是最重要的部分

### 测试优先级
```
1. 核心功能测试（必须）
2. 边界条件测试（重要）
3. 集成测试（推荐）
4. 性能测试（可选）
```

### 测试命名
```
test_{功能}_{场景}_{预期结果}

例如：
test_task_creation_minimal
test_task_creation_with_invalid_data
```

## 2. 记录失败方法

**这是最重要的实践！**

### 为什么重要
- 智能体每次会话都是"新生的"
- 不记录就会重复尝试同样的失败方法
- 浪费时间和资源

### 如何记录

在 CHANGELOG.md 中：

```markdown
## 失败的方法

### 方法：使用 Python 实现 - 2026-03-19

**尝试**: 使用 Python 创建任务计划表，使用 pytest 测试套件

**结果**: 系统未安装 Python，命令不可用

**根本原因**: 
- 当前环境未配置 Python
- Node.js 是主要运行时

**教训**: 
- 先检查环境再选择技术栈
- OpenClaw 项目优先使用 JavaScript/TypeScript

**相关文件**: tests/test_planner.py（已弃用）
```

### 记录什么
- 尝试了什么方法
- 为什么失败
- 根本原因是什么
- 学到了什么教训
- 相关文件路径

## 3. 简洁输出

### 原则
上下文窗口是有限资源，输出要精炼。

### 标准
| 情况 | 行数 | 内容 |
|------|------|------|
| 成功 | 5-10 行 | 结果摘要 |
| 失败 | ~20 行 | 错误信息 + 原因 |
| 进度 | ~10 行 | 当前状态 |

### 输出格式

**成功**：
```
✅ 任务完成

测试: 22 passed
覆盖率: 85%
文件: src/Task.ts, src/store.ts
```

**失败**：
```
❌ 测试失败

错误: test_task_creation
  Expected: "pending"
  Got: "in_progress"

位置: tests/planner.test.ts:45
原因: 状态初始化错误
```

### 避免
- ❌ 打印完整数组
- ❌ 打印完整日志
- ❌ 冗长的描述

## 4. 每步更新 CHANGELOG

### 何时更新
- 完成一个子任务
- 发现一个问题
- 尝试一个方法（成功或失败）
- 达到一个里程碑

### 更新什么
- 当前状态
- 进度百分比
- 完成的任务
- 下一步行动

### 示例
```markdown
## 当前状态: Phase 1 完成

**进度**: 5/14 任务完成，36%

**下一步行动**: 
1. 实现 CLI 界面
2. 编写验证报告
```

## 5. 定向协议

### 什么是定向协议
每个会话开始时执行的固定步骤。

### 为什么需要
- 确保从正确位置开始
- 快速恢复上下文
- 避免重复工作

### 示例协议
```markdown
## 定向协议

每个会话开始时：

1. 读取 CHANGELOG.md 的"当前状态"和"下一步"
2. 运行快速测试确认无回归
3. 从优先列表选择任务
4. 开始工作
```

### 协议设计原则
- 简单明了
- 可快速执行
- 能恢复上下文

## 6. Git 提交粒度

### 原则
每个"有意义的工作单元"提交一次。

### 什么是"有意义的工作单元"
- 一个功能实现
- 一个 bug 修复
- 一个重构
- 一组相关改动

### 提交信息格式
```
<type>: <subject>

<body>

<footer>
```

类型：
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 重构
- `docs`: 文档
- `test`: 测试

### 示例
```
feat: 实现 Task 数据类

- 支持创建/序列化/状态转换
- 过期检测功能
- 10 个测试用例

Closes #1
```

## 7. 任务分解

### 原则
大任务分解为小任务，每个小任务可独立完成和测试。

### 分解粒度
- 每个任务: 15-30 分钟
- 每个任务: 1-5 个测试
- 每个任务: 独立可验证

### 分解示例

**大任务**: 实现任务管理器

**分解后**:
```
Phase 1: 核心数据模型
├── Task 数据类 (15min)
├── TaskStore 存储类 (20min)
└── 持久化 (10min)

Phase 2: CRUD 操作
├── 创建任务 (15min)
├── 查看任务 (10min)
├── 更新任务 (15min)
└── 删除任务 (10min)

Phase 3: 高级功能
├── 优先级排序 (15min)
└── 依赖关系 (20min)
```

## 8. 快速反馈

### 使用 --fast 模式
测试套件应支持快速模式：
- 只运行关键测试
- 跳过慢速测试
- 确保基本功能正常

### 开发循环
```
1. 写测试
2. 运行快速测试
3. 实现代码
4. 运行快速测试
5. 提交前运行完整测试
```

## 9. 上下文管理

### 减少不必要的读取
- 只读取需要的文件
- 使用 grep 而不是 cat
- 指定行数范围

### 避免重复
- 已知的信息不重复读取
- 使用 CHANGELOG 记录关键信息

## 10. 主动沟通

### 何时询问用户
- 不确定需求
- 遇到阻塞
- 需要决策
- 敏感操作

### 如何沟通
- 简洁描述问题
- 提供选项
- 说明推荐选择

### 示例
```
需要选择数据库：

1. SQLite（推荐）- 轻量，无需安装
2. PostgreSQL - 功能强大，需要安装

选择哪个？
```

FILE:references/changelog-template.md
# CHANGELOG.md 模板

```markdown
# CHANGELOG.md - {项目名称} 开发进度

> 创建时间: {日期}
> 最后更新: {日期}

---

## 当前状态: {状态摘要}

**进度**: {X/Y 任务完成，Z%}

**当前里程碑**: {里程碑名称}

**阻塞问题**: {无 或 描述阻塞}

**下一步行动**: 
1. {下一个具体任务}
2. {再下一个任务}

**Ralph Loop 状态**:
```
迭代: {N}/20
成功标准: {具体标准}
```

---

## 测试状态

| 模块 | 通过 | 失败 | 跳过 | 最后运行 |
|------|------|------|------|----------|
| {模块1} | {N} | {N} | {N} | {日期} |

**快速测试**: ✅ 通过 / ❌ 失败

---

## 完成的任务

### {日期}: {任务名称}

**改动**:
- {改动1}
- {改动2}

**验证**:
- 测试: {测试结果}
- 精度: {如适用}

**提交**: `{commit_hash}`

---

## 进行中的任务

### {任务名称}

**当前进度**: {描述}

**已完成**:
- [x] {子任务}

**待完成**:
- [ ] {子任务}

**阻塞**: {无 或 描述}

---

## 失败的方法

> ⚠️ 重要：记录失败的方法，防止后续会话重复尝试

### {方法名称} - {日期}

**尝试**: {简述尝试了什么}

**结果**: {为什么失败}

**根本原因**: {深入分析}

**教训**: {应该怎么做}

**相关代码/文件**: {路径}

---

## 关键检查点

### 精度表

| 指标 | 目标 | 当前 | 状态 |
|------|------|------|------|
| {指标1} | {目标值} | {当前值} | ✅/❌ |

### 里程碑

| 里程碑 | 目标日期 | 完成日期 | 状态 |
|--------|----------|----------|------|
| {里程碑1} | {日期} | {日期} | ✅ |

---

## 已知限制

1. **{限制标题}**
   - 描述: {详细描述}
   - 影响: {影响范围}
   - 可能的解决方案: {思路}
   - 优先级: 高/中/低

---

## Bug 追踪

### 已修复

| ID | 描述 | 根本原因 | 修复日期 |
|----|------|----------|----------|
| #1 | {描述} | {原因} | {日期} |

### 待修复

| ID | 描述 | 优先级 | 状态 |
|----|------|--------|------|
| #2 | {描述} | 高 | 待开始 |

---

## 会话日志

### Session {N} - {日期}

**时长**: {X小时}

**完成**:
- {完成的任务}

**发现**:
- {发现的问题或洞察}

**下次继续**:
- {下一步}

---

## 版本历史

- {日期}: 项目初始化
- {日期}: {重大更新}
```

FILE:references/project-template.md
# PROJECT.md 模板

```markdown
# PROJECT.md - {项目名称}

> 创建时间: {日期}
> 最后更新: {日期}

## 项目概述

**一句话描述**: {项目做什么}

**目标用户**: {谁会使用}

**预期时间**: {预估工作量}

---

## 交付物

- [ ] {交付物1}
- [ ] {交付物2}
- [ ] {交付物3}

---

## 成功标准

项目完成的定义：

1. **功能完整**: {具体标准}
2. **质量标准**: {测试覆盖率、精度要求等}
3. **文档要求**: {需要什么文档}

**可量化指标**:
- 指标1: {目标值}
- 指标2: {目标值}

---

## 定向协议

**每个会话开始时，执行以下步骤**：

```
1. 读取 CHANGELOG.md 的"当前状态"和"下一步"
2. 确认没有回归（运行快速测试）
3. 从优先列表中选择最高影响的任务
4. 开始工作
```

**不要做的事**：
- ❌ 不要跳过定向协议
- ❌ 不要重新尝试已记录为"失败"的方法
- ❌ 不要在测试失败时提交代码

---

## 背景和上下文

### 为什么需要这个项目？

{背景说明}

### 技术决策

| 决策 | 选择 | 原因 |
|------|------|------|
| {决策点} | {选择} | {原因} |

---

## 文件结构

```
{project-name}/
├── PROJECT.md          # 本文件
├── CHANGELOG.md        # 进度追踪
├── tests/              # 测试预言机
└── src/                # 源代码
```

---

## 任务分解

### Phase 1: {阶段名称}

- [ ] {任务1}
  - 预估: {时间}
  - 状态: 待开始 / 进行中 / 完成
- [ ] {任务2}

### Phase 2: {阶段名称}

- [ ] {任务}

---

## 风险和限制

### 已知风险

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| {风险} | {影响} | {措施} |

### 当前限制

- {限制1}
- {限制2}

---

## 笔记

### 重要发现

- {日期}: {发现}

### 需要记住的约定

- {约定}

---

## 版本历史

- {日期}: 项目创建
```

FILE:references/ralph-loop.md
# Ralph Loop 详解

## 问题：智能体惰性

AI 智能体有时会在完成部分任务后找借口停下来：
- "时间差不多了，我们下次继续"
- "这已经足够好了"
- "剩下的可以以后再做"

这种现象称为"智能体惰性"(Agentic Laziness)。

## 解决方案：Ralph Loop

Ralph Loop 本质上是一个 for 循环，在智能体声明完成后再次检查，确保真正完成。

### 核心逻辑

```
for iteration in range(MAX_ITERATIONS):
    result = agent.work(task)
    
    if "DONE" in result and verify_completion():
        print("✅ 任务真正完成")
        break
    else:
        agent.continue("你确定完成了吗？请验证：{success_criteria}")
```

### 实现方式

#### 1. 在 CHANGELOG.md 中声明状态

```markdown
**Ralph Loop 状态**:
```
迭代: 1/20
成功标准: 所有测试通过，覆盖率>80%
```
```

#### 2. 每次会话开始检查

```
1. 读取 CHANGELOG.md 的 Ralph Loop 状态
2. 检查是否已达到成功标准
3. 如果未达到，继续工作
4. 如果达到，标记完成
```

#### 3. 每次迭代更新

```markdown
**Ralph Loop 状态**:
```
迭代: 3/20
成功标准: ✅ 所有测试通过，覆盖率>80%
结果: 完成
```
```

### 成功标准设计

好的成功标准应该是：
- **可量化** - 可以用数字衡量
- **可验证** - 有明确的验证方式
- **有意义** - 与项目目标相关

**示例**：

| 任务 | 成功标准 |
|------|----------|
| 实现功能 | 所有测试通过 |
| 性能优化 | 响应时间 < 100ms |
| 代码重构 | 测试覆盖率 > 80% |
| 文档编写 | 所有 API 有文档 |
| Bug 修复 | Bug 不再复现 |

### 最大迭代次数

默认 20 次，根据任务复杂度调整：
- 简单任务：5-10 次
- 中等任务：10-20 次
- 复杂任务：20-50 次

### 与 HEARTBEAT 集成

可以将 Ralph Loop 检查加入心跳：

```markdown
## HEARTBEAT.md

### 当前 Ralph Loop 任务

```
项目: {项目名}
迭代: {当前}/{最大}
成功标准: {标准}
```

检查：是否需要继续推进？
```

这样即使会话中断，下一次心跳时也会自动继续。

## 实战案例

### 案例：任务计划表项目

```markdown
迭代 1: 项目初始化
- 创建 PROJECT.md, CHANGELOG.md
- 未完成：核心功能未实现

迭代 2: 技术栈调整
- 发现 Python 不可用
- 迁移到 TypeScript
- 未完成：代码未写

迭代 3: 核心实现
- 实现 Task, TaskStore 类
- 22 个测试全部通过
- CLI 工作正常
- ✅ 成功标准达成

结果: 3 次迭代完成项目
```

## 注意事项

1. **不要无限循环** - 设置合理的最大迭代次数
2. **记录进度** - 每次迭代都要更新 CHANGELOG
3. **验证真正完成** - 不是智能体说完成就完成，要用测试验证
4. **失败方法记录** - 如果某次迭代失败，记录原因防止重复