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

package/paseo-plugin/client/detail.tsx

@@ -0,0 +1,277 @@
+// 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 { 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 { 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 ? (
+          <>
+            <Text selectable style={[s.text, { lineHeight: 21 }]}>
+              {doc.data.content}
+            </Text>
+            {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.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,101 @@
+// 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">): Array<"approve" | "stop" | "resume" | "verify"> {
+  if (r.running) return ["stop"];
+  if (r.attention === "approval") return ["approve"];
+  if (r.attention === "interrupted" || r.attention === "business") return ["resume"];
+  if (r.status === "phase_done") return ["verify"];
+  return [];
+}
+
+export const ACTION_TEXT = {
+  approve: { label: "确认方案", confirm: "确认 preview.md 中的方案，开始写代码？请先看过确认预览和原型。" },
+  stop: { label: "停止", confirm: "停止这个需求的流水线？正在运行的步骤会被中断，之后可以继续。" },
+  resume: { label: "继续", confirm: "从中断处继续？需求说明改过的话，只处理变化的部分。" },
+  verify: { label: "开始测试验证", confirm: "开始测试验证？选择在哪里验证。" },
+} as const;

package/paseo-plugin/client/live.ts

@@ -0,0 +1,161 @@
+// Buttons that follow Paseo's agents and workspaces (registered outside React):
+//   - a pill on every step agent of a requirement: which requirement, opens it;
+//   - a header button on every workspace that has requirements: how many need a person.
+import type { PluginButtonRegistration, PluginClientContext } from "@getpaseo/plugin/client";
+import { listRpc, type Requirement } from "../shared/contracts";
+import { inWorkspace } from "./panel";
+
+/** The step agents' labels (req-kit's runtime sets them when it starts a step). */
+const PIPELINE_LABEL = "requirement-pipeline";
+
+interface AgentLike {
+  id: string;
+  workspaceId?: string | null;
+  labels?: Record<string, string> | null;
+}
+
+interface WorkspaceLike {
+  id: string;
+  workspaceDirectory?: string;
+  projectRootPath?: string;
+}
+
+export function contributeLive(client: PluginClientContext): () => void {
+  const lifetime = new AbortController();
+  const pills = new Map<string, PluginButtonRegistration>();
+  const headers = new Map<string, PluginButtonRegistration>();
+  const workspaces = new Map<string, WorkspaceLike>();
+  let requirements: Requirement[] = [];
+
+  // ----- pills on step agents
+  const registerAgent = (agent: AgentLike) => {
+    pills.get(agent.id)?.remove();
+    pills.delete(agent.id);
+    const name = agent.labels?.[PIPELINE_LABEL];
+    if (lifetime.signal.aborted || !name || !agent.workspaceId) return;
+    pills.set(
+      agent.id,
+      client.addComposerPill({
+        id: "requirement",
+        workspaceId: agent.workspaceId,
+        agentId: agent.id,
+        button: {
+          title: `打开需求 ${name}`,
+          icon: "ClipboardList",
+          label: "需求",
+          behavior: { kind: "action", onPress: () => client.openScreen({ screenId: "requirement", params: { name } }) },
+        },
+      }),
+    );
+  };
+  void client.paseo.agents
+    .list({ subscribe: {}, signal: lifetime.signal })
+    .then(({ subscription }) => {
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          for (const pill of pills.values()) pill.remove();
+          pills.clear();
+          for (const { agent } of entries) registerAgent(agent as AgentLike);
+        },
+        update: (message) => {
+          if (message.type !== "agent_update") return;
+          const update = message.payload;
+          if (update.kind === "remove") {
+            pills.get(update.agentId)?.remove();
+            pills.delete(update.agentId);
+          } else registerAgent(update.agent as AgentLike);
+        },
+      });
+      return undefined;
+    })
+    .catch((error: Error) => {
+      if (!lifetime.signal.aborted) console.error("[req-kit] 读取 agent 列表失败", error);
+    });
+
+  // ----- header buttons on workspaces with requirements
+  const refreshHeaders = () => {
+    for (const [id, ws] of workspaces) {
+      const mine = inWorkspace(requirements, ws.workspaceDirectory ?? ws.projectRootPath, id);
+      const existing = headers.get(id);
+      if (mine.length === 0) {
+        existing?.remove();
+        headers.delete(id);
+        continue;
+      }
+      const waiting = mine.filter((r) => r.attention).length;
+      const label = waiting > 0 ? `需求 · 待处理 ${waiting}` : `需求 ${mine.length}`;
+      if (existing) existing.update({ label });
+      else
+        headers.set(
+          id,
+          client.addHeaderButton({
+            id: "requirements",
+            workspaceId: id,
+            button: {
+              title: "这个工作区的需求",
+              icon: "ClipboardList",
+              label,
+              behavior: { kind: "action", onPress: () => client.openPanel("requirements", { workspaceId: id }) },
+            },
+          }),
+        );
+    }
+    for (const [id, button] of headers) {
+      if (!workspaces.has(id)) {
+        button.remove();
+        headers.delete(id);
+      }
+    }
+  };
+  const poll = async () => {
+    try {
+      requirements = await client.rpc(listRpc, {});
+      refreshHeaders();
+    } catch {
+      // req-kit missing or too old: the overview explains; no header buttons meanwhile.
+    }
+  };
+  let releaseWorkspaces: (() => void) | null = null;
+  void client.paseo.workspaces
+    .list({ subscribe: {} })
+    .then(({ subscription }) => {
+      // The workspace list takes no abort signal: release it here or at cleanup.
+      releaseWorkspaces = () => void subscription.release().catch(() => undefined);
+      if (lifetime.signal.aborted) {
+        releaseWorkspaces();
+        return undefined;
+      }
+      subscription.subscribe({
+        snapshot: ({ entries }) => {
+          workspaces.clear();
+          for (const ws of entries) workspaces.set(ws.id, ws as WorkspaceLike);
+          refreshHeaders();
+        },
+        update: (message) => {
+          if (message.type !== "workspace_update") return;
+          const update = message.payload as { kind: string; workspace?: WorkspaceLike; workspaceId?: string; id?: string };
+          if (update.kind === "upsert" && update.workspace) workspaces.set(update.workspace.id, update.workspace);
+          else {
+            const id = update.workspaceId ?? update.id;
+            if (id) workspaces.delete(id);
+          }
+          refreshHeaders();
+        },
+      });
+      return undefined;
+    })
+    .catch((error: Error) => {
+      if (!lifetime.signal.aborted) console.error("[req-kit] 读取工作区列表失败", error);
+    });
+  void poll();
+  const timer = setInterval(() => void poll(), 30_000);
+
+  return () => {
+    lifetime.abort();
+    releaseWorkspaces?.();
+    clearInterval(timer);
+    for (const b of [...pills.values(), ...headers.values()]) b.remove();
+    pills.clear();
+    headers.clear();
+  };
+}

