提案：文件工具"三车道"场景路由——完善"用 read 别用 shell"的指引（附实测数据）

[dc0012]

中文 🇨🇳

摘要

当前 read/edit 的模型指引是绝对化的："Use the read tool — not shell commands like cat"、"Read the file first (the default fs-observation-policy requires it)"。实践中，这个指引对「单点语义修改」正确，但对「探索」和「批量机械变换」是低效的——shell/脚本一次管线调用胜过几十次 read→edit 往返。FS_NOT_OBSERVED 摩擦的真正来源是混用车道：用 shell 读（黑盒子进程，从不登记 fs/observed 观察）然后再用 edit 工具（要求观察）。按场景路由的三车道模型可以在不削弱守卫的前提下消除这一类错误。本提案建议把该模型写进官方文档/系统提示词，并附实测数据。

背景

fs-observation-policy 是防止"AI 基于过期记忆覆盖用户已修改文件"的版本守卫（CAS），机制本身正确且必要。但在真实使用中（包括非开发者/运维用户），模型经常因"图省事"用 shell 查看文件后直接 edit，触发 FS_NOT_OBSERVED（"edit requires reading ... first"），重读后重试——功能能完成，但流程噪音反复出现。

根因

1. edit/write 前必须有该文件的 read 观察记录（按会话 + CAS 版本比对）。无记录 → FS_NOT_OBSERVED；记录过期（read 后文件被改）→ 版本不匹配。
2. bash 子进程是黑盒：DSH 无法得知 shell 内部读了哪些文件，因此 shell 读取不登记观察。这是架构决定，不是缺陷。
3. 错误只产生于「混用车道」：shell 读（不登记观察）+ edit 改（要求观察）→ 必然冲突。选对车道即消除该类错误。

三车道模型

场景	车道	工具
单点语义修改（改一个页面、插一条日志）	观察车道	read（同轮）→ edit
探索/发现/统计（文件在哪、多大、含什么、几行）	只读车道	glob / grep / shell 只读管线
批量机械变换（全库链接修复、批量替换、格式修正）	脚本车道	一条 shell/python 直接写完（不经 edit）

补充：

• 毒化边界（实测）：read → shell 写 → edit 同一文件 = 报 "file changed since it was read"。shell 写会悄悄作废 read 快照；恢复姿势 = 脚本改完后重新 read 再 edit。
• 复杂任务分发/子任务管理属于 subagent/workflow 工具，shell 只做聚合/预处理。

实测

（2026-08-16，macOS，dsh web profile）用临时文件完整走了一遍链路：

步骤	操作	结果
1	read 读文件	✅ 登记观察
2	shell echo >> 追加	✅ 不报错（shell 对策略不可见）
3	edit 同一文件	❌ file changed since it was read
4	重新 read → 再 edit	✅ 正常

另验证：shell 读（cat）+ edit → FS_NOT_OBSERVED（"edit requires reading first"）。

建议修改

1. README「Model Experience / Read guidance」补充场景路由提示（建议文本）：

   Route file access by scenario: surgical single edits → read then edit (observation lane); exploration/statistics → glob/grep or shell read-only; bulk mechanical transforms → one script/shell write pass, never mixed with edit. Mixing lanes (shell-read + edit, or read → shell write → edit) fails the observation guard; after a shell write, re-read before edit.

2. 可选：FS_NOT_OBSERVED 错误信息增强：提示"若刚才是用 shell 查看的该文件，请改用 read 工具，或整批改用 shell 写入"——把报错从"失败"变成"车道提示"。

影响

• 对开发者：批量重构/迁移时脚本车道省几十倍调用。
• 对非开发者/运维用户（本提案作者场景）：知识库/文档维护中"单点改 vs 批量修"天天并存，场景路由让 DSH 既保留数据保护又免去流程噪音。
• 车道模型通用：同时适用于有守卫的工具集（DSH / Claude Code）与无守卫的（Codex / holon 全 shell 派）。

报告人场景：云上陕西运维，Obsidian 知识库 + DSH 日常维护。规则已本地固化（file-edit-discipline），本提案为通用化建议。

English 🇬🇧

Summary

The current model-facing guidance for read/edit is absolute: "Use the read tool — not shell commands like cat — to inspect text files" and "Read the file first (the default fs-observation-policy requires it)". In practice this guidance is correct for surgical single edits but inefficient for exploration and bulk mechanical transforms, where shell/scripts are strictly better (one pipeline call vs dozens of read→edit round-trips). The real source of the FS_NOT_OBSERVED friction is lane mixing: reading via shell (a black-box subprocess that never registers an fs/observed observation) and then editing via the edit tool (which requires an observation). A scenario-routed three-lane model eliminates this error class without weakening the guard. This proposal asks for documenting that model in the README / system prompt, and includes empirical test data.

Background

fs-observation-policy is a version guard (CAS) that prevents an AI from overwriting user-modified files based on stale memory. The mechanism is correct and necessary. In real usage (including non-developer / operations users), the model often reads files via shell "for convenience" and then calls edit, triggering FS_NOT_OBSERVED ("edit requires reading ... first"); after a re-read and retry the task completes, but the friction recurs constantly.

Root cause

1. edit/write require a prior read observation (per-session CAS version compare). Missing → FS_NOT_OBSERVED; stale (file changed after the read) → version mismatch.
2. A shell subprocess is a black box: DSH cannot know which files a shell command read, so shell reads never register an observation. This is an architecture decision, not a bug.
3. The error only arises from lane mixing: shell-read (no observation) + edit (observation required) → guaranteed conflict. Route by scenario and the error class disappears.

The three-lane model

