Sm Analyzer

sm-analyzer — 开源 skill 分析（子 skill ③）

对用户指定的本地 skill 目录做深度分析：先写六章节中间稿 analysis.md， 再跑 scanner.py 安全扫描，最后用 report.py 渲染成单文件 HTML 报告。

遵循三原则（shared-references/skill-anatomy.md §6.2）：扫描与渲染等 确定性操作交给脚本，解读与评价等语义判断留给 LLM，产物落盘前先与 用户确认去向。

工作流

1. 确认输入：被分析 skill 必须是本地目录（用户已 clone/下载）。

   • 用 Test-Path 核对路径；不存在时向用户展示报错并请其核对，不猜路径
   • 用户给 GitHub 仓库链接时：在线下载不在本 skill 范围内，请用户先 自行下载到本地，再提供目录路径
   • 同时确认产物输出位置：默认被分析 skill 同目录，用户指定处优先； 三件产物（analysis.md / findings.json / HTML）都写到这里

2. 通读源码：

   • SKILL.md 必读——frontmatter、工作流、引用结构
   • references/、scripts/、assets/ 按存在逐个通读；其余文件浏览用途
   • 超大目标（文件数 >500，或后续扫描报 truncated）时，先向用户说明 抽样策略（入口文件与脚本全读、references 抽样、其余跳过）， 确认后再继续

3. 写中间稿 analysis.md 并落盘（后续步骤都以它为源，先写盘再走）：

   • 首行一个 H1：# <skill名> 分析报告——report.py 把第一个 H1 抽作 报告标题并从正文移除，全文勿出现第二个 H1
   • 六章节固定结构，每章一个 ##，顺序不可变：
     • ## 功能定位 — 做什么、给谁用、什么场景触发
     • ## 架构 — 目录结构、各文件分工、渐进披露的组织方式
     • ## 工作流拆解 — 入口文件描述的执行步骤，脚本/LLM/用户各管哪段
     • ## 设计模式 — description 写法、触发词、步骤清单化、引用下沉等手法
     • ## 亮点与短板 — 结构规范性逐条对照 shared-references/skill-anatomy.md： 目录结构（§1）、frontmatter（§2）、SKILL.md ≤200 行（§4.1）、 description 与触发词写法（§5）、反模式（§4.3）
     • ## 可借鉴点 — 具体到文件与写法（如"SKILL.md 的 Use when 句式"）， 不写空泛表扬
   • 只用渲染器支持的 markdown 子集：###/#### 标题、段落、有序/无序 列表、围栏代码块、行内code、粗体；表格、链接等其余语法按纯 文本输出，尽量不用

4. 安全扫描（PowerShell，从 skill-master 仓库根执行）：

   python scripts/scanner.py "<被分析skill路径>" --json | Out-File -Encoding utf8 findings.json
   

   • stdout 恒为单一 JSON：{"score","findings":[...],"truncated"}
   • 必须用 Out-File -Encoding utf8 落盘：PowerShell 5.1 的 > 重定向 写 UTF-16，report.py 按 utf-8 读会失败
   • truncated: true（目标超 500 文件被截断）时，回中间稿补注一句 （放"亮点与短板"章末）：安全扫描被截断，结果只覆盖前 500 个文件
   • 退出码非 0 时向用户展示 error JSON 并只停止本环节——中间稿已在 步骤③落盘，不丢；是否继续渲染由用户决定

5. 渲染 HTML 报告：

   python scripts/report.py --draft analysis.md --findings findings.json --out "<skill名>-analysis-<YYYY-MM-DD>.html"
   

   • 文件名含 skill 名与日期；可选 --timestamp "YYYY-MM-DD HH:MM" 固定 报告生成时间（默认取当前时间）
   • 成功时 stdout 打印输出路径；产物为自包含 HTML（内联 CSS，零外部资源）
   • 退出码非 0 时不写输出文件：向用户展示 stderr 报错，跳过渲染环节， 把已落盘的 analysis.md 直接交给用户并说明渲染失败原因

6. 交付：给用户 HTML 路径 + 一段话总结（功能一句话、结构规范性 结论、安全分与关键 findings、最值得借鉴的 1-2 点）。analysis.md 与 findings.json 留档不删——渲染失败时 analysis.md 就是可交付的救场稿。

错误处理

三个环节各自独立降级：任一脚本失败只停对应环节，已落盘的中间稿永不丢。

边界

• 安全深度分工：本 skill 呈现 scanner 的总分与规则命中即止；逐条 误报复核、修复建议等深度安全审查属 sm-security，需要时明确转介
• 对被分析 skill 的评价保持客观：亮点与短板都指向可验证的事实 （行数、目录结构、具体写法），不堆形容词
• 只新增分析产物，不修改被分析 skill 的任何源文件