writer-context-pack

Writer Context Pack（C4→C5 桥接）[无散文]

触发词与路由

• 触发词：writer context pack、context pack、drafting pack、paragraph plan pack、写作上下文包。

目的：通过为每个小节提供一份单一的上下文包，减少 C5「空洞写作」：

• 确切的 RQ／维度 + 段落计划（subsection_briefs）
• 具体的比较卡片 + 评估方案 + 局限性（evidence_drafts）
• 数值／评估／局限性锚点（anchor_sheet）
• 来自 evidence_bindings 的允许引用范围（小节 + 章节并集）

输入

• outline/outline.yml
• outline/subsection_briefs.jsonl
• outline/chapter_briefs.jsonl
• outline/evidence_drafts.jsonl
• outline/anchor_sheet.jsonl
• outline/evidence_bindings.jsonl
• citations/ref.bib

按需阅读

• 当不良的源文本句子或论文自述渗入写作包时，阅读 references/source_text_hygiene.md

机器可读资源

• assets/paper_voice_palette.json
• assets/source_text_hygiene.json
• assets/context_pack_policy.json
• 全仓库范围的 assets/limitation-signals.json——在句子可成为局限性提示之前使用的共享极性规则

输出

• outline/writer_context_packs.jsonl

输出格式（outline/writer_context_packs.jsonl）

JSONL，每个 H3 小节对应一个对象。

必需键：

• sub_id、title、section_id、section_title
• rq、thesis、axes、paragraph_plan
• clusters（从小节简报中复制，以便比较卡片稀少时，写作侧证据仍可按路线分配）
• tension_statement、evaluation_anchor_minimal（从小节简报中复制；具体的张力 + 最简评估上下文槽位）
• opener_mode、opener_hint（论文语气提示，用于变换小节开篇，避免使用模板标签）
• bridge_terms、contrast_hook、required_evidence_fields（从小节简报中复制；过渡／证据抓手；不新增事实）
• chapter_synthesis_mode（从章节简报中复制；有助于避免反复使用模板化的「综合来看……」）
• allowed_bibkeys_{selected,mapped,chapter,global}
• anchor_facts（精简后）
• comparison_cards（精简后）
• must_use（写作契约；根据内容包丰富度 + draft_profile 推导出的最低要求）
• do_not_repeat_phrases（改写触发项；应避免逐字重复的高信号生成器句式）
• pack_warnings（列表；说明若上游未修复，此内容包为何仍可能导致写作空洞）
• paper_voice_palette（正向论文语气短语库 + 改写句式；避免「生成器语气」，同时不设置僵化的硬性限制）
  • 来源：工作区覆盖文件 outline/paper_voice_palette.json（如果存在），否则使用仓库默认文件 .codex/skills/writer-context-pack/assets/paper_voice_palette.json。
  • 包含 role_cards（章节作者／证据管理员／风格协调者）。将其视为角色提示和改写意图，而非句子模板。
• pack_stats（对象；原始／保留／丢弃数量 + 精简策略，避免截断／丢弃情况不透明）

精简策略：

• 内容包会精简较长的片段，在保持 JSONL 易读的同时保留具体细节（参见 pack_stats.trim_policy）。
• 精简不会添加省略号标记（以减少意外将其带入正文的情况）。

Writer 合约（C5 应如何使用此资料包）

将每个资料包视为可执行的检查清单，而非可选背景信息：

A150++ 最低要求（默认值；由门控和自循环使用）：

• paragraph_plan：10
• anchor_facts：>=10
• comparison_cards：>=4
• limitation_hooks：>=3
• allowed_bibkeys_mapped：>=28

course_paper 的最低要求使用较小的上下文资料包：paragraph_plan 6、 anchor_facts >=6、comparison_cards >=3、limitation_hooks >=2，以及 allowed_bibkeys_mapped >=8。面向写作者的 must_use 子集为 3 个锚点、 2 个比较项和 1 个局限项。

• 遵循计划：遵循 paragraph_plan（不要跳过计划中的段落；只有在保留相同对比项／锚点的情况下才合并）。
• 衔接意图：将 paragraph_plan[].connector_phrase 视为语义指导，而非照搬内容；应改述并变换表达；避免使用 Next, we ... 这样的叙述。
• 锚点必用：在适用时，至少纳入一个与段落论点类型（评估／数值／局限）匹配的 anchor_facts 项。
• 比较项必用：复用 comparison_cards，写出明确的 A 与 B 对比句（避免分别总结“A，然后 B”）。
• 只有当比较卡片的两方都包含可用亮点时，卡片才有效；若经过清理后卡片变成单方面内容，就应弃用该卡片，并将缺口上报至上游，而不是让写作者自行编造缺失的一方。
• 论点必用：第一段应以 thesis 陈述收尾（或以承诺程度相同的忠实改述收尾）。
  • 优先提出内容论点；避免使用生成器式的元叙述开场（如 This subsection ...），也要避免在多个 H3 标题下反复照搬开场标签（例如 Key takeaway:）。
