🏥 AssetHub MCP 完整技能文档 (v3.0)

基于 /Users/cjlee/PJ/BmeHub/docs/assethub-mcp-tools.md 官方文档编写

核心原则（必须遵守）

1. 多租户认证 — 每个调用必须传入 tenant_id 和 _auth_context_id
2. 工具优先 — 优先使用直接 MCP 工具，不优先用 smart_call
3. 先查后写 — 写操作前必须先查目标对象确认
4. 全量优先原则 — 查某一类设备名称时，用 list_all_assets(search="xxx") 全量搜索，不用 list_assets(keyword=...)
5. 不暴露内部上下文 — 最终回复中不回显 _auth_context_id、token 等
6. 批量操作优先 — 多个同类操作优先用 batch_* 批量工具
7. 参数必填优先 — 调用前确认必填参数已提供

标准工具参数结构

{
  "_auth_context_id": "ctx_xxxxxxxxxxxx",
  "tenant_id": 2
}

⚠️ _auth_context_id 从当前 Web 会话提示 JSON 的 _auth_context_id 字段获取，每个会话可能不同。

🌐 AssetHub 系统信息

🔧 MCP 配置方法

本 Skill 配合 AssetHub MCP Server 使用，通过 OpenClaw Gateway 自动注入认证上下文。

1. OpenClaw 配置（config.yaml）

mcp:
  servers:
    assethub:
      command: node
      args:
        - /path/to/assethub-mcp/dist/index.js
      env:
        ASSETHUB_BASE_URL: http://127.0.0.1:5183
        ASSETHUB_AUTH_MODE: session    # 使用 Web 会话认证
        ASSETHUB_WEBSOCKET_URL: ws://127.0.0.1:5183

2. 认证流程

