# 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。