@mycodemap/mycodemap 0.4.1 → 0.5.0

package/docs/ai-guide/PATTERNS.md

@@ -1,6 +1,18 @@
 # AI Guide - 使用模式与最佳实践
 
 > 标准工作流模式和输出处理最佳实践
+>
+> CodeMap 的首屏产品面是代码地图与代码分析。`workflow` 是当前公开的 analysis-only 工作流能力，本文件会明确区分核心分析模式与 workflow 编排模式。
+
+---
+
+## 使用边界速查
+
+| 类别 | 说明 |
+|------|------|
+| 核心模式 | `generate`、`query`、`deps`、`impact`、`complexity`、`cycles`、`export`、`ci` |
+| 工作流模式 | `workflow` 仍公开，但不是 AI-first 首次接触项目的主入口 |
+| 输出契约 | 当前多数命令显式加 `--json` 获取机器可读结果；`analyze` 可切换 `--output-mode machine|human` |
 
 ---
 
@@ -48,13 +60,13 @@ node dist/cli/index.js deps -m "src" -j
 
 ```bash
 # Step 1: 搜索相关代码
-node dist/cli/index.js analyze -i search -k "相关关键词" --json
+node dist/cli/index.js analyze -i find -k "相关关键词" --json
 
 # Step 2: 分析影响范围（如果有修改现有代码）
-node dist/cli/index.js analyze -i impact -t "目标文件" --include-tests --json
+node dist/cli/index.js analyze -i read -t "目标文件" --include-tests --json
 
 # Step 3: 检查复杂度（选择最佳实现位置）
-node dist/cli/index.js analyze -i complexity -t "候选目录" --json
+node dist/cli/index.js analyze -i read -t "候选目录" --json
 
 # Step 4: 实现代码
 # - 遵循文件头规范
@@ -85,13 +97,13 @@ npm test
 node dist/cli/index.js cycles -j
 
 # Step 2: 分析目标模块复杂度
-node dist/cli/index.js analyze -i complexity -t "目标模块" --json
+node dist/cli/index.js analyze -i read -t "目标模块" --json
 
 # Step 3: 评估影响范围
-node dist/cli/index.js analyze -i impact -t "目标文件" --scope transitive --json
+node dist/cli/index.js analyze -i read -t "目标文件" --scope transitive --json
 
-# Step 4: 获取重构建议
-node dist/cli/index.js analyze -i refactor -t "目标模块" --json
+# Step 4: 补充依赖上下文
+node dist/cli/index.js analyze -i link -t "目标模块" --json
 
 # Step 5: 执行重构
 
@@ -99,7 +111,7 @@ node dist/cli/index.js analyze -i refactor -t "目标模块" --json
 node dist/cli/index.js cycles -j
 
 # Step 7: 验证复杂度降低
-node dist/cli/index.js analyze -i complexity -t "目标模块" --json
+node dist/cli/index.js analyze -i read -t "目标模块" --json
 
 # Step 8: 运行测试
 npm test
@@ -129,7 +141,7 @@ node dist/cli/index.js impact -f "问题文件" --transitive -j
 node dist/cli/index.js query -s "相关测试" --include-references -j
 
 # Step 4: 搜索相似代码（防止同类问题）
-node dist/cli/index.js analyze -i search -k "问题模式" --json
+node dist/cli/index.js analyze -i find -k "问题模式" --json
 
 # Step 5: 修复 Bug
 
@@ -170,20 +182,32 @@ npm test
 
 ---
 
-### 模式 F: 复杂任务管理
+### 模式 F: 复杂分析任务（analysis-only workflow）
 
 **适用场景**: 需要多步骤完成的复杂开发任务
 
 **执行步骤**:
 
 ```bash
+# Step 0: 如果任务来自人类设计，先校验 design contract
+node dist/cli/index.js design validate mycodemap.design.md --json
+
+# Step 0.5: 把 design contract 映射成 candidate code scope
+node dist/cli/index.js design map mycodemap.design.md --json
+
+# Step 0.75: 生成 reviewer / agent 共用的 handoff package
+node dist/cli/index.js design handoff mycodemap.design.md --json
+
+# Step 0.9: 基于 reviewed handoff truth 做 verification / drift 检查
+node dist/cli/index.js design verify mycodemap.design.md --json
+
 # Step 1: 启动工作流
 node dist/cli/index.js workflow start "实现用户认证模块"
 
 # Step 2: 查看当前阶段建议
 node dist/cli/index.js workflow status
 
