@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.2-beta.1] - 2026-04-19 - Trusted Publishing Verification
+
+### 🛠️ Infrastructure
+
+- **ci**: 升级 `publish.yml` 到 `actions/checkout@v6`、`actions/setup-node@v6`、Node `24` 与 `npm@11.5.1`
+- **release**: OIDC trusted publishing 路径移除显式 `--provenance`，保留 `NPM_TOKEN` fallback 以兼容 registry 偶发问题
+
+### 📝 Documentation
+
+- **release**: 同步 `llms.txt`、`AI_GUIDE.md`、`AI_DISCOVERY.md`、`ai-document-index.yaml` 到 `v0.5.2-beta.1`
+- **changelog**: 新增 beta 验证版本条目，用于自动发布链路验证与 GitHub Release 说明
+
+## [0.5.1] - 2026-04-19 - Rule Control Hardening & Release Sync
+
+### 🚀 New Features
+
+- **rules**: 发布 repo-local rule control baseline，包括 capability report、validator exit-code contract、hooks/CI backstop、scoped subagent rule context 与 executable QA
+- **workflow**: Claude / Codex 执行流现在会在常见执行路径中注入 scoped `<rule_context>`，减少规则遗漏与 prompt 串味
+
+### 📝 Documentation
+
+- **release**: 同步 `llms.txt`、`AI_GUIDE.md`、`AI_DISCOVERY.md`、`ai-document-index.yaml` 到 `v0.5.1`
+- **changelog**: 补齐本版本发布条目，确保 pre-release guardrail 与 GitHub Release notes 可用
+- **claude**: 补齐 `CLAUDE.md` 对 `docs/ai-guide/` 的入口引用，消除发布前 AI 文档交叉引用 warning
+
 ## [0.5.0] - 2026-04-15 - Design Contract Surface
 
 ### 🏗️ v1.4 Milestone: Design-to-Code Mapping & Handoff Package

package/README.md

@@ -7,7 +7,7 @@ CodeMap 是一个面向 TypeScript/JavaScript/Go 项目的 AI-first 代码地图
 ## 特性
 
 - **AI-first 代码地图** - 生成 `AI_MAP.md`、`CONTEXT.md`、`codemap.json` 等 AI/Agent 可直接消费的上下文
-- **核心分析命令** - 提供 `generate`、`query`、`deps`、`impact`、`complexity`、`cycles`、`analyze`、`design`、`export`、`ci`
+- **核心分析命令** - 提供 `generate`、`query`、`deps`、`impact`、`complexity`、`cycles`、`analyze`、`design`、`export`、`ci`，并提供 experimental `mcp`
 - **机器可读优先** - 结构化输出是产品基线；当前 CLI 过渡期仍主要通过 `--json` 暴露机器可读结果
 - **分层架构 (MVP3)** - 保持 `Interface → Infrastructure → Domain → Server → CLI` 的明确边界
 - **双层解析模式** - 提供 `fast`（快速正则）和 `smart`（TypeScript AST）两种解析模式
@@ -25,7 +25,7 @@ CodeMap 是一个面向 TypeScript/JavaScript/Go 项目的 AI-first 代码地图
 | 输出契约 | 目标是机器可读优先；`当前 CLI 现实` 是多数命令通过 `--json` 提供结构化结果，`analyze` 额外支持 `--output-mode machine|human` |
 | 架构边界 | `Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令 |
 
-当前公共 CLI 聚焦 `init`、`generate`、`query`、`deps`、`cycles`、`complexity`、`impact`、`analyze`、`design`、`ci`、`workflow`、`export`、`ship`；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
+当前公共 CLI 聚焦 `init`、`generate`、`query`、`deps`、`cycles`、`complexity`、`impact`、`analyze`、`design`、`ci`、`workflow`、`export`、`ship`，以及 experimental 的 `mcp`；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
 
 ## 安装
 
@@ -145,6 +145,7 @@ mycodemap init -y       # 使用默认配置直接创建
 mycodemap generate                    # 使用默认 hybrid 模式
 mycodemap generate -m smart           # 使用 smart 模式（AST 深度分析）
 mycodemap generate -o ./docs/codemap  # 指定输出目录
+mycodemap generate --symbol-level     # 额外 materialize symbol-level 调用依赖（实验性首期切片）
 
 # 别名：codemap generate 也可以使用
 ```
