仙木 IMS 库存管理

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install xianmu-ims
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 xianmu-ims。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

仙木 IMS 是一个 Openclaw Skills 集成，用于在本地机器、NAS 或私有网络上操作用户部署的仙木 IMS 实例。它将库存搜索、入库和出库、调拨、调整、盘点、低库存警报、物品记录、位置、供应商、附件、文档、采购、项目和 BOM 工作流结合在一个技能入口点后面。
该技能还包含一个用于创建类别和仓库位置的引导式初始化体验。它验证连接、选择初始配置方案、预览提议的配置、请求确认，并通过 MCP 执行仅限管理员的写入操作。这使得 Openclaw Skills 既适用于首次设置，又适用于安全的日常库存管理，而无需将实例数据发送到外部服务。

应用场景

检查物品可用性、库存水平、仓库位置和交易历史记录。
接收现有物品或创建新的物品记录，同时记录入库数量、供应商、成本、位置和备注。
为项目、消耗或管理员批准的报废操作处理出库库存。
在仓库位置之间移动库存并通过库存调整核对盘点数量。
创建、审核、确认或取消盘点任务并调查数量差异。
监控活跃的库存警报并确认已解决的低库存状况。
上传物品图片、重新排序附件、设置封面图片，并将技术文档与多个物品关联。
通过引导式初始化工作流配置类别和存储位置。
通过可用的 MCP 工具管理采购、项目、BOM、借用、供应商和行政主数据。
将 n8n 等自动化平台连接到用户配置的 Webhook，用于库存、警报和采购事件。

工作原理

当未提供基本地址时，通过检查默认健康检查端点来检测仙木 IMS 实例。
如果默认端点不可用，请询问用户的实例 URL，并在请求凭据之前测试提供的本地、NAS 或远程地址。
确认 BASE URL，并在可用时确认以 xmt_ 开头的 API Token。Token 决定查看者、成员或管理员权限，并受每分钟 60 次请求的限制。
选择集成路径：当客户端支持远程 MCP 时，使用位于 BASE/api/mcp 的原生 Streamable HTTP MCP 端点；当 MCP 不切实际时，使用位于 BASE/api/v1 的 REST API。
将请求路由到适当的功能工作流，例如物品搜索、入库、出库、调拨、调整、盘点、警报确认、文档管理或初始配置。
对于写入操作，重申物品、数量、目的地或配置预览并获得确认，除非用户的指令已经明确无误。
逐个项目执行批量写入，检查每个响应，并在操作失败时立即停止。
从响应的 data 字段解析成功的业务数据，并使用返回的代码、消息、HTTP 状态和详细信息解释 API 错误。
保留库存历史记录并避免破坏性端点，例如物品删除、清除、合并、禁用、设置、许可、Token 管理和用户管理。
报告已完成的操作、生成的标识符或数量，以及任何必需的后续操作（例如确认警报或复查盘点差异）。

配置指南

1. 验证连接 在尝试基于 Token 的操作之前，请使用未经身份验证的健康检查端点：
   curl -s http://127.0.0.1:8066/api/v1/health
   包含 "status": "up" 的响应确认实例处于在线状态。记录报告的 version 和 edition。如果默认地址不可用，请询问用户的实例地址（例如 http://:8066）并再次测试。
2. 需要时安装仙木 IMS 如果没有实例响应，请勿重复尝试 Token。请按照 references/setup.md 中的安装和连接指南进行操作，包括支持的 Windows 安装流程或用户选择的部署方法。实例可以运行在本地、NAS 或远程私有网络上。
3. 创建并保护 API Token 在仙木 IMS 中，打开 Settings → API Token，创建一个 Token，并仅在需要时提供给会话。Token 以明文形式显示一次，通常以 xmt_ 开头。请使用所需的最低权限：
   viewer：只读操作。
   member：正常的库存写入。
   admin：初始化写入、报废出库操作和行政工作流。
   强烈建议即使在单用户模式下也使用 Token，因为它可以启用速率限制保护和操作审计。
