openJiuwen 系统架构与社区贡献指南：从五层能力体系到 PR 门禁全流程

• 文档
• 开源治理

openJiuwen 是一个开源 Agent 平台，覆盖 AI Agent 从开发、运行到部署运维的完整生命周期。本文基于社区仓库中的 Contribution_guidance_zh.md 展开，完整梳理其五层系统架构、模块化代码仓布局，并结合社区贡献规范、CLA 签署流程、SIG 治理结构与 CI 门禁机制，给出一条可直接照做的参与贡献路径。

什么是 openJiuwen

openJiuwen 致力于提供灵活、强大且易用的 AI Agent 开发与运行能力。基于该平台，开发者可以快速构建处理各类简单或复杂任务的 AI Agent，实现多 Agent 协同交互，高效开发生产级可靠的 AI Agent；同时助力企业与个人快速搭建 AI Agent 系统或平台，推动商用级 Agentic AI 技术的广泛应用与落地。

需要特别说明一点合规边界：本产品仅作为流程编排工具，不包含 AI 模型能力；用户在连接 AI 模型用于特定业务场景时，需自行承担欧盟 AI 法案等相关合规义务。

系统架构：五层能力体系

openJiuwen 采用分层架构设计，整体由DeepAgents、Agent Studio、Agent Framework、Agent Distributed Runtime、Agent System Service五个部分组成，自顶向下分别对应"智能体应用、可视化开发、核心框架、分布式运行时、系统服务"五层能力：

• DeepAgents：提供面向不同场景的复杂智能体，如 JiuwenSwarm、JiuwenSymbiosis、DeepSearch 等，支持开箱即用。
• Agent Studio：一站式 AI Agent 开发平台，提供低代码 / 零代码可视化开发能力，支持 Agent 开发、工作流编排、Prompt 调优、在线调试和资源管理，帮助开发者快速打造和调试智能体及工作流。
• Agent Framework：openJiuwen 核心框架与执行引擎，为开发者提供多场景、易用的 Agent 开发、编排与调用接口。覆盖复杂任务规划、循环执行、工具与技能调用、上下文管理、记忆子系统、多智能体协同、Agent 自演进、算力亲和调度等关键特性，全面支撑单体 Agent 到多 Agent 协同的工程化落地。
• Agent Distributed Runtime：提供分布式 Agent 运行时底座，支持低码、高码两种智能体部署模式，实现 Agent 一键发布部署与全生命周期统一管控。原生内置多租户资源隔离、服务弹性扩缩容、统一注册发现、跨集群高速互通等核心能力，全面支撑大规模多 Agent 集群稳定运行、业务规模化落地。
• Agent System Service：AgentOS 底层基础系统服务，内置系统级安全隔离沙箱、全局统一记忆持久化存储、原生 CLI 系统工具、标准化 Agent 文件系统、跨 Agent 通信总线等底层核心能力，支撑全平台智能体安全运行、资源统一调度与多 Agent 高效协同。

实现概览：模块化仓库设计

openJiuwen 采用模块化仓库设计，逐层构建 AI Agent 开发生态。各仓库可独立演进，也可组合使用，覆盖从智能体应用、技能分发、可视化编排、框架开发到服务化运行的完整链路。

代码仓总览

代码仓背后的 SIG 组织结构

从源码结构看，社区仓库中的sigs/目录以"一个 SIG 对应一个目录"的方式组织治理信息：sig-agent-core、sig-agent-core-java、sig-agent-gateway、sig-agent-infer、sig-agent-memory、sig-agent-plugin、sig-agent-protocol、sig-agent-runtime-java、sig-agent-solution、sig-agent-studio、sig-agent-tools、sig-agentos-enterprise、sig-deepsearch、sig-iCode、sig-jiuwenswarm、sig-jiuwensymbiosis、sig-model-router、sig-skillhub等目录与上表中的代码仓一一对应。

