baoyu-wechat-summary

WeChat Group Summary

群聊精華提鍊專家。把零散的微信群組聊天紀錄提鍊成結構化、可讀性高的簡報，並維護跨次執行的群組歷史與群友畫像。底層依賴外部 wx-cli 二進位檔（wx 指令），不包裝腳本。

⚠️ Sandbox restriction

wx-cli 會讀取 ~/.wx-cli/（設定檔、快取、daemon socket）以及微信的資料目錄（macOS 上為 ~/Library/Containers/com.tencent.xinWeChat/）。這兩個路徑都在 Claude Code 的預設沙盒之外。此 Skill 中的所有 wx 指令從一開始就需要以 dangerouslyDisableSandbox: true 執行——請勿先嘗試在沙盒內執行而浪費時間。使用者可以使用 /sandbox 來檢視/編輯限制。

References（按需載入）

本檔案只保留工作流程骨架；細節拆分在 references/ 下，執行到對應步驟時再讀取，請勿一開始就全部載入：

參考檔案	內容	何時讀取
references/setup.md	環境檢查（wx-cli 安裝/權限/初始化）、wx-cli 指令速查、排除故障手冊	新環境首次執行，或任何 wx 指令失敗時
references/output-formats.md	兩版摘要的 Section 順序、格式與內容規範、輸出骨架、自檢清單	Round 2 動筆前
references/profiles.md	畫像檔案格式、更新規則、隱私紅線、回溯流程	Step 3.7 / 8.5 / Step 9
references/group-memory.md	群組級事實記憶的寫入門檻、防注入、格式	Step 8.6

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. 優先使用內建的使用者輸入工具（由當前 Agent 執行階段提供）— 例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同等工具。
2. 退路 (Fallback)：若無此類工具，請發送帶有編號的純文字訊息，並要求使用者針對每個問題回覆所選的編號/答案。
3. 批次處理 (Batching)：若工具支援每次呼叫包含多個問題，請將所有適用問題整合為單次呼叫；若僅支援單一問題，請依優先順序一次詢問一個。

下方具體的 AskUserQuestion 參考僅為範例 — 在其他執行階段中請替換為本地相應的工具。

Prerequisites

快速驗證環境：wx --version 有輸出且 wx sessions 回傳資料即可繼續。任何一步失敗，或是首次在新環境執行 → 讀取 references/setup.md（完整環境檢查、wx-cli 指令速查、排除故障手冊），停在第一個失敗項目並提供使用者確切的修復指令。絕不自動安裝、絕不替使用者執行 sudo。

Preferences (EXTEND.md)

按優先順序檢查 EXTEND.md — 找到的第一個優先使用：

優先順序	路徑	範圍 (Scope)
1	.baoyu-skills/baoyu-wechat-summary/EXTEND.md（相對於專案根目錄）	專案 (Project)
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-wechat-summary/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-wechat-summary/EXTEND.md	使用者主目錄 (User home)

結果	動作
已找到	讀取、解析、套用。在本階段 (session) 首次使用時，簡短提醒：「正在使用來自 [路徑] 的偏好設定。可編輯該檔案以修改預設值。」
未找到	必須在生成任何摘要前執行首次設定 (BLOCKING) — 切勿靜默使用預設值。

Supported keys

EXTEND.md 為純文字檔，包含 key: value 或 key=value 行，以 # 作為註解，Key 不區分大小寫。

Key	型別	預設值	用途
self_wxid	string	(必填)	擁有者帳號的 wxid。from_wxid 與此匹配的訊息將歸因於該使用者。
self_display	string	(必填)	在摘要內文中用於替換使用者自身訊息的顯示名稱。
default_version	normal / roast / both	normal	使用者未另作說明時，預設要生成的版本。
default_time_range	string (例：7d, 24h, 1d)	(無)	使用者省略時間且無增量錨點時的預設範圍。
data_root	path	{project_root}/wechat	覆寫摘要資料夾存放的位置。
bot_aliases	以逗號分隔的字串	bot, 精華bot	觸發「@bot 答疑」區段的名稱。包含 @<alias>（不區分大小寫）的訊息會被視為針對摘要 Bot 的提問/要求。請選擇不與任何真實群友或現有 Bot 重複的名稱，以避免歧義。

