ansa-mcp-sum

在可见的 ANSA GUI 上，用 MCP 驱动 78 个具名工具、5 个资源（当前 v1.0.7）。

把 ansa-mcp 的文件 IPC 传输层（GUI 模式、模型操作实时可见）与 ansa-tcp-bridge 的 49 个工具合并成一个 MCP server。合并后共 78 个工具：65 个向 ANSA 派发命令 （收敛到 64 种命令类型），13 个是服务端辅助函数——含 3 个不依赖桥的记忆工具、 4 个内嵌 ANSA API 文档工具（v1.0.4 起，见 §5.6）。 外加一层执行前预检：validate_script 与 execute_script(validate=True) 会在脚本真正跑起来 之前，就拦下"引用了本机不存在的 ANSA 函数"的调用。

Combined ANSA MCP bridge = ansa-mcp's GUI file-IPC transport + the 49 tools from ansa-tcp-bridge, exposed as 78 named MCP tools (65 dispatched + 13 server-side).

• 面向部署的操作手册 → USAGE.md（逐步安装、配置、排错表）

• 本文档偏重架构、测试与实测沉淀——即"这个项目到底验证过什么、哪些坑是真的踩过"。

1. 它解决什么问题

一句话：用 ansa-mcp 的传输层，把 tcp-bridge 的工具全部跑在 GUI 模式下。 每一步操作（建网格、抽中面、跑检查）都能在 ANSA 窗口里直接看到。

Related MCP server: ANSYS Workbench MCP

2. 架构：MCP 层是外壳，文件 IPC 才是真正的执行路径

MCP 客户端 (LLM / mcp_cli.py)
   │  stdio JSON-RPC
   ▼
ansa-mcp-sum-server  (src/ansa_mcp_sum/server.py, FastMCP)
   │  send_command(type, **kwargs)          ← 全部 65 个派发工具的唯一出口
   │  ├─ plugin_ready_error()  读 status.json 判心跳，不新鲜就拒发
   │  ├─ atomic_write_json(commands/cmd_<id>.json)
   │  └─ wait_for_result(results/<id>.json)
   ▼
ANSA_MCP_SUM_HOME/commands/          ← 磁盘文件即队列
   │  ANSA GUI 主线程 guitk.BCTimerCreate 每 200 ms 轮询
   ▼
ANSA GUI 内 plugin.py  HANDLERS[<type>]  →  tools_impl.<fn>(command)
   │  调用 base.* / mesh.* / connections.*
   ▼
ANSA_MCP_SUM_HOME/results/<command_id>.json   →  server 读回并返回

关键认识：server.py 从不直接接触 ANSA。 它只做三件事——判心跳、写命令文件、轮询结果文件。 真正的执行发生在 ANSA 主线程里。

由此推出一个非常实用的结论：MCP 层断了 ≠ 桥坏了。

排障时这就是个二分法：MCP 不通时先 mcp_cli.py ping——通则问题在 MCP 层（客户端握手 / server 进程 / 配置）；不通则问题在桥或 ANSA 侧（看 status.json 时间戳是否推进、 commands/ 是否积压）。

代价也要清楚：文件通道少掉 schema 校验、路径白名单、心跳门控三层保护， 第三条尤其危险——ANSA 没开也会返回 queued，容易误判成"已执行"。 所以它只用于排障与盲投，日常仍走 MCP。

3. 目录结构

src/ansa_mcp_sum/            共 7,550 行（另有 10.4 MB 内嵌 API 索引）
  __init__.py     (40)    __version__ 单一声明（当前 1.0.7，带完整版本史注释）
  config.py       (106)   环境变量 → AnsaMcpConfig        · 双栖（ANSA 内外都 import）
  ipc.py          (171)   原子写命令文件 / 轮询结果文件      · 双栖
  ansa_api.py     (751)  ★ 事实层：ANSA 到底有什么 API（VERIFIED 86 / REJECTED 33 / OPTIONAL 3）
  tools_impl.py   (1324)  49 个 ANSA 侧实现（在 ANSA 解释器里跑）
  plugin.py       (1832)  ANSA 侧派发器：HANDLERS[64 种命令] + 状态/心跳 + 审计落盘
  audit.py        (302)  ★ 运行时审计：logs/audit.jsonl，一行一条命令，带大小轮转
  knowledge.py    (664)  ★ 踩坑登记表 + 实测流水线（ansa://pitfalls / ansa://workflows 的数据源）
  memory.py       (216)  ★ 跨会话记忆：memory/prefs.json + memory/notes.md
  api_doc.py      (306)  ★ 内嵌 ANSA API 文档检索（v1.0.4：search / lookup / list_modules / list_categories）
  server.py       (1853)  MCP server：78 个 @mcp.tool + 5 个 resource
  ansa_api_index.json (10.4 MB)  ★ 内嵌 API 索引：5892 个函数 / ANSA v25.1.4（v1.0.6 起随包分发）
scripts/
  ansa_mcp_sum_autoload.py  (446)  ★ ANSA GUI 自加载：4 个工具栏按钮 + 200ms 轮询定时器
  mcp_cli.py                (107)  绕过 MCP 层的文件通道 CLI
  check_mcp_sum_health.py   (262)  MCP 通道逐环自检（含"进程是否跑的是当前源码"）
  probe_mcp_sum_server.py   (249)  走线的会话探针：initialize + tools/list + resources/read
  probe_ansa_capabilities.py(687)  真机能力探测（需在 ANSA 内跑）→ capabilities.json
  regression_check.py      (1306)  离线回归：208 项断言，全绿
  audit_command_keys.py     (179)  离线审计：服务端参数 ↔ 插件消费 契约
  audit_ansa_api_usage.py   (210)  离线审计：源码调用 ↔ 事实层（扫描 8 文件）
  bridge_doctor.py          (227)  ★ 桥诊断+热重载：经 Run Once 跑，不改文件也能让新代码进内存（含 RELOAD_MARKER 单点声明）
  s2_diag / s3_geomcheck / s4_standards / s5_midsurf / s6_verify   端到端样例流水线
                        （被 knowledge.py 的 ansa://workflows 资源引用，是它的证据留档，故保留）

