本頁部分內容仍為英文:英文原文在翻譯後已進行修改。
參考資料 / 存檔與整合功能
Telegram · 命令列
可透過腳本和代理程式進行搜尋、讀取上下文、統計活動次數,並匯出已儲存的訊息,具備 --json 輸出格式、穩定的退出代碼,以及範圍限定的唯讀憑證。
Preview. tgwitness search, context, messages, stats and export read
saved observations for scripts and AI agents. They cannot send anything to
Telegram, change settings or modify the signed journal. tgwitness index and
tgwitness backup (below) work on a local data directory and
need no token.
當 --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 [--limit N] [--before SEQ] |
前後各十則訊息 ID 範圍內的已儲存訊息 |
tgwitness messages [--limit N] [--offset N] |
可供閱讀的聊天紀錄 |
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--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) 其他功能。
Ranked search stops at 1,000 results. The final page may be shorter than --limit. When more observations match, the last page says so (truncated: true with --json); narrow the query, chat or period.
每則訊息結果皆包含 untrusted_content: true
、工作區、聊天室及
訊息 ID、日誌序列號、儲存記錄的雜湊值以及面板連結。編輯、
刪除通知及 missing_on_recheck
均為獨立記錄。stats
中的涵蓋範圍顯示搜尋結果所代表的期間。
活動統計#
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
進行驗證。
該面板在輸出每筆記錄(包括完成 記錄)之前,會重新檢查存取權限。若存取權限已被撤銷或過期,將導致匯出不完整。延遲頁面讀取 會與其他查詢共享存檔工作程序的限制,且設有等待時間上限。
Index and backup#
These two commands read the data directory directly and take no token or --url.
| 指令 | 結果 |
|---|---|
tgwitness index status [--workspace ID] [--data-dir DIR] [--json] |
Search index state of one workspace or, by default, every workspace: mode, ready, building or not built, indexed and journal head sequence. Works while the panel runs |
tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json] |
Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code 3 while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
tgwitness backup FOLDER [--data-dir DIR] [--json] |
Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes backup-manifest.json with every file's SHA-256 and the journal heads |
index accepts --workspace default or a workspace ID; the default is all. The
backup skips temporary exports, SQLite sidecar files and lock files. The folder
holds the Telegram session and signing keys, so keep it as private as the data
directory. Backup, restore, and capacity
describes restoring and what the next start records.
代理技能#
.agents/skills/tgwitness-cli/SKILL.md
說明代理程式如何使用這些指令、如何引用記錄,以及如何處理
擷取的文字。讀取 .agents/skills 需從儲存庫
的檢出版本中載入該檔案。若使用 Claude Code,請複製 tgwitness-cli 資料夾複製到 .claude/skills/ 您的專案中,或 ~/.claude/skills/.
MCP 與命令列介面#
兩者均採用相同的連線方式、範圍檢查及限制。MCP 的結果限制為
一個 64 KiB 的頁面,因此 MCP 不提供批量匯出功能;其透過命令列進行串流輸出。
get_activity_stats 兩者皆可使用此功能。