# 组件参考
七个组件分别发布什么工具、参数是什么、需要什么权限。
---

## 组件总览

| 配置行 `name` | 介绍 | 默认 | 发布的工具 |
| --- | --- | --- | --- |
| `dsh-ops/shell` | 优先使用 bash，无法覆盖时使用宿主 PowerShell | 开（三个平台） | `ops_bash`；宿主 `pwsh` 保持其原执行器 |
| `dsh-ops/file` | 有界 Rust 文件检索与针对模型的文本输出 | 开 | `ops_read_files`；高级工具通过发现加载 |
| `dsh-ops/ptc` | PTC 会话的类型化文件 API 与渐进式 SDK | 开 | `ops_inspect_local_file`、`ops_result`、`ops_load_sdk`；高级 API 通过 SDK 加载 |
| `dsh-ops/discovery` | 按需加载 Native 高级工具 | 开 | `ops_discover_tools` |
| `dsh-ops/panel` | 数据采集，开关默认关：新对话写入 `<cwd>/.dsh-ops/panel/<sessionId>.json` 与读取它的 `panel.html` | 行关；capture 默认 true | 无；见[配置参考](配置参考.md) |
| `dsh-ops/tui` | 当前会话的只读 OPS 侧栏 | 关 | 无；见 [侧栏说明](tui-panel.zh.md) |
| `dsh-ops/hide-official` | 逐项选择 read/glob/grep 替代流程；未选官方工具保持可见 | 关 | 无 |

原 `dsh-ops/background` 组件（FastCtx 后台任务：`ops_run`、`ops_run_background`、`ops_job_output`、`ops_job_list`、`ops_job_kill`）已移除。仍写着它的 profile 行会作为空操作加载：接受任意配置、不发布任何工具，只记录一条警告提示可删除该行。

---

## 工具总表

共享能力目录有 20 项，其中 PTC 生成 SDK 包含 18 个 API：15 个文件/文档工具，加 batch、result 和 load_sdk；bash 与 discover_tools 属于其他入口。目录成员不表示常驻或已获权限。新 PTC 允许池跟随已实现目录，已有显式池保持不变。文档工具默认按需加载。

| 工具 | 用途 | 完全权限要求 |
| --- | --- | --- |
| `ops_read_files` | 常驻读取 1-32 个文件的有界 UTF-8 范围 | 无命令权限门¹ |
| `ops_inspect_local_file` | 有界 UTF-8 文本行与 hex | 无命令权限门¹ |
| `ops_grep` | Rust 正则搜索、多文件过滤、计数/摘要 | 无命令权限门¹ |
| `ops_glob` | 多模式找路径，支持排除 | 无命令权限门¹ |
| `ops_replace` | 跨文件字面文本批量替换；精确编辑仍用宿主 edit | 无命令权限门¹ |
| `ops_write_file` / `ops_edit_file` | 文件写入与单文件原子多段编辑，保留 revision/CAS | 写入遵循当前权限¹ |
| `ops_diff` / `ops_stat` | 比较文本与查询元数据 | 无命令权限门¹ |
| `ops_copy` / `ops_move` / `ops_remove` | 固定文件操作 | 写入遵循当前权限¹ |
| `ops_read_table` / `ops_read_docx` / `ops_read_pdf` | 有界 CSV/TSV、DOCX、受限 PDF 读取；见下文 | 无命令权限门¹ |
| `ops_bash` | 优先的通用 bash 命令执行器；短命令用 `command`，长脚本用 `script_path` | 受限模式经 DSH 沙箱；Windows x64 使用匹配的私有 IPC 副本 |
| `ops_batch` | 预检并执行 copy / move / remove，带审计与恢复 | 见 PTC 说明 |
| `ops_result` | 有界结果引用：写入、分页、释放 | 见 PTC 说明 |
| `ops_load_sdk` | 为下一步模型请求加载 1-5 个 PTC API；不执行文件操作 | 仅 PTC |
| 宿主 `pwsh` | 使用宿主选择的 PowerShell 的 Windows 原生操作 | 沿用宿主策略 |

¹ **固定文件操作遵循 DSH fs-sandbox 同类的可信操作权限检查，不执行模型代码。** 所有模式在凭据围栏与当前作用域权限允许时可读取 OS 可读路径；read-only 拒绝替换（含其 dry run），workspace-write 允许工作区及本会话私有临时目录内替换，full-access 不额外限制写路径。通过宿主 subprocess 执行固定 Rust worker，保留无链接遍历、预算及 CAS；Bash/run_code 仍通过 OS 沙箱，绝不在失败后裸执行。Windows 启动前只为当前用户拥有的工作区根准备目录自身 WRITE_OWNER 并备份 DACL，不递归、不改所有者。该准备步骤以当前用户身份、在沙箱约束生效之前运行包内自带的脚本，仅在工作区内修改模式下执行，并传 `-ExecutionPolicy Bypass`（组策略仍优先）。

