ShadowDoc Engine

让 LLM 以极低成本处理大型 Markdown 文档的智能引擎

简介

ShadowDoc Engine 是一个专门针对 PDF 转 Markdown（如 MinerU 输出）后的大型非结构化文档处理中间件。它通过构建"影子索引"，将 LLM 的上下文消耗降低 90% 以上。

核心特性

• 🚀 低成本处理：通过影子索引，LLM 只需查看行号、类型和预览，无需读取全文
• 🎯 精准拆分：利用 LLM 的认知能力配合绝对行号定位，解决传统正则拆分的局限
• 🧹 噪声清洗：自动识别页码、页眉等 OCR 噪声
• 📝 上下文增强：在拆分后的碎片中自动回填元数据

安装

# 使用 Bun
bun install

# 或使用 npm
npm install

快速开始

1. 基础引擎使用

import { ShadowDocEngine } from 'shadowdoc-engine';

const markdown = `# 我的文档
## 第一章
这是第一章的内容...
`;

const engine = new ShadowDocEngine('doc-1', markdown);

// 获取文档骨架
const skeleton = await engine.getDocumentSkeleton();
console.log(skeleton.structure);

// 影子扫描
const window = await engine.scanShadowWindow(10, 5);
console.log(window.lines);

// 搜索内容
const results = await engine.searchPattern('第一章');
console.log(results);

2. 使用 Agent 处理文档

import { processDocument } from 'shadowdoc-engine';

// 设置 OpenAI API Key
process.env.OPENAI_API_KEY = 'your-api-key';

const result = await processDocument(markdownContent, {
  modelName: 'gpt-4o-mini',
  userPrompt: '请分析文档结构并提取元数据',
});

console.log('元数据:', result.metadata);
console.log('拆分指令:', result.splitInstructions);

3. 流式处理

import { streamProcessDocument } from 'shadowdoc-engine';

const stream = streamProcessDocument(markdownContent, {
  modelName: 'gpt-4o-mini',
});

for await (const event of stream) {
  switch (event.type) {
    case 'tool_call':
      console.log('调用工具:', event.content);
      break;
    case 'message':
      console.log('Agent 消息:', event.content);
      break;
  }
}

Agent 工具

ShadowDoc Engine 为 LLM Agent 提供以下工具：

工具名	成本	描述
get_document_skeleton	低	获取文档骨架（所有标题）
scan_shadow_window	低	查看指定行周围的上下文
inspect_raw_content	高	读取原始 Markdown 内容
search_pattern	低	正则搜索定位内容
record_metadata	-	记录识别到的元数据
create_split_instruction	-	创建拆分指令

项目结构

src/
├── types.ts                    # 类型定义
├── engine/
│   └── shadow-doc-engine.ts    # 核心引擎
├── tools/
│   └── shadow-doc-tools.ts     # LangGraph 工具
├── agent/
│   └── document-agent.ts       # Agent 实现
├── index.ts                    # 主入口
└── example.ts                  # 使用示例

运行示例

# 运行基础示例（无需 API Key）
bun run example

# 运行完整示例（需要 OpenAI API Key）
OPENAI_API_KEY=your-key bun run example

配置

环境变量

变量名	描述	默认值
OPENAI_API_KEY	OpenAI API 密钥	-
OPENAI_BASE_URL	API 基础 URL	OpenAI 官方

Agent 配置

const result = await processDocument(content, {
  modelName: 'gpt-4o-mini',  // 模型名称
  temperature: 0,             // 温度
  apiKey: 'your-key',        // API Key
  baseURL: 'https://...',    // 自定义 API URL
});

类型定义

LineType

enum LineType {
  HEADER = 'HEADER',       // 标题
  TEXT = 'TEXT',           // 普通文本
  LIST_ITEM = 'LIST_ITEM', // 列表项
  CODE_BLOCK = 'CODE',     // 代码块
  IMAGE = 'IMAGE',         // 图片
  TABLE_ROW = 'TABLE',     // 表格行
  EMPTY = 'EMPTY',         // 空行
  NOISE = 'NOISE',         // 噪声（页码等）
  TOC_ITEM = 'TOC_ITEM',   // 目录项
}

SplitInstruction

interface SplitInstruction {
  id: string;              // 切片 ID
  startLine: number;       // 起始行
  endLine: number;         // 结束行
  context: {
    bookTitle: string;
    chapterTitle: string;
    chapterLevel: number;
    breadcrumb: string[];
  };
  cleaningRules?: {
    removeNoiseLines: boolean;
    fixBrokenTables: boolean;
  };
}

License

MIT