企业官网建设流程全解析

• 文档
• 开源治理

本文基于 openJiuwen 社区的中文贡献指南 CONTRIBUTING_zh.md 展开，系统讲解向 openJiuwen 各仓库贡献代码的完整闭环：许可证与版权合规要求、安全设计与代码风格规范、Git 环境准备与 CLA 邮箱对齐、Fork/Clone/分支/提交/推送操作，以及 PR 创建、Issue 关联、门禁构建与 CI 检查。读完本文，你可以独立完成一次符合 openJiuwen 社区规范的代码提交，并通过 CLA 检查、门禁与代码评审。

贡献总览：一次合规提交的完整链路

openJiuwen 欢迎开发者以多种方式参与：评价现有代码、提交更改、反馈问题或贡献原创代码。无论是代码贡献还是文档、Issue 等非代码贡献，都需要先遵守社区行为准则（openJiuwen社区行为准则.md），并通过 CLA（Contributor License Agreement，贡献者协议）签署——这是代码能够被合入的前提。

一次完整的代码贡献可以归纳为以下链路：

下面按这条链路逐节展开，并结合仓库内的规范文档补充细节。

许可证与版权规范：贡献代码的前置约束

项目许可证

openJiuwen 代码采用Apache License 2.0 (Apache-2.0)许可证。贡献者在提交代码前需要理解这一选择带来的约束：你提交的代码将并入 Apache-2.0 许可的开源体系中分发。

版权声明要求

用户提交的代码必须是原创内容，不得侵犯他人知识产权。具体的许可证与版权要求由 许可证与版权规范 定义，其中与贡献者最相关的规则包括：

• LICENSE 文件：每个开源仓必须有与 openJiuwen 整体许可证规则一致（如 Apache-2.0）的许可证描述，许可证文件必须为纯文本格式、命名为LICENSE（不带.txt、.md后缀），并放置在代码仓根目录；若同一仓包含多种许可证，主许可证写在LICENSE中，其它许可证以LICENSE-许可证类型-备注命名，并在主许可证中说明其适用范围。
• NOTICE 文件：如分发的二进制中包含第三方开源软件，需提供NOTICE文件，以纯文本列出所有第三方软件的名称、版本、权利人声明与 License 信息，通常放在发布文件夹或压缩包顶层目录（.jar文件可位于META-INF目录）。
• 版权和许可头：开源仓中的文件原则上应包含版权和许可头声明，例外情况包括：添加声明会影响文件功能（如 JSON 文件不支持注释）、工具生成且已注明自动生成的文件、以及简短的用户说明文件（如 README）。版权头格式为：

Copyright (C) [第一次发布年份]-[当前版本发布年份] [版权所有者]

许可证头以具体许可证文本为准，例如 Apache-2.0 许可头：

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

需要留意两点：版权头中的年份指作品对外发布的年份，首次发布只写发布年份即可；版权所有者是法律实体（个人或公司），若代表公司贡献代码，应写公司法律实体。

第三方依赖与特殊许可证

若新贡献代码涉及第三方开源软件引入或片段引用，必须遵守 许可证与特殊许可证评审指导：

• 贡献代码许可证白名单：原则上贡献代码应提供源代码并采用 OSI 批准的开源许可证分发，openJiuwen 建议优先采用Apache License 2.0 (Apache-2.0)。
• 第三方依赖可接纳许可证：与 Apache-2.0 兼容的许可证可被接纳，建议优先接纳的包括 MIT、BSD-2-Clause/BSD-3-Clause、ISC、Apache-2.0、MulanPSL-2.0、Apache-1.1、AFL-3.0、BSL-1.0、zlib/libpng、Python Software Foundation License 等。
• 不建议接纳的许可证：不支持商用的许可证，以及包含不合理限制或义务的许可证不建议接纳，例如 GNU GPL 3、GNU Affero GPL 3、Confluent Community License、Amazon Software License、任何包含 Commons Clause 条款的许可证等。
• 特殊许可证评审：如需接纳白名单之外的“特殊许可证”，必须经 openJiuwen 项目代码特殊许可证评审（由合规 SIG 组织，参与人员至少包括 PMC 代表、法务代表、合规 SIG 代表）。评审规则的核心包括：贡献代码应优先选用 Apache-2.0 以确保许可证归一性；特殊许可证必须支持下游用户再分发且与现有项目代码许可证兼容；不得包含广告条款、商用限制、使用领域限制等不合理条款；非源码形式（二进制码或目标码）引入的，须采用开源许可证并经 PMC 审批同意。未经特殊许可证评审的软件模块不能被合入 openJiuwen 主干。

