Metadata-Version: 2.4
Name: semantic-sheet
Version: 0.2.0
Summary: 表格语义化理解工具 — 用 AI 理解表结构和列含义，支持 xlsx/csv/ods
License-Expression: MIT
Keywords: excel,semantic,ai,cli,pandas
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openpyxl>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: click>=8.1
Requires-Dist: pandas>=2.0
Requires-Dist: platformdirs>=3.0
Provides-Extra: ods
Requires-Dist: odfpy>=1.4; extra == "ods"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# Semantic Sheet CLI

Excel 语义化理解工具。用 AI 扫描表格文件（xlsx / csv / ods），理解表结构（含多层表头）和列含义，生成结构化语义标注，供外部 Agent 或数据管道直接消费。

## 环境要求

| 项目 | 要求 |
|---|---|
| Python | >= 3.10 |
| pip | 最新版（建议升级：`pip install --upgrade pip`） |
| LLM API | 任何 OpenAI 兼容的 Chat Completions API（如 OpenAI、DeepSeek、Azure OpenAI 等） |
| 网络 | 需能访问上述 LLM API 端点 |

运行时依赖（由 pip 自动安装）：
- `openpyxl>=3.1` — Excel (.xlsx/.xlsm) 结构解析（合并单元格）
- `pandas>=2.0` — 多格式数据读取（xlsx/csv/ods）
- `httpx>=0.27` — 异步 HTTP（调用 LLM API）
- `click>=8.1` — CLI 框架
- `platformdirs>=3.0` — 跨平台路径管理

可选依赖：
- `[ods]` — `pip install semantic-sheet[ods]`，安装 `odfpy>=1.4` 以支持 ODS 格式
- `[dev]` — `pip install semantic-sheet[dev]`，安装 `pytest>=7.0`

## 安装

```bash
# 克隆项目
git clone <repo-url>
cd excel-agent-plugin

# 基本安装（支持 xlsx / csv）
pip install -e .

# 安装 ODS 格式支持
pip install -e ".[ods]"

# 安装开发依赖
pip install -e ".[dev]"
```

安装完成后，`semantic-sheet` 命令即可使用。

验证安装：
```bash
semantic-sheet --version
# 输出: 0.2.0
```

## 配置

扫描需要调用 LLM API，因此必须配置 API Key。有三种方式：

### 方式 1：环境变量（最快，适合脚本/CI）

```bash
# Windows CMD
set SEMANTIC_SHEET_API_KEY=your-api-key
set SEMANTIC_SHEET_API_BASE=https://api.openai.com/v1
set SEMANTIC_SHEET_MODEL=gpt-4o

# Windows PowerShell
$env:SEMANTIC_SHEET_API_KEY="your-api-key"
$env:SEMANTIC_SHEET_API_BASE="https://api.openai.com/v1"
$env:SEMANTIC_SHEET_MODEL="gpt-4o"

# Linux/macOS
export SEMANTIC_SHEET_API_KEY=your-api-key
export SEMANTIC_SHEET_API_BASE=https://api.openai.com/v1
export SEMANTIC_SHEET_MODEL=gpt-4o
```

使用非 OpenAI 端点时，只需修改 `API_BASE`：
```bash
# DeepSeek 示例
set SEMANTIC_SHEET_API_BASE=https://api.deepseek.com/v1
set SEMANTIC_SHEET_API_KEY=your-deepseek-key
set SEMANTIC_SHEET_MODEL=deepseek-chat
```

### 方式 2：交互式初始化

```bash
semantic-sheet init
# 依次输入: API Key / API Base URL / 模型名称
```

### 方式 3：命令行设置

```bash
semantic-sheet config --set api_key=your-key
semantic-sheet config --set api_base=https://api.openai.com/v1
semantic-sheet config --set model=gpt-4o
```

### 配置存储

配置文件路径（由 platformdirs 自动确定）：
- Windows: `%APPDATA%\semantic-sheet\config.json`
- Linux/macOS: `~/.config/semantic-sheet/config.json`

语义数据存储路径：
- Windows: `%APPDATA%\semantic-sheet\data.db`
- Linux/macOS: `~/.local/share/semantic-sheet/data.db`

