技能体检助手

为什么需要

技能文档会随着版本迭代漂移：代码改了、文档没跟上。典型症状是死引用（文档写着某个文件/参数，代码里早已删除）和描述过时（文档声称某个行为，实测已不成立）。这类偏差不会让脚本报错，却会误导后续维护者与调用方。

能力边界（务必先读）

这个技能是「机器扫描 + AI 语义复核」的组合，两者分工不同：

脚本能可靠判定的（低误报，通常就是偏差） —— 由以下检查器产出，可按需启用（模式机制 / 判定口径 / 误报抑制详见 references/checkers.md）：

• doc（常驻默认开）：文档一致性——死引用 DEAD_PATH、失效命令行参数 DEAD_FLAG、退出码不符、枚举/数量/能力声明与代码事实不符、正向能力覆盖 DOC_CAPABILITY_MISSING（代码注册的能力/参数、文档未写）；自由散文语义漂移由 doc-llm 补足。
• structure：结构体检 + 元信息（frontmatter / 标题 / 引用）。
• security：安全红线静态子集（硬编码密钥、路径穿越、危险通配删除等）。
• runtime：脚本可运行性（语法 / 引用缺失）。
• deps：依赖与平台声明（未声明外部 CLI / 运行平台）。
• deadcode（运行前按 --deadcode-mode 选精度，默认 ask）：未使用定义 / 导入、不可达代码、孤立资源文件（v1.34.6 起 ask 默认档不再静默代决：已装 vulture 则自动高精度、未装则交互询问 / 非交互经执行前决策门确认；--deadcode-mode vulture 显式请求时未装会先尝试自动安装、失败回退 ast 并告警）。非交互 agent 环境经「执行前一次性决策门」确认精度（见下方「Agent 非交互运行须知」）。
• portability（零依赖纯静态）：跨平台可移植性——硬编码绝对路径、os.getcwd 依赖、平台专属 shell、解释器锁、编码假设、agent_coupling；按 target_platform / target_agent 豁免。
• doc-llm：自由散文语义漂移检测（由 agent 直接接手、无需外部 LLM）——由 agent 用自身能力比对 SKILL.md 与代码事实；dossier 含「正向覆盖缺口」预分析（与 doc 的 DOC_CAPABILITY_MISSING 共用 compute_capability_gaps，确定性列出代码已注册但文档未写的检查器 / CLI 参数，供 agent 优先核对）；默认 ask，非交互 agent 环境经「执行前一次性决策门」确认精度（agent 模式会写 dossier + 打印 AGENT_TAKEOVER，⚠ 可能产生不可控 token 消耗；off 跳过），须以显式 --doc-llm-mode agent/off 重跑；显式 off 则静默跳过。
• examples（检查器 #9）：文档示例静态校验——校验任意技能文档里写出的命令示例是否站得住脚（脚本引用是否存在 / 传给脚本的参数是否声明 / 示例调用的外部 CLI 是否声明 / 是否含危险或不可逆命令）。默认 ask，非交互 agent 环境经「执行前一次性决策门」确认精度（run 模式在受限沙箱试运行带 expected 标注的示例，⚠ 可能耗时极长且风险不可控；static 纯静态零执行 / 零网络 / 零 token 推荐）；--examples-mode run 方在受限沙箱试运行（仅白名单解释器 + 技能内脚本 + 超时保护，绝不执行任意 shell）。

各检查器的完整项、判定口径与误报抑制细节见 references/checkers.md。

脚本只能枚举差异、不能判定对错的，以及完全查不出、必须 AI 读代码判断的语义项（如描述是否仍成立、提示是否误导、跨文件一致性），详见 references/checkers.md。不要只用脚本结论就下判断——扫描报告是线索，不是裁决。

能力边界速查（一句话）

为减少「多处查阅 checkers.md 才看清边界」，这里把关键边界浓缩成一张表，细节仍以 references/checkers.md 为准：

> 铁律：报告是线索，不是裁决。（新手误区、避坑要点与常见问答见「常见问题与避坑」）

设计原则（核心约束）

> 默认模式零依赖，但绝不替用户决定。

这是本技能的顶层设计原则，所有「可选 / 增强 / 外部依赖」能力（doc-llm 语义检测、deadcode 精度选择）都必须受此约束：

