# MCP_CREO_MechDog 0.8.5

开发维护从 [开发入口](docs/DEVELOPMENT.md) 和 [统一功能台账](docs/BACKLOG.md) 开始。每项工作先定义验收；语言与单元检查、Creo 实机验收分别记录。项目采用渐进布局整理，当前支持环境见 [兼容矩阵](docs/COMPATIBILITY.md)。

本地 Windows MCP 服务，按需启动或连接 Creo Parametric 9 / 10 / 12，通过官方 C/C++ Toolkit 创建、查询和修改**原生参数化特征**。当前开发与发布按本机 Creo 12.4.0.0 的改动范围验收；Creo 10 不再要求独立复测。Creo 9 与 Toolkit 9 已纳入支持／要求范围，编译探测修复已实现，但本机无 Creo 9 SDK，实机编译与建模运行时均未验收。各环境已测和未测范围见[兼容矩阵](docs/COMPATIBILITY.md)。典型建模流程为：新建零件 → 草图 → 拉伸／旋转 → 切除／孔 → 后续特征；底板接口保留为快捷工具。

当前注册 **94 个工具**，实际可见清单以 `creo_capabilities` 为准。接口覆盖常见实体特征、磁盘模型打开、受管副本接管、会话枚举、**装配只读检查与回放规划**、受控恢复、**显式世代回收**及直接混合，**尚未完成所有 Creo 操作和参数组合的覆盖**。禁用操作从工具列表隐藏，并在提交前拒绝。服务使用官方 Python MCP SDK 2.3.0、stdio 传输，采用 [MIT 许可证](LICENSE)。使用者在自己的 Windows 电脑上安装依赖并编译 Toolkit 执行器，由本地 AI 客户端调用。

当前正式版 **0.8.5**：折边方向改由 `PRO_E_SMT_FLANGE_SEC_FLIP` 控制，默认 `flip=false` 为从选中面向外，旧方向假设须重新核对；本机两例实机均 +18 025.29 mm³、Z 增长 79 mm 并保存重载。钣金体并入式实体 add 已按实测边界新增 `SHEETMETAL_SOLID_ADD_UNSUPPORTED` 拒绝码，`new_body=true` 可建独立实体。公开工具仍为 **94 个**。四壁只完成 2/4，`relief` 尚无可观测切料，T13 bundle 不通过。T08B 5/5、T09A 4/4、T09B 3/3、T12 3/3 已取得本机证据；T02/T06/T07/T08A 保留 [0.8.3 证据](docs/validation/RELEASE-0.8.3.md)，T03 首壁保留 [0.8.4 证据](docs/validation/RELEASE-0.8.4.md)。升级请使用 0.8.5 种子包，并阅读[0.8.5 版本说明](docs/RELEASE_NOTES_0.8.5.md)及[发布记录](docs/validation/RELEASE-0.8.5.md)。本版发布阶段不新连 Creo、不使用 WorkBuddy。

服务后台检测已有会话、协调启动并检查建模就绪；成功建模及保存重载才证明相应操作在该环境可用。启动配置和排错见[安装说明](docs/INSTALL.md)。

普通混合可直接创建或追加，范围见 [直接混合](docs/DIRECT_BLEND_0.2.5.md)；种子复用见 [调用说明](docs/LOFT_SEED.md)、[多截面](docs/MULTISECTION_BLEND.md)。草图支持 `dimensioning="auto" / "autodim" / "coordinates"`，坐标模式的范围与尺寸编辑规则见 [草图说明](docs/SKETCH_STABILITY_0.2.5.md)。迁移步骤见 [种子库](docs/SEED_LIBRARY.md) 和 [换电脑、换 Agent](docs/MIGRATION.md)。

直接混合使用固定注册入口与升级预检：按下文一次性设置及[生命周期说明](docs/CALLBACK_LIFECYCLE.md)完成正式注册、持久配置与手动启动，再查 `creo_callback_status`；只有实时 `ready` 才提交直接混合。查询和建模不加载 DLL、不修改安全策略。升级、回退及多目录并存等剩余验收见[统一台账](docs/BACKLOG.md)。新建种子放样不需要此回调。

工程图、曲面、布尔、筋、UDF、钣金和装配各有验收范围，见[兼容矩阵](docs/COMPATIBILITY.md)；旧版测试与来源见[历史资料](docs/BACKLOG_COMPLETED.md)。新版本不会改写已发布的 GitHub 源码或附件。

[版本检查与提醒](docs/UPDATE_CHECK.md)的断网期间建模、高版本提示及客户端展示等剩余验收仍按台账跟进。0.2.6 旧发布需先手动升级一次才可收到后续更新提醒。

Python 包迁移前两批已完成，更新检查、输入模型及轮廓／翼型辅助实现位于 `src/creo_mechdog/`，整体迁移仍继续。现有开发环境更新源码后执行 `python -m pip install --no-deps -e .`；正常安装由 `setup.ps1` 完成。根入口和数据位置保留，见[迁移任务卡](docs/work-items/DEV-002.md)。

模型引用须按具体工具的参数形状选择，见[引用格式](docs/REFERENCE_SYNTAX.md)。

### 0.5.2 反馈的矩阵与结果迁移口径

`creo_inspect_session_assembly` 的 `transform_to_parent` / `transform_to_root` 是**毫米归一化**的行向量 4×4 矩阵：局部毫米坐标乘矩阵得到父级／根级毫米坐标，平移在末行。`*_raw` 保留 Creo 查询所得原始矩阵及其源／目标模型单位，不可直接作为毫米放置参数。每个节点的 `units.component` / `units.parent` 和装配的 `assembly.length_unit` 提供实际单位名、毫米换算和查询码；缺失或未确认时相应值为 `null`，不能把未知当作毫米。

