鸿蒙开发套件 ilun886/dsh-harmonyos-devkit

dsh-harmonyos-arkts

HarmonyOS / ArkTS 开发套件，打包成 一个 DSH 组合包（bundle）。

装上它，DSH 就同时具备：ArkTS·ArkUI 规则库（按需查询）、离线 ArkTS 静态检查、44 个鸿蒙官方技能（全量），以及可选的 devecocli MCP（HarmonyOS LSP）。不用再手工改 cordis.patch.yml、手工复制技能目录。

它提供什么

| 能力 | 载体 | 说明 |
| arkts_rules 工具 | 本包 rules/ | ArkTS/ArkUI 规则库：致命陷阱清单 + API 速查。写 .ets 前先查 |
| arkts_check 工具 | 本包 skills/.../linter-cli | 离线 ArkTS 静态检查，秒级、无需工程 READY |
| 44 个鸿蒙技能 | 本包 skills/ | 官方 devecocli skills 全量，见下 |
| 规则库提示词 | 本包 lib/index.js | 只在 arkts_rules 可见时注入，不污染无关会话 |
| mcp__deveco__（可选） | devecocli MCP | HarmonyOS LSP：hover / definition / references / documentSymbol / callHierarchy |

捆绑的 44 个技能（按主题）

ArkTS / ArkUI 开发

| 技能 | 用途 |
| hmos-arkui-develop-skill | 写 .ets 前必加载：致命陷阱清单 + 组件→规则交叉表 |
| hmos-arkts-knowledge-retriever | ArkTS 文档检索（并自带 arkts_check 依赖的 linter-cli） |
| hmos-arkui-knowledge-retriever | ArkUI 文档检索（809 篇 md） |
| hmos-arkts-syntax-checker | 静态检查 + 循环构建到成功 |
| hmos-arkui-mvvm-pattern / hmos-arkui-statemgt-migration | MVVM 模式 / 状态管理迁移 |
| hmos-arkui-longtake-transition | 长时转场动画 |
| hmos-arkts-deprecated-interface-checker | 废弃接口替换检查 |

DFX / 稳定性分析（多数含 Python 脚本）

| 技能 | 用途 |
| hmos-jscrash-analysis / hmos-runtime-fix-skill | JS Crash 日志分析 / 运行时崩溃修复 |
| hmos-cppcrash-analysis / hmos-appfreeze-analysis | C++ 崩溃 / 应用卡死 |
| hmos-memleak-analysis / hmos-native-memleak-analysis / hmos-jsleak-analysis / hmos-fdleak-analysis | 内存 / 原生内存 / JS 泄漏 / FD 泄漏 |
| hmos-apifault-analysis | API 故障分析 |

Kit 集成

hmos-push-kit、hmos-account-kit-quicklogin-client、hmos-map-kit-{map-creation,route-planning,poi-search}、hmos-scan-kit-{defaultscan,customscan}、hmos-payment-kit-huawei-payment-integration、hmos-ads-kit-access、hmos-live-view-kit-build-location

多设备 / 折叠屏

hmos-multidevice-{scenario-entry,screen-window-size,avoid-areas,hardware-access,natural-orientation,fold-state,interaction-methods}

测试 / 迁移 / 其它

hmos-local-test、hmos-instrument-test、hmos-ascf-convert-{uniapp,taro}、hmos-ascf-assistant、hmos-atomicservice-assistant、hmos-one-sdk-skill、hmos-connect-api-cli-skill、hmos-design-visual-mobile、app-metadata-audit-skill

⚠️ 其中两个技能带未签名的 Windows exe（hmos-jsleak-analysis 的 rawheap_translator.exe 0.9 MB、hmos-native-memleak-analysis 的 trace_streamer_windows.exe 16.9 MB）。来自华为官方仓库但无 Authenticode 签名，仅在跑对应分析时才被调用。

11 个技能带 Python 脚本（共 86 个 .py），本机 Python 3.12.5 可用；个别脚本可能还需 pip install 额外依赖。

⚠️ Windows 克隆：必须用短路径（否则会静默缺文件）

本仓库内含超深目录嵌套，最长相对路径达 240 字符（位于 skills/hmos-one-sdk-skill/.../hiappevent-watcher-resourceleak-events-arkts/）。
Windows 的经典路径上限是 260 字符，因此：

