@harmonyos-arkts/opencode-plugin 0.0.19 → 0.0.20-beta

package/README.md

@@ -8,7 +8,7 @@
 - **HarmonyOS设计专家**：为HarmonyOS应用和原子化服务创建详细的PRD设计文档
 - **HarmonyOS开发专家**：根据设计文档遵循HarmonyOS规范实现功能
 - **HarmonyOS构建**：使用harmonyos-hvigor技能构建项目并确保编译成功
-- **HarmonyOS文档查询**：通过 `harmony-doc` 工具搜索和查看华为开发者文档（含官方文档与社区内容），支持关键词搜索和分页查看全文
+- **HarmonyOS文档查询**：通过 `harmony-doc-search` 搜索华为官方开发者文档（关键词越精简越准确），通过 `harmony-doc-view` 查看文档全文（支持分页）
 
 ## 快速开始
 

package/dist/index.js

@@ -31913,6 +31913,8 @@ function createHmAgent() {
       doom_loop: "ask",
       "skillSearch": "allow",
       ascf_build: "deny",
+      "harmony-doc-search": "allow",
+      "harmony-doc-view": "allow",
       skill: {
         "*": "deny",
         "harmonyos-atomic-dev": "allow",
@@ -31944,7 +31946,9 @@ function createDesignAgent() {
         "*": "deny",
         "harmonyos-prd-design": "allow"
       },
-      "skillSearch": "deny"
+      "skillSearch": "deny",
+      "harmony-doc-search": "deny",
+      "harmony-doc-view": "deny"
     },
     metadata: void 0
   };
