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

package/site-dist/assets/{guide_project.md.nGlTCo4D.lean.js → guide_project.md.DnD2-Dsd.lean.js}

@@ -1,4 +1,4 @@
-import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";const o=JSON.parse('{"title":"项目定制与运行规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/project.md","filePath":"guide/project.md","lastUpdated":null}'),t={name:"guide/project.md"};function h(k,s,d,r,E,p){return a(),n("div",null,[...s[0]||(s[0]=[i("div",null,[i("h1",{id:"项目定制与运行规则",tabindex:"-1"},[l("项目定制与运行规则 "),i("a",{class:"header-anchor",href:"#项目定制与运行规则","aria-label":'Permalink to "项目定制与运行规则"'},"​")]),i("h2",{id:"每个需求一个-worktree-工作区",tabindex:"-1"},[l("每个需求一个 worktree 工作区 "),i("a",{class:"header-anchor",href:"#每个需求一个-worktree-工作区","aria-label":'Permalink to "每个需求一个 worktree 工作区"'},"​")]),i("p",null,[l("在 Paseo 中为每个需求新建工作区："),i("strong",null,"New workspace"),l(" → 选择项目 → "),i("strong",null,"Isolation"),l(" 选 "),i("strong",null,"New worktree"),l(" → 起点选主分支，然后在这个工作区的对话里输入 "),i("code",null,"/req"),l("。")]),i("ul",null,[i("li",null,"流水线在这个工作区自己的目录和分支上运行、提交，不影响项目主目录。"),i("li",null,"同一个目录一次只能运行一条流水线；用了 worktree，几个需求可以同时进行。"),i("li",null,[l("在主目录发起时，"),i("code",null,"/req"),l(" 会先建议改用 worktree；使用者坚持的话，它会新建 "),i("code",null,"feature/<功能目录名>"),l(" 分支再继续。")])]),i("p",null,[i("strong",null,"分支规则"),l("：流水线把启动时检出的分支作为本次需求的工作分支，所有步骤都提交到这里，不切换、不新建分支。它拒绝在默认分支（"),i("code",null,"main"),l("、"),i("code",null,"master"),l(" 或 "),i("code",null,"origin/HEAD"),l(" 指向的分支）或 detached HEAD 上启动；续跑时分支变了也会拒绝。")]),i("h2",{id:"档位",tabindex:"-1"},[l("档位 "),i("a",{class:"header-anchor",href:"#档位","aria-label":'Permalink to "档位"'},"​")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"档位"),i("th",null,"适用"),i("th",null,"访谈"),i("th",null,"流程")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("快速（"),i("code",null,"quick"),l("）")]),i("td",null,"小改动：文案、样式、配置项、字段显示等，不涉及数据结构、权限、对外接口"),i("td",null,"只问要改什么、改成什么样、不改什么、验收标准"),i("td",null,"审核、评审、缺陷修复各一轮；不做服务启动验证；产物从简")]),i("tr",null,[i("td",null,[l("标准（"),i("code",null,"standard"),l("）")]),i("td",null,"其他情况"),i("td",null,"完整访谈"),i("td",null,"审核最多 2 轮、评审最多 3 轮、缺陷修复最多 3 轮")])])]),i("p",null,[i("code",null,"/req"),l(" 会根据需求推荐档位，用户确认后写进 spec（"),i("code",null,"- 档位：快速"),l("）。流水线按以下顺序决定档位："),i("code",null,"--profile"),l(" 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 "),i("code",null,"defaultProfile"),l("。各档的轮数和是否做服务启动验证可以在配置的 "),i("code",null,"profiles"),l(" 中调整。")]),i("h2",{id:"需求类型",tabindex:"-1"},[l("需求类型 "),i("a",{class:"header-anchor",href:"#需求类型","aria-label":'Permalink to "需求类型"'},"​")]),i("p",null,[l("spec 头部的 "),i("code",null,"- 类型："),l(" 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"类型"),i("th",null,"做法"),i("th",null,"关键证据")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("缺陷（"),i("code",null,"缺陷"),l("、"),i("code",null,"bug"),l("）")]),i("td",null,[l('方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 '),i("code",null,"diagnosis.md"),l("（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败")]),i("td",null,"同一个复现，修复前失败、修复后通过")]),i("tr",null,[i("td",null,[l("重构（"),i("code",null,"重构"),l("、"),i("code",null,"技术改进"),l("）")]),i("td",null,'先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变"'),i("td",null,"重构前后同一组测试一致")]),i("tr",null,[i("td",null,[l("评估（"),i("code",null,"评估"),l("、"),i("code",null,"调研"),l("）")]),i("td",null,[l("只读：调研评估（"),i("code",null,"assessment.md"),l("）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续")]),i("td",null,"引用的代码位置和实际运行的命令")])])]),i("p",null,[l("各类型的做法写在 "),i("code",null,"engine/prompts/types/<类型>.md"),l("，按步骤分节，接在每一步的任务之后；可以用 "),i("code",null,"prompts.local/types/"),l(" 覆盖。不想用某个类型的做法时，从配置 "),i("code",null,"requirementTypes"),l("（默认 "),i("code",null,'["defect", "refactor", "assessment"]'),l("）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。")]),i("h2",{id:"方案确认点-开工前请需求方确认-做完后会看到什么",tabindex:"-1"},[l('方案确认点：开工前请需求方确认"做完后会看到什么" '),i("a",{class:"header-anchor",href:"#方案确认点-开工前请需求方确认-做完后会看到什么","aria-label":'Permalink to "方案确认点：开工前请需求方确认"做完后会看到什么""'},"​")]),i("p",null,[l("方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 "),i("code",null,"preview.md"),l("（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 "),i("code",null,"prototype/"),l(" 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 "),i("code",null,"--approve"),l("（终端里 "),i("code",null,"req approve <需求>"),l("）开始写代码；要改的，更新需求说明后 "),i("code",null,"--resume"),l("，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"说明")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"designApproval.mode")]),i("td",null,[i("code",null,"ui")]),i("td",null,[i("code",null,"ui"),l("：方案判断这次是界面改动（结果文件 "),i("code",null,"ui_change"),l("）时才停；"),i("code",null,"always"),l("：每次都停；"),i("code",null,"off"),l("：不停")])]),i("tr",null,[i("td",null,[i("code",null,"designApproval.profiles")]),i("td",null,[i("code",null,'["standard"]')]),i("td",null,"哪些档位使用；快速档默认不停")]),i("tr",null,[i("td",null,[i("code",null,"designApproval.autoContinueHours")]),i("td",null,"0"),i("td",null,[l("大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 "),i("code",null,"waitingReminderHours"),l(" 会提醒一次")])])])]),i("p",null,[l('等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 '),i("code",null,"approval"),l(" 事件。评估类需求不写代码，不经过确认点。")]),i("p",null,[i("strong",null,"原型审查页（1.13 起）。"),l(" 有 "),i("code",null,"prototype/"),l(' 的需求，插件的需求页面和"等你处理"里有"打开原型审查页"，终端里是 '),i("code",null,"req review <需求>"),l("。需求方在原型上点选要改的地方（页面记下元素、文字、颜色、大小和位置）、双击直接改文字，切换状态和电脑、手机宽度，然后提交：意见整理成带位置信息的清单转给需求会话（与插件中写修改意见的效果相同），或者直接确认方案。草稿和提交记录在功能目录的 "),i("code",null,".pipeline/review/"),l(" 中，每一版原型也存在那里，原型改过后页面会标出这一版改了哪里。")]),i("p",null,[l("为了让审查页能用，方案设计按约定写原型：每个改动区域标 "),i("code",null,"data-ac"),l("（对应的 AC）和 "),i("code",null,"data-label"),l("（用需求方的话说是什么），各种状态包在 "),i("code",null,'<section data-state="状态名">'),l(" 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。")]),i("p",null,[l("审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 "),i("code",null,"127.0.0.1"),l("，地址中带随机令牌（插件设为只读时给只读的地址）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 "),i("code",null,"REQ_KIT_REVIEW_HOST"),l("（例如 "),i("code",null,"0.0.0.0"),l("）、"),i("code",null,"REQ_KIT_REVIEW_PUBLIC_URL"),l("（别人访问这台机器用的地址，例如 "),i("code",null,"http://10.1.2.3:6781"),l("），需要时用 "),i("code",null,"REQ_KIT_REVIEW_PORT"),l(" 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量。")]),i("h2",{id:"代码评审分两个方向",tabindex:"-1"},[l("代码评审分两个方向 "),i("a",{class:"header-anchor",href:"#代码评审分两个方向","aria-label":'Permalink to "代码评审分两个方向"'},"​")]),i("p",null,"标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论："),i("ul",null,[i("li",null,[i("strong",null,"规格评审"),l("：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。")]),i("li",null,[i("strong",null,"规范评审"),l("：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。")])]),i("p",null,[l("两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。"),i("code",null,"reviewAxes.enabled"),l(" 设为 "),i("code",null,"false"),l(" 关闭，"),i("code",null,"reviewAxes.profiles"),l(" 选择档位（默认只有标准档）。配置了评审小组（"),i("code",null,"reviewPanel"),l("）时，以评审小组为准。")]),i("h2",{id:"验收测试先提交",tabindex:"-1"},[l("验收测试先提交 "),i("a",{class:"header-anchor",href:"#验收测试先提交","aria-label":'Permalink to "验收测试先提交"'},"​")]),i("p",null,"方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。"),i("h2",{id:"术语表和范例文件",tabindex:"-1"},[l("术语表和范例文件 "),i("a",{class:"header-anchor",href:"#术语表和范例文件","aria-label":'Permalink to "术语表和范例文件"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,[i("code",null,"GLOSSARY.md")]),l("（仓库根目录）：业务词、含义、代码中的名字。"),i("code",null,"/req-setup"),l(" 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。")]),i("li",null,[i("strong",null,"范例文件"),l("："),i("code",null,"/req-setup"),l(" 在 "),i("code",null,"project-notes.md"),l(" 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。")])]),i("h2",{id:"反复出现的问题变成规则",tabindex:"-1"},[l("反复出现的问题变成规则 "),i("a",{class:"header-anchor",href:"#反复出现的问题变成规则","aria-label":'Permalink to "反复出现的问题变成规则"'},"​")]),i("p",null,[l('完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 '),i("code",null,"lessons.tsv"),l("（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，"),i("code",null,"req digest"),l(' 的需求总览会列在"反复出现的问题"中，'),i("code",null,"/req-retro"),l(" 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 "),i("code",null,".requirement-pipeline/lessons-handled.txt"),l("（一行一个），总览不再提示。")]),i("h2",{id:"质量门-流水线自己运行的检查",tabindex:"-1"},[l("质量门：流水线自己运行的检查 "),i("a",{class:"header-anchor",href:"#质量门-流水线自己运行的检查","aria-label":'Permalink to "质量门：流水线自己运行的检查"'},"​")]),i("p",null,[l("项目配置 "),i("code",null,".requirement-pipeline.json"),l(" 的 "),i("code",null,"checks"),l(" 列出流水线"),i("strong",null,"自己运行"),l("的检查，通常由 "),i("code",null,"/req-setup"),l(" 从实际跑通的命令写入：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
+import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"项目定制与运行规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/project.md","filePath":"guide/project.md","lastUpdated":null}'),t={name:"guide/project.md"};function h(k,s,d,r,E,u){return a(),n("div",null,[...s[0]||(s[0]=[i("div",null,[i("h1",{id:"项目定制与运行规则",tabindex:"-1"},[l("项目定制与运行规则 "),i("a",{class:"header-anchor",href:"#项目定制与运行规则","aria-label":'Permalink to "项目定制与运行规则"'},"​")]),i("h2",{id:"每个需求一个-worktree-工作区",tabindex:"-1"},[l("每个需求一个 worktree 工作区 "),i("a",{class:"header-anchor",href:"#每个需求一个-worktree-工作区","aria-label":'Permalink to "每个需求一个 worktree 工作区"'},"​")]),i("p",null,[l("在 Paseo 中为每个需求新建工作区："),i("strong",null,"New workspace"),l(" → 选择项目 → "),i("strong",null,"Isolation"),l(" 选 "),i("strong",null,"New worktree"),l(" → 起点选主分支，然后在这个工作区的对话里输入 "),i("code",null,"/req"),l("。")]),i("ul",null,[i("li",null,"流水线在这个工作区自己的目录和分支上运行、提交，不影响项目主目录。"),i("li",null,"同一个目录一次只能运行一条流水线；用了 worktree，几个需求可以同时进行。"),i("li",null,[l("在主目录发起时，"),i("code",null,"/req"),l(" 会先建议改用 worktree；使用者坚持的话，它会新建 "),i("code",null,"feature/<功能目录名>"),l(" 分支再继续。")])]),i("p",null,[i("strong",null,"分支规则"),l("：流水线把启动时检出的分支作为本次需求的工作分支，所有步骤都提交到这里，不切换、不新建分支。它拒绝在默认分支（"),i("code",null,"main"),l("、"),i("code",null,"master"),l(" 或 "),i("code",null,"origin/HEAD"),l(" 指向的分支）或 detached HEAD 上启动；续跑时分支变了也会拒绝。")]),i("h2",{id:"档位",tabindex:"-1"},[l("档位 "),i("a",{class:"header-anchor",href:"#档位","aria-label":'Permalink to "档位"'},"​")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"档位"),i("th",null,"适用"),i("th",null,"访谈"),i("th",null,"流程")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("快速（"),i("code",null,"quick"),l("）")]),i("td",null,"小改动：文案、样式、配置项、字段显示等，不涉及数据结构、权限、对外接口"),i("td",null,"只问要改什么、改成什么样、不改什么、验收标准"),i("td",null,"审核、评审、缺陷修复各一轮；不做服务启动验证；产物从简")]),i("tr",null,[i("td",null,[l("标准（"),i("code",null,"standard"),l("）")]),i("td",null,"其他情况"),i("td",null,"完整访谈"),i("td",null,"审核最多 2 轮、评审最多 3 轮、缺陷修复最多 3 轮")])])]),i("p",null,[i("code",null,"/req"),l(" 会根据需求推荐档位，用户确认后写进 spec（"),i("code",null,"- 档位：快速"),l("）。流水线按以下顺序决定档位："),i("code",null,"--profile"),l(" 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 "),i("code",null,"defaultProfile"),l("。各档的轮数和是否做服务启动验证可以在配置的 "),i("code",null,"profiles"),l(" 中调整。")]),i("h2",{id:"需求类型",tabindex:"-1"},[l("需求类型 "),i("a",{class:"header-anchor",href:"#需求类型","aria-label":'Permalink to "需求类型"'},"​")]),i("p",null,[l("spec 头部的 "),i("code",null,"- 类型："),l(" 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"类型"),i("th",null,"做法"),i("th",null,"关键证据")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("缺陷（"),i("code",null,"缺陷"),l("、"),i("code",null,"bug"),l("）")]),i("td",null,[l('方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 '),i("code",null,"diagnosis.md"),l("（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败")]),i("td",null,"同一个复现，修复前失败、修复后通过")]),i("tr",null,[i("td",null,[l("重构（"),i("code",null,"重构"),l("、"),i("code",null,"技术改进"),l("）")]),i("td",null,'先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变"'),i("td",null,"重构前后同一组测试一致")]),i("tr",null,[i("td",null,[l("评估（"),i("code",null,"评估"),l("、"),i("code",null,"调研"),l("）")]),i("td",null,[l("只读：调研评估（"),i("code",null,"assessment.md"),l("）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续")]),i("td",null,"引用的代码位置和实际运行的命令")])])]),i("p",null,[l("各类型的做法写在 "),i("code",null,"engine/prompts/types/<类型>.md"),l("，按步骤分节，接在每一步的任务之后；可以用 "),i("code",null,"prompts.local/types/"),l(" 覆盖。不想用某个类型的做法时，从配置 "),i("code",null,"requirementTypes"),l("（默认 "),i("code",null,'["defect", "refactor", "assessment"]'),l("）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。")]),i("h2",{id:"方案确认点-开工前请需求方确认-做完后会看到什么",tabindex:"-1"},[l('方案确认点：开工前请需求方确认"做完后会看到什么" '),i("a",{class:"header-anchor",href:"#方案确认点-开工前请需求方确认-做完后会看到什么","aria-label":'Permalink to "方案确认点：开工前请需求方确认"做完后会看到什么""'},"​")]),i("p",null,[l("方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 "),i("code",null,"preview.md"),l("（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 "),i("code",null,"prototype/"),l(" 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 "),i("code",null,"--approve"),l("（终端里 "),i("code",null,"req approve <需求>"),l("）开始写代码；要改的，更新需求说明后 "),i("code",null,"--resume"),l("，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"说明")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"designApproval.mode")]),i("td",null,[i("code",null,"ui")]),i("td",null,[i("code",null,"ui"),l("：方案判断这次是界面改动（结果文件 "),i("code",null,"ui_change"),l("）时才停；"),i("code",null,"always"),l("：每次都停；"),i("code",null,"off"),l("：不停")])]),i("tr",null,[i("td",null,[i("code",null,"designApproval.profiles")]),i("td",null,[i("code",null,'["standard"]')]),i("td",null,"哪些档位使用；快速档默认不停")]),i("tr",null,[i("td",null,[i("code",null,"designApproval.autoContinueHours")]),i("td",null,"0"),i("td",null,[l("大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 "),i("code",null,"waitingReminderHours"),l(" 会提醒一次")])])])]),i("p",null,[l('等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 '),i("code",null,"approval"),l(" 事件。评估类需求不写代码，不经过确认点。")]),i("p",null,[i("strong",null,"原型审查页（1.13 起）。"),l(" 有 "),i("code",null,"prototype/"),l(' 的需求，插件的需求页面和"等你处理"里有"审查原型"按钮（等待确认方案时是最醒目的"审查原型并确认方案"），审查页嵌在 Paseo 的网页端和桌面端里打开，手机上在浏览器中打开；终端里是 '),i("code",null,"req review <需求>"),l("。需求方在原型上点选要改的地方（页面记下元素、文字、颜色、大小和位置）、双击直接改文字，切换状态和电脑、手机宽度，然后提交：意见整理成带位置信息的清单转给需求会话（与插件中写修改意见的效果相同），或者直接确认方案。草稿和提交记录在功能目录的 "),i("code",null,".pipeline/review/"),l(" 中，每一版原型也存在那里，原型改过后页面会标出这一版改了哪里。")]),i("p",null,[l("为了让审查页能用，方案设计按约定写原型：每个改动区域标 "),i("code",null,"data-ac"),l("（对应的 AC）和 "),i("code",null,"data-label"),l("（用需求方的话说是什么），各种状态包在 "),i("code",null,'<section data-state="状态名">'),l(" 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。")]),i("p",null,[l("审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 "),i("code",null,"127.0.0.1"),l("，地址中带随机令牌（插件设为只读时给只读的地址）。审查页允许被本机地址上的页面（Paseo 网页端）嵌入；要限定或放开，设 "),i("code",null,"REQ_KIT_REVIEW_FRAME_ANCESTORS"),l("（CSP "),i("code",null,"frame-ancestors"),l(" 的值）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 "),i("code",null,"REQ_KIT_REVIEW_HOST"),l("（例如 "),i("code",null,"0.0.0.0"),l("）、"),i("code",null,"REQ_KIT_REVIEW_PUBLIC_URL"),l("（别人访问这台机器用的地址，例如 "),i("code",null,"http://10.1.2.3:6781"),l("），需要时用 "),i("code",null,"REQ_KIT_REVIEW_PORT"),l(" 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量。")]),i("h2",{id:"代码评审分两个方向",tabindex:"-1"},[l("代码评审分两个方向 "),i("a",{class:"header-anchor",href:"#代码评审分两个方向","aria-label":'Permalink to "代码评审分两个方向"'},"​")]),i("p",null,"标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论："),i("ul",null,[i("li",null,[i("strong",null,"规格评审"),l("：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。")]),i("li",null,[i("strong",null,"规范评审"),l("：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。")])]),i("p",null,[l("两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。"),i("code",null,"reviewAxes.enabled"),l(" 设为 "),i("code",null,"false"),l(" 关闭，"),i("code",null,"reviewAxes.profiles"),l(" 选择档位（默认只有标准档）。配置了评审小组（"),i("code",null,"reviewPanel"),l("）时，以评审小组为准。")]),i("h2",{id:"验收测试先提交",tabindex:"-1"},[l("验收测试先提交 "),i("a",{class:"header-anchor",href:"#验收测试先提交","aria-label":'Permalink to "验收测试先提交"'},"​")]),i("p",null,"方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。"),i("h2",{id:"术语表和范例文件",tabindex:"-1"},[l("术语表和范例文件 "),i("a",{class:"header-anchor",href:"#术语表和范例文件","aria-label":'Permalink to "术语表和范例文件"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,[i("code",null,"GLOSSARY.md")]),l("（仓库根目录）：业务词、含义、代码中的名字。"),i("code",null,"/req-setup"),l(" 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。")]),i("li",null,[i("strong",null,"范例文件"),l("："),i("code",null,"/req-setup"),l(" 在 "),i("code",null,"project-notes.md"),l(" 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。")])]),i("h2",{id:"反复出现的问题变成规则",tabindex:"-1"},[l("反复出现的问题变成规则 "),i("a",{class:"header-anchor",href:"#反复出现的问题变成规则","aria-label":'Permalink to "反复出现的问题变成规则"'},"​")]),i("p",null,[l('完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 '),i("code",null,"lessons.tsv"),l("（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，"),i("code",null,"req digest"),l(' 的需求总览会列在"反复出现的问题"中，'),i("code",null,"/req-retro"),l(" 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 "),i("code",null,".requirement-pipeline/lessons-handled.txt"),l("（一行一个），总览不再提示。")]),i("h2",{id:"质量门-流水线自己运行的检查",tabindex:"-1"},[l("质量门：流水线自己运行的检查 "),i("a",{class:"header-anchor",href:"#质量门-流水线自己运行的检查","aria-label":'Permalink to "质量门：流水线自己运行的检查"'},"​")]),i("p",null,[l("项目配置 "),i("code",null,".requirement-pipeline.json"),l(" 的 "),i("code",null,"checks"),l(" 列出流水线"),i("strong",null,"自己运行"),l("的检查，通常由 "),i("code",null,"/req-setup"),l(" 从实际跑通的命令写入：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "checks"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": [")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"lint"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"npm run lint"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"web 测试"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"npm test"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"cwd"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"web"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`
@@ -31,7 +31,7 @@ import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";c
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'    "test"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"npm test"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'    "web"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"type"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"service"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"  }")]),l(`
-`),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),i("p",null,[i("code",null,"paseo.json"),l(" 是团队共用的，而 Paseo 在各系统上用不同的 shell 执行它的命令（macOS/Linux：bash 和 sh；Windows：准备命令用 PowerShell，带 "),i("code",null,"-ExecutionPolicy Bypass"),l("，不受执行策略限制；脚本和服务用 cmd.exe）。所以 "),i("code",null,"/req-setup"),l(" 只写各系统一样的命令，用到环境变量的地方交给它写进项目的两个小脚本："),i("code",null,"scripts/paseo/copy-local-files.mjs"),l("（从来源目录复制不提交的本地文件，没有就跳过）和 "),i("code",null,"scripts/paseo/with-port.mjs"),l("（把 "),i("code",null,"{PORT}"),l(" 换成 Paseo 分配的端口，并设置 "),i("code",null,"PORT"),l("）。手写 "),i("code",null,"$PASEO_PORT"),l("、"),i("code",null,"%PASEO_PORT%"),l("、"),i("code",null,"cp"),l("、"),i("code",null,"Copy-Item"),l(" 这类只在某个系统上能用的命令时，"),i("code",null,"/req-doctor"),l(" 会指出：在本机上会失败的标为⚠，只是换系统会失败的给出提示。")]),i("ul",null,[i("li",null,[i("code",null,"worktree.setup"),l("：Paseo 新建 worktree 工作区时自动执行，新需求的工作区一建好就装好了依赖、带上了本地配置。")]),i("li",null,[i("code",null,'"type": "service"'),l(" 的脚本：流水线在服务启动验证、功能验证、缺陷修复和复验之前，通过 Paseo 带着当前代码重启它们，把地址（"),i("code",null,"http://web--<分支>--<项目>.localhost:6767"),l(" 这样的代理地址）交给步骤 agent，验证结束后停止。Paseo 为每个工作区分配独立端口，几个需求同时验证不会冲突，服务必须监听 Paseo 分配的端口（环境变量 "),i("code",null,"PASEO_PORT"),l("，用 "),i("code",null,"with-port.mjs"),l(" 传给程序）。")]),i("li",null,[l("服务没有启动成功时，最后的输出写到功能目录的 "),i("code",null,".pipeline/services/<服务名>.log"),l("，交给步骤 agent 查原因。")]),i("li",null,[l("只有从 Paseo 对话启动的流水线才会这样做（需要知道是哪个工作区）。不想用时在配置中设 "),i("code",null,'"paseoServices": "off"'),l("，步骤 agent 会像以前一样自己启动服务。"),i("code",null,"serviceReadySeconds"),l("（默认 120）是等待服务就绪的时间。")]),i("li",null,[l("在 Paseo 设置中打开 "),i("strong",null,"Enable Paseo tools"),l(" 后，步骤 agent 改完代码还可以自己重启这些服务。")]),i("li",null,"写错时服务起不来，流水线会改由步骤 agent 自己启动服务，不会中断。"),i("li",null,[l("PowerShell 被完全禁用（不只是执行策略）的 Windows 机器上，"),i("code",null,"worktree.setup"),l(" 无法执行；新工作区不会自动装依赖，步骤 agent 会按验证方法自己准备。")])]),i("h2",{id:"额度提醒",tabindex:"-1"},[l("额度提醒 "),i("a",{class:"header-anchor",href:"#额度提醒","aria-label":'Permalink to "额度提醒"'},"​")]),i("p",null,[l("开始前，流水线读取 Paseo 的用量信息（需要 Paseo 能读到对应 agent 的订阅用量）。所用 agent 的某个额度窗口用到 "),i("code",null,"quotaWarnPercent"),l("（默认 85）以上时，在对话里提醒一次，流水线照常进行；用完时遇到限流会自动等待重试。设为 0 关闭提醒。")]),i("h2",{id:"并行编排-确认前审阅、方案提案、浏览器验证",tabindex:"-1"},[l("并行编排：确认前审阅、方案提案、浏览器验证 "),i("a",{class:"header-anchor",href:"#并行编排-确认前审阅、方案提案、浏览器验证","aria-label":'Permalink to "并行编排：确认前审阅、方案提案、浏览器验证"'},"​")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"作用")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"specReview")]),i("td",null,[i("code",null,'"standard"')]),i("td",null,[l("请需求方确认之前，由 reviewer 在后台独立审阅需求说明草稿，问题写进 "),i("code",null,"spec-review.md"),l("。"),i("code",null,'"always"'),l(" 快速档也做，"),i("code",null,'"off"'),l(" 关闭")])]),i("tr",null,[i("td",null,[i("code",null,"designProposals")]),i("td",null,"关闭"),i("td",null,[i("code",null,'{"enabled": true}'),l(" 后，标准档的方案设计之前由几个 agent 并行各提一份方案（"),i("code",null,"design-proposals/"),l("），方案设计比较后决定。"),i("code",null,"members"),l(" 不写时用 builder 和 reviewer，也可以像评审小组一样列出成员（可用 "),i("code",null,"paseoProfile"),l("）。需求变更后的增量继续不做")])]),i("tr",null,[i("td",null,[i("code",null,"browserVerify")]),i("td",null,[i("code",null,'"auto"')]),i("td",null,[l("功能验证、缺陷修复、复验检查网页界面的方式。1.13 起总是附上界面检查命令 "),i("code",null,"req ui-check"),l("：用本机的 Edge 或 Chrome（无界面）打开页面，按电脑和手机宽度用文字报告显示不全、遮挡、超出屏幕、图片没加载、文字太淡、控件没有名字、控制台报错和请求失败，并和确认过的原型逐项对文字；不需要模型看图，也不需要 Paseo 桌面端。第一次使用时从 npm 源安装 "),i("code",null,"playwright-core"),l(" 到 "),i("code",null,"~/.req-kit/tools"),l("（不下载浏览器）。步骤 agent 还有 Paseo 浏览器工具（桌面端在线）时，另外按验收标准在浏览器中实际操作。"),i("code",null,'"off"'),l(" 都不用")])])])]),i("p",null,[l("Paseo 自带的 "),i("code",null,"/paseo-advisor"),l("、"),i("code",null,"/paseo-committee"),l(" 等编排 skill 也可以单独使用，例如对一个疑难问题请两个模型分别分析；它们不参与流水线（见 ADR 0019）。")]),i("h2",{id:"自动新建工作区-可选",tabindex:"-1"},[l("自动新建工作区（可选） "),i("a",{class:"header-anchor",href:"#自动新建工作区-可选","aria-label":'Permalink to "自动新建工作区（可选）"'},"​")]),i("p",null,[l("在项目主目录、主分支上发起的需求，可以用 "),i("code",null,"--worktree"),l(" 启动（"),i("code",null,"/req"),l(' 中的"启动（自动新建工作区）"）：流水线从当前分支切出 '),i("code",null,"feature/<功能目录名>"),l("，在 Paseo 中新建 worktree 工作区，把需求说明移过去并提交，之后的步骤都在那个工作区中运行，仍然挂在发起的对话下。对话的工作目录不变，查看进度、暂停、继续都在原对话中进行；读写需求文件用通知中给出的完整路径。只能在第一次启动时选择。见 ADR 0018。")]),i("h2",{id:"调度-预约、提醒、自动继续、排队",tabindex:"-1"},[l("调度：预约、提醒、自动继续、排队 "),i("a",{class:"header-anchor",href:"#调度-预约、提醒、自动继续、排队","aria-label":'Permalink to "调度：预约、提醒、自动继续、排队"'},"​")]),i("p",null,'需要"以后再做"的事，流水线用 Paseo 的定时任务把一条写明步骤的消息发回发起的对话，由对话 agent 执行（机器或 daemon 重启后仍然有效，在 Paseo 的 Schedules 中可以看到）。暂停命令会取消这些预约。'),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"作用")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("（启动参数 "),i("code",null,"--at"),l("）")]),i("td",null,"—"),i("td",null,[l("预约开始时间："),i("code",null,"22:00"),l("、"),i("code",null,"明天 8:30"),l("、"),i("code",null,"2026-10-14 08:30"),l("、"),i("code",null,"+2h")])]),i("tr",null,[i("td",null,[i("code",null,"waitingReminderHours")]),i("td",null,"24"),i("td",null,"等待需求方回答、或研发完成后等待测试验证超过这么久，在对话里提醒一次；0 关闭")]),i("tr",null,[i("td",null,[l("（启动参数 "),i("code",null,"--verify-at"),l("）")]),i("td",null,"—"),i("td",null,[l("分阶段时，研发完成后在这个时间自动开始测试验证（写法同 "),i("code",null,"--at"),l("；隐含分阶段）。研发完成时时间已过就直接继续")])]),i("tr",null,[i("td",null,[i("code",null,"autoResumeMinutes"),l(" / "),i("code",null,"autoResumeMax")]),i("td",null,"30 / 2"),i("td",null,"临时错误（重试用完）中断后，这么久之后在对话里自动继续；每次尝试最多几次；0 关闭")]),i("tr",null,[i("td",null,[i("code",null,"watchdogMinutes")]),i("td",null,"60（1.12 起默认打开）"),i("td",null,[l("运行期间对话定时检查，后台进程意外退出时自动继续。每次检查对话 agent 会运行一个回合；0 关闭。接单器（"),i("code",null,"req factory"),l("）每次检查时也会发现这样的流水线并请它的对话继续")])]),i("tr",null,[i("td",null,[i("code",null,"maxConcurrentPipelines")]),i("td",null,"0（不限）"),i("td",null,"本机同时运行的流水线上限，满了排队。只能写在本机配置中才有意义")])])]),i("h2",{id:"需求总览",tabindex:"-1"},[l("需求总览 "),i("a",{class:"header-anchor",href:"#需求总览","aria-label":'Permalink to "需求总览"'},"​")]),i("p",null,[i("code",null,"req digest"),l(' 在项目目录中列出所有工作区里的需求，按"需要处理、待验收、开发中、对齐中、已验收（最近 7 天）"分组，附用时与用量。'),i("code",null,"--notify"),l(" 同时发给外部通知（事件类型 "),i("code",null,"digest"),l("）；"),i("code",null,'--schedule "<cron>"'),l(" 让 Paseo 按时间表（本机时区）启动一个短暂的 agent 执行 "),i("code",null,"req digest --notify"),l("，例如每周一 9 点："),i("code",null,'req digest --schedule "0 9 * * 1"'),l("；取消："),i("code",null,"req digest --cancel <定时任务 ID>"),l("。")]),i("h2",{id:"使用统计",tabindex:"-1"},[l("使用统计 "),i("a",{class:"header-anchor",href:"#使用统计","aria-label":'Permalink to "使用统计"'},"​")]),i("p",null,[l("1.9.0 起，每次流水线运行结束时，引擎在本机的 "),i("code",null,"~/.req-kit/usage/runs.jsonl"),l(" 追加一条记录：各步骤的用时和用量、质量门、评审和缺陷轮数、结束时的状态（格式见 "),i("a",{href:"./../reference/contracts/usage-record"},"使用记录"),l("）。只记在本机，不记需求内容和代码，也不会自动发往任何地方。")]),i("ul",null,[i("li",null,[i("code",null,"req stats"),l("：最近 30 天的统计（"),i("code",null,"--since 2w"),l("、"),i("code",null,"--since 2026-10-01"),l("、"),i("code",null,"--month 2026-10"),l("）：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败）、各种等待的时长、各步骤用时、用量，以及不同 builder 的比较。"),i("code",null,"--json"),l("、"),i("code",null,"--csv"),l(" 输出机器可读的格式。")]),i("li",null,[i("code",null,"req stats --report --month 2026-10 [--out 目录]"),l("：生成给管理方汇报用的两份文件："),i("code",null,"req-kit-usage-2026-10.md"),l("（汇总）和 "),i("code",null,".csv"),l("（每个需求一行，可以用表格软件打开）。")]),i("li",null,[l("几台机器一起汇报：每台机器运行 "),i("code",null,"req stats --month 2026-10 --export"),l("，得到 "),i("code",null,"req-kit-usage-<主机名>-<日期>.jsonl"),l("；把这些文件放到一起，运行 "),i("code",null,"req stats --merge <文件…> --month 2026-10 --report"),l("。")])]),i("p",null,[l("本机的需求索引 "),i("code",null,"~/.req-kit/index/"),l(" 记录每个运行过的需求在哪个目录，Paseo 插件据此在一个页面列出本机所有项目的需求。1.9 之前运行过的需求不在索引里，在项目目录运行一次 "),i("code",null,"req index --rebuild"),l(" 补登；目录删掉后用 "),i("code",null,"req index --prune"),l(" 清理。")]),i("h2",{id:"外部系统对接-需求管理等",tabindex:"-1"},[l("外部系统对接（需求管理等） "),i("a",{class:"header-anchor",href:"#外部系统对接-需求管理等","aria-label":'Permalink to "外部系统对接（需求管理等）"'},"​")]),i("p",null,"1.9.0 起，流水线可以把需求同步到团队的需求管理系统：需求开始时建一张卡片，之后每到一个阶段改卡片的状态，卡片编号和链接写回需求，显示在进度、完成报告和 Paseo 插件里。对接的是本机已有的命令行工具（例如需求管理系统的 CLI），写在本机或团队配置中（它会运行命令，项目配置中的会被忽略）："),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"integrations"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": [")]),l(`
+`),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),i("p",null,[i("code",null,"paseo.json"),l(" 是团队共用的，而 Paseo 在各系统上用不同的 shell 执行它的命令（macOS/Linux：bash 和 sh；Windows：准备命令用 PowerShell，带 "),i("code",null,"-ExecutionPolicy Bypass"),l("，不受执行策略限制；脚本和服务用 cmd.exe）。所以 "),i("code",null,"/req-setup"),l(" 只写各系统一样的命令，用到环境变量的地方交给它写进项目的两个小脚本："),i("code",null,"scripts/paseo/copy-local-files.mjs"),l("（从来源目录复制不提交的本地文件，没有就跳过）和 "),i("code",null,"scripts/paseo/with-port.mjs"),l("（把 "),i("code",null,"{PORT}"),l(" 换成 Paseo 分配的端口，并设置 "),i("code",null,"PORT"),l("）。手写 "),i("code",null,"$PASEO_PORT"),l("、"),i("code",null,"%PASEO_PORT%"),l("、"),i("code",null,"cp"),l("、"),i("code",null,"Copy-Item"),l(" 这类只在某个系统上能用的命令时，"),i("code",null,"/req-doctor"),l(" 会指出：在本机上会失败的标为⚠，只是换系统会失败的给出提示。")]),i("ul",null,[i("li",null,[i("code",null,"worktree.setup"),l("：Paseo 新建 worktree 工作区时自动执行，新需求的工作区一建好就装好了依赖、带上了本地配置。")]),i("li",null,[i("code",null,'"type": "service"'),l(" 的脚本：流水线在服务启动验证、功能验证、缺陷修复和复验之前，通过 Paseo 带着当前代码重启它们，把地址（"),i("code",null,"http://web--<分支>--<项目>.localhost:6767"),l(" 这样的代理地址）交给步骤 agent，验证结束后停止。Paseo 为每个工作区分配独立端口，几个需求同时验证不会冲突，服务必须监听 Paseo 分配的端口（环境变量 "),i("code",null,"PASEO_PORT"),l("，用 "),i("code",null,"with-port.mjs"),l(" 传给程序）。")]),i("li",null,[l("服务没有启动成功时，最后的输出写到功能目录的 "),i("code",null,".pipeline/services/<服务名>.log"),l("，交给步骤 agent 查原因。")]),i("li",null,[l("只有从 Paseo 对话启动的流水线才会这样做（需要知道是哪个工作区）。不想用时在配置中设 "),i("code",null,'"paseoServices": "off"'),l("，步骤 agent 会像以前一样自己启动服务。"),i("code",null,"serviceReadySeconds"),l("（默认 120）是等待服务就绪的时间。")]),i("li",null,[l("在 Paseo 设置中打开 "),i("strong",null,"Enable Paseo tools"),l(" 后，步骤 agent 改完代码还可以自己重启这些服务。")]),i("li",null,"写错时服务起不来，流水线会改由步骤 agent 自己启动服务，不会中断。"),i("li",null,[l("PowerShell 被完全禁用（不只是执行策略）的 Windows 机器上，"),i("code",null,"worktree.setup"),l(" 无法执行；新工作区不会自动装依赖，步骤 agent 会按验证方法自己准备。")])]),i("h2",{id:"额度提醒",tabindex:"-1"},[l("额度提醒 "),i("a",{class:"header-anchor",href:"#额度提醒","aria-label":'Permalink to "额度提醒"'},"​")]),i("p",null,[l("开始前，流水线读取 Paseo 的用量信息（需要 Paseo 能读到对应 agent 的订阅用量）。所用 agent 的某个额度窗口用到 "),i("code",null,"quotaWarnPercent"),l("（默认 85）以上时，在对话里提醒一次，流水线照常进行；用完时遇到限流会自动等待重试。设为 0 关闭提醒。")]),i("h2",{id:"token-预算和用时估算-1-13-起",tabindex:"-1"},[l("token 预算和用时估算（1.13 起） "),i("a",{class:"header-anchor",href:"#token-预算和用时估算-1-13-起","aria-label":'Permalink to "token 预算和用时估算（1.13 起）"'},"​")]),i("p",null,"内网模型通常不报金额，所以按 token（输入 + 输出）计："),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"说明")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"budget.tokens")]),i("td",null,[i("code",null,"null"),l("（不限）")]),i("td",null,[l("一个需求所有步骤、所有尝试合计最多用多少 tokens，例如 "),i("code",null,"3000000"),l('。每个新步骤开始前检查：用完时，已完成的步骤都保留，流水线在下一步开始前停下（状态"已中断"，停下原因 '),i("code",null,"budget"),l("），请对话问需求方是否继续；继续（"),i("code",null,"req resume"),l(' 或在对话里说"继续开发"）会再给一份同样多的预算')])]),i("tr",null,[i("td",null,[i("code",null,"budget.warnPercent")]),i("td",null,"80"),i("td",null,[l("用到预算的这个比例时在对话里告知一次（不停），同时发 "),i("code",null,"milestone"),l(" 外部通知")])])])]),i("p",null,[l("写在本机、团队或项目配置中都可以，例如 "),i("code",null,'"budget": { "tokens": 3000000 }'),l("。还没有数据时，先不设预算跑几个需求，用 "),i("code",null,"req stats"),l(' 的"token 花在哪"看每个需求的中位数，再按它的两三倍设。')]),i("p",null,[l('用时估算不用配置：本机已完成的同档位需求有 3 个以上时，开始开发的回复里写出"agent 合计用时和 token 的中位数"作为参考；'),i("code",null,"req status"),l(' 和插件的需求页面显示"预计还要约多久"（按中位数减去已用的 agent 时间，不含等人的时间），超过中位数时如实说"已超过通常的用时"。')]),i("h2",{id:"并行编排-确认前审阅、方案提案、浏览器验证",tabindex:"-1"},[l("并行编排：确认前审阅、方案提案、浏览器验证 "),i("a",{class:"header-anchor",href:"#并行编排-确认前审阅、方案提案、浏览器验证","aria-label":'Permalink to "并行编排：确认前审阅、方案提案、浏览器验证"'},"​")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"作用")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"specReview")]),i("td",null,[i("code",null,'"standard"')]),i("td",null,[l("请需求方确认之前，由 reviewer 在后台独立审阅需求说明草稿，问题写进 "),i("code",null,"spec-review.md"),l("。"),i("code",null,'"always"'),l(" 快速档也做，"),i("code",null,'"off"'),l(" 关闭")])]),i("tr",null,[i("td",null,[i("code",null,"designProposals")]),i("td",null,"关闭"),i("td",null,[i("code",null,'{"enabled": true}'),l(" 后，标准档的方案设计之前由几个 agent 并行各提一份方案（"),i("code",null,"design-proposals/"),l("），方案设计比较后决定。"),i("code",null,"members"),l(" 不写时用 builder 和 reviewer，也可以像评审小组一样列出成员（可用 "),i("code",null,"paseoProfile"),l("）。需求变更后的增量继续不做")])]),i("tr",null,[i("td",null,[i("code",null,"browserVerify")]),i("td",null,[i("code",null,'"auto"')]),i("td",null,[l("功能验证、缺陷修复、复验检查网页界面的方式。1.13 起总是附上界面检查命令 "),i("code",null,"req ui-check"),l("：用本机的 Edge 或 Chrome（无界面）打开页面，按电脑和手机宽度用文字报告显示不全、遮挡、超出屏幕、图片没加载、文字太淡、控件没有名字、控制台报错和请求失败，并和确认过的原型逐项对文字；不需要模型看图，也不需要 Paseo 桌面端。第一次使用时从 npm 源安装 "),i("code",null,"playwright-core"),l(" 到 "),i("code",null,"~/.req-kit/tools"),l("（不下载浏览器）。步骤 agent 还有 Paseo 浏览器工具（桌面端在线）时，另外按验收标准在浏览器中实际操作。"),i("code",null,'"off"'),l(" 都不用")])])])]),i("p",null,[l("Paseo 自带的 "),i("code",null,"/paseo-advisor"),l("、"),i("code",null,"/paseo-committee"),l(" 等编排 skill 也可以单独使用，例如对一个疑难问题请两个模型分别分析；它们不参与流水线（见 ADR 0019）。")]),i("h2",{id:"自动新建工作区-可选",tabindex:"-1"},[l("自动新建工作区（可选） "),i("a",{class:"header-anchor",href:"#自动新建工作区-可选","aria-label":'Permalink to "自动新建工作区（可选）"'},"​")]),i("p",null,[l("在项目主目录、主分支上发起的需求，可以用 "),i("code",null,"--worktree"),l(" 启动（"),i("code",null,"/req"),l(' 中的"启动（自动新建工作区）"）：流水线从当前分支切出 '),i("code",null,"feature/<功能目录名>"),l("，在 Paseo 中新建 worktree 工作区，把需求说明移过去并提交，之后的步骤都在那个工作区中运行，仍然挂在发起的对话下。对话的工作目录不变，查看进度、暂停、继续都在原对话中进行；读写需求文件用通知中给出的完整路径。只能在第一次启动时选择。见 ADR 0018。")]),i("h2",{id:"调度-预约、提醒、自动继续、排队",tabindex:"-1"},[l("调度：预约、提醒、自动继续、排队 "),i("a",{class:"header-anchor",href:"#调度-预约、提醒、自动继续、排队","aria-label":'Permalink to "调度：预约、提醒、自动继续、排队"'},"​")]),i("p",null,'需要"以后再做"的事，流水线用 Paseo 的定时任务把一条写明步骤的消息发回发起的对话，由对话 agent 执行（机器或 daemon 重启后仍然有效，在 Paseo 的 Schedules 中可以看到）。暂停命令会取消这些预约。'),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"作用")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("（启动参数 "),i("code",null,"--at"),l("）")]),i("td",null,"—"),i("td",null,[l("预约开始时间："),i("code",null,"22:00"),l("、"),i("code",null,"明天 8:30"),l("、"),i("code",null,"2026-10-14 08:30"),l("、"),i("code",null,"+2h")])]),i("tr",null,[i("td",null,[i("code",null,"waitingReminderHours")]),i("td",null,"24"),i("td",null,"等待需求方回答、或研发完成后等待测试验证超过这么久，在对话里提醒一次；0 关闭")]),i("tr",null,[i("td",null,[l("（启动参数 "),i("code",null,"--verify-at"),l("）")]),i("td",null,"—"),i("td",null,[l("分阶段时，研发完成后在这个时间自动开始测试验证（写法同 "),i("code",null,"--at"),l("；隐含分阶段）。研发完成时时间已过就直接继续")])]),i("tr",null,[i("td",null,[i("code",null,"autoResumeMinutes"),l(" / "),i("code",null,"autoResumeMax")]),i("td",null,"30 / 2"),i("td",null,"临时错误（重试用完）中断后，这么久之后在对话里自动继续；每次尝试最多几次；0 关闭")]),i("tr",null,[i("td",null,[i("code",null,"watchdogMinutes")]),i("td",null,"60（1.12 起默认打开）"),i("td",null,[l('运行期间对话定时检查，后台进程意外退出时自动继续。每次检查对话 agent 会运行一个回合；0 关闭。1.13 起：装了 req-kit 插件时，插件每 5 分钟在 daemon 里直接检查本机所有需求，发现"运行中但后台进程已不在"的就执行 '),i("code",null,"req resume"),l("（不经过模型，每个进程只继续一次，每个需求 24 小时内最多 3 次），这时不再预约对话的定时检查；插件设为只读时不做。接单器（"),i("code",null,"req factory"),l("）每次检查也同样直接继续")])]),i("tr",null,[i("td",null,[i("code",null,"maxConcurrentPipelines")]),i("td",null,"0（不限）"),i("td",null,"本机同时运行的流水线上限，满了排队。只能写在本机配置中才有意义")])])]),i("h2",{id:"需求总览",tabindex:"-1"},[l("需求总览 "),i("a",{class:"header-anchor",href:"#需求总览","aria-label":'Permalink to "需求总览"'},"​")]),i("p",null,[i("code",null,"req digest"),l(' 在项目目录中列出所有工作区里的需求，按"需要处理、待验收、开发中、对齐中、已验收（最近 7 天）"分组，附用时与用量。'),i("code",null,"--notify"),l(" 同时发给外部通知（事件类型 "),i("code",null,"digest"),l("）；"),i("code",null,'--schedule "<cron>"'),l(" 让 Paseo 按时间表（本机时区）启动一个短暂的 agent 执行 "),i("code",null,"req digest --notify"),l("，例如每周一 9 点："),i("code",null,'req digest --schedule "0 9 * * 1"'),l("；取消："),i("code",null,"req digest --cancel <定时任务 ID>"),l("。")]),i("h2",{id:"使用统计",tabindex:"-1"},[l("使用统计 "),i("a",{class:"header-anchor",href:"#使用统计","aria-label":'Permalink to "使用统计"'},"​")]),i("p",null,[l("1.9.0 起，每次流水线运行结束时，引擎在本机的 "),i("code",null,"~/.req-kit/usage/runs.jsonl"),l(" 追加一条记录：各步骤的用时和用量、质量门、评审和缺陷轮数、结束时的状态（格式见 "),i("a",{href:"./../reference/contracts/usage-record"},"使用记录"),l("）。只记在本机，不记需求内容和代码，也不会自动发往任何地方。")]),i("ul",null,[i("li",null,[i("code",null,"req stats"),l("：最近 30 天的统计（"),i("code",null,"--since 2w"),l("、"),i("code",null,"--since 2026-10-01"),l("、"),i("code",null,"--month 2026-10"),l('）：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败）、各种等待的时长、各步骤用时、用量，以及不同 builder 的比较。1.13 起有"token 花在哪"一节：按步骤和按模型的 token 及占比、返工（方案修订、评审问题修复、缺陷修复、复验，以及第 2 轮起的审核和评审）的占比、输入中来自提示缓存的比例、每个完成需求的中位数；插件的"使用统计"页用条形图显示同样的内容。'),i("code",null,"--json"),l("、"),i("code",null,"--csv"),l(" 输出机器可读的格式。")]),i("li",null,[i("code",null,"req stats --report --month 2026-10 [--out 目录]"),l("：生成给管理方汇报用的两份文件："),i("code",null,"req-kit-usage-2026-10.md"),l("（汇总）和 "),i("code",null,".csv"),l("（每个需求一行，可以用表格软件打开）。")]),i("li",null,[l("几台机器一起汇报：每台机器运行 "),i("code",null,"req stats --month 2026-10 --export"),l("，得到 "),i("code",null,"req-kit-usage-<主机名>-<日期>.jsonl"),l("；把这些文件放到一起，运行 "),i("code",null,"req stats --merge <文件…> --month 2026-10 --report"),l("。")])]),i("p",null,[l("本机的需求索引 "),i("code",null,"~/.req-kit/index/"),l(" 记录每个运行过的需求在哪个目录，Paseo 插件据此在一个页面列出本机所有项目的需求。1.9 之前运行过的需求不在索引里，在项目目录运行一次 "),i("code",null,"req index --rebuild"),l(" 补登；目录删掉后用 "),i("code",null,"req index --prune"),l(" 清理。")]),i("h2",{id:"外部系统对接-需求管理等",tabindex:"-1"},[l("外部系统对接（需求管理等） "),i("a",{class:"header-anchor",href:"#外部系统对接-需求管理等","aria-label":'Permalink to "外部系统对接（需求管理等）"'},"​")]),i("p",null,"1.9.0 起，流水线可以把需求同步到团队的需求管理系统：需求开始时建一张卡片，之后每到一个阶段改卡片的状态，卡片编号和链接写回需求，显示在进度、完成报告和 Paseo 插件里。对接的是本机已有的命令行工具（例如需求管理系统的 CLI），写在本机或团队配置中（它会运行命令，项目配置中的会被忽略）："),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"integrations"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": [")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"  {")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'    "name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"ALM"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'    "command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"alm"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
@@ -74,4 +74,4 @@ import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";c
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"安全视角"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"provider"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"codex/<模型 ID>"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"modeId"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"full-access"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"focus"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"重点检查权限、输入校验和数据安全"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"可维护性"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"provider"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"opencode/anthropic/<模型 ID>"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"modeId"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"build"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"featureValues"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"auto_accept"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"true"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"  ]")]),l(`
-`),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),i("ul",null,[i("li",null,[l("成员并行运行，在同一个目录里只读代码、写各自的意见文件（"),i("code",null,"<功能目录>/review-panel/"),l("），不提交，不改文件。")]),i("li",null,"某位成员失败时，只汇总完成的成员；全部失败时该步骤失败。"),i("li",null,"成本：每次启用的评审多出 N 个 agent 的用量，所以默认只用于标准档的第一轮。"),i("li",null,[l("成员的模型和模式会在 "),i("code",null,"/req-doctor"),l(" 中一并检查。")])]),i("h2",{id:"需求总览、决策记录、变更与验收记录",tabindex:"-1"},[l("需求总览、决策记录、变更与验收记录 "),i("a",{class:"header-anchor",href:"#需求总览、决策记录、变更与验收记录","aria-label":'Permalink to "需求总览、决策记录、变更与验收记录"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,"需求总览"),l("："),i("code",null,"node <req-kit>/bin/start-pipeline.mjs --list"),l(" 列出这个仓库所有 worktree 中的需求和各自的阶段（对齐中、开发中、待验收、已验收等）。总览现场生成，不提交到仓库，避免各分支合并时冲突。")]),i("li",null,[i("strong",null,"决策记录"),l(),i("code",null,"decisions.tsv"),l("：各步骤把不显而易见的选择（假设、取舍、偏离方案、驳回的评审意见、决定不修的问题）各记一行。会影响结果的标为 "),i("code",null,"needs_human=yes"),l('，完成报告把它们列入"需要你确认的决定"。')]),i("li",null,[i("strong",null,"变更记录"),l(),i("code",null,"changes.md"),l('：每次修改需求（包括方案审核提出问题、验收发现问题）记一节，spec 头部的"版本"随之加 1。')]),i("li",null,[i("strong",null,"验收记录"),l(),i("code",null,"acceptance.md"),l("：由 "),i("code",null,"/req"),l(" 的验收手册写，逐条记录验收结果和结论。")])]),i("p",null,[l("格式见 "),i("code",null,"contracts/feature-files.md"),l("。")]),i("h2",{id:"运行规则",tabindex:"-1"},[l("运行规则 "),i("a",{class:"header-anchor",href:"#运行规则","aria-label":'Permalink to "运行规则"'},"​")]),i("p",null,[i("strong",null,"步骤和轮数"),l("（轮数按档位，在配置的 "),i("code",null,"profiles"),l(" 中调整；下面是标准档的默认值）：")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"环节"),i("th",null,"规则")])]),i("tbody",null,[i("tr",null,[i("td",null,"评审小组（可选）"),i("td",null,"开启时，标准档的方案审核和代码评审第一轮先由小组成员并行评审，再由评审者核实汇总")]),i("tr",null,[i("td",null,"方案审核 ⇄ 方案修订"),i("td",null,'最多 2 轮审核。判定"阻塞"时暂停并请需求方决定；最后一轮仍要求修改时，修订后直接进入实现')]),i("tr",null,[i("td",null,"代码评审 ⇄ 评审问题修复"),i("td",null,"最多 3 轮评审，通过即止；轮数用完时修复后进入下一阶段")]),i("tr",null,[i("td",null,"提测说明"),i("td",null,[l("代码评审之后执行，写 "),i("code",null,"handoff.md"),l("。分阶段执行时研发阶段到此结束")])]),i("tr",null,[i("td",null,"服务启动验证"),i("td",null,[l("方案设计判断项目有常驻服务、且档位开启了 "),i("code",null,"serviceStart"),l(" 时才执行（在已部署的测试环境中验证时不执行）")])]),i("tr",null,[i("td",null,"缺陷修复 ⇄ 复验"),i("td",null,[l("功能验证发现缺陷时执行，最多 3 轮，复验通过即止（"),i("code",null,"phases.verify.defects"),l(" 为 "),i("code",null,"handback"),l(" 或 "),i("code",null,"report"),l(' 时见上文"执行方式"）')])]),i("tr",null,[i("td",null,"完成报告"),i("td",null,"只要没有暂停或中断就一定执行，遗留问题写进报告")]),i("tr",null,[i("td",null,"完成后继续"),i("td",null,[l("完成后 spec.md 被修改过（需求变更、验收发现问题），"),i("code",null,"--resume"),l(" 从方案设计开始，各步骤在已有方案和代码的基础上只处理变化的部分；没改过则拒绝。"),i("code",null,"--restart"),l(" 则完全从零开始")])]),i("tr",null,[i("td",null,"增量继续"),i("td",null,[l('需求变更、回答了方案审核的问题后继续时：方案在原文末尾追加"第 N 次尝试"一节；实现只改需要改的；代码评审只看本次开始以来的改动；验证重新验证变化涉及的验收标准，其余的至少跑一遍现有测试；报告说明是第几次。做法写在 '),i("code",null,"engine/prompts/incremental.md"),l("，可以用 "),i("code",null,"prompts.local/"),l(" 替换")])])])]),i("p",null,[i("strong",null,"结果文件"),l("：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。")]),i("p",null,[i("strong",null,"等待与超时"),l("：每步有总时限（"),i("code",null,"stepTimeoutMinutes"),l("）。到时 agent 还在做时，先再给它同样长的时间（"),i("code",null,"selfHeal"),l("，见下）；仍未完成才判定失败，但不停止 agent。继续（"),i("code",null,"--resume"),l("、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮（这一轮不再额外延长）；第二次仍超时才停止它、另起一个 agent。需求改过、开始了新一次尝试时，上一次留下的 agent 直接停掉，不接手（1.12.1）。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。")]),i("p",null,[i("strong",null,"临时错误自动重试"),l("：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"retry"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"attempts"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"2"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"backoffSeconds"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": ["),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"60"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"300"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"] }")])])])]),i("p",null,[i("code",null,"attempts"),l(" 设为 0 关闭；"),i("code",null,"backoffSeconds"),l(" 的个数少于重试次数时，后面的重试使用最后一个值。超时、结果文件不合格、agent 自己判定失败等不是临时错误，不按这里重试。重试用完仍失败时，中断通知会注明已重试的次数。")]),i("p",null,[i("strong",null,"自愈"),l("（1.12，"),i("code",null,"selfHeal"),l("，默认 "),i("code",null,"true"),l("）：能安全自动处理的中断不再等人。")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"情况"),i("th",null,"自动处理")])]),i("tbody",null,[i("tr",null,[i("td",null,"步骤超时，agent 还在做"),i("td",null,"不打断它，再等同样长的时间；仍未完成才中断")]),i("tr",null,[i("td",null,"agent 报错（不是临时错误）"),i("td",null,"新开一个 agent 重做这一步一次；配置了备用模型时用备用模型")]),i("tr",null,[i("td",null,"提醒后仍没有有效的结果文件"),i("td",null,"新开一个 agent 重做这一步一次")]),i("tr",null,[i("td",null,"限流、额度用完，重试用完"),i("td",null,[l("配置了备用模型时，用备用模型再做一次；仍不行就中断，并按 Paseo 显示的额度恢复时间预约自动继续（恢复后 5 分钟；没有恢复时间时按 "),i("code",null,"autoResumeMinutes"),l("）")])]),i("tr",null,[i("td",null,"方案审核说需要需求方决定"),i("td",null,[l("先请 builder 从代码、文档和需求说明中找答案（"),i("code",null,"answerQuestionsFirst"),l("，默认 "),i("code",null,"true"),l("），只把真正的业务取舍连同推荐答案交给需求方；都能回答时不停下。最后一轮审核的问题被自答时，再加一轮审核复核这些答案（1.12.1）")])])])]),i("p",null,[i("strong",null,"备用模型"),l("（1.12，可选）："),i("code",null,"agents.fallback"),l("，写法同 builder、reviewer，可以用 "),i("code",null,"paseoProfile"),l("。"),i("code",null,"req configure"),l(' 和插件的"模型"设置页会推荐一个与主模型不同厂商的模型。')]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"agents"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"builder"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }, "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"reviewer"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }, "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"fallback"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"provider"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"opencode/<模型 ID>"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")])])])]),i("p",null,[l("自动处理的每一次都记在进度日志、状态文件的 "),i("code",null,"recoveries"),l(" 和使用记录中，"),i("code",null,"req stats"),l(' 的"人工介入"一节汇总：停下等人的原因、自动处理了多少次、到达提测的需求中没有非必要介入的比例。')]),i("p",null,[i("strong",null,"同一个目录一次只运行一条流水线"),l("，因为各步骤都在这个目录中修改和提交。需要并行时，为每个需求使用单独的 worktree 工作区。")]),i("h2",{id:"注意事项",tabindex:"-1"},[l("注意事项 "),i("a",{class:"header-anchor",href:"#注意事项","aria-label":'Permalink to "注意事项"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,"发起流水线的聊天 agent 需要能访问本机网络。"),l(" 流水线进程继承它的运行环境，需要连接 "),i("code",null,"ws://127.0.0.1:6767"),l("。用 Codex 做聊天 agent 时，请使用 "),i("code",null,"full-access"),l(" 模式；沙箱模式可能禁止网络。")]),i("li",null,[i("strong",null,"必须在仓库对应的项目对话中发起，对话过程中不要切换工作目录。"),l(" 步骤 agent 一律作为子 agent 挂在发起的对话下，而 Paseo 会让子 agent 使用父 agent 的工作目录，所以仓库目录必须就是这个对话的工作目录。在对话中启动时，"),i("code",null,"--repo"),l(" 默认就取对话的工作目录；两者不一致、或发起的对话已不存在时，流水线拒绝启动并说明原因。")]),i("li",null,[i("strong",null,"步骤 agent 以免确认模式运行"),l("，在本机拥有执行命令的权限。提示词禁止了危险操作，但这不是安全边界。请让仓库目录中不包含生产环境凭据。")]),i("li",null,[i("strong",null,"聊天被归档时"),l("，挂在它下面的步骤 agent 也会被归档；通知会发送失败，但流水线会继续运行到结束，结果仍可在 "),i("code",null,"report.md"),l(" 和日志中查看。")]),i("li",null,[i("strong",null,"daemon 重启"),l("会中断正在运行的步骤 agent。流水线会在连续 5 次无法获取状态后判定该步骤失败，之后可以用 "),i("code",null,"--resume"),l(" 继续。")])])],-1),i("p",{class:"source-note"},[l("本页由仓库中的 "),i("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/docs/guide/项目定制与运行规则.md"},"docs/guide/项目定制与运行规则.md"),l(" 生成。"),i("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/docs/guide/项目定制与运行规则.md"},"在 GitHub 上编辑")],-1)])])}const c=e(t,[["render",h]]);export{o as __pageData,c as default};
+`),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),i("ul",null,[i("li",null,[l("成员并行运行，在同一个目录里只读代码、写各自的意见文件（"),i("code",null,"<功能目录>/review-panel/"),l("），不提交，不改文件。")]),i("li",null,"某位成员失败时，只汇总完成的成员；全部失败时该步骤失败。"),i("li",null,"成本：每次启用的评审多出 N 个 agent 的用量，所以默认只用于标准档的第一轮。"),i("li",null,[l("成员的模型和模式会在 "),i("code",null,"/req-doctor"),l(" 中一并检查。")])]),i("h2",{id:"需求总览、决策记录、变更与验收记录",tabindex:"-1"},[l("需求总览、决策记录、变更与验收记录 "),i("a",{class:"header-anchor",href:"#需求总览、决策记录、变更与验收记录","aria-label":'Permalink to "需求总览、决策记录、变更与验收记录"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,"需求总览"),l("："),i("code",null,"node <req-kit>/bin/start-pipeline.mjs --list"),l(" 列出这个仓库所有 worktree 中的需求和各自的阶段（对齐中、开发中、待验收、已验收等）。总览现场生成，不提交到仓库，避免各分支合并时冲突。")]),i("li",null,[i("strong",null,"决策记录"),l(),i("code",null,"decisions.tsv"),l("：各步骤把不显而易见的选择（假设、取舍、偏离方案、驳回的评审意见、决定不修的问题）各记一行。会影响结果的标为 "),i("code",null,"needs_human=yes"),l('，完成报告把它们列入"需要你确认的决定"。')]),i("li",null,[i("strong",null,"变更记录"),l(),i("code",null,"changes.md"),l('：每次修改需求（包括方案审核提出问题、验收发现问题）记一节，spec 头部的"版本"随之加 1。')]),i("li",null,[i("strong",null,"验收记录"),l(),i("code",null,"acceptance.md"),l("：由 "),i("code",null,"/req"),l(" 的验收手册写，逐条记录验收结果和结论。")])]),i("p",null,[l("格式见 "),i("code",null,"contracts/feature-files.md"),l("。")]),i("h2",{id:"运行规则",tabindex:"-1"},[l("运行规则 "),i("a",{class:"header-anchor",href:"#运行规则","aria-label":'Permalink to "运行规则"'},"​")]),i("p",null,[i("strong",null,"步骤和轮数"),l("（轮数按档位，在配置的 "),i("code",null,"profiles"),l(" 中调整；下面是标准档的默认值）：")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"环节"),i("th",null,"规则")])]),i("tbody",null,[i("tr",null,[i("td",null,"评审小组（可选）"),i("td",null,"开启时，标准档的方案审核和代码评审第一轮先由小组成员并行评审，再由评审者核实汇总")]),i("tr",null,[i("td",null,"方案审核 ⇄ 方案修订"),i("td",null,'最多 2 轮审核。判定"阻塞"时暂停并请需求方决定；最后一轮仍要求修改时，修订后直接进入实现')]),i("tr",null,[i("td",null,"代码评审 ⇄ 评审问题修复"),i("td",null,"最多 3 轮评审，通过即止；轮数用完时修复后进入下一阶段")]),i("tr",null,[i("td",null,"提测说明"),i("td",null,[l("代码评审之后执行，写 "),i("code",null,"handoff.md"),l("。分阶段执行时研发阶段到此结束")])]),i("tr",null,[i("td",null,"服务启动验证"),i("td",null,[l("方案设计判断项目有常驻服务、且档位开启了 "),i("code",null,"serviceStart"),l(" 时才执行（在已部署的测试环境中验证时不执行）")])]),i("tr",null,[i("td",null,"缺陷修复 ⇄ 复验"),i("td",null,[l("功能验证发现缺陷时执行，最多 3 轮，复验通过即止（"),i("code",null,"phases.verify.defects"),l(" 为 "),i("code",null,"handback"),l(" 或 "),i("code",null,"report"),l(' 时见上文"执行方式"）')])]),i("tr",null,[i("td",null,"完成报告"),i("td",null,"只要没有暂停或中断就一定执行，遗留问题写进报告")]),i("tr",null,[i("td",null,"完成后继续"),i("td",null,[l("完成后 spec.md 被修改过（需求变更、验收发现问题），"),i("code",null,"--resume"),l(" 从方案设计开始，各步骤在已有方案和代码的基础上只处理变化的部分；没改过则拒绝。"),i("code",null,"--restart"),l(" 则完全从零开始")])]),i("tr",null,[i("td",null,"增量继续"),i("td",null,[l('需求变更、回答了方案审核的问题后继续时：方案在原文末尾追加"第 N 次尝试"一节；实现只改需要改的；代码评审只看本次开始以来的改动；验证重新验证变化涉及的验收标准，其余的至少跑一遍现有测试；报告说明是第几次。做法写在 '),i("code",null,"engine/prompts/incremental.md"),l("，可以用 "),i("code",null,"prompts.local/"),l(" 替换")])])])]),i("p",null,[i("strong",null,"结果文件"),l("：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。")]),i("p",null,[i("strong",null,"等待与超时"),l("：每步有总时限（"),i("code",null,"stepTimeoutMinutes"),l("）。到时 agent 还在做时，先再给它同样长的时间（"),i("code",null,"selfHeal"),l("，见下）；仍未完成才判定失败，但不停止 agent。继续（"),i("code",null,"--resume"),l("、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮（这一轮不再额外延长）；第二次仍超时才停止它、另起一个 agent。需求改过、开始了新一次尝试时，上一次留下的 agent 直接停掉，不接手（1.12.1）。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。")]),i("p",null,[i("strong",null,"临时错误自动重试"),l("：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"retry"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"attempts"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"2"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"backoffSeconds"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": ["),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"60"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"300"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"] }")])])])]),i("p",null,[i("code",null,"attempts"),l(" 设为 0 关闭；"),i("code",null,"backoffSeconds"),l(" 的个数少于重试次数时，后面的重试使用最后一个值。超时、结果文件不合格、agent 自己判定失败等不是临时错误，不按这里重试。重试用完仍失败时，中断通知会注明已重试的次数。")]),i("p",null,[i("strong",null,"自愈"),l("（1.12，"),i("code",null,"selfHeal"),l("，默认 "),i("code",null,"true"),l("）：能安全自动处理的中断不再等人。")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"情况"),i("th",null,"自动处理")])]),i("tbody",null,[i("tr",null,[i("td",null,"步骤超时，agent 还在做"),i("td",null,"不打断它，再等同样长的时间；仍未完成才中断")]),i("tr",null,[i("td",null,"agent 报错（不是临时错误）"),i("td",null,"新开一个 agent 重做这一步一次；配置了备用模型时用备用模型")]),i("tr",null,[i("td",null,"提醒后仍没有有效的结果文件"),i("td",null,"新开一个 agent 重做这一步一次")]),i("tr",null,[i("td",null,"限流、额度用完，重试用完"),i("td",null,[l("配置了备用模型时，用备用模型再做一次；仍不行就中断，并按 Paseo 显示的额度恢复时间预约自动继续（恢复后 5 分钟；没有恢复时间时按 "),i("code",null,"autoResumeMinutes"),l("）")])]),i("tr",null,[i("td",null,"方案审核说需要需求方决定"),i("td",null,[l("先请 builder 从代码、文档和需求说明中找答案（"),i("code",null,"answerQuestionsFirst"),l("，默认 "),i("code",null,"true"),l("），只把真正的业务取舍连同推荐答案交给需求方；都能回答时不停下。最后一轮审核的问题被自答时，再加一轮审核复核这些答案（1.12.1）")])])])]),i("p",null,[i("strong",null,"备用模型"),l("（1.12，可选）："),i("code",null,"agents.fallback"),l("，写法同 builder、reviewer，可以用 "),i("code",null,"paseoProfile"),l("。"),i("code",null,"req configure"),l(' 和插件的"模型"设置页会推荐一个与主模型不同厂商的模型。')]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"agents"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"builder"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }, "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"reviewer"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }, "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"fallback"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"provider"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"opencode/<模型 ID>"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")])])])]),i("p",null,[l("自动处理的每一次都记在进度日志、状态文件的 "),i("code",null,"recoveries"),l(" 和使用记录中，"),i("code",null,"req stats"),l(' 的"人工介入"一节汇总：停下等人的原因、自动处理了多少次、到达提测的需求中没有非必要介入的比例。')]),i("p",null,[i("strong",null,"同一个目录一次只运行一条流水线"),l("，因为各步骤都在这个目录中修改和提交。需要并行时，为每个需求使用单独的 worktree 工作区。")]),i("h2",{id:"注意事项",tabindex:"-1"},[l("注意事项 "),i("a",{class:"header-anchor",href:"#注意事项","aria-label":'Permalink to "注意事项"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,"发起流水线的聊天 agent 需要能访问本机网络。"),l(" 流水线进程继承它的运行环境，需要连接 "),i("code",null,"ws://127.0.0.1:6767"),l("。用 Codex 做聊天 agent 时，请使用 "),i("code",null,"full-access"),l(" 模式；沙箱模式可能禁止网络。")]),i("li",null,[i("strong",null,"必须在仓库对应的项目对话中发起，对话过程中不要切换工作目录。"),l(" 步骤 agent 一律作为子 agent 挂在发起的对话下，而 Paseo 会让子 agent 使用父 agent 的工作目录，所以仓库目录必须就是这个对话的工作目录。在对话中启动时，"),i("code",null,"--repo"),l(" 默认就取对话的工作目录；两者不一致、或发起的对话已不存在时，流水线拒绝启动并说明原因。")]),i("li",null,[i("strong",null,"步骤 agent 以免确认模式运行"),l("，在本机拥有执行命令的权限。提示词禁止了危险操作，但这不是安全边界。请让仓库目录中不包含生产环境凭据。")]),i("li",null,[i("strong",null,"聊天被归档时"),l("，挂在它下面的步骤 agent 也会被归档；通知会发送失败，但流水线会继续运行到结束，结果仍可在 "),i("code",null,"report.md"),l(" 和日志中查看。")]),i("li",null,[i("strong",null,"daemon 重启"),l("会中断正在运行的步骤 agent。流水线会在连续 5 次无法获取状态后判定该步骤失败，之后可以用 "),i("code",null,"--resume"),l(" 继续。")])])],-1),i("p",{class:"source-note"},[l("本页由仓库中的 "),i("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/docs/guide/项目定制与运行规则.md"},"docs/guide/项目定制与运行规则.md"),l(" 生成。"),i("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/docs/guide/项目定制与运行规则.md"},"在 GitHub 上编辑")],-1)])])}const c=e(t,[["render",h]]);export{p as __pageData,c as default};

package/site-dist/assets/{guide_user.md.tiHFxIsQ.js → guide_user.md.Cenm9vlN.js}

@@ -1 +1 @@
-import{_ as o,o as e,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"使用者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/user.md","filePath":"guide/user.md","lastUpdated":null}'),u={name:"guide/user.md"};function s(a,t,i,l,q,n){return e(),r("div",null,[...t[0]||(t[0]=[d('<div><h1 id="使用者指南" tabindex="-1">使用者指南 <a class="header-anchor" href="#使用者指南" aria-label="Permalink to &quot;使用者指南&quot;">​</a></h1><p>req-kit 帮你把一个需求从&quot;我想要……&quot;做到&quot;可以验收&quot;：你在 Paseo 的对话里把需求讲清楚、确认一份需求说明，之后的方案设计、写代码、评审、测试和报告由一组 AI agent 在后台完成，结果发回同一个对话。</p><p>适合测试、产品经理、项目经理等不写代码、但熟悉需求和测试的同事。你不需要读代码，但可以随时查看每一步的产物，也可以亲自执行测试命令核对结果。</p><h2 id="第一次使用之前" tabindex="-1">第一次使用之前 <a class="header-anchor" href="#第一次使用之前" aria-label="Permalink to &quot;第一次使用之前&quot;">​</a></h2><p>请开发同事确认这台机器已经装好 req-kit（<code>/req-doctor</code> 全部正常），并且项目已经接入：在项目根目录的对话中运行过 <code>/req-setup</code>，生成了项目说明和验证方法。测试同事熟悉项目的话，也可以自己运行 <code>/req-setup</code>。</p><h2 id="提一个需求" tabindex="-1">提一个需求 <a class="header-anchor" href="#提一个需求" aria-label="Permalink to &quot;提一个需求&quot;">​</a></h2><ol><li><strong>准备工作区</strong>：每个需求最好有自己的 worktree 工作区，几个需求可以同时进行，互不影响。两种方式任选： <ul><li>直接在项目的对话里开始，AI 问到时选&quot;开发时自动新建工作区&quot;：照常谈需求，启动开发时流水线会自动新建工作区并在那里开发，这个对话不用动。</li><li>自己新建：在 Paseo 中点 <strong>New workspace</strong> → 选择项目 → <strong>Isolation</strong> 选 <strong>New worktree</strong> → 起点选主分支，然后在新工作区的对话里开始。</li></ul></li><li><strong>输入 <code>/req</code> 和一句话</strong>：例如 <code>/req 登录页增加短信验证码登录</code>。用 Pi 时输入 <code>/skill:req ……</code>。</li><li><strong>回答问题</strong>：AI 会先复述它的理解，然后一次问一个问题，给出选项和推荐。它会问到异常情况、权限、已有数据、测试数据和验证环境，这些往往是你最清楚的。拿不准时可以说&quot;你定&quot;，它会采用推荐项并记为假设，最后请你过目。</li><li><strong>独立审阅</strong>（标准档）：确认之前，AI 会请另一个模型把需求说明独立审一遍，几分钟后把发现的问题（歧义、遗漏、没法验证的验收标准）逐个问你。这一步常常能省掉开发之后的返工。</li><li><strong>确认需求说明</strong>：AI 给出一份 10 行以内的摘要，完整的需求说明在 <code>docs/features/&lt;日期&gt;-&lt;名称&gt;/spec.md</code>。确认后它会问是否开始开发。</li><li><strong>等待</strong>：开发在后台进行，通常需要几个小时，不需要盯着。期间你会收到几句进展（方案定了、开始验证等）。</li></ol><p>小改动（改文案、样式、一个配置项）会走快速流程：只问 2–3 个问题，开发环节各做一轮。</p><p><strong>需求的类型</strong>：AI 复述时会和你确认这是哪一类，流水线按类型走不同的做法：</p><table tabindex="0"><thead><tr><th>类型</th><th>说法举例</th><th>流水线怎么做</th><th>你需要讲清楚的</th></tr></thead><tbody><tr><td>新需求</td><td>&quot;加一个……&quot;</td><td>方案、实现、评审、验证</td><td>要什么、怎么算做对</td></tr><tr><td>缺陷</td><td>&quot;……不对&quot;&quot;报错了&quot;</td><td>先复现、找到原因再修；复现不了会回来问你</td><td>复现步骤：环境、账号或数据、操作、看到的、应有的</td></tr><tr><td>重构</td><td>&quot;整理一下……&quot;&quot;升级依赖&quot;</td><td>先用测试锁住现有行为，再小步改，确认行为没变</td><td>改进目标，以及哪些行为必须保持不变</td></tr><tr><td>评估</td><td>&quot;能不能做……&quot;&quot;影响多大&quot;</td><td>只调研、写评估报告，由另一个模型审阅，不写代码</td><td>要回答的问题，结论用来做什么决定</td></tr></tbody></table><p>评估做完后，可以直接说&quot;按评估结果提一个新需求&quot;。</p><p><strong>前端和后端都要改</strong>：另一个仓库已经由开发同事登记过（<code>/req-setup</code> 时登记）的，AI 会问是否作为联合需求一起做：流水线先设计整体方案和双方的接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证，报告里写明每个仓库的分支和合并顺序。</p><p><strong>验收标准带例子</strong>：AI 写验收标准时会给每条配上具体的数据（&quot;输入 13800000000，60 秒内再点发送，提示&#39;请 45 秒后重试&#39;&quot;）。请认真看这些例子：它们会直接变成测试检查的期望值，你确认的就是测试会检查的东西。</p><p><strong>开工前先看一眼&quot;做完后会看到什么&quot;</strong>（标准档的界面改动）：方案审核通过后、写代码之前，流水线会停下来，AI 把 <code>preview.md</code> 的要点讲给你听：会看到什么变化、有哪些需要你确认的假设；界面改动还会有静态的原型页面（功能目录的 <code>prototype/</code> 中），可以在浏览器里打开看。说&quot;可以&quot;就开始写代码；想改的直接说，AI 会更新需求说明，方案调整后再请你看一次。这时调整的成本最低。</p><p><strong>研发和测试分开做</strong>（标准档，确定档位时 AI 会问，团队配置里定好了就不问）：</p><ul><li><strong>连续</strong>（默认）：研发完成后流水线接着做测试验证，一次跑完。</li><li><strong>分阶段</strong>：研发完成、写好提测说明（<code>handoff.md</code>）后停下来通知你：&quot;研发完成，可以提测&quot;。你或测试同事准备好之后说&quot;开始测试验证&quot;，AI 会讲一遍提测说明，问清在哪里测（本地，或已部署的测试环境）、发现缺陷怎么办（当场修复、退回研发修复后再提测，或只记录），然后开始；也可以预约时间。用&quot;开发时自动新建工作区&quot;开发的需求，测试同事可以在自己的对话里输入 <code>/req 开始测试验证 &lt;需求名称&gt;</code> 接手。</li><li><strong>只做研发</strong>：做到提测说明和研发报告为止，测试由人完成，验收时 AI 会按提测说明带你逐条测试。</li></ul><h2 id="过程中" tabindex="-1">过程中 <a class="header-anchor" href="#过程中" aria-label="Permalink to &quot;过程中&quot;">​</a></h2><table tabindex="0"><thead><tr><th>你想做的</th><th>在对话里说</th></tr></thead><tbody><tr><td>看进度</td><td>&quot;做到哪了&quot;（会说明当前在哪一步、agent 最近在做什么，例如正在运行测试）</td></tr><tr><td>暂停</td><td>&quot;先停一下&quot;（当前步骤做到一半的工作不保留，已完成的步骤保留）</td></tr><tr><td>继续</td><td>&quot;继续开发&quot;</td></tr><tr><td>确认方案</td><td>收到&quot;请确认方案&quot;时，看过之后说&quot;可以，按这个做&quot;，或者说要改哪里</td></tr><tr><td>改需求</td><td>&quot;我想改一下……&quot;：先暂停，谈清变化的部分，更新需求说明（版本加 1，记入 <code>changes.md</code>）后继续，开发会在已有方案和代码的基础上只处理变化的部分。开发已经完成的也可以改</td></tr><tr><td>看看项目里有哪些需求</td><td>&quot;现在有哪些需求&quot;：列出所有工作区中的需求和各自的阶段</td></tr><tr><td>研发完成后提测</td><td>&quot;开始测试验证&quot;（分阶段执行时）；想晚点开始就说&quot;等测试环境部署好，明早 9 点开始测试&quot;</td></tr><tr><td>晚点再开始</td><td>确认需求后说&quot;今晚 10 点开始&quot;&quot;明天早上开始&quot;：到时会在这个对话里自动开始，说&quot;先停一下&quot;可以取消</td></tr><tr><td>接手别人的需求</td><td>&quot;这个需求之前是同事提的，现在什么情况&quot;：讲清现状、待决事项和下一步</td></tr></tbody></table><p>也可以不进对话，在终端里用 <code>req</code> 命令（需要开发同事装好并加入 PATH，见 <a href="./install">安装与升级</a>）：在项目目录中 <code>req list</code> 看所有需求，<code>req status</code> 看进度（多个需求时写名称的一部分，如 <code>req status sms-login</code>），<code>req stop</code>、<code>req resume</code> 暂停和继续。</p><p>装了 req-kit 插件的话（见 <a href="./install">安装与升级</a> 第 13 节），在 Paseo 侧边栏点&quot;需求&quot;：本机所有项目的需求一页看完，&quot;需要你处理&quot;的排在最前；点开一个需求能看到每一步的进度和用时、读需求说明、方案、确认预览和完成报告，也可以直接确认方案、停止、继续或开始测试验证。网页端、桌面版和手机上都能用。</p><p>1.12 起，首页最上面是&quot;等你处理&quot;：所有等你确认方案、回答问题、中断了的需求，等得最久的在前，每条写明要做什么、等了多久。方案可以直接确认，也可以写修改意见；方案审核的问题可以直接写回答，插件会转给这个需求的对话，效果和在对话里回答一样。首页的&quot;配置&quot;列出 req-kit 的全部设置：每一项是什么、现在的值、来自本机、团队还是项目的配置文件，可以按项目查看、搜索、只看改过的。</p><p><strong>在原型上提意见（1.13 起）。</strong> 界面改动的需求，在请你确认方案时会有一份界面原型。在插件的需求页面或&quot;等你处理&quot;里点&quot;打开原型审查页&quot;（或在终端运行 <code>req review &lt;需求&gt;</code>），会在浏览器里打开它：</p><ul><li>标着 ①②③ 的是这次要改的地方，右边写着各自对应的验收标准，顺着看就不会漏。</li><li>想改哪里就<strong>点哪里</strong>，选一种改法（文字改成…、大一点、换颜色、换位置、删掉、这里加东西……），再用自己的话补一句。不用想专业词汇，你点的是哪个按钮、原来是什么颜色和大小，页面会自动记下来交给 AI。</li><li>想换文字就<strong>双击文字</strong>，直接改成你想要的字。</li><li>正常、出错、空数据这些状态，以及电脑、手机宽度，在页面上方切换。</li><li>写的意见会自动保存。看完后点&quot;提交修改意见&quot;，需求会话会据此改需求说明，改好后请你再确认；改过的原型再打开时，会用绿色框标出这一版改了哪里。没有要改的，点&quot;同意开始写代码&quot;。</li></ul><p>每个步骤都会出现在这个对话的子 agent 列表里（名字形如&quot;[20261012-sms-login] 6-代码评审 第2轮&quot;），点开可以看到它在做什么。功能目录下的 <code>progress.md</code> 按时间记录了每一步的结果。</p><p>可能收到的通知（团队接入了企业 IM 的话，这些通知也会发到 IM）：</p><ul><li><strong>需要你决定</strong>：方案审核发现只有你能回答的问题。AI 会逐个问你，然后继续。一天没有回答的话，会在对话里提醒一次。</li><li><strong>研发完成，可以提测</strong>（分阶段执行时）：代码已写完并通过评审，提测说明在 <code>handoff.md</code>。一天没有开始测试验证的话，会在对话里提醒一次。</li><li><strong>等待批准</strong>：某一步在等权限批准，按提示打开对应的 agent 处理，或请开发同事处理。</li><li><strong>中断</strong>：限流、网络中断这类临时问题会先自动等待重试，仍然不行才中断，并预约半小时后自动继续（说&quot;先停一下&quot;可以取消）。AI 会说明原因和日志位置。环境类问题（例如测试服务没启动）你可以自己处理；涉及配置或代码的请开发同事处理。处理后说&quot;继续开发&quot;。</li></ul><h2 id="验收" tabindex="-1">验收 <a class="header-anchor" href="#验收" aria-label="Permalink to &quot;验收&quot;">​</a></h2><p>完成后你会收到结论和摘要，完整报告在功能目录的 <code>report.md</code>：</p><ul><li><strong>验收对照表</strong>：每条验收标准的结果，以及是怎么确认的（运行了什么命令、看到了什么、截图在哪里）。</li><li><strong>需要你确认的决定</strong>：开发过程中替你做的假设和取舍，以及被驳回的评审意见里会影响结果的那些。请逐条表态。</li><li><strong>遗留问题</strong>和<strong>需要你做的事</strong>。</li><li><strong>用时与用量</strong>：各步骤 agent 合计用了多长时间、多少 token、大约多少费用，便于估算后续需求的成本。</li></ul><p>然后说&quot;我要验收&quot;。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 <code>acceptance.md</code>。</p><ul><li><strong>全部通过</strong>：请开发同事审阅代码并合并上线。流水线只做本地提交，不会自己合并或上线。</li><li><strong>有不通过的</strong>：逐项决定怎么处理：做得不对的，补进需求说明后继续开发；发现想要的不是这样的，按改需求处理；也可以接受现状并记下理由。</li></ul><p>测试同事可以把验收标准直接转成测试用例：每条都写成了&quot;前置条件 / 操作 / 预期结果&quot;。</p><h2 id="上线后发现问题" tabindex="-1">上线后发现问题 <a class="header-anchor" href="#上线后发现问题" aria-label="Permalink to &quot;上线后发现问题&quot;">​</a></h2><p>说&quot;线上发现……不对&quot;。AI 会先问这个问题是否正在影响真实用户：是的话，请马上联系开发同事或值班人员处理线上情况（req-kit 不碰生产环境）。然后它会问清现象、复现步骤、影响范围，关联到原来的需求，生成一份缺陷说明，按快速流程修复，修复后照常验收。</p><h2 id="注意" tabindex="-1">注意 <a class="header-anchor" href="#注意" aria-label="Permalink to &quot;注意&quot;">​</a></h2><ul><li>一个对话只谈一个需求；对话过程中不要切换工作目录。</li><li>需求属于另一个项目时，到那个项目里新开对话。</li><li>遇到&quot;未启动&quot;或其他看不懂的情况，输入 <code>/req-doctor</code> 做一次体检，或请开发同事看一下。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/guide/使用者指南.md">docs/guide/使用者指南.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/guide/使用者指南.md">在 GitHub 上编辑</a></p>',2)])])}const p=o(u,[["render",s]]);export{g as __pageData,p as default};
+import{_ as o,o as e,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"使用者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/user.md","filePath":"guide/user.md","lastUpdated":null}'),u={name:"guide/user.md"};function s(a,t,q,i,l,n){return e(),r("div",null,[...t[0]||(t[0]=[d('<div><h1 id="使用者指南" tabindex="-1">使用者指南 <a class="header-anchor" href="#使用者指南" aria-label="Permalink to &quot;使用者指南&quot;">​</a></h1><p>req-kit 帮你把一个需求从&quot;我想要……&quot;做到&quot;可以验收&quot;：你在 Paseo 的对话里把需求讲清楚、确认一份需求说明，之后的方案设计、写代码、评审、测试和报告由一组 AI agent 在后台完成，结果发回同一个对话。</p><p>适合测试、产品经理、项目经理等不写代码、但熟悉需求和测试的同事。你不需要读代码，但可以随时查看每一步的产物，也可以亲自执行测试命令核对结果。</p><h2 id="第一次使用之前" tabindex="-1">第一次使用之前 <a class="header-anchor" href="#第一次使用之前" aria-label="Permalink to &quot;第一次使用之前&quot;">​</a></h2><p>请开发同事确认这台机器已经装好 req-kit（<code>/req-doctor</code> 全部正常），并且项目已经接入：在项目根目录的对话中运行过 <code>/req-setup</code>，生成了项目说明和验证方法。测试同事熟悉项目的话，也可以自己运行 <code>/req-setup</code>。</p><h2 id="提一个需求" tabindex="-1">提一个需求 <a class="header-anchor" href="#提一个需求" aria-label="Permalink to &quot;提一个需求&quot;">​</a></h2><ol><li><strong>准备工作区</strong>：每个需求最好有自己的 worktree 工作区，几个需求可以同时进行，互不影响。两种方式任选： <ul><li>直接在项目的对话里开始，AI 问到时选&quot;开发时自动新建工作区&quot;：照常谈需求，启动开发时流水线会自动新建工作区并在那里开发，这个对话不用动。</li><li>自己新建：在 Paseo 中点 <strong>New workspace</strong> → 选择项目 → <strong>Isolation</strong> 选 <strong>New worktree</strong> → 起点选主分支，然后在新工作区的对话里开始。</li></ul></li><li><strong>输入 <code>/req</code> 和一句话</strong>：例如 <code>/req 登录页增加短信验证码登录</code>。用 Pi 时输入 <code>/skill:req ……</code>。</li><li><strong>回答问题</strong>：AI 会先复述它的理解，然后一次问一个问题，给出选项和推荐。它会问到异常情况、权限、已有数据、测试数据和验证环境，这些往往是你最清楚的。拿不准时可以说&quot;你定&quot;，它会采用推荐项并记为假设，最后请你过目。</li><li><strong>独立审阅</strong>（标准档）：确认之前，AI 会请另一个模型把需求说明独立审一遍，几分钟后把发现的问题（歧义、遗漏、没法验证的验收标准）逐个问你。这一步常常能省掉开发之后的返工。</li><li><strong>确认需求说明</strong>：AI 给出一份 10 行以内的摘要，完整的需求说明在 <code>docs/features/&lt;日期&gt;-&lt;名称&gt;/spec.md</code>。确认后它会问是否开始开发。</li><li><strong>等待</strong>：开发在后台进行，通常需要几个小时，不需要盯着。期间你会收到几句进展（方案定了、开始验证等）。</li></ol><p>小改动（改文案、样式、一个配置项）会走快速流程：只问 2–3 个问题，开发环节各做一轮。</p><p><strong>需求的类型</strong>：AI 复述时会和你确认这是哪一类，流水线按类型走不同的做法：</p><table tabindex="0"><thead><tr><th>类型</th><th>说法举例</th><th>流水线怎么做</th><th>你需要讲清楚的</th></tr></thead><tbody><tr><td>新需求</td><td>&quot;加一个……&quot;</td><td>方案、实现、评审、验证</td><td>要什么、怎么算做对</td></tr><tr><td>缺陷</td><td>&quot;……不对&quot;&quot;报错了&quot;</td><td>先复现、找到原因再修；复现不了会回来问你</td><td>复现步骤：环境、账号或数据、操作、看到的、应有的</td></tr><tr><td>重构</td><td>&quot;整理一下……&quot;&quot;升级依赖&quot;</td><td>先用测试锁住现有行为，再小步改，确认行为没变</td><td>改进目标，以及哪些行为必须保持不变</td></tr><tr><td>评估</td><td>&quot;能不能做……&quot;&quot;影响多大&quot;</td><td>只调研、写评估报告，由另一个模型审阅，不写代码</td><td>要回答的问题，结论用来做什么决定</td></tr></tbody></table><p>评估做完后，可以直接说&quot;按评估结果提一个新需求&quot;。</p><p><strong>前端和后端都要改</strong>：另一个仓库已经由开发同事登记过（<code>/req-setup</code> 时登记）的，AI 会问是否作为联合需求一起做：流水线先设计整体方案和双方的接口约定，再在每个仓库各开一个工作区同时开发，最后一起验证，报告里写明每个仓库的分支和合并顺序。</p><p><strong>验收标准带例子</strong>：AI 写验收标准时会给每条配上具体的数据（&quot;输入 13800000000，60 秒内再点发送，提示&#39;请 45 秒后重试&#39;&quot;）。请认真看这些例子：它们会直接变成测试检查的期望值，你确认的就是测试会检查的东西。</p><p><strong>开工前先看一眼&quot;做完后会看到什么&quot;</strong>（标准档的界面改动）：方案审核通过后、写代码之前，流水线会停下来，AI 把 <code>preview.md</code> 的要点讲给你听：会看到什么变化、有哪些需要你确认的假设；界面改动还会有静态的原型页面（功能目录的 <code>prototype/</code> 中），可以在浏览器里打开看。说&quot;可以&quot;就开始写代码；想改的直接说，AI 会更新需求说明，方案调整后再请你看一次。这时调整的成本最低。</p><p><strong>研发和测试分开做</strong>（标准档，确定档位时 AI 会问，团队配置里定好了就不问）：</p><ul><li><strong>连续</strong>（默认）：研发完成后流水线接着做测试验证，一次跑完。</li><li><strong>分阶段</strong>：研发完成、写好提测说明（<code>handoff.md</code>）后停下来通知你：&quot;研发完成，可以提测&quot;。你或测试同事准备好之后说&quot;开始测试验证&quot;，AI 会讲一遍提测说明，问清在哪里测（本地，或已部署的测试环境）、发现缺陷怎么办（当场修复、退回研发修复后再提测，或只记录），然后开始；也可以预约时间。用&quot;开发时自动新建工作区&quot;开发的需求，测试同事可以在自己的对话里输入 <code>/req 开始测试验证 &lt;需求名称&gt;</code> 接手。</li><li><strong>只做研发</strong>：做到提测说明和研发报告为止，测试由人完成，验收时 AI 会按提测说明带你逐条测试。</li></ul><h2 id="过程中" tabindex="-1">过程中 <a class="header-anchor" href="#过程中" aria-label="Permalink to &quot;过程中&quot;">​</a></h2><table tabindex="0"><thead><tr><th>你想做的</th><th>在对话里说</th></tr></thead><tbody><tr><td>看进度</td><td>&quot;做到哪了&quot;（会说明当前在哪一步、agent 最近在做什么，例如正在运行测试）</td></tr><tr><td>暂停</td><td>&quot;先停一下&quot;（当前步骤做到一半的工作不保留，已完成的步骤保留）</td></tr><tr><td>继续</td><td>&quot;继续开发&quot;</td></tr><tr><td>确认方案</td><td>收到&quot;请确认方案&quot;时，看过之后说&quot;可以，按这个做&quot;，或者说要改哪里</td></tr><tr><td>改需求</td><td>&quot;我想改一下……&quot;：先暂停，谈清变化的部分，更新需求说明（版本加 1，记入 <code>changes.md</code>）后继续，开发会在已有方案和代码的基础上只处理变化的部分。开发已经完成的也可以改</td></tr><tr><td>看看项目里有哪些需求</td><td>&quot;现在有哪些需求&quot;：列出所有工作区中的需求和各自的阶段</td></tr><tr><td>研发完成后提测</td><td>&quot;开始测试验证&quot;（分阶段执行时）；想晚点开始就说&quot;等测试环境部署好，明早 9 点开始测试&quot;</td></tr><tr><td>晚点再开始</td><td>确认需求后说&quot;今晚 10 点开始&quot;&quot;明天早上开始&quot;：到时会在这个对话里自动开始，说&quot;先停一下&quot;可以取消</td></tr><tr><td>接手别人的需求</td><td>&quot;这个需求之前是同事提的，现在什么情况&quot;：讲清现状、待决事项和下一步</td></tr></tbody></table><p>也可以不进对话，在终端里用 <code>req</code> 命令（需要开发同事装好并加入 PATH，见 <a href="./install">安装与升级</a>）：在项目目录中 <code>req list</code> 看所有需求，<code>req status</code> 看进度（多个需求时写名称的一部分，如 <code>req status sms-login</code>），<code>req stop</code>、<code>req resume</code> 暂停和继续。</p><p>装了 req-kit 插件的话（见 <a href="./install">安装与升级</a> 第 13 节），在 Paseo 侧边栏点&quot;需求&quot;：本机所有项目的需求一页看完，&quot;需要你处理&quot;的排在最前；点开一个需求能看到每一步的进度和用时、读需求说明、方案、确认预览和完成报告，也可以直接确认方案、停止、继续或开始测试验证。网页端、桌面版和手机上都能用。</p><p>1.12 起，首页最上面是&quot;等你处理&quot;：所有等你确认方案、回答问题、中断了的需求，等得最久的在前，每条写明要做什么、等了多久。方案可以直接确认，也可以写修改意见；方案审核的问题可以直接写回答，插件会转给这个需求的对话，效果和在对话里回答一样。首页的&quot;配置&quot;列出 req-kit 的全部设置：每一项是什么、现在的值、来自本机、团队还是项目的配置文件，可以按项目查看、搜索、只看改过的。</p><p><strong>在原型上提意见（1.13 起）。</strong> 界面改动的需求，在请你确认方案时会有一份界面原型。在插件首页的&quot;等你处理&quot;或需求页面最上面，点**&quot;审查原型并确认方案&quot;**按钮（终端里是 <code>req review &lt;需求&gt;</code>），原型审查页就在 Paseo 里打开（手机上会在浏览器中打开；嫌窗口小时点右上角&quot;在新窗口打开&quot;）：</p><ul><li>标着 ①②③ 的是这次要改的地方，右边写着各自对应的验收标准，顺着看就不会漏。</li><li>想改哪里就<strong>点哪里</strong>，选一种改法（文字改成…、大一点、换颜色、换位置、删掉、这里加东西……），再用自己的话补一句。不用想专业词汇，你点的是哪个按钮、原来是什么颜色和大小，页面会自动记下来交给 AI。</li><li>想换文字就<strong>双击文字</strong>，直接改成你想要的字。</li><li>正常、出错、空数据这些状态，以及电脑、手机宽度，在页面上方切换。</li><li>写的意见会自动保存。看完后点&quot;提交修改意见&quot;，需求会话会据此改需求说明，改好后请你再确认；改过的原型再打开时，会用绿色框标出这一版改了哪里。没有要改的，点&quot;同意开始写代码&quot;。</li></ul><p><strong>还要多久（1.13 起）。</strong> 本机做完过 3 个以上同档位的需求后，开始开发时会告诉你这类需求通常要多久、用多少 token；问&quot;做到哪了&quot;或在插件的需求页面里，会看到&quot;预计还要约多久&quot;（不含等人确认的时间）。</p><p>每个步骤都会出现在这个对话的子 agent 列表里（名字形如&quot;[20261012-sms-login] 6-代码评审 第2轮&quot;），点开可以看到它在做什么。功能目录下的 <code>progress.md</code> 按时间记录了每一步的结果。</p><p>可能收到的通知（团队接入了企业 IM 的话，这些通知也会发到 IM）：</p><ul><li><strong>需要你决定</strong>：方案审核发现只有你能回答的问题。AI 会逐个问你，然后继续。一天没有回答的话，会在对话里提醒一次。</li><li><strong>研发完成，可以提测</strong>（分阶段执行时）：代码已写完并通过评审，提测说明在 <code>handoff.md</code>。一天没有开始测试验证的话，会在对话里提醒一次。</li><li><strong>等待批准</strong>：某一步在等权限批准，按提示打开对应的 agent 处理，或请开发同事处理。1.13 起插件的&quot;等你处理&quot;里也会显示，列出要批准的操作，点&quot;打开这个 agent&quot;直接去处理。</li><li><strong>token 用量提醒</strong>（团队设了 token 预算时）：用到预算的一定比例时告知一次，开发照常进行；用完时做完当前步骤就停下，AI 会告诉你用了多少、问你是否继续。继续会再给一份预算。</li><li><strong>中断</strong>：限流、网络中断这类临时问题会先自动等待重试，仍然不行才中断，并预约半小时后自动继续（说&quot;先停一下&quot;可以取消）。AI 会说明原因和日志位置。环境类问题（例如测试服务没启动）你可以自己处理；涉及配置或代码的请开发同事处理。处理后说&quot;继续开发&quot;。</li></ul><h2 id="验收" tabindex="-1">验收 <a class="header-anchor" href="#验收" aria-label="Permalink to &quot;验收&quot;">​</a></h2><p>完成后你会收到结论和摘要，完整报告在功能目录的 <code>report.md</code>：</p><ul><li><strong>验收对照表</strong>：每条验收标准的结果，以及是怎么确认的（运行了什么命令、看到了什么、截图在哪里）。</li><li><strong>需要你确认的决定</strong>：开发过程中替你做的假设和取舍，以及被驳回的评审意见里会影响结果的那些。请逐条表态。</li><li><strong>遗留问题</strong>和<strong>需要你做的事</strong>。</li><li><strong>用时与用量</strong>：各步骤 agent 合计用了多长时间、多少 token、大约多少费用，便于估算后续需求的成本。</li></ul><p>然后说&quot;我要验收&quot;。AI 会按验收标准一条一条带你核对：告诉你怎么操作、应该看到什么；能用命令验证的给出命令，你可以自己执行。每条结果记入功能目录的 <code>acceptance.md</code>。</p><ul><li><strong>全部通过</strong>：请开发同事审阅代码并合并上线。流水线只做本地提交，不会自己合并或上线。</li><li><strong>有不通过的</strong>：逐项决定怎么处理：做得不对的，补进需求说明后继续开发；发现想要的不是这样的，按改需求处理；也可以接受现状并记下理由。</li></ul><p>测试同事可以把验收标准直接转成测试用例：每条都写成了&quot;前置条件 / 操作 / 预期结果&quot;。</p><h2 id="上线后发现问题" tabindex="-1">上线后发现问题 <a class="header-anchor" href="#上线后发现问题" aria-label="Permalink to &quot;上线后发现问题&quot;">​</a></h2><p>说&quot;线上发现……不对&quot;。AI 会先问这个问题是否正在影响真实用户：是的话，请马上联系开发同事或值班人员处理线上情况（req-kit 不碰生产环境）。然后它会问清现象、复现步骤、影响范围，关联到原来的需求，生成一份缺陷说明，按快速流程修复，修复后照常验收。</p><h2 id="注意" tabindex="-1">注意 <a class="header-anchor" href="#注意" aria-label="Permalink to &quot;注意&quot;">​</a></h2><ul><li>一个对话只谈一个需求；对话过程中不要切换工作目录。</li><li>需求属于另一个项目时，到那个项目里新开对话。</li><li>遇到&quot;未启动&quot;或其他看不懂的情况，输入 <code>/req-doctor</code> 做一次体检，或请开发同事看一下。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/guide/使用者指南.md">docs/guide/使用者指南.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/guide/使用者指南.md">在 GitHub 上编辑</a></p>',2)])])}const p=o(u,[["render",s]]);export{g as __pageData,p as default};

package/site-dist/assets/{guide_user.md.tiHFxIsQ.lean.js → guide_user.md.Cenm9vlN.lean.js}

@@ -1 +1 @@
-import{_ as o,o as e,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"使用者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/user.md","filePath":"guide/user.md","lastUpdated":null}'),u={name:"guide/user.md"};function s(a,t,i,l,q,n){return e(),r("div",null,[...t[0]||(t[0]=[d("",2)])])}const p=o(u,[["render",s]]);export{g as __pageData,p as default};
+import{_ as o,o as e,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const g=JSON.parse('{"title":"使用者指南","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/user.md","filePath":"guide/user.md","lastUpdated":null}'),u={name:"guide/user.md"};function s(a,t,q,i,l,n){return e(),r("div",null,[...t[0]||(t[0]=[d("",2)])])}const p=o(u,[["render",s]]);export{g as __pageData,p as default};

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

@@ -0,0 +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")])]),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

@@ -0,0 +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")])]),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};