@mycodemap/mycodemap 0.1.1 → 0.3.4

package/CHANGELOG.md

@@ -2,6 +2,169 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.4] - 2026-03-23 - CI Pipeline Fixes
+
+### 🔧 Configuration
+
+- **CI**: 修复 `.gitignore` 规则，允许 `scripts/*.js` 用于 CI 验证
+- **CI**: 添加 `docs/rules/testing.md` 到 git 跟踪
+- **CI**: 移除无效的 `ai-feed.txt` git diff 检查
+- **package**: 添加 `package-lock.json` 到 git 解决 CI 依赖问题
+
+## [0.3.3] - 2026-03-23 - Ship Command Improvements
+
+### 🐛 Bug Fixes
+
+- **ship**: 修复 commit 解析支持 `[TYPE]` 格式
+- **ship**: 修复 conventional commits 校验正则表达式
+- **ship**: 添加 CONFIG/INFRA 类型支持
+- **ship**: 修复版本 commit message 格式 (使用 CONFIG 标签)
+
+### 🔧 Configuration
+
+- **ship**: 同步 package.json 与 CHANGELOG 版本
+
+## [0.3.0] - 2026-03-23 - One-Click Ship Command
+
+### 🚀 New Features
+
+- **ship**: 新增 `codemap ship` 一键智能发布命令
+  - 自动分析 commits 并检测变更类型
+  - 基于 conventional commits 规范计算版本号
+  - mustPass/shouldPass 质量检查 + 置信度评分
+  - npm 发布（支持 OIDC 认证）+ git tag
+  - GitHub Actions CI 状态轮询监控
+
+### 📦 CLI Enhancements
+
+- **新增命令**: `codemap ship [--dry-run] [--verbose] [--yes]`
+  - `--dry-run`: 仅分析不发布
+  - `--verbose`: 显示详细输出
+  - `--yes`: 置信度 60-75 时自动确认
+
+## [0.2.1] - 2026-03-23 - AI Documentation & Quality Improvements
+
+### 🐛 Bug Fixes
+
+- **export**: 修复 Mermaid 导出空输出问题，正确保存到 MVP3 存储
+- **cli**: 修复 export 命令 Mermaid 格式输出为空的问题
+- **orchestrator**: 修复 test-linker 中 glob ESM 导入问题
+
+### 📚 Documentation Enhancements
+
+#### AI 友好文档系统
+- 新增 `AI_GUIDE.md` - AI 专属快速参考文档
+- 新增 `docs/ai-guide/` 目录结构，包含：
+  - `QUICKSTART.md` - 快速开始与场景映射
+  - `COMMANDS.md` - 完整 CLI 命令参数参考
+  - `OUTPUT.md` - JSON 输出结构与 TypeScript 类型定义
+  - `PATTERNS.md` - 标准工作流模式
+  - `PROMPTS.md` - 即用型提示词模板
+  - `INTEGRATION.md` - 错误处理与 MCP 集成
+
+#### 文档质量保障
+- 新增 `docs/AI_ASSISTANT_SETUP.md` - AI 助手配置指南
+- 新增 `docs/SETUP_GUIDE.md` - 完整安装设置指南
+- 更新 `docs/rules/architecture-guardrails.md` - 架构约束规则增强
+- 更新 `docs/rules/engineering-with-codex-openai.md` - 工程规范更新
+
+### 🔧 Developer Experience
+
+#### CLI 改进
+- `docs:check` 脚本升级，同步验证人类文档和 AI 文档
+- 新增独立验证命令：
+  - `npm run docs:check:human` - 仅验证人类文档
+  - `npm run docs:check:ai` - 仅验证 AI 文档
+- 新增 `npm run release` - 标准化发布流程
+
+#### 验证流程
+- `check:all` 整合文档检查，更严格的质量门禁
+- 发布工作流 (`.github/workflows/publish.yml`) 优化
+
+### 📦 Dependencies
+
+- 新增 `scripts/validate-ai-docs.js` - AI 文档验证脚本
+
+---
+
+## [0.2.0] - 2026-03-17 - MVP3 Architecture Release
+
+### 🏗️ MVP3 分层架构重构
+
+CodeMap 完成重大架构升级，采用清晰的分层架构设计：Interface → Infrastructure → Domain → Server → CLI
+
+#### Interface Layer
+- 核心类型定义中心 (`src/interface/types/`)
+- 存储接口契约 (`IStorage`, `IStorageFactory`)
+- 解析器接口契约 (`ILanguageParser`, `IParserRegistry`)
+
+#### Infrastructure Layer
+- **存储抽象**: 支持多种存储后端
+  - `FileSystemStorage` - 文件系统存储（默认）
+  - `MemoryStorage` - 内存存储（测试用）
+  - `KuzuDBStorage` - KùzuDB 图数据库（可选）
+  - `Neo4jStorage` - Neo4j 图数据库（可选）
+  - `StorageFactory` - 自动选择存储后端
+- **解析器抽象**: 多语言支持架构
+  - `ParserBase` - 解析器抽象基类
+  - `ParserRegistry` - 解析器注册表
+  - `TypeScriptParser` - TypeScript/JavaScript 解析
+  - `GoParser` - Go 语言解析
+  - `PythonParser` - Python 解析
+- **仓库实现**: `CodeGraphRepositoryImpl` 连接 Domain 和 Infrastructure
+
+#### Domain Layer
+- 领域实体: `Project`, `Module`, `Symbol`, `Dependency`
+- 聚合根: `CodeGraph`
+- 领域服务: `CodeGraphBuilder`
+- 领域事件: `DomainEvent` 及其子类
+- 仓库接口: `CodeGraphRepository`
+
+#### Server Layer
+- HTTP API 服务器 (`CodeMapServer`)
+- RESTful 端点设计
+- `QueryHandler` - 查询处理
+- `AnalysisHandler` - 分析处理
+- 支持 CORS、健康检查、错误处理
+
+#### CLI Layer (MVP3 集成)
+- 新增 `server` 命令 - 启动 HTTP API 服务器
+- 新增 `export` 命令 - 导出代码图到多种格式
+
+### Added
+
+#### New CLI Commands
+- `mycodemap server` - 启动 HTTP API 服务器 (`-p`, `--host`, `--cors`, `--open`)
+- `mycodemap export` - 导出代码图 (`json`, `graphml`, `dot`, `mermaid`)
+
+#### HTTP API Endpoints
+- `GET /api/v1/health` - 健康检查
+- `GET /api/v1/stats` - 项目统计
+- `GET /api/v1/search/symbols?q=` - 符号搜索
+- `GET /api/v1/modules/:id` - 模块详情
+- `GET /api/v1/symbols/:id` - 符号详情
+- `POST /api/v1/analysis/impact` - 影响分析
+- `GET /api/v1/analysis/cycles` - 循环依赖检测
+- `GET /api/v1/graph` - 依赖图数据
+- `GET /api/v1/export/:format` - 数据导出
+
+#### Dependencies
+- `hono` - 轻量级 HTTP 框架
+- `@hono/node-server` - Node.js 服务器适配器
+
+### Test Coverage
+- 新增 37 个单元测试，总计 **742 个测试全部通过**
+- Domain 实体测试 (Project, Module)
+- Parser 测试 (ParserRegistry, TypeScriptParser)
+- Repository 测试 (CodeGraphRepositoryImpl)
+
+---
+
+## [0.1.2] - 2026-03-20
+
+### Changed
+- 文档同步更新：CLI 命令列表、MVP3 架构描述、代码示例全面刷新
+
 ## [0.1.1] - 2026-03-07
 
 ### Added

