# @duke-dsh-plugins/dsh-deveco 中文文档

规范地址：https://npmcn.com/package/%40duke-dsh-plugins/dsh-deveco/

版本：0\.8\.0
npm 元数据更新时间：2026-11-11T16:09:05.677Z
中文译文更新时间：2026-11-13T00:04:44.300Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40duke-dsh-plugins/dsh-deveco
原文对照：https://npmcn.com/package/%40duke-dsh-plugins/dsh-deveco/?lang=original
项目主页：https://github.com/MoonlitDropOfBlood/dsh-deveco
源码仓库：https://github.com/MoonlitDropOfBlood/dsh-deveco

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：697 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-tools ^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0，@deepseek-ai/dsh-typert-protocol ^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0
- 首次发布：2026-10-12T16:03:20.826Z
- 最新版本发布：2026-11-11T16:09:05.179Z
- 近 30 天下载量：3755（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

DSH 1/ 捆绑 : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : (边栏右Tabs) : : : : : : : : : : : : HiLog : : : : : : : : ; ; ; ; : : ; ; : ; ; ; : : : : ; ; ; ; : ; : ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; : ; : ; ; ; ; ; ; ; : ; ; ; : ; ; ; ; ; ; ; ; ;

## 安装

```sh
npm install @duke-dsh-plugins/dsh-deveco
```

也可以使用：`pnpm add @duke-dsh-plugins/dsh-deveco`、`yarn add @duke-dsh-plugins/dsh-deveco`、`bun add @duke-dsh-plugins/dsh-deveco`

## README

### DeepSeek Harness HarmonyOS 开发套件

![DSH plugin](https://img.shields.io/badge/DSH-Plugin-4D6BFE?style=flat) ![supported DSH versions](https://img.shields.io/badge/DSH-%5E0.2.0--rc.1-4D6BFE?style=flat) [![npm version](https://img.shields.io/npm/v/@duke-dsh-plugins/dsh-deveco?style=flat)](https://www.npmjs.com/package/@duke-dsh-plugins/dsh-deveco) [![MIT License](https://img.shields.io/badge/license-MIT-2EA44F?style=flat)](https://npmcn.com/package/%40duke-dsh-plugins/dsh-deveco/LICENSE) ![Web UI](https://img.shields.io/badge/Web%20UI-Yes-22C55E?style=flat)

中文

* * *

为 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) Web UI 打造的 **HarmonyOS 全栈开发套件**插件：HiLog 检查器、Chrome DevTools 风格 ArkUI Inspector（截图点选 + 组件树 + 盒模型声明值 + 自定义组件名）、ArkTS 语法高亮 .ets 查看器、工具链与设备管理，以及对话内 agent 可直接调用的 `harmony_project` / `harmony_ui_tree` / `harmony_debug` / `harmony_web_dom` 工具。

> **兼容性**：支持 DSH **`^0.2.0-rc.1`**（0.2.x；本插件深度依赖 0.2.0 API——官方右侧边栏 `sidebarRightTabs`、设置页、agent 工具 `ctx.tools`，**0.1.x 无右侧边栏，不受支持**）。`engines.dsh` 与 peerDependencies 同步声明。发布走 GitHub `v*` 标签 → Actions 自动构建测试 + GitHub Release + npm（`@duke-dsh-plugins` 组织，OIDC Trusted Publishing）。

## 功能

### 官方右侧边栏 Tab