每个 SIG 目录下都有一份sig-info.yaml，声明该 SIG 的名称、职责、成熟度（mature_level，当前多为startup）、Maintainer 名单以及所辖仓库（repositories）与 Committers。例如 sig-agent-core/sig-info.yaml 声明其负责管理openJiuwen/agent-core仓库；sig-jiuwenswarm/sig-info.yaml 声明其管理openJiuwen/jiuwenswarm仓库并列出十余名 Committers；sig-skillhub/sig-info.yaml 则管理openJiuwen/skillhub。这意味着：你想给某个仓库贡献代码，先找到对应的 SIG，联系其 Maintainer，是最高效的参与路径。

如何参与贡献

前置条件：行为准则、许可证与 CLA

在提交任何贡献之前，需要完成三件事：

1. 遵守行为准则。openJiuwen 是开源社区，参与贡献前请先阅读并遵守 openJiuwen社区行为准则.md。根据 社区章程，社区项目维护者有权利和义务纠正不当行为，并可删除、拒绝违背准则的评论、提交、代码等任何贡献。
2. 遵守许可证与版权规范。社区代码仓采用 Apache License 2.0（如 agent-core 等代码仓的LICENSE文件）；本 community 仓库自身承载的是社区文档，根目录 LICENSE 为 Creative Commons Attribution 4.0 International（CC-BY-4.0），适用于文档内容。贡献代码必须是原创内容，不得侵犯他人知识产权；若涉及第三方开源软件引入或片段引用，须遵守 许可证与特殊许可证评审指导 与 License-and-Copyright-Guidelines.md 中关于 LICENSE 文件、NOTICE 文件与版权头声明的规则。
3. 签署 CLA（贡献者协议）。必须首先完成签署才能参与贡献，个人贡献者、企业员工、企业代表三条路径的操作步骤与 Git 邮箱匹配要求详见 cla/cla使用指南.md。特别注意：CLA 检查以 commit 信息中的 committer 邮箱为准，签署 CLA 使用的邮箱必须与提交代码时的 Git 邮箱一致，否则 PR 会被打上openJiuwen-cla/no标签；个人开发者推荐直接用个人邮箱签署，企业邮箱在公司后续签署企业 CLA 后会使个人签署自动失效。

代码贡献完整流程

以下流程整合自 CONTRIBUTING_zh.md 与 README_CN.md，可直接照做：

1. 环境准备

• 安装并配置 Git，注册 SSH 公钥（可参考 GitCode 帮助中心的 Git 与公钥管理文档）；
• 在 openJiuwen 的代码托管平台（GitCode）上找到你感兴趣的 Repository，并确认其所属 SIG。

2. 云上 Fork 并克隆到本地

打开对应 Repository 的首页，点击右上角Fork按钮，建立属于个人的云上 Fork 仓库，然后克隆到本地：

mkdir ${your_working_dir} cd ${your_working_dir} # 从仓库页面复制 Fork 后的仓库地址为 $remote_link git clone $remote_link

3. 创建开发分支

更新本地主干并基于远端main拉取功能分支：

git remote add origin $remote_link git fetch origin git checkout main git pull --rebase git branch myfeature origin/main git checkout myfeature

之后在myfeature分支上编辑和修改代码。

4. 提交变更（含 Conventional Commits 规范）

git add . git commit -sm "feat: xxx" # 提交信息包含 signoff 邮箱

如需继续补充内容，可用git commit --amend追加到上一次提交；建议通过git rebase将零散提交合并为原子性提交，确保主干历史清晰可追溯。提交信息遵循 Conventional Commits 约定式提交规范，格式为<type>(<scope>): <subject>，type 取值包括：

scope可选，表示影响范围，如model、agent、workflow等。复杂提交可附加正文与Refs: #12关联 Issue，示例：

feat(core): add configuration management feature Add configuration management module to support dynamic settings loading. This feature includes: - Configuration file parser - Environment variable support - Settings validation logic Refs: #12345

