subsection-writer

小节撰写器（兼容性路由器）

触发条件与路由

• 触发条件：小节撰写、逐节撰写、拆分章节、sections/、分小节写、按章节拆分写作。
• 适用场景：已记录 Approve C2，且写作资料包已就绪（outline/writer_context_packs.jsonl）；你希望在证据范围内起草，而不是一次性生成一篇庞大的初稿。

目的：在 sections/ 下撰写或润色各小节的综述正文，同时保持当前流水线契约不变。

兼容模式：

• 输出路径保持不变
• scripts/run.py 仍负责处理审批检查、缺失文件引导初始化，以及 sections/sections_manifest.jsonl
• 撰写指南现在存放在 references/ 中，不再主要写在脚本里

读取顺序

始终阅读：

• references/overview.md
• references/paragraph_jobs.md
• 调整段落角色行为或将写作者策略从 Python 中重构出来时，阅读 references/paragraph_job_archetypes.md
• 分析兼容模式下的引导初始化行为时，阅读 references/bootstrap_assembly.md

按需阅读：

• 第 1 段听起来空泛或像旁白时，阅读 references/opener_catalog.md
• 构建 A 与 B 的对比段落时，阅读 references/contrast_moves.md
• 提出性能、稳健性或基准测试主张时，阅读 references/eval_anchor_patterns.md
• 添加注意事项或局部结论时，阅读 references/limitation_moves.md
• 仅用于校准时，阅读 references/examples_good.md 和 references/examples_bad.md

机器可读契约：

• assets/subsection_writer_context.schema.json
• assets/bootstrap_paragraph_templates.json
• assets/paragraph_job_templates.json

输入

必需：

• DECISIONS.md（必须包含 Approve C2）
• outline/outline.yml
• outline/writer_context_packs.jsonl（优先使用）
• citations/ref.bib

可选但有用：

• outline/subsection_briefs.jsonl
• outline/evidence_drafts.jsonl
• outline/evidence_bindings.jsonl
• outline/anchor_sheet.jsonl
• outline/chapter_briefs.jsonl

输出

保持当前契约：

• H3 正文写入 sections/S<sub_id>.md
• sections/sections_manifest.jsonl：刷新此前由三个写作 Skill 生成的所有章节文件
• sections/h3_bodies.refined.ok：模型或人工审阅生成的 H3 正文后，提交 U100 进行强制验收时创建

front-matter-writer 负责摘要、引言、相关工作、讨论和结论。chapter-lead-writer 负责 H2 引导段。本 Skill 会在刷新共享清单时读取这些文件，但不会将其内容归为自己撰写。

写作者策略

当前规则关注的是论述环节的覆盖，而不是段落配额。 小节应涵盖资料包所支持的必要论述环节；如果证据不足以支撑固定段落数，就不要凑数。

开头与结尾策略：

• 根据资料包中的实际张力、对比、协议或局限信号，生成 2–4 个开头候选；保留内容最充实的选项，不要在所有小节中反复使用同一个固定句式
• 让小节结尾从有证据支撑的比较或局限内容中自然形成；不要为了让段落显得完整，就添加固定的“最稳妥的综合结论／决策规则”式结尾
• 将内部轴标签规范化为自然、面向读者的表述；斜杠式简要标签应仅作为规划元数据，不应原样出现在论文中

脚本边界

仅将 scripts/run.py 用作辅助工具：

• 它可以引导生成缺失的 H3 文件并刷新清单
• 引导生成的正文会根据 writer 包和带版本的模板资源确定性地组装；这些内容是可检查的回退材料，并不代表由模型撰写，也不代表最终正文质量
• 不得将其视为正文结构或语气策略的权威来源
• 不得让它自行认证引导生成的正文：脚本绝不会创建 sections/h3_bodies.refined.ok
• 该标记仅是 U100 的提交证明；它会在下游 writer-selfloop 之前创建，因此不表示自循环已通过
• 强制验收会独立地将 H3 句子与 Run 选定的 writer 模板资源进行比较，并拒绝超出 Pipeline 限值的字面残留
• writer-selfloop 会调用共享的严格章节检查器，该检查器会重新计算 H3 指标，之后报告才能 PASS
• 强制执行的 pipeline-auditor 会测量整个合并后的草稿，并生成评分卡；Harness 会将其判定结果和各维度写入评估台账
• 当前 10% 的限值是初始策略目标；一项已发布的当前合约回放显示，某个保留的 Artifact 集合中有 0/226 条残留，而从零开始的干净重现和跨主题重现仍未解决
• 如果该标记早于某项 writer 输入或 writer 脚本，则它已过时；下一次运行会先将其删除，再重新生成引导正文

快速开始

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

故障排除

• 如果素材包内容太少，请停止并向上游反馈，而不是凑字数。
• 如果小节听起来像在讲述，请重新加载 references/opener_catalog.md 和 references/examples_bad.md。
• 如果某项主张缺少协议背景，请在重写前重新加载 references/eval_anchor_patterns.md。

执行说明

在兼容模式下运行时，scripts/run.py 当前会读取：

• DECISIONS.md 中的 Approve C2
• 用于枚举章节／小节文件的 outline/outline.yml
• 作为主要起草输入的 outline/writer_context_packs.jsonl
• 用于限定范围内引文的 citations/ref.bib
• 作为可选补充来源的 outline/subsection_briefs.jsonl、outline/evidence_drafts.jsonl、outline/evidence_bindings.jsonl、outline/anchor_sheet.jsonl 和 outline/chapter_briefs.jsonl

脚本

快速开始

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

所有选项

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

示例

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

故障排除

• 如果 DECISIONS.md 缺少 Approve C2，请先停止并修复审批。
• 如果 outline/writer_context_packs.jsonl 内容太少，请转向上游处理，而不是凑字数。
• 如果引文范围看起来不正确，请在编辑输出文本前重新检查 citations/ref.bib 和 writer 包。