---

## `dsh-ops/file` —— 文件工具

仅有界多文件读取器 `ops_read_files` 常驻；含 hex 读取的 `ops_inspect_local_file` 按需发现。下述高级工具契约通过[工具发现](工具发现.md)或显式常驻选择激活；路由说明只列出当前实际发布的工具。

文件路径以 DSH 会话 cwd 为基准解析。`ops_read_files` 接受 `files` 数组，每项有独立路径、从 1 开始的行偏移和行数上限；单文件操作接受 `path`。Native 引用分页接受原始引用的 `root`。文件工具不接受 `workspace`、`cwd` 或 `file_path` 别名。文本工具优先使用 UTF-8；文档工具遵循各自有界格式/编码契约。glob 与 grep 不遍历符号链接、junction、重解析点、隐藏文件和 `.git`。

宿主提供 `fs` 服务时，`ops_inspect_local_file` 的读取与 `ops_replace` 的实际写入会像宿主 `read`/`edit` 一样登记到宿主的「先读后改」观测表（`fs/observed`）：用 OPS 读过的文件可直接用宿主 `edit`，OPS 写过之后宿主也不会把它误判为外部改动。`ops_grep`、`ops_glob` 与 `dryRun` 不登记。

### `ops_inspect_local_file`

读取有界 UTF-8 文本行，或某个路径的 hex 视图。目录会被拒绝——请改用 `ops_glob` 或 `ops_grep`。

Native 输出文件标题、带行号的可逆转义正文及 revision/续读提示；PTC 保留规范类型化记录。反斜杠、控制字符和 Unicode 行分隔符均转义，正文不能伪造额外行。worker 字节预算和长行续读仍明确保留，见[紧凑文件范围](紧凑文件范围.md)。展示字节不等于实测 token。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `path` | string | 相对 DSH 会话 cwd 解析 |
| `offset` | integer ≥ 0 | 1-based 文本行/hex 行，默认 1；兼容旧值 0，亦读取第一单元 |
| `limit` | integer 1–10000 | 最多返回行数 |
| `encoding` | `utf-8` | 编码 |
| `view` | `text` \| `hex` | 视图模式 |

### `ops_glob`

在 `path` 下查找普通文件。`pattern` 是 glob **数组**，按相对 `path` 的路径逐段匹配（ASCII 不区分大小写），例如 `["**/*.md","!vendor/**"]`：`*.md` 只匹配顶层，`**/*.md` 匹配任意深度；`!` 前缀表示排除，且至少需要一个正向条目。传单个字符串会被拒绝；没有 `include` 字段。

`outputMode: "details"` 额外返回 `bytes`（磁盘上的字节数）与 `modified`——真实的修改时间，**自 Unix 纪元起的毫秒数**，与 `ops_stat` 的 `modifiedMs` 是同一个量、同一单位；文件系统无法给出时返回 `null`。`sort: "modified"` 最新优先且稳定：时间相同的条目保持遍历得到的路径顺序；`sort: "path"` 与省略 `sort` 都保持该顺序。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `path` | string | 搜索根 |
| `pattern` | string[]（必填，≥1） | glob 模式 |
| `outputMode` | `paths` \| `details` | 输出形态 |
| `sort` | `path` \| `modified` | 排序 |
| `offset` | integer | 分页起点 |
| `limit` | integer 1–10000 | 最多返回条数 |

### `ops_grep`

用 Rust regex 在 `path` 下搜索 UTF-8 文件，输出有界，支持分页与行上下文。`pattern` 是**一个**正则字符串；用 `glob`（与 `ops_glob` 相同语法的数组）限定文件，**没有 `include` 字段**。`glob` 可以只有排除项（表示「除此之外全部」）；`path` 指向单个文件时忽略 `glob`。

