新增 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 里加一行指向该文档。
2.6 KiB
2.6 KiB
AGENTS.md — Envi3D 2026(环境设计)
本文件由 pi 自动加载。完整的项目说明在 CODEBUDDY.md(构建、preset、加密双版本、模块分组、架构分层)。
动手改代码前先 read CODEBUDDY.md。这里只放 pi 环境差异和硬性红线。
pi 环境说明
- 内置工具只有
read/write/edit/bash,没有独立的 grep / glob / web 工具: 搜索一律在bash里用rg,联网靠curl或额外插件。 - 超长文件用
read的offset/limit分段读:AecDbEwFitting.cpp17453 行、AecDbEwEquipment.cpp14290 行、AecDbEwPipe.cpp5002 行。 - 类名与文件名不一定一致,搜之前先
rg -n "ACRX_DXF_DEFINE_MEMBERS" <文件>确认 (例:AecDbSlab.cpp里的类叫AecDbXSlab)。
红线(违反了会污染仓库或造成不可逆损坏)
- 源码编码:
SourceCode/Code2026/**/*.cpp|*.h必须是 UTF-8 with BOM;cmakelists.txt/CMakeLists.txt保持 ASCII 无 BOM。 中文写坏不可逆,只能git checkout HEAD -- <file>还原后重做。 - 禁止新增或依赖
.vcxproj/.sln(StartApp/StartApp.sln是唯一例外)。cmake_output/下的*.vcxproj是构建产物,不要提交。 - 不要直推
main,推送走git push origin HEAD:refs/for/main/<分支名>触发评审。 - commit message 用中文。
- 文件内私有函数放该文件已有的匿名
namespace;不要写文件级static,不要放头文件。 - 平台判断用
#ifdef ZWCAD,不要只比较ARX版本号(ZRX 的ARX宏与 AutoCAD R 版本数值重叠)。 Arx/、ZRX/、bin/、lib/、cmake_output/已被 gitignore,不要手动加进来。
动手前
- 本仓库没有单元测试框架、没有 lint 配置:验证方式 = 编对应 preset + 在 CAD 里加载实测。
- 大改动先读仓库根目录已有的分析文档(
*-review.md/*-plan.md/*-analysis.md), 里面记录了很多"已经决定不做"的理由,别重复踩。 - 构建命令与 target 对照见
CODEBUDDY.md,或直接用 skillbuild-arx。
仓库内 skill
| skill | 用途 |
|---|---|
build-arx |
按 preset 编译、单 target、产物与部署路径 |
verify-utf8 |
UTF-8 BOM 自检、写坏后的回滚 |
pr-flow |
分支命名 / 中文 commit / refs/for/main 推送 |
analyze-big-entity |
万行实体类的分析与改动套路 |
使用说明(常用命令、会话管理、Windows 终端问题、多机同步、插件取舍)见 pi-agent-setup.md。