qiaotong-agent-kit

qiaotong-agent-kit 是面向桥通软件的 Agent 工具层。当前源码版本为 0.24.1，提供模型读取、受控写入，以及集成的 qiaotong_agent_kit.cad 图纸解析和主梁编译能力。

0.24.1 完善运行错误诊断：保留桥通状态、错误代码与处理建议，写入结果未知时阻止自动重试；依赖 qtmodel 2.9.4（add_section 默认 index=-1，按现有最大截面编号加 1 新增）。旧桥通后端支持客户端预检查，完整原子状态检查需更新桥通插件。

0.24.0 新增只读工具 get_bridge_structure_group_weight(group_name, limit=20)，按精确结构组名称汇总全部单元的桥通原生自重，返回总重量 N/kN 及有限明细。limit 只限制明细，不截断合计；空组不会误查全模型，缺失单元或查询期间模型变化会拒绝输出合计，零重量单元会给出提示。重量查询不需要求解或冻结选区，旧桥通没有 model_instance_id 时仍通过连接来源、模型修订及组成员前后核对执行单次只读统计；写入、冻结选区及撤销保持实例保护要求。当前共48个工具（只读46个）。

MCT模型回归补充了六个只读服务：get_bridge_structure_group_summary（材料/截面分布、坐标范围与累计弦长）、diagnose_bridge_model（材料/截面/板厚引用与近重合节点候选诊断）、get_bridge_material_statistics、get_bridge_load_statistics、get_bridge_construction_stage_details（激活对象与阶段对比）和 get_bridge_modal_results。累计弦长不等于墩高；组内连通分量不等于全桥孤岛；原生荷载合力不包含自重、温度、预应力、位移和力矩。模态工程频率为Hz、角频率为rad/s，参与质量字段是无量纲比值（0.01表示1%，不是kg/t），周期如按1/f计算应标为计算值。其他结果单位未由后端声明时保持未知。诊断不是约束秩、施工稳定性或规范检算。

本轮还修复新建工况/组后同批添加节点荷载的规划查询，并检测同批节点荷载覆盖冲突。支持连续撤销本服务签发的事务时，必须有桥通model_undo_receipt_schema=1提供原子撤销回执；人工编辑、Undo/Redo历史变化仍拒绝旧凭证。无原子回执的旧后端维持严格历史校验。环境检测区分“包有版本记录”和“模块实际可导入”，支持定位损坏的rpds/Shapely原生扩展。

同版本补充 get_bridge_section_properties(index)，读取桥通原生面积、惯性矩、静矩、形心与剪切中心，保留变截面两端特性及明确单位。节点、单元、荷载、边界及局部坐标系的只读分页查询兼容旧桥通，以连接来源、可用实例标识与模型修订前后核对；旧版本缺少实例标识时无法区分重新打开的相同内容工程，因此不允许该读取标识用于写计划或冻结选区。

query_bridge_results 新增 self_concurrent_reaction、all_concurrent_reaction、concurrent_force，分别调用桥通结果栏的自并发反力、完全并发反力和并发内力接口，不是并行查询或普通包络。用 list_bridge_concurrent_result_cases 获取实际完整结果名；旧 API 通过缺失工况诊断提供目录，不支持此诊断时明确返回目录不可用。并发反力每次指定一个实际支座控制节点；并发结果 stage_id=-1，控制分量及最大/最小通过准确结果名选择。空目录不表示零反力，也不能用自并发结果替代完全并发结果。当前结果 API 未声明单位时保留原始数值及单位未报告提示。

0.23.0 完善模型实例与轻量修订保护、批量写入及撤回凭证、严格参数校验和结果分页缓存，并新增工况与组管理操作。依赖 qtmodel>=2.9.4,<2.10.0；受控写入需配套更新桥通桌面端，状态协议及升级要求见下文。

0.22.2 在规划自定义线圈截面时把横向坐标移至左缘为零，与桥通原生保存坐标系一致，避免带负坐标的图片识别截面在回读时被误判并回滚。

0.22.0 将 CAD 实现、测试与文档并入本包。安装 qiaotong-agent-kit[cad] 即可使用 DXF 索引、自定义截面、跨度与具名图纸规则编译；DWG 可通过本机 ODA 转换。QPyIDE Agent 使用 create_bridge_from_cad 完成对话翻模，宿主负责批准、事务回读及保存。详见 CAD 翻模说明。

0.22.1 在缺少单位说明时，根据具名截面视图中的横向、竖向尺寸及半幅标注推断唯一合理的单位；图内说明仍优先，冲突或多解时保留待核定状态。

