# 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](USAGE.md)**（逐步安装、配置、排错表）
* 本文档偏重**架构、测试与实测沉淀**——即"这个项目到底验证过什么、哪些坑是真的踩过"。

---

## 1. 它解决什么问题

| 项目 | 传输层 | 能看到 ANSA GUI | 工具数 |
|---|---|---|---|
| `ansa-tcp-bridge` | TCP / IAP（`-b` 批处理） | ❌ | 49 |
| **`ansa-mcp-sum`** | **文件 IPC 命令队列（GUI）** | ✅ | **78** |

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

---

## 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 通道 | 文件通道（`scripts/mcp_cli.py`） |
|---|---|---|
| 本质 | 本地子进程 JSON-RPC（stdio） | 磁盘收发文件 |
| 能力面 | 78 个带 schema 的工具 | 65 个派发命令（64 种类型），手写 `type` + 参数 |
| 参数校验 | JSON Schema 拦一道 | **无** |
| 路径白名单 | `_validated_workspace_path()` | **无** |
| 心跳门控 | 有 | **无**（可 `--no-wait` 盲投，下次轮询执行） |
| 断了的症状 | 工具消失、报 `Not connected` | **无感知，照常通** |

排障时这就是个二分法：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](MODULES.md)**。

---

## 4. 快速开始

完整步骤见 **[USAGE.md](USAGE.md)**，这里只列最小路径。

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

```jsonc
// 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" }
    }
  }
}
```

```python
# 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')
```

```powershell
# 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 候选路径。

### 工具栏按钮

| 按钮 | 作用 |
|---|---|
| **Run Once** | 主线程手动处理当前队列（点一次处理一批） |
| **Auto Poll** | 启动后台轮询（默认开启） |
| **Probe Caps** | 采集本机能力清单 → `<HOME>/capabilities/capabilities.json` |
| **Stop** | 停轮询 + 写 `stop.flag` + `status.json` 置 `stopped`（服务端门禁立即生效） |

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `ANSA_MCP_SUM_HOME` | `~/.ansa-mcp-sum` | 命令/结果目录根 |
| `ANSA_MCP_SUM_AUTO_POLL` | `1` | 设 `0` = 只加载按钮、不起定时器（按需模式）；**须与 ANSA 同环境生效** |
| `ANSA_MCP_TIMEOUT_SECONDS` | `600` | 单条命令等待 ANSA 回结果的超时 |
| `ANSA_MCP_HEARTBEAT_STALE_SECONDS` | `2147483647` | 按需桥不靠心跳，基本永不过期 |
| `ANSA_MCP_MAX_SCRIPT_CHARS` | `65536` | `run_python_script_in_ansa` 的脚本大小上限 |

其它运行时常量：轮询 `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**：

| 类别 | 工具 | 说明 |
|---|---|---|
| 跨会话记忆（3） | `recall` · `remember` · `remember_note` | 刻意不走桥：**桥没起来的时候，恰恰是最需要"我上次在干什么"的时候**（§5.4） |
| 内嵌 ANSA API 文档（4） | `ansa_api_doc_search` · `ansa_api_doc_lookup` · `ansa_api_doc_modules` · `ansa_api_doc_categories` | 读包内 10.4 MB 索引，**既不需要 ANSA 在线，也不依赖另外那个 `ansa-api` MCP**（§5.6） |
| 服务端 helper（6） | `ping` · `select_faces_by_query` · `preview_selection` · `autosave_model` · `batch_benchmark_test` · `read_last_log` | 不真派发；`autosave_model` 转调已派发的 `save_model_as_ws` |

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

<details>
<summary><b>65 个派发工具的分组清单</b></summary>

