qiaotong-agent-kit

桥通有限元软件的 Agent 工具适配层。该包与 qtmodel 独立发行：工程模型、 截面几何和截面特性算法仍由 qtmodel 提供，本包只负责为 Agent 暴露稳定、 可发现、JSON 可序列化的受控工具。

MCP 总功能介绍

默认的 qiaotong-mcp / qiaotong-model-mcp 面向当前打开的桥通模型，提供46个工具， 覆盖以下能力：

• 自动发现桥通动态HTTP端口并核对桥通、qtmodel和Agent Kit版本；
• 查询工程信息、轻量模型摘要、检算上下文和截面完整语义；
• 按条件分页查询节点、梁杆索板单元、节点局部坐标系、材料、板厚、边界约束及荷载；
• 查询施工阶段、结构组、荷载工况、荷载组合、分析上下文和求解状态；
• 通过 Schema → Plan → Commit 协议执行最多100步批量建模，支持65种节点、材料、板厚、 单元、边界、局部坐标系、荷载及参数截面的原子或语义级 operation；
• 直接修改当前模型，整批形成一条桥通原生可撤销命令，失败自动Undo，不创建文件快照；
• 启动模型求解，读取位移、内力、应力、反力及报告兼容图表数据；
• 经明确确认后，使用当前Agent Kit解释器在独立子进程中执行Python脚本，可直接调用qtmodel；
• 经明确确认后，将包含完整计算书API说明的Python脚本导出到当前工程计算书目录，供大模型结合用户DOCX生成定制编辑脚本； 脚本可修改模型、文件或访问网络，不保证统一撤回；stdout/stderr完整返回，运行时长受限。

qiaotong-readonly-mcp 提供41个只读/规划工具；all 模式共64个工具，额外提供本地截面 计算、DXF截面导入、规则证据检索和qtmodel API契约校验。调用 get_capabilities 可取得由 当前工具目录动态生成的功能分组、运行模式、全部受控operation和安全策略。

安装

pip install qiaotong-agent-kit

如需 MCP stdio 服务：

pip install "qiaotong-agent-kit[mcp]"
qiaotong-mcp

客户端连接后应先调用 get_connection_status。该工具会在桥通使用的 55125-55585 端口范围内自动发现 HTTP 服务，并核对桥通 API、qtmodel 和 Agent Kit 版本；桥通未启动时会返回可操作的状态而不是抛出连接异常。特殊部署可通过 环境变量 QIAOTONG_HTTP_URL 显式指定地址。

qiaotong-agent-kit 0.18.x 明确适配 qtmodel>=2.6.3,<2.7.0。 安装包会由 pip 自动解析这一兼容范围，并内置脱敏后的桥型规则和匿名参考证据； 不需要复制开发机上的 qtmodels 目录，也不会发布原始模型脚本、模型名或文件路径。 如果环境中已有不兼容版本，pip 会升级/降级到受支持的 2.6.x；被强制装入不兼容 qtmodel 时，Agent 服务会给出明确的版本错误而不是继续建模。

Python 调用

from qiaotong_agent_kit import SectionToolService

service = SectionToolService()
result = service.invoke("calculate_parameter_section_property", {
    "sec_type": "矩形",
    "sec_info": {"w": 2.0, "h": 1.0},
})
print(result["property"]["Ax"])

JSON-lines 子进程协议

qiaotong-agent-kit list-tools
qiaotong-agent-kit serve

serve 从标准输入逐行接收：

{"id": 1, "tool": "calculate_parameter_section_property", "arguments": {"sec_type": "矩形", "sec_info": {"w": 2, "h": 1}}}

并逐行返回：

{"id": 1, "ok": true, "result": {}}

本地截面计算不需要打开桥通。读取、审查、求解和恢复工具会连接桥通 HTTP 服务。

DXF 创建桥通截面

QPyIDE 先将用户打开的 DXF 暂存为 SHA-256 source_handle。Agent Kit 不接受任意文件路径， 只读取 QIAOTONG_AGENT_RUNTIME_ROOT/imports 中摘要匹配的 DXF。推荐调用顺序：

1. inspect_cad_section：解析单位、线段/圆弧、闭环、孔洞和薄壁厚度，生成 SectionIR 与本地截面特性；
2. prepare_cad_section_import：绑定目标截面编号、模型 revision 和写入前快照；
3. QPyIDE 展示清洗项、属性和警告，并取得一次性用户审批；
4. commit_cad_section_import：原样提交计划凭证，写入后回读校验，失败自动恢复快照；
5. verify_cad_section_import：需要时再次执行独立只读核验。

