@mycodemap/mycodemap 0.5.0 → 0.5.2-beta.1

package/docs/PUBLISHING.md

@@ -23,13 +23,12 @@ codemap ship / release.sh → 创建版本提交 → 推送 tag → GitHub Actio
      - **Workflow Name**: `publish.yml`
      - **GitHub Environment**: (留空)
 
-2. **确保没有设置 NPM_TOKEN**
+2. **默认使用 OIDC；需要时可保留 NPM_TOKEN fallback**
    ```bash
    # 检查是否设置了 NPM_TOKEN
    gh secret list | grep NPM_TOKEN
    
-   # 如果存在，删除它
-   gh secret remove NPM_TOKEN
+   # 默认推荐留空；如果需要 fallback，确保它是 Automation token
    ```
 
 3. **验证权限配置**
@@ -63,6 +62,8 @@ codemap ship --yes
 
 `codemap ship` **不会在本地执行 `npm publish`**；它会创建版本提交、推送 tag，然后由 `.github/workflows/publish.yml` 完成真正的 OIDC 发布。
 
+预发布版本（如 `0.5.2-beta.1`）会自动从版本号推导 npm dist-tag（如 `beta`）；稳定版本默认发布到 `latest`。
+
 ### 方法 1: 使用发布脚本
 
 ```bash
@@ -200,17 +201,28 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0  # 获取完整历史用于生成 changelog
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: '20'
+          node-version: '24'
           cache: 'npm'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Determine npm dist-tag
+        id: npm-tag
+        run: |
+          VERSION="${{ steps.package-version.outputs.version }}"
+          DIST_TAG="latest"
+          if [[ "$VERSION" == *-* ]]; then
+            DIST_TAG="${VERSION#*-}"
+            DIST_TAG="${DIST_TAG%%.*}"
+          fi
+          echo "dist-tag=$DIST_TAG" >> $GITHUB_OUTPUT
+
       - name: Get version from package.json
         id: package-version
         run: |
@@ -259,10 +271,18 @@ jobs:
       - name: Validate package contents
         run: npm run validate-pack
 
-      # 使用 OIDC Trusted Publishing 发布
-      # OIDC 通过 id-token: write 权限自动获取认证，不需要 NPM_TOKEN
+      # 使用 OIDC Trusted Publishing 或 NPM_TOKEN fallback 发布
       - name: Publish to NPM
-        run: npm publish --access public --provenance
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          DIST_TAG="${{ steps.npm-tag.outputs.dist-tag }}"
+          if [ -n "$NPM_TOKEN" ]; then
+            export NODE_AUTH_TOKEN="$NPM_TOKEN"
+            npx npm@11.5.1 publish --access public --tag "$DIST_TAG" --provenance --registry https://registry.npmjs.org
+          else
+            npx npm@11.5.1 publish --access public --tag "$DIST_TAG" --registry https://registry.npmjs.org
+          fi
 
       - name: Generate Release Notes
         if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
@@ -350,13 +370,13 @@ npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/@mycodemap%2fmycodem
 **原因**: 
 1. NPM 端未正确配置 Trusted Publisher
 2. `id-token: write` 权限未设置
-3. 设置了 `NODE_AUTH_TOKEN` 环境变量干扰了 OIDC
+3. workflow 没有为 prerelease 显式传 `--tag`（例如 `0.5.2-beta.1` 需要 `--tag beta`）
 
 **解决**:
 1. 检查 NPM 配置: https://www.npmjs.com/package/@mycodemap/mycodemap/access
 2. 确保 workflow 中有 `id-token: write` 权限
-3. 确保没有设置 `NODE_AUTH_TOKEN` 环境变量
-4. 确保没有设置 `NPM_TOKEN` secret
+3. 确保没有设置错误的 `NODE_AUTH_TOKEN` 环境变量
+4. 如果配置了 `NPM_TOKEN`，确保它是 Automation token
 
 ### 发布失败: "ENEEDAUTH"
 
@@ -393,6 +413,15 @@ npm ERR! 403 403 Forbidden - PUT https://registry.npmjs.org/@mycodemap%2fmycodem
 1. 检查 package.json 中的版本号
 2. npm 版本号不可重复，需要递增
 
+### 发布失败: "You must specify a tag using --tag"
+
+**原因**: 发布的是 prerelease 版本，但 `npm publish` 没有显式传 dist-tag
+
+**解决**:
+1. 确认 workflow 会从版本号推导 dist-tag
+2. `0.5.2-beta.1` 应发布到 `beta`
+3. `0.5.2-rc.1` 应发布到 `rc`
+
 ### GitHub Actions 未触发
 
 **原因**: tag 格式不正确或 workflow 配置错误

package/docs/SETUP_GUIDE.md

@@ -135,9 +135,9 @@ mycodemap init -y
 | `exclude` | string[] | 见上 | 排除的文件 glob 模式 |
 | `output` | string | `".mycodemap"` | 输出目录路径 |
 | `watch` | boolean | `false` | 监听模式预留配置 |
-| `storage.type` | string | `"filesystem"` | 图存储后端类型：`filesystem` / `kuzudb` / `memory` / `auto` |
+| `storage.type` | string | `"filesystem"` | 图存储后端类型：`filesystem` / `sqlite` / `memory` / `auto` |
 | `storage.outputPath` | string | `".codemap/storage"` | 文件系统存储目录 |
-| `storage.databasePath` | string | - | KùzuDB 数据目录（相对项目根目录） |
+| `storage.databasePath` | string | `".codemap/governance.sqlite"` | SQLite 数据库文件路径（相对项目根目录） |
 | `plugins.builtInPlugins` | boolean | `true` | 是否启用内置插件 |
 | `plugins.pluginDir` | string | - | 额外插件目录 |
 | `plugins.plugins` | string[] | `[]` | 显式加载的插件名称列表 |
@@ -146,10 +146,10 @@ mycodemap init -y
 ### 图存储后端配置
 
 - `generate` 会把 CodeGraph 写入 `storage` 指定的后端；`export json|graphml|dot` 会从同一后端读取。
-- 选择 `kuzudb` 前先安装 `npm install kuzu`。
-- 旧的 `neo4j` 配置已不再受支持，会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
-- 缺少依赖时会返回显式错误，不会静默 fallback 到 `filesystem`。
-- `storage.type = "auto"` 当前仍保守使用 `filesystem`，阈值字段先作为配置契约保留。
+- 选择 `sqlite` 时默认落盘到 `.codemap/governance.sqlite`；也可通过 `storage.databasePath` 覆盖。
+- 旧的 `neo4j` / `kuzudb` 配置已不再受支持，会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
+- 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，会返回显式错误。
+- `storage.type = "auto"` 当前优先选择 `sqlite`；仅当 SQLite 运行时不可用时才 warning 后回退到 `filesystem`。
 
 ---
 

package/docs/ai-guide/COMMANDS.md

@@ -16,6 +16,7 @@ mycodemap generate                          # hybrid 模式（推荐）
 mycodemap generate -m smart                 # AST 深度分析
 mycodemap generate -m fast                  # 快速正则分析
 mycodemap generate -o ./output              # 指定输出目录
+mycodemap generate --symbol-level           # 额外 materialize symbol-level call 依赖
 mycodemap generate --ai-context             # 生成 AI 描述
 ```
 
