Workbuddy_skill_check 技能生态管理中枢
> 概念名 skill-check：本技能是用户级 skill 管理专家，对外统一叫「skill 检查 / 体检」。
积木（Blocks）设计哲学
本技能遵循「积木艺术审美」——少即是多，空即有物。
- 模块化：七大能力是独立积木块，通过数据管道（TSV/JSON）而非代码耦合串联
- 一主二辅三点睛：暖纸基底 60% + 墨灰文字分割 30% + 珊瑚橙点睛 10%——色彩只在「该被看见的数字」上出现
- 三秒法则：仪表板首屏结论条让用户 3 秒知道「要不要管」；30 秒看 KPI 与关注列表；深读再展开明细
- 版式固化：仪表板视觉宪法在
references/dashboard-template.html（v1.1.0），dashboard_blocks.py是纯数据引擎。改外观只动模板，改逻辑只动脚本——互不耦合。 - 交互能力（v1.1.0）：可排序表格 · 名称搜索 · 散点图联动定位 · 技能内联8维详情 · 前后对比Δ列 · 一键复制命令 · 卡片折叠 · 趋势hover · 键盘快捷键(D/F/1-4) · 打印样式 · 数据导出(TSV/JSON) · 数据新鲜度指示器 · 5分钟自动刷新
详见 design-review-blocks.md。
定位
编排层，非单体工具。以 8 维量化评分为中枢，串联「体检 → 修复 → 升级 → 生态优化 → 安装推荐 → 仪表板 → 跨技能深检」七项闭环。
> 📜 历史变更已外置至 references/CHANGELOG.md。
v7 核心：从"技能质量"升维到"对用户该不该管"
- 画像层驱动：读
state/profile.json（角色/工作流/P0–P3 权重），标定业务重要性；缺失时退化为纯质量模式（中性权重 0.5） - 二维优先级：
priority = biz_weight × (100 − total_score)，关注列表收敛到 ≤5 个 - 链路断点检测：遍历每条 workflow chain，找未安装/低分掉队技能
- 四象限散点：左上（高权重·低分）必处理，右下（低权重·高分）可缓
- 修复≠升级分轨：修复=改本地文件，升级=人工确认（禁自动/批量）；只改自建技能
能力边界（速览）
> 不想读长文？记住下面这张卡就够了。DO = 我帮你做的事；DON'T = 我不会做的事。
| ✅ DO（我能做） | ⛔ DON'T（我不做） |
|---|---|
| 只读体检：8 维评分、生态分析、升级检查、跨技能深检 | 不自动改任何技能文件（分析引擎全程只读） |
自动修复 agent_created 自建技能的 L1 类问题（frontmatter/触发词） |
不碰 marketplace / plugin / skillhub 来的非自建技能（只出报告） |
| 修复前自动备份、失败自动回滚 | 不突破「每日≤10 次修复」上限（限在 repair_strategies.json 可调） |
| 生成升级方案 + 安全命令模板 | 不自动执行升级；升级需你在会话里明确确认，单次≤1 个 |
| 按画像层算业务优先级，关注列表收敛到 ≤5 | 不为凑数列长清单；不足阈值就显示「本期无需关注」 |
| 周/月自动化跑体检并出简报 | 不在自动化里自动修复或升级（只报告，等你拍板） |
一句话：我是「体检医生 + 处方单」，要动手修，得你点头。
何时使用 / 何时不要使用
| 适合场景 | 不适合场景 |
|---|---|
| 想知道「我的技能里哪些最该管、质量有没有塌方」 | 想让我自动帮你改 / 升级技能（我只出报告 + 处方，动手需你确认） |
| 周期性（周 / 月）生态体检、生成关注列表 | 一次性深度定制开发某个技能（那是 skill-creator 的活） |
发布自建技能前做发布就绪自检（配合 skill-publish-audit） |
非 agent_created 的 marketplace / skillhub 技能要动手修（只出报告） |
输入字段（必填 / 选填）
本技能无强制输入字段，所有 CLI 子命令均可无参数运行（默认纯质量模式）：
| 输入 | 必填? | 默认 | 含义 |
|---|---|---|---|
run.py <子命令> |
必填其一 | — | check / dashboard / repair / upgrade / eco / recommend / health / all |
state/profile.json（画像层） |
选填 | 不存在则纯质量模式 | 角色 / 工作流 / 四级权重，让关注列表收敛到「你真该管的」 |
repair <技能名> 的参数 |
选填 | — | 指定要修复的自建技能；省略则进入待确认队列 |
使用方式
| 自然语言（触发词） | CLI 确定性调用 | 做什么 | 输出 |
|---|---|---|---|
| "skill体检" / "skill检查" | run.py check |
8维体检 + 画像注入 | results.tsv + 终端关注列表(≤5) |
| "配置我的画像" | profile_guide.py --force |
自动扫描用户文件生成画像 | state/profile.json |
| "技能仪表板" | run.py dashboard |
聚合全部报告生成仪表板 | dashboard_blocks.html |
| "修复 XX 技能" | run.py repair <名> |
备份→修复→验证→回滚 | 终端 before/after |
| "有什么可升级的" | run.py upgrade |
升级检查(只读) | upgrade_report.json |
| "生态有什么问题" | run.py eco |
生态分析+链路断点 | eco_report.json |
| "推荐新技能" | run.py recommend |
读 eco gaps → 安装建议 | 终端建议列表 |
| "系统体检" | run.py health |
跨技能深检(5阶段Agent流程) | 生态体检报告 |
| — | run.py all |
月检四步流水线 | 以上全部 |
> 无输入降级：所有命令无需任何参数即可运行。未配置 state/profile.json 时自动退化为「纯质量模式」（中性权重 0.5），照常出分、不报错；配好画像层后关注列表才会加入「业务重要性」这一轴。
统一 Python：优先使用 WorkBuddy 托管 Python（~/.workbuddy/binaries/python/versions/<ver>/python.exe），缺失时回退系统 python
# 标准全量巡检流水线（月检自动化就是这四步，顺序不可乱！）
python scripts/audit_engine.py # 1. 8维体检 + 画像层注入 → results.tsv / audit_latest.json / 趋势
python scripts/eco_optimizer.py # 2. 生态分析 + 链路断点 → eco_report.json（依赖第1步）
python scripts/upgrade_advisor.py # 3. 升级检查 → upgrade_report.json
python scripts/dashboard_blocks.py # 4. 仪表板 → dashboard_blocks.html（依赖第2步的分类覆盖度）
# ⚠ 仪表板依赖 eco_report.json，单独跑前请先跑 eco！
# 推荐直接用: python scripts/run.py all（自动保证顺序 + 仪表板浏览器弹窗）
5 分钟上手
# 1. 第一次体检（无需画像，纯质量模式也能用）
python scripts/run.py check
# 2. (推荐) 配置画像层，让关注列表只报你真该管的
cp state/profile.example.json state/profile.json # 再按自己情况编辑
python scripts/run.py check # 重跑生效
# 3. 打开仪表板（自动浏览器弹窗）
python scripts/run.py dashboard
# 4. (可选) 修复某自建技能
python scripts/run.py repair <技能名>
> 配好画像层后日常就是"说一句话"；没配也只是少了业务优先级维度。完整输出样例见 references/output-samples.md。
七大能力与载体映射
| # | 能力 | 载体 | 模式 |
|---|---|---|---|
| 1 | 8维量化体检（含画像层注入） | scripts/audit_engine.py |
只读 |
| 2 | 自动修复 | scripts/auto_repair.py（5 个 L1 方法） |
写入（备份+回滚+每日上限10） |
| 3 | 升级维护 | scripts/upgrade_advisor.py |
只读（升级命令仅生成不执行） |
| 4 | 生态优化（含链路断点） | scripts/eco_optimizer.py |
只读 |
| 5 | 安装推荐 | eco_report.gaps + find-skills skill |
建议 |
| 6 | 统一仪表板（积木美学·工作流健康度+四象限+关注≤5） | scripts/dashboard_blocks.py（积木美学版，浅色默认+深色切换） |
只读聚合 |
| 7 | 跨技能生态深检 | references/system-health-check.md（5 阶段 Agent 流程） |
只读体检 + 分级修复（P0/P1/P2） |
评分 → 动作映射
| 等级 | 分数 | 动作 |
|---|---|---|
| A/B | ≥75 | L0 仅记录 |
| C | 60-74 | L1 自动修复 frontmatter/触发词（仅 agent_created） |
| D | 40-59 | L2 生成修复方案，等确认 |
| F | <40 | L3 建议重写/废弃，人工决策 |
画像层 → 优先级
| 档位 | 权重 | 含义（来自 profile.json tiers） |
|---|---|---|
| P0 | 1.0 | 关键路径：坏了直接影响当天投资决策 |
| P1 | 0.7 | 高频支撑：每周多次使用的研究/分析能力 |
| P2 | 0.4 | 辅助工具：文档/通信/技能管理等支撑（未列名者默认） |
| P3 | 0.15 | 边缘/娱乐/低频：偶尔一用，质量问题可容忍 |
定期自动化（已激活）
| 任务 | 周期 | 内容 |
|---|---|---|
| SkillOps 每周核心体检 | 每周一 08:00 | audit_engine + 趋势对比 + 关注列表简报（只读） |
| SkillOps 每月全量巡检 | 每月 1 日 08:30 | 四脚本全跑 + 仪表板 + 月度总结（只读） |
自动化任务永不自动修复或升级，只报告。修复/升级由用户在会话中明确触发。
升级护栏（与修复分轨，不可绕过）
详见 state/repair_strategies.json → upgrade_guardrails：禁止自动升级 · 单次会话最多 1 个 · 升级前强制备份 · 安装必须带 --dir · 失败即回滚 · 非自建技能只出报告。完整避坑见 FAQ.md。
与现有积木的协作
| 积木 | 何时调用 |
|---|---|
find-skills / find-skill-skillhub |
能力空白 → 市场检索（优先 skillhub 源） |
skill-creator |
F 级技能建议重写时 |
skill-publish-audit |
自建技能要发布到 skillhub 前 |
| 其他技能管理类技能 | 如本地存在同类管理技能，只读其状态、不依赖；大体积 state 目录已在扫描豁免清单（缺失自动跳过） |
> 注：原伴侣技能 system-health-check 已于 v6.1.0 并入本技能（第 7 能力），流程见 references/system-health-check.md，不再单独发布。
扩展文档指引★
| 文件 | 何时读取 |
|---|---|
state/profile.json |
v7 画像层：用户角色/工作流/四级权重；缺失则退化纯质量模式。个人数据，禁止随发布包上传 skillhub |
state/profile.example.json |
发布版自带的画像层模板（含占位符示例工作流）。需要 v7 画像能力时：cp state/profile.example.json state/profile.json 后按自身角色/工作流/技能清单改写。占位符不会填？先读 references/profile-example-filled.json（已填好的完整参照） |
references/profile-example-filled.json |
画像层填好的完整参照样例（基金投资经理/数学教授/AI Agent 部署者角色），照结构抄、换成你自己的技能名即可 |
references/output-samples.md |
跑完长什么样：终端关注列表 / 仪表板结论条 / 修复 before-after / 升级命令 / 跨技能报告，全部真实样例 |
references/CHANGELOG.md |
历史逐条更新日志（v7.2.0 / v7.3.0 / v7.3.1），从 SKILL.md 外置 |
references/doc-style.md |
文档风格铁律：凡给命令/模板必带真实样例（本技能文档维护约定） |
references/audit-checklist.md |
需要 8 维评分细项定义时 |
references/rule-templates.md |
生成修复方案需要防崩溃模板时 |
references/system-health-check.md |
执行跨技能生态深检（5 阶段流程）时 |
references/skill-checklist.md |
跨技能深检的阶段一需要单技能检查清单时 |
state/repair_strategies.json |
确认某问题类型的修复级别/护栏时 |
state/audit_latest.json |
生态分析、仪表板、回答"哪个技能最差/最该管"时 |
state/audit_history.json |
回答趋势类问题时 |
references/FAQ.md |
遇到问题先查这里：避坑全集（编码/孤儿目录/备份污染/--dir 必带/pycache 禁用/profile 隐私/画像退化/修复上限/升级人工/触发不响应） |
references/dashboard-template.html |
仪表板视觉宪法 (v1.1.0)：积木美学设计体系固化于此。修改此文件即修改全局仪表板外观 |
design-review-blocks.md |
了解积木美学设计体系（色彩铁律/字体三体系/图表五戒/三秒法则） |
已知环境注意事项（Windows）
编码铁律（UTF-8）· 孤儿目录检测 · 备份污染检测 · 大目录豁免 · 禁止 pyc。以上为速查，完整避坑与「怎么办」见 FAQ.md。
失败处理与健壮性
- audit_engine 单技能解析失败：记入
errors数组继续跑，不中断全量；特殊文件（临时锁/权限抖动/超大/>4MB/疑似二进制）经safe_read_text重试 + 识别，打点read_error而非崩溃 - skillhub 查询超时/失败：upgrade_advisor 自动重试最多 3 次（指数退避），仍失败才标注
查询超时，不阻塞报告 - 修复验证失败：auto_repair 自动回滚并转入 L1.5 待确认队列（
issue-pool.json） - 配置文件损坏（profile.json / repair_strategies.json / skill_health.json / audit_latest.json / lock 等）：旧版静默回退或直接裸崩；现统一捕获
json.JSONDecodeError，向 stderr 打印 路径 + 行号 + 原因 + 修复命令（🔧 前缀），降级用兜底值且不崩溃。详见 FAQ Q12 - 无头 / SSH / 定时任务环境：
dashboard无法唤起浏览器时明确提示「无图形界面」并给出 HTML 文件路径，而非含糊报错；可加--no-open关闭。详见 FAQ Q13 - 隐藏 bug 修复：早期版本
execution_count.json因now在定义前被引用、异常被静默吞掉而永不写入，导致画像提醒阶段（第 2–6 次）逻辑从未生效；现已修正，提醒阶段正常触发。
排障与 FAQ（症状速查表）
> 完整 FAQ（现象 → 原因 → 怎么办，Q1~Q15）见 references/FAQ.md。下面只列最高频的几条，方便快速定位。
| 你遇到的现象 | 看哪条 |
|---|---|
| 脚本报编码错误 / 中文乱码 | FAQ Q1 |
技能被装到 C:\c\...（盘符重复 / 孤儿目录） |
FAQ Q2 |
skillhub publish 拒收 *.pyc |
FAQ Q4 |
不确定 profile.json 能不能随包传 |
FAQ Q5 |
| 没配画像层，引擎会不会废 | FAQ Q6 |
| 关注列表里的项为什么没被全修掉 | FAQ Q7 |
| 升级为什么不直接帮我升 | FAQ Q8 |
| 周/月自动化会不会偷偷改技能 | FAQ Q9 |
