@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/rules/engineering-with-codex-openai.md

@@ -0,0 +1,202 @@
+# 基于 Codex 的工程落地规则
+
+> 目标：把 OpenAI《Engineering with Codex》里的高信号原则，转成当前 CodeMap 仓库可执行的开发与交付规则。
+> 适用范围：本仓库内使用 Codex / Claude / 其他 agent 进行分析、修改、验证、提交流程。
+
+## 1. 先说边界
+
+- 本项目当前主要交付形态是 npm 包与 CLI，不是长期运行的 Web 服务。
+- 因此这里强调的是 `CLI` / `CI` 护栏，而不是 preview 环境或部署沙箱。
+- 涉及长期稳定知识时，优先写入仓库文档与生成物；不要把关键约束留在聊天记录、口头约定或临时笔记里。
+
+## 2. 核心原则
+
+- 人类掌舵，agent 执行：人类负责定义目标、限制、DoD、依赖和验收；agent 负责检索、实现、验证和补文档。
+- 地图优于手册：入口文档保持短小，只做路由；细节下沉到 `ARCHITECTURE.md`、`docs/rules/`、`docs/design-docs/`、`docs/exec-plans/`。
+- 仓库是记录系统：规则、设计权衡、执行计划、生成产物、失败复盘都应进入版本控制。
+- 检索优先于记忆：优先使用 `node dist/cli/index.js query|analyze|deps|impact` 获取事实，再回退到 `rg`、`find`、直接读文件。
+- 规则优先编码：重复出现的评审意见、输出约束、结构边界，优先落为 CLI 子命令、hook、CI 检查或生成契约，而不是停留在 prose。
+
+## 3. 渐进式上下文披露（Harness 规范）
+
+**原则**：不向 AI 提供超过当前任务决策所需的信息，避免注意力稀释。
+
+**上下文层级**（AI 按优先级读取）：
+
+1. **T0-地图层**（始终提供）：架构说明、类型定义、关键约束文件
+   - `AGENTS.md`（仓库级强约束）
+   - `CLAUDE.md`（执行手册）
+   - `src/types/index.ts`（核心类型）
+
+2. **T1-任务相关层**（动态检索）：通过 CodeMap CLI 或文件路径匹配提供
+   - 当前修改文件的依赖图谱（直接上下游）
+   - 相关测试文件（同名 `.test.ts` 或 `.spec.ts`）
+   - 接口定义（如果实现类，提供接口）
+
+3. **T2-按需获取层**（工具调用）：AI 明确请求时才提供
+   - 具体业务逻辑实现细节
+   - 历史提交记录
+   - 第三方库文档
+
+**禁止行为**：不要将整个 `node_modules` 目录或上千行无关代码粘贴给 AI。
+
+## 4. 当前项目的 CLI 护栏
+
+- 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
+- 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
+- 修改 `analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+  - `--help` 输出与文档示例一致；
+  - 受影响的真实子命令可以在当前仓库运行；
+  - 若涉及机器输出，`--output-mode machine --json` 仍保持纯 JSON 契约。
+- 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
+- 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`。
+- 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
+
+## 5. 当前项目的 CI 护栏
+
+- 本地护栏：
+  - `.githooks/pre-commit` 会执行变更相关测试、文件头检查，并尝试生成 AI feed。
+  - 当变更涉及 README、`docs/`、CLI 入口、测试配置或 CI 配置时，`.githooks/pre-commit` 还会执行 `npm run docs:check`。
+  - `.githooks/commit-msg` 会校验 `[TAG] scope: message` 格式与单次 commit 文件数量。
+- 服务端护栏：
+  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，然后再通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
+- 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
+
+## 6. 代码生成红线详细规范（Harness 规范）
+
+AI 生成代码时，以下模式触发**硬性阻断**：
+
+| 红线规则 | 检测方式 | 阻断标准 | 修复策略 |
+|---------|---------|---------|---------|
+| **敏感信息硬编码** | 正则检测 `"password"`, `"secret"`, `"api_key"`, `"token"` 字面量 | 生产代码中出现明文凭证 | 替换为 `process.env.XXX` 读取 + env 类型声明 |
+| **`any` 类型使用** | `tsc --noImplicitAny` + ESLint `@typescript-eslint/no-explicit-any` | 非边界文件使用 `any` | 推导具体类型或使用 `unknown` + 类型守卫 |
+| **函数超过 50 行** | 代码行数统计（不含空行和注释） | 单函数 >50 行 | 拆分为子函数，保持单一职责 |
+| **未处理 Promise** | ESLint `@typescript-eslint/no-floating-promises` | 异步调用无 `await` 或错误处理 | 添加 `await` 或 `.catch()` 处理 |
+| **`console.log` 遗留** | ESLint `no-console` | 非调试代码包含 `console.log` | 使用 `src/cli/runtime-logger.ts` 替代 |
+| **未使用 import** | ESLint `@typescript-eslint/no-unused-vars` | 存在未引用 import | 自动删除或标记为使用 |
+| **缺少文件头** | `.githooks/pre-commit` 检查 | TS 源文件缺少 `[META]` 或 `[WHY]` | 添加标准文件头注释 |
+
+## 7. 依赖流向规则（Harness 规范）
+
+**第一性原理**：业务逻辑必须与实现细节解耦，确保可测试性和技术栈可替换性。
+
+当前项目采用 **MVP3 分层架构**（从上至下依赖）：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                            │
+│  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
+├─────────────────────────────────────────────────────────────┤
+│                      Server Layer                           │
+│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
+├─────────────────────────────────────────────────────────────┤
+│                       Domain Layer                          │
+│  src/domain/ - 核心业务逻辑，领域实体与服务                   │
+│  - entities/: Project, Module, Symbol, Dependency, CodeGraph │
+│  - services/: CodeGraphBuilder                              │
+│  - events/: DomainEvent                                     │
+│  - repositories/: 仓库接口                                  │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                      │
+│  src/infrastructure/ - 技术实现细节                          │
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
+│  - repositories/: CodeGraphRepositoryImpl                   │
+├─────────────────────────────────────────────────────────────┤
+│                     Interface Layer                         │
+│  src/interface/ - 类型定义与契约，跨层共享的接口              │
+│  - types/: 核心类型定义                                     │
+│  - config/: 配置接口                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**分层依赖规则**（严格自上而下）：
+- CLI → Server → Domain → Infrastructure → Interface
+- **禁止跨层依赖**（如 Domain 层不得导入 CLI 模块）
+- 同层内可以相互依赖
+
+**Enforcement 规则**：
+1. **Domain 层禁止导入**：CLI、Server 层模块
+2. **Infrastructure 层禁止导入**：CLI、Server、Domain 中的具体实现
+3. **Server 层禁止导入**：CLI 层模块
+4. **跨层调用必须通过接口**，依赖 Interface 层契约
+
+**历史架构说明**：
+- MVP3 之前的旧架构（cli→orchestrator→core→parser→generator）已完成迁移
+- 原有 `src/orchestrator/` 部分功能已整合到 Server 层和 CLI 层
+- 原有 `src/core/`、`src/parser/`、`src/generator/` 已迁移到 Domain/Infrastructure 层
+
+**违规检测**：使用 `dependency-cruiser` 或 CodeMap 自身的 `deps` 命令检查跨层依赖。
+
+**违规示例**：
+```typescript
+// ❌ 违规：Domain 层直接依赖 Infrastructure 具体实现
+// src/domain/services/CodeGraphBuilder.ts
+import { FileSystemStorage } from '../infrastructure/storage/FileSystemStorage'; // 错误！
+
+// ✅ 合规：通过 Interface 层契约依赖
+// src/domain/services/CodeGraphBuilder.ts
+import type { IStorage } from '../interface/types/storage'; // 正确：只依赖接口
+```
+
+## 8. 文档与知识落点
+
+- 规则变化：写入 `docs/rules/`
+- 设计权衡：写入 `docs/design-docs/`
+- 执行计划、复盘、技术债：写入 `docs/exec-plans/`
+- 生成物、快照、报告：写入 `docs/generated/`
+- 外部资料摘要：写入 `docs/references/`
+
+如果一次任务无法在 1 天内稳定完成，先拆成更小的执行单元；复杂任务的过程信息不要只留在对话里。
+
+## 9. 失败预演
+
+至少预演一个失败模式，而不是只验证 happy path。当前仓库已经出现过两类高信号风险：
+
+- 文档漂移：例如测试规则曾与真实 `vitest.config.ts` 不一致，导致 agent 按旧规则执行错误命令。
+- 文档检索盲区：当 `analyze documentation` 无法命中文档时，agent 需要立即回退到 `rg` / 直接读文件，并在适用时记录 CodeMap 缺陷，而不是假装"没问题"。
+
+## 10. 最小交付清单（更新版 - Harness 规范）
+
+### 10.1 交付内容
+
+每次 agent 交付至少要说明：
+
+1. **改了什么**：文件清单 + 变更摘要
+2. **为什么改**：需求背景 + 设计决策
+3. **按什么护栏验证**：执行的检查命令和结果
+4. **失败场景或风险模式**：至少一个预演的失败场景
+5. **可信度自评**（见 AGENTS.md 5.1 格式）：确定/推测/需验证/风险
+6. **文档同步说明**：是否更新了相关文档及原因
+
+### 10.2 必须同步文档的触发条件
+
+以下情况**必须**更新对应文档：
+
+| 你的改动 | 必须更新的文档 |
+|---------|--------------|
+| 新增/修改 CLI 命令或参数 | `CLAUDE.md`、`docs/rules/engineering-with-codex-openai.md` |
+| 新增/修改配置项或 Schema | `README.md`、相关配置示例 |
+| 修改类型定义/公共接口 | 接口注释、`docs/rules/` 中相关文档 |
+| 修改 CI/CD 流程 | `docs/rules/validation.md`、`.github/workflows/` |
+| 修改 Git Hooks | `docs/rules/validation.md` |
+| 修改测试规则/覆盖率要求 | `docs/rules/testing.md` |
+| 修改架构分层或依赖规则 | `ARCHITECTURE.md`、`docs/rules/architecture-guardrails.md` |
+| 新增代码质量红线 | `docs/rules/code-quality-redlines.md` |
+| 修改提交格式规范 | `AGENTS.md` |
+| 发现文档与代码不符 | 立即修复对应文档 |
+
+**原则**：若改动会影响其他开发者或 AI 的行为，就必须更新文档。
+
+## 11. 参考来源
+
+- OpenAI Engineering: https://openai.com/engineering/codex/
+- Harness Engineering 方法论：`docs/references/tmp.md`
+- 仓库入口协议：`AGENTS.md`
+- 最小执行手册：`CLAUDE.md`
+- 架构地图：`ARCHITECTURE.md`
+- 当前验证规则：`docs/rules/validation.md`
+- 当前发布规则：`docs/rules/deployment.md`
+- 代码质量红线：`docs/rules/code-quality-redlines.md`
+- 架构护栏：`docs/rules/architecture-guardrails.md`

