# 数据上报agent

**Repository Path**: thalion/data-reporting-agent

## Basic Information

- **Project Name**: 数据上报agent
- **Description**: 信创HIS数据上报开发工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-21
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HIS 数据报表 Agent

> 根据接口文档（DOCX / XLSX / PDF）自动生成 **KingbaseES** SQL 语句，支持 **JSON / XML / 结果集 / 存储过程** 四种输出格式，并通过表关联图谱与字段映射规则保证生成质量。

| 项目 | 信息 |
|------|------|
| 目标数据库 | KingbaseES（业务 schema 默认 `SM_HIS`） |
| 开发语言 | Python 3.8+（Agent 本体 + Web 服务） |
| MCP | kingbase-mcp（官方，本地启动） |
| 核心能力 | 文档解析 → 表关联图谱匹配 → 字段映射 → 生成 SQL → 数据库校验 → 图谱自动回流 |

## 功能特性

- **多格式输出**：JSON / XML / 结果集 / 存储过程四种格式（`templates/` 模板驱动）。
- **三通道模型**：`opencode` 免费通道 / `direct` 自有 API Key / `codebuddy` CLI，可在界面或配置切换。
- **Web 服务 + CLI 双形态**：浏览器可视化操作，或命令行批量校验。
- **表关联图谱**：按模块拆分（`references/table-graph/`），便于维护与扩展。
- **字段映射规则**：`rules/domains/` 按模块维护，越用越强。
- **数据库校验**：通过 kingbase-mcp 实时校验表/字段是否存在、取数是否可行。
- **字段规范性校验**：对照 `references/field-metadata/` 逐字段核对必填 / 日期格式 / 数值精度。
- **自动进化机制**：新字段映射 → 规则库回流；新表关联 → 图谱缺口检测并回流（回流前强制数据库验证）。

---

## 安装环境

> 以下安装项在 **macOS / Windows / Linux** 上均可完成，差异处已单独标注。

### 1. Python 与项目依赖（三大平台通用）

- 要求 **Python >= 3.8**（推荐 3.10+）。
- 在项目根目录安装依赖（`requirements.txt` 已区分平台，仅 Windows 会装 `pywinpty`）：

```bash
pip install -r requirements.txt
```

> 若系统并存 Python2/3，请用 `pip3` 或 `python3 -m pip`；Windows 建议在 PowerShell（管理员）中执行。

### 2. 安装 opencode CLI（**版本必须 1.19.\***）

> ⚠️ **版本硬性约束**：本项目只适配 opencode **`1.19.*`** 的 `serve` 协议，其它版本（更新或更旧）会导致生成通道不可用。**安装后必须用 `opencode --version` 确认显示 `1.19.x`**。
> opencode 仅在使用 `opencode` 免费通道时需要；若只用 `direct` / `codebuddy` 通道可不安装。

**方式 A（推荐，可精确锁定 1.19.x）：从 GitHub Release 取对应平台二进制**

到 https://github.com/opencode-ai/opencode/releases 选择 `v1.19.x` 中与你平台匹配的资产：

| 平台 | 资产名示例 |
|------|-----------|
| macOS Apple Silicon | `opencode-darwin-arm64` |
| macOS Intel | `opencode-darwin-amd64` |
| Windows x64 | `opencode-windows-amd64.exe` |
| Linux x64 | `opencode-linux-amd64` |
| Linux ARM64 | `opencode-linux-arm64` |

下载后放到 `PATH` 并赋予可执行权限（macOS/Linux：`chmod +x` 后移至 `/usr/local/bin/`；Windows：放入 `C:\opencode\` 并把该目录加入系统 PATH）。

**方式 B：官方一键脚本（装完请核对版本，非 1.19.x 请用方式 A 覆盖）**

```bash
# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

# Windows：在 PowerShell 或本机 WSL 中执行同样的命令
```

**验证（三大平台通用）**：

```bash
opencode --version      # 必须输出 1.19.x
```

> 服务启动时会自动探测 `opencode`（顺序：环境变量 `HIS_OPENCODE_CMD` → PATH → Windows 常见安装目录 → WSL 兜底）；若找不到会提示先安装。

### 3. 安装 KingbaseES MCP（连接数据库模式）

kingbase-mcp 提供表/字段校验能力，三种装法任选：

```bash
# 方式1（推荐）：uv 直接运行，无需本地安装
uv run --from kingbase-mcp kingbase-mcp --access-mode restricted

