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

package/paseo-plugin/client/row.tsx

@@ -0,0 +1,40 @@
+// One requirement in a list: title, facts, stage, what is running, what needs a person.
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { Pressable, Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { ago, ATTENTION_LABELS, facts } from "./format";
+import { Badge, useStyles } from "./ui";
+
+export function RequirementRow({
+  theme,
+  layout,
+  item,
+  onPress,
+}: Pick<PluginHostProps, "theme" | "layout"> & { item: Requirement; onPress(): void }) {
+  const s = useStyles(theme, layout.compact);
+  return (
+    <Pressable accessibilityRole="button" accessibilityLabel={item.title} onPress={onPress} style={s.card}>
+      <View style={s.row}>
+        <Text style={[s.text, { fontWeight: "600", flexShrink: 1 }]}>{item.title}</Text>
+        {item.attention ? (
+          <Badge theme={theme} tone={item.attention === "approval" || item.attention === "business" ? "warning" : "danger"}>
+            {ATTENTION_LABELS[item.attention]}
+          </Badge>
+        ) : item.running ? (
+          <Badge theme={theme} tone="accent">
+            运行中
+          </Badge>
+        ) : null}
+        {!item.present ? (
+          <Badge theme={theme} tone="muted">
+            目录已不在
+          </Badge>
+        ) : null}
+      </View>
+      <Text style={s.muted}>{facts(item)}</Text>
+      <Text style={s.text}>{item.stage}</Text>
+      {item.current.length > 0 ? <Text style={s.muted}>正在：{item.current.map((c) => c.title).join("、")}</Text> : null}
+      <Text style={s.muted}>更新于 {ago(item.updatedAt)}</Text>
+    </Pressable>
+  );
+}

package/paseo-plugin/client/settings.tsx

@@ -0,0 +1,90 @@
+// Settings → Plugins → req-kit: what the plugin found, read-only mode, refresh interval.
+import { type PluginSurfaceProps, type SettingsState, useSettings } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsInput, SettingsRow, SettingsSection, SettingsSelect, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { useState } from "react";
+import { Text } from "react-native";
+import { preferences } from "../shared/contracts";
+import { useKitInfo } from "./data";
+
+type Ready = Extract<SettingsState<typeof preferences.schema>, { status: "ready" }>;
+
+const REFRESH = [
+  { label: "5 秒", value: "5" },
+  { label: "10 秒", value: "10" },
+  { label: "30 秒", value: "30" },
+  { label: "1 分钟", value: "60" },
+];
+
+function Controls({ settings, theme }: { settings: Ready; theme: PluginSurfaceProps["theme"] }) {
+  const [kitHome, setKitHome] = useState(settings.values.kitHome);
+  const info = useKitInfo();
+  return (
+    <>
+      <SettingsSection title="req-kit">
+        <SettingsCard>
+          {info.data ? (
+            <>
+              <SettingsRow label="版本" hint={info.data.kitRoot}>
+                <Text style={{ color: theme.colors.foreground }}>{info.data.kitVersion}</Text>
+              </SettingsRow>
+              <SettingsRow label="支持的 Paseo" hint={`本机配置目录：${info.data.kitHome}`}>
+                <Text style={{ color: theme.colors.foreground }}>{info.data.paseo ?? "-"}</Text>
+              </SettingsRow>
+            </>
+          ) : (
+            <SettingsRow label="状态" error={info.error?.message ?? undefined} hint={info.isPending ? "正在读取…" : undefined} />
+          )}
+          <SettingsInput
+            label="req-kit 的本机配置目录"
+            hint="通常不用填：默认是运行 Paseo 的用户的 ~/.req-kit。设置了 REQ_KIT_HOME 时填那个目录。"
+            initialValue={settings.values.kitHome}
+            placeholder="~/.req-kit"
+            onChangeText={setKitHome}
+            disabled={settings.saving}
+            error={settings.saveError ?? undefined}
+          />
+          <SettingsAction
+            label="保存配置目录"
+            actionLabel="保存"
+            disabled={settings.saving || kitHome === settings.values.kitHome}
+            onPress={() => void settings.save({ ...settings.values, kitHome: kitHome.trim() }, settings.revision).then(() => info.refetch())}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SettingsSection title="显示与操作">
+        <SettingsCard>
+          <SettingsSwitch
+            label="只读"
+            hint="只显示需求和文档，不提供确认方案、停止、继续、开始测试验证。能连上这台 daemon 的人都能看到这个插件。"
+            value={settings.values.readOnly}
+            disabled={settings.saving}
+            onValueChange={(readOnly) => void settings.save({ ...settings.values, readOnly }, settings.revision)}
+          />
+          <SettingsSelect
+            label="刷新间隔"
+            value={String(settings.values.refreshSeconds)}
+            options={REFRESH}
+            disabled={settings.saving}
+            onValueChange={(v) => void settings.save({ ...settings.values, refreshSeconds: Number(v) }, settings.revision)}
+          />
+        </SettingsCard>
+      </SettingsSection>
+    </>
+  );
+}
+
+export function SettingsScreen({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(preferences);
+  if (settings.status === "loading") return <Text style={{ color: theme.colors.foregroundMuted }}>正在读取…</Text>;
+  if (settings.status !== "ready") {
+    return (
+      <SettingsSection title="设置">
+        <SettingsCard>
+          <SettingsRow label="设置读取失败" error={settings.error} />
+          <SettingsAction label="恢复默认设置" actionLabel="恢复" onPress={() => void settings.reset()} />
+        </SettingsCard>
+      </SettingsSection>
+    );
+  }
+  return <Controls settings={settings} theme={theme} />;
+}

package/paseo-plugin/client/sidebar.tsx

@@ -0,0 +1,27 @@
+// The "需求" row in the sidebar, with how many requirements need a person.
+import type { PluginSidebarItemProps } from "@getpaseo/plugin/client";
+import { SidebarRow } from "@getpaseo/plugin/client/ui";
+import { Text, View } from "react-native";
+import { useRequirements } from "./data";
+
+export function RequirementsItem({ theme, currentScreen, openScreen }: PluginSidebarItemProps) {
+  const query = useRequirements();
+  const waiting = (query.data ?? []).filter((r) => r.attention).length;
+  return (
+    <SidebarRow
+      icon="ClipboardList"
+      label="需求"
+      active={currentScreen !== null}
+      onPress={() => openScreen({ screenId: "overview" })}
+      trailing={
+        waiting > 0 ? (
+          <View style={{ backgroundColor: theme.colors.statusWarning, borderRadius: 999, minWidth: 18, paddingHorizontal: 5, alignItems: "center" }}>
+            <Text accessibilityLabel={`${waiting} 个需求需要处理`} style={{ color: theme.colors.surface0, fontSize: 11, fontWeight: "600" }}>
+              {waiting}
+            </Text>
+          </View>
+        ) : undefined
+      }
+    />
+  );
+}

package/paseo-plugin/client/stats.tsx

@@ -0,0 +1,80 @@
+// Usage statistics (req stats): for whoever reports on how requirements went.
+import type { PluginScreenProps } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { useState } from "react";
+import { Text, View } from "react-native";
+import { useStats } from "./data";
+import { minutes, tokens, TYPE_LABELS } from "./format";
+import { Chip, Status, useStyles } from "./ui";
+
+function month(offset: number, now = new Date()): string {
+  const d = new Date(now.getFullYear(), now.getMonth() + offset, 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+}
+
+const OUTCOME: Record<string, string> = { completed: "已完成", completed_with_issues: "有遗留问题", not_completed: "未完成", unknown: "结论未记录" };
+
+export function StatsScreen({ theme, layout }: PluginScreenProps) {
+  const s = useStyles(theme, layout.compact);
+  const periods = [
+    { label: "最近 30 天", value: { since: "30d" } },
+    { label: "本月", value: { month: month(0) } },
+    { label: "上月", value: { month: month(-1) } },
+  ];
+  const [pick, setPick] = useState(0);
+  const query = useStats(periods[pick].value);
+  const d = query.data;
+  const card = (label: string, value: string, note?: string) => (
+    <View key={label} style={[s.card, { minWidth: layout.compact ? "45%" : 160, flexGrow: 1 }]}>
+      <Text style={s.muted}>{label}</Text>
+      <Text style={[s.text, { fontSize: 22, fontWeight: "600" }]}>{value}</Text>
+      {note ? <Text style={s.muted}>{note}</Text> : null}
+    </View>
+  );
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        <View style={s.row}>
+          {periods.map((p, i) => (
+            <Chip key={p.label} theme={theme} label={p.label} active={i === pick} onPress={() => setPick(i)} />
+          ))}
+        </View>
+        <Status theme={theme} loading={query.isPending} error={query.error} empty={d && d.active === 0 ? "这段时间没有流水线运行记录。" : null} />
+        {d && d.active > 0 ? (
+          <>
+            <View style={[s.row, { alignItems: "stretch" }]}>
+              {card("有进展的需求", String(d.active), Object.entries(d.byType).map(([k, v]) => `${TYPE_LABELS[k] ?? "普通"} ${v}`).join("，"))}
+              {card("完成", String(d.completed.total), Object.entries(d.completed.byOutcome).map(([k, v]) => `${OUTCOME[k] ?? k} ${v}`).join("，"))}
+              {card("交付周期中位数", d.cycleHours.median === null ? "-" : `${d.cycleHours.median} 小时`, "首次开始到完成")}
+              {card("平均评审轮数", d.rework.averageReviewRounds === null ? "-" : String(d.rework.averageReviewRounds), d.rework.withDefectRounds === null ? undefined : `${Math.round(d.rework.withDefectRounds * 100)}% 需要缺陷修复`)}
+              {card("agent 合计用时", minutes(d.usage.agentMinutes), `输入 ${tokens(d.usage.inputTokens)}，输出 ${tokens(d.usage.outputTokens)} tokens`)}
+              {d.usage.costUsd !== null ? card("费用", `$${d.usage.costUsd.toFixed(2)}`) : null}
+            </View>
+            {d.waits.length > 0 ? (
+              <View style={s.card}>
+                <Text style={s.heading}>等待</Text>
+                {d.waits.map((w) => (
+                  <Text key={w.kind} style={s.text}>
+                    {w.label}：{w.requirements} 个需求，平均 {minutes(w.averageMinutes)}
+                  </Text>
+                ))}
+              </View>
+            ) : null}
+            <View style={s.card}>
+              <Text style={s.heading}>各步骤用时</Text>
+              {d.steps.map((st) => (
+                <Text key={st.stepId} style={s.text}>
+                  {st.title}：{st.count} 次，平均 {minutes(st.averageMinutes)}，合计 {minutes(st.totalMinutes)}
+                </Text>
+              ))}
+              <Text style={s.muted}>
+                质量门运行 {d.rework.gateRuns} 次，发现新失败 {d.rework.gateFailed} 次。机器：{d.machines.join("、")}
+              </Text>
+            </View>
+            <Text style={s.muted}>给管理方的汇报文件：在终端运行 req stats --report --month {month(0)}；几台机器一起汇报见 req stats --export 和 --merge。</Text>
+          </>
+        ) : null}
+      </ScrollView>
+    </View>
+  );
+}

package/paseo-plugin/client/ui.tsx

@@ -0,0 +1,111 @@
+// Small building blocks in Paseo's theme. Every color comes from theme.colors.
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { type ReactNode, useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+
+type Theme = PluginHostProps["theme"];
+
+export function useStyles(theme: Theme, compact: boolean) {
+  return useMemo(
+    () => ({
+      screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+      body: { padding: compact ? 16 : 24, gap: compact ? 16 : 20 },
+      title: { color: theme.colors.foreground, fontSize: compact ? 18 : 20, fontWeight: "600" as const },
+      heading: { color: theme.colors.foregroundMuted, fontSize: 13, fontWeight: "600" as const, marginBottom: 6 },
+      text: { color: theme.colors.foreground, fontSize: 14 },
+      muted: { color: theme.colors.foregroundMuted, fontSize: 13 },
+      danger: { color: theme.colors.statusDanger, fontSize: 13 },
+      card: {
+        backgroundColor: theme.colors.surface1,
+        borderColor: theme.colors.border,
+        borderWidth: 1,
+        borderRadius: 10,
+        padding: compact ? 12 : 14,
+        gap: 4,
+      },
+      row: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8, flexWrap: "wrap" as const },
+      divider: { height: 1, backgroundColor: theme.colors.border },
+    }),
+    [theme, compact],
+  );
+}
+
+export function Badge({ theme, tone, children }: { theme: Theme; tone: "warning" | "danger" | "success" | "accent" | "muted"; children: ReactNode }) {
+  const color =
+    tone === "warning"
+      ? theme.colors.statusWarning
+      : tone === "danger"
+        ? theme.colors.statusDanger
+        : tone === "success"
+          ? theme.colors.statusSuccess
+          : tone === "accent"
+            ? theme.colors.accent
+            : theme.colors.foregroundMuted;
+  return (
+    <View style={{ borderColor: color, borderWidth: 1, borderRadius: 999, paddingHorizontal: 8, paddingVertical: 2 }}>
+      <Text style={{ color, fontSize: 12 }}>{children}</Text>
+    </View>
+  );
+}
+
+export function Button({
+  theme,
+  label,
+  onPress,
+  primary,
+  disabled,
+}: {
+  theme: Theme;
+  label: string;
+  onPress(): void;
+  primary?: boolean;
+  disabled?: boolean;
+}) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      disabled={disabled}
+      onPress={onPress}
+      style={{
+        paddingHorizontal: 14,
+        paddingVertical: 8,
+        borderRadius: 8,
+        opacity: disabled ? 0.5 : 1,
+        backgroundColor: primary ? theme.colors.accent : theme.colors.surface2,
+        borderColor: theme.colors.border,
+        borderWidth: primary ? 0 : 1,
+      }}
+    >
+      <Text style={{ color: primary ? theme.colors.accentForeground : theme.colors.foreground, fontSize: 14 }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+export function Chip({ theme, label, active, onPress }: { theme: Theme; label: string; active: boolean; onPress(): void }) {
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ selected: active }}
+      onPress={onPress}
+      style={{
+        paddingHorizontal: 10,
+        paddingVertical: 4,
+        borderRadius: 999,
+        backgroundColor: active ? theme.colors.accent : theme.colors.surface1,
+        borderColor: theme.colors.border,
+        borderWidth: active ? 0 : 1,
+      }}
+    >
+      <Text style={{ color: active ? theme.colors.accentForeground : theme.colors.foreground, fontSize: 13 }}>{label}</Text>
+    </Pressable>
+  );
+}
+
+/** Loading, error and empty states in one place. */
+export function Status({ theme, loading, error, empty }: { theme: Theme; loading?: boolean; error?: Error | null; empty?: string | null }) {
+  if (error) return <Text style={{ color: theme.colors.statusDanger, fontSize: 14 }}>{error.message}</Text>;
+  if (loading) return <Text style={{ color: theme.colors.foregroundMuted, fontSize: 14 }}>正在读取…</Text>;
+  if (empty) return <Text style={{ color: theme.colors.foregroundMuted, fontSize: 14 }}>{empty}</Text>;
+  return null;
+}

