前言¶
在 DeepSeek Harness（DSH）里跑智能体改代码时，文件系统观察策略 dsh-fs-observation-policy 会要求模型先读后改。只有走 read 工具（含分段读）、成功的 write/edit、读图片等通道时，才会登记「已观察」；用 bash 做 sed -n、awk、cat、python3 - <<PY 等方式看过文件，不会登记。
模型查代码时往往更习惯 bash。README 里引用的实测会话日志是 1186 次 bash 对 114 次 read，其中 4 次编辑被拒，全部发生在「此前只有 bash 看过、read 次数为 0」的文件上。内容其实看过，只是看的通道不算数，于是反复出现：
Error: cannot modify "…/index.vue": file has not been read — read the file, then retry
每次只能再读一次、重试，长会话里多不少无效来回。下面介绍社区插件 @ruaibeite/dsh-auto-observe（维护者 ruaibeite，SkillHub 分类：记忆）如何在这一约束下补登记观察记录，减少 FS_NOT_OBSERVED 拒改。
这是什么¶
@ruaibeite/dsh-auto-observe 是 DSH 宿主插件（通过 cordis.patch.yml 挂载），在 fs/edit-intent / fs/write-intent 的 waterfall 上前置监听器。当编辑目标在策略账本里还没有观察记录、且智能体从未用过 read 工具读过该文件时，插件用 ctx.fs.stat 取真实版本，并按 read 工具的做法发出 fs/observed，使策略不再以「未读」为由拒改。
没有安装 dsh-fs-observation-policy 时，它只是多一次 stat，不改变写入语义。常与 @deepseek-ai/dsh-fs-local、@deepseek-ai/dsh-fs-observation-policy、@deepseek-ai/dsh-tool-fs 组合使用。
报错从哪来¶
策略要求先读后改，登记观察的通道与 bash 探查对比如下：
| 通道 | 是否登记观察 |
|---|---|
read 工具（含 offset/limit） |
是 |
成功的 write / edit |
是 |
| 读图片 | 是 |
bash：sed -n、awk、cat、python3 - <<PY 等 |
否 |
README 中列出的被拒案例均符合「失败前 read 为 0、bash 已多次读过该文件」这一模式。
核心机制¶
监听器必须用 prepend 注册：策略侧的监听器不调用 next()，排在后面则轮不到本插件。规则概括为三条：
- 同时监听
fs/observed，维护与策略同构的镜像账本（会话对象 → targetKey）。目标已有记录 → 不干预，直接交回 waterfall，因此「文件在你读过之后被改过」时的FS_STALE_VERSION保护原样保留。 - 目标没有记录时，
stat一次真实版本，发出fs/observed：存在为{kind:'present', version}，不存在为{kind:'absent'}。策略视为「刚读过」，返回正常版本守卫。 - 非普通文件、拿不到会话归属（
actor.agent.session缺失）、stat抛错时一律不插手，原样交回。
代价与开关¶
插件记下的观察是文件此刻的真实版本，不是断言「模型看过内容」——放宽的是策略对「已读」的解释。模型可能只知道路径存在、并未用 read 看过正文。
- edit（锚定替换）默认开：替换仍须逐字匹配当前内容；过期 CAS 基准不会被本插件覆盖（见上第 1 条）。
- write（整文件覆盖）默认关：盲覆盖没有逐字匹配兜底；若开启需显式配置
writes: true，并清楚自己在放弃「先读后写」这层保护。 - 每次介入默认打一行日志（
log相关开关），避免安全放宽无声发生。
契约测试还覆盖 edits、writes、log 三个开关及 prepend 注册位置。
已知边界¶
镜像账本从本插件加载时开始记。正常安装路径会重启 Harness，与策略内存账本同步清零。若在已读过若干文件之后才热启用插件，旧记录不在镜像里，插件可能为这些目标补登记当前版本，相当于这一次放宽过期判定；重启 Harness 即可回到与策略一致的状态。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前请自行查看 GitHub 仓库 源码与 MIT 许可证。
在仓库目录执行：
./install.sh # 装进 desktop profile（默认）
PROFILE_NAME=web ./install.sh # 装进别的 profile
宿主插件不像客户端插件那样热重载，装完必须重启 Harness。确认是否挂载：
dsh --profile desktop --dump-config | grep -A3 fs-auto-observe
package.json 标明运行环境为 Node >=20，当前发布版本为 0.1.0。
典型用法与验证¶
本插件无单独 CLI「用法示例」：启用后，智能体在仅通过 bash 探查、未调用 read 的情况下发起 edit-intent，应不再因 FS_NOT_OBSERVED 被拒（在策略已安装且会话归属正常的前提下）。
仓库提供零依赖契约测试，复刻 waterfall 与策略逻辑，可本地验证基线拒改、装插件后放行、已有记录零 stat、过期场景仍用旧版本作 CAS 等行为：
node test/contract.mjs
适用场景与注意¶
适合：已在 DSH 中启用 dsh-fs-observation-policy，且智能体常靠 bash 读文件、偶发「未读拒改」的 Harness 开发场景。
不适合或需谨慎：依赖「必须先 read 再 write」整文件覆盖安全的团队，不应在未理解风险时打开 writes: true。
DSH 生态是「一切皆插件」；SkillHub 插件目录 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-auto-observe 针对「bash 看过、read 未登记」与观察策略之间的缝隙，在保留版本守卫与 edit 逐字匹配的前提下，减少重复 read 与拒改来回。进一步了解可访问目录页 skillhub.cn/plugins/ruaibeite/dsh-auto-observe 与源码 github.com/ruaibeite/dsh-auto-observe。