# 方式2：pip
pip install kingbase-mcp
kingbase-mcp --help

# 方式3：源码
git clone https://gitee.com/king-db/kingbase-mcp.git
cd kingbase-mcp && pip install -e .
```

**平台驱动差异**：
- **Windows / Linux**：`ksycopg2` 有官方 wheel，`pip`/`uv` 安装即用，无需额外处理。
- **macOS**：`ksycopg2` 无 macOS wheel，项目已内置兼容方案——`kingbase-mcp` 目录下的 `mac_compat/ksycopg2/` 把 `ksycopg2` 别名到 `psycopg2` 的 shim，`run_mac.sh` 启动器已配好 `PYTHONPATH`；本项目在 macOS 上由 `config.json` 的 `mcp.kingbase.command` 指向该 `run_mac.sh`（见下文「配置说明」）。

### 4. 安装 CodeBuddy CLI（仅 `codebuddy` 通道需要）

> CodeBuddy 通道通过本机 `codebuddy` CLI 以无头方式调用腾讯 CodeBuddy（个人版 / 企业版均可）。**仅当你要使用 `codebuddy` 模型通道时才需安装并登录**；使用 `opencode` / `direct` 通道无需安装。

**前置：Node.js** —— CodeBuddy CLI 是 Node.js 程序，需先安装 **Node.js 18+（推荐 22）**：
- macOS：`brew install node` 或 `nvm install 22`
- Windows：到 https://nodejs.org 下载 LTS 安装包
- Linux：`apt install -y nodejs npm` 或 `nvm install 22`

**安装 CLI**（目标：终端能直接执行 `codebuddy`）：

```bash
npm install -g @tencent-ai/codebuddy-code      # 若官方 npm 包名不同，请以 CodeBuddy（腾讯）官方安装指引为准
```

**登录（只需一次，登录态持久化在本机，与 CodeBuddy IDE 共享）**：

```bash
codebuddy            # 启动交互 TUI → 输入 /login → 按提示在浏览器完成授权
```

- 个人版：直接回车选默认项，浏览器授权即可。
- 企业版：在登录方式菜单选「Enterprise Domain」并输入企业域名（本项目默认 `https://donghuaruanjian.copilot.qq.com`）。
- 也可在 Web 服务「系统设置 → CodeBuddy」点「弹出登录页面」按钮，由后端自动驱动同一流程。

**验证（三大平台通用）**：

```bash
codebuddy --version                       # 确认 CLI 可用
codebuddy -p "只回复 ok" --permission-mode bypassPermissions -y --tools ""   # 确认已登录且可调用
```

> 本项目登录自动化流程在 **v2.173.0** 验证；若该版本之后登录交互有变动导致自动登录失败，可回退到 v2.173.0。登录态按平台自动存放（无需手动配置）：macOS `~/Library/Application Support/CodeBuddyExtension/...`、Windows `%APPDATA%\CodeBuddyExtension\...`、Linux `~/.config/CodeBuddyExtension\...`。

---

## 快速开始

1. 完成上方「安装环境」（Python 依赖；按需安装 opencode **1.19.\*** 或 CodeBuddy CLI；kingbase-mcp）。
2. 准备本地配置：复制模板并填写——`cp config.json.example config.json`，编辑填入 `database` 块（数据库连接）与 `llm_mode`（模型通道，见「配置说明」）。
3. 启动服务：`python -m src serve`，浏览器打开 `http://127.0.0.1:8000`（可用 `--open` 自动开浏览器）。

服务会：加载 `config.json` → 按需拉起本地 `opencode serve`（端口 4096）→ 提供 Web UI 与 API。

---

## 配置说明（重要）

配置分三层，请务必分清**已提交（公开）**与**本地私有（gitignore）**：

