配置

一句话版：DSH 配置是分层叠加的：bundle 层 → profile 层 → 用户 patch 层，后者覆盖前者；运行时用户可改的东西在 settings.yaml。

这一篇讲清楚"改哪里、哪层生效、怎么排查"。

一、Profile

每个 profile(web / headless / 自建的 tui)是一个独立目录:

~/.dsh/profiles/web/
├── cordis.yml          # 入口文件(空列表,勿编辑;每次启动被重写为空基座)
├── cordis.patch.yml    # 用户挂载层:插件的 insert/覆盖都写这
├── package.json        # 依赖 + dsh.profile.bundles(bundle 层列表)
├── pnpm-lock.yaml
├── pnpm-workspace.yaml # 离树插件所需
└── node_modules/

组合顺序:

dsh.profile.bundles 列的 bundle(每个自带 patch)
cordis.patch.yml(手动挂载的插件)
--patch 命令行覆盖

root cordis.yml 只作为空基座,真实配置树 100% 由 patch 层组成(见插件解剖)。

二、patch 层写什么

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:                       # 手动挂一个 DSH 内核工具
    - id: schedule
      name: '@deepseek-ai/dsh-schedule'

- id: session-telemetry-otel      # 按 id 覆盖某插件配置
  name: '@deepseek-ai/dsh-session-telemetry-otel'
  config:
    mode: FULL                  # 枚举大写:FULL / FEEDBACK_ONLY / DISABLED

三条约束(写对很关键,详见插件解剖):

config 是整行替换,非深合并
name 不符 → 静默跳过
patch 按 entry id 定位,不要求等于注册名

三、全局设置 `~/.dsh/settings.yaml`

patch 是部署方写的静态层;用户运行时可改的东西放 settings.yaml(由 dsh-settings-file 热发布,用户可在 UI 改):

默认路由(部署默认:web / headless / API 入口共用)

agent-default-model: provider: deepseek-official model: deepseek-v4-flash

自定义 provider(llm-pi-ai 网关)

llm-pi-ai: providers: cpa: apiKeyEnv: CPA_API_KEY api: openai-completions baseURL: http://example.gw:8317/v1 models:

id: gpt-5.6-sol

权限预设

permission: defaultPreset: danger-full-access

**patch vs settings 的区别**:

| | patch 层 | settings.yaml |
|---|---|---|
| 谁写 | 部署方(cordis.patch.yml) | 用户运行时 |
| 改法 | 改文件重启动 | UI / 文件热发布 |
| 语义 | 静态配置/挂载 | 动态用户设置 |

## 四、凭据

| 文件 | 内容 | 权限 |
|---|---|---|
| `~/.dsh/.credentials.yaml` | 托管结构化凭据 | 0600(0700 目录) |
| `~/.dsh/.env` | 环境层兜底 | 权限自管 |

托管凭据进 `.credentials.yaml`(DSH 原子落盘 0600);`.env` 是普通环境层(进程环境 > 工作目录 `.env` > `~/.dsh/.env`),密钥也可放,权限自负。详见 [凭据管理](/docs/user-guide/credentials) 与 [数据与隐私](/docs/user-guide/privacy)。

## 五、LLM Provider 配置

provider 在 Models 设置页管理。两种形状:

- **`llm-deepseek`**:扁平顶层(官方 chat-completions)
- **`llm-pi-ai`**:`providers` 字典(多 OpenAI 兼容端点)

```yaml
llm-pi-ai:
  providers:
    <provider-id>:
      apiKeyEnv: <env>
      api: openai-completions
      baseURL: <端点>
      models:
        - id: <模型名>

内置 provider:deepseek-official(api.deepseek.com)、Web 搜索走独立 Anthropic 端点(web-search-deepseek)、任意 OpenAI 兼容端点(自定义网关,注意明文 HTTP 风险)。详见多模型。

六、怎么排查"改没生效"

dsh web --dump-config              # 看组合树 + 每行来源注释(哪层覆盖哪层)
dsh web --dump-default-config      # 只看 bundle 层

--dump-config 是权威诊断工具(见命令行)。

七、常见配置目标速查

想改	写哪
默认模型/路由	`settings.yaml` 的 `agent-default-model`
加一个 provider	`settings.yaml` 的 `llm-pi-ai.providers`
权限预设	`settings.yaml` 的 `permission.defaultPreset`
挂/卸插件	`cordis.patch.yml`
provider 密钥	`~/.dsh/.credentials.yaml`(托管)或环境变量

下一步

命令行：怎么用命令看/改配置
多模型：provider 配置
插件：patch 层具体

一、Profile​

二、patch 层写什么​

三、全局设置 ~/.dsh/settings.yaml​