专利解读交付前的质量闸门:patent-disclosure-skill 的 patent_reader_self_check 自检清单全解析
专利解读交付前的质量闸门:patent-disclosure-skill 的 patent_reader_self_check 自检清单全解析
导读
patent_reader_self_check.md 是本项目专利通俗解读(阅读模式)工作流的交付前内部质量闸门:它把"解读笔记可以交付了"这一主观判断,拆解为 11 条可逐项勾选、可被 lint 脚本自动核验的硬性核对点,覆盖 Callout 结构、Frontmatter、权利要求树校对、附图闸门、术语网、入库状态、实现痕迹禁令、公开线索融合与交付话术。本文将逐条拆解这份清单背后的"为什么"与"怎么验",并深入到 lint_patent_note.py、validate_claim_tree.py、validate_public_clues.py、write_patent_obsidian_note.py 等实现,让你既会用清单,也理解每一项背后由哪个脚本、哪个字段、哪条规则在兜底。
自检清单在解读管线中的位置
自检发生在 patent_plain_reader.md 所定义的八步工作流末端:取证 → 结构化 → 技术线索 → 校对权项树 → 公开检索 → 计划 → 写笔记 → lint → 入库 → 交付。清单自身的"改笔记后重跑 lint → 入库"给出闭环,即自检不是终点,而是 lint 与入库之间的强制过门。
它本质上是把 lint_patent_note.py 的检查项翻译成人话,再加上脚本覆盖不到的流程性约束(如"入库状态里必须有 canvas""交付对话末尾要出示插件引导")。清单顶部特意注明"不写入交付笔记"——它属于 Agent 内部执行纪律,不是交付物的一部分。
L0 Callout:结构骨架的三件套
清单第一条要求 <a href="https://link.gitcode.com/i/1b3122b9d428d9ff2222c8df9060f067" target="_blank">!patent-meta]、[!grounding]、[!warning]- 三种 Callout 齐全,这直接对应 [obsidian_ofm_companion.md 中"必用 Callout 类型"表:
| Callout 语法 | 位置 | 职责 |
|---|---|---|
> [!patent-meta] 著录项 |
# 标题下、导航后 |
著录卡片(公开号 / 领域 / IPC) |
> [!grounding] 应用场景 |
第九节全文 | 应用场景的依据容器 |
> [!warning]- 公开检索线索 |
第十节 B | 推测线索(- 默认折叠) |
在 lint 脚本中这三者都是 issues(缺失即 FAIL):lint_patent_note.py 依次检查 <a href="https://link.gitcode.com/i/7361d7db1fcdb9e454857901977c80e1" target="_blank">!patent-meta]、[!grounding]、[!warning],任一缺失都会产出 missing_callout:* 硬错误。样式层由 [patent-reader.css 通过 cssclasses: patent-reader 挂钩,对 patent-meta、grounding、warning、patent-claim 等自定义 Callout 做专属渲染。[!warning]- 的折叠语法还承担"推测内容仅放折叠区、避免污染主结论"的语义隔离。
Frontmatter:三类字段的正确取值
清单要求 cssclasses: patent-reader、ipc、confidence_speculative 正确。完整字段集见 patent_obsidian_format.md 的示例:
tags:
- patents/化工与材料
- patent/evidence/full
- patent/speculative
cssclasses:
- patent-reader
pub_number: CN107785522B
domain: 化工与材料
ipc: H01M10/0525
evidence_scope: full_text
confidence_speculative: false
三个重点字段的取值规则:
evidence_scope:full_text|abstract_only|partial三选一。lint 中若evidence_scope=abstract_only却出现"保护范围"类断言且无"摘要级/仅摘要"字样,会触发abstract_only_but_claims_scope_asserted——摘要级证据不允许下保护范围结论。confidence_speculative:附录 B 含中/低置信线索时为true,对应标签patent/speculative。它是"推测内容已打标"的结构化声明,供 Bases 仪表盘筛选。ipc:lint 检查ipc:出现在笔记前 1200 字符内,或IPC出现在前 2500 字符内(lint_patent_note.py);同时若 context_anchor.json 中有domain,笔记前 1200 字符须含domain:或前 2000 字符出现该领域名(lint_patent_note.py)。
权利要求树:Agent 校对是主路径,脚本只兜底
清单要求 claim_tree.json 已经 Agent 校对(review.by=agent、父号/独立权正确、含"权1或2"类多引用)、单一树形表、"本项新增"来自 claim_deltas.json、勿 mermaid+表双份主展示。
为什么要 Agent 校对
patent_plain_reader.md 第 1.55 步说得很直白:抽取脚本只会用正则猜独立权与父号,遇"如权利要求1或2所述""权1至3"等极易错。多引用规则的裁定逻辑:
- 「权 A 或 B」→ 选依赖链上更合理的直接限定对象(通常选独立权,或原文主述项),不要留多个
parent; - 「权 A 至 C」→ 一般挂到区间内被进一步限定的那一项,拿不准时挂最小编号且已存在的独立权/父权。
校对的产物是回写 claim_tree.json 并增加 review 元数据,patent_plain_reader.md 给出了完整 JSON 形态:
{
"roots": [1],
"nodes": [
{ "number": 1, "is_independent": true, "parent": null, "text_preview": "…" },
{ "number": 5, "is_independent": false, "parent": 1,
"parent_candidates": [1, 2], "text_preview": "如权利要求1或2所述的…" }
],
"review": {
"by": "agent",
"status": "reviewed",
"notes": "权5「1或2」挂到独立权1;权12 父号由4改为6",
"corrections": [ { "claim": 5, "to_parent": 1, "reason": "或引多项,挂独立权1" } ]
}
}
校验脚本如何兜底
校对后必须重跑 validate_claim_tree.py:
python tools/patent_reader/analyze/validate_claim_tree.py \
-i tmp/patent_reader/${RUN}/claim_tree.json \
--write --require-review
其核心逻辑在 common.py 的 validate_claim_tree:独立权带 parent 报 independent_has_parent;从属权缺 parent 报 dependent_missing_parent;父号悬空报 parent_not_found;自引用报 parent_self。--write 会把规范化后的树(独立权清 parent、重建 roots、修正悬空父号)写回;--require-review 则强制 review.by=agent|human,防止跳过校对直接入库。multi_parent_candidates 只是 warning,校对后保留 parent_candidates 是允许的——这正是"多引用已人工裁定"的证据。
配套测试见 test_patent_reader_debt_fixes.py:test_claim_tree_multi_parent_and_validate 覆盖了多候选树校验与未校对告警路径。
单一树形表与"本项新增"
第三节树形表(◆/├─/└─)由入库脚本按已校对树渲染,"本项新增"列优先取 claim_deltas.json(每句 12~40 字、只写相对父权的增量),缺省权号才退回脚本启发式截句。lint 对第三节做了两条结构性检查(lint_patent_note.py):
- 节内既无"本项新增"也无
| 权 |表头 →section3_missing_claim_table(warning); - 同时出现
mermaid与| 结构 |表 →section3_mermaid_and_table_redundant(warning),呼应"勿 mermaid+表双份主展示"的清单项。
第九节无 URL,推测仅限 Callout
清单要求"第九节无 URL;推测仅在 <a href="https://link.gitcode.com/i/3e40937eaf734d2c7c25ea989763e0dd" target="_blank">!warning] 内",lint 对应两条硬性检查([lint_patent_note.py):
section9_missing_patent_grounding:第九节须含desc_、实施例、背景、说明书 \d{4}或"说明书段落"之一,确保应用场景有专利内依据而非凭空发散;section9_contains_url_use_appendix_b:第九节出现https?://直接 FAIL——外部线索一律下沉到附录 B 的[!warning]-折叠区,主结论区保持"可核验、无外链"。
这与 obsidian_ofm_companion.md 的"禁止在第九节写 URL""推测内容仅放在 [!warning]- 内"完全一致。
附图闸门:insert 嵌入,placeholder 只占位
清单要求"insert 图已嵌入;placeholder 仅 callout"。附图裁定来自 extract_patent_figures.py 产出的 figures/manifest.json:
decision=insert+ 质量 usable → 笔记第六节嵌入![[images/…]],入库脚本也会自动补嵌;decision=placeholder→ 仅[!figure]占位,不得当正式插图;quality=review默认按 placeholder 处理,追加--include-review才按 insert 处理。
lint 对附图是 warning 而非阻断(lint_patent_note.py):insert 决策的图若未在笔记中引用(文件名或相对路径、![[images/… 均未命中),产出 insert_figure_not_referenced:*。设计成 warning 的原因在源码注释里写得很清楚:写入阶段会自动补嵌,此处仅提示,避免 lint↔inject 时序死锁。需要强制嵌入时,入库可加 --strict-figures(要求笔记已嵌入,禁止只靠自动补嵌)。
术语网:file 节点或 stub,第五节必有 wikilink
清单要求"Canvas 术语为 file 节点或已建 stub;第五节有 wikilink"。术语网落地在 Research/术语/(PATENT_READER_GLOSSARY_DIR):
- 入库自动建 stub、Canvas file 节点、第五节 wikilink;stub 正文优先写入第五节"本文含义"一句,避免长期停留在"(待补充…)"空壳;
- 第五节优先写
[[Research/术语/术语名|术语]]; - 入库会合并
glossary_candidates与笔记第五节表/已有 wikilink 再建 stub、反链与 Canvas——这是对"extract 抽不到术语时术语网空白"的兜底。
术语 stub 与反链使得"术语-专利-图谱"形成双向可达网络,这也是后面 L1–L4 线索旁注能在术语层落点的前提。
入库状态:write_status.json 是交付前的硬凭证
清单要求"write_status.json 含 canvas / figures_inserted;索引含 Bases 嵌入"。入库命令见 patent_plain_reader.md,执行后输出结构在 write_patent_obsidian_note.py 中定义,关键字段:
written:笔记落地路径;canvas:图谱 Canvas 路径(文件存在才非空);description_paragraphs/claim_anchors:说明书段落与权项锚点旁路笔记;source_pdf/copy_source_pdf:官方 PDF 是否已拷入source/(默认拷,--no-copy-source-pdf关闭);obsidian+bootstrap:是否入库及 bootstrap 动作清单;figures_inserted:实际嵌入的附图文件名列表;clues_count/clues_dir:公开线索落地条数与clues/目录;moc_updated:全局_专利解读索引.md与领域索引的更新路径。
入库时自动 bootstrap_vault(CSS / Bases / 关系图 Groups),不需要再引导用户手动复制 CSS。索引页的 Bases 嵌入见 _专利解读索引.template.md:![[Research/Patents/patents.base#全部专利解读]]、#按领域、#含推测线索 三个仪表盘区块,并保留 Dataview 回退。因此"索引含 Bases 嵌入"是入库自动化的产物,自检只需确认它真的发生了。
实现痕迹禁令:交付物里不许出现流水线
清单要求"正文无 *.py、无 context_anchor.*、附图说明无 page_*_xref_*.png;无「(StructureSchema)」/「由 *_schema.json 入库」类脚注"。这是交付物洁癖的硬性纪律,lint 用一条正则兜底(lint_patent_note.py):
r"`?[a-z_]+\.py`?|context_anchor\.[a-z_]+|第\s*\d+\s*页\s*[·•]\s*`?page_\d+_xref_"
命中即报 user_facing_internal_tool_leakage(warning)。配套要求:
- 用户可见标题只用简洁名称("二、连贯叙事"而非"二、连贯叙事(故事线)");入库脚本
sanitize_user_facing_titles会幂等清理常见旧标题; - 结构/外观节标题用"结构说明""外观要点";连接关系"自/至"须为件号 + 名称而非仅数字件号;
- 附录"来源"只写"离线 IPC 行业词表"等自然语言;附图说明只写"第 N 页"。
结构连接表:自/至须含件号与名称
清单这条针对结构类(实用新型)与外观解读的连接关系表:仅写"件 1 → 件 2"无法让人理解装配语义,必须写成"件 1 壳体 → 件 2 卡扣"这类"件号 + 名称"形态。这与 obsidian_ofm_companion.md 的实现痕迹禁令同源——交付笔记面向读者而非流水线消费者。
公开线索 L1–L4:Agent 主路径的融合验收
清单这条最重,要求"导航入口;一/二/七/八/九旁注;权/特征点对点;附录 B + clues/ + Canvas;全文标「推测」、未污染说明书依据列;Agent 已写 summary(或明确 fetch_failed)"。其落点矩阵定义在 patent_obsidian_format.md:
| 层 | 位置 | 内容 |
|---|---|---|
| L1 | 导航「公开线索(N 条)」+ 文首 tip 入口 | 计数与入口 |
| L2 | 一/二/七/八/九旁注 | 各节角度不同的去重摘要;术语旁注优先用 anchor_fits |
| L3 | 第四节权项 / 第六节特征旁注 | 贴合句优先 anchor_fits;缺省才启发式;禁空号 F1–F6 |
| L4 | 附录 B + clues/ + Canvas「公开线索」分组 |
总表不重复展开 |
前置校验:validate_public_clues.py
Agent 写完 public_clues.json 后先跑 validate_public_clues.py,默认按置信度排序最多保留 3 条(DEFAULT_MAX_CLUES = 3,见 clue_vault.py,--max 可调)。校验规则(validate_clues):
- 缺
title/url→ issue;URL 非 http/https 或含example.com/localhost/127.0.0.1→ issue/warning; - 缺
confidence或取值不在{高,中,低,high,medium,low,med,mid}→ warning;reason过短(<8 字符)→ warning; - Agent 主路径应写
summary:缺 summary 且status != fetch_failed→missing_summary_agent_should_fetch(warning,可由脚本降级)。
anchor_fits:贴合句只能写可核验内容
anchor_fits 是硬性要求:Agent 读完线索页面/摘要全文后,为真正有对应的锚点各写一句贴合点(fit ≤ 40~80 字),kind 取 feature | claim | term。规则核心是只写页面上能核验的对应——摘要未点名的数值/尺寸特征不要硬编 fit,可省略该条或由脚本归入"另涉"。summary 写法要求 3~8 条要点或两三句连贯短文,禁止粘贴导航/页脚/面包屑;化学式写在同一行(如 Al2O3/勃姆石涂覆);不用行首 >(Obsidian 会变引用竖线)。
降级边界
入库脚本只做结构化落地与 L1–L4 融合,贴合句以 Agent anchor_fits 为准;脚本 HTTP 抓取仅当某条缺 summary 且显式传 --fetch-clues-fallback 时才尝试。换句话说:Agent 主路径负责"读"与"写贴合句",脚本只负责"搬"与"融合"。全部推测线索不得写进一至八主结论——这是"未污染说明书依据列"的底线。
测试侧有 test_validate_public_clues 与端到端管线测试 test_patent_reader_pipeline.py 双重复核 public_clues 校验与写回流程。
交付:插件引导出示在对话末尾
清单最后一条"已向用户出示插件引导(对话末尾,勿写入解读正文)"。交付第 7 步的标准动作是:给出笔记路径、Canvas 路径、索引页路径,加一句话结论、证据范围、应用场景要点,然后 Read obsidian_plugin_guide.md 并向用户出示插件安装引导(含社区插件 URL,页面预览/图谱/Bases 等依赖项)。这条在自检中属于流程性检查,lint 无法覆盖,只能靠执行纪律保证。
发现问题的处理:改 → 重跑 lint → 入库
清单末尾的闭环是"改笔记后重跑 lint → 入库"。lint 的退出码语义(lint_patent_note.py):
issues非空 → 输出FAIL <issue>并返回 1,阻断;须修到 passed;warnings不阻断(section3_missing_mermaid_optional、insert_figure_not_referenced:*等);- 通过时打印
OK lint passed,--output写 lint.json(含passed/issues/warnings/evidence_scope)。
修复后重新入库,write_status.json 会刷新 canvas / figures_inserted 等字段,形成"自检 → 修 → 验 → 入库 → 再核对状态"的收敛循环。
与主流程的关系与适用前提
自检清单只服务于阅读模式(反向解读),与交底书撰写主流程(intake → 交底书 Step 1–8)互不干扰。所有命令以 tmp/patent_reader/${RUN} 为运行目录、以 ${CLAUDE_SKILL_DIR} 为工具根路径,需要先按 patent_plain_reader.md 完成 Obsidian 环境探测(check_obsidian_env.py);无库时降级写 outputs/,自检中"入库状态""术语网""Bases 嵌入"等条目相应降级为"跳过但知晓损失"。此外,权利要求树校验、公开线索校验与 lint 的测试用例均已沉淀在 tests/patent_reader/,可作为你二次开发或扩展自检项时的回归基线。