今天很高兴向大家介绍我刚刚开源的一个新项目 —— wcdb-cli。
这是一个基于 C++ 和 WCDB 的命令行工具，专门用于读取加密的 WCDB 数据库，并且是专为 AI 调用设计的。
GitHub 地址: https://github.com/jadedrip/wcdb-cli
什么是 WCDB？
在介绍工具之前，先简单说一下 WCDB。
WCDB 是由腾讯微信团队开发并开源的跨平台移动数据库框架，基于 SQLite 和 SQLCipher 构建。目前在 GitHub 上拥有超过 11.6k Star，微信 PC 版就使用了 WCDB 作为数据库。
- GitHub 仓库: https://github.com/Tencent/wcdb
- 官方文档: WCDB - 全平台·多语言·高效易用 移动数据库框架
为什么做这个工具？
在使用微信相关数据进行开发和分析时，我们经常需要读取 WCDB 加密数据库中的数据。但是：
- WCDB 使用 SQLCipher 加密：普通 SQLite 工具无法直接打开
- WCDB 支持数据压缩（ZSTD）：即使解密后，压缩字段也需要特殊处理
- 缺乏好用的命令行工具：现有方案要么太复杂，要么不够灵活
所以就有了 wcdb-cli —— 一个简单、高效、专为 AI 调用优化的命令行工具。
核心功能特性
- 支持 SQLCipher 加密数据库读取
- WCDB 压缩数据自动解压（ZSTD）
- 列出数据库中所有表
- 查看表结构（字段名、类型、约束）
- 查询表数据（支持分页、排序、指定字段）
- 支持 WHERE 条件查询
- 支持基于字段排序（正序/倒序）
- YAML 格式输出（便于 AI 解析）
- 支持
--format参数指定输出格式（yaml/json） - 支持从环境变量或命令行参数获取密钥
- 支持解密导出为普通 SQLite 数据库
快速上手
1. 列出所有表
wcdb-cli -d path/to/database.db -k <hex_key> -l
2. 查看表结构
wcdb-cli -d path/to/database.db -k <hex_key> -dt Users
3. 查询表数据
# 查询所有数据
wcdb-cli -d path/to/database.db -k <hex_key> -qt Users
# 分页查询
wcdb-cli -d path/to/database.db -k <hex_key> -qt Users -lim 10 -off 0
# 条件查询
wcdb-cli -d path/to/database.db -k <hex_key> -qt Users -w "unread_count > 0"
# 组合查询（条件+排序+分页）
wcdb-cli -d path/to/database.db -k <hex_key> -qt Users -w "type = 1" -s username -so asc -lim 10 -off 0
4. 获取数据库信息
wcdb-cli -d path/to/database.db -k <hex_key> -i
5. 解密导出为普通 SQLite 数据库
wcdb-cli -d path/to/database.db -k <hex_key> -de -o output.db
输出示例
YAML 格式（默认）
status: success
data:
tables:
- Users
- Orders
- Products
JSON 格式
{
"status": "success",
"data": {
"tables": ["Users", "Orders", "Products"]
}
}
AI 调用示例
由于输出格式为 YAML/JSON，非常适合被 AI 程序解析调用：
import subprocess
import json
def query_wcdb(db_path, key, table_name, limit=10, format='yaml'):
result = subprocess.run(
["wcdb-cli", "--db", db_path, "--key", key, "--format", format,
"--query-table", table_name, "--limit", str(limit)],
capture_output=True,
text=True
)
if result.returncode == 0:
if format == 'json':
return json.loads(result.stdout)
else:
return result.stdout
else:
return {"status": "error", "message": result.stderr}
# 使用示例
data = query_wcdb("example.db", "your_key_here", "Users")
print(data)
技术栈与依赖
- 构建工具: xmake (3.2.0+)
- 编程语言: C++17 (MSVC 2022+)
- 核心库: WCDB 2.1.16
- 第三方库: spdlog、fmt、zlib、sqlite3（通过 vcpkg 管理）
编译方式
# 初始化构建配置
xmake f
# 编译项目
xmake build
编译产物位于 build/windows/x64/release/wcdb-cli.exe
详细的依赖配置和 WCDB 库构建步骤请参考项目 README。
项目结构
wcdb-cli/
├── README.md # 项目文档
├── LICENSE # MIT 许可证
├── xmake.lua # xmake 构建配置
├── doc/
│ ├── skills.md # CLI 工具操作技能文档
│ ├── auto_compression.md # WCDB 自动压缩支持文档
│ ├── database_readme.md # WCDB 数据库读取开发文档
│ └── sorting_guide.md # WCDB 排序方法使用指南
├── src/
│ ├── main.cpp # CLI 主程序
│ ├── sql_expression_parser.h/cpp # SQL 表达式解析器
│ └── wcdb_wrapper.h/cpp # WCDB 封装类
└── test/
├── test_decrypt.py # 解密验证脚本
├── test_query.py # 查询测试脚本
└── test_wcdb_decode.py # 解码测试脚本
开源协议
本项目采用 MIT License 开源协议，欢迎大家一起使用和贡献！
总结
wcdb-cli 是一个专注于解决「加密 WCDB 数据库读取」这一痛点的小而美的命令行工具。它的设计理念是：
- 简单易用：清晰的命令行接口，丰富的选项
- AI 友好：YAML/JSON 输出格式，便于程序化处理
- 功能实用：覆盖了列表、结构、查询、导出等核心场景
如果你也在使用 WCDB 或需要处理微信相关的加密数据库，欢迎试用和反馈！
