# Go API 导航

按任务查找公开入口、消息类型和配置方法，定位完整 GoDoc 与源码。

## 调用与会话

| 入口 | 返回或用途 | 关键约束 |
| --- | --- | --- |
| `Prompt(ctx, PromptRequest)` | `ResultMessage, error` | 内部消费到首个结果 |
| `Query(ctx, QueryRequest)` | `*Stream, error` | 调用者负责关闭 |
| `NewSession(ctx, Options)` | `*Session, error` | 初始化持续连接 |
| `ResumeSession(ctx, id, Options)` | `*Session, error` | id 不能为空，数据需要可访问 |
| `ForkSession(ctx, id, messageID, Options)` | `*Session, error` | 完成消息边界，不同时指定目标 ID |
| `Session.Send / SendWithOptions` | 本轮 Stream | 输出通道由 Session 共用 |
| `Session.SendMessage` | 发送结构化消息 | 使用 protocol 内容块 |
| `Stream.Recv` | 下一条 ReceivedMessage | 不与 Result 并发读取 |
| `Stream.Result` | 首个最终结果 | 没有终态时返回错误 |
| `Session.Interrupt / Close` | 停止执行 / 关闭连接 | 用于不同生命周期阶段 |

完整签名见 [client GoDoc](https://pkg.go.dev/github.com/nexus-research-lab/nexus-agent-sdk-bridge/client)。

## 运行期控制

`Session.Control()` 集中提供 SetModel、SetPermissionMode、SetMaxThinkingTokens、ContextUsage、SupportedModels、SupportedAgents、SupportedCommands、InitializationResult 和 GetSettings 等入口。

扩展控制包括 UpdateEnvironment、TryAutoDream、StopTask、SendTaskMessage、SetNextTurnContext、RemoveMessages 和 RewindFiles。先检查对应能力和运行时支持，再处理返回错误。

RewindFiles 用于指定用户消息的文件回滚，可先 dry run；它不恢复数据库、网络服务或任意外部副作用。RemoveMessages 修改消息记录，不等于回滚文件。

## 配置入口

| 配置域 | 常用方法 | 指南 |
| --- | --- | --- |
| 运行环境 | WithRuntime、WithCLIPath、WithCWD、WithEnv | [运行时](/docs/sdk-runtimes) |
| 提示词 | WithSystemPrompt、WithAppendSystemPrompt | [配置](/docs/sdk-configuration) |
| 模型与预算 | WithModel、WithMaxTurns、WithMaxBudgetUSD | [用量](/docs/sdk-usage) |
| 工具与权限 | WithTools、WithAllowedTools、WithPermissionHandler | [权限](/docs/sdk-permissions) |
| 扩展 | WithCustomTools、WithMCPServer、AddHookMatcher | [工具](/docs/sdk-tools)、[Hooks](/docs/sdk-hooks) |
| 输出 | WithOutputFormat、WithIncludePartialMessages | [结构化输出](/docs/sdk-structured-output)、[消息流](/docs/sdk-streaming) |
| 会话 | WithSessionID、WithResume、WithPersistSession | [会话](/docs/sdk-sessions) |
| 诊断 | WithStderr、WithDiagnostics、WithInitializeTimeout | [排错](/docs/sdk-errors) |

## 消息和结果类型

接收类型使用 `protocol.ReceivedMessage`，最终结果使用 `protocol.ResultMessage`。文本块通过 AsTextBlock 获取，发送结构化内容用 NewUserBlocksMessage、NewTextContent、NewImageContent 等构造函数。

协议含有 mixed-casing 字段，不要对工具输入、Hook 数据或控制消息整体做 snake_case/camelCase 转换。优先用公开类型序列化；兼容未知字段时保留原样，并限制其传播范围。

完整类型见 [protocol GoDoc](https://pkg.go.dev/github.com/nexus-research-lab/nexus-agent-sdk-bridge/protocol)。

## 版本核对

```bash
go list -m github.com/nexus-research-lab/nexus-agent-sdk-bridge
go doc github.com/nexus-research-lab/nexus-agent-sdk-bridge/client.Session
go doc github.com/nexus-research-lab/nexus-agent-sdk-bridge/client.Options
```

文档描述当前公开接口。若 GoDoc 或编译器提示方法不存在，先核对项目实际依赖的版本与运行时版本，阅读 [bridge 变更记录](https://github.com/nexus-research-lab/nexus-agent-sdk-bridge/blob/main/CHANGELOG.md)。不要通过导入 internal 包绕过缺失的公开能力。