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

package/site-dist/assets/{reference_adr_0023-types-gate-slices.md.D2E6yyYQ.js → reference_adr_0023-types-gate-slices.md.Bjufr5EK.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as a,a3 as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0023 需求类型、质量门、按切片实现","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0023-types-gate-slices.md","filePath":"reference/adr/0023-types-gate-slices.md","lastUpdated":null}'),i={name:"reference/adr/0023-types-gate-slices.md"};function s(r,e,d,c,n,u){return t(),a("div",null,[...e[0]||(e[0]=[l('<div><h1 id="_0023-需求类型、质量门、按切片实现" tabindex="-1">0023 需求类型、质量门、按切片实现 <a class="header-anchor" href="#_0023-需求类型、质量门、按切片实现" aria-label="Permalink to &quot;0023 需求类型、质量门、按切片实现&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0004-result-files">0004</a>：结果文件可以带计划字段；<a href="./0022-develop-and-verify-phases">0022</a>：评估类需求没有测试验证阶段）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>到 1.7 为止，所有需求走同一条路：方案设计 → 审核 → 一个 agent 实现全部任务 → 评审 → 验证。三个问题反复出现：</p><ol><li><strong>不同类型的需求要不同的做法。</strong> 修缺陷要先复现、找到原因；重构要先锁住现有行为；&quot;能不能做&quot;的评估根本不该写代码。用新功能的做法处理它们，结果常常&quot;做了，但不是要的&quot;：缺陷改的是现象，重构顺手改了行为，评估做成了半成品。</li><li><strong>&quot;规范&quot;只是提示词里的建议。</strong> lint、测试、构建是否通过，靠实现 agent 自己说，评审 agent 再跑一遍；中间没有任何确定性的检查，改坏了也可能写成&quot;通过&quot;。</li><li><strong>大需求一个 agent 做不完。</strong> 上下文被填满、时限 4 小时、中断后整步重做。</li></ol><p>业界的做法（Matt Pocock 的 skills、pstack、Claude Code 和 Cursor 的最佳实践）在这几点上相同：按任务类型走不同的剧本；能用工具判定的交给确定性的检查，不靠模型自评；把工作切成可以单独验证的纵向切片。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><h3 id="需求类型" tabindex="-1">需求类型 <a class="header-anchor" href="#需求类型" aria-label="Permalink to &quot;需求类型&quot;">​</a></h3><ul><li>spec 头部的 <code>- 类型：</code> 由引擎读取。缺陷、重构、评估三种有自己的<strong>剧本</strong>；新需求、小改动和其他写法走原来的流程。配置 <code>requirementTypes</code> 可以关掉某个剧本（该类型改走原来的流程）。</li><li>剧本<strong>不新增步骤</strong>，而是改变已有步骤做什么：每种类型一个提示词文件 <code>engine/prompts/types/&lt;类型&gt;.md</code>，按&quot;## 步骤名（步骤 ID）&quot;分节，引擎把&quot;所有步骤&quot;一节和当前步骤的一节接在本步骤任务之后，并在 <code>&lt;pipeline-context&gt;</code> 中写明类型。步骤 ID、结果文件和状态都不变，续跑、增量继续、分阶段执行照常适用；<code>prompts.local/types/</code> 可以覆盖。剧本可以改步骤的显示名称（缺陷的方案设计叫&quot;复现与定位&quot;）。</li><li><strong>缺陷</strong>：方案设计改为复现与定位，先提交一个修复前失败的复现测试或脚本，写 <code>diagnosis.md</code>（根因、影响面）。复现不了时结果文件写 <code>reproduced: false</code> 和要问的问题，流水线像方案审核阻塞一样暂停，把问题发回对话。修复必须让复现转绿，评审要实际确认它修复前失败。</li><li><strong>重构</strong>：先补特征测试锁住现有行为，单独提交；之后小步改动，每步全绿；评审的首要问题是&quot;行为有没有变&quot;，特征测试的断言被改要说明理由。</li><li><strong>评估</strong>：只读。调研评估写 <code>assessment.md</code> → 评估审阅 ⇄ 修订 → 评估报告；没有实现、代码评审、提测和验证，执行方式一律按连续。功能目录之外有文件被改动时，引擎把它写进报告的上下文。报告最后给出需求草稿，对话可以接着提一个新需求。</li><li>类型由 <code>/req</code> 在访谈时判断并请用户确认；访谈的重点随类型变化（复现步骤、必须不变的行为、要回答的问题）。</li></ul><h3 id="质量门" tabindex="-1">质量门 <a class="header-anchor" href="#质量门" aria-label="Permalink to &quot;质量门&quot;">​</a></h3><ul><li>项目配置 <code>checks</code> 列出流水线<strong>自己运行</strong>的检查（格式、lint、类型检查、单元测试、构建），由 <code>/req-setup</code> 从实际跑通的命令写入。端到端测试和需要启动服务的检查不放这里，它们属于功能验证。</li><li>每次尝试开始时（方案设计之前，任何提交之前）运行全部检查，记录<strong>基线</strong>。放在方案设计之前，是因为缺陷的复现测试在复现与定位时就提交了，基线晚了会把整个测试检查记成&quot;原本就失败&quot;。</li><li>代码实现（每一片）、评审问题修复、缺陷修复结束后运行与改动相关的检查。只有<strong>改动前通过、现在失败</strong>的检查拦下：把命令和输出的最后部分作为追问发回<strong>同一个 agent</strong>（它还记得自己改了什么），最多 <code>qualityGate.fixAttempts</code> 次（默认 2）。仍然失败时<strong>照常继续</strong>，结果写进状态文件，交给代码评审（要求按阻塞或重要提出）和报告（结论最高为&quot;有遗留问题&quot;）。不让一个 lint 问题卡住整个需求，也不会无声地放过。</li><li>比较以&quot;一项检查&quot;为单位，不细到测试用例：粗，但与项目的测试框架无关。原本就失败的检查不拦，但会在报告中列出。</li><li>检查通过系统 shell 运行（Windows 上是 cmd.exe），命令要写成各系统通用的形式，与 <code>paseo.json</code> 的约定相同。没有配置检查时一切照旧，报告注明&quot;未配置&quot;。</li></ul><h3 id="多模块与关联仓库" tabindex="-1">多模块与关联仓库 <a class="header-anchor" href="#多模块与关联仓库" aria-label="Permalink to &quot;多模块与关联仓库&quot;">​</a></h3><ul><li>检查可以带 <code>cwd</code> 或 <code>paths</code>：只有改动碰到这些路径时才运行，单仓库多模块的项目只检查改动的模块。</li><li>项目配置 <code>relatedRepos</code> 登记其他仓库（例如前端项目的后端）。步骤在 <code>&lt;pipeline-context&gt;</code> 中看到它们的位置、分支和提交，按 <code>related-repos.md</code> <strong>只读</strong>参考：不修改、不提交；验证需要对方服务时优先用已部署的测试环境。</li><li>两边都要改的&quot;联合需求&quot;（父子运行、接口约定、联合验证）不在这个版本，单独设计。</li></ul><h3 id="按切片实现" tabindex="-1">按切片实现 <a class="header-anchor" href="#按切片实现" aria-label="Permalink to &quot;按切片实现&quot;">​</a></h3><ul><li>方案的实施计划分成<strong>纵向切片</strong>（每片能单独演示和验证），设计步骤在结果文件的可选字段 <code>slices</code> 中列出；方案修订可以给出新列表。</li><li>档位在 <code>slices.profiles</code> 中（默认只有标准档）、且有两片以上时，代码实现按片逐个启动新的 agent（步骤键 <code>implement-s&lt;序号&gt;</code>），每片各自提交、各自过一次质量门；中断后只重做当前片。超过 <code>slices.max</code>（默认 6）时最后几片合并。只有一片、快速档时与原来相同。</li><li>子需求（把大需求拆成几个各有 spec 的需求）不在这个版本：切片已经解决上下文和中断的问题。</li></ul><h3 id="范围检查" tabindex="-1">范围检查 <a class="header-anchor" href="#范围检查" aria-label="Permalink to &quot;范围检查&quot;">​</a></h3><ul><li>设计结果的可选字段 <code>files</code> 列出预计改动的文件和目录。代码评审前，引擎比对这次尝试实际改动的文件（不含功能目录），把清单之外的交给评审逐一判断：必需的写理由，无关的要求撤回。评审同时增加&quot;影响面&quot;一节，并明确只把影响正确性、安全、数据和验收的问题提为阻塞或重要，避免评审意见把代码越改越复杂。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件只增加可选字段（<code>type</code>、<code>codeBase</code>、<code>gate</code>），格式版本仍为 1；结果文件增加可选字段。回滚到 1.7 后，旧引擎忽略这些字段；按切片实现中断的需求，旧引擎会把整个实现重做一遍。</li><li>有检查的项目，每次尝试多一次基线运行，写代码的步骤之后各多一次检查运行。检查要能在几分钟内跑完。</li><li>不同的需求类型复用同一套步骤和状态：以后增加类型（界面改动、数据变更、性能优化）只需要一个剧本文件和少量引擎分支。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0023-types-gate-slices.md">docs/adr/0023-types-gate-slices.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0023-types-gate-slices.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(i,[["render",s]]);export{p as __pageData,g as default};
+import{_ as o,o as t,c as a,a2 as l}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0023 需求类型、质量门、按切片实现","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0023-types-gate-slices.md","filePath":"reference/adr/0023-types-gate-slices.md","lastUpdated":null}'),i={name:"reference/adr/0023-types-gate-slices.md"};function s(r,e,d,c,n,u){return t(),a("div",null,[...e[0]||(e[0]=[l('<div><h1 id="_0023-需求类型、质量门、按切片实现" tabindex="-1">0023 需求类型、质量门、按切片实现 <a class="header-anchor" href="#_0023-需求类型、质量门、按切片实现" aria-label="Permalink to &quot;0023 需求类型、质量门、按切片实现&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0004-result-files">0004</a>：结果文件可以带计划字段；<a href="./0022-develop-and-verify-phases">0022</a>：评估类需求没有测试验证阶段）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>到 1.7 为止，所有需求走同一条路：方案设计 → 审核 → 一个 agent 实现全部任务 → 评审 → 验证。三个问题反复出现：</p><ol><li><strong>不同类型的需求要不同的做法。</strong> 修缺陷要先复现、找到原因；重构要先锁住现有行为；&quot;能不能做&quot;的评估根本不该写代码。用新功能的做法处理它们，结果常常&quot;做了，但不是要的&quot;：缺陷改的是现象，重构顺手改了行为，评估做成了半成品。</li><li><strong>&quot;规范&quot;只是提示词里的建议。</strong> lint、测试、构建是否通过，靠实现 agent 自己说，评审 agent 再跑一遍；中间没有任何确定性的检查，改坏了也可能写成&quot;通过&quot;。</li><li><strong>大需求一个 agent 做不完。</strong> 上下文被填满、时限 4 小时、中断后整步重做。</li></ol><p>业界的做法（Matt Pocock 的 skills、pstack、Claude Code 和 Cursor 的最佳实践）在这几点上相同：按任务类型走不同的剧本；能用工具判定的交给确定性的检查，不靠模型自评；把工作切成可以单独验证的纵向切片。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><h3 id="需求类型" tabindex="-1">需求类型 <a class="header-anchor" href="#需求类型" aria-label="Permalink to &quot;需求类型&quot;">​</a></h3><ul><li>spec 头部的 <code>- 类型：</code> 由引擎读取。缺陷、重构、评估三种有自己的<strong>剧本</strong>；新需求、小改动和其他写法走原来的流程。配置 <code>requirementTypes</code> 可以关掉某个剧本（该类型改走原来的流程）。</li><li>剧本<strong>不新增步骤</strong>，而是改变已有步骤做什么：每种类型一个提示词文件 <code>engine/prompts/types/&lt;类型&gt;.md</code>，按&quot;## 步骤名（步骤 ID）&quot;分节，引擎把&quot;所有步骤&quot;一节和当前步骤的一节接在本步骤任务之后，并在 <code>&lt;pipeline-context&gt;</code> 中写明类型。步骤 ID、结果文件和状态都不变，续跑、增量继续、分阶段执行照常适用；<code>prompts.local/types/</code> 可以覆盖。剧本可以改步骤的显示名称（缺陷的方案设计叫&quot;复现与定位&quot;）。</li><li><strong>缺陷</strong>：方案设计改为复现与定位，先提交一个修复前失败的复现测试或脚本，写 <code>diagnosis.md</code>（根因、影响面）。复现不了时结果文件写 <code>reproduced: false</code> 和要问的问题，流水线像方案审核阻塞一样暂停，把问题发回对话。修复必须让复现转绿，评审要实际确认它修复前失败。</li><li><strong>重构</strong>：先补特征测试锁住现有行为，单独提交；之后小步改动，每步全绿；评审的首要问题是&quot;行为有没有变&quot;，特征测试的断言被改要说明理由。</li><li><strong>评估</strong>：只读。调研评估写 <code>assessment.md</code> → 评估审阅 ⇄ 修订 → 评估报告；没有实现、代码评审、提测和验证，执行方式一律按连续。功能目录之外有文件被改动时，引擎把它写进报告的上下文。报告最后给出需求草稿，对话可以接着提一个新需求。</li><li>类型由 <code>/req</code> 在访谈时判断并请用户确认；访谈的重点随类型变化（复现步骤、必须不变的行为、要回答的问题）。</li></ul><h3 id="质量门" tabindex="-1">质量门 <a class="header-anchor" href="#质量门" aria-label="Permalink to &quot;质量门&quot;">​</a></h3><ul><li>项目配置 <code>checks</code> 列出流水线<strong>自己运行</strong>的检查（格式、lint、类型检查、单元测试、构建），由 <code>/req-setup</code> 从实际跑通的命令写入。端到端测试和需要启动服务的检查不放这里，它们属于功能验证。</li><li>每次尝试开始时（方案设计之前，任何提交之前）运行全部检查，记录<strong>基线</strong>。放在方案设计之前，是因为缺陷的复现测试在复现与定位时就提交了，基线晚了会把整个测试检查记成&quot;原本就失败&quot;。</li><li>代码实现（每一片）、评审问题修复、缺陷修复结束后运行与改动相关的检查。只有<strong>改动前通过、现在失败</strong>的检查拦下：把命令和输出的最后部分作为追问发回<strong>同一个 agent</strong>（它还记得自己改了什么），最多 <code>qualityGate.fixAttempts</code> 次（默认 2）。仍然失败时<strong>照常继续</strong>，结果写进状态文件，交给代码评审（要求按阻塞或重要提出）和报告（结论最高为&quot;有遗留问题&quot;）。不让一个 lint 问题卡住整个需求，也不会无声地放过。</li><li>比较以&quot;一项检查&quot;为单位，不细到测试用例：粗，但与项目的测试框架无关。原本就失败的检查不拦，但会在报告中列出。</li><li>检查通过系统 shell 运行（Windows 上是 cmd.exe），命令要写成各系统通用的形式，与 <code>paseo.json</code> 的约定相同。没有配置检查时一切照旧，报告注明&quot;未配置&quot;。</li></ul><h3 id="多模块与关联仓库" tabindex="-1">多模块与关联仓库 <a class="header-anchor" href="#多模块与关联仓库" aria-label="Permalink to &quot;多模块与关联仓库&quot;">​</a></h3><ul><li>检查可以带 <code>cwd</code> 或 <code>paths</code>：只有改动碰到这些路径时才运行，单仓库多模块的项目只检查改动的模块。</li><li>项目配置 <code>relatedRepos</code> 登记其他仓库（例如前端项目的后端）。步骤在 <code>&lt;pipeline-context&gt;</code> 中看到它们的位置、分支和提交，按 <code>related-repos.md</code> <strong>只读</strong>参考：不修改、不提交；验证需要对方服务时优先用已部署的测试环境。</li><li>两边都要改的&quot;联合需求&quot;（父子运行、接口约定、联合验证）不在这个版本，单独设计。</li></ul><h3 id="按切片实现" tabindex="-1">按切片实现 <a class="header-anchor" href="#按切片实现" aria-label="Permalink to &quot;按切片实现&quot;">​</a></h3><ul><li>方案的实施计划分成<strong>纵向切片</strong>（每片能单独演示和验证），设计步骤在结果文件的可选字段 <code>slices</code> 中列出；方案修订可以给出新列表。</li><li>档位在 <code>slices.profiles</code> 中（默认只有标准档）、且有两片以上时，代码实现按片逐个启动新的 agent（步骤键 <code>implement-s&lt;序号&gt;</code>），每片各自提交、各自过一次质量门；中断后只重做当前片。超过 <code>slices.max</code>（默认 6）时最后几片合并。只有一片、快速档时与原来相同。</li><li>子需求（把大需求拆成几个各有 spec 的需求）不在这个版本：切片已经解决上下文和中断的问题。</li></ul><h3 id="范围检查" tabindex="-1">范围检查 <a class="header-anchor" href="#范围检查" aria-label="Permalink to &quot;范围检查&quot;">​</a></h3><ul><li>设计结果的可选字段 <code>files</code> 列出预计改动的文件和目录。代码评审前，引擎比对这次尝试实际改动的文件（不含功能目录），把清单之外的交给评审逐一判断：必需的写理由，无关的要求撤回。评审同时增加&quot;影响面&quot;一节，并明确只把影响正确性、安全、数据和验收的问题提为阻塞或重要，避免评审意见把代码越改越复杂。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件只增加可选字段（<code>type</code>、<code>codeBase</code>、<code>gate</code>），格式版本仍为 1；结果文件增加可选字段。回滚到 1.7 后，旧引擎忽略这些字段；按切片实现中断的需求，旧引擎会把整个实现重做一遍。</li><li>有检查的项目，每次尝试多一次基线运行，写代码的步骤之后各多一次检查运行。检查要能在几分钟内跑完。</li><li>不同的需求类型复用同一套步骤和状态：以后增加类型（界面改动、数据变更、性能优化）只需要一个剧本文件和少量引擎分支。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0023-types-gate-slices.md">docs/adr/0023-types-gate-slices.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0023-types-gate-slices.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(i,[["render",s]]);export{p as __pageData,g as default};

package/site-dist/assets/{reference_adr_0023-types-gate-slices.md.D2E6yyYQ.lean.js → reference_adr_0023-types-gate-slices.md.Bjufr5EK.lean.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as a,a3 as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0023 需求类型、质量门、按切片实现","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0023-types-gate-slices.md","filePath":"reference/adr/0023-types-gate-slices.md","lastUpdated":null}'),i={name:"reference/adr/0023-types-gate-slices.md"};function s(r,e,d,c,n,u){return t(),a("div",null,[...e[0]||(e[0]=[l("",2)])])}const g=o(i,[["render",s]]);export{p as __pageData,g as default};
+import{_ as o,o as t,c as a,a2 as l}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0023 需求类型、质量门、按切片实现","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0023-types-gate-slices.md","filePath":"reference/adr/0023-types-gate-slices.md","lastUpdated":null}'),i={name:"reference/adr/0023-types-gate-slices.md"};function s(r,e,d,c,n,u){return t(),a("div",null,[...e[0]||(e[0]=[l("",2)])])}const g=o(i,[["render",s]]);export{p as __pageData,g as default};

package/site-dist/assets/{reference_adr_0024-confirm-early-review-axes.md.FmK_ke0x.js → reference_adr_0024-confirm-early-review-axes.md.BRxVXJa4.js}

@@ -1 +1 @@
-import{_ as o,o as a,c,a3 as t}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0024-confirm-early-review-axes.md","filePath":"reference/adr/0024-confirm-early-review-axes.md","lastUpdated":null}'),r={name:"reference/adr/0024-confirm-early-review-axes.md"};function d(i,e,s,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0024-让分歧更早暴露-验收例子、方案确认点、两个方向的评审、反复的问题变成规则" tabindex="-1">0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则 <a class="header-anchor" href="#_0024-让分歧更早暴露-验收例子、方案确认点、两个方向的评审、反复的问题变成规则" aria-label="Permalink to &quot;0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0012-review-panel">0012</a>：评审的两个方向复用评审小组的机制；<a href="./0022-develop-and-verify-phases">0022</a>：方案确认点与闸口一样停下来等人，但在写代码之前）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>需求做出来&quot;不符合预期&quot;，多半不是代码写错，而是需求方和 agent 对&quot;做成什么样&quot;理解不同，并且直到验收才发现。到 1.8.0-beta.1 为止，需求方在确认需求说明之后，要等到报告才再看到结果；验收标准常常是抽象的描述（&quot;在限制时间内重复发送会被拒绝&quot;），测试的期望值由实现者自己定；代码评审一位评审者同时看&quot;做没做对&quot;和&quot;做得规不规范&quot;，后者常被挤掉；同一类规范问题在不同需求里反复被提出、反复修。</p><p>Matt Pocock 的 skills（<code>grill-with-docs</code> 的术语表、<code>tdd</code> 先写测试、<code>code-review</code> 分 Standards 和 Spec 两个方向、<code>retro</code>）、pstack 的 <code>correct</code>（把纠正变成规则）和 Specification by Example 的思路一致：把分歧放到最便宜的时候暴露，用具体的例子而不是抽象的描述对齐，把反复出现的问题交给机器挡住。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>验收标准带例子</strong>：<code>acceptance-criteria</code> 要求每条 AC 至少一组具体的输入和期望输出，按规则计算的给出覆盖边界的几组；确认前的独立审阅检查这一点，缺的替需求方拟好例子请其确认。方案的测试直接用这些例子作为期望值，不另编。</li><li><strong>验收测试先提交</strong>：适合测试先行时，实现先把从例子写出的测试单独提交（失败的），在结果文件中写明文件和提交（<code>acceptance_tests</code>、<code>acceptance_tests_commit</code>）。代码评审前引擎用 git 核对它们之后有没有被改，改过的交给评审逐个确认依据。只核对、不阻止：测试本身写错是常见的合理修改。</li><li><strong>方案确认点</strong>（<code>designApproval</code>）：方案审核通过、写代码之前，引擎可以停下来（状态 <code>waiting_for_approval</code>），请需求方看 <code>preview.md</code>（做完后会看到什么、需要确认的假设、不会变的）和界面原型（<code>prototype/</code> 中的静态 HTML）。<code>--approve</code> 继续；要修改的走需求变更（更新 spec 后 <code>--resume</code>，从方案设计增量处理，再确认一次）。等待单独的 <code>--resume</code> 会被拒绝，避免对话误把&quot;继续&quot;当作确认。 <ul><li>默认只对标准档的界面改动开启（<code>mode: &quot;ui&quot;</code>，由方案在结果文件中判断 <code>ui_change</code>）：界面最容易&quot;做对了但不是想要的&quot;，其他需求不增加等待。<code>always</code> 每次都停，<code>off</code> 关闭。</li><li>无人值守的代价：等待提醒复用 <code>waitingReminderHours</code>；<code>autoContinueHours</code> 大于 0 时通过 Paseo 定时任务让对话在超时后按方案继续（默认 0，一直等待）。</li><li>方案中的假设标明对使用者可见的影响（界面、数据、权限）。影响这些、猜错会做错的转为阻塞问题；其余在确认点请需求方过目，没有确认点时由报告交给需求方。</li></ul></li><li><strong>代码评审分两个方向</strong>（<code>reviewAxes</code>，默认标准档开启）：第一轮由规格评审（每条 AC 是否实现、测试期望值是否与例子一致、范围、与预览是否一致）和规范评审（项目惯例与范例文件、术语、测试质量、安全、简单性）并行，reviewer 核实汇总成一份结论。复用评审小组的并行和汇总，两位都用配置的 reviewer；配置了评审小组时以小组为准；后续轮次仍由一位评审核对修复。代价是每个标准档需求多两次评审。</li><li><strong>术语表和范例文件</strong>：沿用仓库根目录的 <code>GLOSSARY.md</code>（不另建文件），增加&quot;代码中的名字&quot;；<code>/req-setup</code> 第一次整理并在项目说明中列出各类代码的范例文件；方案的每个任务写明参照的文件，新概念补进术语表。</li><li><strong>反复出现的问题变成规则</strong>：完成报告把一条项目规则就能挡住的问题写进功能目录的 <code>lessons.tsv</code>。放在各自的功能目录，而不是一个共用文件，避免各需求分支合并时冲突。<code>req digest</code> 汇总所有工作区中的需求，同一类别出现在两个以上需求时提示；<code>/req-retro</code> 据此建议规则，落地后把类别写进 <code>.requirement-pipeline/lessons-handled.txt</code>。规则仍由人批准。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件新增可选字段 <code>approval</code> 和状态值 <code>waiting_for_approval</code>，格式版本仍为 1。回滚到更早的版本后，旧引擎把它当作可以继续的中断，继续时不经确认直接写代码，可以接受。</li><li>结果文件新增可选字段（<code>ui_change</code>、<code>acceptance_tests</code>、<code>acceptance_tests_commit</code>）。外部通知新增事件 <code>approval</code>。</li><li>标准档的界面改动多一次等待；每个标准档需求的第一轮代码评审多两次 agent 运行。都可以在配置中关闭。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0024-confirm-early-review-axes.md">docs/adr/0024-confirm-early-review-axes.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0024-confirm-early-review-axes.md">在 GitHub 上编辑</a></p>',2)])])}const _=o(r,[["render",d]]);export{m as __pageData,_ as default};
+import{_ as o,o as a,c,a2 as t}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0024-confirm-early-review-axes.md","filePath":"reference/adr/0024-confirm-early-review-axes.md","lastUpdated":null}'),r={name:"reference/adr/0024-confirm-early-review-axes.md"};function d(i,e,s,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0024-让分歧更早暴露-验收例子、方案确认点、两个方向的评审、反复的问题变成规则" tabindex="-1">0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则 <a class="header-anchor" href="#_0024-让分歧更早暴露-验收例子、方案确认点、两个方向的评审、反复的问题变成规则" aria-label="Permalink to &quot;0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0012-review-panel">0012</a>：评审的两个方向复用评审小组的机制；<a href="./0022-develop-and-verify-phases">0022</a>：方案确认点与闸口一样停下来等人，但在写代码之前）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>需求做出来&quot;不符合预期&quot;，多半不是代码写错，而是需求方和 agent 对&quot;做成什么样&quot;理解不同，并且直到验收才发现。到 1.8.0-beta.1 为止，需求方在确认需求说明之后，要等到报告才再看到结果；验收标准常常是抽象的描述（&quot;在限制时间内重复发送会被拒绝&quot;），测试的期望值由实现者自己定；代码评审一位评审者同时看&quot;做没做对&quot;和&quot;做得规不规范&quot;，后者常被挤掉；同一类规范问题在不同需求里反复被提出、反复修。</p><p>Matt Pocock 的 skills（<code>grill-with-docs</code> 的术语表、<code>tdd</code> 先写测试、<code>code-review</code> 分 Standards 和 Spec 两个方向、<code>retro</code>）、pstack 的 <code>correct</code>（把纠正变成规则）和 Specification by Example 的思路一致：把分歧放到最便宜的时候暴露，用具体的例子而不是抽象的描述对齐，把反复出现的问题交给机器挡住。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>验收标准带例子</strong>：<code>acceptance-criteria</code> 要求每条 AC 至少一组具体的输入和期望输出，按规则计算的给出覆盖边界的几组；确认前的独立审阅检查这一点，缺的替需求方拟好例子请其确认。方案的测试直接用这些例子作为期望值，不另编。</li><li><strong>验收测试先提交</strong>：适合测试先行时，实现先把从例子写出的测试单独提交（失败的），在结果文件中写明文件和提交（<code>acceptance_tests</code>、<code>acceptance_tests_commit</code>）。代码评审前引擎用 git 核对它们之后有没有被改，改过的交给评审逐个确认依据。只核对、不阻止：测试本身写错是常见的合理修改。</li><li><strong>方案确认点</strong>（<code>designApproval</code>）：方案审核通过、写代码之前，引擎可以停下来（状态 <code>waiting_for_approval</code>），请需求方看 <code>preview.md</code>（做完后会看到什么、需要确认的假设、不会变的）和界面原型（<code>prototype/</code> 中的静态 HTML）。<code>--approve</code> 继续；要修改的走需求变更（更新 spec 后 <code>--resume</code>，从方案设计增量处理，再确认一次）。等待单独的 <code>--resume</code> 会被拒绝，避免对话误把&quot;继续&quot;当作确认。 <ul><li>默认只对标准档的界面改动开启（<code>mode: &quot;ui&quot;</code>，由方案在结果文件中判断 <code>ui_change</code>）：界面最容易&quot;做对了但不是想要的&quot;，其他需求不增加等待。<code>always</code> 每次都停，<code>off</code> 关闭。</li><li>无人值守的代价：等待提醒复用 <code>waitingReminderHours</code>；<code>autoContinueHours</code> 大于 0 时通过 Paseo 定时任务让对话在超时后按方案继续（默认 0，一直等待）。</li><li>方案中的假设标明对使用者可见的影响（界面、数据、权限）。影响这些、猜错会做错的转为阻塞问题；其余在确认点请需求方过目，没有确认点时由报告交给需求方。</li></ul></li><li><strong>代码评审分两个方向</strong>（<code>reviewAxes</code>，默认标准档开启）：第一轮由规格评审（每条 AC 是否实现、测试期望值是否与例子一致、范围、与预览是否一致）和规范评审（项目惯例与范例文件、术语、测试质量、安全、简单性）并行，reviewer 核实汇总成一份结论。复用评审小组的并行和汇总，两位都用配置的 reviewer；配置了评审小组时以小组为准；后续轮次仍由一位评审核对修复。代价是每个标准档需求多两次评审。</li><li><strong>术语表和范例文件</strong>：沿用仓库根目录的 <code>GLOSSARY.md</code>（不另建文件），增加&quot;代码中的名字&quot;；<code>/req-setup</code> 第一次整理并在项目说明中列出各类代码的范例文件；方案的每个任务写明参照的文件，新概念补进术语表。</li><li><strong>反复出现的问题变成规则</strong>：完成报告把一条项目规则就能挡住的问题写进功能目录的 <code>lessons.tsv</code>。放在各自的功能目录，而不是一个共用文件，避免各需求分支合并时冲突。<code>req digest</code> 汇总所有工作区中的需求，同一类别出现在两个以上需求时提示；<code>/req-retro</code> 据此建议规则，落地后把类别写进 <code>.requirement-pipeline/lessons-handled.txt</code>。规则仍由人批准。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件新增可选字段 <code>approval</code> 和状态值 <code>waiting_for_approval</code>，格式版本仍为 1。回滚到更早的版本后，旧引擎把它当作可以继续的中断，继续时不经确认直接写代码，可以接受。</li><li>结果文件新增可选字段（<code>ui_change</code>、<code>acceptance_tests</code>、<code>acceptance_tests_commit</code>）。外部通知新增事件 <code>approval</code>。</li><li>标准档的界面改动多一次等待；每个标准档需求的第一轮代码评审多两次 agent 运行。都可以在配置中关闭。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0024-confirm-early-review-axes.md">docs/adr/0024-confirm-early-review-axes.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0024-confirm-early-review-axes.md">在 GitHub 上编辑</a></p>',2)])])}const _=o(r,[["render",d]]);export{m as __pageData,_ as default};

package/site-dist/assets/{reference_adr_0024-confirm-early-review-axes.md.FmK_ke0x.lean.js → reference_adr_0024-confirm-early-review-axes.md.BRxVXJa4.lean.js}

@@ -1 +1 @@
-import{_ as o,o as a,c,a3 as t}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0024-confirm-early-review-axes.md","filePath":"reference/adr/0024-confirm-early-review-axes.md","lastUpdated":null}'),r={name:"reference/adr/0024-confirm-early-review-axes.md"};function d(i,e,s,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[t("",2)])])}const _=o(r,[["render",d]]);export{m as __pageData,_ as default};
+import{_ as o,o as a,c,a2 as t}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0024-confirm-early-review-axes.md","filePath":"reference/adr/0024-confirm-early-review-axes.md","lastUpdated":null}'),r={name:"reference/adr/0024-confirm-early-review-axes.md"};function d(i,e,s,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[t("",2)])])}const _=o(r,[["render",d]]);export{m as __pageData,_ as default};

package/site-dist/assets/{reference_adr_0025-joint-requirements.md.ChoKvMUx.js → reference_adr_0025-joint-requirements.md.ClCFyIiN.js}

@@ -1 +1 @@
-import{_ as t,o,c as a,a3 as i}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0025 联合需求：一个需求同时改几个仓库","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0025-joint-requirements.md","filePath":"reference/adr/0025-joint-requirements.md","lastUpdated":null}'),r={name:"reference/adr/0025-joint-requirements.md"};function n(s,e,d,l,c,u){return o(),a("div",null,[...e[0]||(e[0]=[i('<div><h1 id="_0025-联合需求-一个需求同时改几个仓库" tabindex="-1">0025 联合需求：一个需求同时改几个仓库 <a class="header-anchor" href="#_0025-联合需求-一个需求同时改几个仓库" aria-label="Permalink to &quot;0025 联合需求：一个需求同时改几个仓库&quot;">​</a></h1><ul><li>状态：已采纳（扩展 <a href="./0018-own-worktree-option">0018</a>：为其他仓库新建工作区；<a href="./0023-types-gate-slices">0023</a>：质量门按仓库进行；落实 1.8 设计中&quot;多代码库需求&quot;的第三种形态）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>前后端分在两个仓库的需求很常见：后端加接口，前端加页面。1.8.0-beta.1 起其他仓库可以作为只读参考，但两边都要改时只能拆成两个互不知道的需求：接口由两边各自理解，联调问题要到人工测试时才暴露，两份报告也凑不成&quot;这个需求做完了没有&quot;的答案。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>主仓库协调，复用单仓库的步骤</strong>：发起需求的仓库是主仓库，它的运行就是协调者，状态只有一份（主仓库的 <code>state.json</code>）。不另起子流水线进程：同一套步骤、结果文件、续跑和用量统计都直接适用，只是某些步骤换一个仓库运行。</li><li>spec 头部 <code>- 联合开发：&lt;名称&gt;</code> 指定还要改的仓库，名称来自 <code>relatedRepos</code>，最多两个（一共三个仓库）。启动前检查名称已登记、本机存在、是 git 仓库，否则不启动、不留运行记录。</li><li><strong>工作区</strong>：每个联合仓库由 Paseo 新建一个工作区，分支 <code>feature/&lt;需求&gt;</code>，从那个仓库当前检出的分支切出；那份检出本身不切换分支、不提交（同 0018 的理由）。同名分支已存在时停下来请人处理，不覆盖。</li><li><strong>步骤怎么分</strong>： <ul><li>方案设计、方案审核与修订、方案确认点、提测说明、功能验证、复验、完成报告都在主仓库。方案按仓库分开写，并写出接口约定 <code>contract.md</code>，方案审核通过后冻结。</li><li>实现、代码评审 ⇄ 修复在<strong>每个仓库各自进行、同时进行</strong>：步骤 agent 的工作目录和 Paseo 工作区是那个仓库的，仍挂在发起的对话下；步骤键加仓库后缀（<code>implement@backend</code>），结果文件写在那个仓库的功能目录。联合需求不按切片实现（每个仓库一个实现步骤），避免切片与仓库交错。</li><li>实现前，主仓库的需求说明、访谈记录、方案、接口约定、预览同步到各仓库的功能目录并提交，合并那个仓库的人能在代码旁边读到。</li><li>功能验证前，各仓库 <code>paseo.json</code> 中的服务都由 Paseo 用当前代码启动。验证和复验的结果用 <code>defect_repos</code> 写明缺陷在哪个仓库，缺陷修复只在那些仓库进行；没写时每个仓库都看一遍。</li></ul></li><li><strong>质量门按仓库</strong>：每个仓库用它自己项目配置中的 <code>checks</code>、自己的基线和记录（<code>joint[].codeBase</code>、<code>joint[].gate</code>）；它自己的项目说明、验证方法和按步骤的说明用在它的步骤里。</li><li><strong>失败与继续</strong>：同时进行的步骤中一个失败时，等其他的做完再中断，不让 agent 在没人看着的情况下继续改代码；继续时沿用已建的工作区和已完成的步骤。</li><li><strong>安全边界不变</strong>：只做本地提交，不合并、不推送；各仓库的合并顺序写进提测说明和报告，由人决定。不克隆本机没有的仓库，不自动部署。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件新增可选字段 <code>joint</code>，结果文件新增可选字段 <code>defect_repos</code>，格式版本仍为 1。回滚到旧版本后，旧引擎忽略 <code>joint</code>，只在主仓库继续，已经在其他仓库做的改动留在它们的工作区里。</li><li>每个联合仓库多一次实现和一轮以上的代码评审，用量大约按仓库数增加；三个步骤同时运行时，本机同时运行的 agent 也更多。</li><li>一个需求的改动分散在几个分支上，合并需要人按顺序进行。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0025-joint-requirements.md">docs/adr/0025-joint-requirements.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0025-joint-requirements.md">在 GitHub 上编辑</a></p>',2)])])}const p=t(r,[["render",n]]);export{m as __pageData,p as default};
+import{_ as t,o,c as a,a2 as i}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0025 联合需求：一个需求同时改几个仓库","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0025-joint-requirements.md","filePath":"reference/adr/0025-joint-requirements.md","lastUpdated":null}'),r={name:"reference/adr/0025-joint-requirements.md"};function n(s,e,d,l,c,u){return o(),a("div",null,[...e[0]||(e[0]=[i('<div><h1 id="_0025-联合需求-一个需求同时改几个仓库" tabindex="-1">0025 联合需求：一个需求同时改几个仓库 <a class="header-anchor" href="#_0025-联合需求-一个需求同时改几个仓库" aria-label="Permalink to &quot;0025 联合需求：一个需求同时改几个仓库&quot;">​</a></h1><ul><li>状态：已采纳（扩展 <a href="./0018-own-worktree-option">0018</a>：为其他仓库新建工作区；<a href="./0023-types-gate-slices">0023</a>：质量门按仓库进行；落实 1.8 设计中&quot;多代码库需求&quot;的第三种形态）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>前后端分在两个仓库的需求很常见：后端加接口，前端加页面。1.8.0-beta.1 起其他仓库可以作为只读参考，但两边都要改时只能拆成两个互不知道的需求：接口由两边各自理解，联调问题要到人工测试时才暴露，两份报告也凑不成&quot;这个需求做完了没有&quot;的答案。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>主仓库协调，复用单仓库的步骤</strong>：发起需求的仓库是主仓库，它的运行就是协调者，状态只有一份（主仓库的 <code>state.json</code>）。不另起子流水线进程：同一套步骤、结果文件、续跑和用量统计都直接适用，只是某些步骤换一个仓库运行。</li><li>spec 头部 <code>- 联合开发：&lt;名称&gt;</code> 指定还要改的仓库，名称来自 <code>relatedRepos</code>，最多两个（一共三个仓库）。启动前检查名称已登记、本机存在、是 git 仓库，否则不启动、不留运行记录。</li><li><strong>工作区</strong>：每个联合仓库由 Paseo 新建一个工作区，分支 <code>feature/&lt;需求&gt;</code>，从那个仓库当前检出的分支切出；那份检出本身不切换分支、不提交（同 0018 的理由）。同名分支已存在时停下来请人处理，不覆盖。</li><li><strong>步骤怎么分</strong>： <ul><li>方案设计、方案审核与修订、方案确认点、提测说明、功能验证、复验、完成报告都在主仓库。方案按仓库分开写，并写出接口约定 <code>contract.md</code>，方案审核通过后冻结。</li><li>实现、代码评审 ⇄ 修复在<strong>每个仓库各自进行、同时进行</strong>：步骤 agent 的工作目录和 Paseo 工作区是那个仓库的，仍挂在发起的对话下；步骤键加仓库后缀（<code>implement@backend</code>），结果文件写在那个仓库的功能目录。联合需求不按切片实现（每个仓库一个实现步骤），避免切片与仓库交错。</li><li>实现前，主仓库的需求说明、访谈记录、方案、接口约定、预览同步到各仓库的功能目录并提交，合并那个仓库的人能在代码旁边读到。</li><li>功能验证前，各仓库 <code>paseo.json</code> 中的服务都由 Paseo 用当前代码启动。验证和复验的结果用 <code>defect_repos</code> 写明缺陷在哪个仓库，缺陷修复只在那些仓库进行；没写时每个仓库都看一遍。</li></ul></li><li><strong>质量门按仓库</strong>：每个仓库用它自己项目配置中的 <code>checks</code>、自己的基线和记录（<code>joint[].codeBase</code>、<code>joint[].gate</code>）；它自己的项目说明、验证方法和按步骤的说明用在它的步骤里。</li><li><strong>失败与继续</strong>：同时进行的步骤中一个失败时，等其他的做完再中断，不让 agent 在没人看着的情况下继续改代码；继续时沿用已建的工作区和已完成的步骤。</li><li><strong>安全边界不变</strong>：只做本地提交，不合并、不推送；各仓库的合并顺序写进提测说明和报告，由人决定。不克隆本机没有的仓库，不自动部署。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>状态文件新增可选字段 <code>joint</code>，结果文件新增可选字段 <code>defect_repos</code>，格式版本仍为 1。回滚到旧版本后，旧引擎忽略 <code>joint</code>，只在主仓库继续，已经在其他仓库做的改动留在它们的工作区里。</li><li>每个联合仓库多一次实现和一轮以上的代码评审，用量大约按仓库数增加；三个步骤同时运行时，本机同时运行的 agent 也更多。</li><li>一个需求的改动分散在几个分支上，合并需要人按顺序进行。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0025-joint-requirements.md">docs/adr/0025-joint-requirements.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0025-joint-requirements.md">在 GitHub 上编辑</a></p>',2)])])}const p=t(r,[["render",n]]);export{m as __pageData,p as default};

package/site-dist/assets/{reference_adr_0025-joint-requirements.md.ChoKvMUx.lean.js → reference_adr_0025-joint-requirements.md.ClCFyIiN.lean.js}

@@ -1 +1 @@
-import{_ as t,o,c as a,a3 as i}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0025 联合需求：一个需求同时改几个仓库","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0025-joint-requirements.md","filePath":"reference/adr/0025-joint-requirements.md","lastUpdated":null}'),r={name:"reference/adr/0025-joint-requirements.md"};function n(s,e,d,l,c,u){return o(),a("div",null,[...e[0]||(e[0]=[i("",2)])])}const p=t(r,[["render",n]]);export{m as __pageData,p as default};
+import{_ as t,o,c as a,a2 as i}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0025 联合需求：一个需求同时改几个仓库","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0025-joint-requirements.md","filePath":"reference/adr/0025-joint-requirements.md","lastUpdated":null}'),r={name:"reference/adr/0025-joint-requirements.md"};function n(s,e,d,l,c,u){return o(),a("div",null,[...e[0]||(e[0]=[i("",2)])])}const p=t(r,[["render",n]]);export{m as __pageData,p as default};

package/site-dist/assets/{reference_adr_0026-machine-records-and-api.md.veybjBPq.js → reference_adr_0026-machine-records-and-api.md.Bv1k_WjT.js}

@@ -1 +1 @@
-import{_ as a,o,c as r,a3 as t}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"0026 本机的需求索引、使用记录和 req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0026-machine-records-and-api.md","filePath":"reference/adr/0026-machine-records-and-api.md","lastUpdated":null}'),i={name:"reference/adr/0026-machine-records-and-api.md"};function d(c,e,s,n,l,p){return o(),r("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0026-本机的需求索引、使用记录和-req-api" tabindex="-1">0026 本机的需求索引、使用记录和 req api <a class="header-anchor" href="#_0026-本机的需求索引、使用记录和-req-api" aria-label="Permalink to &quot;0026 本机的需求索引、使用记录和 req api&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0010-generated-feature-overview">0010</a>：仓库内的总览仍现场生成；<a href="./0014-notifier-slot">0014</a>：通知槽不变）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>1.9 要做两件依赖同一份数据的事：Paseo 插件在网页端列出本机所有项目的需求、做确认和停止这类管理操作；管理方要定期看到 req-kit 的使用情况（多少需求、多快、返工多少、花了多少）。在此之前，需求的状态分散在各仓库各工作区的功能目录里，<code>req list</code> 只看得到当前仓库；用时和用量只在每个需求的状态文件中，没有跨需求的汇总；<code>req list</code>、<code>req status</code> 只输出给人看的文字，程序要用只能解析文字或直接读状态文件，后者把状态文件的内部格式变成了对外约定。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>需求索引</strong>：引擎每次写状态文件时，确认本机配置目录下的 <code>index/&lt;key&gt;.json</code> 记着这个需求在哪里（目录、功能目录、对话所在目录、工作区），一个需求一个文件，几个流水线同时运行也不会互相覆盖。索引只记位置，阶段和进度仍然现场从功能目录读取，所以不会和实际情况不一致。</li><li><strong>使用记录</strong>：每次运行（后台进程从开始到结束）结束时向 <code>usage/runs.jsonl</code> 追加一行：步骤、用时、用量、质量门、结束时的状态。按运行而不是按需求记，追加即可，不用改写旧记录；需求层面的数字（交付周期、评审轮数、等待时长）在统计时从同一需求的各次运行算出。</li><li><strong>只在本机，不自动上报</strong>：两样都不提交进仓库，也不发往任何地方；不记需求内容和代码。汇总给管理方时由人导出（<code>req stats --export</code>）再合并（<code>--merge</code>）；之后定下汇总通道时，用 1.9 的集成模块订阅&quot;运行结束&quot;，数据格式不变。</li><li><strong><code>req stats</code></strong>：Markdown 汇总、JSON、每个需求一行的 CSV，<code>--report</code> 生成汇报用的两份文件。</li><li><strong><code>req api</code></strong>：给程序的稳定接口，一行 JSON，带 <code>schema</code>。读操作（list、status、file、stats、index）不改变任何东西；管理操作 <code>req api run &lt;approve|stop|resume|verify&gt;</code> 就是在相应目录执行 <code>req &lt;命令&gt;</code>，引擎仍是唯一修改状态的一方。<code>file</code> 只能读功能目录中的文档白名单。</li><li><strong>评估和测试不进记录</strong>：<code>REQ_KIT_NO_RECORD=1</code> 关闭记录，评估运行设置它；测试把本机配置目录指向临时目录。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>插件和脚本只依赖 <code>contracts/cli-json.md</code>，状态文件的内部格式可以继续演进。</li><li>1.9 之前运行过的需求不在索引里，需要 <code>req index --rebuild</code> 补登；删掉的目录在索引里显示为&quot;已移除&quot;，<code>--prune</code> 清理。</li><li>记录是尽力而为的：写失败不影响流水线，被强制结束（kill -9、断电）的运行没有记录，统计会少算这次运行。</li><li>主机名写进每条记录，用于合并多台机器的数据时区分来源。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0026-machine-records-and-api.md">docs/adr/0026-machine-records-and-api.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0026-machine-records-and-api.md">在 GitHub 上编辑</a></p>',2)])])}const m=a(i,[["render",d]]);export{u as __pageData,m as default};
+import{_ as a,o,c as r,a2 as t}from"./chunks/framework.BetZR81g.js";const u=JSON.parse('{"title":"0026 本机的需求索引、使用记录和 req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0026-machine-records-and-api.md","filePath":"reference/adr/0026-machine-records-and-api.md","lastUpdated":null}'),i={name:"reference/adr/0026-machine-records-and-api.md"};function d(c,e,s,n,l,p){return o(),r("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0026-本机的需求索引、使用记录和-req-api" tabindex="-1">0026 本机的需求索引、使用记录和 req api <a class="header-anchor" href="#_0026-本机的需求索引、使用记录和-req-api" aria-label="Permalink to &quot;0026 本机的需求索引、使用记录和 req api&quot;">​</a></h1><ul><li>状态：已采纳（补充 <a href="./0010-generated-feature-overview">0010</a>：仓库内的总览仍现场生成；<a href="./0014-notifier-slot">0014</a>：通知槽不变）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>1.9 要做两件依赖同一份数据的事：Paseo 插件在网页端列出本机所有项目的需求、做确认和停止这类管理操作；管理方要定期看到 req-kit 的使用情况（多少需求、多快、返工多少、花了多少）。在此之前，需求的状态分散在各仓库各工作区的功能目录里，<code>req list</code> 只看得到当前仓库；用时和用量只在每个需求的状态文件中，没有跨需求的汇总；<code>req list</code>、<code>req status</code> 只输出给人看的文字，程序要用只能解析文字或直接读状态文件，后者把状态文件的内部格式变成了对外约定。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>需求索引</strong>：引擎每次写状态文件时，确认本机配置目录下的 <code>index/&lt;key&gt;.json</code> 记着这个需求在哪里（目录、功能目录、对话所在目录、工作区），一个需求一个文件，几个流水线同时运行也不会互相覆盖。索引只记位置，阶段和进度仍然现场从功能目录读取，所以不会和实际情况不一致。</li><li><strong>使用记录</strong>：每次运行（后台进程从开始到结束）结束时向 <code>usage/runs.jsonl</code> 追加一行：步骤、用时、用量、质量门、结束时的状态。按运行而不是按需求记，追加即可，不用改写旧记录；需求层面的数字（交付周期、评审轮数、等待时长）在统计时从同一需求的各次运行算出。</li><li><strong>只在本机，不自动上报</strong>：两样都不提交进仓库，也不发往任何地方；不记需求内容和代码。汇总给管理方时由人导出（<code>req stats --export</code>）再合并（<code>--merge</code>）；之后定下汇总通道时，用 1.9 的集成模块订阅&quot;运行结束&quot;，数据格式不变。</li><li><strong><code>req stats</code></strong>：Markdown 汇总、JSON、每个需求一行的 CSV，<code>--report</code> 生成汇报用的两份文件。</li><li><strong><code>req api</code></strong>：给程序的稳定接口，一行 JSON，带 <code>schema</code>。读操作（list、status、file、stats、index）不改变任何东西；管理操作 <code>req api run &lt;approve|stop|resume|verify&gt;</code> 就是在相应目录执行 <code>req &lt;命令&gt;</code>，引擎仍是唯一修改状态的一方。<code>file</code> 只能读功能目录中的文档白名单。</li><li><strong>评估和测试不进记录</strong>：<code>REQ_KIT_NO_RECORD=1</code> 关闭记录，评估运行设置它；测试把本机配置目录指向临时目录。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>插件和脚本只依赖 <code>contracts/cli-json.md</code>，状态文件的内部格式可以继续演进。</li><li>1.9 之前运行过的需求不在索引里，需要 <code>req index --rebuild</code> 补登；删掉的目录在索引里显示为&quot;已移除&quot;，<code>--prune</code> 清理。</li><li>记录是尽力而为的：写失败不影响流水线，被强制结束（kill -9、断电）的运行没有记录，统计会少算这次运行。</li><li>主机名写进每条记录，用于合并多台机器的数据时区分来源。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0026-machine-records-and-api.md">docs/adr/0026-machine-records-and-api.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0026-machine-records-and-api.md">在 GitHub 上编辑</a></p>',2)])])}const m=a(i,[["render",d]]);export{u as __pageData,m as default};

package/site-dist/assets/{reference_adr_0026-machine-records-and-api.md.veybjBPq.lean.js → reference_adr_0026-machine-records-and-api.md.Bv1k_WjT.lean.js}

@@ -1 +1 @@
-import{_ as a,o,c as r,a3 as t}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"0026 本机的需求索引、使用记录和 req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0026-machine-records-and-api.md","filePath":"reference/adr/0026-machine-records-and-api.md","lastUpdated":null}'),i={name:"reference/adr/0026-machine-records-and-api.md"};function d(c,e,s,n,l,p){return o(),r("div",null,[...e[0]||(e[0]=[t("",2)])])}const m=a(i,[["render",d]]);export{u as __pageData,m as default};
+import{_ as a,o,c as r,a2 as t}from"./chunks/framework.BetZR81g.js";const u=JSON.parse('{"title":"0026 本机的需求索引、使用记录和 req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0026-machine-records-and-api.md","filePath":"reference/adr/0026-machine-records-and-api.md","lastUpdated":null}'),i={name:"reference/adr/0026-machine-records-and-api.md"};function d(c,e,s,n,l,p){return o(),r("div",null,[...e[0]||(e[0]=[t("",2)])])}const m=a(i,[["render",d]]);export{u as __pageData,m as default};

package/site-dist/assets/{reference_adr_0027-paseo-plugin.md.BMX33ZNU.js → reference_adr_0027-paseo-plugin.md.CcpaKksi.js}

@@ -1 +1 @@
-import{_ as o,o as a,c as i,a3 as t}from"./chunks/framework.B9qR_F1m.js";const q=JSON.parse('{"title":"0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0027-paseo-plugin.md","filePath":"reference/adr/0027-paseo-plugin.md","lastUpdated":null}'),r={name:"reference/adr/0027-paseo-plugin.md"};function d(s,e,l,n,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0027-paseo-插件-随-req-kit-一起发布-只通过-req-api-工作" tabindex="-1">0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作 <a class="header-anchor" href="#_0027-paseo-插件-随-req-kit-一起发布-只通过-req-api-工作" aria-label="Permalink to &quot;0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作&quot;">​</a></h1><ul><li>状态：已采纳（建立在 <a href="./0026-machine-records-and-api">0026</a> 的需求索引和 <code>req api</code> 之上；不改变 <a href="./0003-script-engine-not-hub">0003</a>：流程仍由脚本引擎驱动）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>需求方和项目经理想在 Paseo 的网页端或手机上看到所有需求在哪一步、卡在哪里，并做确认方案、停止、继续这类操作，而不是在对话里问或在终端敲 <code>req</code>。Paseo 0.11 有完整的插件机制：界面（侧边栏、页面、工作区面板、按钮、命令中心）、daemon 侧的 RPC 和生命周期事件，同一份界面代码在桌面版、网页端和手机上运行。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>插件只做展示和管理，不参与流程</strong>：每个读取是一次 <code>req api</code>，每个管理操作是 <code>req api run &lt;approve|stop|resume|verify&gt;</code>，与在终端执行 <code>req &lt;命令&gt;</code> 完全相同。插件不读写状态文件，引擎仍是唯一修改需求状态的一方。不提供发起需求（需要在对话中对齐）、编辑需求说明或方案、修改配置、删除。</li><li><strong>随 req-kit 一起发布，从固定目录安装</strong>：插件源码在仓库的 <code>paseo-plugin/</code>，打进 <code>paseo-req-kit</code> 包。<code>req plugin install</code> 把当前版本的插件复制到 <code>~/.req-kit/paseo-plugin</code>，用 <code>paseo plugin install &lt;目录&gt;</code> 安装；之后每次启用版本（setup、upgrade、use）都刷新这个目录并 <code>paseo plugin reload</code>。这样插件版本总是和启用的 req-kit 一致，也不需要单独的 npm 包、网络或第二套发布配置。设计时曾考虑第二个 npm 包，Paseo 的目录安装让它变得不必要。</li><li><strong>插件总开关要人同意</strong>：Paseo 的 <code>pluginsEnabled</code> 默认关闭，插件是不受沙箱限制的代码。<code>req plugin install</code> 和安装脚本都先说明再询问，<code>--yes</code> / <code>--with-plugin</code> 表示同意；移除插件不改动总开关。</li><li><strong>只读模式</strong>：Paseo 的插件没有按用户区分的权限，能连上 daemon 的人都能操作。插件设置中的&quot;只读&quot;隐藏管理操作，daemon 侧也拒绝它们。</li><li><strong>只依赖 <code>req api</code> 的格式</strong>：插件通过本机配置目录的 <code>active.json</code> 找到启用的版本并运行它的 <code>req api</code>，不引用 req-kit 的内部代码；req-kit 太旧时插件给出升级提示。</li><li><strong>界面按 Paseo 的跨平台规则写</strong>：只用 React Native 组件和主题颜色，不用 DOM。插件的界面部分由 CI 用 Paseo 的 SDK 做类型检查（<code>paseo-plugin/</code> 的开发依赖），daemon 侧和 <code>req plugin</code> 有单元测试；界面效果需要在真实的 Paseo 中检查。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新增 <code>req plugin install|status|remove</code>，安装脚本最后可选安装插件。</li><li>列表靠轮询刷新（默认 10 秒，可设置）；daemon 侧把短时间内的多个列表请求合并成一次 <code>req api list</code>。</li><li>步骤 agent 的&quot;需求&quot;按钮靠 req-kit 给步骤 agent 打的标签（<code>requirement-pipeline</code>）找到需求；工作区的&quot;需求&quot;按钮按目录匹配需求。</li><li><code>paseo-plugin/package.json</code> 的版本必须与 req-kit 相同（测试检查），<code>paseo-plugin.json</code> 的 Paseo 范围与 <code>reqKit.paseo</code> 相同。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0027-paseo-plugin.md">docs/adr/0027-paseo-plugin.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0027-paseo-plugin.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(r,[["render",d]]);export{q as __pageData,g as default};
+import{_ as o,o as a,c as i,a2 as t}from"./chunks/framework.BetZR81g.js";const q=JSON.parse('{"title":"0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0027-paseo-plugin.md","filePath":"reference/adr/0027-paseo-plugin.md","lastUpdated":null}'),r={name:"reference/adr/0027-paseo-plugin.md"};function d(s,e,l,n,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t('<div><h1 id="_0027-paseo-插件-随-req-kit-一起发布-只通过-req-api-工作" tabindex="-1">0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作 <a class="header-anchor" href="#_0027-paseo-插件-随-req-kit-一起发布-只通过-req-api-工作" aria-label="Permalink to &quot;0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作&quot;">​</a></h1><ul><li>状态：已采纳（建立在 <a href="./0026-machine-records-and-api">0026</a> 的需求索引和 <code>req api</code> 之上；不改变 <a href="./0003-script-engine-not-hub">0003</a>：流程仍由脚本引擎驱动）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>需求方和项目经理想在 Paseo 的网页端或手机上看到所有需求在哪一步、卡在哪里，并做确认方案、停止、继续这类操作，而不是在对话里问或在终端敲 <code>req</code>。Paseo 0.11 有完整的插件机制：界面（侧边栏、页面、工作区面板、按钮、命令中心）、daemon 侧的 RPC 和生命周期事件，同一份界面代码在桌面版、网页端和手机上运行。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>插件只做展示和管理，不参与流程</strong>：每个读取是一次 <code>req api</code>，每个管理操作是 <code>req api run &lt;approve|stop|resume|verify&gt;</code>，与在终端执行 <code>req &lt;命令&gt;</code> 完全相同。插件不读写状态文件，引擎仍是唯一修改需求状态的一方。不提供发起需求（需要在对话中对齐）、编辑需求说明或方案、修改配置、删除。</li><li><strong>随 req-kit 一起发布，从固定目录安装</strong>：插件源码在仓库的 <code>paseo-plugin/</code>，打进 <code>paseo-req-kit</code> 包。<code>req plugin install</code> 把当前版本的插件复制到 <code>~/.req-kit/paseo-plugin</code>，用 <code>paseo plugin install &lt;目录&gt;</code> 安装；之后每次启用版本（setup、upgrade、use）都刷新这个目录并 <code>paseo plugin reload</code>。这样插件版本总是和启用的 req-kit 一致，也不需要单独的 npm 包、网络或第二套发布配置。设计时曾考虑第二个 npm 包，Paseo 的目录安装让它变得不必要。</li><li><strong>插件总开关要人同意</strong>：Paseo 的 <code>pluginsEnabled</code> 默认关闭，插件是不受沙箱限制的代码。<code>req plugin install</code> 和安装脚本都先说明再询问，<code>--yes</code> / <code>--with-plugin</code> 表示同意；移除插件不改动总开关。</li><li><strong>只读模式</strong>：Paseo 的插件没有按用户区分的权限，能连上 daemon 的人都能操作。插件设置中的&quot;只读&quot;隐藏管理操作，daemon 侧也拒绝它们。</li><li><strong>只依赖 <code>req api</code> 的格式</strong>：插件通过本机配置目录的 <code>active.json</code> 找到启用的版本并运行它的 <code>req api</code>，不引用 req-kit 的内部代码；req-kit 太旧时插件给出升级提示。</li><li><strong>界面按 Paseo 的跨平台规则写</strong>：只用 React Native 组件和主题颜色，不用 DOM。插件的界面部分由 CI 用 Paseo 的 SDK 做类型检查（<code>paseo-plugin/</code> 的开发依赖），daemon 侧和 <code>req plugin</code> 有单元测试；界面效果需要在真实的 Paseo 中检查。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新增 <code>req plugin install|status|remove</code>，安装脚本最后可选安装插件。</li><li>列表靠轮询刷新（默认 10 秒，可设置）；daemon 侧把短时间内的多个列表请求合并成一次 <code>req api list</code>。</li><li>步骤 agent 的&quot;需求&quot;按钮靠 req-kit 给步骤 agent 打的标签（<code>requirement-pipeline</code>）找到需求；工作区的&quot;需求&quot;按钮按目录匹配需求。</li><li><code>paseo-plugin/package.json</code> 的版本必须与 req-kit 相同（测试检查），<code>paseo-plugin.json</code> 的 Paseo 范围与 <code>reqKit.paseo</code> 相同。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0027-paseo-plugin.md">docs/adr/0027-paseo-plugin.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0027-paseo-plugin.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(r,[["render",d]]);export{q as __pageData,g as default};

package/site-dist/assets/{reference_adr_0027-paseo-plugin.md.BMX33ZNU.lean.js → reference_adr_0027-paseo-plugin.md.CcpaKksi.lean.js}

@@ -1 +1 @@
-import{_ as o,o as a,c as i,a3 as t}from"./chunks/framework.B9qR_F1m.js";const q=JSON.parse('{"title":"0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0027-paseo-plugin.md","filePath":"reference/adr/0027-paseo-plugin.md","lastUpdated":null}'),r={name:"reference/adr/0027-paseo-plugin.md"};function d(s,e,l,n,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t("",2)])])}const g=o(r,[["render",d]]);export{q as __pageData,g as default};
+import{_ as o,o as a,c as i,a2 as t}from"./chunks/framework.BetZR81g.js";const q=JSON.parse('{"title":"0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0027-paseo-plugin.md","filePath":"reference/adr/0027-paseo-plugin.md","lastUpdated":null}'),r={name:"reference/adr/0027-paseo-plugin.md"};function d(s,e,l,n,c,p){return a(),i("div",null,[...e[0]||(e[0]=[t("",2)])])}const g=o(r,[["render",d]]);export{q as __pageData,g as default};

