@mycodemap/mycodemap 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -2,16 +2,118 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.1] - 2026-04-19 - Rule Control Hardening & Release Sync
+
+### 🚀 New Features
+
+- **rules**: 发布 repo-local rule control baseline，包括 capability report、validator exit-code contract、hooks/CI backstop、scoped subagent rule context 与 executable QA
+- **workflow**: Claude / Codex 执行流现在会在常见执行路径中注入 scoped `<rule_context>`，减少规则遗漏与 prompt 串味
+
+### 📝 Documentation
+
+- **release**: 同步 `llms.txt`、`AI_GUIDE.md`、`AI_DISCOVERY.md`、`ai-document-index.yaml` 到 `v0.5.1`
+- **changelog**: 补齐本版本发布条目，确保 pre-release guardrail 与 GitHub Release notes 可用
+- **claude**: 补齐 `CLAUDE.md` 对 `docs/ai-guide/` 的入口引用，消除发布前 AI 文档交叉引用 warning
+
+## [0.5.0] - 2026-04-15 - Design Contract Surface
+
+### 🏗️ v1.4 Milestone: Design-to-Code Mapping & Handoff Package
+
+v1.4 milestone 完成，新增完整的 design contract 公共 CLI 表面，支持人类设计到 AI 执行的标准化 handoff。
+
+#### Phase 17: Design Contract Validation
+- **feature**: 发布 `design validate` 命令，校验 `mycodemap.design.md` 必填 sections
+- **feature**: 返回结构化 diagnostics（missing-section、duplicate-section、empty-section 等）
+
+#### Phase 18: Design-to-Code Mapping
+- **feature**: 发布 `design map` 命令，将 design contract 解析为 candidate code scope
+- **feature**: 支持 `no-candidates`、`over-broad-scope`、`high-risk-scope` 自动阻断
+
+#### Phase 19: Handoff Package & Human Gates
+- **feature**: 发布 `design handoff` 命令，生成 reviewer / AI agent 共用的 handoff artifact
+- **feature**: 输出 `readyForExecution`、`approvals`、`assumptions`、`openQuestions`
+
+#### Phase 20: Design Drift Verification
+- **feature**: 发布 `design verify` 命令，基于 reviewed handoff truth 做 checklist / drift 检查
+- **feature**: `needs-review` 保持零退出码，仅 blocker diagnostics 返回非零 exit code
+
+### 🚀 New Features
+
+- **design**: 新增 design contract 四阶段 CLI 命令（validate / map / handoff / verify）
+- **docs**: 同步 AI_GUIDE.md、README.md 和 docs/ai-guide 中的 design 类型定义与 workflow 命令
+- **ci**: 更新文档一致性校验脚本，覆盖 design contract 测试与 fixture
+
+### 🐛 Bug Fixes
+
+- **storage**: 修复 `kuzu` 可选依赖在 CI typecheck 中的模块缺失错误
+- **publish**: 移除 GitHub Actions 中不稳定的 `npm install -g npm@latest` 步骤
+
 ## [0.4.2] - 2026-03-25 - Test Infrastructure Fix
 
