如何为OCTO贡献代码:新模块开发指南的完整工作流

原创2026-10-13 15:54:582,150 阅读

如何为OCTO贡献代码:新模块开发指南的完整工作流

本文为首次参与 OCTO 开源项目的开发者梳理一套完整的 octo-web 代码贡献流程:从环境准备、新模块开发指南要求的"四件套"准备,到模块目录规范、验证与 PR 提交,帮助你在提交第一个 PR 前就少走弯路。octo-web 是 OCTO 开放工作平台的 Web 与桌面(Electron)客户端,基于 React + TypeScript 构建,并内置一流的 AI Agent 交互体验。

OCTO 客户端主界面,包含会话列表与消息区,贡献新模块时需理解宿主壳与模块的挂载关系

为什么贡献前必须先读「新模块开发指南」

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 草稿或实现笔记中先写清楚四样东西——写不清楚,说明范围就没准备好:

  1. 行为清单(Behavior List):用户能看到什么、能点什么。包括入口位置(菜单/路由/按钮)、主路径、空态/加载/错误态、是否依赖登录态或当前 Space、跳转是应用内路由还是整页导航。
  2. 文件地图(File Map):计划新增/修改的每个文件及其职责,例如 Service/XxxService.ts 负责 HTTP 边界,bridge/useXxx.ts 负责数据桥接,ui/XxxView/index.tsx 只做渲染。
  3. PR 范围(PR Scope):每个 PR 只有一条主线,明确写出"做什么"与"不做什么"。Service 迁移、视觉重设计、路由重构不要混在同一个 PR。
  4. 验证计划(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)走整页导航,不要塞进宿主路由。

OCTO 的 MCP 市场模块页面,展示模块的侧边栏入口、列表卡片与详情查看,是新模块开发的典型样例

模块对外只有一个注册入口 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 智能总结模块的模板卡片界面,展示亮色主题下的卡片布局与交互状态,可作为 UI Story 覆盖效果的参考

第五步:多层验证,确保可复现

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 顺利合入!

登录后查看全文
octo-web