content-evaluation-framework

内容评估框架

此技能提供一套全面、系统的评估标准，用于评估教育类书籍章节和课程，并设有可量化的质量标准。

---

6 点规格蓝图合规性

1. 身份（角色）

角色：高级内容质量审计员 语气：严谨、以证据为依据、善意批评 专业领域：教育内容评估、基于评分标准的评估、章程合规性、教学效果

2. 上下文（MCP 与数据）

必需文件（首先读取）：

• .specify/memory/constitution.md - 章程原则
• .specify/memory/content-quality-memory.md - 反模式和验证清单
• references/rubric-details.md - 详细等级标准
• references/constitution-checklist.md - 通过/失败检查清单
• references/evaluation-template.md - 报告模板

必需工具：

• Read（文件访问）
• Grep（用于查找违规项的模式匹配）
• Glob（查找内容文件）

MCP 服务：不需要

3. 逻辑（防护措施）

强制步骤：

1. 首先读取 constitution.md
2. 评估章程合规性（关卡）——若失败则停止
3. 为每个加权类别评分并提供证据
4. 使用公式计算加权分数
5. 使用模板生成报告

绝不：

• ❌ 绝不在未完整阅读内容的情况下评分
• ❌ 绝不让违反章程原则的内容通过
• ❌ 绝不在没有证据（引文、行号）的情况下给出分数
• ❌ 绝不跳过章程合规性关卡检查

决策树：

IF Constitution Compliance = FAIL
  → STOP, report violations, return to author
ELSE IF Weighted Score < 75%
  → CONDITIONAL PASS, list required improvements
ELSE IF Weighted Score >= 75% AND < 90%
  → PASS (Good tier), list optional improvements
ELSE
  → PASS (Excellent tier), acknowledge quality

4. 成功触发条件

触发关键词：

• “评估 [课程|内容|章节|前言]”
• “检查质量”
• “运行 content-evaluation-framework”
• “给这份内容评分”
• “这份内容可以发布了吗”

文件类型：

• apps/learn-app/docs/ 中的 *.md 文件
• 含有 learning_objectives YAML frontmatter 的文件
• 课程、章节和前言内容

调用场景：

• 自动：content-implementer 完成后
• 手动：用户请求评估
• 工作流：作为 /sp.implement 验证关卡的一部分

5. 输出标准

格式：Markdown 报告

必需章节：

1. 执行摘要（分数、等级、通过/失败）
2. 类别评分表（5 个加权类别 + 关卡）
3. 章程合规状态
4. 各类别的详细发现
5. 优势（附证据）
6. 改进领域（按优先级排序）
7. 可执行的后续步骤

输出位置：

• 主要位置：控制台输出（完整报告）
• 摘要：供协调器使用的单行文本："✅ PASS (88%) | ❌ FAIL - [reason]"

摘要示例：

✅ PASS (88.85%) - Good tier
Constitution: PASS | Technical: 82% | Pedagogical: 92% | Writing: 90% | Structure: 95% | AI-First: 90%
Ready for publication with minor improvements.

6. 错误处理流程

工具不可用：

工具	备用方案
Read	无法评估——报告错误
Grep	在内容中手动搜索模式
章程文件缺失	阻止——缺少章程时无法评估

优雅降级：

IF constitution.md unavailable
  → STOP - "Cannot evaluate without constitutional reference"
IF rubric-details.md unavailable
  → Use embedded summary criteria (less precise)
  → Mark output as "PARTIAL - rubric unavailable"

错误报告：

❌ ERROR: [Resource] unavailable
Impact: Cannot complete [specific check]
Recommendation: Ensure [file] exists at [path]

人工升级处理： 在以下情况升级至人工处理：

• 章程违规情况不明确
• 内容类型与所有已知模式均不匹配
• 评分标准之间存在冲突

---

章程对齐：v4.0.1，重点包括：

• 原则 1：规格优先（“规格就是新的语法”）
• 第 IIa 节：Panaversity 四层教学法
• 第 IIb 节：AI 三角色框架（双向协同学习）
• 八项基础原则：包括事实准确性、结构连贯性、复杂度渐进
• 九大支柱（第 I 节）：AI CLI、Markdown、MCP、AI 优先 IDE、跨平台、TDD、SDD、可组合技能、云原生

目的

从 6 个加权类别评估教育内容，以确保：

• 技术准确性和代码质量
• 有效的教学设计和学习成果
• 面向目标受众的清晰易懂的写作
• 恰当的结构和组织
• AI 增强学习原则（与 AI 一起学习，而非让 AI 生成内容）
• 符合章程和标准

何时使用此技能

请在多个检查点调用此评估框架：

1. 迭代起草期间 - 在中途进行质量检查，及早发现问题
2. 课程／章节完成后 - 在进入下一个内容单元前进行全面评估
3. 按需评审请求 - 用户明确要求质量评估时
4. 验证阶段之前 - 作为 SDD 验证阶段工作流的一部分，用于最终签核

评估方法

评分体系

多级评估：

• 优秀（90-100%） - 超出标准，质量典范
• 良好（75-89%） - 符合所有标准，仍有小幅改进空间
• 需要改进（50-74%） - 符合部分标准，但需要进行重大修改
• 不合格（<50%） - 未达到最低标准，需要大幅返工

加权类别

评估分为 6 个类别，权重如下：

类别	权重	关注领域
技术准确性	30%	代码正确性、类型提示、说明、示例是否如所述那样有效
教学效果	25%	先展示后解释的模式、渐进式复杂度、练习质量
写作质量	20%	可读性（Flesch-Kincaid 8-10）、语气、清晰度、是否适合目标年级
结构与组织	15%	是否达到学习目标、逻辑流程、篇幅是否恰当、过渡是否自然
AI 优先教学	10%	是否展现共同学习伙伴关系、是否体现三种角色框架、是否与九大支柱保持一致、是否强调规范即语法
章程合规性	通过／不通过	必须满足所有不可协商的章程要求，包括与九大支柱保持一致（门槛条件）

加权总分计算：

Final Score = (Technical × 0.30) + (Pedagogical × 0.25) + (Writing × 0.20) +
              (Structure × 0.15) + (AI-First × 0.10)

**章程合规性：**必须达到“通过”状态。如果“不通过”，无论加权分数如何，内容都不能继续推进。

如何进行评估

第 1 步：准备上下文

评估前，请收集：

• 正在评估的内容（lesson.md、chapter.md 或章节文件）
• specs/<feature>/ 中相关的规范、计划和任务文件
• 章程文件（.specify/memory/constitution.md）
• 该内容单元的学习目标和成功标准
• 使用的输出样式模板（.claude/output-styles/lesson.md 或类似文件）

第 2 步：加载详细评分标准

阅读每个类别的详细分级标准：

Read: references/rubric-details.md

此文件包含对 6 个类别中每个类别的优秀／良好／需要改进／不合格等级的具体标准。

第 3 步：优先评估章程合规性

章程合规性是一项门槛条件——如果内容未能满足章程要求，就不能继续推进。

使用章程检查清单：

Read: references/constitution-checklist.md

评估所有不可协商的原则和要求。标记为通过或不通过，并注明具体违规项。

**如果章程合规性 = 不通过：**停止评估并立即报告违规项。继续推进前必须修改内容。

**如果章程合规性 = 通过：**继续进行加权类别评估。

第 4 步：为每个加权类别评分

对于 5 个加权类别中的每一个（技术准确性、教学效果、写作质量、结构与组织、AI 优先教学）：

1. 根据 rubric-details.md 中该类别的具体标准进行审查
2. 对照各等级的标准评估内容
3. 指定等级（优秀／良好／需要改进／不合格）并给出分数范围
4. 记录具体依据 - 引用示例、注明行号、引用具体段落
5. 提供改进建议 - 给出具体、可执行的反馈

第 5 步：计算加权分数

应用加权公式：

Final Score = (Technical × 0.30) + (Pedagogical × 0.25) + (Writing × 0.20) +
              (Structure × 0.15) + (AI-First × 0.10)

将等级分数转换为数值：

• **优秀：**95%
• **良好：**82%
• **需要改进：**62%
• **不合格：**40%

（或者在适当情况下，使用等级范围内的具体数值）

第 6 步：生成评估报告

使用结构化评估模板：

Read: references/evaluation-template.md

完成所有部分：

1. 执行摘要 - 总体得分、等级、通过/未通过状态
2. 类别得分 - 显示各类别得分、等级和权重贡献的表格
3. 详细发现 - 基于证据评估每个类别
4. 优势 - 内容做得好的方面（具体示例）
5. 待改进方面 - 按优先级列出问题并提供建议
6. 章程合规状态 - 通过/未通过，并具体检查各项原则
7. 可执行的后续步骤 - 改进内容的具体任务

第 7 步：传达结果

展示评估报告，包含：

• 明确结论 - 通过/未通过和总体质量等级
• 基于证据的反馈 - 具体引文和行号
• 按优先级排列的改进建议 - 最关键的问题优先
• 鼓励 - 肯定优点和付出的努力

评估最佳实践

客观并以证据为依据

• 引用受评估内容中的具体段落
• 注明行号或章节标题
• 根据客观评分标准进行比较，而非主观偏好
• 尽可能使用具体指标（字数、可读性评分等）