package/docs/rules/testing.md

@@ -0,0 +1,73 @@
+# 测试规则
+
+> 测试框架、覆盖率要求、基准测试
+
+---
+
+## 测试框架
+
+| 项目 | 配置 |
+|------|------|
+| 框架 | Vitest |
+| 覆盖率工具 | @vitest/coverage-v8 |
+| 目标覆盖率 | >= 80% |
+
+## 测试文件位置
+
+| 类型 | 路径 |
+|------|------|
+| 常规测试 | `src/**/*.test.ts` |
+| 集成测试 | `tests/` 目录（如存在单独集成测试编排） |
+| 基准测试 | `refer/benchmark-quality.test.ts` |
+
+## 测试配置
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', 'refer/**/*.test.ts'],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+    pool: 'threads'
+  }
+});
+```
+
+## 测试要求
+
+- 所有新功能必须附带测试
+- 测试文件命名：`* .test.ts`
+- 使用 `describe` 和 `it` 组织测试用例
+- 使用 `beforeEach`/`afterEach` 管理测试状态
+
+## 基准测试
+
+- 基准查询集：`refer/benchmark-quality.ts`（30 条预定义查询）
+- 基准测试配置：`vitest.benchmark.config.ts`
+- 关键指标：
+  - Token 消耗降低 >= 40%
+  - Hit@8 >= 90%
+
+## 常用命令
+
+```bash
+# 运行所有测试
+npm test
+npx vitest run
+
+# 运行特定测试文件
+npx vitest run src/orchestrator/__tests__/confidence.test.ts
+
+# 运行与变更相关的测试
+npx vitest run --changed
+
+# 运行覆盖率
+npx vitest run --coverage
+
+# 监视模式
+npx vitest watch
+```

package/docs/rules/validation.md

@@ -0,0 +1,39 @@
+# 验证规则
+
+## 最小验证顺序
+
+1. 先验证与你改动最相关的命令、测试或模块。
+2. 若改动影响 agent 路由、CLI 示例、规则文档或测试事实，先执行 `npm run docs:check`。
+3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`。
+4. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
+5. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
+
+## CI Gateway 验证流程
+
+CI Gateway 已集成以下自动检查（按执行顺序）：
+
+1. `npm run docs:check` - 文档护栏检查
+2. `npm run typecheck` - TypeScript 类型检查
+3. `npm run lint` - ESLint 代码质量检查（渐进式规则，0 error 通过）
+4. `npm test` - 单元测试
+5. `npm run build` - 构建验证
+6. CLI 相关检查（commit 格式、文件头等）
+
+## 强约束
+
+- 没有验证，不得声称“已解决”。
+- 失败时优先修根因，不绕过护栏。
+- 涉及 CI / hooks / 输出契约时，必须给出失败场景与修复验证证据。
+- 严禁使用 `--no-verify`、禁用 hooks、删除检查项规避失败。
+
+## 常用命令
+
+```bash
+npm run docs:check
+node dist/cli/index.js ci check-docs-sync
+npm run typecheck
+npm test
+npm run lint
+npm run build
+npm run validate-pack
+```

package/examples/README.md

@@ -0,0 +1,61 @@
+# MyCodeMap 配置示例
+
+本目录包含各种 AI 助手和开发环境的配置示例。
+
+## 目录结构
+
+```
+examples/
+├── kimi/                    # Kimi CLI 配置
+│   └── codemap-skill.md    # Skill 定义文件
+├── claude/                  # Claude Code 配置
+│   └── codemap-skill.md    # Skill 定义文件
+├── codex/                   # Codex CLI 配置
+│   └── codemap-agent.md    # Agent 定义文件
+├── copilot/                 # GitHub Copilot 配置
+│   └── copilot-instructions.md  # 提示词文件
+└── README.md               # 本文件
+```
+
+## 快速使用
+
+### Kimi CLI
+
+```bash
+mkdir -p .kimi/skills/codemap
+cp examples/kimi/codemap-skill.md .kimi/skills/codemap/SKILL.md
+```
+
+### Claude Code
+
+```bash
+mkdir -p .claude/skills/codemap
+cp examples/claude/codemap-skill.md .claude/skills/codemap/SKILL.md
+```
+
+### Codex CLI
+
+```bash
+mkdir -p .agents/skills/codemap
+cp examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
+```
+
+### GitHub Copilot
+
+```bash
+mkdir -p .github
+cp examples/copilot/copilot-instructions.md .github/copilot-instructions.md
+```
+
+## 自定义配置
+
+复制示例文件后，可以根据项目需求进行调整：
+
+1. **修改命令别名** - 如果项目中使用了不同的命令别名
+2. **添加项目特定规则** - 针对项目结构的特殊处理
+3. **调整输出格式** - 根据 AI 助手的解析能力调整
+
+## 更多信息
+
+- [安装配置指南](../docs/SETUP_GUIDE.md)
+- [AI 助手集成指南](../docs/AI_ASSISTANT_SETUP.md)

