如何参与dolphin-code贡献?社区协作与代码规范完全指南

原创2026-10-22 22:45:121,892 阅读

如何参与dolphin-code贡献?社区协作与代码规范完全指南

dolphin-code(OrcaMatrix / aPaaS AI Workspace)是一个开源的 AI 原生研发工作区聚合仓库,涵盖产品原型、Agentic Coding 工具链、沙箱运行时、控制面后端与 React 管理控制台等 9 大模块。本文是一份面向新手贡献者的完全指南:无需深厚背景,照着「选模块 → 读文档 → 建分支 → 跑测试 → 提 PR」六步走,就能安全地参与 dolphin-code 社区协作,并完全遵守项目的代码规范与 Git 工作流。

dolphin-code 产品对象页界面,展示社区协作与 AI 研发工作区的贡献目标场景


一、开始贡献前的准备工作

1. 克隆仓库并定位贡献入口

贡献的第一步是把仓库拉到本地(仓库为只读镜像,请勿直接改动原文件,所有变更都应通过分支和 PR 进行):

git clone https://gitcode.com/gh_mirrors/do/dolphin-code

克隆完成后,重点阅读三个「门面文件」,它们是社区协作的总入口:

文件 作用
README.md 模块地图:告诉你 9 大模块各自负责什么
CONTRIBUTING.md 贡献底线规则与 PR 要求
SECURITY.md 密钥安全红线与漏洞上报方式

💡 一句话原则(来自 CONTRIBUTING.md):把改动限定在相关模块内,动代码前先读该模块的 AGENTS.md 和 README.md。

2. 认识项目结构:从模块目录入手

dolphin-code 是一个「源码聚合」型仓库,每个模块自带独立的构建与测试命令。先了解你要贡献的模块在哪里:

dolphin-code 认知工作台界面,体现多模块协作与贡献者需要理解的整体架构

模块路径 语言/技术栈 贡献方向
product-design/ 原型 + 文档 产品规格、设计源文件、跨模块交接文档
agentic-coding/ Python + Shell Agentic Coding 工具链、skills、CLI wrappers
agent-runtime/ Go + TypeScript 沙箱运行时、workspace 编排、runtime Web UI
control-plane/ Java (Spring Boot) 平台控制面后端、API 契约、适配编排
web-console/ React + TypeScript 管理控制台前端(React 18 / Vite / Vitest)
app-seed/ Java + Vue 3 生成式应用种子工程与 SDK 基线
approve-engine/ Java 审批流引擎与 Flowable 集成
platform-integration/ Helm + YAML DevOps 与集成基线、E2E 示例

dolphin-code AgentStudio 沙箱运行时界面,对应 agent-runtime 模块的贡献范围


二、dolphin-code 贡献流程详解(分支隔离 + Worktree)

1. 先读「四级 Specs 体系」再动手

这是 dolphin-code 最独特的协作规范:每个模块都用 L0→L3 四级文档体系管理知识,动手前按任务范围加载对应级别:

L0  系统级   AGENTS.md(工作模式与最高准则)
L1  架构级   docs/solutions/l1/arch/、docs/solutions/l1/roadmap/
L2  模块级   docs/solutions/l2/{module}/
L3  细节级   docs/solutions/l3/{module}/(API Schema、Bug 记录、最佳实践)

详细协议见 specs-hierarchy-and-context-loading.md,历史方案检索统一从 docs/solutions/ 开始。

2. 按任务复杂度选择工作模式

各模块的 AGENTS.md 定义了两档模式,新手可据此判断自己该走轻重哪种流程:

  • 直接模式(Direct):拼写修复、文档微调、<30 行的非逻辑改动 —— 直接修改并做必要验证即可。
  • 完整模式(Full-Cycle):逻辑变更、新功能、Bug 修复 —— 遵循「Context Loading → 方案探索 → 写 Plan(必须引用已加载的 Specs)→ TDD 测试 → 执行 → 知识归档」闭环。

3. Git 工作流:Plan 分支隔离是硬性规范

