CAP 开放协议

CAP，即 CiteArk Artifact Protocol，是一套用于构建不可变、内容寻址、 可独立验证科研快照的开放协议。研究者、Agent、实验室或平台发布的不再只是 一组文件，而是 Claim、检验它的实验、真实发生的执行、观察到的证据以及基于 证据作出的有边界评估之间的结构化关系。

Claim → Experiment → Execution → Evidence → Assessment → Attestation

CAP 不绑定特定 Agent、模型、云平台或 Registry。一个结构有效的 CAP 可以证明 内容身份和内部绑定关系，但不能证明签名者一定可信、Assessment 一定正确、 结果已经由第三方独立重复，更不能证明整篇论文为真。

Record、Artifact 与 Bundle

CAP 将过去经常混在一个压缩包里的三个概念拆开：

一份研究计划、一次复现、失败运行、新参数实验或独立评估都可以形成 Artifact。Artifact 一旦以 摘要寻址就不再修改；重试和修订会产生新的 Artifact，并通过 derivedFrom、 revises、reproduces、extends 等关系连接历史版本。

Bundle 可以追加签名、当前下载位置、预览和公共元数据，而不改变底层 Artifact 身份。

Bundle 结构

CAP 1.0 的首个 Bundle 运输格式继续使用普通 tar+gzip：

artifact/
├── cap-manifest.json
├── records/
│   └── sha256/<prefix>/<digest>.json
├── blobs/
│   └── sha256/<prefix>/<digest>
├── attestations/
├── ro-crate-metadata.json
├── cap-locations.json
├── projections/
└── preview/

Artifact 只包括 canonical Manifest、已声明的 Record 字节和已声明的内嵌 Blob 字节。Attestation、位置、投影和预览属于 Bundle 附件。路径只负责定位字节， 永远不是科研对象身份。

消费者必须拒绝不安全或重复路径、链接、非普通文件，以及 records/ 或 blobs/ 中未声明的内容。

内容身份

稳定 Artifact 身份由精确的 RFC 8785 canonical Manifest 字节计算：

artifactDigest = SHA-256(JCS(cap-manifest.json))

Manifest 不保存自己的摘要。UUID 可以作为便于阅读的标签，真正的不可变地址是 sha256:<digest>。

所有规范性 JSON Record 都直接保存为 RFC 8785 JSON Canonicalization Scheme 字节：满足 I-JSON、按 UTF-16 排序键、使用 ECMAScript 基本值序列化规则、UTF-8 编码，并且没有多余空白或末尾换行。详见 RFC 8785。

科研十进制数值使用字符串，而不是普通二进制浮点数：

{
  "decimal": "81.900000",
  "unit": "percent"
}

重新打包相同 Artifact、修改预览、移动外部对象或追加 detached signature， 不会改变 artifactDigest；修改 root、Record、Blob 描述符或 Artifact 关系则会 生成新身份。

Manifest 与描述符

cap-manifest.json 声明协议版本、Artifact 创建者、Profiles、roots、Record 描述符、Blob 描述符与不可变外部关系。

{
  "$schema": "https://citeark.com/schemas/cap/v1/manifest.schema.json",
  "mediaType": "application/vnd.citeark.cap.manifest.v1+json",
  "specVersion": "1.0.0-alpha.1",
  "artifact": {
    "id": "urn:uuid:artifact-01",
    "createdAt": "2026-08-24T10:30:00Z",
    "createdBy": {
      "ref": "urn:uuid:actor-assembler",
      "digest": "sha256:..."
    }
  },
  "profiles": [
    "https://citeark.com/cap/profiles/core/1.0",
    "https://citeark.com/cap/profiles/reproduction/1.0"
  ],
  "roots": [
    {
      "role": "primaryClaim",
      "ref": "urn:uuid:claim-01",
      "digest": "sha256:..."
    }
  ],
  "records": [],
  "blobs": [],
  "relations": []
}

Record 描述符绑定逻辑 ID、语义类型、Schema、媒体类型、大小、摘要和当前 Bundle 路径。同一 Artifact 内可以只通过逻辑 ID 引用，因为 Manifest 会把它解析到唯一 摘要；跨 Artifact 引用还必须绑定目标 Artifact 摘要、Record 摘要与 Record 类型。

Blob 描述符同样使用 digest、size 与 media type，并有三种可用状态：

• embedded：精确字节在 Bundle 内；
• external：字节从外部获取，使用前重新验算摘要；
• withheld：敏感或受许可限制的字节不公开，但摘要承诺和访问策略仍可移植。

动态下载地址放在 Artifact 身份之外的 cap-locations.json。

科研 Records

