@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/core/client.ts

@@ -0,0 +1,441 @@
+import { createSseParser } from "./sse.js";
+import { NEW_TASK, parseConvKey } from "./conversation.js";
+import type {
+  BoardInfo, BrowserMessage, BrowserStatus, CenterJob, CenterTask, CenterTurn, DiffResult, DirListing, FileInfo,
+  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;
+  /**
+   * 看板里的文件能不能直接用地址打开（<img src>、<iframe src>、下载链接）。缺省：没给 token / headers / line 时可以
+   * （同源代理注入令牌）；否则浏览器直接请求带不上请求头，看板改为先 fetch 再用 blob 地址显示。
+   */
+  directFileLinks?: boolean;
+}
+
+/** 实时流超过这么久没有任何数据（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: "这个任务不是对话任务",
+  conversation_not_found: "这个对话不在对应的对话任务里",
+  too_many_conversations: "这个对话任务里开的对话太多了，请新建对话任务",
+  not_found: "对话不存在，或不属于当前产品线",
+  unauthorized: "没有权限访问任务中心（产品线令牌缺失或失效）",
+  conversation_requires_one_task: "对话任务只能有一条首轮消息",
+  conversation_prompt_required: "第一条消息不能为空",
+  not_dispatched: "任务还没派发到执行节点",
+  node_unreachable: "执行节点暂时连不上，稍后会自动重试",
+  node_outdated: "执行节点的 Operator 版本较旧，不支持这个功能，请升级节点",
+  too_many_viewers: "同时观看这个浏览器的人太多，请稍后再试",
+  viewer_not_found: "画面连接已断开，正在重连",
+  viewer_not_ready: "画面连接还没就绪，正在重连",
+};
+
+/**
+ * 组件用到的数据后端。界面只依赖这个接口，不直接依赖 center 的地址和字段：
+ *   · 现在的实现是 center 的对话任务接口（createCenterClient）；
+ *   · 以后把组件放进 Operator 自己的界面时，换一个实现这套接口的 Operator 后端即可，界面不用改。
+ * 带 ? 的是可选能力：后端不提供，界面就按 Operator 在「没有这个能力」时的样子显示（例如提问的回答改走下一条消息）。
+ */
+export interface ConversationBackend {
+  baseUrl: string;
+  getJob(jobId: string): Promise<CenterJob>;
+  /** taskId：只要对话任务里这一个对话的轮次。 */
+  listTurns(jobId: string, query?: { afterSeq?: number; limit?: number; taskId?: string }): 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; task_ids?: string[]; turn: CenterTurn }>;
+  /** taskId：发给对话任务里的哪个对话，不给 = 第一个。 */
+  sendMessage(jobId: string, text: string, opts?: { businessId?: string; timeoutSeconds?: number; taskId?: string }): Promise<SendResult>;
+  /** 在对话任务里新开一个对话（同一节点、同一工作区），text 是它的第一条消息。 */
+  openConversation?(jobId: string, text: string, opts?: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
+  cancelTurn(jobId: string, turnId: string): Promise<CenterTurn>;
+  closeConversation(jobId: string): Promise<{ id: string; status: string }>;
+  /** 只关掉对话任务里的一个对话（别的对话和对话任务照常）。 */
+  closeConversationTask?(jobId: string, taskId: string): Promise<{ job_id: string; task_id: string; status: string; closed: boolean }>;
+  /** taskId：看对话任务里的哪个对话，不给 = 第一个。 */
+  stream(jobId: string, handlers: StreamHandlers, intervalMs?: number, taskId?: string | null): () => 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>;
+  /** 右侧看板用到的能力（cli-board）。后端没有时看板显示「不支持」。 */
+  board?: BoardBackend;
+}
+
+/**
+ * 右侧看板（cli-board）：工作区文件、改动、任务浏览器。全部经 center 转发，浏览器不直连节点。
+ * 方法里的 jobId 也可以是对话键（"job_x#task_y"）：看对话任务里那个对话的文件、改动和浏览器。
+ */
+export interface BoardBackend {
+  /** fileUrl 给出的地址浏览器能直接打开（不需要额外请求头）。false 时看板先 fetch 再显示。 */
+  directLinks: boolean;
+  info(jobId: string): Promise<BoardInfo>;
+  /** 目录（缺省根目录）或文件的信息。 */
+  stat(jobId: string, path?: string): Promise<DirListing | FileInfo>;
+  /** 文件地址（给 <img> / <iframe> / 下载链接用）。相对路径用路径式地址，HTML 里的相对资源能跟着解析。 */
+  fileUrl(jobId: string, path: string, opts?: { download?: boolean }): string;
+  /** 读文本（最多 maxBytes，超过的截断）。 */
+  readText(jobId: string, path: string, maxBytes?: number): Promise<{ text: string; truncated: boolean; size: number; contentType: string }>;
+  readBuffer(jobId: string, path: string): Promise<ArrayBuffer>;
+  diff(jobId: string): Promise<DiffResult>;
+  browserStatus(jobId: string): Promise<BrowserStatus>;
+  browserAction(jobId: string, action: "open" | "close" | "takeover" | "handback"): Promise<BrowserStatus>;
+  /** 浏览器状态实时流；返回停止函数。onClose 在断开时调用（error 为 null 表示正常结束）。 */
+  browserEvents(jobId: string, handlers: { onStatus: (status: BrowserStatus) => void; onClose?: (error: CenterError | null) => void }): () => void;
+  /** 浏览器实时画面；onViewer 给出发输入要用的 viewer id。 */
+  browserFrames(jobId: string, handlers: { onViewer: (viewer: string) => void; onMessage: (message: BrowserMessage) => void; onEnd?: (end: { reason: string; detail?: string }) => void; onClose?: (error: CenterError | null) => void }): () => void;
+  browserInput(jobId: string, viewer: string, events: Array<Record<string, unknown>>): Promise<void>;
+}
+
+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; taskId?: string } = {}) => {
+      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));
+      if (query.taskId) params.set("task", query.taskId);
+      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; task_ids?: 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; taskId?: string } = {}) =>
+      post<SendResult>(`/api/jobs/${id(jobId)}/messages`, {
+        text,
+        ...(opts.taskId ? { task_id: opts.taskId } : {}),
+        ...(opts.businessId ? { business_id: opts.businessId } : {}),
+        ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
+      }),
+    /** 同一个 business_id 重发只开一个对话。 */
+    openConversation: (jobId: string, text: string, opts: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number } = {}) =>
+      post<SendResult>(`/api/jobs/${id(jobId)}/conversations`, {
+        text,
+        ...(opts.title ? { title: opts.title } : {}),
+        ...(opts.agent ? { agent: opts.agent } : {}),
+        ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
+        ...(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`),
+    closeConversationTask: (jobId: string, taskId: string) =>
+      post<{ job_id: string; task_id: string; status: string; closed: boolean }>(`/api/jobs/${id(jobId)}/conversations/${id(taskId)}/close`),
+    /**
+     * 订阅对话的实时流（GET /api/jobs/:id/stream）。返回关闭函数。
+     * 不自动重连：重连策略（退避、结束后不再连）由调用方决定。
+     */
+    board: createBoardClient(base, headers, doFetch, request, options.directFileLinks ?? (!options.token && !options.headers && !options.line)),
+    stream(jobId: string, handlers: StreamHandlers, intervalMs = 300, taskId?: string | null): () => 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}${taskId ? `&task=${id(taskId)}` : ""}`, {
+            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;
+}
+
+/** 读一条 SSE（fetch 读流，能带鉴权头），按事件名回调。返回停止函数。 */
+function openSse(
+  doFetch: typeof fetch,
+  url: string,
+  headers: Record<string, string>,
+  onEvent: (event: string, data: unknown) => void,
+  onClose?: (error: CenterError | null) => void,
+): () => void {
+  const ctl = new AbortController();
+  // 静默看门狗：center 每 20 秒发一次心跳，超过 STREAM_SILENCE_MS 什么都没收到（网络静默断开、代理挂住）就当断线。
+  let silent = false;
+  let watchdog: ReturnType<typeof setTimeout> | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  const arm = () => {
+    if (watchdog) clearTimeout(watchdog);
+    // 同时取消读取：宿主自定义的 fetch 不一定理会 signal。
+    watchdog = setTimeout(() => { silent = true; ctl.abort(); void reader?.cancel().catch(() => undefined); }, STREAM_SILENCE_MS);
+  };
+  void (async () => {
+    try {
+      arm();
+      const response = await doFetch(url, { headers: { ...headers, Accept: "text/event-stream" }, signal: ctl.signal });
+      if (!response.ok || !response.body) {
+        const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
+        throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? `连接失败（HTTP ${response.status}）`, body?.error ?? `HTTP_${response.status}`, response.status);
+      }
+      const parser = createSseParser(({ event, data }) => {
+        try { onEvent(event, JSON.parse(data)); } catch { /* 不是 JSON 的忽略 */ }
+      });
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        arm();
+        parser.push(decoder.decode(value, { stream: true }));
+      }
+      parser.end();
+      if (watchdog) clearTimeout(watchdog);
+      if (silent) { onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0)); return; }
+      if (!ctl.signal.aborted) onClose?.(null);
+    } catch (error) {
+      if (watchdog) clearTimeout(watchdog);
+      if (silent) { onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0)); return; }
+      if (ctl.signal.aborted) return;
+      onClose?.(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+    }
+  })();
+  return () => { if (watchdog) clearTimeout(watchdog); ctl.abort(); void reader?.cancel().catch(() => undefined); };
+}
+
+/** 看板请求的对象：对话键 → 对话任务 + 子任务（「新开」的占位不算，看对话任务缺省的那个）。 */
+function boardTarget(key: string) {
+  const { jobId, taskId } = parseConvKey(key);
+  return { job: encodeURIComponent(jobId), task: taskId && taskId !== NEW_TASK ? encodeURIComponent(taskId) : null };
+}
+
+/**
+ * 相对路径 → 路径式地址（各段编码）；绝对路径 / ~ 开头 → ?path=。jobId 可以是对话键：
+ * 指定了子任务时路径式地址带上它（/tasks/<子任务>/files/raw/…），HTML 里的相对资源也落在同一个对话上。
+ */
+export function boardFileUrl(base: string, jobId: string, path: string, download = false) {
+  const { job: id, task } = boardTarget(jobId);
+  const clean = path.replace(/^\.\//, "");
+  const absolute = clean.startsWith("/") || clean.startsWith("~") || /^[a-z]:[\\/]/i.test(clean);
+  if (absolute) return `${base}/api/jobs/${id}/files/raw?path=${encodeURIComponent(clean)}${task ? `&task=${task}` : ""}${download ? "&download=1" : ""}`;
+  const segs = clean.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+  return `${base}/api/jobs/${id}${task ? `/tasks/${task}` : ""}/files/raw/${segs}${download ? "?download=1" : ""}`;
+}
+
+/** 看板接口地址：/api/jobs/<job>/<rest>，指定了子任务时加 task 参数。 */
+function boardPath(key: string, rest: string, query = "") {
+  const { job, task } = boardTarget(key);
+  const params = [query, task ? `task=${task}` : ""].filter(Boolean).join("&");
+  return `/api/jobs/${job}/${rest}${params ? `?${params}` : ""}`;
+}
+
+function createBoardClient(
+  base: string,
+  headers: (extra?: Record<string, string>) => Record<string, string>,
+  doFetch: typeof fetch,
+  request: <T>(path: string, init?: RequestInit) => Promise<T>,
+  directLinks: boolean,
+): BoardBackend {
+  const fileFetch = async (jobId: string, path: string) => {
+    let response: Response;
+    try {
+      response = await doFetch(boardFileUrl(base, jobId, path), { headers: headers() });
+    } catch (error) {
+      throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+    }
+    if (!response.ok) {
+      const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
+      throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? body?.error ?? `读取失败（HTTP ${response.status}）`, body?.error ?? `HTTP_${response.status}`, response.status);
+    }
+    return response;
+  };
+  return {
+    directLinks,
+    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
+    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
+    fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
+    async readText(jobId, path, maxBytes = 512 * 1024) {
+      const response = await fileFetch(jobId, path);
+      const contentType = response.headers.get("content-type") ?? "";
+      const size = Number(response.headers.get("content-length") ?? 0);
+      // 只读前 maxBytes：大文件不整个拉进浏览器。
+      const reader = response.body?.getReader();
+      if (!reader) return { text: await response.text(), truncated: false, size, contentType };
+      const chunks: Uint8Array[] = [];
+      let got = 0;
+      let truncated = false;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        got += value.length;
+        if (got >= maxBytes) { truncated = true; await reader.cancel().catch(() => undefined); break; }
+      }
+      const all = new Uint8Array(Math.min(got, maxBytes));
+      let offset = 0;
+      for (const chunk of chunks) {
+        const take = Math.min(chunk.length, all.length - offset);
+        all.set(chunk.subarray(0, take), offset);
+        offset += take;
+        if (offset >= all.length) break;
+      }
+      return { text: new TextDecoder().decode(all), truncated, size: size || got, contentType };
+    },
+    readBuffer: async (jobId, path) => (await fileFetch(jobId, path)).arrayBuffer(),
+    diff: (jobId) => request<DiffResult>(boardPath(jobId, "diff")),
+    browserStatus: (jobId) => request<BrowserStatus>(boardPath(jobId, "browser")),
+    browserAction: (jobId, action) => request<BrowserStatus>(boardPath(jobId, "browser"), { method: "POST", body: JSON.stringify({ action }) }),
+    browserEvents: (jobId, handlers) => openSse(doFetch, `${base}${boardPath(jobId, "browser/events")}`, headers(), (event, data) => {
+      if (event === "status") handlers.onStatus(data as BrowserStatus);
+    }, handlers.onClose),
+    browserFrames: (jobId, handlers) => openSse(doFetch, `${base}${boardPath(jobId, "browser/frames")}`, headers(), (event, data) => {
+      if (event === "viewer") handlers.onViewer((data as { viewer: string }).viewer);
+      else if (event === "message") handlers.onMessage(data as BrowserMessage);
+      else if (event === "end") handlers.onEnd?.(data as { reason: string; detail?: string });
+    }, handlers.onClose),
+    async browserInput(jobId, viewer, events) {
+      await request(boardPath(jobId, "browser/input"), { method: "POST", body: JSON.stringify({ viewer, events }) });
+    },
+  };
+}

