TableRAG

简体中文 · English

TableRAG

把 Excel / CSV 文件夹变成可追溯、只读的 AI 知识层。

TableRAG 将 .xls、.xlsx、.xlsm 和 .csv 文件夹构建成本地语义目录。它在 DuckDB 中保留精确记录，识别字段、规则和跨表关系，并通过 MCP、CLI 与本地 Web 工作台提供确定性的只读查询。

无需模型或 Embedding 服务。项目路径、表格约定和人工确认的领域知识都保存在 YAML 中，不会硬编码进 Python 包。

快速开始 · 工作原理 · AI 接入指南 · 配置参考 · 安全策略

为什么需要 TableRAG

表格使用中的问题	TableRAG 的处理方式
AI 每次都要重新打开并解析大量工作簿	使用 SHA-256 增量索引，形成可复用的本地目录
不同文件的表头行和字段含义不一致	自动检测，并支持按 Sheet 显式确认语义布局
搜索结果脱离原始表格，无法复核	保留工作簿、Sheet、行、列和单元格证据
相似字段名容易形成错误关联	候选关系与人工验证关系严格分开
切换 Git 分支后配置数据互相污染	可选的分支隔离 DuckDB 目录
业务表格包含敏感数据	源表只保留在本地，TableRAG 永不修改源文件

你会得到什么

• 精确记录查询、字段过滤、表发现、规则搜索和关系追踪。
• 跨 Schema、注释、规则、关系与记录的统一证据搜索。
• 验证候选主键，而不是默认第一列必然唯一。
• 显式规则和推断规则分别保存，并携带置信度与单元格证据。
• 可配置字段名、中文注释、英文说明、字段类型和项目元数据所在行。
• 从指定目录或自动发现的 strings/cn 目录加载正式名称与本地化文本。
• Excel / WPS 保存后的防抖增量更新，以及单写入者索引队列。
• 字段级人工知识，区分候选、已验证和已废弃状态。
• 支持本地 stdio、Streamable HTTP 和兼容 SSE 的只读 MCP。
• 用于范围确认、表格预览、布局修复、诊断、知识审核和构建的本地 Web 工作台。

工作原理

flowchart LR
    A["表格文件夹"] --> B["范围与布局规则"]
    B --> C["解析与诊断"]
    C --> D["DuckDB 语义目录"]
    K["人工验证的项目知识"] --> D
    D --> E["CLI"]
    D --> F["只读 MCP"]
    D --> G["本地 Web 工作台"]
    F --> H["AI 客户端"]

目录中保存规范化记录、Schema 元数据、规则、关系、本地化信息和可搜索语义文档。 所有检索结果都能回到源表证据；TableRAG 不会写入源表。

快速开始

需要 Python 3.10+ 和 uv。

Windows 用户可以双击 start.bat 打开本地配置工作台，也可以直接执行：

cd C:\path\to\TableRAG
uv sync --extra dev
uv run table-rag init C:\path\to\spreadsheet-folder `
  --output projects\my-project.local.yaml `
  --name "My Project"
uv run table-rag web --project projects\my-project.local.yaml

在 Web 工作台中依次完成：

1. 确认数据目录、文件类型、递归范围、需要处理的 Sheet 和排除列。
2. 预览工作簿，确认或修复语义行布局。
3. 处理阻塞诊断，防止结构异常的表进入当前目录。
4. 构建索引并复制生成的 MCP 配置。

需要自动化时可以直接使用 CLI：

uv run table-rag build --project projects\my-project.local.yaml
uv run table-rag doctor --project projects\my-project.local.yaml
uv run table-rag query --project projects\my-project.local.yaml --table item --id 1001
uv run table-rag rag --project projects\my-project.local.yaml --query "查找道具字段和记录"
uv run table-rag watch --project projects\my-project.local.yaml

本地项目文件使用 .local.yaml 后缀，并已被 Git 忽略。

连接 AI 客户端

本地桌面客户端优先使用 stdio：

{
  "mcpServers": {
    "TableRAG": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\TableRAG",
        "run",
        "table-rag",
        "mcp",
        "--project",
        "C:\\path\\to\\TableRAG\\projects\\my-project.local.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

本机 Streamable HTTP：

uv run table-rag mcp `
  --project projects\my-project.local.yaml `
  --transport streamable-http `
  --host 127.0.0.1 `
  --port 8765

端点为 http://127.0.0.1:8765/mcp。除非外部已经配置身份验证、TLS 和明确的网络策略， 否则应始终保持 localhost 监听。完整交接、验证与查询路由见 AI 接入指南。

MCP 查询面

用途	MCP 工具
项目与 Schema 发现	get_project、list_tables、find_tables、describe_table、describe_column
精确记录	get_record、get_records_by_field、search_records
语义检索	search_knowledge、search_project_knowledge、search_rules
关系与解释	trace_relations、get_field_knowledge、explain_record

所有工具均为只读。规则会说明它是显式规则还是推断规则，并返回置信度和 orders.xlsx#Sheet1!F1 形式的源证据。

安全边界

• 源表是只读输入，TableRAG 永不修改源表。
• 本地项目 YAML、DuckDB 目录、基准原始输出和构建产物均被 Git 忽略。
• Web 工作台只监听 localhost，并将预览路径限制在已确认的数据范围内。
• 表格显式规则、人工知识和统计推断始终可以区分。
• 已验证关系在进入普通语义搜索前，会对当前分支目录进行字段检查。

暴露 MCP 端点或分享仓库快照前，请阅读 SECURITY.md。

文档

文档	用途
AI 接入指南	可复制的 MCP 配置、验证步骤和查询路由
配置参考	数据源、布局、本地化、分支、Watcher 与项目知识
贡献指南	开发环境、测试、PR 和数据安全规则
安全策略	私密报告方式和部署边界

开发

uv sync --extra dev --locked
uv run pytest
uv build
uv run python scripts\check_repository_secrets.py --include-untracked

默认 VS Code 构建任务会运行测试并构建 wheel。CI 覆盖 Windows、Linux 和受支持的 Python 版本。

许可证

Apache License 2.0