Skill 助手

搜索 · 推荐 · 安装 · 创建 · 检查 · 诊断 — 全生命周期一站式管理。

┌─────────┐     ┌──────────────┐     ┌──────────────────────┐
│ 用户意图 │ ──→ │ ⛔ 前置检查   │ ──→ │ 意图路由（6 模块）    │
└─────────┘     │ 1. 首次引导   │     │                      │
                │ 2. 更新检查   │     │ 搜索 → modules/search │
                └──────────────┘     │ 推荐 → modules/recommend│
                                     │ 安装 → modules/install │
       ┌─ config/sources.yaml        │ 创建 → modules/create  │
       │   (偏好 + 凭证)             │ 质检 → modules/inspect │
       │                             │ 诊断 → modules/diagnose│
       ├─ references/ (按需加载)     └──────────────────────┘
       └─ scripts/   (CPU 密集)

典型交互

用户：帮我找一个生成 PPT 的 skill → 前置检查通过 → 四级关键词生成 → 5 渠道宽窄双路并行搜索 → 去重归一化 → 展示 Top 5（按来源分区 + 推荐指数）→ 编号菜单（安装/详情/收藏/重搜）→ 用户选择安装 → 三引擎安全扫描 → 完成

用户：推荐适合我的 skill → 扫描已安装 Skill + README + 项目特征 → 用户画像 → 识别能力缺口 → 个性化推荐 2-5 条（标注互补关系）

不在范围内

非 Agent Skill 的通用包管理（npm / pip / brew 等）
IDE 插件/扩展的搜索与安装
已安装 Skill 的代码级修改（诊断模块只交付建议和重构后的文件，不自动覆盖原文件）

⛔ 前置检查（任何操作前必须执行，不可跳过）

读取本 Skill 后，在执行任何用户意图之前，严格按以下顺序完成前置检查。 跳过任何步骤 = 流程错误。无论用户意图多么明确、多么具体，都必须先通过全部前置检查。

⚠️ 跳过前置检查是最常见的执行错误。直接搜索/安装将因缺少 API Token、未选择搜索源等问题导致失败，浪费用户时间。

步骤 1：首次使用拦截

立即读取 config/sources.yaml 的 preferences.setup_completed 字段：

false 或不存在 → 停止。不执行任何后续操作。 转入 modules/setup.md 完成 4 步引导，完成后回到步骤 2
true → 继续步骤 2

步骤 2：自身更新检查

检查 config/sources.yaml 中 preferences.self_update：

判断是否需要检查：

enabled: false 或 check_frequency: never → 跳过，直接路由
enabled: true → 根据 check_frequency 和 last_check_date 判断：
- last_check_date 为空字符串 "" 或字段缺失 → 视为首次检查，强制执行（适用于全新安装或重置）
- daily：last_check_date 不是今天（YYYY-MM-DD 字符串比较）→ 执行检查
- weekly：last_check_date 距今 ≥ 7 天 → 执行检查
- 已检查过且未到期 → 跳过，直接路由

检查流程（非阻塞，完成后继续执行用户原始意图）：

获取最新版本信息（逐级降级，上一级失败才尝试下一级）：
- 第 1 级：使用 iWiki MCP（如已配置）或 WebFetch 访问更新日志 iwiki（preferences.self_update.changelog_url），提取最新版本号和更新内容
- 第 2 级（iwiki 获取失败：MCP 未配置 / 地址变更 / 网络问题）：使用 WebFetch 访问 Knot 详情页（preferences.self_update.knot_url），从页面提取版本和更新说明
- 第 3 级（Knot 页面也失败）：通过 Knot API 搜索并匹配 id=15780（⚠️ 必须用 POST + JSON body）：
```
curl -sk "https://knot.woa.com/apigw/openapi/v1/skills/get" \
  -X POST -H "Content-Type: application/json" \
  -H "x-knot-api-token: ${KNOT_API_TOKEN}" \
  -d '{"keyword":"skill-assistant","category":"","page_num":1,"page_size":5,"order_by":"download_count"}'
```
与当前版本（本文件 frontmatter version）对比
更新 last_check_date 为今天日期（YYYY-MM-DD）
有新版本时，在执行用户原始意图之前，向用户展示：

📢 Skill Assistant 有新版本可用！

  当前版本：v{current_version}
  最新版本：v{latest_version}（{update_date} 更新）
  更新内容：{changelog_summary}

  Knot 地址：https://knot.woa.com/skills/detail/15780

  → [1] 立即更新（从 Knot 重新安装最新版）
    [2] 稍后再说（继续使用当前版本）
    [3] 修改检查频率（当前：{check_frequency}）
    [4] 关闭更新检查

  当前更新检查配置：✅ 已开启 | 频率：每{frequency_display} | 上次检查：{last_check_date}

