企业官网建设流程全解析

headcount如何防止智能体越权？agent-guard写面守卫脚本与CI强制校验原理完整拆解

【免费下载链接】headcountAn agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.项目地址: https://gitcode.com/gh_mirrors/hea/headcount

headcount 是一个把 Claude Code 智能体组织成"公司"结构的开源项目：16 个部门、143 个技能，每个部门可独立安装。当多个智能体并行工作在同一仓库时，如何防止某个智能体越权写入不属于自己的文件？headcount 的答案是：一份叫"写面地图"的 Markdown 清单，加上一个零依赖的守卫脚本 agent-guard.mjs，并在 CI 中每次推送强制校验。本文完整拆解这套"智能体防越权"机制的设计原理与实现细节。

为什么按"主题"划分会让智能体失控

最直觉的做法是按主题分工："一个智能体管 SEO，一个管 UI"。但两者最终都会改到同一个tokens.css——谁都没错，谁也说不清谁覆盖了谁的工作。碰撞是静默的，往往表现为合并冲突，甚至是一个智能体默默回滚了另一个的工作。

headcount 的方法论只有一句话：按"写面"（write surface）拆分，而不是按主题拆分。核心问题永远不是"这个智能体擅长什么"，而是"这个智能体允许写哪些文件"。回答不了第二个问题，这个智能体就不该存在。

写面地图：一份文件同时是文档和配置

整个机制的地基是 docs/AGENT-SURFACES.md，一个普通的 Markdown 文件，内嵌两类代码块：

• roster块：登记每个智能体的 id、类别、状态和权限等级
• surface:<id>块：逐行列出该智能体可写的 glob 路径，!前缀表示排除