+### 🏗️ v1.3 Milestone: Kùzu-only Convergence & High-Signal Debt Cleanup
+
+v1.3 milestone 完成，核心产品面收敛为 Kùzu-only，清偿多项技术债务。
+
+#### Phase 13: Storage Backend Convergence
+- **refactor**: 移除 neo4j 运行时表面 (`8957fca`)
+- **docs**: 同步 kuzu-only public contract (`d07524e`)
+
+#### Phase 14: CLI Surface & Documentation Alignment
+- **refactor**: 收口 analyze 和 server 过渡差距 (`4a756d7`)
+- **docs**: 移除 workflow 过渡性 public 措辞 (`e5b9560`)
+
+#### Phase 15: Analysis Intent & Workflow Runtime
+- **feature**: 发布 public intent contract 和 outputs (`f4abfa6`)
+- **refactor**: 对齐 workflow 运行时编排核心 (`ddd1c80`)
+- **bugfix**: 扩展 quality 和回归测试覆盖 (`5eb38f7`)
+
+#### Phase 16: Core Debt Cleanup & Final Guardrails
+- **refactor**: 实现 plugin 真实 reload 生命周期 (`3a5fbc6`)
+- **refactor**: 收口 parser index 和 resolution 债务 (`f64432a`)
+- **refactor**: 使 analysis write paths 显式化 (`27458cd`)
+- **docs**: 同步 kuzu-only 和 docs gate contract (`a4c8e12`)
+
+#### Milestone Archive
+- **docs**: 归档 v1.0 CI 和 docs phases (`7d474df`)
+- **docs**: 归档 v1.0 analyze 和 workflow phases (`b3e43e4`)
+- **docs**: 归档 v1.0 kickoff 和 cli cleanup (`bb80e4b`)
+- **docs**: 归档 v1.1 plugin rollout phases (`35cfd60`)
+- **docs**: 归档 v1.1 docs 和 v1.2 activation (`0aed09c`)
+- **docs**: 归档 v1.2 backend validation (`a27bfb0`)
+- **docs**: 完成 v1.3 milestone 关闭 (`ccb7d12`)
+
+### 🚀 New Features
+
+- **storage**: 新增 adapter parity 和 validation (`b051dd8`)
+- **storage**: 接入 generate export 和共享 helpers (`f625596`)
+- **analyze**: 发布 public intent contract 和标准化输出 (`f4abfa6`)
+- **plugins**: 新增 runtime config 和 diagnostics surface (`74d7905`)
+- **workflow**: 扩展 quality 和回归测试覆盖 (`5eb38f7`)
+- **claude**: 引入完整的 GSD (Get Shit Done) workflow agents 和命令 (`ef537e2`)
+- **claude/gstack**: 新增 Docker 配置和 agent 定义 (`b83c000`)
+- **claude/gstack**: 新增 GitHub Actions workflows (`7ef301b`)
+
 ### 🐛 Bug Fixes
 
-- **test**: 修复 validate-docs 测试缺少 product-specs 文件的问题
+- **test**: 修复 validate-docs 测试缺少 product-specs 文件的问题 (`20d4293`)
+- **hooks**: 解决 vitest 跨 node_modules 布局的查找问题 (`d53a5ac`)
+- **hooks**: 添加本地 vitest entry 回退 (`d6542b5`)
+- **adapter**: 增加 method signature 测试超时 (`4e97ca5`)
 
 ### 📚 Documentation
 
-- **docs**: 同步 MVP3 产品规格文档基线
-- **docs**: 完成 v1.3 milestone 归档
+- **docs**: 同步 MVP3 产品规格文档基线 (`0c75108`)
+- **docs**: 完成 v1.3 milestone 归档 (`ccb7d12`)
+- **ai-guide**: 新增 ship troubleshooting section (`b7fe6d4`)
+- **guardrails**: 同步 hooks 和 validation 文档 (`38b1964`)
+- **planning**: 添加当前状态和 codebase map (`0bbd4ac`)
+
+### 🔧 Maintenance
+
+- **config**: 同步所有 AI 文档到 v0.4.2 (`43c7b17`)
+- **config**: 版本升级到 v0.4.2 (`d1f55c6`)
+- **config**: vitest 添加 lcov coverage reporter (`a4da751`)
+- **tooling**: checkpoint milestone metadata (`851ecf6`)
 
 ## [0.4.1] - 2026-03-23 - Ship Workflow Fixes
 

package/README.md

@@ -7,7 +7,7 @@ CodeMap 是一个面向 TypeScript/JavaScript/Go 项目的 AI-first 代码地图
 ## 特性
 
 - **AI-first 代码地图** - 生成 `AI_MAP.md`、`CONTEXT.md`、`codemap.json` 等 AI/Agent 可直接消费的上下文
