envi-code/pi-agent-setup.md

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. 常用命令

启动参数

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 之后的推荐顺序：

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 会带来轻微重绘闪烁，换来底部钉住。

当前本机配置：

{
  "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 首次启动会走初始化（接受协议、选配色）。