paseo-req-kit 1.12.1 → 1.13.0-beta.2

package/site-dist/assets/guide_maintainer.md.RZIzyCTV.js

@@ -0,0 +1 @@
+import{_ as o,o as t,c as d,a3 as c}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"维护者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/maintainer.md","filePath":"guide/maintainer.md","lastUpdated":null}'),a={name:"guide/maintainer.md"};function r(s,e,i,n,l,p){return t(),d("div",null,[...e[0]||(e[0]=[c('<div><h1 id="维护者指南" tabindex="-1">维护者指南 <a class="header-anchor" href="#维护者指南" aria-label="Permalink to &quot;维护者指南&quot;">​</a></h1><p>面向维护 req-kit 本身的人：改提示词和 skill、发布新版本、处理复盘提交的问题。</p><h2 id="_1-改动之前" tabindex="-1">1. 改动之前 <a class="header-anchor" href="#_1-改动之前" aria-label="Permalink to &quot;1. 改动之前&quot;">​</a></h2><ul><li>先看 <a href="./../reference/scope">SCOPE.md</a> 和 <a href="https://github.com/yiyisf/paseo-req-kit/tree/main/.out-of-scope" target="_blank" rel="noreferrer">.out-of-scope/</a>：新提议须服务于&quot;帮助非专职开发的同事把一个需求从对齐做到可验收&quot;，至少有两个真实场景，并且无法通过项目配置或项目说明解决。</li><li>改动已有的设计决定（<a href="./../reference/adr/">docs/adr/</a>）时，新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。</li><li>改动文件格式（spec、状态文件、结果文件、决策记录等）时，同时更新 <a href="./../reference/contracts/">contracts/</a>、代码和测试；状态文件的格式变化要加迁移（见 <code>contracts/state.md</code>）。</li></ul><h2 id="_2-改-skill-和提示词的规则" tabindex="-1">2. 改 skill 和提示词的规则 <a class="header-anchor" href="#_2-改-skill-和提示词的规则" aria-label="Permalink to &quot;2. 改 skill 和提示词的规则&quot;">​</a></h2><ul><li><strong>入口不调用入口</strong>（ADR 0008）。<code>/req</code>、<code>/req-setup</code>、<code>/req-doctor</code>、<code>/req-retro</code> 之间只能&quot;告诉用户去运行&quot;，不能互相加载。</li><li><strong>路径用占位符</strong>：skill 中引用安装目录内的文件写 <code>{{REQ_KIT_ROOT}}/...</code>，启动命令写 <code>{{PIPELINE_LAUNCHER}}</code>，版本号写 <code>{{REQ_KIT_VERSION}}</code>。安装器会替换它们；<code>npm test</code> 会检查引用的文件都存在。</li><li><strong>frontmatter</strong> 只用 <code>name</code>、<code>description</code>，agent 专属的放在 <code>metadata</code> 下；<code>description</code> 中不要出现半角的 <code>: </code>。</li><li><strong>手册</strong>（<code>skills/req/playbooks/*.md</code>）开头必须有&quot;## 步骤&quot;编号列表，<code>/req</code> 会把它原样放进待办列表；新增手册要加进 <code>/req</code> 的路由表。</li><li><strong>原则</strong>：增加一条原则需要至少两次真实失误作为依据，并且无法用 CI 或配置解决；总数不超过 10 条。原则的一句话版本写进 <code>principles/INDEX.md</code>，它同时被聊天和每个步骤的提示词使用。</li><li><strong>措辞</strong>：读者是有技术背景、但不读代码的使用者（测试、产品、项目经理）。讲需求和结果，不讲代码实现。</li></ul><h2 id="_3-验证改动" tabindex="-1">3. 验证改动 <a class="header-anchor" href="#_3-验证改动" aria-label="Permalink to &quot;3. 验证改动&quot;">​</a></h2><table tabindex="0"><thead><tr><th>改了什么</th><th>至少要做</th></tr></thead><tbody><tr><td>引擎代码</td><td><code>npm test</code>、<code>npm run typecheck</code></td></tr><tr><td>步骤提示词</td><td>上面两项 + <code>npm run eval</code>（至少跑受影响的用例），与上一次的结果对比</td></tr><tr><td>入口、手册、方法 skill、原则</td><td><code>npm test</code> + 对话评估中受影响的剧本（<code>evals/conversation/</code>）</td></tr><tr><td>安装器</td><td><code>npm test</code>（在临时 HOME 中测试），并在 Windows 上实际装一次</td></tr><tr><td>评估用例</td><td><code>npm run eval:self-check</code>（参考实现必须通过隐藏验收）</td></tr><tr><td>Paseo 插件（<code>paseo-plugin/</code>）</td><td><code>npm test</code>（插件后台和 <code>req plugin</code>）；在 <code>paseo-plugin/</code> 中 <code>npm install &amp;&amp; npm run typecheck</code>（CI 的 plugin 任务也会做）；用 <code>req plugin install</code> 装到一台 Paseo 上，在网页端和手机宽度下看一遍，切换一次深色主题</td></tr></tbody></table><p>提示词改动以评估结果为准：如实率（不夸大）不能下降；隐藏验收通过率、用时、轮次与上一次对比，变差时说明原因。</p><h2 id="_4-发布" tabindex="-1">4. 发布 <a class="header-anchor" href="#_4-发布" aria-label="Permalink to &quot;4. 发布&quot;">​</a></h2><p>版本号遵循语义化版本，标签<strong>不带 <code>v</code> 前缀</strong>（例如 <code>1.2.0</code>、<code>1.3.0-beta.1</code>）。</p><ol><li><strong>确定版本号</strong>：修订号（修复、措辞调整）、次版本号（新手册、新配置项，完全兼容）、主版本号（文件格式、配置字段或入口名称的不兼容变化）。同一主版本内，配置字段只增不删（废弃的继续生效并在 <code>/req-doctor</code> 中提示），文件格式只做可以自动迁移的变更。</li><li><strong>更新 <code>package.json</code> 的 <code>version</code></strong>；Paseo 支持范围有变化时同时更新 <code>reqKit.paseo</code>，并复查 <code>engine/src/paseo-runtime.ts</code> 开头列出的 SDK 用法（其中工作区脚本用的是内部接口，见 ADR 0017）。</li><li><strong>写 <code>CHANGELOG.md</code></strong>：新增一节，分&quot;使用者会看到的变化&quot;和&quot;升级须知&quot;两部分。升级须知写清：要不要重跑 <code>/req-setup</code>、提示词有哪些变化（影响用 <code>prompts.local/</code> 覆盖过的人）、文件格式有没有变化、旧行为的兼容方式。</li><li><strong>验证</strong>：<code>npm test</code>、<code>npm run typecheck</code>、<code>npm run eval:self-check</code>；步骤提示词或引擎有改动时跑 <code>npm run eval</code>，把 <code>summary.md</code> 复制到 <code>evals/baselines/&lt;版本&gt;.md</code>；入口或手册有改动时跑对话评估，记入记分表。主版本发布前，在一个真实项目里试运行一周。</li><li><strong>冒烟测试</strong>：在一台干净的机器（或临时的 <code>REQ_KIT_HOME</code> 和 HOME）上按 <a href="./install">安装与升级</a> 安装，跑冒烟测试第 1–4 项；至少有一台是 Windows。</li><li><strong>合并到 <code>main</code>，标签自动打上</strong>：<code>main</code> 收到 <code>package.json</code> 版本号还没有标签的提交时，<code>.github/workflows/release.yml</code> 先在这个提交上跑测试、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 <code>main</code> 就会用同一个版本号重新发布（1.12.1 起；1.13 起任何推到 <code>main</code> 的提交都会检查，不必再改 <code>package.json</code>）。也可以照旧自己打：在 GitHub 上建 Release 并新建标签 <code>&lt;版本&gt;</code>，或推送 <code>git tag -a &lt;版本&gt;</code>，同样会触发发布。发布流程：跑测试、类型检查和评估自检，核对标签与 <code>package.json</code> 版本一致，然后发布到 npm（预发布版用 <code>beta</code> 标签，正式版用 <code>latest</code>），正式版再设置 <code>paseo-&lt;小版本&gt;</code> 标签，把 <code>npm pack</code> 的安装包附在 Release 上，Release 正文取自 CHANGELOG 的这一节。标签同时也是 git 方式安装的版本列表，所以改版本号的提交要在验证完成后再合到 <code>main</code>（自动打标签的时机就是它）；打错了尽快删除标签，npm 上发布错的版本用 <code>npm deprecate</code> 标注（npm 不允许重新发布同一版本号）。</li><li><strong>通知</strong>：把&quot;使用者会看到的变化&quot;发给使用者，把&quot;升级须知&quot;发给各台机器的安装者；团队配置的 <code>requiredVersion</code> 需要提高时，在团队配置仓库中修改。</li></ol><p><strong>npm 发布的一次性设置</strong>：可信发布（trusted publisher）要在 npm 上已有的包的设置页里配置，所以第一个版本在本机手工发布一次，不需要生成任何口令：</p><ol><li>npmjs.com 账号开启双重验证（2FA）；本机 <code>npm login</code>。</li><li>等版本标签的工作流跑到&quot;Publish&quot;（第一次会因为包不存在而失败，前面的测试已经通过），从仓库取出这个标签：<code>git checkout &lt;版本&gt;</code>，执行 <code>npm publish --tag beta --provenance=false</code>（正式版去掉 <code>--tag beta</code>）。本机不能生成来源证明，所以要关掉 provenance；以后由工作流发布的版本会自动带上。</li><li>在 npmjs.com 打开包的 Settings → Trusted publishing，选 GitHub Actions：Organization or user 填 <code>yiyisf</code>，Repository 填 <code>paseo-req-kit</code>，Workflow filename 填 <code>release.yml</code>，Environment 留空，允许的操作勾上 <code>npm publish</code>（和 <code>npm dist-tag</code>）。保存后 2 天内要有一次成功的发布，否则配置失效需要重建。</li><li>到 GitHub Actions 中重新运行这个标签的 release 工作流：版本已经在 npm 上，会跳过发布，只建 GitHub Release。之后的版本推送标签即可自动发布。</li></ol><p>不建议为发布生成长期口令：npm 正在收紧可以跳过 2FA 的口令，计划 2027 年 1 月起不再允许它们直接发布。工作流仍然支持仓库 Secrets 中的 <code>NPM_TOKEN</code>（有就用），供无法用可信发布的内网仓库使用。</p><p><strong>重新发布已有的标签</strong>：GitHub → Actions → release → Run workflow，填版本标签（如 <code>1.7.0-beta.2</code>）。用的是当前 main 上的流程、标签上的代码；手机网页也能操作。npm 发布失败时仍会建好 Release 和 <code>.tgz</code>，最后再报错。</p><p><strong>检查</strong>：<code>ci.yml</code> 在每次推送到 main 和每个 PR 时运行测试、类型检查、评估自检和打包检查。推送版本标签前先确认它是绿的。<code>paseo-&lt;小版本&gt;</code> 标签的设置需要一个口令：在仓库的 Secrets 中加 <code>NPM_TOKEN</code>（自动化口令）；不加时工作流会提示手工执行 <code>npm dist-tag add</code>。<code>req upgrade</code> 按各版本声明的 <code>reqKit.paseo</code> 选择版本，不依赖这个标签。</p><p><strong>维护分支</strong>：Paseo 出了新的小版本、<code>main</code> 跟进之后，从上一个支持线的最后版本拉出 <code>release/paseo-&lt;小版本&gt;</code> 分支，只合修复，在那里打补丁版本的标签（工作流会把它标成 <code>paseo-&lt;小版本&gt;</code>）；同时在 <code>package.json</code> 中加 <code>&quot;publishConfig&quot;: { &quot;tag&quot;: &quot;paseo-&lt;小版本&gt;&quot; }</code>，避免补丁版本抢走 <code>latest</code>。只维护最新和上一条支持线。</p><p><strong>企业私有仓库</strong>：只代理 npmjs 的不用做什么。需要单独发布到内网仓库时，下载 Release 上的 <code>.tgz</code>，执行 <code>npm publish paseo-req-kit-&lt;版本&gt;.tgz --registry &lt;内网地址&gt; --tag &lt;同名标签&gt;</code>，再在内网仓库设置相同的 <code>paseo-&lt;小版本&gt;</code> 标签。</p><p>没有使用 changesets 等发布工具（见 ADR 0013）：发布频率低，CHANGELOG 由人写更贴近使用者。</p><p><strong>对外约定</strong>：通知事件（<code>contracts/notifier-event.md</code>）由各团队自己的 IM 模块读取，同一 <code>schema</code> 内只增加字段；<code>req</code> 的子命令和参数会被写进各团队的使用说明，改名时保留旧名一个主版本。<code>req api</code> 的输出（<code>contracts/cli-json.md</code>）是插件和脚本读取的格式，同一 <code>schema</code> 内只增加字段。</p><h2 id="_5-处理复盘提交的问题" tabindex="-1">5. 处理复盘提交的问题 <a class="header-anchor" href="#_5-处理复盘提交的问题" aria-label="Permalink to &quot;5. 处理复盘提交的问题&quot;">​</a></h2><p><code>/req-retro</code> 会把 req-kit 本身的问题写成报告草稿交给用户。收到后：</p><ol><li>能复现的，先加一个评估用例或对话剧本，确认它在当前版本失败。</li><li>修改后跑同一个评估，确认修好，并且其他用例没有变差。</li><li>在 CHANGELOG 中记录。</li></ol><h2 id="_6-目录速查" tabindex="-1">6. 目录速查 <a class="header-anchor" href="#_6-目录速查" aria-label="Permalink to &quot;6. 目录速查&quot;">​</a></h2><table tabindex="0"><thead><tr><th>目录</th><th>内容</th></tr></thead><tbody><tr><td><code>skills/</code></td><td>安装到各 agent 的 skill：入口、手册、方法、原则、旧入口的引导</td></tr><tr><td><code>principles/INDEX.md</code></td><td>原则索引</td></tr><tr><td><code>engine/src/</code></td><td>引擎：启动器、主流程、配置、状态与迁移、体检、评估运行器</td></tr><tr><td><code>engine/prompts/</code></td><td>步骤提示词（含 <code>00-shared-context.md</code> 和评审小组成员的 <code>panel-member.md</code>）</td></tr><tr><td><code>engine/test/</code></td><td>引擎测试，<code>fake-runtime.ts</code> 是模拟的 Paseo</td></tr><tr><td><code>test/</code></td><td>安装器、体检、skill 的测试</td></tr><tr><td><code>evals/</code></td><td>评估：样例仓库、用例、对话剧本</td></tr><tr><td><code>contracts/</code></td><td>文件格式约定</td></tr><tr><td><code>docs/adr/</code></td><td>设计决定</td></tr><tr><td><code>paseo-plugin/</code></td><td>Paseo 插件：<code>client/</code>（界面，React Native）、<code>server/</code>（daemon 侧，运行 <code>req api</code>）、<code>shared/</code>（RPC 约定）。版本号与根目录的 <code>package.json</code> 相同，升版本时两处一起改</td></tr></tbody></table></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/guide/维护者指南.md">docs/guide/维护者指南.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/guide/维护者指南.md">在 GitHub 上编辑</a></p>',2)])])}const u=o(a,[["render",r]]);export{g as __pageData,u as default};

package/site-dist/assets/guide_maintainer.md.RZIzyCTV.lean.js

@@ -0,0 +1 @@
+import{_ as o,o as t,c as d,a3 as c}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"维护者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/maintainer.md","filePath":"guide/maintainer.md","lastUpdated":null}'),a={name:"guide/maintainer.md"};function r(s,e,i,n,l,p){return t(),d("div",null,[...e[0]||(e[0]=[c("",2)])])}const u=o(a,[["render",r]]);export{g as __pageData,u as default};

package/site-dist/assets/guide_phases.md.BpGAb1re.js

@@ -0,0 +1 @@
+import{_ as e,o as d,c as o,a3 as a}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"分阶段执行与提测","description":"","frontmatter":{},"headers":[],"relativePath":"guide/phases.md","filePath":"guide/phases.md","lastUpdated":1791966569000}'),s={name:"guide/phases.md"};function i(r,t,n,l,c,h){return d(),o("div",null,[...t[0]||(t[0]=[a('<h1 id="分阶段执行与提测" tabindex="-1">分阶段执行与提测 <a class="header-anchor" href="#分阶段执行与提测" aria-label="Permalink to &quot;分阶段执行与提测&quot;">​</a></h1><p>研发和测试常常是两拨人、两个节奏：研发完成要&quot;提测&quot;，测试同事先部署测试环境、准备数据，再验证，或者干脆人工测试。req-kit 把第 3–11 步分成<strong>研发</strong>和<strong>测试验证</strong>两个阶段，中间一个闸口。</p><h2 id="三种执行方式" tabindex="-1">三种执行方式 <a class="header-anchor" href="#三种执行方式" aria-label="Permalink to &quot;三种执行方式&quot;">​</a></h2><table tabindex="0"><thead><tr><th>执行方式</th><th>研发完成时</th><th>适合</th></tr></thead><tbody><tr><td><strong>连续</strong>（默认）</td><td>写好提测说明后直接进入测试验证</td><td>本地就能验证的项目</td></tr><tr><td><strong>分阶段</strong></td><td>停下来通知&quot;研发完成，可以提测&quot;，等人说&quot;开始测试验证&quot;或到预约的时间</td><td>有专门测试、需要先部署测试环境</td></tr><tr><td><strong>只做研发</strong></td><td>写提测说明和研发报告后结束，测试由人完成</td><td>测试必须由人完成</td></tr></tbody></table><p>标准档的需求在确定档位时，<code>/req</code> 会问执行方式（项目配置里定好了就不问），写进需求说明头部：<code>- 执行方式：分阶段</code>。团队可以在项目配置中统一设置：</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;phases&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;mode&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gated&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } }</span></span></code></pre></div><h2 id="提测说明" tabindex="-1">提测说明 <a class="header-anchor" href="#提测说明" aria-label="Permalink to &quot;提测说明&quot;">​</a></h2><p>研发阶段的最后一步写 <code>handoff.md</code>，三种方式都写：</p><ol><li>这次改了什么（按功能需求列出，附分支和提交范围）</li><li>怎么跑起来（依赖、迁移、配置项、启动命令）</li><li>自测结果（测试、代码评审结论、哪些验收标准已有自动化测试）</li><li>建议重点测试（风险最高的验收标准、回归范围）</li><li>已知问题和未完成项</li><li>测试需要的准备（数据、账号、开关——只写在哪里取，不写口令）</li></ol><h2 id="开始测试验证" tabindex="-1">开始测试验证 <a class="header-anchor" href="#开始测试验证" aria-label="Permalink to &quot;开始测试验证&quot;">​</a></h2><p>收到&quot;研发完成，可以提测&quot;后，在对话中说&quot;开始测试验证&quot;。AI 会讲一遍提测说明，然后确定：</p><ul><li><strong>在哪里验证</strong>：本地启动服务，或<strong>已部署的测试环境</strong>。后者需要和你一起写 <code>test-env.md</code>（地址、如何确认被测版本、账号和口令从哪里取、可用的测试数据）。</li><li><strong>发现缺陷怎么办</strong>：当场修复并复验；<strong>退回研发</strong>（只记录缺陷，回到研发阶段修复、经过代码评审后重新提测）；或只记录。</li></ul><p>也可以预约：启动时加 <code>--verify-at 22:00</code>，研发完成后到时自动开始；或在开始命令后加 <code>--at</code>。</p><h2 id="测试同事接手" tabindex="-1">测试同事接手 <a class="header-anchor" href="#测试同事接手" aria-label="Permalink to &quot;测试同事接手&quot;">​</a></h2><p>用&quot;开发时自动新建工作区&quot;开发的需求，研发完成后，测试同事可以在这个项目<strong>任何工作区</strong>的对话中输入：</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>/req 开始测试验证 sms-login</span></span></code></pre></div><p>之后的通知发到测试同事的对话，步骤仍在需求自己的工作区中运行。研发阶段仍然只能从发起的对话操作。</p><h2 id="相关配置" tabindex="-1">相关配置 <a class="header-anchor" href="#相关配置" aria-label="Permalink to &quot;相关配置&quot;">​</a></h2><table tabindex="0"><thead><tr><th>配置</th><th>默认</th><th>作用</th></tr></thead><tbody><tr><td><code>phases.mode</code></td><td><code>continuous</code></td><td>执行方式：<code>continuous</code> / <code>gated</code> / <code>develop-only</code></td></tr><tr><td><code>phases.verify.environment</code></td><td><code>local</code></td><td><code>deployed</code>：对已部署的测试环境验证</td></tr><tr><td><code>phases.verify.agents</code></td><td><code>{}</code></td><td>测试阶段用的 agent，例如 <code>{ &quot;reviewer&quot;: { &quot;paseoProfile&quot;: &quot;测试&quot; } }</code></td></tr><tr><td><code>phases.verify.defects</code></td><td><code>fix</code></td><td><code>fix</code> / <code>handback</code> / <code>report</code></td></tr><tr><td><code>phases.verify.serviceStart</code></td><td><code>null</code></td><td>测试阶段是否做服务启动验证；<code>null</code> 按档位</td></tr></tbody></table><p>设计决定见 <a href="/reference/adr/0022-develop-and-verify-phases">ADR 0022</a>。</p>',20)])])}const g=e(s,[["render",i]]);export{u as __pageData,g as default};

package/site-dist/assets/guide_phases.md.BpGAb1re.lean.js

@@ -0,0 +1 @@
+import{_ as e,o as d,c as o,a3 as a}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"分阶段执行与提测","description":"","frontmatter":{},"headers":[],"relativePath":"guide/phases.md","filePath":"guide/phases.md","lastUpdated":1791966569000}'),s={name:"guide/phases.md"};function i(r,t,n,l,c,h){return d(),o("div",null,[...t[0]||(t[0]=[a("",20)])])}const g=e(s,[["render",i]]);export{u as __pageData,g as default};