CAP 1.0 定义七种科研 Record，并配套 Manifest 与描述符 Schema：

Execution 永远不能出现 reproduced: true。进程成功属于运行事实，Claim 是否 得到支持只能由 Assessment 表达。

Evidence 明确区分 observed、declared、inferred 和 attested。在 Agent 信任边界外确定性提取的指标会记录 parser、版本、配置、可用时的实现摘要以及 原始输入 Blob 摘要，避免 Agent 自报数字被静默升级为已验证证据。

Assessment 结论只包括 supports、challenges、contradicts 和 inconclusive。notAssessed 不是科研结论，而是不存在 Assessment，应当由 Registry 的覆盖视图表达。

独立复现也不再是布尔值。Assessment 分别记录 operator、implementation、 environment、hardware 和 data 的独立性。

盲化执行与策略承诺

执行 Agent 只接收 Experiment.publicContract。该契约不能暴露论文报告值、 容差、接受标准或私有验证策略。

协调器在执行前使用高熵随机 nonce 对私有策略作出承诺：

policyCommitment = SHA-256(JCS({
  algorithm: "citeark-policy-commitment-v1",
  nonce: <至少 128 bit 熵>,
  policy: <私有比较策略>
}))

执行完成后的 Assessment 再公开 policy 与 nonce，验证器重新计算 commitment。 这可以阻止看到结果后修改判断标准，也避免直接对低熵目标值做无盐哈希导致枚举 泄漏。

失败或部分执行仍然可以形成有价值的 Artifact。完整性失败或没有可信 Evidence 时，Assessment 必须是 inconclusive，不能虚构正面或负面结果。

Agent 工作流 1.0

CAP 1.0 的参考 Agent 工作流只有一条发布路径：

Research Compiler
  → Research Plan CAP
  → 盲化 Execution Contract 1.0 + 私有策略承诺
  → 隔离执行 + Execution Result 1.0
  → 沙箱外证据解析、完整性检查与 Assessment
  → Reproduction CAP --reproduces--> Research Plan Artifact Digest

Execution Result 1.0 只能报告执行状态、真实命令、代码改动、证据文件、科学输出和 局限性；它不能包含 verification 或 observedResult。正式数值由契约指定的确定性 解析器从原始 Evidence 提取，科研结论由独立评估器生成。

低层 run 目录只是崩溃恢复和审计输入，不是 Artifact。参考 CLI 不提供从裸 research.json、私有策略和任意 run 目录直接发布 CAP 的 pipeline replay 入口。 本地 pipeline execute 会生成研究计划与复现两个 .cap；平台流水线则只接受已经 验证并完成任务绑定的研究计划摘要。缺少 reproduces relation、目标 Claim 或 Experiment 不在已验证计划中、结果信封不是 1.0，都会失败关闭。

完整流水线记录十个阶段：研究结构化、研究计划快照、执行契约、计算调度、自主复现、 证据解析、结果验证、验证结论与卡片、产物封装、单文件封装。内部检查点可以恢复执行， 但不能跨越 CAP 信任边界或成为站点导入来源。

Profiles

CAP Core 保持最小，其他能力通过带版本的 Profile 增加约束：

未来的物理实验、仪器、样本或数学证明通过新增 Profile 扩展，不会为了覆盖所有 学科而不断扩大 Core。

Trace 不包含隐藏思维链

Agent Trace Profile 保存可观察的 NDJSON 事件流，包含递增 sequence、 eventType、occurredAt、observedAt、actor、execution、parent、inputs、 outputs 和 attributes；trace/span ID 可以借用 OpenTelemetry 约定。

CAP 可以记录获准公开的 prompt、模型与 Agent 身份、tool calls、命令、文件变化、 错误、重试和显式结构化决策，但永远不要求模型隐藏的 chain-of-thought。

Attestation 与信任

CAP 根 Attestation 是 detached Bundle 附件。推荐格式是 DSSE envelope 中的 in-toto Statement。 Statement subject 是 Artifact SHA-256，CAP predicate 记录 actor 和证明角色。

参考实现可以离线验证 Ed25519；公共发布可以使用 Sigstore Bundle，机构也可以使用自己的 PKI 或外部公钥解析策略。

验证报告会分别回答：

1. Artifact 结构是否符合协议？
2. 声明的 Record 与内嵌 Blob 字节是否完整？
3. 签名是否有效并绑定当前 Artifact？
4. 当前用途下是否信任签名者？
5. Assessment 作出了什么有边界的结论？
6. 是否有独立参与方发布了新的 Evidence 或 Assessment？

对完全相同的 Artifact 联署可以追加 detached Attestation；新增证据或科研判断则 必须生成引用原 Artifact 的新 Artifact。

