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

package/site-dist/assets/reference_contracts_state.md.TRfzD5bc.js

@@ -0,0 +1 @@
+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};

package/site-dist/assets/{reference_contracts_state.md.5bNTC3ow.lean.js → reference_contracts_state.md.TRfzD5bc.lean.js}

@@ -1 +1 @@
-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,p){return o(),t("div",null,[...e[0]||(e[0]=[c("",2)])])}const h=d(r,[["render",a]]);export{m as __pageData,h as default};
+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("",2)])])}const h=d(r,[["render",a]]);export{m as __pageData,h as default};

package/site-dist/assets/{reference_contracts_usage-record.md._C0OXWeq.js → reference_contracts_usage-record.md.DBMNY4OP.js}

@@ -1,4 +1,4 @@
-import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(r,s,o,u,h,c){return n(),t("div",null,[...s[0]||(s[0]=[l("div",null,[l("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[e("本机的需求索引与使用记录 "),l("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"​")]),l("p",null,[e("1.9.0 起，引擎在本机配置目录（默认 "),l("code",null,"~/.req-kit"),e("，可用 "),l("code",null,"REQ_KIT_HOME"),e(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),l("code",null,"REQ_KIT_NO_RECORD=1"),e(" 时两样都不记（评估运行就是这样）。")]),l("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[e("需求索引 "),l("code",null,"index/<key>.json"),e(),l("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"​")]),l("p",null,[e("每个在本机运行过的需求一个文件，记录它在哪里，供 "),l("code",null,"req api list --all"),e(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),e(`
+import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(o,s,r,u,c,h){return n(),t("div",null,[...s[0]||(s[0]=[l("div",null,[l("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[e("本机的需求索引与使用记录 "),l("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"​")]),l("p",null,[e("1.9.0 起，引擎在本机配置目录（默认 "),l("code",null,"~/.req-kit"),e("，可用 "),l("code",null,"REQ_KIT_HOME"),e(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),l("code",null,"REQ_KIT_NO_RECORD=1"),e(" 时两样都不记（评估运行就是这样）。")]),l("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[e("需求索引 "),l("code",null,"index/<key>.json"),e(),l("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"​")]),l("p",null,[e("每个在本机运行过的需求一个文件，记录它在哪里，供 "),l("code",null,"req api list --all"),e(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "schema"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "key"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"3f2a9c1e5b7d4e8a"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "repo"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop-sms-login"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
@@ -7,4 +7,4 @@ import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";c
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "workspaceId"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"ws_123"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "project"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"shop"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "registeredAt"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"2026-10-12T09:00:00.000Z"')]),e(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),l("p",null,[l("code",null,"key"),e(" 由对话所在的目录（没有自己的工作区时即 "),l("code",null,"repo"),e("）和功能目录算出。"),l("code",null,"req index --rebuild"),e(" 为 1.9 之前运行过的需求补登，"),l("code",null,"req index --prune"),e(" 移除目录已不在的。")]),l("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[e("使用记录 "),l("code",null,"usage/runs.jsonl"),e(),l("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"​")]),l("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"schema"),e(" / "),l("code",null,"kind")]),l("td",null,[l("code",null,"1"),e(" / "),l("code",null,'"run"')])]),l("tr",null,[l("td",null,[l("code",null,"machine"),e(" / "),l("code",null,"kitVersion")]),l("td",null,"主机名、req-kit 版本")]),l("tr",null,[l("td",null,[l("code",null,"requirement")]),l("td",null,[l("code",null,"{ key, project, name, title, type, profile }"),e("；从卡片开始的需求（1.10 起）另有 "),l("code",null,"requester"),e("（卡片的提出人）和 "),l("code",null,"source"),e("（"),l("code",null,"{ system, id }"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),e("；"),l("code",null,"status"),e(" 是运行结束时的状态，"),l("code",null,"outcome"),e(" 是完成时报告的结论；"),l("code",null,"stopKind"),e("（1.12 起）是停下等人的原因代码（见 "),l("a",{href:"./state"},"state.md"),e("），"),l("code",null,"recoveries"),e("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),l("code",null,'{ "retry": 2 }'),e("。更早的记录没有这两项")])]),l("tr",null,[l("td",null,[l("code",null,"agents")]),l("td",null,[l("code",null,"{ builder, reviewer }"),e("：当时配置的 agent（如 "),l("code",null,"claude/opus（bypassPermissions）"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("这次运行中开始的步骤："),l("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),e("；agent 没有报告的用量为 null")])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[l("code",null,"{ runs, failed }"),e("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),l("p",null,"不记录需求内容、代码和对话。"),l("h2",{id:"统计口径-req-stats",tabindex:"-1"},[e("统计口径（"),l("code",null,"req stats"),e("） "),l("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"​")]),l("ul",null,[l("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),l("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),l("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),l("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),l("li",null,[e("停下等人的原因（1.12 起）：这段时间结束的运行按 "),l("code",null,"stopKind"),e(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),l("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),l("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),l("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),l("p",null,[l("code",null,"req stats --json"),e(" 和 "),l("code",null,"req api stats"),e(" 输出同样的对象（"),l("code",null,"schema: 1"),e("）："),l("code",null,"period"),e("、"),l("code",null,"machines"),e("、"),l("code",null,"active"),e("、"),l("code",null,"completed"),e("、"),l("code",null,"byType"),e("、"),l("code",null,"cycleHours"),e("、"),l("code",null,"steps"),e("、"),l("code",null,"rework"),e("、"),l("code",null,"waits"),e("、"),l("code",null,"usage"),e("、"),l("code",null,"byBuilder"),e("、"),l("code",null,"requirements"),e("（每个需求一项，字段与 "),l("code",null,"req stats --csv"),e(" 的列对应）。")])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=i(a,[["render",d]]);export{p as __pageData,E as default};
+`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),l("p",null,[l("code",null,"key"),e(" 由对话所在的目录（没有自己的工作区时即 "),l("code",null,"repo"),e("）和功能目录算出。"),l("code",null,"req index --rebuild"),e(" 为 1.9 之前运行过的需求补登，"),l("code",null,"req index --prune"),e(" 移除目录已不在的。")]),l("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[e("使用记录 "),l("code",null,"usage/runs.jsonl"),e(),l("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"​")]),l("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"schema"),e(" / "),l("code",null,"kind")]),l("td",null,[l("code",null,"1"),e(" / "),l("code",null,'"run"')])]),l("tr",null,[l("td",null,[l("code",null,"machine"),e(" / "),l("code",null,"kitVersion")]),l("td",null,"主机名、req-kit 版本")]),l("tr",null,[l("td",null,[l("code",null,"requirement")]),l("td",null,[l("code",null,"{ key, project, name, title, type, profile }"),e("；从卡片开始的需求（1.10 起）另有 "),l("code",null,"requester"),e("（卡片的提出人）和 "),l("code",null,"source"),e("（"),l("code",null,"{ system, id }"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps[].cachedInputTokens"),e(" / "),l("code",null,"steps[].agent")]),l("td",null,'1.13 起。输入中来自提示缓存的 tokens（agent 报告时）；这一步用的 agent（Paseo profile 名，或 "provider/model"）。更早的记录没有')]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),e("；"),l("code",null,"status"),e(" 是运行结束时的状态，"),l("code",null,"outcome"),e(" 是完成时报告的结论；"),l("code",null,"stopKind"),e("（1.12 起）是停下等人的原因代码（见 "),l("a",{href:"./state"},"state.md"),e("），"),l("code",null,"recoveries"),e("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),l("code",null,'{ "retry": 2 }'),e("。更早的记录没有这两项")])]),l("tr",null,[l("td",null,[l("code",null,"agents")]),l("td",null,[l("code",null,"{ builder, reviewer }"),e("：当时配置的 agent（如 "),l("code",null,"claude/opus（bypassPermissions）"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("这次运行中开始的步骤："),l("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),e("；agent 没有报告的用量为 null")])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[l("code",null,"{ runs, failed }"),e("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),l("p",null,"不记录需求内容、代码和对话。"),l("h2",{id:"统计口径-req-stats",tabindex:"-1"},[e("统计口径（"),l("code",null,"req stats"),e("） "),l("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"​")]),l("ul",null,[l("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),l("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),l("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),l("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),l("li",null,[e("token 花在哪（1.13 起，"),l("code",null,"tokens"),e("）：这段时间的步骤按 "),l("code",null,"stepId"),e("、按 "),l("code",null,"agent"),e(" 合计 token（输入 + 输出）和占比；返工（"),l("code",null,"design_revise"),e("、"),l("code",null,"review_fix"),e("、"),l("code",null,"defect_fix"),e("、"),l("code",null,"reverify"),e("，以及 "),l("code",null,"design_review"),e("、"),l("code",null,"code_review"),e(" 第 2 轮起）的合计和占比；报告了 "),l("code",null,"cachedInputTokens"),e(" 的，算出输入中来自提示缓存的比例；已完成需求的 token 中位数（按档位）。")]),l("li",null,[e("停下等人的原因（1.12 起）：这段时间结束的运行按 "),l("code",null,"stopKind"),e(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),l("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),l("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),l("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),l("p",null,[l("code",null,"req stats --json"),e(" 和 "),l("code",null,"req api stats"),e(" 输出同样的对象（"),l("code",null,"schema: 1"),e("）："),l("code",null,"period"),e("、"),l("code",null,"machines"),e("、"),l("code",null,"active"),e("、"),l("code",null,"completed"),e("、"),l("code",null,"byType"),e("、"),l("code",null,"cycleHours"),e("、"),l("code",null,"steps"),e("、"),l("code",null,"rework"),e("、"),l("code",null,"waits"),e("、"),l("code",null,"usage"),e("、"),l("code",null,"byBuilder"),e("、"),l("code",null,"requirements"),e("（每个需求一项，字段与 "),l("code",null,"req stats --csv"),e(" 的列对应）。")])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=i(a,[["render",d]]);export{p as __pageData,E as default};

package/site-dist/assets/{reference_contracts_usage-record.md._C0OXWeq.lean.js → reference_contracts_usage-record.md.DBMNY4OP.lean.js}

@@ -1,4 +1,4 @@
-import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(r,s,o,u,h,c){return n(),t("div",null,[...s[0]||(s[0]=[l("div",null,[l("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[e("本机的需求索引与使用记录 "),l("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"​")]),l("p",null,[e("1.9.0 起，引擎在本机配置目录（默认 "),l("code",null,"~/.req-kit"),e("，可用 "),l("code",null,"REQ_KIT_HOME"),e(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),l("code",null,"REQ_KIT_NO_RECORD=1"),e(" 时两样都不记（评估运行就是这样）。")]),l("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[e("需求索引 "),l("code",null,"index/<key>.json"),e(),l("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"​")]),l("p",null,[e("每个在本机运行过的需求一个文件，记录它在哪里，供 "),l("code",null,"req api list --all"),e(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),e(`
+import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(o,s,r,u,c,h){return n(),t("div",null,[...s[0]||(s[0]=[l("div",null,[l("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[e("本机的需求索引与使用记录 "),l("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"​")]),l("p",null,[e("1.9.0 起，引擎在本机配置目录（默认 "),l("code",null,"~/.req-kit"),e("，可用 "),l("code",null,"REQ_KIT_HOME"),e(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),l("code",null,"REQ_KIT_NO_RECORD=1"),e(" 时两样都不记（评估运行就是这样）。")]),l("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[e("需求索引 "),l("code",null,"index/<key>.json"),e(),l("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"​")]),l("p",null,[e("每个在本机运行过的需求一个文件，记录它在哪里，供 "),l("code",null,"req api list --all"),e(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "schema"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "key"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"3f2a9c1e5b7d4e8a"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "repo"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop-sms-login"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
@@ -7,4 +7,4 @@ import{_ as i,o as n,c as t,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";c
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "workspaceId"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"ws_123"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "project"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"shop"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
 `),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "registeredAt"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"2026-10-12T09:00:00.000Z"')]),e(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),l("p",null,[l("code",null,"key"),e(" 由对话所在的目录（没有自己的工作区时即 "),l("code",null,"repo"),e("）和功能目录算出。"),l("code",null,"req index --rebuild"),e(" 为 1.9 之前运行过的需求补登，"),l("code",null,"req index --prune"),e(" 移除目录已不在的。")]),l("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[e("使用记录 "),l("code",null,"usage/runs.jsonl"),e(),l("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"​")]),l("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"schema"),e(" / "),l("code",null,"kind")]),l("td",null,[l("code",null,"1"),e(" / "),l("code",null,'"run"')])]),l("tr",null,[l("td",null,[l("code",null,"machine"),e(" / "),l("code",null,"kitVersion")]),l("td",null,"主机名、req-kit 版本")]),l("tr",null,[l("td",null,[l("code",null,"requirement")]),l("td",null,[l("code",null,"{ key, project, name, title, type, profile }"),e("；从卡片开始的需求（1.10 起）另有 "),l("code",null,"requester"),e("（卡片的提出人）和 "),l("code",null,"source"),e("（"),l("code",null,"{ system, id }"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),e("；"),l("code",null,"status"),e(" 是运行结束时的状态，"),l("code",null,"outcome"),e(" 是完成时报告的结论；"),l("code",null,"stopKind"),e("（1.12 起）是停下等人的原因代码（见 "),l("a",{href:"./state"},"state.md"),e("），"),l("code",null,"recoveries"),e("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),l("code",null,'{ "retry": 2 }'),e("。更早的记录没有这两项")])]),l("tr",null,[l("td",null,[l("code",null,"agents")]),l("td",null,[l("code",null,"{ builder, reviewer }"),e("：当时配置的 agent（如 "),l("code",null,"claude/opus（bypassPermissions）"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("这次运行中开始的步骤："),l("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),e("；agent 没有报告的用量为 null")])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[l("code",null,"{ runs, failed }"),e("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),l("p",null,"不记录需求内容、代码和对话。"),l("h2",{id:"统计口径-req-stats",tabindex:"-1"},[e("统计口径（"),l("code",null,"req stats"),e("） "),l("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"​")]),l("ul",null,[l("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),l("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),l("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),l("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),l("li",null,[e("停下等人的原因（1.12 起）：这段时间结束的运行按 "),l("code",null,"stopKind"),e(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),l("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),l("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),l("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),l("p",null,[l("code",null,"req stats --json"),e(" 和 "),l("code",null,"req api stats"),e(" 输出同样的对象（"),l("code",null,"schema: 1"),e("）："),l("code",null,"period"),e("、"),l("code",null,"machines"),e("、"),l("code",null,"active"),e("、"),l("code",null,"completed"),e("、"),l("code",null,"byType"),e("、"),l("code",null,"cycleHours"),e("、"),l("code",null,"steps"),e("、"),l("code",null,"rework"),e("、"),l("code",null,"waits"),e("、"),l("code",null,"usage"),e("、"),l("code",null,"byBuilder"),e("、"),l("code",null,"requirements"),e("（每个需求一项，字段与 "),l("code",null,"req stats --csv"),e(" 的列对应）。")])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=i(a,[["render",d]]);export{p as __pageData,E as default};
+`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),l("p",null,[l("code",null,"key"),e(" 由对话所在的目录（没有自己的工作区时即 "),l("code",null,"repo"),e("）和功能目录算出。"),l("code",null,"req index --rebuild"),e(" 为 1.9 之前运行过的需求补登，"),l("code",null,"req index --prune"),e(" 移除目录已不在的。")]),l("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[e("使用记录 "),l("code",null,"usage/runs.jsonl"),e(),l("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"​")]),l("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"schema"),e(" / "),l("code",null,"kind")]),l("td",null,[l("code",null,"1"),e(" / "),l("code",null,'"run"')])]),l("tr",null,[l("td",null,[l("code",null,"machine"),e(" / "),l("code",null,"kitVersion")]),l("td",null,"主机名、req-kit 版本")]),l("tr",null,[l("td",null,[l("code",null,"requirement")]),l("td",null,[l("code",null,"{ key, project, name, title, type, profile }"),e("；从卡片开始的需求（1.10 起）另有 "),l("code",null,"requester"),e("（卡片的提出人）和 "),l("code",null,"source"),e("（"),l("code",null,"{ system, id }"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps[].cachedInputTokens"),e(" / "),l("code",null,"steps[].agent")]),l("td",null,'1.13 起。输入中来自提示缓存的 tokens（agent 报告时）；这一步用的 agent（Paseo profile 名，或 "provider/model"）。更早的记录没有')]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),e("；"),l("code",null,"status"),e(" 是运行结束时的状态，"),l("code",null,"outcome"),e(" 是完成时报告的结论；"),l("code",null,"stopKind"),e("（1.12 起）是停下等人的原因代码（见 "),l("a",{href:"./state"},"state.md"),e("），"),l("code",null,"recoveries"),e("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),l("code",null,'{ "retry": 2 }'),e("。更早的记录没有这两项")])]),l("tr",null,[l("td",null,[l("code",null,"agents")]),l("td",null,[l("code",null,"{ builder, reviewer }"),e("：当时配置的 agent（如 "),l("code",null,"claude/opus（bypassPermissions）"),e("）")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("这次运行中开始的步骤："),l("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),e("；agent 没有报告的用量为 null")])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[l("code",null,"{ runs, failed }"),e("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),l("p",null,"不记录需求内容、代码和对话。"),l("h2",{id:"统计口径-req-stats",tabindex:"-1"},[e("统计口径（"),l("code",null,"req stats"),e("） "),l("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"​")]),l("ul",null,[l("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),l("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),l("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),l("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),l("li",null,[e("token 花在哪（1.13 起，"),l("code",null,"tokens"),e("）：这段时间的步骤按 "),l("code",null,"stepId"),e("、按 "),l("code",null,"agent"),e(" 合计 token（输入 + 输出）和占比；返工（"),l("code",null,"design_revise"),e("、"),l("code",null,"review_fix"),e("、"),l("code",null,"defect_fix"),e("、"),l("code",null,"reverify"),e("，以及 "),l("code",null,"design_review"),e("、"),l("code",null,"code_review"),e(" 第 2 轮起）的合计和占比；报告了 "),l("code",null,"cachedInputTokens"),e(" 的，算出输入中来自提示缓存的比例；已完成需求的 token 中位数（按档位）。")]),l("li",null,[e("停下等人的原因（1.12 起）：这段时间结束的运行按 "),l("code",null,"stopKind"),e(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),l("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),l("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),l("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),l("p",null,[l("code",null,"req stats --json"),e(" 和 "),l("code",null,"req api stats"),e(" 输出同样的对象（"),l("code",null,"schema: 1"),e("）："),l("code",null,"period"),e("、"),l("code",null,"machines"),e("、"),l("code",null,"active"),e("、"),l("code",null,"completed"),e("、"),l("code",null,"byType"),e("、"),l("code",null,"cycleHours"),e("、"),l("code",null,"steps"),e("、"),l("code",null,"rework"),e("、"),l("code",null,"waits"),e("、"),l("code",null,"usage"),e("、"),l("code",null,"byBuilder"),e("、"),l("code",null,"requirements"),e("（每个需求一项，字段与 "),l("code",null,"req stats --csv"),e(" 的列对应）。")])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=i(a,[["render",d]]);export{p as __pageData,E as default};