前言¶

在 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。