tririver/arc · 上手攻略

是什么

Agent Research Copilot (ARC) 是一套面向理论物理研究的 LLM-Agent 工作流，由 Yanjiao Ma、Yi Wang、Xingkai Zhang 三人署名，已发布 ChinaXiv:202606.00234（v1，2026-06）。它本身不是单一 CLI，而是「7 个可独立复用的 Python 包 + 一层对 coding agent 友好的 Skill / 插件 / 工作流 adapter」：

包名 职责
arc-jobs 持久化作业执行（中断恢复、并发、运行时挂掉恢复）
arc-llm 统一 LLM provider / 模型调用层（对各家用同一套抽象）
arc-proposer-reviewer 提议者-评审者双角色编排
arc-paper 论文获取、解析、缓存、摘要
arc-domain 领域发现、类型化摘要、证据化领域产物
arc-translate 双语翻译与评审
arc-companion 配套读物（Companion）组装与发布

主要面向的 agent host 是 Codex、Claude Code，以及所有「能跑 Python、能读 SKILL.md 之类说明」的 coding agent——把 repo 直接交给它们就行。配套 workflow 涵盖：domain.md（建领域）、ideas.md（出主意 + proposer-reviewer 评估）、plan.md（计算规划）、calculate.md（验证 + 计算）、check.md（研究笔记声明核验）、companion.md（翻译 + Companion）。

仓库的「治理哲学」很值得注意一句话：ARC 是给模型的信息基础设施，不是替代模型科学判断的程序逻辑。任何可能把科学问题固化成 routing / 删除 / 资格门槛 / 强制模板的代码都被明确反对；硬停只留给「缺权限 / 持久态损坏 / 不安全破坏性动作 / 完全没有可用输出」。

解决什么问题

理论物理研究里，LLM 经常被以下问题卡住：如何快速定位一篇论文、如何从种子文献构建出一个可信的「研究领域」、idea 出了但没人批、可重复的符号/数值计算怎么搭、跨语种文献怎么对齐解读、把一份复杂文献做成可对照阅读的 Companion。ARC 用 7 个包 + 6 个工作流把这些问题拆成可观察、可审计、可中断恢复的工程任务。

按 README 的实测口径：一次「领域构建 + 想法生成」典型跑动在 Claude + DeepSeek 上消耗约 1M uncached 输入 token + 0.5M 输出 token，跑 1 小时左右。这是个不便宜的 pipeline，必须有意识地控成本。

它没解决的：不是「给答案」，而是「给模型更好的输入」——具体的科学争论、idea 创新性判断、文献综述的解释权衡，作者明确留给模型推理。任何把模型都能改正的科学弱点变成硬否决的设计都被禁掉。

快速安装

环境：Python 3.11+（AGENTS.md 明确要求），可联网（学术论文获取、LLM 调用），可访问至少一个 LLM provider。

# Codex 路径
codex plugin marketplace add tririver/arc --ref stable
codex plugin add arc@arc

# Claude Code 路径
/plugin marketplace add tririver/arc@stable
/plugin install arc

# 其他 coding agent：直接把仓库地址交给 agent，让它读 SKILL.md 安装

⚠️ 安装前 强烈建议先看 README 的「Permission」与「Token usage」两段：ARC 会请求跑 Python 脚本的权限，多且频繁，建议在 Docker / VM 里开全权限；并在跑大流程前预算好 1M / 0.5M token 的消耗。

核心用法

1) 装完之后的第一问

直接让 agent 帮你跑：

Use ARC to summarize a paper.
Use ARC to build a domain from arXiv:0911.3380 with new papers since 2024.
Use ARC to develop and review ideas from the resulting domain.
Use ARC to check this calculation.

