@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/core/types.ts

@@ -0,0 +1,385 @@
+/**
+ * 两套数据形状：
+ *   · center 服务（cli-task-center）对话任务接口的返回（snake_case，原样保留，便于对照 API 文档）；
+ *   · Operator 节点转录的消息与事件（center 的实时流原样转发，界面按 Operator 的规则渲染）。
+ */
+
+// ── center：对话任务 ────────────────────────────────────────────────
+
+export type JobStatus = "queued" | "bound" | "idle" | "running" | "paused" | "succeeded" | "failed" | "cancelled" | string;
+export type TurnStatus = "queued" | "dispatching" | "running" | "succeeded" | "failed" | "cancelled" | "merged" | string;
+
+export interface CenterTurn {
+  turn_id: string;
+  job_id: string;
+  task_id: string;
+  seq: number;
+  business_id: string | null;
+  status: TurnStatus;
+  input: string;
+  /** 合并了后面排队的消息时，实际发给 Agent 的全文；否则为 null（= input）。 */
+  sent_input: string | null;
+  merged_into_turn_id: string | null;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束：reply 是问题，下一条消息就是回答。 */
+  asked: boolean;
+  last_error: string | null;
+  attempt: number;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  /** true = 节点上的会话重建了，这一轮起之前的对话没带过去（工作区文件还在）。 */
+  context_reset: boolean;
+  /** 这一轮的改动是否已合并回项目基线。 */
+  merged?: boolean;
+  merge_error?: string | null;
+  created_at: string;
+  started_at: string | null;
+  ended_at: string | null;
+  queue_position?: number | null;
+}
+
+export interface CenterTask {
+  id: string;
+  job_id: string;
+  seq?: number;
+  title: string;
+  status: string;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  browser?: boolean;
+  last_error: string | null;
+  /** 接续出来的对话：指回旧对话任务里对应的那个对话。 */
+  continue_from_task_id?: string;
+}
+
+/** 对话任务里的一个对话（一个子任务、一个 Agent 会话）。conversation.conversations 的一项。 */
+export interface ConversationInfo {
+  task_id: string;
+  seq: number;
+  title: string;
+  status: string;
+  /** 关掉了（单独关闭这一个，或整个对话任务结束）。 */
+  closed: boolean;
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  remote_task_id: string | null;
+  continue_from_task_id: string | null;
+  created_at: string | null;
+}
+
+export interface ConversationSummary {
+  /** 里面的每个对话（按开的先后）。旧版 center 没有这个字段：当作只有一个对话。 */
+  conversations?: ConversationInfo[];
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  last_activity_at: string | null;
+  expires_at: string | null;
+  closed_reason: string | null;
+  continued_from_job_id: string | null;
+  continued_by_job_id: string | null;
+}
+
+/** GET /api/jobs/:id */
+export interface CenterJob {
+  id: string;
+  title: string;
+  status: JobStatus;
+  mode?: "conversation" | string;
+  conversation?: ConversationSummary;
+  tasks: CenterTask[];
+}
+
+/** POST /api/jobs/:id/messages、POST /api/jobs/:id/conversations */
+export interface SendResult {
+  job_id: string;
+  /** 实际接收这条消息的对话（对话任务过期接续后是新对话任务里对应的那个）。 */
+  task_id?: string;
+  status: JobStatus;
+  duplicate: boolean;
+  /** true = 原对话已结束，这条消息开了一个新对话（job_id 是新的）。 */
+  new_conversation: boolean;
+  previous_job_id: string | null;
+  queue_position: number | null;
+  turn: CenterTurn;
+}
+
+/** 新建对话时可带的参数（POST /api/jobs，mode=conversation）。 */
+export interface NewConversationOptions {
+  title?: string;
+  /** 业务自己的 ID（tasks[0].business_id）：第一轮的回调里原样带回，用来和业务数据对应。 */
+  businessId?: string;
+  workspace?: { name?: string; context?: string; branch?: string };
+  callback?: { url: string; code: string };
+  agent?: string;
+  timeoutSeconds?: number;
+  browser?: boolean;
+}
+
+// ── Operator：节点转录 ─────────────────────────────────────────────
+
+export type MsgRole = "user" | "assistant" | "tool" | "system" | "session_break";
+
+export interface Message {
+  id: string;
+  task_id?: string;
+  generation: number;
+  role: MsgRole;
+  content: string;
+  created_at: number;
+}
+
+export interface PendingMessage {
+  id: string;
+  generation: number;
+  content: string;
+  created_at: number;
+}
+
+export interface Msg {
+  id: string;
+  /** queued：中枢里还在排队、没送到节点的消息（界面上是可撤回的「排队中」气泡）。 */
+  role: MsgRole | "queued";
+  content: string;
+  generation: number;
+  toolId?: string;
+  ts?: number;
+  /** queued 气泡对应的中枢轮次，撤回时用。 */
+  turnId?: string;
+  /** queued 气泡：中枢给出的等待原因（节点连不上、没有可用节点……），正常排队时为空。 */
+  note?: string;
+}
+
+export interface AskOption { label: string; description?: string }
+export interface AskQuestion { question: string; header: string; multiSelect?: boolean; options: AskOption[] }
+export type AskAnswers = string[][];
+
+export interface InputField { label: string; secret?: boolean; options?: string[]; placeholder?: string }
+export interface InputRequest {
+  id: string;
+  message: string;
+  fields: InputField[];
+  status: "pending" | "answered" | "cancelled";
+  values?: string[];
+}
+
+export type DiffLine = { sign: "+" | "-" | " "; text: string };
+
+export type ToolPeek =
+  | { kind: "count"; text: string }
+  | { kind: "diff"; added: number; removed: number; label?: string; lines: DiffLine[]; truncated?: number }
+  | { kind: "lines"; label?: string; lines: string[]; truncated?: number }
+  | { kind: "todos"; items: { text: string; status: string }[] };
+
+export interface ToolData {
+  title: string;
+  detail?: string;
+  result?: string;
+  isError?: boolean;
+  peek?: ToolPeek;
+  diff?: DiffLine[];
+  ask?: { id: string; questions: AskQuestion[]; answers?: AskAnswers };
+  input?: InputRequest;
+}
+
+export interface TurnUsage {
+  cost_usd: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+}
+
+/** 节点回合事件（center 流里 `{type:"node", event}` 的 event）。 */
+export type NodeEvent =
+  | { type: "user"; content: string; msgId: string; generation: number; ts?: number }
+  | { type: "queued"; msgId: string; content: string; generation: number; ts?: number }
+  | { type: "dequeued"; msgId: string }
+  | { type: "model"; model: string }
+  | { type: "assistant"; content: string; msgId?: string; generation?: number; ts?: number }
+  | { type: "tool"; id: string; title: string; detail: string; peek?: ToolPeek; diff?: DiffLine[]; msgId?: string; generation?: number }
+  | { type: "tool_result"; id: string; content: string; isError: boolean; peek?: ToolPeek; msgId?: string }
+  | { type: "ask"; id: string; questions: AskQuestion[]; msgId?: string; generation?: number }
+  | { type: "ask_answered"; id: string; answers: AskAnswers; msgId?: string }
+  | { type: "input"; input: InputRequest; msgId?: string; generation?: number }
+  | { type: "usage"; usage: TurnUsage }
+  | { type: "notice"; content: string; msgId?: string; generation?: number }
+  | { type: "error"; content: string; msgId?: string; generation?: number }
+  | { type: "turn_end" }
+  | { type: string; [key: string]: unknown };
+
+/** center 实时流 chunk.events 里的一项。 */
+export type StreamItem =
+  | { type: "transcript"; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null }
+  | { type: "node"; event: NodeEvent }
+  | { type: "turn"; turn: CenterTurn }
+  | { type: "job"; job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null } }
+  /** 正在看的这个对话的状态变化（关闭了：closed=true）。 */
+  | { type: "task"; task: StreamTask };
+
+/** 实时流看的那个对话（GET /api/jobs/:id/stream?task=）。 */
+export interface StreamTask { id: string; seq: number; title: string; status: string; closed: boolean; remote_task_id: string | null; continue_from_task_id: string | null }
+
+export interface StreamSnapshot {
+  job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null; mode: string; title: string; conversation: ConversationSummary };
+  /** 旧版 center 没有。 */
+  task?: StreamTask;
+  turns: CenterTurn[];
+}
+
+export interface StreamEnd {
+  /** 对话任务的结束原因；只是这个对话被关闭时为 conversation_closed。 */
+  reason: string;
+  task_id?: string;
+  continued_by_job_id?: string | null;
+  /** 接续这个对话的新对话（新对话任务里的子任务）；还没有为 null。 */
+  continued_by_task_id?: string | null;
+}
+
+// ── center 回调体（与中枢 conversation.ts turnCallbackPayload / job-callback.ts 的字段一一对应） ──
+//
+// 组件在前端发出的 conversation_turn / conversation_closed 事件，载荷与中枢投递给 callback.url 的请求体同名同义，
+// 业务方可以用同一套代码处理「后端回调」和「前端事件」。前端拿不到的字段（event_id、callback_seq、cumulative、
+// carried）不出现；以后端回调为准落库，前端事件只用来刷新界面。
+
+/** 每轮一次：type = "conversation_turn"。 */
+export interface ConversationTurnCallback {
+  type: "conversation_turn";
+  /** 投递顺序号（= seq）。同一对话里按它从小到大处理；结束事件是最后一轮 + 1。 */
+  callback_seq: number;
+  job_id: string;
+  task_id: string;
+  turn_id: string;
+  seq: number;
+  business_id: string | null;
+  /** succeeded / failed / cancelled（被合并的消息不单独回调，见 messages）。 */
+  status: TurnStatus;
+  occurred_at: string;
+  /** 实际发给 Agent 的正文（合并了排队消息时是拼起来的全文）。 */
+  input: string;
+  /** 这一轮包含的全部消息，按发送顺序（排队的消息会合并进来）。 */
+  messages: Array<{ turn_id: string; seq: number; business_id: string | null; input: string }>;
+  reply: string | null;
+  /** true = 这一轮以 Agent 提问结束（reply 是问题），status 仍是 succeeded；下一条消息就是回答。 */
+  asked: boolean;
+  /** 失败 / 取消原因（中枢原文）。 */
+  message: string | null;
+  continued_from_job_id: string | null;
+  context_reset: boolean;
+  merged: boolean;
+  merge_error: string | null;
+  agent: string | null;
+  resolved_model: string | null;
+  total_tokens: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_creation_tokens: number;
+  started_at: string | null;
+  ended_at: string | null;
+}
+
+/** 对话结束一次：type = "conversation_closed"。 */
+export interface ConversationClosedCallback {
+  type: "conversation_closed";
+  mode: "conversation";
+  /** 投递顺序号：最后一轮的 seq + 1，永远排在这个对话所有 conversation_turn 之后。 */
+  callback_seq: number;
+  job_id: string;
+  /** 只关掉了对话任务里的这一个对话时才有（前端事件；center 只在整个对话任务结束时回调）。 */
+  task_id?: string;
+  /** succeeded（关闭 / 过期 / 换线）/ cancelled / failed。 */
+  status: JobStatus;
+  /** closed / cancelled / expired / node_reassigned / node_lost。 */
+  closed_reason: string | null;
+  /** 一共几轮（= 最大的 seq，被合并的消息也算）。 */
+  turns: number;
+  /** 接续出来的新对话（过期、换线、节点丢失后再发消息时才有）。 */
+  continued_by_job_id: string | null;
+  occurred_at: string;
+}
+
+export type ConversationCallback = ConversationTurnCallback | ConversationClosedCallback;
+
+/** 一轮结束时 onTurnEnd 收到的载荷（字段与 center 的 conversation_turn 回调体一致）。 */
+export type TurnEndPayload = ConversationTurnCallback;
+/** 对话结束时 onConversationEnd 收到的载荷（字段与 center 的 conversation_closed 回调体一致）。 */
+export type ConversationEndPayload = ConversationClosedCallback;
+
+// ── 右侧看板（cli-board）：center 的 /api/jobs/:id/board、files、diff、browser ──
+
+export interface BoardInfo {
+  job_id: string;
+  /** false = 还没派发到执行节点（文件和浏览器都还没有）。 */
+  dispatched: boolean;
+  detail?: string;
+  task_id?: string;
+  remote_task_id?: string;
+  node?: { id: string; health: string };
+  files: boolean;
+  /** 节点开了浏览器功能。 */
+  browser: boolean;
+}
+
+export interface FileEntry {
+  name: string;
+  /** 相对工作目录的路径，用 / 分隔。 */
+  path: string;
+  type: "dir" | "file";
+  size: number;
+  mtime: number;
+}
+
+export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean }
+export interface FileInfo { type: "file"; path: string; name: string; size: number; mtime: number; contentType: string; inline: boolean }
+
+export interface DiffFile { path: string; status: string; additions: number; deletions: number; binary: boolean; patch: string; truncated?: boolean }
+/** Operator 的 /api/tasks/:id/diff（经 center 原样转发）。 */
+export interface DiffResult {
+  isolated?: boolean;
+  reason?: string;
+  branch?: string;
+  baseLabel?: string;
+  files?: DiffFile[];
+  isDirty?: boolean;
+  ahead?: number;
+  alreadyMerged?: boolean;
+  error?: string;
+  /** 有的节点只给一整段 unified diff。 */
+  diff?: string;
+  patch?: string;
+}
+
+/** Operator 的任务浏览器状态（/api/tasks/:id/browser）。 */
+export interface BrowserStatus {
+  feature: boolean;
+  state: "none" | "opening" | "running" | "closing";
+  origin: "ai" | "manual" | "check" | null;
+  control: "ai" | "human";
+  handoff: { instruction: string; by: "ai" | "user" | "browser" | "kept" } | null;
+  capability: "config" | "manual" | "ai" | null;
+  viewers: number;
+  spaceName: string;
+  instance: { running: boolean; spaces: number };
+  shownLocally: boolean;
+  error: string | null;
+}
+
+/** 浏览器画面流里的一条消息（节点原样转发）。 */
+export type BrowserMessage =
+  | { type: "frame"; data: string; metadata?: { deviceWidth: number; deviceHeight: number } }
+  | { type: "page"; url?: string; title?: string }
+  | { type: "error"; message?: string };

