docling-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docling Graph

Use this skill when the task is specifically about Docling Graph: converting documents into typed Pydantic knowledge graphs, reviewing templates, choosing extraction contracts, tuning pipeline configuration, inspecting/debugging extraction runs, and exporting graph outputs.

Do not use it for generic Docling document parsing, vector-only RAG, graph database administration, ontology-only modeling with no Docling Graph run, or unrelated PDF tooling.

当任务专门围绕Docling Graph展开时使用此技能：将文档转换为类型化Pydantic知识图谱、评审模板、选择提取契约、调整流水线配置、检查/调试提取运行以及导出图谱输出。

请勿将其用于通用Docling文档解析、仅向量型RAG、图数据库管理、未运行Docling Graph的纯本体建模或无关的PDF工具操作。

Dispatch

调度规则

Interpret

$ARGUMENTS

[mode] [source-or-template-or-question] [options]

. If

$ARGUMENTS

is empty, ask for the minimum missing context instead of assuming a document, provider, or extraction contract.

$ARGUMENTS pattern	Mode	What to produce
`plan [documents/domain]`	Plan	End-to-end workflow plan, template strategy, provider/config choices, validation path
`template [domain]`	Template	Pydantic graph template or review notes with stable IDs and relationship hints
`contract [direct	staged	delta] [domain]`
`convert [source] [template]`	Convert	CLI/API run recipe with inputs, provider/model overrides, output paths, and validation
`api [source] [template]`	API	Python integration using `PipelineConfig` and explicit override fields
`inspect [output-path]`	Inspect	HTML/debug inspection workflow for an existing or planned output directory
`export [output]`	Export	JSON/CSV/Cypher/NetworkX export and post-export checks
`debug [error-or-output]`	Debug	Root-cause path using logs, `debug/trace_data.json` , stage artifacts, and schema checks
`batch [folder]`	Batch	Scaling plan for many documents, manifests, retries, idempotency, and QA sampling
Natural language	Auto-detect	Classify first, then run the matching mode
Empty/unclear	Clarify	Ask for the document type, target graph, run surface, and provider constraints

将

$ARGUMENTS

解析为

[模式] [源/模板/问题] [选项]

。若

$ARGUMENTS

为空，应询问缺失的必要上下文，而非默认假设文档、提供者或提取契约。

$ARGUMENTS 格式	模式	输出内容
`plan [documents/domain]`	规划	端到端工作流规划、模板策略、提供者/配置选择、验证路径
`template [domain]`	模板	带有稳定ID和关系提示的Pydantic图谱模板或评审笔记
`contract [direct	staged	delta] [domain]`
`convert [source] [template]`	转换	包含输入、提供者/模型覆盖配置、输出路径及验证步骤的CLI/API运行方案
`api [source] [template]`	API	使用 `PipelineConfig` 和显式覆盖字段的Python集成代码
`inspect [output-path]`	检查	针对现有或规划输出目录的HTML/调试检查工作流
`export [output]`	导出	JSON/CSV/Cypher/NetworkX导出及导出后检查流程
`debug [error-or-output]`	调试	利用日志、 `debug/trace_data.json` 、阶段产物和schema检查的根因分析路径
`batch [folder]`	批量	多文档处理的扩容方案，包含清单、重试、幂等性和QA抽样策略
自然语言描述	自动检测	先分类任务类型，再执行匹配模式
空值/模糊描述	澄清	询问文档类型、目标图谱、运行载体和提供者约束

Auto-Detection

自动检测逻辑

Mentions
```
direct
```
,
```
staged
```
,
```
delta
```
, extraction contract, structured output, schema enforcement, sparse checks, gleaning, or streaming -> Contract.
Mentions
```
inspect
```
, HTML report,
```
trace_data.json
```
, debug artifacts, output directory review, or failed graph mapping -> Inspect or Debug.
Mentions Pydantic models,
```
BaseModel
```
,
```
Field
```
, relationships, entities, or
```
edge()
```
-> Template.
Mentions command line,
```
docling-graph convert
```
, provider/model flags, source file paths, or output directories -> Convert.
Mentions
```
PipelineConfig
```
,
```
run_pipeline
```
, Python integration,
```
provider_override
```
,
```
model_override
```
, or programmatic runs -> API.
Mentions graph exports, Cypher, Neo4j, NetworkX, CSV, or graph JSON -> Export.
Mentions folders, many PDFs, retries, throughput, manifests, or QA sampling -> Batch.
Otherwise ask one concise clarification question before prescribing a workflow.