scripts/ 曾累积 64 个一次性探索脚本（s7–s56 的 Map Block / 碎面修复 / 桥崩溃排查线， 以及早期 probe_* / count_* / discovery 临时探针）。2026-09-13 已清理，只保留上表 14 个承载运行与门禁的文件（见 §10.27）。

每个模块扮演什么角色、在哪个进程里运行、依赖谁、加新工具要改哪几个文件 —— 见 MODULES.md。

4. 快速开始

完整步骤见 USAGE.md，这里只列最小路径。

# 1) 装进受管 venv（mcp 已锁 1.29.1）
C:\Users\Admin\.workbuddy\binaries\python\envs\default\Scripts\pip install -e D:\ansa-mcp-sum

// 2) mcp.json（WorkBuddy: C:\Users\Admin\.workbuddy\mcp.json；CodeBuddy 是另一个文件，配一边另一边不生效）
{
  "mcpServers": {
    "ansa-mcp-sum": {
      "command": "C:\\Users\\Admin\\.workbuddy\\binaries\\python\\envs\\default\\Scripts\\ansa-mcp-sum-server.exe",
      "args": [],
      "env": { "ANSA_MCP_SUM_HOME": "C:\\Users\\Admin\\.ansa-mcp-sum" }
    }
  }
}

# 3) ANSA_TRANSL.py（GUI 模式才加载；带 -b 时跳过）
import ansa
try:
    _gui = '-b' not in [str(a) for a in ansa.session.ProgramArguments()]
except Exception:
    _gui = True
if _gui:
    # 注意：scripts/ 不是 Python 包，不能 import；ImportCode 直接执行该文件
    ansa.ImportCode(r'D:\ansa-mcp-sum\scripts\ansa_mcp_sum_autoload.py')

# 4) 启动 ANSA GUI（看到 MCP-Sum 工具栏）→ 另开终端起 server
ansa-mcp-sum-server

加载成功的证据是 ANSA 控制台出现 [ansa-mcp-sum] bridge loaded. home=... buttons=[MCP-Sum] mode=AUTO。 日志里看不到 "Reading script from: ...autoload.py" 是正常的——ansa.ImportCode 直接执行、 不打印该 banner；同理 NOTICE: script [...] not found 是 ANSA 在探测它自己的 5 个 transl 候选路径。

工具栏按钮

环境变量

其它运行时常量：轮询 POLL_MS=200；模型宽限期 MODEL_GRACE_SECONDS=30（刚开 ANSA 尚无模型时命令延后）； 空闲心跳 HEARTBEAT_EVERY_TICKS=4500（= 15 分钟）；过期命令丢弃阈值 STALE_COMMAND_AGE_SECONDS = timeout + 60。

5. 工具、资源与运行时状态（78 个工具 / 5 个资源）

server.py 注册 78 个 @mcp.tool，其中 65 个会写命令文件派发到 ANSA（收敛到 64 种命令类型， 因为 import_file 与 restore_model 共用同一个类型），13 个是服务端-only：

注：check_ansa_connection 与 restore_model 现在会派发命令（分别复用 ping 与 import_file 命令类型），所以它们不算服务端-only —— 旧版文档把它们列进这一栏是过时的。

A. 会话与文件 I/O（10） ping_ansa · check_ansa_connection · open_model · new_model · save_model · save_model_as · export_nastran · export_lsdyna · export_step · run_python_script_in_ansa

B. 实体操作（18） count_entities · list_entities · get_entity · set_entity_fields · create_entity · delete_entities · search_entities_by_name · get_bounding_box · get_node_coordinates · change_element_type · create_part · create_set · add_to_set · get_model_summary · list_model_includes · calc_element_mass · calc_shell_area · calc_solid_volume

C. 检查与质量（9） check_intersections · check_penetrations · check_free_nodes · run_quality_check · count_failed_elements · check_geometry · check_sharp_edges · check_rigid_dependencies · calc_mesh_quality

D. 网格（5） mesh_shells · mesh_volume · set_shell_mesh_params · delete_mesh · run_batch_mesh

E. 连接（4） apply_connectors · check_connections · list_connectors · create_connection_point

F. 显示控制（5） show_only · show_also · hide · near · neighb

G. 脚本执行与预检（2） execute_script · validate_script（v1.0.4；见 §5.6）

H. 原 ansa-mcp 保留（12） get_capabilities · get_model_info · geometry_inventory · import_file · list_faces · face_properties · delete_faces · restore_model · save_model_as_ws · check_mesh_quality · surface_mesh · export_solver_deck

5.1 每个工具都带 MCP 注解

78 个工具全部声明了 readOnlyHint / destructiveHint / idempotentHint，客户端据此决定 要不要二次确认、能不能并发。分组规则：

39 + 5 + 12 + 5 + 17 = 78。v1.0.4 新增的 5 个工具（4 个 API 文档 + validate_script）全是 READ_ONLY。

两个刻意的例外，宁可保守不可误导：

