assessment-architect

评估设计师 - 概念优先的认证考试

先提取概念，再根据概念图构建基于场景的问题，以生成严谨的认证考试。

输出： assessments/ 目录中的 DOCX
不适用于： 练习测验（这些测验使用章节目录中的 *_quiz.md）

---

操作约定（不可妥协）

这些规则属于结构性要求，不得覆盖：

1. 不得出记忆题。 每道题都必须在题干前提供一个全新的场景段落。测试对课程专属事实记忆的问题将被拒绝。
2. 先写依据说明，再提取概念。 阅读课程内容 → 编写说明文件 → 从说明中提取概念。切勿凭记忆提取概念。说明文件是参与过程的依据。
3. 先有概念，再出题。 概念图（根据说明构建）是第 2 阶段的依据。切勿按课程内容的顺序逐一生成问题。
4. 仅通过文件系统发现。 不得硬编码书籍结构。使用 ls -d 查找路径。文件系统是事实依据。
5. 结构验证。 反记忆题（grep 模式）和反投机取巧（分布偏差）检查不通过即视为失败。可读性是一项原则，不是字数门槛。
6. 按重要性加权题目数量。 核心课程内容出 3-5 道题，辅助内容出 1-2 道，导论内容出 0-1 道。不得简单地“每节 2 题”，而应按重要性加权。
7. 使用 TaskList 进行协作。 提前创建任务。在每个阶段更新状态。子代理需接收 TaskList ID。
8. 最多使用 2 个子代理。 每个子代理仅接收概念图和 references/question-types.md，不得接收完整技能文件。
9. 持久化状态。 将说明、概念图和问题文件保存到 assessments/。在每个阶段报告验证结果。

---

输入解析（通过 $ARGUMENTS）

INPUT = $ARGUMENTS (e.g., "ch 5", "part 3", "ch 2, 3, 4", "ch 2-4")

PARSE:
  IF matches "ch N, N, N" | "chapter N, N and N" (comma/and-separated list):
    SCOPE = "multi-chapter"
    NUMS = extract all numbers → zero-pad each
    FOR each NUM: PATH[] += ls -d apps/learn-app/docs/*/$(printf '%02d' NUM)-*/

  ELSE IF matches "ch N-M" | "chapter N-M" (range):
    SCOPE = "multi-chapter"
    FOR NUM in N..M: PATH[] += ls -d apps/learn-app/docs/*/$(printf '%02d' NUM)-*/

  ELSE IF matches "ch N" | "chapter N" (single):
    SCOPE = "chapter"
    NUM = zero-pad N to 2 digits
    PATH = result of: ls -d apps/learn-app/docs/*/$(printf '%02d' N)-*/

  ELSE IF matches "part N" | "p N" | "pN":
    SCOPE = "part"
    NUM = zero-pad N to 2 digits
    PATH = result of: ls -d apps/learn-app/docs/$(printf '%02d' N)-*/

  ELSE IF bare number:
    AskUserQuestion: "Did you mean Chapter {N} or Part {N}?"

  ELSE IF empty:
    AskUserQuestion: "Which chapter or part? (e.g., 'ch 5' or 'part 3')"

VALIDATE:
  FOR each path: run ls -d. If no result: FAIL "Path not found"

