ARIS 智能体指南
> 面向首次阅读此仓库的 AI 智能体。 若你是人类，请看 README.md 或 docs/ARIS_INTRO.html。
ARIS 是一个研究编排框架：以可组合的 Markdown 技能为核心，通过跨模型对抗协作来驱动机器学习研究的完整生命周期。执行方（Claude / Codex / Cursor / Antigravity / Copilot CLI）负责写代码和论文；审阅方（GPT-5.5 通过 Codex MCP，或 Claude / Gemini 通过 claude-review / gemini-review MCP）在独立的线程中进行批判性审阅。
> 关于真理的源头。 本文件是一个路由索引，并非规范定义。
> 每个技能的行为定义在其 skills/ 中。系统级的约定在 skills/shared-references/*.md 中。若本指南与某个 SKILL.md 冲突，以 SKILL.md 为准。
技能位置与平台
| 平台 | 技能根目录 | 备注 |
|---|---|---|
| Claude Code / Cursor / Trae / Antigravity / Copilot CLI | skills/ | 主线技能；原生 SKILL.md 调用 |
| Codex CLI | skills/skills-codex/ | Codex 镜像；使用 spawn_agent 而非 mcp__codex__codex |
| Codex + Claude-review | skills/skills-codex-claude-review/ | 叠加在 skills-codex/ 之上 |
| Codex + Gemini-review | skills/skills-codex-gemini-review/ | 同理，审阅方为 Gemini |
docs/SKILLS_CATALOG.md — 79 个技能，按角色分组。各宿主平台的调用语法一致：
/skill-name "参数" — key: value, key2: value2
通用参数
ARIS 有两个独立的控制轴，外加作用域标记。
第一轴 — effort（深度 / 预算）
— effort: lite | balanced | max | beast # 默认值: balanced
控制论文数量 / 想法数量 / 迭代轮次 / 试点次数。不论 effort 取何值，Codex 推理级别始终为 xhigh。
第二轴 — assurance（审计严格度，独立于 effort）
— assurance: draft | polished | conference-ready | submission
控制最终报告是否需要经过强制审计关卡。lite / balanced 默认对应 draft；max / beast 默认对应 submission。允许覆盖：--- effort: lite --- assurance: conference-ready 是合法且有意义的组合。详见：shared-references/assurance-contract.md。
其他常用参数
— human checkpoint: true | false # 暂停等待人工批准（默认: false）
— AUTO_PROCEED: true | false # 在关卡处自动继续（默认: true）
— difficulty: medium | hard | nightmare # 审阅方对抗级别
— venue: ICLR | NeurIPS | ICML | ... # 目标会议/期刊
— sources: web, zotero, deepxiv, exa, ... # 文献来源
— gpu: local | remote | vast | modal # GPU 后端
— reviewer: codex | oracle-pro | manual # 审阅方路由
作用域标记（技能专属）
| 标记 | 技能 | 效果 |
|---|---|---|
--- style-ref <来源> | 写作类技能 | 模仿范文的结构风格，但不复制其声明和术语 |
--- edit-whitelist <路径> | /auto-paper-improvement-loop | 以 YAML 模式限定循环可以触碰哪些路径/操作 |
--- soft-only | /citation-audit | 参考文献冻结 — 改写正文而不编辑 .bib 文件 |
--review / --no-review | /render-html | 开关跨模型审阅关卡（默认: academic=开, dashboard=关） |
--author "..." | /render-html | 可选的作者署名，在副标题与元信息之间渲染 |
--deep-fix / --restatement-check | /proof-checker | 补丁级修复方案 / 跨位置定理漂移检测 |
工作流索引
主链: /research-pipeline = W1 → W1.5 → W2 → W3
论文后: W4（反驳信）、W5（转投新会议）、W6（演讲）
| ID | 技能 | 输入 | 输出 | 何时调用 |
|---|---|---|---|---|
| W1 | /idea-discovery "方向" | 研究方向 | IDEA_REPORT.md、EXPERIMENT_PLAN.md、FINAL_PROPOSAL.md | 启动新研究 |
| W1.5 | /experiment-bridge | EXPERIMENT_PLAN.md | 可运行代码、EXPERIMENT_LOG.md | 已有方案，需要实现 |
| W2 | /auto-review-loop "范围" | 论文 + 结果 | 改进后的论文 + REVIEW_STATE.json | 迭代改进循环 |
| W3 | /paper-writing "NARRATIVE_REPORT.md" | 叙事报告 | paper/main.pdf + LaTeX 源码 | 准备撰写论文 |
| W4 | /rebuttal "paper/ + reviews" | 论文 + 审稿意见 | PASTE_READY.txt + REBUTTAL_DRAFT_rich.md | 收到审稿意见之后 |
| W5 | /resubmit-pipeline "paper/" --- venue: X | 已润色论文 + 新会议 | <新会议目录>/ + RESUBMIT_REPORT.json | 在硬约束下转投另一个会议 |
| W6 | /paper-talk "paper/" --- venue: X | 论文 | Beamer + PPTX + 讲稿 + 问答准备 | 论文被接收后的会议演讲 |
--edit-whitelist + RESUBMIT_REPORT.json（7 状态失败模式账本）强制执行。Assurance 与审计链
ARIS 通过一个 5 层跨模型审计链来为投稿把关。每一层由不同的技能调用，全部使用全新的 codex 线程（绝不使用 codex-reply）：
| 层 | 技能 | 审计问题 | 裁决文件 |
|---|---|---|---|
| 1 | /experiment-audit | "评估代码是否诚实？（无伪造 GT、无自归一化分数、无幽灵结果）" | EXPERIMENT_AUDIT.{md,json} |
| 2 | /result-to-claim | "该声明是否从实验结果中科学地推导而来？" | （将声明状态写入研究 Wiki） |
| 3 | /paper-claim-audit | "论文是否如实汇报了数据？"（零上下文的审阅方） | PAPER_CLAIM_AUDIT.{md,json} |
| 4 | /citation-audit | "每条 \cite{} 是否有效？存在性 + 元数据 + 语境适当性？" | CITATION_AUDIT.{md,json} |
| 5 | /kill-argument | "写出最强有力的 200 字拒稿备忘录 + 独立裁决方对每个攻击点打分" | KILL_ARGUMENT.{md,json} |
shared-references/assurance-contract.md 中定义的 6 状态模式输出裁决：PASS | WARN | FAIL | BLOCKED | ERROR | NOT_APPLICABLE。在 assurance: submission 级别下，/paper-writing 的第 6 阶段会运行 tools/verify_paper_audits.sh，若任一层不是绿色则拒绝输出最终报告。
执行方不得评判自身的诚信。 审阅方以零上下文的"冷读"方式审阅工件（仅接收文件路径，绝不接收摘要或解读）。每次审阅方调用的轨迹保存到 .aris/traces/，详见 shared-references/review-tracing.md。
HTML 渲染（供人类阅读）
/render-html 将选定的 MD / JSON 工件（IDEA_REPORT、AUTO_REVIEW、KILL_ARGUMENT、PAPER_PLAN、research-wiki 状态）渲染为单文件 HTML，方便人类阅读。MD / JSON 仍是权威来源；HTML 是从学术报刊风格派生的生成视图。
/render-html <输入.md> [--template academic|dashboard]
[--out <路径>] [--author "..."]
[--review | --no-review]
academic模板（线性长文，带粘性目录）：默认启用了审阅 — 新的mcp__codex__codex线程审计渲染忠实度 / 安全性 / 结构（不审计声明真实性；那是/paper-claim-audit等的职责）dashboard模板（网格驾驶舱）：默认不审阅；传--review强制开启- 输出：
<文件>.html+<文件>.review.json附属文件 + 轨迹存储在.aris/traces/render-html/<日期>_run/ - 不要手动编辑生成的 HTML — 编辑源文件，重新渲染即可
工件约定
技能之间通过在约定位置的纯文本文件进行通信：
| 工件 | 由谁创建 | 由谁消费 |
|---|---|---|
IDEA_REPORT.md | /idea-discovery | /experiment-bridge |
refine-logs/FINAL_PROPOSAL.md | /research-refine | /experiment-plan |
EXPERIMENT_PLAN.md | /experiment-plan | /experiment-bridge |
EXPERIMENT_LOG.md | /experiment-bridge | /auto-review-loop、/result-to-claim |
NARRATIVE_REPORT.md | /auto-review-loop（或人工） | /paper-writing |
paper/main.tex | /paper-write | /paper-compile |
paper/main.pdf | /paper-compile | /auto-paper-improvement-loop |
REVIEW_STATE.json | /auto-review-loop | /auto-review-loop（上下文自动压缩后恢复用） |
EXPERIMENT_AUDIT.{md,json} | /experiment-audit | /result-to-claim |
PAPER_CLAIM_AUDIT.{md,json} | /paper-claim-audit | /paper-writing 第 5.5 阶段关卡 |
CITATION_AUDIT.{md,json} | /citation-audit | /paper-writing 第 5.8 阶段投稿关卡 |
KILL_ARGUMENT.{md,json} | /kill-argument | /paper-writing 第 5.6 阶段 + /resubmit-pipeline 对抗关卡 |
RESUBMIT_REPORT.json | /resubmit-pipeline | 投稿关验证器（7 状态账本） |
GAP_REPORT.md | /paper-plan（设置 --- style-ref: 时） | /paper-write（对缺失部分输出 |
<工件>.review.json | /render-html 审阅关卡 | 人工分诊 |
.aris/edit_whitelist.yaml | 人工 / /resubmit-pipeline | /auto-paper-improvement-loop --edit-whitelist |
research-wiki/ | /research-wiki | /idea-creator、/research-lit、/result-to-claim |
.aris/meta/events.jsonl | hooks（被动日志） | /meta-optimize |
.aris/traces/ | 审阅类技能 | 审计 / 取证回放 |
辅助工具解析（编写新技能时）
当 SKILL.md 调用一个规范辅助工具（如 verify_papers.py、research_wiki.py、save_trace.sh、arxiv_fetch.py、verify_paper_audits.sh）时，不要硬编码 python3 tools/foo.py。应按 shared-references/integration-contract.md §2 中的严格安全链条来解析：
第 0 层: ${CLAUDE_SKILL_DIR}/scripts/<辅助工具> # 所属技能自包含（CC 1.0+）
第 1 层: .aris/tools/<辅助工具> # 项目本地的符号链接
第 2 层: tools/<辅助工具> # 仓库本地
第 3 层: $ARIS_REPO/tools/<辅助工具> # 全局兜底
从 integration-contract.md §2 的逐辅助工具表中选取失败策略：A（关卡阻塞）/ B（副作用）/ C（取证）/ D1（级联）/ D2（多源聚合）/ E（诊断）。每个策略都有 POSIX-sh + set -e + set -u 的安全样例块。
.github/workflows/lint-skills-helpers.yml 中的 CI 检查会标记 PR 修改的 SKILL.md 中硬编码 python3 tools/foo.py 的模式（仅警告，绝不阻塞 CI）。单归属辅助工具（仅被一个 SKILL 使用）按架构 C 原则存放在 skills/<所有者>/scripts/<辅助工具> 中；先例有：figure-spec、paper-illustration-image2、experiment-queue、render-html。
跨模型协议
- 执行方（Claude / Codex / Cursor / Antigravity / Copilot）：写代码、跑实验、起草论文
- 审阅方（GPT-5.5 通过 Codex MCP，默认；或 Claude / Gemini 通过
*-reviewMCP 叠加层）：批评、打分、要求修改 - 规则：执行方与审阅方必须来自不同的模型家族。同家族审阅视为无效功能。
- 审阅方独立性：仅传递文件路径，绝不传递摘要或解读
- 线程清新度：每次审阅方调用使用
mcp__codex__codex（或等价物），绝不使用codex-reply— 叙事积累会虚高评分 - 实验诚信：执行方不得评判自己的评估代码 — 审阅方直接审计，详见
shared-references/experiment-integrity.md
gpt-5.5（自 2026-04-24 起运行时生效；文档于 2026-05-14 对齐）。旧版 gpt-5.4 可通过 --- reviewer-model: gpt-5.4 使用。Oracle Pro 档位（gpt-5.5-pro）通过 --- reviewer: oracle-pro 走单独的路由路径。共享参考文档
在调用审阅相关或审计类技能之前，请阅读以下文件：
| 文件 | 何时需要 |
|---|---|
reviewer-independence.md | 任何跨模型审阅 |
experiment-integrity.md | 编写评估 / 审计代码 |
fan-out-pattern.md | 将子智能体发散出去以扩展覆盖面（任意运行时层级） |
acceptance-gate.md | 自主循环 / 目标模式 — 谁可以 ACCEPT 一个结果 |
external-cadence.md | 在将技能包装到 /loop、/schedule 或 CronCreate 之前 |
assurance-contract.md | 6 状态裁决模式、审计关卡 |
integration-contract.md | 辅助工具解析 + 失败策略（编写新 SKILL.md 时） |
review-tracing.md | 审阅方轨迹的保存位置 |
reviewer-routing.md | --- reviewer: oracle-pro 等 |
citation-discipline.md | 引用规则 |
effort-contract.md | 投入级别规范 |
writing-principles.md | 写作标准 |
venue-checklists.md | 会议格式规范 |
研究 Wiki（可选）
若项目中存在 research-wiki/：
/research-lit自动摄入发现的论文/idea-creator在构思前读取 wiki，完成后将想法（无论成功与否）写回/result-to-claim更新声明状态（supported / invalidated / pending）- 累计 3 个以上的失败想法 → 触发重新构思建议（失败想法成为反重复记忆）
/research-wiki init 初始化。详见：skills/research-wiki/SKILL.md。辅助工具规范路径：tools/research_wiki.py（按上述第 1-3 层链条解析）。---
> 费曼式总结：ARIS 的本质是什么？它是一套游戏规则——你写代码做实验，但你不能自己给自己打分。必须找一个"外人"（不同模型家族）来审你的实验是否诚实、你的声明是否站得住脚、你的引用是否靠谱、你的论文能不能扛住最恶意的攻击。五层审计链就是五道防火墙，每一道都不许你作弊。说到底，它要对抗的是研究者在论文里自欺欺人的天性。