hook体检中心（生成即用·健康体检报告）— WorkBuddy Hook 健康体检
技能定义速览
| 项目 | 内容 |
|---|---|
| 技能名称 | hook体检中心（生成即用·健康体检报告）（z-hook-inspector） |
| 一句话描述 | 一键盘点并安全试跑所有 WorkBuddy hook，自动揪出崩溃/失效/误拦等问题 hook，输出可清理清单。 |
| 触发条件 | 用户提到"hook 清单 / 体检 / 健康检查 / 验证 hook / 哪些 hook 有问题 / 清理 hook"等意图时使用。 |
| 执行逻辑说明 | ① 元数据扫描：解析 ~/.workbuddy/settings.json（注册层）+ hooks.config.json（开关层）+ 脚本目录，输出每个 hook 的名称 / 类型 / 触发条件(matcher) / 所属模块 / 路径 / 启用状态 / 关联规则 / 用途，并附带目录树。② 安全试跑：在临时 HOME 沙箱中真实运行每个 hook 脚本（config / 日志 / 状态全部隔离，零真实副作用），验证其可用性与行为正确性；guard 类 hook 使用沙箱版受保护路径验证"真拦"能力。③ 异常标记与汇总：逐 hook 对比"预期退出码/行为"与"实际结果"，自动标记 ORPHAN / CRASH / TIMEOUT / BLOCK_FAIL / FALSE_BLOCK / DEP_MISSING / STDERR 等异常，最终生成 Markdown 体检报告，含问题 hook 清单与修复 / 停用 / 删除建议。 |
这个 skill 干什么
一句话：给你的 WorkBuddy 钩子做一次"全身体检"——
1. 盘点：把 ~/.workbuddy/settings.json（注册层）+ hooks.config.json（开关层）+ 脚本目录全部扫一遍，输出每个 hook 的元数据表与目录树。
2. 试跑：在临时沙箱里安全地真实运行每个 hook（隔离 HOME，零真实副作用），验证它们到底能不能跑、行为对不对。
3. 揪问题：自动对比"预期行为 vs 实际行为"，标记异常 hook 并给出可清理清单。
何时使用
- 用户问"现在系统里有哪些 hook / 钩子"
- 用户想"检查一下 hook 有没有问题 / 哪些 hook 失效了 / 清理无用 hook"
- 用户新增或修改了 hook，想验证真实可用性
- 排障时想快速拿到 hook 的完整元信息
使用步骤（给执行 Agent）
直接运行脚本即可，无需手工拼命令：
# 完整体检（扫描 + 安全试跑 + 报告）
# 先定位本 skill 的脚本（按文件名检索，兼容任意安装路径与中文文件夹名，如 ~/.workbuddy/skills/hook体检中心/）
SCRIPT=$(find ~/.workbuddy/skills -name 'hook_health_check.py' -path '*/scripts/*' 2>/dev/null | head -1)
python3 "$SCRIPT" --out <输出目录>
# 只看元数据，不试跑（更快，适合单纯盘点）
python3 "$SCRIPT" --inspect-only
# 调试时保留沙箱
python3 "$SCRIPT" --keep
运行后：
- 终端会打印元数据清单 + 试跑逐条结果 + 汇总计数。
- 同时生成一份 Markdown 报告 hook体检中心健康体检报告_时间戳.md 到 --out 目录（默认当前目录），用 present_files 呈现给用户。
安全机制（很重要，告诉用户放心）
- HOME 沙箱隔离：每个 hook 都在临时 HOME 下运行，它内部读写的 config / 日志 / 状态文件全部落在沙箱，不会污染你真实的
~/.workbuddy/hooks。 - guard 阻断验证安全：guard 类 hook 的"拦截"只是打印一段 JSON 并退出码置 2，从不修改任何文件；给它喂真实受保护路径（如 MEMORY.md）是安全的真实性验证。
- 不执行任何外部命令：试跑命令固定为脚本自身的
python3调用，绝不把 hook 里的字符串当命令执行。
报告怎么读
- 总览：注册总数 / 已启用数 / ✅正常 / ⚠️降级(缺依赖) / ❌问题。
- 目录结构：
~/.workbuddy/hooks/的真实树。 - 元数据清单：每个 hook 的名称、类型、触发条件(matcher)、所属模块、路径、启用状态、关联规则标识、用途。
- 试跑与异常标记：逐 hook 列出每个测试用例的"退出码/预期/耗时/是否符合预期"，并标注异常类型。
- 问题 hook 清单：❌ 列出异常 hook（含类型、证据、建议处理：修复/停用/删除）；⚠️ 列出降级项（多为缺可选依赖）。
异常类型速查
| 标记 | 含义 | 严重度 | 常见原因 |
|---|---|---|---|
| ORPHAN | 注册了但脚本文件不存在 | ❌高 | settings.json 指向已删除的脚本 |
| CRASH | 试跑异常退出/非零非2 | ❌高 | 脚本语法/导入错误、运行时异常 |
| TIMEOUT | 超过设定超时 | ❌高 | 死循环、外部调用卡住 |
| BLOCK_FAIL | 该拦的没拦住 | ❌高 | guard 逻辑或 path 匹配错误 |
| FALSE_BLOCK | 不该拦的误拦 | ❌高 | guard 误匹配 |
| DEP_MISSING | 可选依赖缺失，功能降级 | ⚠️中 | 未装 python-docx / python-pptx |
| STDERR | 标准错误含异常信息 | ⚠️中 | 脚本内部 warning/未捕获异常 |
术语小课堂（非技术用户也能懂）
- Hook（钩子）：在 WorkBuddy 执行某个动作"之前"或"之后"自动跑的一段小程序，用来检查或拦截。类比：门口的安检仪。
- PreToolUse / PostToolUse：钩子的两种触发时机。
Pre=动作发生前（可以拦下来），Post=动作发生后（只能提醒，拦不住）。类比：Pre 是进门前的安检，Post 是出门后的监控回放。 - matcher（触发条件）：决定"哪些动作会触发这个钩子"。比如
Write|Edit表示只在写/改文件时触发，*表示所有动作都触发。 - 注册层 vs 开关层（双层开关）：脚本先要在
settings.json里"挂上"（注册层），再在hooks.config.json里"打开"（开关层）。两层都开才真正生效。类比：先装上门禁（注册），再通电启用（开关）。 - fail-open（失败开放）：钩子自己出错时一律"放行不拦截"，宁可漏检也不阻断你的正常任务。是安全设计，不是 bug。
- 沙箱（sandbox）：一块临时的隔离空间，试跑 hook 时把它当成"假的家目录"，所有读写都关在里面，不会动到你的真实文件。
- 退出码（exit code）：程序结束时的一个小数字。
0=正常；2=拦截（仅 PreToolUse 有意义）；其它非0=出错。 - 降级（degrade）：某个 hook 依赖的附加工具没装，它就会"跳过"核心检查只空跑——能运行但不干活，需要补装依赖。
备注
- 本 skill 本身不修改任何 hook 配置；它只读和试跑。清理/修复动作由用户在报告指引下手动决定。
--inspect-only模式下完全不涉及执行，适合只想快速看清单的场景。
