核心分析¶

项目定位：架构上将责任与边界进行清晰划分——工具负责声明UI资源，宿主负责安全的渲染与通信，App负责呈现逻辑。该分层使得多方实现可以独立演进而保持互操作性。

技术优势¶

• 关注点分离：工具、宿主、App 的职责明确，降低团队间耦合与接口不一致风险。
• 传输/宿主无关：协议设计可运行于多种transport（如stdio），使得Server与Client之间的部署方式灵活。
• 安全优先：默认采用沙箱iframe与可施加的CSP，宿主侧统一管理安全策略，比分散实现更可靠。
• 跨框架可移植：以HTML/JS为载体，配套React/Vue/Svelte等示例，减少为每种客户端重写UI的成本。

为什么优于自行实现¶

1. 节省重复工作：SDK与示例覆盖常见实现细节（通信、认证、版本协商），避免每个宿主/工具重新实现这些通道。
2. 一致性与互操作性：标准化的ui://与通知语义保证不同宿主对同一App有可预期的行为。
3. 集中安全措施：宿主统一受控沙箱减少因实现错误导致的安全漏洞传播。

实用建议¶

• 在需要支持多客户端/多工具的产品中优先采用该协议与SDK。
• 若已有单一受控客户端且对宿主深度掌控，可评估是否仅采用部分约定（例如通信协议），但需承担额外维护成本。

重要提示：协议带来的一致性依赖于宿主采纳率；技术优势在多宿主场景中更明显。

总结：该架构通过标准化边界与提供参考实现，降低重复实现与安全风险，适合需要跨客户端一致交互体验的项目。

核心分析¶

问题核心：上手难点主要在宿主实现与安全配置、跨域资源访问、以及在三方（LLM/工具/宿主）间保持一致的状态同步。虽然SDK与示例降低了App端的学习成本，但宿主侧仍需要较多Web安全与iframe运维知识。

常见坑（基于证据）¶

• 资源托管与CORS/网络问题：ui://指向的HTML/静态资源必须可被宿主正确fetch，跨域配置和CDN设置常导致加载失败。
• 沙箱限制：iframe沙箱会限制API（如本地文件、某些Web API），导致App功能在嵌入环境中不可用。
• 状态同步复杂性：长期会话、重连或断网后状态恢复若无设计，会导致UI与工具状态不一致。
• 安全审查不足：未对第三方App来源进行验证或未施加严格CSP会带来XSS或数据泄露风险。

实用建议¶

1. 用basic-host做端到端测试：先在本地用仓库示例验证App在受控宿主中的行为，覆盖网络失败、版本不匹配、降级路径。
2. 遵循无状态或可重建设计：尽量让App在初始化时通过通知拉取必要状态，并实现幂等的恢复逻辑。
3. 严格宿主安全策略：在宿主配置iframe的sandbox属性、CSP，以及对ui://来源做签名或白名单校验。
4. 优化资源与回退机制：减小bundle体积，预览和提供非交互式fallback，避免在移动端加载失败带来差体验。

重要提示：对非前端工程师而言，宿主实现与安全配置是主要上手门槛，应由有Web安全经验的工程师主导。

总结：结合示例进行端到端测试、设计可恢复的无状态逻辑、并在宿主实施严格的网络与安全策略，是降低集成失败率的关键路径。

核心分析¶

问题核心：宿主是控制第三方App执行与通信权限的关键点，错误配置会导致XSS、数据泄露或宿主被滥用。项目建议以沙箱iframe与宿主侧策略来控制风险。

推荐的宿主安全配置（技术清单）¶

• 强制iframe沙箱属性：使用<iframe sandbox="allow-scripts" ...>仅允许必要能力，避免allow-same-origin、allow-top-navigation等能够扩大权限的标记。
• 严格的CSP：为嵌入的App制定最小化的Content-Security-Policy，限制脚本加载源、禁止内联脚本，限制网络目的地。
• 来源验证与白名单机制：对ui://或HTTP(S)资源进行签名校验或白名单管理，阻止任意URL注入。
• 最小权限通信API：宿主仅暴露必须的bridge方法（例如postNotification、callTool），并对参数做类型和权限校验。
• 能力协商与版本检测：在App加载前进行能力检测（host capabilities），若宿主不支持某些API则提供降级路径。
• 运行时监控与隔离：对异常调用、性能指标或长时间占用进行监控，并能强制回收或隔离问题App。

实用建议¶

1. 从basic-host学习配置：参考仓库示例启动实现的默认策略并逐步加强（例如逐步收紧CSP）。
2. 制定审计流程：对第三方App进行安全审计与签名，部署前做渗透测试与CSP回归测试。
3. 提供降级体验：当App被阻止或宿主不支持时，显示简洁的静态/文本替代视图，保持会话连贯性。

重要提示：允许某些功能时应评估最小化授权，即使功能看似安全，也应采用最小权限原则。

总结：宿主应把iframe沙箱、严格CSP、来源验证与最小权限暴露作为首要策略，并配合能力协商与监控机制来实现既能交互又可控的嵌入环境。

核心分析¶

问题核心：在LLM/工具/宿主/ App四方交互中，若没有明确的状态主权和重建机制，长会话或网络波动会导致UI与会话数据不一致，影响用户体验与业务正确性。

推荐的状态同步架构要点¶

• 单一权威来源（Source of Truth）：把权威状态放在工具/服务器端。宿主和App仅作为呈现与交互层，App在初始化时拉取并渲染该权威快照。
• 幂等初始化与版本快照：服务端提供带版本号的状态快照；App用版本号校验并保证初始化为幂等操作，避免重复应用事件。
• 增量事件流与重放：除了快照外，提供自那一版本起的增量事件（或变更日志），使App能在重连时重放事件恢复到最新状态。
• 能力协商与序列号管理：宿主在连接过程中暴露其能力（例如是否支持持久化channel、离线缓存），并在通知消息中携带序列号以保证消息有序与幂等。
• 心跳与恢复策略：实现心跳检测、重连尝试与重建超时策略；在无法恢复时提供降级视图或提示用户刷新会话。

实用实现步骤¶

1. 在工具端实现状态快照API与事件流（带版本号）。
2. App在加载时调用宿主通知获取最新快照并订阅后续事件。
3. 对所有外部影响状态的操作设计为幂等（或使用事务ID）以便安全重放。
4. 在宿主实现重连代理逻辑，确保消息序列与能力协商在重连后保持一致。

重要提示：若App持有大量本地状态，应在会话内定期将必要快照同步回服务端，避免单点依赖。

总结：以服务端为权威状态源、基于版本快照+增量事件+幂等重放的设计，配合宿主的序列与能力协商，是保证长会话与重连一致性的有效方法。