@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/docs/ai-guide/PROMPTS.md

@@ -346,32 +346,37 @@
    node dist/cli/index.js design validate mycodemap.design.md --json
    ```
 
-2. **相关代码搜索**
+2. **如果这是架构边界类需求，先跑 contract gate**
+   ```bash
+   node dist/cli/index.js check --contract mycodemap.design.md --against src
+   ```
+
+3. **相关代码搜索**
    ```bash
    node dist/cli/index.js analyze -i find -k "{{RELATED_KEYWORD}}" --topK 10 --json
    ```
 
-3. **参考现有实现**
+4. **参考现有实现**
    分析类似功能的实现方式
 
-4. **确定实现位置**
+5. **确定实现位置**
    ```bash
    node dist/cli/index.js analyze -i read -t "候选目录" --json
    ```
    选择复杂度最低的模块
 
-5. **影响分析**（如果需要修改现有代码）
+6. **影响分析**（如果需要修改现有代码）
    ```bash
    node dist/cli/index.js analyze -i read -t "目标文件" --json
    ```
 
-6. **实现步骤**
+7. **实现步骤**
    - [ ] 创建新文件（添加 [META] [WHY] 头）
    - [ ] 实现核心功能
    - [ ] 添加单元测试
    - [ ] 运行测试验证
 
-7. **验证**
+8. **验证**
    ```bash
    node dist/cli/index.js ci check-headers -f "新文件.ts"
    npm test

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写的代码不会破坏你的架构**。

package/docs/eatdogfood-reports/2026-04-17-eatdogfood-agent-experience.md

