用途
ara-compiler 是一个运行在 Claude Code 中的智能体技能，目标是把任意包含研究知识的输入编译为一份完整、经过校验的 Agent-Native Research Artifact（ARA）。它不限定输入格式，接受 PDF 论文、arXiv 链接、GitHub 仓库（URL 或本地路径）、代码文件与脚本、notebook（.py、.ipynb、.rs、.cpp 等）、实验日志、训练输出、评估结果、配置文件、超参数扫描、原始研究笔记、头脑风暴记录、会议记录、包含结果与检查点的数据目录、描述研究决策的 Slack/邮件线程，以及上述内容的组合；也可以在没有任何输入时，通过对话交互式地构建 ARA。
主要能力
- 输入识别与读取：通过 Glob、Read 等工具探索给定路径，理解输入性质后再制定生成计划；对 PDF 逐页阅读（含附录），对仓库按 README → 核心算法文件 → 配置 → 环境文件的优先级处理。
- 四阶段认知链式推理：
- 语义解构：剥离叙述框架，提取数学公式、架构规格、实验配置、全部数值结果（精确值，不四舍五入）、引用依赖及其角色、负面结果与消融发现、实现技巧与敏感性观察；并对每个拟引用的表格/图先捕获原始来源标识与标题，转录原始内容，派生视图单独标注。
- 认知映射：将提取的知识原子映射到 logic/ 目录，包括 problem.md（观察→缺口→关键洞见→假设）、claims.md（可证伪声明及证据指针）、concepts.md（≥5 个形式化定义）、experiments.md（≥3 个声明式验证计划，仅方向性、不含精确数字）、solution/（架构、算法、约束、启发式）、related_work.md（带类型的依赖图）。
- 物理存根：生成 src/ 目录，包括精确超参数配置、至少一个实现新颖贡献的 Python 代码存根（带类型签名）、环境说明。
- 探索图提取：重建研究 DAG 到 trace/exploration_tree.yaml，≥8 个节点，必须包含 dead_end 与 decision 类型，每个节点声明 explicit 或 inferred。
- 覆盖检查循环：最多三轮，重新阅读源材料、与 ARA 对比、修补缺口，零修补则提前退出。
- Seal Level 1 校验：检查必需目录与文件、PAPER.md 的 YAML frontmatter 与 Layer Index、claims/experiments/heuristics/concepts 的字段与数量、探索树 YAML 解析与节点类型、跨层引用解析（Claim Proof ↔ Experiment Verifies ↔ Heuristic Code ref ↔ Evidence）、证据文件命名与来源一致性、声明措辞是否超出证据类型等。
- 修复与迭代：针对失败项做定向编辑，通常 2-3 轮收敛。
- 最终报告：输出产物位置、文件数量与总大小、校验结果、claims/experiments/heuristics/concepts/树节点/证据文件等关键统计。
使用方式
作为 Claude Code 智能体技能运行，直接使用原生工具（Read、Write、Edit、Bash、Glob、Grep），无需 API 包装。参数可灵活解释：文件/目录路径直接读取；URL 抓取或克隆；--output <dir> 指定输出目录（默认 ./ara-output/）；--rubric <path> 指定 PaperBench 评分标准用于覆盖映射；其他内容作为上下文或向用户澄清。工作流为：读取全部输入 → 四阶段认知协议推理 → 用 Write 生成全部 ARA 文件 → 覆盖检查循环（最多 3 轮）→ 运行 Seal Level 1 校验 → 修复失败项并重新校验 → 向用户报告摘要。
适用场景
需要把论文、代码仓库、实验记录等异构研究材料整理为结构化、可校验、可追溯的研究产物时；需要从多来源交叉引用中提取声明、实验、证据与探索轨迹时；需要在缺少完整输入时通过对话补全研究信息时。
限制
- 所有数值必须从来源精确复制，不得四舍五入或近似；不得编造来源中不存在的声明、结果或启发式。
- experiments.md 只含方向性/相对预期结果，精确数字放入 evidence/。
- 每个 claim 的 Proof 字段引用实验 ID（E01、E02），而非文件路径。
- 信息确实不可用时写“Not specified in paper”，不得猜测。
- 不得把派生子集标注为 Table N 或 Figure N，除非忠实复现原始来源对象。
- 不得虚构决策、死胡同或实验；推断的轨迹必须标记为 inferred 或省略。
- 声明措辞不得超出证据支持范围，需区分直接观察与解释。
- 涉及花费金钱、占用共享 GPU 或云配额、触碰个人或患者数据、不可撤销的操作前需先询问。
- 版本相关细节可能过时，需对照已安装版本的官方文档确认。
相关技能
- ara-research-manager：在编码或研究会话结束时记录研究来源，扫描对话并写入决策、实验等。
- ara-rigor-reviewer：对 ARA 目录执行 Seal Level 2 语义认知审查，阅读 PAPER.md、logic/claims.md 等。