dsh-hdc-bridge

DSH 原生鸿蒙开发助手：hdc 设备闭环调试（看设备 → 截图 → 看图 → 改码 → 装包 → 验证）＋ 官方优先版本化知识层（离线 Tier-1 随包 + SDK 机读 + 官方文档检索）＋ 可选官方 DevEco CLI 构建/签名通道。 A DSH-native HarmonyOS dev assistant: the hdc device loop (inspect → screenshot → view → fix → install → verify), an official-first version-classified knowledge layer (offline Tier-1 bundled + SDK-accurate reads + official docs search), and an optional official DevEco CLI build/sign backend.

定位

hdc_mcp 等 MCP 服务器已覆盖 hdc 能力层。本插件不重写 hdc 协议，直接复用本机 hdc 二进制（3.x），价值在 DSH 原生层：

• 会话内工具卡片与 read_image 原生闭环
• 按调用会话解析沙箱策略（与 pwsh 工具同款路线），截图写入 <workspace>/.dsh-hdc/screenshots/
• 结构化的失败上报（hdc 传输层退出码不可靠，插件用输出标记 + 落盘校验兜底）
• v0.7 起面板按官方 client 插件形态集成（边栏入口 + 浮动面板 + 官方主题），v0.9 补齐会话级编译、静态检查、部署与日志工具（switch_cwd / build_project / arkts_check / start_app / hdc_log）

截图 / Screenshots

浮动设备面板（点左侧边栏「鸿蒙」入口打开；设备列表 / 系统区 / 工具链徽章 / hilog 尾部，官方主题随深浅色自适应）：

工具

约定：所有工具失败不抛异常，统一返回业务值 { ok: false, error, hint }（error 为可读原因，hint 为修复指引）；成功返回带 ok: true 的结果对象。工具描述里同时给出 error 示例。这是本插件的显式约定（官方工具层允许抛 ToolFailure，本插件为面板/技能一致性选择返回值形式并在此声明）。

这份 README 是 dsh-hdc-bridge 的项目版使用手册。它不仅列出原始工具，还说明模型在真实鸿蒙工程中应如何编排调用、如何判断回退是否真的成功，以及安装本插件后新增的 DSH 能力边界。

工具	说明
hdc_list_targets	列出已连接设备/模拟器（空列表 + 连接指引）
hdc_connect	hdc tconn（严格 host:port 校验）
hdc_shell	设备 shell（param get / ps / uitest dumpLayout…）
hdc_screenshot	截图 → 拉取 JPEG → 落盘校验（API 10+ 的 snapshot_display 仅支持 .jpeg）
hdc_install	安装 .hap（默认 -r；输出标记级失败检测）
hdc_hilog	hilog 尾部 N 行（可选域名 -T 过滤，如 PARAM）
hdc_ui_dump	文本化 UI 快照：uitest 布局树 → 可见文本节点（纯文本模型的「文字截图」）
hdc_ui_find	按文本/hint 找控件：返回 bounds 与中心坐标，配合 tap 免手算坐标
hdc_ui	UI 操作：tap / doubleTap / longPress / swipe / input / key（Back/Home/Power/keyID），配合 dump 形成「观察 → 操作 → 验证」闭环
hdc_app	应用管理：query / start / stop / clear-data / uninstall（破坏性动作已标注）
hdc_crash	崩溃抓取：faultlogger 目录里最近的 jscrash / cppcrash / appfreeze，可按包名过滤，并解析结构化摘要（错误名/信息/错误码/源码帧/已知错误码提示）
hdc_diag	诊断：shell 口味 / hdc 路径 / 策略解析 / 探测日志
错误码提示	install / app / build 失败按 11 条已知错误码附中文修复建议（9568332 签名未绑 UDID→AGC 登记设备、9568289/9568322 签名配置、1300002 空间不足…）；签名类错误附三类修复（AGC 证书配置 / 重装自签名 / 换 debug 签名）+ 直达 AGC 链接
hms_setup	环境体检：hdc / DevEco Studio / SDK(API 版本) / devecocli / 设备五项 + 目标 API 版本三源解析（项目→设备→SDK）与不一致告警
hms_build	官方构建/签名/运行通道：status / build / run / sign / clean；devecocli 缺失时自动回退本机 hvigorw + hdc_install + hdc_app 闭环
hms_api	官方优先的版本化 API 知识：读本机 SDK .d.ts（@since/@deprecated/@syscap 精确到 API 版本），按目标版本分类"可用/已废弃/不可用"
hms_knowledge	离线随包官方知识层（Tier-1）：OpenHarmony 官方文档（CC-BY-4.0）未改文字节选 28 篇高频 API 模块、窗口（window/Window 类）、导航组件 Navigation 与应用模型/ArkTS 指南（大文件按节选入，文件内附节选声明），无需 SDK/CLI/网络。catalog / read（先目录后按小节读）/ search
hms_docs	官方本地文档检索：devecocli docs search / read / catalog（Tier-2：全量文档，需 devecocli）
hms_api_change	官方跨版本破坏性变更扫描：devecocli check compat（versions / diff）——回答"知识在哪一版变了"
hms_lint	官方 lint：rules（本机 57+ 条 codelinter 规则索引）/ read-rule / check（devecocli check lint）
hms_emulator	官方模拟器控制（devecocli emulator）：list / start / stop / create / delete + 状态注入 shake / power / rotate / volume / fold / battery / geolocation / sensor / scene；未装 CLI 时按官方 SKILL.md 指路安装（第 20 个工具）
switch_cwd	为当前会话切换 HarmonyOS 工程根目录，供后续编译工具使用
build_project	构建项目并验证新 .hap 产物；devecocli 通道失败时回退到本机 hvigorw
arkts_check	通过 DevEco Studio SDK ets-loader 进行 ArkTS 静态检查；未传文件时自动

…