---
description: "把一个已构建的 TableRAG 目录连接到 DeepSeek Harness，并作为模型可调用的原生工具。"
kind: "package-bundle"
---

# dsh-TableRAG

[English](README.md) | 中文

`dsh-TableRAG` 把一个已经构建的 [TableRAG](https://github.com/BitDG/TableRAG) 目录连接到 DeepSeek Harness profile。DSH 通过随附的 MCP client 启动本地只读 TableRAG stdio server，并把目录工具暴露为 `mcp__tablerag__<tool>`。

这个 bundle 不包含表格、项目 YAML、DuckDB 数据库、凭据或 Python 运行时。TableRAG 继续负责索引、来源证据和只读查询行为。

## 前置条件

1. 安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
2. 安装 [TableRAG](https://github.com/BitDG/TableRAG)，创建项目 YAML 并完成索引构建。
3. 准备项目 YAML 的绝对路径，以及启动 DSH 的 PowerShell 进程能够访问的 `table-rag` 可执行文件。

TableRAG 仓库提供项目配置和索引构建说明。使用源码 checkout 时，常用构建命令为：

```powershell
uv sync --extra dev --locked
uv run table-rag build --project projects\my-project.local.yaml
```

## 从 GitHub 安装

在即将启动 DSH 的同一个 PowerShell 进程中设置目录路径。`table-rag` 不在 `PATH` 时还要设置 `TABLERAG_EXECUTABLE`：

```powershell
$env:TABLERAG_PROJECT = 'C:\path\to\TableRAG\projects\my-project.local.yaml'
$env:TABLERAG_EXECUTABLE = 'C:\path\to\TableRAG\.venv\Scripts\table-rag.exe'
dsh plugin --profile web add github:BitDG/dsh-TableRAG
dsh --profile web --dump-config
dsh --profile web
```

`--dump-config` 必须显示 `mcp-tablerag` 配置项。缺少项目变量、执行文件无效、索引不存在或 MCP 发现失败时，插件激活会直接失败，不会发布一个空的 TableRAG 连接。

移除 bundle：

```powershell
dsh plugin --profile web remove dsh-tablerag
```

可以换用其他 profile 名称，让这条连接不影响无关会话。只有 MCP 子进程必须从项目 YAML 所在目录之外启动时，才需要设置可选的 `TABLERAG_CWD`。

## 模型获得的能力

DSH MCP client 会发现 TableRAG 工具，并注册以下稳定名称：

- `mcp__tablerag__get_project`
- `mcp__tablerag__find_tables`
- `mcp__tablerag__search_knowledge`
- `mcp__tablerag__get_record`

调用与受限结果经过 DSH 的普通工具执行流程和会话日志。验收部署时应调用 `mcp__tablerag__get_project`，并核对返回的项目身份和目录统计。

## 工作原理

[`cordis.patch.yml`](cordis.patch.yml) 插入一条 `@deepseek-ai/dsh-mcp-client` 配置：

- `TABLERAG_PROJECT` 选择项目 YAML 和目录。
- `TABLERAG_EXECUTABLE` 选择 TableRAG 控制台程序，默认使用 `PATH` 中的 `table-rag`。
- `TABLERAG_CWD` 可以覆盖子进程工作目录。
- `serverName: tablerag` 让模型工具名和权限规则在重启后保持稳定。
- `failOnStartupError: true` 防止 DSH 在没有 TableRAG 工具时静默启动。

所选 DSH profile 拥有连接生命周期和重连行为。TableRAG 继续拥有表格发现、索引构建、DuckDB 访问、来源证据和只读查询语义。

## 限制

- 一个 bundle 实例在固定的 `tablerag` namespace 下连接一个项目 YAML。一个 DSH 进程需要暴露另一个目录时，应增加一条使用不同名称的 profile 配置。
- DSH 只消费 MCP tools，不桥接可选的 `tablerag://catalog` MCP resource；等价的项目和表信息可以通过工具读取。
- 环境变量属于启动进程。需要跨 shell 持久保存路径时，使用可信的本地启动脚本或明确覆盖 profile 配置项。不要提交本机路径或凭据。
- 这个 bundle 不安装 TableRAG、不构建索引，也不修改源表。

## 开发验证

```powershell
npm test
npm run pack:check
```

从本地 checkout 安装：

```powershell
dsh plugin --profile web add 'file:C:/path/to/dsh-TableRAG'
```

采用 Apache-2.0 许可证。