只需全局文件/匹配总数用 `summary`；需要逐文件计数用 `count`；要匹配文本用 `content`（默认）。条目分页默认 100 条。每次调用扫描候选文件统计全局总数，只构造请求窗口，不再把首屏前缀当作完整结果。剩余页按 `nextOffset` 读取；`truncated`/`failed` 的扫描并非穷尽，不应盲目循环重试。非 UTF-8 与超大文件被排除，并记入 `skippedFiles`；读取失败记入 `failed`，阻止报告完成。遍历/文件大小边界仍生效；后续页会重扫，并非持久扫描游标。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `pattern` | string（必填） | Rust 正则 |
| `path` | string | 搜索根 |
| `glob` | string[] | 限定文件 |
| `outputMode` | `files_with_matches` \| `content` \| `count` \| `summary` | 输出形态 |
| `caseInsensitive` | boolean | 忽略大小写 |
| `lineNumbers` | boolean | 显示行号 |
| `beforeContext` / `afterContext` | integer ≤ 32 | 上下文行数 |
| `multiline` | boolean | 跨行匹配 |
| `offset` / `limit` | integer ≥ 0 / integer 1–10000 | 0-based offset 默认 0；limit 默认 100 |

### `ops_replace`

在 `path` 下执行确定性的 UTF-8 替换。`pattern` 是**字面文本，不是正则**；`glob` 规则同 `ops_grep`。`dryRun` 只观察；写入使用内容 revision 校验与原子替换。read-only 会话会被拒绝。