提及
```
direct
```
、
```
staged
```
、
```
delta
```
、提取契约、结构化输出、schema校验、稀疏检查、信息收集或流处理 -> 契约模式。
提及
```
inspect
```
、HTML报告、
```
trace_data.json
```
、调试产物、输出目录评审或图谱映射失败 -> 检查或调试模式。
提及Pydantic模型、
```
BaseModel
```
、
```
Field
```
、关系、实体或
```
edge()
```
-> 模板模式。
提及命令行、
```
docling-graph convert
```
、提供者/模型参数、源文件路径或输出目录 -> 转换模式。
提及
```
PipelineConfig
```
、
```
run_pipeline
```
、Python集成、
```
provider_override
```
、
```
model_override
```
或程序化运行 -> API模式。
提及图谱导出、Cypher、Neo4j、NetworkX、CSV或图谱JSON -> 导出模式。
提及文件夹、多PDF文件、重试、吞吐量、清单或QA抽样 -> 批量模式。
其他情况先提出一个简洁的澄清问题，再给出工作流建议。

Gallery

示例场景

User asks	Response pattern
"Create a template for SEC filings"	Produce Pydantic models with graph ID fields, relationship fields, extraction notes, and a validation checklist.
"Should this use staged extraction?"	Compare direct, staged, and delta contracts against schema size, nesting, cardinality, provider limits, and debug cost.
"Run this PDF with OpenAI"	Provide a `docling-graph convert` command and API equivalent with provider/model overrides and output checks.
"Review this output folder"	Walk `inspect` , graph JSON, `debug/trace_data.json` , stage artifacts, and schema/sparse-check results.
"The graph is missing relationships"	Diagnose template relationship modeling, extraction contract, structured-output fallback, gleaning, and graph mapping artifacts.
"Export to Neo4j"	Generate export steps plus uniqueness constraints, ID normalization, and relationship-count checks.

用户提问	响应模式
"为SEC filings创建模板"	生成带有图谱ID字段、关系字段、提取说明和验证清单的Pydantic模型。
"是否应该使用staged提取？"	对比direct、staged和delta契约在schema规模、嵌套程度、基数、提供者限制及调试成本方面的差异。
"用OpenAI处理这个PDF"	提供 `docling-graph convert` 命令及等效API代码，包含提供者/模型覆盖配置和输出检查步骤。
"评审这个输出文件夹"	引导执行 `inspect` 流程，查看图谱JSON、 `debug/trace_data.json` 、阶段产物及schema/稀疏检查结果。
"图谱缺少关系"	诊断模板关系建模、提取契约、结构化输出降级、信息收集及图谱映射产物的问题。
"导出到Neo4j"	生成导出步骤，包含唯一性约束、ID规范化和关系计数检查。

Workflow

工作流步骤

1. Classify Scope

1. 范围分类

Start every response by deciding whether the task is Docling Graph-specific.

In scope: document-to-typed-knowledge-graph extraction, Pydantic graph templates,
```
docling-graph
```
CLI/API runs, extraction contracts, inspect/debug artifacts, and graph exports.
Out of scope: plain Docling conversion, embeddings-only pipelines, generic LLM extraction, graph database tuning, ontology design without Docling Graph execution.

If out of scope, state the boundary and suggest the closest appropriate skill or workflow.

每次响应先判断任务是否属于Docling Graph专属范畴。

范围内：文档到类型化知识图谱的提取、Pydantic图谱模板、
```
docling-graph
```
CLI/API运行、提取契约、检查/调试产物、图谱导出。
范围外：普通Docling转换、仅嵌入向量的流水线、通用LLM提取、图数据库调优、未执行Docling Graph的本体设计。

若超出范围，说明边界并建议最接近的合适技能或工作流。

2. Gather Minimal Inputs