package/README.md

@@ -2,11 +2,14 @@
 
 > TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文
 
-CodeMap 是一个专为 TypeScript/JavaScript 项目设计的代码分析工具。它通过静态分析自动生成项目的结构化代码地图，帮助 AI 编程助手（如 Claude、Copilot）快速理解项目架构、模块关系和代码上下文。
+CodeMap 是一个专为 TypeScript/JavaScript/Go 项目设计的代码分析工具。它通过静态分析自动生成项目的结构化代码地图，帮助 AI 编程助手（如 Claude、Copilot）快速理解项目架构、模块关系和代码上下文。
 
 ## 特性
 
+- **分层架构 (MVP3)** - 清晰的分层设计：Interface → Infrastructure → Domain → Server → CLI
 - **双层解析模式** - 提供 `fast`（快速正则）和 `smart`（TypeScript AST）两种解析模式，按需平衡速度与精度
+- **多语言支持** - 支持 TypeScript/JavaScript、Go、Python（可扩展架构）
+- **HTTP API 服务器** - 内置 REST API 服务器，支持查询、分析、导出
 - **多格式输出** - 自动生成 `AI_MAP.md`（全局概览）、`CONTEXT.md` + `context/`（模块上下文）、`codemap.json`（结构化数据）
 - **依赖图可视化** - 生成 Mermaid 格式的模块依赖关系图
 - **增量缓存** - 基于文件哈希的 LRU 缓存机制，仅重新分析变更文件