@@ -31967,6 +31971,8 @@ function createHmDevelopmentAgent() {
     temperature: 0.3,
     permission: {
       "skillSearch": "allow",
+      "harmony-doc-search": "allow",
+      "harmony-doc-view": "allow",
       skill: {
         "*": "deny",
         "harmonyos-atomic-dev": "allow",
@@ -44871,8 +44877,10 @@ function createHmTemplateTool(managers) {
   return tool({
     description: "Create an empty HarmonyOS project template. Supports three modes: 'application' (full app), 'module' (sub-module), 'atomic' (atomic service). Defaults to the current working directory unless the user specifies a different directory.",
     args: {
-      filePath: tool.schema.string().describe("Absolute path of the target directory where the template will be created. Defaults to the current working directory if not specified."),
-      mode: tool.schema.string().describe("Template type: 'application' (\u5E94\u7528), 'module' (\u6A21\u5757), or 'atomic' (\u5143\u670D\u52A1)")
+      filePath: tool.schema.string().describe(
+        "Absolute path of the target directory where the template will be created. Defaults to the current working directory if not specified."
+      ),
+      mode: tool.schema.string().describe("Template type: 'application' (\u5E94\u7528), 'module' (\u6A21\u5757), or 'atomic' (\u5143\u670D\u52A1).")
     },
     execute: async (args, context) => {
       try {
@@ -45376,6 +45384,117 @@ 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. Results include experience_file_path (best practices), ets_file_path (code examples), and sdk_file_path (SDK API info). QUERY TIPS: Decompose your intent into short space-separated keywords for best results. 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'.",
+    args: {
+      skill_path: tool.schema.string().describe(
+        "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().describe(
+        "A decomposed requirement or intent describing what you want to find, broken down into searchable keywords separated by spaces."
+      ),
+      topK: tool.schema.number().describe("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 info = results.map((r) => {
+          const lines = [];
+          lines.push(`score ${r.score.toFixed(4)}`);
+          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");
+        return `## Results
+
+${info}`;
+      } catch (e) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    }
+  });
+}
+
+// src/tools/html-preview/html-preview-tool.ts
+import { access } from "fs/promises";
+import path7 from "path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
+var PROTOTYPE_HTML_FILENAME = "prototype.html";
+function toFileUrl(filePath) {
+  return pathToFileURL(path7.resolve(filePath)).href;
+}
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolvePrototypePath(directory, input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("filePath is required");
+  }
+  if (trimmed.startsWith("file://")) {
+    return fileURLToPath2(trimmed);
+  }
+  return path7.isAbsolute(trimmed) ? trimmed : path7.resolve(directory, trimmed);
+}
+async function resolvePrototypePreview(directory, filePathInput) {
+  const filePath = resolvePrototypePath(directory, filePathInput);
+  if (!await fileExists(filePath)) {
+    throw new Error(
+      `Prototype HTML not found: ${filePath}. Pass the exact local path where ${PROTOTYPE_HTML_FILENAME} was written.`
+    );
+  }
+  return { url: toFileUrl(filePath), filePath };
+}
+function htmlPreviewTool(_managers) {
+  return tool({
+    description: "Send the UX prototype preview to the frontend. Call this immediately after writing prototype.html. You MUST pass filePath with the exact local path of the written file so the frontend can locate and preview it.",
+    args: {
+      filePath: tool.schema.string().describe(
+        "Local path to prototype.html. Use the same path from the write step, e.g. prototype.html, /Users/yanqing/coding/your-project/prototype.html, or file:///.../prototype.html."
+      ),
+      title: tool.schema.optional(tool.schema.string().describe("Title shown in the preview panel."))
+    },
+    execute: async (args, context) => {
+      try {
+        log("[html_preview]", { filePath: args.filePath, title: args.title });
+        const { url: url3, filePath } = await resolvePrototypePreview(context.directory, args.filePath);
+        const title = args.title?.trim() || "Prototype Preview";
+        const metadata = {
+          url: url3,
+          filePath,
+          fileName: path7.basename(filePath),
+          title
+        };
+        context.metadata({
+          title,
+          metadata: {
+            htmlPreview: metadata
+          }
+        });
+        return [
+          "Prototype preview sent to frontend.",
+          `Title: ${title}`,
+          `Local path: ${filePath}`,
+          `Preview URL: ${url3}`
+        ].join("\n");
+      } 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 = {
@@ -45578,159 +45697,6 @@ 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().describe("The COMPLETE absolute filesystem path to the harmonyos-atomic-dev skill directory (e.g. '/home/user/.opencode/skills/harmonyos-atomic-dev'). Do NOT pass just the skill name 'harmonyos-atomic-dev' \u2014 you MUST resolve and provide the full absolute path. Do NOT include any prefix like 'file://' or suffix like 'SKILL.md' or 'index.json'."),
-      query: tool.schema.string().describe("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().describe("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 = [];
-          lines.push(`score ${r.score.toFixed(4)}`);
-          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");
-    }
-  });
-}
-
-// src/tools/html-preview/html-preview-tool.ts
-import { access } from "fs/promises";
-import path7 from "path";
-import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
-var PROTOTYPE_HTML_FILENAME = "prototype.html";
-function toFileUrl(filePath) {
-  return pathToFileURL(path7.resolve(filePath)).href;
-}
-async function fileExists(filePath) {
-  try {
-    await access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function resolvePrototypePath(directory, input) {
-  const trimmed = input.trim();
-  if (!trimmed) {
-    throw new Error("filePath is required");
-  }
-  if (trimmed.startsWith("file://")) {
-    return fileURLToPath2(trimmed);
-  }
-  return path7.isAbsolute(trimmed) ? trimmed : path7.resolve(directory, trimmed);
-}
-async function resolvePrototypePreview(directory, filePathInput) {
-  const filePath = resolvePrototypePath(directory, filePathInput);
-  if (!await fileExists(filePath)) {
-    throw new Error(
-      `Prototype HTML not found: ${filePath}. Pass the exact local path where ${PROTOTYPE_HTML_FILENAME} was written.`
-    );
-  }
-  return { url: toFileUrl(filePath), filePath };
-}
-function htmlPreviewTool(_managers) {
-  return tool({
-    description: "Send the UX prototype preview to the frontend. Call this immediately after writing prototype.html. You MUST pass filePath with the exact local path of the written file so the frontend can locate and preview it.",
-    args: {
-      filePath: tool.schema.string().describe("Local path to prototype.html. Use the same path from the write step, e.g. prototype.html, /Users/yanqing/coding/your-project/prototype.html, or file:///.../prototype.html."),
-      title: tool.schema.optional(
-        tool.schema.string().describe("Optional title shown in the preview panel")
-      )
-    },
-    execute: async (args, context) => {
-      try {
-        log("[html_preview]", { filePath: args.filePath, title: args.title });
-        const { url: url3, filePath } = await resolvePrototypePreview(context.directory, args.filePath);
-        const title = args.title?.trim() || "Prototype Preview";
-        const metadata = {
-          url: url3,
-          filePath,
-          fileName: path7.basename(filePath),
-          title
-        };
-        context.metadata({
-          title,
-          metadata: {
-            htmlPreview: metadata
-          }
-        });
-        return [
-          "Prototype preview sent to frontend.",
-          `Title: ${title}`,
-          `Local path: ${filePath}`,
-          `Preview URL: ${url3}`
-        ].join("\n");
-      } catch (e) {
-        return `Error: ${e instanceof Error ? e.message : String(e)}`;
-      }
-    }
-  });
-}
-
 // node_modules/turndown/lib/turndown.es.js
 function extend3(destination) {
   for (var i = 1; i < arguments.length; i++) {
@@ -46781,7 +46747,7 @@ function cleanupMarkdown(md) {
   return out.trim();
 }
 
-// src/tools/harmony-doc/harmony-doc-tool.ts
+// src/tools/harmony-doc/harmony-doc-view-tool.ts
 var docCache = /* @__PURE__ */ new Map();
 var CACHE_TTL = 10 * 60 * 1e3;
 function getCached(objectId) {
@@ -46798,9 +46764,9 @@ function setCache(objectId, doc, markdown, breadcrumb) {
 }
 function harmonyDocViewTool(_managers) {
   return tool({
-    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.",
+    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 harmony-doc-search results. Supports pagination for long documents \u2014 use the 'page' parameter to continue reading.",
     args: {
-      url: tool.schema.string().describe("Full URL of the document to view. Must be a developer.huawei.com URL, typically from skillSearch results."),
+      url: tool.schema.string().describe("Full URL of the document to view. Must be a developer.huawei.com URL."),
       page: tool.schema.number().describe("Page number for long documents. Starts at 1.").min(1).default(1)
     },
     execute: async (args, _context) => {
@@ -46899,13 +46865,67 @@ Source: ${url3}
   }
 }
 
+// src/tools/harmony-doc/harmony-doc-search-tool.ts
+var DEFAULT_SEARCH_COUNT = 5;
+function harmonyDocSearchTool(_managers) {
+  return tool({
+    description: "Search official HarmonyOS documentation from developer.huawei.com. This tool requires network access and takes several seconds to respond. Covers any HarmonyOS-related knowledge: API references, Kit capabilities, ArkUI components, ArkTS syntax, development guides, best practices, error codes, migration guides, sample code references. IMPORTANT: Use concise keywords for best results \u2014 fewer words = more precise matches. Example: 'ScanKit scanBarcode' instead of 'how to implement barcode scanning with ScanKit'. After reviewing results, use harmony-doc-view to read any document in full by URL.",
+    args: {
+      keyword: tool.schema.string().describe(
+        "Concise search keyword for official HarmonyOS documentation. Keep it short and specific \u2014 prefer 1-3 keywords over long sentences. Supports any HarmonyOS-related query: Kit/Component names (ScanKit, AdsKit, List, Column), API names (scanBarcode, ShareController, @State, @Prop), ArkTS syntax (@Entry, @Builder, @Extend), feature keywords (\u626B\u7801, \u5E7F\u544A, \u5206\u4EAB, \u52A8\u753B, \u7F51\u7EDC\u8BF7\u6C42), error codes, migration topics, or any development concept."
+      )
+    },
+    execute: async (args, _context) => {
+      const docResults = await searchDocs(
+        args.keyword,
+        DEFAULT_SEARCH_COUNT
+      ).catch(
+        (e) => new Error(
+          `Doc search failed: ${e instanceof Error ? e.message : String(e)}`
+        )
+      );
+      if (docResults instanceof Error) {
+        return docResults.message;
+      }
+      if (docResults.length === 0) {
+        return `No matching official documents found for "${args.keyword}".`;
+      }
+      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");
+      return `${docInfo}
+
+Use harmony-doc-view with a URL above to read any official document in full.`;
+    }
+  });
+}
+
 // src/tools/builtin.ts
 function createBuiltinTools(managers) {
   return {
     createHmTemplate: createHmTemplateTool(managers),
     skillSearch: skillSearchTool(managers),
     html_preview: htmlPreviewTool(managers),
-    "harmony-doc-view": harmonyDocViewTool(managers)
+    "harmony-doc-view": harmonyDocViewTool(managers),
+    "harmony-doc-search": harmonyDocSearchTool(managers)
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@harmonyos-arkts/opencode-plugin",
-  "version": "0.0.19",
+  "version": "0.0.20-beta",
   "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",
@@ -30,7 +30,7 @@
     "ArkTs"
   ],
   "dependencies": {
-    "@opencode-ai/sdk": "latest",
+    "@opencode-ai/sdk": "1.15.1",
     "diff": "7.0.0",
     "env-paths": "4.0.0",
     "jsonc-parser": "3.3.1",