package/paseo-plugin/index.client.tsx

@@ -0,0 +1,52 @@
+import type { PluginClientContext, PluginScreenProps } from "@getpaseo/plugin/client";
+import { RequirementScreen } from "./client/detail";
+import { contributeLive } from "./client/live";
+import { OverviewScreen } from "./client/overview";
+import { WorkspacePanel } from "./client/panel";
+import { SettingsScreen } from "./client/settings";
+import { RequirementsItem } from "./client/sidebar";
+import { StatsScreen } from "./client/stats";
+
+export default function contribute(client: PluginClientContext) {
+  const openScreen = (input: { screenId: string; params?: Record<string, string> }) => client.openScreen(input);
+  const Overview = (props: PluginScreenProps) => <OverviewScreen {...props} openScreen={openScreen} />;
+
+  client.addScreen({ id: "overview", title: "需求", Component: Overview });
+  client.addScreen({ id: "requirement", title: (params) => params.title || params.name || "需求", Component: RequirementScreen });
+  client.addScreen({ id: "stats", title: "需求统计", Component: StatsScreen });
+  client.addSidebarHeaderItem({ id: "requirements", title: "需求（req-kit）", Component: RequirementsItem });
+  client.addWorkspacePanel({
+    id: "requirements",
+    title: "需求",
+    icon: "ClipboardList",
+    context: "workspace",
+    locations: ["workspace", "explorer"],
+    Component: WorkspacePanel,
+  });
+  client.addSettingsScreen({ id: "preferences", title: "req-kit", icon: "ClipboardList", Component: SettingsScreen });
+  client.addCommandCenterItem({
+    id: "open-overview",
+    title: "需求总览（req-kit）",
+    icon: "ClipboardList",
+    keywords: ["req", "requirement", "需求", "流水线"],
+    context: "global",
+    onSelect: ({ openScreen: open }) => open({ screenId: "overview" }),
+  });
+  client.addCommandCenterItem({
+    id: "open-stats",
+    title: "需求统计（req-kit）",
+    icon: "ChartColumn",
+    keywords: ["req", "stats", "统计", "用量"],
+    context: "global",
+    onSelect: ({ openScreen: open }) => open({ screenId: "stats" }),
+  });
+  client.addCommandCenterItem({
+    id: "open-panel",
+    title: "这个工作区的需求（req-kit）",
+    icon: "ClipboardList",
+    keywords: ["req", "需求"],
+    context: "workspace",
+    onSelect: ({ openPanel }) => openPanel("requirements"),
+  });
+  return contributeLive(client);
+}

