如何为OCTO贡献代码:新模块开发指南的完整工作流
如何为OCTO贡献代码:新模块开发指南的完整工作流
本文为首次参与 OCTO 开源项目的开发者梳理一套完整的 octo-web 代码贡献流程:从环境准备、新模块开发指南要求的"四件套"准备,到模块目录规范、验证与 PR 提交,帮助你在提交第一个 PR 前就少走弯路。octo-web 是 OCTO 开放工作平台的 Web 与桌面(Electron)客户端,基于 React + TypeScript 构建,并内置一流的 AI Agent 交互体验。
为什么贡献前必须先读「新模块开发指南」
OCTO 的仓库结构较大:apps/web 是主应用壳,packages/dmwork* 下是按业务拆分的模块包(联系人、MCP 市场、技能市场、智能总结等)。如果新代码继续往旧的 Components/、Messages/ 目录里"顺手一塞",很容易破坏模块边界。
因此,官方要求:只要你的改动属于新增业务页面、新增路由入口、新增完整用户流程,或对既有模块做结构化迁移,动代码前必须先阅读新模块开发指南,并产出四份准备材料。完整内容见 docs/new-module-development-guide.md,项目级技术规范见 DEVELOPMENT.md,Agent 协作约定见 AGENTS.md。
下面用一个真实视角走一遍完整工作流。
第一步:一键安装环境,跑通本地开发
OCTO 前端基于 Vite + pnpm 的 monorepo,环境要求简单:
| 工具 | 版本 | 说明 |
|---|---|---|
| Node.js | 20.x | 推荐用 nvm 管理 |
| pnpm | 10.x | 必须使用 pnpm,不要用 yarn/npm |
git clone https://gitcode.com/gh_mirrors/oc/octo-web
cd octo-web
pnpm install # 安装依赖
pnpm dev # 启动开发服务器
常用命令速查(定义在根目录 package.json):
pnpm dev:启动所有包的开发服务器pnpm build:生产构建pnpm test:单元测试(vitest,各包独立配置,如 apps/web/vitest.config.ts)pnpm lint:ESLint 检查;pnpm lint:css:Stylelint 检查pnpm gen:component <Name>:生成ui/+bridge/组件脚手架(脚本 scripts/gen-component.mjs)
💡 团队习惯在独立 worktree 中开发,可用
pnpm new:worktree feat/你的分支名一键创建,避免污染主工作目录。
第二步:动代码前产出「四件套」
新模块开发指南要求,在 issue、PR 草稿或实现笔记中先写清楚四样东西——写不清楚,说明范围就没准备好:
- 行为清单(Behavior List):用户能看到什么、能点什么。包括入口位置(菜单/路由/按钮)、主路径、空态/加载/错误态、是否依赖登录态或当前 Space、跳转是应用内路由还是整页导航。
- 文件地图(File Map):计划新增/修改的每个文件及其职责,例如
Service/XxxService.ts负责 HTTP 边界,bridge/useXxx.ts负责数据桥接,ui/XxxView/index.tsx只做渲染。 - PR 范围(PR Scope):每个 PR 只有一条主线,明确写出"做什么"与"不做什么"。Service 迁移、视觉重设计、路由重构不要混在同一个 PR。
- 验证计划(Verification Plan):必须可复现——自动化测试命令、Storybook 验证点、人工操作路径、不能回归的旧行为。
第三步:按标准结构落代码 📂
新增业务能力优先采用如下目录结构(以 packages/dmworkmcp 这类模块为例):
packages/<module>/src/
Service/ # HTTP 边界:endpoint、参数、响应类型
bridge/ # 数据桥接:types.ts + use*.ts
ui/ # 纯展示组件:index.tsx + index.css + stories
features/ # 业务容器,连接 bridge 与 ui
i18n/ # 模块自有的中英文文案
__tests__/ # 行为测试
三条核心规则:
- Service 收口所有接口:Service 内使用
APIClient.shared,方法用业务语义命名(如getUserProfile);UI、features、VM 一律调用 Service 方法,禁止在组件里直接拼接口路径或调用WKApp.apiClient。 - bridge 与 ui 分离:
bridge/负责调用 Service、管理 loading/error/分页等状态、把 API 模型转成视图模型;ui/只从 props 渲染,不 import Service、不读路由与登录态。 - 路由保持干净:新路由不得在 URL 中暴露
sid等内部参数;独立系统(如/space)走整页导航,不要塞进宿主路由。
模块对外只有一个注册入口 module.tsx(如 packages/dmworkmcp/src/module.tsx),负责菜单、路由与 i18n 命名空间的挂载,不要把页面业务逻辑写进 module.tsx。
第四步:UI、主题与国际化规范
写 UI 时 OCTO 有几条"硬规矩",违反它们大概率过不了评审:
- 颜色、间距、圆角一律用 token(如
var(--wk-brand-primary)),禁止硬编码色值;新颜色先加到 packages/dmworkbase/src/theme/ 再引用。 - 禁止
!important、禁止直接覆盖 Semi Design 内部 class;主题切换用body[theme-mode=dark],不用媒体查询。 - 用户可见文案必须走 i18n:模块自带
i18n/zh-CN.json与en-US.json,改完文案运行pnpm i18n:check校验。多语言规范详见 docs/i18n-agent-guide.md。 - 新组件先写 Story 再接业务:默认态、空态、加载态、错误态、长文本、亮/暗主题都要覆盖;本地用
pnpm storybook在 16006 端口验证。
第五步:多层验证,确保可复现
OCTO 的测试是三层结构,验证计划里要写清你跑了哪几层:
| 层级 | 命令 | 覆盖内容 |
|---|---|---|
| 单元测试 | pnpm --filter @dmwork/mcp test |
Service 端点与参数、bridge 状态、组件交互 |
| Storybook | pnpm storybook |
组件各状态在亮/暗主题下的渲染 |
| E2E | pnpm test:e2e(Playwright) |
真实浏览器里的完整用户路径 |
E2E 基建集中在 apps/web/e2e-kit/,包含用例规范(case-specs/)、MSW mock handlers(msw-handlers/)与多份 Playwright 配置。新增 Service 方法至少要补一个单测,覆盖 endpoint 与关键参数。
第六步:规范提交与 Pull Request
分支与提交遵循 Conventional Commits,详见 CONTRIBUTING.zh.md 与 DEVELOPMENT.md 第七章:
- 分支命名:
feat/描述、fix/描述、chore/描述、refactor/描述 - 提交信息:
feat(scope): ...、fix(scope): ...、docs(scope): ... - PR 描述建议包含 Summary / Scope / Out of scope / Risk areas / Verification 五段,UI 变化附截图,PR 描述使用英文
合并前必须通过 CI 的 Build 与 code-review 检查,并获得 maintainer 的 approve;分支过旧需要先 rebase 到 main,最终采用 squash merge 保持历史线性。社区承诺每个 PR 在 3 个工作日内完成首次评审,如果超时没有回应,可以在评论区礼貌 ping 一下——这是被鼓励的。
提交前自查清单 ✅
- [ ] 四件套(行为清单、文件地图、PR 范围、验证计划)完整
- [ ] 该能力只有一个用户可见入口
- [ ] 新接口全部收口在
Service/,UI 不直接拼接口 - [ ] 新文案已走 i18n,
pnpm i18n:check通过 - [ ] 新 UI 有 Story 覆盖(或说明了为什么不需要)
- [ ] 单测 + 人工路径均可复现,PR 里写明了影响范围(模块 / 共享层 / 路由 / 登录态)
按这套流程走,你的贡献会更快通过评审。祝你在 OCTO 的第一个 PR 顺利合入!


