DotCraft SDK
使用 DotCraft SDK 把应用连接到 AppServer。从高层 API 开始，用它处理 thread、run、工具、审批和用户输入。
从这里开始
- 快速开始——连接并运行第一个 turn。
- 线程与运行——管理 thread、输入、流式事件和恢复。
- 工具与审批——添加运行时工具和交互回调。
- MCP 运行时——检查已配置 server、resource、tool 和认证。
- 渠道适配器——连接外部消息平台。
在 DotCraft 对话里可以直接调用 $dotcraft-api。它会把 SDK 问题路由到最新官方文档，并根据已安装的公共类型核对代码。
选择 API 层级
| 层级 | 适用场景 |
|---|---|
| High-level | 使用 DotCraft、thread、run、回调、模型、MCP runtime 或 App Binding 的应用。从这里开始。 |
| Wire | 强类型 JSON-RPC、连接状态、超时和显式 raw 扩展调用。 |
| Contracts | 不含传输 I/O 的生成 DTO、方法映射、注册表和协议元数据。 |
渠道适配器建立在这些层级之上。渠道模块再为适配器补充发现、配置和生命周期元数据，使 Desktop 等 DotCraft 宿主可以加载它。
包
| 语言 | 包 | 可用状态 |
|---|---|---|
| TypeScript | @dotcraft/sdk | 已发布到 npm。 |
| .NET | DotCraft.Sdk | 已发布到 NuGet。 |
快速开始是安装命令的唯一来源。
常用能力
| 任务 | TypeScript | .NET |
|---|---|---|
| 连接工作区 | DotCraft.local() | ConnectLocalAsync() |
| 连接默认 Chat | DotCraft.localChat() | ConnectLocalChatAsync() |
| 连接远程服务 | DotCraft.remote() | ConnectRemoteAsync() |
| 运行 turn | run() / runStreamed() | RunAsync() / RunStreamedAsync() |
| 读取历史分页 | listTurns() / listItems() | ListTurnsAsync() / ListItemsAsync() |
| 列出模型 | models.list() | Models.GetCatalogAsync() |
| 使用 MCP runtime | mcpRuntime | McpRuntime |
| 使用 App Binding | appBindings | AppBindings |
TypeScript 还提供 Channel Adapter profile，.NET 不提供。
连接所有权
本地高层 client 先请求 Hub 确保工作区 AppServer 可用，再直接连接 AppServer。关闭 SDK 连接不会停止由 Hub 管理的 AppServer。
重连只恢复 Wire 传输和初始化，不会重放进行中的请求，也不会重建 thread subscription、活动 run 或运行时工具绑定。恢复步骤见线程与运行。
语言参考
相关文档
- AppServer 模式——SDK 所连接的 AppServer 如何启动、加固并对外暴露 WebSocket 端点。
- AppServer 协议——这些 client 实际收发的方法与通知。
- DotCraft App——App Binding，供应用向 thread 暴露自身能力。