Agent Conductor

Agent Conductor

输入 AGENTS.md，输出受治理的 Agent 团队。

Agent Conductor 是一款 MCP 服务，可将编码 Agent 生态已趋于一致的两项约定——AGENTS.md 操作手册和 SKILL.md 技能——从被动文档转变为主动编排层，并通过经过共识加固的决策引擎把关高风险变更。

• 镜像仓库： codeberg.org/cubiczan/agent-conductor · github.com/icohangar-ops/agent-conductor
• 许可证： MIT
• 状态： v0.1 — 可运行的脚手架；请参阅路线图

---

问题

如今，每款严肃的 Agent 工具——Claude Code、Cursor、Copilot、Codex、Gemini CLI——都会读取仓库根目录中的 AGENTS.md 和一组 SKILL.md 文件。但这两项约定都只是基于信任的文字说明：

• 没有任何机制编译契约。不可妥协的规则、层级边界和验证清单都以 Markdown 形式存在，Agent 可能会，也可能不会将其内化。
• 没有任何机制把关决策。即将重写评分模型的 Agent，和仅仅重命名变量的 Agent，采取行动时拥有同等程度的把握。
• 没有任何机制验证清单是否已执行。“交接前运行 npm test”只是一条建议，并非关卡。

Conductor 让这些约定变得可执行，而且无需任何 Agent 工具做出改动。它以标准 MCP 服务的形式提供，因此任何支持 MCP 的工具都能免费获得契约编译、技能发现和决策把关功能。

工作原理

MCP client (Claude Code / Cursor / Copilot / ...)
        │  stdio (JSON-RPC, MCP)
        ▼
┌────────────────────────────────────────────────┐
│ TypeScript front end (src/)                    │
│   contract/parser.ts   AGENTS.md → contract    │
│   contract/workspace.ts Multi-root merge       │
│   skills/loader.ts     SKILL.md discovery      │
│   server.ts            7 MCP tools             │
└────────────────┬───────────────────────────────┘
                 │  newline-delimited JSON, child stdio
                 ▼
┌────────────────────────────────────────────────┐
│ Python decision engine (engine/)               │
│   vendored Consensus Hardening Protocol core   │
│   R0 gates · foundation attacks · lifecycle    │
└────────────────────────────────────────────────┘

三组功能：

1. 契约——将 AGENTS.md 编译为结构化的任务使命、不可妥协的规则、层级边界（允许与禁止）、验证关卡、技能建议和范围外清单。
2. 技能——跨项目和个人作用域发现 SKILL.md 技能，并采用渐进式披露：元数据约占 100 个 token，只有在需要时才加载正文。
3. 决策——通过共识加固协议把关工作：开始工作前先进行低成本的 R0 合理性检查；高风险变更锁定前，再执行对抗式基础攻击检查。

快速开始

要求：Node 23+（原生运行 TypeScript）和 Python 3.9+（仅使用标准库——引擎无需安装 pip 包）。

git clone https://codeberg.org/cubiczan/agent-conductor.git
cd agent-conductor
npm install
npm test            # TypeScript tests (parser, skills, multi-root, live engine bridge)
npm run test:engine # Python bridge protocol tests
npm run build

在 Claude Code 中注册：

claude mcp add agent-conductor -- node /path/to/agent-conductor/dist/index.js

或者在任何 MCP 客户端的 JSON 配置中：

{
  "mcpServers": {
    "agent-conductor": {
      "command": "node",
      "args": ["/path/to/agent-conductor/dist/index.js"]
    }
  }
}

如果你的 Python 3 不在 python3 路径下，请设置 CONDUCTOR_PYTHON。

然后，在任何包含 AGENTS.md 的项目中：

“加载此项目的 Agent 契约，列出其验证关卡，并对我即将进行的变更运行一次 decision_adversary 检查。”

工具参考

contract_load

