cartography

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cartography Skill

You help users understand and map repositories by creating hierarchical codemaps.

你可以通过创建分层代码地图，帮助用户理解并映射代码仓库。

When to Use

使用场景

User asks to understand/map a repository
User wants codebase documentation
Starting work on an unfamiliar codebase

用户请求理解/映射某个代码仓库
用户需要代码库文档
开始接手不熟悉的代码库工作

Workflow

工作流程

Step 1: Check for Existing State

步骤1：检查现有状态

First, check if
.slim/cartography.json
exists in the repo root.

If it exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.

If it doesn't exist: Continue to Step 2 (Initialize).

首先，检查仓库根目录下是否存在
.slim/cartography.json
文件。

如果已存在：跳过步骤3（检测变更）——无需重新初始化。

如果不存在：继续步骤2（初始化）。

Step 2: Initialize (Only if no state exists)

步骤2：初始化（仅当无现有状态时执行）

Analyze the repository structure - List files, understand directories
Infer patterns for core code/config files ONLY to include:
- Include:
```
src/**/*.ts
```
  ,
```
package.json
```
  , etc.
- Exclude (MANDATORY): Do NOT include tests, documentation, or translations.
  - Tests:
```
**/*.test.ts
```
    ,
```
**/*.spec.ts
```
    ,
```
tests/**
```
    ,
```
__tests__/**
```
  - Docs:
```
docs/**
```
    ,
```
*.md
```
    (except root
```
README.md
```
    if needed),
```
LICENSE
```
  - Build/Deps:
```
node_modules/**
```
    ,
```
dist/**
```
    ,
```
build/**
```
    ,
```
*.min.js
```
- Respect
```
.gitignore
```
  automatically
Run cartographer.py init:

bash

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

This creates:

```
.slim/cartography.json
```
- File and folder hashes for change detection
Empty
```
codemap.md
```
files in all relevant subdirectories

Delegate to Explorer agents - Spawn one explorer per folder to read code and fill in its specific
```
codemap.md
```
file.

分析仓库结构——列出文件，理解目录组织
推断需包含的核心代码/配置文件模式：
- 包含：
```
src/**/*.ts
```
  、
```
package.json
```
  等
- 排除（强制要求）：请勿包含测试、文档或翻译文件。
  - 测试文件：
```
**/*.test.ts
```
    、
```
**/*.spec.ts
```
    、
```
tests/**
```
    、
```
__tests__/**
```
  - 文档文件：
```
docs/**
```
    、
```
*.md
```
    （除非必要，否则不包含根目录的
```
README.md
```
    ）、
```
LICENSE
```
  - 构建/依赖文件：
```
node_modules/**
```
    、
```
dist/**
```
    、
```
build/**
```
    、
```
*.min.js
```
- 自动遵循
```
.gitignore
```
  规则
运行 cartographer.py init 命令：

bash

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
```
文件

委托给Explorer Agent——为每个文件夹启动一个Explorer Agent，读取代码并填充对应目录的
```
codemap.md
```
文件。

Step 3: Detect Changes (If state already exists)

步骤3：检测变更（如果存在现有状态）

Run cartographer.py changes to see what changed:

bash

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

Review the output - It shows:
- Added files
- Removed files
- Modified files
- Affected folders
Only update affected codemaps - Spawn one explorer per affected folder to update its
```
codemap.md
```
.
Run update to save new state:

bash

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

运行 cartographer.py changes 命令查看变更内容：

bash

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

查看输出结果——内容包括：
- 新增文件
- 删除文件
- 修改文件
- 受影响的文件夹
仅更新受影响的代码地图——为每个受影响的文件夹启动一个Explorer Agent，更新其
```
codemap.md
```
文件。
运行更新命令保存新状态：

bash

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

Step 4: Finalize Repository Atlas (Root Codemap)

步骤4：完成仓库地图集（根目录代码地图）

Once all specific directories are mapped, the Orchestrator must create or update the root

codemap.md

. This file serves as the Master Entry Point for any agent or human entering the repository.

Map Root Assets: Document the root-level files (e.g.,
```
package.json
```
,
```
index.ts
```
,
```
plugin.json
```
) and the project's overall purpose.
Aggregate Sub-Maps: Create a "Repository Directory Map" section. For every folder that has a
```
codemap.md
```
, extract its Responsibility summary and include it in a table or list in the root map.
Cross-Reference: Ensure that the root map contains the absolute or relative paths to the sub-maps so agents can jump directly to the relevant details.

当所有具体目录的地图都已生成后，Orchestrator 必须创建或更新根目录的

codemap.md

文件。该文件是任何Agent或开发人员进入仓库的主入口点。

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

Codemap Content

代码地图内容

Explorers are granted write permissions for

codemap.md

files during this workflow. Use precise technical terminology to document the implementation:

Responsibility - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
Design Patterns - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
Data & Control Flow - Explicitly trace how data enters and leaves the module. Mention specific function call sequences and state transitions.
Integration Points - List dependencies and consumer modules. Use technical names for hooks, events, or API endpoints.

Example codemap:

markdown

undefined

在工作流程中，Explorer Agent 被授予

codemap.md

文件的写入权限。请使用精准的技术术语记录实现细节：

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

示例代码地图：

markdown

undefined

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

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

Plugin loads → calls getAgentConfigs()
Reads user config preset
Merges defaults with overrides
Applies permission rules (wildcard expansion)
Returns agent configs to OpenCode

Plugin loads → calls getAgentConfigs()
Reads user config preset
Merges defaults with overrides
Applies permission rules (wildcard expansion)
Returns agent configs to OpenCode

Integration

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


Example **Root Codemap (Atlas)**:

```markdown

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


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

```markdown

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.

```
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/features/`	Core logic for tmux integration, background task spawning, and session state.	View Map
`src/config/`	Implements the configuration loading pipeline and environment variable injection.	View Map

undefined

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

undefined