outline-builder

大纲构建器

触发条件与路由

• 触发词：大纲构建器、项目符号大纲、outline.yml、大纲生成、仅项目符号。
• 适用场景：结构阶段（NO PROSE），已有 taxonomy，需要生成可映射、可写作的章节与小节骨架（每个小节至少 3 个项目符号）。
• 跳过条件：已有经过批准且可映射的大纲（避免无意义的反复修改）。
• 网络：无。
• 护栏：仅项目符号；移除 TODO/模板语句；每个小节至少包含 3 条可检查的项目符号。

outline/outline.refined.ok 仅当标记的时间晚于大纲、所有已声明的输入、defaults 资源和生成器时，才会锁定经过审核的大纲。上游变更会使标记失效，并触发带备份的重新生成。

从以下任一来源构建 outline/outline.yml：

• outline/taxonomy.yml（兼容旧版、H3 优先的路径）
• outline/chapter_skeleton.yml + outline/section_briefs.jsonl（过渡中的小节优先路径）

兼容模式已启用：此次迁移在调整 intro/related 默认设置、Stage A 项目符号模板和特定领域的比较框架并将其移至 references/ 和 assets/ 的同时，保留当前输出约定。

加载顺序

始终阅读：

• references/overview.md
• references/stage_a_contract.md

根据任务阅读：

• 更改 Introduction / Related Work 默认设置时，阅读 references/intro_related_patterns.md
• 校准项目符号时，阅读 references/examples_good.md 和 references/examples_bad.md

机器可读资源：

• assets/outline_defaults.yaml

输入

必需：

• outline/taxonomy.yml

仅用于人工校准的可选内容：

• ref/agent-surveys/STYLE_REPORT.md
• ref/agent-surveys/text/

输出

保留当前输出约定：

• outline/outline.yml

兼容模式

当前模式以参考资料为主，并兼容脚本：

• 章节前置默认设置位于 assets/outline_defaults.yaml
• Stage A 项目符号默认设置和比较维度包位于 assets/outline_defaults.yaml
• 示例和边界规则位于 references/
• scripts/run.py 仍负责大纲生成、小节优先输入选择和占位符安全覆盖行为

脚本边界

仅将 scripts/run.py 用于：

• 加载 taxonomy 或小节优先结构输入，以及 defaults 资源
• 确定性地渲染大纲骨架
• 保留现有的非占位符大纲
• 从机器可读的默认设置中选择比较维度包

不要将脚本视为以下内容的主要存放位置：

• Introduction / Related Work 的领域框架
• 长篇项目符号库或写作范例
• 关于优质大纲应如何呈现的、以提示词为主的指导

输出格式规则

保持以下内容稳定：

• outline/outline.yml 是一个 YAML 列表
• Introduction 和 Related Work 保持为前两个 H2 小节
• 每个 H3 小节都包含 Stage A 项目符号：Intent: / RQ: / Evidence needs: / Expected cites:
• 每个 H3 小节在 Stage A 字段之后还需添加若干特定主题的项目符号
• 辅助工具绝不覆盖非占位符的用户内容

快速开始

• uv run python .codex/skills/outline-builder/scripts/run.py --help
• uv run python .codex/skills/outline-builder/scripts/run.py --workspace <workspace>

执行说明

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

• outline/taxonomy.yml，或
• outline/chapter_skeleton.yml + outline/section_briefs.jsonl
• assets/outline_defaults.yaml

ref/agent-surveys/ 下的可选风格参考仅用于人工校准：

• 使用 ref/agent-surveys/STYLE_REPORT.md 检查章节数量和详略程度是否合理
• 浏览 ref/agent-surveys/text/，仅用于校准结构，而非措辞

脚本

快速开始

• uv run python .codex/skills/outline-builder/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <id>
• --inputs <path1;path2>
• --outputs <path1;path2>
• --checkpoint <C*>

示例

• uv run python .codex/skills/outline-builder/scripts/run.py --workspace <workspace>

故障排查

• 如果 Related Work 仍带有特定领域的框架表述，请先修改 assets/outline_defaults.yaml，再更改 Python 代码。
• 如果子节项目看起来过于泛泛，请查看 references/stage_a_contract.md 和 references/examples_good.md。
• 如果大纲结构有效但过于零散，请改用 outline-budgeter，而不是扩展此脚本。