AssetClaw 完整技能文档 (v1.4.5)

基于 http://160ttth72797.vicp.fun/api 实时接口文档编写
本 Skill 直接调用 HTTP API，不依赖 MCP 协议

---

核心原则（必须遵守）

1. 1. 先登录后请求 — 每个会话首先调用 POST /api/users/login 获取 Bearer Token 并缓存

- 凭证处理原则： - 如果新会话已提供凭证（用户名+密码），直接使用提供的凭证登录，无需再询问 - 如果未提供凭证，则分两步引导：先问用户名 → 用户回答后再问密码 → 收集完整后才执行登录 - 临时 Session 凭证存储：当凭证通过 prompt/对话传入时，Agent 将用户名和密码写入本地临时会话文件 /tmp/assethub-claw-temp-session.json（仅当前会话有效）；调用 assetclaw API 时自动从该文件读取凭证完成登录 - 无论哪种方式，登录成功后 Token 和租户上下文自动保存到会话文件

1. 2. 注销处理 — 当用户发送"注销"时，立即删除会话缓存文件及所有相关凭证，不保留任何登录信息
2. 先查后写 — 写操作前必须先查询目标对象确认 ID/编号
3. 写后回查 — 写操作完成后必须重新查询确认结果，不要仅凭 API 返回的 success 就判断成功
4. 多租户隔离 — 普通用户默认使用登录返回的 tenant_id；超级管理员跨租户时显式传 X-Tenant-ID Header

- 重要：当 Web 应用调用 OpenClaw 时会传递租户 ID，必须使用传入的租户 ID，禁止切换到其他租户

1. 6. 不暴露认证信息 — 最终回复中不回显 Token、密码等敏感信息
2. 批量优先 — 多个同类操作优先批量接口
3. 实时优先 — 如接口行为与本文档不符，以后端实时返回和数据库状态为准

---

🌐 系统连接信息

| 官网 | http://www.medfix.cn |

---

🚀 快速开始

Step 1: 登录获取 Token

凭证处理原则（必须遵守）：

• - 新会话已提供凭证：如果用户在发起新会话时已提供用户名和密码，Agent 将其写入 /tmp/assethub-claw-temp-session.json，调用 API 时自动完成登录，无需用户再次输入
• 未提供凭证：如果未提供，则分两步引导：先问用户名 → 用户回答后再问密码 → 收集完整后才执行登录
• 临时 Session 凭证自动登录：调用 assetclaw 时，自动检查临时凭证文件，若存在则自动登录，无需用户重复输入
• 无论哪种方式，只有在收集到用户名和密码后，才调用登录命令：

CODEBLOCK0

登录成功后 Token 和租户上下文自动保存到会话文件。

多租户选择（必须遵守）：
登录成功后，如用户拥有多个租户，应立即列出所有企业名称供用户选择：

1. 1. 从登录响应 data.enterprises 中提取所有租户
2. 以编号列表形式展示（如 1. 某某医院 2. 中国医科大学附属第四医院 3. 第四医院2）
3. 提示用户直接输入数字选择（如"请输入序号："）
4. 用户输入后，将对应 tenant_id 保存到会话文件
5. 如果用户只有一个租户，默认使用该租户，无需询问

⚠️ Web 应用调用时：如果 OpenClaw 已通过外部参数传入租户 ID（会话 metadata 中包含），则禁止切换租户，必须直接使用传入的租户 ID。

Step 1.5: 注销（退出登录）

CODEBLOCK1

当用户发送"注销"时，执行此命令删除会话缓存文件，用户将无法继续访问 API。

Step 2: 发现可用模块

CODEBLOCK2

Step 3: 调用 API

CODEBLOCK3

Step 4: Raw curl 备用方案

如 helper 脚本网络受限，直接使用 curl：

CODEBLOCK4

---

🛠️ Helper 脚本命令

环境变量