@@ -17,6 +20,7 @@ CodeMap 是一个专为 TypeScript/JavaScript 项目设计的代码分析工具
 - **工作流编排** - v2.5 新增：6 阶段智能工作流 (reference → impact → risk → implementation → commit → ci)
 - **CI 门禁** - v2.5 新增：提交格式检查、风险评估、输出契约验证
 - **插件系统** - 可扩展的插件架构，支持自定义分析和输出
+- **存储抽象** - 支持文件系统、内存、KùzuDB、Neo4j 多种存储后端
 
 ## 安装
 
@@ -36,6 +40,10 @@ npm install -g @mycodemap/mycodemap
 
 **环境要求**: Node.js >= 18.0.0
 
+**MVP3 新依赖**:
+- `hono` - HTTP 服务器框架
+- `@hono/node-server` - Node.js 适配器
+
 ## 快速开始
 
 ```bash
@@ -58,12 +66,36 @@ ls .mycodemap/
 
 ## 文档导航
 
+### 人类用户
+
 | 文档 | 目标读者 | 内容 |
 |------|----------|------|
+| [🧭 文档索引](docs/README.md) | 所有读者 | 文档分层、阅读顺序与迁移状态 |
+| [🏗️ 架构总图](ARCHITECTURE.md) | 开发者 | 系统地图、模块边界、主执行流 |
+| [📋 MVP3 实施路线图](docs/exec-plans/MVP3-IMPLEMENTATION-ROADMAP.md) | 开发者 | 分层架构重构完整计划与状态 |
 | [📖 安装配置指南](docs/SETUP_GUIDE.md) | 人类开发者 | 完整的安装、配置和使用指南 |
-| [🤖 AI 助手集成指南](docs/AI_ASSISTANT_SETUP.md) | AI 用户 | Kimi/Claude/Codex/Copilot 配置指引 |
 | [📁 配置示例](examples/) | 所有用户 | 各平台的现成配置文件 |
 
+### 🤖 AI / Agent 专属文档
+
+> 如果你是 AI 助手或 Agent，**请优先阅读以下文档**：
+
+| 文档 | 说明 |
+|------|------|
+| **[📘 AI_GUIDE.md](AI_GUIDE.md)** | **AI 主指南** - 快速参考、命令选择决策树、提示词模板速用 |
+| **[🚀 docs/ai-guide/QUICKSTART.md](docs/ai-guide/QUICKSTART.md)** | 快速开始、场景-命令映射表 |
+| **[📚 docs/ai-guide/COMMANDS.md](docs/ai-guide/COMMANDS.md)** | 完整 CLI 命令参考 |
+| **[📊 docs/ai-guide/OUTPUT.md](docs/ai-guide/OUTPUT.md)** | JSON 输出结构解析 |
+| **[🔄 docs/ai-guide/PATTERNS.md](docs/ai-guide/PATTERNS.md)** | 标准工作流模式 |
+| **[💬 docs/ai-guide/PROMPTS.md](docs/ai-guide/PROMPTS.md)** | 即用型提示词模板 |
+| **[🔧 docs/ai-guide/INTEGRATION.md](docs/ai-guide/INTEGRATION.md)** | 集成指南、错误处理 |
+| **[🛡️ AGENTS.md](AGENTS.md)** | 仓库级强约束、任务分级、代码红线 |
+| **[⚡ CLAUDE.md](CLAUDE.md)** | AI 执行手册、验收清单 |
+| **[🤖 docs/AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)** | AI 助手配置指引 |
+| **[🛠️ docs/rules/engineering-with-codex-openai.md](docs/rules/engineering-with-codex-openai.md) | 面向 agent 的工程约束 |
+
+**AI 快速入口**: `.cursorrules` | `.github/copilot-instructions.md`
+
 ## CLI 命令
 
 ### `mycodemap init`
@@ -150,7 +182,7 @@ mycodemap query -S "plugin" -l 5       # 限制结果数量
 | `-m, --module <path>` | 查询模块信息 | - |
 | `-d, --deps <name>` | 查询依赖关系 | - |
 | `-S, --search <word>` | 模糊搜索 | - |
-| `-l, --limit <number>` | 限制结果数量 | `20` |
+| `-l, --limit <number>` | 限制结果数量 | `50` |
 | `-j, --json` | 以 JSON 格式输出 | - |
 
 ### `mycodemap deps`
@@ -256,6 +288,48 @@ mycodemap logs clear -d 30 --confirm  # 清理 30 天前的日志
 | `--format <format>` | 导出格式 (`json`/`txt`) | `json` |
 | `-c, --confirm` | 确认清理操作 | - |
 
+### `mycodemap server` (MVP3)
+
+启动 CodeMap HTTP API 服务器。
+
+```bash
+mycodemap server                   # 启动服务器 (默认端口 3000)
+mycodemap server -p 8080           # 指定端口
+mycodemap server -p 3000 --open    # 自动打开浏览器
+mycodemap server --cors            # 启用 CORS
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-p, --port <number>` | 服务器端口 | `3000` |
+| `-h, --host <string>` | 服务器主机 | `0.0.0.0` |
+| `--cors` | 启用 CORS | `false` |
+| `--open` | 自动打开浏览器 | `false` |
+
+**API 端点：**
+- `GET /api/v1/health` - 健康检查
+- `GET /api/v1/stats` - 项目统计
+- `GET /api/v1/search/symbols?q=` - 符号搜索
+- `GET /api/v1/modules/:id` - 模块详情
+- `POST /api/v1/analysis/impact` - 影响分析
+- `GET /api/v1/export/:format` - 导出数据
+
+### `mycodemap export` (MVP3)
+
+导出代码图到各种格式。
+
+```bash
+mycodemap export json              # 导出为 JSON
+mycodemap export graphml           # 导出为 GraphML (Gephi 兼容)
+mycodemap export dot               # 导出为 DOT (Graphviz)
+mycodemap export mermaid           # 导出为 Mermaid 语法
+mycodemap export json -o ./out     # 指定输出路径
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-o, --output <path>` | 输出文件路径 | 自动根据格式生成 |
+
 ## 工作流编排 (v2.5)
 
 CodeMap v2.5 引入智能工作流编排系统，将复杂任务分解为 6 个有序阶段，每个阶段自动分析并传递上下文。
@@ -375,6 +449,12 @@ Current phase: reference
 CodeMap 提供 CI 阶段自动检查，确保代码质量。
 
 ```bash
