@kmlckj/aios-agent-server-sdk 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,629 @@
-# Temporary Holding Version
+# AIOS Agent Server SDK 0.0.1
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 Node.js 应用的智能体开发 SDK。应用负责自己的界面和业务工具，SDK 提供智能体定义、会话、事件、审批、记忆及本地任务执行。
+
+## 安装与运行
+
+```sh
+npm install @kmlckj/aios-agent-server-sdk
+```
+
+SDK 调用库只发布一份，npm 根据系统和处理器架构自动安装对应的 `@kmlckj/aios-runtime-*` 子包，不下载其他平台的二进制。本次正式交付范围为 Windows x64；其他平台须先完成对应运行时构建和发布，不能使用 Windows 子包。不要使用 `--omit=optional`。首次创建客户端时，将随 npm 安装的运行时归档校验并解压到 `runtime.dataDirectory/runtimes`；这个过程不访问网络、不运行 npm 安装脚本。后续初始化验证并复用同一份文件，升级不会覆盖正在运行的旧版本。
+
+`runtime.directory` 可以省略；显式指定时使用该目录，路径无效会报错，不转用 npm 包。离线交付仍支持安装 SDK `.tgz`、解压已签名的运行时并指定目录。当前版本的 npm 发布是否完成以发布记录为准，本说明不是已上架声明。
+
+- 宿主使用 Node 22.23.2+（22 系列）或 Node 24；运行时系统/架构须与宿主一致。
+- 运行时包含任务引擎、工具实现、内置技能、记忆/任务 Worker、中文 PDF 字体及必要原生资源。
+- 不包含 Node、Git、Python、npm、Bash 发行版，也不依赖 Electron 或 CLI 终端界面。
+- Git/Python/Bash 是按需使用的外部程序；可显式设置路径，否则探测 PATH。显式错误路径会报错，不换用其他程序。Windows 的 WSL Bash 不作为本地 Bash 使用。
+- HTML/Markdown 转 PDF 需要指定已有 Chromium/Chrome/Edge 可执行文件；结构化内容和图片生成 PDF 不需要浏览器。Office 转 PDF 沿用 `document_workflow` 的平台文档服务，需要平台模式和有效账号，不需要本地 LibreOffice 配置。
+- 每次创建客户端前验证可信签名、平台/协议/数据格式及完整文件清单。修改、缺失或多出的文件都会拒绝启动。
+- macOS x64/arm64、Linux glibc x64/arm64 使用各自的原生运行时。历史候选的验收不代替当前源码版本的构建和发布；Mac 包需 Developer ID 签名及 Apple 公证，Linux 包需发布清单签名。
+- HTML/Markdown 转 PDF 需要调用方配置可正常启动沙箱的独立 Chromium。Ubuntu 24.04 的自定义浏览器路径可能需要 AppArmor 用户命名空间授权；本轮两个 Linux 架构使用精确路径临时授权完成验证后已移除规则，没有关闭系统保护或浏览器沙箱。转换错误不会关闭 SDK 宿主。
+
+## 平台模式
+
+```js
+import { createClient } from '@kmlckj/aios-agent-server-sdk';
+
+const client = await createClient({
+  mode: 'platform', appId: 'report-assistant', userScope: 'user-123',
+  appName: '报告助手', platformBaseUrl: process.env.AIOS_PLATFORM_URL,
+  runtime: {
+    dataDirectory: process.env.AIOS_DATA_DIRECTORY,
+  },
+});
+const login = await client.auth.login({
+  loginType: 'USERNAME', account: process.env.AIOS_ACCOUNT,
+  password: process.env.AIOS_PASSWORD,
+});
+if (login.status === 'challenge') throw new Error('需要先通过 auth.completePasswordChange 完成密码修改');
+const models = await client.platform.models.list();
+const agent = await client.defineAgent({
+  id: 'report', version: '1', name: '报告助手',
+  model: process.env.AIOS_MODEL, instructions: '根据真实资料生成报告。',
+});
+const session = await agent.createSession({ workspacePath: process.env.AIOS_WORKSPACE });
+const run = await session.send('读取工作目录中的资料并生成总结。');
+for await (const event of run.events()) {
+  // 用事件驱动自己的界面；审批和补充问题需要调用应用显式回应。
+  console.log(event.type);
+}
+await client.close();
+```
+
+`loginType: 'PHONE'` 使用手机号；可传 `countryCode`。网页登录使用 `auth.startBrowserLogin()`，通过返回对象的 `getAuthorizationUrl()` 获取网址，由应用打开；`wait()` 等待确认，`cancel()` 取消该请求。网页通知和拉起应用是两件事，SDK 不注册系统 URL 协议。
+
+`auth.getToken()` 和 `auth.refresh()` 是显式获取凭据接口，调用方应妥善处理结果。普通配置、用户和资源查询不返回模型密钥。默认凭据仅在会话内保存；需要持久登录时选择 `credentialStore: { kind: 'system' }`，或使用带解锁口令的 `vault`。
+
+平台地址必须是 HTTP(S) 基地址，可包含端口，不能包含认证信息、业务路径、查询或片段。切换平台要在空闲且仅当前客户端连接时调用 `setPlatformBaseUrl()`，重新登录并注册智能体；不同平台历史和凭据隔离。
+
+## 应用托管平台身份
+
+应用已经持有平台登录态时，可以显式选择 `authentication.kind: 'managed'`，由应用提供短期凭证。省略该配置仍使用上述 SDK 登录方式。此模式只用于独立 SDK 宿主，`connectCli()` 保持现有 CLI 账号语义。
+
+```ts
+import { createClient, type ManagedPrincipal, type CredentialProvider } from '@kmlckj/aios-agent-server-sdk';
+
+// principal 来自应用验证后的账号上下文；credentials 由应用实现。
+async function openHostedAgent(principal: ManagedPrincipal, credentials: CredentialProvider) {
+  return createClient({
+    mode: 'platform', appId: 'report-service', userScope: 'report-owner',
+    platformBaseUrl: 'https://your-platform.example',
+    runtime: { dataDirectory: '/var/lib/report-agent' },
+    authentication: { kind: 'managed', principal },
+  }, { credentials });
+}
+```
+
+`principal` 必须明确指定 `userId`、`tenantId`、`workspaceId`；无租户或工作区时填 `null`。回调接收 `{ reason, signal, execution? }`，返回 `{ accessToken, session }` 或 `null`。`execution` 包含可信的 `sessionId/runId/context`，运行请求按它取证；实例级平台查询和显式刷新没有该字段。执行绑定及其嵌套主体被冻结，不能通过回调修改本轮身份。`session` 使用公开 `AuthSession` 类型，必须与 Token 中的用户、租户、工作区以及配置的平台一致。SDK 校验身份绑定和有效期，平台仍负责校验 Token 签名及业务权限。
+
+| reason | 应用需要处理的情况 |
+|---|---|
+| `initial` | 首次获取凭证 |
+| `expiring` | 缓存凭证距离过期不足 30 秒，需要续期 |
+| `rejected` | 平台返回 HTTP 401，需要重新获取凭证 |
+| `explicit` | 应用调用 `client.auth.refreshManaged()` 主动续期或恢复授权 |
+
+- 回调和 Token 只保存在内存，通过经过认证的本机私有连接供 SDK 宿主及产品执行进程使用；SDK 不接收或管理 refreshToken、密码。应用可在自己的凭证服务内完成刷新。
+- 同一执行上下文的并发请求共用一次续期；不同会话/轮次/业务上下文分别取证和缓存，不复用实例查询的凭证缓存。内存最多保留 128 个空闲凭证上下文，淘汰后重新向应用取证；正在取证的请求不受这个缓存容量限制。HTTP 401 只允许使用新凭证再发送一次；再次被拒则撤销授权。普通服务错误、网络结果未知、流式上传不会被这层自动重放。
+- 默认只向 `platformBaseUrl` 的 origin 发送平台凭证。模型网关等服务使用不同 origin 时，应用须在 `authentication.allowedOrigins` 明确配置 HTTP(S) origin。带平台凭证的请求不自动跟随重定向。
+- `auth.refreshManaged()` 返回公开会话；`auth.revokeManaged()` 撤销本机托管授权，不等于注销平台账号或回滚已发出的请求。返回 `null` 同样撤销；恢复须显式续期。托管模式不允许密码/网页登录、身份切换以及 `getToken()` / `refresh()` 导出凭据。
+- 一个实例绑定一个平台主体，不能在续期时更换用户、租户或工作区，也不能通过 `configure()` 切换认证方式或平台；需要时创建新客户端。主体同时参与数据目录分区。实例重启后必须重新提供回调，不能从历史恢复 Token。
+- 每个实例只能有一个在线凭证提供者。其他客户端可以不传 `credentials`，作为同配置观察连接。提供者客户端必须在任务和后台工作仍需要平台授权时保持存活；其 `close()` 会关闭回调，后续平台请求将返回真实授权错误。工具授权错误仍作为工具结果交给模型处理。
+
+`auth.refreshManaged()` 会清除全部旧上下文缓存，并取消尚未完成的旧取证；晚到的旧回调不能恢复授权。`auth.revokeManaged()` 对整个提供者生效，不因缓存淘汰而重新启用。
+
+注册回调的客户端可用 `client.auth.managedEvents({ after?, signal? })` 观察授权变化。事件包括 `authorized` 和 `invalidated`，携带原因、作用范围、对应执行绑定和过期时间或错误码，不携带 Token 或回调异常文本。`scope: credential` 表示一个缓存凭证（无 `execution` 时为实例查询凭证），`scope: provider` 表示整个提供者被撤销或关闭。缓存凭证自然过期时，即使没有新请求也会通知；SDK 不在后台自行续期。平台提前撤销凭证仍需下一次实际请求返回 401 才能被发现。
+
+事件保存在提供者进程内，最多 256 条，支持游标续读；游标过期或属于另一提供者时明确报错。中止观察不会撤销授权。普通观察客户端没有该私有事件流；宿主可将其转成自己的前端通知，不把它伪装成某个任务的执行事件。
+
+托管授权已贯通 SDK 平台查询、模型目录、模型请求、额度检查、用量上报、内置插件进程以及共享资源/记忆请求的网络层。运行上下文继续传到凭证回调；后台记忆从原始消息按轮次分批，延迟工具计量保留原轮次绑定。一个实例仍只绑定一个 actor；owner 和平台业务归属由宿主验证后逐轮提供。本轮没有完成文件访问根限制，也不能把同一实例用于不同账号或租户。
+
+## 无平台账号模式
+
+```js
+const client = await createClient({
+  mode: 'standalone', appId: 'inventory', userScope: 'operator-1',
+  runtime: { dataDirectory },
+  models: [{
+    id: 'primary', endpoint: process.env.MODEL_ENDPOINT,
+    model: process.env.MODEL_NAME, protocol: 'chat_completions',
+    apiKey: process.env.MODEL_API_KEY, contextWindow: 300000,
+    functionCalling: true,
+  }],
+  builtins: { tools: false, skills: false },
+});
+```
+
+独立模式不构造平台登录、市场或知识库服务；只向指定模型提供方发送模型请求。支持 `chat_completions` 和 `responses`。平台查询会返回 `PLATFORM_UNAVAILABLE`。平台模式默认开启内置能力，独立模式默认关闭，可以分别选择。
+
+独立模式已接入本地文件/文档、Git/工作树、自动化、记忆、应用技能和原生电脑操作等共享服务。平台知识库、平台模型媒体服务、平台市场及 Office 转 PDF 的平台文档服务需要平台模式。独立模式不加载 `document_workflow`，不会自动访问平台或改用本地转换器；其他本地文档和 PDF 工具仍按选用范围提供。电脑操作仍需选择对应内置工具，并满足操作系统权限与模型能力要求。
+
+## 连接已有完整 CLI
+
+```js
+import { connectCli } from '@kmlckj/aios-agent-server-sdk';
+const client = await connectCli({
+  dataDirectory: cliDataDirectory, appId: 'my-app', userScope: 'operator-1',
+  builtins: { tools: true, skills: true },
+});
+const agent = await client.defineAgent(definition);
+const session = await agent.adoptSession(existingCliTaskId);
+```
+
+CLI 必须运行支持 SDK 协议及能力选择的构建；旧版本没有 `/sdk` 接口时明确返回 `SDK_UNSUPPORTED`。连接不会安装、启动、升级、切换账号或停止 CLI。认证沿用已有 CLI 当前账号，应用可查询登录状态。全局平台/资源路径配置仍由 CLI 管理。
+
+采用历史任务须空闲，保留原 ID、消息、工作目录、附件及产物；应用绑定与能力快照持久化，不能将另一应用任务再次绑定。采用时默认设置独立记忆范围并关闭读写；需要共享时可显式传 `adoptSession(id, { policy })`，不会复制旧范围的长期记忆。关闭连接不关闭 CLI。CLI 恢复应用任务时继续遵守保存的能力上限；应用回调工具离线时将真实错误交给模型处理，任务仍可继续。
+
+## 能力、技能与业务工具
+
+长工具结果由共享运行时保存，模型收到预览与 `next` 续读引用。外部 MCP 和应用回调同样适用，读取已有结果不会再次执行回调。结构化 MCP 输出在代理侧明确声明“原结果或归档引用”两种形式；完整业务数据可从归档读取，图片等非文本块保持原类型。
+
+续读使用 `aios_tool_results.read_tool_output`，参数为本任务的 `output_id` 与字节 `offset`。它是已启用工具的结果交付服务，只能读取本任务产生的托管结果，不接受任意文件路径；关闭内置文件工具不会启用 `read_file`。没有任何 AIOS 工具或外部提供者时，不启动该服务。
+
+单份文本结果、每路命令日志的保存上限为 64 MiB。命令日志保留退出状态和独立的完整性标记；容量不足、磁盘错误或内容已清理都会明确返回，不自动重跑原操作。结果保存在工作目录的 `.aios/tool-output/<任务范围>/` 下，随该目录管理；不会在任务刚结束时删除，以便历史任务继续读取。
+
+```js
+const catalog = await client.capabilities({ kind: 'tool', category: 'documents' });
+const dependencies = await client.dependencies();
+const skills = await client.skills.importPaths([absoluteSkillDirectory]);
+```
+
+`enabled` 表示能力选择结果；`available` 表示当前模式、实现和依赖是否满足，并提供 `reason`。平台权限、模型能力、外部服务连接仍在实际调用时验证。`pdf_artifact.operations` 单独列出 HTML/Markdown 转换依赖；`document_workflow.operations` 的 `office-to-pdf` 表示平台办公文件转换，独立模式返回 `requires-platform`，平台模式关闭工具时返回 `disabled`。
+
+Office 转 PDF 通过任务调用共享内置工具，工具参数为 `{ action: 'analyze', file: '报告.docx', outputs: ['pdf'] }`，同样适用于平台服务支持的 Excel、PPT 文件。转换会上传源文件至当前配置的平台文档服务，并将校验后的产物保存到任务工作区；不依赖桌面渲染，也不新增 `libreOfficeExecutable`。例如向已登录平台模式的会话发送：
+
+```js
+const run = await session.send('使用 document_workflow 将工作目录中的报告.docx 转为 PDF，保留原文件。');
+```
+
+按需启用 `document_workflow` 或 `documents` 工具分类；等待、续查、产物下载和服务错误均沿用桌面端、CLI 的共享执行链。服务未部署、权限不足或转换失败时将真实错误返回模型，不自动换平台、不改用本地程序，也不重放已提交的转换。
+
+工具分类：`workspace`、`process`、`repository`、`web`、`documents`、`data`、`media`、`knowledge`、`memory`、`task-coordination`、`automation`、`computer`、`extensions`。
+
+技能分类：`development`、`documents`、`data-research`、`design`、`media`、`business`、`automation`、`agent-building`。来源和接入方式通过 `source`、`integration` 单独标识。
+
+`builtins.tools` / `builtins.skills` 只控制 AIOS 自带的工具和技能，可以是布尔值，也可以是 `{ categories, include, exclude }`。设为 `false` 时不加载：不注册工具、不启动对应可选服务，不生成、发现或注入内置技能。AI 运行时原有工具、技能及应用自定义扩展不受这两个开关影响。
+
+分类与 include 取并集，减去 exclude，再与上层允许范围相交。客户端、智能体、会话只能逐层缩小 AIOS 内置能力范围；已有会话不会因目录增加而扩大该范围。`session.configureBuiltins()` 在空闲时调整保存的范围，关闭后续接仍保留原历史和文件。
+
+智能体的 `skills` / `plugins` 是默认显式资源引用，单轮 `send()` 可覆盖；本地技能可通过 `client.skills` 导入、列出、移除。技能开启不会替你开启它需要的工具。
+
+业务工具通过 `AgentDefinition.tools` 注册，提供 `name`、`description`、JSON Schema `inputSchema`、`readOnly` 和 `execute(input, { signal, callId })`。使用现有 MCP、权限、审批和取消链。默认权限下只读工具自动执行，写工具等待审批；完全权限遵循现有本地规则。回调函数及凭据不写入任务历史。
+
+普通字符串和 JSON 返回值仍作为文本交给模型。需要图片、文件内容或明确的业务错误时，使用公开的 `toolResult()`：
+
+```ts
+import { toolResult } from '@kmlckj/aios-agent-server-sdk';
+
+return toolResult({
+  content: [
+    { type: 'text', text: '报告已生成' },
+    { type: 'resource', resource: {
+      uri: 'file:///workspace/report.md', mimeType: 'text/markdown', text: '# 报告',
+    } },
+  ],
+  data: { operationId: 'export-123', status: 'succeeded' },
+});
+```
+
+图片内容为 `{ type: 'image', mimeType, data }`，`data` 是 base64。文件资源由回调提供 `text` 或 base64 `blob`，SDK 不根据 URI 自动读取或下载文件。`data` 被编码为模型可见 JSON 文本；外部操作仍由应用按其 `operationId` 查询，SDK 不自动重放。返回 `toolResult({ content: [], error: { code, message, details } })` 会标记工具失败并交给模型处理。
+
+`agent.providerStatus()` 查询该版本提供者是否注册，不代表外部 MCP 服务可达。`agent.unregisterProvider()` 仅允许注销当前客户端自己的注册；当前运行保持既有快照，后续运行会重新加载工具目录。调用 `defineAgent()` 可重新注册相同定义和版本。回调服务随 `client.close()` 关闭；注销不删除历史，也不取消任务。
+
+## 会话、执行和恢复
+
+- `agent.createSession({ name, workspacePath, creationId })`：稳定的 creationId 防止重复建任务。
+- `client.listSessions()` / `openSession(id)`：列出和打开当前应用的会话。
+- `listSessions({ scope, includeArchived: true })` 包含指定范围的归档会话。`session.rename(name, expectedRevision)`、`setArchived(archived, expectedRevision)` 使用 `SessionInfo.metadataRevision` 并返回新的会话信息；旧版本返回 `SESSION_CONFLICT`。归档保留历史和文件，但不能继续发送、重启或新增排队消息；恢复后可继续原任务。归档前必须结束活动执行、后台进程、交互和队列。
+- `session.send(content, options)`：模型、权限、模式、思考、上下文、附件、文件/表格/文本引用、技能/插件均支持按轮设置。
+- `session.configuration(revision?)` / `configure(defaults, expectedRevision?)`：读取当前或已保存版本，修改会话默认值；上下文/思考等级可用 `null` 重置。
+- `session.configureBuiltins(selection, expectedRevision?)`：调整该会话内置能力。配置冲突返回 `CONFIGURATION_CONFLICT`；目标会话有运行、待处理交互或排队消息时返回 `SESSION_BUSY`。
+- `session.history()` / `artifacts()` / `compact()`：历史、产物及上下文压缩。
+- `session.enqueue()`、`queue()`、`editQueued()`、`removeQueued()`、`reorderQueue()`：排队管理，写操作携带读取到的 `queueVersion`，过期版本明确拒绝。
+- `dispatchQueued(messageId, queueVersion, targetRunId)`：传活动 runId 作为本轮补充指令；传 `null` 开始新轮。所有操作复用持久命令回执。
+- `run.events({ cursor, signal })`：增量事件；处理完一条后可保存其 `cursor`，下次从该位置恢复。用事件 `id` 去重；`sequence` 是该游标流内的顺序号，`runtimeSequence`（若存在）保留运行时原始序号。事件还包含 `schemaVersion: 1`、`sessionId`、`runId`。
+- `session.events({ cursor, signal })` / `eventPage()`：跨轮观察整个会话，保留一轮结束后才到达的积分等更新。事件保留工具详情、子线程/团队标识和可信业务 `context`，不会在一轮完成时关闭。详见 [事件与前端接入](EVENTS.md)。浏览器入口 `@kmlckj/aios-agent-server-sdk/events` 提供同源工具短句辅助函数及事件类型。
+- `run.wait({ signal })`：等待当前运行完成或需要用户输入；`waiting` 不表示任务完成。`events`、`wait`、`state` 的 AbortSignal 只取消观察，不发送任务取消命令。
+- `run.approve()` / `answer()` / `confirmPlan()`：审批、补充回答、计划确认。
+- `run.cancel()`：仅取消该 runId；不会误取消之后开始的运行。
+- `session.receipt(commandId)`：发送结果丢失时查询原命令；不换新 ID 自动重试副作用操作。
+- `session.resumeRun(runId)`：重新观察原轮次；无需再次发送用户问题。
+- `session.runs({ cursor, limit }, signal?)` 分页读取当前会话的运行记录，包含真实状态、消息数、消息/队列/终态时间和可信业务上下文。时间字段分别对应原日志，不冒充模型请求开始时间。列表派生自既有消息、终态索引和队列，不新增运行数据库；没有终态证据的旧执行显示 `interrupted`。列表有变化或游标跨会话时返回 `RUN_LIST_CONFLICT`，从首屏重新读取；单轮详情继续用 `resumeRun(id).state()/events()`。
+- `session.queryHistory({ text, around, cursor, limit })`：分页搜索或定位消息。`clear({ historyVersion, cancelActive })` 清空目标会话的消息、事件、交互、原生上下文和阶段交接；`delete(...)` 删除会话记录。两者保留业务文件；自动工作区删除后移动至返回的 `retainedWorkspace`，其他会话仍引用该目录时拒绝移动。`historyVersion` 来自 `queryHistory()` 或 `queue()`，活动任务需要明确 `cancelActive: true`。
+
+`send()` 默认后台执行；`execution: 'foreground'` 将运行租约绑定到发起进程，进程意外退出后取消该轮，审批等待时按 CLI 规则解除前台限制。`timeoutMs` 为 0（不限时）或 1000 到 604800000 毫秒。`run.detach()` 和正常 `client.close()` 会解除前台关联，保留任务及其执行期限。观察者不会获得提交者的租约。
+
+`client.close()` 只断开客户端并关闭自己的业务回调；有后台任务/记忆/已启用自动化时宿主继续运行。`client.shutdown()` 只允许显式停止独占且空闲的精简运行时；不允许停止复用的 CLI。
+
+重启后，所有任务都可以继续。业务工具或外部 MCP 提供者未在线时，将 `APPLICATION_PROVIDER_OFFLINE` 能力错误交给模型处理，模型可根据历史与其他能力继续，不能在外围阻断任务。应用要恢复这些工具的实际调用时，再通过 `defineAgent()` 注册同一 ID/版本和定义；修改角色定义需增加版本，不会改写已有会话的角色。
+
+精简 SDK 宿主的事件读取和状态等待支持最长 15 秒的事件唤醒等待；状态等待只关注生命周期变化，逐字输出不会触发重复状态读取。慢业务请求不会挡住状态读取、审批和取消。连接未声明该能力的旧宿主或现有 CLI 时，保留原观察协议。
+
+## 服务端角色与会话版本
+
+服务端应用可以在 `AgentDefinition` 中显式设置 `profile: { host: 'server', role: 'personal' | 'task' | 'coding' }`。它只改变宿主身份提示；角色、人设和业务要求继续由 `instructions` 与专家定义提供，不增加工具、文件或账号权限。不传 `profile` 时保持原提示行为。
+
+升级已有会话前，先注册新的 Agent 版本，再显式更新目标会话：
+
+```ts
+await client.defineAgent({ ...definition, version: '2', instructions: '新的业务规则' });
+const current = await session.configuration();
+await session.updateAgent({
+  agentId: definition.id, agentVersion: '2', expectedRevision: current.revision,
+});
+```
+
+更新只要求目标会话空闲，不要求其他会话停止。保留会话 ID、历史、工作区和原创建回执，旧配置可按 revision 查询；新版本的工具上限仍受客户端上限约束。无效配置和过期 revision 在停止目标执行进程前被拒绝。提供者变化在下一轮执行时生效，当前运行保持原快照。
+
+`AgentDefinition.rules` 可以提供 `{ id, version, scope: 'application' | 'project' | 'session', text }`，随角色配置形成版本快照，并作为带来源的规则进入运行指令。
+
+`send(..., { context })` 为本轮绑定不可变的 actor、owner、workspaceId、usageScene 和可选平台业务关联。托管模式的 actor/租户/空间必须等于该实例绑定主体；平台负责委托授权。业务工具回调的 `ToolContext.execution` 提供只读 session/run、invocationId 和该上下文，不能被模型参数覆盖。不同上下文的队列项不能插入同一活动轮；`run.context()` 可以读取保存的关联。
+
+新会话的默认记忆策略是独立范围且不读不写。显式启用示例：
+
+```ts
+const session = await agent.createSession({
+  policy: {
+    scope: 'project-a:assistant-x',
+    memory: { scope: 'project-a:assistant-x', read: true, write: true },
+  },
+});
+const memory = await session.memory.get();
+```
+
+相同 memory scope 表示应用明确授权共享；SDK 不因同一个账号而推断两个助手或项目应该共享。作用域用于记忆检索、提取、编辑、reset 和后台整理。`session.memory` 自动携带会话 ID；`client.memory` 要求显式 `sessionId`。`client.listSessions({ scope })` 可按业务范围筛选，但应用仍须鉴权，不能把筛选字段当成独立的跨租户访问控制。旧会话未携带策略时保持既有行为。
+
+每轮可进一步缩小记忆权限，不能扩大会话授权或更换记忆范围：
+
+```ts
+const run = await session.send('本轮内容不要写入长期记忆', {
+  memory: { write: false },
+});
+const effectiveMemory = await run.memoryPolicy();
+```
+
+权限快照与运行一起持久化，排队、重启、规划确认和压缩保留原权限。不同权限的消息不能插入同一活动轮。自动召回和记忆工具按当前轮次检查读取权限；后台提取按原始消息的轮次检查写入权限，跳过的轮次不会在以后补写。任务原始历史保留，历史检索不受长期记忆读写开关影响。
+
+自动化沿用来源会话的能力上限。来源采用默认独立范围时，每次创建的新任务获得自己的范围；来源显式指定共享策略时，自动化继承该策略。范围在任务文件首次落盘前写入，新的自动化轮次不会复制来源任务的平台执行上下文。此前已持久化且没有策略的旧 SDK 记录保留原语义。
+
+SDK 的实施和验证记录见 `docs/SDK-云端托管实施记录-2026-10-22.md`。云端业务宿主、页面、部署与账单对账需要接入方独立验收；下面的接口不代替这些接入工作。
+
+### 受控成员与独立后台会话
+
+`AgentDefinition.team` 随 Agent 版本保存，使用已有任务拆分、成员线程和协作存储：
+
+```ts
+const agent = await client.defineAgent({
+  id: 'review', version: '1', name: '核查助手', model: '平台模型 ID',
+  instructions: '拆分工作，委派成员核查，并根据实际结果汇总。',
+  team: { members: [{
+    id: 'reader', name: '资料核查员', instructions: '读取资料并报告发现。',
+    tools: ['read_file', 'repository.git_preferences'],
+    reasoningEffort: 'high',
+  }] },
+});
+const session = await agent.createSession({ name: '核查任务' });
+const run = await session.send('请委派 reader 核查 input.json，然后汇总。');
+const state = await session.teamState();
+```
+
+成员可指定独立 `model`、`reasoningEffort`、AIOS 工具选择及 `paths`。未指定模型时继承父轮选择，模型网关与用量关联仍独立。工具与父级已启用能力取交集：普通工具用 ID，分组工具也可用 `namespace.name`，外部 MCP/业务工具用 `mcp__serverKey__toolName`。未指定 tools 时继承；空数组不加载可选 AIOS/MCP 工具，保留父级已提供的共享任务读写控制。成员不能再次委派团队。此选择不关闭执行引擎自身工具；文件系统限制通过 `paths` 声明。
+
+`paths` 的读写根只能缩小父级范围。没有显式目录策略时继承普通任务沙箱；显式策略进入原生权限配置，Windows 限制见下文。外部 MCP 服务和应用回调是受信任扩展，其自身进程隔离由部署方负责，工具白名单不等于操作系统沙箱。
+
+Windows 沙箱模式属于整个执行组件，父任务和成员不能声明互相冲突的 `windowsSandbox`；此类配置在启动任务前明确拒绝。
+
+模型使用已有 `task_create/team_delegate/team_follow_up/team_wait/team_close` 完成协作。应用也可对当前活动轮调用 `run.team(command, { signal })`：`task.create`、带 `expectedRevision` 的 `task.update`、`delegate`、`followUp`、`wait`、`stop`、`close`。返回 `TeamCommandResult { success, contentItems }`，能力或执行失败保留结构化错误；错误不会自动取消父任务。过期 run ID、不可用宿主和跨会话控制会明确拒绝。`stop` 等待实际中断结果；`close` 只关闭已空闲的成员。
+
+父任务等待所属成员收敛，成员结果只向模型交付一次；应用调用 wait 观察结果不会消耗模型的结果。宿主排空时允许 wait/stop/close，不接受新委派。`teamState()` 无活动宿主时读取真实保存状态并返回 `ownerAvailable: false`；没有历史状态时返回 null，不伪造成功或重放任务。中断成员再委派时先恢复原线程与当前路由。
+
+独立后台工作使用普通 Session，与父轮内的成员分开管理：
+
+```ts
+const background = await session.createBackgroundSession('reader', '业务唯一创建 ID');
+const backgroundRun = await background.send('核查后台资料');
+// 可独立观察、等待或取消；父任务结束和取消不会自动取消它。
+const result = await backgroundRun.wait();
+const parent = (await background.configuration()).parent;
+```
+
+父关系保存来源 session/member/配置修订。后台会话固定使用创建时的角色和权限，不随父配置升级而变化；它有自己的本地运行 ID，不能把本地 ID 改成平台任务 ID。应用自行提供该后台轮的业务 `context`。回调工具缺少提供者时，任务仍能继续，错误返回模型；重新注册来源 Agent 提供者可恢复相应工具。
+
+### 异步操作查询与取消
+
+`session.operations({ runId? })` / `run.operations()` 列出实际已启动的受管进程、文档任务和媒体任务引用，不创建第二套任务队列。引用包含 `id/sessionId/runId/kind/ownerId/createdAt`。
+
+```ts
+for (const reference of await run.operations()) {
+  const operation = await run.operation(reference.id, { signal });
+  if (operation.status === 'running' && operation.canCancel) {
+    await run.cancelOperation(reference.id, { signal });
+  }
+}
+```
+
+查询使用原操作的主体和业务关联，并重新取得有效凭证；不会重新生成、重新计费或采用下一轮的项目归属。状态为 `running/completed/failed/cancelled/unknown`，附实际响应、查询时间及不可查询原因。文档和媒体服务目前没有可用取消接口，返回 `canCancel: false`；调用取消会明确失败，不能把停止等待伪装成服务已取消。进程优先查询实际所有者，宿主退出后读取真实终态；缺少终态返回 unknown，不猜测已结束。已失去所有者的进程不能通过历史引用重放或取消。成员只能观察和停止自己的受管进程。
+
+`operation.result` 可能含有会过期的服务下载 URL。应用需要下载产物时按原服务契约处理；SDK 不把任意字符串当 HTML 或公开链接。已经实际交付到工作区的文件仍通过 `run.artifacts()` 查询，并保留来源、验证范围和文件版本证据。
+
+## 路径与存储
+
+`runtime.dataDirectory` 保存宿主状态；可分别设置 `workspaceDirectory`、`cacheDirectory`、`temporaryDirectory` 三个绝对目录基址。每个基址仍按应用和主体分区，`getConfiguration().paths` 返回实际目录。新自动任务使用配置的工作区；已有任务继续使用原来保存的路径，不自动迁移文件。缓存清理只处理受管理的缓存，保留工作文件。任务执行子进程的 TEMP/TMP/TMPDIR 使用实际临时目录。
+
+```ts
+const session = await agent.createSession({
+  workspacePath: '/workspace',
+  policy: {
+    scope: 'assistant-a',
+    memory: { scope: 'assistant-a', read: false, write: false },
+    paths: { cwd: 'projects', readRoots: ['.'], writeRoots: ['projects'] },
+  },
+});
+```
+
+相对授权根和 cwd 按 workspacePath 解析；cwd 必须是其中已存在的目录。文件工具按 cwd 解析相对路径，写入前检查真实父目录和符号链接。SDK 状态目录可以位于平台根目录内，但不能被文件工具读取、修改或搜索；显式附件与已登记技能资源保留既有只读授权。未配置 `paths` 的历史任务沿用原有行为。
+
+声明路径策略后，原生命令及 AIOS 受管命令使用同一份原生权限配置，恢复、分叉和后续轮次不会因“完全访问”放大目录授权，只读成员保持只读。当前 Windows 非提权沙箱无法执行分离的读目录或 deny-read 限制，会返回工具失败，不转为无沙箱执行。`windowsSandbox: 'elevated'` 仅供部署方已经配置相应系统沙箱的机器，本 SDK 不自动提权或创建系统账号；本机未验收该模式。
+
+数据分析、UI 和矢量产物工具中的模型脚本，在声明目录策略时也通过同一原生受控命令入口运行。拒绝执行会返回真实工具错误，不改用普通进程启动。应用注册的回调、第三方 MCP 和扩展代码运行在其自身宿主内，须由应用配置相应文件系统/容器边界。
+
+目录契约不能替代部署的挂载、账号及容器隔离。应用回调、外部 MCP 和宿主提供的 Hook 属于受信扩展，它们必须自行遵守宿主授权；不能把 JavaScript 路径检查当成任意外部程序的操作系统隔离。
+
+## 命令 Hook
+
+`AgentDefinition.hooks` 是版本化命令声明，随会话配置快照在下一轮执行组件启动时生效。SDK 只授权本次显式声明的命令，不授权机器上其他用户或项目的 Hook。
+
+```ts
+hooks: [{
+  event: 'PreToolUse',
+  matcher: 'write_file',
+  command: 'node /opt/app/check-tool.mjs',
+  commandWindows: "& 'D:/app/node.exe' 'D:/app/check-tool.mjs'",
+  timeoutSeconds: 10,
+}]
+```
+
+命令从 stdin 接收原生 JSON，stdout 返回原生 Hook JSON；Windows 使用 PowerShell 语法，带引号的程序路径需要 `&` 调用。事前工具 Hook 可明确拒绝或通过 `updatedInput` 改写参数；事后 Hook 可追加反馈，但不能撤销已发生的副作用。实际开始、结束和失败继续通过 SDK 执行事件传出。
+
+`timeoutSeconds` 仅限制这一次 Hook。命令异常退出或超时会产生失败事件，原生执行器不会因此自动阻断工具；需要拒绝时必须返回明确的拒绝决策。Hook 不替代文件权限、敏感保护和工具审批。`Stop` 是模型收尾阶段，不是 SDK run 的最终完成通知；业务完成应使用运行终态。原生 Hook 的 thread/turn/tool-use 标识与 SDK/平台业务标识分别保留，通过实际执行事件关联，不混用。
+
+## 平台资源版本与授权
+
+- `client.plugins.install/update/setEnabled/remove` 复用 CLI 的安装仓库和版本检查；更新要求当前记录的 `expectedRevision`，保留来源与开关。
+- `client.platform.plugins.getAuthorization/saveAuthorization/verifyAuthorization/revokeAuthorization` 保留平台真实授权状态。表单保存不会自动验证；回调模式返回平台授权页面，应用完成交互后再查询状态，不由 SDK 自动批准。
+- `client.platform.skills.getVersions/updateVersion` 复用当前安装范围和版本策略。多范围安装必须明确 tenantId；更新要求 `expectedRevision`，固定版本与自动跟随通过实际平台接口切换。
+- Agent 声明的 MCP 和应用工具提供者继续使用已有注册/移除接口；资源不可用仍作为工具能力错误交给模型，不阻止历史任务继续。
+
+## 产物来源与验证证据
+
+```ts
+const all = await session.artifacts({ type: 'document', limit: 100 });
+const thisRun = await run.artifacts();
+// 也可通过 session.artifacts({ runId }) 查询某轮实际引用的文件。
+```
+
+返回值包含现有文件的类型、MIME、大小、修改时间、工作区和本地源路径；`source` 区分执行事件引用与只有工作区文件的情况，并给出事件、轮次、工具和可用的线程标识。按轮次过滤发生在数量截断之前，其他轮次的新文件不会挤掉该轮文件。失败工具不生成来源证据，已删除或不可访问的文件不作为可用产物返回。
+
+`evidence` 复用实际执行引擎保存的验证记录，保留 `origin`、检查工具、检查时间、`coverage`、文件版本及原始 `reportedVerified`。`validity` 表示该证据对应的文件版本是否仍然有效：`current`、`stale` 或 `unversioned`。文件登记 `file_registration` 不等于验证；`tool_reported` 也只代表工具报告的检查范围，例如部分页、部分工作表或公式范围，不代表业务结果通过。文件修改后旧证据标记为 `stale`，不会因工具曾报告成功而继续标记当前文件通过。
+
+这些接口返回查询时的实际文件，不保存历史文件副本；按旧轮次查询仍须查看当前修改时间和证据状态。宿主负责文件下载授权和对象存储链接，不能把本地绝对路径直接作为浏览器下载地址。异步文档、媒体及进程使用前述操作查询接口；取消能力以实际返回的 `canCancel` 为准。
+
+## 实例活动、资源限制与排空
+
+平台模式和独立模式使用同一套并发、持久队列、提交环境快照和执行租约。独立模式的定时任务也经过相同入口。普通任务默认没有执行期限。
+
+```ts
+const activity = await client.runtime.activity();
+console.log(activity.activeRuns, activity.queuedMessages, activity.pendingInteractions);
+
+// 限额持久化在当前实例，空闲时使用 revision 更新；值为 undefined 时恢复默认值。
+const limits = await client.resources.limits.get();
+await client.resources.limits.set('runtime.maxActiveTasks', 4, limits.revision);
+
+// 预览和清理均只针对当前实例所属的 npm/技能缓存，不删除运行包或工作区文件。
+const cache = await client.resources.cache.status();
+await client.resources.cache.prune({ apply: true, revision: cache.revision });
+
+const result = await client.runtime.drain({
+  timeoutMs: 30_000,       // 停止接收后，等待当前执行自然结束
+  onTimeout: 'cancel',
+  cancelTimeoutMs: 10_000 // 明确取消后，再等待收敛；不是普通任务的执行超时
+});
+if (result.status === 'drained') await client.shutdown();
+else console.log(result.status, result.activity);
+```
+
+限额名称和默认值：
+
+| 名称 | 默认值 | 实际作用位置 |
+| --- | --- | --- |
+| `runtime.maxActiveTasks` | 2 | 共享执行协调器；范围 1–16，原生子智能体仍由任务内部管理 |
+| `runtime.maxQueuedCommands` | 100 | 实例持久消息队列；范围 1–1000 |
+| `runtime.maxQueuedPerTask` | 20 | 每个会话待发送消息，不超过实例总量 |
+| `runtime.defaultTimeout` | `'0'` | 提交执行租约；0 不限时，非零格式如 `'30m'` |
+| `storage.minFreeBytes` | 512 MiB | 创建新会话及执行准备前的磁盘预留检查 |
+| `cache.maxBytes` | 10 GiB | 执行准备检查所属 npm/技能缓存，超额不自动删除 |
+
+`runtime.activity()` 返回实际活动快照：运行与准备操作、待审批/待输入交互、排队消息、自动化、后台记忆、工作区操作，以及已就绪执行引擎中的后台/前台进程、命令、工具调用、原生子线程和专家成员轮次。子线程计数来自原生通知，沿用已有本地协作机制。各项有重叠，不能相加当作操作系统进程数。`unobservedSessions`、`observationErrors` 会明确报告缺少遥测或查询失败，不据此认定空闲。
+
+排空会停止新操作、队列自动派发、定时触发和新的后台记忆提取；已经开始的执行可以继续审批、回答、取消与查询。未派发消息保留在原队列，宿主重启后需显式发送，不自动重放。`onTimeout: 'return'` 仅返回状态，`'cancel'` 请求取消当前实例所属执行、进程和记忆整理。`timed_out` 表示仍有活动，不能当作关闭成功；`failed` 携带真实清理错误，不自动重试。取消观察的 `AbortSignal` 只结束本次等待，不撤销排空或取消任务。排空状态持续到宿主退出，同一时刻只接受一个排空等待请求。
+
+普通后台宿主的 `client.shutdown()` 要求独占客户端且实际空闲；只断开连接用 `close()`。连接已有 CLI 时，活动和限额查询反映共享宿主；为避免影响其他客户端，不允许由该 SDK 连接排空、修改宿主限额或清理共享缓存。全局修改使用 CLI 自身入口。活动遥测需要配套构建的执行运行包；旧运行包缺少这些字段时会报告未观测状态。
+
+## 受管宿主与健康诊断
+
+应用需要管理宿主进程的启动、存活和退出时，使用 `startManagedHost`。它创建附属于调用进程的独立子进程，返回就绪后才接受连接；不会接管同一上下文已有的后台宿主。普通 `createClient` 保持原来的后台连接语义。
+
+```ts
+import { startManagedHost } from '@kmlckj/aios-agent-server-sdk';
+
+const host = await startManagedHost(options, {
+  shutdown: { timeoutMs: 30_000, onTimeout: 'cancel', cancelTimeoutMs: 10_000 }
+});
+const client = await host.connect(services); // 托管账号的 credentials 回调仍在 services 中
+const health = await client.runtime.health();
+console.log(health.ready, health.host, health.versions, health.dependencies);
+
+// 应用自己的退出流程：先释放连接及其回调提供者，再排空宿主。
+await client.close();
+const result = await host.shutdown();
+if (result.status !== 'drained') console.log(result.status, result.activity);
+else console.log(await host.wait()); // 清理完成且子进程实际以 0 退出
+// wait 也可单独观察退出；排空到期但进程还在运行时，它会继续等待。
+```
+
+`host.connect()` 可以重新连接，但不会重新启动已退出的宿主。客户端全部断开后，受管宿主仍保持运行。`host.shutdown()` 是所有者的显式操作，可以关闭仍有观察客户端连接的实例；普通客户端调用 `shutdown/configure` 不能关闭或替换受管进程，返回 `HOST_MANAGED`。更新启动配置需由所有者排空并关闭，然后用新配置重新启动。
+
+受管子进程收到父进程 IPC 断连、`SIGINT` 或 `SIGTERM` 时，使用启动时明确指定的相同排空策略。SDK 不在嵌入它的应用中安装全局信号处理器；应用可在自己的退出处理器中调用 `host.shutdown()`。Windows 应用关闭使用该 API 或父进程 IPC 断连；操作系统强制终止进程不保证能执行清理。到期未完成不会伪造退出或强杀其他进程，仍可查询活动；自动关闭失败写宿主日志并设置非零退出状态，后续处置由进程所有者决定。重复并发调用 `shutdown` 共用一次请求；超时返回后可再次观察排空，不自动重放业务或清理副作用。
+
+`runtime.health(signal?)` 不调用模型，不验证平台账号是否有额度。返回当前宿主进程与 Node 版本、SDK/协议/数据版本、启动模式、配置摘要、启动时依赖检查快照、限额及实际活动。`ready` 表示仍接收新操作且控制/活动观测正常；排空后为 `false`。可选工具未安装、账号未登录或某个任务失败在各自状态中体现，不能据此把整个宿主当作崩溃。依赖快照不是持续的工具存活探测。
+
+正式启动先验证签名和所有清单文件，`verifiedPackage.manifestSha256` 对应通过校验的运行包。包版本、协议、数据格式、系统和架构必须匹配；重连还比较运行中宿主的包摘要，同名同版本但内容不同也明确拒绝。健康查询不重复扫描整个包；源码嵌入宿主和借用 CLI 的连接不会声称通过精简运行包签名校验。版本契约统一维护在 `sdk/src/runtime-compatibility.json`。
+
+## 参数与平台资源
+
+`getConfiguration()` 返回生效路径、网络、能力上限及脱敏模型设置；`configure()` 修改运行时、工具路径、网络、上限或独立模型，要求空闲且仅当前客户端连接，先校验再关闭旧服务。之后重新打开会话即可继续；只有需要恢复业务工具调用时才重新注册回调，未注册不阻断任务。
+
+`settings.get/set` 提供 Git、工作树、删除保护、安全策略和工具配置，携带 revision 防止覆盖并发修改。`memory.get/setEnabled/edit/reset` 提供本地记忆管理。
+
+`native.status('computer' | 'browser')` 查询原生能力与权限；`native.settings()` / `native.configure(settings, revision)` 读取和修改电脑操作设置；`native.registerBrowser()` / `native.unregisterBrowser()` 管理浏览器扩展的本机宿主注册。平台和独立模式均按实际选用的工具启动原生宿主。精简运行时使用调用方配置的宿主 Node，不要求随包 Node。
+
+`platform` 提供用户、企业、当前身份、模型、账户/套餐、用量、技能、插件、知识库目录/搜索/文档查询。不同平台可能未部署全部服务；例如当前企业知识库在 PROD 验收。请求失败保留实际原因，不自动换环境。
+
+## 示例
+
+`examples/platform-assistant.mjs`：平台登录、文件报告和事件。
+
+`examples/business-assistant.mjs`：专用业务助手、只读查询、审批后写入。
+
+`examples/standalone-assistant.mjs`：无平台账号、关闭内置能力、应用库存工具。
+
+运行前设置示例要求的环境变量，凭据不写入源码。示例默认在终端询问写入审批；自动验收须显式设置 `AIOS_APPROVE_WRITES=1`。测试和业务数据目录均由调用方指定。
+
+## 应用定制接口
+
+这些配置作用于 SDK 应用及其会话。桌面端和 CLI 不配置时保留现有默认行为；共享文件路径、媒体结果解析的修复同时生效。应用回调工具的标识调整只作用于 `defineAgent({ tools })`，不重命名内置工具或调用方显式配置的 MCP ID。
+
+### 稳定工具与历史会话
+
+`applicationToolProviderId({ id, version, toolProviderId? })` 生成提供者 ID，`applicationToolReference(agentDefinition, toolName)` 生成可用于成员白名单的完整工具引用。默认 ID 由智能体 ID 和版本生成，与监听端口、临时凭据分离；也可以显式设置 `toolProviderId`。`agent.tools` 返回实际工具引用列表。不要手工拼接协议前缀。
+
+旧 SDK 会话保存的随机 `app_<32 hex>` 标识按该会话所属智能体映射到重新注册的应用提供者，保留原调用名称。映射不改写历史文件，也不把其他显式 MCP 服务改成应用工具。应用没有重新注册时，工具不可用错误仍返回模型，任务可以继续，不增加恢复前置门禁。
+
+`unregisterProvider()` 移除后续轮次的注册；`releaseProvider()` 同时拒绝新 MCP 会话，已有会话与调用继续，全部关闭后释放 HTTP 服务。`waitProviderClosed()` 观察释放完成，不能当作强制中断。旧 Agent 句柄不能注销已被替换的提供者；`client.close()` 终止该客户端的所有应用回调。同一客户端的并发 `defineAgent()` 按调用顺序登记；失败仍返回该调用方，不自动重试，也不阻塞后续登记。
+
+### 上下文与生成参数
+
+智能体默认值、`session.configure()` 和 `session.send()` 均可设置 `runtimeTuning`：
+
+```ts
+await session.configure({
+  runtimeTuning: {
+    compaction: {
+      triggerRatio: 0.7,
+      triggerTokens: 180_000,
+      instructions: '保留需求、约束、已验证结论、文件路径与剩余工作。',
+      summaryTargetTokens: 4_000,
+      handoffCharacters: 20_000,
+    },
+    generation: { temperature: 0.2, topP: 0.9, maxOutputTokens: 8_000 },
+  },
+});
+const effective = await session.runtimeTuning();
+```
+
+阈值取窗口比例、显式 Token 阈值和模型输入上限的较小值，同时用于宿主判断及原生自动压缩。未配置时仍使用已有 75% 策略。`summaryTargetTokens` 是模型摘要目标，不保证硬性截断；`handoffCharacters` 是结构化任务交接快照的字符上限，不是任意历史消息保留数量。原生历史保留策略没有新增可调接口，查询明确返回 `nativeHistoryRetention: 'runtime_default'`。
+
+`session.runtimeTuning()` 区分会话配置 `configured` 与实际已应用的 `applied`，包含实际阈值、输出上限以及最后更新时间；执行前尚无 `applied`。手动压缩、计划继续和从历史提问重新执行沿用相应已提交提问的策略；排队消息保存自己的策略。`session.configure({ runtimeTuning: null })` 清除会话默认值，后续普通提问恢复默认。
+
+生成参数必须由宿主明确声明模型支持：独立模型通过模型定义的 `generationCapabilities`，平台模型通过客户端 `generationCapabilities[modelCode]` 声明 `temperature/topP/maxOutputTokens/responseFormat` 布尔值。未知或未声明参数拒绝执行，不猜测支持情况。显式设置 SDK 的 `maxOutputTokens` 时，输出数量受平台目录上限约束；未设置时不新增输出参数或改变普通桌面/CLI 任务的路由标识，自定义模型原有上限规则保持不变。能力声明只允许调整公开生成参数，不能覆盖身份、凭据或计费头。
+
+结构化结果使用 `generation.responseFormat: { name, schema, strict? }`；Responses 和 Chat 协议分别映射到对应 JSON Schema 字段。该选项只用于普通生成请求，不混入压缩端点。`applied.effectiveGeneration` 返回输出上限约束后的配置。
+
+### 文件引用、对象存储
+
+`session.files.resolve(path, 'read' | 'write', signal?)` 和业务工具 `context.files.resolve(path, access)` 使用会话的 cwd、读写授权根和状态目录隔离规则，返回 `absolutePath/toolPath/workspaceRelativePath/access/exists/bytes`。业务工具中的解析绑定实际执行会话，不能通过模型参数冒用其他会话。未授权路径报错；解析不是扩大原生沙箱权限的通道。
+
+工具返回的 `toolPath` 可以直接交给下一次工具调用。cwd 等于工作空间时维持原有相对路径；SDK 指定子目录 cwd 时返回明确的绝对路径。记录/展示使用独立的工作空间相对路径，不通过“哪个文件存在”猜测路径基准。
+
+实现 `FileStorageAdapter` 后调用：
+
+```ts
+const exported = await session.files.export('报告.pdf', storage, {
+  key: 'reports/report.pdf', expectedVersion: previousObjectVersion, signal,
+});
+await session.files.import(exported.stored, storage, {
+  path: '报告副本.pdf', expectedVersion: null, signal,
+});
+```
+
+`put` 接收不可变快照字节流、SHA-256 和长度，必须完整消费并返回实际对象键与版本；`get` 必须读取指定版本，返回流、摘要和长度，不能静默读取最新版本。对象存储的条件写由适配器落实。导入的 `expectedVersion` 是本地目标文件当前 SHA-256，`null` 表示要求目标不存在。摘要、长度、目标版本或授权检查失败均不覆盖目标。传输按块进行，每文件最大 100 MiB，每个宿主同时最多 32 个传输，传输凭据绑定客户端与会话；取消清理暂存数据，不伪造成功。历史产物索引不是历史文件快照，需要留存旧内容时由应用主动导出保存。
+
+### 外部记忆与提取策略
+
+客户端选项 `memory.extraction` 提供 `enabled/idleMs/model/instructions/timeoutMs`。默认保持当前调度；`enabled: false` 只停自动提取，不关闭已授权的记忆查询/管理。`model/instructions` 仅用于自动提取，不替换用户的正常任务模型。提取超时只约束记忆整理，不成为任务截止时间。
+
+`memory.storage: 'external'` 与第二个参数 `services.memoryStore` 配套使用。适配器实现：
+
+- `read(scope, signal)`：返回 `{ version, snapshot }` 或尚未创建的 `null`。
+- `compareAndSwap({ scope, expectedVersion, snapshot, operationId }, signal)`：原子比较版本并写入，返回新版本；冲突必须报错。
+
+SDK 首次读取会初始化外部状态。适配器是权威存储，不可用时返回真实错误，不切换本地副本。快照保留状态、记录、来源、版本及命名空间；SDK 在隔离的临时目录中执行相同记忆规则，结束即清理。当前接口读写完整快照并重建派生索引，适合有限规模的应用记忆，不是按记录增量同步协议。CAS、跨进程事务和对象版本一致性由适配器实现；网络中断后不自动重放写操作，应用可按 `operationId` 做幂等确认。
+
+### JS 工具回调
+
+```ts
+const agent = await client.defineAgent({
+  ...definition,
+  jsHooks: {
+    beforeTool: {
+      timeoutMs: 30_000,
+      execute: async (event, { signal }) => checkToolAccess(event, signal),
+    },
+    afterTool: {
+      execute: event => ({ additionalContext: `已处理工具 ${event.toolName}` }),
+    },
+  },
+});
+```
+
+两种 Hook 均可指定 `matcher`。事件包含 SDK `sessionId`、工具名、调用 ID、输入、后置结果及原始事件；引擎 thread/turn 标识保留在 `raw`，不冒充 SDK 会话 ID。返回 `{ decision: 'continue' }`、`{ decision: 'deny', reason }` 或附加 `additionalContext`。前置拒绝阻止当前工具；后置拒绝只是已执行操作的反馈，不能撤销副作用。回调异常、离线和超时以工具 Hook 失败反馈交给模型，不吞掉错误。取消信号透传应用；默认 Hook 时限 30 秒，最多 1 小时，与任务寿命无关。回调通过随包轻量进程接入执行引擎，业务函数仍在应用进程执行。
+
+### 会话授权、诊断与通信
+
+`scope` 只定义业务分组和记忆命名空间，不自动构成 ACL。需要按调用方授权时，设置 `authorization: { required: true }` 并提供 `services.authorize(request, { signal })`，精确返回 `true` 才允许。请求带方法、SDK 会话 ID、宿主保存的 scope 和运行 ID；创建/接管会话时使用拟绑定范围。已有会话的客户端伪造 scope 不生效。列表先检查列表权限再逐项过滤；历史、事件、文件、记忆和运行控制入口也检查。缺失授权回调时拒绝访问，不降为允许。关闭传输只删除暂存数据，因此授权撤销后仍允许原客户端清理自己的传输，所有权校验始终保留。
+
+这是会话授权接口，不是宿主管理权限系统。认证、全局设置和 Agent 注册仍属于宿主所有者；不同不可信租户应使用独立宿主或应用网关，不能把拥有本机宿主凭据的任意程序当作受限最终用户。默认不启用此附加 ACL。
+
+`services.diagnostics` 提供 `log/metric/startSpan`，当前覆盖 SDK RPC 调用链：方法、请求 ID、耗时、阶段与受限错误码；不导出参数、提示词、Token 或异常正文。执行内部细节继续通过 `session.events()`、运行事件和已有 trace/context 字段获取。诊断导出异常会发出明确警告，不改变业务结果。
+
+客户端 `communication` 支持 `startupTimeoutMs/rpcTimeoutMs/shutdownTimeoutMs/methodTimeoutMs`。普通 RPC 默认为 120 秒，`rpcTimeoutMs` 或具体方法值为 `0` 表示关闭观察计时；`runtime.drain` 默认不套普通 RPC 时限。超时/停止观察不取消任务，不自动重试；执行取消仍须调用运行控制接口。启动与退出等待必须为正数。
+
+`ExecutionContext.metadata` 接收命名空间下的简单键值，最多 16 个命名空间、每个 32 项、总序列化大小 8192 字符，单值字符串最多 1024 字符。它只承载业务扩展信息，不覆盖 actor/owner/project/trace 等可信字段，不供模型伪造身份。
+
+## 构建、汇总与 npm 发布
+
+以下命令在仓库 `aios-desktop` 目录执行。公共调用库和原生运行时分开构建；不需要在 Windows 上重新编译从其他平台复制过来的产物。
+
+```sh
+npm run typecheck:sdk
+npm run build:sdk
+```
+
+正式 JavaScript 构建统一执行内部标识符混淆、无用代码删除、语法与空白压缩，不输出 source map。SDK 调用库、精简宿主及 Worker 均使用这些设置，共享任务执行资源沿用已有压缩混淆构建。公开导出、业务对象字段、协议名称和 TypeScript 声明保持可用。混淆不会把接口文档或必要资源变成密文，也不替代签名与内容校验；签名和摘要在最终构建完成后生成。
+
+各构建机使用同一代码版本与 SDK 版本，先按仓库运行时构建说明准备本机 AI 运行时，再选择对应命令。Windows 验证公司代码签名，macOS 完成签名和公证，Linux 完成发布清单签名。
+
+| 构建机 | 精简运行时命令 |
+| --- | --- |
+| Windows x64 | `npm run build:sdk:runtime:win -- --output release/sdk-runtime-win32-x64` |
+| macOS Intel | `npm run build:sdk:runtime:mac:x64 -- --output release/sdk-runtime-darwin-x64` |
+| macOS Apple Silicon | `npm run build:sdk:runtime:mac:arm64 -- --output release/sdk-runtime-darwin-arm64` |
+| Linux x64 / glibc | `npm run build:sdk:runtime:linux:x64 -- --output release/sdk-runtime-linux-x64` |
+| Linux arm64 / glibc | `npm run build:sdk:runtime:linux:arm64 -- --output release/sdk-runtime-linux-arm64` |
+
+私钥统一使用 `signing-private/cli-release/aios-cli-2026-10-private.pem`，SDK 与 CLI 共用；仅用于构建签名。所有平台包包含完整签名和必要资源，不包含该私钥、Git、Python、Node、npm、Bash 发行目录。
+
+Windows 构建前配置 `AIOS_CLI_WINDOWS_CERT_SHA1`（证书存储区内公司代码签名证书的指纹）、`AIOS_CLI_WINDOWS_TIMESTAMP_URL`（当前为 `http://time.certum.pl`）和 `AIOS_CLI_SIGNTOOL`（Windows SDK 中 `signtool.exe` 的绝对路径）。macOS 使用 `AIOS_CLI_MAC_SIGN_IDENTITY` 及现有公证配置。原生代码签名凭据和运行时清单签名私钥用途不同，正式构建两项均须准备。
+
+本机构建和真实任务验收后生成交付候选、npm 子包。以下以 Windows 为例，其他平台替换目标目录：
+
+```sh
+npm run package:sdk -- --runtime release/sdk-runtime-win32-x64 --output release/sdk-candidate-win32-x64
+npm run package:sdk:npm -- --input release/sdk-candidate-win32-x64 --output release/sdk-npm
+```
+
+将各构建机 `release/sdk-npm` 中的 `.tgz` 和 `.sdk-npm.json` 复制到同一发布目录，公共 SDK `.tgz` 与 `sdk-npm.json` 只保留一份，且摘要必须相同。不要复制各机器的缓存目录。发布机逐包验证版本、目标架构、npm 配置、归档摘要、运行时签名及完整文件内容，不执行其他系统的程序。
+
+```sh
+npm run verify:sdk:npm -- --output release/sdk-npm
+npm run publish:sdk -- --output release/sdk-npm --dry-run
+npm login --registry https://registry.npmjs.org/
+npm run publish:sdk -- --output release/sdk-npm
+```
+
+默认要求五个平台全部齐备，校验失败时不开始上传。仅发布已验收的平台时必须显式传 `--targets win32-x64`（多个目标用逗号分隔）；缺少其他平台不代表它们已支持。运行时子包先发布，公共 SDK 最后发布；npm 不提供跨包原子事务，途中失败会停止并报告，已上传版本不会删除或覆盖。发布身份须有 `@kmlckj` 范围权限，按 npm 要求完成认证；可使用 `--tag next` 和 `--otp`。同名同版本不能覆盖发布，需增加版本并同步运行时依赖。
+
+发布规则参考 [npm publish](https://docs.npmjs.com/cli/v11/commands/npm-publish/) 和 [公开范围包](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)。