@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/core/documentUpload.ts

@@ -0,0 +1,196 @@
+import { createFileWorkQueue } from "../board/fileSyncQueue";
+/** Original attachments. The message contains an authorized reference only. */
+export const DOCUMENT_MAX_BYTES = 100 * 1024 * 1024;
+export const UPLOAD_OTHER_MAX_BYTES = 10 * 1024 * 1024;
+export const DOCUMENT_CHUNK_BYTES = 1024 * 1024;
+export const isOriginalDocument = (name: string) => /\.(html?|md|markdown)$/i.test(name);
+export const isTaskUploadPath = (path: string) => /\/(?:uploads|attachments)\/[^/]+\/[^/]+$/.test(path.replace(/\\/g, "/"));
+const UPLOAD_TYPES: Record<string, string> = {
+  html: "text/html", htm: "text/html", md: "text/markdown", markdown: "text/markdown",
+  txt: "text/plain", log: "text/plain", yaml: "text/yaml", yml: "text/yaml", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+  js: "text/plain", jsx: "text/plain", mjs: "text/plain", cjs: "text/plain", ts: "text/plain", tsx: "text/plain", mts: "text/plain", cts: "text/plain", py: "text/plain", sh: "text/plain", css: "text/plain", mjsx: "text/plain", cjsx: "text/plain", mtsx: "text/plain", ctsx: "text/plain",
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", xlsm: "application/vnd.ms-excel.sheet.macroEnabled.12",
+};
+export const FILE_UPLOAD_ACCEPT = Object.keys(UPLOAD_TYPES).map(extension => `.${extension}`).join(",");
+export const uploadFileType = (name: string) => {
+  const dot = name.lastIndexOf(".");
+  const extension = dot > 0 ? name.slice(dot + 1).toLowerCase() : undefined;
+  return extension && Object.hasOwn(UPLOAD_TYPES, extension) ? UPLOAD_TYPES[extension] : undefined;
+};
+export type DocumentReceipt = { uploadId: string; draftId: string; name: string; size: number; sha256: string; path?: string; url?: string };
+export type UploadPhase = "queued" | "checking" | "uploading" | "verifying";
+export type DocumentUploadOptions = { draftId: string; signal?: AbortSignal; onBytes?: (bytes: number) => void; onPhase?: (phase: UploadPhase) => void };
+export type UploadDocument = (file: File, options: DocumentUploadOptions) => Promise<DocumentReceipt>;
+const aborted = () => new DOMException("上传已取消", "AbortError");
+function pause(ms: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) return reject(aborted());
+    const stop = () => { clearTimeout(timer); reject(aborted()); };
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", stop); resolve(); }, ms);
+    signal?.addEventListener("abort", stop, { once: true });
+  });
+}
+
+/** Blob cloning is cheap; hashing a 100 MiB file does not copy it through the UI thread. */
+export async function hashDocument(file: Blob, signal?: AbortSignal): Promise<string> {
+  if (signal?.aborted) throw aborted();
+  if (typeof Worker !== "undefined" && typeof URL.createObjectURL === "function") {
+    const source = `onmessage=async e=>{try{const bytes=await e.data.arrayBuffer();const hash=await crypto.subtle.digest('SHA-256',bytes);postMessage({hash:Array.from(new Uint8Array(hash),b=>b.toString(16).padStart(2,'0')).join('')});}catch(e){postMessage({error:String(e)})}}`;
+    const url = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+    let worker: Worker | undefined;
+    try {
+      worker = new Worker(url);
+      return await new Promise<string>((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", stop); worker!.onmessage = null; worker!.onerror = null; };
+        const stop = () => { cleanup(); reject(aborted()); };
+        const timer = setTimeout(() => { cleanup(); reject(Object.assign(new Error("文件校验超时，请重试"), { status: 408, code: "hash_timeout" })); }, 120_000);
+        signal?.addEventListener("abort", stop, { once: true });
+        worker!.onmessage = e => { cleanup(); e.data?.hash ? resolve(e.data.hash) : reject(new Error(e.data?.error || "文件校验失败，请重试")); };
+        worker!.onerror = () => { cleanup(); reject(new Error("文件校验失败，请重试")); };
+        if (signal?.aborted) { stop(); return; }
+        try { worker!.postMessage(file); } catch (error) { cleanup(); reject(error); }
+      });
+    } finally { worker?.terminate(); URL.revokeObjectURL(url); }
+  }
+  const digest = await crypto.subtle.digest("SHA-256", await file.arrayBuffer());
+  if (signal?.aborted) throw aborted();
+  return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** All calls are bounded short requests, including body reads. */
+export async function documentRequest<T>(fetcher: typeof fetch, url: string, init: RequestInit = {}, headers: () => Record<string, string> = () => ({})): Promise<T> {
+  const ctl = new AbortController();
+  const signal = init.signal;
+  const cancel = () => ctl.abort();
+  if (signal?.aborted) throw aborted();
+  signal?.addEventListener("abort", cancel, { once: true });
+  const timer = setTimeout(cancel, 30_000);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let rejectAbort: (() => void) | undefined;
+  try {
+    const cancelled = new Promise<never>((_resolve, reject) => { rejectAbort = () => reject(aborted()); ctl.signal.addEventListener("abort", rejectAbort, { once: true }); });
+    return await Promise.race([cancelled, (async () => {
+    const response = await fetcher(url, { ...init, cache: "no-store", signal: ctl.signal, headers: { ...headers(), ...init.headers } });
+    if (ctl.signal.aborted) { void response.body?.cancel().catch(() => undefined); throw aborted(); }
+    reader = response.body?.getReader();
+    let raw = "", bytes = 0;
+    if (reader) {
+      const decoder = new TextDecoder();
+      for (;;) {
+        const part = await reader.read(); if (part.done) break;
+        bytes += part.value.byteLength;
+        if (bytes > 2 * 1024 * 1024) throw Object.assign(new Error("文件响应超过协议上限"), { status: 502, code: "response_too_large" });
+        raw += decoder.decode(part.value, { stream: true });
+      }
+      raw += decoder.decode();
+    } else raw = await response.text();
+    let value: Record<string, unknown>;
+    try { value = raw ? JSON.parse(raw) : {}; } catch { throw Object.assign(new Error("文件接口返回的数据无效"), { status: 502, code: "invalid_response" }); }
+    const retryHeader = response.headers.get("retry-after");
+    const retryHint = retryHeader ? (/^\d+(\.\d+)?$/.test(retryHeader) ? Number(retryHeader) * 1000 : Date.parse(retryHeader) - Date.now()) : undefined;
+    const retryAfterMs = retryHint !== undefined && Number.isFinite(retryHint) ? Math.max(0, retryHint) : undefined;
+    if (response.status === 202) throw Object.assign(new Error("文件正在校验"), { status: 202, retryAfterMs: retryAfterMs ?? 1000 });
+    if (!response.ok) {
+      const missing = value.error === "file_not_found" ? "文件不存在（可能已被删除或改名）" : "服务端尚未支持原件上传或增量文件同步，请升级节点和中枢";
+      const common: Record<string, string> = { file_sync_busy: "文件服务繁忙，请稍后重试", too_many_snapshot_builds: "文件服务繁忙，请稍后重试", too_many_uploads: "上传任务较多，请稍后重试", file_sync_queue_timeout: "文件处理排队超时，请稍后重试", file_sync_timeout: "文件服务响应超时，请重试", snapshot_cache_full: "文件缓存空间不足，请稍后重试", upload_storage_full: "文件上传空间不足，请稍后重试" };
+      const error = new Error(common[String(value.error)] ?? String(value.detail || (response.status === 404 ? missing : value.error) || `文件请求失败（HTTP ${response.status}）`));
+      Object.assign(error, { status: response.status, code: value.error, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
+      throw error;
+    }
+    return value as T;
+    })()]);
+  } catch (error) {
+    if (signal?.aborted) throw aborted();
+    if (ctl.signal.aborted) throw Object.assign(new Error("文件请求超时，请重试"), { status: 0, code: "timeout" });
+    throw error;
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", cancel); if (rejectAbort) ctl.signal.removeEventListener("abort", rejectAbort); ctl.abort(); void reader?.cancel().catch(() => undefined); }
+}
+
+const uploadQueues = new WeakMap<typeof fetch, ReturnType<typeof createFileWorkQueue>>();
+async function retryUploadRequest<T>(work: () => Promise<T>, signal: AbortSignal | undefined, busyOnly = false, deadline = Date.now() + 180_000): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw aborted();
+    try { return await work(); } catch (error) {
+      const failure = error as { status?: number; code?: string; name?: string; retryAfterMs?: number };
+      const status = failure.status ?? 0;
+      const retryable = busyOnly ? status === 429 : !status || [408, 429, 500, 502, 503, 504].includes(status);
+      if (signal?.aborted || failure.name === "AbortError" || !retryable || attempt >= 3 || ["invalid_response", "response_too_large", "integrity", "client_queue_full"].includes(failure.code ?? "")) throw error;
+      const base = 500 * 2 ** attempt, hint = Number(failure.retryAfterMs ?? 0);
+      const delay = Math.max(base, Number.isFinite(hint) ? hint : 0) + Math.floor(Math.random() * base / 4);
+      if (delay > deadline - Date.now()) throw error;
+      await pause(delay, signal);
+    }
+  }
+}
+export function createDocumentUploader(fetcher: typeof fetch, base: string, headers: () => Record<string, string> = () => ({})): UploadDocument {
+  // Share hashing/upload slots across tasks using this client, with cancellable bounded waiters.
+  let queue = uploadQueues.get(fetcher);
+  if (!queue) { queue = createFileWorkQueue(1, 128); uploadQueues.set(fetcher, queue); }
+  return (file, options) => {
+    options.onPhase?.("queued");
+    const upload = async (): Promise<DocumentReceipt> => {
+      const { signal, onBytes, onPhase, draftId } = options;
+      if (signal?.aborted) throw aborted();
+      const type = uploadFileType(file.name);
+      if (!type) throw new Error("暂不支持此文件类型，请选择文档、图片或文本文件");
+      const maxBytes = isOriginalDocument(file.name) ? DOCUMENT_MAX_BYTES : UPLOAD_OTHER_MAX_BYTES;
+      if (file.size > maxBytes) throw new Error(`“${file.name}”超过 ${isOriginalDocument(file.name) ? "100" : "10"} MiB，请缩小后重试。`);
+      if (new TextEncoder().encode(file.name).length > 240) throw new Error("文件名超过 240 个 UTF-8 字节，请缩短文件名后重试。");
+      onPhase?.("checking");
+      const sha256 = await hashDocument(file, signal);
+      const request = <T>(path: string, init: RequestInit) => documentRequest<T>(fetcher, `${base}${path}`, { ...init, signal }, headers);
+      const session = await retryUploadRequest(() => request<{ uploadId: string; chunkBytes: number }>("/uploads", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ draftId, name: file.name, size: file.size, type, sha256 }) }), signal, true);
+      if (!session.uploadId || session.chunkBytes !== DOCUMENT_CHUNK_BYTES) throw new Error("上传协议不匹配，请升级服务端");
+      const root = `/uploads/${encodeURIComponent(session.uploadId)}`;
+      try {
+        onPhase?.("uploading");
+        onBytes?.(0);
+        for (let start = 0, index = 0; start < file.size; start += session.chunkBytes, index++) {
+          const body = file.slice(start, Math.min(file.size, start + session.chunkBytes));
+          // Only these numbered chunks are safely idempotent after ambiguous network failures.
+          await retryUploadRequest(() => request(`${root}/chunks/${index}`, { method: "PUT", headers: { "Content-Type": "application/octet-stream" }, body }), signal);
+          onBytes?.(Math.min(file.size, start + session.chunkBytes));
+        }
+        onPhase?.("verifying");
+        const deadline = Date.now() + 180_000;
+        for (;;) {
+          try {
+            const result = await retryUploadRequest(() => request<DocumentReceipt>(`${root}/complete`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ draftId }) }), signal, false, deadline);
+            if (result.sha256 !== sha256) throw new Error("上传文件校验不一致，请重试");
+            return { ...result, draftId, name: file.name, size: file.size };
+          } catch (error) {
+            const pending = error as { status?: number; retryAfterMs?: number };
+            if (pending.status !== 202 || Date.now() >= deadline) throw error;
+            const delay = Math.max(100, pending.retryAfterMs ?? 1000);
+            if (delay > deadline - Date.now()) throw error;
+            await pause(delay, signal);
+          }
+        }
+      } catch (error) {
+        void documentRequest(fetcher, `${base}${root}`, { method: "DELETE" }, headers).catch(() => undefined);
+        throw error;
+      }
+    };
+    return queue.run(upload, options.signal);
+  };
+}
+
+export function documentMarker(receipt: DocumentReceipt) {
+  if (receipt.path) {
+    if (/[\r\n\]]/.test(receipt.path)) throw new Error("上传文件路径无效，请重试");
+    return `[Attached ${uploadFileType(receipt.name)?.startsWith("image/") ? "image" : "file"}: ${receipt.path}]`;
+  }
+  const name = receipt.name.replace(/[\r\n\[\]]/g, " ");
+  return `[文件原件：${name}](cli-upload://${encodeURIComponent(receipt.draftId)}/${encodeURIComponent(receipt.uploadId)})`;
+}
+
+export function extractDocumentReferences(text: string) {
+  const attachments: Array<{ uploadId: string; draftId: string }> = [];
+  const clean = text.replace(/\[文件原件：([^\]\r\n]*)\]\(cli-upload:\/\/([^/\s)]+)\/([^\s)]+)\)/g, (_match, name, draft, upload) => {
+    try { attachments.push({ draftId: decodeURIComponent(draft), uploadId: decodeURIComponent(upload) }); } catch { throw new Error("文件引用无效，请移除后重新上传"); }
+    return `[文件原件：${name}]`;
+  });
+  return { text: clean, ...(attachments.length ? { attachments } : {}) };
+}

