Qiao-MCP — Bridge Engineering (桥梁工程)

🌉 Qiao-MCP

English · 简体中文

桥梁全生命周期结构分析——建模、施工阶段、规范验算
桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算

Qiao-MCP 是一个 Model Context Protocol (MCP) 服务器，可让 AI 助手与桥梁结构分析软件交互。它提供用于创建桥梁模型、施加荷载、运行结构分析和检查结果的工具。

功能

🔧 工具（15 个领域入口，153 项操作）

0.6.0 版本提供 15 个领域工具。每个工具接受包含 operation 选择器及相应字段的 request；其架构包含每项操作的完整参数说明、默认值和约束。所有 153 个旧版名称仍可使用原始参数直接调用。

领域工具	范围
inspect_bridge	连接、模型状态和编辑就绪情况
manage_model_files	打开、保存和初始化项目
query_model	定义、实体搜索和几何检查
edit_geometry	节点、单元和桥梁布局
edit_properties	材料、截面、厚度和时变效应
edit_boundaries	地基支座、节点连接和梁端释放
edit_construction	组、阶段、激活和停用
edit_loads	静力工况、组合和物理荷载
analyze_model	求解器设置、动力分析和结构分析
edit_prestress	钢束属性、几何和预应力
edit_traffic	移动荷载、横向荷载和国际活荷载
manage_checks	模型检查快照和当前规范验算上下文
query_results	结构、模态、活荷载和钢束结果
view_model	显示设置、阶段视图、截图和绘图
access_backend	原生方法发现和长尾 API 调用

例如，向 inspect_bridge 发送 {"request":{"operation":"get_model_status"}}。请参阅请求示例和兼容性。 将 QIAO_MCP_CATALOG_LAYOUT=flat 设置为列出原始的 153 个名称。 0.5.1 版本默认使用扁平目录。

151 项非图像操作保留其输出架构和 MCP 结构化内容 （{status, message, ...}）。连接诊断还会公开 connection_status 和 connected；桥梁模板会返回解析后的节点、单元和属性 ID。 get_model_status 会在 status 中保留 QiaoTong 的状态。两个支持图像的工具会返回可查看的 MCP 图像内容或文本摘要。在领域层级，14 个入口发布组合输出架构；view_model 支持混合图像/文本内容。 工具失败会使用带类型的 MCP 错误；只读、破坏性和开放世界操作带有 MCP 工具注释。 服务器说明包含完整的工具分组概览；通过网关调用尚未覆盖的后端方法之前，请先使用 list_qtmodel_api。

输入架构包含参数说明、封闭集合选择器、分页范围以及固定长度的坐标/DOF 数组。无效的架构输入会在调用后端之前被拒绝。梁端 release_i / release_j 标志表示 True = 释放； 省略某一端时，该端的所有六个 DOF 均保持连接。荷载组合分量使用 [case_type, case_name, factor]；包络组合使用 combine_type=3。

支座覆盖设置会保留未提供的坐标/附加设置。提供 extra_parameters 会启用这些设置，除非显式设置 extra_enabled=False 将其清除；此行为同样适用于支持这些选项的旧版 SDK。

0.6.0：领域工具与 qtmodel 2.9.3

0.6.0 版整合了自 GitHub 发布 0.5.1 以来本地版本 0.5.2–0.5.9 的改进。 该版本保留全部 153 个操作和旧版调用，并通过 15 个领域入口提供这些功能， 其中包括变更日志中列出的各工具修正。 请参阅发布与升级说明。 现在，创建/删除截面、删除阶段以及竖向预应力检查都会说明其前置条件、 选择边界和写入行为。 add_custom_temperature 接受原生的 [reference, height, temperature] 行 （reference 1=顶部，2=底部；orientation 1=局部 Z，2=局部 Y）。不接受两值行， 因为它们缺少 reference。修改操作的选择不接受空白、布尔值和小数形式的 ID；重新编号 必须同时提供两份完整列表，或同时省略两份列表以明确对整个模型重新编号。

现在，截图和图表会获取 PNG 字节，以便存储在 MCP 主机上。部分更新要求读取回的数据 唯一且完整；检查查询会保留类型化字段。 活载结果会提供 envelope_type=1（最大值）或 2（最小值）。有关求解器、截面编号、 分组查询和理想化支持的修正，请参阅变更日志。

