radiant-harness

> 🤖 **作为 AI 代理阅读本文？** 请先阅读 **[`AGENTS-FOR-TASKS.md`](AGENTS-FOR-TASKS.md)**，该文件包含安装和连接的合约。 --- <!-- Hero --> <div align="center"> <br/> # ✨ radiant-harness ### 自主开发工具 —— 连接您正在使用的任意代理。 **无需 API 密钥 · 无需 HTTP 出口 · 无需遥测数据。支持 12 种代理。** 支持 **Claude Code · Cursor · Hermes · Codex · Cline · Kimi · OpenCode · OpenClaw · Windsurf · Zed · VS Code Copilot · MiniMax Code** —— 以及任何与 MCP 兼容的代理。 <br/>        <br/> ```text ┌──────────────────────────────────┐ │ 您的代理 │ │ Claude · Cursor · Hermes · … │ └────────────────┬─────────────────┘ │ 通过 stdio 的 MCP │ （JSON-RPC 2.0） ▼ ┌──────────────────────────────────┐ │ radiant-harness │ │ │ │ 55 个命令 · 11 种代理 │ │ 推理：MCP 采样 │ │ 返回给主机代理 │ │ │ │ 无 API 密钥 · 无 HTTP 出口 │ │ 无遥测数据 · 无供应商锁定 │ └──────────────────────────────────┘ ``` <br/> ```bash # 1. 安装（单个二进制文件，无依赖） curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') \ -o /usr/local/bin/radiant && chmod +x /usr/local/bin/radiant # 2. 连接到您的代理（自动检测） radiant setup-mcp # 3. 从任意 shell 使用 radiant loop start "添加 /healthz 端点" radiant run specs/0001-foo radiant fleet start "迁移身份验证" ``` <br/> **[安装](#-installation) · [快速入门](#-quickstart) · [命令](#-commands) · [工作原理](#-how-it-works) · [代理](#-supported-agents) · [FAQ](#-faq)** </div> --- ## 为什么选择 radiant-harness？ 您已经在使用代理了。它可以读取文件、运行测试、编辑代码。但它会陷入循环：做出相同的更改，得到相同的错误，烧毁您的上下文窗口，直到您关闭它。 **radiant-harness 为您的代理提供了一个骨架。** 一个包含 **55 个命令** 的单一二进制文件，驱动与您的代理相同的循环 —— 但具有预算、防止崩溃的状态和一个单独的验证器，永远不会让相同的模型批准自己的工作。 独特约束：**无 API 密钥**。radiant 永远不会直接与 LLM 提供商通信。每个推理都委托给您正在运行的代理，通过 MCP `sampling/createMessage`。Claude Code、Cursor、Hermes、Cline、Kimi 等。主机代理的凭证，主机代理的模型 —— 您的代码永远不会离开您控制的循环。 --- ## 您将获得 | | | |---|---| | **🔁 防止崩溃的循环** | `radiant loop` — 启动、状态、恢复。每一步都记录；Ctrl-C、OOM、网络掉落可恢复。 | | **⚡ 一次性运行** | `radiant run specs/<id>` — 相同引擎在单次模式下用于特定规范。 | | **🪞 单独验证器** | 工作产品由 **不同** 的 LLM 调用进行判断 —— 永远不是编写它的同一个模型。 | | **🧮 预算引擎** | Token、成本、墙上时钟和工具调用上限。耗尽时失败。 | | **🪜 舰队模式** | `radiant fleet` — 计划器 + 实现者 + 验证器 + 总结器并行。 | | **📋 基于规范的开发** | `radiant spec`、`radiant product`、`radiant init` — CONTEXT.md / spec.md / tasks.md 脚手架。 | | **✅ 验证套件** | `radiant validate`、`radiant evals`、`radiant audit`、`radiant review-pr` — AC↔测试覆盖率，门控结果。 | | **🚀 发布和 CI** | `radiant release`、`radiant setup-ci` — 版本号 + 跨编译 + GitHub Actions / GitLab CI / CircleCI。 | | **🩺 医生** | `radiant doctor` — 诊断代理、MCP 连接、零 HTTP 保证。 | | **🔌 MCP 原生** | `radiant setup-mcp` 连接到 11 种代理中的任意一种，30 秒内。成为单个 `radiant_run` 工具。 | | **📚 69 个捆绑技能** | 领域知识，harness 可以按需读取：Go 架构，MCP 内部，ML，金融风险，监管，... | | **🪶 零占用** | 单个 ~11 MB 二进制文件。LLM 调用时无需 HTTP 出口（在构建时通过 `nm` / `strings` 验证）。 | | **🔓 供应商中立** | 跟踪文件是纯 JSONL。规范文件是纯 Markdown。可以带走。 | --- ## 🤖 对于 AI 代理 本 README 是面向人类的介绍。**如果您刚刚在该存储库中收到一个任务，请不要在这里继续阅读 —— 请转到 [`AGENTS-FOR-TASKS.md`](AGENTS-FOR-TASKS.md)**。该文件包含安装和连接合约，MCP 工具参考（`radiant_possess` / `radiant_phase_status` / `radiant_skill_list` / `radiant_skill_load`），采样往返格式以及故障模式表。 --- ## 安装 ### 一键安装程序（Linux/macOS/WSL/git-bash） ```bash curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash ``` 下载与最新 GitHub 版本匹配的 `radiant-<os>-<arch>` + `SHA256SUMS`，验证 SHA256，然后安装到 `/usr/local/bin/radiant`。无需 API 密钥。无需 `go` 工具链。无需 `npm`。~10 MB。 固定版本：`RADIANT_VERSION=v3.2.8 curl -fsSL ... | bash` ### Hermes 快速入门 Hermes（Nous Research / OpenClaw / Nous）是最常见的请求，也是最难连接的。在 `curl … | bash` 之后： ```bash # 1. 连接 MCP — 将采样块写入 ~/.hermes/config.yaml 并启用。 radiant setup-mcp --agent=hermes --global # 2. 重启 Hermes（或在聊天中使用 /reload-mcp）。 # 3. 请求： # > "使用 radiant-harness 执行 <您的目标>" ``` `setup-mcp --agent=hermes` 将完整的采样块写入 `~/.hermes/config.yaml`: ```yaml mcp_servers: radiant: command: /usr/local/bin/radiant args: [mcp, serve] timeout: 300 sampling: enabled: true timeout: 120 max_tokens_cap: 8192 max_tool_rounds: 5 ``` 无需 `pip install pyyaml`，无需手动编辑 `~/.hermes/config.yaml` 的 Python 文件。默认校准适用于 Hermes 的 30–40 秒冷启动延迟。 在同一文件中覆盖每个用户： ```yaml sampling: model: openrouter/google/gemini-2.5-flash # 强制使用更快的模型 timeout: 60 # 更严格的上限 ``` 如果 Hermes 无法启动 MCP 服务器，请参见 `radiant setup-mcp --agent=hermes --dry-run` 以预览写入文件的内容而不编辑文件。 ### 下载版本 预编译二进制文件也可在 [发布页面](https://github.com/quant-risk/radiant-harness/releases) 上提供。支持六个目标： | 操作系统 | 架构 | 文件 | |----|------|------| | Linux | amd64 | `radiant-linux-amd64` | | Linux | arm64 | `radiant-linux-arm64` | | macOS | amd64 | `radiant-darwin-amd64` | | macOS | arm64 | `radiant-darwin-arm64` | | Windows | amd64 | `radiant-windows-amd64.exe` | | Windows | arm64 | `radiant-windows-arm64.exe` | **macOS / Linux：** ```bash # macOS Apple Silicon curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-darwin-arm64 \ -o /usr/local/bin/radiant chmod +x /usr/local/bin/radiant # Linux x86_64 curl -L https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-linux-amd64 \ -o /usr/local/bin/radiant chmod +x /usr/local/bin/radiant # 验证 sha256sum /usr/local/bin/radiant # 与发布中的 SHA256SUMS 交叉检查 radiant --version # → radiant 3.2.0 ``` **Windows (PowerShell):** ```powershell Invoke-WebRequest -Uri "https://github.com/quant-risk/radiant-harness/releases/latest/download/radiant-windows-amd64.exe" -OutFile "$env:LOCALAPPDATA\Microsoft\WindowsApps\radiant.exe" radiant --version ``` ### 从源代码构建 需要 Go 1.22+。 ```bash git clone https://github.com/quant-risk/radiant-harness cd radiant-harness make build # → ./bin/radiant ``` 或使用普通的 `go`: ```bash CGO_ENABLED=0 go build -o radiant ./cmd/radiant ``` 跨编译所有 6 个目标： ```bash make release # → bin/radiant-{linux,darwin,windows}-{amd64,arm64} ``` --- ## 主机驱动循环的工作原理 当主机代理（Claude Code、Cursor、Hermes、MiniMax Code、Cline 等）调用 `mcp__radiant__possess` MCP 工具时，harness 驱动一个 4 阶段循环 —— 而 **主机代理是执行者**。每个阶段都调用 `sampling/createMessage` 回到主机，请求它思考和行动。（旧别名 `radiant_run` 仍然有效以保持兼容；新代码应调用 `radiant_possess`。） ``` ┌─────────────────────────────────────┐ │ 主机代理（Claude Code、Cursor…） │ ← 您的代理进行思考 + 工具 │ 思考 + 读取 + 编写 + bash │ └──────────────┬──────────────────────┘ │ MCP stdio（JSON-RPC 2.0） ▼ ┌─────────────────────────────────────┐ │ radiant mcp serve │ ← 驱动循环，验证门控 │ sampling/createMessage → 主机 │ │ 解析响应 → 下一阶段 │ └─────────────────────────────────────┘ 阶段： 1. **发现** — 主机读取 CONTEXT.md、项目布局、捆绑技能 2. **计划** — 主机将目标分解为 AC + 任务（使用 nova-feature 技能） 3. **执行** — 主机编写代码、运行门控（go build/test/etc.） 4. **验证** — 主机审查自己的工作；单独传递，以便同一个模型不批准自己的输出 主机的 `sampling/createMessage` 响应 **必须** 以以下内容之一结尾： ``` VERDICT: APPROVED SCORE: 1.00 EVIDENCE: <一句话总结> ESCALATE: false ISSUES: ``` （审查阶段 — 每次迭代检查） ``` REVIEW: PASS SCORE: 1.00 EVIDENCE: <一句话总结> FINDINGS: ``` （收敛后审查小组） 其他任何内容，harness 都会重试。关键词后可以有尾随散文；解析器读取第一个单词。 --- ## 快速入门 ### 安装 ```bash curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash ``` 它做了什么：检测您的操作系统/架构，下载与最新 GitHub 版本匹配的 `radiant-<os>-<arch>` + `SHA256SUMS`，验证 SHA256，然后安装到 `/usr/local/bin/radiant`。无需 API 密钥。无需 `go` 工具链。无需 `npm`。单个二进制文件，~10.5 MB。 ```bash curl -fsSL https://raw.githubusercontent.com/quant-risk/radiant-harness/main/install.sh | bash -s -- --setup-mcp ``` 在同一步骤中添加 `--setup-mcp` 以将 harness 连接到您的主机代理。然后重启代理并请求它交付内容。 显式固定版本： ```bash RADIANT_VERSION=v3.2.6 curl -fsSL .../install.sh | bash # 或从检出构建： make build && ./bin/radiant setup-mcp ``` ### 验证 ```bash radiant --version radiant host-info # 自动检测调用此命令的代理 make smoke # 17/17 OK（二进制侧：字节，无 HTTP-LLM，所有命令） ``` ```text $ radiant host-info 检测到的代理 : Claude Code 置信度 : 100 匹配的信号 : CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_SHELL_PREFIX 进程树 : /Users/you/.npm/_npx/.../claude（pid 12345） ``` ### 使用它 从任意 shell： ```bash # 循环引擎 — 多步骤，防止崩溃，可验证 radiant loop start "添加返回 200 OK 和 JSON 正文的 /healthz 端点" # 为特定规范执行一次性运行 radiant run specs/0001-add-healthz # 舰队：并行代理（计划器 + 实现者 + 验证器 + 总结器） radiant fleet start "从 REST 迁移到 gRPC" # 医生：诊断连接 radiant doctor # 规范脚手架 radiant spec "速率限制中间件" --ac="AC1: 每 IP 100 req/min" --ac="AC2: 返回 429 过量" # 精益初始阶段 radiant product "小型开发团队的 API 可观察性" --mvp-weeks=6 ``` 从您的代理（MCP 路径）： > *"使用 radiant-harness 添加带有测试的 /healthz 端点"* 您的代理调用 `radiant_run`，harness 启动循环，每个 LLM 调用通过 MCP `sampling/createMessage` 路由回您的代理，您在 `.radiant-harness/traces/<run-id>.jsonl` 处获得 JSONL 跟踪。 ### 验证端到端（5/5） 最新预发布验证 — 空仓库，完整的 MCP 占有流程，从每次运行的 CLI 中全新开始： ``` 运行 1 退出：成功 迭代次数：0 build+test=PASS 运行 2 退出：成功 迭代次数：0 build+test=PASS 运行 3 退出：成功 迭代次数：0 build+test=PASS 运行 4 退出：成功 迭代次数：0 build+test=PASS 运行 5 退出：成功 迭代次数：0 build+test=PASS ``` （`radiant_run` 由 Python MCP 主机驱动，针对 `case-real-test` 项目 — 构建一个小型 URL 缩短器（Go）。每次运行从头开始生成 `main.go` + `main_test.go`；所有四个验收标准得到满足；`go build ./...` 通过；`go test ./...` 通过。） ### 2. 从任意 shell 使用 ```bash # 循环引擎 — 多步骤，防止崩溃，可验证 radiant loop start "添加返回 200 OK 和 JSON 正文的 /healthz 端点" # 为特定规范执行一次性运行 radiant run specs/0001-add-healthz # 舰队：并行代理（计划器 + 实现者 + 验证器 + 总结器） radiant fleet start "从 REST 迁移到 gRPC" # 医生：诊断连接 radiant doctor # 规范脚手架 radiant spec "速率限制中间件" --ac="AC1: 每 IP 100 req/min" --ac="AC2: 返回 429 过量" # 精益初始阶段 radiant product "小型开发团队的 API 可观察性" --mvp-weeks=6 ``` ### 3. 验证连接 ```bash ./bin/radiant host-info ``` 输出： ```text 检测到的代理 : Claude Code 置信度 : 100 匹配的信号 : CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_SHELL_PREFIX 进程树 : /Users/you/.npm/_npx/.../claude（pid 12345） ``` `--json` 用于机器可读输出，`--verbose` 显示每个匹配的环境变量。 ### 4. 从您的代理（MCP 路径）驱动循环 从 Claude Code（或任何已连接的代理）内部： > *"使用 radiant-harness 添加带有测试的 /healthz 端点"* 您的代理调用 `radiant_run`，harness 启动循环，每个 LLM 调用通过 MCP `sampling/createMessage` 路由回您的代理，您在 `.radiant-harness/traces/<run-id>.jsonl` 处获得 JSONL 跟踪。 --- ## 如果我的代理不支持采样？（v3.6.0+） `mcp__radiant__possess` 需要主机代理实现 `MCP sampling/createMessage`。截至 2026 年中期，**Codex GPT-5 不支持**（它返回 JSON-RPC `-32601`）。在 v3.6.0 之前，harness 静默退出，`docs/`、`specs/`、`scripts/` 为空。 v3.6.0 修复了这个问题。两个变化： 1. **自我驱动的脚手架模式。** 当 harness 通过 **经验性探测**（`~/.radiant-harness/agent-capabilities.json`）或硬编码的 `knownSamplingUnsupported` 列表检测到主机 **不支持采样** 时，占用运行相同的 4 个阶段（`discover → plan → execute → verify`），但发出确定性的 **Markdown 模板**，带有 `[host-agent: 填写...]` 标记。您使用自己的工具替换标记（脚手架是工件；内容是您的）。 2. **公共安全 CLI 命令。** `radiant spec`、`radiant audit`、`radiant skills`、`radiant context`不再需要 `RADIANT_INTERNAL=1`。具有 shell 访问权限的主机可以直接驱动 SDD 流水线 — 脚手架规范，审计布局，列出技能，组装上下文 — 无需 MCP 循环。 Codex 被硬编码在 `knownSamplingUnsupported` 中，版本为 v3.6.0，因此第一个占用调用在没有探测延迟的新 Codex 盒子上路由到自我驱动。Cline、OpenCode、Kimi、OpenClaw、VSCode 和 MiniMax Code 仍然被声明为 `declared=true` — 如果您在其中一个上观察到类似的 `-32601`，请将其添加到 `knownSamplingUnsupported` 映射中 `internal/hostdetect/probe.go` 并打开一个 PR。 完整的自我驱动合约 — 模板化内容、标记含义、探测缓存更新时间 — 位于 [`AGENTS-FOR-TASKS.md`](AGENTS-FOR-TASKS.md) § “自我驱动脚手架模式”。 ## 工作原理 ```text ┌────────────────────────────────────────────────────────────────────┐ │ 您的代理 │ │ │ │ 1. 用户说 "ship X" │ │ 2. 代理确定这是非 trivial 的 → 调用 radiant_run │ │ │ └─────────────────────────────────┬──────────────────────────────────┘ │ MCP 标准输入输出（JSON-RPC 2.0） ▼ ┌────────────────────────────────────────────────────────────────────┐ │ radiant-harness │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │发现 │ → │ 计划 │ → │ 执行 │ → │ 验证 │ → … │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ 读取捆绑 将目标分解 工具调用 单独 LLM │ │ 技能， 成验收标准 （主机代理 调用以判断 │ │ 嗅探仓库 和任务 调用） 工作 │ │ │ │ 每个 LLM 调用 ↘ MCP 采样/创建消息 ↙ （返回代理）│ └────────────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ 磁盘 │ │ │ │ .radiant-harness/ │ │ ├── traces/<run-id>.jsonl ← 每一步，每个令牌 │ │ └── spec.md, tasks.md ← 可移植的 Markdown 文档 │ └────────────────────────────────────────────────────────────────────┘ ``` ### 四个阶段（由主机代理驱动） 1. **发现** — 代理读取 `CONTEXT.md`，嗅探仓库，选择 3-10 个相关的捆绑技能。 2. **计划** — 代理将目标分解成验收标准 + 任务，并具有明确的门控。 3. **执行** — 代理运行每个任务；如果失败，则重试并将失败原因作为上下文。 4. **验证** — 一个 *全新* 的 LLM 调用（在同一代理会话中，但是一个单独的采样轮次）判断与验收标准的差异。 每一步都追加到 `.radiant-harness/traces/<run-id>.jsonl` 中。 --- ## 命令 这是完整的 CLI 接口 — **55 个命令** 在一个二进制文件中： ### 循环引擎 | 命令 | 功能 | |---|---| | `radiant loop start <目标>` | 启动一个新的反馈循环。 | | `radiant loop status` | 显示正在运行的循环。 | | `radiant loop resume <id>` | 从 BoltDB 恢复一个崩溃的循环。 | | `radiant loop cancel <id>` | 取消一个正在运行的循环。 | | `radiant loop history` | 过去的循环运行。 | | `radiant loop export <id>` | 将跟踪导出为 Markdown。 | | `radiant loop diff <id>` | 显示循环期间发生的变化。 | | `radiant run specs/<id>` | 针对特定规范进行一次性运行。 | | `radiant fleet start <目标>` | 多代理并行协调。 | | `radiant fleet status` | 显示舰队运行。 | | `radiant fleet dispatch` | 向正在运行的舰队添加任务。 | | `radiant trace show <id>` | 检查推理跟踪。 | | `radiant trace list` | 列出可用的跟踪。 | ### 规范驱动的开发 | 命令 | 功能 | |---|---| | `radiant init` | 搭建 SDD 管道（AGENTS.md + 技能）。 | | `radiant spec "<意图>"` | 为功能创建 spec.md + tasks.md。 | | `radiant product "<原因>"` | 启动精益启动。 | | `radiant validate specs/<id>` | 验证 SDD 一致性。 | | `radiant validate-file <路径>` | 验证搭建的计划或规范。 | | `radiant evals` | AC↔测试覆盖率（保真度）跨所有规范。 | | `radiant audit` | 项目布局，AC 可追溯性，ADR 有效性。 | | `radiant review-pr specs/<id>` | 生成 pr-review.md。 | | `radiant adr` | 创建架构决策记录。 | | `radiant diagramar` | C4 Mermaid 图表模板。 | | `radiant views [--agent=…]` | 生成原生代理视图。 | ### 发布和 CI | 命令 | 功能 | |---|---| | `radiant release <版本>` | 版本提升 + 测试 + 跨编译 + 提交 + 标签。 | | `radiant setup-ci --provider=github` | 生成 CI 工作流。 | ### 技能和文档 | 命令 | 功能 | |---|---| | `radiant skills list` | 列出捆绑技能。 | | `radiant skills validate` | 验证技能模式。 | | `radiant update` | 刷新捆绑技能 + AGENTS.md。 | | `radiant context detect` | 检测项目领域。 | | `radiant context assemble` | 构建最小 CONTEXT.md。 | | `radiant context compress` | 压缩 CONTEXT.md。 | | `radiant ontology export` | 导出 harness 本体。 | | `radiant boot` | 打印最小项目清单。 | ### 诊断和会话 | 命令 | 功能 | |---|---| | `radiant doctor` | 诊断 radiant 环境。 | | `radiant state` | 显示当前会话状态。 | | `radiant handoff` | 暂停：写入状态到 .radiant-harness/state.md。 | | `radiant worktree add` | 为并行代理隔离的 git 工作树。 | | `radiant budget estimate` | 令牌预算估计。 | | `radiant tools list` | 检查工具注册表。 | ### 垂直脚手架（MCP 采样） | 命令 | 功能 | |---|---| | `radiant model` | 脚手架模型规范。 | | `radiant predict` | 模型服务请求。 | | `radiant train` | 训练计划。 | | `radiant evaluate` | 评估计划。 | | `radiant drift` | 漂移监测。 | | `radiant profile` | 数据配置文件。 | | `radiant stats` | 假设-测试计划。 | | `radiant causal-estimate` | 因果分析。 | | `radiant incident` | 启动事件。 | | `radiant autodata` | 从提示自动创建技能。 | | `radiant eval` | 运行提示 N 次以获取延迟/成本。 | | `radiant bench` | 与 TLC、Spec Kit、OpenSpec、Superpowers 进行基准测试。 | | `radiant improve` | 从跟踪中自我改进引擎。 | | `radiant integrations` | 只读列出声明的 MCP 集成。 | ### MCP 和代理 | 命令 | 功能 | |---|---| | `radiant setup-mcp [--agent=X]` | 检测代理 + 编写 MCP 配置。 | | `radiant mcp serve` | 在标准输入输出上启动 MCP 服务器。 | | `radiant host-info [--json] [--verbose]` | 打印检测到的主机代理。 | | `radiant completion <shell>` | Shell 补全（bash，zsh，fish，powershell）。 | | `radiant help` | 完整的命令列表。 | ### `radiant test-case` — 离线重现真实主机故障模式 > **项目中最具诊断性的命令。** 启动一个真实的 `radiant mcp serve` 子进程，使用可配置的采样延迟（默认为 **25 s/call** — Hermes mimo / xiaomi / OpenRouter 冷启动），并写入 Markdown 报告。 > 在进行真实 LLM 支持的代理测试之前使用此命令。 ```bash radiant test-case case.zip \ --cold-start-ms=25000 --jitter-ms=5000 \ --sampling-timeout=130s \ --profile=standard \ --report .radiant-harness/reports/case.md ``` 您将获得： - 仅当 harness 退出 `success` 时才退出 0 - 在 `critical_failure`、传输错误或超时时返回非零 - 带有每阶段计时、采样调用计数、harness 的最终 `Exit:` 行和完整事件日志的 Markdown 报告 这是 **CI 级别的证明，证明 harness 处理缓慢的现实世界主机**：每个 PR 都运行 `radiant test-case ./case.zip --cold-start-ms=25000`，并且只有当 harness 在 130 秒的采样超时内完成 4 个阶段的流程时，管道才会通过。 为什么 `--cold-start-ms=25000`？因为 Hermes 的生产冷启动延迟约为 20–40 秒每次采样调用，而这是中断的路径 2026-06-29。此命令存在于离线重现它。 ### 低级（实用） | 命令 | 功能 | |---|---| | `radiant config` | 查看当前配置文件（无 API 密钥，仅预算默认值）。 | | `radiant models` | 列出模型预设（只读）。 | | `radiant pricing list` | LLM 定价表（只读；无 HTTP 获取）。 | | `radiant semantic resolve <术语>` | 将业务术语解析为语义模型。 | | `radiant camada-agentica` | 审计代理层（AGENTS.md，原生视图）。 | | `radiant security` | 硬编码的秘密 + 敏感文件权限。 | | `radiant telemetry status` | 本地仅使用统计数据（默认为关闭）。 | --- ## 支持的代理 `setup-mcp` 目前支持 **11 个代理**。自动检测扫描您的当前目录是否存在 `.claude/`、`.codex/`、`.hermes/` 等，并使用全局回退（`~/.kimi`、`~/.cline`）适用于仅限 CLI 的工具。 | 代理 | 配置文件 | 格式 | 检测信号 | | --- | --- | --- | --- | | **Claude Code** | `.mcp.json` | JSON | `CLAUDE_CODE_*` 环境变量 | | **Cursor** | `.cursor/mcp.json` | JSON | `CURSOR_*` 环境变量 | | **Windsurf** | `.windsurf/mcp.json` | JSON | （项目标记） | | **Zed** | `.zed/settings.json` | JSON | （项目标记） | | **VS Code Copilot** | `.vscode/mcp.json` | JSON | `VSCODE_*` 环境变量 | | **OpenAI Codex** | `.codex/config.toml` | TOML | `CODEX_*` 环境变量 | | **OpenCode** | `.opencode/config.json` | JSON（嵌套） | `OPENCODE_*` 环境变量 | | **Hermes** | `.hermes/config.yaml` | YAML | `HERMES_*` 环境变量 | | **Kimi CLI** | `~/.kimi/mcp.json` | JSON | `KIMI_*` 环境变量 | | **MiniMax Code** | `.MiniMax/mcp.json` | JSON | `MINIMAX_CODE_*` 环境变量 | | **OpenClaw** | `.openclaw/openclaw.json` | JSON（嵌套） | `OPENCLAW_*` 环境变量 | | **Cline** | `~/.cline/mcp.json` | JSON | `CLINE_*` 环境变量 | 运行 `./bin/radiant host-info --verbose` 以查看哪些环境变量与您的会话匹配。 --- ## 零 API 密钥保证 ```bash nm bin/radiant | grep -iE 'chatAnthropic|HTTPBackend|NewHTTPBackend' # （必须返回 0 个结果） strings bin/radiant | grep -iE 'anthropic|openai|openrouter' # （必须返回 0 个结果） ls -lh bin/radiant # ≈ 11 MB ``` 这些检查是 `make smoke` 的一部分，并且在每次提交时运行。 ### 测试 ```bash make test # 24 个包 OK，0 个失败 make smoke # 17/17 个验证检查通过 ``` --- ## 项目布局 ``` radiant-harness/ ├── cmd/radiant/ # CLI 源代码（29 个文件） │ ├── main.go # 入口点，注册所有 55 个命令 │ ├── cmd_setup_mcp.go # 11 个代理路由器 │ ├── cmd_mcp_runtime.go # MCP 服务器（单个工具：radiant_run） │ ├── cmd_loop.go, cmd_run.go, cmd_fleet.go # 循环引擎包装器 │ ├── cmd_spec.go # 规范、adr、diagramar、product、views 等 │ ├── cmd_audit.go # 审计、camada-agentica、evals、release、security │ ├── cmd_doctor.go, cmd_diagnose.go # 诊断 │ ├── cmd_telemetry.go # 遥测 + 统计 + 模型 + 预测 + … │ ├── helpers.go # 共享脚手架助手 │ └── … # 29 个文件 │ ├── internal/ │ ├── loop/ # 发现→计划→执行→验证引擎 │ ├── engine/ # 通用 SDD 引擎 │ ├── llm/ # 后端接口 + 采样后端（MCP） │ │ + 客户端 shim（仅限 Light） │ ├── mcpbridge/ # MCP 工具桥 │ ├── hostdetect/ # 运行时代理检测 │ ├── skill/ semantic/ policy/ # 技能 + 语义 + 策略层 │ ├── tools/ # 文件/搜索/编辑工具 │ ├── config/ pricing/ routing/ # 配置文件、定价、模型路由 │ ├── context/ fsutil/ gaterun/ # 上下文引擎、文件系统实用工具 │ ├── fleet/ harness/ worktree/ # 多代理舰队 + git 工作树 │ ├── scaffold/ spec/ ontology/ # SDD 脚手架 │ ├── boot/ mode/ quality/ routing/ # 项目启动、模式、质量门控 │ ├── schedule/ webhook/ slog/ types.go ← 调度 + 可观察性 │ └── … # 28 个包 │ ├── scripts/ │ └── smoke-test.sh # 17 检查二进制验证 │ ├── docs/ │ ├── HOST-AGENTS.md # 检测矩阵 │ ├── ARCHITECTURE.md # 架构概述 │ └── TWO-REPOS.md # Light vs Full 理由 │ ├── Makefile # make build, make release, make smoke ├── CHANGELOG.md # 版本历史 ├── LICENSE # MIT └── README.md # 你在这里 ``` --- ## 常见问题 **问：为什么没有 API 密钥？** 答：每个 LLM 调用都通过 MCP `sampling/createMessage` 委托给主机代理。您的代理已经配置了模型；harness 只驱动循环。二进制文件没有用于 LLM 调用的 HTTP 出口 — 在构建时通过 `nm`/`strings` 验证。 **问：我是代理 — 我可以调用哪些工具？** 答：四个有界限的基元 — `radiant_skill_list`、`radiant_skill_load`、`radiant_possess`、`radiant_phase_status` — 加上遗留别名 `radiant_run`。整个合约（安装、配置、工具引用、采样往返格式、故障模式）位于 **[`AGENTS-FOR-TASKS.md`](AGENTS-FOR-TASKS.md)`** 中，而不是此处。将其用于非 trivial 任务；对于 trivial 任务（例如，类型修复、单个文件读取），不要调用它们。 **问：如何从 shell 而不是在代理内运行循环？** 答：`radiant loop start "your goal"`。harness 驱动循环本身并调用 `sampling/createMessage` 到您通过 `radiant setup-mcp` 配置的代理。如果没有连接代理，您会得到一个清晰的“先运行 `radiant setup-mcp`”的错误。 **问：harness 是否将您的代码发送到任何地方？** 答：否。二进制文件对于 LLM 调用没有 HTTP 出口（通过 `nm`/`strings` 验证）。唯一的出站流量是到 MCP 标准输入输出通道，它进入您的本地代理。 **问：它会打电话回家吗？** 答：否。无遥测，无分析，无更新检查。 二进制文件是离线优先的。 **问：我可以添加新的代理到 `setup-mcp` 吗？** 答：是的。在 `cmd_setup_mcp_per_agent.go` 中添加一个 `<agent-name>` 块，并具有代理的配置格式和签名环境变量。请参阅 [`docs/HOST-AGENTS.md`](docs/HOST-AGENTS.md)。 **问：我可以添加新的命令吗？** 答：是的。或者在现有 `registerXxxCmds()` 中的 `cmd/radiant/` 添加一个 `root.AddCommand(yourCmd)`，或者创建一个新文件并调用它从 `main.go`。 **问：与 Claude Code 的 / OpenAI Codex 的原生循环有什么不同？** 答：三件事：（1）验证器是一个单独的 LLM 调用，因此同一个模型永远不会批准自己的工作，（2）它适用于 11 个 MCP 代理（不仅仅是一个），（3）每一步都可跟踪到可移植的 JSONL。 **问：它是稳定的吗？** 答：是的。第一个公开版本为 v3.0.0；v3.2.0 将完整的 55 命令表面重新添加到 Light 中。从这里开始使用 Semver。 --- ## 贡献 欢迎提出问题、PR 和分支。 - 新代理 `setup-mcp` → 编辑 `cmd_setup_mcp_per_agent.go`。 - 新的主机检测签名 → 编辑 `internal/hostdetect/hostdetect.go`。 - 新的 MCP 工具 → 编辑 `cmd_mcp_runtime.go`。 - 新的捆绑技能 → 在 `internal/skill/skills/` 下添加一个带有 `SKILL.md` + `frontmatter.yaml` 的目录。 --- ## 许可 MIT — 请参阅 [`LICENSE`](LICENSE)。