# 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`。

## 自动化 CAD 实测

可以无人值守跑一次「开图 → 执行命令 → 收结果 → 关进程」。本机环境：

| 项 | 值 |
| --- | --- |
| AutoCAD | `c:\Program Files\Autodesk\AutoCAD 2020\acad.exe`（= R23.0，对应 preset **R230**） |
| 启动参数 | `/p SHS-ENVI2026`（试验用 profile，会自动加载本仓库的 arx） |
| 测试图纸 | `e:\桌面\big1.dwg`（约 8 MB，一次开图 ≈ 108 s） |
| 部署目录 | `c:\ShangHuaSoft\Envi3D-2026-M\R230\`（Debug 构建会自动部署到这里） |

一键脚本：`tools/run_acad_perf.ps1`

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\run_acad_perf.ps1
```

它的做法：写一个只含 `ENVIPERFDUMP` 的 `.scr`，用 `/b` 让 AutoCAD 在**图纸载入完成后**执行；
报告落 `%TEMP%\aec_section_perf.txt`；收完报告按 PID 结束**本次拉起的** acad，
脚本里不写 QUIT，所以不会弹保存对话框、不会回写图纸。

写这类 `.ps1` 时注意：**Windows PowerShell 5.1 把无 BOM 的 UTF-8 当 ANSI 读**，
带中文会直接语法错误——要么保存为 UTF-8 with BOM，要么脚本全用 ASCII（推荐）。

## 需要用户决策时

不要把问题打在终端里就停住——先跑 `tools/notify_decision.ps1`（用 `-MessageFile` 传中文），
发完 toast 再结束本轮。细则见 skill `notify-decision`。

## 仓库内 skill

| skill | 用途 |
| --- | --- |
| `build-arx` | 按 preset 编译、单 target、产物与部署路径 |
| `verify-utf8` | UTF-8 BOM 自检、写坏后的回滚 |
| `pr-flow` | 分支命名 / 中文 commit / `refs/for/main` 推送 |
| `analyze-big-entity` | 万行实体类的分析与改动套路 |
| `notify-decision` | 需要用户拍板时主动推送通知（桌面 toast / IM 机器人），不让他干等终端 |

使用说明（常用命令、会话管理、Windows 终端问题、多机同步、插件取舍）见 `pi-agent-setup.md`。