Agent 接入 SAM：插件架构、工具注册与安全边界 / Integrating AI Agents into SAM with Plugins, Tools, and Safety Boundaries

📅 创建时间：2026-07-23
🏷️ 标签：#SAM #Agent #工具调用 #插件架构 #安全
📚 前置知识：03-python2-verified-api、04-cpp-sdk-mesh-api
📖 系列导航：总目录 · 上一篇：05-parametric-modeling · 下一篇：07-api-validation-workflow

---

第8部分：Agent 作为 SAM 插件

8.1 Agent 不是新的建模内核

Agent 的职责是：

理解自然语言
→ 获取当前模型状态
→ 选择已注册工具
→ 填写结构化参数
→ 请求确认
→ 调用 Python 2 / C++ 工具
→ 验证结果

Agent 不应直接获得“任意执行 Python 字符串”的能力。

8.2 推荐进程架构

SAM 固定使用 Python 2.7，而现代 Agent SDK 通常运行在 Python 3。因此推荐：

┌────────────────────── SAM 进程 ──────────────────────┐
│ SAM.Pre.AgentToolset.dll  Agent 面板与菜单            │
│ SAMAgent.pyd              模型快照与高性能建模工具     │
│ Python 2 Tool Executor    已验证的 mdb/session 工具    │
└───────────────────────┬───────────────────────────────┘
                        │ JSON-RPC / Named Pipe / ZeroMQ
┌───────────────────────▼───────────────────────────────┐
│ Python 3 Agent Service                                │
│ LLM、对话状态、工具选择、任务规划、审计日志             │
└───────────────────────────────────────────────────────┘

8.3 工具注册表

只注册经过验证的最小能力：

{
  "name": "assign_shell_section",
  "description": "只给真正未分配的壳单元分配普通壳截面",
  "parameters": {
    "element_labels": {"type": "array", "items": "integer"},
    "section_name": {"type": "string"},
    "material": {"type": "string"},
    "thickness": {"type": "number", "exclusiveMinimum": 0}
  }
}

工具可以分为：

只读工具
├── get_current_context
├── inspect_model
├── get_selected_nodes
├── audit_section_assignments
└── detect_free_edge_components

修改工具
├── assign_shell_section
├── assign_generic_beam_section
├── create_parametric_lug
├── create_parametric_bracket
├── mirror_elements
└── save_model_as

8.4 一次安全执行

用户输入：

给当前未分配壳单元设置 12 mm 厚度，已有 Section 不要动。

执行链：

1. inspect_model
2. audit_section_assignments
3. 生成修改预览：49398 个壳单元
4. 用户确认
5. assign_shell_section
6. audit_section_assignments
7. save_model_as
8. 重新打开并检查

8.5 Agent 安全边界

必须强制：

• 只允许调用白名单工具
• 参数经过 JSON Schema 和业务规则双重校验
• 删除、覆盖、批量移动必须确认
• 修改前记录节点、单元、Set、Assignment 数量
• 默认另存新 .sam
• 失败后停止工具链，不自动“换一种猜法”
• 保存后重新打开检查
• 分析模型还要导出 INP 并验证求解器读取
• 每次工具调用保存输入、输出、错误和验证结果

---

第9部分：推荐工程结构

SAMAgentPlugin/
├── CMakeLists.txt
├── src/
│   ├── AgentKernel/
│   │   ├── AgentPytModule.h/.cpp
│   │   ├── AgentPartFragment.h/.cpp
│   │   ├── AgentModelFragment.h/.cpp
│   │   ├── AgentUtils.h/.cpp
│   │   ├── MeshReader.h/.cpp
│   │   └── ParametricTools.h/.cpp
│   │
│   └── AgentToolset/
│       ├── AgentToolsetPlugin.h/.cpp
│       ├── AgentToolsetGui.h/.cpp
│       ├── AgentForm.h/.cpp
│       ├── AgentDialog.h/.cpp
│       └── AgentRpcClient.h/.cpp
│
├── python2/
│   ├── sam_tool_dispatch.py
│   ├── tools_read.py
│   ├── tools_section.py
│   ├── tools_mesh.py
│   └── tools_analysis.py
│
├── agent_service/
│   ├── server.py          # Python 3
│   ├── tool_registry.py
│   ├── schemas/
│   └── audit_log.py
│
└── tests/
    ├── probes/
    ├── fixtures/
    └── regression/

---