Host API v0.1

状态：设计基线。本文定义 v0.1 的正式范围；独立的版本协商闭环尚待实现，因此当前运行时不得仅凭已有方法名宣称符合 v0.1。

阅读方式

本页只负责版本级约定和模块索引。每个 Host API 模块都有独立文档，方法、事件、应用场景和用法示例以模块文档为准。

示例统一使用逻辑 JS 绑定对象 host：

const host = await appist.host({ apiVersion: '0.1' });

这行代码描述目标调用形态，不表示当前 SDK 已提供同名入口。原生 WASM 示例使用 C 风格伪代码表达同一逻辑契约；ptr、len 和线协议编码只属于具体绑定，不属于 Host API 语义。

正式模块

v0.1 收录 12 个 L1 模块：

族	模块	典型场景	参考文档
呈现	`canvas`	2D 绘制、软件像素帧、文本度量	`canvas`
呈现	`asset`	读取包内资源、注册包内字体	`asset`
呈现	`playback`	播放应用生成的 PCM 音频	`playback`
输入	`input`	指针、键盘、滚轮和焦点	`input`
输入	`ime`	系统输入法和合成文本	`ime`
输入	`capture`	摄像头帧和麦克风采样	`capture`
数据	`store`	应用作用域持久化 KV	`store`
数据	`clipboard`	系统剪贴板读写	`clipboard`
网络	`net`	经平台代理的有界请求—响应	`net`
身份	`identity`	登录状态和平台托管登录流程	`identity`
平台集成	`env`	粗化环境快照和变化通知	`env`
平台集成	`print`	把文档交给系统打印界面	`print`

八族只是分析工具，不要求首版覆盖每一族。不在上表中的现有方法不构成 v0.1 承诺；候选能力见非正式提议。

版本声明与协商

应用必须声明所需 Host API 版本：

{
  "apiVersion": "0.1"
}

v0.1 宿主必须：

在 /_keel/capabilities.json 公布 apiVersion: "0.1" 和实际方法集合；
发布时校验应用请求的版本；
启动前再次匹配；
不支持时在 guest 执行前以 version-mismatch 失败；
不允许以“部分方法碰巧存在”的方式继续运行。

apiVersion 与应用版本、contractVersion、二进制线协议版本和运行时构建哈希相互独立。

兼容性

v0.1 内可以增加可忽略的返回字段，但 guest 不得依赖未知字段被保留。
新增模块、方法、必填参数或新的失败前提进入后续版本。
删除方法、改变参数含义、收紧既有合法输入或改变可观察副作用属于不兼容变化。
安全修复可以拒绝原本就违反预算、schema 或权限要求的调用。
0.x 不承诺 1.0 级长期稳定，但承诺版本内语义稳定。

共享类型

Bytes       有明确上限的小块字节
ByteSource  大块输入；JS 绑定 Uint8Array，原生 guest 绑定已校验内存区域
ByteSink    大块输出；返回 written / required / eof
Event       经始终存在的类型化事件传输送达
Handle<Resource, Rights, Provenance, Lifetime>

句柄是不透明值。每次使用都必须验证资源类型、权限、来源和有效期；宿主主动失效句柄时发送终止事件。v0.1 不允许把一个模块产生的无类型 token 交给另一模块绕过权限判断。

错误、取消与预算

失败统一使用：

HostError {
  capability: string
  code: string
  retryable: boolean
  data?: bounded-value
}

用户关闭系统选择或确认界面返回空值，不抛错。
权限拒绝使用 denied，版本冲突使用 version-mismatch，预算超限使用 limit-exceeded。
非瞬时调用接受取消信号；取消不得留下不可达句柄。
每个方法执行单次上限、guest 活跃总量上限和时间窗速率上限。

模块文档会列出特有错误和预算维度；具体数值由 v0.1 宿主配置公布。

L0 运行时原语

L0 不参与 capability 声明与信任定档：

原语	语义
`log(level, ByteSource)`	有长度、速率和控制字符过滤的诊断日志
`host_call`	发起一次类型化 Host API 调用
`send_batch`	批量提交运行时消息
typed event transport	将 L1 事件送入 guest；不承载资源授权

now 与 random 尚未完成 v0.1 所需的实现和验证，不属于本版本。

明确不提供

v0.1 故意不提供原始 DOM、Canvas/WebGL/WebGPU context、任意 URL 资源加载、像素读回、屏幕捕获、任意文件路径、原始 socket、WebRTC、P2P、bearer token、全局用户 ID、email、动态代码加载或任意 guest 着色器。

scene、数据库、codec、聊天会话等可在 guest 实现的领域模型属于 L2。缺席是 v0.1 安全契约的一部分，不能作为“遗漏”在补丁版本中加入。

与当前实现的关系

当前各模块普遍使用的 version: "1" 是契约描述版本，不是 Host API v0.1。
当前 media、audio、text 等旧名仍需迁移到 capture、playback、ime。
当前 identity.current、billing.*、ai.chat、analytics.track 不在 v0.1。
当前 asset.decodeBytes({fileToken}) 组合路径必须先完成安全整改。
当前两类 guest 的事件通路必须收敛到统一的类型化事件传输。

宿主只有在名称、逻辑签名、版本握手、策略和行为全部符合本版本文档时，才可以公布 apiVersion: "0.1"。