维护者指南

面向维护 req-kit 本身的人：改提示词和 skill、发布新版本、处理复盘提交的问题。

1. 改动之前

• 先看 SCOPE.md 和 .out-of-scope/：新提议须服务于"帮助非专职开发的同事把一个需求从对齐做到可验收"，至少有两个真实场景，并且无法通过项目配置或项目说明解决。
• 改动已有的设计决定（docs/adr/）时，新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。
• 界面的颜色、字体、组件按 design/（设计规范，见其中的 README）来；改了 design/tokens.json、design/reference/components.css 或 design/examples/icons.js，运行 node scripts/tokens-build.mjs 更新审查网页里的副本。
• 改动文件格式（spec、状态文件、结果文件、决策记录等）时，同时更新 contracts/、代码和测试；状态文件的格式变化要加迁移（见 contracts/state.md）。

2. 改 skill 和提示词的规则

• 入口不调用入口（ADR 0008）。/req、/req-setup、/req-doctor、/req-retro 之间只能"告诉用户去运行"，不能互相加载。
• 路径用占位符：skill 中引用安装目录内的文件写 {{REQ_KIT_ROOT}}/...，启动命令写 {{PIPELINE_LAUNCHER}}，版本号写 {{REQ_KIT_VERSION}}。安装器会替换它们；npm test 会检查引用的文件都存在。
• frontmatter 只用 name、description，agent 专属的放在 metadata 下；description 中不要出现半角的 : 。
• 手册（skills/req/playbooks/*.md）开头必须有"## 步骤"编号列表，/req 会把它原样放进待办列表；新增手册要加进 /req 的路由表。
• 原则：增加一条原则需要至少两次真实失误作为依据，并且无法用 CI 或配置解决；总数不超过 10 条。原则的一句话版本写进 principles/INDEX.md，它同时被聊天和每个步骤的提示词使用。
• 措辞：读者是有技术背景、但不读代码的使用者（测试、产品、项目经理）。讲需求和结果，不讲代码实现。

3. 验证改动

改了什么	至少要做
引擎代码	npm test、npm run typecheck
步骤提示词	上面两项 + npm run eval（至少跑受影响的用例），与上一次的结果对比
入口、手册、方法 skill、原则	npm test + 对话评估中受影响的剧本（evals/conversation/）
安装器	npm test（在临时 HOME 中测试），并在 Windows 上实际装一次
评估用例	npm run eval:self-check（参考实现必须通过隐藏验收）
Paseo 插件（paseo-plugin/）	npm test（插件后台和 req plugin）；在 paseo-plugin/ 中 npm install && npm run typecheck（CI 的 plugin 任务也会做）；用 req plugin install 装到一台 Paseo 上，在网页端和手机宽度下看一遍，切换一次深色主题

提示词改动以评估结果为准：如实率（不夸大）不能下降；隐藏验收通过率、用时、轮次与上一次对比，变差时说明原因。

4. 发布

版本号遵循语义化版本，标签不带 v 前缀（例如 1.2.0、1.3.0-beta.1）。

1. 确定版本号：修订号（修复、措辞调整）、次版本号（新手册、新配置项，完全兼容）、主版本号（文件格式、配置字段或入口名称的不兼容变化）。同一主版本内，配置字段只增不删（废弃的继续生效并在 /req-doctor 中提示），文件格式只做可以自动迁移的变更。
2. 更新 package.json 的 version；Paseo 支持范围有变化时同时更新 reqKit.paseo，并复查 engine/src/paseo-runtime.ts 开头列出的 SDK 用法（其中工作区脚本用的是内部接口，见 ADR 0017）。
3. 写 CHANGELOG.md：新增一节，分"使用者会看到的变化"和"升级须知"两部分。升级须知写清：要不要重跑 /req-setup、提示词有哪些变化（影响用 prompts.local/ 覆盖过的人）、文件格式有没有变化、旧行为的兼容方式。
4. 验证：npm test、npm run typecheck、npm run eval:self-check；步骤提示词或引擎有改动时跑 npm run eval，把 summary.md 复制到 evals/baselines/<版本>.md；入口或手册有改动时跑对话评估，记入记分表。主版本发布前，在一个真实项目里试运行一周。
5. 冒烟测试：在一台干净的机器（或临时的 REQ_KIT_HOME 和 HOME）上按 安装与升级 安装，跑冒烟测试第 1–4 项；至少有一台是 Windows。
6. 合并到 main，标签自动打上：main 收到 package.json 版本号还没有标签的提交时，.github/workflows/release.yml 先在这个提交上跑测试（Linux 和 Windows 各一遍，1.13 起）、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 main 就会用同一个版本号重新发布（1.12.1 起；1.13 起任何推到 main 的提交都会检查，不必再改 package.json）。也可以照旧自己打：在 GitHub 上建 Release 并新建标签 <版本>，或推送 git tag -a <版本>，同样会触发发布。发布流程：跑测试、类型检查和评估自检，核对标签与 package.json 版本一致，然后发布到 npm（预发布版用 beta 标签，正式版用 latest），正式版再设置 paseo-<小版本> 标签，把 npm pack 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以改版本号的提交要在验证完成后再合到 main（自动打标签的时机就是它）；打错了尽快删除标签，npm 上发布错的版本用 npm deprecate 标注（npm 不允许重新发布同一版本号）。
7. 通知：把"使用者会看到的变化"发给使用者，把"升级须知"发给各台机器的安装者；团队配置的 requiredVersion 需要提高时，在团队配置仓库中修改。

npm 发布的一次性设置：可信发布（trusted publisher）要在 npm 上已有的包的设置页里配置，所以第一个版本在本机手工发布一次，不需要生成任何口令：

1. npmjs.com 账号开启双重验证（2FA）；本机 npm login。
2. 等版本标签的工作流跑到"Publish"（第一次会因为包不存在而失败，前面的测试已经通过），从仓库取出这个标签：git checkout <版本>，执行 npm publish --tag beta --provenance=false（正式版去掉 --tag beta）。本机不能生成来源证明，所以要关掉 provenance；以后由工作流发布的版本会自动带上。
3. 在 npmjs.com 打开包的 Settings → Trusted publishing，选 GitHub Actions：Organization or user 填 yiyisf，Repository 填 paseo-req-kit，Workflow filename 填 release.yml，Environment 留空，允许的操作勾上 npm publish（和 npm dist-tag）。保存后 2 天内要有一次成功的发布，否则配置失效需要重建。
4. 到 GitHub Actions 中重新运行这个标签的 release 工作流：版本已经在 npm 上，会跳过发布，只建 GitHub Release。之后的版本推送标签即可自动发布。

不建议为发布生成长期口令：npm 正在收紧可以跳过 2FA 的口令，计划 2027 年 1 月起不再允许它们直接发布。工作流仍然支持仓库 Secrets 中的 NPM_TOKEN（有就用），供无法用可信发布的内网仓库使用。

正式版的海报和幻灯片（1.15 起）：正式版发布时，工作流用 scripts/release-media.mjs 从 CHANGELOG 的这一节生成竖版海报（1080×1920 PNG）、群聊卡片（1200×630 PNG）和汇报幻灯片（1920×1080 PDF，附可编辑的 HTML），附在 GitHub Release 上，文件名 req-kit-<版本>-poster.png、-card.png、-slides.pdf、-slides.html。内容取自这一节：第一段（"稳定版：……"）是导语，"使用者会看到的变化"里每条开头的加粗文字是一项变化（"修复："开头的排在最后），"升级须知"单独一页；测试数取自这次发布跑的测试，版本数、设计决定记录数从仓库数。标题默认是版本号，想写一句口号就在 design/releases/<版本>.json 里写 title（\n 换行，海报每行不超过 8 个字，*…* 是渐变关键词）、lead、card，在改版本号的同一个提交里加上。本机预览：node scripts/release-media.mjs <版本> --render（需要 Playwright，用 PLAYWRIGHT_DIR 指向它的目录），输出在 release-media/<版本>/。这一步失败不影响发布；beta 也会生成一遍用来检查，但不附在 Release 上。

重新发布已有的标签：GitHub → Actions → release → Run workflow，填版本标签（如 1.7.0-beta.2）。用的是当前 main 上的流程、标签上的代码；手机网页也能操作。npm 发布失败时仍会建好 Release 和 .tgz，最后再报错。

检查：ci.yml 在每次推送到 main 和每个 PR 时运行测试、类型检查、评估自检和打包检查。推送版本标签前先确认它是绿的。paseo-<小版本> 标签的设置需要一个口令：在仓库的 Secrets 中加 NPM_TOKEN（自动化口令）；不加时工作流会提示手工执行 npm dist-tag add。req upgrade 按各版本声明的 reqKit.paseo 选择版本，不依赖这个标签。

维护分支：Paseo 出了新的小版本、main 跟进之后，从上一个支持线的最后版本拉出 release/paseo-<小版本> 分支，只合修复，在那里打补丁版本的标签（工作流会把它标成 paseo-<小版本>）；同时在 package.json 中加 "publishConfig": { "tag": "paseo-<小版本>" }，避免补丁版本抢走 latest。只维护最新和上一条支持线。

企业私有仓库：只代理 npmjs 的不用做什么。需要单独发布到内网仓库时，下载 Release 上的 .tgz，执行 npm publish paseo-req-kit-<版本>.tgz --registry <内网地址> --tag <同名标签>，再在内网仓库设置相同的 paseo-<小版本> 标签。

没有使用 changesets 等发布工具（见 ADR 0013）：发布频率低，CHANGELOG 由人写更贴近使用者。

对外约定：通知事件（contracts/notifier-event.md）由各团队自己的 IM 模块读取，同一 schema 内只增加字段；req 的子命令和参数会被写进各团队的使用说明，改名时保留旧名一个主版本。req api 的输出（contracts/cli-json.md）是插件和脚本读取的格式，同一 schema 内只增加字段。

5. 处理复盘提交的问题

/req-retro 会把 req-kit 本身的问题写成报告草稿交给用户。收到后：

1. 能复现的，先加一个评估用例或对话剧本，确认它在当前版本失败。
2. 修改后跑同一个评估，确认修好，并且其他用例没有变差。
3. 在 CHANGELOG 中记录。

6. 目录速查

目录	内容
skills/	安装到各 agent 的 skill：入口、手册、方法、原则、旧入口的引导
principles/INDEX.md	原则索引
engine/src/	引擎：启动器、主流程、配置、状态与迁移、体检、评估运行器
engine/prompts/	步骤提示词（含 00-shared-context.md 和评审小组成员的 panel-member.md）
engine/test/	引擎测试，fake-runtime.ts 是模拟的 Paseo
test/	安装器、体检、skill 的测试
evals/	评估：样例仓库、用例、对话剧本
contracts/	文件格式约定
docs/adr/	设计决定
design/	界面设计规范：tokens、品牌手册、各界面规范、组件、效果图
paseo-plugin/	Paseo 插件：client/（界面，React Native）、server/（daemon 侧，运行 req api）、shared/（RPC 约定）。版本号与根目录的 package.json 相同，升版本时两处一起改

本页由仓库中的 docs/guide/维护者指南.md 生成。在 GitHub 上编辑