-- **核心分析命令** - 提供 `generate`、`query`、`deps`、`impact`、`complexity`、`cycles`、`analyze`、`export`、`ci`
+- **核心分析命令** - 提供 `generate`、`query`、`deps`、`impact`、`complexity`、`cycles`、`analyze`、`design`、`export`、`ci`，并提供 experimental `mcp`
 - **机器可读优先** - 结构化输出是产品基线；当前 CLI 过渡期仍主要通过 `--json` 暴露机器可读结果
 - **分层架构 (MVP3)** - 保持 `Interface → Infrastructure → Domain → Server → CLI` 的明确边界
 - **双层解析模式** - 提供 `fast`（快速正则）和 `smart`（TypeScript AST）两种解析模式
@@ -25,7 +25,7 @@ CodeMap 是一个面向 TypeScript/JavaScript/Go 项目的 AI-first 代码地图
 | 输出契约 | 目标是机器可读优先；`当前 CLI 现实` 是多数命令通过 `--json` 提供结构化结果，`analyze` 额外支持 `--output-mode machine|human` |
 | 架构边界 | `Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令 |
 
-当前公共 CLI 聚焦 `init`、`generate`、`query`、`deps`、`cycles`、`complexity`、`impact`、`analyze`、`ci`、`workflow`、`export`、`ship`；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
+当前公共 CLI 聚焦 `init`、`generate`、`query`、`deps`、`cycles`、`complexity`、`impact`、`analyze`、`design`、`ci`、`workflow`、`export`、`ship`，以及 experimental 的 `mcp`；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
 
 ## 安装
 
@@ -73,6 +73,13 @@ mycodemap impact -f src/cli/index.ts -j
 
 # analyze 额外支持显式 machine/human 模式
 mycodemap analyze -i read -t src/cli/index.ts --output-mode human
+
+# 人类设计先落成 design contract，再交给 AI/Agent 消费
+cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md
+mycodemap design validate mycodemap.design.md --json
+mycodemap design map mycodemap.design.md --json
+mycodemap design handoff mycodemap.design.md --json
+mycodemap design verify mycodemap.design.md --json
 ```
 
 生成后，将 `.mycodemap/AI_MAP.md` 的内容提供给 AI 助手即可让其快速理解你的项目结构；需要结构化结果继续处理时，优先使用 JSON / machine 模式。
@@ -138,6 +145,7 @@ mycodemap init -y       # 使用默认配置直接创建
 mycodemap generate                    # 使用默认 hybrid 模式
 mycodemap generate -m smart           # 使用 smart 模式（AST 深度分析）
 mycodemap generate -o ./docs/codemap  # 指定输出目录
+mycodemap generate --symbol-level     # 额外 materialize symbol-level 调用依赖（实验性首期切片）
 
 # 别名：codemap generate 也可以使用
 ```
@@ -146,8 +154,12 @@ mycodemap generate -o ./docs/codemap  # 指定输出目录
 |------|------|--------|
 | `-m, --mode <mode>` | 分析模式：`fast`（正则匹配）、`smart`（TypeScript AST）或 `hybrid`（自动选择） | `hybrid` |
 | `-o, --output <dir>` | 输出目录 | `.mycodemap` |
+| `--symbol-level` | 额外把可解析的 symbol-level `call` 依赖写入图存储；默认 generate 行为不变 | `false` |
 | `--ai-context` | 为每个文件生成描述 | - |
 
+- `codemap.json` 现在会显式写出 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`。
+- 当某些发现到的文件没有成功进入最终图时，`graphStatus` 会降级为 `partial`；不要把这种结果当成完整图继续做自动化决策。
+
 **模式说明：**
 
 | 模式 | 速度 | 精度 | 适用场景 |
@@ -234,6 +246,30 @@ mycodemap impact -f src/cli/index.ts -j     # JSON 格式输出
 | `-t, --transitive` | 包含传递依赖（间接影响） | - |
 | `-j, --json` | 以 JSON 格式输出 | - |
 