@@ -23,12 +24,15 @@ mycodemap generate --ai-context             # 生成 AI 描述
 |------|------|--------|
 | `-m, --mode <mode>` | 分析模式: fast/smart/hybrid | `hybrid` |
 | `-o, --output <dir>` | 输出目录 | `.mycodemap` |
+| `--symbol-level` | 仅在显式开启时把可解析的 symbol-level `call` 依赖写入图存储 | `false` |
 | `--ai-context` | 为每个文件生成描述 | - |
 
 **模式说明**:
 - `fast`: 正则匹配，极快，适合大型项目
 - `smart`: AST 分析，较慢，信息完整
 - `hybrid`: 自动选择，文件<50用fast，≥50用smart
+- `--symbol-level` 是首期实验性切片；默认 generate 仍只保证现有模块级行为兼容
+- `generate` 完成后，`codemap.json` 会带 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`；若 `graphStatus = "partial"`，不要把结果当成完整图。
 
 **插件运行时说明**:
 - `generate` 不提供独立 `--plugin` flags；插件通过 `mycodemap.config.json` 的 `plugins` 段声明。
@@ -37,9 +41,9 @@ mycodemap generate --ai-context             # 生成 AI 描述
 
 **图存储运行时说明**:
 - `generate` 会读取 `mycodemap.config.json.storage`，并把 CodeGraph 写入所选后端。
-- `storage.type` 支持 `filesystem`、`kuzudb`、`memory`、`auto`；默认是 `filesystem`。
-- 旧的 `neo4j` 配置会直接报迁移错误；缺少 `kuzu` 时也会直接报错，不会静默 fallback 到 `filesystem`。
-- `storage.type = "auto"` 当前仍保守走 `filesystem`；阈值字段是配置契约，不代表自动切换已完成。
+- `storage.type` 支持 `filesystem`、`sqlite`、`memory`、`auto`；默认是 `filesystem`。
+- 旧的 `neo4j` / `kuzudb` 配置会直接报迁移错误；显式选择 `sqlite` 但运行时缺少 `better-sqlite3` 或 Node.js `<20` 时也会直接报错，不会静默 fallback 到 `filesystem`。
+- `storage.type = "auto"` 当前优先走 `sqlite`；只有 SQLite 不可用时才 warning 后回退 `filesystem`。
 
 ---
 
@@ -105,11 +109,35 @@ mycodemap impact -f "src/cli/index.ts" -j   # JSON 输出
 
 ---
 
+### mcp - experimental 本地 MCP 集成
+
+```bash
+mycodemap mcp install                     # 把当前仓库写入 .mcp.json
+mycodemap mcp start                       # 启动本地 stdio MCP server
+mycodemap generate --symbol-level         # 使用前必须先生成 symbol-level 图
+```
+
+| 子命令 | 说明 |
+|--------|------|
+| `install` | 更新当前仓库根目录 `.mcp.json`，追加 `mycodemap-experimental` server entry |
+| `start` | 启动 local-only / read-only / stdio-first experimental MCP server |
+
+**首期规则**:
+- `mcp` 是 experimental surface，不要把它当成稳定长期 public API。
+- `mcp start` 的 `stdout` 只能承载 MCP 协议帧；欢迎信息、迁移提示与 runtime log 不会走这条流。
+- 当前只暴露两个工具：`codemap_query`、`codemap_impact`。
+- `codemap_query` / `codemap_impact` 都会返回 `graph_status`、`generated_at` 与显式 `error.code`。
+- 若图尚未生成，会返回 `GRAPH_NOT_FOUND`；若符号不存在，返回 `SYMBOL_NOT_FOUND`；若同名符号无法消歧，返回 `AMBIGUOUS_EDGE`。
+- 详细安装步骤见 `docs/ai-guide/INTEGRATION.md`；完整 output contract 见 `docs/ai-guide/OUTPUT.md`。
+
+---
+
 ### complexity - 复杂度分析
 
 ```bash
 mycodemap complexity                        # 项目整体
 mycodemap complexity -f "src/cli/index.ts"  # 指定文件
