18—sentry-static 入口收敛：从多能力检查到 1 个统一静态分析入口

前两篇讨论了 LLM 调用过多与 subagent 切换成本过高，效率专题的第三个问题则来自工具入口：用户若每次仍需判断运行 lint、trigger 还是 check，系统使用起来就不够顺手。

sentry-static 的入口收敛并非只是减少一个命令名，而是用稳定入口承接用户一次完整的静态分析意图。本文的原则是按照用户意图划定工具边界，而非依据内部检查项划分。

回顾：三个版本，三种形态

看起来只是名称调整、入口合并与检查维度增加，实际上每次形态变化背后都对应一个工程决策点。

sentry-check（v7.1）的形成：第一次把 sentry-trigger + sentry-lint 合并

合并前的痛点

lint 与 trigger 在 v6.x 里互不隶属，完全是两个工具：

sentry-lint→ 静态结构检查，~30ssentry-trigger → 触发率 AI 模拟（TP/TN），~2min

实际使用暴露出三个问题：

1. 几乎无人只运行其中一个

内部统计的依据，是对真实测评中 20+ 次调用模式所作的复盘：

• 92% 的情况：用户同时需要两者
• 仅检查结构、单独运行 lint：占 5% 的情况
• 微调 description 后单独重测 trigger：占 3% 的情况

用户在 92% 的时间里只有「帮我看看这个 Skill 写得好不好」这一个意图，却要面对两次 spawn、两次 yield/resume 和两份回执，因为工具共有两个。

2. 报告彼此割裂，用户必须自行建立关联

「TN 不触发率只有 40%」出现在 trigger 报告中；「description 太短，缺少不触发场景」则是 lint 报告的结论。

两个结论具有因果联系：description 没有描述「不触发场景」，使 AI 判断是否触发时缺乏足够的排除信号；然而，用户无法从两份独立报告中看到这种关联。

3. 编排器要用额外逻辑确定执行顺序

如果 description 根本不存在，运行 trigger 没有意义，因此主编排器要把 lint 放在前面，再执行 trigger。编排器的复杂度由这种「条件跳过 + 先后依赖」逻辑推高。

合并后的设计

sentry-check:Part 1: 静态检查，~30sPart 2: 触发率评估（TP/TN），~2min支持子模式：lint <Skill名>→ 只跑 Part 1测触发率 <Skill名> → 只跑 Part 2check <Skill名> → 两项都跑

向后兼容——旧的 lint 和 测触发率 命令继续有效。

合并判断标准是：两个工具在 >80% 的调用场景中总是共同出现，而且输入一致（都读取 SKILL.md），通常就应该合并。

状态机阶段的第二次演进：由 sentry-check 转为 sentry-static

为何不再沿用 sentry-check

用户在 v7.1 的 sentry-check 中看到的是以下内容，而它的本质仅是拼合两个工具的输出：

## Part 1 · 静态检查L1: ✅ / ⚠️ / ...L2: ...L3: ...L4: ...L5: ...## Part 2 · 触发率评估TP: 80%TN: 67%

然后用户自己判断：「L1 说 description 没问题，但 TN 只有 67%，说明不触发场景虽然有，但写得不够精准。」

问题是，这项推理本应由工具自动完成。

综合建议成为状态机阶段新增的 Sub-step 3

sentry-static:Sub-step 1: Lint（静态规则检查）Sub-step 2: Trigger（TP/TN 触发率评估）Sub-step 3: Summary（交叉分析 + 综合发布建议）

Sub-step 3 的逻辑：

核心变化是由「提供两组数据」转为「给出一个判断 + 理由」。两份报告之间的关联由工具完成，用户无需自行处理。

改名的原因

sentry-check 的含义是「检查」，暗示输出由多项检查结果构成。sentry-static 输出被暗示为分析结论，因为其语义指向「静态分析」。

工具定位从「数据展示」转向「分析判断」，名称变化正是这一转变的体现。

如何处理旧 sentry-check

在当前实现中，原 sentry-check 属于兼容入口，并非推荐入口：

# sentry-check（兼容入口）此工具已被 sentry-static 替代。如果你是通过旧命令到达这里，请改用 sentry-static。所有旧命令仍然有效：- lint <Skill名> → sentry-static --lint-only- 测触发率 <Skill名> → sentry-static --trigger-only- check <Skill名> → sentry-static（完整模式）

为什么保留兼容入口而不直接删除？因为用户（和 AI 编排器）可能对 sentry-check 有肌肉记忆。兼容入口起到重定向作用，零成本地处理旧路径。

仍然保留独立模式

入口合并不等于放弃精细控制：

sentry-static --lint-only → 只跑 Sub-step 1（~30s）sentry-static --trigger-only→ 只跑 Sub-step 2（~2min）sentry-static → 三步全跑（~2.5min）

保留独立模式的场景：

• 快速验证微调结果：description 改完后若目标只是检验触发率，全部 lint 无须重跑
• CI 集成：lint 属于确定性检查，CI 环境只需运行它；trigger 要做 AI 推理，结果会波动且耗时
• 调试单项：若仅有某一项未通过，只重跑该项能省去等待全部完成的时间

设计决策框架：合并与拆分的适用时机

一套判断标准，来自我对 sentry-lint/trigger → sentry-check → sentry-static 这段演进的总结：

合并的信号

拆分的信号