**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`

</details>

### 5.1 每个工具都带 MCP 注解

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

| 注解常量 | 数量 | 含义 | 代表工具 |
|---|---|---|---|
| `READ_ONLY` | 39 | 只读，不碰模型也不写文件 | `count_entities` · `calc_mesh_quality` · `recall` · `ansa_api_doc_*` |
| `VIEW_ONLY` | 5 | 只改可见性，重复执行结果相同 | `show_only` · `near` · `hide` |
| `WRITE` | 12 | 写输出，幂等，不丢既有数据 | `save_model_as_ws` · `export_*` · `remember` |
| `WRITE_ADDITIVE` | 5 | 新增，跑两次就有两个 | `create_set` · `remember_note` · `autosave_model` |
| `DESTRUCTIVE` | 17 | 删除 / 替换既有状态 | `mesh_shells` · `delete_entities` · `execute_script` |

> 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 两个同名但语义不同的工具

| 工具 | 路径语义 |
|---|---|
| `save_model_as(filepath)` | **绝对路径**，直接存（迁移自 tcp-bridge） |
| `save_model_as_ws(output_path)` | 相对路径落到 `ANSA_MCP_SUM_HOME` 下（workspace 校验，防写飞） |

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

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

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

| URI | 内容 | 为什么存在 |
|---|---|---|
| `ansa://status` | 插件原始状态 JSON | 排障 |
| `ansa://capabilities` | 本机 ANSA 能力清单（probe 产出） | 判"这个函数本机到底有没有" |
| `ansa://pitfalls` | **11 条实测踩坑**（症状 / 原因 / 正确写法 / 判据） | 见下 |
| `ansa://workflows` | **5 段实测流水线**（诊断 → 体检 → 载标准 → 中面+网格 → 验证） | 每步带真实 API 与验收标准 |
| `ansa://memory` | 偏好 + 笔记 + 命令历史摘要 | 跨会话续接（§5.4） |

`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/` 下）：

| 文件 | 形态 | 放什么 |
|---|---|---|
| `prefs.json` | 键值，带 `updated` / `note` / `previous_value` | 本项目的 deck、标准 `.ansa_mpar` 路径、目标边长、质量基线 |
| `notes.md` | 追加式 Markdown | 装不进键的观察（"这个件壁厚 1.86–3.88，所以取 3.0"） |

三个工具：`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：

```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_doc_search(query, module, category, top_n)` | 三层：关键词（模块名/函数名加权）→ 描述+签名模糊 → 外部 txt 兜底。返回签名、参数、返回值、示例 |
| 精确查函数 | `ansa_api_doc_lookup(function_name, module)` | 按精确名（大小写不敏感，支持 `mesh.Mesh` 这类限定名）取完整文档 |
| 列模块 | `ansa_api_doc_modules()` | 各模块函数计数 |
| 列类别 | `ansa_api_doc_categories()` | 各类别函数计数 |
| **预检** | `validate_script(script)` / `execute_script(validate=True)` | 解析脚本里每个 `ansa.<module>.<func>` 与 `<module>.<func>`，对照**活着的** ANSA build，返回缺失调用列表——**在真正跑起来之前**就拦下幻觉 |

**索引来源**：`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）

```bash
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）**：

| 门 | 结果 |
|---|---|
| `regression_check.py` | **208/208 PASS**，exit 0 |
| `audit_command_keys.py` | 命令类型 **64** · 注册处理器 **64** · **可达 64/64**，无未消费 kwarg，exit 0 |
| `audit_ansa_api_usage.py --strict` | 扫描 **8** 文件 · ANSA 调用 **55**（已核实 55 / optional 0 / **未登记 0**）· **REJECTED 命中 0**，exit 0 |

> **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 在跑）

```bash
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）**：

| 项 | 值 |
|---|---|
| `requirements_met` | **true** |
| `verified_function_count` | **80 / 80** |
| `missing_functions` / `unavailable_modules` / `probe_errors` | `[]` / `[]` / `[]` |
| `unexpectedly_present` | `[]`（事实层没有过期） |
| `gui_available` / `undo_available` | `true` / **`false`**（`base.Undo` 本机不可用） |
| `open_questions` | 11 条：10 条 `NOT_FOUND`（如 `base.Show/Hide/SetVisibility`、`mesh.MeshVolume`），1 条 `OK`（`mesh.RemeshShells` **存在**） |
| `functions` 分类计数 | base 54 · REJECTED 17 · mesh 12 · CAND 11 · connections 7 · guitk 3 · ansa 2 · session 2 |

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

### 6.3 通道健康自检

```bash
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 就是真实那个，健康检查不该在操作者的记忆里留垃圾）。

```bash
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）：