@@ -153,8 +154,12 @@ mycodemap generate -o ./docs/codemap  # 指定输出目录
 |------|------|--------|
 | `-m, --mode <mode>` | 分析模式：`fast`（正则匹配）、`smart`（TypeScript AST）或 `hybrid`（自动选择） | `hybrid` |
 | `-o, --output <dir>` | 输出目录 | `.mycodemap` |
+| `--symbol-level` | 额外把可解析的 symbol-level `call` 依赖写入图存储；默认 generate 行为不变 | `false` |
 | `--ai-context` | 为每个文件生成描述 | - |
 
+- `codemap.json` 现在会显式写出 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`。
+- 当某些发现到的文件没有成功进入最终图时，`graphStatus` 会降级为 `partial`；不要把这种结果当成完整图继续做自动化决策。
+
 **模式说明：**
 
 | 模式 | 速度 | 精度 | 适用场景 |
@@ -241,6 +246,30 @@ mycodemap impact -f src/cli/index.ts -j     # JSON 格式输出
 | `-t, --transitive` | 包含传递依赖（间接影响） | - |
 | `-j, --json` | 以 JSON 格式输出 | - |
 
+### `mycodemap mcp`（experimental）
+
+本地只读的 stdio MCP 薄切片。当前只提供两个工具：`codemap_query`、`codemap_impact`。
+
+```bash
+# 先生成 symbol-level 图
+mycodemap generate --symbol-level
+
+# 把当前仓库写入本地 MCP host 配置
+mycodemap mcp install
+
+# 由 MCP host 启动 stdio server
+mycodemap mcp start
+```
+
+| 子命令 | 说明 |
+|--------|------|
+| `mcp install` | 把 experimental 本地 server 写入当前仓库 `.mcp.json` |
+| `mcp start` | 启动本地 stdio MCP server；`stdout` 仅承载协议帧 |
+
+- `mcp` 当前是 **experimental / local-only / read-only** surface，不是稳定长期 public API。
+- 使用前必须先执行 `mycodemap generate --symbol-level`；否则工具会返回 `GRAPH_NOT_FOUND`。
+- canonical 集成文档见 `docs/ai-guide/INTEGRATION.md`；若宿主暂时不支持真正 MCP，可先回退到传统 CLI wrapper 方式。
+
 ### 已移除的公共 CLI 命令
 
 以下命令已从 public CLI 移除；直接调用时，CLI 会显式失败并给出迁移提示，而不是继续执行旧功能。
@@ -419,6 +448,8 @@ mycodemap ci assess-risk -f src/cache/lru-cache.ts
 mycodemap ci check-output-contract
 ```
 
+> `ci assess-risk` 现在输出 `status/confidence/freshness/source` 与统一 risk level；若 Git history 不可用，会显式打印 `unavailable` / warning，并说明阈值未被应用。
+
 ## 配置说明
 
 通过 `mycodemap init` 生成的 `mycodemap.config.json` 配置文件支持以下选项：
@@ -475,9 +506,9 @@ mycodemap ci check-output-contract
 | `exclude` | `string[]` | 排除的文件 glob 模式 | `["node_modules/**", "dist/**", ...]` |
 | `output` | `string` | 输出目录路径 | `".mycodemap"` |
 | `watch` | `boolean` | 监听模式预留配置 | `false` |
-| `storage.type` | `"filesystem" \| "kuzudb" \| "memory" \| "auto"` | 图存储后端类型 | `"filesystem"` |
+| `storage.type` | `"filesystem" \| "sqlite" \| "memory" \| "auto"` | 图存储后端类型 | `"filesystem"` |
 | `storage.outputPath` | `string` | 文件系统存储目录 | `".codemap/storage"` |
-| `storage.databasePath` | `string` | KùzuDB 数据目录（相对项目根目录） | - |
+| `storage.databasePath` | `string` | SQLite 数据目录（相对项目根目录） | `".codemap/governance.sqlite"` |
 | `storage.autoThresholds` | `object` | `auto` 后端选择阈值 | - |
 | `plugins.builtInPlugins` | `boolean` | 是否启用内置插件 | `true` |
 | `plugins.pluginDir` | `string` | 额外插件目录 | - |
@@ -489,16 +520,16 @@ mycodemap ci check-output-contract
 ```jsonc
 {
   "storage": {
-    "type": "kuzudb",
-    "databasePath": ".codemap/kuzu"
+    "type": "sqlite",
+    "databasePath": ".codemap/governance.sqlite"
   }
 }
 ```
 
 - `generate` 会把 CodeGraph 写入配置的 `storage` 后端，`export` 与内部 `Server Layer` handler 会读取同一份后端数据。