2. 收集必要输入

Only ask for missing inputs that change the answer:

Document type and examples: PDF/HTML/DOCX/image, expected length, scanned vs digital, table density.
Graph target: entities, relationships, IDs, required fields, downstream consumer.
Template state: none, draft Pydantic model, existing package/module, or failing template.
Run surface: CLI, Python API, batch job, CI, or notebook.
Provider constraints: OpenAI, Mistral, Gemini, Watsonx, local Ollama/vLLM/LM Studio, privacy/cost/latency limits.
Extraction contract: direct, staged, delta, or undecided.
Debug context: command/API config, output directory, logs,
```
debug/trace_data.json
```
, and exact error.

仅询问会影响答案的缺失信息：

文档类型及示例：PDF/HTML/DOCX/图片、预期长度、扫描件 vs 数字化文档、表格密度。
目标图谱：实体、关系、ID、必填字段、下游使用者。
模板状态：无、草稿Pydantic模型、现有包/模块或失效模板。
运行载体：CLI、Python API、批量任务、CI或笔记本。
提供者约束：OpenAI、Mistral、Gemini、Watsonx、本地Ollama/vLLM/LM Studio、隐私/成本/延迟限制。
提取契约：direct、staged、delta或未确定。
调试上下文：命令/API配置、输出目录、日志、
```
debug/trace_data.json
```
及具体错误信息。

3. Choose the Extraction Contract

3. 选择提取契约

Docling Graph supports three contract styles. Make the choice explicit for non-trivial workflows.

Contract	Use when	Main risks	Required checks
`direct`	Small, stable schemas; limited nesting; provider handles full schema in one pass	Context overflow, weak relationship coverage	Schema fit, sparse-check results, field coverage
`staged`	Large templates with clear sections or nested entity groups	Stage boundaries can drop cross-stage links	Stage outputs, root merge rules, relationship counts
`delta`	Complex/high-cardinality graphs, weak source ordering, or incremental enrichment	Resolver quality and stable IDs dominate correctness	ID strategy, resolver config, duplicate entity checks

Structured output and schema enforcement should be preferred when the provider supports it. If unavailable or brittle, document the fallback parser, sparse-check setting, and extra validation pass. Use gleaning for recall-sensitive extraction, and enable LLM streaming when long runs need live progress or cancellation visibility.

Docling Graph支持三种契约类型。对于非简单工作流，需明确选择依据。

契约类型	适用场景	主要风险	必要检查
`direct`	小型稳定schema、有限嵌套、提供者可一次性处理完整schema	上下文溢出、关系覆盖不足	Schema适配性、稀疏检查结果、字段覆盖率
`staged`	大型模板且有明确分段或嵌套实体组	阶段边界可能丢失跨阶段链接	阶段输出、根合并规则、关系计数
`delta`	复杂/高基数图谱、源数据排序混乱或增量 enrichment	解析器质量和稳定ID决定正确性	ID策略、解析器配置、重复实体检查

若提供者支持，优先选择结构化输出和schema校验。若不可用或不稳定，需记录降级解析器、稀疏检查设置及额外验证步骤。针对对召回率敏感的提取任务使用信息收集功能，当长时运行需要实时进度或取消可见性时启用LLM流处理。

4. Apply Mode Protocol

4. 应用模式协议

Plan

规划模式

Return:

Document and graph assumptions.
Template outline and stable-ID strategy.
Contract choice with direct/staged/delta rationale.
CLI/API run surface, provider/model overrides, and structured-output policy.
Validation path: template lint, dry run, inspect report, graph invariants, export checks.
Operational path: batch manifest, retries, idempotent outputs, traces, and sampled review.

返回内容：

文档和图谱假设。
模板大纲和稳定ID策略。
契约选择及direct/staged/delta的理由。
CLI/API运行载体、提供者/模型覆盖配置及结构化输出策略。
验证路径：模板校验、试运行、检查报告、图谱不变量、导出检查。
运维路径：批量清单、重试、幂等输出、追踪及抽样评审。

Template

模板模式

Use Pydantic

BaseModel

classes. Prefer:

Descriptive
```
Field(..., description=...)
```
metadata for all extracted fields.

