dsh-artifact-index：DeepSeek Harness 側邊欄的缺失後端

前置要求¶

此插件僅提供後端能力，需要配合前端組件使用。

DSH 版本：需安裝 DSH >= 0.1.5-rc.1。
依賴組件：必須先安裝 dsh-better-sidebar 和 dsh-artifacts。本插件不替代它們，而是補全數據鏈路。

核心功能¶

dsh-artifact-index 是 dsh-artifacts 側邊欄標籤頁所需的缺失後端。它運行在 DSH 的 web server 上，負責提供 artifact 的索引 JSON 和文件字節流。

服務索引：通過 GET /report/ 返回 artifact 列表 JSON。
服務文件：通過 GET /report/<name> 返回指定 artifact 的二進制內容。
零依賴：無第三方運行時依賴，無網絡外聯，無遙測。
可配置：支持配置根目錄、最大條目數、單文件大小上限及內容安全策略（CSP）。
安全防護：內置路徑安全校驗，僅允許 loopback 訪問，禁止路徑穿越。

安裝與啓用¶

使用官方安裝命令添加插件。

dsh plugin --profile desktop add dsh-artifact-index

安裝完成後，必須重啓 DSH Desktop。插件與工具列表是會話創建時的快照，重啓後纔會加載新插件。

驗證安裝¶

重啓後，檢查日誌目錄（Windows 下通常爲 %APPDATA%\DSH Desktop\logs\dsh-<日期>.log）中是否存在激活信息：

[dsh-artifact-index] artifact root = <artifact 目錄> (maxItems=500, ...)

若日誌中未出現此行，請檢查 dsh.profile.bundles 中是否包含 dsh-artifact-index，或查看是否有 failed to apply loader entry 的錯誤。

由於 DSH 的 web server 會拒絕非瀏覽器發起的請求，無法使用 curl 驗證路由。如需對真實目錄做端到端檢查，可運行倉庫提供的腳本：

node scripts/smoke.mjs <artifact 目錄>

配置項¶

配置寫入 profile 的 cordis.patch.yml 中掛載行的 config 下，或通過環境變量覆蓋。優先級爲：config > 環境變量 > 默認值。

- id: dsh-artifact-index
  name: 'dsh-artifact-index'
  config:
    root: <artifact 目錄>
    maxItems: 500
    maxFileBytes: 26214400
    csp: sandbox

配置項	默認值	說明
`root`	`$DSH_HOME/artifacts`	要索引的目錄。不遞歸，僅掃描當前層級。
`maxItems`	`500`	返回條目數上限，超過部分丟棄並記錄警告。
`maxFileBytes`	`26214400` (25 MB)	單文件大小上限，超過返回 `413` 錯誤。
`csp`	`sandbox`	內容安全策略。`sandbox` 禁止腳本/表單；`sandbox-scripts` 允許腳本；`none` 不下發。
`trustedHosts`	`[]`	額外允許的 Host，僅在 DSH 不跑在 loopback 上時使用。

環境變量 DSH_ARTIFACT_INDEX_ROOT 可用於覆蓋 root 配置。

接口契約¶

`GET /report/` (索引列表)¶

返回 JSON 格式的索引數據。items 按 mtime 降序排列，同刻按 name 升序。

{
  "count": 2,
  "items": [
    {
      "name": "report.html",
      "url": "/report/report.html",
      "ext": "html",
      "size": 5120,
      "mtime": 1757000000
    },
    {
      "name": "data.json",
      "url": "/report/data.json",
      "ext": "json",
      "size": 2048,
      "mtime": 1756990000
    }
  ]
}

注意：
* url 字段會被上游直接用作 iframe 的 src，因此是根相對且已編碼。
* mtime 單位爲秒。
* 響應中不包含 mine 字段（v0.1 的設計選擇，詳見下文）。
* 若無法讀取目錄，返回 200 狀態碼及 { count: 0, items: [], error: "..." }。

`GET /report/<name>` (文件字節)¶

返回指定文件的二進制流。Content-Type 根據擴展名自動映射。對於 HTML/SVG/XML，會附加 CSP 頭。僅允許單段文件名，不接受子路徑。

設計與限制¶

關於 `mine` 字段¶

mine 是 dsh-artifacts 客戶端約定的字段，用於標記 artifact 是否屬於當前會話。本插件 v0.1 版本故意不返回此字段。原因是在 v0.1 中，準確還原會話歸屬過於複雜，且容易產生誤判。當前版本提供的是一份誠實的扁平列表，而非可能撒謊的歸屬信息。

安全特性¶

路徑安全：對請求路徑進行雙重校驗（字符串校驗 + realpath），防止符號鏈接指向外部目錄或路徑穿越。
訪問控制：僅允許 loopback 訪問。Sec-Fetch-Site: cross-site 請求會被直接拒絕。
操作限制：僅支持 GET/HEAD，無寫入、刪除或認證功能。

總結¶

dsh-artifact-index 解決了 dsh-artifacts 側邊欄因缺少後端而導致顯示 “Could not read the artifact index” 的問題。它是一個輕量級的中間件，用於將本地文件系統映射爲 DSH 的 HTTP 服務，適合需要在側邊欄查看本地生成的報告或文檔的開發者。

倉庫：https://github.com/Huuuuung/dsh-artifact-index
許可證：MIT