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

package/engine/src/pipeline.ts

@@ -33,6 +33,7 @@ import {
 import { kitVersion } from "./locations.js";
 import { type AgentUsage, describeTotals, totals } from "./usage.js";
 import { dispatchNotifiers, type NotifierEventType } from "./notifiers.js";
+import { describeExternal, type IntegrationEvent, type Runner, syncIntegration } from "./integrations.js";
 import { principlesSection, projectAdditions, type PromptLocations, readToolPrompt } from "./prompts.js";
 import type { AgentRuntime, ManagedService, ServiceTarget, StepAgent } from "./runtime.js";
 import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type RunPhases, type StepRecord, writeState } from "./state.js";
@@ -56,6 +57,8 @@ export interface PipelineContext {
   approveCommand?: string;
   log: (message: string) => void;
   sleep: (ms: number) => Promise<void>;
+  /** Runs integration commands; tests replace it. Default: the real command line. */
+  integrationRunner?: Runner;
   /** Paseo-managed services of this run (filled in by the pipeline). */
   services?: { names: string[] | null | undefined; started: Set<string> };
   /** Paseo tools the step agents get; looked up once (undefined: not yet). */
@@ -384,6 +387,21 @@ async function notifyExternal(ctx: PipelineContext, type: NotifierEventType, tex
   );
 }
 
+/** Keeps the requirement's card in each configured external system in step (1.9). Never throws. */
+async function integrate(ctx: PipelineContext, event: IntegrationEvent): Promise<void> {
+  if (ctx.config.integrations.length === 0) return;
+  for (const config of ctx.config.integrations) {
+    await syncIntegration({
+      config,
+      ctx: { repo: ctx.repo, featureDir: ctx.featureDir, state: ctx.state, projectDefaults: ctx.config.integrationDefaults[config.name] },
+      event,
+      run: ctx.integrationRunner,
+      log: ctx.log,
+    });
+  }
+  save(ctx);
+}
+
 /** Sends a progress note once per run attempt, when enabled. */
 async function milestone(ctx: PipelineContext, id: string, text: string): Promise<void> {
   if (!ctx.config.notifyMilestones || ctx.state.milestones.includes(id)) return;
@@ -1648,8 +1666,13 @@ async function setUpJoint(ctx: PipelineContext): Promise<void> {
 }
 
 /** What the report is told about this attempt: usage, the quality gate, the scope check. */
+/** The requirement's cards in external systems, for the report's appendix. */
+function externalLines(ctx: PipelineContext): string[] {
+  return describeExternal(ctx.state.external).map((l) => `外部系统 ${l}`);
+}
+
 function reportLines(ctx: PipelineContext): string[] {
-  const lines = [...usageLines(ctx), ...gateLines(ctx), ...scopeLines(ctx), ...acceptanceLines(ctx), ...jointLines(ctx)];
+  const lines = [...usageLines(ctx), ...gateLines(ctx), ...scopeLines(ctx), ...acceptanceLines(ctx), ...jointLines(ctx), ...externalLines(ctx)];
   if (ctx.config.checks.length === 0 && ctx.state.type !== "assessment") {
     lines.push("质量门：项目没有配置检查（checks），流水线没有自己运行检查，以各步骤记录的检查结果为准");
   }
@@ -1693,6 +1716,7 @@ async function flow(ctx: PipelineContext): Promise<Record<string, unknown>> {
       }
       ctx.state.phase = "verify";
       save(ctx);
+      await integrate(ctx, "verify");
     }
     if (!(await verifyPhase(ctx, design))) break;
     await handBack(ctx);
@@ -1705,6 +1729,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
   ctx.state.status = "running";
   ctx.state.stopReason = null;
   save(ctx);
+  await integrate(ctx, phaseOf(ctx) === "verify" ? "verify" : "started");
   try {
     await checkQuota(ctx);
     const report = await flow(ctx);
@@ -1730,6 +1755,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     const text = developOnly
       ? `研发已完成（只做研发）：${outcomeText[report.outcome as string] ?? report.outcome}，请按提测说明人工测试。`
       : `开发流水线已结束：${outcomeText[report.outcome as string] ?? report.outcome}。`;
+    await integrate(ctx, "completed");
     await notifyExternal(ctx, "completed", text, {
       outcome: report.outcome,
       summary: report.summary,
@@ -1757,6 +1783,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
           handbacks: ctx.state.handbacks ?? 0,
         }),
       );
+      await integrate(ctx, "phase_done");
       await notifyExternal(ctx, "phase_done", `研发已完成，可以提测：提测说明在 ${ctx.featureDir}/handoff.md。${verifyAt ? `已预约在 ${verifyAt} 开始测试验证。` : ""}`, {
         handoffPath: `${ctx.featureDir}/handoff.md`,
         mode: runPhases(ctx.state).mode,
@@ -1785,6 +1812,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
           autoContinueAt,
         }),
       );