此外，openJiuwen 社区有权根据相关规范修改/删除开发者贡献的内容，直至其符合规范要求。

安全设计规范与代码风格

安全设计规范

模块设计阶段应遵循 openJiuwen安全设计规范，该规范参考业界广泛标准和开源最佳实践，用于避免高安全设计风险。对贡献者而言，几条高频出现的核心约束包括：

• 身份认证与鉴权：除非标准协议约定，所有能对系统进行管理（配置、升级、调试等）的接口应具备接入认证机制并缺省启用；最终认证处理必须放在服务端进行；只保留运行维护所必需的对外通信连接，关闭不需要的端口。
• 安全传输：跨网络传输敏感数据或关键业务数据（口令、个人数据、模型参数、梯度数据等）应采用安全传输协议或加密后传输；不应使用 SSL2.0、SSL3.0、TLS1.0、TLS1.1，推荐 TLS1.2 和 TLS1.3。
• 加密算法与密钥管理：不应使用私有、非标准密码算法，推荐使用业界验证过的公开算法，如 AES（密钥长度 128 位及以上）、RSA（推荐 3072 位）、SHA2（256 位及以上）、HMAC-SHA2；同时应避免 MD5、DES/3DES、RC4、RSA 1024 位及以下等已被认为不安全的算法。用于加密的密钥不能在代码中硬编码；密码算法中的随机数必须是密码学意义上的安全随机数（如 OpenSSL 的RAND_bytes、JDK 的java.security.SecureRandom、类 Unix 平台的/dev/random）；密钥材料及组件保存时限权限（如 600 或 400），内存中的密钥释放前应对内存空间填充其他值。
• 敏感数据保护：认证凭据应加密存储并提供访问控制；不需要还原的场景应使用 PBKDF2 等不可逆算法（迭代次数最低 1000 次，盐值为密码学安全随机数、至少 16 字节、按用户区分）；日志、调试信息、错误提示中应过滤或屏蔽认证凭据。
• 权限最小化：系统新建账号默认不授予任何权限，或默认只指派最小权限（如只读）的角色。

代码风格

进行代码开发、检视时务必保持代码风格统一。openJiuwen 的编程规范要求：

• Python：遵循 PEP 8 编程规范（Python 官方社区通用标准）。
• JavaScript：遵循 openJiuwen JavaScript 编码风格指南。该规范以“代码在保证功能正确的前提下满足可读、可维护、安全、可靠、可测试、高效、可移植”为总体原则，将条目区分为“规则”（必须遵守）与“建议”（必须加以考虑）。例如命名规范中要求：须使用正确的英文拼写进行命名，禁止拼音拼写（反例xingming，正例username）；命名尽量少用缩写，仅允许ctx、req、resp等常见缩写；类名、枚举名、命名空间名采用UpperCamelCase风格。规范也明确例外处理：修改外部开源代码或第三方代码时，应遵守其已有规范，保持风格统一。

环境准备与 CLA 签署

Git 环境

• 针对 Git 的安装、环境配置及使用方法，可参考代码托管平台的 Git 帮助文档。
• 开展 Git 工作流之前，需要先在 openJiuwen 的代码托管平台上注册 SSH 公钥，并找到感兴趣的 Repository。

CLA 签署与 Commit 邮箱对齐

CLA 是贡献的前置条件。openJiuwen 社区通过机器人检查PR 中所有 commit 作者的邮箱是否都签署了 CLA，只有全部通过，PR 才算通过 CLA 检查——只要有任意一条 commit 的邮箱未签署，整个 PR 就会被标记为openJiuwen-cla/no。

因此，签署 CLA 时使用什么邮箱，提交代码时（commit 邮箱）就必须使用相同的邮箱。建议在提交前按 Git 配置优先级（本地--local> 全局--global> 系统--system）检查并配置：

# 检查当前仓库的本地配置（优先级最高） git config user.name git config user.email # 检查全局配置 git config --global user.name git config --global user.email # 配置全局信息（推荐用于个人项目） git config --global user.name "你的姓名" git config --global user.email "签署CLA的邮箱"

可通过git config --list --show-origin验证配置是否生效。详细的签署流程（个人开发者、企业员工、企业代表三类路径）、签署状态验证与常见错误处理，可参考 cla使用指南；机器人检查机制与 commit 邮箱修正方法见 cla指导。

如果提交 PR 后出现openJiuwen-cla/no红色标签，典型处理路径是：

1. 先用git log --pretty=fuller检查 commit 邮箱；
2. 若 commit 邮箱与 CLA 邮箱不一致，用正确身份修正后强制推送：