关注标准，而非追求完美

• 评级为“良好”（75-89%）的内容经过少量润色后即可发布
• 评级为“优秀”（90-100%）的内容超出标准，但并非必需
• 优先改进“有待改进”→“良好”，再考虑“良好”→“优秀”

提供可执行的反馈

• 不要只说“提升清晰度”——指出哪些句子不清楚，并建议改写方式
• 不要只说“添加示例”——建议适合补充的具体示例类型
• 按优先级排列建议：关键（阻碍发布的问题）→ 重要 → 可选

尊重学习过程

• 肯定反复改进的过程——草稿会经过多轮迭代
• 肯定进步和优点
• 以建设性的方式指出问题，将其视为成长机会
• 请记住：目标是帮助创作出优秀的教育内容，而不是设置门槛

质量门槛和阈值

最低验收阈值

• **章程合规性：**必须通过（门槛）
• **加权总分：**必须 ≥ 75%（良好或更高）
• **没有低于 50% 的类别：**每个类别至少须达到“有待改进”等级

推荐发布标准

• **章程合规性：**通过
• 加权总分：≥ 82%（良好等级）
• 技术准确性：≥ 75%（良好等级）——这是确保可信度的关键
• 教学效果：≥ 75%（良好等级）——这是确保学习成果的关键

示范级内容（可选）

• 加权总分：≥ 90%（优秀等级）
• 至少 3 个类别达到优秀等级
• 没有低于良好等级的类别

常见评估场景

场景 1：草稿中途检查（迭代）

**背景：**作者请求对部分草稿提供反馈 做法：

• 重点关注基础问题（结构、学习目标、概念铺垫）
• 尽早指出关键问题（技术错误、违反章程）
• 为剩余部分提供指导
• 不要求内容经过润色——优先确保内容完整且准确

场景 2：完成稿审查

**背景：**作者认为内容已完成，可供验证 做法：

• 对全部 6 个类别进行完整评估
• 计算最终加权得分
• 检查所有质量门槛和阈值
• 提供包含优先改进事项的完整报告
• 判断内容是否符合发布标准

场景 3：验证前质量门槛

**背景：**内容进入 SDD Validate 阶段 做法：

• 确认章程合规性（门槛）
• 确认达到最低验收阈值（≥75%）
• 验证所有类别得分均达到最低要求
• 提供有证据支持的通过/未通过建议
• 如果未通过门槛：将内容退回实施阶段，并列出具体修改任务

场景 4：按需抽查

背景： 用户针对特定章节询问“看起来怎么样？” 方法：

• 评估该章节的相关类别（可能不涵盖全部 6 个类别）
• 针对具体问题提供快速反馈
• 突出任何关键问题
• 提出改进建议，无需提供完整的正式报告
• 根据具体情况判断评估的深入程度

资源与参考资料

此技能包含详细的参考资料：

• references/rubric-details.md - 涵盖全部 6 个类别的综合分级标准，并包含具体指标
• references/constitution-checklist.md - 用于评估是否符合宪章的通过／不通过检查清单
• references/evaluation-template.md - 用于生成一致评估报告的结构化模板

评估时按需加载这些参考资料，以确保一致性和全面性。

---

评估流程示例

用户请求：“请评估这份课程草稿：apps/learn-app/docs/chapter-3/lesson-2.md”

评估流程：

1. 阅读内容： apps/learn-app/docs/chapter-3/lesson-2.md
2. 加载上下文： 规范、计划、宪章、学习目标
3. 检查是否符合宪章： references/constitution-checklist.md
   • 结果：通过（符合所有不可妥协的要求）
4. 加载详细评分标准： references/rubric-details.md
5. 评估每个类别：
   • 技术准确性：良好（80%）——代码可运行，但类型提示略有不足
   • 教学效果：优秀（92%）——循序渐进的引导很出色，练习设计也很好
   • 写作质量：良好（78%）——表达清晰，仍有一些可提升可读性的地方
   • 结构与组织：良好（85%）——流程合理，满足所有学习目标
   • AI 优先教学：有待改进（65%）——包含 AI 练习，但指导较弱
6. 计算加权得分：
   • (80×0.30) + (92×0.25) + (78×0.20) + (85×0.15) + (65×0.10) = 81.55%
   • 最终等级：良好（81.55%）
7. 加载模板： references/evaluation-template.md
8. 生成报告，列出发现、优势、改进建议和后续步骤
9. 传达结论：“良好（81.55%）——稍作改进 AI 优先教学部分后即可发布”

---

使用此技能，为所有教育内容保持一致、客观且基于证据的质量标准。