opencode-harmonyos-ascf

opencode-harmonyos-ascf 是一个 OpenCode 插件，作为 HarmonyOS ASCF 全生命周期开发助手，专注于小程序转元服务、ASCF 开发问答与排障。

功能特性

• harmonyos-ascf Agent：小程序转 ASCF 元服务、ASCF 工程开发与排障
• ascf_build 工具（中期超时方案）：用插件内受控超时执行 ascf build，超时或取消时杀进程树；禁止 Agent 用 bash 跑 ASCF/HAP 构建（可配置）
• 依赖 ASCF 相关 Skills（需单独安装）

详细方案说明（问题分析、架构、优缺点、验证记录）见：docs/ascf_build-timeout-solution.md。

ascf_build 与超时配置

在工程或全局 OpenCode 配置（opencode.json / 插件配置）中可设置：

{
  "ascf_build": {
    "default_timeout_ms": 300000,
    "max_timeout_ms": 600000,
    "block_bash_ascf_build": true,
    "circuit_breaker": {
      "enabled": true,
      "max_consecutive_failures": 3
    }
  }
}

• block_bash_ascf_build 默认为 true：拦截 bash 中的 ascf build / hvigor assembleHap，引导使用 ascf_build。
• 设为 false 时仅对 bash 做 timeout 钳制，不拦截（仍建议优先 ascf_build）。
• circuit_breaker：同一工程/任务下 ascf_build 连续失败达到阈值后，在 tool.execute.before 拒绝再次调用，并向模型返回明确错误（默认 3 次）。成功后计数清零。

工具参数示例：projectRoot（可选）、task（默认 assembleHap）、buildMode（debug / release）、timeoutMs。

诊断日志：写入插件日志文件（见 getLogFilePath() / 全局 HMGlobal.Path.log 下的 plugin.log）。关键事件前缀为 ascf_build.*（如 ascf_build.start、ascf_build.process_timeout、ascf_build.guard.bash_blocked），包含 sessionID、callID、pid、durationMs，便于与 ~/.harmony-acp/logs/ 对照。

依赖 Skills

安装以下 Skills 到 OpenCode（路径参考 hm-service-agent/skills/）：

• harmonyos-atomic-ascf-convert — 小程序转 ASCF、ascf build / HAP
• harmonyos-ascf-knowledge — ASCF 文档与排障
• harmonyos-atomic-ascf-release — 发布相关（可选）
• harmonyos-atomic-service-filing — 元服务备案（可选）
• harmony-emulator-debugging — 模拟器调试（可选）
• huawei-payment-integration-release — 华为支付接入（可选）

快速开始

环境要求

• Node.js 18+
• 已安装 OpenCode CLI

安装步骤

1. 编译项目

npm install
npm run build

2. 配置插件

在 ~/.config/opencode/opencode.json 中添加本插件路径：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["/path/to/harmony-ascf"]
}

将 /path/to/harmony-ascf 替换为实际路径。

3. 重启 OpenCode

参考：OpenCode 插件使用说明

安装成功后，将出现 harmonyos-ascf Agent。

与 opencode-harmonyos-code 的关系

本插件从 harmony-code 中拆分 ASCF 能力而成。若只需通用鸿蒙应用开发，请使用 harmony-code；若专注 ASCF / 小程序转元服务，请使用本插件。

许可证

MIT