4. 配置 MCP 或 REST 对于支持远程 MCP 的客户端，配置 Streamable HTTP 端点：
   BASE/api/mcp
   按如下方式发送 Token：
   Authorization: Bearer xmt_
   MCP 端点公开了 67 个工具，包括 21 个读取工具和 46 个写入工具，受版本、物品数量、角色和只读限制的约束。如果 MCP 不可用，请使用具有相同授权标头和 API 前缀的 REST：
   BASE/api/v1
   OpenAPI 定义可在 BASE/api/openapi.json 获取，交互式文档位于 BASE/api/docs。
5. 初始化仓库 对于“初始化”、“创建类别”、“创建位置”或“开始使用系统”等请求，请遵循 references/onboarding.md。工作流检测当前状态、选择方案、询问一组有限的问题、预览提议的类别和位置、获取确认，并使用 admin Token 通过 MCP 写入配置。

数据架构

连接和响应约定
元素 结构或规则
REST 基本路径 BASE/api/v1
MCP 端点 使用 Streamable HTTP 的 BASE/api/mcp
身份验证 Authorization: Bearer
成功信封 { "code": "OK", "message": "ok", "data": }
错误信封 { "code": "", "message": "", "details": ... }
分页 page 和 page_size；服务器最大 200，建议 50 或更少
只读模式 将 ?mode=readonly 附加到 MCP URL
速率限制 每分钟 60 个请求
库存实体
物品： 物品名称、型号、类型、内部标识符、单位、类别、状态、位置、库存数量、供应商、图片和关联文档。
库存记录： 带有数量、用途、位置、时间戳和备注的入库、出库、调拨、调整和盘点相关交易。
位置和类别： 在初始化期间创建或通过管理工具维护的仓库放置和分类结构。
盘点： 任务、盘点明细行、待处理筛选器、清点数量、差异、确认状态和生成的调整记录。
警报： 可以在解决后进行查询和确认的活跃库存警告。
文档： 带有标题、允许的文件类型、元数据以及通过 items[] 的多对多关联的已上传文件或获取的链接。移除物品只会取消其文档的链接；删除文档是一个单独的不可逆操作。
附件： 最大尺寸为 20 MB 的物品图片，按顺序排列，以便第一个附件可以作为封面图片。
业务领域： 供应商、采购记录、项目、BOM、借用工作流和行政主数据通过 MCP 工具层公开。
参考文件
references/setup.md：连接检查、安装、Token 创建、验证和激活指导。
references/api.md：REST 端点、请求正文、参数和响应示例。
references/onboarding.md：类别和位置的初始化生命周期。
references/scenarios.md：七个初始化方案和默认模板。
references/mcp-tools.md：初始化工具名称、返回结构和命名规则。
重要错误分类
AUTH_REQUIRED 表示缺少或无效的 Token；FORBIDDEN 表示角色权限不足；EDITION_REQUIRED 表示 REST 或功能权益限制；LIMIT_EXCEEDED 表示免费版 50 个物品的限制；OUT_OF_STOCK 表示数量不足；DUPLICATE_ITEM 表示可能重复；NOT_FOUND 表示缺少实体；RATE_LIMITED 表示每分钟超过 60 个请求；READONLY_MODE 表示写入已被禁用。

高级特性