範例範本位於 EXTEND.md.example。

First-Time Setup (BLOCKING)

若未找到 EXTEND.md，切勿靜默繼續。

步驟 A — 先嘗試自動偵測 self_wxid 與 self_display。 執行以下指令（依序進行，遇到第一個成功的即停止）：

# 1. 若 wx-cli 提供 whoami，請使用它
wx whoami --json 2>/dev/null

# 2. 否則，在最近的 session 中尋找自己發送的訊息
wx sessions --json --limit 20 2>/dev/null

針對選項 2，掃描使用者曾發言的任何私訊/群組對話串，並讀取一組其自身的 from_wxid / from_nickname 對。若你能有把握地預填這兩個值，請在下方的提問中將其作為預設值；否則保持欄位空白讓使用者填寫。

步驟 B — 使用一次 AskUserQuestion 呼叫（批次）進行確認，並預先填入自動偵測到的內容：

• self_wxid（例如 wxid_abc123）— 備用提示：使用者可透過 wx contacts --query "<自己的暱稱>" 尋找，或是透過檢查 wx sessions --json 中自己發送的任何訊息來取得
• self_display（例如 寶玉）— 希望在訊息歸因中顯示的名稱
• default_version — 選擇 normal / roast / both 其中之一
• data_root — 摘要資料夾存放位置。預設：{project_root}/wechat。可輸入自訂的絕對路徑（例如 ~/Documents/wechat-digests）或留空使用預設值。
• 儲存位置 — 選擇專案 (project) / XDG / 主目錄 (home) 其中之一

將 EXTEND.md 寫入所選路徑。若使用者提供了非預設的 data_root，請將其作為未註解的行包含進去；否則可省略（自動套用預設值）。確認「偏好設定已儲存至 [路徑]。可隨時編輯以變更預設值。」，然後繼續執行摘要工作流程。

Workflow

Step 1: Parse the user's request

解析出：

• 群組名稱（或用於模糊比對的部分名稱）
• 時間範圍 — 彈性解讀：
  • 「最近 1 天」/「今天」/「last 24 hours」→ 1 天
  • 「最近 3 天」→ 3 天
  • 「最近 7 天」/「這週」→ 7 天
  • 「最近 30 天」/「最近一個月」→ 30 天
  • 「某天」（例如「3 月 5 號」）→ 該特定日期
  • 「某天到某天」（例如「3 月 1 號到 3 月 5 號」）→ 日期範圍
  • 「從上次開始」/「繼續」/「接著上次」/「since last」→ 增量模式 (incremental mode)：讀取該群組的 history.json，使用 last_digest.last_message_time 作為起點
  • 未指定時間 → 增量模式。若尚無 history.json，則退回使用 EXTEND.md 中的 default_time_range（若有設定），否則預設為最近 24 小時。
• 要生成的版本：
  • 從 EXTEND.md 的 default_version 開始。
  • 使用者要求覆寫：關鍵字「毒舌」/「roast」/「挑釁」/「再來個毒的」/「sass」→ 強制 include_roast=true。關鍵字「只要正經的」/「normal only」/「不要毒舌」→ 強制 include_normal=true, include_roast=false。「都來一份」/「兩個版本都要」/「both」→ 兩者皆要。
  • include_normal / include_roast 至少需有一個最終為 true。

使用今天的在地日期，將相對範圍轉換為絕對的 --since YYYY-MM-DD --until YYYY-MM-DD 配對。

Step 2: Find the group + resolve folder path

wx contacts --query "<group_name>" --json

過濾出 username 以 @chatroom 結尾的項目。若有多個匹配的群組，使用 AskUserQuestion 消除歧義。若無匹配項目，退回使用 wx sessions --json 在其中搜尋，然後再詢問使用者。

確認後，計算資料夾路徑：

{data_root}/{group_id}-{sanitized_group_name}/

其中 data_root 來自 EXTEND.md（預設為 {project_root}/wechat）。

清理群組名稱 (Sanitize) — 將任何 / \ : * ? " < > | NUL 及控制字元替換為 _。裁切末尾的句點與空白。請勿去除 Emoji 或中文字元。