Stable graph IDs through

model_config = ConfigDict(json_schema_extra={"graph_id_fields": [...]})

or the project-supported equivalent.

Relationship fields typed as entity models or lists of entity models.
Explicit relationship semantics with Docling Graph helpers such as
```
edge()
```
when available.
Root models that describe the document-level graph and expose top-level relationship collections.

Avoid:

Untyped
```
dict
```
/
```
Any
```
blobs for graph-critical entities.
Relationship fields with no source evidence or no stable IDs.
Overly deep list-of-model nesting without a staged/delta contract.
IDs based only on extraction order, page number, or model-generated labels.

使用Pydantic

BaseModel

类，优先遵循：

为所有提取字段添加描述性
```
Field(..., description=...)
```
元数据。

通过

model_config = ConfigDict(json_schema_extra={"graph_id_fields": [...]})

或项目支持的等效方式实现稳定图谱ID。

关系字段类型为实体模型或实体模型列表。
若可用，使用Docling Graph辅助工具（如
```
edge()
```
）明确关系语义。
根模型描述文档级图谱并暴露顶层关系集合。

避免：

对图谱关键实体使用未类型化的
```
dict
```
/
```
Any
```
对象。
无源证据或无稳定ID的关系字段。
未搭配staged/delta契约的过深模型列表嵌套。
仅基于提取顺序、页码或模型生成标签的ID。

Contract

契约模式

Return a recommendation table with:

Selected contract and fallback contract.
Schema changes needed for the contract.
Pipeline flags/config fields to set.
Expected debug artifacts and how to inspect them.
Failure modes that should trigger switching contracts.

Use direct for simple extractions, staged for templates that naturally decompose, and delta when correctness depends on resolving entities/relationships across many observations.

返回包含以下内容的推荐表格：

选定契约及备选契约。
适配契约所需的schema变更。
需设置的流水线参数/配置字段。
预期调试产物及检查方式。
应触发契约切换的失败场景。

简单提取使用direct，自然可分解的模板使用staged，正确性依赖跨多观测值解析实体/关系时使用delta。

Convert

转换模式

Give both a CLI command and validation follow-up. Keep CLI flag names distinct from API field names.

bash

docling-graph convert SOURCE_PATH \
  --template TEMPLATE_MODULE:RootModel \
  --output-dir OUTPUT_DIR \
  --provider PROVIDER \
  --model MODEL \
  --extraction-contract direct \
  --schema-enforced-llm \
  --structured-sparse-check \
  --llm-streaming \
  --show-llm-config

Then instruct the user to inspect:

```
OUTPUT_DIR/graph.json
```
or the configured graph artifact.
```
OUTPUT_DIR/debug/trace_data.json
```
when debug dumping is enabled.
```
docling-graph inspect OUTPUT_DIR
```
for an HTML review report.
Relationship counts, orphan entities, duplicate IDs, and required-field coverage.

同时提供CLI命令和验证后续步骤，确保CLI参数名与API字段名区分开。

bash

docling-graph convert SOURCE_PATH \
  --template TEMPLATE_MODULE:RootModel \
  --output-dir OUTPUT_DIR \
  --provider PROVIDER \
  --model MODEL \
  --extraction-contract direct \
  --schema-enforced-llm \
  --structured-sparse-check \
  --llm-streaming \
  --show-llm-config

随后指导用户检查：

```
OUTPUT_DIR/graph.json
```
或配置的图谱产物。
启用调试转储时的
```
OUTPUT_DIR/debug/trace_data.json
```
。
运行
```
docling-graph inspect OUTPUT_DIR
```
生成HTML评审报告。
关系计数、孤立实体、重复ID及必填字段覆盖率。

API

API模式

Prefer explicit configuration and typed paths:

python

from pathlib import Path

from docling_graph import run_pipeline
from docling_graph.pipeline import PipelineConfig

from templates.sec import FilingGraph

config = PipelineConfig(
    source=Path("filing.pdf"),
    output_dir=Path("out/filing"),
    template=FilingGraph,
    provider_override="openai",
    model_override="gpt-4.1-mini",
    extraction_contract="staged",
    structured_output=True,
    structured_sparse_check=True,
    llm_streaming=True,
    gleaning_enabled=True,
    gleaning_max_passes=2,
    dump_to_disk=True,
    debug=True,
)