dolphin-code 要求每个新任务独立开 plan/* 分支,禁止直接在默认分支上干活。标准操作:

git fetch origin
BASE_BRANCH="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD | sed 's#^origin/##')"
git switch "$BASE_BRANCH" && git pull --ff-only origin "$BASE_BRANCH"
git switch -c plan/2026-05-11-my-first-contribution

关键规则(完整说明见 plan-branch-isolation.md):

  • 分支命名:plan/<yyyy-mm-dd>-<short-topic>;
  • 完成实现与测试后,默认停留在 plan 分支等待验收,不自动合并;
  • 有远端协作要求时,push plan 分支并创建 PR / MR。

并发贡献者的进阶玩法:多人(或多条计划)并行时用 git worktree 隔离工作目录,每个 plan 一个 .worktrees/<topic>/ 目录,互不污染,详见 parallel-plan-worktree-workflow.md。agentic-coding 模块还提供现成的 agentic-plan-worktree create|merge|remove 命令,见 agentic-coding/README.md。

dolphin-code 流程总览界面,直观呈现从分支隔离到合并验收的贡献流水线


三、代码规范:架构边界、安全红线与文档同步

1. 架构规范:DDD + Clean Architecture

agent-runtime/AGENTS.md 给出了后端架构的铁律:

  • 领域层不得依赖 HTTP、Docker、GitLab、CLI、文件系统或数据库实现;
  • 所有 provider 能力通过 interface / port 进入应用层,核心流程不写死具体供应商;
  • 前端(web-console)只消费 Control Plane API,不得自行发明接口字段,详见 web-console/AGENTS.md。

dolphin-code Web Console 管理控制台,代码贡献需与其 API 契约保持一致

2. 安全红线:这些东西永远不要提交

CONTRIBUTING.md 与 SECURITY.md 明确划定了安全边界:

⚠️ 禁止提交:真实凭证、.env.local、kubeconfig、Maven settings、私钥、token、运行日志、本地 evidence、生成的客户数据。 正确做法:使用 example.com、__SET_ME__ 占位符和 localhost 默认值。

万一误提交了密钥:立即轮换 → 从仓库与历史中移除 → 推送前重新做一次密钥扫描(完整流程见 SECURITY.md)。

3. 文档同步:改动行为就要更新知识文档

  • 修改运行时行为时,补充聚焦的测试(CONTRIBUTING.md);
  • 模块特定行为写在拥有它的模块内;
  • 发现 spec 需要调整时,先回到 product-design/ 修改并评审,稳定后再同步到各模块的 docs/superpowers/specs/(见 agent-runtime/AGENTS.md)。

四、测试与验证标准:每个模块的「必跑命令」

提交 PR 前,请先在模块目录内跑通对应的完整验证(根仓库是源码聚合,命令都在模块里执行):

模块 必跑验证命令
web-console npm run typecheck、npm run test -- --run、npm run lint、npm run build(见 web-console/README.md)
agent-runtime go test ./... + npm --prefix web/builder run typecheck/build + 对应 tests/e2e/phase*.sh(见 agent-runtime/README.md)
control-plane 标准 mvn verify;WSL 挂载盘可用 bash scripts/mvn-fast 提速(见 control-plane/AGENTS.md)
app-seed ./scripts/dev-start.sh dev 本地联调 + scripts/smoke-runtime.sh 冒烟(见 app-seed/README.md)
agentic-coding ./bootstrap.sh 初始化后跑 pytest 与 tests/e2e/ smoke(见 agentic-coding/README.md)

📌 WSL 用户注意:前端测试在 /mnt/c 等挂载盘上会明显变慢,应优先使用 npm run test:fast -- <test-files> 做聚焦验证(web-console/AGENTS.md)。


五、提交 Pull Request:社区对 PR 的要求

PR 描述必须包含三要素

按 CONTRIBUTING.md 的规定,你的 PR 需要写清:

  1. 简短摘要 —— 这次改了什么、为什么改;
  2. 受影响的模块路径 —— 例如 web-console/、control-plane/;
  3. 你运行过的验证命令;若某命令无法在本地运行,说明原因。

验收状态要诚实分级

模块文档普遍要求把验收拆细汇报(如 control-plane/AGENTS.md):mock/fixture 冒烟不能冒充真实账号、真实 token、真实 E2E 的验收结论。用 Integrated / E2E Verified 这样的分级,让 reviewer 一眼看清验证深度。


六、新手快速上手清单(Quick Reference)

场景 去哪里 / 用什么
第一次进项目 README.md 模块地图 + 目标模块的 AGENTS.md
找历史方案 / Bug 经验 各模块 docs/solutions/(L1/L2/L3 知识库)
开新任务 git switch -c plan/<日期>-<主题>,规则见 plan-branch-isolation.md
并行多任务 worktree 工作流:parallel-plan-worktree-workflow.md
前端本地跑起来 cd web-console && npm install && npm run dev
种子应用本地联调 cd app-seed && ./scripts/dev-start.sh dev(后端 8080 / 前端 5173)
安全自查 SECURITY.md 密钥红线
提 PR 前 模块必跑命令全绿 + PR 三要素齐备

dolphin-code 管理控制台应用列表界面,展示贡献成果最终呈现给用户的平台形态


写在最后

dolphin-code 的社区协作哲学可以浓缩为一句话:小步快跑、边界清晰、证据说话。改动范围越小、文档引用越准、验证命令越完整,你的 PR 就越容易获得社区认可。从一篇文档修订或一个拼写修复开始,用「直接模式」迈出第一步,再逐步升级到 Full-Cycle 完整流程 —— 这就是参与 dolphin-code 开源贡献最稳妥的完全路径。🚀

登录后查看全文
dolphin-code