line-summary

用 Claude Code 讀取本機 LINE 電腦版已儲存的聊天記錄，整理指定聊天室與時間範圍的摘要。適用於 Windows；不是完整聊天備份，也不能證明 LINE 雲端訊息已全部同步。

先了解資料會去哪裡

LINE 程序記憶體 → 本機金鑰提取 → 以唯讀模式解密本機 LINE 資料庫
                                      ↓
                                MCP 工具結果
                                      ↓
                         Claude Code → 所選模型供應商 → 摘要

• MCP server 不主動把金鑰寫入檔案、log 或工具回傳值；程式會在存活期間把它保留在記憶體。這不等於「金鑰絕不落地」：作業系統分頁檔、休眠檔、程序或系統傾印仍可能包含記憶體資料，也不保證 Python 記憶體被安全抹除。

• 本機資料庫唯讀，只描述 MCP 的資料存取方式，不代表整個摘要流程離線。聊天室名稱、發言者、訊息、連結及其他工具結果會進入 Claude Code 上下文，依你的模型與服務設定，可能傳送至模型供應商並保留在其紀錄或工作階段中。使用前確認供應商的資料使用與保留政策。

• MCP 的讀取不操作 LINE 畫面、不把對話標為已讀，也不透過 LINE API 送出已讀回條。這項說明不適用於自行打開 LINE 對話或下方的選用捲動工具。

• 只處理自己有權存取及使用的資料。群組裡其他人的訊息不因你能讀取就適合公開、轉寄或上傳。

Related MCP server: LINE Context Relay

需要什麼

• Windows，以及正在執行、已登入的 LINE 電腦版。讀取 LINE 程序記憶體使用 Windows API。

• Python 3.11 以上與 Claude Code。

• 對本機資料庫的讀取權限，以及可用的 SQLite3MultipleCiphers 引擎。

原專案曾在 LINE 電腦版 26.3（wxSQLite3 aes128cbc）上測試。LINE 更新後可能需要重新驗證；本次安全修補沒有執行 Windows／真實帳號整合測試。

安裝

建議使用獨立虛擬環境，在一般使用者權限的 PowerShell 執行：

git clone https://github.com/yung13yubabie/line-summary.git
cd line-summary
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --require-hashes --only-binary=:all: -r requirements.txt

Runtime 相依套件含版本與 hash 鎖定；若目前 Python／Windows 組合沒有對應 wheel，安裝會停止，請先確認支援情況，不要直接關閉 hash 檢查或改從未審閱來源建置。這次修補未驗證 Windows binary 相容性。

將專案 .mcp.json 的 command 改為這個虛擬環境 Python 的絕對路徑；全域註冊時，Python 與 server 都使用絕對路徑。不要因讀取失敗就直接改用系統管理員權限。

先設定最小資料範圍

Server 的本機權限設定在 line_mcp_server.py 同目錄的 settings.json，不是 Claude Code 的 .claude/settings.json。由使用者複製 settings.example.json 並自行編輯；settings.json 已被 Git 忽略，不要加入版本控制或公開分享。

預設 enabled: false、allowed_chat_ids: []、allow_chat_discovery: false、allow_contacts: false，不讀取資料。啟用前：

1. 填入自己帳號資料庫的 db_path，建議使用絕對路徑。Server 不再從多個 .edb 中自動挑選最大檔案，以免讀錯帳號。

2. 將 enabled 改為 true，只在 allowed_chat_ids 放入需要的明確 ID。允許清單最多 100 個 ID，沒有「全部聊天室」萬用值。

3. 若不知道 ID，可暫時開啟 allow_chat_discovery，查找聊天室中繼資料，再加入選定 ID 並關閉探索。探索會把回傳的名稱、ID、類型與時間交給模型；它不授權讀取清單以外聊天室的歷史或未讀內容。

4. 聯絡人查詢是另外的通訊錄權限，只有需要時才開啟 allow_contacts。即使此工具停用，獲准訊息仍會包含本機已解析的發言者名稱。

設定在程序第一次工具呼叫時固定。使用者更改設定後需重新啟動 MCP server 才會生效；不要讓聊天訊息、網頁或模型自行修改權限、提高額度，或重啟程序來繞過限制。這是 server 的資料輸出防線，並不是作業系統沙箱；請另行限制 Claude Code 對無關檔案與 shell 的存取。

