项目定制与运行规则

每个需求一个 worktree 工作区

在 Paseo 中为每个需求新建工作区：New workspace → 选择项目 → Isolation 选 New worktree → 起点选主分支，然后在这个工作区的对话里输入 /req。

流水线在这个工作区自己的目录和分支上运行、提交，不影响项目主目录。
同一个目录一次只能运行一条流水线；用了 worktree，几个需求可以同时进行。
在主目录发起时，/req 会先建议改用 worktree；使用者坚持的话，它会新建 feature/<功能目录名> 分支再继续。

分支规则：流水线把启动时检出的分支作为本次需求的工作分支，所有步骤都提交到这里，不切换、不新建分支。它拒绝在默认分支（main、master 或 origin/HEAD 指向的分支）或 detached HEAD 上启动；续跑时分支变了也会拒绝。

档位

档位	适用	访谈	流程
快速（`quick`）	小改动：文案、样式、配置项、字段显示等，不涉及数据结构、权限、对外接口	只问要改什么、改成什么样、不改什么、验收标准	审核、评审、缺陷修复各一轮；不做服务启动验证；产物从简
标准（`standard`）	其他情况	完整访谈	审核最多 2 轮、评审最多 3 轮、缺陷修复最多 3 轮

/req 会根据需求推荐档位，用户确认后写进 spec（- 档位：快速）。流水线按以下顺序决定档位：--profile 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 defaultProfile。各档的轮数和是否做服务启动验证可以在配置的 profiles 中调整。

需求类型

spec 头部的 - 类型： 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：

类型	做法	关键证据
缺陷（`缺陷`、`bug`）	方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 `diagnosis.md`（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败	同一个复现，修复前失败、修复后通过
重构（`重构`、`技术改进`）	先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变"	重构前后同一组测试一致
评估（`评估`、`调研`）	只读：调研评估（`assessment.md`）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续	引用的代码位置和实际运行的命令

各类型的做法写在 engine/prompts/types/<类型>.md，按步骤分节，接在每一步的任务之后；可以用 prompts.local/types/ 覆盖。不想用某个类型的做法时，从配置 requirementTypes（默认 ["defect", "refactor", "assessment"]）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。

方案确认点：开工前请需求方确认"做完后会看到什么"

方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 preview.md（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 prototype/ 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 --approve（终端里 req approve <需求>）开始写代码；要改的，更新需求说明后 --resume，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。

配置	默认	说明
`designApproval.mode`	`ui`	`ui`：方案判断这次是界面改动（结果文件 `ui_change`）时才停；`always`：每次都停；`off`：不停
`designApproval.profiles`	`["standard"]`	哪些档位使用；快速档默认不停
`designApproval.autoContinueHours`	0	大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 `waitingReminderHours` 会提醒一次

等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 approval 事件。评估类需求不写代码，不经过确认点。

原型审查页（1.13 起）。 有 prototype/ 的需求，插件的需求页面和"等你处理"里有"审查原型"按钮（等待确认方案时是最醒目的"审查原型并确认方案"），审查页嵌在 Paseo 的网页端和桌面端里打开，手机上在浏览器中打开；终端里是 req review <需求>。需求方在原型上点选要改的地方（页面记下元素、文字、颜色、大小和位置）、双击直接改文字，切换状态和电脑、手机宽度，然后提交：意见整理成带位置信息的清单转给需求会话（与插件中写修改意见的效果相同），或者直接确认方案。草稿和提交记录在功能目录的 .pipeline/review/ 中，每一版原型也存在那里，原型改过后页面会标出这一版改了哪里。

为了让审查页能用，方案设计按约定写原型：每个改动区域标 data-ac（对应的 AC）和 data-label（用需求方的话说是什么），各种状态包在 <section data-state="状态名"> 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。

审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 127.0.0.1，地址中带随机令牌（插件设为只读时给只读的地址）。审查页允许被本机地址上的页面（Paseo 网页端）嵌入；要限定或放开，设 REQ_KIT_REVIEW_FRAME_ANCESTORS（CSP frame-ancestors 的值）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 REQ_KIT_REVIEW_HOST（例如 0.0.0.0）、REQ_KIT_REVIEW_PUBLIC_URL（别人访问这台机器用的地址，例如 http://10.1.2.3:6781），需要时用 REQ_KIT_REVIEW_PORT 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量（只设 REQ_KIT_REVIEW_HOST 时，地址用这台电脑的计算机名）。没有设置时从别的电脑打开 Paseo 网页、点"审查原型"，页面会说明为什么打不开、该怎么设置（1.13）。

代码评审分两个方向

标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论：

规格评审：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。
规范评审：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。

两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。reviewAxes.enabled 设为 false 关闭，reviewAxes.profiles 选择档位（默认只有标准档）。配置了评审小组（reviewPanel）时，以评审小组为准。

验收测试先提交

方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。

术语表和范例文件

GLOSSARY.md（仓库根目录）：业务词、含义、代码中的名字。/req-setup 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。
范例文件：/req-setup 在 project-notes.md 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。

反复出现的问题变成规则

完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 lessons.tsv（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，req digest 的需求总览会列在"反复出现的问题"中，/req-retro 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 .requirement-pipeline/lessons-handled.txt（一行一个），总览不再提示。

质量门：流水线自己运行的检查

项目配置 .requirement-pipeline.json 的 checks 列出流水线自己运行的检查，通常由 /req-setup 从实际跑通的命令写入：

json

{
  "checks": [
    { "name": "lint", "command": "npm run lint" },
    { "name": "web 测试", "command": "npm test", "cwd": "web" },
    { "name": "server 测试", "command": "npm test", "cwd": "server", "timeoutMinutes": 15 }
  ]
}

基线：每次尝试开始时（方案设计之前）把所有检查运行一遍，记下哪些原本就失败。
之后：代码实现（每一片）、评审问题修复、缺陷修复结束后，运行与改动相关的检查。改动前通过、现在失败的，把命令和输出发回那一步的 agent 修复，最多 qualityGate.fixAttempts 次（默认 2）。仍然失败时照常往下走，交给代码评审和报告：报告的结论最高为"有遗留问题"。原本就失败的检查不拦，但会在报告中列出。
多模块：带 cwd 的检查只在这个目录有改动时运行；需要更精确时用 paths（例如 ["server/", "shared/"]，可以用 *）。
只放几分钟内能跑完的检查（格式、lint、类型检查、单元测试、构建）。端到端测试、需要启动服务的检查由功能验证负责。命令通过系统 shell 运行（Windows 上是 cmd.exe），和 paseo.json 一样写成各系统通用的形式。单项检查的时限是 timeoutMinutes，默认 qualityGate.timeoutMinutes（20 分钟）。
输出保存在 <功能目录>/.pipeline/checks/<步骤>/，结果在状态文件的 gate 中，进度查询显示最近一次的结果。没有配置 checks 时不运行，报告注明"未配置"，/req-doctor 会提醒。

按切片实现

