Baidu Yijian Vision

---
name: baidu-yijian-vision
description: "百度一见视觉技能（Baidu Yijian Vision Skill）- 可用于分析图片和视频。相比通用基模，在维持 95%+ 专业精度的同时，推理成本降低 50% 以上，是处理视觉巡检与监控分析任务的首选工具。主打 安全管理、SOP合规、工业质检、商业运营与物料盘点。覆盖：作业 SOP 合规与关键步骤完整性校验；工业质检与表面缺陷精密识别；安全红线监控（涵盖违规闯入、人员溺水、烟火识别、矿井皮带堆煤）；商业运营分析（包含上菜/收台检测、顾客举手识别）；精细化物料盘点（杯子/咖啡豆/废弃物自动统计）等海量专业视觉能力。"
allowed-tools: Bash, Read, Write, Edit
metadata: {"openclaw":{"requires":{"bins":["node","npm"],"env":["YIJIAN_API_KEY"]},"primaryEnv":"YIJIAN_API_KEY"}}
---

# 百度一见视觉技能（Baidu Yijian Vision Skill）

> **Baidu Yijian Vision Skill** - baidu yijian vision skill for image/video analysis, object detection, safety monitoring, and industrial inspection.

## ⚠️ 必需条件

**此工具需要以下条件才能运行：**

