如何快速向 OpenCollab 贡献代码：四层架构、依赖规则与自定义工具/工作流开发完整指南-平芜编程栈

【免费下载链接】OpenCollab

A research-friendly, high-performance multi-agent collaboration coding framework.

项目地址：https://gitcode.com/gh_mirrors/op/OpenCollab

OpenCollab 是一个研究友好的高性能多智能体协作编码框架，核心 harness 代码不足 5 万行，却能在多个编码基准上超越 Claude Code、Codex CLI 和 OpenHands，并拿下了 OAIC Agentic Software Factory 黑客松第一名 🏆。想为它贡献代码？关键不在于写得多快，而在于先读懂它的四层架构和依赖方向规则——只要守住这条边界，你的 PR 就能顺利通过lint-imports和 CI 检查。

项目速览：OpenCollab 是什么

OpenCollab 提供三种可编程的协作模式：

Team 模式：用 YAML 声明每个角色的提示词、模型、工具与 token 预算，以及谁能给谁发消息；
Workflow 模式：用纯 Python 函数编排每一次交接，内置的 Duo 双码者工作流就是这样实现的；
可验证运行：--trace会为每个步骤写入一条 JSONL 记录（run、agent、role、事件类型、token 用量），让"声明的协作是否真的发生"变得可度量。

下面这张架构图展示了从任务规格（task/model/prompts/topology/budget）到会话循环（Precheck → Model → Response → Tools → Autosave）、再到评估指标（Z、A、Y、C 与 Adherence）的完整链路，是理解贡献代码前必读的一张图：

开发环境一键配置步骤

贡献前先准备好本地环境，全部基于uv管理：

git clone https://gitcode.com/gh_mirrors/op/OpenCollab cd OpenCollab uv sync --locked --extra dev # 创建 .venv，安装运行 + 开发依赖 cp configs/.env.example configs/.env # 填入 OPENCOLLAB_API_KEY

⚠️ 注意：永远不要把真实 API key 提交进仓库。本地测试套件不需要联网凭据，只有 live 运行才需要。

四层架构：代码该放在哪一层

OpenCollab 遵循严格的 Clean Architecture，依赖只允许向内指：

adapters → application → domain

各层职责一览（源自 CONTRIBUTING.md）：

层	目录	职责	规则
领域层	opencollab/domain/	纯值对象 + 会话 FSM	只用标准库，不做任何 I/O
应用层	opencollab/application/	用例、调度器、端口	只依赖`domain`和标准库
适配层	opencollab/adapters/	CLI、TUI、LLM 供应商、工具、环境、追踪	依赖内层，不反向暴露
组合根	opencollab/bootstrap/	唯一认识具体类型的层，负责接线	运行时装配入口

另有两条边界：

opencollab/sdk/ 是面向外部工作流与评测包的版本化公共边界；
公共模块（opencollab.tools、opencollab.workflows等）绝不能直接摸到adapters或domain。

新人最常犯的错：想让domain里直接用某个 LLM SDK——不行。正确姿势是：在application/ports.py里定义一个**端口（port）**表达这个能力，再到bootstrap/里把具体实现接上去。这样内层保持纯净，测试也能轻松替换依赖。

依赖方向规则：lint-imports 是怎么把关的

架构契约写死在 .importlinter 里，CI 会强制执行，任何"由内向外"的导入都会让构建失败。当前共有 4 份契约：

layers：bootstrap > adapters > application > domain的层级顺序（含 CLI 的少量保留例外）；
domain-stdlib-only：禁止domain导入openai、anthropic、typer、pydantic、yaml等任何第三方库；
public-surface：opencollab.sdk、profiles、models、tools、environments、workflows等公共模块禁止导入adapters或domain；
no-sibling-cycles：同层兄弟模块之间不允许形成循环导入。

本地自测命令：

uv run lint-imports # 架构契约检查

💡 拆分模块时，记得把公共名字重新导出，保持既有导入路径稳定。会话不变量的设计依据见 docs/runtime-design.md。

自定义工具开发指南：实现 Tool 协议即可