+### `mycodemap mcp`（experimental）
+
+本地只读的 stdio MCP 薄切片。当前只提供两个工具：`codemap_query`、`codemap_impact`。
+
+```bash
+# 先生成 symbol-level 图
+mycodemap generate --symbol-level
+
+# 把当前仓库写入本地 MCP host 配置
+mycodemap mcp install
+
+# 由 MCP host 启动 stdio server
+mycodemap mcp start
+```
+
+| 子命令 | 说明 |
+|--------|------|
+| `mcp install` | 把 experimental 本地 server 写入当前仓库 `.mcp.json` |
+| `mcp start` | 启动本地 stdio MCP server；`stdout` 仅承载协议帧 |
+
+- `mcp` 当前是 **experimental / local-only / read-only** surface，不是稳定长期 public API。
+- 使用前必须先执行 `mycodemap generate --symbol-level`；否则工具会返回 `GRAPH_NOT_FOUND`。
+- canonical 集成文档见 `docs/ai-guide/INTEGRATION.md`；若宿主暂时不支持真正 MCP，可先回退到传统 CLI wrapper 方式。
+
 ### 已移除的公共 CLI 命令
 
 以下命令已从 public CLI 移除；直接调用时，CLI 会显式失败并给出迁移提示，而不是继续执行旧功能。
@@ -284,6 +320,39 @@ mycodemap export json -o ./out     # 指定输出路径
 
 > 内置模板（`refactoring` / `bugfix` / `feature` / `hotfix`）共享同一 4 阶段顺序，只通过不同的阶段阈值和适用场景调整体验。
 
+## 设计契约输入面
+
+`design` 是给“人类负责设计、AI 负责执行”协作链路准备的正式输入面。
+先把设计写成 `mycodemap.design.md`，再用 CLI 校验必填 sections、空段、重复 heading 和未知 heading。
+
+```bash
+# 从 canonical template 起步
+cp docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md mycodemap.design.md
+
+# 使用默认文件名校验
+mycodemap design validate mycodemap.design.md --json
+
+# 校验通过后生成 candidate scope
+mycodemap design map mycodemap.design.md --json
+
+# 把 scope 打包成 handoff artifact，供 reviewer / AI agent 消费
+mycodemap design handoff mycodemap.design.md --json
+
+# 基于 reviewed handoff truth 做 verification / drift 检查
+mycodemap design verify mycodemap.design.md --json
+
+# 也可以显式传入其他路径
+mycodemap design validate docs/designs/login.design.md
+```
+
+必填 sections：
+- `## Goal`
+- `## Constraints`
+- `## Acceptance Criteria`
+- `## Non-Goals`
+
+> 建议最小工作流：`design validate → design map → design handoff → design verify`。`design map --json` 会返回 `summary`、`candidates`、`diagnostics` 与 `unknowns`；`design handoff --json` 会继续返回 `readyForExecution`、`approvals`、`assumptions` 与 `openQuestions`，默认 artifact 路径为 `.mycodemap/handoffs/{stem}.handoff.md|json`；`design verify --json` 会返回 `checklist`、`drift`、`diagnostics` 与 `readyForExecution`，其中 review-needed 不会直接变成非零退出，只有 blocker diagnostics 才会阻断。
+
 ### 工作流 CLI 命令
 
 ```bash
@@ -379,6 +448,8 @@ mycodemap ci assess-risk -f src/cache/lru-cache.ts
 mycodemap ci check-output-contract
 ```
 
+> `ci assess-risk` 现在输出 `status/confidence/freshness/source` 与统一 risk level；若 Git history 不可用，会显式打印 `unavailable` / warning，并说明阈值未被应用。
+
 ## 配置说明
 
 通过 `mycodemap init` 生成的 `mycodemap.config.json` 配置文件支持以下选项：
@@ -435,9 +506,9 @@ mycodemap ci check-output-contract
 | `exclude` | `string[]` | 排除的文件 glob 模式 | `["node_modules/**", "dist/**", ...]` |
 | `output` | `string` | 输出目录路径 | `".mycodemap"` |
 | `watch` | `boolean` | 监听模式预留配置 | `false` |
