agence

l'Agence — Agentic Engineering Co-Environments

作者：Stephane Korning · 2026 · MIT + Commons Clause
版本：v1.0.0 · 2026 年 5 月

AI 编码 Agent 的治理层。
无论由哪个大模型或工具执行，每个 Agent 操作都会分类、把关并进行加密记录。

---

问题

你的 AI 编码 Agent 能编写代码，也能提交、推送、删除和重构。

但谁在监督它们？

Claude Code 没有审计跟踪。Aider 信任用户。Codex 会把所有内容都放进沙箱，并寄希望于一切顺利。LangChain 提供了构建模块，却没有护栏。

Agence 的存在，是因为建议性的护栏根本算不上护栏。它位于任何 AI Agent 与你的文件系统之间，并明确表示：“未经批准，不得操作。”

---

Agence 的功能

Agence 是一套面向软件工程的与 Agent 无关的治理技术栈。它不会取代你的编码 Agent，而是通过单一控制平面统一治理、编排并审计所有 Agent。

命令把关 — 每条 Shell 命令都会在执行前分类：

层级	把关方式	示例
T0	自动执行	git status、ls、cat
T1	记录日志	git add、git commit
T2	需要人工批准	git push、git reset
T3	禁止执行	rm -rf、chmod 777、kill

未知命令默认归为 T2，而不是 T0。**默认拒绝。**守卫作为独立进程运行，Agent 无法绕过自身的策略。

加密审计 — 每个 Agent 决策都会记录到由 Merkle 链连接的只追加账本中。每条记录都通过 SHA-256 链接到上一条。篡改任何一条记录都会破坏链。使用以下命令验证：agence ^ledger verify。

多 Agent 编排 — 18 个 Agent，分属 4 种类型（persona、tool、loop、ensemble）。使用 @agent 语法路由。使用点表示法覆盖模型：@ralph.gpt4o。可将任务分发给 Aider、Claude Code、Copilot 或你自己的工具，全部由同一策略治理。

同行共识 — 将任何问题路由给 3 个独立的大模型，并获得加权共识。架构评审不应受限于单个模型的盲点。

会话持久化 — 保存、恢复会话，并在 Agent 之间移交会话。完整上下文可在重启后保留。自动通过 tmux 捕获 stdout/stdin/stderr，不受 16KB 缓冲区限制。

原生支持 Git — 不需要数据库，也不需要服务端。状态存储在 Git 工作树和纯文本文件中。知识经过分片、把关并选择性路由，由你决定共享哪些内容。

---

数据一览

30,701	行生产代码（23.9K 行 TypeScript + 6.8K 行 bash）
751	项测试，包含 21 个文件中的 1,768 条断言
279	安全专项测试（guard + hardening + SEC 回归测试）
9	已完成的红队测试周期（SEC-008 至 SEC-019）
33+	编排技能（^fix、^review、^hack、^peers、^vault……）
18	已注册 Agent（10 个 persona、5 个 tool、1 个 loop、2 个 ensemble）
12	大模型提供商（Anthropic、OpenAI、Azure、Google、Mistral、Groq、Ollama……）
10	MCP 工具 + 3 个 MCP 资源（Model Context Protocol 服务）
3	依赖项总数（MCP SDK、Bun、Zod）
0	所需数据库数量

---

适用人群

• 使用多个 AI 编码 Agent 的团队，需要一套统一策略来治理所有 Agent
• 企业，需要审计 AI 生成代码的变更记录
• 注重安全的开发者，需要默认拒绝的把关机制，而不是默认放行的信任机制
• 曾遇到 AI Agent 搞坏东西，并希望 Agent 与 rm -rf 之间有一层防护的人

不适用人群

• 如果你想要 AI 结对编程助手 → 使用 Aider
• 如果你想要 IDE 自动补全 → 使用 Continue 或 Copilot
• 如果你想要构建各种 Agent → 使用 LangChain/LangGraph
• 如果你想要云端托管的异步任务 → 使用 OpenAI Codex

Agence 治理上述所有工具。

---

GitHub Action — Agence Guard

在任何 CI 工作流中管控 AI Agent 命令——只需一个步骤，无需基础设施：

