Rubbing to knowledge

从拓片到知识网络（Rubbing-to-Knowledge）

一套面向古代碑帖与拓片研究的可复现工作流。它不是一个把图修得更好看的 工具，也不是一个能替你读碑的模型；它解决的是碑帖研究里真正会毁掉结论的那个 问题：从一张残损拓片到一条历史判断之间，每一步的来源、参数、坐标、审校 责任人和不确定性会在过程中丢失，于是最后没人能复核这个结论是怎么来的。

这套 Skill 把那条链固定下来，并且结构性地拒绝让机器输出变成史料事实。

1. 它解决什么研究问题

碑帖研究的实际流程是：鉴别材料 → 处理图像 → 识读文字 → 判断异文 → 核验 文献 → 考证人物纪年 → 修订或撤回结论。现有工具各自只覆盖一环，研究者手工 把它们串起来，于是出现四类可预期的事故：

1. 来源与派生谱系丢失。 分不清哪张是原图、哪张是调过对比度的，也说不清 参数是什么、许可是什么。
2. 增强被当成复原。 超分或补笔生成的笔画被写进释文，而那些像素在原物上 并不存在。
3. AI 候选被当成人工审校。 这不是假设——本项目自己发生过一次（见第 7 节），错误原件按原字节保留至今。
4. 失败与冲突被静默删除。 反证、获取失败、阻断本来是合法研究结果，却因为 "不好看"而不落盘，于是下一个人重复同样的错误。

对应地，这套 Skill 的每一条设计都是为了让上述四件事在软件层面做不到， 而不是靠使用者自觉。

2. 差异化：三条结构性约束（这是重点，不要跳过）

2.1 事实、推断、假说结构性分离

研究状态契约要求每一条内容归入五类之一，而且这不是命名约定——诚信审计会按类别 检查发布门，把「未经裁决的机器输出」「哈希断链」「零条主张的完成尝试」等情形判成 warn 或 block，只有没检出规则违反时才给 pass。pass 的含义仅是"未检出 规则违反"，从不表示某条历史主张为真。

类别	含义	例子
OBS	对原始材料的直接观察，未经处理	原拓片上某处笔画的可见状态
DER	确定性派生结果，可复现、可回退、保留父哈希	灰度/对比度/极性 baseline 图
SRC	可定位的外部来源证据，指向具体载体与位置	某版本某卷某叶某行
INF	由已有证据支持、可被反证的推断	"此人与某职官同期"
HYP	待检验假说或生成式候选，默认不是史料事实	OCR 候选字、AI 提议的关系

生成式补笔、超分结果、OCR 读数、AI 关系提议一律是 HYP。要变成可用的 研究判断，必须经过一次显式的、可追责的人工裁决记录。

2.2 每条主张都必须能回链

知识网络的证据链是三段式，任何一段都不能跳过：

CandidateMention  →  HumanAdjudicatedAssertion  →  EvidenceBackedGraphEdge
（软件可以产生）      （只有可信人工裁决能产生）      （只由已接受裁决确定性物化）

materialize 命令不接受任何边作为输入——边只能由已接受的裁决推导出来， 所以"手工塞一条好看的关系进图里"在 CLI 上没有入口。verify 会重走整条链、 重新推导投影，并把每一道门分别报出来。

2.3 失败是正式产物

invalid、null、stop_unresolved、human_review、block 都是类型化的 正式结果，会落盘、会进入路由决策、会阻塞后续步骤直到被显式解除。运行记录、 负结果、失败日志和复审结论只增不改；更正以追加方式写在原件旁边，原件字节 不动。

3. 12 个组件如何组合

主编排 Skill 是"大脑"，只管研究状态与路由，自身不做 OCR、修图、史料解释 或历史事实生成。其余 11 个是可替换、可独立复用的"手脚"。

研究问题（可被证伪的提法）
        |
        v
rubbing-research-orchestrator   研究状态 / 阶段门 / 路由 / 反思触发 / 打包
        |
        +---> 通用科研层（7 个，与碑帖无绑定，可迁移到别的研究领域）
        |
        +---> 碑帖领域层（4 个）
        |
        v