DISCOVER LESSONS:
  FOR each PATH (single or multi):
    LESSONS += ls {PATH}/*.md | grep -v README | grep -v summary | grep -v quiz
  LESSON_COUNT = total across all paths

CONFIRM with user (AskUserQuestion):
  "Found {SCOPE}: {chapter names and numbers}
   Path(s): {paths}
   Total lessons: {LESSON_COUNT}
   Proceed?"

---

任务协调

确认范围后，创建 TaskList 来跟踪进度并协调子代理：

TaskCreate: "Discover scope and confirm with user" → mark in_progress immediately
TaskCreate: "Explore curriculum context (Part/Chapter READMEs)" (blocked by task 1)  ← NEW
TaskCreate: "Calculate chapter importance weights" (blocked by task 2)  ← NEW
TaskCreate: "Read lessons and write grounding notes" (blocked by task 3)
TaskCreate: "Extract concept map from grounding notes" (blocked by task 4)
TaskCreate: "Calculate question distribution and confirm" (blocked by task 5)
TaskCreate: "Generate questions - Subagent A (Scenario + Transfer)" (blocked by task 6)
TaskCreate: "Generate questions - Subagent B (Relationship + Evaluation)" (blocked by task 6)
TaskCreate: "Validate all questions" (blocked by tasks 7, 8)
TaskCreate: "Assemble exam and generate DOCX" (blocked by task 9)

随着工作进展更新每项任务的状态。子代理会收到 TaskList ID，以便在完成时更新各自任务的状态。

---

阶段 0：课程背景发现（必须 - 新增）

重要：必须先完成此阶段，才能阅读各个课程内容。

该技能此前因仅根据课程数量计算问题分布而失败。一章包含 12 节“Markdown 语法”课程，不应与一章包含 12 节“核心 Agent 架构”课程权重相同。

步骤 1：阅读 Part README

# For part scope: read the part's README directly
cat {PART_PATH}/README.md

# For chapter scope: find and read the parent part's README
PART_PATH=$(dirname {CHAPTER_PATH})
cat ${PART_PATH}/README.md

从 Part README 中提取：

• 书籍/Part 学习目标（“你将学到什么”部分）
• 章节说明及其标明的作用
• 此 Part 的总体目标/论点

步骤 2：按课程作用分类各章

对于范围内的每一章，确定其在课程体系中的作用：

CHAPTER_ROLE classification:

  "core-practical"  → Teaches the PRIMARY skills of this part
                      Signals: "You'll master...", hands-on tool usage,
                      the largest chapter, most learning objectives point here
                      Weight: HIGH (30-40% of questions if single chapter dominates)

  "core-conceptual" → Teaches foundational concepts that enable practical skills
                      Signals: principles, frameworks, mental models,
                      "understand WHY" language, synthesis chapters
                      Weight: HIGH (20-30%)

  "supporting"      → Provides necessary context or secondary skills
                      Signals: "before you can...", setup, configuration,
                      enabling skills, smaller learning objective footprint
                      Weight: MEDIUM (10-20%)

  "prerequisite"    → Teaches format/syntax/basics assumed by other chapters
                      Signals: Markdown syntax, installation, environment setup,
                      not mentioned in part learning objectives
                      Weight: LOW (2-5% or exclude entirely)

步骤 3：计算章节重要性权重

公式：根据作用和学习目标覆盖范围加权

FOR each chapter:
  role_weight = {
    "core-practical": 35,
    "core-conceptual": 25,
    "supporting": 15,
    "prerequisite": 3
  }[chapter_role]

  # Adjust by learning objective coverage
  objectives_mentioning_chapter = count of Part learning objectives
    that specifically reference this chapter's topics
  objective_boost = objectives_mentioning_chapter * 5

  raw_weight = role_weight + objective_boost

NORMALIZE weights to sum to 100%

OUTPUT: chapter_weights = { ch1: X%, ch2: Y%, ... }

步骤 4：报告并确认

在阅读课程内容之前，先向用户展示：

## Curriculum Analysis

**Part Goal:** {thesis from README}

| Chapter | Lessons | Role | Weight | Rationale |
|---------|---------|------|--------|-----------|
| Ch 3: General Agents | 52 | core-practical | 35% | Primary hands-on chapter |
| Ch 6: Seven Principles | 20 | core-conceptual | 20% | Synthesis chapter |
| Ch 4: Context Engineering | 22 | core-conceptual | 20% | Quality discipline |
| Ch 1: Agent Factory | 22 | supporting | 15% | Foundational concepts |
| Ch 5: SDD | 10 | supporting | 8% | Methodology |
| Ch 2: Markdown | 12 | prerequisite | 2% | Format only |

**Proposed question distribution (150 total):**
- Ch 3: 52 questions
- Ch 6: 30 questions
- Ch 4: 30 questions
- Ch 1: 23 questions
- Ch 5: 12 questions
- Ch 2: 3 questions

Proceed with this weighting?

用户可以在开始阅读课程内容前调整权重。

这为何重要

不执行阶段 0	执行阶段 0
第 2 章（Markdown）有 12 节 × 2 = 24 道题	第 2 章占 2% = 3 道题
由课程数量决定分布	由书籍目标决定分布
辅助章节权重过高	核心章节优先级得到恰当体现
先修技能被大量测试	先修内容仅少量测试

---

笔记记录（强制要求）

阅读每节课程时，将观察记录到 assessments/{SLUG}-notes.md。此文件是你的工作记忆，也是你认真学习内容的证明。

格式（每节课程追加）：

## Lesson: {filename}

**Weight:** {core | supporting | intro}
**Key concepts:** {2-5 concepts worth testing}
**Relationships to other lessons:** {what connects to what}
**Testable trade-offs:** {decisions or comparisons in this lesson}
**Transfer potential:** {where else this principle applies}
**Surprise/insight:** {anything non-obvious that would make a good question}

规则：

• 阅读时记录笔记，不要等读完所有课程后再写
• 此文件是概念提取的原始输入（Phase 1 读取笔记，而非记忆）
• 概念图必须引用具体的笔记条目作为证据
• 如果概念图中的概念没有对应的笔记，就是捏造的，应将其删除

---

4 种题型（自适应分布）

所有题目都必须在题干前提供简洁的情境。不得采用事实回忆式题型。

类型	布鲁姆层级	关键约束
情境分析	应用／分析	使用课程中未出现过的新情境
概念关系	分析／评价	检验 2 个或更多概念之间的联系
迁移应用	应用／创造	将原理应用到本章未涉及的领域
批判性评估	评价	结合情境，判断某种方法为何会失败

分布根据章节类型调整（在 Phase 0.5 中分类）：

PRACTICAL-TOOL chapters (e.g., Claude Code CLI, Docker, FastAPI):
  Scenario Analysis:     60%  (realistic usage scenarios in the tool's domain)
  Concept Relationship:  20%  (how tool components interact)
  Transfer Application:   5%  (minimal — stay in the tool's domain)
  Critical Evaluation:   15%  (identify why an approach fails with this tool)

CONCEPTUAL chapters (e.g., Seven Principles, Architecture Patterns):
  Scenario Analysis:     35%  (apply principle to realistic situations)
  Concept Relationship:  25%  (how principles connect and interact)
  Transfer Application:  25%  (appropriate — abstract principles transfer broadly)
  Critical Evaluation:   15%  (evaluate when a principle is misapplied)

HYBRID chapters:
  Interpolate between practical-tool and conceptual based on lesson mix.
  Count practical vs conceptual lessons, weight accordingly.
  Example: 60% practical lessons → use 80% of practical distribution + 20% of conceptual.

理由： 实用工具类章节应检验学生能否在真实情境中使用工具，而非将原理迁移到无关领域。概念类章节则应检验学生能否广泛应用原理。

详细模式和示例请参阅 references/question-types.md。

可读性原则

难点在于思考，而非阅读。

使用清晰、专业的表达。每句话只表达一个观点。使用主动语态。避免填充内容。Agent 可完全自主决定字数——原则是表达清晰，而非遵循特定字数要求。

选项长度一致（强制要求）

每道题的所有四个选项都必须长度相近。

规则： 每个选项的词数必须在该题选项平均长度的 0.8 至 1.2 倍之间。如果正确答案的长度为 1.0 倍，所有干扰项都必须在 0.8 至 1.2 倍之间。

重要性： 如果正确答案平均有 22.7 个词，而干扰项平均只有 9.4 个词（比例为 2.42 倍），学生不读题就能通过选择最长选项猜对答案。这会使评估失效。

“先写答案，再匹配长度”流程：

1. 先写正确答案（自然地提供足够细节）
2. 统计词数
3. 将每个干扰项写到相同词数（±20%）
4. 如果干扰项太短，就补充合理但错误的细节
5. 如果正确答案太长，就简化它，然后扩展干扰项，使其长度相匹配

错误（长度偏差——学生会选最长的）：

**A.** Reduce involvement to autocomplete only
**B.** Switch to a more capable model
**C.** Write detailed specifications for each function and validate the AI's complete output against them
**D.** Continue until the AI learns her style

（C 有 15 个词，其他选项只有 5 至 8 个。正确答案从长度上就显而易见。）

正确（所有选项长度相近，难点在于思考）：

**A.** Limit the AI to autocomplete mode and manually write the rest of each function
**B.** Replace the current model with a higher-tier one that produces cleaner code output
**C.** Write detailed specifications first and validate the AI's complete output against them
**D.** Continue the current workflow and wait for the AI to adapt to her coding patterns

（所有选项都有 14 至 17 个词。必须真正理解概念才能作答。）

错误（情境冗长——Agent 绝不能这样写）：

Q. A veteran meteorologist notices that her department's new AI weather
prediction system presents 48-hour forecasts with identical confidence
formatting regardless of actual prediction reliability...

正确（表达清晰，考查相同概念）：

Q. A weather AI displays all forecasts with equal confidence — a risky
tropical storm prediction looks identical to a reliable clear-sky forecast.
Junior staff stopped questioning AI outputs.

How should the team handle AI outputs that show no uncertainty signal?

**A.** Verify all AI forecasts against independent sources before publishing

考查相同概念，难度相同。正确版本只是更清晰，因为没有填充内容。

---

动态题目数量（两级加权）

题目分布采用两级加权：

1. 章节级权重（来自 Phase 0 的课程分析）
2. 课程级权重（在每章内部）

第 1 级：章节权重（来自 Phase 0）

在阅读课程之前，通过课程分析确定章节权重：

• 在全书目标中的作用（核心实用、核心概念、辅助、先修）
• 学习目标覆盖情况
• 用户确认

这些权重决定每章在总题数中所占的百分比。

第 2 级：课程权重（在章节内部）

在 Phase 0.5（阅读课程）期间，为每节课程添加标签：

LESSON_WEIGHT:
  "core"       → Teaches a key capability or central concept (3-5 questions)
                 Signals: new tools, complex workflows, architectural patterns, capstone integration
  "supporting" → Provides context, setup, or secondary skills (1-2 questions)
                 Signals: configuration, secondary features, examples of core concepts
  "intro"      → Opening, overview, or minimal-content lesson (0-1 questions)
                 Signals: motivational content, history, "what you'll learn", installation-only

计算题目总数

tier_multiplier:
  T1 (Introductory) = 0.7
  T2 (Intermediate) = 1.0  [default]
  T3 (Advanced)     = 1.3

total_lessons = sum of lessons across all chapters
concept_count = total concepts extracted

base = max(ceil(concept_count * 0.8), total_lessons * 1.5)
raw = base * tier_multiplier
TOTAL = clamp(round_to_nearest_5(raw), min=30, max=150)

将题目分配到各章

应用 Phase 0 章节权重：

FOR each chapter:
  chapter_questions = round(TOTAL * chapter_weight_percent)

VALIDATE: sum of chapter_questions == TOTAL (adjust rounding as needed)

在各章内分配题目

在每章的题目分配中应用课程权重：

FOR each chapter:
  weighted_sum = sum of lesson weights (core=5, supporting=2, intro=1)

  FOR each lesson in chapter:
    lesson_proportion = lesson_weight / weighted_sum
    lesson_questions = round(chapter_questions * lesson_proportion)

示例：包含 6 章的部分

Phase 0 determined chapter weights:
  Ch 3: 35% (core-practical, 52 lessons)
  Ch 4: 20% (core-conceptual, 22 lessons)
  Ch 6: 20% (core-conceptual, 20 lessons)
  Ch 1: 15% (supporting, 22 lessons)
  Ch 5: 8%  (supporting, 10 lessons)
  Ch 2: 2%  (prerequisite, 12 lessons)

Total = 150 questions (T2)

Chapter allocation:
  Ch 3: 150 * 0.35 = 52 questions
  Ch 4: 150 * 0.20 = 30 questions
  Ch 6: 150 * 0.20 = 30 questions
  Ch 1: 150 * 0.15 = 23 questions
  Ch 5: 150 * 0.08 = 12 questions
  Ch 2: 150 * 0.02 = 3 questions

Within Ch 2 (3 questions for 12 lessons):
  - 2 core lessons get 1 question each
  - 10 intro/supporting lessons get 0-1 questions
  - Total: 3 questions (matches chapter allocation)

向用户展示建议，同时提供章节级和课程级的细分。用户可以在任一层级进行调整。

---

5 阶段工作流

Phase 0 → 课程背景探索（了解书籍目标） Phase 0.5 → 阅读课程并撰写背景记录 Phase 1 → 提取概念 Phase 2 → 生成题目（2 个并行子 Agent） Phase 3 → 验证 Phase 4 → 汇总并输出 DOCX

---

Phase 0.5：阅读课程、对章节分类并撰写背景记录（本 Agent）

前提：必须先确认 Phase 0 章节权重，才能进入本阶段。

阅读范围内的所有课程。阅读每个课程时，将观察结果追加到 assessments/{SLUG}-notes.md（参见上文“背景记录”部分）。

此步骤不可省略。记录文件是你确实阅读并理解内容的证据。Phase 1 将根据记录文件构建概念图，而不是凭记忆构建。

阅读完所有课程后，对章节类型进行分类：

CHAPTER_TYPE classification (determine from lesson content):

  "practical-tool"  → Chapter teaches how to USE a specific tool
                      Signals: CLI commands, installation steps, configuration files,
                      code blocks with tool invocations, "run this command" patterns
                      Examples: Claude Code CLI, Docker, FastAPI, Kubernetes

  "conceptual"      → Chapter teaches principles, patterns, architecture
                      Signals: "when to use", "why", trade-off discussions,
                      design patterns, decision frameworks, no specific tool commands
                      Examples: Seven Principles, General Agent Architecture, Design Patterns

  "hybrid"          → Mix of tool-usage and principle lessons
                      Signals: some lessons are hands-on tool usage,
                      others are conceptual/architectural
                      Examples: MCP (concept + implementation), Agent Skills (concept + creation)

从课程内容中提取领域关键词（本章所教的具体工具、技术和工作流）。这些关键词将限定 Phase 2 中场景生成的范围。

将分类结果和关键词写入记录文件顶部：

# Chapter Classification

- Type: {practical-tool | conceptual | hybrid}
- Domain keywords: {comma-separated list of specific terms from the chapter}
- Example domains for scenarios: {2-3 example settings appropriate for this chapter}

更新任务状态：将“阅读课程并撰写背景记录”标记为 in_progress，然后标记为 completed。

---

Phase 1：提取概念（本 Agent）

阅读 assessments/{SLUG}-notes.md（你的背景记录）。根据记录提取概念，而不是凭记忆提取。

需要提取的内容（详情参见 references/concept-extraction-guide.md）：

• 核心概念（命名的想法、模式、原则）
• 关系（概念 A 能够促成、冲突或扩展概念 B）
• 权衡（选择 X 意味着牺牲 Y）
• 迁移领域（该原则还可以应用于哪些领域？）

每个概念都必须引用一条背景记录。 如果无法指明具体记录条目，该概念就是捏造的。

**输出：**写入 assessments/{SLUG}-concepts.md

格式：

# Concept Map: {Chapter/Part Name}

## Concepts (N total)

### 1. {Concept Name}

- Definition: {1-2 sentences}
- Lessons: {which lessons cover this}
- Relationships: {connects to concepts X, Y}
- Transfer domains: {healthcare, finance, education, etc.}

### 2. {Concept Name}

...

## Relationships

- {Concept A} --enables--> {Concept B}
- {Concept C} --conflicts-with--> {Concept D}
  ...

## Trade-offs

- {Choosing X} vs {Choosing Y}: {what you sacrifice}
  ...

提取完成后：

1. 汇报课程权重细分（核心／辅助／入门课程数量）
2. 汇报概念数量，并根据上文的重要性加权算法建议题目数量
3. 汇报检测到的章节类型所对应的自适应类型分布
4. 请用户确认或调整题目数量
5. 询问用户选择难度等级（T1/T2/T3，默认为 T2）

---

Phase 2：生成题目（2 个并行 Task 子 Agent）

启动 2 个 Task 子 Agent。每个子 Agent 仅接收：

• 概念图（assessments/{SLUG}-concepts.md）
• 题目类型参考（references/question-types.md）
• 章节类型和领域关键词（来自记录文件中的分类）
• 分配给它们的题型和数量

提示模板参见 references/subagent-template.md。

**子 Agent A：**场景分析 + 迁移应用题

• 输出：assessments/{SLUG}-questions-A.md
• 数量：总数的（场景题比例 + 迁移题比例），因章节类型而异：
  • 实用工具型：总数的 65%（60% 场景题 + 5% 迁移题）
  • 概念型：总数的 60%（35% 场景题 + 25% 迁移题）
  • 混合型：按比例插值

**子 Agent B：**概念关系 + 批判性评估题

• 输出：assessments/{SLUG}-questions-B.md
• 数量：总数的（关系题比例 + 评估题比例），因章节类型而异：
  • 实用工具型：总数的 35%（20% 关系题 + 15% 评估题）
  • 概念型：总数的 40%（25% 关系题 + 15% 评估题）
  • 混合型：按比例插值

---

阶段 3：验证（此 Agent）

阅读两个问题文件。应用所有结构检查：

失败条件（拒绝问题，不可协商）：

FAIL if question contains "According to"
FAIL if question contains "Lesson [0-9]" or "lesson [0-9]"
FAIL if question contains "the document states" or "as discussed in"
FAIL if question has NO scenario paragraph before the stem
FAIL if Transfer Application domain appears anywhere in chapter content
FAIL if question doesn't map to a concept in the concept map

反作弊检查（失败条件）：

# Length Parity (CRITICAL — per-question ratio check)
FOR each question:
  mean_length = mean word count of all 4 options
  FOR each option:
    ratio = option_word_count / mean_length
    FAIL if ratio < 0.8 or ratio > 1.2
      → "Q{N}: Option {letter} is {ratio}x mean ({words} words vs {mean} mean)"
FAIL if >15% of questions have any option outside 0.8x-1.2x range (batch-level)

# Position Bias
FAIL if any letter is correct >30% or <20% of total
FAIL if middle (B+C) > 55% of correct answers
FAIL if outer (A+D) < 40% of correct answers
FAIL if >3 consecutive questions have same correct letter

# Specificity Bias (see references/bias-detection-guide.md)
WARN if correct answer specificity score > 30% higher than distractor average
FLAG questions where correct option has examples/qualifiers that distractors lack

分布检查：

Count answer distribution across all questions:
  Each of A/B/C/D must be 20-30% of total
  No >3 consecutive same-letter answers

覆盖率检查：

Each concept in the map should have at least 1 question
  Flag uncovered concepts (warning, not failure)
  Report: "X of Y concepts covered (Z%)"

如果验证失败：

• 按问题编号报告具体失败项
• 指出模式（例如：“子 Agent A 生成了 12 个包含‘According to’的问题”）
• 仅重新生成失败子 Agent 的输出（重新启动该子 Agent）

完整验证流程请参阅 references/validation-rules.md。

---

阶段 4：组卷与 DOCX 输出（本 Agent）

步骤 1：合并并移除内部标签

• 交错排列两个文件中的问题（不要按类型分组）
• 按顺序重新编号为 Q1 至 Q{TOTAL}
• 随机调整答案位置（确保分布均衡）
• 从面向学生的问题中移除所有内部标签：

  REMOVE: [Scenario Analysis], [Concept Relationship], [Transfer Application], [Critical Evaluation]
  REMOVE: [Concept: {anything}]
  REMOVE: **Answer:** lines (answers go ONLY in answer key)
  REMOVE: **Reasoning:** sections (go ONLY in educator supplement)
  

• 移除后的验证：

  grep -E "\[(Scenario|Concept|Transfer|Critical)" assessments/{SLUG}-exam.md
  → MUST return 0 matches in the questions section
  

步骤 2：构建考试文档（两个独立文件）

文件 1：学生试卷（assessments/{SLUG}-exam.md）

# {Chapter/Part Name} Certification Assessment

**Questions:** {TOTAL}
**Time Limit:** {ceil(TOTAL \* 1.5)} minutes
**Passing Score:** 75%

**Instructions:** Select the best answer for each question.

---

Q1. {scenario paragraph}

{stem ending in ?}

**A.** {option}

**B.** {option}

**C.** {option}

**D.** {option}

---

Q2. ...

不要标注类型。不要添加概念标签。不要提供答案。不要提供解释。仅包含问题。

文件 2：教师答案卷（assessments/{SLUG}-answer-key.md）

# Answer Key: {Chapter/Part Name}

| Q   | Answer | Type                 | Concept        |
| --- | ------ | -------------------- | -------------- |
| 1   | B      | Scenario Analysis    | {concept name} |
| 2   | D      | Concept Relationship | {concept name} |

...

## Answer Distribution

A: {count} ({%}) | B: {count} ({%}) | C: {count} ({%}) | D: {count} ({%})

## Concept Coverage

{List concepts and question count per concept}

## Type Distribution

{Scenario Analysis: X | Concept Relationship: X | Transfer Application: X | Critical Evaluation: X}

重要：选项格式必须为 **A.** text（字母加句点加空格，并加粗）。 绝不要使用 A)——pandoc 会将其解读为有序列表标记，并在 DOCX 中渲染为项目符号。

步骤 3：转换为 DOCX（两个文件）

选项 A：pandoc（简单）

pandoc assessments/{SLUG}-exam.md -o assessments/{SLUG}-Assessment-Final.docx --from=markdown --to=docx
pandoc assessments/{SLUG}-answer-key.md -o assessments/{SLUG}-Answer-Key.docx --from=markdown --to=docx

选项 B：使用 docx-js 编程生成（格式控制更佳）

使用 docx-js 库生成专业 DOCX 输出时：

// CRITICAL: Paragraph alignment
// Custom paragraph styles may NOT reliably apply alignment.
// ALWAYS set alignment EXPLICITLY on each Paragraph.

// ❌ WRONG - style-based alignment may be ignored:
new Paragraph({
  style: "Question", // Even if Question style has LEFT alignment
  children: [new TextRun({ text: question.stem })],
});

// ✅ CORRECT - explicit alignment on each paragraph:
new Paragraph({
  alignment: AlignmentType.LEFT, // ALWAYS set this explicitly
  spacing: { before: 200, after: 100 },
  children: [
    new TextRun({ text: `${qNum}. `, bold: true, size: 24, font: "Arial" }),
    new TextRun({ text: question.stem, font: "Arial", size: 22 }),
  ],
});

// ✅ CORRECT - options with explicit alignment and indent:
new Paragraph({
  alignment: AlignmentType.LEFT, // ALWAYS set this explicitly
  indent: { left: 360 },
  spacing: { after: 60 },
  children: [
    new TextRun({ text: `${letter}) ${option}`, font: "Arial", size: 22 }),
  ],
});

docx-js 关键规则：

1. 始终在每个问题/答案段落上显式设置 alignment: AlignmentType.LEFT
2. 不要依赖自定义段落样式设置对齐方式
3. 在每个 TextRun 上设置 font: "Arial"，以确保渲染一致
4. 使用 indent: { left: 360 } 缩进选项（不要使用制表符或空格）

选项 C：更新现有格式化 DOCX（保留自定义格式）

如果已有采用自定义格式（字体、颜色、表格边框、底纹）的 DOCX 需要更新内容，pandoc --reference-doc 只会复制样式定义——不会保留内联格式（表格边框、单元格底纹、自定义颜色）。此时应改用 /docx 技能的 OOXML 编辑工作流。

方法：使用原文档的格式模板重建 document.xml

1. 解压原始 DOCX：

python ooxml/scripts/unpack.py original.docx /tmp/unpacked

2. 从原始 XML 中提取格式模板（读取 word/document.xml）：

   • 页眉部分（标题、副标题、带表格边框/底纹的说明框）
   • 问题段落格式（字体、字号、间距、缩进）
   • 选项段落格式（缩进、间距）
   • 章节标题格式（颜色、字号）
   • 答案卷格式（正确答案颜色、推理样式）

3. 编写 Python 脚本，以便：

   • 原样保留页眉 XML（仅更新问题数量、时间等元数据）
   • 解析更新后的 Markdown 内容
   • 使用提取的格式模板生成新的问题 XML
   • 保留原文档中的节属性（页边距、页眉/页脚）
   • 将组装好的 document.xml 写回

4. 打包结果：

python ooxml/scripts/pack.py /tmp/unpacked output.docx

关键格式模式（来自 Google Docs / Word 格式的试卷）：

<w:p><w:pPr><w:spacing w:after="40" w:before="300" w:lineRule="auto"/></w:pPr>
  <w:r><w:rPr>
    <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
    <w:b w:val="1"/><w:bCs w:val="1"/>
    <w:sz w:val="22"/><w:szCs w:val="22"/>
  </w:rPr><w:t xml:space="preserve">Question N</w:t></w:r>
</w:p>


<w:p><w:pPr><w:spacing w:after="60" w:lineRule="auto"/></w:pPr>
  <w:r><w:rPr>
    <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
    <w:sz w:val="22"/><w:szCs w:val="22"/>
  </w:rPr><w:t xml:space="preserve">Text here</w:t></w:r>
</w:p>


<w:p><w:pPr><w:spacing w:after="80" w:lineRule="auto"/><w:ind w:left="360"/></w:pPr>
  <w:r><w:rPr>
    <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
    <w:sz w:val="22"/><w:szCs w:val="22"/>
  </w:rPr><w:t xml:space="preserve">A. Option text</w:t></w:r>
</w:p>


<w:p><w:pPr><w:spacing w:after="100" w:before="600" w:lineRule="auto"/></w:pPr>
  <w:r><w:rPr>
    <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
    <w:b w:val="1"/><w:bCs w:val="1"/>
    <w:color w:val="1b3a5c"/>
    <w:sz w:val="26"/><w:szCs w:val="26"/>
  </w:rPr><w:t xml:space="preserve">CHAPTER N: TITLE</w:t></w:r>
</w:p>


<w:p><w:pPr><w:spacing w:after="60" w:before="120" w:lineRule="auto"/></w:pPr>
  <w:r><w:rPr>
    <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
    <w:b w:val="1"/><w:bCs w:val="1"/>
    <w:color w:val="1a7431"/>
    <w:sz w:val="22"/><w:szCs w:val="22"/>
  </w:rPr><w:t xml:space="preserve">Correct Answer: B</w:t></w:r>
</w:p>


<w:r><w:rPr>
  <w:rFonts w:ascii="Arial" w:cs="Arial" w:eastAsia="Arial" w:hAnsi="Arial"/>
  <w:i w:val="1"/><w:iCs w:val="1"/>
  <w:color w:val="666666"/>
  <w:sz w:val="18"/><w:szCs w:val="18"/>
</w:rPr><w:t xml:space="preserve">  [Ch1] [Scenario Analysis]</w:t></w:r>

选项 C 与选项 A/B 的适用场景：

• 选项 A（pandoc）：新试卷，无需保留现有格式
• 选项 B（docx-js）：新试卷，需要从头创建专业格式
• 选项 C（OOXML 编辑）：更新现有格式化 DOCX（例如添加问题、修正内容）

步骤 4：转换后验证

• 确认两个 DOCX 文件都存在，且试卷文件大于 10KB
• 重要：在试卷 Markdown 中搜索内部标签：

  grep -cE "\[(Scenario|Concept|Transfer|Critical)" assessments/{SLUG}-exam.md
  → MUST be 0. If not: FAIL "Internal tags leaked into student exam"
  

• 确认试卷 DOCX 中没有“Answer:”或“Reasoning:”文本
• 报告：文件路径、问题数量、概念覆盖率

步骤 5：清理（可选）

• 保留概念图（作为有用的参考）
• 保留问题文件（便于重新生成）
• 如果用户希望输出更整洁，则删除中间 Markdown 文件

---

失败模式（摘要）

失败	预防	检测
跳过课程上下文	Phase 0 为必做阶段	阅读课程前未阅读部分 README
过度侧重先修章节	对章节角色进行分类	“先修”章节的权重应为 2-5%，而非与其他章节相同
课程数量 = 问题数量	两级加权（章节 + 课程）	分布未考虑书籍学习目标
记忆型问题	结构性失败条件	搜索“According to”和“Lesson [0-9]”
长度偏差（正确选项长 2 倍以上）	逐题比例失败：所有选项都在均值的 0.8x-1.2x 范围内	逐题统计字数比例，批次超过 15% = 失败
位置偏差（选项 B/C 聚集）	反作弊失败：中间选项超过 55%	统计 B+C 与 A+D 的分布
具体程度偏差	警告：正确选项的具体程度高出 30% 以上	根据示例/限定条件为选项评分
答案偏差（74% 为 A）	反作弊失败：任何字母占比超过 30%	按字母统计分布
编造概念	必须提供依据说明	每个概念都必须引用一条笔记
问题过少	按重要性加权：核心=3-5，辅助=1-2，入门=0-1	最低数量由加权总和决定，而非固定数量
章节/部分错误	使用 ls -d 搜索文件系统	继续前验证路径
课程缺失	完整统计课程数量 + 笔记文件	笔记文件为每节课程都包含一条记录
缺乏协调	提前创建 TaskList	各阶段的任务状态清晰可见
上下文过载	子 Agent 仅接收概念图 + 类型	上下文约 300 行，而非 937 行 + 176KB
考试中包含内部标签	在 Phase 4 中删除 [Type] 和 [Concept:]	搜索 exam.md 中的方括号，结果为 0
学生文件中包含答案	分为两个独立文件（试卷 + 答案）	DOCX 试卷中不含“Answer:”
DOCX 中的项目符号	使用 **A.** 格式，绝不使用 A)	pandoc 会将 A) 视为列表标记
DOCX 格式丢失	存在已有格式的 DOCX 时使用 Option C（OOXML 编辑）	pandoc 的 --reference-doc 会丢失行内格式
替换问题后答案键未同步	替换问题时，明确更新答案键中的答案	对比新旧答案键差异，确认已更新的问题编号

有关这些失败的历史背景，请参阅 skill 的 Git 历史记录中的 2026 年 1 月事后分析。

---

参考文件

文件	用途	使用者
references/question-types.md	4 种题型定义及示例	子 Agent（阶段 2）
references/concept-extraction-guide.md	如何提取概念而非事实	此 Agent（阶段 1）
references/subagent-template.md	2 个子 Agent 的提示词模板	此 Agent（阶段 2 启动）
references/validation-rules.md	防记忆检查与分布检查	此 Agent（阶段 3）
references/bias-detection-guide.md	长度／位置／具体性偏差检测	此 Agent（阶段 3）
references/bloom-taxonomy.md	认知层级参考	子 Agent（题目设计）
references/psychometric-standards.md	DIF／DIS／DF 指标	此 Agent（阶段 3 验证）
references/distractor-generation-strategies.md	干扰项设计模式	子 Agent（选项创建）
references/academic-rigor-tiers.md	T1-T3 难度框架	此 Agent（阶段 1 层级选择）

---

可观测性（原则 7）

在每个阶段转换时报告：

Phase 0 Complete (Curriculum Context):
  - Part/Book goal: {thesis statement}
  - Chapters in scope: {N}
  - Chapter weights:
    | Chapter | Role | Weight | Questions |
    | Ch 3 | core-practical | 35% | 52 |
    | Ch 6 | core-conceptual | 20% | 30 |
    ...
  - User confirmed: {yes/adjusted to X}

Phase 0.5 Complete:
  - Chapter type: {practical-tool | conceptual | hybrid}
  - Domain keywords: {keywords}
  - Lessons: {N} total ({N} core, {N} supporting, {N} intro)
  - Notes: assessments/{SLUG}-notes.md

Phase 1 Complete:
  - Concepts extracted: {N}
  - Relationships found: {N}
  - Trade-offs identified: {N}
  - Weighted question count: {N} (T{tier})
  - Type distribution: Scenario={N}% Relationship={N}% Transfer={N}% Evaluation={N}%
  - Concept map: assessments/{SLUG}-concepts.md

Phase 2 Complete:
  - Subagent A: {N} questions generated ({types})
  - Subagent B: {N} questions generated ({types})
  - Total: {N} questions

Phase 3 Complete:
  - Validation: {PASS/FAIL}
  - Failed questions: {N} (reasons: ...)
  - Answer distribution: A={N} B={N} C={N} D={N}
  - Concept coverage: {X}/{Y} ({Z}%)

Phase 4 Complete:
  - DOCX: assessments/{SLUG}-Assessment-Final.docx
  - Size: {N}KB
  - Questions: {N}
  - Ready for distribution