• check_penetrations 标 DESTRUCTIVE 而非只读 —— 兄弟检查项（check_free_nodes 等）都是 纯读，但它带 auto_fix=True，真会改模型。

• apply_connectors / mesh_volume / run_batch_mesh 都是破坏性的，即使它们在实现上 "只是生成"：生成物覆盖了原本为空的位置，撤回代价和删除一样高。

mcp 装得极简、没有 ToolAnnotations 时，注解退化为 None（FastMCP 的默认值）， 78 个工具照常注册 —— 不会因为一个元数据字段拒绝启动。

5.2 两个同名但语义不同的工具

实现层两者都接受 path / filepath / output_path，但推荐按上表用。

5.3 资源：把仓库里的知识接到模型眼前

MCP 的 resource 是唯一能让客户端主动取知识的通道。本项目暴露 5 个：

ansa://pitfalls 是把 §7 的内容重新写成数据。动机很直白：§7 里的 10 条硬核教训 原先只存在于这份 Markdown 里，而 MCP 客户端不会去读一个仓库的 README —— 于是每换一个会话，模型都要重新踩一遍。BETA 官方的 AI-Assistant 用"全量文档 + Python API 的 RAG 索引"解决这件事；单机工具链的等价做法就是把同一份知识写成机器可读的资源。

登记表里每条都带 must_resolve：它断言"这些 API 确实存在"。回归门会拿这张表去比对 ansa_api.VERIFIED_API，把某个名字挪进 REJECTED_API 会让构建失败，而不是留下一句 已经过期的自信注释。

资源只在你主动取的时候才到达，所以最要命的几条还同时写进了对应工具的 description：

execute_script / run_python_script_in_ansa / get_entity / get_bounding_box /
get_node_coordinates / check_geometry / calc_mesh_quality / count_failed_elements /
count_entities / export_nastran / export_lsdyna / export_step      （共 12 个）

工具描述是客户端每次都会下发的东西，这一条路比 resource 可靠得多。

实现注记：这里最初写成 """doc""" + knowledge.pitfall_brief([...])，注解是错的 —— Python 只在首个语句是裸字符串字面量时才设 __doc__，表达式会被静默忽略， 于是这些工具的 description 变成了空字符串（比不加注解更糟）。现在改用 @_with_pitfalls(...) 装饰器（跑在 @mcp.tool 之前），并有一条回归断言专门守这个形态。

5.4 跨会话记忆

两类状态，分工明确（都在 <HOME>/memory/ 下）：

三个工具：remember(key, value, note) / recall(key="") / remember_note(text, tag)。 recall() 空参返回全量快照（偏好 + 笔记 + 历史摘要），传键返回值，键不存在时返回 NotFound 并列出已经存在的键 —— 而不是一个空成功。

当前 <HOME>/memory/prefs.json 里已经有 7 条本项目实测事实（deck=1、3.0 目标边长、 标准文件路径、98.9% 中面基线…），下一次会话 recall() 就能拿到。

5.5 运行时审计：logs/audit.jsonl

为什么需要它：scripts/audit_*.py 是离线代码审计（扫源码），跟"运行时谁动了我的模型" 毫无关系。§7.6 那条已知崩溃路径——ANSA 进程直接消失——当时任何地方都没有记录： results/ 是空的、status.json 时间戳停在起始时刻、系统事件日志什么都不写。事后连 "当时在跑什么"都答不上来。

现在一条命令一行 JSON：

{"ts":1757...,"event":"command","id":"a1b2c3d4e5f6","type":"mesh_shells",
 "args_hash":"sha1:9c1f...","deck":1,"model_before":"C:/.../Casting_initial.ansa",
 "model_after":"C:/.../Casting_initial_midmesh_3mm.ansa","model_changed":true,
 "duration_s":54.2,"ok":true,"error_type":null,"pid":12964}

三个设计决定：

• 只由插件写（ANSA 进程内）。另外两件只有 ANSA 侧知道的事：真实耗时（客户端只知道 自己等了多久，一次超时就让这个数失去意义），以及模型路径的前后变化。 服务端不重复写同一个文件 —— 两个写者共用一个文件，一条被撕成两半的 JSONL 比缺一条更糟。 客户端侧的事实（超时、校验拒绝）本来就有家：runs/<stamp>-<id>/。

• 大 payload 只存指纹。一次 execute_script 最大 64 KB，原样写进去会把审计日志变成 脚本的第二份副本。改为 args_hash（sha1 前 12 位）+ payload_chars，既保持"同一调用" 可判定，又不落原文。

• 写失败要能看见。审计是观察者，绝不能让它把一条成功的命令变成失败；但也绝不能不吭声 —— 写失败会累加到 status.json 的 audit_write_errors。一份安静地什么都不写的日志， 比没有日志更危险，因为它是被信任的。

另有两条被记录的非命令事件：dropped_stale（队列里被当过期丢掉的命令，含超龄多少秒） 和 started / stopped（生命周期标记，让日志里的空档有意义 —— 在它之后的命令属于另一个 ANSA 会话）。日志按 4 MB 轮转，保留 2 份（audit.1.jsonl / audit.2.jsonl），无外部 cron。 读取时容忍被撕开的最后一行：跳过而不是抛异常。

read_last_log 现在会在 logs.audit 里同时返回历史摘要（命令数、失败数、最慢耗时、 按类型的计数），所以"那条命令到底跑没跑"是个能回答的问题。

5.6 内嵌 ANSA API 文档 + 执行前预检（v1.0.4 起）

