huaweicloud-devkit 1.1.8-next.2 → 1.1.8

package/README.md

@@ -344,6 +344,54 @@ Configures HTTP/HTTPS proxy for connections to Huawei Cloud services (e.g. enter
 
 Environment variables `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` take precedence over the file configuration — use `proxy show` to inspect the effective settings.
 
+## Telemetry
+
+HuaweiCloud DevKit collects **anonymous** telemetry to understand usage patterns and improve the plugin. Telemetry is **enabled by default**.
+
+### What We Collect
+
+- **Installation ID** — a SHA-256 hash derived from a machine fingerprint (hostname + MAC address + OS type + home directory). The raw values are never sent or stored.
+- **User hash** — a server-generated user identifier hash (produced by the Huawei Cloud backend `check-user` / `generatorUserIDHash` API). It is cached locally and sent with every event; it is not derived from any local PII.
+- **Plugin version** — the installed `huaweicloud-devkit` version.
+- **Agent harness** — which AI coding agent is running (e.g. `opencode`, `codex`, `codearts`).
+- **Agent version** — the agent's version string.
+- **OS type and version** — e.g. `Linux`, `Darwin`, `Windows_NT`.
+- **Capability** — how the event was triggered: `mcp` (MCP tool invocation) or `cli` (CLI command), derived from the event key.
+- **Event type** — what happened, e.g. `plugin:install`, `plugin:first_use`, `dau:active_today` (daily active), `tool:<tool_name>`, `skill:retrieve`, `sandbox:connect`.
+- **Event value** — a short sanitized string (max 255 chars, newlines/tabs stripped). For tool events this is typically `1`; for skill retrieval it is the skill name.
+
+### What We Do **Not** Collect
+
+- No AK/SK, access keys, or any credentials
+- No user input, prompts, or code content
+- No IP addresses
+- No personally identifiable information (PII)
+- No file paths or project names
+
+### How Data Is Transmitted
+
+Events are queued in memory and sent in batches (up to 100 events per batch) via HTTP POST to Huawei Cloud's telemetry endpoint every 60 seconds. Transmission respects your proxy configuration. Failed requests are retried up to 3 times, then dropped.
+
+### Disable Telemetry (Opt-Out)
+
+Set the environment variable:
+
+```bash
+export HUAWEICLOUD_DEVKIT_TELEMETRY=off
+```
+
+When set to `off`, no telemetry events are collected or transmitted.
+
+### Debug Mode
+
+To log telemetry activity for troubleshooting:
+
+```bash
+export HUAWEICLOUD_DEVKIT_DEBUG=true
+```
+
+Debug logs are written to the plugin's `telemetry/telemetry-debug.log` file.
+
 ## What It Does
 
 - **Guided cloud operations** — agents get step-by-step guidance for 20+ commonly used Huawei Cloud services (ECS, OBS, VPC, RDS, GaussDB, FunctionGraph, APIG, CCE, and more)

package/README.zh-CN.md

@@ -338,6 +338,54 @@ npx --yes huaweicloud-devkit proxy clear   # 删除代理配置
 
 环境变量 `HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 优先级高于文件配置——可使用 `proxy show` 查看最终生效的设置。
 
+## 遥测
+
+HuaweiCloud DevKit 收集**匿名**遥测数据，以了解使用模式并改进插件。遥测**默认开启**。
+
+### 收集哪些数据
+
+- **安装 ID** — 基于机器指纹（主机名 + MAC 地址 + OS 类型 + home 目录）生成的 SHA-256 哈希。原始值不会被发送或存储。
+- **用户哈希** — 服务端生成的用户标识哈希（由华为云后端 `check-user` / `generatorUserIDHash` API 生成）。本地缓存后随每次事件发送，非本地 PII 派生。
+- **插件版本** — 已安装的 `huaweicloud-devkit` 版本。
+- **Agent harness** — 正在运行的 AI 编码助手（如 `opencode`、`codex`、`codearts`）。
+- **Agent 版本** — Agent 版本号。
+- **OS 类型和版本** — 如 `Linux`、`Darwin`、`Windows_NT`。
+- **Capability** — 事件触发方式：`mcp`（MCP 工具调用）或 `cli`（CLI 命令），由事件 key 派生。
+- **事件类型** — 发生了什么，如 `plugin:install`（安装）、`plugin:first_use`（首次使用）、`dau:active_today`（日活）、`tool:<工具名>`（工具调用）、`skill:retrieve`（技能加载）、`sandbox:connect`（沙箱连接）。
+- **事件值** — 简短的脱敏字符串（最长 255 字符，换行符/制表符已清除）。工具事件通常为 `1`；技能加载事件为技能名称。
+
+### **不**收集哪些数据
+
+- 不收集 AK/SK、访问密钥或任何凭据
+- 不收集用户输入、提示词或代码内容
+- 不收集 IP 地址
+- 不收集个人可识别信息（PII）
+- 不收集文件路径或项目名称
+
+### 数据如何传输
+
+事件先在内存中排队，然后每 60 秒批量（每批最多 100 条）通过 HTTP POST 发送到华为云遥测端点。传输过程遵循你的代理配置。发送失败最多重试 3 次后丢弃。
+
+### 禁用遥测（Opt-Out）
+
+设置环境变量：
+
+```bash
+export HUAWEICLOUD_DEVKIT_TELEMETRY=off
+```
+
+设置为 `off` 后，不会收集或传输任何遥测事件。
+
+### 调试模式
+
+如需记录遥测活动以供排查：
+
+```bash
+export HUAWEICLOUD_DEVKIT_DEBUG=true
+```
+
+调试日志写入插件的 `telemetry/telemetry-debug.log` 文件。
+
 ## 功能特性
 
 - **引导式云操作** — Agent 获得 20+ 常用华为云服务的分步操作指引（ECS、OBS、VPC、RDS、GaussDB、FunctionGraph、APIG、CCE 等）

package/integrations/opencode/hooks/skill-tracker.js

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const DEBUG = process.env.HUAWEICLOUD_DEVKIT_DEBUG === 'true';
 
@@ -98,19 +99,91 @@ function getHooks() {
   };
 }
 
-// ── Export: function-as-object serves both IDE and CLI ────────
-//
-//  IDE : plugin.default()      -> returns hooks
-//  CLI : plugin.default.server -> returns hooks (via { id, server })
+// ── V2 setup: register hooks on their owning domains via the context. ──────
+//    `tool.execute.before` → ctx.tool.hook("execute.before", ...) whose single
+//    event carries `.tool` (name) and `.input` (args), replacing V1's (input, output).
+//    `event` → ctx.event.subscribe(AsyncIterable of { type, properties }).
+async function setupV2(ctx) {
+  await ctx.tool.hook('execute.before', (event) => {
+    try {
+      debugLog(`HOOK tool.execute.before tool=${event?.tool}`);
+      if (event?.tool === 'skill') {
+        const name = event?.input?.name ?? event?.args?.name;
+        debugLog(`SKILL name=${name}`);
+        if (isHuaweiCloudSkill(name)) {
+          writeEvent('skill:retrieve', name);
+          debugLog(`SKILL TRACKED: ${name}`);
+        }
+        return;
+      }
+      if (event?.tool === 'bash') {
+        const cmd = event?.input?.command ?? event?.args?.command ?? '';
+        if (!cmd) return;
+        const result = classifyHcloud(cmd);
+        if (result) writeEvent(result.key, result.value, { capability: 'cli' });
+      }
+    } catch (error) {
+      debugLog(`HOOK ERROR: ${error?.message || error}`);
+    }
+  });
 
-function plugin() {
-  debugLog('=== PLUGIN EXPORT CALLED ===');
-  return getHooks();
+  const controller = new AbortController();
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        if (event?.type === 'message.part.updated') {
+          const text = event?.properties?.part?.text;
+          if (typeof text === 'string') {
+            const m = text.match(/Base directory for this skill:\s*.*?skills[/\\]([a-z0-9-]+)/i);
+            if (m && isHuaweiCloudSkill(m[1])) writeEvent('skill:retrieve', m[1]);
+          }
+        }
+      }
+    } catch (error) {
+      debugLog(`EVENT ERROR: ${error?.message || error}`);
+    }
+  })();
+
+  return () => controller.abort();
 }
 
-plugin.id = 'huaweicloud-skill-tracker';
-plugin.server = async () => getHooks();
+// ── Dual export: one default object serves OpenCode V1 and V2 ───────────────
+//    V1 loader reads `server()` (returns legacy string-keyed hooks).
+//    V2 loader reads `id` + `setup(ctx)` (registers hooks on the context domains).
+//    `Plugin.define` is a type/runtime helper injected lazily so a V1 host that
+//    lacks `@opencode/plugin` still loads (fallback to an identity define).
+let Plugin = { define: (def) => def };
+try {
+  const require = createRequire(import.meta.url);
+  for (const pkg of ['@opencode/plugin', '@opencode-ai/plugin']) {
+    try {
+      const mod = require(pkg);
+      if (mod?.Plugin?.define) {
+        Plugin = mod.Plugin;
+        break;
+      }
+      if (typeof mod?.define === 'function') {
+        Plugin = mod;
+        break;
+      }
+    } catch {
+      // not installed in this host; keep the identity define
+    }
+  }
+} catch {
+  // createRequire unavailable; keep the identity define
+}
 
-export default plugin;
+export default {
+  ...Plugin.define({
+    id: 'huaweicloud-skill-tracker',
+    async setup(ctx) {
+      return setupV2(ctx);
+    },
+  }),
+  async server() {
+    return getHooks();
+  },
+};
 
 debugLog('=== PLUGIN INIT DONE ===');

package/integrations/opencode/opencode.json

@@ -1,11 +1,12 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "_note": "Merge this into ~/.config/opencode/opencode.jsonc. Replace the path with the absolute path to your mcp-server.mjs installation.",
+  "_note": "Merge this into ~/.config/opencode/opencode.jsonc (OpenCode 2.x). Replace the path with the absolute path to your mcp-server.mjs installation. For OpenCode 1.x, place the same entry directly under \"mcp\" (without the \"servers\" level) and add \"enabled\": true.",
   "mcp": {
-    "huaweicloud-devkit": {
-      "type": "local",
-      "command": ["node", "<绝对路径>/plugins/huaweicloud-core/src/mcp-server.mjs"],
-      "enabled": true
+    "servers": {
+      "huaweicloud-devkit": {
+        "type": "local",
+        "command": ["node", "<绝对路径>/plugins/huaweicloud-core/src/mcp-server.mjs"]
+      }
     }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "kooCliVersion": "7.2.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.8-next.2",
+  "version": "1.1.8",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

package/plugins/huaweicloud-core/skills/huawei-voucher/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: huawei-voucher
-description: '查询和领取华为云激励代金券（一人一次）。当用户首次使用、开始会话、询问插件能力，或提到"领券/代金券/优惠券/激励金/领取/福利"等话题时，先调 voucher_status 查领取状态：未领取（claimed=false）则主动提示可领取一张代金券并询问是否领取；已领取（claimed=true）或状态不明确则静默不打扰。Triggers: 首次使用, 会话开始, voucher, coupon, incentive, 领券, 代金券, 优惠券, 激励金, 领取, 福利. NOT for: 账单/费用查询（用 huawei-billing）。'
-version: 1
+description: '查询和领取华为云激励代金券（一人一次）；领取华为开发者大赛·小红书skill创新赛专属代金券（需已完成赛事报名）。激励代金券：当用户首次使用、开始会话、询问插件能力，或提到"领券/代金券/优惠券/激励金/领取/福利"等话题时，先调 voucher_status 查领取状态：未领取（claimed=false）则主动提示可领取一张代金券并询问是否领取；已领取（claimed=true）或状态不明确则静默不打扰。赛事代金券：仅在用户明确要求领取大赛代金券时调用 competition_voucher_claim，不要主动提示。Triggers: 首次使用, 会话开始, voucher, coupon, incentive, 领券, 代金券, 优惠券, 激励金, 领取, 福利, 华为开发者大赛, 小红书, skill创新赛, 赛事代金券, 大赛代金券, 比赛领券. NOT for: 账单/费用查询（用 huawei-billing）。'
+version: 2
 ---
 
-# 华为云激励代金券
+# 华为云代金券
 
-## 主动提示准则（核心）
+覆盖两类活动：**激励代金券**（通用，一人一次）与**赛事代金券**（华为开发者大赛·小红书skill创新赛，需已完成赛事报名）。两者相互独立，注意区分调用对应工具。
+
+## 激励代金券（一人一次）
+
+### 主动提示准则（核心）
 
 此能力仅在用户尚未领取时才有价值，需避免已领取用户被反复打扰。以下场景默认执行"先查后提示"：会话开始、能力导读、首次对话、提到福利领取类话题。
 
@@ -48,12 +52,40 @@ version: 1
 | `发券失败: <原文>`                                                      | 其他错误                    | 原样转达，不展开         |
 | `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK |
 
+## 赛事代金券（华为开发者大赛·小红书skill创新赛）
+
+### 1. 适用场景与调用时机
+
+用户参加华为开发者大赛·小红书skill创新赛，说出类似"帮我领取华为开发者大赛·小红书skill创新赛华为云代金券"、"领取小红书skill创新赛的券"时，调用 `huaweicloud_competition_voucher_claim`。
+
+**与激励代金券的关键区别**：赛事代金券**不做主动提示**——不要在会话开始、能力导读等场景主动推荐；仅当用户明确提及该赛事并要求领取时才调用。
+
+### 2. 调用
+
+调用 `huaweicloud_competition_voucher_claim`（生产环境无需 `domain_id`，后端从 IAM 自动解析账号；测试环境需传 `domain_id`）。
+
+后端自动完成：赛事报名校验 → 是否已领取校验 → 发券。
+
+### 3. 结果解读（错误码 UX）
+
+| 返回 message / code 特征                                                | 含义                        | 对用户表述                        |
+| ----------------------------------------------------------------------- | --------------------------- | --------------------------------- |
+| `领取成功`                                                              | 发券成功                    | 告知券已到账（含 voucherId/金额） |
+| `code=HDKIT_NOT_SIGNED_UP`（您尚未报名…）                               | 未报名该赛事                | 告知需先完成赛事报名后再来领取    |
+| `已领取过` / `已领取`                                                   | 该账号已领过赛事券          | 告知已领取，不打扰                |
+| `code=HDKIT_COMPETITION_NOT_FOUND`（赛事不存在或已下线）                | 赛事配置异常                | 告知赛事暂不可用，稍后再试        |
+| `本月代金券总额度已用完，所有账号均无法领取`                            | 全局额度用尽（HD.60630042） | 告知下月再试                      |
+| `请先完成实名认证`                                                      | 账号未实名（HD.60630022）   | 引导去控制台实名认证              |
+| `code=HDKIT_CRED_*` / 含「未配置 / not configured / AK/SK 无效 / 限额」 | 凭证未配置、无效或达限额    | 引导用户检查并配置 AK/SK          |
+| 其他（如 `赛事报名查询失败`、`发券失败: <原文>`）                       | 服务端错误                  | 原样转达，建议稍后重试            |
+
 ## 环境注意
 
-- 生产环境：`voucher_status` / `voucher_claim` 无需传 `domain_id`，后端从 IAM 自动解析账号。
+- 生产环境：`voucher_status` / `voucher_claim` / `competition_voucher_claim` 无需传 `domain_id`，后端从 IAM 自动解析账号。
 - 测试环境：需传 `domain_id`（华为云账号 ID）；未传时返回 `测试环境需提供 domain_id`。
 
 ## 注意事项
 
-- 每个账号（domain_id）仅可领取一次，重复调用返回已领取。
-- 领取结果以激励服务返回为准，不要凭本地认知猜测。
+- 激励代金券：每个账号（domain_id）仅可领取一次，重复调用返回已领取。
+- 赛事代金券与激励代金券是**两个独立活动**，领取互不影响；用户问普通代金券时不要调赛事工具，反之亦然。
+- 领取/报名结果以服务端返回为准，不要凭本地认知猜测。

package/plugins/huaweicloud-core/skills/huaweicloud-core/SKILL.md

@@ -52,7 +52,7 @@ Do not rely on training data for facts. Huawei Cloud services, pricing, quotas,
 | troubleshoot  | Troubleshooting Routing | error, bug, failed, AccessDenied, quota                                                                                                     | Handoff to huaweicloud-troubleshooting                                                                                                                                                                         |
 | api-sdk       | API/SDK Routing         | API call, SDK, REST, integration, code example                                                                                              | Handoff to huaweicloud-api-and-sdk                                                                                                                                                                             |
 | report-issue  | Issue Reporting         | wrong service, you picked wrong, incorrect                                                                                                  | Read references/report-issue.md                                                                                                                                                                                |
-| voucher       | Voucher Routing         | 领券, 代金券, 优惠券, 激励金, 领取, voucher, coupon, incentive                                                                              | Handoff to huawei-voucher                                                                                                                                                                                      |
+| voucher       | Voucher Routing         | 领券, 代金券, 优惠券, 激励金, 领取, voucher, coupon, incentive, 华为开发者大赛, 小红书, skill创新赛, 大赛代金券, 赛事代金券, 比赛领券       | Handoff to huawei-voucher                                                                                                                                                                                      |
 
 ## Service Map
 
@@ -81,6 +81,7 @@ Do not rely on training data for facts. Huawei Cloud services, pricing, quotas,
 | Temporary runtime / web app preview              | Sandbox (DevStation) | huawei-sandbox                           |
 | Getting started                                  | Account setup        | huaweicloud-cli-and-auth                 |
 | Incentive voucher                                | Voucher              | huawei-voucher                           |
+| Competition voucher (小红书skill创新赛)          | Voucher              | huawei-voucher                           |
 
 **Web app scenario layering**: for "deploy a web app", prefer `huawei-sandbox` for free/quick try (hello world, prototype, demo, temporary preview — temporary runtime + public URL (runtime lifetime not exposed via API); credential expiry see `expiresAt` from `connect`/`credentials`, zero billed resources); route to `huawei-functiongraph` / `huawei-ecs` (or `huawei-cce`) for production / long-term / custom-domain / high-availability hosting. When the chosen target requires **multiple purchased resources** (e.g. VPC + subnet + ECS + EIP + RDS, or OBS + CDN + DNS) or the user asks for an architecture/cost proposal first, hand off to `huawei-iac` for orchestrated provisioning with a mandatory cost gate.
 

package/plugins/huaweicloud-core/src/auth/agent-registration.mjs

@@ -40,7 +40,8 @@ function readJsonSafe(path) {
 function opencodeRegistered() {
   const path = opencodeConfigFile();
   const cfg = readJsonSafe(path);
-  return Boolean(cfg?.mcp?.['huaweicloud-devkit']);
+  // V2 native (`mcp.servers.*`) or V1 legacy (`mcp.*`) form.
+  return Boolean(cfg?.mcp?.['huaweicloud-devkit'] || cfg?.mcp?.servers?.['huaweicloud-devkit']);
 }
 
 function codexDesktopRegistered() {

package/plugins/huaweicloud-core/src/mcp-config-merge.mjs

@@ -32,28 +32,76 @@ function withDefaultTimeout(entry, defaultTimeout) {
   return entry;
 }
 
-// OpenCode style entry: { type, command: ['node', mcpPath, ...userArgs], ... }
-export function mergeCommandStyle(existing, { mcpPath, defaultTimeout = 300000 } = {}) {
+// OpenCode style entry: { type, command: ['node', mcpPath, ...userArgs], ... }.
+// era 'v1' writes the legacy shape (enabled + flat timeout); era 'v2' writes the
+// native V2 shape (no flat `enabled`/`timeout` — V2 uses `disabled` and a nested
+// timeout object, so both are left to OpenCode defaults unless the user set them).
+export function mergeCommandStyle(existing, { mcpPath, defaultTimeout = 300000, era = 'v1' } = {}) {
+  const v2 = era === 'v2';
+  const freshDefault = () =>
+    v2
+      ? { type: 'local', command: ['node', mcpPath] }
+      : withDefaultTimeout({ type: 'local', command: ['node', mcpPath], enabled: true }, defaultTimeout);
+
   if (!isPlainObject(existing)) {
-    return {
-      entry: withDefaultTimeout({ type: 'local', command: ['node', mcpPath], enabled: true }, defaultTimeout),
-      changed: true,
-    };
+    return { entry: freshDefault(), changed: true };
   }
   const commandIsNodeStyle = Array.isArray(existing.command) && existing.command[0] === 'node';
   if (!commandIsNodeStyle) {
     // Foreign wrapper entry: keep current overwrite behavior.
-    return {
-      entry: withDefaultTimeout({ type: 'local', command: ['node', mcpPath], enabled: true }, defaultTimeout),
-      changed: true,
-    };
+    return { entry: freshDefault(), changed: true };
   }
   const merged = { ...existing, type: 'local', command: ['node', mcpPath, ...existing.command.slice(2)] };
-  if (merged.timeout === undefined && defaultTimeout) merged.timeout = defaultTimeout;
-  if (merged.enabled === undefined) merged.enabled = true;
+  if (v2) {
+    // Native V2 shape: drop V1-only flat `enabled`/`timeout`; `disabled`,
+    // `environment`, and any nested timeout object are preserved via the spread.
+    delete merged.enabled;
+    if (typeof merged.timeout !== 'object' || merged.timeout === null || Array.isArray(merged.timeout)) {
+      delete merged.timeout;
+    }
+  } else {
+    if (merged.timeout === undefined && defaultTimeout) merged.timeout = defaultTimeout;
+    if (merged.enabled === undefined) merged.enabled = true;
+  }
   return { entry: merged, changed: !sameJson(merged, existing) };
 }
 
+// Classify an existing OpenCode config by which MCP form the DevKit entry uses:
+// `mcp.servers.*` (native V2) vs a flat `mcp.<name>` (legacy V1). Returns 'unknown'
+// when the config has no MCP section or no recognizable server entry.
+export function detectOpenCodeEra(config) {
+  if (!isPlainObject(config) || !isPlainObject(config.mcp)) return 'unknown';
+  if (isPlainObject(config.mcp.servers)) return 'v2';
+  if (Object.keys(config.mcp).some((key) => key !== 'servers' && isPlainObject(config.mcp[key]))) return 'v1';
+  return 'unknown';
+}
+
+// Place (or merge) the DevKit entry into an OpenCode config at the correct level
+// for the target era. Returns the new config plus whether an entry pre-existed and
+// whether anything changed, so callers can skip writes and restore backup deltas.
+export function mergeOpenCodeEntry(config, { mcpPath, era = 'v1' } = {}) {
+  const base = isPlainObject(config) ? config : {};
+  const key = 'huaweicloud-devkit';
+  const next = { ...base, mcp: { ...(isPlainObject(base.mcp) ? base.mcp : {}) } };
+
+  if (era === 'v2') {
+    const servers = isPlainObject(next.mcp.servers) ? { ...next.mcp.servers } : {};
+    // An entry may live in the native `servers` map or the legacy flat map; merge
+    // from whichever is present so user fields survive an era switch.
+    const existing = servers[key] ?? next.mcp[key];
+    const { entry } = mergeCommandStyle(existing, { mcpPath, era: 'v2' });
+    servers[key] = entry;
+    if (isPlainObject(next.mcp[key])) delete next.mcp[key];
+    next.mcp.servers = servers;
+    return { config: next, entry, changed: !existing || !sameJson(entry, existing), existing: Boolean(existing) };
+  }
+
+  const existing = next.mcp[key];
+  const { entry, changed } = mergeCommandStyle(existing, { mcpPath, era: 'v1' });
+  next.mcp[key] = entry;
+  return { config: next, entry, changed: !existing || changed, existing: Boolean(existing) };
+}
+
 // WorkBuddy/AtomCode/CodeArts style entry: { command: 'node', args: [mcpPath, ...userArgs], env, ... }
 export function mergeArgsStyle(existing, { mcpPath, env = {}, defaultTimeout = 300000 } = {}) {
   if (!isPlainObject(existing)) {
@@ -105,17 +153,19 @@ export function extractUserDelta(entry, style) {
   } else {
     return null;
   }
-  if (isPlainObject(entry.env)) {
-    const userEnv = Object.fromEntries(Object.entries(entry.env).filter(([key]) => !REQUIRED_ENV_KEYS.has(key)));
+  const env = isPlainObject(entry.env) ? entry.env : isPlainObject(entry.environment) ? entry.environment : null;
+  if (env) {
+    const userEnv = Object.fromEntries(Object.entries(env).filter(([key]) => !REQUIRED_ENV_KEYS.has(key)));
     if (Object.keys(userEnv).length > 0) delta.env = userEnv;
   }
   if (entry.timeout !== undefined && entry.timeout !== 300000) delta.timeout = entry.timeout;
-  if (entry.enabled === false) delta.enabled = false;
+  // Canonical "disabled" marker: V1 uses `enabled:false`, V2 uses `disabled:true`.
+  if (entry.enabled === false || entry.disabled === true) delta.enabled = false;
   return Object.keys(delta).length > 0 ? delta : null;
 }
 
 // Apply a previously saved delta onto a freshly written default entry.
-export function applyUserDelta(entry, delta, style) {
+export function applyUserDelta(entry, delta, style, era = 'v1') {
   if (!isPlainObject(entry) || !isPlainObject(delta)) return entry;
   const merged = { ...entry };
   if (style === 'command' && Array.isArray(delta.commandExtra)) {
@@ -124,10 +174,24 @@ export function applyUserDelta(entry, delta, style) {
     merged.args = [...entry.args, ...delta.argsExtra];
   }
   if (isPlainObject(delta.env)) {
-    merged.env = { ...(isPlainObject(entry.env) ? entry.env : {}), ...delta.env };
+    // V2 native entries use `environment`; V1 (and args-style agents) use `env`.
+    if (style === 'command' && era === 'v2') {
+      merged.environment = { ...(isPlainObject(merged.environment) ? merged.environment : {}), ...delta.env };
+      delete merged.env;
+    } else {
+      merged.env = { ...(isPlainObject(merged.env) ? merged.env : {}), ...delta.env };
+    }
   }
   if (delta.timeout !== undefined) merged.timeout = delta.timeout;
-  if (delta.enabled === false) merged.enabled = false;
+  if (delta.enabled === false) {
+    // Canonical disabled marker → era-appropriate field.
+    if (style === 'command' && era === 'v2') {
+      merged.disabled = true;
+      delete merged.enabled;
+    } else {
+      merged.enabled = false;
+    }
+  }
   return merged;
 }
 

package/plugins/huaweicloud-core/src/sandbox/hdkitservice-api.mjs

@@ -147,3 +147,17 @@ export async function hdkitVoucherClaim(domainId) {
     };
   }
 }
+
+export async function hdkitCompetitionVoucherClaim(domainId) {
+  try {
+    const body = domainId ? { domain_id: domainId } : {};
+    return await hdkitRequest('POST', 'competition/voucher/claim', body);
+  } catch (error) {
+    return {
+      claimed: false,
+      message: error?.message || 'Competition voucher service unavailable, please try again later',
+      code: error?.code,
+      ...(error?.remediation ? { remediation: error.remediation } : {}),
+    };
+  }
+}

package/plugins/huaweicloud-core/src/setup-cli.mjs

@@ -43,6 +43,8 @@ import {
   extractUserDelta,
   applyUserDelta,
   inheritPeerUserEnv,
+  detectOpenCodeEra,
+  mergeOpenCodeEntry,
 } from './mcp-config-merge.mjs';
 import { readAgentDelta, saveAgentDelta, takeAgentDelta, purgeBackup } from './mcp-config-backup.mjs';
 import { isUsableOfficeaceRoot, readOfficeaceRootMarker, writeOfficeaceRootMarker } from './officeace-paths.mjs';
@@ -646,39 +648,103 @@ function removeIfExists(p) {
   return false;
 }
 
+// ── OpenCode era detection ─────────────────────────────────────────────────
+// OpenCode 2.x reads MCP servers from `mcp.servers.<name>` (native); OpenCode
+// 0.x/1.x read from a flat `mcp.<name>`. We resolve the target form in this order:
+//   1. `--opencode-mcp-era v1|v2` explicit override
+//   2. `opencode --version` major (2 → v2, 0/1 → v1)
+//   3. the existing config's shape (`mcp.servers` → v2, flat `mcp.*` → v1)
+//   4. default `v2` (native, future-proof)
+function detectOpenCodeMajor() {
+  const attempts = process.platform === 'win32' ? [false, true] : [false]; // .cmd shims need a shell on Windows
+  for (const shell of attempts) {
+    try {
+      const r = spawnSync('opencode', ['--version'], { shell, windowsHide: true, stdio: 'pipe', timeout: 10000 });
+      const out = `${r.stdout || ''}${r.stderr || ''}`.trim();
+      const m = out.match(/v?(\d+)\.\d+/);
+      if (m) return Number(m[1]);
+    } catch {
+      // ignore and try the next attempt
+    }
+  }
+  return null;
+}
+
+function parseOpenCodeEraFlag() {
+  const idx = process.argv.indexOf('--opencode-mcp-era');
+  if (idx < 0) return null;
+  const raw = (process.argv[idx + 1] || '').toLowerCase();
+  if (raw === 'v1' || raw === 'v2') return raw;
+  console.error(`Invalid --opencode-mcp-era value "${process.argv[idx + 1] || ''}" (expected v1|v2).`);
+  process.exit(1);
+}
+
+let resolvedOpenCodeEra = null;
+function resolveOpenCodeEra() {
+  if (resolvedOpenCodeEra) return resolvedOpenCodeEra;
+
+  const flagged = parseOpenCodeEraFlag();
+  if (flagged) return (resolvedOpenCodeEra = flagged);
+
+  const major = detectOpenCodeMajor();
+  if (major === 2) return (resolvedOpenCodeEra = 'v2');
+  if (major === 0 || major === 1) return (resolvedOpenCodeEra = 'v1');
+
+  const configPath = opencodeConfigFile();
+  if (existsSync(configPath)) {
+    try {
+      const era = detectOpenCodeEra(JSON.parse(readFileSync(configPath, 'utf8')));
+      if (era !== 'unknown') return (resolvedOpenCodeEra = era);
+    } catch {
+      // fall through to default
+    }
+  }
+
+  return (resolvedOpenCodeEra = 'v2');
+}
+
 function updateOpenCodeConfig(pluginDir) {
   const configPath = opencodeConfigFile();
   const mcpPath = join(pluginDir, 'src', 'mcp-server.mjs').replace(/\\/g, '/');
+  const era = resolveOpenCodeEra();
+  const formLabel = era === 'v2' ? 'mcp.servers.huaweicloud-devkit' : 'mcp.huaweicloud-devkit';
   let config = {};
   if (existsSync(configPath)) {
     try {
       config = JSON.parse(readFileSync(configPath, 'utf8'));
     } catch {
       console.log(
-        `  \x1b[33m[WARN]\x1b[0m Could not parse ${configPath} (jsonc comments?). Skipping MCP config write; ensure "mcp.huaweicloud-devkit" points to ${mcpPath}.`,
+        `  \x1b[33m[WARN]\x1b[0m Could not parse ${configPath} (jsonc comments?). Skipping MCP config write; ensure "${formLabel}" points to ${mcpPath}.`,
       );
       return;
     }
-    const existing = config.mcp?.['huaweicloud-devkit'];
-    const { entry, changed } = mergeCommandStyle(existing, { mcpPath });
-    if (existing && !changed) {
-      console.log(`  OpenCode MCP config unchanged: ${configPath}`);
-      return;
-    }
-    if (existing && changed) {
-      config.mcp['huaweicloud-devkit'] = entry;
-      writeMcpSettingsFile(configPath, config);
-      console.log(`  OpenCode MCP config merged (user fields preserved): ${configPath}`);
-      return;
+  }
+
+  const { config: next, existing, changed } = mergeOpenCodeEntry(config, { mcpPath, era });
+
+  // Restore user fields saved by a previous uninstall (issue #615), on fresh install only.
+  if (!existing) {
+    const delta = takeAgentDelta('opencode');
+    if (delta) {
+      const key = 'huaweicloud-devkit';
+      const entry = era === 'v2' ? next.mcp.servers[key] : next.mcp[key];
+      const restored = applyUserDelta(entry, delta, 'command', era);
+      if (era === 'v2') next.mcp.servers[key] = restored;
+      else next.mcp[key] = restored;
     }
   }
-  config.mcp = config.mcp || {};
-  config.mcp['huaweicloud-devkit'] = mergeCommandStyle(undefined, { mcpPath }).entry;
-  // Restore user fields saved by a previous uninstall (issue #615).
-  const delta = takeAgentDelta('opencode');
-  if (delta) config.mcp['huaweicloud-devkit'] = applyUserDelta(config.mcp['huaweicloud-devkit'], delta, 'command');
-  writeMcpSettingsFile(configPath, config);
-  console.log(`  OpenCode config updated: ${configPath}`);
+
+  if (existing && !changed) {
+    console.log(`  OpenCode MCP config unchanged: ${configPath}`);
+    return;
+  }
+
+  writeMcpSettingsFile(configPath, next);
+  console.log(
+    existing
+      ? `  OpenCode MCP config merged (user fields preserved, ${era}): ${configPath}`
+      : `  OpenCode MCP config updated (${era}): ${configPath}`,
+  );
 }
 
 // Read-merge-write for pluginDir/.mcp.json (OpenClaw, Codex Desktop).
@@ -731,12 +797,22 @@ function removeOpenCodeConfig() {
   } catch {
     return;
   }
-  if (!config.mcp?.['huaweicloud-devkit']) return;
+  const key = 'huaweicloud-devkit';
+  const flatEntry = config.mcp?.[key];
+  const serversEntry = config.mcp?.servers?.[key];
+  const entry = serversEntry || flatEntry;
+  if (!entry) return;
   // Back up user-customized fields before removal so a later reinstall can restore them (issue #615).
-  const delta = extractUserDelta(config.mcp['huaweicloud-devkit'], 'command');
+  const delta = extractUserDelta(entry, 'command');
   if (delta) saveAgentDelta('opencode', delta);
-  delete config.mcp['huaweicloud-devkit'];
-  if (Object.keys(config.mcp).length === 0) delete config.mcp;
+  if (config.mcp) {
+    delete config.mcp[key];
+    if (config.mcp.servers) {
+      delete config.mcp.servers[key];
+      if (Object.keys(config.mcp.servers).length === 0) delete config.mcp.servers;
+    }
+    if (Object.keys(config.mcp).length === 0) delete config.mcp;
+  }
   writeMcpSettingsFile(configPath, config);
   console.log(`  OpenCode MCP config cleaned: ${configPath}`);
 }
@@ -3180,7 +3256,11 @@ function opencodeStatus() {
     try {
       const config = JSON.parse(readFileSync(configPath, 'utf8'));
       console.log(
-        `  MCP config: ${config.mcp?.['huaweicloud-devkit'] ? '\x1b[32mConfigured\x1b[0m' : '\x1b[31mNot configured\x1b[0m'}`,
+        `  MCP config: ${
+          config.mcp?.['huaweicloud-devkit'] || config.mcp?.servers?.['huaweicloud-devkit']
+            ? '\x1b[32mConfigured\x1b[0m'
+            : '\x1b[31mNot configured\x1b[0m'
+        }`,
       );
     } catch {
       console.log(`  MCP config: \x1b[31mInvalid\x1b[0m`);
@@ -4017,7 +4097,7 @@ async function cmdDoctor() {
   if (existsSync(opencodeCfg)) {
     try {
       const cfg = JSON.parse(readFileSync(opencodeCfg, 'utf8'));
-      if (cfg.mcp && cfg.mcp['huaweicloud-devkit']) {
+      if (cfg.mcp && (cfg.mcp['huaweicloud-devkit'] || cfg.mcp.servers?.['huaweicloud-devkit'])) {
         mcpConfigured = true;
         mcpCfgTarget = 'OpenCode';
       }
@@ -5188,6 +5268,9 @@ async function main() {
         '  --target     Target agent: opencode (default), codex, codearts, codearts-work, workbuddy, dsh, officeace, hermes, openclaw, atomcode, all',
       );
       console.log('  --version    Print CLI version and installed plugin version per agent');
+      console.log(
+        '  --opencode-mcp-era v1|v2   Force OpenCode MCP config form (v1 legacy flat, v2 native mcp.servers)',
+      );
       console.log('  --clean-kocli   (with: uninstall --target all) also remove KooCLI');
       console.log('  --clean-obs     (with: uninstall --target all) also remove OBS config');
       console.log('  --clean-global  (with: uninstall --target all) also remove KooCLI + OBS config');

package/plugins/huaweicloud-core/src/tools.mjs

@@ -31,6 +31,7 @@ import {
   hdkitCredentials,
   hdkitVoucherStatus,
   hdkitVoucherClaim,
+  hdkitCompetitionVoucherClaim,
   hdkitGenerateUserHash,
 } from './sandbox/hdkitservice-api.mjs';
 import { getCredentials } from './sandbox/hwlink-api.mjs';
@@ -856,6 +857,20 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  {
+    name: 'huaweicloud_competition_voucher_claim',
+    description:
+      '领取华为开发者大赛·小红书skill创新赛专属华为云代金券。前置条件：用户已完成该赛事报名（后端自动校验，未报名返回 code=HDKIT_NOT_SIGNED_UP）。仅当用户明确要求领取该赛事代金券时调用，不要主动提示。重复领取会返回已领取。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        domain_id: {
+          type: 'string',
+          description: 'Optional. Leave empty in production — account is resolved from IAM automatically.',
+        },
+      },
+    },
+  },
   {
     name: 'huaweicloud_check_update',
     description:
@@ -1570,6 +1585,8 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       return await hdkitVoucherStatus(args.domain_id);
     case 'huaweicloud_voucher_claim':
       return await hdkitVoucherClaim(args.domain_id);
+    case 'huaweicloud_competition_voucher_claim':
+      return await hdkitCompetitionVoucherClaim(args.domain_id);
     case 'huaweicloud_check_update':
       return await handleCheckUpdate(args, { sessionId: opts?.sessionId, doQuery: opts?.doQuery });
     case 'huaweicloud_upgrade':