# Lemon Pi 使用与日常开发手册

这份文档面向日常使用者，说明如何安装 Lemon Pi、如何初始化项目、如何选择 `/lemon:*` 命令，以及在实际开发中如何配合 AI 完成项目理解、方案设计、功能开发、审计和提交。

## 1. 安装与更新

先安装 Pi：

```bash
npm install -g @earendil-works/pi-coding-agent@latest
```

安装 Lemon Pi：

```bash
pi install npm:@lemon-pi/lemon-pi
```

更新 Lemon Pi：

```bash
pi update npm:@lemon-pi/lemon-pi
```

卸载 Lemon Pi：

```bash
pi uninstall npm:@lemon-pi/lemon-pi
```

如果需要 CodeGraph 结构化代码探索，安装 CodeGraph CLI：

```bash
npm install -g @colbymchenry/codegraph
```

## 2. 第一次进入项目

进入你的 Lemon 项目目录：

```bash
cd /path/to/lemon-project
pi
```

在 Pi 中运行初始化命令：

```text
/lemon:init
```

初始化会检查和准备：

- 当前项目画像。
- Lemon Pi 所需的 agents/chains。
- 当前项目的 skill registry。
- `lemon_codegraph` 工具是否已注册。
- CodeGraph 索引是否存在。

如果提示 CodeGraph 索引缺失，请在项目目录手动运行：

```bash
codegraph init -i
```

索引建立完成后，`lemon_codegraph` 就可以用于结构化查询。若只是想查看当前状态，可以运行：

```text
/lemon:status
```

## 3. 常用命令

| 命令 | 用途 |
| --- | --- |
| `/lemon:init [path]` | 初始化或检查 Lemon Pi 项目状态。 |
| `/lemon:status` | 查看项目画像、初始化状态和建议入口。 |
| `/lemon:route <需求>` | 默认入口，不确定用哪个命令时使用。 |
| `/lemon:doc <问题>` | 了解项目结构、模块入口、约定和已有能力。 |
| `/lemon:storm <想法>` | 需求还模糊时，用于方案探索和边界收敛。 |
| `/lemon:plan <任务>` | 中等复杂度开发任务，先规划再实现。 |
| `/lemon:spec <任务>` | 复杂模块，先整理需求、设计、任务和验收点。 |
| `/lemon:audit <范围>` | 提交前、上线前或高风险改动审计。 |
| `/lemon:sync <范围>` | 跨工程同步、迁移、对齐上游变更。 |
| `/lemon:commit <范围>` | 整理当前改动并生成本地提交说明。 |

不知道该用哪个命令时，优先用：

```text
/lemon:route 你的需求
```

## 4. 日常开发怎么用

### 了解新项目或新模块

使用：

```text
/lemon:doc 梳理当前项目结构、模块边界和开发入口
```

适合：

- 第一次进入项目。
- 接手陌生模块。
- 查某个接口、页面、菜单、权限、配置的入口。
- 想知道项目里某类能力如何使用。

如果 CodeGraph 索引可用，Lemon Pi 会优先用结构化索引查模块入口、定义、调用链和影响面。

### 需求还没想清楚

使用：

```text
/lemon:storm 我想做一个课程学习数据看板，先帮我收敛方案
```

适合：

- 只有方向，没有明确功能边界。
- 想比较几种实现方案。
- 需要先确认角色、场景、边界、验收标准。

`/lemon:storm` 默认不会直接写代码。方向确认后，再切到 `/lemon:plan` 或 `/lemon:spec`。

### 普通功能开发

使用：

```text
/lemon:plan 给课程分类管理增加后端 CRUD、前端列表、新增编辑删除和按钮权限
```

适合：

- 5 到 15 个文件左右的中等任务。
- 常规 CRUD。
- 前后端联动。
- 菜单、按钮、字典、租户字段等标准业务改动。

推荐做法：

1. 让 AI 先给计划和影响面。
2. 确认计划后再实现。
3. 实现前明确验证方式。
4. 完成后查看测试、构建、接口或页面 smoke 结果。

### 复杂模块开发

使用：

```text
/lemon:spec 设计课程体系管理模块，包含分类、课程、章节、上下架、权限和审计
```

适合：

- 多实体模型。
- 多页面或多接口。
- 涉及权限、租户、字典、菜单、流程、审计。
- 需要先形成需求、设计、任务拆分和验收点。

复杂任务不要一上来要求直接改代码。先让 AI 梳理边界和方案，再进入开发。

### 后端开发

可以直接描述后端目标：

```text
/lemon:route 新增课程分类后端分页接口，包含逻辑删除、租户隔离和统一返回
```

Lemon Pi 会重点关注：

