@spzxg/cli-ui 0.0.0-stage → 0.1.0

package/src/chat/Composer.tsx

@@ -0,0 +1,194 @@
+// 输入框。结构与 Operator 的 Composer.tsx 一致（comp-box / comp-area / send-group / comp-foot），
+// 但只发文本：不收图片和其他附件。文件只收 TXT、Markdown、Word，在前端解析成纯文本，
+// 和长粘贴一样变成可折叠的文本块，发送时按统一格式拼进正文（见 core/blocks.ts）。
+import { useEffect, useRef, useState } from "react";
+import {
+  ACCEPT_ATTR, MAX_MESSAGE_CHARS, PASTE_NAME, charCount, composeMessage, isLongText, readFileText, type TextBlock,
+} from "../core/blocks.js";
+import { Icon } from "../ui/icons.js";
+import { TextBlockCard } from "../ui/TextBlock.js";
+import { fmtCount } from "../ui/format.js";
+
+const draftKey = (key: string) => `cli-ui:draft:${key}`;
+const loadDraft = (key: string) => { try { return localStorage.getItem(draftKey(key)) ?? ""; } catch { return ""; } };
+const saveDraft = (key: string, value: string) => {
+  try {
+    if (value) localStorage.setItem(draftKey(key), value);
+    else localStorage.removeItem(draftKey(key));
+  } catch { /* 隐私模式 / 配额：草稿就不保存 */ }
+};
+
+type Pending = { key: string; name: string; status: "reading" | "error"; error?: string };
+
+/** 输入框的可配置项（来自 CliChat 的 config.composer）。 */
+export interface ComposerOptions {
+  placeholderRunning: string;
+  hints: boolean;
+  charCount: boolean;
+  fileUpload: boolean;
+  fileButtonText: string;
+  queue: boolean;
+}
+
+export function Composer({ draft, placeholder, disabled, disabledHint, running, onSend, onStop, options }: {
+  /** 草稿按这个键存在 localStorage（一般是对话 id）。 */
+  draft: string;
+  placeholder: string;
+  disabled: boolean;
+  disabledHint?: string;
+  running: boolean;
+  onSend: (text: string) => Promise<void>;
+  onStop?: () => Promise<void> | void;
+  options: ComposerOptions;
+}) {
+  const [val, setVal] = useState(() => loadDraft(draft));
+  const [blocks, setBlocks] = useState<Array<TextBlock & { key: string }>>([]);
+  const [pending, setPending] = useState<Pending[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [sending, setSending] = useState(false);
+  const [stopping, setStopping] = useState(false);
+  const [dragging, setDragging] = useState(false);
+  const dragDepth = useRef(0);
+  const seq = useRef(0);
+  const fileRef = useRef<HTMLInputElement>(null);
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => { if (!running) setStopping(false); }, [running]);
+  useEffect(() => { saveDraft(draft, val); }, [draft, val]);
+  const autosize = (el: HTMLTextAreaElement) => { el.style.height = "auto"; el.style.height = Math.min(el.scrollHeight, 160) + "px"; };
+  useEffect(() => { if (ref.current) autosize(ref.current); }, [draft]);
+
+  const nextKey = () => `blk-${++seq.current}`;
+  const addBlock = (block: TextBlock) => setBlocks((prev) => [...prev, { ...block, key: nextKey() }]);
+
+  const addFiles = (files: File[]) => {
+    if (disabled || !options.fileUpload) return;
+    for (const file of files) {
+      const key = nextKey();
+      setPending((prev) => [...prev, { key, name: file.name || "文件", status: "reading" }]);
+      readFileText(file)
+        .then((text) => {
+          setPending((prev) => prev.filter((p) => p.key !== key));
+          if (!text.trim()) throw new Error(`「${file.name}」里没有可读的文字`);
+          addBlock({ name: file.name, text, kind: "file" });
+        })
+        .catch((err: unknown) => {
+          setPending((prev) => prev.map((p) => (p.key === key ? { ...p, status: "error", error: err instanceof Error ? err.message : String(err) } : p)));
+        });
+    }
+  };
+
+  const message = composeMessage(val, blocks);
+  const total = charCount(message);
+  const tooLong = total > MAX_MESSAGE_CHARS;
+  const reading = pending.some((p) => p.status === "reading");
+  // 运行中不允许排队时，等这一轮结束再发。
+  const canSend = !!message.trim() && !reading && !tooLong && !sending && (!running || options.queue);
+
+  const submit = async () => {
+    if (!canSend || disabled) return;
+    setSending(true);
+    setError(null);
+    const key = draft;
+    try {
+      await onSend(message);
+      // 新建对话时发送完成前组件就换成了新对话的输入框（key 变了），这里直接清掉发出时那份草稿。
+      saveDraft(key, "");
+      setVal("");
+      setBlocks([]);
+      setPending([]);
+      if (ref.current) ref.current.style.height = "auto";
+    } catch (err) {
+      // 发送失败：内容留在输入框里，可以直接再发。
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSending(false);
+    }
+  };
+
+  const isFileDrag = (e: React.DragEvent) => Array.from(e.dataTransfer?.types ?? []).includes("Files");
+  const hasFileDrag = (e: React.DragEvent) => options.fileUpload && isFileDrag(e);
+
+  return (
+    <div className="composer">
+      <div className="composer-inner">
+        {(error || tooLong) && (
+          <div className="cli-comp-err">⚠ {tooLong ? `内容共 ${fmtCount(total)} 字，超过单条消息上限 ${fmtCount(MAX_MESSAGE_CHARS)} 字，请删减或分几条发送` : error}</div>
+        )}
+        <div
+          className={`comp-box${dragging ? " dropping" : ""}`}
+          onDragEnter={(e) => { if (!disabled && hasFileDrag(e)) { e.preventDefault(); dragDepth.current++; setDragging(true); } }}
+          onDragOver={(e) => { if (isFileDrag(e)) e.preventDefault(); }}
+          onDragLeave={() => { if (dragDepth.current > 0 && --dragDepth.current === 0) setDragging(false); }}
+          onDrop={(e) => {
+            if (!isFileDrag(e)) return;
+            // 文件拖进来总要拦下：不拦的话浏览器会直接打开这个文件、离开当前页面。
+            e.preventDefault();
+            dragDepth.current = 0;
+            setDragging(false);
+            if (disabled) return;
+            if (!options.fileUpload) { setError("这里只能发送文字"); return; }
+            addFiles(Array.from(e.dataTransfer.files));
+          }}
+        >
+          {(blocks.length > 0 || pending.length > 0) && (
+            <div className="cli-blocks">
+              {blocks.map((b) => <TextBlockCard key={b.key} block={b} onRemove={() => setBlocks((prev) => prev.filter((x) => x.key !== b.key))} />)}
+              {pending.map((p) => (
+                <div key={p.key} className={`attach-chip file ${p.status}`} title={p.error || p.name}>
+                  <span className="attach-file">{Icon.doc()} {p.name}</span>
+                  <span className={`attach-badge ${p.status === "error" ? "err" : ""}`}>{p.status === "reading" ? "解析中…" : p.error}</span>
+                  {p.status === "error" && <button className="attach-x" title="移除" aria-label={`移除 ${p.name}`} onClick={() => setPending((prev) => prev.filter((x) => x.key !== p.key))}>×</button>}
+                </div>
+              ))}
+            </div>
+          )}
+          <div className="comp-area">
+            <textarea
+              ref={ref} rows={1} value={val} disabled={disabled}
+              placeholder={disabled ? disabledHint ?? "暂时不能发送" : running && options.queue ? options.placeholderRunning : placeholder}
+              onChange={(e) => { setVal(e.target.value); autosize(e.target); }}
+              onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) { e.preventDefault(); void submit(); } }}
+              onPaste={(e) => {
+                const files = Array.from(e.clipboardData?.files ?? []);
+                if (files.length) {
+                  e.preventDefault();
+                  if (!options.fileUpload) { setError("这里只能发送文字"); return; }
+                  if (files.some((f) => f.type.startsWith("image/"))) setError("不支持发送图片，只能发送文字，或上传 TXT / Markdown / Word 文件");
+                  addFiles(files.filter((f) => !f.type.startsWith("image/")));
+                  return;
+                }
+                // 大段粘贴不放进输入框（几万字的 textarea 会很卡），转成可折叠的文本块。
+                const text = e.clipboardData?.getData("text/plain") ?? "";
+                if (isLongText(text)) {
+                  e.preventDefault();
+                  addBlock({ name: PASTE_NAME, text, kind: "paste" });
+                }
+              }}
+            />
+            {running ? (
+              <div className="send-group">
+                {canSend && <button className="send queue" onClick={() => void submit()} title="把这条后续消息排队 —— 当前轮次结束后自动发送" disabled={disabled}>{Icon.send()}</button>}
+                {onStop && <button className="send stop" onClick={() => { setStopping(true); void Promise.resolve(onStop()).catch(() => setStopping(false)); }} disabled={stopping} title={stopping ? "正在停止…" : "停止当前轮次"}>{Icon.stop()}</button>}
+              </div>
+            ) : (
+              <button className="send" disabled={!canSend || disabled} onClick={() => void submit()}>{Icon.send()}</button>
+            )}
+          </div>
+          {/* 底部栏的内容都关掉时整行不占位。 */}
+          {(options.hints || options.charCount || options.fileUpload || tooLong) && <div className="comp-foot">
+            {options.hints && <span className="hint"><span className="kbd">⏎</span> 发送</span>}
+            {options.hints && <span className="hint comp-hint-extra"><span className="kbd">⇧⏎</span> 换行</span>}
+            {options.charCount && total > 0 && <span className={`hint cli-count ${tooLong ? "over" : ""}`}>{fmtCount(total)} 字</span>}
+            {!options.charCount && tooLong && <span className="hint cli-count over">{fmtCount(total)} 字</span>}
+            <span className="spacer" />
+            {options.fileUpload && <input ref={fileRef} type="file" accept={ACCEPT_ATTR} multiple hidden onChange={(e) => { addFiles(Array.from(e.target.files ?? [])); e.target.value = ""; }} />}
+            {options.fileUpload && !disabled && (
+              <button className="hint" style={{ cursor: "pointer" }} title="添加 TXT / Markdown / Word 文件（也可拖拽进来），内容会转成文字发送" onMouseDown={(e) => { e.preventDefault(); fileRef.current?.click(); }}>{Icon.clip()} {options.fileButtonText}</button>
+            )}
+          </div>}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/chat/export.ts

