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

package/engine/src/integrations.ts

@@ -0,0 +1,400 @@
+// External system integrations (1.9, ADR 0028): the requirement as a card in the team's
+// requirement management system, kept in step with the pipeline.
+//
+// An integration is a local command line tool (e.g. an ALM's CLI) described in the machine or
+// team configuration: how to create a card, how to change its state, and which state each
+// pipeline event maps to. The engine fills the arguments from the requirement and the card
+// fields the requester confirmed with the spec (card.json, written by /req), runs the tool
+// without a shell, reads the card's id and link from its output and keeps them in the state
+// file. A call that fails is kept in order and sent again before the next one, or with
+// `req sync`. An integration never stops the pipeline.
+
+import { execFile, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { PipelineState } from "./state.js";
+
+export const INTEGRATION_EVENTS = ["started", "approval", "blocked", "phase_done", "verify", "completed", "failed"] as const;
+export type IntegrationEvent = (typeof INTEGRATION_EVENTS)[number];
+
+export const INTEGRATION_EVENT_LABELS: Record<IntegrationEvent, string> = {
+  started: "开始开发",
+  approval: "等待确认方案",
+  blocked: "等待需求方决定",
+  phase_done: "研发完成，待测试",
+  verify: "开始测试验证",
+  completed: "完成",
+  failed: "中断",
+};
+
+/** One command: its arguments, each may contain {placeholders}. */
+export interface IntegrationAction {
+  args: string[];
+}
+
+export interface IntegrationConfig {
+  /** Shown to people, and the key under which the card is kept, e.g. "ALM". */
+  name: string;
+  /** The tool to run, e.g. "shenbing". Found on PATH; npm's .cmd shims on Windows are run through node. */
+  command: string;
+  /** Creates the card. `id` is a regular expression for the card id in its output (the first group, or a group named id); `url` likewise, optional. */
+  create?: IntegrationAction & { id: string; url?: string };
+  /** Changes the card's state; {status} is the mapped state. */
+  status?: IntegrationAction;
+  /** Card state for each pipeline event; "completed_with_issues" and "not_completed" refine "completed". */
+  statusMap?: Partial<Record<IntegrationEvent | "completed_with_issues" | "not_completed", string>>;
+  /** Fields the requester confirms with the spec (card.json): name → what to fill in, for /req. */
+  cardFields?: Record<string, string>;
+  /** Values for {field.<name>} placeholders; a project's integrationDefaults[name] adds to these. */
+  defaults?: Record<string, string>;
+  timeoutSeconds?: number;
+}
+
+/** What is known about a requirement's card, in the state file's `external[name]`. */
+export interface ExternalRecord {
+  id: string | null;
+  url: string | null;
+  /** Last state set on the card. */
+  status: string | null;
+  syncedAt: string | null;
+  /** Calls that failed, oldest first; sent again before the next call and by `req sync`. */
+  pending: Array<{ action: "create" | "status"; event: IntegrationEvent; status: string | null; at: string; attempts: number; error: string }>;
+}
+
+/** The card fields /req writes with the spec: card.json in the feature directory. */
+export interface CardFile {
+  title?: string;
+  body?: string;
+  fields?: Record<string, string>;
+}
+
+export function validateIntegrations(value: unknown): string | null {
+  if (!Array.isArray(value)) return "integrations 必须是数组";
+  const names = new Set<string>();
+  for (const [i, raw] of value.entries()) {
+    const at = `integrations[${i}]`;
+    if (!raw || typeof raw !== "object") return `${at} 必须是对象`;
+    const c = raw as Record<string, unknown>;
+    if (typeof c.name !== "string" || !c.name.trim()) return `${at}.name 必须是名称，例如 "ALM"`;
+    if (names.has(c.name)) return `${at}.name「${c.name}」重复了`;
+    names.add(c.name);
+    if (typeof c.command !== "string" || !c.command.trim()) return `${at}.command 必须是要运行的命令，例如 "shenbing"`;
+    for (const key of ["create", "status"] as const) {
+      const action = c[key] as Record<string, unknown> | undefined;
+      if (action === undefined) continue;
+      if (!action || !Array.isArray(action.args) || !action.args.every((a) => typeof a === "string")) return `${at}.${key}.args 必须是字符串数组`;
+    }
+    const create = c.create as Record<string, unknown> | undefined;
+    if (create) {
+      if (typeof create.id !== "string") return `${at}.create.id 必须是从输出中取卡片编号的正则表达式`;
+      for (const k of ["id", "url"] as const) {
+        if (create[k] === undefined) continue;
+        try {
+          new RegExp(String(create[k]));
+        } catch (error) {
+          return `${at}.create.${k} 不是有效的正则表达式：${(error as Error).message}`;
+        }
+      }
+    }
+    if (c.statusMap !== undefined) {
+      if (!c.statusMap || typeof c.statusMap !== "object") return `${at}.statusMap 必须是对象`;
+      for (const [k, v] of Object.entries(c.statusMap)) {
+        if (![...INTEGRATION_EVENTS, "completed_with_issues", "not_completed"].includes(k)) return `${at}.statusMap 中的 ${k} 不是流水线事件（可用：${INTEGRATION_EVENTS.join("、")}）`;
+        if (typeof v !== "string") return `${at}.statusMap.${k} 必须是字符串`;
+      }
+      if (!c.status) return `${at} 写了 statusMap，但没有 status（改状态的命令）`;
+    }
+    for (const key of ["cardFields", "defaults"] as const) {
+      const m = c[key];
+      if (m === undefined) continue;
+      if (!m || typeof m !== "object" || !Object.values(m).every((v) => typeof v === "string")) return `${at}.${key} 必须是"名称: 文字"的对象`;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Running the tool
+
+/**
+ * How to run `command` without a shell. On Windows an npm-installed tool is a .cmd shim that
+ * only cmd.exe can run, and cmd.exe would mangle arguments such as a Markdown body; the shim
+ * names the script it runs, so run that with node instead.
+ */
+export function resolveCommand(command: string, env: NodeJS.ProcessEnv = process.env): { file: string; prefix: string[] } {
+  if (process.platform !== "win32" || /[\\/]/.test(command) && !/\.cmd$/i.test(command)) return { file: command, prefix: [] };
+  const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+  const candidates = /\.(cmd|exe|bat)$/i.test(command) ? [command] : [`${command}.exe`, `${command}.cmd`];
+  for (const dir of [...(/[\\/]/.test(command) ? [""] : dirs)]) {
+    for (const name of candidates) {
+      const full = dir ? path.join(dir, name) : name;
+      if (!fs.existsSync(full)) continue;
+      if (/\.exe$/i.test(full)) return { file: full, prefix: [] };
+      const text = fs.readFileSync(full, "utf8");
+      const script = /"%(?:~?dp0)%\\?([^"]+?\.(?:c|m)?js)"/i.exec(text)?.[1];
+      if (script) return { file: process.execPath, prefix: [path.join(path.dirname(full), script)] };
+    }
+  }
+  return { file: command, prefix: [] };
+}
+
+export interface RunResult {
+  ok: boolean;
+  output: string;
+  error: string | null;
+}
+
+export type Runner = (command: string, args: string[], timeoutMs: number) => Promise<RunResult>;
+
+export const runCommand: Runner = (command, args, timeoutMs) =>
+  new Promise((resolve) => {
+    const { file, prefix } = resolveCommand(command);
+    execFile(file, [...prefix, ...args], { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+      const output = `${stdout ?? ""}${stderr ? `\n${stderr}` : ""}`.trim();
+      if (error) {
+        const why = (error as NodeJS.ErrnoException).code === "ENOENT" ? `找不到命令 ${command}` : error.killed ? `超过 ${timeoutMs / 1000} 秒没有完成` : (stderr || error.message).trim().split("\n").slice(-2).join(" ");
+        resolve({ ok: false, output, error: why });
+      } else resolve({ ok: true, output, error: null });
+    });
+  });
+
+// ---------------------------------------------------------------------------
+// Arguments
+
+export interface IntegrationContext {
+  repo: string;
+  featureDir: string;
+  state: Pick<PipelineState, "branch" | "profile" | "type" | "outcome" | "external">;
+  /** Project values for {field.*}, from the project's integrationDefaults. */
+  projectDefaults?: Record<string, string>;
+}
+
+function readFile(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export function readCard(repo: string, featureDir: string): CardFile {
+  const raw = readFile(path.join(repo, featureDir, "card.json"));
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as CardFile;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The values arguments can name: {title}, {body}, {card.<field>}, {field.<name>}, {id}, {status}… */
+export function placeholderValues(config: IntegrationConfig, ctx: IntegrationContext, extra: { status?: string | null; event?: IntegrationEvent } = {}): Record<string, string> {
+  const spec = readFile(path.join(ctx.repo, ctx.featureDir, "spec.md")) ?? "";
+  const card = readCard(ctx.repo, ctx.featureDir);
+  const record = ctx.state.external?.[config.name];
+  const values: Record<string, string> = {
+    title: card.title ?? /^#\s+(.+)$/m.exec(spec)?.[1]?.trim() ?? path.basename(ctx.featureDir),
+    body: card.body ?? spec,
+    feature: path.basename(ctx.featureDir),
+    featureDir: ctx.featureDir,
+    repo: ctx.repo,
+    branch: ctx.state.branch ?? "",
+    type: ctx.state.type ?? "",
+    profile: ctx.state.profile,
+    outcome: ctx.state.outcome ?? "",
+    id: record?.id ?? "",
+    url: record?.url ?? "",
+    status: extra.status ?? "",
+    event: extra.event ?? "",
+  };
+  for (const [k, v] of Object.entries({ ...(config.defaults ?? {}), ...(ctx.projectDefaults ?? {}) })) values[`field.${k}`] = v;
+  for (const [k, v] of Object.entries(card.fields ?? {})) values[`card.${k}`] = String(v);
+  // A card field the requester left out falls back to the configured default of the same name.
+  for (const k of Object.keys(config.cardFields ?? {})) if (values[`card.${k}`] === undefined) values[`card.${k}`] = values[`field.${k}`] ?? "";
+  return values;
+}
+
+/**
+ * The arguments with placeholders filled. An argument that is only a placeholder and comes out
+ * empty is dropped together with the option before it ("--priority {card.priority}" → nothing),
+ * so optional fields need no special syntax. Unknown placeholders are an error.
+ */
+export function renderArgs(args: string[], values: Record<string, string>): string[] {
+  const out: string[] = [];
+  for (const arg of args) {
+    const only = /^\{([\w.-]+)\}$/.exec(arg);
+    const rendered = arg.replace(/\{([\w.-]+)\}/g, (_, key: string) => {
+      if (!(key in values)) throw new Error(`参数 ${arg} 中的 {${key}} 没有对应的值`);
+      return values[key];
+    });
+    if (only && rendered === "") {
+      if (out.length > 0 && out.at(-1)!.startsWith("-")) out.pop();
+      continue;
+    }
+    out.push(rendered);
+  }
+  return out;
+}
+
+function capture(pattern: string | undefined, output: string): string | null {
+  if (!pattern) return null;
+  const m = new RegExp(pattern).exec(output);
+  if (!m) return null;
+  return (m.groups?.id ?? m.groups?.url ?? m[1] ?? m[0]).trim();
+}
+
+/** The state an event sets, if any. */
+export function statusFor(config: IntegrationConfig, event: IntegrationEvent, outcome: string | null): string | null {
+  const map = config.statusMap ?? {};
+  if (event === "completed" && (outcome === "completed_with_issues" || outcome === "not_completed") && map[outcome]) return map[outcome] ?? null;
+  return map[event] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Syncing
+
+function emptyRecord(): ExternalRecord {
+  return { id: null, url: null, status: null, syncedAt: null, pending: [] };
+}
+
+/**
+ * Brings one integration up to date for an event: sends what failed before (in order), creates
+ * the card if there is none yet, then sets the event's state. Updates `state.external` in place;
+ * the caller saves the state. Returns lines for the log. Never throws.
+ */
+export async function syncIntegration(input: {
+  config: IntegrationConfig;
+  ctx: IntegrationContext & { state: PipelineState };
+  event: IntegrationEvent | null;
+  run?: Runner;
+  log: (message: string) => void;
+}): Promise<ExternalRecord> {
+  const { config, ctx, log } = input;
+  const run = input.run ?? runCommand;
+  const timeout = (config.timeoutSeconds ?? 60) * 1000;
+  ctx.state.external ??= {};
+  const record = (ctx.state.external[config.name] ??= emptyRecord());
+  const now = () => new Date().toISOString();
+
+  const attempt = async (action: "create" | "status", event: IntegrationEvent, status: string | null): Promise<boolean> => {
+    const def = action === "create" ? config.create : config.status;
+    if (!def) return true;
+    let args: string[];
+    try {
+      args = renderArgs(def.args, placeholderValues(config, ctx, { status, event }));
+    } catch (error) {
+      log(`${config.name}：${(error as Error).message}，没有调用`);
+      return false;
+    }
+    const result = await run(config.command, args, timeout);
+    if (!result.ok) {
+      log(`${config.name}：${action === "create" ? "建卡" : `改为「${status}」`}失败：${result.error}`);
+      const prev = record.pending.find((p) => p.action === action && p.status === status);
+      if (prev) {
+        prev.attempts += 1;
+        prev.error = result.error ?? "";
+      } else {
+        if (action === "status") record.pending = record.pending.filter((p) => p.action !== "status");
+        record.pending.push({ action, event, status, at: now(), attempts: 1, error: result.error ?? "" });
+      }
+      return false;
+    }
+    if (action === "create") {
+      const id = capture(config.create!.id, result.output);
+      if (!id) {
+        log(`${config.name}：建卡命令成功了，但输出中没有找到卡片编号（create.id 的正则没有匹配）。输出：${result.output.slice(0, 300)}`);
+        record.pending.push({ action, event, status, at: now(), attempts: 1, error: "输出中没有卡片编号" });
+        return false;
+      }
+      record.id = id;
+      record.url = capture(config.create!.url, result.output);
+      log(`${config.name}：已建卡 ${id}${record.url ? `（${record.url}）` : ""}`);
+    } else {
+      record.status = status;
+      log(`${config.name}：${record.id} 已改为「${status}」`);
+    }
+    record.syncedAt = now();
+    record.pending = record.pending.filter((p) => !(p.action === action && (action === "create" || p.status === status)));
+    return true;
+  };
+
+  try {
+    // A new state replaces one still waiting to be sent: only the latest matters.
+    const newStatus = input.event ? statusFor(config, input.event, ctx.state.outcome ?? null) : null;
+    if (newStatus) record.pending = record.pending.filter((p) => p.action !== "status");
+    // 1. What failed before, oldest first; stop at the first that still fails, keeping the order.
+    let blocked = false;
+    for (const p of [...record.pending]) {
+      if (p.action === "status" && !record.id) {
+        blocked = true;
+        break;
+      }
+      if ((p.action === "status" && p.status === record.status) || (p.action === "create" && record.id)) {
+        record.pending = record.pending.filter((x) => x !== p);
+        continue;
+      }
+      const index = record.pending.indexOf(p);
+      record.pending.splice(index, 1);
+      if (!(await attempt(p.action, p.event, p.status))) {
+        // attempt() appended it again; put it back where it was so the order holds.
+        const again = record.pending.pop();
+        if (again) record.pending.splice(index, 0, { ...again, attempts: p.attempts + 1, at: p.at });
+        blocked = true;
+        break;
+      }
+    }
+    if (!input.event) return record;
+    // 2. A card for this requirement.
+    if (!record.id && config.create && !blocked) {
+      if (!(await attempt("create", input.event, null))) blocked = true;
+    }
+    // 3. The event's state: now, or queued behind what is still waiting.
+    const status = newStatus;
+    if (status && status !== record.status && !record.pending.some((p) => p.action === "status" && p.status === status)) {
+      // Only the latest state matters: a state still waiting is replaced, not sent after this one.
+      if (blocked || !record.id) {
+        record.pending = record.pending.filter((p) => p.action !== "status");
+        record.pending.push({ action: "status", event: input.event, status, at: now(), attempts: 0, error: "等待前面的调用完成" });
+      }
+      else await attempt("status", input.event, status);
+    }
+  } catch (error) {
+    log(`${config.name}：${(error as Error).message}`);
+  }
+  return record;
+}
+
+/** Plain-language summary lines for status and reports. */
+export function describeExternal(external: PipelineState["external"]): string[] {
+  const lines: string[] = [];
+  for (const [name, r] of Object.entries(external ?? {})) {
+    const head = r.id ? `${name}：${r.id}${r.url ? `（${r.url}）` : ""}${r.status ? `，状态「${r.status}」` : ""}` : `${name}：还没有建卡`;
+    lines.push(r.pending.length > 0 ? `${head}；有 ${r.pending.length} 次调用没有成功，下次自动补发（或 req sync）：${r.pending.at(-1)!.error}` : head);
+  }
+  return lines;
+}
+
+/** For `--card-fields`: what /req should ask for and write to card.json, or null without integrations. */
+export function cardFieldsText(integrations: IntegrationConfig[]): string | null {
+  const withFields = integrations.filter((i) => i.cardFields && Object.keys(i.cardFields).length > 0);
+  if (withFields.length === 0) return null;
+  const lines = [
+    "需求说明确认时，一并和需求方确认下面的卡片字段，写入功能目录的 card.json（和 spec.md 一起提交）：",
+    '{ "title": "<卡片标题，默认用需求说明的标题>", "fields": { "<字段>": "<值>", … } }',
+    "",
+  ];
+  for (const i of withFields) {
+    lines.push(`${i.name}：`);
+    for (const [k, v] of Object.entries(i.cardFields!)) lines.push(`- ${k}：${v}${i.defaults?.[k] ? `（默认 ${i.defaults[k]}）` : ""}`);
+  }
+  lines.push("", "能从需求说明中判断的直接填上请需求方确认；判断不了的问需求方；不知道的可以不写（用默认值或不填）。");
+  return lines.join("\n");
+}
+
+/** Checks that the tool can be found, for the doctor. */
+export function commandAvailable(command: string): boolean {
+  const { file, prefix } = resolveCommand(command);
+  const r = spawnSync(file, [...prefix, "--help"], { encoding: "utf8", timeout: 20_000, windowsHide: true });
+  return !r.error;
+}

package/engine/src/launch.ts

@@ -13,6 +13,7 @@ import { scheduledStartPrompt } from "./messages.js";
 import { describeTime, parseStartTime } from "./schedule-time.js";
 import { moveToOwnWorktree, type OwnWorktree } from "./worktree.js";
 import { loadConfig, PHASE_MODE_LABELS, type PipelineConfig, PROFILE_LABELS } from "./config.js";
+import { cardFieldsText } from "./integrations.js";
 import { defaultConfigPath, ENGINE_DIR } from "./locations.js";
 import { describeLiveActivity, describeStatus, stopPipeline } from "./control.js";
 import { describeFeatures, featuresWithRuns, findWorktreeRun, listFeatures, resolveFeatureArg } from "./features.js";
@@ -79,6 +80,17 @@ try {
 }
 const configPath = args.configPath ?? defaultConfigPath();
 
+if (args.cardFields) {
+  try {
+    const text = cardFieldsText(loadConfig(configPath, fs.existsSync(args.repo) ? args.repo : undefined).config.integrations);
+    console.log(text ?? "没有配置外部系统对接（integrations），不需要 card.json，跳过这一步。");
+    process.exit(0);
+  } catch (error) {
+    console.error((error as Error).message);
+    process.exit(2);
+  }
+}
+
 if (args.list) {
   console.log(describeFeatures(listFeatures(args.repo), args.repo));
   process.exit(0);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.9.0-beta.2",
+  "version": "1.9.1",
   "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",

package/paseo-plugin/client/detail.tsx

@@ -2,11 +2,13 @@
 // 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"];
@@ -64,9 +66,7 @@ function DocumentModal({
         <Status theme={theme} loading={doc.isPending} error={doc.error} />
         {doc.data ? (
           <>
-            <Text selectable style={[s.text, { lineHeight: 21 }]}>
-              {doc.data.content}
-            </Text>
+            <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}
@@ -221,6 +221,32 @@ export function RequirementView({
         ))}
       </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>

package/paseo-plugin/client/format.ts

@@ -85,12 +85,21 @@ export function facts(r: Requirement): string {
 }
 
 /** 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 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 = {
@@ -98,4 +107,5 @@ export const ACTION_TEXT = {
   stop: { label: "停止", confirm: "停止这个需求的流水线？正在运行的步骤会被中断，之后可以继续。" },
   resume: { label: "继续", confirm: "从中断处继续？需求说明改过的话，只处理变化的部分。" },
   verify: { label: "开始测试验证", confirm: "开始测试验证？选择在哪里验证。" },
+  sync: { label: "同步到外部系统", confirm: "把这个需求同步到对接的外部系统：补发没有成功的调用、补建卡片、更新状态。" },
 } as const;