paseo-req-kit 1.8.0 → 1.9.0-beta.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.9.0-beta.1
+
+1.9 的基础：本机知道自己有哪些需求，记下每次运行的用时和用量，并给程序一个稳定的读取接口。插件（beta.2）和外部系统集成（beta.3）都建在它上面。
+
+### 使用者会看到的变化
+
+- **使用统计 `req stats`**：在任何目录运行，看本机最近 30 天（`--since`、`--month 2026-10`）的统计：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败次数）、等待确认和等待决定的时长、各步骤用时、token 用量和费用、不同 builder 的比较。
+- **给管理方的汇报**：`req stats --report --month 2026-10` 生成汇总（`.md`）和每个需求一行的明细（`.csv`，可以用表格软件打开）。几台机器一起汇报时，每台 `req stats --month 2026-10 --export`，再在一处 `req stats --merge <文件…> --month 2026-10 --report`。
+- **本机的需求索引**：运行过的需求会登记在本机，`req index` 查看。1.9 之前运行过的需求在项目目录运行一次 `req index --rebuild` 补登；`req index --prune` 清理目录已不在的。
+- **`req api`**：给程序用的 JSON 输出：列出本机或当前仓库的需求、一个需求的步骤和质量门、读取功能目录中的文档、统计，以及确认方案、停止、继续、开始测试验证这几个管理操作。Paseo 插件将通过它工作。格式见 `contracts/cli-json.md`。
+
+### 升级须知
+
+- 新增本机文件：`~/.req-kit/index/`（每个需求一个小文件）和 `~/.req-kit/usage/runs.jsonl`（每次运行一行）。只在本机，不记需求内容和代码，不会自动发往任何地方。不想记录时设置环境变量 `REQ_KIT_NO_RECORD=1`。
+- 统计只从升级后的运行开始；之前的运行没有记录。
+- 状态文件、结果文件和提示词都没有变化。设计决定见 ADR 0026。
+
 ## 1.8.0
 
 第一个正式版。汇总 1.8.0-beta.1 到 beta.3 的全部内容（各节见下），并让新机器一条命令就能从零用起来。

package/bin/req.mjs