• 默认即零依赖：任何可选能力的默认路径必须是纯脚本、无外部依赖、不联网、零额外成本（token）。开箱即用不应要求用户安装任何东西或配置任何密钥。v1.34.6 起 deadcode 的 vulture 高精度检测已禁用（固定零依赖 AST），不再尝试自动安装 vulture；用户显式 --deadcode-mode vulture 会被降级为 ast 并告警。
• 绝不替用户决定：凡涉及「是否启用增强 / 外部依赖能力」的取舍，必须显式交还用户决策——交互终端呈现可选项（含代价）并等待选择，超时 / 非交互则安全回退默认模式，而绝不为省事自动替用户开启联网或消耗资源（超时 / 非交互回退路径不触发安装）。
• 透明兜底：无法询问（自动化 / Agent / 非 TTY）时，宁可在报告中显著标注「已跳过 / 已降级」（INFO / WARN），也不静默代决。

该原则已在 doc-llm / examples / deadcode（三者默认均 ask）与「执行前一次性决策门」（非交互 agent 环境在执行前一次性征询三者精度决策，含 token 消耗 / 耗时与风险警告，显式 --X-mode 始终优先）中落地。

Agent 非交互运行须知（决策必须回交用户，禁止静默代决；执行前一次性决策门）

本技能被 Agent 经子进程调用时，stdin 不是 TTY，交互菜单无法弹出。为此采用「执行前一次性决策门」确保「绝不替用户决定」且「不静默落空」：

• 执行前一次性决策门（取代逐检查器硬失败）：进入检查器前，若处于非交互环境（stdout/stderr 任一非 TTY）且 doc-llm / examples / deadcode 任一仍为默认 ask，脚本在执行前一次性打印合并决策请求（人类可读提示 + 机读 JSON PRE_RUN_DECISION_JSON 哨兵行），退出码 130 交 Agent 显式重跑；请求中已带风险警告——doc-llm agent 模式「⚠ 可能产生不可控 token 消耗」、examples run 模式「⚠ 可能耗时极长且风险不可控」、deadcode（vulture 可装时提供高精度档，屏蔽/未安装时仅 ast/off）。主 Agent 读取该决策请求即必须调用提问工具（如 AskUserQuestion）向用户一次性确认三者精度档位，再以显式 --doc-llm-mode / --examples-mode / --deadcode-mode 重跑——一次决策后不再逐个询问。契约即权威，不依赖本散文是否被读。
• CI 环境自动安全档位：若检测到 CI 环境变量（CI=true / GITHUB_ACTIONS / CONTINUOUS_INTEGRATION=true），无真人 / Agent 代理时自动选安全档位（doc-llm=off / examples=static / deadcode=ast）并继续，避免挂死；如需其他档位仍须显式 --X-mode。
• 显式 --X-mode 始终优先：只要显式指定 --doc-llm-mode / --examples-mode / --deadcode-mode（含显式 ask），决策门不触发，按指定档位运行。交互终端（真人）仍照常逐检查器弹菜单。

1. 运行前无需自行探测 vulture：v1.34.6 起 deadcode 的 vulture 高精度检测已禁用（固定零依赖 AST），agent 不要自己跑 python -c "import vulture" 去探测；直接以默认 ask 运行即可，脚本经决策门确认精度。doc-llm / examples 仍按各自约定运行前经决策门确认（其取舍不涉及 vulture 安装）：
   - deadcode 精度：默认 ask（经决策门确认），如需锁定可显式 --deadcode-mode vulture/ast/off；
   - doc-llm 模式：agent（由你接手语义比对）/ off（跳过）；
   - examples 模式：run（沙箱试运行，须 --examples-consent）/ static（纯静态）/ off（跳过）。
2. 运行后必查回交（反参告知 + 契约弹窗）：deadcode 会在 stderr 与 JSON checker_runs（deadcode 条目的 mode 字段）回参实际采用的精度（ast / off），agent 必须将该模式明确告知用户（如「deadcode 以 ast 零依赖模式运行」）。若报告出现「⚠ 需用户决策」块或 stderr 的 PRE_RUN_DECISION_JSON 哨兵（或 --json 顶层 prerun_decision）非空，必须调用提问工具向用户一次性确认三者精度取舍，再以显式 --X-mode 重跑。绝不允许静默代决、把决策点悄悄吞掉。 非交互环境未获显式授权时，执行前一次性决策门已以 prerun_decision（退出码 130）挂起，须显式指定 --X-mode 重跑。
3. 代码层兜底：deadcode 默认 ask——已装 vulture 则自动高精度、未装则经执行前一次性决策门确认（prerun_decision，退出码 130）；vulture 可装时决策门提供高精度档，屏蔽/未安装时仅 ast/off，不静默代决、绝不强行联网安装。

> 跨平台、跨 Agent 适配，不写死宿主假设。

本技能不假设自己只跑在 WorkBuddy 上、只装在某个固定用户名 / 盘符的目录。该原则统领路径解析与跨 Agent 分发：

