前言¶

DeepSeek Harness（DSH）通过插件扩展能力，文件系统操作是常见需求。大多数文件工具依赖 JSON 封装，导致 Token 开销大；路径信息冗余，难以在上下文中快速定位。dsh-fs-compact 提供一组精简的文件操作工具，输出纯文本，路径相对于会话工作目录，并在执行替换前进行校验。

这是什么¶

dsh-fs-compact 是一个为 DSH 提供轻量级文件系统操作的社区插件，由 marya505 维护。它提供 fs_read、fs_grep、fs_glob 和 fs_replace 四个工具，输出为紧凑的纯文本，不依赖 JSON 封装或网络请求，仅使用纯 JavaScript 实现。

核心功能¶

• fs_read：读取 UTF-8 文本，按行编号，默认 800 行，支持 offset 继续读取；文件超过 8 MB 时流式读取
• fs_grep：使用正则表达式搜索文件，提供 files、content、count 三种模式，纯 JavaScript 实现，无原生二进制依赖
• fs_glob：支持 *、**、?、[a-z]、{a,b} 等通配符，返回相对于会话工作目录的路径
• fs_replace：全局正则替换，分两阶段校验，支持 dryRun 预览，使用 String.replace 语法（$1、$&、$<name>、$$）

安装与启用¶

安装需要 DSH 版本 >=0.2.1-rc.3。

# npm（推荐）
dsh plugin --profile <profile> add dsh-fs-compact

# 锁定版本
dsh plugin --profile <profile> add dsh-fs-compact@0.3.1

从 GitHub 安装（dsh plugin 会将参数转发给 pnpm）：

dsh plugin --profile <profile> add "github:marya505/dsh-fs-compact"

如遇 HTTPS 访问问题，可安装 tarball：

dsh plugin --profile <profile> add "https://codeload.github.com/marya505/dsh-fs-compact/tar.gz/347518e9d222fb70289068f26ad43992510a9598"

本地开发检出：

dsh plugin --profile <profile> add "file:<path-to-checkout>"

启用后，插件作为配置集（profile bundle）加载。如需在不卸载的情况下禁用，编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml：

- id: dsh-fs-compact
  disabled: true

典型用法¶

以下为工具的典型调用方式：

# 读取文件，默认显示前 800 行
fs_read path/to/file.txt

# 从第 801 行继续读取
fs_read path/to/file.txt offset:801

# 正则搜索，返回匹配行
fs_grep pattern:"error|fail" path/to/dir/

# 统计匹配次数
fs_grep pattern:"TODO" path/to/dir/ mode:count

# 查找所有 .js 文件
fs_glob "*.js"

# 全局替换（dryRun 预览）
fs_replace pattern:"foo" replacement:"bar" path/to/dir/

适用场景与注意¶

• 适合需要在 DSH 会话中快速浏览、搜索和修改文件内容的场景
• 工具以当前 DSH 进程的权限运行，需确保配置正确的沙箱策略
• 目录扫描会跳过 .git、node_modules、dist、target，限制为 50,000 文件或 256 MB，输出长度上限 24,000 字符
• fs_replace 在写入前会校验匹配数量、文件大小和沙箱策略，超限时不会修改文件并提示
• 插件为社区插件，与 DeepSeek 或幻方无官方隶属关系

结语¶

dsh-fs-compact 通过纯文本输出和相对路径设计，减少了 Token 消耗，适合需要频繁操作文件系统的 DSH 场景。更多细节可参考 GitHub 仓库。