codemap

Codemap

Codemap 可即时为你提供任意代码库的架构上下文。它会自动通过钩子对你的意图进行分类、检测风险、匹配相关技能，并跟踪你的工作集。

Codemap 还应维护好每个项目自己的配置。首次在某个仓库中使用时，或输出明显杂乱时，应先调整 .codemap/config.json，再进行深入分析，这样后续调用就能优先关注代码，而不是资源文件。

命令

codemap .                       # Project structure and top files
codemap --deps                  # Dependency flow (imports/functions/hubs)
codemap --diff                  # Changes vs main branch
codemap --diff --ref <branch>   # Changes vs specific branch
codemap --importers <file>      # Who imports this file? Is it a hub?
codemap handoff .               # Build + save handoff artifact
codemap handoff --latest .      # Read latest saved handoff
codemap handoff --json .        # Machine-readable handoff payload
codemap skill list              # Show available skills with descriptions
codemap skill show <name>       # Get full skill instructions
codemap skill init              # Create custom skill template
codemap config show             # Show current project config
codemap context                 # Universal JSON context envelope
codemap context --for "prompt"  # With pre-classified intent + matched skills
codemap context --compact       # Minimal for token-constrained agents
codemap serve --port 9471       # HTTP API for non-MCP integrations

首次使用设置

在仓库中深入分析 Codemap 之前：

1. 检查 .codemap/config.json。
2. 如果该文件缺失、明显只是模板，或对于当前技术栈来说过于杂乱，请运行 codemap skill show config-setup 并按其说明操作。
3. 写入或改进配置后，重新运行 codemap . 和 codemap --deps。

将配置视为仓库记忆。调整好后，未来的 Codemap 调用都应能自动受益。

需要设置或调整配置的信号：

• 缺少 .codemap/config.json
• 配置仅包含通用的自动检测 only 值，没有针对项目的实际定制
• 输出的目录树中，大型非代码目录占据主导
• 特定技术栈带来的噪声淹没了源代码结构（.xcassets、screenshots、PDF、training-data、fixtures、生成文件、models、vendor 目录）
• 仓库使用的技术栈很明显，但配置中没有体现

何时使用

以下情况始终运行 codemap .：

• 开始任何新任务或功能开发
• 用户询问“X 在哪里？”或“哪些文件处理 Y？”
• 用户询问项目结构或组织方式
• 需要在修改前了解代码库

以下情况始终运行 codemap --deps：

• 用户询问“X 是如何工作的？”或“Y 被哪些地方使用？”
• 重构或移动代码
• 需要追踪导入关系或依赖项
• 查找枢纽文件（被导入次数最多的文件）

以下情况始终运行 codemap --diff：

• 用户询问“改了什么？”或“我修改了什么？”
• 提交前审查更改
• 总结某个分支上完成的工作

以下情况始终运行 codemap --importers <file>：

• 即将编辑某个文件——检查它是否为枢纽文件
• 需要了解更改的影响范围
• 决定是否重构或保持原样

以下情况运行 codemap skill show <name>：

• prompt-submit 钩子在 `` 中显示了匹配的技能
• 需要特定任务的指导（编辑枢纽文件、重构、测试）
• 风险级别为中或高

以下情况运行 codemap skill show config-setup：

• 仓库没有 .codemap/config.json
• 配置看起来只是一个基础引导配置，而不是真正的项目策略
• Codemap 输出被大型非代码目录弄得杂乱
• 希望 Codemap 针对该仓库做出更好的后续判断

以下情况运行 codemap context：

• 将 Codemap 智能信息传递给其他工具
• 需要项目状态的结构化 JSON 摘要
• 构建使用代码感知上下文的自动化流程

以下情况运行 codemap handoff：

• 在不同 Agent（Claude、Codex、Cursor）之间切换
• 休息后恢复工作
• 用户询问“下一个 Agent 应该了解什么？”

钩子输出

prompt-submit 钩子会在每条消息上触发，并提供：

Skills matched: hub-safety, refactor — run `codemap skill show <name>` for guidance

• 意图类别：重构、修复错误、功能开发、探索、测试、文档
• 风险级别：低（无枢纽文件）、中（1 个枢纽文件）、高（2 个或更多枢纽文件，或 8 个或更多导入者）
• 技能采用按需获取：只显示名称，运行 codemap skill show 查看完整内容

内置技能

技能	获取时机
config-setup	.codemap/config.json 缺失、只是模板或杂乱
hub-safety	编辑被 3 个或更多文件导入的文件
refactor	重组、重命名或移动代码
test-first	编写测试、采用 TDD 工作流
explore	理解代码的工作方式
handoff	在 AI Agent 之间切换

输出解读

树视图（codemap .）

• 星号（⭐）表示最大的 5 个源文件
• 目录只包含一个子目录时会被展平

依赖流（codemap --deps）

• 按语言分组的外部依赖
• 展示文件间连接方式的内部导入链
• HUBS 部分展示导入次数最多的文件（3 个及以上导入者）

差异模式（codemap --diff）

• (new) = 未跟踪，✎ = 已修改，(+N -M) = 更改的行数
• 警告图标表示枢纽文件（影响较大）

导入者（codemap --importers <file>）

• 显示所有导入此文件的文件
• 标记枢纽状态（3 个及以上导入者 = 影响较大）

上下文包（codemap context）

• 包含项目元数据、意图、工作集、匹配的技能和交接引用的 JSON
• --compact 会移除技能并限制工作集，以节省令牌

MCP 工具

如果已配置 codemap MCP 服务，则可使用以下工具：

工具	用途
get_structure	项目树
get_dependencies	依赖流和枢纽
get_diff	显示更改文件及其影响
find_file	按文件名搜索
get_importers	查看哪些文件导入了某个文件
get_hubs	列出所有枢纽文件
get_file_context	获取单个文件的完整上下文
get_handoff	构建/读取交接产物
get_working_set	本次会话中编辑的文件
list_skills	可用技能（元数据）
get_skill	完整的技能说明
get_activity	最近的编码活动
start_watch / stop_watch	控制守护进程
status	验证 MCP 连接
list_projects	发现项目

HTTP API

运行 codemap serve 时：

端点	返回内容
GET /api/context?intent=...	上下文包
GET /api/skills	所有技能元数据
GET /api/skills/<name>	完整的技能正文
GET /api/working-set	当前工作集
GET /api/health	服务健康状态