+# 检查 README / docs / CLI 示例是否与仓库事实同步
+npm run docs:check
+
+# 通过统一 CLI 护栏入口复用同一检查
+mycodemap ci check-docs-sync
+
 # 检查提交格式 ([TAG] scope: message)
 mycodemap ci check-commits
 
@@ -460,67 +540,87 @@ mycodemap ci check-output-contract
 
 独立的 Mermaid 依赖关系图文件，可在支持 Mermaid 的 Markdown 渲染器中直接预览。
 
-## 项目架构
+## MVP3 分层架构
+
+CodeMap 采用清晰的分层架构设计（MVP3），各层职责明确：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                            │
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│  │   server    │ │   export    │ │ 原有命令(generate..)│   │
+│  └─────────────┘ └─────────────┘ └─────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                      Server Layer                           │
+│  HTTP API / QueryHandler / AnalysisHandler                  │
+├─────────────────────────────────────────────────────────────┤
+│                       Domain Layer                          │
+│  Project / Module / Symbol / Dependency / CodeGraph         │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                      │
+│  ┌──────────────────┐ ┌──────────────────┐                 │
+│  │ Storage          │ │ Parser           │                 │
+│  │ - FileSystem     │ │ - TypeScript     │                 │
+│  │ - Memory         │ │ - Go             │                 │
+│  │ - KùzuDB         │ │ - Python         │                 │
+│  │ - Neo4j          │ │ - Registry       │                 │
+│  └──────────────────┘ └──────────────────┘                 │
+│  ┌──────────────────┐                                      │
+│  │ Repository       │  CodeGraphRepositoryImpl             │
+│  └──────────────────┘                                      │
+├─────────────────────────────────────────────────────────────┤
+│                     Interface Layer                         │
+│  类型定义与契约 (Types, ILanguageParser, IStorage)          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 架构层说明
+
+| 层级 | 路径 | 职责 | 关键组件 |
+|------|------|------|----------|
+| **CLI** | `src/cli/` | 命令行接口 | `server`, `export`, `generate` 命令 |
+| **Server** | `src/server/` | HTTP API | `CodeMapServer`, `QueryHandler` |
+| **Domain** | `src/domain/` | 核心业务逻辑 | `Project`, `Module`, `CodeGraph` |
+| **Infrastructure** | `src/infrastructure/` | 技术实现 | `Storage`, `Parser`, `Repository` |
+| **Interface** | `src/interface/` | 类型契约 | `types/`, `config/` |
+
+### 项目目录结构
 
 ```
 src/
-  ├── cli/              # CLI 命令入口
-  │   ├── index.ts      # Commander 命令注册
-  │   └── commands/     # 各子命令实现
-  │       ├── analyze.ts    # 统一分析入口（支持多意图路由）
-  │       ├── impact.ts     # 影响范围分析
-  │       ├── deps.ts       # 依赖分析
-  │       ├── complexity.ts # 复杂度分析
-  │       ├── workflow.ts   # 工作流编排命令
-  │       └── ci.ts        # CI 门禁命令
-  ├── core/             # 核心分析引擎
-  │   └── analyzer.ts   # 主分析器
-  ├── parser/           # 解析器层
-  │   ├── interfaces/   # 解析器接口定义 (IParser)
-  │   └── implementations/
-  │       ├── fast-parser.ts   # 快速正则解析器
-  │       └── smart-parser.ts  # TypeScript AST 解析器
-  ├── orchestrator/     # 编排层（v2.5 新增）
-  │   ├── index.ts              # 统一导出
-  │   ├── types.ts              # UnifiedResult 类型定义
-  │   ├── confidence.ts         # 置信度计算
-  │   ├── result-fusion.ts      # 结果融合
-  │   ├── tool-orchestrator.ts  # 工具编排器
-  │   ├── intent-router.ts     # 意图路由
-  │   ├── test-linker.ts       # 测试关联器
-  │   ├── git-analyzer.ts      # Git 分析器
-  │   ├── ai-feed-generator.ts # AI 饲料生成器
-  │   ├── file-header-scanner.ts   # 文件头扫描器
-  │   ├── commit-validator.ts      # 提交验证器
-  │   ├── adapters/                 # 工具适配器
-  │   │   ├── base-adapter.ts      # 适配器基类
-  │   │   ├── codemap-adapter.ts  # CodeMap 适配器
-  │   │   └── ast-grep-adapter.ts # AstGrep 适配器
-  │   └── workflow/               # 工作流模块
-  │       ├── workflow-orchestrator.ts  # 工作流编排器
-  │       ├── workflow-persistence.ts    # 工作流持久化
-  │       ├── phase-checkpoint.ts       # 阶段检查点
-  │       └── config.ts                 # 工作流配置
-  ├── generator/        # 输出生成器
-  │   ├── index.ts      # AI_MAP / JSON / Mermaid 生成
-  │   └── context.ts    # CONTEXT.md 生成
-  ├── cache/            # 缓存系统
-  │   ├── lru-cache.ts  # LRU 缓存实现
-  │   ├── parse-cache.ts    # 解析结果缓存
-  │   └── file-hash-cache.ts # 文件哈希缓存
-  ├── watcher/          # 文件监听
-  │   ├── file-watcher.ts # 文件变更监听
-  │   ├── daemon.ts     # 守护进程管理
-  │   └── watch-worker.ts # 监听工作线程
-  ├── plugins/          # 插件系统
-  │   ├── types.ts      # 插件接口定义
-  │   ├── plugin-registry.ts # 插件注册中心
-  │   ├── plugin-loader.ts   # 插件加载器
-  │   └── built-in/     # 内置插件
-  │       ├── complexity-analyzer.ts # 复杂度分析
-  │       └── call-graph.ts          # 调用图分析
-  └── types/            # 类型定义
-      └── index.ts      # 核心类型
+  ├── cli/                    # CLI 命令入口 (原有 + MVP3 新增)
+  │   ├── commands/
+  │   │   ├── server.ts       # MVP3: HTTP API 服务器
+  │   │   ├── export.ts       # MVP3: 导出命令
+  │   │   ├── generate.ts     # 生成代码地图
+  │   │   ├── query.ts        # 查询命令
+  │   │   └── ...             # 其他命令
+  │   └── index.ts
+  ├── server/                 # MVP3: HTTP API 服务器层
+  │   ├── CodeMapServer.ts    # 主服务器类
+  │   ├── handlers/           # QueryHandler, AnalysisHandler
+  │   └── routes/             # API 路由
+  ├── domain/                 # MVP3: 领域层
+  │   ├── entities/           # Project, Module, Symbol, Dependency
+  │   ├── services/           # CodeGraphBuilder
+  │   ├── events/             # DomainEvent
+  │   └── repositories/       # 仓库接口
+  ├── infrastructure/         # MVP3: 基础设施层
+  │   ├── storage/            # 存储适配器
+  │   │   ├── adapters/       # FileSystem, Memory, KùzuDB, Neo4j
+  │   │   └── StorageFactory.ts
+  │   ├── parser/             # 解析器
+  │   │   ├── interfaces/     # ParserBase
+  │   │   ├── implementations/# TypeScript, Go, Python
+  │   │   └── registry/       # ParserRegistry
+  │   └── repositories/       # 仓库实现
+  ├── interface/              # MVP3: 接口层
+  │   ├── types/              # 核心类型定义
+  │   └── config/             # 配置类型
+  ├── core/                   # 核心分析引擎 (原有)
+  ├── parser/                 # 原有解析器 (逐步迁移到 infrastructure/parser)
+  ├── orchestrator/           # 编排层 (v2.5)
+  └── ...
 ```
 
 ## AI 助手集成
