者指南：項目架構(gòu)、Click命令設(shè)計與npm跨平臺二進制分發(fā)深度剖析)
wechat-cli開發(fā)者指南項目架構(gòu)、Click命令設(shè)計與npm跨平臺二進制分發(fā)深度剖析【免費下載鏈接】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是一款查詢本地微信數(shù)據(jù)的命令行工具可從終端查詢微信聊天記錄、聯(lián)系人、會話、收藏與未讀消息并默認輸出 JSON專為大模型LLMAgent 集成而設(shè)計。本文帶你從源碼結(jié)構(gòu)、Click 命令設(shè)計到 npm 跨平臺二進制分發(fā)完整理解這個項目的工程化思路。 wechat-cli 核心能力一覽wechat-cli 提供 11 個命令覆蓋日常微信數(shù)據(jù)查詢的主要場景命令用途sessions最近會話列表history指定聊天的消息記錄支持時間范圍、分頁search全局或指定群的消息關(guān)鍵詞搜索contacts/members聯(lián)系人查詢 / 群成員列表stats聊天統(tǒng)計活躍 Top10、消息類型分布export導(dǎo)出為 Markdown 或純文本favorites/unread/new-messages收藏、未讀、增量新消息init首次初始化自動檢測數(shù)據(jù)目錄、提取密鑰它的技術(shù)亮點在于完全本地化微信數(shù)據(jù)以 SQLCipher 加密存儲在本機 SQLite 數(shù)據(jù)庫中wechat-cli 通過init從微信進程內(nèi)存中提取密鑰再按需進行頁級 AES-256-CBC 實時解密與緩存數(shù)據(jù)全程不出本機。? 項目架構(gòu)清晰分層的目錄設(shè)計項目源碼組織得非常規(guī)整整體可分為命令層、核心層、平臺適配層三層命令層wechat_cli/commands/每個命令一個文件[wechat_cli/commands/](https://link.gitcode.com/i/8376917fd93bb9d99880d04a1874e299)下共有 11 個命令模塊sessions.py、history.py、search.py、init.py等。命令文件只負責(zé)參數(shù)解析、調(diào)用核心邏輯和輸出格式化非常薄。核心層wechat_cli/core/[wechat_cli/core/](https://link.gitcode.com/i/b36ccd5623faf096c0da76ca06cc3b0f)是業(yè)務(wù)邏輯所在config.py從~/.wechat-cli/加載配置并按操作系統(tǒng)自動選擇微信進程名Linux 為wechat、macOS 為WeChat、Windows 為Weixin.execontext.pyAppContext單例上下文每次 CLI 調(diào)用初始化一次被所有命令共享crypto.py/db_cache.pySQLCipher 實時解密與數(shù)據(jù)庫緩存messages.py消息收集、時間范圍解析、分頁校驗其中AppContext是全項目的中樞它在構(gòu)造時加載配置、校驗密鑰文件是否存在不存在就提示先運行wechat-cli init、建立DBCache并通過atexit注冊清理邏輯。任何命令都通過ctx.obj拿到同一個實例避免了重復(fù)加載。平臺適配層wechat_cli/keys/密鑰提取與系統(tǒng)強相關(guān)因此按平臺拆分為三個掃描器scanner_linux.py讀取/proc/pid/mem需要 root 權(quán)限scanner_macos.py掃描 macOS 進程內(nèi)存scanner_windows.py讀取Weixin.exe進程內(nèi)存新增平臺的密鑰提取邏輯時只需在[wechat_cli/keys/common.py](https://link.gitcode.com/i/875d6a43010765938f0c5cdab25d188c)的調(diào)度下補充對應(yīng)掃描器即可互不干擾。? Click 命令設(shè)計一行注冊、裝飾器驅(qū)動wechat-cli 選用Click構(gòu)建 CLI命令注冊集中在入口文件 wechat_cli/main.py體現(xiàn)了典型的 Click 風(fēng)格1. 用click.group()構(gòu)建命令組頂層入口是一個click.group()并掛上了--config全局選項支持環(huán)境變量WECHAT_CLI_CONFIG覆蓋。這里有一個精妙的細節(jié)init命令不需要 AppContext因為它的職責(zé)恰恰是創(chuàng)建配置與密鑰所以入口在invoked_subcommand in (init, version)時直接返回跳過上下文初始化。2. 每個子命令 裝飾器 純函數(shù)以 wechat_cli/commands/history.py 為例history命令完全由裝飾器聲明參數(shù)click.argument(chat_name)聲明位置參數(shù)click.option(--limit, default50)、click.option(--type, typeclick.Choice(MSG_TYPE_NAMES))聲明可選參數(shù)函數(shù)體只做校驗 → 調(diào)用核心層 → 輸出三件事。這種參數(shù)聲明與業(yè)務(wù)邏輯分離的寫法帶來兩個好處--help文檔自動且完整命令 docstring 里還內(nèi)嵌了示例新手零成本上手新增命令只需新建文件 cli.add_command()一行注冊3. JSON / Text 雙輸出AI-First 設(shè)計所有命令默認輸出JSON--format text切換為人類可讀文本。統(tǒng)一的格式化邏輯收斂在 wechat_cli/output/formatter.py 的output()函數(shù)中。這正是 wechat-cli 能被 Claude Code 等 AI Agent 直接當(dāng)工具調(diào)用的關(guān)鍵——結(jié)構(gòu)化輸出天然適合大模型解析。 npm 跨平臺二進制分發(fā)主包 平臺子包模式wechat-cli 是 Python 項目卻能讓用戶npm install -g一條命令裝完、無需安裝 Python這背后的分發(fā)架構(gòu)非常值得借鑒。1. 打包PyInstaller 凍結(jié)成單文件二進制Python 側(cè)通過 pyproject.toml 聲明依賴click、pycryptodome、zstandard并用 PyInstaller 將 entry.py 凍結(jié)為獨立可執(zhí)行文件entry.py單獨存在是為了規(guī)避相對導(dǎo)入問題。各平臺的二進制分別放入bin/目錄。2. 發(fā)布一個主包 五個平臺子包npm 側(cè)采用 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 在任意機器上安裝時只會自動拉取當(dāng)前系統(tǒng)匹配的那個平臺子包其他平臺的包會被優(yōu)雅跳過——這就是為什么主包可以只發(fā) darwin-arm64 也能在別的平臺安全安裝。3. postinstall 鉤子定位并授權(quán)二進制安裝鉤子在npm/wechat-cli/install.js中實現(xiàn)腳本根據(jù)process.platform process.arch拼出平臺鍵如darwin-arm64用require.resolve找到對應(yīng)子包里的bin/wechat-cli可執(zhí)行文件并為非 Windows 環(huán)境補上chmod 0o755執(zhí)行權(quán)限。若平臺包未安裝如使用了--no-optional則打印修復(fù)提示而不是報錯崩潰容錯處理非常克制。 開發(fā)者快速上手三步本地跑起來第一步克隆倉庫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 中檢測數(shù)據(jù)目錄 → 提取密鑰寫入~/.wechat-cli/all_keys.json→ 生成config.json。若本機登錄了多個微信賬號會交互式讓你選擇賬號也可用--db-dir手動指定數(shù)據(jù)目錄--force重新提取密鑰之后即可體驗全部命令wechat-cli sessions --limit 10 wechat-cli history 張三 --limit 20 --format text wechat-cli search deadline --chat 團隊群更多命令細節(jié)與 macOS 權(quán)限配置Full Disk Access、task_for_pid failed自動重簽名等可參考 README.md 與 README_CN.md。 小結(jié)wechat-cli 是一個小而完整的工程化樣本架構(gòu)上commands / core / keys 三層分離AppContext單例貫穿全局平臺差異被隔離在密鑰掃描器中命令設(shè)計上Click 裝飾器聲明參數(shù)、docstring 即文檔、JSON 默認輸出面向 AI Agent分發(fā)上PyInstaller 凍結(jié)二進制 npm 主包/平臺子包 postinstall 鉤子實現(xiàn)零 Python 依賴、一行命令安裝如果你正在做一個需要跨平臺分發(fā)的 CLI 工具或想為 AI Agent 打造可查詢本地數(shù)據(jù)的工具鏈這個項目的源碼都非常值得借鑒?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 wechat-cli開發(fā)者指南：項目架構(gòu)、Click命令設(shè)計與npm跨平臺二進制分發(fā)深度剖析
wechat-cli開發(fā)者指南項目架構(gòu)、Click命令設(shè)計與npm跨平臺二進制分發(fā)深度剖析【免費下載鏈接】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是一款查詢本地微信數(shù)據(jù)的命令行工具可從終端查詢微信聊天記錄、聯(lián)系人、會話、收藏與未讀消息并默認輸出 JSON專為大模型LLMAgent 集成而設(shè)計。本文帶你從源碼結(jié)構(gòu)、Click 命令設(shè)計到 npm 跨平臺二進制分發(fā)完整理解這個項目的工程化思路。 wechat-cli 核心能力一覽wechat-cli 提供 11 個命令覆蓋日常微信數(shù)據(jù)查詢的主要場景命令用途sessions最近會話列表history指定聊天的消息記錄支持時間范圍、分頁search全局或指定群的消息關(guān)鍵詞搜索contacts/members聯(lián)系人查詢 / 群成員列表stats聊天統(tǒng)計活躍 Top10、消息類型分布export導(dǎo)出為 Markdown 或純文本favorites/unread/new-messages收藏、未讀、增量新消息init首次初始化自動檢測數(shù)據(jù)目錄、提取密鑰它的技術(shù)亮點在于完全本地化微信數(shù)據(jù)以 SQLCipher 加密存儲在本機 SQLite 數(shù)據(jù)庫中wechat-cli 通過init從微信進程內(nèi)存中提取密鑰再按需進行頁級 AES-256-CBC 實時解密與緩存數(shù)據(jù)全程不出本機。? 項目架構(gòu)清晰分層的目錄設(shè)計項目源碼組織得非常規(guī)整整體可分為命令層、核心層、平臺適配層三層命令層wechat_cli/commands/每個命令一個文件[wechat_cli/commands/](https://link.gitcode.com/i/8376917fd93bb9d99880d04a1874e299)下共有 11 個命令模塊sessions.py、history.py、search.py、init.py等。命令文件只負責(zé)參數(shù)解析、調(diào)用核心邏輯和輸出格式化非常薄。核心層wechat_cli/core/[wechat_cli/core/](https://link.gitcode.com/i/b36ccd5623faf096c0da76ca06cc3b0f)是業(yè)務(wù)邏輯所在config.py從~/.wechat-cli/加載配置并按操作系統(tǒng)自動選擇微信進程名Linux 為wechat、macOS 為WeChat、Windows 為Weixin.execontext.pyAppContext單例上下文每次 CLI 調(diào)用初始化一次被所有命令共享crypto.py/db_cache.pySQLCipher 實時解密與數(shù)據(jù)庫緩存messages.py消息收集、時間范圍解析、分頁校驗其中AppContext是全項目的中樞它在構(gòu)造時加載配置、校驗密鑰文件是否存在不存在就提示先運行wechat-cli init、建立DBCache并通過atexit注冊清理邏輯。任何命令都通過ctx.obj拿到同一個實例避免了重復(fù)加載。平臺適配層wechat_cli/keys/密鑰提取與系統(tǒng)強相關(guān)因此按平臺拆分為三個掃描器scanner_linux.py讀取/proc/pid/mem需要 root 權(quán)限scanner_macos.py掃描 macOS 進程內(nèi)存scanner_windows.py讀取Weixin.exe進程內(nèi)存新增平臺的密鑰提取邏輯時只需在[wechat_cli/keys/common.py](https://link.gitcode.com/i/875d6a43010765938f0c5cdab25d188c)的調(diào)度下補充對應(yīng)掃描器即可互不干擾。? Click 命令設(shè)計一行注冊、裝飾器驅(qū)動wechat-cli 選用Click構(gòu)建 CLI命令注冊集中在入口文件 wechat_cli/main.py體現(xiàn)了典型的 Click 風(fēng)格1. 用click.group()構(gòu)建命令組頂層入口是一個click.group()并掛上了--config全局選項支持環(huán)境變量WECHAT_CLI_CONFIG覆蓋。這里有一個精妙的細節(jié)init命令不需要 AppContext因為它的職責(zé)恰恰是創(chuàng)建配置與密鑰所以入口在invoked_subcommand in (init, version)時直接返回跳過上下文初始化。2. 每個子命令 裝飾器 純函數(shù)以 wechat_cli/commands/history.py 為例history命令完全由裝飾器聲明參數(shù)click.argument(chat_name)聲明位置參數(shù)click.option(--limit, default50)、click.option(--type, typeclick.Choice(MSG_TYPE_NAMES))聲明可選參數(shù)函數(shù)體只做校驗 → 調(diào)用核心層 → 輸出三件事。這種參數(shù)聲明與業(yè)務(wù)邏輯分離的寫法帶來兩個好處--help文檔自動且完整命令 docstring 里還內(nèi)嵌了示例新手零成本上手新增命令只需新建文件 cli.add_command()一行注冊3. JSON / Text 雙輸出AI-First 設(shè)計所有命令默認輸出JSON--format text切換為人類可讀文本。統(tǒng)一的格式化邏輯收斂在 wechat_cli/output/formatter.py 的output()函數(shù)中。這正是 wechat-cli 能被 Claude Code 等 AI Agent 直接當(dāng)工具調(diào)用的關(guān)鍵——結(jié)構(gòu)化輸出天然適合大模型解析。 npm 跨平臺二進制分發(fā)主包 平臺子包模式wechat-cli 是 Python 項目卻能讓用戶npm install -g一條命令裝完、無需安裝 Python這背后的分發(fā)架構(gòu)非常值得借鑒。1. 打包PyInstaller 凍結(jié)成單文件二進制Python 側(cè)通過 pyproject.toml 聲明依賴click、pycryptodome、zstandard并用 PyInstaller 將 entry.py 凍結(jié)為獨立可執(zhí)行文件entry.py單獨存在是為了規(guī)避相對導(dǎo)入問題。各平臺的二進制分別放入bin/目錄。2. 發(fā)布一個主包 五個平臺子包npm 側(cè)采用 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 在任意機器上安裝時只會自動拉取當(dāng)前系統(tǒng)匹配的那個平臺子包其他平臺的包會被優(yōu)雅跳過——這就是為什么主包可以只發(fā) darwin-arm64 也能在別的平臺安全安裝。3. postinstall 鉤子定位并授權(quán)二進制安裝鉤子在npm/wechat-cli/install.js中實現(xiàn)腳本根據(jù)process.platform process.arch拼出平臺鍵如darwin-arm64用require.resolve找到對應(yīng)子包里的bin/wechat-cli可執(zhí)行文件并為非 Windows 環(huán)境補上chmod 0o755執(zhí)行權(quán)限。若平臺包未安裝如使用了--no-optional則打印修復(fù)提示而不是報錯崩潰容錯處理非常克制。 開發(fā)者快速上手三步本地跑起來第一步克隆倉庫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 中檢測數(shù)據(jù)目錄 → 提取密鑰寫入~/.wechat-cli/all_keys.json→ 生成config.json。若本機登錄了多個微信賬號會交互式讓你選擇賬號也可用--db-dir手動指定數(shù)據(jù)目錄--force重新提取密鑰之后即可體驗全部命令wechat-cli sessions --limit 10 wechat-cli history 張三 --limit 20 --format text wechat-cli search deadline --chat 團隊群更多命令細節(jié)與 macOS 權(quán)限配置Full Disk Access、task_for_pid failed自動重簽名等可參考 README.md 與 README_CN.md。 小結(jié)wechat-cli 是一個小而完整的工程化樣本架構(gòu)上commands / core / keys 三層分離AppContext單例貫穿全局平臺差異被隔離在密鑰掃描器中命令設(shè)計上Click 裝飾器聲明參數(shù)、docstring 即文檔、JSON 默認輸出面向 AI Agent分發(fā)上PyInstaller 凍結(jié)二進制 npm 主包/平臺子包 postinstall 鉤子實現(xiàn)零 Python 依賴、一行命令安裝如果你正在做一個需要跨平臺分發(fā)的 CLI 工具或想為 AI Agent 打造可查詢本地數(shù)據(jù)的工具鏈這個項目的源碼都非常值得借鑒?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考