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

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.9.0-beta.2
+
+Paseo 插件：在 Paseo 的界面里查看和管理需求。
+
+### 使用者会看到的变化
+
+- **req-kit 插件**（`req plugin install`）：在 Paseo 的网页端、桌面版和手机上都能用。
+  - 侧边栏的"需求"：本机所有项目的需求，按"需要你处理、进行中、待测试验证、最近完成"分组，带待处理的数量。
+  - 需求详情：每一步的状态、用时和结论（点开进入那个步骤的 agent）、质量门、联合需求的各仓库、用量；可以读需求说明、方案、确认预览、提测说明、完成报告等。
+  - 确认方案、停止、继续、开始测试验证：每个都要再确认一次，做的事与终端里的 `req` 命令完全相同。
+  - 每个工作区头部的"需求"按钮和面板、步骤 agent 输入框旁的"需求"按钮、使用统计页、Ctrl+K 中的"需求总览"。
+  - 插件设置中可以打开"只读"，给只看不操作的人用。
+- **安装脚本**最后询问是否安装插件（`--with-plugin` 直接安装，`--no-plugin` 不问；PowerShell 用 `$ReqKitPlugin`）。
+- **修正**：安装脚本判断 Paseo 网页界面是否已开启时，读错了 `paseo daemon config get` 的输出（"已设置"被当成"已开启"）。
+
+### 升级须知
+
+- 插件是可选的。安装时会询问是否打开 Paseo 的插件总开关（`pluginsEnabled`）：插件是不受沙箱限制的代码；req-kit 插件只运行本机的 `req api`，不连接外部服务。
+- 装过插件后，`req setup`、`req upgrade`、`req use` 会自动把插件换成启用的版本。插件随 req-kit 一起发布，不需要单独的 npm 包。
+- 需要 Paseo 0.11。1.9 之前运行过的需求，先在项目目录运行一次 `req index --rebuild`。设计决定见 ADR 0027。
+
+## 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/README.md

@@ -74,6 +74,8 @@ irm https://paseo-req-kit.vercel.app/install.ps1 | iex
 2. 在项目的 Paseo 对话中运行 `/req-setup` —— 接入项目（每个项目一次）；
 3. 在 Paseo 对话中输入 `/req 我想……` —— 开始第一个需求。
 
+想在 Paseo 的界面（网页端、桌面版、手机）里看需求总览和进度、确认方案或停止继续，运行 `req plugin install` 安装 req-kit 的 Paseo 插件。
+
 其他安装方式（npm、离线安装包、git）、各 agent 的配置写法和升级回滚，见 [安装与升级](docs/guide/安装与升级.md)。
 
 ## 工作原理

package/bin/req-plugin.mjs

