@mycodemap/mycodemap 0.1.1 → 0.2.0

package/docs/README.md

@@ -0,0 +1,37 @@
+# docs/ - 文档信息架构
+
+本目录采用“入口文档短、细节文档分层”的结构。
+
+## 目录职责
+
+- `docs/rules/`：开发、测试、验证、发布规则。
+- `docs/design-docs/`：当前仍有效的设计文档。
+- `docs/exec-plans/`：活跃计划、已完成计划、技术债跟踪。
+- `docs/generated/`：生成内容与归档说明。
+- `docs/product-specs/`：当前仍有效的产品规格与验收边界。
+- `docs/references/`：外部参考、设计系统、工具链资料。
+- `docs/archive/`：历史方案、迁移遗留、过期文档索引。
+
+## 当前状态
+
+- `docs/` 根层当前只保留仍在使用的操作指南：`AI_ASSISTANT_SETUP.md`、`SETUP_GUIDE.md`。
+- 2026-03-15 已把历史重构设计、历史需求草稿、Go 支持计划和过期计划统一移入 `docs/archive/`。
+- `docs/design-docs/` 与 `docs/product-specs/` 当前不再保留旧稿；历史内容请从 `docs/archive/README.md` 进入。
+- 新增内容优先写入分层目录，不再把新设计或新计划继续堆到根层。
+
+## 建议阅读顺序
+
+1. `../AGENTS.md`
+2. `../CLAUDE.md`
+3. `../ARCHITECTURE.md`
+4. 与任务最相关的 `docs/rules/*`
+5. 与任务最相关的现行文档；如需历史背景，再看 `docs/archive/README.md`
+6. 如需过程信息，再看 `docs/exec-plans/*`
+
+## 维护规则
+
+- 入口文档只做导航，不复述大段细节。
+- 规则进 `docs/rules/`，设计理由进 `docs/design-docs/`，计划进 `docs/exec-plans/`。
+- 需求与验收进 `docs/product-specs/`，生成物说明进 `docs/generated/`，外部资料进 `docs/references/`。
+- 历史文档进入 `docs/archive/`，并补全归档时间、归档原因、当前依据。
+- 若文档更新影响执行协议或入口路径，要同步检查 `AGENTS.md`、`CLAUDE.md`、`ARCHITECTURE.md`、`README.md`。

package/docs/SETUP_GUIDE.md

@@ -178,6 +178,71 @@ mycodemap impact -f src/cli/index.ts
 mycodemap impact -f src/cli/index.ts --transitive
 ```
 
+### 统一分析（analyze）
+
+```bash
+# 影响分析
+mycodemap analyze -i impact -t src/cli/index.ts
+mycodemap analyze -i impact -t src/cli/index.ts --scope transitive --include-tests
+
+# 依赖分析
+mycodemap analyze -i dependency -t src/orchestrator
+
+# 复杂度分析
+mycodemap analyze -i complexity -t src/domain
+
+# 搜索分析
+mycodemap analyze -i search -k "UnifiedResult" --topK 10
+
+# 项目概览
+mycodemap analyze -i overview -t src/
+
+# JSON 输出
+mycodemap analyze -i impact -t src/index.ts --json
+```
+
+### 工作流编排（workflow）
+
+```bash
+# 启动工作流
+mycodemap workflow start "实现用户认证模块"
+mycodemap workflow start "修复登录接口 500" --template bugfix
+
+# 查看当前状态
+mycodemap workflow status
+
+# 可视化工作流
+mycodemap workflow visualize
+
+# 推进到下一阶段
+mycodemap workflow proceed
+
+# 列出所有工作流
+mycodemap workflow list
+```
+
+### CI 门禁（ci）
+
+```bash
+# 检查提交格式
+mycodemap ci check-commits
+mycodemap ci check-commits -c 5
+
+# 检查文件头注释
+mycodemap ci check-headers
+mycodemap ci check-headers -d src/domain
+
+# 评估变更风险
+mycodemap ci assess-risk
+mycodemap ci assess-risk -t 0.5
+
+# 验证输出契约
+mycodemap ci check-output-contract
+
+# 检查提交文件数量
+mycodemap ci check-commit-size
+```
+
 ### 监听模式
 
 ```bash
