运行时与能力协商

使用默认运行时 nxs

Bridge 默认选择 nxs，文档中的任务、工具和会话示例也使用 nxs。独立程序通过 WithCLIPath 或 NEXUS_NXS_COMMAND_PATH 提供可信可执行文件。Bridge 不会从 PATH 中自动寻找 nxs。

options := client.NewOptions().WithRuntime(client.RuntimeNXS).
    WithCLIPath("/opt/nexus/bin/nxs").WithCWD("/srv/agent-work")

可省略 WithRuntime，保留默认选择。路径只是示例，请换成部署机上的实际文件。可执行文件、工作目录、运行身份和环境变量共同决定运行环境。程序能被找到，不代表模型访问已经配置。

接入第三方异构 Agent 运行时

Claude Code 是 bridge 当前支持的一种第三方异构 Agent 运行时。它有自己的安装、认证、模型配置与执行行为，需要显式选择。下面的代码只展示这一适配入口，通用教程仍以 nxs 为默认。

options := client.NewOptions().WithRuntime(client.RuntimeClaude).
    WithCLIPath("/usr/local/bin/claude").WithCWD("/srv/agent-work")

也可通过 NEXUS_CLAUDE_COMMAND_PATH 指定 Claude Code 路径。接入第三方运行时之前，先在相同运行身份下完成它自己的安装和模型配置。

运行时接入不限定为这两个实现。后续扩展其他异构 Agent 运行时，需要相应适配与契约验证；不能仅替换可执行文件路径就视为兼容。宿主应按能力判断可用功能，避免把业务逻辑写成 nxs 与 Claude Code 的二选一。

能力检查与实际调用

公开方法存在不代表当前运行时一定支持。Session.Supports 是宿主判断能力的入口，其中一部分能力由 bridge 适配，一部分按运行时区分，另一部分来自初始化协议协商。

if !session.Supports(client.CapabilityMessageExecutionPolicy) {
    return fmt.Errorf("当前运行时不支持单条消息执行限制")
}
stream, err := session.SendWithOptions(ctx, "只根据现有上下文回答。",
    protocol.OutboundMessageOptions{ToolAccess: "none", MaxOutputTokens: 512})
if err != nil { return err }
result, err := stream.Result(ctx)
if err != nil { return err }
if result.IsError { return fmt.Errorf("受限任务失败：%s", result.Subtype) }

这里遇到不支持时停止发送，不能退回普通 Send。否则“禁止工具”会在兼容分支中失效。MaxOutputTokens 是这条消息的输出限制，不是整个会话的费用上限。

运行时差异

能力	公开能力常量	接入时的判断
下一轮内部上下文	CapabilityInternalContext	nxs 与 Claude 的注入机制不同，宿主调用统一入口
精确会话分叉	CapabilitySessionFork	保留完成消息 ID，并处理恢复文件缺失
Go 进程内 MCP	CapabilityInProcessMCP	工具代码由宿主执行
停止后台任务	CapabilityStopTask	使用运行时提供的 task ID
后台任务续聊	CapabilitySendTaskMessage	当前为 nxs 能力
环境热更新	CapabilityUpdateEnvironment	当前为 nxs 能力
AutoDream	CapabilityAutoDream	当前为 nxs 能力；宿主唤醒不等于必然执行
子任务控制	CapabilitySubagentControl	必须协商 subagent_control_v1
单条消息执行策略	CapabilityMessageExecutionPolicy	必须协商 message_execution_policy_v1
Hook 应用回执	CapabilityHookResponseAck	必须协商 hook_response_ack_v1
自动审核	CapabilityAutoReview	nxs 需要扩展协商；Claude 还需确认原生模式启用

Supports 为 true 也不保证账号、模型或策略可用，最终以控制调用和运行结果为准。能力来源见 capability.go。

控制已建立的会话

用 session.Control() 获取模型、设置和任务控制，用 session.MCP() 管理 MCP 服务。控制请求有自己的 context，应设置超时。长时控制的取消会沿同一 request ID 传给运行时，不应在超时后立即重复发送同一副作用操作。

初始化信息可通过 InitializationResult 获取；模型列表使用 SupportedModels。这些信息适合生成你自己的配置界面，但展示给用户前应筛选字段，不要暴露账号快照或完整进程环境。

自定义连接

WithDirectConnect 用于宿主管理远端运行时，WithTransport 用于宿主提供完整传输实现，二者不能同时设置。这些入口不提供应用级用户认证、负载均衡或租户隔离。只有在进程托管确实由其他服务负责时才使用它们；一般接入从本地子进程开始即可。