| 步骤 | 脚本 | 实测结果 |
|---|---|---|
| 1 模型诊断 | `s2_diag.py` | `is_solid_desc=1`，shell 占比 **0.0%** → 确需抽中面；壁厚 1.86–3.88 mm |
| 2 几何检查 | `s3_geomcheck.py` | 20 项检查；自算拓扑 **2933/2933 边全被 2 面共享**（完全流形、0 自由边、0 重复面） |
| 3 载入标准 | `s4_standards.py` | `target_element_length` average→**3.**，质量标准 77/80 精确匹配 |
| 4 抽中面 | `s5_midsurf.py` | `MidSurfAuto(1.0, faces, False, False, 3.0)` → **54.2 s / 13,510 壳单元** |
| 5 成果验证 | `s6_verify.py` | p50 2.74 / p90 **3.01 mm**；中面质量分 **98.9%**；QCHECK **1.273**；文件 13.98 MB 落地 |

---

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

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

| 函数族 | 成功值 |
|---|---|
| `base.Open` / `Save` / `SaveAs` / `SetANSAdefaultsValues` / `DeleteEntity` | **0** |
| `base.OutputNastran` / `OutputLSDyna` / `OutputAnsys` / `OutputAbaqus` | **1** |
| `mesh.Mesh` / `mesh.CreateBestMesh` / `mesh.*` | **1** |

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

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

```python
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`）的硬规约

| 规约 | 说明 |
|---|---|
| `import ansa.constants` → ✗ | `ansa` 不是 package。必须 `from ansa import constants` |
| `ansa.ImportCode` | 只在**顶层** `ansa` 上；没有 `ansa.session.ImportCode` |
| `DECK_NODE_TYPE` | NASTRAN→`GRID`，LSDYNA/ABAQUS→`NODE`。用错**不报错、只返回 0** |
| `CollectEntities(deck, container, type, recursive)` | 4 个位置参数；实体类型是纯字符串 |
| `base.GetEntityType(deck, entity)` | **必须 2 个参数**；参数个数错误会被误读成"类型不支持" |

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

| 规约 | 说明 |
|---|---|
| `resolve(path)` | 唯一的解析入口；缺失即抛 `ApiMissing` |
| `OPTIONAL_API` | **登记表**，只装真正随构建而异的属性 |
| `resolve_optional(path)` | 只对登记过的名字返回 `None`；未登记的名字照样抛——逃生阀不能变成默认路径 |
| `current_model_path()` | 要"当前打开的文件"时用它；拿不到返回 `None`（只用于上报，不用于判定命令成败） |

> 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 —— 审查第一批（小改动、零行为风险）

| 项 | 改动 | 验证方式 |
|---|---|---|
| 版本治理 | `__version__` 单一来源，`pyproject` 走 `dynamic`；依赖收紧为 `mcp>=1.0,<2` | 构建元数据实测 `Version: 1.0.2` / `Requires-Dist: mcp<2,>=1.0`；回归断言比对 `status.json` |
| 超时对账 | 超时 payload 补 `command_id` / `result_path` / `queue_depth` / `bridge_state` / `elapsed_s`，并明确警告"超时不取消命令" | 回归里真触发一次 0.2 s 超时并逐字段断言 |
| 工具注解 | 70 个工具全部带 `readOnlyHint` / `destructiveHint` / `idempotentHint` | 回归读 FastMCP 注册表（不是读源码文本）：无漏标、无"既只读又破坏"的矛盾 |
| 产物归位 | 新增 `<HOME>/artifacts/`；`s7` / `s10` / `s11` 三个实验脚本不再硬编码 `C:\Users\Admin\...`，也不再往 HOME 根目录丢文件 | 已把 `_proc_list.txt`、`geom_ids_before.json`、`geomfix_trace.json` 移入 `artifacts/` |
| 事实层收口 | 取消 `plugin.py` 的 `getattr` 探测，改走 `api.current_model_path()`；新增 `OPTIONAL_API` 登记表 | `audit_ansa_api_usage --strict` 未登记数 **5 → 0** |

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

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