DXF 未声明单位、普通 LINE 没有薄壁厚度或目标编号冲突时返回 needs_input，不会猜测。 当前支持 LINE、LWPOLYLINE、POLYLINE、ARC 与 CIRCLE；所有 SectionIR 坐标和厚度统一为 m。

脱敏参考规则库

Agent 应先查询规则，再生成建模计划：

from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()
catalog = service.invoke("get_modeling_rule_catalog")
rule = service.invoke("get_modeling_rule", {"bridge_type": "连续梁桥"})
evidence = service.invoke("search_reference_evidence", {
    "bridge_type": "连续梁桥",
    "spans": "30+40+30",
    "standard": "JTG D60-2015",
    "limit": 3,
})

规则资源随 wheel 发布，包含十类桥型的建模规则和 62 个匿名参考记录的技术统计。 参考结果只用于归纳结构、阶段和荷载规律；其中不包含原始 build_model.py，也不允许 从匿名编号反推项目或桥梁名称。

在 QpyIDE 中配置 MCP

推荐把只读与建模能力拆成两个 MCP 入口：

qiaotong-readonly-mcp  # 截面语义、模型摘要、审查和结果查询
qiaotong-model-mcp     # 当前模型原位/批量修改、原生撤回、求解和结果查询

默认 MCP 只发布连接、节点/截面语义、统一批量修改、原生撤回、模型摘要、求解和结果查询。 截面复制、截面变换、CAD 截面导入和连续梁建模不再发布为 MCP 工具。

混凝土箱梁原位修改支持 桥面总宽(b)、梁高(H) 和 箱室个数(n)；修改 b 时会保持左右半幅各段 B0 的比例并整体缩放到目标总宽。

所有受控模型写入统一使用 plan_bridge_model_batch 提交完整操作数组；修改一个对象时也 提交只包含一个 operation 的批次。当前每批支持 1–100 个已注册 operation，包括参数截面、 节点、材料、板厚、四类单元、阶段 4 的边界/约束、阶段 5 的节点/单元荷载创建和修改，以及 阶段 6 的显式删除。同一单一截面只能出现一次；变截面可分别包含 一个 end=I 和一个 end=J 操作，同一端的多个参数应合并到同一操作。规划阶段完全只读， 不保存 BFMD 快照，也不切换当前工程文件；计划会在 MCP 进程内缓存30分钟，用户确认后只需将 plan_id、model_revision 和 confirm_commit=true 交给 commit_bridge_model_batch；旧调用仍可 重复提交原操作数组。服务先解析批内引用和依赖关系，再按 稳定拓扑顺序基于最新模型状态重新生成每一步写入参数并逐项回读。整批修改直接作用于当前 模型，并只向桥通 CommandManager 提交一条原生复合命令；任一步失败都会自动 Undo，不保留 半完成状态。提交成功会返回 undo_transaction，仅当它仍是当前模型的最新改动时，才可经 undo_bridge_model_transaction 一次撤回整批操作，撤回过程同样不会打开或替换工程文件。 计划和提交默认使用 response_detail=summary，只返回计数、最多5项计划预览、验证摘要和撤回 凭证，不回显逐项 source/target/changes/write_result；诊断时可显式使用 response_detail=full 取得旧版逐项明细。

批事务通过 operation 注册表扩展。每种操作分别注册精确 JSON Schema、规范化、规划、 执行和回读验证。为兼容 WorkBuddy 等会在 stdio 之前预校验参数的 MCP 宿主，tools/list 中的 operations.items 使用不含 oneOf、anyOf、allOf 的兼容 Schema；服务端 handler 仍执行精确类型和业务校验。调用方在构造 operation 前应调用 get_bridge_model_write_operation_schema，按返回的 exact_schema、prerequisite_tools 和 example 生成参数。以后增加车辆或活载工况时，不增加新的 plan/commit 工具，只增加对应 handler。每个 handler 还可以声明它产生和消费的批内引用， 注册表会拒绝未声明引用、循环依赖和同一模型对象的重复写入。 查找截面时先调用 query_bridge_sections 按编号、名称或类型筛选；修改参数截面前再调用 get_bridge_section_info 获取完整参数语义，且 parameter_updates 的键只能来自返回的 editable_parameters。

节点写入使用严格语义：create_node 必须提供明确 node_id，编号已存在时失败，不执行 自动合并或静默覆盖；可选 ref（例如 node_i）可供同一批后续单元、连接或荷载操作引用。 update_node 先通过 get_bridge_node 回读当前值，只修改请求中给出的 new_id/x/y/z 字段， 提交时仍向 qtmodel 发送完整目标坐标，避免使用底层默认值。创建和修改都在提交后按浮点 容差回读验证。

