# 配置参考

按组件说明每个配置键，以及**哪个键属于哪个组件行**。

## 内置行配置

活动行通过宿主 Settings/ConfigEditor 提供严格校验的设置。接受的更改通过 profile 写入器持久化并重载所属行；版本过期或无效更改不会修改已保存的值。关闭的行须先用宿主行开关重新启用，等待中的服务须先就绪，之后才能编辑。

默认 bundle 保留 `dsh-ops/file` 及稳定 ID `dsh-ops-file`，已有带名称覆盖继续匹配。固定宿主下，此默认配置不会启用自定义浏览器页面。

## 可选浏览器设置页面

配置裸包名客户端承载行后，宿主插件管理器为替换、发现和 shell 行提供设置页面。默认七行 bundle 保留旧文件模块名，不启用这些页面。更改在**保存更改**成功前仅为草稿。
版本冲突或宿主拒绝保存时保留草稿，供检查；**恢复已保存值**会读取最新保存值。
接受的更改通过宿主配置写入器持久化，并重新加载对应行。

- **替换：**分别选择 `read`、`glob` 和 `grep`，所选工具使用 OPS 契约。
  请在发现设置中始终加载所选对应能力（`read` 对应 `inspect_local_file`，其余为 `glob` 或 `grep`），或在选择替换前激活它们。`read_files` 不满足单文件 `read` 替换契约。
- **发现：**选择允许池、始终加载子集以及 1 到 5 的结果数量上限。
  移除允许能力时，会在同一次保存中将其从始终加载子集移除。
- **Shell：**启用 Bash、填写绝对执行器路径覆盖，或选择检测到的受管理 Bash/Git Bash。
  选择运行时仅填写草稿路径，需要显式保存。清空覆盖值可继承配置默认值。
  安装运行时不会自动更改这一选择。

Bash 安装/删除与 PowerShell 升级按钮首先显示计划，随后需要显式执行已检查的计划。
启动后取消可能已发生更改，此时会报告影响未知。受管理 Bash 删除仅处理具有所有权凭据的安装，
操作前请先停止 Bash 作业。PowerShell 操作通过 WinGet 处理标准宿主 PowerShell 7 安装，
保留 Windows PowerShell 5.1，完成后需要重启 DSH；宿主自定义 `pwshPath` 需单独检查。
打开页面不会运行安装程序。

客户端承载行使用稳定 ID `dsh-ops-file` 和裸包名 `dsh-ops` 承载这些浏览器页面，服务端仍为文件组件；
`dsh-ops/file` 导出保持兼容。关闭此承载行会卸载全部自定义设置页面，请使用宿主的
**内置行开关**重新启用。没有自动表单回退。目标行被关闭时，也必须先重新启用才能编辑设置。
发现组件行与可选客户端承载行都启用后，才可使用其自定义设置页面。

### 启用可选浏览器承载行

这是主动选择的离线 profile 迁移，不是升级前提。停止 DSH 后，使用绝对路径预览已安装 profile：

```console
dsh-ops settings-profile --profile-dir <profile目录> --host-anchor <DSH安装目录的package.json> --dsh-home <DSH主目录>
```

`--host-anchor` 指定提供公开 profile API 的宿主安装。检查预览后，添加 `--offline --yes`
再次执行。命令以 `dsh-ops/lib/profiles/client` **替代** `dsh-ops` bundle，
仅移除该 profile 补丁中经过验证的旧文件行名称匹配条件，保留全部七个 ID、开关和有效配置。
遇到缺失 bundle、重复 OPS 行、外部带名称文件行覆盖、不兼容的更高优先级补丁或过期预览时拒绝写入。
预览包括 home 补丁，不包括启动命令行覆盖；不会更改其他 profile。不要同时启用两种 bundle。

原文件备份到输出显示的 `.dsh-ops-settings-backup-*` 目录；每次写入使用宿主原子写入器和
profile 锁。如果两次写入之间进程退出，第一步结果仍兼容旧 bundle；报告写入失败时，
会在没有并发修改的情况下恢复原文件。如需手动恢复，停止 DSH 后按 `recovery.json` 指示先恢复
`package.json`，再恢复 `cordis.patch.yml`。重启验证成功前请保留备份。
两种 bundle 均由已安装的 `dsh-ops` 包提供，嵌套层不是需要另行安装的软件包。
原来关闭的文件行保持关闭，需先用内置行开关启用才能显示自定义页面。
不运行该命令也可以继续使用默认旧名称 bundle。

