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

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

qiaotong-agent-kit 0.8.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 重复搜索 QtModel API 或生成项目脚本：

service = QiaotongToolService()
resolution = service.invoke("resolve_bridge_request", {
    "text": "查看3号单元在二期恒载下的最大内力",
})
result = service.invoke("execute_bridge_workflow", {
    "workflow_id": resolution["workflow_id"],
    "inputs": resolution["inputs"],
})

可通过 list_bridge_workflows 获取完整目录。首批工作流包括项目/模型概览、模型审查、 指定单元检查、求解状态、结果上下文和有界结果查询。缺少对象编号、结果类型或工况/阶段时 返回 needs_input；工作流入口不接受任意 Python 代码或任意 QtModel 函数名。

设置 QIAOTONG_AGENT_RUNTIME_ROOT 后，快照等运行数据统一写入该应用专属目录；未设置时 才回退到系统临时目录。

脱敏参考规则库

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": "预应力混凝土连续梁",
})

# 用户确认后必须原样提交规划阶段签发的三项事务凭证。
result = service.invoke("build_continuous_beam", {
    "design_code": "JTG D60-2015",
    "spans": "2×30+40+2×30",
    "bridge_type": "预应力混凝土连续梁",
    "plan_id": plan["plan_id"],
    "model_revision": plan["model_revision"],
    "snapshot": plan["snapshot"],
    "confirm_replace": True,
})

计划会自动生成材料、参数化混凝土箱梁/箱型钢梁截面、沿桥向网格、逐跨结构组、支承、一次成桥阶段、 规范移动荷载和运营分析设置；预应力混凝土桥还会生成按拉应力侧分区的顶/底板概念钢束。 桥通自重随一次成桥阶段激活的结构组自动计入，不再建立独立的自重工况。 连续梁截面规则会显式记录顶、底板宽度，并在计划校核时强制要求顶板宽度大于底板宽度。

整体坐标固定为：

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

真正写入模型前应先向用户展示计划。规划结果会签发 plan_id + model_revision + snapshot 事务凭证；build_continuous_beam 必须原样提交三者。执行端会重新计算完整模型指纹， 模型若在规划后发生变化就拒绝写入。confirm_replace=true 仅表示用户确认危险操作。 写入失败会自动恢复事务快照；成功后返回新 model_revision、快照状态和读回审查结果。自动生成的是概念/ 初始分析模型，钢束数量、曲线、锚固和张拉参数仍须结合计算结果做正式设计复核。

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

• 连续梁主梁优先采用箱梁截面，且箱梁顶板宽度必须大于底板宽度；
• 所有线圈型截面在计算或写入前都必须通过拓扑校验：任意两条有限边只允许在双方共同端点相交，禁止非端点交叉、T 形相交、共线重叠和零长度边；
• 变截面组的梁高及其他所有非线性参数，以 I/J 端中数值较小的一端为参考点；
• 自动生成模型必须且只能包含“一次成桥”施工阶段；
• 不创建“自重”或“结构自重”荷载工况；
• 荷载组合中的施工阶段“合计/合计值”仅在一次成桥阶段存在时有效；
• 钢束布置于常见弯矩拉应力侧，沿顶板或底板，控制线不得重合或相交；
• Agent 只能生成当前已安装 qtmodel 中真实存在的 mdb/odb/cdb/bridge 公开函数，且函数名、位置参数、关键字参数、必填参数和可校验类型必须与运行时签名一致。

可调用 select_smaller_end_reference 直接生成桥通非线性 parameter_info 值， 调用 validate_tendon_layout 在写入前检查钢束控制线。参数化线圈截面的预览和特性计算 会自动执行拓扑校验；自定义线圈可先调用 validate_section_loop_topology。生成建模命令时， 先用 get_qtmodel_api_catalog 查询当前版本的真实函数，再将全部命令一次性传给 validate_qtmodel_commands；只有返回 valid=true 才能输出或执行命令。校验过程本身不会 执行任何 qtmodel 命令。

catalog = service.invoke("get_qtmodel_api_catalog", {
    "namespace": "mdb", "query": "add_nodes"
})
check = service.invoke("validate_qtmodel_commands", {
    "commands": [{
        "namespace": "mdb",
        "function": "add_nodes",
        "kwargs": {"node_data": [[1, 0.0, 0.0, 0.0]]},
    }]
})
assert check["valid"] and not check["execution_performed"]

当前支持 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，保存返回的 plan_id、model_revision 和 snapshot，并把假设、警告、节点/单元/支点数量展示给用户；
2. 用户确认后，原样提交三项事务凭证调用 build_continuous_beam；
3. 检查返回的 audit，有 error 时不发起计算；
4. 需要撤销时，使用建模结果中的 snapshot 和当前 model_revision 调用 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 可据此统一实施审批策略。