table-schema

表格 Schema（两层：索引与附录）

触发条件与路由

• 触发条件：表格 schema、schema 优先的表格、表格设计、表格 schema、先定 schema 后填充。
• 适用场景：你想要可验证、可填充的综述表格，并在 LaTeX 之前完成设计（通常处于 C4 阶段，证据包已准备就绪之后）。

表格不是装饰，而是压缩信息的方式。

此工作流中一种常见的失败模式是：生成的第一张表看起来像内部索引。 因此，我们将表格分成两层：

1. outline/tables_index.md（内部）

• 用途：覆盖范围检查、调试和快速扫描证据
• 可以更全面
• 不应插入论文

2. outline/tables_appendix.md（面向读者）

• 用途：可发表的综述表格（布局清晰、信息密度高）
• 可以作为附录插入最终 PDF

此技能会在填充表格前设计好这两层。

默认模式：语义优先（LLM 优先）

将此视为设计任务，而不是运行脚本。

如果某一列无法根据现有证据包填充，且需要猜测，那么这个 schema 就有问题。

角色（明确使用）

表格设计师（读者视角）

使命：选择能回答读者问题的表格，而不是回答工作流问题的表格。

要做：

• 让每张表格回答一个问题
• 表格应小到足以填充（两张好的表格胜过一张无法完成的超大表格）

避免：

• 在论文中放入内部或日志式表格
• 使用只有在此仓库中才有意义的列标签

证据管理员（可填充性）

使命：拒绝需要编造事实的 schema。

要做：

• 将每一列映射到具体的上游字段
• 拒绝会迫使单元格写成长段落的列

避免：

• TODO 列
• 占位符（“TBD”、“...”、“(placeholder)”）

工作流（明确输入）

• 使用 GOAL.md，确保读者问题和范围保持稳定。
• 如有 queries.md:draft_profile，请阅读；它控制的是表格数量，而非证据标准。
• 使用 outline/outline.yml，使表格的行单位与论文结构保持一致。
• 使用 outline/subsection_briefs.jsonl，确保表格维度／轴与已批准的结构一致。
• 使用 outline/evidence_drafts.jsonl，确保每个计划中的列都能在无需猜测的情况下填充。

输入

• outline/outline.yml
• outline/subsection_briefs.jsonl
• outline/evidence_drafts.jsonl
• 可选：GOAL.md

输出

• outline/table_schema.md

不可妥协项（schema 契约）

• 按 draft_profile 的最低定义要求：
  • course_paper：至少 1 张索引表和 1 张附录表
  • survey／deep：至少 2 张索引表和 2 张附录表
• 每个表格定义都必须包含：
  • 它要回答的问题
  • 行单位（H3／基准测试／工作／失败模式）
  • 列（含单元格样式限制）
  • 证据映射（哪些上游字段用于填充哪些列）
• 单元格样式：使用短语；避免段落式单元格。
• 论文文风：附录表格的标题和列必须适合发表（不得包含工作流术语）。

建议的默认设置（arxiv-survey 系列）

对于 course_paper，默认采用精简方案 I1 和 A1。只有在证据支持独立的读者问题时，才添加 I2 或 A2。对于 survey 和 deep，采用下方完整的 I1／I2／A1／A2 方案。

索引表（供 table-filler 生成 outline/tables_index.md）

I1）小节映射（维度 + 代表性工作）

• 行单位：H3
• 列：小节；维度；代表性工作
• 证据来源：subsection_briefs.axes + evidence_drafts 中的引用

I2）具体锚点（基准测试／数字／注意事项）

• 行单位：H3
• 列：小节；锚点事实；代表性工作
• 证据来源：anchor_sheet.anchors

附录表格（用于 appendix-table-writer -> outline/tables_appendix.md）

A1）方法／架构图谱（代表性工作）

• 行单位：工作／系统条目
• 列：工作；核心理念；循环 + 接口假设；关键参考文献
• 证据来源：evidence_drafts（比较 + 定义）+ anchor_sheet

A2）评估协议／基准图谱

• 行单位：基准或评估设置（回退选项：协议维度）
• 列：基准／设置；任务 + 指标；关键协议约束；关键参考文献
• 证据来源：anchor_sheet + evidence_drafts.evaluation_protocol

正面／反面示例

好的（适合发布的问题 + 可填写的列）：

• 问题：“哪些基准构成了该领域评估的基础？它们对应什么任务／指标／约束？”
• 列：基准；任务 + 指标；协议约束；关键参考文献
• 证据映射：evidence_drafts.evaluation_protocol + anchor_sheet

不好的（内部／流水线口吻）：

• 问题：“证据就绪度和验证需求是什么？”
• 列：证据级别、缺失字段、待办清单

如需内部诊断，请将其放入审计报告，而不是面向读者的表格中。

脚本（可选的初始化工具）

快速开始

• uv run python .codex/skills/table-schema/scripts/run.py --help
• uv run python .codex/skills/table-schema/scripts/run.py --workspace <workspace>

所有选项

• --workspace <workspace>（必填）
• --unit-id <id>（可选；仅用于运行器记录）
• --inputs <outline;briefs;packs;goal>（可选；覆盖输入）
• --outputs <relpath>（可选；默认为 outline/table_schema.md）
• --checkpoint <C#>（可选；初始化脚本会忽略）

示例

• 初始化两层架构（索引 + 附录）：

  uv run python .codex/skills/table-schema/scripts/run.py --workspace <workspace>

• 写入自定义架构路径（较少使用）：

  uv run python .codex/skills/table-schema/scripts/run.py --workspace <workspace> --outputs outline/table_schema.md

注意：

• 将脚本作为起点，然后将架构完善为论文材料。
• 如果某列无法根据证据包填写而无需猜测，那么架构就有问题。