req-kit

外观

更新记录 ​

每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 docs/guide/安装与升级.md。

1.15.0 ​

稳定版：审查网页、Paseo 插件和文档站按同一套设计规范重做，要你决定的事用青柠色标出来，AI 写的和人写的一眼分开；每个正式版自动生成海报和汇报幻灯片。内容包括 1.15.0-beta.1 至 beta.4（详见下面各条）。

使用者会看到的变化 ​

  • 三个审查网页换上新设计：审查原型、验收清单、代码审查用同一个骨架：顶栏写清需求名和功能目录，底部决定栏放这一页要你做的决定，每页只有一个青柠色主按钮，条件不满足时写明还差什么。代码审查页把 AI 评审意见和你写的意见分开显示；验收清单页把"先看这些"和"流水线已验证"分开；原型上你点选的地方是青柠图钉。
  • Paseo 插件换上新设计：底色和文字跟随 Paseo 的主题；需求列表每行有状态图标和"项目 · 功能目录"，"等你处理"用图标块标出要做的事，需求页顶部的放行轨显示走到了哪一步。
  • 文档站和首页换上新设计：首页有安装命令（三种系统，一键复制）、需求怎么走的步骤轨和能力介绍；正文页的侧边栏、提示框和代码块按新规范显示，默认跟随系统深浅色。req docs 打开的本机文档站一样。
  • 每个正式版自动生成海报和幻灯片：竖版海报、群聊卡片和汇报幻灯片附在 GitHub Release 上，内容取自这一版的更新记录，数字都是当次核实过的。
  • 网页不再加载外网字体：内网打开审查页和文档站不会等字体超时。
  • 修复：代码审查页底部的决定栏没有对齐。 标签放到输入框左边，摘要、输入框和按钮在同一行。

升级须知 ​

  • 页面、插件的接口和行为没有变化，只换了外观；升级后照常运行 req plugin install 更新 Paseo 里的插件（req upgrade 会自动做）。
  • 设计规范在仓库的 design/ 目录（和 CMASTER 同属一个设计家族，主色青柠绿）；审查网页、插件和文档站用的颜色和图标由 scripts/tokens-build.mjs 从这里生成，测试会检查它们一致、没有写死的颜色。
  • 维护者：正式版的海报口号写在 design/releases/<版本>.json，详见维护者指南"正式版的海报和幻灯片"。

1.15.0-beta.4 ​

使用者会看到的变化 ​

  • 修复：代码审查页底部的决定栏没有对齐。 "审核人""评审人"的标签放到输入框左边，摘要、输入框和按钮在同一行垂直居中；验收清单页的"验收人"同样处理。
  • 每个正式版自动生成一张海报、一张群聊卡片和一套汇报幻灯片，附在 GitHub Release 上（req-kit-<版本>-poster.png、-card.png、-slides.pdf，以及可以再改的 -slides.html）。内容取自更新记录的这一版：导语、每项变化、升级须知，加上这次发布跑过的测试数、版本数和设计决定记录数。

升级须知 ​

  • 维护者：正式版的口号可以写在 design/releases/<版本>.json，没有就用版本号；本机预览运行 node scripts/release-media.mjs <版本> --render。详见维护者指南"正式版的海报和幻灯片"。beta 发布时也会生成一遍用来检查，但不附在 Release 上。

1.15.0-beta.3 ​

使用者会看到的变化 ​

  • 文档站和首页换上了 req-kit 的新设计（req docs 打开的本机文档站、GitHub Pages 和内网托管的副本都一样）：
    • 首页：极光背景上的版本胶囊、标题和安装命令（npx / macOS·Linux / Windows 三个标签，一键复制）；下面是"对齐 → 方案 → 实现 → 评审 → 验证 → 验收"的步骤轨（要你拍板的两步是青柠色），Bento 卡片介绍对齐需求、审查原型、质量门、代码审查、验收清单和危险命令拦截，数字条里的版本数和设计决定记录数从仓库读取。
    • 正文页：底色、文字、链接、按钮换成设计系统的颜色；侧边栏分组标题用等宽小字，当前页青柠底色；提示、注意、危险、说明四种提示框带图标、不用彩色左边框；代码块圆角带边框。
    • 默认跟随系统深浅色，右上角可切换；标志和网页图标换成 req-kit 的新标志。

升级须知 ​

  • 文档站的颜色由 scripts/tokens-build.mjs 生成到 site/.vitepress/theme/（rk-tokens.css、rk.css、rk-icons.ts），标志复制到 site/public/；测试会检查它们和 design/ 一致、主题样式里没有写死的颜色。
  • 非 main 分支和合并请求构建的文档站会作为 site-dist 保留 7 天，方便预览。

1.15.0-beta.2 ​

使用者会看到的变化 ​

  • Paseo 插件换上了 req-kit 的新设计：底色、文字、边框仍跟随 Paseo 的主题，req-kit 的样子靠青柠色的"要你做"、靛色的"AI 写的"、青色的"正在跑"带出来。
    • 首页和统计页顶部有 req-kit 标志；需求分组用等宽小标题（NEEDS YOU / IN PROGRESS / READY TO TEST / DONE）。
    • 需求列表每行前面有图标表示状态，下面一行等宽字体写"项目 · 功能目录"，右边是状态徽章和更新时间。
    • "等你处理"的卡片用图标块代替彩色左边框；需求页顶部有放行轨，一眼看出走到了哪一步；每页只有一个青柠色主按钮（审查方案、代码审查、验收或第一个动作）。
    • 按钮、徽章带图标；统计页的柱子用数据色。

升级须知 ​

  • 插件的颜色由 scripts/tokens-build.mjs 生成到 paseo-plugin/shared/rk-colors.ts，测试会检查插件代码里没有写死的颜色。
  • 插件随 npm 包发布；升级后照常运行 req plugin install 更新到 Paseo 里。
  • 文档站的新设计在下一个 beta 里做。

1.15.0-beta.1 ​

使用者会看到的变化 ​

  • 审查原型、验收清单、代码审查三个网页换上了 req-kit 的新设计（设计规范见仓库 design/，和编排平台 CMASTER 同属一个设计家族，主色青柠绿）：
    • 统一的顶栏（标志、需求名、功能目录、自动保存时间、只读标记、深浅色切换），底部固定的"决定栏"放这一页要你做的决定，每页只有一个青柠色主按钮；条件不满足时按钮旁边写明还差什么。
    • 代码审查页：AI 评审意见（靛色卡片，带编号、轮次、级别和处理结果）和你写的意见（青柠描边卡片）分开显示；侧栏按"概要 / 代码 / 需求文档"分组；改动摘要卡片显示 AI 评审几轮、修复了几条、还开着几条。
    • 验收清单页：前置条件、操作、预期结果排成表格；侧栏把"先看这些"（流水线没验证、没通过、要你表态的）和"流水线已验证"分开；试用放在一张卡片里。
    • 审查原型页：原型放在点阵画布上；"要看的地方"用靛色虚线框和编号标出，你点选的地方是青柠图钉；有意见时主按钮是"提交修改意见"，没有意见时主按钮是"确认方案，开始写代码"。
    • 默认跟随系统的深浅色，右上角可以切换并记住；手机宽度下侧栏变成可横向滑动的一行，决定栏的按钮占满一行。
  • 页面不加载外网字体，内网打开不会等字体超时。

升级须知 ​

  • 页面的接口和行为没有变化，只换了外观。审查服务多提供三个共用文件（rk-tokens.css、rk.css、rk-icons.js），由 scripts/tokens-build.mjs 从 design/ 生成，测试会检查它们和 design/ 一致。
  • Paseo 插件和文档站的新设计在后面的 beta 里做。

1.14.0 ​

稳定版：需求从对齐开始就在插件里，新建工作区能接着做，插件里能做代码审查和验收，危险命令和密钥有程序把关，评审、验收、合并之后的结果有记录可查。内容包括 1.14.0-beta.1 至 beta.5（详见下面各条）。

使用者会看到的变化 ​

  • 修复：自动新建工作区后只有需求说明、没有代码。 工作区一建好就记下来，再次启动在同一个工作区里接着做；最多等 15 分钟。术语表和设计决定随需求说明一起带过去；需求说明不会再被提交到主分支。
  • 需求从开始谈就出现在插件里（"对齐中"）；确认了却没开始开发的进"等你处理"，点"开始开发"即可，谈需求的对话里也会提醒一次。已经开发完的需求不会误显示为"未开始"；同一个需求在两处只列一次。
  • 代码审查（插件需求页面上的"代码审查"，req code-review）：改动按文件列出，AI 评审意见放在对应的行旁边；评审人在任意一行写意见、标"要改 / 不用改"；审核人默认取自 CODEOWNERS，提交前可改。退回修改后流水线自动按意见修改，评审通过后有新提交会提示重新评审。
  • 验收清单和一键试用（"验收清单（可一键试用）"，req checklist、req try）：按验收标准逐条勾选，提交后写成 acceptance.md 并提交；不通过的转给需求的对话处理。
  • 拦截危险命令（dangerGuard）：步骤 agent 推送、发布制品、改动集群、连接其他机器上的数据库或主机、删除仓库以外的目录、下载脚本直接执行，或命令里出现配置的生产环境地址时，打断并通知。
  • 密钥扫描（secretScan）：每个改代码的步骤之后扫描本需求新增的内容，交回 agent 去掉；有疑似密钥的分支不推送。
  • 记录可查：代码审查和验收的全文随需求分支提交；结论另记入使用记录。req stats 和插件统计新增"人工把关和合并后"：评审退回次数、验收通过率、合并进主干的需求、合并后发现的问题（req outcome）。

升级须知 ​

  • 新配置都可选：dangerGuard（默认开，建议团队配置里把生产环境的主机名、地址写进 production）、secretScan（默认开）。打开 dangerGuard 时流水线每 15 秒读一次步骤 agent 的命令记录，不占模型 token。
  • 合并请求还没有接入，等 shenbing 提供类似 gh pr create / gh pr merge 的命令。
  • 状态文件、使用记录、req api 和外部通知的新增字段见各 beta 的升级须知；新命令 req code-review、req review-fix、req checklist、req try、req outcome。
  • 更新后请在 Paseo 中重新加载插件（req upgrade 会自动做）。

1.14.0-beta.5 ​

