Preface¶

In DSH, getting an Agent to write Rust, the most common failure isn’t that the model cannot write syntax, but that it improvises based on memory on APIs: version mismatches, missing traits, inconsistencies between behavior after macro expansion and actual compilation results, fixing errors in one round only to introduce new problems. Cargo by Harness (hereinafter referred to as CbH) addresses this point — it doesn’t create a new Agent framework, but adds a session mode to DSH, allowing the agent to prioritize fetching real crate source code and signatures from the local Cargo cache rather than answering based on memory. Below is an introduction to the capabilities and usage of this plugin.

What is this¶

CbH is an open-source DSH plugin maintained by Lavaver, categorized as a workflow, listed in the SkillHub catalog, licensed MIT, with version 1.9.3 in package.json. After installation, when starting a new session, an additional item “Cargo by Harness” appears in the mode selector. Once selected, the Agent’s core behavior is “Local Cache First Retrieval,” accompanied by pure JS macro_rules! expansion, a compilation feedback loop, and a guidance workflow for beginners. Additionally, publish and install-type commands are physically isolated at the tool layer and will not appear in executable commands.

It solves three specific problems: guessing when the API cannot be found, not being able to see clearly after macro expansion, and fixing compilation errors relying only on logs instead of structured diagnostics.

Core Capabilities¶

1. Local Cache First Retrieval. Prioritize reading source code and rustdoc JSON under $CARGO_HOME/registry/, performing a minimal remote completion only if the previous steps do not match.
2. Pure JS macro_rules! Expansion. Does not depend on external binaries, does not trigger Rust builds; parses top-level use aliases and resolves definitions from locally cached crates.
3. Compilation Feedback Loop. check → fix → verify; when an error occurs, errors and file:line:col are aggregated deterministically and handed over to the accompanying rust-compile-fix skill.
4. Beginner Guidance. Built-in skills like rust-beginner-workflow, rust-crate-choice, and rust-daily-loop fix the workflow rhythm.
5. Tool and Command Separation. The model uses cargo_search / cargo_read to determine “what to search,” while /cargo-* slash commands handle only deterministic, cacheable check-type work.

Installation and Enablement¶

First, confirm Rust is installed on your machine. If not, install it according to the instructions at rust-lang.org/tools/install, then install the plugin:

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

After installation, create a new DSH session and select “Cargo by Harness” in the mode selector. If you modify the sub-rows of the bundle (e.g., adding a new skill), you need to restart the DSH process for the preset combination to remount.

Typical Usage¶

After entering CbH mode, describe your requirements in natural language; the plugin follows the rhythm of “Local Cache → Minimal Implementation → Compilation Verification → Fix.” An example from the README:

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

The Agent will first cargo_search to check the local axum version and interfaces, then write code, run cargo check for verification, and automatically apply rust-compile-fix when encountering errors. The README also records two real verification records: one cargo check --offline failure correctly reported error [E0308] src/main.rs:2:22 mismatched types; /cargo-doctor correctly identified cargo 1.99.1 / rustc 1.99.1 / edition 2021. The repository’s tools/ directory also provides a set of smoke test scripts covering paths such as registry, command registration, tool registration, macro expansion, skill registration, cargo runner whitelist, and remote completion.

Retrieval and Verification Order¶

The retrieval order is fixed and cannot be skipped:

1. $CARGO_HOME/registry/src/<index>/<crate>-<version>/, source code unpacked by Cargo.
2. Precise version of the workspace: first check Cargo.lock, then the version requirements in the manifest.
3. rustdoc JSON in the cache as the structured layer; when encountering declarations, where clauses, or feature-gated code, the registry source code remains the source of truth.
4. If none of the previous three steps match, perform a minimal remote completion (crates.io .crate or docs.rs rustdoc JSON), write it to $CARGO_HOME/cbh-cache/ before returning.

Command Surface¶

The plugin registers 6 deterministic slash commands, handlers respond directly without generating new model messages:

/cargo-doctor      Diagnose Rust toolchain, 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]

There are four model tool sides: cargo_search searches for crates, symbols, trait impls, or code patterns in the local cache, returning up to 20 summaries; cargo_read reads signatures, docs, source code, implementations, or cache status based on exact ID or complete Rust path; cargo executes daily toolchain commands like build/check/test/run/fmt/clippy/add/tree and returns structured diagnostics, without exposing publish, install, or yank; cargo_expand performs the macro expansion mentioned above.

Known Limitations¶

Three macro-related limitations need to be known first:

1. Does not expand procedural macros. #[derive], attribute macros, and functional proc-macros are returned as-is because pure static analysis cannot cover macros that require compilation and execution. The workaround is to go back to cargo_read to read the macro crate source code.
2. Does not parse glob imports. use tokio::*; does not establish macro alias mappings, and static text cannot determine which macros are actually imported; when encountering an unresolved bare call, cargo_expand will report unresolved, and one can switch to using a full path.
3. Does not check macro hygiene. The /* <- [original call] */ comment is retained in the expansion result to facilitate backtracking to the original call location.

Additionally, after modifying preset sub-rows, DSH needs to be restarted; this is the behavior of the DSH preset mechanism itself.

Suitable Scenarios and Notes¶

Suitable for two types of people: developers who are currently writing Rust with DSH and are tired of API hallucinations; and those who have just started with Rust and want the agent to follow a stable rhythm from project creation to verification.

Three points need attention. The plugin runs with the permissions of the current DSH process and can read source code and cache under your $CARGO_HOME. It is recommended to check the source code and license before installation; MIT is just a declaration and does not mean auditing can be skipped. /cargo-fetch performs a remote completion when the previous steps fail and writes it back to $CARGO_HOME/cbh-cache/. In strictly offline or highly controlled environments, this path needs to be confirmed to comply with policies in advance. The three macro limitations determine that it is more suitable for macro_rules! style projects; scenarios that heavily rely on derive and proc-macros still require manually verifying the expansion results.

Conclusion¶

The value of CbH lies not in the amount of capability added, but in adding a deterministic retrieval and verification order to the Rust workflow: first getting the real interface from the local cache, then compiling and verifying, and finally fixing based on structured diagnostics. For the catalog page and source code, see SkillHub (Category: Workflow) and the GitHub repository Lavaver/Cargo-by-Harness.