chapter-lead-writer

章节主笔

触发条件与路由

• 触发词：chapter lead writer、section lead writer、H2 lead、lead paragraph、章节导读、章节导语。
• 适用场景：章节包含多个 H3 小节，且草稿读起来像是分散在各小节中的独立段落。

目的

此技能用于撰写仅包含正文的导读块，放在 H2 标题下方，让包含多个 H3 小节的章节读起来像一个连贯的论证。

此 SKILL.md 现在是软件包路由文件，而不是完整的方法手册。

迁移状态

此软件包正处于P0 兼容性优先迁移阶段：

• references/ 和 assets/ 现在承载预期的知识层和契约层。
• scripts/run.py 仍处于兼容模式，用于当前的生成任务。
• 后续精简脚本时，应将更多判断逻辑和示例移出 Python，并让脚本仅负责确定性执行与验证。

目前，请保留现有输出契约，并将 scripts/run.py 视为执行行为的事实来源。

输入

必需：

• outline/outline.yml
• outline/chapter_briefs.jsonl
• citations/ref.bib

可选：

• outline/writer_context_packs.jsonl

输出

对于每个包含 H3 小节的 H2 节：

• sections/S<sec_id>_lead.md

输出契约

保持以下文件格式规则不变：

• 每个导读文件仅包含正文，不含标题
• 每个导读文件都应预览本章的分析视角，并将多个 H3 小节串联成一个论证
• 每个导读文件都应限定在本章现有的引文范围内
• 每个导读文件都不得加入本章后续内容无法支持的新事实

加载顺序

始终阅读：

• references/overview.md
• references/lead_block_archetypes.md

根据任务阅读：

• references/throughline_patterns.md — 当章节简介过于简略，或难以将其转化为贯穿全文的论述主线时
• references/bridge_examples.md — 当导读需要更自然地衔接 H3 小节，且不采用幻灯片式旁白时
• references/bad_narration_examples.md — 当需要去除目录式旁白、规划者口吻、基于数量的开篇时

机器可读资源：

• assets/lead_block_contract.json — 导读块格式的稳定软件包契约
• assets/lead_block_compatibility_defaults.json — 后备措辞、条目限制、衔接语和句子节奏

路由规则

按以下顺序使用此技能：

1. 确认章节符合条件

• 根据 outline/outline.yml 找出包含 H3 小节的 H2 节
• 在 outline/chapter_briefs.jsonl 中找到对应的章节简介

2. 加载方法

• 阅读 references/overview.md
• 阅读 references/lead_block_archetypes.md
• 仅当章节简介或当前文本有此需要时，才加载其他参考文件

3. 检查引文范围

• 如果存在 outline/writer_context_packs.jsonl，使用它处理跨章节的引文
• 所有引文都应限定在本章现有范围内，并根据 citations/ref.bib 验证引文键

4. 执行

• 当前阶段：以兼容模式使用 scripts/run.py，以保留当前行为和输出格式
• 未来阶段：让 scripts/run.py 仅负责确定性执行，并将写作方法和反模式清单保留在 references/ 中

兼容模式说明

scripts/run.py 仍包含当前启用的导读生成逻辑。

这是临时安排。目前：

• 不要将当前脚本措辞视为目标架构
• 应将 assets/lead_block_compatibility_defaults.json 视为兼容模式的主要措辞来源
• 不要将大段文字说明复制回 SKILL.md
• 在减少当前流程中明显的旁白式措辞时，仍须保留现有输出契约

此技能应确保的内容

无论详细方法位于何处，此技能都应生成满足以下要求的章节引言：

• 陈述章节的比较视角，而不是叙述大纲
• 将 H3 小节串联成一个完整论证，而不是把它们当作彼此孤立的游览站点
• 引入反复出现的对比，但不使用斜杠罗列术语
• 在较高层面清晰呈现评估或校准视角
• 避免幻灯片式叙述、规划器话语和重复使用固定开场白
• 尽可能从多个候选引言框架中选择（视角优先／顺序优先／比较优先），并采用叙述感最弱的选项，而不是到处重复同一种固定节奏

阻止条件

如果符合以下任一情况，请停止并转交上游处理：

• 缺少 outline/chapter_briefs.jsonl
• 目标 H2 章节没有 H3 子章节
• 章节简述过于不完整，无法安全推断贯穿全文的主线
• 所请求的引言需要新增事实或超出范围的引文

脚本职责

目前应将 scripts/run.py 视为一个兼容性执行器。

脚本精简后，其长期职责将更为有限：

• 章节发现
• 简述加载与规范化
• 契约验证
• 确定性报告编写

它并非长期用于存放引言范式、衔接示例或叙述反模式的地方。

脚本

快速开始

• uv run python .codex/skills/chapter-lead-writer/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <id>
• --inputs <a;b;...>
• --outputs <a;b;...>
• --checkpoint <C*>

示例

• uv run python .codex/skills/chapter-lead-writer/scripts/run.py --workspace <workspace>

故障排除

• 如果缺少 outline/chapter_briefs.jsonl 或其中内容过少，请先重新构建章节简述。
• 如果缺少 outline/writer_context_packs.jsonl，脚本仍会运行，但可用的引文池会更少。
• 如果生成的引言听起来像在叙述幻灯片，请先修补兼容性资源及参考资料，再修改 Python。