2) 6 个工作流（对应 plugins/arc/skills/arc/workflows/*.md）

  • domain.md：从种子文献建领域——事实级证据化产物，包含类型化摘要与可视证据。
  • ideas.md：提议者-评审者闭环，idea 出、idea 批，迭代。
  • plan.md：基于现有证据给计算做规划。
  • calculate.md：前提自检 + 实际计算（含可复现脚本）。
  • check.md：研究笔记声明级核验（claim-vs-evidence）。
  • companion.md：双语翻译 + 章节锚定的 Companion 生成。

3) 包级 CLI / 公共 API

每个包都开过公共 CLI 入口（README 与 AGENTS.md 都强调「Skill 不可用时回退到文档化的 CLI 或公共 API」）：

# 示例：用 arc-paper 直接读摘要（具体子命令用 --help 查）
arc-paper --help
arc-domain --help
arc-proposer-reviewer --help
arc-translate --help
arc-companion --help

⚠️ 上面的子命令只是占位演示——README 与 AGENTS.md 都说「以 arc-xxx --help 输出的实际子命令为准」。⚠️ 我没有逐个独立核验每个子命令的具体参数；部署前请自行运行一次 --help 拿到精确字段。

4) 本地开发 / 测试

# 1) 先跑被改动包自己的 focused tests
python -m pytest --import-mode=importlib packages/*/tests

# 2) 跨包离线 contract 测试 + 一体化检查
scripts/check-packages.sh