+mycodemap complexity -f "src/cli/index.ts" -j  # 单文件 JSON，顶层返回 file
 mycodemap complexity -d                     # 函数级详情
 mycodemap complexity -j                     # JSON 输出
 ```
@@ -121,6 +149,8 @@ mycodemap complexity -j                     # JSON 输出
 | `-j, --json` | JSON 格式输出 | - |
 | `--structured` | 纯结构化输出 | - |
 
+> `complexity -f "src/file.ts" -j` 的 JSON 顶层只返回 `file`；不会返回全项目 `modules` 数组。
+
 ---
 
 ### cycles - 循环依赖检测
@@ -148,10 +178,13 @@ mycodemap cycles -j                         # JSON 输出
 | 输出契约 | 多数命令显式 `--json`，`analyze` 额外提供 `--output-mode machine|human` | `--structured --json` 会移除自然语言 `content` |
 | analyze 意图 | `find` / `read` / `link` / `show` | legacy alias 会在输出中返回 `warnings[]`；`refactor` 直接报 `E0001_INVALID_INTENT` |
 
+> 通用搜索仍优先使用 `query -S "XXX" -j`。需要统一 analyze schema 时使用 `analyze -i find -k "XXX" --json --structured`，并读取 stdout JSON 的 `diagnostics.status` 区分真实 0 命中、`partialFailure` 降级与 `failure`。
+
 <!-- BEGIN GENERATED: analyze-commands-intents -->
 ```bash
 # 1. find - 查找符号 / 文本
 mycodemap analyze -i find -k "UnifiedResult"
+mycodemap analyze -i find -k "SourceLocation" --json --structured
 mycodemap analyze -i find -t "src/orchestrator" -k "IntentRouter" --topK 20
 
 # 2. read - 阅读文件（影响 + 复杂度）
@@ -287,6 +320,45 @@ mycodemap design verify mycodemap.design.md --json
 
 ---
 
