dsh-file-mention

English: README.md

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

外掛插入的是輕量路徑參照，不會把檔案內容當附件或直接注入 context。agent step 開始前，Host 會重新驗證每一個路徑並加入只含路徑與類型的 <workspace-reference> 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 範例：

<workspace-reference path="src/main.js" kind="file" />

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