rui-docs/backend/guides/AI开发环境配置手册.md

AI 开发环境配置手册

适用对象: 业务模块开发者（支付、收银台等）
版本: v1.0
更新日期: 2026-06-03

---

目录

1. 概述
2. 环境准备
3. 仓库克隆与配置
4. GitNexus 索引配置
5. AI 开发工作流
6. 常见问题

---

一、概述

1.1 背景

项目已拆分为独立仓库：

仓库	地址	用途	负责人
rui-framework	git@gitee.com:pigeon/rui-framework.git	框架（backend）	框架维护者
rui-payment	git@gitee.com:pigeon/rui-payment.git	支付模块	员工A
rui-cashier	git@gitee.com:pigeon/rui-cashier.git	收银台模块	员工B

业务开发者只需要维护自己的业务仓库，框架依赖通过 Maven 仓库自动下载。

1.2 为什么需要本地 clone 框架仓库？

AI（OpenCode）基于 GitNexus 知识图谱工作：

• 业务代码索引：理解业务逻辑、生成业务代码
• 框架代码索引：理解框架 API（如 AuthUtil、BizException）

框架代码以 jar 包 形式通过 Maven 引入，AI 无法直接解析 jar 中的 class 文件。因此需要在本地 clone 框架仓库作为只读参考，供 AI 索引和查询。

---

二、环境准备

2.1 基础工具

工具	最低版本	验证命令	说明
JDK	21	java -version	必须
Maven	3.9	mvn -version	必须
Git	2.40	git --version	必须
Node.js	18	node --version	GitNexus 需要

2.2 配置 Maven 仓库

确保 ~/.m2/settings.xml 已配置公司 Nexus 仓库认证（向运维获取）：

<settings>
  <servers>
    <server>
      <id>releases</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
    <server>
      <id>snapshots</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
  </servers>
</settings>

注意：框架 rui-parent 和 rui-common-* 已发布到 Nexus，首次编译时会自动下载。

---

三、仓库克隆与配置

3.1 目录结构

~/work/
├── rui-framework/      # 框架仓库（只读参考）
│   ├── backend/
│   └── .gitnexus/      # 框架代码索引
└── rui-payment/        # 业务仓库（主要工作区）
    ├── pom.xml
    ├── rui-payment-api/
    └── .gitnexus/      # 业务代码索引

3.2 克隆仓库

步骤1：克隆框架仓库（所有员工都需要）

git clone git@gitee.com:pigeon/rui-framework.git ~/work/rui-framework

步骤2：克隆业务仓库

# 员工A（支付）
git clone git@gitee.com:pigeon/rui-payment.git ~/work/rui-payment

# 员工B（收银台）
git clone git@gitee.com:pigeon/rui-cashier.git ~/work/rui-cashier

3.3 验证编译

cd ~/work/rui-payment
mvn clean compile -DskipTests

预期输出：BUILD SUCCESS

如果报错找不到 rui-parent，联系框架维护者确认已发布到 Nexus。

---

四、GitNexus 索引配置

4.1 什么是 GitNexus？

GitNexus 是 AI 的代码智能引擎，通过索引代码库构建知识图谱，帮助 AI：

• 理解代码结构（类、方法、调用关系）
• 分析修改影响（改 A 会波及 B、C）
• 安全导航（不重命名、不遗漏引用）

4.2 索引框架仓库

cd ~/work/rui-framework
npx gitnexus analyze

预期输出：

Repository indexed successfully
7,504 nodes | 15,350 edges | 268 clusters | 300 flows

4.3 索引业务仓库

cd ~/work/rui-payment
npx gitnexus analyze

预期输出：

Repository indexed successfully
1,601 nodes | 3,921 edges | 63 clusters | 131 flows

4.4 验证索引

npx gitnexus list

预期输出：

  Indexed Repositories (2)

  rui-framework
    Path:    ~/work/rui-framework
    Stats:   7504 symbols, 15350 edges

  rui-payment
    Path:    ~/work/rui-payment
    Stats:   1601 symbols, 3921 edges

4.5 索引维护

场景	操作
业务代码修改后	cd ~/work/rui-payment && npx gitnexus analyze
框架升级后	cd ~/work/rui-framework && git pull && npx gitnexus analyze
索引损坏	npx gitnexus clean && npx gitnexus analyze
检查状态	npx gitnexus status

---

五、AI 开发工作流

5.1 启动 AI

在业务仓库目录下启动 IDE/OpenCode：

cd ~/work/rui-payment
# 启动 IDE 或 OpenCode

AI 默认使用当前目录的索引（rui-payment）。

5.2 开发业务代码（默认模式）

AI 自动基于 rui-payment 索引工作：

用户：帮我写一个订单查询接口
AI：基于 rui-payment 索引分析...
    生成 OrderController、OrderService、OrderMapper