+      await integrate(ctx, "approval");
       await notifyExternal(ctx, "approval", `方案已通过审核，请需求方确认"做完后会看到什么"再开始写代码：${ctx.featureDir}/preview.md`, {
         previewPath: `${ctx.featureDir}/preview.md`,
         approveCommand: approveCommandOf(ctx),
@@ -1805,6 +1833,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
       const external = reproduce
         ? `没能复现这个缺陷，需要需求方补充 ${error.questions.length} 项信息，流水线已暂停，请到发起的对话中回答。`
         : `方案审核发现 ${error.questions.length} 个需要需求方决定的问题，流水线已暂停，请到发起的对话中回答。`;
+      await integrate(ctx, "blocked");
       await notifyExternal(ctx, "blocked", external, {
         questions: error.questions,
         resumeCommand: ctx.resumeCommand,
@@ -1827,6 +1856,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
         autoResumeAt,
       }),
     );
+    await integrate(ctx, "failed");
     await notifyExternal(ctx, "failed", `开发流水线在「${stepTitle}」步骤中断：${(error as Error).message}`, {
       stepTitle,
       reason: (error as Error).message,

package/engine/src/preflight.ts

@@ -29,6 +29,8 @@ export interface LaunchArgs {
   stop: boolean;
   /** --list: print every requirement in this repository's worktrees. */
   list: boolean;
+  /** --card-fields: what /req confirms with the spec for the external systems (card.json). */
+  cardFields?: boolean;
   /** --spec-review: independent review of the draft spec, before confirmation. */
   specReview: boolean;
   /** --worktree: create a Paseo worktree workspace for this requirement and develop there. */

package/engine/src/state.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { DefectHandling, PhaseMode, ProfileName, RequirementType, VerifyEnvironment } from "./config.js";
+import type { ExternalRecord } from "./integrations.js";
 import { registerRequirement } from "./records.js";
 import type { AgentUsage } from "./usage.js";
 import type { StepId } from "./steps.js";
@@ -106,6 +107,8 @@ export interface PipelineState {
   approval?: { attempt: number; status: "waiting" | "approved"; at: string; auto?: boolean } | null;
   /** Quality gate: the checks' results before the change, and every run after a step (1.8). */
   gate?: { baseline: GateBaseline | null; runs: GateRun[] } | null;
+  /** External systems (1.9): the requirement's card in each, by integration name. */
+  external?: Record<string, ExternalRecord> | null;
 }
 
 export interface JointRepo {

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.3",
   "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"] }),
+  });
+}

package/paseo-plugin/client/detail.tsx

