前言¶
DeepSeek Harness（DSH）在编辑文件前会要求 Agent 先建立「已读」观察：未受信的内容不能直接改。实际工作流里，Agent 往往先用 CodeGraph、MCP 或 Shell 里的 cat/head 看源码，再调用原生 read 才能编辑——同一份文件读两遍，既费 token，也打断节奏。下面介绍社区插件 dsh-fs-observation-bridge（维护者 iBobbyTS）：它不替换 DSH 的编辑与版本检查，只把外部读码工具的输出校验通过后，登记到 DSH 原生的 fs/observed 机制里，从而在合规前提下减少重复的 read。
这是什么¶
dsh-fs-observation-bridge 是一条「读码 → 观察 → 可编辑」的桥接层：将 MCP、CLI、保守的 Bash / PowerShell shell-read，以及 DSH 原生工具等通道上的源码读取证据，接入 DSH 原生文件观察策略。插件当前版本为 0.3.0（MIT 许可证），在 SkillHub 目录中归类为工作流。目录页：dsh-fs-observation-bridge；源码：GitHub。
核心功能¶
多种读取来源¶
内置 Source 覆盖：
- CodeGraph CLI
- CodeGraph MCP（
dsh-plugin-codegraph） - POSIX 上的 shell-read（Bash 白名单语法）
- Windows 上 powershell-read（
pwsh上的Get-Content等保守语法）
各 Source 通过 Transport → Source → Observation Core 三层协作：Transport 归一化输入，Source 识别工具调用并提取证据，Observation Core 校验后调用 fs/observed 注册观察。无法验证的读取不会获得编辑授权。
读取验证与原生安全¶
插件只做「受信观察」的登记，保留 DSH 原有的文件版本检查、并发保护与编辑行为。并发工具按完成顺序建立观察；若同一文件较旧的观察最后到达，后续编辑会以 FS_STALE_VERSION 拒绝（fail-closed），避免编辑模型未见过的内容。
fs/observed 与原生 read offset/limit 一样，是整文件级、带版本的观察：受信的局部视图在版本未变时，也允许后续全文件编辑。
Shell 读文件（典型白名单）¶
在 Linux/macOS 上，foreground bash 且 exit 0、stderr 为空等条件满足时，下列形式可被识别（节选）：
cat src/app.ts
head -n 80 src/app.ts
sed -n '40,120p' src/app.ts
cat app.ts | head -n 80
Windows 上则针对 foreground pwsh 解析 Get-Content（及 gc/cat/type 别名）等固定形式；语法与 Bash 分开，细节以 README 中的表格为准。
安装与启用¶
安装方式为 bundle，通过 DSH 插件管理器的 install_bundle，target 指向本包在磁盘上的绝对路径（不是凭仓库名拼一条 dsh plugin add）。bundle 会通过 dsh.bundle.patch 插入 fs-observation-bridge 配置行，并保留原生 fs-observation-policy 启用。
运行环境要求（见 package.json）：Node ^22.19.0 || >=24.0.0。
可选配置写在 profile patch 的插件 config 中：
- id: fs-observation-bridge
name: 'dsh-fs-observation-bridge'
config:
maxSourceBytes: 8388608
maxEvidenceFiles: 200
disabledSources: []
| 字段 | 默认值 | 含义 |
|---|---|---|
maxSourceBytes |
8388608（8 MiB） |
校验证据时单文件大小上限；更大文件跳过校验（不授权） |
maxEvidenceFiles |
200 |
单次工具结果最多校验的文件数 |
disabledSources |
[] |
禁用内置 source，如 codegraph、shell-read、powershell-read |
典型用法¶
- 在 DSH 中按上文完成 bundle 安装，确认
fs-observation-policy仍启用。 - Agent 用已支持的读码方式查看目标文件，例如 CodeGraph MCP/CLI，或在 bash 中执行白名单内的
cat/sed命令。 - 插件校验 stdout 与当前文件内容一致（仅允许 CRLF/LF 归一化）后，登记观察。
- 在同一文件版本下，Agent 可直接走 DSH 原生编辑路径，无需再为「已看过」的内容重复调用
read。
若你同时使用 CodeGraph CLI 与 shell-read，二者在 Transport 层互斥：一条 shell 命令只会被其中一个归一化处理。
适用场景与注意¶
适合谁：在 DSH 里跑 Coding Agent、且习惯用 CodeGraph 或受控 Shell 读文件，又希望遵守「先读再改」策略的团队或个人。
务必注意：
- 插件与当前 dsh 进程同权限运行；安装前应阅读源码与 MIT 许可证，确认信任维护者与 bundle 内容。
- shell-read 只认白名单语法：重定向、变量替换、复杂管道、
git show、docker exec … cat等默认不会产生观察。 - SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系；星标与热度以各站点展示为准，安装决策仍以仓库 README 为准。
结尾¶
dsh-fs-observation-bridge 的价值在于：连接外部读码工具与 DSH 原生观察，而不是另起一套编辑规则。需要细节（PowerShell 方言、授权条件、如何贡献新 Source）时，请直接查阅仓库 README.zh.md 与 SkillHub 目录页。
