homegraph 1.5.3 → 1.5.4

package/dist/search/query-utils.js

@@ -51,6 +51,11 @@ exports.queryAsCoNamedTypeMethodInteraction = queryAsCoNamedTypeMethodInteractio
 exports.queryHasNamedMemberFocus = queryHasNamedMemberFocus;
 exports.queryAsNamedComponentAction = queryAsNamedComponentAction;
 exports.queryAsOutOfRepoSdkCatalog = queryAsOutOfRepoSdkCatalog;
+exports.queryAsCodeChangeOrientation = queryAsCodeChangeOrientation;
+exports.queryAsExternalManualOnly = queryAsExternalManualOnly;
+exports.queryAsGreenfieldScaffold = queryAsGreenfieldScaffold;
+exports.queryAsVcsHistoryOnly = queryAsVcsHistoryOnly;
+exports.queryAsMediaAssetInventory = queryAsMediaAssetInventory;
 exports.queryShouldDeferToBuiltinTools = queryShouldDeferToBuiltinTools;
 exports.homegraphDeferGuidance = homegraphDeferGuidance;
 exports.queryShouldPreferExploreOverSearch = queryShouldPreferExploreOverSearch;
@@ -96,6 +101,9 @@ exports.shouldBuildCallerInventory = shouldBuildCallerInventory;
 exports.extractCallerSurveySymbols = extractCallerSurveySymbols;
 exports.queryAsCrossModuleFlowSurvey = queryAsCrossModuleFlowSurvey;
 exports.queryAsDataSourceSurvey = queryAsDataSourceSurvey;
+exports.queryAsDataSourceDistinguishAsk = queryAsDataSourceDistinguishAsk;
+exports.queryAsMultiTypeDependencySurvey = queryAsMultiTypeDependencySurvey;
+exports.queryAsEventDispatchSurvey = queryAsEventDispatchSurvey;
 exports.extractLocalDetailAnchors = extractLocalDetailAnchors;
 exports.queryNeedsCoNamedUseBridge = queryNeedsCoNamedUseBridge;
 exports.queryAsLocalSymbolDetail = queryAsLocalSymbolDetail;
@@ -115,6 +123,8 @@ exports.extractDomainSearchTerms = extractDomainSearchTerms;
 exports.queryAsMechanismSurvey = queryAsMechanismSurvey;
 exports.queryAsDomainFileSurvey = queryAsDomainFileSurvey;
 exports.shouldBuildDomainFileSurvey = shouldBuildDomainFileSurvey;
+exports.mechanismDomainPathTokens = mechanismDomainPathTokens;
+exports.isDomainRoleSymbol = isDomainRoleSymbol;
 exports.isImplementationEntrySymbol = isImplementationEntrySymbol;
 exports.shouldCompactImportListing = shouldCompactImportListing;
 exports.shouldLimitToQueryNamedFile = shouldLimitToQueryNamedFile;