| 文件 | 是否提交 | 作用 |
|------|---------|------|
| `config.json.example` | ✅ 已提交 | 本地配置模板（占位符），复制为 `config.json` 后填写 |
| `config/default.json` | ✅ 已提交 | 全局默认/基线配置（MCP 默认值、医院信息、校验/进化设置），口令为占位符 |
| `config.json` | ❌ **gitignore（本地私有）** | 你的实际配置：**真实数据库连接 + 个性化模型设置**。复制自 `config.json.example` |
| `.mcp.json` | ❌ **gitignore（本地私有）** | MCP 配置文件，**由服务从 `config.json` 的 `database` 块自动同步生成，切勿手改、切勿提交** |

> ⚠️ **早期文档曾声称 `.mcp.json` / `opencode.json` / `config/default.json` 是"已提交脱敏版、需 `skip-worktree`"——该说法已过时**：
> - `config.json` 与 `.mcp.json` 现在**直接被 `.gitignore` 忽略**，本就不会进仓库，无需 `skip-worktree`。
> - 仓库里**不存在** `opencode.json`（opencode 由服务进程拉起，不再需要独立配置文件）。
> - 唯一需要你填真实值并本地保存的是 `config.json`。

### `config.json` 关键结构

```jsonc
{
  "host": "127.0.0.1",          // Web 服务监听地址
  "port": 8000,                 // Web 服务端口
  "opencode_port": 4096,        // opencode serve 端口
  "llm_mode": "opencode",       // 模型通道：opencode / direct / codebuddy

  "direct":  { "baseURL": "https://api.deepseek.com", "apiKey": "<你的Key>", "model": "deepseek-chat", "timeout": 600 },
  "codebuddy": { "model": "", "timeout": 600, "domain": "", "effort": "low", "max_output_tokens": 16384, "idle_logout_minutes": 0 },
  "opencode": { "model": "opencode/deepseek-v4.1-flash-free" },

  // 数据库连接统一配置（单一权威来源）：CLI 校验、服务端、MCP 全部从这里取
  "database": {
    "host": "<DB_HOST>",
    "port": 54321,
    "user": "<DB_USER>",
    "password": "<DB_PASSWORD>",
    "dbname": "<DB_NAME>",
    "schema": "SM_HIS"
  },

  // 兼容镜像：服务会把上面 database 块派生为连接串写入 .mcp.json，供 kingbase-mcp 使用
  "mcp": { "kingbase": { "environment": { "DATABASE_URI": "host=... port=... user=... password=... dbname=..." } } }
}
```

要点：
- **数据库连接只在一个地方配置**：`database` 块。服务会自动把它派生为 `mcp.kingbase.environment.DATABASE_URI` 并同步到 `.mcp.json`，无需手动维护连接串。
- `database_uri()` 优先读 `database` 块；`config/default.json` 仅作为兜底默认值。
- 医院信息、SQL 日期/时间格式等仍可在 `config/default.json` 中配置（已提交基线）。

### 模型通道（三选一）

| 通道 | 说明 | 需要 |
|------|------|------|
| `opencode`（默认） | 使用 opencode.ai 免费模型（如 `opencode/deepseek-v4.1-flash-free`），零成本 | 本机安装 `opencode` CLI |
| `direct` | 自有 API Key（DeepSeek / OpenAI 兼容等） | 在 `direct.apiKey` 填 Key |
| `codebuddy` | 通过 CodeBuddy CLI 调用 | 本机安装并登录 CodeBuddy |

切换方式：改 `config.json` 的 `llm_mode`，或在 Web UI「系统设置 → 模型通道」中切换（保存即生效，无需重启）。

> **关于 opencode 免费额度**：免费额度绑定你的 **opencode.ai 账号/设备身份**（存放在本机 `~/.config/opencode/`，不在仓库内）。因此**干净的 `git clone` 不会共享你的额度**。若同事的 clone 也共用了额度，几乎一定是把本地身份文件（整个项目文件夹含 `.git/`，或你的 `~/.config/opencode/`）一并拷贝了——请让对方用干净 clone 并各自登录自己的 opencode.ai 账号。

---

## 运行方式

### Web 服务模式（推荐）

```bash
python -m src serve            # 默认 127.0.0.1:8000
python -m src serve --open     # 启动后自动打开浏览器
python -m src serve --port 9000 --no-opencode   # 自定义端口 / 不自动拉起 opencode
```

