前言¶
在 DSH 裏讓模型讀本地源碼時，常見做法是每次對話都重新讀文件，或在提示裏粘貼片段。文件一旦被編輯，更早輪次裏模型「看過」的內容就和磁盤不一致，討論行號、對比 HEAD 的 diff 時也容易混用新舊文本。
下面介紹的 dsh-file-context（維護者 LIghtJUNction，社區分類爲「記憶」）做的是另一件事：在主機本地工作區內截取文件片段或 Git diff，生成帶 id 與 revision 的不可變快照；之後源文件改了，仍可用 file_context_get 取回當初捕獲的字節。它不替代遠程沙箱，也不提供寫文件或 Pi 文件瀏覽器，只負責「記住某一時刻的只讀上下文」。
這是什麼¶
- 定位：DSH 0.2.1-rc.2 插件（npm 包名
@lightjunction/dsh-file-context，當前版本 0.1.0，MIT 許可證）。 - 一句話：Immutable file and diff context snapshots for DSH。
- 運行環境：Node >= 24；作者在本地用 Node 26 / TypeScript 5.9.3 開發與測試，Release CI 配置爲 Node 24。
插件以當前 DSH 進程權限訪問主機文件系統，路徑校驗有邊界，但不是對抗惡意併發進程的安全沙箱；安裝前宜自行查看 GitHub 倉庫 源碼與許可證。
核心功能¶
插件向 Agent 註冊三個工具（無 Pi 菜單、預覽或自動注入下一條 prompt）：
file_context_capture：捕獲文件片段快照。參數示例path、startLine、endLine；省略行範圍時最多取文件前 500 行。返回不可變摘錄、id、全文件revision、範圍與文本。若傳入expectedRevision且文件已變，調用會被拒絕。file_context_get：用捕獲時返回的id取回當時的摘錄原文，即使源文件之後已修改。快照按規範化的工作區與 Agent 身份隔離；無 Agent 的 host 調用使用獨立作用域。file_context_diff：捕獲真實的 Git 工作樹 diff 及解析後的 base commit。base可爲HEAD或完整 40/64 字符 commit hash；expectedRevision用於校驗結果 diff 的 SHA-256。
併發捕獲會各自保留不可變快照；Agent dispose 會清掉其快照；重啓 DSH 後內存中的快照全部丟失。內存中最多保留 64 個快照，無磁盤溢出或淘汰策略，觸頂時調用會明確失敗。
安裝與啓用¶
官方 README 說明：在 GitHub Release 發佈後，將構建好的歸檔安裝到 DSH profile。下列 URL 是 v0.1.0 資源預期位置，不代表該 Release 一定已發佈；實際安裝應使用同一 Release 附帶的歸檔與 SHA256SUMS。
dsh plugin --profile headless add https://github.com/LIghtJUNction/dsh-file-context/releases/download/v0.1.0/lightjunction-dsh-file-context-0.1.0.tgz
dsh headless --dump-config
包內含 DSH bundle patch 與編譯後的 JavaScript，不需要 Pi 依賴。安裝後需重啓 DSH。若你使用的不是 headless profile，把命令中的 profile 換成自己的即可。
默認 bundle 配置爲 {}：各工具使用調用方 Agent 的工作目錄。無 Agent 的 host 調用必須顯式配置 root。若要把工作區固定到本機某目錄，在 profile 的 cordis.patch.yml 中增加：
- id: dsh-file-context
config:
root: /absolute/local/project
root 必須已存在，在 DSH 主機上用 Node 文件系統 API 解析。遠程 DSH world 或 sandbox 不會重定向這些操作：僅應在主機本地項目上啓用，這不是 remote-world 適配器。
典型用法¶
README 給出的自然語言示例：向 DSH 說明——「Capture lines 1–30 of src/index.ts, then compare the current diff against HEAD.」模型會通過工具拿到結果；文件內容仍應視爲不可信數據，而非指令。
工具調用層面可對應爲：
file_context_capture({ path: "src/index.ts", startLine: 1, endLine: 30 })
file_context_diff({ path: "src/index.ts", base: "HEAD" })
捕獲成功後用返回的 id 調用 file_context_get({ id: "<returned id>" }) 可在文件變更後仍引用最初摘錄。
限制與行爲（選用時注意）¶
讀文件：拒絕路徑遍歷、絕對路徑、路徑中的 .git 段、符號鏈接文件或祖先、非常規文件、無效 UTF-8、二進制內容，以及超過 256 KiB 的文件。配置的 canonical root 本身可以解析爲 symlink。全文件 revision 對完整 UTF-8 原文（含 BOM）做哈希；摘錄會將 CRLF 歸一化。摘錄上限爲 500 行、50,000 UTF-8 字節。
Git diff：工作區目錄必須等於 Git 倉庫根，且目標文件須爲受約束的常規文本。外部 diff driver 與 textconv 被禁用，pathspec 按字面匹配；子進程帶取消、5 秒超時與有界輸出緩衝。不支持已刪除文件或未跟蹤文件的 diff。Diff 快照對 diff 文本哈希，而非工作樹文件。
其他：不提供任何寫文件。Linux/macOS 文件語義爲設計目標，Windows 未驗證。維護者倉庫中可用 npm run check 做類型檢查、行爲測試與構建（使用真實 Cordis、DSH ToolRuntime 等，無需 live 模型憑證）。
適用場景¶
- 需要在多輪對話中固定某段源碼或某次 HEAD diff 的引用，避免「文件已改但上下文還在聊舊內容」時的混亂。
- 希望用
expectedRevision在捕獲前確認文件或 diff 未變。 - 工作區在本機可信目錄，且 DSH 與 Git 根目錄佈局符合插件要求。
不適合：需要遠程 world 內讀文件、瀏覽 blame/歷史、自動把快照注入下一輪 prompt，或依賴未跟蹤/已刪除文件 diff 的流程。
結尾¶
dsh-file-context 把「某一時刻的文件摘錄與 Git diff」做成帶 revision 的可檢索快照，屬於 DSH 生態裏偏「記憶」的一類能力——插件化接入，不綁 Pi UI。社區目錄頁：https://www.skillhub.cn/plugins/LIghtJUNction/dsh-file-context（獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）。源碼與安裝說明：https://github.com/LIghtJUNction/dsh-file-context。