方案把实施计划分成几个纵向切片（每片是一段能单独演示和验证的功能，例如"能发送验证码"）。标准档有两片以上时，代码实现按片逐个进行：每片一个新的 agent、各自提交、各自过一次质量门，子 agent 列表中显示为"5-代码实现第2/3片"；中断后只重做当前片。快速档、只有一片时与原来相同。

配置	默认	说明
`slices.profiles`	`["standard"]`	哪些档位按切片实现；`[]` 关闭
`slices.max`	6	最多几片；方案分得更多时最后几片合并

范围检查

方案在结果文件中列出预计改动的文件和目录（files）。代码评审前，流水线比对这次实际改动的文件，把清单之外的列给评审逐一判断：为实现需求所必需的写理由，与需求无关的要求撤回。结论写进报告附录。

关联仓库（只读参考）

前端项目要用后端的接口、一个服务要用另一个服务的数据格式时，在项目配置中登记相关的仓库，步骤 agent 就能读它们，不用猜：

json

{ "relatedRepos": [{ "name": "后端", "path": "../backend", "role": "提供登录和订单接口" }] }

path 相对项目目录（团队约定把相关仓库放在同一个上级目录最方便），也可以写 ~/ 开头的路径。本机没有这个目录时跳过，/req-doctor 会提醒。
步骤会看到每个关联仓库的位置、当前分支和提交，只读参考：不修改、不提交、不切换分支。验证需要对方的服务时，优先用已部署的测试环境。
两边都要改的需求（例如后端加接口、前端加页面）可以作为联合需求一起做，见下一节。

联合需求：一个需求，几个仓库

需求说明头部写 - 联合开发：后端（relatedRepos 中登记的名称，最多两个）时（1.8 起）：

准备：流水线为每个联合开发的仓库新建一个 Paseo 工作区，分支同名（feature/<需求>），从那个仓库当前检出的分支切出；那份检出本身不动。需求说明同步过去并提交。
方案和接口约定：在主仓库（发起需求的仓库）设计整个需求，design.md 按仓库分开写，contract.md 写双方的接口约定（字段、错误码、示例）。方案审核把接口约定一起审，通过后冻结。需求说明、方案、接口约定同步到其他仓库的功能目录并提交。
同时开发：每个仓库各由一个 agent 实现、各自评审和修复，互不等待：提供接口的一边按约定写接口测试，调用的一边用约定的示例做测试替身。每个仓库用它自己的 checks 做质量门（写在它自己的 .requirement-pipeline.json 中），用它自己的项目说明和验证方法。
一起验证：提测说明、功能验证和报告在主仓库。验证前各仓库 paseo.json 中的服务都由 Paseo 用当前代码启动；验证结果写明每个缺陷属于哪个仓库，缺陷发回那个仓库修复，再一起复验。
合并：每个仓库各有自己的分支，只做本地提交。提测说明和报告写明合并顺序（通常先合提供接口的一边），由人来合并。

一个仓库的步骤失败时，流水线等其他仓库正在进行的步骤做完再中断；继续时沿用已建的工作区和已完成的步骤。不做的：跨仓库的统一提交或合并、自动部署、超过三个仓库、克隆本机没有的仓库。设计决定见 ADR 0025。

执行方式：连续、分阶段、只做研发

第 3–11 步分为两个阶段：研发（方案设计 → 方案审核 ⇄ 修订 → 实现 → 代码评审 ⇄ 修复 → 提测说明）和测试验证（服务启动 → 功能验证 → 缺陷处理），之后是完成报告。研发阶段的最后一步写提测说明 handoff.md：改了什么、怎么跑起来、自测结果、建议重点测试、已知问题、测试前的准备。

执行方式	研发完成时	适合
连续（`continuous`，默认）	直接进入测试验证，与 1.7 之前一致	本地就能验证的项目
分阶段（`gated`）	停下来通知"研发完成，可以提测"；由人说"开始测试验证"，或到 `--verify-at` 预约的时间开始	有专门测试、需要先部署测试环境
只做研发（`develop-only`）	写研发报告后结束；验收时按提测说明人工测试。之后仍可用 `--phase verify` 让流水线验证	测试必须由人完成

来源，后者覆盖前者：配置 phases.mode → spec 头部 - 执行方式：分阶段 → 启动参数 --phases。有测试团队的项目建议在项目配置中写：

json

{
  "phases": {
    "mode": "gated",
    "verify": {
      "environment": "deployed",
      "agents": { "reviewer": { "paseoProfile": "测试" } },
      "defects": "handback"
    }
  }
}

`phases.verify` 中的配置	默认	作用
`environment`	`"local"`	`"deployed"`：不在本地启动服务，对已部署的测试环境验证。功能目录中需要 `test-env.md`（地址、怎么确认版本、账号和口令从哪里取、可用的测试数据；不写口令本身），没有就拒绝开始。开始测试时可用 `--verify-env` 临时指定
`agents`	`{}`	测试阶段的步骤（服务启动、功能验证、缺陷修复、复验）用的 agent，格式同顶层 `agents`，可用 `paseoProfile`；没写的角色用顶层的。完成报告仍用顶层的 builder
`defects`	`"fix"`	`"fix"`：当场修复并复验；`"handback"`：只记录，在 `changes.md` 追加"测试验证退回"一节，回到研发阶段从方案设计开始修复，经过代码评审、重写提测说明后再提测（分阶段时再次停在闸口），最多退回档位的缺陷修复轮数次；`"report"`：只记录，直接出报告。开始测试时可用 `--defects` 临时指定
`serviceStart`	`null`	测试阶段是否做服务启动验证；`null` 按档位。`deployed` 时不做

谁可以开始测试验证：发起的对话；需求在自动新建的工作区中（--worktree）时，同一仓库任何工作区中的对话也可以（研发阶段仍只能从原对话操作），之后的通知转到那个对话。测试阶段开始前需求说明改过的，先回到研发阶段处理变化。用时与用量在状态和完成报告中按阶段分别统计。见 ADR 0022。

进展通知

除了"需要需求方决定""等待批准""中断""完成"这几种通知，流水线默认还会在三个节点各发一句进展：技术方案已经确定、开始写代码；代码通过检查、开始验证；验证发现问题、正在修复。续跑时不会重复发送。不需要的话，在配置中设 "notifyMilestones": false。

同时发到企业 IM：配置 notifiers 后，这些通知还会交给你实现的通知模块，例如转发到企业内部 IM。notifiers 只能写在本机或团队配置中（项目配置中的会被忽略）。做法见安装与升级第 12 节，事件格式见 contracts/notifier-event.md。

按人通知（1.12 起）：从卡片开始的需求，需要需求方处理的事（回答问题、确认方案）和结果（研发完成、流水线结束）在事件中标明发给需求方本人（people.audience 为 requester）。在本机或团队配置中写上姓名到账号的对应，事件里就带上账号，通知模块可以按人发送；其余事件发到群里：

json

"people": { "张广祥": { "um": "ZHANGGX001" } }

运行时文件