在浏览器中：上传接口文档 → 选择接口 → 生成 SQL → 校验（表/字段/取数/图谱缺口）→ 导出。模型通道、数据库连接均在「系统设置」中配置。

> **注意**：点「保存模型」（仅切换模型通道）**不会**清空数据库连接；只有「数据库设置」保存才会更新连接。`config.json` 的 `database` 块与模型设置相互独立。

### 命令行模式（CI / 批量）

```bash
# 校验单个 SQL：表/字段存在性 + 取数可行性 + 表关联图谱缺口检测 + 自动回流
python scripts/validate_sql.py output/6_settlement_upload.sql

# 指定配置文件（默认即根 config.json；--config 也可指向 config/default.json 取全局基线）
python scripts/validate_sql.py output/6_settlement_upload.sql --config config.json

# 图谱缺口检测 / 回流（回流前强制验证，验证不过拒绝写入）
python scripts/graph_flowback.py check  output/6_settlement_upload.sql
python scripts/graph_flowback.py flowback output/6_settlement_upload.sql --apply

# 生成字段规范性自查表（对照 references/field-metadata/）
python scripts/validate_sql.py output/6_settlement_upload.sql --check-metadata
```

### 在 AI 工具中作为 Agent 使用

Agent 的本质 = 项目根目录的指令集（`AGENTS.md` / `CLAUDE.md`）+ 知识库 + 本地 `config.json` 数据库连接。**无需安装**，把工具工作目录指向本项目根即可：

- **opencode / Claude Code / CodeBuddy / Cursor / Trae**：打开项目根目录，自动加载 `AGENTS.md` 与 `CLAUDE.md`；MCP 由本项目的 `.mcp.json` 提供（服务运行时自动生成，或在工具中指向它）。
- 这些工具本身也通过 `python -m src serve` 提供的相同后端生成 SQL，效果一致。

---

## 校验与自动进化（图谱回流闸门）

生成 SQL 后**必须**运行校验，exit=0 才可交付：

```bash
python scripts/validate_sql.py <sql文件>
```

它依次做：① 表/字段存在性（连库改名纠正）→ ② 语法执行（EXPLAIN，模型重生纠正）→ ③ 取数可行性（实际跑样例）→ 表关联图谱缺口检测。

**回流闸门（关键）**：图谱缺口**仅当 ②语法执行 且 ③取数 均通过**才允许自动回流写入 `references/table-graph/`。这是为防止把模型写错的关联当成事实沉淀进图谱——SQL 本身未通过校验时，缺口映射未经实证，回流会被默认拦截，需人工确认。

---

## 目录结构

```
his-datareport-agent/
├── AGENTS.md / CLAUDE.md          # Agent 指令集（供 AI 工具读取）
├── README.md                     # 本文件
├── 00-导航.md                     # 项目导航
├── requirements.txt
├── config/
│   └── default.json              # 已提交：全局默认/基线配置（口令占位）
├── config.json.example           # 已提交：本地配置模板
├── config.json                   # 本地私有(gitignore)：真实数据库+模型设置
├── .mcp.json                     # 本地私有(gitignore)：服务自动同步的 MCP 配置
├── src/
│   ├── __main__.py               # 入口：python -m src serve
│   ├── db_connection.py          # KingbaseES 连接
│   ├── validator.py              # SQL 表/字段校验
│   ├── metadata_validator.py     # 字段规范性校验（必填/格式/精度）
│   ├── graph_validator.py        # 表关联图谱缺口校验
│   ├── graph_store.py            # 图谱存储
│   └── server/                   # Web 服务（FastAPI）
│       ├── app.py / config.py / pipeline.py / task_store.py / doc_parser.py
│       ├── opencode_client.py / direct_llm.py / codebuddy_client.py / codebuddy_login.py
│       ├── redline.py
│       ├── routers/              # system / models / generate / tasks / documents / graph
│       └── services/             # generation / mapping / parsing / field_meta / graph_context / table_context
├── scripts/
│   ├── validate_sql.py           # CLI 校验（默认读 config.json）
│   ├── graph_flowback.py         # 图谱缺口检测与自动回流
│   ├── import_data.py / import_data.sh / import_batch1.sh  # 远程库→本地 ETL
│   └── extract_pdf_tables.py / find_section.py / gen_first_page.py  # 文档解析辅助
├── references/
│   ├── table-graph/              # 表关联图谱（按模块拆分，21 个文件）
│   ├── field-metadata/           # 字段元数据（必填/格式/精度/长度）
│   ├── db_validation.md          # 数据库校验说明
│   ├── mcp_kingbase.md           # KingbaseES MCP 集成说明
│   └── sql_validation.md         # SQL 校验规则
├── rules/
│   ├── functions.md              # 公共函数库（F001~F0xx）
│   └── domains/                  # 字段映射规则（按模块拆分）
├── templates/                    # 输出格式模板（json/xml/result_set/stored_procedure/validation_report）
├── web/static/                   # Web UI（index.html / app.js / style.css）
├── examples/                     # 已完成 SQL 示例（门急诊/住院/在院）
├── output/                       # 生成的 SQL 输出（gitignore）
├── docs/                         # 接口文档存放（gitignore，本地；约定 input/ 放原始文档）
├── data/                         # 运行时数据（gitignore）
└── deploy/                       # 部署脚本（windows/、start.command）
```

