craftsman-map

把任意代码库编译成分层知识图谱，通过 MCP 协议让 AI 编程工具在改代码前真正读懂项目——而不是凭印象乱改。

五层架构，对应五件事：

• INGEST（摄取）：多语言解析 + 文档资产导入 → 统一图谱
• MAP（地图）：功能块聚类 + 渐进披露 → 省 token
• NAVIGATE（导航）：影响面分析 + git 历史 → 双轨证据
• UNDERSTAND（理解）：把代码翻译成人话 → wiki 描述 + 调用方 LLM 增强
• TRACE（工作链）：入口到出口调用链路追踪 → 大模型定位 bug 的核心能力

---

安装

pip install craftsman-map

依赖说明：

• 零强制依赖：Python 解析用内置 ast，图谱用纯 Python，开箱即用
• 可选增强：pip install tree-sitter tree-sitter-javascript tree-sitter-typescript tree-sitter-go → 解锁 JS/TS/Go 多语言
• git 历史：pip install dulwich → 无需安装 git 二进制，纯 Python 读 git 历史

---

快速上手

# 1. 在你的项目根目录建立索引（改代码前必须先跑这个）
cd /path/to/your-project
craftsman-map index

# 2. 看功能块地图（渐进披露第一层）
craftsman-map map

# 3. 找符号
craftsman-map search "UserService"

# 4. 看符号详情 + 邻居
craftsman-map symbol "src/auth/service.py::UserService"

# 5. 分析影响面（改这里会波及哪里）
craftsman-map impact "src/auth/service.py::UserService.login"

# 6. 钻取展开（渐进披露第二层）
craftsman-map explore "src/auth/service.py::UserService" --depth 2

# 7. 热点分析（哪些文件改动最频繁）
craftsman-map hotspots

# 8. 统计概览
craftsman-map overview

# 9. 分层架构视图（自动标出入口/核心/工具层）
craftsman-map layers

# 10. 自动识别真实入口
craftsman-map entrypoints

# 11. 工作链：追踪从入口到出口的调用路径
craftsman-map trace "src/main.py::main"

# 12. 生成 wiki 描述（规则版，零成本）
craftsman-map wiki

# 13. 拿某个功能块的描述原料包（给调用方 LLM 生成描述用）
craftsman-map describe --cluster 0

# 14. 把 LLM 生成的描述写回缓存
craftsman-map desc --cluster 0 --text "这个模块负责..."

---

命令全集

命令	作用	典型用途
index [PATH]	建立/刷新索引	首次使用或代码变更后
overview	节点/边/语言统计	了解项目规模
map	功能块总览	渐进披露第一层，只看摘要
search QUERY	符号搜索	找函数/类/变量
symbol ID	符号详情 + 邻居	精确查看某个符号
impact ID	影响面分析	改动前评估波及范围
explore ID	渐进钻取	从某节点展开邻居
hotspots	变更热点 + 共变关系	找高风险区域
layers	分层架构视图	自动标出入口/核心/工具/配置层
entrypoints	识别真实入口	找出项目真正的调用起点
trace ID	工作链追踪	从入口到出口的完整调用路径
wiki	生成 wiki 描述	把代码翻译成人话（规则版，零成本）
describe	输出描述原料包	给调用方 LLM 生成高质量描述用
desc	回写 LLM 描述	把调用方生成的描述缓存进图谱

所有命令默认输出 JSON（适合大模型解析），加 --pretty 格式化输出。

---

为什么给大模型用？

LLM 的真痛点不是"看不懂代码"，是"找不准 + 看太多"。

craftsman-map 的设计原则：

1. 渐进披露省 token：map 先给功能块摘要（10 行），锁定目标后再 explore 钻进去——不一次吞下 5000 个函数。

2. 置信度体系：每条边都带 confidence 字段（静态铁证 1.0 / 歧义 0.6 / 悬空 0.4），让大模型知道哪些是确定事实、哪些是推断。

3. next_actions 引导：每个输出都包含"下一步可以调哪些命令"，消除大模型的猜测。

4. 双轨影响面：静态调用图 + git 共变历史。纯静态图会漏掉"没有直接调用关系但经常一起改"的隐式耦合。

---

MCP 接入（让大模型自主调用）

craftsman-map 内置 MCP server，标准 stdio JSON-RPC 协议：

craftsman-map serve-mcp

在 AWS Code / Cursor / Cline / Windsurf / Continue 配置：

{
  "mcpServers": {
    "craftsman-map": {
      "command": "craftsman-map",
      "args": ["serve-mcp"]
    }
  }
}

clients/ 目录里有各平台配置文件，复制粘贴即用。MCP 提供 16 个工具，覆盖全部 CLI 命令，AI 可按需自主调用。

---

支持语言

语言	支持状态	后端
Python	✅ 内置，零依赖	内置 ast
JavaScript	✅ 可选	tree-sitter
TypeScript	✅ 可选	tree-sitter
Go	✅ 可选	tree-sitter
Markdown / txt	✅ 内置	文本解析
图片 / 二进制资产	✅ 内置（记录路径，不读内容）	AssetParser

---

项目结构

craftsman-map/
├── craftsman_map/
│   ├── cli.py              # CLI 入口
│   ├── mcp_server.py       # MCP stdio server（16 个工具）
│   ├── indexer.py          # INGEST 层：扫描 + 解析 + 建图
│   ├── git_history.py      # git 历史维度（dulwich 纯 Python）
│   ├── graph/
│   │   ├── model.py        # Node / Edge 数据模型（含 confidence）
│   │   ├── store.py        # CodeGraph 存储 + 聚类 + 序列化
│   │   └── linker.py       # 引用消解
│   ├── parsers/
│   │   ├── base.py         # 解析器抽象接口
│   │   ├── python_parser.py
│   │   ├── ts_parser.py    # JS/TS/Go（tree-sitter）
│   │   └── doc_parser.py   # Markdown / 资产
│   ├── understand/
│   │   ├── wiki.py         # 理解层：规则描述 + 原料包 + 注入回写
│   │   ├── view.py         # 分层视图
│   │   └── trace.py        # 工作链追踪
│   └── commands/
│       ├── core.py
│       └── understand.py
├── tests/                  # 68 条测试，全部 passed
├── clients/                # 各平台 MCP 配置文件
└── pyproject.toml

---

开发 & 测试

pip install -e ".[dev]"
pytest tests/ -v

68 passed，0 skipped，0 failed。

---

💝 赞助 / Sponsor

如果 craftsman-map 对你有帮助，欢迎赞助支持持续开发与维护。

If craftsman-map helps you, consider sponsoring to support ongoing development.

---

设计哲学

craftsman-map 的核心信念：LLM 理解代码库，靠的不是"看全部"，而是"看对的部分"。

把代码库编译成结构化知识图谱，通过确定性 CLI 精准披露——五层架构对应五件事：摄取、分层、导航、理解、查询。每一层都可独立使用，也可以组合成完整的代码理解流水线。

欢迎提 issue 和 PR。

---

联系 / Contact

有任何问题、建议或合作意向，欢迎随时发邮件联系。

Feel free to reach out by email for any questions, suggestions, or collaboration.

• 📧 Email: 545118959@qq.com
• 💬 Issues: github.com/EthanXue666/craftsman-map/issues

---

License

MIT — 个人和商业项目均可免费使用。