5.3 查询框架 API（跨仓库模式）

当需要理解框架源码时，在对话中指定 repo 参数：

查询类定义：

gitnexus_context({
  name: "AuthUtil",
  repo: "rui-framework"
})

搜索功能实现：

gitnexus_query({
  query: "分布式锁 Redisson",
  repo: "rui-framework"
})

分析修改影响：

gitnexus_impact({
  target: "BaseController",
  repo: "rui-framework",
  direction: "upstream"
})

查看执行流程：

gitnexus_query({
  query: "用户登录认证流程",
  repo: "rui-framework"
})

5.4 常用查询对照表

我想查...	命令	仓库
AuthUtil.getUserId() 怎么用	gitnexus_context({name:"AuthUtil", repo:"rui-framework"})	framework
业务异常怎么抛	gitnexus_query({query:"BizException", repo:"rui-framework"})	framework
分布式锁怎么加	gitnexus_query({query:"Redisson分布式锁", repo:"rui-framework"})	framework
支付订单状态流转	gitnexus_query({query:"订单状态", repo:"rui-payment"})	payment
修改订单会影响哪里	gitnexus_impact({target:"OrderService", direction:"upstream"})	payment
收银台缓存策略	gitnexus_query({query:"缓存 CacheKeys", repo:"rui-cashier"})	cashier

5.5 工作流示例

场景：开发一个支付退款接口

1. 员工A在 ~/work/rui-payment 中启动 AI

2. 员工：帮我写退款接口
   AI基于 rui-payment 索引分析业务代码...

3. 员工：退款时需要校验用户权限吗？
   AI：建议调用 AuthUtil.getUserId()...
   
4. 员工：AuthUtil 有哪些方法？
   【AI执行】gitnexus_context({name:"AuthUtil", repo:"rui-framework"})
   AI：AuthUtil 提供 getUserId()、getTenantId()、getUser()...

5. 员工：退款金额用 BigDecimal 吗？
   【AI执行】gitnexus_query({query:"金额计算 BigDecimal", repo:"rui-framework"})
   AI：框架规范要求金额使用 DECIMAL(19,4)，Java 对应 BigDecimal...

6. AI 生成完整代码

---

六、常见问题

Q1：AI 提示 "Index is stale"

原因：代码已修改但索引未更新。
解决：

cd ~/work/你的仓库
npx gitnexus analyze

Q2：查询框架代码时提示 "Repo not found"

原因：框架仓库未索引或索引名称不对。
解决：

# 查看所有索引
npx gitnexus list

# 确认 rui-framework 存在
# 如果不存在，重新索引框架仓库
cd ~/work/rui-framework
npx gitnexus analyze

Q3：编译时找不到 rui-parent

原因：框架未发布到 Nexus，或 Maven 仓库配置错误。
解决：

1. 确认 ~/.m2/settings.xml 已配置 Nexus 认证
2. 联系框架维护者确认已执行 mvn clean deploy
3. 临时方案：本地 clone framework 后执行 mvn clean install -DskipTests

Q4：框架升级后 AI 给出的 API 已过时

原因：框架索引未更新。
解决：

cd ~/work/rui-framework
git pull origin main
npx gitnexus analyze

Q5：发现框架代码有 Bug

禁止：直接修改 ~/work/rui-framework 代码。
正确做法：

1. 在业务仓库记录：docs/框架问题记录.md
2. 通知框架维护者
3. 等待框架修复并发布新版本

Q6：AI 回答中引用了不存在的框架类

原因：业务仓库依赖的框架版本与本地索引的框架版本不一致。
解决：

1. 检查 pom.xml 中 parent version（如 1.0.0）
2. 确认 ~/work/rui-framework 的代码版本一致
3. 如果不一致，更新 framework clone 并重新索引

---

附录

A. 各仓库索引名称

仓库路径	索引名称	说明
~/work/rui-framework	rui-framework	基于 pom.xml artifactId
~/work/rui-payment	rui-payment	基于目录名
~/work/rui-cashier	rui-cashier	基于目录名

B. 快速命令速查

# 克隆所有仓库（新员工一次性执行）
git clone git@gitee.com:pigeon/rui-framework.git ~/work/rui-framework
git clone git@gitee.com:pigeon/rui-payment.git ~/work/rui-payment

# 初始化索引（一次性执行）
cd ~/work/rui-framework && npx gitnexus analyze
cd ~/work/rui-payment && npx gitnexus analyze

# 日常开发
mvn clean install -DskipTests

# 更新索引
npx gitnexus analyze

C. 相关文档

文档	路径
GitNexus 使用指南	docs/gitnexus-guide.md
环境搭建指南	docs/environment-setup.md
项目规范	AGENTS.md

---

提示：本手册随项目演进持续更新。如有问题，联系框架维护者或技术负责人。