办公轻量数据库 Office DB

Overview

帮没有 DBA 的办公族把表格数据（CSV / TSV / JSON / xlsx 多 sheet）变成一个可反复 SQL 查询的本地 SQLite 库，替代"Excel 撑不住、MySQL 不会装"的中间地带：

建库 → 导入 → 查询 → 导出 → 备份 → 建索引，一个 Job 一次装好，之后随口问、随时导出。

• 零安装：SQLite 是文件数据库，.db 文件即库，可拷贝可传输；
• 零第三方依赖：脚本纯 Python 标准库，零网络调用；
• 数据不出设备：全流程本地完成。

对办公族友好的导入增强：
- 自动编码探测：导入 CSV/TSV 时依次尝试 utf-8-sig → utf-8 → gbk → latin-1，绝大多数中文 Excel/CSV 直接可用，无需手动转码；
- 中文列名自动清洗：商品名称、数量(件) 等中文或含空格/括号/特殊字符的列名，自动转成合法 SQL 字段名并保真映射，不丢列、不错位。

硬约束（Agent 每次必须遵守）

1. 查询默认只读连接：scripts/query.py 以 file:xxx?mode=ro 打开库，任何写语句被 SQLite 物理拒绝（attempt to write a readonly database）。禁止为图省事用可写连接跑用户查询。
2. DDL/DML 走确认闸门：需要写入（建索引、删表、清空、恢复）时必须用 scripts/db_manage.py，且先向用户展示影响（表名+行数+将执行的操作），征得确认后带 --yes 执行；工具会在每次写前自动做时间戳备份。
3. 数据本地闭环：不联网、不上传、不把库文件发给第三方服务。
4. 输出语言中文；错误信息必须说人话并给出下一步建议。

工作流程（五步）

第 1 步 · 接需求，定库与表

用户提供数据文件（或已在磁盘上的 .db）+ 想问的问题。确认：

• 库文件路径（建议 数据/业务.db，与源数据同目录）；
• 已有库则先 --tables 看家底，绝不重复导入已存在的表（表已存在时必须先问用户"覆盖重建还是换表名"）。

第 2 步 · 导入（scripts/import_data.py）

python3 scripts/import_data.py 订单.csv --db 业务.db                # CSV/TSV/JSON：表名=文件名
python3 scripts/import_data.py 员工.xlsx --db 业务.db                # xlsx：每个 sheet 一张表
python3 scripts/import_data.py 员工.xlsx --db 业务.db --sheet 员工表 --table 员工
python3 scripts/import_data.py 订单.csv --db 业务.db --dry-run      # 先看建表计划

数据清洗（1.0.6 新增，可选）：导入前若数据脏（重复、空值、列名含空格、金额是文本），先用 scripts/clean_data.py 做确定性清洗再入库：

python3 scripts/clean_data.py --csv 原始.csv --rename --fill-empty --numeric   # 清洗列名/空值/类型
python3 scripts/clean_data.py --csv 原始.csv --json                             # 看清洗报告(去重/空值/类型)

输出清洗报告（去重条数、空值填充、列名清洗、类型规范）。清洗只改格式不造数据——缺失值填 "N/A" 或 0（仅数值列），不编造内容；清洗后再 import_data 入库。

导入后必须核验：query.py --tables 行数与源文件一致；--schema 类型符合预期（金额列应为 REAL/INTEGER，变 TEXT 说明源数据有脏值）。

细节与坑（xlsx sharedStrings/日期序列号 1900 假闰年/合并单元格/.xls 转换指引/性能舒适区）见 references/01-create-import.md。

第 3 步 · 查询（scripts/query.py，只读）

python3 scripts/query.py --db 业务.db --tables                      # 表清单
python3 scripts/query.py --db 业务.db --schema 员工表                 # 先看结构再写 SQL
python3 scripts/query.py --db 业务.db --sql "SELECT ..." [--format table|csv|json|markdown]
python3 scripts/query.py --db 业务.db --sql "SELECT * FROM orders WHERE 客户名称=:c" --param c=杭州云图科技

生成 SQL 的铁律：先 --schema 再写 SQL（禁止猜列名）；大表禁裸 SELECT *（默认 LIMIT 10）；中文标识符加双引号；值一律参数化绑定。办公场景模板（JOIN/聚合/窗口函数/时间处理）见 references/02-query.md。

第 4 步 · 导出

python3 scripts/query.py --db 业务.db --sql "..." --format csv --csv-out 结果.csv   # Excel 直开不乱码(utf-8-sig)
python3 scripts/query.py --db 业务.db --sql "..." --format json                     # 程序用
python3 scripts/query.py --db 业务.db --sql "..." --format markdown                  # 贴周报