将 AGENTS.md（或 CLAUDE.md）编译为结构化契约。接受文件路径、项目目录、显式的 roots 列表或 rootsFile 映射；默认使用当前工作目录。多根工作区会生成一份契约，其中的层级表和验证命令会合并。此工具不会提供章节正文，以便调用方遵守渐进式披露预算（仅包含元数据和结构化字段）。

// input
{ "path": "examples/pipeline-pulse" }

// output (abridged — real output from the bundled example)
{
  "source": "examples/pipeline-pulse/AGENTS.md",
  "title": "AGENTS.md — Pipeline Pulse CRM",
  "mission": "Pipeline Pulse CRM is a lightweight, local-first pipeline review dashboard...",
  "rules": [
    "Deterministic logic — same inputs → same scores, labels, and summaries...",
    "Logic in crm.js — keep main.js thin (fetch, render, events).",
    "... (6 total)"
  ],
  "layers": [
    { "layer": "src/crm.js", "role": "Domain logic",
      "do": "Deterministic scoring, filtering, summaries", "dont": "DOM manipulation" }
  ],
  "gates": [
    { "name": "Code change checklist", "commands": ["npm test"], "notes": "" },
    { "name": "Before completion", "commands": [], "notes": "npm test — all green...\n..." }
  ],
  "skills": [
    { "task": "CRM scoring / forecast changes", "skill": "obra/test-driven-development",
      "url": "https://github.com/obra/superpowers/...", "why": "Tests-first changes to deterministic logic" }
  ],
  "outOfScope": ["External CRM integrations (Salesforce, HubSpot, etc.)", "..."],
  "sectionCount": 28
}

解析器具有无损性：无法识别的章节会原样保留，因此不会丢弃非传统 AGENTS.md 中的任何内容。

contract_verification

仅返回验证关卡——必须在交接工作前通过的命名检查清单和 shell 命令。将其与 Agent 的工作流配合使用：运行命令、确认成功，然后宣布完成。接受与 contract_load 相同的单根或多根输入。

skills_list

发现从项目根目录或已声明的多根工作区可见的 SKILL.md 技能。仅包含元数据。当额外源根目录出现在根目录列表或映射中时，也会纳入模块目录之外的额外源根目录。

// input
{ "projectRoot": "examples/pipeline-pulse" }

// output
{
  "skills": [
    {
      "name": "pipeline-scoring",
      "description": "Explain and modify scoreDealRisk weights in src/crm.js with matching test updates...",
      "version": "0.1.0",
      "scope": "project"
    }
  ]
}

搜索顺序（每个技能名称以首次命中为准）。在多根工作区中，项目级路径会针对每个已声明的根目录依次搜索，然后个人级路径只搜索一次：

