tipoLi5890/dsh-file-mention

dsh-file-mention

Awesome DSH Plugin

English: README.md

提供 DeepSeek Harness (DSH)
Web composer 使用的安全、session-scoped @ 檔案／資料夾提及與檔案拖放。

外掛插入的是輕量路徑參照，不會把檔案內容當附件或直接注入 context。agent step 開始前，Host
會重新驗證每一個路徑並加入只含路徑與類型的  marker；agent 再依自己的
工具與任務需要決定是否、如何讀取。

功能

- 檔案與資料夾 — 只打 @ 就開啟 workspace 清單，繼續輸入 basename 或 path 片段過濾。
- Git-aware index — tracked + untracked/non-ignored；已刪除 tracked path 排除。非 Git workspace
使用有深度／數量限制的 filesystem walk。
- 可控索引 — .aiinclude 可納入 Git 忽略的必要檔案，巢狀規則採 last-match-wins；
dirty/mtime 讓變更與最近檔案優先，indexVersion 與 workspace watcher 精準失效 cache。
- 快速輸入 — 每個 session 只抓一份 index，具備 warm()、single-flight、30 秒
stale-while-revalidate、Client 本地排序與可選的最近路徑優先。
- 不歧義引用 — pick 保留完整相對路徑；空白路徑使用 @"quoted path"。
- 送出前驗證 — agent/pre-step 驗證 workspace confinement、symlink realpath、存在性與
file/directory 類型，不讀內容。
- 鍵盤完成 — 方向鍵 + Enter 或 Tab，Tab 走 input-trigger controller。
- 受控拖放 — 串流至 temp file 後原子落盤，具單檔/session/global quota、retention、進度與取消；
純圖片仍交給內建圖片列。
- 貼上即上傳 — 貼上非圖片檔案時走同一受控上傳管線，不再落入內建圖片
intake 而失敗；純圖片貼上仍交給內建圖片列。
- 保留游標插入 — 上傳完成的 @ 路徑透過凍結契約 slash/input-insert-text
（draftRev CAS 加游標重映射）插入至上傳前記錄的游標位置，失敗時退回附加到結尾。
- Reference Tray — composer 下方以檔案／資料夾卡片呈現引用，可複製、reveal、逐筆移除或
一次清空，保留周圍草稿文字。
- Control Center — 以總覽、索引、上傳、輸出四個分頁取代平面設定表，提供即時 index
診斷、儲存用量、ignore presets、重建索引與清理過期上傳。
- 候選資訊 — 可顯示 changed-file status；瀏覽器本地 recent-path history 讓常用路徑優先，
不會把使用紀錄送到 Host。
- 官方 UI slots — Reference Tray、Control Center 與輸出 companion 都使用支援的 DSH
integration points。
- 可選輸出 companion — 只讓 Host 驗證通過的 assistant inline-code path 顯示開啟／reveal 操作，
不使用 MutationObserver。
- 零建置 — 手寫 Host ESM 與 lazy-CJS browser bundle；React 由 DSH Client runtime 提供。

畫面範例

瀏覽工作區檔案與資料夾

篩選並選取檔案

檔案提及設定頁

將本機檔案拖入輸入區

從 Reference Tray 使用受控上傳

安裝

需要相容的 DSH Web profile，並具備 client input-trigger、runtime 與 locale services。

dsh plugin --profile web add github:tipoLi5890/dsh-file-mention

本機開發：

dsh plugin --profile web add link:/絕對路徑/dsh-file-mention
dsh --profile web --dump-config

安裝／更新後請重啟 DSH Web。

使用方式

| 操作 | 結果 |
|---|---|
| @ | 開啟淺層優先排序的 workspace 檔案／資料夾清單 |
| @readme | 找到 README.md 等 basename 命中 |
| @src/ma | 依完整相對路徑搜尋 |
| 選 src/main.js | 插入 @src/main.js  |
| 選 docs/file with spaces.md | 插入 @"docs/file with spaces.md"  |
| 選 docs/ | 插入 @docs/  |
| 方向鍵 + Tab | 接受目前反白的 files candidate |
| 拖入非圖片檔 | 複製至 managed uploads 並於游標處插入其路徑 |
| 貼上非圖片檔 | 以相同方式上傳並於游標處插入其路徑 |

基於安全邊界，picker 不再提供 @/、@~/、@../ 的 workspace 外瀏覽；Host index root
永遠由指定 session 決定。

運作原理

Host

POST /api/file-mention/index 接受 { "sessionId": "..." }。Host 從 session state
取得 cwd，建立／快取 Git 或 fallback index，只回相對檔案／資料夾 path。

POST /api/file-mention/upload?sessionId=&name= 接受單一 raw file body。Host 依設定檢查單檔、
session 與 global quota，串流至同檔案系統 temp file，再以 no-clobber hard-link 原子完成，回 managed absolute path。

POST /api/file-mention/settings 讀寫 plugin-owned JSON 設定；POST /api/file-mention/status
提供不含路徑明細的 index/storage 統計，POST /api/file-mention/maintenance 可重建指定 session
的 index 或清除超過保留期的 upload；POST /api/file-mention/path-action
只對目前 workspace 或 managed upload 執行 check／reveal，系統程序以 execFile argument array 啟動。

在 agent/pre-step，只掃 direct user mentions。relative path 必須仍位於 session.cwd；
absolute path 只有在 managed upload root 中才會被標記。marker 範例：

Browser

Browser 註冊 @/files input source；每個 session 抓一次完整但有界的 index，每次按鍵只在
本地排序，pick 回傳純文字 insertion outcome。dirty、mtime 與可選的 browser-local recent
counts 會在相關度同分時優先。
connection reset 會清掉全部 index state。

Capture-phase drag handler 接管含非圖片檔的 drag，使用 XHR streaming body 顯示進度並允許取消；
插入則走 conversation.input.dock 提供的 inputActions.setDraft，不再修改 textarea DOM。

限制

| 限制 | 數值 |
|---|---:|
| Index entries | 20,000 |
| 非 Git traversal depth | 32 |
| Client menu rows | 40 |
| Host/Client index freshness | 30 秒 |
| 單一拖入檔案 | 50 MiB |
| .aiinclude files | 50 |
| JSON request body | 256 KiB |
| Session upload quota | 250 MiB（可設定） |
| Global upload quota | 2 GiB（可設定） |
| Upload retention | 7 天（可設定） |

Git workspace 遵守 .gitignore。非 Git fallback 跳過 hidden entries、symlink、VCS metadata、
dependencies、cache 與常見 build outputs。

開發與文件

npm run check

不需安裝 dependency，也沒有 build step。詳細文件：

- 架構
- 安全模型
- Host API 與設定參考
- 開發與發布流程
- Changelog

授權

MIT © 2026 dsh-file-mention contributors