@@ -30,6 +30,16 @@ const HELP = `req-kit ${version}（${kitRoot}）
   req digest --schedule "0 9 * * 1"
                                让 Paseo 按时间表发送需求总览（例子为每周一 9:00）；取消：req digest --cancel <ID>
 
+使用情况（可以在任何目录运行）：
+  req stats [--since 30d] [--month 2026-10]
+                               本机的使用统计：需求数、交付周期、返工、等待、各步骤用时、用量
+  req stats --report [--out 目录]
+                               生成汇报用的汇总（.md）和每个需求一行的表格（.csv）
+  req stats --export [文件]    导出本机的运行记录；汇总多台机器：req stats --merge <文件…> --report
+  req index [--rebuild [目录…]] [--prune]
+                               本机记录的需求（Paseo 插件据此找到所有需求）；1.9 之前运行过的用 --rebuild 补登
+  req api <命令> …             给程序用的 JSON 输出（见 contracts/cli-json.md）
+
 本机维护：
   req doctor [--no-project]    体检：安装、配置、daemon、当前项目
   req configure                配置向导：选择 builder 和 reviewer 用的 agent
@@ -156,6 +166,15 @@ switch (command) {
   case "digest":
     code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "digest.ts"), ...rest]) : 1;
     break;
+  case "stats":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "stats.ts"), ...rest]) : 1;
+    break;
+  case "index":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "index-cmd.ts"), ...rest]) : 1;
+    break;
+  case "api":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "api.ts"), ...rest]) : 1;
+    break;
   case "notify-test":
     code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "notify-test.ts"), ...rest]) : 1;
     break;

package/contracts/README.md

@@ -10,6 +10,8 @@
 | `decisions.tsv`、`changes.md`、`acceptance.md` 与需求总览 | [feature-files.md](feature-files.md) | 见各文件说明 |
 | `.requirement-pipeline/verify.md` | [verify.md](verify.md) | 自由格式，建议结构见文件 |
 | 外部通知（企业 IM 等）收到的事件 | [notifier-event.md](notifier-event.md) | `schema: 1` |
+| `req api` 的输出（Paseo 插件等程序读取） | [cli-json.md](cli-json.md) | `schema: 1` |
+| `~/.req-kit/index/`、`~/.req-kit/usage/runs.jsonl` | [usage-record.md](usage-record.md) | `schema: 1` |
 
 格式版本的规则：
 

package/contracts/cli-json.md

@@ -0,0 +1,66 @@
+# 给程序用的 JSON 输出：`req api`
+
+1.9.0 起。Paseo 插件和其他程序通过 `req api` 读取需求、执行管理操作，不直接读写状态文件。每个命令输出一行 JSON：
+
+```json
+{ "schema": 1, "kitVersion": "1.9.0", "data": … }
+```
+
+出错时退出码为 1：
+
+```json
+{ "schema": 1, "kitVersion": "1.9.0", "error": { "code": "not_found", "message": "没有找到需求……" } }
+```
+
+`code`：`bad_arguments`（参数不对）、`not_found`（目录或需求不存在）、`not_allowed`（不允许的文件或命令）、`failed`（其他错误）。
+
+`schema` 只在不兼容的修改时增加；新增字段不改变 `schema`，读取方应忽略不认识的字段。
+
+## 命令
+
+| 命令 | `data` |
+| --- | --- |
+| `req api version` | `{ kitVersion, kitRoot, apiSchema, paseo, featuresDir }`：`paseo` 是这个版本支持的 Paseo 范围 |
+| `req api list [--repo <目录>]` | 这个仓库所有工作区中的需求，数组，每项见下面的"需求" |
+| `req api list --all` | 本机记录过的所有需求（[需求索引](usage-record.md)），同上；目录已不在的 `present: false` |
+| `req api status <需求> [--repo <目录>]` | 一个需求的详情，见下面的"详情" |
+| `req api file <需求> <文件> [--repo <目录>]` | `{ featureDir, file, size, truncated, content }`；只能读取功能目录中的文档（见下），最多 512 KB |
+| `req api stats [--since 30d] [--month 2026-10]` | `req stats --json` 的内容，见 [使用记录](usage-record.md) |
+| `req api index [--rebuild <目录>…] [--prune]` | 不带选项：索引的全部条目；`--rebuild`：`{ scanned, registered, pruned, total }` |
+| `req api run <approve\|stop\|resume\|verify> <需求> [--repo <目录>] [选项]` | `{ command, featureDir, ok, exitCode, message }`。在 `--repo`（默认当前目录）中执行与 `req <命令> <需求>` 完全相同的操作；`ok` 为 false 时退出码为 1 |
+
+`<需求>` 的写法与 `req status` 相同：功能目录、目录名或名称中能唯一确定的一部分。需求在为它新建的工作区中开发时，`--repo` 写对话所在的目录或那个工作区都可以。
+
+`req api file` 能读取的文件：`spec.md`、`alignment.md`、`spec-review.md`、`changes.md`、`decisions.tsv`、`design.md`、`design-review.md`、`preview.md`、`contract.md`、`diagnosis.md`、`assessment.md`、`implementation.md`、`progress.md`、`code-review.md`、`handoff.md`、`service-start.md`、`verification.md`、`report.md`、`acceptance.md`、`lessons.tsv`。
+
+## 需求（`list` 的每一项）
+
+| 字段 | 含义 |
+| --- | --- |
+| `key` | 需求在本机的标识（对话所在目录 + 功能目录） |
+| `project` | 项目名：对话所在目录的目录名 |
+| `repo` | 需求所在的目录（有自己的工作区时是那个工作区） |
+| `sourceRepo` / `workspaceId` | 有自己的工作区时：对话所在的目录、Paseo 工作区 ID；否则 null |
+| `featureDir` / `name` / `title` | 功能目录、目录名、需求标题 |
+| `type` / `profile` / `branch` | 需求类型（`defect`、`refactor`、`assessment` 或 null）、档位、分支 |
+| `stage` | 与 `req list` 相同的阶段说明，如"开发中""等待确认方案""待验收" |
+| `status` | 状态文件的 `status`；还没运行过为 null |
+| `running` | 后台进程是否在运行 |
+| `phase` | `develop` / `verify` |
+| `attention` | 需要人处理的事：`approval`（确认方案）、`business`（需求方决定）、`interrupted`（中断，可以继续）、`not_completed`（结束但未完成）；没有为 null |
+| `current` | 正在运行的步骤 `[{ key, title, agentId }]` |
+| `updatedAt` | 最近一次变化的时间 |
+| `usage` | `{ steps, agentMinutes, inputTokens, outputTokens, costUsd }`；没运行过为 null |
+| `present` | 目录是否还在 |
+
+## 详情（`status`）
+
+"需求"的全部字段，另加：
+
+| 字段 | 含义 |
+| --- | --- |
+| `files` | 功能目录中存在的、可以用 `req api file` 读取的文件 |
+| `run` | `{ attempt, startedAt, updatedAt, pid, phaseMode, stopReason, outcome, queuedSince, verifyAt, approval, originAgentId }`；没运行过为 null |
+| `steps` | 每个步骤一项：`{ key, stepId, title, phase, attempt, round, agentId, startedAt, endedAt, minutes, outcome, result, error, usage }`；`title` 是给人看的名称（如"代码评审（第 2 轮）"），`result` 是结论的文字（如"需要修改"） |
+| `gate` | 质量门：状态文件中的 `gate` |
+| `joint` | 联合需求的其他仓库：`[{ name, slug, repo, sourceRepo, branch, workspaceId, gate }]` |

package/contracts/usage-record.md

@@ -0,0 +1,48 @@
+# 本机的需求索引与使用记录
+
+1.9.0 起，引擎在本机配置目录（默认 `~/.req-kit`，可用 `REQ_KIT_HOME` 改变）下记两样东西。它们只在这台机器上，不提交进任何仓库，也不会自动发往任何地方。环境变量 `REQ_KIT_NO_RECORD=1` 时两样都不记（评估运行就是这样）。
+
+## 需求索引 `index/<key>.json`
+
+每个在本机运行过的需求一个文件，记录它在哪里，供 `req api list --all` 和 Paseo 插件找到本机所有的需求。需求的阶段、进度仍然现场从功能目录读取（ADR 0010）。
+
+```json
+{
+  "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`）和功能目录算出。`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 }` |
+| `run` | `{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason }`；`status` 是运行结束时的状态，`outcome` 是完成时报告的结论 |
+| `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 }`：这次运行中质量门运行的次数、发现新失败的次数 |
+
+不记录需求内容、代码和对话。
+
+## 统计口径（`req stats`）
+
+- 一段时间的用量、步骤用时：结束时间在这段时间内的运行。
+- 交付周期：需求第一次开始到完成（最后一次运行以"已完成"结束）的小时数，用这个需求的全部运行，算在完成的那段时间。
+- 代码评审轮数、缺陷修复轮数：不同的（尝试、轮次、仓库）个数；评审分方向或评审小组的几个成员算一轮。
+- 等待：相邻两次运行之间的间隔，按前一次结束时的状态归类：等待确认方案、等待需求方决定、研发完成到开始测试验证、中断到继续。
+- 合并多台机器的导出时，同一机器、同一需求、同一开始时间的运行只算一次。
+
+`req stats --json` 和 `req api stats` 输出同样的对象（`schema: 1`）：`period`、`machines`、`active`、`completed`、`byType`、`cycleHours`、`steps`、`rework`、`waits`、`usage`、`byBuilder`、`requirements`（每个需求一项，字段与 `req stats --csv` 的列对应）。

package/docs/adr/0026-machine-records-and-api.md

@@ -0,0 +1,23 @@
+# 0026 本机的需求索引、使用记录和 req api
+
+- 状态：已采纳（补充 [0010](0010-generated-feature-overview.md)：仓库内的总览仍现场生成；[0014](0014-notifier-slot.md)：通知槽不变）
+
+## 背景
+
+1.9 要做两件依赖同一份数据的事：Paseo 插件在网页端列出本机所有项目的需求、做确认和停止这类管理操作；管理方要定期看到 req-kit 的使用情况（多少需求、多快、返工多少、花了多少）。在此之前，需求的状态分散在各仓库各工作区的功能目录里，`req list` 只看得到当前仓库；用时和用量只在每个需求的状态文件中，没有跨需求的汇总；`req list`、`req status` 只输出给人看的文字，程序要用只能解析文字或直接读状态文件，后者把状态文件的内部格式变成了对外约定。
+
+## 决定
+
+- **需求索引**：引擎每次写状态文件时，确认本机配置目录下的 `index/<key>.json` 记着这个需求在哪里（目录、功能目录、对话所在目录、工作区），一个需求一个文件，几个流水线同时运行也不会互相覆盖。索引只记位置，阶段和进度仍然现场从功能目录读取，所以不会和实际情况不一致。
+- **使用记录**：每次运行（后台进程从开始到结束）结束时向 `usage/runs.jsonl` 追加一行：步骤、用时、用量、质量门、结束时的状态。按运行而不是按需求记，追加即可，不用改写旧记录；需求层面的数字（交付周期、评审轮数、等待时长）在统计时从同一需求的各次运行算出。
+- **只在本机，不自动上报**：两样都不提交进仓库，也不发往任何地方；不记需求内容和代码。汇总给管理方时由人导出（`req stats --export`）再合并（`--merge`）；之后定下汇总通道时，用 1.9 的集成模块订阅"运行结束"，数据格式不变。
+- **`req stats`**：Markdown 汇总、JSON、每个需求一行的 CSV，`--report` 生成汇报用的两份文件。
+- **`req api`**：给程序的稳定接口，一行 JSON，带 `schema`。读操作（list、status、file、stats、index）不改变任何东西；管理操作 `req api run <approve|stop|resume|verify>` 就是在相应目录执行 `req <命令>`，引擎仍是唯一修改状态的一方。`file` 只能读功能目录中的文档白名单。
+- **评估和测试不进记录**：`REQ_KIT_NO_RECORD=1` 关闭记录，评估运行设置它；测试把本机配置目录指向临时目录。
+
+## 影响
+
+- 插件和脚本只依赖 `contracts/cli-json.md`，状态文件的内部格式可以继续演进。
+- 1.9 之前运行过的需求不在索引里，需要 `req index --rebuild` 补登；删掉的目录在索引里显示为"已移除"，`--prune` 清理。
+- 记录是尽力而为的：写失败不影响流水线，被强制结束（kill -9、断电）的运行没有记录，统计会少算这次运行。
+- 主机名写进每条记录，用于合并多台机器的数据时区分来源。

package/docs/adr/README.md

@@ -27,3 +27,4 @@ req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR
 - [0023 需求类型、质量门、按切片实现](0023-types-gate-slices.md)
 - [0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则](0024-confirm-early-review-axes.md)
 - [0025 联合需求：一个需求同时改几个仓库](0025-joint-requirements.md)
+- [0026 本机的需求索引、使用记录和 req api](0026-machine-records-and-api.md)

package/docs/guide//345/256/211/350/243/205/344/270/216/345/215/207/347/272/247.md

@@ -125,6 +125,8 @@ node install.mjs --configure
 | `req upgrade` | 升级到最新版本 |
 | `req notify-test` | 给外部通知发测试消息 |
 | `req digest` | 项目的需求总览；`--notify` 发到外部通知，`--schedule "0 9 * * 1"` 每周一 9 点自动发送 |
+| `req stats` | 本机的使用统计；`--report --month 2026-10` 生成汇报用的文件，`--export` / `--merge` 汇总多台机器 |
+| `req index --rebuild` | 把 1.9 之前运行过的需求登记进本机的需求索引（Paseo 插件据此列出所有需求） |
 
 `<需求>` 可以只写名称中能唯一确定的一部分，如 `sms-login`。`req help` 查看全部。不加 PATH 也可以用完整路径 `~/.req-kit/bin/req`（Windows 为 `%USERPROFILE%\.req-kit\bin\req.cmd`）。
 

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -275,6 +275,16 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 `req digest` 在项目目录中列出所有工作区里的需求，按"需要处理、待验收、开发中、对齐中、已验收（最近 7 天）"分组，附用时与用量。`--notify` 同时发给外部通知（事件类型 `digest`）；`--schedule "<cron>"` 让 Paseo 按时间表（本机时区）启动一个短暂的 agent 执行 `req digest --notify`，例如每周一 9 点：`req digest --schedule "0 9 * * 1"`；取消：`req digest --cancel <定时任务 ID>`。
 
+## 使用统计
+
+1.9.0 起，每次流水线运行结束时，引擎在本机的 `~/.req-kit/usage/runs.jsonl` 追加一条记录：各步骤的用时和用量、质量门、评审和缺陷轮数、结束时的状态（格式见 [使用记录](../../contracts/usage-record.md)）。只记在本机，不记需求内容和代码，也不会自动发往任何地方。
+
+- `req stats`：最近 30 天的统计（`--since 2w`、`--since 2026-10-01`、`--month 2026-10`）：有进展和完成的需求数、交付周期、返工（评审轮数、需要缺陷修复的占比、质量门失败）、各种等待的时长、各步骤用时、用量，以及不同 builder 的比较。`--json`、`--csv` 输出机器可读的格式。
+- `req stats --report --month 2026-10 [--out 目录]`：生成给管理方汇报用的两份文件：`req-kit-usage-2026-10.md`（汇总）和 `.csv`（每个需求一行，可以用表格软件打开）。
+- 几台机器一起汇报：每台机器运行 `req stats --month 2026-10 --export`，得到 `req-kit-usage-<主机名>-<日期>.jsonl`；把这些文件放到一起，运行 `req stats --merge <文件…> --month 2026-10 --report`。
+
+本机的需求索引 `~/.req-kit/index/` 记录每个运行过的需求在哪个目录，Paseo 插件据此在一个页面列出本机所有项目的需求。1.9 之前运行过的需求不在索引里，在项目目录运行一次 `req index --rebuild` 补登；目录删掉后用 `req index --prune` 清理。
+
 ## 团队配置
 
 几台机器、多个项目共用的设置（统一的模型、评审小组、超时、要求的 req-kit 版本）可以放在一份团队配置里。把它放进一个团队共用的 git 仓库，各台机器克隆下来，在本机配置 `~/.req-kit/config.json` 中写上它的路径（绝对路径，或相对 `~/.req-kit/` 的路径）：

package/engine/src/api.ts

@@ -0,0 +1,397 @@
+// `req api`: machine-readable output for programs (the Paseo plugin, scripts), 1.9.
+// The format is a contract (contracts/cli-json.md): every command prints one JSON object,
+//   { "schema": 1, "kitVersion": "…", "data": … }        exit 0
+//   { "schema": 1, "kitVersion": "…", "error": { "code", "message" } }   exit 1
+//
+//   req api version
+//   req api list [--all] [--repo <dir>]
+//   req api status <需求> [--repo <dir>]
+//   req api file <需求> <文件> [--repo <dir>]
+//   req api stats [--since 30d] [--month 2026-10]
+//   req api index [--rebuild <dir>...] [--prune]
+//   req api run <approve|stop|resume|verify> <需求> [--repo <dir>] [其他选项]
+//
+// Reading never changes anything. `run` performs the same command as `req <command>` in that
+// directory, so the engine stays the only one that changes a requirement's state.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resultText, stepName } from "./control.js";
+import { FEATURES_DIR, findWorktreeRun, listFeatures, resolveFeatureArg, summarize } from "./features.js";
+import { KIT_ROOT, kitVersion } from "./locations.js";
+import { pruneIndex, readIndex, registerRequirement, requirementKey } from "./records.js";
+import { isAlive, type PipelineState, readState, statePath, type StepRecord } from "./state.js";
+import { parsePeriod, summarizeRuns } from "./stats.js";
+import { readRuns, runsFile } from "./records.js";
+import { totals } from "./usage.js";
+
+export const API_SCHEMA = 1;
+
+export class ApiError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Documents a program may read from a feature directory (`req api file`). */
+export const READABLE_FILES = [
+  "spec.md",
+  "alignment.md",
+  "spec-review.md",
+  "changes.md",
+  "decisions.tsv",
+  "design.md",
+  "design-review.md",
+  "preview.md",
+  "contract.md",
+  "diagnosis.md",
+  "assessment.md",
+  "implementation.md",
+  "progress.md",
+  "code-review.md",
+  "handoff.md",
+  "service-start.md",
+  "verification.md",
+  "report.md",
+  "acceptance.md",
+  "lessons.tsv",
+] as const;
+
+const MAX_FILE_BYTES = 512 * 1024;
+
+export type Attention = "approval" | "business" | "interrupted" | "not_completed" | null;
+
+/** What a person needs to do about a requirement, if anything. */
+export function attentionOf(state: Pick<PipelineState, "status" | "pid" | "outcome"> | null): Attention {
+  if (!state) return null;
+  if (state.status === "waiting_for_approval") return "approval";
+  if (state.status === "waiting_for_business") return "business";
+  if (state.status === "failed" || (state.status === "running" && !isAlive(state.pid))) return "interrupted";
+  if (state.status === "completed" && state.outcome === "not_completed") return "not_completed";
+  return null;
+}
+
+function usageOf(state: PipelineState | null) {
+  if (!state || state.history.length === 0) return null;
+  const t = totals(state.history);
+  return { steps: t.steps, agentMinutes: Math.round(t.agentMinutes * 10) / 10, inputTokens: t.inputTokens, outputTokens: t.outputTokens, costUsd: t.costUsd };
+}
+
+function readStateSafe(repo: string, featureDir: string): PipelineState | null {
+  try {
+    return readState(statePath(repo, featureDir));
+  } catch {
+    return null;
+  }
+}
+
+function currentSteps(state: PipelineState | null) {
+  if (!state || state.status !== "running" || !isAlive(state.pid)) return [];
+  return state.history.filter((h) => h.outcome === "running").map((h) => ({ key: h.key, title: stepName(h, state), agentId: h.agentId }));
+}
+
+export interface ListItem {
+  key: string;
+  project: string;
+  repo: string;
+  sourceRepo: string | null;
+  workspaceId: string | null;
+  featureDir: string;
+  name: string;
+  title: string;
+  type: string | null;
+  profile: string | null;
+  branch: string | null;
+  /** Plain-language stage, as `req list` shows it. */
+  stage: string;
+  /** The state file's status; null before the first run. */
+  status: string | null;
+  running: boolean;
+  phase: string | null;
+  attention: Attention;
+  current: Array<{ key: string; title: string; agentId: string }>;
+  updatedAt: string;
+  usage: ReturnType<typeof usageOf>;
+  /** False when the index still lists a requirement whose directory is gone. */
+  present: boolean;
+}
+
+function item(repo: string, branch: string | null, featureDir: string, extra: { sourceRepo: string | null; workspaceId: string | null; project: string }): ListItem | null {
+  const name = path.basename(featureDir);
+  const summary = summarize({ path: repo, branch }, name);
+  if (!summary) return null;
+  const state = readStateSafe(repo, featureDir);
+  return {
+    key: requirementKey(extra.sourceRepo ?? repo, featureDir),
+    project: extra.project,
+    repo,
+    sourceRepo: extra.sourceRepo,
+    workspaceId: extra.workspaceId ?? state?.worktree?.workspaceId ?? null,
+    featureDir: summary.featureDir,
+    name,
+    title: summary.title,
+    type: state?.type ?? null,
+    profile: summary.profile ?? state?.profile ?? null,
+    branch: state?.branch ?? summary.branch,
+    stage: summary.stage,
+    status: state?.status ?? null,
+    running: !!state && state.status === "running" && isAlive(state.pid),
+    phase: state?.phase ?? null,
+    attention: attentionOf(state),
+    current: currentSteps(state),
+    updatedAt: summary.updatedAt,
+    usage: usageOf(state),
+    present: true,
+  };
+}
+
+/** Requirements of the repository at `repo` (all its worktrees), or of the whole machine. */
+export function apiList(input: { repo: string; all: boolean }): ListItem[] {
+  if (!input.all) {
+    const repo = fs.realpathSync(input.repo);
+    return listFeatures(repo)
+      .map((f) => {
+        const state = readStateSafe(f.worktree, f.featureDir);
+        const source = state?.worktree?.sourceRepo ?? null;
+        return item(f.worktree, f.branch, f.featureDir, { sourceRepo: source, workspaceId: state?.worktree?.workspaceId ?? null, project: path.basename(source ?? repo) });
+      })
+      .filter((x): x is ListItem => x !== null);
+  }
+  const out: ListItem[] = [];
+  for (const e of readIndex()) {
+    const found = e.present ? item(e.repo, null, e.featureDir, { sourceRepo: e.sourceRepo, workspaceId: e.workspaceId, project: e.project }) : null;
+    out.push(
+      found ?? {
+        key: e.key,
+        project: e.project,
+        repo: e.repo,
+        sourceRepo: e.sourceRepo,
+        workspaceId: e.workspaceId,
+        featureDir: e.featureDir,
+        name: path.basename(e.featureDir),
+        title: path.basename(e.featureDir),
+        type: null,
+        profile: null,
+        branch: null,
+        stage: "已移除（目录不在了）",
+        status: null,
+        running: false,
+        phase: null,
+        attention: null,
+        current: [],
+        updatedAt: e.registeredAt,
+        usage: null,
+        present: false,
+      },
+    );
+  }
+  return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** The repository and feature directory a requirement argument names, as `req status` resolves it. */
+export function locate(repoArg: string, feature: string): { repo: string; featureDir: string; sourceRepo: string | null } {
+  if (!fs.existsSync(repoArg)) throw new ApiError("not_found", `目录不存在：${repoArg}`);
+  const repo = fs.realpathSync(repoArg);
+  let here: string | null = null;
+  try {
+    here = resolveFeatureArg(repo, feature);
+  } catch {
+    here = null;
+  }
+  if (here && fs.existsSync(statePath(repo, here))) return { repo, featureDir: here, sourceRepo: null };
+  const away = findWorktreeRun(repo, here ?? feature);
+  if (away) return { repo: away.repo, featureDir: away.featureDir, sourceRepo: repo };
+  if (here) return { repo, featureDir: here, sourceRepo: null };
+  throw new ApiError("not_found", `没有找到需求"${feature}"（${repo}）`);
+}
+
+function stepJson(h: StepRecord, state: PipelineState) {
+  const minutes = Math.max(0, ((h.endedAt ? new Date(h.endedAt) : new Date()).getTime() - new Date(h.startedAt).getTime()) / 60_000);
+  return {
+    key: h.key,
+    stepId: h.stepId,
+    title: stepName(h, state),
+    phase: h.phase ?? null,
+    attempt: h.attempt,
+    round: h.round,
+    agentId: h.agentId,
+    startedAt: h.startedAt,
+    endedAt: h.endedAt,
+    minutes: Math.round(minutes * 10) / 10,
+    outcome: h.outcome,
+    result: h.outcome === "completed" ? resultText(h) : null,
+    error: h.error,
+    usage: h.usage ?? null,
+  };
+}
+
+export function apiStatus(repoArg: string, feature: string) {
+  const { repo, featureDir, sourceRepo } = locate(repoArg, feature);
+  const state = readStateSafe(repo, featureDir);
+  const source = sourceRepo ?? state?.worktree?.sourceRepo ?? null;
+  const base = item(repo, state?.branch ?? null, featureDir, { sourceRepo: source, workspaceId: state?.worktree?.workspaceId ?? null, project: path.basename(source ?? repo) });
+  if (!base) throw new ApiError("not_found", `${featureDir} 中没有 spec.md`);
+  const dir = path.join(repo, featureDir);
+  return {
+    ...base,
+    files: READABLE_FILES.filter((f) => fs.existsSync(path.join(dir, f))),
+    run: state
+      ? {
+          attempt: state.attempt,
+          startedAt: state.startedAt,
+          updatedAt: state.updatedAt,
+          pid: state.pid,
+          phaseMode: state.phases?.mode ?? null,
+          stopReason: state.stopReason,
+          outcome: state.outcome,
+          queuedSince: state.queuedSince ?? null,
+          verifyAt: state.verifyAt ?? null,
+          approval: state.approval ?? null,
+          originAgentId: state.originAgentId,
+        }
+      : null,
+    steps: state ? state.history.map((h) => stepJson(h, state)) : [],
+    gate: state?.gate ?? null,
+    joint: (state?.joint ?? []).map((j) => ({ name: j.name, slug: j.slug, repo: j.repo, sourceRepo: j.sourceRepo, branch: j.branch, workspaceId: j.workspaceId, gate: j.gate ?? null })),
+  };
+}
+
+export function apiFile(repoArg: string, feature: string, file: string) {
+  if (!(READABLE_FILES as readonly string[]).includes(file)) {
+    throw new ApiError("not_allowed", `只能读取这些文件：${READABLE_FILES.join("、")}`);
+  }
+  const { repo, featureDir } = locate(repoArg, feature);
+  const full = path.join(repo, featureDir, file);
+  if (!fs.existsSync(full)) throw new ApiError("not_found", `${featureDir} 中没有 ${file}`);
+  const size = fs.statSync(full).size;
+  const buf = fs.readFileSync(full);
+  return { featureDir, file, size, truncated: size > MAX_FILE_BYTES, content: buf.subarray(0, MAX_FILE_BYTES).toString("utf8") };
+}
+
+/** Registers the requirements that have run in these directories' repositories (all worktrees). */
+export function apiIndex(input: { rebuild: string[]; prune: boolean }) {
+  let registered = 0;
+  const dirs = new Set(input.rebuild.map((d) => path.resolve(d)));
+  for (const e of readIndex()) if (input.rebuild.length > 0 && e.present) dirs.add(e.sourceRepo ?? e.repo);
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const f of listFeatures(dir)) {
+      const state = readStateSafe(f.worktree, f.featureDir);
+      if (!state) continue;
+      registerRequirement({ repo: f.worktree, featureDir: f.featureDir, worktree: state.worktree ?? null });
+      registered++;
+    }
+  }
+  const pruned = input.prune ? pruneIndex() : 0;
+  return { scanned: [...dirs], registered, pruned, total: readIndex().length };
+}
+
+const RUNNABLE = ["approve", "stop", "resume", "verify"] as const;
+
+/** Runs `req <command> <需求>` where people would, and reports what it said. */
+export function apiRun(command: string, repoArg: string, feature: string, extra: string[]) {
+  if (!(RUNNABLE as readonly string[]).includes(command)) throw new ApiError("not_allowed", `只能执行：${RUNNABLE.join("、")}`);
+  if (!fs.existsSync(repoArg)) throw new ApiError("not_found", `目录不存在：${repoArg}`);
+  const cwd = fs.realpathSync(repoArg);
+  // Not from a chat: the run keeps reporting to the chat that started it.
+  const env = { ...process.env };
+  delete env.PASEO_AGENT_ID;
+  delete env.PASEO_AGENT_CWD;
+  const r = spawnSync(process.execPath, [path.join(KIT_ROOT, "bin", "req.mjs"), command, feature, ...extra], {
+    cwd,
+    env,
+    encoding: "utf8",
+    timeout: 180_000,
+    windowsHide: true,
+  });
+  const output = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+  return { command, featureDir: feature, ok: r.status === 0, exitCode: r.status, message: r.error ? r.error.message : output };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+function option(argv: string[], name: string): string | null {
+  const i = argv.indexOf(name);
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  if (v === undefined || v.startsWith("--")) throw new ApiError("bad_arguments", `${name} 后面要写值`);
+  argv.splice(i, 2);
+  return v;
+}
+
+function flag(argv: string[], name: string): boolean {
+  const i = argv.indexOf(name);
+  if (i < 0) return false;
+  argv.splice(i, 1);
+  return true;
+}
+
+export function apiMain(argvIn: string[], cwd = process.cwd()): unknown {
+  const argv = [...argvIn];
+  const command = argv.shift();
+  const repo = option(argv, "--repo") ?? cwd;
+  const need = (what: string) => {
+    const v = argv.shift();
+    if (!v || v.startsWith("--")) throw new ApiError("bad_arguments", `缺少${what}`);
+    return v;
+  };
+  switch (command) {
+    case "version":
+      return {
+        kitVersion: kitVersion(),
+        kitRoot: KIT_ROOT,
+        apiSchema: API_SCHEMA,
+        paseo: (JSON.parse(fs.readFileSync(path.join(KIT_ROOT, "package.json"), "utf8")) as { reqKit?: { paseo?: string } }).reqKit?.paseo ?? null,
+        featuresDir: FEATURES_DIR.split(path.sep).join("/"),
+      };
+    case "list":
+      return apiList({ repo, all: flag(argv, "--all") });
+    case "status":
+      return apiStatus(repo, need("需求"));
+    case "file": {
+      const feature = need("需求");
+      return apiFile(repo, feature, need("文件名"));
+    }
+    case "stats": {
+      const since = option(argv, "--since");
+      const month = option(argv, "--month");
+      return summarizeRuns(readRuns(runsFile()), parsePeriod({ since, month }));
+    }
+    case "index": {
+      const prune = flag(argv, "--prune");
+      const rebuild: string[] = [];
+      if (flag(argv, "--rebuild")) {
+        while (argv[0] && !argv[0].startsWith("--")) rebuild.push(argv.shift()!);
+        if (rebuild.length === 0) rebuild.push(cwd);
+      }
+      return rebuild.length > 0 || prune ? apiIndex({ rebuild, prune }) : readIndex();
+    }
+    case "run": {
+      const what = need("命令（approve、stop、resume、verify）");
+      return apiRun(what, repo, need("需求"), argv.splice(0));
+    }
+    default:
+      throw new ApiError("bad_arguments", `没有 "${command ?? ""}" 这个 api 命令。可用：version、list、status、file、stats、index、run`);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  let code = 0;
+  let out: Record<string, unknown>;
+  try {
+    out = { schema: API_SCHEMA, kitVersion: kitVersion(), data: apiMain(process.argv.slice(2)) };
+    const data = out.data as { ok?: boolean } | null;
+    if (data && data.ok === false) code = 1;
+  } catch (error) {
+    const e = error as Error & { code?: string };
+    out = { schema: API_SCHEMA, kitVersion: kitVersion(), error: { code: error instanceof ApiError ? e.code : "failed", message: e.message } };
+    code = 1;
+  }
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+  process.exit(code);
+}

package/engine/src/control.ts

@@ -31,7 +31,7 @@ const RESULT_TEXT: Record<string, string> = {
   not_completed: "未完成",
 };
 
-function resultText(record: StepRecord): string {
+export function resultText(record: StepRecord): string {
   const r = record.result ?? {};
   if (typeof r.has_runnable_service === "boolean") return r.has_runnable_service ? "完成（项目有常驻服务）" : "完成";
   if (typeof r.started === "boolean") return r.started ? "服务启动成功" : "服务启动失败";
@@ -42,7 +42,7 @@ function resultText(record: StepRecord): string {
   return "完成";
 }
 
-function stepName(record: StepRecord, state: Pick<PipelineState, "type" | "joint"> | null = null): string {
+export function stepName(record: StepRecord, state: Pick<PipelineState, "type" | "joint"> | null = null): string {
   const [base, slug] = record.key.split("@");
   const repo = slug ? (state?.joint ?? []).find((j) => j.slug === slug)?.name ?? slug : null;
   const title = `${stepTitle(state?.type, record.stepId)}${repo ? `·${repo}` : ""}`;