# 修正最后一次提交 git -c user.name="正确姓名" -c user.email="正确邮箱" commit --amend --reset-author git commit --amend --author="正确姓名 <正确邮箱>" --no-edit git push --force # 修正多个提交：交互式 rebase git rebase -i <commit_id>~n # 将 pick 改为 edit，逐一执行： git commit --amend --author="正确姓名 <正确邮箱>" --no-edit git rebase --continue git push --force

3. 在 PR 评论区评论/check-cla触发重新检查，确认标签更新为openJiuwen-cla/yes。

另外注意：若通过 GitCode 平台的 Fork 仓页面或轻量级 PR 直接提交代码，提交对话框中同样需要填写提交邮箱并勾选“添加署名信息（类似 git commit --signoff）”：

代码下载：从云上 Fork 到本地 Clone

从云上 Fork 代码分支

1. 找到并打开对应 Repository 的首页；
2. 点击右上角的 Fork 按钮，按照指引，建立一个属于个人的云上 Fork 分支。

把 Fork 仓下载到本地

1. 创建本地工作目录，便于本地代码的查找和管理：

mkdir ${your_working_dir}

2. 复制远程仓库到本地：
   • 在仓库页面内复制远程仓库的拷贝地址，得到$remote_link；
   • 切换到工作目录并执行拷贝命令：

cd ${your_working_dir} git clone $remote_link

本地分支、提交与推送

拉取开发分支

首先更新本地分支：

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

然后基于远端 main 分支拉取本地调试分支：

git branch myfeature origin/main git checkout myfeature

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

提交变更（含 signoff）

在本地工作目录提交变更：

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

-s（signoff）参数会在提交信息尾部追加署名信息，CLA 检查与提交者追溯都依赖这个邮箱，因此务必与 CLA 签署邮箱保持一致。若在前次提交基础上继续编辑、构建并测试，可用git commit --amend追加到上一个提交。

约定式提交（Conventional Commits）

提交信息采用 Conventional Commits（约定式提交规范），一个较完整的 commit 格式参考如下：

feat: add some new features Add xx feature for xxx, it can xxxx. Add xx feature for xxx, it can xxxx. Refs: #12

常用的提交类型包括：feat（新功能）、fix（缺陷修复）、docs（仅文档变更）、style（不影响代码含义的格式调整）、refactor（既不修复缺陷也不添加功能的代码变更）、perf（性能优化）、test（补充或修正测试）、ci（CI 配置变更）、chore（构建流程或辅助工具变更）；scope为可选项，用于标识影响范围（如model、agent、workflow）。保持统一的提交风格有助于提升 commit 历史可读性，也便于自动化工具生成变更日志。

推送到远端

准备进行审查（或只是建立工作的异地备份）时，将分支推送到你的 Fork 仓库：

git push -f origin myfeature

创建 Pull Request

访问你的 Fork 仓页面，点击“创建 Pull Request”按钮，选择myfeature分支生成 PR。PR 描述中建议包含：

• 变更的目的与背景；
• 变更内容的详细描述；
• 测试状态；
• 关联的 Issue 编号（#I+ 五位 Issue ID 格式，如#I12345）。

门禁构建：Issue 关联与合入约束

创建 Issue 并与 PR 关联

1. 找到并打开对应 Repository 的首页，选择 Issues 页签，点击新建 Issue，建立一个专属任务，用于相关联的代码（开发特性/修改 bug）执行 CI 门禁；
2. 创建 PR 或编辑已有 PR 时，在描述框输入#I+ 五位 Issue ID（例如#I12345），即可将 Issue 与 PR 关联。

合入约束

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

触发代码门禁

门禁执行完成后，会在该 Issue 关联的所有 PR 中自动评论门禁执行结果。

CI 门户：代码门禁与每日构建

openJiuwen 通过持续集成（CI，Continuous Integration）及时发现代码问题，确保代码质量可靠和功能稳定，主要包括两类机制：

• 代码门禁：开发者向 openJiuwen 提交代码合入申请后，会触发门禁检查，例如静态检查、代码编译、功能测试等，门禁通过后才能合入代码；
• 每日构建：openJiuwen 的持续集成流水线每日自动执行，提前发现代码静态检查、编译、功能等方面的问题，及时修复，确保代码质量。

社区沟通渠道

贡献过程中遇到问题时，可通过邮件列表参与讨论，详见 maillist_zh.md：

完整的英文贡献指南可参考 Contribution_guidance_zh.md，其中包含 openJiuwen 的系统架构与各代码仓总览，帮助你在选择贡献目标 Repository 时理解各模块（DeepAgents、Agent Studio、Agent Framework、Agent Distributed Runtime、Agent System Service）的职责边界。

• 文档
• 开源治理