使用者会看到的变化 ​

  • 拦截危险命令（dangerGuard，默认开）：步骤 agent 推送代码、发布制品、改动集群或基础设施、连接其他机器上的数据库或主机、删除仓库以外的目录、下载脚本直接执行，或者命令里出现配置的生产环境地址时，流水线打断它（还在运行时）、告诉它把需要人做的写进产物，并通知需求的对话；每次都记下来，写进完成报告。按命令文字检查，不用模型；能拦住常见的情况，不是沙箱。
  • 密钥扫描（secretScan，默认开）：每个改代码的步骤之后，检查本需求新增的内容（每次提交加的行、未提交的改动、新文件）有没有密钥、令牌、口令；发现了交回这一步的 agent 去掉（包括从还没推送的提交里去掉），仍去不掉的通知需求的对话、写进代码评审和完成报告；配置了推送的需求不会推送有疑似密钥的分支。
  • 记录合并之后的结果：req stats 和插件的使用统计新增"人工把关和合并后"：人工代码评审几次、退回几次，验收几次、不通过几次，第一次就通过的需求数，合并进主干的需求和"完成到合并"的时间，合并后发现的问题。合并是从本机仓库已有的分支判断的（需求的流水线文件进了主干）；缺陷需求写了 - 引入问题的需求：<目录名> 的，算作那个需求合并后的问题；也可以 req outcome <需求> --issue "<问题>" 手动记一笔。
  • 代码审查和验收的结论进使用记录：每次在代码审查页、验收页提交，结论、评审人和意见条数记入本机使用记录（全文仍在随分支提交的 code-review.md、acceptance.md 里）；req stats --export 一起导出。
  • 确认了却没开始开发的需求，在谈需求的对话里提醒一次（插件的后台检查，确认 30 分钟后；只提醒 3 天内确认的）。
  • 修复：同一个需求在主目录和它自己的工作区里各有一份时，插件列出两次。 现在只列一次，优先列在运行的、有运行状态的那一份。

升级须知 ​

  • 新配置都可选：dangerGuard（默认 { "enabled": true, "production": [], "allow": [] }，建议团队配置里把生产环境的主机名、地址写进 production）、secretScan（默认 { "enabled": true, "allow": [] }）。打开 dangerGuard 时流水线每 15 秒读一次步骤 agent 的命令记录，不占模型 token。
  • 使用记录 usage/runs.jsonl 新增 review、acceptance、merge、issue 几种记录（见 contracts/usage-record.md），旧版本读取时会跳过；req stats --json / req api stats 新增 oversight，每个需求新增 afterRun，CSV 新增 7 列。状态文件新增 dangers、secretScans；外部通知 alert 事件新增 details.kind: "danger"。
  • 新命令 req outcome；req reply 新增 --notice（后台检查用）。
  • 提示词里"不改写历史"加了一个例外：流水线要求从本需求还没推送的提交里去掉密钥时。

1.14.0-beta.4 ​

使用者会看到的变化 ​

  • 代码审查（插件需求页面上的"代码审查"，req code-review <需求>）：列出需求分支相对起点的全部改动（需求文档放最后、折叠），AI 代码评审的意见放在对应的代码行旁边，带级别和修复步骤的处理结果；评审人可以在任意一行写意见、把 AI 意见标为"要改 / 不用改"、写总体意见。
  • 审核人默认取自 CODEOWNERS（支持 GitLab / GitHub 格式和 GitLab 的分节），按改动的文件给出，提交前可以修改，以后建合并请求时使用。
  • 退回修改：意见写进 code-review.md 的"人工评审"一节（HR-1 起）和 changes.md 并提交，流水线开始新的一次尝试（req review-fix），需求说明不变、方案确认不用重来，从方案设计开始只处理这些意见，之后照常经过 AI 代码评审和验证。评审通过：记下评审人、审核人和评审的提交；之后又有新提交时提示需要重新评审。
  • AI 代码评审的结果文件新增 findings（每条意见的级别、文件、行号、问题、修复方向）；没有它的旧需求从 code-review.md 的 CR 条目中读取。

升级须知 ​

  • 合并请求还没有接入：等 shenbing 提供类似 gh pr create / gh pr merge 的命令后，用评审通过时记下的审核人建合并请求。
  • req api status 新增 humanReview；req api review-url 的 --page 新增 code；启动参数新增 --review-fix（req review-fix <需求>）。

1.14.0-beta.3 ​

使用者会看到的变化 ​

  • 验收清单（req checklist <需求>，插件需求页面上的"验收清单（可一键试用）"）：按需求说明的验收标准生成清单，每条写着前置条件、操作、预期结果和流水线的验证结果，没验证或没通过的排在前面，报告里"需要你确认的决定"也列上。逐条点"通过 / 不对 / 先不验"，进度自动保存；提交后写成 acceptance.md 并提交，不通过时把不对的地方转给需求的对话。
  • 一键试用（req try <需求>，验收清单页右上角"把它跑起来试用"）：用项目的 Paseo 服务脚本在需求自己的工作区里启动，给出访问地址和提测说明里的测试账号、数据；--stop 或"停止试用"停掉。没有服务脚本的项目给出提测说明里的启动方法。

升级须知 ​

  • req api review-url 新增 --page check；req reply 新增 --acceptance（验收页用）。验收页和原型审查页是同一个本机服务。

1.14.0-beta.2 ​

使用者会看到的变化 ​

  • 修复：已经开发完（待验收、已验收）的需求在插件里显示"已确认，未开始开发"和"开始开发"按钮。 需求分支合并到主分支后，主分支里的需求文件夹没有运行状态（运行状态不提交），beta.1 把它当成了没开始。现在看到方案、完成报告等只有流水线才会写的文件，就按已开发处理：有完成报告的显示"待验收"（或验收记录里的结论），不会进"等你处理"。

1.14.0-beta.1 ​

使用者会看到的变化 ​

  • 修复：自动新建工作区后只有需求说明、没有代码。 以前新建工作区只等 2 分钟，超时（大仓库在 Windows 上常见）或建好后启动前的检查没通过，启动命令就退出了，留下一个只有需求说明提交的分支；再启动又报"分支已存在"。现在工作区一建好就记下来，再次启动会在这个工作区里接着开始；最多等 15 分钟。以前版本留下的这种工作区，也会由 Paseo 接手接着做。
  • 访谈改过的术语表（GLOSSARY.md）和设计决定（docs/adr/）随需求说明一起带到新工作区，在需求自己的分支上提交。
  • 修复：需求说明可能被提交到主分支。 写需求说明的说明和"新需求"手册对是否提交说法不一致，现在统一为：要自动新建工作区的，确认后不提交，由流水线在新工作区里提交。需求说明已经提交在主分支上、本地主分支比远端落后、主目录还有别的未提交改动时，启动结果里会写明。
  • 需求从开始谈就出现在插件里（"对齐中"）：建好功能目录后 /req 会登记它（start-pipeline --feature <功能目录> --track）；没登记的，插件也会在本机用过的项目里找到。
  • 确认了却没开始开发的需求进"等你处理"：需求说明确认超过 30 分钟还没开始，或者上次启动没成功，插件里显示"还没开始开发"，点"开始开发"即可：在项目主目录中会新建（或接着用）需求自己的工作区，进展发回谈需求的那个对话。

升级须知 ​

  • req api list --all 也会列出对齐中的需求（没有运行状态）；attention 新增 not_started，waiting 新增 canStart；req api run 新增 start；需求索引新增可选的 chatAgentId；新增 ~/.req-kit/worktrees/ 记录。
  • 更新后请在 Paseo 中重新加载插件（req upgrade 会自动做）。

1.13.0 ​

稳定版：内网能装能用、在 Paseo 网页端审查原型、不靠看图检查界面、看得见 token 花在哪。内容包括 1.13.0-beta.1 至 beta.5（详见下面各条）和下面新增的三项，设计决定见 ADR 0032、0033。

使用者会看到的变化 ​

  • 内网安装和文档：npx -y [--registry=<镜像地址>] paseo-req-kit@latest install 一条命令装好，只需要 npm 源；req docs 在本机打开文档站点。
  • 在 Paseo 里审查原型：需求页面和"等你处理"里的主按钮"审查原型并确认方案"，在原型上点要改的地方、选改法、用自己的话补一句，提交后整理成清单交给需求会话。
  • 界面检查 req ui-check：用本机的 Edge 或 Chrome，用文字报告显示不全、遮挡、超出屏幕、文字太淡、没名字的控件、报错，并和确认过的原型对文字；功能验证自动使用，不需要模型看图。
  • token：req stats 和插件的"token 花在哪"；可选的每个需求预算（budget）；开始时和 req status 里的"预计还要多久"。
  • 后台进程意外退出时由插件直接继续，不再每小时叫醒对话；等待批准的权限进"等你处理"。
  • 新增：打断大目录搜索（scanGuard，默认开）：步骤 agent 搜索整个磁盘、用户目录、Maven 本地仓库（~/.m2）、Gradle 缓存、全局或整个 node_modules 时，流水线一分钟后打断这个命令，并告诉 agent 改用什么办法（git grep、按坐标直接打开那一个依赖、mvn dependency:tree）；任何搜索运行超过 5 分钟也打断。构建和测试命令不受影响。各步骤的提示词也写明了只在仓库里搜索。
  • 新增：预算不起作用时会说：agent 不报告 token 用量时，设了预算的需求在第一步之后提醒一次"预算不会起作用"，req doctor 也会检查。
  • 新增：从别的电脑打开审查页时说明原因：审查页默认只在运行 Paseo 的电脑上能打开；从别的电脑打开 Paseo 网页、点"审查原型"时，页面写明为什么看不到、怎么设置。只设 REQ_KIT_REVIEW_HOST 时，审查页地址用这台电脑的计算机名。

升级须知 ​

  • 新配置都可选：budget（默认不限）、scanGuard（默认开：{ "enabled": true, "minutes": 5, "paths": [] }，关闭写 "enabled": false）。
  • 打开 scanGuard 时，流水线每分钟查看一次步骤 agent 的状态（以前每 10 分钟），只是读取状态，不占模型 token。
  • 原型按新约定写（data-ac、data-label、<section data-state>、不写脚本），旧原型照常能看，只是审查页认不出区域和状态。
  • 1.12 时预约的"对话定时检查"会留到过期（最多 3 天），装了插件后新需求不再预约，不用手动删。
  • 装过插件的，req upgrade 会一并更新插件。新的安装脚本只能安装 1.13 及以后的版本。
  • 状态文件、使用记录和 req api 的新增字段见各 beta 的升级须知；recoveries 新增 stop_scan。
  • 发布前 Linux 和 Windows 的测试都必须通过。

1.13.0-beta.5 ​

使用者会看到的变化 ​

  • Windows：配置成 .js / .mjs 脚本的外部命令能运行了：对接外部系统（integrations）、合并请求（push.mergeRequest）等配置的命令是一个 JavaScript 文件时，以前在 Windows 上启动不了（Windows 不认文件开头的 #!/usr/bin/env node），现在用 Node.js 运行它，其他系统也不再需要给脚本加执行权限。

维护 ​

  • 测试改为可以在 Windows 上运行（用 Node.js 直接启动 tsx；只能在 sh 下运行的几项在 Windows 上跳过），CI 的 Windows 任务把失败的测试和报错写在运行结果页上。

1.13.0-beta.4 ​

使用者会看到的变化 ​

  • token 花在哪：req stats 和插件的"使用统计"页新增一节，按步骤、按模型列出 token（输入 + 输出）和占比，单独算出返工（方案修订、评审问题修复、缺陷修复、复验，以及第 2 轮起的审核和评审）占了多少、输入中多少来自提示缓存、每个完成需求的中位数。每一步用的模型从这个版本开始记录。
  • token 预算（可选，budget.tokens）：用到 budget.warnPercent（默认 80%）时在对话里告知一次；用完时已完成的步骤保留，在下一步开始前停下，问需求方是否继续，继续会再给一份预算。
  • 还要多久：本机已完成 3 个以上同档位需求后，开始开发时给出这类需求通常的 agent 用时和 token；req status 和插件的需求页面显示"预计还要约多久"。
  • 后台进程意外退出时直接继续，不再叫醒对话：装了插件时，插件每 5 分钟在 daemon 里检查一次，发现"运行中但后台进程已不在"的需求就直接继续（req resume），不经过模型；这时流水线不再预约对话每小时一次的定时检查，省下这部分 token。接单器也改为直接继续。
  • 等待批准权限进"等你处理"：步骤 agent 在等你允许一项操作时，插件的"等你处理"列出要批准的操作，点"打开这个 agent"去处理。

升级须知 ​

  • 新配置 budget（默认不限）。用 req stats 看过"每个完成需求的中位数"后，可以按它的两三倍设置。
  • 停下原因新增 budget；状态文件新增 budget、waitingPermission；使用记录的步骤新增 cachedInputTokens、agent；req api 新增 watchdog，status 新增 estimate，attention 新增 permission。
  • 插件设为只读时不做自动继续。
  • CI 新增 Windows 任务（暂时只报告结果，不阻断发布）。

1.13.0-beta.3 ​

使用者会看到的变化 ​

  • 原型审查页在 Paseo 里打开：网页端和桌面端不再跳到单独的浏览器窗口，审查页嵌在插件的"审查原型"页面中；手机上仍在浏览器中打开，页面右上角也可以"在新窗口打开"。
  • 按钮更醒目："等你处理"和需求页面最上面，有原型的方案确认显示为主按钮"审查原型并确认方案"（"确认方案"变为次要按钮）；没在等确认时也有"审查原型"按钮。请你确认方案的对话消息也会告诉你去点这个按钮。

升级须知 ​

  • 审查页现在允许被本机地址上的页面嵌入（frame-ancestors）；从别的电脑访问时（设了 REQ_KIT_REVIEW_HOST）允许任何页面嵌入，地址中的令牌仍是访问的唯一凭证。可以用 REQ_KIT_REVIEW_FRAME_ANCESTORS 指定。

1.13.0-beta.2 ​

在 Paseo 网页端审查原型，界面验证不再依赖桌面端和模型的视觉能力。见 ADR 0033。

使用者会看到的变化 ​

  • 原型审查页：界面改动的需求请你确认方案时，在插件的需求页面或"等你处理"里点"打开原型审查页"（终端：req review <需求>）。在原型上点要改的地方，选一种改法（文字改成…、大一点、换颜色、换位置、删掉、这里加东西……），用自己的话补一句；双击文字直接改字；切换正常、出错、空数据等状态和电脑、手机宽度。被点元素的文字、颜色、大小、位置和对应的验收标准自动记下，提交后整理成清单转给需求会话；没有要改的，直接同意开始写代码。意见自动保存；原型改过后再打开，会标出这一版改了哪里。
  • 界面检查 req ui-check：用本机的 Edge 或 Chrome 打开页面，按电脑和手机宽度用文字报告文字显示不全、互相遮挡、超出屏幕、图片没加载、文字太淡、控件没有名字、控制台报错、请求失败，并和确认过的原型逐项对标题、按钮、字段名、表头。功能验证、缺陷修复和复验自动使用；不需要 Paseo 桌面端，不需要模型看图。截图只存成文件给人看，不再读进对话，省 token。
  • 安装时 Paseo daemon 启动得慢不再判为失败；真的没启动时写出 Paseo 报的原因和日志位置。

升级须知 ​

  • 方案设计的原型按新约定写：改动区域标 data-ac、data-label，状态包在 <section data-state="…"> 中，原型里不写脚本（审查页不会运行它们）。
  • req ui-check 第一次运行时从 npm 源安装 playwright-core 到 ~/.req-kit/tools（不下载浏览器）；本机要有 Edge 或 Chrome，或者用 --browser / REQ_KIT_BROWSER 指定浏览器程序。
  • 原型审查页的服务默认只给本机访问。需求方从别的电脑访问 Paseo 网页端时，见《项目定制与运行规则》"方案确认点"一节的 REQ_KIT_REVIEW_* 环境变量。
  • browserVerify: "off" 现在同时关闭界面检查。

1.13.0-beta.1 ​

公司内网只有 npm 镜像、打不开 GitHub 和文档站点时，也能一条命令装好、升级和看文档。见 ADR 0032。

使用者会看到的变化 ​

  • npx 一条命令安装：npx -y paseo-req-kit@latest install，任何系统都可以，只需要 Node.js 22+ 和能访问的 npm 源。做的事和以前的一键安装完全一样：检查环境、安装、检查和安装 Paseo、启用、自动选好 agent、询问是否装插件。已安装时也可以运行 req install。
  • 公司内网：npx -y --registry=<镜像地址> paseo-req-kit@latest install。镜像地址会保存为本机的 npm 源（屏幕上写出原来的值），以后 req upgrade 和安装 Paseo 命令行也走镜像；只想用一次加 --no-save-registry。镜像还没同步这个版本时直接说明，不再去访问 GitHub。
  • req docs：在本机打开和所装版本一致的文档站点，不需要外网（发布时构建进 npm 包）。
  • 安装脚本：install.sh / install.ps1 用法不变，新增 --registry / $ReqKitRegistry 和 --no-save-registry / $ReqKitNoSaveRegistry。文档站点首页增加 npx 的写法；站点放在别的地址（例如内网）时，首页的安装命令自动换成那个地址。

升级须知 ​

  • 安装脚本现在只负责选版本，其余步骤由所选版本自带的 req install 完成，所以新脚本只能安装 1.13 及以后的版本。要装更早的版本：npm i -g paseo-req-kit@<版本> && req setup。
  • npm 包增加了 site-dist/（构建好的文档站点，约几 MB）和命令 paseo-req-kit（与 req 相同）。

1.12.1 ​

修正 1.12.0 审查中发现的问题，不改变用法。

使用者会看到的变化 ​

  • 需求改了以后不再沿用旧 agent：继续时如果某一步还有上一次尝试留下的 agent（按旧需求在做），会先停掉它再新开，不再接着等它或采用它的结果。
  • 超时只多等一轮：接着等上一次的 agent 时不再重新延长，卡住的步骤最多等两倍时限就会换人。
  • 自答的问题有人复核：方案审核最后一轮的问题由 builder 自答后，再加一轮方案审核复核这些答案，然后才写代码（快速档也一样）。
  • 连不上 Paseo 时不再挂住或泄漏连接：所有连接 30 秒连不上就放弃并关闭；接单器不会在 Paseo 离线期间积攒后台重连的连接。
  • 卡片回复更稳妥：卡片上还有没回答的问题，或回复区只写了一个"是""对"时，不再当作确认；需求方写的内容里如果带有 </card-reply> 这样的标签，不会再被当成 req-kit 的话。
  • 两个进程同时更新卡片记录时不再互相覆盖（流水线写 AI 区与接单器转达回复）。
  • Windows：状态文件被杀毒软件或索引服务短暂占用时会重试，不再让流水线意外退出。
  • 发布流程：测试通过后才打版本标签，失败的发布不再占用版本号。

1.12.0 ​

稳定版：少等人，内容同 1.12.0-beta.1 至 beta.4（详见下面各条），设计决定见 ADR 0031。

使用者会看到的变化 ​

  • 自愈：超时时 agent 还在做就多等一轮；agent 报错、结果文件无效时新开 agent 重做一次；限流时按 Paseo 的额度恢复时间预约自动继续；可选的备用模型（agents.fallback）。
  • 方案审核的问题先自答，只把业务取舍连同推荐答案交给需求方。
  • 后台进程意外退出后自动继续：定时检查默认每 60 分钟；接单器也会发现并续跑。
  • 装好就选好模型：安装时自动选 builder、reviewer 和备用模型；插件设置中有"模型"页。
  • /req 少问：工作区、档位、执行方式、开始时间按推荐值走，确认摘要写明；卡片回复写"好的"也算同意。
  • 插件："等你处理"收件箱（直接确认方案、回答问题、继续），"配置"页列出全部设置和来源。
  • 接单器：自检与告警、草稿合并请求（push.mergeRequest）、小改动自动确认（autoConfirm.hours）、按人通知（people）。
  • req stats："人工介入"一节：停下等人的原因、自动处理的次数和比例。

升级须知 ​

  • 默认行为的变化：selfHeal、answerQuestionsFirst 默认打开，watchdogMinutes 默认从 0 改为 60。想保持 1.11 的行为，分别设为 false、false、0。
  • 新配置都可选：agents.fallback、push.mergeRequest、autoConfirm、people。
  • 外部通知新增事件 alert 和字段 people；状态文件和使用记录新增 stopKind、recoveries，旧文件照常可用。
  • 从 1.11 升级后运行 paseo plugin reload req-kit（或重启 Paseo）加载新插件。

