paseo-req-kit 1.13.0-beta.4 → 1.13.0

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

@@ -1 +0,0 @@
-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/reference_contracts_state.md.TRfzD5bc.js

@@ -1 +0,0 @@
-import{_ as d,o,c as t,a3 as c}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"state.json","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/state.md","filePath":"reference/contracts/state.md","lastUpdated":null}'),r={name:"reference/contracts/state.md"};function a(s,e,n,i,l,u){return o(),t("div",null,[...e[0]||(e[0]=[c('<div><h1 id="state-json" tabindex="-1">state.json <a class="header-anchor" href="#state-json" aria-label="Permalink to &quot;state.json&quot;">​</a></h1><p>流水线的运行状态，位于 <code>docs/features/&lt;目录&gt;/.pipeline/state.json</code>，只由引擎写入，不提交。</p><h2 id="当前格式-version-1" tabindex="-1">当前格式：version 1 <a class="header-anchor" href="#当前格式-version-1" aria-label="Permalink to &quot;当前格式：version 1&quot;">​</a></h2><table tabindex="0"><thead><tr><th>字段</th><th>类型</th><th>含义</th></tr></thead><tbody><tr><td><code>version</code></td><td>number</td><td>格式版本。没有这个字段的文件按 1 处理</td></tr><tr><td><code>repo</code></td><td>string</td><td>仓库目录（绝对路径）</td></tr><tr><td><code>featureDir</code></td><td>string</td><td>功能目录（相对路径，<code>/</code> 分隔）</td></tr><tr><td><code>status</code></td><td><code>running</code> | <code>waiting_for_business</code> | <code>failed</code> | <code>completed</code> | <code>phase_done</code> | <code>waiting_for_approval</code></td><td>当前状态。<code>waiting_for_business</code> 表示等待需求方决定；<code>phase_done</code>（1.7.0 起）表示研发阶段已完成、停在闸口等待测试验证；<code>waiting_for_approval</code>（1.8.0 起）表示方案已通过审核、等待需求方确认 <code>preview.md</code>，<code>--approve</code> 继续。旧引擎把不认识的状态当作可以继续的中断：<code>phase_done</code> 继续时直接做验证，<code>waiting_for_approval</code> 继续时不经确认直接写代码</td></tr><tr><td><code>attempt</code></td><td>number</td><td>第几次从方案设计开始</td></tr><tr><td><code>specHash</code></td><td>string</td><td>启动时 spec.md 的 sha256</td></tr><tr><td><code>originAgentId</code></td><td>string | null</td><td>发起对话的 agent，通知发往这里</td></tr><tr><td><code>pid</code></td><td>number</td><td>流水线进程</td></tr><tr><td><code>startedAt</code> / <code>updatedAt</code></td><td>ISO 时间</td><td></td></tr><tr><td><code>results</code></td><td>object</td><td>已完成步骤的结果，键为步骤键（如 <code>code_review-r2</code>）</td></tr><tr><td><code>history</code></td><td>array</td><td>每次步骤执行的记录：agent、起止时间、结果、错误；<code>usage</code>（可选，1.3.0 起）为 agent 报告的用量：<code>inputTokens</code>、<code>cachedInputTokens</code>、<code>outputTokens</code>、<code>totalCostUsd</code>，agent 没有报告时为 null 或缺少；<code>leftRunning</code>（可选，1.11 起）为 true 表示失败时 agent 可能还在运行，下一次运行这一步时先看它；<code>reattached</code>（可选，1.11 起）为接着等上一次 agent 的次数</td></tr><tr><td><code>stopReason</code> / <code>outcome</code></td><td>string | null</td><td>停止原因；最终结论</td></tr><tr><td><code>stopKind</code></td><td>string | null</td><td>可选，1.12 起。停下等人的原因代码：必要的决定 <code>approval</code>（确认方案）、<code>phase_gate</code>（研发完成，等待测试）、<code>business</code>（需求方决定）、<code>reproduce</code>（缺陷复现不了）；中断 <code>timeout</code>、<code>agent_error</code>、<code>invalid_result</code>、<code>transient</code>、<code>stopped</code>、<code>process_exit</code>、<code>budget</code>（1.13，用完 token 预算）、<code>other</code>。运行中或完成时为 null</td></tr><tr><td><code>budget</code></td><td>object</td><td>可选，1.13 起，配置了 <code>budget.tokens</code> 时。<code>{ allowance, warnedAt }</code>：停下前允许用到的 tokens（预算，每次用完后继续再加一份）；已经提醒过的那一档</td></tr><tr><td><code>waitingPermission</code></td><td>object | null</td><td>可选，1.13 起。步骤 agent 在等权限批准时：<code>{ agentId, stepTitle, requests, since }</code>；没有在等时为 null</td></tr><tr><td><code>recoveries</code></td><td>array</td><td>可选，1.12 起。流水线自己处理掉的问题（最多保留 200 条）：<code>at</code>、<code>key</code>（步骤键）、<code>kind</code>（<code>retry</code> 重试 / <code>reattach</code> 接着等上一次的 agent / <code>reuse_result</code> 沿用上一次 agent 的结果 / <code>extend_timeout</code> 超时后多等一轮 / <code>redo</code> 新开 agent 重做 / <code>fallback</code> 换备用模型 / <code>auto_resume</code> 预约自动继续 / <code>quota_wait</code> 预约在额度恢复后继续 / <code>self_answer</code> 方案审核的问题由 builder 自答）、<code>detail</code></td></tr><tr><td><code>profile</code></td><td><code>quick</code> | <code>standard</code></td><td>档位</td></tr><tr><td><code>branch</code></td><td>string | null</td><td>工作分支，启动时确定</td></tr><tr><td><code>milestones</code></td><td>string[]</td><td>已发送的进展通知，续跑时不重复发送</td></tr><tr><td><code>incremental</code></td><td>object | null</td><td>可选，1.3.0 起。需求变更或回答问题后的继续：<code>fromAttempt</code>（接着哪一次）、<code>reason</code>、<code>baseCommit</code>（本次开始时的提交，评审看这之后的改动）、<code>hadImplementation</code>（上一次是否已写过代码）。第一次运行和 <code>--restart</code> 为 null</td></tr><tr><td><code>worktree</code></td><td>object | null</td><td>可选，1.5.0 起。用 <code>--worktree</code> 启动、在为需求新建的工作区中开发时：<code>workspaceId</code>（Paseo 工作区）、<code>sourceRepo</code>（对话所在的目录）。此时 <code>repo</code> 是新工作区的目录</td></tr><tr><td><code>schedules</code></td><td>array</td><td>可选，1.6.0 起。这次运行创建的 Paseo 定时任务：<code>id</code>、<code>kind</code>（<code>reminder</code> 提醒 / <code>auto-resume</code> 自动继续 / <code>watchdog</code> 定时检查）、<code>at</code>。下一次运行或暂停命令会取消它们</td></tr><tr><td><code>autoResumes</code></td><td>object | null</td><td>可选，1.6.0 起。<code>attempt</code>、<code>count</code>：这次尝试已经预约过几次自动继续</td></tr><tr><td><code>queuedSince</code></td><td>string | null</td><td>可选，1.6.0 起。正在排队（<code>maxConcurrentPipelines</code>）时为开始排队的时间</td></tr><tr><td><code>phases</code></td><td>object | null</td><td>可选，1.7.0 起。这次运行的执行方式：<code>mode</code>（<code>continuous</code> / <code>gated</code> / <code>develop-only</code>）、<code>environment</code>（<code>local</code> / <code>deployed</code>）、<code>defects</code>（<code>fix</code> / <code>handback</code> / <code>report</code>）。没有时按 <code>continuous</code>、<code>local</code>、<code>fix</code> 处理</td></tr><tr><td><code>phase</code></td><td><code>develop</code> | <code>verify</code></td><td>可选，1.7.0 起。当前阶段。用字符串而不是编号，以后增加阶段不用改格式</td></tr><tr><td><code>verifyAt</code></td><td>string | null</td><td>可选，1.7.0 起。<code>--verify-at</code>：研发完成后在这个时间开始测试验证</td></tr><tr><td><code>handbacks</code></td><td>number</td><td>可选，1.7.0 起。测试验证把缺陷退回研发阶段的次数（<code>defects</code> 为 <code>handback</code>），上限为档位的 <code>defectFix</code> 轮数</td></tr><tr><td><code>type</code></td><td><code>defect</code> | <code>refactor</code> | <code>assessment</code> | null</td><td>可选，1.8.0 起。spec 中&quot;类型&quot;对应的做法；新需求、小改动和配置关掉的类型为 null</td></tr><tr><td><code>codeBase</code></td><td>object | null</td><td>可选，1.8.0 起。<code>attempt</code>、<code>commit</code>：这次尝试在改动任何代码之前的提交，质量门的基线和范围检查从这里比较。尝试开始时就已经写过代码的旧记录为 <code>commit: null</code></td></tr><tr><td><code>joint</code></td><td>array | null</td><td>可选，1.8.0 起。联合需求（spec 的 <code>- 联合开发：</code>）中其他仓库的工作区：<code>name</code>（<code>relatedRepos</code> 中的名称）、<code>slug</code>（步骤键的后缀，如 <code>implement@backend</code>）、<code>sourceRepo</code>（切出工作区的那份检出）、<code>repo</code>（工作区目录）、<code>workspaceId</code>、<code>branch</code>、<code>specHash</code>（最近一次同步过去的 spec），以及这个仓库自己的 <code>codeBase</code> 和 <code>gate</code>（格式同顶层）。见 ADR 0025</td></tr><tr><td><code>approval</code></td><td>object | null</td><td>可选，1.8.0 起。方案确认点：<code>attempt</code>（哪一次尝试的方案）、<code>status</code>（<code>waiting</code> / <code>approved</code>）、<code>at</code>。需求变更后的新尝试需要重新确认</td></tr><tr><td><code>external</code></td><td>object | null</td><td>可选，1.9.0 起。外部系统中的卡片，按集成名称：<code>id</code>（卡片编号）、<code>url</code>、<code>status</code>（最近设置的状态）、<code>syncedAt</code>、<code>pending</code>（没有成功、等待补发的调用：<code>action</code> 为 <code>create</code> / <code>status</code>、<code>event</code>、<code>status</code>、<code>at</code>、<code>attempts</code>、<code>error</code>）。见 ADR 0028</td></tr><tr><td><code>pushed</code></td><td>array | null</td><td>可选，1.10 起。从卡片开始、配置了 <code>push</code> 的需求推送过的分支，每个仓库一条（主仓库在前）：<code>repo</code>、<code>remote</code>、<code>branch</code>、<code>at</code>、<code>error</code>（成功时为 null）。见 ADR 0029</td></tr><tr><td><code>gate</code></td><td>object | null</td><td>可选，1.8.0 起。质量门：<code>baseline</code>（<code>attempt</code>、<code>commit</code>、<code>at</code>、<code>results</code>：每项检查改动前 <code>pass</code> / <code>fail</code>），<code>runs</code>（每次运行：<code>key</code> 步骤键、<code>attempt</code>、<code>at</code>、<code>checks</code>（<code>name</code>、<code>result</code>：<code>pass</code> / <code>fail</code> / <code>skipped</code>、<code>failedBefore</code>）、<code>newFailures</code>、<code>fixRounds</code>、<code>passed</code>）。各次运行的完整输出在 <code>.pipeline/checks/&lt;步骤键&gt;/</code></td></tr></tbody></table><p><code>schedules[].kind</code> 在 1.7.0 起还可能是 <code>verify-start</code>（<code>--verify-at</code> 预约的测试验证开始），1.8.0 起还可能是 <code>approval-continue</code>（方案确认超时后按方案继续，<code>designApproval.autoContinueHours</code>）。<code>history</code> 中每条步骤记录在 1.7.0 起有可选的 <code>phase</code>（<code>develop</code> / <code>verify</code>），用于按阶段统计用时与用量；没有时按研发阶段统计。</p><h2 id="迁移" tabindex="-1">迁移 <a class="header-anchor" href="#迁移" aria-label="Permalink to &quot;迁移&quot;">​</a></h2><p>只增加可选字段（缺少时按默认值处理，旧版本引擎读到也不出错）时不提升版本，以便回滚到旧版本后仍能继续已有的流水线；在上表中注明&quot;可选&quot;和起始版本即可。</p><p>引擎（<code>engine/src/state.ts</code>）中 <code>STATE_VERSION</code> 是当前版本，<code>STATE_MIGRATIONS[n]</code> 把第 n 版升级到第 n+1 版。增加必需字段或改变已有字段的含义时：</p><ol><li><code>STATE_VERSION</code> 加 1。</li><li>在 <code>STATE_MIGRATIONS</code> 中加一个从旧版本到新版本的函数，为旧文件补上默认值。</li><li>在 <code>engine/test/state.test.ts</code> 中加一条迁移测试，更新本文件。</li></ol></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/state.md">contracts/state.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/state.md">在 GitHub 上编辑</a></p>',2)])])}const h=d(r,[["render",a]]);export{m as __pageData,h as default};