-   **HiLog 检查器**：实时日志流（基于 `devecocli log --follow`）+ 级别过滤（chip 多选）+ **包名/关键词实时过滤**——流跑着随时改随时生效、清空即回溯（不丢已缓冲的行）；包名自动解析为进程 pid 集合过滤（主进程 + `:render` 等后缀进程全收）+ **Ctrl+F 日志内查找**（Tab 内接管快捷键：全部命中高亮 + 计数 + Enter 逐个跳转 + Esc 关闭）+ 「开始/停止」控制
-   **ArkUI Inspector**：Chrome Elements 风格三栏——**左侧设备截图**（点「Dump UI」自动抓取，Host 内联返回 PNG dataUrl；**点击截图直接选中对应节点**并显示蓝色高亮框，**按 `origBounds` 真实布局矩形标注**——`bounds` 只是被滚动/遮挡后的可见区域，List 尤其不准；高亮与点击命中共用同一坐标系；点中后 **UI 树自动展开并滚动定位到该行**并高亮选中）+ **右上 UI 树**（**可逐节点折叠/展开 + 「折叠全部」**、层级引导线（**线性缩进不封顶**，深层可横向滚动）、**自定义组件显示组件名**，其内部 `__Common__` 占位节点归属到所属组件、tap/scroll/子节点数标记、`#accessibilityId` 标识、**顶部「树源」下拉两选一**：**DevEco 调试源**（反编译复刻 DevEco Studio 同款 `ark:<pid>@<pkg>` WebSocket 调试链路，**唯一带 padding/margin/border 声明值与 viewTag 组件名**；需 debug 应用且应用侧调试 socket 空闲——DevEco Studio 的 Inspector 面板开着时会占用唯一连接）/ 无障碍树（uitest，适合已发布应用）、**窗口下拉切换窗口**）+ **右下节点属性**（**全部设备原始属性**，支持**按属性名或值搜索过滤**并高亮命中项 + **盒子模型**：组件区域 / **内容区域（子节点并集实测）** / 四边内缩实测值；padding/margin/border 声明值在 uitest 源下显示「未提供」——已穷尽核对 7 条取数路径确实不输出，不做假数据；**DevEco 调试源下显示真实声明值**）；底部 Tap/Swipe/Text 操作
-   **Projects 数据面**：紧凑 `listProjects` Remote 可识别 Host 工作目录中的工程；面向 agent 的完整工程模型由 `harmony_project` 提供（当前没有单独的 Projects 图形页）。

### Agent 工具（对话内可调用）

-   **`harmony_project`**：只读解析真实 DevEco/Hvigor 工程（JSON5），从工程内任意路径向上定位应用根，返回 bundle/版本、products/build modes、模块/targets、Ability/ExtensionAbility、权限、页面、依赖、HAP/HSP/HAR/APP 构建产物及 Source Map 清单。省略 `path` 时使用当前 agent 工作区；签名配置只返回名称/类型/完整性，不暴露证书路径、别名或密码。
-   **`harmony_ui_tree`**：把 DevEco 调试源取树注册为 DSH 的 agent 工具（`ctx.tools`），对话里的 agent 可直接调用，返回**缩进树文本**（或 `format=json` 完整节点）——节点含组件名、bounds、文本与 **padding/margin/border 声明值**；JSON 中每个节点带裁剪前原始直接子节点数 `childCount`（裁剪为叶子也不归零）。Swiper 在 `displayCount` 未配置或 ≤1 时只完整展开 `currentIndex` 页，其他页保留一层（`TabContent` 两层），`displayCount>1` 时不裁剪。支持 `device` / `pid` / `package_name` 定位目标、`include_attrs` 附带全部原始属性、`max_nodes` 截断保护。前置条件同 DevEco 调试源（debug 应用、DevEco Inspector 面板未占用）。
-   **`harmony_web_dom`**：读取 **ArkWeb（HarmonyOS Web 组件）页面的真实 DOM**，走 ArkWeb 自带的 Chromium DevTools Protocol，不依赖 uitest/ArkUI Inspector/Chrome 中间页。
    -   `action="targets"` 枚举 `webview_devtools_remote_<pid>` 进程与可调试页面（id / type / title / url / pid / 包名）。
    -   `action="snapshot"` 读取指定 target 的 DOM；支持 CSS `selector` 定位子树、`depth` / `max_nodes` 有界裁剪、`include_attrs` 返回全部属性、`include_html` / `format="html"` 返回 outerHTML。
    -   截断保持「整棵子树省略」语义：边界父节点带 `childrenOmitted` 与 `hiddenDirect`，`childCount` 保留 CDP 原始直接子节点数，不会被误报为叶子。
    -   只读：不执行页面 JavaScript，不修改 DOM；页面标题、URL、属性和文本均是不可信网页数据。
    -   前置条件：应用调用 `webview.WebviewController.setWebDebuggingAccess(true)`、声明 `ohos.permission.INTERNET`、Web 页面已加载、设备 ≥ 4.1.0。**不需要** `aa attach`、debug 签名或 ArkUI inspector 会话。
    -   当前能力先以 Remote + agent 工具提供；ArkUI Inspector 的节点模型/设备像素 overlay 不混用 Web DOM。