@@ -550,21 +650,91 @@ mkdir -p .agents/skills/codemap
 cp examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
 ```
 
-详细配置请参考 [AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)。
+详细配置请参考 [AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)，设计与规则入口请先看 [docs/README.md](docs/README.md)。
 
 ## 新增 CLI 命令
 
 ### `mycodemap analyze`
 
-统一分析入口，支持多意图路由：
+统一分析入口，支持多意图路由和结构化输出：
+
+```bash
+# 影响分析（查看文件变更影响范围）
+mycodemap analyze -i impact -t src/cli/index.ts
+mycodemap analyze -i impact -t src/cli/index.ts --scope transitive
+mycodemap analyze -i impact -t src/cli/index.ts --include-tests
+
+# 依赖分析
+mycodemap analyze -i dependency -t src/cli/index.ts
+
+# 项目概览
+mycodemap analyze -i overview -t src/orchestrator
+
+# 复杂度分析
+mycodemap analyze -i complexity -t src/domain
+
+# 搜索分析
+mycodemap analyze -i search -k UnifiedResult
+
+# 重构建议
+mycodemap analyze -i refactor -t src/cache
+
+# 引用查找
+mycodemap analyze -i reference -t src/interface/types
+
+# 文档生成
+mycodemap analyze -i documentation -t src/domain/services
+
+# 机器可读输出（JSON）
+mycodemap analyze -i impact -t src/index.ts --json
+mycodemap analyze -i impact -t src/index.ts --structured --json
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-i, --intent <type>` | 分析类型：`impact`/`dependency`/`search`/`documentation`/`complexity`/`overview`/`refactor`/`reference` | `impact` |
+| `-t, --targets <paths...>` | 目标文件/模块路径（必填） | - |
+| `-k, --keywords <words...>` | 搜索关键词（用于 search/documentation 意图） | - |
+| `-s, --scope <scope>` | 范围：`direct`（直接）/`transitive`（传递） | `direct` |
+| `-n, --topK <number>` | 返回结果数量 | `8` |
+| `--include-tests` | 包含测试文件关联 | - |
+| `--include-git-history` | 包含 Git 历史分析 | - |
+| `--json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出（移除自然语言字段，配合 `--json` 使用） | - |
+| `--output-mode <mode>` | 输出模式：`machine`/`human` | `human` |
+
+### `mycodemap ci`
+
+CI Gateway - 代码质量门禁工具：
 
 ```bash
-mycodemap analyze "分析 tool-orchestrator 的影响范围"
-mycodemap analyze --intent impact --file src/cli/index.ts
-mycodemap analyze --intent dependency --file src/cli/index.ts
-mycodemap analyze --intent search "UnifiedResult"
+# 验证提交格式（[TAG] scope: message）
+mycodemap ci check-commits
+mycodemap ci check-commits -c 5
+mycodemap ci check-commits -r origin/main..HEAD
+
+# 验证文件头注释（[META], [WHY]）
+mycodemap ci check-headers
+mycodemap ci check-headers -d src/domain
+mycodemap ci check-headers -f "src/index.ts,src/cli/index.ts"
+
+# 评估变更风险
+mycodemap ci assess-risk
+mycodemap ci assess-risk -t 0.5
+
+# 验证文档同步
+mycodemap ci check-docs-sync
+
+# 验证输出契约
+mycodemap ci check-output-contract
+
+# 检查提交文件数量（限制 10 个文件）
+mycodemap ci check-commit-size
+mycodemap ci check-commit-size -m 15
 ```
 
