# 我的 DSH 使用手记：两个提案的由来（三车道模型 × 启动自愈）

> 本文件包含两篇独立博客文章，可用 `---` 分隔处拆分发布。
> 文章一：AI 工具使用方法论（三车道模型）
> 文章二：插件故障自愈（健康守卫 + 官方提案）

---

## 文章一

# AI 用工具总报错？"三车道模型"帮你根治——read 和 bash 的正确用法

用过 AI 编程/写作助手的朋友，多半见过这类报错：

```
edit requires reading "xxx.md" first
file changed since it was read — re-read the file, then retry
```

任务最终都能完成，但每轮都来这么一下，很烦。我在 Claude Code CLI 里遇到过，换到 DeepSeek Harness（DSH）后依然遇到。这到底是工具的 bug，还是我的用法有问题？我花了一天时间把它查到底，结论很有意思：**不是工具坏了，是我一直在"混车道"开车。**

## 先搞清楚机制：为什么 edit 前必须先 read？

DSH 的文件系统有一个"观察策略"（fs-observation-policy），本质是一道防呆守卫：

1. 你用 `read` 工具读文件时，系统会**登记一条观察记录**（带文件版本号）；
2. 你用 `edit` 修改文件时，系统要求**必须有这条观察记录**，并且文件版本要和你读的时候一致；
3. 没有记录 → 报 "requires reading first"；记录过期（文件在你读后被改过）→ 报 "file changed since it was read"。

为什么要这么设计？因为要防止 AI 干一件很危险的事：**凭记忆/猜内容去覆盖一个它根本没读过的文件**，或者覆盖一个**已经被别人（比如你自己）改过的文件**。这是并发编程里的 CAS（Compare-And-Swap）思想：改之前先确认"你看到的还是最新的"。

这个守卫本身，我非常认可。它两次救了我的文件不被 AI 静默覆盖。

## 那问题出在哪？——bash 是个"黑盒"

我的坏习惯是：想看看文件内容时，随手用 bash（`cat`、`head`、`grep`）看一眼，然后直接 `edit`。

但 DSH 无法知道 bash 子进程内部读了什么——**bash 是黑盒，读文件不登记观察记录**。于是：

- bash 读 + edit 改 = 必然报 "requires reading first"

这不是机制的漏洞，而是架构决定的：要让 bash 登记观察，得做系统调用级拦截，成本极高。所以设计上只有 `read` 工具是"可信通道"。

## 核心洞察：错误只产生于"混用车道"

想通之后，我把文件操作分成了三条"车道"：

| 场景 | 车道 | 正确工具 |
|------|------|---------|
| 单点语义修改（改一个页面、插一条日志） | 观察车道 | `read`（同一轮）→ `edit` |
| 探索/统计（文件在哪、多大、含什么） | 只读车道 | `glob`/`grep`，或 bash 只读命令 |
| 批量机械变换（全库链接修复、批量替换） | 脚本车道 | 一条 bash/python 脚本直接写完，**不走 edit** |

**只要不混车道，这类报错就永远不会出现。** 我复盘了所有报错，100% 是混用：bash 读 + edit 改。

## 还有个反直觉的边界：read → bash 改 → edit

我做了实测（写了个临时文件完整走了一遍）：

| 步骤 | 操作 | 结果 |
|------|------|------|
| 1 | `read` 读文件 | ✅ 登记观察 |
| 2 | bash 追加一行 | ✅ 不报错（bash 不在观察体系内） |
| 3 | `edit` 改同一文件 | ❌ "file changed since it was read" |
| 4 | 重新 `read` → 再 `edit` | ✅ 正常 |

结论：**bash 写会悄悄作废你手里的 read 记录**。正确姿势是"脚本改完 → 重新 read → 再 edit"。

## 为什么"图省事"反而更费事？

两种"省事"要分清：

- **省调用次数**（真效率）：一条 bash 管线合并多步操作，批量改 200 个文件的链接，脚本一次写完——这是脚本车道的价值；
- **省读取**（假效率）：bash 看一眼就 edit——必然被守卫拦下，重读重试，反而多花一轮。

## 这不是 DSH 独有的问题

我查了一圈：Claude Code 的 GitHub issue 里，这类抱怨一抓一大把（"Edit tool fails after every user message"、"File has not been read yet" 等），社区早就反馈过。各家解法也不一样：

- **Claude Code / Trae**：提供 write 覆盖但不设版本守卫——最危险，用户手动改的内容可能被直接冲掉；
- **Codex / holon**：干脆全走 shell（"shell 是模型最熟的语言"），没有观察体系，代价是编辑复杂度和输出截断；
- **DSH**：提供 write 但带版本守卫——文件被外部改过就拒绝，宁可用一次重读换数据安全。

我的判断：**守卫保留 + 场景路由**是最优解。工具没有好坏，只有用对场景。这个"三车道模型"我已提交到 DSH 官方讨论区，欢迎讨论：

