@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/core/xlsx.ts

@@ -0,0 +1,142 @@
+// Excel（.xlsx / .xlsm）→ 纯文本：每个工作表一段 CSV，发给智能体。
+//
+// .xlsx 是 ZIP 里的一堆 XML：workbook.xml 列出工作表，sharedStrings.xml 是共享字符串，worksheets/sheetN.xml 是单元格。
+// 只取单元格的值（公式取缓存的结果），不要格式、图片、图表；日期按单元格格式认出来写成 2026-08-10（带时间的加上时分），
+// 百分比写成 0.6%（和表格里看到的一致）。
+// 老版 .xls（二进制）读不了，调用方提示另存为 .xlsx。
+
+export interface SheetText { name: string; hidden: boolean; rows: string[][] }
+
+const NS_MAIN = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const NS_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+/** 内置的日期 / 时间数字格式编号。 */
+const BUILTIN_DATE_FMTS = new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 27, 30, 36, 45, 46, 47, 50, 57]);
+
+const parseXml = (text: string) => new DOMParser().parseFromString(text, "application/xml");
+const els = (root: Document | Element, tag: string) => Array.from(root.getElementsByTagNameNS(NS_MAIN, tag));
+
+/** 「A1」→ 列号（从 0 开始）。 */
+export function columnIndex(ref: string) {
+  let n = 0;
+  for (const ch of ref) {
+    const c = ch.toUpperCase().charCodeAt(0);
+    if (c < 65 || c > 90) break;
+    n = n * 26 + (c - 64);
+  }
+  return n - 1;
+}
+
+/** 自定义格式里有年月日时（引号里的、[颜色] 不算）就当日期。 */
+function isDateFormat(code: string) {
+  const bare = code.replace(/"[^"]*"/g, "").replace(/\[[^\]]*\]/g, "").replace(/\\./g, "");
+  return /[ymdhs]/i.test(bare) && !/^[#0.,%E+\-\s]*$/i.test(bare);
+}
+
+/** Excel 序列日期 → 2026-08-10 / 2026-08-10 14:30。 */
+export function excelDate(serial: number) {
+  const ms = Math.round((serial - 25569) * 86_400_000); // 1970-01-01 = 25569
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return String(serial);
+  const p = (n: number) => String(n).padStart(2, "0");
+  const date = `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}`;
+  const secs = d.getUTCHours() * 3600 + d.getUTCMinutes() * 60 + d.getUTCSeconds();
+  if (!secs) return date;
+  const time = `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}${d.getUTCSeconds() ? `:${p(d.getUTCSeconds())}` : ""}`;
+  return serial < 1 ? time : `${date} ${time}`;
+}
+
+/** 单元格里的文字：<t> 连起来（富文本是多段 <r><t>），不要注音（<rPh>）。 */
+function richText(el: Element) {
+  return els(el, "t").filter((t) => t.parentElement?.localName !== "rPh").map((t) => t.textContent ?? "").join("");
+}
+
+/** 读出所有工作表（按工作簿里的顺序）。 */
+export async function readXlsx(data: ArrayBuffer): Promise<SheetText[]> {
+  // 按需加载（mammoth 也用它，不额外增加体积）。
+  const mod = (await import("jszip")) as unknown as { default?: typeof import("jszip") } & typeof import("jszip");
+  const JSZip = mod.default ?? mod;
+  const zip = await JSZip.loadAsync(data);
+  const read = async (path: string) => { const f = zip.file(path); return f ? f.async("string") : null; };
+
+  const workbook = await read("xl/workbook.xml");
+  if (!workbook) throw new Error("不是 Excel 工作簿");
+  const rels = new Map<string, string>();
+  const relsXml = await read("xl/_rels/workbook.xml.rels");
+  if (relsXml) {
+    for (const r of Array.from(parseXml(relsXml).getElementsByTagName("Relationship"))) {
+      const target = r.getAttribute("Target") ?? "";
+      rels.set(r.getAttribute("Id") ?? "", target.startsWith("/") ? target.slice(1) : `xl/${target}`);
+    }
+  }
+  const shared: string[] = [];
+  const sharedXml = await read("xl/sharedStrings.xml");
+  if (sharedXml) for (const si of els(parseXml(sharedXml), "si")) shared.push(richText(si));
+
+  // 哪些样式是日期 / 百分比：cellXfs 第 i 个 → numFmtId → 内置格式或自定义格式。
+  const dateStyles = new Set<number>();
+  const percentStyles = new Set<number>();
+  const stylesXml = await read("xl/styles.xml");
+  if (stylesXml) {
+    const styles = parseXml(stylesXml);
+    const custom = new Map(els(styles, "numFmt").map((f) => [Number(f.getAttribute("numFmtId")), f.getAttribute("formatCode") ?? ""]));
+    const xfs = els(styles, "cellXfs")[0];
+    if (xfs) {
+      Array.from(xfs.children).filter((x) => x.localName === "xf").forEach((xf, i) => {
+        const id = Number(xf.getAttribute("numFmtId") ?? 0);
+        const code = custom.get(id);
+        if (BUILTIN_DATE_FMTS.has(id) || (code !== undefined && isDateFormat(code))) dateStyles.add(i);
+        else if (id === 9 || id === 10 || (code !== undefined && code.replace(/"[^"]*"/g, "").includes("%"))) percentStyles.add(i);
+      });
+    }
+  }
+
+  const sheets: SheetText[] = [];
+  for (const s of els(parseXml(workbook), "sheet")) {
+    const name = s.getAttribute("name") ?? `Sheet${sheets.length + 1}`;
+    const path = rels.get(s.getAttributeNS(NS_REL, "id") ?? s.getAttribute("r:id") ?? "") ?? `xl/worksheets/sheet${sheets.length + 1}.xml`;
+    const xml = await read(path);
+    if (!xml) continue;
+    const rows: string[][] = [];
+    for (const row of els(parseXml(xml), "row")) {
+      const r = Number(row.getAttribute("r")) || rows.length + 1;
+      const cells: string[] = [];
+      let next = 0;
+      for (const c of Array.from(row.children).filter((x) => x.localName === "c")) {
+        const ref = c.getAttribute("r");
+        const col = ref ? columnIndex(ref) : next;
+        next = col + 1;
+        const type = c.getAttribute("t");
+        const v = els(c, "v")[0]?.textContent ?? "";
+        let value: string;
+        if (type === "s") value = shared[Number(v)] ?? "";
+        else if (type === "inlineStr") value = richText(c);
+        else if (type === "b") value = v === "1" ? "TRUE" : v === "0" ? "FALSE" : v;
+        else if (type === "str" || type === "e" || !v) value = v;
+        else if (dateStyles.has(Number(c.getAttribute("s") ?? -1)) && Number.isFinite(Number(v))) value = excelDate(Number(v));
+        else if (percentStyles.has(Number(c.getAttribute("s") ?? -1)) && Number.isFinite(Number(v))) value = `${Number((Number(v) * 100).toPrecision(12))}%`;
+        else value = v;
+        cells[col] = value;
+      }
+      rows[r - 1] = Array.from(cells, (x) => x ?? "");
+    }
+    const dense = Array.from(rows, (x) => x ?? []);
+    // 去掉末尾的空行、每行末尾的空格子。
+    while (dense.length && dense[dense.length - 1].every((x) => !x)) dense.pop();
+    for (const row of dense) while (row.length && !row[row.length - 1]) row.pop();
+    sheets.push({ name, hidden: (s.getAttribute("state") ?? "visible") !== "visible", rows: dense });
+  }
+  return sheets;
+}
+
+const csvCell = (v: string) => (/[",\n\r]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v);
+
+/** 工作表 → 发给智能体的文字：每个工作表一个标题 + CSV。 */
+export function sheetsToText(sheets: SheetText[]) {
+  return sheets
+    .map((s) => {
+      const head = `## 工作表：${s.name}${s.hidden ? "（隐藏）" : ""}（${s.rows.length} 行）`;
+      return s.rows.length ? `${head}\n${s.rows.map((r) => r.map(csvCell).join(",")).join("\n")}` : `${head}\n（空）`;
+    })
+    .join("\n\n");
+}

package/src/elements.tsx

@@ -0,0 +1,376 @@
+/**
+ * Web Component 版：任何页面（不用 React）都能直接放 <cli-msglist> / <cli-chat>。
+ *
+ *   import "@xgspz/cli-ui/styles.css";
+ *   import { defineCliElements } from "@xgspz/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>                                  （单独的浏览器实时画面）
+ *   <cli-split storage-key="a"> <cli-msglist …/> <cli-chat …/> <cli-board …/> </cli-split>
+ *                                    （可拖动分栏：子元素每个是一栏，栏之间左右拖动改宽度；panes='[{"size":300},{},{"size":"42%"}]'）
+ *
+ * 同一个 group 的元素共享一个仓库，切换时一起变：列表点哪个，对话和看板就显示哪个；不写 group 各自独立。
+ * 要一起切换，group 里的元素就不要写 job-id（写了的只看自己那个）；从外面打开某个对话，给任意一个元素写
+ * selected-id="job_x" 或 "job_x#task_y"（改它就一起切过去），选中变化在 cli-event 的 select 事件里。
+ * 属性：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, CliChat, CliBoard } from "./components";
+import type { BoardTab } from "./board/CliBoard";
+import { CliBrowserView, CliFilePreview } from "./board/blocks";
+import { createCliStore, cloneWorkspaceEvent, type CliEvent, type CliStore } from "./core/store";
+import { convKey } from "./core/conversation";
+import type { CliWorkspace } from "./board/workspace";
+import { attachSplit, type SplitHandle } from "./layout/split";
+
+type StoreOptions = ReturnType<typeof storeOptions>;
+type GroupMember = { el: HTMLElement; refresh: () => void };
+type StoreBucket = { store: CliStore; options: StoreOptions; members: Set<GroupMember> };
+type StoreGroup = { buckets: Map<string, StoreBucket>; preferred: StoreBucket | null; owner: GroupMember | null; configured: boolean; members: Set<GroupMember> };
+type GroupBinding = { groupName: string; group: StoreGroup; bucket: StoreBucket };
+const groups = new Map<string, StoreGroup>();
+const STORE_ATTRS = ["base-url", "token", "line", "namespace", "new-conversation"] as const;
+const identity = (options: StoreOptions) => JSON.stringify(options);
+const configured = (el: HTMLElement) => STORE_ATTRS.some(name => el.hasAttribute(name));
+
+const memberships = new WeakMap<GroupMember, { groupName: string; group: StoreGroup }>();
+function notifyGroup(group: StoreGroup, except?: GroupMember) {
+  const peers = [...group.members];
+  queueMicrotask(() => { for (const peer of peers) if (peer !== except) peer.refresh(); });
+}
+function leaveGroup(member: GroupMember) {
+  const membership = memberships.get(member);
+  if (!membership) return;
+  const { groupName, group } = membership;
+  group.members.delete(member);
+  for (const [key, bucket] of group.buckets) {
+    bucket.members.delete(member);
+    if (!bucket.members.size && bucket !== group.preferred) group.buckets.delete(key);
+  }
+  if (group.owner === member) group.owner = null;
+  memberships.delete(member);
+  if (!group.members.size) groups.delete(groupName); else notifyGroup(group);
+}
+function releaseGroup(binding: GroupBinding, member: GroupMember, retainOwner = false) {
+  const { group, bucket } = binding;
+  bucket.members.delete(member);
+  if (!retainOwner && group.owner === member) group.owner = null;
+  if (!bucket.members.size && bucket !== group.preferred) group.buckets.delete(identity(bucket.options));
+  notifyGroup(group, member);
+}
+
+function inheritedOptions(el: HTMLElement, base: StoreOptions | null): StoreOptions {
+  if (!base) return storeOptions(el);
+  return {
+    baseUrl: el.hasAttribute("base-url") ? el.getAttribute("base-url")! : base.baseUrl,
+    token: el.hasAttribute("token") ? el.getAttribute("token")! : base.token,
+    line: el.hasAttribute("line") ? el.getAttribute("line")! : base.line,
+    namespace: el.hasAttribute("namespace") ? el.getAttribute("namespace")! : base.namespace,
+    newConversation: el.hasAttribute("new-conversation") ? jsonAttr(el, "new-conversation") : base.newConversation,
+  };
+}
+
+// 服务端渲染（Next.js 等）时没有 HTMLElement：模块照样能导入，defineCliElements() 在服务端什么都不做。
+const Base = (typeof HTMLElement === "undefined" ? class {} : HTMLElement) as typeof HTMLElement;
+
+function storeFor(el: HTMLElement, member: GroupMember, previous?: GroupBinding): GroupBinding | undefined {
+  const groupName = el.getAttribute("group");
+  if (!groupName) { leaveGroup(member); return undefined; }
+  if (memberships.get(member)?.groupName !== groupName) leaveGroup(member);
+  let group = groups.get(groupName);
+  if (!group) {
+    group = { buckets: new Map(), preferred: null, owner: null, configured: false, members: new Set() };
+    groups.set(groupName, group);
+  }
+  group.members.add(member);
+  memberships.set(member, { groupName, group });
+  const ownsDefaults = group.owner === member || (!group.configured && configured(el));
+  const matches = [...group.buckets.values()].filter(item => [...item.members].some(peer => configured(peer.el))).filter(item => {
+    const values = storeOptions(el);
+    return STORE_ATTRS.every(name => {
+      if (!el.hasAttribute(name)) return true;
+      const key = ({ "base-url": "baseUrl", token: "token", line: "line", namespace: "namespace", "new-conversation": "newConversation" } as const)[name as typeof STORE_ATTRS[number]];
+      return JSON.stringify(values[key as keyof StoreOptions]) === JSON.stringify(item.options[key as keyof StoreOptions]);
+    });
+  });
+  if (!ownsDefaults && matches.length > 1) throw new Error("同一 group 有多个连接配置，请明确设置 base-url、token、line 或 namespace，避免混用会话。");
+  const options = inheritedOptions(el, ownsDefaults ? null : matches[0]?.options ?? group.preferred?.options ?? null);
+  const key = identity(options);
+  let bucket = group.buckets.get(key);
+  const newBucket = !bucket;
+  if (!bucket) {
+    bucket = { store: createCliStore(options), options, members: new Set() };
+    group.buckets.set(key, bucket);
+  }
+  bucket.members.add(member);
+  if (newBucket) notifyGroup(group, member);
+  if (!group.preferred || ownsDefaults) {
+    const changed = group.preferred !== bucket;
+    group.preferred = bucket;
+    if (ownsDefaults) { group.configured = true; group.owner = member; }
+    if (changed) {
+      // Config may arrive after a sibling with only group was connected. Move
+      // inheriting siblings together; explicitly different credentials remain isolated.
+      notifyGroup(group, member);
+    }
+  }
+  const binding = { groupName, group, bucket };
+  if (previous && (previous.group !== group || previous.bucket !== bucket)) releaseGroup(previous, member, previous.group === group);
+  return binding;
+}
+
+const ATTRS = ["base-url", "token", "line", "namespace", "group", "selected-id", "job-id", "task-id", "title", "color", "theme", "context", "read-only", "config", "new-conversation", "tabs", "available-tabs", "default-tab", "file-open", "path", "no-quote", "hidden", "watch-files", "passive-context"];
+
+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 Base {
+  static observedAttributes = ATTRS;
+  private root: Root | null = null;
+  private ownStore: CliStore | undefined;
+  private ownStoreKey: string | undefined;
+  private groupBinding: GroupBinding | undefined;
+  private groupMember: GroupMember = { el: this, refresh: () => { if (this.root) this.render(); } };
+  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();
+  }
+
+  /** 这个元素用的仓库（同一个 group 的元素共用一个）。高级用法：store.on(...)、store.select(...)。 */
+  get store(): CliStore {
+    const binding = storeFor(this, this.groupMember, this.groupBinding);
+    if (binding) { this.groupBinding = binding; return binding.bucket.store; }
+    if (this.groupBinding) { releaseGroup(this.groupBinding, this.groupMember); this.groupBinding = undefined; }
+    const options = storeOptions(this), key = identity(options);
+    if (!this.ownStore || this.ownStoreKey !== key) { this.ownStore = createCliStore(options); this.ownStoreKey = key; }
+    return this.ownStore;
+  }
+  /** 元素自己写的对话（job-id + task-id）；没写时 null（跟着这一组的选中走）。 */
+  private ownKey(): string | null {
+    const job = this.getAttribute("job-id");
+    if (!job) return null;
+    const task = this.getAttribute("task-id");
+    return task ? convKey(job, task) : job;
+  }
+  /**
+   * 工作区文件接口：列文件、读文件、下载、打包、当前打开的文件。不传 jobId = 这个元素看的对话（没写 job-id 时是这一组选中的）。
+   * 看板可以隐藏（<cli-board hidden>）或者干脆不放，接口照样能用。
+   */
+  workspace(jobId?: string): CliWorkspace {
+    return this.store.workspace(jobId ?? this.ownKey() ?? undefined);
+  }
+  /**
+   * 追加项目背景：下一条消息发出时一起带给智能体。opts.jobId 不传 = 这个元素看的对话（还没有对话时，随新对话的第一条消息带上）。
+   * 返回这条背景的 id（同一个 id 再追加会替换）。
+   */
+  appendContext(text: string, opts: { title?: string; id?: string; jobId?: string } = {}): string {
+    const key = opts.jobId ?? this.ownKey() ?? this.store.getState().selected;
+    return this.store.appendContext(key, text, { title: opts.title, id: opts.id });
+  }
+  /** 去掉还没发出的补充背景（不传 id = 全部）。 */
+  removeContext(id?: string, jobId?: string) {
+    this.store.removeContext(jobId ?? this.ownKey() ?? this.store.getState().selected, id);
+  }
+
+  connectedCallback() {
+    // 缺省撑满父容器；组件自己内部滚动（宿主给定高度即可）。hidden：不显示、不连接（接口照样能用）。
+    this.syncHidden();
+    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;
+      leaveGroup(this.groupMember); this.groupBinding = undefined;
+      this.ownStore = undefined; this.ownStoreKey = undefined;
+      this.appliedSelection = null; this.selectionStore = null;
+    } });
+  }
+  attributeChangedCallback() { this.syncHidden(); if (this.root) this.render(); }
+  private syncHidden() {
+    if (this.hasAttribute("hidden")) this.style.display = "none";
+    else if (!this.style.display || this.style.display === "none") this.style.display = "block";
+  }
+
+  private appliedSelection: string | null = null;
+  private selectionStore: CliStore | null = null;
+  /** selected-id：这一组一起看哪个对话。属性变了才切（列表点击换了选中，不会被属性拉回去）。隐藏的元素也生效。 */
+  private applySelection() {
+    const selection = this.getAttribute("selected-id");
+    const store = this.store;
+    if (selection !== null && (selection !== this.appliedSelection || store !== this.selectionStore)) {
+      this.appliedSelection = selection;
+      this.selectionStore = store;
+      store.select(selection || null);
+    }
+  }
+  protected common() {
+    const store = this.store;
+    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: cloneWorkspaceEvent(event as CliEvent), bubbles: true }));
+        const type=(event as {type?:string}).type;
+        const name=type==='files_changed'?'cli-files-change':type==='files_watch'?'cli-files-watch':type==='board_context'?'cli-board-context':null;
+        if(name)this.dispatchEvent(new CustomEvent(name,{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;
+  // 隐藏的元素什么都不渲染：不轮询、不占连接；workspace() / appendContext() 照样能用。
+  private render() {
+    try {
+      this.applySelection();
+      this.root?.render(this.hasAttribute("hidden") ? null : this.element());
+    } catch (error) {
+      // Configuration errors must unmount the previous connection, never leave
+      // another account's old interface interactive under new attributes.
+      this.root?.render(this.hasAttribute("hidden") ? null : <div className="cli-ui cli-error" role="alert">{error instanceof Error ? error.message : "组件连接配置无效"}</div>);
+    }
+  }
+}
+
+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 } : {})} passiveContext={this.getAttribute("passive-context")!=="false"} 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 availableTabs = this.getAttribute("available-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={this.hasAttribute("tabs") ? tabs ?? [] : undefined} availableTabs={availableTabs} defaultTab={defaultTab} readOnly={this.hasAttribute("read-only")}
+      // 同一个 group 里有对话：看板里「引用到对话」带进那个对话的下一条消息；no-quote 关掉。
+      watchFiles={this.getAttribute("watch-files")!=="false"}
+      quoteToChat={this.hasAttribute("group") && !this.hasAttribute("no-quote")} />;
+  }
+}
+
+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")} />;
+  }
+}
+
+/** <cli-split>：可拖动分栏（规则见 layout/split.ts）。属性 panes（JSON，每栏 size / min / max）、storage-key（记住宽度）。 */
+class CliSplitElement extends Base {
+  static observedAttributes = ["panes", "storage-key"];
+  private handle: SplitHandle | null = null;
+  private options() {
+    let panes: unknown;
+    try { panes = JSON.parse(this.getAttribute("panes") ?? "null"); } catch { panes = null; }
+    return {
+      ...(Array.isArray(panes) ? { panes } : {}),
+      storageKey: this.getAttribute("storage-key") ?? undefined,
+      onResize: (sizes: (number | null)[]) => this.dispatchEvent(new CustomEvent("cli-resize", { detail: { sizes } })),
+    };
+  }
+  connectedCallback() {
+    this.style.height ||= "100%";
+    this.handle ??= attachSplit(this, this.options());
+  }
+  disconnectedCallback() {
+    queueMicrotask(() => { if (!this.isConnected) { this.handle?.destroy(); this.handle = null; } });
+  }
+  attributeChangedCallback() { this.handle?.update(this.options()); }
+}
+
+export function defineCliElements() {
+  if (typeof customElements === "undefined") return;
+  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);
+  if (!customElements.get("cli-split")) customElements.define("cli-split", CliSplitElement);
+}
+
+/** 元素上给业务方用的方法（<cli-msglist> / <cli-chat> / <cli-board> / <cli-file-preview> / <cli-browser> 都有）。 */
+export interface CliElementApi extends HTMLElement {
+  readonly store: CliStore;
+  config: object | undefined;
+  workspace(jobId?: string): CliWorkspace;
+  appendContext(text: string, opts?: { title?: string; id?: string; jobId?: string }): string;
+  removeContext(id?: string, jobId?: string): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "cli-msglist": CliElementApi;
+    "cli-chat": CliElementApi;
+    "cli-board": CliElementApi;
+    "cli-file-preview": CliElementApi;
+    "cli-browser": CliElementApi;
+  }
+}

