ConPact：基于文件系统的多智能体协作协议设计与实战-编程阁

1. 项目概述：为什么我们需要一个多智能体协作协议

在AI驱动的软件开发领域，像Claude Code、Codex、OpenClaw这样的编码智能体正变得越来越强大。它们能独立完成代码生成、重构、调试等任务。但当我们尝试让多个这样的智能体在同一项目中协同工作时，混乱就开始了。想象一下，你让Claude去写一个API接口，同时让Codex去优化数据库查询，结果它们都去修改了同一个配置文件，或者都认为自己应该处理用户认证逻辑。最终，你得到的不是高效协作，而是代码冲突、重复劳动和大量被浪费的算力与Token。

这正是ConPact项目要解决的核心痛点。它不是一个全新的AI模型，而是一个协调层，一个基于文件系统的、结构化的“契约协议”。它的核心思想非常直接：把智能体之间的协作，从临时的、模糊的指令，变成明确的、可追踪的“合同”。就像在现实项目中，产品经理给工程师提需求不会只靠口头沟通，而是会有一份清晰的需求文档（PRD）和任务工单（Ticket）。ConPact就是把这种工作流带入了多智能体协作的世界。

我最初接触这个想法，是在尝试用Claude Code和Codex接力完成一个微服务模块时。我需要手动在它们之间复制粘贴上下文，提醒A“B已经改了这里”，告诉B“A的接口定义是这样的”。整个过程笨拙、易错，且完全无法规模化。ConPact的出现，相当于为智能体们建立了一个共享的、带状态管理的任务看板（Kanban）。任何智能体都可以发布任务（创建合同），其他智能体可以认领、执行、提交，最后由发布者审核。所有状态都通过JSON文件固化在项目目录中，对任何智能体都可见、可操作。

它的名字也很有意思：Contract（合同） +Pact（协议/协定），同时谐音Compact（紧凑的），完美概括了其设计哲学——用轻量、紧凑的协议实现可靠的协作。

2. 核心设计思路：基于文件系统的去中心化状态机

ConPact的设计摒弃了复杂的中央服务器或消息队列，选择了一个极其朴素却无比可靠的基石：本地文件系统。这个选择背后有深刻的考量，也是其能保持“框架无关”的关键。

2.1 为什么是文件系统，而不是中心化服务？

首先，复杂度与依赖最小化。一个中心化的协调服务需要部署、维护、处理网络通信和并发。而文件系统是每个开发环境、每个智能体工具链都天然具备的。使用文件系统作为状态存储，意味着ConPact几乎可以零成本地集成到任何工作流中，无需额外的基础设施。

其次，状态持久化与可追溯性。所有合同（Contract）都以JSON文件的形式存在。这不仅是状态存储，更是一份完整的审计日志。你可以随时查看某个任务是如何被创建、认领、更新和完成的。如果协作出现问题，你可以直接检查这些JSON文件来定位问题，就像查看Git日志一样。

第三，真正的去中心化（Peer-to-Peer）。没有主控节点。任何一个智能体，只要它能读写项目目录，就能参与到协作中。智能体A可以给智能体B派活，智能体B也可以反过来给A派活。这种对等网络结构非常灵活，能适应各种动态的团队组成。

注意：这里的“去中心化”指的是协调逻辑的去中心化，而非数据存储。所有合同文件仍然存储在一个共同的、可访问的文件系统位置（通常是项目根目录下的.agents/文件夹）。因此，确保所有协作智能体对该目录有读写权限是前提。

2.2 合同的生命周期与状态机

ConPact将一次协作任务抽象为一个“合同”，这个合同的生命周期由一个严格的状态机来管理。这是整个协议可靠性的核心保障。

合同的状态流转如下图所示（用文字描述其逻辑）：一个合同被创建后，初始状态为assigned（已分配）。被指定的智能体可以将其状态改为in_progress（进行中），表示已开始工作。工作完成后，状态变为submitted（已提交），等待审核。审核者（通常是创建者）可以将其closed（关闭）表示接受，或者打回为revision_needed（需要修订），后者会将其状态重置回in_progress。