| 克隆到 | 结果 |
| D:\t（2 字符） | ✅ 完整 4749 文件 |
| D:\dsh-harmonyos-arkts（23 字符） | ❌ 121 个文件创建失败 |

克隆者拿不到 core.longpaths 配置（它是本地设置，不会随仓库分发），所以克隆时不会报「配置缺失」，而是直接抛一串：

error: unable to create file ...: Filename too long
注意 git clone 在这种情况下仍返回 exit code 0——不检查文件数就会以为成功了。

三种解法，任选其一：

① 克隆到短路径（推荐，零配置）
git clone <url> D:\t

② 克隆时显式开启长路径支持
git -c core.longpaths=true clone <url> <任意路径>

③ 先开全局长路径（一次生效，需管理员）
git config --global core.longpaths true
可选：同时开启 Windows 系统级支持（Win10 1607+，需管理员 + 重启） New-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Value 1 -PropertyType DWord -Force

克隆后请自检文件数应为 4749：

(Get-ChildItem . -Recurse -File -Force |
Where-Object { $_.FullName -notmatch '\\\.git\\' }).Count

安装

dsh plugin --profile desktop add link:D:\dsh-harmonyos-arkts

装完重启 DSH（MCP 与技能目录在启动时注册）。回滚：

dsh plugin --profile desktop remove dsh-harmonyos-arkts

两个工具怎么用

arkts_rules

arkts_rules → 规则总索引（含"组件→规则文件"交叉表）
arkts_rules { query: "..." } → 全库关键词检索
arkts_rules { file: "05-state.md" } → 读某一篇
arkts_rules { file: "05-state.md", offset: 1, limit: 50 } → 按行窗口读
arkts_rules { listFiles: true } → 列出全部 35 个规则文件

规则库重点覆盖：V1/V2 状态管理不混用、禁用 any 与匿名对象字面量、Navigation 路由栈、 @kit. 真实成员、以及"构造参数字段名凭记忆编造"这类编译必挂项。

arkts_check

arkts_check { files: ["D:\\proj\\entry\\src\\main\\ets\\pages\\Index.ets"] }

实测输出：

3 error(s), 0 warning(s)

ERROR .../BadPage.ets:8:17 Use explicit types instead of "any", "unknown" (arkts-no-any-unknown)
ERROR .../BadPage.ets:11:20 Object literal must correspond to some explicitly declared class or interface (arkts-no-untyped-obj-literals)
ERROR .../BadPage.ets:26:11 Use "let" instead of "var" (arkts-no-var)

SDK 路径自动探测（DEVECO_SDK_HOME → 标准 DevEco 安装路径）；排查问题时可用 sdkPath / projectRoot / moduleRoot / moduleJson 覆盖。

⚠️ --sdk-path 必须指到 sdk\default，不能指 sdk 根

这是本包踩过的最阴的坑，会伪造错误。DevEco 的布局比 linter-cli 预期的多一层：

D:\DevEco Studio\sdk\default\openharmony\ets
^^^^^^^ 必须包含这一层

实测（API 26 SDK + 官方模板 EntryAbility.ets，该文件本身完全正确）：

| 传给 --sdk-path | 诊断数 |
| D:\DevEco Studio\sdk | 5 条（全是假阳性） |
| D:\DevEco Studio\sdk\default | 0 条 |
| D:\DevEco Studio\sdk\default\openharmony | 0 条 |
| 完全不传 | 5 条 |

假阳性长这样——3 条 Cannot find module '@kit.AbilityKit' 之类，外加因类型丢失连锁 产生的 Property 'context' does not exist on type 'EntryAbility' 与 arkts-no-any-unknown。
最坏的结果是照着它去"修"官方模板里本来正确的代码。

本包已内置归一化（resolveSdkRoot()）：给 sdk 根或 default 层都会自动落到正确层级，
显式传 sdkPath 也一并归一化。别绕过本工具直接调 linter-cli。

三个必须知道的坑

这些是本机实测结论，不是推测：

1. devecocli check lint 是坏的。 在 DevEco 自带模板、ASCII 探针工程、以及真实的活跃工程上，一律返回 Files checked: 0（报告文件照常生成，内容就是空）。别依赖它 ——用本包的 arkts_check。

