vifo
a7f3ee3565
同步仓库名称变更，涉及 16 个文件 66 处引用： - ai-skills: 菜单配置 - backend/guides: AI操作手册、环境配置、部署、gitnexus、opencode 工作流 - backend: 模块创建规则、通信规范、协作工作流、实施规范 - frontend: 收银设计、管理后台实施计划 - standards: 数据库设计规范
323 lines
8.0 KiB
Markdown
323 lines
8.0 KiB
Markdown
# OpenCode 多仓库操作指南
|
||
|
||
> **版本**: v1.0
|
||
> **创建日期**: 2026-06-04
|
||
> **适用**: rui 项目前后端分离开发团队
|
||
|
||
---
|
||
|
||
## 一、项目结构概览
|
||
|
||
rui 项目采用**多仓库**架构：
|
||
|
||
```
|
||
~/rhkj/
|
||
├── rui-framework/ # 后端仓库（Java/Spring）
|
||
│ ├── backend/ # 基础框架
|
||
│ ├── app/ # 应用模块
|
||
│ └── docs/ # 文档
|
||
│
|
||
└── rui-frontend/ # 前端仓库（Vue/Node.js）
|
||
├── admin-ui/ # 管理后台
|
||
├── cashier-mobile/ # 收银移动端
|
||
└── customer-mobile/ # 顾客端
|
||
```
|
||
|
||
**原则**：一个 OpenCode 会话只处理一个仓库。
|
||
|
||
---
|
||
|
||
## 二、启动 OpenCode 的正确姿势
|
||
|
||
### 2.1 后端开发（rui-framework）
|
||
|
||
```bash
|
||
# 1. 进入后端目录
|
||
cd /Users/zhangsheng/rhkj/rui-framework
|
||
|
||
# 2. 启动 OpenCode（命令行方式）
|
||
opencode
|
||
|
||
# 3. 会话启动后，明确告知角色
|
||
```
|
||
|
||
**启动时输入**（粘贴到 OpenCode 对话框）：
|
||
|
||
```
|
||
你现在进入【后端开发模式】。
|
||
|
||
工作目录：/Users/zhangsheng/rhkj/rui-framework
|
||
负责范围：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）
|
||
|
||
```bash
|
||
# 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. 需要后端接口时，在 rui-framework 仓库创建 Gitee Issue
|
||
3. 编码规范参考 AGENTS.md
|
||
4. 使用 pnpm workspace 管理多项目
|
||
|
||
当前任务：【在这里描述你的具体任务，如：开发用户管理页面】
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 框架开发（仅修改 backend/）
|
||
|
||
```
|
||
你现在进入【框架开发模式】。
|
||
|
||
工作目录：/Users/zhangsheng/rhkj/rui-framework
|
||
负责范围：仅 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 应该回答：
|
||
```
|
||
请在 rui-framework 仓库创建 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，怎么办？
|
||
|
||
**答**：
|
||
1. 保存当前对话（如有重要信息）
|
||
2. 关闭当前 OpenCode 窗口
|
||
3. 切换到正确目录重新启动
|
||
4. 使用 `/new` 创建新会话
|
||
|
||
### Q2: 一个功能需要同时修改前后端，怎么操作？
|
||
|
||
**答**：
|
||
1. **方法 A（推荐）**：先在一个仓库完成，提交后切换到另一个仓库
|
||
- 在 rui-framework 开发接口 → 提交 PR
|
||
- 在 rui-frontend 开发页面 → 提交 PR
|
||
|
||
2. **方法 B（并行）**：两个 OpenCode 窗口同时工作
|
||
- 窗口 1：rui-framework 目录，开发后端
|
||
- 窗口 2：rui-frontend 目录，开发前端
|
||
|
||
3. **不要**：在一个会话中同时修改两个仓库
|
||
|
||
### Q3: OpenCode 能记住跨仓库的上下文吗？
|
||
|
||
**答**：不能。每个 OpenCode 会话是独立的：
|
||
- 不同目录 = 不同上下文
|
||
- 即使同一个目录，`/new` 后也是全新上下文
|
||
- 需要人工传递关键信息（如接口文档链接）
|
||
|
||
### Q4: 怎么快速查看当前在哪个仓库？
|
||
|
||
**答**：在 OpenCode 中输入：
|
||
```
|
||
请告诉我当前工作目录和可修改范围
|
||
```
|
||
|
||
### Q5: 可以用同一个 OpenCode 窗口切换目录吗？
|
||
|
||
**答**：不建议。OpenCode 启动时会锁定工作目录。如果需要切换：
|
||
1. 关闭当前窗口
|
||
2. `cd` 到新目录
|
||
3. 重新启动 OpenCode
|
||
|
||
---
|
||
|
||
## 七、快捷键和命令速查
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 创建新会话 | `/new` |
|
||
| 查看当前目录 | `pwd` |
|
||
| 查看文件树 | `tree -L 2` |
|
||
| 查看 Git 状态 | `git status` |
|
||
| 切换分支 | `git checkout branch-name` |
|
||
|
||
---
|
||
|
||
## 八、最佳实践
|
||
|
||
1. **明确角色**：启动时明确告知 OpenCode 当前角色和范围
|
||
2. **单一职责**：一个会话只做一件事（一个功能/一个 Bug）
|
||
3. **及时提交**：完成一个功能后立即 `git commit`，不要积压
|
||
4. **Issue 驱动**：跨仓库需求通过 Issue 追踪，不要口头传递
|
||
5. **文档优先**：复杂功能先写设计文档，再编码
|
||
6. **定期 /new**：对话超过 20-30 轮后，新建会话保持上下文清晰
|
||
|
||
---
|
||
|
||
## 九、模板库
|
||
|
||
### 启动模板
|
||
|
||
保存以下模板，启动时直接粘贴：
|
||
|
||
**后端启动模板**：
|
||
```markdown
|
||
你现在进入【后端开发模式】。
|
||
工作目录：/Users/zhangsheng/rhkj/rui-framework
|
||
技术栈：Spring Boot 4.x、JDK 21、MyBatis Plus
|
||
规则：只能修改 backend/ 和 app/ 目录
|
||
当前任务：【填写】
|
||
```
|
||
|
||
**前端启动模板**：
|
||
```markdown
|
||
你现在进入【前端开发模式】。
|
||
工作目录：/Users/zhangsheng/rhkj/rui-frontend
|
||
技术栈：Vue 3、TypeScript、Element Plus、Vite
|
||
规则：只能修改前端项目目录
|
||
当前任务：【填写】
|
||
```
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- [跨团队协作规范](./cross-team-workflow.md)
|
||
- [后端项目规范](../AGENTS.md)
|
||
- [前端项目规范](../../rui-frontend/AGENTS.md)
|
||
- [Gitea 自建 Git 服务器](./self-hosted-git-server.md)
|
||
|
||
---
|
||
|
||
> **提示**：本文档是活文档，根据团队实践持续更新。如有建议请提交 PR。
|