@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/PUBLISHING.md

@@ -0,0 +1,162 @@
+# NPM 自动发布指南
+
+> 本文档说明如何配置和触发 @mycodemap/mycodemap 的自动发布流程
+
+## 📋 发布流程概览
+
+```
+本地执行 release.sh → 推送 tag → GitHub Actions → 发布到 NPM
+```
+
+## 🔧 前置配置
+
+### 方式一: NPM Token (推荐，简单)
+
+1. **获取 NPM Token**
+   - 登录 [npmjs.com](https://www.npmjs.com/)
+   - 进入 Access Tokens → Generate New Token → Classic Token
+   - 选择类型: **Automation** (用于 CI/CD)
+   - 复制生成的 token
+
+2. **配置 GitHub Secret**
+   - 进入仓库 Settings → Secrets and variables → Actions
+   - 点击 "New repository secret"
+   - Name: `NPM_TOKEN`
+   - Value: 粘贴刚才复制的 npm token
+   - 点击 "Add secret"
+
+### 方式二: OIDC Trusted Publishing (更安全)
+
+1. **在 NPM 上配置**
+   - 登录 [npmjs.com](https://www.npmjs.com/)
+   - 进入包页面 → Access → Grant Access
+   - 选择 "Automation" → "GitHub Actions"
+   - 配置:
+     - GitHub Organization: `yuanyuanyuan` (或你的组织名)
+     - GitHub Repository: `mycodemap`
+     - Workflow name: `publish.yml`
+
+2. **修改 workflow** (已默认支持)
+   - 当前 `publish.yml` 已同时支持两种方式
+   - 如使用 OIDC，确保不设置 `NPM_TOKEN` secret
+
+## 🚀 发布操作
+
+### 方法 1: 使用发布脚本 (推荐)
+
+```bash
+# 进入项目目录
+cd /path/to/mycodemap
+
+# 发布 patch 版本 (0.2.0 -> 0.2.1)
+./scripts/release.sh patch
+
+# 发布 minor 版本 (0.2.0 -> 0.3.0)
+./scripts/release.sh minor
+
+# 发布 major 版本 (0.2.0 -> 1.0.0)
+./scripts/release.sh major
+
+# 发布指定版本
+./scripts/release.sh 0.2.1
+```
+
+脚本会自动：
+1. 更新 `package.json` 和 `package-lock.json` 中的版本号
+2. 运行完整的代码检查
+3. 提交版本更新
+4. 创建 git tag
+5. 推送到远程仓库
+6. 触发 GitHub Actions 发布流程
+
+### 方法 2: 手动操作
+
+```bash
+# 1. 更新版本号
+npm version patch  # 或 minor, major
+
+# 2. 推送代码和标签
+git push origin main --tags
+
+# 或者直接推送特定标签
+git push origin v0.2.1
+```
+
+### 方法 3: GitHub 网页手动触发
+
+1. 进入仓库 Actions → Publish to NPM
+2. 点击 "Run workflow"
+3. 可选择输入版本号，或直接运行使用当前 package.json 版本
+
+## ✅ 发布前检查清单
+
+- [ ] 更新 `CHANGELOG.md` 记录本次变更
+- [ ] 确保所有测试通过 (`npm test`)
+- [ ] 确保代码检查通过 (`npm run check:all`)
+- [ ] 更新 `README.md` 中的版本说明（如需要）
+- [ ] 确认版本号符合 [semver](https://semver.org/lang/zh-CN/) 规范
+
+## 🔍 验证发布
+
+发布后验证：
+
+```bash
+# 查看 npm 上的最新版本
+npm view @mycodemap/mycodemap version
+
+# 安装测试
+npm install -g @mycodemap/mycodemap
+
+# 验证 CLI 版本
+mycodemap --version
+```
+
+## 🐛 故障排查
+
+### 发布失败: "ENEEDAUTH"
+
+**原因**: NPM_TOKEN 未配置或已过期
+
+**解决**:
+1. 检查 GitHub Secrets 中是否设置了 `NPM_TOKEN`
+2. 确认 token 未过期（npm 上可查看）
+3. 确认 token 有发布权限
+
+### 发布失败: "403 Forbidden"
+
+**原因**: 没有包发布权限
+
+**解决**:
+1. 确认你是该 npm 包的维护者
+2. 如果是 scoped package (@mycodemap/xxx)，确认已设置 `--access public`
+
+### 发布失败: "版本已存在"
+
+**原因**: npm 上已有相同版本
+
+**解决**:
+1. 检查 package.json 中的版本号
+2. npm 版本号不可重复，需要递增
+
+### GitHub Actions 未触发
+
+**原因**: tag 格式不正确或 workflow 配置错误
+
+**解决**:
+1. 确保 tag 格式为 `v*` (例如: v0.2.1)
+2. 检查 `.github/workflows/publish.yml` 是否存在
+3. 查看 Actions 日志排查问题
+
+## 📚 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `.github/workflows/publish.yml` | GitHub Actions 发布工作流 |
+| `scripts/release.sh` | 本地发布助手脚本 |
+| `package.json` | 版本号定义 |
+| `CHANGELOG.md` | 版本变更记录 |
+
+## 🔗 相关链接
+
+- NPM 包页面: https://www.npmjs.com/package/@mycodemap/mycodemap
+- GitHub Actions: https://github.com/yuanyuanyuan/mycodemap/actions

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

@@ -0,0 +1,493 @@
+# MyCodeMap 安装与配置指南
+
+> 面向人类开发者的完整安装、配置和使用指南
+
+---
+
+## 目录
+
+1. [快速开始](#快速开始)
+2. [安装方式](#安装方式)
+3. [初始化配置](#初始化配置)
+4. [日常使用](#日常使用)
+5. [AI 助手集成](#ai-助手集成)
+6. [CI/CD 集成](#cicd-集成)
+7. [故障排除](#故障排除)
+
+---
+
+## 快速开始
+
+### 5 分钟上手
+
+```bash
+# 1. 安装
+npm install -g @mycodemap/mycodemap
+
+# 2. 在项目根目录初始化
+mycodemap init -y
+
+# 3. 生成代码地图
+mycodemap generate
+
+# 4. 查看结果
+ls .mycodemap/
+```
+
+---
+
+## 安装方式
+
+### 方式一：全局安装（推荐）
+
+```bash
+npm install -g @mycodemap/mycodemap
+```
+
+**优点**：
+- 所有项目可用
+- 直接使用 `mycodemap` 命令
+
+### 方式二：项目本地安装
+
+```bash
+npm install --save-dev @mycodemap/mycodemap
+```
+
+**使用**：
+```bash
+npx mycodemap --help
+```
+
+**优点**：
+- 版本锁定
+- 团队协作一致
+- 可作为 npm 脚本使用
+
+### 方式三：使用 npx（无需安装）
+
+```bash
+npx @mycodemap/mycodemap --help
+```
+
+**适用场景**：
+- 临时使用
+- CI/CD 环境
+
+---
+
+## 初始化配置
+
+### 交互式初始化
+
+```bash
+mycodemap init
+```
+
+会询问以下问题：
+- 分析模式（fast/smart/hybrid）
+- 包含的文件路径
+- 排除的文件路径
+- 输出目录
+
+### 使用默认配置
+
+```bash
+mycodemap init -y
+```
+
+生成的配置文件 `mycodemap.config.json`：
+
+```json
+{
+  "$schema": "https://mycodemap.dev/schema/config.json",
+  "mode": "hybrid",
+  "include": ["src/**/*"],
+  "exclude": [
+    "node_modules/**",
+    "dist/**",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ],
+  "output": ".mycodemap"
+}
+```
+
+### 配置选项详解
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `mode` | string | `"hybrid"` | 分析模式：`fast`（快速正则）、`smart`（AST深度分析）、`hybrid`（自动选择） |
+| `include` | string[] | `["src/**/*"]` | 包含的文件 glob 模式 |
+| `exclude` | string[] | 见上 | 排除的文件 glob 模式 |
+| `output` | string | `".mycodemap"` | 输出目录路径 |
+
+---
+
+## 日常使用
+
+### 生成代码地图
+
+```bash
+# 默认 hybrid 模式
+mycodemap generate
+
+# 指定模式
+mycodemap generate -m smart
+
+# 指定输出目录
+mycodemap generate -o ./docs/codemap
+```
+
+### 查询代码
+
+```bash
+# 查询符号
+mycodemap query -s "ModuleInfo"
+
+# 查询模块
+mycodemap query -m "src/parser"
+
+# 模糊搜索
+mycodemap query -S "cache" -l 10
+
+# JSON 输出
+mycodemap query -s "IntentRouter" -j
+```
+
+### 依赖分析
+
+```bash
+# 查看所有依赖
+mycodemap deps
+
+# 查看指定模块依赖
+mycodemap deps -m "src/parser"
+
+# 检测循环依赖
+mycodemap cycles
+```
+
+### 影响范围分析
+
+```bash
+# 分析文件变更影响
+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
+# 前台监听
+mycodemap watch
+
+# 后台守护进程
+mycodemap watch -d
+
+# 查看状态
+mycodemap watch -t
+
+# 停止守护进程
+mycodemap watch -s
+```
+
+---
+
+## AI 助手集成
+
+MyCodeMap 可以与多种 AI 编程助手集成，提升代码理解效率。
+
+### 支持的 AI 助手
+
+| AI 助手 | 配置方式 | 详细文档 |
+|---------|----------|----------|
+| Kimi CLI | Skill 配置 | [AI_ASSISTANT_SETUP.md](./AI_ASSISTANT_SETUP.md#kimi-cli) |
+| Claude Code | Skill 配置 | [AI_ASSISTANT_SETUP.md](./AI_ASSISTANT_SETUP.md#claude-code) |
+| Codex CLI | Agent 配置 | [AI_ASSISTANT_SETUP.md](./AI_ASSISTANT_SETUP.md#codex-cli) |
+| GitHub Copilot | 提示词模板 | [AI_ASSISTANT_SETUP.md](./AI_ASSISTANT_SETUP.md#github-copilot) |
+
+### 快速配置
+
+#### Kimi CLI
+
+```bash
+# 复制示例配置到项目
+cp node_modules/@mycodemap/mycodemap/examples/kimi/codemap-skill.md .kimi/skills/codemap/SKILL.md
+```
+
+#### Claude Code
+
+```bash
+# 复制示例配置
+cp node_modules/@mycodemap/mycodemap/examples/claude/codemap-skill.md .claude/skills/codemap/SKILL.md
+```
+
+#### Codex CLI
+
+```bash
+# 复制示例配置
+cp node_modules/@mycodemap/mycodemap/examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
+```
+
+详细配置步骤请参考 [AI_ASSISTANT_SETUP.md](./AI_ASSISTANT_SETUP.md)。
+
+---
+
+## CI/CD 集成
+
+### Git Hooks（本地门禁）
+
+#### 自动安装
+
+```bash
+# 安装 Git hooks
+npm run postinstall  # 如果 package.json 中配置了
+
+# 或手动安装
+sh scripts/hooks/install-hooks.sh
+```
+
+#### 手动配置
+
+如果项目没有提供 hooks 安装脚本，可以手动配置：
+
+```bash
+# 创建 .githooks 目录
+mkdir -p .githooks
+
+# 创建 pre-commit hook
+cat > .githooks/pre-commit << 'EOF'
+#!/bin/sh
+# MyCodeMap pre-commit check
+
+if ! command -v mycodemap &> /dev/null; then
+    exit 0
+fi
+
+# 可选：运行测试
+# npm test
+
+# 可选：当改动 README / docs / CLI 示例时检查文档护栏
+# npm run docs:check
+
+# 可选：检查文件头
+# mycodemap ci check-headers
+
+exit 0
+EOF
+
+chmod +x .githooks/pre-commit
+
+# 配置 git 使用自定义 hooks 目录
+git config core.hookspath .githooks
+```
+
+### GitHub Actions
+
+创建 `.github/workflows/codemap.yml`：
+
+```yaml
+name: CodeMap CI
+
+on: [push, pull_request]
+
+jobs:
+  codemap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - 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 AI feed
+        run: npx mycodemap generate
+      
+      - 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](./design-docs/CI_GATEWAY_DESIGN.md) 了解所有检查项。
+
+---
+
+## 故障排除
+
+### 常见问题
+
+#### 1. 命令未找到
+
+```bash
+# 检查是否安装
+which mycodemap
+
+# 全局安装后可能需要刷新 shell hash
+hash -r
+
+# 或使用 npx
+npx mycodemap --help
+```
+
+#### 2. 配置文件未找到
+
+```bash
+# 确认配置文件存在
+ls mycodemap.config.json
+
+# 重新初始化
+mycodemap init -y
+```
+
+#### 3. 权限问题
+
+```bash
+# 检查文件权限
+ls -la .mycodemap/
+
+# 修复权限
+chmod -R u+rw .mycodemap/
+```
+
+#### 4. tree-sitter 构建失败
+
+某些环境可能需要安装构建工具：
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install build-essential
+
+# macOS
+xcode-select --install
+```
+
+### 获取帮助
+
+```bash
+# 查看帮助
+mycodemap --help
+
+# 查看子命令帮助
+mycodemap generate --help
+
+# 查看版本
+mycodemap --version
+```
+
+### 日志与调试
+
+CLI 运行日志默认写入 `.mycodemap/logs/mycodemap-YYYY-MM-DD.log`
+
+环境变量：
+- `CODEMAP_RUNTIME_LOG_ENABLED=false`：关闭运行日志
+- `CODEMAP_RUNTIME_LOG_DIR=<dir>`：自定义日志目录
+- `CODEMAP_RUNTIME_LOG_RETENTION_DAYS=<days>`：设置保留天数
+
+---
+
+## 下一步
+
+- 了解 [AI 助手配置](./AI_ASSISTANT_SETUP.md)
+- 查看 [CLI 完整命令参考](../README.md#cli-命令)
+- 阅读 [架构设计文档](./design-docs/REFACTOR_ARCHITECTURE_OVERVIEW.md)