群組重命名偵測：列出 {data_root}/ 下現有的資料夾，尋找名稱以 {group_id}- 開頭的任何資料夾。若存在但字尾不同（群組已重命名），將現有資料夾重命名為新的 {group_id}-{sanitized_new_name} 格式。若已存在相同新名稱的目標（極少見），保留兩者並在本執行階段中優先使用現有資料夾。

Step 2.5: Look up the group owner（群主）

群主是誰必須有據可查，不能憑歷史摘要、群友玩笑或印象推斷（群主可能換屆，歷史摘要裡的說法會過期）：

wx members "<group_name_or_id>" --json

• 檢查輸出中是否有 owner / role 欄位標示群主；有則以此為準
• 若 wx-cli 版本未揭露群主資訊，則查 memory.md「群基本檔案」裡有出處的記錄；兩處都沒有 → 摘要裡不要斷言誰是群主
• 查到的結果與「群基本檔案」不一致時以本次查詢為準，更新檔案並追加修訂記錄（註明查詢日期）

Step 3: Fetch messages

務必將擷取內容重導向至 $TMPDIR 檔案 — 該檔案是整個執行階段唯一的真理來源 (single source of truth)：Round 3 的歸因稽核會對其進行 grep，統計資料亦由此計算。切勿純粹依據對話記憶撰寫摘要。

對於小批次（單日摘要，通常 < 200 則訊息），你可以額外將 JSON 透過管道傳送給 Agent 直接讀取：

wx history "<group_name_or_id>" --since YYYY-MM-DD --until YYYY-MM-DD -n 5000 --json

對於大批次（週/月摘要，> 200 則訊息），$TMPDIR 重導向亦可避免原始載荷塞滿對話上下文：

wx history "<group_name_or_id>" --since YYYY-MM-DD --until YYYY-MM-DD -n 5000 --json > "$TMPDIR/wx-messages.json"
wc -c "$TMPDIR/wx-messages.json"
jq 'length' "$TMPDIR/wx-messages.json"

然後透過帶有 offset + limit 的 Read 分區段讀取檔案，或使用 jq 查詢進行處理（例如 jq '.[0:200]'，jq '[.[] | {id, from_nickname, timestamp, content: (.content | .[0:50])}]' 以進行輕量骨架檢視）。一次讀取所有 500+ 則訊息會不必要地消耗 Token 預算。

注意事項：

• --since 包含該日期；--until 解讀為日期（整天）。若使用者要求「僅限今天」，請將兩者均設為今天。
• -n 5000 為防禦性上限；對於非常活躍的群組，請調高並重新擷取。
• 為保險起見，請按訊息的 timestamp 過濾回傳的訊息（某些背景程式可能會回傳相鄰日期的訊息）。
• 範圍分割：對於 > 7 天或 > 500 則訊息的範圍，相較於強制生成單一巨大摘要，建議優先生成每 3 天的摘要再進行後設總結 (meta-summary) — 超過一週的無關主題會導致分類品質急劇下降。

增量模式：擷取後，丟棄任何 timestamp <= 來自 history.json 的 last_message_time 的訊息，並將過濾後的集合寫回 $TMPDIR 檔案（確保稽核與統計資料精確基於摘要所涵蓋的內容執行）。注意：last_message_time 為 MM-DD HH:MM — 純字串比較在跨年份邊界時會失效（12-31 與 01-01）；請在此處依日期語意進行比較。若剩餘 0 則訊息，請告知使用者「上次摘要後沒有新訊息，已跳過生成」並結束。

Step 3.5: Parse the message schema

wx history --json 會回傳訊息物件的陣列。請使用存在的欄位，並容忍缺失的欄位：

• id / msg_id / local_id — 訊息識別碼（使用 wx-cli 發出者）。建立骨架時，在工作筆記中引用 ID 作為錨點。
• from_wxid — 穩定的發送者識別碼
• from_nickname — 顯示名稱（可能是群組備註或原始暱稱）
• content — 文字載荷。範例：
  • 純文字 → 原樣使用
  • [圖片] → 不透明佔位符；參見下方的圖片處理說明
  • [表情] → emoji/貼圖；除非周圍有討論，否則在內文中跳過
  • [影片] / [文件] → 媒體引用；除非有被討論，否則跳過
  • [連結] <title> 或 [連結/文件] <title> → 分享的文章；標題即為資訊 — 引用它並註明分享者