| 项 | 新增 | 验证方式 |
|---|---|---|
| 运行时审计 | `audit.py` + `logs/audit.jsonl`：一行一条命令，含 `args_hash` / `duration_s` / `model_before`→`model_after`；`dropped_stale` 与 `started`/`stopped` 同流；4 MB 轮转 | 回归在独立 HOME 里真派发命令、真丢一条过期命令，逐字段断言；另断言 4 KB 脚本原文**不落盘**、被撕开的末行不抛异常、写失败返回 `False` 并累加 `BRIDGE["audit_write_errors"]` |
| 踩坑知识 | `knowledge.py`（11 条 × 症状/原因/正确写法/判据）+ `ansa://pitfalls`、`ansa://workflows` 两个 resource | 回归断言条目字段完整、id 唯一、**每条 `must_resolve` 的 API 都在 `VERIFIED_API` 里**（把名字挪进 `REJECTED_API` 会让门失败） |
| 知识下发 | `@_with_pitfalls` 装饰器，10 个易踩坑工具的 description 里直接带正确写法 | 走线断言 73/73 有描述、10 个含踩坑段；源码形态断言禁止 `"""doc""" + brief()`（它会静默产生空 description） |
| 跨会话记忆 | `memory.py` + `memory/prefs.json` + `memory/notes.md` + `remember`/`recall`/`remember_note` + `ansa://memory` | 回归 `importlib.reload` 模拟新会话，断言值仍在；断言未知键返回 `NotFound` 且附已知键列表、空键/超大值/空笔记被拒、损坏的 prefs 被上报而非当空 |
| 通道自检补环 | `check_mcp_sum_health.py` 新增"进程启动时间 vs `server.py` mtime"比对 | 实测直接报出 `[WARN] server 进程早于 server.py 的修改时间`，并给出后果与修法 —— 此前这一步要人工比时间才看得出 |
| 走线探针 | `probe_mcp_sum_server.py` 重写为完整会话（工具 + 资源 + 工具调用），并在结束时擦掉自己写的标记 | 实测 **18/18**：73 工具、5 资源、`resources/read` 逐个解析、`remember`→`recall` 闭环、真实 HOME 不留垃圾 |
| 通道健康自检 | `check_mcp_sum_health.py` 的 deep 环节改读探针的结论行与退出码，不再 grep `"protocolVersion"` | 走线 18/18，健康自检报 `会话探针（走 JSON-RPC 真实链路）` |
| 审计范围 | `audit_ansa_api_usage.py` 的 SHIPPED 加入 3 个新模块（预期 0 次 ANSA 调用） | 扫描 4 → 7 文件，调用数仍为 52、未登记 0，证明新模块是纯的 |

工具数 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** 上跑，
暴露出三个离线门看不见的缺陷。它们的共同形态是：**问错了问题，而答案看起来像模型的属性** ——
所以每一条的判据都写在"错答案的产物"上，而不是"调用是否返回"。

| 缺陷 | 真机症状 | 根因 | 修法 |
|---|---|---|---|
| **模型路径访问器全死** | `audit.jsonl` 里 `open_model` 打开了 18 MB 模型，`model_before` / `model_after` 仍是 `null`；`status.json` 从不出现 `current_model_path` | 候选表里的 `base.GetCurrentFileName` 与 `base.CurrentFileName` 在 25.1.4 里**都不存在**（`hasattr` → False）。而源码注释写着"第一个能解析"——事实层里躺着一句未经核实的结论 | 候选首位改为 `base.DataBaseName`（实测返回当前模型路径，0.0 ms）；新增 `current_model_path_accessor()` 区分"没开模型"与"本构建没有访问器"；审计新增 `model_snapshot_error`，让后者不再和前者长得一样 |
| **NASTRAN 节点坐标读成空** | `get_bounding_box(deck=1, entity_type='GRID')` 报 "no node carried X/Y/Z card values"，而模型里有 16 381 个可见 GRID；`get_node_coordinates` 更糟 —— 每个节点都回 `[0.0, 0.0, 0.0]`，看不出是错的 | NASTRAN 的 GRID 把坐标放在 `X1/X2/X3`。`GetEntityCardValues` 对未知字段名返回**空字典而不是异常**，硬编码的 `('X','Y','Z')` 于是静默失效 | 新增 `NODE_COORD_FIELD_CANDIDATES` + `node_coord_fields()`（从真实实体自发现、按 deck 缓存）+ `read_node_xyz()`；`get_node_coordinates` 不再把缺失值兜底成 `0.0` —— "没读到"和"值就是 0"是两件事 |
| **审计残行会吃掉下一条** | 回归自身撞出来的：写一条不带尾换行的半截行之后，**下一条**事件的 JSON 被焊接到残行上，整行无法解析 —— 丢的不是残行，是新事件 | `append_event` 直接以 `"a"` 追加，不检查文件是否以换行结尾。`read_recent` 跳过残行只解决了读的一半 | 新增 `_newline_guard()`：追加前读 1 字节，上一行没写完就先补一个换行 |

