taxonomy-builder

分类体系构建器（路由器，兼容模式）

触发条件与路由

• 触发条件：taxonomy、taxonomy builder、分类、主题树、taxonomy.yml。
• 适用情形：survey/snapshot 的结构阶段（NO PROSE），已有 papers/core_set.csv，需要生成可映射且对读者友好的主题结构。
• 跳过条件：已有获批且可映射的分类体系（不要无意义地重构）。
• 网络：无。
• 防护措施：避免泛化的占位类别；保持至少 2 层，且每个节点都有具体描述。

根据 papers/core_set.csv 构建 outline/taxonomy.yml。

P0 兼容性说明：

• 输出约定保持不变（outline/taxonomy.yml、YAML 列表、至少 2 层、具体描述）。
• 精选领域分类体系现在存放在 assets/domain_packs/*.yaml 中，不再以 Python 说明文字的形式存在。
• scripts/run.py 仍是确定性的脚手架/辅助工具：检测领域包 -> 有可用包时加载 -> 否则回退到通用构建器。

加载顺序

1. references/overview.md
2. references/taxonomy_principles.md
3. 如果适用某个领域包，读取其 references/domain_pack_<domain>.md 和 assets/domain_packs/<domain>.yaml
4. 否则读取 references/archetypes_generic.md
5. 通过 references/examples_good.md 和 references/examples_bad.md 校准命名与描述质量

当前兼容包：

• llm_agents
• gen_image
• embodied_ai
• rag_evaluation

显式优化标记

只有在审阅手动优化后的分类体系后，才创建 outline/taxonomy.refined.ok。仅当该标记的时间晚于分类体系、其上游证据和生成器时，才会认可该标记；过期标记会被移除，且重新生成前会备份先前的分类体系。

输入

• papers/core_set.csv（必需）
• 可选：papers/papers_dedup.jsonl
• 可选：DECISIONS.md、GOAL.md、queries.md

输出

• outline/taxonomy.yml

资源约定

• assets/taxonomy_schema.json：领域包和输出预期的机器可读结构
• assets/domain_packs/*.yaml：受支持领域的兼容领域包

脚本职责

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

• 绝不覆盖非占位符的用户分类体系
• 保留当前 CLI 标志和输出路径
• 仅当 GOAL.md / queries.md 明确符合其检测约定时，才加载受支持的领域分类体系
• 为没有领域包的领域保留通用回退构建器

何时手动优化

如果出现以下情况，在将单元标记为 DONE 之前优化生成的分类体系：

• 顶层类别看起来像关键词聚类，而不是章节级问题
• 叶节点名称过于笼统（Overview、Benchmarks、Open Problems、Misc）
• 描述缺少范围提示或代表性论文锚点
• 领域检测选错了领域包

快速开始

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

执行说明

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

• papers/core_set.csv 作为必需的语料输入
  • 若存在，则读取 papers/papers_dedup.jsonl 获取通用语料信号
  • 将 GOAL.md 和 queries.md 作为选择领域包的权威意图；语料词语共现不能覆盖它们

脚本

快速开始

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

所有选项

• --workspace <dir>
• --top-k <int>
• --min-freq <int>
• --unit-id <id>
• --inputs <a;b;...>
• --outputs <a;b;...>
• --checkpoint <C*>

示例

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

故障排查

• 如果选错了领域包，请先检查 GOAL.md、queries.md 和领域包的 detect 规则，再考虑修改 Python。
• 如果 outline/taxonomy.yml 已包含真实的非占位分类体系，脚本会按设计直接返回，不予覆盖。
• 如果没有匹配的领域包，脚本会回退到通用构建器。