锁定安装现在使用 qtmodel 2.9.3。借助其实例上下文，以及声明 model_instance_guard=1 的桌面应用，修改和提交都会携带相同的模型实例标识符， 包括分析工作线程。网关的 undo_model 在 model_revision_schema=1 时也会检查模型/ 历史版本；有待处理或状态不确定的编辑会阻止该撤销操作。如果版本不匹配，请先检查 当前模型和命令历史，再决定是否发出其他操作。较旧协议保留现有状态检查。 初始化/打开操作和旧版原始路径文件路由仍遵循原有约定，无法携带此新绑定； 该绑定不提供事务回滚，也不会将不同的客户端请求绑定为一个经审核的计划。

选择操作

完整的 Args 文本已发布在参数架构中；每个领域都列出了其接受的操作。请选择与预期效果 相匹配的操作。

使用 update_node 进行节点绝对位置编辑，使用 move_nodes 设置偏移，使用 update_node_id/renumber_nodes 修改编号。对于截面， calc_section_property 用于评估提供的几何数据，get_model_data 用于读取已存储的 属性，而 calculate_section_property 会重写所有现有截面。 预应力筋定义、计算得到的损失和坐标分别使用不同的查询工具。 自动自重由阶段控制，而不是通过创建名为自重的工况来控制。

请参阅领域边界，了解每项任务对应的入口。

0.5.0：查询、横向分析、检查快照与国际荷载

此版本通过 20 个新工具和一个工作流提示词实现了 B1–B4。 它包含自 0.3.3 以来的所有更改，包括此前标记为 0.4.0 的工作。 请参阅发布说明 以及从 0.3.3 升级。 新命令需要受支持的 QiaoTong 构建版本。实时测试确认了基本静力计算和部分 B1 支持； 请参阅已知后端限制。

get_model_edit_readiness 是只读的，即使模型操作被阻止，仍可访问。其 success 状态表示已收到响应，并不表示可以安全编辑；请检查原始的 readiness 对象。不会保留/复用令牌，也不会更改任何阶段/结果。

query_model_data 接受类型化的 request，例如：

{"request": {"kind": "nodes", "structure_group_names": ["MainGirder"], "limit": 20, "offset": 0}}

类型：nodes、elements、boundaries、loads、node_local_axes、 section_summaries。名称是列表；ID 必须是正整数或整数列表，不能是范围字符串。查询节点至少需要一个筛选条件；near 和 tolerance 必须成对提供。Qiao-MCP 将筛选列表和分页上限设为 500；截面摘要仅允许提供 100 个显式 ID，且每页最多 100 项。结构化的 data 字段会保留原生分页元数据，不会重新计算总数或再次切片。不支持的端点会明确报错，而不会下载所有数据后再进行本地筛选。

get_model_data 还支持 material_summaries、material_detail、load_case_summaries、load_case_detail、load_combination_summaries、load_combination_detail、construction_stage_summaries、element_section 和 spans。新的详情类型在 ids 中使用一个正整数（或仅含一个整数的列表）；element_section 使用 position=0|1。荷载工况和组合详情的分页在服务端执行；其他列表类型保留原有的文本分页方式。摘要不是完整的可写回快照，施工阶段 ID 按阶段顺序排列。

configure_live_load_system 会明确选择五种活荷载体系之一；清除旧定义时，默认值为关闭。configure_operation_stage 要求提供全部四个工况列表；[] 会禁用对应类别。这些工具只会提交设置，不会运行分析。

横向定义使用 set_transversal_vehicle / set_transversal_lane，并提供完整的类型化 request 和 action="add"|"update"。这两个工具都可以替换现有定义。请先选择 china_transversal。无论显示单位如何，荷载均使用 kN，长度均使用 m。车道节点保留输入顺序，且必须由梁单元直接连接；distribution_widths 的单位为米。引用时请使用返回的 data.index 或 get_transversal_data。读回数据会保留原生车道字段 load_factors；编辑时请将其映射到 distribution_widths。

set_transversal_case 会验证所引用的车辆和车道 ID，并接受适用于 1..N 条车道的正数 reduction_factors，以及适用于超过 N 条车道的 greater_lane_factor。remove_transversal_data 必须指定明确的目标；删除车辆或车道时，cascade=False 为默认值。删除工况不接受 cascade。必须先显式移除组合和施工阶段中的引用。