@@ -0,0 +1,231 @@
+# CodeMap Eatdogfood 测试报告
+
+> 测试者身份：AI Agent（eatdogfood）  
+> 测试日期：2026-04-17  
+> 测试目标：用 CodeMap CLI 分析 CodeMap 自身，记录完整使用体验（尤其 Agent 视角）
+
+---
+
+## 1. 执行摘要
+
+本次测试以 AI Agent 的身份，完整体验了 CodeMap CLI 的**查询层**与**非查询层**能力。测试覆盖 10+ 命令，包含符号查询、依赖影响分析、代码地图生成、复杂度分析、循环依赖检测、CI 风险评估、设计契约验证/交接/漂移检测、工作流启动、Mermaid 导出等。
+
+**核心结论**：CodeMap 在"让 Agent 快速建立代码库心智模型"上表现优异，但部分命令在**参数一致性**和**零结果反馈**上仍有打磨空间。
+
+---
+
+## 2. 测试覆盖与结果
+
+### 2.1 查询与影响分析层
+
+| 命令 | 目标 | 结果 | Agent 评分 |
+|------|------|------|-----------|
+| `query -s "AnalyzeCommand"` | 查找符号定义 | 4 条精确结果，含 `kind`/`location`/`isExported` | ★★★★★ |
+| `deps -m "src/core/analyzer"` | 模块依赖关系 | 6 个依赖 + 6 个依赖者，带路径映射 | ★★★★★ |
+| `impact -f src/cli/commands/analyze.ts` | 文件变更影响面 | 33 个结果，自动区分 `source`/`test` | ★★★★★ |
+| `analyze -i read` | 高相关度文件摘要 | 人类友好，带 100%/95% 相关度 | ★★★★☆ |
+| `analyze -i link` | 架构关联映射 | 22 引用方/17 关联目标，`riskLevel: high` | ★★★★☆ |
+| `analyze -i show` | 模块导出摘要 | 导出 4 符号，依赖 17 模块 | ★★★★☆ |
+| `analyze -i find` | 关键词发现 | 对单文件路径 confidence 仅 0.04 | ★★☆☆☆ |
+| `history --symbol` | Git 历史与风险 | 返回 symbolId/moduleId/exactNameMatch | ★★★★★ |
+
+### 2.2 非查询层（生成、分析、工程、工作流）
+
+| 命令 | 目标 | 结果 | Agent 评分 |
+|------|------|------|-----------|
+| `generate -m fast` | 生成代码地图 | 242 模块/958 导出符号/62482 行，成功 | ★★★★★ |
+| `complexity src/cli/commands/analyze.ts` | 代码复杂度 | **指定文件后仍返回全量 79KB JSON** | ★★☆☆☆ |
+| `cycles` | 循环依赖检测 | `hasCycles: false`，架构健康 | ★★★★★ |
+| `ci assess-risk` | 变更风险评估 | score=0.05（low），threshold=0.50，通过 | ★★★★☆ |
+| `design validate` | 设计契约校验 | 有效 doc ✅，无效 doc ❌ 并列出缺失 section | ★★★★★ |
+| `design map` | 设计范围映射 | 无设计文档时 `blocked: true`，检测准确 | ★★★★★ |
+| `design handoff` | 生成交接包 | 生成 `.mycodemap/handoffs/` 含 touchedFiles/tests/risks | ★★★★★ |
+| `design verify` | 验证设计漂移 | 发现 5 处 drift，3 项待 review | ★★★★★ |
+| `check --contract ...` | 契约门禁检查 | `passed: true`，diff scope 从 1 扩展到 3 文件 | ★★★★☆ |
+| `export mermaid` | 导出依赖图 | 242 模块，7.1KB Mermaid 文件，成功 | ★★★★★ |
+| `workflow start` | 启动分析工作流 | 生成 workflow ID，推荐 `refactoring` 模板 | ★★★★☆ |
+
+---
+
+## 3. Agent 视角的使用体验（重点）
+
+### 3.1 Agent 的核心痛点：上下文是有限的，噪音是致命的
+
+作为 AI Agent，我在分析代码库时最大的约束不是计算能力，而是**上下文窗口**。当使用传统工具链（`grep` + `read`）分析 `src/cli/commands/analyze.ts` 的影响面时：
+
+- 3 次 Grep 返回约 **92 条文件引用**
+- 混入 `.planning/`、`.claude/`、`docs/archive/` 等 20+ 文档噪音
+- `src/orchestrator/result-fusion.ts` 被误抓——实际并未导入 `analyze.ts`，只是文本中出现了 "analyze"
+
+为了排除误报，我不得不**逐个 Read 文件验证**。这个过程消耗了大量 token，而且结果仍需要我手动去重、分类。
+
+而使用 `impact -f` 时：
+- **1 次调用**
+- **33 条精准结果**
+- **0 条文档噪音**
+- **自动标记 `source` / `test`**
+
+这不仅是"快"，而是从"猜测-验证"模式切换到了"直接获取答案"模式。
+
+### 3.2 哪些命令是 Agent 的"高信号工具"
+
+以下命令对 Agent 来说是**高 ROI**的，应优先集成到 Agent 工作流中：
+
+1. **`impact -f`** → 重构前的必备步骤。自动分类测试文件，让 Agent  instantly 知道"改完要跑哪些测试"。
+2. **`deps -m`** → 理解模块边界。比文本搜索 `import` 更准确，因为它基于解析后的依赖图。
+3. **`query -s`** → 符号导航。不仅找定义，还找重导出和关联函数，是 Agent 定位代码的 GPS。
+4. **`design validate` / `design map` / `design handoff`** → 设计驱动开发的三件套。Agent 可以在动手写代码前验证设计文档是否完整，生成交接包后按图施工。
+5. **`ci assess-risk`** → 在 Plan 阶段给变更打分。Agent 可以根据风险分数决定是否建议人类审查。
+6. **`generate`** → 建立项目基线。Agent 可以在任务开始时生成代码地图，后续所有查询都在这个基线上进行。
+
+### 3.3 哪些体验会打断 Agent 的自主性
+
+以下问题会迫使 Agent 从"自动执行"退回"试探-纠错"模式：
+
+#### 问题 A：`--json` 支持不统一
+
+```bash
+# 这些命令支持 --json ✅
+query -s, deps -m, impact -f, design validate, design map, design handoff, design verify, check, cycles
+
+# 这些命令不支持 --json ❌
+history --symbol, ci assess-risk, workflow start
+```
+
+对 Agent 来说，JSON 是**机器可解析的默认语言**。当某些命令不支持 `--json` 时，Agent 需要额外处理人类可读输出，增加解析失败的风险。
+
+#### 问题 B：`complexity` 指定文件仍返回全量
+
+我执行了：
+```bash
+node dist/cli/index.js complexity src/cli/commands/analyze.ts --json
+```
+
+但它返回了**所有 242 个文件**的复杂度数据（79KB）。对 Agent 来说，这意味着：
+- 大量无关信息挤占上下文
+- 需要自行过滤目标文件
+- 命令参数语义与行为不一致
+
+#### 问题 C：`check` / `ci assess-risk` 的静默通过
+
+当 `check` 检测到文件没有对应设计文档时，输出为空；`ci assess-risk` 输出纯文本但没有结构化分数字段。Agent 很难判断：
+- 这是"通过"还是"跳过"？
+- 状态码 0 是否代表一切正常？
+
+#### 问题 D：`analyze -i find` 对显式文件路径 confidence 过低
+
+```bash
+node dist/cli/index.js analyze -i find src/core/analyzer.ts --json
+# confidence: 0.04, results: []
+```
+
+当 Agent 已经精确指定了文件路径，工具却以低置信度返回空结果，这会让 Agent 怀疑自己的输入是否正确，从而触发不必要的 fallback 逻辑。
+
+### 3.4 Agent 最喜欢的设计细节
+
+1. **`impact` 的 `source` / `test` 分类**
+   这不是 UI 装饰，而是直接影响 Agent 决策的结构化信息。Agent 可以立刻生成测试计划："需要验证的测试文件：X, Y, Z"。
+
+2. **`design verify` 的 `driftCount` 和 `needsReviewCount`**
+   让 Agent 可以量化设计文档的"健康度"。`driftCount: 5` 意味着 Agent 应该优先提醒人类审查，而不是继续自动执行。
+
+3. **`check` 的 `scan_mode: diff` 和 scope 扩展警告**
+   ```json
+   { "code": "diff-scope-expanded", "message": "diff scope 从 1 个 changed file 扩展到 3 个 scanned file" }
+   ```
+   这让 Agent 理解契约检查的边界——它不是只看你改的那一行，而是会智能扩展到关联文件。
+
+4. **`history` 的 symbolId / moduleId**
+   虽然不支持 `--json`，但默认输出就是 JSON，而且带稳定的标识符。Agent 可以跟踪同一个符号在不同 commit 中的演变。
+
+---
+
+## 4. 对照实验：用 vs 不用 CodeMap
+
+**问题**：修改 `src/cli/commands/analyze.ts` 中的 `AnalyzeCommand`，会影响哪些文件？
+
+### 不用 CodeMap（传统路径）
+
+| 步骤 | 工具 | 结果 | 问题 |
+|------|------|------|------|
+| 1 | `grep "AnalyzeCommand"` | 18 个文件 | 混入了大量文档和历史文件 |
+| 2 | `grep "from.*analyze"` | 45 个文件 | 包含 `.claude/`、`.planning/` 噪音 |
+| 3 | `grep "import.*analyze"` | 29 个文件 | 仍有误报（如 `result-fusion.ts`） |
+| 4 | `Read` 验证 | 3+ 次 | 确认哪些是真依赖 |
+| 5 | 手动分类 | - | 测试文件和源码混在一起 |
+
+**总计**：6 次工具调用，~92 条引用（大量重复/噪音），需人工去重验证。
+
+### 用 CodeMap
+
+```bash
+node dist/cli/index.js impact -f src/cli/commands/analyze.ts --json
+```
+
+**结果**：1 次调用，33 条精准结果，0 噪音，自动分类 source/test。
+
+### 差距总结
+
+| 维度 | 不用 CodeMap | 用 CodeMap |
+|------|-------------|-----------|
+| 调用次数 | 6+ | **1** |
+| 结果量 | ~92 条 | **33 条** |
+| 噪音混入 | 20+ 文档/历史文件 | **0** |
+| 误报率 | 高（文本匹配） | **0** |
+| 测试/源码分类 | 手动 | **自动** |
+| Token 消耗 | 高 | **低** |
+
+---
+
+## 5. 发现的问题与改进建议
+
+### 5.1 高优先级（影响 Agent 自主性）
+
+| 问题 | 影响 | 建议 |
+|------|------|------|
+| `--json` 支持不统一 | Agent 需要为不同命令写不同解析器 | 所有命令统一支持 `--json`，或默认输出机器可读格式 |
+| `complexity` 指定文件仍返回全量 | 上下文爆炸 | 当提供文件参数时，只返回指定文件的复杂度 |
+| `check` / `ci assess-risk` 静默通过 | Agent 无法区分"通过"和"未执行" | 始终输出一条状态摘要，如 `status: passed` / `status: skipped` |
+| `analyze -i find` 对显式路径 confidence 过低 | Agent 会怀疑输入正确性 | 对绝对/相对文件路径提升 confidence 权重 |
+
+### 5.2 中优先级（体验优化）
+
+| 问题 | 影响 | 建议 |
+|------|------|------|
+| `generate` 默认输出到 `.mycodemap` | Agent 可能需要区分不同任务的结果 | 支持 `--task-id` 后缀或子目录 |
+| `workflow` 不支持 `--json` | 难以自动化驱动工作流 | 支持 `--json` 和 `--auto-proceed` |
+| RTK `Filters NOT applied` 警告 | 每次命令都出现，干扰输出 | 在 CI/Agent 模式下可静默 |
+
+---
+
+## 6. 结论
+
+### 对 Agent 来说，CodeMap 的价值是什么？
+
+CodeMap 把 AI Agent 从"**在代码海里钓鱼**"变成了"**直接拿到导航图**"。
+
+- **`impact`** 让 Agent 在改代码前就知道"会打翻哪些盘子"
+- **`design validate/handoff/verify`** 让 Agent 能参与设计驱动流程，而不是盲目写代码
+- **`ci assess-risk`** 让 Agent 具备风险意识，知道什么时候该停下来叫人类审查
+- **`generate` + `export`** 让 Agent 能把代码库结构转换成各种可消费格式
+
+### 当前的短板是什么？
+
+最大的短板不是功能缺失，而是**"Agent 接口的一致性"**。
+
+当 Agent 调用 10 个命令时，如果有 3 个不支持 `--json`、1 个忽略文件参数、2 个静默通过，Agent 的可靠性就会从"自动驾驶"降级为"辅助驾驶"。
+
+### 最终评分
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 查询精准度 | 9/10 | `query`/`deps`/`impact` 非常可靠 |
+| 非查询能力 | 8/10 | 生成/设计/CI/导出能力完整 |
+| Agent 友好度 | 6/10 | `--json` 不一致和部分命令 UX 影响自动化 |
+| 整体推荐度 | 8/10 | **值得作为 Agent 工具链的核心组件**，但需要修复接口一致性问题 |
+
+---
+
+**测试执行者**：Claude (AI Agent)  
+**测试对象**：CodeMap CLI v当前版本（基于 `main` 分支构建）  
+**报告生成时间**：2026-04-17