- name: Gate AI command
  id: guard
  uses: l-agence/agence@v1
  with:
    command: 'git push origin main'   # command proposed by your AI agent
    agent: ci
    fail_on_block: 'true'             # fail if T3-blocked

- run: echo "Tier ${{ steps.guard.outputs.tier }} — ${{ steps.guard.outputs.reason }}"

输入	描述	默认值
command	要分类的 Shell 命令	必填
policy	自定义 AIPOLICY.yaml 的路径（相对于仓库）	内置策略
agent	用于 MLS 能力检查的 Agent 身份	ci
fail_on_block	T3（拒绝）时退出码为 1	true
fail_on_escalate	T2（需要审批）时退出码为 1	false

输出	值
tier	T0 · T1 · T2 · T3
action	allow · flag · escalate · deny
reason	人类可读的决策说明
rule	匹配的策略规则

完整文档请参阅 docs/marketplace/description.md。

本 PR 首先推出 GitHub Action 方案，便于各仓库快速采用；GitHub App 上架及 Webhook 服务可在后续阶段或单独的 PR 中推出，以支持在组织层面推广到多个仓库。

对于企业采用，在 GitHub App 之后的下一层是 分片接入，让组织能够清晰地划分团队、策略和知识边界，而不是被迫采用单一共享分片模式。

---

安装

作为 Git 子模块（推荐）

git submodule add https://github.com/l-agence/agence .agence
git submodule update --init --recursive
bash .agence/bin/agence ^init
export PATH="$PWD/.agence/bin:$PATH"

或：直接克隆

git clone https://github.com/l-agence/agence .agence
cd .agence && bun install
./bin/agence ^init
export PATH="$PWD/.agence/bin:$PATH"

先决条件

工具	必需	安装
bash 4+	是	Linux/macOS/WSL 内置
git 2.30+	是	sudo apt install git
bun 1.3+	是	bun.sh
tmux	用于 swarm	sudo apt install tmux
jq	用于查询账本	sudo apt install jq

Windows：请使用 WSL（推荐 Ubuntu）。

---

快速开始

# Chat with an agent
agence "How should I structure this feature?"

# Route to a specific agent
agence @sonya "Review this auth module"

# Launch an agent shell
agence !ralph                    # Persona: autonomous iteration
agence !claude                   # Tool: Claude Code CLI
agence !aider                    # Tool: aider (code patches)

# Save session (resume later or hand off to another agent)
agence ^save "OAuth2: done token validation, next: refresh flow"
agence ^resume
agence ^handoff @sonya

# Audit trail
agence ^ledger verify            # Verify Merkle chain integrity
agence ^audit trail              # View full decision history

# Peer consensus (3 independent LLMs)
agence @peers "Should we use Redis or Postgres for session storage?"

# See all commands
agence --help

---

架构

YOUR REPO/
└── .agence/                     ← lives here (submodule or clone)
    ├── bin/                     # CLI: agence, aibash, ibash, aido, agentd
    ├── codex/                   # Governance: AIPOLICY.yaml, Laws, Principles, agents/
    ├── nexus/                   # Local state: .ailedger, sessions, faults (gitignored)
    ├── knowledge/               # Team knowledge: docs, lessons, plans (committed)
    │   └── private/             # Private knowledge (gitignored, never shared)
    ├── organic/                 # Swarm coordination: tasks, jobs, workflows
    └── lib/                     # Core: guard.ts, signal.ts, skill.ts, memory.ts, peers.ts

COGNOS — 四大支柱：

支柱	用途	位置
CODEX	不可变治理——法律、原则、规则、AIPOLICY	codex/
KNOWLEDGE	团队共享文档、经验、计划——通过 @ 符号链接选择性路由	knowledge/
NEXUS	本地运行状态——会话、账本、信号	nexus/（已加入 gitignore）
ORGANIC	Swarm 编排——任务、工作流、矩阵调度	organic/

运行时：Bun + bash。不使用 Python。不使用 pip。关键路径中不通过 npm 安装不可信的软件包。