0.21.0 新增 create_custom_section、create_parameter_section、create_tapered_section 和 create_frame_mesh，共 69 个模型操作。网格导入最多 5000 个创建对象，在单个原生事务中排序、执行、回读和撤销；普通批次仍限制为 100 个操作。CAD 默认采用自定义线圈截面，保留外圈、孔洞和倒角；非闭合轮廓由 CAD 界面询问并核定正厚度后转为自定义线宽截面。可选参数截面创建支持矩形和无倒角的对称混凝土箱梁。

自定义线圈回读核对轮廓、孔洞、参考点、面积与惯性矩；自定义线宽核对每条中心线及厚度、参考点、面积，并要求原生抗扭、抗弯及剪切特性均为有限正值。线宽接头的本地条带算法与桥通原生算法不同，原生惯性矩用于模型，差异在 line_width_checks 中记录。质心参考点核验考虑原生属性接口保留 4 位小数的输出精度。CAD 编译只输出明确模型对象，不直接提交模型或执行模型生成的任意脚本。

0.23.0 MCP 与事务更新

0.23.0 提供39个工具（只读模式37个），operation 注册表扩展至77项。 新增工况、荷载组、边界组和结构组的 create_* / update_* 操作，仅调用已有公开 API。

• 计划、冻结选区、模型查询游标和 Undo 凭证绑定工程实例；重新打开同一内容的工程也需要重新规划。
• 每个写请求携带实例标识，桥通在 UI 调度器执行前校验，避免检查后切换工程造成误写。
• 原始 JSON 按发布的 Schema 校验，拒绝未知字段、类型转换式确认和非有限数值。
• 计划开始发送写请求后即消耗，旧计划不能直接重放。明确失败时尝试原生回滚并验证； COMMAND_OUTCOME_UNKNOWN 表示请求可能仍在执行，此时不自动 Undo 或重发，禁用该实例后续写入。 请等待桥通处理完成、在桌面端核对模型和命令历史，确认后重启 Agent 服务并重新规划。
• 只读模式能力目录与实际发布工具一致，没有提交或撤销工具，不引导执行建模脚本。
• 结果查询每次最多 5000 个明确编号、每页最多 200 行。相同范围复用 120 秒快照， 后续只传 cursor；快照绑定工程、结果数据源、阶段和模型修订，变化后拒绝分页。 编号和缺失编号仅回显前 20 个，同时返回数量和摘要；统计始终覆盖该查询快照的全部行。 每个快照最多4 MiB、缓存总计最多16 MiB，响应数据限64 KiB；宽表会缩小页大小并正确续页。

本批需要配套更新并重新编译桥通 Bridge.ProjectManager 与 Bridge.PythonPlugin（状态协议 4、model_instance_guard=1、model_revision_schema=1）， 并使用含 QtServer.require_model_instance / require_model_revision 的 qtmodel 源码或新构建包。旧桥通仍可读取摘要和不依赖实例标识的单项明细， 受控写入、冻结选区及游标查询会明确要求升级；没有实例和结果源标识时不复用结果快照。旧计划和 Undo 凭证应重新生成。

结构组成员参数是完整替换：省略时保留，空数组清空；新增工况和组会先于其荷载执行， 结构组可引用同批先创建的明确节点/单元编号。重命名目录和修改其已有成员建议分两批规划。 本批没有新增目录删除操作，避免隐式级联删除工况内荷载或关联定义。

第 7 批接入轻量 model_revision 协议：直接读取已有握手状态，不重复导出完整模型。 修订号标识命令状态，覆盖 UI/API 共用命令、待提交子命令、无日志提交、Undo/Redo、历史清空和工程重开； 提交不改变同一模型状态的修订号，Undo/Redo 恢复对应状态。独立 history_revision 防止旧撤回凭证在历史变化后继续使用。 UPDATE 的可选 capture_command_state=true 响应在同次 UI 调度内捕获提交状态；默认响应保持兼容。 撤回在桌面执行前校验实例、模型修订、历史和待提交命令，回滚失败或未登记修改无法证明恢复时停止自动写入。 旧桥通没有轻量协议时仍逐次计算完整内容指纹，不使用时间缓存；有协议但字段无效时明确失败。

第 8 批按实际开放 API 整理旧 SDK 契约：46 个旧方法/别名建立明确状态清单， 17 个缺少服务端路由的历史命令在连接前报告 API_NOT_OPEN，API 帮助同步标注。 当前接口的正向测试保留，失效模块与日志改为不可用契约，未为测试新增 API。 同时修复 remove_elements 显式空集合可能触发“删除全部单元”的问题。 详见 SDK 契约说明。

