import { AppWebEntry } from '@deepseek-ai/dsh-client-web' // 唯一依赖：壳内核入口类，加载/组装/插件装配全在它里面const el = document.getElementById('root') // 找挂载点——这是整个"应用"里唯一的 DOM 操作if (el === null) throw new Error('web app: missing #root') // 找不到直接抛错：fail loud，不渲染任何兜底 UIvoid new AppWebEntry(el).run() // 把挂载点交给内核跑两阶段启动；void 表示不 await——失败由加载页自己呈现

async run(): Promise<void> { // 启动链跑到"结算"为止；失败不 reject，而是留在加载页渲染错误报告  this.manifest = parseBootManifest((globalThis as DshWindow).__DSH_BOOT__) // 解析宿主注入的 manifest（wire 边界）：modules 视图 + plugins 视图两张表  this.modules = new ClientModuleSystem({ // 建模块系统：fetch bundle 的 external 全靠它解析    modules: this.manifest.modules, staticModules: getStaticModules(), ...this.seams, // manifest 模块行 + 壳静态表一起喂给模块系统；seams 是测试注入点（jsdom 替换 script 路径）  })  this.modules.registerStatic(APP_SHELL_ID, AppShell) // app-shell 组装是唯一的壳自有模块——其余 graph row 全是 fetch 来的插件 bundle  this.modules.registerStatic(MODULES_ID, ModulesClient) // modules 包自己的 client 半部按裸包名注册（=graph row id），否则 statics 分支漏掉会触发真 fetch  ;(globalThis as DshWindow).__DSH_MODULES__ = this.modules // 把实例挂到内核槽位：modules entry 的 wrapper apply 从这里读，provide ctx.modules  this.root = createRoot(this.el) // React root：先渲染加载页（AppRoot），settled 之后一次性切真实 UI  this.root.render(<AppRoot settled={this.settled} status={this.status} error={this.error} // 加载页先行：三个 signal store 全是内核自有——失败报告不依赖任何插件（壳自足性规则）    renderApp={() => { const shell = this.ctx.get('appShell') // 延迟到 settled 后才取 appShell 服务——此刻插件还没 active      if (shell === undefined) throw new Error('web boot: appShell service missing after settled') // inject set 已保证 active，这是不可达防御——fail loud 而非静默返回空 UI      return shell.renderApp() }} />) // renderApp 闭包：settled 后 AppRoot 每次重渲染都调它（内部有 identity-stable 缓存）  const prefetching = this.prefetchImmediateTier() // immediately 层预取与 Loader 挂载并行跑（只注册 factory，失败静默留给 import 路径大声报）  this.ctx = new Context() // cordis 上下文：插件面所有服务/事件/inject 的宿主  try { // 启动链失败不 reject——留在加载页渲染错误报告（fail-loud surface）    await this.runPluginBoot(prefetching) // 插件面：挂 Loader → 注入 internal → 建 entry → await → sweep    this.settled.set(true) // 全部 ACTIVE 才翻 settled 信号，AppRoot 一次性切真实 UI  } catch (reason) { // 任何阶段抛错都走这里：console + error signal，绝不渲染半个 UI    console.error(reason) // 完整堆栈进控制台——加载页只显示 message，细节靠这里查    this.error.set(reason instanceof Error ? reason.message : String(reason)) // 失败留在加载页呈现（fail loud），绝不渲染半个 UI  }}

private assertEntriesActive(): void { // 树静默后扫所有 entry：这是 inject waiting 无超时的 fail-loud 补偿  const ctx = this.ctx // 用当前 ctx 读服务表（判断 pending entry 缺哪个服务）  const failures: string[] = [] // 收集所有不合格 entry——一次性全列出，不只看第一个  for (const entry of ctx.loader.entries()) { // 遍历全部 loader entry：import 失败 / PENDING / FAILED 三种病都要抓    const name = entry.options.name // entry 名 = graph row id（包名），报告里直接可读    if (entry.fiber === undefined) { // import 失败的 entry 没有 fiber（Entry._init 记日志后返回）——直接算失败      failures.push(`${name}: import failed (see console for the import error)`)      continue    }    const state = STATE_LABELS[entry.fiber.state]    if (state === 'active') continue // ACTIVE 是唯一合格态    if (state === 'pending') { // PENDING：某个必需服务永远没到——把缺的服务名列出来，定位一步到位      const missing = Object.keys(entry.fiber.inject).filter(service => ctx.get(service) === undefined)      failures.push(`${name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)    } else {      failures.push(`${name}: ${state}`) // FAILED（apply 抛了）等其他态    }  }  if (failures.length > 0) { // 任何一条不合格就整体失败——宁可白屏+报告，不给半个 UI    throw new Error(`web boot: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)  }}

import * as React from 'react' // 壳静态 import：所有 bundle 看到的必须是同一个 React 实例（hooks 状态表是模块级的）import * as ReactJsxRuntime from 'react/jsx-runtime' // jsx runtime 同理——两份实例 = 两套 dispatcher，渲染直接炸import * as ReactDom from 'react-dom' // react-dom 本体（createRoot 等）——同样必须单实例import * as ReactDomClient from 'react-dom/client' // client 入口单独列：bundle 里 import 的是这个子路径，表里必须有对应 keyimport * as Cordis from '@deepseek-ai/cordis' // cordis 本体也走这张表：插件 bundle 里的 Context/Service 与壳是同一份import * as UiSlots from '@deepseek-ai/dsh-client-ui-slots' // slot 系统的 SlotMap 声明合并必须落在同一个模块上，否则类型链断裂import * as WebReact from '@deepseek-ai/dsh-client-web-react'import * as UiPrimitives from '@deepseek-ai/dsh-client-ui-primitives' // UI 基础组件库：所有 ui-* 插件共享同一份，避免样式/状态分裂import * as UiAttachment from '@deepseek-ai/dsh-client-ui-attachment' // 附件 UI（图片预览等）：宿主侧 attachment 能力的浏览器半部import * as SchemaForm from '@deepseek-ai/dsh-client-schema-form' // schema → 表单渲染器：settings/credentials 等配置 UI 的公共底座export function getStaticModules(): Record<string, unknown> { // 构建静态模块表——壳在启动时调用一次，冻结后交给 loader  return { // satisfies 是投影契约：PLATFORM_MODULES 加一个词而这里没 import（或反之）直接编译失败，不会漂成运行时 require miss    'react': React,    'react/jsx-runtime': ReactJsxRuntime,    'react-dom': ReactDom,    'react-dom/client': ReactDomClient,    '@deepseek-ai/cordis': Cordis,    '@deepseek-ai/dsh-client-ui-slots': UiSlots,    '@deepseek-ai/dsh-client-web-react': WebReact,    '@deepseek-ai/dsh-client-ui-primitives': UiPrimitives,    '@deepseek-ai/dsh-client-ui-attachment': UiAttachment,    '@deepseek-ai/dsh-client-schema-form': SchemaForm,  } satisfies Record<PlatformModule, unknown>}

export const name = 'app-shell' // cordis 插件名（graph row id）——伪包：只存在于宿主 graph，没有 npm 实体 // cordis 插件名export const inject = ['slots', 'sessions', 'layout'] // 必需服务：等这三个都 active，本 entry 才激活——顺序由 fiber inject waiting 保证export function apply(ctx: Context): void { // 等 inject set（slots/sessions/layout）全 active 才执行——顺序由 fiber inject waiting 保证  ctx.slots.install(createSlotRenderer()) // 渲染器安装是壳的事（web-react 被壳打包），但 ctx.slots 要等 runtime entry active 才存在——所以落在这里，由 inject set 保证顺序  let renderApp: (() => ReactNode) | undefined // 闭包缓存：buildRenderApp 只跑一次，引用在 AppRoot 重渲染间保持稳定  ctx.reflect.provide('appShell', {    renderApp: (): ReactNode => {      renderApp ??= buildRenderApp({ ctx }) // 首次调用才组装；??= 保证 identity-stable——React 树不能每次重渲染都换根      return renderApp()    },  })}

export function buildRenderApp(deps: AssemblyDeps): () => ReactNode { // 组装真实 UI 树的工厂——由 app-shell 的 renderApp 闭包首次调用时执行  const { ctx } = deps // 解出 active 的 app-shell ctx（slots/sessions/layout 服务已就位）  const sessions = ctx.get('sessions') // 取 sessions 服务；strict get 读全局服务表（属性代理是拓扑敏感的，这里必须用 get）  if (sessions === undefined) throw new Error('shell assembly: sessions service unavailable') // inject set 已保证 active，不可达防御——fail loud // inject set 已保证 active，这里是不可达的防御——fail loud  const useSessions = bindSnapshotSelector(sessions.list) // 把裸 observable 源绑成 uSES selector hook（web-react 的唯一 hook 构造器）  const SessionDocumentTitle = (): ReactNode => { // 文档标题跟随当前会话：纯派生数据，走框架 hook    const title = useSessions((state) => {      const id = state.current // 当前会话 id；没有就 undefined（无会话态）      return id === undefined ? undefined : state.byId[id]?.title // 从快照里取标题——派生是纯函数，不建自己的订阅    })    return <DocumentTitle {...title === undefined ? {} : { title }} />  }  return () => ( // 返回的函数 = AppRoot settled 后每次重渲染调用的真实 UI 树    <>      <SessionDocumentTitle />      {ctx.slots.renderSlot('root', {})} // 全程序唯一一次顶层 renderSlot：整棵布局树都挂在 'root' slot 上（ui-layout 把 AppFrame 注册在这里）    </>  )}

export function apply(ctx: ClientContext): void { // client 插件体：等 inject（slots/theme）active 后执行  const layout = new LayoutController() // 面板动作控制器：跨插件的 ctx.layout 契约（折叠/展开侧栏、详情列） // 面板动作控制器：跨插件的 ctx.layout 契约（折叠/展开侧栏、详情列）  ctx.effect(() => { // effect = 注册即副作用，返回 disposer——HMR 安全性的基础    const disposeService = ctx.reflect.provide('layout', layout) // provide 服务面：只暴露 ILayout 接口，具体实现留在包内（export discipline） // provide 服务面：只暴露 ILayout 接口，具体实现留在包内（export discipline）    const disposeRegistration = ctx.slots.register({      name: 'root', // 注册进 runtime 内置的 'root' slot——shell 唯一 renderSlot 的那个坑      children: { // children = 声明 + 授权：AppFrame 能渲染的 slot 恰好就是这四个 key，多一个少一个都在加载期失败        'sidebar': { kind: 'single', scope: 'root' }, // 左列整体；被 ui-sidebar 占据——注册即替换整列，它内部声明的座位随之消失        'conversation': { kind: 'single', scope: 'session-maybe' }, // 中列（含无会话 hero）；session-maybe = 当前会话可选，占位者自己管两种状态        'details': { kind: 'single', scope: 'session' }, // 右详情列；scope session = 框架自动注入 sessionId 标准 prop        'shell.overlay': { kind: 'list', scope: 'root' }, // 全帧浮层：badge/toast/status pill 都在这，kind list = 并列追加而非替换      },      store: createLayoutStore, // 独占 store：传的是工厂本身——框架按 entry 实例化，把 useStore/actions 作为标准 prop 递给 AppFrame      inject: (actions: PanelActions) => { // hook 的唯一副作用：把根 store 的绑定动作接到 ctx.layout；会话业务动作归各注册者自己        layout.attachPanels(actions)        return {}      },    }, AppFrame) // AppFrame = 三列布局 + 让渡求解（concession solve）的帧组件    return () => { // disposer：先撤注册，再异步 settle provide——teardown 是同步 fire-and-forget      disposeRegistration()      void disposeService()    }  }, 'ui-layout: service + root registration')}

private upgrade<F extends Frame>( // 泛型 F = MuxFrame | HostFrame：两条下行流共用同一套升级/泵逻辑  req: IncomingMessage,  socket: Duplex,  head: Buffer,  open: (signal: AbortSignal) => AsyncIterable<RpcRequest<F>>, // open = 打开类型化事件流的工厂（mux 或 host），AbortSignal 贯穿全程): void {  this.server.handleUpgrade(req, socket, head, (websocket) => { // noServer 模式：升级由我们手动接管，socket 所有权从 HTTP server 转移过来 // noServer 模式：升级由我们手动接管，socket 所有权从 HTTP server 转移过来    const abort = new AbortController() // 本连接的取消控制器：贯穿上游事件流迭代 + socket 生命周期    websocket.once('close', () => { abort.abort() }) // 对端关闭 → 中止上游事件流迭代（资源回收）    websocket.once('error', () => { abort.abort() }) // socket 错误同理    websocket.once('message', () => { // downlink-only 协议：收到任何上行消息都是违规      websocket.close(1008, 'downlink only') // 1008 = policy violation，直接断开——上行必须走 HTTP（协议级约束） // 1008 = policy violation，直接断开——上行必须走 HTTP    })    const pump = this.pump(websocket, open(abort.signal), abort) // 启动泵：从事件流读帧 → JSON 序列化 → send    this.pumps.add(pump) // 登记到 pumps 集合：close() 时统一 await（优雅关停所有在途泵） // 登记到 pumps 集合，close() 时统一 await（优雅关停）    void pump.then(() => { this.pumps.delete(pump) }) // 泵结束后自清理  })}private async pump<F extends Frame>(socket: WebSocket, frames: AsyncIterable<RpcRequest<F>>, abort: AbortController): Promise<void> {  try {    for await (const frame of frames) await send(socket, frame) // 逐帧发送；await send = 背压——socket 没写完不发下一帧 // 逐帧发送；await send 保证背压——socket 没写完不发下一帧  } catch (error) { // 上游迭代或 socket 写入失败    if (!abort.signal.aborted) { // 只有"非主动中止"才补发失败帧（对端已走就没人收了） // 只有"非主动中止"才补发失败帧（对端已走就没人收了）      try { await send(socket, failureFrame(error)) } catch { /* socket 丢失赢了竞态：失败帧发不出去就算了 */ }    }  } finally {    abort.abort() // 无论如何中止上游迭代    if (socket.readyState === WebSocket.OPEN) socket.close() // 优雅关闭（区别于 terminate）  }}

async fetch(request: Request): Promise<Response> { // RPC over HTTP 的完整校验链：五道关，任何一道不过都返回明确错误码  const endpoint = endpointFromPath(channel, new URL(request.url).pathname) // 从路径提取 endpoint；含空段/./.. /非法字符一律 undefined（防目录穿越） // 从路径提取 endpoint；含空段/./.. /非法字符一律返回 undefined（防目录穿越）  if (request.method !== 'POST' || endpoint === undefined) { return new Response('not found', { status: 404 }) } // RPC 只走 POST；GET 事件流端点另有 426 upgrade required // RPC 只走 POST；GET 事件流端点另有 426 upgrade required  const mediaType = request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase() // 取 MIME 主类型（剥掉 charset 等参数）——严格匹配，不猜  if (mediaType !== 'application/json') { return new Response('content type must be application/json', { status: 415 }) } // 415 = unsupported media type：不兼容、不猜测 // 严格 MIME：不猜、不兼容  let body: unknown // 先声明后赋值——json() 可能抛错，需要 try/catch 包住  try { body = await request.json() } catch { return new Response('body is not JSON', { status: 400 }) }  const envelope = clientRequestSchema.safeParse(body) // schemastery schema 校验：rpcId + method + payload 三件套缺一不可 // schemastery schema 校验：rpcId + method + payload 三件套  if (!envelope.success) { return invalidEnvelopeResponse(body, envelope.error.issues) } // 失败时尽量回带原始 rpcId——客户端能把错误对到发起的请求上 // 失败时尽量回带原始 rpcId，客户端能把错误对到发起的请求上  const message: ClientRequest = envelope.data // 校验通过，拿到类型安全的请求消息  if (message.method !== endpoint) { // method 与 URL endpoint 必须一致——防"合法 envelope 打错端点"    return errorResponse(message.rpcId, { code: 'bad-request', // method 与 URL endpoint 必须一致——防"合法 envelope 打错端点"      message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`, details: { issues: [] } })  }  try {    const result = await handler(endpoint, message.payload, request.signal) // 分发到业务 handler；request.signal 贯穿——客户端断开即中止    return fullResponse(message.rpcId, result) // 成功：{ type: 'server-response', rpcId, result }  } catch (error) {    return new Response(`handler failure: ${String(error)}`, { status: 500 }) // handler 抛错 = 服务端故障，500 + 原文  }}

// trustedHosts 是 DNS-rebinding 围栏，明确不是认证——所以在真正的认证层出现之前，// 整个配置平面保持 loopback-same-origin。const PRIVILEGED_METHODS = new Set([ // 特权方法名单：即使部署声明了 trustedHosts，这些也钉死在 loopback  'agentPreset.read', // preset 组合点名了会话要跑哪些插件——读一个就是侦察；copy/remove 重排部署提供的能力  'agentPreset.copy', // copy preset = 重排部署提供的能力组合——比只读 list 权限高得多  'agentPreset.openDocument', // 驱动宿主桌面打开文档——比旁边只读的 list 权限高得多  'agentPreset.remove',  'host.pickDirectory', // 原生目录选择对话框作用于宿主机本身——LAN 调用者不该有这能力 // 原生对话框作用于宿主机本身  'host.openPath',  'settings.describe', // 返回所有暴露命名空间的配置——读和写同样特权（侦察）  'settings.openDocument', // 打开宿主机的 settings 文档文件——驱动桌面，不是纯读  'settings.update', // 修改用户配置——写操作，必须 loopback  'settings.replace', // 整体替换配置——比 update 更危险（一次抹掉所有命名空间）  'settings.mutate',  'credentials.describe', // 报告任意环境变量名是否已配置、从哪来——匿名调用者不该有的侦察  'credentials.set', // 写入凭证存储——匿名 LAN 调用者绝对不能碰  'credentials.unset',  'llm.discoverModels', // 携带草稿凭证 + 让宿主向调用者选的 URL 发 GET 并回报状态/解析体 = 匿名 LAN 调用者的探测工具])

private async loop(): Promise<void> {  while (this.running) { // running 是跨 await 的活体守卫——stop() 可能在任何 await 处翻转它    const gen = ++this.generation // 代际号：每轮重连一个新 generation，旧代的迟到事件靠它丢弃    const ac = new AbortController()    this.current = ac    let muxOpened = (): void => {} // 占位闭包（executor 同步替换）：mux 流 onOpen 的 resolve 句柄 // 占位闭包（executor 同步替换）：mux 流 onOpen 的 resolve 句柄    let hostOpened = (): void => {} // host 流同理——两个占位，等各自流的 onOpen 回调触发 // host 流同理    const streamsOpen = Promise.all([ // 两条物理流都建立才算"开"      new Promise<void>((resolve) => { muxOpened = resolve }),      new Promise<void>((resolve) => { hostOpened = resolve }),    ])    const failed = new Promise<void>((resolve) => { // 任一泵结束（流丢失）→ settle → abort 本代      const settle = (): void => { if (gen === this.generation && !ac.signal.aborted) ac.abort(); resolve() } // 任一泵结束 → 校验代际仍有效且未被 abort → 中止本代 + resolve failed promise      void this.pumpStream(this.api.events.mux({}, ac.signal, muxOpened), this.sinks.onMuxEnvelope, settle) // mux 流：会话事件（session/event、queue、approval…）      void this.pumpStream(this.api.events.host({}, ac.signal, hostOpened), this.sinks.onHostEnvelope, settle) // host 流：宿主级事件    })    try { // 严格就绪握手：describe（一元可达）+ 双流 onOpen（物理建立）——三者齐了才算 connected      const timeout = new AbortController() // 独立超时控制器：只用于 streamOpenTimeout，不影响主 ac      const [description] = await Promise.all([ // 严格就绪握手：describe（一元可达）+ 双流 onOpen（物理建立）        this.api.host.describe({}),        Promise.race([streamsOpen, sleep(this.config.streamOpenTimeoutMs, timeout.signal)]), // 超时兜底：永不发 onOpen 的坏代理不能把连接卡死——超时后按已连处理，live-gap repair 补漏      ]) // Promise.all 完成 = describe 成功 + 双流都开（或超时兜底）      timeout.abort()      const descriptionResult = description.result      if (!descriptionResult.ok) { throw new Error(`host.describe failed: ${descriptionResult.error.code}: ${descriptionResult.error.message}`) }      if (ac.signal.aborted) throw new Error('generation aborted during readiness handshake') // 握手期间被 stop/abort → 本代作废，走 catch 分支 // 握手期间被 stop/abort → 本代作废      this.attempt = 0 // 成功一次，退避计数归零      this.emitState('connected') // 去重发射：只在状态变化时通知 UI      if (this.isGenerationActive(ac)) { // state sink 可能同步 stop 掉控制器——不再存在的代不发布 description        this.callSink(() => { this.sinks.onConnected?.(descriptionResult.value) }) // onConnected 触发 SessionManager resync（拉基线）      }    } catch { // describe 失败 / 超时 / abort——都算代际失败，落到共享退避      if (!ac.signal.aborted) ac.abort() // 传输失败 = 代际失败：确保本代被中止后落到共享退避    }    await failed // 等某条流结束——正常路径：一直泵到断连才 resolve // 等某条流结束（正常路径：一直泵到断）    if (!this.isRunning()) return // stop() 已生效 → 干净退出    this.emitState('reconnecting') // UI 立刻看到"重连中"——覆盖整个退避+重试窗口（去重发射） // UI 立刻看到"重连中"——覆盖整个退避+重试窗口    this.attempt += 1    console.warn(`[web-runtime] connection lost, retry #${this.attempt}`)    const idle = new AbortController() // 退避等待的取消控制器：stop() 可以打断 sleep    await sleep(this.backoffDelay(this.attempt), idle.signal) // 指数退避 + 抖动（见下）  }}

handleMuxEnvelope(rpcId: RpcId, frame: MuxFrame): void { // mux 帧到达的分发 switch（Manager-only 入口，UI 永不直接调）  switch (frame.type) {    case 'session/event': { this.acceptLiveEvent(frame.event, frame.view); return } // 会话事件 → 进事件窗口 + 触发 conversation 重建    case 'session/queue': { this.queueMirror.replace(frame.items); this.notifier.markDirty(); return } // 队列镜像整体替换——宿主是权威，客户端只镜像 // 队列镜像整体替换（宿主是权威）    case 'session/subscribed': { // 新 mux 代基线：宿主在同一条流上、subscribed 之后推队列快照      this.subscribedLastSeq = frame.lastSeq      if (this.queueMirror.reset()) this.notifier.markDirty() // 在这里清旧镜像——与 onConnected/resync 时序无竞态（在那两处清可能抹掉已落地的基线） // 在这里清旧镜像——与 onConnected/resync 时序无竞态（在那两处清可能抹掉已落地的基线）      return    }    case 'approval/requested': { // 审批请求到达 → mint 一个 PendingWait（挂起等待宿主侧 resolve） // 审批请求 → mint 一个 PendingWait（挂起等待宿主侧 resolve）      const { type: _type, sessionId: _sid, ...payload } = frame // 剥掉信封字段，payload 才是业务数据      this.mint(new PendingWait('approval', rpcId, this.sessionId, payload, m => this.api.respond(m))) // respond 闭包：用户决策后走 HTTP 上行回宿主 // respond 闭包：用户决策后走 HTTP 上行回宿主      this.notifier.markDirty()      return    }    case 'approval/resolved': { // 审批被（别处）解决 → settle 对应 pending，UI 的等待态消失 // 审批被（别处）解决 → settle 对应 pending，UI 的等待态消失      for (const item of this.pending.values()) { if (item.kind === 'approval' && item.payload.approvalId === frame.approvalId) this.settle(item) } // 按 approvalId 匹配——同一会话可能有多个并发审批      this.notifier.markDirty()      return    }    case 'question/requested': { const { type: _t, sessionId: _s, ...q } = frame; this.mint(new PendingWait('question', rpcId, this.sessionId, q, m => this.api.respond(m))); this.notifier.markDirty(); return } // 提问请求：同 approval 模式——mint + markDirty    case 'question/resolved': { const item = this.pending.get(`q:${frame.questionRpcId}`); if (item !== undefined) this.settle(item); this.notifier.markDirty(); return } // 按 questionRpcId 精确匹配（比 approval 的遍历更直接）    default: return // stream/error 到不了这里（Controller 收敛）；未知帧忽略（文档化的默认行为）  }}

markDirty(): void { // 状态变更入口：标脏 + 排一次微任务 flush  this.dirty = true // 标脏：快照缓存已过期，下次读必须重建  this.notifyPending = true // 通知待发送——与 dirty 是两个独立 bit（pull 不能吞掉 push）  if (this.scheduled === 'microtask') return // 已有微任务在排队 → N 次 markDirty 合并成一次通知（批处理核心）  this.schedule('microtask') // 排一个微任务：flush 时先重建快照再通知 listener}markFrameDirty(): void { // 流式变更入口：标脏 + 每帧最多发布一次累计状态  this.dirty = true // 标脏：快照缓存已过期，下次读必须重建  this.notifyPending = true // 通知待发送——与 dirty 是两个独立 bit（pull 不能吞掉 push）  if (this.scheduled !== 'none') return // 已有更高优先级的调度（微任务）→ 不降级；否则用 rAF 对齐渲染帧  this.schedule(typeof globalThis.requestAnimationFrame === 'function' ? 'frame' : 'microtask')}flush(): void { // 批量 flush：先重建快照缓存，再通知——useSyncExternalStore 要求 getSnapshot 引用稳定  if (!this.notifyPending) return  if (this.listeners.size === 0) return // 无监听者 → 跳过重建（保持帧风暴廉价），下次 getSnapshot 懒重建  this.notifyPending = false  if (this.dirty) { this.dirty = false; this.rebuild() } // 重建在通知之前：保证 listener 看到的快照是新的  for (const listener of this.listeners) listener()}

async prompt(content: PromptContentPart[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>> { // queue = 追加到当前 turn 之后；steer = 打断当前 turn // queue = 追加到当前 turn 之后；steer = 打断当前 turn  this.promptError = null // 清上一轮错误（发送即重置）  this.lastAgentError = null  this.promptAttempted = true // 同步、在第一个 await 之前：blank→engaging 边必须在会话区第一帧可见（首条消息先于导航到达的场景）  if (this.blankBit) this.firstPromptPendingTurn = true  this.notifier.markDirty()  let result: RpcResult<{ accepted: true }>  try {    if (this.address === undefined) { // 普通会话：走 sessions.prompt RPC（上行 HTTP）      result = (await this.api.sessions.prompt({ sessionId: this.sessionId, mode, // 普通会话：走 sessions.prompt RPC（上行 HTTP）；mode 决定排队还是打断 content,        clientTimeZone: resolvedClientTimeZone(), })).result // 客户端时区随请求带上——宿主侧时间戳/调度依赖它    } else if (this.address.mode === 'one-shot') { // one-shot 子代理会话：只读，拒绝发送（错误码 subagent-not-resumable）      result = { ok: false, error: { code: 'subagent-not-resumable', message: 'one-shot subagent conversations are read-only', details: { childSessionId: this.address.childSessionId } } } // one-shot 子代理会话只读——明确拒绝而非静默忽略    } else { // 可续子代理：继续对话走 subagents.prompt      if (content.some(part => part.type === 'image')) { // 图片输入对子代理续聊不可用——检查后明确报错，不静默丢弃 // 图片输入对子代理续聊不可用——明确报错而非静默丢弃        result = { ok: false, error: { code: 'attachment-error', message: 'Image input is unavailable for subagent continuations.', details: { reason: 'SUBAGENT_IMAGE_UNSUPPORTED' } } } // 错误码 + reason 双字段：UI 可展示、程序可分支      } else {        const routed = (await this.api.subagents.prompt({ ...this.address, // 可续子代理：走 subagents.prompt（address 含 childSessionId + mode）          content: content.flatMap(part => part.type === 'text' ? [{ type: 'text' as const, text: part.text }] : []), // 只转发文本部分（图片已被上面拒绝）——flatMap 过滤非文本 // 只转发文本部分（图片已被上面拒绝）          clientTimeZone: resolvedClientTimeZone(), })).result        result = routed.ok ? { ok: true, value: { accepted: true } } : routed // 统一成 sessions.prompt 的返回形状——调用方只面对一种成功形态      }    }  } catch (error) { result = transportError(error) } // 传输层错误（网络断、超时）统一转 RpcResult——调用方不区分业务错/传输错 // 传输层错误统一转成 RpcResult 形状——调用方只面对一种失败形态  if (!result.ok) { this.promptError = { op: 'send', error: result.error }; this.notifier.markDirty(); return result } // 失败：记录错误 + 标脏（UI 显示发送失败）+ 提前返回  if (this.blankBit) { // blank 在"接受"时翻转，不在"尝试"时：宿主判据是已记录的 turn/start（事实而非乐观）    this.blankBit = false // blank → engaged：会话从"空"变成"有内容"——侧栏列表、workspace 复用资格都依赖这个翻转 // 被拒的首条 prompt 必须让会话保持 blank——客户端 blank 镜像只降不升    this.options.onEngaged?.(this) // 通知上层"会话已激活"（侧栏列表、workspace 复用资格等依赖这个事实）    this.notifier.markDirty()  }  return result}

export function bindSnapshotSelector<T>(w: HostObservable<T>): SnapshotSelectorHook<T> { // 入参：裸 observable 源（engine store / Session 对象 / store 实例）  const subscribe = (fn: () => void) => w.subscribe(fn) // 每个源只捕获一次稳定闭包——组件跨渲染永不重新订阅  const getSnapshot = () => w.getSnapshot() // 同理；同时为方法型源重绑 this  return function useSelector<S>(sel: (s: T) => S, eq?: (a: S, b: S) => boolean): S { // 返回的 selector hook：传选择器 + 可选相等函数（默认 Object.is）    return useSyncExternalStoreWithSelector(subscribe, getSnapshot, undefined, sel, eq) // uSES shim：React 官方的外部 store 桥，selector 版——只在选择器的输出变化时重渲染  }}

上行路径（prompt：HTTP RPC）

▼

▼

下行路径（事件：WebSocket downlink）

▼

▼

▼