SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场schema-normalizer

schema-normalizer

写作与研究

查看项目

更新于 10-16 04:42

技能介绍

用途 Schema Normalizer 用于在“技能优先”的 pipeline 中消除一个常见失败模式：不同 JSONL 产物之间的 schema 漂移。当字段不一致（如缺少 ids/titles、引文键格式混杂）时，下游技能会开始做尽力而为的 join 和脆弱解析；该技能让接口变得显式且确定。

触发条件 触发词包括：schema normalize、jsonl contract、interface drift、join drift、字段不一致、schema 规范化。 适用场景：当你已经生成 C2-C4 的 JSONL 产物（outline/briefs/bindings/packs/anchors），并希望在 self-loops/writing 之前获得确定、稳定的字段时使用。

输入

  • outline/outline.yml：section/subsection ids 与 titles 的事实来源。
  • 可选：citations/ref.bib，用于引文键的合理性检查。
  • 默认需要规范化的 JSONL 产物（arxiv-survey(-latex) C4 bridge）：
    • outline/subsection_briefs.jsonl
    • outline/chapter_briefs.jsonl
    • outline/evidence_bindings.jsonl
    • outline/evidence_drafts.jsonl
    • outline/anchor_sheet.jsonl
  • 可选（在 writer packs 生成之后运行）：
    • outline/writer_context_packs.jsonl

输出

  • output/SCHEMA_NORMALIZATION_REPORT.md：始终写出，含 PASS/FAIL 与变更内容。
  • 被处理的 JSONL 文件原地规范化；若应用了变更，会创建 .bak.* 备份。

规范化内容

  1. IDs 与 titles（join keys）
  • 对于含 sub_id: "<H2>.<H3>" 的记录：确保 section_id 存在（由点号前的前缀推导）；确保 title、section_title 存在（从 outline/outline.yml 填充）。
  • 对于含 section_id: "<H2>" 的记录：确保 section_title 存在（从 outline/outline.yml 填充）。
  1. 引文键格式（减少解析漂移） 在这些 C2-C4 JSONL 产物内，将引文键规范化为原始 BibTeX 键（不带 @ 前缀），例如："citations": ["smith2023", "jones2024"]。 注意：最终正文仍使用 Markdown 引文格式 [@smith2023]。该技能不增加或删除引文，只规范化格式。

运行时机 建议在 arxiv-survey(-latex) 中：在 evidence-draft + anchor-sheet 之后、writer-context-pack + evidence-selfloop 之前运行。这能确保在构建起草 packs 之前，outline/evidence_drafts.jsonl 与 outline/anchor_sheet.jsonl 的 schema 是稳定的。

失败模式

  • 如果 outline/outline.yml 缺失或无法解析，技能 FAIL。
  • 如果任一目标 JSONL 含无效 JSON 行，技能会报告并 FAIL（不要在损坏的产物上继续）。

使用方式（脚本，可选） 快速开始：uv run python .codex/skills/schema-normalizer/scripts/run.py --help 规范化 C4 bridge 产物：uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace> 全部选项：--workspace <dir>、--unit-id <U###>、--inputs <以分号分隔>、--outputs <以分号分隔>、--checkpoint <C#>。

示例

  • 规范化默认 C4 产物（ids/titles + citations 格式）：uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace> --inputs outline/outline.yml;citations/ref.bib;outline/subsection_briefs.jsonl;outline/chapter_briefs.jsonl;outline/evidence_bindings.jsonl;outline/evidence_drafts.jsonl;outline/anchor_sheet.jsonl --outputs output/SCHEMA_NORMALIZATION_REPORT.md
  • 同时规范化 writer packs（若在 writer-context-pack 之后运行）：uv run python .codex/skills/schema-normalizer/scripts/run.py --workspace <workspace> --inputs outline/outline.yml;citations/ref.bib;outline/writer_context_packs.jsonl --outputs output/SCHEMA_NORMALIZATION_REPORT.md

适用场景与限制 适用于已存在上述 JSONL 产物、需要统一 id/title 与引文键格式的生成式研究/写作 pipeline。限制：强依赖 outline/outline.yml；不新增或删除引文；不做 best-effort 修复，遇到无效 JSON 会 FAIL。具体收费、价格、平台支持等信息暂未提供。