react-task-solver

v0.3.2

Published

2 months ago

Automated Cursor agent task orchestration until goals are achieved

0High
0Medium
0Low

puresaber

TaskSolver

基于 YAML 定义目标的 Cursor Agent 多轮任务编排工具。支持 IDE 模式（Stop Hook 自动续跑）与 SDK 模式（CLI 长时运行）。

功能概览

用 YAML 声明任务图（依赖、完成条件、验收命令）
Stop Hook 在每轮 Agent 结束后自动验证 done_when 并下发下一任务
CLI 通过 @cursor/sdk 在无 IDE 环境下连续执行
内置示例 Goal：goals/example-todo.yaml、goals/example-parallel.yaml
可观测性：npm run task:status 查看轮次、任务进度、活动 shell
自动恢复：npm run task:resume / npm run task:watch 应对异常停止
并行任务：Goal 中 parallel_group + 任务内 subagents 指引
ReAct 内层循环：任务级 rea_ct:（Reasoning + Acting）— 见 docs/rea-ct-loop.md
React 强化：Goal 模板、component_test_passes / exports_symbol 验收、状态面板、 task:init-react / task:init-project 脚手架 — 见 docs/react-enhancements.md 与 docs/react-workflow.md（全流程）

ReAct vs React.js

| | ReAct (rea_ct) | React.js (react-*) | |--|------------------|----------------------| | 含义 | 任务内 Reasoning + Acting 微循环 | React 组件与 UI 开发 | | 示例 Goal | goals/example-rea-ct.yaml | goals/react-enhancements.yaml | | CLI | npm run task:react-trace | npm run task:init-react |

npm run task:sync-hooks -- goals/example-rea-ct.yaml
# Run the TaskSolver workflow for goals/example-rea-ct.yaml
npm run task:react-trace -- R1

React 强化工作流

完整流程：docs/react-workflow.md（init-project → sync-hooks → 启动 → 验收 → 恢复）

npm run build
npm run task:init-project -- ../my-app MyApp --title "我的应用"
# 在目标项目目录 sync hooks，然后对 Agent 说：
# Run the TaskSolver workflow for goals/my-app.yaml
npm run task:status --watch

从模板快速新建 React 组件 Goal：

npm run task:init-react -- component MyWidget

环境要求

Node.js ≥ 20
npm ≥ 10
Cursor API Key（SDK 模式必需）：Cursor Dashboard → Integrations

初学者入门

第一次使用建议先看 docs/beginner-guide.md；要看「改→测→循环」请看 docs/mini-score-loop.md。
运行模式（模拟 / Cloud / IDE） 见 docs/running-modes.md。

cp goals/beginner-demo.active-goal.json state/active-goal.json
npm run task:sync-hooks -- goals/beginner-demo.yaml
# 在 Cursor Agent 里说：Run the TaskSolver workflow for goals/beginner-demo.yaml

快速开始

# 1. 克隆仓库
git clone <your-repo-url>
cd React_TaskSolver

# 2. 安装依赖
npm ci

# 3. 编译编排器与 Hook
npm run build

# 4. 设置当前 Goal（IDE 模式）
mkdir -p state
cp state/active-goal.example.json state/active-goal.json

# 5. 验证
npm run lint
npm run test

IDE 模式（推荐）

在 Cursor 中打开本项目（或包含 .cursor/hooks.json 的工作区）：

