Caveman Agent Profile 贡献指南：从一份 JSON 到 `caveman wrap` 可用的完整注册与校验流程

Caveman Agent Profile 贡献指南从一份 JSON 到caveman wrap可用的完整注册与校验流程【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman本文为 Caveman一个通过原始人话术削减约 65% token 消耗的 Claude Code skill / AI 编码代理网关项目社区贡献者而写。Caveman 接受的最快社区贡献形式是一个 agent profile一份纯 JSON 文件教会caveman run/caveman wrap如何通过既有的 wire 协议和 hook 机制把另一个 AI 编码代理如 Aider、Codex CLI、opencode 等接入 Caveman 网关。读完本文你能独立编写一份通过编译校验的 profile理解agents/compile.mjs编译器的四条安全边界与 fail-closed 校验逻辑并知道哪些改动属于纯数据贡献、哪些必须走核心代码评审。一、License 边界哪些代码可以用什么协议贡献Caveman 仓库采用双许可证结构详见 CONTRIBUTING.md 与 LICENSING.mdMIT 部分profilesagent 配置文件、CLI launcher、SDKs、contracts、kit、graders、provider catalog、integration recipes、extension shell、非核心 skillsBSL 1.1 部分与 engine 绑定的运行时源码。两者都是贡献目标但适用条款不同。提交 profile 属于 MIT 一侧的贡献这也是最快路径的原因之一——profile 是数据文件不涉及核心运行时。二、纯 profile PR 的准入条件一份纯 profilepure profilePR 只需向 agents/profiles/ 目录新增一个id.json文件且目标代理必须满足以下四条约束说一种已存在的wire_protocol协议枚举封闭见下文使用一种已存在的injection.method注入方式使用已存在的命令 hook / 记忆 hook 方法或者干脆省略 hooks不需要新的 CLI installer 或 gateway adapter。满足这四条添加一个代理就是加一个文件而不是改代码。schema 文件 agents/profiles/schema.json 的 description 把这一点写得很直白Profiles are DATA: adding an agent is a new file here, not a code change.2.1 Profile 字段契约schema.json 全字段解析agents/profiles/schema.json 是 draft-07 JSON SchemaadditionalProperties: false——任何未知顶层键都会直接让编译失败。字段分为必填与可选两组必填字段字段约束说明schema_version常量1契约版本id^[a-z0-9][a-z0-9-]*$kebab-case全局唯一caveman wrap id的选择器且不得与保留命令冲突display_name非空字符串展示名vendor非空字符串厂商homepageURI 格式官方文档地址binary_names非空字符串数组与 wrap 目标 / argv basename 匹配用于自动检测每个名字都不能撞保留命令install非空字符串二进制缺失时展示的一行安装提示wire_protocol四值枚举见 2.2代理对代理网关说哪种协议injection四种 method 的 oneOf见 2.3CLI 如何把这个代理指向网关可选字段字段说明args附加启动参数默认[]如 agents/profiles/openclaw.json 中为[chat]attribution{ header }代理读取哪个 HTTP header 做遥测归因如x-cave-agentcommand_hook声明caveman wrap/caveman hooks如何把该代理的嘈杂 shell 输出自动过caveman shrink缺省 无 hook 表面只打印caveman shrink -- cmd的手动指引memory_hook可选、默认关闭caveman mem hook install/--auto-recall每轮自动注入 cavemem 召回skills代理在磁盘上的 skill 表面format: skill-mduser_dirs/project_dirs供caveman convert做像素压缩缺省 该代理没有已验证的 skill 文件约定tested_agent_version该 profile 实际验证过的二进制精确版本x表示未测试。CI 的 agent-conformance 矩阵 pin 必须与它相等injection_completeness三值诚实度标签declarative/builder-assisted/code-only见 2.4last_verified_at/verified_by可选的 ISO 日期 验证者超过 365 天 staleness 预算会 fail closedfallback检测/注入失败时的兜底策略generic-env是安全默认maintainernull Caveman 核心团队否则为 GitHub handle2.2 wire_protocol 枚举当前封闭枚举为四种schema.jsonwire_protocol.enum与 agents/compile.mjs 中WIRE_PROTOCOLS集合一致anthropic-messagesopenai-chatopenai-responsesgemini-generatecontent未知值会直接编译失败honesty: no guessed protocol——wrap 路径不做协议翻译只透传网关已支持的 wire 协议。2.3 injection 的四种 methodinjection是一个 oneOf 结构profile 必须完整落入其中一种形态env—— 设置字面量环境变量。env的 key/value 受 3.1/3.2 两条安全规则约束值可用模板 token{{cave_base_url}}、{{cave_proxy_url}}、{{cave_api_key}}、{{cave_org_id}}。渲染后为空的变量会被整体省略绝不会出现空 auth token。典型例子是 agents/profiles/claude.jsoninjection: { method: env, env: { ANTHROPIC_BASE_URL: {{cave_base_url}}, ANTHROPIC_AUTH_TOKEN: {{cave_api_key}} } }config-env-content—— 渲染一份模式选择的内联 JSON 配置config_content.local用于本地 BYOK 的caveman startconfig_content.managed用于CAVE_GATEWAY_URL指向非回环地址的托管模式整体塞进一个 env var如OPENCODE_CONFIG_CONTENT。agents/profiles/opencode.json 即此形态local把 openai/anthropic provider 的baseURL指到{{cave_base_url}}/v1managed声明一个cavemanprovider 并 pin 模型。config-file—— 把config_overlay合并进用户的真实配置文件base_config.path~按 HOME 解析通过一个 env var如OPENCLAW_CONFIG_PATH指向渲染出的临时配置文件——不改动用户原文件。agents/profiles/openclaw.json 展示了base_config的完整能力path 覆盖用的env_varstate_direnv var 缺失时从状态目录读filename。native-extension—— 由宿主代理加载 CLI 自带的扩展资产。所有字段都是封闭白名单host目前仅允许pi且必须等于 profile idasset仅允许caveman-pi-extensionloader_flag仅允许--extension。profile 永远不能指名一个任意的可执行文件或路径。agents/profiles/pi.json 是唯一实例。另外注入配置中的所有字符串会被validateConfigStrings递归扫描未知模板 token、shell/loader 元字符反引号、分号、$(、换行等都会失败baseurl/api_base/host/endpoint/url 类键必须路由经过 cave 模板 token字面 URL 只允许出现在$schema键。2.4 injection_completeness三级诚实度标签从源码结构看并非所有代理的注入都真的纯数据。agents/technical/agent-profile-registry.md 与 agents/compile.mjs 共同定义了三级诚实尺度declarative—— 仅injection块就能完成路由如 opencode、aider、gemini这才是真正的>node agents/compile.mjs npm install --ignore-scripts --no-audit --no-fund --no-package-lock --prefix packages/cli npm --prefix packages/cli run build node --test packages/cli/tests/agent-registry.runtime.mjs packages/cli/tests/agent-shortcut.runtime.mjs packages/cli/tests/porcelain.runtime.mjsnode agents/compile.mjs的产出是确定性的profile 按 id 排序未变更输入重跑无 diff它会生成/更新三个文件全部标注DO NOT EDITagents/agents.json —— 发布的注册表当前消费方是 CLIpackages/cli/src/agents.generated.ts—— CLI 的内嵌类型化副本使 CLI 保持零运行时依赖import 生成模块运行期不读文件packages/cli/src/reserved-verbs.generated.ts—— 由 agents/reserved-verbs.json 生成的保留词集合。因此提交时必须包含 profile 本身 重新生成的agents/agents.json和packages/cli/src/agents.generated.ts三者缺一不可。也可以对单个文件做干跑校验compile.mjs 提供--check-profile入口node agents/compile.mjs --check-profile agents/profiles/id.json # 成功输出agent profile valid: idCI 侧profile-only 的 PR 会重跑 compiler、fake-harness 矩阵和 first-screen help fixture完整服务端发布门禁是独立的一套。五、何时需要代码评审超出纯 JSON 的改动以下改动属于核心变更不是纯 JSON profile 贡献必须走代码评审新增 wire protocol新增 injection 或 hook 方法新增环境变量键形态或模板词汇修改 compiler 白名单或保留命令表需要手写 installer 的 profile。边界规则很明确留在既有契约内的 profile-only PRCI 全绿即可合入而对 compiler 枚举/白名单的任何改动需要强制的创始人评审。六、Provider 价格更新如果你要动的是价格数据而不是 profile请遵循 shared/provider-catalog/CONTRIBUTING.md。硬性要求每次价格变更必须有引用来源、新的verified_at时间戳并生成不可变的按日期快照未知模型保持零价并打unpriced:标签——绝不猜测。七、签名提交与协作约定本项目使用 Developer Certificate of OriginDCO。每个提交都要签名git commit -s -m your message这会在提交信息里追加Signed-off-by: Your Name youremail。贡献许可按 CONTRIBUTING.md 中的目录级规则执行即第一节所述 MIT / BSL 1.1 分界。协作收尾约定保持 PR 小而聚焦有问题时开 discussion 或发邮件hellocaveman.so。附现有 profile 一览可作为模板参考当前 agents/profiles/ 内置 8 个 profile覆盖四种注入方式与三种注入完整度层级是编写新 profile 时最直接的参照系profilewire_protocolinjection.methodinjection_completenessclaude.jsonanthropic-messagesenvbuilder-assistedcodex.jsonopenai-responsesenv空代码路由code-onlyaider.jsonopenai-chatenv{{cave_base_url}}/openai/v1路径追加declarativeopencode.jsonopenai-chatconfig-env-contentdeclarativeopenclaw.jsonopenai-chatconfig-filebuilder-assistedpi.jsonopenai-chatnative-extensionbuilder-assistedgemini.json / hermes.json—见文件见文件编写建议从declarative层级最简单的 env 形态参考 aider/claude起步若你的代理只能靠配置文件接入选 config-file 并注意~/.id/路径圈禁无论哪种形态先跑node agents/compile.mjs --check-profile file做干跑校验再执行第四节完整命令链确保 CI 一次通过。【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考