@@ -0,0 +1,34 @@
+import type { CenterTurn, Msg } from "../core/types.js";
+import { toolDataOf } from "../ui/transcriptModel.js";
+
+/** 把对话过程导出成 Markdown 下载（对应 Operator 的「导出执行过程」，这里在前端用已加载的转录生成）。 */
+export function buildMarkdown(title: string, jobId: string, messages: Msg[], turns: CenterTurn[]): string {
+  const tokens = turns.reduce((sum, turn) => sum + (turn.total_tokens || 0), 0);
+  const lines = [`# ${title}`, "", `- 对话：${jobId}`, `- 轮次：${turns.length}`, `- tokens：${tokens.toLocaleString()}`, `- 导出时间：${new Date().toLocaleString()}`, ""];
+  for (const m of messages) {
+    const time = m.ts ? ` · ${new Date(m.ts).toLocaleString()}` : "";
+    if (m.role === "user" || m.role === "queued") lines.push(`## 你${m.role === "queued" ? "（排队中）" : ""}${time}`, "", m.content, "");
+    else if (m.role === "assistant") lines.push(`## 智能体${time}`, "", m.content, "");
+    else if (m.role === "system") lines.push(`> ${m.content.replace(/\n/g, "\n> ")}`, "");
+    else if (m.role === "tool") {
+      const data = toolDataOf(m);
+      lines.push(`<details><summary>工具：${data.title}${data.isError ? "（失败）" : ""}</summary>`, "");
+      if (data.detail) lines.push("```", data.detail, "```", "");
+      if (data.result !== undefined) lines.push("结果：", "", "```", data.result, "```", "");
+      lines.push("</details>", "");
+    }
+  }
+  return lines.join("\n");
+}
+
+export function exportMarkdown(title: string, jobId: string, messages: Msg[], turns: CenterTurn[]) {
+  const blob = new Blob([buildMarkdown(title, jobId, messages, turns)], { type: "text/markdown;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${title.replace(/[\\/:*?"<>|]+/g, "_").slice(0, 60) || "对话"}.md`;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

package/src/core/blocks.ts

@@ -0,0 +1,132 @@
+/**
+ * 「文本块」：上传的文件（TXT / Markdown / Word）和粘贴的大段文字。
+ *
+ * 前端先把文件解析成纯文本，再按统一格式拼进消息正文发给 center——center 只收纯文本。
+ * 同一个格式两头用：输入框里是可折叠的卡片，发出去之后转录里也解析回同样的卡片，
+ * 所以长内容在输入框和对话里都只显示开头，点开才看全部，不会把页面卡住。
+ *
+ *   ----- 附件：需求说明.docx（12,345 字）-----
+ *   ……纯文本……
+ *   ----- 附件结束：需求说明.docx -----
+ *
+ * 对 Agent 来说这也是清楚的分隔：哪段是附件、叫什么、在哪结束。
+ */
+
+export interface TextBlock {
+  /** 显示名：文件名，粘贴的文字为「粘贴的文本」。 */
+  name: string;
+  text: string;
+  kind: "file" | "paste";
+}
+
+/** 支持的文件：只有 TXT、Markdown、Word（.docx）。 */
+export const ACCEPTED_EXTENSIONS = [".txt", ".md", ".markdown", ".docx"] as const;
+export const ACCEPT_ATTR = ".txt,.md,.markdown,.docx,text/plain,text/markdown,application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** 粘贴超过这个长度（或行数）就转成文本块，不放进输入框。 */
+export const PASTE_BLOCK_CHARS = 2_000;
+export const PASTE_BLOCK_LINES = 40;
+/** center 单条消息上限（POST /api/jobs/:id/messages 的 text 最长 200,000 字符）。 */
+export const MAX_MESSAGE_CHARS = 200_000;
+export const PASTE_NAME = "粘贴的文本";
+
+const OPEN = /^----- 附件：(.+?)（[\d,]+ 字）-----$/;
+const CLOSE = (name: string) => `----- 附件结束：${name} -----`;
+
+export const charCount = (text: string) => Array.from(text).length;
+
+export function serializeBlock(block: TextBlock): string {
+  const name = block.name.replace(/[\r\n]/g, " ").trim() || PASTE_NAME;
+  return `----- 附件：${name}（${charCount(block.text).toLocaleString("en-US")} 字）-----\n${block.text}\n${CLOSE(name)}`;
+}
+
+/** 输入框里的文字 + 文本块 → 发给 center 的正文。 */
+export function composeMessage(typed: string, blocks: TextBlock[]): string {
+  return [typed.trim(), ...blocks.map(serializeBlock)].filter(Boolean).join("\n\n");
+}
+
+export type MessagePart = { kind: "text"; text: string } | { kind: "block"; block: TextBlock };
+
+/** 正文 → 文字段和文本块（转录里渲染用）。不成对的标记原样当文字。 */
+export function splitMessage(content: string): MessagePart[] {
+  if (!content.includes("----- 附件：")) return [{ kind: "text", text: content }];
+  const lines = content.split("\n");
+  const parts: MessagePart[] = [];
+  let text: string[] = [];
+  const flush = () => {
+    const value = text.join("\n").trim();
+    if (value) parts.push({ kind: "text", text: value });
+    text = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const open = OPEN.exec(lines[i]);
+    const end = open ? lines.indexOf(CLOSE(open[1]), i + 1) : -1;
+    if (!open || end === -1) { text.push(lines[i]); continue; }
+    flush();
+    const name = open[1];
+    parts.push({ kind: "block", block: { name, text: lines.slice(i + 1, end).join("\n"), kind: name === PASTE_NAME ? "paste" : "file" } });
+    i = end;
+  }
+  flush();
+  return parts.length ? parts : [{ kind: "text", text: content }];
+}
+
+/** 粘贴的内容是不是该转成文本块。 */
+export function isLongText(text: string) {
+  if (text.length > PASTE_BLOCK_CHARS) return true;
+  let lines = 1;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10 && ++lines > PASTE_BLOCK_LINES) return true;
+  return false;
+}
+
+export function extensionOf(name: string) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot).toLowerCase();
+}
+
+export class FileReadError extends Error {}
+
+/**
+ * 读出文件的纯文本。TXT / Markdown 直接按 UTF-8 读；Word 用 mammoth 取正文文字（不带格式、图片）。
+ * 老式 .doc（二进制）浏览器里读不了，提示另存为 .docx。
+ */
+export async function readFileText(file: File): Promise<string> {
+  const ext = extensionOf(file.name);
+  if (ext === ".doc") throw new FileReadError("不支持老版 Word（.doc），请另存为 .docx 后再上传");
+  if (!(ACCEPTED_EXTENSIONS as readonly string[]).includes(ext)) throw new FileReadError("只支持 TXT、Markdown 和 Word（.docx）文件");
+  if (ext === ".docx") {
+    // 按需加载：mammoth 不小，只有真的传 Word 时才下载。
+    const mammoth = await import("mammoth");
+    const extract = (mammoth as unknown as { extractRawText: typeof import("mammoth").extractRawText }).extractRawText
+      ?? (mammoth as unknown as { default: typeof import("mammoth") }).default.extractRawText;
+    try {
+      const arrayBuffer = await readAs(file, "buffer");
+      // 浏览器版 mammoth 读 arrayBuffer；Node 版（测试、SSR）只认 buffer，有 Buffer 时一并给上。
+      const NodeBuffer = (globalThis as { Buffer?: { from(data: ArrayBuffer): unknown } }).Buffer;
+      const result = await extract({ arrayBuffer, ...(NodeBuffer ? { buffer: NodeBuffer.from(arrayBuffer) } : {}) } as { arrayBuffer: ArrayBuffer });
+      return normalizeText(result.value);
+    } catch {
+      throw new FileReadError("Word 文件解析失败，文件可能已损坏或不是 .docx 格式");
+    }
+  }
+  return normalizeText(await readAs(file, "text"));
+}
+
+/** Blob.text() / arrayBuffer() 老浏览器（Safari 14 以前）没有，退回 FileReader。 */
+function readAs(file: Blob, as: "text"): Promise<string>;
+function readAs(file: Blob, as: "buffer"): Promise<ArrayBuffer>;
+function readAs(file: Blob, as: "text" | "buffer"): Promise<string | ArrayBuffer> {
+  if (as === "text" && typeof file.text === "function") return file.text();
+  if (as === "buffer" && typeof file.arrayBuffer === "function") return file.arrayBuffer();
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string | ArrayBuffer);
+    reader.onerror = () => reject(reader.error ?? new FileReadError("文件读取失败"));
+    if (as === "text") reader.readAsText(file, "utf-8");
+    else reader.readAsArrayBuffer(file);
+  });
+}
+
+/** 统一换行、去掉 BOM 和首尾空行；段落间多余的空行压成一个。 */
+export function normalizeText(text: string) {
+  return text.replace(/^/, "").replace(/\r\n?/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}

package/src/core/client.ts

@@ -0,0 +1,230 @@
+import { createSseParser } from "./sse.js";
+import type {
+  CenterJob, CenterTask, CenterTurn, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot,
+} from "./types.js";
+
+/**
+ * center 服务（cli-task-center）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
+ *
+ * 怎么连：
+ *   · 推荐走同源代理（缺省 baseUrl = "/api/center"）：Vite 代理 / nginx 把 /api/center 转到 center，
+ *     并在代理里注入 `Authorization: Bearer <产品线令牌>`——令牌不进浏览器。
+ *   · 本地联调也可以直接给 token（会以 Bearer 头发出），或用 headers() 自己加头。
+ * center 本身不开 CORS，跨域直连需要代理。
+ */
+export interface CenterClientOptions {
+  /** center 的地址前缀，缺省 "/api/center"（同源代理）。 */
+  baseUrl?: string;
+  /** 产品线令牌；有代理注入时不要给。 */
+  token?: string;
+  /**
+   * 产品线（line key）。以请求头 `X-CLI-Line` 发出，给代理选用哪条产品线的令牌：
+   * 一个代理服务多条产品线时，按这个头注入对应的 Authorization（见文档「连接中枢」）。center 本身不读这个头，
+   * 产品线只由令牌决定。
+   */
+  line?: string;
+  /** 额外请求头（每次请求时取，可放会话令牌等）。 */
+  headers?: () => Record<string, string>;
+  fetch?: typeof fetch;
+}
+
+/** 实时流超过这么久没有任何数据（center 每 20 秒一次心跳）就当连接已断。 */
+export const STREAM_SILENCE_MS = 45_000;
+
+export class CenterError extends Error {
+  constructor(message: string, readonly code: string, readonly status: number, readonly detail?: unknown) {
+    super(message);
+    this.name = "CenterError";
+  }
+}
+
+/** center 的错误码翻成看得懂、知道怎么办的中文。 */
+const ERROR_TEXT: Record<string, string> = {
+  conversation_closed: "这个对话已经结束，不能再发消息；需要继续请新建对话",
+  conversation_queue_full: "排队的消息太多了，请等前面的回复后再发",
+  business_id_conflict: "消息编号冲突，请重新发送",
+  not_a_conversation: "这个任务不是对话任务",
+  not_found: "对话不存在，或不属于当前产品线",
+  unauthorized: "没有权限访问任务中心（产品线令牌缺失或失效）",
+  conversation_requires_one_task: "对话任务只能有一条首轮消息",
+  conversation_prompt_required: "第一条消息不能为空",
+};
+
+/**
+ * 组件用到的数据后端。界面只依赖这个接口，不直接依赖 center 的地址和字段：
+ *   · 现在的实现是 center 的对话任务接口（createCenterClient）；
+ *   · 以后把组件放进 Operator 自己的界面时，换一个实现这套接口的 Operator 后端即可，界面不用改。
+ * 带 ? 的是可选能力：后端不提供，界面就按 Operator 在「没有这个能力」时的样子显示（例如提问的回答改走下一条消息）。
+ */
+export interface ConversationBackend {
+  baseUrl: string;
+  getJob(jobId: string): Promise<CenterJob>;
+  listTurns(jobId: string, query?: { afterSeq?: number; limit?: number }): Promise<{ job_id: string; turns: CenterTurn[] }>;
+  listTasks(): Promise<{ tasks: CenterTask[] }>;
+  createConversation(firstMessage: string, opts?: NewConversationOptions & { businessId?: string }): Promise<{ id: string; job_id: string; status: string; turn: CenterTurn }>;
+  sendMessage(jobId: string, text: string, opts?: { businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
+  cancelTurn(jobId: string, turnId: string): Promise<CenterTurn>;
+  closeConversation(jobId: string): Promise<{ id: string; status: string }>;
+  stream(jobId: string, handlers: StreamHandlers, intervalMs?: number): () => void;
+  /**
+   * 把回答直接交给正停在提问上的回合（Operator 的 POST /api/tasks/:id/answer）。
+   * resolved=false 表示没有在等的回合，调用方改用「下一条消息」发回答。center 不提供：它在 Agent 提问时已经结束那一轮。
+   */
+  answerAsk?(jobId: string, askId: string, answers: string[][]): Promise<{ resolved: boolean }>;
+  /** 提交浏览器输入卡片（Operator 的 POST /api/tasks/:id/input），返回错误文案或 null。center 不提供。 */
+  submitInput?(jobId: string, inputId: string, values: string[]): Promise<string | null>;
+  /** 浏览器交接后交还给 AI（Operator 的 POST /api/tasks/:id/browser），返回错误文案或 null。center 不提供。 */
+  handback?(jobId: string): Promise<string | null>;
+}
+
+export function createCenterClient(options: CenterClientOptions = {}): ConversationBackend {
+  const base = (options.baseUrl ?? "/api/center").replace(/\/+$/, "");
+  const doFetch = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+
+  function headers(extra: Record<string, string> = {}) {
+    const result: Record<string, string> = { ...(options.headers?.() ?? {}), ...extra };
+    if (options.line) result["X-CLI-Line"] = options.line;
+    if (options.token) result.Authorization = `Bearer ${options.token}`;
+    return result;
+  }
+
+  async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    let response: Response;
+    try {
+      response = await doFetch(`${base}${path}`, {
+        ...init,
+        headers: headers(init.body ? { "Content-Type": "application/json" } : {}),
+      });
+    } catch (error) {
+      throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+    }
+    const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+    if (!response.ok) {
+      const code = typeof body?.error === "string" ? body.error : `HTTP_${response.status}`;
+      const detail = typeof body?.detail === "string" ? body.detail : undefined;
+      throw new CenterError(ERROR_TEXT[code] ?? detail ?? `任务中心返回错误（HTTP ${response.status}）`, code, response.status, body);
+    }
+    return body as T;
+  }
+
+  const post = <T>(path: string, body: unknown = {}) => request<T>(path, { method: "POST", body: JSON.stringify(body) });
+  const id = encodeURIComponent;
+
+  return {
+    baseUrl: base,
+    getJob: (jobId: string) => request<CenterJob>(`/api/jobs/${id(jobId)}`),
+    listTurns: (jobId: string, query: { afterSeq?: number; limit?: number } = {}) => {
+      const params = new URLSearchParams();
+      if (query.afterSeq !== undefined) params.set("after_seq", String(query.afterSeq));
+      if (query.limit !== undefined) params.set("limit", String(query.limit));
+      const qs = params.toString();
+      return request<{ job_id: string; turns: CenterTurn[] }>(`/api/jobs/${id(jobId)}/turns${qs ? `?${qs}` : ""}`);
+    },
+    /** 列表用：本产品线全部子任务（对话任务每个对话一条），用来发现对话。 */
+    listTasks: () => request<{ tasks: CenterTask[] }>("/api/tasks"),
+    createConversation: (firstMessage: string, opts: NewConversationOptions & { businessId?: string } = {}) => {
+      const title = (opts.title || firstLine(firstMessage)).slice(0, 120);
+      return post<{ id: string; job_id: string; status: string; turn: CenterTurn }>("/api/jobs", {
+        title,
+        mode: "conversation",
+        ...(opts.workspace ? { workspace: opts.workspace } : {}),
+        ...(opts.callback ? { callback: opts.callback } : {}),
+        tasks: [{
+          title,
+          prompt: firstMessage,
+          ...(opts.businessId ? { business_id: opts.businessId } : {}),
+          ...(opts.agent ? { agent: opts.agent } : {}),
+          ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+          ...(opts.browser ? { browser: true } : {}),
+        }],
+      });
+    },
+    /** 带 business_id 时 center 按它去重，网络超时可以放心重发同一条。 */
+    sendMessage: (jobId: string, text: string, opts: { businessId?: string; timeoutSeconds?: number } = {}) =>
+      post<SendResult>(`/api/jobs/${id(jobId)}/messages`, {
+        text,
+        ...(opts.businessId ? { business_id: opts.businessId } : {}),
+        ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+      }),
+    /** 取消一轮：排队中的直接撤回；正在执行的会中止节点上的回合。 */
+    cancelTurn: (jobId: string, turnId: string) => post<CenterTurn>(`/api/jobs/${id(jobId)}/turns/${id(turnId)}/cancel`),
+    closeConversation: (jobId: string) => post<{ id: string; status: string }>(`/api/jobs/${id(jobId)}/close`),
+    /**
+     * 订阅对话的实时流（GET /api/jobs/:id/stream）。返回关闭函数。
+     * 不自动重连：重连策略（退避、结束后不再连）由调用方决定。
+     */
+    stream(jobId: string, handlers: StreamHandlers, intervalMs = 300): () => void {
+      const ctl = new AbortController();
+      let stopped = false;
+      // 心跳看门狗：center 每 20 秒发一次 `: ping`。代理 / 负载均衡在上游断掉时可能把连接挂着不关，
+      // 这时一直收不到数据却也不报错——超过 STREAM_SILENCE_MS 没有任何字节就当断线，交给调用方重连。
+      let lastByte = Date.now();
+      let silent = false;
+      let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+      const silenceError = () => new CenterError("实时连接长时间没有数据，正在重连", "NETWORK", 0);
+      // 中止请求之外还要直接取消读取：有的环境里中止信号不会让挂着的 read() 结束。
+      const cut = () => { ctl.abort(); reader?.cancel().catch(() => undefined); };
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastByte > STREAM_SILENCE_MS) { silent = true; cut(); }
+      }, 5_000);
+      void (async () => {
+        try {
+          const response = await doFetch(`${base}/api/jobs/${id(jobId)}/stream?interval_ms=${intervalMs}`, {
+            headers: headers({ Accept: "text/event-stream" }),
+            signal: ctl.signal,
+          });
+          if (!response.ok || !response.body) {
+            const body = (await response.json().catch(() => null)) as { error?: string } | null;
+            const code = body?.error ?? `HTTP_${response.status}`;
+            throw new CenterError(ERROR_TEXT[code] ?? `实时流连接失败（HTTP ${response.status}）`, code, response.status);
+          }
+          handlers.onOpen?.();
+          const parser = createSseParser(({ event, data }) => {
+            let payload: unknown;
+            try { payload = JSON.parse(data); } catch { return; }
+            if (event === "snapshot") handlers.onSnapshot?.(payload as StreamSnapshot);
+            else if (event === "chunk") handlers.onChunk?.((payload as { events?: StreamItem[] }).events ?? []);
+            else if (event === "end") handlers.onEnd?.(payload as StreamEnd);
+          });
+          reader = response.body.getReader();
+          const decoder = new TextDecoder();
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            lastByte = Date.now();
+            parser.push(decoder.decode(value, { stream: true }));
+          }
+          parser.end();
+          if (stopped) return;
+          if (silent) return handlers.onClose?.(silenceError());
+          if (!ctl.signal.aborted) handlers.onClose?.(null);
+        } catch (error) {
+          if (stopped) return;
+          if (silent) return handlers.onClose?.(silenceError());
+          if (ctl.signal.aborted) return;
+          handlers.onClose?.(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+        } finally {
+          clearInterval(watchdog);
+        }
+      })();
+      return () => { stopped = true; clearInterval(watchdog); cut(); };
+    },
+  };
+}
+
+export interface StreamHandlers {
+  onOpen?: () => void;
+  onSnapshot?: (snapshot: StreamSnapshot) => void;
+  onChunk?: (events: StreamItem[]) => void;
+  onEnd?: (end: StreamEnd) => void;
+  /** 流断了（error 为 null = 服务端正常关闭）。onEnd 之后也会触发一次。 */
+  onClose?: (error: CenterError | null) => void;
+}
+
+/** 兼容旧名字。 */
+export type CenterClient = ConversationBackend;
+
+export function firstLine(text: string, max = 40) {
+  const line = text.split("\n").map((value) => value.trim()).find(Boolean) ?? "新对话";
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+}