协作写入者通过目标旁持久、隐藏的更新锁边车（`.dsh-ops-update-<名字小写后的 sha256>.lock`）串行化。它在读取目标之前创建，因此被拒绝的调用也可能留下它；为什么不删除、可以何时清理见 [更新锁边车](native-ptc.md#update-lock-sidecars)。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `pattern` | string（必填） | 字面文本 |
| `replacement` | string（必填） | 替换内容 |
| `path` | string | 作用根 |
| `glob` | string[] | 限定文件 |
| `maxReplacements` | integer 1–100000 | 替换数硬上限 |
| `dryRun` | boolean | 不产生写入 |

### 文档读取器

`ops_read_table` 读取 CSV/TSV 字符串单元格（默认 UTF-8，支持明确 UTF-16LE/BE）；`ops_read_docx` 读取 DOCX 主体段落与表格坐标，不支持旧二进制 DOC。两者 offset 默认 1，limit 默认 200、上限 1000，输入最多 32 MiB。`ops_read_pdf` 仅处理 PDF 1.3–1.7 经典 xref 与标准 Type 1 字体文本，最多 16 MiB/32 页，offset 默认 1，limit 默认 10、上限 32；不支持 OCR、嵌入字体或现代对象/xref 流。

所有文档工具分别报告扫描、分页、展示与引用捕获完整性。后续错误可保留此前安全完整记录，但不提供虚假的全量总数或 revision；offset 不能绕过物理扫描缺口。全部格式边界、编码规则及恢复说明见[原生内核](原生内核.md)。

### 结果与错误

- **文件工具、`ops_batch` 与 `ops_result` 以值返回失败。** PTC Outcome 为 completed/partial 数据，或 rejected/conflict/error/unknown，并带错误码、副作用状态和重试策略。批处理 plan/run 状态保留在类型化 data 中；只包 try/catch 会漏掉失败，应先检查 status 与覆盖信息。Native 将同样事实投影为文本。
- **`ops_bash`** 返回宿主兼容的 `foreground`、`background` 或 `promoted` 值。包括参数无效和执行器不可用在内的失败均返回值，不抛异常；前台失败保留字符串 `error` 并附加 `failure`（错误码、副作用状态、重试策略）。启动后的副作用可能未知，不得自动重放；后台结果使用宿主 job 工具收集。
- 宿主工具（`read` / `write` / `edit` / `pwsh` 等）失败时抛 `ToolCallError`。

---

## `dsh-ops/ptc` —— 原生批处理与结果引用

组件默认启用，仅纯 PTC 会话发布工具；保留用户在 profile 中明确关闭的选择。

### `ops_batch`

预检并校验 copy / move / remove。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `action` | `plan` \| `run` \| `resume`（必填） | 动作 |
| `root` | string | 默认会话 cwd；显式给出时必须是绝对路径（相对 root 在 preflight 被拒，返回 `INVALID_ARGUMENT`） |
| `operations` | 数组，≤512 项 | 每项 `op`（`copy`/`move`/`remove`）+ `path` + `to` |
| `operationsRef` | string | 引用已存的操作清单 |
| `protect` | string[]，≤128 项 | 保护路径 |
| `id` | string | `resume` 时指定既有计划 |

> `action=plan` 需要 `operations`，只产生无副作用的审计计划；执行该计划要传 `action=resume` 加 `id`（**不要改成 `run`**）。`action=run` 需要 `operations` 并立即执行。操作使用相对 `/` 路径，不覆盖、不跟随链接。计划 root 与会话工作区 root 不同时，分页 `detailsRef` 要传同一个 `root`，否则返回 `NOT_FOUND`。

### `ops_result`

会话自有的有界结果引用：PTC 可写入对象行；Native 文件组件仅为 ref:// 提供分页/释放。分页支持顶层 equals/fields 与数量/字节预算。新引用默认 ttlMs=0（会话生命周期），可指定最多七天；仅旧 r- 快照为 24 小时过期。job 审计只读且仅在 PTC 可用。引用是观察结果，从不是权限来源。Native root 默认当前会话 cwd，PTC 默认工作区根目录。详见[分页与捕获完整性](结果预算.md#native-与-ptc-引用分页)。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `action` | `put` \| `page` \| `release`（必填） | 动作 |
| `items` | 对象数组，≤10000 项 | PTC put；整个请求 ≤2 MiB，快照 ≤10 MiB |
| `ttlMs` | integer 0–604800000 | PTC put；默认 0 表示会话生命周期 |
| `root` / `id` | string | 作用根与结果 id |
| `offset` | integer ≥ 0 | 分页起点 |
| `limit` | integer 1–512 | 每页条数 |
| `maxBytes` | integer 512–65536 | 每页字节预算 |
| `fields` | string[]，≤32 项 | 投影字段 |
| `equals` | object | 顶层过滤条件 |

---

## `dsh-ops/shell` —— 终端与 shell

执行顺序：**工具包 → bash → 宿主 PowerShell**。

Windows x64 上，主包以可选依赖的形式随安装带上固定版本的 bash 载荷（`@dsh-ops/bash-win32-x64@0.2.1`，PortableGit `v2.56.0.windows.2`，GNU bash 5.3.15）；也可用 `bashPath` 选择 Git Bash；载荷缺失或不完整时用 `dsh-ops bash-runtime install` 修复或安装托管副本。POSIX 主机使用系统 bash，不随包提供载荷。PowerShell 保持宿主选择。

- `ops_bash`：优先的通用命令执行器。短命令用 `command`，长脚本用 `script_path`。
  取消也会终止尚未完成的沙箱准备；迟到的准备结果不能再启动命令。取消与超时同时发生时，报告最先触发的原因。
  相对 `workdir`（包括 `.`）按调用会话的工作区解析；省略或传空白字符串时使用该工作区，绝对路径保持绝对路径语义。不存在或不是目录的目标会在执行前被拒绝，错误中包含解析后的路径。
  Windows 上的 `\child` 使用会话所在盘符；`C:child` 这类位于另一盘符的相对路径需改写为绝对路径。
- 宿主 `pwsh`：Windows 原生操作，使用宿主选择的 PowerShell。

`ops_bash` 必须提供非空 `description`，输入字段和结果类型与宿主 Bash 保持一致：`foreground`、`background` 或 `promoted`。默认超时 120 秒，上限 600 秒。宿主 jobs 服务可用时，`run_in_background: true` 立即返回 job ID；前台等待超时会把同一个运行中任务交给宿主管理。用宿主 `job_output` 收集输出、`job_kill` 停止任务。没有 jobs 服务时不声明后台参数，前台超时会停止命令。未知参数在执行前被拒绝。

Bash 参数错误以失败的 foreground 值返回，不抛出异常。兼容的字符串 `error` 保留，`failure` 补充稳定错误码、副作用状态和重试指引。参数错误无命令副作用；执行后的超时、取消和非零退出效果未知，必须先只读检查，禁止自动重放。 宿主接受任务启动回调后准入失败时，取消排队启动，不会转为前台再次执行。

`sandbox_permissions` 和 `justification` 可通过宿主审批服务申请更宽的权限。一次批准只作用于当前命令；拒绝后不执行，也不修改会话模式。审批与沙箱准备后都会重新检查会话权限。Windows 如实报告宿主的实际约束级别（包括 `partial`）；不兼容的 Bash 运行时直接拒绝执行。

`script_path`（替代 `command`）、`graceMs` 和 `includeDiagnostics` 是保留的 OPS 兼容扩展，不改变宿主命令契约或超时上限。

“默认终端改为 bash”指模型提示优先使用 `ops_bash`，**不修改系统默认终端、PATH 或宿主原有 shell 工具名称**。OPS 不覆盖宿主 PowerShell 执行器配置。运行 `dsh-ops upgrade-host-pwsh` 预览标准 PowerShell 7 的显式安装计划，添加 `--yes` 才执行。之后重启 DSH，并在宿主设置中检查自定义 `pwshPath`。已有运行命令和旧托管副本都不会被移除。

插件按实际发布情况渲染路由提示。以下为合成示例；生产上模型分别看到 file 与 shell 两段提示，各自只列出该段已发布的工具（含 `ops_discover_tools`、`ops_read_files`、文档读取器及其它文件工具）：

```
# Shell routing: bash → host PowerShell

| Task | Tool |
| --- | --- |
| Bounded UTF-8 text / hex | ops_inspect_local_file |
| Images | read_image (host) |
| Search contents | ops_grep |
| Find paths | ops_glob |
| Batch replacement; use host edit for precise edits | ops_replace |
| General commands / builds / git / pipelines / scripts — preferred command executor | ops_bash |
| Windows-native cmdlets / registry / services only | pwsh (host PowerShell) |
```

---

## `dsh-ops/hide-official` —— 逐项替换

默认禁用，配置为 `replaceTools: []`。显式选择后，模型会改用下列经评审的读取/搜索流程。它们的名称、参数和结果与宿主工具不同；不会在官方名称下翻译或转发调用。

<!-- hide-official-scope:start -->
| 官方工具 | OPS 替代工具 | 经评审用途 |
| --- | --- | --- |
| `read` | `ops_inspect_local_file` | 有界本地 UTF-8 文本读取，也支持十六进制视图 |
| `glob` | `ops_glob` | 有界普通文件路径搜索 |
| `grep` | `ops_grep` | 有界 UTF-8 内容搜索 |
<!-- hide-official-scope:end -->

- **read：** 两者均使用从 1 开始的行偏移和有界行数。OPS 另有十六进制视图，返回修订值和分页信息，并执行自己的本地文件权限及凭据保护。此选择不替换 `read_image`、附件、目录或非本地文件系统提供者。
- **glob：** 宿主接受一个模式字符串，裸文件名可匹配任意深度，并包含隐藏及忽略文件。OPS 接受相对 `path` 的 glob 数组；`*.ts` 仅匹配顶层，递归应使用 `**/*.ts`。OPS 支持排除规则和分页，但不遍历符号链接、重解析点、隐藏文件或 `.git`。搜索覆盖范围和排序并不完全相同。
- **grep：** 宿主接受单个 glob 过滤条件和 ripgrep 正则表达式。OPS 使用 Rust regex、相对 glob 数组、可选上下文和输出模式，以及有界分页结果。必须读取完成/截断字段；部分扫描不能证明全局无匹配。宿主的溢出文件和 OPS 分页属于不同流程。

OPS 调用始终保留自己的会话 cwd 路径基准、权限检查和输出契约。选择替代工具不会扩大权限。需要宿主特定覆盖范围时，应保留对应官方工具。

`write`、`edit`、`str_replace_editor` 故意不提供选择。OPS 写入和编辑要求观测到的 `expectedRevision` 并以 CAS 发布；宿主的直接写入和全量匹配编辑不具有相同契约。名称相似的注册项不能证明兼容。Shell、`run_code`、委派、任务、媒体和第三方工具也保持可见，不产生警告列表。

所选 OPS 替代工具必须已注册、可见，并且是 OPS 拥有的确切 Native 定义。同名或 schema 完全相同的外部注册不能满足就绪条件。即使 schema 字节不变，所有权变化也会重新检查；OPS PTC 适配器创建的 Native 映射保留受跟踪的所有权。仅有 PTC 数据 API 不能替换 Native 工具。任一所选替代工具不可用时，仅受影响作用域以 `READINESS_BLOCKED` 拒绝运行，并撤销该作用域自身的替代隐藏；健康作用域及继承的权限限制保持生效。移除选择、卸载或禁用组件会恢复对应官方工具。旧 `strict`/`scope`/`additionalOfficialTools` 会校验但不生效，必须显式提供 `replaceTools` 才会隐藏。

常驻的 `ops_read_files` 不是经评审的 `read` 替代项。选择 `read` 前，应配置发现组件 `alwaysLoaded: [inspect_local_file]`，或确保该单文件能力已在当前 Native 作用域激活。`glob` 和 `grep` 同样需要就绪。内部展示模式检查允许发现组件在启动时发布这些已配置工具；普通提示词组装和工具执行在就绪前仍会被拒绝。

组件同时导出 StandardSchemaV1 验证器与公开 JSON schema 描述，供宿主内置行表单使用。可选浏览器多选页面需要显式客户端承载行迁移，见[配置参考](配置参考.md)。


---

## 相关文档

- [配置参考](配置参考.md) —— 配置项与归属组件
- [使用指南](使用指南.md) —— 安装、更新、卸载、命令行接口
- [常见问题](常见问题.md) —— 报错与排查
- [原生 PTC](native-ptc.md) —— PTC 的设计与构建