前言¶

在 DSH（DeepSeek Harness）裏跑 Agent 時，找文件、搜調用點、改代碼往往各自調用 ls、cat、sed 或宿主內置工具，缺少統一的檢索後端，也缺少帶快照、臺賬和回滾的編輯路徑。倉庫沒有 Git 時，一旦改錯更難恢復。dsh-forge 是社區維護者 Asaiuta 發佈的工作流類插件，把 fff 的 Rust 檢索、Tree-sitter 符號解析和一套容錯編輯引擎接到 DSH 工具面，讓檢索與「施工」走同一套可治理的工具，而不是零散腳本。

這是什麼¶

dsh-forge 面向 DSH >=0.2.0-rc.2：全文與模糊檢索（fff 預編譯動態庫）、11 種語言的 AST 符號與 Trace、以及帶臺賬、快照、回滾的編輯與驗證。運行時不需要本機安裝 cargo / rustc；符號解析走 WASM，可選 Rust sidecar（rust_indexer/）加速掃描與 Trace。

• 維護者：Asaiuta
• 版本狀態：v0.1.0，尚未發佈到 npm，需按源碼安裝
• 許可證：MIT
• 目錄頁：https://www.skillhub.cn/plugins/Asaiuta/dsh-forge
• 源碼：https://github.com/Asaiuta/dsh-forge

SkillHub 等社區目錄與 DeepSeek / 幻方無官方從屬關係；插件以當前 DSH 進程權限訪問工作區與 ~/.dsh/forge，安裝前請閱讀源碼與 LICENSE。

架構概覽¶

不啓用 sidecar 時全部工具仍可用，符號與 Trace 查詢會走 WASM。啓用 sidecar 需在 checkout 內用 Rust 1.88+ 執行 pnpm run build:indexer，產物位於 rust_indexer/bin。

核心功能¶

工具面：retrieval 與 full¶

默認只註冊 retrieval 三個工具；在 profile 的 patch 裏把 surface 設爲 full 後，額外註冊編輯、臺賬、文件操作與 Trace 等，共 10 個 canonical 工具（與 retrieval 合計爲 README 所述「retrieval 3 / full 10」）。

只註冊新公開名，無運行時舊名 alias。內置 read / grep / glob 仍保留原 schema；forge 在分發層增強，例如 read 支持 file_path=<文件>#<符號> 只讀定義窗口。

AST 支持：JavaScript、TypeScript（含 TSX/MTS/CTS）、Python（含 PYI）、Rust、Go、C、C++、Java、C#、Lua。

數據與邊界（節選）¶

快照與批次在 ~/.dsh/forge/snapshots/，票據在 tickets/，驗證在 verification/；無 Git 也可回滾，整目錄可刪後由下次調用重建。單文件 AST 超過 2 MiB 會降級並提示改用 ff_grep。ff_find 在 Everything 索引命中時可返回帶尾部 / 的目錄；走 fff 模糊回退時只返回文件。

安裝與啓用¶

前置要求¶

• Node ^22.19 || >=24
• 已安裝 DSH，版本 >=0.2.0-rc.2 且 <0.3.0
• pnpm

插件未上 npm，需從 GitHub checkout 後 link 到 profile。

步驟¶

1. 克隆並安裝依賴（prepare 會構建 lib/）：

git clone https://github.com/Asaiuta/dsh-forge.git
cd dsh-forge
pnpm install

2. 編輯 ~/.dsh/profiles/desktop/package.json，在 dependencies 中 link 本地路徑：

{
  "dependencies": {
    "dsh-forge": "link:<dsh-forge 的本地絕對路徑>"
  }
}

3. 在同文件的 dsh.profile.bundles 中登記 bundle 名 dsh-forge：

{
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-forge"]
    }
  }
}

4. 安裝依賴並重啓 DSH：

pnpm -C ~/.dsh/profiles/desktop install

重啓後可在宿主中使用 /forge-status 查看當前生效狀態（含內置工具增強與交回內置的統計）。

啓用完整工具面¶

開箱默認 surface: retrieval。需要編輯與回滾時，在用戶 patch 中配置：

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: dsh-forge
  name: dsh-forge
  config:
    surface: full

也可在 設置 → DSH-Forge 或 插件 → dsh-forge → 配置 中切換同一 surface 控件；保存寫入當前 profile 的 cordis.patch.yml 並重載 bundle，無需重啓應用（修改插件源碼仍需 pnpm run build 後由宿主重載）。

常用環境變量（可選）¶

完整列表見倉庫 README「配置」一節。

典型用法¶

下面步驟假設已啓用 full surface，且 Agent 已掛載 forge 工具。

模糊找文件（拼寫不確定）：

• 使用 ff_find，路徑 glob 仍用內置 glob。

搜調用點或配置名：

• 不確定的文本或多關鍵字 OR 用 ff_grep；明確正則用內置 grep。

讀單個函數定義（不必整文件 read）：

• 內置 read，參數形如 file_path=src/store.ts#Store.save。

帶審計的修改：

• ff_edit 完成編輯；需要時用 ff_verify 單獨驗證（不新建批次）。
• 符號編輯參數包括 sourceSymbol、includeLeadingComment 等，詳見接口遷移文檔。

出錯或需要對比歷史：

• ff_history 查批次與 diff；ff_rollback 先預覽再按批次恢復（可用 latest:true 或 throughBatch）。

靜態依賴與影響：

• ff_trace；符號定義仍用 ff_symbols 或 read#Symbol，不要給 trace 傳 symbol:。

安裝 dsh-better-sidebar 時，側欄「臺賬」與 ff_history 同源數據；HTTP 路由包括 GET /forge-ledger、/forge-config、/forge-projects（headless profile 無 webServer 時沒有設置頁，主插件仍加載）。

適用場景與注意¶

適合：希望在 DSH 裏統一檢索後端、用符號級 read/edit、並在無 Git 倉庫仍保留快照與回滾的 Agent 工作流；Windows 上需要 Everything 加速文件名檢索時可配置 FORGE_GLOBAL_INDEX。

注意：

• 插件以 DSH 進程權限讀寫工作區與 ~/.dsh/forge，安裝前審查源碼與 MIT 許可證。
• M0/M1 實現已在當前源碼中，README 寫明真實 DSH 集成驗收仍依賴具備宿主模塊的環境；M2 及之後在路線圖中。
• grep 增強不走內容索引，是爲保持 BOM、二進制與正則語義與內置一致；/forge-status 可覈對 Rust 搜索是否接管。
• 社區目錄星標與 npm 發佈狀態以倉庫爲準；當前爲源碼 link 安裝，無 dsh plugin add 一類一鍵命令出現在官方 README 中。

結尾¶

dsh-forge 把 fff 檢索、Tree-sitter 符號和帶臺賬的編輯收進 DSH 工具面，默認輕量 retrieval，按需切到 full 做 Trace、驗證與回滾。若要跟進接口變更與路線圖，以 GitHub 倉庫 README 與 docs/ 爲準。

• 目錄頁：https://www.skillhub.cn/plugins/Asaiuta/dsh-forge
• 源碼：https://github.com/Asaiuta/dsh-forge