docs: 增加 pi agent 使用说明

新增 pi-agent-setup.md，把这几轮摸出来的 pi 使用知识固定下来，供三台机器共用： - 仓库里放了什么：AGENTS.md、4 个 skill、3 个 prompt 模板，以及加载规则（AGENTS.md 作为 context file 不需要项目信任，.pi/ 下需要）。并说明 AGENTS.md 为何不复制 CODEBUDDY.md 正文。 - 常用命令：启动参数（-c/-r/--session/--fork/--tui-mode/-e/--offline）、会话命令（/new /resume /tree /fork /clone /compact）、资源命令。 - 重点澄清 /reload 不恢复会话：它只重载 skill/prompt/AGENTS.md/主题/扩展，历史靠 -c / -r / /resume；并给出 pull 之后的推荐顺序，以及"会话按工作目录关联"这个容易踩的点。 - Windows 终端底部状态栏上下跳动：定位到三条叠加原因（cmd 的默认宿主是 conhost、terminal.clearOnShrink 默认 false、窗口不够宽导致 footer 折行），给出按性价比排序的处理办法和 PI_TUI_WRITE_LOG 排查手段，附当前本机配置与桌面快捷方式的实际参数。 - 三台机器的同步清单：哪些随仓库走、哪些必须各自准备、三个坑（.pi/settings.json 冲突、项目级与用户级 skill 目录、首次要授予项目信任）。 - 插件取舍：pi-lens 对本仓库为何不建议装（clangd 需要 compile_commands.json 而本项目用 VS 生成器、编译检查不带 ARX/MFC 宏、无 .clang-format 且强制 UTF-8 BOM），以及少数值得考虑的包和明确不需要的包。 - 其他已知坑：pi 不读 CODEBUDDY.md、内置工具只有 read/write/edit/bash、 UTF-8 BOM 约定、类名与文件名不一致。同时在 AGENTS.md 里加一行指向该文档。
2026-10-28 11:00:00 +08:00
1 parent fb82e5abd0
commit 6337ee45bc
@@ -40,3 +40,5 @@
 | `verify-utf8` | UTF-8 BOM 自检、写坏后的回滚 |
 | `pr-flow` | 分支命名 / 中文 commit / `refs/for/main` 推送 |
 | `analyze-big-entity` | 万行实体类的分析与改动套路 |
+
+使用说明（常用命令、会话管理、Windows 终端问题、多机同步、插件取舍）见 `pi-agent-setup.md`。
@@ -0,0 +1,201 @@
+# 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 首次启动**会走初始化（接受协议、选配色）。