真机验证（同一会话内**热重载插件**后即刻生效，未重启 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()`，启动时的自动轮询调的也是它。

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

| 观测量 | 值 | 含义 |
|---|---|---|
| `status.json` 年龄 | **557 s** | 轮询活着时每个 tick 都会走到 `write_idle_status()`，节流只有 5 s —— 所以这不是节流 |
| `commands/` 里最老一条 | 283 s 无人取 | 队列有货、没人搬 |
| 新投 `ping_ansa` | 20 s 超时 | 端到端确认 |

根因在判据本身：

```python
# 旧：只要对象"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 成功不能当作轮询正常的证据。**

| 改动 | 内容 |
|---|---|
| 判据换成"最近有没有真的 tick 过" | 新增 `_last_tick_at`，**只在通过守卫、真正干活的 tick 里刷新**。active 但静默超过 `STALL_SECONDS = 10` → 重建，而不是信任对象状态 |
| 每个分支都必须说话 | 旧的无操作路径连 `print` 都没有。现在"已经在跑"、"命令在执行中"、"可能停摆，开始重建"都要打印 |
| `_busy` 卡住时给出可见痕迹 | 写一次 `status.json`（`poll callback re-entered while a command is still in flight`），但**不自动清** —— 长命令（一次完整质量检查约 20 min）是正常的，清了会让两条命令并发。超过 `BUSY_LIMIT_SECONDS = 1800` 才强清并告警 |
| 新增 `scripts/bridge_doctor.py` | 经 `Run Once` 跑（这条通道绕开定时器，所以桥死着也能用）。扫 `sys.modules` 反查 autoload 命名空间 —— `ansa.ImportCode` 把文件体放哪儿不由你决定，按模块私有全局名反查比猜模块名可靠。打印 `_busy` / `_stop_requested` / `_poll_timer` / `BCTimerIsActive` / uptime 快照，再强清软闸门 + 重建 |
| 健康自检第 6 环收紧 | 判据从"300 s"改成 **30 s**（理由同表：写盘节流只有 5 s），并列出三个成因；队列环节从"有几条"改成"最老一条等了多久"，≥ 60 s 判 FAIL |

顺带纠正一条**流传了很久但没依据**的说法：注释、`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` 点击后走的
已经是新逻辑。

| 项 | 内容 |
|---|---|
| 新增 | `bridge_doctor._reload_autoload(ns)`：compile + exec（吞掉 `defbutton`），报告 `reload` / `code_is_current`；若重载后定时器仍未起（例如 `ANSA_MCP_SUM_AUTO_POLL=0`），再显式调一次 `_init_bridge()` |
| 新增 | `_ensure_window()`：窗口只创建一次，恢复时复用（见 §10.18 那条 API 事实） |
| 新增 | `_init_bridge()` 的 attach 重试：仅当"窗口本来就在"却挂不上定时器时，才丢引用重建一次；失败路径**不再**清 `_bridge_window`（那是唯一句柄，清了会造出同名第二窗口） |
| 测试 | 回归新增 `test_the_autoload_script_can_be_hot_reloaded_without_an_ansa_restart`：真实 exec 一次载荷 4 个按钮的脚本 → 重载后 `defbutton` 调用数必须不变（4 → 4）→ 再故意不带守护重跑一次证明它会变成 8（说明守护是承重的）→ 重建时定时器换新、**窗口对象不变** |
| 文档 | 本文件的计数、`USAGE.md` 排错表、技能 `ansa-python-api-25` §15.3 同步 |

