Docgraph

像管理代码一样治理文档。 DocGraph 将 .md、.docx、.html 和 .pdf 编入图谱，并对其执行漂移审计——发现过时的政策、相互冲突的研究观点、已被取代的 ADR、缺少文档说明的代码导出项等，让你能够像审查代码库一样审查文档集。大多数文档工具只会编制索引和搜索。DocGraph 还会告诉你哪些内容出了问题。

文档漂移审计

docgraph_context format=drift_audit

在整个文档集中识别 14 种问题代码，包括：

• policy.stale_review — 已超过 review_due 日期的 SOP
• policy.superseded_referenced — 引用了已被替代政策的文档
• policy.conflicting — 范围相同、规则相互矛盾
• research.competing_interpretations — 相互矛盾的观点
• research.unverified_evidence — 没有来源的断言
• research.superseded_claim — 已被较新观点推翻的研究结论
• doc.stale_by_git — 长期没有 git 提交记录的文档
• code.undocumented_export — 没有文档锚点的代码接口
• code.unanchored_feature — 没有代码锚点的已批准功能

默认启用三个规则包（governance、research_provenance、entity）；另有三个可选启用（policy_process、assessment_drift、code_doc）。治理和研究功能不要求了解代码——适用于任何文档集。

可选的 Agent 信息增强，保留来源信息

你的 .docx / .pdf / .html 归档没有 frontmatter，因此无法进行治理。DocGraph 能在不损害权威性的前提下解决这一问题：

agent → docgraph_enrichment(action=pending)
        ↳ scope (N docs), per-model USD estimate, sensitive paths flagged, token
user  → "go"
agent → runs LLM with its own key, then action=process for each doc
        ↳ stored as source=agent_inferred (advisory, lowest authority)
        ↳ logged with model_id, agent_id, run_id, content_hash

确认令牌与批次绑定——用户的一次授权仅适用于该用户已查看的文档，不会扩展到其他文档。敏感路径会静默拒绝签发令牌。agent_inferred 元数据绝不会覆盖人工 frontmatter 或提取出的文档元数据。治理不会因 Agent 而失效。 DocGraph 本身绝不会调用大模型。使用 --enable-enrichment 启用。

其他差异化特性

• 真正可用的 CJK + Latin 搜索 — 使用 FTS5 trigram，而非仅支持英语
• 面向文档的 CodeGraph 风格图遍历 — docgraph_graph operation=incoming|outgoing|impact|trace
• 工作区扇出 — 一个 MCP 服务，N 个项目，一次查询
• 可审查的证据包 — format=context_pack 返回已索引文本、哈希、引文和影响信息（不是 RAG 黑盒）

它不是什么

它不是 RAG 黑盒、嵌入服务，也不是 Notion 的替代品。它为你现有的文档提供可审计、可导航的能力，并让文档能够安全地交给大模型使用。

面向大模型的适用指南——说明 DocGraph 适用于哪些项目，以及何时应改用自己的工具——请见 AGENTS.md。它是单一二进制文件、零运行时依赖，可在数秒内为数百份文档编制索引。

概览

指标	值
语言	Go 1.25+
二进制文件大小	~13 MB
代码库	~23,520 行 Go 代码（另有 ~28,390 行测试代码）
索引速度	每个项目 2–6 秒处理 70–700 个文件（完整重建；--force）
典型图谱	每索引 100 个文件约有 ~950 个节点和 ~670 条边

安装

go install github.com/Detective-XH/docgraph@latest

或者从源代码构建并嵌入版本号：

git clone https://github.com/Detective-XH/DocGraph.git
cd DocGraph
go build -ldflags "-X main.version=$(git describe --tags --always)" -o docgraph .

需要 Go 1.25 或更高版本。

go install 不支持注入 -ldflags，因此通过这种方式安装的二进制文件运行 docgraph version 时会输出 dev。要获取带版本号的二进制文件，请使用上面的源代码构建方式。

CLI