2. linter-cli 的 --input 只能给一个文件。 重复传入只有最后一个生效，前面的被静默丢弃（会漏报）。本包已按"每文件单独起一次进程"处理，所以传多个文件是安全的。

3. 鸿蒙工程不能放在含非 ASCII 字符的路径下。 例如 D:\新建文件夹 (2)：

hvigor ERROR: 00306003 Invalid project path.
Current path does not match: D:\新建文件夹 (2)\...

build / sync / MCP 检查全部会失败。工程请放纯 ASCII 路径。

启用 devecocli MCP（可选）

该 MCP 绑定单个工程：PROJECT_PATH 写死在配置里，一次只对一个鸿蒙工程有效。
默认关闭，因为工程路径为空时它只会产生启动噪音。

启用步骤：

setx DSH_HARMONY_PROJECT "C:\Users\86198\DevEcoStudioProjects\MyApplication"

然后重启 DSH。换工程 = 改这个变量 + 重启。

为什么默认关？ 本机的 dsh-mcp-client 未实现 MCP 的 roots 能力（lib/index.js 里搜不到 listRoots），服务端无法从客户端自动探测工程，所以路径必须显式给。

为什么用 node + cli.js 绝对路径？ npm 生成的 devecocli.cmd / .ps1 是包装脚本， MCP 的 stdio spawn 不经过 shell、无法执行；cli.js 才是真实入口。可用环境变量覆盖： DSH_DEVECO_NODE、DSH_DEVECO_CLI。

注意：此 MCP 需工程先完成 ohpm install + hvigor sync 才可用，冷启动可能要 1 分钟以上（已把 toolCallTimeoutMs 调到 180 秒）。日常改完 .ets 想立刻自检，arkts_check 更快。

目录结构

dsh-harmonyos-arkts/ # 173.8 MB（其中 skills 173.5 MB） ├── package.json # dsh.bundle.patch 指向下面的 patch ├── cordis.patch.yml # 挂载声明：本插件 + MCP（共 2 行） ├── lib/index.js # skills 注册 + arkts_rules + arkts_check + 提示词 ├── scripts/build-skill-manifest.mjs # 构建期：从 SKILL.md 抽 frontmatter 生成清单 ├── rules/ # 规则库（quick-rules 16 篇 + quick-apis 19 篇） └── skills/ ├── _manifest.json # 由上面的脚本生成，运行时只读它（免 YAML 依赖） └── <44 个鸿蒙 skill>/ # 官方 devecocli skills 全量

增删 skill（以及为何不能直接拷目录）

skill 清单是构建期快照：lib/index.js 运行时只读 skills/_manifest.json，不从磁盘重扫 SKILL.md（避免运行时依赖 YAML 解析器）。所以新增或删除 skill 后，必须重跑清单脚本，否则改动不生效：

node scripts\build-skill-manifest.mjs

从官方仓库批量安装（--path 可绕过「skills add 不支持 DSH」的限制）：

目录必须预先存在，否则报 "Directory not found" New-Item -ItemType Directory -Path D:\__skill_stage -Force devecocli skills add --all --path D:\__skill_stage

挑单个装（注意：多个 --skill 只有最后一个生效，和 linter-cli --input 同一个坑） devecocli skills add --skill hmos-push-kit --path D:\__skill_stage

⚠️ 装完务必清理 linter-cache/。跑过 arkts_check 后， skills/hmos-arkts-knowledge-retriever/linter-cli/bin/linter-cache/ 会生成缓存（.tsbuildinfo + 按本机绝对路径命名的 sdk-configs/）。这些是机器相关的产物，不应进包：

Get-ChildItem skills -Recurse -Directory -Filter linter-cache | Remove-Item -Recurse -Force

改代码后必须重启 DSH

这是本包开发时最容易踩的坑。 Node 的 ESM 加载器按 URL 记忆已求值的模块， set_bundle 启停不会清掉这个缓存：

- 若旧版模块求值成功（哪怕 apply() 里抛错），改完文件后再次启用， 运行中的仍是旧代码，看起来像"改了没生效"。
- 只有进程重启才会重新读盘。

所以改完 lib/index.js（或任何被 import 的文件）后：重启 DSH，别指望热重载。
patch（cordis.patch.yml）倒是每次启用都会重读，所以增删 patch 行不必重启。

