企业官网建设流程全解析

• 人工智能
• AI 应用
• AI 技能
• AI 插件
• LLMOps
• 开发工具

caveman 是一个"让编码 Agent 用穴居人式压缩语言回复以降低 token 消耗"的开源项目，它自身的仓库恰好是这份"Agent 协作契约"的完整范例。本文以根目录 AGENTS.md 为绝对主体，拆解它如何用绑定式路由（binding routing）、可见性声明和@文件导入三部分，把 Claude Code、Codex、Gemini CLI 等编码 Agent 约束在正确的仓库边界内并自动加载核心技能；再顺着它强制引用的 CLAUDE.md，把背后的单文件真相源、插件自动发现机制、CI 同步工作流与测试守护串成一条可复现的链路。读完本文，你可以在自己的多仓库项目中复刻同样的 Agent 入口文件设计，并理解每一项约束在源码与测试中的落地证据。

一、AGENTS.md 是什么：编码 Agent 的自动发现入口

AGENTS.md 是整个仓库中最短的文档之一，全文仅 15 行，但它是为编码 Agent 自动发现机制设计的入口文件。CLAUDE.md 的仓库结构树中明确标注了它的定位与硬约束：

├── CLAUDE.md # This file (maintainer instructions) ├── AGENTS.md / GEMINI.md # Autodiscovery files (must stay at root)

即 AGENTS.md 与 GEMINI.md 是"自动发现文件"，必须留在仓库根目录，移动到其他位置会导致支持该约定的 Agent 无法发现它们。

逐段拆解 AGENTS.md 的原文结构，它由四个部分组成：

1. 强制首句：Read CLAUDE.md before repository work.—— 任何 Agent 在动手改代码前必须先读维护者手册 CLAUDE.md；
2. 绑定路由（Binding routing）：声明本仓库与另外三个仓库的职责边界；
3. 可见性声明（Visibility）：声明四个仓库当前及规划中的公开/私有状态；
4. 四个@文件导入：把核心技能文件直接拉进 Agent 上下文。

第 4 部分原文如下（路径为相对仓库根）：

@./skills/caveman/SKILL.md @./skills/caveman-commit/SKILL.md @./skills/caveman-review/SKILL.md @./skills/caveman-compress/SKILL.md

GEMINI.md 是同一机制的 Gemini CLI 变体，内容为完全相同的四条导入——这正是 caveman 项目"自己吃自己的狗粮"的设计：任何用 Claude Code 或 Gemini CLI 打开本仓库工作的 Agent，会在加载入口文件时自动获得这四个技能的行为规则，而不需要人工粘贴 prompt。

二、绑定路由：用一个文件锁定四个仓库的边界

AGENTS.md 的第二、三段声明了绑定式路由与可见性。这是多仓库产品族中防止 Agent 跨边界误改的关键约定，原文将工作按主题切分到四个仓库：

AGENTS.md 原文为本地路径形式的声明（/Users/.../caveman-agent-sdk等），CLAUDE.md 中给出了对应的上游仓库名：JuliusBrussee/agent-sdk、JuliusBrussee/caveman-coding-agent、JuliusBrussee/caveman-browse。对 Agent 而言，这段的实际语义是路由规则：收到"改 Agent SDK"这类请求时，不应在本仓库里找代码，而应指向对应仓库。

其中一条边界尤其值得注意，CLAUDE.md 在"Repository routing"一节给出补充说明：本仓库的 browse/ 目录是consumer copy（消费方副本）——它仍然构建caveman-browse发布二进制，但源码真相在caveman-browse仓库。因此只允许为"pinned integration、迁移/移除、或明确请求的跨仓库同步"三类理由编辑该目录。这条规则直接约束了 Agent 的日常行为：绝大多数情况下browse/对写入是只读的。

三、@导入的四份技能文件：被注入上下文的压缩行为规则

AGENTS.md 导入的四个 SKILL.md 文件各有一份独立的人类可读 README.md 伴随（CLAUDE.md 强调"面向 LLM 的是 SKILL.md，面向浏览 GitHub 的用户的是 README.md，两者不可合并"）。四份技能的 frontmatter 定位如下：

以核心的 skills/caveman/SKILL.md 为例，@导入意味着 Agent 读到 AGENTS.md 时就把整套行为规则读进了上下文。这份规则定义了六个强度级别：lite、full（默认）、ultra、wenyan-lite、wenyan-full、wenyan-ultra（wenyan 即文言文模式），以及几条可验证的压缩纪律：