-   **`harmony_debug`**：**ArkTS 运行时调试器**（与 DevEco Studio 同款通道：`hdc fport ark:<pid>@Debugger` + 裸 socket WebSocket + CDP 风格 JSON-RPC）。动作：`attach`（`launch=true` 走已验证的 wait-for-debugger 流程：`aa appdebug` → force-stop → `aa start` → fport → 握手 → `Runtime.runIfWaitingForDebugger`）、`status` / `scripts`（已加载脚本 url，断点必须逐字匹配）、`set_breakpoint` / `remove_breakpoint` / `breakpoints`、`pause` / `resume` / `step`（over/into/out）、`run`、`stack`（调用栈）、`evaluate`（暂停帧求值——该 runtime 不支持 `Runtime.evaluate`）、`properties`（展开远程对象）、`exceptions`（none/uncaught/all）、`events`、`notify`（开关自动通知）、`skip_pauses`（开关 runtime 的「跳过暂停」启动快进）、`detach`。**应用停在断点/异常暂停时，会话会自动收到一条通知**（暂停位置 + 调用栈 + 下一步建议），agent 不必轮询 `status`；自己触发的暂停（attach 入口暂停、`pause`、`step`）由工具结果内联回报，不会重复通知。**启动期默认跳过 ArkVM 的逐脚本暂停**（`Debugger.setSkipAllPauses`，实测 55 个脚本 = 55 次「Break on start」会让 app 卡在启动页）；设断点 / `pause` / `step` 会自动关掉它。**推荐源码断点**：`source_path` + 1 基 `source_line`（可选 1 基 `source_column`、`project_path`、`build_mode`），通过真实 Hvigor Source Map v3 定位 ArkVM 编译 URL/0 基位置；空白行会明确移动到下一可执行映射，源文件比映射新时拒绝使用旧映射。`attach/status/stack/step` 与自动暂停通知都会把帧反解为 `.ets` 位置，同时保留编译位置。旧的 `url` + 0 基 `line` 编译断点仍然兼容。前置条件：应用必须是 **debug 签名**；同一 pid 同时只允许一个调试客户端（DevEco 调试会话开着时 attach 会连不上）。

> 日志与应用管理不另做工具——直接用官方 CLI：`devecocli log`（`--level/--keyword/--bundle-name/--tail/--format json/--follow`）与 `devecocli device app list|info|start|stop|install|uninstall`（`device app info --format json` 里含 `applicationInfo.appProvisionType`，即 debug 签名判定）。

工程理解与源码调试示例（JSON 为工具参数）：

```json
// harmony_project：path 可省略，默认当前会话工作区
{ "path": "D:/ai-projects/dsh/dsh-remote-control/app" }

// harmony_debug：attach 时记住工程，后续 stack/通知都带源码位置
{ "action": "attach", "package_name": "com.dukedsh.remotecontrol", "launch": true, "project_path": "D:/ai-projects/dsh/dsh-remote-control/app" }

// harmony_debug：直接用 .ets 第 296 行，不需要手查编译后的 Index.ts
{ "action": "set_breakpoint", "source_path": "entry/src/main/ets/pages/Index.ets", "source_line": 296 }

// harmony_web_dom：先找 ArkWeb 页面，再按 CSS 选择器读取 DOM
{ "action": "targets", "package_name": "com.example.app" }
{ "action": "snapshot", "target_id": "<target-id>", "selector": "div#app", "depth": 8, "max_nodes": 400 }
```

### .ets 文件查看器

