@zmzai/theme 0.2.13 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmzai/theme",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "zmzai 全品牌设计系统 — Radix UI + framer-motion + Tailwind v4 + MiSans",
@@ -94,7 +94,10 @@
     "@radix-ui/react-select": "^2.1.0",
     "@radix-ui/react-tooltip": "^1.1.0",
     "class-variance-authority": "^0.7.0",
-    "framer-motion": "^11.0.0"
+    "framer-motion": "^11.0.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "highlight.js": "^11.11.1"
   },
   "packageManager": "pnpm@10.34.5+sha512.a4ee05f2f73658255bd6a89859c065a45c28a57daefae2c893a168ee2b73168c37b91e83e57ea67654ad03f03031746430e8bce38e362e042605fb8abc80192e"
 }

package/src/components/diff-view/DiffView.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { parseUnifiedDiff, type DiffFile, type DiffLine } from "./parse-unified-diff";
+import "./diff-view.css";
+
+function DiffLineRow({ line, index }: { line: DiffLine; index: number }) {
+  if (line.type === "hunk") {
+    return <div className="diff-line hunk" key={index}><span className="diff-gutter">@@</span><span className="diff-text">{line.text.replace(/^@@ /, "").replace(/ @@$/, "")}</span></div>;
+  }
+  if (line.type === "meta") {
+    return <div className="diff-line meta" key={index}><span className="diff-gutter" /><span className="diff-text">{line.text}</span></div>;
+  }
+  const gutter = line.type === "add" ? "+" : line.type === "remove" ? "−" : " ";
+  return (
+    <div className={`diff-line ${line.type}`} key={index}>
+      <span className="diff-gutter">{gutter}</span>
+      <span className="diff-text">{line.text || " "}</span>
+    </div>
+  );
+}
+
+function DiffFileBlock({ file }: { file: DiffFile }) {
+  return (
+    <section className="diff-file">
+      <header className="diff-file-head">
+        <span className="diff-file-path">{file.newPath ?? file.oldPath ?? "(未知文件)"}</span>
+        <span className="diff-file-stats">
+          {file.additions > 0 && <em className="diff-add-count">+{file.additions}</em>}
+          {file.deletions > 0 && <em className="diff-del-count">−{file.deletions}</em>}
+        </span>
+      </header>
+      {file.hunks.map((hunk, hunkIndex) => (
+        <div className="diff-hunk" key={hunkIndex}>
+          {hunk.lines.map((line, lineIndex) => <DiffLineRow line={line} index={lineIndex} key={lineIndex} />)}
+        </div>
+      ))}
+    </section>
+  );
+}
+
+/**
+ * DiffView — Codex-style colored unified diff renderer.
+ *
+ * Falls back to a plain mono block when the diff text cannot be parsed
+ * into known structure.
+ *
+ * @example
+ * <DiffView diff={unifiedDiffText} />
+ */
+export function DiffView({ diff }: { diff: string }) {
+  const parsed = useMemo(() => parseUnifiedDiff(diff), [diff]);
+  if (!parsed.files.length) {
+    return <pre className="diff-preview">{diff}</pre>;
+  }
+  return (
+    <div className="diff-canvas">
+      <div className="diff-summary">
+        <span>{parsed.files.length} 个文件</span>
+        <span className="diff-summary-stats">
+          {parsed.additions > 0 && <em className="diff-add-count">+{parsed.additions}</em>}
+          {parsed.deletions > 0 && <em className="diff-del-count">−{parsed.deletions}</em>}
+        </span>
+      </div>
+      {parsed.files.map((file, index) => <DiffFileBlock file={file} key={index} />)}
+    </div>
+  );
+}

package/src/components/diff-view/diff-view.css

