博客之家-Feng

本文说明如何为 CATIA V5 CAA 二次开发创建一个面向 mkmk 编译体系的 skill。这里的“mk 编译器”不是重新实现一个编译器，是把 CAA 的 mkmk、Imakefile.mk、IdentityCard、前置框架、运行时视图和常见错误诊断规则封装成一份可被 AI 编程助手按需加载的领域技能说明。

如果团队经常在编程智能体中分析 CAA 工程、修正编译错误、补依赖、维护 Imakefile.mk，这个 skill 的价值很直接：让编程助手在看到 mkmk、LINK_WITH、mkGetPreq、mkCreateRuntimeView、mkrun、未解析外部符号、找不到头文件等问题时，自动进入 CAA RADE 的构建语境，而不是把它误判成普通 Make/CMake 项目。

1. 先理解 skill 要包装的对象

CAA V5 的 mkmk 是 RADE 提供的代码构建器。官方文档把它描述为 CAA V5 code builder，可构建 C、C++、Express、Fortran、Java 等源文件。在 CAA C++ 项目中，它通常负责以下几类工作：

对象	典型文件/命令	作用
框架身份	`IdentityCard/IdentityCard.xml` 或旧式 `IdentityCard.h`	声明 framework 的类型、是否构建、前置 framework 以及访问级别。
模块规则	`*.m/Imakefile.mk`	声明模块产物类型、链接依赖、平台条件和构建规则。
编译主命令	`mkmk`	编译 identity card、生成公开头文件列表、检查/更新 `Imakefile.mk` build-time data，并编译链接模块。
前置框架	`mkGetPreq` 、`mkPrintPreq`、`mkCopyPreq`	建立或检查当前 workspace 对其他 workspace/framework 的依赖可见性。
运行时视图	`mkCreateRuntimeView`	把 `CNext` 资源复制或链接到运行时文件树；CATIA 运行时只认识 runtime view。
运行环境	`mkrun`	在正确的 PATH、library path、CATIA/CAA 环境变量下执行命令或程序。
清理派生物	`mkRemoveDo`	删除派生对象，通常用于清理过期 build 结果；应先模拟或确认范围。

mkmk 默认执行四个关键阶段：

编译 framework identity card。
生成 framework 对外公开头文件列表。
检查并更新模块 Imakefile.mk 对应的 build-time data。
执行真正的编译和链接；共享库场景下会分阶段处理，以便处理库之间的链接关系。

因此，一个合格的 mkmk skill 不能只写“运行 mkmk”。它应该引导编程助手先判断当前目录是 workspace、framework 还是 module，再检查 IdentityCard、Imakefile.mk、前置框架、运行时视图和命令输出。

2. skill 适合解决什么问题

建议把这个 skill 的目标控制在“CAA 构建和运行诊断”这一类任务中，避免做成泛化的 C++ 助手。它应该在以下场景被触发：

编译 CAA framework 或 module。
解释或修复 mkmk 输出中的错误。
维护 Imakefile.mk 的 BUILT_OBJECT_TYPE、LINK_WITH、平台条件。
维护 IdentityCard.xml 或旧式 IdentityCard.h 中的 prerequisites。
使用 mkGetPreq、mkPrintPreq 检查前置 framework。
创建或刷新 runtime view。
使用 mkrun 启动测试程序、批处理程序或 CATIA 相关命令。
处理找不到头文件、找不到库、未解析外部符号、NLS/图标/资源未进入运行时视图等问题。

它不应该试图替代 CAA 架构设计、COM 接口设计、Feature Modeler 建模、命令状态机设计等更大的主题。那些内容可以拆成另外的 skill，例如 catia-caa-command-skill、catia-caa-feature-skill。

3. 推荐的目录结构

在工作区级别创建 skill 时，推荐放在：

.github/skills/catia-mkmk-compiler/SKILL.md

如果想给 skill 配套一些模板和检查清单，可以扩展成：

.github/skills/catia-mkmk-compiler/
  SKILL.md
  references/
    mkmk-diagnosis-checklist.md
    imakefile-patterns.md
    identitycard-prerequisites.md
  templates/
    Imakefile-shared-library.mk
    Imakefile-load-module.mk

最小可用版本只需要 SKILL.md。后续如果团队积累了自己的 framework 命名规则、常用 LINK_WITH 组合、内部工具路径和错误排查经验，再把它们沉淀到 references 或 templates 目录中。

4. `SKILL.md` 的 frontmatter

skill 的发现主要依赖 frontmatter 中的 description。这段描述必须包含真实触发词，尤其是 CAA 开发者实际会说出来的词，例如 mkmk、Imakefile.mk、IdentityCard、mkGetPreq、LINK_WITH、mkCreateRuntimeView、mkrun。

