qiaotong-agent-kit

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

安装

pip install qiaotong-agent-kit

如需 MCP stdio 服务（Python 3.10 及以上）：

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

安装包会自动安装 qtmodel>=2.5.0，并内置脱敏后的桥型规则和匿名参考证据； 不需要复制开发机上的 qtmodels 目录，也不会发布原始模型脚本、模型名或文件路径。

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 服务。

脱敏参考规则库

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，也不允许 从匿名编号反推项目或桥梁名称。

连续梁一键建模

用户只需要提供三个工程输入：规范、跨度和桥型。例如：

from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()
plan = service.invoke("plan_continuous_beam", {
    "design_code": "JTG D60-2015",
    "spans": "2×30+40+2×30",
    "bridge_type": "预应力混凝土连续梁",
})

计划会自动生成材料、等效箱形截面、沿桥向网格、逐跨结构组、支承、一次成桥阶段、 规范移动荷载和运营分析设置；预应力混凝土桥还会生成按拉应力侧分区的顶/底板概念钢束。 桥通自重随一次成桥阶段激活的结构组自动计入，不再建立独立的自重工况。

整体坐标固定为：

• 主梁沿整体 +X；
• 横桥向为整体 +Y；
• 竖向及桥塔正方向为整体 +Z；
• 主梁单元 I 端在小 X 侧、J 端在大 X 侧；
• 单元局部轴遵循桥通源码 FrameElement.UpdateLocalOrientation，Agent 只负责节点顺序和 beta 角。

真正写入模型前应先向用户展示计划。build_continuous_beam 的 confirm_replace=true 只是危险操作确认，不是第四个工程参数。写入过程会先保存当前 模型快照，失败时自动恢复；成功后返回快照路径和读回审查结果。自动生成的是概念/ 初始分析模型，钢束数量、曲线、锚固和张拉参数仍须结合计算结果做正式设计复核。

Agent 建模还执行以下强制规则：

• 变截面组的梁高及其他所有非线性参数，以 I/J 端中数值较小的一端为参考点；
• 自动生成模型必须且只能包含“一次成桥”施工阶段；
• 不创建“自重”或“结构自重”荷载工况；
• 荷载组合中的施工阶段“合计/合计值”仅在一次成桥阶段存在时有效；
• 钢束布置于常见弯矩拉应力侧，沿顶板或底板，控制线不得重合或相交。

可调用 select_smaller_end_reference 直接生成桥通非线性 parameter_info 值， 调用 validate_tendon_layout 在写入前检查钢束控制线。

当前支持 JTG D60-2015、JTG 3362-2018、CJJ 11-2019、TB 10002-2017、 TB 10092-2017，以及预应力混凝土连续箱梁和钢连续箱梁。可调用 list_continuous_beam_defaults 获取机器可读清单。

在 QpyIDE 中配置 MCP

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

qiaotong-readonly-mcp  # 截面、计划、模型摘要和审查，不暴露写模型工具
qiaotong-model-mcp     # 包含建模与快照恢复，QpyIDE 应对工具调用弹出确认

QpyIDE 的 Agent 应遵循以下调用顺序：

1. 调用 plan_continuous_beam，把假设、警告、节点/单元/支点数量展示给用户；
2. 用户确认后调用 build_continuous_beam；
3. 检查返回的 audit，有 error 时不发起计算；
4. 需要撤销时，使用返回的 snapshot_path 调用 restore_model_snapshot。

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

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

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

检查当前打开模型时，可用 audit_bridge_model 做全局拓扑/支承/坐标审查；对“检查 第 N 号单元截面是否正常”这类问题，使用 inspect_bridge_element 一次读取该单元的 I/J 节点、材料截面号、截面数据、截面特性和按源码计算的局部坐标系。

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