codemaps

AI 项目上下文管理工具。通过模块级文档（README.md + YAML frontmatter）自动生成 XML 索引，注入到 AGENTS.md 等规则文档，配合 AI Agent Hooks 实现会话级自动同步。

核心能力

• 扫描 — 递归发现项目中含 YAML frontmatter 的上下文文件
• 生成 — 将模块信息汇总为 <codemaps> XML 块，注入到目标文档
• 检查 — 对比 Git staged 文件，验证模块文档是否已同步更新
• 初始化 — 一键配置 codemaps.json + Claude Code / Cursor / Git hooks

安装

# 直接使用（推荐，零安装）
npx codemaps

# 或安装为项目开发依赖
npm i -D codemaps

要求 Node.js 20+。

快速开始

# 1. 初始化项目
npx codemaps init

# 2. 在模块目录创建 README.md（含 frontmatter）
# src/auth/README.md:
# ---
# description: 用户认证模块
# updated: 2026-04-27 11:00
# ---

# 3. 生成 codemap
npx codemaps

执行后，AGENTS.md 末尾会出现：

<codemaps>
<guide>
本项目使用模块上下文文档记录模块信息...
</guide>
<items>
<item path="src/auth/README.md" desc="用户认证模块" />
</items>
</codemaps>

命令

npx codemaps              # 扫描 → 解析 → 生成 → 更新目标文档
npx codemaps check        # 检查同步状态（默认 warn 模式）
npx codemaps check --strict  # 严格模式（不通过则退出码 1）
npx codemaps init         # 交互式初始化向导
npx codemaps --debug      # 任意命令 + --debug 输出诊断信息到 stderr
npx codemaps --version
npx codemaps --help

init 非交互式 flag

npx codemaps init --config       # 只创建 codemaps.json
npx codemaps init --claude-hook  # 配置 Claude Code Stop hook
npx codemaps init --cursor-hook  # 配置 Cursor afterAgentResponse hook
npx codemaps init --git-hook     # 安装 git pre-commit hook
npx codemaps init --all-hooks    # 配置所有（git + claude + cursor）

init 交互式向导

不带 flag 运行 npx codemaps init，向导会自动检测系统上已安装的 AI Agent 环境（~/.claude、~/.cursor），并在多选列表中默认选中已检测到的 Agent。使用空格选中/取消，回车确认。

配置文件

codemaps.json（项目根目录）：

{
  "targets": ["AGENTS.md"],
  "contextFiles": ["README.md"],
  "ignore": ["node_modules", ".git", "dist", "build", "vendor"]
}

| 字段 | 默认值 | 说明 | | -------------- | ----------------------- | ---------------- | | targets | ["AGENTS.md"] | 目标规则文档列表 | | contextFiles | ["README.md"] | 上下文文件名列表 | | ignore | ["node_modules", ...] | 忽略目录列表 |

模块文档格式

被纳入 codemap 的文件需要包含 YAML frontmatter：

---
description: 模块功能描述
updated: 2026-04-27 11:00
---

# 模块标题

模块详细内容...

• description — 模块功能简述（必填，功能不变时保持稳定）
• updated — 最近更新时间（必填，格式 YYYY-MM-DD HH:mm，每次代码修改必须更新）

双防线机制

| 防线 | 触发时机 | 说明 | | -------------- | ------------ | -------------------------------------------- | | Agent Hooks | AI 每轮对话结束 | 主力防线，Stop / afterAgentResponse 更新 codemap 并检查同步 | | Git pre-commit | git commit | 兜底防线，--strict 模式阻断不合规提交 |

Claude Code hooks（.claude/settings.json）

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "command": "npx codemaps && npx codemaps check", "type": "command" }
        ]
      }
    ]
  }
}

Cursor hooks（.cursor/hooks.json）

{
  "version": 1,
  "hooks": {
    "afterAgentResponse": [{ "command": "npx codemaps && npx codemaps check" }]
  }
}

输出格式

所有命令默认 JSON 输出到 stdout：

默认命令：

{
  "targets": ["AGENTS.md"],
  "itemsCount": 3,
  "items": [{ "path": "...", "desc": "..." }]
}

check 命令：

{ "passed": true, "violations": [] }

License

MIT