写 ANSA 脚本时最贵的一类错，是调用了一个本机根本不存在的函数：GetEntityCardValues 对未知 字段静默返回空字典、CollectEntities 用错类型只返回 0、getattr(mod, "Fn", None) 兜底则把错误 推迟到操作跑到一半时的 TypeError。以前只能靠人在真机上一个个试。

v1.0.4 把另外那个 ansa-api MCP 的检索能力整个搬了进来，并加了一层执行前预检：

索引来源：ansa_api_index.json（10.4 MB，5892 个函数，ANSA v25.1.4）随包分发 （package-data），所以项目自包含、可直接分享，不需要另外装 ansa_tools。解析顺序是 ANSA_API_INDEX_PATH 环境变量 → 包内副本 → ansa_tools 资源（仅作向后兼容兜底）。 api_doc.py 是纯逻辑模块：没有 FastMCP 对象、import 无副作用，只暴露 search / lookup / list_modules / list_categories 返回 markdown。

预检默认开启：execute_script 的签名是 execute_script(script, timeout_seconds=None, validate=True)。 只有当调用确实合法、但用 dir(ansa) 探测不到时，才显式 validate=False 绕过。 v1.0.5 修好了拒绝路径：ipc.error_response 现在接受可选 data，所以一个引用了不存在函数的脚本 会返回结构化的 data.missing / data.checked，而不是在构造错误响应时抛 TypeError 崩掉。

6. 测试与验证

6.1 三道离线门（不需要开 ANSA，退出码非 0 即失败，可直接接 CI）

export PYTHONPATH=src
python scripts/regression_check.py                 # 208 项断言
python scripts/audit_command_keys.py               # 服务端参数 ↔ 插件消费 契约
python scripts/audit_ansa_api_usage.py --strict    # 源码调用 ↔ 事实层（命中 REJECTED 即失败）

实测结果（2026-09-13，当前 v1.0.7）：

v1.0.7 收尾：三条滞后断言已修（实现一直是对的，过期的是断言；判据见 §10.26）。 曾让门变红的四处：check("__version__ is the shipped 1.0.3", ...)（写死字面量，每次发版必假失败）、 check("all 73 tools are registered", ...)（真实 78）、 check("... callable(namespace.get("_teardown_timer"))")（v1.0.7 已改名 _reset_bridge_refs）， 以及 bridge_doctor.py 把 _teardown_timer 当"新代码已生效"的标记符号 —— 该处最隐蔽：改名后 doctor 会永远报 code_is_current = False。 修法：版本断言改为"X.Y.Z 形态"（不再写死）、工具数保留为有意的计数跳线、 标记符号抽成 bridge_doctor.RELOAD_MARKER 单点声明。 另把 3 个"未登记"的 ANSA 调用补进 VERIFIED_API： guitk.BCWindowShowTitleBarButtons 与两个 BCEnumTitleBarButton 常量 （BCMinimizeButton / BCMaximizeButton）。

8 个被扫文件里的 audit.py / knowledge.py / memory.py / api_doc.py 预期各自 0 次 ANSA 调用 —— 把它们列进去，是为了让"这几个模块是纯的"变成一条被检查的断言， 而不是一个假设。（api_doc.py 于 v1.0.7 加入，见 §10.26。）

--verbose 会把 opt 前缀标出来：那些是 ansa_api.OPTIONAL_API 里登记过的、随构建而异的 属性（base.GetCurrentFileName 等）。它们算"已知"而非"未登记"—— 否则一份永远挂着例外的报告，会让一个真的拼写错误混在噪音里过关。

这三道门守的是本项目最容易犯的三类错：参数名写错、服务端发了插件不认的键、 调用了一个根本不存在的 ANSA 函数。它们跑得很快，改完代码先跑一遍再上真机。

6.2 真机能力探测（需要 ANSA 在跑）

python scripts/mcp_cli.py run_python_script_in_ansa --no-wait \
    --script-file scripts/probe_ansa_capabilities.py --kw function_name=main

或在 ANSA 里点 MCP-Sum → Probe Caps。产物：<HOME>/capabilities/capabilities.json。

本机实测摘要（ANSA 25.1.4，probe 2.0）：

import_style 字段记录每个模块实测用哪种导入方式才成功。旧版 probe 1.0 只用单一 importlib 策略，把 ansa.constants、ansa.base.checks.* 误判成"不可用"——1.0 的清单不可信， 服务端会返回 stale: true / action: reprobe。

6.3 通道健康自检

python scripts/check_mcp_sum_health.py            # 逐环定位断点
python scripts/check_mcp_sum_health.py --deep     # 额外做一次 stdio 握手（约 12 秒）

覆盖 8 环：mcp.json 条目 → 解释器 → PYTHONPATH → 模块可导入 → server 进程存在 → 进程是否跑的是当前源码 → 桥 status.json → 文件通道 ping。

第 6 环是 2026-09-13 真机联调后补的。前 4 环都是另起一个解释器验证当前源码， 回答的是"源码里有什么"，不是"客户端正连着的那个进程有什么"——两者可以不一致： 实测源文件 13:05 改完、server 进程 12:57 起来，于是那次新加的工具在客户端全部表现为"调不到" （当时的现场是 73 个工具的源码只被客户端看到 70 个）。判据是进程启动时间 vs server.py 的 mtime。

--deep 现在走的是完整会话而不只是 initialize（probe_mcp_sum_server.py 于第二批重写）： initialize → tools/list（78 个、注解齐全、无空描述、12 个带踩坑提示）→ resources/list（5 个 URI）→ resources/read（逐个读回并解析）→ tools/call remember / recall。