### 配置优先级

环境变量 > 配置文件 > 默认值

查看当前配置：
```bash
semantic-sheet config --show
```

## 支持的文件格式

| 格式 | 扩展名 | 说明 | 依赖 |
|---|---|---|---|
| Excel | `.xlsx`, `.xlsm` | 支持合并单元格、多层表头 | openpyxl（默认安装） |
| CSV | `.csv` | 单 sheet，无合并单元格 | pandas（默认安装） |
| ODS | `.ods` | OpenDocument 格式 | odfpy（需 `[ods]` extras） |

扫描目录时自动识别格式：
```bash
semantic-sheet scan ./data/   # 递归查找所有 xlsx/csv/ods 文件
```

## 使用

### 基本扫描

```bash
# 扫描单个文件（交互模式，遇到不确定的列会提问）
semantic-sheet scan 成绩表.xlsx

# 扫描 CSV 文件
semantic-sheet scan data.csv

# 扫描 ODS 文件（需安装 [ods] extras）
semantic-sheet scan report.ods

# 扫描目录（递归查找所有 xlsx/csv/ods 文件）
semantic-sheet scan ./data/

# 限制递归深度
semantic-sheet scan ./data/ --max-depth 2

# 不递归子目录
semantic-sheet scan ./data/ --no-recursive
```

扫描完成后，语义标注自动写入 SQLite 数据库。

### 非交互模式（供外部 Agent 使用）

```bash
# 不提问，不确定时中断并返回 JSON（exit code 10）
semantic-sheet scan 成绩表.xlsx --yes
```

非交互模式下，当 Agent 需要用户输入时，程序以 exit code 10 退出，stdout 输出 `needs_input` JSON，外部 Agent 可捕获后注入答案重新运行：

```bash
# 注入已知答案（可多次使用）
semantic-sheet scan 成绩表.xlsx --yes \
  --known-answer "生排=生物排名" \
  --known-answer "sf=生活费"
```

### 后台模式

```bash
# 立即返回 task_id，后台执行扫描
semantic-sheet scan 成绩表.xlsx --background

# 查看后台任务
semantic-sheet status

# 查看指定任务
semantic-sheet status <task_id>
```

### 指定模型

```bash
# 临时使用其他模型
semantic-sheet scan 成绩表.xlsx --model gpt-4o-mini
```

### 查看结果

```bash
# 读取语义标注（人类可读格式）
semantic-sheet read 成绩表.xlsx

# JSON 格式（供程序消费）
semantic-sheet read 成绩表.xlsx --json

# 只看某个 Sheet
semantic-sheet read 成绩表.xlsx --sheet "成绩汇总"

# 列出所有已索引的条目
semantic-sheet list

# JSON 格式列出
semantic-sheet list --json
```

### 生成 Pandas 代码

```bash
# 生成代码（根据文件格式自动选择 pd.read_excel 或 pd.read_csv）
semantic-sheet code 成绩表.xlsx

# 只生成某个 Sheet 的代码
semantic-sheet code 成绩表.xlsx --sheet "成绩汇总"

# CSV 文件自动生成 pd.read_csv
semantic-sheet code data.csv

# ODS 文件自动生成 pd.read_excel(engine='odf')
semantic-sheet code report.ods
```

对于多层表头，自动生成 `pd.read_excel(header=[0, 1])` 代码并附带 flatten 列名的注释。

### 多表关联

```bash
# 自动检测指定文件之间的关联键（基于同名列）
semantic-sheet relate 成绩表.xlsx 学生表.xlsx --auto-detect

# 扫描所有已索引条目之间的关联
semantic-sheet relate --all --auto-detect
```

### 记忆库

记忆库存储跨扫描会话的领域知识（缩写含义、术语映射等），每次扫描时自动注入 Agent prompt。记忆存储在 SQLite 数据库中，支持去重和导出/导入。

```bash
# 添加一条记忆
semantic-sheet memory --add "生排=生物排名"

# 查看所有记忆
semantic-sheet memory --list

# 导出记忆为 Markdown 文件（方便查看和编辑）
semantic-sheet memory --export memory_backup.md

# 从 Markdown 文件导入记忆到数据库
semantic-sheet memory --import memory_backup.md

# 清空记忆库
semantic-sheet memory --clear --yes
```

