dsh-coding-tools

August 24, 2026 · View on GitHub

English | 简体中文

一个 DeepSeek Harness 主机插件，提供一个范围严格限定的设置卡片，在不修改 DSH 的前提下添加紧凑、受限的编码工具：

  • code_read — 带有精确字节版本令牌的 UTF-8 代码窗口
  • edit_ranges — 基于已观察范围的原子编辑，支持操作员配置审批
  • ast_grep — 对单个由提供程序读取的文件快照运行固定版本的 ast-grep CLI，支持分页和只读进程约束
  • lsp — 使用有界 JSON-RPC 的持久化只读语言服务器查询
  • 当匹配的 LSP 服务器已处于活动状态时，在插件自身的编辑后提供新鲜的诊断摘要

在安全的初始版本中，ast_edit 和 DAP 调试被有意设置为不注册。浏览器包仅包含编码工具设置卡片。

要求

  • Node.js 22.19+ 或 24+
  • DeepSeek Harness 0.1.1-rc.2 或兼容的公共服务契约
  • 提供 tools、fs、sandboxPolicy、sandbox、approval、spillStore、subprocess 和 settings 的 DSH 配置文件（标准 Web 配置文件已提供）
  • 由配置文件操作员配置的可选绝对路径语言服务器可执行文件

安装

构建本地检出，然后使用受支持的配置文件命令将其加入 DSH 配置文件：

pnpm install
pnpm check
dsh plugin --profile web add "C:\absolute\path\to\dsh-coding-tools"

该软件包提供 cordis.patch.yml，它会插入带软件包前缀的行 dsh-coding-tools。主机插件更改后，请重启 Web 配置文件。仅使用原始源码补丁并不等同于加入软件包。

对于已发布版本或 Git 安装，请固定到某个发布版本或提交，而不要使用浮动分支。

配置

设置 → 插件 → 插件配置中会出现一个可展开的编码工具卡片。它为 code_read、edit_ranges、ast_grep 和 lsp 提供开关，提供独立的要求编辑审批和要求进程启动审批控件，并针对降低进程隔离程度的原生 Windows 兼容性选择加入项给出醒目警告。审批提示默认开启。高级限制和语言服务器方案仍属于配置文件配置。保存的设置会持久化到 DSH 的用户层并实时生效：禁用的工具会被注销，启用的工具会被注册，进程支持的资源会在无需重启 DSH Web 的情况下停止或重新创建。重新配置会取消正在进行的读取和查询，等待可能已提交的编辑完成，并使现有游标和 code_read 版本令牌失效。

配置文件补丁层可以用显式基础配置替换插入的行：

- insert:
    - id: dsh-coding-tools
      name: 'dsh-coding-tools'
      config:
        inlineMaxBytes: 8192
        approvals:
          editRanges: true
          processStart: true
        processPolicy:
          allowWindowsPartialReadOnlyProcessConfinement: false
        codeRead:
          enabled: true
          defaultLines: 200
          maxLines: 2000
          maxBytes: 262144
          maxFileBytes: 16777216
          snapshotMaxBytes: 67108864
        versionedEdit:
          enabled: true
          requireObservedRanges: true
          maxOperations: 100
          maxChangedBytes: 1048576
          diagnosticsOnWrite: true
        ast:
          grepEnabled: true
          executable: '' # empty = pinned @ast-grep/cli binary
          maxFileBytes: 2097152
          maxMatchesPerPage: 50
          maxTotalMatches: 5000
          timeoutMs: 30000
        lsp:
          enabled: true
          servers:
            clangd:
              command: '/absolute/path/to/clangd'
              args: ['--background-index=false']
              extensions: ['.c', '.cc', '.cpp', '.h', '.hpp']
              languageId: 'cpp'
              env: {}
          maxOpenDocuments: 64
          maxDocumentBytes: 16777216
          maxDiagnosticBytes: 4194304
        debug:
          enabled: false

配置中的可执行文件路径必须是绝对路径。仓库文件绝不会选择二进制文件或注入命令行参数。环境条目是显式的；DSH 的子进程提供程序会在应用这些条目前移除环境中类似凭据的变量和 DSH_* 变量。

请参阅配置参考。

原生 Windows 兼容性

processPolicy.allowWindowsPartialReadOnlyProcessConfinement 默认为 false。在原生 Windows 上显式启用后，只有 ast_grep 和已配置的 LSP 启动可以接受 DSH 的 partial 受限令牌强制机制；在其他所有主机上以及对于任何未知的强制机制值，仍然要求 full。进程策略仍被强制设为 read-only，可执行文件方案仍由操作员控制，所有常规限制和生命周期清理仍保持生效。

这是降低后的隔离，而不是与 Linux 完全约束等效的 Windows 实现。所有人可写的 ACL 和 NTFS 硬链接可能削弱写入隔离，授予根目录之外的 FAT 类目标仍然可写，且后端不会隔离读取、网络访问或进程可见性。请仅对受信任的仓库和可执行文件使用此功能。

工具工作流

精确读取和编辑

  1. 调用 code_read，传入 file 以及可选的一基索引 offset / limit。
  2. 保留返回的 version。
  3. 调用 edit_ranges，传入完全相同的 file、version 和互不重叠的操作。
  4. 在只读会话中，使用 sandbox_permissions: workspace-write 和 justification 中的一句话重试被拒绝的调用一次；沙箱权限提升始终需要针对该单次调用的独立审批。在已可写会话中，只有启用 approvals.editRanges 时才需要常规变更提示。

