项目上下文地图

问题从哪来

在陌生或大型仓库里，agent 常见做法是整仓 Glob/Grep 或逐文件 Read。这不仅耗 token，还容易踩坑：例如 ripgrep 默认跳过 .deps 等隐藏目录，会出现「搜不到其实存在的符号」的误判。你需要的是会话级全局认知——先有一张紧凑、可检索的索引，再按关键词落到少数文件。

技能如何工作

本技能用 build_map.py（Python 3.8+ 标准库、离线、无 pip）生成 /.workbuddy/project-map.md，可选 --json 导出 project-map.json。地图通常包含：

• 目录树与每文件一行摘要（docstring/首行注释）
• 符号索引（class/function/type，多语言正则启发式）
• 依赖与调用关系（文字有向边，模块/可选文件级）
• API 路由（Flask/FastAPI/Django/Express/NestJS/Next 等）
• 部署架构角色（设备端/服务器/客户端/桩/外部 URL，与 import 依赖是不同维度）
• 核心文件重要性排序、死代码提示、展示层密钥脱敏

增量靠 .workbuddy/project-map.cache.json（文件 hash）；重跑只重算变更文件。查定位应走技能的 --search 流程（先地图再默认读前几个命中），而不是绕过统计手动翻地图。

设计上支持零配置自启：在含源码的工作区，agent 加载技能后会确保地图存在且较新；小项目可用 --min-files（hook 默认 20）跳过建图。

边界与注意

• 小于约 20 个文件的项目，建图索引开销可能大于直接读；不必硬建。
• 符号、路由、调用图、死代码均为启发式，动态/装饰器/宏场景可能漏提或误提；文件路径比符号名更可靠，删「疑似未用」前需人工确认。
• 地图是快照；结构大改后需 refresh；--timeout 超大仓可能只产出部分地图。
• 只读写 /.workbuddy/ 下的地图与缓存，不改源码；MCP/Tree-sitter 精确解析在路线中暂缓。