@@ -0,0 +1,226 @@
+// `req plugin`: the req-kit plugin for Paseo (1.9, ADR 0027).
+//
+//   req plugin install [--yes]   copy the plugin to <kit home>/paseo-plugin and install it in Paseo
+//   req plugin status            whether it is installed and running
+//   req plugin remove            remove it from Paseo
+//
+// The plugin ships inside this package (paseo-plugin/). It is installed from a fixed copy under
+// the kit home, so upgrading or switching req-kit versions only refreshes that copy and reloads
+// the plugin (refreshPlugin, called by install.mjs); the plugin always matches the active version.
+// Turning on Paseo's plugin switch (pluginsEnabled) needs the person's consent: plugins run
+// unsandboxed on this machine.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+export const PLUGIN_ID = "req-kit";
+const KIT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function kitHome(env = process.env) {
+  const override = env.REQ_KIT_HOME?.trim();
+  return override ? path.resolve(override) : path.join(os.homedir(), ".req-kit");
+}
+
+export function stagedDir(home = kitHome()) {
+  return path.join(home, "paseo-plugin");
+}
+
+/** Copies this version's plugin to the fixed directory Paseo installs from. */
+export function stagePlugin(kitRoot = KIT_ROOT, home = kitHome()) {
+  const from = path.join(kitRoot, "paseo-plugin");
+  if (!fs.existsSync(path.join(from, "paseo-plugin.json"))) throw new Error(`这个版本的 req-kit 没有附带 Paseo 插件（${from}）`);
+  const to = stagedDir(home);
+  fs.rmSync(to, { recursive: true, force: true });
+  fs.cpSync(from, to, {
+    recursive: true,
+    filter: (src) => !path.relative(from, src).split(path.sep).includes("node_modules"),
+  });
+  return to;
+}
+
+/** The paseo command: REQ_KIT_PASEO_BIN (tests; empty means none), else paseo on PATH. */
+function paseoCommand(env = process.env) {
+  if (env.REQ_KIT_PASEO_BIN !== undefined) return env.REQ_KIT_PASEO_BIN || null;
+  const cmd = process.platform === "win32" ? "paseo.cmd" : "paseo";
+  return run(cmd, ["--version"], 30_000, env).status === 0 ? cmd : null;
+}
+
+// A .cmd shim on Windows only runs through the shell; quote what the shell would split.
+const WINDOWS = process.platform === "win32";
+const quote = (a) => (WINDOWS && /[\s"&|<>^]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a);
+
+function run(cmd, args, timeout, env = process.env) {
+  return spawnSync(WINDOWS ? quote(cmd) : cmd, WINDOWS ? args.map(quote) : args, { encoding: "utf8", windowsHide: true, timeout, shell: WINDOWS, env });
+}
+
+function paseo(cmd, args, env = process.env) {
+  const r = run(cmd, args, 180_000, env);
+  let json = null;
+  try {
+    json = JSON.parse((r.stdout ?? "").trim());
+  } catch {
+    json = null;
+  }
+  return { ok: r.status === 0, json, text: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+
+function pluginEntry(cmd, env = process.env) {
+  const r = paseo(cmd, ["plugin", "ls", "--json"], env);
+  if (!r.ok) return { error: r.text };
+  const list = Array.isArray(r.json) ? r.json : Array.isArray(r.json?.data) ? r.json.data : [];
+  return { entry: list.find((p) => p.id === PLUGIN_ID) ?? null };
+}
+
+function pluginsEnabled(cmd, env = process.env) {
+  const r = paseo(cmd, ["daemon", "config", "get", "pluginsEnabled", "--json"], env);
+  const value = r.json?.value ?? r.json?.data?.value;
+  return value === true;
+}
+
+function ask(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) =>
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^(y|yes|是|好|可以)$/i.test(answer.trim()));
+    }),
+  );
+}
+
+const say = (s) => console.log(s);
+
+function manualSteps(dir) {
+  say("也可以在 Paseo 中手动安装：");
+  say("  1. 设置 → Plugins → 打开 Enable plugins（插件是不受限制的代码，可以访问这台机器上的文件和进程）");
+  say(`  2. 在 Plugin source 中填：${dir}`);
+}
+
+export async function installPlugin({ yes = false, env = process.env, kitRoot = KIT_ROOT } = {}) {
+  const dir = stagePlugin(kitRoot, kitHome(env));
+  say(`插件文件：${dir}`);
+  const cmd = paseoCommand(env);
+  if (!cmd) {
+    say("没有找到 paseo 命令（桌面版 Paseo 管理的 daemon 通常没有）。");
+    manualSteps(dir);
+    return 1;
+  }
+  if (!pluginsEnabled(cmd, env)) {
+    say("");
+    say("Paseo 的插件总开关（pluginsEnabled）是关着的。");
+    say("插件是受信任、不受沙箱限制的代码：它的后台部分可以访问这台机器上的文件、进程和网络。");
+    say("req-kit 插件只运行本机的 req 命令，不连接任何外部服务。");
+    const agreed = yes || (await ask("打开 Paseo 的插件总开关并安装 req-kit 插件？[y/N] "));
+    if (!agreed) {
+      say("没有安装。之后可以运行 req plugin install（或加 --yes）。");
+      manualSteps(dir);
+      return 1;
+    }
+    const set = paseo(cmd, ["daemon", "config", "set", "pluginsEnabled", "true", "--json"], env);
+    if (!set.ok) {
+      say(`没能打开插件总开关：${set.text}`);
+      manualSteps(dir);
+      return 1;
+    }
+    say("✓ 已打开 Paseo 的插件总开关");
+  }
+  const found = pluginEntry(cmd, env);
+  if (found.error) {
+    say(`读取不了 Paseo 的插件列表：${found.error}`);
+    say("请确认 Paseo daemon 在运行（paseo daemon status）。");
+    return 1;
+  }
+  const r = found.entry ? paseo(cmd, ["plugin", "reload", PLUGIN_ID, "--json"], env) : paseo(cmd, ["plugin", "install", dir, "--json"], env);
+  if (!r.ok) {
+    say(`${found.entry ? "重新加载" : "安装"}失败：${r.text}`);
+    say(`查看插件输出：paseo plugin logs ${PLUGIN_ID}`);
+    return 1;
+  }
+  const after = pluginEntry(cmd, env).entry;
+  if (after?.status === "running") {
+    say(`✓ req-kit 插件${found.entry ? "已更新" : "已安装"}，正在运行。在 Paseo 侧边栏中点"需求"打开。`);
+    return 0;
+  }
+  say(`插件状态：${after?.status ?? "未知"}${after?.error ? `（${after.error}）` : ""}。查看输出：paseo plugin logs ${PLUGIN_ID}`);
+  return 1;
+}
+
+export function pluginStatus({ env = process.env } = {}) {
+  const dir = stagedDir(kitHome(env));
+  const staged = fs.existsSync(path.join(dir, "package.json")) ? JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8")).version : null;
+  say(staged ? `插件文件：${dir}（版本 ${staged}）` : "还没有准备插件文件：运行 req plugin install");
+  const cmd = paseoCommand(env);
+  if (!cmd) {
+    say("没有找到 paseo 命令，无法查看 Paseo 中的状态（在 Paseo 的 设置 → Plugins 中查看）。");
+    return staged ? 0 : 1;
+  }
+  const found = pluginEntry(cmd, env);
+  if (found.error) {
+    say(`读取不了 Paseo 的插件列表：${found.error}`);
+    return 1;
+  }
+  if (!found.entry) {
+    say("Paseo 中没有安装 req-kit 插件：运行 req plugin install");
+    return 1;
+  }
+  say(`Paseo 中的 req-kit 插件：${found.entry.status}${found.entry.error ? `（${found.entry.error}）` : ""}`);
+  if (!pluginsEnabled(cmd, env)) say("注意：Paseo 的插件总开关是关着的（设置 → Plugins → Enable plugins）。");
+  return found.entry.status === "running" ? 0 : 1;
+}
+
+export function removePlugin({ env = process.env } = {}) {
+  const cmd = paseoCommand(env);
+  if (cmd) {
+    const found = pluginEntry(cmd, env);
+    if (found.entry) {
+      const r = paseo(cmd, ["plugin", "remove", PLUGIN_ID, "--json"], env);
+      if (!r.ok) {
+        say(`移除失败：${r.text}`);
+        return 1;
+      }
+      say("✓ 已从 Paseo 移除 req-kit 插件（Paseo 的插件总开关保持原样）");
+    } else say("Paseo 中没有安装 req-kit 插件");
+  } else say("没有找到 paseo 命令：请在 Paseo 的 设置 → Plugins 中移除 req-kit。");
+  fs.rmSync(stagedDir(kitHome(env)), { recursive: true, force: true });
+  return 0;
+}
+
+/**
+ * After a version becomes active (req setup, upgrade, use): if the plugin was installed,
+ * refresh its files from that version and reload it. Quiet and best effort.
+ */
+export function refreshPlugin({ kitRoot = KIT_ROOT, env = process.env, log = () => {} } = {}) {
+  const home = kitHome(env);
+  if (!fs.existsSync(path.join(stagedDir(home), "paseo-plugin.json"))) return false;
+  try {
+    stagePlugin(kitRoot, home);
+  } catch (error) {
+    log(`没能更新 Paseo 插件的文件：${error.message}`);
+    return false;
+  }
+  const cmd = paseoCommand(env);
+  const r = cmd ? paseo(cmd, ["plugin", "reload", PLUGIN_ID, "--json"], env) : null;
+  log(r?.ok ? "Paseo 插件已更新到这个版本" : `Paseo 插件的文件已更新；在 Paseo 中重新加载它：paseo plugin reload ${PLUGIN_ID}（或 设置 → Plugins）`);
+  return true;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [sub = "status", ...rest] = process.argv.slice(2);
+  let code;
+  try {
+    if (sub === "install") code = await installPlugin({ yes: rest.includes("--yes") || rest.includes("-y") });
+    else if (sub === "status") code = pluginStatus();
+    else if (sub === "remove" || sub === "uninstall") code = removePlugin();
+    else {
+      console.error(`没有 "${sub}" 这个子命令。可用：req plugin install [--yes]、req plugin status、req plugin remove`);
+      code = 2;
+    }
+  } catch (error) {
+    console.error(error.message);
+    code = 1;
+  }
+  process.exit(code);
+}