1.12.0-beta.4 ​

  • 修正：1.12.0-beta.3 的 Paseo 插件加载失败（"Invalid plugin RPC method: req.setAgents"）。Paseo 要求插件接口名只用小写字母、数字和 . _ -，改为 req.set-agents；测试中加上了这条规则的检查。其余内容同 1.12.0-beta.3。

1.12.0-beta.3 ​

接单机器能自己发现问题；插件里可以直接处理等你的事、看到全部配置。

使用者会看到的变化 ​

  • 插件"等你处理"：需求首页最上面列出所有等人处理的事（确认方案、回答问题、中断、未完成），等得最久的在前，写明要做什么、等了多久。方案可以直接确认或写修改意见，问题可以直接回答，插件把回复转给需求的对话，和在对话里回答一样（req reply）。
  • 插件"配置"页：首页的"配置"按主题列出 req-kit 的全部设置，每项写明是什么、现在的值、来自本机、团队还是项目的配置文件；可以按项目查看、搜索、只看改过的。只看不改，页尾写明各项怎么改。密钥和个人账号不显示。
  • 接单器自检与告警：每次检查前确认 Paseo 在线、agent 已登录、额度没用完、需求管理系统的命令可用；不正常时暂停接单，并通过外部通知告警一次（新事件 alert），恢复时再说一次。
  • 草稿合并请求（可选，push.mergeRequest）：推送分支后用机器上已登录的 glab 等命令建草稿合并请求，描述是提测说明和卡片链接，地址写进卡片。合并仍由人做。req doctor 检查是否已登录。
  • 小改动自动确认（可选，autoConfirm.hours，默认关闭）：快速档、没有待答问题的卡片，AI 区写明到时没有异议就开始。
  • 按人通知：通知事件带上发给谁（people）：需求方要处理的事和结果发给卡片的提出人，账号来自配置的 people；其余发到群。内部 IM 适配器拿到接口后可以直接用。

升级须知 ​

  • 新配置 push.mergeRequest、autoConfirm、people（都只在需要时写）。people、push 只能写在本机或团队配置中。
  • 外部通知新增事件类型 alert 和字段 people；只订阅了部分事件的通知模块不受影响。
  • 新命令 req reply、req api config；req api list 的每一项多了 waiting。

1.12.0-beta.2 ​

1.12.0-beta.1 的内容（见下），加一处修正：

  • 修正：安装时自动选模型，Paseo 没有运行时会一直等待连接；现在 20 秒连不上就放弃，改为提示之后运行 req configure --auto。1.12.0-beta.1 因此没有发布。

1.12.0-beta.1 ​

少等人：能自动处理的中断不再停下等人，选择题改为默认值，装好就选好模型。设计决定见 ADR 0031。

使用者会看到的变化 ​

  • 自愈：步骤超时而 agent 还在做时，再等它一轮；agent 报错、没写出有效结果时，新开一个 agent 重做一次。限流重试用完时，预约在 Paseo 显示的额度恢复时间之后自动继续，而不是固定 30 分钟。
  • 备用模型（可选）：配置 agents.fallback 后，报错重做、限流重试用完时换它把这一步做完。req configure 和插件的"模型"设置页会推荐一个。
  • 方案审核的问题先自答：审核说需要需求方决定时，先由 builder 从代码和文档中找答案，只把真正的业务取舍连同推荐答案交给需求方；都能回答时不停下。
  • 后台进程意外退出后自动继续：定时检查默认打开（每 60 分钟）；接单器每次检查时也会发现并请对话继续。
  • 装好就选好模型：安装时自动选好已登录的 agent（两个不同厂商分别做 builder 和 reviewer，再选一个做备用），不再需要回答配置向导；req configure --auto 同样。插件设置中新增"模型"一页，可以直接修改。
  • /req 少问：不再问是否新建工作区、档位、执行方式、现在开始还是预约，按推荐值直接走，确认摘要最后一行写明，想改再说；确认需求说明后立即开始。
  • 卡片回复更宽松：写"好的""没问题""按你说的来"也算同意；回复区只写了一句"好的"也算确认。卡片已经写清需求时，不再为提问而提问；问题附上推荐答案。
  • req stats 新增"人工介入"一节：停下等人的原因、自动处理的次数、到达提测的需求中没有非必要介入的比例。

升级须知 ​

  • 新配置 selfHeal、answerQuestionsFirst（默认都是 true）、agents.fallback（可选）；watchdogMinutes 默认从 0 改为 60。想保持以前的行为，分别设为 false、false、0。
  • 状态文件新增 stopKind、recoveries，使用记录的 run 新增 stopKind、recoveries；旧文件照常可用，统计按状态推断旧记录的原因。

1.11.0 ​

稳定版：包含 1.10 的"从卡片开始的需求"和 1.11 的接单器（详见下面的 beta 记录），并修正步骤超时后会重复开 agent 的问题。

使用者会看到的变化 ​

  • 从卡片开始的需求（1.10）：req start --from <系统>:<卡号> 读卡片、建需求会话；卡片描述末尾的 AI 区和需求方回复区代替对话；按子系统自动选仓库；工厂模式下研发完成后可以推送 req/ 分支；统计按需求方汇总。
  • 接单器（1.11）：req factory 定时接标题带 [AI]/【AI】 的新卡片，并把需求方的回复转给需求会话。
  • 修正：步骤超时后不再重复开 agent。以前超时只判定失败、不看 agent 实际状态，继续时会新建一个 agent，而旧的仍在运行，两个 agent 同时改同一批文件、在同一个工作区提交、写同一个结果文件，需要手动停止旧的。现在继续（--resume、自动重试）时先看上一次的 agent：做完了就用它的结果；还在做就接着等它一轮；第二次仍超时才停止它，再新建。连续读不到 agent 状态时同样处理。

升级须知 ​

  • 从 1.9 升级：先看 1.10.0-beta.1 至 1.11.0-beta.1 的升级须知（对接配置的 query、describe、list，项目配置的 cardSource，本机或团队配置的 push、factory）。不用卡片的项目不需要改任何配置。
  • 状态文件的步骤记录新增 leftRunning、reattached 两项，旧状态文件照常可用。

1.11.0-beta.1 ​

接单器：一台共享研发机器自动接卡片、转达回复，需求方只在卡片上操作。

使用者会看到的变化 ​

  • req factory：每隔几分钟（factory.pollMinutes，默认 5）检查一次需求管理系统：本机登记的仓库所在空间中，标题以 [AI] 或 【AI】 开头、还没开始过的卡片，自动按子系统进入对应仓库、开始需求；需求方在卡片中的新回复自动转给需求会话。
    • req factory once 检查一次；start / stop 在后台运行；status 看最近一次检查和没能接的卡片；service 给出作为系统服务（开机自动运行）的写法。
    • 每次最多开始 3 个需求（factory.maxNewPerPoll），其余下次再接；接不了的卡片记下原因，卡片改了马上再试，否则一天后再试。
  • 修正：req start --from 在建需求会话时失败（例如 Paseo 没在运行）后，再运行一次会补建会话，而不是提示"已经开始过"。

升级须知 ​

  • 需要在对接配置中加上 list（列出卡片的命令），写法见《项目定制与运行规则》的"接单器"一节；接单的仓库要在 cardSource 中写上空间（projectId）。
  • 新增配置 factory（只能写在本机或团队配置中）、本机目录 ~/.req-kit/factory/。现在只支持一台机器接单。设计决定见 ADR 0030。

1.10.0-beta.3 ​

从卡片开始的需求：按子系统自动选仓库、研发完成后推送分支、统计按需求方汇总。

使用者会看到的变化 ​

  • 按子系统选仓库：在仓库中运行 /req-setup 时可以写上这个仓库接哪个空间、哪些子系统的卡片（同一子系统有几个仓库时再写标题关键字），并在本机登记。之后 req start --from ALM:<卡号> 不用写 --repo。req card route 查看本机登记的仓库。
  • 推送分支（默认关闭）：本机或团队配置打开 push 后，从卡片开始的需求在研发完成、写好提测说明后推送到 origin 的 req/<卡号简称> 分支，分支名写进卡片。不强推、不合并。
  • 统计：运行记录带上需求方和卡号，req stats --report 多一节"从卡片开始的需求（按需求方）"，CSV 多 requester、card 两列。

升级须知 ​

  • 都是可选的。推送只在 push.enabled 为 true、需求是从卡片开始的时候发生，并且只能在本机或团队配置中打开（ADR 0029 记录了这条对"只在本地提交"规则的放宽）。
  • 新增项目配置 cardSource、本机文件 ~/.req-kit/card-repos.json、状态文件可选字段 pushed、运行记录可选字段 requirement.requester 和 requirement.source，格式版本都不变。

1.10.0-beta.2 ​

（1.10.0-beta.1 的发布任务因一个测试的顺序问题失败，没有发布，内容相同，以 beta.2 发布。）

从卡片开始需求：需求方在需求管理系统中写好卡片，不必有人在 Paseo 对话里发起；问题和确认通过卡片描述往来。这是"软件工厂"的第一步，定时接单器在 1.11。

使用者会看到的变化 ​

  • req start --from <系统>:<卡号>：读一张卡片，建功能目录，在 Paseo 中为这个需求建一个需求会话。需求会话按新的无人值守手册从卡片写需求说明，把摘要、验收标准、假设和问题写进卡片描述末尾的"req-kit AI 区"；需求方在"需求方回复"区回答，写"确认：同意"后它自己启动开发（自动新建工作区）。需求方自己写的描述原样保留。
  • req card check [<卡号> | --all]：读需求方的回复，把新的回答、补充、描述修改和确认转给需求会话；同样的内容只转一次。req card list 列出本机从卡片开始的需求。
  • 开发中卡片跟着走：状态按 statusMap 改（例如"开发中""待测试"），AI 区更新进度；方案待确认时附上方案摘要，需求方在"方案确认："后写"同意"即可。
  • 从卡片开始的需求用这张卡片，不另建卡片；项目没有指定执行方式时默认只做研发。
  • 在 Paseo 中打开需求会话可以看到整个过程。