包含 67 个工具的原生 MCP 集成，涵盖库存读取、写入、库存变动、盘点、警报、采购、项目、BOM、借用、文档和行政数据。
为无法使用远程 MCP 的客户端提供 REST 后备，支持 OpenAPI 发现和 Swagger UI。
基于确认的引导式初始化，具有方案模板、幂等写入和仅限管理员的配置更改。
?mode=readonly
提供可选的 MCP 只读模式，用于演示和更安全的检查环境。
针对 viewer、member 和 admin Token 的角色感知执行，包括受保护的报废和初始化操作。
多位置库存跟踪，具有针对性的库存分布查询和交易历史记录。
从确认的盘点差异生成调整记录的盘点核对。
多对多文档关联、远程文档获取、本地上传、图片排序和封面图片管理。
带有用于库存、警报和采购自动化平台（如 n8n）的 HMAC 签名的 Webhook 兼容事件传递。
针对身份验证、权益、限制、冲突、丢失的资源、速率限制和只读环境的结构化错误处理。
安全护栏，要求在重大写入前进行确认、禁止破坏性系统端点、防止自动数据删除并在失败后停止顺序批次执行。
基于域的文档架构，允许通过
references/
文件添加新功能，同时保持单个 Openclaw Skills 入口点可维护。

name: xianmu-ims description: 闲沐 IMS 智能体操作技能（单一入口，覆盖全部功能域）。当用户要初始化配置（初始化、新手指引、建分类、建位置、规划库位、开始使用）、日常管理库存（物品档案、入库、出库、移库、盘点、预警、采购、项目/BOM、供应商、库位、图片资料），或尚未安装闲沐 IMS 需要下载安装、设置 API Token 时使用——通过用户自建的闲沐 IMS 实例 MCP / REST API 完成。触发词：闲沐、IMS、库存、入库、出库、移库、盘点、预警、库存查询、初始化、引导设置、建分类、建位置、新手指引、开始使用、安装闲沐、下载闲沐、闲沐没装、激活。 version: 1.1.0 闲沐 IMS 智能体操作技能

通过用户部署的闲沐 IMS 实例（局域网/NAS/本机）的 MCP 或 REST API 操作闲沐 IMS。本技能是闲沐 IMS 智能体能力的单一入口，按功能域分文档维护：当前含「日常库存操作」与「初始化引导」两个域，后续新域按文末「扩充规则」并入。

使用前提

步骤 0 · 连通性检测：用户没给实例地址时，先探测默认地址 curl -s http://127.0.0.1:8066/api/v1/health（免认证）——返回 "status": "up" 即实例在线，顺手记下响应里的 version 与 edition；连不上先问用户实例地址（NAS / 远程部署很常见）再探一次；仍不通说明实例可能未安装，不要硬问 Token，转 references/setup.md 走安装与接入引导。

实例可达后，向用户确认两件事（本会话内记住即可）：

实例地址（BASE，如 http://:8066，实例本机可用 http://127.0.0.1:8066）
API Token（可选但强烈建议）：用户在闲沐 IMS「设置 → API Token」新建，形如 xmt_ 开头，明文只显示一次。Token 决定操作权限（viewer 只读 / member 可写 / admin 管理），并有每分钟 60 次限流保护。初始化引导的写入（建分类/位置）需要 admin Token，详见 references/onboarding.md。实例未安装时的下载安装与 Token 设置引导见 references/setup.md。

单人模式下实例不强制认证，无 Token 也能调用；但仍建议用户提供 Token（限流保护 + 操作审计）。

接入方式选择

闲沐 IMS 同时提供两种方式，同受 Token 限流约束；权益上 MCP 走 feature.mcp（免费版权益内置，免费版 50 件条目内与专业版无差别），裸 REST 走 feature.api（专业版权益，无权益返回 403 EDITION_REQUIRED）——免费版用户优先走 MCP，二选一即可：