基本模型的配筋使用 set_section_reinforcement 和完整的 UI 导出快照，或使用 remove_section_reinforcement 和明确的完整截面标识符（1、1-I、1-J、G7-2）。快照中的每个字段都是必填项；空数组会清除对应部分。六项外层/内层行与模型长度单位不同于旧版参数化工具。当前 CSAN 查询并非无损模型快照。新工具需要模型写入权限，且只会提交一次。

set_check_stirrup_snapshot 会保留完整的导出定义，并接受用于重新编号的 original_id。set_element_stirrups 可分别替换完整的剪力（五项）和扭转（三项）赋值：null 表示保留该类别，[] 表示清除该类别，箍筋 ID 0 表示未分配。这些工具与旧版当前 CSAN 箍筋工具相互独立。

manage_check_material 可设置完整的导出覆盖项，或将明确指定的 ID 重置为其基础材料。manage_check_case_definition 可使用原生枚举值设置/移除混凝土、抗震和加固模型定义。现有的 run_concrete_check 会在这些提交后导入指定的混凝土工况；它不会运行抗震或加固校核。请保留完整的导出材料属性/参数和存储单位，不要构造不完整的快照。

报告的失败、取消或其他非成功完成状态均属于工具错误，包括在旧版 SDK 的等待器返回这些状态而不抛出异常时。 国际车辆使用 set_international_vehicle，其 request 根据 standard="AASHTO"|"BS"|"EN1991" 进行区分。请先选择匹配的模型 系统。parameters 和 load_items 必须显式提供，即使值为 {}/[] 也不例外。 添加和更新都会替换定义；省略或为 null 的标量采用新定义的默认值。更新时通过原名称定位，并保留其实际 ID/引用。 写入仅提交一次，并返回按精确名称读取的定义。

标准	原生单位和约定
AASHTO	轴重 [N, m]，w 为 N/m，长度为 m，r 为百分比（90 = 90%）
BS	pa/pb 为 kN，w3 为 kN/m，长度为 m；w1/w2 为公式系数，指数无量纲
EN1991	轴重 [kN, m]，均布荷载为 kN/m，集中荷载为 kN，长度为 m；加载长度与间距是不同的参数

SDK 未指定 BS 轴力单位。请原样使用经验证的 BS 原生轴力导出/查询值；不要根据其他标准推断其单位。 get_international_live_load_data(kind="vehicles"|"cases") 会保留完整的原生字段；筛选和分页在其原生完整列表响应上本地执行。车辆导出可能包含适用于其他标准的非活动参数： 请为类型化工具选择文档规定的字段，或使用现有网关重放未更改的完整原生定义。不会进行全局单位转换。

create_en1991_vehicle 通过显式名称选择原生 source="standard"|"user" 工厂。 标准车辆仅公开有效的工厂控制项；其代码生成的均布荷载/长度/间距不可覆盖。用户车辆保留这些字段以及 p/dis、load_length、num 和 point_load；当 p/dis 均为 null 时，LM71 使用四个 250 kN 轴重。 工厂写入也会读回实际车辆 ID。例如，选择 en1991 后：

{"request": {"source": "standard", "name": "LM71", "load_type": "LM71"}}

set_planned_lane 要求提供平面、参考双轴、宽度、车辆数量、 有符号偏移量和方向。它使用独立端点，与 add_traffic_lane(optimize=True) 不同。没有单独的计划车道读取器； 其响应确认提交已完成，模型导出/UI 检查可验证定义。 通过网关删除时，必须向 remove_lane_line 传入 lane_kind="planned"。

set_international_live_load_case 会在写入前检查每辆车的精确名称和预期的 standard。 子工况通过 optimized=False|True 选择普通/计划车道；EN1991 会拒绝重复的车道分配。QiaoTong 会检查车道是否存在、车道类型以及其是否属于影响面。系数对象使用完整的原生字段名称和值；null 表示使用服务器默认值，更新时也一样。请使用 configure_operation_stage 显式配置 live_load_cases，然后使用 run_analysis 和 get_analysis_results(case_name_mode="full")，并传入经 QiaoTong 验证的结果标识符。 定义不会启动分析。仍可通过现有网关中的 remove_international_vehicle 和 remove_live_load_case 删除车辆/工况。

0.5.0 还通过现有网关跟踪上游 0687ffe， 支持质量/刚度系数、翼缘/有效宽度定义、统计信息和结构合并。模型重量查询固定使用 N，与显示单位无关。

📦 资源（7 项资源）