-| `storage.type` | `"filesystem" \| "kuzudb" \| "memory" \| "auto"` | 图存储后端类型 | `"filesystem"` |
+| `storage.type` | `"filesystem" \| "sqlite" \| "memory" \| "auto"` | 图存储后端类型 | `"filesystem"` |
 | `storage.outputPath` | `string` | 文件系统存储目录 | `".codemap/storage"` |
-| `storage.databasePath` | `string` | KùzuDB 数据目录（相对项目根目录） | - |
+| `storage.databasePath` | `string` | SQLite 数据目录（相对项目根目录） | `".codemap/governance.sqlite"` |
 | `storage.autoThresholds` | `object` | `auto` 后端选择阈值 | - |
 | `plugins.builtInPlugins` | `boolean` | 是否启用内置插件 | `true` |
 | `plugins.pluginDir` | `string` | 额外插件目录 | - |
@@ -449,16 +520,16 @@ mycodemap ci check-output-contract
 ```jsonc
 {
   "storage": {
-    "type": "kuzudb",
-    "databasePath": ".codemap/kuzu"
+    "type": "sqlite",
+    "databasePath": ".codemap/governance.sqlite"
   }
 }
 ```
 
 - `generate` 会把 CodeGraph 写入配置的 `storage` 后端，`export` 与内部 `Server Layer` handler 会读取同一份后端数据。
-- `neo4j` 已不再是正式支持的 backend；旧配置会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
-- 选择 `kuzudb` 前先安装 `npm install kuzu`；缺少依赖时会返回显式错误。
-- `storage.type = "auto"` 当前仍以 `filesystem` 为保守默认值；阈值字段先作为显式契约保留，不伪装成已完成的自动切换能力。
+- `neo4j` 与 `kuzudb` 已不再是正式支持的 backend；旧配置会返回显式迁移错误，不会静默 fallback 到 `filesystem`。
+- 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，会返回显式错误。
+- `storage.type = "auto"` 当前优先选择 `sqlite`；若运行时缺少 `better-sqlite3` 或 Node.js `<20` 导致 SQLite 不可用，则 warning 后回退到 `filesystem`。
 - 图存储后端生产化不等于重新开放公共 HTTP API 产品面；`Server Layer` 仍是内部架构层。
 
 ### 插件运行时说明
@@ -632,6 +703,72 @@ cp examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
 
 ## 新增 CLI 命令
 
+### `mycodemap design`
+
+校验、映射并验证 human-authored design contract，默认读取仓库根目录的 `mycodemap.design.md`。
+
+```bash
+# validate: 使用默认路径校验
+mycodemap design validate mycodemap.design.md --json
+
+# validate: 显式指定文件
+mycodemap design validate docs/designs/login.design.md
+
+# map: 生成 candidate code scope
+mycodemap design map mycodemap.design.md --json
+
+# handoff: 生成 reviewer + agent 共用的 handoff package
+mycodemap design handoff mycodemap.design.md --json
+
+# verify: 基于 reviewed handoff truth 做 checklist / drift 校验
+mycodemap design verify mycodemap.design.md --json
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-j, --json` | 输出纯 JSON diagnostics，适合 AI/CI 消费 |
+
+> canonical 模板位于 `docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md`。
+> 缺失必填 section、重复 section、空 section 或未知 heading 时，CLI 会返回结构化 diagnostics，而不是继续猜测设计意图。
+> `design map` 会基于 design contract 返回 `candidates`、`diagnostics` 与 `unknowns`；若命中 `no-candidates`、`over-broad-scope` 或 `high-risk-scope`，命令会直接阻断。
+> `design handoff` 会基于 validated design contract + mapping truth 返回 `readyForExecution`、`approvals`、`assumptions`、`openQuestions`；human mode 默认写出 `.mycodemap/handoffs/{stem}.handoff.md|json`。
+> `design verify` 会把 `Acceptance Criteria` 固定映射为 `checklist`，并输出 `drift` / `diagnostics`；当结果只是 `needs-review` 时保持零退出码，只有 `ok=false` 或 blocker diagnostics 才返回非零 exit code。
+
+### `mycodemap check`
+
+执行 design contract contract gate，默认输出机器可读 JSON。
+
+```bash
+# 默认 full scan
+mycodemap check --contract mycodemap.design.md --against src
+
+# 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
+```
+
+> PR 默认 hard gate 只在 calibration 通过且 `changed files <= 10` 时开启；超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时必须显式切回 `warn-only / fallback`。
+
+### `mycodemap history`
+
+符号级 Git history / risk 查询：
+
+```bash
+# 默认输出 machine-first JSON
+mycodemap history --symbol createCheckCommand
+
+# 查询某个符号的历史轨迹与风险摘要
+mycodemap history --symbol createCheckCommand
+
+# 人类可读摘要
+mycodemap history --symbol createCheckCommand --human
+```
+
 ### `mycodemap analyze`
 
 统一分析入口，当前公共契约只暴露四个 intent，并统一返回结构化输出：
