chargehand

chargehand

面向编码 Agent（Claude Code、OpenCode）的编排器：发送问题或变更请求，获取结构化 JSON，其中每项声明都引用固定提交中的文件。

活跃开发中。本月我会继续开发它。

flowchart LR
  caller[You or a program<br/>CLI · HTTP · MCP] -- request --> intake[Intake<br/>picks an action]
  intake -- answer or split --> workers[Agent sessions<br/>Claude Code or OpenCode]
  intake -- ask · deny · improve --> result
  workers -- claims + citations --> resolver[Evidence resolver<br/>checks each citation]
  resolver --> result[Typed result<br/>claims · open questions · cost]
  workers -. code preset, driven batches .-> branch[Tested branch<br/>or draft pull request]
  resolver --> log[(Run log<br/>tokens · cache · prompts)]

为什么要做

编码 Agent 会用散文作答。调用它的程序需要可验证的内容：关联到某个提交中文件的声明、差异、会话消息或调用方自己的输入，以及置信度和答案背后的确切提示词。 我还希望将控制流（任务图、预算、重试、并行处理）写在代码里，而不是放进提示词中，这样每个 Agent 的上下文就能保持精简、可缓存且可丢弃。

功能

• 提供带有已验证引用的答案。 引用可以是文件和行范围、提交、差异范围、会话消息或输入 ID。每条引用都必须在固定提交中存在，声明才能离开工作器；工作器有一次修复机会，仍未通过验证的声明会转为待解问题。
• 将问题拆分为 2 到 4 个只读子任务，并在任务图中运行；仅当接收阶段选择拆分且预设允许时才会这样做。后续子任务会复用第一个子任务缓存的提示词前缀。
• 预设会设置工具、令牌与费用预算，以及允许的操作：default、cheap、thorough、strict、draft（适用于自带事实的程序）、review 和 code；code 会在沙盒中编写一个通过测试的分支。
• **批量执行任务。**将任务列表作为并行的 Claude Code 会话运行，每个会话使用一个受限容器，并以草稿拉取请求结束。
• **接入你的工具。**提供 MCP 服务（stdio 或 HTTP）、HTTP API、CLI、Claude Code 插件（/chargehand:change：用一个提示词完成审查后的本地分支变更），以及浏览器中的操作控制台。
• **衡量自身表现。**运行日志会记录每次调用的令牌数、缓存命中、费用和提示词链；Prompt CI 会在提示词和预设变更合并前，通过配对评测进行门禁检查。

本项目不提供：自带 Agent 循环、直接调用模型提供商、模型网关、记忆存储（通过 MCP 使用你的记忆存储）或托管服务。能够解析的引用会指向确实存在的内容；检查引用文本是否支持对应声明属于规划中的功能，尚未实现（路线图）。

警告

尚未达到 1.0 版本。镜像没有 latest 标签：请固定使用确切版本，并在升级前阅读更新日志。

快速开始

从克隆的仓库中提出一个关于 chargehand 本身的问题。需要 .NET 10 SDK、git，以及位于 PATH 中的 Claude Code 2.1.283，并且已登录（运行一次 claude）。如果没有配置文件，工作器会使用 CLI 自身的登录信息和默认模型。

git clone https://github.com/Egoushka/chargehand.git && cd chargehand
cat > request.json <<EOF
{
  "contract_version": "request/v1",
  "text": "Where does a split node decide whether to fork the first node's session? Cite the code.",
  "context": { "interactive": false, "preset": "default",
               "repository": { "path": "$PWD", "commit": "$(git rev-parse HEAD)" } }
}
EOF
dotnet run --project src/Chargehand.Cli -- run < request.json

它会在 stdout 上打印 result/v1：包含引用的声明、待解问题、置信度和费用。快速入门指南解释了每个字段、如何用 OpenCode 替代 Claude Code，以及运行失败时该怎么做。

若要从 MCP 客户端使用，无需克隆仓库；可通过 dnx 从 nuget.org 运行该包，并固定到某个发行版本：

claude mcp add chargehand -e CLAUDE_CODE_OAUTH_TOKEN=<token> -- dnx Chargehand@<version> --yes -- mcp

工作原理

1. 接收请求读取请求（request/v1），并写入一份任务规范：一个操作，answer、split、ask、deny 或 improve。后三种操作会通过提问、说明原因或给出更好的请求来停止运行。预设也可以在风险或成本估算超过阈值时停止运行，等待批准。
2. 工作器是在固定提交版本的仓库克隆中运行的普通 Claude Code 或 OpenCode 会话，且仅限于配置文件允许的目录。chargehand 本身不会调用模型提供商。
3. 证据解析器会根据 git、会话和请求检查每条引文。不变条件是：除非引文已解析，否则任何声明都不会进入结果。
4. 结果（result/v1）包含声明、待解决问题、用量和提示词链。同一记录也会写入运行日志，show、cache 和 routes 会读取该日志。

写入类运行使用沙箱化工作器，并遵循相同流程：code 预设会通过仓库测试验证分支，而驱动式批次还会添加出口允许列表、独占 Docker 套接字的运行器，以及在创建拉取请求前的检查关卡。ARCHITECTURE.md 描述了代码结构。

数据

	数值	来源
已解析的引文，只读运行	50 条中的 50 条（阶段 3），99 条中的 99 条（阶段 4）	基准测试
与单个普通会话相比，拆分的成本	1.53×（每次运行 $0.00754，而非 $0.00492），盲测得分为 0.967，而非 0.950	阶段 4
Prompt CI 阻止的故意提示词回归	2 次中阻止了 1 次，而且是在得分加入完整性指标后才做到的	Prompt CI
公开仓库上的质量基准测试	在 4 个固定版本的仓库上执行 13 项任务；尚无真实运行	基准测试
用户	1 名，就是我	计数值

经验

• **并行处理在我测量的问题上并不划算。**拆分处理解析了所有引文，但成本高出一半，得分提升却很小，因此发布的 default、review 和 draft 预设均不允许拆分 （ADR 0017）。
• **衡量运行时检查已强制执行内容的得分，发现不了问题。**最初的 Prompt CI 得分衡量依据充分性，而解析器已经强制保证了这一点，因此即使提示词遗漏了三分之一的声明，也能通过。现在的得分会将依据充分性与完整性相乘（ADR 0019）。

文档

• 概述：它是什么、运行如何工作、有哪些不包含的内容，以及状态
• 功能及其依据：各项功能的状态与证据
• 快速入门 · 使用 Docker Compose 安装：从克隆开始，或使用发布镜像
• 从 MCP 客户端使用 · 运行 HTTP 服务 · Web UI
• 编写分支 · 驱动式写作会话 · 多个运行器
• change 命令：Claude Code 插件
• 记忆与服务 · Prompt CI · 基准测试
• 参考：命令、路由、预设、契约、配置文件字段、环境变量
• 架构 · 决策 · 更新日志 · 路线图
• 贡献指南 · 安全 · Apache-2.0 许可证