docgraph init [--dry-run] [--interactive] [--install-clients auto|all|LIST] [--workspace] [--scope user] [--with-skills] [--update-skills] [path] # Create local config; optionally install MCP clients and bundled skills
docgraph install [--dry-run] [--interactive] [--clients auto|all|LIST] [--workspace] [--scope user] [--update-skills] [path]      # Configure MCP clients without re-initializing
docgraph pack list [--workspace] <path>                         # List domain packs and enabled state
docgraph pack enable [--workspace] [--no-sync] <pack-id> <path>  # Enable a domain pack; code_doc syncs by default
docgraph pack disable [--workspace] <pack-id> <path>             # Disable a domain pack; code_doc rows are removed
docgraph index [--force] [--threshold N] [--no-gitignore] [--no-history] <path>  # Index a project
docgraph sync [--threshold N] [--no-gitignore] [--no-history] <path>             # Incremental hash-based update
docgraph heal [--project <path>] [--fix] [--owner <name>] [--git-timeout <dur>]  # Infer and patch missing status/owner frontmatter fields in .md files
docgraph status <path>                       # Print index stats
docgraph serve [--threshold N] [--no-gitignore] [--no-history] [--max-watches N] [--enable-embeddings] [--enable-enrichment] --path <path>     # MCP stdio server (single project)
docgraph serve [--threshold N] [--no-gitignore] [--no-history] [--max-watches N] [--enable-embeddings] [--enable-enrichment] --workspace <dir> # MCP stdio server (auto-discover all child dirs)
docgraph version                             # Print build version

LIST 是以逗号分隔的客户端列表：claude,codex,hermes,opencode。 auto 始终会写入项目本地的 Claude Code 配置；如果 Codex、Hermes 和 OpenCode 的配置目录已存在，也会写入相应配置。 all 会为所有受支持的客户端创建配置文件。 使用 --dry-run 可打印创建、更新或未更改的操作，而不写入文件。 使用 --interactive 可打印相同的操作预览，并在写入前确认。

内置技能

为 Claude Code 安装时，DocGraph 会自动将配套技能安装到 .claude/skills/，与 MCP 配置放在一起，无需额外标志：

docgraph init --install-clients claude /path/to/project  # MCP config + skill
docgraph install --clients claude /path/to/project       # MCP config + skill

若要为已经初始化、但未使用 --install-clients 的项目安装技能：

docgraph init --with-skills /path/to/project

技能采用存在时跳过的策略安装，可安全地重复运行。要将现有技能更新为最新的内置版本：

docgraph init --update-skills /path/to/project
docgraph install --clients claude --update-skills /path/to/project

docgraph-drift-audit 技能会审计所有已索引的 .md 文件是否兼容 DocGraph，包括缺少 frontmatter、文档孤立（没有外链）、损坏的 wikilinks、标题和相似性孤岛。它会按类别报告 PASS/FAIL，并提供通过 docgraph_files 和 docgraph_similar 自动修复的选项。

二进制文件中内置的技能：

技能	用途
docgraph-drift-audit	审计 .md 文件是否兼容 DocGraph
policy-drift-audit	显示并分流来自 docgraph_context format=drift_audit 的政策／流程漂移发现
assessment-drift-audit	显示并分流来自 docgraph_context format=drift_audit 的研究评估漂移发现
code-doc-drift-audit	当启用 code_doc pack 时，显示并分流文档与代码漂移发现（code.*）

MCP 工具

docgraph_graph 支持 operation=incoming|outgoing|impact|trace。对于 incoming、outgoing 和 impact，使用 document；对于 trace，使用 from 和 to。

工具

