Metadata-Version: 2.4
Name: qiaotong-agent-kit
Version: 0.9.0
Summary: Agent-safe tools for Qiaotong bridge finite element modeling
Author: Qiaotong Agent Kit Maintainers
Keywords: bridge,finite-element,agent,qtmodel,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: qtmodel<2.7.0,>=2.6.3
Requires-Dist: ezdxf<2,>=1.4
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"

# qiaotong-agent-kit

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

## 安装

```bash
pip install qiaotong-agent-kit
```

如需 MCP stdio 服务：

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

## Python 调用

```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 子进程协议

```bash
qiaotong-agent-kit list-tools
qiaotong-agent-kit serve
```

`serve` 从标准输入逐行接收：

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

并逐行返回：

```json
{"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 或生成项目脚本：

```python
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 函数名。

0.9.0 新增 `model.section.inspect`、`model.section.transform.plan`、
`model.section.transform.commit` 和 `model.section.transform.verify`。截面修改先生成绑定
`model_revision + plan_hash + snapshot` 的不可变计划；真实提交工具不会出现在只读 MCP 中，
只能由 QPyIDE 独立审批后调用。参数化截面和线宽截面支持“板厚保持不变”；无法确定性保持
板厚的任意线圈截面会明确拒绝，不会采用删除重建或近似偏移。

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

## 脱敏参考规则库

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

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

## 连续梁一键建模

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

```python
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 命令。

```python
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 入口：

```text
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 可据此统一实施审批策略。