变量	说明	默认值
INLINECODE9	API 基础地址	INLINECODE10
INLINECODE11

登录用户名 | — | | ASSETHUB_API_PASSWORD | 登录密码 | — | | ASSETHUB_TENANT_ID | 显式租户 ID | 登录返回的 tenant_id | | ASSETHUB_SESSION_FILE | 会话缓存文件 | /tmp/assethub-claw-session.json |

命令列表

命令	说明
INLINECODE16	登录并缓存 Token
INLINECODE17

注销登录，删除凭证缓存文件 | | bash scripts/assethub_api.sh session | 查看当前会话状态 | | bash scripts/assethub_api.sh set-tenant <序号> | 切换当前租户（多租户用户用） | | bash scripts/assethub_api.sh modules | 列出所有 API 模块 | | bash scripts/assethub_api.sh module <path> | 查看指定模块接口文档 | | bash scripts/assethub_api.sh request GET <path> | GET 请求 | | bash scripts/assethub_api.sh request POST <path> <json> | POST 请求 | | bash scripts/assethub_api.sh request PUT <path> <json> | PUT 请求 | | bash scripts/assethub_api.sh request DELETE <path> | DELETE 请求 |

---

📊 API 模块速查

模块	路径	说明
资产	INLINECODE26	资产全生命周期管理
维修维护

/maintenance | 维修申请、工单、日志、计划与分析 | | 盘点 | /inventory /inventory-plans /inventory-tasks /inventory-discrepancies | 盘点计划、任务、差异处理 | | 调配 | /transfer | 资产调配申请与审批 | | 闲置 | /idle | 闲置资产发布与调配 | | 报废 | /scrapping | 报废申请与审批 | | 采购 | /procurement | 采购申请与审批 | | 质检 | /quality-control /quality | 计量与质量控制 | | 验收 | /acceptance | 资产验收记录 | | 文档 | /technical-documents | 技术资料上传、AI 分析 | | 折旧 | /depreciation | 折旧计算与统计 | | 部门 | /departments | 部门组织管理 | | 用户 | /users | 用户管理 | | 角色权限 | /roles-permissions | 角色、权限、菜单 | | 模块配置 | /module-configs /modules | 模块启停、配置 | | 物联网 | /iot /iot-devices | IoT 设备与数据上报 | | 资产定位 | /asset-location | 资产定位与位置数据 | | 标签 | /asset-labels | 标签模板与打印 | | 告警 | /intelligent-alerts /location-alerts | 智能告警与位置告警 | | 审计日志 | /audit-logs | 系统操作审计 | | 仪表盘 | /dashboard | 仪表盘统计 | | 工作流 | /workflow | 状态迁移规则 | | AI 分析 | /asset-ai-analysis /agent-mesh | AI 故障分析与预测 | | 库存 | /inventory | 备件库存管理 | | 备份 | /backup | 数据备份恢复 | | 系统配置 | /system-config | 数据库、IoT Token 配置 |

---

🔑 认证与请求头

标准请求头

CODEBLOCK5

登录响应解析

登录成功后，从响应中提取：

• - data.token → Bearer Token
• INLINECODE61 → 当前租户 ID
• INLINECODE62 → 用户名
• INLINECODE63 → 真实姓名
• INLINECODE64 → 角色

⚠️ 高风险操作限制

AssetHub API 对写操作有两层安全机制：

1. Idempotency-Key（防重复提交，所有写操作都需要）

• - 格式：长度 ≤ 128 的唯一字符串
• 生成方式：INLINECODE65
• Header: INLINECODE66
• 注意：即使走 AI 安全入口也需要此 Header

2. 二次风险确认（仅限普通端点，AI入口无需此步）

CODEBLOCK6

3. 报修推荐路径：AI 安全入口（绕过二次确认）

✅ 首选：POST /api/maintenance/ai/submit-request