@@ -270,6 +335,9 @@ fi
 # 可选：运行测试
 # npm test
 
+# 可选：当改动 README / docs / CLI 示例时检查文档护栏
+# npm run docs:check
+
 # 可选：检查文件头
 # mycodemap ci check-headers
 
@@ -304,26 +372,44 @@ jobs:
       
       - name: Install dependencies
         run: npm ci
+
+      - name: Validate docs sync
+        run: npm run docs:check
+
+      - name: Run typecheck
+        run: npm run typecheck
       
       - name: Run tests
         run: npm test
       
       - name: Check commits
         run: npx mycodemap ci check-commits --range origin/main..HEAD
+
+      - name: Check docs sync via CLI
+        run: npx mycodemap ci check-docs-sync
+      
+      - name: Check commit size
+        run: npx mycodemap ci check-commit-size --range origin/main..HEAD
       
       - name: Check headers
         run: npx mycodemap ci check-headers
+
+      - name: Assess risk
+        run: npx mycodemap ci assess-risk --threshold=0.7
       
-      - name: Generate codemap
+      - name: Generate AI feed
         run: npx mycodemap generate
       
-      - name: Check codemap sync
-        run: git diff --exit-code .mycodemap/
+      - name: Check AI feed sync
+        run: git diff --exit-code .mycodemap/ai-feed.txt
+
+      - name: Check output contract
+        run: npx mycodemap ci check-output-contract --schema-version v1.0.0 --top-k 8 --max-tokens 160
 ```
 
 ### 其他 CI 平台
 
-参考 [CI_GATEWAY_DESIGN.md](./CI_GATEWAY_DESIGN.md) 了解所有检查项。
+参考 [CI_GATEWAY_DESIGN.md](./design-docs/CI_GATEWAY_DESIGN.md) 了解所有检查项。
 
 ---
 
@@ -404,4 +490,4 @@ CLI 运行日志默认写入 `.mycodemap/logs/mycodemap-YYYY-MM-DD.log`
 
 - 了解 [AI 助手配置](./AI_ASSISTANT_SETUP.md)
 - 查看 [CLI 完整命令参考](../README.md#cli-命令)
-- 阅读 [架构设计文档](./REFACTOR_ARCHITECTURE_OVERVIEW.md)
+- 阅读 [架构设计文档](./design-docs/REFACTOR_ARCHITECTURE_OVERVIEW.md)

package/docs/ai-guide/COMMANDS.md

@@ -0,0 +1,369 @@
+# AI Guide - 命令参考
+
+> 完整的 CLI 命令详解
+
+---
+
+## 核心命令
+
+### generate - 生成代码地图
+
+```bash
+mycodemap generate                          # hybrid 模式（推荐）
+mycodemap generate -m smart                 # AST 深度分析
+mycodemap generate -m fast                  # 快速正则分析
+mycodemap generate -o ./output              # 指定输出目录
+mycodemap generate --ai-context             # 生成 AI 描述
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-m, --mode <mode>` | 分析模式: fast/smart/hybrid | `hybrid` |
+| `-o, --output <dir>` | 输出目录 | `.mycodemap` |
+| `--ai-context` | 为每个文件生成描述 | - |
+
+**模式说明**:
+- `fast`: 正则匹配，极快，适合大型项目
+- `smart`: AST 分析，较慢，信息完整
+- `hybrid`: 自动选择，文件<50用fast，≥50用smart
+
+---
+
+### query - 查询代码
+
+```bash
+mycodemap query -s "SymbolName"             # 精确查询符号
+mycodemap query -m "src/parser"             # 查询模块
+mycodemap query -d "analyzer"               # 查询依赖
+mycodemap query -S "cache" -l 10            # 模糊搜索
+mycodemap query -s "Symbol" -j              # JSON 输出
+mycodemap query -s "Symbol" --include-references  # 包含引用
+mycodemap query -S "pattern" -r             # 正则搜索
+mycodemap query -c 5                        # 显示上下文5行
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-s, --symbol <name>` | 精确查询符号 | - |
+| `-m, --module <path>` | 查询模块 | - |
+| `-d, --deps <name>` | 查询依赖 | - |
+| `-S, --search <word>` | 模糊搜索 | - |
+| `-l, --limit <number>` | 限制结果数量 | `50` |
+| `-j, --json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+| `-r, --regex` | 使用正则表达式 | - |
+| `-c, --context <lines>` | 显示代码上下文 | `0` |
+| `--include-references` | 包含引用位置 | - |
+
+---
+
+### deps - 依赖分析
+
+```bash
+mycodemap deps                              # 全部依赖
+mycodemap deps -m "src/domain"              # 指定模块
+mycodemap deps -m "src/domain" -j           # JSON 输出
+mycodemap deps -m "src/domain" --structured # 纯结构化
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-m, --module <path>` | 查询指定模块 | - |
+| `-j, --json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+
+---
+
+### impact - 影响分析
+
+```bash
+mycodemap impact -f "src/cli/index.ts"      # 文件变更影响
+mycodemap impact -f "src/cli/index.ts" -t   # 包含传递依赖
+mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-f, --file <path>` | **必填** 指定文件 | - |
+| `-t, --transitive` | 包含传递依赖 | - |
+| `-j, --json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+
+---
+
+### complexity - 复杂度分析
+
+```bash
+mycodemap complexity                        # 项目整体
+mycodemap complexity -f "src/cli/index.ts"  # 指定文件
+mycodemap complexity -d                     # 函数级详情
+mycodemap complexity -j                     # JSON 输出
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-f, --file <path>` | 指定文件 | - |
+| `-d, --detail` | 函数级详情 | - |
+| `-j, --json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+
+---
+
+### cycles - 循环依赖检测
+
+```bash
+mycodemap cycles                            # 检测所有循环依赖
+mycodemap cycles -d 5                       # 指定检测深度
+mycodemap cycles -j                         # JSON 输出
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-d, --depth <number>` | 检测深度 | `5` |
+| `-j, --json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+
+---
+
+## analyze - 统一分析入口
+
+### 8 种分析意图
+
+```bash
+# 1. 影响分析
+mycodemap analyze -i impact -t "src/index.ts"
+mycodemap analyze -i impact -t "src/index.ts" --scope transitive
+mycodemap analyze -i impact -t "src/index.ts" --include-tests
+
+# 2. 依赖分析
+mycodemap analyze -i dependency -t "src/orchestrator"
+
+# 3. 复杂度分析
+mycodemap analyze -i complexity -t "src/domain"
+
+# 4. 搜索分析
+mycodemap analyze -i search -k "UnifiedResult"
+mycodemap analyze -i search -k "keyword" --topK 20
+
+# 5. 项目概览
+mycodemap analyze -i overview -t "src/"
+
+# 6. 重构建议
+mycodemap analyze -i refactor -t "src/cache"
+
+# 7. 引用查找
+mycodemap analyze -i reference -t "src/interface/types"
+
+# 8. 文档生成
+mycodemap analyze -i documentation -t "src/domain/services"
+```
+
+### 输出选项
+
+```bash
+# JSON 输出
+mycodemap analyze -i impact -t "src/index.ts" --json
+
+# 纯结构化（移除自然语言字段）
+mycodemap analyze -i impact -t "src/index.ts" --structured --json
+
+# 机器可读模式
+mycodemap analyze -i impact -t "src/index.ts" --output-mode machine
+
+# 人类可读模式（默认）
+mycodemap analyze -i impact -t "src/index.ts" --output-mode human
+```
+
+### 通用选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-i, --intent <type>` | 分析类型 | `impact` |
+| `-t, --targets <paths...>` | 目标路径（必填） | - |
+| `-k, --keywords <words...>` | 搜索关键词 | - |
+| `-s, --scope <scope>` | 范围: direct/transitive | `direct` |
+| `-n, --topK <number>` | 返回结果数量 | `8` |
+| `--include-tests` | 包含测试文件关联 | - |
+| `--include-git-history` | 包含 Git 历史 | - |
+| `--json` | JSON 格式输出 | - |
+| `--structured` | 纯结构化输出 | - |
+| `--output-mode <mode>` | 输出模式: machine/human | `human` |
+
+---
+
+## ci - CI 门禁
+
+### 子命令
+
+```bash
+# 验证提交格式（[TAG] scope: message）
+mycodemap ci check-commits
+mycodemap ci check-commits -c 5             # 最近 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 "file1.ts,file2.ts"
+
+# 评估变更风险
+mycodemap ci assess-risk
+mycodemap ci assess-risk -t 0.5             # 设置阈值 0.5
+mycodemap ci assess-risk -f "changed.ts"
+
+# 验证文档同步
+mycodemap ci check-docs-sync
+mycodemap ci check-docs-sync --root "/path"
+
+# 验证输出契约
+mycodemap ci check-output-contract
+mycodemap ci check-output-contract -s v1.0.0 -k 8 -t 160
+
+# 检查提交文件数量
+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]`
+
+---
+
+## workflow - 工作流编排
+
+### 生命周期管理
+
+```bash
+# 启动工作流
+mycodemap workflow start "实现用户认证模块"
+mycodemap workflow start "修复登录接口" --template bugfix
+
+# 查看状态
+mycodemap workflow status
+
+# 可视化
+mycodemap workflow visualize
+mycodemap workflow visualize --timeline
+mycodemap workflow visualize --results
+
+# 推进阶段
+mycodemap workflow proceed
+mycodemap workflow proceed --force
+
+# 检查点
+mycodemap workflow checkpoint
+
+# 列出/删除
+mycodemap workflow list
+mycodemap workflow delete "workflow-id"
+
+# 恢复
+mycodemap workflow resume
+mycodemap workflow resume "workflow-id"
+```
+
+### 模板管理
+
+```bash
+mycodemap workflow template list              # 列出模板
+mycodemap workflow template list --all        # 包含内置模板
+mycodemap workflow template info bugfix       # 模板详情
+mycodemap workflow template apply bugfix      # 应用模板
+mycodemap workflow template recommend "任务"  # 推荐模板
+```
+
+### 内置模板
+
+- `refactoring` - 重构任务
+- `bugfix` - 缺陷修复
+- `feature` - 新功能开发
+- `hotfix` - 紧急修复
+
+---
+
+## server - HTTP 服务器
+
+```bash
+mycodemap server                             # 默认端口 3000
+mycodemap server -p 8080                     # 指定端口
+mycodemap server -h 127.0.0.1                # 指定主机
+mycodemap server --cors                      # 启用 CORS
+mycodemap server --open                      # 自动打开浏览器
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-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` | 模块详情 |
+| GET | `/api/v1/symbols/:id` | 符号详情 |
+| POST | `/api/v1/analysis/impact` | 影响分析 |
+| GET | `/api/v1/analysis/cycles` | 循环依赖检测 |
+| GET | `/api/v1/graph` | 依赖图数据 |
+| GET | `/api/v1/export/:format` | 数据导出 |
+
+---
+
+## 其他命令
+
+### watch - 监听模式
+
+```bash
+mycodemap watch                              # 前台监听
+mycodemap watch -d                           # 后台守护进程
+mycodemap watch -s                           # 停止守护进程
+mycodemap watch -t                           # 查看状态
+mycodemap watch -m smart                     # 指定模式
+```
+
+### report - 生成报告
+
+```bash
+mycodemap report                             # 最近 7 天
+mycodemap report -d 14                       # 最近 14 天
+mycodemap report -o ./reports                # 输出目录
+mycodemap report -j                          # JSON 输出
+```
+
+### logs - 日志管理
+
+```bash
+mycodemap logs list                          # 列出日志
+mycodemap logs list -l 20                    # 限制 20 条
+mycodemap logs list --level ERROR            # 仅错误
+mycodemap logs export -d 30                  # 导出 30 天
+mycodemap logs clear -d 30 --confirm         # 清理 30 天前
+```
+
+### export - 导出代码图
+
+```bash
+mycodemap export json                        # JSON 格式
+mycodemap export graphml                     # GraphML (Gephi)
+mycodemap export dot                         # DOT (Graphviz)
+mycodemap export mermaid                     # Mermaid 语法
+mycodemap export json -o ./output.json       # 指定输出
+```
+
+---
+
+## 全局选项
+
+所有命令支持：
+
+| 选项 | 说明 |
+|------|------|
+| `-V, --version` | 显示版本号 |
+| `-h, --help` | 显示帮助信息 |
+| `--no-cache` | 禁用缓存（部分命令） |