---

## 配置的位置

在 DSH 的配置编辑器中找到对应的 `dsh-ops/shell`、`dsh-ops/file`、`dsh-ops/ptc` 或 `dsh-ops/panel` 行，调整 `config` 后保存；未知配置键会点名报错。
Bundle 声明七个独立启停组件，首次安装默认值如下。已有 profile 的显式开关和原始配置覆盖 bundle 默认值；添加 discovery 不重写这些数据。未保存显式开关的行继承新版默认值。
| 配置行 `name` | 组件 | 默认 |
| --- | --- | --- |
| `dsh-ops/shell` | 终端与 shell | 开（三个平台） |
| `dsh-ops/file` (`dsh-ops-file`) | Rust 文件工具 | 开 |
| `dsh-ops/ptc` | 原生 PTC 批处理 | 开 |
| `dsh-ops/discovery` | Native 高级工具发现 | 开 |
| `dsh-ops/panel` | 采集后续事件 | 行关；启用即开始采集 |
| `dsh-ops/tui` | 只读侧栏，独立配置 | 关 |
| `dsh-ops/hide-official` | 逐项替换官方工具，独立配置 | 关 |

早期版本留下的 `dsh-ops/background` 行会作为空操作桩加载（FastCtx 后台组件已移除）；它忽略自身配置，可直接删除。

---

## 🔴 键与组件的归属关系