可追溯研究证据包，或者一个诚实的阻断

#	组件 Skill	层	它负责什么
1	rubbing-research-orchestrator	编排	ResearchCase 状态、阶段门、跨 Skill 路由、类型化决策（continue / reroute / rollback / human_review / stop_unresolved）
2	research-provenance-ledger	通用	只增账本：材料登记、SHA-256、大小、MIME、来源、许可、权利状态；重复 ID 与哈希漂移检测
3	research-source-acquisition	通用	单个已授权 URL 的获取：HTTPS 白名单、SSRF 抗性 DNS 与重定向检查、流式限额、MIME/magic 校验，落入不可变隔离区
4	research-quarantine-promotion	通用	隔离字节与内容感知工具之间的 B0 结构门：严格解析、同缓冲区身份、无内容泄露的结构报告
5	research-run-ledger	通用	不经 shell 执行命令，防篡改事件链，stdout/stderr 独立留存，输入输出快照与只增 checkpoint 链
6	research-literature-evidence	通用	预注册检索 → 精确定位的证据候选；查询、发现、失败、排除、不可获取、冲突、待核验全部落盘
7	research-hypothesis-reflection	通用	证据反馈后的复核：支持/反对冲突、负结果、依赖性证据、停滞检测；版本化 ReflectionMemo，旧假说不被覆盖
8	research-integrity-audit	通用	发布门审计：缺证据、未裁决的机器输出、无法追责的裁决记录、哈希断链、空洞的"完成"尝试
9	rubbing-image-preparation	碑帖	图像质量测量、拒收不安全输入、父哈希不可变、灰度/对比度/极性等确定性非生成式 baseline 与变体对比
10	rubbing-ocr-review	碑帖	OCR 候选绑定图像哈希与像素区域，空/失败结果一律保留，AI 预标与自称人工审校严格区分，人工审校交接
11	epigraphy-text-structure	碑帖	不可变外交文本层、物理阅读顺序、断句/加注/异体字规范化/元数据/人地职官纪年关系的待审提议
12	epigraphy-knowledge-network	碑帖	候选 → 人工裁决 → 证据边；确定性的时间轴、关系路径与实体查询（对应官方功能方向五）

对照官方五个功能方向：方向一（图像）→ 9；方向二（OCR）→ 10 与第 5 节的实测配置； 方向三（文本结构化）→ 11；方向四（人文知识网络）→ 12；方向五（检索与可视化）→ 12 的 query 子命令（时间轴 / 关系路径 / 实体，结果绑定图状态哈希与查询哈希）， 外加下面那个可以直接双击打开的离线页面。 方向一的生成式部分（去污、超分、补笔）见第 6.3 节的能力边界说明。

方向五有一个可以直接打开的产物：离线单文件可视化页面

knowledge-visualisation.html 把时间轴、人物关系网络与多维筛选渲染进一个 自包含的 HTML 文件：双击即开，不需要安装任何东西，不发一个网络请求，不引用 任何外部资源（构建清单实测 embedded_images: 0 / external_references: 0 / network_requests: 0）。它由仓库里的生成脚本 build-knowledge-visualisation.py 从已提交的图状态与查询结果确定性生成，页面上每一个数字都在同名构建清单里登记了 来源文件与推导规则，硬编码一个统计量会让构建失败。

它的数据是合成的（SYNTHETIC）。 背后的图状态自带 synthetic_policy.academic_use = prohibited、public_demo_use = prohibited、 publication_gate = block、real_world_referent = false，页面在四个独立层面 逐字声明这件事：首个实体标签之前的常驻横幅、两个视图内部的水印、每个对象详情里 的合成标记、以及把上述四个 policy 字段原样列出。它演示的是机制，不是任何历史 知识；把页面上的人物、纪年或关系当作研究结论，与页面自己的声明直接冲突。

在哪里找它：仓库里在 docs/research/visualisation/（页面 + 构建清单），提交包里 在 demo/knowledge-graph/。本根包既不含 docs/research/、也不含那个生成脚本， 所以页面不在你解压出来的这个包里，重建它要在仓库里做；仓库地址见第 10 节。

