ECC 指南：为 HarmonyOS / ArkTS 项目配置自动化构建与验证 Hooks
发布时间：2026/9/11 18:18:08 作者：尧图编辑部 阅读量：1,286
ECC 指南为 HarmonyOS / ArkTS 项目配置自动化构建与验证 Hooks【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC导读本文基于 ECC 仓库中的 rules/arkts/hooks.md日语版本见 docs/ja-JP/rules/arkts/hooks.md系统讲解如何为 HarmonyOS / ArkTS 项目接入 ECC 的事件驱动 Hook 体系在 Agent 每次编辑.ets/.ts/module.json5/oh-package.json5之后自动触发hvigor构建、权限校验与依赖重装并在写入代码前用 PreToolUse 钩子拦截 V1 状态管理装饰器。读完本文你将掌握一套改完即校验、写入即约束的 HarmonyOS 开发闭环可直接复制其中的 JSON 片段到自己的 Hook 配置中使用。Hook 机制ECC 事件驱动自动化的基础ECCEverything Claude Code将 Hook 定义为在 Agent 工具调用前后触发的自动化命令用于强制代码质量、尽早发现错误并消除重复性检查。rules/common/hooks.md 给出了三种核心 Hook 类型PreToolUse在工具执行之前触发可用于校验、参数修改甚至以退出码 2 阻断工具调用PostToolUse在工具执行之后触发用于自动格式化、结果检查无法阻断Stop会话结束时触发执行最终验证。在实际运行层面hooks/README.md 补充了完整的事件流用户请求 → Agent 选择工具 → PreToolUse Hook 运行 → 工具执行 → PostToolUse Hook 运行此外还有SessionStart、SessionEnd、PreCompact等生命周期钩子。HarmonyOS / ArkTS 的 Hook 规则正是基于这一通用机制叠加了hvigor构建与ohpm依赖管理特有的校验逻辑。HarmonyOS 规则文件通过 YAML frontmatter 声明生效范围即 Hook 的 matcher 匹配目标paths: - **/*.ets - **/*.ts - **/module.json5 - **/oh-package.json5这意味着下述所有构建命令与 Hook 约定仅作用于 ArkTS 源文件、TypeScript 文件、模块声明文件module.json5与依赖清单oh-package.json5与仓库中其他语言规则如 rules/cpp/hooks.md、rules/python互不干扰。构建命令基础hvigor 与 ohpmHarmonyOS 项目的构建由hvigorHarmonyOS 构建引擎驱动依赖管理由ohpmOpenHarmony Package Manager负责。ECC 的 ArkTS Hook 全部围绕这两条命令链设计。HAP 包构建# 构建 HAP 包全局 hvigor 环境 hvigorw assembleHap -p productdefault # 指定模块构建 hvigorw assembleHap -p moduleentry -p productdefault # 清理构建 hvigorw cleanassembleHap将模块编译并打包为 HAPHarmonyOS Ability Package-p productdefault选择构建产物配置多产品变体如default、phone、tablet时可切换-p moduleentry限定到某个模块如默认的entry模块适合多模块工程局部验证clean清空增量构建缓存在出现难以排查的编译问题时使用。-p参数可以叠加如-p moduleentry -p productdefault与 examples/harmonyos-app-CLAUDE.md 中要求的每次实现完成后运行hvigorw assembleHap -p productdefault验证编译保持一致。DevEco Studio CLI 与依赖管理# 检查项目结构 / 确认 hvigor 环境 hvigorw --version # 安装依赖 ohpm install # 更新依赖 ohpm updatehvigorw --version确认 hvigor wrapper 与 SDK 版本匹配通常在项目环境异常时首先执行ohpm install依据oh-package.json5安装全部依赖ohpm update将依赖更新到清单允许的最新版本需谨慎使用见后文依赖安全。此外单元/仪器测试场景下还会用到hvigorw testHap -p productdefault与hdc shell aa test详见 rules/arkts/testing.md这些命令同样可以被包装为 Hook。PostToolUse 推荐 Hook改完即校验PostToolUse Hook 在 Agent 完成编辑后自动运行是本规则的核心实战部分。以下三个 JSON 配置片段可直接复制。编辑 .ets / .ts 文件后编译错误检查ArkTS 文件修改后最直接的质量信号就是能否通过编译。以下 Hook 在每次Edit/Write命中.ets/.ts文件后自动执行完整 HAP 构建并把 stdout/stderr 合并后截取末尾 20 行{ type: PostToolUse, matcher: { tool: [Edit, Write], filePath: [**/*.ets, **/*.ts] }, hooks: [ { command: hvigorw assembleHap -p productdefault 21 | tail -20, async: true, timeout: 60000 } ] }要点解读matcher.tool 为数组同时匹配Edit修改与Write新建/整写两种工具filePath使用 glob 匹配两种 ArkTS 源文件后缀21 | tail -20将错误输出并入标准输出只保留最后 20 行避免完整构建日志淹没上下文——编译器报错信息通常集中在构建输出末尾async: true异步执行不阻塞 Agent 主流程适合耗时较长的完整构建参考 hooks/README.md 中异步 Hook 无法阻断工具执行的约定60 秒超时对中等规模 HAP 构建是合理起点复杂工程可适当加大。编辑 module.json5 后权限与能力声明校验module.json5是 HarmonyOS 模块的声明文件集中了权限requestPermissions、Ability、ExtensionAbility 等关键配置。修改后应人工核对声明完整性{ type: PostToolUse, matcher: { tool: Edit, filePath: **/module.json5 }, hooks: [ { command: echo [HarmonyOS] module.json5 modified - verify permissions and abilities, async: false } ] }async: false同步执行确保提醒必然出现在 Agent 视野中不会被异步任务吞掉此处命令是纯提示echo不执行自动修改因为权限声明的增删需要结合 API 调用场景由开发者判断更严格的方案可在此基础上接入 rules/arkts/security.md 的权限清单权限是否声明、reason 字符串是否在资源中定义、敏感权限是否有运行时申请逻辑作为检查脚本。编辑 oh-package.json5 后重新安装依赖oh-package.json5是 HarmonyOS 的依赖清单Agent 在编辑它之后工作区内的node_modules等效物oh_modules可能已过期。该 Hook 自动重新安装依赖以消除版本漂移{ type: PostToolUse, matcher: { tool: Edit, filePath: **/oh-package.json5 }, hooks: [ { command: ohpm install 21 | tail -10, async: true, timeout: 30000 } ] }tail -10只保留安装过程末尾的输出如版本解析结果或错误摘要30 秒超时覆盖常规依赖安装耗时。配合 rules/arkts/security.md 的依赖安全建议仅使用官方 ohpm 仓库、固定版本号、定期检查已知漏洞可实现依赖变更的自动化收敛。PreToolUse 推荐 HookV1 装饰器守卫PreToolUse 在工具执行前触发适合做写入即约束的守卫。HarmonyOS 规则的核心红线是状态管理只用 V2ComponentV2、Local、Param、Event、Provider、Consumer、Monitor、Computed以及ObservedV2Trace的类级观察模型V1 装饰器State、Prop、Link、ObjectLink、Observed、Provide、Consume、Watch、Component已被废弃详见 rules/arkts/patterns.md 的禁止清单。路由同样只允许NavigationNavPathStack禁止ohos.router。在每次Write/Edit写.ets文件前用以下守卫提醒 Agent 使用 V2 装饰器{ type: PreToolUse, matcher: { tool: [Write, Edit], filePath: **/*.ets }, hooks: [ { command: echo [HarmonyOS] Reminder: Use ComponentV2 / Local / Param - V1 decorators (State, Prop, Link) are prohibited } ] }说明这是一个警告型守卫echo 提示、退出码 0只提醒不阻断若需强制拦截可在command中改为检测new_string中是否含 V1 装饰器并process.exit(2)PreToolUse 专属阻断语义见 hooks/README.md 的退出码约定0放行、2阻断、其他非零仅记日志守卫与 agents/harmonyos-app-resolver.md 中 HarmonyOS 专家 Agent 的职责一致——该 Agent 在代码评审时会标记任何 V1 状态管理用法并建议迁移到 V2PreToolUse 守卫把这条评审规则前移到写入之前。深入原理Hook 配置结构、异步控制与运行时开关为了让上述配置真正落地理解 ECC 的 Hook 运行时是必要的。仓库自身的 hooks/hooks.json 是生产级参考实现展示了真实 Hook 的完整结构每个 Hook 含matcher可匹配Bash、Write、Edit|Write、.*等、type: command、command、可选的description、id、async、timeout。其中id用于运行时细粒度控制——这与本规则中给出的简化 JSON 是同一模式。关键设计点stdin/stdout 协议Hook 命令以 JSON 接收工具输入tool_name、tool_input、PostToolUse 时含tool_output必须原样回写 stdin 数据到 stdout 以保证工具调用继续参考 hooks/README.md 的 Hook 输入 Schemaasync 与 timeoutasync: true的 Hook 后台运行、不阻塞主流程timeout单位为毫秒。规则中三处 PostToolUse 分别使用 60000ms完整构建、无超时纯提示、30000ms依赖安装体现了耗时任务异步化、关键提醒同步化的取舍运行时开关无需改动hooks.json即可通过环境变量控制行为例如ECC_HOOKS_ENABLEDtrue主开关、ECC_HOOK_PROFILEstandard可选minimal/standard/strict、ECC_DISABLED_HOOKSpre:write:doc-file-warning精确禁用某个 Hook ID安装方式HarmonyOS 项目的 Hook 建议通过 ECC 安装器写入~/.claude/hooks/hooks.jsonbash ./install.sh --target claude --modules hooks-runtime --enable-hooks避免手工粘贴导致命令路径解析失败见 hooks/README.md。实现周期后的验证清单规则为每个实现周期收尾定义了明确的验收清单Hook 自动化负责把大部分条目提前到写入时但最终验收仍需逐项核对hvigorw assembleHap无错误完成可由.ets/.ts的 PostToolUse Hook 自动前置执行新增或修改的.ets文件中不含 V1 装饰器由 PreToolUse 守卫前置提醒新增或修改的文件中没有ohos.router导入Navigation 路由合规所有 API 权限已在module.json5中声明配合 rules/arkts/security.md 的权限声明示例requestPermissions中写明name、reason与usedScene所有依赖已列入oh-package.json5由 oh-package PostToolUse Hook 自动执行ohpm install收敛资源字符串已添加到所有 i18n 目录多语言资源完整性与 rules/arkts/patterns.md 的UI 常量一律走$r()资源引用配套新增颜色资源同时提供深色主题配色与其他规则联动一套完整的 HarmonyOS 开发规范HarmonyOS 的 Hook 规则并非孤立存在它与rules/arkts/目录下的其他规则构成闭环状态管理与路由红线rules/arkts/patterns.mdPreToolUse V1 守卫的执行依据同时规定LazyForEach、Builder、组件复用、动画性能等模式权限与安全rules/arkts/security.mdmodule.json5PostToolUse 校验的延伸覆盖权限声明格式、运行时权限申请、密钥管理HUKS、输入校验与依赖安全测试rules/arkts/testing.md测试目录结构src/ohosTest/ets/test/与hvigorw testHap命令可进一步包装为 Hook实现编辑即测试专家 Agentagents/harmonyos-app-resolver.md负责在评审阶段执行同样的合规约束与写入阶段的 Hook 守卫形成写入前提醒 写入后校验 评审时复核三道防线。对 HarmonyOS 工程而言这套 Hook 方案的价值在于把记得构建、记得声明权限、记得用 V2这类靠纪律维持的规范固化为每次工具调用的自动行为Agent 编辑 ArkTS 代码即触发编译检查触碰module.json5即提醒权限核对改动依赖清单即自动重装最终在每个实现周期用七项清单完成收尾验收从源头降低编译失败、权限缺失、依赖漂移与 V1 残留的风险。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 