全量 Python 回归 1707 项通过、1 项跳过，另有 644 项子测试通过；跳过项为未安装的可选旧 CAD 兼容包。 两份 C# 检查脚本直接编译生产命令类、请求分发和执行前校验，覆盖修订恢复、历史保护和提交状态捕获。 当前环境不能构建完整 WPF 工程，发布前仍需正常编译并在桥通桌面验证。

环境要求

• Python 3.10 或更高版本（低于 Python 4）
• qtmodel>=2.9.4,<2.10.0
• 需要 MCP 服务时安装可选依赖 mcp

安装基础库：

python -m pip install qiaotong-agent-kit

安装 MCP 支持：

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

功能范围

模型读取包括：

• 模型摘要、工程信息和规范配置；
• 节点、单元、截面、材料和板厚；
• 边界、节点局部坐标系和节点/单元荷载；
• 结构组、施工阶段、荷载工况和荷载组合；
• 服务端筛选、游标分页和可重绑定的冻结节点选择集。

模型写入采用统一 operation 注册表，覆盖节点、材料、板厚、参数截面、梁/杆/索/板 单元、边界、局部坐标系及荷载的创建、修改和删除，并支持工况与组的创建和修改。所有提交遵循：

1. 查询 operation 的精确 Schema；
2. 生成写入计划并绑定工程实例与 model_revision；宿主通过 ModelReviewSession.prepare 发起有效的纯创建请求时，无工程首页会先自动新建空白工程并进入前处理；底层 plan_bridge_model_batch 仍保持只读；
3. 用户确认后提交计划；
4. 整批作为一条桥通原生命令执行；明确失败时尝试 Undo，结果未知时停止并核对；
5. 成功后可使用返回的 undo_transaction 撤回最新事务。

Python 调用

from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()

status = service.invoke("get_connection_status")
summary = service.invoke("get_bridge_model_summary")

nodes = service.invoke("query_bridge_nodes", {
    "bbox": [0.0, -5.0, -5.0, 100.0, 5.0, 5.0],
    "limit": 20,
})

模型写入示例：

operation = {
    "operation": "create_node",
    "node_id": 101,
    "x": 10.0,
    "y": 0.0,
    "z": 0.0,
}

schema = service.invoke(
    "get_bridge_model_write_operation_schema",
    {"operation": operation["operation"]},
)

plan = service.invoke(
    "plan_bridge_model_batch",
    {"operations": [operation]},
)

receipt = service.invoke("commit_bridge_model_batch", {
    "plan_id": plan["plan_id"],
    "model_revision": plan["model_revision"],
    "confirm_commit": True,
})

撤回最新事务：

service.invoke("undo_bridge_model_transaction", {
    "transaction": receipt["undo_transaction"],
    "confirm_undo": True,
})

MCP 服务

默认模型读写服务：

qiaotong-model-mcp

只读服务：

qiaotong-readonly-mcp

通用 MCP 宿主配置示例：

{
  "command": "python",
  "args": ["-m", "qiaotong_agent_kit.interfaces.mcp_server"]
}

当前模型模式和完整模式均只发布模型读写工具。只读模式不发布 commit_bridge_model_batch 和 undo_bridge_model_transaction。

包结构

qiaotong_agent_kit/
├─ application/
│  ├─ bridge_model.py       # 模型查询、写入事务和桥通适配门面
│  ├─ results.py            # 有界结果快照和游标分页
│  └─ service.py            # Agent 工具目录与调用服务
├─ cad/                     # 可选图纸解析与主梁编译
├─ contracts/
│  └─ tool_schema.py        # 与 MCP 框架无关的工具元数据
├─ infrastructure/
│  └─ qiaotong_api/         # 外部桥通 API 连接与 qtmodel 版本兼容性
├─ interfaces/
│  ├─ cli.py                # JSON-lines 命令行接口
│  └─ mcp_server.py         # MCP stdio 服务
├─ model_write/
│  ├─ operations/           # 单项模型写 operation
│  ├─ registry.py           # operation 注册、规划与排序
│  └─ references.py         # 批内引用协议
└─ support/
   └─ privacy.py            # 输出和错误信息脱敏

infrastructure/qiaotong_api 是 Agent Kit 的基础设施边界，不是外部 qtmodel 包的副本。使用这个名称可以避免 qiaotong_agent_kit.infrastructure.qtmodel 与顶层 qtmodel 运行库产生导入和认知混淆。

依赖原则

基础安装声明 qtmodel、shapely 与契约校验使用的 jsonschema。MCP 依赖通过 [mcp] 引入； DXF 解析器 ezdxf 与 CAD 数值依赖通过 [cad] 引入。集成 CAD 能力面向 Python/CLI 与宿主集成， 标准 MCP 工具面仍限于模型读写和只读结果查询。