企业官网建设流程全解析

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用

当一篇稿件的主文依赖补充图片、表格、数据、方法或注释（supplementary figures, tables, data, methods, notes）时，仅仅把补充文件打包进目录远远不够——投稿系统与审稿人需要知道"主文哪一句声明、由哪份补充材料支撑、上传到期刊门户的又是哪一个文件"。PaperSpine 通过supplement_evidence_index.py提供了一套 fail-closed（失败即阻断）的校验器，把这类依赖关系建模为一份"双向契约"（bidirectional contract），并配套 JSON Schema 与结构化报告输出。读完本文，你将掌握该索引的字段设计、校验规则、命令行用法，以及它如何与投稿清单（submission_inventory）联动守住"作者审批"与"外部投稿授权"的边界。

何时需要它：使用场景与触发条件

根据 supplement-evidence-index.md 的定义，只要稿件依赖以下五类补充物中的任意一类，就应当使用该机制：

• figure（补充图）
• table（补充表）
• data（补充数据）
• method（补充方法细节）
• note（补充说明/注释）

在完整的投稿工作流中，它位于 submission.md 的 Workflow 第 5 步：当主文依赖补充证据时，创建supplement_evidence_index.json并运行supplement_evidence_index.py，每个承载声明（claim-bearing）的条目都必须链接到主文定位符、真实补充说明/章节、出版资产、上传产物以及语义像素审查回执。方法路由表 current-method-routing.json 将其标记为覆盖evidence、draft、review、delivery四个阶段的方法，并强调"无补充依赖时不伪造补充项"。

核心概念：双向契约，而不是文件名清单

索引的第一原则是：它不是一份文件名列表，而是一份双向可追溯契约。每个承载声明的补充条目需要同时记录"从主文到补充"和"从补充回到主文"两个方向的连接：

1. 主文侧：声明 ID（claim ID）与字面定位符（literal locator，即主文中实际出现的文字片段）；
2. 补充侧：补充材料的题注（caption）或章节定位符；
3. 文件身份侧：出版资产（publication asset，如排版后的正式版）与实际上传产物（upload artifact），二者各自绑定 SHA-256 哈希；
4. 语义侧：渲染表面摘要（rendered-surface summary）与独立保存的语义审查回执（semantic-review receipt）；
5. 科学角色侧：该条目的科学角色——支持主声明（support）、边界情况（boundary case）、稳健性检验（robustness check）、方法细节（detailed method）或次要结果（secondary result）。

这样，索引在"主文声明 ↔ 补充内容 ↔ 上传文件"之间建立了可验证的对应关系，任何一侧发生漂移（例如改版后图注与主文定位符不再匹配），校验器都能在投稿前拦截。

索引文件的字段设计：JSON 结构与完整示例

索引文件的结构由 supplement-evidence-index.schema.json 严格定义，schema_version固定为1.0。顶层必需字段为：schema_version、package_root、main_manuscript、supplementary_material、claims、items、submission_inventory。

一个可直接参考的完整示例：

{ "schema_version": "1.0", "package_root": ".", "main_manuscript": { "path": "manuscript/main.tex", "sha256": "9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08" }, "supplementary_material": { "path": "supplement/supplementary_material.pdf", "sha256": "60303AE22B998861BCE3B28F33E6F0C8F9F9E4E6B4F0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F60718" }, "claims": [ { "claim_id": "C1", "text": "The proposed model improves F1 by 4.2 points.", "main_text_locator": "improves F1 by 4.2 points", "requires_supplement": true } ], "items": [ { "supplement_id": "S1", "kind": "figure", "scientific_role": "support", "supported_claim_ids": ["C1"], "main_text_locators": ["improves F1 by 4.2 points"], "supplement_locators": ["Figure S1: Precision-recall curves"], "publication_asset": { "path": "supplement/figure_s1_publication.png", "sha256": "60303AE22B998861BCE3B28F33E6F0C8F9F9E4E6B4F0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F60718" }, "upload_artifact": { "path": "supplement/upload/figure_s1.tiff", "sha256": "60303AE22B998861BCE3B28F33E6F0C8F9F9E4E6B4F0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F60718" }, "semantic_validation": { "status": "pass", "rendered_surface_summary": "Rendered figure S1 shows the same curves as the source plot.", "caption_summary": "Caption matches the plotted precision-recall curves.", "review_receipt": { "path": "supplement/review/s1_semantic_review.json", "sha256": "60303AE22B998861BCE3B28F33E6F0C8F9F9E4E6B4F0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F60718" } } } ], "submission_inventory": [ { "item_id": "upload-figure-s1", "required": true, "state": "ready", "artifact": { "path": "supplement/upload/figure_s1.tiff", "sha256": "60303AE22B998861BCE3B28F33E6F0C8F9F9E4E6B4F0C1D2E3F4A5B6C7D8E9F0A1B2C3D4E5F60718" } } ] }

