qcloop

程序驱动的 AI 批量测试编排工具

Go Version React License

功能特性 • 快速开始 • 使用指南 • 架构设计 • 文档

AI agent 使用者请读 llms-full.txt (导航索引见 llms.txt)。 qcloop 的设计意图之一就是让 AI agent 自动提单、自动轮询、自动重试;人类只下发意图、授权和必要确认,不要手动在 UI 里逐项操作。 AI 使用 qcloop 有两条主路径:支持 Skill 的 agent 走 skills/qcloop + qcloop-skill;其他 agent 读取 http://localhost:3000/llm-full.txt 后直接调用 HTTP API。

最快用法:先打开 qcloop,再把这句话发给 Codex / Claude Code / Gemini CLI / Kiro CLI:

请读取 http://localhost:3000/llm-full.txt,然后使用 qcloop 帮我测试当前任务。

llm-full.txt 会指导 AI 自动理解上下文、拆分自动化测试任务、创建批次并启动运行。完整说明见 AI Agent 一句话使用指南。如果你已经在 qcloop 启动环境中设置了 QCLOOP_EXECUTOR_PROVIDER=claude_code|gemini_cli|kiro_cli,AI 创建批次时会默认使用对应执行器;也可以在批次里显式传 executor_provider。

如果你的 Agent 支持技能,也可以直接启用仓库内置的 qcloop 技能。该技能内置参考 Lime CLI 风格的 qcloop-skill 命令,供 AI 稳定执行 doctor -> job create/run -> job wait/status/report -> item answer/retry/cancel -> queue metrics -> template CRUD 流程,避免手写 curl;同一 CLI 已整理为 npm 包 @limecloud/qcloop-skill-cli,方便全局安装或 npx 使用。

📖 项目简介

为什么需要 qcloop?

不只是"agent 检查"

架构对比

一句话异步使用架构

产品界面预览

与 Codex /goal 的区别

🎯 功能特性

核心功能

工作流程

1. 创建批次
 ├─ 定义 Worker Prompt 模板
 ├─ 定义 Verifier Prompt 模板(可选)
 ├─ 提供测试项列表
 └─ 设置最大质检轮次
2. 执行批次
 ├─ Worker: 执行测试任务
 ├─ Verifier: 审查结果(输出 JSON verdict)
 ├─ Repair: 根据 feedback 自动返修
 └─ 循环直到通过或达到最大轮次
3. 查看结果
 ├─ 批次列表:所有批次概览
 ├─ 批次详情:统计卡片 + 测试项表格
 └─ 执行历史:每一轮的详细记录

🚀 快速开始

前置要求

安装

方式 1:从源码构建

# 克隆仓库
git clone https://github.com/limecloud/qcloop.git
cd qcloop
# 构建后端
go build -o qcloop ./cmd/qcloop
# 安装到系统路径(可选)
sudo mv qcloop /usr/local/bin/

方式 2:使用 Go Install

go install github.com/limecloud/qcloop/cmd/qcloop@latest

验证安装

qcloop --help

📚 使用指南

推荐:AI Agent 一句话使用

请读取 http://localhost:3000/llm-full.txt,然后使用 qcloop 帮我测试当前任务。

技能使用

npm install -g @limecloud/qcloop-skill-cli
qcloop-skill doctor
# 或直接使用仓库内置 CLI
skills/qcloop/bin/qcloop-skill doctor
skills/qcloop/bin/qcloop-skill guide --full --raw
skills/qcloop/bin/qcloop-skill job create --file /tmp/qcloop-job.json --run
skills/qcloop/bin/qcloop-skill job create --file /tmp/qcloop-job.json --cwd "$PWD" --glob "docs/**/*.md" --run
skills/qcloop/bin/qcloop-skill job wait <job_id> --timeout 1800
skills/qcloop/bin/qcloop-skill job status <job_id> --include-items
skills/qcloop/bin/qcloop-skill job report <job_id> --format markdown
skills/qcloop/bin/qcloop-skill item answer <item_id> --answer "确认允许继续" --resume
skills/qcloop/bin/qcloop-skill item retry <item_id>
skills/qcloop/bin/qcloop-skill item cancel <item_id> --reason "该项暂不处理"
skills/qcloop/bin/qcloop-skill queue metrics
skills/qcloop/bin/qcloop-skill template list

