如何参与dolphin-code贡献?社区协作与代码规范完全指南
如何参与dolphin-code贡献?社区协作与代码规范完全指南
dolphin-code(OrcaMatrix / aPaaS AI Workspace)是一个开源的 AI 原生研发工作区聚合仓库,涵盖产品原型、Agentic Coding 工具链、沙箱运行时、控制面后端与 React 管理控制台等 9 大模块。本文是一份面向新手贡献者的完全指南:无需深厚背景,照着「选模块 → 读文档 → 建分支 → 跑测试 → 提 PR」六步走,就能安全地参与 dolphin-code 社区协作,并完全遵守项目的代码规范与 Git 工作流。
一、开始贡献前的准备工作
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 是一个「源码聚合」型仓库,每个模块自带独立的构建与测试命令。先了解你要贡献的模块在哪里:
| 模块路径 | 语言/技术栈 | 贡献方向 |
|---|---|---|
| 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 贡献流程详解(分支隔离 + 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。
三、代码规范:架构边界、安全红线与文档同步
1. 架构规范:DDD + Clean Architecture
agent-runtime/AGENTS.md 给出了后端架构的铁律:
- 领域层不得依赖 HTTP、Docker、GitLab、CLI、文件系统或数据库实现;
- 所有 provider 能力通过 interface / port 进入应用层,核心流程不写死具体供应商;
- 前端(web-console)只消费 Control Plane API,不得自行发明接口字段,详见 web-console/AGENTS.md。
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 需要写清:
- 简短摘要 —— 这次改了什么、为什么改;
- 受影响的模块路径 —— 例如
web-console/、control-plane/; - 你运行过的验证命令;若某命令无法在本地运行,说明原因。
验收状态要诚实分级
模块文档普遍要求把验收拆细汇报(如 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 的社区协作哲学可以浓缩为一句话:小步快跑、边界清晰、证据说话。改动范围越小、文档引用越准、验证命令越完整,你的 PR 就越容易获得社区认可。从一篇文档修订或一个拼写修复开始,用「直接模式」迈出第一步,再逐步升级到 Full-Cycle 完整流程 —— 这就是参与 dolphin-code 开源贡献最稳妥的完全路径。🚀