package/src/elements.tsx

@@ -0,0 +1,166 @@
+/**
+ * Web Component 版：任何页面（不用 React）都能直接放 <cli-msglist> / <cli-chat>。
+ *
+ *   import "@spzxg/cli-ui/styles.css";
+ *   import { defineCliElements } from "@spzxg/cli-ui/elements";
+ *   defineCliElements();
+ *
+ *   <cli-msglist group="a" base-url="/api/center" title="战略"></cli-msglist>
+ *   <cli-chat group="a"></cli-chat>
+ *   <cli-board group="a"></cli-board>      （右侧看板：文件 / 改动 / 浏览器；对话里点文件会在这里打开）
+ *   <cli-file-preview job-id="job_x" path="outputs/报告.md"></cli-file-preview>   （单独的文件预览 + 下载）
+ *   <cli-browser job-id="job_x"></cli-browser>                                  （单独的浏览器实时画面）
+ *
+ * 同一个 group 的元素共享一个仓库：列表点哪个，对话就显示哪个；不写 group 各自独立。
+ * 属性：base-url、token、line、namespace、group、job-id、task-id（对话任务里的哪个对话，"new" = 新开一个；对话 / 看板）、
+ *       title、color、theme、context、read-only、
+ *       tabs（看板页签，逗号分隔：files,changes,browser）、default-tab、file-open（对话：auto / board / modal / link）、
+ *       config（界面配置 JSON）、new-conversation（新建对话参数 JSON：title / businessId / workspace / callback / agent …）。
+ * 界面配置也可以直接赋对象：document.querySelector("cli-chat").config = { header: { export: false } }。
+ * 事件（全在浏览器里从实时流算出，和 center 的 callback.url 无关）：
+ *       cli-turn-end（一轮结束）、cli-conversation-end（对话结束），detail 字段与 center 回调体一致；
+ *       cli-event（全部事件：select / conversation_turn / conversation_closed / job_change / open / error）；
+ *       cli-callback 是旧名字，等同于前两个合在一起，保留兼容。
+ * 渲染在 light DOM 里（不用 Shadow DOM），样式靠页面引入 styles.css，作用域都在 .cli-ui 内。
+ */
+import { createRoot, type Root } from "react-dom/client";
+import { CliMsgList } from "./msglist/CliMsgList.js";
+import { CliChat } from "./chat/CliChat.js";
+import { CliBoard, type BoardTab } from "./board/CliBoard.js";
+import { CliBrowserView, CliFilePreview } from "./board/blocks.js";
+import { createCliStore, type CliStore } from "./core/store.js";
+
+const groups = new Map<string, CliStore>();
+
+function storeFor(el: HTMLElement): CliStore | undefined {
+  const group = el.getAttribute("group");
+  if (!group) return undefined;
+  const baseUrl = el.getAttribute("base-url") ?? undefined;
+  const key = `${group}|${baseUrl ?? ""}`;
+  let store = groups.get(key);
+  if (!store) {
+    store = createCliStore(storeOptions(el));
+    groups.set(key, store);
+  }
+  return store;
+}
+
+const ATTRS = ["base-url", "token", "line", "namespace", "group", "job-id", "task-id", "title", "color", "theme", "context", "read-only", "config", "new-conversation", "tabs", "default-tab", "file-open", "path"];
+
+function jsonAttr(el: HTMLElement, name: string): object | undefined {
+  const raw = el.getAttribute(name);
+  if (!raw) return undefined;
+  try { return JSON.parse(raw) as object; } catch { console.warn(`<${el.localName}> 的 ${name} 不是合法 JSON，已忽略`); return undefined; }
+}
+
+function storeOptions(el: HTMLElement) {
+  return {
+    baseUrl: el.getAttribute("base-url") ?? undefined,
+    token: el.getAttribute("token") ?? undefined,
+    line: el.getAttribute("line") ?? undefined,
+    namespace: el.getAttribute("namespace") ?? el.getAttribute("group") ?? undefined,
+    newConversation: jsonAttr(el, "new-conversation"),
+  };
+}
+
+abstract class CliElement extends HTMLElement {
+  static observedAttributes = ATTRS;
+  private root: Root | null = null;
+  private ownStore: CliStore | undefined;
+  private configValue: object | undefined;
+
+  /** 界面配置（对象）。优先于 config 属性里的 JSON。 */
+  get config(): object | undefined {
+    return this.configValue ?? jsonAttr(this, "config");
+  }
+  set config(value: object | undefined) {
+    this.configValue = value;
+    if (this.root) this.render();
+  }
+
+  connectedCallback() {
+    // 缺省撑满父容器；组件自己内部滚动（宿主给定高度即可）。
+    this.style.display ||= "block";
+    this.style.height ||= "100%";
+    this.style.minHeight ||= "0";
+    this.root ??= createRoot(this);
+    this.render();
+  }
+  disconnectedCallback() {
+    // 移动节点时会先断开再连上：推到下一轮再卸载。
+    queueMicrotask(() => { if (!this.isConnected) { this.root?.unmount(); this.root = null; } });
+  }
+  attributeChangedCallback() { if (this.root) this.render(); }
+
+  protected common() {
+    const store = storeFor(this) ?? (this.ownStore ??= createCliStore(storeOptions(this)));
+    return {
+      store,
+      title: this.getAttribute("title") ?? undefined,
+      color: this.getAttribute("color") ?? undefined,
+      theme: (this.getAttribute("theme") as "light" | "dark" | null) ?? undefined,
+      onEvent: (event: unknown) => this.dispatchEvent(new CustomEvent("cli-event", { detail: event, bubbles: true })),
+      onTurnEnd: (payload: unknown) => this.dispatchEvent(new CustomEvent("cli-turn-end", { detail: payload, bubbles: true })),
+      onConversationEnd: (payload: unknown) => this.dispatchEvent(new CustomEvent("cli-conversation-end", { detail: payload, bubbles: true })),
+      onCallback: (payload: unknown) => this.dispatchEvent(new CustomEvent("cli-callback", { detail: payload, bubbles: true })),
+      style: { height: "100%" },
+      config: this.config as never,
+    };
+  }
+  protected abstract element(): React.ReactNode;
+  private render() { this.root?.render(this.element()); }
+}
+
+class CliMsgListElement extends CliElement {
+  protected element() {
+    const context = this.getAttribute("context");
+    // 结果事件只由 <cli-chat> 发：同一个 group 里列表和对话共用一个仓库，两边都发的话 document 上会收到两遍。
+    const { onTurnEnd: _a, onConversationEnd: _b, onCallback: _c, ...common } = this.common();
+    return <CliMsgList {...common} {...(context !== null ? { context } : {})} />;
+  }
+}
+
+class CliChatElement extends CliElement {
+  protected element() {
+    const jobId = this.getAttribute("job-id");
+    const taskId = this.getAttribute("task-id");
+    const fileOpen = this.getAttribute("file-open") as "auto" | "board" | "modal" | "link" | null;
+    return <CliChat {...this.common()} {...(jobId !== null ? { jobId: jobId || null } : {})} {...(taskId ? { taskId } : {})} readOnly={this.hasAttribute("read-only")} {...(fileOpen ? { fileOpen } : {})} />;
+  }
+}
+
+class CliBoardElement extends CliElement {
+  protected element() {
+    const jobId = this.getAttribute("job-id");
+    const tabs = this.getAttribute("tabs")?.split(",").map((t) => t.trim()).filter(Boolean) as BoardTab[] | undefined;
+    const defaultTab = (this.getAttribute("default-tab") as BoardTab | null) ?? undefined;
+    // 结果事件只由 <cli-chat> 发（同上）；看板只发 cli-event。
+    const { onTurnEnd: _a, onConversationEnd: _b, onCallback: _c, title: _t, color: _k, config: _g, ...common } = this.common();
+    const taskId = this.getAttribute("task-id");
+    return <CliBoard {...common} {...(jobId !== null ? { jobId: jobId || null } : {})} {...(taskId ? { taskId } : {})} tabs={tabs?.length ? tabs : undefined} defaultTab={defaultTab} readOnly={this.hasAttribute("read-only")} />;
+  }
+}
+
+class CliFilePreviewElement extends CliElement {
+  protected element() {
+    const jobId = this.getAttribute("job-id");
+    const { onTurnEnd: _a, onConversationEnd: _b, onCallback: _c, title: _t, color: _k, config: _g, ...common } = this.common();
+    return <CliFilePreview {...common} {...(jobId !== null ? { jobId: jobId || null } : {})} path={this.getAttribute("path") ?? ""} />;
+  }
+}
+
+class CliBrowserElement extends CliElement {
+  protected element() {
+    const jobId = this.getAttribute("job-id");
+    const { onTurnEnd: _a, onConversationEnd: _b, onCallback: _c, title: _t, color: _k, config: _g, ...common } = this.common();
+    return <CliBrowserView {...common} {...(jobId !== null ? { jobId: jobId || null } : {})} readOnly={this.hasAttribute("read-only")} />;
+  }
+}
+
+export function defineCliElements() {
+  if (!customElements.get("cli-msglist")) customElements.define("cli-msglist", CliMsgListElement);
+  if (!customElements.get("cli-chat")) customElements.define("cli-chat", CliChatElement);
+  if (!customElements.get("cli-board")) customElements.define("cli-board", CliBoardElement);
+  if (!customElements.get("cli-file-preview")) customElements.define("cli-file-preview", CliFilePreviewElement);
+  if (!customElements.get("cli-browser")) customElements.define("cli-browser", CliBrowserElement);
+}