Scenario	Lane	Tools
Surgical single edit (edit a page, insert a log entry)	Observation	read (same round) → edit
Exploration & stats (where/what/size/line count)	Read-only	glob / grep / shell read-only pipelines
Bulk mechanical transforms (mass link fixes, batch replace, format fixes)	Script	one shell/python pass writing directly (never via edit)

Notes:

• Poisoning boundary (tested): read → shell write → edit same file errors with "file changed since it was read": a shell write silently invalidates the read observation; recovery = re-read after the script pass, then edit.
• Task dispatch / subagent management belongs to subagent/workflow tools; shell is for aggregation/preprocessing only.

Empirical test

(2026-08-16, macOS, dsh web profile) A full pass over a temporary file:

Step	Action	Result
1	read the file	✅ observation recorded
2	shell echo >> append	✅ no error (shell is opaque to the policy)
3	edit the same file	❌ file changed since it was read
4	re-read, then edit	✅ normal

Also verified: shell-read (cat) + edit → FS_NOT_OBSERVED ("edit requires reading first").

Suggested changes

1. README「Model Experience / Read guidance」: add scenario-routing hint (suggested text):

   Route file access by scenario: surgical single edits → read then edit (observation lane); exploration/statistics → glob/grep or shell read-only; bulk mechanical transforms → one script/shell write pass, never mixed with edit. Mixing lanes (shell-read + edit, or read → shell write → edit) fails the observation guard; after a shell write, re-read before edit.

2. Optional: augment the FS_NOT_OBSERVED message with lane hints — "if you just viewed this file via shell, either use read first, or switch the whole pass to shell writes" — turning the error from a dead-end into a lane hint.

Impact

• Developers: the script lane saves dozens of calls in bulk refactors/migrations.
• Non-developer / operations users (this proposal's author scenario): in knowledge-base/doc maintenance, "surgical edits vs bulk fixes" coexist daily; scenario routing keeps DSH's data protection while removing the friction.
• The lane model is generic: applicable to guarded tool sets (DSH / Claude Code) and unguarded ones (Codex / holon all-shell).

Reporter scenario: cloud operations engineer (Shaanxi), Obsidian knowledge base + DSH daily maintenance. Rule locally solidified (file-edit-discipline); this proposal is the generalized form.

[Overraingit]

多调用一轮确实不爽

[deepseekv41flash]

补充一个 #2509 没有覆盖的变体，来自 Windows 上的实测：当预设里只有 shell 工具时，「三车道」里没有一条可行车道。

场景

本机 DSH Desktop Next（上游 dsh 0.2.1-rc.2）装了第三方预设「极简模式 (Git Bash)」。该预设的工具面只有两个：bash（Git Bash）和 str_replace_editor。模型很自然地用 bash 的 cat 看文件、再用 str_replace_editor 改，于是稳定复现：

cannot modify "…": file has not been read — read the file, then retry

与 #2509 的关系：机制一致，但结论需要补一条

我核对过，这不是缺陷，文档甚至已经写明（@deepseek-ai/dsh-fs-observation-policy/README.zh.md，已知限制第 130 行）：

直接 ctx.fs 读取不会发出 fs/observed：在 read 工具之外读取的文件仍未观察；后续防护编辑会以 FS_NOT_OBSERVED 拒绝，直到工具读取该文件。

观察记录只由原生工具发出：dsh-tool-fs 的 read/edit/write、以及 dsh-tool-str-replace-editor 的 view（三处 ctx.emit("fs/observed", …)）。shell 子进程对策略是黑盒 —— 与 #2509 的根因 2 完全一致。

差别在于：在三车道模型里，「观察车道」的前提是存在 read 工具。而极简类预设（含 Windows 的 Git Bash 变体）刻意把工具面压到 bash + 编辑器，没有 read。这时：

车道	在本预设里
观察车道（read → edit）	不存在 read；实际可行的是 str_replace_editor view → edit（view 确实登记观察），但模型不会自己想到
只读车道（glob/grep/shell）	有 shell，但正好落进"混用车道的陷阱"
脚本车道（一条 shell 写完）	可行，可是模型若只想改一处，更倾向 str_replace_editor

所以这里的摩擦来源不只是"模型图省事"，而是提示词里没有把 shell 车道和观察车道分开讲：极简预设的固化 persona 只说"用 bash"，str_replace_editor 的工具描述也不会提示"用 view 才能建立观察"。

生态旁证

• MichaelShii/dsh-plugin-teamflow#15：「Sub-agents are restarted due to read-before-write gate error」——同一个门禁导致子代理重启。
• 第三方 shell 插件（如 dsh-bash-terminal）已经把 shell/terminal 做成一等工具，但它们的提示词里同样没有"shell 读取不计入观察"的提醒。

三条建议（按落地成本排序）

1. FS_NOT_OBSERVED 文案加一句车道提示（与 提案：文件工具"三车道"场景路由——完善"用 read 别用 shell"的指引（附实测数据） #2509 建议 2 一致，此处附议）：现在只说 "read the file"，改成点明"若刚才是用 shell 查看的，请改用 read（或编辑器 view），或整批改用 shell 写入"。
2. 让 shell 工具能声明自己的观察边界：例如给 @deepseek-ai/dsh-tool-bash / dsh-tool-pwsh 的固定描述里加一句"本工具内的读取不登记 fs/observed；随后编辑同一文件前请用 read/view"。第三方 shell 插件可以照抄这一句。这样不必每个预设作者各自摸索。
3. （可选）policy 增加配置：per-tool 豁免或整体关闭 read-before-edit，默认保持现状。当前 policy 没有任何 Config，想放宽只能整行 disabled，会把 FS_STALE_VERSION 守卫一起丢掉。

一句话总结：文档层面已经说清了，缺的是把这条边界送进模型看得见的地方（工具描述/错误文案），尤其是没有 read 工具的预设。