一见技能注册与使用指南
> Baidu Yijian Vision - Professional vision AI agent for image/video analysis, object detection, safety monitoring, and industrial inspection.
⚠️ 必需条件
此工具需要以下条件才能运行：
- YIJIAN_API_KEY 环境变量（必需）- 从一见平台获取
- Node.js >= 16.0.0 - 本工具依赖 Node.js 运行时
- npm >= 8.0.0 - 用于依赖管理和安装
如果缺少上述任何条件，工具将无法运行。
详见 安装指南 了解详细配置步骤。
> 🔒 客户端工具 - 这是一个本地工具，用于与百度一见平台交互。所有数据处理遵循安全协议。详见 安全说明。
🎯 此工具的功能
一见（yijian-next.cloud.baidu.com）是百度的视觉理解平台。此工具使你能够：
- 注册技能 - 从一见平台本地注册检测技能
- 调用技能 - 使用图像或视频帧调用已注册的技能
- 可视化结果 - 绘制边框、生成网格参考、预览 ROI/绊线
- 定义检测区域 - 使用交互式工作流定义 ROI（电子围栏）或绊线（检测线）
支持的检测类型： 人员检测、行人计数、车辆识别、OCR、姿态估计、目标跟踪等。
📋 快速开始
系统要求
- Node.js >= 16.0.0
- npm >= 8.0.0
- YIJIAN_API_KEY 环境变量
💡 详见 安装指南 获取详细说明
🔧 前置条件
获取 API Key
- 登录 一见平台
- 激活试用包
- 生成 API Key（一见平台 → 系统管理 → 安全认证 → API Key）
配置环境
设置环境变量：
YIJIAN_API_KEY=your-api-key
📚 使用指南
按意图筛选技能
当用户描述需求但不确定用哪个技能时，先读取技能列表筛选匹配的技能：
-
读取技能列表：
bash node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/list.mjs -
根据用户意图筛选匹配的技能（如"检查是否有猫"、"检测人员摔倒"）
-
确认技能后调用：
bash echo '{"input0":{"image":"photo.jpg"}}' | node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs <ep-id> ${CLAUDE_PLUGIN_ROOT} -
基本工作流
# 1. 列出可用技能（预设和已注册的）
node scripts/invoke.mjs --list
# 2. 调用一个技能
echo '{"input0":{"image":"photo.jpg"}}' | node scripts/invoke.mjs ep-xxxx-yyyy
# 3. 可视化或显示结果（可选）
node scripts/visualize.mjs photo.jpg '<result-json>'
或先注册一个技能再使用：
# 注册技能
YIJIAN_API_KEY=${YIJIAN_API_KEY} node scripts/register.mjs ep-xxxx-yyyy
# 然后调用
echo '{"input0":{"image":"photo.jpg"}}' | node scripts/invoke.mjs ep-xxxx-yyyy
定义检测区域
需要定义电子围栏（ROI，又叫感兴趣区域）或绊线（Tripwire，又叫检测线）？
- ROI 工作流 — 创建电子围栏，仅在指定区域检测
- 绊线工作流 — 绘制检测线，统计穿越事件
两个工作流都包含完整的交互步骤和示例对话。
查看完整文档
- 安装指南 — 详细的安装和配置说明
- 安全说明 — 数据安全和隐私说明
- 类型定义 — 检测（Detection），图像（Image）、电子围栏（ROI）、绊线（Tripwire）等数据结构
- 可视化指南 — 显示检测结果、生成网格
- 视频帧提取 — 从视频提取帧进行检测
- 网格输入系统 — 使用网格坐标指定点
💡 常见任务
注册一个技能
获得 ep-id 后：
YIJIAN_API_KEY=${YIJIAN_API_KEY} node scripts/register.mjs <ep-id>
调用一个技能
echo '{"input0":{"image":"photo.jpg"}}' | node scripts/invoke.mjs <ep-id>
带有 ROI：
echo '{"input0":{"image":"photo.jpg","roi":{...}}}' | node scripts/invoke.mjs <ep-id>
带有绊线：
echo '{"input0":{"image":"photo.jpg","tripwire":{...}}}' | node scripts/invoke.mjs <ep-id>
预览 ROI/绊线
在调用前在图像上预览：
node scripts/visualize.mjs photo.jpg '[]' preview.png \
--overlays '[{"kind":"ROI","name":"zone","points":[...]}]'
生成网格
帮助用户使用网格坐标指定点位置：
node scripts/show-grid.mjs photo.jpg grid.png
📋 使用示例
示例 1：基本检测工作流
场景： 你有一张监控画面图像，想使用预设一见技能检测摔倒的人员。
# 第 1 步：列出可用技能
node scripts/list.mjs
# 第 2 步：调用技能
echo '{"input0":{"image":"surveillance.jpg"}}' | \
node scripts/invoke.mjs ep-public-inqm15aq
# 第 3 步：可视化结果
detections='[{"bbox":[150,200,80,180],"confidence":0.94,"category":{"id":"person","name":"人体"}}]'
node scripts/visualize.mjs surveillance.jpg "$detections" output.jpg
# 第 4 步：处理结果
echo "$detections" | jq 'length' # 计数人数
示例 2：基于网格的 ROI 设置
场景： 在走廊监控摄像机中计数进入特定房间的人员，使用 ROI 限制检测区域。
# 第 1 步：生成网格参考
node scripts/show-grid.mjs hallway.jpg --cols 6 --rows 4
# 第 2 步：根据网格识别坐标（B1, D1, D3, B3）并创建 ROI
roi='{"kind":"ROI","points":[320,270,960,270,960,810,320,810]}'
# 第 3 步：验证 ROI
node scripts/visualize.mjs hallway.jpg '[]' roi_preview.jpg \
--overlays "[{\"kind\":\"ROI\",\"name\":\"doorway\",\"points\":[320,270,960,270,960,810,320,810]}]"
# 第 4 步：使用 ROI 运行检测
echo "{\"input0\":{\"image\":\"hallway.jpg\",\"roi\":$roi}}" | \
node scripts/invoke.mjs ep-public-2403um2p
示例 3：视频帧处理和跟踪
场景： 处理 30 秒监控视频，逐帧检测和跟踪人员。
# 第 1 步：提取帧
ffmpeg -i surveillance_30sec.mp4 -vf fps=1 frames/frame_%04d.jpg
# 第 2 步：计算 sourceId（视频标识符）
sourceId=$(head -c 65536 surveillance_30sec.mp4 | md5sum | awk '{print substr($1, 1, 16)}')
# 第 3 步：处理每个帧并跟踪
for frame_file in frames/frame_*.jpg; do
frame_num=$(basename "$frame_file" | grep -oE '[0-9]+' | head -1)
frame_index=$((10#$frame_num - 1))
timestamp=$((frame_index * 1000))
imageId="frame_$(printf '%04d' "$frame_num")"
frame_data="{\"file\":\"$frame_file\",\"sourceId\":\"$sourceId\",\"imageId\":\"$imageId\",\"timestamp\":$timestamp}"
result=$(echo "{\"input0\":{\"image\":$frame_data}}" | \
node scripts/invoke.mjs ep-public-2403um2p)
detections=$(echo "$result" | jq '.outputs[0].parsedValue')
echo "$detections" > "results/${imageId}_detections.json"
done
API Key 从 YIJIAN_API_KEY 环境变量读取。所有脚本将 JSON 输出到标准输出，错误输出到标准错误。