5. 推送到 Fork 仓库并创建 PR

git push -f origin myfeature

访问你的 Fork 仓库页面，点击创建 Pull Request，选择myfeature分支生成 PR。PR 描述建议包含：变更的目的和背景、变更的详细说明、测试情况、相关 Issue 编号（#I12345格式）。

6. 关联 Issue 与 CI 门禁

1. 创建 Issue：打开对应 Repository 首页，选择Issues页签，点击新建 Issue，为相关联的代码（开发特性 / 修改 Bug）建立专属任务，用于执行 CI 门禁；
2. 关联 PR 与 Issue：创建 PR 或编辑已有 PR 时，在描述框输入#I+ 五位 Issue ID（如#I12345）即可关联；
3. 门禁触发：门禁执行完成后，会在该 Issue 关联的所有 PR 中自动评论执行结果。

PR 审查约束与 CI 持续集成

PR 合入须同时满足以下门禁约束：

• 需要达到最低评审人数；
• 评审问题全部解决才能合入；
• 禁止合入自己创建的 Pull Request；
• 合并 PR 前需确保关联的流水线任务成功运行并通过检查。

openJiuwen 通过持续集成（CI）保证代码质量：

• 代码门禁：提交代码合入申请后触发门禁检查，例如静态检查、代码编译、功能测试等，门禁通过后才能合入；
• 每日构建：CI 流水线每日自动执行，提前发现静态检查、编译、功能等方面的问题。

开发规范速查

• Python：遵循 PEP 8 编程规范；
• JavaScript：遵循 openJiuwen-JavaScript-coding-style-guide.md；
• 安全设计：遵循 openJiuwen-security-design-guide.md；
• 文档写作：遵循 contribute/style-guide 下的文档结构、内容要素与语言风格指南。

贡献者成长路径

根据 社区章程 第四章，社区成员沿 Contributor → Committer → Maintainer 的路径成长：

• Contributor：签署 CLA 后，在社区有一个或以上被 Committer 合入的 PR；
• Committer：担任该 SIG 的 Contributor 至少三个月，独立完成至少一个功能或修复一个重大 Bug，由本 SIG 的 Maintainer 或 Committer 提名，经全体 Maintainer 和 Committer 同意当选；拥有 SIG 项目的代码检视与合入权限；
• Maintainer：担任 Committer 至少三个月，持续参加 SIG 例会（近 6 个月与会率 70% 以上），作为主要审阅者参与至少 12 次 PR 审阅、审阅或合并至少 30 个基本 PR，由 Maintainer 或 TC 成员提名并报 TC 决策审批。

SIG 的成立同样由技术委员会（TC）决策，需明确职责范围、沟通方式、维护人员任免与业务范围；SIG 组每月召开 1~2 次工作例会，议题收集、技术讨论、会议纪要均对外开放。

社区沟通与交流

如果您在使用 openJiuwen 过程中遇到问题，可以通过以下渠道联系社区：

此外，也可通过对应仓库的 Issues 页面提交问题，或关注仓库 release/openJiuwen生命周期发布公告.md 中的版本生命周期公告。

小结

openJiuwen 以 DeepAgents、Agent Studio、Agent Framework、Agent Distributed Runtime、Agent System Service 五层能力体系为骨架，通过十余个可独立演进、可组合使用的模块化仓库覆盖 Agent 开发到服务化运行的全链路；每个仓库由对应的 SIG 组织看护，贡献者沿"签署 CLA → Fork → 分支开发 → Conventional Commits 提交 → PR 关联 Issue → 门禁与评审"的标准化路径参与共建。建议新贡献者先选定一个与自身方向匹配的 SIG（可从sigs/目录下的sig-info.yaml找到 Maintainer 联系方式），从文档或小范围 Bug 修复入手，逐步成长为 Committer 与 Maintainer。

• 文档
• 开源治理