无新版本时静默继续；选 [1] 通过 knot-cli 覆盖安装；选 [3] 修改 check_frequency（daily/weekly/never）；选 [4] 将 enabled 置 false。无论选什么，完成后继续执行原始意图。

降级策略：

iwiki 不可用（MCP 未配置 / 地址变更 / 网络问题）→ 降级到 Knot API
全部失败 → 静默跳过，不影响正常功能
连续 3 次检查全部失败 → 自动暂停检查，下次用户主动触发时恢复

步骤 3：意图路由

根据用户输入分流到对应模块，严禁跳模块混合执行。

| 用户意图 | 路由模块 | 参考文件 | |---------|---------|---------| | "搜一个 xxx skill" / "find skill for xxx" | 搜索 | modules/search.md | | "推荐适合我的 skill" / "有什么好用的" | 推荐 | modules/recommend.md | | "安装 xxx" / "帮我装这个 skill" | 安装 | modules/install.md | | "创建 / 写一个 skill" / "create skill" | 创建 | modules/create.md | | "检查这个 skill 质量" / "skill 体检" | 质检 | modules/inspect.md | | "动态评测 / 实测验证 / 跑测试看效果" | 质检（eval_mode=dynamic） | modules/inspect.md | | "混合评测 / 静态加动态 / 正式评审" | 质检（eval_mode=hybrid） | modules/inspect.md | | "扫描所有 skill / 全量体检 / 优化优先级" | 质检（mode=batch_baseline） | modules/inspect.md | | "诊断 / 优化 / 重构这个 skill" / "迭代到收敛" | 诊断 | modules/diagnose.md | | "优化 description / 提升触发率 / 跑加速器 / trigger eval" | 诊断（Step 4.6 description 量化加速器） | modules/diagnose.md + references/description-optimizer.md | | "生成成果卡片 / 出张图 / skill 优化战报" | 质检/诊断 报告后菜单触发 | references/result-card.md | | "推荐一个 xxx skill" | 搜索（以 xxx 为关键词） | modules/search.md | | "热门 skill" / "最受欢迎的 skill" | 搜索（Leaderboard 优先） | modules/search.md | | "更新 skill" / "检查 skill 新版本" | 安装（更新流程） | modules/install.md | | "相似 skill" / "类似 xxx 的 skill" | 搜索（相似搜索模式） | modules/search.md | | "收藏 / star 这个 skill" | 推荐（收藏操作） | modules/recommend.md | | "重新配置搜索偏好" / "reconfigure" | 引导 | modules/setup.md | | "开启/关闭更新检查" / "修改更新频率" | 自更新配置（修改 self_update） | config/sources.yaml preferences | | "检查 skill-assistant 更新" | 自更新检查（立即执行） | 上方「自身更新检查」流程 | | 搜索无结果时 | 自动降级到推荐 + 引导创建 | modules/recommend.md | | 安装前未扫描时 | 自动插入安装模块的安全扫描 | modules/install.md |

复合意图处理：用户同时提到搜索+安装（"帮我找一个 xxx skill 并装上"），按顺序执行搜索 → 用户确认 → 安装。

提案式交互：每次搜索/推荐结果后，必须附带编号式下一步菜单（安装/详情/收藏/重搜）。

关键参数契约速查（详细定义见各 modules/*.md）：

| 模块 | 必填参数 | 可选参数 | 前置条件 | |---|---|---|---| | 搜索 | query(用户意图字符串) | strategy(speed/balanced/thorough，默认 balanced) | 无 | | 安装 | skill_id(平台 ID 或仓库路径) | force(bool，默认 false) | 安全扫描通过 | | 质检 | target(SKILL.md 路径) | eval_mode(static/dynamic/hybrid/blind_hybrid) | 建产物前先调 resolve_workspace.py 解析 workspace 路径 | | 诊断 | target(SKILL.md 路径) | eval_mode, max_iterations(默认 3) | D10.1 ≥ 30（dynamic/hybrid 时）/ 建 workspace 前必走 W.0 | | Description 加速器 | target | provider(claude/codebuddy/…) | D10.2 ≥ 30（需 trigger-queries.json）|

Workspace 路径解析规则（W.0 步骤 · 任何会建产物的模块在 Step 0 之前强制执行）：

必读：references/workspace-layout.md（不在按需加载范围）
必调：python3 scripts/resolve_workspace.py --skill <skill_path> —— 唯一权威路径来源
必查：解析结果是否符合 <skills_container>/skill-assistant-workspace/<skill_name>/
必扫：<skills_container>/skill-assistant-workspace/ 下现有 sibling 子目录确认路径模板
manifest_io.write_manifest_atomic() 会做最后的路径合法性校验，路径不在 skill-assistant-workspace/ 下时 拒绝写入 并报错

核心原则

安全第一

所有来源不明的 Skill 安装前必须经过三引擎安全扫描（脚本硬扫描 + skills.sh 三方审计 + AI 软判断）
渠道信任等级 → 审查深度映射（Expert 决策规则）：

| 信任等级 | 渠道示例 | 扫描策略 | |---|---|---| | 高信任 | skills.sh 官方认证 / Knot 企业认证 | 跳过脚本扫描，仅 AI 软判断 | | 中信任 | Knot 社区 / SkillHub | 完整三引擎扫描 | | 低信任 | 用户自带 URL / 私有仓库 / 未知作者 | 三引擎 + 人工确认后才安装 |

CRITICAL 风险（如发现 curl | bash、硬编码密钥、读 MEMORY.md）→ 立即中止，不询问用户；HIGH 风险 → 展示详情由用户决定
检查访问 MEMORY.md、USER.md、SOUL.md、IDENTITY.md 等 AI Agent 敏感文件的行为

渠道可配置

源分为平台型技能市场和GitHub 优质仓库两大类，通过 config/sources.yaml 统一配置：

平台型提供独有质量信号（安装量/评分/认证），仓库型靠 Stars/作者声誉/社区策展
用户可在 preferences 段自定义安装位置、搜索策略、偏好源、去重策略
每个源可独立设置优先级、信任等级、获取方式、启用/禁用
用户可添加自有源（公司内部 registry、私有 GitHub 组织等）

渠道优先级快查表（Expert 规则，不在 LLM 训练数据中）：

| 场景 | 首选渠道 | 原因 | |---|---|---| | 中文内网场景 | Knot（POST+JSON body）| 中文内容最全，但需 POST 接口 | | 社区热门 skill | skills.sh（安装量降序）| 安装量是最真实的质量信号 | | 最新/实验性 skill | GitHub（gh search repos）| 上架慢的平台常滞后 1-2 版本 | | 公司私有 skill | 自定义源（sources.yaml）| 平台不收录内部 skill |

质量驱动

搜索关键词遵循三原则：简单核心词优先 / 先粗后细 / 多意图拆分（防止长查询导致低质量结果）
跨平台质量归一化：将各平台不同维度的指标（周安装量/Stars/排名/收录）映射为统一的推荐指数，混合排序
跨源去重比较：同一 Skill 出现在多个源时合并展示，功能相似的给出 A/B/融合建议
搜索结果必须经过名称验证 + 质量评估才能推荐（防止名不副实）
质检模块提供 10 维度 70+ 检查项量化评分（A-F 五级）+ D10 实测可验证性附加维度
诊断模块基于"Prompt 效能模型"进行三维分析（指令 40% / 约束 30% / 冗余 30%）

渐进式披露（按需加载架构）

本文件只做路由和原则声明
每个模块的详细工作流在对应的 modules/*.md 中
搜索模块核心流程（modules/search.md），固定规则拆到 references/ 按需加载：
- 评分映射表：references/scoring-rules.md
- 渠道命令模板：references/channel-search-commands.md
- 输出模板：references/output-templates.md
- 搜索透明度规范（诊断数据模型 + 异常检测规则）：references/search-transparency.md
- 搜索 Refine 规则（5 个 refine 分支处理逻辑，仅 refine 触发时加载）：references/refine-search.md
sources.yaml 选择性读取：搜索时只读 preferences: + settings: 段（~70 行），无需加载全文 545 行
模板、规则库等低频参考在 references/ 中
自动化逻辑在 scripts/ 中

静默执行

搜索/安装命令由 Agent 直接执行，不向用户展示原始命令
用编号式菜单和自然语言提案代替命令行展示

幂等性

除 last_check_date 写入外，所有读操作幂等——重复执行不产生副作用
搜索、质检、诊断报告阶段均为只读操作
安装操作通过 --force 参数控制覆盖行为，默认检测已安装不重复安装

常见错误（NEVER）

NEVER 跳过前置检查直接搜索/安装 — API Token 未加载会导致全部需认证渠道失败，浪费用户时间
NEVER 用 npx skills add 安装 — 侵入性强，会写 skills-lock.json + ~/.agents/，统一用 install_skill.sh
NEVER 跳模块混合执行 — 模块间有数据依赖（如搜索结果 → 安装输入），混合执行破坏流程完整性
NEVER 在多平台搜索时只发窄路不发宽路 — 窄路用复合关键词在部分平台（特别是 Knot 中文平台）可能全部返空，宽路是召回率的基础保障
NEVER 对中文平台只用英文关键词 — Knot 等中文平台的内容以中文为主，纯英文复合词无法匹配，必须同时生成中文变体关键词
NEVER 在 Knot API 中用 URL query params 传参 — 虽然不报错，但只返回近期上架的子集（ID ≥ 13000），丢失所有早期高质量 Skill，必须用 POST + JSON body
NEVER 把 Knot 响应字段写成 data.skill_list / data.skills / data.results — Knot OpenAPI 实际字段是 data.list（外层 {"code":0,"data":{"list":[...],"total_count":N},"msg":"success"}）。手写解析片段拼错字段会导致所有 Knot 候选被静默丢光 ——CHANNEL_THIN 只能记录"候选 0"，分不出是网络问题、Token 问题还是字段错配。任何"环境健康但 Knot 总候选 = 0"的情况都必须触发 KNOT_PARSE_MISMATCH（🚨 阻断），打印未解析的原始 JSON 自检后重跑（详见 references/search-transparency.md 异常规则表）
NEVER 在 gh search repos 第一轮叠加 --language / --stars 过滤 — 会踢掉其他语言的大型项目（如 Go ⭐38K）和新锐高质量项目；第一轮必须用 Level 3 单核心词无过滤，过滤只能作为第二轮补充或在结果集内 Agent 侧筛选
NEVER 用复合长查询调用 gh search repos — 如 "resume AI generator" 会漏掉只含 resume 的头部仓库；遵循「简单核心词优先」原则，第一轮用 1 个最短核心词 limit=30
NEVER 隐藏搜索参数 — 搜索输出必须包含诊断头（关键词/渠道候选数/漏斗收敛/异常清单），不得只返回"找到 N 条结果"而不展示用了什么关键词、查了多少条。用户不认可结果时，诊断头是定位偏差的唯一依据
NEVER 跳过 eval_mode 确认直接开始评审或优化 — inspect 和 diagnose 都适用：用户说"评审/质检/review/optimize/诊断"等任何评测或优化意图时，若未在原始输入中明确说明策略（static/dynamic/hybrid/blind），第一步必须展示策略选择菜单（inspect 用入口菜单 / diagnose 用 Step -1），再执行任何实质操作。"评审和优化"、"帮我看看这个 skill"等模糊意图绝不视为已指定策略。eval_mode 决定测试集是否必须、子 Agent 是否 spawn、报告深度——跳过等于让用户在不知情的情况下走了 structure_only 流程
NEVER 悄悄 refine — 用户通过菜单 7-11 发起 refine 时，输出必须用诊断头 diff 版展示"调整带来了什么变化"（候选量/置信度/命中率），不得只给新结果不给变化归因
NEVER 现场判断工具可用性 — 如 which gh && gh auth status 与其他 echo/ls 混写在一行，shell 退出码、stdout 顺序、权限前缀会让 Agent 把可用工具误判为不可用（真实事故：gh 实际装在 /opt/homebrew/bin/gh 但被误判为 missing，导致整个 GitHub 路降级）。工具/Key/网络三类状态必须通过 modules/search.md 第 0.5 步的结构化快照脚本一次性采集，结果写入 diagnostics.environment，后续步骤只读快照，不得重复探测
NEVER 漏专有名词 — 用户输入含人名/品牌名/中文译名（如"达尔文""花叔"）必须强制触发 L4 扩展，不受"L1-L3 已 ≥ 5 条"阈值限制；详见 references/search-templates.md Level 4 强制触发条件
NEVER 仅看头部 Top 5/10 就丢弃宽路结果 — skills.sh 按 installs 降序会让"贴脸但安装量较低"的精确匹配（如 darwin-skill@2878）被挤出 Top；宽路 limit=30 必须全部读 description 做语义二次筛选
NEVER 用列表/卡片/段落替代 Top N 表格 — 搜索输出的所有结构化信息（诊断头关键词/漏斗、每个来源分区的 Top N、跨源比较、推荐方案四档）必须用 markdown 表格展示，即使只有 1 条结果也必须有表头 + 1 行数据。列表、每条一个 ### 小标题、散文描述都会破坏搜索透明度主线——用户无法快速扫读对比。违反会触发 🚨 阻断级 LAYOUT_NON_TABLE，Agent 必须回退重写后才能交付。规则详见 modules/search.md §6.3.1
NEVER 质检/诊断完成后不展示报告选择菜单就结束 — inspect 报告生成后必须展示「[1]进diagnose棘轮 / [2]完整HTML报告 / [3]成果卡片 / [4]查看细则 / [5]完成」；diagnose 优化收尾必须展示 Step 6 的「[1]完整HTML报告 / [2]成果卡片 / [3]两者都要 / [4]不生成」——即使用户明确说"不需要"，也必须输出菜单等用户明确选 [4] 或 [5]，不得静默结束
NEVER 凭直觉拼 workspace 路径 — workspace 容器名是固定的 skill-assistant-workspace/（不是 <skill>-workspace/、不是 <skill>_eval/），下面再按 skill 名分子目录。建任何评测产物前必须：① 读 references/workspace-layout.md 解析规则；② 调 scripts/resolve_workspace.py --skill <path> 拿到唯一权威路径；③ Glob 现有 sibling workspace 验证模板一致。inspect / diagnose / batch_baseline / 加速器入口都受此约束。真实事故：未走解析直接建 .cursor/skills/<skill>-workspace/，27 个产物文件全建错位置后被迫迁移
NEVER 把新建 test-prompts.json 写到 <skill_dir> 内 — 产物统一写 workspace（<workspace>/<skill>/test-prompts.json，其中 <workspace> 严格指 skill-assistant-workspace/，由 resolve_workspace.py 解析得到，不许手拼），skill 目录内旧文件仅兼容读取；如检测到旧位置有文件，必须提示用户迁移
NEVER 只判断 test-prompts.json 是否存在就继续 — 存在性检查通过后，必须执行 test-prompts-design.md Step P.3 完整性 checklist（与 auto-judgement-generator.md Phase 3.5 同款标准——功能覆盖 100% / P0 场景 ≥95% / category ≥4 / 判别力 / negative 防偏置 / 场景类型至少 3 类）；不通过时必须展示交互菜单（自动补全/手动追加/优化judgement/跳过），不得静默继续
NEVER 未走 test-prompts-design.md 共用流程就开始动态评测 — 进入动态评测（inspect D.1）或诊断棘轮（diagnose Step 4）前，必须调 references/test-prompts-design.md Step P.1-P.5（定位 → 展示 → 丰富度 → STOP 用户确认 → 写 hash），inspect/diagnose 共用一份逻辑。例外：同一会话中 inspect 已写 manifest.test_prompts_confirmation.hash、当前 test-prompts.json 内容 hash 一致、用户未输入"review test-prompts"——此时 diagnose Step 0 可跳过 P.2-P.4 重复展示，仅打印简短"✓ 测试集与本会话上次确认一致"。其他情况必须走完整 STOP 流程
NEVER 跳过 Phase 2.5 矩阵确认直接生成测试 prompt — 自动生成测试集时，必须先按 auto-judgement-generator.md Phase 1 抽出功能模块清单，再按 Phase 2.5 规划"功能 × 5 类场景 × 优先级"4 维矩阵让用户对齐后才生成。直接凭直觉写几条 prompt = 必有功能盲区，棘轮决策可信度直接 -50%
NEVER 生成只覆盖 happy_path 的测试集 — 5 类场景至少要覆盖 3 类（happy + complex 各 ≥1，edge/negative/error 至少 1 类有覆盖）。只有 happy 路径的测试集等于"只测顺风路况"——无法发现 skill 在边界 / 反例 / 异常下的脆弱点
NEVER 把 CLI 新进程混入常规动态 eval 决策 — CLI 新进程（codebuddy / claude-internal）专门用于触发率测试（D10.2 / description 加速器 Step 4.6），不是"更好的输出质量评测引擎"；常规输出质量对比（D.1-D.3）用子 Agent 即可，不要向用户推销 CLI 作为动态 eval 默认选项
NEVER 触发率数据和输出质量数据混算 — CLI 新进程输出的 true trigger rate 和子 Agent 输出质量分不在同一维度，报告中必须分区展示，不得合并为单一评分
NEVER 在 dry_run 降级路径下不落盘 eval 结果 — inspect D.1 / diagnose Step 4.1.4.c 降级到 dry_run 时，主 Agent 必须把每条 test-prompt 的 baseline / with_skill 推演输出 + 逐条 judgement 评分按标准 schema 写到 <workspace>/iteration-N/eval-<scenario>/{baseline,with_skill}/run-1/{outputs/report.md,grading.json}。"只在对话记忆里推演"等于报告生成阶段读到空 eval-*/ 目录，{{EVAL_RESULTS_DETAIL}} 只能渲染 static 占位文本——这是修复过的真实事故。dry_run 不是"免落盘"，只是"主 Agent 自己当 Grader"
NEVER 把 dry_run 落盘 sanity check 延后到 Step 6 报告生成时 — 必须在 4.1.4.c / D.1 写完 grading.json 后就地校验 7 项（见各模块）：① baseline + with_skill 双 grading.json 存在且 size>50B ② expectations 数量 == judgements 数 ③ 每条 expectation 含 text/passed/evidence ④ evidence 不为空话 ⑤ 不允许"全 passed=true"（with_skill）/"全 passed=false"（baseline） ⑥ outputs/report.md 首行含"⚠️ dry_run 推演"标记 ⑦ 任一不通过立刻回写本条不进 4.1.5 / D.2。把 sanity check 拖到 Step 6 = 让用户等到看报告时才发现"评测整轮白做"
NEVER 凭直觉自拟 grading.json / eval_metadata.json schema — 子 Agent 与 dry_run 主 Agent 都必须按 references/sub-agent-protocol.md §grading.json 完整 schema 字段表落盘：顶层必含 passed_count + total_count + expectations[]（不是 summary.passed/total + judgements[] —— 后者是修复过的真实事故，导致报告 ⑥ 段空白且 sanity 误以为通过）；写完后必须立即调 scripts/validate_eval_artifacts.py <iter_dir>，failed 立即修，绝不带病调 generate-full-report.mjs。manifest 必须在 evaluation.eval_mode + iterations[].eval_mode 两处都写 eval_mode（前者是权威源）
NEVER 用固定 0.5σ 阈值做棘轮决策 — 4.1.5 的 keep/revert/unchanged 三档阈值必须按 N_repeats 动态算：threshold(N) = t(α=0.10, df=N-1) × σ/√N（N=3 → ≈1.09σ，N=10 → ≈0.44σ）。固定 0.5σ 在 N=3 时假阳性率 ~30%——会把噪声当好转 keep 下来。N=2 强制降级标 confidence=low；CV>0.30 标 high_variance 提示用户升 N 再决策
NEVER 把 N_repeats 一刀切应用到所有 prompt — 4.1.4.b 必须按 prompt 优先级差异化分配 N：P0=5 / P1=3 / P2=2 / 缺 priority 字段=3。每条 prompt 独立记录 N（benchmark.json 含 per_prompt_runs），让"核心场景决策更严谨、锦上场景花更少时间"。一刀切 N=3 在 P0 上不够稳、在 P2 上又浪费成本
NEVER 把 preview 模式结果写进 results.tsv 主分 — preview eval_mode 单点采样仅用于决策"下一步跑啥"，污染历史分会让棘轮跨次对比失真。preview 必须写到独立的 preview-results.tsv，且报告里明确标"preview · 单点采样不代表整体"
NEVER 在 Step 6 把"用户说不需要"等同于"选 [4]" — 用户自然语言输入"不需要"/"不用"/"skip" 时，必须先输出确认提示「这等同选 [4] 不生成，直接结束吗？[4] 是 / [1] 改主意要完整报告」让用户 STOP 显式选择。直接静默结束 = 让用户事后无报告归档无法挽回；同样不允许在 inspect 收尾跳过菜单
NEVER 用 Write 工具从零拼接 HTML 替代 templates/full-report.html — 详细诊断报告（iteration-N/detailed-report.html，原 full-report.html）必须通过 scripts/generate-full-report.mjs，单轮摘要报告（iter-summary.html，原 report.html）必须通过 templates/iteration-report.html + str.replace 渲染。手写 HTML 会跳过新模板的 {{COVERAGE_MATRIX}} / {{MUST_READ_ITEMS}} / {{D_DIMENSIONS_ROWS}} / {{D10_SUB_ROWS}} / {{EVAL_RESULTS_DETAIL}} 等占位符注入和 sanity check，导致用户视角 8 章节缺失。脚本落盘后会自动 sanity check：① 渲染产物无残留 {{ ② 有 eval-card 或 static 模式 或 dry_run 任一标记 ③ 非 static 非 dry_run 模式下 eval-*/grading.json 至少 1 个；任一失败 exit code = 3
NEVER 把 fidelity_mode 默认升档到 cli_fresh_process — 输出质量评测默认 subagent_default 子 Agent 双跑足够，CLI 新进程耗时 1.5-2× 必须用户明示才启用；results.tsv 必须有 fidelity 列一行可见，不允许默默升档浪费用户预算
NEVER 不显式记 time_budget.started_at 就开跑评测 — 每个 eval_mode 必须按 references/time-budget.md 表写入 soft/hard deadline + started_at，每完成 scenario 边界更新 elapsed_checkpoints；soft 超时弹 5 选项菜单 STOP 等用户、hard 超时按表自动降级（preview→3min / dynamic→10min / hybrid→12min / blind_hybrid→20min）。partial 评测 results.tsv 加 time_budget=hard_exceeded 标记，4.1.5 棘轮决策跳过判 unchanged
NEVER 在 hard_deadline 超时时优先牺牲 P0 prompt — time-budget hard 超时降级时牺牲顺序必须是 P2 → P1 → P0，P0 任何时候都保留（除非整个评测中止）。优先级反转 = 核心场景被砍 = 决策可信度归零
NEVER 用 path.write_text(yaml.dump(data)) 直接覆盖 manifest.yaml — 必须走 scripts/manifest_io.py write_manifest_atomic（.tmp + fsync + POSIX rename）；直写在 IDE 崩溃 / Ctrl-C / 断电时机会留下半截 yaml，下次 resume YAML 解析失败丢失整个评测会话。残留 manifest.yaml.tmp 不得静默吃掉 ——必须告知用户上次崩溃由用户决定是否信任 .tmp 兜底
NEVER hybrid/blind_hybrid 跑完不算 Grader vs static 一致性校验 — 4.1.5.5 / D.3.5 必须算 delta = abs(static_score − dynamic_score)，>15 在报告 Must-Read 加橙色警告、>25 红色严重警告；典型分歧（静态高 + 动态低 = "摆设型"，静态低 + 动态高 = "干货但格式糙"）必须显式归类。delta>15 + D10.3<0.5 时警告升级为"测试集可能没区分度"，建议先回 Step 0 重做测试集
NEVER 让 Grader/Comparator/Analyzer 子 Agent 自己读 test-prompts.json — 主 Agent 装配 _subagent_input.json 单向传递给子 Agent，子 Agent 只读这个 + transcript_path + outputs_dir。让子 Agent 自读会导致 scenario 漂移（错配 prompt） / 数据 inflation（扫描整个文件） / 盲评破坏（Comparator 反推身份）。装配协议 + 7 项收尾校验全文见 references/sub-agent-protocol.md
NEVER 给 Comparator 任何能反推身份的信息 — winner_role / anon_mapping / SKILL.md 路径泄漏 = 盲评设计直接失效。装配 _subagent_input.json 时必须把这些字段排除（仅 Analyzer 揭盲后调用时才接受 winner_role）
NEVER 评测完成后不落盘 detailed-report.html—— 无论 eval_mode 是 static / preview / dynamic / hybrid / blind_hybrid / dry_run，也无论用户 Step 6 最终选 [1]/[2]/[3]/[4]，<workspace>/iteration-N/detailed-report.html 必须在每轮 diagnose Step 4.1.6.5 / inspect 报告生成后立即通过 scripts/generate-full-report.mjs 强制生成落盘。Step 6 菜单仅控制"是否打开浏览器 + 是否追加 PNG 卡片"，不再触发 HTML 首次生成。静默不生成 = 事后用户需二次指令补生成（历史 iter-6 / iter-7 事故），违反"每次评测都要有可归档 HTML 产物"原则。Node 不可用时必须在 results.tsv 记 html_report=node_missing 异常行并提示用户装 Node，不得以"没 Node"为由跳过

模块概览

引导模块 — `modules/setup.md`

首次使用引导（setup_completed: false 时强制触发）：搜索源选择（ClawHub/SkillHub 二选一，支持自定义仓库）→ 环境检查 + API Key 持久化 → 搜索策略（speed/balanced/thorough）→ 配置写入 sources.yaml。说"重新配置搜索偏好"可随时重进。

搜索模块 — `modules/search.md`

宽窄双路 × 多路并行（宽路 30 + 窄路 10）；多平台（skills.sh / SkillsMP / SkillHub / Knot）+ 优质仓库（gh）+ 全 GitHub；跨源去重 + 融合推荐（A/B/融合三选一）；质量归一化（热度 40% + 权威 35% + 鲜度 25%）→ 统一推荐指数；搜索透明化（诊断头 + 11 条异常检测 + 5 个 refine 分支）。

安装模块 — `modules/install.md`

统一安装入口（install_skill.sh v2，禁止 npx skills add）+ 三引擎安全审查（13 项硬扫描 / skills.sh audit / AI 软判断）+ _skill_meta.json 版本追踪（folderHash > commitHash 双精度更新检测）。支持单/批量更新。

创建模块 — `modules/create.md`

Skill 创建全流程指南：三层加载系统 → 自由度设定 → 命名规范 → Eval 驱动开发。详见 references/create-best-practices.md。

质检模块 — `modules/inspect.md`

10 维度评分（D0-D9，对齐 OWASP LLM Top 10）+ D10 实测可验证性（附加）；eval_mode 四选一（static / dynamic / hybrid / blind_hybrid）；mode=batch_baseline 全量扫描输出优先级排行榜；输出 A-F 评分 + 改进建议 + 子 Agent 双跑实证。

诊断模块 — `modules/diagnose.md`

三维诊断（指令 40% / 约束 30% / 冗余 30%）→ Step 0-6 交互流程 → Step 4 棘轮迭代（独立子 Agent 评分 / git revert 防退步 / 体积守门 ≤ 1.5×）。Step 4.6 description 加速器（子 Agent 模拟 / CLI 保真双路径，60/40 split + 5 轮选优）；三角色子 Agent（Grader / Comparator / Analyzer）；产物落独立 workspace（manifest.yaml 管理）。

降级规则

| 异常情况 | 降级策略 | |---------|---------| | CLI 不可用（无 Node.js） | skills.sh 搜索降级为 curl API（同一端点），安装统一用 install_skill.sh（禁止 npx skills add），其余 CLI 渠道跳过并标注 | | ClawHub 版本不兼容 | 跳过，标注不可用 | | gh CLI 未安装或未认证 | 强烈引导安装 gh；降级为 WebSearch 兜底（精度显著降低；触发 balanced 条件 D） | | GitHub 搜索全部无结果 | 扩展关键词（同义词），最多重试一次 | | 深度抓取失败/超时 | 跳过，基于已有摘要分类 | | 安全扫描脚本不可用 | 跳过硬扫描，仅执行 AI 软判断 | | 全部搜索均无结果 | 自动切到智能推荐 + 引导创建模块；浏览 https://skills.sh | | config/sources.yaml 不存在 | 使用内置默认渠道配置 | | skills.sh API 超时 | CLI 和 API 是同一端点，一个超时另一个也不行；跳过 skills.sh，继续其他渠道 | | 自定义渠道响应异常 | 跳过该渠道，标注原因，继续其他渠道 |

全局兜底原则（三层降级链）

上表覆盖的是单源失败。当多源 / 整模块 / 全系统都失败时，按以下三层链路兜底：

| 层级 | 触发条件 | 处理策略 | |---|---|---| | L1 单源失败 | 上表 9 条任一命中 | 按表格策略处理，输出标注「⚠️ 渠道/工具降级」 | | L2 模块失败 | 同模块超过半数渠道全部失败（如所有搜索源都返空 / API Key 全无效） | 自动跨模块降级：搜索 → 推荐（基于已安装 skill）→ 创建引导（modules/create.md） | | L3 全部失败 | L2 后仍无结果 / 系统资源缺失（无 git、无网络、无任何 API Key、无可用 CLI） | 透明告知用户：列出已尝试路径 + 已识别失败原因 + 给出 3 条人工兜底（① 浏览 https://skills.sh ② 进入 setup 重新配置 ③ 联系 skill-assistant 维护者）|

降级透明度强制约束：任何 L1/L2/L3 降级必须在输出中显式提示 ——不允许静默 fallback。降级路径写入诊断头的「环境/异常」段，让用户能定位偏差来源（违反触发 🚨 阻断级 SILENT_FALLBACK，重跑前必须修复）。

参考资料

渠道详情：references/channels.md
安全规则（三引擎）：references/security-rules.md
搜索词模板：references/search-templates.md
推荐策略模板：references/recommend-templates.md
质检维度详情：references/quality-dimensions.md
诊断校准参考：references/diagnosis-calibration.md
创建最佳实践：references/create-best-practices.md
评分归一化映射表：references/scoring-rules.md
渠道搜索命令模板：references/channel-search-commands.md
搜索输出模板：references/output-templates.md
搜索透明度规范：references/search-transparency.md
搜索 Refine 规则：references/refine-search.md
成果卡片生成：references/result-card.md
单轮摘要报告（在 diagnose Step 4.1.6.5 自动生成 iteration-N/iter-summary.html 时加载）：references/iteration-report.md
完整详细报告（在 diagnose Step 6 生成 iteration-N/detailed-report.html 时加载）：references/full-report.md
卡片模板：templates/result-card.html
卡片渲染脚本：scripts/render-card.mjs
Description 量化加速器（融合 skill-creator）：references/description-optimizer.md
自动 Judgement 生成器（在 diagnose Step 0 / inspect D.0 自动生成测试集时加载 ——含 7 阶段流程 + 4 维覆盖矩阵 + 完整性 checklist）：references/auto-judgement-generator.md
test-prompts 设计与确认共用模块（在 inspect D.0.1 / diagnose Step 0.1 必加载 ——5 步定位/展示/丰富度/STOP确认/写hash + 同会话跳过逻辑）：references/test-prompts-design.md
时间预算控制（在 inspect D.0.3 / diagnose Step 4.0 必加载 ——按 eval_mode 默认 deadline + soft/hard 超时降级策略 + manifest.evaluation.time_budget 字段）：references/time-budget.md
子 Agent 调用协议（在 inspect D.1 / diagnose 4.1.4 / agents/grader|comparator|analyzer 共同遵循 ——主 Agent 装配 _subagent_input.json + 子 Agent 落盘约定 + 7 项收尾校验）：references/sub-agent-protocol.md
manifest 原子读写 helper（强约束 ——任何 manifest 写入必须走原子 write，详见 references/manifest-schema.md §atomic write）：scripts/manifest_io.py
金标数据集（在执行 batch_baseline 扫描 / 用户触发 detector 回归时加载）：tests/golden-dataset/（位于 workspace 根，不在 skill 目录内）
Detector 回归基线脚本（用户运行时参考）：tests/run_golden_baseline.py（位于 workspace 根）
渠道配置：config/sources.yaml
浏览所有 skills：https://skills.sh