-# Step 3: 执行当前阶段的分析和实现
+# Step 3: 执行当前阶段的分析（实现/提交/CI 不在 workflow phase 内）
 
 # Step 4: 完成阶段后推进
 node dist/cli/index.js workflow proceed
@@ -197,13 +221,48 @@ node dist/cli/index.js workflow checkpoint
 # Step 7: 重复直到完成
 ```
 
-**工作流阶段**:
-1. `reference` - 参考搜索
-2. `impact` - 影响分析
-3. `risk` - 风险评估
-4. `implementation` - 代码实现
-5. `commit` - 提交验证
-6. `ci` - CI 验证
+**当前工作流阶段**:
+1. `find` - 查找候选符号、文件与关键词线索
+2. `read` - 阅读影响范围、复杂度与上下文
+3. `link` - 汇总依赖、引用与关联关系
+4. `show` - 生成概览、摘要与展示型结果
+
+> 说明：`workflow` 仍只保留 `find` / `read` / `link` / `show` 四阶段；如果任务由人类设计驱动，先走 `design validate → design map → design handoff → design verify` 固定输入、候选范围、review gate 与 drift 检查，再进入 workflow。
+
+---
+
+### 模式 G: 切换图存储后端
+
+**适用场景**: 需要把 CodeGraph 从默认文件系统存储切到 KùzuDB，或验证 graph backend 是否真正生效
+
+**执行步骤**:
+
+```bash
+# Step 1: 编辑配置文件
+cat mycodemap.config.json
+
+# Step 2: 选择后端
+# {
+#   "storage": {
+#     "type": "kuzudb",
+#     "databasePath": ".codemap/kuzu"
+#   }
+# }
+
+# Step 3: 如需 Kùzu 图数据库后端，安装可选依赖
+npm install kuzu
+
+# Step 4: 重新生成代码地图
+node dist/cli/index.js generate
+
+# Step 5: 验证同一 backend 可被读取
+node dist/cli/index.js export json -o /tmp/codemap.json
+```
+
+**决策要点**:
+- 旧的 `neo4j` 配置现在应该直接报迁移错误；缺少 `kuzu` 时也应看到显式错误，而不是静默 fallback。
+- `storage.type = "auto"` 当前仍保守落到 `filesystem`，不要把阈值字段误读成已上线自动切换。
+- 图存储生产化只收口存储面，不重新开放公共 HTTP API 产品面。
 
 ---
 

package/docs/ai-guide/PROMPTS.md

@@ -23,7 +23,7 @@
 
 3. **获取详细信息**
    ```bash
-   node dist/cli/index.js analyze -i overview -t "src/" --json
+   node dist/cli/index.js analyze -i show -t "src/" --json
    ```
 
 4. **回答以下问题**
@@ -53,7 +53,7 @@
 
 1. **影响分析**
    ```bash
-   node dist/cli/index.js analyze -i impact -t "{{FILE_PATH}}" --transitive --include-tests --json
+   node dist/cli/index.js analyze -i read -t "{{FILE_PATH}}" --scope transitive --include-tests --json
    ```
 
 2. **分析结果**
@@ -103,7 +103,7 @@
 
 3. **如果仍不足，使用统一搜索**
    ```bash
-   node dist/cli/index.js analyze -i search -k "{{KEYWORD}}" --topK 15 --json
+   node dist/cli/index.js analyze -i find -k "{{KEYWORD}}" --topK 15 --json
    ```
 
 4. **汇总结果**
@@ -137,17 +137,17 @@
 1. **检测现有问题**
    ```bash
    node dist/cli/index.js cycles -j
-   node dist/cli/index.js analyze -i complexity -t "{{MODULE_PATH}}" --json
+   node dist/cli/index.js analyze -i read -t "{{MODULE_PATH}}" --json
    ```
 
-2. **获取重构建议**
+2. **补充模块上下文**
    ```bash
-   node dist/cli/index.js analyze -i refactor -t "{{MODULE_PATH}}" --json
+   node dist/cli/index.js analyze -i link -t "{{MODULE_PATH}}" --json
    ```
 
 3. **评估影响范围**
    ```bash