字段速查表

文件对象统一要求path（相对于package_root）与sha256（正则^[0-9A-Fa-f]{64}$，见 supplement_evidence_index.py）。

校验器如何工作：逐项对照源码的检查清单

实现位于 supplement_evidence_index.py，入口为check_index()（第 75 行起）。它采用fail-closed（失败即阻断）策略：任何一条 blocker 都会让最终状态变为BLOCKED，退出码非零。校验按以下顺序进行：

1. 结构与根目录安全：payload必须是 JSON 对象、schema_version必须为1.0；package_root解析后必须存在。所有路径先经_safe_path()（第 32 行）解析，并通过candidate.relative_to(root)检查，路径逃逸 package_root 会被直接列为 blocker——这是防止索引引用包外私人文件的关键防线。
2. 文件哈希：_file_entry()（第 48 行）校验每个文件对象的sha256格式（64 位十六进制），并逐块（1 MiB 分块，第 27 行）重算文件真实哈希比对，不一致即阻断。main_manuscript与supplementary_material同样走此路径。
3. 声明（claims）：至少 1 条；claim_id非空且唯一；main_text_locator必须以字面形式存在于主文文本中（locator not in main_text即阻断，第 113 行）——这是"字面定位符"的含义：不能用章节编号代替实际文字。
4. 补充条目（items）：至少 1 条；supplement_id非空且唯一；kind必须在五类枚举内；scientific_role必填；supported_claim_ids非空且每个引用的声明必须已定义；main_text_locators与supplement_locators中的每个元素都必须分别在主文/补充材料的原文中检索到（第 154-164 行）；publication_asset与upload_artifact均须为有效文件对象。
5. 语义验证（semantic_validation）：必须是对象；status只能是pass或blocked，且blocked直接阻断；rendered_surface_summary与caption_summary必填；review_receipt必须是真实存在的文件（第 168-185 行）。
6. 覆盖闭合性：任何requires_supplement: true的声明若没有被任何条目引用，会得到 blocker：requires supplementary support but no item links to it（第 194-196 行）。这一步保证"依赖补充证据的声明必然有补充支撑"。
7. 投稿库存（submission_inventory）：见下一节。

每条目的逐项结果（supplement_id、valid、supported_claim_ids）会汇总进报告的item_results，便于定位是哪一个补充项失败。

命令行用法与报告输出

文档给出的标准命令（PowerShell 续行符写法）：