一次完整走向的顺序：

提出可证伪问题 → 登记材料/许可/原始哈希 → 诊断图像并建立确定性 baseline
→ OCR 候选与逐字坐标 → 低置信度与高影响判断交真人复核 → 按物理阅读顺序
形成外交文本与结构化候选 → 检索并定位支持证据与反证 → 反思：增强/降级/撤回/
改版假说 → 构建带证据边的知识网络与时间轴 → 诚信审计 → 导出证据包或阻断

4. 消费者第一步跑什么

环境要求：Python 3.9+，标准库即可。完全离线，不联网，不需要 API Key、 不需要任何云服务或本项目的凭证。只有 rubbing-image-preparation 与 rubbing-ocr-review 声明了第三方依赖（numpy / Pillow），见其各自的 requirements.txt；缺失时这两个 Skill 的相关命令报错，其余 10 个照常工作。

第一步：复算，不要相信本文档的数字

python3 scripts/verify-research-skills.py --output report.json
python3 -c "import json,sys; d=json.load(open('report.json')); print(d['status']); sys.exit(0 if d['status']=='pass' else 1)"

统一验证器逐个 Skill 跑测试，对每个测试子进程设 PYTHONNOUSERSITE=1， 只按该 Skill 自己的 requirements.txt 逐项授权它声明的发行包，无关的用户级 site-packages 全程进不来。耗时约 5–10 分钟（research-literature-evidence 与 research-run-ledger 的测试本身较慢），超过多数工具的 120 秒默认超时， 请放后台或提高超时。未装 numpy/Pillow 时 rubbing-image-preparation 会失败， 这是设计的信任边界，不是缺陷。

本包上的实测结果（2026-07-25，macOS arm64 / CPython 3.9.6，numpy 与 Pillow 已装）：

status: pass
12 个 Skill / 712 项 Skill 测试（其中 18 项 skip，见下）
3 个包级测试模块 / 67 项测试
合计 779 项，跨 Skill 合成集成检查 pass

这一组数字测的是你手上这个根包——由仓库里的组装脚本 build-root-skill-package.py 生成的那棵目录树，顶层 status: pass、退出码 0。

那 18 项 skip 全部是同一类原因，且每一项都自己写明了理由：它们校验的是 仓库里的历史记录（例如"按旧版本写成的文档是否仍然验证通过"、某次真实运行的 权利记录），而 docs/research/ 按设计不随本包分发，独立下载没有历史可复验。 skip 不是"测试被放过"：同一套测试在完整仓库的 git clone 工作树里跑， 0 项 skip、712 项全跑；那棵树上另有 8 个仓库级测试模块 392 项测试， 合计 1104 项，同样 status: pass、退出码 0，集成检查 pass。仓库侧比本包多出 的 5 个模块测的是"仓库怎么发布自己"（提交包构建、上传就绪度、操作单、可视化 产物、根包组装），对下载者没有意义，因此不随包分发。

有一种树确实会 fail，先说清楚它不是本包。 如果你不是解压本根包，而是把整棵 仓库导出成一个没有 .git 的目录（git archive HEAD，或从代码托管站下载 source zip），那 8 个仓库级模块里有 4 个会失败、顶层 status: fail、退出码 1：3 个因为 要查询 git 才能数出某份 SKILL.md 被多少 committed 记录钉住，1 个因为 ATTRIBUTION.md 复算需要被 .gitignore 排除的本机 data/。那棵树上 12 个 Skill 的 712 项同样全 OK——失败的是"仓库怎么发布自己"，不是 Skill 功能。 三种环境（git clone 工作树 / 本根包 / 无 .git 导出树）的逐条实测输出见随包的 docs/REUSE.md 第 3.4 节。

这些数字随开发推进会变（本节测于 2026-07-25）。以你自己跑出来的 report.json 顶层 status 为准，本节只说明在什么条件下测到了什么。

第二步：端到端跑一次跨 Skill 合成闭环

python3 scripts/run-synthetic-research-cycle.py ./cycle-out