@@ -0,0 +1,22 @@
+/* DiffView — Codex 式彩色 unified diff。token 依赖消费端 @theme（ink/line/surface/accent/success）。 */
+.diff-canvas { display: grid; gap: 0.85rem; }
+.diff-summary { display: flex; justify-content: space-between; gap: 0.75rem; font-family: var(--font-mono); font-size: 0.625rem; letter-spacing: 0.07em; text-transform: uppercase; color: var(--color-muted); }
+.diff-summary-stats { display: inline-flex; gap: 0.5rem; }
+.diff-add-count { color: var(--color-success); font-style: normal; }
+.diff-del-count { color: #b03a28; font-style: normal; }
+.diff-file { border: 1px solid var(--color-line); border-radius: var(--radius); background: var(--color-surface); overflow: hidden; }
+.diff-file-head { display: flex; align-items: center; justify-content: space-between; gap: 0.75rem; padding: 0.4rem 0.6rem; border-bottom: 1px solid var(--color-line); background: var(--color-surface-strong); }
+.diff-file-path { font-family: var(--font-mono); font-size: 0.6875rem; color: var(--color-ink); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.diff-file-stats { display: inline-flex; gap: 0.5rem; font-family: var(--font-mono); font-size: 0.625rem; }
+.diff-hunk { display: grid; }
+.diff-line { display: grid; grid-template-columns: 1.25rem minmax(0, 1fr); font-family: var(--font-mono); font-size: 0.65625rem; line-height: 1.6; }
+.diff-gutter { text-align: center; user-select: none; }
+.diff-text { padding-left: 0.5rem; white-space: pre-wrap; overflow-wrap: anywhere; }
+.diff-line.hunk { background: color-mix(in oklab, var(--color-accent-ink) 82%, var(--color-accent)); color: var(--color-accent-strong); }
+.diff-line.add { background: color-mix(in oklab, var(--color-success) 16%, var(--color-surface)); color: var(--color-ink); }
+.diff-line.remove { background: color-mix(in oklab, #b03a28 14%, var(--color-surface)); color: var(--color-ink); }
+.diff-line.meta { color: var(--color-muted); background: var(--color-surface); }
+.diff-line.context { color: var(--color-muted); background: var(--color-surface); }
+.diff-line.add .diff-gutter { color: var(--color-success); }
+.diff-line.remove .diff-gutter { color: #b03a28; }
+.diff-preview { max-height: min(48dvh, 34rem); margin: 0; overflow: auto; padding: 0.75rem; border: 1px solid var(--color-line); background: var(--color-ink); color: var(--color-paper); font-family: var(--font-mono); font-size: 0.65625rem; line-height: 1.7; white-space: pre-wrap; overflow-wrap: anywhere; }

package/src/components/diff-view/index.ts

@@ -0,0 +1,2 @@
+export * from "./DiffView";
+export * from "./parse-unified-diff";

package/src/components/diff-view/parse-unified-diff.ts

@@ -0,0 +1,94 @@
+export type DiffLine =
+  | { type: "hunk"; oldStart: number; newStart: number; text: string }
+  | { type: "context"; text: string }
+  | { type: "add"; text: string }
+  | { type: "remove"; text: string }
+  | { type: "meta"; text: string };
+
+export type DiffFile = {
+  oldPath: string | null;
+  newPath: string | null;
+  additions: number;
+  deletions: number;
+  hunks: Array<{ oldStart: number; newStart: number; lines: DiffLine[] }>;
+};
+
+export type UnifiedDiff = {
+  files: DiffFile[];
+  additions: number;
+  deletions: number;
+};
+
+function parseHunkHeader(line: string): { oldStart: number; newStart: number } | null {
+  const match = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+  if (!match) return null;
+  return { oldStart: Number.parseInt(match[1], 10), newStart: Number.parseInt(match[2], 10) };
+}
+
+/**
+ * Parses a unified diff (as produced by `git diff` / `createUnifiedDiff`)
+ * into structured files/hunks/lines so UIs can render Codex-style colored
+ * changes instead of a raw <pre>. Unknown lines degrade to context.
+ */
+export function parseUnifiedDiff(input: string): UnifiedDiff {
+  const files: DiffFile[] = [];
+  let current: DiffFile | null = null;
+  let currentHunk: { oldStart: number; newStart: number; lines: DiffLine[] } | null = null;
+  let additions = 0;
+  let deletions = 0;
+
+  for (const raw of input.split("\n")) {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (line.startsWith("diff --git ") || (line.startsWith("--- ") && current !== null && current.oldPath !== null)) {
+      if (current && currentHunk) {
+        current.hunks.push(currentHunk);
+        currentHunk = null;
+      }
+      current = { oldPath: null, newPath: null, additions: 0, deletions: 0, hunks: [] };
+      files.push(current);
+      if (line.startsWith("diff --git ")) continue;
+    }
+    if (line.startsWith("--- ")) {
+      if (!current) {
+        current = { oldPath: null, newPath: null, additions: 0, deletions: 0, hunks: [] };
+        files.push(current);
+      }
+      current.oldPath = line.slice(4).replace(/^(a|b)\//, "");
+      continue;
+    }
+    if (line.startsWith("+++ ")) {
+      if (!current) {
+        current = { oldPath: null, newPath: null, additions: 0, deletions: 0, hunks: [] };
+        files.push(current);
+      }
+      current.newPath = line.slice(4).replace(/^(a|b)\//, "");
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      const header = parseHunkHeader(line);
+      if (current && header) {
+        if (currentHunk) current.hunks.push(currentHunk);
+        currentHunk = { oldStart: header.oldStart, newStart: header.newStart, lines: [] };
+        currentHunk.lines.push({ type: "hunk", oldStart: header.oldStart, newStart: header.newStart, text: line });
+      }
+      continue;
+    }
+    if (!current || !currentHunk) continue;
+    if (line.startsWith("+")) {
+      currentHunk.lines.push({ type: "add", text: line.slice(1) });
+      current.additions += 1;
+      additions += 1;
+    } else if (line.startsWith("-")) {
+      currentHunk.lines.push({ type: "remove", text: line.slice(1) });
+      current.deletions += 1;
+      deletions += 1;
+    } else if (line.startsWith("\\")) {
+      currentHunk.lines.push({ type: "meta", text: line });
+    } else {
+      currentHunk.lines.push({ type: "context", text: line.startsWith(" ") ? line.slice(1) : line });
+    }
+  }
+
+  if (current && currentHunk) current.hunks.push(currentHunk);
+  return { files, additions, deletions };
+}

package/src/components/index.ts

@@ -48,6 +48,13 @@ export * from "./code-block";
 export * from "./multi-step-loader";
 export * from "./timeline";
 
+// === Business (agent workflow) ===
+export * from "./markdown";
+export * from "./diff-view";
+export * from "./tool-card";
+export * from "./todo-checklist";
+export * from "./permission-card";
+
 // === Text Effects ===
 export * from "./text-generate";
 export * from "./encrypt-text";

package/src/components/markdown/Markdown.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { Children, memo, useMemo, useState, type ReactElement, type ReactNode } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import hljs from "highlight.js/lib/core";
+
+import bash from "highlight.js/lib/languages/bash";
+import css from "highlight.js/lib/languages/css";
+import javascript from "highlight.js/lib/languages/javascript";
+import json from "highlight.js/lib/languages/json";
+import markdownLang from "highlight.js/lib/languages/markdown";
+import plaintext from "highlight.js/lib/languages/plaintext";
+import python from "highlight.js/lib/languages/python";
+import typescript from "highlight.js/lib/languages/typescript";
+import xml from "highlight.js/lib/languages/xml";
+
+import "./markdown.css";
+
+// Curated language set keeps the client bundle small; every other language
+// falls back to plain text.
+hljs.registerLanguage("bash", bash);
+hljs.registerLanguage("sh", bash);
+hljs.registerLanguage("shell", bash);
+hljs.registerLanguage("css", css);
+hljs.registerLanguage("javascript", javascript);
+hljs.registerLanguage("js", javascript);
+hljs.registerLanguage("jsx", javascript);
+hljs.registerLanguage("json", json);
+hljs.registerLanguage("markdown", markdownLang);
+hljs.registerLanguage("plaintext", plaintext);
+hljs.registerLanguage("text", plaintext);
+hljs.registerLanguage("python", python);
+hljs.registerLanguage("py", python);
+hljs.registerLanguage("typescript", typescript);
+hljs.registerLanguage("ts", typescript);
+hljs.registerLanguage("tsx", typescript);
+hljs.registerLanguage("xml", xml);
+hljs.registerLanguage("html", xml);
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// Streaming deltas re-render frequently; memoize highlight output per exact
+// (language, code) pair so only changed blocks pay for highlighting.
+const highlightCache = new Map<string, string>();
+
+function highlightCode(code: string, language: string | undefined): string {
+  const key = `${language ?? ""}\u0000${code}`;
+  const cached = highlightCache.get(key);
+  if (cached !== undefined) return cached;
+  let html: string;
+  if (language && hljs.getLanguage(language)) {
+    try {
+      html = hljs.highlight(code, { language }).value;
+    } catch {
+      html = escapeHtml(code);
+    }
+  } else {
+    html = escapeHtml(code);
+  }
+  if (highlightCache.size > 600) highlightCache.clear();
+  highlightCache.set(key, html);
+  return html;
+}
+
+function CodeBlock({ language, code }: { language: string | undefined; code: string }) {
+  const [copied, setCopied] = useState(false);
+  const html = useMemo(() => highlightCode(code, language), [code, language]);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // Clipboard unavailable (e.g. non-secure context); the block stays readable.
+    }
+  };
+  return (
+    <div className="md-codeblock">
+      <div className="md-codeblock-head">
+        <span>{language ?? "text"}</span>
+        <button type="button" className="md-copy" onClick={() => void copy()}>{copied ? "已复制" : "复制"}</button>
+      </div>
+      <pre><code className={language ? `language-${language}` : undefined} dangerouslySetInnerHTML={{ __html: html }} /></pre>
+    </div>
+  );
+}
+
+/**
+ * Markdown — streaming GFM renderer.
+ *
+ * `message.delta` chunks can be fed as partial markdown; block rendering
+ * stays stable while the text grows. Fenced code blocks render as
+ * highlighted cards with a copy button; bare code is inline.
+ *
+ * @example
+ * <Markdown text={streamingText} />
+ */
+export const Markdown = memo(function Markdown({ text }: { text: string }) {
+  return (
+    <div className="markdown-body">
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        components={{
+          // react-markdown feeds every fenced block through <pre><code>. We
+          // intercept the pre to render a highlighted block with a copy
+          // button; bare <code> is inline.
+          pre({ children }) {
+            const child = Children.only(children) as ReactElement<{ className?: string; children?: ReactNode }>;
+            const className = typeof child?.props?.className === "string" ? child.props.className : undefined;
+            const match = /language-(\w+)/.exec(className ?? "");
+            const code = String(child?.props?.children ?? "").replace(/\n$/, "");
+            return <CodeBlock language={match?.[1]} code={code} />;
+          },
+          code({ className, children, ...props }) {
+            return <code className={className} {...props}>{children}</code>;
+          },
+          a({ children, ...props }) {
+            return <a {...props} target="_blank" rel="noreferrer">{children}</a>;
+          },
+        }}
+      >{text}</ReactMarkdown>
+    </div>
+  );
+});

package/src/components/markdown/index.ts

@@ -0,0 +1 @@
+export * from "./Markdown";

package/src/components/markdown/markdown.css

@@ -0,0 +1,37 @@
+/* Markdown — GFM 流式渲染 + hljs 暖墨代码主题。token 依赖消费端 @theme。 */
+.markdown-body { min-width: 0; font-size: 0.9375rem; line-height: 1.7; overflow-wrap: anywhere; }
+.markdown-body > :first-child { margin-top: 0; }
+.markdown-body > :last-child { margin-bottom: 0; }
+.markdown-body p { margin: 0.6rem 0; }
+.markdown-body h1, .markdown-body h2, .markdown-body h3, .markdown-body h4 { margin: 1.2rem 0 0.5rem; line-height: 1.35; letter-spacing: -0.01em; }
+.markdown-body h1 { font-size: 1.25rem; } .markdown-body h2 { font-size: 1.125rem; } .markdown-body h3, .markdown-body h4 { font-size: 1rem; }
+.markdown-body ul, .markdown-body ol { margin: 0.6rem 0; padding-left: 1.35rem; }
+.markdown-body li { margin: 0.25rem 0; }
+.markdown-body blockquote { margin: 0.7rem 0; padding-left: 0.9rem; border-left: 3px solid var(--color-ink); color: var(--color-muted); }
+.markdown-body a { color: var(--color-accent-strong); text-decoration: underline; text-underline-offset: 2px; }
+.markdown-body a:hover { color: var(--color-accent); }
+.markdown-body code { font-family: var(--font-mono); font-size: 0.82em; padding: 0.12em 0.35em; background: var(--color-surface-strong); border: 1px solid var(--color-line); }
+.markdown-body table { border-collapse: collapse; margin: 0.8rem 0; width: 100%; font-size: 0.85rem; }
+.markdown-body th, .markdown-body td { border: 1px solid var(--color-line); padding: 0.4rem 0.6rem; text-align: left; }
+.markdown-body th { background: var(--color-surface-strong); font-weight: 700; }
+.markdown-body hr { border: 0; border-top: 1px solid var(--color-line); margin: 1.2rem 0; }
+.markdown-body .md-codeblock code { padding: 0; border: 0; background: transparent; font-size: inherit; }
+
+.md-codeblock { margin: 0.8rem 0; border: 1px solid var(--color-line); border-radius: var(--radius); overflow: hidden; }
+.md-codeblock-head { display: flex; align-items: center; justify-content: space-between; padding: 0.35rem 0.6rem; border-bottom: 1px solid var(--color-line); background: var(--color-surface-strong); font-family: var(--font-mono); font-size: 0.625rem; letter-spacing: 0.07em; text-transform: uppercase; color: var(--color-muted); }
+.md-copy { border: 0; border-bottom: 1px solid currentColor; background: transparent; color: var(--color-accent-strong); font: inherit; padding: 0; cursor: pointer; }
+.md-copy:hover { color: var(--color-accent); }
+.md-codeblock pre { max-height: 24rem; margin: 0; overflow: auto; padding: 0.75rem; background: var(--color-ink); color: var(--color-paper); font-family: var(--font-mono); font-size: 0.75rem; line-height: 1.65; }
+.md-codeblock code { font-family: inherit; }
+
+/* hljs 暖墨主题（深底暖字） */
+.md-codeblock .hljs-comment, .md-codeblock .hljs-quote { color: #9a9184; font-style: italic; }
+.md-codeblock .hljs-keyword, .md-codeblock .hljs-selector-tag, .md-codeblock .hljs-literal { color: #e08a7a; }
+.md-codeblock .hljs-string, .md-codeblock .hljs-attr, .md-codeblock .hljs-template-tag { color: #c9b896; }
+.md-codeblock .hljs-number, .md-codeblock .hljs-built_in, .md-codeblock .hljs-symbol { color: #d9a05b; }
+.md-codeblock .hljs-title, .md-codeblock .hljs-section, .md-codeblock .hljs-function .hljs-title { color: #f2e9d8; }
+.md-codeblock .hljs-type, .md-codeblock .hljs-class .hljs-title { color: #e8c4a8; }
+.md-codeblock .hljs-variable, .md-codeblock .hljs-template-variable { color: #f2e9d8; }
+.md-codeblock .hljs-params { color: #f2e9d8; }
+.md-codeblock .hljs-meta, .md-codeblock .hljs-tag { color: #9a9184; }
+.md-codeblock .hljs-name { color: #e08a7a; }

package/src/components/permission-card/PermissionCard.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { useState } from "react";
+
+import { Badge } from "../../components/badge";
+import { Button } from "../../components/button";
+import { Input } from "../../components/input";
+import "./permission-card.css";
+
+export type PermissionRequestData = {
+  id: string;
+  permission: string;
+  patterns: string[];
+  metadata?: unknown;
+};
+
+export type PermissionReply = "once" | "always" | "reject";
+
+/**
+ * PermissionCard — 内联审批卡：Agent 请求授权时在消息流中渲染。
+ *
+ * 印章红描边 + 说明文案 + 三档操作（允许一次 / 始终允许 / 拒绝），
+ * 拒绝可附理由（会反馈给 Agent）。
+ *
+ * @example
+ * <PermissionCard request={req} busy={replying} onReply={(reply, feedback) => …} />
+ */
+export function PermissionCard({ request, busy = false, onReply }: {
+  request: PermissionRequestData;
+  busy?: boolean;
+  onReply: (reply: PermissionReply, feedback?: string) => void;
+}) {
+  const [feedback, setFeedback] = useState("");
+  const command = typeof (request.metadata as { command?: unknown } | undefined)?.command === "string" ? (request.metadata as { command: string }).command : null;
+  return (
+    <article className="zmz-permission-card">
+      <div className="zmz-permission-head">
+        <Badge variant="solid" size="sm">{request.permission}</Badge>
+        <strong>{command ?? request.patterns.join("、")}</strong>
+      </div>
+      <p className="zmz-permission-note">
+        {request.permission === "bash" ? "Agent 请求在隔离沙箱中执行这条命令。批准后本次运行一次有效；选择「始终允许」则同任务内同类命令不再询问。" : "Agent 请求执行此操作。"}
+      </p>
+      <div className="zmz-permission-actions">
+        <Input
+          className="zmz-permission-feedback"
+          placeholder="拒绝理由（可选，会反馈给 Agent）"
+          value={feedback}
+          onChange={(event) => setFeedback(event.target.value)}
+        />
+        <Button type="button" variant="ghost" size="sm" disabled={busy} onClick={() => onReply("reject", feedback || undefined)}>
+          拒绝
+        </Button>
+        <Button type="button" variant="secondary" size="sm" disabled={busy} onClick={() => onReply("always")}>
+          始终允许
+        </Button>
+        <Button type="button" size="sm" disabled={busy} onClick={() => onReply("once")}>
+          允许一次
+        </Button>
+      </div>
+    </article>
+  );
+}

package/src/components/permission-card/index.ts

@@ -0,0 +1 @@
+export * from "./PermissionCard";

package/src/components/permission-card/permission-card.css

@@ -0,0 +1,7 @@
+/* PermissionCard — 内联审批卡。token 依赖消费端 @theme。 */
+.zmz-permission-card { border: 1px solid var(--color-accent); border-radius: var(--radius); padding: 0.85rem 1rem; background: color-mix(in oklab, var(--color-accent) 4%, var(--color-surface)); margin: 0.5rem 0; }
+.zmz-permission-head { display: flex; align-items: center; gap: 0.6rem; }
+.zmz-permission-head strong { font-family: var(--font-mono); font-size: 0.8125rem; overflow-wrap: anywhere; }
+.zmz-permission-note { margin: 0.5rem 0 0.75rem; font-size: 0.8125rem; color: var(--color-muted); }
+.zmz-permission-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 0.6rem; }
+.zmz-permission-feedback { flex: 1 1 12rem; min-width: 0; }

package/src/components/todo-checklist/TodoChecklist.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { useState } from "react";
+
+import { Badge } from "../../components/badge";
+import { Icon } from "../../components/icon/Icon";
+import { ToolCard, type ToolCall } from "../../components/tool-card";
+import "./todo-checklist.css";
+
+export type TodoItem = {
+  content: string;
+  status: "pending" | "in_progress" | "completed" | "cancelled";
+  priority?: "high" | "medium" | "low";
+};
+
+/** 从 todo 工具调用的 completed metadata 读进度游标（约定：N 表示第 N+1 步进行中）。 */
+function metadataCount(call: ToolCall): number | null {
+  if (call.state.status !== "completed") return null;
+  const value = call.state.metadata?.completed;
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+/** 把工具调用按 todo 进度游标分配到各步骤名下（分支渲染）。 */
+function assignToolsToTodos(todos: TodoItem[], calls: ToolCall[]): ToolCall[][] {
+  const branches = todos.map(() => [] as ToolCall[]);
+  let branchIndex = 0;
+  for (const call of calls) {
+    if (call.tool === "todo") {
+      const completed = metadataCount(call);
+      if (completed !== null) branchIndex = Math.min(Math.max(completed, 0), todos.length - 1);
+      continue;
+    }
+    branches[branchIndex]?.push(call);
+  }
+  return branches;
+}
+
+function TaskPlanNode({ todo, index, calls }: { todo: TodoItem; index: number; calls: ToolCall[] }) {
+  const [expanded, setExpanded] = useState(false);
+  const active = todo.status === "in_progress";
+  const canExpand = calls.length > 0;
+  const open = canExpand && (active || expanded);
+  const state = active ? "当前执行" : todo.status === "completed" ? "已完成" : todo.status === "cancelled" ? "已跳过" : "待执行";
+  const stateVariant = active ? "accent" : todo.status === "completed" ? "success" : todo.status === "cancelled" ? "danger" : "outline";
+  return (
+    <li className={`zmz-task-node ${todo.status}`}>
+      <button type="button" className="zmz-task-node-trigger" aria-expanded={open} disabled={!canExpand} onClick={() => setExpanded((value) => !value)}>
+        <span className="zmz-task-node-marker" aria-hidden>{todo.status === "completed" ? <Icon name="check" size={10} /> : active ? <span className="zmz-todo-spinner" /> : null}</span>
+        <span className="zmz-task-node-copy"><span className="zmz-task-node-index">{String(index + 1).padStart(2, "0")}</span><strong>{todo.content}</strong></span>
+        {canExpand ? <Badge variant="outline" size="sm">{calls.length} 次执行</Badge> : <Badge variant={stateVariant} size="sm">{state}</Badge>}
+        {canExpand && <Icon name="chevron-down" size={12} className={open ? "zmz-chevron open" : "zmz-chevron"} />}
+      </button>
+      {open && calls.length > 0 && <div className="zmz-task-executions">{calls.map((call) => <ToolCard key={`${call.id}:${call.state.status}`} call={call} />)}</div>}
+    </li>
+  );
+}
+
+/**
+ * TodoChecklist — Task Plan 卡：进度摘要 + 步骤清单，每步可展开看工具执行。
+ *
+ * `calls` 可选：传入会话的工具调用后，按 todo 进度游标自动分配到各步骤
+ * 名下（约定 tool 名为 "todo" 的调用、其 completed metadata 为游标）。
+ *
+ * @example
+ * <TodoChecklist todos={todos} calls={toolCalls} />
+ */
+export function TodoChecklist({ todos, calls = [] }: { todos: TodoItem[]; calls?: ToolCall[] }) {
+  if (!todos.length) return null;
+  const done = todos.filter((todo) => todo.status === "completed").length;
+  const current = todos.find((todo) => todo.status === "in_progress");
+  const progress = Math.round((done / todos.length) * 100);
+  const branches = assignToolsToTodos(todos, calls);
+  return (
+    <section className="zmz-todo">
+      <div className="zmz-todo-head">
+        <div className="zmz-todo-heading"><span className="zmz-todo-kicker">Task Plan</span><Badge variant={current ? "accent" : done === todos.length ? "success" : "outline"} size="sm">{current ? "执行中" : done === todos.length ? "已完成" : "待执行"}</Badge></div>
+        <span className="zmz-todo-progress"><b>{done}</b>/{todos.length}</span>
+      </div>
+      <div className="zmz-todo-summary"><span>{current?.content ?? (done === todos.length ? "所有步骤已完成" : "等待 Agent 开始执行")}</span><span>{progress}%</span></div>
+      <div className="zmz-todo-progressbar" aria-hidden><span style={{ width: `${progress}%` }} /></div>
+      <ol className="zmz-todo-list">
+        {todos.map((todo, index) => (
+          <TaskPlanNode key={`${todo.content}-${index}`} todo={todo} index={index} calls={branches[index] ?? []} />
+        ))}
+      </ol>
+    </section>
+  );
+}

package/src/components/todo-checklist/index.ts

@@ -0,0 +1 @@
+export * from "./TodoChecklist";

package/src/components/todo-checklist/todo-checklist.css

@@ -0,0 +1,35 @@
+/* TodoChecklist — Task Plan 卡。token 依赖消费端 @theme。 */
+@keyframes zmz-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.35; } }
+
+.zmz-todo { margin: 0 0 1rem; padding: 0.75rem 0.8rem 0.7rem; border: 1px solid var(--color-line); border-left: 2px solid var(--color-ink); border-radius: var(--radius); background: color-mix(in oklab, var(--color-surface) 94%, var(--color-bg)); }
+.zmz-todo-head { display: flex; justify-content: space-between; align-items: flex-start; gap: 1rem; margin-bottom: 0.55rem; }
+.zmz-todo-heading { display: flex; align-items: baseline; gap: 0.55rem; }
+.zmz-todo-kicker { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.58rem; letter-spacing: 0.1em; text-transform: uppercase; }
+.zmz-todo-progress { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.62rem; }
+.zmz-todo-progress b { color: var(--color-ink); font-weight: 700; }
+.zmz-todo-summary { display: flex; justify-content: space-between; gap: 1rem; min-width: 0; margin-bottom: 0.45rem; color: var(--color-ink); font-size: 0.78rem; line-height: 1.35; }
+.zmz-todo-summary span:first-child { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.zmz-todo-summary span:last-child { flex: 0 0 auto; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.6rem; }
+.zmz-todo-progressbar { height: 3px; margin-bottom: 0.65rem; overflow: hidden; background: var(--color-surface-strong); }
+.zmz-todo-progressbar span { display: block; height: 100%; background: var(--color-accent); transition: width 220ms var(--ease-out); }
+.zmz-todo-list { position: relative; display: grid; gap: 0; margin: 0; padding: 0 0 0 0.15rem; list-style: none; }
+.zmz-task-node { position: relative; }
+.zmz-task-node:not(:last-child)::before { position: absolute; z-index: 0; top: 1.35rem; bottom: -0.1rem; left: 0.47rem; width: 1px; background: var(--color-line); content: ""; }
+.zmz-task-node-trigger { position: relative; z-index: 1; display: grid; width: 100%; min-height: 2rem; grid-template-columns: 1rem minmax(0, 1fr) auto auto; align-items: center; gap: 0.45rem; border: 0; border-radius: var(--radius-sm); background: transparent; color: var(--color-ink); padding: 0.35rem 0.25rem; text-align: left; cursor: pointer; transition: background 0.15s var(--ease-out); }
+.zmz-task-node-trigger:hover { background: var(--color-surface); }
+.zmz-task-node-trigger:disabled { cursor: default; }
+.zmz-task-node-trigger:disabled:hover { background: transparent; }
+.zmz-task-node-marker { display: inline-flex; width: 0.9rem; height: 0.9rem; align-items: center; justify-content: center; border: 1px solid var(--color-line); border-radius: 50%; background: var(--color-surface); color: var(--color-success); }
+.zmz-task-node.in_progress .zmz-task-node-marker { border-color: var(--color-accent); }
+.zmz-task-node-copy { display: flex; min-width: 0; align-items: baseline; gap: 0.45rem; }
+.zmz-task-node-copy strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 0.76rem; font-weight: 600; }
+.zmz-task-node-index { flex: 0 0 auto; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.55rem; }
+.zmz-task-node.completed .zmz-task-node-copy strong { color: var(--color-muted); text-decoration: line-through; }
+.zmz-task-node.in_progress .zmz-task-node-copy strong { color: var(--color-accent-strong); }
+.zmz-todo-spinner { width: 0.45rem; height: 0.45rem; border-radius: 50%; background: var(--color-accent); animation: zmz-pulse 1s var(--ease-out) infinite; }
+.zmz-chevron { transition: transform 0.15s var(--ease-out); }
+.zmz-chevron.open { transform: rotate(180deg); }
+.zmz-task-executions { position: relative; display: grid; gap: 0; margin: 0 0 0.15rem 1.3rem; padding: 0.05rem 0 0.1rem 1rem; }
+.zmz-task-executions::before { position: absolute; top: 0; bottom: 0.2rem; left: 0.35rem; width: 1px; background: var(--color-line); content: ""; }
+.zmz-task-executions .tool-card::before { left: -0.65rem; width: 0.65rem; }
+.zmz-task-executions .tool-card-detail { margin-left: 1.3rem; }

package/src/components/tool-card/ToolCard.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { useState } from "react";
+
+import { Badge } from "../../components/badge";
+import { Icon } from "../../components/icon/Icon";
+import { formatToolInput, toolDuration, type ToolCall } from "./types";
+import "./tool-card.css";
+
+/**
+ * ToolCard — 单次工具调用卡：状态色左边条 + 展开/收起的输入输出详情。
+ *
+ * 运行中卡常开；进入终态后收起，点标题可再看输出。
+ * `sessionIdle=true` 时非终态工具渲染为「失败（中断）」——
+ * 会话空闲却停在 running 是崩溃/重启的遗留，不该永远转圈。
+ *
+ * @example
+ * <ToolCard call={toolCall} sessionIdle={idle} />
+ */
+export function ToolCard({ call, sessionIdle = false }: { call: ToolCall; sessionIdle?: boolean }) {
+  const [expanded, setExpanded] = useState(false);
+  const state = call.state;
+  const running = state.status === "running" || state.status === "pending";
+  const interrupted = running && sessionIdle;
+  const title = state.status === "completed" ? state.title : state.status === "running" ? (state.title ?? call.tool) : call.tool;
+  const output = state.status === "completed" ? state.output : state.status === "error" ? state.error : null;
+  const statusClass = state.status === "completed" ? "completed" : interrupted ? "failed" : state.status === "error" ? "failed" : "running";
+  const isOpen = running || expanded;
+
+  return (
+    <div className={`tool-card ${statusClass}`}>
+      <button type="button" className="tool-card-trigger" aria-expanded={isOpen} onClick={() => setExpanded((value) => !value)}>
+        <span className="tool-card-glyph" aria-hidden><Icon name={state.status === "completed" ? "check" : interrupted || state.status === "error" ? "cross" : "chevron-down"} size={12} /></span>
+        <span className="tool-card-label">{title}</span>
+        {(state.status === "error" || interrupted) && <Badge variant="danger" size="sm">失败</Badge>}
+        {running && !interrupted && <Badge variant="warning" size="sm">运行中</Badge>}
+        {toolDuration(call) && <span className="tool-card-duration">{toolDuration(call)}</span>}
+        <Icon name="chevron-down" size={12} className={isOpen ? "tool-card-chevron open" : "tool-card-chevron"} />
+      </button>
+      {isOpen && (
+        <div className="tool-card-detail">
+          <div className="tool-card-detail-section">
+            <span className="tool-card-detail-label">输入</span>
+            <pre>{formatToolInput(state.input)}</pre>
+          </div>
+          {output !== null && (
+            <div className="tool-card-detail-section">
+              <span className="tool-card-detail-label">输出</span>
+              <pre>{output}</pre>
+            </div>
+          )}
+          {running && <span className="tool-card-live-note">{interrupted ? "运行已中断（服务重启），可在同一会话继续。" : "正在等待工具返回结果…"}</span>}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * ToolGroup — 连续工具调用的折叠组（G1 防淹没）。
+ *
+ * 运行中/有失败/单条时自动展开；多条完成时折叠为一条摘要行。
+ *
+ * @example
+ * <ToolGroup calls={toolCalls} sessionIdle={idle} />
+ */
+export function ToolGroup({ calls, sessionIdle = false }: { calls: ToolCall[]; sessionIdle?: boolean }) {
+  const [expanded, setExpanded] = useState(false);
+  const running = calls.filter((c) => c.state.status === "running" || c.state.status === "pending");
+  const failed = calls.filter((c) => c.state.status === "error" || (sessionIdle && (c.state.status === "running" || c.state.status === "pending")));
+  const done = calls.filter((c) => c.state.status === "completed");
+  const autoExpand = running.length > 0 || failed.length > 0 || calls.length <= 1;
+  const open = expanded || autoExpand;
+  const glyph = failed.length > 0 ? "cross" : running.length > 0 ? "chevron-down" : "check";
+  const summary = [
+    running.length > 0 && `${running.length} 个进行中`,
+    failed.length > 0 && `${failed.length} 个失败`,
+    done.length > 0 && `${done.length} 个完成`,
+  ].filter(Boolean).join(" · ");
+  return (
+    <div className="zmz-tool-group">
+      <button type="button" className="zmz-tool-group-trigger" aria-expanded={open} onClick={() => setExpanded((value) => !value)} disabled={autoExpand}>
+        <span className="tool-card-glyph" aria-hidden><Icon name={glyph} size={12} /></span>
+        <span className="zmz-tool-group-label">运行了 {calls.length} 个工具</span>
+        {!autoExpand && <small>{summary}</small>}
+        <Icon name="chevron-down" size={12} className={open ? "tool-card-chevron open" : "tool-card-chevron"} />
+      </button>
+      {open && (
+        <div className="zmz-tool-group-body">
+          {calls.map((call) => <ToolCard key={`${call.id}:${call.state.status}`} call={call} sessionIdle={sessionIdle} />)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/tool-card/index.ts

@@ -0,0 +1,2 @@
+export * from "./ToolCard";
+export * from "./types";

package/src/components/tool-card/tool-card.css

@@ -0,0 +1,30 @@
+/* ToolCard / ToolGroup — 工具调用卡与折叠组。token 依赖消费端 @theme。
+   执行树分支线（::before）等上下文增强由消费端自己的 CSS 叠加。 */
+@keyframes zmz-tool-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.35; } }
+
+.tool-card { position: relative; border-radius: var(--radius-sm); }
+/* 执行树分支线（挂在左侧时间轴上；独立使用时容器需留出左侧空间） */
+.tool-card::before { position: absolute; top: 1.08rem; left: -0.81rem; width: 0.81rem; height: 1px; background: var(--color-line); content: ""; }
+.tool-card-trigger { display: flex; width: 100%; min-height: 2.15rem; align-items: center; gap: 0.5rem; border: 0; border-radius: var(--radius-sm); background: transparent; color: var(--color-ink); padding: 0.38rem 0.4rem; text-align: left; cursor: pointer; transition: background 0.15s var(--ease-out); }
+.tool-card-trigger:hover { background: var(--color-surface); }
+.tool-card-glyph { display: grid; width: 1rem; height: 1rem; flex: 0 0 1rem; place-items: center; border-radius: 50%; color: var(--color-muted); }
+.tool-card.running .tool-card-glyph { color: var(--color-accent); animation: zmz-tool-pulse 1s ease-in-out infinite; }
+.tool-card.completed .tool-card-glyph { color: var(--color-success); }
+.tool-card.failed .tool-card-glyph { color: #b03a28; }
+.tool-card-label { min-width: 0; flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 0.75rem; }
+.tool-card-duration { flex: 0 0 auto; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.6rem; }
+.tool-card-chevron { flex: 0 0 auto; color: var(--color-muted); transition: transform 0.15s var(--ease-out); }
+.tool-card-chevron.open { transform: rotate(180deg); }
+.tool-card-detail { display: grid; gap: 0.6rem; max-height: 18rem; margin: 0 0 0.25rem 1.5rem; overflow: auto; border-left: 1px solid var(--color-line); padding: 0.45rem 0.65rem; background: color-mix(in oklab, var(--color-surface-strong) 42%, var(--color-surface)); }
+.tool-card-detail-section { display: grid; gap: 0.25rem; }
+.tool-card-detail-label { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.58rem; letter-spacing: 0.08em; text-transform: uppercase; }
+.tool-card-detail pre { margin: 0; color: var(--color-muted); font-family: var(--font-mono); font-size: 0.68rem; line-height: 1.5; white-space: pre-wrap; overflow-wrap: anywhere; }
+.tool-card-live-note { color: var(--color-accent-strong); font-family: var(--font-mono); font-size: 0.62rem; }
+
+.zmz-tool-group { display: grid; gap: 0.5rem; margin: 0.4rem 0; }
+.zmz-tool-group-trigger { display: flex; align-items: center; gap: 0.5rem; width: 100%; border: 1px solid var(--color-line); border-radius: var(--radius-sm); background: color-mix(in oklab, var(--color-surface) 92%, var(--color-bg)); color: var(--color-ink); padding: 0.4rem 0.6rem; cursor: pointer; transition: border-color 0.15s var(--ease-out); }
+.zmz-tool-group-trigger:hover:not(:disabled) { border-color: var(--color-line-strong); }
+.zmz-tool-group-trigger:disabled { cursor: default; opacity: 0.85; }
+.zmz-tool-group-label { font-family: var(--font-mono); font-size: 0.7rem; }
+.zmz-tool-group-trigger small { color: var(--color-muted); font-family: var(--font-mono); font-size: 0.6rem; }
+.zmz-tool-group-body { display: grid; gap: 0.5rem; padding-left: 0.6rem; border-left: 2px solid var(--color-line); }

package/src/components/tool-card/types.ts

@@ -0,0 +1,41 @@
+/** 工具调用状态 — 与 agent-framework ToolState 对齐的通用形状。 */
+export type ToolState =
+  | { status: "pending"; input: unknown }
+  | { status: "running"; input: unknown; title?: string; time: { start: string } }
+  | {
+      status: "completed";
+      input: unknown;
+      output: string;
+      title: string;
+      metadata?: Record<string, unknown>;
+      time: { start: string; end: string };
+    }
+  | { status: "error"; input: unknown; error: string; time: { start: string; end: string } };
+
+/** 单次工具调用（会话事件投影中的 tool part，去掉 message/session 归属字段）。 */
+export type ToolCall = {
+  id: string;
+  tool: string;
+  state: ToolState;
+};
+
+export function toolDuration(call: ToolCall): string | null {
+  const state = call.state;
+  if (state.status === "pending") return null;
+  if (!state.time || !("end" in state.time)) return null;
+  const ms = new Date(state.time.end).getTime() - new Date(state.time.start).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  if (ms < 1000) return `${Math.max(1, Math.round(ms))}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+  return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+}
+
+export function formatToolInput(input: unknown): string {
+  if (input === null || input === undefined) return "";
+  if (typeof input === "string") return input;
+  try {
+    return JSON.stringify(input, null, 2);
+  } catch {
+    return String(input);
+  }
+}