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

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

@@ -1,4 +1,4 @@
-import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";const o=JSON.parse('{"title":"项目定制与运行规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"guide/project.md","filePath":"guide/project.md","lastUpdated":null}'),t={name:"guide/project.md"};function h(k,s,d,r,E,p){return a(),n("div",null,[...s[0]||(s[0]=[i("div",null,[i("h1",{id:"项目定制与运行规则",tabindex:"-1"},[l("项目定制与运行规则 "),i("a",{class:"header-anchor",href:"#项目定制与运行规则","aria-label":'Permalink to "项目定制与运行规则"'},"​")]),i("h2",{id:"每个需求一个-worktree-工作区",tabindex:"-1"},[l("每个需求一个 worktree 工作区 "),i("a",{class:"header-anchor",href:"#每个需求一个-worktree-工作区","aria-label":'Permalink to "每个需求一个 worktree 工作区"'},"​")]),i("p",null,[l("在 Paseo 中为每个需求新建工作区："),i("strong",null,"New workspace"),l(" → 选择项目 → "),i("strong",null,"Isolation"),l(" 选 "),i("strong",null,"New worktree"),l(" → 起点选主分支，然后在这个工作区的对话里输入 "),i("code",null,"/req"),l("。")]),i("ul",null,[i("li",null,"流水线在这个工作区自己的目录和分支上运行、提交，不影响项目主目录。"),i("li",null,"同一个目录一次只能运行一条流水线；用了 worktree，几个需求可以同时进行。"),i("li",null,[l("在主目录发起时，"),i("code",null,"/req"),l(" 会先建议改用 worktree；使用者坚持的话，它会新建 "),i("code",null,"feature/<功能目录名>"),l(" 分支再继续。")])]),i("p",null,[i("strong",null,"分支规则"),l("：流水线把启动时检出的分支作为本次需求的工作分支，所有步骤都提交到这里，不切换、不新建分支。它拒绝在默认分支（"),i("code",null,"main"),l("、"),i("code",null,"master"),l(" 或 "),i("code",null,"origin/HEAD"),l(" 指向的分支）或 detached HEAD 上启动；续跑时分支变了也会拒绝。")]),i("h2",{id:"档位",tabindex:"-1"},[l("档位 "),i("a",{class:"header-anchor",href:"#档位","aria-label":'Permalink to "档位"'},"​")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"档位"),i("th",null,"适用"),i("th",null,"访谈"),i("th",null,"流程")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("快速（"),i("code",null,"quick"),l("）")]),i("td",null,"小改动：文案、样式、配置项、字段显示等，不涉及数据结构、权限、对外接口"),i("td",null,"只问要改什么、改成什么样、不改什么、验收标准"),i("td",null,"审核、评审、缺陷修复各一轮；不做服务启动验证；产物从简")]),i("tr",null,[i("td",null,[l("标准（"),i("code",null,"standard"),l("）")]),i("td",null,"其他情况"),i("td",null,"完整访谈"),i("td",null,"审核最多 2 轮、评审最多 3 轮、缺陷修复最多 3 轮")])])]),i("p",null,[i("code",null,"/req"),l(" 会根据需求推荐档位，用户确认后写进 spec（"),i("code",null,"- 档位：快速"),l("）。流水线按以下顺序决定档位："),i("code",null,"--profile"),l(" 参数 → 续跑时沿用上次的档位 → spec 中的档位 → 配置中的 "),i("code",null,"defaultProfile"),l("。各档的轮数和是否做服务启动验证可以在配置的 "),i("code",null,"profiles"),l(" 中调整。")]),i("h2",{id:"需求类型",tabindex:"-1"},[l("需求类型 "),i("a",{class:"header-anchor",href:"#需求类型","aria-label":'Permalink to "需求类型"'},"​")]),i("p",null,[l("spec 头部的 "),i("code",null,"- 类型："),l(" 决定流水线走哪种做法（1.8 起）。缺陷、重构、评估有自己的做法，新需求和小改动走通常的流程：")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"类型"),i("th",null,"做法"),i("th",null,"关键证据")])]),i("tbody",null,[i("tr",null,[i("td",null,[l("缺陷（"),i("code",null,"缺陷"),l("、"),i("code",null,"bug"),l("）")]),i("td",null,[l('方案设计改为"复现与定位"：先提交一个修复前失败的复现测试或脚本，写 '),i("code",null,"diagnosis.md"),l("（根因、影响面）；复现不了就暂停，把需要补充的信息发回对话。修复要让复现转绿，评审实际确认它修复前失败")]),i("td",null,"同一个复现，修复前失败、修复后通过")]),i("tr",null,[i("td",null,[l("重构（"),i("code",null,"重构"),l("、"),i("code",null,"技术改进"),l("）")]),i("td",null,'先补特征测试锁住现有行为并单独提交，再小步改动、每步全绿；评审的首要问题是"行为有没有变"'),i("td",null,"重构前后同一组测试一致")]),i("tr",null,[i("td",null,[l("评估（"),i("code",null,"评估"),l("、"),i("code",null,"调研"),l("）")]),i("td",null,[l("只读：调研评估（"),i("code",null,"assessment.md"),l("）→ 评估审阅 ⇄ 修订 → 评估报告；没有实现、评审、提测和验证，执行方式按连续")]),i("td",null,"引用的代码位置和实际运行的命令")])])]),i("p",null,[l("各类型的做法写在 "),i("code",null,"engine/prompts/types/<类型>.md"),l("，按步骤分节，接在每一步的任务之后；可以用 "),i("code",null,"prompts.local/types/"),l(" 覆盖。不想用某个类型的做法时，从配置 "),i("code",null,"requirementTypes"),l("（默认 "),i("code",null,'["defect", "refactor", "assessment"]'),l("）中去掉它，这个类型就按新需求处理。设计决定见 ADR 0023。")]),i("h2",{id:"方案确认点-开工前请需求方确认-做完后会看到什么",tabindex:"-1"},[l('方案确认点：开工前请需求方确认"做完后会看到什么" '),i("a",{class:"header-anchor",href:"#方案确认点-开工前请需求方确认-做完后会看到什么","aria-label":'Permalink to "方案确认点：开工前请需求方确认"做完后会看到什么""'},"​")]),i("p",null,[l("方案审核通过后、写代码之前，流水线可以停下来请需求方确认（1.8 起）。方案设计写 "),i("code",null,"preview.md"),l("（按操作顺序描述做完后会看到什么、需要确认的假设、不会变的地方），界面改动还在 "),i("code",null,"prototype/"),l(" 中画出静态的原型页面。对话里的 AI 把要点讲给需求方：确认后执行 "),i("code",null,"--approve"),l("（终端里 "),i("code",null,"req approve <需求>"),l("）开始写代码；要改的，更新需求说明后 "),i("code",null,"--resume"),l("，方案调整后再确认一次。需求方确认过的预览和原型，实现和功能验证都以它为准：界面与原型不一致按缺陷处理。")]),i("table",{tabindex:"0"},[i("thead",null,[i("tr",null,[i("th",null,"配置"),i("th",null,"默认"),i("th",null,"说明")])]),i("tbody",null,[i("tr",null,[i("td",null,[i("code",null,"designApproval.mode")]),i("td",null,[i("code",null,"ui")]),i("td",null,[i("code",null,"ui"),l("：方案判断这次是界面改动（结果文件 "),i("code",null,"ui_change"),l("）时才停；"),i("code",null,"always"),l("：每次都停；"),i("code",null,"off"),l("：不停")])]),i("tr",null,[i("td",null,[i("code",null,"designApproval.profiles")]),i("td",null,[i("code",null,'["standard"]')]),i("td",null,"哪些档位使用；快速档默认不停")]),i("tr",null,[i("td",null,[i("code",null,"designApproval.autoContinueHours")]),i("td",null,"0"),i("td",null,[l("大于 0 时，等了这么久还没确认就按方案继续（通过对话执行）；0 表示一直等待。等待超过 "),i("code",null,"waitingReminderHours"),l(" 会提醒一次")])])])]),i("p",null,[l('等待确认时进度显示"等待需求方确认方案"，需求总览归入"需要处理"，外部通知收到 '),i("code",null,"approval"),l(" 事件。评估类需求不写代码，不经过确认点。")]),i("p",null,[i("strong",null,"原型审查页（1.13 起）。"),l(" 有 "),i("code",null,"prototype/"),l(' 的需求，插件的需求页面和"等你处理"里有"打开原型审查页"，终端里是 '),i("code",null,"req review <需求>"),l("。需求方在原型上点选要改的地方（页面记下元素、文字、颜色、大小和位置）、双击直接改文字，切换状态和电脑、手机宽度，然后提交：意见整理成带位置信息的清单转给需求会话（与插件中写修改意见的效果相同），或者直接确认方案。草稿和提交记录在功能目录的 "),i("code",null,".pipeline/review/"),l(" 中，每一版原型也存在那里，原型改过后页面会标出这一版改了哪里。")]),i("p",null,[l("为了让审查页能用，方案设计按约定写原型：每个改动区域标 "),i("code",null,"data-ac"),l("（对应的 AC）和 "),i("code",null,"data-label"),l("（用需求方的话说是什么），各种状态包在 "),i("code",null,'<section data-state="状态名">'),l(" 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。")]),i("p",null,[l("审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 "),i("code",null,"127.0.0.1"),l("，地址中带随机令牌（插件设为只读时给只读的地址）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 "),i("code",null,"REQ_KIT_REVIEW_HOST"),l("（例如 "),i("code",null,"0.0.0.0"),l("）、"),i("code",null,"REQ_KIT_REVIEW_PUBLIC_URL"),l("（别人访问这台机器用的地址，例如 "),i("code",null,"http://10.1.2.3:6781"),l("），需要时用 "),i("code",null,"REQ_KIT_REVIEW_PORT"),l(" 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量。")]),i("h2",{id:"代码评审分两个方向",tabindex:"-1"},[l("代码评审分两个方向 "),i("a",{class:"header-anchor",href:"#代码评审分两个方向","aria-label":'Permalink to "代码评审分两个方向"'},"​")]),i("p",null,"标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论："),i("ul",null,[i("li",null,[i("strong",null,"规格评审"),l("：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。")]),i("li",null,[i("strong",null,"规范评审"),l("：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。")])]),i("p",null,[l("两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。"),i("code",null,"reviewAxes.enabled"),l(" 设为 "),i("code",null,"false"),l(" 关闭，"),i("code",null,"reviewAxes.profiles"),l(" 选择档位（默认只有标准档）。配置了评审小组（"),i("code",null,"reviewPanel"),l("）时，以评审小组为准。")]),i("h2",{id:"验收测试先提交",tabindex:"-1"},[l("验收测试先提交 "),i("a",{class:"header-anchor",href:"#验收测试先提交","aria-label":'Permalink to "验收测试先提交"'},"​")]),i("p",null,"方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。"),i("h2",{id:"术语表和范例文件",tabindex:"-1"},[l("术语表和范例文件 "),i("a",{class:"header-anchor",href:"#术语表和范例文件","aria-label":'Permalink to "术语表和范例文件"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,[i("code",null,"GLOSSARY.md")]),l("（仓库根目录）：业务词、含义、代码中的名字。"),i("code",null,"/req-setup"),l(" 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。")]),i("li",null,[i("strong",null,"范例文件"),l("："),i("code",null,"/req-setup"),l(" 在 "),i("code",null,"project-notes.md"),l(" 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。")])]),i("h2",{id:"反复出现的问题变成规则",tabindex:"-1"},[l("反复出现的问题变成规则 "),i("a",{class:"header-anchor",href:"#反复出现的问题变成规则","aria-label":'Permalink to "反复出现的问题变成规则"'},"​")]),i("p",null,[l('完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 '),i("code",null,"lessons.tsv"),l("（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，"),i("code",null,"req digest"),l(' 的需求总览会列在"反复出现的问题"中，'),i("code",null,"/req-retro"),l(" 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 "),i("code",null,".requirement-pipeline/lessons-handled.txt"),l("（一行一个），总览不再提示。")]),i("h2",{id:"质量门-流水线自己运行的检查",tabindex:"-1"},[l("质量门：流水线自己运行的检查 "),i("a",{class:"header-anchor",href:"#质量门-流水线自己运行的检查","aria-label":'Permalink to "质量门：流水线自己运行的检查"'},"​")]),i("p",null,[l("项目配置 "),i("code",null,".requirement-pipeline.json"),l(" 的 "),i("code",null,"checks"),l(" 列出流水线"),i("strong",null,"自己运行"),l("的检查，通常由 "),i("code",null,"/req-setup"),l(" 从实际跑通的命令写入：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
+import{_ as e,o as a,c as n,j as i,a as l}from"./chunks/framework.B9qR_F1m.js";const 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(' 的需求，插件的需求页面和"等你处理"里有"审查原型"按钮（等待确认方案时是最醒目的"审查原型并确认方案"），审查页嵌在 Paseo 的网页端和桌面端里打开，手机上在浏览器中打开；终端里是 '),i("code",null,"req review <需求>"),l("。需求方在原型上点选要改的地方（页面记下元素、文字、颜色、大小和位置）、双击直接改文字，切换状态和电脑、手机宽度，然后提交：意见整理成带位置信息的清单转给需求会话（与插件中写修改意见的效果相同），或者直接确认方案。草稿和提交记录在功能目录的 "),i("code",null,".pipeline/review/"),l(" 中，每一版原型也存在那里，原型改过后页面会标出这一版改了哪里。")]),i("p",null,[l("为了让审查页能用，方案设计按约定写原型：每个改动区域标 "),i("code",null,"data-ac"),l("（对应的 AC）和 "),i("code",null,"data-label"),l("（用需求方的话说是什么），各种状态包在 "),i("code",null,'<section data-state="状态名">'),l(" 中，按钮、标题、字段名写最终的文字。原型里的脚本不会运行。")]),i("p",null,[l("审查页由一个本机服务提供：用到时在后台启动，空闲 4 小时后自己退出，只监听 "),i("code",null,"127.0.0.1"),l("，地址中带随机令牌（插件设为只读时给只读的地址）。审查页允许被本机地址上的页面（Paseo 网页端）嵌入；要限定或放开，设 "),i("code",null,"REQ_KIT_REVIEW_FRAME_ANCESTORS"),l("（CSP "),i("code",null,"frame-ancestors"),l(" 的值）。需求方在别的电脑上用浏览器访问 Paseo 网页端时，在运行 Paseo daemon 的机器上设置环境变量 "),i("code",null,"REQ_KIT_REVIEW_HOST"),l("（例如 "),i("code",null,"0.0.0.0"),l("）、"),i("code",null,"REQ_KIT_REVIEW_PUBLIC_URL"),l("（别人访问这台机器用的地址，例如 "),i("code",null,"http://10.1.2.3:6781"),l("），需要时用 "),i("code",null,"REQ_KIT_REVIEW_PORT"),l(" 换端口（默认 6781），然后重启 Paseo daemon 让插件拿到新的环境变量。")]),i("h2",{id:"代码评审分两个方向",tabindex:"-1"},[l("代码评审分两个方向 "),i("a",{class:"header-anchor",href:"#代码评审分两个方向","aria-label":'Permalink to "代码评审分两个方向"'},"​")]),i("p",null,"标准档第一轮代码评审由两位评审者同时进行（1.8 起），各自写意见，再由 reviewer 核实、汇总成一份结论："),i("ul",null,[i("li",null,[i("strong",null,"规格评审"),l("：每条验收标准是否真的实现并有测试、测试的期望值是否与验收标准的例子一致、有没有做需求之外的事、与确认过的预览是否一致。")]),i("li",null,[i("strong",null,"规范评审"),l("：项目惯例和范例文件、术语表中的代码名称、测试质量、安全与数据、简单性，以及可以变成规则的问题。")])]),i("p",null,[l("两位都用配置的 reviewer agent，相当于多两次评审的用量；之后的轮次只核对修复，仍由一位评审。"),i("code",null,"reviewAxes.enabled"),l(" 设为 "),i("code",null,"false"),l(" 关闭，"),i("code",null,"reviewAxes.profiles"),l(" 选择档位（默认只有标准档）。配置了评审小组（"),i("code",null,"reviewPanel"),l("）时，以评审小组为准。")]),i("h2",{id:"验收测试先提交",tabindex:"-1"},[l("验收测试先提交 "),i("a",{class:"header-anchor",href:"#验收测试先提交","aria-label":'Permalink to "验收测试先提交"'},"​")]),i("p",null,"方案判断适合测试先行时，代码实现先把从验收标准的例子写出的测试单独提交一次（这时它们是失败的），在结果文件中写明这些测试文件和那次提交。代码评审前，流水线核对它们之后有没有被改过，被改过的交给评审逐个确认有没有依据：为了让测试通过而放宽断言的，按阻塞提出。"),i("h2",{id:"术语表和范例文件",tabindex:"-1"},[l("术语表和范例文件 "),i("a",{class:"header-anchor",href:"#术语表和范例文件","aria-label":'Permalink to "术语表和范例文件"'},"​")]),i("ul",null,[i("li",null,[i("strong",null,[i("code",null,"GLOSSARY.md")]),l("（仓库根目录）：业务词、含义、代码中的名字。"),i("code",null,"/req-setup"),l(" 第一次整理，访谈遇到新词时补充，方案设计为新概念补上代码中的名字；各步骤按它命名，规范评审检查是否一致。")]),i("li",null,[i("strong",null,"范例文件"),l("："),i("code",null,"/req-setup"),l(" 在 "),i("code",null,"project-notes.md"),l(" 中列出各类代码（接口、页面、测试、迁移脚本）写得最好的文件。方案的每个任务写明参照哪个文件，实现照它的结构、命名、错误处理和测试写法来。")])]),i("h2",{id:"反复出现的问题变成规则",tabindex:"-1"},[l("反复出现的问题变成规则 "),i("a",{class:"header-anchor",href:"#反复出现的问题变成规则","aria-label":'Permalink to "反复出现的问题变成规则"'},"​")]),i("p",null,[l('完成报告把这次评审、质量门、缺陷中"一条项目规则就能挡住"的问题写进功能目录的 '),i("code",null,"lessons.tsv"),l("（类别、问题、出处、建议的规则、放在哪一层）。同一个类别在两个以上的需求里出现时，"),i("code",null,"req digest"),l(' 的需求总览会列在"反复出现的问题"中，'),i("code",null,"/req-retro"),l(" 会建议把它变成 lint 规则、类型约束、测试或项目说明里的一行，批准后落地。已经处理的类别写进 "),i("code",null,".requirement-pipeline/lessons-handled.txt"),l("（一行一个），总览不再提示。")]),i("h2",{id:"质量门-流水线自己运行的检查",tabindex:"-1"},[l("质量门：流水线自己运行的检查 "),i("a",{class:"header-anchor",href:"#质量门-流水线自己运行的检查","aria-label":'Permalink to "质量门：流水线自己运行的检查"'},"​")]),i("p",null,[l("项目配置 "),i("code",null,".requirement-pipeline.json"),l(" 的 "),i("code",null,"checks"),l(" 列出流水线"),i("strong",null,"自己运行"),l("的检查，通常由 "),i("code",null,"/req-setup"),l(" 从实际跑通的命令写入：")]),i("div",{class:"language-json vp-adaptive-theme"},[i("button",{title:"Copy Code",class:"copy"}),i("span",{class:"lang"},"json"),i("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[i("code",null,[i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "checks"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": [")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"lint"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"npm run lint"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`
 `),i("span",{class:"line"},[i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"    { "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"name"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"web 测试"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"command"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"npm test"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"cwd"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"web"'),i("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," },")]),l(`

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

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