Randy Goal Compiler

把一句模糊需求，编译成一个 有证据、有边界、有止损、可独立验收 的 Agent Goal Contract。

当前版本：v0.1.0

成熟度：runnable——结构、模板、示例和确定性校验可在干净环境运行；跨模型效果评测与真实业务验证仍待完成。

English

它解决什么

长程 Agent 最危险的不是不努力，而是朝错误目标持续努力：

• 把“测试变绿”做成删除测试；
• 把“完成同步”理解成 API 调用没有报错，却没有读回；
• 把“研究结论”做成来源不明的漂亮摘要；
• 把“帮我发布”误当成已经获得外部发布授权。

Randy Goal Compiler 在执行前增加一层合同编译：

自然语言需求
→ 核对规则、现状、事实和权限
→ 必要时一次询问最多 3 个决定
→ 生成 ≤4000 字符 Goal Contract
→ 交给 Codex / Claude Code / Hermes / 其他 Agent
→ 执行证据 + 独立验收

它是什么，不是什么

它是：

• 一个遵循 Agent Skills 格式的 SKILL.md；
• 一套跨运行时的 Goal Contract 协议；
• 一个确定性的合同和仓库验证器；
• 三类合成示例，展示执行、研究和运营预览任务。

它不是：

• Agent 执行器、模型或调度平台；
• 权限系统或外部发布授权；
• Hermes、飞书、GitHub 或客户系统连接器；
• “贴进普通聊天就会自动持续运行”的承诺。

与普通任务书的差别

层	普通任务书常见内容	Randy Goal Compiler
目标	做什么	完成后什么必须成立、为什么
事实	背景描述	[FACT] / [JUDGMENT] / [UNKNOWN]
权限	很少说明	Allowed / Read-only / Requires approval / Forbidden
验收	执行者说做完	证据面 + 独立复核
风险	依赖临场判断	明确风险等级与人工闸门
失败	卡住再说	Stop / Resume / 阻塞证据

适用任务

• 执行型：代码、文档、数据转换、本地产物；
• 探索型：研究、选型、该不该做；
• 运营写入型：API、表格、数据库、消息与发布；
• 创意型：内容、设计、图片、视频，同时保留人工审美判断。

安装

公开仓库：Randy0609/randy-goal-compiler

git clone https://github.com/Randy0609/randy-goal-compiler.git

支持 Agent Skills 的工具可以从仓库 URL 安装，或把整个目录放入该工具的 skills 目录。

也可以不安装：把 SKILL.md 作为项目规则交给 Agent。

不同客户端的安装路径和 Goal 生命周期不同；以客户端当前官方文档为准。

HERMES 本地开发态可以把项目注册为外部 Skill 目录：

hermes config get skills.external_dirs
hermes config set skills.external_dirs \
  "/absolute/path/to/randy-goal-compiler"
hermes skills list

如果 skills.external_dirs 已有内容，必须追加而不是覆盖。详细调用、验证和回滚方式见 目标运行时适配。

使用

对 Agent 说：

帮我把这个需求编译成一个 Goal Contract
给执行 Agent 写一个可独立跑完的目标
把这项研究写成有来源、有止损的任务书
先不要执行，给我一份能交给 Codex /goal 的合同

Skill 的最终交付包含：

1. 可直接复制的 Goal Markdown；
2. 管理者独立抽查；
3. 仍需用户决定的事项。

固定合同结构见 模板，完整字段语义见 协议。

示例

• 执行型：修复合成日期解析项目
• 探索型：评估小团队是否需要向量数据库
• 运营型：只生成合成客户表导入预览

三个示例都是合成教学材料，不对应真实客户、仓库或经营数据。

版本化评测输入见 evals/cases.json。当前只公开评测合同和人工判据，尚未发布任何模型成绩。

验证

只依赖 Python 标准库：

python3 scripts/validate.py repo
python3 scripts/validate.py goal examples/execution-goal.md
python3 -m unittest discover -s tests -v

验证器支持 Python 3.9+；当前本地已在 Python 3.9.6 与 3.14.5 通过。GitHub Actions 使用 Python 3.12，当前远端结果见页首状态徽章。

仓库校验覆盖：

• Agent Skills frontmatter 与目录名；
• 必要文件和内部 Markdown 链接；
• Goal 字符上限、字段顺序和权限四分法；
• 示例中的占位符、证据、风险与停止条件；
• 常见密钥、私钥和敏感文件名。

通过校验只证明结构和规则成立，不证明模型一定执行正确。

事实边界与成熟度

项目	当前状态
Agent Skills 结构校验	已验证
自带示例和单元测试	已验证
不依赖第三方 Python 包	已验证
Hermes Agent 技能发现与预加载	本地已验证于 v0.19.0；真实模型自动触发待评测
Codex / Claude Code 跨模型 A/B	待评测
Hermes Kanban、飞书或其他私有连接器	未包含
降低返工率或提升经营结果	未证明，不作承诺

安全设计

• Goal Contract 不能扩大用户原始授权；
• 高风险动作缺少授权时只能做到预览、草稿或只读证据；
• API 拉取、外部写入、读回、通知分别验证；
• 默认不创建 PROGRESS.md 或 BLOCKED.md 污染业务仓库；
• 不允许用修改测试、CI、阈值或口径制造假完成；
• 不提交客户原始数据、凭据、Cookie、Token、私钥或内部日志。

详见 安全与授权边界 和 SECURITY.md。

路线图

• v0.1：协议、Skill、模板、示例、验证器；
• v0.2：公开、脱敏的任务集和多模型 A/B；
• v0.3：可选的 Kanban / Agent 调度适配器；
• v1.0：有独立复现者、版本化评测集和公开失败案例。

后续发布或重大变更按 开源发布清单 完成远端、CI、干净克隆和安装验证。

来源与致谢

本项目由 Randy 的六段式 Goal Contract 实践演化而来，并吸收了以下公开资源的设计启发：

• KKKKhazix/khazix-skills — leader
• OpenAI — Using Goals in Codex
• Anthropic — Keep Claude working toward a goal
• Agent Skills specification

本仓库没有复制或打包上述项目的代码；链接用于说明方法来源和兼容背景。

License

MIT