From 83cb1f49c84393e8f2d3283e958080612bc93ad6 Mon Sep 17 00:00:00 2001 From: company-desktop-computer Date: Thu, 29 Oct 2026 19:45:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AF=84=E4=BC=B0=E4=B8=A4=E4=B8=AA=20?= =?UTF-8?q?Autodesk=20=E5=AE=98=E6=96=B9=20skill=20=E5=AF=B9=E6=9C=AC?= =?UTF-8?q?=E4=BB=93=E5=BA=93=E7=9A=84=E9=80=82=E7=94=A8=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象：工作计划第 1 项要求判断 ADN-DevTech 的 acad-api-skill 与 acad-memory-leak-skill 对本仓库是否有帮助。两份 skill 都没有在仓库里留下结论， 下次还得重新读一遍。 结论（写入 acad-skills-evaluation.md）： - acad-api-skill：全篇 .NET 10 托管插件 / AutoCAD 2027 / NuGet / .csproj， 与本仓库 C++ ObjectARX + CMake + ZRX 双平台零重叠，模板还撞红线 2 （禁止新增 .vcxproj/.sln）。唯一有价值的是 skills/code-sleuth.md 里提到的 Autodesk Knowledge MCP 端点。 - acad-memory-leak-skill：方法论与本仓库现状对得上——本仓库 Debug 也链 Release CRT（HRL-MODEL-refactor.md:222 已记），_CrtSetDbgFlag 这类 CRT 自检不可用，内存只能从进程外部测，正是该 skill 的全部内容。但 4 个脚本里 3 个有缺陷。 文档里记录的实测证据（本轮真跑过，不是抄文档）： - Autodesk Knowledge MCP 免注册可用，直接返回 C++ 签名，例如 acdbModelerRestoreEntitiesFromDwgFiler(AcDbDwgFiler*, AcArray&, int* pModelerVersion, unsigned restoreOptions)（dbacis.h），可为工作计划第 2 项 查 modelerVersion/restoreOptions 语义；locale 必须用 en_US 下划线形式。 - 本机 WPT 齐全且当前会话是 admin；skill 自带的 VirtualAlloc .wprp 实测 wpr -start/-stop 干净出 ETL。据此修正 open-drawing-perf-summary.md 里 "wpr -stop 本机报 0x80010106" 的旧结论：现在可正常使用。 - run_with_metering.ps1 无条件把 "迭代数 模式" 拼进 argv，给 acad.exe 用会 起不来（实跑复现）；dump_regions.ps1 不创建 -OutDir 却在结尾 Resolve-Path， 首次调用必失败；run_with_wpa.ps1 的 .wprp 声明了 HeapEventProvider 却没挂进 Collectors，堆栈图拿不到 heap 数据；plot_leak.py 依赖未安装的 matplotlib。 改动范围：仅新增一篇文档，不动任何源码、脚本与工程文件。 验证方式：文档内容对应本轮的实测记录；未改代码，无需编译与 CAD 实测。 已知风险：无。建议采纳项（挂 MCP、改两个测量脚本、抽成 skill）经确认为 暂不实施，仅留档。 --- acad-skills-evaluation.md | 144 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 acad-skills-evaluation.md diff --git a/acad-skills-evaluation.md b/acad-skills-evaluation.md new file mode 100644 index 0000000..beedc3d --- /dev/null +++ b/acad-skills-evaluation.md @@ -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& 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 !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 `，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_.csv`（4 列聚合） | +| `run_with_wpa.ps1` | 同上 argv bug；另外 `.wprp` 里声明了 `HeapEventProvider HEP.Heap` 却**没挂到 `` 下** → "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 /b `，跑完按 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 几何从"重建"变"反序列化"，内存曲线会变形，光看时间会误判）。 -- 2.54.0