企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG

本文以 Nexent 官方贡献指南（doc/docs/en/contributing.md）为骨架，结合仓库内的开发者文档、CI 工作流与核心实现，系统讲解如何参与 Nexent 开源共建：包括 GitFlow 分支策略、Bug 报告与功能请求模板、开源纪念墙的零门槛贡献流程、代码提交的七步路径、受保护分支的 Code Owner 审核机制，以及本地开发环境与测试的实战细节。读完本文，你将具备从"发现问题"到"提交 PR 并合入"的全流程操作能力。

一、为什么参与 Nexent 共建

Nexent 是一个开源智能体（Agent）SDK 与平台，能够把描述流程的自然语言转化为完整的多模态服务——无需编排、无需复杂拖拉拽，并基于 MCP 工具生态系统提供灵活的模型集成、可扩展的数据处理与知识库管理能力。

从仓库布局看，Nexent 是一个典型的多模块单体仓库（Monorepo）：

• frontend/：Next.js + TypeScript 构建的 Web 应用；
• backend/：FastAPI + Python 实现的 HTTP API 与业务服务；
• sdk/nexent/：Agent 运行时框架与数据处理能力，可独立作为 Python 包使用；
• deploy/、k8s/ 与 docker/：Docker、Kubernetes 部署配置；
• doc/docs/：VitePress 文档站点（中英双语）；
• test/：后端与 SDK 的测试代码。

参与 Nexent 共建的方式非常多元：提交代码修复 Bug、提出新功能想法、改进文档、翻译文档，甚至只是在开源纪念墙上留下一段话，都属于贡献。无论你是资深工程师还是第一次接触开源的初学者，都能找到适合自己的切入点。

仓库以 LICENSE（MIT License，Copyright (c) 2025 Huawei Technologies Co., Ltd.）开源，社区同时遵循 CODE_OF_CONDUCT.md（Contributor Covenant 行为准则），核心维护团队与 Committer 名单见 doc/docs/en/contributors.md。贡献前请花一分钟阅读许可协议与行为准则，确保共建过程合规、友善。

二、GitFlow 分支策略：Nexent 的分支管理规范

GitFlow 是一种结构化的 Git 分支模型，为不同目的（新功能、发布、热修复）定义专用分支，并规定它们之间的交互方式，从而让开发流程更清晰、发布管理更高效、团队协作更顺畅。Nexent 仓库严格采用该模型。

2.1 主分支（Main Branches）

• main：代表官方发布历史，任何时刻都应保持可部署（deployable）状态。正式版本只从该分支产出。
• develop：日常开发的主干分支，用于集成来自 feature 分支的新功能与 Bug 修复。

2.2 辅助分支（Supporting Branches）

• feature 分支：用于开发新功能。从develop派生，功能完成后合并回develop。命名如feature/xxx。
• release 分支：准备新版本发布时创建（命名如release/1.0.0），用于发布前的最终测试与微调，随后同时合并进main与develop。
• hotfix 分支：用于修复生产环境的紧急 Bug。从main派生，修复后同时合并回main与develop（命名如hotfix/bug1）。

2.3 GitFlow 带来的收益

• 结构化工作流：为不同类型变更提供清晰、一致的流程；
• 改善协作：明确各分支角色及交互方式，方便团队分工；
• 高效发布：在专用分支中隔离变更并做最终测试，简化发布流程；
• 减少冲突：通过 feature 分支与 release 分支的隔离，最大限度减少合并冲突并易于解决。

2.4 仓库中的分支保护与 CI 佐证