URI	描述
bridge://model/summary	模型概览
bridge://model/materials	材料列表
bridge://model/sections	截面列表
bridge://model/load-cases	荷载工况
bridge://model/stages	施工阶段
bridge://model/structure-groups	结构组
bridge://model/boundaries	边界条件

💬 提示词（5 个工作流）

提示词	描述
design_simple_beam	简支梁设计工作流（简支梁设计）
design_continuous_beam	连续梁桥设计（连续梁设计）
check_structure	结构规范检算（结构检算）
construction_stage_analysis	施工阶段分析（施工阶段分析）
analyze_transversal	显式横向定义、配置、求解及经验证的结果标识符

对于普通静力工况，get_analysis_results 会保留自动添加的 ST: 前缀。对于其他结果系列，请使用 case_name_mode="full"，并填写通过 QiaoTong 结果/UI 验证的完整标识符。该值会原样传递；TV/MV 组合代码不能作为结果端点命名规则的依据。

架构

qiao-mcp/
├── src/qiao_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/                 # MCP Tools (envelope-wrapped)
│   ├── resources/             # MCP Resources
│   ├── prompts/               # MCP Prompts
│   └── providers/             # Backend adapters
│       ├── __init__.py        # BridgeProvider abstract base
│       └── qtmodel_provider.py  # QiaoTong adapter
├── tests/                     # Offline unit, integration, and API contract tests
└── reference-docs/            # Local reference material (not committed)

Provider 模式使 153 个操作与任何单一后端解耦。通过 BRIDGE_PROVIDER 选择一个后端；每个 Provider 都会声明自己的软件专属规则，因此 LLM 无需更改提示词即可适配。目前支持：

• QTModel（qtmodel，默认）— 桥梁分析软件 QiaoTong（桥通）（用户手册）

添加后端只需实现 BridgeProvider 并注册一行代码，无需更改工具层。请参阅后端选择。

快速开始

前置条件

• Python >= 3.11
• uv 包管理器
• qtmodel 2.6.3 – 2.9.x，但不包括 2.9.0（由 uv sync 安装；当前锁定版本为 2.9.3）
• 调用后端模型、分析或可视化操作时，QiaoTong 软件必须处于运行状态 （各版本的兼容关系请参阅兼容性）

MCP 服务无需 QiaoTong 即可启动。使用 check_qiaotong_connection 区分服务已连接和软件未运行的情况，并使用 get_model_status 查看模型是否已打开，以及当前 QiaoTong 状态允许执行哪些操作。

安装与运行

# Install dependencies
uv sync

# Run the server
uv run qiao-mcp

在 Claude Desktop 中配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "qiao-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/qiao-mcp", "run", "qiao-mcp"]
    }
  }
}

在 Cursor 中配置

将以下内容添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "qiao-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/qiao-mcp", "run", "qiao-mcp"]
    }
  }
}

在 Reasonix（UI）中配置

打开设置 → MCP 与工具，然后添加新的 MCP 服务：

• 名称：qiao-mcp
• 传输方式：stdio（保持默认值）
• 命令：uv --directory /path/to/qiao-mcp run qiao-mcp
  • 将 /path/to/qiao-mcp 替换为实际的项目路径
  • Windows：使用反斜杠 D:\path\to\qiao-mcp
  • macOS/Linux：使用正斜杠 /path/to/qiao-mcp
• 环境变量（可选）：UV_PYTHON=3.11

点击添加以保存。

在 Cherry Studio（UI）中配置

打开设置 → 扩展 → MCP Servers，然后添加新的服务：

• 名称（Name）：qiao-mcp
• 描述（Description）：可选描述
• 类型（Type）：标准输入 / 输出 (stdio)
• 命令（Command）：uv
• 包管理器（Package Manager）：选择 默认（Default）
• 参数（Args）：

  /path/to/qiao-mcp
  run
  qiao-mcp
  

  （每行是一个参数，无需添加 --directory 前缀）
  • 将 /path/to/qiao-mcp 替换为实际的项目路径

点击保存以保存。

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector uv run qiao-mcp

局域网调试代理

用于跨机器调试的 scripts/qiaotong_lan_proxy.py 会将面向局域网的端口转发到同一台机器上的 QiaoTong API。代理使用 45125，并将请求转发到选定的 QiaoTong 进程的 127.0.0.1:55125：

python scripts/qiaotong_lan_proxy.py

然后将客户端机器指向：

from qtmodel import mdb

mdb.set_url("http://<proxy-machine-LAN-IP>:45125/pythonForQt/")

代理会打印每个转发的请求和响应。若同时运行多个 QiaoTong 进程，请让一个进程使用 55125 端口以供此固定代理转发，或为不同进程使用 独立的代理实例和端口。

也可以使用 SSH 隧道，这样无需在局域网上公开 API 端口：

ssh -N -L 45125:127.0.0.1:55125 <user>@<qiaotong-machine-LAN-IP>

隧道运行期间，请在客户端机器上使用 http://localhost:45125/pythonForQt/。在此配置下，Windows HTTP.sys 会验证 Host 标头，并以 400 Invalid Hostname 拒绝 127.0.0.1。

开发

# Install in dev mode (includes ruff, mypy, pytest)
uv sync

# Run directly
uv run python -m qiao_mcp.server

# Quality checks and offline regression tests
uv run ruff check src/ tests/
uv run mypy src/qiao_mcp/
uv run pytest tests/ --ignore=tests/test_end_to_end.py -q

上述命令可离线运行，不需要 QiaoTong 软件。 Provider/工具调用会根据已安装的 qtmodel API 签名进行验证 （契约测试），并通过进程内的模拟后端执行。 被排除的端到端测试需要一个可随时销毁的 QiaoTong 模型：它会在求解前清空并 重建当前模型。

后端：QTModel（桥通）

此 MCP 服务封装了 qtmodel Python API，该 API 提供以下访问能力：

• mdb — 模型数据库：查询、构建和修改桥梁模型
• odb — 输出数据库：查询分析结果并进行可视化
• cdb — 检查数据库：结构验证与规范检查

版本管理

Qiao-MCP 的版本独立于 qtmodel：项目会自行迭代（修复错误、新增工具、完善文档）， 无需等待后端发布；后端发布也不会强制要求此处升级版本。后端要求在其所属位置 通过依赖约束表达。

兼容性

Qiao-MCP	qtmodel	QiaoTong 软件
0.6.0	2.6.3 – 2.9.x，但不包括 2.9.0	后端要求相同；提供 15 个领域工具，涵盖全部 153 个旧版操作
0.5.1	2.6.3 – 2.9.x，但不包括 2.9.0	对于 2.9.x，QiaoTong 必须报告模型状态；新命令需要服务端支持
0.5.0	2.6.3 – 2.9.x，但不包括 2.9.0	对于 2.9.x，QiaoTong 必须报告模型状态；新命令需要服务端支持
0.3.2 – 0.3.3	2.6.3 – 2.8.x	2.6.3+；不再固定 2.8.x 配对版本
0.3.0 – 0.3.1	2.6.3 – 2.6.x	2.6.3（由 qtmodel 强制精确匹配）
0.2.x	2.5.0 – 2.5.x	2.5.0

已知的最低版本限制：qtmodel 2.6.3 缺少 get_load_group_names，因此单次调用的桥梁工作流工具无法在此版本上运行。这是现有的限制；这些工作流请使用 2.6.4 或更高版本（仍不包括 2.9.0）。 依赖版本范围并不保证每个版本构建都支持所有新工具：如果缺少方法或参数不兼容，会在写入前明确报错。离线测试套件针对 PyPI 版本 2.6.3、2.6.4、2.8.2、2.9.1、2.9.2 和 2.9.3，以及参考版本 0687ffe 运行。 这些测试用于验证软件契约；完整的工程验收仍待完成。 qtmodel 2.9.3 会明确拒绝历史检查快照和计划车道的添加/更新路由，并返回 API_NOT_OPEN； SDK 目录中存在某个方法，并不能证明桌面端存在对应路由。

两端的匹配方式在 qtmodel 2.8.2 中发生了变化：

• qtmodel 2.6 / 2.7 执行严格的版本握手——QiaoTong API 版本必须与已安装的 qtmodel 完全匹配，否则 check_qiaotong_connection 会报告 version_mismatch 并拒绝连接。
• qtmodel 2.8.2 移除了该握手。只要 QiaoTong 提供 Python API，就可以连接，因此不再出现 version_mismatch。代价是较旧的 QiaoTong 可能缺少较新的命令；get_model_status 会将此情况标记为 state_unknown（该软件早于模型状态握手）， 使工具以安全失败的方式停止，而不是盲目写入。