-   注册为官方侧边栏 file tab（`patterns: ["dsh-resource://file/**"]` + `canOpen` 按扩展名过滤），`extension` 优先级优先于内置 text editor
-   提供 ArkTS 语法高亮：关键字 + 装饰器（@Entry /@Component /@State 等）+ 注释 + 字符串 + 数字
-   内容经官方 `remote.workspaceFiles.read` 分页读取；绝对路径文件回退插件自有 `readTextFile` Remote

### 设置 → HarmonyOS Suite

导航项图标是手机造型（16px，跟随主题色）。**自定义图标需要 DSH ≥ 0.2.2-rc.1**（该版本新增了官方 `settings.section.icon` 接口）；在 0.2.0 / 0.2.1 上插件改用壳的通用齿轮图标，设置页本身功能不受影响。

页面分两个分区：

**工具链**

-   「DevEco Studio 路径」输入框 + 「扫描系统默认」+ 自发现结果列表
-   「HarmonyOS Command Line Tools 路径」输入框 + 版本校验（≥ 26.0.0）+ 自发现结果列表
-   「重新扫描」按钮 + 「保存 / 放弃」
-   状态徽章（devecocli / hdc 降级（未安装 devecocli）/ CLT ≥26 / CLT<26 / Studio / 未配置）

**设备管理**

-   **设备列表**：实时列出 USB / 网络设备（`devecocli device list`；未安装 devecocli 时自动降级 `hdc list targets`），网络目标（`ip:port`）带「网络」徽章，可一键「断开」（`hdc tconn <ip>:<port> -remove`）
-   **IP 网络连接**：输入设备 IP 和端口（**端口必填**——hdc 无默认端口，须与设备开启调试后暴露的端口一致）后「连接」，底层执行 `hdc tconn <ip>:<port>`；连接/断开后列表自动刷新。devecocli 本身没有 IP 连接能力，这里直连 SDK 自带的 hdc（按 `DEVECO_SDK_HOME` → `DEVECO_HOME` → 已配置/已发现的 Studio/CLT 安装根 → PATH 顺序解析）。前提：设备已在「设置 → 开发者选项」中开启调试

## 工具链解析优先级（用户决策）

1.  **`PATH` 存在 `devecocli`** → 优先使用，**忽略设置路径**
2.  **CLT 路径 ≥ 26.0.0** → 用 CLT（与 Studio 互斥）
3.  **DevEco Studio 路径** → 兜底
4.  **都没有** → 设备/日志/截图/操作自动降级到 SDK 自带的 `hdc`；`hdc` 也找不到才提示去设置

互斥规则：`setCltPath` 清空 `studioPath`；`setStudioPath` 清空 `cltPath`。

> **devecocli 不是 DevEco Studio / Command Line Tools 自带的**——它是独立的 npm 包（`@deveco/deveco-cli`）。本插件在未安装它时**不会变砖**：所有设备与 UI 能力都会自动切换到 SDK 自带的 `hdc`。

## 没有 devecocli 也能用（hdc 降级）

装了 DevEco Studio 或 Command Line Tools（拿到 SDK 里的 `hdc`）但没有装 `devecocli` 时，插件按下面的矩阵自动降级——不需要任何额外开关：

| 能力 | 有 devecocli | 没有 devecocli（hdc 降级） |
| --- | --- | --- |
| 设备列表 | `devecocli device list` | `hdc list targets` |
| 设备详情 | `devecocli device view` | `hdc shell param get const.*` |
| 实时 / 历史日志 | `devecocli log [--follow]` | `hdc shell hilog` / `hilog -x` |
| 窗口列表 | `devecocli ui window list` | `hdc shell hidumper -s WindowManagerService -a -a` |
| 截图 | `devecocli ui screenshot` | `hdc shell uitest screenCap`（失败退 `snapshot_display`）+ `hdc file recv` |
| Tap / Swipe / Text | `devecocli ui click/swipe/text` | `hdc shell uitest uiInput click/swipe/text` |
| ArkUI 无障碍树 | — | `hdc shell uitest dumpLayout`（本来就走 hdc，不受影响） |
| DevEco 调试树 / ArkTS 调试器 / IP 连接 / 包名→pid | — | 本来就走 hdc，不受影响 |