这个状态机被硬编码在协议中，每一次状态变更（通过对应的工具调用）都会进行验证。例如，你不能将一个assigned状态的合同直接close，也不能将一个closed的合同重新claim。这种强制性的流程确保了协作的纪律性，防止了状态混乱。

2.3 原子写入与并发安全

当多个智能体可能同时操作同一个合同时，如何避免文件损坏？ConPact采用了“原子写入”策略。它并不是一个复杂的分布式锁，而是利用文件系统操作的最佳实践。

在更新一个合同文件时，协议的实现会遵循以下步骤：

将更新后的完整内容写入一个临时文件（例如contract.json.tmp）。
确保数据成功写入磁盘（调用操作系统的fsync或类似机制）。
将临时文件原子性地重命名（rename）覆盖原合同文件。

在大多数现代操作系统中，rename操作是原子的。这意味着在任何其他进程（智能体）看来，合同文件要么是完全旧版本，要么是完全新版本，永远不会看到一个写入一半的损坏状态。这是一种简单而有效的并发控制机制，足以应对智能体协作场景下的写入冲突（因为高频并发写入在此场景下并不常见）。

3. 协议实战：从零搭建一个多智能体协作项目

理论说得再多，不如亲手跑一遍。下面我将带你完整地走一遍使用ConPact协调Claude Code和Codex两个智能体，共同开发一个简单功能的流程。我们假设项目是一个Python的待办事项（Todo）API。

3.1 环境准备与协议安装

首先，你需要一个支持MCP（Model Context Protocol）的客户端。这里我们以Claude Desktop（集成了Claude Code）和Cursor（集成Codex）为例。ConPact本身是一个MCP服务器。

步骤1：克隆与安装ConPact在你的项目根目录下，或者在一个全局的Python环境中安装ConPact。

# 克隆仓库（假设你从GitHub获取） git clone <conpact-repo-url> cd ConPact # 以可编辑模式安装，方便后续修改或查看源码 pip install -e .

安装成功后，你会得到一个名为conpact_server的Python模块。

步骤2：在Claude Code中注册ConPact服务器对于Claude Desktop，你需要编辑其MCP配置。配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或类似位置。

{ "mcpServers": { "conpact": { "command": "python", "args": ["-m", "conpact_server"] } } }

保存并重启Claude Desktop。现在，Claude Code就具备了调用ConPact所有工具的能力。

步骤3：在Codex/Cursor中配置对于Cursor，配置方式可能不同，但原理一致。你需要在Cursor的MCP设置中，添加一个指向python -m conpact_server的服务器配置。具体路径请参考Cursor的文档。配置成功后，Codex也能使用相同的协议工具。

3.2 项目初始化与智能体注册

现在，进入你的Todo API项目目录。

步骤1：项目初始化在Claude Code的聊天窗口中，你可以直接告诉它：“请使用ConPact工具初始化本项目。” 或者，更具体地，它应该调用：

/conpact_init

这个命令会在你的项目根目录下创建一个.agents/文件夹，里面包含基本的目录结构（contracts/,registry.json等）。这标志着本项目已启用多智能体协作协议。

步骤2：智能体身份注册每个参与的智能体都需要一个唯一的ID。这通常在智能体“加入”项目时完成。

在Claude Code的上下文中，调用：

/conpact_register agent_id="claude-code"

在Codex的上下文中，调用：

/conpact_register agent_id="cursor-codex"

registry.json文件会记录这些注册信息。虽然协议不强制要求注册，但这是一个好的实践，有助于在合同中清晰标识各方。

3.3 创建第一个协作合同：设计数据库模型

假设我（作为人类开发者或主控智能体）想让Claude Code来设计数据模型，然后让Codex基于这个模型实现对应的CRUD API。