#	工具	描述
1	docgraph_search	FTS5 全文搜索（CJK + 拉丁文），提供章节级结果、字段加权排名、结合图谱和 Git 历史的重新排序，以及治理、研究和实体筛选器。默认仅返回文档；传入 include_code=true 或 kind=code_file 可包含 code_doc 包中的代码文件
2	docgraph_context	主要入口——提供任务上下文、相关文档、结构、交叉引用和范围受限的源内容。使用 format=context_pack 生成便于审查的证据包；使用 format=drift_audit 生成策略/流程、研究以及（启用 code_doc 时）文档与代码偏差审计报告
3	docgraph_graph	图谱遍历接口。operation=incoming（谁引用了此文档）、operation=outgoing（此文档链接到什么内容）、operation=impact（影响范围，可配置深度）、operation=trace（两个文档之间的最短路径）。incoming/outgoing/impact 使用 document=；trace 使用 from= 和 to=
4	docgraph_node	单个文档的详细信息，包括元数据、结构和边
5	docgraph_files	已索引文件树
6	docgraph_similar	查找主题相似的文档（TF-IDF + 共享引用 + 标签；engine=auto/tfidf/neural）
7	docgraph_status	索引健康状态（文件/节点/边/未解析项/数据库大小）、各项目统计、神经嵌入模型总数、领域包、元数据质量、增强覆盖率、大模型调用工具状态（嵌入/增强已启用或已禁用 + 必需标志），以及存在策略/研究发现时的精简偏差审计摘要
8	docgraph_tags	列出所有标签及其文档计数，或按标签筛选文档
9	docgraph_enrichment	选择启用（--enable-enrichment）。为没有 frontmatter 的文档提取或存储推断摘要和元数据。接口：action=pending|process
10	docgraph_embeddings	选择启用（--enable-embeddings）。神经嵌入工作流接口。action=pending 列出需要嵌入的文档；action=store 保存向量并重新计算神经相似度；action=clear 删除某个模型的所有嵌入

对于任何研究问题，都从 docgraph_context 开始。它会将搜索、 结构和交叉引用整合到单个结果中。使用其他工具 深入了解具体内容。

关于面向 Agent 的决策——是否安装/使用 DocGraph，请参阅 AGENTS.md。安装后，工具选择规则见 MCP serverInstructions（每次会话注入）和各工具的描述。

Agent 元数据增强

README 顶部概述了选择加入工作流的完整机制。DocGraph 本身不会调用大模型——由你的 Agent 使用自己的密钥调用大模型，然后将结果连同来源信息写回。

1. docgraph_enrichment(action=pending, limit, content_mode) 返回没有当前推断摘要且不含 frontmatter 的文档，包括 doc_id、content_hash 和有界内容。响应中包含一个 CONFIRMATION_TOKEN，与其列出的这批 doc_id 绑定。
2. Agent 推断简洁摘要和可选的元数据 JSON 对象。
3. docgraph_enrichment(action=process, doc_id, content_hash, summary, metadata, confidence, model_id, provider, agent_id, confirmation_token) 存储结果。必须提供 model_id，content_hash 必须与待处理响应中的值一致，而 confirmation_token 必须是 action=pending 为该批次中的某个 doc_id 返回的令牌。

推断的元数据不会覆盖作者编写的 frontmatter 或提取的文档元数据。存储的摘要会显示在 docgraph_node、docgraph_context 和上下文包中。docgraph_status 会报告增强覆盖率和过期结果。常规检索每份文档使用一个当前增强结果，而 DocGraph 会在内部运行记录中保留模型、提供方、Agent 和内容哈希来源信息。Agent 推断的摘要和元数据仅作为参考上下文，并非事实依据。

隐私：docgraph_enrichment action=pending 会返回文档内容，你的 Agent 可能会将其发送给外部提供方。继续之前请征得用户同意。

语义相似度

DocGraph 使用三种信号计算文档之间的主题相似度：

信号	方法	权重
文本重叠	TF-IDF 余弦相似度	50%
共同引用	出站链接目标的 Jaccard 相似度	30%
标签重叠	frontmatter 标签的 Jaccard 相似度	20%

得分高于阈值（默认值为 0.25）的文档会通过 similar_to 边连接起来。即使文档之间没有显式链接，这也能找出概念相关的文档——这是相较于基于 grep 的搜索的关键优势。

索引期间会自动计算相似度。使用 docgraph_similar 进行查询。可通过 index、sync 或 serve 上的 --threshold N 调整灵敏度；值越低，创建的 similar_to 边越多。

神经嵌入（由 Agent 驱动）

DocGraph 本身不会调用大模型。你的 Agent 可以使用任意提供方计算嵌入向量，并将向量推送回来——这种先拉取再推送的 Agent 工作流，可实现远超 TF-IDF 词汇匹配的语义搜索。