• - 不触发二次确认闸门，一次请求完成
• 同样需要 Idempotency-Key Header
• 提交后申请自动进入待审批状态

❌ 普通端点（需二次确认）：POST /api/maintenance/requests

• - 触发二次确认流程，需两段式请求

curl 示例（AI 安全入口）：
CODEBLOCK7

错误处理

HTTP 状态码	含义	处理方式
INLINECODE70	参数错误	补全必填字段，不盲目重试
INLINECODE71

Token 无效/过期 | 重新登录 | | 403 | 无权限/租户限制 | 停止写操作，确认权限 | | 404 | 资源不存在 | 回到查询步骤 | | 429 | 接口限流 | 退避后重试 | | 500 | 服务异常 | 保留上下文，稍后重试 |

🩺 常见错误与处理（基于实测）

错误信息	含义	处理方式
INLINECODE76	写操作缺少 Idempotency-Key	添加 Header: INLINECODE77
INLINECODE78 + INLINECODE79

普通端点触发二次确认 | 用同一 Idempotency-Key + X-Risk-Confirm-Token: <confirmToken> 重放请求 | | success: false + "资产不存在" | asset_code 错误 | 重新查询资产确认编号 | | success: false + "无权限" | 租户或角色限制 | 确认当前租户和用户角色 | | HTTP 401 | Token 过期 | 删除会话文件后重新登录 |

注：API 错误信息在 JSON 响应的 message 字段中，如 INLINECODE86

❓ 常见问题

搜索中文参数返回空结果

问题： 使用中文搜索时（如 search=超声）返回空，但数据确实存在。

原因： shell 传递中文字符时存在编码问题，从非脚本目录调用时触发。

解决方案： 搜索参数包含中文时使用 URL 编码：

• - ❌ 错误：INLINECODE88
• ✅ 正确：INLINECODE89

---

📋 核心工作流

1. 资产报修流程

CODEBLOCK8

2. 资产调配流程

CODEBLOCK9

3. 盘点完整流程

CODEBLOCK10

4. 闲置资产发布流程

CODEBLOCK11

5. 报废申请流程

CODEBLOCK12

6. 采购申请流程

CODEBLOCK13

7. 文档上传审核流程

CODEBLOCK14

8. 预防性维护流程

CODEBLOCK15

9. IoT 设备注册与数据上报

CODEBLOCK16

10. 质检记录流程

CODEBLOCK17

---

🔍 查询决策树

"查某类设备"问题

CODEBLOCK18

"查询科室资产"问题 ⚠️ 重要

CODEBLOCK19

"查询调配记录"问题

CODEBLOCK20

"查询盘点状态"问题

CODEBLOCK21

"查询维修记录"问题

CODEBLOCK22

"查询资产详情"问题

CODEBLOCK23

⚠️ 全量扫描规范（适用于全面统计场景）

当用户要求"全院某类资产统计"、科室资产统计等需要完整数据时：

CODEBLOCK24

---

📖 常用 API 调用示例

资产操作

CODEBLOCK25

维修管理

CODEBLOCK26

调配/闲置/报废

CODEBLOCK27

盘点

CODEBLOCK28

采购/质检/验收

CODEBLOCK29

文档

CODEBLOCK30

预防性维护

CODEBLOCK31

折旧

CODEBLOCK32

部门/用户/角色

CODEBLOCK33

IoT/定位

CODEBLOCK34

标签打印

CODEBLOCK35

告警

CODEBLOCK36

审计/备份

CODEBLOCK37

仪表盘/统计

CODEBLOCK38

模块配置

CODEBLOCK39

工作流

CODEBLOCK40

AI 分析

CODEBLOCK41

库存管理

CODEBLOCK42

系统配置

CODEBLOCK43

---

⚠️ 重要兼容说明

维修申请字段

• - 必填: asset_code + INLINECODE91
• 兼容旧文档: 可同时传 issue_description（与 fault_description 相同值）

调配申请

