IM-MCP 智能體運維與資料生命週期管理指南
本技能指導智能體在 Windows 及 macOS 環境下管理 im-mcp 工具集（包含微信 MCP 與釘釘 MCP），涵蓋前置環境檢查、離線資料庫初始化與解密、聊天資料檢索以及任務完成後的安全清理。
1. 核心定位與運行策略 (Core Principles & Execution Strategy)
1.1 運行方式優先原則與執行策略
智能體在引導或協助使用者部署時，應遵循以下運行策略：
- 優先持久化安裝：若在 Claude Desktop、Cursor 等桌面客戶端或支援持久化工具的環境中，推薦使用
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"； - 沙箱/受限環境降級：若當前 AI 客戶端環境（如 Pi 沙箱環境）攔截了全域工具安裝（提示
Blocked ... use uvx），應直接遵循該環境安全策略，使用uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]"方式即席執行相關命令； - 國內網路映像備選（Gitee 源）：若使用者處於國內網路環境或存取 GitHub 受限/較慢，可直接將上述 Git 地址替換為 Gitee 映像倉庫：
- 持久化：
uv tool install "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]" - 即席執行：
uvx --from "git+https://gitee.com/ws4m/im-mcp.git[all]" <command>
- 持久化：
- 禁止私自編寫協定測試程式碼：安裝並運行初始化（
wechat-init與dingtalk-init）後，嚴禁私自編寫腳本或程式碼模擬底層 JSON-RPC/stdio 協定測試，必須直接交付使用者並提供客戶端啟用引導； - 宿主環境感知與交付引導：智能體應根據當前所運行的客戶端環境（如 Pi、Claude Code/Desktop、Cursor、Cline 等），自主判斷並向使用者提示具體的 Skill 與 MCP 啟用步驟（如告知輸入
/reload、重新啟動用戶端或在側邊欄開啟信任），並直接給出 1~2 個日常對話的使用範例。
1.2 命令矩陣與權限一覽
# 方式 A：全域持久化隔離安裝 CLI 工具鏈（推薦優先選擇）
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"
命令矩陣如下：
| 命令 | 全域安裝後呼叫方式 | 沙箱/受限環境 uvx 即席運行方式 | 適用場景 | 權限要求 | 關鍵產物 / 路徑 |
|---|---|---|---|---|---|
wechat-init | wechat-init | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-init | 提取微信 DBKey 並離線解密為 SQLite 資料庫 | Windows 需管理員權限 (掃記憶體)；macOS 支援 --passphrase 或配置持久化 | ~/.wechat_mcp/decrypted/, ~/.wechat_mcp/app.db |
dingtalk-init | dingtalk-init | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-init | 離線提取釘釘金鑰、解密 DB 並合併 WAL 事務 | 普通使用者權限 | ~/.dingtalk_mcp/decrypted/dingtalk.db |
im-clean | im-clean | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" im-clean | 一鍵安全清理所有匯出的明文資料、金鑰與快取 | 普通/管理員權限 | 清理上述兩者的解密庫及全域資料目錄 |
wechat-mcp | wechat-mcp | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-mcp | 微信 FastMCP 標準服務端入口 | 普通使用者權限 | stdio 介面 |
dingtalk-mcp | dingtalk-mcp | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-mcp | 釘釘 FastMCP 標準服務端入口 | 普通使用者權限 | stdio 介面 |
2. 智能體操作工作流 (Lifecycle Workflows)
2.1 任務開始前：自動初始化資料庫 (Pre-flight Initialization)
當使用者要求「分析最近微信/釘釘溝通」、「生成週報」、「查某某群聊檔案」時，若 MCP 報錯提示「資料庫未找到」或回傳空結果，智能體應自主執行初始化：
釘釘資料庫初始化 (DingTalk)
釘釘是純 Python 本機離線解密，幾乎 100% 自動化，無需管理員權限：
# 智能體執行初始化
dingtalk-init
- 預期輸出：檢測到活躍 UID，輸出
🎉 釘釘數據初始化同步成功！。 - 環境前置判斷（禁止盲目掃描）：若提示未找到資料目錄或 UID，禁止智能體自行在宿主機上漫無目的地遞迴深搜掃描行程或磁碟。請直接暫停並向使用者說明情況，詢問並提醒使用者確認釘釘用戶端是否已在當前機器上登入。
微信資料庫初始化 (WeChat)
微信需要金鑰並對 WCDB 資料庫執行解密與校驗：
- Windows：
# Windows: 管理員身分執行 wechat-initwechat-init會報錯。 - macOS：
# macOS: 支援直接傳入 64 位元 passphrase wechat-init --passphrase <64位元十六進位passphrase>~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/*/db_storage），呼叫系統原生CommonCrypto（CCCrypt）派生金鑰並完成解密。 - 微信運行前置檢查（禁止盲目掃描）：
- 重要約束：如果找不到微信進程或缺少金鑰原料，智能體切勿自行嘗試猜測掃描系統無關進程或遍歷系統全域目錄！
- 正確處置：應主動向使用者明確說明當前環境狀態，引導使用者準備環境或填入 passphrase。
- 權限判定：若 Windows 報錯
Access Denied，向使用者說明原因並建議以管理員身分執行。 - 成功標誌：在使用者資料目錄
~/.wechat_mcp/decrypted/下生成解密資料庫，並在~/.wechat_mcp/app.db下完成 FTS5 索引清洗。若僅需重跑資料清洗與索引，可執行wechat-init --etl-only。
2.2 任務執行中：MCP 工具呼叫規範
在初始化成功後，智能體應優先透過 MCP 工具檢索，避免直接使用裸 SQL 查詢：
微信 (wechat) 推薦呼叫順序：
list_wechat_sessions(limit=20): 先列出最近活躍的會話/群聊，拿到關鍵的session_id（如xxx@chatroom或微信號）。search_wechat_messages(query="關鍵詞", limit=50): 全域全文檢索聊天內容（支援offset翻頁）。get_session_history(session_id="...", limit=100): 獲取目標會話的上下文訊息流。get_message_image(message_id=...): 聊天圖片按需解密。當搜尋或歷史訊息中包含[圖片]時，使用對應的訊息id呼叫此工具。- 預設模式：回傳解密後圖片的本機物理絕對路徑（快取至
~/.wechat_mcp/images/），杜絕因大圖 Base64 直接撐爆 Agent 上下文； - 多模態看圖模式：如當前 Agent 需要視覺看圖分析，可設定
include_base64=True提取 Base64 字串供模型理解。
- 預設模式：回傳解密後圖片的本機物理絕對路徑（快取至
search_shared_files(keyword="...", limit=20): 定位群內或私聊傳輸的檔案路徑。
微信側另提供：get_messages_by_date / get_messages_by_range（按日期或時間範圍取數）、search_contacts（聯絡人反查）、list_chatroom_members（群成員名單）、search_media_files（圖片/影片磁碟路徑）、list_favorites（收藏）、list_emoticons（表情）、get_chat_activity_stats（活躍度統計）、get_persona_style（溝通風格蒸餾）、get_sync_status（索引新鮮度）。其中 get_messages_by_date / get_messages_by_range 與 search_wechat_messages 一樣支援 offset 翻頁。
釘釘 (dingtalk) 推薦呼叫順序：
list_dingtalk_conversations(limit=20): 獲取最近群聊與私聊列表（已自動映射最新實名及群名）。search_dingtalk_messages(keyword="關鍵詞", limit=50): 跨 128 個分表彙總檢索文字。get_dingtalk_messages(cid="...", limit=100): 查看特定釘釘群或私聊的對話細節。list_dingtalk_contacts(keyword="姓名/拼音"): 快速反查聯絡人 UID 與真實姓名。
2.3 版本升級與更新維護 (Project Upgrade & Version Maintenance)
當使用者提出「更新 im-mcp」、「升級微信/釘釘 MCP」、「拉取最新修復」或發現新特性/Bug 修復發佈時，智能體應根據目前的安裝方式執行平滑升級：
1. 全域持久化安裝模式下的升級（推薦）：
如果使用者此前採用 uv tool install 進行安裝，使用 uv tool update 或重新指定 Git 倉庫升級：
# 標準全域一鍵更新
uv tool upgrade im-mcp
# 或強制以最新遠端倉庫版本重新覆蓋安裝（支援最新 Git HEAD）
uv tool install --force "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"
# 國內網路環境（Gitee 源）
uv tool install --force "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]"
2. 即席運行模式 (uvx)：
如果是在沙箱中透過 uvx 運行，uvx 預設可能快取舊版本 Wheel。執行升級或強制刷新版本快取：
# 清理 uvx 臨時工具快取以確保拉取最新 Git 程式碼
uv cache clean im-mcp
# 或在下一次呼叫 uvx 時追加 --refresh 參數強制拉取最新版本
uvx --refresh --from "git+https://github.com/stkoecn/im-mcp.git[all]" <command>
3. 升級後平滑重新載入：
升級完成後，智能體應主動提醒使用者重新整理或重新載入用戶端，以載入最新版本的 MCP 服務定義與工具集：
- Pi / Pebrel：提示輸入
/reload； - Claude Desktop / Cursor / WorkBuddy：提示重啟用戶端或重新連接 MCP 伺服器；
- 如本次升級涉及底層資料庫清洗邏輯變更，可執行
wechat-init --etl-only在 2 秒內無損重建最新 FTS 索引，無需耗時重新提取或解密。
2.4 任務結束後：資料隱私與儲存清理 (Post-flight Cleanup)
在完成週報、工時彙總或使用者明確要求「清理環境」、「刪除匯出的聊天記錄」時，智能體應主動呼叫 im-clean：
預覽待清理檔案（唯讀安全檢查）：
im-clean --dry-run
徹底執行清理：
# 使用 -y 參數靜默清理所有匯出的明文 SQLite、金鑰及中間快取（支援自動檢測並處置常駐進程鎖）
im-clean -y
# 若遇到殘留句柄鎖定，可追加 --force 強制終止 MCP 服務並完成徹底刪除
im-clean -y --force
僅清理特定平台資料：
# 僅清理微信資料，保留釘釘
im-clean --scope wechat -y
# 僅清理釘釘資料，保留微信
im-clean --scope dingtalk -y
2.5 完全卸載與客戶端清理協同 (Full Uninstallation Guidance)
當使用者明確提出「完全卸載這個 MCP」、「徹底刪除聊天工具及配置」時，智能體應協助使用者完成以下層級的標準順序清理，並主動告知使用者哪些步驟需要其在用戶端介面手動操作：
- 退出用戶端或停止服務：提醒使用者先退出當前 AI 用戶端，或由
im-clean -y --force自動處理殘留 MCP 進程； - 自動清理資料：智能體執行
im-clean -y --force徹底清除~/.wechat_mcp與~/.dingtalk_mcp（確保回傳碼為 0，若非 0 嚴禁謊報成功）； - 自動卸載依賴：智能體執行
uv tool uninstall im-mcp或uv cache clean清理環境與快取； - 主動向使用者輸出用戶端手動清理提醒：
- 智能體應根據目前宿主用戶端，提示使用者手動清理設定檔（具體各環境常見路徑可參考本技能文末的【附錄：主流 Agent 宿主環境參考目錄】）。
3. 常見故障處理與智能體行為準則 (Troubleshooting & Agent Rules)
-
核心禁令：報錯立即停下，嚴禁擅自分析程式碼或盲目折騰：
- 如果在安裝、初始化或測試呼叫過程中遇到任何未知報錯、環境衝突或執行異常：
- 絕對禁止：智能體嚴禁擅自深入翻查原始碼、自行寫 patch 補丁修程式碼、反覆猜測重試或盲目排查系統環境；
- 必須執行：立刻停止在報錯步驟，原樣展示核心錯誤摘要，並明確詢問使用者：
「當前步驟遇到錯誤：
[錯誤簡述]。請問您是希望排查自行解決問題，還是停止操作不再使用？」 - 把控制權交給使用者，使用者確認繼續或退出後再行動。
-
安裝初始化後即刻交付使用者，嚴禁擅自編寫程式碼模擬協定反覆測試：
- 智能體在完成工具安裝（如
uv tool install）、設定檔寫入以及init初始化後，整個部署流程就已經全部結束。 - 絕對禁止：智能體私自編寫 Python/Node 測試腳本去模擬 JSON-RPC 2.0 握手、管道通訊或探測協定內部細節。這不僅徒增 Token 消耗與不可控的意外報錯風險，還剝奪了使用者的即時感知與控制權。
- 必須執行：在安裝和初始化完成後，直接交付並給出最簡明友好的使用引導：
- 明確提示使用者在當前用戶端中啟用/信任該 MCP（例如提示 Pi 使用者執行
/reload，Claude Desktop / Cursor 使用者重啟用戶端生效）； - 給出 1~2 個簡單、直觀的自然語言範例引導使用者體驗，例如：
「安裝與初始化已就緒！請您在用戶端中確認信任/開啟該 MCP（如執行
/reload），之後直接對我說類似這樣的話即可開始使用： 👉 『幫我查一下最近專案群裡聊了什麼』 👉 『找一下釘釘裡成鵬發過的報表統計結果』 👉 『彙總一下上週關於某某需求的溝通記錄做週報』」
- 明確提示使用者在當前用戶端中啟用/信任該 MCP（例如提示 Pi 使用者執行
- 智能體在完成工具安裝（如
-
用戶端與應用授權信任（宿主環境自主識別與啟用指引）：
- Agent 必須透過當前會話特徵自主識別出當前使用者所使用的用戶端宿主；
- 嚴禁含糊地輸出「在您的用戶端裡啟用」，而應根據當前宿主給出對應用戶端的具體生效方式（如提示 Pi 輸入
/reload，或提示桌面應用重啟生效，具體特徵可參考文末附錄）。
-
找不到微信/釘釘進程時的行為禁忌：
- 嚴禁自行在宿主機上執行耗時且侵入式的全盤暴力掃描或猜測其他系統進程；
- 必須直接暫停，並友好向使用者確認用戶端登入狀態。
-
微信增量訊息同步問題： 微信用戶端在線時，新訊息會寫入原加密庫。如需獲取剛剛產生的新訊息，智能體可提示使用者「重新執行
wechat-init」以更新本地解密庫。 -
釘釘 WAL 鎖問題：
dingtalk-init已內建自動拷貝機制，即使釘釘正在運行且處於 WAL 事務中，也不會發生 SQLite 鎖庫衝突。 -
隱私安全原則： 解密後的 SQLite 資料庫屬於敏感本機隱私，在公共機器或多租戶環境下，工作結束後務必引導或自動執行
im-clean -y。 -
部署回饋報告與社群自動開發機制 (Deployment Feedback & Auto-Development)：
- 無論部署與初始化是成功還是遇到失敗，智能體在流程結束時，都應主動整理並為使用者產生一份結構化、簡明扼要的《部署與運維回饋簡報》，並提示使用者可一鍵複製並前往 GitHub 提交 Issue。
- ⚠️ 核心高亮原則（必須重點標記，嚴禁含糊）：
- 在報告標題和第一行狀態欄必須使用極其醒目的視覺標識（如
【狀態：🟢 部署成功 / SUCCESS】或【狀態：🔴 部署受阻 / FAILED】）； - 堅決杜絕模稜兩可、中立記敘，讓提問者與排查智能體一眼就能看穿是成功還是失敗。
- 在報告標題和第一行狀態欄必須使用極其醒目的視覺標識（如
- 智能體自動化運維承諾：提示使用者：「本專案已接入 GitHub Agent 自動化協作管道，您提交的 Issue 會有專職智能體自動進行復現排查、程式碼修復並合併提交！」
- 簡報產生規範模板：
- 若成功 (SUCCESS)：
### 📋 im-mcp 部署回饋報告 【狀態：🟢 部署成功 / SUCCESS】 > **最終結論**：✅ 全部依賴安裝成功，資料提取與索引同步完成，服務已具備即時呼叫能力！ - **核心狀態**：🟢 SUCCESS - **環境資訊**：OS版本（如 Win11 23H2）、用戶端宿主（如 WorkBuddy / Pi / Claude Desktop）、Python 及 uv 版本 - **安裝模式**：`uv tool install` / `uvx` / 本地原始碼 - **初始化指標**：耗時（如 微信 12s / 釘釘 3s）、聯絡人/會話/訊息同步條數 - **使用建議**：冷啟動體驗、增量同步指引或下一步功能期望 - **回饋入口**：可前往 [GitHub Issues](https://github.com/stkoecn/im-mcp/issues) 提交經驗，社群 Agent 將自動追蹤最佳化！ - 若失敗或遇阻 (FAILED)：
### ⚠️ im-mcp 部署回饋報告 【狀態：🔴 部署受阻 / FAILED】 > **最終結論**：❌ 流程在中途受阻中斷，核心服務暫無法正常啟動，請參考以下故障定位。 - **核心狀態**：🔴 FAILED - **受阻階段**：依賴安裝 / 微信金鑰提取 / 釘釘解密 / 資料庫索引構建 / 用戶端掛載 - **環境特徵**：OS版本、用戶端宿主、微信版本（如 4.x / 3.x）、釘釘版本（如 7.x V3） - **關鍵報錯摘要**：截取核心錯誤堆疊或系統提示（如 Access Denied / 進程未運行 / 檔案鎖拒絕） - **已嘗試措施**：是否提權、是否嘗試過 `--force` 或 `--etl-only` - **改進建議**：指出當前流程中不夠順暢或需工具自動容錯的環節 - **一鍵回饋**：請直接複製本報告前往 [GitHub Issues](https://github.com/stkoecn/im-mcp/issues) 提交，倉庫專職智能體將自動分析日誌並開展修復！
- 若成功 (SUCCESS)：
4. 附錄：主流 Agent 宿主環境參考目錄（僅供參考）
💡 聲明：本目錄收錄當前各主流 AI 用戶端/智能體環境的預設行為與配置特徵，僅供參考。各平台版本更新迭代後可能存在調整，請以對應平台最新官方文件為準。
| 用戶端環境 | 典型識別特徵 | 配置 / 啟用方式參考 | 卸載與清理方式參考 |
|---|---|---|---|
| Pi / Pebrel | 存在 PI_* 環境變數或 ~/.pi/ 目錄 | 編輯 ~/.pi/agent/mcp.json，在會話中輸入 /reload 重新載入生效 | 從 mcp.json 移除條目，刪除 ~/.agents/skills/im-mcp，輸入 /reload |
| Claude Desktop | 本機 AppData 存在 Claude 配置 | 編輯 %APPDATA%\Claude\claude_desktop_config.json，完全重啟用戶端應用 | 從設定檔的 mcpServers 移除條目並重啟軟體，清理技能目錄 |
| Cursor | VS Code 衍生，存在 Cursor 配置 | 在 Settings ➔ Features ➔ MCP Servers 新增，介面即時掛載 | 在 MCP 伺服器列表點擊對應條目的 Delete / Remove |
| Cline / Roo Code | VS Code 擴充面板 | 在擴充側邊欄 MCP 選項卡中新增配置，切換為「Enabled」啟用並授權 | 在側邊欄 MCP 列表中關閉開關或點擊垃圾桶圖示移除 |
| Cherry Studio | 桌面端多模型管理工具 | 在 設定 ➔ MCP 伺服器 中新增 stdio 命令，儲存即生效 | 在 MCP 伺服器列表選中並點擊「刪除」，儲存設定 |
| WorkBuddy | 存在 ~/.workbuddy/ 目錄或相關配置 | 編輯 ~/.workbuddy/mcp.json，在連接器管理介面手動點擊「信任/啟用」 | 從 mcp.json 移除設定塊並在介面移除連接器 |