1. docgraph_embeddings(action=pending, model_id, limit, content_mode) — 返回没有最新嵌入向量的文档，包括内容和 content_hash。content_mode=full（默认值）会从磁盘读取完整章节；content_mode=excerpt 则使用已存储的正文摘录。不同的 model_id 会分别处理，彼此之间不会进行比较。
2. 你的 Agent 使用自己的提供方（OpenAI、Ollama、Nomic 等）计算向量。
3. 对每份文档调用 docgraph_embeddings(action=store, doc_id, model_id, vector, content_hash) — 存储向量并重新计算神经 similar_to 边。传入的 content_hash 必须与第 1 步返回的值完全一致。
4. docgraph_similar 会对同一对文档的 TF-IDF 和神经搜索结果去重；两者都存在时优先采用神经结果。

在工作区模式下，两种嵌入工作流都会根据 doc_id 自动定位正确的项目级存储。

隐私：待处理的嵌入操作会返回文档内容，你的 Agent 会将其发送给外部提供方。继续之前请征得用户同意。

使用 docgraph_embeddings(action=clear, model_id) 可删除某个模型的所有向量并释放空间。docgraph_status 会显示一个 Neural Embeddings 表格，其中列出已存储的模型、向量总数和过期数量。

节点和边的类型

节点： document、heading、definition、tag；启用 code_doc 领域包时可选添加 code_file 节点。

边：

类型	含义
contains	文档包含标题/定义
references	[text](path.md) Markdown 链接
wikilinks_to	[[target]] Wiki 链接
related_to	Frontmatter Wiki 链接（例如，related_to: "[[target]]"）
similar_to	主题相似度（TF-IDF + 共享引用 + 标签；或使用已存储的嵌入向量进行神经网络计算）
tagged	Frontmatter 标签关联
embeds	![[embed]] 嵌入内容
links_external	指向外部资源的 URL

索引内容

Markdown（.md） — 每个文件最大 1 MB：

• 将 YAML frontmatter 解析为元数据；标题和 **Term:** definition 行会生成结构化节点
• [[wikilinks]]、[links](path.md)、![[embeds]]、外部 URL 和 frontmatter 标签会生成具有类型的边

Word 文档（.docx） — 每个文件最大 10 MB：

• 标题段落（Heading 1–6 样式）会成为带有包含边的 heading 节点
• 提取超链接作为 docx_hyperlink 边；将 Dublin Core 元数据（core.xml）存储为键/值元组
• 防止 Zip Slip 攻击，限制每个条目的大小，解压后总大小上限为 50 MB

HTML（.html、.htm） — 每个文件最大 5 MB：

• <h1>–<h6> 标签（包括 id 属性）会成为 heading 节点
• 将 <meta name=…> 和 <meta property=…> 存储为元数据元组；<a href=…> 会成为具有类型的链接边
• <script> 和 <style> 内容会从正文文本和分节块中排除

PDF（.pdf） — 每个文件最大 50 MB / 500 页：

• 每页会成为一个 heading 节点和一个分节块
• 将信息字典字段（标题、作者、主题、关键词、创建日期）编入索引，作为元数据元组
• 通过每页平均字符数检测纯图片 PDF，并标记为 warning: image-only-pdf
• 原生解码预定义 CMap 字体：Uni*-UCS2-*（UniGB/CNS/JIS/KS）、90ms-RKSJ-*（Shift-JIS）、GBK-EUC-H/V（简体中文）、ETen-B5-H/V（繁体中文）、KSCms-UHC-H/V（韩语）。仍无法解码的页面会标记为 warning: extraction-failed:encoding-garbage，并跳过，而不是用替换字符乱码编入索引

代码文档内容（选择启用） — 每个文件最大 1 MB：

• 启用 code_doc 领域包以索引文件头、导出项文档注释、测试名称和示例名称：
  • 单个项目：docgraph pack enable code_doc /path/to/project
  • 工作区：docgraph pack enable --workspace code_doc /path/to/workspace
  • 检查状态：docgraph pack list /path/to/project