# 3) 跨包完整离线套件（按 AGENTS.md 的「Testing and Evaluation」）
packages/arc-paper/.venv/bin/python -m pytest --import-mode=importlib \
  packages/*/tests tests

单元测试默认离线；联网 / 调真实模型的测试通过 ARC_RUN_NET_TESTS=1 显式打开，且被故意收紧到「至多 1 worker / 3 次 provider call / 5 分钟 / 固定输入 / 写 local/」——AGENTS.md 明确禁止在没有用户授权时把测试扩展成完整 workflow 跑。

5) 持久化作业 / 中断恢复

arc-jobs 包负责状态持久化：写 ARC 拥有的共享存储只限于 ~/.arc/runtimes 与 ~/.arc/cache/arc-paper 两个目录；其他持久态（领域状态、未发布生成物、LLM 会话、临时文件、日志、子工作区）都必须在项目根下的 .arc/，或者本仓库 checkout 里的 local/（被 .gitignore）。

这是一个相当强的约定——意味着你不应该自己造 tmp/、output/、results/ 这类顶层目录；违反这一规则会被 AGENTS.md 直接点为违反仓库规约。

6) 提 PR / 发版本

按 AGENTS.md：非平凡改动建议先在 local/implementation-plans/<task-slug>.md 写实施计划（路径在 .gitignore 内）。版本升级（VERSION、manifest、依赖范围）必须显式由人来批准，自己不能改。发布脚本：

scripts/release-arc.sh <version>

它会自动做发布校验、改包/plugin 版本号，会在动 Git 步骤前暂停让人确认。

典型适用场景

  • 理论物理 / 数学 / 高能 / 凝聚态研究生的日常辅助——读文献摘要、做领域概览、生成 idea 并被 reviewer 攻击、写可复现的符号计算。
  • 「给一个 coding agent 配研究型工具」时的标准模板——Skill + 包分离、host-specific 行为可选、有 portable CLI 回退，是这一类项目的范式之一。
  • 论文 pairwise 评审 / 双语 Companion 生成——这两件事在 ARC 里是被显式 supported 的工作流。
  • 希望工作流「可中断恢复、可审计」的研究团队——arc-jobs + local/ 隔离 + 强制 ~/.arc 共享存储的约定，是认真做研究 infra 的几个关键约束。
  • 学术写作 Co-pilot——把研究笔记丢过来，让 check.md 工作流做 claim-vs-evidence 校对。

坑与注意

  • 预算与权限必须先定。README 警告：跑了 1 小时把 1M 输入 token 烧光的可能性是存在的，且 ARC 要 Python 脚本权限，敏感机器请放 Docker/VM。这一点 README 显式标注是「risk to your data and system」。
  • 不是「替代科学判断」。AGENTS.md 把这一条写在最显眼的「Governing Philosophy」段：ARC 是给模型更好信息的，不是把科学问题固化成自动化规则。期待它「自动判 idea 新颖性」会被拒绝——这是设计决策，不是缺陷。
  • local/ 必须用。任何开发跑动、临时抽取、渲染预览、生成产物、评估输出都必须落到被 gitignore 的 local/ 树；顶层 tmp/output/results 都不允许。被别人配过的 agent 可能直接照它熟悉的工具惯例乱写，所以最好把这条写进你自己的 Coding agent 提示词。
  • ~/.arc 是仓库约定的根。运行时只识别 ~/.arc/runtimes 与 ~/.arc/cache/arc-paper 两个目录；其余共享 cache 必须有「跨项目身份 / 失效 / 并发 / 生命周期」四个规则文档，否则按 project state 落到项目 .arc/ 下面。别图省事把别的 cache 也塞进去。
  • author 名是「ARC 管的出版身份」。自动从论文里解析出的作者必须经模型对冻结源做核验；高置信才发布归属，否则必须显式空着——这是为了防止「模型先把名字编出来再让人类点头」。
  • 测试扩张到 token 贵流程前必须人批。Agent 自己默认只跑离线测试；想跑联网/真实 LLM 测试要显式 ARC_RUN_NET_TESTS=1，并满足「1 worker / 3 calls / 5 min / 写 local/」硬约束。完整 workflow 评估必须人类授权。
  • 版本操作必须由人批准。scripts/release-arc.sh <version> 是显式 human operation 的脚本；agent 不能自己改 VERSION、manifest 版本号、依赖范围、内部 schema 版本号只允许一起改（producer / consumer / 校验 / 测试 / 文档）。
  • 不要创建 / 移动 / push Git tag。AGENTS.md 明确禁止——agent 写代码可以，但仓库版本发布权是人的。
  • Worktree 是共享资源。Agent commit 前不应把别人的改动一起 rebase / 抹掉；可以保留「dirty worktree + 自己分批 commit」的并行模式。
  • Skill 不能塞复杂控制流。SKILL.md 要简短、按任务组织；具体示例和排错放到单独参考文档。包源码不能 import / 检查 / 执行 / 派生运行时行为自 Skill / plugin / workflow 文件——这是包 / host 边界纪律。

与同类对比

  • Paper-QA / LitSearch / OpenScholar 类文献检索 + QA 工具：差异点是 ARC 把「领域构建 + 提议者-评审者 idea + 计算可复现 + 双语 Companion」做成完整工作流，而不是单点 QA。
  • openai/agents-sdk / anthropics/claude-code-sdk 等 Agent SDK：那些是「让 coding agent 写代码」的 SDK。ARC 是「让 coding agent 做研究」，且已经把 7 个包 + 6 个 workflow 做到可复用级别——可以理解为「领域专用研究工作流」而非通用 agent 框架。
  • Future-House/lindroid / PrincetonPLI/... 类研究 agent 学术项目：多偏 agent 本身的研究，ARC 偏「稳定可复用的工程产物」。二者目标人群不一样——想拿来跑研究选 ARC，想做 agent 框架研究看那些学术项目。
  • asreview / PySR / SymPy 等专用科学 Python：单点工具。ARC 是把这些单点工具用法「以 Skill + 包」的方式整合进工作流的 glue layer——如果你只需要 sympy 或符号计算，那就直接用 SymPy。
  • Pieces-app / Continue.dev 等 IDE 内研究 Copilot：定位是「编辑器内 AI 助手」。ARC 是「可独立跑、可让 coding agent 装载、可审计产物」的研究 infra——可以互补。

一句话推荐结论

如果你做理论物理 / 数学 / 高能 / 凝聚态方向的研究，并且已经习惯了让 Codex、Claude Code 这样的 coding agent 帮你读文献、做计算、写笔记——ARC 是当前少有的「把 7 个 Python 包 + 6 个工作流 + 持久化作业」打包成可审计流程的开源方案；先在 Docker 里试用，预足 1M token 预算，按 AGENTS.md 走，再决定要不要常驻。

引用：Yanjiao Ma, Yi Wang, Xingkai Zhang. ARC: An LLM-Native Agent Workflow for Theoretical Physics Research. ChinaXiv:202606.00234, 2026. https://chinaxiv.org/abs/202606.00234

原始链接：https://github.com/tririver/arc/blob/main/README.md 与 AGENTS.md。⚠️ 仓库未在 README 标注具体 commit SHA；如需可复现锚点请自行 git rev-parse HEAD 取当前 HEAD。