内容
# Graphscribe
`graphscribe` 是一个基于 Neo4j 构建的自托管语料库摄入、向量 RAG 和 GraphRAG 流程。其主要 v3 工作流程摄入本地文本、Markdown、PDF 和 YouTube 转录内容，无需 NotebookLM，创建分层检索块和原生的 Neo4j 向量/全文索引，提取知识图谱，并通过 REST 和 MCP 提供引用的研究。
参见 [本地 Neo4j 语料库 RAG](docs/LOCAL_CORPUS_RAG.md) 以获取主要设置、迁移、API、MCP 和操作指南。
对于 Aura 权威紧凑父向量语料库的例行添加，请使用修订范围的 [Aura 紧凑语料库更新工作流程](docs/AURA_COMPACT_CORPUS_UPDATES.md) 或调用 `$update-aura-compact-corpus`。它更新父嵌入和图证据，而无需重新运行完整的合并。
## 主要本地流程
```mermaid
flowchart LR
A["TXT / Markdown / PDF / YouTube"] --> B["规范结构化文档"]
B --> C["父和 MiniLM 安全子块"]
C --> D["Neo4j 向量和全文索引"]
C --> E["基于父图的提取"]
D --> F["混合检索和重排序"]
E --> F
F --> G["REST / MCP 引用答案"]
```
快速入门：
```powershell
.\.venv\Scripts\python.exe scripts\sync_corpus_graph.py create `
--dataset-dir C:\path\to\corpus `
--corpus-title 我的语料库
.\.venv\Scripts\python.exe scripts\serve_corpus_api.py
```
## 旧版 NotebookLM 流程
暂时保留用于蓝绿迁移和历史基准兼容性。`sync_notebook_graph.py` 已弃用，直接执行时委托给本地语料库同步器。参见 [旧版 NotebookLM 流程](docs/LEGACY_NOTEBOOKLM_PIPELINE.md) 以获取完整的设置、迁移和入门指南。
## 提供商、代理和技能
默认本地图构建嵌入是 `sentence-transformer`，使用 `all-MiniLM-L6-v2`。路由配置可以在这些提供商中切换嵌入、提示和判断角色：
| 提供商或运行时 | 环境变量 | 何时需要 | Python 依赖 |
| --- | --- | --- | --- |
| `genai` / `gemini` | `GOOGLE_API_KEY` | 当 `scripts/postprocess_graph.py` 或默认合并流程使用 Google 支持的提示/判断/嵌入角色时，或当 `--llm-routing-config` 选择 Google 支持的角色时 | `google-genai`, `langchain-google-vertexai` |
| `openai` | `OPENAI_API_KEY` | 当路由配置为嵌入或单提示角色选择 OpenAI 时 | `openai`, `langchain-openai` |
| `openrouter` | `OPENROUTER_API_KEY` | 当路由配置为嵌入或单提示角色选择 OpenRouter 时 | `openai`, `langchain-openai` |
| `codex` | ChatGPT 订阅登录 (`codex login`) | 订阅支持的单提示角色；CLI 以非交互方式调用，带有只读沙盒和结构化 JSON 输出 | Codex CLI |
| `claude` | Claude 订阅登录 (`claude auth login`) | 订阅支持的单提示角色；CLI 以非交互方式调用，带有禁用工具和结构化 JSON 输出 | Claude Code CLI |
| `sentence-transformer` | 无 | 默认本地图构建嵌入，或当显式选择本地嵌入时 | `sentence-transformers`, `langchain-huggingface` |
如果没有 `--llm-routing-config`，第 2 层、分类和第 3 层使用 `minimax/minimax-m3` 通过 OpenRouter 进行其主要提示角色。第 2 层在低推理努力时升级到订阅身份验证的 `gpt-5.6-luna` 通过 Codex，而第 3 层在中等努力时升级到相同的模型。分类的次要角色保持为 `gemini-3.1-pro-preview`，而第 3 层的嵌入保持为 `gemini-embedding-001`，因此默认合并需要 `OPENROUTER_API_KEY`、`GOOGLE_API_KEY` 和身份验证的 Codex CLI。在 Codex 单提示角色上设置 `reasoning_effort` 为 `low`、`medium`、`high` 或 `xhigh`；Claude 支持 `low`、`medium` 或 `high`。
支持的代理运行时用于审查或分类尾部步骤的是 `codex`、`claude` 和 `opencode`。如果没有路由配置，合并默认为 `codex`。
捆绑的 `neo4j-corpus-deep-research` 工作流程适用于 `.claude`、`.opencode` 和 `.codex`。它用 Neo4j 邻域扩展交替引用本地语料库检索，仅保留源可验证的分支，并在附加循环停止添加信号时停止。
## MCP 工具和代理技能
- 本地语料库 MCP (`scripts/serve_corpus_mcp.py`)：引用语料库搜索、答案、源元数据、图邻域和同步状态
- [`neo4j`](https://github.com/neo4j-contrib/mcp-neo4j)：模式读取和 Cypher 资源管理器
捆绑的深度研究包使用本地语料库 MCP 和可选的 Neo4j MCP：
- `.codex/skills/neo4j-corpus-deep-research/`
- `.claude/agents/neo4j-corpus-deep-research.md`
- `.opencode/agents/neo4j-corpus-deep-research.md`
提供技能的作用：
- 将引用语料库检索视为高上下文读取器，将 Neo4j 视为拓扑资源管理器
- 从有根答案开始，提取具体实体、概念、别名和开放问题
- 通过图邻域扩展最强的种子，然后将最佳图发现转换为更紧密的语料库后续
- 为相关性、新颖性、图支持和可解释性评估候选分支，并在循环停止添加信号时停止
示例用法：
```text
对语料库“my-corpus”和其连接的 Neo4j 图使用捆绑的 neo4j-corpus-deep-research 技能。研究这个问题：“哪些方法将基于图的检索与此语料库中的幻觉控制连接起来？”使用 3 次迭代循环预算并返回完整的技能输出。
```
在实践中，该工作流程查询本地语料库以获取初始引用答案，提取高信号种子，探测 Neo4j 获取邻域和桥接概念，验证图发现与源块，并返回具有最终答案、迭代日志、接受/拒绝分支、停止原因和自我批评的结构化报告。
## 仓库布局和叠加
- `vendor/llm-graph-builder/`：上游 `neo4j-labs/llm-graph-builder` 子模块
- `src/`：本地后端叠加模块，覆盖选定的上游行为
- `scripts/`：同步、图构建、后处理、评估和合并入口
- `tests/`：编排和叠加行为的回归覆盖
- `.claude/`、`.opencode/`、`.codex/`：捆绑的代理和技能定义
`src/` 覆盖 `vendor/llm-graph-builder/backend/src`。将本地后端行为更改放在叠加包中，而不是在托管的子模块中。
