@yss123/cage-cli 0.1.0 → 0.3.0

package/templates/app/apps/web/src/shared/ui/assistant-panel.tsx

@@ -0,0 +1,200 @@
+/**
+ * 工作台内持续存在的业务助理面板，负责输入、流式文本、工具进度和人工确认的可视交互。
+ * 实际运行、持久化计划、工具授权与取消由 useAssistant 和服务端负责；面板关闭只是收起 UI。
+ * 每轮绑定发送时页面实例与中文标签，切页后不把新页面快照冒充本轮原始上下文。
+ */
+// 组件只消费框架 SDK；页面显式传入语义上下文，业务事实与写权限由服务端核验。
+import { useEffect, useMemo, useRef, useState, type FormEvent } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { client, AiPageContext, useAssistant, type PageContextInput, type AiRun } from '@yss123/cage-client';
+import { AssistantMarkdown } from './assistant-markdown';
+import './assistant-panel.css';
+
+/**
+ * 服务端运行状态的界面名称；succeeded 表示本轮运行结束，具体业务效果以命令回执和重新查询为准。
+ */
+const captions: Record<string, string> = {
+  queued: '等待处理', running: '正在核对页面与业务规则', waiting_confirmation: '等待你确认操作',
+  waiting_input: '需要补充信息', succeeded: '本轮已完成', failed: '本轮执行失败', expired: '本轮已超时', cancelled: '已停止',
+};
+/**
+ * 工具活动的展示名称，只用于解释过程；不能依据这个表构造工具白名单或权限。
+ */
+const toolLabels: Record<string, string> = {
+  ontology_search: '查询业务规则', data_get: '读取单据', data_list: '查询业务数据', data_related: '查询关联记录',
+  data_query: '汇总业务数据', approval_history: '查询审批进度', approval_tasks: '查询审批待办',
+  approval_decide: '处理审批', request_input: '补充必要信息', request_page_context: '更新页面内容', memory_remember: '保存偏好',
+};
+/**
+ * 助理入口与空性格头像使用的装饰图形；aria-hidden 避免重复朗读按钮名称。
+ */
+function AssistantMark() {
+  return <svg viewBox="0 0 32 32" fill="none" aria-hidden="true"><path d="M7 6h18a3 3 0 0 1 3 3v12a3 3 0 0 1-3 3H14l-7 4v-4a3 3 0 0 1-3-3V9a3 3 0 0 1 3-3Z" stroke="currentColor" strokeWidth="1.6" strokeLinejoin="round" /><path d="m16 10 1.5 4.5L22 16l-4.5 1.5L16 22l-1.5-4.5L10 16l4.5-1.5L16 10Z" fill="currentColor" /></svg>;
+}
+/**
+ * 渲染浮动面板、当前页面提示、会话消息、确认步骤和提问表单。
+ * context/suggestions 由页面注册层提供；pageKey 对应一次导航，字段与命令标签只影响展示。
+ * 对话文字保存在组件状态；SDK 的 run/events/streamingText 提供执行证据，不能用文字直接修改业务缓存。
+ * 展开时更新性格列表并恢复输入焦点；流式计时器在忙碌结束或卸载时释放，自动滚动尊重用户阅读位置。
+ */
+export function AssistantPanel({ context, suggestions, pageKey, fieldLabels = {}, commandLabels = {} }: {
+  context: PageContextInput; suggestions: string[]; pageKey: string; fieldLabels?: Record<string, string>; commandLabels?: Record<string, string>;
+}) {
+  // 会话属于工作台，页面身份属于一次导航；新的页面不能覆盖已经发送的快照。
+  const pageRef = useRef<{ key: string; value: AiPageContext } | null>(null);
+  if (pageRef.current?.key !== pageKey) pageRef.current = { key: pageKey, value: new AiPageContext(context) };
+  pageRef.current.value.update(context);
+  const page = pageRef.current.value, assistant = useAssistant(client.ai, page), cache = useQueryClient();
+  const [open, setOpen] = useState(false), [unread, setUnread] = useState(false);
+  const launcher = useRef<HTMLButtonElement | null>(null), composer = useRef<HTMLTextAreaElement | null>(null), closeButton = useRef<HTMLButtonElement | null>(null);
+  const sentPage = useRef({ instanceId: '', title: '', fieldLabels, commandLabels });
+  const [input, setInput] = useState(''), [messages, setMessages] = useState<{ role: 'user' | 'assistant'; text: string; page?: string; name?: string }[]>([]);
+  const [failure, setFailure] = useState('');
+  const scrollArea = useRef<HTMLDivElement | null>(null), followOutput = useRef(true);
+  const [showLatest, setShowLatest] = useState(false), [elapsed, setElapsed] = useState(0);
+  const interaction = assistant.run?.interactions[0];
+  const streaming = assistant.streamingText;
+  const progress = assistant.progress;
+  const labelTool = (tool: string, name?: string | null) => sentPage.current.commandLabels[name ?? ''] ?? toolLabels[tool] ?? (tool.startsWith('query_') ? '查询业务数据' : '执行业务操作');
+  /**
+   * 按 step 与 callId 合并工具开始/完成事件，只显示最近四项活动。
+   * 这里是过程摘要，失败状态不能被后续自然语言回答覆盖成成功。
+   */
+  const activity = useMemo(() => {
+    const calls = new Map<string, { tool: string; name?: string; status: 'running' | 'completed' | 'failed' }>();
+    for (const event of assistant.events) {
+      const data = event.data as { callId: string; tool: string; name?: string; ok?: boolean; step?: number };
+      const key = `${data.step ?? 0}:${data.callId}`;
+      if (event.type === 'tool.started') calls.set(key, { tool: data.tool, name: data.name, status: 'running' });
+      if (event.type === 'tool.completed') calls.set(key, { ...calls.get(key), tool: data.tool, status: data.ok === false ? 'failed' : 'completed' });
+    }
+    return [...calls.entries()].slice(-4);
+  }, [assistant.events]);
+  const workingLabel = !assistant.run ? '正在发送…' : interaction ? captions[assistant.run.status] ?? '等待你回复' :
+    progress.stage === 'queued' ? '已收到，等待执行' : progress.stage === 'context' ? '正在核对页面与访问权限' :
+    progress.stage === 'tool' && progress.tool ? progress.toolState === 'running' ? `正在${labelTool(progress.tool, progress.toolName)}` : '操作已完成，正在整理结果' :
+    streaming ? '正在生成回复' : '正在分析当前需求';
+  useEffect(() => {
+    if (!assistant.busy) return;
+    const started = Date.now(); setElapsed(0);
+    const timer = setInterval(() => setElapsed(Math.floor((Date.now() - started) / 1000)), 1000);
+    return () => clearInterval(timer);
+  }, [assistant.busy]);
+  useEffect(() => {
+    if (open && followOutput.current && scrollArea.current) scrollArea.current.scrollTop = scrollArea.current.scrollHeight;
+  }, [messages, streaming, assistant.busy, activity, open]);
+  useEffect(() => {
+    if (open) { setUnread(false); void assistant.refreshPersonalities(); (composer.current?.disabled ? closeButton.current : composer.current)?.focus({ preventScroll: true }); }
+  }, [open]);
+  useEffect(() => { if (!open && (streaming || interaction)) setUnread(true); }, [streaming, interaction, open]);
+  /**
+   * 收起面板并将焦点交回启动按钮；保留会话与在途任务，显式停止应调用 SDK cancel。
+   */
+  function close() { setOpen(false); launcher.current?.focus({ preventScroll: true }); }
+  const preview = (interaction?.data ?? {}) as Record<string, any>;
+  const fields = (preview.input ?? (preview.key ? { key: preview.key, value: preview.value } : { outcome: preview.outcome, comment: preview.comment })) as Record<string, unknown>;
+  const append = (role: 'user' | 'assistant', text: string, page?: string, name?: string) => setMessages(old => [...old, { role, text, page, name }]);
+  /**
+   * 统一等待发送、回复或停止操作，将最终回答追加到本地对话，并在返回后刷新业务查询。
+   * failed/expired 给出未完成提示，取消类异常不重复显示普通请求失败；其他异常展示原因。
+   * 刷新读取服务端真实结果，不使用模型回复拼造已保存记录。
+   */
+  async function execute(action: () => Promise<AiRun | undefined>) {
+    setFailure('');
+    try {
+      const result = await action();
+      if (result?.answer) append('assistant', result.answer, undefined, result.personality?.label);
+      if (result && ['failed', 'expired'].includes(result.status)) setFailure(`执行未完成（${result.error ?? result.status}），可以重试或交由人工处理。`);
+      // 命令成功后由服务端重新读取记录，页面不会用模型文本假装更新了业务对象。
+      await cache.invalidateQueries();
+    } catch (error) {
+      if (!(error instanceof Error && (error.message === 'CANCELLED' || error.name === 'AbortError'))) setFailure(error instanceof Error ? error.message : '请求失败，请重试');
+    }
+  }
+  /**
+   * 仅在文本非空且没有运行、性格切换或待回复交互时开启一轮。
+   * 保存发送页面身份与标签；上一轮失败或取消的部分文本保留为历史，新的输入经 SDK 创建运行。
+   */
+  function send(message: string) {
+    if (!message.trim() || assistant.busy || assistant.personalityBusy || interaction) return;
+    if (streaming && ['cancelled', 'failed', 'expired'].includes(assistant.run?.status ?? '')) append('assistant', streaming, undefined, assistant.run?.personality?.label);
+    sentPage.current = { instanceId: page.pageInstanceId, title: context.page.title, fieldLabels, commandLabels };
+    followOutput.current = true; setShowLatest(false); append('user', message, context.page.title); setInput('');
+    void execute(() => assistant.send(message));
+  }
+  /**
+   * 拦截原生提交。等待 input 交互时提交补充答案，否则发送新问题。
+   * confirmation/page_context 由各自按钮处理，避免普通输入绕过确认或替换已持久化计划。
+   */
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    if (assistant.busy || assistant.personalityBusy) return;
+    if (interaction?.kind === 'input') {
+      const answer = input.trim(); if (!answer) return;
+      append('user', answer); setInput('');
+      void execute(() => assistant.respond(interaction.id, { answer }));
+    } else send(input);
+  }
+  return <div className="assistant-dock">
+    <section id="workspace-assistant" className="assistant-panel" role="dialog" aria-modal="false" aria-labelledby="assistant-title" hidden={!open} onKeyDown={event => {
+      if (event.key === 'Escape') { event.stopPropagation(); close(); }
+    }}>
+    <div className="assistant-heading">
+      <span className="assistant-emblem">{assistant.personality ? <span className="assistant-personality-avatar" aria-hidden="true">{assistant.personality.avatar}</span> : <AssistantMark />}</span>
+      <div><span className="assistant-wordmark">CAGE / ASSISTANT</span><h2 id="assistant-title">{assistant.personality?.label ?? '业务助理'}<span>AI</span></h2></div>
+      <button ref={closeButton} className="assistant-close" onClick={close} aria-label="收起助理" title="收起 · Esc"><svg viewBox="0 0 20 20" fill="none" aria-hidden="true"><path d="m5 8 5 5 5-5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg></button>
+    </div>
+    <div className="assistant-personality"><label htmlFor="assistant-personality-select">相处方式</label><select id="assistant-personality-select" aria-label="助理性格" value={assistant.personalityKey ?? ''}
+      disabled={assistant.busy || assistant.personalityBusy || !assistant.personalities.length} onChange={event => {
+        void assistant.setPersonality(event.target.value || null).catch(() => {});
+      }}><option value="">跟随默认{assistant.personalities.find(p => p.key === assistant.defaultPersonalityKey) ? ` · ${assistant.personalities.find(p => p.key === assistant.defaultPersonalityKey)!.label}` : ''}</option>
+      {assistant.personalityKey && !assistant.personalities.some(p => p.key === assistant.personalityKey) && <option value={assistant.personalityKey}>已停用，请重新选择</option>}
+      {assistant.personalities.map(p => <option key={p.key} value={p.key}>{p.avatar} {p.label}</option>)}
+    </select><small>{assistant.personalityBusy ? '切换中…' : '下条消息生效'}</small></div>
+    {assistant.personalityError && <p className="assistant-personality-error" role="alert">性格配置暂不可用。<button onClick={() => void assistant.refreshPersonalities()}>重新读取</button></p>}
+    <div className="assistant-context"><span className="assistant-context-dot" /><span>当前页面</span><strong>{context.page.title}</strong>{context.draft && <small>含未保存内容</small>}</div>
+    <div className="assistant-messages" ref={scrollArea} role="log" aria-live="polite" aria-atomic="false" onScroll={e => {
+      const area = e.currentTarget;
+      followOutput.current = area.scrollHeight - area.scrollTop - area.clientHeight < 64;
+      setShowLatest(!followOutput.current);
+    }}>
+      {!messages.length && <div className="assistant-empty"><span className="assistant-greeting">就在这里，帮你多走一步。</span><h3>有什么可以<br />一起处理的？</h3><p>查数据、看进度，或梳理一项操作。<br />我会结合你正在浏览的页面来回答。</p>
+        <div className="assistant-suggestions">{suggestions.map((text, index) => <button key={text} disabled={assistant.busy || assistant.personalityBusy || !!interaction} onClick={() => send(text)}><span className="assistant-suggestion-no">0{index + 1}</span><span>{text}</span><span aria-hidden="true">↗</span></button>)}</div>
+      </div>}
+      {messages.map((message, index) => <div key={index} className={`assistant-message ${message.role === 'user' ? 'assistant-user' : 'assistant'}`}><small>{message.role === 'user' ? '你' : message.name ?? '业务助理'}{message.page && <span className="assistant-message-page">{message.page}</span>}</small>{message.role === 'assistant' ? <AssistantMarkdown>{message.text}</AssistantMarkdown> : <p className="assistant-user-text">{message.text}</p>}</div>)}
+      {!!activity.length && <ol className="assistant-activity" aria-label="本轮执行过程">{activity.map(([id, action]) => <li key={id} data-status={action.status}>
+        <span className="assistant-activity-dot" aria-hidden="true">{action.status === 'completed' ? '✓' : action.status === 'failed' ? '!' : '·'}</span>
+        <span>{labelTool(action.tool, action.name)}</span><small>{action.status === 'completed' ? '已完成' : action.status === 'failed' ? '未完成' : interaction ? '待确认' : '进行中'}</small>
+      </li>)}</ol>}
+      {(assistant.busy || (streaming && ['cancelled', 'failed', 'expired'].includes(assistant.run?.status ?? ''))) && <div className="assistant-message assistant" aria-busy={assistant.busy}>
+        <small>{assistant.run?.personality?.label ?? '业务助理'}{assistant.busy && <span className="assistant-live-dot" aria-label="正在回复" />}</small>
+        {streaming ? <AssistantMarkdown>{streaming}</AssistantMarkdown> : <p className="assistant-pending">{workingLabel}</p>}
+      </div>}
+    {interaction && <div className="assistant-confirm">
+      <strong>{interaction.kind === 'confirmation' ? sentPage.current.commandLabels[String(preview.command)] ?? '确认这次操作' : interaction.prompt}</strong>
+      {interaction.kind === 'confirmation' && <>
+        {preview.subject?.id && <p className="muted">目标单据：{String(preview.subject.id).slice(0, 8).toUpperCase()} · 当前版本 {preview.subject.version}</p>}
+        <dl>{Object.entries(fields).filter(([key, value]) => key !== 'id' && value !== undefined).map(([key, value]) => <div key={key}><dt>{sentPage.current.fieldLabels[key] ?? key}</dt><dd>{typeof value === 'object' ? JSON.stringify(value) : String(value)}</dd></div>)}</dl>
+        <div className="actions"><button className="primary" disabled={assistant.busy || assistant.personalityBusy} onClick={() => void execute(() => assistant.respond(interaction.id, { approved: true }))}>确认执行</button><button disabled={assistant.busy || assistant.personalityBusy} onClick={() => void execute(() => assistant.respond(interaction.id, { approved: false }))}>不执行</button></div>
+      </>}
+      {interaction.kind === 'page_context' && (sentPage.current.instanceId === page.pageInstanceId
+        ? <button disabled={assistant.busy || assistant.personalityBusy} onClick={() => void execute(() => assistant.respond(interaction.id, { pageContext: page.snapshot() }))}>提供当前页面内容</button>
+        : <p>本轮来自「{sentPage.current.title}」。页面已切换，请停止本轮后，结合新页面重新提问。</p>)}
+    </div>}
+    {failure && <p className="error" role="alert">{failure}</p>}
+    </div>
+    {showLatest && <button className="assistant-latest" onClick={() => {
+      followOutput.current = true; setShowLatest(false); if (scrollArea.current) scrollArea.current.scrollTop = scrollArea.current.scrollHeight;
+    }}>回到最新回复 ↓</button>}
+    {(assistant.busy || assistant.run) && <div className="assistant-status-row"><p className="assistant-status" role="status"><span>{assistant.busy ? workingLabel : captions[assistant.run!.status]}</span>
+      {assistant.busy && <span aria-hidden="true">{elapsed}s</span>}{!!assistant.run?.toolCalls && <span>完成 {assistant.run.toolCalls} 项操作</span>}
+    </p>{(assistant.busy || interaction) && <button className="assistant-stop" onClick={() => void execute(() => assistant.cancel())}>停止本轮</button>}</div>}
+    <form className="assistant-compose" onSubmit={submit}><label htmlFor="assistant-message-input" className="assistant-input-label">{interaction?.kind === 'input' ? '补充信息' : '向助理提问'}</label><div className="assistant-input-box"><textarea ref={composer} id="assistant-message-input" value={input} onChange={e => setInput(e.target.value)} rows={2} placeholder="说说你想处理的事…" maxLength={16000} disabled={assistant.busy || (!!interaction && interaction.kind !== 'input')} onKeyDown={event => {
+      if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing) { event.preventDefault(); event.currentTarget.form?.requestSubmit(); }
+    }} /><button className="assistant-send" aria-label="发送消息" title="发送 · Enter" disabled={assistant.busy || assistant.personalityBusy || !input.trim() || (!!interaction && interaction.kind !== 'input')}><svg viewBox="0 0 20 20" fill="none" aria-hidden="true"><path d="M10 15V5m-4 4 4-4 4 4" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" /></svg></button></div><div className="assistant-compose-note"><span>结合当前页面 · 操作前确认</span><span>Shift + Enter 换行</span></div></form>
+    </section>
+    <button ref={launcher} className={`assistant-launcher${open ? ' is-open' : ''}`} aria-label={open ? '收起业务助理' : '打开业务助理'} aria-expanded={open} aria-controls="workspace-assistant" onClick={() => open ? close() : setOpen(true)}>
+      <span className="assistant-launcher-mark"><AssistantMark /></span><span><strong>业务助理</strong><small>{assistant.busy ? '正在处理你的问题' : interaction ? '有一项操作待确认' : unread ? '有新的回复' : '随时为你解答'}</small></span><span className="assistant-launcher-indicator" data-active={assistant.busy || unread || !!interaction} />
+    </button>
+  </div>;
+}

package/templates/app/apps/web/src/shared/ui/assistant-scope.tsx

@@ -0,0 +1,72 @@
+/**
+ * 工作台助理的页面上下文注册层：保持一个面板实例，同时按导航身份切换页面语义。
+ * 页面只提交显式可见内容与草稿；工具发现、授权和数据读取仍由客户端及服务端完成。
+ */
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useState, type ReactNode } from 'react';
+import { can, type PageContextInput } from '@yss123/cage-client';
+import { AssistantPanel } from './assistant-panel';
+
+/**
+ * 页面提供给助理的上下文与展示配置，不授予模型任何新能力。
+ */
+export interface AssistantPageOptions {
+  /**
+   * 当前页面的显式语义快照；未保存输入应置于 draft，不能冒充数据库事实。
+   */
+  context: PageContextInput;
+  /**
+   * 初次打开面板时可点击的建议问题，只是输入文案，不自动执行操作。
+   */
+  suggestions: string[];
+  /**
+   * 可选字段中文名表，用于确认预览；缺失时按字段键显示。
+   */
+  fieldLabels?: Record<string, string>;
+  /**
+   * 可选完整命令名到展示名映射，不改变服务端实际调用的命令。
+   */
+  commandLabels?: Record<string, string>;
+}
+/**
+ * owner 标识注册者；options 为 null 表示释放自己的上下文，不能删除另一个页面的新注册。
+ */
+type RegisterPage = (owner: symbol, options: AssistantPageOptions | null) => void;
+const Registration = createContext<RegisterPage | null>(null);
+
+/** 应用壳只挂载一个助理，切页和收起都不卸载正在进行的对话。 */
+/**
+ * 在应用壳包裹 children，并渲染单个 AssistantPanel。
+ * pageKey 是本次导航身份，fallback 是页面尚未注册时的安全兜底上下文。
+ * 注册结果仅在 pageKey 匹配时使用；切页立即采用 fallback，避免加载期间将旧单据带入新问题。
+ */
+export function AssistantScope({ pageKey, fallback, children }: {
+  pageKey: string; fallback: AssistantPageOptions; children: ReactNode;
+}) {
+  const [registered, setRegistered] = useState<{ owner: symbol; pageKey: string; options: AssistantPageOptions } | null>(null);
+  const register = useCallback<RegisterPage>((owner, options) => {
+    setRegistered(previous => options ? { owner, pageKey, options } : previous?.owner === owner ? null : previous);
+  }, [pageKey]);
+  // 切页的同一次渲染立即弃用旧页面信息，避免新页面加载时携带上一张单据。
+  const current = registered?.pageKey === pageKey ? registered.options : fallback;
+  return <Registration.Provider value={register}>
+    {children}
+    {can('Sys.ai.use') && <AssistantPanel {...current} pageKey={pageKey} />}
+  </Registration.Provider>;
+}
+
+/** 页面仅声明自己的语义上下文；不渲染第二个面板，也不读取其他业务模块。 */
+/**
+ * 页面通过此无 UI 组件登记 options。序列化内容变化后在 layout effect 中重新注册，卸载时释放本 owner。
+ * Symbol owner 防止旧页面的清理覆盖新页面注册；应放在 AssistantScope 内使用。
+ */
+export function AssistantPage(options: AssistantPageOptions) {
+  const register = useContext(Registration);
+  const owner = useMemo(() => Symbol('assistant-page'), []);
+  const serialized = JSON.stringify(options);
+  useLayoutEffect(() => {
+    if (!register) return;
+    register(owner, JSON.parse(serialized));
+    return () => register(owner, null);
+  }, [register, owner, serialized]);
+  return null;
+}

