SDK API 指南¶

本文档为非规范性内容。它描述实现 Computer Runtime Contract 时推荐的 SDK API 能力，不规定语言专属的 class、trait、builder、constructor 或 async runtime 形态。

1. 稳定能力族¶

鼓励 SDK 暴露以下能力族的公共入口：

能力族	稳定语义预期
create from config	从声明式 config 和 runtime options 创建一个 runtime Computer
start / stop	初始化和停止本地 runtime service activity
connect / disconnect	建立和结束 SMCP connection，且不销毁 durable config
join / leave office	当未折叠进 connect/disconnect 时，加入或离开 Office
sync config	应用新 config，使最终 public runtime behavior 与其匹配
query projection	返回 SDK-visible tools、config、resources、Desktop 和 SKILL 视图，且与协议投影一致
plugin lifecycle	install、enable、disable 和 uninstall plugin-contributed capabilities
marketplace lifecycle	add、sync/refresh、list 和 prune marketplace sources
input values	resolve、set、clear 和 inspect input values，且不向 Agent 暴露 secrets
diagnostics	返回 lifecycle state、degraded components、validation errors 和 last failures
shutdown	释放 resources，并阻止 stale callbacks/events

具体名称由各 SDK 自行决定。例如，一个 SDK 可以暴露 builder，另一个可以暴露 factory，第三个可以使用 async constructor。Conformance 以行为为准。

2. API 形态建议原则¶

鼓励 SDK：

将 config parsing 与 side effects 分离。从 config 创建 runtime 不应连接 Server 或执行 tools。
让生命周期操作显式，并在可行时保持幂等。
返回公开 lifecycle state 和 diagnostics，而不是要求调用方检查 logs 或 private fields。
区分 disconnect、stop 和 shutdown。
提供单一 sync_config 语义操作，即使实现内部会重建 runtime。
提供与 Runtime Contract §6 对齐的 typed 或 structured error categories。
保持 management diagnostics 与 Agent-facing protocol payloads 隔离。
允许调用方注入业务 auth fields，但不要把 secrets 放入 a2c_version、role、update notifications 或 Agent-visible config。

3. Config 与默认值¶

SDK 可以使用语言原生类型，但应支持用于 conformance 的共享 JSON fixtures。

推荐默认行为：

区域	指南
namespace	默认使用 `/smcp`
protocol version	在 URL query 中使用 SDK 声明的 A2C-SMCP protocol version
auth role	`role` 经 `server:join_office`（`EnterOfficeReq.role`）声明；connection `auth` 仅承载业务鉴权（如 token），不含 `role`
auto connect	文档化 start 是否自动 connect；对嵌入方优先推荐显式 connect
auto reconnect	如果支持，应使行为可配置且可观察
disabled servers	保留 config，但从 Agent-facing projection 中排除能力
forbidden tools	从 tools 中排除，并拒绝成功执行
marketplace reconcile	优先采用 additive-only startup reconcile 和 explicit prune/gc
plugin MCP 依赖	按 `bundle_id` 依赖预检（读运行期权威配置集）：已存在 = 依赖已满足 → 提示 + 正常安装，不拒绝；同文件多 key 归一同 `bundle_id` 才 fail-fast
secret values	仅本地解析，绝不放入 Agent-facing projection

4. Lifecycle API 指南¶

4.1 Create¶

SDK 可以提供任意等价入口：

runtime = create_computer(config, runtime_options)

该操作应校验 shape 并解析默认值，但避免 network 和 MCP process side effects。

4.2 Start¶

start 应初始化本地 resources、registries、blob resolvers、watchers 和 MCP manager intent。如果 start 会立即启动 MCP Servers，SDK 应文档化该 policy，并以 public diagnostics 暴露 startup failures。

4.3 Connect¶

connect 应接收 Server URL 和可选 connection options。SDK 应让最终 handshake 足够可检查，以便测试验证：

a2c_version 位于 URL query 中。
连接 auth 不含 role（角色经 server:join_office 声明）。
caller-supplied auth payload 已包含，且不会泄露 MCP credentials。
配置后会发送 server:join_office，其中 role = "computer"。

