@ljwei-stak/dsh-model-route-bot 0.66.4 → 0.67.0

package/apps/integration-client/secure-pairing.jsx

@@ -0,0 +1,84 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { parseSecureInvite } from '../../packages/orchestration/src/pairing-invite.mjs'
+import { UiIcon } from './ui-icons.jsx'
+import { PairingQrReader } from './pairing-qr.jsx'
+
+const errors = {
+  PAIRING_CODE_INVALID: '确认码不正确，请核对目标电脑上显示的六位数字。五次错误后邀请码失效。',
+  PAIRING_WINDOW_CLOSED: '邀请码已过期或已关闭，请在目标电脑生成新的邀请码。',
+  PAIRING_PEER_UNVERIFIED: '未能验证目标电脑。请检查地址和网络，并核对设备指纹；不会切换到明文连接。',
+  PAIRING_RESULT_UNKNOWN: '兑换结果尚未确认。保留这份邀请码，点击“继续核对原配对”；宿主会沿用原请求身份。',
+  PAIRING_RESULT_UNRECOVERABLE: '原请求的恢复窗口已结束。请在目标电脑检查已配对设备；若宿主没有保存凭据，使用“撤销旧配对后重新邀请”，再导入新邀请。',
+  PAIRING_DEVICE_ALREADY_COMMITTED: '目标电脑已登记这次配对，宿主未能保存可用凭据。请在目标电脑核对设备，运行 pair-device.cmd -ResetPairing 撤销旧配对并重新邀请；此操作会断开旧配对。',
+  PAIRING_CREDENTIAL_CHANGED: '宿主中已保存的凭据与原配对记录不一致。请核对目标电脑和宿主的设备登记后重新邀请。',
+  PAIRING_ALREADY_REDEEMED: '这份邀请码已经被兑换。请在目标电脑核对已配对设备。',
+  PAIRING_BINDING_REVIEW_REQUIRED: '设备已添加，请在电脑卡片中核对并完成 Bot 授权。',
+  PAIRING_DEVICE_LIMIT: '目标电脑的已配对设备已达上限，请先在目标电脑撤销不再使用的设备。',
+}
+
+export function SecurePairingSetup({ snapshot, dispatch, busy }) {
+  const [text,setText] = useState(''), [code,setCode] = useState(''), [working,setWorking] = useState(false)
+  const [failure,setFailure] = useState(null), [status,setStatus] = useState(''), [clock,setClock] = useState(Date.now())
+  const request = useRef(null), mounted = useRef(true), sequence = useRef(0), active = useRef(false), fileInput=useRef(null)
+  const importSequence = useRef(0)
+  useEffect(() => { mounted.current=true; return () => { mounted.current=false; sequence.current++;importSequence.current++ } }, [])
+  useEffect(() => { const timer=setInterval(()=>setClock(Date.now()),1000); return ()=>clearInterval(timer) }, [])
+  const parsed = useMemo(() => { if (!text.trim()) return {}; try { return { invite:parseSecureInvite(text) } } catch (error) { return { error:error.code } } },[text])
+  const invite = parsed.invite
+  const seconds = invite ? Math.max(0,Math.ceil((invite.expiresAt-clock)/1000)) : 0
+  const probeBotId = snapshot.mainBotId ?? snapshot.bots?.[0]?.id
+  const allowed = invite?.ceiling.hostManagedBots || invite?.ceiling.botIds.includes(probeBotId)
+  const recoverable = request.current !== null && Boolean(failure)
+  const ready = invite && /^\d{6}$/.test(code) && probeBotId && allowed && (seconds>0 || recoverable)
+  const change = value => { importSequence.current++;setText(value); request.current=null; setCode(''); setFailure(null); setStatus('') }
+  const submit = async () => {
+    if (!ready || active.current || busy) return
+    importSequence.current++;active.current=true;setWorking(true);setFailure(null);setStatus('')
+    const epoch=++sequence.current
+    try {
+      if (!request.current) request.current={requestId:[...crypto.getRandomValues(new Uint8Array(16))].map(byte=>byte.toString(16).padStart(2,'0')).join(''),code,invite,probeBotId,
+        expectedRevision:(snapshot.machines?.items??[]).find(item=>item.id===invite.machineId)?.revision??0}
+      const result=await dispatch('machine.pair.invite',request.current,{errorResult:true})
+      if (!result || result.ok===false) throw Object.assign(new Error('配对尚未确认。'),{code:result?.error?.code})
+      if (!mounted.current || epoch!==sequence.current) return
+      setStatus(result.mainBinding?.status==='blocked'
+        ? `设备已安全配对。${errors[result.mainBinding.code]??`Bot 绑定需要处理：${result.mainBinding.code}`}`
+        : '已验证设备并保存连接凭据，Bot 的授权范围已登记。')
+      setText('');setCode('');request.current=null
+    } catch(error) {
+      if (mounted.current && epoch===sequence.current) setFailure({code:error.code,message:errors[error.code]??String(error.message??error)})
+      if (error.code==='PAIRING_CODE_INVALID') request.current=null
+    } finally { active.current=false;if(mounted.current&&epoch===sequence.current)setWorking(false) }
+  }
+  const importFile = async event => {
+    const file=event.target.files?.[0];event.target.value=''
+    if(!file||active.current||recoverable||busy)return
+    const epoch=++importSequence.current
+    if(file.size>16384){setFailure({message:'邀请码文件超过 16 KB。'});return}
+    try{const value=await file.text();if(mounted.current&&epoch===importSequence.current&&!active.current&&!request.current)change(value)}
+    catch{if(mounted.current&&epoch===importSequence.current)setFailure({message:'无法读取邀请码文件。'})}
+  }
+  return <details className="bp-card bp-secure-pairing" open><summary><UiIcon name="computer" />安全配对电脑</summary>
+    <p className="bp-muted">在目标电脑生成两分钟邀请码，扫描或粘贴到这里，再核对确认码与设备指纹。连接后可从 Bot 聊天中的电脑入口打开桌面。</p>
+    <p className="bp-muted">安全配对需要同一预览版 Agent；已有长期配对文件可使用下方兼容入口。</p>
+    {(snapshot.availableActions??[]).includes('machine.pair.invite') ? <div className="bp-form">
+      <PairingQrReader onRead={change} disabled={working||recoverable||busy}/>
+      <label>设备邀请码<textarea rows={3} value={text} disabled={working||recoverable} onChange={event=>change(event.target.value)} autoComplete="off" spellCheck={false} placeholder="粘贴目标电脑生成的 dsh-pairing-invite JSON" /></label>
+      <div className="bp-actions"><button type="button" disabled={working||recoverable||busy} onClick={()=>fileInput.current?.click()}>导入邀请码文件</button><input ref={fileInput} className="bp-pairing-file" aria-label="邀请码文件" type="file" accept=".json,application/json" disabled={working||recoverable} onChange={event=>{void importFile(event)}} /></div>
+      {parsed.error&&<p className="bp-error" role="alert">无法识别这份邀请码。需要 Agent 生成的第 2 版安全配对文件。</p>}
+      {invite&&<section className="bp-pairing-identity" aria-label="核对设备身份"><strong>{invite.name}</strong><code>{invite.endpoint}</code>
+        <label>设备指纹<code>{invite.transport.fingerprint.match(/.{1,8}/g).join(' ')}</code></label>
+        <p>共享目录：{invite.ceiling.roots.join('、')}；允许 {invite.ceiling.tools.length} 项能力。</p>
+        <details><summary>查看允许的能力</summary><p className="bp-muted">{invite.ceiling.tools.join('、')}</p></details>
+        <p className="bp-muted">{invite.ceiling.hostManagedBots?'目标电脑允许本宿主管理团队 Bot，仍受共享目录和能力范围限制。':`仅允许 Bot：${invite.ceiling.botIds.join('、')}`}</p>
+        {!allowed&&<p className="bp-error" role="alert">当前主 Bot 不在目标电脑允许的范围内。</p>}
+        <span role="timer">{seconds>0?`邀请码剩余 ${seconds} 秒`:recoverable?'邀请码已过期；可继续核对已保存凭据的原请求。':'邀请码已过期，请在目标电脑重新生成。'}</span>
+      </section>}
+      <label>目标电脑的六位确认码<input inputMode="numeric" autoComplete="one-time-code" maxLength={6} value={code} disabled={working||recoverable} onChange={event=>{importSequence.current++;setCode(event.target.value.replace(/\D/g,''));request.current=null;setFailure(null)}} placeholder="000000" /></label>
+      <div className="bp-actions"><button type="button" className="bp-button-primary" disabled={!ready||busy||working} onClick={()=>{void submit()}}>{working?'正在验证设备…':recoverable?'继续核对原配对':'验证并配对'}</button>
+        {recoverable&&<button type="button" disabled={working} onClick={()=>change('')}>清除本地表单</button>}</div>
+      {failure&&<p className="bp-error" role="alert">{failure.message}</p>}
+      {status&&<p role="status">{status}</p>}
+    </div>:<p className="bp-muted">宿主尚未提供安全配对操作，请更新 Host 与 Remote Agent。</p>}
+  </details>
+}

