# pi agent 使用说明（本仓库）

> 面向在 Envi3D 2026 仓库上使用 pi agent 的人（目前三台机器）。
> 记录项目级配置、常用命令、Windows 终端问题、会话管理，以及插件的取舍结论。
> 基于 **pi 1.4.0 / Windows 10（19045）** 实测。

---

## 1. 仓库里放了什么

```
AGENTS.md                        pi 启动时自动加载的上下文文件
.pi/skills/build-arx/            preset / target / 产物路径
.pi/skills/verify-utf8/          UTF-8 BOM 自检与回滚
.pi/skills/pr-flow/              分支 / 中文 commit / refs/for/main
.pi/skills/analyze-big-entity/   万行实体类分析套路
.pi/prompts/build.md             /build [preset] [target]
.pi/prompts/pr.md                /pr [分支描述]
.pi/prompts/chk.md               /chk
CODEBUDDY.md                     完整项目说明（构建、加密、架构），pi 不会自动读
```

加载规则：

| 资源 | 是否需要「项目信任」 |
| --- | --- |
| `AGENTS.md`（context file） | **不需要**，任何时候都加载 |
| `.pi/skills`、`.pi/prompts`、`.pi/settings.json` | **需要**。未信任时整块跳过 |

`AGENTS.md` 故意不复制 `CODEBUDDY.md` 正文：一是避免两份 170 行文档各自漂移，
二是 `CODEBUDDY.md` 这个名字还被 `AecDbSlab-review.md`、`GiDrawUtility-analysis.md`、
`XEquipment-refactor-plan.md` 引用。改代码前让模型先 `read CODEBUDDY.md` 即可。

## 2. 常用命令

### 启动参数

```cmd
pi                       新会话
pi -c                    续上「当前工作目录」最近一次会话（--continue）
pi -r                    会话选择器（--resume）
pi --session <path|id>   指定会话
pi --fork <id>           从某会话分叉
pi --tui-mode regular    常规模式（默认 fullscreen）
pi -e npm:<包>           临时加载一个包，不写入 settings
pi --offline             禁用所有联网（等价 PI_OFFLINE=1）
```

### 会话命令

| 命令 | 用途 |
| --- | --- |
| `/new` | 开新会话（旧的不丢） |
| `/resume` | 切到别的已保存会话 |
| `/tree` | 浏览会话树、回到某个分支 |
| `/fork` | 从某条用户消息分叉 |
| `/clone` | 原位复制当前会话 |
| `/compact` | 压缩上下文 |
| `/session` | 当前会话信息与统计 |
| `/import <path>` | 导入 JSONL 会话 |

会话文件在 `C:\Users\gjm\.pi\agent\sessions\`，默认自动保存（`--no-session` 才临时）。

### 资源与环境命令

| 命令 | 用途 |
| --- | --- |
| `/reload` | 重载 keybindings / extensions / **skills** / **prompts** / themes / **AGENTS.md** |
| `/skill:xxx` | 强制加载某个 skill |
| `/settings` | 打开设置面板（可直接改，例如搜 shrink） |
| `/trust` | 保存项目信任决定 |
| `/hotkeys` | 查看当前快捷键 |
| `/build` `/pr` `/chk` | 本仓库的 prompt 模板 |

## 3. `/reload` 不恢复会话（最容易混）

| | 作用范围 |
| --- | --- |
| `/reload` | 只重载**资源**：skill、prompt、AGENTS.md、主题、扩展、快捷键 |
| 对话历史 | 完全不受影响，靠 `-c` / `-r` / `/resume` 恢复 |

`/reload` 的正确用途：`git pull` 拿到新的 skill / prompt / AGENTS.md 后，让它重新扫一遍。

刚 clone 或刚 pull 之后的推荐顺序：

```cmd
pi -c        :: 1. 先续上会话（或直接 pi 开新的）
             :: 2. /reload，让新的 skill / prompt 被扫到
             :: 3. 正常干活