package/examples/claude/codemap-skill.md

@@ -0,0 +1,94 @@
+# MyCodeMap Code Analysis
+
+## Overview
+
+Use MyCodeMap to analyze TypeScript/JavaScript project structure, query symbols, analyze dependencies, and assess change impact.
+
+## CLI Detection
+
+Detect MyCodeMap CLI availability:
+
+```bash
+# Check global installation
+if command -v mycodemap &> /dev/null; then
+    CODEMAP="mycodemap"
+# Check local installation
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP="./node_modules/.bin/mycodemap"
+# Fallback to npx
+else
+    CODEMAP="npx @mycodemap/mycodemap"
+fi
+```
+
+## Commands
+
+### Generate Code Map
+```bash
+$CODEMAP generate
+```
+Generates: `.mycodemap/AI_MAP.md`, `.mycodemap/CONTEXT.md`, `.mycodemap/codemap.json`
+
+### Query Symbol
+```bash
+$CODEMAP query -s "<symbol-name>"
+$CODEMAP query -s "<symbol-name>" -j  # JSON output
+```
+
+### Query Module
+```bash
+$CODEMAP query -m "<module-path>"
+```
+
+### Search
+```bash
+$CODEMAP query -S "<keyword>" -l 10
+```
+
+### Dependency Analysis
+```bash
+$CODEMAP deps -m "<module-path>"
+$CODEMAP deps -m "<module-path>" -j
+```
+
+### Impact Analysis
+```bash
+$CODEMAP impact -f "<file-path>"
+$CODEMAP impact -f "<file-path>" --transitive
+```
+
+### Cycle Detection
+```bash
+$CODEMAP cycles
+```
+
+### Complexity Analysis
+```bash
+$CODEMAP complexity
+$CODEMAP complexity -f "<file-path>"
+```
+
+## Workflows
+
+### Understanding Project Structure
+
+1. Generate code map: `$CODEMAP generate`
+2. Read `.mycodemap/AI_MAP.md` for overview
+3. Query specific modules as needed
+
+### Before Code Changes
+
+1. Run impact analysis: `$CODEMAP impact -f "<file>" --transitive`
+2. Review affected files
+3. Suggest test cases based on impact
+
+### Finding Code
+
+1. Search symbol: `$CODEMAP query -s "<name>"`
+2. If not found, fuzzy search: `$CODEMAP query -S "<name>"`
+3. Check module context: `$CODEMAP query -m "<path>"`
+
+## Output Format
+
+- Default: Human-readable text
+- JSON: Add `-j` flag for structured data