• 删除冠词、填充词（just/really/basically）、客套话（sure/certainly/happy to）与对冲表达；允许句子碎片；
• 禁止发明新缩写：cfg/impl/req/res/fn这类自造缩写经 tokenizer 切分后与全词 token 数相同，零节省还损失可读性——"全词更便宜也更清晰"；
• 因果箭头→同样是零节省（占一个 token），禁用；
• not/never/no/only/except永不删除——删掉比省下的任何 token 都更糟；
• Auto-Clarity 规则：遇到安全警告、不可逆操作确认、可能被碎片语序误读的多步序列时，自动退回正常行文，讲清楚后再恢复压缩。

CLAUDE.md 为此专门设立了一条硬规则："Editskills/<name>/SKILL.mdfor behavior changes. Never edit synced copies underplugins/caveman/skills/"——行为变更只改源头技能文件，同步副本由 CI 负责（见第五节）。

四、CLAUDE.md：被 AGENTS.md 强制引用的维护者手册

AGENTS.md 第一句要求先读 CLAUDE.md，因此后文内容同样是这条链路的组成部分：AGENTS.md 是"路由 + 技能注入"，CLAUDE.md 是"工程纪律全文"。

4.1 单文件真相源（Single Source of Truth）

CLAUDE.md 用一张表声明了"只允许编辑这些文件"的清单，摘录核心行：

配套规则是构建产物纪律：构建产物一律进dist/，从不手工提交——CI 在 push 时重建，dist/已被 gitignore（仅!dist/caveman.skill例外，见第五节）。

4.2 插件自动发现：没有 allowlist 的skills/目录