执行 npm run build 生成 dist/hooks/*.js
（推荐）同步 loop_limit：npm run task:sync-hooks -- goals/example-todo.yaml
配置 state/active-goal.json 指向目标 YAML
另开终端监视进度：npm run task:status --watch
对 Agent 说：
Run the TaskSolver workflow for goals/example-todo.yaml

Stop Hook 会在每轮结束后自动验证任务并注入 follow-up 消息，直到 Goal 完成或达到轮次上限。

Hook 配置见 .cursor/hooks.json。

SDK 模式（无 IDE）

# Windows PowerShell
$env:CURSOR_API_KEY = "cursor_..."
npm run task:run -- goals/example-todo.yaml

# Linux / macOS
export CURSOR_API_KEY=cursor_...
npm run task:run -- goals/example-todo.yaml

也可复制 .env.example 为 .env 并在 shell 中加载（.env 已被 gitignore）。

# 从 interrupted 状态继续
npm run task:run -- goals/example-todo.yaml --resume

可观测性与恢复

| 命令 | 说明 | |------|------| | npm run task:status | 查看 Goal 状态、轮次余量、当前任务 | | npm run task:status --watch | 每 3 秒刷新状态 | | npm run task:status --json | JSON 输出（供脚本集成） | | npm run task:resume | 生成续跑 prompt（IDE）或恢复 state | | npm run task:resume -- --force | 强制重置 blocked 重试计数 | | npm run task:watch | 看门狗：检测 stale 运行并写 resume prompt | | npm run task:sync-hooks -- <goal> | 将 hooks.json loop_limit 同步到 Goal 轮次 |

活动日志：state/{goalId}-activity.jsonl（shell 执行、verify、任务完成等事件）。

Goal 意外停止（如 Cursor loop_limit 用尽）后：

npm run task:resume
# 将输出的 prompt 粘贴到 Cursor，或读取 state/resume-prompt.txt

编写 Goal

Goal 文件放在 goals/ 目录，结构示例：

id: my-goal
title: 我的自动化目标

max_auto_rounds: 15
max_retries_per_task: 3

tasks:
  - id: T1
    title: 创建某个文件
    depends_on: []
    done_when:
      - file_exists: src/foo.ts

  - id: T2
    title: 通过测试
    depends_on: [T1]
    done_when:
      - command_passes: npm run test

acceptance:
  - command: npm run lint

human_gates: []

并行任务与 subagent

tasks:
  - id: T2a
    title: 探索代码库
    depends_on: [T1]
    parallel_group: batch1
    subagents:
      - type: explore
        prompt_hint: "扫描 src/orchestrator"
    done_when:
      - file_exists: src/orchestrator/Orchestrator.ts

  - id: T2b
    title: 运行测试
    depends_on: [T1]
    parallel_group: batch1
    done_when:
      - command_passes: npm run test

parallel_group：同组且依赖已满足的任务可并行执行
subagents：提示主 Agent 使用 Cursor Task/subagent 工具
auto_resume_on_session: true：新会话启动时注入续跑上下文

示例：goals/example-parallel.yaml

`done_when` 条件类型

| 类型 | 说明 | 示例 | |------|------|------| | file_exists | 文件存在 | file_exists: src/App.tsx | | command_passes | 命令退出码为 0 | command_passes: npm run test | | git_has_changes_in | 路径下有未提交变更 | git_has_changes_in: src/ |

更多说明见 AGENTS.md。React 强化见 docs/react-enhancements.md。

项目结构

├── .cursor/
│   ├── hooks.json          # Cursor Stop Hook 配置
│   └── rules/              # Agent 工作流规则
├── goals/                  # Goal YAML 定义
├── src/
│   ├── orchestrator/       # 任务图、进度、决策逻辑
│   ├── hooks/              # IDE Stop Hook 入口
│   ├── cli/                # SDK CLI 入口
│   └── verify/             # done_when 校验
├── state/                  # 运行时状态（gitignore，需本地创建）
├── dist/                   # 编译产物（npm run build）
└── AGENTS.md               # Agent 使用说明

常用命令

| 命令 | 说明 | |------|------| | npm run build | 编译 TypeScript 工具链（Hook / CLI） | | npm run build:app | 构建示例 React 应用 | | npm run lint | 类型检查 | | npm run test | 运行单元测试 | | npm run task:run -- <goal> | SDK 模式执行 Goal | | npm run task:run -- <goal> --resume | 从 interrupted/blocked 恢复 | | npm run task:status | 查看运行状态与轮次余量 | | npm run task:resume | 生成续跑 prompt | | npm run task:watch | 看门狗监视 stale 运行 | | npm run task:sync-hooks -- <goal> | 同步 hooks loop_limit（含 rea_ct 步数估算） | | npm run task:react-trace -- [taskId] | 打印 ReAct 步骤 trace | | npm run task:sync-vendor -- <path> | 同步 vendored TaskSolver 到目标项目 | | npm run task:goal -- status\|pause\|resume\|clear | Goal 生命周期（等同 /goal 命令） | | npm run task:init-react -- component <Name> | 从模板生成 React 组件 Goal | | npm run hook:stop | 手动测试 Stop Hook |

作为依赖安装

支持两种引用方式（版本号与 npm 包对齐，当前 0.2.1）：

方式 A — npm（推荐，适合 CI）：

npm install react-task-solver@^0.2.1

方式 B — Git 标签（适合私有项目或本地联调）：

"react-task-solver": "github:PureSaber/React_TaskSolver#v0.2.1"

本地开发可临时使用 "file:../React_TaskSolver"。Git 依赖安装时会通过 prepare 自动编译 dist/。

安装后在消费项目的 package.json 中：

{
  "scripts": {
    "task:run": "tasksolver-run",
    "task:status": "tasksolver-status",
    "task:sync-hooks": "tasksolver-sync-hooks"
  }
}

.cursor/hooks.json 引用 node_modules 路径（相对项目根目录）：

{
  "version": 1,
  "hooks": {
    "stop": [{
      "command": "node node_modules/react-task-solver/dist/hooks/orchestrate-stop.js",
      "timeout": 600,
      "loop_limit": 15
    }]
  }
}

完整 hook 集见 agent-toolkit tasksolver-hooks-full.json。

在其他工作区复用

推荐：使用上文 npm 或 Git 依赖，不要复制源码。

Legacy（不推荐）：npm run task:sync-vendor -- <target-project> 将源码同步到目标项目的 tasksolver/ 目录。新项目请改用 npm 依赖。

安装 react-task-solver 或使用 TASKSOLVER_ROOT 指向本地克隆
配置 .cursor/hooks.json（见上节）
在目标工作区创建 state/active-goal.json，或通过环境变量 TASKSOLVER_GOAL_PATH 指定 Goal 路径

状态与重置

| 文件 | 用途 | |------|------| | state/active-goal.json | 当前激活的 Goal 路径 | | state/{goalId}.json | 各 Goal 的进度、重试次数、轮次 |

删除 state/ 目录可重置运行进度。

开发规范

使用 strict TypeScript，避免 any
提交前运行 npm run lint
不提交密钥（.env、API Key）
详见 .cursor/rules/coding-standards.mdc

License

MIT