package/paseo-plugin/client/overview.tsx

@@ -0,0 +1,89 @@
+// The overview: every requirement on this machine, grouped by what it needs.
+import type { PluginOpenScreenInput, PluginScreenProps } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { useMemo, useState } from "react";
+import { Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { useRequirements } from "./data";
+import { type Group, GROUP_LABELS, groupOf } from "./format";
+import { RequirementRow } from "./row";
+import { Button, Chip, Status, useStyles } from "./ui";
+
+export const ORDER: Group[] = ["attention", "running", "verify", "done", "other"];
+
+/** Opens a requirement's detail screen. */
+export type OpenRequirement = (item: Pick<Requirement, "repo" | "featureDir" | "title">) => void;
+
+export function RequirementGroups({
+  theme,
+  layout,
+  items,
+  open,
+}: Pick<PluginScreenProps, "theme" | "layout"> & { items: Requirement[]; open: OpenRequirement }) {
+  const s = useStyles(theme, layout.compact);
+  const [showOther, setShowOther] = useState(false);
+  const groups = useMemo(() => {
+    const map = new Map<Group, Requirement[]>();
+    for (const item of items) map.set(groupOf(item), [...(map.get(groupOf(item)) ?? []), item]);
+    return map;
+  }, [items]);
+  return (
+    <View style={{ gap: 20 }}>
+      {ORDER.filter((g) => groups.has(g)).map((g) => (
+        <View key={g} style={{ gap: 8 }}>
+          <View style={s.row}>
+            <Text style={s.heading}>
+              {GROUP_LABELS[g]}（{groups.get(g)!.length}）
+            </Text>
+            {g === "other" ? <Button theme={theme} label={showOther ? "收起" : "展开"} onPress={() => setShowOther((v) => !v)} /> : null}
+          </View>
+          {g === "other" && !showOther
+            ? null
+            : groups.get(g)!.map((item) => <RequirementRow key={item.key} theme={theme} layout={layout} item={item} onPress={() => open(item)} />)}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/** Screens open other screens through the client context; index.client.tsx passes it in. */
+export type ScreenOpener = (input: PluginOpenScreenInput) => void;
+
+export function requirementOpener(openScreen: ScreenOpener): OpenRequirement {
+  return (item) => openScreen({ screenId: "requirement", params: { repo: item.repo, featureDir: item.featureDir, title: item.title } });
+}
+
+export function OverviewScreen(props: PluginScreenProps & { openScreen: ScreenOpener }) {
+  const { theme, layout } = props;
+  const s = useStyles(theme, layout.compact);
+  const query = useRequirements();
+  const [project, setProject] = useState<string | null>(null);
+  const items = query.data ?? [];
+  const projects = useMemo(() => [...new Set(items.map((i) => i.project))].sort(), [items]);
+  const shown = project ? items.filter((i) => i.project === project) : items;
+  const open = requirementOpener(props.openScreen);
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        <View style={s.row}>
+          <Button theme={theme} label="使用统计" onPress={() => props.openScreen({ screenId: "stats" })} />
+        </View>
+        {projects.length > 1 ? (
+          <View style={s.row}>
+            <Chip theme={theme} label="全部项目" active={project === null} onPress={() => setProject(null)} />
+            {projects.map((p) => (
+              <Chip key={p} theme={theme} label={p} active={project === p} onPress={() => setProject(p)} />
+            ))}
+          </View>
+        ) : null}
+        <Status
+          theme={theme}
+          loading={query.isPending}
+          error={query.error}
+          empty={query.data && items.length === 0 ? "这台机器上还没有记录任何需求。在 Paseo 对话中用 /req 开始一个；1.9 之前运行过的需求，在项目目录运行 req index --rebuild。" : null}
+        />
+        <RequirementGroups theme={theme} layout={layout} items={shown} open={open} />
+      </ScrollView>
+    </View>
+  );
+}

package/paseo-plugin/client/panel.tsx

@@ -0,0 +1,56 @@
+// The panel beside a workspace: the requirements developed in it or started from it.
+import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin/client";
+import { ScrollView } from "@getpaseo/plugin/client/react-native";
+import { useState } from "react";
+import { Text, View } from "react-native";
+import type { Requirement } from "../shared/contracts";
+import { useRequirements } from "./data";
+import { RequirementView } from "./detail";
+import { RequirementGroups } from "./overview";
+import { Button, Status, useStyles } from "./ui";
+
+/** Same directory, ignoring a trailing separator and (on Windows) case. */
+export function sameDir(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (!a || !b) return false;
+  const norm = (p: string) => p.replace(/[\\/]+$/, "").replace(/\\/g, "/");
+  const x = norm(a);
+  const y = norm(b);
+  return /^[a-z]:\//i.test(x) ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+
+export function inWorkspace(items: Requirement[], directory: string | null | undefined, workspaceId?: string | null): Requirement[] {
+  return items.filter((r) => (workspaceId && r.workspaceId === workspaceId) || sameDir(r.repo, directory) || sameDir(r.sourceRepo, directory));
+}
+
+export function WorkspacePanel({ theme, layout, navigation, workspaceId }: PluginWorkspacePanelProps) {
+  const s = useStyles(theme, layout.compact);
+  const workspace = useWorkspace(workspaceId, (w) => ({ directory: w.directory, name: w.name }));
+  const query = useRequirements();
+  const [picked, setPicked] = useState<Pick<Requirement, "repo" | "featureDir"> | null>(null);
+  const items = inWorkspace(query.data ?? [], workspace?.directory, workspaceId);
+  const only = items.length === 1 ? items[0] : null;
+  const shown = picked ?? only;
+  return (
+    <View style={s.screen}>
+      <ScrollView contentContainerStyle={s.body}>
+        <Status
+          theme={theme}
+          loading={query.isPending}
+          error={query.error}
+          empty={query.data && items.length === 0 ? `${workspace?.name ?? "这个工作区"}还没有需求。在对话中用 /req 开始一个。` : null}
+        />
+        {shown ? (
+          <>
+            {picked && !only ? <Button theme={theme} label="返回列表" onPress={() => setPicked(null)} /> : null}
+            <RequirementView theme={theme} layout={layout} navigation={navigation} repo={shown.repo} featureDir={shown.featureDir} />
+          </>
+        ) : items.length > 1 ? (
+          <>
+            <Text style={s.muted}>这个工作区有 {items.length} 个需求</Text>
+            <RequirementGroups theme={theme} layout={layout} items={items} open={(item) => setPicked(item)} />
+          </>
+        ) : null}
+      </ScrollView>
+    </View>
+  );
+}