-- `neo4j` 已不再是正式支持的 backend；旧配置会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
-- 选择 `kuzudb` 前先安装 `npm install kuzu`；缺少依赖时会返回显式错误。
-- `storage.type = "auto"` 当前仍以 `filesystem` 为保守默认值；阈值字段先作为显式契约保留，不伪装成已完成的自动切换能力。
+- `neo4j` 与 `kuzudb` 已不再是正式支持的 backend；旧配置会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
+- 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，会返回显式错误。
+- `storage.type = "auto"` 当前优先选择 `sqlite`；若运行时缺少 `better-sqlite3` 或 Node.js `<20` 导致 SQLite 不可用，则 warning 后回退到 `filesystem`。
 - 图存储后端生产化不等于重新开放公共 HTTP API 产品面；`Server Layer` 仍是内部架构层。
 
 ### 插件运行时说明
@@ -703,6 +734,41 @@ mycodemap design verify mycodemap.design.md --json
 > `design handoff` 会基于 validated design contract + mapping truth 返回 `readyForExecution`、`approvals`、`assumptions`、`openQuestions`；human mode 默认写出 `.mycodemap/handoffs/{stem}.handoff.md|json`。
 > `design verify` 会把 `Acceptance Criteria` 固定映射为 `checklist`，并输出 `drift` / `diagnostics`；当结果只是 `needs-review` 时保持零退出码，只有 `ok=false` 或 blocker diagnostics 才返回非零 exit code。
 
+### `mycodemap check`
+
+执行 design contract contract gate，默认输出机器可读 JSON。
+
+```bash
+# 默认 full scan
+mycodemap check --contract mycodemap.design.md --against src
+
+# GitHub PR annotations
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+
+# GitLab code quality artifact
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format gitlab --annotation-file gl-code-quality-report.json
+
+# 校准当前仓库是否允许默认 hard gate
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+```
+
+> PR 默认 hard gate 只在 calibration 通过且 `changed files <= 10` 时开启；超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时必须显式切回 `warn-only / fallback`。
+
+### `mycodemap history`
+
+符号级 Git history / risk 查询：
+
+```bash
+# 默认输出 machine-first JSON
+mycodemap history --symbol createCheckCommand
+
+# 查询某个符号的历史轨迹与风险摘要
+mycodemap history --symbol createCheckCommand
+
+# 人类可读摘要
+mycodemap history --symbol createCheckCommand --human
+```
+
 ### `mycodemap analyze`
 
 统一分析入口，当前公共契约只暴露四个 intent，并统一返回结构化输出：
@@ -752,6 +818,8 @@ mycodemap analyze -i link -t src/index.ts --structured --json
 > 产品目标是机器可读优先；当前实现仍以显式 `--json` / `--output-mode` 作为主要入口。
 >
 > legacy 兼容映射：`search → find`、`impact/complexity → read`、`dependency/reference → link`、`overview/documentation → show`；`refactor` 会返回 `E0001_INVALID_INTENT`。
+>
+> `--include-git-history` 现在只会在 `read` intent 上附加统一的 Git history enrichment；其他 intent 会显式给出 warning，而不是 silent noop。
 
 
 ## 贡献指南

package/dist/cli/commands/analyze.d.ts

