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

package/site-dist/assets/{guide_project.md.r2g5uU_4.js → guide_project.md.nGlTCo4D.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("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 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(`
 `),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("步骤 agent 有 Paseo 浏览器工具（Paseo 设置中打开 Enable Paseo tools 和浏览器工具，桌面端在线）时，功能验证、缺陷修复、复验按验收标准在浏览器中实际操作。"),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:"并行编排-确认前审阅、方案提案、浏览器验证",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"}},"  {")]),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(`

package/site-dist/assets/{guide_project.md.r2g5uU_4.lean.js → guide_project.md.nGlTCo4D.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("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 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(`
 `),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("步骤 agent 有 Paseo 浏览器工具（Paseo 设置中打开 Enable Paseo tools 和浏览器工具，桌面端在线）时，功能验证、缺陷修复、复验按验收标准在浏览器中实际操作。"),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:"并行编排-确认前审阅、方案提案、浏览器验证",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"}},"  {")]),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(`

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

@@ -1 +1 @@
-import{_ as o,o as e,c as d,a3 as r}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}'),a={name:"guide/user.md"};function u(s,t,i,l,q,n){return e(),d("div",null,[...t[0]||(t[0]=[r('<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>每个步骤都会出现在这个对话的子 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(a,[["render",u]]);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,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};

package/site-dist/assets/guide_user.md.tiHFxIsQ.lean.js

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

package/site-dist/assets/reference_adr_0033-prototype-review-and-ui-check.md.hFcQzmaa.js

@@ -0,0 +1 @@
+import{_ as o,o as a,c as t,a3 as i}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0033 原型审查页和不靠看图的界面检查","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0033-prototype-review-and-ui-check.md","filePath":"reference/adr/0033-prototype-review-and-ui-check.md","lastUpdated":null}'),r={name:"reference/adr/0033-prototype-review-and-ui-check.md"};function d(c,e,l,n,s,u){return a(),t("div",null,[...e[0]||(e[0]=[i('<div><h1 id="_0033-原型审查页和不靠看图的界面检查" tabindex="-1">0033 原型审查页和不靠看图的界面检查 <a class="header-anchor" href="#_0033-原型审查页和不靠看图的界面检查" aria-label="Permalink to &quot;0033 原型审查页和不靠看图的界面检查&quot;">​</a></h1><ul><li>状态：已采纳（1.13.0-beta.2）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>内网的使用者有三个限制：</p><ul><li>只能用 Paseo 网页端（桌面端有安装限制），所以 Paseo 内置浏览器和它的 <code>browser_*</code> 工具用不了，1.8 起的&quot;浏览器验证&quot;实际上从不运行。</li><li>内网模型看图能力弱：截图交给它判断界面对不对，效果差，每张图还要消耗不少 token。</li><li>需求方多数不是开发者，确认方案时看得出&quot;不对&quot;，但说不清哪里不对、要改成什么；插件里只有一个文本框写修改意见。插件页面也不能显示 HTML，原型只能在功能目录里自己找文件打开。</li></ul><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>原型审查页</strong>：一个本机网页（<code>engine/src/review.ts</code>），插件和 <code>req review</code> 打开它。需求方在原型上点选、选改法、补一句话，页面记下被点元素的文字、颜色、字号、大小、所在区域和对应的 AC；双击可以直接改文字。提交时整理成一份带位置信息的清单，经已有的 <code>req reply</code> 转给需求会话，确认方案经 <code>req approve</code>：不增加新的流程分支。 <ul><li>原型由 agent 生成，内容可能来自卡片等外部文字，和提交接口同源。所以原型以 <code>script-src &#39;none&#39;</code> 返回，里面的脚本不运行，审查页从外面读写它的 DOM。</li><li>服务只监听 <code>127.0.0.1</code>，地址带随机令牌；另有一个只读令牌。远程访问要显式设置环境变量。</li><li>每次打开时保存原型的版本，改过后用文字差异标出变化，需求方不用自己找改了哪里。</li><li>方案设计的提示词规定原型的写法（<code>data-ac</code>、<code>data-label</code>、<code>data-state</code>、真实文字），审查页和界面检查都依赖它。</li></ul></li><li><strong>界面检查 <code>req ui-check</code></strong>：用 <code>playwright-core</code> 驱动本机的 Edge 或 Chrome（不下载浏览器，驱动在第一次使用时从 npm 源装到 <code>~/.req-kit/tools</code>），在页面里运行一段固定的脚本，用文字报告看得出的版面问题，并拿原型里的标题、按钮、字段名、表头和页面对文字。结果是确定的，不依赖模型看图。截图只存文件给人看。验证类步骤总是附上它；有 Paseo 浏览器时，同一段脚本也可以用 <code>browser_evaluate</code> 运行。</li><li>对比度只报明显看不清的（低于 3:1，大字 2.5:1），不报 WCAG 4.5:1 的边缘情况：常见组件库的主按钮正好在这个边缘，全报会淹没真正的问题。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>需求方确认方案的方式从&quot;写一段话&quot;变成&quot;在原型上点&quot;，修改意见能直接定位到元素。效果要看原型是否按约定标了区域。</li><li>验证不再依赖桌面端和模型的视觉能力；需要本机有 Edge 或 Chrome（Windows 自带 Edge）。</li><li><code>req ui-check</code> 第一次运行要能从 npm 源取到 <code>playwright-core</code>，内网走镜像。</li><li>只检查&quot;看得出的&quot;问题，不判断设计是否好看；&quot;和原型对文字&quot;只比较标签类文字，原型中的示例数据不比较。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0033-prototype-review-and-ui-check.md">docs/adr/0033-prototype-review-and-ui-check.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0033-prototype-review-and-ui-check.md">在 GitHub 上编辑</a></p>',2)])])}const q=o(r,[["render",d]]);export{p as __pageData,q as default};

package/site-dist/assets/reference_adr_0033-prototype-review-and-ui-check.md.hFcQzmaa.lean.js

@@ -0,0 +1 @@
+import{_ as o,o as a,c as t,a3 as i}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0033 原型审查页和不靠看图的界面检查","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0033-prototype-review-and-ui-check.md","filePath":"reference/adr/0033-prototype-review-and-ui-check.md","lastUpdated":null}'),r={name:"reference/adr/0033-prototype-review-and-ui-check.md"};function d(c,e,l,n,s,u){return a(),t("div",null,[...e[0]||(e[0]=[i("",2)])])}const q=o(r,[["render",d]]);export{p as __pageData,q as default};

package/site-dist/assets/{reference_adr_index.md.DTVyIA6V.js → reference_adr_index.md.BYF-Ofor.js}

@@ -1 +1 @@
-import{_ as a,o as i,c as l,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"设计决定（ADR）","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/index.md","filePath":"reference/adr/index.md","lastUpdated":null}'),t={name:"reference/adr/index.md"};function n(s,e,o,f,h,d){return i(),l("div",null,[...e[0]||(e[0]=[r('<div><h1 id="设计决定-adr" tabindex="-1">设计决定（ADR） <a class="header-anchor" href="#设计决定-adr" aria-label="Permalink to &quot;设计决定（ADR）&quot;">​</a></h1><p>req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。</p><ul><li><a href="./0001-step-agents-under-origin-chat">0001 步骤 agent 挂在发起的对话下</a></li><li><a href="./0002-no-directory-switch-in-chat">0002 对话过程中不切换工作目录</a></li><li><a href="./0003-script-engine-not-hub">0003 第 3–11 步由脚本引擎驱动，不用 Hub 多步骤工作流</a></li><li><a href="./0004-result-files">0004 步骤结论只看结果文件</a></li><li><a href="./0005-no-default-branch-local-commits-only">0005 不在默认分支上运行，只做本地提交</a></li><li><a href="./0006-skill-install-targets">0006 只安装到 ~/.agents/skills 和 ~/.claude/skills</a></li><li><a href="./0007-own-interview-skill">0007 自带需求访谈 skill，不依赖外部 skill 包</a></li><li><a href="./0008-entries-do-not-call-entries">0008 入口 skill 之间不互相调用</a></li><li><a href="./0009-versioned-install-layout">0009 程序与本机配置分开存放，按版本目录并存</a></li><li><a href="./0010-generated-feature-overview">0010 需求总览现场生成，不维护 INDEX.md</a></li><li><a href="./0011-resume-after-completion">0011 完成后修改 spec 可以继续开发</a></li><li><a href="./0012-review-panel">0012 评审小组：首轮并行评审，评审者核实汇总</a></li><li><a href="./0013-no-release-tooling">0013 发布不使用 changesets 等工具</a></li><li><a href="./0014-notifier-slot">0014 外部通知只留接口，不内置任何 IM</a></li><li><a href="./0015-incremental-continue">0015 需求变更后增量继续，而不是从零重做</a></li><li><a href="./0016-upgrade-from-tags">0016 一键升级：从 git 标签下载到 versions/ 再切换</a></li><li><a href="./0017-use-paseo-capabilities">0017 用好 Paseo 自身的能力：profile、工作区脚本、用量和时间线</a></li><li><a href="./0018-own-worktree-option">0018 可选：流水线为需求新建 worktree 工作区</a></li><li><a href="./0019-parallel-orchestration">0019 用 Paseo 的并行子 agent：确认前独立审阅、方案提案</a></li><li><a href="./0020-scheduling-through-the-chat">0020 调度：用 Paseo 定时任务把消息发回对话，排队在本机进行</a></li><li><a href="./0021-npm-version-manager">0021 npm 分发：全局包是版本管理器，各版本仍装在 versions/ 下</a></li><li><a href="./0022-develop-and-verify-phases">0022 分阶段执行：研发阶段、闸口、测试验证阶段</a></li><li><a href="./0023-types-gate-slices">0023 需求类型、质量门、按切片实现</a></li><li><a href="./0024-confirm-early-review-axes">0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则</a></li><li><a href="./0025-joint-requirements">0025 联合需求：一个需求同时改几个仓库</a></li><li><a href="./0026-machine-records-and-api">0026 本机的需求索引、使用记录和 req api</a></li><li><a href="./0027-paseo-plugin">0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作</a></li><li><a href="./0028-external-integrations">0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的</a></li><li><a href="./0029-requirements-from-cards">0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话</a></li><li><a href="./0030-card-intake-process">0030 接单器：共享机器上定时接卡片、转达回复</a></li><li><a href="./0031-fewer-interventions">0031 少等人：每种中断都有自动的下一步</a></li><li><a href="./0032-npm-only-install">0032 安装、升级和文档只依赖 npm 源</a></li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/README.md">docs/adr/README.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/README.md">在 GitHub 上编辑</a></p>',2)])])}const m=a(t,[["render",n]]);export{p as __pageData,m as default};
+import{_ as a,o as i,c as r,a3 as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"设计决定（ADR）","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/index.md","filePath":"reference/adr/index.md","lastUpdated":null}'),t={name:"reference/adr/index.md"};function n(s,e,o,f,h,d){return i(),r("div",null,[...e[0]||(e[0]=[l('<div><h1 id="设计决定-adr" tabindex="-1">设计决定（ADR） <a class="header-anchor" href="#设计决定-adr" aria-label="Permalink to &quot;设计决定（ADR）&quot;">​</a></h1><p>req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR 说明理由，并在旧的一条中注明被哪条取代。</p><ul><li><a href="./0001-step-agents-under-origin-chat">0001 步骤 agent 挂在发起的对话下</a></li><li><a href="./0002-no-directory-switch-in-chat">0002 对话过程中不切换工作目录</a></li><li><a href="./0003-script-engine-not-hub">0003 第 3–11 步由脚本引擎驱动，不用 Hub 多步骤工作流</a></li><li><a href="./0004-result-files">0004 步骤结论只看结果文件</a></li><li><a href="./0005-no-default-branch-local-commits-only">0005 不在默认分支上运行，只做本地提交</a></li><li><a href="./0006-skill-install-targets">0006 只安装到 ~/.agents/skills 和 ~/.claude/skills</a></li><li><a href="./0007-own-interview-skill">0007 自带需求访谈 skill，不依赖外部 skill 包</a></li><li><a href="./0008-entries-do-not-call-entries">0008 入口 skill 之间不互相调用</a></li><li><a href="./0009-versioned-install-layout">0009 程序与本机配置分开存放，按版本目录并存</a></li><li><a href="./0010-generated-feature-overview">0010 需求总览现场生成，不维护 INDEX.md</a></li><li><a href="./0011-resume-after-completion">0011 完成后修改 spec 可以继续开发</a></li><li><a href="./0012-review-panel">0012 评审小组：首轮并行评审，评审者核实汇总</a></li><li><a href="./0013-no-release-tooling">0013 发布不使用 changesets 等工具</a></li><li><a href="./0014-notifier-slot">0014 外部通知只留接口，不内置任何 IM</a></li><li><a href="./0015-incremental-continue">0015 需求变更后增量继续，而不是从零重做</a></li><li><a href="./0016-upgrade-from-tags">0016 一键升级：从 git 标签下载到 versions/ 再切换</a></li><li><a href="./0017-use-paseo-capabilities">0017 用好 Paseo 自身的能力：profile、工作区脚本、用量和时间线</a></li><li><a href="./0018-own-worktree-option">0018 可选：流水线为需求新建 worktree 工作区</a></li><li><a href="./0019-parallel-orchestration">0019 用 Paseo 的并行子 agent：确认前独立审阅、方案提案</a></li><li><a href="./0020-scheduling-through-the-chat">0020 调度：用 Paseo 定时任务把消息发回对话，排队在本机进行</a></li><li><a href="./0021-npm-version-manager">0021 npm 分发：全局包是版本管理器，各版本仍装在 versions/ 下</a></li><li><a href="./0022-develop-and-verify-phases">0022 分阶段执行：研发阶段、闸口、测试验证阶段</a></li><li><a href="./0023-types-gate-slices">0023 需求类型、质量门、按切片实现</a></li><li><a href="./0024-confirm-early-review-axes">0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则</a></li><li><a href="./0025-joint-requirements">0025 联合需求：一个需求同时改几个仓库</a></li><li><a href="./0026-machine-records-and-api">0026 本机的需求索引、使用记录和 req api</a></li><li><a href="./0027-paseo-plugin">0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作</a></li><li><a href="./0028-external-integrations">0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的</a></li><li><a href="./0029-requirements-from-cards">0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话</a></li><li><a href="./0030-card-intake-process">0030 接单器：共享机器上定时接卡片、转达回复</a></li><li><a href="./0031-fewer-interventions">0031 少等人：每种中断都有自动的下一步</a></li><li><a href="./0032-npm-only-install">0032 安装、升级和文档只依赖 npm 源</a></li><li><a href="./0033-prototype-review-and-ui-check">0033 原型审查页和不靠看图的界面检查</a></li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/README.md">docs/adr/README.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/README.md">在 GitHub 上编辑</a></p>',2)])])}const m=a(t,[["render",n]]);export{p as __pageData,m as default};

package/site-dist/assets/{reference_adr_index.md.DTVyIA6V.lean.js → reference_adr_index.md.BYF-Ofor.lean.js}

@@ -1 +1 @@
-import{_ as a,o as i,c as l,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"设计决定（ADR）","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/index.md","filePath":"reference/adr/index.md","lastUpdated":null}'),t={name:"reference/adr/index.md"};function n(s,e,o,f,h,d){return i(),l("div",null,[...e[0]||(e[0]=[r("",2)])])}const m=a(t,[["render",n]]);export{p as __pageData,m as default};
+import{_ as a,o as i,c as r,a3 as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"设计决定（ADR）","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/index.md","filePath":"reference/adr/index.md","lastUpdated":null}'),t={name:"reference/adr/index.md"};function n(s,e,o,f,h,d){return i(),r("div",null,[...e[0]||(e[0]=[l("",2)])])}const m=a(t,[["render",n]]);export{p as __pageData,m as default};