• 路径零宿主硬编码：一律经 os.path.expanduser("~") / 环境变量解析，禁止写死随账号或盘符变化的用户主目录绝对路径（例如 Windows 用户目录下「用户名」起手的写法）；换机器 / 换用户名 / 自定义数据目录都不应破。
• 用户侧审计本就 agent 无关：--skill <目录> 收任意路径、--all 扫宿主 skills 根、--source 支持 github / skillhub / url；跨 Agent 分发以 target_agent 字段声明，portability 据此豁免耦合项（agent_coupling）。

快速开始

三条命令覆盖 90% 场景：

# 1) 体检一个技能（doc 一致性常驻默认开，审计前自动备份 SKILL.md）
python scripts/audit_docs.py --skill ~/.workbuddy/skills/<技能名> --backup

# 2) 全套体检（结构/安全/可运行/依赖/死代码；deadcode 默认 ask：脚本检测 vulture，已装自动高精度并回参告知，未装询问精度模式）
python scripts/audit_docs.py --skill <目录> --all-checks

# 3) 先预览再审计（看清楚会扫哪些检查器、哪些文件，退出码 0）
python scripts/audit_docs.py --skill <目录> --all-checks --preview
# examples 示例执行验证：默认 ask（非交互降级纯静态）；agent 非交互显式 --examples-mode 须附 --examples-consent 授权令牌（否则阻断并报告 examples_consent_missing）

想做某件事，直接用对应命令要点：

其余参数（--json / --timeout / --max-file-size / --deadcode-mode / --backup-limit / --source / --ref / --keep-temp）与完整检查项口径见下方「用法」与 references/checkers.md。

5 分钟上手（极简路径）

只想最快跑起来，只需记住一条命令：

python scripts/audit_docs.py --skill <技能目录> --all-checks

它会自动备份 SKILL.md、跑完全部检查器、输出带中文标签的报告。deadcode 默认 ask 由脚本静态检测 vulture：已装则自动用高精度模式并回参告知实际精度（不需要额外安装任何东西就能跑），没装则询问精度模式（非交互环境挂载决策请求交 agent 弹窗）。其余 90% 场景用「快速开始」那张表查对应命令要点即可，无需通读全文。注意：Agent 经管道执行时若 vulture 缺失不会真正询问用户，会挂载精度决策请求并交你弹窗确认或显式 --deadcode-mode 指定，勿依赖静默降级。

> 三个最常见疑问（要装 vulture 吗 / 远程审计要装 git 吗 / WARN 要不要全改）见「常见问题与避坑」·速答三问。

多平台来源（--source github / skillhub / url）

默认 --source local：用 --skill <目录> 或 --all（扫 ~/.workbuddy/skills）审计本机技能。
新增 --source 可把远程仓库 / 集市技能拉到临时目录后照常审计，analyze_skill 核心逻辑零改动。

> 本地审计完全离线、零外部依赖：--source local（默认）与 --all 只读写本机目录，不联网、不需要任何外部 CLI 或令牌。仅 --source github（需 git）、--source skillhub（需 skillhub CLI）才要求对应命令在 PATH 中；而 --source url 用标准库 urllib 直抓，同样零外部 CLI（仅需 HTTPS 网络可达、对目标 OS 透明）。切勿因「远程审计」条目误以为本工具整体依赖联网——本地体检是纯离线脚本。

> 审计远端技能优先用 --source url（零外部 CLI、绕开 git clone 不通的网络限制；常见误区见「常见问题与避坑」·新手误区）。

审计结束后临时目录默认自动清理；加 --keep-temp 可保留并打印路径，便于排查。

流程

1. 备份并扫描
   sh python scripts/audit_docs.py --skill ~/.workbuddy/skills/<技能名> --backup
   脚本会在审计前把 SKILL.md 备份为 SKILL.md.bak.<时间戳>。为防频繁迭代产生过多备份，同一 SKILL.md 的 .bak.* 文件最多保留 3 个——生成新备份前会先删除最旧者。可用 --backup-limit N 调整上限（如 --backup-limit 5）。

2. AI 复核：阅读报告后，针对每一条核对源码。重点甄别三类：
   - A 类里是否有「有意为之」的条目（例如文档标注「已弃用」的退出码，属正常）
   - B 类里哪些其实是用户可感知行为、应当补写
   - 脚本查不出的语义项：把文档逐段与代码行为对照，确认描述仍然成立

3. 直接修改：本技能按「全自动改 + 备份」模式运行——判断清楚后直接编辑 SKILL.md，无需停下来等待确认。

