syllabus

教学大纲 — 课程补充阅读清单

可移植性： 需要连接 Consensus MCP、安装了 docx 包的 Node.js，以及读取教学大纲文件的能力。可在 Claude Code CLI 中原生运行。在 Claude.ai 中搭配 Consensus MCP、Code Execution 和文件上传，也支持此工作流。

对于持有课程教学大纲的教师或学生，为每个课程单元制作一份专业的 .docx 补充阅读清单，其中包含近期经过同行评审的论文。

架构模式：捆绑脚本

此技能使用捆绑的 JavaScript 辅助脚本生成 DOCX，而不是将 300 多行布局代码内联：

• DOCX 生成逻辑可复用且复杂
• 更好地分离职责：技能负责编排和智能处理；脚本负责机械化的文档组装
• 节省令牌：技能无需在每次运行时重新推导布局
• 更易于维护和管理版本

捆绑脚本位于 scripts/generate_reading_list.js。技能负责编排工作流，并调用脚本，输入为 JSON。

Agent 完整性规则（Research-Pack 约定）

根据 PR #657 审计要求，逐字锁定。

• 只使用 Consensus 返回的内容。 每篇论文的标题、作者、期刊、年份和 URL 都必须来自本次会话的工具调用。标记为 [Not from Consensus — model knowledge] 的训练知识论文不得使用。
• 确认后再继续。 收到并检查响应之前，搜索都不算完成。
• 记录三项数量。 已发送的查询数／收到的论文数／引用的论文数。在审计摘要中列出。
• 指出缺口，不要填补。 只有一篇论文的单元，加上结果有限的说明，胜过用编造的论文凑数。

阶段 0：问答式信息收集（3 个必答问题）

Q1（根问题）— 教学大纲输入

提供教学大纲 — 请选择一项：

1. 文件路径（PDF、DOCX、文本）——我来读取
2. 粘贴内容——在下方粘贴
3. 教学大纲的打印版图片——附上图片

我这样询问的原因： 每种格式都需要不同的读取器（PDF／DOCX 解析器／视觉识别）。提前选择可避免无谓的尝试。

必须做出选择。未提供教学大纲时不得开始。

Q2（取决于 Q1）— 课程受众

课程受众 — 请选择一项：

1. 本科（入门级）
2. 本科（高级／高年级）
3. 研究生（硕士／博士早期阶段）
4. 研究生（博士阶段／高级）
5. 专业人士／继续教育
6. 混合受众

我这样询问的原因： 受众决定摘要的术语难度和讨论问题的复杂程度。本科生摘要会解释每个术语；研究生摘要则默认读者具备技术知识。本科生的讨论问题侧重分析能力；研究生的讨论问题侧重批判和拓展能力。

规范说明见 references/audience_calibration.md。

Q3（取决于 Q1）— 年份范围

论文年份范围 — 请选择一项：

1. 最近 1 年（仅限最新论文）
2. 最近 2 年（默认值——近期论文加上一年的背景资料）
3. 最近 5 年（范围更广，包含近期的基础性研究）

我这样询问的原因： 阅读清单很快就会过时。1 年的筛选范围可保持内容新鲜；5 年的筛选范围则会呈现已经成为标准的近期基础性研究。此选择将决定每次 Consensus 搜索的 year_min 参数。

必须做出选择，默认值为最近 2 年。

停止条件： 进入阶段 1 前最多提出 3 个问题。阶段 2 之后的分组并确认环节是另一个独立的信息收集步骤。

阶段 1：解析教学大纲

根据 Q1 选择的输入格式：

• PDF：使用 PDF 阅读器；提取文本
• DOCX：使用 pandoc 或 DOCX 解析器；提取文本
• 文本／粘贴内容：直接读取
• 图片：使用视觉识别；提取文本

从提取的文本中获取：

1. 课程名称＋教师＋学期
2. 主题列表（讲座标题、每周安排等）
3. 学习成果（如有明确说明；如缺失，则根据课程描述推断 3–5 项）

在 DOCX 中，将推断出的学习成果标记为 [inferred]。

阶段 2：对主题分组并向用户确认

使用 topic_grouper.py 分组

使用 scripts/topic_grouper.py 将相关主题归为 6-12 个章节。启发式规则：密切相关的主题合并；跨领域主题单独成章。

分组并确认检查点（强制选项）

分组后，展示：

拟定章节：[列表及各章条目数]。请选择一项：

1. “看起来不错——按这些章节继续”
2. “合并章节 [X] 和 [Y]”
3. “将章节 [X] 拆分为两章”
4. “新增一个关于 [topic] 的章节”
5. “移除章节 [X]”

询问原因： 分组决定搜索资源的分配。分组不当会让搜索预算浪费在错误的主题簇上。在搜索消耗 Consensus 调用之前，这是最后一个低成本的调整时机。

未经用户明确选择，不要开始阶段 3。

阶段 3：按章节使用 Consensus 搜索

依次执行，每秒 1 个查询。每章 1-2 个查询。

融入应用领域（关键）

不要只搜索主题——要搜索主题 + 应用领域：

❌ 泛泛搜索	✅ 融入应用领域
"enzyme kinetics"	"enzyme kinetics food processing applications"
"machine learning"	"machine learning clinical decision support"
"thermodynamics"	"thermodynamics renewable energy systems"
"social network analysis"	"social network analysis public health interventions"

这能大幅提升论文的相关性。规范请参阅 references/applied_domain_weaving.md。

每章搜索模式

For each section:
  1. Construct query: "{topic-keywords} {applied-domain-angle}" + year_min from Q3
  2. Submit to Consensus (sequential, 1 q/sec gap enforced by citation_tracker)
  3. Receive results
  4. (If thin) submit one fallback query without applied-domain angle
  5. Select 1-3 papers per section (15-25 total across all sections)