运行时的文件都在功能目录下的 .pipeline/ 中，不会被提交：

state.json：当前状态、档位、工作分支、每个步骤的 agent ID 和结果、历次尝试的记录
results/<步骤>.json：每个步骤的结果文件
pipeline.log：运行日志，包括使用了哪些配置文件、发出的每一条通知和每次自动重试

用时与用量：每个步骤记录 agent 的起止时间和 agent 报告的 token 用量、费用（有的 agent 不报告）。查看进度（req status）、需求总览（req list）和完成报告都会显示合计。评审小组的成员并行运行，所以"agent 合计用时"可能比实际经过的时间长。

按项目定制

本机配置（~/.req-kit/config.json）对所有项目生效。各项目可以在仓库里放自己的定制，随代码一起提交，团队共享。最简单的做法是在项目根目录的对话中运行 /req-setup，它会生成前两份文件并实际运行验证命令：

text

<仓库根目录>/
├── .requirement-pipeline.json          覆盖本机配置中的项
└── .requirement-pipeline/
    ├── project-notes.md                追加到每个步骤的提示词；/req 访谈前也会读
    ├── verify.md                       验证方法；追加到实现、修复、服务启动、验证、复验步骤
    └── steps/
        └── <步骤>.md                   只追加到某一步，例如 verify.md

.requirement-pipeline.json 可以设置除 daemonUrl、daemonPasswordEnv、teamConfig 以外的所有项（这几项描述的是本机，写了会被忽略，并在日志和 /req-doctor 中提示）。例如这个项目默认走快速档、实现用另一个模型：

json

{
  "defaultProfile": "quick",
  "agents": { "builder": { "provider": "claude/<模型 ID>", "modeId": "bypassPermissions" } },
  "profiles": { "standard": { "rounds": { "codeReview": 2 } } }
}

agents 按角色整体替换；profiles、stepTimeoutMinutes 按项合并。

project-notes.md 写这个项目的约定，例如：

markdown

- 包管理用 pnpm，不要用 npm。
- 不要改动 legacy/ 目录。
- 数据库变更必须写成 migrations/ 下的迁移脚本。

verify.md 写这个项目怎么安装依赖、启动服务、运行测试、准备测试数据，命令要实际运行过。结构建议见 contracts/verify.md。步骤 agent 发现它过时或不准确时，会在 service-start.md 或 verification.md 的"建议写入 verify.md 的内容"一节给出实际可行的做法；再次运行 /req-setup 会参考这些建议更新它。项目的构建文件改过而 verify.md 没有更新时，/req-doctor 会提醒。

项目配置还常写 checks（质量门）和 relatedRepos（关联仓库），见上文。checks、relatedRepos、requirementTypes 整体替换，qualityGate、slices 按项合并。

steps/<步骤>.md 的文件名用步骤 ID：design、design_review、design_revise、implement、code_review、review_fix、service_start、verify、defect_fix、reverify、report。例如 steps/verify.md 写"端到端测试用 pnpm e2e 运行，测试账号见 docs/test-accounts.md"。

这些内容追加在步骤任务之后，并注明"与通用要求冲突时以项目说明为准"，但"如实报告"和安全要求始终有效。

统一修改某一步的提示词：在 ~/.req-kit/prompts.local/ 中放入与 engine/prompts/ 中同名的文件，就会替换随版本发布的那一篇。升级只替换版本目录，prompts.local/ 不受影响；但新版本对同名提示词的改进也不会生效，升级时请对比。这是最后的手段：能写进项目说明、配置或测试的，优先写在那里。

paseo.json：环境准备和由 Paseo 管理的服务（推荐）

paseo.json 是 Paseo 自己的项目文件，放在仓库根目录并提交。/req-setup 可以生成它：

json

{
  "worktree": { "setup": ["npm ci", "node scripts/paseo/copy-local-files.mjs .env"] },
  "scripts": {
    "test": { "command": "npm test" },
    "web": { "type": "service", "command": "node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}" }
  }
}

paseo.json 是团队共用的，而 Paseo 在各系统上用不同的 shell 执行它的命令（macOS/Linux：bash 和 sh；Windows：准备命令用 PowerShell，带 -ExecutionPolicy Bypass，不受执行策略限制；脚本和服务用 cmd.exe）。所以 /req-setup 只写各系统一样的命令，用到环境变量的地方交给它写进项目的两个小脚本：scripts/paseo/copy-local-files.mjs（从来源目录复制不提交的本地文件，没有就跳过）和 scripts/paseo/with-port.mjs（把 {PORT} 换成 Paseo 分配的端口，并设置 PORT）。手写 $PASEO_PORT、%PASEO_PORT%、cp、Copy-Item 这类只在某个系统上能用的命令时，/req-doctor 会指出：在本机上会失败的标为⚠，只是换系统会失败的给出提示。

worktree.setup：Paseo 新建 worktree 工作区时自动执行，新需求的工作区一建好就装好了依赖、带上了本地配置。
"type": "service" 的脚本：流水线在服务启动验证、功能验证、缺陷修复和复验之前，通过 Paseo 带着当前代码重启它们，把地址（http://web--<分支>--<项目>.localhost:6767 这样的代理地址）交给步骤 agent，验证结束后停止。Paseo 为每个工作区分配独立端口，几个需求同时验证不会冲突，服务必须监听 Paseo 分配的端口（环境变量 PASEO_PORT，用 with-port.mjs 传给程序）。
服务没有启动成功时，最后的输出写到功能目录的 .pipeline/services/<服务名>.log，交给步骤 agent 查原因。
只有从 Paseo 对话启动的流水线才会这样做（需要知道是哪个工作区）。不想用时在配置中设 "paseoServices": "off"，步骤 agent 会像以前一样自己启动服务。serviceReadySeconds（默认 120）是等待服务就绪的时间。
在 Paseo 设置中打开 Enable Paseo tools 后，步骤 agent 改完代码还可以自己重启这些服务。
写错时服务起不来，流水线会改由步骤 agent 自己启动服务，不会中断。
PowerShell 被完全禁用（不只是执行策略）的 Windows 机器上，worktree.setup 无法执行；新工作区不会自动装依赖，步骤 agent 会按验证方法自己准备。

额度提醒

开始前，流水线读取 Paseo 的用量信息（需要 Paseo 能读到对应 agent 的订阅用量）。所用 agent 的某个额度窗口用到 quotaWarnPercent（默认 85）以上时，在对话里提醒一次，流水线照常进行；用完时遇到限流会自动等待重试。设为 0 关闭提醒。

token 预算和用时估算（1.13 起）

内网模型通常不报金额，所以按 token（输入 + 输出）计：

配置	默认	说明
`budget.tokens`	`null`（不限）	一个需求所有步骤、所有尝试合计最多用多少 tokens，例如 `3000000`。每个新步骤开始前检查：用完时，已完成的步骤都保留，流水线在下一步开始前停下（状态"已中断"，停下原因 `budget`），请对话问需求方是否继续；继续（`req resume` 或在对话里说"继续开发"）会再给一份同样多的预算
`budget.warnPercent`	80	用到预算的这个比例时在对话里告知一次（不停），同时发 `milestone` 外部通知

