@spzxg/cli-ui 0.6.6 → 0.6.8

package/src/chat/useExecutionConfig.ts

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { CenterError, type ConversationBackend } from "../core/client";
+import type { ExecutionConfiguration, ExecutionOptions } from "../core/execution";
+import { isConfigurationBusy, useConfigurationBusy } from "./configuration";
+import { readComposerDraft, updateComposerDraft, useComposerDraft } from "./draft";
+
+const errorText = (error: unknown) => error instanceof CenterError && [404, 405, 501].includes(error.status)
+  ? "当前服务尚未支持执行设置，请升级配套服务。"
+  : error instanceof Error ? error.message : "执行设置读取失败，请重试。";
+
+function validate(result: ExecutionConfiguration) {
+  if (!result || typeof result.agent !== "string" || !Number.isSafeInteger(result.revision) || result.revision < 0 || !Array.isArray(result.agents)
+    || result.agents.some(agent => typeof agent?.id !== "string" || typeof agent.label !== "string" || !agent.capabilities
+      || [agent.capabilities.models, agent.capabilities.reasoningOptions, agent.capabilities.permissionModes].some(options => !Array.isArray(options)
+        || options.some(option => typeof option?.value !== "string" || typeof option.label !== "string")))) {
+    throw new Error("服务未返回有效的执行设置，请检查配套服务版本。");
+  }
+}
+
+/** 按对话隔离读取与保存，不轮询；换对话后的迟到响应不覆盖当前选择。 */
+export function useExecutionConfig({ client, scope, target, enabled, initial, running }: {
+  client: ConversationBackend; scope: string; target: string | null; enabled: boolean;
+  initial?: ExecutionOptions; running: boolean;
+}) {
+  const [view, setView] = useState<{ scope: string; config?: ExecutionConfiguration; error?: string; loading: boolean; saveFailed?: boolean }>({ scope, loading: false });
+  const current = useRef(scope);
+  const request = useRef(0);
+  const mounted = useRef(true);
+  useLayoutEffect(() => { current.current = scope; request.current++; }, [scope]);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; request.current++; }; }, []);
+  const draft = useComposerDraft(scope);
+  const busy = useConfigurationBusy(scope);
+  const config = view.scope === scope ? view.config : undefined;
+  const reload = useCallback(async () => {
+    const serial = ++request.current;
+    const active = () => mounted.current && current.current === scope && request.current === serial;
+    if (!enabled && !readComposerDraft(scope).executionUncertain) return;
+    if (!client.getExecutionConfig) {
+      setView({ scope, loading: false, error: "当前接入尚未提供执行设置。" });
+      return;
+    }
+    setView(value => ({ ...(value.scope === scope ? value : {}), scope, loading: true }));
+    try {
+      const result = await client.getExecutionConfig(target);
+      validate(result);
+      if (active()) {
+        if (!isConfigurationBusy(scope) && readComposerDraft(scope).executionUncertain) updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: false }));
+        setView({ scope, config: result, loading: false });
+      }
+    } catch (error) {
+      if (active()) setView(value => ({ ...(value.scope === scope ? value : {}), scope, error: errorText(error), loading: false }));
+    }
+  }, [client, scope, target, enabled]);
+  useEffect(() => { void reload(); return () => { request.current++; }; }, [reload]);
+  const wasRunning = useRef(running);
+  useEffect(() => {
+    if (wasRunning.current && !running && !isConfigurationBusy(scope)) void reload();
+    wasRunning.current = running;
+  }, [running, reload, scope]);
+
+  const local = target === null ? { ...initial, ...draft.executionConfig } : undefined;
+  const selected = config ? { ...config, ...local } : undefined;
+  const save = async (changes: ExecutionOptions) => {
+    if (!config || !enabled || running) throw new Error("当前无法修改执行设置，请稍后重试。");
+    if (target === null) {
+      updateComposerDraft(scope, value => ({ ...value, executionConfig: { agent: config.agent, ...initial, ...value.executionConfig, ...changes } }));
+      return;
+    }
+    if (!client.setExecutionConfig) throw new Error("当前接入尚未提供保存执行设置的接口。");
+    // An earlier GET must not overwrite the response to this save.
+    const serial = ++request.current;
+    updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: true }));
+    try {
+      const result = await client.setExecutionConfig(target, changes, config.revision);
+      validate(result);
+      updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: false }));
+      if (mounted.current && current.current === scope && request.current === serial) setView({ scope, config: result, loading: false });
+    } catch (error) {
+      if (mounted.current && current.current === scope && request.current === serial) setView({ scope, config, loading: false, saveFailed: true, error: `${errorText(error)} 请重新读取设置后再发送。` });
+      throw error;
+    }
+  };
+  return {
+    config: selected, busy, loading: view.scope === scope && view.loading,
+    error: view.scope === scope && (enabled || view.saveFailed || draft.executionUncertain) ? view.error ?? (draft.executionUncertain && !busy ? "执行设置尚未确认，请重新读取后再发送。" : undefined) : undefined,
+    blocked: busy || !!draft.executionUncertain || (view.scope === scope && !!view.saveFailed), reload, save,
+    /** Read at submit time, including changes committed before React paints. */
+    prepareSend: () => {
+      if (isConfigurationBusy(scope) || readComposerDraft(scope).executionUncertain || (view.scope === scope && view.saveFailed)) throw new Error("请等待执行设置保存或重新读取设置后再发送。");
+      return target === null ? { executionConfig: readComposerDraft(scope).executionConfig } : { expectedExecutionRevision: config?.revision };
+    },
+  };
+}