零第三方依赖，串起编排 → 来源账本 → 反思 → 诚信审计四个 Skill，终态是 human_review / block，并且产物自声明 synthetic_only: true 与 historical_claims_permitted: false。这是"软件跑通 ≠ 学术结论成立"的最短 证据，也是理解本作品设计意图的最快路径。

第三步：读你要用的那个 Skill 自己的 SKILL.md

每个组件都是独立完备的：自带 SKILL.md、scripts/ 下的 CLI、references/ 下的离线 Schema 与契约、tests/ 下可单独运行的标准库 unittest。例如：

python3 -m unittest skills/research-provenance-ledger/tests/test_provenance_ledger.py
python3 skills/rubbing-research-orchestrator/scripts/orchestrate.py --help
python3 skills/epigraphy-knowledge-network/scripts/knowledge_network.py --help

单独复用某一个 Skill 时，把它的文件夹整个拿走即可；它不依赖本根包的其它部分。 唯一的例外是 research-quarantine-promotion，它的文档里有一条命令指向 research-source-acquisition（隔离字节的上游），单独拿走那一个文件夹时那条 命令会失效——所以本作品是一个根包，而不是十二个互不相认的上传。

5. 已实测的 OCR 配置（照抄，不要按直觉改）

来自本项目的门禁运行记录 OCR-TESSERACT-GATE-001（Tesseract 5.5.3 + tessdata commit ced78752cc61322fb554c280d13360b35b8684e4，在真实拓片图像上 实测）：

配置	字符数	退化 box（宽或高为 0）	结论
chi_tra + --psm 6	333	0（0%）	满足逐字坐标契约，用这个
chi_tra + --psm 5	374	175（46%）	近半字符拿不到坐标
chi_tra + --psm 3（自动版面）	1	0	在拓片上崩到 1 字符，不可用
chi_tra_vert（竖排模型）	133 / 4 / 8	全部 100%	不要用它取坐标

要点：碑帖是竖排书写，所以任何人的第一直觉都是选竖排模型 chi_tra_vert。 那恰好是唯一完全拿不到逐字坐标的配置——三次独立测试（上下文图、单字 cell、 裁切图）中退化率都是 100%，下游的表面限定器一个坐标都拿不到。请用 chi_tra 配 --psm 6 取逐字坐标，并且不要把 chi_tra_vert 用于坐标。

同一份记录明确不含任何准确率或 CER 数字，理由见第 6 节。

6. 诚实的现状：什么可跑、什么只是合成、什么还没有

评委与使用者请把这一节当作作品的一部分读，它和上面的功能列表同样重要。

6.1 只有合成通道可跑（真实通道故意 fail-closed）

• epigraphy-knowledge-network 1.0.0：端到端可跑的 lane 只有 synthetic-test-fixture。两条真实 lane 会被解析、报告并阻断，因为目前不 存在可信的权利、权威性与真人身份验证器。合成通道通过只证明契约成立， 不证明任何知识网络结论。
• epigraphy-text-structure 1.1.2：同样只有 synthetic-test-fixture 可正向 跑通；两条真实 lane、decision-append 与 export-publishable 故意 fail-closed。结构良好的真实输入并不因此就算合格。
• research-literature-evidence 1.2.0 的 synthetic-test-only lane 使用 明显虚构的字节，永久非学术、非公开。

6.2 真人审校尚未完成，且身份无法验证

审校身份模式是 self-attested-not-authenticated。系统可以报告"自称人工审校 的覆盖率"，但永远无法满足经认证的真人门禁——那道门在接入受信外部身份 验证之前恒为阻断，这一点写在 rubbing-ocr-review 的文档开头，不是脚注。 人工审校交接包已物化，但 human_review_completed: false。

6.3 本作品不产出的东西（加限定词也不产出）

