@mycodemap/mycodemap 0.4.2 → 0.5.1

package/docs/archive/test_scenario_3_impact_analysis_report.md

@@ -0,0 +1,520 @@
+# 测试场景3：影响范围分析对比测试报告
+
+## 测试概述
+
+**测试目标**: 对比 CodeMap `impact` 命令与手动 `grep` 分析文件变更影响范围的差异
+
+**测试时间**: 2025年3月2日  
+**测试目录**: `/data/codemap`  
+**CodeMap版本**: 本地构建版本
+
+---
+
+## 测试用例 1: src/core/analyzer.ts 影响分析
+
+### 测试目的
+分析核心分析器文件的变更影响范围，对比 CodeMap 的依赖图分析与手动 grep 文本搜索的差异。
+
+### CodeMap 执行 (直接依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts
+```
+
+**执行时间**: 0.539s (real)
+
+**输出**:
+```
+📍 影响分析
+──────────────────────────────────────────────────
+
+目标文件:
+   src/core/analyzer.ts
+   导出: analyze
+
+⬇️  直接依赖该文件的模块 (13):
+   • src/orchestrator/ai-feed-generator.ts
+   • src/orchestrator/result-fusion.ts
+   • src/watcher/watch-worker.ts
+   • src/core/__tests__/analyzer.test.ts
+   • src/cli/__tests__/generate.test.ts
+   • src/cli/commands/ci.ts
+   • src/cli/commands/generate.ts
+   • src/cli/commands/watch-foreground.ts
+   • src/orchestrator/__tests__/ai-feed-generator.test.ts
+   • src/orchestrator/__tests__/git-analyzer.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+   • src/plugins/__tests__/complexity-analyzer.test.ts
+   • src/cli/commands/__tests__/watch-foreground.test.ts
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 13 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts --transitive
+```
+
+**执行时间**: 0.698s (real)
+
+**输出**:
+```
+直接依赖该文件的模块 (13):
+   [同上]
+
+🌐 传递依赖 (66):
+       └─► src/cli/index.ts [距离: 3]
+         └─► src/ai/claude.ts [距离: 4]
+         └─► src/ai/codex.ts [距离: 4]
+         ... 还有 46 个
+
+直接影响: 13 个模块
+传递影响: 66 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "analyzer|Analyzer" src/ | head -20
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/__tests__/generate.test.ts
+src/cli/commands/__tests__/generate.test.ts
+src/cli/commands/__tests__/watch-foreground.test.ts
+src/plugins/built-in/complexity-analyzer.ts
+src/cli/commands/watch-foreground.ts
+src/core/__tests__/analyzer.test.ts
+src/cli/commands/ci.ts
+src/core/analyzer.ts
+src/cli/commands/generate.ts
+src/plugins/__tests__/complexity-analyzer.test.ts
+src/plugins/index.ts
+src/plugins/plugin-loader.ts
+src/index.ts
+src/orchestrator/ai-feed-generator.ts
+src/orchestrator/index.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/__tests__/git-analyzer.test.ts
+src/orchestrator/__tests__/ai-feed-generator.test.ts
+```
+
+**匹配文件总数**: 22 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.54s | 0.70s | 0.01s | Grep 更快 (54-70x) |
+| **直接依赖数** | 13 | 13 | 22 | Grep 包含大量误报 |
+| **传递依赖数** | 未显示 | 66 | N/A | CodeMap 独有功能 |
+| **依赖深度** | ❌ | ✅ (显示距离) | ❌ | CodeMap 传递模式优势 |
+| **风险评估** | ✅ 极高风险 | ✅ 极高风险 | ❌ | CodeMap 独有功能 |
+| **导出信息** | ✅ | ✅ | ❌ | CodeMap 独有功能 |
+| **误报率** | 低 | 低 | 高 (40%) | CodeMap 更准确 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖"**:
+```
+src/cli/commands/__tests__/generate.test.ts  (不包含 analyzer 导入)
+src/core/analyzer.ts                          (文件自身)
+src/index.ts                                  ✅ 应该被检测！
+src/orchestrator/git-analyzer.ts              (独立模块，非依赖)
+src/orchestrator/index.ts                     (通过 git-analyzer 导入)
+src/plugins/built-in/complexity-analyzer.ts   (独立模块)
+src/plugins/index.ts                          (通过 complexity-analyzer 导入)
+src/plugins/plugin-loader.ts                  (通过 complexity-analyzer 导入)
+```
+
+**关键发现**: 
+- `src/index.ts` 确实导出了 `analyze` 函数 (`export { analyze } from './core/analyzer.js'`)，但 CodeMap 未检测到这是 analyzer.ts 的依赖
+- Grep 找到的 22 个文件中，约 9 个是误报（文件名含 analyzer 但实际不依赖 core/analyzer.ts）
+- CodeMap 的 13 个直接依赖都是准确的导入关系
+
+---
+
+## 测试用例 2: src/types/index.ts 影响分析
+
+### 测试目的
+分析类型定义文件的变更影响，类型文件通常有大量依赖关系。
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/types/index.ts --transitive
+```
+
+**执行时间**: 0.858s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/types/index.ts
+   导出: SymbolKind, SourceLocation, DecoratorInfo, ... (38 个类型)
+
+⬇️  直接依赖该文件的模块 (38):
+   • src/ai/claude.ts
+   • src/ai/codex.ts
+   • src/ai/provider.ts
+   • src/ai/subagent-caller.ts
+   • src/core/analyzer.ts
+   • src/core/global-index.ts
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/generator/ai-overview.ts
+   • src/generator/context.ts
+   • ... (共38个)
+
+🌐 传递依赖 (41):
+     └─► src/ai/factory.ts [距离: 2]
+     └─► src/ai/index.ts [距离: 2]
+             └─► src/cli/index.ts [距离: 6]
+             └─► ...
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 38 个模块
+   传递影响: 41 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "from.*types/index|from.*types" src/
+```
+
+**执行时间**: 0.009s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/commands/complexity.ts
+src/cli/commands/analyze.ts
+src/cli/commands/watch-foreground.ts
+src/cli/commands/impact.ts
+src/cli/commands/cycles.ts
+src/cli/commands/ci.ts
+src/cli/commands/generate.ts
+src/cli/commands/deps.ts
+src/cli/commands/workflow.ts
+src/cli/commands/query.ts
+src/worker/index.ts
+src/ai/claude.ts
+src/ai/subagent-caller.ts
+src/ai/provider.ts
+src/ai/codex.ts
+src/ai/index.ts
+... (共66个文件)
+```
+
+**匹配文件总数**: 66 个
+
+### 对比分析
+
+| 维度 | CodeMap | Grep | 结论 |
+|------|---------|------|------|
+| **执行时间** | 0.86s | 0.009s | Grep 快 95x |
+| **匹配文件数** | 38 | 66 | 差异 28 个文件 |
+| **误报/漏报** | 可能遗漏 | 包含非 types/index.ts 导入 | 各有优劣 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖" (28 个)**:
+```
+src/ai/index.ts
+src/cli/commands/analyze.ts
+src/cli/commands/ci.ts
+src/cli/commands/workflow.ts
+src/index.ts
+src/orchestrator/adapters/ast-grep-adapter.ts
+src/orchestrator/adapters/base-adapter.ts
+src/orchestrator/adapters/codemap-adapter.ts
+src/orchestrator/confidence.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/index.ts
+src/orchestrator/integration/pipeline.test.ts
+src/orchestrator/intent-router.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/tool-orchestrator.ts
+src/orchestrator/workflow/phase-checkpoint.ts
+src/orchestrator/workflow/types.ts
+src/orchestrator/workflow/workflow-context.ts
+src/orchestrator/workflow/workflow-orchestrator.ts
+... (共28个)
+```
+
+**原因分析**:
+这些文件通过 `src/orchestrator/types.ts` 间接使用类型，而非直接从 `src/types/index.ts` 导入。例如:
+```typescript
+// src/orchestrator/result-fusion.ts
+import type { UnifiedResult, HeatScore } from './types.js';  // 不是 types/index.js
+```
+
+而 `src/orchestrator/types.ts` 自身又从 `src/types/index.ts` 导入，形成间接依赖。
+
+**结论**: 
+- CodeMap 准确识别**直接**依赖 (38个)
+- Grep 捕获了**间接**依赖模式，但也包含了一些误报 (通过 `orchestrator/types` 而非 `types/index`)
+- CodeMap 传递依赖模式 (41个) 补充了间接依赖，总计 79 个影响模块
+
+---
+
+## 测试用例 3: src/cache/lru-cache.ts 影响分析
+
+### 测试目的
+分析具体工具类文件的变更影响，评估叶节点文件的依赖分析。
+
+### CodeMap 执行
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts
+```
+
+**执行时间**: 0.800s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/cache/lru-cache.ts
+   导出: LRUCache, LRUCacheWithTTL
+
+⬇️  直接依赖该文件的模块 (4):
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/cache/__tests__/lru-cache.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+
+⚠️  风险评估:
+   ⚠️  高风险 - 该文件被多个模块依赖，修改需谨慎
+   直接影响: 4 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts --transitive
+```
+
+**传递依赖**: 76 个模块
+
+### 传统工具执行
+
+```bash
+rg -l "lru-cache|LRUCache" src/
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/cache/__tests__/lru-cache.test.ts
+src/cache/parse-cache.ts
+src/cache/lru-cache.ts
+src/cache/index.ts
+src/orchestrator/test-linker.ts
+```
+
+**匹配文件总数**: 5 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.80s | ~1.0s | 0.01s | Grep 快 80-100x |
+| **直接依赖数** | 4 | 4 | 5 | Grep 多1个 |
+| **传递依赖数** | 未显示 | 76 | N/A | CodeMap 独有功能 |
+| **风险评估** | ✅ 高风险 | ✅ 高风险 | ❌ | CodeMap 独有 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的**:
+```
+src/orchestrator/test-linker.ts  (仅作为字符串示例提及，无实际导入)
+```
+
+这是一个**误报**: `test-linker.ts` 只是在注释中提到 `lru-cache.test.ts` 作为示例:
+```typescript
+* lru-cache.test.ts → lru-cache.ts
+```
+
+CodeMap 正确地识别了这一点，没有将其列为依赖。
+
+---
+
+## 综合对比分析
+
+### 1. 直接依赖识别
+
+| 测试文件 | CodeMap 直接依赖 | Grep 匹配数 | CodeMap 准确率 | Grep 准确率 |
+|---------|-----------------|------------|----------------|-------------|
+| analyzer.ts | 13 | 22 | 100% | ~41% |
+| types/index.ts | 38 | 66 | 100% | ~58% |
+| lru-cache.ts | 4 | 5 | 100% | ~80% |
+
+**结论**: CodeMap 在直接依赖识别上具有**更高的准确性**，几乎没有误报。
+
+### 2. 传递依赖识别
+
+| 测试文件 | CodeMap 传递依赖 | 手动分析可行性 | 优势 |
+|---------|-----------------|---------------|------|
+| analyzer.ts | 66 | 困难 | 揭示深层影响 |
+| types/index.ts | 41 | 困难 | 跨层级追踪 |
+| lru-cache.ts | 76 | 几乎不可能 | 揭示广泛影响 |
+
+**结论**: CodeMap 的传递依赖分析是**独有功能**，手动几乎无法完成同等分析。
+
+### 3. 风险评估准确性
+
+CodeMap 风险评估分级:
+- 🔴 极高风险: > 20 个直接依赖 (如 types/index.ts: 38个)
+- ⚠️ 高风险: 5-20 个直接依赖
+- ⚠️ 中风险: 1-4 个直接依赖 (如 cycles.ts: 2个)
+- 🟢 低风险: 0 个依赖
+
+**验证**:
+- `src/types/index.ts` (38依赖) → 🔴 极高风险 ✅ 合理
+- `src/cache/lru-cache.ts` (4依赖) → ⚠️ 高风险 ✅ 合理 (虽数量不多但核心功能)
+- `src/cli/commands/cycles.ts` (2依赖) → ⚠️ 中风险 ✅ 合理
+
+### 4. 输出格式实用性
+
+**CodeMap 优势**:
+- 可视化依赖树结构
+- 显示每个依赖的导出内容
+- 距离标记 (传递依赖)
+- 风险等级评估
+- 统计汇总
+
+**Grep 优势**:
+- 简单列表，易于脚本处理
+- 可与其他 Unix 工具链组合
+
+### 5. 性能对比
+
+| 工具 | 平均执行时间 | 相对速度 |
+|------|-------------|---------|
+| CodeMap (direct) | ~0.6s | 1x |
+| CodeMap (transitive) | ~0.8s | 0.75x |
+| ripgrep | ~0.01s | 60-80x |
+
+---
+
+## 发现的问题
+
+### 问题 1: 遗漏 re-export 依赖
+**严重性**: 🔴 高
+
+**描述**: CodeMap 未能检测到通过 re-export 模式依赖的文件。
+
+**示例**: `src/index.ts` 包含:
+```typescript
+export { analyze } from './core/analyzer.js';
+```
+
+但 CodeMap 未将 `src/index.ts` 列为 `analyzer.ts` 的依赖。
+
+**影响**: 修改 analyzer.ts 可能影响所有通过主入口导入的下游用户。
+
+### 问题 2: 对 "高/极高风险" 阈值定义不明确
+**严重性**: 🟡 中
+
+**描述**: 
+- `types/index.ts` (38依赖) → 🔴 极高风险
+- `analyzer.ts` (13依赖) → 🔴 极高风险
+- `lru-cache.ts` (4依赖) → ⚠️ 高风险
+
+阈值跳跃较大，13和38都被归为"极高"，但4就是"高"，缺少中间等级。
+
+### 问题 3: 执行时间较长
+**严重性**: 🟡 中
+
+**描述**: CodeMap 比 ripgrep 慢 60-80 倍。对于大型代码库或频繁查询场景，这可能成为瓶颈。
+
+**建议**: 
+- 提供缓存机制
+- 增量更新依赖图
+- 添加 `--fast` 模式使用简化分析
+
+### 问题 4: 输出格式缺乏机器可读性
+**严重性**: 🟢 低
+
+**描述**: 输出主要是人类可读格式，没有 JSON/YAML 输出选项，不利于脚本集成。
+
+---
+
+## 改进建议
+
+### 1. 增强 re-export 检测
+```typescript
+// 检测以下模式:
+export { foo } from './module';
+export * from './module';
+export { default } from './module';
+```
+
+### 2. 细化风险等级
+```
+🟢 低风险: 0-2 依赖
+🟡 中风险: 3-10 依赖  
+🟠 高风险: 11-25 依赖
+🔴 极高风险: 26+ 依赖
+```
+
+### 3. 添加性能优化选项
+```bash
+npx codemap impact -f file.ts --cached        # 使用缓存
+npx codemap impact -f file.ts --depth 2       # 限制传递深度
+npx codemap impact -f file.ts --json          # 机器可读输出
+```
+
+### 4. 提供 diff 模式
+```bash
+npx codemap impact --compare branch1 branch2  # 对比分支影响
+```
+
+---
+
+## 总结
+
+| 评估维度 | 评分 | 说明 |
+|---------|------|------|
+| 准确性 | ⭐⭐⭐⭐⭐ | 几乎无直接依赖误报 |
+| 完整性 | ⭐⭐⭐⭐ | 遗漏 re-export，其他良好 |
+| 传递分析 | ⭐⭐⭐⭐⭐ | 独有功能，非常有价值 |
+| 风险评估 | ⭐⭐⭐⭐ | 分级合理但阈值可细化 |
+| 性能 | ⭐⭐⭐ | 比 grep 慢，但可接受 |
+| 实用性 | ⭐⭐⭐⭐⭐ | 可视化输出，信息丰富 |
+
+### 最终结论
+
+**CodeMap impact 命令**在影响范围分析上**显著优于**传统 grep 方法:
+
+1. **准确性**: 几乎零误报，而 grep 有 20-60% 的误报率
+2. **传递依赖**: 提供手动几乎无法完成的深层依赖分析
+3. **风险评估**: 量化风险等级，辅助决策
+4. **可视化**: 树形结构直观展示依赖关系
+
+**适用场景**:
+- ✅ 发布前影响评估
+- ✅ 重构前依赖分析  
+- ✅ 代码审查辅助
+- ✅ 架构决策支持
+
+**不适用场景**:
+- ❌ 需要极快速响应的实时监控
+- ❌ 纯文本处理的自动化脚本
+
+**总体推荐**: ⭐⭐⭐⭐⭐ (5/5) - 对于需要准确影响分析的场景强烈推荐使用