• 支持的语言包括 Go、Python、Ruby、JavaScript、TypeScript、Svelte、Vue、Rust、C、C++、Java、Swift、C#、PHP、Kotlin、Dart、Lua、Luau、Pascal、SQL 和 Liquid
• 每个源文件新增一个 code_file 节点；增量执行 pack enable 同步 40–80 个代码文件需 1–4 秒，300 个以上代码文件最多约需 12 秒
• 启用后，docgraph_search 默认仍只返回文档 — 使用 kind=code_file 或 include_code=true 纳入代码文件 — format=drift_audit 会展示 code.* 检查结果
• 使用 --force 重新索引会重置领域包状态 — 强制重建后需重新运行 docgraph pack enable code_doc <path>
• 这仅用于浅层文档索引；CodeGraph 仍是用于调用图、类型解析、路由和代码影响分析的指定工具

通用规则：

• 遵循 .gitignore 和 .docgraphignore
• 跳过的目录：node_modules、.git、target、dist、build、vendor、.next、.cache、__pycache__、.codegraph、.docgraph、.obsidian 和 .claude/worktrees（Agent Git 工作树 — 完整的仓库副本，索引后会产生重复内容）。这些目录会被无条件排除 — --no-gitignore 会取消 .gitignore 规则，但不会重新纳入这些目录。（对于 Obsidian 库，这意味着会跳过 .obsidian/ 应用配置目录，同时仍会完整索引你的笔记。）

领域包

领域包可扩展元数据架构，以适用于特定用例。默认启用三个包；另有三个可选启用。

包	默认启用	领域	用途
governance	是	治理	生命周期状态、所有权、敏感度、审查安排、受众访问控制，以及文档替代关系
research_provenance	是	研究	主张、证据、来源类型、置信度、分析师工作流、事件/评估日期，以及时效性
entity	是	实体	实体分类、规范命名和别名声明；启用实体来源图
code_doc	关闭	代码	Go、Python、JS/TS、Rust 及其他 20 多种语言的文件头、文档注释、测试名称和示例名称
policy_process	关闭	policy_process	检测政策/SOP 偏差——相互冲突、过时、重复、已被替代和非规范文档
assessment_drift	关闭	研究	检测评估偏差——评估过时、证据未经验证，以及相互竞争的研究解读

各包的 Frontmatter 字段

每个包都会读取 Markdown frontmatter 中的特定键。

governance — 生命周期和访问控制：

status: active            # Governance lifecycle status
owner: alice              # Accountable person or role
sensitivity: internal     # Sets retrieval boundaries
allowed_audience: [engineering, legal]
review_due: 2026-12-31    # Triggers policy.stale_review when overdue
effective_date: 2026-01-01
canonical_source: true    # Marks as the authoritative copy among duplicates
approver: bob
department: Engineering
supersedes: old-policy.md
superseded_by: new-policy.md

research_provenance — 证据和来源追踪：

claim_id: CLM-001
source_type: primary      # primary | secondary | internal
confidence: high
analyst_status: verified
assessment_date: 2026-05-01
event_date: 2026-04-15
last_verified: 2026-05-20
valid_until: 2026-11-01   # Triggers research.stale_assessment when expired
evidence: [doc/evidence-a.md, doc/evidence-b.md]
client: ACME
deliverable_id: RPT-42

entity — 规范实体声明：

entity_type: organization   # person | organization | location | …
canonical_name: Acme Corp
aliases: [ACME, Acme Corporation]

policy_process（可选启用）— SOP 和政策增强：

sop_category: onboarding
policy_domain: HR           # HR | Security | Finance | …
process_owner: People Ops
version: "2.1"
conflict_resolution: supersedes-v2.0

assessment_drift（可选启用）— 相互竞争的研究追踪：

contradicts: assessment-2026-03.md
supersedes_claim: CLM-099

偏差审计发现

docgraph_context format=drift_audit 会显示已启用包提供的提示性发现。 无需代码知识——governance 和 research 包可用于任何文档集合（.md、.docx、.html、.pdf）。

发现	所需包	检测内容
policy.stale_review	governance	review_due 已过期
policy.superseded_referenced	governance	已被替代的文档仍被其他文档引用
policy.duplicate	governance	通过相似度检测近似重复内容
policy.non_canonical	governance	近似重复文档中没有 canonical_source 标记
policy.conflicting	governance	相似文档的状态或生效日期相互冲突
research.stale_assessment	research_provenance	valid_until 已过期
research.unverified_evidence	research_provenance	无法解析证据引用
research.competing_interpretations	research_provenance + assessment_drift	同一主题存在相互冲突的主张
research.superseded_claim	research_provenance + assessment_drift	过时的主张仍被引用
research.impacted_deliverable	research_provenance	交付物依赖于过时的主张
doc.stale_by_git	无（git 历史）	超过 N 天没有 git 提交（默认 365 天），与 frontmatter 日期无关
code.missing_symbol	code_doc	文档引用的代码符号已不存在
code.undocumented_export	code_doc	导出符号没有文档注释
code.unanchored_feature	code_doc + governance	文档中提到的功能没有对应的代码

