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

package/site-dist/assets/reference_contracts_cli-json.md.B7o8deSY.js

@@ -1 +0,0 @@
-import{_ as t,o as d,c as u,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const k=JSON.parse('{"title":"给程序用的 JSON 输出：req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/cli-json.md","filePath":"reference/contracts/cli-json.md","lastUpdated":null}'),s={name:"reference/contracts/cli-json.md"};function i(o,n,a,r,c,p){return d(),u("div",null,[...n[0]||(n[0]=[l("div",null,[l("h1",{id:"给程序用的-json-输出-req-api",tabindex:"-1"},[e("给程序用的 JSON 输出："),l("code",null,"req api"),e(),l("a",{class:"header-anchor",href:"#给程序用的-json-输出-req-api","aria-label":'Permalink to "给程序用的 JSON 输出：`req api`"'},"​")]),l("p",null,[e("1.9.0 起。Paseo 插件和其他程序通过 "),l("code",null,"req api"),e(" 读取需求、执行管理操作，不直接读写状态文件。每个命令输出一行 JSON：")]),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"}},"{ "),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"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"data"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }")])])])]),l("p",null,"出错时退出码为 1："),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"}},"{ "),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"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"error"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"code"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"not_found"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"message"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"没有找到需求……"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")])])])]),l("p",null,[l("code",null,"code"),e("："),l("code",null,"bad_arguments"),e("（参数不对）、"),l("code",null,"not_found"),e("（目录或需求不存在）、"),l("code",null,"not_allowed"),e("（不允许的文件或命令）、"),l("code",null,"failed"),e("（其他错误）。")]),l("p",null,[l("code",null,"schema"),e(" 只在不兼容的修改时增加；新增字段不改变 "),l("code",null,"schema"),e("，读取方应忽略不认识的字段。")]),l("h2",{id:"命令",tabindex:"-1"},[e("命令 "),l("a",{class:"header-anchor",href:"#命令","aria-label":'Permalink to "命令"'},"​")]),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"命令"),l("th",null,[l("code",null,"data")])])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"req api version")]),l("td",null,[l("code",null,"{ kitVersion, kitRoot, apiSchema, paseo, featuresDir }"),e("："),l("code",null,"paseo"),e(" 是这个版本支持的 Paseo 范围")])]),l("tr",null,[l("td",null,[l("code",null,"req api list [--repo <目录>]")]),l("td",null,'这个仓库所有工作区中的需求，数组，每项见下面的"需求"')]),l("tr",null,[l("td",null,[l("code",null,"req api list --all")]),l("td",null,[e("本机记录过的所有需求（"),l("a",{href:"./usage-record"},"需求索引"),e("），同上；目录已不在的 "),l("code",null,"present: false")])]),l("tr",null,[l("td",null,[l("code",null,"req api status <需求> [--repo <目录>]")]),l("td",null,'一个需求的详情，见下面的"详情"')]),l("tr",null,[l("td",null,[l("code",null,"req api file <需求> <文件> [--repo <目录>]")]),l("td",null,[l("code",null,"{ featureDir, file, size, truncated, content }"),e("；只能读取功能目录中的文档（见下），最多 512 KB")])]),l("tr",null,[l("td",null,[l("code",null,"req api stats [--since 30d] [--month 2026-10]")]),l("td",null,[l("code",null,"req stats --json"),e(" 的内容，见 "),l("a",{href:"./usage-record"},"使用记录")])]),l("tr",null,[l("td",null,[l("code",null,"req api index [--rebuild <目录>…] [--prune]")]),l("td",null,[e("不带选项：索引的全部条目；"),l("code",null,"--rebuild"),e("："),l("code",null,"{ scanned, registered, pruned, total }")])]),l("tr",null,[l("td",null,[l("code",null,"req api run <approve|stop|resume|verify|sync|reply> <需求> [--repo <目录>] [选项]")]),l("td",null,[l("code",null,"{ command, featureDir, ok, exitCode, message }"),e("。在 "),l("code",null,"--repo"),e("（默认当前目录）中执行与 "),l("code",null,"req <命令> <需求>"),e(" 完全相同的操作；"),l("code",null,"ok"),e(" 为 false 时退出码为 1")])]),l("tr",null,[l("td",null,[l("code",null,"req api models")]),l("td",null,[e("1.12 起。"),l("code",null,"{ current, choices, recommended }"),e("：本机配置中现在的 "),l("code",null,"agents"),e("；daemon 上能无人值守运行的选择（"),l("code",null,"{ id, label, provider, profile }"),e("，Paseo profile 在前）；按推荐的 "),l("code",null,"agents"),e("。连不上 daemon 时报错")])]),l("tr",null,[l("td",null,[l("code",null,"req api config [--repo <目录>] [--machine]")]),l("td",null,[e("1.12 起。"),l("code",null,"{ sources, ignored, error, repo, groups }"),e("："),l("code",null,"sources"),e(" 是生效的配置文件（"),l("code",null,"layer"),e(" 为 "),l("code",null,"machine"),e(" / "),l("code",null,"team"),e(" / "),l("code",null,"project"),e("，按叠加顺序）；"),l("code",null,"groups"),e(" 按主题分组，每项 "),l("code",null,"{ key, label, description, display, value, setBy, scope, changed }"),e("："),l("code",null,"display"),e(" 是用大白话写的值，"),l("code",null,"value"),e(" 中看起来像密钥的值和个人账号替换为 "),l("code",null,"••••"),e("，"),l("code",null,"setBy"),e(" 是写了它的文件，"),l("code",null,"changed"),e(" 表示与默认值不同。配置有错误时 "),l("code",null,"error"),e(" 写明原因，值按各文件所写。"),l("code",null,"--machine"),e(" 不看项目配置")])]),l("tr",null,[l("td",null,[l("code",null,"req api set-agents --json <设置>")]),l("td",null,[e("1.12 起。"),l("code",null,"{ ok, message }"),e("。"),l("code",null,"<设置>"),e(" 是 "),l("code",null,"{ builder, reviewer, fallback }"),e("（"),l("code",null,"fallback"),e(" 可以为 null），检查后写入本机配置的 "),l("code",null,"agents"),e("，原文件备份")])]),l("tr",null,[l("td",null,[l("code",null,"req api watchdog [--by plugin|factory] [--dry-run]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ checked, resumed, failed, skipped }"),e('：把本机"运行中但后台进程已不在"的需求直接继续（'),l("code",null,"req resume"),e("）。每个进程只继续一次，每个需求 24 小时内最多 3 次；"),l("code",null,"--by plugin"),e(" 同时记下插件在检查（流水线据此不再预约对话的定时检查）")])]),l("tr",null,[l("td",null,[l("code",null,"req api review-url <需求> [--repo <目录>] [--read-only]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ url, readOnly }"),e("：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。"),l("code",null,"--read-only"),e(" 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 "),l("code",null,"prototype/"),e(" 时报 "),l("code",null,"not_found")])])])]),l("p",null,[l("code",null,"<需求>"),e(" 的写法与 "),l("code",null,"req status"),e(" 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，"),l("code",null,"--repo"),e(" 写对话所在的目录或那个工作区都可以。")]),l("p",null,[l("code",null,"req api file"),e(" 能读取的文件："),l("code",null,"spec.md"),e("、"),l("code",null,"alignment.md"),e("、"),l("code",null,"spec-review.md"),e("、"),l("code",null,"changes.md"),e("、"),l("code",null,"decisions.tsv"),e("、"),l("code",null,"design.md"),e("、"),l("code",null,"design-review.md"),e("、"),l("code",null,"preview.md"),e("、"),l("code",null,"contract.md"),e("、"),l("code",null,"diagnosis.md"),e("、"),l("code",null,"assessment.md"),e("、"),l("code",null,"implementation.md"),e("、"),l("code",null,"progress.md"),e("、"),l("code",null,"code-review.md"),e("、"),l("code",null,"handoff.md"),e("、"),l("code",null,"service-start.md"),e("、"),l("code",null,"verification.md"),e("、"),l("code",null,"report.md"),e("、"),l("code",null,"acceptance.md"),e("、"),l("code",null,"lessons.tsv"),e("。")]),l("h2",{id:"需求-list-的每一项",tabindex:"-1"},[e("需求（"),l("code",null,"list"),e(" 的每一项） "),l("a",{class:"header-anchor",href:"#需求-list-的每一项","aria-label":'Permalink to "需求（`list` 的每一项）"'},"​")]),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,"key")]),l("td",null,"需求在本机的标识（对话所在目录 + 功能目录）")]),l("tr",null,[l("td",null,[l("code",null,"project")]),l("td",null,"项目名：对话所在目录的目录名")]),l("tr",null,[l("td",null,[l("code",null,"repo")]),l("td",null,"需求所在的目录（有自己的工作区时是那个工作区）")]),l("tr",null,[l("td",null,[l("code",null,"sourceRepo"),e(" / "),l("code",null,"workspaceId")]),l("td",null,"有自己的工作区时：对话所在的目录、Paseo 工作区 ID；否则 null")]),l("tr",null,[l("td",null,[l("code",null,"featureDir"),e(" / "),l("code",null,"name"),e(" / "),l("code",null,"title")]),l("td",null,"功能目录、目录名、需求标题")]),l("tr",null,[l("td",null,[l("code",null,"type"),e(" / "),l("code",null,"profile"),e(" / "),l("code",null,"branch")]),l("td",null,[e("需求类型（"),l("code",null,"defect"),e("、"),l("code",null,"refactor"),e("、"),l("code",null,"assessment"),e(" 或 null）、档位、分支")])]),l("tr",null,[l("td",null,[l("code",null,"stage")]),l("td",null,[e("与 "),l("code",null,"req list"),e(' 相同的阶段说明，如"开发中""等待确认方案""待验收"')])]),l("tr",null,[l("td",null,[l("code",null,"status")]),l("td",null,[e("状态文件的 "),l("code",null,"status"),e("；还没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"running")]),l("td",null,"后台进程是否在运行")]),l("tr",null,[l("td",null,[l("code",null,"phase")]),l("td",null,[l("code",null,"develop"),e(" / "),l("code",null,"verify")])]),l("tr",null,[l("td",null,[l("code",null,"attention")]),l("td",null,[e("需要人处理的事："),l("code",null,"approval"),e("（确认方案）、"),l("code",null,"business"),e("（需求方决定）、"),l("code",null,"permission"),e("（1.13，步骤在等权限批准；"),l("code",null,"waiting.questions"),e(" 是要批准的操作，"),l("code",null,"waiting.agentId"),e(" 是那个 agent）、"),l("code",null,"interrupted"),e("（中断，可以继续）、"),l("code",null,"not_completed"),e("（结束但未完成）；没有为 null")])]),l("tr",null,[l("td",null,[l("code",null,"waiting")]),l("td",null,[e("1.12 起。"),l("code",null,"attention"),e(" 不为 null 时："),l("code",null,"since"),e("（从什么时候开始等）、"),l("code",null,"questions"),e("（需求方要回答的问题）、"),l("code",null,"reason"),e("（停止原因）、"),l("code",null,"card"),e("（"),l("code",null,"{ system, id, url, requester }"),e("，从卡片开始的需求）、"),l("code",null,"canReply"),e("（能否用 "),l("code",null,"req api run reply <需求> <回复>"),e(" 把回复转给需求的对话）；否则为 null")])]),l("tr",null,[l("td",null,[l("code",null,"current")]),l("td",null,[e("正在运行的步骤 "),l("code",null,"[{ key, title, agentId }]")])]),l("tr",null,[l("td",null,[l("code",null,"updatedAt")]),l("td",null,"最近一次变化的时间")]),l("tr",null,[l("td",null,[l("code",null,"usage")]),l("td",null,[l("code",null,"{ steps, agentMinutes, inputTokens, outputTokens, costUsd }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"present")]),l("td",null,"目录是否还在")]),l("tr",null,[l("td",null,[l("code",null,"hasPrototype")]),l("td",null,[e("1.13 起。功能目录中有界面原型（"),l("code",null,"prototype/"),e("），可以用原型审查页查看")])])])]),l("h2",{id:"详情-status",tabindex:"-1"},[e("详情（"),l("code",null,"status"),e("） "),l("a",{class:"header-anchor",href:"#详情-status","aria-label":'Permalink to "详情（`status`）"'},"​")]),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,"files")]),l("td",null,[e("功能目录中存在的、可以用 "),l("code",null,"req api file"),e(" 读取的文件")])]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ attempt, startedAt, updatedAt, pid, phaseMode, stopReason, outcome, queuedSince, verifyAt, approval, originAgentId }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("每个步骤一项："),l("code",null,"{ key, stepId, title, phase, attempt, round, agentId, startedAt, endedAt, minutes, outcome, result, error, usage }"),e("；"),l("code",null,"title"),e(' 是给人看的名称（如"代码评审（第 2 轮）"），'),l("code",null,"result"),e(' 是结论的文字（如"需要修改"）')])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[e("质量门：状态文件中的 "),l("code",null,"gate")])]),l("tr",null,[l("td",null,[l("code",null,"estimate")]),l("td",null,[e("1.13 起。"),l("code",null,"{ basis, profile, typicalAgentMinutes, typicalTokens, usedAgentMinutes, usedTokens, leftMinutes, over }"),e("：按本机已完成的同档位需求（至少 3 个）的中位数估算；数据不够或已完成时为 null")])]),l("tr",null,[l("td",null,[l("code",null,"joint")]),l("td",null,[e("联合需求的其他仓库："),l("code",null,"[{ name, slug, repo, sourceRepo, branch, workspaceId, gate }]")])]),l("tr",null,[l("td",null,[l("code",null,"external")]),l("td",null,[e("外部系统中的卡片（1.9.0 起）："),l("code",null,"[{ name, id, url, status, syncedAt, pending, lastError }]"),e("；"),l("code",null,"pending"),e(" 是等待补发的调用数")])])])])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/cli-json.md"},"contracts/cli-json.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/cli-json.md"},"在 GitHub 上编辑")],-1)])])}const g=t(s,[["render",i]]);export{k as __pageData,g as default};

