@spzxg/cli-ui 0.6.2 → 0.6.5

package/src/operator/node/WorktreePrune.tsx

@@ -0,0 +1,333 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Icon } from "./icons";
+import { jget, jsend } from "./api";
+import { LoadNote, ErrNote } from "./shared";
+import { fmtBytes } from "./format";
+import { DEFAULT_RETENTION_DAYS, retentionDays, validRetentionDays } from "./protocol/storageRetention";
+
+interface Candidate {
+  taskId: string;
+  title: string;
+  projectId: string;
+  projectName: string;
+  branch: string;
+  mergedAt: number;
+  cleanupAt: number;
+  status: string;
+  sizeBytes: number;
+  running: boolean;
+  unsafe: boolean; // dirty or ahead — removing it would lose work
+  unsafeReason: string | null;
+  canDiscard: boolean; // Done tasks may be explicitly destroyed even when unsafe
+}
+interface PruneList {
+  candidates: Candidate[];
+  totalBytes: number;
+}
+interface PruneResult {
+  pruned: string[];
+  discarded: string[];
+  skipped: { taskId: string; reason: string }[];
+  reclaimedBytes: number;
+}
+
+const DAY = 86_400_000;
+const daysAgo = (at: number) => Math.floor((Date.now() - at) / DAY);
+const cleanupLabel = (c: Candidate) => {
+  const d = daysAgo(c.cleanupAt);
+  const action = c.mergedAt ? "合并" : "完成";
+  if (d <= 0) return `今天${action}`;
+  return `${d} 天前${action}`;
+};
+
+// Settings cleanup for merged worktrees and worktrees belonging to Done tasks.
+// Safe cleanup retains branches by default. Unmerged work in a Done task can be
+// explicitly discarded, which permanently deletes its edits and task branch.
+export function WorktreePrune() {
+  const [list, setList] = useState<PruneList | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [minDays, setMinDays] = useState(0);
+  const [deleteBranch, setDeleteBranch] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [result, setResult] = useState<PruneResult | null>(null);
+  // null until the app settings load, so the toggle can't flash the wrong state.
+  const [autoPrune, setAutoPrune] = useState<boolean | null>(null);
+  const [autoDays, setAutoDays] = useState(String(DEFAULT_RETENTION_DAYS));
+  const [savedAutoDays, setSavedAutoDays] = useState(String(DEFAULT_RETENTION_DAYS));
+  const [autoBusy, setAutoBusy] = useState(false);
+  const [autoErr, setAutoErr] = useState<string | null>(null);
+
+  useEffect(() => {
+    jget<Record<string, string>>("/api/settings")
+      .then((s) => {
+        setAutoPrune(s.auto_prune_worktrees !== "off");
+        const days = String(retentionDays(s.auto_prune_days));
+        setAutoDays(days);
+        setSavedAutoDays(days);
+      })
+      .catch((e) => setAutoErr(e instanceof Error ? e.message : String(e)));
+  }, []);
+
+  // Persist off explicitly now that the built-in default is on.
+  const toggleAutoPrune = (on: boolean) => {
+    setAutoBusy(true);
+    setAutoErr(null);
+    jsend<Record<string, string>>("/api/settings", "PATCH", { auto_prune_worktrees: on ? "on" : "off" })
+      .then((s) => setAutoPrune(s.auto_prune_worktrees !== "off"))
+      .catch((e) => setAutoErr(e instanceof Error ? e.message : String(e)))
+      .finally(() => setAutoBusy(false));
+  };
+
+  const saveAutoDays = () => {
+    if (!validRetentionDays(autoDays)) {
+      setAutoErr("保留天数必须是大于或等于 1 的整数");
+      return;
+    }
+    setAutoBusy(true);
+    setAutoErr(null);
+    jsend<Record<string, string>>("/api/settings", "PATCH", { auto_prune_days: String(Number(autoDays)) })
+      .then((s) => {
+        const days = String(retentionDays(s.auto_prune_days));
+        setAutoDays(days);
+        setSavedAutoDays(days);
+      })
+      .catch((e) => setAutoErr(e instanceof Error ? e.message : String(e)))
+      .finally(() => setAutoBusy(false));
+  };
+
+  const refresh = useCallback(() => {
+    setError(null);
+    setResult(null);
+    setConfirming(false);
+    jget<PruneList>("/api/maintenance/worktrees")
+      .then((d) => {
+        setList(d);
+        // Drop any now-stale selections (pruned elsewhere, or filtered out).
+        setSelected((prev) => new Set(d.candidates.filter((c) => prev.has(c.taskId)).map((c) => c.taskId)));
+      })
+      .catch((e) => setError(e instanceof Error ? e.message : String(e)));
+  }, []);
+  useEffect(() => { refresh(); }, [refresh]);
+
+  // Candidates old enough to show, based on merge time or the time marked Done.
+  const shown = useMemo(
+    () => (list?.candidates ?? []).filter((c) => daysAgo(c.cleanupAt) >= minDays),
+    [list, minDays]
+  );
+  const selectable = useMemo(() => shown.filter((c) => !c.running && (!c.unsafe || c.canDiscard)), [shown]);
+  const selectedList = useMemo(() => shown.filter((c) => selected.has(c.taskId)), [shown, selected]);
+  const destructiveList = useMemo(() => selectedList.filter((c) => c.unsafe), [selectedList]);
+  const selectedBytes = selectedList.reduce((s, c) => s + c.sizeBytes, 0);
+  const allSelected = selectable.length > 0 && selectable.every((c) => selected.has(c.taskId));
+
+  const toggle = (taskId: string) => {
+    setConfirming(false);
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(taskId)) next.delete(taskId);
+      else next.add(taskId);
+      return next;
+    });
+  };
+  const toggleAll = () => {
+    setConfirming(false);
+    setSelected(allSelected ? new Set() : new Set(selectable.map((c) => c.taskId)));
+  };
+
+  async function prune() {
+    if (selectedList.length === 0) return;
+    if (!confirming) { setConfirming(true); return; }
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await jsend<PruneResult>("/api/maintenance/worktrees", "POST", {
+        taskIds: selectedList.map((c) => c.taskId),
+        deleteBranch,
+        discardChanges: destructiveList.length > 0,
+      });
+      setResult(res);
+      setSelected(new Set());
+      setConfirming(false);
+      // Reload the candidate list without wiping the just-shown result banner.
+      const fresh = await jget<PruneList>("/api/maintenance/worktrees");
+      setList(fresh);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <>
+      <div className="field">
+        <div className="lab">{Icon.archive()} 回收任务 worktree</div>
+        <div className="hlp" style={{ marginTop: 0, marginBottom: 12 }}>
+          每个任务都在自己的 git worktree 中运行。删除已合并或已完成任务的 worktree 可以回收磁盘空间。
+          安全清理默认<strong>保留分支</strong>，重新打开时会连同提交一起重建 worktree。
+          含未合并改动的已完成任务也可以丢弃，但其改动和分支将被永久删除。
+        </div>
+
+        {error && <ErrNote style={{ marginBottom: 10 }} onRetry={refresh}>{error}</ErrNote>}
+        {result && (
+          <div className="hlp" style={{ marginBottom: 10 }}>
+            {Icon.check()} 已删除 {result.pruned.length} 个 worktree，回收{" "}
+            <strong>{fmtBytes(result.reclaimedBytes)}</strong>
+            {result.discarded.length > 0 && ` · 永久丢弃了 ${result.discarded.length} 个任务的改动`}
+            {result.skipped.length > 0 && ` · 跳过 ${result.skipped.length} 个（${result.skipped.map((s) => s.reason).join("、")}）`}
+          </div>
+        )}
+
+        {list == null && !error ? (
+          <LoadNote style={{ padding: 0 }}>正在扫描 worktree…</LoadNote>
+        ) : list == null ? null : list.candidates.length === 0 ? (
+          <div className="hlp" style={{ marginTop: 0 }}>没有可删除的已合并或已完成任务 worktree —— 无需回收。🎉</div>
+        ) : (
+          <>
+            <div style={{ display: "flex", alignItems: "center", gap: 12, marginBottom: 10, flexWrap: "wrap" }}>
+              <label className="hlp" style={{ margin: 0, display: "flex", alignItems: "center", gap: 6 }}>
+                完成超过
+                <input
+                  type="number" min={0} value={minDays}
+                  onChange={(e) => setMinDays(Math.max(0, Math.round(Number(e.target.value) || 0)))}
+                  style={{ width: 64 }}
+                />
+                天
+              </label>
+              <span className="spacer" style={{ flex: 1 }} />
+              <button className="btn btn-ghost btn-sm" onClick={refresh} disabled={busy}>{Icon.restore()} 重新扫描</button>
+            </div>
+
+            <div style={{ border: "1px solid var(--line, #2a2a2a)", borderRadius: 8, overflow: "hidden" }}>
+              <label className="prune-row" style={rowStyle(true)}>
+                <input type="checkbox" checked={allSelected} onChange={toggleAll} disabled={selectable.length === 0} />
+                <span style={{ flex: 1, fontWeight: 600 }}>
+                  {shown.length} 个 worktree
+                  {minDays > 0 && list.candidates.length !== shown.length ? `（共 ${list.candidates.length} 个）` : ""}
+                </span>
+                <span className="hlp" style={{ margin: 0 }}>合计 {fmtBytes(shown.reduce((s, c) => s + c.sizeBytes, 0))}</span>
+              </label>
+              {shown.map((c) => (
+                <label key={c.taskId} className="prune-row" style={rowStyle(false)} title={c.unsafe ? c.unsafeReason ?? undefined : c.branch}>
+                  <input
+                    type="checkbox"
+                    checked={selected.has(c.taskId)}
+                    onChange={() => toggle(c.taskId)}
+                    disabled={c.running || (c.unsafe && !c.canDiscard)}
+                  />
+                  <span style={{ flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                    <span style={{ opacity: 0.6 }}>{c.projectName} · </span>
+                    {c.title || "（未命名）"}
+                    {c.running && <span className="hlp" style={{ margin: 0, marginLeft: 8 }}>· 运行中，已跳过</span>}
+                    {!c.running && c.unsafe && c.canDiscard && (
+                      <span className="hlp" style={{ margin: 0, marginLeft: 8, color: "var(--red)" }}>
+                        · 永久丢弃{c.unsafeReason ? `（${c.unsafeReason}）` : ""}
+                      </span>
+                    )}
+                    {!c.running && c.unsafe && !c.canDiscard && (
+                      <span className="hlp" style={{ margin: 0, marginLeft: 8, color: "var(--red)" }}>
+                        · 仍有未合并的改动 —— 请先标记为已完成再丢弃
+                      </span>
+                    )}
+                  </span>
+                  <span className="hlp" style={{ margin: 0, whiteSpace: "nowrap" }}>{cleanupLabel(c)}</span>
+                  <span style={{ whiteSpace: "nowrap", fontVariantNumeric: "tabular-nums", width: 72, textAlign: "right" }}>
+                    {fmtBytes(c.sizeBytes)}
+                  </span>
+                </label>
+              ))}
+            </div>
+
+            {destructiveList.length > 0 && (
+              <div className="err-note" style={{ marginTop: 12 }}>
+                <strong>永久丢弃：</strong>所选的 {destructiveList.length} 个已完成任务仍有未合并的改动。
+                {" "}删除它们会一并删除未提交的改动和任务分支，且无法撤销。
+              </div>
+            )}
+
+            <label className="hlp" style={{ display: "flex", alignItems: "flex-start", gap: 8, marginTop: 12 }}>
+              <input type="checkbox" checked={deleteBranch} onChange={(e) => { setDeleteBranch(e.target.checked); setConfirming(false); }} style={{ marginTop: 2 }} />
+              <span>
+                <strong>同时删除分支</strong>（默认关闭）。可以多释放一点空间，但你将无法再查看该任务相对原始基线的 diff。
+                重新打开仍然可用 —— 只是会新建一个空的 worktree。
+                {destructiveList.length > 0 && " 含未合并改动的分支在永久丢弃时总会被删除。"}
+              </span>
+            </label>
+
+            <div style={{ display: "flex", alignItems: "center", gap: 12, marginTop: 12 }}>
+              <button
+                className={`btn ${confirming ? "btn-danger" : "btn-line"}`}
+                onClick={prune}
+                disabled={busy || selectedList.length === 0}
+              >
+                {Icon.archive()}{" "}
+                {busy
+                  ? "删除中…"
+                  : confirming
+                    ? destructiveList.length > 0
+                      ? `确认 —— 删除 ${selectedList.length} 个，永久丢弃 ${destructiveList.length} 个 · 回收 ${fmtBytes(selectedBytes)}`
+                      : `确认 —— 删除 ${selectedList.length} 个并回收 ${fmtBytes(selectedBytes)}${deleteBranch ? " + 删除分支" : ""}`
+                    : `删除所选 ${selectedList.length} 个 · ${fmtBytes(selectedBytes)}`}
+              </button>
+              {confirming && !busy && (
+                <button className="btn btn-ghost btn-sm" onClick={() => setConfirming(false)}>取消</button>
+              )}
+            </div>
+          </>
+        )}
+      </div>
+
+      <div className="field">
+        <div className="lab">{Icon.clock()} 自动清理</div>
+        <label className="hlp" style={{ display: "flex", alignItems: "flex-start", gap: 8, marginTop: 0 }}>
+          <input
+            type="checkbox"
+            aria-label="开启自动清理"
+            checked={autoPrune === true}
+            disabled={autoPrune === null || autoBusy}
+            onChange={(e) => toggleAutoPrune(e.target.checked)}
+            style={{ marginTop: 2 }}
+          />
+          <span>
+            开启自动清理（默认开启）
+          </span>
+        </label>
+        <div style={{ display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap", marginTop: 10 }}>
+          <label className="hlp" style={{ margin: 0, display: "flex", alignItems: "center", gap: 8 }}>
+            保留
+            <input type="number" min={1} step={1} aria-label="自动清理保留天数" value={autoDays}
+              onChange={(e) => setAutoDays(e.target.value)} disabled={autoPrune === null || autoBusy}
+              style={{ width: 80 }} />
+            天
+          </label>
+          <button className="btn btn-line btn-sm" onClick={saveAutoDays}
+            disabled={autoPrune === null || autoBusy || autoDays === savedAutoDays || !validRetentionDays(autoDays)}>
+            {autoBusy ? "保存中…" : "保存天数"}
+          </button>
+          <span className="hlp" style={{ margin: 0 }}>默认 30 天，当前已保存 {savedAutoDays} 天</span>
+        </div>
+        <div className="hlp" style={{ marginTop: 10 }}>
+          按任务最后一次运行结束时间计算，每小时检查一次，关闭浏览器后仍会执行。
+          到期后只回收已核验可恢复的任务工作区副本；项目仓库、原始资料、成果、附件和对话记录保留。
+          正在运行或仍有排队消息的任务会跳过，结束后按最新运行时间重新计算。
+          未提交、未合并或被 Git 忽略的文件会阻止回收，避免丢失续聊需要的资料。
+        </div>
+        {autoErr && <ErrNote>{autoErr}</ErrNote>}
+      </div>
+    </>
+  );
+}
+
+const rowStyle = (header: boolean): React.CSSProperties => ({
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  padding: "8px 12px",
+  borderTop: header ? undefined : "1px solid var(--line, #2a2a2a)",
+  background: header ? "var(--panel, rgba(255,255,255,0.03))" : undefined,
+  cursor: "default",
+});

package/src/operator/node/agents.ts

@@ -0,0 +1,58 @@
+// Client-side helpers over the agents capability bundle (GET /api/agents).
+// Every run control + label the UI shows is derived from this data rather than
+// hardcoded per agent, so adding a driver server-side surfaces in the UI with
+// no client edits. Pure functions (no React) so any module can import them.
+import type { AgentsBundle, AgentInfo, AgentCapabilities } from "./types";
+import { isOptInAgent } from "./protocol/agents/optIn";
+
+export function findAgent(bundle: AgentsBundle, id: string | null | undefined): AgentInfo | undefined {
+  return bundle.agents.find((a) => a.id === id);
+}
+
+// The human name for an agent id, e.g. "Claude Code" / "Codex". Falls back to
+// the raw id (or a generic "Agent") so a task carrying an unknown/legacy id
+// still labels sensibly.
+export function agentLabel(bundle: AgentsBundle, id: string | null | undefined): string {
+  return findAgent(bundle, id)?.label || id || "智能体";
+}
+
+// The capability descriptor for a task's agent — drives its model/reasoning/
+// permission pickers and feature gates (asks, cost display). Undefined until the
+// bundle loads or for an unknown id; callers treat undefined as "no data yet".
+export function capsFor(bundle: AgentsBundle, id: string | null | undefined): AgentCapabilities | undefined {
+  return findAgent(bundle, id)?.capabilities;
+}
+
+// Whether an agent can actually run a turn: connected AND its CLI present on the
+// server. Mirrors isAgentUsable() server-side (lib/agents/connections.ts) so the
+// New-task dialog and POST /api/tasks pick the same agent. `installed`
+// undefined = an older payload that didn't report it; treat as installed rather
+// than hiding every agent.
+export function agentUsable(a: AgentInfo | undefined): boolean {
+  return !!a?.authenticated && a.installed !== false;
+}
+
+// Why an agent can't run right now, as the short suffix pickers show after its
+// label — or null when it's fine. The two states need different words because
+// they need different fixes: "未连接" is a login, "未安装" is a missing CLI on
+// the server that no login will conjure.
+export function agentStateHint(a: AgentInfo | undefined): string | null {
+  if (!a) return null;
+  if (!a.authenticated) return "未连接";
+  if (a.installed === false) return "未安装";
+  return null;
+}
+
+// The agent a new task should default to: the project's default, else the app
+// default — but only when that agent can actually run. Otherwise fall to the
+// first usable agent (a Codex-only instance must not default new tasks to an
+// unconnected — or uninstalled — Claude), and only when NOTHING is usable fall
+// back to mere existence so the picker still renders (with its connect CTA).
+export function defaultAgentFor(bundle: AgentsBundle, projectDefault: string | null | undefined): string {
+  const want = findAgent(bundle, projectDefault || bundle.default);
+  if (agentUsable(want)) return want!.id;
+  const appDefault = findAgent(bundle, bundle.default);
+  if (agentUsable(appDefault)) return appDefault!.id;
+  const usable = bundle.agents.find((a) => !isOptInAgent(a.id) && agentUsable(a));
+  return usable?.id ?? want?.id ?? bundle.agents[0]?.id ?? bundle.default;
+}

package/src/operator/node/api.ts

@@ -0,0 +1,40 @@
+// Tiny fetch helpers used throughout the orchestrator client.
+
+// Routes report failures as JSON `{ error }` — unwrap that so surfaced messages
+// read "worktree is dirty", not a raw JSON blob (transcript system errors, modal
+// error notes and ErrNote all show this string verbatim).
+async function fail(r: Response): Promise<never> {
+  const raw = await r.text();
+  let msg = raw || `${r.status} ${r.statusText}`;
+  try {
+    const j = JSON.parse(raw);
+    if (typeof j?.error === "string" && j.error) msg = j.error;
+  } catch { /* not JSON — keep the raw body */ }
+  throw new Error(msg);
+}
+
+export async function jget<T>(url: string): Promise<T> {
+  const r = await fetch(url, { cache: "no-store" });
+  if (!r.ok) await fail(r);
+  return r.json();
+}
+export async function jsend<T>(url: string, method: string, body?: unknown): Promise<T> {
+  const r = await fetch(url, { method, headers: { "Content-Type": "application/json" }, body: body ? JSON.stringify(body) : undefined });
+  if (!r.ok) await fail(r);
+  return r.json();
+}
+
+// Save an export (GET /api/tasks/[id]/export, /api/projects/[id]/export) to
+// disk. A `download` anchor rather than fetch + blob: the browser streams the
+// response straight to a file with its own progress UI, however long the
+// history is, and — unlike assigning window.location — it never tears down the
+// page's open event streams. The server names the file (Content-Disposition);
+// the viewer's time zone rides along so the timestamps read in local time.
+export function downloadExport(path: string) {
+  const a = document.createElement("a");
+  a.href = `${path}?tz=${encodeURIComponent(Intl.DateTimeFormat().resolvedOptions().timeZone)}`;
+  a.download = "";
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}

package/src/operator/node/boardBackend.ts

@@ -0,0 +1,80 @@
+import { CenterError, createCenterClient, type BoardBackend } from '../../core/client';
+import type { BrowserMessage, BrowserStatus } from '../../core/types';
+import { clientId } from '../../core/id';
+import { taskFileApiUrl } from './fileLinks';
+import { openLive } from './liveStream';
+import { clientFeatures } from './protocol/features';
+/** Node transport for the shared file and browser UI. No center routes or synthetic conversation data. */
+export function createOperatorBoardBackend(fetcher: typeof fetch = (...args) => fetch(...args)): BoardBackend {
+  const client = createCenterClient({ baseUrl: '', fetch: async (input, init) => {
+    const url = new URL(String(input), 'http://operator.invalid');
+    const target = url.pathname.match(/^\/api\/jobs\/([^/]+)\/(.+)$/);
+    if (!target) throw new Error('无效的节点看板请求');
+    let suffix=target[2];
+    if(suffix==='files')url.searchParams.set('format','json');
+    suffix=suffix.replace(/^files\/raw/,'files');
+    return fetcher(`/api/tasks/${target[1]}/${suffix}${url.search}`, init);
+  } });
+  const viewers=new Map<string,WebSocket>();
+  return { ...client.board!, directLinks: true, browserLive:undefined,
+    async info(id) {
+      const response=await fetcher(`/api/tasks/${encodeURIComponent(id)}`,{cache:'no-store'});
+      if(!response.ok)throw new CenterError('无法读取任务看板',`HTTP_${response.status}`,response.status);
+      const task=await response.json();return{job_id:id,dispatched:!!task.started||!!task.worktree_path,files:true,browser:clientFeatures().browser,remote_task_id:id};
+    },
+    fileUrl(id, path, options) { const url = taskFileApiUrl(id, path); return options?.download ? `${url}${url.includes('?') ? '&' : '?'}download=1` : url; },
+    fileLinkBase: async id => `/api/tasks/${encodeURIComponent(id)}/files`,
+    watchFiles(id,handlers) {
+      let stopped=false,ended=false;
+      const disrupted=(reason:string)=>{if(!stopped&&!ended)handlers.onEvent({type:'resync',reason,complete:false});};
+      const subscription=openLive(`/api/tasks/${encodeURIComponent(id)}/files/events`,{
+        onMessage:data=>{
+          if(stopped||ended)return;
+          try{const event=JSON.parse(data);if(['snapshot','changes','resync'].includes(event.type))handlers.onEvent(event);}catch{/* Ignore invalid event. */}
+        },
+        onEnd:code=>{
+          if(stopped||ended)return;
+          if(code===0||code===408||code===429||(code>=500&&code!==501)){disrupted(code===429?'文件监听暂时限流，正在等待恢复':'文件监听连接中断，正在重连');return;}
+          ended=true;
+          const message=code===401?'文件监听登录已过期，请重新登录':code===403?'文件监听被拒绝，请检查任务权限或登录':code===404?'未找到任务或节点不支持文件事件接口':`文件监听请求失败（HTTP ${code}）`;
+          handlers.onClose(new CenterError(message,`HTTP_${code}`,code));
+        },
+        onError:error=>disrupted(error.message),
+      });
+      return()=>{stopped=true;subscription.close();};
+    },
+    browserEvents(id,handlers) {
+      let stopped=false,ended=false;
+      const disrupted=(error:CenterError)=>{if(!stopped&&!ended)handlers.onError?.(error);};
+      const sub=openLive(`/api/tasks/${encodeURIComponent(id)}/browser/events`,{
+        onMessage:data=>{if(stopped||ended)return;try{const status=JSON.parse(data) as BrowserStatus;if(status.state)handlers.onStatus(status);}catch{/* Keep last valid status. */}},
+        onEnd:code=>{
+          if(stopped||ended)return;
+          const error=new CenterError(code===401?'浏览器状态登录已过期':code===403?'没有读取浏览器状态的权限':code===404?'未找到任务或浏览器状态接口':`浏览器状态连接中断（HTTP ${code}）`,`HTTP_${code}`,code);
+          if(code===0||code===408||code===429||(code>=500&&code!==501)){disrupted(error);return;}
+          ended=!!handlers.onClose;handlers.onClose?.(error);
+        },
+        onError:error=>disrupted(new CenterError(error.message,'NETWORK',0)),
+      });return()=>{stopped=true;sub.close();};
+    },
+    browserFrames(id,handlers) {
+      const socket=new WebSocket(`${location.protocol==='https:'?'wss:':'ws:'}//${location.host}/browser/${encodeURIComponent(id)}/stream`);
+      const viewer=clientId();let stopped=false;
+      viewers.set(viewer,socket);
+      const timeout=setTimeout(()=>{if(socket.readyState!==WebSocket.OPEN)socket.close();},10000);
+      socket.onopen=()=>{clearTimeout(timeout);if(!stopped)handlers.onViewer(viewer);};
+      socket.onmessage=event=>{if(stopped)return;try{handlers.onMessage(JSON.parse(String(event.data)) as BrowserMessage);}catch{/* Next frame can recover. */}};
+      socket.onerror=()=>socket.close();
+      socket.onclose=event=>{clearTimeout(timeout);viewers.delete(viewer);if(!stopped)handlers.onClose?.(new CenterError(event.reason||'浏览器画面连接已断开，正在重连','NETWORK',0));};
+      return()=>{stopped=true;clearTimeout(timeout);viewers.delete(viewer);socket.close();};
+    },
+    async browserInput(_id,viewer,events) {
+      const socket=viewers.get(viewer);
+      if(!socket||socket.readyState!==WebSocket.OPEN)throw new CenterError('浏览器画面尚未连接，请稍后重试','NETWORK',0);
+      for(const event of events)socket.send(JSON.stringify(event));
+    },
+  };
+}
+
+let sharedBoardBackend:BoardBackend|undefined;
+export function getOperatorBoardBackend():BoardBackend { return sharedBoardBackend??=createOperatorBoardBackend(); }

package/src/operator/node/boardEvents.ts

@@ -0,0 +1,22 @@
+import { useEffect, useRef } from 'react';
+import { notifyCallback } from '../../core/callbacks';
+import type { WorkspaceHandlers } from '../../core/provider';
+import type { WorkspaceChangeEvent } from '../../core/types';
+import { cloneBoardView } from '../../board/context';
+import type { CliEvent } from '../../core/store';
+import { cloneWorkspaceChange, subscribeWorkspaceFiles } from '../../board/fileWatch';
+import { getOperatorBoardBackend } from './boardBackend';
+import { readBoardState, subscribeBoardState } from './boardState';
+export type OperatorBoardHandlers=WorkspaceHandlers&{onEvent?:(event:CliEvent)=>void};
+export function useOperatorFileWatch(taskId:string,enabled:boolean,handlers:OperatorBoardHandlers={},onChange?:(event:WorkspaceChangeEvent)=>void,intervalMs?:number){
+ const current=useRef({handlers,onChange});current.current={handlers,onChange};
+ useEffect(()=>{
+  if(!enabled)return;
+  return subscribeWorkspaceFiles(getOperatorBoardBackend(),taskId,event=>{current.current.onChange?.(event);notifyCallback(current.current.handlers.onFilesChange,cloneWorkspaceChange(event));notifyCallback(current.current.handlers.onEvent,cloneWorkspaceChange(event));},
+   {intervalMs,onStatus:status=>{notifyCallback(current.current.handlers.onFilesWatch,{...status});notifyCallback(current.current.handlers.onEvent,{...status});}});
+ },[taskId,enabled,intervalMs]);
+}
+export function useOperatorContextEvents(taskId:string,enabled:boolean,handlers:OperatorBoardHandlers={}){
+ const current=useRef(handlers);current.current=handlers;
+ useEffect(()=>{if(!enabled)return;return subscribeBoardState(taskId,()=>{const view=readBoardState(taskId);if(!view)return;const event={type:'board_context' as const,jobId:taskId,view:cloneBoardView(view)};notifyCallback(current.current.onBoardContextChange,{...event,view:cloneBoardView(view)});notifyCallback(current.current.onEvent,event);});},[taskId,enabled]);
+}

package/src/operator/node/boardInteraction.ts

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+import type { WorkspaceHandlers } from '../../core/provider';
+import type { CliEvent } from '../../core/store';
+import type { Quote } from './composerDraft';
+export type OperatorBoardTab = 'files' | 'changes' | 'context' | 'preview' | 'browser';
+export interface OperatorBoardOptions extends WorkspaceHandlers { watchFiles?:boolean; fileWatchIntervalMs?:number; onEvent?:(event:CliEvent)=>void; tabs?: OperatorBoardTab[]; availableTabs?: OperatorBoardTab[]; defaultTab?: OperatorBoardTab; autoContext?: boolean }
+export type OperatorBoardTarget = { kind: 'file'; taskId: string; path: string } | { kind: 'browser'; taskId: string };
+export interface OperatorBoardRequest { sequence: number; target: OperatorBoardTarget }
+export const OperatorBoardContext = createContext<((target: OperatorBoardTarget) => boolean) | null>(null);
+
+export const OperatorBoardQuoteContext = createContext<((quote:Quote)=>void)|null>(null);
+
+const surfaces=new Set<(target:OperatorBoardTarget)=>boolean>();
+export function registerOperatorBoard(surface:(target:OperatorBoardTarget)=>boolean):()=>void {surfaces.add(surface);return()=>{surfaces.delete(surface);};}
+export function openOperatorBoard(target:OperatorBoardTarget):boolean {for(const surface of [...surfaces].reverse())if(surface(target))return true;return false;}

package/src/operator/node/boardState.ts

@@ -0,0 +1,57 @@
+import { useSyncExternalStore } from 'react';
+import type { BoardFile, BoardView } from '../../board/workspace';
+import { rememberBoardFile, cloneBoardView, reportBoardOwner, activateBoardOwner, selectedBoardOwner } from '../../board/context';
+import { notifyCallback } from '../../core/callbacks';
+const cache=new Map<string,{stamp:string;view:BoardView|null}>();
+const listeners=new Map<string,Set<()=>void>>();
+const owners=new Map<string,Map<string,BoardView>>();
+const key=(id:string)=>`cli-ui:operator-board:${id}`;
+const stamp=(id:string)=>{try{return sessionStorage.getItem(key(id))??'';}catch{return 'blocked';}};
+const validFile=(value:unknown):value is BoardFile=>!!value&&typeof value==='object'&&typeof (value as BoardFile).path==='string'&&!!(value as BoardFile).path&&((value as BoardFile).sourceId===undefined||typeof (value as BoardFile).sourceId==='string');
+const recent=(items:BoardFile[]=[])=>{
+ return items.filter(validFile).reduce((history,file)=>rememberBoardFile(history,file),[] as BoardFile[]);
+};
+export function readBoardState(taskId:string):BoardView|null {
+ const saved=stamp(taskId),known=cache.get(taskId);if(known?.stamp===saved)return known.view;
+ let view:BoardView|null=null;
+ try{
+  const value=JSON.parse(saved||'null');
+  if(value&&typeof value.tab==='string'&&typeof value.dir==='string'&&Array.isArray(value.files))view={...value,file:typeof value.file==='string'?value.file:null,files:value.files.filter((path:unknown)=>typeof path==='string'),current:validFile(value.current)?{...value.current}:null,opened:recent(value.opened),history:recent(value.history),visible:false};
+ }catch{/* Broken preferences cannot stop the workspace. */}
+ cache.set(taskId,{stamp:saved,view});return view;
+}
+export function subscribeBoardState(taskId:string,listener:()=>void):()=>void {
+ const set=listeners.get(taskId)??new Set<()=>void>();set.add(listener);listeners.set(taskId,set);return()=>{set.delete(listener);if(!set.size)listeners.delete(taskId);};
+}
+export function publishBoardState(taskId:string,view:BoardView):void {
+ const next=cloneBoardView({...view,current:view.current??null,opened:recent(view.opened),history:recent(view.history)});
+ if(JSON.stringify(readBoardState(taskId))===JSON.stringify(next))return;
+ try{sessionStorage.setItem(key(taskId),JSON.stringify(next));}catch{/* In-memory state still reaches Chat. */}
+ cache.set(taskId,{stamp:stamp(taskId),view:next});for(const listener of [...listeners.get(taskId)??[]])notifyCallback(listener,undefined);
+}
+export function useBoardState(taskId:string):BoardView|null {
+ return useSyncExternalStore(listener=>subscribeBoardState(taskId,listener),()=>readBoardState(taskId),()=>null);
+}
+export function visitBoardFile(taskId:string,file:BoardFile):void {
+ const current=readBoardState(taskId)??{tab:'files',dir:'',file:null,files:[]};
+ publishBoardState(taskId,{...current,history:recent([...(current.history??[]),file])});
+}
+export function reportBoardState(taskId:string,owner:string,view:BoardView):void {
+ const sources=owners.get(taskId)??new Map<string,BoardView>();
+ const history=readBoardState(taskId)?.history??view.history??[];
+ const selected=reportBoardOwner(sources,owner,{...view,history});owners.set(taskId,sources);
+ if(selected)publishBoardState(taskId,{...selected[1],history});
+}
+export function activateBoardState(taskId:string,owner:string):void {
+ const sources=owners.get(taskId);if(!sources)return;
+ const selected=activateBoardOwner(sources,owner);if(!selected)return;
+ const previous=readBoardState(taskId),file=selected[1].current;
+ const history=file?rememberBoardFile(previous?.history??[],file):previous?.history??[];
+ publishBoardState(taskId,{...selected[1],history});
+}
+export function releaseBoardState(taskId:string,owner:string):void {
+ const sources=owners.get(taskId);sources?.delete(owner);if(!sources?.size)owners.delete(taskId);
+ const previous=readBoardState(taskId);if(!previous)return;
+ const remaining=sources?.size?selectedBoardOwner(sources)?.[1]:null;
+ publishBoardState(taskId,remaining?{...remaining,history:previous.history,visible:remaining.visible!==false}:{...previous,visible:false});
+}

package/src/operator/node/boardWorkspace.ts

@@ -0,0 +1,12 @@
+import { createWorkspace } from '../../board/workspace';
+import { cloneBoardView } from '../../board/context';
+import { getOperatorBoardBackend } from './boardBackend';
+import { readBoardState } from './boardState';
+import { openOperatorBoard } from './boardInteraction';
+/** Host API for the node workspace. Uses the same cloud-facing file API as the board. */
+export function createOperatorWorkspace(taskId:string){
+ return createWorkspace({backend:getOperatorBoardBackend(),key:taskId,
+  view:()=>{const view=readBoardState(taskId);return view?.visible?cloneBoardView(view):undefined;},
+  context:()=>{const view=readBoardState(taskId);return view?cloneBoardView(view):null;},
+  open:path=>openOperatorBoard({kind:'file',taskId,path})});
+}

package/src/operator/node/branchFlow.ts

@@ -0,0 +1 @@
+export * from "../branchFlow";