写在本机、团队或项目配置中都可以，例如 "budget": { "tokens": 3000000 }。还没有数据时，先不设预算跑几个需求，用 req stats 的"token 花在哪"看每个需求的中位数，再按它的两三倍设。

agent 不报告 token 用量时（有些模型或接入方式不报告），预算不会起作用：设了预算的需求在第一个步骤结束后会在对话里说明一次，流水线照常继续；req doctor 也会检查本机最近的需求有没有用量数据。

用时估算不用配置：本机已完成的同档位需求有 3 个以上时，开始开发的回复里写出"agent 合计用时和 token 的中位数"作为参考；req status 和插件的需求页面显示"预计还要约多久"（按中位数减去已用的 agent 时间，不含等人的时间），超过中位数时如实说"已超过通常的用时"。

并行编排：确认前审阅、方案提案、浏览器验证

配置	默认	作用
`specReview`	`"standard"`	请需求方确认之前，由 reviewer 在后台独立审阅需求说明草稿，问题写进 `spec-review.md`。`"always"` 快速档也做，`"off"` 关闭
`designProposals`	关闭	`{"enabled": true}` 后，标准档的方案设计之前由几个 agent 并行各提一份方案（`design-proposals/`），方案设计比较后决定。`members` 不写时用 builder 和 reviewer，也可以像评审小组一样列出成员（可用 `paseoProfile`）。需求变更后的增量继续不做
`browserVerify`	`"auto"`	功能验证、缺陷修复、复验检查网页界面的方式。1.13 起总是附上界面检查命令 `req ui-check`：用本机的 Edge 或 Chrome（无界面）打开页面，按电脑和手机宽度用文字报告显示不全、遮挡、超出屏幕、图片没加载、文字太淡、控件没有名字、控制台报错和请求失败，并和确认过的原型逐项对文字；不需要模型看图，也不需要 Paseo 桌面端。第一次使用时从 npm 源安装 `playwright-core` 到 `~/.req-kit/tools`（不下载浏览器）。步骤 agent 还有 Paseo 浏览器工具（桌面端在线）时，另外按验收标准在浏览器中实际操作。`"off"` 都不用

Paseo 自带的 /paseo-advisor、/paseo-committee 等编排 skill 也可以单独使用，例如对一个疑难问题请两个模型分别分析；它们不参与流水线（见 ADR 0019）。

自动新建工作区（可选）

在项目主目录、主分支上发起的需求，可以用 --worktree 启动（/req 中的"启动（自动新建工作区）"）：流水线从当前分支切出 feature/<功能目录名>，在 Paseo 中新建 worktree 工作区，把需求说明移过去并提交，之后的步骤都在那个工作区中运行，仍然挂在发起的对话下。对话的工作目录不变，查看进度、暂停、继续都在原对话中进行；读写需求文件用通知中给出的完整路径。只能在第一次启动时选择。见 ADR 0018。

1.14 起：

启动没成功也能接着做。 工作区一建好就记下来（~/.req-kit/worktrees/）。之后不管哪一步失败（建工作区慢、启动前的检查没通过），再次执行启动命令都会在这个工作区里接着开始，不会报"分支已存在"，也不会留下只有需求说明的分支。新建工作区最多等 15 分钟（以前是 2 分钟，大仓库在 Windows 上常常不够）。以前版本留下的"分支和工作区都在、开发没开始"的，也会由 Paseo 接手那个目录接着做。
访谈改过的 GLOSSARY.md、docs/adr/ 一起带过去，和需求说明在需求自己的分支上一起提交；主目录里的这些未提交改动保留不动（可能和别的改动在一起），确认后可以撤销。
如实提示起点的问题：需求说明已经提交在主分支上、本地主分支比远端落后、主目录里还有别的未提交改动时，启动结果里会写明。流水线不改动主分支。

调度：预约、提醒、自动继续、排队

需要"以后再做"的事，流水线用 Paseo 的定时任务把一条写明步骤的消息发回发起的对话，由对话 agent 执行（机器或 daemon 重启后仍然有效，在 Paseo 的 Schedules 中可以看到）。暂停命令会取消这些预约。

配置	默认	作用
（启动参数 `--at`）	—	预约开始时间：`22:00`、`明天 8:30`、`2026-10-14 08:30`、`+2h`
`waitingReminderHours`	24	等待需求方回答、或研发完成后等待测试验证超过这么久，在对话里提醒一次；0 关闭
（启动参数 `--verify-at`）	—	分阶段时，研发完成后在这个时间自动开始测试验证（写法同 `--at`；隐含分阶段）。研发完成时时间已过就直接继续
`autoResumeMinutes` / `autoResumeMax`	30 / 2	临时错误（重试用完）中断后，这么久之后在对话里自动继续；每次尝试最多几次；0 关闭
`watchdogMinutes`	60（1.12 起默认打开）	运行期间对话定时检查，后台进程意外退出时自动继续。每次检查对话 agent 会运行一个回合；0 关闭。1.13 起：装了 req-kit 插件时，插件每 5 分钟在 daemon 里直接检查本机所有需求，发现"运行中但后台进程已不在"的就执行 `req resume`（不经过模型，每个进程只继续一次，每个需求 24 小时内最多 3 次），这时不再预约对话的定时检查；插件设为只读时不做。接单器（`req factory`）每次检查也同样直接继续
`maxConcurrentPipelines`	0（不限）	本机同时运行的流水线上限，满了排队。只能写在本机配置中才有意义

需求总览

req digest 在项目目录中列出所有工作区里的需求，按"需要处理、待验收、开发中、对齐中、已验收（最近 7 天）"分组，附用时与用量。--notify 同时发给外部通知（事件类型 digest）；--schedule "<cron>" 让 Paseo 按时间表（本机时区）启动一个短暂的 agent 执行 req digest --notify，例如每周一 9 点：req digest --schedule "0 9 * * 1"；取消：req digest --cancel <定时任务 ID>。

使用统计

1.9.0 起，每次流水线运行结束时，引擎在本机的 ~/.req-kit/usage/runs.jsonl 追加一条记录：各步骤的用时和用量、质量门、评审和缺陷轮数、结束时的状态（格式见使用记录）。只记在本机，不记需求内容和代码，也不会自动发往任何地方。

req stats：最近 30 天的统计（--since 2w、--since 2026-10-01、--month 2026-10）：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败）、各种等待的时长、各步骤用时、用量，以及不同 builder 的比较。1.13 起有"token 花在哪"一节：按步骤和按模型的 token 及占比、返工（方案修订、评审问题修复、缺陷修复、复验，以及第 2 轮起的审核和评审）的占比、输入中来自提示缓存的比例、每个完成需求的中位数；插件的"使用统计"页用条形图显示同样的内容。--json、--csv 输出机器可读的格式。
req stats --report --month 2026-10 [--out 目录]：生成给管理方汇报用的两份文件：req-kit-usage-2026-10.md（汇总）和 .csv（每个需求一行，可以用表格软件打开）。
几台机器一起汇报：每台机器运行 req stats --month 2026-10 --export，得到 req-kit-usage-<主机名>-<日期>.jsonl；把这些文件放到一起，运行 req stats --merge <文件…> --month 2026-10 --report。

