自动恢复 cyanseek/dsh-autofix

dsh-autofix

开发版本 0.1.1（GitHub 源码版，未发布 npm 包）：2026-09-28 在 Windows Node.js 24.11.1、DSH 0.1.7-rc.2 上完成本地验证。审批拒绝和后置策略阻止不会触发恢复；安装使用当前执行包并校验升级版本。 本轮未重跑真实模型端到端及原生 macOS 验证。

DSH 报错后别停：自动重试、自动刷新、自动换路，任务继续跑。

安装一次，然后照常使用 DeepSeek Harness。命中支持范围的错误时给出一次明确恢复动作；未知错误保持不变。

- Web 或 API 瞬时错误：重试一次
- 编辑期间文件变化：刷新当前上下文
- 当前系统缺少命令：使用已安装的等价命令
- 常见 DSH 错误：给 Agent 可直接执行的下一步

安装

npx -y github:cyanseek/dsh-autofix install

完成。之后正常使用 DSH。

使用前后

Web 工具返回 502

以前：HTTP 502 → 任务暂停 → 用户说“继续” 现在：HTTP 502 → AutoFix 要求重试一次 → 任务继续

编辑时文件发生变化

以前：old text not found → 用户转述错误 → Agent 再读取现在：old text not found → AutoFix 刷新有界片段 → Agent 重新编辑

不同平台的命令名称不同

以前：找不到 rg → 任务停止现在：找不到 rg → AutoFix 找到已安装的等价命令 → Agent 继续

恢复 Recipe

| Recipe | 识别范围 | 动作 |
| 瞬时工具错误 | 限流、部分 408/5xx、超时和传输重置 | 要求 Agent 对同一操作重试一次，再失败就换方案 |
| 过期文件上下文 | 明确的编辑过期和替换未命中错误 | DSH 文件服务可用时附加当前文件的有界片段 |
| 命令替代 | Shell 工具的 command-not-found 错误 | 只推荐当前 PATH 中真实存在的第一个等价命令 |
| DSH Error Atlas | 一组受控且有版本的常见 DSH 错误 | 附加简短下一步，不改写 profile 或 session 数据 |

公开目录见 recipes/catalog.json。欢迎通过 Recipe 需求表单 补充常见错误。

零打断契约

dsh-autofix 只在工具已经失败后工作。它不增加审批弹窗、不修改工具参数、不改变成功结果、不安装系统命令、不要求额外服务，也不增加 UI。

同一错误在短窗口内最多触发一次恢复。第二次相同失败保持可见，让 Agent 换方案。取消会停止待处理的恢复工作；卸载会移除插件和随包 Skill。

未知错误保持原样。

兼容性

当前候选版本通过 58 项测试，包含真实 DSH ToolRuntime、审批拒绝和后置策略阻止回归；TypeScript 7.0.2 使用显式 Node 类型配置完成构建。历史版本和平台证据单独保留在兼容矩阵。

准确证据与限制见兼容矩阵。

高级 Test Kit

维护者可以运行随包提供的确定性恢复检查：

dsh-autofix test --scenario transient-tool-error --json

可用场景为 transient-tool-error、stale-file、command-alternative 和 error-atlas。

插件作者可以导入稳定的 Recipe 接口：

import { applyRecipes } from 'dsh-autofix'
import type { AutoFixRecipe } from 'dsh-autofix/recipes'

const recipes: AutoFixRecipe[] = [myRecipe]
applyRecipes(ctx, recipes)

该高级入口应放入一个自定义 bundle，不要再同时挂载默认 bundle。Recipe 按 priority 降序执行，重复 ID 会立即报错。

旧的确定性故障引擎继续作为高级回归测试工具提供：

import { ChaosEngine } from 'dsh-autofix/testkit'

普通用户无需使用 Test Kit。

开发与贡献

npm ci --ignore-scripts
npm run check

一个恢复贡献应保持很小：一个 Recipe、一个确定性回归测试和一个简短目录条目。提交前请阅读 CONTRIBUTING.zh-CN.md。

许可证

MIT