4.4 Sync Config¶

SDK 应暴露一个应用新 desired config 的操作。它可以实现为：

incremental update；
diff-and-apply；
在稳定 identity 背后 full rebuild；
保持 projection 的 stop/start。

SDK 应文档化 sync 期间 in-flight tool calls 是继续、被取消，还是允许完成。无论实现方式如何，最终 projection 必须匹配新 config。

4.5 Shutdown¶

SDK 应提供一个终止性的 cleanup 操作。完成后：

不应再发送 update notification；
watcher 不应调用 stale callbacks；
旧 Socket.IO client 不应 ack 新请求；
owned MCP server resources 应按文档化 policy 被停止或 detach。

5. Plugin 与 Marketplace API 指南¶

鼓励 SDK 把 plugin 和 marketplace 操作暴露为 management APIs，而不是 Agent-facing protocol events。

5.1 MCP Server 寻址：库层收 bundle_id，name 解析只在人机面¶

库层公开 API（remove / unmount / start / stop 等治理与生命周期操作）一律收 bundle_id，无 name 启发式、无回退猜测——「入参即身份」。理由：治理路径（uninstall / disable / rollback / 账本）全程持 bundle_id；name→id 启发式放库层会让每个外部集成方各继承一次不可靠推断（name 空间与 id 空间在缺省派生下大面积重叠，重叠处「先按 name 再回退按 id」不可靠）。

name→id 解析（resolve_target 语义）只存在于人机面（CLI / REPL 等），该用户可见行为双端 MUST 逐字一致：

token 按 display name 在活跃配置集 ∪ 声明面反查（术语定义见下方），唯一命中 → 解析为其 bundle_id，执行；
多命中，且 token 精确等于其中某候选的 bundle_id → 按该 bundle_id 执行（用户已显式表达身份意图，不应报「请用 bundle_id 重试」）；
多命中，且 token 不等于任何候选的 bundle_id → 报错并列出各候选的 bundle_id + display name + 归属（用户/哪个 plugin），要求用户改用 bundle_id 重试——只列 bundle_id 用户分不清哪个是自己的；
0 命中且 token 是合法 bundle_id 且存在于查找空间（活跃配置集 ∪ 声明面）→ 按 bundle_id 执行；仍无 → 报错「未找到」；
MUST NOT 以字典序最小等任意规则「确定性地选一个」——那是把不确定的错变成确定的错。精确 bundle_id 匹配（步骤 2）是执行用户已显式表达的身份意图，不属于「任意规则」范畴；
未命中/多命中 MUST 报错，MUST NOT 静默成功（假成功回执：打印「已停止」而 server 仍在跑，用户无从察觉）。

$ server rm filesystem
⚠️ 有 2 个 server 叫 filesystem:
   filesystem      (user)
   bundle_a3f9c2e1 (plugin:fs-tools)
请用 bundle_id 重试

术语定义：

活跃配置集（active config set）：Computer 运行期当前持有且可操作进程的 MCP Server 配置集合。它只包含已挂载（mounted）的 server，不含仅落盘声明但尚未通过审批门或尚未 reconcile 的条目。
声明面（declaration surface）：通过 resolve_mcp_declarations / declared_mcp_servers 读出的、所有已落盘的 MCP Server 声明，无论其当前是否已挂载。声明面的 origin 含 user / project / local / embed / flag / policy（plugin 拥有的 bundled server 不走声明面，其归属另有 ledger 途径）。
查找空间（search space）：§5.1 步骤 1 的查找空间为活跃配置集 ∪ 声明面，以 bundle_id 去重。取并集而非单取活跃配置集，是为了让 remove 等具有双空间语义（声明优先、无声明则看运行期投影）的操作可达声明面目标；仅取活跃配置集会丢失仅落盘声明但尚未挂载的条目，导致部分 target 从 CLI 无路可达。

生命周期动词对"已声明未挂载"的规范行为：

查找空间 ∪ 声明面后，start / stop 可能解析到「仅声明而尚未挂载」的目标。start / stop 操作的是运行期进程，非声明生命周期——对该态：

