Skip to content

expert-harness (hx)

自建 Agent Harness(可信内核)+ 专家包(可分发内容)的 Rust 实现。 当前范围:M0 契约先行 + M1 地基主链 + M2 可信(结构性部分)+ M3 装配(expert.json / 装配器 / 压缩-摘要-外置); M4 团队编排 / M5 治理 / M6 分发尚未开始。

构建

bash
cargo build --offline                 # 全工作区(依赖走本机 rsproxy 镜像缓存)
cargo test --offline -p hx-contract   # 契约单测(离线可跑)
cargo run --offline -p hx-cli -- demo # 演示主链
cargo run --offline -p hx-cli -- run-package examples/deep-research   # 专家包端到端(M3)

真实 provider 联调(run-package 专有开关)

  • --live:走真实 OpenAI 兼容 provider。默认(不加 --live)仍为离线 MockProvider,零外呼。 需环境变量 HX_<PROVIDER>_API_KEY(如 HX_DEEPSEEK_API_KEY)或 HX_API_KEY;凭据缺失则 fail-closed(启动即报错,绝不静默出网)。只读环境变量,不读任何密钥文件。
  • --text-protocol(别名 --no-native-tools):强制走文本协议降级路径 (tool_calling=false → 不下发 tools,从正文解析 <tool_call>{…}</tool_call>)。
  • --model <id>:覆盖入口角色的模型(按内置能力表重建描述符,如 deepseek-flash;未知 id 回落默认条目)。
  • --base-url <URL>:覆盖入口端点(指向任意 OpenAI 兼容 /chat/completions 服务,如 https://api.deepseek.com/v1)。
bash
# 真机示例(凭据只经环境变量注入,不落盘、不进仓库)。去掉 --live 即为离线 mock。
# 用 examples/live-smoke:其 hosted 工具仅 echo、approval.requireFor 为空 → 一次往返即 Done。
# (不要用 examples/deep-research 做真机联调:它声明了 write_file 审批,模型一旦写文件
#   就会停在 awaiting_approval;而 resume 当前不支持 --live,无法续跑 → 卡死。
#   该包用于离线端到端,见上方第 13 行。)
HX_DEEPSEEK_API_KEY=... cargo run --offline -p hx-cli -- run-package examples/live-smoke \
  --live --model deepseek-flash --base-url https://api.deepseek.com/v1

四个开关仅对 run-package 有效;用于其它子命令一律报错(不静默忽略)。

本机外网受限(crates.io 403),统一使用 --offline。不要提交 rust-toolchain.toml—— 它会让 rustup 尝试联网重装工具链而卡死(见 docs/rust-architecture.md 第 12 章 Q8)。 工具链要求:rustc/cargo 1.98.0(本机 stable 即为 1.98.0)。

crate 布局(依赖单向无环,hx-contract 为叶子)

crate 职责
hx-contract 编排原语契约(纯数据 + trait,M0 交付物)
hx-store 状态存储(SQLite,bundled)
hx-policy 策略引擎(三档裁决 + tier 矩阵)
hx-gateway 多模型网关(Chat Completions 主路径 + MockProvider)
hx-context 上下文装配器(A/B/C 三段分离)
hx-tools 工具运行时(只读并行 / 副作用串行;含 read_artifact)
hx-assembly 专家包装配器(expert.json → ResolvedAgent;hx-core 不依赖它)
hx-core 循环引擎(唯一大脑)
hx-cli 命令行 hx(组合根;demo / resume / list / run-package)

设计文档见 docs/rust-architecture.md;M3 设计与审查见 docs/m3-design.md、docs/m3-review-*.md; 交付概览见 overview.md,本机验证记录见 VERIFY.md。