### 清理

```bash
# 自动删除源文件已不存在的过期条目（从数据库删除）
semantic-sheet clean --auto-stale --yes
```

## 多层表头支持

Semantic Sheet 支持识别和理解多层（复杂）表头，包括：

- **合并单元格层级表头**：如第 1 行 "成绩信息" 合并跨越 A-C 列，第 2 行是 "语文|数学|英语"
- **多行表头**：连续多行共同定义列含义
- **混合深度**：部分列单层表头，部分列多层表头

扫描结果中，每列会生成 `headerPath` 字段，如：

```json
{
  "col": "C",
  "name": "语文",
  "headerPath": ["成绩信息", "语文"],
  "type": "number",
  "role": "measure",
  "description": "成绩信息类别下的语文科目分数"
}
```

单层表头时 `headerPath` 为 `["列名"]`，与旧版完全兼容。

`read` 命令显示为 `成绩信息 > 语文` 格式。

## 完整命令参考

```
semantic-sheet init                  交互式配置 API Key / Base / Model
semantic-sheet scan <path>           扫描文件或目录
  --yes                              非交互模式（exit code 10）
  --background                       后台模式
  --model <name>                     临时指定模型
  --known-answer <str>               注入已知答案（可多次）
  --max-depth <n>                    递归深度限制
  --no-recursive                     不递归子目录
semantic-sheet list                  列出已索引条目
  --json                             JSON 输出
  --all                              含无语义数据的条目
semantic-sheet read <path>           读取语义标注
  --json                             JSON 输出
  --sheet <name>                     指定 Sheet
  --columns                          只看列信息
semantic-sheet code <path>           生成 Pandas 代码
  --sheet <name>                     指定 Sheet
semantic-sheet relate <f1> <f2> ...  多表关联检测
  --auto-detect                      自动检测关联键
  --all                              扫描全部已索引条目
  --name <str>                       关联集名称
semantic-sheet memory                管理记忆库
  --add <str>                        添加记忆
  --list                             列出记忆
  --export <path>                    导出为 Markdown 文件
  --import <path>                    从 Markdown 文件导入
  --clear                            清空记忆
semantic-sheet config                管理配置
  --set <key=value>                  设置配置项
  --show                             显示当前配置
semantic-sheet status [task_id]      查看后台任务
semantic-sheet clean                 清理过期条目
  --auto-stale                       自动清理源文件已不存在的条目
  --days <n>                         过期天数阈值（默认 30）
  --yes                              自动确认
semantic-sheet --version             显示版本号
```

## 语义标注数据格式

`semantic-sheet read --json` 输出的 JSON 结构：

```json
{
  "$schema": "https://semantic-sheet.dev/v1",
  "version": "1.0",
  "source_file": "成绩表.xlsx",
  "description": "学生成绩汇总表",
  "sheets": [
    {
      "sheet_name": "成绩汇总",
      "description": "包含学生基本信息和各科成绩",
      "header_row": 1,
      "header_rows": [1, 2],
      "header_depth": 2,
      "columns": [
        {
          "col": "A",
          "name": "姓名",
          "headerPath": ["基本信息", "姓名"],
          "type": "string",
          "role": "label",
          "description": "学生姓名"
        }
      ]
    }
  ]
}
```

字段说明：

| 字段 | 说明 |
|---|---|
| `name` | 最底层列名（叶子节点） |
| `headerPath` | 从上到下的完整表头路径，单层表头为 `["列名"]` |
| `type` | 数据类型：string / number / date / boolean / unknown |
| `role` | 语义角色：label / dimension / measure / key / unknown |
| `header_depth` | 表头层级数，1 = 单层，2+ = 多层 |
| `header_rows` | 表头行号列表（1-based），如 `[1, 2]` |

## 存储架构

Semantic Sheet 使用 SQLite 数据库存储所有数据（语义标注、任务、记忆），单文件、零配置、高性能。