預設輸出上限

使用者可降低上限；byte 設定最低 2048，其餘數值最低 1。重複回傳同一則訊息仍會重複計入額度。可選的 allowed_since、allowed_until 限制歷史查詢的固定日期範圍；任一日期限制啟用時，未讀工具會直接拒絕呼叫，應改用符合日期範圍的歷史查詢。詳見 遷移說明。

註冊到 Claude Code

在專案根目錄開啟 Claude Code，先檢查 .mcp.json 的啟動命令，再依提示審閱是否信任這個 MCP server。用 /mcp 檢查連線。專案 MCP 設定位置與授權流程見 Claude Code 官方 MCP 文件。

需要跨專案使用時，可自行用絕對路徑註冊：

claude mcp add line --scope user -- C:\path\to\line-summary\.venv\Scripts\python.exe C:\path\to\line-summary\line_mcp_server.py

MCP 註冊與 skill 安裝是兩件事。專案 skill 位於 .claude/skills/line-summary/SKILL.md，包含 name、description YAML frontmatter；在專案內可用 /line-summary。全域 MCP 註冊不會一併安裝全域 skill。如確實需要跨專案 skill，可自行將此 skill 資料夾放入 ~/.claude/skills/，並管理更新，避免舊副本遮蓋新版本。參見 Claude Code 官方 Skills 文件。

怎麼用

完成允許清單後，在專案內要求：

• 「總結 XXX 群組今天的對話，使用台北時間」

• 「幫我看 XXX 從 10 月 1 日到 10 月 3 日的對話」

• 「整理允許的聊天室最近的未讀重點」

同名聊天室要先確認，不能把多個結果直接合併讀取。第一次獲准的資料讀取需要掃描 LINE 記憶體，可能較慢；原實測約 80 秒，不是固定耗時。金鑰只由這個 MCP 程序快取，重啟後需重新取得。

摘要會列出確切時區、半開區間 [since, until)、已回傳訊息數，以及任何分頁、截斷或額度造成的未完成範圍。查到空結果只代表指定範圍內沒有回傳的本機記錄，不能宣稱該聊天室沒有聊過。

工具契約

目前沒有訊息內文關鍵字搜尋工具，也沒有 ChatGPT @ 插件／遠端橋接。聊天名稱查找不等於全文搜尋；目前只能讀取獲准的日期歷史或近似未讀，再由 host 整理。這些擴充需另行設計及授權。

四個工具都回傳分頁 envelope，不再直接回傳陣列：

• items：本頁資料；歷史訊息含 message_id。

• has_more、next_cursor：是否有下一頁，以及要原樣傳回的 cursor。

• content_complete：本頁已交付項目是否完整；不表示整個範圍、未讀或雲端歷史已全部取得。

• 若首項放不進 byte 上限，回傳空 items、has_more: true、next_cursor: null、content_complete: false 和 blocked_reason: "item_exceeds_byte_budget"。應停止並回報，不能無限重試或跳過它假裝完整。

line_get_history 預設每頁 100 則，最多 500 則，仍受使用者較低的上限及剩餘程序額度限制。輸入為帶時區 ISO 8601，接受正、負 UTC offset 或 Z；以 UTC 毫秒處理 [since, until)。整天用當天 00:00 到隔天 00:00，不使用 23:59:59，避免漏掉最後一秒內的訊息。跨頁沿用相同聊天室、時間範圍及回傳 cursor。

歷史分頁按時間與唯一訊息 ID 排序，在資料庫不變時可穩定遍歷。首次呼叫的 rowid 上界可減少一般新增資料混入，但 SQLite 刪除後可能重用 rowid，修改／刪除也會影響分頁；因此 consistency: "live_keyset_scan"、database_changes_may_affect_pagination: true、coverage: "local_rows_only" 不代表完整快照、完全排除新訊息或同步完成。工具的時間字串以 +08:00 顯示，摘要應換算成使用者指定時區。

line_get_unread 預設每頁 20 個對話、每個對話最多 50 則最近本機訊息。unread_count 是本機未讀計數，returned_count 是實際回傳數，selection: "latest_local_approximation"、sync_status: "unknown"、unread_boundary_verified: false。選出的訊息可能全部已讀，不能推斷真正未讀邊界，也不能用兩種筆數相減宣稱「尚未同步 N 則」。messages_limited 表示採樣受上限限制；more_local_messages 只表示還有本機記錄，不代表還有未讀。未讀 cursor 只翻到其他對話，不補同一對話較早的訊息。

