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

2.6 KiB
Raw Blame History

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。