为什么要走到读回来为止：注册了但读不出来的资源等于没加，而这一点在本地单元测试里看不到 —— 本地是直接调 Python 函数，不走 JSON-RPC 那一层。加 --home <path> 可换一个隔离状态目录， 不动真实 HOME。实测 18/18 通过（v1.0.7 收尾前这里是 17/18：唯一失败项是探针脚本里 仍写着旧值 tools/list 返回 73 个工具，实际 78 个 —— 同样是断言滞后，见 §10.26； 最后一项是探针擦掉自己写入的标记 —— 默认 HOME 就是真实那个，健康检查不该在操作者的记忆里留垃圾）。

python scripts/probe_mcp_sum_server.py --home "$TEMP/ansamcp-probe"   # 隔离 HOME，全走线

6.4 一个真实的端到端样例

scripts/s2–s6 是一次完整作业的留档（铸件 Casting_initial.ansa，1101 个几何面、 无实体无网格，包围盒 501×50.5×122.3 mm）：

7. 实测沉淀：这些坑是真踩过的

7.1 返回值约定不统一（写判定时的头号坑）

按 ret == 0 判成功，会让每一次成功导出都带一条警告。逐函数真值见 ansa_api.VERIFIED_API。

7.2 MidSurfAuto 只认位置参数（静默失效，最阴的一个）

base.MidSurfAuto(thick=1.0, faces=faces, length=3.0)   # ✗ 关键字被忽略：返回 0、耗时 0.0s、模型零变化
base.MidSurfAuto(1.0, faces, False, False, 3.0)        # ✓ 位置参数：(thick, faces, exact_middle, connect_weldings, length)

关键字传参不报错，看起来完全像成功。判成败必须看耗时与 SHELL 计数， 不能只看返回值。同类现象还有 base.CalculateOffElements()——返回 {'TOTAL OFF': n, ...}， n 取决于当时载入了哪套质量准则；准则全 OFF 时它恒为 0，不代表网格更好。报这个数必须附准则状态。

7.3 CheckReport.try_fix() 不做几何修复

语义是把报告标记为已修复（is_fixed）。实测两次对照实验：

修复前:  status=error, 5 issues, has_fix=True
try_fix: tried=1, ok=true
修复后:  status=ok,    0 issues, has_fix=False   ← 检查"通过"了
────────────────────────────────────────────────
ID 集合差:  8821 / 9280 消失 → ID 1 / 2 出现（删掉重建，换号）
几何统计:   逐位相同（min 面积 0.007mm²、154 个 <1mm² 面、177 边面 1 个、总面积 196074.8）

即：删掉问题面再重建，几何一像素没动，然后把检查状态改成 ok。 另一条路 删除碎面 + FillHoleGeom(..., always_produce_new_faces=False) 同样几何守恒—— 缺口形状由那几条 CONS 唯一决定，曲面延展不进去，只能新建一个形状相同的面。

结论：ProblematicSurfaces 报的面是相邻面之间必要的过渡面，不是冗余碎面。 下游中面质量分 98.9% 已达标的情况下，强改几何是高风险低收益。

7.4 事实层（ansa_api.py）的硬规约

禁止再用 getattr(mod, "Fn", None) 兜底——那会把"函数不存在"变成操作执行到一半时的 TypeError: 'NoneType' object is not callable。统一走 api.resolve()，缺失时抛 ApiMissing。

v1.0.2 之前这里有两处"规则例外"：plugin.py 用循环 getattr(base, name, None) 探测 GetCurrentFileName / CurrentFileName，靠 audit 脚本的"探测位置"豁免才没被标记； autoload 脚本里的 ansa.session.defbutton / ProgramArguments 则一直挂在"未登记"栏。 现在前者收进 OPTIONAL_API、后者登记进 VERIFIED_API，未登记数归零。 规则可以带逃生阀，但不能带说不清来源的例外。

7.5 运维层面的两个陷阱

• 心跳老化 ≠ 桥死了。 插件空闲时 status.json 按 5 秒节流写盘，时间戳不推进很正常。 判桥活性只能用 mcp_cli.py ping。

• 过期命令会被自动丢弃。 STALE_COMMAND_AGE_SECONDS = timeout + 60，超龄命令在下次轮询时 丢弃并记入 logs/dropped.log——所以上游崩溃后重启 ANSA，不会在开机时再撞一次同一条命令。

7.6 一条已知的崩溃路径（未完全定位）

对字段不匹配的 FACE 实体批量调用 base.GetEntityCardValues(deck, entity)（不传字段元组） 曾导致 ANSA 进程直接消失：无结果落盘、status.json 时间戳停在起始时刻、系统事件日志无崩溃记录。 把以下 4 类调用排除后，同一套脚本完整跑通且结果可复现：

GetEntityCardValues 无字段调用 · CheckDescription.read_descriptions() · Check.parameters() · Or()/RedrawAll() 可见性批操作

纪律：逐条单独试，每条之间确认 status.json 时间戳已推进； GetEntityCardValues 永远显式传语义匹配的字段元组并包 try/except。

8. 已知限制

• 仅 GUI 模式。-b 批处理下 ANSA_TRANSL.py 里的加载被跳过（本项目的立身基础就是 GUI）。

• mesh_volume 无法按实体限定——已验证的 API 不支持，工具会明确拒绝而不是静默网格化整个模型。

• ProblematicSurfaces 无法自动修复（见 §7.3），has_fix=True 只代表 GUI 里有交互式手段。

