req-kit 是运行在 Paseo 上的需求开发体系，面向非专职开发、但有一定技术背景的同事——测试、产品经理、项目经理。你在对话里讲清楚想要什么、确认一份需求说明；之后的工作由不同角色的 agent 完成，进展和结论发回同一个对话，最后你按验收标准逐条验收。全程只做本地提交，合并和上线由人决定。
你 ▸ /req 登录页增加短信验证码登录
AI ▸ 我理解的是……对吗？验证码有效期是 5 分钟还是 10 分钟？（推荐 5 分钟：……）
… 一次一个问题，写成 spec.md，另一个模型独立审阅，你确认
AI ▸ 已在后台开始开发。每个步骤都在这个对话的子 agent 列表里。
◦ 技术方案已经确定（审核 1 轮），开始写代码。
◦ 代码已经写完并通过检查，开始按验收标准逐条验证。
AI ▸ 结论：已完成，可以验收。6 条验收标准全部通过……完整报告：report.md
特性
- 对话对齐需求：一次一个问题，给出选项和推荐；确认前由另一个模型独立审阅需求说明，减少返工。
- 后台 agent 流水线：方案设计 → 方案审核 ⇄ 修订 → 代码实现（适合时 TDD，大需求按切片逐片实现）→ 代码评审 ⇄ 修复 → 提测说明 → 服务启动 → 功能验证 → 缺陷修复 ⇄ 复验 → 完成报告。
- 按需求类型走不同的做法：缺陷先复现、找到根因再修；重构先用测试锁住行为再小步改；评估只调研、写评估报告，不写代码。
- 让分歧更早暴露：验收标准带具体例子，测试直接用它们作为期望值；界面改动在写代码之前请你确认预览和原型；代码评审分规格、规范两个方向；反复出现的问题记下来，提示变成项目的规则。
- 质量门：流水线自己运行项目的 lint、类型检查、测试、构建，只拦改动前通过、现在失败的检查，发回那一步的 agent 修复；代码评审前比对方案列出的文件，清单之外的改动要说明理由。
- 联合需求：前后端分在两个仓库的需求可以一起做：先定接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证。
- 做事的和检查的分开：builder 与 reviewer 可用不同模型；可选的评审小组并行评审、方案提案并行比较；其他仓库（例如后端）可以登记为只读参考。
- 如实报告：每一步的结论只看结果文件和证据；没验证的写"未验证"，遗留问题写进报告。
- 分阶段提测：研发完成写好提测说明，可以停下来交给测试同事，在已部署的测试环境中验证；缺陷可退回研发。
- 用好 Paseo：复用 agent profile、
paseo.json 服务和 worktree、定时任务、内置浏览器；几个需求并行互不干扰。
- 可恢复：中断后从断点继续；需求变了只处理变化的部分；临时错误自动重试、自动继续。
- 安全边界清楚：不合并、不推送、不上线；不连接生产环境，不使用生产凭据。
快速开始
在要运行 Paseo 的机器上（需要 Node.js 22+；还没有 Paseo 也可以，会一起装好）：
# 任何系统；公司内网只有 npm 镜像时加 --registry=<镜像地址>（npx -y --registry=… paseo-req-kit@latest install）
npx -y paseo-req-kit@latest install
# macOS、Linux、Windows 的 Git Bash 或 WSL
curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh
# Windows PowerShell
irm https://paseo-req-kit.vercel.app/install.ps1 | iex
安装脚本会检查环境、安装 paseo-req-kit；没有 Paseo 时安装 Paseo 命令行，开启它自带的网页界面（http://localhost:6767/）并启动 daemon；为 Claude Code / Codex / OpenCode / Pi 安装 /req 等 skill，并引导你为 builder 和 reviewer 选择 agent。再次运行即升级；req docs 在本机打开文档。然后：
req doctor —— 检查 daemon、agent 模式和额度；- 在项目的 Paseo 对话中运行
/req-setup —— 接入项目（每个项目一次）；
- 在 Paseo 对话中输入
/req 我想…… —— 开始第一个需求。
想在 Paseo 的界面（网页端、桌面版、手机）里看需求总览和进度、确认方案或停止继续，运行 req plugin install 安装 req-kit 的 Paseo 插件。
其他安装方式（npm、离线安装包、git）、各 agent 的配置写法和升级回滚，见 安装与升级。
工作原理
Paseo 对话（/req） 流水线引擎（后台进程）
访谈 → spec.md → 独立审阅 → 确认
启动 ──────────────────────────────────────► 研发：方案设计 → 审核 ⇄ 修订 → 实现
→ 代码评审 ⇄ 修复 → 提测说明
┄┄ 闸口：连续 / 分阶段 / 只做研发 ┄┄
验证：服务启动 → 功能验证 → 缺陷修复 ⇄ 复验
→ 完成报告
◄── 进展 · 需要决定的问题 · 等待批准 · 结论 ──
- 每个步骤是一个新的 Paseo agent，作为子 agent 挂在发起的对话下；步骤之间只通过功能目录
docs/features/<日期>-<名称>/ 中的文件交接。
- 每一步写一个 JSON 结果文件，流水线据此决定下一步，不解析 agent 的回复文字。
- 运行状态在
.pipeline/state.json，可以随时查看进度、暂停、继续。
详见 工作原理。
文档
这些文档也发布在 文档站点 (Vercel)（附 GitHub Pages 镜像），附有命令和配置参考。
项目结构
| 目录 | 内容 |
|---|
skills/ | 安装到各 agent 的 skill：入口（/req、/req-setup、/req-doctor、/req-retro）、方法（访谈、需求说明、验收标准、结果说明）、原则 |
engine/ | 流水线引擎：src/ 程序、prompts/ 步骤提示词、test/ 场景测试（模拟 Paseo 运行时） |
bin/ | req、start-pipeline、req-doctor 命令 |
install.mjs、bin/bootstrap.mjs、install.sh、install.ps1 | 安装、升级、回滚、卸载；一键安装（req install）和安装脚本 |
contracts/ | spec、状态文件、结果文件、通知事件等的格式约定 |
docs/ | 使用指南与设计决定（ADR） |
evals/ | 端到端评估：样例仓库、隐藏验收测试、对话剧本 |
site/ | 文档站点（VitePress） |
notifiers/ | 外部通知（企业 IM 等）的模板 |
入口之间不互相调用；引擎不调用 skill，只读取提示词和原则索引。
开发
npm install
npm test # 引擎场景测试（模拟 Paseo）、安装器、一键安装脚本、体检、skill 校验
npm run typecheck
npm run eval:self-check # 评估用例的参考实现能否通过隐藏验收（不需要 Paseo）
npm run eval # 用真实的 Paseo 和 agent 跑端到端评估
cd site && npm install && npm run dev # 本地预览文档站点
引擎的编排逻辑用模拟的 Paseo 运行时（engine/test/fake-runtime.ts）运行真实代码来测试；真实 daemon 和 agent 的行为、提示词的产出质量通过冒烟测试和评估确认。发布流程见 维护者指南。
参与贡献
- 先读 范围：新的提议需要服务于"把一个需求从对齐做到可验收"，并有至少两个真实场景。
- 修改设计决定时新增一条 ADR；修改文件格式时同时更新 contracts/、代码、测试和 CHANGELOG 的"升级须知"。
- 提交前运行
npm test 和 npm run typecheck。
许可
MIT