推荐写法如下：

---
name: catia-mkmk-compiler
description: "Use when: compiling CATIA V5 CAA C++ projects with mkmk, diagnosing Imakefile.mk, IdentityCard prerequisites, mkGetPreq, mkPrintPreq, mkCreateRuntimeView, mkrun, LINK_WITH, missing headers, unresolved externals, CAA runtime view, RADE build errors."
---

注意三点：

name

最好和目录名一致，即 catia-mkmk-compiler。
description

中含冒号时要加引号，避免 YAML 解析失败。
不要把 description 写得太抽象，例如“CAA helper”。抽象描述很难被自动命中。

5. 可直接使用的 skill 正文模板

下面是一份可直接保存为 .github/skills/catia-mkmk-compiler/SKILL.md 的模板。团队可以在此基础上继续添加本地规则。

---
name: catia-mkmk-compiler
description: "Use when: compiling CATIA V5 CAA C++ projects with mkmk, diagnosing Imakefile.mk, IdentityCard prerequisites, mkGetPreq, mkPrintPreq, mkCreateRuntimeView, mkrun, LINK_WITH, missing headers, unresolved externals, CAA runtime view, RADE build errors."
---

# CATIA V5 CAA mkmk Compiler Skill

You are assisting with CATIA V5 CAA C++ build and runtime setup tasks. Treat `mkmk` as the CAA RADE code builder, not as ordinary GNU make, CMake, MSBuild, or Visual Studio project generation.

## Core Model

- A CAA workspace contains frameworks.
- A framework owns `IdentityCard/IdentityCard.xml` or older `IdentityCard/IdentityCard.h`.
- A framework contains modules named `*.m`.
- A module usually contains `Imakefile.mk`, `src`, `LocalInterfaces`, and may depend on framework-level `PublicInterfaces`, `ProtectedInterfaces`, `PrivateInterfaces`, and generated interfaces.
- `IdentityCard` declares framework prerequisites.
- `Imakefile.mk` declares module build output and link dependencies.
- `mkGetPreq` defines a dynamic prerequisite search path.
- `mkmk -u` should be considered after prerequisite search path changes.
- `mkCreateRuntimeView` prepares runtime resources and binaries for CATIA execution.
- `mkrun` starts commands under the CAA runtime environment.

## First Response Workflow

When the user reports a build issue:

1. Identify whether the current path is a workspace root, framework directory, or module directory.
2. Locate the target framework, target module, `IdentityCard`, and `Imakefile.mk`.
3. Ask for or inspect the exact `mkmk` output before changing files.
4. Classify the failure as one of: missing header, missing framework prerequisite, missing `LINK_WITH`, stale build-time data, generated interface issue, resource/runtime-view issue, linker/runtime library issue, or environment issue.
5. Prefer the smallest fix consistent with CAA conventions.

## Files To Inspect

- `IdentityCard/IdentityCard.xml`
- `IdentityCard/IdentityCard.h`
- `*.m/Imakefile.mk`
- `*.m/src/*`
- `PublicInterfaces/*`
- `ProtectedInterfaces/*`
- `PrivateInterfaces/*`
- `ImportedInterfaces/<OS>/*`
- `<OS>/code/bin/*`
- `Install_config`

## Command Guidance

- Use `mkmk -h` to confirm options on the installed level.
- Use `mkmk` in a module directory to build the current module.
- Use `mkmk ModuleName` in a framework directory to build one module.
- Use `mkmk -a` from a workspace or framework when the user explicitly wants all relevant targets.
- Use `mkmk -u -nobuild` when only build-time data regeneration is needed.
- Use `mkmk -showcmd` when the actual compiler or linker command line is needed.
- Use `mkmk -g` for debug build, while remembering that on Windows mkmk keeps compatibility with release Visual C++ runtime usage.
- Use `mkPrintPreq -l -f FrameworkName` to inspect direct and indirect prerequisites.
- Use `mkGetPreq -p <workspace-path-list>` to define prerequisite concatenation. On Windows, separate paths with semicolons; on Unix, use colons.
- Use `mkCreateRuntimeView` after resources, command headers, icons, NLS, or runtime files change.
- Use `mkrun -c "command args"` to run commands in the CAA environment.
- Treat `mkRemoveDo` as destructive cleanup. Prefer simulation first and ask before deleting derived objects.

## Imakefile Rules