- Controller、Service、Mapper、VO/DTO。
- 分页和统一返回。
- 租户字段、逻辑删除、数据权限。
- SQL、Flyway、Mapper XML。
- 与已有模块和工具类保持一致。

### 前端开发

可以描述页面目标：

```text
/lemon:route 新增课程分类前端列表页，包含搜索、新增、编辑、删除和按钮权限
```

Lemon Pi 会重点关注：

- 页面结构和路由。
- API 调用。
- zvue / option 配置。
- 字典、权限按钮、表格和表单。
- 页面 smoke 验证。

### 查找已有能力，避免重复造轮子

使用：

```text
/lemon:route 帮我找项目里处理 JSON、Bean 拷贝、当前用户和分页条件的工具类，不要重复造轮子
```

适合开发前确认：

- 是否已有工具类。
- 是否已有同类模块。
- 是否可以通过配置解决。
- 是否可以用代码生成器起步。

### 代码生成后的适配

使用：

```text
/lemon:route 根据课程分类表生成 CRUD，并适配当前项目的后端、前端和菜单权限
```

代码生成结果只是起点。后续仍要按当前项目的模块结构、权限规则、接口契约和页面约定进行二次校准。

### 跨工程同步

先做 dry-run 分析：

```text
/lemon:sync dry-run 对比源项目和当前项目的资源模块差异
```

确认路径映射、冲突点和预期变更后，再决定是否应用。

### 提交前审计

使用：

```text
/lemon:audit 审查当前课程分类管理改动
```

建议在这些情况使用：

- 涉及租户、权限、数据权限。
- 涉及菜单、按钮、字典。
- 涉及 SQL、Flyway、Mapper XML。
- 涉及前后端接口契约。
- 改动范围较大。
- 涉及流程审批或状态流转。

### 本地提交说明

使用：

```text
/lemon:commit 当前课程分类管理改动
```

它适合整理当前改动并生成提交说明。推送仍建议由开发者确认后执行。

## 5. CodeGraph 使用说明

Lemon Pi 使用 `lemon_codegraph` 做结构化代码探索。它依赖项目中的 CodeGraph 索引。

首次进入项目时，如果 `/lemon:init` 提示索引缺失，在项目目录执行：

```bash
codegraph init -i
```

如果项目代码有大量变化，可以按需刷新索引：

```bash
codegraph sync
```

如果 CodeGraph 提示旧引擎索引，或你想全量重建：

```bash
codegraph index
```

可以用终端先验证 CodeGraph 是否工作：

```bash
codegraph explore -p . "项目主要模块和入口"
```

## 6. 推荐工作习惯

日常开发建议按这个节奏：

1. 进入项目后先运行 `/lemon:status`，确认项目画像和初始化状态。
2. 陌生模块先用 `/lemon:doc` 查结构，不要直接让 AI 改代码。
3. 需求模糊时先用 `/lemon:storm` 收敛边界。
4. 普通开发用 `/lemon:plan`，复杂模块用 `/lemon:spec`。
5. 实现前确认复用路径和验证方式。
6. 涉及权限、租户、SQL、菜单、字典、流程时，用 `/lemon:audit` 做审计。
7. 提交前让 AI 总结改动、验证结果和残余风险。

## 7. 常见问题

**启动页为什么不显示底层 Lemon 能力？**

这是预期行为。普通用户只需要使用 `/lemon:*` 命令，底层能力由 Lemon Pi 调度。

**`/lemon:init` 要不要写路径？**

通常不用。默认检查当前目录。需要检查其他目录时可以写：

```text
/lemon:init "/path/to/lemon-project"
```

**提示找不到 CodeGraph CLI 怎么办？**

安装 CodeGraph：

```bash
npm install -g @colbymchenry/codegraph
```

然后在项目目录建立索引：

```bash
codegraph init -i
```

**提示 CodeGraph 索引缺失怎么办？**

进入提示中的项目目录，运行：

```bash
codegraph init -i
```

**提示 `lemon_codegraph` 工具不可见怎么办？**

更新 Lemon Pi 后重新打开 Pi：

```bash
pi update npm:@lemon-pi/lemon-pi
```

**什么时候用 `/lemon:storm`，什么时候用 `/lemon:plan`？**

想法还不清楚，用 `/lemon:storm`。已经决定要做具体功能，用 `/lemon:plan`。如果模块复杂、涉及多实体或多流程，用 `/lemon:spec`。

**为什么 AI 不展示完整内部流程或工具日志？**

Lemon Pi 会把内部规则作为执行约束使用，最终回答尽量只保留结论、关键证据和可执行建议。这样可以减少噪音，也避免把内部实现细节暴露给普通使用者。