材料写入先使用 list_bridge_materials / get_bridge_material 核对编号、名称和现有参数。 数据库材料通过 material_type + standard + database 定义；用户自定义材料或覆盖数据库 参数时，精确 Schema 会要求 elastic_modulus、unit_weight、poisson_ratio 和 temperature_coefficient 四个具名参数。update_material 支持部分字段更新，C# UPDATE-MATERIAL 原位路由会同步迁移单元、钢束、施工阶段和组合材料引用。

板厚写入先使用 list_bridge_thicknesses / get_bridge_thickness 回读完整定义。 normal 板厚可设置无偏心、比例偏心或数值偏心；ribbed 板厚可分别定义T肋四参数或U肋 五参数、纵横向间距、肋位置及计算方式。UPDATE-THICKNESS 会替换完整板厚对象并同步所有 关联板单元。新增材料和板厚可声明 ref，供后续单元 operation 在同一批中引用。

阶段 3 已加入梁、杆、索、板单元的类型化写入：create_beam_element / update_beam_element、 create_truss_element / update_truss_element、create_cable_element / update_cable_element 以及 create_plate_element / update_plate_element。写入前使用 query_bridge_elements / get_bridge_element 回读当前定义；修改操作仅接受同类型单元并保留未提供字段。节点、材料和板厚 既可使用明确编号，也可通过同一批前序操作声明的 ref 引用；截面使用明确 section_id。四类单元可与节点、材料和板厚一起 提交为一个桥通原生撤销步骤；C# 同类型更新在原对象上执行，避免丢失施工阶段、荷载等对象引用。

阶段 4 已加入一般支承、弹性支承、弹性连接、主从约束、梁端约束、约束方程和节点局部 坐标系。先用 list_bridge_boundary_groups 发现真实边界组名称，再用 query_bridge_boundaries / get_bridge_boundary 回读；未指定 group_names 时边界查询会遍历 全部边界组，并返回搜索组数、候选数和匹配数诊断；节点局部坐标系用 query_bridge_node_local_axes / get_bridge_node_local_axis。自由度顺序统一为 [X,Y,Z,RX,RY,RZ]，True 对外始终表示约束或耦合。所有创建操作使用明确编号且禁止静默 覆盖，所有修改操作保留未提供字段并通过 C# 原生修改命令原位执行，可与节点和单元操作一起 放入同一批次、一次提交和一次撤销。

阶段 5 已加入节点力、节点强制位移、梁/杆/索集中与分布荷载，以及板集中、板边线分布和 板面分布荷载。先用 query_bridge_loads / get_bridge_load 按“荷载族 + 工况 + 编号”回读， 并用 list_bridge_load_groups 核对可用荷载组； 集中与分布、板线与板面使用各自独立编号空间，修改时禁止跨族变更。梁荷载位置统一使用距 I端 0..1 相对位置，板集中荷载位置继续使用沿 IJ/IL 方向的绝对距离。14 个 create_* / update_* operation 均提供具名字段和严格枚举；创建荷载可通过 node_ref 或 element_ref 引用同一批中创建的对象。多个荷载与其他建模操作可放入一个批次，提交后只形成 一条桥通原生撤销命令。

阶段 6 为阶段 1–5 对象加入 21 个 delete_* operation：节点、材料、板厚、梁/杆/索/板单元、 六类边界、节点局部坐标系和七类荷载。删除始终使用稳定身份：普通对象按编号，边界按 “边界类型 + 边界组 + 编号”，荷载按“荷载族 + 工况 + 编号”。包含依赖对象的批次可按任意 输入顺序提交，注册表会按“荷载/边界 → 单元 → 节点/材料/板厚”的逆依赖顺序执行。删除节点、 单元、材料或板厚时，如果仍有阶段 1–5 的受管对象引用它，而对应 delete_* 未显式列入同一 批次，规划阶段会拒绝操作，不借用旧 API 的隐式级联行为。整批删除或创建/修改/删除混合批次 仍受 100 个 operation 上限、plan_id + model_revision 乐观锁、逐项回读、失败自动 Undo 和 一次原生撤回约束。

如果宿主在调用工具之前仍报告 oneOf / anyOf 校验错误，通常是缓存了旧版 tools/list。此时应重新加载 MCP 工具或重启宿主，不要把数字强制转换为字符串来绕过校验。

模型审查无 error 后，QpyIDE 可先请求用户确认并调用 solve_current_model。求解完成后， 使用 get_bridge_result 提取明确范围的结果：

• deformation：节点变形；
• element_force：单元内力；
• element_stress：单元应力；
• reaction：节点反力。

运营阶段查询使用 stage_id=-1 并必须指定 case_name；ids 必须明确给出，默认最多 返回 500 行，避免自然语言误操作导出整个大型模型。

