# 配置模型、提示词与工作目录

组织 Options，区分启动配置、持久指令、工具集合和运行期修改。

## 一份 Options 描述一次连接

Options 使用值式链式构造。调用 With 方法会返回新配置，使用时要接住返回值，或直接链式赋值。先建立可信的基础配置，再附加与本次任务有关的选项。

```go
options := client.NewOptions().WithRuntime(client.RuntimeNXS).
    WithCWD("/srv/agent-work").
    WithAppendSystemPrompt("回答引用文件位置；没有证据时说明尚未确认。")
```

`WithCWD` 决定工作目录，不是沙箱根目录。目录需要在运行时所在环境中存在，访问范围仍由操作系统与运行时策略决定。`WithAdditionalDirectories` 扩展目录访问，不应让未验证的用户输入直接决定该列表。

## 系统提示词的几种入口

| 方法 | 用途 |
| --- | --- |
| `WithSystemPrompt` | 设置自定义系统提示文本 |
| `WithSystemPromptFile` | 从指定文件提供系统提示配置 |
| `WithSystemPromptPreset` | 使用运行时支持的预设并附加内容 |
| `WithAppendSystemPrompt` | 在运行时提示基础上补充宿主要求 |
| `WithAppendSystemPromptParts` | 区分稳定追加段和动态追加段 |

自定义完整提示会改变运行时原有工作方式，接入初期优先使用追加要求。提示中写职责、材料和验收标准；访问控制应放在权限或工具代码中，不靠一句“不要访问别人的数据”。

稳定的职责不必每轮重复发送。只与下一条消息有关的宿主上下文使用[下一轮上下文](/docs/sdk-context)，避免污染持久指令。

## 模型与思考设置

`WithModel` 设置模型标识，`WithFallbackModel` 配置后备模型；是否能使用取决于运行时与账号。使用 `SupportedModels` 获取当前会话的可选项，而不是向用户展示一份固定的全量模型表。

思考配置可通过 WithThinking、WithEffort、WithMaxThinkingTokens 传入。它们不是所有模型通用的开关，预算和支持范围需要实测。运行期间修改模型可调用 SetModel，并检查返回错误。

## 设置来源与 Skill

WithSettings、WithSettingsObject 和 WithSettingSources 分别用于设置 JSON 文本或文件路径、内联对象和来源列表。不要同时维护几份相互冲突的配置来源；发布时记录你允许载入哪些层级，排错时核对实际合并结果。

Skill 有 WithSkills、WithDisabledSkills、WithAllSkills 和 WithoutSkills 等入口。Skill 的发现目录与运行时加载规则有关，列出一个名称不代表文件已经存在。需要使用的 Skill 应随运行环境准备，并用小任务确认实际生效。

改变启动期工具策略、Skill 配置或进程环境时，可能需要重启运行时。遇到 ErrRestartRequired 应重新组织连接生命周期，不要忽略错误后继续显示新配置。

## 环境与诊断

WithEnv 和 AddEnv 向运行环境提供变量。Bridge 不解释模型服务的请求格式，也不会把所有环境变量变成模型配置。只传入任务需要的值，凭据从部署环境读取，不写进 Go 源码和文档。

WithStderr 用于收集子进程诊断，WithDiagnostics 用于 bridge 传输事件，WithInitializeTimeout 设置初始化期限。它们和模型任务的执行 deadline 是不同层次。如何分辨这些超时见[错误处理](/docs/sdk-errors)。