package/site-dist/assets/{reference_adr_0028-external-integrations.md.DtdMe8RK.js → reference_adr_0028-external-integrations.md.CrGqXJux.js}

@@ -1 +1 @@
-import{_ as a,o as t,c as o,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0028-external-integrations.md","filePath":"reference/adr/0028-external-integrations.md","lastUpdated":null}'),i={name:"reference/adr/0028-external-integrations.md"};function n(d,e,l,s,c,h){return t(),o("div",null,[...e[0]||(e[0]=[r('<div><h1 id="_0028-外部系统对接-命令写法在配置里-内容由-ai-整理-调用是确定的" tabindex="-1">0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的 <a class="header-anchor" href="#_0028-外部系统对接-命令写法在配置里-内容由-ai-整理-调用是确定的" aria-label="Permalink to &quot;0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的&quot;">​</a></h1><ul><li>状态：已采纳（与 <a href="./0014-notifier-slot">0014</a> 的通知槽并存：通知只发消息，集成会回写）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>团队希望需求同时出现在自己的需求管理系统中：需求开始时建卡，阶段变化时改卡片状态，卡片编号能在需求、报告和插件里看到。对接的系统各不相同，通常提供本机命令行工具（例如需求管理系统的 CLI），参数会随系统升级变化。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>命令写法写在本机或团队配置里，不写进 req-kit 的代码</strong>：<code>integrations</code> 中每项写明工具、建卡和改状态的参数（带占位符）、从输出取卡片编号和链接的正则、各个流水线事件对应的卡片状态。换系统或系统改参数只改配置。项目配置不能写 <code>integrations</code>（它会运行命令），只能用 <code>integrationDefaults</code> 提供自己的取值，例如项目编号。</li><li><strong>AI 整理内容，不决定怎么调用</strong>：卡片的业务字段（<code>cardFields</code>，如优先级、需求类型、子系统）由 <code>/req</code> 在需求说明确认时从需求说明中整理，和需求方一起确认后写进 <code>card.json</code>。运行时引擎按配置把这些值填进参数并执行，每次行为一致、可以补发、不会重复建卡；不在每次调用时让 AI 读帮助、拼命令，避免结果不确定、在真实系统上做错操作和难以复现。配置本身可以请 AI 读工具的帮助起草，由人确认。</li><li><strong>不经过 shell</strong>：参数数组直接传给进程，标题和 Markdown 描述中的空格、换行、引号都原样传递。Windows 上 npm 安装的工具是 <code>.cmd</code> 包装，只有 cmd.exe 能运行，而 cmd.exe 会破坏这类参数，所以改用 node 直接运行包装里指向的脚本。</li><li><strong>外部系统出错不影响流水线</strong>：失败或超时的调用记在状态文件的 <code>external.&lt;名称&gt;.pending</code>，下一个事件时先按顺序补发；卡片没建好时状态排在后面；等待中的状态只留最新的一个。流水线没在运行时可以 <code>req sync</code>。</li><li><strong>先试再用</strong>：<code>req integration test</code> 打印每个事件会执行的完整命令而不调用。</li><li>录入测试用例暂不做，等对接系统提供能力后，作为新的动作和事件加入（例如功能验证结束时把验收标准和结果录入）。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新的状态文件字段 <code>external</code>（可选，格式版本仍为 1）、功能目录文件 <code>card.json</code>、<code>req api status</code> 的 <code>external</code>。</li><li><code>/req</code> 在确认需求说明前运行&quot;卡片字段&quot;命令；没有配置对接时它输出&quot;跳过&quot;。</li><li>事件：started、approval、blocked、phase_done、verify、completed（可按结论细分）、failed。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0028-external-integrations.md">docs/adr/0028-external-integrations.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0028-external-integrations.md">在 GitHub 上编辑</a></p>',2)])])}const g=a(i,[["render",n]]);export{p as __pageData,g as default};
+import{_ as a,o as t,c as o,a2 as r}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0028-external-integrations.md","filePath":"reference/adr/0028-external-integrations.md","lastUpdated":null}'),i={name:"reference/adr/0028-external-integrations.md"};function n(d,e,l,s,c,h){return t(),o("div",null,[...e[0]||(e[0]=[r('<div><h1 id="_0028-外部系统对接-命令写法在配置里-内容由-ai-整理-调用是确定的" tabindex="-1">0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的 <a class="header-anchor" href="#_0028-外部系统对接-命令写法在配置里-内容由-ai-整理-调用是确定的" aria-label="Permalink to &quot;0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的&quot;">​</a></h1><ul><li>状态：已采纳（与 <a href="./0014-notifier-slot">0014</a> 的通知槽并存：通知只发消息，集成会回写）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>团队希望需求同时出现在自己的需求管理系统中：需求开始时建卡，阶段变化时改卡片状态，卡片编号能在需求、报告和插件里看到。对接的系统各不相同，通常提供本机命令行工具（例如需求管理系统的 CLI），参数会随系统升级变化。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>命令写法写在本机或团队配置里，不写进 req-kit 的代码</strong>：<code>integrations</code> 中每项写明工具、建卡和改状态的参数（带占位符）、从输出取卡片编号和链接的正则、各个流水线事件对应的卡片状态。换系统或系统改参数只改配置。项目配置不能写 <code>integrations</code>（它会运行命令），只能用 <code>integrationDefaults</code> 提供自己的取值，例如项目编号。</li><li><strong>AI 整理内容，不决定怎么调用</strong>：卡片的业务字段（<code>cardFields</code>，如优先级、需求类型、子系统）由 <code>/req</code> 在需求说明确认时从需求说明中整理，和需求方一起确认后写进 <code>card.json</code>。运行时引擎按配置把这些值填进参数并执行，每次行为一致、可以补发、不会重复建卡；不在每次调用时让 AI 读帮助、拼命令，避免结果不确定、在真实系统上做错操作和难以复现。配置本身可以请 AI 读工具的帮助起草，由人确认。</li><li><strong>不经过 shell</strong>：参数数组直接传给进程，标题和 Markdown 描述中的空格、换行、引号都原样传递。Windows 上 npm 安装的工具是 <code>.cmd</code> 包装，只有 cmd.exe 能运行，而 cmd.exe 会破坏这类参数，所以改用 node 直接运行包装里指向的脚本。</li><li><strong>外部系统出错不影响流水线</strong>：失败或超时的调用记在状态文件的 <code>external.&lt;名称&gt;.pending</code>，下一个事件时先按顺序补发；卡片没建好时状态排在后面；等待中的状态只留最新的一个。流水线没在运行时可以 <code>req sync</code>。</li><li><strong>先试再用</strong>：<code>req integration test</code> 打印每个事件会执行的完整命令而不调用。</li><li>录入测试用例暂不做，等对接系统提供能力后，作为新的动作和事件加入（例如功能验证结束时把验收标准和结果录入）。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新的状态文件字段 <code>external</code>（可选，格式版本仍为 1）、功能目录文件 <code>card.json</code>、<code>req api status</code> 的 <code>external</code>。</li><li><code>/req</code> 在确认需求说明前运行&quot;卡片字段&quot;命令；没有配置对接时它输出&quot;跳过&quot;。</li><li>事件：started、approval、blocked、phase_done、verify、completed（可按结论细分）、failed。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0028-external-integrations.md">docs/adr/0028-external-integrations.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0028-external-integrations.md">在 GitHub 上编辑</a></p>',2)])])}const g=a(i,[["render",n]]);export{p as __pageData,g as default};

package/site-dist/assets/{reference_adr_0028-external-integrations.md.DtdMe8RK.lean.js → reference_adr_0028-external-integrations.md.CrGqXJux.lean.js}

@@ -1 +1 @@
-import{_ as a,o as t,c as o,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0028-external-integrations.md","filePath":"reference/adr/0028-external-integrations.md","lastUpdated":null}'),i={name:"reference/adr/0028-external-integrations.md"};function n(d,e,l,s,c,h){return t(),o("div",null,[...e[0]||(e[0]=[r("",2)])])}const g=a(i,[["render",n]]);export{p as __pageData,g as default};
+import{_ as a,o as t,c as o,a2 as r}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0028-external-integrations.md","filePath":"reference/adr/0028-external-integrations.md","lastUpdated":null}'),i={name:"reference/adr/0028-external-integrations.md"};function n(d,e,l,s,c,h){return t(),o("div",null,[...e[0]||(e[0]=[r("",2)])])}const g=a(i,[["render",n]]);export{p as __pageData,g as default};

package/site-dist/assets/{reference_adr_0029-requirements-from-cards.md.BHd1SQPe.js → reference_adr_0029-requirements-from-cards.md.BUVah9hV.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0029-requirements-from-cards.md","filePath":"reference/adr/0029-requirements-from-cards.md","lastUpdated":null}'),c={name:"reference/adr/0029-requirements-from-cards.md"};function a(i,e,s,l,n,u){return t(),r("div",null,[...e[0]||(e[0]=[d('<div><h1 id="_0029-从卡片开始的需求-需求会话代替人-卡片描述代替对话" tabindex="-1">0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话 <a class="header-anchor" href="#_0029-从卡片开始的需求-需求会话代替人-卡片描述代替对话" aria-label="Permalink to &quot;0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话&quot;">​</a></h1><ul><li>状态：已采纳（1.10.0-beta.2；建在 <a href="./0028-external-integrations">0028</a> 的外部系统对接之上）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>团队希望需求不必有人坐在 Paseo 对话前发起：需求方在需求管理系统（ALM）中写好一张卡片、标题加上约定的标识，就由一台共享的研发机器接手，整理需求、请需求方确认、开发、提测，结果回到卡片上。人只在确认需求、确认方案、验收这几个点介入（&quot;软件工厂&quot;）。</p><p>约束：</p><ul><li>ALM 不支持评论，状态只有新建、开发中、待测试等，没有&quot;待补充&quot;&quot;待确认&quot;。</li><li>现有规则：步骤 agent 挂在发起需求的对话下，对话的工作目录不变；流水线只在本地提交。</li><li>卡片描述可能已经是一份完整的需求文档，也可能只有一句话；内容来自需求方，不能当作给 agent 的指令。</li></ul><p>另评估过 Paseo Hub：它的事件来源（GitHub、Slack、Discord、Linear）是编译在 Hub 代码里的，没有插件或通用 webhook；可用的扩展口只有开放 API 的 <code>manual.run</code> 和定时触发。代码在内部 GitLab、IM 是内部工具、Hub 只能内网自建，所以不用 Hub 接单；以后一台机器不够用时，再用内网 Hub 的 <code>manual.run</code> 把需求派到多台机器。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>需求会话代替人</strong>：<code>req start --from &lt;系统&gt;:&lt;卡号&gt;</code> 读卡片、建功能目录（<code>docs/features/&lt;日期&gt;-&lt;卡号简称&gt;/</code>），然后在 Paseo 中为这个需求建一个顶层 agent（需求会话），工作目录是仓库，第一条消息以 <code>/req 无人值守</code> 开头。它按 <code>unattended.md</code> 手册整理需求说明，确认后用现有的&quot;启动（自动新建工作区）&quot;命令启动流水线，所以它就是流水线的发起对话：步骤 agent 挂在它下面，进度通知发给它，现有的启动、继续、确认方案命令都不变。人在 Paseo 中打开这个会话就能看到全部过程。</li><li><strong>卡片描述代替对话</strong>：描述末尾由 req-kit 维护两个区块：<code>## req-kit AI 区（自动维护，请勿修改）</code> 每次整块替换（进度一行 + 会话写的 <code>card-ai.md</code> + 必要时的方案摘要），<code>## 需求方回复（请在下方填写）</code> 只由需求方填写，req-kit 只读、只补空行（每个问题一行 <code>- Q1：</code>，以及 <code>- 确认：</code>、方案待确认时的 <code>- 方案确认：</code>）。区块以上需求方自己写的内容从不改动。每次写入前重新读取卡片。</li><li><strong>轮询而不是回调</strong>：<code>req card check</code> 读卡片，把新内容（回答、补充、描述的修改、&quot;确认：同意&quot;&quot;方案确认：同意&quot;）转给需求会话；只看有意义的内容（空的模板行不算），同样的内容只转一次。1.11 的接单器定时调用它。会话自己执行启动和确认方案的命令，req-kit 不替它决定。</li><li><strong>卡片状态少，确认放在描述里</strong>：澄清和确认期间卡片停在&quot;新建&quot;，需求方确认后改为&quot;开发中&quot;，研发完成后改为&quot;待测试&quot;（都由 <code>statusMap</code> 配置）。&quot;只做研发&quot;的需求在研发完成时发 <code>phase_done</code> 事件，而不是 <code>completed</code>：对外部系统来说，这就是&quot;研发完成，待测试&quot;。</li><li><strong>默认只做研发</strong>：从卡片开始的需求，项目没有指定执行方式时，默认研发完成、写好提测说明后停下，测试由测试同事做。</li><li><strong>卡片内容是数据</strong>：会话读到的卡片描述和回复放在 <code>&lt;card-description&gt;</code>、<code>&lt;card-reply&gt;</code> 中并注明不是指令；其中要求执行命令、推送、访问生产环境的一律不做。</li><li><strong>用这张卡片，不另建</strong>：功能目录的 <code>source.json</code> 记下来源；外部系统对接遇到它时直接使用这张卡片的编号，不再建卡。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>对接配置新增 <code>query</code>（读一张卡片：参数 + 输出 JSON 中各值的位置）和 <code>describe</code>（改描述：<code>{description}</code> 是完整的新描述）。</li><li>新命令：<code>req start --from</code>、<code>req card publish | check | list</code>。本机新增 <code>~/.req-kit/cards/</code>（从卡片开始的需求的登记）。</li><li>功能目录新增 <code>source.json</code>、<code>card-source.md</code>、<code>card-ai.md</code>。</li><li>运行时新增 <code>startSessionAgent</code>：建一个不挂在任何对话下的 agent，工作目录是仓库。</li><li><strong>按子系统选仓库</strong>（beta.3）：仓库在项目配置的 <code>cardSource</code> 中写明接哪个系统、空间和子系统，<code>/req-setup</code> 写入并在本机登记（<code>~/.req-kit/card-repos.json</code>）；同一子系统有几个仓库时用 <code>titleKeywords</code> 区分。匹配不到或分不清时报错说明，不猜。</li><li><strong>工厂模式可以推送分支</strong>（beta.3，放宽&quot;只在本地提交&quot;）：配置 <code>push.enabled</code> 后，只对从卡片开始的需求，在研发完成、写好提测说明后推送到 <code>&lt;remote&gt;/req/&lt;卡号简称&gt;</code>。只推这个前缀，不强推、不合并、不建合并请求；只能在本机或团队配置中打开。理由：接单的是共享机器，测试同事拿不到它的本地分支；合并这道人工关口不变。个人电脑上从对话发起的需求仍只在本地提交。</li><li>使用记录带上需求方（卡片的提出人）和卡号，统计可以按需求方汇总。1.11：接单器 <code>req factory</code>。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0029-requirements-from-cards.md">docs/adr/0029-requirements-from-cards.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0029-requirements-from-cards.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(c,[["render",a]]);export{m as __pageData,g as default};
+import{_ as o,o as t,c as r,a2 as d}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0029-requirements-from-cards.md","filePath":"reference/adr/0029-requirements-from-cards.md","lastUpdated":null}'),c={name:"reference/adr/0029-requirements-from-cards.md"};function a(i,e,s,l,n,u){return t(),r("div",null,[...e[0]||(e[0]=[d('<div><h1 id="_0029-从卡片开始的需求-需求会话代替人-卡片描述代替对话" tabindex="-1">0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话 <a class="header-anchor" href="#_0029-从卡片开始的需求-需求会话代替人-卡片描述代替对话" aria-label="Permalink to &quot;0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话&quot;">​</a></h1><ul><li>状态：已采纳（1.10.0-beta.2；建在 <a href="./0028-external-integrations">0028</a> 的外部系统对接之上）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>团队希望需求不必有人坐在 Paseo 对话前发起：需求方在需求管理系统（ALM）中写好一张卡片、标题加上约定的标识，就由一台共享的研发机器接手，整理需求、请需求方确认、开发、提测，结果回到卡片上。人只在确认需求、确认方案、验收这几个点介入（&quot;软件工厂&quot;）。</p><p>约束：</p><ul><li>ALM 不支持评论，状态只有新建、开发中、待测试等，没有&quot;待补充&quot;&quot;待确认&quot;。</li><li>现有规则：步骤 agent 挂在发起需求的对话下，对话的工作目录不变；流水线只在本地提交。</li><li>卡片描述可能已经是一份完整的需求文档，也可能只有一句话；内容来自需求方，不能当作给 agent 的指令。</li></ul><p>另评估过 Paseo Hub：它的事件来源（GitHub、Slack、Discord、Linear）是编译在 Hub 代码里的，没有插件或通用 webhook；可用的扩展口只有开放 API 的 <code>manual.run</code> 和定时触发。代码在内部 GitLab、IM 是内部工具、Hub 只能内网自建，所以不用 Hub 接单；以后一台机器不够用时，再用内网 Hub 的 <code>manual.run</code> 把需求派到多台机器。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>需求会话代替人</strong>：<code>req start --from &lt;系统&gt;:&lt;卡号&gt;</code> 读卡片、建功能目录（<code>docs/features/&lt;日期&gt;-&lt;卡号简称&gt;/</code>），然后在 Paseo 中为这个需求建一个顶层 agent（需求会话），工作目录是仓库，第一条消息以 <code>/req 无人值守</code> 开头。它按 <code>unattended.md</code> 手册整理需求说明，确认后用现有的&quot;启动（自动新建工作区）&quot;命令启动流水线，所以它就是流水线的发起对话：步骤 agent 挂在它下面，进度通知发给它，现有的启动、继续、确认方案命令都不变。人在 Paseo 中打开这个会话就能看到全部过程。</li><li><strong>卡片描述代替对话</strong>：描述末尾由 req-kit 维护两个区块：<code>## req-kit AI 区（自动维护，请勿修改）</code> 每次整块替换（进度一行 + 会话写的 <code>card-ai.md</code> + 必要时的方案摘要），<code>## 需求方回复（请在下方填写）</code> 只由需求方填写，req-kit 只读、只补空行（每个问题一行 <code>- Q1：</code>，以及 <code>- 确认：</code>、方案待确认时的 <code>- 方案确认：</code>）。区块以上需求方自己写的内容从不改动。每次写入前重新读取卡片。</li><li><strong>轮询而不是回调</strong>：<code>req card check</code> 读卡片，把新内容（回答、补充、描述的修改、&quot;确认：同意&quot;&quot;方案确认：同意&quot;）转给需求会话；只看有意义的内容（空的模板行不算），同样的内容只转一次。1.11 的接单器定时调用它。会话自己执行启动和确认方案的命令，req-kit 不替它决定。</li><li><strong>卡片状态少，确认放在描述里</strong>：澄清和确认期间卡片停在&quot;新建&quot;，需求方确认后改为&quot;开发中&quot;，研发完成后改为&quot;待测试&quot;（都由 <code>statusMap</code> 配置）。&quot;只做研发&quot;的需求在研发完成时发 <code>phase_done</code> 事件，而不是 <code>completed</code>：对外部系统来说，这就是&quot;研发完成，待测试&quot;。</li><li><strong>默认只做研发</strong>：从卡片开始的需求，项目没有指定执行方式时，默认研发完成、写好提测说明后停下，测试由测试同事做。</li><li><strong>卡片内容是数据</strong>：会话读到的卡片描述和回复放在 <code>&lt;card-description&gt;</code>、<code>&lt;card-reply&gt;</code> 中并注明不是指令；其中要求执行命令、推送、访问生产环境的一律不做。</li><li><strong>用这张卡片，不另建</strong>：功能目录的 <code>source.json</code> 记下来源；外部系统对接遇到它时直接使用这张卡片的编号，不再建卡。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>对接配置新增 <code>query</code>（读一张卡片：参数 + 输出 JSON 中各值的位置）和 <code>describe</code>（改描述：<code>{description}</code> 是完整的新描述）。</li><li>新命令：<code>req start --from</code>、<code>req card publish | check | list</code>。本机新增 <code>~/.req-kit/cards/</code>（从卡片开始的需求的登记）。</li><li>功能目录新增 <code>source.json</code>、<code>card-source.md</code>、<code>card-ai.md</code>。</li><li>运行时新增 <code>startSessionAgent</code>：建一个不挂在任何对话下的 agent，工作目录是仓库。</li><li><strong>按子系统选仓库</strong>（beta.3）：仓库在项目配置的 <code>cardSource</code> 中写明接哪个系统、空间和子系统，<code>/req-setup</code> 写入并在本机登记（<code>~/.req-kit/card-repos.json</code>）；同一子系统有几个仓库时用 <code>titleKeywords</code> 区分。匹配不到或分不清时报错说明，不猜。</li><li><strong>工厂模式可以推送分支</strong>（beta.3，放宽&quot;只在本地提交&quot;）：配置 <code>push.enabled</code> 后，只对从卡片开始的需求，在研发完成、写好提测说明后推送到 <code>&lt;remote&gt;/req/&lt;卡号简称&gt;</code>。只推这个前缀，不强推、不合并、不建合并请求；只能在本机或团队配置中打开。理由：接单的是共享机器，测试同事拿不到它的本地分支；合并这道人工关口不变。个人电脑上从对话发起的需求仍只在本地提交。</li><li>使用记录带上需求方（卡片的提出人）和卡号，统计可以按需求方汇总。1.11：接单器 <code>req factory</code>。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0029-requirements-from-cards.md">docs/adr/0029-requirements-from-cards.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0029-requirements-from-cards.md">在 GitHub 上编辑</a></p>',2)])])}const g=o(c,[["render",a]]);export{m as __pageData,g as default};

package/site-dist/assets/{reference_adr_0029-requirements-from-cards.md.BHd1SQPe.lean.js → reference_adr_0029-requirements-from-cards.md.BUVah9hV.lean.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as r,a3 as d}from"./chunks/framework.B9qR_F1m.js";const m=JSON.parse('{"title":"0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0029-requirements-from-cards.md","filePath":"reference/adr/0029-requirements-from-cards.md","lastUpdated":null}'),c={name:"reference/adr/0029-requirements-from-cards.md"};function a(i,e,s,l,n,u){return t(),r("div",null,[...e[0]||(e[0]=[d("",2)])])}const g=o(c,[["render",a]]);export{m as __pageData,g as default};
+import{_ as o,o as t,c as r,a2 as d}from"./chunks/framework.BetZR81g.js";const m=JSON.parse('{"title":"0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0029-requirements-from-cards.md","filePath":"reference/adr/0029-requirements-from-cards.md","lastUpdated":null}'),c={name:"reference/adr/0029-requirements-from-cards.md"};function a(i,e,s,l,n,u){return t(),r("div",null,[...e[0]||(e[0]=[d("",2)])])}const g=o(c,[["render",a]]);export{m as __pageData,g as default};

package/site-dist/assets/{reference_adr_0030-card-intake-process.md.kLc-DG9_.js → reference_adr_0030-card-intake-process.md.DKMkIFXw.js}

@@ -1 +1 @@
-import{_ as o,o as a,c,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0030 接单器：共享机器上定时接卡片、转达回复","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0030-card-intake-process.md","filePath":"reference/adr/0030-card-intake-process.md","lastUpdated":null}'),t={name:"reference/adr/0030-card-intake-process.md"};function d(s,e,i,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[r('<div><h1 id="_0030-接单器-共享机器上定时接卡片、转达回复" tabindex="-1">0030 接单器：共享机器上定时接卡片、转达回复 <a class="header-anchor" href="#_0030-接单器-共享机器上定时接卡片、转达回复" aria-label="Permalink to &quot;0030 接单器：共享机器上定时接卡片、转达回复&quot;">​</a></h1><ul><li>状态：已采纳（1.11.0-beta.1；建在 <a href="./0029-requirements-from-cards">0029</a> 之上）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>1.10 已经可以从一张卡片开始需求（<code>req start --from</code>）、把需求方在卡片中的回复转给需求会话（<code>req card check</code>），但这两步都要有人运行。&quot;软件工厂&quot;要求需求方只在卡片上操作：写好卡片、标题加上约定的标识，就有一台共享研发机器接手。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>一个常驻进程，两件事</strong>：<code>req factory run</code> 每隔 <code>factory.pollMinutes</code>（默认 5 分钟）检查一次：先用对接配置的 <code>list</code> 命令列出各空间（本机登记仓库的 <code>cardSource.projectId</code>）中的卡片，标题以 <code>factory.titleTags</code>（默认 <code>[AI]</code>、<code>【AI】</code>）开头、本机还没开始过的，按 1.10 的 <code>req start --from</code> 开始（按子系统选仓库、建需求会话）；再按 <code>req card check --all</code> 转达回复，跳过流水线已完成的需求。同一台机器上一次只做一次检查（<code>~/.req-kit/factory/poll.lock</code>）。</li><li><strong>轮询外部系统，不用回调</strong>：需求管理系统没有我们能用的事件推送；轮询的间隔是几分钟，对需求开发足够，失败了下次再来。卡片状态、条件（例如只查&quot;新建&quot;的用户故事）写在 <code>list</code> 的参数里，由团队配置决定。</li><li><strong>克制地接单</strong>：每次最多开始 <code>factory.maxNewPerPoll</code>（默认 3）个需求，其余下次再接；流水线本身仍受 <code>maxConcurrentPipelines</code> 限制。接不了的卡片（例如子系统没有对应的仓库）记下原因，卡片的标题和子系统不变就一天内不再试，<code>req factory status</code> 中可以看到。</li><li><strong>只读卡片、不改卡片状态来&quot;占位&quot;</strong>：本机的登记（<code>~/.req-kit/cards/</code>）就是去重的依据。卡片状态仍只由流水线事件改（开发中、待测试）。将来多台机器同时接单时再引入占位（例如改状态或经内网 Hub 派工），见 <a href="./0029-requirements-from-cards">0029</a>。</li><li><strong>运行方式交给系统</strong>：<code>req factory start</code> / <code>stop</code> 在后台运行，适合先试；长期运行用系统服务（<code>req factory service</code> 给出 systemd 用户服务或 Windows 计划任务的写法），机器重启后自动恢复。接单器通过 Paseo daemon 创建需求会话，daemon 需要同时运行。</li><li><strong>配置只在本机或团队配置中</strong>：<code>factory</code> 和 <code>integrations</code> 一样会让机器做事，写在项目配置中会被忽略。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>对接配置新增 <code>list</code>（参数可用 <code>{projectId}</code>、<code>{page}</code>、<code>{pageSize}</code>、<code>{titleTag}</code>；<code>fields</code> 写每张卡片中 id、title 等的位置；<code>items</code> 写输出中列表的位置，不写时依次找 data.list、data.records、data.items、data.rows、data）。</li><li>新增配置 <code>factory</code>（<code>pollMinutes</code>、<code>titleTags</code>、<code>maxNewPerPoll</code>）、命令 <code>req factory once | run | start | stop | status | service</code>、本机目录 <code>~/.req-kit/factory/</code>（日志、状态、没能接的卡片）。</li><li><code>req start --from</code> 中途失败（例如 Paseo 没在运行，会话没建成）时，再次运行会补建会话，而不是当作已经开始过。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0030-card-intake-process.md">docs/adr/0030-card-intake-process.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0030-card-intake-process.md">在 GitHub 上编辑</a></p>',2)])])}const m=o(t,[["render",d]]);export{p as __pageData,m as default};
+import{_ as o,o as a,c,a2 as r}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0030 接单器：共享机器上定时接卡片、转达回复","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0030-card-intake-process.md","filePath":"reference/adr/0030-card-intake-process.md","lastUpdated":null}'),t={name:"reference/adr/0030-card-intake-process.md"};function d(s,e,i,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[r('<div><h1 id="_0030-接单器-共享机器上定时接卡片、转达回复" tabindex="-1">0030 接单器：共享机器上定时接卡片、转达回复 <a class="header-anchor" href="#_0030-接单器-共享机器上定时接卡片、转达回复" aria-label="Permalink to &quot;0030 接单器：共享机器上定时接卡片、转达回复&quot;">​</a></h1><ul><li>状态：已采纳（1.11.0-beta.1；建在 <a href="./0029-requirements-from-cards">0029</a> 之上）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>1.10 已经可以从一张卡片开始需求（<code>req start --from</code>）、把需求方在卡片中的回复转给需求会话（<code>req card check</code>），但这两步都要有人运行。&quot;软件工厂&quot;要求需求方只在卡片上操作：写好卡片、标题加上约定的标识，就有一台共享研发机器接手。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>一个常驻进程，两件事</strong>：<code>req factory run</code> 每隔 <code>factory.pollMinutes</code>（默认 5 分钟）检查一次：先用对接配置的 <code>list</code> 命令列出各空间（本机登记仓库的 <code>cardSource.projectId</code>）中的卡片，标题以 <code>factory.titleTags</code>（默认 <code>[AI]</code>、<code>【AI】</code>）开头、本机还没开始过的，按 1.10 的 <code>req start --from</code> 开始（按子系统选仓库、建需求会话）；再按 <code>req card check --all</code> 转达回复，跳过流水线已完成的需求。同一台机器上一次只做一次检查（<code>~/.req-kit/factory/poll.lock</code>）。</li><li><strong>轮询外部系统，不用回调</strong>：需求管理系统没有我们能用的事件推送；轮询的间隔是几分钟，对需求开发足够，失败了下次再来。卡片状态、条件（例如只查&quot;新建&quot;的用户故事）写在 <code>list</code> 的参数里，由团队配置决定。</li><li><strong>克制地接单</strong>：每次最多开始 <code>factory.maxNewPerPoll</code>（默认 3）个需求，其余下次再接；流水线本身仍受 <code>maxConcurrentPipelines</code> 限制。接不了的卡片（例如子系统没有对应的仓库）记下原因，卡片的标题和子系统不变就一天内不再试，<code>req factory status</code> 中可以看到。</li><li><strong>只读卡片、不改卡片状态来&quot;占位&quot;</strong>：本机的登记（<code>~/.req-kit/cards/</code>）就是去重的依据。卡片状态仍只由流水线事件改（开发中、待测试）。将来多台机器同时接单时再引入占位（例如改状态或经内网 Hub 派工），见 <a href="./0029-requirements-from-cards">0029</a>。</li><li><strong>运行方式交给系统</strong>：<code>req factory start</code> / <code>stop</code> 在后台运行，适合先试；长期运行用系统服务（<code>req factory service</code> 给出 systemd 用户服务或 Windows 计划任务的写法），机器重启后自动恢复。接单器通过 Paseo daemon 创建需求会话，daemon 需要同时运行。</li><li><strong>配置只在本机或团队配置中</strong>：<code>factory</code> 和 <code>integrations</code> 一样会让机器做事，写在项目配置中会被忽略。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>对接配置新增 <code>list</code>（参数可用 <code>{projectId}</code>、<code>{page}</code>、<code>{pageSize}</code>、<code>{titleTag}</code>；<code>fields</code> 写每张卡片中 id、title 等的位置；<code>items</code> 写输出中列表的位置，不写时依次找 data.list、data.records、data.items、data.rows、data）。</li><li>新增配置 <code>factory</code>（<code>pollMinutes</code>、<code>titleTags</code>、<code>maxNewPerPoll</code>）、命令 <code>req factory once | run | start | stop | status | service</code>、本机目录 <code>~/.req-kit/factory/</code>（日志、状态、没能接的卡片）。</li><li><code>req start --from</code> 中途失败（例如 Paseo 没在运行，会话没建成）时，再次运行会补建会话，而不是当作已经开始过。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0030-card-intake-process.md">docs/adr/0030-card-intake-process.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0030-card-intake-process.md">在 GitHub 上编辑</a></p>',2)])])}const m=o(t,[["render",d]]);export{p as __pageData,m as default};

package/site-dist/assets/{reference_adr_0030-card-intake-process.md.kLc-DG9_.lean.js → reference_adr_0030-card-intake-process.md.DKMkIFXw.lean.js}

@@ -1 +1 @@
-import{_ as o,o as a,c,a3 as r}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"0030 接单器：共享机器上定时接卡片、转达回复","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0030-card-intake-process.md","filePath":"reference/adr/0030-card-intake-process.md","lastUpdated":null}'),t={name:"reference/adr/0030-card-intake-process.md"};function d(s,e,i,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[r("",2)])])}const m=o(t,[["render",d]]);export{p as __pageData,m as default};
+import{_ as o,o as a,c,a2 as r}from"./chunks/framework.BetZR81g.js";const p=JSON.parse('{"title":"0030 接单器：共享机器上定时接卡片、转达回复","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0030-card-intake-process.md","filePath":"reference/adr/0030-card-intake-process.md","lastUpdated":null}'),t={name:"reference/adr/0030-card-intake-process.md"};function d(s,e,i,l,n,u){return a(),c("div",null,[...e[0]||(e[0]=[r("",2)])])}const m=o(t,[["render",d]]);export{p as __pageData,m as default};

package/site-dist/assets/{reference_adr_0031-fewer-interventions.md.BDnQcz8g.js → reference_adr_0031-fewer-interventions.md.C8e2jpbC.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as r,a3 as i}from"./chunks/framework.B9qR_F1m.js";const q=JSON.parse('{"title":"0031 少等人：每种中断都有自动的下一步","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0031-fewer-interventions.md","filePath":"reference/adr/0031-fewer-interventions.md","lastUpdated":null}'),a={name:"reference/adr/0031-fewer-interventions.md"};function n(s,e,l,d,c,u){return t(),r("div",null,[...e[0]||(e[0]=[i('<div><h1 id="_0031-少等人-每种中断都有自动的下一步" tabindex="-1">0031 少等人：每种中断都有自动的下一步 <a class="header-anchor" href="#_0031-少等人-每种中断都有自动的下一步" aria-label="Permalink to &quot;0031 少等人：每种中断都有自动的下一步&quot;">​</a></h1><ul><li>状态：已采纳（1.12.0-beta.1）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>目标是需求方只在三处介入：确认需求、确认方案（只有界面改动时）、验收合并。核对代码、默认配置和 <code>/req</code> 手册后，现在要人的地方共 16 处，其中只有这 3 处是必要的决定；其余多数来自两类：</p><ul><li><strong>中断等人继续</strong>：步骤超时、agent 报错、结果文件无效直接中断；限流重试用完只按固定间隔自动继续两次；后台进程意外退出的定时检查默认关闭。</li><li><strong>可以有默认值的选择题</strong>：是否新建工作区、档位、执行方式、现在开始还是预约；装好后要运行配置向导选模型；方案审核提出的问题不加筛选地交给需求方。</li></ul><p>另外，过去没有记录每次停下等人的原因，无法用数据判断先改哪里。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>先记录</strong>：状态文件和使用记录加上 <code>stopKind</code>（停下等人的原因代码）和 <code>recoveries</code>（自己处理掉的问题），<code>req stats</code> 新增&quot;人工介入&quot;一节。用两周的真实数据复核后续的优先级。</li><li><strong>自愈</strong>（<code>selfHeal</code>，默认开）： <ul><li>超时：agent 还在做就再等同样长的时间，不打断它；仍未完成才中断（1.11 已保证继续时不会另起一个 agent）。</li><li>agent 报错、结果文件无效：新开一个 agent 重做一次。只重做一次，避免一个确实做不了的步骤反复消耗额度。</li></ul></li><li><strong>备用模型</strong>（<code>agents.fallback</code>，可选）：报错重做、限流重试用完时换它做一次。只用一次、只在这一步，下一步仍用主模型。</li><li><strong>按额度恢复时间预约</strong>：限流中断时，读 Paseo 报告的额度恢复时间，预约在恢复后 5 分钟自动继续；读不到时仍按 <code>autoResumeMinutes</code>。</li><li><strong>后台进程退出后续跑</strong>：个人机器的定时检查默认打开（60 分钟）；接单器每次检查时发现&quot;运行中但进程已不在&quot;的流水线，请它的对话检查并继续，每个进程只提醒一次。</li><li><strong>方案审核的问题先自答</strong>（<code>answerQuestionsFirst</code>，默认开）：审核结论为&quot;需要需求方决定&quot;时，先让 builder 在方案修订中从代码、文档和需求说明里找答案；只把真正的业务取舍连同推荐答案交给需求方，都能回答时不停下。</li><li><strong>装好就能用</strong>：安装时 <code>req configure --auto</code> 不提问，按推荐选好已登录的 agent（两个不同厂商分别做 builder、reviewer，再选一个做备用，都用免确认模式）。插件新增&quot;模型&quot;设置页，列出 Paseo 中已登录的 agent，选择后写回本机配置，与 <code>req configure</code> 用同一套逻辑。</li><li><strong>默认值代替选择题</strong>：<code>/req</code> 不再问是否新建工作区、档位、执行方式、现在开始还是预约，按推荐值直接走，在确认摘要的最后一行写明，想改再说；确认需求说明就是同意开始。</li><li><strong>卡片回复更宽松</strong>：回复区写&quot;好的&quot;&quot;没问题&quot;&quot;按你说的来&quot;也算同意；只写了这样一句、没有别的内容时，按正在等待的确认（需求说明或方案）处理。卡片已经写清需求时，需求会话不为提问而提问。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新配置：<code>selfHeal</code>、<code>answerQuestionsFirst</code>、<code>agents.fallback</code>；<code>watchdogMinutes</code> 默认从 0 改为 60。想保持以前行为的，把它们设为 <code>false</code> / <code>0</code>。</li><li>方案修订的结果文件可以带 <code>business_questions</code>。</li><li>新命令：<code>req configure --auto</code>、<code>req api models</code>、<code>req api set-agents</code>。</li><li>自动处理会多用一些额度（多等一轮、重做一次）；每次都写进进度日志和使用记录，可以查到。</li></ul><h2 id="补充-1-12-0-beta-3-接单机器的运维和插件中的处理" tabindex="-1">补充（1.12.0-beta.3）：接单机器的运维和插件中的处理 <a class="header-anchor" href="#补充-1-12-0-beta-3-接单机器的运维和插件中的处理" aria-label="Permalink to &quot;补充（1.12.0-beta.3）：接单机器的运维和插件中的处理&quot;">​</a></h2><ul><li><strong>接单器自检</strong>：每次检查前确认 Paseo、agent 登录、额度和需求管理系统的命令。不正常就整次跳过（不接新单、不转达），因为这时接下来的需求也跑不起来；告警走外部通知的新事件 <code>alert</code>，按&quot;问题的内容&quot;去重，只在出现、变化和恢复时各发一次，避免刷屏。</li><li><strong>草稿合并请求</strong>：和对接配置一样，命令写在配置里、参数用占位符，req-kit 不内置 GitLab 接口、不保存令牌；只建草稿、每个仓库只建一次，合并仍由人做。</li><li><strong>自动确认</strong>：只对快速档、没有待答问题的卡片，默认关闭；需求方写了任何内容就不自动确认，每次摘要更新重新计时。确认仍然发生在需求会话里，req-kit 只是在到时转达&quot;按自动确认处理&quot;。</li><li><strong>按人通知</strong>：事件带上 <code>people</code>（发给需求方还是群、需求方的账号），账号来自本机或团队配置的 <code>people</code>，内部 IM 的适配器拿到接口后只需要读它。</li><li><strong>插件&quot;等你处理&quot;和配置页</strong>：回答和方案意见用 <code>req reply</code> 转给需求的对话，由对话按原来的做法更新需求说明并继续，插件不直接改需求文件或状态；配置页只读，展示 <code>req api config</code> 的结果，密钥和个人账号不显示。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0031-fewer-interventions.md">docs/adr/0031-fewer-interventions.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0031-fewer-interventions.md">在 GitHub 上编辑</a></p>',2)])])}const f=o(a,[["render",n]]);export{q as __pageData,f as default};
+import{_ as o,o as t,c as r,a2 as i}from"./chunks/framework.BetZR81g.js";const q=JSON.parse('{"title":"0031 少等人：每种中断都有自动的下一步","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0031-fewer-interventions.md","filePath":"reference/adr/0031-fewer-interventions.md","lastUpdated":null}'),a={name:"reference/adr/0031-fewer-interventions.md"};function n(s,e,l,d,c,u){return t(),r("div",null,[...e[0]||(e[0]=[i('<div><h1 id="_0031-少等人-每种中断都有自动的下一步" tabindex="-1">0031 少等人：每种中断都有自动的下一步 <a class="header-anchor" href="#_0031-少等人-每种中断都有自动的下一步" aria-label="Permalink to &quot;0031 少等人：每种中断都有自动的下一步&quot;">​</a></h1><ul><li>状态：已采纳（1.12.0-beta.1）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>目标是需求方只在三处介入：确认需求、确认方案（只有界面改动时）、验收合并。核对代码、默认配置和 <code>/req</code> 手册后，现在要人的地方共 16 处，其中只有这 3 处是必要的决定；其余多数来自两类：</p><ul><li><strong>中断等人继续</strong>：步骤超时、agent 报错、结果文件无效直接中断；限流重试用完只按固定间隔自动继续两次；后台进程意外退出的定时检查默认关闭。</li><li><strong>可以有默认值的选择题</strong>：是否新建工作区、档位、执行方式、现在开始还是预约；装好后要运行配置向导选模型；方案审核提出的问题不加筛选地交给需求方。</li></ul><p>另外，过去没有记录每次停下等人的原因，无法用数据判断先改哪里。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>先记录</strong>：状态文件和使用记录加上 <code>stopKind</code>（停下等人的原因代码）和 <code>recoveries</code>（自己处理掉的问题），<code>req stats</code> 新增&quot;人工介入&quot;一节。用两周的真实数据复核后续的优先级。</li><li><strong>自愈</strong>（<code>selfHeal</code>，默认开）： <ul><li>超时：agent 还在做就再等同样长的时间，不打断它；仍未完成才中断（1.11 已保证继续时不会另起一个 agent）。</li><li>agent 报错、结果文件无效：新开一个 agent 重做一次。只重做一次，避免一个确实做不了的步骤反复消耗额度。</li></ul></li><li><strong>备用模型</strong>（<code>agents.fallback</code>，可选）：报错重做、限流重试用完时换它做一次。只用一次、只在这一步，下一步仍用主模型。</li><li><strong>按额度恢复时间预约</strong>：限流中断时，读 Paseo 报告的额度恢复时间，预约在恢复后 5 分钟自动继续；读不到时仍按 <code>autoResumeMinutes</code>。</li><li><strong>后台进程退出后续跑</strong>：个人机器的定时检查默认打开（60 分钟）；接单器每次检查时发现&quot;运行中但进程已不在&quot;的流水线，请它的对话检查并继续，每个进程只提醒一次。</li><li><strong>方案审核的问题先自答</strong>（<code>answerQuestionsFirst</code>，默认开）：审核结论为&quot;需要需求方决定&quot;时，先让 builder 在方案修订中从代码、文档和需求说明里找答案；只把真正的业务取舍连同推荐答案交给需求方，都能回答时不停下。</li><li><strong>装好就能用</strong>：安装时 <code>req configure --auto</code> 不提问，按推荐选好已登录的 agent（两个不同厂商分别做 builder、reviewer，再选一个做备用，都用免确认模式）。插件新增&quot;模型&quot;设置页，列出 Paseo 中已登录的 agent，选择后写回本机配置，与 <code>req configure</code> 用同一套逻辑。</li><li><strong>默认值代替选择题</strong>：<code>/req</code> 不再问是否新建工作区、档位、执行方式、现在开始还是预约，按推荐值直接走，在确认摘要的最后一行写明，想改再说；确认需求说明就是同意开始。</li><li><strong>卡片回复更宽松</strong>：回复区写&quot;好的&quot;&quot;没问题&quot;&quot;按你说的来&quot;也算同意；只写了这样一句、没有别的内容时，按正在等待的确认（需求说明或方案）处理。卡片已经写清需求时，需求会话不为提问而提问。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>新配置：<code>selfHeal</code>、<code>answerQuestionsFirst</code>、<code>agents.fallback</code>；<code>watchdogMinutes</code> 默认从 0 改为 60。想保持以前行为的，把它们设为 <code>false</code> / <code>0</code>。</li><li>方案修订的结果文件可以带 <code>business_questions</code>。</li><li>新命令：<code>req configure --auto</code>、<code>req api models</code>、<code>req api set-agents</code>。</li><li>自动处理会多用一些额度（多等一轮、重做一次）；每次都写进进度日志和使用记录，可以查到。</li></ul><h2 id="补充-1-12-0-beta-3-接单机器的运维和插件中的处理" tabindex="-1">补充（1.12.0-beta.3）：接单机器的运维和插件中的处理 <a class="header-anchor" href="#补充-1-12-0-beta-3-接单机器的运维和插件中的处理" aria-label="Permalink to &quot;补充（1.12.0-beta.3）：接单机器的运维和插件中的处理&quot;">​</a></h2><ul><li><strong>接单器自检</strong>：每次检查前确认 Paseo、agent 登录、额度和需求管理系统的命令。不正常就整次跳过（不接新单、不转达），因为这时接下来的需求也跑不起来；告警走外部通知的新事件 <code>alert</code>，按&quot;问题的内容&quot;去重，只在出现、变化和恢复时各发一次，避免刷屏。</li><li><strong>草稿合并请求</strong>：和对接配置一样，命令写在配置里、参数用占位符，req-kit 不内置 GitLab 接口、不保存令牌；只建草稿、每个仓库只建一次，合并仍由人做。</li><li><strong>自动确认</strong>：只对快速档、没有待答问题的卡片，默认关闭；需求方写了任何内容就不自动确认，每次摘要更新重新计时。确认仍然发生在需求会话里，req-kit 只是在到时转达&quot;按自动确认处理&quot;。</li><li><strong>按人通知</strong>：事件带上 <code>people</code>（发给需求方还是群、需求方的账号），账号来自本机或团队配置的 <code>people</code>，内部 IM 的适配器拿到接口后只需要读它。</li><li><strong>插件&quot;等你处理&quot;和配置页</strong>：回答和方案意见用 <code>req reply</code> 转给需求的对话，由对话按原来的做法更新需求说明并继续，插件不直接改需求文件或状态；配置页只读，展示 <code>req api config</code> 的结果，密钥和个人账号不显示。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0031-fewer-interventions.md">docs/adr/0031-fewer-interventions.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0031-fewer-interventions.md">在 GitHub 上编辑</a></p>',2)])])}const f=o(a,[["render",n]]);export{q as __pageData,f as default};

package/site-dist/assets/{reference_adr_0031-fewer-interventions.md.BDnQcz8g.lean.js → reference_adr_0031-fewer-interventions.md.C8e2jpbC.lean.js}

@@ -1 +1 @@
-import{_ as o,o as t,c as r,a3 as i}from"./chunks/framework.B9qR_F1m.js";const q=JSON.parse('{"title":"0031 少等人：每种中断都有自动的下一步","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0031-fewer-interventions.md","filePath":"reference/adr/0031-fewer-interventions.md","lastUpdated":null}'),a={name:"reference/adr/0031-fewer-interventions.md"};function n(s,e,l,d,c,u){return t(),r("div",null,[...e[0]||(e[0]=[i("",2)])])}const f=o(a,[["render",n]]);export{q as __pageData,f as default};
+import{_ as o,o as t,c as r,a2 as i}from"./chunks/framework.BetZR81g.js";const q=JSON.parse('{"title":"0031 少等人：每种中断都有自动的下一步","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0031-fewer-interventions.md","filePath":"reference/adr/0031-fewer-interventions.md","lastUpdated":null}'),a={name:"reference/adr/0031-fewer-interventions.md"};function n(s,e,l,d,c,u){return t(),r("div",null,[...e[0]||(e[0]=[i("",2)])])}const f=o(a,[["render",n]]);export{q as __pageData,f as default};

package/site-dist/assets/{reference_adr_0032-npm-only-install.md.C-3L1FkX.js → reference_adr_0032-npm-only-install.md.5tFsGLKz.js}

@@ -1 +1 @@
-import{_ as t,o as a,c as l,a3 as o}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"0032 安装、升级和文档只依赖 npm 源","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0032-npm-only-install.md","filePath":"reference/adr/0032-npm-only-install.md","lastUpdated":null}'),i={name:"reference/adr/0032-npm-only-install.md"};function n(s,e,d,r,c,p){return a(),l("div",null,[...e[0]||(e[0]=[o('<div><h1 id="_0032-安装、升级和文档只依赖-npm-源" tabindex="-1">0032 安装、升级和文档只依赖 npm 源 <a class="header-anchor" href="#_0032-安装、升级和文档只依赖-npm-源" aria-label="Permalink to &quot;0032 安装、升级和文档只依赖 npm 源&quot;">​</a></h1><ul><li>状态：已采纳（1.13.0-beta.1）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>req-kit 要分发给公司内网的使用者。内网有 npm 镜像，但打不开 GitHub 和部署在 Vercel、GitHub Pages 上的文档站点。过去的一键安装依赖三样外网资源：</p><ul><li>安装脚本 <code>install.sh</code> / <code>install.ps1</code> 放在文档站点上；</li><li>npm 上没有某个版本时，脚本去 GitHub 的 Release 列表找安装包；</li><li>文档只在线上站点。</li></ul><p>另外，两份脚本各自实现了检查环境、安装 Paseo、启用、配置 agent、插件这些步骤，改一处要改两处，Windows 和其他系统的行为也容易不一致。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>安装逻辑放进包里</strong>：新增 <code>req install</code>（<code>bin/bootstrap.mjs</code>，Node.js 实现），包含原来脚本的全部步骤。包新增同名命令 <code>paseo-req-kit</code>，所以任何能访问 npm 源的机器都可以直接运行 <code>npx -y paseo-req-kit@latest install</code>。</li><li><strong>镜像地址只说一次</strong>：<code>npx -y --registry=&lt;镜像&gt; … install</code>（或 <code>--registry &lt;镜像&gt;</code>）会把镜像保存为本机的 npm 源，之后的升级和 Paseo 命令行安装都走镜像；<code>--no-save-registry</code> 只用这一次。指定了镜像而镜像上没有这个版本时，直接说明可能还没同步，不再尝试 GitHub。</li><li><strong>安装脚本变薄</strong>：<code>install.sh</code> / <code>install.ps1</code> 只检查 Node.js 和 npm、选版本（npm 优先，GitHub Release 兜底），然后用 <code>npm exec</code> 运行那个版本自带的 <code>install</code>。外网用户的用法不变。</li><li><strong>文档随包发布</strong>：发布流程把文档站点构建进 npm 包（<code>site-dist/</code>），<code>req docs</code> 在本机起一个只监听 127.0.0.1 的服务并打开浏览器。文档和装的版本一致，不需要外网。</li><li>内网的共享文档站点（例如内网 Git Pages）是可选的，可以从镜像中的 npm 包取出 <code>site-dist/</code> 部署，另行实现。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>1.13 之前的版本没有 <code>install</code> 命令：新的安装脚本只能安装 1.13 及以后的版本。要装更早的版本，用那个版本标签下的旧脚本，或 <code>npm i -g paseo-req-kit@&lt;版本&gt; &amp;&amp; req setup</code>。</li><li>npm 包增加了构建好的文档站点（约几 MB）。</li><li>内网只支持 npm 方式安装和升级；git 方式仍需访问 GitHub。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0032-npm-only-install.md">docs/adr/0032-npm-only-install.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0032-npm-only-install.md">在 GitHub 上编辑</a></p>',2)])])}const h=t(i,[["render",n]]);export{u as __pageData,h as default};
+import{_ as t,o as a,c as l,a2 as o}from"./chunks/framework.BetZR81g.js";const u=JSON.parse('{"title":"0032 安装、升级和文档只依赖 npm 源","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0032-npm-only-install.md","filePath":"reference/adr/0032-npm-only-install.md","lastUpdated":null}'),i={name:"reference/adr/0032-npm-only-install.md"};function n(s,e,d,r,c,p){return a(),l("div",null,[...e[0]||(e[0]=[o('<div><h1 id="_0032-安装、升级和文档只依赖-npm-源" tabindex="-1">0032 安装、升级和文档只依赖 npm 源 <a class="header-anchor" href="#_0032-安装、升级和文档只依赖-npm-源" aria-label="Permalink to &quot;0032 安装、升级和文档只依赖 npm 源&quot;">​</a></h1><ul><li>状态：已采纳（1.13.0-beta.1）</li></ul><h2 id="背景" tabindex="-1">背景 <a class="header-anchor" href="#背景" aria-label="Permalink to &quot;背景&quot;">​</a></h2><p>req-kit 要分发给公司内网的使用者。内网有 npm 镜像，但打不开 GitHub 和部署在 Vercel、GitHub Pages 上的文档站点。过去的一键安装依赖三样外网资源：</p><ul><li>安装脚本 <code>install.sh</code> / <code>install.ps1</code> 放在文档站点上；</li><li>npm 上没有某个版本时，脚本去 GitHub 的 Release 列表找安装包；</li><li>文档只在线上站点。</li></ul><p>另外，两份脚本各自实现了检查环境、安装 Paseo、启用、配置 agent、插件这些步骤，改一处要改两处，Windows 和其他系统的行为也容易不一致。</p><h2 id="决定" tabindex="-1">决定 <a class="header-anchor" href="#决定" aria-label="Permalink to &quot;决定&quot;">​</a></h2><ul><li><strong>安装逻辑放进包里</strong>：新增 <code>req install</code>（<code>bin/bootstrap.mjs</code>，Node.js 实现），包含原来脚本的全部步骤。包新增同名命令 <code>paseo-req-kit</code>，所以任何能访问 npm 源的机器都可以直接运行 <code>npx -y paseo-req-kit@latest install</code>。</li><li><strong>镜像地址只说一次</strong>：<code>npx -y --registry=&lt;镜像&gt; … install</code>（或 <code>--registry &lt;镜像&gt;</code>）会把镜像保存为本机的 npm 源，之后的升级和 Paseo 命令行安装都走镜像；<code>--no-save-registry</code> 只用这一次。指定了镜像而镜像上没有这个版本时，直接说明可能还没同步，不再尝试 GitHub。</li><li><strong>安装脚本变薄</strong>：<code>install.sh</code> / <code>install.ps1</code> 只检查 Node.js 和 npm、选版本（npm 优先，GitHub Release 兜底），然后用 <code>npm exec</code> 运行那个版本自带的 <code>install</code>。外网用户的用法不变。</li><li><strong>文档随包发布</strong>：发布流程把文档站点构建进 npm 包（<code>site-dist/</code>），<code>req docs</code> 在本机起一个只监听 127.0.0.1 的服务并打开浏览器。文档和装的版本一致，不需要外网。</li><li>内网的共享文档站点（例如内网 Git Pages）是可选的，可以从镜像中的 npm 包取出 <code>site-dist/</code> 部署，另行实现。</li></ul><h2 id="影响" tabindex="-1">影响 <a class="header-anchor" href="#影响" aria-label="Permalink to &quot;影响&quot;">​</a></h2><ul><li>1.13 之前的版本没有 <code>install</code> 命令：新的安装脚本只能安装 1.13 及以后的版本。要装更早的版本，用那个版本标签下的旧脚本，或 <code>npm i -g paseo-req-kit@&lt;版本&gt; &amp;&amp; req setup</code>。</li><li>npm 包增加了构建好的文档站点（约几 MB）。</li><li>内网只支持 npm 方式安装和升级；git 方式仍需访问 GitHub。</li></ul></div><p class="source-note">本页由仓库中的 <a href="https://github.com/yiyisf/paseo-req-kit/blob/main/docs/adr/0032-npm-only-install.md">docs/adr/0032-npm-only-install.md</a> 生成。<a href="https://github.com/yiyisf/paseo-req-kit/edit/main/docs/adr/0032-npm-only-install.md">在 GitHub 上编辑</a></p>',2)])])}const h=t(i,[["render",n]]);export{u as __pageData,h as default};

package/site-dist/assets/{reference_adr_0032-npm-only-install.md.C-3L1FkX.lean.js → reference_adr_0032-npm-only-install.md.5tFsGLKz.lean.js}

@@ -1 +1 @@
-import{_ as t,o as a,c as l,a3 as o}from"./chunks/framework.B9qR_F1m.js";const u=JSON.parse('{"title":"0032 安装、升级和文档只依赖 npm 源","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0032-npm-only-install.md","filePath":"reference/adr/0032-npm-only-install.md","lastUpdated":null}'),i={name:"reference/adr/0032-npm-only-install.md"};function n(s,e,d,r,c,p){return a(),l("div",null,[...e[0]||(e[0]=[o("",2)])])}const h=t(i,[["render",n]]);export{u as __pageData,h as default};
+import{_ as t,o as a,c as l,a2 as o}from"./chunks/framework.BetZR81g.js";const u=JSON.parse('{"title":"0032 安装、升级和文档只依赖 npm 源","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/adr/0032-npm-only-install.md","filePath":"reference/adr/0032-npm-only-install.md","lastUpdated":null}'),i={name:"reference/adr/0032-npm-only-install.md"};function n(s,e,d,r,c,p){return a(),l("div",null,[...e[0]||(e[0]=[o("",2)])])}const h=t(i,[["render",n]]);export{u as __pageData,h as default};

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

@@ -1 +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};
+import{_ as o,o as a,c as t,a2 as i}from"./chunks/framework.BetZR81g.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 → reference_adr_0033-prototype-review-and-ui-check.md.CW5Soqvp.lean.js}

@@ -1 +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};
+import{_ as o,o as a,c as t,a2 as i}from"./chunks/framework.BetZR81g.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.BYF-Ofor.js → reference_adr_index.md.DgUVrHoO.js}

@@ -1 +1 @@
-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};
+import{_ as a,o as i,c as r,a2 as l}from"./chunks/framework.BetZR81g.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.BYF-Ofor.lean.js → reference_adr_index.md.DgUVrHoO.lean.js}

@@ -1 +1 @@
-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};
+import{_ as a,o as i,c as r,a2 as l}from"./chunks/framework.BetZR81g.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};