package/src/core/config.ts

@@ -0,0 +1,222 @@
+/**
+ * 组件的界面配置：哪些模块显示、文案怎么写。全部可选，不给就是缺省（全部显示、默认文案）。
+ *
+ *   <CliChat config={{ header: { export: false, close: false }, composer: { placeholder: "问点什么…", fileUpload: false } }} />
+ *   <CliMsgList config={{ header: { refresh: false }, card: { turns: false } }} />
+ *
+ * 开关类的模块写 false 就整块隐藏，写对象就逐项开关；文案里可以用 {title}（对话标题）、{agent}（智能体名）。
+ */
+
+// ── cli-chat ─────────────────────────────────────────
+
+export interface CliChatConfig {
+  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  header?: boolean | {
+    /** 面包屑：色块 + 名称 / 对话。 */
+    crumb?: boolean;
+    /** 「导出执行过程」按钮。 */
+    export?: boolean;
+    /** 对话标题。 */
+    title?: boolean;
+    /** 智能体标签（Codex / Claude Code）。 */
+    agent?: boolean;
+    /** token 用量。 */
+    usage?: boolean;
+    /** 模型（默认 + 实际模型）。 */
+    model?: boolean;
+    /** 对话状态（运行中 / 需要你处理 / 已结束）。 */
+    status?: boolean;
+    /** 「结束对话」按钮。 */
+    close?: boolean;
+  };
+  /** 底部输入框。false = 不显示输入框（只读）；对象 = 逐项配置。 */
+  composer?: boolean | {
+    /** 回复时的占位文案，可用 {title} {agent}。 */
+    placeholder?: string;
+    /** 新对话（还没有 jobId）时的占位文案。 */
+    placeholderNew?: string;
+    /** 智能体正在执行、发的消息会排队时的占位文案。 */
+    placeholderRunning?: string;
+    /** 不能发送时（对话已结束、只读）的占位文案。 */
+    placeholderDisabled?: string;
+    /** 底部「⏎ 发送 / ⇧⏎ 换行」提示。 */
+    hints?: boolean;
+    /** 底部字数统计。 */
+    charCount?: boolean;
+    /** 文件上传（按钮、拖拽、粘贴文件）。只收 TXT / Markdown / Word。 */
+    fileUpload?: boolean;
+    /** 「文件」按钮的文字。 */
+    fileButtonText?: string;
+    /** 运行中的停止按钮。 */
+    stop?: boolean;
+    /** 运行中允许发消息排队；false = 运行中不能发。 */
+    queue?: boolean;
+  };
+  /** 对话区。 */
+  transcript?: {
+    /** 右下角的上一条 / 下一条 / 跳到最新按钮。 */
+    nav?: boolean;
+    /** 「第 1 次会话 · 当前」分隔线。 */
+    sessionLabel?: boolean;
+    /** 消息时间。 */
+    timestamps?: boolean;
+    /** 首条消息上的「初始提示」「已随项目上下文发送」标记。 */
+    initialBadge?: boolean;
+    /** 工具调用卡片（命令、读写文件……）；false 只留文字往来（提问卡片照常显示）。 */
+    tools?: boolean;
+    /** 「智能体 · 运行中 0:12」那一行。 */
+    runningIndicator?: boolean;
+  };
+  /** 消息头上的称呼。 */
+  labels?: { user?: string; agent?: string };
+  /** 新对话的空白页。false = 不显示。 */
+  empty?: boolean | { title?: string; description?: string };
+}
+
+export interface ResolvedChatConfig {
+  header: { show: boolean; crumb: boolean; export: boolean; title: boolean; agent: boolean; usage: boolean; model: boolean; status: boolean; close: boolean };
+  composer: {
+    show: boolean; placeholder: string; placeholderNew: string; placeholderRunning: string; placeholderDisabled: string | null;
+    hints: boolean; charCount: boolean; fileUpload: boolean; fileButtonText: string; stop: boolean; queue: boolean;
+  };
+  transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean };
+  labels: { user: string; agent: string };
+  empty: { show: boolean; title: string; description: string };
+}
+
+export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
+  header: { show: true, crumb: true, export: true, title: true, agent: true, usage: true, model: true, status: true, close: true },
+  composer: {
+    show: true,
+    placeholder: "在“{title}”中回复 {agent}…（可拖入 TXT / Markdown / Word 文件）",
+    placeholderNew: "输入第一条消息，开始新对话…（可拖入 TXT / Markdown / Word 文件）",
+    placeholderRunning: "排队一条后续消息…（本轮结束后发送）",
+    placeholderDisabled: null,
+    hints: true, charCount: true, fileUpload: true, fileButtonText: "文件", stop: true, queue: true,
+  },
+  transcript: { nav: true, sessionLabel: true, timestamps: true, initialBadge: true, tools: true, runningIndicator: true },
+  labels: { user: "你", agent: "智能体" },
+  empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 TXT、Markdown 或 Word 文件，内容会转成文字一起发送。" },
+};
+
+export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfig {
+  const d = DEFAULT_CHAT_CONFIG;
+  const header = toggle(config.header, d.header);
+  const composer = toggle(config.composer, d.composer);
+  const empty = toggle(config.empty, d.empty);
+  // 没有文件上传时，缺省文案里的「可拖入文件」提示也去掉。
+  if (!composer.fileUpload) {
+    const strip = (text: string) => text.replace(/（可拖入 TXT \/ Markdown \/ Word 文件）$/, "");
+    if (!isObj(config.composer) || config.composer.placeholder === undefined) composer.placeholder = strip(composer.placeholder);
+    if (!isObj(config.composer) || config.composer.placeholderNew === undefined) composer.placeholderNew = strip(composer.placeholderNew);
+  }
+  return {
+    header,
+    composer,
+    transcript: { ...d.transcript, ...defined(config.transcript) },
+    labels: { ...d.labels, ...defined(config.labels) },
+    empty,
+  };
+}
+
+// ── cli-msglist ──────────────────────────────────────
+
+export interface CliMsgListConfig {
+  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  header?: boolean | {
+    /** 色块 + 名称。 */
+    title?: boolean;
+    /** 「+ 对话」按钮。 */
+    newButton?: boolean;
+    /** 「+ 对话」按钮的文字。 */
+    newButtonText?: string;
+    /** 刷新按钮。 */
+    refresh?: boolean;
+    /** 上下文说明框（需同时给 context 或 onEditContext）。 */
+    context?: boolean;
+  };
+  /** 搜索框：true 总是显示，false 不显示，"auto"（缺省）对话数 ≥ 6 时显示。 */
+  search?: boolean | "auto";
+  searchPlaceholder?: string;
+  /** 卡片上显示哪些内容。 */
+  card?: {
+    /** 状态点和状态文字。 */
+    status?: boolean;
+    /** 智能体标签。 */
+    agent?: boolean;
+    /** 第一条消息摘要。 */
+    description?: boolean;
+    /** 底部活动（运行中 · 3 分钟前……）。 */
+    activity?: boolean;
+    /** 「N 轮对话」。 */
+    turns?: boolean;
+    /** 「+」按钮：在这个任务（对话任务）里新开一个对话，共用同一个工作区。 */
+    newInJob?: boolean;
+  };
+  /** 分组标题；写 false 隐藏这一组。 */
+  groups?: { needs?: string | false; active?: string | false; done?: string | false; cancelled?: string | false };
+  /** 没有对话时的提示。 */
+  emptyTitle?: string;
+  emptyDescription?: string;
+}
+
+export interface ResolvedMsgListConfig {
+  header: { show: boolean; title: boolean; newButton: boolean; newButtonText: string; refresh: boolean; context: boolean };
+  search: boolean | "auto";
+  searchPlaceholder: string;
+  card: { status: boolean; agent: boolean; description: boolean; activity: boolean; turns: boolean; newInJob: boolean };
+  groups: { needs: string | false; active: string | false; done: string | false; cancelled: string | false };
+  emptyTitle: string;
+  emptyDescription: string;
+}
+
+export const DEFAULT_MSGLIST_CONFIG: ResolvedMsgListConfig = {
+  header: { show: true, title: true, newButton: true, newButtonText: "对话", refresh: true, context: true },
+  search: "auto",
+  searchPlaceholder: "搜索对话…",
+  card: { status: true, agent: true, description: true, activity: true, turns: true, newInJob: true },
+  groups: { needs: "需要你处理", active: "进行中", done: "已结束", cancelled: "已取消" },
+  emptyTitle: "还没有对话",
+  emptyDescription: "点「对话」开始一个新的对话。",
+};
+
+export function resolveMsgListConfig(config: CliMsgListConfig = {}): ResolvedMsgListConfig {
+  const d = DEFAULT_MSGLIST_CONFIG;
+  return {
+    header: toggle(config.header, d.header),
+    search: config.search ?? d.search,
+    searchPlaceholder: config.searchPlaceholder ?? d.searchPlaceholder,
+    card: { ...d.card, ...defined(config.card) },
+    groups: { ...d.groups, ...defined(config.groups) },
+    emptyTitle: config.emptyTitle ?? d.emptyTitle,
+    emptyDescription: config.emptyDescription ?? d.emptyDescription,
+  };
+}
+
+// ── 小工具 ───────────────────────────────────────────
+
+/** 文案模板：{title}、{agent}。 */
+export function fillTemplate(template: string, vars: Record<string, string>) {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => (key in vars ? vars[key] : match));
+}
+
+const isObj = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object";
+
+/** 去掉值为 undefined 的键，免得盖掉缺省值。 */
+function defined<T extends object>(value: T | undefined): Partial<T> {
+  if (!value) return {};
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+/**
+ * 开关型模块：false → 全关（show=false 且布尔项全 false，文案保留）；true / 不给 → 缺省；对象 → 合并缺省。
+ */
+function toggle<T extends { show: boolean }>(value: boolean | object | undefined, defaults: T): T {
+  if (value === false) {
+    const off = { ...defaults, show: false } as Record<string, unknown>;
+    for (const key of Object.keys(off)) if (typeof off[key] === "boolean") off[key] = false;
+    return off as T;
+  }
+  if (!isObj(value)) return { ...defaults };
+  return { ...defaults, ...defined(value as Partial<T>), show: true };
+}