结论：**不需要重启 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 分钟 ——
现象与"桥死了"无法区分。

| 项 | 内容 |
|---|---|
| 修复 | 新增 `_command_age_limit(payload)`：`payload["timeout_seconds"] + COMMAND_EXPIRY_GRACE_SECONDS(60)`；读不到或非法时回退 `STALE_COMMAND_AGE_SECONDS` |
| 修复 | `dropped.log` / 审计里的 `limit` 改为**实际生效的** limit，不再是全局常量 |
| 测试 | 回归新增 `test_a_long_client_timeout_is_not_dropped_early`：1800s 的命令在 age=832s 必须**仍在队列**（复现事故现场）、越过自身超时后必须被收走、payload 缺失/非法时回退默认 |
| 断言 | 199 → **204** |

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

### 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 机制已堵住"重复派发"，本条目堵"重载后窗口句柄被抹掉"这一环。

| 项 | 内容 |
|---|---|
| 修复 | 窗口句柄改存 `plugin.GUI_HANDLES["bridge_window"]`（`plugin` 模块**从不被重新执行**，随进程常驻）；autoload 模块体开头改读 `plugin.GUI_HANDLES.get("bridge_window")` 而非写死 `None`；`_ensure_window()` 建窗后立即回写 `GUI_HANDLES` |
| 效果 | 任意次 `bridge_doctor` 重载、`Auto Poll` 反复点，都复用**同一个**窗口，不再堆叠 |
| 测试 | 回归新增 `test_hot_reload_preserves_the_bridge_window`：用真实的 `exec(code, g)` 重载路径，断言重载前后 `namespace["_bridge_window"] is 同一对象` 且 `GUI_HANDLES` 仍指向它 |
| 断言 | 204 → **205**（含本条目） |
| 版本 | `1.0.2` → `1.0.3`（`__init__.py` 单一来源，`pyproject` 走 `dynamic`） |

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

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

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

| 项 | 内容 |
|---|---|
| 新增模块 | `api_doc.py`（306 行）：纯逻辑，无 FastMCP、import 无副作用，暴露 `search` / `lookup` / `list_modules` / `list_categories` |
| 新增工具（4） | `ansa_api_doc_search` · `ansa_api_doc_lookup` · `ansa_api_doc_modules` · `ansa_api_doc_categories`，全 `READ_ONLY` |
| 新增预检 | `validate_script` + `execute_script(validate=True)`（**默认开**）：解析脚本里每个 `ansa.<module>.<func>` / `<module>.<func>`，对照**活着的** build，返回缺失调用 |
| 事实来源 | `ansa_api_index.json`（5892 函数 / ANSA v25.1.4），三层检索：关键词（模块名·函数名加权）→ 描述+签名模糊 → txt 兜底 |

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

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

| 项 | 内容 |
|---|---|
| 现场 | `execute_script(validate=True)` 对一个引用了不存在函数的脚本，本应返回"缺哪些调用"，却抛 `TypeError` |
| 根因 | `ipc.error_response(...)` 的签名里**没有** `data` 关键字 |
| 修法 | `error_response` 增加可选 `data` 参数；拒绝现在返回结构化的 `data.missing` / `data.checked`，而不是在构造响应时崩掉 |

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

| 项 | 内容 |
|---|---|
| 动机 | 之前 `api_doc` 读的是 `ansa_tools` 包里的索引，单装本项目的人拿不到 |
| 修法 | 把 `ansa_api_index.json`（10.4 MB）放进 `src/ansa_mcp_sum/`，并在 `pyproject.toml` 的 `package-data` 里声明，随 wheel 一起分发 |
| 解析顺序 | `ANSA_API_INDEX_PATH` 环境变量 → 包内副本 → `ansa_tools` 资源（仅作向后兼容兜底） |

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

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