- `BUILT_OBJECT_TYPE=SHARED LIBRARY` builds a regular shared library/DLL.
- `BUILT_OBJECT_TYPE=LOAD MODULE` builds an explicitly loaded module.
- `BUILT_OBJECT_TYPE=ARCHIVE` builds an archive/static library-like output.
- `BUILT_OBJECT_TYPE=NONE` is used when the module does not produce a binary output.
- `LINK_WITH` must explicitly include modules/framework libraries needed at link time.
- Keep wizard-managed zones intact when present.
- Do not add random system libraries until the missing symbol or header has been traced to the owning CAA framework/module.

## IdentityCard Rules

- Prefer `IdentityCard.xml` on newer levels.
- Use `mkICE` to edit XML Identity Cards when available.
- Use `mkCreateIC` to create an empty XML Identity Card instead of copying one blindly.
- Use `mkIc2Xml` only for one-shot migration from old `.h` identity cards.
- API CD-ROM or installed CAA framework prerequisites are typically declared with public access.
- After changing prerequisites, refresh prerequisite information and consider `mkmk -u`.

## Diagnostic Heuristics

- Missing header usually points to missing framework prerequisite, wrong public/protected/private interface visibility, stale imported interfaces, or missing generated interfaces.
- Unresolved external symbol usually points to a missing `LINK_WITH` module, wrong `BUILT_OBJECT_TYPE`, or a link order/dependency problem.
- Command loads but UI resources are missing usually points to runtime view, NLS, icons, command header resource files, or `CATGraphicPath`/runtime environment.
- A module visible through concatenation may be readable but not safely editable. Local modifications require the relevant local framework/module structure.
- After changing CNext resources, command headers, NLS, icons, or catalogs, refresh runtime view before testing in CATIA.

## Safety

- Do not run destructive cleanup commands without user approval.
- Do not unload and reload CAA DLLs inside a running CATIA session as a normal workflow; restart the session when changing loaded binaries.
- Do not rewrite unrelated framework structure while fixing a build issue.
- Preserve local wizard zones and existing team conventions.

这份模板的重点不是“让 AI 记住几个命令”，而是强制它从 CAA 的构建图来思考：framework 依赖在 IdentityCard，模块链接在 Imakefile.mk，运行资源在 runtime view，执行环境由 mkrun 建立。

6. skill 中应该内置的 mkmk 心智模型

一个 CAA 编译问题通常沿着下面这条链路传播：

IdentityCard prerequisites
  -> mkGetPreq / Install_config
  -> ImportedInterfaces / header list
  -> Imakefile.mk / LINK_WITH
  -> mkmk compile and link
  -> OS/code/bin output
  -> mkCreateRuntimeView
  -> mkrun / CATIA runtime load

诊断时不要跳着改。比如“找不到某个头文件”不一定是 include 写错，更常见的是 framework prerequisite 没声明、mkGetPreq 没更新、公开/受保护/私有接口使用边界错了，或者 build-time data 没刷新。又比如“未解析外部符号”通常和 LINK_WITH 相关，但也要确认符号所在模块到底是 shared library、load module 还是 archive。

7. `Imakefile.mk` 模板片段

典型 CAA 模块的 Imakefile.mk 很短，但含义很重。下面是一个共享库示意：

BUILT_OBJECT_TYPE=SHARED LIBRARY

# DO NOT EDIT :: THE CAA2 WIZARDS WILL ADD CODE HERE
WIZARD_LINK_MODULES =
# END WIZARD EDITION ZONE

LINK_WITH = $(WIZARD_LINK_MODULES) \
            JS0GROUP \
            CATObjectModelerBase \
            CATMathematics \
            CATApplicationFrame

常见产物类型可以这样理解：

`BUILT_OBJECT_TYPE`	典型用途
`SHARED LIBRARY`	普通 DLL/共享库，很多 CAA 实现模块和接口实现模块使用它。
`LOAD MODULE`	显式加载模块，常见于被框架按 late type、factory、command 等机制加载的模块。
`ARCHIVE`	归档库，用于被其他模块静态链接或作为基础对象集合。
`NONE`	不产生二进制，常见于只承载接口、IDL、UUID 或生成内容的模块。

skill 应提醒助手：LINK_WITH 不是“把所有看起来相关的库都加进去”。正确做法是先定位头文件、接口或符号的拥有 framework/module，再补最小依赖。

8. IdentityCard 规则片段

在旧式 IdentityCard.h 中，framework prerequisites 常见写法类似：

AddPrereqComponent("System", Public);
AddPrereqComponent("ObjectModelerBase", Public);

在较新的 XML identity card 中，应优先用 mkICE 编辑，避免手写 XML 时破坏 schema、命名空间或层级。示意结构如下，具体以当前安装级别的 mkICE 生成结果为准：