@@ -681,51 +818,9 @@ mycodemap analyze -i link -t src/index.ts --structured --json
 > 产品目标是机器可读优先；当前实现仍以显式 `--json` / `--output-mode` 作为主要入口。
 >
 > legacy 兼容映射：`search → find`、`impact/complexity → read`、`dependency/reference → link`、`overview/documentation → show`；`refactor` 会返回 `E0001_INVALID_INTENT`。
+>
+> `--include-git-history` 现在只会在 `read` intent 上附加统一的 Git history enrichment；其他 intent 会显式给出 warning，而不是 silent noop。
 
-### `mycodemap ci`
-
-CI Gateway - 代码质量门禁工具：
-
-```bash
-# 验证工作区是否干净（ship 的发布前检查也复用这条规则）
-mycodemap ci check-working-tree
-
-# 验证当前分支是否允许执行发布前检查
-mycodemap ci check-branch
-mycodemap ci check-branch --allow main,release/*
-
-# 运行发布前脚本集合（docs/typecheck/lint/test/build/pack）
-mycodemap ci check-scripts
-
-# 验证提交格式（[TAG] scope: message）
-mycodemap ci check-commits
-mycodemap ci check-commits -c 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 "src/index.ts,src/cli/index.ts"
-
-# 评估变更风险
-mycodemap ci assess-risk
-mycodemap ci assess-risk -t 0.5
-
-# 验证文档同步（含 analyze generated block 校验）
-mycodemap ci check-docs-sync
-
-# 验证输出契约
-mycodemap ci check-output-contract
-
-# 检查提交文件数量（限制 10 个文件）
-mycodemap ci check-commit-size
-mycodemap ci check-commit-size -m 15
-```
-
-> `mycodemap ship` 的 CHECK 阶段现在复用 `ci check-working-tree`、`ci check-branch`、`ci check-scripts` 作为 must-pass 事实源，而不是重复实现这些检查。
-> `mycodemap ci check-headers -d <dir>` 与 `generate` / `analyze` 共享同一套 `.gitignore` 感知排除模块；若仓库没有 `.gitignore`，则回退到默认 `exclude` 列表。
-
-支持的提交 TAG 类型：`[REFACTOR]`, `[TEST]`, `[DOCS]`, `[FEAT]`, `[FIX]`, `[CHORE]`, `[PERF]`, `[SECURITY]`, `[BREAKING]`, `[HOTFIX]`, `[MIGRATION]`, `[WIP]`
 
 ## 贡献指南
 
@@ -816,3 +911,47 @@ DELETE   删除代码/文件
 ## 许可证
 
 [MIT](LICENSE)
