<p align="center">
  <strong>简体中文</strong> · <a href="README.en.md">English</a>
</p>

<p align="center">
  <img src="docs/assets/tablerag-hero.svg" alt="TableRAG：表格网格汇入可追溯的证据关系图" width="100%">
</p>

# TableRAG

<p align="center">
  <strong>把 Excel / CSV 文件夹变成可追溯、只读的 AI 知识层。</strong>
</p>

<p align="center">
  <a href="https://github.com/BitDG/TableRAG/actions/workflows/ci.yml"><img src="https://github.com/BitDG/TableRAG/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB.svg" alt="Python 3.10+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-%E5%8F%AA%E8%AF%BB-2F8F6B.svg" alt="只读 MCP"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-15212B.svg" alt="Apache License 2.0"></a>
</p>

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

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

[快速开始](#快速开始) · [工作原理](#工作原理) ·
[AI 接入指南](docs/AI_ONBOARDING.md) · [配置参考](docs/CONFIGURATION.md) ·
[安全策略](SECURITY.md)

## 为什么需要 TableRAG

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

## 你会得到什么

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

## 工作原理

```mermaid
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](https://docs.astral.sh/uv/)。

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

```powershell
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：

```powershell
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`：

```json
{
  "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：

```powershell
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 接入指南](docs/AI_ONBOARDING.md)。

## 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](SECURITY.md)。

## 文档

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

## 开发

```powershell
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](LICENSE)