# data-summary-agent

**Repository Path**: hackcat_admin/data-summary-agent

## Basic Information

- **Project Name**: data-summary-agent
- **Description**: 专门数表格数据的智能体。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据汇总智能体

面向单位内网的 B/S 表格盘点工具。上传 ZIP 后，系统递归遍历目录与嵌套 ZIP，统计 `.xls`、`.xlsx`、`.csv` 中的数据行，并把无法读取、低置信度和仅计数文件完整列入网页与 Excel 报告。

## 功能

- 最大 2GB 上传、5 万文件、10GB 解压容量，限制均可配置。
- 阻止路径穿越、符号链接、加密条目和异常压缩率。
- Excel 全部工作表纳入统计，包括隐藏与深度隐藏工作表。
- 兼容 WPS/第三方系统生成的错误工作表范围元数据，强制扫描真实 XLSX 行。
- CSV 自动识别常见中文编码、分隔符、引号与字段内换行。
- 本地规则优先；低置信度表头可并行调用 OpenAI 兼容模型，并可人工修正。
- 每次上传可独立选择是否启用模型辅助；页面可查看、切换和停止排队或执行中的任务。
- Excel 报告包含：汇总、文件明细、工作表明细、异常与存疑。
- 上传内容和报告默认保留 24 小时后自动清理。

## Linux 内网部署

1. 安装 Docker Engine 与 Docker Compose Plugin，确保服务器至少有 30GB 可用磁盘。
2. 复制环境配置并修改数据库密码：

   ```bash
   cp .env.example .env
   ```

3. 如果需要模型辅助，在 `.env` 配置 `LLM_BASE_URL`、`LLM_MODEL` 和 `LLM_API_KEY`。接口需兼容 `/chat/completions`；`LLM_CONCURRENCY` 控制模型复核并发数，`LLM_MAX_TOKENS` 控制包含思考过程在内的单次最大输出，默认 `512`。不配置模型也能正常工作，低置信度结果会进入待复核。
4. 构建并启动：

   ```bash
   docker compose up -d --build
   ```

5. 浏览器访问 `http://服务器地址/`。查看状态：

   ```bash
   docker compose ps
   docker compose logs -f api worker
   ```

升级时重新拉取代码并执行 `docker compose up -d --build`。持久数据位于 Docker volumes；删除容器不会自动删除数据库和任务卷。

### ARM64 离线部署

仓库的 `deploy/arm64/` 包含 ARM64 离线 Compose 模板和部署说明。生成好的离线包解压后，先执行：

```bash
docker load -i data-summary-agent-arm64-images.tar
cp env.example .env
docker compose up -d
```

目标系统须为 64 位 ARM Linux，`uname -m` 输出 `aarch64` 或 `arm64`。

## 本地开发

前端需要 Node.js 22+：

```bash
npm ci
npm run dev
```

后端需要 Python 3.12：

```bash
cd backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt
INLINE_TASKS=true DATABASE_URL=sqlite:///./work/app.db STORAGE_ROOT=./work .venv/bin/uvicorn app.main:app --reload
```

本地联调时可使用 Nginx、反向代理或将前端请求转发到 `http://localhost:8000`。生产环境由根目录 `nginx/nginx.conf` 统一路由。

## 统计口径

系统先在前 20 行中识别表头。数据条数为表头结束行之后“至少一个有效单元格非空”的行数；中间空行不终止统计。不同工作簿和工作表之间不合并、不去重。`.et`、`.pdf`、`.rar`、`.7z` 及其他非目标格式只统计文件数量。

模型只会接收低置信度工作表前 20 行、前 30 列的截断样本，不负责直接计算行数。本地统计完成后，系统以有界并发复核存疑工作表；模型请求失败不会阻断任务。模型返回不同表头位置时，系统按新位置重新统计该工作表。

任务 ID 会写入页面地址的 `taskId` 查询参数，因此刷新页面后仍会恢复当前任务。停止任务后，中间结果与源文件仍按保留期限清理。

## 测试

```bash
npm test
cd backend
pytest -q
```

后端测试覆盖多工作表、隐藏表、GB18030 CSV、字段内换行、嵌套 ZIP、不安全路径、人工修正和 Excel 报告生成。