权利与互操作

权利附着在每个 source 与 Blob 上。论文、仓库、数据集、模型和本次生成的 checkpoint 可能拥有完全不同的条款；CAP 不授予再分发权，也不允许一个全局 license 覆盖这些差异。

CAP 通过投影或 envelope 复用已有标准：

• RO-Crate 1.3：公共科研 对象元数据；
• Workflow Run RO-Crate：已有工作流 provenance；
• W3C PROV：Entity、Activity 与 Agent 映射；
• SPDX 3.0.1：软件、模型、数据集、构建和权利 清单；
• in-toto 与 DSSE：经过认证的 metadata；
• OCI descriptor：未来 Registry 运输形式。

这些投影不能覆盖 canonical CAP Record 内容或摘要。

流水线与平台导入

CiteArk 流水线使用两层 CAP 1.0 快照，不经过专用平台导入包：

Research Compiler
  → Research Plan CAP
  → SourceWork / all Claims / planned Experiments / declared Evidence
  → trusted verification and research-plan import

each blinded reproduction target
  → Reproduction CAP --reproduces--> Research Plan Artifact Digest
  → Experiment / Execution / observed Evidence / Assessment

raw evidence + typed outputs
  → content-addressed Blobs + Evidence Records
private policy reveal + comparisons
  → Assessment Record
runner identity + processing binding
  → Actor Records + detached DSSE Attestation

Research Plan CAP 使用 research-plan/1.0 Profile，不包含 Execution 或 Assessment； 论文中的报告值只能记录为 basis: declared。计划 Experiment 在此阶段可以不含私有 验证策略承诺，实际调度后生成的 Reproduction CAP 则必须绑定承诺，并在 Assessment 中揭示。每个 Reproduction CAP 必须通过 Manifest reproduces relation 固定已导入的 Research Plan Artifact Digest。

内部 Research Compiler 检查点只用于崩溃恢复。它没有 CAP Artifact 身份，也不能 直接建立仓库、Claim 或实验投影；因此不存在“pending”签名或占位证明跨越信任边界。

小型 Blob 内嵌在 Bundle；大型 Blob 以 external 描述符进入 Artifact，工作节点先按 digest 单独上传对象，再上传 .cap。平台导入时会重新验证归档摘要、Artifact Digest、所有 Record、内嵌 Blob、策略承诺揭示、可信 Ed25519 DSSE，以及证明中的 jobId、repositoryId、源摘要和基础提交绑定。任何一步失败都不会建立站点记录。

平台先从经过验证的 Research Plan CAP 建立仓库、Claim 与计划实验投影，再从经过 验证且正确引用计划摘要的 Reproduction CAP 建立运行、证据和 Assessment 投影。 导入器还会逐项核对复现包中的 Claim 与 Experiment 版本确实存在于这份已验证计划， 不能只凭一个正确的父摘要执行计划外目标。 projections/citeark/ 与 preview/ 仅用于界面和可读导出，不是导入权威来源；CAP 1.0 中不存在 platform/import-bundle.json，也没有旧 manifest 的兼容分支。

验证与封装

参考 CLI 只处理 CAP 1.0：

cd agent
node src/cli.mjs cap verify --dir ./artifact
node src/cli.mjs cap pack --dir ./artifact --output ./artifact.cap
node src/cli.mjs cap verify --file ./artifact.cap

CAP 1.0 验证器会安全解包 Bundle、解析精确 canonical Manifest、计算 artifactDigest、校验描述符、复算每个 Record 与内嵌 Blob、解析引用、应用已支持 Profiles、检查 policy reveal，最后验证 detached Attestations。

没有 cap-manifest.json、使用其他 specVersion、归档内缺少 CAP 1.0 Manifest， 或者使用 .citeark 后缀的输入都会被拒绝。外部论文、仓库或数据包若要进入 CAP， 导入器必须创建新的 CAP 1.0 Artifact 并记录来源与转换 provenance，不能直接改名。

结构一致性、内容 materialization、签名有效性、签名者信任和科研 Assessment 会 分开报告。CLI 的 valid 退出状态永远不是科研真理分数。

CiteArk 仓库中的参考资料：

• agent/protocol/CAP.md：规范正文；
• agent/protocol/profiles/：Profile 规则；
• agent/protocol/MAPPINGS.md：标准映射；
• agent/schemas/cap/v1/：九个 JSON Schema；
• agent/protocol/conformance-v1.0-alpha.1.json：公共测试向量；
• agent/src/cap/v1/：参考实现。

协议、Schema 和一致性向量使用 CC0 1.0。这不会改变 CAP Artifact 所引用科研 材料原本拥有的权利。