+## check - 执行 contract gate
+
+```bash
+# 默认 full scan
+mycodemap check --contract mycodemap.design.md --against src
+
+# 人类可读渲染
+mycodemap check --contract mycodemap.design.md --against src --human
+
+# PR / CI 显式 diff
+mycodemap check --contract mycodemap.design.md --against src --base origin/main
+
+# 显式 changed files
+mycodemap check --contract mycodemap.design.md --against src --changed-files src/core/service.ts
+
+# GitHub PR annotations
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format github
+
+# GitLab code quality artifact
+mycodemap check --contract mycodemap.design.md --against src --base origin/main --annotation-format gitlab --annotation-file gl-code-quality-report.json
+
+# 校准当前仓库是否允许默认 hard gate
+node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10
+```
+
+- 默认输出 `ContractCheckResult` JSON；`--human` 只改变渲染，不改变底层 truth
+- JSON 默认包含 `passed` 与 `summary`，Agent 不需要解析 prose 判断通过状态
+- `severity:error` 返回非零退出码，`severity:warn` 不阻断
+- diff-aware 只在显式提供 `--base` 或 `--changed-files` 时启用
+- 坏掉的 diff base 或越界 changed files 会回退 full scan，并把原因写进 `warnings[]`
+- 当前 rule families 为 `layer_direction` / `forbidden_imports` / `module_public_api_only` / `complexity_threshold`
+- `--annotation-format github` 会输出 GitHub Actions annotations；`gitlab` 需要配合 `--annotation-file gl-code-quality-report.json`，并只保留 line-scoped diagnostics
+- PR 默认 hard gate 只在 calibration 通过且 `changed files <= 10` 时开启；超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时必须显式切回 `warn-only / fallback`
+- calibration 输出的 recommendation 目前是 `hard-gate-ok` / `warn-only` / `re-scope`；fallback 不应伪装成稳定 hard gate
+- Git history risk 是 additive enrichment：会附加 `violations[].risk` 与顶层 `history`，但不会改变 `severity:error` / exit 语义
+- 仓库根 `mycodemap.design.md` 是当前 canonical contract truth
+
+---
+
 ## ci - CI 门禁
 
 ### 子命令
@@ -312,10 +384,11 @@ mycodemap ci check-headers
 mycodemap ci check-headers -d "src/domain"  # 指定目录
 mycodemap ci check-headers -f "file1.ts,file2.ts"
 
-# 评估变更风险
+# 评估变更风险（与 `check` / `history` 共用同一套 Git history risk truth）
 mycodemap ci assess-risk
 mycodemap ci assess-risk -t 0.5             # 设置阈值 0.5
 mycodemap ci assess-risk -f "changed.ts"
+mycodemap ci assess-risk --files "changed.ts" --json
 
 # 验证文档同步
 mycodemap ci check-docs-sync
@@ -334,6 +407,24 @@ mycodemap ci check-commit-size -m 15
 
 > `ship` 的 CHECK 阶段会复用 `ci check-working-tree`、`ci check-branch`、`ci check-scripts` 这三条发布前 gate checks。
 > `ci check-branch --allow` 支持 `*` 通配；`ci check-headers -d` 与 `generate` / `analyze` 共享同一套 `.gitignore` 感知排除规则，在没有 `.gitignore` 时回退到默认 `exclude`。
+> `ci assess-risk` 现在输出 `status / confidence / freshness / source / score / level`；若 Git history 不可用，会显式给出 `unavailable` / warning，并说明阈值未被应用。
+> `ci assess-risk --json` 顶层输出 `status: "passed" | "failed" | "skipped"`；`failed` 会设置非零 exit code，但 stdout 保持可解析 JSON。
+
+---
+
+## history - 符号级 Git history / risk 查询
+
+```bash
+# 默认输出 machine-first JSON
+mycodemap history --symbol createCheckCommand
+
+# 人类可读渲染
+mycodemap history --symbol createCheckCommand --human
+```
+
+- 返回 `ok` / `ambiguous` / `not_found` / `unavailable` 四种状态
+- `--human` 只改变展示，不改变结构化 truth
+- 与 `check` / `ci assess-risk` 共用同一套 history risk service；历史缺失时会显式返回 `unavailable`
 
 ### 支持的提交 TAG
 
@@ -360,6 +451,7 @@ mycodemap ci check-commit-size -m 15
 # 启动工作流
 mycodemap workflow start "实现用户认证模块"
 mycodemap workflow start "修复登录接口" --template bugfix
+mycodemap workflow start "inspect analyze find" --json
 
 # 查看状态
 mycodemap workflow status
@@ -385,6 +477,8 @@ mycodemap workflow resume
 mycodemap workflow resume "workflow-id"
 ```
 
+> `workflow start --json` 输出 `{ status, task, id, currentPhase, template, nextSteps }`，不改变 workflow 的 analysis-only 边界。
+
 ### 模板管理
 
 ```bash