TgWitness參考資料 / 存檔與整合功能
Telegram · 命令列
可透過腳本和代理程式進行搜尋、讀取上下文、統計活動次數，並匯出已儲存的訊息，具備 --json 輸出格式、穩定的退出代碼，以及範圍限定的唯讀憑證。
預覽。 tgwitness search, context, messages, stats 以及 export 讀取
已儲存的觀察記錄，供腳本及 AI 代理程式使用。該工具無法向
Telegram 發送任何內容、變更設定或修改簽名日誌。
當 --json，標準輸出（stdout）會傳輸精確一個 JSON 文件（export 寫入 JSON Lines）。
進度、提示與錯誤訊息將輸出至 stderr。退出代碼保持不變：
| 程式碼 | 含義 |
|---|---|
0 |
成功，包括空結果 |
1 |
失敗：無法存取面板、資料無法讀取、匯出中斷 |
2 |
使用錯誤或無效請求：日期格式錯誤、未知選項、搜尋索引未啟用 |
3 |
目前無法使用：工作區已在運行的面板中開啟，或面板要求稍後重試（速率限制、超時） |
4 |
存取遭拒：代幣遺失、過期或遭撤銷、聊天室超出權限範圍，或該工具不允許執行此操作 |
兩種閱讀方式#
透過控制面板（--url）。此指令使用與
MCP 相同的範圍限定存檔 API。請在「整合」→「MCP」中建立連線：選擇工作區與聊天室、
工具及有效期限，然後複製一次權杖。此連線為唯讀模式，僅限
於所選的聊天室，每分鐘請求次數上限為 60 次，且可隨時撤銷或
輪替。控制面板的登入權杖及 Telegram 憑證在此處無法使用。
export TGWITNESS_URL=https://panel.example.org # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_... # or --token-file path
tgwitness search 'перевод карта' --json遠端控制面板需使用 HTTPS；僅在以下情況下接受明文 HTTP： 127.0.0.1,
localhost 和 ::1。代理伺服器環境變數將被忽略，且不接受
重定向，因此令牌僅會傳送至您指定的地址。
直接從已停止的工作區（--data-dir）讀取。以
完全本地存取權限讀取資料目錄，無需憑證。請在資料目錄的副本上使用，或於
資料收集停止時使用。簽名記錄絕不會被更改；如同控制面板，開啟
工作區可能會將其衍生的索引更新至最新狀態。當控制面板已開啟該工作區時，此指令會以
代碼 3；請改透過面板進行讀取。若未指定 --data-dir, TGWITNESS_DATA,
./data/live ，則會使用執行該指令之安裝環境的資料目錄。
--workspace ID 選取工作區（預設 default). tgwitness messages
--workspaces 列出您有權限閱讀的工作區。
指令#
| 指令 | 結果 |
|---|---|
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] |
優先顯示最符合的結果，包含詞形變化、加引號的完整短語、網域及 @username (語法) |
tgwitness search QUERY --exact [--before SEQ] |
精確文字，最新內容優先，不包含索引 |
tgwitness context CHAT_ID MESSAGE_ID |
前後各十則訊息 ID 範圍內的已儲存訊息 |
tgwitness messages |
可供閱讀的聊天紀錄 |
tgwitness messages CHAT_ID [--since] [--until] [--before SEQ] |
聊天室中已儲存的訊息，最新訊息排在最前 |
tgwitness messages CHAT_ID --message ID |
每則訊息的所有儲存版本及刪除紀錄 |
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] |
活動統計資料如下 |
tgwitness export [--chat ID] [--since] [--until] [--output FILE] |
將觀察記錄以 JSON Lines 格式依日誌順序儲存 |
日期格式為 2026-10-01 （UTC 午夜）或附有時區的 ISO 時間格式，
2026-10-01T09:00+03:00。關於 search, messages 及 export ，它們代表
觀察時間。每個頁面最多可容納 50 筆記錄：請遵循 next_offset (--offset) 進行
排序搜尋，並 next_before (--before) 其他功能。
排序搜尋結果上限為 1,000 筆。最後一頁的結果數量可能少於 --limit；若存在更多符合條件的觀察結果，請縮小查詢範圍、聊天室或時間範圍。
每則訊息結果皆包含 untrusted_content: true工作區、聊天室及
訊息 ID、日誌序號、儲存紀錄的雜湊值，以及一個面板連結。編輯、
刪除通知與 missing_on_recheck 均為獨立的記錄。若某項記錄缺失
，並不代表該事件從未發生。
活動統計#
stats 統計特定聊天室、特定發送者或範圍內所有聊天室中已儲存的觀察記錄數量：
- 按 UTC 小時及星期幾（以星期一為起點）分類的訊息；最繁忙的小時與日子；
- 已編輯、刪除及
missing_on_recheck分享； - 發訊者及其訊息數量，以及第一則與最後一則訊息的時間；
- 最常出現的網域以及
@handles，在所有 儲存的版本中，每則訊息僅計數一次； - 涵蓋範圍：
coverage.gap記錄，以及（若要存取整個工作區） 未接收到收集器心跳訊號的期間（collector_liveness).
該時間段選取自 Telegram 回報的訊息時間。小時數與星期數可
協助估算發訊者的時區；但無法據此確定時區。相關數據是根據
請求從日誌中計算得出，並不會儲存。若您的存取範圍涵蓋整個工作區，每個結果會標示其
所涵蓋的日誌起始點。透過
控制面板瀏覽五秒後，或 --timeout 本地（預設 30 秒）後，讀取即停止；此時 complete 的值為 false，且
partial 會標示出第一筆尚未讀取的記錄。在此情況下，僅會
計算最新記錄的數量。
匯出#
export 每筆儲存的觀察記錄（新訊息、快照、
編輯、復原訊息、刪除通知、 missing_on_recheck 及已儲存的媒體
記錄），並依日誌順序排列。每行皆包含與其他結果相同的欄位，並附有
完整內容。若 --output，檔案將以 .partial 名稱下寫入，
並僅在面板完成記錄後才重新命名；若匯出過程中被中斷，則不會產生
檔案，並以代碼 1. --output 絕不會覆寫現有檔案。若使用
--output 和 --json，標準輸出將顯示摘要：記錄數、最後的日誌
序列，以及（若為整個工作區存取）日誌頭。
透過控制面板進行匯出時，需具備允許「匯出訊息」
（僅限命令列）的連線；此選項預設為未勾選狀態。此檔案僅為工作副本，並非證據：若需可驗證的
移交，請使用「匯出」區段中的簽名匯出檔，該檔 python -m tgwitness.verify會進行驗證。
該面板在輸出每筆記錄（包括完成 記錄）之前，會重新檢查存取權限。若存取權限已被撤銷或過期，將導致匯出不完整。延遲頁面讀取 會與其他查詢共享存檔工作程序的限制，且設有等待時間上限。
代理技能#
.agents/skills/tgwitness-cli/SKILL.md
說明代理程式如何使用這些指令、如何引用記錄，以及如何處理
擷取的文字。讀取 .agents/skills 需從儲存庫
的檢出版本中載入該檔案。若使用 Claude Code，請複製 tgwitness-cli 資料夾複製到 .claude/skills/ 您的專案中，或 ~/.claude/skills/.
MCP 與命令列介面#
兩者均採用相同的連線方式、範圍檢查及限制。MCP 的結果限制為
一個 64 KiB 的頁面，因此 MCP 不提供批量匯出功能；其透過命令列進行串流輸出。
get_activity_stats 兩者皆可使用此功能。