新增 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 里加一行指向该文档。
45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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.cpp` 17453 行、`AecDbEwEquipment.cpp` 14290 行、`AecDbEwPipe.cpp` 5002 行。
|
||
- 类名与文件名不一定一致,搜之前先 `rg -n "ACRX_DXF_DEFINE_MEMBERS" <文件>` 确认
|
||
(例:`AecDbSlab.cpp` 里的类叫 `AecDbXSlab`)。
|
||
|
||
## 红线(违反了会污染仓库或造成不可逆损坏)
|
||
|
||
1. **源码编码**:`SourceCode/Code2026/**/*.cpp|*.h` 必须是 **UTF-8 with BOM**;
|
||
`cmakelists.txt` / `CMakeLists.txt` 保持 ASCII 无 BOM。
|
||
中文写坏**不可逆**,只能 `git checkout HEAD -- <file>` 还原后重做。
|
||
2. **禁止新增或依赖 `.vcxproj` / `.sln`**(`StartApp/StartApp.sln` 是唯一例外)。
|
||
`cmake_output/` 下的 `*.vcxproj` 是构建产物,不要提交。
|
||
3. **不要直推 `main`**,推送走 `git push origin HEAD:refs/for/main/<分支名>` 触发评审。
|
||
4. commit message 用中文。
|
||
5. 文件内私有函数放**该文件已有的匿名 `namespace`**;不要写文件级 `static`,不要放头文件。
|
||
6. 平台判断用 `#ifdef ZWCAD`,**不要**只比较 `ARX` 版本号(ZRX 的 `ARX` 宏与 AutoCAD R 版本数值重叠)。
|
||
7. `Arx/`、`ZRX/`、`bin/`、`lib/`、`cmake_output/` 已被 gitignore,不要手动加进来。
|
||
|
||
## 动手前
|
||
|
||
- 本仓库**没有单元测试框架、没有 lint 配置**:验证方式 = 编对应 preset + 在 CAD 里加载实测。
|
||
- 大改动先读仓库根目录已有的分析文档(`*-review.md` / `*-plan.md` / `*-analysis.md`),
|
||
里面记录了很多"已经决定不做"的理由,别重复踩。
|
||
- 构建命令与 target 对照见 `CODEBUDDY.md`,或直接用 skill `build-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`。
|