package/src/embed.ts

@@ -0,0 +1,56 @@
+/**
+ * 给第三方页面用的一体化入口：引入一个 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 @xgspz/cli-ui` 生成在 dist/。
+ */
+import "./styles.css";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { defineCliElements } from "./elements";
+import { CliChat, CliMsgList, CliBoard, type CliChatProps, type CliMsgListProps, type CliBoardProps } from "./components";
+import { CliBrowserView, CliFilePreview, type CliBrowserViewProps, type CliFilePreviewProps } from "./board/blocks";
+import { CliCenterProvider } from "./core/provider";
+import { createCliStore } from "./core/store";
+import { createCenterClient } from "./core/client";
+
+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,56 @@
+export { CliMsgList, CliChat, CliBoard, type CliMsgListProps, type CliChatProps, type CliBoardProps } from "./components";
+export type { GroupChatAdapter, GroupChatMessage, GroupChatReference } from "./chat/GroupChat";
+/**
+ * @xgspz/cli-ui —— 任务中心（cli-task-center）对话任务的前端积木，数据全部来自 center 服务。
+ *
+ *   cli-msglist  消息对话列表（CliMsgList）
+ *   cli-chat     对话（CliChat）
+ *   cli-board    右侧看板：工作区文件（预览 / 下载）、改动、任务浏览器（CliBoard）
+ *                 其中两个核心也能单独用：CliFilePreview（文件预览 + 下载）、CliBrowserView（浏览器实时画面）
+ *   CliSplit     可拖动分栏：把上面几个横着排，栏之间左右拖动改宽度（Web Component：<cli-split>）
+ *
+ * 单独用：
+ *   <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 "@xgspz/cli-ui/styles.css";
+ * 非 React 页面用 Web Component：import { defineCliElements } from "@xgspz/cli-ui/elements"。
+ */
+export { type BoardTab, type BoardExtraTab } from "./board/CliBoard";
+export { downloadFolder, zipFolder, listFolder, FOLDER_MAX_FILES, FOLDER_MAX_BYTES, type FolderResult, type FolderZip, type FolderProgress } from "./board/folderDownload";
+export { createWorkspace, WORKSPACE_TEXT_MAX, WORKSPACE_LIST_MAX, WORKSPACE_FILE_MAX, type CliWorkspace, type BoardView } from "./board/workspace";
+export { CliFilePreview, CliBrowserView, type CliFilePreviewProps, type CliBrowserViewProps } from "./board/blocks";
+export { FileViewer, downloadFile, type FileViewerProps, type FileAction } from "./board/FileViewer";
+export { BrowserPane } from "./board/BrowserPane";
+export { CliSplit, type CliSplitProps } from "./layout/CliSplit";
+export { attachSplit, type SplitPane, type SplitOptions, type SplitHandle } from "./layout/split";
+export { CliCenterProvider, useCliStore, useCliState, type CliCenterProviderProps, type ResultHandlers } from "./core/provider";
+
+export {
+  resolveChatConfig, resolveMsgListConfig, DEFAULT_CHAT_CONFIG, DEFAULT_MSGLIST_CONFIG,
+  type CliChatConfig, type CliMsgListConfig, type ResolvedChatConfig, type ResolvedMsgListConfig,
+} from "./core/config";
+export { createCliStore, CONTEXT_ITEM_MAX, type CliStore, type CliStoreOptions, type CliState, type CliEvent, type JobEntry, type OpenTarget, type BoardRef, type ContextItem } from "./core/store";
+export { createCenterClient, CenterError, boardFileUrl, type CenterClient, type CenterClientOptions, type StreamHandlers, type BoardBackend, type ConversationBackend } from "./core/client";
+export { viewMessages, isRunning, runningTurn, convKey, parseConvKey, NEW_TASK, type ConvState } from "./core/conversation";
+export {
+  composeMessage, splitMessage, serializeBlock, readFileText, isLongText, ACCEPTED_EXTENSIONS, MAX_MESSAGE_CHARS,
+  type TextBlock, type MessagePart,
+} from "./core/blocks";
+export type * from "./core/types";
+export type { ExecutionOptions, ExecutionConfiguration } from "./core/execution";
+
+
+export { RunControls, type RunControlProps, type RunCapabilities, type RunTask } from "./chat/RunControls";
+
+export { formatBoardContext, appendBoardContext, BOARD_HISTORY_MAX } from "./board/context";
+export { subscribeWorkspaceFiles, type WorkspaceWatchOptions } from "./board/fileWatch";
+export type { WorkspaceHandlers } from "./core/provider";
+export type { BoardFile } from "./board/workspace";
+
+export { syncFile, clearFileSyncNamespace, FILE_SYNC_MAX, type FileSyncTransport, type FileSyncManifest, type FileSyncProgress } from "./board/fileSync";