SpaceSDK Windows 接入指南

文档基线：SpaceSDK 0.1.0-preview.1，2026-09-06，Developer API 1。名称及迁移映射见SpaceSDK 首页。独立包从当前源码构建，包含 handlers 和可选 knowledge。旧 packages/sdk/dist 不属于本次 SpaceSDK 交付，见交付评估。下列代码是接入示例，不是已经完成签名安装验收的独立应用。

1. 你的业务空间能否接入

当前可评估接入的具体形态是：签名 Application 包中的 Windows sandboxed-window 页面，通过 Host 登记和打开；业务处理器使用应用声明并链接的既有 Plugin 依赖，业务数据由应用自己拥有。

“无需修改 LUMII 源码”不等于“第三方应用无需开发”。第三方仍需实现工作台、manifest、业务处理器和业务授权，准备可信 Plugin 依赖，并完成接入验收。若需求超出现有接口范围，应登记具体缺口；不能以应用自报账号、原始 Native 命令或 Gateway 凭据绕过边界。

2. 运行前提

1. 用户已进入可准入业务应用的 LUMII Windows Host 会话；Host/Core、适配层数据库及必要依赖就绪。
2. Application 已由可信 DStore 安装流程登记，入口由 Host 打开。直接双击 HTML、用普通本地网页服务打开，或复制文件到安装目录都不建立调用身份。
3. lumii.app.json 声明 Windows 和 developerApi: 1，所需技术能力实际获批。
4. 必需 Agent/Team 岗位由用户在可信 DStore 应用配置中绑定；不是应用自行选择全局账号目录或生成 Agent。
5. SDK 浏览器 JS、类型文件和 Host/Core 来自同一验证组合，业务 Plugin 使用真实、精确的已发布 releaseId。

业务空间不要读取 Host 的数据库连接、路径注册或 Gateway 凭据。应用身份由 createNativeApplicationRuntimeContext() 返回，不由页面填写。

3. 获取与引用 SDK

取得交付的 lumii-spacesdk-0.1.0-preview.1.tgz，并核对同目录 SHA256SUMS.txt。将 tarball 放到自己的项目目录：

npm init -y
npm install --save-exact ./lumii-spacesdk-0.1.0-preview.1.tgz

已有项目无需重复 npm init。本次没有上传公共 npm Registry；实际包名为 @lumii/spacesdk，无运行时依赖。包内包含 ESM、类型、文档和工作台示例，消费项目自行提供 TypeScript/浏览器打包器。

独立消费路径如下：

// 已安装 SpaceSDK tarball 的 TypeScript/浏览器打包环境。
import {
  createNativeApplicationRuntimeContext,
  mountApplicationChat,
} from "@lumii/spacesdk/chat";

业务页面不要使用 @lumii/sdk 默认入口或旧 Node 版 dist/developer.mjs。用浏览器打包器将已安装 SpaceSDK 编入页面，或交付全部所需 ESM chunks。所有引用文件必须进入应用完整性索引，不能运行时从任意 CDN 加载替代版本。SpaceSDK 随包提供 .d.ts；不得混用旧 SDK 的 JS 和新类型。

SpaceSDK 独立示例随包位于 examples/windows-workspace/，包含页面、TypeScript、manifest 模板及生成未签名完整性索引的构建器；按该目录 README 可从已安装包的空项目开始。仓库内旧库存示例仍引用旧 SDK 路径和 dist，它用于说明业务/Plugin 架构，不是本次已迁移或已签名的应用成品；移植时按 SpaceSDK 示例的包导入与浏览器打包方式消费新包。

4. 应用包需要声明什么

直接参考库存示例 manifest（仓库参考：apps/windows/reference-apps/inventory-workspace/lumii.app.json）以及应用包契约（仓库参考：docs/dstore-application-package-and-runtime.md）。它是构建输入，不是可直接发布的模板成品：示例 publisherId 不是你的账号，Plugin releaseId 留空，需要在交付准备中替换为真实身份和发行结果。

如使用完整聊天视图，通常需要 employment.read、session.read、session.manage、session.send、session.history、session.cancel；页面调用业务处理器需要 business.invoke。其余能力按需声明，具体映射见API 参考。不把 KBrain、全局模型管理或任务执行作为基础接入的隐含前提。

5. 初始化与显式选择岗位

初始化只进行一次，失败要显示实际错误。不要在无 Host 的浏览器中伪造 Native 全局对象作为接入方案。

const context = await createNativeApplicationRuntimeContext();
const descriptor = await context.platform.describe();
if (descriptor.apiVersion !== 1) {
  throw new Error("当前 Host 接口版本与此应用不兼容。");
}

const grants = new Set(context.application.grantedTechnicalCapabilities);
for (const capability of [
  "employment.read", "session.read", "session.manage",
  "session.send", "session.history", "session.cancel",
]) {
  if (!grants.has(capability)) {
    throw new Error(`缺少应用能力：${capability}`);
  }
}

// 只读取本应用、本账号已授权的绑定。完整列表需继续消费 nextCursor。
const page = await context.platform.employments.listOwnBindings({ limit: 100 });
// 用 page.items 的 bindingId/displayName/kind/state 呈现选项。
// 用户选择前不取 items[0]，也不按名字推断绑定。

descriptor.unsupportedOperations 是已知明确拒绝的方法列表，不是全部能力保证。当前它只列出 schedule.runNow，不能据此推断 active 调度或 resume 已可执行。

6. 嵌入聊天