降级状态下设置页徽章显示「**hdc 降级（未安装 devecocli）**」；设备列表获取失败时 Tab 内会显示错误原因，而不是只给一个空下拉。想用 devecocli 的完整能力（例如更友好的 `device view` 输出）时再安装即可：`npm i -g @deveco/deveco-cli`。

## 安装

```bash
dsh plugin --profile web add @duke-dsh-plugins/dsh-deveco
```

本地开发版：

```bash
git clone https://github.com/MoonlitDropOfBlood/dsh-deveco
cd dsh-deveco
dsh plugin --profile web add .
```

## 开发

```bash
npm run check    # 全部 JS 语法检查
npm test         # 138 个独立核心单元测试（含 JSON5 工程模型/签名脱敏 + Source Map VLQ 双向映射 + 源码断点工具执行 + 源码暂停通知）

# 真实 Hvigor 工程 Source Map 双向映射探针（不依赖设备/DSH）
node scripts/e2e-source-map.mjs --project <工程根> --source entry/src/main/ets/pages/Index.ets --line 296

# 模拟器跑 agent 工程/调试工具（不依赖 DSH；--source 可选，省略则测编译断点）
node scripts/e2e-agent-tools.mjs --device 127.0.0.1:5555 --bundle <你的 debug 包名> --project <工程根> --source entry/src/main/ets/pages/Index.ets --source-line 296 --attach
```

**改插件后必须重启 DSH** 生效（Host 加载、typert 注册、client bundle 注入都在启动时发生）。

详细开发规范见 `AGENTS.md`。

## 三平台自动发现

| 平台 | Studio 默认路径 | CLT 根默认路径 |
| --- | --- | --- |
| Windows | `C:\Program Files\Huawei\DevEco Studio`  
`C:\Program Files (x86)\Huawei\DevEco Studio`  
`C:\DevEco Studio` | `C:\Program Files\Huawei\Command Line Tools`  
`%LOCALAPPDATA%\Huawei\Command Line Tools` |
| macOS | `/Applications/DevEco Studio.app/Contents`  
`/Applications/Huawei DevEco Studio.app/Contents`  
`~/Applications/DevEco Studio.app/Contents` | `/Applications/Command Line Tools.app/Contents`  
`~/Library/Huawei/Command Line Tools` |
| Linux | `/opt/deveco-studio`  
`/opt/Huawei DevEco Studio`  
`~/deveco-studio` | `/opt/Huawei/Command Line Tools`  
`~/Huawei/Command Line Tools` |

## 持久化

-   配置：`<DSH_HOME>/data/dsh-deveco/config.json`
-   自发现缓存：`<DSH_HOME>/data/dsh-deveco/discovery.json`

首次启动（`discovery.json` 不存在）自动触发三平台自发现，结果缓存到 `<DSH_HOME>/data/dsh-deveco/discovery.json`。

## 许可证

MIT

## 常见问题

### @duke-dsh-plugins/dsh-deveco 是什么？

DSH 1/ 捆绑 : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : \(边栏右Tabs\) : : : : : : : : : : : : HiLog : : : : : : : : ; ; ; ; : : ; ; : ; ; ; : : : : ; ; ; ; : ; : ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; : ; : ; ; ; ; ; ; ; : ; ; ; : ; ; ; ; ; ; ; ; ;

### 如何安装 @duke-dsh-plugins/dsh-deveco？

在项目目录运行 npm install @duke-dsh-plugins/dsh-deveco，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-tools（^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0）、@deepseek-ai/dsh-typert-protocol（^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @duke-dsh-plugins/dsh-deveco 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/duke-dsh-plugins\_\_dsh-deveco 是否存在。

### @duke-dsh-plugins/dsh-deveco 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @duke-dsh-plugins/dsh-deveco 可以商用吗？

@duke-dsh-plugins/dsh-deveco 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @duke-dsh-plugins/dsh-deveco 的下载量有多少？

根据 npm 官方下载统计，@duke-dsh-plugins/dsh-deveco 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,755 次，日均约 125 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @duke-dsh-plugins/dsh-deveco 还在维护吗？

最新版本 0\.8\.0 发布于 2026/11/12（1 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。