映射助手
映射助手是面向客户的 AI Skill(包名 olink-assist):装进 Cursor / Claude Code 等支持 Skills 的助手后,可在同局域网连接你的 Olink,协助分析已接入设备、起草自定义映射,并一键配置出口(如 HomeKit)。
适合:系统内置映射不覆盖的型号、需要调整出口侧表现、或希望 AI 带着走完「分析 → 映射 → 配对」的客户。
下载
日常只需下载 zip;查当前线上版本可看 VERSION 或 manifest.json。
环境要求
- Node.js ≥ 18(命令行执行助手自带的
olink-ca) - 本机可执行 unzip(用于安装与自更新)
- 电脑与运行 Olink 的设备在 同一局域网(建议 Olink 使用固定 IP)
- 已能打开 Olink Web 控制台(参见 快速开始)
安装
在你的项目或助手工作区根目录执行(路径可按实际调整):
mkdir -p .agents/skills
curl -fsSL -o /tmp/olink-assist.zip \
https://release.hperfect.cn/skills/olink-assist.zip
unzip -o /tmp/olink-assist.zip -d .agents/skills/安装后目录应为 .agents/skills/olink-assist/。若你的 AI 工具使用其他 Skills 目录,把解压结果放到该工具要求的位置即可,目录名保持 olink-assist。
在对话里说明要用「映射助手 / olink-assist」时,助手应能加载该 Skill。
更新
安装后可用自带 CLI 检查与覆盖安装:
CA="node .agents/skills/olink-assist/scripts/olink-ca/bin/olink-ca.mjs"
$CA version # 本地版本
$CA update-check # 对比远程 manifest
$CA self-update # 有新版本则下载 zip 覆盖
$CA self-update --force # 强制重装远程包也可重新下载 zip,再次解压到同一目录覆盖。
使用流程
以下命令均通过映射助手自带的 olink-ca 执行。建议先设别名:
CA="node .agents/skills/olink-assist/scripts/olink-ca/bin/olink-ca.mjs"
# 之后用: $CA <命令>也可以直接让 AI 按 Skill 说明帮你跑这些步骤;你只需在关键节点确认(分析结论、TOML 内容、写设备操作等)。
1. 连接 Olink
$CA connect http://<Olink的IP>:<端口>例如 http://192.168.1.10:5512。也可用本机前端代理地址(如 http://localhost:5173),只要指向同一 Olink 实例即可。
2. 授权(API Token)
$CA token ensure按提示在浏览器打开 Olink 设置页,创建并回传 永久 Token。若自动回传失败,可在设置页复制 Token 后手动添加:
$CA token add --name olink-assist --token olk_…请勿把 Token 发到公开群聊、截图外传或提交进公开仓库。
3. 选择设备
$CA devices list
$CA device show <did或名称>确认要接入的 did / model 等信息。
4. 接入前分析(先看结论再动手)
$CA mapping analyze <did>助手会给出能否接入、建议的 HomeKit 服务/配件类别、读写路径与风险。请先确认分析报告,再进入写映射;结论为「不建议接入」时不要强行继续。
5. 自定义映射
映射只写入你实例上的 自定义 mapping_rules,不会改 Olink 发行包里的系统映射。
典型顺序:起草 TOML → 给你确认 → 保存草稿 → 应用到实例。AI 会按 Skill 要求附带 did / model / author / note 等元数据,便于以后导出与排查。
6. 适配器接入与出口单配件
若设备尚未经适配器纳入 Olink,需先做 lifecycle 接入(可由助手调用相关 API)。成功后设备 did 通常带适配器域前缀(如 mijia.<原did>)。
再一键配置 HomeKit 等出口单配件:
$CA hap one-click <olink-did> --single按输出的配对码 / 二维码信息,在手机「家庭」App 中添加配件。HomeKit 侧操作也可对照 HomeKit 桥接与配件。
7. 没效果时
若 Home 里有控件但设备不动、模式反了等:不要只反复改映射文件。让助手进入现场米家调试(读属性、经你确认后写属性 / 调 action、看操作日志),用现象再改映射。写设备操作默认 dry-run,确认后才会真正下发。
8. 导出
可将本批自定义映射导出到本机,便于备份或反馈:
$CA mapping export --batch <id>
# 或
$CA mapping export --all-custom导出目录在 ~/.olink/olink-assist/<instance_id>/exports/。
使用注意
- 先分析、再写映射、再配对;分析未确认前不要 apply / 一键 HomeKit。
- 只使用 自定义映射;系统内置映射仅作对照,不要指望本助手去改发行包内文件。
- Token、配对码等敏感信息仅保存在本机会话目录,勿对外传播。
- 摄像头等特殊品类有单独能力边界,见 摄像头 与常见问题中的摄像头专题。