@@ -208,23 +218,32 @@ function extractKitModuleNamesFromQuery(query) {
  *  Covers `util模块`, `util 模块`, and `@kit.Foo的bar` / `@kit.Foo bar` (export focus).
  */
 function extractKitSubmoduleNamesFromQuery(query) {
+    // NL leftovers in agent rewrites ("util module API functions") — not exports.
+    const SUBMODULE_NOISE = new Set([
+        'module', 'modules', 'function', 'functions', 'feature', 'features',
+        'api', 'apis', 'capability', 'capabilities', 'export', 'exports',
+    ]);
     const names = new Set();
+    const add = (raw) => {
+        if (!raw || raw.length < 2)
+            return;
+        const s = raw.toLowerCase();
+        if (exports.STOP_WORDS.has(s) || exports.GENERIC_VERB_ANCHOR_NOISE.has(s) || SUBMODULE_NOISE.has(s))
+            return;
+        names.add(raw);
+    };
     for (const m of query.matchAll(/([a-z][a-z0-9_]{1,24})模块/gi)) {
-        if (m[1] && m[1].length >= 2)
-            names.add(m[1]);
+        add(m[1]);
     }
     for (const m of query.matchAll(/\b([a-z][a-z0-9_]*)\s+模块\b/gi)) {
-        if (m[1] && m[1].length >= 2)
-            names.add(m[1]);
+        add(m[1]);
     }
     // `@kit.ArkTS的taskpool` / `@kit.ArkTS的 foo` — named export, not a catalog.
     for (const m of query.matchAll(/@kit\.[A-Za-z][A-Za-z0-9]*的\s*([a-z][a-zA-Z0-9_]{2,24})\b/gi)) {
-        if (m[1])
-            names.add(m[1]);
+        add(m[1]);
     }
     for (const m of query.matchAll(/@kit\.[A-Za-z][A-Za-z0-9]*[\s.]+([a-z][a-zA-Z0-9_]{2,24})\b/gi)) {
-        if (m[1] && !exports.STOP_WORDS.has(m[1].toLowerCase()))
-            names.add(m[1]);
+        add(m[1]);
     }
     return [...names];
 }
@@ -235,7 +254,9 @@ function extractKitSubmoduleNamesFromQuery(query) {
 function queryAsKitModuleCapabilitySurvey(query) {
     if (extractKitModuleNamesFromQuery(query).length === 0)
         return false;
-    const capability = /有哪些功能|有什么功能|哪些功能|模块功能|功能有哪些|what\s+(?:are\s+the\s+)?features|module\s+features|kit\s+features/i.test(query);
+    const capability = /有哪些功能|有什么功能|哪些功能|模块功能|功能有哪些|what\s+(?:are\s+the\s+)?features|module\s+features|kit\s+features/i.test(query)
+        // Agent rewrites: "@kit.ArkTS util module API functions"
+        || /(?:module\s+)?API\s+functions?|API\s+(?:list|catalog|surface)|what\s+(?:APIs?|functions?)\s+(?:does|are)/i.test(query);
     if (!capability)
         return false;
     return /@kit\.|模块|\bkit\b/i.test(query) || extractKitSubmoduleNamesFromQuery(query).length > 0;
@@ -316,25 +337,77 @@ function queryAsNamedComponentAction(query) {
     return /点击|单击|按下|按钮|悬停|hover|onClick|onTap|onHover|会发生什么|what\s+happens|when\s+(?:clicked|pressed|hovered)/i.test(query);
 }
 /**
- * Out-of-repo SDK catalog (kept for survey omit logic — not as a refuse list).
+ * Out-of-repo SDK catalog phrasing (kit + "what features/APIs").
+ * Routed to Skip HomeGraph — graph has usages, not official feature lists.
  */
 function queryAsOutOfRepoSdkCatalog(query) {
     if (queryAsKitModuleCapabilitySurvey(query))
         return true;
-    const catalog = /有哪些(?:功能|API|接口|方法|能力)|提供(?:哪些|什么)|模块有哪些|what\s+(?:are\s+the\s+)?(?:apis?|features|methods)|(?:api|feature)\s+(?:list|catalog)|official\s+(?:api|sdk)\s+docs|module\s+features|kit\s+features/i.test(query);
-    if (!catalog)
+    const catalog = /有哪些(?:功能|API|接口|方法|能力)|提供(?:哪些|什么)|模块有哪些|what\s+(?:are\s+the\s+)?(?:apis?|features|methods)|(?:api|feature)\s+(?:list|catalog)|official\s+(?:api|sdk)\s+docs|module\s+features|kit\s+features/i.test(query)
+        || /(?:module\s+)?API\s+functions?|API\s+(?:list|catalog|surface)/i.test(query);
+    if (catalog && /@kit\.|\b[A-Z][A-Za-z0-9]*Kit\b/i.test(query))
+        return true;
+    // Pure SDK "which callback must I implement" with no in-repo file anchor.
+    // OHAudio-style SDK tokens may parse as Types — still catalog if no .ets/.ts file.
+    const hasFile = extractFileBasenamesFromQuery(query).length > 0;
+    const types = extractTypeNamesFromQuery(query);
+    const onlySdkishTypes = types.length > 0
+        && types.every((t) => /^(?:OH|Napi|NAPI)/.test(t) || /(?:Kit|API)$/.test(t));
+    if (!hasFile
+        && (types.length === 0 || onlySdkishTypes)
+        && /(?:C\s+API|NAPI|\bOH[A-Z][A-Za-z]+\b)/i.test(query)
+        && /需要实现哪个回调|实现哪个回调|哪个回调函数|which\s+callback\s+(?:must|should|to)\s+implement|callback\s+(?:to|must)\s+(?:implement|provide)/i.test(query)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Agent is about to change an existing codebase (feature / fix / refactor).
+ * Used for explore *routing* (prefer explore / light mechanism), not Skip.
+ */
+function queryAsCodeChangeOrientation(query) {
+    const q = query.trim();
+    if (!q)
         return false;
-    return /@kit\.|\b[A-Z][A-Za-z0-9]*Kit\b/i.test(query);
+    return (/(?:请)?(?:直接)?(?:在|给|为).{0,40}(?:工程|项目|代码|模块|页面|组件).{0,40}(?:新增|添加|增加|修改|改造|实现|修复|重构)/i.test(q)
+        || /(?:新增|添加|增加|修改|改造|实现|修复|重构|接入|改一下|帮我改).{0,40}(?:功能|逻辑|页面|组件|入口|按钮|接口|模块)/i.test(q)
+        || /\b(?:implement|add|introduce|wire|integrate|extend|refactor|fix|modify|update|change)\b.{0,60}\b(?:feature|page|component|module|handler|api|bug|crash|flow)\b/i.test(q)
+        || /\b(?:fix|repair|debug)\b.{0,40}\b(?:crash|bug|error|issue|regression)\b/i.test(q)
+        || /定位并修复|修复.*崩溃|修复.*闪退|find\s+(?:and\s+)?fix/i.test(q));
+}
+/** Explicit "answer from official docs / website only" — no repo graph needed. */
+function queryAsExternalManualOnly(query) {
+    return (/(?:请)?(?:只|仅)?(?:查阅|查看|打开|去看|参考)(?:一下)?(?:官方|官网)(?:文档|手册|网站)/i.test(query)
+        || /developer\.huawei\.com|华为开发者(?:联盟|官网)/i.test(query)
+        || /according\s+to\s+(?:the\s+)?official\s+(?:sdk\s+)?docs?(?:\s+only)?/i.test(query)
+        || /(?:read|see|check)\s+(?:the\s+)?official\s+(?:documentation|docs|website)\s+only/i.test(query)
+        || /不要看代码.*(?:文档|官网)|(?:文档|官网).*(?:不要|别)看代码/i.test(query));
+}
+/** Scaffold / empty project from scratch — nothing useful in an existing index. */
+function queryAsGreenfieldScaffold(query) {
+    return (/从零(?:开始)?(?:创建|新建|搭建)|创建(?:一个)?空的(?:工程|项目|应用)|新建(?:一个)?空白(?:工程|项目)/i.test(query)
+        || /create\s+(?:a\s+)?(?:new\s+)?(?:empty\s+)?(?:harmonyos\s+|arkts\s+)?(?:project|app)\s+from\s+scratch/i.test(query)
+        || /scaffold\s+(?:a\s+)?(?:brand\s+)?new\s+(?:empty\s+)?project/i.test(query));
+}
+/** Git / VCS history — not in the symbol graph. */
+function queryAsVcsHistoryOnly(query) {
+    return (/\bgit\s+(?:log|blame|diff|show|bisect|history)\b/i.test(query)
+        || /(?:提交历史|commit\s+history|git\s+blame|谁改过|上次提交|最近一次提交|哪次\s*commit)/i.test(query)
+        || /(?:查看|看一下|列出).{0,12}(?:git\s+)?(?:log|blame|diff)/i.test(query));
+}
+/** Media / binary asset inventory by extension — Glob, not the symbol graph. */
+function queryAsMediaAssetInventory(query) {
+    const listing = /(?:所有|全部|列出|找(?:出|到)?|盘点|有哪些|which|list|find|inventory)\b/i.test(query)
+        || /资源文件|图片资源|音频资源|媒体资源|media\s+assets?/i.test(query);
+    if (!listing)
+        return false;
+    return (/\.(?:png|jpe?g|gif|svg|webp|bmp|ico|mp4|mp3|wav|aac|flac|ttf|otf|woff2?)\b/i.test(query)
+        || /(?:png|jpe?g|gif|svg|webp|图片|图标|音频|视频|字体)\s*(?:文件|资源|assets?)/i.test(query));
 }
 function queryShouldDeferToBuiltinTools(query) {
     const q = query.trim();
     if (!q)
         return null;
-    // Pre-existing catalog classifiers (@kit / *Kit + "what features/APIs").
-    // Checked before named-member heuristics — `@kit.X` can look like Type.member.
-    if (queryAsOutOfRepoSdkCatalog(q) || queryAsKitModuleCapabilitySurvey(q)) {
-        return 'sdk-catalog';
-    }
     const hasType = extractTypeNamesFromQuery(q).length > 0;
     const hasFile = extractFileBasenamesFromQuery(q).length > 0;
     const hasMember = extractMemberAccessFromQuery(q).length > 0;
@@ -342,62 +415,35 @@ function queryShouldDeferToBuiltinTools(query) {
     const hasCaps = /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/.test(q);
     const hasField = extractFieldLikeSymbolsFromQuery(q).length > 0;
     const hasPath = extractPathSegmentsFromQuery(q).length > 0;
-    // Literal / layout / "import text from graphics package" hunts → Grep.
-    // No PascalCase Type — light-mechanism must not claim these.
+    const hasGraphAnchor = hasType || hasFile || hasMember || hasKit || hasCaps || hasField || hasPath;
+    // 1) Explicit external-manual-only asks.
+    if (queryAsExternalManualOnly(q))
+        return 'external-manual';
+    // 1b) Kit/SDK feature catalogs ("what APIs does X have") — not in-repo usage.
+    if (queryAsOutOfRepoSdkCatalog(q))
+        return 'sdk-catalog';
+    // 2) VCS history (independent of anchors — graph has no commits).
+    if (queryAsVcsHistoryOnly(q))
+        return 'vcs-history';
+    // 3) Media/binary asset inventories → Glob.
+    if (queryAsMediaAssetInventory(q))
+        return 'media-assets';
+    // 4) Greenfield empty scaffold (no existing code to orient on).
+    if (!hasGraphAnchor && queryAsGreenfieldScaffold(q))
+        return 'greenfield';
+    // 5) Repo-wide literal / copy / layout-string hunts → Grep.
+    // Layout chains (`.width('100%')`) can look like member access — still Skip.
+    if (queryLooksLikeLiteralOrCopyHunt(q))
+        return 'literal-hunt';
+    // 6) Topic → file list with no Type/file anchor → Glob/Grep.
     if (!hasType
         && !hasFile
-        && !hasMember
-        && !hasKit
-        && !hasCaps
-        && !hasField
-        && !hasPath
-        && queryLooksLikeLiteralOrCopyHunt(q)) {
-        return 'concept-or-existence';
-    }
-    // Structural / in-repo usage surveys must still run.
-    if (queryAsMechanismSurvey(q) || queryAsCrossModuleFlowSurvey(q))
-        return null;
-    if (shouldBuildKitModuleUsageSurvey(q) || shouldBuildApiUsageSurvey(q))
-        return null;
-    if (shouldBuildCallerInventory(q) || shouldTryLightMechanismExplore(q))
-        return null;
-    if (queryAsNamedComponentAction(q) || queryHasNamedMemberFocus(q))
-        return null;
-    if (queryAsInterpretationSurvey(q) || queryAsLocalSymbolDetail(q))
-        return null;
-    if (queryHasFocusedNamedAnchors(q))
-        return null;
-    if (queryAsDeclarationSiteSurvey(q)
-        || queryAsConstantUsageSurvey(q)
-        || queryAsFieldUsageSurvey(q)
-        || queryAsModuleExportSurvey(q)
-        || queryAsModuleDependencySurvey(q)) {
-        return null;
-    }
-    // "Which files relate to <topic>?" with no Type/file anchor → Glob/Grep.
-    if (/哪些文件|有哪些.*文件|相关的?\s*文件|涉及.*文件|which\s+files?|files?\s+(?:are\s+)?related/i.test(q)
-        && !hasType
-        && !hasFile) {
+        && /哪些文件|有哪些.*文件|相关的?\s*文件|涉及.*文件|which\s+files?|files?\s+(?:are\s+)?related/i.test(q)) {
         return 'file-listing';
     }
-    // Existence / concept-compare with no graph anchor → Grep/docs.
-    if (/有使用|是否使用|有没有使用|使用了.*吗|是否存在|有没有完整|有什么不同|区别|difference|vs\.?|versus|对比|does\s+(?:this\s+)?(?:project|repo)\s+have|is\s+there\s+(?:a\s+)?complete/i.test(q)
-        && !hasType
-        && !hasFile
-        && !hasMember
-        && !hasKit) {
-        return 'concept-or-existence';
-    }
-    // Hover / 悬停 without a named Type → inventory of hover handlers (not Skip).
-    if (shouldBuildHoverHandlerSurvey(q))
-        return null;
-    // Behavioral / interaction outcome with zero graph anchors → Grep (no symbol to seed).
-    // Do NOT include hover/悬停 here — those have a graph inventory path above.
-    if (!hasType
-        && !hasFile
-        && !hasMember
-        && !hasKit
-        && /会有什么|会发生什么|什么反应|what\s+happens|what\s+(?:is|are)\s+the\s+(?:reaction|response)|when\s+(?:the\s+)?user\b/i.test(q)) {
+    // 7) Pure existence / concept-compare with zero graph anchors → Grep/docs.
+    if (!hasGraphAnchor
+        && /有使用|是否使用|有没有使用|使用了.*吗|是否存在|有没有完整|有什么不同|区别|difference|vs\.?|versus|对比|does\s+(?:this\s+)?(?:project|repo)\s+have|is\s+there\s+(?:a\s+)?complete/i.test(q)) {
         return 'concept-or-existence';
     }
     return null;
@@ -406,15 +452,20 @@ function queryShouldDeferToBuiltinTools(query) {
 function homegraphDeferGuidance(kind, query) {
     const q = query.trim().slice(0, 120);
     const reasons = {
-        'sdk-catalog': 'Official SDK / @kit feature catalogs are outside this repo index — use SDK docs.',
         'file-listing': 'Topic → file lists need Grep/Glob (keyword paths), not the symbol graph.',
-        'concept-or-existence': 'Concept compare / UI-behavior / existence checks without a named in-repo Type/file/@kit target — Grep (and docs) beat HomeGraph.',
+        'literal-hunt': 'Repo-wide literal / copy / layout-string hunts with no Type/file/@kit anchor — use Grep.',
+        'concept-or-existence': 'Pure existence/concept-compare with no named in-repo Type/file/@kit/@ohos anchor — Grep/docs.',
+        'external-manual': 'Question asks for official website/docs only — open the manual; HomeGraph indexes code/API graphs, not marketing pages.',
+        'sdk-catalog': 'Kit/SDK **feature or API catalogs** ("what does util export") need SDK docs — HomeGraph indexes in-repo imports/usages, not official capability lists. Rephrase as "which files import @kit.X / export Y" if you want usages.',
+        'greenfield': 'Scaffolding an empty project from scratch needs generators/docs, not an existing code graph.',
+        'vcs-history': 'Git/commit/blame/diff history is not in the symbol graph — use git / IDE history.',
+        'media-assets': 'Media/binary asset inventories (.png/.mp4/fonts/…) need Glob, not the symbol graph.',
     };
     return [
         'Skip HomeGraph for this question shape — do **not** retry any `homegraph_*` tool for it.',
         reasons[kind],
         `Query: "${q}${query.trim().length > 120 ? '…' : ''}"`,
-        'Next: Grep / Glob / Read / SDK docs. Call HomeGraph only for in-repo wiring, callers/callees, or named-symbol flows.',
+        'Next: Grep / Glob / Read / git / SDK docs / project generators as appropriate. Otherwise call `homegraph_explore` with the task or symbol names.',
     ].join('\n');
 }
 /**
@@ -424,8 +475,10 @@ function queryShouldPreferExploreOverSearch(query) {
     const q = query.trim();
     if (!q)
         return false;
-    if (queryLooksLikeLiteralOrCopyHunt(query))
+    if (queryLooksLikeLiteralOrCopyHunt(query) && !queryAsCodeChangeOrientation(query))
         return false;
+    if (queryAsCodeChangeOrientation(query))
+        return true;
     if (/^[A-Za-z_][\w]*$/.test(q))
         return true;
     if (extractFileBasenamesFromQuery(query).length > 0
@@ -720,6 +773,18 @@ exports.GENERIC_VERB_ANCHOR_NOISE = new Set([
     // Inventory / NL fillers agents leave in rewritten bags (not real symbols).
     'usage', 'usages', 'use', 'uses', 'using', 'api', 'apis', 'endpoint', 'endpoints',
     'project', 'codebase', 'repo', 'documentation', 'document', 'docs', '说明',
+    // Kit-deps rewrite leftovers: "ServiceCollaborationKit import usage dependencies"
+    // must NOT become import-inventory focus (matches every `import` line).
+    'import', 'imports', 'importing', 'dependency', 'dependencies', 'deps', 'dep',
+    'param', 'params', 'parameter', 'parameters', 'extra', 'other', 'require', 'requires',
+    'calling', 'call', 'calls', 'needed', 'install', 'installing',
+    // Kit catalog rewrites: "util module API functions"
+    'module', 'modules', 'function', 'functions', 'feature', 'features',
+    'capability', 'capabilities', 'export', 'exports',
+    // Data-source EN rewrites: "badge source system service" must NOT become
+    // import-inventory focus (matches every `*Service` / ServiceExtensionAbility).
+    'service', 'services', 'source', 'sources', 'system', 'systems',
+    'upstream', 'origin', 'origins',
     // Shared-lib / GL thread NL leftovers (not symbols).
     'context', 'opengl', 'gles', 'glesv3', 'egl',
 ]);
@@ -879,14 +944,21 @@ function queryAsFieldUsageSurvey(query) {
 }
 /**
  * Native shared lib + GL/EGL thread questions (`libfoo.so` … OpenGL … 哪个线程).
- * Light-mechanism (CMake + EGLCore/PluginRender), not `.so` member survey.
+ * Light-mechanism (CMake + named Draw/Render/EGL owners), not `.so` member survey.
  */
 function queryAsNativeRenderThreadSurvey(query) {
     const hasLib = /\b\w+\.(?:so|dll|dylib)\b/i.test(query)
         || /\blib\w+\b/i.test(query);
     const hasGl = /\b(?:GLES(?:v3)?|EGL|OpenGL)\b/i.test(query);
     const hasThread = /线程|thread|UI\s*线程|主线程|JS\s*主?线程/i.test(query);
-    return (hasLib || hasGl) && hasThread;
+    if ((hasLib || hasGl) && hasThread)
+        return true;
+    // Named Draw/Render/EGL owner + frame-sync / sub-thread (no project Type list).
+    if (/\b(?:[A-Z][A-Za-z0-9]*(?:Draw|Render)|EGL(?:Core)?|EglCore)\b/.test(query)
+        && /帧同步|撕裂|tearing|frame\s*sync|synchron|mutex|sub-?thread|子线程/i.test(query)) {
+        return true;
+    }
+    return false;
 }
 /** Named `.d.ts` wrap — what calls / imports it in-repo. */
 function queryAsDtsWrapSurvey(query) {
@@ -915,11 +987,15 @@ function queryAsAssignedFlagImpactSurvey(query) {
  * Named Toggle/control kept consistent across surfaces — which module guarantees it.
  */
 function queryAsNamedControlStateSyncSurvey(query) {
+    // Prefer Toggle/Switch anchors — bag-of-words rewrites often add Control/Center noise Types.
     const types = extractTypeNamesFromQuery(query).filter((t) => !isFrameworkUiDecoratorName(t));
-    if (types.length < 1 || types.length > 2)
+    const controlTypes = types.filter((t) => /Toggle|Switch|开关/i.test(t));
+    const anchors = controlTypes.length > 0 ? controlTypes : types;
+    if (anchors.length < 1 || anchors.length > 3)
         return false;
-    return (/状态一致|保持一致|三处|哪个模块保证|who\s+keeps|consistent\s+state|state\s+sync|guarantees?\s+it|which\s+module\s+guarantees/i.test(query)
-        || (/Toggle|Switch|开关/.test(query) && /一致|保证|模块|consistent|guarantees?/i.test(query)));
+    return (/状态一致|保持一致|多处|多端|哪个模块保证|who\s+keeps|consistent\s+state|state\s+consistenc|state\s+sync|consistenc(?:y|ies)|guarantees?\s+it|which\s+module\s+guarantees|across\s+(?:surfaces|places)/i.test(query)
+        || (/Toggle|Switch|开关/i.test(query)
+            && /一致|保证|模块|consistenc|consistent|guarantees?/i.test(query)));
 }
 /**
  * Methods listed beside a Type for caller inventories
@@ -990,6 +1066,16 @@ function queryAsModuleDependencySurvey(query) {
  * Shape-only: no PascalCase Type / file / member / kit anchors.
  */
 function queryLooksLikeLiteralOrCopyHunt(query) {
+    // Layout/style literal chains first — `.width('100%')` looks like member access
+    // to extractors but is Grep territory.
+    if (/检索所有\s*\.\w+\(\s*['"][^'"]+['"]\s*\)/i.test(query)
+        || /\.\w+\(\s*['"][^'"]{1,40}['"]\s*\).{0,80}\.\w+\(\s*['"][^'"]{1,40}['"]\s*\)/i.test(query)) {
+        if (extractTypeNamesFromQuery(query).length === 0
+            && extractFileBasenamesFromQuery(query).length === 0
+            && extractKitModuleNamesFromQuery(query).length === 0) {
+            return true;
+        }
+    }
     if (extractTypeNamesFromQuery(query).length > 0)
         return false;
     if (extractFileBasenamesFromQuery(query).length > 0)
@@ -1059,6 +1145,11 @@ function extractApiUsageTokens(query) {
         if (m[1] && m[1].length >= 6)
             tokens.add(m[1]);
     }
+    // "statfs这个API端点" / "使用了statfs这个API" — Chinese demonstrative after the symbol.
+    for (const m of query.matchAll(/\b([A-Za-z_][\w]{2,})\s*这个\s*(?:API|接口|端点|方法)/gi)) {
+        if (m[1] && !exports.GENERIC_VERB_ANCHOR_NOISE.has(m[1].toLowerCase()))
+            tokens.add(m[1]);
+    }
     // When a PascalCase SDK/module token is present (Telephony, DrawContext), drop
     // short lowercase bag noise agents add (`call`/`radio`/`usage`) — those flood
     // false-positive files and tank precision.
@@ -1190,7 +1281,57 @@ function queryAsCrossModuleFlowSurvey(query) {
 }
 /** Data-source / upstream-service intent (来源于哪个服务 / which service). */
 function queryAsDataSourceSurvey(query) {
-    return /来源于|数据来源|状态来源|来自哪个|哪个系统服务|来自什么服务|data\s+source|status\s+source|state\s+source|which\s+service|来源.*服务|如何统一或区分/i.test(query);
+    if (/来源于|数据来源|状态来源|来自哪个|哪个系统服务|来自什么服务|data\s+source|status\s+source|state\s+source|which\s+service|来源.*服务|如何统一或区分/i.test(query)) {
+        return true;
+    }
+    // Agent EN / bag-of-words rewrites of the same intent.
+    if (/\bsystem\s+service\b/i.test(query))
+        return true;
+    if (/\bupstream\s+(?:service|source|data)\b/i.test(query))
+        return true;
+    if (/\bsource\b.{0,48}\b(?:system\s+)?service\b/i.test(query))
+        return true;
+    if (/\b(?:data|status|state)\b.{0,48}\bsource\b/i.test(query))
+        return true;
+    return false;
+}
+/** "How are sources unified/distinguished" — inventory alone is Partial, not ANSWER NOW. */
+function queryAsDataSourceDistinguishAsk(query) {
+    if (/如何统一或区分|统一或区分|区分.*来源|来源.*区分|unify|distinguish|how\s+(?:are|is).{0,40}(?:unified|distinguished)/i.test(query)) {
+        return true;
+    }
+    // Rewrites may drop 「如何统一或区分」but keep 状态来源 / status|state source.
+    if (/哪个系统服务|which\s+system\s+service|来源于哪个|来自哪个系统/i.test(query)) {
+        return false;
+    }
+    if (/\bsystem\s+service\b/i.test(query) && !/状态来源|status\s*source|state.{0,24}source/i.test(query)) {
+        return false;
+    }
+    return /状态来源|status\s*source|state\s+change\s+source|state.{0,24}source/i.test(query);
+}
+/**
+ * ≥3 named Types + dependency/relationship ask — inventory edges, not a fat
+ * multi-body compact that hits the soft deadline.
+ */
+function queryAsMultiTypeDependencySurvey(query) {
+    const types = extractTypeNamesFromQuery(query).filter((t) => t.length >= 8
+        || /(?:Manager|Installer|Parser|Service|Controller|Handler|Provider|Store)$/i.test(t));
+    if (types.length < 3)
+        return false;
+    return /依赖|关系|互相|之间|调用关系|dependenc|relationship|how\s+(?:do|are).{0,40}relate|related/i.test(query);
+}
+/**
+ * Event-type → handler/Manager dispatch inventory
+ * (`FooEvent` types / which Managers handle them).
+ */
+function queryAsEventDispatchSurvey(query) {
+    const types = extractTypeNamesFromQuery(query);
+    const hasEventType = types.some((t) => /Event$/i.test(t));
+    const hasEventCue = hasEventType
+        || /\b[A-Z][A-Za-z0-9]*Event\b|事件类型|事件枚举/i.test(query);
+    if (!hasEventCue)
+        return false;
+    return /分发|分发给|哪些\s*Manager|handlers?|dispatch|routed?\s+to|handled\s+by|处理/i.test(query);
 }
 /**
  * Local one/few-symbol behavior or contract — NOT multi-file mechanism / inventory.
@@ -1242,7 +1383,7 @@ function extractLocalDetailAnchors(query) {
         return score(b) - score(a) || a.localeCompare(b);
     });
     // Drop framework decorator names when a concrete UI Type is also present
-    // (`@CustomDialog` + WallpaperApplyDialog → keep only the Apply* types).
+    // (`@CustomDialog` + `FooDialog` → keep only the concrete UI types).
     const hasConcreteUi = ranked.some((n) => queryLooksLikeUiComponentType(n) && !isFrameworkUiDecoratorName(n));
     const filtered = hasConcreteUi
         ? ranked.filter((n) => !isFrameworkUiDecoratorName(n))
@@ -1296,6 +1437,8 @@ function queryAsLocalSymbolDetail(query) {
         return false;
     if (queryAsDataSourceSurvey(query))
         return false;
+    if (queryAsEventDispatchSurvey(query))
+        return false;
     // Named UI control + event: compact body + callees (not import inventory).
     if (queryAsNamedComponentAction(query))
         return true;
@@ -1418,33 +1561,17 @@ function extractMechanismEntrySeeds(query) {
             seeds.add(term);
         }
     }
-    // Shared-lib + GLES/EGL thread — seed the usual native GL owners (not `.so` / Context).
+    // Shared-lib + GLES/EGL thread — seed Draw/Render/EGL owners named in the query.
     if (queryAsNativeRenderThreadSurvey(query)) {
-        seeds.add('EGLCore');
-        seeds.add('PluginRender');
+        for (const t of extractTypeNamesFromQuery(query))
+            seeds.add(t);
+        for (const m of query.matchAll(/\b([A-Z][A-Za-z0-9]*(?:Draw|Render|Core))\b/g)) {
+            if (m[1])
+                seeds.add(m[1]);
+        }
         if (/\bCMakeLists\b|\.so\b|链接|link/i.test(query))
             seeds.add('CMakeLists');
     }
-    // Theme pack download→parse→install — agents often omit PascalCase names.
-    if (/主题|theme\s*pack|theme\s*package/i.test(query) && /安装|解析|下载|install|parse|download/i.test(query)) {
-        for (const s of [
-            'ThemePackParser', 'ThemePackageInstaller', 'SkinInstaller', 'IconsInstaller', 'FontInstaller',
-        ]) {
-            seeds.add(s);
-        }
-    }
-    // Notification subscribe/manage howto — same pattern (CJK domain, no Type named).
-    if (/通知|notification/i.test(query) && /订阅|subscribe|管理|manage|多线程|multithread/i.test(query)) {
-        for (const s of ['NotificationManager', 'NotificationSubscriber', 'AnsManager', 'SubscribeCallback']) {
-            seeds.add(s);
-        }
-    }
-    // XML parse howto — seed the real API, not bare `xml` (which floods every Xml* path).
-    if (/\bxml\b|xml解析|解析xml/i.test(query) && /解析|parse|convert|实现/i.test(query)) {
-        for (const s of ['convertxml', 'XmlParseUtil', 'ConvertXML', 'fastConvertToJSObject']) {
-            seeds.add(s);
-        }
-    }
     return [...seeds].filter((s) => s.length >= 3).slice(0, 12);
 }
 /**
@@ -1476,20 +1603,50 @@ function queryAsDomainMechanismBag(query) {
     const distinct = domain.filter((t) => /^[A-Za-z][A-Za-z0-9._-]{2,}$/.test(t) && !exports.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()));
     if (distinct.length === 0)
         return false;
-    const hasActionVerb = domain.some((t) => exports.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase()))
+    // Only *verb* leftovers count as the action half. Noun noise in
+    // GENERIC_VERB_ANCHOR_NOISE (`service` / `source` / `system` / `api` / …)
+    // must not turn a multi-term locator bag (`item service`) into light-mechanism.
+    const MECHANISM_BAG_NOUN_NOISE = new Set([
+        'service', 'services', 'source', 'sources', 'system', 'systems',
+        'upstream', 'origin', 'origins',
+        'usage', 'usages', 'use', 'uses', 'using',
+        'api', 'apis', 'endpoint', 'endpoints',
+        'module', 'modules', 'function', 'functions', 'feature', 'features',
+        'capability', 'capabilities', 'export', 'exports',
+        'dependency', 'dependencies', 'deps', 'dep',
+        'param', 'params', 'parameter', 'parameters',
+        'project', 'codebase', 'repo', 'documentation', 'document', 'docs',
+        'context', 'opengl', 'gles', 'glesv3', 'egl',
+        'extra', 'other', 'require', 'requires', 'needed',
+    ]);
+    const hasActionVerb = domain.some((t) => {
+        const l = t.toLowerCase();
+        return exports.GENERIC_VERB_ANCHOR_NOISE.has(l) && !MECHANISM_BAG_NOUN_NOISE.has(l);
+    })
         || /\b(?:parse|implement|manage|handle|process|subscribe|convert|encode|decode)(?:s|d|ing)?\b/i.test(query);
     // Remaining CJK tokens are the topic half of a rewritten how-question bag.
     const hasCjkDomain = domain.some((t) => /[\u4e00-\u9fff]/.test(t));
     return hasActionVerb || hasCjkDomain;
 }
 function shouldTryLightMechanismExplore(query) {
+    if (queryShouldDeferToBuiltinTools(query))
+        return false;
     if (queryAsCrossModuleFlowSurvey(query))
         return false;
     if (queryAsInterpretationSurvey(query))
         return false;
-    // Literal / copy hunts → Grep (never light dump).
-    if (queryLooksLikeLiteralOrCopyHunt(query))
+    // Literal / copy hunts → Grep (never light dump), unless this is an edit/fix task.
+    if (queryLooksLikeLiteralOrCopyHunt(query) && !queryAsCodeChangeOrientation(query))
         return false;
+    // Pre-edit orientation: task keywords → light mechanism seeds (domain / Type / file).
+    if (queryAsCodeChangeOrientation(query)) {
+        if (extractDomainSearchTerms(query).length >= 1
+            || extractTypeNamesFromQuery(query).length > 0
+            || extractFileBasenamesFromQuery(query).length > 0
+            || extractMemberAccessFromQuery(query).length > 0) {
+            return true;
+        }
+    }
     // System-setting howto → lean capability inventory, not every `language` import.
     if (queryAsInRepoSystemCapabilityHowto(query))
         return false;
@@ -1499,6 +1656,12 @@ function shouldTryLightMechanismExplore(query) {
     // Manager data/status source → inventory, not light-mechanism.
     if (queryAsDataSourceSurvey(query))
         return false;
+    // Event type → Manager dispatch inventory.
+    if (queryAsEventDispatchSurvey(query))
+        return false;
+    // ≥3 Types + dependency relationship → lean inventory (not light/compact dump).
+    if (queryAsMultiTypeDependencySurvey(query))
+        return false;
     // Named UI control + event → compact (body + callees + usage sites), not light-mechanism.
     if (queryAsNamedComponentAction(query))
         return false;
@@ -1546,6 +1709,8 @@ function shouldTryLightMechanismExplore(query) {
  * Skip expensive subgraph gathering — inventory sections alone answer the query.
  */
 function shouldTryFastInventoryExplore(query) {
+    if (queryShouldDeferToBuiltinTools(query))
+        return false;
     if (queryAsCrossModuleFlowSurvey(query))
         return false;
     if (shouldTryLightMechanismExplore(query))
@@ -1571,6 +1736,8 @@ function shouldTryFastInventoryExplore(query) {
         || shouldBuildDomainFileSurvey(query)
         || shouldBuildConfigSection(query)
         || queryAsDataSourceSurvey(query)
+        || queryAsEventDispatchSurvey(query)
+        || queryAsMultiTypeDependencySurvey(query)
         || shouldBuildHoverHandlerSurvey(query)
         || queryAsModuleExportSurvey(query)
         || queryAsModuleDependencySurvey(query)
@@ -1669,7 +1836,14 @@ function extractDomainSearchTerms(query) {
 }
 /** How/implementation/mechanism intent — needs entry symbols + flow, not flat file list. */
 function queryAsMechanismSurvey(query) {
-    return /如何(?:实现|获取|做|处理|管理)|怎样(?:实现|获取|做)|怎么(?:实现|获取|做)|是如何|是怎么|how\s+(?:is|does|are|to\s+(?:get|implement|work))|机制|流程|架构|多线程|多进程|multithread|multi-thread|会走到哪些|步骤中会|解析和安装|下载完|下载后/i.test(query);
+    // Cross-Type drive / state-machine interaction — must not collapse into compact
+    // hard-ANSWER-NOW on abstract base names (Machine+Engine, Session FG/BG, …).
+    const types = extractTypeNamesFromQuery(query).filter((t) => !isFrameworkUiDecoratorName(t));
+    if (types.length >= 2
+        && /驱动|触发|状态机|状态变化|重新计算|foreground|background|layout|布局/i.test(query)) {
+        return true;
+    }
+    return /如何(?:实现|获取|做|处理|管理|驱动|触发)|怎样(?:实现|获取|做|驱动|触发)|怎么(?:实现|获取|做|驱动|触发)|是如何|是怎么|how\s+(?:is|does|are|to\s+(?:get|implement|work|drive|trigger))|机制|状态机|流程|架构|多线程|多进程|multithread|multi-thread|会走到哪些|步骤中会|解析和安装|下载完|下载后|状态变化如何|如何驱动|如何触发/i.test(query);
 }
 /**
  * Broad domain survey — related files, usage existence, or concept comparison.
@@ -1712,7 +1886,57 @@ function shouldBuildDomainFileSurvey(query) {
     return queryAsDomainFileSurvey(query) && extractDomainSearchTerms(query).length > 0;
 }
 /** Callable/class names that commonly anchor implementation flows. */
-exports.IMPLEMENTATION_ENTRY_NAME_RE = /Manager|Service|Handler|Extension|Parser|Helper|Controller|Provider|Worker|Backup|Restore|Subscription|Monitor|Coordinator|Delegate|Adapter|Factory|Processor/i;
+exports.IMPLEMENTATION_ENTRY_NAME_RE = /Manager|Service|Handler|Extension|Parser|Helper|Controller|Provider|Worker|Backup|Restore|Subscription|Monitor|Coordinator|Delegate|Adapter|Factory|Processor|Subscriber|Listener/i;
+/**
+ * ASCII path/name stems for mechanism affinity.
+ * Expands a few CJK domain nouns so `通知订阅` can match `/notification/` paths
+ * without a product-specific file blacklist.
+ */
+function mechanismDomainPathTokens(query) {
+    const out = new Set();
+    for (const t of extractDomainSearchTerms(query)) {
+        if (/^[\x00-\x7F]+$/.test(t) && t.length >= 4 && !exports.GENERIC_VERB_ANCHOR_NOISE.has(t.toLowerCase())) {
+            out.add(t.toLowerCase());
+        }
+    }
+    if (/通知/.test(query))
+        out.add('notification');
+    if (/订阅/.test(query)) {
+        out.add('subscribe');
+        out.add('subscriber');
+    }
+    if (/壁纸|wallpaper/i.test(query))
+        out.add('wallpaper');
+    if (/主题|theme/i.test(query)) {
+        out.add('theme');
+        // Prefer themeservice / themepack paths over appinstall "download/install" Managers.
+        out.add('themeservice');
+        out.add('themepack');
+    }
+    if (/备份|backup/i.test(query))
+        out.add('backup');
+    if (/恢复|restore/i.test(query))
+        out.add('restore');
+    if (/锁屏|screenlock|keyguard/i.test(query)) {
+        out.add('screenlock');
+        out.add('keyguard');
+    }
+    return [...out].slice(0, 12);
+}
+/** Class/file looks like a domain Manager/Service under matching path or name. */
+function isDomainRoleSymbol(name, filePath, domainTokens) {
+    if (!exports.IMPLEMENTATION_ENTRY_NAME_RE.test(name))
+        return false;
+    if (domainTokens.length === 0)
+        return /Manager|Subscriber|Listener$/i.test(name);
+    const blob = `${name}\n${filePath}`.toLowerCase().replace(/\\/g, '/');
+    return domainTokens.some((t) => {
+        const tl = t.toLowerCase();
+        if (tl.length < 4)
+            return false;
+        return blob.includes(tl) || blob.includes(`/${tl}/`);
+    });
+}
 function isImplementationEntrySymbol(name, domainTerms) {
     if (!exports.IMPLEMENTATION_ENTRY_NAME_RE.test(name))
         return false;
@@ -2043,6 +2267,8 @@ function isTestFile(filePath) {
         lower.includes('/__tests__/') || lower.includes('/spec/') ||
         lower.includes('/specs/') || lower.includes('/testlib/') ||
         lower.includes('/testing/') ||
+        // HarmonyOS / OpenHarmony instrumented test trees
+        lower.includes('/ohostest/') ||
         lower.startsWith('test/') || lower.startsWith('tests/') ||
         lower.startsWith('spec/') || lower.startsWith('specs/') ||
         // CamelCase test source-set dirs (Kotlin Multiplatform / Gradle / Xcode):