本机的需求索引 ~/.req-kit/index/ 记录每个运行过的需求在哪个目录，Paseo 插件据此在一个页面列出本机所有项目的需求。1.9 之前运行过的需求不在索引里，在项目目录运行一次 req index --rebuild 补登；目录删掉后用 req index --prune 清理。

外部系统对接（需求管理等）

1.9.0 起，流水线可以把需求同步到团队的需求管理系统：需求开始时建一张卡片，之后每到一个阶段改卡片的状态，卡片编号和链接写回需求，显示在进度、完成报告和 Paseo 插件里。对接的是本机已有的命令行工具（例如需求管理系统的 CLI），写在本机或团队配置中（它会运行命令，项目配置中的会被忽略）：

json

"integrations": [
  {
    "name": "ALM",
    "command": "alm",
    "create": {
      "args": ["card", "create", "--title", "{title}", "--type", "{field.issueType}", "--project", "{field.projectId}", "--priority", "{card.priority}", "--body", "{body}"],
      "id": "(?<id>[A-Z][A-Z0-9-]*#\\d+)",
      "url": "(https?://\\S+)"
    },
    "status": { "args": ["card", "edit", "{id}", "--state", "{status}"] },
    "statusMap": { "started": "开发中", "phase_done": "待测试", "verify": "测试中", "completed": "已完成", "not_completed": "已挂起" },
    "cardFields": { "priority": "优先级：高 / 中 / 低" },
    "defaults": { "issueType": "用户故事" }
  }
],
"integrationDefaults": { "ALM": { "projectId": "<团队的项目编号>" } }

命令：args 是参数数组，引擎不经过 shell 运行，标题或描述里有空格、换行、引号都不会出问题。Windows 上 npm 安装的命令（.cmd）会改用 node 直接运行它的脚本。
占位符：{title}（card.json 的标题，否则需求说明的标题）、{body}（card.json 的描述，否则 spec.md 全文）、{card.<字段>}（card.json 中需求方确认过的字段）、{field.<名称>}（defaults 和项目配置的 integrationDefaults，项目可以只写自己的项目编号）、{id}、{url}、{status}、{feature}、{branch}、{type}、{outcome}。一个参数只是占位符且没有值时，它和前面的选项一起省略。
卡片编号：create.id 是从建卡命令输出中取编号的正则表达式（取名为 id 的组或第一个组），url 同理，可以不写。
状态：statusMap 的键是流水线事件：started（开始开发）、approval（等待确认方案）、blocked（等待需求方决定）、phase_done（研发完成，待测试）、verify（开始测试验证）、completed（完成；可以用 completed_with_issues、not_completed 细分）、failed（中断）。没写的事件不改状态。"只做研发"的需求在研发完成时发的是 phase_done（1.10 起；之前是 completed）。
卡片字段由 AI 整理、需求方确认：写了 cardFields 时，/req 在请需求方确认需求说明时，从需求说明中整理出这些字段的取值一起确认，写进功能目录的 card.json。命令的写法固定在配置里，运行时不让 AI 决定怎么调用。
失败不影响流水线：调用失败或超时（timeoutSeconds，默认 60）记在状态文件里，下一个事件时先按顺序补发；等待中的状态只留最新的一个，不会重复建卡。流水线没在运行时，req sync <需求> 立即补发（插件中也有"同步到外部系统"）。
先试再用：req integration test [需求] 显示每个事件会执行的完整命令（用这个需求的需求说明和 card.json 填好），不真正调用；req integration fields 显示需求方要确认的字段。
认证由工具自己负责（例如工具已登录本机账号）。不要把口令写进配置；工具需要时放在环境变量里。

从卡片开始需求（1.10 起，beta）

需求方在需求管理系统中写好一张卡片，就可以从卡片开始需求，不必有人在 Paseo 对话里发起。对接配置中再写两项：query 读一张卡片，describe 改卡片描述：

json

{
  "name": "ALM",
  "command": "shenbing",
  "query": {
    "args": ["alm-card", "view", "{id}", "--fields", "globalId,name,state,createdBy,subsysName,description"],
    "fields": { "title": "data.name", "body": "data.description", "state": "data.state", "author": "data.createdBy", "subsystem": "data.subsysName" }
  },
  "describe": { "args": ["alm-card", "edit", "{id}", "-b", "{description}"] },
  "status": { "args": ["alm-card", "edit", "{id}", "--state-detail", "{status}"] },
  "statusMap": { "started": "开发中", "phase_done": "待测试" }
}

query.fields 写输出 JSON 中各值的位置（点分路径）；title 和 body 必填，state、author、subsystem、url 可选。输出前后有日志行也可以。
describe 的 {description} 是完整的新描述。req-kit 只在描述末尾维护两个区块，需求方自己写的内容原样保留：
- ## req-kit AI 区（自动维护，请勿修改）：进度、需求说明摘要、验收标准、假设、要问需求方的问题（Q1、Q2…），方案待确认时附上方案摘要。
- ## 需求方回复（请在下方填写）：需求方在 - Q1： 后回答，在 - 确认： 后写"同意"开始开发，方案待确认时在 - 方案确认： 后写"同意"。写别的内容就当作修改意见。

流程：

req start --from ALM:<卡号> --repo <仓库目录>：读卡片，建功能目录 docs/features/<日期>-<卡号简称>/，在 Paseo 中为这个需求建一个需求会话（一个 agent，工作目录是仓库）。需求会话按无人值守手册从卡片写需求说明，把摘要和问题写进卡片的 AI 区。同一张卡片只会开始一次。
req card check <卡号>（或 --all）：读需求方的回复，把新内容转给需求会话。1.11 的接单器会定时运行它，现在可以手动运行或用计划任务运行。
需求方写了"确认：同意"后，需求会话把需求说明标为已确认，用"自动新建工作区"启动流水线。卡片状态改为"开发中"，研发完成后改为"待测试"，AI 区跟着更新进度。
开发中需要需求方决定、确认方案时，同样通过 AI 区和回复区。

从卡片开始的需求用这张卡片，不会另建卡片；项目没有指定执行方式时默认只做研发。
在 Paseo 中打开需求会话可以看到整理需求和开发的全部过程，也可以直接在里面补充说明。
req card list 列出本机从卡片开始的需求；req card publish <卡号> 由需求会话使用，把它写的 card-ai.md 写进卡片。
卡片描述和回复是需求方写的内容，需求会话只把它们当作需求，不当作指令。