python src/scripts/supplement_evidence_index.py path/to/supplement_evidence_index.json ` --write-report path/to/supplement_evidence_index_report.json

参数由parse_args()（第 258 行）定义：位置参数index为索引文件路径，可选参数--write-report指定报告输出路径。脚本会先解析索引 JSON，调用check_index()生成报告，随后：若指定--write-report，自动创建父目录并写入报告；最后打印报告，状态为PASS时退出码为 0，否则为 1（第 265-275 行）——因此它可以干净地接入 CI 或投稿打包脚本的退出码判断。

报告 JSON 的关键结构（源码第 240-255 行直接生成）：

{ "schema_version": "1.0", "status": "PASS", "package_root": "/abs/path/to/package", "signals": { "supplement_evidence_index_valid": true, "submission_inventory_complete": true, "external_submission_ready": false }, "item_results": [ { "supplement_id": "S1", "valid": true, "supported_claim_ids": ["C1"] } ], "evidence_blockers": [], "inventory_blockers": [], "blockers": [], "warnings": [], "completion_boundary": "A valid local index does not establish author approval or authorize external submission." }

注意两个值得警惕的设计：

• signals.external_submission_ready恒为false——本地校验通过绝不等于获得投稿授权；
• 当submission_inventory为空时，只产生 warning（supplementary evidence can pass, but package completeness was not assessed，第 234-235 行），证据索引本身仍可 PASS，但包完整性未被评估——这正是文档强调"补充证据通过 ≠ 投稿包完整"的实现体现。

submission_inventory：投稿上传面与作者审批边界

submission_inventory记录期刊要求的各个上传面（upload surface）。每个条目含item_id、required、state，可选artifact与justification，状态枚举为ready/needs_author/not_applicable。校验规则（第 200-235 行）：

• item_id非空且唯一；
• required: true且状态为needs_author→ 阻断，因为"必需项仍等待作者输入"意味着包不完整；
• required: true且状态为not_applicable时，必须有至少 12 个字符的具体理由（justification），防止滥用"不适用"跳过必需项；
• 状态为ready时，artifact必须是真实存在的文件对象（含哈希校验），否则submission_inventory_complete置为false。

这与文档中的两条边界完全对应：必需项处于needs_author会阻断包完整性；本地 PASS 永远不能替代作者审批，也永远不能授权外部投稿。作者身份/顺序、声明、伦理与知情同意等事实，必须由作者本人提供或确认（参见 submission.md 的 Workflow 第 7 步）。

能力边界：检查器不做什么

文档明确划定了检查器的职责边界，这也是使用该工具最容易踩的坑：

• 不检查像素：check_index()只做结构、定位符、哈希、语义状态字段与审查文件存在性校验，它不会真的打开图片比较像素；
• 不确立评审独立性：review_receipt文件的存在只证明"有一份回执"，不能证明评审者真的独立审查过；
• PDF 合法或检查 PASS 不等于科学批准：一份技术上有效（technically valid）的 PDF 或一份检查 PASS，都不能替代真正的独立评审。

因此文档要求：独立评审者必须实际打开当前补充材料，逐项比对补充内容、题注与所支撑的声明，并把结论保留在同一任务的评审笔记中。这正是"双向契约"语义层面的闭环——脚本负责机器可验证的部分，人负责语义可验证的部分。方法路由 current-method-routing.json 对补充证据索引条目的review_check同样写明："附件存在/PDF 合法不足，主张依赖必须有真实支撑；匿名/作者信息按目标范围，不自动上传。"

在完整投稿流程中的位置与快速自检清单

在 submission.md 的八步投稿工作流中，本工具在第 5 步发挥作用，与第 6 步的rules-check --phase writing、第 8 步的不可变 bundle 组装衔接：只有每个适用的必需项都ready且最终结构化期刊规则复查通过，才会生成上传 ZIP。

生成或复核索引时，建议按以下清单自检：

1. 每个claim_id是否唯一，main_text_locator是否能在主文原文中字面检索到？
2. 每个supplement_id是否唯一，supplement_locators是否能在补充材料原文中字面检索到？
3. publication_asset与upload_artifact的sha256是否真实对应磁盘文件？
4. semantic_validation.status是否为pass，且三要素（渲染摘要、题注摘要、审查回执文件）齐全？
5. 所有requires_supplement: true的声明是否都被至少一个条目覆盖？
6. 每个required投稿项是否处于ready，needs_author与not_applicable是否都有真实依据？
7. 脚本退出码是否为 0，报告中blockers是否为空？
8. 是否有一位独立评审者真正打开过补充材料并留档？

该索引的实现文件、Schema 与方法路由在仓库中均有完整对应：脚本 supplement_evidence_index.py、契约 supplement-evidence-index.schema.json、指南 supplement-evidence-index.md，且三者被 test_skill_structure.py 纳入技能结构完整性校验。需要部署到各 Agent 宿主时，dist/下的 claude/codex/hermes/openclaw 目录各自携带同版本的脚本、指南与 Schema 副本，例如 dist/claude/skills/paper-spine/scripts/supplement_evidence_index.py。

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用