+支持的提交 TAG 类型：`[REFACTOR]`, `[TEST]`, `[DOCS]`, `[FEAT]`, `[FIX]`, `[CHORE]`, `[PERF]`, `[SECURITY]`, `[BREAKING]`, `[HOTFIX]`, `[MIGRATION]`, `[WIP]`
+
 ## 贡献指南
 
 欢迎提交 Issue 和 Pull Request！
@@ -590,6 +760,10 @@ npm test                  # 功能测试（src/**/*.test.ts）
 npm run benchmark         # 性能基准测试（refer/benchmark-quality.test.ts）
 npm run test:all          # 功能 + 基准（串联执行）
 
+# 文档 / CLI 示例护栏
+npm run docs:check
+node dist/cli/index.js ci check-docs-sync
+
 # 类型检查
 npm run typecheck
 

package/dist/cli/commands/ci.d.ts

@@ -11,12 +11,18 @@ export declare enum CIErrorCode {
     E0008_MISSING_HEADER = "E0008",
     E0009_MISSING_WHY = "E0009",
     E0010_OUTPUT_CONTRACT_VIOLATION = "E0010",
-    E0011_COMMIT_TOO_LARGE = "E0011"
+    E0011_COMMIT_TOO_LARGE = "E0011",
+    E0012_DOCS_GUARDRAIL_FAILED = "E0012"
 }
 /**
  * CI 命令错误信息
  */
 export declare const CI_ERROR_MESSAGES: Record<CIErrorCode, string>;