第 5 步 · 管理与防护（scripts/db_manage.py）

python3 scripts/db_manage.py --db 业务.db --index orders --index-cols 客户名称,订单日期  # 高频列建索引
python3 scripts/db_manage.py --db 业务.db --backup 备份.db                              # 热备(Connection.backup)
python3 scripts/db_manage.py --db 业务.db --backup 备份.sql                              # SQL 文本 dump
python3 scripts/db_manage.py --db 业务.db --check                                       # integrity_check 体检
python3 scripts/db_manage.py --db 业务.db --truncate-table 临时表 --yes                  # 清空（自动先备份）
python3 scripts/db_manage.py --db 业务.db --drop-table 废表 --yes                      # 删表（自动先备份）
python3 scripts/db_manage.py --db 业务.db --restore 备份.db --yes                       # 恢复（自动备份当前库）

删表/清空/恢复前，Agent 必须先展示影响并取得用户确认。备份双路线选择、恢复语义、索引最左前缀原则见 references/03-export-backup.md。

资源清单

典型问答（Agent 话术参考）

• "把这份订单 Excel 做成能查的数据库" → 第 2 步导入 + 核验 + 告知表清单，并给 3 条示例查询。
• "上季度杭州云图买了多少" → 已有库直接第 3 步：先 --schema 再写聚合 SQL，表格输出。
• "导出来发同事" → 第 4 步 --format csv --csv-out，提示 Excel 双击可开。
• "这张临时表没用了，删掉" → 第 5 步：先展示"表 xx，当前 N 行，删前自动备份到 xxx"，用户确认后 --drop-table --yes。
• "数据好像坏了" → --check 体检；异常则给出最近备份的恢复方案。

红线（禁止事项）

• 禁止用可写连接执行用户查询（绕过只读保护）。
• 禁止跳过"展示影响 + 确认 + 自动备份"直接删表/清空/恢复。
• 禁止把用户数据传出本机（上传、外发、嵌入远程服务）。
• 禁止替用户"顺手"删改数据；一切写操作显式征得同意。
• 超出舒适区（单表>500 万行或库>2GB 的重度分析、多人并发写）时，如实建议升级 DuckDB/PostgreSQL，不硬扛。

免责声明

• 本技能处理的数据全程留在本机，不构成数据托管；请用户自行遵守所在机构的数据安全规定（尤其涉密、涉客户信息的数据）。
• SQLite 官方 guarantee：integrity_check 通过只代表文件结构完好，不代表业务内容正确；重要结论请以源数据交叉核对。
• 自动备份默认存放在库文件同目录，请勿把含敏感数据的库与备份放在公共同步盘而不设访问控制。
• xlsx 解析针对标准 OOXML 实现；个别第三方工具导出的畸形文件可能解析不完整，遇到时以 --dry-run 与行数核验兜底，如实告知用户差异。

NOTICE

方法论与类型推断思路借鉴 simonw/sqlite-utils 与 datasette（均为 Apache-2.0），仅借鉴设计思想、脚本为原创实现，详见 NOTICE.md。

输入输出示例

输入（用户一句话 + 一份 Excel）：「把这份销售订单表做成本地可查的数据库，帮我查一下上季度（7-9 月）杭州云图科技买走了多少货。」

Agent 动作：
1. import_data.py 订单.xlsx --db 业务.db 导入 + --schema 核验列名/类型
2. query.py --db 业务.db --sql "SELECT 客户名称, SUM(金额) FROM 订单 WHERE 客户名称=:c AND 订单日期 BETWEEN :a AND :b" --param c=杭州云图科技 --param a=2026-07-01 --param b=2026-09-30

输出：一行中文结果（如「杭州云图科技 2026 Q3 合计 ¥1,234,500」），同时告知已建的库文件路径与表清单，并给 2-3 条后续可用的示例查询。

常见问题

• Q1：表已经存在，重复导入会怎样？ 不会自动覆盖。脚本检测到同名表会停下，Agent 先问你「覆盖重建还是换表名」，再走对应动作，绝不悄悄覆盖。
• Q2：会不会把数据发到网上？ 不会。全流程本地 SQLite，零联网、零上传，数据不出设备；重要结论请自行遵守机构数据安全规定。
• Q3：Excel 有几百 MB、几百万行，跑得动吗？ 单表 500 万行 / 库 2GB 以内是本技能舒适区；超出或需要多人并发写，如实建议升级 DuckDB / PostgreSQL，不硬扛。
• Q4：删了表/清了数据能找回吗？ 每次写操作（删表/清空/恢复）前自动做时间戳备份，恢复到最近可用备份即可；备份默认在库同目录。