docs: 评估两个 Autodesk 官方 skill 对本仓库的适用性 #111
@@ -0,0 +1,144 @@
|
||||
# 两份 Autodesk 官方 skill 对本仓库的价值评估
|
||||
|
||||
评估对象（2025-10 抓取，`--depth 1` 克隆到临时目录逐文件读过）：
|
||||
|
||||
| 仓库 | 版本/规模 | 技术栈 |
|
||||
| --- | --- | --- |
|
||||
| [ADN-DevTech/acad-api-skill](https://github.com/ADN-DevTech/acad-api-skill) | 59 文件，`skills/*.md` 共 1873 行 | **.NET 10 托管插件**，AutoCAD / Civil 3D / Plant 3D 2027，NuGet + `.csproj` + `.bundle` |
|
||||
| [ADN-DevTech/acad-memory-leak-skill](https://github.com/ADN-DevTech/acad-memory-leak-skill) | 19 文件，687 行文档 + 5 个脚本 + 2 个 repro 模板 | **C++ / ObjectARX**，Private Bytes metering + ETW/WPA + `VirtualQueryEx` 区域快照 |
|
||||
|
||||
本仓库是 C++ ObjectARX/ZRX 双平台（`Code2026`，CMake preset，AutoCAD R230 实测），
|
||||
结论差别很大：**第二个基本对得上（方法论值钱、脚本要改），第一个只有 1 个文件有用。**
|
||||
|
||||
## 结论速览
|
||||
|
||||
| skill | 判断 | 理由（一句话） |
|
||||
| --- | --- | --- |
|
||||
| `acad-api-skill` | **基本无用，只取 1 项** | 全篇托管 .NET / 2027 / NuGet / `.csproj`，与本仓库 C++ + CMake + ZRX 技术栈零重叠；唯一能落地的是它推荐的 **Autodesk Knowledge MCP**（已实测可查 ObjectARX C++ 参考） |
|
||||
| `acad-memory-leak-skill` | **有用，取方法论 + 2 个脚本（需改）** | 本仓库 Debug 链 Release CRT，`_CrtDumpMemoryLeaks` 用不了（`HRL-MODEL-refactor.md:222` 已记录），而"外部测量 Private Bytes + ETW 栈"正是绕过这个限制的唯一路子；脚本 4 个里有 3 个有 bug/与本机环境冲突 |
|
||||
|
||||
**注意两份 skill 的定位偏差**：它们都是"给 AI 的 API 事实卡 + 模板"，不是自动化工具。
|
||||
价值在于**判据与坑**，不在于代码。搬模板基本等于重写。
|
||||
|
||||
---
|
||||
|
||||
## 一、acad-api-skill：绝大多数不适用
|
||||
|
||||
逐文件核对：
|
||||
|
||||
| 文件 | 内容 | 对本仓库 |
|
||||
| --- | --- | --- |
|
||||
| `skills/scaffold.md`（552 行） | `dotnet new acad/civil` 模板、`.bundle/PackageContents.xml`、`accoreconsole /al` | ✗ 我们是 `.arx/.zrx` + CMake，红线 #2 还禁止新增 `.vcxproj/.sln` |
|
||||
| `skills/autocad-api.md`（270 行） | `AcCoreMgd/AcDbMgd/AcMgd.dll` 装配映射、`PlotSettingsValidator`、`PlotEngine.BeginPage` 签名 | ✗ 全是托管 API。文中标注"verified against AutoCAD 2027 (26.0.0)"，我们是 R230 实测环境 |
|
||||
| `skills/civil3d-api.md` / `plant3d-api.md` | Civil 3D / Plant 3D 托管对象模型 | ✗ 本仓库是自研 `AecDb*` 自定义实体，不是 Civil/Plant |
|
||||
| `templates/acad/*.csproj`、`templates/civil/` | .NET 工程骨架 | ✗ 且用了 `.csproj`/`PackageContents.xml` |
|
||||
| `skills/code-sleuth.md`（112 行） | `rg` 查 SDK 样例 + 在线文档索引 + **Autodesk Knowledge MCP 端点** | **✓ 只有这条 URL 有价**（见下） |
|
||||
| `skills/learnings.md` | append-only 学习日志的协作模式 | △ 理念可借，但仓库已有 15 篇 `*-analysis.md` / `*-plan.md` / `*-review.md`，再加一层日志会重复 |
|
||||
|
||||
### 唯一值得拿的东西：Autodesk Knowledge MCP（已实测）
|
||||
|
||||
`code-sleuth.md` 里给的 `https://developer.api.autodesk.com/knowledge/public/v1/mcp`
|
||||
是一个免注册的 streamable-HTTP MCP server，两个工具：`get_available_products`、`search_help_content`。
|
||||
|
||||
实测（本轮真实调用，非文档抄写）：
|
||||
|
||||
- `initialize` 正常返回 `autodesk-knowledge-public-v1-mcp-server 1.0.12`；
|
||||
- 查 `acdbModelerRestoreEntitiesFromDwgFiler` 直接返回了 **C++ 签名**：
|
||||
`C++ ACDB_PORT Acad::ErrorStatus acdbModelerRestoreEntitiesFromDwgFiler( AcDbDwgFiler* filer, AcArray<AcDbEntity*>& entities, int* pModelerVersion = nullptr, unsigned restoreOptions = kReadStrangerEntityDefault );`（`dbacis.h`），
|
||||
查 `acdbModelerSaveEntitiesToDxfFiler` 同样命中；查 `AcDbObject::dwgOutFields` 也命中。
|
||||
- `locale` 必须是 `en_US` 这种下划线形式（传 `en-US` 会被 schema 直接打回）。
|
||||
|
||||
**这条对"工作计划第 2 项"直接有用**：`AcDb3dSolid`/`AcDbRegion` 的 modeler filer 存盘、
|
||||
版本号（`modelerVersion`：`<0` 跟随 DWG、`0` 当前、`2170` 指定版）这些参数语义，
|
||||
比翻 `Arx/*/inc/dbacis.h` 的残注释快得多；且能查到 `Arx/` 里根本没有的托管侧说明。
|
||||
|
||||
落地方式（项目级，只影响本仓库）：
|
||||
|
||||
```jsonc
|
||||
// .pi/mcp.json
|
||||
{ "mcpServers": { "autodesk-knowledge": { "url": "https://developer.api.autodesk.com/knowledge/public/v1/mcp" } } }
|
||||
```
|
||||
|
||||
代价：一次会话多一个远程 server；`search_help_content` 偶发把 Fusion/Revit 文档混进结果，需按标题过滤。
|
||||
|
||||
---
|
||||
|
||||
## 二、acad-memory-leak-skill：方法论有用，脚本要改
|
||||
|
||||
### 2.1 为什么"有用"——本仓库恰好缺这一层
|
||||
|
||||
本仓库现有工具链只测**时间**：
|
||||
|
||||
| 已有 | 作用 | 缺什么 |
|
||||
| --- | --- | --- |
|
||||
| `tools/run_acad_perf.ps1` | 开图 + `ENVIPERFDUMP` + 收 `aec_section_perf.txt`，`-CpuTrace` 抓 CPU 采样 | 没有任何内存指标 |
|
||||
| `tools/perf_diagsession.py` | `.diagsession/.etl` → 模块/函数/线程 CPU 排行 | 只管 CPU |
|
||||
| `tools/resolve_rva.ps1` | 模块+RVA → 函数名 | 同上 |
|
||||
| `ENVIPERFDUMP` 计数器 | 调用次数（截面恢复、回写、延迟建几何） | 计数量，不计量 |
|
||||
|
||||
全仓库 `rg -i "leak"` 只在 `HRL-MODEL-refactor.md:222` 命中一次，且那一句正是**否决** CRT 自检的理由：
|
||||
Debug 也链 Release CRT（`CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreadedDLL"`，Debug 还剥了 `_DEBUG`），
|
||||
所以 `_CrtSetDbgFlag` / `_CrtDumpMemoryLeaks` 全废。
|
||||
→ **内存只能从进程外部测**，而这正是这份 skill 的全部内容。这不是"可选的补充"，是唯一可行路径。
|
||||
|
||||
另外 ObjectARX/acdb 自己有分配池，"堆泄漏"和 "VirtualAlloc 池泄漏"要分开看——
|
||||
skill 里 `core/workflow.md` 的判别表（`AllocBase` 增长 = 堆；新 16 MB Private 段 = 池）
|
||||
对排查 `AecDbEwEquipment` / `AecDbSlab` 这类万行实体是直接可用的判据。
|
||||
|
||||
### 2.2 本机环境实测（决定它能不能直接用）
|
||||
|
||||
| 依赖 | 状态 | 影响 |
|
||||
| --- | --- | --- |
|
||||
| `wpr.exe` / `wpa.exe` / `xperf.exe`（WPT 10.0.26100） | ✅ 已装 | Level 2/3 可用 |
|
||||
| 管理员权限 | ✅ 当前会话是 admin | ETW 可采 |
|
||||
| 自带 `.wprp`（VirtualAlloc + SampledProfile 栈） | ✅ `wpr -start <wprp>!AcadLeak -filemode` → `-stop` 干净出 6 MB ETL | **VirtualAlloc 栈追踪这条路在本机是通的** |
|
||||
| `gflags.exe` / `umdh.exe`（Debugging Tools） | ❌ 未装 | UST/UMDH 路线不可用（不影响，skill 也没走这条） |
|
||||
| `matplotlib`（`plot_leak.py` 依赖） | ❌ 未装（Python 3.14） | 画图脚本不可用；且仓库现有报告都是 Markdown 表格，不需要 PNG |
|
||||
| Debug 构建的 CRT 自检 | ❌ 不可用（见 2.1） | 进一步说明只能用外部测量 |
|
||||
|
||||
顺带修正一条仓库旧结论：`open-drawing-perf-summary.md` 记着"`wpr -stop` 本机报 `0x80010106`（COM 线程模式）"，
|
||||
本轮实测 **`wpr -start CPU -filemode` / `wpr -stop` 均成功（exit 0，74 MB ETL）**。
|
||||
之前那次失败更像是残留 session 或 profile 冲突，可以再试 wpr 路线，不必永远绕到 `xperf`。
|
||||
|
||||
### 2.3 脚本的 4 个真问题（不修就不能用在 acad.exe 上）
|
||||
|
||||
| 脚本 | 问题 | 证据 |
|
||||
| --- | --- | --- |
|
||||
| `run_with_metering.ps1` | **无条件把 `$Iterations $Mode` 塞进 argv**。给 RealDWG 的 `leaktest.exe` 用没问题，给 `acad.exe` 会变成 `acad.exe 50 writeread /b x.scr <dwg>`，CAD 直接不认。README 写的"AutoCAD 用法"其实跑不通 | 实跑 `-Iterations 3 -Mode writeread` → 目标进程收到 `3 writeread` 当参数，报 `can't open file '3'` |
|
||||
| `dump_regions.ps1` | **不创建 `-OutDir`**，结尾再 `Resolve-Path` 它 → 首次调用必炸；而且 `Export-Csv` 只写聚合结果，README 说的"逐 region 对比 before/after"其实拿不到原始行 | 实跑：目录不存在时 `CSV:` 为空、exit 1；目录预先建好后正常出 `regions_<tag>.csv`（4 列聚合） |
|
||||
| `run_with_wpa.ps1` | 同上 argv bug；另外 `.wprp` 里声明了 `HeapEventProvider HEP.Heap` 却**没挂到 `<Collectors>` 下** → "Heap Allocations Outstanding" 图里没数据，文档宣传的堆栈追踪实际只有 VirtualAlloc 那一半 | 读脚本 60~90 行；ETL 能出但缺 heap provider |
|
||||
| `plot_leak.py` | 依赖 matplotlib（未装） | 见上 |
|
||||
|
||||
好消息：**要搬的其实只有一个 30 行的采样循环**（`while(-not $proc.HasExited){ 200ms 采 PrivateMemorySize64 }`）
|
||||
和 `dump_regions.ps1` 的 `VirtualQueryEx` 聚合逻辑。这两个跟"RealDWG / 2027"没有任何绑定，改掉 argv 就能进本仓库。
|
||||
|
||||
### 2.4 不该搬的
|
||||
|
||||
- `templates/example/leaktest.cpp` + `.vcxproj`：RealDWG 独立 exe 的复现工程，我们是 in-process ARX，用不上；且 `.vcxproj` 撞红线 #2。
|
||||
- `templates/arx/leak_repro_arx.cpp`：思路（一个 `LEAKTEST` 命令 + 循环调用可疑 API）可借，但**工程文件要改成 CMake preset**，否则不能进仓库。
|
||||
- `memxperfex.bat`：交互式 xperf，本仓库的自动化脚本风格是"无人值守 + 按 PID 收尾"，不匹配。
|
||||
- 符号服务器那段（`symbols.autodesk.com`）：只对 Autodesk 自己的 DLL 有意义；我们自己的 `.arx` 用本地 PDB（`resolve_rva.ps1` 已在做）。
|
||||
|
||||
---
|
||||
|
||||
## 三、建议采纳清单（按性价比）
|
||||
|
||||
| # | 动作 | 来源 | 成本 | 收益 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| A | `.pi/mcp.json` 挂 Autodesk Knowledge MCP | acad-api-skill / `code-sleuth.md` | 5 分钟 | 直接服务第 2、3 项工作：查 ObjectARX C++ 签名/版本语义，已实测可返回 `dbacis.h` 的函数原型 |
|
||||
| B | 新建仓库 skill `.pi/skills/acad-mem-leak/SKILL.md`：只写"4 级流程 + 判据 + 本仓库的坑"（Debug 链 Release CRT、加密构建下符号不可信、`AEC_PERF_COUNTER` 计数器优先于采样） | acad-memory-leak-skill / `core/*.md` | 30 分钟 | 把"内存问题怎么证伪"固化成可复用步骤，而不是每次重新想 |
|
||||
| C | 两个脚本改好放进 `tools/`：`mem_meter.ps1`（Private Bytes 采样，参数按本仓库约定 `/p <profile> /b <scr> <dwg>`，跑完按 PID 杀，不写回图纸）+ `mem_regions.ps1`（`VirtualQueryEx` 聚合，自动建目录） | 同上 | 40 分钟 | 内存回归可量化；也为第 2 项"3D 缓存存盘"提供"存盘后内存涨了多少"的对照数据 |
|
||||
| D | 搬 acad-api-skill 其余部分（模板 / `.csproj` / scaffold） | — | — | **不建议**：技术栈不重叠，还撞红线 #2 |
|
||||
| E | 引入 `learnings.md` append-only 日志 | acad-api-skill | 10 分钟 | **不建议**：与现有 15 篇 `*-analysis.md` 重复，维护两套记录只会分裂 |
|
||||
|
||||
**我的建议**：只做 A、B、C，跳过 D、E。
|
||||
|
||||
## 四、对"工作计划第 2 项"的连带影响
|
||||
|
||||
第 2 项是"把 `m_ar3DDrableBufPtrs_` 的 3D 缓存用 `acdbModelerSave/RestoreEntities*` 存进 DWG"，
|
||||
`pipe-section-region-performance-plan.md` 的 Phase 3（第 436~555 行）已经论证过一轮并**暂缓**，暂缓理由里有一条是
|
||||
"收益不明确——无法确定 modeler 通道比 SAT 通道显著更快"。所以第 2 项本质是**用实测把这条悬案结掉**，
|
||||
而 A（MCP 查 `dbacis.h` 语义）+ C（内存对照）正好是这项实验的两块拼图：
|
||||
|
||||
- A 解决 `modelerVersion` / `restoreOptions` 怎么给；
|
||||
- C 解决"缓存存进 DWG 后，开图内存峰值和驻留是否会失控"（3D 几何从"重建"变"反序列化"，内存曲线会变形，光看时间会误判）。
|
||||
Reference in new issue
Block a user