From d29aa7095704d8dd265e693ad443f3b86f5c891e Mon Sep 17 00:00:00 2001 From: company-desktop-computer Date: Wed, 28 Oct 2026 10:36:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20AGENTS.md=20?= =?UTF-8?q?=E4=B8=8E=20.pi=20=E4=B8=8B=E7=9A=84=20skill=20/=20prompt=20?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pi agent 只认 AGENTS.md / CLAUDE.md,不认 CODEBUDDY.md,所以此前 pi 启动时 完全没有加载本仓库的项目说明。本次补上,并把手头反复要做的流程固化成 skill 与 prompt 模板,供团队三台机器共享。 新增内容: - AGENTS.md —— pi 每次启动自动加载。只放 pi 环境差异(内置工具只有 read/write/edit/bash,搜索用 rg;万行文件分段读;类名与文件名不一致) 和硬性红线(UTF-8 BOM、禁止 vcxproj、不直推 main、中文 commit、 匿名 namespace、#ifdef ZWCAD 判平台),其余指路 CODEBUDDY.md。 不复制 CODEBUDDY.md 正文,避免两份 170 行文档各自漂移;CODEBUDDY.md 这个名字还被 3 篇分析文档引用,保持原文件名不动。 - .pi/skills/build-arx —— preset(R180~R260 / Z2023~Z2026)与常用 target、 加密双版本 target 后缀、目录名≠target 的例外、产物与部署路径、 LNK4099 rxapi PDB 属已知噪音。 - .pi/skills/verify-utf8 —— UTF-8 BOM 自检命令与判读表、写坏后 git checkout 还原重做的流程、批量自检脚本。 - .pi/skills/pr-flow —— 分支命名(<机器名>/<英文描述>)、代码与文档分开 两个 commit、中文 message 结构、git push refs/for/main/<分支>、 提交前检查清单、私钥不入库。 - .pi/skills/analyze-big-entity —— 万行实体类的定位套路(先 rg ACRX_DXF_DEFINE_MEMBERS 确认类名、必看的持久化/生命周期/绘制缓存/ 内存所有权四个面)、性能问题的量化口径、分析文档命名与结构。 - .pi/prompts/{build,pr,chk}.md —— /build、/pr、/chk 三个模板。 全部为 Markdown,不含可执行代码。.pi/ 为项目级资源,需 pi 授予项目信任 后加载;AGENTS.md 作为 context file 不受信任限制。 --- .pi/prompts/build.md | 12 ++++++ .pi/prompts/chk.md | 13 ++++++ .pi/prompts/pr.md | 11 +++++ .pi/skills/analyze-big-entity/SKILL.md | 54 +++++++++++++++++++++++++ .pi/skills/build-arx/SKILL.md | 54 +++++++++++++++++++++++++ .pi/skills/pr-flow/SKILL.md | 56 ++++++++++++++++++++++++++ .pi/skills/verify-utf8/SKILL.md | 51 +++++++++++++++++++++++ AGENTS.md | 42 +++++++++++++++++++ 8 files changed, 293 insertions(+) create mode 100644 .pi/prompts/build.md create mode 100644 .pi/prompts/chk.md create mode 100644 .pi/prompts/pr.md create mode 100644 .pi/skills/analyze-big-entity/SKILL.md create mode 100644 .pi/skills/build-arx/SKILL.md create mode 100644 .pi/skills/pr-flow/SKILL.md create mode 100644 .pi/skills/verify-utf8/SKILL.md create mode 100644 AGENTS.md diff --git a/.pi/prompts/build.md b/.pi/prompts/build.md new file mode 100644 index 0000000..000b397 --- /dev/null +++ b/.pi/prompts/build.md @@ -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. 失败时给出 `文件:行号` + 原因 + 最小修复方案,不要贴整段编译日志。 diff --git a/.pi/prompts/chk.md b/.pi/prompts/chk.md new file mode 100644 index 0000000..23b824e --- /dev/null +++ b/.pi/prompts/chk.md @@ -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. 最后给一行结论:可以提交 / 需要先修什么。 diff --git a/.pi/prompts/pr.md b/.pi/prompts/pr.md new file mode 100644 index 0000000..0e874c4 --- /dev/null +++ b/.pi/prompts/pr.md @@ -0,0 +1,11 @@ +--- +description: 按仓库约定建分支、提交并推送评审 +argument-hint: "[分支描述]" +--- +按 `AGENTS.md` 和 skill `pr-flow` 的约定提交当前改动,分支描述用 `${1:-fix}`。 + +1. `git fetch origin`,确认 `origin/main` 有没有新提交;有就先说明,不要擅自 rebase。 +2. 从 `main` 建分支 `/${1:-fix}`。 +3. 拆 commit:代码与文档分开,message 用中文,正文写「现象 → 根因 → 改动范围 → 验证方式 → 风险」。 +4. `git push origin HEAD:refs/for/main/<分支名>`。 +5. 回报:PR 地址、分支名、每个 commit 的文件变更统计,以及**还没做的验证项**(例如 CAD 内实测)。 diff --git a/.pi/skills/analyze-big-entity/SKILL.md b/.pi/skills/analyze-big-entity/SKILL.md new file mode 100644 index 0000000..9b26ec5 --- /dev/null +++ b/.pi/skills/analyze-big-entity/SKILL.md @@ -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`,不要攒。 +- 决定"不做"的项也要写进文档并给出理由,避免下一轮重复讨论(仓库里已有多处这种记录)。 diff --git a/.pi/skills/build-arx/SKILL.md b/.pi/skills/build-arx/SKILL.md new file mode 100644 index 0000000..4683465 --- /dev/null +++ b/.pi/skills/build-arx/SKILL.md @@ -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 +``` + +## 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/-x64-<标签>/`、`lib/Code2026/.../<标签>/` +- 加密模块落到 `-` 子目录(实测 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 失败。 diff --git a/.pi/skills/pr-flow/SKILL.md b/.pi/skills/pr-flow/SKILL.md new file mode 100644 index 0000000..f03e97f --- /dev/null +++ b/.pi/skills/pr-flow/SKILL.md @@ -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 <分支名> +``` + +分支名沿仓库历史惯例,优先 `/<英文短横线描述>`: + +``` +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/`)。 +更新同一个 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、客户专版配置提交进来。 diff --git a/.pi/skills/verify-utf8/SKILL.md b/.pi/skills/verify-utf8/SKILL.md new file mode 100644 index 0000000..8f3ca71 --- /dev/null +++ b/.pi/skills/verify-utf8/SKILL.md @@ -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 -- ` 还原 +3. 重新用 `edit` 工具做定点替换,不要整体重写文件 +4. 再跑一次自检 + +## 改文件时的注意事项 + +- 优先用 `edit`(精确文本替换),避免 `write` 整文件覆盖——整覆盖最容易丢 BOM。 +- 从旧分支/旧机器检出、仍为 GBK 或 UTF-16 的文件,先探明编码再动,不要假设。 +- 编辑 `cmakelists.txt` 时确认没有引入 BOM。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..72a5fdb --- /dev/null +++ b/AGENTS.md @@ -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 -- ` 还原后重做。 +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` | 万行实体类的分析与改动套路 | -- 2.54.0