context = run_pipeline(config)

When exact upstream API names differ by installed version, inspect the installed docs/help and adapt. Preserve the concept split: provider/model overrides, contract selection, structured-output policy, gleaning, streaming, and debug dumping.

优先使用显式配置和类型化路径：

python

from pathlib import Path

from docling_graph import run_pipeline
from docling_graph.pipeline import PipelineConfig

from templates.sec import FilingGraph

config = PipelineConfig(
    source=Path("filing.pdf"),
    output_dir=Path("out/filing"),
    template=FilingGraph,
    provider_override="openai",
    model_override="gpt-4.1-mini",
    extraction_contract="staged",
    structured_output=True,
    structured_sparse_check=True,
    llm_streaming=True,
    gleaning_enabled=True,
    gleaning_max_passes=2,
    dump_to_disk=True,
    debug=True,
)

context = run_pipeline(config)

若上游API名称因安装版本不同而存在差异，需查看已安装的文档/帮助并调整。保留概念划分：提供者/模型覆盖、契约选择、结构化输出策略、信息收集、流处理及调试转储。

Inspect

检查模式

Use inspect when reviewing an output folder or preparing a debug handoff:

bash

docling-graph inspect OUTPUT_DIR

Review:

HTML summary for extraction stages, errors, model calls, and graph mapping.
```
debug/trace_data.json
```
for stage inputs/outputs, fallback paths, structured-output failures, and sparse-check findings.
Graph artifact for root entity count, relationship count, orphan nodes, duplicate IDs, and missing required fields.
Provider/model config actually used, not only the intended config.

评审输出文件夹或准备调试交接时使用检查模式：

bash

docling-graph inspect OUTPUT_DIR

检查内容：

提取阶段、错误、模型调用及图谱映射的HTML摘要。
```
debug/trace_data.json
```
中的阶段输入/输出、降级路径、结构化输出失败及稀疏检查结果。
根实体计数、关系计数、孤立节点、重复ID及缺失必填字段的图谱产物。
实际使用的提供者/模型配置，而非仅预期配置。

Export

导出模式

Tie export format to downstream needs:

JSON: canonical artifact, regression fixtures, API handoff.
CSV: analyst review, relationship tables, import staging.
Cypher/Neo4j: graph database load with uniqueness constraints.
NetworkX: algorithmic checks, connected components, centrality, reachability.

Before export handoff, verify stable IDs, relationship direction, duplicate nodes, and counts against the inspect report.

根据下游需求选择导出格式：

JSON：标准产物、回归测试用例、API交接。
CSV：分析师评审、关系表、导入准备。
Cypher/Neo4j：带唯一性约束的图数据库加载。
NetworkX：算法检查、连通组件、中心性、可达性分析。

导出交接前，验证稳定ID、关系方向、重复节点及计数是否与检查报告一致。

Debug

调试模式

Debug in this order:

Confirm installed
```
docling-graph
```
version, Python version, provider credentials, and CLI/API command.
Lint the template for root model, stable IDs, field descriptions, relationship types, and contract fit.
Reproduce with debug dumping and a small source sample.
Inspect
```
debug/trace_data.json
```
for structured-output fallback, sparse-check failures, stage/delta resolver misses, and graph mapping errors.
Compare source evidence -> extracted JSON -> graph artifact -> export artifact.
Propose the smallest fix: template field description, contract switch, provider/model override, gleaning pass, resolver config, or export mapping.

按以下顺序调试：

确认已安装的
```
docling-graph
```
版本、Python版本、提供者凭证及CLI/API命令。
校验模板的根模型、稳定ID、字段描述、关系类型及契约适配性。
启用调试转储并使用小型源样本重现问题。
检查
```
debug/trace_data.json
```
中的结构化输出降级、稀疏检查失败、阶段/delta解析器遗漏及图谱映射错误。
对比源证据 -> 提取JSON -> 图谱产物 -> 导出产物的链路。
提出最小修复方案：模板字段描述、契约切换、提供者/模型覆盖、信息收集次数、解析器配置或导出映射调整。