4. 汇总：列出改了什么、依据是什么，并告知备份位置与回滚方法。

修改原则

• 修改文档时的五条避坑原则（只改文档不改代码、保留「已弃用」标注、存疑标注、先读源码复核、语义化递增版本号）已归集到「常见问题与避坑」·避坑要点。

用法

# doc 一致性（常驻默认）
python scripts/audit_docs.py --skill ~/.workbuddy/skills/workbuddy-checkin --backup

# 启用插件式检查器（doc 常驻 + 指定项，可重复 --check）
python scripts/audit_docs.py --skill <目录> --check structure --check security

# 全部检查器（doc + structure + security + runtime + deps + deadcode；deadcode 默认 ask：脚本检测 vulture，已装自动高精度并回参告知，未装询问精度模式）
python scripts/audit_docs.py --skill <目录> --all-checks

# 仅依赖/平台声明检查
python scripts/audit_docs.py --skill <目录> --check deps

# 备份上限可调；批量审计；JSON 机读（同时仍打印可读报告）
python scripts/audit_docs.py --skill <目录> --backup --backup-limit 5
python scripts/audit_docs.py --all --all-checks
python scripts/audit_docs.py --skill <目录> --all-checks --json
# CI 门禁：WARN 也计入退出码（默认仅 ERROR 计入）
python scripts/audit_docs.py --skill <目录> --all-checks --strict
# 整体超时保护（秒）；超时优雅终止，不再卡死
python scripts/audit_docs.py --skill <目录> --all-checks --timeout 60
# 超大文件跳过阈值（字节）；超过则跳过并报告，避免拖慢
python scripts/audit_docs.py --skill <目录> --all-checks --max-file-size 2000000
# deadcode 精度模式：ask(默认，脚本静态检测 vulture；已装则自动高精度并回参告知，未装交还用户决策) / 显式 vulture 高精度 / ast 零依赖 / off 不运行；Agent/CI 可用显式 --deadcode-mode 锁定精度，否则默认 ask 由脚本检测并回参告知
python scripts/audit_docs.py --skill <目录> --all-checks   # deadcode 默认 ask：脚本检测 vulture，已装用高精度并回参告知，未装交还决策
python scripts/audit_docs.py --skill <目录> --all-checks --deadcode-mode vulture   # 或显式锁定高精度
# 先预览将运行哪些检查器、将扫描哪些文件（不产出发现，退出码 0）
python scripts/audit_docs.py --skill <目录> --all-checks --preview
# examples 示例执行验证：默认 ask（非交互降级纯静态）；agent 非交互显式 --examples-mode 须附 --examples-consent 授权令牌（否则阻断并报告 examples_consent_missing）

# 多平台来源：克隆 GitHub 仓库并审计（可 @分支；仓库内 SKILL.md 在 src/ 也能自动定位）
python scripts/audit_docs.py --source github --ref owner/repo --all-checks
python scripts/audit_docs.py --source github --ref https://github.com/owner/repo @dev --check structure
# 多平台来源：经 skillhub CLI 拉取集市技能并审计
python scripts/audit_docs.py --source skillhub --ref <slug> --all-checks
# 保留克隆/安装的临时目录供排查
python scripts/audit_docs.py --source github --ref owner/repo --keep-temp
# 泛化源：直接审计任意 URL 上的 SKILL.md（零外部依赖，github blob 链接自动转 raw）
python scripts/audit_docs.py --source url --ref https://raw.githubusercontent.com/owner/repo/main/SKILL.md --all-checks
python scripts/audit_docs.py --source url --ref https://github.com/owner/repo/blob/main/SKILL.md

退出码：0 未发现 ERROR 级问题（--strict 下还需无 WARN）；1 发现 ERROR 级问题（或 --strict 下存在 WARN）；2 参数或路径错误；130 审计被中断（超时或 Ctrl+C），优雅退出、不抛堆栈。报告同时提供人类可读分组与 --json 机读（每条含 checker/severity/category/category_cn/message/file/line/suggestion）；category 为稳定机器标识符（用于机读与跨版本比对），category_cn 为中文可读标签（用于人类报告，使每条发现自解释）。

回滚

cp SKILL.md.bak.<时间戳> SKILL.md

触发与实测

本技能在以下真实对话口吻下应被准确触发（正例），以及在相似但不同诉求下不应触发（near-miss 反例）。