不同构建版本报告的 qtmodel 2.8.2 并不一致：PyPI wheel（2026-08-20）不包含 QtServer.get_model_state，而同一版本的上游源码包含此方法。 Qiao-MCP 会检测功能，而非版本——缺少此方法时会跳过 模型状态防护（guard_unavailable），工具的行为与 0.3.1 相同； 具备此方法时，每个工具都会受 QiaoTong 报告的状态约束。qtmodel 2.9.0 是首个包含此方法的 PyPI 版本，因此在 2.9.x 上始终会启用防护。

实测后端限制

2026-10-12 的实测使用了 QiaoTong 26.1.116.1010 和 qtmodel 2.9.2。 一个独立悬臂模型通过了反力、弯矩和平移检查； 端部位移与包含剪切的手算结果相差约 0.00125%。 同一次测试也确认了以下后端限制：

• GET-DEFORMATION 返回错误的 rz，在测试案例中该值等于 ry。 求解器数据库包含正确的 Rz。请勿依赖此版本 API 返回的 Rz；Qiao-MCP 不会臆造替代值。
• configure_live_load_system 因 未知参数：clear_existing 而被拒绝。 横向工作流在系统选择步骤停止。国际工作流有相同的前置条件，因此未运行；本次测试未确认各个国际接口不受支持。
• SET-SECTION-REINFORCEMENT、SET-CHECK-STIRRUP 和 SET-CHECK-CASE 被拒绝为未知命令。完整的配筋/检查快照能否被接受仍待确认。

connected 或 compatible 并不能证明这些功能可用。请使用支持这些功能的 QiaoTong 版本，并在一次性模型上验证。 BS 轴力单位在上游仍未确认。

从 0.3.3 升级

0.5.0 对 add_nodal_mass 做了不兼容修正：

• 对 X、Y 和 Z 方向指定相同的平动质量时使用 mass，例如 {"node_id": 1, "mass": 10}。可选的 mass_x/mass_y/mass_z 可覆盖 各个方向；未指定的方向使用 mass，其默认值为零。
• 已移除 mass_rm。请使用 rot_x、rot_y 或 rot_z 指定目标转动惯量轴；不要直接机械地重命名旧参数。
• 不同方向的质量需要支持 mass_xyz 的 SDK（受支持的 PyPI 2.9 版本为 2.9.1 和 2.9.2）。旧版本会在写入前拒绝这些参数。

早期版本会将部分平动质量参数写入转动字段。 升级软件包不会修复现有模型：请读取此前写入的节点质量，并核对其是否符合预期工程值。 另请查看更新日志，了解更严格的徐变/材料校验、非整数阶段时长以及上述模型状态要求。

与上游 qtmodel 2.9 对齐

当前参考版本为 0687ffe，标记为 2.9.2，但与 PyPI 上的 2.9.2 wheel 不同。更早的本地基线是 8ae651e，其软件包与该 wheel 相符，只有版本标记较旧。

• 写入安全性。 如果写入操作的回复丢失，会引发 CommandOutcomeUnknownError，且不再重发。Qiao-MCP 会将其报告为结果未知，并告知客户端在执行其他操作前先读取模型。
• 客户端验证。 现在许多写入操作会在发送前拒绝格式错误的值。Qiao-MCP 的架构与此一致：蠕变／收缩曲线不能为空；截面属性表必须包含 26 或 29 个值；蠕变参数数量必须符合对应代码的要求；自定义材料必须提供 data_info。
• 节点质量布局。 add_nodal_mass 将 mass_info 说明为 (mass, inertia X, Y, Z)，并新增了用于指定方向质量的 mass_xyz。Qiao-MCP 现在会按该布局发送（更正后的字段见变更日志）。
• 现有工具新增参数。 施工阶段支持小数时长和 sub_steps；create_material 新增 is_orthotropic / ey；set_support 和 add_elastic_support 新增 coordinate、extra_enabled 和包含 8 个值的 extra_parameters。单向弹性支座也接受带符号的 axis_direction。add_influence_plane 新增 always_divided_by_beam_shape，create_live_load_case 新增了按子工况设置的布尔值列表 sub_case_optimized。省略选项时保持旧行为；显式指定的选项会在写入前根据已安装版本的签名进行检查。在会截断小数阶段时长的版本中，会拒绝创建小数阶段。这些新增功能包含在 0.5.0 中；其工具目录包含 153 个工具。
• 操作设置与级联删除。 configure_operation_stage 提供全部 4 个工况列表，包括横向工况。网关方法 update_operation_stage_setting 仍可使用；请提供所有预期的工况列表，因为省略列表或提供空列表都会禁用相应分析。 remove_material 默认使用 cascade=True（也会删除关联的索属性和索）。remove_tendon_property 默认使用 False；设为 True 时会在不弹出对话框的情况下删除引用该属性的索及其荷载。请先确认删除范围；省略名称和索引时会将所有对象作为目标。
• 专用工具与长尾 API。 0.5.0 新增了横向、国际／规划车道、钢筋／检查快照以及编辑就绪状态专用工具。精确对象删除（delete_model_object）、系数、有效宽度、统计信息和结构合并仍可通过网关使用。所有 MDB 写入以及显式 CDB 模型快照方法都会通过 update_model 提交。
• 网关中已屏蔽。 post_python_file（读取本地文件并将其发送到任意 URL 执行）、prepare_model_edit（可能不可逆地删除结果；需在用户批准后供宿主应用程序使用）、export_api_help（将 SDK 帮助写入任意本地路径），以及原有的 ensure_running、set_url、set_version、export_qt_helper 和 wait_solve（无限期轮询；请使用 run_analysis）。

