Files
envi-code/pi-agent-setup.md
T
company-desktop 6337ee45bc 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

202 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 首次启动**会走初始化(接受协议、选配色)。