repo-mapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Repo Mapping Skill

仓库映射Skill

Build and maintain a cached AST-based map of repository symbols and imports using ast-grep.

使用ast-grep构建并维护基于AST的仓库符号与导入缓存地图。

Parse Arguments

解析参数

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const action = args.find(a => !a.startsWith('--')) || 'status';
const force = args.includes('--force');

javascript

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const action = args.find(a => !a.startsWith('--')) || 'status';
const force = args.includes('--force');

Primary Responsibilities

主要职责

Generate map on demand (
```
/repo-map init
```
)
Update map incrementally (
```
/repo-map update
```
)
Check status and staleness (
```
/repo-map status
```
)
Validate output with the map-validator agent

按需生成地图（
```
/repo-map init
```
）
增量更新地图（
```
/repo-map update
```
）
检查状态与过期情况（
```
/repo-map status
```
）
使用map-validator Agent验证输出

Core Data Contract

核心数据约定

Repo map is stored in the platform state directory:

Claude Code:
```
.claude/repo-map.json
```
OpenCode:
```
.opencode/repo-map.json
```
Codex CLI:
```
.codex/repo-map.json
```

Minimal structure:

json

{
  "version": "1.0.0",
  "generated": "2026-01-25T12:00:00Z",
  "updated": "2026-01-25T12:05:00Z",
  "git": { "commit": "abc123", "branch": "main" },
  "project": { "languages": ["typescript", "python"] },
  "stats": { "totalFiles": 142, "totalSymbols": 847 },
  "files": {
    "src/auth/login.ts": {
      "hash": "deadbeef1234abcd",
      "language": "typescript",
      "symbols": { "exports": [], "functions": [], "classes": [] },
      "imports": [ { "source": "./utils", "kind": "named" } ]
    }
  }
}

仓库地图存储在平台状态目录中：

Claude Code:
```
.claude/repo-map.json
```
OpenCode:
```
.opencode/repo-map.json
```
Codex CLI:
```
.codex/repo-map.json
```

最小结构：

json

{
  "version": "1.0.0",
  "generated": "2026-01-25T12:00:00Z",
  "updated": "2026-01-25T12:05:00Z",
  "git": { "commit": "abc123", "branch": "main" },
  "project": { "languages": ["typescript", "python"] },
  "stats": { "totalFiles": 142, "totalSymbols": 847 },
  "files": {
    "src/auth/login.ts": {
      "hash": "deadbeef1234abcd",
      "language": "typescript",
      "symbols": { "exports": [], "functions": [], "classes": [] },
      "imports": [ { "source": "./utils", "kind": "named" } ]
    }
  }
}

Behavior Rules

行为规则

Never run ast-grep without user approval if it is not installed
Never install dependencies without explicit user consent
Always validate map output with
```
map-validator
```
after init/update
Prefer incremental update unless map is stale or history rewritten

若未安装ast-grep，绝不能在未获得用户批准的情况下运行它
绝不能在未获得用户明确同意的情况下安装依赖
初始化/更新后必须使用
```
map-validator
```
验证地图输出
除非地图已过期或历史记录被重写，优先使用增量更新

When to Suggest Repo Map

何时建议使用仓库地图

If a user asks for drift detection, documentation alignment, or repo analysis and repo-map is missing:

Repo map not found. For better analysis, run:
  /repo-map init

如果用户要求进行漂移检测、文档对齐或仓库分析，但未找到仓库地图时：

未找到仓库地图。为获得更优分析结果，请运行：
  /repo-map init

Staleness Signals

过期信号

Map commit not found (rebased)
Branch changed
Git hooks marked stale
Commits behind HEAD

地图对应的提交不存在（已变基）
分支已更改
Git钩子标记为过期
提交落后于HEAD

Output Expectations

输出规范

Keep outputs concise:

init/update: file count, symbol count, commit, warnings
status: staleness, commits behind, last updated

保持输出简洁：

初始化/更新：文件数量、符号数量、提交记录、警告信息
状态查询：过期情况、落后提交数、最后更新时间