• 本机 base.Undo 不可用（undo_available: false），脚本没有撤销退路——改模型的脚本务必谨慎。

• 路径白名单（_validated_workspace_path）只作用于三个工具：save_model_as_ws、 export_solver_deck、以及 delete_faces 的可选 save_as 参数；save_model_as(filepath) 与文件通道（mcp_cli.py）都没有路径校验。

• 能力清单是快照。换 ANSA 版本或装了新模块后需重新 Probe Caps。

• 项目未纳入版本控制（无 git 仓库），三道离线门也还没接进 CI。

• 预检依赖"活的" ANSA：validate_script / execute_script(validate=True) 要把脚本里的调用 对照正在运行的 ANSA build 校验，所以桥没起来时无法预检（此时会被插件就绪门禁挡下）。

• 能力清单还没接进工具注册。load_capabilities() 的 docstring 承诺"缺 API 的工具对模型隐藏"， 但 78 个工具目前全是静态注册，清单只是 ansa://capabilities 的一份报告。

• 工具数断言是"计数跳线"：regression_check.py 里的 all 78 tools are registered 是有意的 字面量 —— 增删工具必须在同一次提交里改它。这是它与版本号断言的区别（后者已改为"X.Y.Z 形态"， 不再写死），别为了"全绿"把这条也改成范围判断。

已不再是限制（本清单曾列出）：

• v1.0.2 第二批：运行时审计已落地为 logs/audit.jsonl（见 §5.5）； 跨会话记忆已落地为 remember / recall / remember_note 与 memory/（见 §5.4）。

• v1.0.7 收尾：离线门滞后已修（3 条回归断言 + 1 条探针断言 + bridge_doctor 的标记符号）； 事实层未登记数已归零（补进 3 个 guitk 名字）；api_doc.py 已纳入审计扫描（见 §10.26）。

10. 变更记录与路线图

10.1 v1.0.2 —— 审查第一批（小改动、零行为风险）

三道门：204/204 · 63/63 · REJECTED 0，全部 exit 0。 旧版全量备份在 D:\ansa-mcp-sum_backup_20260913_124913（48 文件 / 883 K）。

10.15 v1.0.2 —— 审查第二批（纯新增能力，不动现有路径）

工具数 70 → 73、资源 2 → 5、回归断言 91 → 178。版本号按第一批的约定仍为 1.0.2。 新版备份在 D:\ansa-mcp-sum_backup_batch1_20260913_125908（第二批改前的状态）。

10.16 v1.0.2 —— 首次真机联调修复（2026-09-13，ANSA 25.1.4 在线）

前两批都是离线验证的（回归 + 探针 + 离线审计）。第一次把 73 个工具接到真正开着的 ANSA 上跑， 暴露出三个离线门看不见的缺陷。它们的共同形态是：问错了问题，而答案看起来像模型的属性 —— 所以每一条的判据都写在"错答案的产物"上，而不是"调用是否返回"。

真机验证（同一会话内热重载插件后即刻生效，未重启 ANSA）：

get_bounding_box(1, 'GRID')    -> ok  coord_fields=["X1","X2","X3"]  20000 点
                                  min=[-540.21, -700.04, -170.00]  max=[0.20, 1200.00, 120.00]
get_node_coordinates([1,2,3])  -> 节点 1 = [-418.06424, 244.09517, 51.38365]   （修复前是 [0,0,0]）
open_model(result.ansa)        -> 审计 model_before=initial.ansa  model_after=result.ansa  changed=True
open_model(initial.ansa)       -> 恢复用户要求的初始状态

回归断言 164 → 178（新增 4 个测试函数，含"残行之后写入的事件仍可读"）。 踩坑登记表 10 → 11 条：新增 nastran-grid-coords-are-x1x2x3，并挂到受影响的 get_bounding_box / get_node_coordinates 的工具描述上。

热重载：autoload 的 _poll_once() 是按模块属性查表调用 plugin.ansa_mcp_process_one() 的， 所以在 ANSA 里 importlib.reload 这几个模块即可让插件侧改动立即生效，不必重启 ANSA。 但 server 侧不行 —— MCP 客户端是在自己启动时拉起 ansa_mcp_sum.server 子进程的， 改完 server.py（工具表、resource、记忆工具）必须让客户端重连该 server 才会看到， 否则工具数会停在旧值。

这次联调还留下两条已确认、未修的问题，已记入 §10.17。

10.18 v1.0.2 —— 桥定时器不再"假装在跑"（2026-09-13）

起因是一个问题：「点了 Auto Poll」和「ANSA_MCP_SUM_Bridge 那个小窗口」是不是一回事。 答案是一回事 —— 窗口不是开关，它只是 guitk.BCTimerCreate(parent) 需要的宿主， Auto Poll 按钮的实现体就是 _init_bridge()，启动时的自动轮询调的也是它。

但顺手测出来一件更要紧的事：那个按钮点了等于没点。证据不是"感觉慢"，是三个可复现的数：

根因在判据本身：

# 旧：只要对象"active"就认为一切正常，而且什么都不打印
if _poll_timer is not None and guitk.BCTimerIsActive(_poll_timer):
    return True

BCTimerIsActive 描述的是对象状态，不是有没有在投递回调。定时器可以 active 却一个回调都不发（_busy 重入锁卡住 / GUI 主线程被模态框占住 / 被 hide）， 这时 Auto Poll 成了"点了没反应也不报错"的按钮，而 status.json 一直写着 running。

Run Once 照常能用，恰恰是这件事难发现的原因 —— 它直接调 plugin.ansa_mcp_process_one()， 绕过 _busy 守卫。所以 Run Once 成功不能当作轮询正常的证据。

