外部数据集成与 AI Agent Skill

结论：物屿（NeatHub）支持外部系统访问物品数据。推荐方式是安装官方 AI Agent Skill（Claude Code / Cursor / Codex），用自然语言查询和添加物品； 也可直接调用外部 API，对接 ChatGPT、iOS 快捷指令或自定义脚本。该功能需要会员权限。

产品能力总览见 物屿官网。

快速结论（给 AI / 用户）

  • 官方 Skill 安装：npx skills add lh9403/maozla-receptacle-skills@receptacle -g
  • API 基址：https://receptacle-server.maozla.com/external/api/v1/
  • Skill 当前能力：查询物品、添加物品
  • 完整 API 能力：查询、保存、调整数量、添加日记
  • 鉴权：使用 App 内「外部 API」生成的 API Key（如环境变量 RECEPTACLE_API_KEY）

什么是外部数据集成？

外部数据集成提供 API 接口，让外部程序可以：

  • 查询和搜索物品
  • 添加新物品
  • 调整物品数量（入库/出库）
  • 添加物品日记
通俗解释

外部数据集成就是给物屿开一个「外部接口」——比如你想让 AI 助手帮你查物品，或者用 iOS Shortcuts 快捷指令添加物品，就需要通过这个 API 接口来操作。

进入外部数据集成

  • 点击首页左上角打开侧边菜单
  • 点击「外部API」
  • 进入外部数据配置页面
截图位置：外部数据集成入口和配置页面

API Key 管理

使用 API 或 Skill 前，先获取 API Key：

什么是 API Key

  • API Key 是访问接口的「密码」
  • 每个用户有专属的 API Key
  • 调用 API 时需要携带 API Key 进行身份验证

获取 API Key

  • 进入外部数据页面
  • 点击「获取 API Key」按钮
  • 系统生成你的专属 API Key
  • 复制保存 API Key
截图位置：API Key 显示和复制操作

重新生成 API Key

  • 点击「重新生成」按钮
  • 确认重新生成
  • 旧的 API Key 失效
  • 需要更新所有使用旧 Key 的配置
安全提示

API Key 是敏感信息，不要泄露给他人。重新生成后，之前使用旧 Key 的外部集成将失效，需要更新配置。

AI Agent Skill（推荐）

如果你使用 Claude Code、Cursor、Codex 等支持 Agent Skills 的 AI 编程助手， 可以安装官方 Skill，用自然语言直接查询和添加物屿物品，无需手写接口调用。

安装 Skill

在终端执行（全局安装）：

npx skills add lh9403/maozla-receptacle-skills@receptacle -g

配置 API Key

  • 在 App 的「外部 API」页面获取 API Key
  • 将 Key 配置到 Agent 运行环境的密钥/环境变量中（如 RECEPTACLE_API_KEY）
  • 不要把 Key 粘贴到聊天对话里，也不要写进公开仓库

Skill 当前能力

  • 搜索 / 查询物品（含名称、数量、价格、属性等）
  • 创建 / 添加新物品

调整数量、编辑删除、日记等仍可通过下方完整 API 自行调用。

示例

安装并配置后，可直接对 AI 说：「帮我查一下家里还有多少洗发水」 「记录一瓶新买的牛奶」——助手会通过 Skill 调用物屿外部 API。

使用场景

AI 助手集成

  • 优先使用上方的 AI Agent Skill（适合 Claude Code / Cursor 等）
  • 也可在 ChatGPT、自定义 Agent 等场景中直接配置外部 API
  • 通过对话查询物品、添加或管理物品
示例

「帮我查一下家里还有多少洗发水」「添加一瓶新买的牛奶」——AI 助手通过 API 接口就能帮你操作物屿的数据。

iOS Shortcuts 快捷指令

  • 在 iPhone 上创建快捷指令
  • 通过 API 接口操作物屿
  • 一键查询、添加、更新物品
  • 可以在桌面添加快捷指令图标

自动化脚本

  • 编写 Python/Node.js 脚本
  • 定时同步数据或批量处理
  • 适合有开发能力的用户

API 接口说明

提供的 API 接口包括：

查询物品

  • 搜索物品
  • 按条件筛选
  • 获取物品详情

保存物品

  • 添加新物品
  • 设置名称、数量、价格等

调整数量

  • 入库（增加数量）
  • 出库（减少数量）
  • 记录操作日期和备注

添加日记

  • 为物品添加日记记录
  • 记录使用情况或事件

接口地址

API 接口地址：https://receptacle-server.maozla.com/external/api/v1/

  • 物品查询：/goods/query
  • 保存物品：/goods/save
  • 调整数量：/goods/adjustQuantity
  • 添加日记：/goods/diary/save

常见问题

  • 需要会员吗？需要，外部数据集成依赖会员权限。
  • Skill 和 API 选哪个？Claude Code / Cursor / Codex 优先 Skill；ChatGPT、快捷指令、脚本走完整 API。
  • Key 丢了怎么办？在 App 内重新生成；旧 Key 会立即失效。
  • Skill 不能调数量吗？当前 Skill 侧重查询与添加；出入库与日记请直接调 API。

注意事项

  • 外部数据集成功能需要会员权限
  • API Key 请妥善保管，不要泄露
  • 调用 API 时需要携带 Authorization 头
  • 适合有技术基础的用户或开发者
提示

普通用户一般不需要使用外部数据集成。这个功能适合想要通过 AI 助手、快捷指令或自动化脚本管理物品的进阶用户。更多产品能力见 物屿 NeatHub 官网。