package/examples/codex/codemap-agent.md

@@ -0,0 +1,66 @@
+# MyCodeMap Skill
+
+## Description
+
+Code analysis tool for TypeScript/JavaScript projects. Provides project structure analysis, symbol querying, dependency analysis, and impact assessment.
+
+## CLI Command Detection
+
+```bash
+# Priority: global > local > npx
+if command -v mycodemap &> /dev/null; then
+    CODEMAP_CMD="mycodemap"
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP_CMD="./node_modules/.bin/mycodemap"
+else
+    CODEMAP_CMD="npx @mycodemap/mycodemap"
+fi
+```
+
+## Available Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `generate` | Generate code map | `$CODEMAP_CMD generate` |
+| `query -s` | Query symbol | `$CODEMAP_CMD query -s "ClassName"` |
+| `query -m` | Query module | `$CODEMAP_CMD query -m "src/parser"` |
+| `query -S` | Fuzzy search | `$CODEMAP_CMD query -S "keyword"` |
+| `deps` | Dependency analysis | `$CODEMAP_CMD deps -m "src/core"` |
+| `impact` | Impact analysis | `$CODEMAP_CMD impact -f "src/index.ts"` |
+| `cycles` | Cycle detection | `$CODEMAP_CMD cycles` |
+| `complexity` | Complexity metrics | `$CODEMAP_CMD complexity` |
+
+## Usage Patterns
+
+### Pattern 1: Project Onboarding
+```
+User: "Explain this project structure"
+Agent:
+1. $CODEMAP_CMD generate
+2. Read .mycodemap/AI_MAP.md
+3. Summarize key components
+```
+
+### Pattern 2: Change Impact
+```
+User: "What happens if I modify X?"
+Agent:
+1. $CODEMAP_CMD impact -f "<path>" --transitive
+2. Analyze output
+3. List affected files and suggest tests
+```
+
+### Pattern 3: Code Navigation
+```
+User: "Where is function Y defined?"
+Agent:
+1. $CODEMAP_CMD query -s "Y"
+2. Report location
+3. Offer to show code context
+```
+
+## Best Practices
+
+- Always generate code map before queries if `.mycodemap/` is stale
+- Use `-j` flag for programmatic processing
+- Use `--transitive` for complete impact analysis