顺带纠正一条流传了很久但没依据的说法：注释、USAGE.md 与技能文档里都写着 "关掉那个窗口就会静默停止轮询"。官方文档里 guitk.constants.BCOnExitHide 写的是 hides the window（BCOnExitDestroy 才是 destroy），而隐藏的父对象不会停掉子定时器。 这句话已从三处删掉、改为"未经验证、与官方文档相悖"。窗口的提示文字也改成只是"它承载定时器"。

两个 API 事实值得记下（都已进 ansa_api.REJECTED_API，写错会被离线审计拦下）： guitk 里既没有 BCTimerDestroy，也没有 BCDestroyWindow。25.1.4 的定时器只有 Create/Start/Stop/IsActive/ChangeInterval，"重建定时器"只能是 BCTimerStop 旧的 + 丢引用，旧对象交给 GC。窗口则不能销毁 —— BCDestroy 的文档明确要求用 BCWindowAccept/BCWindowReject 关窗口，而 BCWindowCreate(name, ...) 的 name 是它 gui 数据的 xml tag、文档要求唯一；所以恢复时复用同一个窗口 （_ensure_window）而不是重建，否则每恢复一次就多叠一个同名窗口。 之前 _teardown_timer()/bridge_doctor.py/能力探针里那三处 BCDestroyWindow 全部包在 try/except 里，所以它一直"成功"地什么都没做。

回归断言 178 → 190：新增 3 个测试函数（把一个假 guitk 装进 autoload 模块，再驱动状态）， 覆盖"冷启动真的建了定时器 / 健康的定时器不重建 / active 但停摆必须重建 / 命令在跑不算停摆 / _busy 卡死超限时清锁不抛异常 / 重入与停止时 tick 时钟必须冻结（否则停摆永远测不出来）"。

10.19 v1.0.2 —— 改完脚本不必重启 ANSA（2026-09-13）

为什么必须专门解决这件事：ansa.ImportCode 只在 ANSA 启动时执行一次 scripts/ansa_mcp_sum_autoload.py，之后代码活在 ANSA 自己的命名空间里，磁盘上的文件 再也不会被读。Auto Poll 按钮读不到它，importlib.reload(ansa_mcp_sum.plugin) 也读不到 它（那是另一个文件）。所以"改完脚本点一下按钮"这个直觉是错的——修好的代码在重启前一直是 文本。这也解释了本次现场：用户点了 Auto Poll 而行为没变。

解法：bridge_doctor.py 新增 _reload_autoload()，把当前文件 exec 回它自己的 命名空间。一个坑：文件里四个工具栏按钮是模块级 @defbutton 装饰的，直接重跑会给每个 按钮再加一份，所以 exec 期间把 ansa.session.defbutton 换成空操作，结束后还原。

按钮不需要重新注册也能用上新代码：按钮持有的是旧函数对象，但它们的 __globals__ 正是被 刷新的那个命名空间，_init_bridge 等名字在调用时才查表，所以 Auto Poll 点击后走的 已经是新逻辑。

结论：不需要重启 ANSA。点一次 MCP-Sum > Run Once 即可（doctor 命令在队列里）， 之后 Auto Poll 与看门狗走的都是新代码。

10.20 v1.0.2 —— 命令过期按"它自己的超时"判（2026-09-13，真机事故后修）

现场：mcp_cli.py --timeout 1800 把 doctor 命令投进队列，用户 14:36 点了 Run Once， 结果 status.json 显示 processed 0 + dropped_stale 1，dropped.log 里一条：

2026-09-13T14:36:47  dropped  244fc2b1c25c  age=832.0s  limit=660s

根因：cleanup_stale_commands() 用全局 STALE_COMMAND_AGE_SECONDS （CONFIG.timeout_seconds + 60 = 660s）判过期，完全无视命令 payload 里的 timeout_seconds。而 mcp_cli.py --timeout N 是写进 payload 的，客户端真的会等 N 秒。 于是 --timeout 1800 的命令在 660s 就被删，客户端还要再空等 19 分钟 —— 现象与"桥死了"无法区分。

教训：任何"多久算过期"的判据，只要生产者与消费者是两端，就必须读那一端自己声明的 数字，不能用本端配置里的默认值代替 —— 否则默认值一旦与调用方不一致，失效方式是静默丢弃。

10.21 v1.0.3 —— 热重载不再"叠"桥窗口（2026-09-13，真机事故后修）

现场：bridge_doctor 经 MCP-Sum > Run Once 投进队列，因 §10.20 之前的旧 ansa_mcp_process_one() 不删命令文件，该命令被反复派发 82 次；每次 bridge_doctor 都把 ansa_mcp_sum_autoload.py 用 exec(code, g) 重新执行进 autoload 自己的 namespace。模块体里有一行 _bridge_window = None，于是每次重载都把活的窗口句柄 抹成 None，紧接着 _init_bridge() 以 _bridge_window is None 又建一个 ANSA_MCP_SUM_Bridge 窗口 —— 而 25.x 没有 guitk.BCDestroyWindow，旧窗口只是被 遗弃不销毁。82 次重载 → 几十个窗口叠在同一份 xml tag 下（"几十个窗口"症状）。 §10.20 的 claim 机制已堵住"重复派发"，本条目堵"重载后窗口句柄被抹掉"这一环。

教训：凡是"跨热重载必须存活"的对象，绝不能放在会被 exec 重置的脚本模块全局里， 要放进一个从不重新执行的宿主模块（这里是 ansa_mcp_sum.plugin 的 GUI_HANDLES）。