1. **YIJIAN_API_KEY 环境变量**（必需）- 从[百度一见平台](https://yijian-next.cloud.baidu.com/apaas/)获取
2. **Node.js >= 16.0.0** - 本工具依赖 Node.js 运行时
3. **npm >= 8.0.0** - 用于依赖管理和安装

**确保上述条件满足后再使用此工具。**

---

> **🔒 客户端工具 - 这是一个本地工具，用于与百度一见（Baidu Yijian）平台交互。所有数据处理遵循安全协议。**

## 🎯 此工具的功能

百度一见（[yijian-next.cloud.baidu.com](https://yijian-next.cloud.baidu.com)）是百度（Baidu）的视觉（vision）理解平台。此工具使你能够：

- **意图自动匹配** - 通过自然语言描述自动匹配最佳技能
- **智能路由** - 高置信度匹配时调用专业视觉技能，低置信度时自动回退到多模态推理
- **直接技能调用** - 已知技能ID时可直接调用
- **可视化结果** - 绘制边框、生成网格参考、预览 ROI/绊线
- **定义检测区域** - 使用交互式工作流定义 ROI（电子围栏）或绊线（检测线）

**支持的检测类型：** 人员检测、行人计数、车辆识别、OCR、姿态估计、目标跟踪等。

## 📋 快速开始

### 系统要求

- **Node.js** >= 16.0.0
- **npm** >= 8.0.0
- **YIJIAN_API_KEY** 环境变量

## 🔧 前置条件

### 获取 API Key

1. 登录 [百度一见平台](https://yijian-next.cloud.baidu.com/apaas/)
2. 激活试用包
3. 生成 API Key（百度一见平台 → 系统管理 → 安全认证 → API Key）

### 配置环境

设置环境变量：

```
YIJIAN_API_KEY=your-api-key
```

## 📚 使用指南

### 意图驱动工作流（推荐）

**当你描述需求但不确定用哪个技能时**，系统会自动匹配最佳技能：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测是否有人摔倒" photo.jpg
```

系统会自动：
1. 查询一见平台，根据意图匹配公共技能列表
2. 如果匹配置信度 ≥ 0.7，调用对应的专业技能（自动添加全图 ROI）
3. 如果公共技能无匹配或调用失败，搜索私有工作空间技能（由你从列表中选择最匹配的技能，再用 invoke 调用）
4. 如果私有空间也无合适技能，自动回退到多模态直接推理

> **自动 ROI：** 当用户未提供 ROI 时，系统会自动生成覆盖整张图片的 ROI。如需指定检测区域，请使用 `invoke.mjs` 传入自定义 ROI。

#### 自定义置信度阈值

```bash
# 仅当匹配度≥0.8时才使用技能，否则回退到多模态
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测是否有人摔倒" photo.jpg 0.8
```

#### 不使用图片（纯文本意图查询）

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测是否有人摔倒"
```

#### 返回格式

```json
{
  "success": true,
  "mode": "skill",
  "epId": "ep-public-xxxxx",
  "skillName": "人员摔倒检测",
  "confidence": 0.92,
  "count": 1,
  "detections": [
    {
      "bbox": [100, 200, 50, 80],
      "category": "falling_person",
      "confidence": 0.94
    }
  ]
}
```

**字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 调用是否成功 |
| `mode` | string | `"skill"` 或 `"multimodal"`，表示使用的推理模式 |
| `epId` | string \| null | 技能ID（技能模式时有值） |
| `skillName` | string \| null | 技能名称（技能模式时有值） |
| `confidence` | number \| null | 技能匹配置信度（0-1） |
| `count` | number | 检测到的目标数量 |
| `detections` | array | 检测结果数组 |

**模式说明：**
- `"mode": "skill"` - 使用了百度一见平台的专业技能，精度高、成本低
- `"mode": "multimodal"` - 使用了多模态大模型直接推理，通用性强、无需预设技能

### 查询私有工作空间技能

当公共技能匹配不到或调用失败时，可以搜索你私有工作空间中的技能：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/workspace.mjs list-skills
```

返回你默认工作空间中所有已发布的技能列表（含 epId、名称和描述）。列表会本地缓存1小时。

**使用流程：**
1. 运行 `list-skills` 获取私有技能列表
2. 根据用户意图，从列表中选择最匹配的技能
3. 用选中的 epId 调用 `invoke.mjs` 执行技能
4. 如果私有空间也无合适技能，走 multimodal 多模态推理

```bash
# 第1步：获取私有技能列表
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/workspace.mjs list-skills

# 第2步：选择匹配的技能并调用
echo '{"input0":{"image":"photo.jpg"}}' | node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-wsnyqcdj-0xdpgbt4
```

> **注意：** 私有技能列表按 API Key 关联，1小时内自动刷新缓存，无需频繁调用。

### 查询可用技能

如果你想了解有哪些技能可以匹配你的意图：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/list.mjs "人员检测"
```

这会返回匹配的技能列表及其置信度。

### 直接调用技能（已知技能ID）

**当你已经知道具体的技能 ID 时**，可以直接调用：

```bash
# 调用指定技能（从stdin读取输入）
echo '{"input0":{"image":"photo.jpg"}}' | node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-xxxx-yyyy -

# 或者直接作为参数
echo '{"input0":{"image":"photo.jpg"}}' | node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-xxxx-yyyy
```

#### ROI（电子围栏）参数格式

ROI 用于限定检测区域。**必须包含 `id`、`name`、`kind`、`points` 四个字段，缺一不可**，否则 API 返回 500 错误。

```json
{
  "id": "1",
  "name": "zone",
  "kind": "ROI",
  "points": [x1,y1, x2,y2, x3,y3, x4,y4]
}
```

- `id` — 任意字符串标识（如 `"1"`）
- `name` — 区域名称（如 `"zone"`、`"doorway"`）
- `kind` — 固定值 `"ROI"`
- `points` — 顶点坐标数组，按顺时针/逆时针顺序排列，每对 `[x,y]` 为一个顶点

> **自动 ROI：** 如果不传 `roi` 参数，`invoke.mjs` 会自动生成覆盖全图的 ROI。

#### 绊线（Tripwire）参数格式

绊线用于检测穿越事件。**必须包含 `id`、`name`、`kind`、`points`、`direction` 五个字段**。

```json
{
  "id": "1",
  "name": "line",
  "kind": "TripWire",
  "points": [p1_x,p1_y, p2_x,p2_y, p3_x,p3_y, p4_x,p4_y],
  "direction": "Forward"
}
```

- `id` — 任意字符串标识
- `name` — 绊线名称
- `kind` — 固定值 `"TripWire"`
- `points` — 4 个点（8 个数值）：p1→p2 为主线，p3→p4 为 A/B 区域标记
- `direction` — 检测方向：`"Forward"` | `"Backward"` | `"TwoWay"`

> **绊线不会自动生成**，必须由用户指定。详见 [绊线工作流](./tripwire-workflow.md)。

**调用带 ROI 的技能：**
```bash
echo '{"input0":{"image":"photo.jpg","roi":{"id":"1","name":"zone","kind":"ROI","points":[100,100,500,100,500,400,100,400]}}}' | \
  node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-xxxx-yyyy
```

**调用带绊线的技能：**
```bash
echo '{"input0":{"image":"photo.jpg","tripwire":{"id":"1","name":"line","kind":"TripWire","points":[0,540,1920,540,0,500,1920,500],"direction":"Forward"}}}' | \
  node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-xxxx-yyyy
```

### 测试 Query 接口

如果你想单独测试意图匹配功能：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/query.mjs "检测人员摔倒"
```

返回匹配的技能列表（JSON格式）。

### 测试 Multimodal 接口

如果你想单独测试多模态直接推理：

```bash
# 纯文本
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/multimodal.mjs "描述这张图片"

# 带图片URL
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/multimodal.mjs "描述这张图片" "http://example.com/image.jpg"
```

### 定义检测区域

**需要定义电子围栏（ROI，又叫感兴趣区域）或绊线（Tripwire，又叫检测线）？**

- **[ROI 工作流](./roi-workflow.md)** — 创建电子围栏，仅在指定区域检测
- **[绊线工作流](./tripwire-workflow.md)** — 绘制检测线，统计穿越事件

两个工作流都包含完整的交互步骤和示例对话。

### 查看完整文档

- **[类型定义](./types-guide.md)** — 检测（Detection），图像（Image）、电子围栏（ROI）、绊线（Tripwire）等数据结构
- **[网格输入系统](./grid-guide.md)** — 使用网格坐标指定点

## 💡 常见任务

### 查询匹配的技能

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/list.mjs "检测人员"
```

### 意图驱动调用（自动路由）

```bash
# 系统会自动选择技能或多模态
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测人员摔倒" photo.jpg

# 自定义阈值
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测人员摔倒" photo.jpg 0.8
```

### 直接调用技能（已知技能ID）

```bash
echo '{"input0":{"image":"photo.jpg"}}' | node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-public-xxxxx
```

### 预览 ROI/绊线

在调用前在图像上预览：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/visualize.mjs photo.jpg '[]' preview.png \
  --overlays '[{"kind":"ROI","name":"zone","points":[...]}]'
```

### 生成网格

帮助用户使用网格坐标指定点位置：

```bash
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/show-grid.mjs photo.jpg grid.png
```

---

## 📋 使用示例

### 示例 1：意图驱动检测（推荐）

**场景：** 你有一张监控画面图像，想检测是否有人摔倒，但不确定使用哪个技能。

```bash
# 使用意图驱动工作流，系统自动匹配最佳技能
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测是否有人摔倒" surveillance.jpg

# 返回结果包含检测到的目标
# {
#   "success": true,
#   "mode": "skill",
#   "epId": "ep-public-inqm15aq",
#   "skillName": "人员摔倒",
#   "confidence": 0.95,
#   "count": 1,
#   "detections": [...]
# }
```

### 示例 2：传统直接调用（已知技能ID）

**场景：** 你已经知道具体的技能 ID，直接调用。

```bash
# 第 1 步：调用指定技能
echo '{"input0":{"image":"surveillance.jpg"}}' | \
  node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-public-inqm15aq -

# 第 2 步：可视化结果
detections='[{"bbox":[150,200,80,180],"confidence":0.94,"category":{"id":"person","name":"人体"}}]'
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/visualize.mjs surveillance.jpg "$detections" output.jpg

# 第 3 步：处理结果
echo "$detections" | jq 'length'  # 计数人数
```

### 示例 3：基于网格的 ROI 设置

**场景：** 在走廊监控摄像机中计数进入特定房间的人员，使用 ROI 限制检测区域。

```bash
# 第 1 步：生成网格参考
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/show-grid.mjs hallway.jpg --cols 6 --rows 4

# 第 2 步：根据网格识别坐标（B1, D1, D3, B3）并创建 ROI
# 注意：ROI 必须包含 id 和 name 字段

# 第 3 步：验证 ROI
node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/visualize.mjs hallway.jpg '[]' roi_preview.jpg \
  --overlays "[{\"kind\":\"ROI\",\"name\":\"doorway\",\"points\":[320,270,960,270,960,810,320,810]}]"

# 第 4 步：使用 invoke.mjs 传入自定义 ROI（不要用 intent-invoke.mjs，它只会添加全图 ROI）
echo '{"input0":{"image":"hallway.jpg","roi":{"id":"1","name":"doorway","kind":"ROI","points":[320,270,960,270,960,810,320,810]}}}' | \
  node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/invoke.mjs ep-xxxx-yyyy
```

### 示例 4：视频帧处理和跟踪

**场景：** 处理 30 秒监控视频，逐帧检测和跟踪人员。

```bash
# 第 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")"

  # 使用意图驱动调用
  result=$(node ${CLAUDE_PLUGIN_ROOT}/skill/scripts/intent-invoke.mjs "检测人员" "$frame_file")

  detections=$(echo "$result" | jq '.detections')
  echo "$detections" > "results/${imageId}_detections.json"
done
```

---

**API Key 从 `YIJIAN_API_KEY` 环境变量读取。所有脚本将 JSON 输出到标准输出，错误输出到标准错误。**