package/docs/exec-plans/completed/2026-04-17-eatdogfood-codemap-cli.md

@@ -0,0 +1,103 @@
+# 2026-04-17 eatdogfood：CodeMap CLI 项目内自试用记录
+
+## 1. 任务定义
+
+- [证据] **目标**：以真实使用者（eatdogfood）的身份，在当前仓库里直接使用项目自己的 CLI 做一次最小闭环试用，覆盖 `generate`、`query`、`analyze`、`deps`、`impact`，并记录体验、失败模式与后续建议。公开命令面与 AI/Agent 的推荐入口已在 `README.md:10`、`README.md:11`、`README.md:25`、`README.md:28`、`AI_GUIDE.md:47`、`AI_GUIDE.md:49`、`AI_GUIDE.md:51`、`AI_GUIDE.md:52`、`AI_GUIDE.md:54` 说明。
+- [证据] **限制条件**：当前仓库的默认配置只扫描 `src/**/*.ts`，排除 `dist/**`、`build/**`、测试文件，输出目录为 `.mycodemap`，因此本次 dogfood 以源码主干为主，不把构建产物视为正常分析对象。见 `mycodemap.config.json:3`、`mycodemap.config.json:4`、`mycodemap.config.json:7`、`mycodemap.config.json:8`、`mycodemap.config.json:9`、`mycodemap.config.json:10`、`mycodemap.config.json:12`。
+- [证据] **验收标准**：至少形成一次“生成 → 查询 → 阅读 → 依赖 → 影响”的真实操作链；至少记录一个失败场景；结果落到 `docs/exec-plans/` 以满足“目标、限制、DoD、风险、复盘”边界。目录职责见 `docs/exec-plans/README.md:3`、`docs/exec-plans/README.md:7`、`docs/exec-plans/README.md:8`、`docs/exec-plans/README.md:22`、`docs/exec-plans/README.md:23`、`docs/exec-plans/README.md:24`。
+- [证据] **依赖关系**：本仓库 `bin` 已指向 `dist/cli/index.js`，且 `build` 脚本为 `tsc`，说明可以直接基于已构建 CLI 运行体验测试。见 `package.json:15`、`package.json:16`、`package.json:17`、`package.json:29`、`package.json:30`。
+
+## 2. 操作过程
+
+### 2.1 入口确认
+
+- [证据] 先用 `node dist/cli/index.js --help` 确认当前公共命令，结果与 README/AI 指南一致：存在 `generate`、`query`、`deps`、`impact`、`analyze` 等入口；这与 `README.md:10`、`README.md:28`、`docs/ai-guide/COMMANDS.md:12`、`docs/ai-guide/COMMANDS.md:46`、`docs/ai-guide/COMMANDS.md:74`、`docs/ai-guide/COMMANDS.md:91` 一致。
+- [观点] 这一步体验是“入口比较完整，但用户需要自己决定该先用 `query` 还是 `analyze`”；对于第一次上手的人，命令多不一定是优势。
+
+### 2.2 生成代码地图
+
+- [证据] 执行命令：`rtk node dist/cli/index.js generate`
+- [证据] 实际输出显示：扫描 242 个文件、62482 行代码、242 个模块、958 个导出符号，并写出 `AI_MAP.md`、`codemap.json`、`dependency-graph.md` 与 `context/`。
+- [推论] 这一步与文档承诺基本一致：README 明确把 `generate` 作为第一步，并说明输出 `.mycodemap/AI_MAP.md`、`codemap.json`、`dependency-graph.md` 等文件，见 `README.md:58`、`README.md:59`、`README.md:61`、`README.md:62`、`README.md:66`、`README.md:67`；命令参考也把 `.mycodemap` 作为默认输出目录，见 `docs/ai-guide/COMMANDS.md:15`、`docs/ai-guide/COMMANDS.md:25`。
+- [观点] 这一步是本次体验里“最稳”的一环：执行路径短、反馈明确、产物可见，能快速建立信心。
+
+### 2.3 符号与模块查询
+
+- [证据] 执行命令：`node dist/cli/index.js query --search CodeMapServer --limit 5 --json --structured`
+- [证据] 返回 3 个结果：`src/server/CodeMapServer.ts` 模块、`CodeMapServer` 类导出、`src/server/index.ts` 里的 `CodeMapServer` 变量导出。
+- [证据] 执行命令：`node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured`
+- [证据] 返回 1 个结果：`src/interface/types/index.ts` 中导出的 `SourceLocation` 接口。
+- [推论] `query` 基本符合 AI 指南里“查定义/查相关代码”的定位：`query -s "XXX"` 用于找定义，`query -S "XXX"` 用于模糊检索，见 `AI_GUIDE.md:50`、`AI_GUIDE.md:54`、`docs/ai-guide/COMMANDS.md:49`、`docs/ai-guide/COMMANDS.md:52`、`docs/ai-guide/COMMANDS.md:65`、`docs/ai-guide/COMMANDS.md:66`。
+- [观点] 如果我是第一次接触项目的 agent，我会优先保留 `query`，因为它给我的“是否找到了东西”的反馈最直接。
+
+### 2.4 read / link / show
+
+- [证据] 执行命令：`node dist/cli/index.js analyze -i read -t src/server/CodeMapServer.ts --scope direct --include-git-history --json --structured`
+- [证据] 返回 `confidence.score = 0.8`、`level = high`、`results.length = 7`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i read -t src/interface/types/index.ts --scope direct --json --structured`
+- [证据] 返回 `confidence.score = 0.8`、`results.length = 8`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i link -t src/server --json --structured`
+- [证据] 返回 `confidence.score = 0.6`、`level = medium`、`resultCount = 2`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i show -t src/server --output-mode human`
+- [证据] 人类输出中直接给出 `src/server/CodeMapServer.ts:1`，并提示“导出 1 个符号，依赖 11 个模块，相关度 75.0%”。
+- [推论] `analyze` 的 `read/show` 路径能跑通，且与 README 中“`analyze` 支持 human/machine 模式”的承诺一致，见 `README.md:25`、`README.md:74`、`README.md:75`、`docs/ai-guide/COMMANDS.md:6`。
+- [观点] `show` 的人类输出有“开箱即看”的味道，比结构化 JSON 更像产品；但它的 discoverability 仍然依赖文档，不是 CLI 自解释。
+
+### 2.5 deps / impact
+
+- [证据] 执行命令：`node dist/cli/index.js deps -m src/server/CodeMapServer.ts --json --structured`
+- [证据] 返回结果显示：`src/server/CodeMapServer.ts` 直接依赖 11 个模块，前 5 个外部依赖是 `hono`、`@hono/node-server`、`hono/cors`、`hono/logger`、`hono/pretty-json`。
+- [证据] 执行命令：`node dist/cli/index.js impact -f src/server/CodeMapServer.ts --transitive --json --structured`
+- [证据] 返回结果显示：直接影响 6 个依赖方，统计字段中传递影响规模为 217。
+- [推论] 这与 AI 指南中“依赖看 `deps`、影响看 `impact -t -j`”的建议一致，见 `AI_GUIDE.md:51`、`AI_GUIDE.md:52`、`docs/ai-guide/COMMANDS.md:74`、`docs/ai-guide/COMMANDS.md:91`、`docs/ai-guide/COMMANDS.md:95`、`docs/ai-guide/COMMANDS.md:101`。
+- [观点] 这一步很像真实开发者决策前的“最后一跳”：如果我要改 `CodeMapServer`，这两个命令能快速告诉我“依赖谁”和“谁会被我炸到”。
+
+## 3. 失败预演与实际失败案例
+
+### 3.1 实际失败案例：`analyze -i find` 失准
+
+- [证据] 执行命令：`node dist/cli/index.js analyze -i find -k SourceLocation --json --structured`
+- [证据] 标准输出返回：`confidence.score = 0.04`、`level = low`、`resultCount = 0`。
+- [证据] 同一次执行的标准错误包含 `ast-grep scan 命令失败: SyntaxError`，错误内容直接打印了 TypeScript 语法（例如 `filePath: string`、`Promise<string>` 等），说明底层扫描器在解析 TS 文件时发生失败。
+- [证据] 对照组 1：`rtk grep 'SourceLocation' src tests docs --glob '!dist/**' --glob '!node_modules/**'` 能在 10 个文件里找到 37 处匹配。
+- [证据] 对照组 2：`node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured` 能稳定返回 `src/interface/types/index.ts` 中的 `SourceLocation`。
+- [推论] 这不是“仓库里没有该符号”，而是 `analyze find` 的实现/回退链有缺口：同一个关键词，基础文本检索与 `query` 都能命中，唯独 `analyze find` 在报扫描错误后给出空结果。
+- [观点] 这是本次 dogfood 最大的问题：它会让用户误以为“没有结果”，而不是“工具在部分路径上坏了”。
+
+### 3.2 风险模式
+
+- [推论] 风险模式 1：**静默降级**。命令虽然打印了 stderr，但仍然返回结构化空结果；如果调用方只读 stdout，就会把失败误判成“安全的 0 命中”。
+- [推论] 风险模式 2：**命令选择误导**。`AI_GUIDE.md:54` 把“查找与 XXX 相关的代码”推荐为 `query -S "XXX" -j`，这次反而证明它比 `analyze -i find` 更可靠；若未来文档把 find/promoted workflow 放在更前面，可能会扩大误导面。
+- [推论] 风险模式 3：**配置与实现不一致**。`mycodemap.config.json:7`、`mycodemap.config.json:8` 明确排除了 `dist/**`、`build/**`，但扫描错误里出现了对不兼容语法的解析失败，说明 analyze 链路可能没有完全复用 generate/query 那套“配置感知 + 忽略规则”。
+
+## 4. 心得和感受
+
+- [观点] **好感点**：`generate`、`query`、`deps`、`impact` 组合起来，已经足以支持“先建图、再定位、再评估改动范围”的真实工作流；对 agent 很实用。
+- [观点] **不满点**：`analyze` 想做统一入口，但当前可靠性不如专用命令；这让“统一入口”变成概念上更高级、实际体验上更脆弱。
+- [观点] **对立面质疑**：如果产品前提是“让 AI/Agent 通过统一结构化入口稳定拿到代码上下文”，那 `find` 返回空且不 hard fail 就已经触碰产品底线；这不是小瑕疵，而是信任问题。
+- [观点] **作为 eatdogfood 的主观感受**：我愿意继续用这个工具，但会形成一个保守习惯——先用 `generate + query`，把 `analyze find` 当成实验功能，而不是主路径。
+
+## 5. 结论与建议
+
+- [推论] **短期建议**：把 `query -S` 继续作为默认查找路径，对 `analyze -i find` 增加显式失败状态或 warning 升级，避免“空结果伪装成功”。
+- [推论] **中期建议**：检查 `analyze` 是否复用了与 `generate/query` 一致的 include/exclude 与 TypeScript 解析策略，优先消除“配置写了排除、实际扫描没排除”的偏差。
+- [推论] **长期建议**：让 `analyze` 只做 orchestration，不再偷偷切到不稳定的底层扫描器；或者至少在 JSON 结果里暴露 `partialFailure` 字段。
+
+## 6. 文档同步判断
+
+- [证据] 本次没有修改 CLI 契约、配置项、输出格式、架构边界，因此不触发 README / AI_GUIDE / COMMANDS / OUTPUT 的强制同步条件；触发条件定义见 `AGENTS.md:151`、`AGENTS.md:152`、`AGENTS.md:153`、`AGENTS.md:158`、`AGENTS.md:160`。
+- [证据] 本次新增的是执行复盘与缺陷记录，符合 `docs/exec-plans/` 与 `.codemap/issues/` 的用途，不属于产品文档失真修复。
+
+## 7. 本次使用的命令清单
+
+- [证据] `rtk node dist/cli/index.js generate`
+- [证据] `node dist/cli/index.js query --search CodeMapServer --limit 5 --json --structured`
+- [证据] `node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured`
+- [证据] `node dist/cli/index.js analyze -i read -t src/server/CodeMapServer.ts --scope direct --include-git-history --json --structured`
+- [证据] `node dist/cli/index.js analyze -i read -t src/interface/types/index.ts --scope direct --json --structured`
+- [证据] `node dist/cli/index.js analyze -i link -t src/server --json --structured`
+- [证据] `node dist/cli/index.js analyze -i show -t src/server --output-mode human`
+- [证据] `node dist/cli/index.js deps -m src/server/CodeMapServer.ts --json --structured`
+- [证据] `node dist/cli/index.js impact -f src/server/CodeMapServer.ts --transitive --json --structured`
+- [证据] `node dist/cli/index.js analyze -i find -k SourceLocation --json --structured`
+- [证据] `rtk grep 'SourceLocation' src tests docs --glob '!dist/**' --glob '!node_modules/**'`