优先级	路径	范围
1	<root>/.conductor/skills/*/SKILL.md	项目
2	<root>/.claude/skills/*/SKILL.md	项目
3	<root>/.cursor/skills/*/SKILL.md	项目
4	~/.claude/skills/*/SKILL.md	个人
5	~/.cursor/skills/*/SKILL.md	个人

skill_load

加载指定技能的完整 SKILL.md 正文——渐进式披露中按需加载的部分。仅当任务符合该技能的描述时才调用。

decision_gate

Consensus Hardening Protocol R0 gate：成本最低、杠杆效应最高的检查，应在开始工作之前执行。

// input
{ "solvable": true, "scoped": false, "valid": true, "worth_it": true }

// output
{ "verdict": "HALT", "results": { "Solvable": "PASS", "Scoped": "FATAL", "Valid": "PASS", "Worth_it": "PASS" } }

任何 FATAL 答案都会终止流程：先停下来重新界定问题，再继续处理，以免在范围不明、未理解或不值得解决的问题上浪费令牌。

decision_adversary

针对高风险变更进行一次对抗性审查：CHP 会质疑主张的基础，以 0–100 分评分，并返回反方意见调查结果及会话状态。

// input
{
  "claim": "Change scoreDealRisk stale-activity weight from 20 to 30",
  "context": "Tests updated; label distribution checked against fixture"
}

// output
{
  "status": "EXPLORING",          // or HALT / REFRAME_REQUIRED
  "foundation_score": 77,
  "findings": [
    "Treat every financial number as unverified until tied to source data.",
    "Require explicit flip criteria for any provisional recommendation."
  ],
  "verification_failures": ["PENDING third-party validation"],
  "report": "## TriangulationRunner Adversary Pass\n..."
}

状态对应 CHP 决策生命周期 （EXPLORING → PROVISIONAL_LOCK → LOCKED，另有 HALT 和 REFRAME_REQUIRED 退出状态）：EXPLORING 表示主张经受住了质疑，工作可以继续推进并最终锁定；HALT/REFRAME_REQUIRED 表示基础未通过检验。

engine_status

对 Python 引擎子进程进行健康检查。返回 { ok, engine: "chp", version }。

解析器识别的内容

contract_load 基于约定而非模式。它会提取实际 AGENTS.md 文件中常用的模式：

合约字段	来源约定
mission	第一个 Mission / Purpose / Overview 章节
rules	Non-negotiables > Engineering rules > 通用 rules 下的列表项（按优先级排序，因此通用的“Product rules”章节不会覆盖明确的不可妥协项）
layers	架构类标题下，第一个包含 Layer 列的表格
gates	清单 / 验证 / 完成前标题下的 Shell 代码块和列表项
skills	包含 Task / Skill / Why 列的表格；链接会解析为文本 + URL
outOfScope	范围外 / 非目标标题下的列表
sections	所有内容，原样保留——无损回退方案

代码围栏中的标题会被忽略；表格标题中的强调格式可以正常解析； 提取文本时会去除 Markdown 链接和强调格式。

编写技能

技能是一个包含带 YAML frontmatter 的 SKILL.md 的目录：

---
name: pipeline-scoring
description: Explain and modify scoreDealRisk weights in src/crm.js with matching test updates. Use when changing deal risk scoring, risk labels, or forecast thresholds.
version: 0.1.0
tools: [Read, Edit, Bash]
---

# Pipeline Scoring

Step-by-step instructions the agent follows when the task matches...

质量标准（继承自 awesome-agent-skills 标准）：使用便于匹配关键词的第三人称描述，元数据约 100 个令牌，正文少于 500 行，不使用特定于机器的绝对路径，只声明技能所需的工具。

内置示例：

• examples/pipeline-pulse — 完整的真实 AGENTS.md 和项目级技能（单根目录编译）。
• examples/multimodule — Gradle 风格的额外源根目录：技能位于 shared/ 下，在 modules/billing 之外。

单体仓库指南

简单的加载器只会遍历指定的目录。这会导致与 Gradle 模块的相同问题：当 sourceSet 指向模块之外（srcDirs = ['src/main/java', '../shared/src']）时，额外的目录树虽然是真实的工作内容，却不在模块目录中。

请声明所有额外的根目录。如果缺少某个根目录，Conductor 会以失败关闭——它不会自行臆造根目录，也不会悄悄跳过。

1. 编写 roots 映射

规范位置（优先采用第一个命中项）：

文件	使用时机
.conductor/roots.json	与 .conductor/skills 位于同一目录
conductor.roots.json	仓库根目录下的便捷位置
.conductor/roots / conductor.roots	按行列出的替代格式

JSON 对象（ID 可选）：

{
  "roots": [
    { "id": "workspace", "path": "." },
    { "id": "billing", "path": "modules/billing" },
    { "id": "shared", "path": "shared" }
  ]
}

路径的 JSON 数组：

[".", "modules/billing", "shared"]

按行列出的映射（允许使用 # 注释）：

workspace: .
billing: modules/billing
shared

相对路径以映射文件所在目录为基准解析。

2. 将技能保留在额外的根目录中

examples/multimodule/
├── conductor.roots.json
├── AGENTS.md                    # workspace layers + `npm test`
├── modules/billing/AGENTS.md    # module layers + `npm -C modules/billing test`
└── shared/.conductor/skills/shared-ledger/SKILL.md

单独的 modules/billing 无法看到 shared-ledger。声明映射后，skills_list 和 skill_load 会遍历所有根目录，然后遍历个人作用域，并按优先命中项生效的规则处理遮蔽。

3. 调用工具

// Auto-detect a roots map under a directory
{ "path": "examples/multimodule" }

// Explicit list (relative paths resolve against `path` or cwd)
{ "path": "examples/multimodule", "roots": [".", "modules/billing", "shared"] }

// Explicit map file
{ "rootsFile": "examples/multimodule/conductor.roots.json" }

contract_load 仍只返回摘要，不包含章节正文；contract_verification 仍只返回门禁；skills_list 仍返回 frontmatter 元数据。没有映射文件的单根项目（包括 examples/pipeline-pulse）会继续使用之前的编译路径。

项目结构

.
├── AGENTS.md                  # This repo's own contract (compiles with itself)
├── ARCHITECTURE.md            # Design decisions and component detail
├── src/
│   ├── index.ts               # stdio entrypoint
│   ├── server.ts              # MCP server: 7 tools
│   ├── contract/              # AGENTS.md → AgentContract compiler (incl. multi-root)
│   ├── skills/                # SKILL.md loader + registry
│   ├── engine/chpBridge.ts    # Python engine client
│   └── utils/logger.ts        # stderr-only logging (stdout is the transport)
├── engine/
│   ├── bridge.py              # JSON-over-stdio request router
│   ├── test_bridge.py         # protocol tests
│   └── vendor/cme/            # vendored CHP core (MIT, byte-identical; see NOTICE.md)
├── examples/pipeline-pulse/   # real AGENTS.md fixture + example skill
├── examples/multimodule/      # extra source root (skills outside the module)
└── test/                      # node:test suites (run the .ts directly)

开发

npm test            # TypeScript tests — includes a live engine round-trip
npm run test:engine # Python-side protocol tests
npx tsc --noEmit    # type check
npm run build       # emit dist/
npm run dev         # run the server from source (Node type stripping)

项目规约（完整内容见本仓库自己的 AGENTS.md）：

1. stdout 至关重要——它由 MCP 传输层占用；桥接两端的所有日志都输出到 stderr。
2. 不新增运行时依赖——仅使用 @modelcontextprotocol/sdk 和 zod；Markdown 和 frontmatter 解析均手工实现并经过测试。
3. 仅使用可擦除的 TypeScript——源码必须能在 Node 的类型擦除模式下运行（不使用枚举或参数属性）。
4. 依赖管理纪律——engine/vendor/cme/ 除文档注明的 __init__.py 补丁外，必须与上游逐字节保持一致；引擎行为变更应放在 bridge.py 中。

合约验证 CLI（第 21 项：可执行合约）

支撑 contract_load 的同一解析器也通过 CLI 子命令提供，因此 CI 可以以失败即关闭的方式编译 AGENTS.md，并（可选）运行其中声明的验证门禁：

agent-conductor verify AGENTS.md                  # compile; exit 0/1
agent-conductor verify --require-gates AGENTS.md  # also fail when the contract
                                                  # declares no gates (anti-placeholder)
agent-conductor verify --run-gates AGENTS.md      # run every declared gate
                                                  # command; exit 1 on failure

--run-gates 会将“读取合约”变为“执行合约”：AGENTS.md 中的清单 shell 代码块将成为 CI 步骤。本仓库自己的 CI 也以此方式编译自己的 AGENTS.md——模式的源项目会用自身实践该模式。

门禁执行的信任策略。 --run-gates 只会执行命令行传入的单个合约文件中的门禁命令——CLI 使用单文件解析器（loadContract）编译该文件，不会合并其他工作区根目录中的门禁。如需在多根工作区中实施约束，请在 CI 中为每个根目录运行一次 CLI（本仓库的 CI 正是如此）。作为库使用时，工作区编译器（src/contract/workspace.ts）会合并所有已声明根目录中的门禁；该接口信任所有已声明根目录，不提供按根目录筛选或提示功能，因此只能将它指向你完全信任的根目录。单条命令的超时时间（默认 120s）可限制进程挂起，但无法阻止恶意行为。

Skills 锁定（第 23 行：供应链纪律）

项目可以在项目根目录的 skills-lock.json 中固定其信任的 Skills：

{
  "version": 1,
  "skills": {
    "pipeline-scoring": {
      "path": ".conductor/skills/pipeline-scoring/SKILL.md",
      "sha256": "<hex digest of the SKILL.md bytes>"
    }
  }
}

存在锁定文件时，skill_load 会在验证失败时拒绝加载：系统会计算 SKILL.md 字节的哈希（SHA-256），并与固定的摘要进行比对；如果缺少条目、文件遭到篡改或哈希已过期，就会拒绝加载，并抛出一个列出技能名称和两个摘要的 SkillLockError。发现阶段（仅 frontmatter）仍未经验证——威胁边界在于技能内容进入 Agent 的时刻。没有锁定文件 → 行为不变（通过提交锁定文件选择启用验证）。

威胁模型说明——锁定文件涵盖和不涵盖的内容。

• 摘要涵盖整个 SKILL.md 文件，包括 frontmatter：对 frontmatter（描述、工具列表）的任何编辑都会改变摘要，skill_load 会因哈希不匹配而失败，直到更新锁定文件。在发现时，元数据从不单独验证——在加载前按 description 选择技能的路由器会读取未经验证的 frontmatter（在没有锁定文件的根目录中，完全不会进行验证）。元数据与正文的边界属于 API 层面，而非文件层面：锁定文件通过对字节进行哈希来保护两者；这种区分仅描述哪些使用方会在验证前读取哪一部分。
• 锁定解析按根目录进行。loadSkill 会根据技能所属根目录（包含其路径的允许根目录）中的 skills-lock.json 验证技能。在多根工作区中，没有各自锁定文件的根目录会加载未经验证的技能；不同根目录的锁定文件不会合并。这与合约规范编译有意不同，后者会先合并已声明根目录中的各层，并采用首次匹配优先规则——不要假设一个根目录中的锁定文件能覆盖其他根目录的技能。

立即采用锁定文件。 目前还没有 lock generate 子命令（计划实现：运行 agent-conductor lock generate，遍历 .conductor/skills/ 并使用验证器所用的同一 computeLockEntry 生成或更新 skills-lock.json）。在此之前，请手动编写锁定文件，并通过 shasum -a 256 SKILL.md（或 openssl dgst -sha256）对确切的 SKILL.md 字节固定摘要——摘要涵盖整个文件，包括 frontmatter。

路线图

版本	主题	范围
v0.2	强制执行	将 contract_verification 门禁作为真正的子进程执行，并返回通过/失败证据——将“读取合约”变为“强制执行合约”——已在 0.2.0 发布，交付范围为 CLI：agent-conductor verify --run-gates <AGENTS.md>（以及用于反占位符门禁的 --require-gates）。contract_verification MCP 工具仍会列出门禁，但不会执行——会话内执行证据不属于 0.2.0；在将带副作用的执行引入 MCP 接口前，需要明确的用户同意/沙盒模型
v0.3	编排	将合约层映射到 CHP MeshAgent 能力（produces/consumes），并通过 MCP 提供完整的多 Agent 审议会话
v0.4	注册表	通过来源审查提示词，从远程目录（awesome-agent-skills 格式）安装经过审核的技能

来源

Conductor 会刻意复用经过验证的组件，而非重新编写：

组件	来源	许可证
决策引擎（engine/vendor/cme/）	consensus-hardening-protocol	MIT
MCP 服务 + 注册表结构	onchainmind	MIT
技能质量标准	VoltAgent/awesome-agent-skills	—
示例 fixture	Pipeline Pulse CRM 操作手册	fixture

有关 vendoring 详情，请参阅 engine/vendor/NOTICE.md；有关双语言设计背后的原因，请参阅 ARCHITECTURE.md。

许可证

MIT — 详见 LICENSE。vendored 组件保留其原有的 MIT 许可证。