管理包

docgraph pack list /path/to/project                                # Show all packs and enabled state
docgraph pack enable policy_process /path/to/project               # Enable an opt-in pack
docgraph pack enable assessment_drift /path/to/project
docgraph pack enable code_doc /path/to/project                     # Also triggers incremental sync
docgraph pack disable code_doc /path/to/project                    # Removes code_file rows
docgraph pack enable --workspace policy_process /path/to/workspace # Apply to all child projects

--force 重新索引会重置所有包状态——强制重建后，请重新运行 docgraph pack enable <pack-id> <path>。

工作区模式

将 DocGraph 指向一个父目录，它会自动发现所有直接子目录，并将其作为独立项目：

docgraph serve --workspace /path/to/workspace

• 每个项目都有自己的 .docgraph/docgraph.db（将 .docgraph/ 添加到 .gitignore）
• 跨项目搜索会遍历所有数据库
• 文件监视器（fsnotify，2 秒防抖）会监视已提供服务的项目，以便实时重新索引
• 每个进程的监视数量有上限（--max-watches，默认值为 8192；0 = 不限）。在 macOS 上，每个被监视的目录/文件都占用一个描述符，因此对非常大的目录树进行无限制递归监视，可能会导致操作系统文件描述符表接近耗尽（更糟的是，每个已连接的客户端都运行一个这样的进程）。此上限会将打开的描述符数量控制在接近上限的范围内，外加最宽的单个被监视目录所占用的描述符，因为 fsnotify 会立即打开该目录；而不是为整棵目录树中的每个文件都打开一个描述符。超过上限后，变更不会自动触发重新索引；请运行 docgraph sync 或重启。可通过该标志或 DOCGRAPH_MAX_WATCHES 覆盖此设置。
• 无需配置文件

文件排除

DocGraph 默认遵循 .gitignore。如需进一步控制，可创建 .docgraphignore 文件（语法与 .gitignore 相同）：

# Project-level .docgraphignore — exclude files within a project
drafts/
archive/
*.draft.md
!archive/INDEX.md    # re-include a specific file

工作区级别的 .docgraphignore（位于工作区根目录）可按目录名称排除整个项目：

# Workspace-level .docgraphignore — exclude projects
OSINT-Platform-backup-20260518
csint-private

在 docgraph serve 运行期间编辑 .docgraphignore 会自动应用变更：保存时会从索引中清除新排除的文件（采用受保护的协调机制——如果某个过于宽泛的模式会导致删除超过一半的语料库，系统会拒绝执行并显示提示，而不会清空索引）。如果没有正在运行的服务，新排除的文件会在下次运行 docgraph index --force <path> 时被移除。docgraph_status 会报告当前生效的忽略来源（.gitignore、.docgraphignore、--no-gitignore）以及如何添加排除规则。

索引所有文件

若要索引被 git 忽略的文件（例如 .claude/skills/、memory/ 目录），请使用 --no-gitignore 标志：

docgraph index --no-gitignore <path>
docgraph sync --no-gitignore <path>
docgraph serve --no-gitignore --workspace <dir>

此选项会忽略 .gitignore 规则，但仍遵循 .docgraphignore。

MCP 客户端集成

DocGraph 可通过 stdio 传输与任何兼容 MCP 的客户端配合使用。

自动设置：

docgraph init --install-clients auto /path/to/project
docgraph install --clients all --workspace /path/to/workspace

安装程序会写入：

客户端	配置目标
Claude Code	/path/to/project/.mcp.json
Codex	$CODEX_HOME/config.toml 或 ~/.codex/config.toml
Hermes Agent	~/.hermes/config.yaml
OpenCode	项目中的 opencode.json / .opencode.json；否则为 $XDG_CONFIG_HOME/opencode/opencode.json