10.22 v1.0.4 —— 内嵌 ANSA API 文档 + 执行前预检（2026-09-13）

把另外那个 ansa-api MCP 的检索能力搬进本项目，并加一层"跑脚本之前先验函数是否存在"的预检。

工具数 73 → 78（+5）；派发 63 → 65（validate_script 也写命令文件）。 动机见 §5.6 开头："调用了一个本机不存在的函数"是最贵的一类脚本错误，它要么静默返回 0、 要么在操作跑到一半时才抛 TypeError。

10.23 v1.0.5 —— 预检的拒绝路径不再崩

10.24 v1.0.6 —— 索引随包分发，项目自包含

10.25 v1.0.7 —— 桥崩溃（EXCEPTION 0xC0000005）根治（2026-09-13，真机事故后修）

现场：Auto Poll 期间 ANSA 直接段错误消失（EXCEPTION 0xC0000005）。这是不可捕获的 native 崩溃 —— Python 的 try/except 拦不住，results/ 空、status.json 时间戳不动。两条独立的修复：

这是"离线门看不见"的典型：回归与走线探针全过，但真机上点一下窗口的 X 就崩 —— 因为两类断言都只在假 guitk 上跑。教训延续 §10.21： 跨热重载 / 跨生命周期存活的原生句柄，任何一次解引用都可能是最后一次； 能用 Python 侧状态判断的，就不要去碰 native 句柄。

10.26 v1.0.7 收尾 —— 让离线门重新全绿（2026-09-13）

三道门 + 走线探针在 v1.0.4–v1.0.7 期间陆续转红，追下去实现全是对的，红的是断言与审计清单。 共五处：

第 3 条是本次唯一的功能性缺陷：doctor 的整个价值就是"证明新代码进了内存"， 标记符号跟着改名失配后，这个诊断工具自己静默失真——每次都告诉你"代码没更新"。

验证（2026-09-13，四条全部 exit 0）：

python scripts/regression_check.py                 # 208/208
python scripts/audit_command_keys.py               # 64/64 可达
python scripts/audit_ansa_api_usage.py --strict    # 扫描 8 文件 · 调用 55 · 已核实 55 · 未登记 0 · REJECTED 0
python scripts/probe_mcp_sum_server.py --home "$TEMP/ansamcp-probe"   # 18/18

事实层同时涨到 VERIFIED 86 / REJECTED 33 / OPTIONAL 3。

教训：这三类"门变红"长得一样，处理却不同 —— ①版本号字面量：天生会过期 → 改成形态断言； ②函数 / 符号名：改名会静默失效 → 抽成单点常量，并让测试断言当前名字； ③计数：留着当跳线，但必须与工具面变化同一次提交。 判据只需问一句："这个数字 / 名字明年还会对吗？" 不会，就别写死。

10.27 scripts/ 瘦身 78 → 14，移除陈旧 build/（2026-09-13）

仓库里攒了 64 个一次性探索脚本（s7–s56 的 Map Block / 碎面修复 / 桥崩溃排查线， 以及更早的 discovery.py / count_*.py / probe_* 临时探针）。它们全仓库零代码引用， 是"当时在真机上试过什么"的留档，不是运行路径。按"是否承载运行与门禁"清理：

同时清掉 scripts/__pycache__，并把顶层 build/（11 MB、12 个文件，其中 __init__.py 与 ansa_api.py 已与 src/ 不一致） 移出仓库：它是 setuptools 构建产物，grep 全仓库 （代码 / 文档 / 配置）无任何引用，python -m build 即可重新生成。

验证：清理后三道离线门照旧全绿（208/208 · 64/64 · unlisted 0）， 说明删掉的确是不承载运行的东西。顺手修了两处会变成悬空的文档注释： mcp_cli.py 的示例 --script-file discovery.py → my_script.py； audit_ansa_api_usage.py 的 SHIPPED 注释不再点名已删的探针。

教训：删"历史脚本"前先做引用图，别按文件名猜 —— 本例中 5 个看似可删的 s2–s6 其实被 shipped 资源引用；而看似"正式"的 build/ 才是真正没人要的。判据不是"名字像什么"， 而是"全仓库谁在引用它"。

10.17 还没做（按优先级）

9. 排错

常见现象的处置见 USAGE.md §11 排错表。30 秒自查顺序：

python scripts/check_mcp_sum_health.py --deep     # ① 通道逐环
python scripts/mcp_cli.py ping                     # ② 桥是否应答（绕开 MCP 层）
tasklist | findstr ansa_win64                      # ③ ANSA 进程还在吗

三条一起看就能定性：ping 通 → 问题在 MCP 层；ping 不通且 ANSA 进程不在 → 只是 ANSA 关了 （重启 ANSA 桥会自动回来，ANSA_TRANSL.py 的 ImportCode 还在）；ping 不通但 ANSA 在 → 查 <HOME>/logs/audit.jsonl 与 status.json。

"我发的那条命令到底跑了没有" —— 按顺序看这三处就够，不用猜：

tail -5 "$HOME/logs/audit.jsonl"     # ① 跑过没有、多久、成没成、模型路径变没变
ls "$HOME/results/<command_id>.json" # ② 有结果文件 = 跑完了（超时后也要来这查）
ls "$HOME/commands/"                 # ③ 还躺在这里 = 从没被取走；超龄会被记为 dropped_stale

超时不取消 ANSA 侧的操作。重试一条改模型的命令之前，先看 ① 和 ②。