@spzxg/cli-ui 0.6.1 → 0.6.5

package/src/operator/node/Transcript.tsx

@@ -0,0 +1,463 @@
+"use client";
+import { useContext } from "react";
+import { OperatorBoardContext } from "./boardInteraction";
+import { FileLinkContext } from "./fileLinks";
+
+import { memo, useState } from "react";
+import type { ToolData, ToolPeek, AskQuestion, AskAnswers, InputRequest } from "./protocol/types";
+import { Icon } from "./icons";
+import { Markdown } from "./Markdown";
+import { splitMessage } from "../../core/blocks";
+import { withoutBoardContext } from "../../board/context";
+import { clockTime, diffCls, splitAttachments, type MsgAttachment } from "./format";
+import { CONTEXT_OVERFLOW_NOTICE } from "./protocol/promptLimits";
+import { AUTH_EXPIRED_NOTICE } from "./protocol/authFailure";
+import { USAGE_LIMIT_NOTICE } from "./protocol/usageLimit";
+import { APPROVAL_BLOCKED_NOTICE } from "./protocol/approvalFailure";
+import type { Msg } from "./types";
+import { clientFeatures } from "./protocol/features";
+import { Avatar } from "./shared";
+import { toolDataOf } from "./transcriptModel";
+
+// The always-visible "peek" tier — Claude Code's `⎿` line. Counts show no
+// content; diffs/snippets show a capped hunk with a clickable "+N more" that
+// opens the full body. TodoWrite renders its checklist inline.
+function PeekView({ peek, expandable, onExpand }: { peek: ToolPeek; expandable: boolean; onExpand: () => void }) {
+  const corner = <span className="tcorner">⎿</span>;
+  if (peek.kind === "count") {
+    return (
+      <button className="tpeek tpeek-count" style={{ cursor: expandable ? "pointer" : "default" }} onClick={() => expandable && onExpand()}>
+        {corner}<span className="tpeek-txt">{peek.text}</span>
+        {expandable && <span className="tpeek-more">展开</span>}
+      </button>
+    );
+  }
+  if (peek.kind === "todos") {
+    return (
+      <div className="tpeek tpeek-todos">
+        {peek.items.map((t, i) => (
+          <div className={`tdo ${t.status}`} key={i}>
+            <span className="tdo-box">{t.status === "completed" ? "✔" : t.status === "in_progress" ? "▣" : "▢"}</span>
+            <span className="tdo-txt">{t.text}</span>
+          </div>
+        ))}
+      </div>
+    );
+  }
+  if (peek.kind === "diff") {
+    return (
+      <div className="tpeek tpeek-diff">
+        <div className="tpeek-sum">{corner}<span className="dstat add">+{peek.added}</span><span className="dstat del">−{peek.removed}</span>{peek.label && <span className="tpeek-txt">{peek.label}</span>}</div>
+        <pre className="tpeek-pre diff">{peek.lines.map((l, i) => <div className={`dl ${diffCls(l.sign)}`} key={i}>{l.sign} {l.text}</div>)}</pre>
+        {peek.truncated ? <button className="tpeek-more btn-link" onClick={onExpand}>还有 {peek.truncated} 行</button> : null}
+      </div>
+    );
+  }
+  // lines (Bash output)
+  return (
+    <div className="tpeek tpeek-lines">
+      {peek.label && <div className="tpeek-sum">{corner}<span className="tpeek-txt">{peek.label}</span></div>}
+      <pre className="tpeek-pre">{peek.lines.join("\n") || "（无输出）"}</pre>
+      {peek.truncated ? <button className="tpeek-more btn-link" onClick={onExpand}>还有 {peek.truncated} 行</button> : null}
+    </div>
+  );
+}
+
+function ToolView({ data }: { data: ToolData }) {
+  const [open, setOpen] = useState(false);
+  const hasDiff = !!data.diff?.length;
+  const expandable = !!(data.detail || hasDiff || data.result !== undefined);
+  // Failures surface their output automatically, like Claude Code.
+  const showBody = open || (!!data.isError && data.result !== undefined);
+  return (
+    <div className="tool">
+      <button className="tool-h" style={{ cursor: expandable ? "pointer" : "default" }} onClick={() => expandable && setOpen((o) => !o)}>
+        {expandable && <span className={`tchev ${showBody ? "open" : ""}`}>{Icon.chevRight()}</span>}
+        <span className="tg">{data.title}</span>
+        {data.result !== undefined && <span className={data.isError ? "tx" : "tcheck"}>{data.isError ? Icon.x() : Icon.check()}</span>}
+      </button>
+      {data.peek && !showBody && <PeekView peek={data.peek} expandable={expandable} onExpand={() => setOpen(true)} />}
+      {showBody && (
+        <div className="tool-body">
+          {data.detail && <pre className="tool-pre">{data.detail}</pre>}
+          {hasDiff && (
+            <pre className="tool-pre diff">{data.diff!.map((l, i) => <div className={`dl ${diffCls(l.sign)}`} key={i}>{l.sign} {l.text}</div>)}</pre>
+          )}
+          {data.result !== undefined && (
+            <>
+              {(data.detail || hasDiff) && <div className="tool-divider">结果</div>}
+              <pre className={`tool-pre ${data.isError ? "err" : ""}`}>{data.result || "（无输出）"}</pre>
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Interactive AskUserQuestion card: option pickers (+ an "Other" free-text per
+// question) while pending; a read-only summary once answered.
+function AskView({ data, agentLabel, onAnswer }: { data: ToolData; agentLabel: string; onAnswer: (answers: AskAnswers) => void }) {
+  const questions = data.ask?.questions ?? [];
+  const existing = data.ask?.answers;
+  const [state, setState] = useState(() => questions.map(() => ({ picked: [] as string[], other: "" })));
+  const [submitted, setSubmitted] = useState(false);
+
+  if (existing) {
+    return (
+      <div className="ask answered">
+        <div className="ask-head">{Icon.spark()} 你的回答</div>
+        {questions.map((q, i) => (
+          <div className="ask-q" key={i}>
+            <div className="ask-qh"><span className="ask-chip">{q.header}</span>{q.question}</div>
+            <div className="ask-picked">{(existing[i] ?? []).join("、") || "—"}</div>
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  const toggle = (qi: number, label: string, multi: boolean) =>
+    setState((s) => s.map((st, i) => {
+      if (i !== qi) return st;
+      if (multi) {
+        const has = st.picked.includes(label);
+        return { ...st, picked: has ? st.picked.filter((l) => l !== label) : [...st.picked, label] };
+      }
+      return { picked: [label], other: "" }; // single-select replaces, clears Other
+    }));
+  const setOther = (qi: number, v: string) =>
+    setState((s) => s.map((st, i) => (i === qi ? (questions[i].multiSelect ? { ...st, other: v } : { picked: [], other: v }) : st)));
+
+  const answers: AskAnswers = state.map((st) => [...st.picked, ...(st.other.trim() ? [st.other.trim()] : [])]);
+  const complete = answers.every((a) => a.length > 0);
+  const submit = () => { if (complete && !submitted) { setSubmitted(true); onAnswer(answers); } };
+
+  return (
+    <div className="ask">
+      <div className="ask-head">{Icon.spark()} {agentLabel} 需要你的输入</div>
+      {questions.map((q, i) => (
+        <div className="ask-q" key={i}>
+          <div className="ask-qh"><span className="ask-chip">{q.header}</span>{q.question}{q.multiSelect && <span className="ask-multi">可多选</span>}</div>
+          <div className="ask-opts">
+            {q.options.map((o) => (
+              <button key={o.label} className={`ask-opt ${state[i].picked.includes(o.label) ? "on" : ""}`} onClick={() => toggle(i, o.label, !!q.multiSelect)} disabled={submitted}>
+                <span className="ask-opt-l">{o.label}</span>
+                {o.description && <span className="ask-opt-d">{o.description}</span>}
+              </button>
+            ))}
+            <input className="ask-other" placeholder="其他…" value={state[i].other} disabled={submitted} onChange={(e) => setOther(i, e.target.value)} />
+          </div>
+        </div>
+      ))}
+      <div className="ask-foot">
+        <button className="btn btn-accent btn-sm" onClick={submit} disabled={!complete || submitted}>{submitted ? "发送中…" : "发送回答"}</button>
+      </div>
+    </div>
+  );
+}
+
+/** Ask the session rail to show this task's browser (SessionRail / SessionView listen). */
+export function showTaskBrowser(taskId?: string): void {
+  window.dispatchEvent(new CustomEvent("orch:show-browser", {detail:{taskId}}));
+}
+
+// browser_ask_user card (lib/browserInput.ts): what the agent needs to carry on
+// in the browser — codes, accounts, passwords, choices — typed or picked right
+// here while the browser waits on the page. Passwords are masked and never kept.
+function InputView({ input, agentLabel, onSubmit, onShowBrowser }: { onShowBrowser?:()=>void; input: InputRequest; agentLabel: string; onSubmit?: (id: string, values: string[]) => Promise<string | null> }) {
+  const [vals, setVals] = useState<string[]>(() => input.fields.map(() => ""));
+  const [shown, setShown] = useState<boolean[]>(() => input.fields.map(() => false));
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  const browser = clientFeatures().browser;
+
+  if (input.status !== "pending") {
+    return (
+      <div className="ask answered">
+        <div className="ask-head">{Icon.lock()} {input.status === "answered" ? "你提供的信息" : "已取消 —— 这一轮被停止了"}</div>
+        <div className="ask-q"><div className="ask-qh">{input.message}</div></div>
+        {input.status === "answered" && input.fields.map((f, i) => (
+          <div className="ask-q" key={i}>
+            <div className="ask-qh"><span className="ask-chip">{f.label}</span></div>
+            <div className="ask-picked">{f.secret ? "••••••（只交给浏览器脚本，没有保存，也没有发给模型）" : input.values?.[i] ?? "—"}</div>
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  const set = (i: number, v: string) => setVals((a) => a.map((x, j) => (j === i ? v : x)));
+  const complete = vals.every((v) => v.trim());
+  const submit = async () => {
+    if (!complete || busy || !onSubmit) return;
+    setBusy(true);
+    setErr(null);
+    const e = await onSubmit(input.id, vals.map((v) => v.trim()));
+    if (e) { setErr(e); setBusy(false); }
+  };
+  return (
+    <div className="ask">
+      <div className="ask-head">{Icon.lock()} {agentLabel} 需要你提供信息 · 浏览器正停在这一页等待</div>
+      <div className="ask-q"><div className="ask-qh" style={{ whiteSpace: "pre-wrap" }}>{input.message}</div></div>
+      {input.fields.map((f, i) => (
+        <div className="ask-q" key={i}>
+          <div className="ask-qh"><span className="ask-chip">{f.label}</span>{f.secret && <span className="ask-multi">保密</span>}</div>
+          <div className="ask-opts">
+            {f.options?.map((o) => (
+              <button key={o} className={`ask-opt ${vals[i] === o ? "on" : ""}`} onClick={() => set(i, o)} disabled={busy}>
+                <span className="ask-opt-l">{o}</span>
+              </button>
+            ))}
+            <div className="input-row">
+              <input
+                className="ask-other"
+                type={f.secret && !shown[i] ? "password" : "text"}
+                autoComplete={f.secret ? "new-password" : "off"}
+                placeholder={f.options?.length ? "其他…" : f.placeholder || `输入${f.label}`}
+                value={f.options?.includes(vals[i]) ? "" : vals[i]}
+                disabled={busy}
+                autoFocus={i === 0 && !f.options?.length}
+                onChange={(e) => set(i, e.target.value)}
+                onKeyDown={(e) => { if (e.key === "Enter" && !e.nativeEvent.isComposing) void submit(); }}
+              />
+              {f.secret && (
+                <button className="btn btn-ghost btn-sm" type="button" onClick={() => setShown((a) => a.map((x, j) => (j === i ? !x : x)))}>
+                  {shown[i] ? "隐藏" : "显示"}
+                </button>
+              )}
+            </div>
+          </div>
+        </div>
+      ))}
+      <div className="ask-foot" style={{ gap: 8, alignItems: "center" }}>
+        {err && <span className="input-err">{err}</span>}
+        {input.fields.some((f) => f.secret) && !err && <span className="input-note">密码只交给浏览器脚本，不保存、不发给模型</span>}
+        <span style={{ flex: 1 }} />
+        {browser && <button className="btn btn-line btn-sm" onClick={onShowBrowser ?? (()=>showTaskBrowser())}>查看浏览器</button>}
+        <button className="btn btn-accent btn-sm" onClick={() => void submit()} disabled={!complete || busy}>{busy ? "发送中…" : "提交"}</button>
+      </div>
+    </div>
+  );
+}
+
+// The transcript lines browser_handoff / a page prompt write (lib/browserHandoff.ts,
+// lib/browser.ts — both start with 🖐): the user has to act in the page itself. Buttons to open the live browser and to hand
+// it back without hunting for the rail.
+export const HANDOFF_NOTICE_PREFIX = "🖐 ";
+function HandoffLine({ text, onBrowser, onShowBrowser, readOnly }: { readOnly?:boolean; onShowBrowser?:()=>void; text: string; onBrowser?: (action: "handback") => Promise<string | null> }) {
+  const [state, setState] = useState<"idle" | "busy" | "done">("idle");
+  const [err, setErr] = useState<string | null>(null);
+  const browser = clientFeatures().browser;
+  return (
+    <div className="msg system info">
+      <div className="msg-body">
+        {text}
+        {browser && (
+          <div style={{ display: "flex", gap: 8, marginTop: 8, flexWrap: "wrap", alignItems: "center" }}>
+            {!readOnly&&<button className="btn btn-line btn-sm" onClick={onShowBrowser ?? (()=>showTaskBrowser())}>查看浏览器</button>}
+            {onBrowser && (
+              <button className="btn btn-accent btn-sm" disabled={state !== "idle"} onClick={async () => {
+                setState("busy");
+                const e = await onBrowser("handback");
+                if (e) { setErr(e); setState("idle"); } else setState("done");
+              }}>{state === "done" ? "已交还" : state === "busy" ? "交还中…" : "我已完成，交还给 AI"}</button>
+            )}
+            {err && <span className="input-err">{err}</span>}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// Attachment chips parsed out of a user message's markers: image thumbnails
+// (click opens full size) and text-file chips (a big paste diverted to a file;
+// click opens it). Both are served from the task's uploads dir.
+function AttachmentStrip({ items }: { items: MsgAttachment[] }) {
+  if (!items.length) return null;
+  return (
+    <div className="msg-attachments">
+      {items.map((a, i) =>
+        a.kind === "image" ? (
+          <a key={i} href={a.url} target="_blank" rel="noreferrer" title="查看原图">
+            {/* eslint-disable-next-line @next/next/no-img-element */}
+            <img src={a.url} alt="附件图片" loading="lazy" />
+          </a>
+        ) : (
+          <a key={i} href={a.url} target="_blank" rel="noreferrer" className="file-chip" title={`打开 ${a.name}`}>
+            {Icon.clip()} <span>附件文件</span>
+          </a>
+        )
+      )}
+    </div>
+  );
+}
+
+// Memoized: during a live turn every SSE event re-renders the transcript's
+// parents, but message objects are append-only (replaced only when their content
+// changes), so unchanged messages skip re-rendering — and re-parsing their
+// markdown — entirely. Callers must pass identity-stable handlers or the memo
+// is defeated (SessionView wraps its handlers for exactly this reason).
+function AutomaticBoardBackground({content}:{content:string}) {
+ const blocks=splitMessage(content).filter(part=>part.kind==='block'&&part.block.kind==='viewing');
+ if(!blocks.length)return null;
+ return <details className="cli-auto-background"><summary>自动看板背景</summary>{blocks.map((part,index)=>part.kind==='block'?<pre key={index}>{part.block.text}</pre>:null)}</details>;
+}
+
+export const MessageView = memo(function MessageView({ m, initial, hideWho, running, agent, agentLabel = "智能体", onAnswer, onInput, onBrowser, onCancelQueued, onClear, onReconnect, onRetry, onQuote, readOnly }: { readOnly?: boolean; onQuote?: (m: Msg, selected?: string) => void; m: Msg; initial: boolean; hideWho: boolean; running?: boolean; agent?: string | null; agentLabel?: string; onAnswer?: (askId: string, questions: AskQuestion[], answers: AskAnswers) => void; onInput?: (inputId: string, values: string[]) => Promise<string | null>; onBrowser?: (action: "handback") => Promise<string | null>; onCancelQueued?: (pendingId: string) => void; onClear?: () => void; onReconnect?: () => void; onRetry?: (msgId: string) => void }) {
+  const openBoard=useContext(OperatorBoardContext);
+  const fileScope=useContext(FileLinkContext);
+  const onShowBrowser=()=>{if(fileScope&&openBoard)openBoard({kind:'browser',taskId:fileScope.taskId});else showTaskBrowser(fileScope?.taskId);};
+  if (readOnly) { onAnswer=undefined; onInput=undefined; onBrowser=undefined; onRetry=undefined; onCancelQueued=undefined; onClear=undefined; }
+  if (m.role === "queued") {
+    // A follow-up the user typed mid-turn, waiting its turn. Reads like a user
+    // bubble but dimmed, tagged "Queued", with an × to drop it before it runs.
+    const { text, attachments } = splitAttachments(withoutBoardContext(m.content));
+    return (
+      <div className="msg user queued">
+        <div className="who"><Avatar who="user" /> 你<span className="badge queued-badge">排队中</span>{m.ts != null && <span className="msg-time">{clockTime(m.ts)}</span>}</div>
+        <div className="msg-body">
+          {text && <Markdown>{text}</Markdown>}
+          <AutomaticBoardBackground content={m.content}/>
+          <AttachmentStrip items={attachments} />
+          {onCancelQueued && <button className="queued-x" title="从队列中移除" aria-label="从队列中移除" onClick={() => onCancelQueued(m.id)}>{Icon.x()}</button>}
+        </div>
+      </div>
+    );
+  }
+  if (m.role === "tool") {
+    const data = toolDataOf(m);
+    if (data.input) {
+      return <div className="msg msg-tool" inert={readOnly||undefined}><InputView input={data.input} agentLabel={agentLabel} onSubmit={onInput} onShowBrowser={onShowBrowser} /></div>;
+    }
+    if (data.ask) {
+      return <div className="msg msg-tool" inert={readOnly||undefined}><AskView data={data} agentLabel={agentLabel} onAnswer={(answers) => onAnswer?.(data.ask?.id || m.toolId || "", data.ask?.questions ?? [], answers)} /></div>;
+    }
+    return <div className="msg msg-tool"><ToolView data={data} /></div>;
+  }
+  if (m.role === "system" && m.content.startsWith(HANDOFF_NOTICE_PREFIX)) {
+    return <HandoffLine text={m.content} onBrowser={onBrowser} onShowBrowser={onShowBrowser} readOnly={readOnly} />;
+  }
+  if (m.role === "system") {
+    // A context-overflow failure: render the warning line plus a one-click path
+    // to /clear, which resets the poisoned session and starts a fresh window
+    // (carrying a summary over). The notice string is matched verbatim — it's
+    // the durable, reconnect-safe channel written by lib/runner.ts.
+    if (m.content.includes(CONTEXT_OVERFLOW_NOTICE)) {
+      return (
+        <div className="msg system overflow">
+          <div className="msg-body">
+            {m.content}
+            {onClear && (
+              <div className="overflow-actions">
+                <button className="btn btn-sm" onClick={onClear} disabled={running} title="保存摘要并开启全新的上下文窗口">
+                  {Icon.clear()} 开启新上下文
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+      );
+    }
+    // The agent's login died: same shape as the overflow case — the warning line
+    // plus the one action that fixes it (Settings → Agents, where the connect
+    // flow lives). Instance-wide, so the titlebar banner says it too; this is
+    // the in-context copy for whoever is reading the failed task.
+    if (m.content.includes(AUTH_EXPIRED_NOTICE)) {
+      return (
+        <div className="msg system overflow">
+          <div className="msg-body">
+            {m.content}
+            {onReconnect && (
+              <div className="overflow-actions">
+                <button className="btn btn-sm" onClick={onReconnect} title={`重新登录 ${agentLabel}`}>
+                  {Icon.bolt()} 重新连接 {agentLabel}
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+      );
+    }
+    // The agent's usage limit is spent: same shape as the two cases above, but
+    // the only recovery is waiting for the reset (the error line above the
+    // notice carries the reset time when the SDK reported one), so this renders
+    // the notice styled like the others with no action button.
+    if (m.content.includes(USAGE_LIMIT_NOTICE)) {
+      return (
+        <div className="msg system overflow">
+          <div className="msg-body">{m.content}</div>
+        </div>
+      );
+    }
+    // The approval policy blocked the turn (enterprise-managed Codex downgraded
+    // the driver's "never" to an approval-requiring policy that exec mode can't
+    // service): same shape as the cases above, with a Retry button — the driver
+    // already switched future turns to the compatible "on-request" policy, so
+    // resending the failed message is the recovery (see lib/approvalFailure.ts).
+    if (m.content.includes(APPROVAL_BLOCKED_NOTICE)) {
+      return (
+        <div className="msg system overflow">
+          <div className="msg-body">
+            {m.content}
+            {onRetry && (
+              <div className="overflow-actions">
+                <button className="btn btn-sm" onClick={() => onRetry(m.id)} disabled={running} title="重新发送失败的消息">
+                  {Icon.bolt()} 重试
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+      );
+    }
+    // Notes that already carry their own glyph (✓/ℹ/⇄ — e.g. the "caught up to main"
+    // sync note) render quietly; anything else is a warning. The runner's error
+    // lines arrive with their own ⚠ already, so only glyph-less content gets one
+    // (prepending unconditionally used to render "⚠ ⚠ …").
+    const info = /^[✓ℹ⇄]/.test(m.content);
+    const glyphed = info || m.content.startsWith("⚠");
+    return <div className={`msg system${info ? " info" : ""}`}><div className="msg-body">{glyphed ? m.content : `⚠ ${m.content}`}</div></div>;
+  }
+  const isUser = m.role === "user";
+  // Only user messages carry attachment markers; assistant text passes through.
+  const { text, attachments } = isUser ? splitAttachments(withoutBoardContext(m.content)) : { text: m.content, attachments: [] };
+  return (
+    <div className={`msg ${isUser ? "user" : "assistant"} ${initial ? "initial" : ""}`}>
+      {!hideWho && (
+        <div className="who">
+          <Avatar who={isUser ? "user" : "cc"} agent={agent} />
+          {isUser ? "你" : "智能体"}
+          {initial && <span className="badge">初始提示</span>}
+          {m.ts != null && <span className="msg-time">{clockTime(m.ts)}</span>}
+        </div>
+      )}
+      <div className="msg-body">
+        {initial && <div className="initial-tag">{Icon.spark()} 已随项目上下文发送</div>}
+        {text && <Markdown>{text}</Markdown>}
+        {isUser&&<AutomaticBoardBackground content={m.content}/>}
+        <AttachmentStrip items={attachments} />
+      </div>
+      {onQuote && text.trim() && <div className="msg-actions"><button title="引用这条消息（选中文字可仅引用选中部分）" aria-label="引用消息" onMouseDown={(e) => e.preventDefault()} onClick={(e) => {
+        const selection = window.getSelection();
+        const body = e.currentTarget.closest(".msg")?.querySelector(".msg-body");
+        const selected = selection && body?.contains(selection.anchorNode) && body.contains(selection.focusNode) ? selection.toString().trim() : "";
+        onQuote(isUser?{...m,content:withoutBoardContext(m.content)}:m, selected || undefined);
+      }}>{Icon.doc()} 引用</button></div>}
+    </div>
+  );
+});
+
+export function SessionBreak({ summary }: { summary: string }) {
+  return (
+    <div className="sbreak">
+      <span className="ln" />
+      <div className="card">
+        <div className="cl">{Icon.clear()} 上下文已清空 · 摘要已保存</div>
+        <div className="ct">{summary}</div>
+      </div>
+      <span className="ln" />
+    </div>
+  );
+}

package/src/operator/node/ViewFile.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { Markdown } from "./Markdown";
+import { FileLinkContext, taskFileApiUrl } from "./fileLinks";
+import { loadPersist } from "./persist";
+
+// Markdown 预览页：/view?task=<任务 id>&path=<文件路径>
+//
+// 智能体在对话里给出的 .md 报告从这里打开 —— 渲染成和对话里一样的排版，
+// 文中指向其他文件的相对链接 / 图片按这个 md 所在的目录解析。原文和下载
+// 走同一个文件接口（app/api/tasks/[id]/files）。
+export default function ViewFile() {
+  const [theme,setTheme]=useState("dark");
+  const [q, setQ] = useState<{ task: string; path: string } | null>(null);
+  // Where the server actually found the file (it may fall back to another
+  // folder): relative links and images in the document resolve from there.
+  const [real, setReal] = useState<string | null>(null);
+  const [text, setText] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const p = loadPersist();
+    setTheme(p.appearance?.theme??"dark");
+    if (p.appearance?.theme) document.documentElement.setAttribute("data-theme", p.appearance.theme);
+    const sp = new URLSearchParams(window.location.search);
+    const task = sp.get("task") ?? "";
+    const path = sp.get("path") ?? "";
+    if (!task || !path) {
+      setError("链接缺少任务或文件路径。");
+      return;
+    }
+    setQ({ task, path });
+    let alive = true;
+    fetch(taskFileApiUrl(task, path))
+      .then(async (res) => {
+        if (!res.ok) {
+          const j = await res.json().catch(() => null);
+          throw new Error(j?.error || `打开失败（${res.status}）`);
+        }
+        const at = res.headers.get("x-orch-file-path");
+        if (at && alive) { try { setReal(decodeURIComponent(at)); } catch { /* keep the asked path */ } }
+        return res.text();
+      })
+      .then((t) => { if (alive) setText(t); })
+      .catch((e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); });
+    return () => { alive = false; };
+  }, []);
+
+  const scope = useMemo(() => {
+    if (!q) return null;
+    const p = real ?? q.path;
+    const cut = p.lastIndexOf("/");
+    return { taskId: q.task, baseDir: cut > 0 ? p.slice(0, cut) : cut === 0 ? "/" : "" };
+  }, [q, real]);
+  const name = q ? q.path.split("/").pop() || q.path : "";
+  const raw = q ? taskFileApiUrl(q.task, q.path) : "";
+
+  return (
+    <div className="cli-ui" data-theme={theme} style={{ position: "fixed", inset: 0, overflow: "auto", background: "var(--bg)", color: "var(--ink)" }}>
+      <div style={{ position: "sticky", top: 0, zIndex: 1, display: "flex", alignItems: "center", gap: 10, padding: "10px 20px", borderBottom: "1px solid var(--line)", background: "var(--chrome)" }}>
+        <span style={{ fontFamily: "var(--mono)", fontSize: 13, fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", flex: 1, minWidth: 0 }} title={q?.path}>{name}</span>
+        {q && <a className="btn btn-line btn-sm" href={raw} target="_blank" rel="noreferrer">原文</a>}
+        {q && <a className="btn btn-line btn-sm" href={`${raw}${raw.includes("?") ? "&" : "?"}download=1`}>下载</a>}
+      </div>
+      <div style={{ maxWidth: 880, margin: "0 auto", padding: "24px 20px 64px", fontSize: 14, lineHeight: 1.7 }}>
+        {error ? (
+          <div style={{ color: "var(--red)" }}>{error}</div>
+        ) : text === null ? (
+          <div style={{ color: "var(--ink-3)" }}>加载中…</div>
+        ) : (
+          <FileLinkContext.Provider value={scope}>
+            <Markdown>{text}</Markdown>
+          </FileLinkContext.Provider>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/operator/node/Welcome.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { useState } from "react";
+import { Icon } from "./icons";
+import { Modal } from "./Modal";
+
+// Coach marks + the post-merge nudge for the built-in "Welcome" tutorial project
+// (projects.seeded = 1). These carry the "how Operator works" teaching that we
+// deliberately keep OUT of the Claude-facing project context — so the concepts
+// live where the user reads them, not where the agent does.
+
+const COACH_KEY = "orch:welcomeCoach:dismissed";
+
+// A slim, dismissible bar above the tutorial session. Names the three-column loop
+// and the three beats of the task the user is about to run.
+export function WelcomeCoach() {
+  const [gone, setGone] = useState<boolean>(() => {
+    try { return localStorage.getItem(COACH_KEY) === "1"; } catch { return false; }
+  });
+  if (gone) return null;
+  const dismiss = () => {
+    try { localStorage.setItem(COACH_KEY, "1"); } catch {}
+    setGone(true);
+  };
+
+  const steps: [string, string][] = [
+    ["开始", "点击「开始」，实时看着 Claude 流式输出它的工具调用。"],
+    ["回答", "它会停下来问你一个小问题 —— 选一个选项即可。"],
+    ["审阅并合并", "打开「改动」，看一遍 diff，然后一键合并。"],
+  ];
+
+  return (
+    <div className="wcoach">
+      <div className="wcoach-head">
+        <span className="wcoach-ic">{Icon.bolt()}</span>
+        <div className="wcoach-title">欢迎 —— 这是一个 2 分钟的实操导览</div>
+        <button className="wcoach-x" onClick={dismiss} title="关闭">{Icon.x()}</button>
+      </div>
+      <div className="wcoach-sub">
+        三栏布局：<strong>项目</strong>（左）· 本项目的<strong>任务</strong> · <strong>实时会话</strong>（右）。
+        运行下面的「试试看」任务，完整体验一遍流程。
+      </div>
+      <div className="wcoach-steps">
+        {steps.map(([label, body], i) => (
+          <div className="wcoach-step" key={label}>
+            <span className="wcoach-num">{i + 1}</span>
+            <div>
+              <div className="wcoach-step-t">{label}</div>
+              <div className="wcoach-step-b">{body}</div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// Fires once the tutorial task is merged: the aha moment landed, so this is the
+// natural place to point the user at their own code (and, since we dropped the
+// notifications step from the wizard, to offer the browser-notification opt-in).
+export function WelcomeNudge({ onCreateProject, onClose }: { onCreateProject: () => void; onClose: () => void }) {
+  const notifSupported = typeof window !== "undefined" && "Notification" in window;
+  const [perm, setPerm] = useState<NotificationPermission | "unsupported">(
+    notifSupported ? Notification.permission : "unsupported"
+  );
+  const enableNotifs = async () => {
+    if (!notifSupported) return;
+    try { setPerm(await Notification.requestPermission()); } catch {}
+  };
+
+  return (
+    <Modal
+      title="你刚刚跑通了整个流程 🎉"
+      sub="流式输出 · 一个提问 · 一份 diff · 一次合并 —— 全都在你自己的工作区里完成。"
+      onClose={onClose}
+      width={520}
+      footer={<>
+        <span className="spacer" />
+        <button className="btn btn-ghost" onClick={onClose}>继续探索</button>
+        <button className="btn btn-accent" onClick={onCreateProject}>{Icon.plus()} 创建项目</button>
+      </>}
+    >
+      <p style={{ margin: "0 0 14px", color: "var(--ink-2)", lineHeight: 1.55 }}>
+        这就是 Operator 的核心：每个任务都是独立的智能体会话，跑在各自的 git worktree 里，
+        因此审阅与合并完全由你决定。准备好把它对准你自己的代码了吗？这个「欢迎」项目
+        随时可以删除。
+      </p>
+      {perm === "default" && notifSupported && (
+        <button className="btn btn-line" onClick={enableNotifs} style={{ alignSelf: "flex-start" }}>
+          {Icon.spark()} 任务需要我时通知我
+        </button>
+      )}
+      {perm === "granted" && (
+        <div className="hlp" style={{ margin: 0, display: "flex", alignItems: "center", gap: 6 }}>
+          <span style={{ color: "var(--green, var(--accent))", display: "inline-flex" }}>{Icon.check()}</span>
+          通知已开启 —— 会话运行时你可以放心离开。
+        </div>
+      )}
+    </Modal>
+  );
+}