@harmonyos-arkts/opencode-plugin 0.0.11 → 0.0.12

package/dist/index.js

@@ -45333,37 +45333,6 @@ function convert_search_result(searchResults, prefix) {
   });
 }
 
-// src/tools/skill-search/skill-search-tool.ts
-function skillSearchTool(managers) {
-  return tool({
-    description: "Search for relevant documents within the harmonyos-atomic-dev skill directory by keywords. Returns the top K most relevant document snippets from the skill directory, ranked by keyword match frequency. Use this tool instead of Glob/Grep when you need to find specific knowledge or documentation within harmonyos-atomic-dev skill. The results include experience_file_path (path to the matching experience document best practices) and ets_file_path (path to the ETS code examples and SDK API file). IMPORTANT: Each scenario only supports ONE tool call. Do NOT call this tool multiple times.",
-    args: {
-      skill_path: tool.schema.string("Absolute path to the harmonyos-atomic-dev skill directory. IMPORTANT: this path should not contain any prefix or suffix like 'file://' or 'SKILL.md'."),
-      query: tool.schema.string("A decomposed requirement or intent describing what you want to find, broken down into searchable keywords separated by spaces. QUERY TIPS: For best results, decompose your intent into short space-separated keywords instead of long sentences. Include: 1) Kit or component name (e.g. ScanKit, AdsKit, ShareKit), 2) specific API or method names (e.g. scanBarcode, loadAd, ShareController), 3) feature keywords (e.g. \u626B\u7801, \u5E7F\u544A\u52A0\u8F7D, \u5206\u4EAB). Example: 'ScanKit \u626B\u7801 scanBarcode startScanForResult' instead of '\u5E2E\u6211\u5B9E\u73B0\u4E00\u4E2A\u626B\u7801\u529F\u80FD'. "),
-      topK: tool.schema.number("Maximum number of top-ranked documents to return. Actual results may be fewer depending on query relevance.").min(1).max(3).default(3)
-    },
-    execute: async (args, context) => {
-      try {
-        const results = await searchSkill(args.skill_path, args.query, args.topK);
-        if (results.length === 0) {
-          return "No relative items found in the skill directory.";
-        }
-        const sdkInfo = results.map((r) => {
-          const parts = [];
-          if (r.experience_file_path) parts.push(`experience path ${r.experience_file_path}`);
-          if (r.ets_file_path) parts.push(`sample code path ${r.ets_file_path}`);
-          if (r.sdk_file_path) parts.push(`sdk info path ${r.sdk_file_path}`);
-          return parts.join("\n");
-        }).join("\n\n");
-        return `You can read the following files as needed to obtain information. 
- ${sdkInfo}`;
-      } catch (e) {
-        return `Error: ${e instanceof Error ? e.message : String(e)}`;
-      }
-    }
-  });
-}
-
 // src/tools/harmony-doc/api-client.ts
 var BASE_URL = "https://svc-drcn.developer.huawei.com/community/servlet";
 var HEADERS = {
@@ -45371,46 +45340,28 @@ var HEADERS = {
   Referer: "https://developer.huawei.com/consumer/cn/doc/",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
 };
-var MAX_RETRIES = 2;
-var RETRY_DELAY_MS = 1e3;
-async function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+var REQUEST_TIMEOUT_MS = 1e4;
 async function post(path7, body) {
-  let lastError;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    try {
-      const res = await fetch(BASE_URL + path7, {
-        method: "POST",
-        headers: HEADERS,
-        body: JSON.stringify(body)
-      });
-      if (!res.ok) {
-        const retriable = res.status === 429 || res.status >= 500;
-        if (retriable && attempt < MAX_RETRIES) {
-          lastError = new Error(`API request failed: ${res.status} ${res.statusText} for ${path7}`);
-          await sleep(RETRY_DELAY_MS * (attempt + 1));
-          continue;
-        }
-        throw new Error(`API request failed: ${res.status} ${res.statusText} for ${path7}`);
-      }
-      const data = await res.json();
-      if (data.code && data.code !== 0 && data.code !== "0") {
-        throw new Error(`API error [${data.code}]: ${data.message} for ${path7}`);
-      }
-      return data;
-    } catch (e) {
-      if (e instanceof TypeError && e.message.includes("fetch")) {
-        lastError = e;
-        if (attempt < MAX_RETRIES) {
-          await sleep(RETRY_DELAY_MS * (attempt + 1));
-          continue;
-        }
-      }
-      throw e;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(BASE_URL + path7, {
+      method: "POST",
+      headers: HEADERS,
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      throw new Error(`API request failed: ${res.status} ${res.statusText} for ${path7}`);
+    }
+    const data = await res.json();
+    if (data.code && data.code !== 0 && data.code !== "0") {
+      throw new Error(`API error [${data.code}]: ${data.message} for ${path7}`);
     }
+    return data;
+  } finally {
+    clearTimeout(timer);
   }
-  throw lastError ?? new Error("Request failed after retries");
 }
 var CATALOG_DISPLAY_NAMES = {
   "harmonyos-guides": "\u6307\u5357",
@@ -45475,6 +45426,7 @@ async function searchDocs(keyword, maxResults = 10) {
       title: r.name ?? "",
       url: r.url ?? "",
       excerpt: (r.content ?? "").replace(/\n/g, " ").substring(0, 200),
+      excerptTruncated: (r.content ?? "").replace(/\n/g, " ").length > 200,
       breadcrumb,
       contentType: r.metaData?.type ?? 0,
       timestamp: r.metaData?.timestamp ?? "",
@@ -45583,6 +45535,84 @@ function formatUpdateTime(utcTimeStr) {
   return `${y}-${m}-${d} ${h}:${min}`;
 }
 
+// src/tools/skill-search/skill-search-tool.ts
+function skillSearchTool(managers) {
+  return tool({
+    description: "Search HarmonyOS development knowledge across BOTH local skill documents AND official Huawei documentation. Returns two sections: (1) Local Skill Results \u2014 file paths to curated code examples, best practices, and SDK API info from the harmonyos-atomic-dev skill directory; (2) Official Documentation \u2014 search results from developer.huawei.com with titles, URLs, breadcrumbs, and excerpts. Use this tool for any HarmonyOS API, component, Kit, or development pattern lookup. After reviewing results, read local skill files for code patterns and use harmony-doc-view to read full official documents by URL. IMPORTANT: This tool already searches official documentation \u2014 do NOT also call harmony-doc-view for the same purpose. Only use harmony-doc-view to read a specific document page from the URLs listed below. Each scenario only supports ONE tool call. Do NOT call this tool multiple times.",
+    args: {
+      skill_path: tool.schema.string("Absolute path to the harmonyos-atomic-dev skill directory. IMPORTANT: this path should not contain any prefix or suffix like 'file://' or 'SKILL.md'."),
+      query: tool.schema.string("A decomposed requirement or intent describing what you want to find, broken down into searchable keywords separated by spaces. QUERY TIPS: For best results, decompose your intent into short space-separated keywords instead of long sentences. Include: 1) Kit or component name (e.g. ScanKit, AdsKit, ShareKit), 2) specific API or method names (e.g. scanBarcode, loadAd, ShareController), 3) feature keywords (e.g. \u626B\u7801, \u5E7F\u544A\u52A0\u8F7D, \u5206\u4EAB). Example: 'ScanKit \u626B\u7801 scanBarcode startScanForResult' instead of '\u5E2E\u6211\u5B9E\u73B0\u4E00\u4E2A\u626B\u7801\u529F\u80FD'. "),
+      topK: tool.schema.number("Maximum number of top-ranked documents to return. Actual results may be fewer depending on query relevance.").min(1).max(3).default(3)
+    },
+    execute: async (args, context) => {
+      const [localResults, docResults] = await Promise.all([
+        searchSkill(args.skill_path, args.query, args.topK).catch(
+          (e) => new Error(`Local search failed: ${e instanceof Error ? e.message : String(e)}`)
+        ),
+        searchDocs(args.query, 5).catch(
+          (e) => new Error(`Doc search failed: ${e instanceof Error ? e.message : String(e)}`)
+        )
+      ]);
+      const parts = [];
+      if (localResults instanceof Error) {
+        parts.push(`## Local Skill Results
+
+${localResults.message}`);
+      } else if (localResults.length === 0) {
+        parts.push("## Local Skill Results\n\nNo matching skill documents found.");
+      } else {
+        const localInfo = localResults.map((r) => {
+          const lines = [];
+          if (r.experience_file_path) lines.push(`- experience path: ${r.experience_file_path}`);
+          if (r.ets_file_path) lines.push(`- sample code path: ${r.ets_file_path}`);
+          if (r.sdk_file_path) lines.push(`- sdk info path: ${r.sdk_file_path}`);
+          return lines.join("\n");
+        }).join("\n\n");
+        parts.push(`## Local Skill Results
+
+${localInfo}`);
+      }
+      if (docResults instanceof Error) {
+        parts.push(`## Official Documentation
+
+${docResults.message}`);
+      } else if (docResults.length === 0) {
+        parts.push("## Official Documentation\n\nNo matching official documents found.");
+      } else {
+        const docInfo = docResults.map((r, i) => {
+          const lines = [];
+          let title = r.title;
+          if (r.subsection && r.subsection !== r.title) {
+            title += ` #${r.subsection}`;
+          }
+          lines.push(`${i + 1}. **${title}**`);
+          let displayUrl = r.url;
+          if (r.anchorId) {
+            displayUrl += `#${r.anchorId}`;
+          }
+          lines.push(`   URL: ${displayUrl}`);
+          if (r.excerpt) {
+            const suffix = r.excerptTruncated ? "..." : "";
+            lines.push(`   ${r.excerpt}${suffix}`);
+          }
+          if (r.breadcrumb.length > 0) {
+            lines.push(`   \u6765\u81EA: ${r.breadcrumb.join(" > ")}`);
+          }
+          return lines.join("\n");
+        }).join("\n\n");
+        parts.push(
+          `## Official Documentation
+
+${docInfo}
+
+Use harmony-doc-view with a URL above to read any official document in full.`
+        );
+      }
+      return parts.join("\n\n");
+    }
+  });
+}
+
 // node_modules/turndown/lib/turndown.es.js
 function extend3(destination) {
   for (var i = 1; i < arguments.length; i++) {
@@ -46648,69 +46678,21 @@ function getCached(objectId) {
 function setCache(objectId, doc, markdown, breadcrumb) {
   docCache.set(objectId, { doc, markdown, breadcrumb, fetchedAt: Date.now() });
 }
-function harmonyDocTool(_managers) {
+function harmonyDocViewTool(_managers) {
   return tool({
-    description: "HarmonyOS developer documentation tool with two actions: 'search' and 'view'. Use 'search' to find documents by keyword; use 'view' to read a specific document by URL. Typical workflow: search first, then view the relevant result. NOTE: This tool makes network requests and may take longer to respond. Prefer using skillSearch first for component usage, Kit capabilities, and common development patterns \u2014 only fall back to this tool when skillSearch does not cover the topic.",
+    description: "View a HarmonyOS official documentation page by URL with full Markdown content and pagination. Use this tool to read official API references, guides, and best practices from developer.huawei.com. Typically used with URLs obtained from skillSearch's Official Documentation results. Supports pagination for long documents \u2014 use the 'page' parameter to continue reading.",
     args: {
-      action: tool.schema.enum(["search", "view"]).describe("Action to perform: 'search' to find documents by keyword, 'view' to read a document by URL."),
-      query: tool.schema.string("Search keyword or phrase (for action='search'). Use specific terms, e.g. 'Button component', 'router navigation'.").optional(),
-      maxResults: tool.schema.number("Maximum search results to return (for action='search').").min(1).max(20).default(10),
-      url: tool.schema.string("Full URL of the document to view (for action='view'). Must be a developer.huawei.com URL from search results.").optional(),
-      page: tool.schema.number("Page number for long documents (for action='view'). Starts at 1.").min(1).default(1)
+      url: tool.schema.string("Full URL of the document to view. Must be a developer.huawei.com URL, typically from skillSearch results."),
+      page: tool.schema.number("Page number for long documents. Starts at 1.").min(1).default(1)
     },
     execute: async (args, _context) => {
-      if (args.action === "search") {
-        return executeSearch(args.query, args.maxResults);
-      }
       return executeView(args.url, args.page);
     }
   });
 }
-async function executeSearch(query, maxResults) {
-  if (!query) {
-    return "Error: 'query' is required when action is 'search'.";
-  }
-  try {
-    log("[harmony-doc search]", { query, maxResults });
-    const results = await searchDocs(query, maxResults ?? 10);
-    if (results.length === 0) {
-      return `No results found for "${query}". Try different keywords.`;
-    }
-    const formatted = results.map((r, i) => {
-      const parts = [];
-      let title = r.title;
-      if (r.subsection && r.subsection !== r.title) {
-        title += ` #${r.subsection}`;
-      }
-      parts.push(`${i + 1}. **${title}**`);
-      if (r.breadcrumb.length > 0) {
-        parts.push(`   Path: ${r.breadcrumb.join(" > ")}`);
-      }
-      let displayUrl = r.url;
-      if (r.anchorId) {
-        displayUrl += `#${r.anchorId}`;
-      }
-      parts.push(`   URL: ${displayUrl}`);
-      if (r.excerpt) {
-        parts.push(`   ${r.excerpt}`);
-      }
-      return parts.join("\n");
-    }).join("\n\n");
-    return `Found ${results.length} results for "${query}":
-
-${formatted}
-
-Use action='view' with the URL to read the full document.`;
-  } catch (e) {
-    return `Error: ${e instanceof Error ? e.message : String(e)}`;
-  }
-}
 async function executeView(url3, page) {
-  if (!url3) {
-    return "Error: 'url' is required when action is 'view'.";
-  }
   try {
-    log("[harmony-doc view]", { url: url3, page });
+    log("[harmony-doc-view]", { url: url3, page });
     const objectId = objectIdFromUrl(url3);
     if (!objectId) {
       return `Error: Cannot extract document ID from URL: ${url3}`;
@@ -46723,22 +46705,22 @@ async function executeView(url3, page) {
       doc = cached3.doc;
       markdown = cached3.markdown;
       breadcrumb = cached3.breadcrumb;
-      log("[harmony-doc view] cache hit", { objectId, page });
+      log("[harmony-doc-view] cache hit", { objectId, page });
     } else {
       doc = await fetchDocument(objectId);
       if (!doc.html) {
-        log("[harmony-doc view] API returned empty HTML", { objectId, title: doc.title });
+        log("[harmony-doc-view] API returned empty HTML", { objectId, title: doc.title });
         return `Error: Document content is empty for ${url3} (objectId: ${objectId}). The API returned no HTML content \u2014 the document may not be available through this API.`;
       }
       markdown = htmlToMarkdown(doc.html);
-      log("[harmony-doc view] conversion result", {
+      log("[harmony-doc-view] conversion result", {
         objectId,
         htmlLength: doc.html.length,
         markdownLength: markdown.length,
         markdownPreview: markdown.substring(0, 300)
       });
       if (!markdown.trim()) {
-        log("[harmony-doc view] markdown conversion produced empty output", {
+        log("[harmony-doc-view] markdown conversion produced empty output", {
           objectId,
           htmlLength: doc.html.length
         });
@@ -46749,11 +46731,11 @@ async function executeView(url3, page) {
         try {
           breadcrumb = await resolveBreadcrumb("cn", doc.catalogName, objectId);
         } catch (e) {
-          log("[harmony-doc view] breadcrumb resolution failed", { objectId, error: String(e) });
+          log("[harmony-doc-view] breadcrumb resolution failed", { objectId, error: String(e) });
         }
       }
       setCache(objectId, doc, markdown, breadcrumb);
-      log("[harmony-doc view] cache miss, fetched from network", { objectId });
+      log("[harmony-doc-view] cache miss, fetched from network", { objectId });
     }
     const MAX_LENGTH = 3e4;
     const totalPages = Math.max(1, Math.ceil(markdown.length / MAX_LENGTH));
@@ -46784,9 +46766,9 @@ Source: ${url3}
       output += `
 
 ---
-[Document continues \u2014 call with action='view' and page=${currentPage + 1} to read more]`;
+[Document continues \u2014 call with page=${currentPage + 1} to read more]`;
     }
-    log("[harmony-doc view] RETURN", {
+    log("[harmony-doc-view] RETURN", {
       objectId,
       outputLength: output.length,
       chunkLength: chunk.length,
@@ -46804,7 +46786,7 @@ function createBuiltinTools(managers) {
   return {
     createHmTemplate: createHmTemplateTool(managers),
     skillSearch: skillSearchTool(managers),
-    "harmony-doc": harmonyDocTool(managers)
+    "harmony-doc-view": harmonyDocViewTool(managers)
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@harmonyos-arkts/opencode-plugin",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "HarmonyOS Full-Lifecycle Development Assistant. Specialized in the complete development lifecycle of HarmonyOS applications, including project creation, UI development, state management, network requests, data storage, permission requests, performance optimization, testing, and release.",
   "type": "module",
   "license": "MIT",