GeekAI 仓库开发协作指南:从模块结构到构建测试的完整工程规范
GeekAI 仓库开发协作指南:从模块结构到构建测试的完整工程规范
本文以仓库根目录的 AGENTS.md 为核心骨架,系统梳理 GeekAI(geekai)项目的工程组织方式:四大代码模块如何分工、本地开发与多架构构建命令、前后端编码规范、测试与提交(Pull Request)流程,以及密钥与敏感配置的安全处置原则。读者可据此快速理解仓库全貌,并照着命令清单在本机跑通「克隆 → 开发 → 构建 → 提交」的完整链路。
一、仓库全景:四个工程模块与辅助目录
GeekAI 是一个 Go + Vue3 的全栈 AI 创作平台,代码仓库从顶层就按「端」拆分,职责边界清晰。以当前仓库快照为准,顶层目录如下:
| 目录 | 角色 | 说明 |
|---|---|---|
api/ |
后端服务 | Go + Gin 实现的 API 服务,含 core/、handler/、service/、store/ 四层,配置与构建脚本同置 |
web/ |
前端应用 | Vue3 + Vite 工程,src/ 为源码,public/ 为静态资源,构建产物输出到 dist/ |
desktop/ |
桌面客户端 | Electron 壳,入口为 desktop/index.js,可打包多平台安装包 |
config/ |
全局配置 | 存放全局 YAML 配置(当前快照中 config/config.yaml 为空占位文件,实际运行配置以 TOML 为主) |
database/ |
SQL 脚本 | 数据库初始化脚本,如 database/geekai_plus-v4.2.6.sql |
docs/ |
文档 | 需求与部署相关文档 |
docker/ |
容器编排 | docker/docker-compose.yaml 一键拉起全套服务 |
需要说明的是,AGENTS.md 中提到的 miniprogram/(小程序壳)与 build/(Dockerfile、安装脚本)目录在当前仓库快照中并未包含,实际协作时以现有目录为准。
1.1 后端 api/:Gin + uber-go/fx 依赖注入
后端采用分层架构,api/main.go 是唯一入口,它使用 uber-go/fx 完成依赖注入与生命周期管理(api/go.mod 中声明 go 1.24.0,并引入 gin、gorm、redis 等核心依赖):
core/:业务内核。app_server.go负责构建 Gin Engine 并注册全局中间件;config.go负责 TOML 配置的加载与持久化;types/定义全部配置与业务类型(见 api/core/types/config.go)。handler/:控制器层。普通用户 API 与admin/子目录下的管理后台 API 分离,每个 Handler 通过RegisterRoutes()注册到/api/v1/...路由组。service/:业务与三方集成。涵盖 AI 绘画(mj、jimeng)、音乐(suno)、视频(video)、PPT 生成、短信(sms)、支付(payment)、对象存储(oss)、文本审查(moderation)等。store/:数据访问层。model/为 GORM 实体,vo/为视图对象,mysql.go、redis.go、leveldb.go分别封装 MySQL、Redis 与本地 LevelDB。
main.go 中可以看到大量 fx.Provide(...) 与 fx.Invoke(...),例如:
- 通过
fx.Provide(core.NewServer)创建 Gin 服务; - 通过
fx.Invoke(func(s *core.AppServer, ...) { h.RegisterRoutes() })批量注册各模块路由; - 各类 AI 任务服务(MJ、Suno、Video、Jimeng)在启动时即调用
Run()、SyncTaskProgress()、DownloadImages()等协程任务。
1.2 前端 web/:Vue3 + Vite + Pinia
前端源码集中在 web/src/,采用 Vue 3 Composition API,桌面端 UI 基于 element-plus,移动端基于 Vant(见 web/README.md)。状态管理使用 Pinia(web/src/store/),路由使用 vue-router(web/src/router.js)。构建配置见 web/vite.config.js:开发服务器默认监听 8888 端口,并将 /api 与 /static/upload/ 反向代理到后端地址(默认 http://localhost:5678),@ 与 ~@ 均指向 src/ 目录,产物输出到 dist/。
1.3 桌面端 desktop/:Electron 壳工程
desktop/package.json 定义了两条核心命令:start(electron .)用于本地调试,package(electron-builder)用于打包。构建配置中,Linux 目标为 AppImage、macOS 目标为 dmg、Windows 目标为 NSIS,图标分别使用 desktop/icons/logo.png、desktop/icons/logo.icns、desktop/icons/logo.ico。入口 desktop/index.js 实现典型的「加载页 + 主窗口」流程:启动时先隐藏主窗口并加载 loading.html,主窗口 loadURL 目标站点,待 did-finish-load 事件触发后最大化显示主窗口并关闭加载窗口。
二、构建、测试与开发命令速查
AGENTS.md 给出的命令全部可以在仓库中得到印证,以下逐一展开。
2.1 一键启动:docker-compose
docker-compose up -d
docker/docker-compose.yaml 定义了 5 个服务:MySQL 8.0.33(含 mysql_native_password 认证、healthcheck)、Redis 6.0.6(带密码、healthcheck)、Apache Tika(文档解析,端口 9998)、geekai-api 后端(端口 5678,通过 depends_on 等待数据库与缓存就绪)与 geekai-web 前端(Nginx,端口 8080)。后端容器通过环境变量 CONFIG_FILE=config.toml 指定配置,并把宿主机 ./conf/config.toml 挂载进容器(模板见 docker/conf/config.toml)。注意:拉起前需提前准备好 MySQL、Redis 与各模型平台密钥,并先构建或拉取对应镜像。
2.2 后端:热调试与多架构交叉构建
cd api && go run main.go
go run main.go 从当前目录读取 config.toml(默认配置文件名)。如果文件不存在,api/core/config.go 的 LoadConfig 会自动生成一份默认配置。仓库还提供了 api/fresh.conf,可配合 fresh 工具实现文件变更后的自动重启,实现热调试。
多架构构建使用 api/Makefile:
cd api && make amd64 # CGO_ENABLED=0 GOOS=linux GOARCH=amd64
cd api && make arm64 # CGO_ENABLED=0 GOOS=linux GOARCH=arm64 GOARM=7
两个 target 均关闭 CGO 并以 -ldflags "-s -w" 瘦身,产物为 api/bin/geekai-linux(make 默认同时构建 amd64 与 arm64),方便打进不同架构的容器镜像。这也与 docker-compose 中 geekai-api:v4.3.1-amd64 这类按架构打标签的镜像命名方式对应。
2.3 前端:安装、开发与构建
cd web && pnpm install
cd web && pnpm dev --host # 或直接 pnpm dev(脚本内已含 --host)
cd web && pnpm build
cd web && pnpm lint
以上命令与 web/package.json 的 scripts 一一对应:dev 为 vite --host,build 为 vite build(输出到 web/dist/),lint 为 eslint . --ext .vue,.js,.jsx,.cjs,.mjs。构建产物可被 api/static/ 或 desktop/ 引用,实现一套前端多端复用。
2.4 桌面端:调试与打包
cd desktop && npm install
cd desktop && npm run start # electron . 调试
cd desktop && npm run package # electron-builder 打包多平台安装包
打包产物目标与平台对应关系已在上文 1.3 节说明,package 命令会根据当前运行平台生成对应格式(如 Linux 下产出 AppImage)。
三、编码风格与命名规范
3.1 Go 后端
- 所有 Go 代码必须经过
gofmt/goimports,统一 tab 缩进与驼峰命名; - HTTP 路由遵循
/api/v1/resources模式,例如 api/handler/ppt_task_handler.go 中的/api/v1/tasks路由组; - 每个 handler 类型命名为
ResourceHandler并实现RegisterRoutes(),与路由资源一一对应,这一约定从main.go中大量fx.Provide(handler.NewXxxHandler)的写法可以得到印证。
3.2 Vue 前端
- 组件文件使用 PascalCase(如
ChatPanel.vue),与web/src/components/下的实际文件命名一致; - Pinia store 与工具文件采用 kebab-case(如
chat-session.ts),对应web/src/store/下的 session.js、sidebar.js 等文件; - 样式统一经由 ESLint、Tailwind(web/tailwind.config.js)与 web/postcss.config.js 约束,
.vue、.js等后缀文件均在 lint 检查范围内。
四、测试指南
AGENTS.md 明确了质量底线:
cd api && go test ./... -race
这是后端的最低要求。新增 service/handler 时需补 _test.go 文件,并用 mock 隔离第三方 API(避免真实调用外部 AI 平台);涉及时序逻辑的场景可新增 Test*Integration 用例验证。当前快照中 api/ 下暂未发现已提交的 _test.go 单测文件,api/test/ 目录是一个独立的调试程序 api/test/test.go,用于验证 Sora 服务从生成文本中抽取视频下载地址的辅助逻辑,可视为验证型小工具而非正式测试套件——正式单测仍按规范从零补齐。
前端暂未启用单测框架,因此最低要求是 pnpm lint 通过,并在 PR 中附关键页面截图或录屏证明交互可用;桌面端若修改了构建脚本,需在 macOS/Linux/Windows 三平台中至少验证一个安装包可用。
五、提交与 Pull Request 规范
- 提交信息使用中文动词开头、聚焦单一变更,允许加子系统前缀,例如
web: 优化聊天动画,仓库历史中即有「支持腾讯云短信服务」这类先例; - PR 描述必须包含:变更背景、实现概述、验证方式(命令、截图或日志)以及关联的 issue/任务号;
- 涉及配置或部署脚本的变更,还需要额外说明回滚流程,并 @ 相关 reviewer。
这套规范的本质是「可回溯、可验证、可回滚」,配合上面的测试底线,保证多人在同一仓库上的协作质量。
六、安全与配置提示
AGENTS.md 对敏感信息的管理提出了三条硬性要求,仓库配置结构也从机制上予以支持:
- 禁止提交真实密钥。后端采用 TOML 配置,开发时复制 api/config.sample.toml 为私有
config.toml(生产环境则使用 docker/conf/config.toml 作为挂载模板),并用git update-index --skip-worktree将私有文件标记为本地忽略,避免误提交。配置文件中的SecretKey是 JWT 授权密钥,注释明确要求「生产环境请务必更换」。 - 凭证统一入 Vault 或 CI Secret。代码中仅引用占位常量。从 api/core/types/config.go 可见,SMTP、支付(支付宝/微信/EPay)、OSS、短信等敏感配置均有独立配置结构,并在 api/core/config.go 的
LoadSystemConfig中从数据库按配置键(system、oss、payment、smtp、sms、captcha、wx_login等)逐项加载,运行期敏感参数不写死在源码里。 - 文档同步记录。新增敏感字段时需在
docs/中同步记录字段含义与启用步骤,方便后续维护者照文档完成配置。
七、小结
AGENTS.md 本质上是 GeekAI 仓库的「协作契约」,而这份契约的每条约定都能在源码与配置文件中找到落点:api/Makefile 印证多架构构建、web/package.json 印证前端脚本、desktop/package.json 印证 Electron 打包目标、docker/docker-compose.yaml 印证一键编排、api/core/config.go 与 api/config.sample.toml 印证配置加载与密钥隔离。按本文的顺序走一遍「读结构 → 跑命令 → 守规范 → 提 PR」,即可无缝接入该项目的日常开发与贡献流程。