Claude Code

项目级别（仅此项目）——在项目根目录的 .mcp.json 中添加配置，或运行：

docgraph init --install-clients claude /path/to/project

手动配置 .mcp.json：

{
  "mcpServers": {
    "docgraph": {
      "command": "docgraph",
      "args": ["serve", "--path", "."]
    }
  }
}

用户级别（全局）——可用于所有项目。通过 claude CLI 写入 ~/.claude.json：

docgraph install --clients claude --scope user --workspace /path/to/workspace

或使用 claude CLI 手动配置：

claude mcp add --scope user docgraph -- docgraph serve --workspace /path/to/workspace

验证连接：

claude mcp list

重要提示： Claude Code 将用户范围的 MCP 配置存储在 ~/.claude.json 中，而非 ~/.claude/mcp.json。手动编辑 ~/.claude/mcp.json 不会生效——请改用 claude mcp add --scope user 或项目级别的 .mcp.json 方式。

PATH 提示： docgraph 必须位于你的 PATH 中。若通过 go install 构建，请确保 $GOPATH/bin 已加入 PATH（运行 go env GOPATH 可查找其位置）。否则，请使用二进制文件的绝对路径。

Codex（OpenAI）

添加到 MCP 配置中：

[mcp_servers.docgraph]
command = "docgraph"
args = ["serve", "--workspace", "/path/to/workspace"]

Hermes Agent

添加到 ~/.hermes/config.yaml：

mcp_servers:
  docgraph:
    command: docgraph
    args:
      - serve
      - --workspace
      - /path/to/workspace

OpenCode

添加到 OpenCode MCP 配置中：

{
  "mcpServers": {
    "docgraph": {
      "command": "docgraph",
      "args": ["serve", "--workspace", "/path/to/workspace"]
    }
  }
}

任意 MCP 客户端

DocGraph 使用 stdio 传输。启动命令：

docgraph serve --workspace /path/to/workspace
# or single project:
docgraph serve --path /path/to/project

服务器从 stdin 读取 JSON-RPC，并写入 stdout。

架构

scan .md / .docx / .html / .pdf  (docformat registry: extensions + per-format size limits)
  -> dispatch:
       .md          → goldmark + inlined YAML frontmatter parser
       .docx        → stdlib archive/zip + encoding/xml
       .html / .htm → golang.org/x/net HTML tokenizer
       .pdf         → Detective-XH/gopdf (ledongthuc/pdf fork; text layer + CJK CMaps; writes to temp file)
       code docs    → optional code_doc pack for comments/tests/examples
  -> extract nodes, edges, links, metadata tuples, and section chunks
  -> store in SQLite (modernc.org/sqlite, pure Go)
  -> resolve cross-document references
  -> compute topic similarity (TF-IDF + graph Jaccard)
  -> serve over MCP stdio (mark3labs/mcp-go)

FTS5 使用 trigram 分词器进行中日韩文字与拉丁文字混合的全文搜索。

依赖项

依赖项	作用
modernc.org/sqlite	纯 Go SQLite 驱动（无需 CGo），支持 FTS5
goldmark	Markdown 解析器
yaml.v3	YAML frontmatter 解析
mcp-go	MCP 协议（stdio 传输）
fsnotify	跨平台文件监视器
golang.org/x/net	用于提取 .html/.htm 的 HTML 分词器
Detective-XH/gopdf	PDF 文本层提取（ledongthuc/pdf 的分支，添加了 CJK CMap 解码器）
stdlib	.gitignore + .docgraphignore 匹配；使用 archive/zip + encoding/xml 处理 .docx

供应链

CI 使用 go mod verify 验证模块校验和，运行 govulncheck，并使用 cyclonedx-gomod 生成名为 docgraph-sbom 的 CycloneDX JSON SBOM 构件。SBOM 在 GitHub Actions 运行期间根据 go.mod 生成；生成的 SBOM 文件不会提交到代码库。

CodeGraph 互操作性

DocGraph 和 CodeGraph 互为补充。DocGraph 负责文档上下文、 治理/研究元数据、引用路径、文档引用、上下文包、漂移审计以及浅层的代码文档表层。CodeGraph 负责 源代码智能分析，例如符号、调用方/被调用方、调用跟踪、路由处理程序和代码影响。

