docs: 增加 AGENTS.md 与 .pi 下的 skill / prompt 模板 #90

Merged
gjm merged 1 commits from company-desktop/company-desktop-computer/doc-pi-agent-setup AGit into main 2026-10-28 10:37:35 +08:00
8 changed files with 293 additions and 0 deletions

No files matched your search

+12
View File
@@ -0,0 +1,12 @@
---
description: 编译指定 preset 和 target,只汇报错误
argument-hint: "[preset=R190] [target=CoreCommand_BAL_REMOTE]"
---
在 `SourceCode/Code2026` 下编译,preset 用 `${1:-R190}`,target 用 `${2:-CoreCommand_BAL_REMOTE}`。
步骤:
1. 若 `cmake_output/code2026/${1:-R190}` 不存在,或 `cmakelists.txt` / `cmake/presets` 有改动,先跑
`cmake --preset ${1:-R190}`。
2. `cmake --build --preset ${1:-R190} --config Debug --target ${2:-CoreCommand_BAL_REMOTE}`。
3. 只汇报 error 和本次改动引入的 warning;`rxapi.lib ... PDB 'rxapi_cl.pdb' was not found` 是已知噪音,忽略。
4. 失败时给出 `文件:行号` + 原因 + 最小修复方案,不要贴整段编译日志。
+13
View File
@@ -0,0 +1,13 @@
---
description: 改动自检(编码、行尾、脏文件、diff 规模)
---
对当前工作区改动做自检,用表格汇报:
1. `git status --short`:列出脏文件,标出未跟踪文件是否应该提交(`cmake_output/`、`bin/`、`lib/`、`Arx/`、`ZRX/` 一律不该提交)。
2. 每个改动的 `.cpp` / `.h`:跑
`python -c "d=open(p,'rb').read(); print(d[:3], d.count(b'\xef\xbf\xbd'))"`
要求前 3 字节为 `b'\xef\xbb\xbf'`、坏字节数为 0。任何一项不满足就停下来报告,不要继续。
3. `git diff --numstat`:确认改动行数合理,不是整文件重写。
4. 若 `cmakelists.txt` / `CMakeLists.txt` 有改动:确认是 ASCII 无 BOM。
5. 若动了 `.cpp/.h`,提示用户跑 `/build`(或我直接编受影响的 target)。
6. 最后给一行结论:可以提交 / 需要先修什么。
+11
View File
@@ -0,0 +1,11 @@
---
description: 按仓库约定建分支、提交并推送评审
argument-hint: "[分支描述]"
---
按 `AGENTS.md` 和 skill `pr-flow` 的约定提交当前改动,分支描述用 `${1:-fix}`。
1. `git fetch origin`,确认 `origin/main` 有没有新提交;有就先说明,不要擅自 rebase。
2. 从 `main` 建分支 `<git config user.name>/${1:-fix}`。
3. 拆 commit:代码与文档分开,message 用中文,正文写「现象 → 根因 → 改动范围 → 验证方式 → 风险」。
4. `git push origin HEAD:refs/for/main/<分支名>`。
5. 回报:PR 地址、分支名、每个 commit 的文件变更统计,以及**还没做的验证项**(例如 CAD 内实测)。
+54
View File
@@ -0,0 +1,54 @@
---
name: analyze-big-entity
description: Analyze or refactor the huge AecDb* custom entity classes in CoreLibrary (10k+ line files). Use when investigating memory leaks, performance, or bugs in an AecDbXxx entity, or before planning a refactor.
---
# 万行实体类分析套路
`SourceCode/Code2026/CoreLibrary/` 下的 `AecDb*.cpp` 普遍 5000~17000 行,
继承链 `AecDbXxx → … → AecDbCurveBase/AecDbEntityBase → AcDbEntity`。
## 1. 先定位,别顺着读
```bash
# 类名可能与文件名不同(AecDbSlab.cpp 里是 AecDbXSlab)
rg -n "ACRX_DXF_DEFINE_MEMBERS" SourceCode/Code2026/CoreLibrary/<文件>.cpp
# 继承链
rg -n "class .*<类名>.*:" SourceCode/Code2026/inc/<头文件>.h
# 数据结构:参数都在 m_mapSpecXData(AecDbObjXDataMap)里
rg -n "m_mapSpecXData|m_pXDataMap" SourceCode/Code2026/CoreLibrary/<文件>.cpp | head -40
# 关键入口函数
rg -n "::dwgInFields|::dwgOutFields|::Draw2d|::Draw3d|::copyFrom|::subTransformBy|::GetPipeParam" <文件>.cpp
```
## 2. 必看的几个面
| 面 | 看什么 |
| --- | --- |
| 持久化 | `dwgInFields` / `dwgOutFields` 的版本号分支(`kCurrentVersionNumber`);老图兼容逻辑常在这里补键/查库 |
| 生命周期 | 构造函数里 `new` 了什么、析构函数里有没有对应 `delete`;`m_arDrawBuffer*` 之类的缓存数组 |
| 绘制缓存 | `AssertWriteEnabled` 里是否 `Clean2DBuffer` / `Clean3DBuffer`;缓存失效点漏了就会画旧图 |
| 内存所有权 | 返回裸指针的函数(`GetPipeParam` 返回 `new` 出来的对象),调用方是否 `delete` |
| 外部资源 | `sqlite`、临时文件(`CoreTools::getTempFilePath`)、`AcDbRegion`(`delete` 而非 `close`) |
## 3. 性能问题的定位口径
- 先量化**调用次数**,再谈单次耗时。用 `rg -c` 数调用点;在可疑函数里临时加计数器 + `acutPrintf`。
- 已知热点类型:每次绘制/加载都开 `Plumbing.db`(见 `sqlite_query_cache.md`)、
每次调用都 `getLayerTable(kForWrite)`、反复构造大 `CString`/`AcDbRegion`。
## 4. 产出
- 分析文档写在**仓库根目录**,命名与既有文档一致:
`<类名>-review.md`(审查)/ `<类名>-refactor-plan.md`(重构计划)/ `<类名>-analysis.md`(分析)。
- 文档结构参考 `AecDbSlab-review.md`:范围与基线 → 内存泄漏(编号 L1..Ln)→ 潜在 Bug(B1..Bn)→
运行逻辑 → 运行效率(E1..En)→ 修复批次与状态。
- 每条结论带**文件:行号**,并注明"基线 commit";改了代码后行号会漂移,在文首写清基线。
## 5. 改动纪律
- 一次只改一类问题,改完立刻编 + 跑 `verify-utf8`,不要攒。
- 决定"不做"的项也要写进文档并给出理由,避免下一轮重复讨论(仓库里已有多处这种记录)。
+54
View File
@@ -0,0 +1,54 @@
---
name: build-arx
description: Build Envi3D ObjectARX/ZRX modules with CMake presets. Use when compiling, checking compile errors, or verifying that an edit builds.
---
# 编译
所有命令在 `SourceCode/Code2026` 下执行(`cmakelists.txt` 与 `cmakepresets.json` 同目录)。
```bash
cd SourceCode/Code2026
cmake --preset R190 # 配置;build 树已存在且 CMakeLists 未改可跳过
cmake --build --preset R190 --config Debug --target <Target>
```
## preset
| 分组 | preset |
| --- | --- |
| AutoCAD | `R180 R190 R200 R210 R220 R230 R240 R243 R250 R260` |
| 中望CAD | `Z2023 Z2024 Z2025 Z2026` |
R190 = AutoCAD 2019(C++98),R250/R260 = 2025/2027(C++20)。
不确定用哪个就先用 `R190`:标准最老,代码最容易暴露问题,且 Debug 编译最快。
## 常用 target
`AecRxBase`、`CoreCommand_BAL_REMOTE`、`CoreLibrary_BAL_REMOTE`、`CoreImplement`、
`PipelineCmd`、`PipelineSpecCmd`、`PIDLineCmd`、`ISODraftCmd`、`PipeHangerCmd`、
`PlumbingCmd`、`Pool3dCmd`、`HvacCmd`、`ElecCmd`、`ArchCmd`、`SPLDCmd`、
`EarthWormCmd`、`EarthWormMain`、`Dimension`、`shsTK`、`sqliteserver`、`MFCCtrl`。
聚合目标:`Build_SH_CORE`(AecRxBase + 两个 CoreCommand)、`Build_SH_GLOBAL`、`Build_TG`。
**易错点**:
- `CoreCommand` / `CoreLibrary` 是**加密双版本**,target 名必须带后缀:
`CoreCommand_BAL_REMOTE`(正式/网络锁)或 `CoreCommand_TRIAL_YEAR`(1 年期试用)。
业务模块只链接 `_BAL_REMOTE`。
- 目录名 ≠ target 名的:`ISODraft` → `ISODraftCmd`、`PipeHanger` → `PipeHangerCmd`、
`pool3dcmd` → `Pool3dCmd`、`tg_shs/shs_kernal` → `wfK`、`tg_shs/shs_annotate` → `wfA`。
见顶层 `cmakelists.txt` 的 `add_custom_module` / `add_custom_module_2`。
## 产物与部署
- 输出:`bin/Code2026/<Debug|Release>-x64-<标签>/`、`lib/Code2026/.../<标签>/`
- 加密模块落到 `-<MODE>` 子目录(实测 R190 为 `WF2023-BAL_REMOTE/`)
- **Debug 构建**的 post-build 会调 `copyarx.exe` 部署到 `c:\ShangHuaSoft\Envi3D-2026-M\<标签>\`;
Release 不部署。
## 读日志
- 只报 error 和本次改动引入的 warning。
- `rxapi.lib : warning LNK4099: PDB 'rxapi_cl.pdb' was not found` 是**已知噪音**,忽略。
- 需要 `Windows SDK 10.0.22621.0` 与 `Visual Studio 18 2026` 生成器(x64),缺了会 configure 失败。
+56
View File
@@ -0,0 +1,56 @@
---
name: pr-flow
description: Commit and push changes the way this repo requires — branch naming, Chinese commit messages, and pushing to refs/for/main for Gitea review. Use whenever the user asks to commit, push, or open a PR here.
---
# 提交与推送流程
远端:`origin = ssh://git@39.107.55.179:222/gjm/envi-code.git`(Gitea),主干 `main`。
**不要直推 `main`。**
## 1. 分支
```bash
git fetch origin
git log --oneline -1 origin/main # 确认起点
git checkout -b <分支名>
```
分支名沿仓库历史惯例,优先 `<git config user.name>/<英文短横线描述>`:
```
company-desktop-computer/perf-pipe-style-sqlite-cache
home-laptop/fix-aecdbslab-memory-leaks
```
也见过纯英文(`refactor-i_aecdbxequipment-copyfrom`)和带分类前缀(`docs/xxx`、`fix/xxx`),但不要用中文分支名。
## 2. commit
- message **用中文**;代码修复开头用「修复」或 `fix:` / `perf:` / `refactor:` / `docs:`
- **代码与文档分开两个 commit**(便于单独 review / revert),历史先例:
`f349ed2 补充 HLR 模块问题记录文档`、`9b80db3 rafactor-pipe,fitting-speedup`
- message 正文写清:现象 → 根因 → 改动范围 → 与之前 PR 的关系 → 验证方式 → 已知风险
- 用 `git commit -F <文件>` 传多行中文 message,避免 shell 引号问题
## 3. 推送
```bash
git push origin HEAD:refs/for/main/<分支名>
```
成功后 Gitea 会返回 PR 地址(`http://39.107.55.179:3000/gjm/envi-code/pulls/<N>`)。
更新同一个 PR:amend / 追加 commit 后再推一次同一个分支名即可。
## 4. 提交前检查
- [ ] `git status --short` 干净,无临时文件、无 `cmake_output/` 之类产物
- [ ] `git diff --numstat` 不是整文件重写
- [ ] 改过 `.cpp/.h` → 跑 `verify-utf8` skill
- [ ] 至少编过受影响的 target(`build-arx` skill)
- [ ] **没做过 CAD 实测就在 PR 里写明"仅编译验证"**,并列出待实测项
## 5. 安全
- 各机器 SSH 私钥不同,在 `~/.ssh/config` 里指定;**私钥文件名不要写进仓库**。
- 不要把 `auth.json`、token、客户专版配置提交进来。
+51
View File
@@ -0,0 +1,51 @@
---
name: verify-utf8
description: Check and repair UTF-8 BOM and Chinese text encoding in SourceCode/Code2026 sources. Use after every edit of a .cpp or .h file in this repo, and before committing.
---
# 编码自检与修复
仓库约定:`SourceCode/Code2026/**/*.cpp|*.h` 全部是 **UTF-8 with BOM**;
`cmakelists.txt` / `CMakeLists.txt` 保持 **ASCII 无 BOM**。
## 自检
对每个改动过的文件跑:
```bash
python -c "d=open('路径','rb').read(); print(d[:3], d.count(b'\xef\xbf\xbd'))"
```
判读:
| 输出 | 含义 | 处理 |
| --- | --- | --- |
| `b'\xef\xbb\xbf' 0` | 正确 | 通过 |
| `b'\xef\xbb\xbf' N`(N>0) | 有 U+FFFD 替换字符,中文已损坏 | **不可逆**,见下 |
| 不是 `\xef\xbb\xbf` 开头 | 缺 BOM(或是 GBK/UTF-16 老文件) | 补 BOM / 先探明编码再改 |
批量检查一次:
```bash
python - <<'EOF'
import glob
for p in glob.glob('SourceCode/Code2026/**/*.cpp', recursive=True) + \
glob.glob('SourceCode/Code2026/**/*.h', recursive=True):
d = open(p, 'rb').read()
if not d.startswith(b'\xef\xbb\xbf') or b'\xef\xbf\xbd' in d:
print(p, d[:3], d.count(b'\xef\xbf\xbd'))
EOF
```
## 写坏了怎么办
1. **不要**在损坏文件上继续改(越改越乱)
2. `git checkout HEAD -- <file>` 还原
3. 重新用 `edit` 工具做定点替换,不要整体重写文件
4. 再跑一次自检
## 改文件时的注意事项
- 优先用 `edit`(精确文本替换),避免 `write` 整文件覆盖——整覆盖最容易丢 BOM。
- 从旧分支/旧机器检出、仍为 GBK 或 UTF-16 的文件,先探明编码再动,不要假设。
- 编辑 `cmakelists.txt` 时确认没有引入 BOM。
+42
View File
@@ -0,0 +1,42 @@
# 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` | 万行实体类的分析与改动套路 |