Host API 非正式提议

本页不是 API 规范。这里的名字、边界、签名和优先级都未冻结，应用不得声明或依赖本页内容。

进入正式版本前

每项提议必须先提供具体应用、最小用例、不能由已有 API 实现的证据、生命周期、威胁模型、预算和端到端原型。性能理由必须附基准，不接受“可能更快”作为宿主能力的充分理由。

L1 候选能力

提议	当前未准入原因
GPU	共享硬件残留、跨应用 DoS、命令集和着色器边界仍需独立评审
文件输入与持久写回	临时读取句柄和持久写权限生命周期不同，模块边界与命名未定
window / shell	路径、标题、角标和外链的载荷、预算、审计与回跳安全尚未全部成立
lifecycle	事件模型、卸载收尾窗口和后台阶段未定
permissions	只应查询/观察，还是也负责申请资源，职责边界未定
local network	具体设备应用、连接模型、配对、持久授权和审计需要重新确认
bidirectional relay	具体应用和协议未定；“realtime”只描述性能，不描述资源
notifications	内容形状、交互回调、调度和授权生命周期未定
share	与文件输出、剪贴板写和系统 intent 的边界未定
wake lock	真实应用和电量预算未定
scheduler	后台唤醒粒度、配额、持久登记和生命周期未定
credentials	密钥作用域、断言格式、撤销和设备绑定未定
billing	当前没有真实收入应用，服务端能力也未完成
ads	当前广告只在平台启动确认页展示，不需要 guest API；没有应用内广告用例
AI inference	需要先把平台代理推理与聊天、agent、RAG 等 L2 产品模型分开
analytics	当前实现是 no-op；固定目的地、事件 schema、预算、披露和保留策略未定
background compute	是否真的授予额外执行资源尚未证明，可能只是运行时部署或 L2 任务库
gamepad	轮询/事件模型、连接生命周期和手柄震动归属未定
sensors	类型、采样预算、指纹风险和授权状态机未定
geolocation	精度、持续订阅、后台位置和披露未定
XR	没有具体应用，且会同时涉及姿态、显示、输入和共享硬件
intent	应用间调用、文件关联、用户选择和被调方句柄语义未定
canvas accessibility tree	有明确平台价值，但尚无端到端应用验证其事件与焦点模型

双向中继不是 WebRTC 的同义词

若未来出现多人协作或实时游戏需求，优先评估的是经平台中继的有界双向消息或字节流。它不意味着向 guest 提供 RTCPeerConnection、SDP、ICE、STUN、TURN 或任意 P2P。

WebRTC 可以成为宿主内部实现，但只有在对端、IP 暴露、媒体权限和中继策略都被结构性限制时才可讨论。没有具体应用前，不冻结 realtime 这个名字。

ads 的实际场景

设想中的应用内广告能力是：第三方应用声明一个广告位，平台代持广告拉取、渲染和上报，应用不取得广告网络、用户标识或广告内容。

仓库现在实现的是 /a/:uuid 启动确认页上的平台自营广告位。它位于平台自己的页面，不需要任何 guest API。因此 ads 没有进入 v0.1 的理由；若未来真有应用内广告收入需求，再从 manifest 声明、平台组件和 Host API 三种方案中重新选择最小边界。

L2 guest 库提议

以下内容默认不是 Host API：

库	建议依赖的 L1 能力
scene	canvas / 未来 GPU / asset；场景树、动画、剔除和排序留在 guest
database	store；索引、查询、事务组织、CRDT 和页缓存留在 guest
codec	asset.read、文件读取；图片、音视频和压缩编解码留在 guest
chat session	未来推理能力；历史、agent、RAG 和工具编排留在 guest
realtime client	未来双向中继；重连、房间、presence 和应用协议留在 guest

性能不足时怎么处理

L2 出现性能瓶颈时，先测量跨边界调用次数、复制量和宿主等待时间，再补足更低层、可批处理的 L1 原语：

• scene 优先使用每帧一次的二进制 GPU 命令缓冲，而不是把场景树搬入宿主；
• database 优先补页级批量读写、原子 batch、范围扫描或快照，而不是把 SQL 和索引模型固化进宿主；
• codec 只有在基准证明 guest 解码不可接受时，才讨论受预算的宿主原生加速接口。

性能优化不得改变 L1/L2 的职责分界，除非新的证据证明 guest 无法获得所需资源或系统效果。