@mycodemap/mycodemap 0.1.1 → 0.3.4

package/docs/archive/MYCLAUDE_GUIDE.md

@@ -0,0 +1,305 @@
+# MyClaude 使用指南
+
+> 归档时间：2026-03-15
+> 归档原因：外部工具调研笔记，不属于当前仓库执行协议或现行规则。
+> 当前依据：`docs/references/README.md` 与对应上游官方文档
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
+> 基于官方 README 编写 | 官方仓库: https://github.com/stellarlinkco/myclaude
+
+---
+
+## 1. 系统架构
+
+### 1.1 双智能体核心架构
+
+官方定义 (来源: README.md Core Architecture):
+
+| 角色 | 组件 | 职责 |
+|------|------|------|
+| **Orchestrator** | Claude Code | 规划、上下文收集、验证 |
+| **Executor** | codeagent-wrapper | 代码编辑、测试执行 |
+
+支持的后端: **Codex / Claude / Gemini / OpenCode**
+
+### 1.2 官方 Backend CLI 要求
+
+| 后端 | 必须支持的功能 |
+|------|----------------|
+| Codex | `codex e`, `--json`, `-C`, `resume` |
+| Claude | `--output-format stream-json`, `-r` |
+| Gemini | `-o stream-json`, `-y`, `-r` |
+| OpenCode | `opencode`, stdin mode |
+
+---
+
+## 2. 六大模块 (官方)
+
+官方模块列表 (来源: README.md Modules Overview):
+
+| 模块 | 命令 | 说明 |
+|------|------|------|
+| **do** | `/do` | 5阶段功能开发 (推荐) |
+| **omo** | `/omo` | 多智能体智能路由编排 |
+| **bmad** | `/bmad-pilot` | 6角色敏捷工作流 |
+| **requirements** | `/requirements-pilot` | 轻量级需求到代码 |
+| **essentials** | `/code`, `/debug` 等 | 11核心开发命令 |
+| **sparv** | `/sparv` | SPARV工作流 (Specify→Plan→Act→Review→Vault) |
+| **course** | 组合模块 | 课程开发 |
+| **claudekit** | 组合模块 | do skill + 全局钩子 |
+
+### 2.1 模块选择指南 (官方)
+
+官方推荐 (来源: README.md Workflow Selection Guide):
+
+| 场景 | 推荐命令 |
+|------|----------|
+| 功能开发 | `/do` |
+| Bug调查+修复 | `/omo` |
+| 大型企业项目 | `/bmad-pilot` |
+| 快速原型 | `/requirements-pilot` |
+| 简单任务 | `/code`, `/debug` |
+
+---
+
+## 3. /do 模块 (5阶段开发)
+
+官方描述: "5-phase feature development with codeagent orchestration"
+
+**5阶段流程:**
+
+```
+Phase 1: Understand    → 需求理解 + 代码分析
+Phase 2: Clarify      → 解决阻塞性问题
+Phase 3: Design       → 设计实现计划
+Phase 4: Implement    → 代码实现 + 审查
+Phase 5: Complete     → 完成总结
+```
+
+**使用方式:**
+
+```bash
+/do <任务描述>
+```
+
+---
+
+## 4. /omo 模块 (多智能体编排)
+
+官方描述: "Multi-agent orchestration with intelligent routing"
+
+**智能路由**: 系统会根据任务特征自动选择合适的 agent
+
+**使用方式:**
+
+```bash
+/omo <任务描述>
+```
+
+---
+
+## 5. /bmad-pilot 模块 (6角色敏捷)
+
+官方描述: "BMAD agile workflow with 6 specialized agents"
+
+BMAD 源自独立的 BMAD-METHOD 项目 (https://github.com/bmad-code-org/BMAD-METHOD)，是敏捷开发方法论的 AI 化实现。
+
+**6角色:**
+
+| 角色 | 说明 |
+|------|------|
+| Product Owner | 产品负责人 |
+| Architect | 架构师 |
+| Tech Lead | 技术负责人 |
+| Developer | 开发者 |
+| Code Reviewer | 代码审查者 |
+| QA Engineer | 质量工程师 |
+
+**使用方式:**
+
+```bash
+/bmad-pilot <任务描述>
+```
+
+---
+
+## 6. /requirements-pilot 模块
+
+官方描述: "Lightweight requirements-to-code pipeline"
+
+**适用场景**: 快速原型、明确定义的小功能
+
+**使用方式:**
+
+```bash
+/requirements-pilot <任务描述>
+```
+
+---
+
+## 7. essentials 模块 (11核心命令)
+
+官方列表 (来源: README.md Essentials Commands):
+
+> ask, bugfix, code, debug, docs, enhance-prompt, optimize, refactor, review, test, think
+
+**使用方式:**
+
+```bash
+/code <任务>          # 直接代码生成
+/debug <问题>         # 调试辅助
+/test <模块>         # 测试生成
+/review <代码>        # 代码审查
+/refactor <代码>      # 重构
+/optimize <代码>     # 性能优化
+/docs <主题>         # 文档生成
+/ask <问题>          # 知识问答
+/bugfix <问题>       # Bug修复
+/think <问题>        # 深度思考
+/enhance-prompt <内容>  # 提示词优化
+```
+
+---
+
+## 8. /sparv 模块
+
+官方描述: "SPARV workflow (Specify→Plan→Act→Review→Vault)"
+
+**5阶段:**
+
+```
+Specify → Plan → Act → Review → Vault
+```
+
+**使用方式:**
+
+```bash
+/sparv <任务描述>
+```
+
+---
+
+## 9. codeagent-wrapper 使用
+
+### 9.1 核心功能 (官方文档)
+
+- 多后端统一接口: Codex / Claude / Gemini / OpenCode
+- 并行执行: `--parallel`
+- Skill 注入: `--skills`
+- Git Worktree 隔离: `--worktree`
+- 会话恢复: `resume <session_id>`
+
+### 9.2 使用示例
+
+**单 Agent:**
+
+```bash
+codeagent-wrapper --agent explore - . <<'EOF'
+分析代码
+EOF
+```
+
+**并行执行:**
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: t1
+agent: develop
+---CONTENT---
+任务1
+EOF
+
+---TASK---
+id: t2
+agent: develop
+---CONTENT---
+任务2
+EOF
+EOF
+```
+
+### 9.3 环境变量 (官方)
+
+| 变量 | 功能 |
+|------|------|
+| CODEAGENT_BACKEND | 默认后端 |
+| CODEAGENT_PARALLEL | 启用并行 |
+| CODEAGENT_TIMEOUT | 超时(秒) |
+| CODEAGENT_LOG_LEVEL | 日志级别 |
+
+---
+
+## 10. 安装配置
+
+### 10.1 安装命令 (官方)
+
+```bash
+npx github:stellarlinkco/myclaude
+
+npx github:stellarlinkco/myclaude --list
+
+npx github:stellarlinkco/myclaude --update
+```
+
+### 10.2 目录结构 (官方)
+
+```
+~/.claude/
+├── bin/codeagent-wrapper
+├── CLAUDE.md
+├── commands/          (essentials)
+├── agents/            (bmad/requirements)
+├── skills/            (do/omo/sparv/course)
+├── hooks/             (claudekit)
+├── settings.json
+└── installed_modules.json
+```
+
+### 10.3 模块配置 (官方)
+
+```json
+{
+  "modules": {
+    "bmad": { "enabled": false },
+    "do": { "enabled": true },
+    "omo": { "enabled": false }
+  }
+}
+```
+
+---
+
+## 11. 故障排除 (官方)
+
+官方文档 (来源: README.md Troubleshooting):
+
+### Codex wrapper not found
+
+```bash
+npx github:stellarlinkco/myclaude
+# 选择: codeagent-wrapper
+```
+
+### Module not loading
+
+```bash
+cat ~/.claude/installed_modules.json
+npx github:stellarlinkco/myclaude --force
+```
+
+---
+
+## 信息来源
+
+| 内容 | 来源 |
+|------|------|
+| 模块列表 | README.md Modules Overview |
+| 工作流选择 | README.md Workflow Selection Guide |
+| 核心架构 | README.md Core Architecture |
+| 后端要求 | README.md Backend CLI Requirements |
+| Essentials命令 | README.md Essentials Commands |
+| 目录结构 | README.md Directory Structure |
+| 故障排除 | README.md Troubleshooting |
+| BMAD方法论 | https://github.com/bmad-code-org/BMAD-METHOD |

package/docs/archive/PUBLISH_NPM_DESIGN_V1.md

@@ -1,5 +1,11 @@
 # MyCodeMap NPM 发布设计方案
 
+> 归档时间：2026-03-15
+> 归档原因：历史发布方案草稿，已被后续迁移方案和当前实现事实替代。
+> 当前依据：`docs/rules/deployment.md`、`package.json`、`.github/workflows/publish.yml`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
 > 版本: 1.2  
 > 日期: 2026-03-04  
 > 方案: 完整体验版（方案 1，最终审查版）

package/docs/archive/PUBLISH_NPM_DESIGN_V2.md

@@ -1,5 +1,11 @@
 # MyCodeMap NPM 发布设计方案
 
+> 归档时间：2026-03-15
+> 归档原因：历史发布方案草稿，记录迁移过程，不再作为当前发布依据。
+> 当前依据：`docs/rules/deployment.md`、`package.json`、`.github/workflows/publish.yml`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
 > 版本: 2.0
 > 日期: 2026-03-04
 > 状态: 最终方案（待实施）

package/docs/archive/README.md

@@ -0,0 +1,29 @@
+# docs/archive/
+
+本目录存放历史文档、迁移遗留和过期方案。这里的内容只用于复盘与对照，不作为当前执行依据。
+
+## 使用规则
+
+- 归档文档必须写明：归档时间、归档原因、当前依据、状态。
+- 当前事实优先顺序：`AGENTS.md` -> `CLAUDE.md` -> `ARCHITECTURE.md` -> `docs/rules/` -> `docs/exec-plans/` -> 代码与配置事实。
+- 如果需要重启旧方案，不直接“复活”归档文档，而是在现行目录重新建文档并按当前模板收敛。
+
+## 归档索引
+
+| 文件 | 归档时间 | 归档原因 | 当前依据 |
+|---|---|---|---|
+| `AI_INTEGRATION_GUIDE_ARCHIVED.md` | 2026-03-15 | 旧版 AI 集成指南，被当前统一指南替代 | `docs/AI_ASSISTANT_SETUP.md` |
+| `MYCLAUDE_GUIDE.md` | 2026-03-15 | 外部工具调研笔记，非当前仓库规则 | `docs/references/README.md` |
+| `PUBLISH_NPM_DESIGN_V1.md` | 2026-03-15 | 历史发布草案 | `docs/rules/deployment.md`、`package.json` |
+| `PUBLISH_NPM_DESIGN_V2.md` | 2026-03-15 | 历史发布草案 | `docs/rules/deployment.md`、`package.json` |
+| `TASK_DESIGN_COVERAGE_REPORT.md` | 2026-03-15 | 历史覆盖率报告，部分结论已过期 | `docs/exec-plans/completed/2026-03-03-post-task-plan.md`、`src/cli/commands/workflow.ts` |
+| `design-docs/CI_GATEWAY_DESIGN.md` | 2026-03-15 | 历史 CI 设计稿 | `docs/rules/engineering-with-codex-openai.md`、`.github/workflows/ci-gateway.yml` |
+| `design-docs/PUBLISH_NPM_DESIGN_FINAL.md` | 2026-03-15 | 历史迁移设计稿 | `docs/rules/deployment.md`、`.github/workflows/publish.yml` |
+| `design-docs/REFACTOR_ARCHITECTURE_OVERVIEW.md` | 2026-03-15 | 历史重构概要设计，状态冲突 | `ARCHITECTURE.md`、`src/cli/commands/workflow.ts` |
+| `design-docs/REFACTOR_CONFIDENCE_DESIGN.md` | 2026-03-15 | 历史置信度设计稿，结构已偏离实现 | `src/orchestrator/confidence.ts`、`src/orchestrator/types.ts` |
+| `design-docs/REFACTOR_GIT_ANALYZER_DESIGN.md` | 2026-03-15 | 历史 Git 分析设计稿 | `src/orchestrator/git-analyzer.ts`、`docs/rules/engineering-with-codex-openai.md` |
+| `design-docs/REFACTOR_ORCHESTRATOR_DESIGN.md` | 2026-03-15 | 历史编排设计稿，仍混入规划态与旧路径 | `src/cli/commands/workflow.ts`、`src/orchestrator/workflow/` |
+| `design-docs/REFACTOR_RESULT_FUSION_DESIGN.md` | 2026-03-15 | 历史结果融合设计稿 | `src/orchestrator/result-fusion.ts`、`src/orchestrator/types.ts` |
+| `design-docs/REFACTOR_TEST_LINKER_DESIGN.md` | 2026-03-15 | 历史测试关联设计稿 | `docs/rules/testing.md`、`src/orchestrator/test-linker.ts` |
+| `plans/2026-03-14-go-language-support-design.md` | 2026-03-15 | 迁移遗留计划，原目录已废弃且方案未落地 | `docs/exec-plans/README.md` |
+| `product-specs/REFACTOR_REQUIREMENTS.md` | 2026-03-15 | 历史需求草稿，状态仍为待实施 | `ARCHITECTURE.md`、`docs/rules/*`、`src/cli/index.ts` |

package/docs/archive/TASK_DESIGN_COVERAGE_REPORT.md

@@ -1,5 +1,11 @@
 # CodeMap 任务与设计文档覆盖检查报告
 
+> 归档时间：2026-03-15
+> 归档原因：历史覆盖率报告，部分结论已被后续实现状态推翻。
+> 当前依据：`ARCHITECTURE.md`、`docs/exec-plans/completed/2026-03-03-post-task-plan.md`、`src/cli/commands/workflow.ts`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
 > 生成时间: 2026-03-01
 > 检查范围: Phase 1-10 vs 8个设计文档
 

package/docs/archive/TEST_SUMMARY.md

@@ -0,0 +1,140 @@
+# CodeMap 工具测试与修复总结报告
+
+## 📋 测试概览
+
+本次测试模拟了日常开发场景，全面对比了 CodeMap 与传统工具（grep, rg, find）的差异，发现并修复了关键问题。
+
+| 测试项目 | 状态 | 说明 |
+|---------|------|------|
+| 符号搜索对比 | ✅ 完成 | 发现搜索遗漏问题，已修复 |
+| 模块依赖分析 | ✅ 完成 | CodeMap 显著优于 grep |
+| 影响范围分析 | ✅ 完成 | 独有功能，准确率100% |
+| 复杂度分析 | ✅ 完成 | 发现可维护性指数错误，已修复 |
+| 查询与JSON输出 | ✅ 完成 | 功能完整，需优化性能 |
+
+---
+
+## 🔧 修复的问题
+
+### P0 - 严重问题（全部修复）
+
+| 问题 | 影响 | 修复状态 |
+|------|------|----------|
+| 符号搜索遗漏 GitAnalyzer | 搜索功能不完整 | ✅ 已修复 |
+| 可维护性指数全部为100 | 指标完全不可用 | ✅ 已修复 |
+| 未检测 re-export 依赖 | 依赖分析不完整 | ✅ 已修复 |
+| 无查询缓存机制 | 性能不佳 | ✅ 已修复 |
+
+---
+
+## 📊 CodeMap vs 传统工具对比
+
+### 优势场景（推荐使用 CodeMap）
+
+| 场景 | CodeMap | rg/grep | 胜出者 |
+|------|---------|---------|--------|
+| 模块依赖分析 | ⭐⭐⭐⭐⭐ | ❌ 不支持 | CodeMap |
+| 循环依赖检测 | ⭐⭐⭐⭐⭐ | ❌ 极难实现 | CodeMap |
+| 影响范围分析 | ⭐⭐⭐⭐⭐ | ⚠️ 高误报率 | CodeMap |
+| 传递依赖分析 | ⭐⭐⭐⭐⭐ | ❌ 不支持 | CodeMap |
+| 代码复杂度分析 | ⭐⭐⭐⭐ | ❌ 不支持 | CodeMap |
+| 结构化JSON输出 | ⭐⭐⭐⭐⭐ | ❌ 需处理 | CodeMap |
+
+### 劣势场景（推荐使用 rg/grep）
+
+| 场景 | CodeMap | rg/grep | 胜出者 |
+|------|---------|---------|--------|
+| 速度 | 0.5s | 0.008s | rg |
+| 文本搜索 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | rg |
+| 正则表达式 | ⭐⭐ | ⭐⭐⭐⭐⭐ | rg |
+| 代码片段预览 | ⭐⭐ | ⭐⭐⭐⭐⭐ | rg |
+
+---
+
+## 🎯 使用建议
+
+### 推荐使用 CodeMap 的场景
+
+```bash
+# 1. 架构分析
+npx codemap deps                    # 查看项目依赖结构
+npx codemap cycles                  # 检测循环依赖
+
+# 2. 变更影响评估
+npx codemap impact -f src/core.ts --transitive
+
+# 3. 代码质量分析
+npx codemap complexity              # 识别高风险文件
+
+# 4. 符号查询
+npx codemap query -s "ClassName"    # 查找类定义
+npx codemap query -m "src/parser"   # 查看模块信息
+```
+
+### 推荐使用 rg 的场景
+
+```bash
+# 1. 快速文本搜索
+rg "TODO|FIXME" src/
+
+# 2. 正则搜索
+rg "class \w+ extends" src/
+
+# 3. 代码片段预览
+rg -A 3 -B 3 "function name" src/
+```
+
+---
+
+## 📈 修复效果对比
+
+### 修复前 vs 修复后
+
+| 功能 | 修复前 | 修复后 |
+|------|--------|--------|
+| 符号搜索 | 遗漏关键类 | 完整准确 |
+| 可维护性指数 | 全部为100（无用） | 0-100 分布（有价值） |
+| re-export 检测 | 未检测 | 正确识别 |
+| 查询性能 | ~0.5s/次 | 缓存后更快 |
+
+---
+
+## 🔍 仍存在的问题（P1/P2）
+
+| 优先级 | 问题 | 建议 |
+|--------|------|------|
+| P1 | 圈复杂度估算而非精确计算 | 集成 AST 控制流分析 |
+| P1 | JSON details 字段非结构化 | 改为结构化对象 |
+| P2 | 缺少函数级复杂度详情 | 增加函数级分析 |
+| P2 | 性能仍有优化空间 | 考虑 msgpack 序列化 |
+
+---
+
+## 📝 测试输出文件
+
+| 文件 | 内容 |
+|------|------|
+| `comprehensive_test_report.md` | 综合测试报告 |
+| `FIXES_VERIFICATION.md` | 修复验证报告 |
+| `TEST_SUMMARY.md` | 本文件 |
+
+---
+
+## 🎉 总结
+
+CodeMap 在以下方面**显著优于**传统工具：
+- ✅ 语义化代码理解
+- ✅ 依赖关系分析
+- ✅ 影响范围评估
+- ✅ 代码质量分析
+- ✅ 结构化输出
+
+修复后版本 **v0.1.1** 已解决所有严重问题，可以投入日常使用。
+
+---
+
+**测试完成日期**: 2026-03-02  
+**测试版本**: v0.1.0 → v0.1.1  
+**测试项目数**: 5个核心场景  
+**发现问题**: 18个（4个P0已修复，7个P1，7个P2）  
+**修复率**: 100% (P0问题)