例如组件为英寸、父装配为毫米时，先确认双方单位及查询结果，再使用完整的 `transform_to_parent` 映射毫米点。若把 raw 定义为 `p_parent_raw = p_local_raw × R_raw + t_raw`，且组件、父级每原始单位分别为 `s_local`、`s_parent` 毫米，则 `p_parent_mm = p_local_mm × (s_parent/s_local × R_raw) + s_parent × t_raw`。混合单位影响 3×3 块与平移，不能只缩放平移。回放位姿时只从**有效的** `transform_to_parent` 取左上 3×3 和末行前三项，并满足 `rotation_matrix` 的正交／行列式校验；单位未知或矩阵不能表达刚体位姿时停止，重新取得证据，不猜测坐标。详见[装配重建管线](docs/ASSEMBLY_REBUILD.md#位姿与矩阵约定)。

`unchanged=true` 只说明对应操作走了**原生几何核验过的同几何快捷路径**；不能据此假定所有写操作都无效果，也不能把同值 `creo_set_dimensions` 自动视为 `unchanged`。成功作业仍按接口保存、重载并推进约定的 revision。批量结果的执行与最终提交／回滚语义以[DEV-047 共享基线](docs/work-items/DEV-047.md#interface-baseline)为准。

## 安装

升级后先重启目标 MCP 连接器，再核对实际路径、启动指纹和工具清单；现有模型接管流程与未测边界见[接管说明](docs/ADOPTION.md)。

准备 Windows x64、Python 3.12+ x64、Creo Parametric 9、10 或 12 及匹配的 Toolkit SDK、MSVC x64 C++ 构建工具和可用的 PTC 许可。Creo 9 与 Toolkit 9 的编译探测修复已实现，实机编译与建模运行时未在本机验收。Creo 软件、SDK、模板和许可需要自行取得；MIT 适用于本项目代码、文档及种子库的原创内容，不提供 PTC 软件授权。第三方依赖和 PTC 前置条件见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

1. 下载源码，解压到较短的可写目录，例如 `C:\MCP_CREO_MechDog`；下列命令在该目录执行。
2. 运行安装脚本，填写自己的 Creo 安装根目录：

   ```powershell
   .\setup.ps1 -CreoRoot 'C:\Program Files\PTC\Creo 10.0.0.0'
   ```

   Creo 12.4 的安装示例：

   ```powershell
   .\setup.ps1 -CreoRoot 'C:\Program Files\PTC\Creo 12.4.0.0'
   ```

   按自己的安装位置替换路径，使用对应版本的 Toolkit SDK 在目标机重新构建。

   如果 Python 没有加入 PATH，可加 `-Python 'C:\Path\To\python.exe'`。如果编译器没有自动找到，可加 `-VcVars64 'C:\Path\To\vcvars64.bat'`。这两个示例路径需要替换。
3. 安装成功后，脚本生成本机 `config.json`、`.venv/`、`build/` 和 `client-config.json`。将 `client-config.json` 中的服务配置加入支持本地 stdio MCP 的 AI 客户端。
4. 启动客户端中的 MCP 服务，服务自动复用已有 Creo 或按配置启动。让 AI 调用 `creo_startup_status` 等待 `state == "ready"`，再用 `creo_session_status` 确认连接后提交建模计划。若 Creo 显示启动对话框，由使用者处理。成功建模及保存重载验证才证明相应操作在该环境可用。

脚本不修改全局客户端配置。完整安装与排错说明见 [docs/INSTALL.md](docs/INSTALL.md)；GitHub 源码发布步骤见 [docs/PUBLISH_GITHUB.md](docs/PUBLISH_GITHUB.md)。GitHub 仓库用于分发源码，服务在使用者的电脑运行。

### 直接混合（Blend）的一次性回调设置

`creo_loft` / 计划内 `loft`（直接混合）依赖一个常驻回调 DLL，须由使用者完成一次正式注册；未就绪时建模前会被明确拒绝（`BLEND_CALLBACK_SETUP_REQUIRED`）。**新建种子放样（`creo_new_loft_part`、`creo_new_airfoil_blade`）不需要此回调**。一次性步骤：

1. 构建后在 `build\blend_callback_setup.json` 或 `creo_callback_status` 返回中确认 `registry_file`（固定入口 `<安装目录>\build\blend_callback_protk.dat`）。
2. 在 Creo 的「辅助应用程序」（Auxiliary Applications）对话框注册该 `registry_file` 一次，手动启动它并亲自确认 DLL 安全提示；不要直接注册 `module_file`。
3. 跨 Creo 重启保持条目：把 `build\blend_callback.config.pro` 中的 `protkdat <注册文件绝对路径>` 一行合入实际加载的 config.pro（生成片段不会被自动读取）。
4. 正常重启 Creo 后条目应自动出现（`delay_start true` 仍需手动 Start）。
5. 查询 `creo_callback_status`：`readiness=ready` 才提交直接混合；`not_loaded`（可确定未加载，含首次）的 `instruction` 首行即注册入口，`unknown` 表示无法确认，保守处理。

MCP 不会代为注册、加载 DLL 或修改 Creo 安全策略。完整流程、升级/回退与限制见 [生命周期说明](docs/CALLBACK_LIFECYCLE.md)。

## 建模能力

| 类别 | 工具及能力 |
| --- | --- |
| 零件与建模计划 | `creo_new_part`、`creo_execute_plan`：新建毫米零件，或对已有 MCP 零件逐步追加特征 |
| 草图 | `creo_create_sketch`：直线、中心线、圆、圆弧、矩形、多段线、样条、椭圆；显式尺寸和约束；auto/autodim/coordinates 尺寸策略 |
| 拉伸 | `creo_extrude`：实体增材、切除、贯穿切除、曲面、薄壁、正/反向、对称深度、新实体；切除未去料（板外草图、方向/深度错误或已去除区域）时失败回滚，成功操作详情返回material_removed_mm3 |
| 旋转 | `creo_revolve`：实体旋转、旋转切除、指定角度，使用草图中心线或外部轴；提供曲面、薄壁和对称角度分支；切除零去料同样失败回滚并返回material_removed_mm3 |
| 孔 | `creo_hole`：原生直孔及可选沉孔／沉头，平面定位，两条独立平面参考或共面直边及有符号偏置；通孔或盲孔，flip 反转切削侧。沉孔/沉头 T12 指定 3/3 实机通过（180° 按契约拒绝）；其余尺寸编辑仍待验 |
| 修饰特征 | `creo_round`、`creo_chamfer`、`creo_shell`：恒定半径圆角、等距倒角、恒定厚度抽壳；用查询得到的边/面 ID 选引用 |
| 基准与重复 | `creo_datum_plane`、`creo_datum_axis`、`creo_dimension_pattern`：偏移/角度基准面、基准轴、一方向尺寸阵列 |
| 镜像、扫掠、拔模 | `creo_mirror`：整体/几何镜像；`creo_sweep`：恒定截面及命名截面尺寸；`creo_draft`：恒角、不分割拔模 |
| 钣金 | `creo_new_sheetmetal`、`creo_sheetmetal_wall`、`creo_sheetmetal_flange`、`creo_sheetmetal_unbend`、`creo_sheetmetal_bend_back`、`creo_sheetmetal_flat_pattern`：首壁参数建模前校验、可选 `relief`（默认 `none`）、折边、展开、折弯回去和平展；首壁五组已在 0.8.4 实机通过；0.8.5 两道折边几何与方向通过，四壁仅 2/4、relief 去料未证实；钣金体并入式实体 add 明确拒绝。**开发分支（未发布）新增** `creo_sheetmetal_flange` 的可选 `end_trim_mm`：模型单位的正数（`>0`，上限 100000，布尔值拒绝），把两侧链端各缩短该长度，缺省时元素树与旧行为完全一致；**它在 Creo 中究竟按链端 setback 还是按截面起算的壁长读取尚未实机确认，属诊断用途**，先用自由壁探针实测再依赖修剪几何 |
| 装配 | `creo_new_assembly`、`creo_assemble_component`、`creo_component_placement`、`creo_component_constraints`、`creo_remove_component`、`creo_list_components`：组件版本快照、定位（Euler 或互斥的嵌套 3×3 `rotation_matrix`）、约束、删除和查询；含组件操作的作业附 `component_changes` 有界变更摘要（committed/rolled_back/unknown_outcome），`list_components` 约束保留数字 `type` 并附 `type_name` 符号；单作业插入多个组件与官方重建管线见 [ASSEMBLY_REBUILD.md](docs/ASSEMBLY_REBUILD.md)；矩阵放置子项已在本机 Creo 12.4 实机通过（0.6.0 交付，38 父作业含故意失败回滚），显式源件更新与嵌套装配仍开放，见 [FEAT-012](docs/work-items/FEAT-012.md)。`creo_list_components` 的每条组件记录另带业务身份字段 `identity`/`labels`/`label`/`label_state`/`source_model_id`/`source_revision`/`bindings`，顶层带 `deleted_identities` 与 `identity_key`；关联键是**模型身份 + feature_id**，label 只是业务名，删除重插后旧标签不误指新组件 |
| 新增曲面与实体 | `creo_surface_fill`、`creo_thicken`、`creo_solidify`、`creo_boolean_bodies`、`creo_rib` |
| 新增基准 | `creo_datum_csys`、`creo_datum_points` |
| 原生工程图 | `creo_new_drawing`；图纸、一般/投影视图、尺寸显示、注释、表格及编辑/删除；原生 DRW 与 PDF 输出 |
| UDF 特征库 | `creo_inspect_udf`、`creo_create_udf`：查询并复用用户的 .gph，保留组内原生参数特征 |
| 普通混合种子复用 | `creo_new_loft_part`：按新 XY 截面和模式自动选择随包种子；自动匹配 2/3/4/6 的直线和平滑及 5 的平滑，其他数量需显式兼容种子或使用直接混合；`creo_list_seeds`、`creo_validate_seed`、`creo_install_seed_library` |
| 翼型与几何编辑 | `creo_create_airfoil_section`、`creo_new_airfoil_blade`、`creo_set_airfoil_parameters`、`creo_update_sketch_geometry`；原生草图和 Blend，弦长/厚度/扭转/原点参数 |
| 定位及特征组织 | `creo_transform_geometry`、`creo_set_geometry_transform`、`creo_group_features`、`creo_reorder_features`、`creo_axis_pattern`、`creo_feature_state`；完整实体/quilt 原生定位、原生局部组和轴阵列；`creo_feature_state` 按 `delete`/`suppress`/`resume` 操作已有零件或钣金模型的特征（目标用特征标签或特征 ID，带依赖闭包准入、墓碑与抑制登记，失败真实回滚） |
| 直接混合及追加 | `creo_loft`：独立 XY 草图按 Z 递增，直线/平滑原生实体混合；支持受管零件的默认实体增材 |
| 参数化修改 | `creo_set_dimensions`、`creo_set_sketch_dimensions`、`creo_set_parameters`、`creo_set_relations`：编辑特征尺寸/草图尺寸、零件参数、简单算术关系式，重新生成依赖特征 |
| 特征树与拓扑查询 | `creo_inspect_model`、`creo_refresh_model`、`creo_list_models`：特征 ID、名称、类型、状态、尺寸、草图尺寸、几何引用 ID、面/边/实体、体积、包围盒、参数和版本 |
| 高级原生特征接口 | `creo_create_feature_tree`、`creo_lookup_constants`、`creo_dump_feature_tree`：按照本机 SDK 的 Element Tree 结构创建特征，查询常量、导出特征 XML |
| 保存与导出 | `creo_regenerate`、`creo_save_model`、`creo_export_model`：保存原生 PRT/ASM，导出 STEP、IGES、STL、JPEG；已登记装配可显式选择 `native_bundle`，结果含 manifest 与 `complete`，新目录可打开性待实机 |
| 环境与任务 | `creo_check_environment`、`creo_session_status`、`creo_capabilities`、`creo_get_job`、`creo_list_jobs`：环境、实际 Toolkit 连接、能力和任务进度 |
| 磁盘模型打开 | `creo_open_file`：只读检索并显示磁盘既有 `.prt`/`.asm`（显式 `.N` 版本或目录内最高数字版本）；同名同类型会话模型与非空会话装配拒绝，冲突提示含装配依赖加载来源；缺件装配报残留对象、缺件清单标记未知；不保存、不擦除、不接管，成功返回 `model_id=null`，并附有界 `loaded_session_models` 摘要（区分会话模型数与组件实例数） |
| 注册表维护 | `creo_registry_health`：只读报告每个模型登记的字节数、16 MiB 读取预算占比、详情（别名/检查资料）形态与状态（正常/接近预算/超限/损坏/旧内联格式），单条异常不终止整份报告，不连接 Toolkit。`creo_migrate_registry`：`inspect` 列出仍内联详情的条目（含超限项）及其作业证据链；`apply(idempotency_key)` 先备份原始字节为 `*.pre-split-bak`，把详情写入内容寻址 sidecar 后原子发布控制记录，并把每个动作追加到 `models/registry-migration.jsonl`。重复执行幂等、中断可续作；不提高预算、不删除文件，原始原生结果保持原样 ；apply 持有共用非阻塞通道锁并核验 owner，targets 仅接受合法 model_id。health、迁移 inspect/apply/幂等回放均受完整 32 KiB 响应预算约束，使用 limit/cursor 逐页读取；登记变化后 inspect/health 游标需重采 |
| 会话模型擦除 | `creo_erase_session_models`：显式擦除选定的会话模型清单。`inspect(targets)` 返回每项目标身份、阻断原因、装配先于组件的擦除顺序、预期剩余对象和 600 秒令牌；`apply(evidence_token, idempotency_key)` 只执行令牌中的清单并返回 `job_id`。仅限有盘、未修改、非受管、无清单外引用与依赖环的对象；逐项复核后经两次独立查询确认消失；中途失败停止并明确报告已完成/未确认清单。不保存模型、不删除磁盘文件 |
| 世代回收 | `creo_reclaim_generations`：显式回收本项目自有的 loader/payload 世代目录。`inspect` 只列 `creo_callback_status.generation_inventory` 中可证明未被引用的世代并签发 600 秒证据令牌，`apply` 只删除令牌清单内目标且幂等键回放不重复删除；当前、已注册、运行中、回退保留与记录缺失/损坏/冲突的世代一律保留，不连接 Toolkit、不加载 DLL、不在启动或升级时自动清理 |
| 快捷底板 | `creo_create_plate`：兼容此前矩形底板、角圆角、独立通孔接口 |

特征保存为 Creo 可编辑的草图、拉伸、旋转、孔、圆角等，保留尺寸及依赖。多段线和矩形会展开为原生直线，不能将 `polyline` 名字当作单个尺寸引用；例如 `box_0` 是矩形第一条边。

0.8.0 接口增量：圆弧 `dir` 只接受严格整数，零扫角和整圆输入拒绝；弧结果回显原生几何而非按输入推算。钣金首壁不再静默改写不一致参数，而是在建模前拒绝；`relief` 省略时为 `none`。0.8.4 修复首壁准入将草图坐标系误计为几何的阻断，本机 T03 五组已通过。0.8.5 折边默认方向改为从选中面向外，并明确拒绝钣金体并入式实体 add，升级须检查 `flip` 和拒绝码。装配组件可使用业务标签定位，回转特征返回实际原生轴查询结果；未知几何明确保持未知。多操作请求、`feature_state`、独立 `draft` 及失败后 `rolled_back` 的前置重建边界以各工具实际返回为准。其余原生行为按各项实机证据与未测范围判断。

**开发分支（0.8.5 之后，未发布）接口增量：**`creo_sheetmetal_flange` 新增可选 `end_trim_mm`（正数、两侧链端缩短，语义待实机确认，属诊断参数）；`revolve_axis` 的 `section_centerline_count` 改为只计用户中心线（此前一条用户线被计成 3）；`creo_list_components` 的组件身份投影补保存重载与删除重插回归锁定。这些都**尚未取得实机验收**，不构成已验证能力；逐项状态见 [DEV-051 工作卡](docs/work-items/DEV-051.md#2026-10-30-离线批次十个提交与当前状态矩阵)。

提供接口不等于所有参数组合都已验证。[直线混合摘要](docs/validation_loft_seed.json) 与 [平滑混合摘要](docs/validation_loft_smooth.json) 保留两截面的历史测试；[其他开发功能摘要](docs/validation_development.json) 和 `build/capability_evidence.json` 是此前测试的历史证据，本轮未重跑其完整套件。已测试非矩形支架、带内孔和沟槽的轴类件、多实体圆弧/椭圆实体、样条拉伸曲面、薄壁对称拉伸、抽壳、边圆角和倒角、尺寸阵列及参数关系驱动。高级树接口需要符合 SDK 的具体特征定义，不能自动补齐任意缺失的草图或集合。

## 接入与调用

把以下本地 stdio 服务配置加入支持 MCP 的客户端：

```json
{
  "command": "C:\\MCP_CREO_MechDog\\.venv\\Scripts\\python.exe",
  "args": ["C:\\MCP_CREO_MechDog\\server.py"]
}
```

上述路径仅为示例，以安装生成的实际路径为准。服务名称及客户端注册键为 `MCP_CREO_MechDog`。`client-config.json` 是同一配置的 `mcpServers` 格式；不同客户端的配置格式可能需要转换，必须保留相同的 command/args。服务启动后客户端可发现工具的完整 JSON Schema。服务从自然语言规划器接收结构化建模操作；自然语言理解由调用它的 AI 客户端完成。

典型流程：

1. 调用 `creo_check_environment`、`creo_session_status` 检查本机环境并实际连接。
2. 使用 `creo_execute_plan` 一次创建完整零件，或用 `creo_new_part` 后分步调用草图及特征工具。
3. 建模工具立即返回 `job_id`；轮询 `creo_get_job(job_id, detail="compact")`，等待 `status == "succeeded"`，并检查 `result.saved_file_reloaded_and_verified == true`。需要完整几何和尺寸时使用 `detail="full"`；该值仍是单任务查询的默认值。`creo_list_jobs` 默认返回精简结果。
4. 保留 `model_id` 和最新 `revision`。修改已有零件时提供 `expected_revision`；版本不一致会拒绝旧请求。
5. 查询实际面/边/尺寸 ID 后追加特征。引用发生变化时重新查询，不复用猜测的拓扑 ID。

Toolkit 操作共用一个通道，提交时忙碌会立即拒绝；响应保持 MCP `isError=true`，JSON 文本与 `structuredContent` 同时给出 `status="busy"`、`accepted=false`、`blocking_job_id`、`blocking_model_id`、`blocking_operation`、`retry_after_seconds` 和 `retry_guidance`。未创建新任务。占用者可能是任务、提交登记、连接探针或构建；无法确定时 ID 为 null，不能猜测最近的任务就是占用者。1 秒是建议重查间隔，不是完成时间承诺。已接受的任务只轮询，不重新提交；未知结果先检查模型。

任务模型登记（revision、pending_job、保存结果）在锁内收尾，释放通道后才发布持久化终态。观察到旧任务 succeeded 后，其他客户端仍可能取得通道，此时按新响应的占用者处理。`creo_get_job`、`creo_list_jobs`、`creo_inspect_model`、`creo_list_models` 读取持久化快照，不等待 Toolkit；`creo_refresh_model`、导出和实际连接检查仍需要通道。已接受后台 runner 最多等锁 120 秒；没有公开 FIFO、容量或排队顺序保证，本次没有增加队列能力。开发与 WorkBuddy 验收范围见 [BUG-009](docs/work-items/BUG-009.md)。

例如创建有原生特征树的圆柱：

```json
{
  "operations": [
    {"op":"sketch","label":"profile","plane":"XY",
     "entities":[{"type":"circle","name":"circle","center":[0,0],"radius":10}],
     "dimensions":[{"name":"diameter","type":"diameter","refs":[{"entity":"circle"}],"value":20,"position":[15,0]}]},
    {"op":"extrude","label":"solid","sketch":"profile","depth":30}
  ],
  "assertions":{"require_solid":true,"volume_mm3":9424.77796076938}
}
```

随后 `creo_set_sketch_dimensions` 使用 `sketch:"profile", values:{"diameter":24}` 修改直径；拉伸实体随之更新。`creo_set_dimensions` 接收查询结果中的模型尺寸 ID，例如 `values:[{"id":18,"value":40}]`；实际 ID 由 Creo 生成。

完整案例在 `examples/`；0.21 新增镜像、扫掠、拔模和钣金首壁计划；装配重建管线与单作业多组件示例见 `examples/assembly_rebuild_pipeline.json` 与 `examples/assembly_multicomponent_plan.json`（说明见 [docs/ASSEMBLY_REBUILD.md](docs/ASSEMBLY_REBUILD.md)）。装配调用步骤见 [docs/MODELING_0.21.md](docs/MODELING_0.21.md)。尺寸阵列先建立引导孔，再查询其定位尺寸 ID，调用 `creo_dimension_pattern`，指定包含引导成员的总数量和每次增量。

### 能力发现示例

以下四个最小请求覆盖最常被问到的入口。全部经当前 schema 的 `validate_operations` 校验通过（2026-10-30 离线核对），**示例本身不是新的实机证据**；各能力的已验范围以台账与各验收卡为准。

**一次 `creo_execute_plan` 提交多个操作**（草图 → 拉伸 → 孔，同一作业一次 revision、一次保存重载）：

```json
{
  "operations": [
    {"op":"sketch","label":"profile","plane":"XY",
     "entities":[{"type":"rectangle","name":"r","min":[0,0],"max":[60,40]}]},
    {"op":"extrude","label":"solid","sketch":"profile","depth":12},
    {"op":"hole","label":"main_bore",
     "placement":{"kind":"plane","axis":"z","offset":12},
     "reference1":{"kind":"datum_plane","axis":"x","offset":30},
     "reference2":{"kind":"datum_plane","axis":"y","offset":20},
     "diameter":10,"depth":12}
  ],
  "assertions":{"require_solid":true}
}
```

**`creo_feature_state` 删除／抑制／恢复特征**（目标是特征标签或特征 ID；同一批目标必须互不相同）：

```json
{"operations":[{"op":"feature_state","action":"suppress","targets":["main_bore"]}]}
```

```json
{"operations":[{"op":"feature_state","action":"resume","targets":["main_bore"]}]}
```

```json
{"operations":[{"op":"feature_state","action":"delete","targets":[18]}]}
```

**独立拔模 `creo_draft`**（恒角、不分割；`surfaces` 是裸面引用数组，`neutral_plane` 与 `pull_direction` 是裸单引用）：

```json
{
  "operations": [
    {"op":"sketch","label":"base","plane":"XY",
     "entities":[{"type":"rectangle","name":"r","min":[0,0],"max":[20,20]}]},
    {"op":"extrude","label":"solid","sketch":"base","depth":20},
    {"op":"draft","label":"taper",
     "surfaces":[{"kind":"plane","axis":"x","offset":20}],
     "neutral_plane":{"kind":"datum_plane","axis":"z"},
     "angle":3}
  ]
}
```

**组件标签查询**（标签是业务名，身份是模型身份 + feature_id；删除重插后旧标签不误指新组件）：

```json
{"model_id": "<装配 model_id>", "tool": "creo_list_components"}
```

返回的每条组件记录带 `identity`、`labels`、`label`、`label_state`（`single`/`multi`/`unlabeled`）、`source_model_id`、`source_revision`、`bindings`；顶层另返回 `deleted_identities`（旧 feature_id 不再出现在当前组件集时单独列出）与 `identity_key`。放置与约束按 label 引用组件，例如 `{"op":"component_placement","component":"part_alpha","translation":[0,0,25]}`。

**钣金折边两端缩短（开发分支，未发布；语义待实机确认）**：

```json
{
  "model_id": "<钣金 model_id>",
  "expected_revision": 1,
  "label": "trimmed_wall",
  "edge": {"kind":"edge","id": 12},
  "height": 20,
  "angle": 90,
  "radius": 1,
  "flip": false,
  "y_factor": 0.5,
  "end_trim_mm": 20
}
```

`end_trim_mm` 是模型单位的正数，缺省时元素树与旧行为完全一致。**Creo 究竟把它读作「距链端各内缩 setback」还是「自截面起算的壁长」尚未实机确认**，因此它是诊断参数：先在一道两端均为自由角的自由壁上探测并用实测体积分类，再决定是否用于修剪对照；不要仅凭回显就认为修剪已生效。

## 坐标、引用与参数

长度使用毫米，角度使用度。草图输入是平面内的 `(u,v)`：

| 平面 | u | v | 正向法线 | offset |
| --- | --- | --- | --- | --- |
| XY | +X | +Y | +Z | 世界 Z 坐标 |
| XZ | +X | +Z | −Y | 世界 Y 坐标 |
| YZ | +Y | +Z | +X | 世界 X 坐标 |

`direction:"positive"` 沿表中正向法线，`negative` 反向。对称拉伸的 `depth` 是总深度。圆弧起止角以输入平面 u 轴为零度，沿 u→v 逆时针。

平面也可传入 `{"reference":{"kind":"surface","id":实际ID},"origin":[x,y,z],"u_axis":[x,y,z]}`，用于已有平面面或基准面。默认原点是世界原点到该平面的垂足；指定原点必须在平面内。基准面的方向和生成几何由 Toolkit 决定，应按查询结果使用。

`creo_datum_axis` 的操作详情包含 `datum_axes` 与 `axes_query_code`；`creo_inspect_model(detail="full", section="datum_axes")` 分页返回已保存快照中的原生轴几何。`origin` 是原生轴线上的一个点（不保证是离原点最近点），`direction` 是原生两端点差的单位向量。坐标使用实际模型长度单位；同层 `length_unit` 提供单位名、到毫米的比例及原始查询码。查询失败/未执行或几何退化时使用 null/`geometry_known:false`，不得把输入引用猜成几何。巡检 `center_of_gravity` 同样使用原生长度单位，查询结果由 `volume_query_code` 记录；尚无实体或质量查询失败时为 null。上述接口已随 0.7.0 交付。倾斜面与主平面的正/反/对称盲深拉伸（800 mm³、完整 AABB 与重心）及贯穿去料（48/48/96），以及偏心 `(4,-3)` 两平面交线轴、基体柱面轴的正余弦阵列，已在本机 Creo 12.4 实机通过 18/18 并逐个保存重载（[T05 Live03](docs/development/DEV047-T05-ACCEPTANCE-2026-10-26.md)）。仍未覆盖：外部 Creo 9/10、非毫米与单位未知场景，以及无基准轴模型上的倾斜面草图（日志 `SKETCH_REFERENCE_INCOMPLETE`）。

常用引用：

```json
{"kind":"datum_plane","axis":"x","offset":0}
{"kind":"plane","axis":"z","offset":30}
{"kind":"surface","id":123}
{"kind":"edge","id":456}
{"kind":"axis","id":78}
{"kind":"datum_feature","label":"offset_plane"}
{"kind":"datum_axis_feature","label":"axis"}
```

`plane` 选择实际实体平面面，必须唯一；有多个匹配面时使用查询得到的 `surface` ID。`datum_plane` 的零偏移主平面选择模板中最早的对应基准，避免与 Creo 自动生成的内部基准混淆。非零偏移仍要求唯一。草图/拉伸等特征间用 `label` 引用；标签须匹配 `^[a-z][a-z0-9_]{0,27}$`，即以小写字母开头，其余仅用小写字母、数字或下划线，总长最多 28 字符，例如 `i001_part1`。服务不会自动改名。

显式尺寸支持长度、半径、直径、点间距离/水平距离/垂直距离、线间距离、夹角、圆弧角度和椭圆半轴。约束接口包含水平、垂直、重合、点在线上、相切、垂直、等半径、平行、等长、共线；实测包括水平/垂直约束及驱动直径尺寸，其余组合由原生求解器验证。

关系式当前接受简单算术赋值，例如 `d18 = LENGTH / 2`；替换零件当前关系式集合。参数支持数字、布尔值和字符串。

## 验证、恢复与当前边界

每次修改成功后，执行器检查单位、所有原生特征的活动/完整状态及实体状态；保存 `.prt.N` 或 `.asm.N`，擦除该 MCP 零件的内存模型，从实际保存文件重载、重新生成，再对比特征 ID/类型/名称、尺寸值、实体数量、体积和参数。可额外提供 `require_solid`、`volume_mm3`、`volume_tolerance` 断言。体积计算临时使用密度 1，不修改材料。

**默认摘要与分页接口一览。** 以下三个查询接口默认返回 compact 摘要（小体积、可直接整读），需要全量内容时显式请求并按页遍历；依赖旧全量返回的调用方会静默拿到摘要，不会报错：

| 接口 | 默认 | 取全量 |
| --- | --- | --- |
| `creo_list_models` | compact 模型清单摘要 | `detail="full"`，必要时沿 `next_cursor` 分页 |
| `creo_inspect_model` | compact 快照摘要（身份/revision/体积/计数） | `detail="full"` + `section="dimensions"`/`"surfaces"`/`"edges"`/`"features"` 等，沿 `next_cursor` 分页 |
| `creo_capabilities` | compact 能力摘要页 | `detail="full"` + `section="tools"`/`"families"`/`"references"` 等，沿 `next_cursor` 分页 |

通用规则：单页响应预算 32 KiB，超预算会分页或对单条超限项显式标记；出现 `next_cursor` 时保持相同 `detail`/`section` 继续翻页，翻完即 `complete=true`。`creo_inspect_model` 的分页绑定已保存快照，模型改变后游标失效，应重新查询；`creo_capabilities` 的分页绑定进程内约 600 秒冻结快照，过期 cursor 被拒绝并提示重新首查。

`creo_list_session_models` 的 cursor 语义另有两态：不带 `cursor` 调用时实时重新采集会话清单；携带上次返回的 `cursor` 时读取约 10 分钟的冻结快照分页，不反映快照创建后的会话变化。因此"打开/擦除模型后要确认会话现状"时应省略 `cursor` 重新查询；需要稳定遍历时沿用 `cursor`。结果中的 `snapshot_age_seconds`/`expires_in_seconds`/`refresh_guidance` 说明快照年龄与刷新方式；`service_session_changes` 列出本服务自快照以来记录的会话内容变化（跨进程、有界），GUI 手工变化不在其中、未实时复核。`creo_open_file` 成功结果的 `open_file.opened_session_model` 直接提供刚打开模型的单条会话观察（字段与会话枚举条目一致，另含 `observed_at`）；`open_file.loaded_session_models` 提供打开后的有界会话摘要（会话模型数、组件实例数与详情入口），不必立即发起全量枚举。

`creo_list_models` 与 `creo_inspect_model` 默认返回 compact 摘要，保留身份、revision、状态、体积、真实计数和快照时间。需要几何时显式使用 `detail="full"`，可指定 `section="dimensions"`、`"surfaces"`、`"edges"`、`"features"` 等。详情默认每页50条、最多200条，响应预算32 KiB；出现 `next_cursor` 时保持 detail/section 继续分页，模型改变后重新查询。大快照的 `data` 按 section 返回；特征内的尺寸、几何项和草图尺寸分别分页，未知计数为 null，不能当作0。小快照的 full 保留原 inspection/aliases 布局。Python调用方可用 `creo_mechdog.query_client.read_full_model` 收集全部页并重建快照。

`creo_inspect_model` 返回最近已验证的保存快照，snapshot明确不代表实时状态；人工在 Creo 修改后，用 `creo_refresh_model` 获取实况。实时查询不会替换已保存模型的基线，也不会保存或接受人工修改。已有模型修改前会检测模型与记录是否一致；因任务失败或人工修改而不一致时，不应盲目重复提交。失败作业的 inspection 仅在恢复并验证成功时代表恢复模型；失败中间状态另列 failure_inspection，无法取得真实状态时为 null。

恢复失败按实际阶段返回原因：执行器派发前的证据校验拒绝返回 `failed` / `before_native`，在锁内仅释放本次恢复占位；原生执行器可能已开始时仍为 `unknown_outcome` 并保留保护。原生会话指纹拒绝发生在连接之后，不能因消息含 refused 就自动重试。见[恢复契约](docs/MODEL_RECOVERY.md)。[隔离 MCP 契约验收](docs/validation/DEV-040-isolated-contract-2026-10-18.md)已通过，不代表真实 Creo 会话切换、中断、几何或并发恢复已全部验收；剩余范围按台账跟进。

`creo_loft.sections` 和计划中 `op="loft"` 支持草图标签、整数feature_id，以及为客户端兼容接受的纯十进制数字字符串；例如 `[40,"49"]` 归一化为整数ID。归一化后的重复引用被拒绝，不影响其他参数的字符串语义。原生几何与公开客户端验收范围仍分别记录。

现有 MCP 零件任务失败，会尝试从任务开始前的保存文件恢复；只有 `rollback_succeeded` 确认成功才能继续。版本号不随失败增加。辅助进程崩溃、超时或结果不能确认时标记 `unknown_outcome`，保留现场供检查。新零件失败可能留下本任务的部分模型。

未知作业保留 `pending_job`，`creo_get_job` 的 `recovery` 提供执行器身份、断开前检查点及已保存基线；检查点不等于成功，也不自动提交 revision。原生断开有 20 秒 helper 看门狗，只退出自有 helper，不关闭 Creo。`creo_startup_status(retry=true)` 只重新核实通道及安全启动条件，不能解锁或重放未知作业。启动等待区分 `waiting_for_channel` 与 `building_worker`，preparation 为 180 秒，总预算为 180 秒加配置的启动预算；到期仍在执行时说明 in-flight，继续保留保护。状态快照带 `verified_at`、`verification_age_seconds`、`stale`；`creo_session_status` 的独立探针预算为 9 秒，超时返回 `probe_timeout` 和处理指引。

共享启动历史损坏时，仅在核实记录早于本次 Windows 启动、双锁已取得且没有现有 Creo 后，备份原字节并重建启动状态，再由协调器启动 Creo；`startup_recovery` 提供归档与重启依据。同次开机损坏、时钟／会话不确定或备份失败仍返回 `startup_state_unreadable` 和处理说明，已有会话可只读重连。未知任务和模型保护不随启动历史重建而清除，验证范围见[重启恢复记录](docs/validation/BUG-008-reboot-recovery.md)。

目前高层工具覆盖上述常见实体特征，仍有明确范围：

- 持续修改支持本服务创建、登记的零件、钣金模型和装配；用户已在 Creo 打开的未登记模型可通过 `creo_adopt_current_model` 显式接管为受管副本（原件与原会话对象不动，首批独立 part/钣金、mm 单位、无外部依赖；身份按 origin 路径 + 文件哈希 + live 快照证明，不信任显示名）。
- Development branch: `creo_adopt_file` accepts 1-20 ordered source paths with inspect/apply, independent per-item commits and no display/window activation. Existing unmodified exact-origin residents are copied as explicitly inspected session state; their pre-inspection disk/content equality is unknown. Duplicate sources are refused with reuse guidance; unknown outcomes stop remaining items and retain protection. See the [path-adoption contract and its live evidence range](docs/FILE_ADOPTION.md).
- 各类尺寸/约束的复杂组合、极端几何及外部人工修改的自动接管仍需后续扩展。
- 孔支持直孔及可选原生沉孔／沉头；螺纹与标准孔系列未封装。倒角为等距，阵列支持一方向尺寸阵列和原生轴阵列。
- 普通混合支持平行 XY 截面的种子复用及直接创建/追加。随包九个种子覆盖 2/3/4/6 截面的直线和平滑，以及 5 截面平滑；其他数量需显式兼容种子或直接创建并本机验证。直接混合仅支持受管草图、Z 严格递增和默认实体增材。不支持自动增减种子截面、转换连接模式、非平行截面或端点相切/曲率控制。数量上限不代表每种数量都已实测。新零件整体可用原生定位特征移动或旋转。
- 钣金首壁 T03 五组已在本机验证；0.8.5 在真正的 1 mm 板上，两道折边为真实 90° 折弯（各 +18 025.29 mm³、Z 增长 79 mm、保存重载通过，`flip=false` 默认从选中面向外），但**四壁仍只完成 2/4**：第三道 `f_ny` 创建后回滚、第四道未执行，`relief` 目前只确认「请求被接受并回显」，尚无可观测几何去料。板厚同步、释放有效场景与第三壁对照已在开发分支离线交付但**未实机验收**。其他钣金能力及历史验证范围见版本说明和能力文档。镜像、扫掠、拔模、装配、筋和工程图各自具有明确范围；复杂自由曲面及专业模块仍未完整封装。
- 装配插入源模型的版本快照，源模型后续修改不更新组件；子装配复制尚未开放。
- `creo_create_feature_tree` 可扩展符合本机 SDK 的特征结构，但无法保证所有 PTC 特征类型和选项均可创建。
- 不承诺任意文字描述都自动成功。AI 需要规划有效的轮廓、基准、尺寸和特征顺序；无效几何由 Creo 返回错误。

服务串行执行 Toolkit 操作，后台检测并复用已有会话，无会话时按配置启动；连接确认前拒绝建模提交，不自动关闭 Creo。输出保存在项目运行数据目录内：`models/`（受管模型登记与输出）、`jobs/`（作业请求/结果/日志）、`open_file/`（磁盘打开的幂等意图登记）、`session_erase/`（会话擦除的令牌与意图登记）和 `session_activity.json`（本服务引起的会话内容变化记录）；升级到新版本时保留这些目录，不要手工删除或合并它们。不提供任意命令／代码执行工具，不输出许可服务器内容或修改安装目录。正在交互建模或有模态对话框时，应先处理该会话状态。

## 开发与测试

安装脚本创建虚拟环境、安装锁定依赖、验证/注册随包种子库、读取本机 SDK 生成常量表、编译执行器并生成客户端配置。首次运行或原生源码改变时也会自动重新编译。`native/constants.inc` 由本机 SDK 生成；不随源码分发。源码包含九个项目原创 MIT 种子 PRT，不含 Creo SDK 库、许可内容、虚拟环境、编译二进制或其他本机测试模型。第三方 JSON 头文件附带其原始 MIT 许可。

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe tools\test_mcp.py --classic
.\.venv\Scripts\python.exe tools\test_general.py
.\.venv\Scripts\python.exe tools\test_extended.py
.\.venv\Scripts\python.exe tools\test_guards.py
.\.venv\Scripts\python.exe tools\test_v021.py
.\.venv\Scripts\python.exe tools\test_unit.py
```

除输入验证外，上述集成测试会实际连接 Creo 并创建或修改独立测试模型。`test_v021.py` 默认验证启用功能和禁用接口的拒绝行为；禁用接口的拒绝测试不是建模成功证明。日志位于任务 `native.log`/`runner.log`/`job.json` 和 `build/build.log`；证据在 `build/*integration_test.json`。保存目录较长时应缩短项目路径。

Windows 登记文件读取允许共享删除，写入使用单步原子替换；短暂占用最多重试 1 秒，持续失败保留旧登记并报错，不会自动重复原生操作。登记读写压力与并发实机轮询可分别运行 `tools/test_registry_io.py` 和 `tools/test_registry_native.py --readers 3`。Creo 12.4 结果及历史交接记录见 [BUG-002 验证与交接](docs/validation/BUG-002.md)。

实现依据：[PTC 草图特征 Element Tree 文档](https://support.ptc.com/help/creo_toolkit/protoolkit_plus/usascii/creo_toolkit/user_guide/Element_Tree_for_Sketched_Features.html)、本机 Creo 10 Toolkit 头文件与示例、[官方 MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)。实际本机建模成功、保存重载成功的记录才证明该路径可用，SDK/许可环境文件存在本身不能证明许可可用。

完成普通放样实机测试后，可生成它的独立摘要；打包会重新生成本地同版本压缩包：

```powershell
.\.venv\Scripts\python.exe tools\summarize_loft_seed.py
.\.venv\Scripts\python.exe tools\summarize_loft_seed.py --interpolation smooth
.\.venv\Scripts\python.exe tools\package.py
```

摘要命令需要已经完成相应的实机测试；打包命令只选择公开源码及文档。`config.json`、`client-config.json`、虚拟环境、构建结果、任务和模型目录已在 `.gitignore` 中排除。

毫米、英寸与混合装配的单位对照场景由固定矩阵驱动覆盖：`tools/test_assembly_matrix.py`（毫米／英寸组件的 normalized 与 raw 矩阵、已知点对照）和 `tools/test_assembly_units.py`（毫米／英寸／混合与单位查询失败的 null 表达）。这组矩阵是后续新增数值接口（坐标、变换、体积等）的验收模板：新接口必须在毫米、英寸、混合与未知单位四种场景下分别取得证据，未知或查询失败如实为 `null`，不得默认毫米。批处理与拔模官方示例见 `examples/dev047_t12_batch_append.json`（一次计划多特征、单次 revision 与整体回滚）和 `examples/dev047_t12_draft_boss.json`（Ø6×3 凸台 11° 内拔模，`r_top = 3 − 3·tan(11°)` 圆台体积断言）。