DevEco CLI 智能体插件开发指南：从 Runtime 选型到发布产物的完整实现剖析

开发工具CLIOpenHarmonyMCP 服务移动开发【免费下载链接】deveco-cli集成HarmonyOS应用开发工具集提供知识文档和精品Skills支持多种智能体助力开发者使用AI辅助高效开发HarmonyOS应用。项目地址https://gitcode.com/openharmony-sig/deveco-cli点击查看免费下载导读本文基于 openharmony-sig/deveco-cli 仓库中的 .plugin/AGENTS.md 展开系统讲解如何为智能体Agent宿主构建一个能「发现、安装并运行 DevEco CLI」的插件包括platforms.json多宿主配置、CLI 查找优先级、私有安装private Runtime生命周期、受限命令策略、构建/校验/冒烟测试脚本以及发布产物规范。读完本文你将掌握该插件从源码到dist/plugin/platform/发布 ZIP 的全链路设计并能据此为新宿主扩展配置或排查插件安装与 CLI 选择问题。一、插件是什么给 Agent 一个可用的 DevEco CLI插件的核心目标非常聚焦为智能体提供一项 Skill 和一组命令让它能够查找、安装并运行 DevEco CLI从而在对话式环境中完成 HarmonyOS 开发任务创建项目、编译运行、签名、模拟器、文档查询等。几个关键边界在设计之初就已划定见 .plugin/AGENTS.md 的 Code Structure 一节CLI 与插件分离安装DevEco CLI、DevEco Studio 和 SDK 需要单独安装插件只负责找到可用的 CLI 并按需安装 CLI 本身。插件不注册 MCP 服务插件只提供 Skill 与命令入口不涉及 MCP server 注册。运行环境要求Node.js 22 是硬性前提安装 CLI 还需要 npm 以及可访问 npm registry 的网络。这一约束在源码中有直接体现runtime/main.ts 在入口处即校验 Node 大版本低于 22 直接抛错DevEco CLI requires Node.js 22 or later.packages/cli/package.json 与 packages/cli-wrapper/package.json 的engines.node也声明为22。二、代码结构一份文件对应一个职责原文档给出了一张文件职责对照表结合仓库实际内容整理如下文件职责.plugin/platforms.jsonAgent 宿主设置宿主名、manifest 路径、CLI 查找目录与安装目录.plugin/README.md插件市场页面模板功能特性、使用方法、设置项含{{hostName}}等模板变量.plugin/runtime-skill-supplement.md构建时注入根 SKILL.md 的插件运行指导文本.plugin/bin/*启动 Node 并透传run/check/install模式与命令参数devecocli、devecocli-install、devecocli-runtime-check三对含.cmd.plugin/runtime/main.ts检查 Node、按模式分发、打印检查结果、应用私有 CLI 限制规则.plugin/runtime/resolve.ts查找 CLI 入口文件、读取 npm 包版本、选择最终使用的 CLI.plugin/runtime/install.ts定位 npm、加锁安装目录、校验新 CLI、将其设为 current.plugin/runtime/process.ts / .plugin/runtime/types.ts运行与清理子进程定义 Runtime、进程与安装依赖的类型.plugin/scripts/platforms.mjs校验宿主设置、构建输出路径、替换模板变量.plugin/scripts/build.mjs生成 Skill、打包 Runtime、创建插件目录、ZIP 与校验和.plugin/scripts/validate.mjs检查目录与 ZIP 内容、元数据、模板与启动器.plugin/scripts/smoke.mjs从 npm 真实安装一个 CLI校验版本与帮助输出.plugin/tests/plugin.test.ts测试宿主设置、构建产物、CLI 选择、安装与进程行为以bin/devecocli为例它的实际实现.plugin/bin/devecocli非常薄先检查node是否可用然后exec node $SCRIPT_DIR/../runtime/main.mjs run $把控制权交给打包后的 Runtime 入口。这也是校验脚本要求每个 launcher 必须包含deveco-cli-plugin-entry标记的原因——Runtime 在扫描 PATH 时需要据此识别并跳过插件自身的入口.plugin/scripts/validate.mjs、.plugin/runtime/resolve.ts。三、共享设计多宿主复用同一套源码3.1 一个platforms.json驱动所有宿主插件遵循「所有宿主共享同一份源文件」的原则每新增一个宿主只需在 .plugin/platforms.json 中添加一个条目把该宿主的设置集中存放。以当前唯一的 Qoder 配置为例{ platform: qoder, hostName: Qoder, agentName: qoder, manifestPath: .qoder-plugin/plugin.json, manifest: { name: deveco-cli, version: 0.1.0, displayName: DevEco CLI / 鸿蒙开发, description: 通过 DevEco CLI 创建、构建、运行和调试 HarmonyOS 应用查询鸿蒙文档并检查设备 UI。, author: { name: DevEco CLI Maintainers }, homepage: https://gitcode.com/openharmony-sig/deveco-cli, repository: https://gitcode.com/openharmony-sig/deveco-cli, license: MIT, keywords: [harmonyos, deveco, arkts, arkui, 鸿蒙] }, runtime: { hostBinDirs: [.qoder/bin, .qoder-cn/bin], installRoot: .local/share/qoder/deveco-cli } }loadPlatforms.plugin/scripts/platforms.mjs在构建前会做严格校验平台名必须匹配^[a-z0-9-]$且不重复manifestPath必须位于点目录如.qoder-plugin/避免覆盖共享文件manifest 的name必须为deveco-cli且版本符合 semverhostBinDirs与installRoot必须是相对用户主目录的路径HOME_RELATIVE正则校验拒绝绝对路径与../逃逸。测试 .plugin/tests/plugin.test.ts 用test.each覆盖了空数组、重复平台、非法路径、错误插件名等全部拒绝分支。3.2 版本信息从哪里来CLI 包名、最低版本与默认安装版本读取 packages/cli/package.json构建时实际以packages/cli-wrapper/package.json为发布载体见 .plugin/scripts/build.mjs。当前仓库中 wrapper 包名为deveco-test/deveco-cli版本1.3.5-Test.4其bin.devecocli指向cli.js。插件版本读取宿主 manifest即platforms.json中manifest.version。构建产物的两份元数据runtime.json记录 CLI 包名、最低 Node 版本固定nodeMajorMinimum: 22与宿主 Runtime 设置hostBinDirs、installRootprovenance.json记录源提交git rev-parse HEAD、工作树是否 dirty、平台、版本与根 SKILL.md 的 SHA-256.plugin/scripts/build.mjs。设计要点是插件更新后下一次 check 会按新的最低版本要求重新选择 CLI但已安装的 CLI 保持不变——插件与 CLI 是两条独立的更新线。3.3 CLI 选择顺序核心机制Runtime 按如下优先级选择 CLI.plugin/runtime/resolve.ts 的resolveRuntime实现DEVECO_PLUGIN_RUNTIME_EXECUTABLE指定的绝对文件路径——直接使用跳过最低版本检查路径必须绝对且有效无效路径直接报错依次搜索runtime.hostBinDirs相对用户主目录中的 CLI——目录不存在、版本过低或无法识别时跳过并继续这些目录仅用于查找安装器不会改动它们按序搜索绝对 PATH 目录会忽略插件自身 launcher——找到的首个 CLI 版本不达标时继续尝试第 4 项除显式路径外所有条目都必须满足最低版本旧版本或无法识别的版本会被记录进skippedruntime.installRoot下由插件安装的私有 CLI即 plugin-managed Runtime——同样必须满足最低版本。resolveRuntime的判定依赖两个关键函数.plugin/runtime/resolve.tsisSemver用正则^\d\.\d\.\d(?:-[0-9A-Za-z.-])?(?:\[0-9A-Za-z.-])?$判断版本可识别meetsMinimum复用仓库自带的compareVersionspackages/cli/src/utils/semver.js 的导出比较版本是否不低于packageVersion。版本读取不执行 CLIentryPackage.plugin/runtime/resolve.ts向上最多遍历 3 层目录查找package.json确认bin.devecocli指向的正是该入口后返回包名与版本。测试 .plugin/tests/plugin.test.ts 专门验证了check模式不会执行 CLI用 marker 文件证明未产生任何副作用、不会安装任何东西。关键行为约定在会话中第一次执行 CLI 任务之前先运行devecocli-runtime-check后续所有调用使用它返回的绝对launcher路径而不是依赖 PATH 顺序应用类命令以用户项目目录作为 cwd。main.ts的check分支输出 JSON包含sourceexplicit / host / path / private、entry、version、skipped、launcher、nodeVersion、minimumVersion、defaultPackage.plugin/runtime/main.ts方便 Agent 精确得知当前生效的 CLI。3.4 私有安装生命周期锁、UUID 目录与原子切换私有 CLI 安装在runtime.installRoot相对用户主目录下DEVECO_PLUGIN_INSTALL_ROOT可指定其他绝对路径但安装目录必须在插件目录与当前项目目录之外且不改动全局 npm prefix 与 PATH。installRoot函数.plugin/runtime/resolve.ts会校验该变量必须为绝对路径。installRuntime.plugin/runtime/install.ts的完整流程若请求版本是 semver先做最低版本断言assertMinimum不满足直接拒绝且不执行 npm校验目标目录位置合法性inside(pluginRoot, root)/inside(process.cwd(), root)均拒绝且不允许是文件系统根定位 npm优先用 npm 自身的 JavaScript 入口node_modules/npm/bin/npm-cli.js或../lib/node_modules/npm/bin/npm-cli.js避免 cmd.exe 引号问题并保留 registry 配置npmInvocation.plugin/runtime/install.ts以wx独占方式创建install.lock并写入{ pid, packageName, version }若已存在则报错Another installation holds ...并提示确认中断进程已停止后再移除锁以randomUUID()生成 installId安装到installs/UUID/执行npm install --prefix target --no-audit --no-fund --omitdev packageversion三重校验包名与bin.devecocli必须匹配 → 版本满足最低要求 → 用 Node 执行入口的--versionstdout 必须与package.json版本完全一致30 秒超时全部通过后把状态文件写入current-UUID.json再rename为current.json完成原子切换失败时清理新安装目录、保留当前版本成功后保留旧安装目录便于回退。测试 .plugin/tests/plugin.test.ts 验证安装只使用私有 prefix、绝不带-g/--globalL770-L816 覆盖了「安装失败 / 版本未通过校验 / 版本过低」三种情况下current.json与旧安装目录均保持不变L818-L856 验证并发安装时第二个安装者因锁直接失败。另外注意npmEnvironment.plugin/runtime/install.ts若环境存在npm_config_allow_scripts会把它从环境中移除并写入目标目录的.npmrcallow-scripts...因为 npm 12 对 prefix 安装会拒绝该环境变量策略值含换行时报错。安装过程还遵循用户的 npm registry、代理与脚本权限设置。3.5 私有 CLI 的受限命令策略私有 Runtime 出于「不改变用户全局环境」的约束拒绝以下命令.plugin/runtime/main.ts 的changesAgentSetupinit包括--mcp——只放行init --help、init -h、init helpskills add/skills remove——只放行skills list、skills find以及各类--help形式update不带子命令——拒绝并提示改用devecocli-install但update docs、update --help放行。这些规则即使私有条目被显式指定DEVECO_PLUGIN_RUNTIME_EXECUTABLE也照样生效。判定私有条目的逻辑是isPrivateEntry.plugin/runtime/main.ts来源为private或入口路径位于installRoot/installs/之下。测试 L874-L907 用一长串被拦截的init/skills参数组合验证私有 Runtime 绝不改写任何 Skill 文件L909-L933 验证只读命令被正常透传。3.6 全局 CLI 升级与 Skill 刷新路径当用户同意升级全局 CLI 时先验证升级后的全局条目满足最低版本然后**用该全局条目而非插件 launcher**执行init --skill --agent agentName --force刷新全局 Skill且不覆盖项目级 Skill私有安装则保持所有 Skill 与 Agent 设置不变。这一约定同时写入 .plugin/runtime-skill-supplement.md 与 .plugin/tests/plugin.test.ts测试断言生成的 Skill 包含## Qoder Plugin Runtime小节与--agent qoder --force。3.7 授权复用与免交互命令安装、登录、接受协议复用会话中已有的授权仅当缺少对应授权时才询问登录使用devecocli auth login --no-prompt跳过终端回车确认用户在浏览器完成认证非 TTY stdin 也会自动跳过模拟器协议先devecocli emulator license view展示文本经授权后执行devecocli emulator license accept免提示接受随后继续被阻塞的操作绝不在 Agent 终端使用交互式devecocli emulator license表单。3.8 子进程转发与中断处理runProcess.plugin/runtime/process.ts以spawnshell: false防止 shell 注入启动子进程透传调用方的 cwd、环境变量与 stdio并返回其退出码每次启动外部命令前调用debugLog复用 packages/cli/src/utils/logger.ts。中断采用两级策略forwardInterrupts.plugin/runtime/process.ts首次收到 SIGINT/SIGTERM 转发给子进程并提示「再中断一次将强制终止」等待子进程自行清理第二次收到则直接SIGKILL进程结束时移除监听器。Windows 上控制台 CtrlC 可直接到达子进程因此对SIGINT不做kill转发避免强制终止。测试 L969-L1008Unix 下验证 SIGTERM 到达 CLI 且其退出被等待L708-L735 用含空格、中文、引号、%PATH%、$(bad)等参数的极端用例验证 argv 原样透传、退出码23与 stderr 均保真。四、平台细节Qoder 宿主与操作系统差异4.1 Qoder 宿主配置platform与agentNameqodermanifest 路径.qoder-plugin/plugin.json构建时生成源码中不存在该文件测试 L266-L277 确认这一点CLI 查找顺序DEVECO_PLUGIN_RUNTIME_EXECUTABLE→~/.qoder/bin→~/.qoder-cn/bin→PATH→~/.local/share/qoder/deveco-cli默认安装目录~/.local/share/qoder/deveco-cli。4.2 Windows 与 Unix 差异Windows按devecocli.cmd→devecocli.exe顺序查找从标准 npm.cmd文件中读取 JavaScript 入口正则匹配%dp0%\...js并用 Node 参数数组运行保证 Windows 不会把用户 argv 当 shell 代码解释.plugin/runtime/resolve.ts自定义批处理文件不受支持控制台 CtrlC 直接到达子进程。Unix查找devecocli接受可执行文件与 Node 脚本含 shebang 判定.plugin/runtime/resolve.ts.exe直接作为命令运行。五、开发与校验命令矩阵与测试纪律5.1 开发命令命令使用时机npm run lint插件 TypeScript / MJS 改动之后npm run test:plugin运行插件类型检查与 Vitest 测试tsc -p .plugin vitest run --config .plugin/vitest.config.tsnpm run build:plugin为所有配置的宿主构建并校验目录与 ZIPnpm run check:plugin仅检查既有构建产物对应 .plugin/scripts/validate.mjsnpm run smoke:plugin安装器或发布相关改动之后联网真实安装 npm 包做冒烟对应 .plugin/scripts/smoke.mjsgit diff --check检查空白错误文档链接需另行检查插件测试使用独立的 .plugin/vitest.config.ts仅包含.plugin/tests/**/*.test.ts因此根目录的npm test不会执行它们。改动范围对应的检查方式遵循 .agents/skills/deveco-check-changes/SKILL.md。5.2 测试编写纪律每个测试使用独立目录并设置 cwd 与环境测试用vi.stubEnv/vi.unstubAllEnvs隔离DEVECO_PLUGIN_INSTALL_ROOT等变量删除目录前恢复环境变更并等待子进程退出断言选中的 CLI、skipped、参数、退出码与文件状态回归测试需确认「旧 bug 存在时测试会失败」。5.3 冒烟测试做了什么.plugin/scripts/smoke.mjs 在临时目录中构造隔离环境清空PATH/HOME/npm_config_cache/deveco_plugin_*等变量设置DEVECO_PLUGIN_INSTALL_ROOT与DEVECO_CLI_DATA_DIR到临时目录、DEVECO_CLI_DISABLE_TELEMETRY1然后对每个平台真实执行install→ 解析check输出断言source private→ 执行run --version断言与packageVersion一致 → 执行run --help断言包含build与run。整个过程结束后递归清理临时目录。六、发布产物dist/plugin/platform/的构成与校验6.1 产物清单构建输出写入dist/plugin/platform/仓库根目录下由outputRoot定义见 .plugin/scripts/platforms.mjsdeveco-cli/插件文件夹以插件版本命名的 ZIPdeveco-cli-version.zip及其 SHA-256 文件Runtime 打包为runtime/main.mjstsup 以node22为目标、ESM 格式打包 .plugin/runtime/main.ts见 .plugin/scripts/build.mjsmanifest 写入manifestPath.qoder-plugin/plugin.jsonZIP 内插件文件直接放在根目录。6.2 白名单校验拒绝多余文件.plugin/scripts/validate.mjs 定义了严格的文件白名单构建与校验只允许以下内容多一个文件都会失败manifest三对bin/*launcherdevecocli、devecocli-install、devecocli-runtime-check各自的 Unix 与.cmd版本runtime/main.mjsskills/deveco-cli/SKILL.md生成后的 SkillREADME.md、LICENSE、PRIVACY.mdruntime.json与provenance.json两份元数据。开发文档、源码与测试绝不进入发布包。校验内容还包括manifest 与platforms.json逐字段一致runtime.json的packageName匹配^[a-z0-9-]\/deveco-cli$、nodeMajorMinimum 22、Runtime 路径与平台配置一致provenance.json的skillSha256为 64 位 hex生成的 Skill 必须保留---frontmattername: deveco-cli且恰好包含一个## hostName Plugin Runtime标题README 与 Skill 中不得残留未渲染的{{var}}bin/*必须为 LF 行尾、包含deveco-cli-plugin-entry标记ZIP 内的 Unix launcher 必须带可执行权限位0o111且不允许符号链接。6.3 发布流水线GitCode 每日工作流daily workflow在发布 CLI 之前运行插件测试与构建随后检查真实安装并上传 ZIP。客户端加载、真实项目任务与市场发布需另行人工验证。七、二次开发速查如何接入新宿主若要为新的 Agent 宿主扩展插件按以下步骤即可全部为仓库内可验证的路径在 .plugin/platforms.json 添加一条平台配置platform/hostName/agentName/manifestPath/manifest/runtimehostBinDirs与installRoot使用相对主目录路径修改 .plugin/README.md 与 .plugin/runtime-skill-supplement.md 中需要按宿主区分的文本共享命令/参数变化时同步更新根 SKILL.md 与 README.md如需新增模板变量在 .plugin/scripts/platforms.mjs 的templateVariables中定义renderTemplate会自动拒绝未知变量名测试 L345-L355 覆盖执行npm run lint、npm run test:plugin、npm run build:plugin发布前视改动运行npm run smoke:plugin产物出现在dist/plugin/platform/由 .plugin/scripts/validate.mjs 把关文件清单与元数据一致性。注意本文所述版本、路径与命令以当前仓库快照为准如deveco-test/deveco-cli1.3.5-Test.4、platforms.json中 manifest0.1.0发布到 npm 的实际包名与版本可能不同请以构建时生成的runtime.json为准。结语从platforms.json的声明式配置到resolveRuntime的四级选型、installRuntime的锁与原子切换再到validate.mjs的白名单校验——这个插件用一套紧凑的源码同时实现了「多宿主复用、全局 CLI 优先、私有 Runtime 兜底、绝不污染用户环境」四个目标。理解 .plugin/AGENTS.md 与其背后的 .plugin/runtime 实现你既能准确排查「为什么选中了某个 CLI」「安装为什么失败」也能用最少的改动为新的智能体宿主接入 DevEco CLI。赞分享开发工具CLIOpenHarmonyMCP 服务移动开发【免费下载链接】deveco-cli集成HarmonyOS应用开发工具集提供知识文档和精品Skills支持多种智能体助力开发者使用AI辅助高效开发HarmonyOS应用。项目地址https://gitcode.com/openharmony-sig/deveco-cli点击查看免费下载相关推荐DevEco CLI 鸿蒙开发插件Agent 插件完整使用指南安装、CLI 选择与实战配置DevEco CLI 鸿蒙开发插件Agent 插件完整使用指南安装、CLI 选择与实战配置 本文以开源仓库 openharmony sig/deveco开发工具CLIOpenHarmonyMCP 服务移动开发DeepChat .dcplugin 插件打包体系从插件目录到嵌入发布产物的完整流水线DeepChat .dcplugin 插件打包体系从插件目录到嵌入发布产物的完整流水线 DeepChat 通过自有的 .dcplugin 打包格式把 pluAI Agent人工智能AI 应用桌面应用MCP ClientsEmDash 插件发布实战从 emdash-plugin CLI 校验到 GitHub 委托发布的完整指南EmDash 插件发布实战从 emdash plugin CLI 校验到 GitHub 委托发布的完整指南 EmDash 是一个基于 Astro 的全栈 TyCMS后端前端插件系统上一篇三步解锁 Wand 专业版开源增强工具 Wand-Enhancer 上手全攻略下一篇Serial-Studio256K帧/秒的串口调试与数据可视化仪表板完整上手指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考