SkillSentry 中的应用示例

为什么 sentry-static 和 cases 步骤不合并？

• 输入并不相同：cases 需要 inputs/ 素材，static 则只读取 SKILL.md
• 失败彼此独立：若 static 因结构问题失败，用户可能先完成修复，之后才运行 cases
• 耗时并不相同：cases ~5-8min，static ~2.5min
• 用户或许只想执行 lint，并不准备设计用例，两者的调用场景因此不同

三个拆分信号全部命中，因此不合并才是正确选择。

对 Pipeline 状态机的影响

状态机阶段 Pipeline 的设计因 sentry-static 被引入而产生一个关键影响：

Pipeline 数组的第一步由 check 调整为 static：

// v7.x（非正式 pipeline）["check", "cases", "executor", "grader", "report"]// 状态机阶段+ 正式 Pipeline["static", "cases", "sync-pull", "sync-push-cases", "executor-with", "grader", "sync-push-results", "report", "publish"]

状态机只认 Pipeline 数组里的 step name。当工具改名时，Pipeline 数组必须同步更新。这就是为什么当前主流程只写 static，不再把 lint、trigger、check 写成正式 pipeline step。

工具链演进的普遍规律

从 v5.x 走向稳定形态，SkillSentry 的工具经历了如下演进：

v5.x: 5 个独立工具（lint, trigger, cases, executor, grader）v6.x: 5 个 + sync + report = 7 个v7.1: 合并 → check + cases + executor + grader + report = 5 个状态机阶段: 重组 → static + cases + executor + grader(含report) + report(独立)+ comparator + analyzer + openclaw = 8 个稳定形态: 收敛 → static 是推荐入口；grader-report 是主流程评分报告；sentry-report 仅用于已有 grading 后独立重出报告

工具数量不是越少越好，也不是越多越好。判断标准是：每个工具对应一个「用户意图的最小完整单元」。

• v6.x 的 7 个工具过于零散，因为 lint 与 trigger 并非独立意图
• 若把全部工具合并成 1 个，「工具」就会变成「应用」，并失去可组合性

「意图完整」与「原子可组合」之间的平衡点，构成了最终形态。

后续扩展：规则组 6——规范合规检查

“用户只需要记一个静态分析入口”是入口收敛所解决的问题：后续检查组以及 Summary、Trigger、Lint 都纳入 sentry-static。这个稳定入口内部增加了 L6 这一检查维度，并未产生新增入口；它要回答的，是更基础的 SKILL.md 结构完整性问题。

一个真实案例是：某个 Skill 虽通过 L1-L5 全部检查，新人接手后却完全不清楚它解决的问题、依赖的环境变量、输入输出格式以及覆盖或不覆盖的场景。这些内容属于“结构”而非“规则”，决定 Skill 能否被团队理解与维护。

结构完整度为何也是质量指标

一份标准 SKILL.md 需要以《MIT AI Skill 撰写规范 V1.1-beta》为对照，覆盖的章节共有 13 个，各自用于回答一个实际问题：

每缺少一个章节，就会增加一个“凭感觉”处理的环节。

L6 的三层检查

L6a：Frontmatter 9 字段——name、display_name、version、description、author、track、platform、spec、tags。缺 name/version 会影响 CI 缓存命中（sentry_preflight.py 用 name + hash 判断复用）。

L6b：13 章节覆盖率——逐项确认是否包含对应内容，判断依据是实质内容而非标题：

• ✅ 存在且实质性
• ⚠️ 散落在其他章节中（建议独立）
• ❌ 完全缺失

L6c：合规度评级：

≥ 90% → ✅ 合规70-89% → ⚠️ 基本合规50-69% → ⚠️ 部分合规< 50% → ❌ 不合规

和 L1-L5 的关系

L6 不替代 L1-L5。一个 Skill 可以 L1-L5 全绿但 L6 只有 35%——能跑，但别人接不住。反过来 L6 100% 但 L2 红（写操作没确认），也不能发布。六组一起看才是完整的静态质量画像。

在 CI 中的定位

结构化诊断产物或报告可以记录 L6 评级，但 PASS/FAIL 不由它否决。发布决策者可把这项参考指标用于判断“这个 Skill 是否已经准备好交给别人用”。如果已有 Skill 能正常工作，就不能仅凭“文档不全”将其卡住。

FAQ

Q：AI 判断的不确定性会因 sentry-static 的 Sub-step 3 而出现吗？

Sub-step 3 采用规则化判断逻辑，以静态检查项及 TP/TN 数值阈值为依据，并非让 AI 自由判断。AI 只生成自然语言解释，判断结果本身具有确定性。

Q：迁移工作从 sentry-check 转向 sentry-static 时涉及哪些改动？

用户侧：将推荐入口统一为 sentry-static。lint、测触发率、check 此类旧说法仍可兼容或重定向，但不再被推荐为正式入口。

Pipeline 侧：自定义 pipeline 配置如果存在，需要调整其中的 step name，把原名称从 check 修改为 static 即可。

Q：兼容入口是否会永久保留？

兼容入口目前仍然保留。删除与否要由日志中是否存在旧命令调用来决定，不能只凭版本号；调用只要尚未消失，重定向就须继续保留，文档也应标明目前推荐的入口为 sentry-static。

sentry-static 设计文档、历史 sentry-check/SKILL.md、SkillSentry contract 为资料来源。