package/docs/backlog.md

@@ -0,0 +1,177 @@
+
+
+# mycodemap 产品重塑提案 v0.6
+**从"代码地图工具"到"架构契约治理引擎"**
+
+## 一、战略定位重置（Positioning）
+
+### 核心定位转变
+| 维度 | 当前（v0.5 MVP3） | **重塑后（v0.6）** |
+|------|------------------|-------------------|
+| **产品品类** | TypeScript 代码地图生成工具 | **架构契约验证与护栏系统** |
+| **核心价值** | 帮助AI理解代码结构 | **防止AI/人类破坏架构边界** |
+| **竞争差异** | 生成 JSON 地图供AI消费 | **生成决策：通过/阻断，并给出架构违反证据** |
+| **技术重心** | Tree-sitter 解析 + 图数据库 | **Tree-sitter + SQLite + 轻量内存图** |
+
+---
+
+## 二、只做（Must Do）- 差异化护城河
+
+### 1. **契约护栏系统（Contract Barriers）**
+基于 `mycodemap.design.md` 的强约束验证：
+- **模块边界守护**：验证跨模块调用是否通过允许的中介
+- **依赖方向检查**：确保分层架构（如领域层→基础设施层）不被反向依赖
+- ** breaking change 预警**：当修改影响契约定义的公开 API 时自动标记
+
+```typescript
+// 新命令示例
+mycodemap verify --contract design.md --against src/
+// 输出: { "passed": false, "violations": [{ "rule": "auth禁止直接调用payment", "location": "auth/login.ts:45" }] }
+```
+
+### 2. **Git 历史融合分析（Code Archaeology）**
+利用 SQLite 存储 git blame + 变更历史：
+- **危险区域标记**：高频修改且伴随回滚的代码区域自动标记"高风险"
+- **契约漂移检测**：对比当前代码与历史契约版本，发现架构腐化趋势
+- **影响评估增强**：不仅告诉AI"这修改影响3个文件"，还告诉"这3个文件在过去6个月被修改了17次，回滚率35%"
+
+### 3. **轻量级混合存储架构**
+**放弃重型图数据库**，采用 SQLite + 内存图计算：
+
+```typescript
+// 技术架构示意
+StorageLayer {
+  // Layer 1: SQLite 负责持久化 + BM25全文搜索 + 契约元数据
+  sqlite: BetterSQLite3Wrapper;
+  
+  // Layer 2: 内存图计算（替代 NetworkX，使用 graphlib 或自研邻接表）
+  graph: DirectedGraph; // 基于 Map/Set 的轻量实现
+  
+  // 启动时从 SQLite 加载符号关系到内存图，<500ms
+  loadGraph(): void;
+  
+  // 核心操作：基于图的可达性分析（契约验证的关键）
+  computeImpact(symbol: string, depth: number): ImpactGraph;
+}
+```
+
+**为什么这个架构对 TypeScript 项目更优：**
+- `better-sqlite3`：Node.js 最快的 SQLite 绑定，零配置，单文件存储
+- 内存图计算：对于 <50K 文件的 TypeScript 项目，纯 JavaScript 图遍历（DFS/BFS）性能足够（<100ms），无需引入沉重的图数据库客户端
+
+### 4. **CI/CD 原生集成（Quality Gate）**
+专为流水线设计的"硬阻断"模式：
+- **退出码策略**：发现契约违反时返回非零退出码，直接阻断 CI 流程
+- **JSON 报告**：生成结构化报告供 GitHub/GitLab 的 Code Review 界面渲染
+- **增量验证**：仅验证 git diff 涉及的符号，<2秒完成门禁检查
+
+---
+
+## 三、不做（Must Not Do）- 避免与巨人正面竞争
+
+### 1. **不追求极致的 Token 节省**
+- **不做**：与 code-review-graph 竞争的"49倍Token节省"宣传
+- **原因**：这是 code-review-graph 的核心赛道，且需要极其优化的增量算法和向量索引，投入产出比低
+- **替代**：专注"**精准上下文**"——不是给AI更少代码，而是给AI**符合架构约束**的代码上下文
+
+### 2. **不做动态运行时分析**
+- **不做**：eBPF 插桩、JavaScript 运行时追踪、调用链路采集
+- **原因**： 
+  - 技术债务极重（需维护运行时 agent）
+  - 与静态分析工具定位冲突（用户不会同时安装两类工具）
+  - 报告中提到的"运行时图谱"目前仍是学术阶段，无成熟开源方案
+
+### 3. **不做多模态支持（文档/图像/音频）**
+- **不做**：解析 PDF 架构图、会议录音转录、白板照片识别
+- **原因**：这是 graphify 的独占赛道，需集成 Whisper/OCR/LLM，架构重量与 mycodemap 的"轻量CLI"定位冲突
+
+### 4. **不做通用代码搜索引擎**
+- **不做**：支持 25 种语言的通用符号搜索、跨语言调用图
+- **原因**：竞品已覆盖（code-review-graph 支持 23 种语言，graphify 25 种）
+- **专注**：TypeScript/JavaScript 生态的**深度架构治理**，而非广度语言支持
+
+---
+
+## 四、优化方向（Optimization Roadmap）
+
+### Phase 1: 架构瘦身（v0.6.0）
+- **移除**：KuzuDB 依赖（如果当前有）
+- **引入**：better-sqlite3 + 内存图结构（基于 Map 的邻接表）
+- **基准**：10K 文件项目启动时间 <1s，内存占用 <200MB
+
+### Phase 2: 契约系统硬化（v0.7.0）
+- **设计契约 Schema 标准化**：`design.md` → JSON Schema 验证
+- **护栏规则引擎**：支持复杂度、依赖方向、模块边界三类规则
+- **Git 融合**：SQLite 存储 git blame 信息，支持 `mycodemap history --symbol X` 查询变更轨迹
+
+### Phase 3: AI 协作协议（v0.8.0）
+- **MCP 工具增强**：从"提供上下文"转向"提供决策建议"
+  - 新增 `verify_contract` MCP 工具：AI 在修改前调用，获取"此修改是否安全"的布尔值
+- **Prompt 模板**：为 Claude Code/Cursor 提供"架构师模式"提示词，强制在修改前调用 mycodemap verify
+
+---
+
+## 五、用户场景（User Scenarios）
+
+### 场景 A：架构师的守门员（Quality Gate）
+**角色**：资深工程师/架构师  
+**痛点**： junior 开发或 AI 工具经常破坏精心设计的模块边界  
+**使用**：
+```bash
+# 在 pre-commit 钩子中
+mycodemap verify --strict --fail-on-barrier-break
+```
+**价值**：将架构文档（design.md）从"仅供参考"变为"强制执行的代码法律"
+
+### 场景 B：AI 辅助开发的安全护栏
+**角色**：使用 Claude Code/Cursor 的开发者  
+**痛点**：AI 经常生成"看似正确但破坏架构"的代码（如直接跨层调用数据库）  
+**使用**：
+```typescript
+// .cursorrules 或 claude.md 配置
+"Before modifying code, run: mycodemap impact -t {target} --check-contracts"
+```
+**价值**：AI 在每次修改前自动检查，避免" AI 写代码，架构师擦屁股"的循环
+
+### 场景 C：遗留项目现代化评估
+**角色**：技术负责人  
+**痛点**：不知道当前代码与最初架构设计偏离了多远  
+**使用**：
+```bash
+mycodemap drift --since 2024-01-01 --contract original-design.md
+```
+**价值**：量化"架构腐化度"，为重构决策提供数据支撑（如"当前 23% 的调用违反了原始模块边界"）
+
+### 场景 D：高风险修改预警
+**角色**：DevOps/运维  
+**痛点**：某些代码区域变更极易引发故障  
+**使用**：
+```bash
+mycodemap analyze -i modify -t "payment/" --include-history --json
+# 输出标记：该区域过去 12 个月修改 47 次，回滚 12 次，事故 3 次
+```
+**价值**：在变更发布前识别"代码墓地"区域，强制增加 review 层级
+
+---
+
+## 六、竞品差异化对比表
+
+| 功能维度 | code-review-graph | graphify | **mycodemap (重塑后)** |
+|---------|-------------------|----------|----------------------|
+| **核心问题** | "哪些代码可能相关" | "这段代码的设计动机是什么" | **"这次修改是否破坏架构规则"** |
+| **输出形态** | 文件列表 + 置信度 | 自然语言解释 + 多模态关联 | **布尔值（通过/阻断）+ 违规证据链** |
+| **存储架构** | SQLite (极致性能) | SHA256缓存 + 大模型语义 | **SQLite + 内存图（轻量可移植）** |
+| **最佳场景** | 日常编码辅助 | 理解遗留项目 | **CI/CD 门禁 + 架构守护** |
+| **与AI关系** | AI 的"眼"（提供上下文） | AI 的"脑"（提供理解） | **AI 的"护栏"（提供约束）** |
+
+---
+
+## 七、总结
+
+mycodemap 的救赎之路是**放弃成为更好的"代码搜索引擎"，转而成为唯一的"架构契约执行引擎"**：
+
+- **不做** code-review-graph 能做到的事（快速搜索、Token节省）
+- **不做** graphify 能做到的事（多模态理解、设计动机提取）
+- **只做** 它们都做不到的事：**将架构文档转化为可执行的代码法律，并在 CI/CD 中强制执行**
+
+这是从"工具"到"基础设施"的跃迁——不是让AI更方便地写代码，而是**确保AI写的代码不会破坏你的架构**。