API 文档 专业版

概述与约定

• Base URL：{你的实例地址}/api/v1，例如 http://192.168.1.10:8066/api/v1；
• 响应信封：成功统一为 {"code":"OK","message":"ok","data":…}，业务数据在 data 里；错误返回 {"code":"错误码","message":…}；
• 限流：按 Token 每分钟 60 次，超限返回 429 RATE_LIMITED——脚本侧请做分页合并（分页 page_size 建议 ≤50，服务端上限 200）；
• 机器可读契约：完整接口定义见 /api/openapi.json（Swagger UI 在 /api/docs）；
• 角色：Token 继承其所属用户的角色——读接口需 viewer 及以上，写接口需 member 及以上，「报废」出库需 admin；日期参数支持 YYYY-MM-DD。

Token 认证

1. 登录系统，进「设置 → API Token」，点「新建」；
2. Token 以 xmt_ 开头，明文只在创建时显示一次，请立即保存（落库的是哈希，丢了只能吊销重建）；
3. 所有请求带请求头 Authorization: Bearer xmt_…；
4. 不用了随时在设置页吊销，立即失效。

curl -s -H "Authorization: Bearer xmt_你的Token" \
  "http://你的实例:8066/api/v1/items?page=1&page_size=5"

接口总览

以下为常用精选面，全部路径相对 /api/v1：

读接口（viewer+）

写接口（member+）

删除类（DELETE /items/{id} 等）、系统设置、授权、Token 与用户管理接口不对 Token 开放；流水冲正仅限界面操作，防止脚本误操作连环放大。

调用示例

搜索物品

curl -s -H "Authorization: Bearer $XMT" \
  "$BASE/api/v1/items?q=M3%E8%9E%BA%E4%B8%9D&page=1&page_size=20"

建档（含期初数量）

curl -s -X POST "$BASE/api/v1/items" \
  -H "Authorization: Bearer $XMT" -H "Content-Type: application/json" \
  -d '{"name":"M3×8 内六角螺丝","model":"M3x8","type":"PRT","location_id":12,
       "unit":"颗","quantity":200,"safety_stock":50,"tags":["紧固件"]}'

入库

curl -s -X POST "$BASE/api/v1/stock/inbound" \
  -H "Authorization: Bearer $XMT" -H "Content-Type: application/json" \
  -d '{"item_id":34,"quantity":100,"total_price":25.8,"supplier_id":3,"remark":"补货"}'

Webhook

在「设置 → Webhook」配置接收地址，库存相关事件会 POST 到你的端点（JSON）。当前事件：

事件在业务事务内入队、后台轮询投递；带 HMAC-SHA256 签名头 X-Xianmu-Signature（密钥在建 Webhook 时生成），失败退避重试 3 次，投递记录可查、可发测试事件。验签示例（Python）：

import hmac, hashlib

def verify(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# signature 取请求头 X-Xianmu-Signature；body 为原始请求体字节

智能体接入 专业版 · v1.1.0

开放 API 的产品化形态：让 AI 编码助手与通用智能体直接操作库存——问一句「A 柜还剩多少 M3 螺丝」，或说「把这批料入库到 A 柜二层」。两种形态：

• MCP（推荐，内置端点）：服务端原生 /api/mcp（Streamable HTTP），客户端只填「实例地址 + Token」即得精选工具面（查询 11 个 + 写入 14 个，含图片与资料管理），零本地依赖，NAS / 远程实例同样可用；支持 ?mode=readonly 只读模式——「只让 AI 查库存」的安心开关，演示实例自动强制只读；
• Skill（技能文件）：把随发布包提供的 xianmu-ims 技能文件夹放进 Claude Code / ZCode / Cursor 的技能目录，Agent 即按本文接口约定查库存、办出入库 / 盘点，内置「写操作先确认、限流合并查询」等护栏，适合不想配 MCP 的编码类 Agent。

状态与护栏说明：MCP 端点随 v1.1.0 提供（正式发布前对外统一标注 v1.1.0）；两者属专业版权益（feature.api），免费版权益的 Token 调用返回 403 EDITION_REQUIRED。写工具内置护栏：报废出库需 admin 角色、流水冲正不开放给智能体（记错请登录界面操作）；注意 MCP 的 update_item 为部分更新语义（REST 的 PUT /items/{id} 是全量语义）。

各工具接入配置

所有 MCP 客户端接入都只需要三样东西：

• 服务地址：http://你的实例:8066/api/mcp（只读加 ?mode=readonly）；
• 请求头：Authorization: Bearer xmt_你的Token（在「设置 → API Token」创建，见 上文）；
• 类型：HTTP / Streamable HTTP（不要选 stdio / 本地命令类型）。

地址必须是运行客户端的那台机器能访问到的地址：同局域网填 NAS / 电脑的内网 IP（如 192.168.1.10），客户端装在实例本机才可用 127.0.0.1。以下示例统一用 192.168.1.10:8066，请替换成你的实际地址与 Token。

Claude Desktop（桌面版 · 已实测连通）

1. 打开配置文件：设置 → 开发者 → 编辑配置，或直接编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）/ ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）；
2. 加入如下配置后完全退出并重启 Claude Desktop；
3. 新对话里点输入框的工具图标，应能看到「xianmu-ims」的 25 个工具。

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "http://192.168.1.10:8066/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" }
    }
  }
}

