@harmonyos-arkts/opencode-plugin 0.0.10 → 0.0.11

package/README.md

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

package/dist/index.js

@@ -45368,23 +45368,63 @@ function skillSearchTool(managers) {
 var BASE_URL = "https://svc-drcn.developer.huawei.com/community/servlet";
 var HEADERS = {
   "Content-Type": "application/json",
-  "Referer": "https://developer.huawei.com/consumer/cn/doc/",
+  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));
+}
 async function post(path7, body) {
-  const res = await fetch(BASE_URL + path7, {
-    method: "POST",
-    headers: HEADERS,
-    body: JSON.stringify(body)
-  });
-  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}`);
+  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;
+    }
   }
-  return data;
+  throw lastError ?? new Error("Request failed after retries");
+}
+var CATALOG_DISPLAY_NAMES = {
+  "harmonyos-guides": "\u6307\u5357",
+  "harmonyos-references": "API\u53C2\u8003",
+  "harmonyos-best-practices": "\u6700\u4F73\u5B9E\u8DF5",
+  "harmonyos-faqs": "FAQ",
+  "design-guides": "\u8BBE\u8BA1\u6307\u5357",
+  "atomic-guides": "\u6307\u5357",
+  "atomic-references": "API\u53C2\u8003",
+  "atomic-faqs": "FAQ",
+  "atomic-ascf": "ASCF\u6846\u67B6"
+};
+function catalogDisplayName(catalogName) {
+  return CATALOG_DISPLAY_NAMES[catalogName] || "";
 }
 async function searchDocs(keyword, maxResults = 10) {
   const data = await post(
@@ -45405,12 +45445,29 @@ async function searchDocs(keyword, maxResults = 10) {
     }
   );
   return (data.resultList ?? []).map((r) => {
+    let subsection = "";
+    let anchorId = "";
+    if (r.anchorHighlightInfo) {
+      subsection = r.anchorHighlightInfo.replace(/<\/?em>/g, "");
+    }
     let breadcrumb = [];
     try {
       const ext = typeof r.metaData?.ext === "string" ? JSON.parse(r.metaData.ext) : r.metaData?.ext ?? {};
       const nodeNames = Array.isArray(ext.nodeNames) ? ext.nodeNames : [];
+      const catalogName = typeof ext.catalogName === "string" ? ext.catalogName : "";
       if (nodeNames.length > 0) {
-        breadcrumb = nodeNames;
+        const rootName = catalogDisplayName(catalogName) || catalogName;
+        breadcrumb = rootName ? [rootName, ...nodeNames] : nodeNames;
+      }
+      if (subsection) {
+        try {
+          const anchors = typeof ext.anchorList === "string" ? JSON.parse(ext.anchorList) : ext.anchorList;
+          if (Array.isArray(anchors)) {
+            const match = anchors.find((a) => a.title === subsection);
+            if (match) anchorId = match.anchorId ?? "";
+          }
+        } catch {
+        }
       }
     } catch {
     }
@@ -45420,15 +45477,31 @@ async function searchDocs(keyword, maxResults = 10) {
       excerpt: (r.content ?? "").replace(/\n/g, " ").substring(0, 200),
       breadcrumb,
       contentType: r.metaData?.type ?? 0,
-      timestamp: r.metaData?.timestamp ?? ""
+      timestamp: r.metaData?.timestamp ?? "",
+      subsection,
+      anchorId
     };
   });
 }
 function objectIdFromUrl(url3) {
   try {
-    const pathname = new URL(url3).pathname.replace(/\/$/, "");
+    const parsed = new URL(url3);
+    const pathname = parsed.pathname.replace(/\/$/, "");
+    const queryId = parsed.searchParams.get("objectId") || parsed.searchParams.get("id");
+    if (queryId) return queryId;
     const parts = pathname.split("/");
-    return parts[parts.length - 1] || null;
+    const lastSegment = parts[parts.length - 1];
+    if (lastSegment && lastSegment.length > 2) return lastSegment;
+    if (parts.length >= 2) {
+      const secondLast = parts[parts.length - 2];
+      if (secondLast && secondLast.length > 2) return secondLast;
+    }
+    const hash3 = parsed.hash;
+    if (hash3) {
+      const hashId = hash3.replace(/^#/, "");
+      if (hashId.length > 5) return hashId;
+    }
+    return null;
   } catch {
     return null;
   }
@@ -45442,50 +45515,72 @@ async function fetchDocument(objectId, language = "cn") {
   if (!v) {
     throw new Error(`Empty response for objectId: ${objectId}`);
   }
+  const html = v.content?.content ?? "";
   return {
     title: v.title ?? "",
-    html: v.content?.content ?? "",
+    html,
     objectId,
     catalogName: v.catalogName ?? "",
     displayUpdateTime: v.displayUpdateTime ?? ""
   };
 }
-
-// src/tools/harmony-doc/doc-search-tool.ts
-function docSearchTool(_managers) {
-  return tool({
-    description: "Search HarmonyOS developer documentation by keyword. Results cover official docs, API references, guides, and community content from developer.huawei.com. The breadcrumb path in each result helps identify the source type \u2014 prefer official docs over community posts when accuracy is critical. HarmonyOS APIs evolve rapidly; prefer searching for the latest information. After finding relevant results, use the harmony-doc-view tool with the URL to read the full document.",
-    args: {
-      query: tool.schema.string("Search keyword or phrase. Use specific terms for best results, e.g. 'Button component', 'router navigation', 'NetworkRequest'."),
-      maxResults: tool.schema.number("Maximum number of search results to return.").min(1).max(20).default(10)
-    },
-    execute: async (args, _context) => {
-      try {
-        log("[harmony-doc-search]", { query: args.query, maxResults: args.maxResults });
-        const results = await searchDocs(args.query, args.maxResults);
-        if (results.length === 0) {
-          return `No results found for "${args.query}". Try different keywords.`;
-        }
-        const formatted = results.map((r, i) => {
-          const parts = [];
-          parts.push(`${i + 1}. **${r.title}**`);
-          if (r.breadcrumb.length > 0) {
-            parts.push(`   Path: ${r.breadcrumb.join(" > ")}`);
-          }
-          parts.push(`   URL: ${r.url}`);
-          if (r.excerpt) {
-            parts.push(`   ${r.excerpt}`);
-          }
-          return parts.join("\n");
-        }).join("\n\n");
-        return `Found ${results.length} results for "${args.query}":
-
-${formatted}`;
-      } catch (e) {
-        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+var treeCache = /* @__PURE__ */ new Map();
+async function getCatalogTree(language, catalogName, objectId) {
+  const body = { language, catalogName };
+  if (objectId) body.objectId = objectId;
+  const data = await post(
+    "/consumer/cn/documentPortal/getCatalogTree",
+    body
+  );
+  return data.value?.catalogTreeList ?? [];
+}
+async function resolveBreadcrumb(language, catalogName, relateDocument) {
+  if (!relateDocument) return [];
+  const cacheKey = `${language}:${catalogName}`;
+  if (!treeCache.has(cacheKey)) {
+    const nodes = await getCatalogTree(language, catalogName);
+    const map4 = /* @__PURE__ */ new Map();
+    const walk = (list) => {
+      for (const node of list) {
+        map4.set(node.nodeId, { name: node.nodeName, parent: node.parent, rel: node.relateDocument });
+        if (node.children?.length) walk(node.children);
       }
+    };
+    walk(nodes);
+    treeCache.set(cacheKey, map4);
+  }
+  const map3 = treeCache.get(cacheKey);
+  let target;
+  for (const node of map3.values()) {
+    if (node.rel === relateDocument) {
+      target = node;
+      break;
     }
-  });
+  }
+  if (!target) return [];
+  const breadcrumb = [];
+  let current = target;
+  while (current) {
+    breadcrumb.unshift(current.name);
+    current = current.parent ? map3.get(current.parent) : void 0;
+  }
+  const rootName = catalogDisplayName(catalogName);
+  if (rootName && breadcrumb[0] !== rootName) {
+    breadcrumb.unshift(rootName);
+  }
+  return breadcrumb;
+}
+function formatUpdateTime(utcTimeStr) {
+  if (!utcTimeStr) return "";
+  const dt = /* @__PURE__ */ new Date(utcTimeStr.replace(" ", "T") + "Z");
+  if (isNaN(dt.getTime())) return utcTimeStr;
+  const bj = new Date(dt.getTime() + 8 * 60 * 60 * 1e3);
+  const y = bj.getUTCFullYear();
+  const m = String(bj.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(bj.getUTCDate()).padStart(2, "0");
+  const h = String(bj.getUTCHours()).padStart(2, "0");
+  const min = String(bj.getUTCMinutes()).padStart(2, "0");
+  return `${y}-${m}-${d} ${h}:${min}`;
 }
 
 // node_modules/turndown/lib/turndown.es.js
@@ -46176,18 +46271,61 @@ var removeUIParagraphs = {
     return "";
   }
 };
+var NAV_SHORT_TEXT = /* @__PURE__ */ new Set([
+  "\u7B80\u4F53\u4E2D\u6587",
+  "English",
+  "\u4E0B\u8F7D App",
+  "\u63A2\u7D22",
+  "\u8BBE\u8BA1",
+  "\u5F00\u53D1",
+  "\u5206\u53D1",
+  "\u63A8\u5E7F\u4E0E\u53D8\u73B0",
+  "\u751F\u6001\u5408\u4F5C",
+  "\u652F\u6301",
+  "\u66F4\u591A",
+  "\u7ACB\u5373\u767B\u5F55",
+  "\u8F93\u5165\u5173\u952E\u5B57\u641C\u7D22",
+  "Hello\uFF0C",
+  "\u6B22\u8FCE\u6765\u5230\u5F00\u53D1\u8005\u8054\u76DF",
+  "CTRL+K",
+  "Created with Pixso",
+  "\u7248\u672C\u8BF4\u660E",
+  "\u6307\u5357",
+  "API\u53C2\u8003",
+  "\u6700\u4F73\u5B9E\u8DF5",
+  "FAQ",
+  "\u53D8\u66F4\u9884\u544A",
+  "\u591A\u8BBE\u5907\u573A\u666F",
+  "\u624B\u673A",
+  "\u5E94\u7528\u8D28\u91CF",
+  "\u6280\u672F\u8D28\u91CF",
+  "\u5F00\u53D1\u8005\u80FD\u529B\u8BA4\u8BC1",
+  "\u6211\u7684",
+  "\u7BA1\u7406\u4E2D\u5FC3",
+  "\u4E2A\u4EBA\u4E2D\u5FC3",
+  "\u6211\u7684\u5B66\u5802",
+  "\u6211\u7684\u6536\u85CF",
+  "\u6211\u7684\u6D3B\u52A8",
+  "\u6211\u7684\u5DE5\u5355"
+]);
 var removeNavigation = {
   filter(node) {
     if (node.nodeType !== 1) return false;
+    const text = (node.textContent ?? "").trim();
+    if (text.length <= 20 && NAV_SHORT_TEXT.has(text)) {
+      return true;
+    }
+    if (node.nodeName === "P" && text.length === 0) {
+      const hasContent = node.querySelector("img, code, pre, table");
+      if (!hasContent) return true;
+    }
     const cls = node.className?.toLowerCase() ?? "";
     const id = node.id?.toLowerCase() ?? "";
     const unwantedClasses = [
       "top-bar",
       "menu-bar",
-      "sidebar",
       "search-bar",
       "breadcrumb",
-      "toolbar",
       "footer-nav",
       "main-nav",
       "side-nav",
@@ -46204,7 +46342,29 @@ var removeNavigation = {
       "feedback-section",
       "qrcode-section"
     ];
-    return unwantedClasses.some((c) => cls.includes(c) || id.includes(c));
+    const classList = cls.split(/\s+/);
+    const matchesClass = classList.some(
+      (c) => unwantedClasses.some((u) => c === u || c.startsWith(u + "-") || c.endsWith("-" + u))
+    );
+    const matchesId = unwantedClasses.some(
+      (u) => id === u || id.startsWith(u + "-") || id.endsWith("-" + u)
+    );
+    return matchesClass || matchesId;
+  },
+  replacement() {
+    return "";
+  }
+};
+var removeCodeUI = {
+  filter(node) {
+    if (node.nodeType === 3) {
+      return isUnwantedText(node.textContent ?? "");
+    }
+    if (node.nodeType === 1 && ["P", "DIV", "SPAN"].includes(node.nodeName)) {
+      const text = (node.textContent ?? "").trim();
+      return isUnwantedText(text);
+    }
+    return false;
   },
   replacement() {
     return "";
@@ -46240,6 +46400,18 @@ var huaweiCodeBlock = {
     return "\n```" + language + "\n" + lines.join("\n") + "\n```\n";
   }
 };
+function inferLanguage(codeText) {
+  if (codeText.includes("import ") || codeText.includes("export ") || codeText.includes("interface ")) {
+    return "typescript";
+  }
+  if (codeText.includes("#include") || codeText.includes("int main")) {
+    return "cpp";
+  }
+  if (codeText.includes("public class")) {
+    return "java";
+  }
+  return "";
+}
 var genericPre = {
   filter(node) {
     return node.nodeName === "PRE" && !node.querySelector("ol.linenums");
@@ -46257,6 +46429,9 @@ var genericPre = {
       const codeMatch = (codeElem.className ?? "").match(/language-(\w+)/);
       if (codeMatch) language = codeMatch[1];
     }
+    if (!language && codeText) {
+      language = inferLanguage(codeText);
+    }
     const cleanLines = codeText.split("\n").filter((line) => {
       const trimmed = line.trim();
       return !trimmed || !isUnwantedText(trimmed);
@@ -46264,6 +46439,30 @@ var genericPre = {
     return "\n```" + language + "\n" + cleanLines.join("\n") + "\n```\n";
   }
 };
+var standardCodeBlock = {
+  filter(node) {
+    return node.nodeName === "PRE" && !!node.firstChild && node.firstChild.nodeName === "CODE";
+  },
+  replacement(content, node) {
+    const codeNode = node.firstChild;
+    const lang = codeNode.className || codeNode.getAttribute("class") || "";
+    const langMatch = lang.match(/language-(\w+)|hljs language-(\w+)/);
+    const language = langMatch ? langMatch[1] || langMatch[2] : "";
+    const codeContent = codeNode.textContent || content;
+    const cleanContent = codeContent.split("\n").filter((line) => {
+      const trimmed = line.trim();
+      return !isUnwantedText(trimmed);
+    }).join("\n");
+    return "\n```" + language + "\n" + cleanContent + "\n```\n";
+  }
+};
+function cleanCellText(text) {
+  let cleaned = text.replace(/\s+/g, " ");
+  for (const t of UI_TEXT) {
+    cleaned = cleaned.replaceAll(t, "");
+  }
+  return cleaned.trim();
+}
 var harmonyTable = {
   filter(node) {
     return node.nodeName === "TABLE";
@@ -46282,7 +46481,7 @@ var harmonyTable = {
         }
         const code = cell.querySelector("code");
         if (code) return `\`${code.textContent?.trim() ?? ""}\``;