inspect_bridge_element 的单元综合检查不再保留；需要时按对象类型增加符合 list_bridge_* / get_bridge_* 命名的有界接口。全局模型审查只保留为 Agent Kit 内部校验，不发布 audit_bridge_model MCP 工具；solve_current_model 会在启动计算前 自动执行这项内部模型审查。

get_bridge_model_summary 固定输出精简摘要，include_details 只能为 false，不会返回 节点、单元或支承明细。截面目录使用 query_bridge_sections，检查具体截面时使用 get_bridge_section_info，高基数模型对象使用带筛选条件的查询或明确身份详情工具。

大量节点的多步工作流先调用 resolve_bridge_node_selection。它在桥通进程内按显式编号、 结构组、包围盒和 x/y/z 坐标比较条件取交集，可再用 exclude_node_ids 或另一个 exclude_selection_id 排除已经处理的节点。返回值只包含 selection_id、数量、编号摘要、 包围盒和最多 10 个样本，不把数千个节点编号回显给 MCP。选择集在 MCP 进程内保存 30 分钟， 最多包含 20000 个节点，并严格绑定创建时的 model_revision；超量会失败而不是静默截断， 模型一旦变化后旧选择集不能直接写入。普通分页游标仍用于浏览坐标明细，冻结选择集用于后续 语义级写操作，二者职责不同。

阶段 3 提供首个语义级写 operation：translate_nodes。调用方先冻结节点选择集，再通过 get_bridge_model_write_operation_schema(operation="translate_nodes") 取得精确字段，把 selection_id 与全局平移量 dx/dy/dz 作为批次中的唯一 operation 交给 plan_bridge_model_batch。一个 operation 可一次平移最多 20000 个节点，不受“每节点一个 operation”的 100 项上限影响；提交时只进行一次严格 C# 批量调用，禁止空编号退化为全部节点， 也不会在移动时自动分割杆系单元。计划只显示选择摘要、前后包围盒和 5 个样本，提交结果只返回 计数、位移和验证摘要。整次平移仍使用 plan_id + model_revision 乐观锁，写入当前模型后形成 一条桥通原生撤销命令，可由 undo_bridge_model_transaction 整体撤回。

阶段 4 支持提交后继续导航。若后续步骤仍要操作完全相同的一批节点，调用 rebase_bridge_node_selection 将旧选择集显式重绑定到当前 model_revision；服务端按原冻结编号 逐项核对，只要有一个节点已删除就整体拒绝，绝不会静默缩小集合。若需要组合多个条件结果，使用 combine_bridge_node_selections 在服务端执行 union、intersection 或 difference，其中差集 定义为第一个集合减去其余集合。集合运算最多接收 16 个当前版本选择集、最多产生 20000 个节点， 返回值仍只有新 selection_id、数量、摘要、包围盒和样本。分页 cursor 继续严格绑定旧查询版本， 不会因阶段 4 而放宽一致性。

报告“基本信息”对应的只读 MCP 接口采用目录/详情分离：

• get_bridge_project_metadata、get_bridge_code_check_context 返回工程身份和检算上下文；
• resolve_bridge_node_selection 冻结大规模节点集合，rebase_bridge_node_selection 跨提交续用同一集合，combine_bridge_node_selections 执行服务端集合运算；
• query_bridge_nodes 浏览有界坐标明细，get_bridge_node 获取单节点精确坐标；
• query_bridge_elements、query_bridge_node_local_axes 查询单元和节点局部坐标系；
• query_bridge_loads、query_bridge_boundaries 按荷载族或边界类型及相关对象查询；
• list_bridge_boundary_groups 分页列出边界组名称，避免创建或查询时猜测组名；
• list_bridge_materials 配合 get_bridge_material 查询材料；
• list_bridge_thicknesses 配合 get_bridge_thickness 查询普通板厚和加劲板厚；
• list_bridge_load_cases 配合 get_bridge_load_case 查询有界荷载明细；
• list_bridge_load_combinations 配合 get_bridge_load_combination 查询组合项与系数。

所有详情接口均要求明确编号，列表及明细最多返回 100 项，并携带 model_revision。 模型分页游标继续严格绑定 model_revision；错误会明确区分 CURSOR_MALFORMED、 CURSOR_WRONG_KIND、CURSOR_TAMPERED 和 CURSOR_STALE。 旧的 list_bridge_nodes、list_bridge_elements、list_bridge_loads 和 list_bridge_boundaries 不再发布；模型写入与删除依赖检查同样不会回退到这些全量读取路径。 未打开检算工况时，检算上下文返回 check_case_available=false，不会伪造报告占位字段。

CLI 和 list-tools 输出为每个工具提供 mutates_model、risk_level、 requires_confirmation、undoable 元数据，QpyIDE 可据此统一实施审批策略。