精简文件工具 marya505/dsh-fs-compact

dsh-fs-compact

给 DeepSeek Harness（DSH）用的省 token 文件系统工具：fs_read、fs_grep、fs_glob 和 fs_replace。输出是紧凑的纯文本，路径相对于会话 cwd，并带「先读后替换」保护。

非官方社区插件，与 DeepSeek 无隶属关系，也未获其背书。

工具

| 工具 | 用途 |
| fs_read | 按 UTF-8 文本读取，输出带行号，默认 800 行，用 offset 续读；超过 8 MB 的文件走流式读取 |
| fs_grep | 正则搜索（纯 JavaScript，无原生二进制）；mode = files / content / count |
| fs_glob | 支持 、、?、[a-z]、{a,b} 通配；返回相对 cwd 的路径 |
| fs_replace | 全局正则替换，分两阶段校验，dryRun 可预览 |

设计取舍：

- 输出纯文本，不带 JSON 外壳，也没有记账字段；
- 路径每组只打印一次，相对会话 cwd；
- 工具 schema 保持紧凑，让提示词更小；
- 目标文件没先读过（或只读了一部分）时，fs_replace 会给出警告；
- 不遍历 .git、node_modules、dist、target。

安装

要求 DSH >=0.2.1-rc.3。

From GitHub — dsh plugin forwards its arguments to pnpm
dsh plugin --profile <profile> add "github:marya505/dsh-fs-compact"

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

<profile> 是你用的 DSH 配置档，比如 desktop。如果 dsh 不在 PATH 里，就从 DSH 安装目录运行命令行，例如 <DSH install>/resources/runtime/cli/bin/dsh（Windows 上是 .cmd）。

更新。 pnpm 对 file: 依赖用硬链接，所以只跑 add 不会刷新已安装的本地检出：

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

安装或更新后重启 DSH 桌面应用。

启用 / 禁用

以配置档 bundle 的形式启用。想关掉又不想卸载，就往 ~/.dsh/profiles/<profile>/cordis.patch.yml 里加：

- id: dsh-fs-compact
disabled: true

如果另一个已安装插件也提供文件工具，就禁用其中一套，免得模型拿到重叠的工具。

卸载

dsh plugin --profile <profile> remove dsh-fs-compact

然后重启 DSH。只想禁用不想卸载，用上面的 disabled: true 条目。

兼容性

- DSH >=0.2.1-rc.3（在 0.2.1-rc.3 上测试过）。
- 开发和测试需要 Node.js 20+。
- 纯 JavaScript；无原生二进制，无运行时依赖。

安全模型

- fs_read、fs_grep 和 fs_glob 只读。插件不发网络请求，也不启动进程。
- fs_replace 遵循调用时解析出的宿主沙箱策略：
- read-only 拒绝写入；
- workspace-write 只允许写工作区内和操作系统临时目录；
- danger-full-access 允许任意可写路径；
- 其他模式一律拒绝（失败即关闭）。
- 目录扫描跳过 .git、node_modules 和构建产物，跳过符号链接，并在 50,000 个文件 / 256 MB 处停止。
- fs_replace 在写入任何内容之前先校验每个目标（匹配数、文件大小、输出大小和策略）；超限调用不会改动任何内容。

漏洞上报见 SECURITY.md。

语义

通配符。 模式匹配的是相对于所搜索 path 的路径。
不含 / 的模式也会匹配基名，所以 .js 保持递归，而 src/.js 是一层路径过滤。include、exclude 和 replace 的 glob 都用同一套实现。

替换字符串。 fs_replace 使用 String.replace，因此 $1（捕获组）、$&（整个匹配）、$<name>（命名组）和 $$（字面 $）都可用。想写字面美元符号时写 $$。

限制与失败行为。 fs_replace 先规划每个文件——统计匹配数、检查 maxReplacements、文件大小和沙箱策略——然后才写入。超限调用不改动任何内容，并会说明。单个写入失败会报告为 skipped，而不是中止整批（已写入的文件不会回滚）。

扫描。 扫描在 50,000 个文件或 256 MB 处停止，并会说明。符号链接跳过。输出上限为 24,000 字符；fs_grep 会报告因过大 / 不可读 / 二进制而跳过的文件。

为什么它是 bundle，而不是普通依赖

DSH 的插件列表只显示 配置档层：即 package.json 中带有 dsh.bundle.patch 的包。普通依赖只要有人插入仍会加载，但市场 UI 从不列出它（命令行甚至会警告 declares no dsh.bundle — installed as a plain dependency, not a profile layer）。

因此本包附带：

- package.json → dsh.bundle.patch: ./cordis.patch.yml
- cordis.patch.yml → 挂载插件的 insert 条目

执行 dsh plugin add 时，DSH 的 reconcile 步骤会应用该补丁，并把 dsh-fs-compact 追加到 dsh.profile.bundles，正是这一步让它作为已安装插件可见。

注册陷阱

ctx.tools.register() 要求 output: { schema, render }。省略
output.schema 会抛出 TypeError: tool "x" must declare output { schema, render }，而如果这个抛出发生在 ctx.effect(...) 内部，它会被吞掉——提示词段落仍然出现，于是插件看起来*已安装，而它的工具一个都不存在。schema 必须与 execute 返回的值一致；本插件返回 { text: string }。

工具只在 ctx.inject(['tools']) 下注册。沙箱策略在调用时解析，所以缺少 sandboxPolicy 服务不会让工具悄悄消失。

开发

git clone https://github.com/marya505/dsh-fs-compact.git
cd dsh-fs-compact
node --test

测试套件针对 os.tmpdir() 夹具运行，覆盖读取分页/流式传输， grep 模式与上下文合并、glob 语义、替换原子性、策略 fail-closed 行为、错误码映射，以及注册入口。

License

MIT © 2026 marya505