Batch

批量模式

For many documents, specify:

Manifest format with source path, template, contract, provider/model, output directory, and retry state.
Idempotent output directories and resumable runs.
Per-document traces retained for failures only unless compliance requires all traces.
QA sampling by document class and failure class.
Aggregate checks: required-field coverage, relationship density, duplicate IDs, provider cost, latency, and fallback rate.

针对多文档处理，需指定：

清单格式，包含源路径、模板、契约、提供者/模型、输出目录及重试状态。
幂等输出目录和可恢复运行机制。
仅保留失败文档的追踪数据，除非合规要求保留所有追踪数据。
按文档类型和失败类型进行QA抽样。
聚合检查：必填字段覆盖率、关系密度、重复ID、提供者成本、延迟及降级率。

Helper Scripts

辅助脚本

This skill includes optional local helpers:

bash

uv run python skills/docling-graph/scripts/check-env.py --provider openai --format json
uv run python skills/docling-graph/scripts/lint-template.py path/to/template.py --root FilingGraph --format json

The helpers are advisory. They should never replace running the installed

docling-graph

CLI/API and inspecting real outputs.

此技能包含可选的本地辅助脚本：

bash

uv run python skills/docling-graph/scripts/check-env.py --provider openai --format json
uv run python skills/docling-graph/scripts/lint-template.py path/to/template.py --root FilingGraph --format json

辅助脚本仅作参考，绝不能替代运行已安装的

docling-graph

CLI/API及检查实际输出。

References

参考文档

Reference file	Load when
`references/template-design.md`	Creating or reviewing Pydantic graph templates, stable IDs, relationship fields, staged/delta modeling
`references/pipeline-configuration.md`	Choosing contracts, provider/model overrides, structured output, gleaning, streaming, debug dumping
`references/cli-api-recipes.md`	Writing CLI/API run patterns, inspect workflows, or batch manifests
`references/export-graph-management.md`	Planning JSON/CSV/Cypher/NetworkX exports and graph integrity checks
`references/debugging.md`	Debugging traces, inspect reports, failed graph mapping, or artifact handoffs

参考文件	加载场景
`references/template-design.md`	创建或评审Pydantic图谱模板、稳定ID、关系字段、staged/delta建模
`references/pipeline-configuration.md`	选择契约、提供者/模型覆盖、结构化输出、信息收集、流处理、调试转储
`references/cli-api-recipes.md`	编写CLI/API运行模式、检查工作流或批量清单
`references/export-graph-management.md`	规划JSON/CSV/Cypher/NetworkX导出及图谱完整性检查
`references/debugging.md`	调试追踪数据、检查报告、图谱映射失败或产物交接

Canonical Vocabulary

标准术语

Canonical terms. Use these exactly:

Canonical term	Meaning
`direct contract`	One-pass extraction from source evidence into the root graph schema
`staged contract`	Decomposed extraction into stage outputs that are merged into the root graph
`delta contract`	Observation-first extraction plus entity/relationship resolution into the graph
`structured output`	Provider-supported schema enforcement or equivalent constrained generation
`sparse check`	Validation pass that identifies missing or underfilled schema fields
`gleaning`	Bounded follow-up passes that improve recall for entities and relationships
`inspect report`	Human-readable review surface created from an output directory
`trace data`	Debug artifacts such as `debug/trace_data.json` that connect source, extraction, mapping, and graph output

标准术语，请严格使用：

标准术语	含义
`direct contract`	从源证据一次性提取到根图谱schema的契约
`staged contract`	分解为阶段输出后合并到根图谱的提取契约
`delta contract`	先观测提取再解析实体/关系到图谱的契约
`structured output`	提供者支持的schema校验或等效约束生成
`sparse check`	识别缺失或填充不足schema字段的验证步骤
`gleaning`	提升实体和关系召回率的有限后续处理次数
`inspect report`	从输出目录生成的人类可读评审界面
`trace data`	连接源数据、提取、映射及图谱输出的调试产物（如 `debug/trace_data.json` ）

Progressive Disclosure