| 缺陷 | 根因 | 修法 |
|---|---|---|
| 窗口被销毁后，下一次 Auto Poll 解引用**悬空句柄** → 崩 | 用户点了桥窗口标题栏的**关闭 (X)**，窗口连同它的子定时器一起被销毁；而 25.x 没有 `guitk.BCDestroyWindow`，句柄变成悬空的 C++ 指针 | `_ensure_window()` 把标题栏的关闭按钮**隐藏**，用户再也关不掉这个窗口 |
| `guitk.BCTimerIsActive(保留的定时器句柄)` 在句柄悬空时崩 | 这同样是 native 调用，Python 层无法兜底 | `_init_bridge` **不再**对保留句柄调 `BCTimerIsActive`；定时器健康纯看 Python 侧的 `_last_tick_at` 心跳；停摆的定时器经 `_reset_bridge_refs` **只丢引用、绝不解引用**，再建一个新的 |

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

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

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

| # | 位置 | 症状 | 修法 |
|---|---|---|---|
| 1 | `regression_check.py` 版本断言 | 写死 `__version__ == "1.0.3"`，每次发版必假失败 | 改为"X.Y.Z 形态"（`re.fullmatch`），不再随版本漂 |
| 2 | `regression_check.py` 工具数 | `all 73 tools`，真实 78 | 改为 78，并注明这是**有意的计数跳线**（增删工具须同步改） |
| 3 | `bridge_doctor.py`（**真缺陷，非测试**） | 把 `_teardown_timer` 当"新代码已生效"的标记；v1.0.7 改名后 doctor **恒报** `code_is_current = False` | 抽成 `bridge_doctor.RELOAD_MARKER = "_reset_bridge_refs"` 单点声明，4 处引用统一 |
| 4 | `probe_mcp_sum_server.py` | 断言 `tools/list 返回 73 个工具`（模块 docstring 里也各有一处旧值） | 改为 78 |
| 5 | `audit_ansa_api_usage.py` | 3 个 ANSA 调用未登记（`unlisted: 3`）；纯模块 `api_doc.py` 未列入扫描 | 3 个 guitk 名字补进 `VERIFIED_API`；`api_doc.py` 加入 `SHIPPED` |

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

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

```bash
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_*` 临时探针）。它们全仓库零代码引用，
是"当时在真机上试过什么"的留档，不是运行路径。按"是否承载运行与门禁"清理：

| 层 | 数量 | 保留理由 |
|---|---|---|
| 运行 / 门禁依赖 | 9 | `autoload` 被 ANSA `ImportCode`；`probe_ansa_capabilities` 被 autoload 调；`mcp_cli` 被健康检查 `subprocess` 调；4 道门 |
| 被 shipped 代码引用 | 5 | `s2_diag / s3 / s4 / s5_midsurf / s6_verify` 写在 `knowledge.py` 里，是 `ansa://workflows` 资源的证据留档 —— 删了资源会引用幽灵文件 |

同时清掉 `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 还没做（按优先级）

| 批次 | 内容 | 为什么排后面 |
|---|---|---|
| ~~第二批~~ | ~~审计日志 · pitfalls/workflows resource · 跨会话记忆~~ | **已完成**（见 §10.15） |
| 第三批 | 路径白名单收口到 `send_command` · 能力清单接线裁工具 · 队列 FIFO · `runs/`+`results/` 回收 · 单实例锁 · 三道闸进 CI | 会改行为，需要真机回归 |
| 未排期 | 超时分级（查询 30 s / 检查 120 s / 网格 900 s） | **不能单独改**：`STALE_COMMAND_AGE_SECONDS` 是按 `timeout_seconds + 60` 算的，一旦单命令超时超过它，插件会先把命令当过期丢掉 —— 正是 §7.5 踩过的那个坑。要和 staleness 一起改 |
| 第三批 | `model_changed` 目前只比**文件路径** —— `mesh_shells` 把壳从 0 变成 65 908 时它仍是 `False`。要回答"模型变了吗"得比实体计数指纹 | 改的是审计语义，要真机跑一遍改模型的操作才知道指纹够不够便宜 |
| 第三批 | 单实例锁 | **不再是理论风险**：现场实测有**两个** `ansa_mcp_sum.server` 进程跑在同一个 HOME 上 |
| 未排期 | `get_entity` 的 `fields` 默认值 | §7.6 的崩溃路径是"不传字段元组"，而工具签名里 `fields=None` 仍是默认。要么改成必填，要么在插件侧强制补一套语义字段 —— 需要真机验证补哪一套是对的 |

---

## 9. 排错

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

```bash
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`。

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

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

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