正例（应触发）
- 「帮我体检一下这个技能的文档，看看版本迭代后有没有漂移」→ 触发 doc 一致性检查。
- 「审计一下这个技能的安全红线，有没有硬编码密钥或路径穿越」→ 触发 security 检查器（含上下文感知的 path_traversal，自动排除 https://.../v2 这类文档 URL 与合法资源上溯，不再误报）。
- 「我想批量检查一下所有已安装技能的依赖和平台声明」→ 触发 --all --all-checks（含 deps）。

Near-miss 反例（不应触发）
- 「帮我优化这段代码的性能」→ 属通用编码任务，非文档/静态体检，本技能不介入。
- 「把这个技能打包成 Docker 镜像」→ 属部署范畴，超出静态体检边界，不触发。

> 触发判据：用户意图围绕「文档与代码一致性 / 结构 / 安全红线 / 可运行性 / 依赖平台」的静态审计时使用；纯运行期、动态行为或部署类诉求不在范围内。

误报自纠错能力：security 检查器对所有正则统一采用上下文感知过滤，自动排除注释、文档 URL、自引用资源上溯，避免上下文盲误报；该能力同样覆盖 structure/portability——hardcoded_path 已跳过表格/引用块/示例性描述行，encoding_sep 已排除 urlopen/io.open 等非文件 open（如 --source url 的 urllib.request.urlopen 不再误报），hardcoded_endpoint 已对 raw.githubusercontent.com 等 url 源规范主机白名单放行。完整机制见 references/checkers.md。

examples 检查器：文档示例静态校验（检查器 #9）

校验任意技能文档里写出的命令示例是否站得住脚——避免「文档教用户的命令一跑就挂」这类漂移。默认 ask（交互询问是否允许沙箱试运行；非交互 / 超时回退 static），实际执行属需显式授权的可选能力；纯静态检查（零执行 / 零网络 / 零 token）仍是日常与 CI 的落地姿态。