```roster executive builder installed autonomous repo-meta builder installed proposes security-review reviewer installed autonomous

这种"可读即文档、可解析即配置"的设计保证只有一个事实源——两个文件必然互相漂移，一个文件不会。 [![headcount智能体组织架构图：CEO、16个部门与两个独立只读的审核者智能体](https://raw.gitcode.com/gh_mirrors/hea/headcount/raw/1f3f550826c0dcabe7b70ad0ad76953d4ff22a98/docs/assets/org-chart-light.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/71330d6a129dbe90689e1d91b51328a0) ## 两类智能体 + 三级权限：越权在结构上不可能 地图把智能体严格分成两类，**协调者（主会话）不属于任何一类，它是唯一有权提交的人**： | 类别 | 能写什么 | 能提交吗 | 并行安全 | |---|---|---|---| | **builder**（构建者） | 只能写自己独占的写面 | 永远不能 | 写面不重叠时安全 | | **reviewer**（审核者） | 什么都不写，永久只读 | 永远不能 | 总是安全 | "builder 永远不提交"是真正生效的控制：一个物理上无法提交的智能体，就不可能落地任何协调者没读过的东西。 写面回答的是"在哪写"，但没回答"这个写入能否不经人工决策就落地"。为此每个 roster 行还带一个**权限等级**（authority），源码中定义为三种（见 [agent-guard.mjs#L45-L49](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L45-L49)）： - `autonomous`（自主）：派工直接取结果，写面就是唯一的闸门 - `proposes`（提案）：可以做工作，但提交前协调者必须把 diff 摆出来 - `escalates`（升级）：不主动派发，工作本身就是决策 本项目 18 行 roster 几乎全是 `autonomous`，唯一的例外是 `repo-meta`——因为它拥有 CI 工作流、校验脚本和这份地图本身：改错一个部门的插件最多毁掉一个部门，改错 `scripts/check-all.sh` 会让所有其他检查静默失效。这就是"权限要按爆炸半径分配"的实例。 ## check 命令原理：证明地图自身是可靠的 运行 `node agent-guard.mjs check`，脚本对 `git ls-files` 的每个文件逐条断言： 1. **每个文件有且只有一个属主**（[agent-guard.mjs#L185-L205](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L185-L205)）——两个属主是未来的冲突，零属主更糟：谁先碰它谁就默默成了属主 2. **roster 与 charter 双向一致**（[agent-guard.mjs#L207-L221](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L207-L221)）——没有 roster 行的 charter 可以写任何地方；标着 `planned` 但 charter 已存在的行是谎言 3. **reviewer 不持有任何写面**（[agent-guard.mjs#L223-L230](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L223-L230)）——只读必须是结构性的，不是 charter 里的一句承诺 4. **权限与写面自洽**（[agent-guard.mjs#L232-L246](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L232-L246)）——给没有写面的 builder 加闸门、给根本不写的 reviewer 加闸门，都属于"看起来受治理、实际治理了空集" 5. **决策日志编号唯一**——两个并发会话同时认领 `D14` 在 git 里能干净合并、什么都不报错，这正是它需要脚本而非约定的原因 另外，匹配不到任何文件的 glob 会以提示（而非失败）报出：可能是重命名遗留，也可能是在目录存在前合法地预留了写面。 注意一个刻意的工程决策：glob 匹配器是**手写的**（[agent-guard.mjs#L51-L86](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L51-L86)），不引入任何依赖——在一个职责就是"执行规则"的文件上，多一个依赖就多一次供应链审查。 ## diff 命令原理：在归属信息消失前抓住越权 `check` 只能证明地图自洽，无法证明某次改动遵守了地图——协调者一旦提交，"哪个 hunk 出自哪个智能体"的信息就永远丢失了。所以必须有第二个守卫，趁归属信息还在时运行：

node agent-guard.mjs diff

它的流程（[agent-guard.mjs#L302-L346](https://link.gitcode.com/i/f8192849694925dd497ab7f436b664d4#L302-L346)）： 1. 从 `git status --porcelain` 取出工作区改动路径（或 `--base <ref>` 对比某个引用） 2. 对 builder：落在自己写面内的路径直接放行；**落在外面的路径按"真正属主是谁"分组报出**——这个分组本身就是交接路由信息，告诉你该把这批文件交给哪个部门 3. 对 reviewer：任何改动路径都是违规 4. 全部干净但该行是 `proposes`/`escalates` 时，额外提醒：提交前必须先摆出 diff 做决策 两个命令缺一不可：`check` 管地图的"现在"，`diff` 管每次派工的"这一手"。 ## CI 强制校验：让规则真正执行 headcount 有一句核心信条：**散文规则不会执行**。一份写在 Markdown 里从不检查的写面地图只是建议；每次 PR 都被检查的地图才是控制。 执行链路只有两环： - CI 工作流 [.github/workflows/checks.yml](https://link.gitcode.com/i/1b530c08661b6082c1d5ba88e7c02d7c) 在每次 push 和 PR 时运行 `./scripts/check-all.sh`，并显式声明 `contents: read` 只读权限，防止宽松默认配置把写 token 递给外部 fork 触发的工作流 - [scripts/check-all.sh](https://link.gitcode.com/i/99b88734a02e8ca50fa27c880ed83f87) 把"本地跑"和"CI 跑"统一为同一个入口，第一项检查就是 `agent-guard.mjs check`，后面跟着技能 frontmatter 校验、溯源检查、README/社交卡片/组织架构图一致性、美国英语拼写等——任何一项失败即整个 PR 挂掉 本地有一个必须知道的坑：`git ls-files` 看不见未跟踪的文件。新加一个路径到写面、建了文件、本地跑 check，会通过——因为文件没被 `git add`，碰撞只在 CI 里才现形。所以规矩是：**先 `git add`，再跑 check**。 ## 快速上手清单 想在自己的仓库复刻这套防越权机制，完整方法在 [agent-hierarchy 技能](https://link.gitcode.com/i/12c54bb8d6a9988f15b27580c71a59a3) 及其 415 行的[playbook](https://link.gitcode.com/i/f4775193e2c83a9fe42cacd303064df9) 中，顺序不可颠倒： 1. 盘点真实目录树，先看有什么再提方案 2. 提出最小 roster：任何两个智能体不共享文件；写面没法用 glob 说清楚的"智能体"，并入别的 3. 写写面地图，一个 Markdown 文件，roster 行 + surface 块，排除行（`!`）是诚实的地图里最重的部分 4. 接入守卫：`check` 进 CI，`diff` 在每次 builder 提交前运行 5. 最后才写 charter；给每个 builder 配一个没有写过该内容的独立 reviewer ## 小结 headcount 防越权的精髓不是禁止清单，而是把"越权"变成**一个必然失败的 CI 检查**：写面地图定义边界，`check` 保证边界自洽，`diff` 在归属消失前拦截越界写入，`repo-meta` 的 `proposes` 权限保证"看门人"自己改门也要有人点头。规则一旦被脚本执行，智能体组织才第一次从"约定"升级为"控制"。 完整方法论见 [plugins/executive/skills/agent-hierarchy/references/playbook.md](https://link.gitcode.com/i/f4775193e2c83a9fe42cacd303064df9)，决策记录实例见 [docs/DECISION-LOG.md](https://link.gitcode.com/i/d756ec5b549cce02f1441db9b2153716)。

【免费下载链接】headcountAn agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.项目地址: https://gitcode.com/gh_mirrors/hea/headcount