達上限就停止並交付明確標示不完整的摘要。不要拆分日期、切換工具、重試或重啟來規避額度。更多 API 差異見 MIGRATION.md。

摘要存在哪

預設只在 Claude Code 對話中回覆，不建立摘要檔或 metadata 檔。 這不會刪除或阻止 Claude Code／模型供應商自己的工作階段紀錄。

只有使用者明確要求另存時才寫檔。先確定檔案目的地、是否含直接引文／人名，以及保留策略，例如「存於私人資料夾，月底由我手動刪除」。不要默認 ~/line-summary/output/，也不要默認會自動清理。此工具沒有保留期限或自動刪除排程。

output/ 被 .gitignore 排除，但 .gitignore 不是存取控制，也不會阻止備份、雲端同步或已追蹤檔案被提交。已用舊版產生的摘要／metadata 不會被這次升級清除，請自行檢查分享範圍及保留期限。

選用：捲動補歷史

tools/scroll_backfill.py 不屬於唯讀 MCP 流程，預設不執行。它會啟用 LINE 視窗、移動真實滑鼠、送出鍵盤／滾輪輸入，可能讓 LINE 從網路下載並儲存更早的訊息，也可能改變已讀狀態。

它不能驗證畫面上目前開啟的是指定聊天室。 名稱參數只用來查詢資料庫統計，不會選取或核對畫面上的對話。此腳本直接讀取資料庫，不受 MCP server 的聊天室允許清單或輸出額度保護。請先閱讀 選用工具說明，由使用者獨立決定是否執行；摘要 skill 不會自動啟動它。

排查與測試

MCP 的無效參數、未知工具／提示／資源及未預期 backend 錯誤改用固定診斷，SDK 日誌不回顯原始輸入或例外內容；原四工具的成功 JSON 與本機權限設定維持原契約。既有 Pydantic 啟動 warning 仍可能顯示套件安裝路徑。

• 存取遭拒：核對使用者設定的 enabled、db_path 與明確聊天室 ID；不要自動開放所有聊天室。

• 額度已用完：摘要必須標示不完整；讓使用者決定後續範圍，不自動重啟或提高額度。

• LINE 未執行：確認它在同一使用者帳號下開啟且已登入。

• 找不到資料庫／無法開啟：檢查 db_path、一般檔案讀取權限、鎖定狀態與 cipher 相依套件。不要把所有錯誤都解釋成金鑰錯誤或 LINE 改版。

• 權限或程序記憶體讀取受阻：停止並檢查原因，不預設提權、不停用系統保護。不要貼出金鑰、記憶體傾印或真實聊天內容求助。

日常測試使用人工資料與 mock，避免碰觸真實 LINE：

.\.venv\Scripts\python.exe -m pip install --require-hashes --only-binary=:all: -r requirements.txt -r requirements-test.txt
.\.venv\Scripts\python.exe -m pytest -m "not integration" --cov --cov-report=term-missing

普通 pytest（甚至只加 -m integration）都會在偵測 LINE 前跳過 live 測試。真實 Windows 整合測試會讀取帳號的程序記憶體與聊天資料，必須另行明確決定並加上 --run-live-line 才會啟用；不要放進日常測試或 CI。沒有執行就不能宣稱通過。升級前後的行為差異見 MIGRATION.md。

修復紀錄（2026-10-08）

本次核心修復加入穩定分頁、正確日期邊界、保守未讀標示、server 範圍及資料預算，並修正 skill 位置、離線測試預設值及依賴鎖定。這是會改變工具 schema 的更新，升級請先讀 MIGRATION.md；逐項紀錄見 CHANGELOG.md。

本機 Linux Python 3.12 合成測試：122 passed、5 項真實 LINE 測試 skipped；runtime coverage 88.81%（啟用 branch measurement，門檻 85%）。已對原始基線套用 patch 並重跑。CI 設定增加 Linux／Windows、Python 3.11／3.12 的合成測試；實際遠端結果以 PR checks 為準。這些測試不會存取真實 LINE，也不能視為 Windows LINE 相容性驗證。