下面函数接收用户刚从有效列表中选择的 bindingId。重新读取绑定，确认仍有效，再挂载组件。应用路由离开、切换视图时调用组件的 dispose()；这不会删除底座会话。

async function openSelectedChat(container: HTMLElement, selectedBindingId: string) {
  const binding = await context.platform.employments.getOwnBinding(selectedBindingId);
  if (binding.state !== "active") {
    throw new Error("岗位已失效，请在 DStore 应用配置中检查后重新选择。");
  }
  return mountApplicationChat(container, {
    sessions: context.platform.sessions,
    bindingId: binding.bindingId,
    kind: binding.kind,
    title: binding.displayName,
    label: "业务讨论",
    onError: (message) => { console.error(message); },
    onRequest: (receipt) => {
      // accepted 仅表示受理；以 runState 和成员结果显示真实进度。
      // 成员或请求完成后，重新查询业务处理器取得已提交数据。
    },
  });
}

// 在用户的选择事件中：先 await oldChat?.dispose()，再调用 openSelectedChat。
// 在应用路由卸载中：await chat.dispose()；pagehide 时也应发起清理。

这是 SDK 自带的独立聊天视图，使用 Shadow DOM；不是复制、接管或保证像素一致地复用 LUMII 主聊天页面。当前组件自带控件文案仍有英文，没有可承诺的完整中文本地化选项。需要自有视觉和文案时，使用 ApplicationChatController 或 platform.sessions 构建第三方自己的视图。

Team 模式由用户明确选择当前成员并填写目标，通过 executeTeam 执行；不自动找组长，也不把 Team 请求降级为普通 Agent send。部分成员成功后，即使总请求失败，仍可能已有业务变更，页面须回读实际业务数据。

已有会话接入先由用户在可信 DStore 界面明确选择会话及授权历史范围；应用只能通过 sessions.list() 取得已经授权的 sessionRef。SpaceSDK 没有任意会话 attach(sessionKey) 公共入口，不自动接入最近会话。

7. 页面与 Agent 共用业务处理器

业务 Plugin 使用自己的 Plugin SDK 实现实际工具；SpaceSDK 则让业务页面调用该应用声明并链接的 Plugin。两种 SDK 名称和职责保持分离。

下面仅针对库存参考应用，依赖 ID、工具名和返回格式由该应用定义；它们不是 SpaceSDK 通用库存 API。

if (!context.platform.handlers ||
    typeof context.platform.handlers.invoke !== "function") {
  throw new Error("SDK 产物缺少业务处理器接口，请使用与 Host 匹配的交付版本。");
}
if (!grants.has("business.invoke")) {
  throw new Error("此应用尚未获授 business.invoke。");
}

const result = await context.platform.handlers.invoke({
  dependencyId: "inventory-tools",
  operation: "inventory_application",
  input: { operation: "products.list", input: {} },
});
// 按本 Plugin 的 ToolResult 协议校验 isError/details，然后呈现结果。
// 泛型 T 仅帮助类型检查，不会验证实际返回数据。

调用路径为：业务页面 → SpaceSDK → Host 准入与依赖校验 → 已链接的 Plugin → 应用自有业务逻辑/存储。Agent 则通过既有工具机制进入同一业务处理器。处理器不能信任页面或模型传入的 accountId、安装路径、底座 sessionKey；业务运行范围来自 Host/Core 的受信上下文，并在实际执行时重验。

业务应用自行负责业务授权、输入校验、并发版本检查、事务和业务幂等。SDK 的 requestId 是关联标识，不能代替业务变更的幂等键。库存示例将变更及幂等回执放在自己同一数据库事务中；响应失联不意味着事务回滚。

8. 签名、安装与验证

沿用既有 DStore 流程：准备应用和 Plugin → 以真实用户身份准备发布签名 → 提交具体版本 → 管理端审核 → 发布者显式发布获批版本 → 回读发行结果 → Host 可信安装 → 配置岗位 → 从 Host 打开应用。

Plugin 与 Application 是不同包类型。库存示例要求先发布 Plugin，再用其真实 releaseId 生成 Application 构建输入。示例 build.mjs 生成的目录和 signed:false 回执不是可信安装授权，不能复制到安装目录代替发行。构建方式和依赖要求以库存示例 README（仓库参考：apps/windows/reference-apps/inventory-workspace/README.md）为准。

账号签名、平台发行签名、Host 信任根各自有独立职责；存在一个信任根文件不证明某个包已审核、签名或安装。用户无需另外注册一套开发者账号；管理员审批权限不能由发布签名能力推导。

SpaceSDK 文档与第三方应用包不改变 Windows 产品发布入口。若涉及 Host 更新，必须依照Windows SOP（仓库参考：docs/windows-release-build-install-deployment-sop.md）、分层契约（仓库参考：docs/windows-layered-installation-and-incremental-release.md）、归属锁（仓库参考：apps/windows/windows-package-ownership.lock.json）和Windows README（仓库参考：apps/windows/README.md），不在 SDK 指南中另建产品发布流程。

至少验证：安装与真实账号准入；有效岗位选择；创建会话、真实消息及工具执行；页面与 Agent 看见同一份业务结果；请求失联后恢复；Team 部分成功；账号退出/切换后旧视图失权；更新保留业务数据；卸载遵守用户的数据保留选择。逐项保存版本与实际回执，不能用类型通过、网页可打开或 mock 成功代替。

9. 排查入口

错误码、请求恢复、订阅确认与取消规则见API 参考。