DEVELOPER DOCUMENTATION
SpaceSDK Windows API、权限与恢复参考
本页目录
1. 入口与公共参数2. Agent/Team 雇佣关联3. 会话、消息与 Team4. 受理、恢复与订阅5. 业务处理器6. Dock7. 调度：只描述现有有限能力8. KBrain：可选扩展9. 错误处理基线：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 不授权自动重复副作用操作。退出、切换账号、应用关闭及准入撤销时，终止旧视图订阅并清理旧账号显示状态；不要用本地缓存补回已失权的正文。