package/paseo-plugin/index.server.ts

@@ -0,0 +1,41 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { fileRpc, listRpc, preferences, runRpc, statsRpc, statusRpc, versionRpc } from "./shared/contracts";
+import { createHandlers } from "./server/handlers";
+import { kitHomeOf, reqApi } from "./server/req";
+
+export default function contribute(server: PluginServerContext) {
+  const settings = server.registerSettings(preferences);
+  let kitHomeSetting = "";
+  let readOnly = false;
+  const load = async () => {
+    const state = await settings.read();
+    if (state.status === "ready") {
+      kitHomeSetting = state.values.kitHome;
+      readOnly = state.values.readOnly;
+    }
+  };
+  void load();
+  const unsubscribe = settings.subscribe((state) => {
+    if (state.status !== "ready") return;
+    kitHomeSetting = state.values.kitHome;
+    readOnly = state.values.readOnly;
+  });
+  const kitHome = () => kitHomeOf(kitHomeSetting);
+  const handlers = createHandlers({
+    req: reqApi(kitHome),
+    kitHome,
+    readOnly: async () => {
+      await load();
+      return readOnly;
+    },
+  });
+  server.handle(versionRpc, () => handlers.version());
+  server.handle(listRpc, () => handlers.list());
+  server.handle(statusRpc, (input) => handlers.status(input));
+  server.handle(fileRpc, (input) => handlers.file(input));
+  server.handle(statsRpc, (input) => handlers.stats(input));
+  server.handle(runRpc, (input) => handlers.run(input));
+  return () => {
+    unsubscribe();
+  };
+}