步骤：Claude Code创建合同我在Claude Code中下达指令：“为Todo项目创建一个合同，指派给cursor-codex，目标是创建Todo项的SQLAlchemy模型。” Claude Code会调用conpact_create工具，我需要提供关键信息：

{ "assignee": "cursor-codex", "objective": "设计并实现Todo项目的SQLAlchemy数据模型。", "boundaries": "仅关注数据模型定义，位于 `models.py` 文件中。不涉及API路由或业务逻辑。", "references": ["项目使用Python 3.9+，SQLAlchemy 2.0，数据库为SQLite。"], "acceptance_criteria": [ "1. 模型类名为 `TodoItem`。", "2. 包含字段：id (主键, Integer), title (String, 非空), description (Text, 可选), completed (Boolean, 默认False), created_at (DateTime)。", "3. 使用SQLAlchemy的Declarative Base。", "4. 包含清晰的文档字符串。" ] }

调用成功后，在.agents/contracts/目录下会生成一个类似@cursor-codex.abc123.json的文件。这就是我们的“合同”。文件名包含了受托方（assignee）和唯一ID。

3.4 执行与交付：Codex认领并完成任务

现在，切换到集成了Codex的Cursor IDE。

步骤1：检查待办合同Codex可以主动查看分配给自己的任务。调用：

/conpact_check agent_id="cursor-codex"

工具会返回所有状态为assigned且指定给cursor-codex的合同列表。它看到了我们刚创建的那个。

步骤2：认领合同Codex决定处理这个任务，调用：

/conpact_claim contract_id="abc123"

这个操作会将合同状态从assigned变为in_progress。同时，Codex应该在本地更新合同文件中的diligence部分，记录开始时间，或者任何初步计划。

步骤3：执行工作并更新进度Codex开始编写models.py。在编写过程中，如果遇到问题（比如不确定某个字段类型），它可以调用conpact_update来更新diligence部分，记录一个“阻塞项”（blocker），这相当于向任务发布者（Claude Code）提问或请求澄清。

// 在diligence部分更新 "blockers": ["请问`created_at`字段是否应该设置为自动生成当前时间？"]

Claude Code那边可以通过conpact_read查看合同更新，并直接修改合同文件中的delegation.references或新增说明来回答。

步骤4：提交成果Codex完成models.py的编写后，调用conpact_submit来交付。