这是 CLAUDE.md 中"最锋利的边"。.claude-plugin/marketplace.json 设置"source": "./"，即插件根就是仓库根，Claude Code 会自动发现每一个skills/*/SKILL.md，plugin.json里没有任何skills键可以拦截它。后果：往 skills/ 下新增任何目录，都会安装进所有插件用户的 Agent，其description会在日常任务中参与激活竞争。CLAUDE.md 的结论是"没有 allowlist。新增目录前先决定它是否该到达终端用户；不该的话放packages/或其他根目录"，并要求以ls skills/为真相源同步文档表格。

同一机制还有两个踩坑记录，均被 tests/verify_repo.py 守住：

• agents/*.md会被整体自动发现为子代理，而 plugin.json 中的agents数组曾在 Claude Code 2.1.235 上加载 0 个代理（claude plugin details报Agents (0)）。因此维护文档必须放在agents/树外，且plugin.json不得重新加回agents键；
• commands/*.md会与同名技能影子冲突。caveman.md等四个与真实技能同名的 3 行 stub 曾与完整规则集竞争同一 slash 命令，已被删除；commands/ 目录现在只保留没有技能孪生的caveman-init.md以及 Codex/Gemini 专用的.tomlstub（.toml不被扫描）。

4.3 各 Agent 的分发机制

CLAUDE.md 用一张表说明 caveman 如何到达每一类 Agent，摘录关键行：

新增 Agent 的规程同样写死在 CLAUDE.md：只改 bin/install.js 的PROVIDERS数组，每个条目含id、label、mech、detect（如command:foo||dir:$HOME/x）、可选profile与soft: true；改完用node bin/install.js --list验证渲染。

4.4 数据纪律：eval 与 benchmark 不允许编造

CLAUDE.md 为数字设立了双保险。evals/ 是三臂 harness：__baseline__（无系统提示）、__terse__（仅Answer concisely.）、<skill>（Answer concisely.+ SKILL.md 全文），且诚实的 delta 定义为 skill 对比 terse，而非 skill 对比 baseline——与 baseline 比会把"技能"和"泛化简洁"混为一谈，harness 的结构就是为了防这一点。benchmarks/ 则用真实 prompt 走 Claude API 记录原始 token 数，结果以 JSON 提交在 benchmarks/results/，README 的 benchmark 表由结果生成。两条配套规则：基准数字必须来自真实运行，"Never invent or round"；新增技能只需放入skills/<name>/SKILL.md，harness 自动发现。

4.5 安全与可靠性纪律（对 Agent 的硬性禁令）

CLAUDE.md 末尾的"Key rules for agents working here"是一组可执行的工程纪律，逐条都有实现或测试背书：

• flag 文件写入必须走safeWriteFlag()（src/hooks/caveman-config.js）：拒绝符号链接目标、支持O_NOFOLLOW、临时文件 + rename 原子写、0600权限——防止本地攻击者把可预测路径替换为符号链接去覆盖用户可写文件；
• 凡进入文件路径的session_id必须先过validateSessionId()（白名单^[A-Za-z0-9_-]{1,128}$），因为 session id 会拼进文件路径，符号链接加固不覆盖路径穿越；
• 所有从 stdin 读 host hook payload 的入口，在第一个完整 JSON 对象处返回，绝不等到 EOF——Windows 管道实现下宿主关闭写端会任意滞后（CLAUDE.md 引 issue #729/#833/#949），等 EOF 的读者会烧光宿主 5 秒预算；caveman-activate.js、caveman-mode-tracker.js等读者各自配有"保持写端打开"的回归测试；
• hooks 必须在一切文件系统错误上静默失败，绝不让 hook 崩溃阻塞会话启动；
• 改 src/hooks/ 下任何文件后必须重算src/hooks/checksums.sha256，否则 tests/verify_repo.py 构建失败，且 bin/install.js 会用该清单校验远程下载的 hook 文件；
• settings.json 读写必须走 bin/lib/settings.js的readSettings()（容忍 JSONC 注释）与写入前的validateHookFields()——Claude Code 的 Zod 会在 schema 不匹配时静默丢弃整个 settings.json，一条坏 hook 不能毒化全文件；
• hooks 必须尊重CLAUDE_CONFIG_DIR环境变量，不得硬编码~/.claude。

五、CI 同步与测试守护：让"只改源头"成立

第三节的"Never edit synced copies"能成立，靠的是 .github/workflows/sync-skill.yml 与 tests/verify_repo.py 的组合。

sync-skill.yml的触发条件（以工作流文件实际内容为准）：push 到main且命中skills/caveman/SKILL.md、skills/cavecrew/SKILL.md、agents/cavecrew-*.md、skills/caveman-compress/SKILL.md、skills/caveman-compress/scripts/**任一路径。流程为：

1. 拷贝skills/caveman/SKILL.md到 plugins/caveman/skills/caveman/ 镜像；
2. 拷贝 caveman-compress 技能及其scripts/（清理__pycache__）到插件镜像；
3. 拷贝skills/cavecrew/SKILL.md与三个agents/cavecrew-*.md子代理到插件镜像；
4. 重建dist/caveman.skill——先rm -f再zip -r，因为zip -r是增量追加，而该 ZIP 被 git 跟踪，不先删除的话从skills/caveman/删掉的文件会永远留在发布包里；
5. 以github-actions[bot]提交并 push，带[skip ci]防止循环。

本地验证端由 tests/verify_repo.py 的verify_synced_files()承担（约 L220-L268）。它的校验强度超过"文件存在"：三份 SKILL 镜像与三个子代理镜像必须与源头逐字节相等；对dist/caveman.skill则同时检查缺失项与多余项——解包内容集合必须与skills/caveman/磁盘文件集合精确一致，从而抓住zip -r增量追加导致的陈旧条目。CI 与本地测试从两端夹住了同一不变量：源头改、镜像跟、包不漂。

安装侧的证据链同样完整：根目录 install.sh 只是约 60 行的 shim——检测 Node ≥ 18，在本地克隆时直接exec node bin/install.js，curl-pipe 路径则委派给npx -y "github:JuliusBrussee/caveman#v3.0.0"（install.ps1 对称）。注释里记录了双源时代的历史教训："install.sh + install.ps1 used to be parallel sources of truth and constantly drifted (issue #249)"——这正是bin/install.js成为唯一安装器真相源的原因。而 hook 在插件形态下的注册内容可对照 .claude-plugin/plugin.json：SessionStart钩caveman-activate.js、UserPromptSubmit钩caveman-mode-tracker.js，均为 command 类型、30 秒超时。

六、小结：AGENTS.md 模式的可复制要点

以 AGENTS.md 为主体的这条链路给出了多仓库 + 多 Agent 项目的入口文件范式：

1. 路由先于内容：入口文件第一段就声明"什么工作属于哪个仓库"，并用 consumer copy 条款锁定本仓库内只读区域，把 Agent 的误改面收敛到最小；
2. 可见性与所有权分离声明：public/private 是披露策略，不影响代码归属判断，分开写避免歧义；
3. @导入替代粘贴：技能规则以@./skills/<name>/SKILL.md形式引用，GEMINI.md 复用同一组导入，规则本体只在skills/下维护一份；
4. 每个纪律都挂一个守护：镜像同步挂sync-skill.yml+verify_repo.py字节级比对，hook 完整性挂checksums.sha256，路径安全挂validateSessionId/safeWriteFlag及其回归测试——文档里的禁令没有一条是"君子协定"。

这套设计的最终效果是：AGENTS.md 保持 15 行的极简，但它指向的 CLAUDE.md、四个 SKILL.md、CI 工作流与测试文件共同构成了一份 Agent 可执行、CI 可验证、可逐条引用文件路径的协作契约。

• 人工智能
• AI 应用
• AI 技能
• AI 插件
• LLMOps
• 开发工具