package/paseo-plugin/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "req-kit-paseo-plugin",
+  "version": "1.9.0-beta.2",
+  "private": true,
+  "description": "The req-kit plugin for Paseo. Ships inside the paseo-req-kit package; installed with req plugin install.",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "0.11.2",
+    "@getpaseo/plugin": "0.11.2",
+    "@getpaseo/protocol": "0.11.2",
+    "@tanstack/react-query": "^5.90.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "~19.2.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^5.9.3",
+    "zod": "^4.4.3"
+  }
+}

package/paseo-plugin/paseo-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "req-kit",
+  "name": "req-kit 需求",
+  "description": "在 Paseo 中查看和管理 req-kit 的需求：总览、进度、文档、统计，确认方案、停止和继续",
+  "requirements": { "paseo": ">=0.11.0 <0.12.0" }
+}

package/paseo-plugin/server/handlers.ts

@@ -0,0 +1,45 @@
+// The daemon side: each RPC is one `req api` call. Management actions are refused here too
+// when the plugin is set to read-only, not only hidden in the app.
+import type { RpcInput } from "@getpaseo/plugin";
+import type { fileRpc, KitInfo, Requirement, RequirementDetail, runRpc, statsRpc, StatsSummary, statusRpc } from "../shared/contracts";
+import { coalesce, type ReqRunner } from "./req";
+
+export interface Handlers {
+  version(): Promise<KitInfo>;
+  list(): Promise<Requirement[]>;
+  status(input: RpcInput<typeof statusRpc>): Promise<RequirementDetail>;
+  file(input: RpcInput<typeof fileRpc>): Promise<{ file: string; size: number; truncated: boolean; content: string }>;
+  stats(input: RpcInput<typeof statsRpc>): Promise<StatsSummary>;
+  run(input: RpcInput<typeof runRpc>): Promise<{ ok: boolean; message: string }>;
+}
+
+export function createHandlers(input: { req: ReqRunner; kitHome: () => string; readOnly: () => Promise<boolean> }): Handlers {
+  const { req } = input;
+  // Every open screen polls the list; one `req api list` serves them all for a moment.
+  const list = coalesce(2_000, () => req(["list", "--all"]) as Promise<Requirement[]>);
+  return {
+    async version() {
+      const info = (await req(["version"])) as Omit<KitInfo, "kitHome">;
+      return { ...info, kitHome: input.kitHome() };
+    },
+    list,
+    async status({ repo, featureDir }) {
+      return (await req(["status", featureDir, "--repo", repo])) as RequirementDetail;
+    },
+    async file({ repo, featureDir, file }) {
+      return (await req(["file", featureDir, file, "--repo", repo])) as { file: string; size: number; truncated: boolean; content: string };
+    },
+    async stats({ since, month }) {
+      const args = ["stats"];
+      if (month) args.push("--month", month);
+      else if (since) args.push("--since", since);
+      return (await req(args)) as StatsSummary;
+    },
+    async run({ action, repo, featureDir, verifyEnv }) {
+      if (await input.readOnly()) return { ok: false, message: "插件设置为只读：不能在这里操作需求。可以在插件设置中关闭只读，或在终端用 req 命令。" };
+      const extra = action === "verify" && verifyEnv ? ["--verify-env", verifyEnv] : [];
+      const result = (await req(["run", action, featureDir, "--repo", repo, ...extra], { timeoutMs: 200_000 })) as { ok: boolean; message: string };
+      return { ok: result.ok, message: result.message };
+    },
+  };
+}

