前言¶

在 DSH 裏讓 Agent 寫 Rust，最常見的失敗不是模型不會寫語法，而是它在 API 上憑記憶發揮：版本對不上、trait 漏了、宏展開後的做法和實際編譯結果不一致，報錯修一輪又引入新問題。Cargo by Harness（下稱 CbH）針對的就是這一點——它不做新的 Agent 框架，而是給 DSH 加一個 session mode，讓代理優先從本機 Cargo 緩存裏取真實的 crate 源碼和簽名，而不是靠記憶回答。下面介紹這個插件的能力和用法。

這是什麼¶

CbH 是 Lavaver 維護的開源 DSH 插件，分類爲工作流，目錄頁收錄於 SkillHub，許可證 MIT，package.json 中版本爲 1.9.3。安裝後啓動新會話時會在 mode 選擇器裏多出一項 Cargo by Harness；選中之後，Agent 的核心行爲是「本地緩存優先檢索」，並且配套了純 JS 的 macro_rules! 展開、編譯反饋循環，以及面向新手的引導流程。另外，發佈和安裝類命令在工具層被物理隔離，不會出現在可執行命令裏。

它解決的是三個具體問題：API 查不到時猜、宏展開後看不清、編譯錯誤只靠日誌而非結構化診斷去修。

核心能力¶

1. 本地緩存優先檢索。優先讀 $CARGO_HOME/registry/ 下的源碼和 rustdoc JSON，只有前面幾步都沒命中時才做一次最小化遠程補全。
2. 純 JS 的 macro_rules! 展開。不依賴外部二進制，不觸發 Rust 構建；解析頂層 use 別名，從本地緩存的 crate 解析定義。
3. 編譯反饋循環。check → fix → verify；報錯時按確定性方式彙總錯誤碼、file:line:col，交給配套的 rust-compile-fix skill 處理。
4. 新手引導。內置 rust-beginner-workflow、rust-crate-choice、rust-daily-loop 等 skill，把工作節奏固定下來。
5. 工具與命令分離。模型通過 cargo_search / cargo_read 做「該查什麼」的判斷，/cargo-* 斜槓命令只做確定性的、可緩存的檢查類工作。

安裝與啓用¶

先確認本機已裝 Rust。沒有的話按 rust-lang.org/tools/install 的說明裝完，再裝插件：

dsh plugin --profile <profile> add https://github.com/Lavaver/Cargo-by-Harness

裝完新建一個 DSH 會話，在 mode 選擇器裏選中 Cargo by Harness。如果改動 bundle 的子行（例如新增 skill），需要重啓 DSH 進程，preset 組合纔會重新掛載。

典型用法¶

進入 CbH 模式後用自然語言描述需求，插件按「本地緩存 → 最小實現 → 編譯驗證 → 修復」的節奏走。一個 README 裏的示例：

I'm a Rust beginner. Help me write a hello world using axum that returns JSON, and make sure it runs.

Agent 會先 cargo_search 查本地 axum 的版本和接口，再寫代碼，然後跑 cargo check 驗證，遇到錯誤自動套用 rust-compile-fix。README 還記錄了兩個真實驗證記錄：一次 cargo check --offline 失敗正確報出 error [E0308] src/main.rs:2:22 mismatched types；/cargo-doctor 正確識別出 cargo 1.99.1 / rustc 1.99.1 / edition 2021。倉庫 tools/ 目錄另提供了一組 smoke test 腳本，覆蓋 registry、命令註冊、工具註冊、宏展開、skill 註冊、cargo runner 白名單、遠程補全等路徑。

檢索與驗證的順序¶

檢索順序是固定的，不允許跳過：

1. $CARGO_HOME/registry/src/<index>/<crate>-<version>/，Cargo 解開的源碼。
2. 工作區的精確版本：先看 Cargo.lock，再看 manifest 的版本要求。
3. 緩存裏的 rustdoc JSON 作爲結構化層；遇到聲明、where 子句、feature gated 代碼時，仍以 registry 源碼爲準。
4. 前三步都沒命中時，做一次最小化的遠程補全（crates.io 的 .crate 或 docs.rs 的 rustdoc JSON），落盤到 $CARGO_HOME/cbh-cache/ 後再返回。

命令面¶

插件註冊了 6 個確定性斜槓命令，handler 直接回應，不產生新的模型消息：

/cargo-doctor      診斷 Rust 工具鏈、workspace、lockfile、target
/cargo-check [--all-targets] [--clippy] [--offline] [--timeout <s>]
/cargo-cache [status|list|prune|verify]
/cargo-fetch <crate>[@version] [--from crates.io|docs.rs|local]
/cargo-workspace [deps|features|target]
/cargo-item <crate::path> [--source]

模型工具側共四個：cargo_search 在本地緩存裏搜 crate、symbol、trait impl 或代碼模式，最多返回 20 條摘要；cargo_read 按精確 ID 或完整 Rust 路徑讀簽名、文檔、源碼、實現或緩存狀態；cargo 執行 build/check/test/run/fmt/clippy/add/tree 等日常工具鏈命令並返回結構化診斷，不暴露 publish、install、yank；cargo_expand 做上文提到的宏展開。

已知邊界¶

三條宏相關的限制需要先知道：

1. 不展開過程宏。#[derive]、屬性宏、函數式 proc-macro 原樣返回，因爲純靜態分析無法覆蓋需要編譯執行的宏。應對辦法是回到 cargo_read 讀宏 crate 源碼。
2. 不解析 glob 導入。use tokio::*; 不會建立宏別名映射，靜態文本無法判定實際導入了哪些宏；遇到無法解析的裸調用時 cargo_expand 會報未解析，可改用完整路徑。
3. 不檢查宏 hygiene。展開結果裏保留 /* <- [original call] */ 註釋以便回溯原始調用位置。

另外，修改 preset 的子行後需要重啓 DSH，這是 DSH preset 機制本身的行爲。

適用場景與注意¶

適合兩類人：一是正在用 DSH 寫 Rust、受夠了 API 幻覺的開發者；二是剛入門 Rust、想讓代理按穩定節奏從建項到驗證的人。

需要注意三點。插件以當前 DSH 進程的權限運行，能讀到你 $CARGO_HOME 下的源碼與緩存，安裝前建議先檢查源碼和許可證，MIT 只是聲明，不代表可以跳過審計。/cargo-fetch 會在前幾步失敗時做一次遠程補全，寫回 $CARGO_HOME/cbh-cache/，在嚴格離線或強管控環境裏要提前確認這條鏈路是否符合策略。三項宏限制決定了它更適合 macro_rules! 風格的項目，大量依賴 derive 和 proc-macro 的場景仍需自己覈對展開結果。

結尾¶

CbH 的價值不在於增加了多少能力，而是給 Rust 工作流加了一條確定的檢索與驗證順序：先從本地緩存拿真實接口，再編譯驗證，再按結構化診斷修復。目錄頁與源碼見 SkillHub（分類：工作流）和 GitHub 倉庫 Lavaver/Cargo-by-Harness。