@@ -71,6 +71,24 @@ export declare class AnalyzeCommand {
      * find fallback
      */
     private executeFind;
+    private executeConfigAwareTextFallback;
+    private runConfigAwareTextFallback;
+    private resolveFallbackSearchScope;
+    private searchFileWithFallback;
+    private createExplicitPathFallbackResults;
+    private createFallbackResult;
+    private matchDiscoveredTargetFiles;
+    private isPathLikeTarget;
+    private uniqueNonEmptyStrings;
+    private toProjectRelativePath;
+    private toPosixPath;
+    private withDiagnostics;
+    private createSuccessDiagnostics;
+    private createPartialFailureDiagnostics;
+    private createFailureDiagnostics;
+    private createDiagnostic;
+    private errorMessage;
+    private isMachineOutputMode;
     /**
      * 执行 read 聚合
      */

package/dist/cli/commands/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/analyze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,UAAU,EAahB,MAAM,6BAA6B,CAAC;AAUrC;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,yBAAyB;IACzB,oBAAoB,UAAU;IAC9B,oBAAoB;IACpB,4BAA4B,UAAU;IACtC,qBAAqB;IACrB,sBAAsB,UAAU;IAChC,oBAAoB;IACpB,uBAAuB,UAAU;IACjC,oBAAoB;IACpB,sBAAsB,UAAU;IAChC,mBAAmB;IACnB,oBAAoB,UAAU;CAC/B;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAO3D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,EAErC,CAAC;AAEF;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAc;IAE1B;;;OAGG;gBACS,IAAI,EAAE,WAAW;IAI7B;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAiDhB;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAyBjC;;OAEG;YACW,uBAAuB;IAYrC;;OAEG;YACW,uBAAuB;IAuDrC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAuBlC;;OAEG;YACW,WAAW;IAyBzB;;OAEG;YACW,WAAW;IAqDzB;;OAEG;YACW,WAAW;IAuCzB;;OAEG;YACW,WAAW;IAmCzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;YACW,WAAW;IAUzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAiBnC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAkClC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA4ChC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAsCjC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoDxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;YACW,aAAa;IAsC3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;OAEG;YACW,WAAW;IAoCzB;;OAEG;YACW,iBAAiB;IAoC/B;;OAEG;YACW,eAAe;IAmB7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAuBzB;AAiBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CA6B5D;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0DlE;AAUD,YAAY,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/analyze.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/analyze.js

@@ -18,6 +18,8 @@ import { CodemapAdapter } from '../../orchestrator/adapters/codemap-adapter.js';
 import { AstGrepAdapter } from '../../orchestrator/adapters/ast-grep-adapter.js';
 import { IntentRouter } from '../../orchestrator/intent-router.js';
 import { resolveDataPath, resolveOutputDir } from '../paths.js';
+import { discoverProjectFiles } from '../../core/file-discovery.js';
+import { loadCodemapConfig } from '../config-loader.js';
 /**
  * 错误码定义
  */
@@ -132,11 +134,26 @@ export class AnalyzeCommand {
      */
     async executeFindWithFallback(intentObj, topK) {
         try {
-            return this.withCompatibility(await this.executeWithOrchestrator(intentObj, topK), intentObj.compatibility);
+            const orchestratedOutput = await this.executeWithOrchestrator(intentObj, topK);
+            if (orchestratedOutput.results.length > 0) {
+                return this.withCompatibility(this.withDiagnostics(orchestratedOutput, this.createSuccessDiagnostics()), intentObj.compatibility);
+            }
+            try {
+                await this.executeFind(intentObj, topK, { failOnScanError: true });
+            }
+            catch (scanError) {
+                return this.withCompatibility(await this.executeConfigAwareTextFallback(intentObj, topK, scanError, undefined), intentObj.compatibility);
+            }
+            return this.withCompatibility(this.withDiagnostics(orchestratedOutput, this.createSuccessDiagnostics()), intentObj.compatibility);
         }
-        catch {
+        catch (orchestratorError) {
             console.warn('[Analyze] Orchestrator not available, falling back to AstGrep search');
-            return this.executeFind(intentObj, topK);
+            try {
+                return await this.executeFind(intentObj, topK, { failOnScanError: true });
+            }
+            catch (scanError) {
+                return this.withCompatibility(await this.executeConfigAwareTextFallback(intentObj, topK, scanError, orchestratorError), intentObj.compatibility);
+            }
         }
     }
     /**
@@ -146,7 +163,7 @@ export class AnalyzeCommand {
         const orchestrator = new ToolOrchestrator();
         // 注册适配器
         const codemapAdapter = new CodemapAdapter({ codemapPath: resolveOutputDir().outputDir });
-        const astGrepAdapter = new AstGrepAdapter();
+        const astGrepAdapter = new AstGrepAdapter({ includeTests: this.args.includeTests ?? true });
         orchestrator.registerAdapter(codemapAdapter);
         orchestrator.registerAdapter(astGrepAdapter);
         const fusion = new ResultFusion();
@@ -230,9 +247,12 @@ export class AnalyzeCommand {
     /**
      * find fallback
      */
-    async executeFind(intentObj, topK) {
+    async executeFind(intentObj, topK, options = {}) {
         const searchTerms = intentObj.keywords.length > 0 ? intentObj.keywords : intentObj.targets;
-        const adapter = new AstGrepAdapter({ includeTests: this.args.includeTests ?? true });
+        const adapter = new AstGrepAdapter({
+            includeTests: this.args.includeTests ?? true,
+            failOnScanError: options.failOnScanError ?? false
+        });
         const rawResults = await adapter.execute(searchTerms, {
             topK,
             includeTests: this.args.includeTests,
@@ -246,6 +266,7 @@ export class AnalyzeCommand {
             tool: 'ast-grep-find',
             confidence,
             results,
+            diagnostics: this.createSuccessDiagnostics(),
             metadata: {
                 total: results.length,
                 resultCount: results.length,
@@ -253,6 +274,218 @@ export class AnalyzeCommand {
             }
         }, intentObj.compatibility);
     }
+    async executeConfigAwareTextFallback(intentObj, topK, scanError, orchestratorError) {
+        try {
+            const results = await this.runConfigAwareTextFallback(intentObj, topK);
+            const diagnostics = this.createPartialFailureDiagnostics(scanError, orchestratorError);
+            return {
+                schemaVersion: 'v1.0.0',
+                intent: 'find',
+                tool: 'codemap-find-fallback',
+                confidence: this.buildConfidence(results.length > 0 ? 0.65 : 0),
+                results,
+                diagnostics,
+                metadata: {
+                    total: results.length,
+                    resultCount: results.length,
+                    scope: intentObj.scope
+                }
+            };
+        }
+        catch (fallbackError) {
+            if (this.isMachineOutputMode()) {
+                process.exitCode = 1;
+            }
+            return {
+                schemaVersion: 'v1.0.0',
+                intent: 'find',
+                tool: 'codemap-find-fallback',
+                confidence: this.buildConfidence(0),
+                results: [],
+                diagnostics: this.createFailureDiagnostics(scanError, fallbackError, orchestratorError),
+                metadata: {
+                    total: 0,
+                    resultCount: 0,
+                    scope: intentObj.scope
+                }
+            };
+        }
+    }
+    async runConfigAwareTextFallback(intentObj, topK) {
+        const { config } = await loadCodemapConfig(process.cwd());
+        const discoveredFiles = await discoverProjectFiles({
+            rootDir: process.cwd(),
+            include: config.include,
+            exclude: config.exclude,
+            absolute: true,
+            gitignore: true
+        });
+        const { files, searchTerms, explicitPathMode } = this.resolveFallbackSearchScope(discoveredFiles, intentObj);
+        const results = [];
+        for (const file of files) {
+            const fileResults = await this.searchFileWithFallback(file, searchTerms, topK - results.length);
+            results.push(...fileResults);
+            if (results.length >= topK) {
+                return results.slice(0, topK);
+            }
+        }
+        if (explicitPathMode && intentObj.keywords.length === 0 && results.length === 0) {
+            const anchoredResults = await this.createExplicitPathFallbackResults(files, searchTerms, topK);
+            results.push(...anchoredResults);
+        }
+        return results.slice(0, topK);
+    }
+    resolveFallbackSearchScope(discoveredFiles, intentObj) {
+        const explicitPathTargets = intentObj.targets.filter(target => this.isPathLikeTarget(target));
+        const matchedTargetFiles = this.matchDiscoveredTargetFiles(discoveredFiles, explicitPathTargets);
+        if (matchedTargetFiles.length > 0) {
+            const pathTerms = explicitPathTargets.flatMap(target => {
+                const basename = path.basename(target);
+                return [basename, this.stripModuleExtension(basename)];
+            });
+            return {
+                files: matchedTargetFiles,
+                searchTerms: this.uniqueNonEmptyStrings(intentObj.keywords.length > 0 ? intentObj.keywords : pathTerms),
+                explicitPathMode: true
+            };
+        }
+        return {
+            files: discoveredFiles,
+            searchTerms: this.uniqueNonEmptyStrings(intentObj.keywords.length > 0 ? intentObj.keywords : intentObj.targets),
+            explicitPathMode: false
+        };
+    }
+    async searchFileWithFallback(file, searchTerms, remainingSlots) {
+        if (remainingSlots <= 0 || searchTerms.length === 0) {
+            return [];
+        }
+        const content = await readFile(file, 'utf-8');
+        const lines = content.split(/\r?\n/);
+        const results = [];
+        for (const [index, line] of lines.entries()) {
+            const matchedTerms = searchTerms.filter(term => line.includes(term));
+            if (matchedTerms.length === 0) {
+                continue;
+            }
+            const relativeFile = this.toProjectRelativePath(file);
+            const lineNumber = index + 1;
+            results.push(this.createFallbackResult(relativeFile, lineNumber, line, matchedTerms));
+            if (results.length >= remainingSlots) {
+                break;
+            }
+        }
+        return results;
+    }
+    async createExplicitPathFallbackResults(files, searchTerms, topK) {
+        const results = [];
+        for (const file of files) {
+            const content = await readFile(file, 'utf-8');
+            const firstLine = content.split(/\r?\n/, 1)[0] ?? '';
+            const relativeFile = this.toProjectRelativePath(file);
+            results.push(this.createFallbackResult(relativeFile, 1, firstLine || `Matched file path ${relativeFile}`, searchTerms));
+            if (results.length >= topK) {
+                break;
+            }
+        }
+        return results;
+    }
+    createFallbackResult(relativeFile, lineNumber, content, keywords) {
+        return {
+            id: `codemap-fallback:${relativeFile}:${lineNumber}`,
+            source: 'codemap-fallback',
+            toolScore: 0.65,
+            type: 'code',
+            file: relativeFile,
+            line: lineNumber,
+            location: {
+                file: relativeFile,
+                line: lineNumber,
+                column: 1
+            },
+            content: content.substring(0, 200),
+            relevance: 0.65,
+            keywords,
+            metadata: {
+                stability: true,
+                riskLevel: 'low'
+            }
+        };
+    }
+    matchDiscoveredTargetFiles(discoveredFiles, targets) {
+        const normalizedTargets = new Set(targets.flatMap(target => {
+            const absoluteTarget = path.resolve(process.cwd(), target);
+            return [
+                this.toPosixPath(absoluteTarget),
+                this.toPosixPath(path.relative(process.cwd(), absoluteTarget)),
+                this.toPosixPath(target)
+            ];
+        }));
+        return discoveredFiles.filter(file => {
+            const absoluteFile = path.resolve(file);
+            const relativeFile = path.relative(process.cwd(), absoluteFile);
+            return normalizedTargets.has(this.toPosixPath(absoluteFile))
+                || normalizedTargets.has(this.toPosixPath(relativeFile));
+        });
+    }
+    isPathLikeTarget(target) {
+        return target.includes('/') || target.includes('\\') || /\.[cm]?[jt]sx?$/i.test(target);
+    }
+    uniqueNonEmptyStrings(values) {
+        return Array.from(new Set(values.map(value => value.trim()).filter(Boolean)));
+    }
+    toProjectRelativePath(file) {
+        return this.toPosixPath(path.relative(process.cwd(), path.resolve(file)));
+    }
+    toPosixPath(filePath) {
+        return filePath.replace(/\\/g, '/');
+    }
+    withDiagnostics(output, diagnostics) {
+        return {
+            ...output,
+            diagnostics
+        };
+    }
+    createSuccessDiagnostics() {
+        return {
+            status: 'success',
+            items: []
+        };
+    }
+    createPartialFailureDiagnostics(scanError, orchestratorError) {
+        return {
+            status: 'partialFailure',
+            items: [
+                this.createDiagnostic('find-scanner-degraded', 'warning', `find 主扫描退化，已使用配置感知文本 fallback: ${this.errorMessage(scanError)}`, 'ast-grep', true, { orchestratorError: this.errorMessage(orchestratorError) })
+            ],
+            degradedTools: ['ast-grep']
+        };
+    }
+    createFailureDiagnostics(scanError, fallbackError, orchestratorError) {
+        return {
+            status: 'failure',
+            items: [
+                this.createDiagnostic('find-scanner-failed', 'error', `find 主扫描失败: ${this.errorMessage(scanError)}`, 'ast-grep', false, { orchestratorError: this.errorMessage(orchestratorError) }),
+                this.createDiagnostic('find-fallback-failed', 'error', `配置感知文本 fallback 失败: ${this.errorMessage(fallbackError)}`, 'codemap-find-fallback', false)
+            ],
+            failedTools: ['ast-grep', 'codemap-find-fallback']
+        };
+    }
+    createDiagnostic(code, severity, message, source, recoverable, details) {
+        return {
+            code,
+            severity,
+            message,
+            source,
+            recoverable,
+            ...(details ? { details } : {})
+        };
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    isMachineOutputMode() {
+        return this.args.json === true || this.args.structured === true || this.args.outputMode === 'machine';
+    }
     /**
      * 执行 read 聚合
      */