@@ -0,0 +1,303 @@
+// One requirement: where it stands, its steps, the quality gate, its documents, and the
+// management actions (each one is `req <command>` on the daemon machine, after confirming).
+import type { PluginHostProps, PluginScreenProps, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import { Modal, ScrollView, useToast } from "@getpaseo/plugin/client/react-native";
+import { ExternalLink } from "@getpaseo/plugin/client/ui";
+import { useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import type { Action, RequirementDetail, Step } from "../shared/contracts";
+import { useAction, useDocument, usePreferences, useRequirement, useRequirements } from "./data";
+import { ACTION_TEXT, actionsFor, ago, ATTENTION_LABELS, facts, FILE_LABELS, minutes, tokens } from "./format";
+import { Markdown, tsvToMarkdown } from "./markdown";
+import { Badge, Button, Chip, Status, useStyles } from "./ui";
+
+type Theme = PluginHostProps["theme"];
+type Layout = PluginHostProps["layout"];
+type Navigation = PluginSurfaceProps["navigation"];
+
+const OUTCOME_LABELS: Record<Step["outcome"], string> = { running: "运行中", completed: "完成", failed: "失败" };
+
+function StepRow({ theme, layout, step, navigation }: { theme: Theme; layout: Layout; step: Step; navigation: Navigation }) {
+  const s = useStyles(theme, layout.compact);
+  const tone = step.outcome === "failed" ? "danger" : step.outcome === "running" ? "accent" : "muted";
+  const body = (
+    <View style={{ gap: 2, paddingVertical: 6 }}>
+      <View style={s.row}>
+        <Text style={[s.text, { flexShrink: 1 }]}>{step.title}</Text>
+        <Badge theme={theme} tone={tone}>
+          {step.outcome === "completed" && step.result ? step.result : OUTCOME_LABELS[step.outcome]}
+        </Badge>
+      </View>
+      <Text style={s.muted}>
+        第 {step.attempt} 次尝试 · {minutes(step.minutes)} · {ago(step.startedAt)}开始
+      </Text>
+      {step.error ? <Text style={s.danger}>{step.error}</Text> : null}
+    </View>
+  );
+  // A step agent opens in Paseo, where its whole conversation is.
+  if (!navigation || !step.agentId) return body;
+  return (
+    <Pressable accessibilityRole="button" accessibilityLabel={`打开 ${step.title} 的 agent`} onPress={() => navigation.openAgent({ agentId: step.agentId })}>
+      {body}
+    </Pressable>
+  );
+}
+
+function DocumentModal({
+  theme,
+  layout,
+  repo,
+  featureDir,
+  file,
+  onClose,
+}: {
+  theme: Theme;
+  layout: Layout;
+  repo: string;
+  featureDir: string;
+  file: string | null;
+  onClose(): void;
+}) {
+  const s = useStyles(theme, layout.compact);
+  const doc = useDocument(repo, featureDir, file);
+  return (
+    <Modal title={file ? `${FILE_LABELS[file] ?? file}（${file}）` : ""} open={file !== null} onOpenChange={(open) => (open ? undefined : onClose())}>
+      <Modal.Content>
+        <Status theme={theme} loading={doc.isPending} error={doc.error} />
+        {doc.data ? (
+          <>
+            <Markdown theme={theme} source={doc.data.file.endsWith(".tsv") ? tsvToMarkdown(doc.data.content) : doc.data.content} />
+            {doc.data.truncated ? <Text style={s.muted}>文件较大，只显示了开头的 512 KB。</Text> : null}
+          </>
+        ) : null}
+      </Modal.Content>
+    </Modal>
+  );
+}
+
+function ActionModal({
+  theme,
+  layout,
+  detail,
+  action,
+  onClose,
+}: {
+  theme: Theme;
+  layout: Layout;
+  detail: RequirementDetail;
+  action: Action | null;
+  onClose(): void;
+}) {
+  const s = useStyles(theme, layout.compact);
+  const run = useAction();
+  const toast = useToast();
+  const go = async (verifyEnv?: "local" | "deployed") => {
+    if (!action) return;
+    try {
+      const result = await run.mutateAsync({ action, repo: detail.sourceRepo ?? detail.repo, featureDir: detail.featureDir, verifyEnv });
+      const first = result.message.split("\n").find((l) => l.trim()) ?? "";
+      if (result.ok) toast.show(first || "已完成", { variant: "success", durationMs: 4000 });
+      else toast.error(first || "没有完成");
+      onClose();
+    } catch (error) {
+      toast.error((error as Error).message);
+    }
+  };
+  const text = action ? ACTION_TEXT[action] : null;
+  return (
+    <Modal title={text ? `${text.label}：${detail.title}` : ""} open={action !== null} onOpenChange={(open) => (open ? undefined : onClose())}>
+      <Modal.Content>
+        <Text style={s.text}>{text?.confirm}</Text>
+        {action === "approve" && detail.files.includes("preview.md") ? <Text style={s.muted}>确认预览在本页的"文档"中：确认预览（preview.md）。</Text> : null}
+        <View style={s.row}>
+          {action === "verify" ? (
+            <>
+              <Button theme={theme} primary label="在本地验证" disabled={run.isPending} onPress={() => void go("local")} />
+              <Button theme={theme} label="在已部署的测试环境验证" disabled={run.isPending} onPress={() => void go("deployed")} />
+            </>
+          ) : (
+            <Button theme={theme} primary label={run.isPending ? "正在执行…" : (text?.label ?? "")} disabled={run.isPending} onPress={() => void go()} />
+          )}
+          <Button theme={theme} label="取消" disabled={run.isPending} onPress={onClose} />
+        </View>
+      </Modal.Content>
+    </Modal>
+  );
+}
+
+function GateSummary({ theme, layout, detail }: { theme: Theme; layout: Layout; detail: RequirementDetail }) {
+  const s = useStyles(theme, layout.compact);
+  const runs = [...(detail.gate?.runs ?? []), ...detail.joint.flatMap((j) => j.gate?.runs ?? [])];
+  if (runs.length === 0) return null;
+  const last = runs.at(-1)!;
+  const failed = runs.filter((r) => !r.passed).length;
+  return (
+    <View style={s.card}>
+      <Text style={s.heading}>质量门</Text>
+      <Text style={s.text}>
+        运行 {runs.length} 次{failed > 0 ? `，其中 ${failed} 次发现改动带来的新失败` : "，都没有新失败"}
+      </Text>
+      <Text style={s.muted}>
+        最近一次（{last.key}）：{last.passed ? "通过" : `新失败：${last.newFailures.join("、")}`}
+      </Text>
+    </View>
+  );
+}
+
+export function RequirementView({
+  theme,
+  layout,
+  navigation,
+  repo,
+  featureDir,
+}: {
+  theme: Theme;
+  layout: Layout;
+  navigation: Navigation;
+  repo: string;
+  featureDir: string;
+}) {
+  const s = useStyles(theme, layout.compact);
+  const query = useRequirement(repo, featureDir);
+  const { readOnly } = usePreferences();
+  const [doc, setDoc] = useState<string | null>(null);
+  const [action, setAction] = useState<Action | null>(null);
+  const [allSteps, setAllSteps] = useState(false);
+  const d = query.data;
+  if (!d) return <Status theme={theme} loading={query.isPending} error={query.error} />;
+  const steps = allSteps ? d.steps : d.steps.slice(-12);
+  const actions = readOnly ? [] : actionsFor(d);
+  return (
+    <View style={{ gap: 16 }}>
+      <View style={{ gap: 4 }}>
+        <View style={s.row}>
+          <Text style={s.title}>{d.title}</Text>
+          {d.attention ? (
+            <Badge theme={theme} tone={d.attention === "approval" || d.attention === "business" ? "warning" : "danger"}>
+              {ATTENTION_LABELS[d.attention]}
+            </Badge>
+          ) : null}
+        </View>
+        <Text style={s.muted}>{facts(d)}</Text>
+        <Text style={s.text}>{d.stage}</Text>
+        {d.run?.stopReason && !d.running ? <Text style={s.danger}>{d.run.stopReason}</Text> : null}
+        {d.attention === "business" ? <Text style={s.muted}>需求方的决定请在发起需求的对话中回答，回答后再继续。</Text> : null}
+      </View>
+
+      {actions.length > 0 ? (
+        <View style={s.row}>
+          {actions.map((a) => (
+            <Button key={a} theme={theme} primary={a !== "stop"} label={ACTION_TEXT[a].label} onPress={() => setAction(a)} />
+          ))}
+        </View>
+      ) : null}
+
+      {d.files.length > 0 ? (
+        <View style={{ gap: 6 }}>
+          <Text style={s.heading}>文档</Text>
+          <View style={s.row}>
+            {d.files.map((f) => (
+              <Chip key={f} theme={theme} label={FILE_LABELS[f] ?? f} active={false} onPress={() => setDoc(f)} />
+            ))}
+          </View>
+        </View>
+      ) : null}
+
+      <View style={s.card}>
+        <Text style={s.heading}>位置</Text>
+        <Text selectable style={s.text}>
+          {d.repo}/{d.featureDir}
+        </Text>
+        {d.branch ? <Text style={s.muted}>分支 {d.branch}</Text> : null}
+        {d.workspaceId && navigation ? (
+          <Pressable accessibilityRole="button" onPress={() => navigation.openWorkspace({ workspaceId: d.workspaceId! })}>
+            <Text style={{ color: theme.colors.accent, fontSize: 13 }}>打开这个需求的工作区</Text>
+          </Pressable>
+        ) : null}
+        {d.joint.map((j) => (
+          <Text key={j.name} style={s.muted}>
+            联合开发「{j.name}」：{j.repo}（分支 {j.branch}）
+          </Text>
+        ))}
+      </View>
+
+      {(d.external ?? []).length > 0 ? (
+        <View style={s.card}>
+          <Text style={s.heading}>外部系统</Text>
+          {(d.external ?? []).map((e) => (
+            <View key={e.name} style={{ gap: 2 }}>
+              <View style={s.row}>
+                <Text style={s.text}>
+                  {e.name}：{e.id ?? "还没有建卡"}
+                </Text>
+                {e.status ? (
+                  <Badge theme={theme} tone="muted">
+                    {e.status}
+                  </Badge>
+                ) : null}
+              </View>
+              {e.url ? <ExternalLink href={e.url}>打开卡片</ExternalLink> : null}
+              {e.pending > 0 ? (
+                <Text style={s.danger}>
+                  有 {e.pending} 次调用没有成功：{e.lastError}
+                </Text>
+              ) : null}
+            </View>
+          ))}
+        </View>
+      ) : null}
+
+      {d.usage ? (
+        <View style={s.card}>
+          <Text style={s.heading}>用时与用量</Text>
+          <Text style={s.text}>
+            {d.usage.steps} 个步骤，agent 合计 {minutes(d.usage.agentMinutes)}
+          </Text>
+          <Text style={s.muted}>
+            输入 {tokens(d.usage.inputTokens)} tokens，输出 {tokens(d.usage.outputTokens)} tokens
+            {d.usage.costUsd !== null ? `，约 $${d.usage.costUsd.toFixed(2)}` : ""}
+          </Text>
+        </View>
+      ) : null}
+
+      <GateSummary theme={theme} layout={layout} detail={d} />
+
+      {d.steps.length > 0 ? (
+        <View style={s.card}>
+          <View style={s.row}>
+            <Text style={s.heading}>步骤（{d.steps.length}）</Text>
+            {d.steps.length > 12 ? <Button theme={theme} label={allSteps ? "只看最近的" : "显示全部"} onPress={() => setAllSteps((v) => !v)} /> : null}
+          </View>
+          {steps.map((step) => (
+            <StepRow key={`${step.key}-${step.attempt}-${step.startedAt}`} theme={theme} layout={layout} step={step} navigation={navigation} />
+          ))}
+        </View>
+      ) : null}
+
+      <DocumentModal theme={theme} layout={layout} repo={d.repo} featureDir={d.featureDir} file={doc} onClose={() => setDoc(null)} />
+      <ActionModal theme={theme} layout={layout} detail={d} action={action} onClose={() => setAction(null)} />
+    </View>
+  );
+}
+
+export function RequirementScreen({ theme, layout, navigation, params }: PluginScreenProps) {
+  const s = useStyles(theme, layout.compact);
+  // Opened from a step agent's pill: only the requirement's name is known; find it in the list.
+  const list = useRequirements();
+  const byName = !params.repo && params.name ? (list.data ?? []).find((r) => r.name === params.name) : null;
+  const repo = params.repo ?? byName?.repo;
+  const featureDir = params.featureDir ?? byName?.featureDir;
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        {repo && featureDir ? (
+          <RequirementView theme={theme} layout={layout} navigation={navigation} repo={repo} featureDir={featureDir} />
+        ) : params.name ? (
+          <Status theme={theme} loading={list.isPending} error={list.error} empty={list.data ? `本机记录中没有需求 ${params.name}。` : null} />
+        ) : (
+          <Text style={s.muted}>没有指定需求。</Text>
+        )}
+      </ScrollView>
+    </View>
+  );
+}

package/paseo-plugin/client/format.ts

@@ -0,0 +1,111 @@
+// Plain-language labels, shared by every screen.
+import type { Attention, Requirement } from "../shared/contracts";
+
+export const ATTENTION_LABELS: Record<Exclude<Attention, null>, string> = {
+  approval: "等待确认方案",
+  business: "等待需求方决定",
+  interrupted: "已中断，可以继续",
+  not_completed: "结束但未完成",
+};
+
+export const TYPE_LABELS: Record<string, string> = { defect: "缺陷", refactor: "重构", assessment: "评估" };
+
+export const PROFILE_LABELS: Record<string, string> = { quick: "快速档", standard: "标准档" };
+
+export const FILE_LABELS: Record<string, string> = {
+  "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": "可以变成规则的问题",
+};
+
+export type Group = "attention" | "running" | "verify" | "done" | "other";
+
+export const GROUP_LABELS: Record<Group, string> = {
+  attention: "需要你处理",
+  running: "进行中",
+  verify: "研发完成，待测试验证",
+  done: "最近完成",
+  other: "其他",
+};
+
+const RECENT_MS = 14 * 24 * 3600_000;
+
+export function groupOf(r: Requirement, now = Date.now()): Group {
+  if (r.attention) return "attention";
+  if (r.running) return "running";
+  if (r.status === "phase_done") return "verify";
+  if (r.status === "completed" && now - Date.parse(r.updatedAt) < RECENT_MS) return "done";
+  return "other";
+}
+
+export function minutes(m: number): string {
+  if (m < 1) return "不到 1 分钟";
+  if (m < 60) return `${Math.round(m)} 分钟`;
+  const h = Math.floor(m / 60);
+  const rest = Math.round(m % 60);
+  return rest === 0 ? `${h} 小时` : `${h} 小时 ${rest} 分`;
+}
+
+export function ago(iso: string, now = Date.now()): string {
+  const m = (now - Date.parse(iso)) / 60_000;
+  if (!Number.isFinite(m)) return "";
+  if (m < 1) return "刚刚";
+  if (m < 60) return `${Math.round(m)} 分钟前`;
+  if (m < 24 * 60) return `${Math.round(m / 60)} 小时前`;
+  return `${Math.round(m / 60 / 24)} 天前`;
+}
+
+export function tokens(n: number | null): string {
+  if (n === null) return "未报告";
+  return n >= 10_000 ? `${Math.round(n / 1_000) / 10} 万` : String(n);
+}
+
+/** One line under a requirement's title: project, type, stage. */
+export function facts(r: Requirement): string {
+  return [r.project, r.type ? TYPE_LABELS[r.type] ?? r.type : null, r.profile ? PROFILE_LABELS[r.profile] ?? r.profile : null]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+/** What a person can do from here, by the requirement's state. */
+export function actionsFor(
+  r: Pick<Requirement, "attention" | "running" | "status"> & { external?: Array<{ pending: number; id: string | null }> },
+): Array<"approve" | "stop" | "resume" | "verify" | "sync"> {
+  const base: Array<"approve" | "stop" | "resume" | "verify" | "sync"> = r.running
+    ? ["stop"]
+    : r.attention === "approval"
+      ? ["approve"]
+      : r.attention === "interrupted" || r.attention === "business"
+        ? ["resume"]
+        : r.status === "phase_done"
+          ? ["verify"]
+          : [];
+  // A running pipeline sends what failed by itself at its next step change.
+  if (!r.running && r.status && (r.external ?? []).some((e) => e.pending > 0 || !e.id)) base.push("sync");
+  return base;
+}
+
+export const ACTION_TEXT = {
+  approve: { label: "确认方案", confirm: "确认 preview.md 中的方案，开始写代码？请先看过确认预览和原型。" },
+  stop: { label: "停止", confirm: "停止这个需求的流水线？正在运行的步骤会被中断，之后可以继续。" },
+  resume: { label: "继续", confirm: "从中断处继续？需求说明改过的话，只处理变化的部分。" },
+  verify: { label: "开始测试验证", confirm: "开始测试验证？选择在哪里验证。" },
+  sync: { label: "同步到外部系统", confirm: "把这个需求同步到对接的外部系统：补发没有成功的调用、补建卡片、更新状态。" },
+} as const;