CANN PyPTO 技能质量审计基于 pypto-skill-reviewer 的 52 规则四阶段评审与评分指南【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel 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规则按检查方式分为三类规则类型数量检查方式对应阶段static静态26 条由 validate_skill.py 确定性检查第 1 阶段semantic语义22 条由 LLM 依据 semantic-checklist.md 逐条判断第 2 阶段knowledge知识4 条R49–R52对照docs/目录验证知识内容一致性第 4 阶段52 26 22 4覆盖率计算的分母固定为 52。十个维度的名称与权重定义在 rules.json 的dimensions字段维度名称权重D1Frontmatter 元数据25%D2简洁性与效率15%D3文件结构与导航5%D4语言与表达10%D5精确性与可执行性10%D6工作流完整性10%D7模式与最佳实践5%D8反模式检测10%D9脚本与代码质量5%D10知识库一致性5%每条规则带有固定的严重级别severity与扣分由 rules.json 的severity_deductions定义S0 扣 20 分致命缺陷触发否决机制、S1 扣 10 分重大问题、S2 扣 5 分中等问题、S3 扣 2 分轻微建议。S0 级别规则仅有四条R01frontmatter 块、R02name 字段、R03description 字段、R34敏感数据。输入与参考文件评审器的事实来源体系评审器的设计原则是规则与评分可审计、可复现。用户只需提供一个skill-path待评审 skill 目录必须包含SKILL.md文件其余信息全部来自 skill 目录内的固定参考文件文件用途加载时机references/rules.json52 条规则、维度、权重和严重级别的唯一事实来源第 1、2 阶段开始时references/scoring-spec.md评分算法维度权重、扣分公式、S0 否决、等级映射第 3 阶段开始时references/semantic-checklist.md22 条语义规则的详细检查要求、证据标准和判定准则第 2 阶段开始时references/knowledge-checklist.md知识库一致性检查清单检查范围、内容正确性、语义一致性检查项第 4 阶段开始时scripts/validate_skill.py对 26 条静态规则做确定性静态检查输出 JSON findings第 1 阶段执行scripts/score_findings.py对合并后的 findings 执行确定性打分与覆盖率统计输出 JSON score第 3 阶段执行templates/report-template.md最终评审报告的 Markdown 模板第 3 阶段开始时读取这一SKILL.md 仅编排、参考文件承载细节的结构本身即符合 D7 维度的渐进式披露模式R32入口摘要 → 正文指令 → 参考深度。四阶段工作流详解评审执行四个阶段其中第 1 阶段与第 2 阶段可并行运行第 4 阶段独立检查知识库一致性references/ SKILL.md 中的知识内容。第 1 阶段静态检查26 条规则脚本确定性执行读取 references/rules.json理解规则定义——后续语义评审需识别 semantic 类型规则知识检查需识别 knowledge 类型规则问题聚合需从 rules.json 查询rule_content。对目标 skill 运行静态检查器。因为 26 条静态规则可通过脚本确定性检查避免人工误判python3 scripts/validate_skill.py skill-path捕获 JSON 输出——一个 finding 对象数组findings_static。验证脚本输出的字段完整性每个 finding 必须包含rule_id/status/severity/dimension/message/evidence/suggested_fix。缺失字段补充默认值PASS finding 的suggested_fix FAIL finding 必须提供非空suggested_fix若脚本未提供需在后续步骤补充。验证脚本是否成功退出。若失败报告错误并仅继续输出第 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 findingvalidate_skill.py保证 26 条静态规则全部有状态记录。第 2 阶段语义评审22 条规则LLM 逐条判断读取 references/rules.json 识别type: semantic的规则。读取 references/semantic-checklist.md 获取详细检查流程。读取目标 skill 目录中的全部文件SKILL.md必需、子目录中的所有文件references/、scripts/、templates/等。严格按照清单流程逐条评估语义规则与目标 skill 内容的一致性。对每条规则生成包含必需字段的 finding 对象{ rule_id: R07, status: 失败|通过|跳过, severity: S1, dimension: D1, message: 必须引用目标 skill 的具体内容, evidence: { file: SKILL.md, line: 3, snippet: 来自目标 skill 的逐字摘录≥10 个字符 }, suggested_fix: 针对该具体 skill 的明确修改建议 }对所有语义 findings 执行自校验Snippet 匹配验证每个evidence.snippet都在目标 skill 文件中逐字存在发现伪造片段立即删除或修正该 finding唯一性确保任意两条 finding 的message文本不完全相同重复项合并或差异化具体性确认每条message和suggested_fix都引用目标 skill 的具体内容而非泛化建议。semantic-checklist.md 为每条语义规则给出了检查要点、证据标准与 PASS/FAIL 判定示例。例如 R07description 必须回答做什么和何时使用PASS 示例是生成 PyPTO 算子的 golden 参考实现。当需要创建验证基准、写 golden 函数时使用。FAIL 示例是本技能用于 PyPTO 算子开发流程。——后者未说明具体产出、触发条件模糊。R20祈使语气要求运行脚本并捕获输出而非脚本应该被执行R33确定性脚本优先要求验证任务使用脚本而非完全依赖 LLM 判断。第 3 阶段评分与报告读取 references/scoring-spec.md 获取评分算法。读取 templates/report-template.md 获取报告格式。将第 1、2 阶段的所有 findings 合并为单一列表保存为findings_merged.json。对合并后的 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。按位置将 findings 聚合为问题issue聚合键file line_range彼此相距 ±5 行内的 findings 合并为一个问题每个问题记录所有匹配的rule_id值每个问题生成一条统一修复建议包含修改前/后对比rule_content从 rules.json 查询对应 rule_id 的rule字段内容。分数、等级、覆盖率、计数pass/fail/warn/skip必须使用score_result的输出不得手工估算。按维度计算分数时以score_result.dimensions为唯一来源dimension_raw max(0, 100 - sum_of_FAIL_deductions) dimension_score dimension_raw * weight应用质量门禁——评分前过滤 findings内部错绑internal_misbound_rule_or_evidence若某语义 finding 的证据明显引用的是 reviewer 自身而非目标 skill移除该 finding证据不足low_information_snippet若某语义 finding 的evidence.snippet无法在目标文件中逐字找到移除该 finding为报告的质量门禁章节记录所有被过滤项。使用模板渲染最终报告填充全部占位符。渲染遵循严格的脚本执行纪律生成脚本 → 执行脚本 → 脚本输出结果文件 → 验证文件存在 → 读取文件内容禁止跳过执行步骤直接读取结果文件若脚本执行失败记录错误并跳过该步骤不可陷入生成脚本→尝试读取结果→失败→重试的死循环仅在无法使用辅助脚本时才直接渲染报告不推荐。第 4 阶段知识库一致性检查R49–R52此阶段检查 skill 中的知识内容与docs/目录的一致性处理 knowledge 类型规则。检查范围references/目录若存在SKILL.md 中的知识性内容API 说明、路径说明、术语定义等。排除内容流程语义内容如运行脚本读取文件不需要检查。读取 references/rules.json 识别 knowledge 类型规则R49–R52。读取 references/knowledge-checklist.md 获取详细检查流程。扫描references/目录若存在获取文件列表。提取 SKILL.md 知识性内容APIpypto.xxxAPI 名称及说明、路径文件路径、命令路径引用、术语tile、tensor、pass、codegen 等框架概念。对提取的知识内容执行一致性检查识别实体 → 搜索 docs 验证 → 对比分析。问题分类P0/P1/P2并二次验证。生成 R49–R52 finding 对象添加到合并列表。将知识库检查结果作为独立章节添加到评审报告。知识检查的问题分级knowledge-checklist.mdP0 必须修复事实性错误、代码错误、路径错误、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%若 R04S1-10与 R05S2-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、R34FAIL总分上限59.9、最高等级D、报告摘要标注该否决。4. 等级映射数学区间表示法[a, b)含 a 不含 b等级分数范围A≥ 95.0B[85.0, 95.0)C[70.0, 85.0)D[55.0, 70.0)F 55.05. 计数规则PASS 不扣分FAIL 按严重级别扣分WARN 仅告警用于 S3 规则检查结果不确定的情况单独计数不扣分SKIP 不计数例如不存在scripts/目录时的 R42。此外还有两条自动满分规则不存在scripts/目录时 D9 自动满分skill 中不存在知识性内容时 D10 自动满分此时报告中第 7 章节标注未检测到知识性内容R49-R52 自动 SKIP。评审报告7 个必含章节最终向用户输出完整的 Markdown 评审报告模板见 report-template.md缺少任意章节都视为不完整评审摘要—— skill 名称、总分0–100保留两位小数、等级A/B/C/D/F、S0 否决状态是/否、规则统计pass/fail/warn/skip 计数。维度评分表—— 10 行D1–D10每行包含原始分0–100、权重、加权分、扣分明细列出每个 FAIL 的 rule_id 及其扣分值。规则覆盖率—— 静态计数 语义计数 知识计数 总评估数按状态拆分PASS/FAIL/SKIP覆盖率 evaluated / 52 × 100%。质量门禁—— 被过滤项的数量与移除原因internal_misbound/low_information_snippet。问题列表—— 按严重级别分组S0 → S3每个问题包含引用目标 skill 具体内容的问题描述、带严重级别标记的匹配规则 ID、位置file:line与逐字证据片段≥10 字符、含修改前/后对比的具体修复建议。通过规则汇总—— 按维度分组的全部通过 rule_id。知识库一致性检查—— 子章节包括检查概况references/ 文件数、SKILL.md 知识内容、问题统计、R49–R52 规则状态、P0 必须修复问题列表、P1 建议修复问题列表、P2 可选修复问题列表、无需修复项说明、联动修改检查。成功标准一个有效报告需满足 (a) 核心 7 个章节全部存在(b) 总分 各维度加权分之和±0.01(c) 每条 finding 的evidence.snippet都在目标文件中逐字存在(d) 覆盖率分母 52(e) 第 7 章节知识库一致性检查必须存在。错误处理策略失败场景的降级路径评审器为每种典型故障定义了明确的降级路径确保在任何异常下都能输出最小可用的报告故障场景处理方式未找到 SKILL.md以单条 S0 findingR01上报跳过其他所有检查输出最小报告分数 0等级 Fskill 目录为空同未找到 SKILL.mdfrontmatter 无效R01 FAIL 触发 S0 否决尽可能继续检查其他规则即不依赖 frontmatter 数据的规则脚本执行失败记录错误仅继续语义评审报告中注明静态检查未完成26 条静态规则全部标记 SKIPvalidate_skill.py 输出非 JSON报告静态分析脚本返回了非 JSON 输出质量门禁章节包含原始 stderr前 500 字符仅继续语义评审26 条静态规则全部标记 SKIP约束与最佳实践评审过程受到严格的约束这些约束共同保证了评审结果的客观性与可复现性只读评审不修改目标 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-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考