升级须知 ​

  • 需要在对接配置中加上 query（读卡片）和 describe（改描述），写法见《项目定制与运行规则》"从卡片开始需求"。不用这个功能的，什么都不用改。
  • 行为变化："只做研发"的需求在研发完成时，发给外部系统对接的事件由 completed 改为 phase_done（"研发完成，待测试"）。给 phase_done 配了状态的，这类需求的卡片会改为那个状态，而不是"完成"对应的状态。
  • 功能目录新增 source.json、card-source.md、card-ai.md（只在从卡片开始的需求中）；本机新增 ~/.req-kit/cards/。状态文件格式不变。设计决定见 ADR 0029。

1.9.1 ​

1.9 的正式版（1.9.0 的发布任务因一个测试的时序问题失败，没有发布到 npm，内容相同，以 1.9.1 发布）。汇总 1.9.0-beta.1 到 beta.3 的全部内容（各节见下）：本机的需求索引与使用统计、Paseo 插件、外部系统对接。

使用者会看到的变化 ​

  • 使用统计：req stats 看本机的需求数、交付周期、返工、等待时长、用时和用量；--report 生成给管理方的汇总和明细，--export / --merge 汇总多台机器。
  • Paseo 插件（req plugin install）：在 Paseo 的网页端、桌面版和手机上查看本机所有需求的进度、文档（按 Markdown 显示）和统计，确认方案、停止、继续、开始测试验证、同步到外部系统。可以设为只读。
  • 外部系统对接：配置 integrations 后，需求在团队的需求管理系统中自动建卡、跟着阶段改状态；卡片字段在确认需求说明时整理。req integration test 预演命令，req sync 补发。
  • req api：给程序用的 JSON 接口，插件通过它工作。

升级须知 ​

  • 从 1.8.0 升级：依次看下面 1.9.0-beta.1 到 beta.3 的升级须知。三项新能力都是可选的；升级后在项目目录运行一次 req index --rebuild，让之前运行过的需求出现在索引和插件中。
  • 装过插件的，req upgrade 会自动把插件换成 1.9.1。
  • 从 1.9.0-beta.3 升级：功能没有变化，只改了版本号和文档中的版本示例。

1.9.0-beta.3 ​

外部系统对接：需求在团队的需求管理系统中自动建卡、跟着阶段改状态；插件中的文档按 Markdown 显示。

使用者会看到的变化 ​

  • 外部系统对接：配置 integrations 后，流水线开始时在需求管理系统中建一张卡，之后每到一个阶段改卡片的状态：开始开发、等待确认、研发完成、开始测试验证、完成、中断，对应哪个状态可以配置。卡片编号和链接显示在进度、完成报告和 Paseo 插件里。
    • 对接的是本机已有的命令行工具，命令的写法写在团队配置里，换系统或系统改参数都不用升级 req-kit。
    • 卡片的业务字段（优先级、需求类型等）由 AI 在确认需求说明时从需求说明中整理，和需求方一起确认后写进 card.json。
    • 外部系统出错不影响流水线：失败的调用会自动补发，也可以运行 req sync <需求>，插件中有"同步到外部系统"。
    • req integration test [需求] 显示每个事件会执行的完整命令，但不真正调用，配置时先用它检查。
  • 插件：文档按 Markdown 显示（标题、列表、表格、代码、链接），decisions.tsv 等显示为表格；需求详情中显示外部系统的卡片和链接。

升级须知 ​

  • 对接是可选的，写法见《项目定制与运行规则》的"外部系统对接"。integrations 只能写在本机或团队配置中；项目可以在自己的配置中用 integrationDefaults 提供项目编号等取值。
  • 状态文件新增可选字段 external，功能目录新增 card.json，格式版本仍为 1。
  • 自定义了 prompts.local/ 的不受影响；/req 的新需求手册在确认前多一步"卡片字段"，没有配置对接时自动跳过。设计决定见 ADR 0028。

1.9.0-beta.2 ​

Paseo 插件：在 Paseo 的界面里查看和管理需求。

使用者会看到的变化 ​

  • req-kit 插件（req plugin install）：在 Paseo 的网页端、桌面版和手机上都能用。
    • 侧边栏的"需求"：本机所有项目的需求，按"需要你处理、进行中、待测试验证、最近完成"分组，带待处理的数量。
    • 需求详情：每一步的状态、用时和结论（点开进入那个步骤的 agent）、质量门、联合需求的各仓库、用量；可以读需求说明、方案、确认预览、提测说明、完成报告等。
    • 确认方案、停止、继续、开始测试验证：每个都要再确认一次，做的事与终端里的 req 命令完全相同。
    • 每个工作区头部的"需求"按钮和面板、步骤 agent 输入框旁的"需求"按钮、使用统计页、Ctrl+K 中的"需求总览"。
    • 插件设置中可以打开"只读"，给只看不操作的人用。
  • 安装脚本最后询问是否安装插件（--with-plugin 直接安装，--no-plugin 不问；PowerShell 用 $ReqKitPlugin）。
  • 修正：安装脚本判断 Paseo 网页界面是否已开启时，读错了 paseo daemon config get 的输出（"已设置"被当成"已开启"）。

升级须知 ​

  • 插件是可选的。安装时会询问是否打开 Paseo 的插件总开关（pluginsEnabled）：插件是不受沙箱限制的代码；req-kit 插件只运行本机的 req api，不连接外部服务。
  • 装过插件后，req setup、req upgrade、req use 会自动把插件换成启用的版本。插件随 req-kit 一起发布，不需要单独的 npm 包。
  • 需要 Paseo 0.11。1.9 之前运行过的需求，先在项目目录运行一次 req index --rebuild。设计决定见 ADR 0027。

1.9.0-beta.1 ​

1.9 的基础：本机知道自己有哪些需求，记下每次运行的用时和用量，并给程序一个稳定的读取接口。插件（beta.2）和外部系统集成（beta.3）都建在它上面。

使用者会看到的变化 ​

  • 使用统计 req stats：在任何目录运行，看本机最近 30 天（--since、--month 2026-10）的统计：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败次数）、等待确认和等待决定的时长、各步骤用时、token 用量和费用、不同 builder 的比较。
  • 给管理方的汇报：req stats --report --month 2026-10 生成汇总（.md）和每个需求一行的明细（.csv，可以用表格软件打开）。几台机器一起汇报时，每台 req stats --month 2026-10 --export，再在一处 req stats --merge <文件…> --month 2026-10 --report。
  • 本机的需求索引：运行过的需求会登记在本机，req index 查看。1.9 之前运行过的需求在项目目录运行一次 req index --rebuild 补登；req index --prune 清理目录已不在的。
  • req api：给程序用的 JSON 输出：列出本机或当前仓库的需求、一个需求的步骤和质量门、读取功能目录中的文档、统计，以及确认方案、停止、继续、开始测试验证这几个管理操作。Paseo 插件将通过它工作。格式见 contracts/cli-json.md。

升级须知 ​

  • 新增本机文件：~/.req-kit/index/（每个需求一个小文件）和 ~/.req-kit/usage/runs.jsonl（每次运行一行）。只在本机，不记需求内容和代码，不会自动发往任何地方。不想记录时设置环境变量 REQ_KIT_NO_RECORD=1。
  • 统计只从升级后的运行开始；之前的运行没有记录。
  • 状态文件、结果文件和提示词都没有变化。设计决定见 ADR 0026。

1.8.0 ​

第一个正式版。汇总 1.8.0-beta.1 到 beta.3 的全部内容（各节见下），并让新机器一条命令就能从零用起来。

使用者会看到的变化 ​

  • 一键安装改用站点地址：
    • macOS、Linux、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
    • 原来的 GitHub 地址仍然可用。
  • 一键安装会准备好 Paseo：
    • 新机器上没有 Paseo 时，脚本先安装与这个版本匹配的 Paseo 命令行（@getpaseo/cli@~0.11.0），开启它自带的网页界面，再启动 daemon。装完在浏览器打开 http://localhost:6767/ 就能用 Paseo 对话，不必另装桌面版。
    • 已有 paseo 命令时不重装：核对版本（不在支持范围内时提醒），开启网页界面；daemon 没在运行就启动。daemon 已在运行而网页界面是刚开启的，只提示 paseo daemon restart，不自动重启，因为重启会中断正在运行的 agent。
    • 只有桌面版 Paseo 管理的 daemon（没有 paseo 命令）时什么都不装，只提示在桌面版中开启网页界面。
    • 一个 agent 命令行（Claude Code、Codex、OpenCode、Pi、Copilot）都没有时会提醒。
    • 不想让脚本动 Paseo 时加 --skip-paseo（PowerShell：$ReqKitSkipPaseo = $true）。
  • 1.8 的内容：
    • 按需求类型分流（缺陷先复现、重构先锁行为、评估只出报告）。
    • 质量门、按切片实现、范围检查、关联仓库。
    • 带例子的验收标准、开工前确认方案、评审分规格和规范两个方向、反复出现的问题变成规则。
    • 前后端联合需求。

升级须知 ​

  • 这是 npm 上的第一个 latest 版本：npm i -g paseo-req-kit 和不带 --beta 的一键安装从此装正式版。在 beta 通道的（req upgrade --beta 或 @beta）照常收到之后的 beta 版；没有更新的 beta 时，一键安装的 --beta 装正式版，而不是更早的 1.8.0-beta.3。
  • 从 1.7.x 或更早升级：依次看下面 1.8.0-beta.1 到 beta.3 的升级须知。最重要的是在每个项目主目录的对话中再运行一次 /req-setup，写入检查命令、术语表和范例文件。
  • 从 1.8.0-beta.3 升级：引擎和提示词没有变化，只改了安装脚本和文档。

1.8.0-beta.3 ​

联合需求：前端和后端分在两个仓库的需求，可以作为一个需求一起做。

使用者会看到的变化 ​

  • 联合需求：另一个仓库已经登记为关联仓库（relatedRepos）时，/req 会问两边都要改的需求是否一起做。需求说明头部写 - 联合开发：后端（最多再加两个仓库）。
    • 流水线为后端新建一个工作区（分支同名），后端那份检出本身不动。
    • 在发起需求的仓库（主仓库）设计整体方案，并写出双方的接口约定 contract.md（字段、错误码、示例），方案审核一起审，通过后冻结。
    • 需求说明、方案和接口约定同步到后端的工作区并提交；两边同时实现、评审、修复，各用各的检查命令和项目说明。子 agent 列表中显示为"5-代码实现（后端）"。
    • 提测说明、功能验证和报告在主仓库：两边的服务都由 Paseo 启动，每个缺陷发回它所在的仓库修复，再一起复验。报告写明每个仓库的分支和合并顺序，合并仍然由人来做。
    • 进度查询显示每个仓库的工作区和各自的步骤。