package/src/components.tsx

@@ -9,5 +9,5 @@ export interface CliMsgListProps extends CenterMsgListProps { operator?: Compone
 export interface CliChatProps extends CenterChatProps { operator?: ComponentProps<typeof SessionView> }
 export interface CliBoardProps extends CenterBoardProps { operator?: ComponentProps<typeof SessionRail> }
 export function CliMsgList(props: CliMsgListProps) { return props.operator ? <TasksColumn {...props.operator}/> : <CenterMsgList {...props}/>; }
-export function CliChat(props: CliChatProps) { return props.operator ? <SessionView {...props.operator} board={{...props.operator.board,autoContext:props.operator.board?.autoContext??props.passiveContext,onFilesChange:props.operator.board?.onFilesChange??props.onFilesChange,onFilesWatch:props.operator.board?.onFilesWatch??props.onFilesWatch,onBoardContextChange:props.operator.board?.onBoardContextChange??props.onBoardContextChange}}/> : <CenterChat {...props}/>; }
+export function CliChat(props: CliChatProps) { return props.operator ? <SessionView {...props.operator} composer={props.config?.composer ?? props.operator.composer} board={{...props.operator.board,autoContext:props.operator.board?.autoContext??props.passiveContext,onFilesChange:props.operator.board?.onFilesChange??props.onFilesChange,onFilesWatch:props.operator.board?.onFilesWatch??props.onFilesWatch,onBoardContextChange:props.operator.board?.onBoardContextChange??props.onBoardContextChange}}/> : <CenterChat {...props}/>; }
 export function CliBoard(props: CliBoardProps) { return props.operator ? <SessionRail key={props.operator.task.id} {...props.operator} tabs={props.operator.tabs ?? props.tabs} availableTabs={props.operator.availableTabs ?? props.availableTabs} defaultTab={props.operator.defaultTab ?? props.defaultTab} autoContext={props.operator.autoContext ?? props.autoQuoteOpenFile} watchFiles={props.operator.watchFiles ?? props.watchFiles} fileWatchIntervalMs={props.operator.fileWatchIntervalMs ?? props.fileWatchIntervalMs} onFilesChange={props.operator.onFilesChange ?? props.onFilesChange} onFilesWatch={props.operator.onFilesWatch ?? props.onFilesWatch} onBoardContextChange={props.operator.onBoardContextChange ?? props.onBoardContextChange} onEvent={props.operator.onEvent ?? props.onEvent}/> : <CenterBoard {...props}/>; }

package/src/core/blocks.ts

@@ -88,7 +88,8 @@ export function serializeBlock(block: TextBlock): string {
 
 /** 输入框里的文字 + 文本块 → 发给 center 的正文。 */
 export function composeMessage(typed: string, blocks: TextBlock[]): string {
-  return [typed.trim(), ...blocks.map(serializeBlock)].filter(Boolean).join("\n\n");
+  const originals = blocks.some(block => block.kind === "file" && (/^\[Attached (?:file|image): /.test(block.text) || /^\[文件原件：.*\]\(cli-upload:\/\//.test(block.text)));
+  return [typed.trim(), originals ? "请先读取以下附件原件，再处理本条消息。" : "", ...blocks.map(serializeBlock)].filter(Boolean).join("\n\n");
 }
 
 export type MessagePart = { kind: "text"; text: string } | { kind: "block"; block: TextBlock };

package/src/core/client.ts

@@ -5,6 +5,10 @@ import type {
   BatchStreamSnapshot, BrowserFramesState, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot, WorkspaceFileBatch,
 } from "./types";
 import { decodeText } from "./textDecode";
+import { createDocumentUploader, extractDocumentReferences, documentRequest, isTaskUploadPath, type UploadDocument, type DocumentUploadOptions, type DocumentReceipt } from "./documentUpload";
+import { syncFile, type FileSyncTransport } from "../board/fileSync";
+import { createFileSyncTransport } from "../board/fileSyncTransport";
+import type { ExecutionConfiguration, ExecutionOptions } from "./execution";
 
 /**
  * center 服务（cli-task-center）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
@@ -92,6 +96,12 @@ const ERROR_TEXT: Record<string, string> = {
  * 带 ? 的是可选能力：后端不提供，界面就按 Operator 在「没有这个能力」时的样子显示（例如提问的回答改走下一条消息）。
  */
 export interface ConversationBackend {
+  /** 无 key 时读取新对话可用设置；有 key 时读取该对话的已保存设置。 */
+  getExecutionConfig?(key?: string | null): Promise<ExecutionConfiguration>;
+  /** 保存成功才切换界面；服务端用 revision 防止并发覆盖。 */
+  setExecutionConfig?(key: string, changes: ExecutionOptions, expectedRevision: number): Promise<ExecutionConfiguration>;
+  /** Upload original HTML/Markdown without embedding document bytes in a message. */
+  uploadDocument?: UploadDocument;
   baseUrl: string;
   getJob(jobId: string): Promise<CenterJob>;
   /** taskId：只要对话任务里这一个对话的轮次。 */
@@ -104,7 +114,7 @@ export interface ConversationBackend {
   history?(jobId: string, remote: string, before: string, limit?: number): Promise<{ messages: Message[]; older: number }>;
   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>;
+  sendMessage(jobId: string, text: string, opts?: { businessId?: string; timeoutSeconds?: number; taskId?: string; expectedExecutionRevision?: number }): Promise<SendResult>;
   /**
    * 一次性任务里的对话式子任务接着聊：续派一条 mode=conversation、continue_from 这个子任务的子任务（接在同一个 Agent 会话里）。
    * 返回新子任务的 id。
@@ -114,7 +124,7 @@ export interface ConversationBackend {
   pauseTask?(taskId: string): Promise<CenterTask>;
   resumeTask?(taskId: string): Promise<CenterTask>;
   /** 在对话任务里新开一个对话（同一节点、同一工作区），text 是它的第一条消息。 */
-  openConversation?(jobId: string, text: string, opts?: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
+  openConversation?(jobId: string, text: string, opts?: { title?: string; agent?: string; executionConfig?: ExecutionOptions; browser?: boolean; businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
   cancelTurn(jobId: string, turnId: string): Promise<CenterTurn>;
   closeConversation(jobId: string): Promise<{ id: string; status: string }>;
   /** 只关掉对话任务里的一个对话（别的对话和对话任务照常）。 */
@@ -143,6 +153,15 @@ export interface ConversationBackend {
  * 方法里的 jobId 也可以是对话键（"job_x#task_y"）：看对话任务里那个对话的文件、改动和浏览器。
  */
 export interface BoardBackend {
+  /** Save an original file to this conversation without sending a message or starting the agent. */
+  uploadFile?(jobId: string, file: File, options: DocumentUploadOptions): Promise<DocumentReceipt>;
+  /** Authorized input directory of this task; browsing it never starts an agent turn. */
+  uploadDirectory?(jobId: string, signal?: AbortSignal): Promise<string | null>;
+  /** Immutable revisions and content-addressed blocks; refreshes reuse validated local blocks. */
+  fileSync?: FileSyncTransport;
+  /** One directory page only. No recursive scan or file body prefetch. */
+  listFiles?(jobId: string, dir: string, options?: { cursor?: string; limit?: number; signal?: AbortSignal }): Promise<DirListing>;
+  pollFiles?(jobId: string, scope: { paths: string[]; dirs: string[]; cursor?: string }, signal?: AbortSignal): Promise<WorkspaceFileBatch & { cursor?: string; directories: Array<{ path: string; revision: string | null }> }>;
   /** fileUrl 给出的地址浏览器能直接打开（不需要额外请求头）。false 时看板先 fetch 再显示。 */
   directLinks: boolean;
   info(jobId: string): Promise<BoardInfo>;
@@ -283,9 +302,19 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
 
   const post = <T>(path: string, body: unknown = {}) => request<T>(path, { method: "POST", body: JSON.stringify(body) });
   const id = encodeURIComponent;
+  const executionPath = (key?: string | null) => {
+    if (!key) return "/api/execution-config";
+    const ref = parseConvKey(key);
+    return `/api/jobs/${id(ref.jobId)}/execution-config${ref.taskId && ref.taskId !== NEW_TASK ? `?task_id=${id(ref.taskId)}` : ""}`;
+  };
 
   return {
     baseUrl: base,
+    getExecutionConfig: key => request<ExecutionConfiguration>(executionPath(key)),
+    setExecutionConfig: (key, changes, expectedRevision) => request<ExecutionConfiguration>(executionPath(key), {
+      method: "PATCH", body: JSON.stringify({ ...changes, expected_revision: expectedRevision }),
+    }),
+    uploadDocument: createDocumentUploader(doFetch, `${base}/api/file-sync`, headers),
     getJob: (jobId: string) => request<CenterJob>(`/api/jobs/${id(jobId)}`),
     listTurns: (jobId: string, query: { afterSeq?: number; limit?: number; taskId?: string } = {}) => {
       const params = new URLSearchParams();
@@ -326,9 +355,11 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
         ...(opts.callback ? { callback: opts.callback } : {}),
         tasks: [{
           title,
-          prompt: firstMessage,
+          prompt: extractDocumentReferences(firstMessage).text,
+          ...(extractDocumentReferences(firstMessage).attachments ? { attachments: extractDocumentReferences(firstMessage).attachments } : {}),
           ...(opts.businessId ? { business_id: opts.businessId } : {}),
           ...(opts.agent ? { agent: opts.agent } : {}),
+          ...(opts.executionConfig ? { execution_config: opts.executionConfig } : {}),
           ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
           ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
           ...(opts.browserPlaybook !== undefined ? { browser_playbook: opts.browserPlaybook } : {}),
@@ -337,28 +368,30 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
       });
     },
     /** 带 business_id 时 center 按它去重，网络超时可以放心重发同一条。 */
-    sendMessage: (jobId: string, text: string, opts: { businessId?: string; timeoutSeconds?: number; taskId?: string } = {}) =>
+    sendMessage: (jobId: string, text: string, opts: { businessId?: string; timeoutSeconds?: number; taskId?: string; expectedExecutionRevision?: number } = {}) =>
       post<SendResult>(`/api/jobs/${id(jobId)}/messages`, {
-        text,
+        ...extractDocumentReferences(text),
         ...(opts.taskId ? { task_id: opts.taskId } : {}),
+        ...(opts.expectedExecutionRevision !== undefined ? { expected_execution_revision: opts.expectedExecutionRevision } : {}),
         ...(opts.businessId ? { business_id: opts.businessId } : {}),
         ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
       }),
     continueTask: async (jobId: string, taskId: string, text: string, opts: { title?: string; businessId?: string } = {}) => {
       const result = await post<{ task_ids: string[] }>(`/api/jobs`, {
         job_id: jobId, mode: "conversation",
-        tasks: [{ title: opts.title || firstLine(text, 60), prompt: text, continue_from: taskId, ...(opts.businessId ? { business_id: opts.businessId } : {}) }],
+        tasks: [{ title: opts.title || firstLine(text, 60), prompt: extractDocumentReferences(text).text, ...(extractDocumentReferences(text).attachments ? { attachments: extractDocumentReferences(text).attachments } : {}), continue_from: taskId, ...(opts.businessId ? { business_id: opts.businessId } : {}) }],
       });
       return { task_id: result.task_ids[0] };
     },
     pauseTask: (taskId: string) => post<CenterTask>(`/api/tasks/${id(taskId)}/pause`, {}),
     resumeTask: (taskId: string) => post<CenterTask>(`/api/tasks/${id(taskId)}/resume`, {}),
     /** 同一个 business_id 重发只开一个对话。 */
-    openConversation: (jobId: string, text: string, opts: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number } = {}) =>
+    openConversation: (jobId: string, text: string, opts: { title?: string; agent?: string; executionConfig?: ExecutionOptions; browser?: boolean; businessId?: string; timeoutSeconds?: number } = {}) =>
       post<SendResult>(`/api/jobs/${id(jobId)}/conversations`, {
-        text,
+        ...extractDocumentReferences(text),
         ...(opts.title ? { title: opts.title } : {}),
         ...(opts.agent ? { agent: opts.agent } : {}),
+        ...(opts.executionConfig ? { execution_config: opts.executionConfig } : {}),
         ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
         ...(opts.businessId ? { business_id: opts.businessId } : {}),
         ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
@@ -534,31 +567,6 @@ function boardPath(key: string, rest: string, query = "") {
   return `/api/jobs/${job}/${rest}${params ? `?${params}` : ""}`;
 }
 
-/** Reject a malformed manifest as a whole: silently dropping entries could invent deletions. */
-function isWorkspaceFileBatch(value: unknown): value is WorkspaceFileBatch {
-  if (!value || typeof value !== "object") return false;
-  const batch = value as Record<string, unknown>;
-  if (typeof batch.complete !== "boolean" || (batch.revision !== undefined && typeof batch.revision !== "string")) return false;
-  const file = (value: unknown) => {
-    if (!value || typeof value !== "object") return false;
-    const entry = value as Record<string, unknown>;
-    return typeof entry.name === "string" && typeof entry.path === "string" && !!entry.path
-      && (entry.type === "file" || entry.type === "dir")
-      && typeof entry.size === "number" && Number.isFinite(entry.size) && entry.size >= 0
-      && typeof entry.mtime === "number" && Number.isFinite(entry.mtime)
-      && (entry.changeToken === undefined || typeof entry.changeToken === "string");
-  };
-  if (batch.type === "snapshot") return Array.isArray(batch.files) && batch.files.every(file);
-  if (batch.type === "resync") return batch.complete === false && typeof batch.reason === "string";
-  return batch.type === "changes" && Array.isArray(batch.changes) && batch.changes.every(value => {
-    if (!value || typeof value !== "object") return false;
-    const change = value as Record<string, unknown>;
-    return ["created", "modified", "deleted"].includes(String(change.kind)) && typeof change.path === "string" && !!change.path
-      && (change.file === undefined || (file(change.file) && (change.file as { path: string }).path === change.path))
-      && (change.previous === undefined || (file(change.previous) && (change.previous as { path: string }).path === change.path));
-  });
-}
-
 function createBoardClient(
   base: string,
   headers: (extra?: Record<string, string>) => Record<string, string>,
@@ -698,37 +706,28 @@ function createBoardClient(
   const minting = new Map<string, Promise<string | null>>();
   let linksUnsupported = false;
   const LINK_REFRESH_MS = 5 * 60_000;
+  const uploads = new Map<string, UploadDocument>();
+  const fileSync = createFileSyncTransport(doFetch, (jobId, operation) => `${base}${boardPath(jobId, `file-sync/${operation}`)}`, headers);
   return {
     directLinks,
-    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
-    watchFiles(jobId, handlers) {
-      let active = true;
-      let stop: () => void = () => {};
-      const close = (error: CenterError | null) => {
-        if (!active) return;
-        active = false; stop(); handlers.onClose(error);
-      };
-      const fetchStream: typeof fetch = async (input, init) => {
-        const response = await doFetch(input, init);
-        if (response.ok && !/^text\/event-stream(?:\s*;|$)/i.test(response.headers.get("content-type") ?? "")) {
-          await response.body?.cancel().catch(() => undefined);
-          throw new CenterError("文件事件接口未返回事件流，请检查服务代理配置", "INVALID_RESPONSE", 502);
-        }
-        return response;
-      };
-      stop = openSse(fetchStream, `${base}${boardPath(jobId, "files/events")}`, headers(), (event, data) => {
-        if (!active) return;
-        if (event === "files" || event === "message") {
-          if (!isWorkspaceFileBatch(data)) { close(new CenterError("文件事件数据不完整，正在重新同步", "INVALID_RESPONSE", 502)); return; }
-          handlers.onEvent(data);
-        } else if (event === "end") {
-          const end = data && typeof data === "object" ? data as Record<string, unknown> : {};
-          close(new CenterError(typeof end.detail === "string" ? end.detail : "文件监听连接中断，正在重连", typeof end.reason === "string" ? end.reason : "NETWORK", typeof end.status === "number" ? end.status : 0));
-        }
-      }, close);
-      return () => { active = false; stop(); };
+    uploadFile(jobId, file, options) {
+      let upload = uploads.get(jobId);
+      if (!upload) {
+        const { job, task } = boardTarget(jobId);
+        upload = createDocumentUploader(doFetch, `${base}/api/jobs/${job}${task ? `/tasks/${task}` : ""}/file-sync`, headers);
+        uploads.set(jobId, upload);
+      }
+      return upload(file, options);
     },
-    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
+    async uploadDirectory(jobId, signal) {
+      const capabilities = await documentRequest<{ uploadsPath?: string }>(doFetch, `${base}${boardPath(jobId, "file-sync/capabilities")}`, { signal }, headers);
+      return typeof capabilities.uploadsPath === "string" ? capabilities.uploadsPath : null;
+    },
+    fileSync,
+    listFiles: (jobId, dir, options = {}) => documentRequest<DirListing>(doFetch, `${base}${boardPath(jobId, "file-sync/list", new URLSearchParams({ dir: dir || ".", limit: String(options.limit ?? 200), ...(options.cursor ? { cursor: options.cursor } : {}) }).toString())}`, { signal: options.signal }, headers),
+    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
+    pollFiles: (jobId, scope, signal) => documentRequest(doFetch, `${base}${boardPath(jobId, "file-sync/changes")}`, { method: "POST", signal, headers: { "Content-Type": "application/json" }, body: JSON.stringify(scope) }, headers),
+    stat: (jobId, path = ".") => documentRequest<DirListing | FileInfo>(doFetch, `${base}${boardPath(jobId, "file-sync/stat", `path=${encodeURIComponent(path)}`)}`, {}, headers),
     fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
     async fileLinkBase(jobId) {
       const { job, task } = boardTarget(jobId);
@@ -761,6 +760,11 @@ function createBoardClient(
       return { bytes, start, size };
     },
     async readBuffer(jobId, path, opts = {}) {
+      if (isTaskUploadPath(path)) {
+        const file = await syncFile(fileSync, jobId, path, { signal: opts.signal, decode: false,
+          onProgress: progress => opts.onBytes?.(progress.loadedBytes) });
+        return file.bytes.buffer as ArrayBuffer;
+      }
       const { body } = await fileFetch(jobId, path, {}, opts.signal);
       return (await body({ onBytes: opts.onBytes })).buffer;
     },

package/src/core/config.ts

@@ -45,6 +45,10 @@ export interface CliChatConfig {
     charCount?: boolean;
     /** 文件上传（按钮、拖拽、粘贴文件）。只收文档：Word、Excel、Markdown、TXT、HTML、CSV。 */
     fileUpload?: boolean;
+    /** 智能体选择入口，默认显示；缺少服务端能力时禁用。 */
+    agentSelector?: boolean;
+    /** 执行模式选择入口，默认显示；缺少服务端能力时禁用。 */
+    executionMode?: boolean;
     /** 「文件」按钮的文字。 */
     fileButtonText?: string;
     /** 执行控制：普通对话停止当前轮次，一次性子任务暂停 / 继续。 */
@@ -87,7 +91,7 @@ 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;
+    hints: boolean; charCount: boolean; fileUpload: boolean; agentSelector: boolean; executionMode: boolean; fileButtonText: string; stop: boolean; queue: boolean;
   };
   transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialPrompt: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean; status: boolean };
   labels: { user: string; agent: string };
@@ -108,7 +112,7 @@ export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
     placeholderNew: "输入消息，开始新对话…",
     placeholderRunning: "排队一条后续消息…（本轮结束后发送）",
     placeholderDisabled: null,
-    hints: true, charCount: true, fileUpload: true, fileButtonText: "文件", stop: true, queue: true,
+    hints: false, charCount: false, fileUpload: true, agentSelector: true, executionMode: true, fileButtonText: "", stop: true, queue: true,
   },
   transcript: { nav: true, sessionLabel: true, timestamps: true, initialPrompt: false, initialBadge: true, tools: true, runningIndicator: true, status: false },
   labels: { user: "你", agent: "智能体" },

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">;
+  }>;
+}