npm - paseo-req-kit - Versions diffs - 1.13.0 → 1.14.0-beta.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (106) hide show

package/site-dist/assets/{guide_user.md.Cenm9vlN.js → guide_user.md.2v7b_fzd.js} RENAMED Viewed

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

package/site-dist/assets/{guide_user.md.Cenm9vlN.lean.js → guide_user.md.2v7b_fzd.lean.js} RENAMED Viewed

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

package/site-dist/assets/reference_contracts_cli-json.md.BR6gwq-e.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as t,o as d,c as u,j as l,a as e}from"./chunks/framework.B9qR_F1m.js";const k=JSON.parse('{"title":"给程序用的 JSON 输出：req api","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/cli-json.md","filePath":"reference/contracts/cli-json.md","lastUpdated":null}'),s={name:"reference/contracts/cli-json.md"};function i(o,n,a,r,c,p){return d(),u("div",null,[...n[0]||(n[0]=[l("div",null,[l("h1",{id:"给程序用的-json-输出-req-api",tabindex:"-1"},[e("给程序用的 JSON 输出："),l("code",null,"req api"),e(),l("a",{class:"header-anchor",href:"#给程序用的-json-输出-req-api","aria-label":'Permalink to "给程序用的 JSON 输出：`req api`"'},"")]),l("p",null,[e("1.9.0 起。Paseo 插件和其他程序通过 "),l("code",null,"req api"),e(" 读取需求、执行管理操作，不直接读写状态文件。每个命令输出一行 JSON：")]),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{ "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"schema"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"data"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#B31D28","--shiki-light-font-style":"italic","--shiki-dark":"#FDAEB7","--shiki-dark-font-style":"italic"}},"…"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," }")])])])]),l("p",null,"出错时退出码为 1："),l("div",{class:"language-json vp-adaptive-theme"},[l("button",{title:"Copy Code",class:"copy"}),l("span",{class:"lang"},"json"),l("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[l("code",null,[l("span",{class:"line"},[l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{ "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"schema"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"kitVersion"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"1.9.0"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"error"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": { "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"code"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"not_found"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},", "),l("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'"message"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),l("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"没有找到需求……"'),l("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}}," } }")])])])]),l("p",null,[l("code",null,"code"),e("："),l("code",null,"bad_arguments"),e("（参数不对）、"),l("code",null,"not_found"),e("（目录或需求不存在）、"),l("code",null,"not_allowed"),e("（不允许的文件或命令）、"),l("code",null,"failed"),e("（其他错误）。")]),l("p",null,[l("code",null,"schema"),e(" 只在不兼容的修改时增加；新增字段不改变 "),l("code",null,"schema"),e("，读取方应忽略不认识的字段。")]),l("h2",{id:"命令",tabindex:"-1"},[e("命令 "),l("a",{class:"header-anchor",href:"#命令","aria-label":'Permalink to "命令"'},"")]),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"命令"),l("th",null,[l("code",null,"data")])])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"req api version")]),l("td",null,[l("code",null,"{ kitVersion, kitRoot, apiSchema, paseo, featuresDir }"),e("："),l("code",null,"paseo"),e(" 是这个版本支持的 Paseo 范围")])]),l("tr",null,[l("td",null,[l("code",null,"req api list [--repo <目录>]")]),l("td",null,'这个仓库所有工作区中的需求，数组，每项见下面的"需求"')]),l("tr",null,[l("td",null,[l("code",null,"req api list --all")]),l("td",null,[e("本机记录过的所有需求（"),l("a",{href:"./usage-record"},"需求索引"),e("），同上；目录已不在的 "),l("code",null,"present: false"),e("。1.14 起还包括：用 "),l("code",null,"--track"),e(" 登记、还在对齐中的需求（"),l("code",null,"stage"),e(' 为"对齐中"，没有 '),l("code",null,"spec.md"),e(" 时 "),l("code",null,"title"),e(" 取自 "),l("code",null,"alignment.md"),e("），以及索引里出现过的项目中没登记的需求")])]),l("tr",null,[l("td",null,[l("code",null,"req api status <需求> [--repo <目录>]")]),l("td",null,'一个需求的详情，见下面的"详情"')]),l("tr",null,[l("td",null,[l("code",null,"req api file <需求> <文件> [--repo <目录>]")]),l("td",null,[l("code",null,"{ featureDir, file, size, truncated, content }"),e("；只能读取功能目录中的文档（见下），最多 512 KB")])]),l("tr",null,[l("td",null,[l("code",null,"req api stats [--since 30d] [--month 2026-10]")]),l("td",null,[l("code",null,"req stats --json"),e(" 的内容，见 "),l("a",{href:"./usage-record"},"使用记录")])]),l("tr",null,[l("td",null,[l("code",null,"req api index [--rebuild <目录>…] [--prune]")]),l("td",null,[e("不带选项：索引的全部条目；"),l("code",null,"--rebuild"),e("："),l("code",null,"{ scanned, registered, pruned, total }")])]),l("tr",null,[l("td",null,[l("code",null,"req api run <approve|stop|resume|verify|sync|reply|start> <需求> [--repo <目录>] [选项]")]),l("td",null,[l("code",null,"{ command, featureDir, ok, exitCode, message }"),e("。在 "),l("code",null,"--repo"),e("（默认当前目录）中执行与 "),l("code",null,"req <命令> <需求>"),e(" 完全相同的操作；"),l("code",null,"ok"),e(" 为 false 时退出码为 1。"),l("code",null,"start"),e("（1.14）：在项目主目录中自动加 "),l("code",null,"--worktree"),e("（上次已建好工作区的接着用），并把进展发回登记时的对话")])]),l("tr",null,[l("td",null,[l("code",null,"req api models")]),l("td",null,[e("1.12 起。"),l("code",null,"{ current, choices, recommended }"),e("：本机配置中现在的 "),l("code",null,"agents"),e("；daemon 上能无人值守运行的选择（"),l("code",null,"{ id, label, provider, profile }"),e("，Paseo profile 在前）；按推荐的 "),l("code",null,"agents"),e("。连不上 daemon 时报错")])]),l("tr",null,[l("td",null,[l("code",null,"req api config [--repo <目录>] [--machine]")]),l("td",null,[e("1.12 起。"),l("code",null,"{ sources, ignored, error, repo, groups }"),e("："),l("code",null,"sources"),e(" 是生效的配置文件（"),l("code",null,"layer"),e(" 为 "),l("code",null,"machine"),e(" / "),l("code",null,"team"),e(" / "),l("code",null,"project"),e("，按叠加顺序）；"),l("code",null,"groups"),e(" 按主题分组，每项 "),l("code",null,"{ key, label, description, display, value, setBy, scope, changed }"),e("："),l("code",null,"display"),e(" 是用大白话写的值，"),l("code",null,"value"),e(" 中看起来像密钥的值和个人账号替换为 "),l("code",null,"••••"),e("，"),l("code",null,"setBy"),e(" 是写了它的文件，"),l("code",null,"changed"),e(" 表示与默认值不同。配置有错误时 "),l("code",null,"error"),e(" 写明原因，值按各文件所写。"),l("code",null,"--machine"),e(" 不看项目配置")])]),l("tr",null,[l("td",null,[l("code",null,"req api set-agents --json <设置>")]),l("td",null,[e("1.12 起。"),l("code",null,"{ ok, message }"),e("。"),l("code",null,"<设置>"),e(" 是 "),l("code",null,"{ builder, reviewer, fallback }"),e("（"),l("code",null,"fallback"),e(" 可以为 null），检查后写入本机配置的 "),l("code",null,"agents"),e("，原文件备份")])]),l("tr",null,[l("td",null,[l("code",null,"req api watchdog [--by plugin|factory] [--dry-run]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ checked, resumed, failed, skipped }"),e('：把本机"运行中但后台进程已不在"的需求直接继续（'),l("code",null,"req resume"),e("）。每个进程只继续一次，每个需求 24 小时内最多 3 次；"),l("code",null,"--by plugin"),e(" 同时记下插件在检查（流水线据此不再预约对话的定时检查）")])]),l("tr",null,[l("td",null,[l("code",null,"req api review-url <需求> [--repo <目录>] [--read-only]")]),l("td",null,[e("1.13 起。"),l("code",null,"{ url, readOnly }"),e("：这个需求的原型审查页地址（需要时在后台启动审查页的服务）。"),l("code",null,"--read-only"),e(" 的地址只能看，不能提交意见或确认方案。需求不在本机的需求索引中或还没有 "),l("code",null,"prototype/"),e(" 时报 "),l("code",null,"not_found")])])])]),l("p",null,[l("code",null,"<需求>"),e(" 的写法与 "),l("code",null,"req status"),e(" 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，"),l("code",null,"--repo"),e(" 写对话所在的目录或那个工作区都可以。")]),l("p",null,[l("code",null,"req api file"),e(" 能读取的文件："),l("code",null,"spec.md"),e("、"),l("code",null,"alignment.md"),e("、"),l("code",null,"spec-review.md"),e("、"),l("code",null,"changes.md"),e("、"),l("code",null,"decisions.tsv"),e("、"),l("code",null,"design.md"),e("、"),l("code",null,"design-review.md"),e("、"),l("code",null,"preview.md"),e("、"),l("code",null,"contract.md"),e("、"),l("code",null,"diagnosis.md"),e("、"),l("code",null,"assessment.md"),e("、"),l("code",null,"implementation.md"),e("、"),l("code",null,"progress.md"),e("、"),l("code",null,"code-review.md"),e("、"),l("code",null,"handoff.md"),e("、"),l("code",null,"service-start.md"),e("、"),l("code",null,"verification.md"),e("、"),l("code",null,"report.md"),e("、"),l("code",null,"acceptance.md"),e("、"),l("code",null,"lessons.tsv"),e("。")]),l("h2",{id:"需求-list-的每一项",tabindex:"-1"},[e("需求（"),l("code",null,"list"),e(" 的每一项） "),l("a",{class:"header-anchor",href:"#需求-list-的每一项","aria-label":'Permalink to "需求（`list` 的每一项）"'},"")]),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"key")]),l("td",null,"需求在本机的标识（对话所在目录 + 功能目录）")]),l("tr",null,[l("td",null,[l("code",null,"project")]),l("td",null,"项目名：对话所在目录的目录名")]),l("tr",null,[l("td",null,[l("code",null,"repo")]),l("td",null,"需求所在的目录（有自己的工作区时是那个工作区）")]),l("tr",null,[l("td",null,[l("code",null,"sourceRepo"),e(" / "),l("code",null,"workspaceId")]),l("td",null,"有自己的工作区时：对话所在的目录、Paseo 工作区 ID；否则 null")]),l("tr",null,[l("td",null,[l("code",null,"featureDir"),e(" / "),l("code",null,"name"),e(" / "),l("code",null,"title")]),l("td",null,"功能目录、目录名、需求标题")]),l("tr",null,[l("td",null,[l("code",null,"type"),e(" / "),l("code",null,"profile"),e(" / "),l("code",null,"branch")]),l("td",null,[e("需求类型（"),l("code",null,"defect"),e("、"),l("code",null,"refactor"),e("、"),l("code",null,"assessment"),e(" 或 null）、档位、分支")])]),l("tr",null,[l("td",null,[l("code",null,"stage")]),l("td",null,[e("与 "),l("code",null,"req list"),e(' 相同的阶段说明，如"开发中""等待确认方案""待验收"')])]),l("tr",null,[l("td",null,[l("code",null,"status")]),l("td",null,[e("状态文件的 "),l("code",null,"status"),e("；还没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"running")]),l("td",null,"后台进程是否在运行")]),l("tr",null,[l("td",null,[l("code",null,"phase")]),l("td",null,[l("code",null,"develop"),e(" / "),l("code",null,"verify")])]),l("tr",null,[l("td",null,[l("code",null,"attention")]),l("td",null,[e("需要人处理的事："),l("code",null,"approval"),e("（确认方案）、"),l("code",null,"business"),e("（需求方决定）、"),l("code",null,"permission"),e("（1.13，步骤在等权限批准；"),l("code",null,"waiting.questions"),e(" 是要批准的操作，"),l("code",null,"waiting.agentId"),e(" 是那个 agent）、"),l("code",null,"interrupted"),e("（中断，可以继续）、"),l("code",null,"not_completed"),e("（结束但未完成）、"),l("code",null,"not_started"),e("（1.14，需求说明已确认超过 30 分钟、或已为它建好工作区，但流水线没有运行过）；没有为 null")])]),l("tr",null,[l("td",null,[l("code",null,"waiting")]),l("td",null,[e("1.12 起。"),l("code",null,"attention"),e(" 不为 null 时："),l("code",null,"since"),e("（从什么时候开始等）、"),l("code",null,"questions"),e("（需求方要回答的问题）、"),l("code",null,"reason"),e("（停止原因）、"),l("code",null,"card"),e("（"),l("code",null,"{ system, id, url, requester }"),e("，从卡片开始的需求）、"),l("code",null,"canReply"),e("（能否用 "),l("code",null,"req api run reply <需求> <回复>"),e(" 把回复转给需求的对话）、"),l("code",null,"canStart"),e("（1.14，"),l("code",null,"not_started"),e(" 时为 true：可以用 "),l("code",null,"req api run start <需求>"),e(" 开始开发）；否则为 null")])]),l("tr",null,[l("td",null,[l("code",null,"current")]),l("td",null,[e("正在运行的步骤 "),l("code",null,"[{ key, title, agentId }]")])]),l("tr",null,[l("td",null,[l("code",null,"updatedAt")]),l("td",null,"最近一次变化的时间")]),l("tr",null,[l("td",null,[l("code",null,"usage")]),l("td",null,[l("code",null,"{ steps, agentMinutes, inputTokens, outputTokens, costUsd }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"present")]),l("td",null,"目录是否还在")]),l("tr",null,[l("td",null,[l("code",null,"hasPrototype")]),l("td",null,[e("1.13 起。功能目录中有界面原型（"),l("code",null,"prototype/"),e("），可以用原型审查页查看")])])])]),l("h2",{id:"详情-status",tabindex:"-1"},[e("详情（"),l("code",null,"status"),e("） "),l("a",{class:"header-anchor",href:"#详情-status","aria-label":'Permalink to "详情（`status`）"'},"")]),l("p",null,'"需求"的全部字段，另加：'),l("table",{tabindex:"0"},[l("thead",null,[l("tr",null,[l("th",null,"字段"),l("th",null,"含义")])]),l("tbody",null,[l("tr",null,[l("td",null,[l("code",null,"files")]),l("td",null,[e("功能目录中存在的、可以用 "),l("code",null,"req api file"),e(" 读取的文件")])]),l("tr",null,[l("td",null,[l("code",null,"run")]),l("td",null,[l("code",null,"{ attempt, startedAt, updatedAt, pid, phaseMode, stopReason, outcome, queuedSince, verifyAt, approval, originAgentId }"),e("；没运行过为 null")])]),l("tr",null,[l("td",null,[l("code",null,"steps")]),l("td",null,[e("每个步骤一项："),l("code",null,"{ key, stepId, title, phase, attempt, round, agentId, startedAt, endedAt, minutes, outcome, result, error, usage }"),e("；"),l("code",null,"title"),e(' 是给人看的名称（如"代码评审（第 2 轮）"），'),l("code",null,"result"),e(' 是结论的文字（如"需要修改"）')])]),l("tr",null,[l("td",null,[l("code",null,"gate")]),l("td",null,[e("质量门：状态文件中的 "),l("code",null,"gate")])]),l("tr",null,[l("td",null,[l("code",null,"estimate")]),l("td",null,[e("1.13 起。"),l("code",null,"{ basis, profile, typicalAgentMinutes, typicalTokens, usedAgentMinutes, usedTokens, leftMinutes, over }"),e("：按本机已完成的同档位需求（至少 3 个）的中位数估算；数据不够或已完成时为 null")])]),l("tr",null,[l("td",null,[l("code",null,"joint")]),l("td",null,[e("联合需求的其他仓库："),l("code",null,"[{ name, slug, repo, sourceRepo, branch, workspaceId, gate }]")])]),l("tr",null,[l("td",null,[l("code",null,"external")]),l("td",null,[e("外部系统中的卡片（1.9.0 起）："),l("code",null,"[{ name, id, url, status, syncedAt, pending, lastError }]"),e("；"),l("code",null,"pending"),e(" 是等待补发的调用数")])])])])],-1),l("p",{class:"source-note"},[e("本页由仓库中的 "),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/cli-json.md"},"contracts/cli-json.md"),e(" 生成。"),l("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/cli-json.md"},"在 GitHub 上编辑")],-1)])])}const g=t(s,[["render",i]]);export{k as __pageData,g as default};

package/site-dist/assets/reference_contracts_cli-json.md.BR6gwq-e.lean.js ADDED Viewed

@@ -0,0 +1 @@

package/site-dist/assets/reference_contracts_usage-record.md.D5krNLW7.js ADDED Viewed

@@ -0,0 +1,10 @@
+import{_ as n,o as i,c as t,j as e,a as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(o,s,r,u,c,h){return i(),t("div",null,[...s[0]||(s[0]=[e("div",null,[e("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[l("本机的需求索引与使用记录 "),e("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"")]),e("p",null,[l("1.9.0 起，引擎在本机配置目录（默认 "),e("code",null,"~/.req-kit"),l("，可用 "),e("code",null,"REQ_KIT_HOME"),l(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),e("code",null,"REQ_KIT_NO_RECORD=1"),l(" 时两样都不记（评估运行就是这样）。")]),e("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[l("需求索引 "),e("code",null,"index/<key>.json"),l(),e("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"")]),e("p",null,[l("每个在本机运行过的需求一个文件，记录它在哪里，供 "),e("code",null,"req api list --all"),l(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),e("div",{class:"language-json vp-adaptive-theme"},[e("button",{title:"Copy Code",class:"copy"}),e("span",{class:"lang"},"json"),e("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[e("code",null,[e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "schema"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "key"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"3f2a9c1e5b7d4e8a"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "repo"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop-sms-login"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "featureDir"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"docs/features/20261012-sms-login"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "sourceRepo"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "workspaceId"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"ws_123"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "project"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"shop"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "registeredAt"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"2026-10-12T09:00:00.000Z"')]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),e("p",null,[e("code",null,"key"),l(" 由对话所在的目录（没有自己的工作区时即 "),e("code",null,"repo"),l("）和功能目录算出。1.14 起：开始谈需求时（"),e("code",null,"start-pipeline --feature <功能目录> --track"),l("）就登记，此时多一个可选字段 "),e("code",null,"chatAgentId"),l("（谈需求的对话），之后的登记保留它；新建需求自己的工作区时，条目改为指向那个工作区。目录里有 "),e("code",null,"spec.md"),l("、"),e("code",null,"alignment.md"),l(" 或 "),e("code",null,".pipeline/"),l(" 下的状态或登记标记时算作存在。")]),e("h2",{id:"新建工作区的记录-worktrees-key-json-1-14",tabindex:"-1"},[l("新建工作区的记录 "),e("code",null,"worktrees/<key>.json"),l("（1.14） "),e("a",{class:"header-anchor",href:"#新建工作区的记录-worktrees-key-json-1-14","aria-label":'Permalink to "新建工作区的记录 `worktrees/<key>.json`（1.14）"'},"")]),e("p",null,[l("用 "),e("code",null,"--worktree"),l(" 启动时，工作区一建好就写下："),e("code",null,"{ schema, sourceRepo, featureDir, repo, workspaceId, branch, baseRef, createdAt, originAgentId }"),l('。之后的启动失败了，再次启动时在这个工作区里接着做，不再新建；插件据此把"工作区已建、开发没开始"的需求列进"等你处理"。'),e("code",null,"req index --rebuild"),l(" 为 1.9 之前运行过的需求补登，"),e("code",null,"req index --prune"),l(" 移除目录已不在的。")]),e("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[l("使用记录 "),e("code",null,"usage/runs.jsonl"),l(),e("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"")]),e("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),e("table",{tabindex:"0"},[e("thead",null,[e("tr",null,[e("th",null,"字段"),e("th",null,"含义")])]),e("tbody",null,[e("tr",null,[e("td",null,[e("code",null,"schema"),l(" / "),e("code",null,"kind")]),e("td",null,[e("code",null,"1"),l(" / "),e("code",null,'"run"')])]),e("tr",null,[e("td",null,[e("code",null,"machine"),l(" / "),e("code",null,"kitVersion")]),e("td",null,"主机名、req-kit 版本")]),e("tr",null,[e("td",null,[e("code",null,"requirement")]),e("td",null,[e("code",null,"{ key, project, name, title, type, profile }"),l("；从卡片开始的需求（1.10 起）另有 "),e("code",null,"requester"),l("（卡片的提出人）和 "),e("code",null,"source"),l("（"),e("code",null,"{ system, id }"),l("）")])]),e("tr",null,[e("td",null,[e("code",null,"steps[].cachedInputTokens"),l(" / "),e("code",null,"steps[].agent")]),e("td",null,'1.13 起。输入中来自提示缓存的 tokens（agent 报告时）；这一步用的 agent（Paseo profile 名，或 "provider/model"）。更早的记录没有')]),e("tr",null,[e("td",null,[e("code",null,"run")]),e("td",null,[e("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),l("；"),e("code",null,"status"),l(" 是运行结束时的状态，"),e("code",null,"outcome"),l(" 是完成时报告的结论；"),e("code",null,"stopKind"),l("（1.12 起）是停下等人的原因代码（见 "),e("a",{href:"./state"},"state.md"),l("），"),e("code",null,"recoveries"),l("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),e("code",null,'{ "retry": 2 }'),l("。更早的记录没有这两项")])]),e("tr",null,[e("td",null,[e("code",null,"agents")]),e("td",null,[e("code",null,"{ builder, reviewer }"),l("：当时配置的 agent（如 "),e("code",null,"claude/opus（bypassPermissions）"),l("）")])]),e("tr",null,[e("td",null,[e("code",null,"steps")]),e("td",null,[l("这次运行中开始的步骤："),e("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),l("；agent 没有报告的用量为 null")])]),e("tr",null,[e("td",null,[e("code",null,"gate")]),e("td",null,[e("code",null,"{ runs, failed }"),l("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),e("p",null,"不记录需求内容、代码和对话。"),e("h2",{id:"统计口径-req-stats",tabindex:"-1"},[l("统计口径（"),e("code",null,"req stats"),l("） "),e("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"")]),e("ul",null,[e("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),e("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),e("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),e("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),e("li",null,[l("token 花在哪（1.13 起，"),e("code",null,"tokens"),l("）：这段时间的步骤按 "),e("code",null,"stepId"),l("、按 "),e("code",null,"agent"),l(" 合计 token（输入 + 输出）和占比；返工（"),e("code",null,"design_revise"),l("、"),e("code",null,"review_fix"),l("、"),e("code",null,"defect_fix"),l("、"),e("code",null,"reverify"),l("，以及 "),e("code",null,"design_review"),l("、"),e("code",null,"code_review"),l(" 第 2 轮起）的合计和占比；报告了 "),e("code",null,"cachedInputTokens"),l(" 的，算出输入中来自提示缓存的比例；已完成需求的 token 中位数（按档位）。")]),e("li",null,[l("停下等人的原因（1.12 起）：这段时间结束的运行按 "),e("code",null,"stopKind"),l(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),e("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),e("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),e("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),e("p",null,[e("code",null,"req stats --json"),l(" 和 "),e("code",null,"req api stats"),l(" 输出同样的对象（"),e("code",null,"schema: 1"),l("）："),e("code",null,"period"),l("、"),e("code",null,"machines"),l("、"),e("code",null,"active"),l("、"),e("code",null,"completed"),l("、"),e("code",null,"byType"),l("、"),e("code",null,"cycleHours"),l("、"),e("code",null,"steps"),l("、"),e("code",null,"rework"),l("、"),e("code",null,"waits"),l("、"),e("code",null,"usage"),l("、"),e("code",null,"byBuilder"),l("、"),e("code",null,"requirements"),l("（每个需求一项，字段与 "),e("code",null,"req stats --csv"),l(" 的列对应）。")])],-1),e("p",{class:"source-note"},[l("本页由仓库中的 "),e("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),l(" 生成。"),e("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=n(a,[["render",d]]);export{p as __pageData,E as default};

package/site-dist/assets/reference_contracts_usage-record.md.D5krNLW7.lean.js ADDED Viewed

@@ -0,0 +1,10 @@
+import{_ as n,o as i,c as t,j as e,a as l}from"./chunks/framework.B9qR_F1m.js";const p=JSON.parse('{"title":"本机的需求索引与使用记录","description":"","frontmatter":{"editLink":false},"headers":[],"relativePath":"reference/contracts/usage-record.md","filePath":"reference/contracts/usage-record.md","lastUpdated":null}'),a={name:"reference/contracts/usage-record.md"};function d(o,s,r,u,c,h){return i(),t("div",null,[...s[0]||(s[0]=[e("div",null,[e("h1",{id:"本机的需求索引与使用记录",tabindex:"-1"},[l("本机的需求索引与使用记录 "),e("a",{class:"header-anchor",href:"#本机的需求索引与使用记录","aria-label":'Permalink to "本机的需求索引与使用记录"'},"")]),e("p",null,[l("1.9.0 起，引擎在本机配置目录（默认 "),e("code",null,"~/.req-kit"),l("，可用 "),e("code",null,"REQ_KIT_HOME"),l(" 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 "),e("code",null,"REQ_KIT_NO_RECORD=1"),l(" 时两样都不记（评估运行就是这样）。")]),e("h2",{id:"需求索引-index-key-json",tabindex:"-1"},[l("需求索引 "),e("code",null,"index/<key>.json"),l(),e("a",{class:"header-anchor",href:"#需求索引-index-key-json","aria-label":'Permalink to "需求索引 `index/<key>.json`"'},"")]),e("p",null,[l("每个在本机运行过的需求一个文件，记录它在哪里，供 "),e("code",null,"req api list --all"),l(" 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。")]),e("div",{class:"language-json vp-adaptive-theme"},[e("button",{title:"Copy Code",class:"copy"}),e("span",{class:"lang"},"json"),e("pre",{class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0","v-pre":""},[e("code",null,[e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"{")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "schema"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},"1"),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "key"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"3f2a9c1e5b7d4e8a"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "repo"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop-sms-login"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "featureDir"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"docs/features/20261012-sms-login"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "sourceRepo"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"/home/me/work/shop"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "workspaceId"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"ws_123"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "project"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"shop"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},",")]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}},'  "registeredAt"'),e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},": "),e("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},'"2026-10-12T09:00:00.000Z"')]),l(`
+`),e("span",{class:"line"},[e("span",{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"}},"}")])])])]),e("p",null,[e("code",null,"key"),l(" 由对话所在的目录（没有自己的工作区时即 "),e("code",null,"repo"),l("）和功能目录算出。1.14 起：开始谈需求时（"),e("code",null,"start-pipeline --feature <功能目录> --track"),l("）就登记，此时多一个可选字段 "),e("code",null,"chatAgentId"),l("（谈需求的对话），之后的登记保留它；新建需求自己的工作区时，条目改为指向那个工作区。目录里有 "),e("code",null,"spec.md"),l("、"),e("code",null,"alignment.md"),l(" 或 "),e("code",null,".pipeline/"),l(" 下的状态或登记标记时算作存在。")]),e("h2",{id:"新建工作区的记录-worktrees-key-json-1-14",tabindex:"-1"},[l("新建工作区的记录 "),e("code",null,"worktrees/<key>.json"),l("（1.14） "),e("a",{class:"header-anchor",href:"#新建工作区的记录-worktrees-key-json-1-14","aria-label":'Permalink to "新建工作区的记录 `worktrees/<key>.json`（1.14）"'},"")]),e("p",null,[l("用 "),e("code",null,"--worktree"),l(" 启动时，工作区一建好就写下："),e("code",null,"{ schema, sourceRepo, featureDir, repo, workspaceId, branch, baseRef, createdAt, originAgentId }"),l('。之后的启动失败了，再次启动时在这个工作区里接着做，不再新建；插件据此把"工作区已建、开发没开始"的需求列进"等你处理"。'),e("code",null,"req index --rebuild"),l(" 为 1.9 之前运行过的需求补登，"),e("code",null,"req index --prune"),l(" 移除目录已不在的。")]),e("h2",{id:"使用记录-usage-runs-jsonl",tabindex:"-1"},[l("使用记录 "),e("code",null,"usage/runs.jsonl"),l(),e("a",{class:"header-anchor",href:"#使用记录-usage-runs-jsonl","aria-label":'Permalink to "使用记录 `usage/runs.jsonl`"'},"")]),e("p",null,"每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行："),e("table",{tabindex:"0"},[e("thead",null,[e("tr",null,[e("th",null,"字段"),e("th",null,"含义")])]),e("tbody",null,[e("tr",null,[e("td",null,[e("code",null,"schema"),l(" / "),e("code",null,"kind")]),e("td",null,[e("code",null,"1"),l(" / "),e("code",null,'"run"')])]),e("tr",null,[e("td",null,[e("code",null,"machine"),l(" / "),e("code",null,"kitVersion")]),e("td",null,"主机名、req-kit 版本")]),e("tr",null,[e("td",null,[e("code",null,"requirement")]),e("td",null,[e("code",null,"{ key, project, name, title, type, profile }"),l("；从卡片开始的需求（1.10 起）另有 "),e("code",null,"requester"),l("（卡片的提出人）和 "),e("code",null,"source"),l("（"),e("code",null,"{ system, id }"),l("）")])]),e("tr",null,[e("td",null,[e("code",null,"steps[].cachedInputTokens"),l(" / "),e("code",null,"steps[].agent")]),e("td",null,'1.13 起。输入中来自提示缓存的 tokens（agent 报告时）；这一步用的 agent（Paseo profile 名，或 "provider/model"）。更早的记录没有')]),e("tr",null,[e("td",null,[e("code",null,"run")]),e("td",null,[e("code",null,"{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }"),l("；"),e("code",null,"status"),l(" 是运行结束时的状态，"),e("code",null,"outcome"),l(" 是完成时报告的结论；"),e("code",null,"stopKind"),l("（1.12 起）是停下等人的原因代码（见 "),e("a",{href:"./state"},"state.md"),l("），"),e("code",null,"recoveries"),l("（1.12 起）是这次运行中自动处理的次数，按种类，如 "),e("code",null,'{ "retry": 2 }'),l("。更早的记录没有这两项")])]),e("tr",null,[e("td",null,[e("code",null,"agents")]),e("td",null,[e("code",null,"{ builder, reviewer }"),l("：当时配置的 agent（如 "),e("code",null,"claude/opus（bypassPermissions）"),l("）")])]),e("tr",null,[e("td",null,[e("code",null,"steps")]),e("td",null,[l("这次运行中开始的步骤："),e("code",null,"{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }"),l("；agent 没有报告的用量为 null")])]),e("tr",null,[e("td",null,[e("code",null,"gate")]),e("td",null,[e("code",null,"{ runs, failed }"),l("：这次运行中质量门运行的次数、发现新失败的次数")])])])]),e("p",null,"不记录需求内容、代码和对话。"),e("h2",{id:"统计口径-req-stats",tabindex:"-1"},[l("统计口径（"),e("code",null,"req stats"),l("） "),e("a",{class:"header-anchor",href:"#统计口径-req-stats","aria-label":'Permalink to "统计口径（`req stats`）"'},"")]),e("ul",null,[e("li",null,"一段时间的用量、步骤用时：结束时间在这段时间内的运行。"),e("li",null,'交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。'),e("li",null,"代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。"),e("li",null,"等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。"),e("li",null,[l("token 花在哪（1.13 起，"),e("code",null,"tokens"),l("）：这段时间的步骤按 "),e("code",null,"stepId"),l("、按 "),e("code",null,"agent"),l(" 合计 token（输入 + 输出）和占比；返工（"),e("code",null,"design_revise"),l("、"),e("code",null,"review_fix"),l("、"),e("code",null,"defect_fix"),l("、"),e("code",null,"reverify"),l("，以及 "),e("code",null,"design_review"),l("、"),e("code",null,"code_review"),l(" 第 2 轮起）的合计和占比；报告了 "),e("code",null,"cachedInputTokens"),l(" 的，算出输入中来自提示缓存的比例；已完成需求的 token 中位数（按档位）。")]),e("li",null,[l("停下等人的原因（1.12 起）：这段时间结束的运行按 "),e("code",null,"stopKind"),l(" 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。")]),e("li",null,"无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。"),e("li",null,"自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。"),e("li",null,"合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。")]),e("p",null,[e("code",null,"req stats --json"),l(" 和 "),e("code",null,"req api stats"),l(" 输出同样的对象（"),e("code",null,"schema: 1"),l("）："),e("code",null,"period"),l("、"),e("code",null,"machines"),l("、"),e("code",null,"active"),l("、"),e("code",null,"completed"),l("、"),e("code",null,"byType"),l("、"),e("code",null,"cycleHours"),l("、"),e("code",null,"steps"),l("、"),e("code",null,"rework"),l("、"),e("code",null,"waits"),l("、"),e("code",null,"usage"),l("、"),e("code",null,"byBuilder"),l("、"),e("code",null,"requirements"),l("（每个需求一项，字段与 "),e("code",null,"req stats --csv"),l(" 的列对应）。")])],-1),e("p",{class:"source-note"},[l("本页由仓库中的 "),e("a",{href:"https://github.com/yiyisf/paseo-req-kit/blob/main/contracts/usage-record.md"},"contracts/usage-record.md"),l(" 生成。"),e("a",{href:"https://github.com/yiyisf/paseo-req-kit/edit/main/contracts/usage-record.md"},"在 GitHub 上编辑")],-1)])])}const E=n(a,[["render",d]]);export{p as __pageData,E as default};