-   node dist/cli/index.js analyze -i impact -t "{{MODULE_PATH}}" --scope transitive --json
+   node dist/cli/index.js analyze -i read -t "{{MODULE_PATH}}" --scope transitive --json
    ```
 
 4. **生成评估报告**
@@ -253,7 +253,7 @@
 
 1. **依赖分析**
    ```bash
-   node dist/cli/index.js analyze -i dependency -t "{{MODULE_PATH}}" --json
+   node dist/cli/index.js analyze -i link -t "{{MODULE_PATH}}" --json
    ```
 
 2. **循环依赖检测**
@@ -301,7 +301,7 @@
 
 1. **整体复杂度分析**
    ```bash
-   node dist/cli/index.js analyze -i complexity -t "src/" --json
+   node dist/cli/index.js analyze -i read -t "src/" --json
    ```
 
 2. **函数级复杂度**（针对复杂文件）
@@ -340,32 +340,38 @@
 
 请执行以下步骤：
 
-1. **相关代码搜索**
+1. **先把设计写成可验证输入**
    ```bash
-   node dist/cli/index.js analyze -i search -k "{{RELATED_KEYWORD}}" --topK 10 --json
+   cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md
+   node dist/cli/index.js design validate mycodemap.design.md --json
    ```
 
-2. **参考现有实现**
+2. **相关代码搜索**
+   ```bash
+   node dist/cli/index.js analyze -i find -k "{{RELATED_KEYWORD}}" --topK 10 --json
+   ```
+
+3. **参考现有实现**
    分析类似功能的实现方式
 
-3. **确定实现位置**
+4. **确定实现位置**
    ```bash
-   node dist/cli/index.js analyze -i complexity -t "候选目录" --json
+   node dist/cli/index.js analyze -i read -t "候选目录" --json
    ```
    选择复杂度最低的模块
 
-4. **影响分析**（如果需要修改现有代码）
+5. **影响分析**（如果需要修改现有代码）
    ```bash
-   node dist/cli/index.js analyze -i impact -t "目标文件" --json
+   node dist/cli/index.js analyze -i read -t "目标文件" --json
    ```
 
-5. **实现步骤**
+6. **实现步骤**
    - [ ] 创建新文件（添加 [META] [WHY] 头）
    - [ ] 实现核心功能
    - [ ] 添加单元测试
    - [ ] 运行测试验证
 
-6. **验证**
+7. **验证**
    ```bash
    node dist/cli/index.js ci check-headers -f "新文件.ts"
    npm test

package/docs/ai-guide/QUICKSTART.md

@@ -1,6 +1,8 @@
 # AI Guide - 快速开始
 
 > AI/Agent 使用 CodeMap 的快速入门和决策指南
+>
+> CodeMap 是一个 AI-first 代码地图工具：AI/Agent 是主要消费者，代码分析是首屏产品面。
 
 ---
 
@@ -10,7 +12,8 @@
 # Step 1: 生成代码地图（必须在其他命令之前执行）
 node dist/cli/index.js generate
 
-# Step 2: 阅读生成的 AI_MAP.md 获取项目概览
+# Step 2: 阅读生成的 AI_MAP.md 获取项目概览（若显式配置了 plugins，也要看 Plugin Summary）
+# stdout 还会显示当前写入的 `MVP3 Storage (...)`
 cat .mycodemap/AI_MAP.md
 
 # Step 3: 根据任务选择命令...
@@ -18,6 +21,16 @@ cat .mycodemap/AI_MAP.md
 
 ---
 