---

## 安全与协作须知（务必阅读）

1. **不要提交真实口令**：`config.json` 与 `.mcp.json` 已被 `.gitignore` 忽略。任何含真实数据库口令、API Key 的内容都只留在本地。
2. **不要把整个项目文件夹拷给别人**：会一并带走 `.git/`（含本地 opencode 身份令牌）与本地配置，导致对方共享你的 opencode 免费额度等。交付请用 `git clone`（或 `git archive`）。
3. **口令一旦泄漏必须改密**：即便从仓库历史清除，已暴露的数据库口令/API Key 也必须去服务端重置，清除历史只是辅助。
4. **历史清理需谨慎**：若需把历史中的明文口令抹掉，用 `git filter-repo` 改写后 **force-push**，会重写共享历史、影响所有协作者，需团队共识。
5. **`config/default.json` 是公开基线**：里面口令为占位符；若要改全局默认值，请保持占位、不要写入真实值。

---

## 常见问题

**Q: 生成的 SQL 字段取值为空（TODO）怎么办？**
A: 该字段在规则库未命中。可在 `rules/domains/` 添加映射规则，或直接告诉 Agent 取值逻辑，会自动整理后回流规则库。

**Q: 如何添加新业务模块？**
A: 在 `references/table-graph/` 创建模块文件，参照现有格式描述表关系；字段映射放 `rules/domains/`。

**Q: MCP 连接失败？**
A: 检查 ① `config.json` 的 `database` 块是否正确 ② kingbase-mcp 是否已安装 ③ `<DB_HOST>:54321` 是否可访问 ④ 防火墙放行。

**Q: 保存模型后数据库连接没了？**
A: 旧版本有该 bug，现已修复——「保存模型」仅切换通道，不再清空 `database` 块；只有「数据库设置」保存才更新连接。若连接被清空，到「数据库设置」重新填入保存即可。

**Q: 切换两种模式（纯知识库 / 连库校验）？**
A: 不连库时校验类功能不可用；连库需在 `config.json` 填 `database` 块并安装 kingbase-mcp。生成本身无需数据库。

**Q: 如何支持新的数据库？**
A: 修改 `config.json` 的 `database` 块（及 `config/default.json` 的 MCP 默认值），并调整 SQL 模板语法。

---

## 相关文档

- [表关联图谱](references/table-graph/README.md) — 表关系详细说明
- [字段映射规则](rules/domains/common.md) — 通用映射规则
- [公共函数库](rules/functions.md) — 可直接调用的 `sm_his` 函数
- [数据库校验](references/db_validation.md) — 校验详细说明
- [KingbaseES MCP 集成](references/mcp_kingbase.md) — MCP 配置说明
- [SQL 校验规则](references/sql_validation.md) — 校验规则细则
- [字段元数据](references/field-metadata/README.md) — 元数据条目格式

## 许可证

内部项目，仅限授权使用。