<codeFrameworkxmlns="http://www.3ds.ic">
<prerequisitename="System"access="Public" />
<prerequisitename="ObjectModelerBase"access="Public" />
</codeFramework>

当修改了 prerequisites，skill 应引导执行或建议以下检查：

mkPrintPreq -l -f MyFramework
mkmk -u -nobuild MyFramework

如果使用动态前置路径，则 Windows 使用分号分隔 workspace 路径：

mkGetPreq -p D:\CAA\BaseWs;D:\CAA\TeamWs

Unix/Linux/AIX 环境则通常使用冒号分隔：

mkGetPreq -p /u/caa/base:/u/caa/team

9. 构建命令建议写进 skill

下面这些命令是 mkmk skill 中最常用的判断入口：

rem 查看 mkmk 用法
mkmk -h

rem 在当前 module 目录构建当前模块
mkmk

rem 在 framework 目录构建指定 module
mkmk MyModule.m

rem 在 workspace 或 framework 范围构建全部目标
mkmk -a

rem 只刷新 build-time data，不真正编译
mkmk -u -nobuild

rem 展开底层编译/链接命令，适合分析 include/lib 路径
mkmk -showcmd

rem 调试构建
mkmk -g

rem 查看 framework 的直接和间接前置依赖
mkPrintPreq -l -f MyFramework

rem 刷新运行时视图
mkCreateRuntimeView

rem 在 CAA 环境下运行命令
mkrun -c "MyExecutable arg1 arg2"

在 Windows 上，如果使用 mkrun，还要注意官方文档提到的 C:\temp 目录要求；一些环境脚本会在该目录下生成临时 bat 文件。

10. skill 的诊断流程可以这样设计

当用户说“mkmk 编译不过”时，skill 应让助手按下面顺序推进：

定位当前工作目录：workspace root、framework、还是 *.m module。
找到目标 framework 和 module。
读取 Imakefile.mk，确认 BUILT_OBJECT_TYPE 和 LINK_WITH。
读取 IdentityCard.xml 或 IdentityCard.h，确认 prerequisites。
检查 Install_config 或让用户提供 mkGetPreq 设置方式。
根据错误类型决定下一步：

找不到头文件：查 interface 所在 framework、prerequisite、ImportedInterfaces、公开级别。
未解析外部符号：查 symbol 所在模块、LINK_WITH、产物类型。
找不到 DLL/load module：查构建输出、runtime view、mkrun 环境。
资源缺失：查 CNext/resources、NLS、图标、mkCreateRuntimeView。

只改必要文件，保留 wizard 区域和团队已有格式。
构建后给出验证命令和剩余风险。

这个流程能避免一个常见错误：看到链接错误就盲目向 LINK_WITH 追加大量库。CAA 的依赖关系应当是可解释的，最好能说明“为什么是这个 framework/module”。

11. 常见坑应写进 skill

把 mkmk 当成普通 make

mkmk 会处理 CAA 特有的 identity card、header list、build-time data、generated interfaces 和 runtime view 约定。不要用普通 Makefile/CMake 的经验直接替代它。

忘记刷新前置框架

IdentityCard 改了以后，不等于构建环境自动可见。通常要重新管理 prerequisites，并考虑 mkmk -u。

`LINK_WITH` 和 `IdentityCard` 混淆

IdentityCard 解决 framework 级别的可见性和前置关系，LINK_WITH 解决 module 级别的链接关系。头文件能找到不代表链接一定能过；链接库存在也不代表 framework prerequisite 合理。

资源构建成功但 CATIA 里看不到

命令标题、图标、NLS、catalog、.CATfct 等资源经常需要 runtime view。编译成功后仍然要 mkCreateRuntimeView，再用 mkrun 或正确环境启动 CATIA/测试命令。

在运行中的 CATIA 里反复卸载/加载 DLL

官方 FAQ 明确不建议把卸载再加载 DLL 当作常规开发流程。DLL 地址变化、对象持有旧接口指针等问题可能导致不可预测崩溃。改了已加载模块后，重启 CATIA 会更稳。

Windows OS 名称混乱

老文档里常见 intel_a 表示 Windows 32 位平台；当前 B28 安装库中常见目录是 win_b64。skill 应提醒助手以当前环境的 $MkmkOS_VAR 或实际生成目录为准，不要机械照抄旧文档中的平台名。

12. 创建后的验证方式

创建 skill 后，可以在 VS Code 里用这些测试问题验证它是否会被触发：

我的 CAA 模块 mkmk 编译找不到 CATApplicationFrame 的头文件，帮我看 Imakefile 和 IdentityCard。

这个模块 unresolved external symbol，应该补哪个 LINK_WITH？

