企业官网建设流程全解析

CANN PyPTO 技能质量审计：基于 pypto-skill-reviewer 的 52 规则四阶段评审与评分指南

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto

在 CANN PyPTO 仓库中，.agents/skills/目录沉淀了面向框架调试、编译期 Pass 分析、PR/Issue 流程与环境配置的十余个专家技能（skill）。当这些 skill 需要发布、审计或合规性评估时，pypto-skill-reviewer提供了一套确定性的质量评审方案：以 rules.json 中定义的 52 条规则为唯一事实来源，通过静态脚本、LLM 语义判断与知识库一致性检查三个层面交叉验证，最终输出带可执行修复建议的评分报告。读完本文，你将掌握该评审器的完整工作流、评分算法、报告结构与错误处理策略，能够在发布前独立对任意 skill 目录完成一次合规评审。

评审框架总览：10 个维度与 52 条规则

pypto-skill-reviewer将 skill 质量拆解为10 个维度（D1–D10）、52 条规则（R01–R52），规则按检查方式分为三类：

52 = 26 + 22 + 4，覆盖率计算的分母固定为 52。十个维度的名称与权重定义在 rules.json 的dimensions字段：

每条规则带有固定的严重级别（severity）与扣分（由 rules.json 的severity_deductions定义）：S0 扣 20 分（致命缺陷，触发否决机制）、S1 扣 10 分（重大问题）、S2 扣 5 分（中等问题）、S3 扣 2 分（轻微建议）。S0 级别规则仅有四条：R01（frontmatter 块）、R02（name 字段）、R03（description 字段）、R34（敏感数据）。

输入与参考文件：评审器的"事实来源"体系

评审器的设计原则是"规则与评分可审计、可复现"。用户只需提供一个<skill-path>（待评审 skill 目录，必须包含SKILL.md文件），其余信息全部来自 skill 目录内的固定参考文件：

这一"SKILL.md 仅编排、参考文件承载细节"的结构本身即符合 D7 维度的渐进式披露模式（R32）：入口摘要 → 正文指令 → 参考深度。

四阶段工作流详解

评审执行四个阶段，其中第 1 阶段与第 2 阶段可并行运行；第 4 阶段独立检查知识库一致性（references/+ SKILL.md 中的知识内容）。

第 1 阶段：静态检查（26 条规则，脚本确定性执行）

1. 读取 references/rules.json，理解规则定义——后续语义评审需识别 semantic 类型规则，知识检查需识别 knowledge 类型规则，问题聚合需从 rules.json 查询rule_content。

2. 对目标 skill 运行静态检查器。因为 26 条静态规则可通过脚本确定性检查，避免人工误判：

   python3 scripts/validate_skill.py <skill-path>

3. 捕获 JSON 输出——一个 finding 对象数组findings_static。

4. 验证脚本输出的字段完整性：每个 finding 必须包含rule_id/status/severity/dimension/message/evidence/suggested_fix。缺失字段补充默认值：PASS finding 的suggested_fix = ""；FAIL finding 必须提供非空suggested_fix（若脚本未提供需在后续步骤补充）。

5. 验证脚本是否成功退出。若失败，报告错误，并仅继续输出第 2 阶段结果。

