@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/app/apps/web/src/shared/ui/approval-member-picker.tsx

@@ -0,0 +1,51 @@
+/**
+ * 采购参与者共用的审批协作名录选择器，由采购表单和审批管理弹窗消费。
+ * 仅通过生成契约读取 ApprovalMember 安全视图，不读取完整 User 或凭账号名猜测权限。
+ * 目录是公开协作身份，不保证被选者对当前单据有审批权限；实际提交由服务端复核，空/失败不能伪装成可选名单。
+ */
+import { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { approvalMember } from '@app/contracts';
+import { errorMessage } from '../lib/error-message';
+import './approval-member-picker.css';
+
+/**
+ * 在有名录读取权限的界面加载当前页，可按显示名/职责就地筛选；最多读取 200 项，不声称返回完整组织。
+ * page 进入查询缓存键，退出账号时由应用会话层清理；retired 默认不用于选人。
+ */
+export function useApprovalMembers(page = 1, includeRetired = false) {
+  return useQuery({ queryKey: ['approval-members', page, includeRetired], queryFn: async () => {
+    const result = await approvalMember.list({ page, pageSize: 200, ...(includeRetired ? {} : { status: 'active' }) });
+    if (!result.ok) throw new Error(errorMessage(result));
+    return result.data;
+  } });
+}
+
+/**
+ * 单选/多选均输出真实 userId，value 与 onChange 由父表单持有，exclude 只改善体验，不替代服务端重复票检查。
+ * max 限制本次选择数量，已选项始终可取消；翻页保留已选 ID，页面展示本次已选数量。
+ * disabled 用于在父级提交时冻结编辑；刷新与失败保留用户选择，不自动选择或发起写操作。
+ */
+export function ApprovalMemberPicker({ value, onChange, max = 5, exclude = [], disabled = false }: {
+  value: string[]; onChange: (ids: string[]) => void; max?: number; exclude?: string[]; disabled?: boolean;
+}) {
+  const [search, setSearch] = useState(''), [page, setPage] = useState(1);
+  const query = useApprovalMembers(page);
+  const entries = query.data?.items.filter(member => !exclude.includes(member.userId) &&
+    `${member.displayName} ${member.specialty}`.includes(search.trim())) ?? [];
+  return <fieldset className="approval-member-picker" disabled={disabled}>
+    <legend>选择协作人员 · 已选 {value.length}/{max}</legend>
+    <input aria-label="筛选协作人员" placeholder="按姓名或职责筛选当前页" value={search} onChange={event => setSearch(event.target.value)} />
+    {query.isPending && <p role="status">正在读取协作名录…</p>}
+    {query.isError && <p role="alert">{query.error.message} <button type="button" onClick={() => void query.refetch()}>重试</button></p>}
+    <div className="approval-member-options">{entries.map(member => <label key={member.id}>
+      <input type="checkbox" checked={value.includes(member.userId)} disabled={disabled || (!value.includes(member.userId) && value.length >= max && max !== 1)}
+        onChange={event => onChange(event.target.checked ? max === 1 ? [member.userId] : [...value, member.userId] : value.filter(id => id !== member.userId))} />
+      <span><strong>{member.displayName}</strong><small>{member.specialty}</small></span>
+    </label>)}</div>
+    {query.data && entries.length === 0 && <p className="muted">当前页没有匹配人员，请调整筛选或联系名录维护人。</p>}
+    {(query.data?.total ?? 0) > 200 && <div className="actions"><button type="button" disabled={page === 1} onClick={() => setPage(page - 1)}>上一页</button>
+      <span>第 {page} 页</span><button type="button" disabled={page * 200 >= query.data!.total} onClick={() => setPage(page + 1)}>下一页</button></div>}
+    <small className="muted">名录只提供选人信息，处理权限、数据范围和最终额度仍以服务端校验为准。</small>
+  </fieldset>;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 助理输出的 Markdown 展示边界，支持 GFM 表格及链接，并跳过原始 HTML。
+ * 图片转换为纯文字说明，避免模型文本直接触发图片加载；业务状态仍由真实查询呈现。
+ */
+import Markdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+/** 模型文字是不可信内容：支持 Markdown/GFM，不执行 HTML，也不自动加载模型给出的远端图片。 */
+/**
+ * 将 children 中的模型文本渲染为受限 Markdown；外链使用独立窗口和 noopener 等关系属性。
+ * 只负责显示，不执行代码块、不把文本转成业务命令，也不对内容的事实准确性背书。
+ */
+export function AssistantMarkdown({ children }: { children: string }) {
+  return <div className="assistant-markdown"><Markdown remarkPlugins={[remarkGfm]} skipHtml components={{
+    a: ({ children, href }) => <a href={href} target="_blank" rel="noopener noreferrer">{children}</a>,
+    img: ({ alt }) => <span className="assistant-image-label">[图片：{alt || '未提供说明'}]</span>,
+    table: ({ children }) => <div className="assistant-table"><table>{children}</table></div>,
+  }}>{children}</Markdown></div>;
+}

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

@@ -0,0 +1,134 @@
+/**
+ * 业务助理的浮动入口、面板、消息、活动摘要、确认区及输入区样式。
+ * 面板固定在视口并考虑安全区域，内部消息区单独滚动；关闭使用 hidden 属性，组件会话仍由 React 保留。
+ */
+/* 助理独立于页面排版：暖白对话纸面、墨绿工具条，悬浮窗收起后保持会话。 */
+.assistant-dock { position: fixed; z-index: 30; right: max(28px, env(safe-area-inset-right)); bottom: max(24px, env(safe-area-inset-bottom)); color: var(--green); }
+.assistant-launcher { display: flex; align-items: center; gap: 12px; min-height: 60px; padding: 10px 18px 10px 12px; margin-left: auto; border: 1px solid #456459; border-radius: 18px; color: #f4f8e9; background: #153c35; box-shadow: 0 8px 26px #183d3526, inset 0 1px 0 #ffffff14; transition: background .18s, transform .18s; }
+.assistant-launcher:hover { background: #244f43; transform: translateY(-2px); }
+.assistant-launcher.is-open { background: #264d41; }
+.assistant-launcher-mark { width: 35px; height: 35px; padding: 3px; color: #d1eb9f; }
+.assistant-launcher svg, .assistant-emblem svg { display: block; width: 100%; height: 100%; }
+.assistant-launcher strong, .assistant-launcher small { display: block; text-align: left; }
+.assistant-launcher strong { font-size: 13px; font-weight: 600; letter-spacing: 1px; }
+.assistant-launcher small { color: #b9cec1; font-size: 10px; margin-top: 4px; }
+.assistant-launcher-indicator { width: 5px; height: 5px; border-radius: 50%; background: #819e8a; margin-left: 4px; }
+.assistant-launcher-indicator[data-active="true"] { background: #d1eb9f; box-shadow: 0 0 0 4px #d1eb9f1c; }
+.assistant-panel { position: absolute; bottom: 76px; right: 0; width: 440px; height: min(700px, calc(100dvh - 124px)); display: flex; flex-direction: column; overflow: hidden; border: 1px solid #cdd8cd; border-radius: 20px; background: #fcfcf7; box-shadow: 0 20px 80px #1a35252b, 0 3px 12px #1a352510; animation: assistant-reveal .2s ease-out; }
+/**
+ * 显式覆盖面板的 flex 布局，保证 hidden 属性真正隐藏面板，同时不卸载组件或结束任务。
+ */
+.assistant-panel[hidden] { display: none; }
+.assistant-heading { display: flex; align-items: center; gap: 12px; flex-shrink: 0; padding: 19px 22px; color: #fffef6; background: #173d34; }
+.assistant-emblem { width: 36px; height: 36px; color: #d1eb9f; }
+.assistant-personality-avatar { display: grid; place-items: center; height: 36px; font-size: 27px; }
+.assistant-personality { display: flex; align-items: center; gap: 9px; flex-shrink: 0; padding: 9px 20px; border-bottom: 1px solid #e4e9db; background: #f8faf3; font-size: 10px; color: #7b8a70; }
+.assistant-personality label { white-space: nowrap; }
+.assistant-personality select { min-width: 0; flex: 1; border: 1px solid #dce4d2; border-radius: 6px; padding: 5px 7px; font: inherit; font-size: 11px; color: #46613e; background: #fff; }
+.assistant-personality small { white-space: nowrap; font-size: 9px; }
+.assistant-personality-error { padding: 6px 20px; font-size: 10px; color: #976e43; }
+.assistant-personality-error button { padding: 2px 5px; font-size: 10px; }
+.assistant-wordmark { font-size: 8px; letter-spacing: 2px; color: #a7c0ae; }
+.assistant-heading h2 { font-size: 17px; font-weight: 550; margin-top: 4px; letter-spacing: 1px; }
+.assistant-heading h2 > span { display: inline-block; font: 9px Georgia, serif; color: #d1eb9f; border: 1px solid #67826a; padding: 2px 4px; border-radius: 3px; margin-left: 9px; vertical-align: middle; }
+.assistant-close { display: grid; place-items: center; width: 32px; height: 32px; padding: 6px; margin-left: auto; border: 1px solid #48695b; color: #dce8d7; border-radius: 50%; background: transparent; }
+.assistant-close:hover { background: #34584b; }
+.assistant-close svg { width: 20px; height: 20px; }
+.assistant-context { display: flex; align-items: center; gap: 8px; min-height: 41px; padding: 10px 22px; flex-shrink: 0; background: #eef2e7; border-bottom: 1px solid #e0e6d8; font-size: 10px; color: #6f7d64; }
+.assistant-context-dot { width: 5px; height: 5px; flex-shrink: 0; border-radius: 50%; background: #72904f; }
+.assistant-context strong { color: #3c573d; font-size: 11px; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.assistant-context small { margin-left: auto; font-size: 9px; color: #8a7146; white-space: nowrap; }
+/**
+ * flex 子区设 min-height:0 后才可在有限面板高度内滚动；overscroll 限制滚动传播到背后页面。
+ */
+.assistant-messages { flex: 1; min-height: 0; overflow: auto; overscroll-behavior: contain; padding: 24px 20px; scrollbar-width: thin; scrollbar-color: #c9d5c1 transparent; }
+.assistant-empty { padding: 10px 4px 8px; }
+.assistant-greeting { display: block; margin-bottom: 12px; color: #768662; font-size: 10px; letter-spacing: 1px; }
+.assistant-empty h3 { font-family: 'STSong', 'SimSun', 'Noto Serif CJK SC', serif; font-size: 30px; font-weight: 500; line-height: 1.5; letter-spacing: 1px; }
+.assistant-empty > p { margin-top: 14px; color: #73816a; font-size: 12px; line-height: 1.9; }
+.assistant-suggestions { display: grid; gap: 8px; margin-top: 26px; }
+.assistant-suggestions button { display: flex; gap: 10px; align-items: center; padding: 12px 13px; text-align: left; font-size: 12px; line-height: 1.6; border-color: #e0e5d7; border-radius: 8px; background: #ffffffa6; }
+.assistant-suggestions button:hover { background: #edf3e3; border-color: #c6d6b8; }
+.assistant-suggestions button > span:last-child { margin-left: auto; color: #7b9164; }
+.assistant-suggestion-no { font: 10px Georgia, serif; color: #95a285; }
+.assistant-message { margin-bottom: 18px; padding: 14px 15px; border: 1px solid #e1e6d8; border-radius: 4px 14px 14px; background: #fff; }
+.assistant-message.assistant-user { margin-left: 28px; background: #eaf0df; border-color: #e1e8d5; border-radius: 14px 4px 14px 14px; }
+.assistant-message > small { display: flex; align-items: center; gap: 8px; font-size: 10px; color: #718366; }
+.assistant-message-page { margin-left: auto; font-size: 9px; opacity: .85; }
+.assistant-user-text { font-size: 13px; line-height: 1.85; white-space: pre-wrap; overflow-wrap: anywhere; margin-top: 6px; }
+.assistant-pending { color: #718366; font-size: 12px; margin-top: 8px; line-height: 1.8; }
+.assistant-status-row { display: flex; align-items: center; gap: 8px; padding: 8px 22px 0; flex-shrink: 0; }
+.assistant-status { display: flex; flex: 1; flex-wrap: wrap; gap: 4px 9px; color: #7b876f; font-size: 10px; line-height: 1.6; }
+.assistant-status > span:first-child { color: #4e6f41; }
+.assistant-live-dot { width: 5px; height: 5px; border-radius: 50%; background: #81a355; animation: assistant-pulse 1s ease-in-out infinite; }
+.assistant-activity { list-style: none; margin: 0 0 16px; padding: 8px 12px; border-left: 2px solid #c5d3b0; font-size: 11px; display: grid; gap: 8px; }
+.assistant-activity li { display: flex; gap: 8px; align-items: center; color: #51694a; }
+.assistant-activity li > small { margin-left: auto; color: #849176; font-size: 9px; white-space: nowrap; }
+.assistant-activity-dot { width: 12px; color: #789754; }
+.assistant-activity [data-status="failed"] .assistant-activity-dot { color: #a46e3f; }
+.assistant-latest { position: absolute; bottom: 160px; left: 50%; transform: translateX(-50%); padding: 7px 12px; font-size: 11px; border-radius: 20px; background: #fcfdf8; box-shadow: 0 3px 14px #153c3514; white-space: nowrap; }
+/**
+ * 约束模型文字的换行与排版；长代码和表格各自滚动，不能撑破面板宽度。
+ */
+.assistant-markdown { font-size: 13px; line-height: 1.85; overflow-wrap: anywhere; margin-top: 8px; }
+.assistant-markdown > :first-child { margin-top: 0; }
+.assistant-markdown > :last-child { margin-bottom: 0; }
+.assistant-markdown p { margin: 8px 0; white-space: normal; }
+.assistant-markdown h1, .assistant-markdown h2, .assistant-markdown h3, .assistant-markdown h4 { font-family: inherit; font-weight: 600; line-height: 1.6; font-size: 14px; margin: 16px 0 7px; letter-spacing: 0; }
+.assistant-markdown ul, .assistant-markdown ol { padding-left: 21px; margin: 8px 0; }
+.assistant-markdown li { margin: 3px 0; }
+.assistant-markdown li > p { margin: 3px 0; }
+.assistant-markdown strong { font-weight: 650; color: #214b3b; }
+.assistant-markdown a { color: #476a32; text-decoration: underline; text-underline-offset: 3px; }
+.assistant-markdown code { font: 12px/1.65 Consolas, monospace; background: #edf1e5; border-radius: 3px; padding: 2px 4px; }
+.assistant-markdown pre { overflow: auto; padding: 12px 14px; margin: 12px 0; background: #173e35; border-radius: 8px; color: #eff5e5; }
+.assistant-markdown pre code { background: none; padding: 0; white-space: pre; color: inherit; }
+.assistant-markdown blockquote { margin: 10px 0; padding: 1px 12px; border-left: 3px solid #bbce9e; color: #677a5b; }
+.assistant-markdown hr { border: 0; border-top: 1px solid #dee5d7; margin: 16px 0; }
+.assistant-table { overflow-x: auto; margin: 10px 0; }
+.assistant-table table { min-width: 100%; border-collapse: collapse; font-size: 12px; }
+.assistant-table th, .assistant-table td { text-align: left; padding: 7px 10px; border: 1px solid #dde4d5; white-space: normal; }
+.assistant-table th { color: #375536; background: #edf2e6; font-weight: 600; }
+.assistant-markdown input[type="checkbox"] { margin-right: 6px; }
+.assistant-image-label { color: #7b876f; }
+/**
+ * 确认区与普通回答形成视觉区别；是否可以执行、预览数据及确认有效性仍由 SDK 与服务端控制。
+ */
+.assistant-confirm { background: #fff9eb; border: 1px solid #e8d5a4; padding: 16px; border-radius: 10px; margin: 14px 0; font-size: 12px; }
+.assistant-confirm > p { margin-top: 8px; line-height: 1.8; }
+.assistant-confirm dl { margin: 12px 0; }
+.assistant-confirm dl > div { display: grid; grid-template-columns: 80px 1fr; gap: 12px; margin: 9px 0; }
+.assistant-confirm dt { color: #887541; }
+.assistant-confirm dd { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.6; }
+.assistant-confirm .actions { flex-wrap: wrap; }
+.assistant-compose { margin: 0; padding: 14px 18px 15px; flex-shrink: 0; background: #fcfcf7; }
+/**
+ * 视觉隐藏输入标签但保留给辅助技术，避免仅用 placeholder 作为字段名称。
+ */
+.assistant-input-label { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+.assistant-input-box { display: flex; align-items: flex-end; gap: 8px; padding: 11px 10px 10px 13px; border: 1px solid #d6dfcb; border-radius: 12px; background: #fff; box-shadow: 0 2px 5px #153c3504; }
+.assistant-input-box:focus-within { border-color: #9bb47d; box-shadow: 0 0 0 3px #b5cb9126; }
+.assistant-compose textarea { flex: 1; min-width: 0; width: 100%; resize: none; border: 0; outline: 0; background: transparent; color: var(--green); font: inherit; font-size: 13px; line-height: 1.7; padding: 2px 0; }
+.assistant-compose textarea::placeholder { color: #9aa68c; }
+.assistant-send { display: grid; place-items: center; flex-shrink: 0; width: 32px; height: 32px; padding: 6px; border: 0; border-radius: 9px; background: #1c4438; color: #eff6de; }
+.assistant-send:hover { background: #335c43; }
+.assistant-send:disabled { background: #e8eee0; color: #a4b392; opacity: 1; }
+.assistant-send svg { width: 20px; height: 20px; }
+.assistant-compose-note { display: flex; justify-content: space-between; gap: 6px; color: #8a947e; font-size: 9px; margin: 9px 2px 0; }
+.assistant-stop { padding: 4px 0 4px 8px; font-size: 10px; background: none; border: 0; color: #916843; white-space: nowrap; }
+.assistant-panel button:focus-visible, .assistant-launcher:focus-visible { outline: 2px solid #8ca668; outline-offset: 3px; }
+@keyframes assistant-pulse { 50% { opacity: .3; } }
+@keyframes assistant-reveal { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
+/**
+ * 小屏使用视口宽度与动态视口高度约束面板，同时为启动按钮及设备安全区留空间。
+ */
+@media (max-width: 600px) {
+  .assistant-dock { right: max(12px, env(safe-area-inset-right)); bottom: max(12px, env(safe-area-inset-bottom)); }
+  .assistant-panel { width: calc(100vw - 24px); height: min(680px, calc(100dvh - 104px)); bottom: 76px; border-radius: 16px; }
+  .assistant-heading { padding: 16px 18px; }
+  .assistant-messages { padding: 20px 16px; }
+  .assistant-empty h3 { font-size: 27px; }
+  .assistant-launcher { min-height: 56px; }
+  .assistant-compose-note > span:last-child { display: none; }
+}
+@media (prefers-reduced-motion: reduce) { .assistant-live-dot, .assistant-panel { animation: none; } .assistant-launcher { transition: none; } }

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