上游源代码变更（2026-09-04–08）

这些变更首次同步于 2316654，当时仍标记为 2.8.2，现属于 2.9.0：

• ac4dbad 将模型查询从 odb 移至 mdb。Qiao-MCP 优先使用新的命名空间，若方法不存在则回退到 odb。现有模型的截面几何使用 mdb.get_model_section_shape；mdb.get_section_shape 仍用作本地几何构建器。分析结果和视图仍使用 odb。
• bc1ee99 返回支持 to_dict() 和 Mapping 的类型化模型记录。Provider 会递归地将其转换为纯 JSON 数据，供工具、资源和 API 网关使用，同时保留服务器原始字段。MDB 查询调用使用读取权限，而非模型写入权限，且不会刷新模型。calculate_section_property 等状态变更调用仍需要模型写入权限。
• 6821413 将模型对象拆分到各领域模块，并保留 core.model_db 作为兼容性导出。适配器不依赖这些内部路径。
• 9 月 7–8 日的更新为厚度定义添加了 t_out，为求解添加了 show_view，新增了十二个分析设置重置 API 和三个批量厚度 API。Qiao-MCP 在现有工具上公开了这两个新选项；十五个管理 API 可通过先发现再调用的网关使用。

**构建兼容性：**这些选项和管理 API 已包含在 PyPI 2.9.x 版本中；PyPI 2.8.2 构建（8 月 20 日）不包含它们。默认工具调用在两种版本上均可正常工作；如果安装的 API 不接受显式传入的 t_out 或 show_view=True 请求，请求会在写入或开始求解前失败。版本标签相同并不能证明支持这些功能。

使用支持这些功能的 qtmodel 构建的 MCP 工具调用示例：

add_thickness(name="Deck", t=0.20, t_out=0.30, thick_type=0)
run_analysis(read_timeout=3600, show_view=True)
list_qtmodel_api(api_object="mdb", pattern="thickness")
call_qtmodel_api(api_object="mdb", method="copy_thicknesses", kwargs={"ids": [1, 2]})
list_qtmodel_api(api_object="mdb", pattern="reset_")

thick_type 表示 0 = 普通板，1 = 肋板，而非面内和面外厚度相等/不等。省略 t_out 时，t 会同时用于两者。show_view 仅控制 QiaoTong 进度窗口：求解仍使用后台执行、轮询和 MCP 进度心跳。

批量厚度 API 接受正整数 ID 或列表，不接受范围字符串。remove_thicknesses([]) 不会删除任何内容。分析重置会删除设置，而 arrange_thickness_ids 会更改 ID 和引用；调用这些写入 API 前，请先发现预期的方法并确认预期的更改。

如需在不替换已安装软件包的情况下测试参考源（macOS/Linux）：

PYTHONPATH=reference_codes/qtmodel-release/packages/qtmodel/src:src uv run pytest tests/ --ignore=tests/test_end_to_end.py -q

0.x 表示 API 仍可能发生变化；这并不代表发布质量。迁移到新的 qtmodel 次版本系列时，请提高依赖版本下限，并在上表中添加一行。

许可证

版权所有 2026 Sorata（https://github.com/SorataYang）

依据 Apache License 2.0 版授权。请参阅 LICENSE。 其他署名声明见 NOTICE。