stop <已声明未挂载>：MUST 诚实陈述 "Server X not mounted; nothing to stop"，MUST NOT 打印「停止完成」（假成功回执——打印「已停止」而 server 仍在跑，用户无从察觉）。
start <已声明未挂载>：MUST 诚实陈述 "Server X declared but not mounted; it may be pending the approval gate"，MUST NOT 透传库层内部错误（如 Unknown server bundle_id: ...——内部概念泄露给用户）。

SDK 应在人机面解析完成后、调用库层 API 前增加挂载态检查（如 python _resolve_lifecycle_target、rust stop_receipt 模式），而非依赖库层 API 的失败回执来间接表现。本规范行为与 §5.1 步骤 6（MUST NOT 静默成功）形成互补：步骤 6 覆盖「拼错的名字」，本段覆盖「名字拼对、但目标尚未挂载」。

鼓励 SDK：

将 input definitions 与 resolved values 分离。
支持 plugin-scoped input disambiguation，避免相同 bare id 冲突。
避免记录 resolved secret values。
为缺失 input values 暴露 public diagnostics，但不包含实际 secrets。
将 .skillenv 和本地 secret files 视为 local-only；绝不把其内容放入 client:get_skill、client:get_blob、client:get_config 或 tool metadata。

7. 测试指南¶

SDK 应同时维护 protocol conformance tests 和 runtime contract tests：

测试类别	验证内容
wire conformance	`client:*` response shape、flat `ErrorPayload`、update notifications、room behavior
runtime conformance	lifecycle state transitions、`sync_config`、plugin/marketplace semantics、shutdown cleanup
projection conformance	management operations 后最终 `get_config`/`get_tools`/`get_skills`/`get_desktop` 视图
security conformance	无 secret/path leakage、sandbox boundaries、blob handle opacity
cross-SDK fixture conformance	Python/Rust/TypeScript 将同一 JSON fixture 解析为等价 runtime intent

共享 checklist 见 Conformance Tests。

8. 迁移指南¶

鼓励将本 runtime contract 加入既有 API 的 SDK：

保持既有 constructors/builders 作为 compatibility wrappers 继续工作。
在改变 CLI UX 前，先加入共享 fixture parsing。
引入 lifecycle state diagnostics，同时不改变 Agent-facing wire behavior。
在重构 internals 前，为当前行为补充 conformance tests。
保持 marketplace/plugin management APIs 明确为 trusted-local。

9. 非目标¶

本指南不标准化：

必需的 Computer class 名；
精确的 builder/factory signatures；
本地 home layout；
settings file names；
watcher implementation；
process supervision model；
retry scheduler；
CLI commands；
UI flows；
运行期命令式 MCP Server CRUD（对非-bundled server 的 add/update/remove）是落盘为 durable 声明意图（重启存活）还是仅内存生效（持久化留给 host 编辑声明文件）——属管理面（CLI/桌面客户端）与内核间的本地约定（详见 runtime-contract §2.3）。

操作	指南
install	物化 plugin、写 `installedPlugins` 意图、校验 manifest、MCP 依赖预检（bundle_id 比对运行期权威集，依赖已满足 → 提示不拒绝）；MUST NOT 激活（SKILL/MCP/input contributions 待 enable 才注册）
enable	标记 plugin enabled（写 `enabledPlugins=true`）并 reconcile contributions（skills 与 bundled server 原子一并；同 `bundle_id` 多来源按 runtime-contract §2.5 优先序合并）
disable	标记 plugin disabled，并使 contributions 不可见/不可调用；其声明依赖的 server 按 runtime-contract §4.9.1 回收判据处理
uninstall	移除 plugin records 并按 §4.9.1 回收判据 teardown（无人再依赖 ∧ 非用户声明才回收；停摘名单在账本移除前取得且仅依赖账本字段）
info/list	仅向 trusted caller 返回 management diagnostics 和 provenance

操作	指南
add	在 trust/policy approval 后添加 source declaration
sync/refresh	fetch/update declared sources，并注册 enabled plugin SKILLs
list	向 trusted caller 返回 source status 和 diagnostics
prune	在调用方确认后显式移除 orphan materialization