Claude Code（命令行）

在项目目录执行一条命令即可（全局可用加 --scope user）：

claude mcp add --transport http xianmu-ims "http://192.168.1.10:8066/api/mcp" \
  --header "Authorization: Bearer xmt_你的Token"

# 验证：列出已接入的 MCP 与工具
claude mcp list

Cursor（已实测连通）

1. 设置 → MCP & Integrations，点「New MCP Server」，Cursor 会打开 mcp.json；
2. 填入与 Claude Desktop 相同结构的配置：

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "http://192.168.1.10:8066/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" }
    }
  }
}

保存后回到 MCP 列表，xianmu-ims 显示绿色圆点即连接成功。Agent 模式下直接对话即可。

Qoder

Qoder 同样采用 mcpServers JSON 结构：在客户端的 MCP 设置中添加服务，或直接在项目根目录放 .mcp.json，内容与上面 Cursor 的配置完全一致（入口名称随版本可能不同，认准「MCP / 工具」设置项即可）。

WorkBuddy（已实测全部工具连通）

1. 左侧导航「专家 · 技能 · 连接器」→「连接器」，进入连接器页后点「自定义连接器」（或在「MCP 服务管理」弹窗右上角点「＋ 添加 MCP」）；
2. WorkBuddy 采用标准 mcpServers JSON 配置（配置文件路径 %USERPROFILE%\.workbuddy\mcp.json，在编辑器里直接修改），填入下面的内容并保存；
3. 回到「MCP 服务管理」列表：xianmu-ims 显示绿点、工具全部显示「已启用」（当前版本 25 个）即接入成功；列表里可随时用开关启用 / 停用、刷新或删除。

{
  "mcpServers": {
    "xianmu-ims": {
      "url": "http://192.168.1.10:8066/api/mcp",
      "headers": { "Authorization": "Bearer xmt_你的Token" },
      "disabled": false
    }
  }
}

提示：列表页的「MCP Hub」是服务市场入口，与本接入无关；「连接器」页的搜索框用于检索已有连接器，自定义接入走「自定义连接器」按钮。

ZCode 及其他编码类客户端

ZCode 等编码类 Agent 客户端普遍兼容同一套 mcpServers JSON：在对应的 MCP 配置文件或客户端设置里添加同构配置即可。若客户端不支持远程 HTTP 型 MCP，可改用 Skill 方式——把 xianmu-ims 技能文件夹复制到其技能目录（如 ~/.claude/skills/、.zcode/skills/），Agent 会按技能文件走 REST API 操作库存，效果等价。

Cherry Studio 等对话类客户端

「设置 → MCP 服务器 → 添加」：类型选流式 HTTP（Streamable HTTP），URL 填服务地址，请求头填 Authorization: Bearer xmt_你的Token，开启后即可在对话中直接调用库存工具。

接入后怎么验证

1. 客户端工具列表里出现「xianmu-ims」的 25 个工具（search_items、inbound、outbound 等）；
2. 先试只读问题：「现在有多少条低库存预警？」；
3. 需要放开写入时，把地址换成完整模式重新连接；不确定就让 AI 先用只读跑几天。

接入常见问题

错误码

接口问题与集成咨询：服务 QQ 7740840 · kf@wwzu.com。