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

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [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）都建在它上面。

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

@@ -40,6 +40,11 @@ const HELP = `req-kit ${version}（${kitRoot}）
                                本机记录的需求（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
@@ -175,6 +180,9 @@ switch (command) {
   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/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

@@ -28,3 +28,4 @@ req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR
 - [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

@@ -357,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/install.mjs

@@ -911,6 +911,9 @@ if (values.check) {
   if (active && path.resolve(active.root) !== path.resolve(KIT_ROOT)) ok(`已从 ${active.version} 切换到 ${VERSION}`);
   else ok(`已启用 ${VERSION}`);
   writeShims();
+  // The Paseo plugin, when installed, follows the active version (bin/req-plugin.mjs).
+  const { refreshPlugin } = await import("./bin/req-plugin.mjs");
+  refreshPlugin({ kitRoot: KIT_ROOT, log: (message) => ok(message) });
 }
 checkLegacyLeftovers(roots);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.9.0-beta.1",
+  "version": "1.9.0-beta.2",
   "description": "req-kit: a requirement-development workflow for Paseo. /req aligns a requirement in chat; the engine runs design, implementation, review and verification as Paseo agents.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "bin/",
     "engine/src/",
     "engine/prompts/",
+    "paseo-plugin/",
     "skills/",
     "principles/",
     "contracts/",

package/paseo-plugin/OVERVIEW.md

@@ -0,0 +1,7 @@
+req-kit 的需求在 Paseo 里的样子：本机所有项目的需求一页看完，哪些在等你确认、哪些卡住了、哪些在运行；点开一个需求，看它走到哪一步、每一步用了多久、质量门的结果，读需求说明、方案、确认预览、提测说明和完成报告。
+
+需要人处理的时候，可以直接在这里确认方案、停止、继续或开始测试验证。这些操作和在终端运行 `req approve`、`req stop`、`req resume`、`req verify` 完全一样，流水线本身不受插件影响；不想让人在网页上操作时，在插件设置中打开"只读"。
+
+还有：侧边栏的"需求"（带待处理数）、每个工作区头部的"需求"按钮和面板、步骤 agent 输入框旁的"需求"按钮，以及使用统计（交付周期、返工、等待、用量）。
+
+需要这台 daemon 上安装 req-kit 1.9 或更新的版本，插件通过本机的 `req api` 读取需求；它不连接任何外部服务。用 `req plugin install` 安装和更新。

package/paseo-plugin/client/data.ts

@@ -0,0 +1,55 @@
+// Data hooks: every read is an RPC to the daemon side (req api), cached by React Query.
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useRpc, useSettings } from "@getpaseo/plugin/client";
+import { fileRpc, listRpc, preferences, runRpc, statsRpc, statusRpc, versionRpc, type Action } from "../shared/contracts";
+
+export function usePreferences(): { readOnly: boolean; refreshMs: number } {
+  const settings = useSettings(preferences);
+  if (settings.status !== "ready") return { readOnly: true, refreshMs: 10_000 };
+  return { readOnly: settings.values.readOnly, refreshMs: settings.values.refreshSeconds * 1000 };
+}
+
+export function useRequirements() {
+  const list = useRpc(listRpc);
+  const { refreshMs } = usePreferences();
+  return useQuery({ queryKey: ["req", "list"], queryFn: () => list({}), refetchInterval: refreshMs });
+}
+
+export function useRequirement(repo: string, featureDir: string) {
+  const status = useRpc(statusRpc);
+  const { refreshMs } = usePreferences();
+  return useQuery({
+    queryKey: ["req", "status", repo, featureDir],
+    queryFn: () => status({ repo, featureDir }),
+    refetchInterval: refreshMs,
+    enabled: Boolean(repo && featureDir),
+  });
+}
+
+export function useDocument(repo: string, featureDir: string, file: string | null) {
+  const read = useRpc(fileRpc);
+  return useQuery({
+    queryKey: ["req", "file", repo, featureDir, file],
+    queryFn: () => read({ repo, featureDir, file: file ?? "" }),
+    enabled: Boolean(file),
+  });
+}
+
+export function useStats(period: { since?: string; month?: string }) {
+  const stats = useRpc(statsRpc);
+  return useQuery({ queryKey: ["req", "stats", period.since ?? "", period.month ?? ""], queryFn: () => stats(period) });
+}
+
+export function useKitInfo() {
+  const version = useRpc(versionRpc);
+  return useQuery({ queryKey: ["req", "version"], queryFn: () => version({}), retry: false });
+}
+
+export function useAction() {
+  const run = useRpc(runRpc);
+  const queries = useQueryClient();
+  return useMutation({
+    mutationFn: (input: { action: Action; repo: string; featureDir: string; verifyEnv?: "local" | "deployed" }) => run(input),
+    onSettled: () => queries.invalidateQueries({ queryKey: ["req"] }),
+  });
+}