• 任何历史学结论、释文或人物/纪年考证结果。 迄今为止一个都没有。
• 任何准确率 / CER / "哪个版本更好" 的数字。 计算它需要锁定样本 + 可信 真人真值 + 同模型同样本的对照；真人真值目前为 0 人完成，因此该判断悬置， 不得由任何代理代替。
• 可再分发的 OCR 模型权重。 四个候选全部 release_allowed_now: false， 卡住的原因各不相同（3 个未定位权重许可证正文，Tesseract 卡在非许可证类 门禁）。本包不携带权重，消费者需自行安装 tesseract 与 tessdata。
• "图像修复"意义上的生成式补笔。 官方赛题方向一里的去污、超分、残损笔画 补全，本作品只实现确定性、非生成式的 baseline 与变体对比；生成式结果 在设计上被归为 HYP，不作为史料证据。这是一个明确的能力边界，不是遗漏。

6.4 真实数据上的两次运行，结果都是"停下"

• 真实切片 001：固定 IIIF 图像 GET 返回 HTTP 403 → 正式结果 invalid → rollback → 类型化 reroute。处置明确拒绝伪装 UA、绕过防护、放宽重定向。 403 只被解释为获取方法失败，不外推为权利或学术结论。
• 真实切片 002：安全获取一幅公有领域数字影像，生成 4 路确定性派生图与 5 路 OCR 结果，比较报告确认 4 个 completed / 1 个 empty / 7 类具名机器差异， 不计算准确率、不评选最佳版本；两次反思均为 stop_unresolved，最终 类型化决策为 human_review，自动路由停止。

"系统在自动化边界上如实止步"就是本作品要展示的能力本身，不是失败。

7. 一次真实事故，原样保留

一次 AI 视觉预审曾被误标为人工复核。错误原件按原字节保留，更正以追加方式 写在旁边并逐条列出 6 条受影响的裁决，旧版本不改写；此后这条约束被做成机器 可执行的门（ai_advisory_satisfies_human_gate: false）。

我们把它写在作品说明里而不是删掉，因为一个声称"AI 输出不等于人工审校"的 系统，必须能证明它在自己犯这个错时也没有掩盖。

8. 可复用性与可扩展性

• 12 个组件各自独立：自带 SKILL.md、CLI、离线 Schema、可单独运行的 标准库测试。可以只取其中一个用在完全无关的研究领域——通用科研层的 7 个 Skill（来源、账本、隔离晋级、运行账本、文献证据、反思、审计）与碑帖毫无 绑定。
• 阶梯式 Schema 版本：新版本并存旧 Schema 文件，按旧字节写成的文档继续 按原样验证通过。升级不会让历史记录失效。
• 契约先于实现：references/ 下是离线 JSON Schema 与书面契约，替换某个 Skill 的实现只需满足同一份契约。
• provider-neutral：OCR 与模型调用不绑定任何厂商；比较是只读的，强制 参数与派生父链对账，不"选最佳"。
• 可审计的扩展点：想接入新的 OCR、新的图像方法或新的文献库，路径是先写 候选登记表与预注册（固定假说、变量、门禁、停止条件），再实现——而不是先 跑通再补理由。

9. 许可与知识产权

许可以随包的 LICENSE 为准；必要声明见随包的 NOTICE；第三方成分与出处见 ATTRIBUTION.md。以文件为准，不以本节的转述为准。

本包一张图像都不含（实测：包内 .png/.jpg/.jpeg/.tif/.webp 计数为 0）， 也不含模型权重、馆藏媒体或任何权利未清的资产。这不是遗漏而是权利门禁的结果： 本项目的候选登记表里 release_allowed_now: true 的条目数为 0，构建器读取权利 来源自行判定，凡解析不出明确清关的一律排除，且 CLI 上不存在任何 --force / --override / --allow-unknown-rights 之类可以推翻它的开关。

10. 完整证据在哪里

本包是可运行的能力包。它引用的每一条运行记录、负结果、失败日志与独立复审 结论都在项目仓库的 docs/research/ 下按只增不改的方式保存，包括本文档第 5、 6、7 节的每一个数字与结论的原始出处（OCR-TESSERACT-GATE-001、 REAL-RUBBING-SLICE-001 / -002、PRODUCT_CLAIM_LEDGER.md）。那些记录里 有相当一部分结论是 BLOCK 与 HOLD，它们同样被保留。

仓库：https://github.com/Lx050/rubbing-to-knowledge

如果本文档的任何一句话与包内实际文件冲突，以实际文件为准。