目前，CodeGraph 互操作性通过 MCP 服务指令中的建议性交接层提供。DocGraph 不会调用 CodeGraph、读取 .codegraph/，也不会导入 CodeGraph 符号锚点。保留的 codegraph_anchor 元数据 字段会保持为空，直到 CodeGraph 提供稳定的导出/API 契约。

对于文档与代码相关的工作，请启用 DocGraph 的 code_doc 包——它是 DocGraph 与 CodeGraph 之间的接口层。DocGraph 会为文档表层建立索引 （文件头、导出的文档注释、测试名称、示例名称）；CodeGraph 会为代码结构建立索引（符号、调用方/被调用方、调用图、类型解析）。 两者结合可提供完整视图：启用 code_doc 的 format=drift_audit 可以发现 code.missing_symbol、code.undocumented_export 和 code.unanchored_feature 问题，然后在 Agent 环境提供相关工具时，将符号级问题交由 codegraph_* 工具处理。

灵感来源

DocGraph 的灵感来自 CodeGraph，它使用 tree-sitter 和 SQLite 从源代码符号构建知识图谱。DocGraph 采用了相同的核心设计：

• 架构：nodes + edges + files + unresolved_refs + FTS5 + section_chunks + section_chunks_fts + document_metadata + governance_metadata + research_metadata + domain_packs + domain_pack_fields + entities + entity_mentions — 在图模型的基础上扩展了章节快照、章节级搜索、规范化治理元数据、研究溯源、领域架构包注册，以及实体/来源图基础组件。每次打开时，都会通过幂等的 CREATE TABLE/INDEX/TRIGGER IF NOT EXISTS 引导架构；若需要更改架构形状，请删除 .docgraph/ 并重新索引。
• 流水线：扫描 → 解析 → 存储 → 解析引用 — 相同的四阶段索引流水线，但使用 goldmark 替代 tree-sitter 提取 AST。
• 两阶段解析：解析过程中提取原始链接，然后在所有文件完成索引后通过单独的步骤解析 — 与 CodeGraph 的 UnresolvedReference → ReferenceResolver 模式相同。
• MCP 工具接口：默认提供 8 个工具，命名与 CodeGraph 兼容，涵盖上下文、搜索、节点、相似项、文件、状态、标签以及图遍历（docgraph_graph）；另外 2 个 LLM 调用工具（docgraph_embeddings、docgraph_enrichment）仅在设置相应的 --enable-* 标志后注册。图遍历、嵌入和丰富功能均为门面工具，通过单一分派参数组合细粒度操作，使面向 Agent 的说明保持简洁。

两者的不同之处：DocGraph 使用 Go 编写（单个二进制文件，无需 Node.js 运行时），使用三元组分词器支持 CJK，并增加了工作区模式以支持多项目扇出查询 — 这些功能反映的是文档场景，而非代码导航。DocGraph 还增加了混合主题相似度（TF-IDF + 图 Jaccard + 标签），用于发现显式链接和代码结构都无法捕捉的概念关系。

版本 v0.3.4 — SHA-256 校验和

由 EDB0808F3F248B66F53837B4888293C4BA30EEF6（Xavier）签名。

docgraph-darwin-arm64.tar.gz

c4dc880d8ed6796f28718c76c99e410c110366fd6c47bd991b518b023b5c28c3

docgraph-darwin-amd64.tar.gz

31dbfa7f8d6748f7147863f1f0b9549f82ca83f0e9847bc45002520c7039a1e6

docgraph-linux-amd64.tar.gz

a8ae2cf4843b47316853ee5177c89599c9893eb6d256731db432ec4565846f71

docgraph-linux-arm64.tar.gz

a9223d01473554063b0bbb584b1e7c205271c6340db3d2826a50fdefff52c3cc

docgraph-windows-amd64.zip

b1cacd26d9d69cc7169f7a6fe73cce565868d7be6131cc1a925a16545ad1a88a

验证：

gpg --verify SHA256SUMS.asc SHA256SUMS
shasum -a 256 -c SHA256SUMS

许可证

MIT