@mycodemap/mycodemap 0.4.0 → 0.4.2

package/docs/ai-guide/OUTPUT.md

@@ -4,7 +4,18 @@
 
 ---
 
-## 何时使用 --json
+## Phase 1 契约基线
+
+| 维度 | 目标态 | 当前 CLI 现实 |
+|------|--------|---------------|
+| 机器可读 | 机器可读优先，适合 AI/Agent 继续处理 | 多数命令仍通过 `--json` 显式返回结构化结果 |
+| 人类可读 | 显式的人类阅读入口 | `analyze` 当前支持 `--output-mode human`，其余命令多保留现有文本输出 |
+| analyze 收敛 | 输出契约应逐步收敛 | 当前公共契约已固定为 `find` / `read` / `link` / `show`，legacy alias 通过 `warnings[]` 暴露迁移提示 |
+| 文件发现 | 扫描类命令共享一个文件发现模块 | 先尊重仓库 `.gitignore`，无 `.gitignore` 时回退到默认 `exclude` |
+
+---
+
+## 当前 CLI 现实：何时使用 --json
 
 | 场景 | 使用 `--json` | 原因 |
 |------|--------------|------|
@@ -17,6 +28,88 @@
 
 ---
 
+## 文件发现契约
+
+```typescript
+type DiscoveryFallbackExclude =
+  | "node_modules/**"
+  | "dist/**"
+  | "build/**"
+  | "coverage/**"
+  | "**/*.test.ts"
+  | "**/*.spec.ts"
+  | "**/*.d.ts";
+
+interface DiscoveryContract {
+  gitignore: true;
+  fallbackExclude: DiscoveryFallbackExclude[];
+  sharedBy: ["generate", "analyze", "ci check-headers -d"];
+}
+```
+
+> `generate`、`analyze` 与 `ci check-headers -d` 会共享同一个文件发现模块；若仓库没有 `.gitignore`，则回退到上面的默认排除列表。
+
+---
+
+## generate / codemap.json 插件扩展字段
+
+> 仅当 `mycodemap.config.json` **显式声明** `plugins` 段时，`generate` 输出才会包含 `pluginReport`。
+
+```typescript
+interface PluginDiagnostic {
+  plugin?: string;
+  stage: "load" | "initialize" | "analyze" | "generate";
+  level: "warning" | "error";
+  message: string;
+}
+
+interface PluginExecutionReport {
+  loadedPlugins: string[];
+  generatedFiles: string[];
+  metrics: Record<string, unknown>;
+  diagnostics: PluginDiagnostic[];
+}
+
+interface CodeMap {
+  version: string;
+  generatedAt: string;
+  project: ProjectInfo;
+  summary: ProjectSummary;
+  modules: ModuleInfo[];
+  dependencies: DependencyGraph;
+  actualMode?: "fast" | "smart";
+  pluginReport?: PluginExecutionReport;
+}
+```
+
+### 示例
+
+```json
+{
+  "pluginReport": {
+    "loadedPlugins": ["complexity-analyzer", "my-local-plugin"],
+    "generatedFiles": ["plugins/good.txt"],
+    "metrics": {
+      "complexity-analyzer": {
+        "complexityAnalysis": {
+          "totalCyclomaticComplexity": 17
+        }
+      }
+    },
+    "diagnostics": [
+      {
+        "plugin": "my-local-plugin",
+        "stage": "analyze",
+        "level": "warning",
+        "message": "my-local-plugin warning"
+      }
+    ]
+  }
+}
+```
+
+---
+
 ## query 命令输出结构
 
 ### JSON 输出 (-j)
