前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，常见流程是：列目录、搜关键词、读全文、改完再读一遍确认。同一份源码被反复送进上下文，token 消耗快，步骤也重复。系统自带的读文件工具每次调用都是「新鲜」的，不会记住上一轮已经交付过的正文。
下面介绍社区插件 dsh-file-state-cache（维护者 Zzzk187）。它在硬盘上缓存文件状态与影子副本，让 explore 替代「ls + grep + 盲目 read」，让第二次 read 在内容未变时只回一行摘要，让 edit 直接返回 diff 和精确行号，而不必再全文重读确认。分类上属于 DSH 插件目录中的「记忆」类；状态跨工具调用、跨轮次、跨进程重启仍有效，这是纯上下文方案做不到的。
这是什么¶
dsh-file-state-cache 同时是 DSH 插件和 Cordis 技能。装好后，技能列表里会出现 file-state-cache（package 名 dsh-file-state-cache，当前 npm 版本 1.0.9，MIT 许可）。核心 CLI 在包内 scripts/fstate（Python 实现，Python 3.8+，仅用标准库）；插件本体要求 Node.js >= 18。
一句话：同一件事会发生第二遍时，用这套工具省上下文；只做一次的一次性操作，仍宜用系统原生读文件工具。
核心功能¶
explore：一次定位，代替三轮摸索¶
不知道符号在哪时，用 explore "关键词" 在指定根目录下搜索，返回命中文件、定义行号、片段以及建议的下一步命令，意图是减少「先 ls 再 grep 再 read」的重复。
read：带 SHA-1 校验的缓存读¶
每次读之前先算磁盘上文件的 SHA-1，与缓存记录比对：
| 磁盘状态 | 行为 |
|---|---|
| 从未读过 | 返回正文（首次） |
| SHA-1 未变，且本会话已完整交付过正文 | 一行摘要，不再吐正文 |
| SHA-1 已变，且有影子副本 | 返回 diff + 变动行号 |
| SHA-1 已变，但无影子基线 | 明确说明无基线，降级为全文 |
默认一次最多输出 400 行；大文件会提示截断并给出续读方式，截断部分不算「读过」，避免用「内容未变」跳过未进入上下文的段落。摘要凭证仅在本会话内有效；换会话或上下文被压缩后，会重新给正文，避免「以为自己看过」的错觉。
支持 --mode full / range / changed，以及 --max-chars、--label 等开关。
edit / write：改完用 diff 当验证¶
edit 在匹配 --old / --new 后写回文件，输出 unified diff 和精确变动区间（不含 diff 上下文行）。不提供 --new 会直接报错，不会把「未指定」当成删除；要删内容需显式 --new ''。写回保持原 BOM、原编码、原换行风格。
write 支持整文件写入；--mkdir 可在父目录不存在时创建（默认报错以防路径打错）。
digest / state / diff / reset / hot¶
- digest 目录/：多文件结构总览（例如函数签名一览）。
- state 文件：查看该文件的缓存版本、阅读次数、是否过期等。
- diff 文件：查看上次完整 diff。
- reset 文件：清除单文件缓存；也可删除
~/.dsh/fstate-cache/全量重建。 - hot：查看反复读取的文件，便于自查占用。
存储与限制¶
每个文件一条 JSON 存在 ~/.dsh/fstate-cache/，并对 ≤2 MB 且真正读过的文件保留影子副本用于 diff（不依赖 git）。可通过环境变量 FSTATE_HOME 更换缓存根目录；找不到 Python 时可设 FSTATE_PYTHON。
按设计拒绝：二进制 / 含 NUL、超过 8 MB 的文本。编码探测支持 BOM 与 UTF-8 / GBK / Latin-1 等，且不会在无 BOM 文件上凭空添加 BOM。
在 DSH 0.2.1-rc.5 上验证通过；技能注册档位 rank 600（bundled）。若 ~/.dsh/dsh-skill/file-state-cache 存在本地副本，本地版优先。
安装与启用¶
官方安装命令（来自项目 README）：
dsh plugin --profile web add Zzzk187/dsh-file-state-cache
本地开发时可指向目录：
dsh plugin --profile web add /你的路径/dsh-file-state-cache
装完后用 dsh plugin --profile web list 确认插件在列表中；技能未出现时 README 建议重启一次 DSH。安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限运行，缓存会写入用户目录下的 ~/.dsh/fstate-cache/。
典型用法¶
包目录通常为：
~/.dsh/profiles/<profile>/node_modules/dsh-file-state-cache
（Windows 为 C:\Users\你\.dsh\profiles\<profile>\node_modules\dsh-file-state-cache。）
设置 CLI 路径并试跑：
F="<包目录>/scripts/fstate"
"$F" explore "handleRequest" --root .
"$F" read src/app.py
"$F" edit src/app.py --old 'return 1' --new 'return 2'
"$F" digest src/
read 指定行段：
"$F" read src/app.py --mode range --start 40 --end 90
edit 成功时输出类似（可直接作为改完验证，无需再 read 全文）：
# 已改 src/app.py → v2 19 行 区间 14..14
--- a/app.py
+++ b/app.py
@@ -11,7 +11,7 @@
- return {"ok": True, "uptime": 0}
+ return {"ok": True, "uptime": 42}
清缓存示例：
"$F" reset src/app.py
rm -rf ~/.dsh/fstate-cache
适用场景与注意¶
更适合：
- 同一文件或同一批目录会被多次 read / 改完多次确认；
- 需要先「找代码在哪」再精读，
explore+digest能压缩摸索步骤； - 希望 diff 和行号进入上下文，而不是每次改完再灌一遍全文。
不必强行使用：
- 已经知道确切行号 → 原生读文件工具更直接；
- 一次性脚本或单条命令 → 没有第二遍，缓存几乎无收益；
- README 也说明：「定位 → 读一段 → 改一处 → 只走一遍」的流程，用它可能更贵；反复碰同一内容时才明显省 token。
与原生读文件工具不冲突：插件不修改系统工具，只是多一种选择。外部编辑器若在背后改文件（格式化、保存钩子），下次 read 会按 SHA-1 变化处理；可用 state 核对版本。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-file-state-cache 把「读过什么、改过什么」落到磁盘，用 explore、read、edit、digest 等命令减少 Agent 在 ls、grep、全文重读上的重复劳动。需要细节、排错表与 FAQ 时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/Zzzk187/dsh-file-state-cache
- GitHub：https://github.com/Zzzk187/dsh-file-state-cache
