# devecocli-Filling

**Repository Path**: Duke_Bit/devecocli-filling

## Basic Information

- **Project Name**: devecocli-Filling
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# harmony-device-control

一个可分享的 **ZCode skill**：补充 `devecocli` 未覆盖的鸿蒙能力——设备操作（按键、启动已装
应用、杀进程）+ 小图截图 + 连抓多帧（捕捉动画）+ 官方文档检索（按章节精读、按关键词提取片段）。

**为什么不直接用 devecocli**：点击/滑动/dump layout/输入文本/列设备/查日志/录屏等设备能力
`devecocli`（`ui` / `device` / `log`）已提供；但按键、纯启动已装应用（不走构建/部署）、杀进程、
**小图截图（默认 ~85KB 适合 agent Read）、连抓多帧捕捉动画** 这几项它没有或做得不够。
文档方面 `devecocli docs read` 只能读整篇，本 skill 的 `docread` 能按章节定位、
`docfetch` 能按关键词提取最相关片段。

**特点**：
- 🪶 **零依赖** —— 脚本只用 Node 内置模块，无需 `npm install`、无需构建。
- 🎯 **职责单一** —— 只做 devecocli 没有的，不重复造轮子。
- 🔍 **自动发现 hdc** —— Mac / Windows 下无需手动配 PATH，自动扫描 DevEco Studio 默认路径。
- 🎞️ **连抓多帧** —— `grab` 按指定间隔连抓 N 帧（每帧 ~80KB 适合 Read），专为捕捉 > 200ms 的页面转场/动画过程优化。单抓用 `grab --count 1`。
- 📚 **文档检索** —— 直连华为官方文档后端，搜文档、按章节读、按关键词提取片段。
- 📱 **多设备支持** —— `--device <id>` 精确指定；多设备环境不会误操作。
- 🧩 **可分享** —— 整个目录复制到任意 ZCode 项目即可被识别为 skill。

## 安装

把本目录复制到目标 ZCode 项目的 skill 目录，**目录名必须改为 `harmony-device-control`**
（与 `SKILL.md` 里 `name` 字段一致，否则不会被识别）：

```
<目标项目>/
└── .agents/
    └── skills/
        └── harmony-device-control/     ← 改成这个名字
            ├── SKILL.md
            ├── README.md
            └── scripts/
                └── device.mjs
```

安装后，在目标项目的 ZCode 会话里，涉及鸿蒙设备按键/启动/杀进程时会自动触发；
也可手动 `Skill` 调用 `harmony-device-control`。

## 环境要求

| 依赖 | 说明 |
|---|---|
| Node.js 18+ | 脚本运行环境（内置模块，无需安装包） |
| `hdc` | HarmonyOS Device Connector。脚本会自动从 DevEco Studio 默认路径发现，通常无需手动配置 |
| 鸿蒙设备/模拟器 | 已连接，开启开发者模式与 USB 调试 |

### hdc 解析顺序

脚本按以下顺序自动解析 hdc 路径，前一步命中就不再往下：

1. 环境变量 `HDC_PATH` / `RC_HDC_PATH` —— 显式指定 hdc 绝对路径
2. PATH 中的 `hdc`
3. **自动发现** —— 扫描 `DEVECO_HOME` / `DEVECO_SDK_HOME` / `HARMONY_SDK_HOME` 指向的目录，
   以及 DevEco Studio 各盘常见安装位置（`Program Files\Huawei`、`Application\Huawei` 等）；
   递归匹配其中的 `toolchains/hdc(.exe)`，兼容 `sdk/<版本或 default>/openharmony/toolchains` 等结构
4. 都没找到则降级为 `hdc`，由后续命令报真实错误

### 环境变量

| 变量 | 作用 |
|---|---|
| `HDC_PATH` / `RC_HDC_PATH` | hdc 可执行文件绝对路径（最高优先级） |
| `DEVECO_HOME` | DevEco Studio 安装目录，自动发现时优先扫描（推荐） |
| `DEVECO_SDK_HOME` / `HARMONY_SDK_HOME` | HarmonyOS SDK 根目录，自动发现时会扫描 |

## 快速上手

```bash
# 按返回键 / 主页键
node scripts/device.mjs presskey Back
node scripts/device.mjs presskey Home

# 启动已装应用（--fresh 先杀进程冷启动）
node scripts/device.mjs startapp com.example.myapp --fresh

# 杀掉应用进程
node scripts/device.mjs killapp com.example.myapp

# 连抓多帧（捕捉 > 200ms 的页面转场/动画过程）
node scripts/device.mjs grab --count 6 --interval 80
# 输出：grab_1.jpeg ... grab_6.jpeg，逐帧 Read 即可看到动画过程
```

### 查鸿蒙开发文档（无需设备）

```bash
# 搜索官方文档
node scripts/device.mjs docsearch --limit 5 Tabs 滑动切换

# 看文档结构（列章节目录）
node scripts/device.mjs docread arkts-navigation-tabs

# 按章节精读（section_id 从上面的目录获取）
node scripts/device.mjs docread arkts-navigation-tabs section-3

# 按关键词提取最相关片段（查 API 用法最省 token）
node scripts/device.mjs docfetch arkts-navigation-tabs --top 3 TabContent 懒加载
```

### 多设备

```bash
# 先列出设备 ID（用 hdc list targets 或 devecocli）
# 示例设备 ID：
#   7001005452350033
#   emulator-5554

# 对指定设备操作（用本 CLI 的 --device）
node scripts/device.mjs --device 7001005452350033 presskey Back
node scripts/device.mjs --device emulator-5554 startapp com.example.myapp
```

> 不指定 `--device` 时：单设备自动选用；多设备会报错并列出 ID，要求显式选择——
> 避免默默操作错误的设备。

## 完整命令列表

运行 `node scripts/device.mjs --help` 查看全部命令，或阅读
[`SKILL.md`](./SKILL.md) 中的命令速查表与 agent 验证场景。

## 项目结构

```
harmony-device-control/
├── SKILL.md            # skill 主文件（触发条件 + 用法 + 验证场景）
├── README.md           # 本文件
└── scripts/
    └── device.mjs      # 零依赖 CLI（唯一脚本）
```

## 致谢

设备交互逻辑参考了 [codegenie-test](https://gitcode.com/codegenie/codegenie-test/tree/master/mcp/runtime-calibration-src)
项目 `devices/harmony.ts` 的实现（应用启动解析、杀进程、按键、命令容错层），
精简为只保留 devecocli 未覆盖的能力，并新增了 hdc 自动发现与多设备支持。