我修改了命令图标和 CATNls，mkmk 成功但 CATIA 里没有变化，怎么查 runtime view？

帮我检查 mkGetPreq 和 mkPrintPreq 输出，看这个 framework 的 prerequisites 是否完整。

如果助手仍然按普通 C++ 项目分析，通常是 description 触发词不够明确，或者 skill 没放在 VS Code 支持的位置。优先检查：

SKILL.md

是否位于 .github/skills/catia-mkmk-compiler/。
frontmatter 是否由上下两个 --- 包住。
name

是否和目录名一致。
description

是否加了引号。
description

是否包含 mkmk、Imakefile.mk、IdentityCard、LINK_WITH 等关键词。

13. 可参考的本地官方文档

本安装库中与本文相关的 CAA 文档主要在以下位置：

CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMANMkmk.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMANMkThemIx.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMkHandBook.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMkOthers.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMkICEV5.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMkCreateICV5.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlMkIc2XmlV5.htm
CAADoc/Doc/online/CAABtlQuickRefs/CAABtlFAQ.htm
CAAStudio/wxpug0206.htm

其中：

CAABtlMANMkmk.htm

说明 mkmk 的目的、默认阶段、常用选项和目标选择方式。
CAABtlMANMkThemIx.htm

汇总 mkmk 周边命令。
CAABtlMkHandBook.htm

给出构建 framework/module、管理 prerequisites、运行程序和文件后缀位置的快速表。
CAABtlMkOthers.htm

说明 mkGetPreq、mkPrintPreq、mkCreateRuntimeView、mkrun、mkRemoveDo 等命令。
CAABtlMkICEV5.htm

说明 XML Identity Card 编辑器 mkICE。
CAABtlFAQ.htm

包含一些 mkmk 常见问题，例如 Windows PDB warning、避免卸载/重载模块、/clr 不支持等。

14. 最小落地步骤

最终落地可以按这个顺序做：

在仓库创建 .github/skills/catia-mkmk-compiler/。
新建 SKILL.md，写入上面的 frontmatter 和正文模板。
把团队常用 Imakefile.mk、IdentityCard 示例、常见错误清单放入 references 或 templates。
用真实 mkmk 错误提问，验证 skill 是否自动命中。
根据团队项目继续补充 framework 命名、常用 LINK_WITH 组合和内部运行命令。

一个好的 mkmk skill，本质上是把 CAA 老工程师脑子里的构建图显式写出来：先看 workspace/framework/module 边界，再看 identity card 和 prerequisites，再看 module 的 Imakefile.mk，最后才看编译器和链接器命令本身。这样 AI 才能在 CAA V5 的规则里判断问题，而不是只按普通 C++ 工程做猜测。

如何创建一个 CATIA CAA mkmk 编译器 Skill

1. 先理解 skill 要包装的对象

2. skill 适合解决什么问题

3. 推荐的目录结构

4. `SKILL.md` 的 frontmatter

5. 可直接使用的 skill 正文模板

6. skill 中应该内置的 mkmk 心智模型

7. `Imakefile.mk` 模板片段

8. IdentityCard 规则片段

9. 构建命令建议写进 skill

10. skill 的诊断流程可以这样设计

11. 常见坑应写进 skill

把 mkmk 当成普通 make

忘记刷新前置框架

`LINK_WITH` 和 `IdentityCard` 混淆

资源构建成功但 CATIA 里看不到

在运行中的 CATIA 里反复卸载/加载 DLL

Windows OS 名称混乱

12. 创建后的验证方式

13. 可参考的本地官方文档

14. 最小落地步骤

评论

如何创建一个 CATIA CAA mkmk 编译器 Skill

1. 先理解 skill 要包装的对象

2. skill 适合解决什么问题

3. 推荐的目录结构

4. SKILL.md 的 frontmatter

5. 可直接使用的 skill 正文模板

6. skill 中应该内置的 mkmk 心智模型

7. Imakefile.mk 模板片段

8. IdentityCard 规则片段

9. 构建命令建议写进 skill

10. skill 的诊断流程可以这样设计

11. 常见坑应写进 skill

把 mkmk 当成普通 make

忘记刷新前置框架

LINK_WITH 和 IdentityCard 混淆

资源构建成功但 CATIA 里看不到

在运行中的 CATIA 里反复卸载/加载 DLL

Windows OS 名称混乱

12. 创建后的验证方式

13. 可参考的本地官方文档

14. 最小落地步骤

评论

4. `SKILL.md` 的 frontmatter

7. `Imakefile.mk` 模板片段

`LINK_WITH` 和 `IdentityCard` 混淆