应用级工具无需继承任何适配器基类，只要实现公开的 Tool 协议（定义在 opencollab/tools.py），然后通过OpenCollab.agent(tools=[...])或工作流角色的tools=参数传入。契约要求提供：

name、description：工具身份；
parameters：JSON Schema 描述接受的参数；
default_timeout、disable_outer_timeout：超时策略；
to_openai_schema()：转换为 OpenAI 函数调用格式；
异步execute_with_runtime(params, runtime)：执行并返回字符串。

最小示意（完整示例见 opencollab/README.md 的 Custom tools 一节）：

class ProjectPolicy: name = "project_policy" description = "Look up the project's test command for a language." # ... parameters / to_openai_schema() ... async def execute_with_runtime(self, params, runtime): return "python -m pytest -q"

要点提醒 📌：

执行状态作用域限定在单次调用内；需要访问环境时，使用框架注入的runtime，不要假设调用方主机目录；
同一批次内工具名必须唯一；
要贡献框架内置工具，则放在 opencollab/adapters/tools/ 下，并在 opencollab/bootstrap/tool_registry.py 注册工厂，同时给角色配置显式工具列表，而不是扩大所有人的权限。

自定义工作流开发指南：一个 @workflow 起步

工作流就是一个带@workflow装饰器的普通 async Python 函数。把它放进workflows/目录（或用OPENCOLLAB_WORKFLOWS_DIR指定其他目录），CLI 与 SDK 都会自动发现：

uv run opencollab workflow run implement-and-review \ --args '{"task": "Add a regression test for the target bug."}'

编写思路（完整可运行版本见 opencollab/README.md 的 Workflow authoring 一节）：

用ctx.agent(prompt, tools=..., timeout=...)发起每一步交接；
用ctx.diff()、ctx.log()、ctx.tokens_spent()获取证据与统计；
可复用的框架行为走公共 API；基准评分与远程执行留给 OpenCollab-Eval，别混进来。

想看社区级别的真实案例，推荐这两个示例：

examples/mini-edict/README.md：仅239 行team + workflow 代码，复刻了约 2.4 万行的多智能体协作协议；
examples/member-authored-workflow/README.md：团队成员在运行期自行编写并启动工作流的完整演示。

协作是否真的按声明发生，OpenCollab 用运行轨迹来回答。下面这张图对比了"已解决"与"未解决"两种典型运行：左侧 Adopter 按时采纳 Coder A 的提交并通过评分，右侧 Adopter 自己一直忙到预算耗尽，最终失败——这正是测试与 trace 机制要守护的行为边界：

PR 提交前的四条命令与提交规范

提交前在仓库根目录跑完这四条，全部绿了再推（详见 CONTRIBUTING.md）：

uv run ruff check . # 全仓 lint uv run lint-imports # 架构契约 uv run deptry . # 依赖卫生 uv run pytest -q # Python 测试套件

测试按行为分组，定位相关用例很方便：

目录	覆盖行为
tests/agents/	单体会话、回合与完成
tests/workflows/	团队、拓扑、消息、调度与工作流
tests/tools/	工具、文件、Shell、Git 与可执行证据
tests/runtime/	供应商、环境、取消、上下文、存储与追踪
tests/interfaces/	CLI、TUI 与公共 SDK 入口
tests/packaging/	架构、仓库所有权与分发

聚焦运行示例：uv run pytest -q tests/tools，或用节点 ID 精确到单个用例。

其他硬性约定：

✅ 新行为必须带测试，套件必须保持全绿；
✅ 提交与 PR 标题使用 Conventional Commits（feat/fix/refactor等前缀），且标题和描述必须用英文，CI 会拒绝 PR 标题中的中文正文；
✅ 修改已有中文翻译的英文文档时，同一 PR 内更新NAME.md与NAME.zh-CN.md两份，可本地执行python3 scripts/check_doc_translations.py origin/main HEAD自查；
✅ 单文件新增不得超过 512,000 字节，Python 模块超过 800 行会收到警告，建议按职责拆分。