前言¶
在 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