+## 输出契约速查
+
+| 维度 | 目标态 | 当前 CLI 现实 | 使用建议 |
+|------|--------|---------------|----------|
+| 机器可读 | 机器可读优先 | 多数命令显式使用 `--json`；`analyze` 也可 `--output-mode machine` | 交给 AI/Agent 继续处理时优先结构化结果 |
+| 人类可读 | 显式人类阅读模式 | `analyze` 支持 `--output-mode human`；其余命令多保留现有文本输出 | 人工审阅时使用 |
+| 边界命名 | `Server Layer` 是内部架构层 | 公共 `mycodemap server` 命令已从 public CLI 移除 | 不要把两者混为一谈 |
+
+---
+
 ## 命令选择决策树
 
 ```
@@ -30,22 +43,22 @@ cat .mycodemap/AI_MAP.md
     ├── 是 → mycodemap query -s "SymbolName"
     ↓ 否
 需要修改某个文件？
-    ├── 是 → mycodemap impact -f "path/to/file" --transitive
+    ├── 是 → mycodemap impact -f "path/to/file" --transitive -j
     ↓ 否
 需要理解模块依赖关系？
-    ├── 是 → mycodemap analyze -i dependency -t "src/module"
+    ├── 是 → mycodemap deps -m "src/module" -j
     ↓ 否
 需要评估代码质量/复杂度？
-    ├── 是 → mycodemap analyze -i complexity -t "src/"
+    ├── 是 → mycodemap complexity -f "src/file.ts" -j
     ↓ 否
 需要搜索包含特定关键词的代码？
-    ├── 是 → mycodemap analyze -i search -k "keyword"
+    ├── 是 → mycodemap query -S "keyword" -j
     ↓ 否
-需要执行复杂的多步骤任务？
+需要执行复杂的多步骤分析？
     ├── 是 → mycodemap workflow start "任务描述"
     ↓ 否
 需要验证代码是否符合规范？
-        └── 是 → mycodemap ci check-headers
+        └── 是 → mycodemap ci check-docs-sync / ci check-headers
 ```
 
 ---
@@ -54,14 +67,16 @@ cat .mycodemap/AI_MAP.md
 
 | 用户意图 | 推荐命令 | 备选命令 | 输出格式 |
 |---------|---------|---------|---------|
-| "项目结构是什么" | `generate` + 读 `AI_MAP.md` | `analyze -i overview` | 文本 |
+| "项目结构是什么" | `generate` + 读 `AI_MAP.md` | `analyze -i show -t "src/" --json` | 文本 |
+| "插件是否真的加载成功" | `generate` + 读 `AI_MAP.md` 的 `Plugin Summary` | 解析 `.mycodemap/codemap.json` 的 `pluginReport` | 机器可读优先 |
+| "需要切换/排查图存储后端" | 编辑 `mycodemap.config.json.storage` 后运行 `generate` | `export json` 验证是否能从同一 backend 读回 | 文本 + 机器可读 |
 | "XXX 在哪里定义" | `query -s "XXX"` | `query -S "XXX"` | 文本 |
-| "修改 XXX 会影响什么" | `impact -f "XXX" -t` | `analyze -i impact -t "XXX"` | JSON |
-| "XXX 模块依赖什么" | `analyze -i dependency -t "XXX"` | `deps -m "XXX"` | JSON |
-| "代码质量如何" | `analyze -i complexity -t "src/"` | `complexity` | JSON |
-| "查找与 XXX 相关的代码" | `analyze -i search -k "XXX"` | `query -S "XXX"` | JSON |
-| "这个改动安全吗" | `ci assess-risk` | `analyze -i impact` | 文本 |
-| "需要重构建议" | `analyze -i refactor -t "src/"` | `cycles` + `complexity` | JSON |
+| "修改 XXX 会影响什么" | `impact -f "XXX" -t -j` | `analyze -i read -t "XXX" --scope transitive --json` | 机器可读优先 |
+| "XXX 模块依赖什么" | `deps -m "XXX" -j` | `analyze -i link -t "XXX" --json` | 机器可读优先 |
+| "代码质量如何" | `complexity -f "src/file.ts" -j` | `analyze -i read -t "src/file.ts" --json` | 机器可读优先 |
+| "查找与 XXX 相关的代码" | `query -S "XXX" -j` | `analyze -i find -k "XXX" --json` | 机器可读优先 |
+| "这个改动安全吗" | `ci assess-risk` | `analyze -i read -t "目标文件" --scope transitive --json` | 文本 |
+| "需要重构建议" | `cycles` + `complexity` | `analyze -i read -t "src/" --json` | 机器可读优先 |
 | "查找循环依赖" | `cycles` | - | 文本 |
 | "有哪些测试文件" | `query -S ".test.ts"` | - | 文本 |
 
@@ -96,14 +111,14 @@ cat .mycodemap/AI_MAP.md
 |------|------|---------|
 | 代码地图生成 | `generate` | 首次理解项目结构 |
 | 符号查询 | `query -s` | 查找类/函数定义位置 |
