WorkBuddy Skill 全景地图
一句话：把散落在机器上的 WorkBuddy skills，变成一张可拖拽、可搜索、可看关系、可发现工作链路的全景地图。
你会看到什么
| 你想知道 | 地图回答 |
|---|---|
| 我装了哪些 skill？ | 左侧列表 + 中间力导向图，全部列出 |
| 某个 skill 是干嘛的？ | 点节点，底部详情面板显示描述、触发词、输入→输出 |
| 哪些 skill 是一类的？ | 7 色分类着色，左侧分类按钮一键过滤，地图同步高亮该类 |
| skill 之间怎么串起来？ | 蓝色流光线展示「输出→输入」可衔接的工作链路（按热度分活跃/待唤醒/未探索） |
| 最近热门有什么？ | 顶部 SkillHub 今日热门跑马灯，点击直达主页 |
| 我实际用了哪些？ | 节点大小/透明度按调用热度缩放，顶部「最近冷落」提示曾高频已冷落的 skill |
| 图太密 / 看不清怎么办？ | 右上角视图控制：⛶ 适应视图、⌂ 重置视图、文 显隐标签；放大或悬停会重新显示标签 |
30 秒上手
- 对 WorkBuddy 说：「打开 skill 地图」
- 自动生成并打开
output/map.html；沙箱环境自动回退到应用内预览面板打开（HTML 内置localStorage安全垫片，不会白屏）。 - 在左侧搜索框输入关键词，或点击节点看详情。
> 也可以命令行运行：
> bash
> python scripts/build_map.py # 生成并自动打开
> python scripts/build_map.py --no-open # 只生成不打开
>
使用方式
| 你说 | 系统做什么 |
|---|---|
| 「打开 skill 地图」 | 扫描 skills 并生成 output/map.html，自动打开 |
| 「skill 全景 / skill 可视化」 | 同上 |
| 「查看 xxx 怎么用」 | 在地图搜索 xxx，点节点看详情面板 |
> 无输入也会跑：不传参数直接运行，自动扫描用户级 ~/.workbuddy/skills/ + 当前工作区 .workbuddy/skills/，地图永远有内容。
CLI 参数
| 参数 | 作用 |
|---|---|
--no-open |
生成后不自动打开浏览器 |
--offline |
跳过 SkillHub 联网拉取，走缓存/本地推荐（离线免等超时） |
--json <路径> |
导出结构化数据到 JSON（二次分析用，缺省 output/skill-map-data.json） |
--set-category <id> <分类> |
写回 categories_override.json（图内右键纠错的终端落地） |
--verbose / --no-color |
打印原始堆栈 / 关闭终端 ANSI 颜色 |
▶ 执行流程（agent 必读）
- 运行
python scripts/build_map.py。⚠️ 不要加--offline：默认联网拉取 SkillHub 热门、刷新缓存，避免用户看到「缓存过期」；仅当用户明确要求离线时才用。 - 务必调用
present_files(output/map.html)——这是沙箱环境下唯一可靠的可见路径。 - 完全访问权限下
os.startfile会真正调起宿主浏览器，与应用内预览形成双保险。
能力边界
| 维度 | 说明 |
|---|---|
| 能做什么 | 扫描本机 skills，生成单文件离线 HTML：安装清单、分类分布、调用热度、关联边、技能链路、SkillHub 热门 |
| 不能做什么 | 不安装/卸载/启用/修改 skill；不联网分析他人技能；不替代任务路由 |
| 数据来源 | 本地 SKILL.md frontmatter、调用日志（workbuddy.db）、SkillHub API（仅热门） |
| 分类体系 | 7 大标准分类 +「其他」，口径见 references/taxonomy.md |
何时不要使用
- 需要安装 / 卸载 / 启用 / 修改 skill —— 本 skill 是只读可视化工具。
- 需要分析他人 / 远程技能库 —— 只读取本机本地数据。
- 需要任务路由 / SkillHub 搜索 —— 它是「看清已有」，不负责「该用哪个」。
- 要把
map.html发给不信任的人 —— 含本机全部 skill 名，先脱敏。
反模式
- ❌ 直接把
map.html发给不信任的人 → 先脱敏再分享。 - ❌ 指望它替代任务路由 / SkillHub 搜索 → 它是可视化，不是决策器。
- ❌ 把
categories_override.json当分类规则库堆关键词 → 只用于 override 例外。 - ❌ 反复跑
build_map.py却不归档output/旧报告 → 定期归档保持目录聚焦。
排障
症状速查表
| 你遇到的现象 | 看哪里 |
|---|---|
| 地图里少了某个 skill | references/faq.md（反模式使用者篇 · Q2） |
| 节点是灰色 / 分类不对 | references/faq.md（反模式作者篇 · Q4） |
| 顶部热门显示「缓存」/「离线」 | references/faq.md Q3 |
| 地图打开空白 / 力导向图不动 | references/faq.md Q25 |
| 想完全离线运行 | references/faq.md Q5 · Q15 |
进阶配置
扫描项目级 / 连接器 skills
默认只扫用户级 ~/.workbuddy/skills/。用环境变量扩展：
set WB_SKILL_MAP_EXTRA_ROOTS=C:\project1\.workbuddy\skills;C:\project2\.workbuddy\skills
python scripts/build_map.py
扫描到的 skill 会标注来源：🗂️ 项目级 / 🔌 连接器 / ✅ 自建 / 📦 市场。
自定义分类
编辑 scripts/categories_override.json（图内右键节点也能一键生成纠错命令）：
{ "skill_id": "投资分析引擎", "another_skill": ["投资分析引擎", "文档 & 可视化"] }
技术亮点
- 完全离线 + 优雅降级：D3 内联、localStorage 安全垫片、D3 双重校验；任何单点失败都自动回退、终端中文提示，不中断整体生成。
- 技能链路自动发现 + IO 断点：基于「输入→输出」格式匹配展示可串接工作流，按使用热度三级着色，并提示「有输出无人接 / 有输入无人产」的缺中间环节。
- 节点热度 + 个性化推荐：扫描调用日志，节点大小反映真实使用频率；顶部「最近冷落」推荐曾高频、最近少用的 skill。
- 多来源扫描 + 来源筛选：用户级 / 项目级 / 连接器统一可视化，来源筛选栏一键过滤。
- 标识性名称提取：优先读
workbuddy.json/_skillhub_meta.json元数据，自动跳过skill_<数字>自动 ID，显示「腾讯ima」等友好名。 - 分类置信度 + 图内纠错：三档置信度区分「作者自报」与「启发式猜测」，低置信节点虚线环标注，右键即可纠错。
- 导出分享：一键导出 PNG/SVG 截图，
--json导出结构化数据供二次分析。
更多文档
- 完整 FAQ（Q1–Q27）：
references/faq.md - 自动降级链路与终端提示对照：
references/troubleshooting.md - 分类口径与 override 规则：
references/taxonomy.md - 技术亮点沿革与完整版本历史：
references/changelog.md