+### `mycodemap ci`
+
+CI Gateway - 代码质量门禁工具：
+
+```bash
+# 验证工作区是否干净（ship 的发布前检查也复用这条规则）
+mycodemap ci check-working-tree
+
+# 验证当前分支是否允许执行发布前检查
+mycodemap ci check-branch
+mycodemap ci check-branch --allow main,release/*
+
+# 运行发布前脚本集合（docs/typecheck/lint/test/build/pack）
+mycodemap ci check-scripts
+
+# 验证提交格式（[TAG] scope: message）
+mycodemap ci check-commits
+mycodemap ci check-commits -c 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 "src/index.ts,src/cli/index.ts"
+
+# 评估变更风险
+mycodemap ci assess-risk
+mycodemap ci assess-risk -t 0.5
+
+# 验证文档同步（含 analyze generated block 校验）
+mycodemap ci check-docs-sync
+
+# 验证输出契约
+mycodemap ci check-output-contract
+
+# 检查提交文件数量（限制 10 个文件）
+mycodemap ci check-commit-size
+mycodemap ci check-commit-size -m 15
+```
+
+> `mycodemap ship` 的 CHECK 阶段现在复用 `ci check-working-tree`、`ci check-branch`、`ci check-scripts` 作为 must-pass 事实源，而不是重复实现这些检查。
+> `mycodemap ci check-headers -d <dir>` 与 `generate` / `analyze` 共享同一套 `.gitignore` 感知排除模块；若仓库没有 `.gitignore`，则回退到默认 `exclude` 列表。
+
+支持的提交 TAG 类型：`[REFACTOR]`, `[TEST]`, `[DOCS]`, `[FEAT]`, `[FIX]`, `[CHORE]`, `[PERF]`, `[SECURITY]`, `[BREAKING]`, `[HOTFIX]`, `[MIGRATION]`, `[WIP]`

package/dist/ai/claude.d.ts

@@ -0,0 +1,38 @@
+import { AIProvider, type AIProviderConfig, type AIResponse } from './provider.js';
+import type { CodeMap } from '../types/index.js';
+/**
+ * Claude Provider 配置
+ */
+export interface ClaudeProviderConfig extends AIProviderConfig {
+    /** CLI 路径，默认 claude */
+    cliPath?: string;
+}
+/**
+ * Claude Provider - 通过 CLI 调用 Claude
+ */
+export declare class ClaudeProvider extends AIProvider {
+    readonly name: "claude";
+    private cliPath;
+    constructor(config?: ClaudeProviderConfig);
+    /**
+     * 执行 AI 推理
+     */
+    execute(prompt: string, context?: CodeMap): Promise<AIResponse>;
+    /**
+     * 检查 Claude CLI 是否可用
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * 构建提示词
+     */
+    private buildPrompt;
+    /**
+     * 总结 CodeMap 上下文
+     */
+    private summarizeContext;
+    /**
+     * 解析 Claude CLI JSON 响应
+     */
+    private parseResponse;
+}
+//# sourceMappingURL=claude.d.ts.map

package/dist/ai/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/ai/claude.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAWjD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,uBAAuB;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,SAAgB,IAAI,EAAG,QAAQ,CAAU;IACzC,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,GAAE,oBAAyB;IAK7C;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAoErE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAsBrC;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsCxB;;OAEG;IACH,OAAO,CAAC,aAAa;CA6BtB"}

package/dist/ai/claude.js

