codemap

Codemap 技能

你可以通过创建分层代码地图，帮助用户了解和梳理代码仓库。

适用场景

• 用户要求了解或梳理代码仓库
• 用户需要代码库文档
• 开始处理不熟悉的代码库

工作流

第 1 步：检查现有状态

首先，检查仓库根目录中是否存在 .slim/codemap.json。

如果不存在，检查旧版状态文件 .slim/cartography.json。

如果旧版状态存在：将 .slim/cartography.json 移动到 .slim/codemap.json，然后继续检测变更。

如果 .slim/codemap.json 存在：跳至第 3 步（检测变更），无需重新初始化。

如果两个文件都不存在：继续执行第 2 步（初始化）。

第 2 步：初始化（仅在不存在状态文件时执行）

1. 分析代码仓库结构——列出文件，了解目录
2. 推断模式，仅纳入核心代码/配置文件：
   • 纳入：src/**/*.ts、package.json 等
   • 排除（必须）：不要纳入测试、文档或翻译文件。
     • 测试：**/*.test.ts、**/*.spec.ts、tests/**、__tests__/**
     • 文档：docs/**、*.md（必要时可纳入根目录的 README.md）、LICENSE
     • 构建/依赖：node_modules/**、dist/**、build/**、*.min.js
   • 自动遵循 .gitignore
3. 运行 codemap.mjs init（scripts/codemap.mjs 相对于此技能的基础目录——宿主会将其显示为 Base directory for this skill）：

node scripts/codemap.mjs init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"

这会创建：

• .slim/codemap.json——用于检测变更的文件和文件夹哈希
• 所有相关子目录中的空 codemap.md 文件

4. 委派 Fixer Agent 编写代码地图——每个文件夹启动一个 Fixer，让其读取代码并创建或更新对应的 codemap.md 文件。

第 3 步：检测变更（已有状态文件时执行）

1. 运行 codemap.mjs changes，查看变更内容：

node scripts/codemap.mjs changes \
  --root ./

2. 查看输出——其中会显示：

   • 新增文件
   • 删除文件
   • 修改文件
   • 受影响的文件夹

3. 仅更新受影响的代码地图——每个受影响的文件夹启动一个 Fixer，更新其 codemap.md。

4. 运行 update，保存新状态：

node scripts/codemap.mjs update \
  --root ./

第 4 步：整理代码仓库地图（根目录代码地图）

所有特定目录都完成映射后，Orchestrator 必须创建或更新根目录的 codemap.md。此文件作为任何进入代码仓库的 Agent 或人员的主入口。

1. 梳理根目录资源：记录根目录级别的文件（例如 package.json、index.ts、plugin.json）和项目的整体用途。
2. 汇总子地图：创建一个“代码仓库目录地图”部分。对于每个包含 codemap.md 的文件夹，提取其职责概要，并将其列入根目录地图中的表格或列表。
3. 交叉引用：确保根目录地图包含子地图的绝对或相对路径，方便 Agent 直接跳转到相关详情。

第 5 步：在 AGENTS.md 中注册代码地图

**OpenCode 会在每次会话中自动将 AGENTS.md 加载到 Agent 上下文中。**为确保 Agent 能自动发现并使用代码地图，请更新（或创建）仓库根目录的 AGENTS.md：

1. 如果 AGENTS.md 已存在，且已包含 ## Repository Map 部分，跳过此步骤——引用已设置。
2. 如果 AGENTS.md 已存在，但不包含 ## Repository Map 部分，请追加以下部分。
3. 如果 AGENTS.md 不存在，请使用以下部分创建该文件。

## Repository Map

A full codemap is available at `codemap.md` in the project root.

Before working on any task, read `codemap.md` to understand:
- Project architecture and entry points
- Directory responsibilities and design patterns
- Data flow and integration points between modules

For deep work on a specific folder, also read that folder's `codemap.md`.

此操作具有幂等性——重复运行代码地图时，会检测到已有部分并跳过，不会重复添加。

Codemap 内容

Fixer 负责在此工作流中编写 codemap.md 文件。使用精准的技术术语记录实现：

• 职责 - 使用标准软件工程术语（例如“服务层”“数据访问对象”“中间件”）定义此目录的具体作用。
• 设计模式 - 识别并命名所用的具体模式（例如“观察者”“单例”“工厂”“策略”）。详细说明抽象和接口。
• 数据与控制流 - 明确追踪数据如何进入和离开模块。提及具体的函数调用序列和状态转换。
• 集成点 - 列出依赖项和使用此模块的其他模块。使用钩子、事件或 API 端点的技术名称。

示例骨架：

# src/<dir>/
## Responsibility
<role of this directory>
## Design
<patterns and abstractions>
## Flow
<data in → key calls → data out>
## Integration
<consumers / dependencies>

对于根 atlas，汇总相同的标题，并添加目录映射表：

目录	职责	链接
src/<dir>/		查看映射