升级须知 ​

  • 新的 spec 头部行 - 联合开发：（relatedRepos 中的名称）。关联仓库最好也运行过 /req-setup：它自己的 checks、验证方法和项目说明会用在它的步骤里。
  • 状态文件新增可选字段 joint，验证和复验的结果文件新增可选字段 defect_repos，格式版本仍为 1。回滚到更早的版本后，旧引擎只在主仓库继续，其他仓库工作区中的改动保持原样。
  • 自定义了 prompts.local/ 的：新增 joint.md。
  • 联合需求的用量大约按仓库数增加；几个仓库的步骤同时运行，本机同时运行的 agent 也更多。设计决定见 ADR 0025。
  • 维护者：main 收到版本号还没有标签的 package.json 时，发布工作流会自动打上同名标签并发布，不必再手工打标签（手工打照样可以）。

1.8.0-beta.2 ​

让"做成什么样"的分歧更早暴露：验收标准带例子、开工前确认方案、评审分两个方向、反复出现的问题变成规则。

使用者会看到的变化 ​

  • 验收标准带例子：AI 写验收标准时给每条配上具体的数据（输入什么、看到什么；按规则计算的给出边界上的几组），确认前的独立审阅会检查这一点。这些例子直接成为测试的期望值：你确认的，就是测试会检查的东西。
  • 开工前确认方案（标准档的界面改动）：方案审核通过、写代码之前，流水线停下来发来"请确认方案"：AI 讲 preview.md 的要点（做完后会看到什么、需要你确认的假设、不会变的地方），界面改动还有静态的原型页面（prototype/）。说"可以"就开工；想改就直接说，更新需求说明后方案会调整，再请你看一次。功能验证会对照确认过的原型。终端里新增 req approve <需求>。
  • 代码评审分两个方向：标准档第一轮由规格评审（每条验收标准是否实现、测试是否用了验收标准的例子、有没有做需求之外的事）和规范评审（项目惯例、范例文件、术语、测试质量、安全）同时进行，再汇总成一份结论。
  • 验收测试先提交：适合测试先行时，从例子写出的测试先单独提交；之后被改过的，代码评审前由流水线列出，评审逐个确认有没有依据。
  • 术语表和范例文件：/req-setup 整理 GLOSSARY.md（业务词、含义、代码中的名字）并列出各类代码的范例文件；方案的每个任务写明照哪个文件的写法来。
  • 反复出现的问题变成规则：完成报告把一条项目规则就能挡住的问题记进 lessons.tsv；同一类问题在两个以上需求里出现时，需求总览（req digest）会提示，/req-retro 会建议把它变成 lint 规则、测试或项目说明里的一行。

升级须知 ​

  • 新配置（都有默认值）：designApproval（mode 默认 ui、profiles 标准档、autoContinueHours 0）、reviewAxes（默认标准档开启）。不想要开工前的确认，设 "designApproval": { "mode": "off" }；不想多两次评审，设 "reviewAxes": { "enabled": false }。
  • 新状态 waiting_for_approval（等待需求方确认方案）和启动参数 --approve。等待确认时单独的 --resume 会被拒绝。状态文件新增可选字段 approval，格式版本仍为 1；回滚到更早的版本后，旧引擎会不经确认直接继续写代码。
  • 结果文件新增可选字段：方案设计和修订的 ui_change，代码实现的 acceptance_tests、acceptance_tests_commit。外部通知新增事件 approval（notifiers/im-template.mjs 已加上它的标题）；只订阅了部分事件的不受影响。
  • 自定义了 prompts.local/ 的：新增 review-axis-spec.md、review-axis-standards.md；00-shared-context.md、02-spec-review.md、03-design.md、04-design-review.md、04b-design-revise.md、05-implement.md、06-code-review.md、09-verify.md、11-report.md、incremental.md 有增补，覆盖过它们的请对照合并。
  • 在项目主目录再运行一次 /req-setup，生成术语表和范例文件清单。/req-doctor 会提醒没有 GLOSSARY.md 的项目。设计决定见 ADR 0024。

1.8.0-beta.1 ​

研发流程按需求类型分流，代码检查由流水线自己把关，大需求按切片实现。

使用者会看到的变化 ​

  • 需求类型：/req 复述需求时会确认它是哪一类，流水线按类型走不同的做法：
    • 缺陷：先复现、找到根因再修。第一步改为"复现与定位"，先提交一个修复前失败的复现测试，写 diagnosis.md；复现不了就暂停，把需要你补充的信息发回对话。修复要让复现转绿，评审会实际确认。
    • 重构：先用测试锁住现有行为，再小步改动；评审首先看行为有没有变。
    • 评估：只调研、写评估报告（assessment.md），由另一个模型审阅，不写代码、不做验证；报告附需求草稿，可以接着说"按评估结果提一个新需求"。
  • 质量门：项目配置了检查命令时，流水线在写代码和修复的步骤之后自己运行 lint、类型检查、测试、构建。改动前通过、现在失败的，发回那一步的 agent 修复（最多 2 次）；仍然失败的交给代码评审和报告，报告结论最高为"有遗留问题"。进度查询会显示质量门的结果。
  • 按切片实现：标准档的方案分成几个能单独验证的切片时，代码实现逐片进行，每片一个新的 agent、各自提交和检查；子 agent 列表中显示为"5-代码实现 第2/3片"，中断后只重做当前片。
  • 范围检查：代码评审前比对方案列出的文件和实际改动的文件，清单之外的改动由评审逐一说明理由；评审新增"影响面"一节，只把影响正确性、安全、数据和验收的问题提为必须修改，避免越改越复杂。
  • 多模块与关联仓库：检查可以只在对应模块有改动时运行；其他仓库（例如前端项目的后端）可以登记为关联仓库，各步骤只读参考，不用猜接口。

升级须知 ​

  • 在项目主目录的对话中再运行一次 /req-setup：它会把实际跑通的检查命令写进 .requirement-pipeline.json 的 checks，并询问关联仓库。不运行也能用，只是没有质量门，/req-doctor 会提醒。
  • 新配置（都有默认值）：checks、qualityGate（fixAttempts 2、timeoutMinutes 20）、slices（profiles 标准档、max 6）、requirementTypes（缺陷、重构、评估）、relatedRepos。spec 头部的 - 类型： 由引擎读取（之前只给人看）：已有 spec 中写着"缺陷"的，继续时会按缺陷的做法进行。
  • 结果文件新增可选字段：方案设计的 slices、files、reproduced、questions，方案修订的 slices、files。状态文件新增可选字段 type、codeBase、gate，格式版本仍为 1。回滚到 1.7 后旧引擎忽略它们；按切片实现中断的需求，旧引擎会把实现整个重做一遍。
  • 自定义了 prompts.local/ 的：新增 types/defect.md、types/refactor.md、types/assessment.md、related-repos.md；00-shared-context.md、03-design.md、04-design-review.md、04b-design-revise.md、05-implement.md、06-code-review.md、07-review-fix.md、10-defect-fix.md、11-report.md 有增补，覆盖过它们的请对照合并。
  • 有质量门的项目，每次尝试开始时多一次检查运行，写代码的步骤之后各多一次；检查要能在几分钟内跑完。
  • 评估：新增用例 text-utils-rounding-defect（缺陷类型，检查先复现再修）。设计决定见 ADR 0023。

1.7.0-beta.3 ​

一键安装、产品站点，以及 paseo.json 跨系统。

使用者会看到的变化 ​

  • 一键安装：curl -fsSL https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.sh | sh（macOS、Linux、Git Bash、WSL），Windows PowerShell 用 irm …/install.ps1 | iex。一条命令完成检查环境、安装（npm 上没有时用 GitHub Release 的安装包，npm 全局目录不可写时装到 ~/.req-kit/npm）、req setup 和配置向导，再次运行即升级。
  • 产品站点：https://yiyisf.github.io/paseo-req-kit/ ，包括首页、快速开始、工作原理、分阶段执行、命令和配置参考，以及由仓库文档生成的指南、文件约定、设计决定和更新记录（site/，VitePress）。
  • paseo.json 跨系统：Paseo 在各系统上用不同的 shell 执行 paseo.json 的命令（macOS/Linux：bash、sh；Windows：准备命令用 PowerShell，脚本和服务用 cmd.exe），之前按 bash 写的命令（$PASEO_PORT、[ -f … ] && cp …）在 Windows 上会失败。/req-setup 现在只写各系统一样的命令，并在项目中写入两个小脚本 scripts/paseo/with-port.mjs（服务端口）和 scripts/paseo/copy-local-files.mjs（复制本地配置）；/req-doctor 按本机系统检查 paseo.json，在本机会失败的写法给出警告，只在某个系统能用的写法给出提示。已经用 /req-setup 生成过 paseo.json 的项目，再运行一次即可更新。

升级须知 ​

  • 已安装的机器：req upgrade --beta，或重新运行一键安装命令。
  • 已经用 /req-setup 生成过 paseo.json 的项目：在项目主目录的对话中再运行一次 /req-setup，改成各系统通用的写法（会新增 scripts/paseo/ 下的两个脚本）；不改也能用，/req-doctor 会提示哪些命令只在部分系统上有效。
  • 安装包新增 LICENSE（MIT）。状态文件、配置格式没有变化。
  • 维护者：文档站点由 .github/workflows/site.yml 构建并推送到 gh-pages 分支，需要在仓库 Settings → Pages 中选择从 gh-pages 分支发布；发布流程支持对已有标签手动重跑（Actions → release → Run workflow）。

1.7.0-beta.2 ​

分阶段执行：研发和测试验证可以分开进行。

