paseo-req-kit 0.0.0-stage → 1.8.0-beta.3

package/engine/src/state.ts

@@ -0,0 +1,333 @@
+import crypto from "node:crypto";
+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 { AgentUsage } from "./usage.js";
+import type { StepId } from "./steps.js";
+
+/**
+ * "phase_done": the develop phase is done and the run stopped at the gate, waiting for
+ * someone to start the verify phase (phases.mode "gated"). Engines before 1.7 treat an
+ * unknown status as an interrupted run, which continues into verification: acceptable.
+ * "waiting_for_approval" (1.8): the design waits for the requester's confirmation
+ * (designApproval); older engines continue as after an interruption, i.e. without it.
+ */
+export type PipelineStatus = "running" | "waiting_for_business" | "failed" | "completed" | "phase_done" | "waiting_for_approval";
+
+/** Phase names are strings so later phases need no format change. */
+export type PhaseName = "develop" | "verify";
+
+/** Execution mode and verify-phase options a run settled on (absent before 1.7: continuous). */
+export interface RunPhases {
+  mode: PhaseMode;
+  environment: VerifyEnvironment;
+  defects: DefectHandling;
+}
+
+export interface StepRecord {
+  key: string;
+  stepId: StepId;
+  round: number | null;
+  attempt: number;
+  agentId: string;
+  startedAt: string;
+  endedAt: string | null;
+  outcome: "running" | "completed" | "failed";
+  followUps: number;
+  result: Record<string, unknown> | null;
+  error: string | null;
+  /** Latest usage the agent reported for this step; absent in older state files. */
+  usage?: AgentUsage | null;
+  /** Phase the step ran in; absent before 1.7 (develop or verify by step). */
+  phase?: PhaseName;
+}
+
+export interface PipelineState {
+  /** Format version, see STATE_VERSION. */
+  version: number;
+  repo: string;
+  featureDir: string;
+  status: PipelineStatus;
+  /** Incremented every time the pipeline starts over from the design step. */
+  attempt: number;
+  specHash: string;
+  originAgentId: string | null;
+  pid: number;
+  startedAt: string;
+  updatedAt: string;
+  /** Completed step results by step key. A resumed run reuses these instead of re-running the step. */
+  results: Record<string, Record<string, unknown>>;
+  history: StepRecord[];
+  stopReason: string | null;
+  outcome: string | null;
+  /** "quick" or "standard"; decides loop rounds and optional steps. */
+  profile: ProfileName;
+  /** Git branch the run commits to, fixed at launch. Null outside a git repository. */
+  branch: string | null;
+  /** Progress notes already sent, so a resumed run does not repeat them. */
+  milestones: string[];
+  /**
+   * Set when this attempt restarted from design because the requirement changed (or a
+   * business decision was answered): the steps build on the existing design and code
+   * instead of starting over. Absent in older state files.
+   */
+  incremental?: IncrementalInfo | null;
+  /**
+   * Set when the requirement is developed in a worktree created for it (--worktree):
+   * the Paseo workspace and the checkout the chat works in. `repo` is the worktree.
+   */
+  worktree?: { workspaceId: string; sourceRepo: string } | null;
+  /** Paseo schedules this run created (reminders, automatic continuation, watchdog); cancelled by the next run. */
+  schedules?: Array<{ id: string; kind: "reminder" | "auto-resume" | "watchdog" | "verify-start" | "approval-continue"; at: string | null }>;
+  /** Automatic continuations used in this attempt. */
+  autoResumes?: { attempt: number; count: number } | null;
+  /** Set while waiting for a free slot (maxConcurrentPipelines). */
+  queuedSince?: string | null;
+  /** Execution mode of this run; absent in older state files (continuous). */
+  phases?: RunPhases | null;
+  /** Current phase; absent in older state files. */
+  phase?: PhaseName;
+  /** --verify-at: when the verify phase should start once development is done (ISO time). */
+  verifyAt?: string | null;
+  /** How many times the verify phase handed defects back to development (defects "handback"). */
+  handbacks?: number;
+  /** Requirement type with its own playbook, from the spec's "类型" line; absent: the normal flow (1.8). */
+  type?: RequirementType | null;
+  /** Commit before the attempt's first code change; the quality gate's baseline and the scope check start here (1.8). */
+  codeBase?: { attempt: number; commit: string | null } | null;
+  /**
+   * Joint requirement (1.8): other repositories this requirement also changes, each in a
+   * worktree created for it, with its own code base and quality gate. See ADR 0025.
+   */
+  joint?: JointRepo[] | null;
+  /** Design confirmation point (1.8): which attempt's design is waiting or was confirmed. */
+  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;
+}
+
+export interface JointRepo {
+  /** Name in relatedRepos, e.g. "后端". */
+  name: string;
+  /** ASCII key suffix for its steps ("implement@backend"). */
+  slug: string;
+  /** The checkout the worktree was cut from. */
+  sourceRepo: string;
+  /** The worktree the steps work in. */
+  repo: string;
+  workspaceId: string;
+  branch: string;
+  /** Hash of the spec last copied there. */
+  specHash: string | null;
+  codeBase?: { attempt: number; commit: string | null } | null;
+  gate?: { baseline: GateBaseline | null; runs: GateRun[] } | null;
+}
+
+export type CheckOutcome = "pass" | "fail";
+
+export interface GateBaseline {
+  attempt: number;
+  commit: string | null;
+  at: string;
+  results: Record<string, CheckOutcome>;
+}
+
+export interface GateRun {
+  /** Step key the checks ran after, e.g. "implement-s2", "review_fix-r1". */
+  key: string;
+  attempt: number;
+  at: string;
+  /** Checks that applied to the change; "skipped" ones did not touch their paths. */
+  checks: Array<{ name: string; result: CheckOutcome | "skipped"; failedBefore: boolean }>;
+  /** Checks that pass before the change and fail after it: these block. */
+  newFailures: string[];
+  /** Times the step agent was asked to fix them. */
+  fixRounds: number;
+  passed: boolean;
+}
+
+export interface IncrementalInfo {
+  /** Attempt whose work this one continues. */
+  fromAttempt: number;
+  reason: string;
+  /** Commit at the start of this attempt; reviewers look at changes since here. Null outside git. */
+  baseCommit: string | null;
+  /** Whether the previous attempt got as far as writing code. */
+  hadImplementation: boolean;
+}
+
+export function pipelineDir(repo: string, featureDir: string): string {
+  return path.join(repo, featureDir, ".pipeline");
+}
+
+export function statePath(repo: string, featureDir: string): string {
+  return path.join(pipelineDir(repo, featureDir), "state.json");
+}
+
+export function ensurePipelineDir(repo: string, featureDir: string): string {
+  const dir = pipelineDir(repo, featureDir);
+  fs.mkdirSync(path.join(dir, "results"), { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  // Runtime files only; never committed by the step agents.
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
+
+/**
+ * Format version of state.json written by this engine. Bump it when the shape changes
+ * and add a migration from the previous version to STATE_MIGRATIONS.
+ */
+export const STATE_VERSION = 1;
+
+/** Upgrades a state object from version `n` to `n + 1`. */
+export type StateMigration = (state: Record<string, unknown>) => Record<string, unknown>;
+
+/** Keyed by the version a migration upgrades from. */
+export const STATE_MIGRATIONS: Record<number, StateMigration> = {};
+
+export class StateVersionError extends Error {
+  constructor(file: string, found: number, supported: number) {
+    super(
+      `${file} 是由更新版本的 req-kit 写入的（格式第 ${found} 版，当前版本只支持到第 ${supported} 版）。` +
+        "请升级 req-kit 后再操作；如果是回滚到旧版本造成的，可以把同目录下的 state.json.bak-v<旧版本号> 恢复为 state.json，" +
+        "或者删除 state.json 后用 --restart 从头开始。",
+    );
+    this.name = "StateVersionError";
+  }
+}
+
+/**
+ * Brings a parsed state object up to `target`, one version at a time.
+ * Files written before the version field existed count as version 1.
+ */
+export function migrateState(
+  raw: Record<string, unknown>,
+  file: string,
+  migrations: Record<number, StateMigration> = STATE_MIGRATIONS,
+  target: number = STATE_VERSION,
+): { state: Record<string, unknown>; from: number } {
+  const from = typeof raw.version === "number" ? raw.version : 1;
+  if (from > target) throw new StateVersionError(file, from, target);
+  let state = raw;
+  for (let version = from; version < target; version += 1) {
+    const step = migrations[version];
+    if (!step) throw new Error(`缺少 state.json 从第 ${version} 版到第 ${version + 1} 版的迁移`);
+    state = { ...step(state), version: version + 1 };
+  }
+  return { state, from };
+}
+
+/**
+ * Reads state.json, migrating an older format in place. The file as it was is kept
+ * next to it as state.json.bak-v<old version>, so a rollback can restore it.
+ */
+export function readState(
+  file: string,
+  migrations: Record<number, StateMigration> = STATE_MIGRATIONS,
+  target: number = STATE_VERSION,
+): PipelineState | null {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8");
+  const raw = JSON.parse(text) as Record<string, unknown>;
+  const { state, from } = migrateState(raw, file, migrations, target);
+  if (from < target) {
+    const backup = `${file}.bak-v${from}`;
+    if (!fs.existsSync(backup)) fs.writeFileSync(backup, text);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+  }
+  return state as unknown as PipelineState;
+}
+
+export function writeState(file: string, state: PipelineState): void {
+  state.updatedAt = new Date().toISOString();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+export function hashFile(file: string): string {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// One pipeline per repository checkout: the steps switch branches and commit,
+// so two pipelines in the same directory would corrupt each other's work.
+// ---------------------------------------------------------------------------
+
+export interface LockInfo {
+  pid: number;
+  featureDir: string;
+  startedAt: string;
+}
+
+export function lockPath(repo: string): string {
+  const id = crypto.createHash("sha1").update(fs.realpathSync(repo)).digest("hex").slice(0, 12);
+  return path.join(os.tmpdir(), `requirement-pipeline-${id}.lock`);
+}
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** Returns the live holder of the repository lock, or null. Removes a stale lock. */
+export function currentLockHolder(repo: string): LockInfo | null {
+  const file = lockPath(repo);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const info = JSON.parse(fs.readFileSync(file, "utf8")) as LockInfo;
+    if (isAlive(info.pid)) return info;
+  } catch {
+    // Unreadable lock: treat as stale.
+  }
+  fs.rmSync(file, { force: true });
+  return null;
+}
+
+export function acquireLock(repo: string, featureDir: string): () => void {
+  const file = lockPath(repo);
+  const holder = currentLockHolder(repo);
+  if (holder && holder.pid !== process.pid) {
+    throw new LockHeldError(holder);
+  }
+  const info: LockInfo = { pid: process.pid, featureDir, startedAt: new Date().toISOString() };
+  try {
+    fs.writeFileSync(file, JSON.stringify(info), { flag: holder ? "w" : "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      const other = currentLockHolder(repo);
+      if (other) throw new LockHeldError(other);
+      fs.writeFileSync(file, JSON.stringify(info), { flag: "wx" });
+    } else {
+      throw error;
+    }
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    try {
+      const now = JSON.parse(fs.readFileSync(file, "utf8")) as LockInfo;
+      if (now.pid === process.pid) fs.rmSync(file, { force: true });
+    } catch {
+      // Already gone.
+    }
+  };
+}
+
+export class LockHeldError extends Error {
+  constructor(public readonly holder: LockInfo) {
+    super(
+      `这个仓库目录已有一条流水线在运行（进程 ${holder.pid}，功能目录 ${holder.featureDir}，开始于 ${holder.startedAt}）。` +
+        "同一个目录一次只能运行一条，请等它结束。",
+    );
+    this.name = "LockHeldError";
+  }
+}

package/engine/src/steps.ts

@@ -0,0 +1,266 @@
+import type { AgentRole } from "./runtime.js";
+
+export type StepId =
+  | "design"
+  | "design_review"
+  | "design_revise"
+  | "implement"
+  | "code_review"
+  | "review_fix"
+  | "service_start"
+  | "verify"
+  | "defect_fix"
+  | "reverify"
+  | "report"
+  /** Handoff note for testing (提测说明), the last step of the develop phase. */
+  | "handoff"
+  /** One member of the optional review panel; runs before design_review / code_review consolidates. */
+  | "panel_review"
+  /** Independent review of a draft spec before the requester confirms it (run from the chat, not the pipeline). */
+  | "spec_review"
+  /** One of the parallel design proposals that the design step compares (optional). */
+  | "design_proposal";
+
+type FieldSpec =
+  | { kind: "boolean" }
+  | { kind: "enum"; values: readonly string[] }
+  | { kind: "string" }
+  | { kind: "string[]" };
+
+export interface ResultSpec {
+  required: Record<string, FieldSpec>;
+  optional?: Record<string, FieldSpec>;
+  /** Extra cross-field rule; returns an error message or null. */
+  check?: (value: Record<string, unknown>) => string | null;
+}
+
+export interface StepDef {
+  id: StepId;
+  /** Step number in the 11-step list the user defined. */
+  number: number;
+  title: string;
+  role: AgentRole;
+  promptFile: string;
+  result: ResultSpec;
+}
+
+const done: ResultSpec = { required: { status: { kind: "enum", values: ["done", "partial"] } } };
+
+/**
+ * Optional plan fields of the design result (1.8): the implementation slices, the files the
+ * plan expects to change (for the scope check), and for a defect whether it was reproduced.
+ */
+const PLAN_FIELDS: Pick<ResultSpec, "optional"> = {
+  optional: {
+    slices: { kind: "string[]" },
+    files: { kind: "string[]" },
+    reproduced: { kind: "boolean" },
+    questions: { kind: "string[]" },
+    ui_change: { kind: "boolean" },
+  },
+};
+
+/** Review steps that can run with a review panel. */
+export const PANEL_STEPS = ["design_review", "code_review"] as const;
+export type PanelStep = (typeof PANEL_STEPS)[number];
+
+export const STEPS: Record<StepId, StepDef> = {
+  spec_review: {
+    id: "spec_review",
+    number: 2,
+    title: "需求说明审阅",
+    role: "reviewer",
+    promptFile: "02-spec-review.md",
+    result: {
+      required: { verdict: { kind: "enum", values: ["ready", "issues"] } },
+      optional: { issues: { kind: "string[]" } },
+      check: (value) =>
+        value.verdict === "issues" && (!Array.isArray(value.issues) || value.issues.length === 0)
+          ? "verdict 为 issues 时，issues 必须是非空的字符串数组（每条一句话）"
+          : null,
+    },
+  },
+  design_proposal: {
+    id: "design_proposal",
+    number: 3,
+    title: "方案提案",
+    role: "builder",
+    promptFile: "03a-design-proposal.md",
+    result: done,
+  },
+  panel_review: {
+    id: "panel_review",
+    number: 0,
+    title: "评审小组成员",
+    role: "reviewer",
+    promptFile: "panel-member.md",
+    result: done,
+  },
+  design: {
+    id: "design",
+    number: 3,
+    title: "方案设计",
+    role: "builder",
+    promptFile: "03-design.md",
+    result: {
+      required: { has_runnable_service: { kind: "boolean" } },
+      optional: PLAN_FIELDS.optional,
+      check: (value) =>
+        value.reproduced === false && (!Array.isArray(value.questions) || value.questions.length === 0)
+          ? "reproduced 为 false 时，questions 必须是非空的字符串数组：需要需求方补充什么才能复现"
+          : null,
+    },
+  },
+  design_review: {
+    id: "design_review",
+    number: 4,
+    title: "方案审核",
+    role: "reviewer",
+    promptFile: "04-design-review.md",
+    result: {
+      required: { verdict: { kind: "enum", values: ["approved", "changes_required", "blocked"] } },
+      optional: { questions: { kind: "string[]" } },
+      check: (value) =>
+        value.verdict === "blocked" && (!Array.isArray(value.questions) || value.questions.length === 0)
+          ? "verdict 为 blocked 时，questions 必须是非空的字符串数组"
+          : null,
+    },
+  },
+  design_revise: {
+    id: "design_revise",
+    number: 4,
+    title: "方案修订",
+    role: "builder",
+    promptFile: "04b-design-revise.md",
+    result: { required: done.required, optional: { slices: { kind: "string[]" }, files: { kind: "string[]" }, ui_change: { kind: "boolean" } } },
+  },
+  implement: {
+    id: "implement",
+    number: 5,
+    title: "代码实现",
+    role: "builder",
+    promptFile: "05-implement.md",
+    // acceptance_tests: test files written from the AC examples, committed first (in
+    // acceptance_tests_commit); the engine tells the code review when they changed later.
+    result: { required: done.required, optional: { acceptance_tests: { kind: "string[]" }, acceptance_tests_commit: { kind: "string" } } },
+  },
+  code_review: {
+    id: "code_review",
+    number: 6,
+    title: "代码评审",
+    role: "reviewer",
+    promptFile: "06-code-review.md",
+    result: { required: { verdict: { kind: "enum", values: ["pass", "changes_required"] } } },
+  },
+  review_fix: {
+    id: "review_fix",
+    number: 7,
+    title: "评审问题修复",
+    role: "builder",
+    promptFile: "07-review-fix.md",
+    result: done,
+  },
+  handoff: {
+    id: "handoff",
+    number: 7,
+    title: "提测说明",
+    role: "builder",
+    promptFile: "07b-handoff.md",
+    result: done,
+  },
+  service_start: {
+    id: "service_start",
+    number: 8,
+    title: "服务启动验证",
+    role: "builder",
+    promptFile: "08-service-start.md",
+    result: { required: { started: { kind: "boolean" } } },
+  },
+  verify: {
+    id: "verify",
+    number: 9,
+    title: "功能验证",
+    role: "reviewer",
+    promptFile: "09-verify.md",
+    // defect_repos (joint requirements): where the defects are, "本仓库" or a joint repository's name.
+    result: { required: { result: { kind: "enum", values: ["pass", "defects_found", "blocked"] } }, optional: { defect_repos: { kind: "string[]" } } },
+  },
+  defect_fix: {
+    id: "defect_fix",
+    number: 10,
+    title: "缺陷修复",
+    role: "builder",
+    promptFile: "10-defect-fix.md",
+    result: done,
+  },
+  reverify: {
+    id: "reverify",
+    number: 10,
+    title: "复验",
+    role: "reviewer",
+    promptFile: "10b-reverify.md",
+    result: { required: { result: { kind: "enum", values: ["pass", "defects_remaining"] } }, optional: { defect_repos: { kind: "string[]" } } },
+  },
+  report: {
+    id: "report",
+    number: 11,
+    title: "完成报告",
+    role: "builder",
+    promptFile: "11-report.md",
+    result: {
+      required: {
+        outcome: { kind: "enum", values: ["completed", "completed_with_issues", "not_completed"] },
+        summary: { kind: "string" },
+      },
+    },
+  },
+};
+
+function checkField(name: string, spec: FieldSpec, value: unknown): string | null {
+  switch (spec.kind) {
+    case "boolean":
+      return typeof value === "boolean" ? null : `${name} 必须是 true 或 false`;
+    case "string":
+      return typeof value === "string" && value.trim() !== "" ? null : `${name} 必须是非空字符串`;
+    case "string[]":
+      return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? null
+        : `${name} 必须是字符串数组`;
+    case "enum":
+      return typeof value === "string" && spec.values.includes(value)
+        ? null
+        : `${name} 必须是 ${spec.values.map((v) => `"${v}"`).join(" / ")} 之一`;
+  }
+}
+
+export type ValidationResult =
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; error: string };
+
+export function validateResult(spec: ResultSpec, raw: unknown): ValidationResult {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, error: "内容必须是一个 JSON 对象" };
+  }
+  const value = raw as Record<string, unknown>;
+  for (const [name, field] of Object.entries(spec.required)) {
+    if (!(name in value)) return { ok: false, error: `缺少字段 ${name}` };
+    const error = checkField(name, field, value[name]);
+    if (error) return { ok: false, error };
+  }
+  for (const [name, field] of Object.entries(spec.optional ?? {})) {
+    if (name in value && value[name] !== undefined) {
+      const error = checkField(name, field, value[name]);
+      if (error) return { ok: false, error };
+    }
+  }
+  const crossError = spec.check?.(value) ?? null;
+  if (crossError) return { ok: false, error: crossError };
+  return { ok: true, value };
+}
+
+/** Steps of the verify phase; they may use phases.verify.agents. */
+export const VERIFY_PHASE_STEPS: readonly StepId[] = ["service_start", "verify", "defect_fix", "reverify"];
+
+export function stepKey(id: StepId, round: number | null): string {
+  return round === null ? id : `${id}-r${round}`;
+}

package/engine/src/usage.ts

@@ -0,0 +1,67 @@
+// Time and token usage per step, as reported by the agents, and plain-language summaries.
+
+export interface AgentUsage {
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  totalCostUsd?: number;
+}
+
+interface UsageRecord {
+  attempt: number;
+  startedAt: string;
+  endedAt: string | null;
+  usage?: AgentUsage | null;
+}
+
+export interface UsageTotals {
+  steps: number;
+  /** Sum of step durations (steps of a review panel overlap, so this can exceed wall time). */
+  agentMinutes: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+}
+
+function add(total: number | null, value: number | undefined): number | null {
+  return typeof value === "number" ? (total ?? 0) + value : total;
+}
+
+export function totals(records: UsageRecord[], now = new Date()): UsageTotals {
+  let agentMinutes = 0;
+  let inputTokens: number | null = null;
+  let outputTokens: number | null = null;
+  let costUsd: number | null = null;
+  for (const r of records) {
+    const end = r.endedAt ? new Date(r.endedAt) : now;
+    agentMinutes += Math.max(0, (end.getTime() - new Date(r.startedAt).getTime()) / 60_000);
+    inputTokens = add(inputTokens, r.usage?.inputTokens);
+    outputTokens = add(outputTokens, r.usage?.outputTokens);
+    costUsd = add(costUsd, r.usage?.totalCostUsd);
+  }
+  return { steps: records.length, agentMinutes, inputTokens, outputTokens, costUsd };
+}
+
+function tokens(n: number): string {
+  return n >= 10_000 ? `${(n / 10_000).toFixed(1).replace(/\.0$/, "")} 万` : String(n);
+}
+
+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} 分`;
+}
+
+/** e.g. "6 个步骤，agent 合计用时 2 小时 5 分；输入 120 万 tokens，输出 8.3 万 tokens，约 $4.20" */
+export function describeTotals(t: UsageTotals): string {
+  const parts = [`${t.steps} 个步骤，agent 合计用时 ${minutes(t.agentMinutes)}`];
+  const usage: string[] = [];
+  if (t.inputTokens !== null) usage.push(`输入 ${tokens(t.inputTokens)} tokens`);
+  if (t.outputTokens !== null) usage.push(`输出 ${tokens(t.outputTokens)} tokens`);
+  if (t.costUsd !== null) usage.push(`约 $${t.costUsd.toFixed(2)}`);
+  if (usage.length > 0) parts.push(usage.join("，"));
+  else parts.push("agent 没有报告 token 用量");
+  return parts.join("；");
+}