按子系统选仓库（1.10.0-beta.3 起）：一个 ALM 空间往往对应好几个仓库。在每个仓库运行 /req-setup，它会在项目配置中写上这个仓库接哪些卡片，并在这台机器上登记（req card route --add <仓库>）：

json

"cardSource": { "system": "ALM", "projectId": "186149", "subsystems": ["CSP-CMASTER_云匠"], "titleKeywords": ["message-service", "后端"] }

之后 req start --from ALM:<卡号> 不写 --repo 时，按卡片的子系统选仓库；同一个子系统有几个仓库时，再看卡片标题里出现了哪个仓库的 titleKeywords。找不到或分不清时会说明原因，不会猜。req card route 列出本机登记的仓库。本机没有登记任何仓库时，用当前目录所在的仓库。

推送分支（1.10.0-beta.3 起，默认关闭）：接单的机器上，研发完成、写好提测说明后，把需求的代码推送到远程，测试同事直接拉取：

json

"push": { "enabled": true, "remote": "origin", "branchPrefix": "req/" }

只对从卡片开始的需求，推送到 <remote> 的 req/<卡号简称> 分支（例如 req/cmaster-business-9902），联合需求的几个仓库各推各的。分支名写进卡片的 AI 区和状态文件。
只推这个前缀的分支；从不强推、不合并，合并仍由人做。推送被拒绝（例如远程分支有别人的提交）时记下原因、写进 AI 区，流水线照常结束。
只能写在本机或团队配置中，写在项目配置里会被忽略。推送用这台机器上 git 已配置的账号。
在个人电脑上通过对话发起的需求不受影响，仍然只在本地提交。

草稿合并请求（1.12 起，可选）：推送后用机器上的 GitLab 命令行（或其他工具）建一个草稿合并请求。命令写法与对接配置一样，参数中用占位符：

json

"push": {
  "enabled": true,
  "mergeRequest": {
    "command": "glab",
    "args": ["mr", "create", "--draft", "--source-branch", "{branch}", "--target-branch", "{target}", "--title", "{title}", "--description", "{description}", "--yes"],
    "check": ["auth", "status"]
  }
}

占位符：{branch} 推送的分支；{target} 目标分支（target 没写时用远程的默认分支，读不到时 main）；{title} 为"[卡号] 需求标题"；{description} 为提测说明加卡片链接，开头注明是草稿、合并前请人工评审；{card}、{cardUrl}。
在需求的仓库中执行；输出中的第一个网址记为合并请求地址，写进卡片 AI 区和状态文件。每个仓库只建一次，测试退回后再推送时合并请求自动更新。
建失败（例如没有登录）只记下原因，分支照常推送。req doctor 用 check 中的参数检查是否已登录。
需要机器上提前登录好（例如 glab auth login），req-kit 不保存令牌。

使用统计：从卡片开始的需求，运行记录带上需求方（卡片的提出人）和卡号。req stats --report 多一节"从卡片开始的需求（按需求方）"，CSV 多 requester、card 两列。

接单器（1.11 起，beta）

接单器在一台共享研发机器上常驻运行，需求方只在卡片上操作：标题以 [AI]（或 【AI】）开头的新卡片会被自动接手，需求方在卡片中的回复会自动转给需求会话。

在对接配置中再写 list（列出卡片的命令），例如：

json

"list": {
  "args": ["alm-card", "list", "--project-id", "{projectId}", "-t", "用户故事", "-S", "新建", "-s", "AI", "-L", "{pageSize}", "-P", "{page}", "--fields", "globalId,name,state,subsysName,createdBy"],
  "fields": { "id": "globalId", "title": "name", "state": "state", "subsystem": "subsysName", "author": "createdBy" }
}

{projectId} 是本机登记的仓库在 cardSource 中写的空间，每个空间查一次；{page}、{pageSize} 用于翻页（pageSize 默认 100，最多 maxPages 页，默认 5）。
输出中卡片列表的位置不在 data.list、data.records、data.items、data.rows 或 data 时，用 items 写明，例如 "items": "data.result"。
只接什么样的卡片（类型、状态）写在参数里；接单器再按标题开头的标识筛一遍，-s 只是让列表短一些。

本机或团队配置中可以调整（都有默认值）：

json

"factory": { "pollMinutes": 5, "titleTags": ["[AI]", "【AI】"], "maxNewPerPoll": 3 }

运行：

命令	做什么
`req factory once`	检查一次：为新卡片开始需求，转达新回复。先用它试配置
`req factory start` / `stop`	在后台运行 / 停止，日志在 `~/.req-kit/factory/factory.log`
`req factory status`	是否在运行、最近一次检查的结果、没能接的卡片和原因
`req factory service`	作为系统服务运行的写法（Linux systemd 用户服务、Windows 计划任务），机器重启后自动恢复

每次最多开始 maxNewPerPoll 个需求，其余下次再接；开发仍受 maxConcurrentPipelines 限制。
接不了的卡片（例如子系统没有对应的仓库）记下原因；卡片的标题和子系统改了会马上再试，否则一天后再试。
Paseo daemon 要同时运行：接单器通过它创建需求会话。
现在只支持一台机器接单。几台机器同时运行接单器会重复接同一张卡片。

自检与告警（1.12 起）：每次检查前先确认 Paseo 连得上、builder 和 reviewer 用的 agent 已登录、额度没有用完（配置了备用模型时，备用的也用完才算），以及需求管理系统的命令能列出卡片。不正常时这次不接新卡片、不转达回复，原因写进 req factory status 和日志，并通过外部通知发一条 alert 事件；同样的问题只发一次，恢复正常时再发一次。

续跑中断的需求（1.12 起）：每次检查时，发现本机有流水线标着"运行中"但后台进程已经不在（机器重启、进程被杀），请它的对话检查并继续，每个进程只提醒一次。

小改动自动确认（1.12 起，默认关闭）：

json

"autoConfirm": { "hours": 4 }

快速档、没有待回答问题的卡片，AI 区写明"到某时前没有异议就开始"；到时需求方没有在回复区写任何内容，接单器按"确认：同意"处理。需求方随时可以写"同意"提前开始，或写修改意见。每次摘要更新都重新计时。

团队配置

几台机器、多个项目共用的设置（统一的模型、评审小组、超时、要求的 req-kit 版本）可以放在一份团队配置里。把它放进一个团队共用的 git 仓库，各台机器克隆下来，在本机配置 ~/.req-kit/config.json 中写上它的路径（绝对路径，或相对 ~/.req-kit/ 的路径）：

json

{ "teamConfig": "D:/Users/me/team-config/req-kit.json" }

合并顺序是本机 → 团队 → 项目 → spec 中的档位 → 启动参数，后面的覆盖前面的。daemonUrl、daemonPasswordEnv、teamConfig 只在本机配置中生效，写在团队或项目配置里会被忽略并提示。

团队配置中可以写 "requiredVersion": ">=1.2.0 <2"。本机的 req-kit 版本不在范围内时，/req-doctor 和流水线日志会提醒升级，但不会阻止运行。

评审小组（可选）