使用者会看到的变化 ​

  • 提测说明：代码评审之后新增一步，写 handoff.md：这次改了什么、怎么跑起来、自测结果、建议重点测试、已知问题、测试前要准备什么。功能验证会先读它。
  • 执行方式：标准档的需求在确定档位时可以选（团队或项目配置里定好了就不问）：
    • 连续（默认，与之前一样）：研发完成后接着做测试验证。
    • 分阶段：研发完成后停下来通知"研发完成，可以提测"；你或测试同事说"开始测试验证"再开始，也可以预约时间（--verify-at）。一天没有开始会提醒一次。
    • 只做研发：做到提测说明和研发报告为止，验收时按提测说明人工测试；之后仍可以让流水线做测试验证。
  • 测试验证的做法：开始测试时可以选在本地验证，还是在已部署的测试环境中验证（AI 会和你一起写 test-env.md，只写口令在哪里取）；发现缺陷时当场修复、退回研发修复后再提测，或只记录。测试阶段也可以换一个 agent（例如测试同事习惯的 profile）。
  • 测试同事接手：用"开发时自动新建工作区"开发的需求，研发完成后，测试同事可以在这个项目任何工作区的对话里输入 /req 开始测试验证 <需求名称> 接手，之后的通知发到他的对话。
  • 进度和总览：显示"研发完成，待测试验证"，总览把它归入"需要处理"；用时与用量按阶段分别统计。终端里新增 req verify <需求>。
  • 外部通知：新增事件类型 phase_done（带提测说明的路径和开始测试验证的命令），可以直接通知测试同事。

升级须知 ​

  • 所有运行（包括连续方式）多了"提测说明"一步，通常几分钟；新增步骤超时 stepTimeoutMinutes.handoff（30 分钟）。
  • 新的可选配置 phases（mode、verify.environment、verify.agents、verify.defects、verify.serviceStart），默认值保持原来的行为；spec 头部可选的新行 - 执行方式：；启动参数 --phases、--phase verify、--verify-at、--verify-env、--defects。
  • 状态文件新增可选字段和状态值 phase_done，格式版本仍为 1。回滚到 1.7.0-beta.1 或更早版本后，旧引擎把"研发完成，待测试验证"当作可以继续的中断，继续时沿用研发结果、直接做验证。
  • 外部通知模块：新事件类型 phase_done；只订阅了部分事件（events）的不受影响。notifiers/im-template.mjs 已加上它的标题。
  • 自定义了 prompts.local/ 的：新增提示词 07b-handoff.md、verify-deployed.md；09-verify.md、11-report.md、incremental.md 有增补，覆盖过它们的请对照合并。
  • 评估：新增用例 text-utils-tb-gated，检查研发完成后停在闸口并写了提测说明。设计决定见 ADR 0022。
  • 发布：1.7.0-beta.1 的发布工作流因类型检查失败没有发布到 npm（新建工作区时传了 Paseo 0.11.2 还不认识的 background 选项，已去掉；之前不会影响运行），1.7.0-beta.2 包含它的全部内容。新增 ci.yml 在推送到 main 时先跑一遍检查；第一次发布到 npm 在本机手工进行，之后用可信发布（见维护者指南）。

1.7.0-beta.1 ​

npm 分发：npm i -g paseo-req-kit 安装，按本机 Paseo 的版本升级。

使用者会看到的变化 ​

  • 用 npm 安装：npm i -g paseo-req-kit，然后 req setup、req configure。Windows 上 req 命令由 npm 放进 PATH，不用再手工设置。全局安装的是一个版本管理器：各版本仍装在 ~/tools/req-kit/versions/<版本>，正在运行的流水线不受升级影响。
  • 按 Paseo 版本升级：req upgrade 先读本机 Paseo daemon 的版本，只升级到能支持它的 req-kit，并说明跳过了哪些版本、为什么。req upgrade --beta 在正式版上也考虑 beta 版。
  • 新命令：req versions（已安装的版本和 npm 上的版本）、req use <版本>（切换或回滚）、req setup。也提供同名命令 req-kit，避免和其他工具的 req 冲突。
  • 体检：显示本机 Paseo 的版本，以及它是否在当前 req-kit 支持的范围内。
  • 发布：每个版本发布到 npm（beta 版用 beta 标签），正式版另有 paseo-<小版本> 标签（如 npm i -g paseo-req-kit@paseo-0.11）；GitHub Release 附带离线安装包。

升级须知 ​

  • 已用 git 安装的机器可以照旧 req upgrade（来源仍是 git）；想改用 npm：npm i -g paseo-req-kit 后 req setup，原有的 git 版本保留在 versions/ 中，可以 req use 切回。
  • req upgrade --from 现在接受 npm、git 或 git 地址。
  • 依赖查找改为按 Node 的方式向上查找（npm 安装时依赖在 versions/<版本>/node_modules）。
  • 维护者：发布改由 GitHub Actions 完成（.github/workflows/release.yml），需要先在 npmjs.com 上把仓库登记为可信发布者，见维护者指南。设计决定见 ADR 0021。
  • 状态文件和配置没有变化。

1.6.0-beta.1 ​

调度：预约开始、等待提醒、中断后自动继续、排队，以及需求总览。

使用者会看到的变化 ​

  • 预约开始：确认需求后可以说"今晚 10 点开始"或"明天早上开始"。流水线用 Paseo 定时任务预约，到时在这个对话里自动执行启动命令；在那之前修改需求说明也没关系。查看进度能看到预约，说"先停一下"即可取消。
  • 等待提醒：方案审核提出需要你决定的问题后，如果 24 小时内没有回答，会在对话里提醒一次（waitingReminderHours）。
  • 中断后自动继续：因限流、网络中断等临时错误中断（已自动重试过）时，预约 30 分钟后在对话里自动继续，每次尝试最多 2 次（autoResumeMinutes、autoResumeMax）。中断通知会写明预约的时间；说"先停一下"可以取消。
  • 排队：可以限制一台机器上同时运行的流水线数量（maxConcurrentPipelines，默认不限）。满了的时候新的需求会排队，并在对话里说明前面在跑哪些；轮到时自动开始。查看进度会显示"排队中"。
  • 定时检查（可选，默认关闭）：开启 watchdogMinutes 后，运行期间对话会定时检查一次，发现后台进程意外退出（例如机器重启）时自动继续。
  • 需求总览：req digest 列出项目中的需求，按"需要处理、待验收、开发中、对齐中、已验收"分组；req digest --notify 发到外部通知（如企业 IM，新的事件类型 digest）；req digest --schedule "0 9 * * 1" 让 Paseo 每周一 9 点自动发送。

升级须知 ​

  • 新的可选配置：maxConcurrentPipelines（0）、queuePollSeconds（60）、waitingReminderHours（24）、autoResumeMinutes（30）、autoResumeMax（2）、watchdogMinutes（0）。提醒和自动继续默认开启，不需要时设为 0。现有配置无需改动。
  • 新的启动参数 --at；新命令 req digest。
  • 外部通知新增事件类型 digest。通知模块配置了 events 列表的不会收到它；没有配置 events 的会收到，按 contracts/notifier-event.md 的约定，模块应忽略不认识的类型（模板已处理）。
  • 状态文件增加可选字段 schedules、autoResumes、queuedSince（格式版本仍为 1）。
  • 这些功能使用 Paseo 的定时任务（经由内部客户端，见 ADR 0020）；Paseo 不支持时自动关闭，并在输出中说明。
  • 设计决定见 ADR 0020。

1.5.0-beta.1 ​

并行编排：确认前的独立审阅、方案提案、浏览器验证，以及可选的"自动新建工作区"。

使用者会看到的变化 ​

  • 确认前独立审阅需求说明：标准档的需求在请你确认之前，会先请另一个模型（配置的 reviewer）在后台独立审一遍草稿，找出歧义、遗漏、没法验证的验收标准和矛盾，每个问题写成带推荐的选择题（spec-review.md）。几分钟后结果发回对话，AI 核对后再逐个问你。快速档默认不做。
  • 自动新建工作区（可选）：在项目主目录、主分支上提需求时，/req 多了一个选项"开发时自动新建工作区"：照常在这个对话里谈需求，启动开发时流水线为这个需求新建一个 worktree 工作区（分支 feature/<功能目录名>），把需求说明移过去提交，在那里开发；步骤仍然挂在这个对话下，对话的目录不变，之后的进度、暂停、继续、验收都在这里说。paseo.json 的环境准备会自动执行。
  • 方案提案（可选，默认关闭）：开启后，标准档的方案设计之前由几个 agent（默认 builder 和 reviewer）并行各提一份方案，方案设计步骤比较后决定，design.md 中多一节"方案比较"。
  • 浏览器验证：在 Paseo 设置中打开 Paseo 工具和浏览器工具后，功能验证、缺陷修复、复验步骤会用 Paseo 内置浏览器按验收标准实际操作网页，你可以在桌面端实时看到；截图在对应步骤 agent 的对话记录里。

升级须知 ​

  • 新的可选配置：specReview（"standard" 默认 / "always" / "off"）、designProposals（默认 {"enabled": false, "profiles": ["standard"], "members": []}）、browserVerify（"auto" 默认 / "off"）；stepTimeoutMinutes 增加 spec_review（20）、design_proposal（45）。现有配置无需改动。
  • 新的启动参数：--spec-review、--worktree。/req 的新需求手册增加了"独立审阅"一步，以及在主分支上"自动新建工作区"的选项；已经打开的对话请新开一个才能用到新手册。
  • 新增步骤提示词 02-spec-review.md、03a-design-proposal.md、browser-verify.md；已有提示词没有改动。
  • 状态文件增加可选字段 worktree（格式版本仍为 1）。用"自动新建工作区"启动的需求回滚到 1.4 之后，要在新工作区的对话中继续。
  • 修复：req resume <名称的一部分> 等简写在 1.3 中会让后台进程找不到功能目录，现在启动器把解析后的参数传给后台进程。
  • 设计决定见 ADR 0018（自动新建工作区，补充 0001、0002）、ADR 0019（并行编排）。

1.4.0-beta.1 ​

用好 Paseo 本身的能力（第一批）：agent profiles、paseo.json 与受 Paseo 管理的服务、额度提醒、实时活动。

使用者会看到的变化 ​

  • 用 Paseo 的 agent profile 配置 agent：配置中可以写 "builder": { "paseoProfile": "实现" }，引用在 Paseo 设置 → Agents → Agent profiles 中建好的 profile。之后换模型、改模式只需在 Paseo 中修改 profile，下一次运行生效。配置向导会先列出已有的 profile 供选择；写在 paseoProfile 旁边的字段优先于 profile 中的设置。
  • 服务由 Paseo 管理：项目的 paseo.json 中定义了服务（"type": "service"）时，流水线在服务启动验证、功能验证、缺陷修复和复验之前，通过 Paseo 带着当前代码重启这些服务，把地址交给步骤 agent，验证结束后停止。Paseo 为每个 worktree 分配独立端口，几个需求同时验证不会端口冲突。服务没有启动成功时，最后的输出会写到 .pipeline/services/<服务名>.log 交给步骤。
  • /req-setup 生成 paseo.json：新建 worktree 时自动安装依赖、复制本地配置（如 .env），并把常驻服务定义为监听 $PASEO_PORT 的服务。
  • 额度提醒：开始前读取 Paseo 的用量信息，所用 agent 的订阅额度用到 85% 以上时，在对话里提醒一次（不阻止运行）。
  • "做到哪了"更具体：运行中查看进度时，会附上当前步骤 agent 最近几分钟在做什么（运行了什么命令、改了哪些文件），从 Paseo 实时读取。
  • 体检：显示 Paseo 中的 agent profile 和引用的解析结果、Paseo 工具和浏览器工具是否开启、各 agent 的额度；检查项目的 paseo.json（服务是否使用 $PASEO_PORT、是否已提交）。