@@ -0,0 +1,169 @@
+// ============================================
+// Claude CLI Provider 实现
+// ============================================
+import { spawn } from 'child_process';
+import { AIProvider } from './provider.js';
+/**
+ * Claude Provider - 通过 CLI 调用 Claude
+ */
+export class ClaudeProvider extends AIProvider {
+    name = 'claude';
+    cliPath;
+    constructor(config = {}) {
+        super(config);
+        this.cliPath = config.cliPath || 'claude';
+    }
+    /**
+     * 执行 AI 推理
+     */
+    async execute(prompt, context) {
+        const timeout = this.config.timeout || 60000;
+        // 构建包含上下文的完整提示词
+        const fullPrompt = this.buildPrompt(prompt, context);
+        return new Promise((resolve, reject) => {
+            const args = [
+                '-p',
+                '--output-format', 'json',
+                '--dangerously-skip-permissions'
+            ];
+            let stdout = '';
+            let stderr = '';
+            let killed = false;
+            const proc = spawn(this.cliPath, args, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout
+            });
+            // 超时处理
+            const timeoutId = setTimeout(() => {
+                killed = true;
+                proc.kill('SIGTERM');
+                reject(new Error(`Claude 执行超时（${timeout / 1000}秒）`));
+            }, timeout);
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (code) => {
+                clearTimeout(timeoutId);
+                if (killed)
+                    return;
+                if (code !== 0 && code !== null) {
+                    reject(new Error(`Claude CLI 错误: ${stderr || `exit code ${code}`}`));
+                    return;
+                }
+                try {
+                    const response = this.parseResponse(stdout);
+                    resolve(response);
+                }
+                catch (error) {
+                    reject(new Error(`解析 Claude 响应失败: ${error instanceof Error ? error.message : String(error)}`));
+                }
+            });
+            proc.on('error', (error) => {
+                clearTimeout(timeoutId);
+                if (!killed) {
+                    reject(new Error(`Claude CLI 执行失败: ${error.message}`));
+                }
+            });
+            // 发送提示词
+            proc.stdin.write(fullPrompt);
+            proc.stdin.end();
+        });
+    }
+    /**
+     * 检查 Claude CLI 是否可用
+     */
+    async isAvailable() {
+        return new Promise((resolve) => {
+            const proc = spawn(this.cliPath, ['--version'], {
+                stdio: 'ignore'
+            });
+            proc.on('close', (code) => {
+                resolve(code === 0);
+            });
+            proc.on('error', () => {
+                resolve(false);
+            });
+            // 2 秒超时
+            setTimeout(() => {
+                proc.kill();
+                resolve(false);
+            }, 2000);
+        });
+    }
+    /**
+     * 构建提示词
+     */
+    buildPrompt(prompt, context) {
+        let fullPrompt = prompt;
+        if (context) {
+            const contextInfo = this.summarizeContext(context);
+            fullPrompt = `${contextInfo}\n\n---\n\n${prompt}`;
+        }
+        return fullPrompt;
+    }
+    /**
+     * 总结 CodeMap 上下文
+     */
+    summarizeContext(codeMap) {
+        const lines = [];
+        lines.push('# Project Context');
+        lines.push('');
+        lines.push(`Project: ${codeMap.project.name}`);
+        lines.push(`Total Files: ${codeMap.summary.totalFiles}`);
+        lines.push(`Total Modules: ${codeMap.summary.totalModules}`);
+        lines.push('');
+        // 入口点
+        const entryPoints = codeMap.modules.filter(m => {
+            const basename = require('path').basename(m.path);
+            return basename === 'index.ts' || basename === 'main.ts' || basename === 'app.ts';
+        });
+        if (entryPoints.length > 0) {
+            lines.push('## Entry Points');
+            for (const ep of entryPoints.slice(0, 5)) {
+                lines.push(`- ${ep.path}`);
+            }
+            lines.push('');
+        }
+        // 模块列表
+        lines.push('## Modules');
+        for (const mod of codeMap.modules.slice(0, 20)) {
+            const exports = mod.exports.map(e => e.name).join(', ');
+            lines.push(`- ${mod.path}: ${exports || '(no exports)'}`);
+        }
+        if (codeMap.modules.length > 20) {
+            lines.push(`- ... and ${codeMap.modules.length - 20} more`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * 解析 Claude CLI JSON 响应
+     */
+    parseResponse(stdout) {
+        // Claude 可能输出多行 JSON，需要找到有效的 JSON
+        const lines = stdout.trim().split('\n');
+        let jsonStr = '';
+        // 从后往前找有效的 JSON 对象
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (line.startsWith('{') && line.endsWith('}')) {
+                jsonStr = line;
+                break;
+            }
+        }
+        if (!jsonStr) {
+            // 如果没有 JSON，直接返回原始输出
+            return { content: stdout.trim() };
+        }
+        const parsed = JSON.parse(jsonStr);
+        if (parsed.error) {
+            throw new Error(parsed.error);
+        }
+        return {
+            content: parsed.result || stdout.trim()
+        };
+    }
+}
+//# sourceMappingURL=claude.js.map