spectra-cli 4.1.1 → 4.3.0

package/README.md

@@ -3,7 +3,7 @@
 <!-- spec-driver:section:badges -->
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![npm version](https://img.shields.io/npm/v/spectra-cli.svg)
-![Version](https://img.shields.io/badge/version-4.1.1-green)
+![Version](https://img.shields.io/badge/version-4.3.0-green)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6)
 ![Node.js](https://img.shields.io/badge/Node.js-20.x+-339933)
 <!-- spec-driver:section:badges:end -->
@@ -53,6 +53,12 @@
 | **M-100** Spectra Evolution | ✅ Delivered | reverse-spec → Spectra rebrand · panoramic Phase 1（多语言索引、跨包依赖、LLM 语义增强、多格式输出） | [blueprint](specs/M-100-spectra-evolution/blueprint.md) |
 | **M-101** Phase 2 — Reading Platform | ✅ Delivered | Graph schema v2.0 + Hyperedges · LLM cost transparency · SpecStore + sourceKind · TODO/Open Questions extraction · Natural language Q&A + interactive `graph.html` · Default model upgrade to Sonnet 4.6 / Opus 4.7 1M | [blueprint](specs/M-101-phase2-reading-platform/blueprint.md) · [postmortem](specs/M-101-phase2-reading-platform/postmortem.md) |
 | **M-102 / M-103** Phase 3 | 🟡 In Progress | Python AST function-level graph (v4.1) · E2E fixture infrastructure · large-project baseline · LLM concurrency optimizer | [proposal](specs/M-102-phase3/proposal.md) |
+| **M7** Spectra MCP Productization | ✅ Delivered | 17 MCP tools（统一 `{code}` 响应契约 + 全工具 telemetry）· file navigation + symbol fuzzy match · batch 默认增量 + byte-stable graph.json · 44 stdio E2E · spec-driver 4.2.1（委派硬约束）· SWE-Bench Verified 5-cohort 评测 | [milestone](docs/design/milestone-M7-spectra-mcp-productization.md) · [评测报告](specs/147-competitor-evaluation-platform/PUBLISH-REPORT-M7.md) |
+| **M8** Trust Repair + Drift Flagship | ✅ Delivered | 增量缓存正确性（混合大小写/混语言）· MCP 触发率工程 · 委派契约全 skill 单源化（F185）· FAIL_TO_PASS 评测 oracle（评测设施 v2）· `batch --mode graph-only`（纯 AST·零 LLM 建图）· `spectra --version` build 元数据 · **领域知识脚手架** `scaffold-kb` + KB MCP（doc-graph + FTS5 双层联查）· AST-anchored spec drift 原型（spec + prototype） | [milestone](docs/design/milestone-M8-trust-repair-and-drift-flagship.md) |
+
+> **M8 note** — Spectra release contract is bumped to **4.3.0** (F186: build-stamped `--version`, wrapper sha256 gate); the npm `spectra-cli` publish of 4.3.0 is staged pending explicit authorization. The M7 eval re-judge on the new FAIL_TO_PASS oracle is wired and ready to run.
+
+> **Honest benchmark note (M7, 2026-06)** — We ran a 150-run SWE-Bench Verified comparison (bare Claude Code vs Spec Driver vs Spec Driver + Spectra MCP vs SuperPowers vs GStack). After correcting a one-sided oracle bias (the fuzzy-match scorer penalized frameworks for writing tests — see [report §4.5](specs/147-competitor-evaluation-platform/PUBLISH-REPORT-M7.md)), **all five cohorts tie on completion rate** within N=30 noise. Two honest signals: structured workflows cost **4-12× more tokens with no completion gain on single-file fixes**, and Spectra MCP's real gap is *adoption, not quality* — runs that actually called the MCP tools passed at 43% vs 12% for those that didn't, with the heaviest MCP usage producing the strongest single fix in the dataset. M8 targets exactly these: trigger-rate engineering + a real FAIL_TO_PASS execution oracle.
 
 ## Quick Start
 
@@ -75,7 +81,7 @@ spectra batch --mode reading --html       # ~2-5 min for typical project
 /spec-driver:spec-driver-feature  Add OAuth2 login flow
 ```
 
-After step 4, AI coding assistants (Claude Code, Cursor, Codex with MCP) can query your codebase architecture via 6 MCP tools — **see [How AI Coding Assistants Use Spectra](#-how-ai-coding-assistants-use-spectra) below**.
+After step 4, AI coding assistants (Claude Code, Cursor, Codex with MCP) can query your codebase architecture via **17 MCP tools** (6 graph queries + 3 agent-context + 3 file-navigation + 5 pipeline) — **see [How AI Coding Assistants Use Spectra](#-how-ai-coding-assistants-use-spectra) below**.
 
 ---
 
@@ -89,10 +95,10 @@ A hybrid AST + LLM pipeline that reverse-engineers source code into structured S
 
 - 📝 **9-section module specs** — AST-extracted intent / interface / data / dependencies / quality / lifecycle / etc. (TS/JS interface 100% AST-extracted)
 - 🌐 **Knowledge graph schema v2.0** — `references` / `conceptually_related_to` / `rationale_for` edges + multi-node hyperedges
-- 🔍 **6 MCP query tools** — natural language graph queries that AI assistants can call directly
+- 🔍 **17 MCP tools** — graph queries (community / god-nodes / hyperedges / path) + agent context (impact / context / detect_changes with unified `{code}` error contract + per-call telemetry) + file navigation (token-efficient line-range reads, symbol fuzzy match) + pipeline (prepare / generate / batch / diff / panoramic-query)
 - 📊 **Interactive `graph.html`** — D3-force visualization with hyperedge convex hulls (self-contained, no server)
 - 💰 **LLM cost transparency** — `--dry-run` cost preview + `--budget N` enforcement + `tokenUsage` in every spec frontmatter
-- ⚡ **Lightweight modes** — `--mode reading` (skip product docs) / `--mode code-only` (skip all LLM, AST-only)
+- ⚡ **Lightweight modes** — `--mode reading` (skip product docs) / `--mode code-only` (skip enrichment, still per-module spec-gen LLM) / `--mode graph-only` (pure AST, zero LLM, no auth)
 - 🚧 **Technical debt extraction** — TODO/FIXME/HACK code comments + design-doc Open Questions
 - 🔄 **Continuous sync** — `spectra watch` (file watcher) or `spectra install` (post-commit hook)
 - 🌍 **Multi-language** — TS/JS (ts-morph) + Python (AST + tree-sitter) + Go/Java/Rust (tree-sitter)
@@ -163,7 +169,7 @@ This is **AI-for-AI architecture memory**: the AI never has to re-read your code
 - **Token economics** — Querying a 50K-token graph instead of re-reading 500K LOC saves 90%+ tokens per session
 - **Cross-session memory** — `_meta/graph.json` persists between Claude Code sessions; AI can ask "what changed since last time?"
 - **Multi-IDE compatible** — Same MCP server works for Claude Code, Cursor, Codex, Aider, OpenCode, etc.
-- **Hook-driven freshness** — `spectra install` registers a post-commit hook that incrementally rebuilds the graph; AI always queries the latest
+- **Hook-driven freshness** — `spectra install --git` registers a post-commit hook that incrementally rebuilds the graph; AI always queries the latest
 
 #### Trigger via auto-injection (PreToolUse hook)
 
@@ -318,6 +324,7 @@ Notes:
 ## Documentation
 
 - 📘 **[Spectra CLI Reference](docs/spectra-cli-reference.md)** — full command list, knowledge graph workflows, architecture pipeline diagram
+- 📚 **[Domain Knowledge Scaffold Guide](docs/scaffold-kb-guide.md)** — build a vendor doc KB (`scaffold-kb`), ship it as a plugin, query via KB MCP tools
 - 🎼 **[Spec Driver Modes](docs/spec-driver-modes.md)** — 8 modes detailed, sub-agents, generated artifacts, quality gates
 - ⚙️ **[Configuration](docs/configuration.md)** — model presets (`spec-driver.config.yaml`) + project-level orchestration overrides (`.specify/orchestration-overrides.yaml`)
 - 🏛️ **[Repository Architecture](docs/repository-architecture.md)** — `src/` layout, tech stack, testing, sync contracts

package/dist/.spectra-build-meta.json

@@ -0,0 +1,9 @@
+{
+  "commit": "4d1fb050e7dd1f585a3aa7f95c138bcf5b2d5cb6",
+  "dirty": true,
+  "sourceDirty": false,
+  "distSha256": "96551a712ad01d1ae5870418faa7a4567137424d48453ea61407d4ada3dc9cc8",
+  "distFileCount": 342,
+  "builtAtIso": "2026-07-19T03:58:42.612Z",
+  "note": "F176 版本门禁凭据；勿手改。distSha256 绑定 dist 内容；sourceDirty 只看 build 输入。"
+}

package/dist/adapters/go-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"go-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/go-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,iBAAkB,YAAW,eAAe;IACvD,QAAQ,CAAC,EAAE,QAAQ;IAEnB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAU;IAEjD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAoB;IAE5D,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAE5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAOxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAMlE"}
+{"version":3,"file":"go-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/go-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,iBAAkB,YAAW,eAAe;IACvD,QAAQ,CAAC,EAAE,QAAQ;IAEnB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAU;IAEjD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAoB;IAE5D,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAE5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IASxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAMlE"}

package/dist/adapters/go-adapter.js

@@ -15,6 +15,8 @@ export class GoLanguageAdapter {
         const analyzer = TreeSitterAnalyzer.getInstance();
         return analyzer.analyze(filePath, 'go', {
             includePrivate: options?.includePrivate,
+            // Feature 153 — 透传 extractCallSites flag（与 PythonLanguageAdapter 行为一致）
+            extractCallSites: options?.extractCallSites,
         });
     }
     /**

package/dist/adapters/go-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"go-adapter.js","sourceRoot":"","sources":["../../src/adapters/go-adapter.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAGnF,MAAM,OAAO,iBAAiB;IACnB,EAAE,GAAG,IAAI,CAAC;IAEV,SAAS,GAAwB,CAAC,IAAI,CAAC,CAAC;IAExC,UAAU,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAEnD,iBAAiB,GAAwB,IAAI,GAAG,CAAC;QACxD,QAAQ;KACT,CAAC,CAAC;IAEH;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,OAA4B;QAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC;QAClD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE;YACtC,cAAc,EAAE,OAAO,EAAE,cAAc;SACxC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO;YACL,iBAAiB,EAAE,IAAI;YACvB,aAAa,EAAE,0BAA0B;YACzC,aAAa,EAAE,kBAAkB;YACjC,qBAAqB,EAAE,yBAAyB;YAChD,gBAAgB,EAAE,qCAAqC;YACvD,YAAY,EAAE,qCAAqC;SACpD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO;YACL,WAAW,EAAE,eAAe;YAC5B,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,6BAA6B,CAAC,QAAQ,EAAE;YAC7C,WAAW,EAAE,IAAI;YACjB,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"go-adapter.js","sourceRoot":"","sources":["../../src/adapters/go-adapter.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAGnF,MAAM,OAAO,iBAAiB;IACnB,EAAE,GAAG,IAAI,CAAC;IAEV,SAAS,GAAwB,CAAC,IAAI,CAAC,CAAC;IAExC,UAAU,GAAwB,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAEnD,iBAAiB,GAAwB,IAAI,GAAG,CAAC;QACxD,QAAQ;KACT,CAAC,CAAC;IAEH;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,OAA4B;QAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC;QAClD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE;YACtC,cAAc,EAAE,OAAO,EAAE,cAAc;YACvC,uEAAuE;YACvE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB;SAC5C,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO;YACL,iBAAiB,EAAE,IAAI;YACvB,aAAa,EAAE,0BAA0B;YACzC,aAAa,EAAE,kBAAkB;YACjC,qBAAqB,EAAE,yBAAyB;YAChD,gBAAgB,EAAE,qCAAqC;YACvD,YAAY,EAAE,qCAAqC;SACpD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO;YACL,WAAW,EAAE,eAAe;YAC5B,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,6BAA6B,CAAC,QAAQ,EAAE;YAC7C,WAAW,EAAE,IAAI;YACjB,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;SACvC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/adapters/index.d.ts

@@ -6,7 +6,7 @@ export type { LanguageAdapter } from './language-adapter.js';
 export type { LanguageTerminology } from './language-adapter.js';
 export type { TestPatterns } from './language-adapter.js';
 export type { AnalyzeFileOptions } from './language-adapter.js';
-export type { DependencyGraphOptions } from './language-adapter.js';
+export type { ModuleGraphOptions } from './language-adapter.js';
 export { LanguageAdapterRegistry } from './language-adapter-registry.js';
 export { TsJsLanguageAdapter } from './ts-js-adapter.js';
 export { PythonLanguageAdapter } from './python-adapter.js';

package/dist/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAYxD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAYxD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC"}

package/dist/adapters/java-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"java-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/java-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,EAAE,UAAU;IAErB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAY;IAEnD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAsB;IAE9D,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAQ5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAOxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;;OAGG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAMlE"}
+{"version":3,"file":"java-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/java-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,EAAE,UAAU;IAErB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAY;IAEnD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAsB;IAE9D,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAQ5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IASxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;;OAGG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAMlE"}

package/dist/adapters/java-adapter.js

@@ -21,6 +21,8 @@ export class JavaLanguageAdapter {
         const analyzer = TreeSitterAnalyzer.getInstance();
         return analyzer.analyze(filePath, 'java', {
             includePrivate: options?.includePrivate,
+            // Feature 154 — 透传 extractCallSites flag（与 python-adapter.ts 对齐，CL-05 默认 false）
+            extractCallSites: options?.extractCallSites,
         });
     }
     /**

package/dist/adapters/java-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"java-adapter.js","sourceRoot":"","sources":["../../src/adapters/java-adapter.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAGnF,MAAM,OAAO,mBAAmB;IACrB,EAAE,GAAG,MAAM,CAAC;IAEZ,SAAS,GAAwB,CAAC,MAAM,CAAC,CAAC;IAE1C,UAAU,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAErD,iBAAiB,GAAwB,IAAI,GAAG,CAAC;QACxD,QAAQ,EAAI,QAAQ;QACpB,OAAO,EAAK,SAAS;QACrB,KAAK,EAAO,gBAAgB;QAC5B,SAAS,EAAG,YAAY;QACxB,OAAO,EAAK,cAAc;QAC1B,WAAW,EAAE,aAAa;QAC1B,MAAM,EAAM,gBAAgB;KAC7B,CAAC,CAAC;IAEH;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,OAA4B;QAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC;QAClD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE;YACxC,cAAc,EAAE,OAAO,EAAE,cAAc;SACxC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO;YACL,iBAAiB,EAAE,MAAM;YACzB,aAAa,EAAE,+BAA+B;YAC9C,aAAa,EAAE,gCAAgC;YAC/C,qBAAqB,EAAE,mBAAmB;YAC1C,gBAAgB,EAAE,yDAAyD;YAC3E,YAAY,EAAE,sCAAsC;SACrD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO;YACL,WAAW,EAAE,sCAAsC;YACnD,QAAQ,EAAE,CAAC,eAAe,CAAC;SAC5B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,6BAA6B,CAAC,QAAQ,EAAE;YAC7C,WAAW,EAAE,MAAM;YACnB,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"java-adapter.js","sourceRoot":"","sources":["../../src/adapters/java-adapter.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAGnF,MAAM,OAAO,mBAAmB;IACrB,EAAE,GAAG,MAAM,CAAC;IAEZ,SAAS,GAAwB,CAAC,MAAM,CAAC,CAAC;IAE1C,UAAU,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAErD,iBAAiB,GAAwB,IAAI,GAAG,CAAC;QACxD,QAAQ,EAAI,QAAQ;QACpB,OAAO,EAAK,SAAS;QACrB,KAAK,EAAO,gBAAgB;QAC5B,SAAS,EAAG,YAAY;QACxB,OAAO,EAAK,cAAc;QAC1B,WAAW,EAAE,aAAa;QAC1B,MAAM,EAAM,gBAAgB;KAC7B,CAAC,CAAC;IAEH;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,OAA4B;QAE5B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC;QAClD,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE;YACxC,cAAc,EAAE,OAAO,EAAE,cAAc;YACvC,gFAAgF;YAChF,gBAAgB,EAAE,OAAO,EAAE,gBAAgB;SAC5C,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO;YACL,iBAAiB,EAAE,MAAM;YACzB,aAAa,EAAE,+BAA+B;YAC9C,aAAa,EAAE,gCAAgC;YAC/C,qBAAqB,EAAE,mBAAmB;YAC1C,gBAAgB,EAAE,yDAAyD;YAC3E,YAAY,EAAE,sCAAsC;SACrD,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO;YACL,WAAW,EAAE,sCAAsC;YACnD,QAAQ,EAAE,CAAC,eAAe,CAAC;SAC5B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,QAAgB;QACpC,OAAO,6BAA6B,CAAC,QAAQ,EAAE;YAC7C,WAAW,EAAE,MAAM;YACnB,gBAAgB,EAAE,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/adapters/language-adapter.d.ts

@@ -1,11 +1,15 @@
 /**
  * 语言适配器接口定义
  * 定义一种编程语言支持所需的全部能力契约：文件分析、降级分析、
- * 依赖图构建（可选）、术语映射、测试文件模式。
+ * 模块图构建（可选）、术语映射、测试文件模式。
+ *
+ * Feature 156 W1.4：模块图统一使用 ModuleGraph
+ * （UnifiedGraph 派生视图，src/knowledge-graph/module-derivation.ts）。
  */
 import type { CodeSkeleton, Language } from '../models/code-skeleton.js';
-import type { DependencyGraph } from '../models/dependency-graph.js';
+import type { ModuleGraph } from '../knowledge-graph/module-derivation.js';
 import type { CommentRegion } from '../debt-scanner/types.js';
+import type { TsConfigResolutionContext } from '../core/import-resolver.js';
 export type { CommentRegion };
 /**
  * 文件分析选项
@@ -15,11 +19,37 @@ export interface AnalyzeFileOptions {
     includePrivate?: boolean;
     /** 类继承层级最大解析深度（默认 5） */
     maxDepth?: number;
+    /**
+     * 抽取函数调用点（Feature 151 + CL-05），默认 false。
+     *
+     * 设计动机：抽 callSites 会增加 AST 遍历开销（NFR-1 性能），
+     * spec drift check / 单文件分析等无 graph 需求的场景不需要 callSites，保持默认 false。
+     * panoramic 流水线（batch-orchestrator / batch-project-docs / coverage-auditor）
+     * 必须显式传 true 才能让 graph.json 含 calls 边。
+     */
+    extractCallSites?: boolean;
+    /**
+     * 项目根目录绝对路径（Feature 156 W1.0 新增，FR-28）。
+     *
+     * 用于 import-resolver 解析 tsconfig path alias 与跨包相对路径。
+     * 缺失时仍可解析相对路径（fallback 用 path.dirname(filePath) 作 base），
+     * 但 alias 会失效。
+     */
+    projectRoot?: string;
+    /**
+     * tsconfig 解析上下文（Feature 181 收口：统一替代历史 pathAliases + baseUrl 双字段）。
+     *
+     * 由 import-resolver.findNearestTsConfig + buildTsConfigContext 生成，承载
+     * tsconfig.compilerOptions 的 baseUrl + paths（含 extends 链），交由
+     * 单一权威 import-resolver.resolveTsJsImport 解析 alias / baseUrl。
+     * 缺失时仍可解析相对路径，但 alias / baseUrl 会失效。
+     */
+    tsConfigContext?: TsConfigResolutionContext | null;
 }
 /**
- * 依赖图构建选项
+ * 模块图构建选项（W1.4：ModuleGraphOptions）
  */
-export interface DependencyGraphOptions {
+export interface ModuleGraphOptions {
     /** 用于过滤分析文件的 Glob 模式 */
     includeOnly?: string;
     /** 排除模式 */
@@ -59,7 +89,7 @@ export interface TestPatterns {
 /**
  * 语言适配器接口
  * 定义一种编程语言支持所需的全部能力：文件分析、降级分析、
- * 依赖图构建（可选）、术语映射、测试文件模式。
+ * 模块图构建（可选）、术语映射、测试文件模式。
  */
 export interface LanguageAdapter {
     /** 适配器唯一标识（如 'ts-js', 'python', 'go'） */
@@ -94,14 +124,17 @@ export interface LanguageAdapter {
      */
     analyzeFallback(filePath: string): Promise<CodeSkeleton>;
     /**
-     * 构建项目级依赖图（可选能力）
-     * 并非所有语言在初始阶段都需要依赖图支持。
+     * 构建项目级模块图（可选能力）
+     * 并非所有语言在初始阶段都需要模块图支持。
+     *
+     * Feature 156 W1.4：所有实现内部统一走 buildUnifiedGraph + deriveModuleGraph
+     * 派生路径，不再依赖 dependency-cruiser 等外部工具。
      *
      * @param projectRoot - 项目根目录
      * @param options - 构建选项（可选）
-     * @returns DependencyGraph
+     * @returns ModuleGraph（UnifiedGraph 派生视图）
      */
-    buildDependencyGraph?(projectRoot: string, options?: DependencyGraphOptions): Promise<DependencyGraph>;
+    buildModuleGraph?(projectRoot: string, options?: ModuleGraphOptions): Promise<ModuleGraph>;
     /**
      * 返回该语言的术语映射
      * 用于 LLM prompt 的语言参数化。

package/dist/adapters/language-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"language-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/language-adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,YAAY,EAAE,aAAa,EAAE,CAAC;AAM9B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa;IACb,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnF;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,oBAAoB,CAAC,CACnB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5B;;;OAGG;IACH,cAAc,IAAI,mBAAmB,CAAC;IAEtC;;;OAGG;IACH,eAAe,IAAI,YAAY,CAAC;IAEhC;;;;;;;;;OASG;IACH,eAAe,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAC9D"}
+{"version":3,"file":"language-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/language-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E,YAAY,EAAE,aAAa,EAAE,CAAC;AAM9B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa;IACb,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAMD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnF;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB;;;OAGG;IACH,cAAc,IAAI,mBAAmB,CAAC;IAEtC;;;OAGG;IACH,eAAe,IAAI,YAAY,CAAC;IAEhC;;;;;;;;;OASG;IACH,eAAe,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAC9D"}

package/dist/adapters/python-adapter.d.ts

@@ -1,7 +1,7 @@
 import type { CodeSkeleton, Language } from '../models/code-skeleton.js';
 import type { ExtractionResult } from '../extraction/extraction-types.js';
-import type { LanguageAdapter, AnalyzeFileOptions, DependencyGraphOptions, LanguageTerminology, TestPatterns } from './language-adapter.js';
-import type { DependencyGraph } from '../models/dependency-graph.js';
+import type { LanguageAdapter, AnalyzeFileOptions, ModuleGraphOptions, LanguageTerminology, TestPatterns } from './language-adapter.js';
+import type { ModuleGraph } from '../knowledge-graph/module-derivation.js';
 import type { CommentRegion } from '../debt-scanner/types.js';
 export declare class PythonLanguageAdapter implements LanguageAdapter {
     readonly id = "python";
@@ -35,7 +35,7 @@ export declare class PythonLanguageAdapter implements LanguageAdapter {
      * 递归扫描项目根目录下所有 `.py` 文件，排除语言生态常见忽略目录。
      *
      * 复用 `defaultIgnoreDirs` 并叠加 Python 项目惯例（test/tests/dist 等）。
-     * 由 `extractSymbolNodes` 与 `buildDependencyGraph` 共用，避免 DRY 违反。
+     * 由 `extractSymbolNodes` 与 `buildModuleGraph` 共用，避免 DRY 违反。
      *
      * @throws 当根目录不可读时抛出（调用方按需 try-catch 决定是否吞掉）
      */
@@ -53,9 +53,37 @@ export declare class PythonLanguageAdapter implements LanguageAdapter {
      */
     extractSymbolNodes(projectRoot: string): Promise<ExtractionResult[]>;
     /**
-     * 构建 Python 项目的模块依赖图
-     * 扫描所有 .py 文件，解析 import 语句，仅对本地模块构建有向边
+     * 构建 Python 项目的模块图（Feature 156 W1.4：UnifiedGraph 派生路径）
+     *
+     * 流程：
+     * 1. 递归扫描所有 .py 文件，排除语言生态忽略目录
+     * 2. 解析 Python import → 相对路径（包含 dot-relative + namedImports 展开）
+     * 3. 把推断到的 resolvedPath 写回 CodeSkeleton.imports[i]
+     * 4. buildModuleGraphFromCodeSkeletons 一站式派生
+     *
+     * Python import 解析规则：
+     * - 绝对模块（`import foo` / `from foo import x`）：用 basename map（EC-6 简化策略）
+     * - 单点相对（`from . import utils` / `from . import a, b`）：
+     *   * 当 moduleSpecifier === '.'：把每个 namedImport 名字 N 当作候选模块，
+     *     在当前包目录尝试解析 ./N.py 或 ./N/__init__.py
+     *   * 多个 named import 都命中时，取第一个命中的（resolvedPath 是单值字段）；
+     * - 双点相对（`from .. import x`）：同理，往上一级查
+     * - 带模块名相对（`from .nn import Module`）：解析 `.nn` 子模块
+     */
+    buildModuleGraph(projectRoot: string, _options?: ModuleGraphOptions): Promise<ModuleGraph>;
+    /**
+     * 解析单条 Python ImportReference 为 0..N 条带 resolvedPath 的 ImportReference。
+     *
+     * CRIT-4 v2：处理 dot-relative + namedImports 展开。当 specifier 为纯点号（'.'/'..'）时，
+     * 把 namedImports 每个名字 N 展开为候选 specifier `.N` / `..N`，用相对路径解析每个候选；
+     * 任一命中即派生一条 edge（resolvedPath 写回）。
+     *
+     * 返回 ImportReference 数组：
+     *  - 命中 0 个候选：返回原 imp（不带 resolvedPath，下游 deriveImportEdges 跳过）
+     *  - 命中 1 个：返回单元素数组（imp + resolvedPath）
+     *  - 命中 N 个（仅 dot-relative + multi-named 才会发生）：返回 N 元素数组，
+     *    每个元素是同一 imp 的副本但 resolvedPath 各异 + namedImports 收窄到对应名字
      */
-    buildDependencyGraph(projectRoot: string, _options?: DependencyGraphOptions): Promise<DependencyGraph>;
+    private resolvePythonImport;
 }
 //# sourceMappingURL=python-adapter.d.ts.map

package/dist/adapters/python-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"python-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/python-adapter.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,+BAA+B,CAAC;AAIhG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,QAAQ,CAAC,EAAE,YAAY;IAEvB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAc;IAErD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAA4B;IAEpE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAQ5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAOxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAOjE;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAqBnB;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA8E1E;;;OAGG;IACG,oBAAoB,CACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,sBAAsB,GAChC,OAAO,CAAC,eAAe,CAAC;CA2E5B"}
+{"version":3,"file":"python-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/python-adapter.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAmB,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAI3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAI9D,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,QAAQ,CAAC,EAAE,YAAY;IAEvB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAc;IAErD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAA4B;IAEpE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAQ5C;IAEH;;OAEG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC;IASxB;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI9D;;OAEG;IACH,cAAc,IAAI,mBAAmB;IAWrC;;OAEG;IACH,eAAe,IAAI,YAAY;IAO/B;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAOjE;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IA6BnB;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA8E1E;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,OAAO,CAAC,WAAW,CAAC;IA6EvB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;CAyE5B"}

package/dist/adapters/python-adapter.js

@@ -11,6 +11,8 @@ import * as fs from 'node:fs';
 import { TreeSitterAnalyzer } from '../core/tree-sitter-analyzer.js';
 import { analyzeFallback as treeSitterFallback } from '../core/tree-sitter-fallback.js';
 import { extractCommentsWithTreeSitter } from './tree-sitter-comment-extractor.js';
+import { buildModuleGraphFromCodeSkeletons } from '../knowledge-graph/module-derivation.js';
+import { createGitignoreFilter } from '../utils/file-scanner.js';
 export class PythonLanguageAdapter {
     id = 'python';
     languages = ['python'];
@@ -31,6 +33,8 @@ export class PythonLanguageAdapter {
         const analyzer = TreeSitterAnalyzer.getInstance();
         return analyzer.analyze(filePath, 'python', {
             includePrivate: options?.includePrivate,
+            // Feature 151 — 透传 extractCallSites flag（CL-05 默认 false）
+            extractCallSites: options?.extractCallSites,
         });
     }
     /**
@@ -77,7 +81,7 @@ export class PythonLanguageAdapter {
      * 递归扫描项目根目录下所有 `.py` 文件，排除语言生态常见忽略目录。
      *
      * 复用 `defaultIgnoreDirs` 并叠加 Python 项目惯例（test/tests/dist 等）。
-     * 由 `extractSymbolNodes` 与 `buildDependencyGraph` 共用，避免 DRY 违反。
+     * 由 `extractSymbolNodes` 与 `buildModuleGraph` 共用，避免 DRY 违反。
      *
      * @throws 当根目录不可读时抛出（调用方按需 try-catch 决定是否吞掉）
      */
@@ -86,16 +90,24 @@ export class PythonLanguageAdapter {
             ...this.defaultIgnoreDirs,
             'test', 'tests', 'dist', 'node_modules', '.git',
         ]);
+        // F194：叠加 .gitignore 过滤层（只叠加不替换硬编码集）。
+        // 基准 = resolvedRoot（与 file-scanner walkDir 的 path.relative(baseDir, fullPath) 同口径，不做 sep 转换）。
+        const isGitignored = createGitignoreFilter(resolvedRoot);
         const pyFiles = [];
         function walk(dir) {
             for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const relPath = path.relative(resolvedRoot, path.join(dir, entry.name));
                 if (entry.isDirectory()) {
-                    if (!ignoreNames.has(entry.name) && !entry.name.startsWith('.')) {
+                    // 目录命中 .gitignore 则剪枝（保留硬编码集与点前缀剪枝不变）
+                    if (!ignoreNames.has(entry.name) && !entry.name.startsWith('.') && !isGitignored(relPath)) {
                         walk(path.join(dir, entry.name));
                     }
                 }
                 else if (entry.isFile() && entry.name.endsWith('.py')) {
-                    pyFiles.push(path.join(dir, entry.name));
+                    // 文件命中 .gitignore 则跳过
+                    if (!isGitignored(relPath)) {
+                        pyFiles.push(path.join(dir, entry.name));
+                    }
                 }
             }
         }
@@ -185,76 +197,171 @@ export class PythonLanguageAdapter {
         return results;
     }
     /**
-     * 构建 Python 项目的模块依赖图
-     * 扫描所有 .py 文件，解析 import 语句，仅对本地模块构建有向边
+     * 构建 Python 项目的模块图（Feature 156 W1.4：UnifiedGraph 派生路径）
+     *
+     * 流程：
+     * 1. 递归扫描所有 .py 文件，排除语言生态忽略目录
+     * 2. 解析 Python import → 相对路径（包含 dot-relative + namedImports 展开）
+     * 3. 把推断到的 resolvedPath 写回 CodeSkeleton.imports[i]
+     * 4. buildModuleGraphFromCodeSkeletons 一站式派生
+     *
+     * Python import 解析规则：
+     * - 绝对模块（`import foo` / `from foo import x`）：用 basename map（EC-6 简化策略）
+     * - 单点相对（`from . import utils` / `from . import a, b`）：
+     *   * 当 moduleSpecifier === '.'：把每个 namedImport 名字 N 当作候选模块，
+     *     在当前包目录尝试解析 ./N.py 或 ./N/__init__.py
+     *   * 多个 named import 都命中时，取第一个命中的（resolvedPath 是单值字段）；
+     * - 双点相对（`from .. import x`）：同理，往上一级查
+     * - 带模块名相对（`from .nn import Module`）：解析 `.nn` 子模块
      */
-    async buildDependencyGraph(projectRoot, _options) {
+    async buildModuleGraph(projectRoot, _options) {
         const resolvedRoot = path.resolve(projectRoot);
-        // 递归扫描所有 .py 文件，排除语言生态常见忽略目录
+        // 递归扫描所有 .py 文件
         const pyFiles = this.scanPyFiles(resolvedRoot);
-        // 构建模块名 → 绝对路径映射（basename 不含扩展名）
+        // 构建模块名 → 相对路径映射（绝对 import 用）
         const pyModuleMap = new Map();
-        for (const f of pyFiles) {
-            pyModuleMap.set(path.basename(f, '.py'), f);
+        const relPyFiles = [];
+        const relPySet = new Set();
+        for (const absF of pyFiles) {
+            const rel = path.relative(resolvedRoot, absF).split(path.sep).join('/');
+            relPyFiles.push(rel);
+            relPySet.add(rel);
+            pyModuleMap.set(path.basename(absF, '.py'), rel);
         }
-        const nodeSet = new Set();
-        const rawEdges = [];
-        for (const filePath of pyFiles) {
+        // 收集 CodeSkeleton（含推断的 resolvedPath），喂给 buildGraphFromCodeSkeletons
+        const codeSkeletons = new Map();
+        for (const absPath of pyFiles) {
+            const relFrom = path.relative(resolvedRoot, absPath).split(path.sep).join('/');
             try {
-                const skeleton = await this.analyzeFile(filePath);
-                const relFrom = path.relative(resolvedRoot, filePath);
-                nodeSet.add(relFrom);
-                for (const imp of skeleton.imports) {
-                    // 取模块路径的顶层包名（如 parser.submodule → parser）
-                    const topModule = imp.moduleSpecifier.replace(/^\.+/, '').split('.')[0];
-                    if (!topModule)
-                        continue;
-                    const resolvedPath = pyModuleMap.get(topModule);
-                    if (resolvedPath) {
-                        const relTo = path.relative(resolvedRoot, resolvedPath);
-                        nodeSet.add(relTo);
-                        rawEdges.push({ from: relFrom, to: relTo });
-                    }
-                }
+                const skeleton = await this.analyzeFile(absPath);
+                const newImports = skeleton.imports.flatMap((imp) => this.resolvePythonImport(imp, relFrom, relPySet, pyModuleMap));
+                codeSkeletons.set(relFrom, {
+                    ...skeleton,
+                    filePath: relFrom,
+                    imports: newImports,
+                });
             }
             catch {
-                // 单文件解析失败不影响整体依赖图构建
+                // WARN-2 修订：解析失败时不注入空 skeleton（loc:1 占位会污染 module 节点 + 跨语言统计）。
+                // 改为在 metadata 标 parseError，buildGraphFromCodeSkeletons 之前过滤掉。
+                // 仍保留 module 节点的最小占位（让 graph 可见该文件存在），但 imports/exports 必为空。
+                codeSkeletons.set(relFrom, {
+                    filePath: relFrom,
+                    language: 'python',
+                    loc: 0,
+                    exports: [],
+                    imports: [],
+                    hash: '0'.repeat(64),
+                    analyzedAt: new Date().toISOString(),
+                    parserUsed: 'tree-sitter',
+                    metadata: { parseError: true },
+                });
             }
         }
-        const edges = rawEdges.map(e => ({
-            from: e.from,
-            to: e.to,
-            isCircular: false,
-            importType: 'static',
-        }));
-        // O(n) 单次遍历计算度数（避免 O(n·m) 的 3 次数组遍历）
-        const inDegreeMap = new Map();
-        const outDegreeMap = new Map();
-        const connectedNodes = new Set();
-        for (const e of rawEdges) {
-            inDegreeMap.set(e.to, (inDegreeMap.get(e.to) ?? 0) + 1);
-            outDegreeMap.set(e.from, (outDegreeMap.get(e.from) ?? 0) + 1);
-            connectedNodes.add(e.from);
-            connectedNodes.add(e.to);
+        // 兜底：scan 到的文件但 codeSkeletons 漏掉的（不应该发生），补一个空骨架
+        for (const rel of relPyFiles) {
+            if (!codeSkeletons.has(rel)) {
+                codeSkeletons.set(rel, {
+                    filePath: rel,
+                    language: 'python',
+                    loc: 1,
+                    exports: [],
+                    imports: [],
+                    hash: '0'.repeat(64),
+                    analyzedAt: new Date().toISOString(),
+                    parserUsed: 'tree-sitter',
+                });
+            }
         }
-        const modules = [...nodeSet].map(source => ({
-            source,
-            isOrphan: !connectedNodes.has(source),
-            inDegree: inDegreeMap.get(source) ?? 0,
-            outDegree: outDegreeMap.get(source) ?? 0,
-            level: 0,
-        }));
-        return {
-            projectRoot: resolvedRoot,
-            modules,
-            edges,
-            topologicalOrder: modules.map(m => m.source),
-            sccs: [],
-            totalModules: modules.length,
-            totalEdges: edges.length,
-            analyzedAt: new Date().toISOString(),
-            mermaidSource: '',
+        // WARN-2：过滤掉 parseError 的 skeleton 不让它进 buildUnifiedGraph 派生 module 节点
+        // —— 但保留一条诊断日志会更好；当前为 silent 跳过（与现有 stderr noise budget 一致）。
+        const cleanSkeletons = new Map();
+        for (const [k, sk] of codeSkeletons) {
+            const md = sk.metadata;
+            if (md?.parseError)
+                continue;
+            cleanSkeletons.set(k, sk);
+        }
+        return buildModuleGraphFromCodeSkeletons(cleanSkeletons, resolvedRoot, 'python');
+    }
+    /**
+     * 解析单条 Python ImportReference 为 0..N 条带 resolvedPath 的 ImportReference。
+     *
+     * CRIT-4 v2：处理 dot-relative + namedImports 展开。当 specifier 为纯点号（'.'/'..'）时，
+     * 把 namedImports 每个名字 N 展开为候选 specifier `.N` / `..N`，用相对路径解析每个候选；
+     * 任一命中即派生一条 edge（resolvedPath 写回）。
+     *
+     * 返回 ImportReference 数组：
+     *  - 命中 0 个候选：返回原 imp（不带 resolvedPath，下游 deriveImportEdges 跳过）
+     *  - 命中 1 个：返回单元素数组（imp + resolvedPath）
+     *  - 命中 N 个（仅 dot-relative + multi-named 才会发生）：返回 N 元素数组，
+     *    每个元素是同一 imp 的副本但 resolvedPath 各异 + namedImports 收窄到对应名字
+     */
+    resolvePythonImport(imp, fromRel, relPySet, pyModuleMap) {
+        const spec = imp.moduleSpecifier;
+        const fromDir = path.dirname(fromRel);
+        // 工具函数：从一个目录起始，解析 "moduleSegment[/subSegment...]" 为实际 .py 文件
+        // 返回相对项目根的路径，未命中返回 null
+        const tryResolveAtDir = (baseDir, segments) => {
+            const joinedSegs = segments.join('/');
+            const candidates = [
+                `${baseDir}/${joinedSegs}.py`,
+                `${baseDir}/${joinedSegs}/__init__.py`,
+            ];
+            for (const c of candidates) {
+                // path.normalize 处理 './a/../b' 这类
+                const norm = path.posix.normalize(c.startsWith('/') ? c : `./${c}`).replace(/^\.\//, '');
+                if (relPySet.has(norm))
+                    return norm;
+            }
+            return null;
         };
+        // Case A: 纯点号 specifier（'.', '..'）—— 必须靠 namedImports 展开
+        if (/^\.+$/.test(spec)) {
+            const dots = spec.length;
+            // dots=1: 当前包；dots=2: 父包；以此类推
+            let baseDir = fromDir;
+            for (let i = 1; i < dots; i++) {
+                baseDir = path.dirname(baseDir) === '.' ? '' : path.dirname(baseDir);
+            }
+            // 如果没有 namedImports，无法展开 → 保留原 imp
+            const named = imp.namedImports ?? [];
+            if (named.length === 0)
+                return [imp];
+            const out = [];
+            for (const name of named) {
+                const resolved = tryResolveAtDir(baseDir || '.', [name]);
+                if (resolved && resolved !== fromRel) {
+                    out.push({ ...imp, resolvedPath: resolved, namedImports: [name] });
+                }
+            }
+            return out.length > 0 ? out : [imp];
+        }
+        // Case B: dot-relative + 模块名（'.foo' / '..foo.bar'）
+        const dotRelMatch = /^(\.+)(.*)$/.exec(spec);
+        if (dotRelMatch && dotRelMatch[1].length >= 1 && dotRelMatch[2].length > 0) {
+            const dots = dotRelMatch[1].length;
+            const tail = dotRelMatch[2];
+            let baseDir = fromDir;
+            for (let i = 1; i < dots; i++) {
+                baseDir = path.dirname(baseDir) === '.' ? '' : path.dirname(baseDir);
+            }
+            const segs = tail.split('.');
+            const resolved = tryResolveAtDir(baseDir || '.', segs);
+            if (resolved && resolved !== fromRel) {
+                return [{ ...imp, resolvedPath: resolved }];
+            }
+            return [imp];
+        }
+        // Case C: 绝对 import — 用 basename map（保留原简化策略，EC-6 留给后续 Feature）
+        const topModule = spec.split('.')[0];
+        if (!topModule)
+            return [imp];
+        const resolvedRel = pyModuleMap.get(topModule);
+        if (resolvedRel && resolvedRel !== fromRel) {
+            return [{ ...imp, resolvedPath: resolvedRel }];
+        }
+        return [imp];
     }
 }
 //# sourceMappingURL=python-adapter.js.map