筛选优先级

1. 相关性——论文直接讨论该章节主题
2. 综述 / 元分析——综合该领域研究
3. 引用次数——具有较高认可度的研究
4. 应用领域关联——与课程领域相关（例如工程，而非理论）

阶段 4：撰写摘要和讨论问题

撰写摘要

每篇论文：

• 使用通俗易懂的语言（根据 Q2 中的受众水平调整）
• 2-3 句
• 如果受众为本科生，则解释术语；如果受众为研究生，则默认其已掌握相关知识

质量标准

✅ 好的摘要	❌ 不好的摘要
“这篇综述梳理了不同饮食——地中海饮食、北欧饮食、素食——如何改变血液中循环的脂肪分子类型，以及这对心脏病风险的影响。”	“本文综述了不同饮食干预下的脂质组学特征及其对心脏代谢的影响。”

撰写讨论问题

每篇论文：

• 使用布鲁姆分类法的高阶思维（应用 / 分析 / 评价）
• 与具体的课程学习成果相关
• 促进讨论，而不只是考查记忆

✅ 好的问题	❌ 不好的问题
“如果膳食脂肪的质量能够改变你的脂蛋白脂质组，这对膳食指南建议选择不饱和脂肪而非饱和脂肪的生化依据有何启示？”	“作者发现了什么？”（仅考查记忆）

使用 scripts/discussion_question_validator.py 标记仅考查记忆的问题。

阶段 5：使用随附脚本生成 .docx

node scripts/generate_reading_list.js \
  --input /tmp/syllabus_data.json \
  --output /path/to/reading_list_<course>_<date>.docx

脚本接受符合以下架构的 JSON：

{
  "courseTitle": "string",
  "courseSubtitle": "string",
  "generatedDate": "string",
  "yearRange": "string",
  "introText": "string",
  "learningOutcomes": ["string", ...],
  "sections": [
    {
      "heading": "string",
      "papers": [
        {
          "title": "string",
          "authors": "string",
          "journal": "string",
          "year": number,
          "url": "string",
          "summary": "string",
          "question": "string"
        }
      ]
    }
  ],
  "auditLog": {
    "totalQueriesSent": number,
    "totalPapersReceived": number,
    "totalPapersCited": number,
    "toolConstraints": "string",
    "searchDetails": [
      {
        "section": "string",
        "query": "string",
        "papersReturned": number,
        "papersSelected": number,
        "status": "string"
      }
    ],
    "failures": []
  }
}

脚本会处理：

• docx 包的 require，并在多个位置进行回退查找
• 标题页、含 Consensus 链接的引言、学习成果框，以及各章节中的编号论文
• 使用完整 Consensus URL 的 ExternalHyperlink（绝不截断）
• 列表使用 LevelFormat.BULLET（不使用 Unicode 项目符号）
• 包含生成元数据的页脚
• 输入验证（缺少字段时优雅报错）

关于选择随附脚本而非内联脚本的原因，请参阅 references/bundled_script_pattern.md。

阶段 6：交付

• 文件路径
• 在聊天中提供审计摘要：“已保存 {file}。{N} 个章节 × 每章 {M} 篇论文 / 共引用 {K} 篇。套餐级别：{tier}。”
• 验证：使用 python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" <docx> 检查 ZIP 完整性（无输出表示完整），然后确认必需的章节均已包含

工具

脚本	作用
scripts/citation_tracker.py	Consensus 三次计数审计 + 在 ~/.syllabus_sessions/<session>.json 中按 1 秒间隔依次执行
scripts/topic_grouper.py	根据提取的主题，通过启发式方法将内容分为 6-12 个部分
scripts/discussion_question_validator.py	Bloom 高阶质量检查；标记仅考查记忆的问题
scripts/generate_reading_list.js	打包的 Node.js DOCX 生成器 — JSON 输入 → .docx 输出

参考资料

• references/applied_domain_weaving.md — 搜索质量准则（7+ 个来源）
• references/audience_calibration.md — 面向本科生与研究生的摘要术语校准（7+ 个来源）
• references/bundled_script_pattern.md — 为何选择打包而非内联（7+ 个来源）

错误处理

失败情况	处理方式
Consensus 命中速率限制	等待 3 秒，重试一次并记录日志
某个部分的搜索结果为 0	将该部分标注为“结果有限 — 考虑手动补充”
连续失败 3 次	停止，提醒用户，并分享目前收集到的内容
未安装 docx 包	脚本尝试运行 npm install；若仍然失败，则给出明确错误消息
DOCX 验证失败	解压 XML，记录问题，并请用户重试
不支持课程大纲格式	列出支持的格式，并请用户转换
无法提取学习成果	根据课程简介推断 3-5 项；在文档中标注为推断内容

应拒绝的反模式

• 并行调用 Consensus（会触发速率限制）
• 搜索主题时不结合应用领域角度（相关性较差）
• Consensus 返回结果较少时，用编造的条目凑数
• 提出泛泛的讨论问题（“作者发现了什么？”）
• 使用不适合课程受众水平、充斥术语的摘要
• 跳过分组并确认的步骤（会浪费搜索次数）
• 截断超链接中的 Consensus URL
• 在技能正文中内联 300 行 DOCX 生成 JavaScript（应使用打包脚本）

---

版本： 1.0.0 源规范： megaprompts/10-syllabus-megaprompt.md（维护者本地草稿规范 — 已加入 gitignore，未包含在公开代码库中） 构建模式： 路径 B（直接转换）。打包的 JavaScript DOCX 生成器变体。