从源码看，validate_skill.py 实现了全部 26 条静态规则检查器（check_r01至check_r45），其核心机制包括：YAML frontmatter 解析器（parse_frontmatter，以---分隔、yaml.safe_load解析）、代码块感知的行分类器（CodeBlockTracker，跟踪```/~~~围栏的开闭状态，使 R13/R34/R35/R38 等扫描自动跳过代码块内容）、以及统一的finding()工厂函数（从rule_meta自动回填严重级别与维度归属）。脚本还会自动为未触发的静态规则补充 PASS finding（validate_skill.py），保证 26 条静态规则全部有状态记录。

第 2 阶段：语义评审（22 条规则，LLM 逐条判断）

1. 读取 references/rules.json 识别type: "semantic"的规则。

2. 读取 references/semantic-checklist.md 获取详细检查流程。

3. 读取目标 skill 目录中的全部文件：SKILL.md（必需）、子目录中的所有文件（references/、scripts/、templates/等）。

4. 严格按照清单流程，逐条评估语义规则与目标 skill 内容的一致性。

5. 对每条规则生成包含必需字段的 finding 对象：

   { "rule_id": "R07", "status": "失败|通过|跳过", "severity": "S1", "dimension": "D1", "message": "（必须引用目标 skill 的具体内容）", "evidence": { "file": "SKILL.md", "line": 3, "snippet": "（来自目标 skill 的逐字摘录，≥10 个字符）" }, "suggested_fix": "（针对该具体 skill 的明确修改建议）" }

6. 对所有语义 findings 执行自校验：

   • Snippet 匹配：验证每个evidence.snippet都在目标 skill 文件中逐字存在，发现伪造片段立即删除或修正该 finding；
   • 唯一性：确保任意两条 finding 的message文本不完全相同，重复项合并或差异化；
   • 具体性：确认每条message和suggested_fix都引用目标 skill 的具体内容，而非泛化建议。

semantic-checklist.md 为每条语义规则给出了检查要点、证据标准与 PASS/FAIL 判定示例。例如 R07（description 必须回答"做什么"和"何时使用"）：PASS 示例是"生成 PyPTO 算子的 golden 参考实现。当需要创建验证基准、写 golden 函数时使用。"，FAIL 示例是"本技能用于 PyPTO 算子开发流程。"——后者未说明具体产出、触发条件模糊。R20（祈使语气）要求"运行脚本并捕获输出"而非"脚本应该被执行"；R33（确定性脚本优先）要求验证任务使用脚本而非完全依赖 LLM 判断。

第 3 阶段：评分与报告

1. 读取 references/scoring-spec.md 获取评分算法。

2. 读取 templates/report-template.md 获取报告格式。

3. 将第 1、2 阶段的所有 findings 合并为单一列表，保存为findings_merged.json。

4. 对合并后的 findings 运行确定性评分脚本：

   python3 scripts/score_findings.py \ --rules references/rules.json \ --skill-path <skill-path> \ --findings findings_merged.json

   将 JSON 输出保存为score_result.json文件。该脚本也支持--static/--semantic分别传入两阶段 findings，以及--out指定输出路径（score_findings.py）。

5. 按位置将 findings 聚合为问题（issue）：

   • 聚合键：file + line_range（彼此相距 ±5 行内的 findings 合并为一个问题）；
   • 每个问题记录所有匹配的rule_id值；
   • 每个问题生成一条统一修复建议（包含修改前/后对比）；
   • rule_content：从 rules.json 查询对应 rule_id 的rule字段内容。

6. 分数、等级、覆盖率、计数（pass/fail/warn/skip）必须使用score_result的输出，不得手工估算。

7. 按维度计算分数时，以score_result.dimensions为唯一来源：

   dimension_raw = max(0, 100 - sum_of_FAIL_deductions) dimension_score = dimension_raw * weight

8. 应用质量门禁——评分前过滤 findings：

   • 内部错绑（internal_misbound_rule_or_evidence）：若某语义 finding 的证据明显引用的是 reviewer 自身而非目标 skill，移除该 finding；
   • 证据不足（low_information_snippet）：若某语义 finding 的evidence.snippet无法在目标文件中逐字找到，移除该 finding；
   • 为报告的质量门禁章节记录所有被过滤项。

9. 使用模板渲染最终报告，填充全部占位符。渲染遵循严格的脚本执行纪律：生成脚本 → 执行脚本 → 脚本输出结果文件 → 验证文件存在 → 读取文件内容，禁止跳过执行步骤直接读取结果文件；若脚本执行失败，记录错误并跳过该步骤，不可陷入"生成脚本→尝试读取结果→失败→重试"的死循环；仅在无法使用辅助脚本时才直接渲染报告（不推荐）。

第 4 阶段：知识库一致性检查（R49–R52）

此阶段检查 skill 中的知识内容与docs/目录的一致性，处理 knowledge 类型规则。

检查范围：references/目录（若存在）；SKILL.md 中的知识性内容（API 说明、路径说明、术语定义等）。排除内容：流程语义内容（如"运行脚本""读取文件"）不需要检查。

1. 读取 references/rules.json 识别 knowledge 类型规则（R49–R52）。
2. 读取 references/knowledge-checklist.md 获取详细检查流程。
3. 扫描references/目录（若存在），获取文件列表。
4. 提取 SKILL.md 知识性内容：API（pypto.xxxAPI 名称及说明）、路径（文件路径、命令路径引用）、术语（tile、tensor、pass、codegen 等框架概念）。
5. 对提取的知识内容执行一致性检查（识别实体 → 搜索 docs 验证 → 对比分析）。
6. 问题分类（P0/P1/P2）并二次验证。
7. 生成 R49–R52 finding 对象，添加到合并列表。
8. 将知识库检查结果作为独立章节添加到评审报告。

知识检查的问题分级（knowledge-checklist.md）：P0 必须修复（事实性错误、代码错误、路径错误、API 不存在、与 docs 直接矛盾）、P1 建议修复（概念歧义、术语不一致、正则/格式错误）、P2 可选修复（描述模糊、引用缺失）。同时该清单明确定义了排除项：合理简化（如 dtype 速查表 + 指向 docs）、更严格规范（skill 可定义比 docs 更严的要求）、内部知识（troubleshooting 经验）、上下文相关路径（已确认执行上下文的scripts/xxx.py）、无对应 docs 的内容（评审规则、报告模板）——这些均不误报为问题。检查中还要求确认执行上下文（工作目录、环境变量、前置条件），避免把"从错误目录验证"导致的假阴性当成错误。

评分算法：从扣分到等级的完整链路

scoring-spec.md 定义了三条核心规则，全部由 score_findings.py 确定性实现：

1. 单维度得分。每个维度先按 0–100 的内部量表评分，再乘以权重：

dimension_raw = max(0, 100 - sum_of_deductions_in_dimension) dimension_score = dimension_raw × weight

示例（D1 权重 25%）：若 R04（S1，-10）与 R05（S2，-5）均失败：

D1_raw = max(0, 100 - 10 - 5) = 85 D1_score = 85 × 0.25 = 21.25

该公式避免低权重维度因一次 S1 扣分被直接清零（例如 D7 权重 5% 时，一次 S1 得max(0,100-10)×0.05 = 4.5，而非max(0,5-10) = 0）。

2. 总分：total_score = Σ dimension_scores (D1 至 D10)。

3. S0 否决机制。若任意S0 规则（R01、R02、R03、R34）FAIL：总分上限59.9、最高等级D、报告摘要标注该否决。

4. 等级映射（数学区间表示法，[a, b)含 a 不含 b）：

5. 计数规则：PASS 不扣分；FAIL 按严重级别扣分；WARN 仅告警（用于 S3 规则检查结果不确定的情况）单独计数不扣分；SKIP 不计数（例如不存在scripts/目录时的 R42）。此外还有两条自动满分规则：不存在scripts/目录时 D9 自动满分；skill 中不存在知识性内容时 D10 自动满分（此时报告中第 7 章节标注"未检测到知识性内容，R49-R52 自动 SKIP"）。

评审报告：7 个必含章节

最终向用户输出完整的 Markdown 评审报告，模板见 report-template.md，缺少任意章节都视为不完整：

1. 评审摘要—— skill 名称、总分（0–100，保留两位小数）、等级（A/B/C/D/F）、S0 否决状态（是/否）、规则统计（pass/fail/warn/skip 计数）。
2. 维度评分表—— 10 行（D1–D10），每行包含：原始分（0–100）、权重、加权分、扣分明细（列出每个 FAIL 的 rule_id 及其扣分值）。
3. 规则覆盖率—— 静态计数 + 语义计数 + 知识计数 = 总评估数，按状态拆分（PASS/FAIL/SKIP），覆盖率 = evaluated / 52 × 100%。
4. 质量门禁—— 被过滤项的数量与移除原因（internal_misbound/low_information_snippet）。
5. 问题列表—— 按严重级别分组（S0 → S3），每个问题包含：引用目标 skill 具体内容的问题描述、带严重级别标记的匹配规则 ID、位置（file:line）与逐字证据片段（≥10 字符）、含修改前/后对比的具体修复建议。
6. 通过规则汇总—— 按维度分组的全部通过 rule_id。
7. 知识库一致性检查—— 子章节包括：检查概况（references/ 文件数、SKILL.md 知识内容、问题统计、R49–R52 规则状态）、P0 必须修复问题列表、P1 建议修复问题列表、P2 可选修复问题列表、无需修复项说明、联动修改检查。

成功标准：一个有效报告需满足 (a) 核心 7 个章节全部存在；(b) 总分 = 各维度加权分之和（±0.01）；(c) 每条 finding 的evidence.snippet都在目标文件中逐字存在；(d) 覆盖率分母 = 52；(e) 第 7 章节（知识库一致性检查）必须存在。

错误处理策略：失败场景的降级路径

评审器为每种典型故障定义了明确的降级路径，确保在任何异常下都能输出最小可用的报告：

约束与最佳实践

评审过程受到严格的约束，这些约束共同保证了评审结果的客观性与可复现性：

• 只读评审：不修改目标 skill 目录中的任何文件。
• 不伪造证据：每个 snippet 都必须真实存在于目标文件中。
• rules.json 是唯一事实来源：禁止发明 rules.json 未定义的规则、修改其中的严重级别或维度归属、跳过任何规则（若某规则无法检查必须以 SKIP 标记并给出原因）、基于假设或外部知识覆盖规则定义；每条 finding 都必须引用一个存在于 rules.json 的rule_id。
• 评分纪律：严格使用 scoring-spec.md 中的评分公式，不得估算或近似。
• 脚本执行纪律：正确流程为 Write script → Bash execute script → Read result file；执行失败时记录错误并继续，不可陷入死循环；禁止跳过执行步骤直接读取结果文件。
• Python 代码生成约束（用于生成临时脚本时）：所有 Python 变量名、字符串内容使用纯 ASCII 字符；禁止在 Python 代码中使用中文标点（如、。：）；注释和说明性文本可用中文但必须使用标准 ASCII 标点；字符串值若需包含中文文本，用英文标点分隔。
• 知识规则检查的额外约束：以docs/目录为唯一标杆，不以经验推断代替文档验证；标记问题前必须确认执行上下文（工作目录、环境变量、前置条件）；合理简化、更严格规范、内部知识不属于问题，不应误报。

结语：让 skill 评审从"人工抽查"走向"确定性审计"

pypto-skill-reviewer的设计核心在于把 LLM 判断与确定性脚本分层：26 条静态规则由脚本零误差扫描，22 条语义规则在严格的证据标准（逐字 snippet、唯一性、具体性）约束下由 LLM 判断，4 条知识规则以docs/为唯一标杆做一致性核验，最终评分完全由 score_findings.py 依据 scoring-spec.md 的公式计算。配合 S0 否决机制、质量门禁过滤与完整的错误降级路径，它能在 skill 发布前给出"分数 + 等级 + 按严重级别排序的可执行修复清单"，让技能生态的质量维护变得可审计、可复现、可追踪。若需在cann/pypto仓库中审计任意 skill，只需将目标 skill 目录路径传入上述两个脚本，并按本文所述四阶段流程组织评审即可。

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto