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：完成代码仓库图谱（根目录代码地图）

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

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

代码地图内容

在此工作流中，Explorer 获得了 codemap.md 文件的写入权限。请使用精确的技术术语记录实现：

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

代码地图示例：

# 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

**根目录代码地图（图谱）**示例：

# 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) |