客户端支持远程 HTTP MCP 时，优先用 MCP：服务端原生 BASE + /api/mcp（Streamable HTTP），只填「实例地址 + Token」即得精选 67 个工具（读 21 / 写 46），零本地依赖，NAS / 远程实例同样可用。配置见文末「参考」。
客户端不支持（或不方便改配置）时，用本技能的 REST 方式：即下文全部内容。
请求约定
所有接口前缀 BASE + /api/v1；认证用请求头 Authorization: Bearer 。
成功响应是信封：{"code": "OK", "message": "ok", "data": } —— 业务数据一律从 data 里取。
失败响应：{"code": "", "message": "", "details": …}，HTTP 状态码同时给出。常见错误码：
错误码 含义 处理建议
连接失败（无 HTTP 响应/拒绝/超时） 实例未启动、未安装或地址不对 先问实例地址重探；确认未装则按 references/setup.md 引导安装并设置 Token
AUTH_REQUIRED (401) Token 缺失/无效/已吊销 请用户重新创建 Token
FORBIDDEN (403) 角色权限不足 写操作需要 member 及以上；报废（scrap）出库与初始化写入需要 admin；向用户说明
EDITION_REQUIRED (403) 无专业版权益（裸 REST / Webhook 调用） 提示改用 MCP 工具面（免费版可用），或指引用户升级专业版
LIMIT_EXCEEDED (403) 免费版物品条目已达 50 件上限（新建档类操作） 报告当前数量与上限；请用户删减条目或升级专业版（不限条目）
READONLY_MODE（仅 MCP） 实例处于只读模式 URL 带 ?mode=readonly 或演示环境时写操作不可用；确认用户是否需要只读，再决定是否改用普通地址
NOT_FOUND (404) 物品/库位/任务/父节点不存在 换关键词重查；建子级报错多半是写入顺序错了（先建父再建子）
BAD_REQUEST (400) 参数或命名冲突 如同级重名、同父同 code、大类缺 type、深度超限；按 message 提示修正
DUPLICATE_ITEM (409) 建档查重命中 向用户展示疑似重复项，确认后可用 force: true 强制建档
OUT_OF_STOCK (409) 库存不足 报告现有数量，不要擅自降低出库数
IN_USE (409) 对象仍被引用（删除时） 分类/位置改用停用（status="disabled"），其余向用户说明占用方
RATE_LIMITED (429) 超过 60 次/分 等待几十秒重试，减少请求频率
分页统一参数 page / page_size，服务端上限 200，建议 ≤50 避免撑爆上下文。
工作流

按域路由；日常操作的细节与完整参数见 references/api.md。

1. 查库存 GET /api/v1/items?q=M3&low_stock=false&page=1&page_size=20

拿到列表后，需要某物品在各库位的分布再调 GET /items/{id}/stocks；需要流水调 GET /stock/records?item_id={id}。先精确后模糊：优先用型号/内部编号查询，减少分页轮次。

2. 入库（含建档） 已有物品：POST /api/v1/stock/inbound，body 至少给 item_id + quantity（+total_price、supplier_id、location_id、remark 按需）。
   新物品一步到位：body 里不给 item_id，给 new_item（内联建档字段：name/model/type/location_id/unit 必填）+ quantity。
   建档前先 GET /items?q= 查重，命中 DUPLICATE_ITEM 时把候选给用户确认。
3. 出库 / 移库 / 调整 POST /stock/outbound：item_id + quantity + purpose（project/consume/scrap，scrap 需 admin）。
   POST /stock/transfer：item_id + to_location_id（多位置物品可加 from_location_id）。
   POST /stock/adjust：item_id + counted_qty（按实盘数调整，生成 adjust 流水）。
4. 盘点 / 预警 盘点：GET /stocktakes 找到进行中的任务 → GET /stocktakes/{task_id}/lines?filter=pending 看待盘行 → PUT /stocktakes/{task_id}/lines/{line_id} 录 counted_qty（实盘余额）。任务创建/确认/取消也有对应能力（MCP：create_stocktake / confirm_stocktake / cancel_stocktake；确认结案会按各行差异生成 adjust 流水，确认前先核对 diff 行）。
   预警：GET /alerts（默认只回 active）→ 处理完后 POST /alerts/{id}/acknowledge 确认。
5. 图片与资料 加图片：POST /items/{id}/attachments（multipart，file_type=image，≤20MB）；调整顺序/封面用 PUT /items/{id}/attachments/order（ids 须覆盖全部附件，第一张为封面）。
   加资料：链接用 POST /items/{id}/docs（后台抓取，稍后 GET /docs?item_id= 看结果）；本地文件用 POST /docs/upload（后缀白名单 pdf/docx/txt/md/png/jpg/xlsx/csv/pptx/zip 等）。
   一份资料可关联多个物品（多对多）：改显示名用 PATCH /docs/{doc_id}（body {"title": "…"}）；追加关联用 POST /docs/{doc_id}/items（body {"item_id": 123}，幂等）；解除关联用 DELETE /docs/{doc_id}/items/{item_id}（资料本身保留）。注意 GET /docs?item_id= 的含义是「包含该物品的资料」，不等于唯一归属；列表行里 items[] 才是全部关联物品。
   删除物品不会删除它名下的资料，只会解除关联（资料降级为未关联的全局资料）；资料被删除只有 DELETE /docs/{doc_id} 一条路径。
   删除图片/资料均为不可恢复操作，先向用户确认再调用。
6. 初始化引导（分类与位置一次配好）

用户表达「初始化 / 新手指引 / 帮我建分类、建位置 / 开始使用 / 规划库位」等意图时走本域：读 references/onboarding.md，严格按其中五阶段流程执行（现状检测 → 场景选择 → 场景提问 → 配置预览 → 写入执行 → 收尾），全程最多 4 问、确认后才写入、幂等可重入。场景话术见 references/scenarios.md，工具签名与命名规则见 references/mcp-tools.md。写入需 admin Token；本域只走 MCP 工具，不直接调 REST。

其他能力

采购、项目/BOM、借用、基础档案（管理员）等域 MCP 工具面已覆盖，可直接按工具签名调用；服务端 guide 工具内置 stock/purchase/project/docs 四域操作规范与初始化五阶段引导（仅接 MCP 未装本技能的客户端可直取）。专属域指南按文末「扩充规则」陆续并入。

护栏（必须遵守）
写操作前先复述确认：入库/出库/移库/调整/建档/初始化写入前，向用户复述关键内容（物品 + 数量 + 目标库位，或配置预览），得到确认再调用。用户指令已非常明确时可省略复述直接执行。
禁触端点：不要调用设置（/settings，含 AI 密钥）、授权（/license）、Token/Webhook 管理、用户管理等系统端点；也不要调用物品删除/物理删除/并库/停用（DELETE /items/{id}、/purge、/merge、/disable）——这些留给用户在界面操作。
出错不删数据：有流水的物品不可删除只能停用；写错了提示用户在界面用「冲正」功能回退，Agent 不要自行尝试补救性反向操作。
一次一步：批量写入逐条执行，每条之间检查响应；某条失败（如 OUT_OF_STOCK）就停下报告，不要跳过继续。
数量与单位照抄用户口径，不主动换算；价格字段留 0 表示未计价。
不编造工具与参数：只用本文档和 references 列出的工具与端点，不确定就先查再调。
不外发：用户的回答与实例数据只用于操作当前实例，不发送到任何外部服务。
扩充规则（新功能域如何并入本技能）

本技能是闲沐 IMS 智能体能力的唯一入口，后续新功能域按以下固定流程并入：