• 多档模式（--examples-mode）：ask（默认，交互询问是否允许沙箱试运行，30 秒超时或本地非交互一律回退 static 并发 INFO finding examples_degraded）/ static（纯静态解析）/ run（受限沙箱试运行）/ off（跳过）。
• agent 决策回交（ask 非交互）：ask 降级为静态并发 examples_degraded INFO，决策载荷进 JSON user_prompts 并在报告印「⚠ 需用户决策」块；agent 须据此向用户确认后以 --examples-mode run/static 重跑。非交互环境若显式指定 --examples-mode run/static/off 须携带 --examples-consent 授权令牌，否则脚本阻断并报 examples_consent_missing（ERROR）——该强制由代码闸门执行，不依赖文档约定。
• 默认静态档查什么：① 示例命令引用的脚本文件是否存在（EXAMPLE_TARGET_MISSING，仅核验 .py/.js/.mjs/.ts/.sh/.ps1 这类脚本扩展名，仓库引用 / 安装路径 / 输出文件一律跳过，避免误报）；② 传给脚本的参数是否在脚本中声明（EXAMPLE_FLAG_UNKNOWN WARN，仅 SKILL.md）；③ 示例调用的外部 CLI 是否在文档声明依赖（EXAMPLE_EXT_CMD INFO）；④ 是否含危险 / 不可逆命令（EXAMPLE_DANGEROUS ERROR/WARN）。纯文档快照（未取到代码）时退为 INFO，绝不把「没下载到」误判成「文件不存在」。
• 安全红线（不可放宽）：即便 run 模式也绝不执行文档里的任意 shell。只执行同时满足全部条件的命令：白名单解释器（python/python3/node）+ 无 shell 元字符（; | & < > $ \ ( )` 等）+ 目标脚本在技能目录内 + 扩展名白名单 + 该示例块由作者显式标注了期望 + 受超时与条数上限约束。不满足即跳过并 INFO 说明，绝不「尽力执行」。
• 示例标注语法（作者可选，供 run 模式比对）：为示例围栏加标注 {example expected-exit=0 expected-stdout="OK"} 后，run 模式会执行并比对期望（仅白名单解释器 + 技能内脚本 + 超时保护）；未标注的示例任何模式都只做静态检查、不执行。

python scripts/audit_docs.py --check doc --skill <技能目录>

支持 expected-exit / expected-stdout / expected-stderr。未标注的示例任何模式都只做静态检查、不执行。

> 与 self_validate.py 的区别：本检查器是审计目标技能的插件式检查器（进 CHECKERS 与 --all-checks）；self_validate.py 是维护者自校工具，只校验本技能自身。两者不同类。

常见问题与避坑

本节导航（速查锚点）

• 速答三问：要装 vulture 吗 / 远程审计要装 git 吗 / WARN 要不要全改
• 新手误区：把线索当裁决 · 远程必用 github · 报漏洞就是真漏洞 · 已弃用即错 · 没装 vulture 用不了
• 避坑要点：DEAD_PATH 是运行产物 · WARN/INFO 非错误 · 改文档五原则 · 缩小审计范围 · 默认零依赖 · doc-llm 语义检测

> 铁律：报告是线索，不是裁决。 任何改动前先读源码核对，尤其 WARN/INFO 与语义项。脚本只枚举差异、不判定对错；语义项（描述是否仍成立、提示是否误导、跨文件一致性）必须 AI 读代码判断。

速答三问（30 秒）

• 要装 vulture 吗？ 不用手动装。默认 ask 由脚本静态检测：环境已装 vulture 则直接高精度（回参告知，不触发安装）；仅显式 --deadcode-mode vulture（或交互选 vulture）但环境缺库时，脚本才先自动 pip install vulture（装好即用高精度），装不上降级 ast 并标注精度降级。其它情形（ast/off、ask 非交互且缺库回退）不触发安装，缺库即零依赖 ast，其它检查器完全不受影响。
• 审计远程技能要装 git / skillhub 吗？ 不用。用 --source url --ref <SKILL.md 的 https 地址> 即可，标准库直抓、零外部 CLI。
• 报告里一堆 WARN/INFO 要不要全改？ 不要。只有 ERROR 默认计入退出码；WARN/INFO 是线索，需你/AI 读源码复核后再决定。

新手误区

• 误区一：把线索当裁决。 只有 ERROR 默认计入退出码；WARN/INFO 是「这里可能有问题，请你/AI 读源码确认」的提示。例如 agent_coupling 的 INFO 是跨 Agent 咨询、非缺陷；hardcoded_path 的 WARN 若出现在表格/引用块里多半是示例误报（已做上下文感知过滤）。先读源码，再决定改不改。
• 误区二：以为远程审计必须 --source github。 其实优先用 --source url --ref <SKILL.md 的 https 地址> 即可——标准库直抓、零外部 CLI、绕开 git clone，绝大多数远端技能都能审计。仅在需要完整克隆仓库（含嵌套子目录/多技能）时才用 --source github / --source skillhub。
• 误区三：报了路径穿越 / 硬编码密钥就是真漏洞。 多半是上下文盲误报。security 检查器对所有正则统一做上下文感知过滤，自动排除注释行、含 :// 的文档 URL、含 __file__/dirname/.asar 的合法资源上溯；真实漏洞（外部可控字符串拼入落盘路径、文档里真写死密钥）才会保留。
• 误区四：文档列了退出码但代码从不返回，就是文档错了。 未必。若标注「已弃用」，那是刻意的向后兼容说明，保留不要删。
• 误区五：没装 vulture 就跑不了死代码检测 / 整工具用不了。 不是。没装时 deadcode 仍可用：ask 默认路径下非交互环境由「执行前一次性决策门」（退出码 130）接管确认精度、交互环境提示 ast/off 供选择，绝不以「硬失败挂起」或「静默代决」糊弄；仅显式 --deadcode-mode vulture 路径才尝试自动安装（失败回退 ast 并告警）。装不上或显式选 ast/off 以零依赖 ast 运行（仅死代码精度略低），其余检查器完全不受影响。

避坑要点

• DEAD_PATH 但路径确实在用？ 很可能指向「运行期生成的产物」（如技能在目标项目创建 .learnings/、脚本在临时目录生成 state），本技能目录下不存在却非漂移。判定前留意引用处是否含「生成 / 创建 / 写入」含义。详见 references/checkers.md 的「判定提示」。
• WARN/INFO 不是错误：structure 的 name_mismatch 是提示性项，portability 的 agent_coupling INFO 是跨 Agent 咨询、非 OS 级破损，均属正常产物，勿直接当错误处置。
• 修改文档的五条原则：① 只改文档，不改代码（代码问题整理出来交用户决策）；② 保留「已弃用」标注（不因「代码从不返回」就删）；③ 存疑时标注「待确认」而非臆断；④ 先读源码复核再决定；⑤ 版本号按语义化递增（修正文档表述属补丁级，修复功能缺陷属小版本级）。
• 缩小审计范围：用 --check 按需启用（如 --check security），或 --all-checks 全开；--strict 让 WARN 也计入退出码，适合 CI 门禁。
• 设计原则：默认零依赖，绝不替用户决定：本技能所有可选 / 增强能力默认纯脚本、不联网、零 token；涉及是否启用外部依赖能力的取舍必须显式交还用户（菜单含代价、超时回退默认），自动化环境宁可显著标注跳过也不静默代决。这条原则统领 doc-llm 与 deadcode。
• doc-llm 已纳入全量集，语义检测由 agent 直接接手（会占用 agent 推理 token，但不向外部 LLM 付费）：--all-checks 会跑 doc-llm 并显式问询是否启用语义检测（全量检测理应包含语义漂移问询）。默认按 ask：交互终端弹菜单、30 秒超时默认不启用；非交互环境无法询问则跳过并记 INFO doc_llm_skipped。不依赖任何外部 LLM 端点——选「agent 接手」时脚本把 SKILL.md 全文 + 代码事实清单写成 dossier 并打印 [doc-llm] AGENT_TAKEOVER: <path> 哨兵，由 agent 读取后用自身能力完成语义比对；此过程会占用 agent 自身推理 token（输入侧为主、输出极少），但不向任何外部 LLM 服务付费。完全不想参加可显式 --doc-llm-mode off。调用流程刻意对齐 deadcode 检查器（--doc-llm-mode 与 --deadcode-mode 同构）。

完整运行示例（真实输出 + 解读）

对某个技能目录运行全套体检时（下方输出取自对本技能自身的审计；当审计目标目录名与技能名不一致时，会额外出现 1 个 name_mismatch WARN，审计正常部署的技能则无此项）：

python scripts/audit_docs.py --skill src --all-checks

输出节选（示意，每条发现均带中文标签与机器码，自解释；各检查器计数随版本演进会有差异，以实际运行为准）：

  [doc]       ERROR 0 / WARN 0 / INFO 1
  [structure] ERROR 0 / WARN 1 / INFO 0
  [security] ERROR 0 / WARN 0 / INFO 0
  [runtime]   ERROR 0 / WARN 0 / INFO 1
  [deps]      ERROR 0 / WARN 0 / INFO 0
  [deadcode]  ERROR 0 / WARN 0 / INFO 0
  [portability] ERROR 0 / WARN 0 / INFO 18

  本技能汇总：ERROR 0 / WARN 1 / INFO 20    通过

如何解读（关键）
- 通过 = 未发现 ERROR 级问题，退出码 0。只有 ERROR 默认计入退出码；--strict 才把 WARN 也算失败。
- WARN/INFO 是否要处理、portability 的 agent_coupling INFO 为何可忽略，见「常见问题与避坑」·避坑要点。
- 每条发现的机器码（category）稳定、可用于跨版本比对；--json 输出供 CI 消费（每条含 checker/severity/category/category_cn/message/file/line/suggestion）。

> 练习：把上面这条命令对你的一个技能跑一遍，对照「能力边界速查」表判断每条 WARN/INFO 是否真要处理。绝大多数技能首跑都会有几个 INFO，属正常。

错误码对照表

每条发现都带一个机器标识符 category（稳定、用于机读与跨版本比对）与一个中文标签 category_cn（用于人类报告）。下表为全部 category 的权威对照；各检查项完整判定口径与误报抑制机制见 references/checkers.md。

doc（文档一致性，常驻默认开）

> 结构化声明 ↔ 代码事实交叉校验（DOC_ENUM_DRIFT / DOC_COUNT_DRIFT / DOC_CAPABILITY_DRIFT / DOC_CAPABILITY_MISSING，均 WARN 仅作线索）；自由散文语义漂移由独立的 doc-llm 检查器覆盖（由 agent 直接接手、不再调外部 LLM）。完整机制见 references/checkers.md。

structure（结构体检 + 元信息）

security（安全红线静态子集）

runtime（脚本可运行性）

deps（依赖与平台声明）

> 何时显式声明 target_platform（deps 指引）：deps 仅发 platform_undeclared INFO（非阻断），但正确声明可消除误报、提升 portability 审计精度。判定：① 技能只能在某一 OS 上运行（依赖 winreg/ctypes.windll 等 Windows 专属 API）→ 显式 target_platform: windows（linux/macos 同理）；② 调用平台专属 shell/命令是设计内行为 → 同样声明豁免该项；③ 跨平台通用（目标 = 全平台）→ 不写 target_platform（默认即跨平台全检），切勿为消 WARN 而谎报平台。声明后 portability 仅抑制与 breaks_on 无交集的 OS 项（详见下方「豁免规则」），不会掩盖真实跨平台破损。

deadcode（死代码检测，运行前按 --deadcode-mode 选精度）

> 死代码误报抑制（详见 references/checkers.md）：字符串键/装饰器/入口启发、跨文件引用感知、# keep 白名单；orphan_asset 仅当文件名或相对路径未出现在任何文档/代码、也未被其他 .py 以模块名 import 时才报（只可能漏报、不会误标孤儿）。

portability（跨平台可移植性，按 target_platform 豁免）

> portability 先由 detect_format() 推断技能格式并构建统一 SkillModel，再按 target_platform / target_agent 豁免；跨格式矩阵 / 转译机制见 references/checkers.md。

> --report portability-matrix 生成「源格式 → 各目标格式」的 P/D/L 矩阵；跨格式转译（--report translate）与 agentskills 枢纽机制见 references/checkers.md。

> --report translate（只读预览·不落盘）做跨格式转译方案；agentskills 为全生态通用枢纽（一次转译即被 40+ 工具消费）。完整机制见 references/checkers.md。

> 豁免规则（核心）：每条发现的 breaks_on 是「它会在哪些 OS 上崩」。声明平台与 breaks_on 有交集才报，无交集才抑制。例：target_platform: windows 会抑制 powershell/C:\ 这类 Windows 专属项的误报，但保留 rm -rf//Users/ 这种在 Windows 目标上真会崩的项。target_platform 不写 = 跨平台（全平台）→ 始终全检。agent_coupling（Agent 平台耦合）为 INFO/WARN 咨询项，受 target_agent 字段门控：声明跨 Agent 目标（不含 workbuddy，如 claude-code/cross-agent）但仍含 WorkBuddy 耦合时升为 WARN（跨 Agent 会失效）；其余（未声明 / 声明含 workbuddy / 推断 workbuddy）均按 INFO 提示——不再因 workbuddy 而抑制，因本 skill 自身亦开发跨 Agent 能力，耦合提示对所有技能均有价值。开放标准技能的 compatibility 字段视作 target_agent。

跨平台可移植性证明（本技能自身）

本技能自身满足跨平台可部署要求，以下为实测证据（非声明、可复现）：

• 纯 Python 标准库实现，零第三方依赖：scripts/audit_docs.py 仅依赖 argparse / re / os / json / zipfile / subprocess / threading 等标准库，无需 pip install；deadcode 高精度模式的可选依赖 vulture 缺省时自动降级为零依赖 ast，非运行必需。
• 无平台专属 API 的实际调用：代码中出现的 win32api / ctypes.windll / winreg / HKEY_ / ShellExecute / os.startfile / powershell / cmd.exe / os.getcwd / shell=True 等字样，仅作为检查器自身的检测规则（用于发现其他技能的这些反模式），本技能自身从未调用；所有实际调用的外部 CLI（git / pip / skillhub 等）均以列表传参方式调用，未使用 shell=True。
• portability 自检零 OS 级发现：在本技能源码（SKILL.md 未声明 target_platform，即「跨平台 = 全平台全检」）上运行 --check portability，结果为 ERROR 0 / WARN 0；所有 INFO 均为 agent_coupling（跨 Agent 咨询，提示 .workbuddy / allowed-tools 耦合，非 OS 级破损）——无硬编码绝对路径、无启动目录依赖、无平台专属 shell、无解释器锁、无编码假设。
• 结论：可在 Windows / Linux / macOS 上无修改运行。仅当接入 --source github（git clone）或 --source skillhub（skillhub CLI）时才需对应外部 CLI 存在于 PATH；--source url 使用标准库 urllib，无需任何外部 CLI，且 HTTPS 依赖对目标 OS 透明。

进阶用法示例

基础用法之外，以下场景覆盖更复杂的实际诉求：

1. CI 质量门禁（任何小瑕疵都阻断合并）

# --strict 让 WARN 也计入退出码；--json 便于接入看板
python scripts/audit_docs.py --skill . --all-checks --strict --json > audit.json
echo "exit=$?"   # 0=体检通过，1=发现问题（含 WARN）

解读：--strict 适合发布前的强约束；把 audit.json 喂给后续步骤可做「文档质量趋势」看板，每次提交对比 ERROR/WARN 数量。

2. 超大单体仓库扫描调优（避免卡死/拖慢）

# 调高超大文件跳过阈值、设总超时上限
python scripts/audit_docs.py --skill ./huge-monorepo --all-checks --max-file-size 5000000 --timeout 120
# 只查安全红线 + 依赖声明，省时
python scripts/audit_docs.py --skill ./huge-monorepo --check security --check deps

解读：单仓库文件极多时，优先用 --check 指定检查器，配合 --max-file-size/--timeout 把审计控制在可接受时长内，超大文件会自动跳过并报告、不拖慢整体。

3. 一次体检多个已安装技能

python scripts/audit_docs.py --all --all-checks

解读：--all 遍历 ~/.workbuddy/skills/ 下全部技能，批量产出各自报告，适合周期性「存量技能大扫除」。