MCP：Agence 将自身作为 MCP 服务公开（10 个工具、3 个资源），以便任何兼容 MCP 的客户端都能使用 agence 的治理层。Agence 也可作为 MCP 客户端，使用外部 MCP 服务提供的工具。集成指南请参阅 MCP.md。

---

命令参考

前缀	模式	示例	适用场景
(none)	聊天	agence "explain this error"	建议、解释、问答
^	知识	agence ^save、agence ^lesson	共享状态、知识操作
~	私有	agence ~note "idea"	私有笔记（绝不提交）
+	自主	agence +refactor-auth	Agent 规划并执行任务
/	已验证	agence /git-status	预先批准的安全命令
!	系统	agence !ralph、agence !claude	启动 Agent 或工具
@	路由	agence @sonya "review this"	发送给指定 Agent

---

Agent 名册

Agent	类型	最适用场景
@ralph	循环	带反压的自主迭代
@sonya	人设	架构、代码审查
@claudia	人设	深度推理、关键决策
@chad	人设	DevOps、基础设施、CI/CD
@aleph	人设	红队、安全分析
@claude	工具	Claude Code CLI（无头启动）
@aider	工具	代码补丁、git 差异
@pilot	工具	GitHub Copilot CLI
@peers	集成	3 个大模型加权共识
@pair	集成	2 个大模型轻量级共识

使用点号表示法覆盖模型：@ralph.gpt4o、@sonya.opus、@ralph.aider

---

治理

Agence 使用 5 级命令策略。守卫作为独立进程运行，Agent 无法绕过自身策略。

级别	控制方式	示例
T0	自动执行	git status、ls、cat
T1	记录日志	git add、git commit
T2	需人工批准	git push、git reset
T3	禁止执行	rm -rf、chmod 777
T4	永不允许	强制推送 main、删除数据库

未知命令默认归为 T2。默认拒绝。 涵盖 git、GitHub CLI、AWS、Terraform 和 shell 的 120 多条规则。

所有决策均记录到 nexus/.ailedger——仅追加、采用 Merkle 链、经 HMAC 签名。

完整的安全架构、红队发现和披露时间线，请参阅 SECURITY.md。

---

Swarm（agentd）

agentd start ralph claude aider   # Launch 3 agents in tmux
agentd tangent create fix-auth    # Isolated worktree + container
agentd inject fix-auth "run tests"  # Send command via socat socket
agentd status                     # View all agents + tangents

每个分支任务都配有：隔离的 git 工作树、可选的 Docker 容器（--cap-drop ALL、--read-only、--no-new-privileges）、用于 IPC 的 socat 套接字，以及用于观察运行情况的 tmux 面板。

---

测试

bun test                          # Full suite

751 项测试、1,768 条断言，21 个文件中有 0 项失败：

测试套件	测试数	覆盖范围
guard.test.ts	132	命令控制、级别升级、eval 安全性
security-hardening.test.ts	134	HMAC、信号伪造、注入防护、SEC-010→019 回归测试
memory.test.ts	62	COGNOS 三存储：保留／回忆／缓存／遗忘／提升／提炼
peers-dispatch.test.ts	53	同伴共识、混合路由
queue.test.ts	42	工作队列、仪表板、GitHub Issues 桥接
runs.test.ts	35	SWE 运行生命周期、聚合、结果
vault.test.ts	20	Hermetic vault 初始化／同步／推送／拉取 + SEC-019 安全性
setup.test.ts	10	交互式向导、转义、验证
mcp-client.test.ts	10	MCP 客户端守卫控制、环境清理
mcp.test.ts	10	MCP 工具／资源接口验证
sequent.test.ts	12	锦标赛分支任务、CLI 调度

---

文档

文档	内容
架构	端到端系统设计
Swarm	agentd、分支任务、tmux 模型
命令	完整的 CLI 参考
安全	TCB、红队发现、披露时间线
教程	入门指南
设置	详细安装指南

---

许可证

MIT + Commons Clause——可免费使用、修改和自托管。
商业再分发需另行签订协议。
请参阅 LICENSE.md。

---

由 Stephane Korning 构建。经 5 轮红队测试加固。由自身的 CODEX 治理。