实测记录：磁盘上的文件已改成零外部依赖（import 只有 4 个 node: 内置模块， junction 与真实文件 MD5 一致），但运行中的宿主仍报旧的 Cannot find module '@deepseek-ai/dsh-tools' —— 就是被这个缓存钉住了。

实现要点（改代码前先读）

- 本插件零外部依赖：不 import 任何 harness 包，也不 import 任何第三方包，只用 node: 内置模块。这不是洁癖，是必须：
- DSH 启动时装了模块解析路由（dsh-app-boot 的 ResolutionRouter），它按插件 真实路径算 require.resolve.paths() 来决定能解析哪些包。本包以 link: 装成 junction 时真实路径在工作区（如 D:\dsh-harmonyos-arkts），从那儿向上找不到 ~/.dsh/profiles/node_modules → 裸包名解析必然失败。
- 在 package.json 里声明 dependencies / peerDependencies 也救不了：搜索路径同样从真实路径算起。
- 于是改为手写 JSON Schema。defineTool 本身只做「参数规格 → JSON Schema 编译」+ 入参校验，这里直接给出原生 JSON Schema（type/oneOf/properties/required/additionalProperties/items/enum/const + 注记），并自行校验入参，行为等价。已用真实的 assertSupportedJsonSchema 验证两个 schema 均通过。
- ⚠️ 注意方言差异：原生 JSON Schema 的必填写在对象级 required: [...] 数组里，不是 defineTool ParameterSchemaSpec 的字段级 required: true。
- ⚠️ 可选字段必须「解构删除」，不能「条件展开补」。arkts_check 曾经这样写：
issues: result.issues.map((i) => ({ ...i, ...(i.rule === null ? {} : { rule: i.rule }) }))

这是错的 —— 展开空对象不会删除已存在的 rule: null，而 schema 声明 rule 是 string，结果整个工具调用失败：tool "arkts_check" returned invalid output: "value.issues[0].rule" must be a string。正确写法是先解构掉再按需加回：
issues: result.issues.map(({ rule, ...rest }) => rule === null ? rest : { ...rest, rule })

（对照：官方 dsh-mcp-client 的 supportedOutputSchema() 遇到不支持的结构是丢弃整个 schema 而不是报错 —— 说明 harness 对输出结构是严格校验的，别指望它宽容。）
- ⚠️ --sdk-path 的层级陷阱（最阴的一个，细节见上文 arkts_check 章节）：指到 sdk 根会伪造 5 条假阳性，指到 sdk\default 才是 0 条。代码里由 resolveSdkRoot() 统一归一化。

- skills 由代码注册，不用 patch 的 bundledSkillDir。 后者要拼绝对路径，而可用作锚点的环境变量在 host 进程里并不存在 —— host 进程里没有 DSH_PROFILE_DIR（该变量只由 dsh-shell-env 注入给 shell 子进程，不写给 host）。首版据此配置导致挂载失败，现改为 import.meta.url 定位 + ctx.skills.register()。
- skill 元数据取自构建期生成的 skills/_manifest.json，避免运行时依赖 YAML 解析器（description 里有 > 折叠块和引号，正则硬解不可靠）。新增/修改 skill 后重跑：
node scripts\build-skill-manifest.mjs

- 自带资源用 import.meta.url 定位（rules/、skills/）—— 在 link: 与 copy 两种安装下都正确。
- linter-cli 必须从它自己的目录启动（cwd），否则它 node_modules/typescript 里的 OpenHarmony 定制版编译器解析不到。
- linter-cli 的 --input 一次只能给一个文件（重复传入仅最后一个生效，其余静默丢弃 → 假阴性），且其默认 linter-cache/ 固定在自身安装目录下，所以必须逐文件串行执行。
- 诊断写在 stderr 且带 ANSI 颜色码。 上游把 ERROR/WARN 写 stderr、只把 FAQ 提示写 stdout；且带 \x1b31m 前缀。只看 stdout 或不去色都会漏报，代码里已处理。
- patch 里的 !!js 表达式在 loader 的 with(ctx) 作用域求值：process.env 与 dshHomePath() 可用，require / __dirname 不可用。

许可

MIT。捆绑的 linter-cli 与 skills 来自 [HarmonyOS_Skills/harmonyos-agent-skills， linter-cli 内含上游 OpenHarmony 定制版 TypeScript，遵循其原始许可。