package/src/core/execution.ts

@@ -0,0 +1,24 @@
+import type { RunCapabilities } from "../chat/RunControls";
+
+/** 用户选择的下一轮执行设置；不包含账号或凭据。null 表示使用服务端默认值。 */
+export interface ExecutionOptions {
+  agent?: string;
+  model?: string | null;
+  reasoning?: string | null;
+  permission_mode?: string | null;
+}
+
+export interface ExecutionConfiguration {
+  revision: number;
+  agent: string;
+  model: string | null;
+  reasoning: string | null;
+  permission_mode: string | null;
+  agents: Array<{
+    id: string;
+    label: string;
+    disabled?: boolean;
+    capabilities: RunCapabilities;
+    defaults?: Omit<ExecutionOptions, "agent">;
+  }>;
+}

package/src/core/id.ts

@@ -0,0 +1,15 @@
+/** Correlation/draft IDs only: never use this fallback as a credential or token. */
+let sequence = 0;
+export function clientId(): string {
+  try { if (typeof globalThis.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID(); } catch { /* Fall back in restricted or insecure contexts. */ }
+  try {
+    if (typeof globalThis.crypto?.getRandomValues === 'function') {
+      const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+      bytes[6] = (bytes[6] & 0x0f) | 0x40;
+      bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      const hex = Array.from(bytes, value => value.toString(16).padStart(2, '0')).join('');
+      return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`;
+    }
+  } catch { /* Drafts still work when Web Crypto is unavailable. */ }
+  return `${Date.now().toString(36)}-${(++sequence).toString(36)}-${Math.random().toString(36).slice(2,10)}`;
+}

package/src/core/identity.ts

@@ -0,0 +1,21 @@
+import type { CenterClientOptions } from './client';
+import { clientId } from './id';
+import { sha256 } from './sha256';
+// A synchronous SHA-256 fingerprint partitions persistent drafts without putting
+// credentials in localStorage keys. It is never used for authentication.
+export function connectionFingerprint(text:string):string {
+ return sha256(new TextEncoder().encode(text));
+}
+const customScopes=new WeakMap<object,string>();
+export function connectionDraftScope(options:CenterClientOptions&{namespace?:string|null;client?:object}):string {
+ // Custom transports may hide cookies or credentials. Isolate by object identity
+ // rather than pretending their URL proves the account identity.
+ const headers = options.headers?.() ?? {};
+ const signature=JSON.stringify([options.baseUrl?.replace(/\/+$/,'')??'',options.token??'',options.line??'',options.namespace??'',Object.keys(headers).sort().map(key=>[key,headers[key]])]);
+ const transport=options.client;
+ if(transport){let scope=customScopes.get(transport);if(!scope){scope=clientId();customScopes.set(transport,scope);}return `custom-${scope}:${connectionFingerprint(signature)}`;}
+ // Preserve the historical default same-origin draft keys. Cookie-auth hosts
+ // must supply an account-specific namespace and remount after account changes.
+ if(!options.baseUrl&&!options.token&&!options.line&&!options.namespace&&!Object.keys(headers).length)return '';
+ return connectionFingerprint(signature);
+}

package/src/core/provider.tsx

@@ -0,0 +1,141 @@
+import { notifyCallback } from "./callbacks";
+import { Fragment, createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore, type ReactNode } from "react";
+import { connectionDraftScope } from "./identity";
+import { createCliStore, cloneWorkspaceEvent, type CliEvent, type CliState, type CliStore, type CliStoreOptions } from "./store";
+import type { ConversationCallback, ConversationEndPayload, TurnEndPayload } from "./types";
+
+/**
+ * 积木的拼接点。放在同一个 <CliCenterProvider> 里的组件共享一个仓库，切换时一起变：
+ * 列表点哪个对话，对话和看板就显示哪个；对话里新建 / 接续出新对话，列表跟着选中、看板跟着切；
+ * 对话里点文件在看板里打开。同一个对话只连一条实时流。
+ *
+ *   <CliCenterProvider baseUrl="/api/center" selectedId={key} onEvent={(e) => e.type === "select" && setKey(e.jobId)}>
+ *     <CliMsgList />
+ *     <CliChat />
+ *     <CliBoard />
+ *   </CliCenterProvider>
+ *
+ * 要一起切换，里面的组件就不要再传 jobId（传了的组件只看自己那个，不跟着切）；从外面打开某个对话用 selectedId。
+ *
+ * 组件单独使用时不需要它：组件发现外面没有 Provider，会用自己的 props 建一个。
+ */
+const StoreContext = createContext<CliStore | null>(null);
+
+export interface CliCenterProviderProps extends CliStoreOptions, ResultHandlers {
+  /** 外部建好的仓库（例如 Web Component 按 group 共享的）；给了就不再自己建。 */
+  store?: CliStore;
+  /**
+   * 里面这几个组件一起看哪个对话（对话键："job_x" 或 "job_x#task_y"；null = 新对话）。不给就由列表的点击决定。
+   * 给了之后改它，列表、对话、看板一起切过去；列表点击、对话里新建出的对话照样会切，并发 select / job_change 事件。
+   */
+  selectedId?: string | null;
+  /** 监听仓库事件：选中、一轮结束、对话结束、job 变化、错误。 */
+  onEvent?: (event: CliEvent) => void;
+  children: ReactNode;
+}
+
+/**
+ * 结果通知：组件从实时流里看到一轮结束 / 对话结束时调用，全在浏览器里发生，**和 center 的 callback.url 无关**——
+ * 不配 callback 也照样会调。载荷字段与 center 回调体一致，方便业务后端和前端用同一套代码解析。
+ */
+export interface WorkspaceHandlers {
+  onFilesChange?: (event: import("./types").WorkspaceChangeEvent) => void;
+  onFilesWatch?: (event: import("./types").WorkspaceWatchStatus) => void;
+  onBoardContextChange?: (event: Extract<CliEvent,{type:"board_context"}>) => void;
+}
+export interface ResultHandlers extends WorkspaceHandlers {
+  /** 一轮结束（成功 / 失败 / 取消）。 */
+  onTurnEnd?: (payload: TurnEndPayload) => void;
+  /** 对话结束（关闭 / 取消 / 过期……）。 */
+  onConversationEnd?: (payload: ConversationEndPayload) => void;
+  /** @deprecated 旧名字，等同于同时监听 onTurnEnd 和 onConversationEnd（payload.type 区分）。 */
+  onCallback?: (payload: ConversationCallback) => void;
+}
+
+export function dispatchResult(event: CliEvent, handlers: ResultHandlers) {
+  if (event.type === "conversation_turn") { notifyCallback(handlers.onTurnEnd, event.payload); notifyCallback(handlers.onCallback, event.payload); }
+  else if (event.type === "conversation_closed") { notifyCallback(handlers.onConversationEnd, event.payload); notifyCallback(handlers.onCallback, event.payload); }
+  else if(event.type === "files_changed") notifyCallback(handlers.onFilesChange,event);
+  else if(event.type === "files_watch") notifyCallback(handlers.onFilesWatch,event);
+  else if(event.type === "board_context") notifyCallback(handlers.onBoardContextChange,event);
+}
+
+export function CliCenterProvider({ store: external, selectedId, onEvent, onTurnEnd, onConversationEnd, onCallback, onFilesChange, onFilesWatch, onBoardContextChange, children, ...options }: CliCenterProviderProps) {
+  // 连接参数只在建仓库时用一次：中途换 baseUrl / token 请换 key 重建。
+  const optionsRef = useRef(options);
+  const applied = useRef<string | null | undefined>(undefined);
+  const store = useMemo(() => {
+    const created = external ?? createCliStore(optionsRef.current);
+    // 第一次渲染前就选好：里面的组件一上来就看这个对话，不会先打开别的。
+    if (selectedId !== undefined) { created.select(selectedId); applied.current = selectedId; }
+    return created;
+  }, [external]); // eslint-disable-line react-hooks/exhaustive-deps
+  // Creation defaults can arrive after a file/configuration load. Update only
+  // these defaults on commit; the connection and workspace state stay stable.
+  useLayoutEffect(() => {
+    optionsRef.current.newConversation = options.newConversation;
+    optionsRef.current.createConversation = options.createConversation;
+    optionsRef.current.businessIdFor = options.businessIdFor;
+  }, [options.newConversation, options.createConversation, options.businessIdFor]);
+  // 之后宿主改了 selectedId：一起切过去（在绘制前，免得闪一下旧的）。
+  useLayoutEffect(() => {
+    if (selectedId === undefined || selectedId === applied.current) return;
+    applied.current = selectedId;
+    store.select(selectedId);
+  }, [store, selectedId]);
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const resultRef = useRef<ResultHandlers>({});
+  resultRef.current = { onTurnEnd, onConversationEnd, onCallback, onFilesChange, onFilesWatch, onBoardContextChange };
+  useEffect(() => store.on((event) => {
+    notifyCallback(onEventRef.current, cloneWorkspaceEvent(event));
+    dispatchResult(event, resultRef.current);
+  }), [store]);
+  return <StoreContext.Provider value={store}><Fragment key={store.draftScope}>{children}</Fragment></StoreContext.Provider>;
+}
+
+export function useCliStoreContext(): CliStore | null {
+  return useContext(StoreContext);
+}
+
+export function useCliStore(): CliStore {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error("useCliStore 必须在 <CliCenterProvider> 内使用");
+  return store;
+}
+
+/** 订阅仓库状态的一部分。选择器返回的值按引用比较，状态是不可变的，所以返回子对象是安全的。 */
+export function useCliState<T>(selector: (state: CliState) => T): T {
+  const store = useCliStore();
+  return useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getState()));
+}
+
+/** 组件外面没有 Provider 时，用组件自己的 props 包一层。 */
+export function withOwnProvider<P extends object>(props: P & CliStoreOptions & ResultHandlers & { onEvent?: (event: CliEvent) => void; store?: CliStore }, inner: ReactNode, hasContext: boolean) {
+  if (hasContext) return inner;
+  const { baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onTurnEnd, onConversationEnd, onCallback, onFilesChange, onFilesWatch, onBoardContextChange, store } = props;
+  // 连接参数变了（换了中枢地址、令牌、产品线、命名空间）就换一个新仓库重连，不沿用旧连接。
+  const connection = connectionDraftScope({baseUrl,token,line,namespace,headers,fetch,client});
+  return (
+    <CliCenterProvider key={store ? "external" : connection} {...{ baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onTurnEnd, onConversationEnd, onCallback, onFilesChange, onFilesWatch, onBoardContextChange, store }}>
+      {inner}
+    </CliCenterProvider>
+  );
+}
+
+/**
+ * 组件自己的 onEvent / onTurnEnd / onConversationEnd：组件放在外层 Provider 里时由这里订阅
+ * （自己建 Provider 时交给那个 Provider，免得调两次）。
+ */
+export function useComponentEvents(onEvent: ((event: CliEvent) => void) | undefined, results: ResultHandlers, enabled: boolean) {
+  const store = useContext(StoreContext);
+  const ref = useRef({ onEvent, results });
+  ref.current = { onEvent, results };
+  useEffect(() => {
+    if (!enabled || !store) return;
+    return store.on((event) => {
+      notifyCallback(ref.current.onEvent, cloneWorkspaceEvent(event));
+      dispatchResult(event, ref.current.results);
+    });
+  }, [store, enabled]);
+}

package/src/core/sha256.ts

@@ -0,0 +1,21 @@
+/** Keep this byte-only fallback self-contained so file workers can use the same implementation. */
+export function sha256(bytes: Uint8Array): string {
+ const K = [0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2];
+ const rotate = (x:number,n:number)=>(x>>>n)|(x<<(32-n));
+ // Only the final one or two blocks need padding; do not copy an entire large file.
+ const blockBytes=bytes.length-bytes.length%64,tail=new Uint8Array(bytes.length%64<56?64:128);
+ tail.set(bytes.subarray(blockBytes));tail[bytes.length%64]=128;
+ const input=new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength),padding=new DataView(tail.buffer);
+ padding.setUint32(tail.length-8,Math.floor(bytes.length/0x20000000));padding.setUint32(tail.length-4,(bytes.length*8)>>>0);
+ const hash=[0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19],w=new Int32Array(64);
+ for(let offset=0;offset<blockBytes+tail.length;offset+=64){
+  const view=offset<blockBytes?input:padding,base=offset<blockBytes?offset:offset-blockBytes;
+  for(let i=0;i<16;i++)w[i]=view.getInt32(base+i*4);
+  for(let i=16;i<64;i++){const x=w[i-15],y=w[i-2];w[i]=(w[i-16]+(rotate(x,7)^rotate(x,18)^(x>>>3))+w[i-7]+(rotate(y,17)^rotate(y,19)^(y>>>10)))|0;}
+  let [a,b,c,d,e,f,g,h]=hash;
+  for(let i=0;i<64;i++){const t1=(h+(rotate(e,6)^rotate(e,11)^rotate(e,25))+((e&f)^(~e&g))+K[i]+w[i])|0,t2=((rotate(a,2)^rotate(a,13)^rotate(a,22))+((a&b)^(a&c)^(b&c)))|0;
+   h=g;g=f;f=e;e=(d+t1)|0;d=c;c=b;b=a;a=(t1+t2)|0;}
+  [a,b,c,d,e,f,g,h].forEach((value,i)=>{hash[i]=(hash[i]+value)|0;});
+ }
+ return hash.map(value=>(value>>>0).toString(16).padStart(8,'0')).join('');
+}

package/src/core/sse.ts

@@ -0,0 +1,51 @@
+/**
+ * 极简 SSE 解析器。用 fetch 读流而不是 EventSource：EventSource 不能带 Authorization 头，
+ * 而 center 的接口按产品线令牌鉴权（直连或经代理都可能需要带头）。
+ *
+ * 按 https://html.spec.whatwg.org/multipage/server-sent-events.html 的行规则：
+ * `event:` 设事件名，`data:` 累加数据，空行派发；以 `:` 开头的是注释（心跳 ping）。
+ */
+export interface SseMessage { event: string; data: string }
+
+export function createSseParser(onMessage: (message: SseMessage) => void) {
+  let buffer = "";
+  let event = "";
+  let data: string[] = [];
+
+  const dispatch = () => {
+    if (data.length) onMessage({ event: event || "message", data: data.join("\n") });
+    event = "";
+    data = [];
+  };
+
+  const line = (raw: string) => {
+    if (raw === "") return dispatch();
+    if (raw.startsWith(":")) return;
+    const colon = raw.indexOf(":");
+    const field = colon === -1 ? raw : raw.slice(0, colon);
+    let value = colon === -1 ? "" : raw.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  };
+
+  return {
+    push(chunk: string) {
+      buffer += chunk;
+      let index: number;
+      // 行尾可能是 \n、\r\n 或 \r。
+      while ((index = buffer.search(/\r\n|\r|\n/)) !== -1) {
+        const sep = buffer.startsWith("\r\n", index) ? 2 : 1;
+        // 只剩一个 \r 时等下一块：它可能是 \r\n 的前半。
+        if (buffer[index] === "\r" && sep === 1 && index === buffer.length - 1) break;
+        line(buffer.slice(0, index));
+        buffer = buffer.slice(index + sep);
+      }
+    },
+    end() {
+      if (buffer) line(buffer);
+      buffer = "";
+      dispatch();
+    },
+  };
+}