• - 新版路径: INLINECODE94
• 旧版路径: POST /api/assets/{id}/transfer-apply（兼容 asset_code 参数）

闲置发布

• - publish_person 必填
• INLINECODE98 和 asset_name 至少一个

报废申请

• - 必填: asset_code, asset_name, applicant, INLINECODE103

盘点计划

• - 新版路径: /inventory-plans（推荐）
• 旧版路径: INLINECODE105

---

📤 输出格式规范

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

• - 编号/ID、名称/标题、状态
• 关联资产/部门/人员
• 创建时间/更新时间
• 关键数值（价格、数量、费用等）

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

操作结果先展示操作内容，再展示回查确认结果。

---

📍 常见设备名称映射

用户说	系统资产名称
监护仪	插件式病人监护仪
心电/心电图机

数字式多道心电图机、12导联心电图机等 |
| 呼吸机 | 呼吸机 |
| 注射泵 | 注射泵 |
| 除颤仪 | 体外除颤监护仪 |
| 血液透析 | 血液透析设备(血液透析滤过机) |
| CT | CT机、16层CT机、64排螺旋CT等 |
| 核磁共振 | 核磁共振成像设备(MRI) |
| 车辆/机动车 | 救护车、轿车、客车、旅行车、核酸检测车、铲车、装载机、电动车（指机动车，非手推车） |

---

📝 故障描述规范

报修时的描述应尽量具体：

规范	示例
✅ 正确	"显示屏不亮，无法开机"
✅ 正确

"心电导联无信号" |
| ✅ 正确 | "CT球管打火，报警E01" |
| ❌ 错误 | "坏了" / "不能用" / "故障" |

---

🔢 状态值速查

资源	状态值
资产	INLINECODE106 / 维修 / 闲置 / 调配中 / INLINECODE110
维修申请

pending / approved / in_progress / completed / cancelled |
| 调配 | pending / approved / rejected / completed |
| 盘点计划 | draft / active / completed / cancelled |
| 盘点任务 | pending / in_progress / completed / cancelled |
| 采购 | pending / approved / rejected / executed / completed |
| 报废 | pending / approved / rejected / completed |
| 质检结果 | 合格 / 不合格 / 待整改 |
| 文档审核 | pending / approved / rejected |

---

📝 经验教训（基于实际操作发现）

2026-04-02 关键发现：科室资产多字段分布问题

问题现象：

• - 查询"检验科资产"时，使用 department=检验科 参数只返回 0 条记录
• 全量扫描（遍历所有页 + 所有文本字段）后，发现检验科实际有 550 件资产

根本原因：
AssetHub 的科室信息分散存储在多个字段：

• - department — 正式科室字段（很多资产此处为空）
• INLINECODE145 — 位置字段，包含大量科室信息（如"检验科（崇山）"）
• INLINECODE146 — 使用科室字段
• INLINECODE147 — 新版科室字段

经验：

1. 1. 查询科室资产时，必须对所有文本字段做关键词匹配，不能依赖单一 department 参数
2. 全量扫描时需遍历所有页（总资产 28291 条 × 95 页）
3. 车辆识别需要排除"输液车/处置车/抢救车"等医用小型手推车

2026-04-02 发现：API 安全机制与 AI 入口

问题现象：

• - 直接调用 /maintenance/requests POST 无 Idempotency-Key → 返回"需要 Idempotency-Key"
• 带 Idempotency-Key 调用普通端点 → 触发二次确认，返回 confirmToken
• 带 Idempotency-Key 调用 AI 入口 /maintenance/ai/submit-request → 直接成功，无需二次确认

经验：

1. 1. 所有写操作必须带 INLINECODE150
2. 报修走 AI 安全入口 POST /maintenance/ai/submit-request，一次完成，不触发二次确认
3. 普通端点需两段式：第一次拿 confirmToken，第二次带 X-Risk-Confirm-Token 重放