WorkBuddy Skill 全景地图

一句话：把散落在机器上的 WorkBuddy skills，变成一张可拖拽、可搜索、可看关系、可发现工作链路的全景地图。

你会看到什么

| 你想知道 | 地图回答 | |---|---| | 我装了哪些 skill？ | 左侧列表 + 中间力导向图，全部列出 | | 某个 skill 是干嘛的？ | 点节点，底部详情面板显示描述、触发词、输入→输出 | | 哪些 skill 是一类的？ | 7 色分类着色，左侧分类按钮一键过滤，地图同步高亮该类 | | skill 之间怎么串起来？ | 蓝色流光线展示「输出→输入」可衔接的工作链路（按热度分活跃/待唤醒/未探索） | | 最近热门有什么？ | 顶部 SkillHub 今日热门跑马灯，点击直达主页 | | 我实际用了哪些？ | 节点大小/透明度按调用热度缩放，顶部「最近冷落」提示曾高频已冷落的 skill | | 图太密 / 看不清怎么办？ | 右上角视图控制：⛶ 适应视图、⌂ 重置视图、文显隐标签；放大或悬停会重新显示标签 |

30 秒上手

对 WorkBuddy 说：「打开 skill 地图」
自动生成并打开 output/map.html；沙箱环境自动回退到应用内预览面板打开（HTML 内置 localStorage 安全垫片，不会白屏）。
在左侧搜索框输入关键词，或点击节点看详情。

也可以命令行运行：

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 导出结构化数据供二次分析。

skill.看一看