从源码结构看，Nexent 的 CI 明确围绕 GitFlow 分支模型设计：.github/workflows/auto-unit-test.yml 与 .github/workflows/auto-web-check-dev.yml 均在pull_request与push事件中限定分支为develop、release/**、hotfix/**，也就是说：

• 日常功能开发合入develop时自动触发单元测试与前端类型检查；
• release/**分支触发发布前验证；
• hotfix/**分支触发紧急修复验证。

这印证了贡献指南中"受保护分支（如main）不允许直接推送"的约束——所有变更必须通过 PR 进入这些受控分支。

三、提交 Bug 报告或功能请求

发现 Bug 或有好点子，请先通过 Issue 渠道告知社区。为提高处理效率，仓库提供了标准化的 Issue 模板（见 .github/ISSUE_TEMPLATE/），提交时务必选择对应模板并完整填写。

3.1 Bug 报告（Bug Report）

在 .github/ISSUE_TEMPLATE/bug_report.yml 模板中，报告 Bug 需要包含：

• 清晰的标题：概括 Bug 现象；
• Nexent 版本：标明受影响版本（当前仓库 VERSION 记录为 v2.7.0）；
• 问题描述（必填）：清晰、简洁地描述问题；
• 复现步骤：给出明确、可复现的操作路径；
• 错误信息或日志（如有）；
• 期望行为 vs 实际行为：说明应当发生什么、实际发生了什么；
• 截图或录屏（如有助于说明问题）。

3.2 功能请求（Feature Request）

在 .github/ISSUE_TEMPLATE/feature_request.yml 模板中，需要提供：

• 清晰的标题：概括功能诉求；
• 功能描述（必填）：说明希望通过该功能解决什么问题；
• 提议方案：描述你期望的实现方式；
• 相关用例或示例：该功能的应用场景；
• 截图或原型图（如有）。

提交前请先检索已有 Issue（包括已关闭的），避免重复提交。

四、开源纪念墙贡献：面向新手的零门槛路径

Nexent 在文档中设置了一面"开源纪念墙"（doc/docs/en/opensource-memorial-wall.md），社区成员可以在此留下自己的开源故事与体验。这是专为初学者设计的贡献方式——不需要写代码，只需四步。

Step 1：编辑纪念墙文件

在纪念墙文件页点击 ✏️ 编辑按钮，直接进入在线编辑。

Step 2：添加你的留言

在 "Community Messages" 区域按以下格式添加留言，然后点击 "Commit changes"：

::: info Your Name - 2024-01-15 Share your open source story or experience with Nexent! :::

格式要点：:::后为提示类型（info、tip等），随后是昵称与日期，正文为你的故事或体验。仓库中已有多条真实留言可供参考，例如：

::: tip product_guy - 2025-02-07 no more PRDs!! just describe in plain english and devs get it instantly ::: ::: info techbro_kevin - 2025-06-15 first time doing open source, nexent is pretty cool! natural language to create agents, way easier than i thought :::

Step 3：发起变更提议

点击 "Propose changes" 提交变更提议，随后点击 "Create pull request" 创建 PR，等待合入即可。整个流程均在网页端完成，无需本地 Git 环境。

Step 4：成功！

PR 合入后，你的留言就会展示在开源纪念墙上，你也正式成为 Nexent 的共建者之一。社区会尽快审核并合入你的贡献。

五、提交代码变更：七步完整路径

想要提交代码，按以下七个步骤操作。

Step 1：Fork 仓库

将 Nexent 仓库 Fork 到你的个人账号下。

Step 2：Clone 你的 Fork

将 Fork 后的仓库克隆到本地：

git clone https://gitcode.com/ModelEngine/nexent.git

Step 3：创建分支

基于当前开发基线创建新分支：

git checkout -b your-branch-name

建议按 GitFlow 规范命名（如feature/xxx、fix/xxx），并保持变更聚焦单一主题。

Step 4：进行修改

动手编码前，先阅读 doc/docs/en/developer-guide/overview.md 了解代码结构与编码规范。关键约定包括：

• 分层职责：backend/apps/负责请求解析、鉴权与 HTTP 错误映射；backend/services/负责业务编排并抛出领域异常；业务能力放 SDK。不要把数据库操作或业务编排直接写进端点函数；
• 环境变量集中管理：后端环境变量统一在 backend/consts/const.py 中读取，其他模块一律从consts.const导入，SDK 只通过函数参数接收配置、不得直接读环境变量；
• SQL 迁移不可变：deploy/sql/ 下已合入目标分支的 SQL 文件不可修改，数据库变更须新增带版本号的迁移文件；
• 注释与文档语言：代码注释、docstring 用英文编写；
• 测试要求：后端与 SDK 使用 pytest，缺陷修复至少覆盖对应回归场景。

Step 5：提交变更

使用清晰、简洁的提交信息，并遵循以下提交信息规范（Conventional Commit 风格）：

示例：

git commit -m "✨ add user authentication" git commit -m "🐛 resolve login timeout issue" git commit -m "📝 update API documentation"

Step 6：与上游保持同步

保持你的 Fork 与主仓库最新状态一致：

git remote add upstream https://gitcode.com/ModelEngine/nexent.git git fetch upstream git merge upstream/main

（如使用 GitHub 镜像托管，将 upstream 地址替换为对应仓库地址即可。）

Step 7：打开 Pull Request

将变更推送到你的 Fork 并在主仓库发起 PR，PR 中应包含：

• 清晰的标题与描述：说明改动内容与动机；
• 关联 Issue 引用：如fixes #123；
• 补充上下文或截图：便于 Reviewer 理解。

提交后团队会审核并反馈意见，按反馈迭代修改即可。

六、受保护分支与 Code Owner 审核

向受保护分支（如main）提交变更时，需遵守以下要求：

1. 必须经过 Code Owner 审核

   • PR 会自动请求相关 Code Owner 评审；
   • 你不能给自己的 PR 审批；
   • Code Owner 的批准是强制性的。

2. 需要多重批准

   • 至少 2 个批准（含 Code Owner 批准）；
   • 所有 CI 检查必须通过（lint、test、build 等）。

3. 合并流程

   • 提交 PR 后系统自动请求 Code Owner 评审；
   • 至少两个批准（含 Code Owner）后，"Merge" 按钮才会可用。

4. 限制

   • 不能绕过评审或强制合并；
   • 禁止直接推送到受保护分支；
   • 自我批准无效。

从 CI 配置可以印证上述约束的落地：如前文所述，.github/workflows/auto-unit-test.yml 会在 PR 推送到develop、release/**、hotfix/**时自动运行部署脚本测试、Python 3.11 环境下的全量测试（python test/run_all_test.py）并上传覆盖率到 Codecov；.github/workflows/auto-web-check-dev.yml 则对frontend/**的改动自动执行 TypeScript 类型检查。只有这些 CI 全部通过，PR 才具备合入条件。

七、改进文档

优秀的文档是优秀项目的关键。你可以通过以下方式贡献：

• 修正拼写错误、澄清含糊不清的段落；
• 为功能或安装步骤补充缺失文档；
• 将文档翻译为其他语言（仓库 doc/docs/zh/ 即为中文文档站点）。

操作方式与代码贡献相同（Fork → Clone → 建分支 → 修改 → 提交 PR），文档改动建议使用📝类型提交信息。需要特别提醒：文档中引用的相对链接必须保持正确，例如 doc/docs/en/contributing.md 中指向纪念墙的链接为 doc/docs/en/opensource-memorial-wall.md，指向开发者指南的链接为 doc/docs/en/developer-guide/overview.md，修改时不要破坏这些路径。

八、开发者实战：本地环境、测试与质量门禁

贡献代码前，先按 doc/docs/en/developer-guide/environment-setup.md 准备环境。这里补充关键实操命令（均以仓库根目录为基准）。

8.1 通用前置依赖

• Python 3.11+、Node.js 18.18+ 与 pnpm；
• Docker 与 Docker Compose（系统级运行时沙箱默认开启，调试工具或 Skill 脚本时必须有 Docker）；
• uv（Python 包与虚拟环境管理工具）。

8.2 全栈开发环境

启动基础设施（PostgreSQL、Redis、Elasticsearch、MinIO）：

bash deploy.sh docker --components infrastructure --port-policy development

注意：该命令会在仓库根目录生成包含服务地址与密钥的.env文件，此文件禁止提交，敏感值也不得写入文档、日志或聊天元数据。

安装后端依赖：

cd backend uv sync --extra>cd frontend pnpm install pnpm dev

按需启动后端服务（每个服务一个终端，先激活虚拟环境source backend/.venv/bin/activate）：

python backend/mcp_service.py python backend/data_process_service.py python backend/config_service.py python backend/runtime_service.py python backend/northbound_service.py

8.3 测试与质量门禁

• 后端/ SDK：pytest test/backend/apps/test_agent_app.py -v可单文件定向测试，全量跑python test/run_all_test.py；
• 前端：pnpm run check-all依次执行类型检查、lint、格式检查与构建（单步可用npm run type-check）；
• 开发约定补充（详见 AGENTS.md）：Python 导入顺序遵循标准库 → 第三方 → 项目内；SDK 的 Ruff 配置使用 119 字符行宽。

8.4 从源码看版本管理

提交 Bug 报告时需要填写 Nexent 版本。从源码看，版本号解析逻辑集中在 backend/consts/const.py：APP_VERSION依次尝试APP_VERSION_FILE环境变量覆盖、容器路径/opt/nexent/VERSION、仓库根目录 VERSION 文件，最后回退到硬编码默认值。当前仓库 VERSION 记录为v2.7.0，报告 Bug 时以你实际运行环境的版本为准。

九、获取帮助

遇到问题或有疑问，可通过以下渠道联系社区：

• GitHub Issues：发起 Issue 进行讨论（Bug 用 Bug Report 模板，想法用 Feature Request 模板）；
• Discord：加入 Nexent 社区进行实时交流；
• 邮件：联系维护团队。

十、结语

参与开源最好的方式就是现在动手。无论你是修一个错别字、翻译一页文档、报告一个 Bug，还是在纪念墙上留下一段经历，都是 Nexent 成长的一部分。从 GitFlow 分支规范到 Code Owner 审核，Nexent 用清晰、低门槛的流程欢迎每一位共建者——Happy coding!

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG