semantic-sheet 0.2.0

表格语义化理解工具 — 用 AI 理解表结构和列含义，支持 xlsx/csv/ods

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

安装

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

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

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

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

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

验证安装：

semantic-sheet --version
# 输出: 0.2.0

配置

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

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

# 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：

# 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：交互式初始化

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

方式 3：命令行设置

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

配置优先级

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

查看当前配置：

semantic-sheet config --show

支持的文件格式

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

扫描目录时自动识别格式：

semantic-sheet scan ./data/   # 递归查找所有 xlsx/csv/ods 文件

使用

基本扫描

# 扫描单个文件（交互模式，遇到不确定的列会提问）
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 使用）

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

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

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

后台模式

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

# 查看后台任务
semantic-sheet status

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

指定模型

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

查看结果

# 读取语义标注（人类可读格式）
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 代码

# 生成代码（根据文件格式自动选择 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 列名的注释。

多表关联

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

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

记忆库

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

# 添加一条记忆
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

清理

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

多层表头支持

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

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

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

{
  "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 结构：

{
  "$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 调用。典型集成流程：

# 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 是否正确，网络是否可达。如使用代理：

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

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

ODS 文件扫描失败

确保安装了 odfpy：

pip install semantic-sheet[ods]

中文乱码（Windows CMD）

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

chcp 65001

或使用 PowerShell / Windows Terminal。

License

MIT