package/bin/req.mjs

@@ -30,6 +30,21 @@ 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）
+
+Paseo 插件（在 Paseo 中查看和管理需求）：
+  req plugin install [--yes]   安装或更新插件；需要时会询问是否打开 Paseo 的插件总开关
+  req plugin status            插件是否在运行
+  req plugin remove            从 Paseo 移除插件
+
 本机维护：
   req doctor [--no-project]    体检：安装、配置、daemon、当前项目
   req configure                配置向导：选择 builder 和 reviewer 用的 agent
@@ -156,6 +171,18 @@ 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 "plugin":
+    code = node([path.join(kitRoot, "bin", "req-plugin.mjs"), ...rest]);
+    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/0027-paseo-plugin.md

@@ -0,0 +1,23 @@
+# 0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作
+
+- 状态：已采纳（建立在 [0026](0026-machine-records-and-api.md) 的需求索引和 `req api` 之上；不改变 [0003](0003-script-engine-not-hub.md)：流程仍由脚本引擎驱动）
+
+## 背景
+
+需求方和项目经理想在 Paseo 的网页端或手机上看到所有需求在哪一步、卡在哪里，并做确认方案、停止、继续这类操作，而不是在对话里问或在终端敲 `req`。Paseo 0.11 有完整的插件机制：界面（侧边栏、页面、工作区面板、按钮、命令中心）、daemon 侧的 RPC 和生命周期事件，同一份界面代码在桌面版、网页端和手机上运行。
+
+## 决定
+
+- **插件只做展示和管理，不参与流程**：每个读取是一次 `req api`，每个管理操作是 `req api run <approve|stop|resume|verify>`，与在终端执行 `req <命令>` 完全相同。插件不读写状态文件，引擎仍是唯一修改需求状态的一方。不提供发起需求（需要在对话中对齐）、编辑需求说明或方案、修改配置、删除。
+- **随 req-kit 一起发布，从固定目录安装**：插件源码在仓库的 `paseo-plugin/`，打进 `paseo-req-kit` 包。`req plugin install` 把当前版本的插件复制到 `~/.req-kit/paseo-plugin`，用 `paseo plugin install <目录>` 安装；之后每次启用版本（setup、upgrade、use）都刷新这个目录并 `paseo plugin reload`。这样插件版本总是和启用的 req-kit 一致，也不需要单独的 npm 包、网络或第二套发布配置。设计时曾考虑第二个 npm 包，Paseo 的目录安装让它变得不必要。
+- **插件总开关要人同意**：Paseo 的 `pluginsEnabled` 默认关闭，插件是不受沙箱限制的代码。`req plugin install` 和安装脚本都先说明再询问，`--yes` / `--with-plugin` 表示同意；移除插件不改动总开关。
+- **只读模式**：Paseo 的插件没有按用户区分的权限，能连上 daemon 的人都能操作。插件设置中的"只读"隐藏管理操作，daemon 侧也拒绝它们。
+- **只依赖 `req api` 的格式**：插件通过本机配置目录的 `active.json` 找到启用的版本并运行它的 `req api`，不引用 req-kit 的内部代码；req-kit 太旧时插件给出升级提示。
+- **界面按 Paseo 的跨平台规则写**：只用 React Native 组件和主题颜色，不用 DOM。插件的界面部分由 CI 用 Paseo 的 SDK 做类型检查（`paseo-plugin/` 的开发依赖），daemon 侧和 `req plugin` 有单元测试；界面效果需要在真实的 Paseo 中检查。
+
+## 影响
+
+- 新增 `req plugin install|status|remove`，安装脚本最后可选安装插件。
+- 列表靠轮询刷新（默认 10 秒，可设置）；daemon 侧把短时间内的多个列表请求合并成一次 `req api list`。
+- 步骤 agent 的"需求"按钮靠 req-kit 给步骤 agent 打的标签（`requirement-pipeline`）找到需求；工作区的"需求"按钮按目录匹配需求。
+- `paseo-plugin/package.json` 的版本必须与 req-kit 相同（测试检查），`paseo-plugin.json` 的 Paseo 范围与 `reqKit.paseo` 相同。

