Developer Docs

文档首页
应用模型Client SDKReact App Kit应用身份与鉴权Web 嵌入Host 集成Skills 与 ExpertsConnectors 与 MCPHARP 应用

开发文档 · 构建应用

Host 集成

设计 Web、Desktop 与 Mobile 宿主能力边界，并在统一 Host Bridge 稳定前选择可执行路径。

状态：Experimental。 AIOS Host 模块与统一 Host Bridge 尚未达到 Preview。本文提供集成边界和当前可执行路径，不承诺未发布的 Host API、方法名或跨端兼容性。跨端 App Manifest 为 Proposed。

目标与适用场景

本页面向需要把智能应用接入浏览器或设备能力的外部开发者，例如文件选择、通知、窗口或剪贴板。它帮助你设计 Host adapter、权限和降级策略，同时避免把实验接口当作生产契约。

如果应用只需要 Thread、Run、事件流与 Consent，不需要 Host Bridge；直接使用 Client SDK或 React App Kit。

Host 的职责

Host 是应用所在环境中受控设备能力的提供方。应用描述意图，Host 决定能力是否存在、参数是否合法、用户是否授权，以及操作能否执行。

Application
    │  结构化请求
    ▼
Host adapter
    │  能力检测 → 参数校验 → 策略 → Consent
    ▼
Web API / Desktop OS / Mobile OS

Host 与 Runtime 不同：Runtime 负责执行 Run、Sandbox workload 或应用生命周期；Host 负责接近用户设备和界面的能力。Host Consent 也不等同于 API Key、短期用户 Token 或 Console Token。

平台边界

宿主当前定位可执行路径不应假定
WebReact 接入为 Preview使用浏览器标准能力和你的 adapter；Fellow 交互走短期 Token存在统一稳定的 Fellow Web Host Bridge
Desktop官方 Application 与参考实现通过公开 SDK 验证交互；HARP 可使用当前 HTTP Runtime 子集官方应用内部能力已经全部公开或跨平台一致
Mobile官方 Application 方向；App Kit 为 Experimental复用公开 Interaction 契约，设备能力封装在自有 adapter已有稳定 Mobile App Kit 或 Host API

Desktop、Web、Mobile 属于 Applications 产品线。它们是 SDK-first 官方应用案例，不是 Developer Platform，也不能作为第三方公共能力存在的证据。

当前可执行路径

1. 先隔离 Interaction

使用 @fellow.work/client 处理 Thread、Run、SSE 与 Consent。不要让 Host adapter 直接依赖 Gateway 私有接口。

2. 定义应用自己的窄接口

在稳定 Host Bridge 发布前，把每项设备能力封装在自己的 adapter 后面。接口应使用结构化参数，并只暴露应用确实需要的最小操作。

例如，应用可以在自己的代码中定义能力查询与调用抽象；这只是你的应用接口，不是 Fellow 已发布 API：

type HostCapability = 'file.open' | 'notification.show';

interface AppHostAdapter {
  supports(capability: HostCapability): boolean;
  invoke(
    capability: HostCapability,
    input: unknown,
  ): Promise<unknown>;
}

3. 默认拒绝并显式授权

对未知能力、未知参数和越界路径一律拒绝。对文件写入、剪贴板读取、外部跳转等敏感或有副作用的操作，在执行前展示具体对象、范围与后果，并允许用户拒绝。

4. 为各端实现 adapter

  • Web adapter 只调用目标浏览器实际支持且符合权限模型的 Web API。
  • Desktop adapter 通过你控制的原生边界执行，并对输入做二次校验。
  • Mobile adapter 遵循目标系统权限和生命周期，不假定与 Desktop 等价。

5. 测试降级

至少覆盖能力不存在、权限被拒绝、用户取消、参数非法、执行超时和宿主重启。业务逻辑不应根据产品名猜测能力。

Capability Discovery

统一 capability discovery 仍在演进。当前应用侧应：

  1. 在实际 Host 上探测自己 adapter 的能力；
  2. 记录能力标识、版本或限制；
  3. 对缺失能力提供无副作用的降级；
  4. 不以 @fellow.work/client 包版本推断文件、窗口或通知能力；
  5. 不把 Experimental 结果缓存为永久生产事实。

本文没有给出 Fellow capability discovery 的请求或响应 Schema，因为尚无可在此承诺的稳定公共契约。

App Manifest（Proposed）

统一 App Manifest 的目标是描述应用身份、入口和跨端能力需求。它尚未稳定，因此：

  • 不要为它虚构文件名、字段或签名流程；
  • 不要把自定义 JSON 当作 Fellow 兼容 Manifest；
  • 不要与 HARP 的 harp.json 混用；
  • 在稳定 Schema 发布前，把能力声明保留在应用自己的配置和 adapter 中。

HARP 与 Host

HARP 当前 Fellow Host 实现覆盖 HTTP Runtime 的部分安装与运行能力。HARP 规范中的 Host API 仍是信息性设计，validate、logs、完整权限强制和非 HTTP Runtime 不能作为统一 Host Bridge 的现成替代。

安全与恢复检查

  • Host 对能力请求默认拒绝。
  • 参数在可信边界内重新校验，不直接执行模型生成的路径或命令。
  • 有副作用的操作具备明确 Consent。
  • Token 与 Host 授权分属不同信任域，不互相替代。
  • 失败结果可区分“不支持”“未授权”“用户拒绝”和“执行失败”。
  • 重试不会重复写入或造成不可逆副作用；无法保证时要求用户再次确认。

相关文档