`dsh-ops/tui` 只接受 `maxSessions`、`maxActive`、`recentLimit`，见 [侧栏上限](tui-panel.zh.md#上限)。下表列出字段实际作用的组件。file/root 与 shell 保留共享旧校验器，某些兼容字段可被接受但不影响该行；PTC、discovery、panel、TUI 和替换各有严格字段集，不可复制通用 file/shell 配置进去。Loader 行开关是 config 外的 disabled。

| 配置键 | 类型 | 默认 | 归属组件 |
| --- | --- | --- | --- |
| `configUpdateVersion` | 非负整数 | `0` | file / shell（迁移标记） |
| `binaryPath` | 绝对路径 | — | file / ptc / discovery |
| `bashPath` | 字符串路径 | — | shell |
| `publishBashTool` | 布尔 | `true` | shell |
| `promptPolicy` | 布尔 | `true` | file / shell |
| `extraGuidance` | 字符串 | 空 | file / shell |
| `required` | 布尔 | `false` | file / ptc / discovery |
| `shellPolicy` | `advise` \| `deny-host-shell` | `advise` | shell |
| `deniedHostTools` | 字符串数组 | `[pwsh, bash, pwsh_persistent]` | shell |
| `allowSystemShellFallback` | 布尔 | `false` | shell |
| `denyCredentialReads` | 布尔 | `true` | file / discovery |
| `capture` | 布尔 | `true` | panel（行默认关） |
| `textLimit` | 整数 | `2000` | panel |
| `maxSessionBytes` | 整数 | `8388608` | panel |

PTC 只接受 binaryPath、required、allowedTools、alwaysLoaded，凭据围栏保持开启；其始终加载列表独立于动态允许池。Discovery 另有 enabled、maxResults、denyCredentialReads，且 alwaysLoaded 必须是 allowedTools 子集。默认值和确切名称见[PTC 设置](PTC按需加载.md)与[发现设置](工具发现.md)。替换拥有 replaceTools 及不生效的旧兼容键；panel/TUI 仅接受其采集/展示字段。

### 凭据围栏（`denyCredentialReads`）

凭据预检拒绝仍返回 `rejected`、`CREDENTIAL_DENIED`、无副作用及禁止重试的指引。Native 文本和 PTC 返回值不披露被拒路径、解析后的父目录或匹配规则。

键名是历史遗留；围栏本身拦的是**路径**，不是某一个方向。凭据位置在**读**（`inspect_local_file`，且 `grep`/`glob` 从不报告或列出它）、**写及删除**（`write`、`edit`、`replace`、`remove`）以及作为 `copy`/`move` 的**目标**时都会被拒绝，覆盖单个路径、batch 的操作根以及递归的每个子项，`danger-full-access` 下也一样。被拒的操作返回 `CREDENTIAL_DENIED`、`phase: preflight`、`effectState: none`，并且发生在 native worker 被拉起之前。`denyCredentialReads: false` 只对该行关闭围栏，`DSH_OPS_DENY_READ` 只能扩大清单。**新建** `.env` 或 `~/.ssh/config` 也无法通过这些工具完成，详见[常见问题](常见问题.md)。

**已弃用的键。** `serverName`、`enableShellTools`、`toolCallTimeoutMs` 只被已移除的 FastCtx 后台组件读取。它们仍被接受（并仍做类型校验），以便既有配置行照常加载——早期 bundle 会把 `enableShellTools: false` 和 `toolCallTimeoutMs: 300000` 写进每个 file 行——但已不起作用，配置更新 2 会在下次启动时把它们从已保存的行中删除。

---

## 示例

`dsh-ops/shell` 行：

```yaml
config:
  promptPolicy: true
  publishBashTool: true
  shellPolicy: advise
  allowSystemShellFallback: false
  # bashPath: 'C:\tools\bash.exe'   # Windows 受限执行须匹配 MSYS/IPC，见下文
```

`dsh-ops/file` 行：

```yaml
config:
  promptPolicy: true
  required: false
  # binaryPath: 'C:\tools\dsh-ops-worker.exe'
  # Managed update metadata; do not remove after the first startup self-check
  # configUpdateVersion: 2
```

`dsh-ops/panel` 行**默认关闭**。启用新行即开始采集；旧配置显式 `capture: false` 保持关闭，需操作者自行更改：

```yaml
config:
  capture: true         # 行开关控制采集；旧配置 false 继续不采集
  textLimit: 2000       # 每个文本字段保留的字符数,被截断时会标记
  maxSessionBytes: 8388608
```

---

## 逐个说明

- `publishBashTool`：是否发布 `ops_bash`；读取最新会话权限，受限模式需宿主 sandbox，完全权限使用宿主 subprocess。
- `promptPolicy`：是否注入该组件的运行时说明；可用 `extraGuidance` 追加指导。
- `required`：原生 worker 不可用时是否拒绝激活。
- 宿主 PowerShell 不参与 OPS 运行时选择：不再捆绑执行器或覆盖 `pwshPath`。`upgrade-host-pwsh` 预览标准 Windows 安装，`--yes` 才执行。之后重启 DSH，并检查自定义宿主 `pwshPath`。
- `shellPolicy`：默认 `advise`；`deny-host-shell` 拒绝 `deniedHostTools` 列表中的宿主 shell（默认 `[pwsh, bash, pwsh_persistent]`）。这也会禁用第三层 pwsh，谨慎开启。
- `allowSystemShellFallback`：默认 `false`，随包/已 provision 的 bash 缺失时不探测系统 PATH 或常见安装目录（**POSIX 主机上该键不起作用**：shell 组件本来就解析宿主 bash，这里没有 pin 过的载荷可"回退"）。只有显式设 `true` 才使用未固定摘要的系统 bash，请自行信任与维护该执行器。显式 `bashPath` 是另一种操作者选择，并非自动回退。首次升级启动的迁移见 [使用指南](使用指南.md) 的「更新配置修改区」。
- `shellPolicy` 与此开关独立：`deny-host-shell` 遮蔽/拒绝宿主工具；禁止系统回退只约束插件自己的 bash 解析，不关闭宿主 `pwsh`，也不提供文件系统沙箱。
- `binaryPath`（原生 worker 可执行文件）/ `bashPath`：可选显式绝对路径；不可用时报错，不悄悄换执行器。Windows 上固定版本的 bash 载荷是主包的 npm 可选依赖，随安装到位，通常无需配置；缺失或不完整时用 `dsh-ops bash-runtime install` 修复，或用 `dsh-ops bash-runtime git` / `managed` 打印 Bash 选择。
- **POSIX 主机上 `ops_bash` 本就用宿主发行版的 bash**：解析顺序为 `bashPath` → `PATH` → `/bin/bash`、`/usr/bin/bash`、`/usr/local/bin/bash`，随包不提供第二份 shell，因此没有需要"回退"的载荷，`allowSystemShellFallback` 也不影响它。受限模式（`workspace-write` / `read-only`）下 `bashPath` 同样生效，约束由宿主沙箱（bwrap / Landlock）落实；沙箱不可用或无法约束时**拒绝执行**，不会退化为无约束运行。
- `bashPath` **（Windows）在受限模式下必须匹配固定 MSYS。** 只读与工作区内修改模式下，`ops_bash` 只运行已校验 IPC 兼容代理的固定摘要 MSYS（`dsh-ops bash-runtime install` 或兼容的已有副本）；其它任何 `msys-2.0.dll`（包括你自己的 Git for Windows）都会按设计返回 `EXECUTOR_UNAVAILABLE`，且绝不裸执行。不要把 `bashPath` 指向自带 Git Bash 来规避受限模式问题。可用 `dsh-ops ladder --config <文件>` 检查所选 bash，报告中的 `restricted: yes/no` 即受限模式能否运行。见 [常见问题](常见问题.md#受限模式下-ops_bash-无法运行自定义-bashpath-或-git-for-windows)。
- `deniedHostTools`：`deny-host-shell` 策略下拒绝的宿主工具名列表。
- `configUpdateVersion`：配置迁移的完成标记（当前为 `2`：更新 1 撤销旧的隐式系统 bash 选择，更新 2 删除已弃用的 FastCtx 键）。不要删除迁移标记，否则会重新自检。
关闭组件行或保存 `capture: false` 会立即停止事件采集、取消尚未开始的文件操作，并在宿主完成变更前等待已开始的 I/O。停用不会触发最终归并；已有 NDJSON 可恢复，中断归并留下的临时文件可能保留。重新开启只采集后续事件，不补录关闭期间的事件。

- panel 行默认关闭，不注册监听、不写文件。启用后 `capture` 默认为 `true`；旧配置显式 `false` 仍不采集，不会被静默更改。宿主无法原子地清除旧字段并同时停用行，因此保留兼容设置，供操作者显式编辑。采集到的事件写入会话工作目录：
  - `<cwd>/.dsh-ops/panel/<sessionId>.json` —— 唯一数据源：对话文本、tool_call/tool_result/里程碑轨迹、usage 分桶，以及截断与上限记录；
  - `<cwd>/.dsh-ops/panel/panel.html` —— 静态查看器，在浏览器里读取该 JSON，**不内联任何数据**（把 JSON 拖到页面上，或运行 `dsh-ops panel [目录]` 在回环地址上服务该目录；普通静态服务也可用 `?data=<sessionId>.json`）。

  会话进行中先追加 NDJSON（`<sessionId>.ndjson`，崩溃安全），在每个 turn 结束与会话封存时归并为 JSON；封存后删除追加日志。采集行本身不开端口、不注册界面、不写 `~/.dsh`；只有显式的 `dsh-ops panel` 运维命令会启动仅绑定回环地址的服务，只读指定目录且不写文件。不新增构建步骤——`panel.html` 随包发布。工作目录位于 DSH home 之内、或会话 id 不能作为文件名的会话会被拒绝并各记一行日志。采集写在对话自己的工作目录里，提交前请把 `.dsh-ops/` 加入该项目的 `.gitignore`：报告可能包含提示词、对话文本和工具输出。
- `textLimit`：每条消息文本、工具参数与 reasoning 字段保留的字符数；截断会在该行置 `truncated`/`droppedChars`，而不是无声变短。范围 `64`–`100000`。
- `maxSessionBytes`：单会话追加日志的预算，也是归并后 JSON 被裁剪到的上限。超出预算的记录被丢弃并计入 `limits.droppedEvents`；JSON 超限时从最旧的对话/轨迹行开始裁剪并计入 `limits.trimmedRows`，usage 总量始终保持完整。范围 `65536`–`268435456`。

---

## 逐项替换官方工具（`dsh-ops/hide-official`）

该行**默认禁用**，`replaceTools` 默认是 `[]`。直接启用未配置的行不会隐藏任何工具。可从经评审的官方名称 `read`、`glob`、`grep` 中逐项选择；未选工具保持可见且不产生警告。所选项会改用不同的操作流程，请先阅读[映射与覆盖范围差异](组件参考.md)。

| 键 | 类型 | 默认 | 含义 |
| --- | --- | --- | --- |
| `replaceTools` | 字符串数组 | `[]` | 要替换的官方工具；只接受 `read`、`glob`、`grep`，重复名称去重。未知键和不支持的名称会在错误中点名。 |

例如，只替换官方 read、grep，保留官方 glob：

```yaml
- name: dsh-ops/hide-official
  config:
    replaceTools: [read, grep]
```

设为 `replaceTools: []` 或禁用该行即可恢复全部官方工具。每个作用域中，所选 OPS 替代工具必须是已注册且可见的确切 OPS Native 定义；同名外部工具或仅有 PTC 数据 API 均不符合条件。若其中任一工具缺失，该作用域会撤销隐藏，并以 `READINESS_BLOCKED` 拒绝提示词组装和执行；健康作用域仍可使用。恢复替代工具、移除相应选择或禁用该行即可解除。无需注册其它无关的 OPS 工具。

Native 默认只保留精简核心工具。选择上例前，应先为发现组件配置 `alwaysLoaded: [inspect_local_file, grep]`，或先激活这些 Native 能力。`read` 仍映射到 `inspect_local_file`，常驻 `read_files` 不能满足此选择。撤销或覆盖受拥有的替代定义会立即重新检查就绪状态，即使 schema 字节完全相同。

**从 0.3 迁移：** 仅为兼容旧配置，接受并按旧类型和取值校验 `strict`、`scope`、`additionalOfficialTools`；它们均不授予隐藏权限，包括 `scope: extended` 和别名列表。只有旧键的既有行会变为无操作。即使保留旧键，`replaceTools` 也是唯一选择来源。本组件不改写已保存的 profile。

Cordis 通过 `StandardSchemaV1` 校验配置；独立的公共设置描述在内置 Settings/ConfigEditor 中提供可编辑数组。成功保存后持久化并重载对应行。自定义浏览器多选界面仍需单独实现。


---

## 提示词注册

提示以作用域运行时段落注册，不写入 AGENTS.md。关闭 shell 撤回其路由；关闭 file 撤回 Native 文件指引。新 Native 文件面仅常驻 ops_read_files，发现组件发布 ops_discover_tools，三个平台的 shell 行另有 ops_bash（Windows 为固定载荷，POSIX 为发行版 bash）。高级工具通过发现或显式始终加载启用。PTC 拥有独立类型化 SDK，并保持当前权限检查。已批准的 BM-03 预算对文件/发现 schema 执行 ≤400 token 上限。Bash 启动常驻不变，其 schema 与完整启动总数另列；缺少 Bash 不能满足 Windows 就绪检查。

---

## 相关文档

- [使用指南](使用指南.md) —— 安装、更新、卸载、命令行接口
- [组件参考](组件参考.md) —— 组件与工具列表
- [常见问题](常见问题.md) —— 报错与排查

## 宿主设置表单

已启用的 shell、discovery 和官方工具替换行向宿主设置服务提供经过校验的字段。
保存使用表单读取时的配置版本；版本过期或选项无效时，在写入前拒绝更改。
宿主持久化成功后重新加载对应行，使运行中的设置与已保存选择一致，同时保留其他行字段。
禁用的行没有可编辑表单；请先使用宿主内置的行开关重新启用。

运行时操作使用宿主已认证的网关及受管理的子进程服务。安装、删除和升级必须先预览，
再执行仍然有效的预览；过期、内容变化或已使用的计划会被拒绝。同一时间只执行一个操作。
卸载对应 shell 组件会取消尚未完成的操作并等待结束；启动后取消可能已造成更改，副作用标为未知。
Bash 安装拒绝包含无归属版本目录的存储。PowerShell 操作更新标准 WinGet 安装，随后需要重启
DSH；宿主显式设置的 `pwshPath` 仍然优先。安装器输出留在宿主日志中；如果 WinGet 需要交互输入，
请在终端运行预览中显示的命令。