🔗 https://github.com/deepseek-ai/deepseek-harness/discussions/2509

---

## 文章二

# 一个坏插件能让你的 AI 助手失联——我是怎么用"健康守卫"自救的，还提了个官方提案

先讲一个真实事故。

## 事故：装了个主题插件，整个 AI 助手没了

某天我给 DeepSeek Harness（DSH）装了一个社区主题插件。重启后，Web 界面起不来了。

DSH 是 **fail-fast** 设计：任何一个插件加载失败，整个程序直接退出。而这个插件缺一个依赖（`schemastery`），加载器报 `Cannot find package 'schemastery'`。加上系统级守护（launchctl KeepAlive）会反复拉起，于是程序陷入"启动 → 失败 → 重启 → 再失败"的崩溃循环。

最要命的是：**DSH 的 Web 界面是我唯一的 AI 助手入口。** GUI 起不来 = 助手失联。要修复就得改配置文件，可"能帮我改配置的助手"恰恰就是那个起不来的东西。最后是靠另一台机器上的另一个 agent 才救回来。

这暴露了一个空白：**fail-fast 保证了"不带着坏状态跑"，但失败之后呢？没有任何恢复路径。** 没有"上次健康状态"的快照，没有自动回滚，没有修复命令。

## 自救：给 dsh 套一个"健康守卫"

我写了一个守护脚本（`dsh-web-guard.sh`），原理很简单：

```
启动 dsh → 探测 http://127.0.0.1:3080（20 秒超时）
  ├─ 成功 → 把当前 package.json + pnpm-lock.yaml 存为"健康快照"
  └─ 失败 → 恢复最近健康快照 → pnpm install --frozen-lockfile → 重启
```

再加两个细节：

- **端口清理**：`launchctl kickstart -k` 杀掉守护后，旧进程可能残留占用 3080 端口，导致新实例 EADDRINUSE 起不来——启动前先清端口；
- **快照自动更新**：每次成功启动都更新快照，保证回滚目标是"最近一次真正跑起来的状态"。

## 实战验证：一天两次救回环境

就在同一天，这个守卫连续两次实战：

1. **第一次（上午）**：catppuccin 主题插件缺依赖，崩溃循环——守卫回滚快照、重装、恢复；
2. **第二次（晚上）**：装 GitHub 登录插件时，插件自带的配置文件里包名写错了（声明 `@deepseek-ai/dsh-github-login`，实际包名 `dsh-github-login`），启动报 `ERR_MODULE_NOT_FOUND`——守卫数秒内自动回滚，界面恢复，等我修好配置再正常启动。

两次都是"无人值守自动救回"。这正是早上那次事故的教训换来的。

## 一个反向思考：fail-fast 到底保护了什么？

fail-fast 是对的：带着坏状态继续跑，比不跑更危险（数据损坏、行为错乱）。但"快速失败"只回答了前半句，**后半句"失败之后怎么回来"被忽略了**。守护进程只会重复同样的失败，用户被困在门外。

所以我认为 DSH 需要内置恢复路径，而不是靠用户自己写外部脚本：

1. **健康快照（自动）**：启动成功后记录依赖状态；
2. **失败自动回滚（可选开启）**：启动失败且存在健康快照时，恢复快照重装并限次重试；
3. **手动修复命令**：`dsh --repair`——恢复上次健康状态，作为显式救援路径；
4. **可操作的失败诊断**：启动失败时直接告诉你"哪个插件挂了、为什么、怎么救"。

我已经把这个提案发到 DSH 官方讨论区：

🔗 https://github.com/deepseek-ai/deepseek-harness/discussions/2514

## 一点感想

两个提案都不是凭空想的，全部来自同一天的实战：**一次事故、两次救回、三次踩坑**。工具是死的，用法是活的；把踩坑变成提案，把提案变成别人的避坑指南——这大概就是技术人最好的复盘方式。

---

*作者：一名运维工程师。工具：DeepSeek Harness（DSH）。欢迎在评论区交流你的踩坑经历。*


本文件包含两篇独立博客文章，可用 --- 分隔处拆分发布。 文章一：AI 工具使用方法论（三车道模型） 文章二：插件故障自愈（健康守卫 + 官方提案）

DSH 使用手记：两个提案的由来（三车道模型 × 启动自愈）

人工智能

开发工具

运维

本文通过实战解析DSH工具两大痛点：提出"三车道模型"解决read/bash混用报错，详解文件操作场景路由；并分享插件故障自愈方案，通过健康快照与自动回滚机制守护AI助手可用性，附官方讨论区提案链接。

数据安全

文件系统

代码解释

AI编程

路由

GitHub

快速部署LLM、AI绘画等应用,助你玩转AIGC！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

DSH 使用手记：两个提案的由来（三车道模型 × 启动自愈）-腾讯云开发者社区-腾讯云

DSH 使用手记：两个提案的由来（三车道模型 × 启动自愈）

DSH 使用手记：两个提案的由来（三车道模型 × 启动自愈）

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