{ "contract_id": "abc123", "summary": "已成功创建TodoItem模型，包含所有指定字段，并添加了__repr__方法。", "files_changed": ["models.py"], "verification_steps": ["运行了 `alembic revision --autogenerate` 成功生成迁移脚本。"], "result_content": "..." // 可选，可以附上生成的关键代码片段 }

提交后，合同状态变为submitted。

3.5 审核与闭环：Claude Code进行验收

任务回到Claude Code这里。

步骤1：审核提交Claude Code调用conpact_review来审核Codex提交的工作。

{ "contract_id": "abc123", "decision": "accept", // 或 "request_revision" "feedback": "模型定义符合要求，文档字符串清晰。感谢！", "suggestions": [] // 如果需要修订，这里可以给出具体修改建议 }

如果选择accept，合同状态会变为closed，整个协作流程圆满结束。合同文件会被移动到.agents/contracts/_archive/目录下存档。如果选择request_revision，合同状态会变回in_progress，并附带审核反馈，Codex需要根据反馈继续修改。

至此，一次完整的、结构化的多智能体协作就完成了。整个过程有迹可循，责任明确，避免了口头传达的歧义和遗忘。

4. 合同文件深度解析：你的协作蓝图

合同文件是ConPact的灵魂，它是一个结构清晰的JSON文档。理解每个部分的用途，对于编写有效的合同和进行高效的协作至关重要。

4.1 合同结构详解

一个完整的合同包含四个主要部分，每个部分承载了协作流程中不同阶段的信息。

1. Delegation（委托）这是任务的“需求说明书”，由合同创建者填写。它的质量直接决定了后续协作的顺畅程度。

objective（目标）：用一句话清晰说明要做什么。切忌模糊。对比“优化代码”（模糊）和“将函数process_data的运行速度提升20%，同时保持输出结果不变”（清晰）。
boundaries（边界）：明确限定工作范围。什么该做，什么不该做。例如：“只修改utils/helper.py文件中的calculate_score函数，不改变其公开接口，不涉及其他模块。”
references（参考）：提供上下文。可以是文件路径、文档链接、代码片段、对话记录等。为执行者提供充足的“弹药”。
acceptance_criteria（验收标准）：可衡量的、具体的完成条件。最好以列表形式呈现，便于逐项核对。例如：“1. 通过所有现有单元测试。2. 新增3个边界条件测试用例。3. 代码复杂度（Cyclomatic Complexity）低于10。”

2. Diligence（勤勉）这是执行者的“工作日志”，用于跟踪进度和沟通障碍。

progress_updates：一个数组，记录关键进展节点和时间戳。例如：“[‘2023-10-27T10:00:00Z: 已完成初步设计’， ‘2023-10-27T14:30:00Z: 已实现核心算法’]”。
blockers：遇到的阻碍列表。这是最重要的沟通渠道。执行者应尽早、具体地提出阻碍。例如：“[‘需要确认用户表的索引策略’， ‘第三方API的文档缺失第5章节’]”。创建者应定期查看并回应这些阻碍。

3. Result（结果）这是执行者的“交付物报告”。

summary：对所做工作的文字总结。
files_changed：列出所有被创建、修改或删除的文件路径。这对于审核者快速定位变更至关重要。
verification_steps：执行者是如何验证自己的工作是正确的。例如：“[‘运行了pytest tests/，全部通过’， ‘手动测试了新增的API端点，返回符合预期’]”。这大大增强了交付物的可信度。
result_content：（可选）可以直接嵌入关键的产出物，比如生成的配置代码、设计图等，方便在不直接查看文件的情况下进行初步审核。

4. Discernment（审辨）这是审核者的“验收报告”。

review_feedback：审核意见。
decision：accept或request_revision。
suggestions：如果要求修订，这里给出具体的、可操作的修改建议。

4.2 编写高质量合同的技巧

根据我的经验，一份糟糕的合同会让协作效率减半。以下是一些实战心得：

从模板开始：为不同类型的任务（如“创建模块”、“修复Bug”、“重构代码”、“编写测试”）创建合同模板，预先填好通用的boundaries和acceptance_criteria格式。
验收标准必须可验证：避免使用“性能更好”、“代码更优雅”这类主观描述。使用“P95延迟降低50ms”、“代码覆盖率提升至85%”、“通过flake8检查且无错误”等客观指标。
善用References：不要假设执行者知道所有背景。把相关的需求文档、设计图、之前的讨论链接、甚至是一段失败的代码片段，都作为Reference附上。信息越充分，执行者的理解偏差就越小。
鼓励频繁更新Diligence：告诉执行的智能体，每完成一个子任务或遇到任何不确定，就更新一下progress_updates或添加blockers。这比最后提交时才发现方向错了要好得多。

5. 高级用法与集成模式

ConPact的基础流程很简单，但在复杂项目中，我们可以利用其灵活性构建更强大的协作模式。

5.1 链式协作与工作流编排

一个任务的输出可能是另一个任务的输入。ConPact可以轻松编排这种链式工作流。

场景：我们需要一个数据处理管道：A智能体从API拉取原始数据并清洗，B智能体进行分析并生成报告，C智能体将报告可视化。

人类或主控智能体创建合同C1给A，目标是“清洗API X的数据，输出为cleaned_data.json”。
A智能体在提交C1的result中，将cleaned_data.json作为产出。
在A提交C1后，一个自动化脚本（或另一个智能体）可以监听合同关闭事件，然后自动创建合同C2给B，其objective为“分析cleaned_data.json”，并在references中直接引用C1合同ID或产出文件路径。
B智能体完成分析，提交报告。同样，可以触发创建合同C3给C，进行可视化。

通过将合同ID和文件路径作为references传递，智能体之间就形成了清晰的数据流和依赖关系。

5.2 与版本控制系统（Git）的协同

ConPact的合同文件是纯JSON，非常适合纳入版本控制（如Git）。这带来了两个巨大好处：

协作历史追溯：所有的任务分派、进度更新、审核意见都随着代码一起被Git记录。你可以通过git log看到不仅是代码谁改了，还能看到为什么改（对应的合同目标是什么），以及审核过程是怎样的。
分支与合同：你可以在不同的Git分支上运行不同的合同集。例如，在feat/auth特性分支上，所有关于认证功能的智能体协作合同都只在这个分支上创建和执行。合并分支时，代码和其背后的协作历史一并合并。

最佳实践：将.agents/目录添加到你的.gitignore文件中，但将.agents/contracts/_archive/目录排除在忽略规则之外。这样，只有已关闭的、有最终结果的合同会被提交到仓库，作为项目文档的一部分。而进行中的合同和本地注册信息则保留在本地，避免冲突。

5.3 自定义工具与协议扩展

ConPact提供了12个核心MCP工具，但你的团队可能需要更多。由于其开源和模块化的设计，扩展是可行的。

例如，你可以创建一个新的MCP工具conpact_metrics，它读取_archive目录下的所有合同，生成团队效率报表：每个智能体的平均任务完成时间、合同驳回率、常见阻碍类型等。这为优化协作流程提供了数据支持。

另一个扩展方向是集成外部系统。编写一个工具，当合同状态变为submitted时，自动在你的团队聊天工具（如Slack）中发送通知，并附上合同链接，提醒审核者及时处理。

6. 常见问题、排查技巧与避坑指南

在实际使用中，你肯定会遇到一些问题。下面是我在多次实践中总结出的常见坑点和解决方案。

6.1 合同状态卡住或出错

问题现象	可能原因	排查步骤与解决方案
无法`claim`合同	1. 合同ID错误。 2. 合同当前状态不是`assigned`。 3. 调用`claim`的智能体ID与合同`assignee`不匹配。	1. 使用`conpact_list`查看所有合同，确认正确的ID和状态。 2. 使用`conpact_read`仔细查看合同详情，确认`assignee`字段。 3. 如果是`assignee`错误，可以使用`conpact_reassign`工具（如果协议版本支持）重新指派，或者由创建者关闭旧合同，创建新合同。
无法`submit`合同	1. 合同状态不是`in_progress`。 2. 执行`submit`的智能体不是当前合同的认领者。	1. 确认合同状态。只有认领者才能提交。如果状态异常，直接检查JSON文件中的`state`字段。 2. 这是一个状态机保护机制，确保权责一致。请用正确的智能体ID操作。
`review`时决策无效	`decision`字段值错误。只接受`accept`或`request_revision`。	检查调用`conpact_review`时传入的JSON参数，确保`decision`字段拼写完全正确。

核心排查心法：当工具调用失败时，第一时间直接查看对应的合同JSON文件。95%的问题都能通过文件内容找到原因。状态、指派人、历史记录都在里面。

6.2 智能体间的沟通低效

问题：执行者遇到阻碍，但不更新blockers，而是闷头瞎猜，最后提交的结果不符合预期。
解决：在合同模板的delegation部分或项目规范中明确要求：“遇到任何不确定性或阻碍，必须在2小时内更新到合同的diligence.blockers字段中。” 将主动沟通作为强制流程。
问题：审核者的反馈过于模糊，如“代码需要优化”，让执行者无从下手。
解决：培训或提示审核者，在discernment.suggestions中必须提供具体的、可操作的建议。例如：“calculate函数中的循环可以改为列表推导式，见第45行。” 或者 “请为User类添加__repr__方法。”

6.3 文件系统权限与路径问题

问题：智能体报告“找不到合同文件”或“权限被拒绝”。
解决：
1. 统一工作目录：确保所有智能体的“当前工作目录”都是项目的根目录。在IDE或脚本中启动智能体时，要设置好正确的路径。
2. 检查.agents/目录权限：确保运行智能体的用户账户对该目录有读写和执行权限。
3. 使用绝对路径：在合同references或result中提及文件时，考虑使用相对于项目根目录的路径（如src/models.py），而非绝对路径，以增强可移植性。

6.4 性能与规模化考量

合同数量爆炸：在大型活跃项目中，contracts/目录下可能有数百个合同文件，list或check操作可能会变慢。
- 应对：ConPact本身很轻量，文件操作通常很快。如果真遇到性能问题，可以考虑定期将已关闭的合同归档到其他存储（如数据库），但会牺牲一部分可追溯性。更简单的办法是鼓励及时关闭合同，并利用_archive目录。
大文件作为Reference：将巨大的代码文件或数据集内容直接粘贴到合同的references里会使得JSON文件臃肿不堪。
- 应对：references应该是指向信息的指针，而不是信息本身。使用文件路径、Git commit hash、文档URL、或内部知识库链接。例如：“references”: [“参见设计文档：https://...”, “相关代码：src/legacy/old_module.py (函数foo)”]。

7. 与其他多智能体框架的对比与选型思考

ConPact并非市场上唯一的多智能体协调方案。理解它的定位，有助于你在正确场景选择它。

vs. AutoGen, CrewAI 等“重型”框架：

AutoGen/CrewAI：它们提供了一套完整的、编程式的框架来定义智能体角色、编排复杂的对话和工作流。你需要写Python代码来搭建整个系统，功能强大，但学习成本和集成复杂度较高。
ConPact：它更偏向于一个轻量级的通信协议和状态管理库。它不关心智能体内部如何思考，只关心它们之间任务交接的“接口”和“状态”。你可以用任何能调用MCP工具的东西（Claude Code, Codex，甚至是你自己写的脚本）作为智能体。它的优势是简单、无侵入、与现有工具链无缝结合。
选型建议：如果你需要构建一个高度自动化、流程固定的多智能体应用（如自动客服系统、数据分析流水线），AutoGen可能更合适。如果你的需求是让几个现有的、你日常使用的AI编码助手（Claude, Cursor, GPT Engineer）在同一个软件项目里更好地协同工作，避免混乱，那么ConPact的简洁性将是巨大优势。

vs. 简单的共享提示词或上下文窗口：

有些人尝试通过在一个超长的提示词中给多个AI分配角色，或者在一个聊天窗口中@不同AI来协作。这种方法极其脆弱，上下文容易丢失，状态无法持久化，几乎无法管理复杂任务。
ConPact通过文件系统持久化状态，提供了结构化的输入（合同）和输出（结果），使得协作过程可中断、可恢复、可审计。这是质的飞跃。

ConPact的适用场景总结：

中小型软件开发团队，希望将AI助手纳入开发流程，并让它们有序协作。
个人开发者，同时使用多个AI工具（如Claude + Cursor），希望管理它们的工作，避免任务遗漏或冲突。
作为更复杂智能体系统的底层协调层，你可以用AutoGen来定义智能体行为，但用ConPact来管理它们之间的任务交接和状态，各取所长。

在我自己的使用中，ConPact最大的魅力在于它的“无感”集成。我不需要改变我使用Claude或Cursor的习惯，只需要在需要协同时，多打一两条/conpact命令。它就像在混乱的协作现场拉了一条清晰的分工线，立了一块任务看板，成本极低，效果立竿见影。它可能不会解决所有多智能体协作的问题，但它用一种极其优雅的方式，解决了其中最基础、最烦人的“秩序”问题。