• 开场模式（反模板化）：使用 opener_mode / opener_hint 来改变第 1 段引入本小节的方式（先讲张力、先讲决策或先讲视角）。
  • 不要将标签直接写入正文；引导语应简洁，并承载内容。
• 反模板化：将 do_not_repeat_phrases 视为触发改写的信号（论文语体规范）：
  • 如果出现所列短语，应将其改写为内容论点／论证衔接（不要叙述提纲）。
  • 避免换用新的重复句式；表达应多样化，符合论文语体。
  • 例外：若某个短语确实仅适用于本小节（而非可复用句式），则可出现一次。
• 微观结构：如果正文开始流于平淡的总结，应反复运用 grad-paragraph（张力 → 对比 → 评估锚点 → 局限）。
• 引用范围：优先使用 allowed_bibkeys_selected（其次为 allowed_bibkeys_mapped，再其次为 allowed_bibkeys_chapter）。allowed_bibkeys_global 专用于映射到多个小节的跨领域著作（基础研究／基准测试／综述）：应谨慎使用，并且每个 H3 仍应保留 >=3 条小节专属引文。

此资料包如何预防常见的写作失误（主动使用）

将资料包视为一组写作约束与支持条件。

失败 -> 打包处理 -> 撰写调整

• 叙述式开场（“This subsection ...”“In this subsection ...”）

  • 使用：tension_statement、opener_mode、opener_hint、thesis
  • 调整：以内容为先撰写第 1 段：张力／决策／视角 -> 说明其重要性 -> 以论点收尾。

• 逐篇列举主题（每篇论文写一个段落，不做比较）

  • 使用：comparison_cards、axes
  • 调整：撰写 A 与 B 的对比句，明确使用对比词（whereas / in contrast / unlike），并一次围绕一个维度展开。

• 缺少评估背景（论断缺少协议／指标支撑）

  • 使用：evaluation_anchor_minimal、evaluation_protocol
  • 调整：在比较结果的段落中说明最基本的三项：任务类型 + 指标 + 限制条件（预算／工具访问权限／成本）。
  • 将 evaluation_protocol 中的基准测试清单仅视为元数据；不要在正文中照搬原始基准测试名称列表。

• 缺少局限性（读起来过于自信）

  • 使用：limitation_hooks、required_evidence_fields
  • 调整：添加一个明确的保留意见段落或分句，指出证据无法证明什么（协议不匹配、缺少消融实验、威胁模型不明确）。

• 免责声明泛滥（每个 H3 都重复“仅有摘要证据”）

  • 将 pack_warnings 作为信号，而非直接复制的文案
  • 调整：在前置内容中说明一次证据政策；在 H3 中仅在与该小节具体相关时添加简短的局部保留意见。

• 引文漂移／随意引用全文文献

  • 使用 allowed_bibkeys_selected（然后是 mapped，再然后是 chapter，很少使用 global）
  • 调整：如果不引用这些集合之外的文献就无法写作，请停下来修正上游映射／绑定，而不是在正文中“勉强凑合”。

小示例（请勿照抄；应改写）

不佳（叙述式开场）：

• This subsection surveys tool interfaces for agents ...

较好（内容优先的开场）：

• A central tension in tool interfaces is balancing expressive action spaces with verifiable execution; we argue that interface contracts largely determine what evaluation claims can be trusted.

不佳（元层面的指导）：

• Therefore, survey comparisons should focus on ...

较好（面向文献的观察）：

• Across reported protocols, comparisons often hinge on whether tools are treated as deterministic APIs or as stochastic resources, which changes both cost and failure modes.

脚本

快速入门

• uv run python .codex/skills/writer-context-pack/scripts/run.py --help
• uv run python .codex/skills/writer-context-pack/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <U###>
• --inputs <semicolon-separated>
• --outputs <semicolon-separated>
• --checkpoint <C#>

示例

• 默认 IO：
  • uv run python .codex/skills/writer-context-pack/scripts/run.py --workspace <workspace>
• 显式 IO：
  • uv run python .codex/skills/writer-context-pack/scripts/run.py --workspace <workspace> --inputs "outline/outline.yml;outline/subsection_briefs.jsonl;outline/chapter_briefs.jsonl;outline/evidence_drafts.jsonl;outline/anchor_sheet.jsonl;outline/evidence_bindings.jsonl;citations/ref.bib" --outputs "outline/writer_context_packs.jsonl"

优化标记（推荐；可避免反复返工）

当你对 writer packs 感到满意（且它们与 briefs／bindings 一致）时，创建：

• outline/writer_context_packs.refined.ok

这是一个明确的“我已审阅／优化”信号：

• 可防止脚本重新生成内容并覆盖你的修改
• （在严格运行中）可在撰写前用作完成信号