paseo-req-kit 1.14.0-beta.3 → 1.14.0-beta.4

package/site-dist/assets/{reference_contracts_cli-json.md.BV1HtTmr.js → reference_contracts_cli-json.md.CCvKLasM.js}

@@ -1 +1 @@
-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"),e("。1.14 起还包括：用 "),l("code",null,"--track"),e(" 登记、还在对齐中的需求（"),l("code",null,"stage"),e(' 为"对齐中"，没有 '),l("code",null,"spec.md"),e(" 时 "),l("code",null,"title"),e(" 取自 "),l("code",null,"alignment.md"),e("），以及索引里出现过的项目中没登记的需求")])]),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|start> <需求> [--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("code",null,"start"),e("（1.14）：在项目主目录中自动加 "),l("code",null,"--worktree"),e("（上次已建好工作区的接着用），并把进展发回登记时的对话")])]),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] [--page check]")]),l("td",null,[e("1.13 起；"),l("code",null,"--page check"),e("（1.14）给出同一服务上的验收清单页地址（需要 "),l("code",null,"spec.md"),e("）。"),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("（结束但未完成）、"),l("code",null,"not_started"),e("（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 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(" 把回复转给需求的对话）、"),l("code",null,"canStart"),e("（1.14，"),l("code",null,"not_started"),e(" 时为 true：可以用 "),l("code",null,"req api run start <需求>"),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};
+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"),e("。1.14 起还包括：用 "),l("code",null,"--track"),e(" 登记、还在对齐中的需求（"),l("code",null,"stage"),e(' 为"对齐中"，没有 '),l("code",null,"spec.md"),e(" 时 "),l("code",null,"title"),e(" 取自 "),l("code",null,"alignment.md"),e("），以及索引里出现过的项目中没登记的需求")])]),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|start> <需求> [--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("code",null,"start"),e("（1.14）：在项目主目录中自动加 "),l("code",null,"--worktree"),e("（上次已建好工作区的接着用），并把进展发回登记时的对话")])]),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] [--page check]")]),l("td",null,[e("1.13 起；"),l("code",null,"--page check"),e("（1.14）给出同一服务上的验收清单页地址（需要 "),l("code",null,"spec.md"),e("），"),l("code",null,"--page code"),e("（1.14）给出代码审查页地址（需要已经写过代码）。"),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("（结束但未完成）、"),l("code",null,"not_started"),e("（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 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(" 把回复转给需求的对话）、"),l("code",null,"canStart"),e("（1.14，"),l("code",null,"not_started"),e(" 时为 true：可以用 "),l("code",null,"req api run start <需求>"),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.BV1HtTmr.lean.js → reference_contracts_cli-json.md.CCvKLasM.lean.js}

@@ -1 +1 @@
-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"),e("。1.14 起还包括：用 "),l("code",null,"--track"),e(" 登记、还在对齐中的需求（"),l("code",null,"stage"),e(' 为"对齐中"，没有 '),l("code",null,"spec.md"),e(" 时 "),l("code",null,"title"),e(" 取自 "),l("code",null,"alignment.md"),e("），以及索引里出现过的项目中没登记的需求")])]),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|start> <需求> [--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("code",null,"start"),e("（1.14）：在项目主目录中自动加 "),l("code",null,"--worktree"),e("（上次已建好工作区的接着用），并把进展发回登记时的对话")])]),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] [--page check]")]),l("td",null,[e("1.13 起；"),l("code",null,"--page check"),e("（1.14）给出同一服务上的验收清单页地址（需要 "),l("code",null,"spec.md"),e("）。"),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("（结束但未完成）、"),l("code",null,"not_started"),e("（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 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(" 把回复转给需求的对话）、"),l("code",null,"canStart"),e("（1.14，"),l("code",null,"not_started"),e(" 时为 true：可以用 "),l("code",null,"req api run start <需求>"),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};
+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"),e("。1.14 起还包括：用 "),l("code",null,"--track"),e(" 登记、还在对齐中的需求（"),l("code",null,"stage"),e(' 为"对齐中"，没有 '),l("code",null,"spec.md"),e(" 时 "),l("code",null,"title"),e(" 取自 "),l("code",null,"alignment.md"),e("），以及索引里出现过的项目中没登记的需求")])]),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|start> <需求> [--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("code",null,"start"),e("（1.14）：在项目主目录中自动加 "),l("code",null,"--worktree"),e("（上次已建好工作区的接着用），并把进展发回登记时的对话")])]),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] [--page check]")]),l("td",null,[e("1.13 起；"),l("code",null,"--page check"),e("（1.14）给出同一服务上的验收清单页地址（需要 "),l("code",null,"spec.md"),e("），"),l("code",null,"--page code"),e("（1.14）给出代码审查页地址（需要已经写过代码）。"),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("（结束但未完成）、"),l("code",null,"not_started"),e("（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 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(" 把回复转给需求的对话）、"),l("code",null,"canStart"),e("（1.14，"),l("code",null,"not_started"),e(" 时为 true：可以用 "),l("code",null,"req api run start <需求>"),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};