渐进式披露

Load references only when the request needs them:

Start with this skill body for dispatch, scope, and mode protocol.
Open one reference file for the active mode.
Open helper scripts only when asked to run local checks or when maintaining the skill.
Avoid loading all references for simple scope redirects or one-command answers.

仅在请求需要时加载参考文档：

首先使用本技能主体内容处理调度、范围及模式协议。
为当前模式加载一个参考文件。
仅在要求运行本地检查或维护技能时加载辅助脚本。
简单范围重定向或单命令回答时避免加载所有参考文档。

Scaling Strategy

扩容策略

Scale Docling Graph work by increasing operational controls before increasing model complexity:

Scope	Strategy
Small	Validate one representative document with debug dumping and inspect output
Medium	Add a manifest, idempotent outputs, retries, and sampled QA
Large	Use batch execution with aggregate metrics, trace retention policy, and staged promotion
100+ files	Parallelize by manifest shard only after the single-document invariant suite passes

Validate one representative document with debug dumping and inspect output.
Add a manifest for batches with source, template, contract, provider/model, output path, and status.
Make outputs idempotent and resumable.
Retain traces for failures and sampled successes.
Aggregate required-field coverage, relationship density, duplicate IDs, orphan relationships, fallback rate, cost, and latency.
Promote to larger batches only after graph invariants pass on the sampled set.

在增加模型复杂度前，先通过提升运维控制来扩容Docling Graph工作：

规模	策略
小型	使用调试转储和检查输出验证一个代表性文档
中型	添加清单、幂等输出、重试及抽样QA
大型	使用批量执行并结合聚合指标、追踪保留策略和阶段式推广
100+文件	仅在单文档不变量套件通过后，按清单分片并行处理

使用调试转储和检查输出验证一个代表性文档。
为批量任务添加包含源、模板、契约、提供者/模型、输出路径及状态的清单。
实现输出的幂等性和可恢复性。
保留失败文档和抽样成功文档的追踪数据。
聚合必填字段覆盖率、关系密度、重复ID、孤立关系、降级率、成本及延迟指标。
仅在抽样集通过图谱不变量检查后，推广到更大批量处理。

Validation Contract

验证契约

Run from this skill directory before declaring changes complete:

bash

python scripts/check.py
python -m py_compile scripts/check-env.py scripts/lint-template.py
pytest -q tests/test_docling_graph_skill.py
git diff --check

Completion criteria:

```
scripts/check.py
```
exits 0.
Helper scripts compile and focused tests pass.
```
git diff --check
```
exits 0.
No portable-CLI violations remain under this skill directory.

After changing skill definitions, public descriptions, reference files, or eval behavior, invoke

docs-steward

if available.

在宣布变更完成前，从本技能目录运行以下命令：

bash

python scripts/check.py
python -m py_compile scripts/check-env.py scripts/lint-template.py
pytest -q tests/test_docling_graph_skill.py
git diff --check

完成标准：

```
scripts/check.py
```
退出码为0。
辅助脚本编译通过且聚焦测试通过。
```
git diff --check
```
退出码为0。
本技能目录下无便携CLI违规项。

修改技能定义、公开描述、参考文件或评估行为后，若可用请调用

docs-steward

。

Critical Rules

关键规则

Keep Docling Graph scope narrow; redirect generic parsing or graph database questions.
Distinguish CLI flags from Python API fields.
Verify IDs, required fields, relationships, and debug/inspect artifacts before claiming graph quality.
Prefer structured output/schema enforcement when available, and specify fallback behavior.
Choose direct, staged, or delta explicitly for complex templates.
Preserve source evidence paths in debug handoffs.
Redact secrets from commands, logs, examples, traces, and generated configs.

严格限定Docling Graph范围；重定向通用解析或图数据库相关问题。
区分CLI参数与Python API字段。
在声称图谱质量达标前，验证ID、必填字段、关系及调试/检查产物。
优先使用结构化输出/schema校验，并指定降级行为。
针对复杂模板明确选择direct、staged或delta契约。
在调试交接中保留源证据路径。
从命令、日志、示例、追踪数据及生成的配置中脱敏敏感信息。