paseo-req-kit 1.15.0-beta.3 → 1.15.0

package/site-dist/assets/{guide_maintainer.md.SWALpGR5.js → guide_maintainer.md.CKt4mDvc.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as d,a2 as c}from"./chunks/framework.BetZR81g.js";const m=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,n,i,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>界面的颜色、字体、组件按 <code>design/</code>（设计规范，见其中的 README）来；改了 <code>design/tokens.json</code>、<code>design/reference/components.css</code> 或 <code>design/examples/icons.js</code>，运行 <code>node scripts/tokens-build.mjs</code> 更新审查网页里的副本。</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> 先在这个提交上跑测试（Linux 和 Windows 各一遍，1.13 起）、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 <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>design/</code></td><td>界面设计规范：tokens、品牌手册、各界面规范、组件、效果图</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{m as __pageData,u as default};
+import{_ as o,o as d,c as t,a2 as c}from"./chunks/framework.BetZR81g.js";const m=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,n,i,l,p){return d(),t("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>界面的颜色、字体、组件按 <code>design/</code>（设计规范，见其中的 README）来；改了 <code>design/tokens.json</code>、<code>design/reference/components.css</code> 或 <code>design/examples/icons.js</code>，运行 <code>node scripts/tokens-build.mjs</code> 更新审查网页里的副本。</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> 先在这个提交上跑测试（Linux 和 Windows 各一遍，1.13 起）、类型检查和评估自检，通过后才打上同名标签（不用自己打，也不需要推送标签的权限），接着在同一次运行里发布。测试没通过时不会留下标签，把修复合到 <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>（1.15 起）：正式版发布时，工作流用 <code>scripts/release-media.mjs</code> 从 CHANGELOG 的这一节生成竖版海报（1080×1920 PNG）、群聊卡片（1200×630 PNG）和汇报幻灯片（1920×1080 PDF，附可编辑的 HTML），附在 GitHub Release 上，文件名 <code>req-kit-&lt;版本&gt;-poster.png</code>、<code>-card.png</code>、<code>-slides.pdf</code>、<code>-slides.html</code>。内容取自这一节：第一段（&quot;稳定版：……&quot;）是导语，&quot;使用者会看到的变化&quot;里每条开头的加粗文字是一项变化（&quot;修复：&quot;开头的排在最后），&quot;升级须知&quot;单独一页；测试数取自这次发布跑的测试，版本数、设计决定记录数从仓库数。标题默认是版本号，想写一句口号就在 <code>design/releases/&lt;版本&gt;.json</code> 里写 <code>title</code>（<code>\\n</code> 换行，海报每行不超过 8 个字，<code>*…*</code> 是渐变关键词）、<code>lead</code>、<code>card</code>，在改版本号的同一个提交里加上。本机预览：<code>node scripts/release-media.mjs &lt;版本&gt; --render</code>（需要 Playwright，用 <code>PLAYWRIGHT_DIR</code> 指向它的目录），输出在 <code>release-media/&lt;版本&gt;/</code>。这一步失败不影响发布；beta 也会生成一遍用来检查，但不附在 Release 上。</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>design/</code></td><td>界面设计规范：tokens、品牌手册、各界面规范、组件、效果图</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{m as __pageData,u as default};

package/site-dist/assets/{guide_maintainer.md.SWALpGR5.lean.js → guide_maintainer.md.CKt4mDvc.lean.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as d,a2 as c}from"./chunks/framework.BetZR81g.js";const m=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,n,i,l,p){return t(),d("div",null,[...e[0]||(e[0]=[c("",2)])])}const u=o(a,[["render",r]]);export{m as __pageData,u as default};
+import{_ as o,o as d,c as t,a2 as c}from"./chunks/framework.BetZR81g.js";const m=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,n,i,l,p){return d(),t("div",null,[...e[0]||(e[0]=[c("",2)])])}const u=o(a,[["render",r]]);export{m as __pageData,u as default};