本机的需求索引与使用记录

1.9.0 起，引擎在本机配置目录（默认 ~/.req-kit，可用 REQ_KIT_HOME 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 REQ_KIT_NO_RECORD=1 时两样都不记（评估运行就是这样）。

需求索引 index/<key>.json

每个在本机运行过的需求一个文件，记录它在哪里，供 req api list --all 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。

{
  "schema": 1,
  "key": "3f2a9c1e5b7d4e8a",
  "repo": "/home/me/work/shop-sms-login",
  "featureDir": "docs/features/20261012-sms-login",
  "sourceRepo": "/home/me/work/shop",
  "workspaceId": "ws_123",
  "project": "shop",
  "registeredAt": "2026-10-12T09:00:00.000Z"
}

key 由对话所在的目录（没有自己的工作区时即 repo）和功能目录算出。1.14 起：开始谈需求时（start-pipeline --feature <功能目录> --track）就登记，此时多一个可选字段 chatAgentId（谈需求的对话），之后的登记保留它；新建需求自己的工作区时，条目改为指向那个工作区。目录里有 spec.md、alignment.md 或 .pipeline/ 下的状态或登记标记时算作存在。

新建工作区的记录 worktrees/<key>.json（1.14）

用 --worktree 启动时，工作区一建好就写下：{ schema, sourceRepo, featureDir, repo, workspaceId, branch, baseRef, createdAt, originAgentId }。之后的启动失败了，再次启动时在这个工作区里接着做，不再新建；插件据此把"工作区已建、开发没开始"的需求列进"等你处理"。req index --rebuild 为 1.9 之前运行过的需求补登，req index --prune 移除目录已不在的。

使用记录 usage/runs.jsonl

每次流水线运行（后台进程从开始到结束，包括停在等待确认、等待需求方、研发完成处）结束时追加一行：

字段	含义
schema / kind	1 / "run"
machine / kitVersion	主机名、req-kit 版本
requirement	{ key, project, name, title, type, profile }；从卡片开始的需求（1.10 起）另有 requester（卡片的提出人）和 source（{ system, id }）
steps[].cachedInputTokens / steps[].agent	1.13 起。输入中来自提示缓存的 tokens（agent 报告时）；这一步用的 agent（Paseo profile 名，或 "provider/model"）。更早的记录没有
run	{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason, stopKind, recoveries }；status 是运行结束时的状态，outcome 是完成时报告的结论；stopKind（1.12 起）是停下等人的原因代码（见 state.md），recoveries（1.12 起）是这次运行中自动处理的次数，按种类，如 { "retry": 2 }。更早的记录没有这两项
agents	{ builder, reviewer }：当时配置的 agent（如 claude/opus（bypassPermissions））
steps	这次运行中开始的步骤：{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }；agent 没有报告的用量为 null
gate	{ runs, failed }：这次运行中质量门运行的次数、发现新失败的次数

不记录需求内容、代码和对话。

运行之后的事（1.14 起）

同一个文件里还有几种记录，都有 schema（1）、kind、machine、kitVersion、at 和 requirement（{ key, project, name, title }，key 与运行记录相同）。读运行记录的旧版本会跳过它们。

kind	何时写	字段
review	插件代码审查页提交"退回修改"或"评审通过"	review: { verdict: "approved" | "changes_requested", reviewer, items, head }：评审人、意见条数、评审的提交
acceptance	验收清单页提交	acceptance: { verdict: "通过" | "不通过", reviewer, total, passed, failed, unchecked }
merge	req stats、req api stats、req outcome 发现需求的流水线文件（implementation.md、report.md 等）已经在主干（origin/HEAD，没有时 origin/main、main 等）里；或者 req outcome <需求> --merged	merge: { into, commit, mergedAt, how: "files" | "manual" }：commit、mergedAt 是把它带进主干的那次提交（合并提交或压缩合并的提交）；只看本机已有的分支，不 fetch
issue	缺陷需求的 spec 写了 - 引入问题的需求：<目录名>（扫描时发现），或者 req outcome <需求> --issue "<问题>"	issue: { text, by, id }：by 是那个缺陷需求的目录名，手动记的为 null；同一个 id 只算一次

每个需求的 merge 只记一次。评审和验收的全文在需求目录的 code-review.md、acceptance.md 里，随需求分支提交；这里只记结论和数量，用于统计。

统计口径（req stats）

• 一段时间的用量、步骤用时：结束时间在这段时间内的运行。
• 交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。
• 代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。
• 等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。
• token 花在哪（1.13 起，tokens）：这段时间的步骤按 stepId、按 agent 合计 token（输入 + 输出）和占比；返工（design_revise、review_fix、defect_fix、reverify，以及 design_review、code_review 第 2 轮起）的合计和占比；报告了 cachedInputTokens 的，算出输入中来自提示缓存的比例；已完成需求的 token 中位数（按档位）。
• 停下等人的原因（1.12 起）：这段时间结束的运行按 stopKind 计数；更早的记录按结束时的状态推断。确认方案、研发完成等待测试是必要的决定。
• 无人工到提测的比例（1.12 起）：这段时间有进展、已经研发完成或完成的需求中，所有运行都只停在必要决定处的比例。
• 自动处理的比例（1.12 起）：自动处理的次数 ÷（自动处理的次数 + 以中断结束的运行数）；需求方决定、缺陷复现不了不算中断。
• 人工把关和合并后（1.14 起，oversight）：这段时间里的人工代码评审次数、退回修改次数、意见条数，验收次数和不通过次数；"第一次就通过"看每个需求最早的那次评审（验收），它在这段时间里并且是通过；合并进主干的需求数和"完成到合并"的小时数中位数；合并后发现的问题数和涉及的需求数。每个需求一项里的 afterRun 汇总它全部的这类记录（humanReviews、sentBack、lastReview、acceptance、acceptanceFailed、mergedAt、issues）。
• 合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次；同一个需求、同一种、同一时间的事件（问题按 id）只算一次。req stats --export 同时导出这些需求的事件。

req stats --json 和 req api stats 输出同样的对象（schema: 1）：period、machines、active、completed、byType、cycleHours、steps、rework、waits、usage、tokens、oversight、byBuilder、requirements（每个需求一项，字段与 req stats --csv 的列对应）。

本页由仓库中的 contracts/usage-record.md 生成。在 GitHub 上编辑