禁用常规编辑审批不会放宽沙箱策略。标准 DSH 权限提升字段会针对单次调用放宽策略，并且始终保留审批；仅当挂载的文件系统报告沙箱强制机制时，才会公布这些字段。裸文件系统无法提升权限，并会在只读策略下以关闭方式失败。更改源文件的操作必须仅引用规范的、受字节限制的 code_read 结果中存在的完整行，并且该结果须属于相同所有者、规范目标和精确版本。超大行可能通过明确标记为未观察的预览和后续偏移量来报告，但绝不会获得变更授权。由于公共主机观察事件针对整个目标而非感知范围，插件仅在累计的同版本 code_read 页面明显覆盖完整文件后才发布该事件；编辑前请通过分页完成覆盖。append 是已观察范围的唯一例外，但仍要求已观察版本。所有操作会先完成验证，然后执行一次由提供程序版本保护的原子写入。

行操作语义：

  • replace：替换闭区间内的完整行，并保留下一个行分隔符
  • delete：删除闭区间内的完整行
  • insert_before / insert_after：使用文件的主要分隔符插入行形式的文本
  • append：追加文本；当文件末尾没有分隔符时，添加一个主要分隔符

BOM、现有未改动的行尾和 UTF-8 字节都会保留。无效 UTF-8 和包含 NUL 的二进制文件会以关闭方式失败。完整文件读取限制与返回结果限制相互独立。成功发布始终返回 applied: true；始终标识 intendedVersion，而 newVersion 仅在读取验证写入确已落地后出现。landedExact 和 postWriteWarning 会明确指出提交后验证或诊断的任何问题，以免调用方盲目重试已提交的写入。差异预览和完整结构化结果均受 UTF-8 字节限制，并明确给出大小、截断原因以及可用时的溢出定位器。

结构化搜索

ast_grep 接受一个模式、paths 中恰好一个常规工作区文件、必需的语言、可选的严格度、页面限制以及限定所有者的游标。启动前，它会：

  • 通过 ctx.fs 解析文件，并证明其规范路径位于工作区内
  • 拒绝显式符号链接和目录
  • 执行稳定且受字节限制的提供程序读取
  • 通过 stdin 将该不可变快照传给 ast-grep，绝不将其作为进程路径传递
  • 强制执行结果、捕获、游标、输出和时间上限
  • 当启用 approvals.processStart 时，为该进程启动请求一次审批并强制使用只读 DSH 策略；除非受信任的操作员显式启用原生 Windows 部分约束后备方案，否则仍然必须执行完全约束

宽泛的目录扫描被有意禁用。DSH 目前没有公开原子进程读取白名单/打开句柄契约，因此将工作区路径传递给后续进程会留下读取侧 TOCTOU 竞态。从有损的有界输出中保留的完整记录仍可安全返回。匹配项和解析错误会被去重、确定性排序、限制数量，并同时按项目数和渲染后/结构化 UTF-8 字节进行分页。不完整覆盖会通过明确的计数、字节上限、limitReasons 和有界的 parseErrors 报告。

语言服务器

lsp 支持 hover、definition、references、symbols 和 diagnostics。配置的服务器会延迟启动；启用 approvals.processStart 时请求一次性审批；其范围限定为所有者 + 规范工作区 + 配置文件，并在空闲超时或插件释放时停止。

客户端不声明任何编辑或命令能力。服务器对 workspace/applyEdit 的请求会被显式拒绝；动态能力、终端启动、工作区命令和未知服务器请求绝不会执行。会丢弃会话工作区之外的结果。

每个基于文件的操作都会在 lsp.maxDocumentBytes 限制内同步完整、稳定的 UTF-8 文档；绝不会将源文件前缀呈现为完整文档。LSP 源限制独立于 code_read 结果限制。位置会根据精确同步的 UTF-16 行进行检查，并且在工作区符号查询之前会同步所提供的文件。

定义、引用、符号和诊断会被规范化、去重、确定性排序、限制数量，并同时按项目数和渲染后/结构化 UTF-8 字节进行分页。计数会标明重复项、无效项或工作区外条目、省略项、源字节数和具体限制原因。只有服务器提供的版本与当前同步文档版本相对应时，诊断才会标记为新鲜。没有版本的诊断绝不会被认证为新鲜；它们可能作为覆盖不完整的陈旧证据返回。诊断保留会被去重并确定性排序，同时明确标明项目、字节和序列化损失原因。

安全性

请阅读安全模型和公共契约矩阵。审批提示默认启用。操作员可以显式、独立地禁用常规编辑和进程启动提示；精确版本观察、提供程序原子写入、绝对路径可执行文件方案、有界执行和强制只读进程策略仍是必需的。默认要求完全约束。只有显式启用 processPolicy.allowWindowsPartialReadOnlyProcessConfinement 时，原生 Windows 才可以接受 DSH 报告的部分强制机制。沙箱权限提升审批绝不会被绕过。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

本仓库独立于 DSH 源码检出。绝不要通过修补 DSH 来挂载它。