package/apps/integration-client/tasks-panel.jsx

@@ -3,6 +3,7 @@ import { TASK_STATES } from './api.mjs'
 import { botAttentionSummary, remoteUncertain } from './bot-attention.mjs'
 import { filterTasks, progressNote, taskProgress, taskIdOf, taskKey, taskTitle, TASK_FILTERS, TASK_EVENTS } from './task-progress.mjs'
 import { UiIcon } from './ui-icons.jsx'
+import { taskBoard } from './workspace-model.mjs'
 
 const Tag = ({ children }) => <span className="bp-tag">{children}</span>
 const date = value => value === null || value === undefined || !Number.isFinite(new Date(value).getTime()) ? '未取得' : new Date(value).toLocaleString('zh-CN')
@@ -33,7 +34,7 @@ function RemoteNotice({ row }) {
   return remote.possiblyApplied === true ? <small>操作已停止，文件可能已改变；重试不会撤销已有变更，请先核对产物。</small> : null
 }
 
-function TaskDetail({ task, inspect, busy, actions, dispatch, onClose, bot, openSession }) {
+function TaskDetail({ task, inspect, busy, actions, dispatch, onClose, bot, openSession, focusAttemptId }) {
   const [history, setHistory] = useState(null), [failure, setFailure] = useState(''), [loading, setLoading] = useState(false)
   const [reload, setReload] = useState(0)
   const ref = useRef(null)
@@ -54,11 +55,21 @@ function TaskDetail({ task, inspect, busy, actions, dispatch, onClose, bot, open
     return () => controller.abort()
   }, [key, task.updatedAt, inspect, actions.includes('task.inspect'), reload])
   const data = history?.task ?? task
+  const requestedAttempt = focusAttemptId && history?.attempts.find(item=>item.attemptId===focusAttemptId)
+  const missingAttempt = Boolean(history && focusAttemptId && !requestedAttempt)
+  const historical = Boolean(focusAttemptId && focusAttemptId!==data.attemptId)
+  const readOnlyDetail = Boolean(task.unloaded && !history || focusAttemptId && (!history || historical || missingAttempt))
+  useEffect(()=>{if(requestedAttempt)ref.current?.querySelector('[data-focused-attempt]')?.scrollIntoView?.({block:'nearest'})},[history,focusAttemptId])
   return <article className="bp-card bp-task-detail" aria-label="任务详情" ref={ref} tabIndex={-1}>
-    <div className="bp-card-title"><div><h2>任务详情</h2><p>{taskTitle(task)}</p></div><button type="button" onClick={onClose}>关闭</button></div>
+    <div className="bp-card-title"><div><h2>任务详情</h2><p>{taskTitle(data)}</p></div><button type="button" onClick={onClose}>关闭</button></div>
     <div className="bp-actions"><Tag>{TASK_STATES[data.state] ?? data.state}</Tag><span>{bot?.name ?? task.botId ?? '未取得归属'}</span>
       {bot?.sessionId && openSession && <button type="button" onClick={() => openSession(bot.sessionId)}>打开 Bot 私聊</button>}
-      <TaskActions row={data} actions={actions} dispatch={dispatch} busy={busy} /></div>
+      {!readOnlyDetail && <TaskActions row={data} actions={actions} dispatch={dispatch} busy={busy} />}</div>
+    {task.unloaded && <p className="bp-muted">原任务未包含在当前列表，详情通过原 Bot 与 Task 编号单独读取。</p>}
+    {missingAttempt && <p role="alert" className="bp-blocked">未找到所选的原执行尝试。请在原 Bot 会话核对执行记录。</p>}
+    {requestedAttempt && <section className="bp-blocked" aria-label="所选原执行尝试"><strong>第 {requestedAttempt.number} 次尝试 · {TASK_STATES[requestedAttempt.state]??requestedAttempt.state}</strong>
+      {historical && <p>此处定位历史尝试，当前任务已进入后续尝试。原记录只读。</p>}
+      <p>开始 {date(requestedAttempt.startedAt)} · 结束 {date(requestedAttempt.finishedAt)}</p><small className="bp-code">{requestedAttempt.attemptId} · {requestedAttempt.operationId}</small></section>}
     <RemoteNotice row={data} />
     <dl className="bp-facts"><Value label="创建">{date(data.createdAt)}</Value><Value label="最近更新">{date(data.updatedAt)}</Value><Value label="期限">{date(data.deadlineAt)}</Value>{data.attribution?.label && <Value label="执行进度">{data.attribution.label}</Value>}</dl>
     <h3>任务时间线</h3>
@@ -68,7 +79,7 @@ function TaskDetail({ task, inspect, busy, actions, dispatch, onClose, bot, open
     {!actions.includes('task.inspect') && <p className="bp-muted">此宿主尚未提供任务时间线，可在下方查看现有收据依据。</p>}
     {history && <>
       <p className="bp-muted">{history.attempts.length} 次执行尝试 · {history.timeline.total} 条日志{history.timeline.truncated ? `，显示最近 ${history.timeline.items.length} 条` : ''}。停止请求需等待原操作确认。</p>
-      <ol className="bp-task-timeline">{history.timeline.items.map(event => <li key={event.seq}>
+      <ol className="bp-task-timeline">{history.timeline.items.map(event => <li key={event.seq} data-focused-attempt={focusAttemptId&&event.attemptId===focusAttemptId?'':undefined}>
         <span className="bp-timeline-dot" aria-hidden="true" /><div><strong>{TASK_EVENTS[event.kind] ?? '任务状态更新'}</strong>
           <small><time>{date(event.at)}</time>{event.attemptNumber != null ? ` · 第 ${event.attemptNumber} 次尝试` : ''}{event.outcome ? ` · ${TASK_STATES[event.outcome] ?? (event.outcome === 'unknown' ? '结果未知' : event.outcome)}` : ''}</small>
           {event.code && <small className="bp-code">{event.code}</small>}</div>
@@ -83,18 +94,29 @@ function TaskDetail({ task, inspect, busy, actions, dispatch, onClose, bot, open
   </article>
 }
 
-export function TaskWorkspace({ snapshot, dispatch, busy, scope, inspect, openSession, routingCard }) {
+export function TaskWorkspace({ snapshot, dispatch, busy, scope, inspect, openSession, routingCard, focus }) {
   const progress = useMemo(() => taskProgress(snapshot), [snapshot])
   const [botId, setBotId] = useState(''), [status, setStatus] = useState('all'), [query, setQuery] = useState('')
   const [expanded, setExpanded] = useState(false), [selection, setSelection] = useState(null)
-  useEffect(() => { setBotId(''); setStatus('all'); setQuery(''); setExpanded(false); setSelection(null) }, [scope])
+  const [view, setView] = useState('list'), [focusMissing, setFocusMissing] = useState(false)
+  useEffect(() => { setBotId(''); setStatus('all'); setQuery(''); setExpanded(false); setSelection(null); setFocusMissing(false) }, [scope])
+  useEffect(() => {
+    if (!focus) return
+    setQuery(''); setStatus(focus.filter ?? 'all'); setBotId(focus.taskId ? '' : focus.botId ?? '')
+    const target = focus.taskId ? progress.items.find(row => taskIdOf(row) === focus.taskId && row.botId === focus.botId) : null
+    const canReadMissing = focus.taskId && focus.botId && inspect && snapshot.availableActions?.includes('task.inspect') && snapshot.bots?.some(bot=>bot.id===focus.botId)
+    setSelection(target ? { scope, key: taskKey(target), attemptId:focus.attemptId } : canReadMissing ? {scope,key:taskKey(focus),attemptId:focus.attemptId,
+      lookup:{botId:focus.botId,taskId:focus.taskId,state:'unloaded',title:'原任务',unloaded:true,attempts:0}} : null)
+    setFocusMissing(Boolean(focus.taskId && !target && !canReadMissing))
+  }, [focus?.version, scope, Boolean(inspect), snapshot.availableActions?.includes('task.inspect')])
   const rows = filterTasks(progress, { botId, status, query })
-  const task = selection && selection.scope === scope ? progress.items.find(row => taskKey(row) === selection.key) : null
+  const task = selection && selection.scope === scope ? progress.items.find(row => taskKey(row) === selection.key) ?? selection.lookup : null
   const actions = snapshot.availableActions ?? []
   const select = row => setSelection({ scope, key: taskKey(row) })
   const attention = expanded ? progress.attention : progress.attention.slice(0, 6)
   const [showPlans, setShowPlans] = useState(false)
   return <>
+    {focusMissing && <p className="bp-blocked" role="status">所选任务不在当前已加载的记录中。请刷新记录，或返回原 Bot 会话核对。</p>}
     <section className="bp-card bp-task-overview" aria-label="多 Bot 任务总览">
       <div className="bp-card-title"><div><h2>团队任务</h2><p className="bp-muted">按 Bot 查看进展，优先处理需要你介入的任务。</p></div><Tag>{progress.items.length} 条已加载</Tag></div>
       {snapshot.tasks.truncated && <p role="status" className="bp-blocked">已加载 {progress.items.length} / {snapshot.tasks.total} 条任务，优先显示待处理与进行中的记录。下方数量与筛选仅针对已加载任务。</p>}
@@ -117,11 +139,11 @@ export function TaskWorkspace({ snapshot, dispatch, busy, scope, inspect, openSe
       })}</ul>
       {progress.attention.length > 6 && <button type="button" aria-expanded={expanded} onClick={() => setExpanded(value => !value)}>{expanded ? '收起待处理事项' : `查看全部 ${progress.attention.length} 项待处理`}</button>}
     </section>}
-    {task && <TaskDetail key={taskKey(task)} task={task} inspect={inspect} busy={busy} actions={actions} dispatch={dispatch} onClose={() => setSelection(null)} bot={snapshot.bots?.find(bot => bot.id === task.botId)} openSession={openSession} />}
-    <section className="bp-card" aria-label="任务记录"><div className="bp-card-title"><h2>任务记录</h2><span className="bp-muted" role="status">显示 {rows.length} / {progress.items.length} 条</span></div>
+    {task && <TaskDetail key={taskKey(task)} task={task} focusAttemptId={selection.attemptId} inspect={inspect} busy={busy} actions={actions} dispatch={dispatch} onClose={() => setSelection(null)} bot={snapshot.bots?.find(bot => bot.id === task.botId)} openSession={openSession} />}
+    <section className="bp-card bp-task-records" aria-label="任务记录"><div className="bp-card-title"><div><h2>任务记录</h2><span className="bp-muted" role="status">显示 {rows.length} / {progress.items.length} 条</span></div><div className="bp-segmented" role="group" aria-label="任务显示方式"><button type="button" aria-pressed={view === 'list'} onClick={() => setView('list')}><UiIcon name="list" size={15} />列表</button><button type="button" aria-pressed={view === 'board'} onClick={() => setView('board')}><UiIcon name="board" size={15} />看板</button></div></div>
       <div className="bp-task-search"><label>搜索任务<input type="search" value={query} placeholder="任务名称、Bot 或任务 / 计划 / 操作编号" onChange={event => setQuery(event.target.value)} /></label>
         {(query || botId || status !== 'all') && <button type="button" onClick={() => { setQuery(''); setBotId(''); setStatus('all') }}>清除筛选</button>}</div>
-      {!progress.items.length ? <p className="bp-empty">尚无持久任务。在 Main 私聊中提出目标后，可在这里查看工作包、执行尝试与收据。</p> : rows.length === 0 ? <p className="bp-empty">没有符合当前筛选的任务。可清除筛选查看其他记录。</p> : <div className="bp-table-wrap"><table>
+      {!progress.items.length ? <p className="bp-empty">尚无持久任务。在 Main 私聊中提出目标后，可在这里查看工作包、执行尝试与收据。</p> : rows.length === 0 ? <p className="bp-empty">没有符合当前筛选的任务。可清除筛选查看其他记录。</p> : view === 'board' ? <div className="bp-board" aria-label="任务看板">{taskBoard(progress, rows).map(lane => <section key={lane.id} className="bp-board-lane" aria-label={lane.title} data-lane={lane.id}><h3><UiIcon name={lane.icon} size={15} />{lane.title}<span>{lane.items.length}</span></h3><div className="bp-board-items">{lane.items.map(row => <article key={taskKey(row)} className="bp-board-card"><span className="bp-board-state">{TASK_STATES[row.state] ?? row.state}</span><button type="button" className="bp-text-button" onClick={() => select(row)}>{taskTitle(row)}</button><p>{snapshot.bots?.find(bot => bot.id === row.botId)?.name ?? row.botId ?? '归属未提供'}</p>{row.blockedReason && <small>{row.blockedReason}</small>}<RemoteNotice row={row} /><footer><time>{date(row.updatedAt)}</time><div className="bp-actions"><TaskActions row={row} actions={actions} dispatch={dispatch} busy={busy} /></div></footer></article>)}{!lane.items.length && <p className="bp-board-empty">暂无任务</p>}</div></section>)}</div> : <div className="bp-table-wrap"><table>
         <thead><tr><th>任务</th><th>Bot</th><th>状态</th><th>执行尝试</th><th>操作</th></tr></thead><tbody>{rows.map(row => <tr key={taskKey(row)}>
           <td><button className="bp-text-button" onClick={() => select(row)}>{taskTitle(row)}</button><small>更新 {date(row.updatedAt)}</small></td>
           <td>{snapshot.bots?.find(bot => bot.id === row.botId)?.name ?? row.botId ?? '未取得归属'}</td><td><Tag>{TASK_STATES[row.state] ?? row.state}</Tag>{progressNote(row, TASK_STATES[row.state] ?? row.state) && <small>{progressNote(row, TASK_STATES[row.state] ?? row.state)}</small>}{row.blockedReason && <small>{row.blockedReason}</small>}<RemoteNotice row={row} /></td>

package/apps/integration-client/ui-icons.jsx

@@ -1,6 +1,22 @@
 import React from 'react'
 
 const paths = {
+  home: ['m3 10 9-7 9 7v10a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1Zm6 11v-8h6v8'],
+  inbox: ['M4 4h16l2 10v6H2v-6Zm-2 10h6l2 3h4l2-3h6'],
+  bell: ['M18 8a6 6 0 0 0-12 0c0 7-3 7-3 9h18c0-2-3-2-3-9M10 21h4'],
+  clock: ['M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18Zm0 4v5l3 2'],
+  activity: ['M3 12h4l3-8 4 16 3-8h4'],
+  sun: ['M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8ZM12 2v2m0 16v2M2 12h2m16 0h2M5 5l1.5 1.5m11 11L19 19M5 19l1.5-1.5m11-11L19 5'],
+  moon: ['M20 14.5A8.5 8.5 0 0 1 9.5 4 8.5 8.5 0 1 0 20 14.5Z'],
+  memory: ['M9 4a3 3 0 0 0-5 3 4 4 0 0 0 0 7 4 4 0 0 0 5 5m6-15a3 3 0 0 1 5 3 4 4 0 0 1 0 7 4 4 0 0 1-5 5', 'M12 3v18m-5-11 5 2 5-2m-9 6 4-2 4 2'],
+  voice: ['M12 3a3 3 0 0 0-3 3v6a3 3 0 0 0 6 0V6a3 3 0 0 0-3-3Zm-7 8v1a7 7 0 0 0 14 0v-1m-7 8v3m-4 0h8'],
+  keyboard: ['M3 5h18v14H3Zm4 4h1m3 0h1m3 0h1m-9 4h1m3 0h1m3 0h1m-9 3h10'],
+  hand: ['M7 11V5a2 2 0 0 1 4 0v5-7a2 2 0 0 1 4 0v7-5a2 2 0 0 1 4 0v7l1-2a2 2 0 0 1 3 2l-4 9H9l-6-7a2 2 0 0 1 3-3l3 3'],
+  fit: ['M8 3H3v5m13-5h5v5M3 16v5h5m13-5v5h-5M8 8h8v8H8Z'],
+  close: ['m6 6 12 12M6 18 18 6'],
+  board: ['M3 4h7v16H3Zm11 0h7v10h-7'],
+  list: ['M9 6h12M9 12h12M9 18h12M3 6h1m-1 6h1m-1 6h1'],
+  spark: ['m12 3 2.3 6.7L21 12l-6.7 2.3L12 21l-2.3-6.7L3 12l6.7-2.3Z'],
   bot: ['M8 4h8l4 4v8l-4 4H8l-4-4V8Z', 'M9 10v3m6-3v3'],
   team: ['M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2m20 0v-2a4 4 0 0 0-3-3.87', 'M9 11a4 4 0 1 0 0-8 4 4 0 0 0 0 8m8-7.87a4 4 0 0 1 0 7.75'],
   tasks: ['M9 5H6a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2h-3', 'M9 3h6v4H9Zm-1 10 2 2 5-5m-7 8h8'],
@@ -12,6 +28,7 @@ const paths = {
   refresh: ['M20 7v5h-5M4 17v-5h5', 'M6.1 6.1A8 8 0 0 1 19.5 9M4.5 15a8 8 0 0 0 13.4 2.9'],
   search: ['M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14m5-2 5 5'],
   upload: ['M12 16V3m-5 5 5-5 5 5M4 15v4a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-4'],
+  download: ['M12 3v13m-5-5 5 5 5-5M4 16v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3'],
   plus: ['M12 5v14M5 12h14'],
   file: ['M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Zm0 0v6h6', 'M8 13h8m-8 4h5'],
   arrow: ['M7 17 17 7M7 7h10v10'],

package/apps/integration-client/usage-explorer.jsx

@@ -0,0 +1,43 @@
+import React,{useEffect,useMemo,useState} from 'react'
+import {money} from './api.mjs'
+import {usageReport,usageCsv,usageDay,usageModel,USAGE_SOURCES,USAGE_STATES} from './usage-report.mjs'
+import {UiIcon} from './ui-icons.jsx'
+
+const quantity=value=>value===null?'未知':value.toLocaleString('zh-CN')
+export function UsageExplorer({section,busy=false,scope}){
+  const [filter,setFilter]=useState({from:'',to:'',botId:'',source:'',status:'',groupBy:'none'}),[page,setPage]=useState(0),[message,setMessage]=useState('')
+  useEffect(()=>{setFilter({from:'',to:'',botId:'',source:'',status:'',groupBy:'none'});setPage(0);setMessage('')},[scope])
+  const items=section.items??[]
+  const report=useMemo(()=>usageReport(items,{...filter,timezone:section.timezone}),[items,filter,section.timezone])
+  const bots=useMemo(()=>[...new Map(items.map(row=>[row.botId??'',row.botName??row.botId??'未归属'])).entries()].sort((a,b)=>String(a[1]).localeCompare(String(b[1]))),[items])
+  const statuses=useMemo(()=>[...new Set(items.map(row=>row.status).filter(Boolean))].sort(),[items])
+  const pages=Math.max(1,Math.ceil(report.rows.length/100)),current=Math.min(page,pages-1),visible=report.rows.slice(current*100,(current+1)*100)
+  const change=(key,value)=>{setFilter(old=>({...old,[key]:value}));setPage(0);setMessage('')}
+  const exportCsv=()=>{
+    if(busy||report.error||!report.rows.length)return
+    try{
+      const href=URL.createObjectURL(new Blob([usageCsv(report)],{type:'text/csv;charset=utf-8'})),link=document.createElement('a')
+      link.href=href;link.download=`dsh-usage-${filter.from||'all'}-${filter.to||'all'}.csv`;link.hidden=true;document.body.append(link)
+      try{link.click()}finally{link.remove();setTimeout(()=>URL.revokeObjectURL(href),1000)}
+      setMessage(`已导出 ${report.rows.length} 条当前筛选的收据。`)
+    }catch{setMessage('浏览器未能导出文件，请检查下载权限后重试。')}
+  }
+  return <section className="bp-usage-explorer" aria-label="费用收据明细">
+    <div className="bp-usage-heading"><div><h2>收据明细</h2><p className="bp-muted">按调用开始时间筛选 · {report.timezone}。仅包含当前 Bot 的逐条调用收据；早期汇总归档与无归属费用见上方资金汇总。</p></div><button type="button" disabled={busy||Boolean(report.error)||!report.rows.length} onClick={exportCsv}><UiIcon name="download" size={15}/>导出 CSV</button></div>
+    <div className="bp-usage-filters">
+      <label>开始日期<input type="date" aria-label="收据开始日期" value={filter.from} onChange={event=>change('from',event.target.value)}/></label>
+      <label>结束日期<input type="date" aria-label="收据结束日期" value={filter.to} onChange={event=>change('to',event.target.value)}/></label>
+      <label>Bot<select aria-label="筛选收据 Bot" value={filter.botId} onChange={event=>change('botId',event.target.value)}><option value="">全部 Bot</option>{bots.filter(([id])=>id).map(([id,label])=><option key={id} value={id}>{label}</option>)}</select></label>
+      <label>来源<select aria-label="筛选收据来源" value={filter.source} onChange={event=>change('source',event.target.value)}><option value="">全部来源</option>{[...new Set(items.map(row=>row.source).filter(Boolean))].sort().map(source=><option key={source} value={source}>{USAGE_SOURCES[source]??source}</option>)}</select></label>
+      <label>状态<select aria-label="筛选收据状态" value={filter.status} onChange={event=>change('status',event.target.value)}><option value="">全部状态</option>{statuses.map(status=><option key={status} value={status}>{USAGE_STATES[status]??status}</option>)}</select></label>
+      <label>分组<select aria-label="收据分组" value={filter.groupBy} onChange={event=>change('groupBy',event.target.value)}>{[['none','不分组'],['bot','按 Bot'],['model','按模型'],['source','按来源'],['day','按日期']].map(([value,label])=><option key={value} value={value}>{label}</option>)}</select></label>
+    </div>
+    {report.error&&<p className="bp-error" role="alert">{report.error}</p>}
+    {(report.undatedExcluded>0||report.undated>0&&!filter.from&&!filter.to)&&<p className="bp-muted">{report.undatedExcluded?`${report.undatedExcluded} 条收据未报告日期，不计入所选日期范围。`:`${report.undated} 条收据未报告日期，保留在全部明细中。`}</p>}
+    <div className="bp-usage-totals" aria-label="当前筛选汇总"><span><strong>{report.summary.calls}</strong> 条收据</span><span>已知 API 金额 <strong>{money(report.summary.knownApiUsd)}</strong></span><span>金额未知 <strong>{report.summary.unknownApiCalls}</strong> 条</span><span>订阅调用 <strong>{report.summary.subscriptionCalls}</strong> 次</span><span>已知 Token {quantity(report.summary.calls>report.summary.unknownInputCalls?report.summary.inputTokens:null)} / {quantity(report.summary.calls>report.summary.unknownOutputCalls?report.summary.outputTokens:null)}{report.summary.unknownInputCalls+report.summary.unknownOutputCalls>0?'（含未报告项）':''}</span></div>
+    {report.groups.length>0&&<div className="bp-table-wrap bp-usage-groups"><table><thead><tr><th>分组</th><th>收据数</th><th>已知 API 金额</th><th>金额未知</th><th>订阅调用</th></tr></thead><tbody>{report.groups.map(group=><tr key={group.key}><td>{group.label}</td><td>{group.calls}</td><td>{money(group.knownApiUsd)}</td><td>{group.unknownApiCalls}</td><td>{group.subscriptionCalls}</td></tr>)}</tbody></table></div>}
+    {!visible.length?<p className="bp-empty">{items.length?'没有符合条件的收据。':'尚无费用收据。'}</p>:<div className="bp-table-wrap bp-usage-receipts"><table role="table"><thead><tr><th>日期 / Bot / 任务</th><th>来源</th><th>准确模型</th><th>金额</th><th>状态</th></tr></thead><tbody role="rowgroup">{visible.map((row,index)=><tr role="row" key={row.id??row.receiptId??index}><td role="cell" data-label="日期 / Bot / 任务">{usageDay(row,report.timezone)??'日期未报告'}<small>{row.botName??row.botId??'未归属'}</small><small>{row.taskId??row.runId}</small></td><td role="cell" data-label="来源">{USAGE_SOURCES[row.source]??row.source??'未报告'}</td><td role="cell" data-label="准确模型">{usageModel(row)}</td><td role="cell" data-label="金额">{row.billing==='subscription'?'订阅':money(row.amountUsd??row.costUsd)}</td><td role="cell" data-label="状态">{USAGE_STATES[row.status]??row.status??'未知'}{row.resolution&&<span className="bp-tag">{row.resolution.kind==='waive'?'已按零费用放行':`已确认 ${money(row.resolution.costUsd)}`}</span>}</td></tr>)}</tbody></table></div>}
+    <div className="bp-usage-pagination"><span>{report.rows.length} / {report.total} 条 · 第 {current+1} / {pages} 页</span><button type="button" disabled={current===0} onClick={()=>setPage(current-1)}>上一页</button><button type="button" disabled={current+1>=pages} onClick={()=>setPage(current+1)}>下一页</button></div>
+    {message&&<p role="status">{message}</p>}
+  </section>
+}

package/apps/integration-client/usage-report.mjs

@@ -0,0 +1,71 @@
+export const USAGE_SOURCES = Object.freeze({bot:'Bot 对话',aux:'Bot 辅助调用','mr-api':'MR API',cli:'官方 CLI',review:'评审'})
+export const USAGE_STATES = Object.freeze({admitted:'已准入',running:'执行中',reported:'已报告',settled:'已结算',unknown:'待核对'})
+const quantity=value=>typeof value==='number'&&Number.isFinite(value)&&value>=0?value:null
+const dateOf=row=>Number.isSafeInteger(row.createdAt)&&row.createdAt>=0?row.createdAt:Number.isSafeInteger(row.finishedAt)&&row.finishedAt>=0?row.finishedAt:null
+const validDate=value=>!value||/^\d{4}-\d{2}-\d{2}$/.test(value)&&Number.isFinite(Date.parse(`${value}T00:00:00Z`))&&new Date(`${value}T00:00:00Z`).toISOString().slice(0,10)===value
+const formatterCache=new Map()
+export function usageTimezone(value){
+  if(formatterCache.has(value||'UTC'))return value||'UTC'
+  try{new Intl.DateTimeFormat('en',{timeZone:value||'UTC'}).format(0);return value||'UTC'}catch{return 'UTC'}
+}
+export function usageDay(row,timezone='UTC'){
+  const at=dateOf(row)
+  if(at===null||!Number.isFinite(new Date(at).getTime()))return null
+  const zone=usageTimezone(timezone)
+  if(!formatterCache.has(zone)){if(formatterCache.size>=32)formatterCache.delete(formatterCache.keys().next().value);formatterCache.set(zone,new Intl.DateTimeFormat('en',{timeZone:zone,year:'numeric',month:'2-digit',day:'2-digit'}))}
+  const parts=Object.fromEntries(formatterCache.get(zone).formatToParts(at).map(part=>[part.type,part.value]))
+  return `${parts.year.padStart(4,'0')}-${parts.month}-${parts.day}`
+}
+export const usageModel=row=>typeof row.model==='object'&&row.model?`${row.model.provider??row.provider??'未知来源'}/${row.model.model??row.model.id??'未知模型'}`:row.provider?`${row.provider}/${row.model??row.modelId??'未知模型'}`:String(row.model??row.modelId??'未报告')
+const emptySummary=()=>({calls:0,knownApiUsd:null,knownApiCalls:0,amountOverflow:false,unknownApiCalls:0,subscriptionCalls:0,inputTokens:0,outputTokens:0,unknownInputCalls:0,unknownOutputCalls:0})
+function accumulate(total,row){
+  total.calls++
+  const amount=quantity(row.amountUsd??row.costUsd)
+  if(row.billing==='subscription')total.subscriptionCalls++
+  else if(amount===null)total.unknownApiCalls++
+  else {
+    total.knownApiCalls++
+    if(!total.amountOverflow){const sum=(total.knownApiUsd??0)+amount;total.amountOverflow=!Number.isFinite(sum);total.knownApiUsd=total.amountOverflow?null:sum}
+  }
+  for(const [field,missing]of [['inputTokens','unknownInputCalls'],['outputTokens','unknownOutputCalls']]){
+    const value=Number.isSafeInteger(row[field])&&row[field]>=0?row[field]:null
+    if(value===null)total[missing]++
+    else total[field]=total[field]===null||!Number.isSafeInteger(total[field]+value)?null:total[field]+value
+  }
+}
+
+/** Analysis of public source receipts only; no budget, reservation or billing decisions. */
+export function usageReport(items=[],{from='',to='',botId='',source='',status='',groupBy='none',timezone='UTC'}={}){
+  const error=!validDate(from)||!validDate(to)?'请选择有效的起止日期。':from&&to&&from>to?'开始日期不能晚于结束日期。':''
+  const zone=usageTimezone(timezone),rows=[],groups=new Map(),summary=emptySummary()
+  let undated=0,undatedExcluded=0
+  for(const row of Array.isArray(items)?items:[]){
+    if(!row||typeof row!=='object'||botId&&row.botId!==botId||source&&row.source!==source||status&&row.status!==status)continue
+    const day=usageDay(row,zone)
+    if(!day){undated++;if(from||to)undatedExcluded++}
+    if(error||(from||to)&&!day||from&&day<from||to&&day>to)continue
+    rows.push(row);accumulate(summary,row)
+    if(groupBy!=='none'){
+      const key=groupBy==='bot'?String(row.botId??''):groupBy==='model'?usageModel(row):groupBy==='source'?String(row.source??''):day??''
+      if(!groups.has(key))groups.set(key,{key,label:groupBy==='bot'?row.botName??row.botId??'未归属':groupBy==='source'?USAGE_SOURCES[row.source]??row.source??'未报告':groupBy==='day'?day??'日期未报告':key,...emptySummary()})
+      accumulate(groups.get(key),row)
+    }
+  }
+  rows.sort((a,b)=>(dateOf(b)??-1)-(dateOf(a)??-1)||(b.sequence??0)-(a.sequence??0))
+  return {rows,groups:[...groups.values()].sort((a,b)=>groupBy==='day'?b.key.localeCompare(a.key):b.calls-a.calls||a.key.localeCompare(b.key)),summary,timezone:zone,undated,undatedExcluded,error,total:Array.isArray(items)?items.length:0}
+}
+
+/** Quoting alone does not prevent spreadsheet formulas in a person's Bot/model name. */
+export function csvCell(value){
+  let text=value===null||value===undefined?'':String(value).replaceAll('\0','')
+  if(/^[\s\uFEFF]*[=+\-@]/u.test(text)||/^[\t\r\n]/.test(text))text=`'${text}`
+  return `"${text.replaceAll('"','""')}"`
+}
+export function usageCsv(report){
+  const headers=['收据编号','Bot 编号','Bot 名称','任务编号','运行编号','调用开始时间','日期时区','来源','准确模型','计费方式','金额 USD（空白=未知或订阅）','金额状态','输入 Token（空白=未知）','输出 Token（空白=未知）','状态','核对结果']
+  const lines=report.rows.map(row=>{
+    const amount=quantity(row.amountUsd??row.costUsd),at=dateOf(row),dated=at!==null&&Number.isFinite(new Date(at).getTime())
+    return [row.id??row.receiptId,row.botId,row.botName,row.taskId,row.runId,dated?new Date(at).toISOString():'',report.timezone,USAGE_SOURCES[row.source]??row.source,usageModel(row),row.billing==='subscription'?'订阅':'API',row.billing==='subscription'?null:amount,row.billing==='subscription'?'订阅':amount===null?'未知':'已知',quantity(row.inputTokens),quantity(row.outputTokens),row.status,row.resolution?.kind??'']
+  })
+  return '\uFEFF'+[headers,...lines].map(cells=>cells.map(csvCell).join(',')).join('\r\n')+'\r\n'
+}

package/apps/integration-client/usage.css

@@ -0,0 +1,34 @@
+body[data-bot-product-ui] .bp-usage-explorer { display:flex;flex-direction:column;gap:16px;min-width:0; }
+body[data-bot-product-ui] .bp-usage-heading { display:flex;align-items:flex-start;gap:20px;justify-content:space-between; }
+body[data-bot-product-ui] .bp-usage-heading > div { flex:1;min-width:0; }
+body[data-bot-product-ui] .bp-usage-heading h2 { margin:0 0 6px;font-size:17px;font-weight:600; }
+body[data-bot-product-ui] .bp-usage-heading p { margin:0;line-height:1.7; }
+body[data-bot-product-ui] .bp-usage-heading > button { display:inline-flex;align-items:center;gap:7px;flex:none; }
+body[data-bot-product-ui] .bp-usage-filters { display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;padding:16px;border:1px solid var(--bp-border);border-radius:14px;background:var(--bp-surface); }
+body[data-bot-product-ui] .bp-usage-filters label { display:flex;flex-direction:column;gap:7px;min-width:0;font-size:12px;color:var(--bp-muted); }
+body[data-bot-product-ui] .bp-usage-filters :is(input,select) { width:100%;min-width:0;min-height:36px;color:var(--bp-ink); }
+body[data-bot-product-ui] .bp-usage-filters input[type=date] { color-scheme:light; }
+body[data-bot-product-ui][data-bp-appearance=dark] .bp-usage-filters input[type=date],
+body[data-bot-product-ui][data-ds-dark-theme]:not([data-bp-appearance=light]) .bp-usage-filters input[type=date] { color-scheme:dark; }
+body[data-bot-product-ui] .bp-usage-totals { display:flex;flex-wrap:wrap;gap:10px 20px;font-size:12px;color:var(--bp-muted); }
+body[data-bot-product-ui] .bp-usage-totals strong { color:var(--bp-ink);font-variant-numeric:tabular-nums;font-weight:600; }
+body[data-bot-product-ui] .bp-usage-explorer td { overflow-wrap:anywhere; }
+body[data-bot-product-ui] .bp-usage-pagination { display:flex;align-items:center;flex-wrap:wrap;gap:8px;font-size:12px;color:var(--bp-muted); }
+body[data-bot-product-ui] .bp-usage-pagination > span { flex:1;min-width:100px; }
+@container(max-width:600px) {
+  body[data-bot-product-ui] .bp-usage-filters { grid-template-columns:repeat(2,minmax(0,1fr));padding:12px; }
+  body[data-bot-product-ui] .bp-usage-heading { flex-direction:column;gap:12px; }
+  body[data-bot-product-ui] .bp-usage-groups table { min-width:520px; }
+  body[data-bot-product-ui] .bp-usage-receipts { border:0;background:transparent; }
+  body[data-bot-product-ui] .bp-usage-receipts :is(table,tbody) { display:block;width:100%; }
+  body[data-bot-product-ui] .bp-usage-receipts thead { position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%); }
+  body[data-bot-product-ui] .bp-usage-receipts tbody { display:flex;flex-direction:column;gap:12px; }
+  body[data-bot-product-ui] .bp-usage-receipts tbody tr { display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:14px 12px;padding:16px;border:1px solid var(--bp-border);border-radius:12px;background:var(--bp-surface); }
+  body[data-bot-product-ui] .bp-usage-receipts td { display:block;min-width:0;padding:0;border:0; }
+  body[data-bot-product-ui] .bp-usage-receipts td::before { display:block;content:attr(data-label);margin-bottom:5px;font-size:11px;color:var(--bp-muted); }
+  body[data-bot-product-ui] .bp-usage-receipts td:first-child { order:0; }
+  body[data-bot-product-ui] .bp-usage-receipts td:nth-child(4) { order:1; }
+  body[data-bot-product-ui] .bp-usage-receipts td:nth-child(3) { order:2;grid-column:1 / -1; }
+  body[data-bot-product-ui] .bp-usage-receipts td:nth-child(2) { order:3; }
+  body[data-bot-product-ui] .bp-usage-receipts td:nth-child(5) { order:4; }
+}

package/apps/integration-client/web-panel-model.mjs

@@ -0,0 +1,140 @@
+// Pure helpers for the pinned web panel surface: the same closed input check the
+// Host applies, the wording for every framing verdict, and the messages for every
+// way a Host can refuse. Kept free of React so both the panel and the sidebar pin
+// list — and their tests — read one definition.
+//
+// The client check is a mirror, never the authority: it exists so a typo is
+// answered while the person is still typing, and the Host re-validates every save
+// with the caller's real embedding origin.
+
+export const MAX_WEB_PANELS = 6
+export const MAX_WEB_PANEL_NAME_CHARS = 40
+export const MAX_WEB_PANEL_NAME_BYTES = 120
+export const MAX_WEB_PANEL_URL_BYTES = 2048
+
+// The frame keeps its page's own origin, so it may run scripts and use its own
+// storage. What it never gets is a way out: no top-level navigation, no pointer
+// lock, no presentation. `allow-popups` stays because a dashboard's sign-in very
+// often opens one.
+export const WEB_PANEL_SANDBOX = 'allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads'
+export const WEB_PANEL_REFERRER_POLICY = 'no-referrer'
+export const WEB_PANEL_LOAD_TIMEOUT_MS = 10_000
+
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+
+// The client bundle has no Buffer, and the byte count is only a fast "this is
+// absurdly long" answer for a person still typing; the Host measures for real.
+const byteLength = text => {
+  let size = 0
+  for (let index = 0; index < text.length; index++) {
+    const point = text.codePointAt(index)
+    if (point < 0x80) size += 1
+    else if (point < 0x800) size += 2
+    else if (point < 0x10000) size += 3
+    else { size += 4; index++ }
+  }
+  return size
+}
+
+/** Mirrors `validateWebPanelInput` on the Host. */
+export function validateWebPanelDraft(input, embeddingOrigin = '') {
+  const name = typeof input?.name === 'string' ? input.name.trim() : ''
+  const raw = typeof input?.url === 'string' ? input.url.trim() : ''
+  if (!name || name.length > MAX_WEB_PANEL_NAME_CHARS || CONTROL.test(name)) return { ok: false, error: 'name' }
+  let url
+  try { url = new URL(raw) } catch { return { ok: false, error: 'url' } }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return { ok: false, error: 'url' }
+  if (url.username || url.password || !url.hostname) return { ok: false, error: 'url' }
+  if (byteLength(raw) > MAX_WEB_PANEL_URL_BYTES) return { ok: false, error: 'url' }
+  if (embeddingOrigin && sameOrigin(url, embeddingOrigin)) return { ok: false, error: 'self' }
+  return { ok: true, name, url: url.href }
+}
+
+function sameOrigin(url, origin) {
+  try { return new URL(origin).origin === url.origin } catch { return false }
+}
+
+export function panelHost(url) {
+  try { return new URL(url).host } catch { return '' }
+}
+
+/** The client's own embedding origin: the native shell's, or the browser's. */
+export function clientOrigin(location = globalThis.location) {
+  try { return location?.origin ?? '' } catch { return '' }
+}
+
+/** A panel framed from this app's own origin would run with the app's access. */
+export function isSelfOrigin(url, origin) {
+  if (!origin) return false
+  try { return new URL(url).origin === new URL(origin).origin } catch { return false }
+}
+
+export function panelsOf(snapshot) {
+  const section = snapshot?.webPanels
+  if (!section || section.status !== 'available' || !Array.isArray(section.items)) {
+    return { status: section?.status === 'blocked' ? 'blocked' : 'unavailable', items: [], revision: 0, limits: null, reason: section?.reason ?? '', nextAction: section?.nextAction ?? '' }
+  }
+  const items = section.items
+    .filter(panel => panel && typeof panel.id === 'string' && typeof panel.url === 'string')
+    .map((panel, index) => ({ id: panel.id, name: typeof panel.name === 'string' ? panel.name : panel.id,
+      url: panel.url, host: panelHost(panel.url), position: Number.isSafeInteger(panel.position) ? panel.position : index + 1 }))
+    .sort((left, right) => left.position - right.position)
+  return { status: 'available', items, revision: Number.isSafeInteger(section.revision) ? section.revision : 0,
+    limits: section.limits ?? null, reason: '', nextAction: '' }
+}
+
+/** The list in a new order after moving one panel by `delta`. */
+export function movedOrder(panels, id, delta) {
+  const index = panels.findIndex(panel => panel.id === id)
+  const target = index + delta
+  if (index < 0 || target < 0 || target >= panels.length) return null
+  const ids = panels.map(panel => panel.id)
+  ;[ids[index], ids[target]] = [ids[target], ids[index]]
+  return ids
+}
+
+/** What a probe verdict means, in the words the panel shows. Never a server's own text. */
+export function framingMessage(result) {
+  if (!result || result.state === 'checking') return { tone: 'idle', text: '正在向宿主确认该页面是否允许显示…' }
+  if (result.framing === 'blocked') return { tone: 'blocked', text: `${result.host || '该网站'} 不允许在其他应用中显示它。可以在浏览器中打开，或换一个允许嵌入的页面。` }
+  if (result.framing === 'allowed') return { tone: 'ok', text: '宿主确认该页面允许在此显示。浏览器仍可能因其他设置拒绝渲染。' }
+  const reason = result.reason
+  if (reason === 'timeout') return { tone: 'unknown', text: '无法确认：该页面响应超时。仍会尝试显示，浏览器可能可以打开它。' }
+  if (reason === 'redirect') return { tone: 'unknown', text: '无法确认：该页面会跳转，可能是浏览器先登录后才看到的页面。' }
+  if (reason === 'bad-status') return { tone: 'unknown', text: '无法确认：该页面没有返回可显示的内容。' }
+  if (reason === 'unreachable') return { tone: 'unknown', text: '无法确认：宿主暂时连不上该页面。仍会尝试显示。' }
+  if (reason === 'aborted') return { tone: 'idle', text: '' }
+  if (['invalid-url', 'unsupported-scheme', 'credentials-in-url'].includes(reason)) return { tone: 'blocked', text: '该地址不能作为网页面板：只支持不带登录信息的 http/https 地址。' }
+  return { tone: 'unknown', text: '无法确认该页面是否允许显示。仍会尝试显示。' }
+}
+
+/** A Host refusal, in the words the panel shows. Codes are the contract, not the text. */
+export function actionError(error) {
+  const code = error?.code ?? ''
+  const text = ({
+    WEB_PANEL_NAME: '名称需为 1–40 个字符。',
+    WEB_PANEL_URL: '请填写完整的 http/https 地址，且不要带登录信息。',
+    WEB_PANEL_SELF_URL: '不能固定应用自身的页面。',
+    WEB_PANEL_LIMIT: `最多固定 ${MAX_WEB_PANELS} 个网页面板。`,
+    WEB_PANEL_NOT_FOUND: '该固定页面已不存在，列表已刷新。',
+    WEB_PANEL_REVISION_CONFLICT: '列表刚刚在别处被改过，已刷新；请重新操作。',
+    WEB_PANEL_ORDER_INVALID: '排序与当前列表不一致，已刷新；请重新排序。',
+    WEB_PANEL_INPUT: '请求格式不正确。',
+    WEB_PANEL_READBACK_MISMATCH: '宿主未确认这次修改，请刷新后重试。',
+    WEB_PANEL_PROBE_BUSY: '正在检测其他页面，请稍候再试。',
+    WEB_PANEL_STORE_CLOSED: '宿主正在关闭，请刷新后重试。',
+    REMOTE_OWNER_REQUIRED: '请重新登录宿主拥有者账号。',
+    PRODUCT_READ_ONLY: '宿主目前处于只读状态，暂不能修改。',
+    PRODUCT_ACTION_UNAVAILABLE: '当前宿主尚未接入固定网页面板，请更新宿主。',
+  })[code]
+  return { code, text: text ?? '宿主请求未完成，请刷新后重试。' }
+}
+
+/**
+ * Open a page in the user's own browser. Only ever called from a click, in a new
+ * browsing context, with no handle back to this window and no referrer sent.
+ */
+export function openExternally(url, open = globalThis.open) {
+  if (typeof open !== 'function') return false
+  try { return open(url, '_blank', 'noopener,noreferrer') !== null } catch { return false }
+}