package/paseo-plugin/server/req.ts

@@ -0,0 +1,100 @@
+// Runs `req api …` with the req-kit version this machine has active, and parses its one line
+// of JSON (contracts/cli-json.md). The plugin never reads or writes req-kit's files itself.
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export class ReqError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function kitHomeOf(configured: string): string {
+  if (configured.trim()) return path.resolve(configured.trim().replace(/^~(?=$|[\\/])/, os.homedir()));
+  const env = process.env.REQ_KIT_HOME?.trim();
+  return env ? path.resolve(env) : path.join(os.homedir(), ".req-kit");
+}
+
+/** The active version's req.mjs, from <kit home>/active.json. */
+export function activeReq(kitHome: string): string {
+  const file = path.join(kitHome, "active.json");
+  let active: { root?: string; version?: string } | null = null;
+  try {
+    active = JSON.parse(fs.readFileSync(file, "utf8")) as { root?: string };
+  } catch {
+    throw new ReqError("no_kit", `这台机器上没有找到 req-kit（${file}）。请先安装 req-kit 并运行 req setup。`);
+  }
+  const req = active?.root ? path.join(active.root, "bin", "req.mjs") : "";
+  if (!req || !fs.existsSync(req)) throw new ReqError("no_kit", `req-kit 当前启用的版本不在了（${active?.root ?? "未知"}）。请运行 req versions 和 req use。`);
+  return req;
+}
+
+/** A node to run req with: this process's when it is node, else the one on PATH. */
+function nodeBinary(): string {
+  const base = path.basename(process.execPath).toLowerCase();
+  return base === "node" || base === "node.exe" ? process.execPath : "node";
+}
+
+export interface ReqRunner {
+  (args: string[], options?: { timeoutMs?: number }): Promise<unknown>;
+}
+
+/** Runs `req api <args>` and returns its data, or throws ReqError with req's message. */
+export function reqApi(kitHome: () => string): ReqRunner {
+  return (args, options = {}) =>
+    new Promise((resolve, reject) => {
+      let req: string;
+      const home = kitHome();
+      try {
+        req = activeReq(home);
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      const env: NodeJS.ProcessEnv = { ...process.env, REQ_KIT_HOME: home };
+      // Not a chat: the run keeps reporting to the chat that started it.
+      delete env.PASEO_AGENT_ID;
+      delete env.PASEO_AGENT_CWD;
+      execFile(
+        nodeBinary(),
+        [req, "api", ...args],
+        { env, timeout: options.timeoutMs ?? 60_000, maxBuffer: 16 * 1024 * 1024, windowsHide: true },
+        (error, stdout, stderr) => {
+          const line = stdout.trim().split("\n").pop() ?? "";
+          let parsed: { schema?: number; data?: unknown; error?: { code: string; message: string } } | null = null;
+          try {
+            parsed = JSON.parse(line);
+          } catch {
+            parsed = null;
+          }
+          if (parsed?.error) return reject(new ReqError(parsed.error.code, parsed.error.message));
+          if (parsed && "data" in parsed) return resolve(parsed.data);
+          const why = (stderr || error?.message || "没有输出").trim().split("\n").slice(-3).join(" ");
+          if (/没有 "api" 这个命令|not.*api/i.test(stdout + stderr)) {
+            return reject(new ReqError("old_kit", "本机的 req-kit 太旧，不支持插件（需要 1.9 或更新的版本）。请运行 req upgrade。"));
+          }
+          reject(new ReqError("failed", `req api ${args[0] ?? ""} 失败：${why}`));
+        },
+      );
+    });
+}
+
+/** The same call made twice within `ms` shares one run (several open screens, one daemon). */
+export function coalesce<T>(ms: number, run: () => Promise<T>): () => Promise<T> {
+  let last: { at: number; value: Promise<T> } | null = null;
+  return () => {
+    const now = Date.now();
+    if (last && now - last.at < ms) return last.value;
+    const value = run();
+    last = { at: now, value };
+    value.catch(() => {
+      if (last?.value === value) last = null;
+    });
+    return value;
+  };
+}