package/src/embed.ts

@@ -0,0 +1,58 @@
+/**
+ * 给第三方页面用的一体化入口：引入一个 JS 和一个 CSS 就能用，不需要 React、打包工具或 TypeScript。
+ *
+ *   <link rel="stylesheet" href="/static/cli-ui/cli-ui.css">
+ *   <script type="module" src="/static/cli-ui/cli-ui.js"></script>
+ *   <cli-chat base-url="/api/center" job-id="job_xxx"></cli-chat>
+ *
+ * 引入后自动注册 <cli-chat> / <cli-msglist> / <cli-board>；想用 JS 控制（传回调函数、随时改参数）就用
+ * window.CliUI.mountChat / mountMsgList / mountBoard。几个 mount 要联动（对话里点文件在看板打开）时传同一个 store：
+ *   const store = CliUI.createCliStore({ baseUrl: "/api/center" });
+ *   CliUI.mountChat(a, { store }); CliUI.mountBoard(b, { store });
+ * 产物由 `npm run build:embed -w @spzxg/cli-ui` 生成在 dist/。
+ */
+import "./styles.css";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { defineCliElements } from "./elements.js";
+import { CliChat, type CliChatProps } from "./chat/CliChat.js";
+import { CliMsgList, type CliMsgListProps } from "./msglist/CliMsgList.js";
+import { CliBoard, type CliBoardProps } from "./board/CliBoard.js";
+import { CliBrowserView, CliFilePreview, type CliBrowserViewProps, type CliFilePreviewProps } from "./board/blocks.js";
+import { CliCenterProvider } from "./core/provider.js";
+import { createCliStore } from "./core/store.js";
+import { createCenterClient } from "./core/client.js";
+
+export interface Mounted<P> {
+  /** 合并更新参数（只传要改的）。 */
+  update(next: Partial<P>): void;
+  unmount(): void;
+}
+
+function mount<P extends object>(Component: (props: P) => unknown, el: Element, props: P): Mounted<P> {
+  const root = createRoot(el);
+  let current = props;
+  const render = () => root.render(createElement(Component as never, { style: { height: "100%" }, ...current }));
+  render();
+  return {
+    update(next) { current = { ...current, ...next }; render(); },
+    unmount() { root.unmount(); },
+  };
+}
+
+/** 在一个元素里挂对话组件。参数与 React 的 <CliChat> 相同（jobId、newConversation、onTurnEnd、config……）。 */
+export const mountChat = (el: Element, props: CliChatProps = {}) => mount(CliChat, el, props);
+/** 在一个元素里挂列表组件。参数与 React 的 <CliMsgList> 相同。 */
+export const mountMsgList = (el: Element, props: CliMsgListProps = {}) => mount(CliMsgList, el, props);
+/** 在一个元素里挂右侧看板。参数与 React 的 <CliBoard> 相同（jobId、tabs、fileActions……）。 */
+export const mountBoard = (el: Element, props: CliBoardProps = {}) => mount(CliBoard, el, props);
+/** 单独的文件预览 + 下载：{ jobId, path, baseUrl… }。 */
+export const mountFilePreview = (el: Element, props: CliFilePreviewProps) => mount(CliFilePreview, el, props);
+/** 单独的浏览器实时画面：{ jobId, readOnly, baseUrl… }。 */
+export const mountBrowser = (el: Element, props: CliBrowserViewProps = {}) => mount(CliBrowserView, el, props);
+
+export { defineCliElements, CliChat, CliMsgList, CliBoard, CliFilePreview, CliBrowserView, CliCenterProvider, createCliStore, createCenterClient };
+
+defineCliElements();
+const api = { mountChat, mountMsgList, mountBoard, mountFilePreview, mountBrowser, createCliStore, createCenterClient, defineCliElements };
+(globalThis as { CliUI?: typeof api }).CliUI = api;

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @spzxg/cli-ui —— 任务中心（cli-task-center）对话任务的前端积木，数据全部来自 center 服务。
+ *
+ *   cli-msglist  消息对话列表（CliMsgList）
+ *   cli-chat     对话（CliChat）
+ *   cli-board    右侧看板：工作区文件（预览 / 下载）、改动、任务浏览器（CliBoard）
+ *                 其中两个核心也能单独用：CliFilePreview（文件预览 + 下载）、CliBrowserView（浏览器实时画面）
+ *
+ * 单独用：
+ *   <CliChat baseUrl="/api/center" jobId="job_xxx" />
+ *   <CliChat baseUrl="/api/center" jobId="job_xxx" taskId="task_yyy" />   （对话任务里的某个对话；taskId="new" 新开一个）
+ * 组合用（同一个 Provider 里共享选中和实时流）：
+ *   <CliCenterProvider baseUrl="/api/center" namespace="strategy">
+ *     <CliMsgList title="战略" />
+ *     <CliChat />
+ *   </CliCenterProvider>
+ *
+ *   import "@spzxg/cli-ui/styles.css";
+ * 非 React 页面用 Web Component：import { defineCliElements } from "@spzxg/cli-ui/elements"。
+ */
+export { CliMsgList, type CliMsgListProps } from "./msglist/CliMsgList.js";
+export { CliChat, type CliChatProps } from "./chat/CliChat.js";
+export { CliBoard, type CliBoardProps, type BoardTab } from "./board/CliBoard.js";
+export { CliFilePreview, CliBrowserView, type CliFilePreviewProps, type CliBrowserViewProps } from "./board/blocks.js";
+export { FileViewer, downloadFile, type FileViewerProps, type FileAction } from "./board/FileViewer.js";
+export { BrowserPane } from "./board/BrowserPane.js";
+export { CliCenterProvider, useCliStore, useCliState, type CliCenterProviderProps, type ResultHandlers } from "./core/provider.js";
+
+export {
+  resolveChatConfig, resolveMsgListConfig, DEFAULT_CHAT_CONFIG, DEFAULT_MSGLIST_CONFIG,
+  type CliChatConfig, type CliMsgListConfig, type ResolvedChatConfig, type ResolvedMsgListConfig,
+} from "./core/config.js";
+export { createCliStore, type CliStore, type CliStoreOptions, type CliState, type CliEvent, type JobEntry, type OpenTarget } from "./core/store.js";
+export { createCenterClient, CenterError, boardFileUrl, type CenterClient, type CenterClientOptions, type StreamHandlers, type BoardBackend, type ConversationBackend } from "./core/client.js";
+export { viewMessages, isRunning, runningTurn, convKey, parseConvKey, NEW_TASK, type ConvState } from "./core/conversation.js";
+export {
+  composeMessage, splitMessage, serializeBlock, readFileText, isLongText, ACCEPTED_EXTENSIONS, MAX_MESSAGE_CHARS,
+  type TextBlock, type MessagePart,
+} from "./core/blocks.js";
+export type * from "./core/types.js";