开启后，标准档的方案审核和代码评审在第一轮先由几位评审者（建议使用不同厂商的模型）各自独立评审，再由配置的 reviewer 逐条核实、归类（必须修改 / 建议修改 / 留给人决定 / 已驳回），写出正式结论。被驳回和留给人决定的意见记入 decisions.tsv，最终报告会展示它们。后续轮次只核对修复，用单个评审者。

json

"reviewPanel": {
  "enabled": true,
  "steps": ["design_review", "code_review"],
  "profiles": ["standard"],
  "members": [
    { "name": "安全视角", "provider": "codex/<模型 ID>", "modeId": "full-access", "focus": "重点检查权限、输入校验和数据安全" },
    { "name": "可维护性", "provider": "opencode/anthropic/<模型 ID>", "modeId": "build", "featureValues": { "auto_accept": true } }
  ]
}

成员并行运行，在同一个目录里只读代码、写各自的意见文件（<功能目录>/review-panel/），不提交，不改文件。
某位成员失败时，只汇总完成的成员；全部失败时该步骤失败。
成本：每次启用的评审多出 N 个 agent 的用量，所以默认只用于标准档的第一轮。
成员的模型和模式会在 /req-doctor 中一并检查。

需求总览、决策记录、变更与验收记录

需求总览：node <req-kit>/bin/start-pipeline.mjs --list 列出这个仓库所有 worktree 中的需求和各自的阶段（对齐中、开发中、待验收、已验收等）。总览现场生成，不提交到仓库，避免各分支合并时冲突。
决策记录 decisions.tsv：各步骤把不显而易见的选择（假设、取舍、偏离方案、驳回的评审意见、决定不修的问题）各记一行。会影响结果的标为 needs_human=yes，完成报告把它们列入"需要你确认的决定"。
变更记录 changes.md：每次修改需求（包括方案审核提出问题、验收发现问题）记一节，spec 头部的"版本"随之加 1。
验收记录 acceptance.md：由 /req 的验收手册写，逐条记录验收结果和结论。

格式见 contracts/feature-files.md。

运行规则

步骤和轮数（轮数按档位，在配置的 profiles 中调整；下面是标准档的默认值）：

环节	规则
评审小组（可选）	开启时，标准档的方案审核和代码评审第一轮先由小组成员并行评审，再由评审者核实汇总
方案审核 ⇄ 方案修订	最多 2 轮审核。判定"阻塞"时暂停并请需求方决定；最后一轮仍要求修改时，修订后直接进入实现
代码评审 ⇄ 评审问题修复	最多 3 轮评审，通过即止；轮数用完时修复后进入下一阶段
提测说明	代码评审之后执行，写 `handoff.md`。分阶段执行时研发阶段到此结束
服务启动验证	方案设计判断项目有常驻服务、且档位开启了 `serviceStart` 时才执行（在已部署的测试环境中验证时不执行）
缺陷修复 ⇄ 复验	功能验证发现缺陷时执行，最多 3 轮，复验通过即止（`phases.verify.defects` 为 `handback` 或 `report` 时见上文"执行方式"）
完成报告	只要没有暂停或中断就一定执行，遗留问题写进报告
完成后继续	完成后 spec.md 被修改过（需求变更、验收发现问题），`--resume` 从方案设计开始，各步骤在已有方案和代码的基础上只处理变化的部分；没改过则拒绝。`--restart` 则完全从零开始
增量继续	需求变更、回答了方案审核的问题后继续时：方案在原文末尾追加"第 N 次尝试"一节；实现只改需要改的；代码评审只看本次开始以来的改动；验证重新验证变化涉及的验收标准，其余的至少跑一遍现有测试；报告说明是第几次。做法写在 `engine/prompts/incremental.md`，可以用 `prompts.local/` 替换

结果文件：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。

等待与超时：每步有总时限（stepTimeoutMinutes）。到时 agent 还在做时，先再给它同样长的时间（selfHeal，见下）；仍未完成才判定失败，但不停止 agent。继续（--resume、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮（这一轮不再额外延长）；第二次仍超时才停止它、另起一个 agent。需求改过、开始了新一次尝试时，上一次留下的 agent 直接停掉，不接手（1.12.1）。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟（打开 scanGuard 时每段 1 分钟、打开 dangerGuard 时每段 15 秒，以便查看正在运行的命令；只是读取状态，不占模型 token），连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。

临时错误自动重试：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：

json

"retry": { "attempts": 2, "backoffSeconds": [60, 300] }

attempts 设为 0 关闭；backoffSeconds 的个数少于重试次数时，后面的重试使用最后一个值。超时、结果文件不合格、agent 自己判定失败等不是临时错误，不按这里重试。重试用完仍失败时，中断通知会注明已重试的次数。

自愈（1.12，selfHeal，默认 true）：能安全自动处理的中断不再等人。

情况	自动处理
步骤超时，agent 还在做	不打断它，再等同样长的时间；仍未完成才中断
agent 报错（不是临时错误）	新开一个 agent 重做这一步一次；配置了备用模型时用备用模型
提醒后仍没有有效的结果文件	新开一个 agent 重做这一步一次
限流、额度用完，重试用完	配置了备用模型时，用备用模型再做一次；仍不行就中断，并按 Paseo 显示的额度恢复时间预约自动继续（恢复后 5 分钟；没有恢复时间时按 `autoResumeMinutes`）
方案审核说需要需求方决定	先请 builder 从代码、文档和需求说明中找答案（`answerQuestionsFirst`，默认 `true`），只把真正的业务取舍连同推荐答案交给需求方；都能回答时不停下。最后一轮审核的问题被自答时，再加一轮审核复核这些答案（1.12.1）

备用模型（1.12，可选）：agents.fallback，写法同 builder、reviewer，可以用 paseoProfile。req configure 和插件的"模型"设置页会推荐一个与主模型不同厂商的模型。

json

"agents": { "builder": { … }, "reviewer": { … }, "fallback": { "provider": "opencode/<模型 ID>" } }

自动处理的每一次都记在进度日志、状态文件的 recoveries 和使用记录中，req stats 的"人工介入"一节汇总：停下等人的原因、自动处理了多少次、到达提测的需求中没有非必要介入的比例。

打断大目录搜索（1.13，scanGuard，默认开）：步骤 agent 有时为了找一个类或一个包，去搜索整个磁盘、用户目录、Maven 本地仓库（~/.m2）、Gradle 缓存、全局 node_modules 或整个 node_modules，一次就是几十分钟，这一步迟迟做不完。步骤运行时，流水线大约每分钟看一次 agent 正在运行的命令：搜索这类大目录的命令运行超过 1 分钟、或者任何搜索命令运行超过 minutes 分钟，就打断它，并告诉 agent 改用什么办法（在仓库里用 git grep；按 pom.xml 里的坐标直接打开那一个依赖目录、用 unzip -l 看那一个 jar；mvn dependency:tree；找不到就写进"假设"继续）。构建和测试命令（mvn、gradle、npm test 等）不打断；只搜具体的子目录（如 ~/.m2/repository/com/acme/foo）或排除了 node_modules 的搜索也不算。同一个命令只打断一次，每轮最多打断 5 次；每次都记在进度日志和 recoveries（stop_scan）中。各步骤的提示词里也写明了只在仓库里搜索。