新增域文档：references/ 下新建域文档（如 references/procurement.md），细节全下放；「工作流」节加 2~5 行摘要 + 指针。
触发词：description 补该域触发词（整段控制在 ~500 字符内），只增不删。
护栏：域专属护栏写进域文档；全局性护栏并入本文「护栏」节。
行数纪律：本文正文 ≤ 200 行；域文档超 ~150 行或自成多轮体系时，评估升格为独立技能。
版本递增：新增域/功能章节 → 次版本 +1；话术与参考修正 → 修订号 +1；结构性重构/不兼容 → 主版本 +1。每次变更在「版本记录」表加一行。
红线：示例地址一律占位符（发布门禁拦截内网 IP / 个人绝对路径）；工具面以服务端 mcp_server.py 为准；不整抄官网 api.html；文件保持 CRLF + UTF-8 无 BOM。
双源同文：本技能的工作流要点与初始化话术，和服务端 guide 工具的话术常量（server/app/core/guide_script.py）同源维护——修改任一侧须同步另一侧。
版本记录
版本 日期 变更摘要 1.0.0 2026-09-29 基线：合并原 xianmu-ims（日常操作）与 xianmu-ims-init（初始化引导）为单一技能；初始化引导流程移至 references/onboarding.md；确立「单技能 + 分域文档」架构与扩充规则 1.0.1 2026-09-29 增补：仅接 MCP 的客户端可调服务端 guide 工具获取同款引导与各域操作规范（双源同文义务入扩充规则）；修正盘点工作流表述（任务创建/确认/取消已有 MCP 工具） 1.0.2 2026-09-29 修正：初始化引导「全新库」判定改为只看物品总数——出厂种子分类/位置是系统默认初始化内容，不作为已配置判据（与 guide_script.py、官网 skill.md 三处同文） 1.0.3 2026-09-30 口径更新（配套产品 v1.88.0 / 10 号 v3.2.1）：MCP 免费放开——权益总述与参考区改双键口径（MCP 查 feature.mcp 免费可用、裸 REST 维持 feature.api 专业版），免费版优先引导走 MCP；错误码表补 LIMIT_EXCEEDED（免费版 50 条目上限）行、EDITION_REQUIRED 行改 REST 专属 1.0.4 2026-10-01 参考修正（配套产品 v1.90.0）：mcp-tools.md 的 search_items 参数说明补 series 支持逗号分隔多值（产品端系列筛选多选） 1.0.5 2026-10-07 口径订正（配套官网 skill.md v1.0.1 三处同步）：onboarding.md 的 Token 前提与 FORBIDDEN 处置改「Token 权限跟随创建账号（创建时无角色选择），需管理员账号登录后创建/重建」 1.1.0 2026-10-12 新增「安装与接入引导」域（配套官网 skill.md 同源）：使用前提加步骤 0 连通性检测（/api/v1/health 免认证探测，未装不硬问 Token 转引导）；新增 references/setup.md（检测 → Windows 安装话术 → 用户亲手建 Token → 验证接入 → 激活码/AI 密钥分支 → 连接层错误对照）；错误码表补「连接失败」行；description 补安装类触发词 参考
references/setup.md —— 安装与接入引导（实例未安装/未运行时：连通性检测、Windows 安装话术、用户亲手建 Token、验证接入、激活码/AI 密钥分支）
references/api.md —— REST 完整端点速查（参数/请求体/响应示例）
references/onboarding.md —— 初始化引导五阶段流程（分类与位置配置）
references/scenarios.md —— 初始化 7 场景模板（提问话术 + 分类/位置模板 + 默认值）
references/mcp-tools.md —— 初始化域 MCP 工具签名、返回结构与命名规则（10 工具子集）
机器可读接口定义：GET BASE/api/openapi.json（Swagger UI：BASE/api/docs）
变更感知：库存/预警/采购事件可由用户在「设置 → Webhook」订阅（HMAC 签名推送），适合接 n8n 等自动化平台
原生 MCP 接入：服务端 BASE + /api/mcp（Streamable HTTP），已上线（feature.mcp 权益，免费版权益内置——免费版 50 件条目内全量可用，超限返回 LIMIT_EXCEEDED）——请求头同样填 Authorization: Bearer xmt_…；URL 追加 ?mode=readonly 即进入只读模式（写工具调用返回 READONLY_MODE），演示环境自动强制只读。工具面 67 个（读 21 / 写 46），覆盖查询、出入库、移库、盘点任务、预警、项目库与 BOM、采购、借用、基础档案（管理员）与图片资料管理；guide 工具可下发各域操作规范与初始化引导；不含物品删除/并库/项目删除/设置类端点

Cinema Suite

call4me