- **数据库路径**：由 `platformdirs` 自动确定
  - Windows: `%APPDATA%\semantic-sheet\data.db`
  - Linux/macOS: `~/.local/share/semantic-sheet/data.db`
- **并发安全**：WAL 模式 + `threading.local()` 连接池
- **数据完整性**：外键约束 + CASCADE 删除

数据库表：

| 表 | 说明 |
|---|---|
| `entries` | 文件索引（路径、状态、格式、sheet 数） |
| `sheets` | 工作表信息（表头行、深度、描述） |
| `columns` | 列信息（名称、路径、类型、角色、描述） |
| `tasks` | 后台任务（状态、结果） |
| `memory` | 记忆库（领域知识，支持去重） |
| `schema_version` | 版本追踪 |

`semantic-sheet read --json` 从数据库重建完整 JSON，格式与旧版文件存储完全兼容。

## 项目结构

```
excel-agent-plugin/
  pyproject.toml                     包配置 & 入口点定义
  requirements.txt                   依赖清单
  semantic_sheet/                    主 Python 包
    __init__.py                      版本号
    cli.py                           Click CLI（所有子命令）
    db.py                            SQLite 数据库层（CRUD + 连接管理）
    scanner.py                       表格结构扫描（多格式 + 多层表头检测）
    config.py                        配置加载（env > file > defaults，platformdirs）
    store.py                         数据库入口层（thin wrapper over db.py）
    memory.py                        记忆库管理（DB + 导出/导入 Markdown）
    task_manager.py                  后台任务线程管理
    utils.py                         哈希、路径、文件查找工具
    agent.py                         ReAct Agent 循环（最多 20 步）
    llm.py                           异步 LLM 客户端（OpenAI 兼容）
    prompt_templates/system.md       Agent 系统 prompt 模板
    tools/
      registry.py                    工具注册与调度
      scan_sheet.py                  scan_sheet 工具
      ask_user.py                    ask_user 工具（交互/非交互）
      write_semantic.py              write_semantic 工具
      update_memory.py               update_memory 工具
  skill/
    SKILL.md                         外部 Agent 集成指南（CLI 命令引用）
```

## Agent 工作原理

Semantic Sheet 使用 ReAct (Reasoning + Acting) 循环：

1. **Think** — LLM 分析当前信息，推理列含义
2. **Act** — LLM 调用工具（scan_sheet / ask_user / write_semantic / update_memory）
3. **Observe** — 工具返回结果，LLM 继续推理

最多 20 步循环，最终调用 `write_semantic` 写入数据库。

## 为外部 Agent 集成

Semantic Sheet 设计为可被外部 AI Agent 调用。典型集成流程：

```bash
# Step 1: 非交互扫描，可能因不确定而中断（exit code 10）
semantic-sheet scan data.xlsx --yes

# 如果 exit code = 10，stdout JSON 中包含 needs_input 信息
# 解析后注入答案重试：
semantic-sheet scan data.xlsx --yes \
  --known-answer "生排=生物排名"

# Step 2: 读取结果（JSON 格式）
semantic-sheet read data.xlsx --json

# Step 3: 生成 Pandas 代码
semantic-sheet code data.xlsx

# Step 4: 检测多表关联
semantic-sheet relate --all --auto-detect
```

详见 `skill/SKILL.md`。

## 常见问题

### 扫描失败：API Key 未配置

```
[X] 未配置 API Key
  提示: 请先设置 API Key
    方式 1: semantic-sheet init
    方式 2: set SEMANTIC_SHEET_API_KEY=your_key
    方式 3: semantic-sheet config --set api_key=your_key
```

### 扫描失败：无法连接 LLM API

检查 `API_BASE` 是否正确，网络是否可达。如使用代理：

```bash
# Windows
set HTTPS_PROXY=http://proxy:port

# Linux/macOS
export HTTPS_PROXY=http://proxy:port
```

### ODS 文件扫描失败

确保安装了 `odfpy`：

```bash
pip install semantic-sheet[ods]
```

### 中文乱码（Windows CMD）

Windows CMD 默认编码为 GBK，可能导致中文显示乱码。解决方法：

```cmd
chcp 65001
```

或使用 PowerShell / Windows Terminal。

## License

MIT