用户打开 AssetHub Web UI (http://127.0.0.1:13579)
       ↓
    登录系统
       ↓
OpenClaw Gateway 捕获会话认证上下文 (ctx_xxx)
       ↓
MCP 工具调用时自动注入 _auth_context_id
       ↓
返回数据时过滤敏感信息

3. 多租户支持

⚠️ 不同租户的 tenant_id 不同，调用时必须指定正确的 tenant_id

4. 快速验证连接

在 OpenClaw AI 助手中输入：

我的租户ID是多少？

系统会自动返回当前用户的租户上下文信息。

📊 工具统计总览

🔑 关键区别：keyword vs search vs 全量

实战经验：

• 查"空调"→ list_all_assets(search="空调") ✅
• 查"监护仪"→ list_all_assets(search="监护仪") ✅
• 已知资产编号→ get_asset(asset_code="xxx") ✅
• 查某部门资产→ list_assets(department="xxx") ✅

📋 常用工具速查

查询类

维修类

调配/报废类

盘点类

采购/质检类

文档类

预防性维护类

告警类

用户/角色类

IoT/监测类

折旧类

AI分析类

报表统计类

模块配置类

位置管理类

库存管理类

🏗️ 标准工作流

1. 资产报修流程

Step 1: 定位资产
  assethub_list_all_assets(search="设备名称")

Step 2: 确认资产编号

Step 3: 创建维修申请
  assethub_create_maintenance_request(
    asset_code="xxx",
    fault_description="故障描述",
    fault_level="一般/紧急",
    request_department="报修科室",
    contact_phone="电话"
  )

Step 4: (可选) 审批
  assethub_approve_maintenance_request(id=xxx, action="approve", comment="同意")

Step 5: (可选) 开始执行
  assethub_start_maintenance_request(id=xxx, repair_person="张三")

Step 6: (可选) 完成维修
  assethub_complete_maintenance_request(
    id=xxx,
    repair_content="维修内容",
    repair_cost=1000,
    parts_replaced="更换零件"
  )

2. 资产调配流程

Step 1: 查询资产确认
  assethub_get_asset(asset_code="xxx")

Step 2: 提交调配申请
  assethub_transfer_asset(
    asset_code="xxx",
    target_department="目标科室",
    reason="调配原因"
  )

Step 3: 审批
  assethub_approve_transfer(id=xxx, action="approve", comment="同意")

Step 4: 执行
  assethub_execute_transfer(id=xxx)

3. 盘点完整流程

Step 1: 创建盘点计划
  assethub_create_inventory_plan(
    plan_no="PD20260402001",
    plan_name="全院资产盘点",
    start_date="2026-04-02",
    end_date="2026-04-09"
  )

Step 2: 激活计划
  assethub_activate_inventory_plan(id=计划ID)

Step 3: 创建盘点任务
  assethub_create_inventory_task(
    inventory_id=计划ID,
    task_name="科室盘点任务",
    assignee="李刚",
    assignee_name="李刚",
    location="科室位置"
  )

Step 4: 执行盘点
  assethub_start_inventory_task(id=任务ID)

Step 5: 完成盘点
  assethub_complete_inventory_task(id=任务ID, actual_count=100)

Step 6: 生成差异
  assethub_generate_inventory_discrepancies(inventory_id=计划ID)

Step 7: 处理差异(批量)
  assethub_batch_handle_inventory_discrepancies(
    ids=[ID1, ID2],
    handling_status="已处理",
    handling_method="盘亏报废"
  )

Step 8: 完成计划
  assethub_complete_inventory_plan(id=计划ID)

4. 文档上传审核流程

Step 1: 上传文档
  assethub_upload_document(
    title="设备操作手册",
    doc_type="操作手册",
    category="技术资料",
    asset_code="xxx"
  )

Step 2: 审核文档
  assethub_review_document(id=文档ID, review_status="approved", comment="审核通过")

Step 3: 创建分享(可选)
  assethub_create_document_share(
    id=文档ID,
    expires_days=30,
    supplier_name="供应商名称"
  )

5. 预防性维护流程

Step 1: 创建维护计划
  assethub_create_maintenance_plan(
    plan_name="CT机年度维护",
    asset_code="xxx",
    maintenance_type="预防性维护",
    cycle_type="year",
    cycle_value=1,
    trigger_type="time"
  )

Step 2: 配置提醒
  assethub_config_reminder(
    plan_id=计划ID,
    reminder_days=7,
    reminder_types=["email", "sms"],
    recipient="工程师"
  )

Step 3: 执行维护
  assethub_complete_maintenance_plan(
    id=计划ID,
    maintenance_date="2026-04-01",
    maintenance_person="张三",
    actual_hours=4,
    parts_replaced="滤网"
  )

6. 设备注册与定位上报流程

Step 1: 注册IoT设备
  assethub_register_device(
    device_name="Beacon-001",
    device_type="beacon",
    device_id="BEACON-001",
    asset_code="xxx"
  )

Step 2: 上报设备位置
  assethub_report_device_location_data(
    device_id="BEACON-001",
    latitude=31.2304,
    longitude=121.4737,
    battery_level=85
  )

Step 3: 或上报Beacon位置编码
  assethub_report_beacon_location(
    device_id="BEACON-001",
    location_code="LOCATION-001"
  )

🎯 推荐决策树

"查某类设备"问题

用户要查某类设备（未限定科室）
  │
  └─ 用 assethub_list_all_assets(search="设备名称") ✅
     (不要用 assethub_list_assets keyword，会漏数据)

"我是谁"问题

用户问"我是谁/什么角色/哪个租户"
  │
  └─ 调用 assethub_get_current_auth_context
     → 读取: scope.user.username, real_name, role, tenant_id, tenant_name

"调配申请"问题

用户要申请调配
  │
  ├─ Step 1: 查询资产确认 asset_code
  ├─ Step 2: 调用 assethub_transfer_asset
  ├─ Step 3: 调用 assethub_approve_transfer (如有权限)
  └─ Step 4: 调用 assethub_execute_transfer

"修改角色权限"问题

用户要修改角色权限
  │
  ├─ Step 1: 调用 assethub_get_current_auth_context 确认权限
  ├─ Step 2: 确认当前角色有管理权限
  ├─ Step 3: 调用 assethub_update_role_permissions
  └─ Step 4: 调用 assethub_get_role_permissions 回查确认

"报修"问题

用户要报修设备
  │
  ├─ Step 1: assethub_list_all_assets(search="设备名称") 定位资产
  ├─ Step 2: 确认资产编号
  ├─ Step 3: assethub_create_maintenance_request 创建申请
  └─ (可选) 审批 → 开始 → 完成

"盘点"问题

用户要发起盘点
  │
  ├─ Step 1: assethub_create_inventory_plan 创建计划
  ├─ Step 2: assethub_activate_inventory_plan 激活
  ├─ Step 3: assethub_create_inventory_task 创建任务
  ├─ Step 4: assethub_start_inventory_task 开始盘点
  ├─ Step 5: assethub_complete_inventory_task 完成
  ├─ Step 6: assethub_generate_inventory_discrepancies 生成差异
  └─ Step 7: assethub_batch_handle_inventory_discrepancies 处理

⚠️ 常见误区

1. ❌ 不要把当前页面上显示的用户名当成最终事实来源
2. ❌ 不要把 tenant_id 固化到长期记忆里
3. ❌ 不要把共享用户名密码写死进 MCP 配置
4. ❌ 不要在缺少租户上下文时替超级管理员猜租户
5. ❌ 不要省略 _auth_context_id
6. ❌ 不要在写操作前跳过目标对象确认
7. ❌ 不要在最终回复里回显内部上下文 JSON
8. ❌ 不要优先走 smart_call 代替直接工具
9. ❌ 查某一类设备名称时，不要用 list_assets(keyword=...)，要用 list_all_assets(search=...)
10. ❌ smart_call 对资产名称类查询的推荐质量不稳定，不要依赖它

🔧 认证异常处理

📱 常见设备名称映射

📊 故障描述规范

报修时的 fault_description / maintenance_content 字段应尽量具体：

📤 输出格式规范

查询结果统一用表格展示，字段包括：

• 资产编号、资产名称、规格型号
• 使用科室、存放位置
• 购置日期、购置价格、当前价值
• 资产状态

统计类查询应包含合计行和关键洞察。

📍 系统拓扑

📝 资产状态说明

🔢 故障等级

📋 盘点状态

🎯 调配/审批操作 action

📌 维修工单状态

📌 库存调整类型

📌 盘点处理方式

🔐 smart_call 使用原则

❌ smart_call 对资产名称类查询的推荐质量不稳定（如"查空调"它只建议 list_assets），不要依赖它作为主查询路径。已知设备名称时直接走 assethub_list_all_assets。

📖 参数必填说明

调用工具前必须确认必填参数已提供，以下是各工具必填参数速查：

资产管理

• create_asset: asset_name, category_id
• update_asset: id
• get_asset: asset_code 或 id
• delete_asset: id
• list_assets: 无
• list_all_assets: 无

维修管理

• create_maintenance_request: asset_code, fault_description
• approve_maintenance_request: id, action (approve/reject)
• start_maintenance_request: id, repair_person
• complete_maintenance_request: id
• create_maintenance_workorder: title, asset_code
• complete_workorder: id
• create_maintenance_log: asset_code, maintenance_type, maintenance_date, maintenance_person, maintenance_content
• create_maintenance_plan: plan_name, asset_code, maintenance_type, cycle_type, cycle_value

调配/报废

• transfer_asset: asset_code, target_department, reason
• approve_transfer: id, action
• execute_transfer: id
• publish_idle_asset: asset_code
• create_scrapping: asset_code, reason
• approve_scrapping: id, action

盘点

• create_inventory_plan: plan_no, plan_name
• activate_inventory_plan: id
• create_inventory_task: inventory_id, task_name, assignee, assignee_name
• complete_inventory_task: id, actual_count
• generate_inventory_discrepancies: inventory_id
• handle_inventory_discrepancy: id, handling_status, handling_method
• batch_handle_inventory_discrepancies: ids, handling_status, handling_method

采购/质检

• create_procurement: asset_name, department, reason
• approve_procurement: id, action
• create_quality_control: asset_code, qc_type, qc_date, qc_person, result
• create_acceptance: asset_code, acceptance_date, result

文档

• upload_document: title
• review_document: id
• create_document_comment: id, content
• favorite_document: id
• create_document_share: id
• create_document_tag: tag_name

位置/IoT

• create_location_code: location_code, location_name
• register_device: device_name, device_type
• report_device_location_data: device_id
• report_beacon_location: device_id, location_code
• ingest_zone_location_batch: events

用户/角色

• create_user: username, real_name, password, role
• assign_user_role: user_id, role
• update_role_permissions: role, permissions
• reset_user_password: id, new_password

模块配置

• enable_module: module_id
• disable_module: module_id
• update_module_config: module_id, config
• backup_module_config: module_id
• rollback_module_version: module_id, version_id

🔍 复合查询工具 (query_*)

复合查询工具可一次性获取多维度数据，适合分析场景：

📚 快速调用示例

创建资产

assethub_create_asset(
  asset_name="医用 CT 扫描仪",
  category_id=1,
  purchase_price=5000000,
  status="在用"
)

创建维修申请

assethub_create_maintenance_request(
  asset_code="CT-001",
  fault_description="球管老化，需要更换",
  fault_level="紧急",
  request_department="放射科",
  contact_phone="13800138000"
)

创建维修工单

assethub_create_maintenance_workorder(
  title="CT 设备故障维修",
  asset_code="CT-001",
  description="球管老化，需要更换",
  priority=1,
  estimated_hours=24
)

查询资产列表

assethub_list_assets(
  page=1,
  limit=20,
  status="在用",
  department="放射科"
)

创建盘点计划

assethub_create_inventory_plan(
  plan_no="PD-2024-001",
  plan_name="2024年度设备盘点",
  start_date="2024-01-01",
  end_date="2024-01-31"
)

上报设备位置

assethub_report_device_location_data(
  device_id="BEACON-001",
  latitude=31.2304,
  longitude=121.4737,
  battery_level=85
)

批量写入区域定位

assethub_ingest_zone_location_batch({
  events: [
    {
      device_id: "BEACON-001",
      asset_code: "ASSET-001",
      event_time: "2026-04-01T10:00:00Z",
      location_code: "LOCATION-001",
      rssi: -65,
      battery_level: 85
    }
  ]
})

创建维修日志

assethub_create_maintenance_log(
  asset_code="ZY2020000122",
  maintenance_type="故障维修",
  maintenance_date="2026-04-01",
  maintenance_person="张三",
  maintenance_content="更换碳纤维骨科牵引架轴承",
  maintenance_duration=2,
  parts_replaced="轴承",
  maintenance_cost=500
)

创建质检记录

assethub_create_quality_control(
  asset_code="ASSET-001",
  qc_type="年度质检",
  qc_date="2026-04-01",
  qc_person="李四",
  result="合格",
  finding="无异常"
)

创建采购申请

assethub_create_procurement(
  asset_name="迈瑞监护仪",
  department="心内科",
  reason="科室新增需要",
  quantity=5,
  estimated_cost=150000,
  expected_date="2026-05-01"
)

创建报废申请

assethub_create_scrapping(
  asset_code="OLD-CT-001",
  reason="设备老旧，无法维修",
  estimated_value=5000
)

配置预防性维护提醒

assethub_config_reminder(
  plan_id=1,
  reminder_days=7,
  reminder_types=["email", "sms"],
  recipient="工程师"
)

注册IoT设备

assethub_register_device(
  device_name="温湿度传感器-001",
  device_type="environment_sensor",
  device_id="ENV-001",
  asset_code="ASSET-001",
  manufacturer="小米",
  model="MHO-A400"
)

批量处理位置告警

assethub_batch_handle_location_alerts({
  ids: [1, 2, 3],
  handle_result="已确认资产位置正常"
})