@@ -101,18 +194,24 @@ interface ContextLine {
 
 ## analyze 命令输出结构
 
+> 当前 `analyze` 的公共契约为 `find` / `read` / `link` / `show`；legacy alias 会在输出中返回 `warnings[]`，其中 `refactor` 不在兼容白名单内。
+
 ### 标准 JSON 输出 (--json)
 
 ```typescript
+type AnalyzeIntent = "find" | "read" | "link" | "show";
+
 interface AnalyzeOutput {
   schemaVersion: "v1.0.0";
-  intent: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "refactor" | "reference";
+  intent: AnalyzeIntent;
   tool: string;
   confidence: {
     score: number;        // 0.0 - 1.0
     level: "high" | "medium" | "low";
   };
   results: AnalyzeResult[];
+  warnings?: AnalyzeWarning[];
+  analysis?: ReadAnalysis | LinkAnalysis | ShowAnalysis;
   metadata: {
     total: number;
     scope: "direct" | "transitive";
@@ -120,6 +219,15 @@ interface AnalyzeOutput {
   };
 }
 
+interface AnalyzeWarning {
+  code: "deprecated-intent";
+  severity: "warning";
+  message: string;
+  deprecatedIntent: "impact" | "dependency" | "search" | "documentation" | "complexity" | "overview" | "reference";
+  replacementIntent: AnalyzeIntent;
+  sunsetPolicy: "2-minor-window";
+}
+
 interface AnalyzeResult {
   file: string;
   location?: {
@@ -131,10 +239,66 @@ interface AnalyzeResult {
   relevance: number;        // 0.0 - 1.0
   metadata?: {
     testFile?: string;      // 关联的测试文件
-    complexity?: number;    // 复杂度分数
-    [key: string]: any;
+    dependencies?: string[];
+    impactCount?: number;
+    complexityMetrics?: {
+      cyclomatic: number;
+      cognitive: number;
+      maintainability: number;
+    };
+    riskLevel?: "high" | "medium" | "low";
+    [key: string]: unknown;
   };
 }
+
+interface ReadAnalysis {
+  intent: "read";
+  impact?: Array<{
+    file: string;
+    changedFiles: string[];
+    transitiveDependencies: string[];
+    impactCount: number;
+    risk: "high" | "medium" | "low";
+  }>;
+  complexity?: Array<{
+    file: string;
+    metrics: {
+      cyclomatic: number;
+      cognitive: number;
+      maintainability: number;
+    };
+    risk: "high" | "medium" | "low";
+  }>;
+}
+
+interface LinkAnalysis {
+  intent: "link";
+  reference?: Array<{
+    target: string;
+    callers: string[];
+    callees: string[];
+  }>;
+  dependency?: Array<{
+    file: string;
+    imports: string[];
+    importedBy: string[];
+  }>;
+}
+
+interface ShowAnalysis {
+  intent: "show";
+  overview?: Array<{
+    title: string;
+    file: string;
+    overview: string;
+    exports: string[];
+  }>;
+  documentation?: Array<{
+    title: string;
+    file: string;
+    content: string;
+  }>;
+}
 ```
 
 ### 纯结构化输出 (--structured --json)
@@ -144,13 +308,15 @@ interface AnalyzeResult {
 ```typescript
 interface StructuredAnalyzeOutput {
   schemaVersion: "v1.0.0";
-  intent: string;
+  intent: AnalyzeIntent;
   tool: string;
   confidence: {
     score: number;
     level: "high" | "medium" | "low";
   };
   results: StructuredResult[];
+  warnings?: AnalyzeWarning[];
+  analysis?: ReadAnalysis | LinkAnalysis | ShowAnalysis;
   metadata: {
     total: number;
     scope: string;
@@ -168,7 +334,7 @@ interface StructuredResult {
   // 注意：没有 content 字段
   relevance: number;
   metadata?: {
-    [key: string]: any;
+    [key: string]: unknown;
   };
 }
 ```
@@ -178,12 +344,22 @@ interface StructuredResult {
 ```json
 {
   "schemaVersion": "v1.0.0",
-  "intent": "impact",
-  "tool": "codemap-impact",
+  "intent": "read",
+  "tool": "codemap-read",
   "confidence": {
     "score": 0.85,
     "level": "high"
   },
+  "warnings": [
+    {
+      "code": "deprecated-intent",
+      "severity": "warning",
+      "message": "legacy intent \"impact\" 已弃用，请改用 \"read\"",
+      "deprecatedIntent": "impact",
+      "replacementIntent": "read",
+      "sunsetPolicy": "2-minor-window"
+    }
+  ],
   "results": [
     {
       "file": "src/cli/commands/analyze.ts",
@@ -192,13 +368,33 @@ interface StructuredResult {
         "line": 45,
         "column": 1
       },
-      "content": "导入自 src/orchestrator/intent-router.ts 的 IntentRouter 类",
+      "content": "被 3 个模块依赖",
       "relevance": 0.95,
       "metadata": {
-        "testFile": "src/cli/commands/analyze.test.ts"
+        "impactCount": 3,
+        "dependencies": [
+          "src/orchestrator/intent-router.ts"
+        ],
+        "riskLevel": "medium"
       }
     }
   ],
+  "analysis": {
+    "intent": "read",
+    "impact": [
+      {
+        "file": "src/cli/commands/analyze.ts",
+        "changedFiles": [
+          "src/cli/commands/analyze.ts"
+        ],
+        "transitiveDependencies": [
+          "src/orchestrator/intent-router.ts"
+        ],
+        "impactCount": 3,
+        "risk": "medium"
+      }
+    ]
+  },
   "metadata": {
     "total": 8,
     "scope": "transitive",

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,7 +182,7 @@ npm test
 
 ---
 
-### 模式 F: 复杂任务管理
+### 模式 F: 复杂分析任务（analysis-only workflow）
 
 **适用场景**: 需要多步骤完成的复杂开发任务
 
@@ -197,14 +209,51 @@ node dist/cli/index.js workflow checkpoint
 # Step 7: 重复直到完成
 ```
 
-**工作流阶段**:
-1. `reference` - 参考搜索
-2. `impact` - 影响分析
-3. `risk` - 风险评估
-4. `implementation` - 代码实现
+**当前工作流阶段**:
+1. `find` - 查找候选符号、文件与关键词线索
+2. `read` - 阅读影响范围、复杂度与上下文
+3. `link` - 汇总依赖、引用与关联关系
+4. `show` - 生成概览、摘要与展示型结果
 5. `commit` - 提交验证
 6. `ci` - CI 验证
 
+> 说明：以上是当前公开实现，不代表最终收敛模型；如果只需要代码地图能力，优先使用前面几个核心分析模式。
+
+---
+
+### 模式 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. **函数级复杂度**（针对复杂文件）
@@ -342,7 +342,7 @@
 
 1. **相关代码搜索**
    ```bash
-   node dist/cli/index.js analyze -i search -k "{{RELATED_KEYWORD}}" --topK 10 --json
+   node dist/cli/index.js analyze -i find -k "{{RELATED_KEYWORD}}" --topK 10 --json
    ```
 
 2. **参考现有实现**
@@ -350,13 +350,13 @@
 
 3. **确定实现位置**
    ```bash
-   node dist/cli/index.js analyze -i complexity -t "候选目录" --json
+   node dist/cli/index.js analyze -i read -t "候选目录" --json
    ```
    选择复杂度最低的模块
 
 4. **影响分析**（如果需要修改现有代码）
    ```bash
-   node dist/cli/index.js analyze -i impact -t "目标文件" --json
+   node dist/cli/index.js analyze -i read -t "目标文件" --json
    ```
 
 5. **实现步骤**
@@ -394,6 +394,7 @@
 | 看模块关系 | 模板 6: 依赖分析 |
 | 找复杂代码 | 模板 7: 复杂度分析 |
 | 做新功能 | 模板 8: 新功能实现 |
+| 验证自动发布 | 模板 9: ship 发布验证 |
 
 ### 如何自定义模板
 
@@ -412,3 +413,40 @@
   → 变更影响分析 (模板 2) 
   → 代码审查 (模板 5)
 ```
+
+---
+
+## 模板 9: ship 发布验证
+
+**适用场景**: 需要验证 `codemap ship` 是否会通过 tag push 触发 GitHub Actions，而不是本地直接发布
+
+```markdown
+我需要验证 `codemap ship` 的自动发布链路是否完整。
+
+请执行以下步骤：
+
+1. **先做预检查**
+   ```bash
+   npm run docs:check:pre-release
+   npm run build
+   npm test
+   ```
+
+2. **做无副作用预演**
+   ```bash
+   node dist/cli/index.js ship --dry-run
+   ```
+
+3. **确认发布路径**
+   - 必须是：版本提交 → git tag → `git push` → GitHub Actions → OIDC 发布
+   - 不允许：本地直接执行 `npm publish`
+
+4. **正式执行**
+   ```bash
+   node dist/cli/index.js ship --yes
+   ```
+
+5. **核验结果**
+   - 记录 tag 名称、workflow run URL、GitHub Release URL
+   - 如果失败，记录失败的 job/step，并定位根因
+```

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) 中的边界说明