docs: 增加 AGENTS.md 与 .pi 下的 skill / prompt 模板 #90
No files matched your search
@@ -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. 失败时给出 `文件:行号` + 原因 + 最小修复方案,不要贴整段编译日志。
|
||||
@@ -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. 最后给一行结论:可以提交 / 需要先修什么。
|
||||
@@ -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 内实测)。
|
||||
@@ -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`,不要攒。
|
||||
- 决定"不做"的项也要写进文档并给出理由,避免下一轮重复讨论(仓库里已有多处这种记录)。
|
||||
@@ -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 失败。
|
||||
@@ -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、客户专版配置提交进来。
|
||||
@@ -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。
|
||||
@@ -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` | 万行实体类的分析与改动套路 |
|
||||
Reference in new issue
Block a user