@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/archive/AI_INTEGRATION_GUIDE_ARCHIVED.md

@@ -0,0 +1,391 @@
+# MyCodeMap AI 集成配置指南
+
+> 归档时间：2026-03-15
+> 归档原因：旧版 AI 集成指南，已被当前仓库的统一 AI 助手接入说明替代。
+> 当前依据：`docs/AI_ASSISTANT_SETUP.md`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
+> 让 AI 大模型（如 Claude、Copilot、Cursor）更好地理解和使用 CodeMap
+
+## 目录
+
+1. [快速开始](#快速开始)
+2. [CLI 安装](#cli-安装)
+3. [AI 助手集成](#ai-助手集成)
+   - [Claude Code](#claude-code-集成)
+   - [VS Code + Copilot](#vs-code--copilot-集成)
+   - [Cursor](#cursor-集成)
+   - [Kimi / 通义千问](#kimi--通义千问-集成)
+4. [配置文件说明](#配置文件说明)
+5. [Git Hooks 配置](#git-hooks-配置)
+6. [常见问题](#常见问题)
+
+---
+
+## 快速开始
+
+```bash
+# 1. 全局安装
+npm install -g @mycodemap/mycodemap
+
+# 2. 初始化项目
+cd your-project
+codemap init
+
+# 3. 生成代码地图
+codemap generate
+```
+
+---
+
+## CLI 安装
+
+### 本地安装（项目内）
+
+```bash
+npm install @mycodemap/mycodemap --save-dev
+
+# 使用 npx
+npx codemap generate
+```
+
+### 全局安装（推荐）
+
+```bash
+npm install -g @mycodemap/mycodemap
+
+# 验证安装
+codemap --version
+```
+
+---
+
+## AI 助手集成
+
+### Claude Code 集成
+
+#### 方式一：复制 Skill 文件（推荐）
+
+在目标项目的 `.claude/skills/` 目录下创建 codemap skill：
+
+```bash
+# 在你的项目根目录
+mkdir -p .claude/skills/codemap
+```
+
+创建 `.claude/skills/codemap/SKILL.md`：
+
+```markdown
+---
+name: codemap
+description: 项目级代码分析技能，用于 TypeScript/JavaScript 项目的结构化分析
+---
+
+# CodeMap 技能
+
+本项目使用 CodeMap 进行代码分析。
+
+## 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `codemap generate` | 生成代码地图 |
+| `codemap query -s "符号"` | 查询符号定义 |
+| `codemap query -m "模块"` | 查询模块信息 |
+| `codemap query -S "关键词"` | 模糊搜索 |
+| `codemap deps -m "模块"` | 依赖分析 |
+| `codemap impact -f "文件"` | 变更影响分析 |
+| `codemap complexity -f "文件"` | 复杂度分析 |
+| `codemap cycles` | 检测循环依赖 |
+
+## 输出文件
+
+- `.codemap/AI_MAP.md` - 项目全局概览
+- `.codemap/codemap.json` - 结构化数据
+- `.codemap/dependency-graph.md` - Mermaid 依赖图
+```
+
+#### 方式二：添加 CLAUDE.md 指引
+
+在项目根目录创建/更新 `CLAUDE.md`：
+
+```markdown
+# 项目 AI 集成
+
+## CodeMap 使用
+
+本项目使用 CodeMap 进行代码分析。
+
+### 常用命令
+
+```bash
+# 生成代码地图
+codemap generate
+
+# 查询符号
+codemap query -s "SymbolName"
+
+# 分析影响
+codemap impact -f src/xxx.ts
+
+# 依赖分析
+codemap deps -m src/parser
+```
+
+### 输出文件
+
+- `.codemap/AI_MAP.md` - 项目全局概览，AI 首先读取此文件
+- `.codemap/codemap.json` - 结构化数据
+- `.codemap/context/` - 各模块详细上下文
+```
+
+#### 方式三：添加 AGENTS.md 指引（详细）
+
+在项目根目录创建 `AGENTS.md`，提供更详细的 AI 助手指南：
+
+```markdown
+# AGENTS.md - 项目开发指南
+
+> 本文档面向 AI 编程助手，介绍项目结构和开发规范
+
+## 项目概述
+
+[项目简介]
+
+## 技术栈
+
+- TypeScript 5.3+
+- Node.js >= 18.0.0
+
+## 代码分析
+
+使用 CodeMap 进行代码分析：
+
+```bash
+# 生成代码地图（首次使用）
+codemap generate
+
+# 查找符号定义
+codemap query -s "SymbolName"
+
+# 查看模块依赖
+codemap deps -m "src/module"
+
+# 分析变更影响
+codemap impact -f "src/file.ts"
+```
+
+## 关键文件
+
+- `codemap.config.json` - CodeMap 配置文件
+- `.codemap/AI_MAP.md` - 项目全局概览
+
+## 开发规范
+
+- 使用 TypeScript Strict Mode
+- 所有非测试文件需要 `[META]` 和 `[WHY]` 头注释
+- 提交格式：`[TAG] scope: message`
+```
+
+### 全局 Skill（所有项目可用）
+
+```bash
+# 找到 Claude Code 全局 skills 目录
+# macOS: ~/Library/Application Support/Claude/skills/
+# Linux: ~/.config/Claude/skills/
+
+mkdir -p "$HOME/.config/Claude/skills/codemap"
+# 将上述 SKILL.md 复制进去
+```
+
+---
+
+### VS Code + Copilot 集成
+
+在项目根目录创建 `.vscode/copilot-instructions.md`：
+
+```markdown
+# Code Analysis
+
+## CodeMap
+
+Use CodeMap for code analysis:
+- Run `codemap generate` to create/update code map
+- Query symbols: `codemap query -s "SymbolName"`
+- Check dependencies: `codemap deps -m "module"`
+- Analyze impact: `codemap impact -f "file.ts"`
+
+## Key Files
+
+- `.codemap/AI_MAP.md` - Project overview for AI
+```
+
+或在 `.vscode/extensions.json` 中推荐：
+
+```json
+{
+  "recommendations": ["ms-azuretools.vscode-docker"]
+}
+```
+
+---
+
+### Cursor 集成
+
+创建 `.cursor/rules/codemap.md`：
+
+```markdown
+## CodeMap
+
+Use CodeMap CLI for code analysis:
+- `codemap generate` - Generate/update code map
+- `codemap query -s "symbol"` - Find symbol definition
+- `codemap query -m "module"` - Get module info
+- `codemap impact -f "file"` - Analyze change impact
+- `codemap deps -m "module"` - Show dependency tree
+
+Project structure is documented in `.codemap/AI_MAP.md`.
+```
+
+---
+
+### Kimi / 通义千问 集成
+
+在 `README.md` 中添加"AI 助手使用说明"章节：
+
+```markdown
+## AI 助手使用说明
+
+本项目使用 CodeMap 生成代码地图。AI 助手可通过以下方式理解项目：
+
+### 快速开始
+
+```bash
+# 安装
+npm install -g @mycodemap/mycodemap
+
+# 生成代码地图
+codemap generate
+```
+
+### 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `codemap query -s "符号"` | 查找符号定义 |
+| `codemap query -m "模块"` | 查看模块信息 |
+| `codemap deps -m "模块"` | 查看依赖树 |
+| `codemap impact -f "文件"` | 分析变更影响 |
+
+### 关键文件
+
+- `.codemap/AI_MAP.md` - 项目全局概览，AI 应首先读取此文件
+- `.codemap/codemap.json` - 结构化数据
+```
+
+---
+
+## 配置文件说明
+
+### codemap.config.json
+
+```json
+{
+  "mode": "hybrid",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules/**", "dist/**"],
+  "output": ".codemap"
+}
+```
+
+### 输出文件
+
+| 文件 | 说明 | AI 读取优先级 |
+|------|------|--------------|
+| `AI_MAP.md` | 项目全局概览 | ⭐⭐⭐ 最高 |
+| `codemap.json` | 结构化数据 | ⭐⭐ |
+| `CONTEXT.md` | 上下文入口 | ⭐⭐ |
+| `context/` | 模块详细上下文 | ⭐ |
+| `dependency-graph.md` | Mermaid 依赖图 | ⭐ |
+
+---
+
+## Git Hooks 配置
+
+### 手动配置
+
+```bash
+# 创建 .githooks 目录
+mkdir -p .githooks
+
+# 创建 pre-commit hook
+cat > .githooks/pre-commit << 'EOF'
+#!/bin/sh
+# CodeMap pre-commit check
+
+if ! command -v codemap &> /dev/null; then
+    exit 0
+fi
+
+# 可选：运行测试
+# npm test
+
+# 可选：检查文件头
+# codemap ci check-headers
+
+exit 0
+EOF
+
+chmod +x .githooks/pre-commit
+
+# 配置 git
+git config core.hookspath .githooks
+```
+
+---
+
+## 常见问题
+
+### Q: codemap 命令找不到
+
+```bash
+# 确认安装
+npm list -g codemap
+
+# 确认路径
+which codemap
+
+# 重新安装
+npm uninstall -g @mycodemap/mycodemap
+npm install -g @mycodemap/mycodemap
+```
+
+### Q: 如何让 AI 理解项目结构？
+
+```bash
+# 1. 生成代码地图
+codemap generate
+
+# 2. 告诉 AI 读取 .codemap/AI_MAP.md
+# 或直接粘贴该文件内容给 AI
+```
+
+### Q: 可以在 CI 中使用吗？
+
+```yaml
+# .github/workflows/codemap.yml
+- name: CodeMap Analysis
+  run: |
+    npm install -g @mycodemap/mycodemap
+    codemap generate
+    codemap ci check-commits --range origin/main..HEAD
+```
+
+---
+
+## 相关链接
+
+- [CodeMap GitHub](https://github.com/stark020/codemap)
+- [CodeMap npm](https://www.npmjs.com/package/@mycodemap/mycodemap)
+- [完整 CLI 文档](../../README.md)

package/docs/archive/ARCHIVE.md

@@ -0,0 +1,39 @@
+# 测试报告归档说明
+
+**归档时间**: 2026-03-03
+**归档文件**: `comprehensive_test_report.md`
+
+---
+
+## 归档原因
+
+该综合测试报告在验证过程中发现**部分关键数据与实际情况不符**，需要归档处理：
+
+### 数据错误
+
+| 项目 | 报告值 | 实际值 |
+|------|--------|--------|
+| TypeScript 文件数 | 104 | 108 |
+| 代码总行数 | 28,878 | 30,846 |
+| 可维护性指数 | 全部为 100 | 实际为 0 (极低) |
+| GitAnalyzer 搜索 | 遗漏 | **已找到** (报告错误) |
+
+### 仍有效的发现
+
+- ✅ 性能问题：比 rg 慢约 90 倍
+- ✅ re-export 依赖遗漏
+- ✅ JSON 输出格式不一致
+- ✅ 路径显示 .js 而非 .ts
+
+---
+
+## 后续建议
+
+1. **重新生成报告**：使用更新后的 CodeMap 版本重新测试
+2. **修正数据**：基于实际运行结果更新数值
+3. **保留方法论**：P0/P1/P2 问题分类方式仍可参考
+4. **跟踪修复**：根据报告中的修复计划验证问题是否解决
+
+---
+
+*归档操作由 Claude Code 执行*

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 |