package/docs/adr/README.md

@@ -27,3 +27,5 @@ 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)
+- [0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作](0027-paseo-plugin.md)

package/docs/guide//344/275/277/347/224/250/350/200/205/346/214/207/345/215/227.md

@@ -60,6 +60,8 @@ req-kit 帮你把一个需求从"我想要……"做到"可以验收"：你在 P
 
 也可以不进对话，在终端里用 `req` 命令（需要开发同事装好并加入 PATH，见 [安装与升级](安装与升级.md)）：在项目目录中 `req list` 看所有需求，`req status` 看进度（多个需求时写名称的一部分，如 `req status sms-login`），`req stop`、`req resume` 暂停和继续。
 
+装了 req-kit 插件的话（见 [安装与升级](安装与升级.md) 第 13 节），在 Paseo 侧边栏点"需求"：本机所有项目的需求一页看完，"需要你处理"的排在最前；点开一个需求能看到每一步的进度和用时、读需求说明、方案、确认预览和完成报告，也可以直接确认方案、停止、继续或开始测试验证。网页端、桌面版和手机上都能用。
+
 每个步骤都会出现在这个对话的子 agent 列表里（名字形如"[20261012-sms-login] 6-代码评审 第2轮"），点开可以看到它在做什么。功能目录下的 `progress.md` 按时间记录了每一步的结果。
 
 可能收到的通知（团队接入了企业 IM 的话，这些通知也会发到 IM）：

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`）。
 
@@ -355,3 +357,27 @@ node ~/tools/req-kit/versions/<当前版本>/install.mjs --uninstall
 
 事件的类型和字段见 [contracts/notifier-event.md](../../contracts/notifier-event.md)。通知失败只记日志，不影响流水线。项目配置（`.requirement-pipeline.json`）中的 `notifiers` 会被忽略。
 
+## 13. Paseo 插件（可选）
+
+1.9 起，req-kit 附带一个 Paseo 插件，把需求搬进 Paseo 的界面（网页端、桌面版、手机都能用）：
+
+- 侧边栏的"需求"：本机所有项目的需求，按"需要你处理、进行中、待测试验证、最近完成"分组，带待处理的数量。
+- 需求详情：每一步的状态、用时和结论（点开即进入那个步骤的 agent）、质量门、联合需求的各仓库、用量；可以读需求说明、方案、确认预览、提测说明、完成报告等文档。
+- 管理操作：确认方案、停止、继续、开始测试验证。每个操作都要再确认一次，做的事和终端里的 `req approve`、`req stop`、`req resume`、`req verify` 完全一样，流水线本身不受插件影响。
+- 每个工作区头部的"需求"按钮和面板、步骤 agent 输入框旁的"需求"按钮、使用统计（同 `req stats`），以及 Ctrl+K（macOS 为 ⌘K）中的"需求总览"。
+
+**安装**：在运行 Paseo daemon 的机器上运行
+
+```bash
+req plugin install
+```
+
+它把当前版本的插件复制到 `~/.req-kit/paseo-plugin`，再用 Paseo 的命令行安装。Paseo 的插件总开关（`pluginsEnabled`）默认是关着的：插件是不受沙箱限制的代码，后台部分可以访问这台机器上的文件和进程，所以打开前会先问你（`--yes` 表示同意）。req-kit 插件只运行本机的 `req api`，不连接任何外部服务。一键安装脚本在最后也会问一次是否安装（`--with-plugin` 直接安装，`--no-plugin` 不问）。
+
+没有 `paseo` 命令时（例如只用桌面版 Paseo），在 Paseo 的 设置 → Plugins 中打开 Enable plugins，再在 Plugin source 中填 `~/.req-kit/paseo-plugin` 的完整路径（运行 `req plugin install` 会准备好这个目录并显示路径）。
+
+**更新**：不用单独做。`req setup`、`req upgrade`、`req use` 启用一个版本时，如果装过插件，会把插件文件换成这个版本的并让 Paseo 重新加载，插件总是和启用的 req-kit 版本一致。
+
+**只读**：网页端会给只看不操作的人用时，在 Paseo 的 设置 → Plugins → req-kit 中打开"只读"：不再显示管理操作，插件的后台也会拒绝它们。能连上这台 daemon 的人都能看到插件，Paseo 的插件没有按用户区分的权限。
+
+**其他**：`req plugin status` 看插件是否在运行；`req plugin remove` 从 Paseo 移除（不改插件总开关）。插件需要 req-kit 1.9 和 Paseo 0.11。1.9 之前运行过的需求要先在项目目录运行一次 `req index --rebuild` 才会出现在插件里。插件出问题时：`paseo plugin logs req-kit`。

package/docs/guide//347/273/264/346/212/244/350/200/205/346/214/207/345/215/227.md

@@ -26,6 +26,7 @@
 | 入口、手册、方法 skill、原则 | `npm test` + 对话评估中受影响的剧本（`evals/conversation/`） |
 | 安装器 | `npm test`（在临时 HOME 中测试），并在 Windows 上实际装一次 |
 | 评估用例 | `npm run eval:self-check`（参考实现必须通过隐藏验收） |
+| Paseo 插件（`paseo-plugin/`） | `npm test`（插件后台和 `req plugin`）；在 `paseo-plugin/` 中 `npm install && npm run typecheck`（CI 的 plugin 任务也会做）；用 `req plugin install` 装到一台 Paseo 上，在网页端和手机宽度下看一遍，切换一次深色主题 |
 
 提示词改动以评估结果为准：如实率（不夸大）不能下降；隐藏验收通过率、用时、轮次与上一次对比，变差时说明原因。
 
@@ -60,7 +61,7 @@
 
 没有使用 changesets 等发布工具（见 ADR 0013）：发布频率低，CHANGELOG 由人写更贴近使用者。
 
-**对外约定**：通知事件（`contracts/notifier-event.md`）由各团队自己的 IM 模块读取，同一 `schema` 内只增加字段；`req` 的子命令和参数会被写进各团队的使用说明，改名时保留旧名一个主版本。
+**对外约定**：通知事件（`contracts/notifier-event.md`）由各团队自己的 IM 模块读取，同一 `schema` 内只增加字段；`req` 的子命令和参数会被写进各团队的使用说明，改名时保留旧名一个主版本。`req api` 的输出（`contracts/cli-json.md`）是插件和脚本读取的格式，同一 `schema` 内只增加字段。
 
 ## 5. 处理复盘提交的问题
 
@@ -83,3 +84,4 @@
 | `evals/` | 评估：样例仓库、用例、对话剧本 |
 | `contracts/` | 文件格式约定 |
 | `docs/adr/` | 设计决定 |
+| `paseo-plugin/` | Paseo 插件：`client/`（界面，React Native）、`server/`（daemon 侧，运行 `req api`）、`shared/`（RPC 约定）。版本号与根目录的 `package.json` 相同，升版本时两处一起改 |

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/` 的路径）：