CLI 使用(开发者 / 手动模式)

1. 创建批次

qcloop create \
 --name "test-lime-workspace" \
 --prompt "测试 Lime workspace 功能: {{item}}" \
 --verifier-prompt "检查结果,输出 JSON: {\"pass\": bool, \"feedback\": \"OK\"}" \
 --items "create,read,update,delete" \
 --max-qc-rounds 3 \
 --executor-provider codex

✅ 批次创建成功
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
批次 ID: abc-123-def
批次名称: test-lime-workspace
测试项数: 4
最大质检轮次: 3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2. 运行批次

qcloop run --job-id abc-123-def

🚀 开始执行批次: test-lime-workspace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1/4] 执行测试项: create
 ✅ Worker 执行成功
 ✅ Verifier 通过
[2/4] 执行测试项: read
 ✅ Worker 执行成功
 ❌ Verifier 失败: 输出格式不正确
 🔧 Repair 执行中...
 ✅ Verifier 通过
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 批次执行完成

3. 查询状态

qcloop status --job-id abc-123-def

批次状态: test-lime-workspace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
批次 ID: abc-123-def
状态: completed
创建时间: 2026年05月09日 23:00:00
完成时间: 2026年05月09日 23:05:30
总耗时: 5m30s
测试项统计:
 总数: 4
 ✅ 成功: 3 (75.0%)
 ❌ 失败: 1 (25.0%)
 ⏳ 待处理: 0 (0.0%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Web 界面使用(观察 / 开发模式)

1. 打开服务

qcloop serve --addr :8080 --workers 2
cd web
npm install
npm run dev

2. 访问界面

3. 界面功能

🏗️ 架构设计

AI Agent 异步使用架构

系统架构

┌─────────────────────────────────────────────────────────┐
│ 用户交互层 │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI 命令 │ │ Web 界面 │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────┐
│ API 层 │
│ HTTP API Server (RESTful + CORS) │
└─────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────┐
│ 编排层 │
│ 全局 QueueManager + Runner(并发 claim / 断点恢复) │
└─────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────┐
│ 执行层 │
│ Provider Adapter → Codex / Claude Code / Gemini / Kiro │
└─────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────┐
│ 存储层 │
│ SQLite(5 张表) │
└─────────────────────────────────────────────────────────┘

数据模型

batch_jobs (批次)
 ├─ id, name, prompt_template
 ├─ verifier_prompt_template
 ├─ max_qc_rounds, max_executor_retries, run_no
 ├─ status(completed=全成功, failed=存在失败/耗尽, canceled=已终止)
 └─ created_at, finished_at
batch_items (测试项)
 ├─ id, batch_job_id, item_value
 ├─ status, current_attempt_no, current_qc_no
 ├─ last_error, confirmation_question, confirmation_answer
 ├─ lock_owner, lock_expires_at, queued_at
 └─ created_at, finished_at
attempts (执行尝试)
 ├─ id, batch_item_id, attempt_no, run_no
 ├─ attempt_type (worker/repair)
 ├─ status, stdout, stderr, exit_code
 └─ started_at, finished_at
qc_rounds (质检轮次)
 ├─ id, batch_item_id, qc_no, run_no
 ├─ status, verdict, feedback
 └─ started_at, finished_at
batch_templates (批次模板)
 ├─ prompt_template, verifier_prompt_template, items_text
 └─ max_qc_rounds, max_executor_retries, execution_mode, executor_provider

多轮质检流程

开始
 │
 ▼
Worker 执行
 │
 ▼
保存 attempt(stdout/stderr/exit_code)
 │
 ▼
是否配置 verifier? ──否──▶ 标记为 success ──▶ 完成
 │
 是
 ▼
运行 Verifier(可读取 stdout/stderr/exit_code)
 │
 ▼
解析 verdict JSON
 │
 ▼
verdict.pass? ──是──▶ 标记为 success ──▶ 完成
 │
 否
 ▼
是否达到 max_qc_rounds? ──是──▶ 标记为 exhausted ──▶ 完成
 │
 否
 ▼
Repair(携带上一轮证据 + feedback,修复并复测)
 │
 ▼
保存 repair attempt(stdout/stderr/exit_code)
 │
 ▼
进入下一轮 Verifier

📂 项目结构

qcloop/
├── cmd/qcloop/ # CLI 入口
│ └── main.go
├── internal/
│ ├── db/ # 数据库层
│ │ ├── db.go # 数据库连接
│ │ ├── models.go # 数据模型
│ │ ├── schema.go # 表结构
│ │ └── dao.go # CRUD 操作
│ ├── core/ # 编排引擎
│ │ └── runner.go # 多轮质检逻辑
│ ├── executor/ # 执行器
│ │ ├── provider.go # provider 选择与默认值
│ │ ├── agent_cli.go # Claude/Gemini/Kiro 共享 CLI 执行器
│ │ ├── cli_process.go # 进程探测与执行公共逻辑
│ │ ├── codex.go # Codex Executor
│ │ └── fake.go # Fake Executor(测试用)
│ └── api/ # HTTP API
│ └── server.go # RESTful 服务器
├── web/ # React 前端
│ ├── src/
│ │ ├── components/ # UI 组件
│ │ │ ├── BatchTable.tsx
│ │ │ ├── CreateJobForm.tsx
│ │ │ └── StatusBadges.tsx
│ │ ├── hooks/ # React Hooks
│ │ │ └── usePollingItems.ts
│ │ ├── api/ # API 客户端
│ │ │ └── index.ts
│ │ ├── types/ # TypeScript 类型
│ │ │ └── index.ts
│ │ ├── App.tsx
│ │ ├── main.tsx
│ │ └── styles.css
│ ├── index.html
│ ├── package.json
│ ├── tsconfig.json
│ └── vite.config.ts
├── docs/ # 文档
│ ├── AI_AGENT_USAGE.md # 多 AI CLI 一句话使用指南
│ ├── PRD.md # 产品需求文档(含设计哲学、用户故事)
│ ├── TEST_CASES.md # 测试用例(32 个测试点)
│ ├── QUICK_TEST.md # 快速测试指南
│ ├── GOAL_INTEGRATION.md # Codex Goal 集成方案
│ ├── PROJECT_SUMMARY.md # 项目完成总结
│ └── images/ # 文档图片(含异步使用架构图)
├── skills/ # 给 AI agent 使用的 qcloop 技能与 JSON CLI
│ └── qcloop/
│ ├── SKILL.md
│ ├── bin/qcloop-skill
│ └── scripts/qcloop_cli.py
├── packages/ # 可发布包
│ └── qcloop-skill-cli-npm/ # @limecloud/qcloop-skill-cli npm 包
├── go.mod
├── go.sum
├── README.md
└── LICENSE

👥 用户故事

故事 1:批量执行测试用例

故事 2:确保测试质量

故事 3:追踪批次执行情况

📖 文档

🛠️ 技术栈

🔧 开发

运行测试

go test ./...

本地开发

# 后端
go run ./cmd/qcloop serve --addr :8080 --workers 2
# 前端
cd web
npm run dev

构建生产版本

# 后端
go build -o qcloop ./cmd/qcloop
# 前端
cd web
npm run build

🤝 贡献

📝 License

🙏 致谢

⬆ 回到顶部

Made with ❤️ by the qcloop team