vifo
19de7e24ec
从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
8.0 KiB
8.0 KiB
OpenCode 多仓库操作指南
版本: v1.0
创建日期: 2026-06-04
适用: rui 项目前后端分离开发团队
一、项目结构概览
rui 项目采用多仓库架构：
~/rhkj/
├── spring-ai/ # 后端仓库（Java/Spring）
│ ├── backend/ # 基础框架
│ ├── app/ # 应用模块
│ └── docs/ # 文档
│
└── rui-frontend/ # 前端仓库（Vue/Node.js）
├── admin-ui/ # 管理后台
├── cashier-mobile/ # 收银移动端
└── customer-mobile/ # 顾客端
原则：一个 OpenCode 会话只处理一个仓库。
二、启动 OpenCode 的正确姿势
2.1 后端开发（spring-ai）
# 1. 进入后端目录
cd /Users/zhangsheng/rhkj/spring-ai
# 2. 启动 OpenCode（命令行方式）
opencode
# 3. 会话启动后，明确告知角色
启动时输入（粘贴到 OpenCode 对话框）：
你现在进入【后端开发模式】。
工作目录：/Users/zhangsheng/rhkj/spring-ai
负责范围：backend/ 和 app/ 目录下的 Java 代码
技术栈：Spring Boot 4.x、Spring Cloud、MyBatis Plus、JDK 21
规则：
1. 只能修改 backend/ 和 app/ 下的代码
2. 发现前端需求时，提醒用户创建 Gitee Issue
3. 编码规范参考 docs/AGENTS.md
当前任务：【在这里描述你的具体任务】
2.2 前端开发（rui-frontend）
# 1. 进入前端目录
cd /Users/zhangsheng/rhkj/rui-frontend
# 2. 启动 OpenCode
opencode
# 3. 会话启动后，明确告知角色
启动时输入（粘贴到 OpenCode 对话框）：
你现在进入【前端开发模式】。
工作目录：/Users/zhangsheng/rhkj/rui-frontend
负责范围：admin-ui/、cashier-mobile/、customer-mobile/
技术栈：Vue 3、TypeScript、Element Plus、Vite、pnpm
规则：
1. 只能修改前端项目下的代码
2. 需要后端接口时，在 spring-ai 仓库创建 Gitee Issue
3. 编码规范参考 AGENTS.md
4. 使用 pnpm workspace 管理多项目
当前任务：【在这里描述你的具体任务，如：开发用户管理页面】
2.3 框架开发（仅修改 backend/）
你现在进入【框架开发模式】。
工作目录：/Users/zhangsheng/rhkj/spring-ai
负责范围：仅 backend/ 目录
角色：基础框架维护者
规则：
1. 只能修改 backend/ 下的代码
2. 不修改任何 app/ 目录下的业务代码
3. 保持框架的通用性和向后兼容性
4. 修改公共接口时，评估对 app/ 的影响
当前任务：【描述框架任务】
三、切换工作流的正确方式
❌ 错误示范
在一个 OpenCode 会话中：
用户：帮我修改后端接口
AI：好的，已修改 backend/xxx.java
用户：再帮我改一下前端页面
AI：好的，已修改 admin-ui/xxx.vue ← 错误！上下文已污染
✅ 正确示范
场景 1：同一仓库内切换任务
如果任务相关（如修改后端接口 + 对应单元测试），可以在同一会话中完成。
如果任务不相关（如用户管理 + 订单管理），建议：
用户：/new
AI：已创建新会话
用户：【输入新的任务描述】
场景 2：跨仓库协作
# 后端仓库会话
用户：开发用户查询接口
AI：已完成，接口路径：GET /user/admin/list
# 需要前端对接时
用户：需要前端开发列表页面
AI：请创建新会话处理前端任务。
在 rui-frontend 目录启动 OpenCode，输入前端开发模式提示词。
接口文档：http://localhost:8080/doc.html#/user/list
# 用户切换到前端仓库，新建会话
用户：/new
【进入 rui-frontend 目录，启动新 OpenCode 会话】
用户：根据接口文档开发用户列表页面
AI：好的，开始开发前端页面...
四、跨仓库通信机制
4.1 前端需要后端接口
前端会话中：
我需要后端提供用户批量导入接口，参数是 Excel 文件
OpenCode 应该回答：
请在 spring-ai 仓库创建 Issue，使用模板：api_request.md
Issue 内容：
标题：[API-REQ] 用户模块需要批量导入接口
内容：...
创建后，在 backend/ 开发会话中处理该 Issue
4.2 后端接口完成通知前端
后端会话中：
接口已实现，Swagger 地址：/doc.html#/user/import
请通知前端团队进行对接
OpenCode 应该：
已在 Issue 中回复前端团队。
前端可以在 rui-frontend 仓库的新会话中进行对接开发。
五、目录访问限制检查
启动会话后，可以让 OpenCode 自我检查：
请确认你的工作范围：
1. 可以修改哪些目录？
2. 不能修改哪些目录？
3. 如果需要跨仓库协作，应该怎么做？
期望回答：
1. 可修改：backend/、app/（后端模式）或 admin-ui/（前端模式）
2. 不可修改：frontend/（后端模式）或 backend/（前端模式）
3. 跨仓库协作：通过 Gitee Issue 进行
六、常见问题
Q1: 我不小心在错误目录启动了 OpenCode，怎么办？
答：
- 保存当前对话（如有重要信息）
- 关闭当前 OpenCode 窗口
- 切换到正确目录重新启动
- 使用
/new创建新会话
Q2: 一个功能需要同时修改前后端，怎么操作？
答：
-
方法 A（推荐）：先在一个仓库完成，提交后切换到另一个仓库
- 在 spring-ai 开发接口 → 提交 PR
- 在 rui-frontend 开发页面 → 提交 PR
-
方法 B（并行）：两个 OpenCode 窗口同时工作
- 窗口 1：spring-ai 目录，开发后端
- 窗口 2：rui-frontend 目录，开发前端
-
不要：在一个会话中同时修改两个仓库
Q3: OpenCode 能记住跨仓库的上下文吗？
答：不能。每个 OpenCode 会话是独立的：
- 不同目录 = 不同上下文
- 即使同一个目录，
/new后也是全新上下文 - 需要人工传递关键信息（如接口文档链接）
Q4: 怎么快速查看当前在哪个仓库？
答：在 OpenCode 中输入：
请告诉我当前工作目录和可修改范围
Q5: 可以用同一个 OpenCode 窗口切换目录吗？
答：不建议。OpenCode 启动时会锁定工作目录。如果需要切换：
- 关闭当前窗口
cd到新目录- 重新启动 OpenCode
七、快捷键和命令速查
| 操作 | 命令 |
|---|---|
| 创建新会话 | /new |
| 查看当前目录 | pwd |
| 查看文件树 | tree -L 2 |
| 查看 Git 状态 | git status |
| 切换分支 | git checkout branch-name |
八、最佳实践
- 明确角色：启动时明确告知 OpenCode 当前角色和范围
- 单一职责：一个会话只做一件事（一个功能/一个 Bug）
- 及时提交：完成一个功能后立即
git commit，不要积压 - Issue 驱动：跨仓库需求通过 Issue 追踪，不要口头传递
- 文档优先：复杂功能先写设计文档，再编码
- 定期 /new：对话超过 20-30 轮后，新建会话保持上下文清晰
九、模板库
启动模板
保存以下模板，启动时直接粘贴：
后端启动模板：
你现在进入【后端开发模式】。
工作目录：/Users/zhangsheng/rhkj/spring-ai
技术栈：Spring Boot 4.x、JDK 21、MyBatis Plus
规则：只能修改 backend/ 和 app/ 目录
当前任务：【填写】
前端启动模板：
你现在进入【前端开发模式】。
工作目录：/Users/zhangsheng/rhkj/rui-frontend
技术栈：Vue 3、TypeScript、Element Plus、Vite
规则：只能修改前端项目目录
当前任务：【填写】
十、相关文档
提示：本文档是活文档，根据团队实践持续更新。如有建议请提交 PR。