wechat-cli开发者指南项目架构、Click命令设计与npm跨平台二进制分发深度剖析【免费下载链接】wechat-cliA CLI tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration.项目地址: https://gitcode.com/gh_mirrors/wech/wechat-cliwechat-cli是一款查询本地微信数据的命令行工具可从终端查询微信聊天记录、联系人、会话、收藏与未读消息并默认输出 JSON专为大模型LLMAgent 集成而设计。本文带你从源码结构、Click 命令设计到 npm 跨平台二进制分发完整理解这个项目的工程化思路。 wechat-cli 核心能力一览wechat-cli 提供 11 个命令覆盖日常微信数据查询的主要场景命令用途sessions最近会话列表history指定聊天的消息记录支持时间范围、分页search全局或指定群的消息关键词搜索contacts/members联系人查询 / 群成员列表stats聊天统计活跃 Top10、消息类型分布export导出为 Markdown 或纯文本favorites/unread/new-messages收藏、未读、增量新消息init首次初始化自动检测数据目录、提取密钥它的技术亮点在于完全本地化微信数据以 SQLCipher 加密存储在本机 SQLite 数据库中wechat-cli 通过init从微信进程内存中提取密钥再按需进行页级 AES-256-CBC 实时解密与缓存数据全程不出本机。️ 项目架构清晰分层的目录设计项目源码组织得非常规整整体可分为命令层、核心层、平台适配层三层命令层wechat_cli/commands/每个命令一个文件[wechat_cli/commands/](https://link.gitcode.com/i/8376917fd93bb9d99880d04a1874e299)下共有 11 个命令模块sessions.py、history.py、search.py、init.py等。命令文件只负责参数解析、调用核心逻辑和输出格式化非常薄。核心层wechat_cli/core/[wechat_cli/core/](https://link.gitcode.com/i/b36ccd5623faf096c0da76ca06cc3b0f)是业务逻辑所在config.py从~/.wechat-cli/加载配置并按操作系统自动选择微信进程名Linux 为wechat、macOS 为WeChat、Windows 为Weixin.execontext.pyAppContext单例上下文每次 CLI 调用初始化一次被所有命令共享crypto.py/db_cache.pySQLCipher 实时解密与数据库缓存messages.py消息收集、时间范围解析、分页校验其中AppContext是全项目的中枢它在构造时加载配置、校验密钥文件是否存在不存在就提示先运行wechat-cli init、建立DBCache并通过atexit注册清理逻辑。任何命令都通过ctx.obj拿到同一个实例避免了重复加载。平台适配层wechat_cli/keys/密钥提取与系统强相关因此按平台拆分为三个扫描器scanner_linux.py读取/proc/pid/mem需要 root 权限scanner_macos.py扫描 macOS 进程内存scanner_windows.py读取Weixin.exe进程内存新增平台的密钥提取逻辑时只需在[wechat_cli/keys/common.py](https://link.gitcode.com/i/875d6a43010765938f0c5cdab25d188c)的调度下补充对应扫描器即可互不干扰。⚡ Click 命令设计一行注册、装饰器驱动wechat-cli 选用Click构建 CLI命令注册集中在入口文件 wechat_cli/main.py体现了典型的 Click 风格1. 用click.group()构建命令组顶层入口是一个click.group()并挂上了--config全局选项支持环境变量WECHAT_CLI_CONFIG覆盖。这里有一个精妙的细节init命令不需要 AppContext因为它的职责恰恰是创建配置与密钥所以入口在invoked_subcommand in (init, version)时直接返回跳过上下文初始化。2. 每个子命令 装饰器 纯函数以 wechat_cli/commands/history.py 为例history命令完全由装饰器声明参数click.argument(chat_name)声明位置参数click.option(--limit, default50)、click.option(--type, typeclick.Choice(MSG_TYPE_NAMES))声明可选参数函数体只做校验 → 调用核心层 → 输出三件事。这种参数声明与业务逻辑分离的写法带来两个好处--help文档自动且完整命令 docstring 里还内嵌了示例新手零成本上手新增命令只需新建文件 cli.add_command()一行注册3. JSON / Text 双输出AI-First 设计所有命令默认输出JSON--format text切换为人类可读文本。统一的格式化逻辑收敛在 wechat_cli/output/formatter.py 的output()函数中。这正是 wechat-cli 能被 Claude Code 等 AI Agent 直接当工具调用的关键——结构化输出天然适合大模型解析。 npm 跨平台二进制分发主包 平台子包模式wechat-cli 是 Python 项目却能让用户npm install -g一条命令装完、无需安装 Python这背后的分发架构非常值得借鉴。1. 打包PyInstaller 冻结成单文件二进制Python 侧通过 pyproject.toml 声明依赖click、pycryptodome、zstandard并用 PyInstaller 将 entry.py 冻结为独立可执行文件entry.py单独存在是为了规避相对导入问题。各平台的二进制分别放入bin/目录。2. 发布一个主包 五个平台子包npm 侧采用 npm 官方的可选依赖optionalDependencies平台包模式npm/wechat-cli/package.json主包只包含启动脚本通过optionalDependencies声明canghe_ai/wechat-cli-darwin-arm64等平台包npm/platforms/每个平台一个独立包如 npm/platforms/darwin-arm64/package.json 通过os和cpu字段声明自己只适用于 macOS Apple Siliconnpm 在任意机器上安装时只会自动拉取当前系统匹配的那个平台子包其他平台的包会被优雅跳过——这就是为什么主包可以只发 darwin-arm64 也能在别的平台安全安装。3. postinstall 钩子定位并授权二进制安装钩子在npm/wechat-cli/install.js中实现脚本根据process.platform process.arch拼出平台键如darwin-arm64用require.resolve找到对应子包里的bin/wechat-cli可执行文件并为非 Windows 环境补上chmod 0o755执行权限。若平台包未安装如使用了--no-optional则打印修复提示而不是报错崩溃容错处理非常克制。 开发者快速上手三步本地跑起来第一步克隆仓库git clone https://gitcode.com/gh_mirrors/wech/wechat-cli cd wechat-cli第二步源码方式安装要求 Python ≥ 3.10pip install -e .第三步初始化后开始查询。确保微信正在运行然后sudo wechat-cli init # macOS/Linux wechat-cli init # Windowsinit的完整流程在 wechat_cli/commands/init.py 中检测数据目录 → 提取密钥写入~/.wechat-cli/all_keys.json→ 生成config.json。若本机登录了多个微信账号会交互式让你选择账号也可用--db-dir手动指定数据目录--force重新提取密钥之后即可体验全部命令wechat-cli sessions --limit 10 wechat-cli history 张三 --limit 20 --format text wechat-cli search deadline --chat 团队群更多命令细节与 macOS 权限配置Full Disk Access、task_for_pid failed自动重签名等可参考 README.md 与 README_CN.md。 小结wechat-cli 是一个小而完整的工程化样本架构上commands / core / keys 三层分离AppContext单例贯穿全局平台差异被隔离在密钥扫描器中命令设计上Click 装饰器声明参数、docstring 即文档、JSON 默认输出面向 AI Agent分发上PyInstaller 冻结二进制 npm 主包/平台子包 postinstall 钩子实现零 Python 依赖、一行命令安装如果你正在做一个需要跨平台分发的 CLI 工具或想为 AI Agent 打造可查询本地数据的工具链这个项目的源码都非常值得借鉴。【免费下载链接】wechat-cliA CLI tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration.项目地址: https://gitcode.com/gh_mirrors/wech/wechat-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考