package/examples/copilot/copilot-instructions.md

@@ -0,0 +1,24 @@
+# MyCodeMap Integration
+
+This project uses MyCodeMap for code analysis.
+
+## Available Commands
+
+Before answering questions about project structure, run:
+```bash
+mycodemap generate
+```
+
+Then read `.mycodemap/AI_MAP.md` for context.
+
+## Common Queries
+
+- Find symbol: `mycodemap query -s "<name>"`
+- Check dependencies: `mycodemap deps -m "<path>"`
+- Impact analysis: `mycodemap impact -f "<path>"`
+
+## When Answering
+
+1. Always check the code map first for structural questions
+2. Use impact analysis before suggesting changes
+3. Reference specific files and line numbers

package/examples/kimi/codemap-skill.md

@@ -0,0 +1,92 @@
+---
+name: codemap
+description: MyCodeMap 代码分析技能，用于项目结构分析、符号查询、依赖分析和影响评估。
+---
+
+# MyCodeMap Skill
+
+## 环境检测
+
+首先检测 CLI 是否可用：
+
+```bash
+# 检测全局安装的 mycodemap
+if command -v mycodemap &> /dev/null; then
+    CODEMAP_CMD="mycodemap"
+# 检测本地安装的 mycodemap
+elif [ -f "./node_modules/.bin/mycodemap" ]; then
+    CODEMAP_CMD="./node_modules/.bin/mycodemap"
+# 使用 npx
+else
+    CODEMAP_CMD="npx @mycodemap/mycodemap"
+fi
+```
+
+## 常用命令
+
+### 生成代码地图
+```bash
+$CODEMAP_CMD generate
+```
+
+### 查询符号
+```bash
+$CODEMAP_CMD query -s "<symbol-name>"
+```
+
+### 查询模块
+```bash
+$CODEMAP_CMD query -m "<module-path>"
+```
+
+### 模糊搜索
+```bash
+$CODEMAP_CMD query -S "<keyword>" -l 10
+```
+
+### 依赖分析
+```bash
+$CODEMAP_CMD deps -m "<module-path>"
+```
+
+### 影响范围分析
+```bash
+$CODEMAP_CMD impact -f "<file-path>"
+```
+
+### 循环依赖检测
+```bash
+$CODEMAP_CMD cycles
+```
+
+### 复杂度分析
+```bash
+$CODEMAP_CMD complexity -f "<file-path>"
+```
+
+## 使用场景
+
+### 场景 1：理解项目结构
+
+当用户询问项目结构或特定模块时：
+1. 运行 `$CODEMAP_CMD generate` 生成最新代码地图
+2. 阅读 `.mycodemap/AI_MAP.md` 获取项目概览
+3. 根据需要使用 `query` 或 `deps` 获取详细信息
+
+### 场景 2：代码变更影响分析
+
+当用户要修改某个文件时：
+1. 运行 `$CODEMAP_CMD impact -f "<file-path>" --transitive`
+2. 分析输出结果，告知用户受影响的模块和文件
+
+### 场景 3：查找代码定义
+
+当用户询问某个类/函数的位置时：
+1. 运行 `$CODEMAP_CMD query -s "<symbol-name>"`
+2. 根据结果提供精确的文件路径和行号
+
+## 输出处理
+
+- 直接返回 CLI 输出给用户
+- 使用 `-j` 参数获取 JSON 格式便于解析
+- 复杂输出可重定向到临时文件分析