-| 依赖分析 | `deps` / `analyze -i dependency` | 理解模块关系 |
-| 影响分析 | `impact` / `analyze -i impact` | 评估变更范围 |
-| 复杂度分析 | `complexity` / `analyze -i complexity` | 识别复杂代码 |
+| 依赖分析 | `deps` / `analyze -i link` | 理解模块关系 |
+| 影响分析 | `impact` / `analyze -i read` | 评估变更范围 |
+| 复杂度分析 | `complexity` / `analyze -i read` | 识别复杂代码 |
 | 循环依赖检测 | `cycles` | 发现架构问题 |
 | 统一分析 | `analyze` | 多意图智能路由 |
+| 结果导出 | `export` | 导出 JSON / GraphML / Mermaid |
 | CI 门禁 | `ci` | 代码质量检查 |
-| 工作流编排 | `workflow` | 复杂任务管理 |
-| HTTP API | `server` | 远程访问分析能力 |
+| 工作流编排（analysis-only） | `workflow` | 复杂分析任务管理 |
 
 ---
 
@@ -112,3 +127,4 @@ cat .mycodemap/AI_MAP.md
 - 需要完整命令参数？查看 [COMMANDS.md](./COMMANDS.md)
 - 需要解析 JSON 输出？查看 [OUTPUT.md](./OUTPUT.md)
 - 需要即用型提示词？查看 [PROMPTS.md](./PROMPTS.md)
+- 需要理解哪些命令仍属边界/兼容 surface？查看 [COMMANDS.md](./COMMANDS.md) 中的边界说明

package/docs/ai-guide/README.md

@@ -1,6 +1,10 @@
 # AI Guide 文档目录
 
-> 专为 AI 大模型和 Agent 设计的 CodeMap 使用指南
+> 专为 AI/Agent 设计的 CodeMap 使用指南。
+>
+> CodeMap 是一个 AI-first 代码地图工具；AI/Agent 是主要消费者。  
+> 入口层优先聚焦 `generate`、`query`、`deps`、`impact`、`complexity`、`export`、`ci` 等核心分析能力。  
+> `workflow` 是当前公开的 analysis-only 工作流能力，`ship` 仍是公开的过渡能力；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
 
 ---
 
@@ -17,6 +21,17 @@
 
 ---
 
+## 使用原则
+
+| 原则 | 说明 |
+|------|------|
+| AI-first 入口 | 优先从 `AI_GUIDE.md`、`QUICKSTART.md`、`OUTPUT.md` 建立对产品和契约的理解 |
+| 机器可读优先 | 当前 CLI 过渡现实下，大多数命令仍用 `--json` 暴露机器可读结果 |
+| 人类可读显式入口 | `analyze` 当前支持 `--output-mode human`；其余命令按现有文本输出使用 |
+| 边界优先 | `Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令 |
+
+---
+
 ## 快速开始
 
 ### 如果你是 AI/Agent
@@ -25,6 +40,8 @@
 2. **然后参考**: `PROMPTS.md` - 使用提示词模板开始任务
 3. **遇到问题时**: `INTEGRATION.md` - 查看错误处理方法
 
+**建议顺序**：先理解产品定位，再进入命令细节；不要把 `workflow`、`ship` 当成首次接触项目时的主入口，也不要把已移除的 `server`、`watch`、`report`、`logs` 当成现行命令。
+
 ### 如果你是开发者
 
 1. **查看**: `PROMPTS.md` - 选择适合场景的提示词模板
@@ -39,9 +56,9 @@
 | 文档 | 行数 | 核心内容 |
 |------|------|---------|
 | QUICKSTART.md | ~120 | 决策树、场景映射 |
-| COMMANDS.md | ~350 | 16个命令完整参数 |
-| OUTPUT.md | ~320 | JSON 结构、解析工具 |
-| PATTERNS.md | ~290 | 6种工作流模式 |
+| COMMANDS.md | ~350 | 核心分析命令 + 移除命令迁移说明 |
+| OUTPUT.md | ~320 | 目标契约、当前 CLI 现实与 JSON 结构 |
+| PATTERNS.md | ~290 | 核心分析模式 + 过渡 workflow 说明 |
 | PROMPTS.md | ~300 | 8个提示词模板 |
 | INTEGRATION.md | ~420 | MCP、Skill、错误处理 |
 | **总计** | **~1800** | **完整 AI 使用指南** |
@@ -51,6 +68,7 @@
 ## 主索引
 
 项目根目录的 `AI_GUIDE.md` 是主索引文档，包含：
+- 产品定位与目标用户
 - 项目速览
 - 命令选择速查表
 - 文档导航