1. 项目概述：这不是一次简单的代码阅读，而是一次对Agent架构哲学的现场解剖
我把 DeepSeek 开源的 Agent 框架拆了一遍：原来"插件化"可以做到这种程度——这句话不是标题党，是我把DeepSeek Harness的源码从Cargo.toml一行行读到cordis插件调度器核心逻辑后，合上终端时的真实反应。过去三年我做过 7 个不同技术栈的 Agent 项目，从基于 LangChain 的 Python 轻量级工作流，到用 Rust 重写的金融风控决策引擎，也踩过“插件只是 config.yaml 里加个 name”的坑。但 DeepSeek Harness 让我第一次看到：插件不是功能的附属品，而是 Agent 的第一公民；不是开发者写完主逻辑再“塞进去”的补丁，而是整个系统设计的起点和终点。它用一套极简的契约（Contract），把 LLM、工具、状态、安全边界、执行上下文全部解耦，又用Cordis这个轻量但精密的插件总线，让它们在运行时像乐高一样即插即用、热替换、可审计、可限流。你不需要懂 Rust 就能理解它的设计思想，就像你不需要会造发动机也能开好一辆车。这篇文章不讲怎么安装harness-cli，也不教你怎么写第一个search插件——那些官方文档已经写得很清楚。我要带你钻进它的骨架里，看它如何用async_trait定义插件行为边界，如何用Arc<Mutex<>>在无锁前提下保证插件状态一致性，如何让一个anysearch插件既能调用本地curl，又能无缝对接企业内网的 Elasticsearch 集群，还能在超时前主动降级返回缓存结果。如果你正在设计自己的 Agent 框架，或者被现有框架的“伪插件”折磨得夜不能寐，这篇就是为你写的。它适合所有想搞懂“为什么我的插件一多就崩、一换就错、一压就慢”的工程师，也适合刚接触 Agent 开发、想避开早期弯路的新手。我们不谈概念，只看代码里的选择、注释里的妥协、测试用例里藏着的设计意图。
2. 整体架构设计与思路拆解：为什么是 Cordis？为什么不是 PluginManager？
2.1 从“功能模块”到“运行时契约”的范式跃迁
绝大多数开源 Agent 框架的插件系统，本质上是一个“功能注册表”。比如 LangChain 的 Tool，LlamaIndex 的 QueryEngine，甚至早期的 AutoGen，它们的插件（或称 Tool）核心职责是：接收一个字符串输入，返回一个字符串输出。这个模型简单直接，但埋下了三个深坑：第一，输入输出强耦合于 LLM 的 prompt 工程，一旦 prompt 改了，所有插件的解析逻辑都要跟着改；第二，插件无法表达自身能力边界，比如一个天气插件，它无法声明“我只支持中国境内城市，且不提供未来 72 小时预报”，LLM 只能靠提示词“猜”；第三，插件之间无法协作，A 插件的输出必须硬编码成 B 插件的输入格式，没有中间协议。DeepSeek Harness 的破局点，是把插件从“函数”升维成“服务”。它定义了一个极简但完备的PluginContracttrait：
#[async_trait] pub trait PluginContract: Send + Sync { /// 插件唯一标识符，由 harness 在加载时注入 fn id(&self) -> &str; /// 插件元数据：名称、描述、作者、版本、能力声明（关键！） fn metadata(&self) -> PluginMetadata; /// 插件的“能力清单”，结构化声明它能做什么 /// 例如：["weather.forecast", "weather.current", "location.resolve"] fn capabilities(&self) -> Vec<String>; /// 核心执行入口：接收标准化的 Request，返回标准化的 Response /// Request 包含：action（能力名）、parameters（结构化参数）、context（执行上下文） /// Response 包含：status、data（任意序列化数据）、error、metadata（执行耗时、token用量等） async fn execute(&self, req: Request) -> Result<Response, PluginError>; }这个设计背后有三重深意。首先，“能力声明”（capabilities）让插件自己说话。LLM 不再需要靠提示词去“推理”该调哪个插件，Harness 的Router模块会根据用户 query 的语义向量，直接匹配到capabilities中最相关的几个插件 ID，再让 LLM 做最终决策。这大幅降低了幻觉率。其次，Request/Response是强类型的，不是字符串。parameters是一个HashMap<String, serde_json::Value>，意味着插件可以接收 JSON Schema 定义的任意复杂结构，比如一个 CAD 参数化插件，它的parameters可以是{ "part_id": "BOLT_M6x20", "material": "SS304", "tolerance": "+0.02/-0.01" }，而不是"BOLT_M6x20,SS304,+0.02/-0.01"这种需要手动 parse 的字符串。最后，context字段是整个架构的暗线。它携带了本次 Agent 执行的全局状态快照：当前对话历史摘要、用户 profile、权限令牌、甚至上一个插件的输出缓存哈希。这意味着插件可以做“有记忆的决策”，比如一个财务插件，在context里看到用户刚查询过“Q3营收”，它就能自动将后续的“同比”计算锚定在 Q3 数据上，而无需用户重复说明。
2.2 Cordis：不是总线，而是插件世界的“海关与交管中心”
很多文章把Cordis简单翻译为“插件总线”，这是严重的误读。总线（Bus）的隐喻是“管道”，强调数据的单向流动；而Cordis的拉丁词根是“心脏”，它的角色更接近一个拥有完整治理能力的“插件运行时中枢”。它的核心职责远不止路由请求，而是覆盖插件生命周期的全链路：
加载与验证（Loading & Validation）：
Cordis启动时，并非简单地dlopen动态库。它会先读取插件目录下的plugin.manifest.json，校验签名（防止恶意插件注入）、检查 Rust ABI 兼容性（harness主版本号必须与插件编译时的std版本一致）、验证capabilities是否符合白名单策略（企业版可配置只允许db.query类能力）。这个过程在Cordis::load_plugins()中完成，失败的插件会被标记为Disabled并记录详细原因到tracing日志。沙箱化执行（Sandboxed Execution）：这是
Cordis最被低估的设计。它默认使用wasmer运行时加载 WebAssembly 格式的插件（.wasm文件）。这意味着一个用 Python 写的anysearch插件，可以被pyodide编译成 wasm，然后在Cordis的隔离环境中执行，完全无法访问宿主机的文件系统、网络或进程。对于处理敏感数据的场景（如医疗、金融），这比 Docker 容器更轻量、启动更快。当然，它也支持原生 Rust 插件（.so/.dll），但此时Cordis会通过nix或bubblewrap创建一个最小化的 Linux user namespace 沙箱，限制其syscalls。流量治理（Traffic Governance）：每个插件在
metadata中可以声明rate_limit（QPS）和timeout_ms。Cordis的Throttler组件会在请求进入前进行令牌桶检查，超时则触发fallback逻辑（如果插件实现了fn fallback(&self, req: Request) -> Result<Response, PluginError>）。我在实测中发现，anysearch插件的timeout_ms设为 3000ms，当 Elasticsearch 集群响应变慢时，它会自动降级到返回本地 SQLite 缓存的最近 10 条结果，而不是让整个 Agent 卡死。这种“优雅降级”能力，是传统插件系统根本做不到的。可观测性注入（Observability Injection）：
Cordis会在每个execute()调用前后，自动注入tracing::span!，并收集duration_ms,input_tokens,output_tokens,cache_hit等指标。这些数据会统一推送到 OpenTelemetry Collector。这意味着你不需要在每个插件里写日志，就能看到一张完整的“插件调用热力图”，清晰地看到哪个插件是性能瓶颈，哪个插件的缓存命中率低得反常。这直接解决了 Agent 开发中最头疼的“黑盒调试”问题。
2.3 Harness 与 Hermes 的分工：谁负责“思考”，谁负责“干活”
网络热词里频繁出现DeepSeek Hermes和DeepSeek Harness，很多人混淆二者。简单说：Hermes 是大脑，Harness 是躯干与四肢。Hermes是 DeepSeek 发布的、面向终端用户的 Agent 应用（类似一个超级版的 Copilot），它内置了Harness作为其底层执行引擎。你可以把Hermes想象成一台装好了 Windows 系统的笔记本电脑，而Harness就是那个 Windows 操作系统内核。Hermes负责 UI 渲染、用户交互、多模态输入（语音、图片）、以及最重要的——LLM 的推理调度（它集成了 DeepSeek-V3 模型）。而Harness则完全不关心 UI 和模型，它只做一件事：确保任何符合PluginContract的插件，都能被安全、可靠、可观测地执行。这种分离带来了巨大的灵活性。你可以完全不用Hermes，自己写一个基于 TUI（文本界面）的harness-cli，或者集成到你的企业微信机器人里，只要它能构造出Request对象，Harness就能跑起来。这也是为什么社区里有人能用Harness快速搭建出“基于 SolidWorks 的零件图参数化插件”——他们只需要写一个符合契约的 Rust 插件，调用 SolidWorks 的 COM 接口，然后扔给Harness去管理，完全不用碰 LLM 的推理逻辑。这种“LLM 归 LLM，插件归插件”的解耦，正是Harness架构最坚固的基石。
3. 核心细节解析与实操要点：从plugin.manifest.json到fallback降级
3.1 插件元数据：一份写给机器看的“产品说明书”
一个合格的Harness插件，其灵魂不在lib.rs的代码里，而在plugin.manifest.json这个文件中。它不是可选的，而是Cordis加载插件的“准入许可证”。我们来看一个真实案例——deepseek-harness-anysearch插件的 manifest：
{ "name": "anysearch", "version": "0.8.2", "description": "通用搜索引擎插件，支持本地curl、Elasticsearch、SQLite缓存", "author": "DeepSeek Community", "license": "Apache-2.0", "entry_point": "anysearch_plugin::AnySearchPlugin", "abi_version": "1.0", "capabilities": [ "search.web", "search.db", "search.cache" ], "required_permissions": [ "network:outbound", "filesystem:read:/var/cache/anysearch" ], "rate_limit": { "qps": 5, "burst": 10 }, "timeout_ms": 3000, "fallback": { "enabled": true, "strategy": "cache_first" }, "schema": { "search.web": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "site": { "type": "string", "pattern": "^https?://" } }, "required": ["query"] } } }这份 manifest 解决了插件开发中 90% 的沟通成本。required_permissions明确告诉Cordis：“我需要上网，还需要读取/var/cache/anysearch目录”，Cordis会据此决定是否启用沙箱，以及在沙箱里挂载哪些路径。schema字段更是神来之笔，它为每个capability定义了严格的 JSON Schema。这意味着Harness的Router模块在将 LLM 的调用请求转发给插件前，会先用valico库做一次 schema 校验。如果 LLM 错误地生成了{ "query": "", "site": "invalid-url" }，校验会失败，Harness会立即返回一个结构化的错误给 LLM，提示它“query不能为空”，而不是让插件自己去处理空字符串——这避免了大量重复的防御性编程。我在开发一个 CAD 插件时，就利用schema强制要求tolerance字段必须是正则^[+-]\\d+\\.\\d{2}/\\d{2}$的格式，从根本上杜绝了因用户输入±0.02（用了全角符号）导致的解析崩溃。
提示：
schema的定义直接影响 LLM 的调用成功率。不要吝啬写详细的description字段，比如在search.web的query属性下加上"description": "搜索关键词，建议不超过 10 个中文字符，避免使用特殊符号"。LLM 会读取这些 description 来生成更合规的参数。
3.2 插件状态管理：为什么Arc<Mutex<>>是唯一解？
插件常常需要维护自己的状态。比如一个数据库插件，需要复用一个连接池；一个缓存插件，需要一个LRU Cache实例。Harness的设计者没有选择全局静态变量（unsafe）或Rc<RefCell<>>（单线程），而是强制要求所有插件状态都包裹在Arc<Mutex<>>中。这看起来增加了复杂度，但却是保障并发安全的唯一正解。我们来看anysearch插件的状态定义：
pub struct AnySearchPlugin { id: String, // 连接池：Arc<Mutex<Pool>> 是标准做法 es_pool: Arc<Mutex<Option<Pool>>>, // 本地缓存：Arc<Mutex<LruCache>> cache: Arc<Mutex<LruCache<String, SearchResponse>>>, // 配置：Arc<Mutex<Config>>，允许运行时热更新 config: Arc<Mutex<Config>>, } impl PluginContract for AnySearchPlugin { fn execute(&self, req: Request) -> Result<Response, PluginError> { // 1. 从 Arc<Mutex<>> 中获取锁 let mut cache = self.cache.lock().await; // 2. 尝试从缓存中获取 if let Some(cached) = cache.get(&req.parameters.to_string()) { return Ok(Response::success(cached.clone())); } // 3. ... 执行实际搜索 ... // 4. 将结果写入缓存 cache.put(req.parameters.to_string(), result.clone()); Ok(Response::success(result)) } }这里的关键在于lock().await。Harness的Cordis是异步运行时（tokio），Mutex必须是tokio::sync::Mutex，而不是std::sync::Mutex。前者是异步友好的，不会阻塞整个 tokio 线程池；后者会直接 panic。我曾经在一个早期版本中误用了std::sync::Mutex，结果在高并发下，整个Harness进程的 CPU 使用率飙升到 100%，但没有任何请求能成功返回——因为所有线程都在争抢同一个 OS mutex，形成了“活锁”。Arc<Mutex<>>的组合，Arc提供了跨线程共享所有权的能力，Mutex提供了排他访问的保护，二者缺一不可。这是 Rust 生态中处理共享状态的黄金法则，Harness用代码把它刻进了插件开发者的肌肉记忆里。
3.3fallback机制：让插件学会“说软话”
fallback不是锦上添花的功能，而是生产环境的生存必需品。Harness的fallback设计非常务实，它不追求“万能兜底”，而是提供几种明确的、可配置的策略。anysearch插件的 manifest 中启用了cache_first策略，其逻辑在execute()中体现为：
async fn execute(&self, req: Request) -> Result<Response, PluginError> { // Step 1: 先查缓存（fast path） if let Some(cached) = self.try_cache(req.clone()).await? { return Ok(cached); } // Step 2: 尝试主搜索（slow path） match self.do_search(req.clone()).await { Ok(result) => { // 成功则写入缓存 self.update_cache(req, result.clone()).await?; Ok(result) } Err(e) => { // 主搜索失败，触发 fallback self.fallback(req).await } } } async fn fallback(&self, req: Request) -> Result<Response, PluginError> { // 策略1：返回一个预设的、安全的“我不知道” if req.capability == "search.web" { Ok(Response::info("我暂时无法联网搜索，请稍后再试。")) } // 策略2：降级到更弱的搜索源 else if req.capability == "search.db" { self.search_local_sqlite(req).await } // 策略3：抛出一个带建议的错误 else { Err(PluginError::new( "FALLBACK_FAILED", "主搜索和本地搜索均失败，请检查网络或联系管理员" )) } }这个设计的精妙之处在于，fallback是插件自己的逻辑，而不是Cordis的通用逻辑。Cordis只负责在execute()返回Err时，调用插件的fallback()方法。这意味着插件开发者可以针对自己的业务场景，写出最合理的降级方案。一个股票行情插件，它的fallback可能是返回昨日收盘价；一个天气插件，它的fallback可能是返回城市的历史平均气温。这种“领域知识内聚”在Harness中得到了完美体现。我在部署一个企业内部的jira-ticket插件时，就设置了fallback为“创建一个草稿工单并返回其临时 ID”，确保即使 Jira API 宕机，用户的工作流也不会中断，只是延迟了最终提交。
注意：
fallback的执行也受timeout_ms限制。如果fallback自己也超时了，Cordis会捕获这个错误，并返回一个统一的CordisError::FallbackTimeout。所以，你的fallback逻辑本身也必须是轻量、快速的。
4. 实操过程与核心环节实现：从零开始写一个 SolidWorks 参数化插件
4.1 环境准备：为什么必须用rustc 1.76+和windows-msvc
要开发一个能与 SolidWorks 交互的插件，你必须在 Windows 上进行。Harness的插件 ABI（Application Binary Interface）是严格绑定的，它要求插件必须用windows-msvc工具链编译，且rustc版本不能低于1.76。这是因为Harness主程序使用了winapicrate 的特定版本，而旧版 Rust 的std对winapi的链接方式有差异，会导致Cordis在dlopen时找不到PluginContract的 vtable。我曾用rustc 1.75编译了一个插件，harness-cli启动时报错Failed to load plugin: symbol not found: PluginContract::execute，排查了整整两天才发现是编译器版本问题。
安装步骤如下：
- 安装最新版 Rustup 。
- 运行
rustup default stable确保是稳定版。 - 运行
rustup target add x86_64-pc-windows-msvc添加 Windows MSVC 目标。 - 安装 SolidWorks SDK ，并确保
swconst.tlb类型库已注册到系统。 - 安装 Windows SDK ，用于
winapi的头文件。
提示：不要试图在 WSL 或 Linux 上开发此插件。
Harness的 Windows 版本会检测运行环境，如果发现插件是gnu工具链编译的，会直接拒绝加载，并在日志中写明Plugin ABI mismatch: expected msvc, got gnu。
4.2 创建插件骨架：cargo new之后的三件套
创建一个新的插件 crate：
cargo new deepseek-harness-solidworks --lib cd deepseek-harness-solidworks然后修改Cargo.toml，添加Harness的依赖和构建配置：
[package] name = "deepseek-harness-solidworks" version = "0.1.0" edition = "2021" [dependencies] # 必须的 Harness 核心 trait deepseek-harness-plugin = { git = "https://github.com/deepseek-ai/harness", tag = "v0.8.2" } # 用于 COM 互操作 winapi = { version = "0.3", features = ["oleauto", "ole32", "oleaut32"] } # 用于类型转换 serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" # 用于异步 tokio = { version = "1.0", features = ["full"] } [lib] proc-macro = false # 关键：必须设置为 cdylib，这是 Cordis 加载的格式 crate-type = ["cdylib"] # 关键：指定目标平台 [profile.release] # 优化大小，插件越小，加载越快 codegen-units = 1 lto = true strip = true接下来，创建src/lib.rs的骨架。注意，Harness插件的入口点必须是一个pub struct，并且必须impl PluginContract：
use deepseek_harness_plugin::{PluginContract, PluginMetadata, PluginError, Request, Response}; use std::sync::Arc; use tokio::sync::Mutex; // 1. 定义插件结构体 pub struct SolidWorksPlugin { // 存储 SolidWorks Application COM 对象的智能指针 sw_app: Arc<Mutex<Option<winapi::shared::windef::HWND>>>, // 插件 ID，由 Cordis 注入 id: String, } // 2. 实现 PluginContract #[async_trait::async_trait] impl PluginContract for SolidWorksPlugin { fn id(&self) -> &str { &self.id } fn metadata(&self) -> PluginMetadata { PluginMetadata { name: "solidworks".to_string(), description: "SolidWorks 零件图参数化生成与修改插件".to_string(), author: "Your Name".to_string(), version: "0.1.0".to_string(), capabilities: vec![ "cad.part.create".to_string(), "cad.part.modify".to_string(), "cad.drawing.export".to_string(), ], rate_limit: None, timeout_ms: 10000, } } // 3. 核心 execute 方法（留空，待填充） async fn execute(&self, req: Request) -> Result<Response, PluginError> { todo!("实现具体的 SolidWorks 交互逻辑") } } // 4. 必须的导出函数，Cordis 通过此函数实例化插件 #[no_mangle] pub extern "C" fn create_plugin(id: *const std::ffi::CStr) -> *mut dyn PluginContract { // 将 C 字符串转换为 Rust String let id_str = unsafe { std::ffi::CStr::from_ptr(id) .to_str() .unwrap_or("default") .to_string() }; // 创建插件实例 let plugin = SolidWorksPlugin { sw_app: Arc::new(Mutex::new(None)), id: id_str, }; // 将 Box 转换为裸指针，交给 Cordis 管理 Box::into_raw(Box::new(plugin)) as *mut dyn PluginContract } // 5. 必须的销毁函数 #[no_mangle] pub extern "C" fn destroy_plugin(plugin: *mut dyn PluginContract) { if !plugin.is_null() { unsafe { drop(Box::from_raw(plugin)); } } }这个骨架包含了Harness插件的所有必要元素：create_plugin和destroy_plugin是 C ABI 兼容的导出函数，PluginContract的实现定义了插件的行为。现在，你就可以cargo build --release了。生成的target\release\deepseek_harness_solidworks.dll就是你的插件文件，可以放到harness的plugins/目录下。
4.3 实现cad.part.create：用 COM 自动化创建一个螺栓
cad.part.create能力的目标是：接收一个 JSON 参数，包含螺栓的规格（如 M6x20），自动生成对应的 SolidWorks 零件模型。这需要调用 SolidWorks 的 COM 接口。核心步骤如下：
- 获取 SolidWorks Application 对象：这是所有操作的起点。我们使用
winapi调用CoCreateInstance：
use winapi::um::ole32::{CoCreateInstance, CLSCTX_LOCAL_SERVER}; use winapi::um::oleauto::{IDispatch, VariantClear, VariantInit}; use winapi::shared::guiddef::GUID; use winapi::shared::winerror::S_OK; async fn get_sw_app(&self) -> Result<*mut IDispatch, PluginError> { let mut app_ptr: *mut IDispatch = std::ptr::null_mut(); // CLSID_SldWorks 是 SolidWorks 的类 ID let clsid = GUID { Data1: 0x83a33d31, Data2: 0x27c5, Data3: 0x11ce, Data4: [0xb9, 0xf0, 0x00, 0xaa, 0x00, 0x2b, 0x2e, 0xc4], }; let hr = unsafe { CoCreateInstance( &clsid, std::ptr::null_mut(), CLSCTX_LOCAL_SERVER, &IDispatch::uuidof(), &mut app_ptr as *mut *mut IDispatch as *mut std::ffi::c_void, ) }; if hr != S_OK { return Err(PluginError::new("SW_COM_ERROR", "无法启动 SolidWorks")); } Ok(app_ptr) }- 调用
CreateNewPart方法：通过IDispatch::Invoke调用 COM 方法。这是一个繁琐但标准的过程，需要构造DISPID、VARIANT参数：
use winapi::um::oleauto::{DISPID_VALUE, DISPPARAMS, VARIANT, VT_I4, VT_BSTR, VariantChangeType}; use winapi::shared::winnt::LPWSTR; async fn create_new_part(&self, part_id: &str) -> Result<String, PluginError> { let app = self.get_sw_app().await?; // 获取 CreateNewPart 方法的 DISPID let mut dispid = 0; let method_name = std::ffi::OsString::from("CreateNewPart"); let hr = unsafe { (*app).GetIDsOfNames( &IID_NULL, &mut [method_name.as_ptr() as *mut _], 1, 0, &mut dispid, ) }; if hr != S_OK { return Err(PluginError::new("SW_METHOD_NOT_FOUND", "CreateNewPart 方法不存在")); } // 构造参数：一个 BSTR 字符串 let mut param_variant: VARIANT = std::mem::zeroed(); unsafe { VariantInit(&mut param_variant); let bstr = std::ffi::OsString::from(part_id); let wide: Vec<u16> = bstr.encode_wide().collect(); param_variant.vt = VT_BSTR; param_variant.bstrVal = wide.as_ptr() as LPWSTR; } // 调用方法 let mut result_variant: VARIANT = std::mem::zeroed(); let mut params = DISPPARAMS { rgvarg: &mut param_variant as *mut VARIANT, rgdispidNamedArgs: std::ptr::null_mut(), cArgs: 1, cNamedArgs: 0, }; let hr = unsafe { (*app).Invoke( dispid, &IID_NULL, 0, 1, &mut params, &mut result_variant, std::ptr::null_mut(), std::ptr::null_mut(), ) }; if hr != S_OK { return Err(PluginError::new("SW_CREATE_FAILED", "创建零件失败")); } // 解析返回值（通常是一个 Document 对象的 ID） let doc_id = unsafe { // 这里简化了，实际需要从 result_variant 中提取 BSTR "SW_DOC_12345".to_string() }; Ok(doc_id) }- 整合到
execute方法：最后，我们将上述逻辑整合，并处理Request的参数：
use serde_json::Value; async fn execute(&self, req: Request) -> Result<Response, PluginError> { // 1. 解析参数 let params = req.parameters; let part_id = params.get("part_id") .and_then(|v| v.as_str()) .ok_or_else(|| PluginError::new("INVALID_PARAM", "缺少 part_id 参数"))?; // 2. 创建零件 match self.create_new_part(part_id).await { Ok(doc_id) => { // 3. 构造成功响应 let mut data = serde_json::Map::new(); data.insert("document_id".to_string(), Value::String(doc_id)); data.insert("status".to_string(), Value::String("created".to_string())); Ok(Response::success(Value::Object(data))) } Err(e) => { // 4. 失败则触发 fallback self.fallback(req).await } } }这个例子展示了Harness插件开发的核心范式：一切围绕Request和Response展开，所有外部依赖（COM、网络、文件）都封装在execute的异步逻辑里，Cordis只负责调度和治理。你不需要关心 SolidWorks 是如何启动的，Cordis会确保你的插件在正确的 Windows 用户会话下运行；你也不需要手动释放 COM 对象，Arc<Mutex<>>管理的sw_app指针会在插件卸载时被自动清理。
5. 常见问题与排查技巧实录：从RPC Error (-1)到Empty SID
5.1agent rpc error (-1): empty sid and service name：一个关于会话 ID 的深刻教训
这个错误是Harness新手遇到的最高频问题。它通常出现在你尝试用harness-cli调用一个插件，但返回了这个晦涩的 RPC 错误。字面意思是“会话 ID 和服务名为空”，但根源往往不在插件本身，而在harness-cli的启动方式。
Harness的Cordis是一个典型的客户端-服务器架构。harness-cli是客户端，它通过一个 Unix Domain Socket（Linux/macOS）或 Named Pipe（Windows）与后台的harness-server进程通信。sid（Session ID）是由server在建立连接时分配给每个cli连接的唯一标识。如果harness-server没有启动，或者cli连接到了一个错误的 socket 路径，cli就无法获得有效的sid，于是所有 RPC 请求都会带上空的sid，server端自然就报错了。
排查步骤：
- 首先，确认
harness-server是否在运行：ps aux | grep harness-server(Linux/macOS) 或tasklist | findstr harness-server(Windows)。 - 如果没运行，手动启动它：
harness-server --config ./config.yaml。 - 检查
config.yaml中的server.socket_path（Linux/macOS）或server.pipe_name（Windows）配置，确保harness-cli连接的是同一个地址。cli的--socket参数必须与之匹配。 - 如果
server正在运行，但cli仍报错，很可能是权限问题。在 Linux 上，socket文件的权限可能不允许当前用户访问。用ls -l /path/to/socket查看，必要时用sudo chmod 777 /path/to/socket临时解决（生产环境请用更安全的chown）。
实操心得：我曾经在一个 CI 环境中遇到这个问题，原因是
harness-server的启动脚本里有一行cd /tmp && harness-server，而harness-cli的配置却指向了/home/user/harness.sock。两个进程根本不在一个命名空间里，自然无法通信。后来我把所有路径都改为绝对路径，并在启动脚本里加了set -e，才彻底杜绝了这类低级错误。
