使用 ov-add-paper 技能：将研究论文编译为 ARA 工件并摄入 OpenViking
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
导读
本文讲解 OpenViking 仓库中ov-add-paper技能的完整用法：它把一份研究论文（PDF 或 URL）编译为符合 ARA（Agent-Native Research Artifact）规范的 Markdown/Python 工件目录，经过scripts/validate_ara.py确定性校验后，再通过ov add-resource摄入 OpenViking 成为可检索的知识资源。读完本文，你将掌握 ARA 工件的目录结构、逐字段编译规范、校验脚本的检查逻辑，以及ovCLI 完整摄取流程（含目录上传的常见坑与断连恢复方案）。
技能定位与适用场景
ov-add-paper位于 examples/skills/ov-add-paper/SKILL.md，是一个面向 Agent（LLM 助手）的技能说明文档。其描述明确要求：当用户提出添加、导入、编译或摄入研究论文/PDF时加载该技能，尤其是当用户提到ov-add-paper、ARA、claims、evidence、figures、tables 等关键词时。
从技能 frontmatter 可见其运行前提与权限边界：
name: ov-add-paper description: "Load when the user asks to add, import, compile, or ingest a research paper/PDF into OpenViking..." compatibility: OpenViking CLI configured at `~/.openviking/ovcli.conf` version: 0.1.1 last_updated: 2026-06-10 allowed-tools: - Read - Write - Edit - Bash - Glob - Grep tags: - openviking - paper-ingestion - research - ara技能的核心目标一句话：把论文变成 OpenViking 就绪的结构化资源，然后完成ov add-resource摄取——工件目录被校验并提交到 OpenViking 之前，任务不算完成。
输入与工作流总览
输入
- 必需：论文来源，通常是本地 PDF 路径或论文 URL；
- 可选：输出目录、OpenViking 目标 URI、领域备注、相关仓库/源文件，以及是否等待 OV 处理完成；
- 若论文来源缺失或不可访问，必须先向用户索要再开始。
六步工作流
- 完整阅读论文，包括附录和所有编号的图（Figure）与表（Table）；
- 依据 references/ara-compiler-profile.md 编译 ARA 风格工件目录；
- 用
scripts/validate_ara.py校验工件； - 修复校验失败项（除非用户明确接受这些错误）；
- 直接用
ov add-resource摄入校验通过的工件目录； - 用
ov stat/ov tree确认目标，并向用户返回工件路径、OV 目标/根 URI、校验结果、摄入结果和未解决的缺口。
ARA 工件目录规范（核心输出契约）
ARA 编译规范源自 Agent-Native Research Artifact 编译器模式，但ov-add-paper将其适配为 OV 资源目录：保留 ARA 的知识论结构，最终交付物却是 OpenViking 可直接摄入的资源目录。
必须包含的文件
工件必须包含以下文件（PAPER.md及各级子目录）：
PAPER.md logic/ problem.md claims.md concepts.md experiments.md related_work.md solution/ constraints.md src/ environment.md trace/ exploration_tree.yaml evidence/ README.md figures/ tables/此外，只有当论文确实需要时才允许附加文件，例如logic/solution/algorithm.md、logic/solution/architecture.md、data/dataset.md、src/configs/或evidence/proofs/——不允许为凑结构而凭空制造文件。
编译原则（Evidence First）
- 把论文当作证据优先、叙述其次；
- 通读全文，包括源材料中可获得的附录与补充章节；
- 在综合之前先保留原始证据；
- 严格区分：精确源事实、视觉估计、模型推断、不可用信息；
- 强声明必须有直接证据，证据较窄时使用更弱的措辞；
- 每个源引用都应指向真实的页码、章节、图、表、公式或仓库文件。
证据整理（Evidence Pass）
在撰写 claims 之前先建立证据账本：
- 按顺序枚举论文中所有编号的
Figure N和Table N； - 对每个已归档对象同时保存：裁剪或整页的 PNG（保留原始视觉）+ Markdown 转录或结构化描述；
- 无法归档的对象必须在
evidence/README.md中说明原因； - 原始源证据与派生子集分离存放。
Figure Markdown 应包含：Source、Caption、Figure type（quantitative_plot/diagram/qualitative_sample/mixed）、Extraction method（exact_from_labels/digitized_estimate/visual_description）、Reading confidence、Supports、转录或视觉描述。
Table Markdown 应包含：Source、Caption、Supports、忠实的表格转录。
认知层（Cognitive Layer）
各logic/文件职责清晰：
logic/problem.md：记录观察、缺口、关键洞见与假设；logic/claims.md：使用C01、C02… 标题，每条声明需包含 Statement、Status、Falsification criteria、Proof（引用E01等实验 ID）、Evidence basis、Interpretation（可选）、Dependencies、Tags；logic/experiments.md：使用E01、E02… 标题，描述验证计划而非精确结果数字，精确数字属于证据文件；logic/concepts.md：仅定义论文特有概念，不填充通用术语；logic/related_work.md：描述类型化依赖关系，如 imports、extends、baseline、bounds、refutes；logic/solution/constraints.md：始终必需，陈述边界条件、假设与局限。
工件层与探索轨迹
src/environment.md始终必需；其余src/文件只在论文或源材料中确实存在对应产物时才记录。不得从纯文本方法中臆造代码桩；若包含代码，必须标注是“从源码转录”还是“根据显式打印的伪代码/公式重构”。trace/exploration_tree.yaml记录研究 DAG：中心问题、实验、决策、死胡同、转向点，以及support_level: explicit或inferred。不得虚构失败或决策；若论文隐藏了研究过程，使用更小的 trace 并将重构节点标记为 inferred。
覆盖循环（Coverage Loop）
校验前最多进行三轮覆盖检查：
- 重读源标题、图、表、公式、附录章节与参考文献；
- 对照工件排查缺失项；
- 修补遗漏、弱化的声明措辞、缺失的证据链接或未解决的源引用；
- 若某轮未发现实质缺口可提前停止。
Done State（编译完成判定）
只有同时满足以下条件，ARA 编译阶段才算完成：
- 必需文件存在且非空；
- 已归档的图/表证据同时具有 Markdown 与 PNG；
- claims 与 experiments 交叉引用正确；
PAPER.md包含有用的 Layer Index；- 工件通过
scripts/validate_ara.py。
校验器源码解读：validate_ara.py 的确定性检查
scripts/validate_ara.py 是技能自带的确定性校验器（依赖标准库 argparse/json/re/sys/pathlib，无需第三方包）。其校验逻辑可分为六组，与上述工件规范一一对应：
1. 必需文件检查：REQUIRED_FILES列表中的 10 个文件必须存在且非空，缺文件或空文件都会记 ERROR。
2. PAPER.md 检查：必须含 YAML frontmatter，且 frontmatter 中title、authors、year三个字段齐全；正文必须包含Layer Index字样。
3. Claims 检查：用正则^##\s+(C\d{2,})切分C01风格块；每条声明必须含 Statement、Status、Falsification criteria、Proof、Evidence basis 五个字段；Proof 字段必须引用至少一个E##实验，且被引用的实验 ID 必须真实存在于logic/experiments.md（否则报“references missing experiment”）。
4. Experiments 检查：用^##\s+(E\d{2,})切分块；每条实验必须含 Verifies、Setup、Procedure、Metrics、Expected outcome 五个字段；Verifies 字段必须引用至少一个C##声明，且引用必须存在（否则报“Verifies references missing claim”）。
5. 证据文件检查：evidence/figures/、evidence/tables/目录缺失只记 WARNING；目录存在时统计 md/png 数量；每个 figure/table 的 Markdown 必须含Source字段（否则 ERROR）；figure 缺少Figure type、Extraction method、Reading confidence字段记 WARNING；每个 evidence Markdown 必须存在同名 PNG 兄弟文件（否则 ERROR）。
6. 探索轨迹检查：trace/exploration_tree.yaml必须包含support_level条目（否则 ERROR）；无明显的id:节点条目记 WARNING。
最后输出 summary（含 required_files、claims、experiments、figure_md/figure_png、table_md/table_png 计数）。main()中--json参数可输出机器可读 JSON，便于 Agent 解析；退出码 0 表示 PASS，1 表示 FAIL。
摄入契约：ov add-resource 完整流程
references/openviking-ingest.md 规定ov-add-paper必须以ov add-resource将论文工件导入 OpenViking 收尾。推荐的 CLI 流程：
# 1. 校验工件 python3 scripts/validate_ara.py <artifact-dir> # 2. 预检目标是否已存在（新目标应返回 NOT_FOUND） ov -o json stat viking://resources/papers/<slug> # 3. 摄入工件（--wait 等待处理完成） ov add-resource <artifact-dir> --to viking://resources/papers/<slug> --wait # 4. 事后确认 ov -o json stat viking://resources/papers/<slug> ov tree viking://resources/papers/<slug>关键细节：
- slug 生成：若用户未提供目标 URI，从论文标题、arXiv ID、DOI 或文件名派生出稳定 slug；
- 超时：中等篇幅论文建议
--timeout 300或更大值：
ov add-resource <artifact-dir> --to viking://resources/papers/<slug> --wait --timeout 300- 预检语义：
stat对新目标应返回NOT_FOUND；若预检成功（目标已存在），必须先询问用户，避免覆盖，或换一个目标 URI； - 前置条件：
ovCLI 已安装配置、~/.openviking/ovcli.conf（或等价环境配置）存在、工件目录本地存在、校验通过或用户明确接受所列校验错误。
底层实现：目录上传的 zip 语义
从 crates/ov_cli/src/client.rs 可以看到add_resource的实现：当路径是目录时，CLI 会先调用zip_directory/zip_directory_with_progress将整个目录打包为 zip，再upload_temp_file上传为临时文件，随后 POST 到/api/v1/resources（body 携带temp_file_id、source_name、to、parent、reason、instruction、wait、timeout、strict、include、exclude、processing_mode、args等字段）。这意味着：
--include/--exclude只是请求参数，不会减少客户端 zip 的载荷；- 若目录上传反复以
Could not reach OpenViking结束，而ov health正常、单文件导入正常，应怀疑上传超时或大目录载荷不稳定。
上传瘦身缓解措施
- 保持 OV 上传工件精简：必要的 ARA Markdown/YAML + 已归档的图/表 PNG 证据；
- 不要在上传目录内重复存放大型原始 PDF、源压缩包或抽取的临时文件（除非用户明确需要它们进入 OV）；
- 原始源文件保留在本地
source/或完整artifact/工作副本中，并在src/environment.md记录其路径； - 在保证可读性的前提下优化 PNG，例如全页渲染用 1.5x 代替 2x；
- 如需可创建独立上传副本（如
<artifact-dir>-ov/），而不要改动完整本地工件； upload.mode = "shared"有助于分布式部署，但不会让超大目录载荷变小。
断连恢复：把"等待中断"与"摄入失败"区分开
若ov add-resource --wait在目标已创建后因连接错误退出，应视为等待中断而非摄入失败，执行恢复检查：
ov -o json stat viking://resources/papers/<slug> ov wait --timeout 300 ov observer queue ov tree viking://resources/papers/<slug>判定规则：若stat显示isLocked=false、count非零、队列为空，且tree/read能访问内容，则报告"摄入已完成，但原--wait连接中断"；若目标不可见，则缩小上传载荷后重试。
权限与边界
技能对 Agent 的权限边界定义明确：
- 允许：用户要求添加/摄入论文时，可写入新的 OpenViking 资源；
- 必须先询问：故意复用可能覆盖/替换已有资源的目标 URI；
--skip-validation仅当用户明确接受所列校验错误时可用；- 禁止
ov add-skill：本技能创建的是论文资源而非 OV 技能； - 不得静默跳过
ov add-resource：摄入失败必须报告命令、错误与恢复路径； - 不得虚构claims、evidence、源引用、代码、数字或研究历史；
- 不得覆盖用户未指定的既有 OV 目标；不支持或不可读的内容标记为 unavailable，而不是编造填充。
收尾报告契约
ov-add-paper的最终回复必须包含：ov add-resource命令结果，或证明目标在--wait中断后仍然落地的恢复检查证据，或阻止摄入的确切阻塞点。references/openviking-ingest.md进一步要求报告：工件目录路径、目标 URI（或返回的根 URI）、--wait是否完成或需要恢复检查、校验摘要、以及摄入失败时的确切错误与恢复路径。同时不得隐藏异步摄入状态——若未使用--wait，必须说明处理在后台继续；不得在 CLI 失败时虚构成功的 OV URI。
在仓库中继续深入
- 技能本体与工作流： examples/skills/ov-add-paper/SKILL.md
- ARA 编译规范（证据账本、认知层、探索轨迹）： examples/skills/ov-add-paper/references/ara-compiler-profile.md
- OpenViking 摄入契约（推荐 CLI 流、上传坑、断连恢复）： examples/skills/ov-add-paper/references/openviking-ingest.md
- 确定性校验器（10 个必需文件、C##/E## 交叉引用、证据 PNG 兄弟文件检查）： examples/skills/ov-add-paper/scripts/validate_ara.py
ov add-resource命令入口（wait/timeout/include/exclude/strict 等参数）： crates/ov_cli/src/commands/resources.rs- 目录 zip 打包与上传的底层实现： crates/ov_cli/src/client.rs
仓库中的其他 ov-* 技能（如 examples/skills/ov-server-operate、examples/skills/ov-experience-memory、examples/skills/ov-resources）与 ov-add-paper 共同构成 OpenViking 面向 Agent 的技能体系，可以对照学习资源管理的不同侧面。
【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