json

"scanGuard": { "enabled": true, "minutes": 5, "paths": ["D:/share"] }

paths：另外不允许整个搜索的目录（例如共享盘）；enabled: false 关闭。

拦截危险命令（1.14，dangerGuard，默认开）：步骤 agent 通常以免确认模式运行命令，"只做本地提交、不碰生产"以前只写在提示词里。现在步骤运行时，流水线每 15 秒看一次 agent 运行过和正在运行的命令（读 Paseo 的记录，不用模型）。下面这些会被处理：推送（git push，强推、删除远程分支单独标出）、改远程地址；发布制品（npm publish、mvn deploy、gradle publish、docker push 等）；改动集群和基础设施（kubectl apply/delete/exec…、helm install/upgrade…、terraform apply/destroy、ansible-playbook）；连接其他机器上的数据库（mysql -h <带点的主机名或地址> 等，localhost 和 docker compose 里的服务名如 db 不算）；登录或复制到其他机器（ssh、scp、rsync，git@ 不算）；删除仓库以外的目录（rm -rf ~、/、..、仓库外的绝对路径，临时目录除外）；下载脚本直接执行（curl … | sh）；关机、格式化等系统级操作；以及命令里出现 production 中任何一项（生产环境的主机名、地址、库名）。还在运行的命令立即打断，告诉 agent 不要再做、把需要人做的写进产物；已经运行完的也会告诉它。每次都通知需求的对话（和外部通知的 alert 事件，details.kind 为 danger），记在状态文件的 dangers 里，并写进完成报告。这是按命令文字的检查，能拦住常见的情况，不是沙箱。

json

"dangerGuard": { "enabled": true, "production": ["prod.example.com", "10.8.0."], "allow": ["^ssh test-box"] }

production：生产环境的标记（出现在命令或访问的地址里就拦），建议团队配置里写上；allow：放行的命令（正则表达式），例如测试机的登录；enabled: false 关闭。

密钥扫描（1.14，secretScan，默认开）：每个改代码的步骤之后（和质量门一起），流水线检查本需求新增的内容：从这次尝试开始时的提交以来，每次提交加进来的行、还没提交的改动和新文件。常见格式的密钥（私钥、AWS、GitHub、GitLab、Slack、模型服务的 API 密钥、JWT、地址里带的口令）在任何文件里都算；password = "…"、token: … 这样的赋值只在代码和配置里算，测试和文档不算，值是占位符（${…}、<your-token>、changeme）或从环境变量读取的也不算。发现了就交回这一步的 agent：改成从配置或环境变量读取；已经写进本需求提交的，用 git commit --fixup 和非交互的 git rebase --autosquash 从这些还没推送的提交里去掉；确实不是密钥的，在那一行加注释 req-kit:allow-secret。最多要求 qualityGate.fixAttempts 次，仍有的通知需求的对话、写进代码评审和完成报告；配置了 push 的需求不会推送有疑似密钥的分支。

json

"secretScan": { "enabled": true, "allow": ["test/fixtures/**"] }

allow：不扫描的文件（路径或通配符）；enabled: false 关闭。

同一个目录一次只运行一条流水线，因为各步骤都在这个目录中修改和提交。需要并行时，为每个需求使用单独的 worktree 工作区。

注意事项

发起流水线的聊天 agent 需要能访问本机网络。 流水线进程继承它的运行环境，需要连接 ws://127.0.0.1:6767。用 Codex 做聊天 agent 时，请使用 full-access 模式；沙箱模式可能禁止网络。
必须在仓库对应的项目对话中发起，对话过程中不要切换工作目录。 步骤 agent 一律作为子 agent 挂在发起的对话下，而 Paseo 会让子 agent 使用父 agent 的工作目录，所以仓库目录必须就是这个对话的工作目录。在对话中启动时，--repo 默认就取对话的工作目录；两者不一致、或发起的对话已不存在时，流水线拒绝启动并说明原因。
步骤 agent 以免确认模式运行，在本机拥有执行命令的权限。提示词禁止了危险操作，但这不是安全边界。请让仓库目录中不包含生产环境凭据。
聊天被归档时，挂在它下面的步骤 agent 也会被归档；通知会发送失败，但流水线会继续运行到结束，结果仍可在 report.md 和日志中查看。
daemon 重启会中断正在运行的步骤 agent。流水线会在连续 5 次无法获取状态后判定该步骤失败，之后可以用 --resume 继续。

本页由仓库中的 docs/guide/项目定制与运行规则.md 生成。在 GitHub 上编辑

项目定制与运行规则 ​

每个需求一个 worktree 工作区 ​

档位 ​

需求类型 ​

方案确认点：开工前请需求方确认"做完后会看到什么" ​

代码评审分两个方向 ​

验收测试先提交 ​

术语表和范例文件 ​

反复出现的问题变成规则 ​

质量门：流水线自己运行的检查 ​

按切片实现 ​

范围检查 ​

关联仓库（只读参考） ​

联合需求：一个需求，几个仓库 ​

执行方式：连续、分阶段、只做研发 ​

进展通知 ​

运行时文件 ​

按项目定制 ​

paseo.json：环境准备和由 Paseo 管理的服务（推荐） ​

额度提醒 ​

token 预算和用时估算（1.13 起） ​

并行编排：确认前审阅、方案提案、浏览器验证 ​

自动新建工作区（可选） ​

调度：预约、提醒、自动继续、排队 ​

需求总览 ​

使用统计 ​

外部系统对接（需求管理等） ​

从卡片开始需求（1.10 起，beta） ​

接单器（1.11 起，beta） ​

团队配置 ​

评审小组（可选） ​

需求总览、决策记录、变更与验收记录 ​

运行规则 ​

注意事项 ​

项目定制与运行规则

每个需求一个 worktree 工作区

档位

需求类型

方案确认点：开工前请需求方确认"做完后会看到什么"

代码评审分两个方向

验收测试先提交

术语表和范例文件

反复出现的问题变成规则

质量门：流水线自己运行的检查

按切片实现

范围检查

关联仓库（只读参考）

联合需求：一个需求，几个仓库

执行方式：连续、分阶段、只做研发

进展通知

运行时文件

按项目定制

paseo.json：环境准备和由 Paseo 管理的服务（推荐）

额度提醒

token 预算和用时估算（1.13 起）

并行编排：确认前审阅、方案提案、浏览器验证

自动新建工作区（可选）

调度：预约、提醒、自动继续、排队

需求总览

使用统计

外部系统对接（需求管理等）

从卡片开始需求（1.10 起，beta）

接单器（1.11 起，beta）

团队配置

评审小组（可选）

需求总览、决策记录、变更与验收记录

运行规则

注意事项