+export declare function resolveDocsGuardrailScriptPath(projectRoot?: string): string;
+export declare function runDocsGuardrailCheck(options?: {
+    root?: string;
+    projectRoot?: string;
+}): void;
 /**
  * 创建 CI Gateway 命令
  */

package/dist/cli/commands/ci.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ci.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;GAEG;AACH,oBAAY,WAAW;IACrB,2BAA2B,UAAU;IACrC,oBAAoB,UAAU;IAC9B,iBAAiB,UAAU;IAC3B,+BAA+B,UAAU;IACzC,sBAAsB,UAAU;CACjC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMzD,CAAC;AA2dF;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CA0CzC;AAED,eAAO,MAAM,SAAS,SAAoB,CAAC"}
+{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ci.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;GAEG;AACH,oBAAY,WAAW;IACrB,2BAA2B,UAAU;IACrC,oBAAoB,UAAU;IAC9B,iBAAiB,UAAU;IAC3B,+BAA+B,UAAU;IACzC,sBAAsB,UAAU;IAChC,2BAA2B,UAAU;CACtC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAOzD,CAAC;AAcF,wBAAgB,8BAA8B,CAAC,WAAW,GAAE,MAAsB,GAAG,MAAM,CAE1F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAiBjG;AAydD;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAgDzC;AAED,eAAO,MAAM,SAAS,SAAoB,CAAC"}

package/dist/cli/commands/ci.js

@@ -2,6 +2,9 @@
  * [META] CI Gateway CLI 命令
  * [WHY] 提供 CI 门禁相关的子命令
  */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import { Command } from 'commander';
 import { validateCommitMessage, validateRecentCommits, VALID_TAGS } from '../../orchestrator/commit-validator.js';
 import { scanDirectory, scanFileHeader } from '../../orchestrator/file-header-scanner.js';
@@ -17,6 +20,7 @@ export var CIErrorCode;
     CIErrorCode["E0009_MISSING_WHY"] = "E0009";
     CIErrorCode["E0010_OUTPUT_CONTRACT_VIOLATION"] = "E0010";
     CIErrorCode["E0011_COMMIT_TOO_LARGE"] = "E0011";
+    CIErrorCode["E0012_DOCS_GUARDRAIL_FAILED"] = "E0012";
 })(CIErrorCode || (CIErrorCode = {}));
 /**
  * CI 命令错误信息
@@ -27,6 +31,7 @@ export const CI_ERROR_MESSAGES = {
     [CIErrorCode.E0009_MISSING_WHY]: '文件头缺少 [WHY] 注释',
     [CIErrorCode.E0010_OUTPUT_CONTRACT_VIOLATION]: '输出契约校验失败',
     [CIErrorCode.E0011_COMMIT_TOO_LARGE]: 'Commit 包含文件数量超过限制',
+    [CIErrorCode.E0012_DOCS_GUARDRAIL_FAILED]: '文档护栏校验失败',
 };
 /**
  * 单 commit 文件数量限制
@@ -38,6 +43,24 @@ function parseGitDiffFiles(command) {
         .map((line) => line.trim())
         .filter(Boolean);
 }
+export function resolveDocsGuardrailScriptPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, 'scripts', 'validate-docs.js');
+}
+export function runDocsGuardrailCheck(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const scriptPath = resolveDocsGuardrailScriptPath(projectRoot);
+    if (!existsSync(scriptPath)) {
+        throw new Error(`Documentation guardrail script not found: ${scriptPath}`);
+    }
+    const args = [scriptPath];
+    if (options.root) {
+        args.push('--root', options.root);
+    }
+    execFileSync(process.execPath, args, {
+        cwd: projectRoot,
+        stdio: 'inherit',
+    });
+}
 async function getChangedFiles(options) {
     if (options.files) {
         return options.files
@@ -81,6 +104,16 @@ async function getChangedFiles(options) {
         process.exit(1);
     }
 }
+async function checkDocsSyncAction(options) {
+    try {
+        runDocsGuardrailCheck({ root: options.root });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`ERROR: [${CIErrorCode.E0012_DOCS_GUARDRAIL_FAILED}] ${message}`);
+        process.exit(1);
+    }
+}
 /**
  * check-commits 子命令 - 验证 Commit 格式
  */
@@ -462,6 +495,11 @@ export function createCICommand() {
         .option('-f, --files <files>', '逗号分隔的变更文件列表')
         .option('-t, --threshold <number>', '风险阈值 (0-1)', '0.7')
         .action(assessRiskAction);
+    ci
+        .command('check-docs-sync')
+        .description('验证当前仓库高信号文档、CLI 示例与护栏配置是否保持同步')
+        .option('--root <path>', '指定要校验的仓库根目录')
+        .action(checkDocsSyncAction);
     ci
         .command('check-output-contract')
         .description('验证 analyze 命令的输出契约')