-        return (cell.textContent ?? "").replace(/\s+/g, " ").trim();
+        return cleanCellText(cell.textContent ?? "");
       });
       if (cells.length === 0) return;
       md += "| " + cells.join(" | ") + " |\n";
@@ -46294,6 +46493,49 @@ var harmonyTable = {
     return md + "\n";
   }
 };
+var divTable = {
+  filter(node) {
+    if (node.nodeType !== 1 || node.nodeName !== "DIV") return false;
+    const cls = (node.className ?? "").toLowerCase();
+    const tableClasses = ["table", "tbl", "data-table", "table-container", "table-wrap"];
+    if (!tableClasses.some((c) => cls.includes(c))) return false;
+    const rowDivs = Array.from(node.children).filter((child) => {
+      const childClass = (child.className ?? "").toLowerCase();
+      return childClass.includes("tr") || childClass.includes("row") || childClass.includes("table-row");
+    });
+    return rowDivs.length > 0;
+  },
+  replacement(content, node) {
+    const rows = Array.from(node.children).filter((child) => {
+      const childClass = (child.className ?? "").toLowerCase();
+      return childClass.includes("tr") || childClass.includes("row") || childClass.includes("table-row");
+    });
+    if (rows.length === 0) return content;
+    let md = "\n";
+    rows.forEach((row, rowIndex) => {
+      const cells = Array.from(row.children).filter((child) => {
+        const childClass = (child.className ?? "").toLowerCase();
+        return childClass.includes("td") || childClass.includes("th") || childClass.includes("cell");
+      }).map((cell) => {
+        const link = cell.querySelector("a");
+        if (link?.getAttribute("href")) {
+          const href = link.getAttribute("href");
+          const full = href.startsWith("http") ? href : `https://developer.huawei.com${href}`;
+          return `[${link.textContent?.trim() ?? ""}](${full})`;
+        }
+        const code = cell.querySelector("code");
+        if (code) return `\`${code.textContent?.trim() ?? ""}\``;
+        return cleanCellText(cell.textContent ?? "");
+      });
+      if (cells.length === 0) return;
+      md += "| " + cells.join(" | ") + " |\n";
+      if (rowIndex === 0) {
+        md += "| " + cells.map(() => "---").join(" | ") + " |\n";
+      }
+    });
+    return md + "\n";
+  }
+};
 var processLinks = {
   filter(node) {
     return node.nodeName === "A" && !!node.getAttribute("href");
@@ -46310,10 +46552,13 @@ function addCustomRules(td) {
     ["removeCodeUIContainers", removeCodeUIContainers],
     ["removeUIParagraphs", removeUIParagraphs],
     ["removeNavigation", removeNavigation],
+    ["removeCodeUI", removeCodeUI],
     ["removePlatformBadge", removePlatformBadge],
     ["huaweiCodeBlock", huaweiCodeBlock],
     ["genericPre", genericPre],
+    ["standardCodeBlock", standardCodeBlock],
     ["harmonyTable", harmonyTable],
+    ["divTable", divTable],
     ["processLinks", processLinks]
   ];
   for (const [name, rule] of rules2) {
@@ -46388,7 +46633,7 @@ function cleanupMarkdown(md) {
   return out.trim();
 }
 
-// src/tools/harmony-doc/doc-view-tool.ts
+// src/tools/harmony-doc/harmony-doc-tool.ts
 var docCache = /* @__PURE__ */ new Map();
 var CACHE_TTL = 10 * 60 * 1e3;
 function getCached(objectId) {
@@ -46400,71 +46645,158 @@ function getCached(objectId) {
   }
   return entry;
 }
-function setCache(objectId, doc, markdown) {
-  docCache.set(objectId, { doc, markdown, fetchedAt: Date.now() });
+function setCache(objectId, doc, markdown, breadcrumb) {
+  docCache.set(objectId, { doc, markdown, breadcrumb, fetchedAt: Date.now() });
 }
-function docViewTool(_managers) {
+function harmonyDocTool(_managers) {
   return tool({
-    description: "Fetch and display the content of a HarmonyOS developer document by its URL. Use this tool after harmony-doc-search to read the full content of a relevant document. The URL should be from developer.huawei.com (e.g. from search results). For long documents, use the page parameter to read content in chunks.",
+    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.",
     args: {
-      url: tool.schema.string("Full URL of the HarmonyOS document to view. Must be a developer.huawei.com document URL."),
-      page: tool.schema.number("Page number for long documents. Starts at 1. Use this when the response indicates more pages are available.").min(1).default(1)
+      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)
     },
     execute: async (args, _context) => {
-      try {
-        log("[harmony-doc-view]", { url: args.url, page: args.page });
-        const objectId = objectIdFromUrl(args.url);
-        if (!objectId) {
-          return `Error: Cannot extract document ID from URL: ${args.url}`;
-        }
-        let cached3 = getCached(objectId);
-        let doc;
-        let markdown;
-        if (cached3) {
-          doc = cached3.doc;
-          markdown = cached3.markdown;
-          log("[harmony-doc-view] cache hit", { objectId, page: args.page });
-        } else {
-          doc = await fetchDocument(objectId);
-          if (!doc.html) {
-            return `Error: Document content is empty for ${args.url}`;
-          }
-          markdown = htmlToMarkdown(doc.html);
-          setCache(objectId, doc, markdown);
-          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));
-        const page = Math.min(args.page, totalPages);
-        const start = (page - 1) * MAX_LENGTH;
-        const end = Math.min(page * MAX_LENGTH, markdown.length);
-        const chunk = markdown.substring(start, end);
-        let output = `# ${doc.title}
-
-Source: ${args.url}
+      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 });
+    const objectId = objectIdFromUrl(url3);
+    if (!objectId) {
+      return `Error: Cannot extract document ID from URL: ${url3}`;
+    }
+    let cached3 = getCached(objectId);
+    let doc;
+    let markdown;
+    let breadcrumb;
+    if (cached3) {
+      doc = cached3.doc;
+      markdown = cached3.markdown;
+      breadcrumb = cached3.breadcrumb;
+      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 });
+        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", {
+        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", {
+          objectId,
+          htmlLength: doc.html.length
+        });
+        return `Error: Document HTML was non-empty (${doc.html.length} chars) but converted to empty markdown for ${url3}. This may indicate the HTML structure is not supported.`;
+      }
+      breadcrumb = [];
+      if (doc.catalogName) {
+        try {
+          breadcrumb = await resolveBreadcrumb("cn", doc.catalogName, objectId);
+        } catch (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 });
+    }
+    const MAX_LENGTH = 3e4;
+    const totalPages = Math.max(1, Math.ceil(markdown.length / MAX_LENGTH));
+    const currentPage = Math.min(page ?? 1, totalPages);
+    const start = (currentPage - 1) * MAX_LENGTH;
+    const end = Math.min(currentPage * MAX_LENGTH, markdown.length);
+    const chunk = markdown.substring(start, end);
+    let output = `# ${doc.title}
+
+Source: ${url3}
 `;
-        if (doc.displayUpdateTime) {
-          output += `Updated: ${doc.displayUpdateTime}
+    if (breadcrumb.length > 0) {
+      output += `Path: ${breadcrumb.join(" > ")}
 `;
-        }
-        if (totalPages > 1) {
-          output += `Page ${page} of ${totalPages}
+    }
+    const updateTime = formatUpdateTime(doc.displayUpdateTime);
+    if (updateTime) {
+      output += `Updated: ${updateTime}
 `;
-        }
-        output += "\n---\n\n";
-        output += chunk;
-        if (page < totalPages) {
-          output += `
+    }
+    if (totalPages > 1) {
+      output += `Page ${currentPage} of ${totalPages}
+`;
+    }
+    output += "\n---\n\n";
+    output += chunk;
+    if (currentPage < totalPages) {
+      output += `
 
 ---
-[Document continues \u2014 call harmony-doc-view with page=${page + 1} to read more]`;
-        }
-        return output;
-      } catch (e) {
-        return `Error: ${e instanceof Error ? e.message : String(e)}`;
-      }
-    }
-  });
+[Document continues \u2014 call with action='view' and page=${currentPage + 1} to read more]`;
+    }
+    log("[harmony-doc view] RETURN", {
+      objectId,
+      outputLength: output.length,
+      chunkLength: chunk.length,
+      markdownLength: markdown.length,
+      outputEnd: output.substring(Math.max(0, output.length - 200))
+    });
+    return output;
+  } catch (e) {
+    return `Error: ${e instanceof Error ? e.message : String(e)}`;
+  }
 }
 
 // src/tools/builtin.ts
@@ -46472,8 +46804,7 @@ function createBuiltinTools(managers) {
   return {
     createHmTemplate: createHmTemplateTool(managers),
     skillSearch: skillSearchTool(managers),
-    "harmony-doc-search": docSearchTool(managers),
-    "harmony-doc-view": docViewTool(managers)
+    "harmony-doc": harmonyDocTool(managers)
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@harmonyos-arkts/opencode-plugin",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "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",