升级须知 ​

  • 新的可选配置：paseoServices（"auto" 默认 / "off"）、serviceReadySeconds（默认 120）、quotaWarnPercent（默认 85，0 关闭）；角色和评审小组成员可以用 paseoProfile 代替 provider。现有配置无需改动。
  • 新增步骤提示词 paseo-services.md（只在服务由 Paseo 管理时附加）；08-service-start.md、09-verify.md 增加了"服务由 Paseo 管理时"的说明。用 prompts.local/ 整篇替换过这两篇的，请对比新版。
  • /req-setup 有更新：已接入的项目可以再运行一次，生成 paseo.json。
  • 管理服务用到了 @getpaseo/client 0.11 导出的内部客户端（公开 API 还没有工作区脚本），见 ADR 0017；Paseo 版本不支持时自动退回到"步骤 agent 自己启动服务"。
  • 状态文件格式没有变化。

1.3.0-beta.1 ​

便利性与可靠性：配置向导、一键升级、req 命令、需求变更后增量继续、临时错误自动重试、用时与用量，以及接入企业 IM 的通知接口。

使用者会看到的变化 ​

  • 需求变更后增量继续：修改需求、回答了方案审核的问题、验收不通过后继续开发时，在已有方案和代码的基础上只处理变化的部分（方案追加"第 N 次尝试"一节，评审只看本次的改动，验证重点验变化的验收标准并回归其余的），通常比第一次快很多。要完全从零开始仍用 --restart。
  • 临时错误自动重试：限流（429）、服务暂时不可用、网络中断等临时错误，自动等待后重试（默认最多 2 次，间隔 1 分钟、5 分钟），重试的步骤会被告知工作区里可能有上次没做完的改动。重试用完仍失败才中断。
  • 用时与用量：查看进度、需求总览和完成报告中显示各步骤 agent 合计用时，以及 agent 报告的 token 用量和费用（有的 agent 不报告）。
  • req 命令：在终端中用短命令查看和操作需求：req list、req status、req stop sms-login、req resume sms-login、req doctor、req upgrade 等，req help 查看全部。需求可以只写名称中能唯一确定的一部分；只有一个需求运行过时 req status 不用写名称。
  • 配置向导：req configure（或 node install.mjs --configure）列出 Paseo 中可用的 agent、模型，自动选择不需要确认的运行模式，几个选择题即可写好配置，不再需要手工编辑 JSON。
  • 一键升级：req upgrade 下载最新版本、安装依赖并切换；req upgrade 1.3.0 指定版本；req upgrade --check 只看有没有新版本。/req-doctor 会提示有新版本。
  • 外部通知接口：可以在"需要你决定""等待批准""开发中断""已完成"和进展时刻，调用本机的通知模块，例如转发到企业内部 IM。req-kit 只提供接口和模板（notifiers/im-template.mjs），具体发送由使用方实现；req notify-test 发测试消息。

升级须知 ​

  • 本次可以用新的方式升级，也可以照旧手工升级。从 1.2 升级时 1.2 还没有 --upgrade，请按 安装与升级 第 6 节手工升级一次，之后就可以用 req upgrade。
  • 安装时会在 ~/.req-kit/bin 写入 req 命令（Windows 为 req.cmd）。是否加入 PATH 由你决定，安装输出中给出了命令。
  • 新的可选配置：retry（临时错误重试，默认 {"attempts": 2, "backoffSeconds": [60, 300]}，设 attempts 为 0 关闭）、notifiers（外部通知，默认为空；只在本机或团队配置中有效，项目配置中的会被忽略）。现有配置无需改动。
  • 新增步骤提示词 incremental.md（只在增量继续时附加）；11-report.md 增加了"用时与用量"。用 prompts.local/ 整篇替换过 11-report.md 的，请对比新版。
  • 状态文件增加了可选字段 incremental 和步骤记录中的 usage，格式版本仍为 1：回滚到 1.2 后可以继续已有的流水线（只是不再增量）。
  • 新的文件格式约定：contracts/notifier-event.md（通知事件，schema: 1）。设计决定见 ADR 0014–0016。

1.2.0-beta.1 ​

第三阶段（质量与分发）：评审小组、复盘、评估体系和团队配置。

使用者会看到的变化 ​

  • 开启评审小组后，标准档的方案审核和代码评审第一轮由几位评审者（可以是不同的模型）独立评审，再由评审者核实汇总。完成报告会列出被驳回的意见和留给人决定的事项。默认关闭。
  • 新增 /req-retro（复盘）：需求完成、中断或验收不通过后，找出问题和根因，按"能用机器挡住的不写进文档"的顺序提出改进，批准后落地。验收手册在验收不通过时会提示复盘。
  • 需求总览在 Windows 上能正确标出"当前工作区"。
  • 产物文件统一要求 UTF-8 编码；步骤提示词提醒不要用 Windows PowerShell 的重定向写文件（会变成 UTF-16）。

升级须知 ​

  • 新的可选配置：teamConfig（只在本机配置中有效，指向团队配置文件）、requiredVersion（版本要求，只提醒不阻止）、reviewPanel（评审小组，默认关闭）。现有配置无需改动。
  • 新增步骤提示词 panel-member.md；00-shared-context.md 增加了编码要求。用 prompts.local/ 整篇替换过 00-shared-context.md 的，请对比新版。
  • 新增评估：npm run eval:self-check（不需要 Paseo）和 npm run eval（真实运行流水线）。见 evals/README.md。
  • 新增 维护者指南：改动规则和发布流程。
  • 状态文件格式没有变化。

1.1.0-beta.1 ​

第二阶段（生命周期）：需求从提出到验收、上线后问题、接手的完整过程。

使用者会看到的变化 ​

  • /req 新增四本手册：
    • 修改需求：只谈变化的部分，需求说明版本加 1，变更记入 changes.md；已经完成的需求改完后也能继续开发，从方案设计重新开始。
    • 验收：按验收标准逐条核对，能用命令验证的给出命令，结果记入 acceptance.md；不通过的项可以转为修改继续开发。
    • 上线后发现问题：问清现象、复现步骤和影响，关联原需求，生成缺陷说明后按快速档修复。
    • 接手：列出项目中所有工作区的需求，讲清某个需求的现状、待决事项和下一步。
  • 完成报告新增"需要你确认的决定"：汇总各步骤中会影响结果的假设、取舍和被驳回的评审意见（来自新的决策记录 decisions.tsv）。
  • 验证结果写明每条验收标准的证据（命令及关键输出、截图或日志路径）。
  • 新增 /req-setup：为项目生成项目说明和验证方法（verify.md，其中的命令实际运行过）。接入后，实现、服务启动和验证步骤按它执行，更快也更稳定。

升级须知 ​

  • 建议每个项目运行一次 /req-setup，提交生成的 .requirement-pipeline/verify.md 和 project-notes.md。不运行也能使用，/req-doctor 会提示。
  • 流水线完成后，如果 spec.md 被修改过，--resume 会从方案设计重新开始（以前要求用 --restart）。spec 没改时仍然拒绝。
  • 新增 start-pipeline --list：列出这个仓库所有 worktree 中的需求。设计方案中的 docs/features/INDEX.md 改为现场生成，不提交，见 ADR 0010。
  • 步骤提示词有改动（决策记录、验证方法、证据要求）。用 prompts.local/ 整篇替换过提示词的，请对比新版。
  • 状态文件格式没有变化。
  • 版本标签不带 v 前缀，例如 1.1.0-beta.1。

1.0.0-beta.1 ​

第一阶段（骨架）。由"需求对齐 skill + 脚本流水线"（paseo-requirement-workflow）演进而来。

使用者会看到的变化 ​

  • 入口改为 /req（Pi 中为 /skill:req）。/req 会判断你想做什么：提新需求、做小改动、查看进度、暂停或继续。旧入口 /requirement-kickoff 仍然可用，会提示改用 /req。
  • 小改动有了专门的流程：只问 2–3 个关键问题，走快速档。
  • 访谈面向有一定技术背景的使用者：可以直接谈接口、字段、测试用例；会追问异常流程、测试数据和验证环境。
  • 验收标准写成"前置条件 / 操作 / 预期结果"，测试同事可以直接转成用例。
  • 完成报告写明每条验收标准的证据（运行的命令、输出、截图路径），方便自己复核。
  • 新增 /req-doctor：检查安装、配置、Paseo 和当前项目，列出要处理的问题和修复方法。

升级须知 ​

  • 安装方式变了：程序放在 ~/tools/req-kit/versions/<版本>/，本机配置放在 ~/.req-kit/config.json。从脚本版迁移时运行 node install.mjs --import-legacy ~/tools/requirement-pipeline，它会导入旧配置和 prompts.local/，并替换旧的 requirement-kickoff。
  • 不再需要 Matt Pocock 的 grilling、domain-modeling skill，可以保留或自行卸载。
  • 项目中的 .requirement-pipeline.json、.requirement-pipeline/ 和 docs/features/ 无需改动。旧的状态文件（没有 version 字段）按第 1 版读取。
  • 新的术语写入 GLOSSARY.md；已有的 CONTEXT.md 会继续读取，是否合并由开发同事决定。
  • 每个步骤的提示词现在包含"工作原则"一节（principles/INDEX.md）。用 prompts.local/ 整篇替换过 00-shared-context.md 的，请对比新版。
  • Paseo Hub 版本移到 legacy/hub-workflow/，不再维护。

本页由仓库中的 CHANGELOG.md 生成。在 GitHub 上编辑

以 MIT 许可发布。req-kit 是运行在 Paseo 上的社区项目。

Copyright © 2026 yiyisf