huaweicloud-devkit 0.1.17

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

@@ -0,0 +1,672 @@
+import { planHcloudCommand, runHcloud } from './hcloud-cli.mjs';
+import { classifyTextCommand, redactSecrets } from './safety-policy.mjs';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { searchMarketplace } from './search-market.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT_DEV = join(__dirname, '..', 'skills');
+function opencodeSkillsDir() {
+  const home = homedir();
+  return join(home, '.config', 'opencode', 'skills');
+}
+function resolveSkillsRoot() {
+  if (existsSync(SKILLS_ROOT_DEV)) return SKILLS_ROOT_DEV;
+  if (existsSync(opencodeSkillsDir())) return opencodeSkillsDir();
+  return SKILLS_ROOT_DEV;
+}
+const SKILLS_ROOT = resolveSkillsRoot();
+
+export const TOOL_DEFINITIONS = [
+  {
+    name: 'huaweicloud_check_cli',
+    description: 'Check whether Huawei Cloud KooCLI hcloud is installed. Returns redacted output.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'huaweicloud_plan_cli_command',
+    description: 'Classify and plan a Huawei Cloud hcloud command without executing it.',
+    inputSchema: {
+      type: 'object',
+      required: ['args'],
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'hcloud arguments, excluding the hcloud executable.',
+        },
+        allowWrites: {
+          type: 'boolean',
+          description: 'Only true after explicit user approval for this exact operation.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_run_readonly_command',
+    description: 'Run a read-only hcloud command through the toolkit safety policy and redact output.',
+    inputSchema: {
+      type: 'object',
+      required: ['args'],
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+        timeoutMs: {
+          type: 'number',
+          description: 'Optional timeout in milliseconds. Defaults to 60000.',
+        },
+        maxRetries: {
+          type: 'number',
+          description: 'Optional retry count for transient network errors. Defaults to 1.',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Optional working directory for the hcloud process.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_list_operations',
+    description: 'List KooCLI operations for a Huawei Cloud service by running local/read-only hcloud <Service> --help.',
+    inputSchema: {
+      type: 'object',
+      required: ['service'],
+      properties: {
+        service: {
+          type: 'string',
+          description: 'KooCLI service name, such as ECS, VPC, IMS, OBS, RDS, or CDN.',
+        },
+        timeoutMs: {
+          type: 'number',
+          description: 'Optional timeout in milliseconds. Defaults to 60000.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_run_approved_command',
+    description: 'Run a write-capable hcloud command only after the exact command has been shown and explicitly approved by the user.',
+    inputSchema: {
+      type: 'object',
+      required: ['args', 'approvedCommand', 'approvedByUser'],
+      properties: {
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'hcloud arguments, excluding the hcloud executable.',
+        },
+        approvedCommand: {
+          type: 'string',
+          description: 'The exact command string previously shown to the user.',
+        },
+        approvedByUser: {
+          type: 'boolean',
+          description: 'Must be true only after the user explicitly approves this exact command.',
+        },
+        timeoutMs: {
+          type: 'number',
+          description: 'Optional timeout in milliseconds. Defaults to 60000.',
+        },
+        maxRetries: {
+          type: 'number',
+          description: 'Optional retry count for transient network errors. Defaults to 1.',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Optional working directory for the hcloud process.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_show_profile_redacted',
+    description: 'Inspect a KooCLI profile through hcloud configure show and return only redacted output.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        profile: {
+          type: 'string',
+          description: 'Optional KooCLI profile name.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_service_catalog',
+    description: 'Return the recommended capability sources for Huawei Cloud agent tasks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          description: 'Developer intent to route, such as deploy app, use API, debug error, or inspect resources.',
+        },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_explain_error',
+    description: 'Explain a Huawei Cloud CLI, API, SDK, or agent workflow error and suggest next diagnostic steps.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        service: { type: 'string' },
+        errorCode: { type: 'string' },
+        message: { type: 'string' },
+        requestId: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_search_docs',
+    description: 'Search across Huawei Cloud SKILL.md files and local documentation. Returns top 10 relevant results with source, name, snippet, and relevance score. Use when the agent needs to discover which skill covers a topic, or when uncertain about API parameters, quotas, or limitations.',
+    inputSchema: {
+      type: 'object',
+      required: ['query'],
+      properties: {
+        query: { type: 'string', description: 'Search query across skill descriptions and documentation.' },
+        topic: { type: 'string', description: 'Optional filter: all | ecs | obs | vpc | iam | rds | cce | modelarts | dew. Defaults to all.' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_retrieve_skill',
+    description: 'Retrieve a full SKILL.md by skill name. Returns the complete skill content plus list of reference files. Use when the agent has identified which skill to load and needs the full procedure.',
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: {
+        name: { type: 'string', description: 'Skill name, e.g., huaweicloud-core, huawei-ecs, huawei-obs.' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_list_regions',
+    description: 'List available Huawei Cloud regions. Returns region IDs, display names, and endpoints. Use when the agent needs to discover available regions before creating resources.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'huaweicloud_get_regional_availability',
+    description: 'Check if a specific Huawei Cloud service is available in a target region. Use before creating resources to prevent failures from regional unavailability.',
+    inputSchema: {
+      type: 'object',
+      required: ['service', 'region'],
+      properties: {
+        service: { type: 'string', description: 'Service name: ecs, obs, rds, gaussdb, cce, modelarts, functiongraph, etc.' },
+        region: { type: 'string', description: 'Region ID: cn-south-1, cn-north-4, ap-southeast-3, etc.' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_search_marketplace',
+    description: 'Search the Huawei Cloud agent skill marketplace for available skills. Returns scored results with names, categories, and descriptions. Use when built-in skills are insufficient or the user asks what skills exist.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query across skill name, description, triggers, and service.' },
+        category: { type: 'string', description: 'Optional category filter: computing, storage, network, security, devtools, monitoring, etc.' },
+      },
+    },
+  },
+];
+
+export async function callTool(name, args = {}) {
+  switch (name) {
+    case 'huaweicloud_check_cli':
+      return runVersionCheck();
+    case 'huaweicloud_plan_cli_command':
+      return planHcloudCommand(args.args || [], { allowWrites: args.allowWrites === true });
+    case 'huaweicloud_run_readonly_command':
+      return runHcloud(args.args || [], {
+        timeoutMs: args.timeoutMs,
+        maxRetries: args.maxRetries,
+        cwd: args.cwd,
+        stdin: args.stdin,
+      });
+    case 'huaweicloud_list_operations':
+      return listOperations(args.service, { timeoutMs: args.timeoutMs });
+    case 'huaweicloud_run_approved_command':
+      return runApprovedCommand(args);
+    case 'huaweicloud_show_profile_redacted':
+      return showProfileRedacted(args.profile);
+    case 'huaweicloud_service_catalog':
+      return serviceCatalog(args.intent);
+    case 'huaweicloud_search_docs':
+      return searchDocs(args.query || '', args.topic || 'all');
+    case 'huaweicloud_retrieve_skill':
+      return retrieveSkill(args.name || '');
+    case 'huaweicloud_list_regions':
+      return listRegions();
+    case 'huaweicloud_get_regional_availability':
+      return getRegionalAvailability(args.service || '', args.region || '');
+        case 'huaweicloud_explain_error':
+      return explainError(args);
+    case 'huaweicloud_search_marketplace':
+      return searchMarketplace(args.query || '', args.category || '');
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export async function runVersionCheck(options = {}) {
+  const result = await runHcloud(['version'], {
+    ...options,
+    maxRetries: options.maxRetries ?? 0,
+  });
+  const errorText = result.error || result.stderr || '';
+  const isSpawnError = /ENOENT|SPAWN_ERROR/i.test(errorText) || result.code === 'SPAWN_ERROR';
+  return {
+    installed: result.ok,
+    authenticated: result.ok && !/配置文件中不存在配置项|USE_ERROR.*配置/i.test(result.stdout || ''),
+    errorCode: isSpawnError ? 'HCLOUD_NOT_FOUND' : undefined,
+    output: result.ok ? result.stdout : errorText,
+    nextStep: result.ok
+      ? 'Use huaweicloud_show_profile_redacted to inspect the active KooCLI profile safely.'
+      : isSpawnError
+        ? 'hcloud executable not found. Set HCLOUD_BIN to the full hcloud path, or install KooCLI: npx huaweicloud-devkit install-hcloud. Then restart the agent.'
+        : 'Install Huawei Cloud KooCLI: npx huaweicloud-devkit install-hcloud. Configure credentials outside the agent conversation.',
+    authHint: 'If hcloud is installed but commands fail with "配置文件中不存在配置项", run `hcloud configure set --cli-access-key=<AK> --cli-secret-key=<SK> --cli-region=<region>` outside agent chat to configure credentials.',
+  };
+}
+
+async function showProfileRedacted(profile) {
+  const args = ['configure', 'show'];
+  if (profile) {
+    args.push('--cli-profile', String(profile));
+  }
+  const result = await runHcloud(args, { allowWrites: false, allowCredentialRead: true }).catch((error) => ({
+    ok: false,
+    blocked: true,
+    reason: error.message,
+  }));
+  if (result.blocked) {
+    return {
+      ok: false,
+      blockedByPolicy: true,
+      reason: result.reason,
+      safeAlternative: 'Use huaweicloud_show_profile_redacted so profile output is returned through the redaction pipeline.',
+    };
+  }
+  return {
+    ok: result.ok,
+    note: result.ok
+      ? 'Profile information was returned through the toolkit redaction pipeline.'
+      : 'Failed to retrieve profile — hcloud may not be installed or configured.',
+    result: redactSecrets(result),
+  };
+}
+
+const SERVICE_EXAMPLES = {
+  ECS: { list: 'ECS ListServersDetails', create: 'ECS CreateServers', show: 'IMS GlanceShowImage' },
+  VPC: { list: 'VPC ListVpcs', create: 'VPC CreateVpc', show: 'VPC ShowVpc' },
+  FunctionGraph: { list: 'FunctionGraph ListFunctions', create: 'FunctionGraph CreateFunction', show: 'FunctionGraph ShowFunctionConfig' },
+  APIG: { list: 'APIG ListInstancesV2', create: 'APIG CreateInstanceV2', show: 'APIG ShowDetailsOfInstanceV2' },
+  OBS: { list: 'OBS ls', create: 'OBS mb obs://<bucket>', show: 'OBS stat obs://<bucket>/<key>' },
+  RDS: { list: 'RDS ListInstances', create: 'RDS CreateInstance', show: 'RDS ShowInstance' },
+  CES: { list: 'CES ListAlarms', create: 'CES CreateAlarm', show: 'CES ListMetrics' },
+  GaussDB: { list: 'GaussDB ListInstances', create: 'GaussDB CreateInstance', show: 'GaussDB ShowInstance' },
+  DDS: { list: 'DDS ListInstances', create: 'DDS CreateInstance', show: 'DDS ShowInstance' },
+  DCS: { list: 'DCS ListInstances', create: 'DCS CreateInstance', show: 'DCS ShowInstance' },
+};
+
+async function listOperations(service, options = {}) {
+  const serviceName = String(service || '').trim();
+  if (!/^[A-Za-z][A-Za-z0-9-]{1,63}$/.test(serviceName)) {
+    throw new Error('service must be a KooCLI service name such as ECS, VPC, IMS, OBS, RDS, or CDN.');
+  }
+  const isObs = /^obs$/i.test(serviceName);
+  const svc = isObs ? 'obs' : serviceName;
+  const args = isObs ? ['obs', 'help'] : [svc, '--help'];
+  let result = await runHcloud(args, {
+    timeoutMs: options.timeoutMs,
+    maxRetries: 0,
+  });
+  if (!result.ok && !isObs) {
+    result = await runHcloud([svc, 'help'], {
+      timeoutMs: options.timeoutMs,
+      maxRetries: 0,
+    });
+  }
+  return {
+    service: serviceName,
+    command: isObs ? 'hcloud obs help' : `hcloud ${svc} --help`,
+    selectionRule: 'Use this help text to select the exact KooCLI operation name before planning any service command.',
+    examples: SERVICE_EXAMPLES[serviceName.toUpperCase()] || { note: `No cached examples for ${serviceName}. Use the help text above to discover available operations.` },
+    result,
+  };
+}
+
+async function runApprovedCommand(args = {}) {
+  if (args.approvedByUser !== true) {
+    throw new Error('approvedByUser must be true after explicit user approval for this exact command.');
+  }
+  const strictPlan = planHcloudCommand(args.args || [], { allowWrites: false });
+  const plan = planHcloudCommand(args.args || [], { allowWrites: true });
+  if (String(args.approvedCommand || '') !== plan.command) {
+    throw new Error('approvedCommand must exactly match the planned hcloud command.');
+  }
+  const result = await runHcloud(args.args || [], {
+    allowWrites: true,
+    timeoutMs: args.timeoutMs,
+    maxRetries: args.maxRetries,
+    cwd: args.cwd,
+    stdin: args.stdin,
+  });
+  result.approved = true;
+  result.plan = strictPlan;
+  return result;
+}
+
+function serviceCatalog(intent = '') {
+  const it = String(intent).toLowerCase();
+  const routeMap = [
+    { keywords: ['ecs', 'server', 'vm', 'instance', 'compute', 'flavor', 'image'], skills: ['huawei-ecs'], services: ['ECS'] },
+    { keywords: ['vpc', 'subnet', 'network', 'security group', 'eip', 'nat', 'vpn', 'bandwidth'], skills: ['huawei-vpc'], services: ['VPC', 'EIP'] },
+    { keywords: ['obs', 'bucket', 'storage', 'object', 'static website', 'static site', 'hosting'], skills: ['huawei-obs'], services: ['OBS'] },
+    { keywords: ['functiongraph', 'serverless', 'function', 'lambda', 'trigger', 'faas'], skills: ['huawei-functiongraph'], services: ['FunctionGraph'] },
+    { keywords: ['cce', 'kubernetes', 'k8s', 'container', 'cluster', 'node pool', 'swr', 'docker', 'image registry'], skills: ['huawei-cce'], services: ['CCE', 'SWR'] },
+    { keywords: ['apig', 'api gateway', 'publish', 'throttle'], skills: ['huawei-apig'], services: ['APIG'] },
+    { keywords: ['rds', 'mysql', 'postgresql', 'database', 'db'], skills: ['huawei-rds'], services: ['RDS'] },
+    { keywords: ['gaussdb', 'distributed', 'sharding', 'opengauss'], skills: ['huawei-gaussdb'], services: ['GaussDB'] },
+    { keywords: ['iam', 'permission', 'policy', 'role', 'user', 'ak/sk', 'access key', 'agency'], skills: ['huawei-iam'], services: ['IAM'] },
+    { keywords: ['dew', 'secret', 'kms', 'encrypt', 'decrypt', 'certificate', 'csms'], skills: ['huawei-dew'], services: ['CSMS', 'KMS'] },
+    { keywords: ['modelarts', 'ai', 'model', 'training', 'inference', 'machine learning'], skills: ['huawei-modelarts'], services: ['ModelArts'] },
+    { keywords: ['billing', 'cost', 'bill', 'budget', 'expense', 'bss'], skills: ['huawei-billing'], services: ['BSS'] },
+    { keywords: ['waf', 'aad', 'ddos', 'firewall', 'web protection'], skills: ['huawei-waf-aad'], services: ['WAF', 'AAD'] },
+    { keywords: ['smn', 'dms', 'notification', 'message', 'kafka', 'rabbitmq'], skills: ['huawei-smn-dms'], services: ['SMN', 'DMS'] },
+    { keywords: ['ces', 'monitor', 'alarm', 'metric', 'dashboard', 'cloud eye'], skills: ['huawei-cloud-eye'], services: ['CES'] },
+    { keywords: ['cts', 'audit', 'trace', 'tracker'], skills: ['huawei-cts'], services: ['CTS'] },
+    { keywords: ['cbr', 'backup', 'restore', 'vault', 'snapshot'], skills: ['huawei-cbr'], services: ['CBR'] },
+    { keywords: ['deployment', 'deploy', 'ci/cd', 'pipeline', 'release'], skills: ['huawei-deployment'], services: ['CloudDeploy'] },
+    { keywords: ['dds', 'dcs', 'mongodb', 'redis', 'memcached', 'cache', 'document db'], skills: ['huawei-dds-dcs'], services: ['DDS', 'DCS'] },
+];
+  const matched = [];
+  const tokens = it.split(/[\s,./-]+/).filter((t) => t.length > 0);
+  for (const route of routeMap) {
+    if (route.keywords.some((kw) => tokens.includes(kw))) {
+      matched.push(route);
+    }
+  }
+  const recommendedSkills = [...new Set(matched.flatMap((r) => r.skills))];
+  const recommendedServices = [...new Set(matched.flatMap((r) => r.services))].slice(0, 5);
+
+  return {
+    intent,
+    recommendedSkills: recommendedSkills.length ? recommendedSkills : ['Use huaweicloud-core to route intent.'],
+    recommendedServices: recommendedServices.length ? recommendedServices : ['Run hcloud --help to list available services.'],
+    capabilityOrder: [
+      'Huawei Cloud Skills for task-specific workflows and examples',
+      'KooCLI hcloud for local authenticated operations and quick inspection',
+      'Huawei Cloud API documentation for exact request and response contracts',
+      'Huawei Cloud SDKs for application code integration',
+      'Huawei Cloud MCP when an official or approved server is available',
+      'Terraform Provider only when IaC reviewability and repeatability are important',
+    ],
+    ruleOfThumb: {
+      skills: 'Start here when the user describes a scenario or wants a guided workflow.',
+      cli: 'Use for local diagnostics, read-only inspection, and commands the user can review.',
+      api: 'Use for exact service contract, region endpoint, project_id, pagination, and error codes.',
+      sdk: 'Use when writing application code that calls Huawei Cloud services.',
+      mcp: 'Prefer approved MCP tools when available because tools can carry structured schemas.',
+      terraform: 'Keep low priority in V1; suggest it for reviewed infrastructure changes, not quick diagnosis.',
+    },
+  };
+}
+
+function explainError({ service = 'unknown', errorCode = '', message = '', requestId = '' } = {}) {
+  const combined = `${errorCode} ${message}`.toLowerCase();
+  const suggestions = [];
+  const svc = String(service).toLowerCase();
+
+  const SERVICE_ALIASES = {
+    'functiongraph': 'FSS',
+    'fgs': 'FSS',
+  };
+  const patternKey = SERVICE_ALIASES[svc] || service;
+
+  const hwErrorPatterns = {
+    OBS: {
+      'InvalidAccessKeyId': 'OBS uses AK/SK directly (not IAM tokens). Verify AK/SK validity, OBS endpoint, and OBS permissions.',
+      'UserRestricted': 'This IAM user is restricted from OBS operations (403). Check IAM console → Users → Permissions: grant OBS bucket/object actions, or use an unrestricted account. If the account is a sub-account, the main account may have imposed restrictions.',
+    },
+    APIG: {
+      'APIC.7241': 'The enterprise_project_id is required for enterprise accounts. Add --enterprise_project_id=0.',
+      'APIC.7242': 'The EIP binding method depends on loadbalancer_provider. Use AddIngressEipV2 for elb, AddEipV2 for lvs.',
+      'APIC.7256': 'Bandwidth minimum is 5 Mbps. Use --bandwidth_size=5 or higher.',
+      'APIC.7310': 'available_zone_ids must use AZ codes (e.g. ap-southeast-3a), NOT UUIDs from ListAvailableZonesV2.',
+    },
+    FSS: {
+      'FSS.0403': 'Missing FunctionGraph IAM permissions. Attach FunctionGraph FullAccess role or grant specific actions.',
+      'FSS.1078': '--code_filename is filename-only (no path). cd to the file directory before running the command.',
+      'FSS.1417': 'event_data field validation failed. Check parameter format: use dotted key=value, verify required hidden-optional fields.',
+    },
+    VPC: {
+      'VPC.0301': 'Bandwidth name is required for PER type EIPs, even though --help marks it optional.',
+    },
+    APIGW: {
+      'APIGW.0802': 'The current IAM user has no permissions in the requested region. Go to IAM console → Users → Permissions → add the target region, or switch to a different region.',
+    },
+  };
+  if (hwErrorPatterns[patternKey] && hwErrorPatterns[patternKey][errorCode]) {
+    suggestions.push(hwErrorPatterns[patternKey][errorCode]);
+  }
+  const svcPatterns = hwErrorPatterns[patternKey] || {};
+  for (const [code, tip] of Object.entries(svcPatterns)) {
+    if (errorCode && code.includes(errorCode)) {
+      if (!suggestions.includes(tip)) suggestions.push(tip);
+    }
+  }
+
+  if (/auth|token|credential|ak|sk|401|403|unauthorized|forbidden|Incorrect IAM/i.test(combined)) {
+    if (svc === 'obs') {
+      suggestions.push('OBS uses AK/SK directly, not IAM tokens. Verify AK/SK validity and OBS bucket permissions via hcloud configure list or the Huawei Cloud console.');
+    } else {
+      suggestions.push('Check KooCLI profile, region, project_id, and IAM permissions without printing secrets.');
+    }
+  }
+  if (/APIGW\.(\d+)/i.test(errorCode)) {
+    suggestions.push('APIGW.' + (errorCode.match(/APIGW\.(\d+)/i) || [])[1] + ': API Gateway layer error. ' + (errorCode === 'APIGW.0802' ? 'IAM user has no region permissions — check IAM console → User → Permissions → add target region.' : 'Verify the API request, region endpoint, and IAM permissions.'));
+  }
+  if (/region|endpoint|project/i.test(combined)) {
+    suggestions.push('Confirm the service endpoint, region, and project_id match the target resource.');
+  }
+  if (/quota|limit|insufficient|reach the limit/i.test(combined)) {
+    suggestions.push('Check quota and resource limits before retrying a create or scale operation. Consider switching accounts or requesting a quota increase.');
+  }
+  if (/not.?found|404/i.test(combined)) {
+    if (/list.?regions/i.test(svc)) {
+      suggestions.push('Use hcloud IAM KeystoneListRegions (not list-regions).');
+    } else {
+      suggestions.push('List resources in the same region/project and verify the resource identifier.');
+    }
+  }
+  if (!suggestions.length) {
+    suggestions.push('Collect service name, operation, region, project_id, request_id, and the full redacted error message.');
+  }
+
+  if (requestId) {
+    suggestions.push('Provide the Request ID (' + requestId + ') when contacting Huawei Cloud support.');
+  }
+
+  const uniqueSuggestions = suggestions.filter((s, i, arr) => {
+    return !arr.slice(0, i).some((prev) =>
+      prev.substring(0, 50).toLowerCase() === s.substring(0, 50).toLowerCase());
+  });
+
+  return {
+    service,
+    errorCode,
+    requestId,
+    suggestions: uniqueSuggestions,
+  };
+}
+
+async function searchDocs(query, topic = 'all') {
+  const q = String(query || '').toLowerCase();
+  const tokens = q.split(/\s+/).filter((t) => t.length > 0);
+  const results = [];
+  try {
+    if (existsSync(SKILLS_ROOT)) {
+      const dirs = readdirSync(SKILLS_ROOT, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+      for (const dir of dirs) {
+        const skillPath = join(SKILLS_ROOT, dir, 'SKILL.md');
+        if (!existsSync(skillPath)) continue;
+        const content = readFileSync(skillPath, 'utf8');
+        const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        let description = '';
+        let name = dir;
+        if (frontmatter) {
+          const fm = frontmatter[1];
+          const nameMatch = fm.match(/^name:\s*(.+)$/m);
+          if (nameMatch) name = nameMatch[1].trim();
+          const descMatch = fm.match(/^description:\s*(.+)$/m);
+          if (descMatch) description = descMatch[1].trim();
+        }
+        if (topic !== 'all') {
+          const topicLower = topic.toLowerCase();
+          if (!name.toLowerCase().includes(topicLower) && !description.toLowerCase().includes(topicLower)) continue;
+        }
+        const descLower = description.toLowerCase();
+        const nameLower = name.toLowerCase();
+        const contentLower = content.toLowerCase();
+        const relevance = tokens.reduce((score, token) => {
+          return score + (descLower.includes(token) ? 3 : 0) + (nameLower.includes(token) ? 2 : 0) + (contentLower.includes(token) ? 1 : 0);
+        }, 0);
+        if (relevance > 0) {
+          results.push({
+            source: "skills/" + dir + "/SKILL.md",
+            name,
+            snippet: description.substring(0, 200),
+            relevance,
+          });
+        }
+      }
+    }
+  } catch (err) {
+    return { ok: false, error: err.message, results: [] };
+  }
+  results.sort((a, b) => b.relevance - a.relevance);
+  return { ok: true, query: q, topic, count: results.length, results: results.slice(0, 10) };
+}
+
+async function retrieveSkill(name) {
+  const skillName = String(name || '').trim();
+  if (!skillName) return { ok: false, error: 'Skill name is required.' };
+  const skillPath = join(SKILLS_ROOT, skillName, 'SKILL.md');
+  if (!existsSync(skillPath)) {
+    const dirs = existsSync(SKILLS_ROOT)
+      ? readdirSync(SKILLS_ROOT, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)
+      : [];
+    return { ok: false, error: 'Skill "' + skillName + '" not found. Available: ' + dirs.join(', ') };
+  }
+  const content = readFileSync(skillPath, 'utf8');
+  const references = [];
+  const refDir = join(SKILLS_ROOT, skillName, 'references');
+  if (existsSync(refDir)) {
+    readdirSync(refDir).forEach((f) => {
+      const refPath = join(refDir, f);
+      references.push({ filename: f, content: readFileSync(refPath, 'utf8').substring(0, 4000) });
+    });
+  }
+  const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  let version = 1, description = '';
+  if (frontmatter) {
+    const fm = frontmatter[1];
+    const vm = fm.match(/^version:\s*(.+)$/m);
+    if (vm) version = vm[1].trim();
+    const dm = fm.match(/^description:\s*(.+)$/m);
+    if (dm) description = dm[1].trim();
+  }
+  return { ok: true, name: skillName, version, description, content, references };
+}
+
+async function listRegions() {
+  const result = await runHcloud(['IAM', 'KeystoneListRegions'], { timeoutMs: 30000, maxRetries: 0 })
+    .catch((err) => ({ ok: false, error: err.message }));
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: result.error || 'Failed to list regions.',
+      fallback: 'Check https://developer.huaweicloud.com/endpoint for available regions.',
+      staticRegions: [
+        { id: 'cn-north-1', description: '华北-北京一' },
+        { id: 'cn-north-4', description: '华北-北京四' },
+        { id: 'cn-east-3', description: '华东-上海一' },
+        { id: 'cn-east-2', description: '华东-上海二' },
+        { id: 'cn-south-1', description: '华南-广州' },
+        { id: 'ap-southeast-1', description: '香港' },
+        { id: 'ap-southeast-3', description: '新加坡' },
+        { id: 'ap-southeast-2', description: '曼谷' },
+        { id: 'af-south-1', description: '约翰内斯堡' },
+      ],
+      note: 'hcloud unavailable. Showing static region list. For the complete list, visit the fallback URL.',
+    };
+  }
+  let regions = [];
+  try {
+    const parsed = typeof result.stdout === 'string' ? JSON.parse(result.stdout) : result.stdout;
+    const rawRegions = parsed.regions || [];
+    regions = rawRegions.map((r) => ({
+      id: r.id,
+      description: r.description || r.names,
+      type: r.type,
+      locales: r.locales,
+    }));
+  } catch {
+    regions = [{ raw: String(result.stdout).substring(0, 1000) }];
+  }
+  regions.sort((a, b) => String(a.id || '').localeCompare(String(b.id || '')));
+  return { ok: true, count: regions.length, regions };
+}
+
+async function getRegionalAvailability(service, region) {
+  const svc = String(service || '').toLowerCase().trim();
+  const reg = String(region || '').toLowerCase().trim();
+  if (!svc || !reg) return { ok: false, error: 'Both service and region are required.' };
+  const known = {
+    ecs: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','ap-southeast-4','af-south-1','tr-west-1','sa-brazil-1','la-north-2','na-mexico-1','me-east-1'],
+    obs: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','af-south-1'],
+    vpc: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1','ap-southeast-4','af-south-1','tr-west-1','sa-brazil-1','la-north-2','me-east-1'],
+    iam: ['global'],
+    rds: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
+    gaussdb: ['cn-south-1','cn-north-4','cn-east-3'],
+    cce: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
+    modelarts: ['cn-south-1','cn-north-4','cn-east-3'],
+    functiongraph: ['cn-south-1','cn-north-4','cn-north-1','cn-east-3','cn-east-2','ap-southeast-3','ap-southeast-2','ap-southeast-1'],
+    dew: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    smn: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    ces: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    cts: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    apig: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    cbr: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    dds: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+    dcs: ['cn-south-1','cn-north-4','cn-east-3','ap-southeast-3'],
+  };
+  if (!known[svc]) return { ok: false, service: svc, region: reg, available: false, note: 'Service ' + svc + ' is not in the regional availability cache. Run hcloud ' + svc.toUpperCase() + ' --help to verify, or check https://developer.huaweicloud.com/endpoint.' };
+  const available = known[svc].includes(reg) || known[svc].includes('global');
+  return {
+    ok: true, service: svc, region: reg, available,
+    note: available
+      ? svc + ' is available in ' + reg + '.'
+      : svc + ' availability in ' + reg + ' could not be confirmed. Verify at https://developer.huaweicloud.com/endpoint.',
+    sourcedFrom: 'static cache, update via npm package upgrade',
+    disclaimer: 'This result reflects service-level availability only. It does NOT guarantee that your IAM user has permissions in this region. Account-level restrictions (e.g., APIGW.0802) may block actual API calls even when the service is available.',
+  };
+}
+
+export function classifyRawCommand(command) {
+  return classifyTextCommand(command);
+}