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

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [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 的全部内容（各节见下），并让新机器一条命令就能从零用起来。
+
+### 使用者会看到的变化
+
+- **一键安装改用站点地址**：
+  - macOS、Linux、Git Bash、WSL：`curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh`
+  - Windows PowerShell：`irm https://paseo-req-kit.vercel.app/install.ps1 | iex`
+  - 原来的 GitHub 地址仍然可用。
+- **一键安装会准备好 Paseo**：
+  - 新机器上没有 Paseo 时，脚本先安装与这个版本匹配的 Paseo 命令行（`@getpaseo/cli@~0.11.0`），开启它自带的网页界面，再启动 daemon。装完在浏览器打开 `http://localhost:6767/` 就能用 Paseo 对话，不必另装桌面版。
+  - 已有 `paseo` 命令时不重装：核对版本（不在支持范围内时提醒），开启网页界面；daemon 没在运行就启动。daemon 已在运行而网页界面是刚开启的，只提示 `paseo daemon restart`，不自动重启，因为重启会中断正在运行的 agent。
+  - 只有桌面版 Paseo 管理的 daemon（没有 `paseo` 命令）时什么都不装，只提示在桌面版中开启网页界面。
+  - 一个 agent 命令行（Claude Code、Codex、OpenCode、Pi、Copilot）都没有时会提醒。
+  - 不想让脚本动 Paseo 时加 `--skip-paseo`（PowerShell：`$ReqKitSkipPaseo = $true`）。
+- **1.8 的内容**：
+  - 按需求类型分流（缺陷先复现、重构先锁行为、评估只出报告）。
+  - 质量门、按切片实现、范围检查、关联仓库。
+  - 带例子的验收标准、开工前确认方案、评审分规格和规范两个方向、反复出现的问题变成规则。
+  - 前后端联合需求。
+
+### 升级须知
+
+- 这是 npm 上的第一个 `latest` 版本：`npm i -g paseo-req-kit` 和不带 `--beta` 的一键安装从此装正式版。在 beta 通道的（`req upgrade --beta` 或 `@beta`）照常收到之后的 beta 版；没有更新的 beta 时，一键安装的 `--beta` 装正式版，而不是更早的 1.8.0-beta.3。
+- 从 1.7.x 或更早升级：依次看下面 1.8.0-beta.1 到 beta.3 的升级须知。最重要的是在每个项目主目录的对话中再运行一次 `/req-setup`，写入检查命令、术语表和范例文件。
+- 从 1.8.0-beta.3 升级：引擎和提示词没有变化，只改了安装脚本和文档。
+
 ## 1.8.0-beta.3
 
 联合需求：前端和后端分在两个仓库的需求，可以作为一个需求一起做。

package/README.md

@@ -56,19 +56,19 @@ AI  ▸ 结论：已完成，可以验收。6 条验收标准全部通过……
 
 ## 快速开始
 
-在运行 Paseo daemon 的机器上（需要 Node.js 22+）：
+在要运行 Paseo 的机器上（需要 Node.js 22+；还没有 Paseo 也可以，脚本会装好）：
 
 ```bash
 # macOS、Linux、Windows 的 Git Bash 或 WSL
-curl -fsSL https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.sh | sh
+curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh
 ```
 
 ```powershell
 # Windows PowerShell
-irm https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.ps1 | iex
+irm https://paseo-req-kit.vercel.app/install.ps1 | iex
 ```
 
-安装脚本会检查环境、安装 `paseo-req-kit`、为 Claude Code / Codex / OpenCode / Pi 安装 `/req` 等 skill，并引导你为 builder 和 reviewer 选择 agent。再次运行即升级。然后：
+安装脚本会检查环境、安装 `paseo-req-kit`；没有 Paseo 时安装 Paseo 命令行，开启它自带的网页界面（`http://localhost:6767/`）并启动 daemon；为 Claude Code / Codex / OpenCode / Pi 安装 `/req` 等 skill，并引导你为 builder 和 reviewer 选择 agent。再次运行即升级。然后：
 
 1. `req doctor` —— 检查 daemon、agent 模式和额度；
 2. 在项目的 Paseo 对话中运行 `/req-setup` —— 接入项目（每个项目一次）；

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

@@ -29,7 +29,7 @@ Windows 上 `~` 即 `%USERPROFILE%`（如 `D:\Users\<用户名>`）。安装器
 
 | 项目 | 要求 | 如何确认 |
 | --- | --- | --- |
-| Paseo | 0.11，daemon 在运行 | Paseo 桌面端能正常对话；默认地址 `ws://127.0.0.1:6767/ws` |
+| Paseo | 0.11，daemon 在运行（一键安装会在没有时安装 Paseo 命令行并启动） | Paseo 桌面端能正常对话，或浏览器打开 `http://localhost:6767/`；默认地址 `ws://127.0.0.1:6767/ws` |
 | Node.js | 22 或更新 | `node -v` |
 | npm | Node.js 自带；公司网络需配置镜像（`npm config get registry`） | `npm -v` |
 | git | 近期版本（只有 git 方式安装时需要） | `git --version` |
@@ -45,15 +45,24 @@ Windows 上 `~` 即 `%USERPROFILE%`（如 `D:\Users\<用户名>`）。安装器
 
 ```bash
 # macOS、Linux、Windows 的 Git Bash 或 WSL
-curl -fsSL https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.sh | sh
+curl -fsSL https://paseo-req-kit.vercel.app/install.sh | sh
 ```
 
 ```powershell
 # Windows PowerShell（不受脚本执行策略限制）
-irm https://raw.githubusercontent.com/yiyisf/paseo-req-kit/main/install.ps1 | iex
+irm https://paseo-req-kit.vercel.app/install.ps1 | iex
 ```
 
-脚本依次：检查 Node.js 22+、npm、git；从 npm 安装 `paseo-req-kit`，npm 上没有时改用 GitHub Release 的安装包；npm 全局目录不可写时装到 `~/.req-kit/npm`（不需要 sudo）；运行 `req setup`；本机配置还没填时运行 `req configure`；最后提示把 `req` 加入 PATH（如需要）。选项：`install.sh` 写在 `sh -s --` 之后（`--beta`、`--version <版本>`、`--from npm|release`、`--no-configure`）；`install.ps1` 用变量（`$ReqKitBeta = $true; irm … | iex`，还有 `$ReqKitVersion`、`$ReqKitFrom`、`$ReqKitNoConfigure`）。完成后接着做下面的**第四步**到**第六步**。
+脚本依次：检查 Node.js 22+、npm、git；从 npm 安装 `paseo-req-kit`，npm 上没有时改用 GitHub Release 的安装包；npm 全局目录不可写时装到 `~/.req-kit/npm`（不需要 sudo）；**检查 Paseo**（见下）；运行 `req setup`；本机配置还没填时运行 `req configure`；最后提示把 `req` 加入 PATH（如需要）。选项：`install.sh` 写在 `sh -s --` 之后（`--beta`、`--version <版本>`、`--from npm|release`、`--no-configure`、`--skip-paseo`）；`install.ps1` 用变量（`$ReqKitBeta = $true; irm … | iex`，还有 `$ReqKitVersion`、`$ReqKitFrom`、`$ReqKitNoConfigure`、`$ReqKitSkipPaseo`）。
+
+检查 Paseo 这一步：
+
+- **有 `paseo` 命令**：核对它的版本是否在这个 req-kit 支持的范围内（不在时提醒，不替换）；开启 daemon 自带的网页界面（`paseo daemon config set features.webUi.enabled true`）；daemon 没在运行就 `paseo daemon start`。daemon 已在运行而网页界面是刚开启的，只提示 `paseo daemon restart`，不自动重启——重启会中断正在运行的 agent。
+- **没有 `paseo` 命令，但 daemon 在运行**：通常是桌面版 Paseo 管理的 daemon，什么都不装；需要网页界面时在桌面版中开启。
+- **都没有（新机器）**：用 npm 安装与 req-kit 匹配的 Paseo 命令行（例如 `@getpaseo/cli@~0.11.0`），开启网页界面，启动 daemon。之后在浏览器打开 `http://localhost:6767/` 就能用 Paseo 对话。
+- 最后检查有没有 agent 命令行（Claude Code、Codex、OpenCode、Pi、Copilot），一个都没有时提醒：至少装一个并登录，再运行 `req configure`。
+
+不想让脚本动 Paseo（例如由别人统一管理）时加 `--skip-paseo`。完成后接着做下面的**第四步**到**第六步**。
 
 **也可以用 npm 安装（1.7.0 起）。** 一键安装做的就是这几条命令，Windows 上 `req` 命令由 npm 放进 PATH，不用自己设置：
 
@@ -77,19 +86,19 @@ req doctor --no-project       # 体检
 **第一步：取得程序。** 把要安装的版本放进它自己的版本目录：
 
 ```bash
-git clone --branch 1.8.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.8.0-beta.3
+git clone --branch 1.8.0 --depth 1 https://github.com/yiyisf/paseo-req-kit ~/tools/req-kit/versions/1.8.0
 ```
 
 Windows PowerShell：
 
 ```powershell
-git clone --branch 1.8.0-beta.3 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.8.0-beta.3"
+git clone --branch 1.8.0 --depth 1 https://github.com/yiyisf/paseo-req-kit "$env:USERPROFILE\tools\req-kit\versions\1.8.0"
 ```
 
 **第二步：安装依赖并启用。**
 
 ```bash
-cd ~/tools/req-kit/versions/1.8.0-beta.3
+cd ~/tools/req-kit/versions/1.8.0
 npm install
 node install.mjs
 ```
@@ -116,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/` 的路径）：