```

⚠️ 会话按**工作目录**关联：`-c` 找的是当前目录最近的会话，所以必须在
`D:\new-start\envi-code` 里启动，否则找不到。

## 4. Windows 终端：底部状态栏忽上忽下

### 现象

编辑器 + 底部状态信息（目录 / 会话 / 模型 / 上下文占比 / 用量）在内容变化时上下跳动，
状态信息还常折成好几行。

### 根因（三条叠加）

1. **宿主是 `conhost.exe`**。Windows 10 没有「默认终端应用」设置，`cmd.exe` 默认宿主就是 conhost，
   它对 VT 备用屏幕和滚动区域的支持最弱；而 pi 默认 `tuiMode: "fullscreen"` 恰好依赖它。
   判定方法：`echo %WT_SESSION%`，为空即不是 Windows Terminal。
2. **`terminal.clearOnShrink` 默认 `false`**。pi 1.4.0 的说明：
   *"keeps the editor and footer pinned to the bottom of the terminal when content shrinks"*。
   关着的时候，工具结果折叠、编辑器清空、spinner 消失后多余的行不清除，底部就浮在半空。
3. **窗口不够宽**。footer 是单行渲染，宽度不足时折行成 2~3 行。

### 解决办法（按性价比）

| 顺序 | 做法 |
| --- | --- |
| 1 | `~/.pi/agent/settings.json` 加 `"terminal": { "clearOnShrink": true }`，或在会话里 `/settings` 搜 `shrink` 打开；临时验证可用 `set PI_CLEAR_ON_SHRINK=1` |
| 2 | 装 Windows Terminal：`winget install --id Microsoft.WindowsTerminal -e`，用 `wt -d D:\new-start\envi-code cmd /k pi` 启动（Win10 不会自动接管 cmd，必须显式 `wt`） |
| 3 | 窗口拉到 **≥120 列**，减少 footer 折行 |
| 4 | `pi --tui-mode regular` 对比一次，常规模式不抢视口、用终端自己的 scrollback |
| 5 | 排查用 `set PI_TUI_WRITE_LOG=D:\pi-tui.log` 抓原始 ANSI 流 |

已知取舍：`clearOnShrink` 会带来轻微重绘闪烁，换来底部钉住。

当前本机配置：

```json
{
  "lastChangelogVersion": "1.4.0",
  "terminal": { "clearOnShrink": true }
}
```

桌面快捷方式 `E:\桌面\pi - envi-code.lnk` →
目标 `wt.exe`，参数 `-d "D:\new-start\envi-code" cmd /k pi`，起始位置为仓库目录。

## 5. 三台机器怎么同步

### 随仓库走（`git pull` 就有）

`AGENTS.md`、`.pi/skills/**`、`.pi/prompts/**`、`.pi/settings.json`（若声明了包）。

被 `.gitignore` 挡住的（各自准备，不要试图提交）：`Arx/`、`ZRX/`、`bin/`、`lib/`、`cmake_output/`。

### 每台机器必须自己弄

| 项 | 说明 |
| --- | --- |
| CAD SDK `Arx/R19.0~R26.0`、`ZRX/Z2023~Z2026` | 与主仓库同级放置 |
| Visual Studio 18 2026 生成器 + Windows SDK `10.0.22621.0` | preset 里写死，缺了 configure 失败 |
| CMake ≥ 3.21 | |
| `~/.ssh/config` 里的私钥 | 每台机器私钥不同，**文件名不要写进仓库** |
| pi 本体 + `~/.pi/agent/auth.json` | 模型认证 |
| `c:\ShangHuaSoft\Envi3D-2026-M\<标签>\` | Debug 构建 post-build 的部署目录 |

### 三个坑

1. **`.pi/settings.json` 会冲突**。团队统一用的包 → `pi install -l npm:xxx`（写进项目文件，可提交）；
   个人想装的 → 不加 `-l`（写进 `~/.pi/agent/settings.json`，不入库）。
2. **`.pi/skills/` vs `~/.pi/agent/skills/`**。前者是本仓库专用（推荐，团队共享）；
   后者是本机所有项目可用。要跨项目复用请以仓库为准复制，避免版本分叉。
3. **首次启动要授予项目信任**，否则 `.pi/` 下全部不加载（`AGENTS.md` 不受影响）。

## 6. 插件取舍结论

### pi-lens（npm:pi-lens，4.4.6）

**结论：对本仓库不建议装。** 它的核心卖点在这里全部用不上：

| 功能 | 为什么用不上 |
| --- | --- |
| C++ LSP 诊断（clangd） | 需要 `compile_commands.json`，而本项目用 **Visual Studio 生成器**，根本不会产出 |
| 编译检查 runner | 跑 `cl /Zs <单文件>`，不带 `-D ARX=19 -D_AFXDLL` 等宏，MFC/ARX 全是「找不到 afxwin.h」 |
| 格式化 / autofix | 仓库无 `.clang-format`，且源码强制 **UTF-8 BOM**，整文件重排风险极高 |
| knip / madge 等 | JS/TS 生态工具 |

剩下能用的只有 ast-grep 的结构化搜索（MFC 宏会削弱解析精度），相比 `rg` 提升有限。
本机 PATH 上没有任何 C++ 工具链，所以它默认连 LSP/编译器都找不到，等于只有词索引在工作。

### 值得考虑的（按需）

| 包 | 用途 |
| --- | --- |
| `pi-plan-task` | 把「阶段一/二/三」重构计划变成可批准、可续跑的任务流 |
| `@demigodmode/pi-web-agent` | pi 内置**没有**任何联网工具，查 ObjectARX/AutoCAD API 时需要 |
| `pi-docparser` | 解析/截图 PDF，偶尔看 ISO 图纸对比时有帮助 |

### 明确不需要

主题/UI 装饰类（`osdy-pi`、`pi-spark`）、文件提及加速类（`@zigai/pi-mention-*`）、
配置备份类（`pi-my-setup`）——都不解决这个仓库的实际问题。

## 7. 其他已知坑

1. **pi 不读 `CODEBUDDY.md`**，只认 `AGENTS.override.md` / `AGENTS.md` / `CLAUDE.md`（含大小写变体）。
2. **内置工具只有 `read` / `write` / `edit` / `bash`**，没有独立的 grep / glob / web 工具：
   搜索用 `bash` 调 `rg`，联网靠 `curl` 或插件。
3. **源码必须 UTF-8 with BOM**，`cmakelists.txt` 保持 ASCII 无 BOM。中文写坏不可逆，只能
   `git checkout HEAD -- <file>` 重做。改完照 skill `verify-utf8` 自检。
4. **类名与文件名可能不一致**（`AecDbSlab.cpp` 里是 `AecDbXSlab`），搜之前先
   `rg -n "ACRX_DXF_DEFINE_MEMBERS"`。
5. **Windows Terminal 首次启动**会走初始化（接受协议、选配色）。