用途
Runcap（仓库名 ai-agent-manager）是一个本地优先的 AI 编程智能体控制层，面向需要控制 AI 编程花费、约束任务范围并在合并前要求证据的开发者。它不提供模型访问，而是通过本地网关拦截你自己的智能体（如 Claude Code、Codex 或任何调用 OpenAI/Anthropic API 的脚本）的请求，进行计价、限价和压缩。
主要能力
- 硬性支出上限（网关）：将兼容 OpenAI 或 Anthropic 的工具指向本地网关，记录真实 Token 用量，依据来源表计价，并在达到每日上限时立即阻止调用，返回 429 budget_guard。支持 --mock 无密钥试用。
- Token 无损压缩（内置，无额外依赖）：三层压缩，按构造保证无损，不改变自然语言指令和代码语义。包括逐字段裁剪（JSON 紧凑重序列化、长日志/堆栈折叠为首尾、去除尾随空白）、相同块去重、近似重复的增量编码。实测一次编辑后重读文件从 1,186 降至 737 提示 Token（节省 37.9%），模型仍能正确回答改动行。可用 AIM_COMPRESS=off 关闭。
- 循环检测：当连续多个提示高度相似（默认 3 个 92%+ 相似度）且对话无进展时，标记 loop.looping 并发出警告。可用 AIM_LOOP_DETECT=off 关闭。
- 验证结果成本（runcap outcome）：计算 Verified Outcome Cost = 总运行成本 / 通过验证的任务数，生成带真实性标签的结果收据。
- 验证完整性守卫（runcap outcome --guard）：运行前冻结任务契约（基线提交、验证命令所涉文件 SHA-256、package.json 脚本快照、确认任务当前失败），运行后在干净工作树中从基线重新运行验证命令，检测测试篡改等行为，给出信任等级。
- 任务策略与 CI 执行（runcap mission / policy / ci）：在 .runcap/mission.yaml 中声明任务规则，运行中执行硬性上限，生成带策略块的收据，并在违规时返回 BLOCKED。CI 裁决模式（runcap ci --mode adjudicate）作为必需 PR 检查，不信任智能体收据，从 PR 基础提交在干净 CI 任务中重新计算裁决，输出 PASS / BLOCKED / HUMAN_APPROVAL_REQUIRED。
使用方式
通过归档安装 Runcap，将智能体 API 调用指向本地网关。任务运行：runcap mission run 执行策略并生成收据。CI 集成：添加 .runcap/mission.yaml，将 examples/runcap-adjudicate.yml 复制到 .github/workflows/，模板固定到 Runcap v0.6.0，升级时替换为完整 40 位提交 SHA（不要使用浮动标签）。需配置加固的 GitHub 分支保护（受保护分支、必需检查、合并前最新、驳回陈旧批准、CODEOWNERS 覆盖工作流/策略/验证器/依赖/受保护路径、普通作者无绕过）。无 API 密钥时可离线试用演示命令。
适用场景与限制
适用于已自备 OpenAI 或 Anthropic API 密钥、自备智能体、且能舒适运行 CLI 和本地进程的开发者。Runcap 不承诺精确成本预言，只提供范围加硬性上限。支出控制仅适用于经 Runcap 路由的请求；CI 证明门独立验证代码变更，但不声称独立计量所有模型用量。当前托管同步、团队池、组织报告和付费计划并非可购买产品。验证结果成本不包含订阅、CI 分钟、沙箱计算或人工审查时间。
项目信息
MIT 许可，100% 本地。文档包括信任模型、增量编码证据（docs/delta-encoding-evidence.md）等，暂未提供更多具体链接之外的细节。