package/site-dist/assets/reference_contracts_cli-json.md.B7o8deSY.lean.js

@@ -1 +0,0 @@
-import{_ as t,o as d,c as u,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const k=JSON.parse('{"title":"给程序用的 JSON 输出：req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/cli-json.md","filePath":"reference/contracts/cli-json.md","lastUpdated":null}'),s={name:"reference/contracts/cli-json.md"};function i(o,n,a,r,c,p){return d(),u("div",null,[...n[0]||(n[0]=[l("div",null,[l("h1",{id:"给程序用的-json-输出-req-api",tabindex:"-1"},[e("给程序用的 JSON 输出："),l("code",null,"req api"),e(),l("a",{class:"header-anchor",href:"#给程序用的-json-输出-req-api","aria-label":'Permalink to "给程序用的 JSON 输出：`req api`"'},"​")]),l("p",null,[e("1.9.0 起。Paseo 插件和其他程序通过 "),l("code",null,"req api"),e(" 读取需求、执行管理操作，不直接读写状态文件。每个命令输出一行 JSON：")]),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"}},"{ "),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"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"data"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }")])])])]),l("p",null,"出错时退出码为 1："),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"}},"{ "),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"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"error"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"code"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"not_found"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"message"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"没有找到需求……"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")])])])]),l("p",null,[l("code",null,"code"),e("："),l("code",null,"bad_arguments"),e("（参数不对）、"),l("code",null,"not_found"),e("（目录或需求不存在）、"),l("code",null,"not_allowed"),e("（不允许的文件或命令）、"),l("code",null,"failed"),e("（其他错误）。")]),l("p",null,[l("code",null,"schema"),e(" 只在不兼容的修改时增加；新增字段不改变 "),l("code",null,"schema"),e("，读取方应忽略不认识的字段。")]),l("h2",{id:"命令",tabindex:"-1"},[e("命令 "),l("a",{class:"header-anchor",href:"#命令","aria-label":'Permalink to "命令"'},"​")]),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"命令"),l("th",null,[l("code",null,"data")])])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"req api version")]),l("td",null,[l("code",null,"{ kitVersion, kitRoot, apiSchema, paseo, featuresDir }"),e("："),l("code",null,"paseo"),e(" 是这个版本支持的 Paseo 范围")])]),l("tr",null,[l("td",null,[l("code",null,"req api list [--repo <目录>]")]),l("td",null,'这个仓库所有工作区中的需求，数组，每项见下面的"需求"')]),l("tr",null,[l("td",null,[l("code",null,"req api list --all")]),l("td",null,[e("本机记录过的所有需求（"),l("a",{href:"./usage-record"},"需求索引"),e("），同上；目录已不在的 "),l("code",null,"present: false")])]),l("tr",null,[l("td",null,[l("code",null,"req api status <需求> [--repo <目录>]")]),l("td",null,'一个需求的详情，见下面的"详情"')]),l("tr",null,[l("td",null,[l("code",null,"req api file <需求> <文件> [--repo <目录>]")]),l("td",null,[l("code",null,"{ featureDir, file, size, truncated, content }"),e("；只能读取功能目录中的文档（见下），最多 512 KB")])]),l("tr",null,[l("td",null,[l("code",null,"req api stats [--since 30d] [--month 2026-10]")]),l("td",null,[l("code",null,"req stats --json"),e(" 的内容，见 "),l("a",{href:"./usage-record"},"使用记录")])]),l("tr",null,[l("td",null,[l("code",null,"req api index [--rebuild <目录>…] [--prune]")]),l("td",null,[e("不带选项：索引的全部条目；"),l("code",null,"--rebuild"),e("："),l("code",null,"{ scanned, registered, pruned, total }")])]),l("tr",null,[l("td",null,[l("code",null,"req api run <approve|stop|resume|verify|sync|reply> <需求> [--repo <目录>] [选项]")]),l("td",null,[l("code",null,"{ command, featureDir, ok, exitCode, message }"),e("。在 "),l("code",null,"--repo"),e("（默认当前目录）中执行与 "),l("code",null,"req <命令> <需求>"),e(" 完全相同的操作；"),l("code",null,"ok"),e(" 为 false 时退出码为 1")])]),l("tr",null,[l("td",null,[l("code",null,"req api models")]),l("td",null,[e("1.12 起。"),l("code",null,"{ current, choices, recommended }"),e("：本机配置中现在的 "),l("code",null,"agents"),e("；daemon 上能无人值守运行的选择（"),l("code",null,"{ id, label, provider, profile }"),e("，Paseo profile 在前）；按推荐的 "),l("code",null,"agents"),e("。连不上 daemon 时报错")])]),l("tr",null,[l("td",null,[l("code",null,"req api config [--repo <目录>] [--machine]")]),l("td",null,[e("1.12 起。"),l("code",null,"{ sources, ignored, error, repo, groups }"),e("："),l("code",null,"sources"),e(" 是生效的配置文件（"),l("code",null,"layer"),e(" 为 "),l("code",null,"machine"),e(" / "),l("code",null,"team"),e(" / "),l("code",null,"project"),e("，按叠加顺序）；"),l("code",null,"groups"),e(" 按主题分组，每项 "),l("code",null,"{ key, label, description, display, value, setBy, scope, changed }"),e("："),l("code",null,"display"),e(" 是用大白话写的值，"),l("code",null,"value"),e(" 中看起来像密钥的值和个人账号替换为 "),l("code",null,"••••"),e("，"),l("code",null,"setBy"),e(" 是写了它的文件，"),l("code",null,"changed"),e(" 表示与默认值不同。配置有错误时 "),l("code",null,"error"),e(" 写明原因，值按各文件所写。"),l("code",null,"--machine"),e(" 不看项目配置")])]),l("tr",null,[l("td",null,[l("code",null,"req api set-agents --json <设置>")]),l("td",null,[e("1.12 起。"),l("code",null,"{ ok, message }"),e("。"),l("code",null,"<设置>"),e(" 是 "),l("code",null,"{ builder, reviewer, fallback }"),e("（"),l("code",null,"fallback"),e(" 可以为 null），检查后写入本机配置的 "),l("code",null,"agents"),e("，原文件备份")])]),l("tr",null,[l("td",null,[l("code",null,"req api watchdog [--by plugin|factory] [--dry-run]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ checked, resumed, failed, skipped }"),e('：把本机"运行中但后台进程已不在"的需求直接继续（'),l("code",null,"req resume"),e("）。每个进程只继续一次，每个需求 24 小时内最多 3 次；"),l("code",null,"--by plugin"),e(" 同时记下插件在检查（流水线据此不再预约对话的定时检查）")])]),l("tr",null,[l("td",null,[l("code",null,"req api review-url <需求> [--repo <目录>] [--read-only]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ url, readOnly }"),e("：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。"),l("code",null,"--read-only"),e(" 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 "),l("code",null,"prototype/"),e(" 时报 "),l("code",null,"not_found")])])])]),l("p",null,[l("code",null,"<需求>"),e(" 的写法与 "),l("code",null,"req status"),e(" 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，"),l("code",null,"--repo"),e(" 写对话所在的目录或那个工作区都可以。")]),l("p",null,[l("code",null,"req api file"),e(" 能读取的文件："),l("code",null,"spec.md"),e("、"),l("code",null,"alignment.md"),e("、"),l("code",null,"spec-review.md"),e("、"),l("code",null,"changes.md"),e("、"),l("code",null,"decisions.tsv"),e("、"),l("code",null,"design.md"),e("、"),l("code",null,"design-review.md"),e("、"),l("code",null,"preview.md"),e("、"),l("code",null,"contract.md"),e("、"),l("code",null,"diagnosis.md"),e("、"),l("code",null,"assessment.md"),e("、"),l("code",null,"implementation.md"),e("、"),l("code",null,"progress.md"),e("、"),l("code",null,"code-review.md"),e("、"),l("code",null,"handoff.md"),e("、"),l("code",null,"service-start.md"),e("、"),l("code",null,"verification.md"),e("、"),l("code",null,"report.md"),e("、"),l("code",null,"acceptance.md"),e("、"),l("code",null,"lessons.tsv"),e("。")]),l("h2",{id:"需求-list-的每一项",tabindex:"-1"},[e("需求（"),l("code",null,"list"),e(" 的每一项） "),l("a",{class:"header-anchor",href:"#需求-list-的每一项","aria-label":'Permalink to "需求（`list` 的每一项）"'},"​")]),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,"key")]),l("td",null,"需求在本机的标识（对话所在目录 + 功能目录）")]),l("tr",null,[l("td",null,[l("code",null,"project")]),l("td",null,"项目名：对话所在目录的目录名")]),l("tr",null,[l("td",null,[l("code",null,"repo")]),l("td",null,"需求所在的目录（有自己的工作区时是那个工作区）")]),l("tr",null,[l("td",null,[l("code",null,"sourceRepo"),e(" / "),l("code",null,"workspaceId")]),l("td",null,"有自己的工作区时：对话所在的目录、Paseo 工作区 ID；否则 null")]),l("tr",null,[l("td",null,[l("code",null,"featureDir"),e(" / "),l("code",null,"name"),e(" / "),l("code",null,"title")]),l("td",null,"功能目录、目录名、需求标题")]),l("tr",null,[l("td",null,[l("code",null,"type"),e(" / "),l("code",null,"profile"),e(" / "),l("code",null,"branch")]),l("td",null,[e("需求类型（"),l("code",null,"defect"),e("、"),l("code",null,"refactor"),e("、"),l("code",null,"assessment"),e(" 或 null）、档位、分支")])]),l("tr",null,[l("td",null,[l("code",null,"stage")]),l("td",null,[e("与 "),l("code",null,"req list"),e(' 相同的阶段说明，如"开发中""等待确认方案""待验收"')])]),l("tr",null,[l("td",null,[l("code",null,"status")]),l("td",null,[e("状态文件的 "),l("code",null,"status"),e("；还没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"running")]),l("td",null,"后台进程是否在运行")]),l("tr",null,[l("td",null,[l("code",null,"phase")]),l("td",null,[l("code",null,"develop"),e(" / "),l("code",null,"verify")])]),l("tr",null,[l("td",null,[l("code",null,"attention")]),l("td",null,[e("需要人处理的事："),l("code",null,"approval"),e("（确认方案）、"),l("code",null,"business"),e("（需求方决定）、"),l("code",null,"permission"),e("（1.13，步骤在等权限批准；"),l("code",null,"waiting.questions"),e(" 是要批准的操作，"),l("code",null,"waiting.agentId"),e(" 是那个 agent）、"),l("code",null,"interrupted"),e("（中断，可以继续）、"),l("code",null,"not_completed"),e("（结束但未完成）；没有为 null")])]),l("tr",null,[l("td",null,[l("code",null,"waiting")]),l("td",null,[e("1.12 起。"),l("code",null,"attention"),e(" 不为 null 时："),l("code",null,"since"),e("（从什么时候开始等）、"),l("code",null,"questions"),e("（需求方要回答的问题）、"),l("code",null,"reason"),e("（停止原因）、"),l("code",null,"card"),e("（"),l("code",null,"{ system, id, url, requester }"),e("，从卡片开始的需求）、"),l("code",null,"canReply"),e("（能否用 "),l("code",null,"req api run reply <需求> <回复>"),e(" 把回复转给需求的对话）；否则为 null")])]),l("tr",null,[l("td",null,[l("code",null,"current")]),l("td",null,[e("正在运行的步骤 "),l("code",null,"[{ key, title, agentId }]")])]),l("tr",null,[l("td",null,[l("code",null,"updatedAt")]),l("td",null,"最近一次变化的时间")]),l("tr",null,[l("td",null,[l("code",null,"usage")]),l("td",null,[l("code",null,"{ steps, agentMinutes, inputTokens, outputTokens, costUsd }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"present")]),l("td",null,"目录是否还在")]),l("tr",null,[l("td",null,[l("code",null,"hasPrototype")]),l("td",null,[e("1.13 起。功能目录中有界面原型（"),l("code",null,"prototype/"),e("），可以用原型审查页查看")])])])]),l("h2",{id:"详情-status",tabindex:"-1"},[e("详情（"),l("code",null,"status"),e("） "),l("a",{class:"header-anchor",href:"#详情-status","aria-label":'Permalink to "详情（`status`）"'},"​")]),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,"files")]),l("td",null,[e("功能目录中存在的、可以用 "),l("code",null,"req api file"),e(" 读取的文件")])]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ attempt, startedAt, updatedAt, pid, phaseMode, stopReason, outcome, queuedSince, verifyAt, approval, originAgentId }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("每个步骤一项："),l("code",null,"{ key, stepId, title, phase, attempt, round, agentId, startedAt, endedAt, minutes, outcome, result, error, usage }"),e("；"),l("code",null,"title"),e(' 是给人看的名称（如"代码评审（第 2 轮）"），'),l("code",null,"result"),e(' 是结论的文字（如"需要修改"）')])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[e("质量门：状态文件中的 "),l("code",null,"gate")])]),l("tr",null,[l("td",null,[l("code",null,"estimate")]),l("td",null,[e("1.13 起。"),l("code",null,"{ basis, profile, typicalAgentMinutes, typicalTokens, usedAgentMinutes, usedTokens, leftMinutes, over }"),e("：按本机已完成的同档位需求（至少 3 个）的中位数估算；数据不够或已完成时为 null")])]),l("tr",null,[l("td",null,[l("code",null,"joint")]),l("td",null,[e("联合需求的其他仓库："),l("code",null,"[{ name, slug, repo, sourceRepo, branch, workspaceId, gate }]")])]),l("tr",null,[l("td",null,[l("code",null,"external")]),l("td",null,[e("外部系统中的卡片（1.9.0 起）："),l("code",null,"[{ name, id, url, status, syncedAt, pending, lastError }]"),e("；"),l("code",null,"pending"),e(" 是等待补发的调用数")])])])])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/cli-json.md"},"contracts/cli-json.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/cli-json.md"},"在 GitHub 上编辑")],-1)])])}const g=t(s,[["render",i]]);export{k as __pageData,g as default};

package/site-dist/assets/reference_contracts_usage-record.md.DBMNY4OP.js

@@ -1,10 +0,0 @@
-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(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "featureDir"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"docs/features/20261012-sms-login"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "sourceRepo"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
-`),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,"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.DBMNY4OP.lean.js

@@ -1,10 +0,0 @@
-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(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "featureDir"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"docs/features/20261012-sms-login"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
-`),l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "sourceRepo"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),e(`
-`),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,"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};