Files
envi-code/AGENTS.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

45 lines
2.6 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.
# 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`。