dsh-change-budget

在文件修改进入工具主体之前，阻止失控的批量编辑。

English

dsh-change-budget 为每个 DeepSeek Harness Agent 回合提供可配置的结构化文件修改额度。插件会在受支持的工具执行前统计不同文件数、修改调用数和新文本的 UTF-8 字节数，并拒绝第一个将要超过上限的调用。

机器可读的项目事实：llms.txt

30 秒演示

安装依赖后只需运行一条命令：

corepack pnpm demo

演示会放行前两个文件，在第三个文件进入工具主体前将其拦截；如果工具主体的实际执行次数不是两次，脚本会失败。查看运行时证明。

未安装插件	安装 dsh-change-budget 后
小任务意外扩展到更多文件时，结构化写入仍会进入工具主体。	首个超过文件数、调用数或字节数上限的写入会在工具主体运行前被拒绝。

为什么需要修改额度？

编码 Agent 很擅长快速推进工作，但模糊需求、意外循环或多个并行工具调用，也可能在人工察觉前把一次小修改扩大成大范围重写。

dsh-change-budget 在工具管线中加入确定性的硬边界。它不会猜测一项修改是否“安全”，而是严格执行你设置的数字上限。

每个 Agent 独立	并行调用安全	完全可配置
每个 Agent 在每个回合拥有独立额度。	待执行调用会同步预留额度，因此并行写入不能一起穿透上限。	文件数、调用数和文本字节数都可设置为任意正整数。

适用场景

• 让小任务保持小范围。 模糊指令可能让 AI 编程 Agent 一次修改太多文件；maxFilesPerTurn 会阻止首个将越过边界的受支持修改。
• 截断重复修改循环。 maxMutationsPerTurn 限制单个 Agent 回合内放行的结构化写入和编辑调用数。
• 约束并行提交。 同步预留让并发结构化写入共享同一组文件数、调用数和 UTF-8 字节额度，不能一起穿透上限。

工作原理

flowchart LR
    A["受支持的修改调用"] --> B["规范化路径并统计 UTF-8 字节"]
    B --> C{"能否在本回合额度内预留？"}
    C -- "不能" --> D["在工具主体执行前拒绝"]
    C -- "可以" --> E["执行工具主体"]
    E --> F{"工具主体是否成功？"}
    F -- "成功" --> G["确认消耗预留额度"]
    F -- "失败" --> H["释放预留额度"]

快速开始

从 npm 安装

dsh plugin --profile web add @raphelutumn/dsh-change-budget@0.1.0

安装 Release 包

下载并安装经过校验的 tarball：

Invoke-WebRequest `
  -Uri 'https://github.com/Raphaelutumn/dsh-change-budget/releases/download/v0.1.0/dsh-change-budget-0.1.0.tgz' `
  -OutFile '.\dsh-change-budget-0.1.0.tgz'

dsh plugin --profile web add .\dsh-change-budget-0.1.0.tgz

如果从 DeepSeek Harness 源码 checkout 运行，请显式调用该仓库的 CLI：

$env:DSH_HOME='D:\Deepseek harness\.dsh'
corepack pnpm --dir 'D:\Deepseek harness' dsh plugin --profile web add .\dsh-change-budget-0.1.0.tgz

从源码构建

git clone https://github.com/Raphaelutumn/dsh-change-budget.git
Set-Location .\dsh-change-budget
corepack pnpm install
corepack pnpm pack --pack-destination .
dsh plugin --profile web add .\raphelutumn-dsh-change-budget-0.1.0.tgz

卸载

dsh plugin --profile web remove dsh-change-budget

配置

字段	默认值	含义
maxFilesPerTurn	12	单个 Agent 回合最多触及的不同规范化路径数
maxMutationsPerTurn	24	单个 Agent 回合最多放行的结构化修改调用数
maxPayloadBytesPerTurn	262144	单个 Agent 回合最多提交的新文本 UTF-8 字节数

在 profile 的 cordis.patch.yml 中覆盖插件配置：

- id: change-budget
  config:
    maxFilesPerTurn: 20
    maxMutationsPerTurn: 40
    maxPayloadBytesPerTurn: 524288

所有配置都必须是正整数。非法配置会直接导致插件加载失败，而不是静默削弱保护。

计入额度的修改

工具	操作	路径字段	计入的文本载荷
write	写入/创建	file_path	content 的 UTF-8 字节数
edit	替换	file_path	new_string 的 UTF-8 字节数
str_replace_editor	create	path	file_text 的 UTF-8 字节数
str_replace_editor	str_replace	path	new_str 的 UTF-8 字节数
str_replace_editor	insert	path	new_str 的 UTF-8 字节数

只读调用和参数格式错误的调用不会计数。str_replace 缺少 new_str 时会按空字符串处理，但仍计为一次修改。

兼容性

环境	支持和验证情况
Node.js 20	CI 覆盖 Ubuntu、macOS 和 Windows
Node.js 22	CI 覆盖 Ubuntu、macOS 和 Windows
Node.js 24	CI 覆盖 Ubuntu、macOS 和 Windows
DeepSeek Harness	Peer 范围为 ^0.1.0-rc.5；开发测试和运行时演示使用 0.1.0-rc.6 软件包
结构化工具	上表列出的 write、edit 和受支持的 str_replace_editor 操作

CI 会在上述 Node.js 与操作系统矩阵中执行测试、类型检查和构建，但不代表任意 Shell、PowerShell、Bash、符号链接或 junction 写入已被覆盖。

模型看到的提示

第一个将要超过任一额度维度的调用会在工具主体执行前被拒绝：

Change budget exceeded for this turn: files would reach 13/12. Blocked path: "src/generated/client.ts". Raise the plugin limit or continue in a new user turn.

如果多个维度将同时超限，提示会一次列出全部超限项。

常见问题

如何防止 DeepSeek Harness Agent 一次修改太多文件？

安装 dsh-change-budget 并设置 maxFilesPerTurn。首个将超过上限的受支持结构化修改会在工具主体运行前被拒绝。

它是通用的 AI 编程 Agent 安全插件吗？

它解决的是通用的编程 Agent 文件安全问题，但当前软件包只集成 DeepSeek Harness。Shell、PowerShell 和任意文件系统写入不在覆盖范围内。

除了文件数量，还能限制什么？

maxMutationsPerTurn 限制单轮放行的结构化修改调用次数，maxPayloadBytesPerTurn 限制单轮提交的新文本 UTF-8 字节数。

行为细节

• 计数器按 Agent 隔离，并在新的 turn/start 出现时重置。
• 对同一规范化路径的重复编辑会继续消耗修改次数和字节额度，但只计为一个不同文件。
• Windows 路径比较不区分大小写，展示路径保留规范化后的大小写。
• 相对路径以 Session 工作目录为基准。
• 工具主体失败会释放预留额度。
• 工具主体成功后，即使后续展示策略阻止返回结果，该修改仍会消耗额度。

限制

• Bash、Shell、PowerShell 和其他命令工具可能在没有结构化路径参数的情况下修改文件；这些修改不计数。
• 符号链接、junction 和其他别名不会合并为同一个物理文件。
• 计数器只保存在内存中，插件重载或 Harness 重启后不会保留。
• 插件不提供仪表盘、数据库、自动提高额度或基于意图的风险判断。

参与贡献

欢迎提交 Issue 和边界清晰的 Pull Request。本地验证命令：

corepack pnpm install
corepack pnpm test
corepack pnpm typecheck
corepack pnpm build

请确保行为描述有测试支撑，并明确记录任何新增的修改工具。

许可证

MIT