The-Ideal-Harness

# 理想的 Harness **围绕无状态模型的控制平面操作系统 — 将概率推理转化为确定性、受控、安全的行动。** 一个与 Claude Code 深度集成的代理 Harness，以及一个可移植的 MCP 执行和工具核心。 `github.com/bharat3645/The-Ideal-Harness` · MIT · 由 Bharat 构建 --- ## 问题 每个“最佳 Harness”都是不完整的。 - **技能** 项目提供了可重用的工作流，但没有执行控制 — 技能可以告诉代理运行 `curl … | bash`，而没有任何阻止措施。 - **记忆** 项目记得，但不会压缩 — 它将整个文件交给模型，烧毁了原本用于节省的上下文窗口。 - **压缩** 项目压缩，但不会记忆 — 它缩小了一个工具结果，而忘记了本次会话的其他内容。 - **编排** 项目按顺序执行工作，但假设您就是 Harness — 它运行在一个主机上，而当您切换代理时，保证就会消失。 每个项目都是真实且优秀的。但它们都没有涵盖整个栈。将四个项目组合在一起，您会得到四个重叠的“状态”概念、两个相互竞争的策略故事，以及一个实际上只是一个礼貌的提示段落的安全底线。 所以，我们构建了一个涵盖所有层次的 Harness，没有重叠。 ## 它是什么 理想的 Harness 是围绕无状态模型的控制平面操作系统：它将概率推理转化为确定性、受控、安全的行动。它是 ~30 个领先的 Harness、技能、记忆和 Web 仓库中精选的最佳理念的清洁室合成 — Superpowers、gstack、gsd-core、hermes、omnigent、headroom、graphify、claude-mem、chrome-devtools-mcp、impeccable、SkillSpector、last30days、firecrawl 等等 — 有理化的 **一个相干的 monorepo，其中每个功能都有一个确定的归属**。每个功能都选择了一种机制。被拒绝的替代方案有文档记录，而不是被静默删除。 我们阅读了那些 ~30 个仓库，以确定事实真相，从每个仓库中选取最好的想法，并抛弃了那些空洞的想法。剩下的内容是五个模块，它们共享一个基板和一个执行底线，模块之间没有功能重叠。 安全层不是模型的建议。它是运行在模型 **之下** 的确定性代码，位于 `PreToolUse` / `PostToolUse` 钩子上。模型提出建议；底线决定行动。 ## 数据 在一个真实的代码库上进行了测量（Voraxx worker 源代码：105 个文件，33,629 行代码，16 毫秒内索引到 2,707 个符号；整个仓库的秘密扫描覆盖了 2,577 个文件）。这些是唯一声称的指标，其中几个指标故意不吸引人 — 那些 **无法造假** 的指标证明了其他指标是真实的。Voraxx 代码库是外部的，**不** 包含在这个仓库中，因此无法从这里重新运行这些确切的令牌计数；方法和逐个案例的分析在 [`BENCHMARK.md`](./BENCHMARK.md) 中，压缩器本身由仓库内的单元测试覆盖。 | 功能 | 测量 | 结果 | |---|---|---| | **上下文（代码图）** | 通过 token-budgeted 子图回答代码问题 vs 读取文件 | ~1,988 个令牌 vs 17,323–37,369 → **8.7x–18.8x** 更少 | | **压缩（结构化）** | 2,707 行 JSON 工具输出 | 100,728 → 196 个令牌 → **99.8% 已保存** | | **压缩（日志）** | 2,969 行 grep 日志，大多数是唯一的行 | 91,544 → 88,402 个令牌 → **3.4% 已保存** | | **秘密红控** | 扫描 2,577 个文件 | 标记了 40 个类似秘密的字符串，跨越 18 个文件 | | **策略引擎** | 10 个现实请求 | 2 个允许 / 4 个询问 / 4 个拒绝 | | **漂移防护** | 3 个真实符号 + 1 个虚构符号 | 找到 3 个，标记 1 个缺失，0 个错误阻止 | | **恶意技能审查** | 具有 `curl … \| bash` + “忽略所有以前的指令” 的技能 | 已阻止（高严重性） | 关于诚实的那些： - **3.4% 在 grep 日志上是重点。** 唯一的行几乎无法压缩，因此我们直接报告。结构化输出从 100,728 到 196 个令牌压缩；非结构化日志不会。声称否则的 Harness 就是在撒谎。 - **40 个类似秘密的字符串** 包括测试夹具；命名类别细分为 jwt 10，private-key 5，bearer 5，aws 2，anthropic 1，github 1，其余类别未命名。声明是 **在任何内容到达模型或日志之前进行确定性检测** — 不是“此仓库正在泄密”。 - **策略拒绝** 是凭证读取、`rm -rf` 和写入策略文件本身。底线拒绝让代理编辑自己的底线。 - **漂移防护** 被赋予 3 个真实符号和 1 个虚构符号：它找到了所有 3 个，标记了虚构的符号缺失，并且没有硬阻止任何真实符号。虚构的符号在它们变成损坏的编辑之前被捕获。 - **审查扫描器** 以高严重性阻止了一个携带 `curl … | bash` 和“忽略所有以前的指令”的技能 **在其安装之前，而不是运行后**。 ## 五个模块（v0.1） 每个模块都是一个独立的可安装插件；`core` 是必需的。每个引擎也作为一个独立的 MCP 服务器和 CLI 运行。 | 模块 | 角色 | 这里有什么 | |---|---|---| | `core` | 基板 | 插件加载器，清单 + 技能验证，依赖项无关的技能模板化，具有多主机生成的（Claude Code，Codex，Gemini，Cursor），一个启动技能和每个其他引擎重用的最小 MCP stdio 服务器。 | | `guard` | 执行底线，在模型下 | 拒绝赢 / 关闭策略引擎，具有 Anthropic 对齐的默认值，提示注入包装，始终开启的秘密红控，作用域秘密代理，技能审查扫描器（威胁签名 DB + 同形 / 隐藏字符检测），漂移防护权限阶梯捕获虚构符号，和 OS 沙盒命令构建器（Seatbelt / bubblewrap）与子进程环境净化。`PreToolUse` / `PostToolUse` 钩子使 **策略，外发秘密阻止，秘密红控和注入防护** 自动化；沙盒，审查，漂移防护和代理是 MCP 工具 / CLI 主机调用（见下文）。 | | `compress` | 上下文经济 | 确定性，提示缓存安全的 `tool_result` 压缩 - 异常保留的 JSON 采样，日志 RLE，堆栈跟踪折叠 - 由令牌阈值控制，具有无损恢复的 Compress-Cache-Retrieve（CCR）存储，以及原始输出侧的简洁模式。 | | `memory` | 回忆 | 具有令牌预算的子图检索（回忆结构，而不是整个文件）的结构化代码图和按 BM25 相关性排名的临时存储，而不是按时间顺序，由调解员与工具调用证据相协调。 | | `orchestrate` | 控制流 | 持久任务账本，工具注册表，循环 / 无进展防护，支出管理，API 重试 / 退后，会话恢复 / 检查点，以及带有子代理驱动开发和集思广益（HARD-GATE）技能。 | ## 普遍性，诚实地讲述 这 **不是** 多后端运行时。可移植性分为两个层级，我们在实际应用中划分界限。 - **第一层 — 深度，Claude Code 原生。** `SessionStart` / `PreToolUse` / `PostToolUse` 钩子，自动防护，完整的技能 + 插件体验。底线在没有模型配合的情况下强制执行。 - **第二层 — 任意 MCP 能力代理** （Cursor / Cline / Codex / Gemini）。每个引擎都作为一个独立的 MCP 服务器和 CLI 交付，因此其他主机获得工具 **和** 执行原语。技能通过多主机 `SKILL.md` 生成移植。 **不传输的内容：** 钩子驱动的 **自动** 执行。在第二层主机上，没有任何内容会自动触发 — 主机必须自己调用策略，沙盒和审查 CLI。我们宁愿公开说明这一点，也不愿假装地板在任何地方都是免费的。 ## 每个工具调用自动运行的内容（第一层） 两个 `guard` 钩子在每次工具调用周围确定性地触发 - 没有提示，没有模型合作。这是运行 **在其自身** 的地板： **PreToolUse — 在调用执行之前：** 1. **策略检查。** 拒绝 > 允许 > 询问，关闭失败（Claude Code 自己的优先级）。凭证读取，`rm -rf` 和写入策略文件被拒绝；只读 git 允许；模糊操作变为询问，而不是静默允许。底线 **默认软性** — 降级为询问，以便人类决策，镜像 Claude Code 的开箱即用姿态 — **操作员可调，不限模型**：`IDEAL_HARNESS_FLOOR_MODE=enforce` 恢复硬性拒绝，`ideal-harness.policy.json`（项目根目录或 `~/.config/`）添加更高层级的规则或按 ID 禁用默认值，和 `claude --dangerously-skip-permissions`（或 `IDEAL_HARNESS_DANGEROUSLY_SKIP_PERMISSIONS=1`）完全放弃权限门控。每个软化都会在 stderr 上宣布；损坏的用户策略会恢复到原始默认值；未识别的模式值会严格失败。 2. **外发秘密阻止。** 出口工具（`Bash`，`Write`，`Edit`，`WebFetch`）被扫描；一个会携带秘密的调用在运行前被阻止。 3. **决策日志 + 学习循环。** 每个决策都被追加（秘密红控，失败打开）到 `.ideal-harness/guard-journal.jsonl`；`ideal-harness-guard learn` 将重复的批准转化为 **建议** 的允许列表条目，人类可以粘贴到策略文件中 — Harness 自己不会应用它们。 **PostToolUse — 在结果上，在模型读取之前：** 4. **秘密红控。** 结果被重写，秘密被遮蔽为 `[REDACTED:type]` （通过 `updatedToolOutput` 合同）在模型看到它之前 — 与标记 40 个类似秘密的字符串跨 18 个文件相同的检测器。 5. **注入防护。** Web/MCP 输出或任何结果触发注入提示，被包装在一个突破安全的安全 `<untrusted_content>` 围栏中，以便模型将其视为数据，而不是指令。 **在 SessionStart** 时，注入 `using-ideal-harness` 启动技能，以便模型知道地板是活动的以及如何路由。 ## 代理或主机调用的工具 — 确定性，但非自动 这些是地板和引擎的其余部分。它们是 **MCP 工具和 CLI** — 模型或主机有意调用它们；它们 **尚未** 应用钩子。自动应用沙盒（通过 PreToolUse `updatedInput`）和压缩（通过 PostToolUse `updatedToolOutput`）是路线图上的下一个连接步骤。 - **沙盒** — `buildSandboxCommand` 用一个带有净化环境的 Seatbelt / bubblewrap 配置文件包装 shell 命令（CLI / 原始）。 - **压缩 + CCR** — `compress_tool_result` 缩小超大 JSON / 日志缓存安全；`ccr_retrieve` 恢复原始。 - **漂移防护** — `verify_symbol` 在依赖它之前检查符号与代码图。 - **技能审查** — `vet_skill` 在安装之前扫描技能（威胁签名 DB + 同形 / 隐藏字符）。 - **记忆** — `query_graph`，`memory_search`，`memory_write`，`reconcile`，`add_file`。 - **编排** — `ledger_add` / `ledger_update` / `ledger_status`，`loop_check`，`spend_check`。 在第二层（任意 MCP 主机）上，**两个列表中的所有项目** 都可以通过相同的 MCP 服务器 / CLI 访问；只有上述自动钩子应用是 Claude Code 特有的。 ## 上下文预算状态栏（第一层） Claude Code 的底线带有实时上下文窗口仪表 — `IH <used>/<window> <pct>%`（例如 `IH 142k/1M 14%`）— 显示已花费的令牌和它们占模型 **总上下文窗口** 的份额。它建议在 14% 后 `⚠ consider /compact or /clear`，在 17% 后 `⚠ /compact or /clear for better results`，并在单个回合添加很多时显示 `· filling fast` 标志。它 **仅显示 + 建议**：Claude Code 没有钩子强制 `/compact` 会话中间，因此 Harness 永远不会自动压缩。建议带是 **软** 质量线 — 答案随着窗口填充而降低 — **不是** 模型的硬限制；原生自动压缩仍然是硬限制退路，而 `compress` 的工具结果缩小减缓了填充。窗口 **不是** 硬编码 — 钩子从 Claude Code 的 `context_window.context_window_size` 读取活动模型的实际窗口（默认 200k，扩展上下文模型为 1M），因此百分比在您运行的模型上是正确的；`IDEAL_HARNESS_BUDGET_WINDOW` 覆盖它，而 ~1M 仅在主机报告没有窗口时作为备用。分类是 `compress` 中的纯单元测试逻辑；状态栏钩子从 Claude Code（或回退到转录）读取已花费的令牌 + 窗口，并失败打开到 `IH —`。 ## 原则 - **在模型下执行。** 每个安全性和范围规则都是确定性代码 — 钩子，门，扫描器 — 而不是提示中的礼貌请求。 - **零重叠。** 每个功能都选择一种机制；被拒绝的替代方案有文档记录，而不是被静默删除。 - **默认诚实。** 3.4% 的压缩率和 v0.1 的范围注释都是功能。我们无法伪造的指标是 **证据** ，证明那些不容易检查的指标。 - **标准对齐。** 12-Factor Agents 合规；与已发布的上下文工程和长期运行的 Harness 指南以及 OWASP LLM06（过度代理）对齐。 ## 架构 ``` ┌─────────────────────────────┐ 模型提出 ──► │ guard │ ◄── 拒绝赢，关闭 工具调用 │ 策略 · 沙盒 · 审查 · │ PreToolUse / PostToolUse │ 秘密红控 · 漂移防护 │ 执行底线 └──────────────┬──────────────┘ │ 允许调用 ┌──────────────┬─────────────┼─────────────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────┐ │ core │ │ compress │ │ memory │ │orchestrate│ │ (您的工具) │ │基板│ │ 上下文 │ │ 回忆 │ │ 控制 │ │ │ └─────────┘ └──────────┘ └──────────┘ └───────────┘ └──────────────┘ │ 每个引擎 = 插件（第一层）+ 一个 MCP 服务器 / CLI（第二层） </div> `guard` 位于模型和每个工具之间。其他引擎作为插件运行在 Claude Code（第一层）作为 MCP 服务器或 CLI 运行在其他地方（第二层）。## 安装和快速开始 理想的 Harness 作为 Claude Code **插件市场** 支持 npm 交付。每个模块都是一个独立的可安装插件；`core` 是必需的。 **安装一次，全机范围** — 插件在用户范围内安装，并在每个项目中可用。 ### 第一层 — 在 Claude Code 中安装（推荐）```bash # 添加市场，然后安装核心（必需）以及您想要的任意插件。 # 每个插件都来自 npm，因此其构建代码、钩子和 MCP 服务器 # 安装并连接自动 — 无需克隆，无需构建，无需 .mcp.json 编辑。 /plugin marketplace add bharat3645/The-Ideal-Harness /plugin install ideal-harness-core@ideal-harness # 必需 /plugin install ideal-harness-guard@ideal-harness # 执行底线 /plugin install ideal-harness-compress@ideal-harness /plugin install ideal-harness-memory@ideal-harness /plugin install ideal-harness-orchestrate@ideal-harness ``` 每个插件的 `source` 是其 npm 包 (`@ideal-harness/*`)；安装它会将发布的 tarball（包括 `dist/`、钩子和技能）拉入 `${CLAUDE_PLUGIN_ROOT}`，因此地板和工具立即生效。批准一次 MCP 服务器提示。 ### 第二层 — 以 MCP 服务器 / CLI 运行任意引擎（任意 MCP 主机） ```bash npx -y @ideal-harness/guard mcp # 策略 / 审查 / 漂移 / 隐藏 - MCP（stdio） npx -y @ideal-harness/memory mcp # 代码图 + 临时存储 npx -y @ideal-harness/compress mcp # tool_result 压缩 + CCR npx -y @ideal-harness/orchestrate mcp # 账本 / 支出 / 循环防护 ``` 将第二层主机（Cursor / Cline / Codex / Gemini）指向 MCP 服务器，或直接调用 CLI 以手动调用策略检查、沙盒和技能审查。 ### 从源码开发（无需发布） 在 Harness 本身或发布前运行它？构建一次并将任意项目指向本地检查： ```bash git clone https://github.com/bharat3645/The-Ideal-Harness && cd The-Ideal-Harness pnpm install pnpm build # 所有引擎（或：pnpm -r run build） pnpm test # node:test，无测试框架依赖 pnpm validate # 基板验证其自身仓库 pnpm setup # 将 Harness 绑定到此目录，或… pnpm setup /path/to/your/project # …任意项目 - 写入 .claude/settings.json + .mcp.json ``` `pnpm setup` 是幂等的；重启会话并再次批准 MCP 服务器。 ### 发布（维护者） ```bash pnpm release:dry # 构建 + 打包所有内容，无需发布 — 检查内容 pnpm release # 构建 + 发布所有 @ideal-harness/* 到 npm（需要 npm 授权） ``` 在 CI 中标记 `vX.Y.Z` 以通过 CI 发布（`.github/workflows/release.yml`，需要 `NPM_TOKEN` 秘密）。## 验证 - **130 个单元测试** 在 `node:test` 上运行，无测试框架依赖。 - Biome clean，完全类型检查。 - CI 在每次更改时运行 biome + 构建 + 检查 + 测试 + 验证 + 技能威胁自我扫描。 - **自测试。** 基板验证其自身仓库；代码图索引其源代码。 ## v0.1 范围，简单说明 诚实是品牌，所以这里是 v0.1 的准确位置。 - **9 个设计模块中有 5 个已发布。** `web`（浏览器 + 抓取 + 研究），`skills`（SDLC 库），`design`（风格检查器）和 `eval` 将在 v0.2 中发布。 - **故意为深层清洁而设计，具有已经绘制好的升级路径：** - 代码图今天使用正则表达式；树状解析器是 v0.2 升级后的相同接口。 - 临时存储今天在内存中；SQLite-FTS5 + 向量搜索是 v0.2。 - 漂移防护今天使用 grep 层；LSP / SCIP 是 v0.2。 没有被高估的内容。合同已固定；引擎在它们后面变得更加锐利。 ## 许可证 MIT。