SpaceSDK Windows API、权限与恢复参考

基线：SpaceSDK 0.1.0-preview.1，2026-09-06，Developer API 1。本文列出公开端口及调用语义；完整字段随包提供于 dist/*.d.ts，仓库链接指向共享 TypeScript 定义。SDK 端口存在不等于 Host 实机验收完成，见交付状态。

1. 入口与公共参数

浏览器入口 @lumii/spacesdk/chat 导出 createNativeApplicationRuntimeContext、createNativeApplicationRuntimePlatform、NativeDeveloperBridgeCallError、mountApplicationChat 和 ApplicationChatController。完整契约与其他类型在 @lumii/spacesdk；两者都是浏览器可打包的 ESM，不包含 Gateway 客户端。SPACESDK_API_VERSION 为协议常量的统一名称，现有 LUMII_DEVELOPER_API_VERSION 保留兼容。

createNativeApplicationRuntimeContext() 返回 { application, platform }；包含 Host 确定的本应用身份及平台端口。
createNativeApplicationRuntimePlatform() 只构造端口，不代表调用者已通过准入，也不代表 Native 方法已执行。
platform.describe(options?) 返回 apiVersion、hostVersion、grantedTechnicalCapabilities 和 unsupportedOperations。
RequestOptions 包含 requestId? 和 signal?。关联 ID 不是业务幂等承诺。
MutationContext 包含必需的 idempotencyKey。同一逻辑变更恢复时保留原键；用户明确发起的新操作使用新键。
PageRequest 为 { cursor?, limit? }；普通分页返回 { items, nextCursor? }。依次消费游标，不自动以第一页替代完整目录。
ApplicationRuntimeIdentity 中的应用/发行/安装引用只用于应用上下文，不是登录令牌，也不授权其他应用。

签名依据：公共类型（仓库参考：packages/sdk/src/developer/common.ts）、平台上下文（仓库参考：packages/sdk/src/developer/platform.ts）、浏览器导出（仓库参考：packages/sdk/src/developer-chat.ts）。

2. Agent/Team 雇佣关联

端口 platform.employments，完整类型见 employment.ts（仓库参考：packages/sdk/src/developer/employment.ts）。

方法	主要参数	技术能力	语义
`listOwnBindings`	`PageRequest?`, `options?`	`employment.read`	只列出本应用、本账号的关联
`getOwnBinding`	`bindingId`, `options?`	`employment.read`	回读精确绑定，检查 active 状态
`requestEmployment`	`employmentId`, `MutationContext`, `options?`	`employment.manage`	请求已声明岗位的配置；由可信 Host/用户选择实际主体
`requestRelease`	`bindingId`, `MutationContext`, `options?`	`employment.manage`	请求解除关联，不删除 Agent/Team
`events`	`{ afterEventId?, afterSequence? }?`, `options?`	`employment.read`	本应用关联事件流
`acknowledgeEvents`	`throughSequence`, `options?`	`employment.read`	确认已处理到的事件序号

变更回执可能是 confirmation_required、configuration_required、active 或 released。收到配置或确认请求不等于已雇佣成功。应用没有全局主体目录或自行批准绑定的接口。

3. 会话、消息与 Team

端口 platform.sessions，完整类型见 sessions.ts（仓库参考：packages/sdk/src/developer/sessions.ts）。

方法	主要参数	技术能力
`list`	`PageRequest?`, `options?`	`session.read`
`listRecoverable`	`{ bindingId?, includeTerminal?, cursor?, limit? }?`, `options?`	`session.read`
`create`	`{ bindingId, label }`, `MutationContext`, `options?`	`session.manage`
`getCreation`	`creationRef`, `options?`	`session.read`
`get`	`sessionRef`, `options?`	`session.read`
`detach`	`sessionRef`, `MutationContext`, `options?`	`session.manage`
`send`	`{ sessionRef, message: { text } }`, `MutationContext`, `options?`	`session.send`
`teamMembers`	`sessionRef`, `options?`	`session.read`
`executeTeam`	`{ sessionRef, memberJobs: [{ memberRegistrationId, objective }] }`, `MutationContext`, `options?`	`session.send`
`getRequest`	`requestRef`, `options?`	`session.read`
`cancel`	`requestRef`, `MutationContext`, `options?`	`session.cancel`
`history`	`sessionRef`, `{ cursor?, limit? }`, `options?`	`session.history`
`subscribeHistory`	`sessionRef`, `options?`	`session.history`
`subscribeRequest`	`requestRef`, `{ afterSequence? }`, `options?`	`session.read`
`acknowledgeRequestEvents`	`requestRef`, `throughSequence`, `options?`	`session.read`

应用仅使用 Host 返回的 opaque 引用，不传底座 sessionKey、运行凭据或 Agent 身份。会话 detach 撤销应用的引用访问，不删除或取消底座会话。已有会话必须先由可信配置入口授权，list 不能扩大历史范围。

history 返回 { messages, nextCursor? }，不是普通 { items }。初始页为最近历史，页内按时间顺序排列，继续游标读取更早的授权历史。

Team 成员来自 teamMembers；memberJobs 是用户明确选择的计划，不能自动全部选中或按名称猜成员。返回的 team.members 保留逐成员状态和授权结果；总请求失败不抹掉已成功成员造成的业务变更。

4. 受理、恢复与订阅

对象	状态及处理
会话创建回执	`creationRef` + `uncertain / ready / failed / detached`；只有 ready 且有 session 时进入正常发送
消息/Team 回执	`requestRef`、`sessionRef`、`delivery`、`runState`；受理与执行完成分别判断
`delivery`	`uncertain`、`accepted`、`not_accepted`；uncertain 不证明没有执行
`runState`	`unknown`、`running`、`completed`、`failed`、`cancelled`
取消回执	`requested`、`already_terminal`、`not_running`；requested 不表示已停止，也不回滚已提交业务事务

恢复顺序：保存原幂等键及返回的引用；有 creationRef 时调用 getCreation，有 requestRef 时调用 getRequest；丢失本地引用时由用户显式进入 listRecoverable 发现原记录；必要时使用原键恢复同一请求。不要定时轮询 Host 存活，不自动换键重建会话或重发可能有副作用的消息。

请求事件只是状态通知。消费 subscribeRequest 后回读 getRequest 获得当前授权结果，处理成功后确认对应序号，并保存恢复游标；不能先确认再处理。subscribeHistory 产生 { sessionRef, revision } 失效通知，收到后重新读取授权历史；它没有请求事件那样的序号确认协议。

Employment/Dock/Schedule 的 events 返回 AsyncIterable，SDK 管理内部回放与订阅；应用处理后调用对应 acknowledgeEvents。不要把所有流都当成相同结构的轮询接口。

AbortSignal 在 Native 一次性请求尚未派发前可阻止派发；已派发后仍等待原 Host 结果，不等于取消 Core 工作。流上使用 signal 停止本地订阅。真正取消使用 sessions.cancel；组件 dispose() 释放本地视图与订阅，不自动删除会话或回滚业务。

5. 业务处理器

完整类型：handlers.ts（仓库参考：packages/sdk/src/developer/handlers.ts）。

platform.handlers.invoke<T>(
  { dependencyId, operation, input },
  options?,
): Promise<T>

需要 business.invoke。dependencyId 必须是本应用签名 manifest 中已声明并实际链接的 Plugin 依赖；operation 是该 Plugin 注册的工具名，input 为应用自有 JSON 对象。Host 不接收应用自报的安装路径、运行身份或任意工具目标。返回结构由 Plugin 定义，调用者必须验证业务结果而不是把泛型当运行时校验。

独立 SpaceSDK 已包含此端口；旧 @lumii/sdk dist 不属于本次交付。不要使用底层 developer_bridge_call 手写兼容绕行。

6. Dock

端口 platform.dock，均需 dock.manage；类型见 dock.ts（仓库参考：packages/sdk/src/developer/dock.ts）。

方法	参数
`listOwn`	`PageRequest?`, `options?`
`requestAdd`	`{ contributionId, idempotencyKey }`, `options?`
`requestRemove`	`dockEntryId`, `MutationContext`, `options?`
`openOwn`	`dockEntryId`, `options?`
`events`	`{ afterEventId?, afterSequence? }?`, `options?`
`acknowledgeEvents`	`throughSequence`, `options?`

只操作本应用已经声明/登记的入口，不接受任意 URL、文件路径或 EXE。确认请求与实际添加/移除的状态须分别展示。

7. 调度：只描述现有有限能力

platform.schedules 需要 schedule.manage。完整字段见 scheduling.ts（仓库参考：packages/sdk/src/developer/scheduling.ts）。

现有接口：getPolicy、create、update、get、list、pause、resume、remove、listRuns、events、acknowledgeEvents。
create 的请求中携带 idempotencyKey；update 还要求 expectedRevision；pause/resume/remove 使用包含二者的 ScheduleMutationContext。
当前 Native 支持符合登记约束的 paused 定义及相关管理；创建 active 返回 UNAVAILABLE，resume 同样因缺少沙箱执行器返回 UNAVAILABLE。
当前源码没有 runNow；旧产物残留的此方法在 Host 返回 METHOD_NOT_ALLOWED。
getPolicy 的正数配额、listRuns 或运行事件类型的存在，都不证明实际执行器可用。
本页的调度限定于第三方应用任务，不代表主聊天/第一方定时任务的功能范围。

首版接入不能依赖这些定义自动执行业务任务；不能把失败降级为假成功或其他调度器。

8. KBrain：可选扩展

platform.knowledge 的类型见 knowledge.ts（仓库参考：packages/sdk/src/developer/knowledge.ts），完整领域语义见KBrain 知识接口契约（仓库参考：docs/kbrain-knowledge-api-contract.md）。不安装该扩展，不妨碍基础业务空间接入。

方法	技术能力
`list`、`search`、`get`、`getProcedure`、`readSource`	`kbrain.knowledge.read`
`propose`、`feedback`	`kbrain.knowledge.contribute`
`getOperation`	当前 Native 要求 read 或 contribute 至少其一，并校验操作归属

这不是业务数据库接口，也不提供原始 Memory/Wiki/Dreaming 管理。独立 SpaceSDK 已包含此端口；Native/Core 对扩展实际可用性、具体版本和授权仍需单独验证。不能凭端口声明宣称 KBrain 服务已完成交付。

9. 错误处理

NativeDeveloperBridgeCallError 包含 code、message、details?、retryable。未知 Host 错误码归一到 INTERNAL，原码保存在 details.hostCode。

code	应用处理
`CALLER_NOT_ADMITTED`	停止继续提交；等待 Host 恢复准入并重新打开应用
`CAPABILITY_NOT_GRANTED`	检查 manifest 和真实授权，提供配置说明
`FORBIDDEN`	检查当前调用者、绑定及业务范围，不借用其他账号权限
`METHOD_NOT_ALLOWED`	当前方法不受支持；禁用依赖该方法的入口
`NOT_FOUND`	精确引用不存在或当前不可读取；回到用户显式选择
`CONFLICT`	检查原请求、参数及 revision，不换键盲目重试
`INVALID_ARGUMENT`	按实际类型校验输入；不补造目标或默认身份
`RESOURCE_EXHAUSTED`	显示真实额度/资源限制，按 Host 规则恢复
`APPROVAL_REQUIRED`	引导到实际可信审批/确认入口，不在应用端自行批准
`CANCELLED`	显示取消状态并回读可能已提交的业务结果
`UNAVAILABLE`	判断依赖不可用、明确未支持或结果未定；有原回执先查原回执
`INTERNAL`	显示失败并记录必要诊断；不要向用户泄漏凭据、路径或原始数据库内容

retryable: true 不授权自动重复副作用操作。退出、切换账号、应用关闭及准入撤销时，终止旧视图订阅并清理旧账号显示状态；不要用本地缓存补回已失权的正文。