package/templates/app/apps/web/src/shared/ui/attachment-upload.css

@@ -0,0 +1,28 @@
+/**
+ * 附件选择、上传进度与恢复会话列表的局部样式，类名前缀限制对其他表单的影响。
+ * 透明原生文件 input 覆盖选择区域，保留系统文件选择行为；focus-within 让键盘定位仍可见。
+ */
+.attachment-upload { margin: 20px 0; border-top: 1px solid var(--line, #e3e5df); padding-top: 18px; }
+.attachment-heading, .attachment-row, .attachment-progress { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
+.attachment-heading { margin-bottom: 10px; }
+.attachment-picker { position: relative; display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 16px; border: 1px dashed #a9b8aa; border-radius: 8px; background: #f5f8f2; cursor: pointer; }
+/**
+ * 隐藏原生输入的外观但保留可点击区域和文件选择语义，不使用 display:none 移除交互。
+ */
+.attachment-picker input, .attachment-resume input { position: absolute; inset: 0; width: 100%; height: 100%; opacity: 0; cursor: pointer; }
+.attachment-picker:focus-within, .attachment-resume:focus-within { outline: 2px solid #3c6c48; outline-offset: 3px; }
+.attachment-picker small, .attachment-hint, .attachment-progress { font-size: 12px; }
+.attachment-hint { margin: 8px 0 12px; }
+.attachment-row { padding: 8px 0; min-width: 0; }
+.attachment-row > span, .attachment-row > a { overflow-wrap: anywhere; }
+.attachment-task { padding: 8px 0; border-bottom: 1px solid var(--line, #e3e5df); }
+.attachment-task progress { display: block; width: 100%; height: 6px; accent-color: #3c6c48; }
+.attachment-progress { margin-top: 8px; color: #687066; font-variant-numeric: tabular-nums; }
+.attachment-error { color: #a33b30; font-size: 13px; }
+.attachment-recovery { margin-top: 14px; padding: 12px; background: #f6f4ed; border-radius: 8px; font-size: 13px; }
+.attachment-recovery > p { margin: 6px 0; }
+.attachment-resume { position: relative; display: inline-flex; padding: 6px 10px; border: 1px solid #c5c9bf; border-radius: 5px; cursor: pointer; white-space: nowrap; }
+/**
+ * 窄屏将文件选择说明和操作拆行，长文件名允许折行，避免上传及取消按钮溢出。
+ */
+@media (max-width: 600px) { .attachment-picker { align-items: flex-start; flex-direction: column; } .attachment-row { flex-wrap: wrap; } }

package/templates/app/apps/web/src/shared/ui/attachment-upload.tsx

@@ -0,0 +1,163 @@
+/**
+ * 受控附件选择与可恢复上传界面，连接客户端分片任务、上传会话查询和父表单的附件 ID。
+ * 上传 ready 仅说明字节准备完成，正式绑定到业务记录仍需调用方提交领域命令。
+ * 本地校验用于及时反馈，文件策略、归属与下载权限始终由服务端重新检查。
+ */
+// 文件上传与业务保存分开：这里只产出已完成的 ID，最终关联仍由调用方的领域命令提交。
+import { useEffect, useRef, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { client, useFileUpload, type FileUploadTask, type UploadSession } from '@app/contracts';
+import './attachment-upload.css';
+
+/**
+ * 上传组件契约：父组件持有附件草稿，上传任务状态在本组件内维护。
+ */
+interface Props {
+  /**
+   * 最终绑定附件的完整命令名，供服务端验证上传用途及调用能力。
+   */
+  command: string;
+  /**
+   * 该命令目标聚合上的文件字段名，必须匹配生成的字段策略。
+   */
+  field: string;
+  /**
+   * 编辑已有记录时的目标 UUID；创建命令尚无记录时省略。
+   */
+  targetId?: string;
+  /**
+   * 由生成契约提供的策略：maxBytes 为字节上限，maxCount 缺省按单附件，accept 为允许的 MIME 列表。
+   */
+  policy: { maxBytes: number; maxCount?: number; accept: readonly string[] };
+  /**
+   * 父表单当前选择的已准备附件 ID；不是服务端已经保存的关联证明。
+   */
+  value: string[];
+  /**
+   * 附件新增或移除时回传完整 ID 列表，父表单决定何时提交。
+   */
+  onChange: (ids: string[]) => void;
+  /**
+   * 当任一任务处于上传流程时通知父表单，以便阻止不完整附件的保存。
+   */
+  onBusyChange: (busy: boolean) => void;
+}
+/**
+ * 以 1024 为单位换算文件大小供展示；输入为字节，不参与服务端大小限制判断。
+ */
+const size = (bytes: number) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : bytes >= 1024 ** 2 ? `${(bytes / 1024 ** 2).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`;
+
+/**
+ * 按 id 查询可访问的文件元信息，成功后提供受服务端鉴权的下载地址。
+ * 加载与不可访问分别提示；不通过存储内部路径绕过下载权限。
+ */
+export function FileLink({ id }: { id: string }) {
+  const query = useQuery({ queryKey: ['file-info', id], queryFn: async () => {
+    const result = await client.fileInfo(id);
+    if (!result.ok) throw new Error(result.code);
+    return result.data;
+  } });
+  if (query.isPending) return <span className="muted">正在读取附件…</span>;
+  if (query.isError) return <span role="status">附件不可访问</span>;
+  return <a href={client.fileDownloadUrl(id)}>{query.data.filename} <small className="muted">{size(query.data.bytes)}</small></a>;
+}
+
+/**
+ * 先读取匹配 command/field/targetId 的可恢复会话，再创建或继续本地文件任务。
+ * 通过 refs 读取最新父表单值及任务列表，卸载时 dispose 已创建任务；取消/删除业务关联不是卸载的隐含效果。
+ * 父组件负责保存 value；移除选中项只改变草稿，不直接删除服务端已绑定文件。
+ */
+export function AttachmentUpload(props: Props) {
+  const { command, field, targetId, policy, value, onChange, onBusyChange } = props;
+  const current = useRef(props); current.current = props;
+  const [tasks, setTasks] = useState<{ key: number; file: File; task: FileUploadTask }[]>([]);
+  const [error, setError] = useState('');
+  const sequence = useRef(0), tasksRef = useRef(tasks); tasksRef.current = tasks;
+  const [active, setActive] = useState<Record<number, boolean>>({});
+  const pending = useQuery({ queryKey: ['file-uploads', command, field, targetId], queryFn: async () => {
+    const result = await client.uploadSessions({ command, field, targetId });
+    if (!result.ok) throw new Error(result.code);
+    return result.data;
+  } });
+  useEffect(() => { onBusyChange(Object.values(active).some(Boolean)); }, [active, onBusyChange]);
+  useEffect(() => () => { for (const entry of tasksRef.current) entry.task.dispose(); }, []);
+
+  /**
+   * 校验选中文件数量、字节大小和 MIME 后构造上传任务；session 可指定待续传的会话。
+   * 数量同时计入已选附件与未结束任务，续传时实际文件内容匹配由 SDK/服务端验证。
+   */
+  function add(files: FileList | null, session?: UploadSession) {
+    if (!files?.length) return;
+    setError('');
+    const maximum = policy.maxCount ?? 1;
+    const working = tasks.filter(entry => !['completed', 'cancelled'].includes(entry.task.getSnapshot().status)).length;
+    if (value.length + working + files.length > maximum) { setError(`最多选择 ${maximum} 个附件，请先取消多余任务。`); return; }
+    for (const file of Array.from(files)) {
+      if (file.size < 1 || file.size > policy.maxBytes || !policy.accept.includes(file.type || 'application/octet-stream')) {
+        setError(`“${file.name}”的大小或类型不符合要求。`); continue;
+      }
+      const task = client.upload(file, { command, field, targetId }, { uploadId: session?.id });
+      const key = ++sequence.current;
+      setActive(previous => ({ ...previous, [key]: true }));
+      setTasks(previous => [...previous, { key, file, task }]);
+    }
+  }
+  /**
+   * 把已准备的上传 ID 纳入当前父表单草稿；读取最新 props，拒绝重复项及超过数量上限。
+   * 名字表示采用完成结果，此函数是事件处理器，不是 React hook。
+   */
+  function useCompleted(id: string) {
+    const { value, onChange, policy } = current.current;
+    if (value.includes(id)) return;
+    if (value.length >= (policy.maxCount ?? 1)) { setError('附件数量已达到上限，请移除后重试。'); return; }
+    onChange([...value, id]);
+  }
+  const taskIds = new Set(tasks.map(entry => entry.task.getSnapshot().id));
+  const recoverable = (pending.data ?? []).filter(session => !value.includes(session.id) && !taskIds.has(session.id));
+  return <div className="attachment-upload">
+    <div className="attachment-heading"><strong>附件</strong><span className="muted">{value.length} / {policy.maxCount ?? 1}</span></div>
+    <label className="attachment-picker">
+      <span>＋ 选择文件</span>
+      <input type="file" multiple={(policy.maxCount ?? 1) > 1} accept={policy.accept.join(',')} disabled={value.length >= (policy.maxCount ?? 1)}
+        onChange={event => { add(event.target.files); event.target.value = ''; }} />
+      <small>支持暂停与续传 · 单文件最大 {size(policy.maxBytes)}</small>
+    </label>
+    <p className="muted attachment-hint">上传完成后，保存记录才会正式关联；未完成的上传可以稍后恢复。</p>
+    {error && <p role="alert" className="attachment-error">{error}</p>}
+    {value.map(id => <div className="attachment-row" key={id}><FileLink id={id} /><button type="button" onClick={() => onChange(value.filter(item => item !== id))}>移除</button></div>)}
+    {tasks.map(entry => value.includes(entry.task.getSnapshot().id ?? '') ? null : <UploadRow key={entry.key} file={entry.file} task={entry.task}
+      onDone={id => { setActive(previous => ({ ...previous, [entry.key]: false })); useCompleted(id); }} onBusy={busy => setActive(previous => previous[entry.key] === busy ? previous : ({ ...previous, [entry.key]: busy }))} />)}
+    {recoverable.length > 0 && <div className="attachment-recovery"><strong>可恢复的上传</strong><p className="muted">继续上传时，请重新选择原文件；已完成部分会先核对内容。</p>
+      {recoverable.map(session => <div className="attachment-row" key={session.id}><span>{session.filename} <small className="muted">{size(session.bytes)}</small></span><div className="actions">
+        {session.status === 'ready' ? <button type="button" onClick={() => useCompleted(session.id)}>使用附件</button> : <label className="attachment-resume">选择原文件续传<input type="file" onChange={event => { add(event.target.files, session); event.target.value = ''; }} /></label>}
+        <button type="button" onClick={async () => { const result = await client.cancelUpload(session.id); if (result.ok) void pending.refetch(); else setError('取消失败，请重试。'); }}>取消</button>
+      </div></div>)}
+    </div>}
+    {pending.isError && <p role="status" className="muted">暂时无法查询可恢复任务。<button type="button" onClick={() => void pending.refetch()}>重试</button></p>}
+  </div>;
+}
+
+/**
+ * 订阅单个 FileUploadTask，挂载后启动，向父组件报告 busy 与完成 ID。
+ * 进度使用 confirmedBytes；暂停/继续/取消交给 SDK，失败从订阅快照显示。
+ * start/cancel 的 Promise 失败在这里不另行抛到页面，错误可见性依赖任务状态；资源释放由外层统一处理。
+ */
+function UploadRow({ file, task, onDone, onBusy }: { file: File; task: FileUploadTask; onDone: (id: string) => void; onBusy: (busy: boolean) => void }) {
+  const state = useFileUpload(task);
+  const callbacks = useRef({ onDone, onBusy }); callbacks.current = { onDone, onBusy };
+  const busy = ['initializing', 'verifying', 'uploading', 'completing'].includes(state.status);
+  const start = () => { void task.start().then(session => callbacks.current.onDone(session.id)).catch(() => {}); };
+  useEffect(() => { start(); }, [task]);
+  useEffect(() => { callbacks.current.onBusy(busy); }, [busy]);
+  const labels = { idle: '等待上传', initializing: '准备上传', verifying: '核对已上传内容', uploading: '上传中', paused: '已暂停', completing: '校验与合并中', completed: '上传完成', failed: '上传失败，可重试', cancelled: '已取消' };
+  if (state.status === 'cancelled') return null;
+  return <div className="attachment-task"><div className="attachment-row"><span>{file.name}</span><div className="actions">
+    {busy && state.status !== 'completing' && <button type="button" onClick={() => task.pause()}>暂停</button>}
+    {['paused', 'failed', 'completed'].includes(state.status) && <button type="button" onClick={state.status === 'completed' && state.id ? () => onDone(state.id!) : start}>{state.status === 'completed' ? '使用附件' : '继续'}</button>}
+    <button type="button" onClick={() => { void task.cancel().catch(() => {}); }}>取消</button>
+  </div></div>
+    <progress aria-label={`${file.name} 上传进度`} max={state.totalBytes} value={state.confirmedBytes} />
+    <div className="attachment-progress" role="status"><span>{labels[state.status]}</span><span>{size(state.confirmedBytes)} / {size(state.totalBytes)}{state.bytesPerSecond > 0 ? ` · ${size(state.bytesPerSecond)}/s` : ''}</span></div>
+    {state.error && <p className="attachment-error">{({ NETWORK: '网络中断，已上传内容会保留。', TIMEOUT: '请求超时，可继续重试。', FORBIDDEN: '权限不足，请联系管理员。', UNAUTHENTICATED: '登录已失效，请重新登录。', NOT_FOUND: '上传会话或业务记录不可访问。', INVALID_INPUT: '文件不符合要求，请重新选择。', CONFLICT: '上传状态有变化，请稍后重试。', RATE_LIMITED: '上传配额或请求次数已达上限，请稍后重试。' } as Record<string, string>)[state.error] ?? state.error}</p>}
+  </div>;
+}

package/templates/app/apps/web/src/shared/ui/notice.tsx

@@ -0,0 +1,20 @@
+/**
+ * 业务操作结果的可关闭提示，内容和关闭状态由页面或 useCommand 持有。
+ */
+import type { ReactNode } from 'react';
+
+/** 通用提示容器只负责呈现；提示文案和关闭后的业务行为由调用页面决定。 */
+/**
+ * 呈现 children 消息并在关闭按钮点击时调用 onClose。
+ * 仅关闭提示，不回滚已经提交的命令，也不取消正在运行的任务。
+ */
+export function Notice({ children, onClose }: { children: ReactNode; onClose: () => void }) {
+  return (
+    <div role="status" className="notice">
+      {children}
+      <button onClick={onClose} aria-label="关闭提示">
+        ×
+      </button>
+    </div>
+  );
+}

package/templates/app/apps/web/src/shared/ui/page-heading.tsx

@@ -0,0 +1,35 @@
+/**
+ * 业务页公共标题区，统一标题、说明与右侧操作的布局，不包含查询和权限逻辑。
+ */
+import type { ReactNode } from 'react';
+
+/** 统一页面标题的排版；不读取路由或业务状态，避免共享 UI 反向依赖某项业务。 */
+/**
+ * 展示 eyebrow 分类文字、title 主标题、description 说明和 children 操作区。
+ * 操作按钮及其 can 检查由使用页面提供；此组件不会替调用方判断权限。
+ */
+export function PageHeading({
+  eyebrow,
+  title,
+  description,
+  children,
+}: {
+  eyebrow: string;
+  title: string;
+  description: string;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="page-title">
+      <div>
+        <span className="eyebrow">{eyebrow}</span>
+        <h1>
+          {title}
+          <span className="title-dot">.</span>
+        </h1>
+        <p className="muted">{description}</p>
+      </div>
+      {children}
+    </div>
+  );
+}

package/templates/app/apps/web/src/shared/ui/page-state.css

@@ -0,0 +1,47 @@
+/**
+ * 共享页面状态卡与返回链接的样式，采购和空白模板均由同步流程取得同一版本。
+ * 颜色变量由应用主题提供；这里只排版标题、说明和操作，具体错误分类由 PageState/QueryFailure 决定。
+ */
+/* 与两套工作台共享的纸面状态卡；状态清楚可读，链接保持可聚焦和可复制。 */
+.route-state {
+  margin: 32px 0;
+  padding: 68px 36px;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #fdfefb;
+  text-align: center;
+}
+.route-state-mark {
+  display: block;
+  margin-bottom: 20px;
+  color: #7d9866;
+  font:
+    italic 42px Georgia,
+    serif;
+}
+.route-state h1 {
+  font-size: 26px;
+  letter-spacing: -0.5px;
+}
+.route-state p {
+  margin: 16px 0 26px;
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.9;
+}
+.route-link {
+  display: inline-flex;
+  align-items: center;
+  padding: 10px 16px;
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  background: #f1f5eb;
+  color: var(--green);
+  font-size: 12px;
+}
+.route-link:hover {
+  background: #e4ecd9;
+}
+.route-state > button {
+  margin-left: 12px;
+}