cartography

制图技能

通过创建分层代码地图，帮助用户了解和绘制代码仓库。

适用场景

• 用户要求了解或绘制代码仓库
• 用户想编写代码库文档
• 开始处理不熟悉的代码库

工作流

步骤 1：检查是否已有状态

首先，检查代码仓库根目录中是否存在 .slim/cartography.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. 运行 cartographer.py init：

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"

这会创建：

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

4. 委派给 Explorer Agent——每个文件夹启动一个 Explorer Agent，读取代码并填写对应的 codemap.md 文件。

步骤 3：检测变更（状态已存在时执行）

1. 运行 cartographer.py changes，查看变更内容：

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
  --root ./

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

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

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

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

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py 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 内容

在此工作流中，探索者获准写入 codemap.md 文件。请使用精确的技术术语记录实现：

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

Codemap 示例：

# src/agents/

## Responsibility
Defines agent personalities and manages their configuration lifecycle.

## Design
Each agent is a prompt + permission set. Config system uses:
- Default prompts (orchestrator.ts, explorer.ts, etc.)
- User overrides from ~/.config/opencode/oh-my-opencode-slim.json
- Permission wildcards for skill/MCP access control

## Flow
1. Plugin loads → calls getAgentConfigs()
2. Reads user config preset
3. Merges defaults with overrides
4. Applies permission rules (wildcard expansion)
5. Returns agent configs to OpenCode

## Integration
- Consumed by: Main plugin (src/index.ts)
- Depends on: Config loader, skills registry

根级 Codemap（Atlas） 示例：

# Repository Atlas: oh-my-opencode-slim

## Project Responsibility
A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.

## System Entry Points
- `src/index.ts`: Plugin initialization and OpenCode integration.
- `package.json`: Dependency manifest and build scripts.
- `oh-my-opencode-slim.json`: User configuration schema.

## Directory Map (Aggregated)
| Directory | Responsibility Summary | Detailed Map |
|-----------|------------------------|--------------|
| `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
| `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
| `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |