# 資料蒐集原理

Canonical page: https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/collection/

觀察範圍、即時更新、重新核對、附件、使用者操作以及「缺口」的含義，皆以逐筆記錄的方式呈現。

TgWitness 會記錄已連線的 Telegram 帳號所觀察到的內容。該日誌會保存 這些觀察結果、其時間順序，以及隨附的上下文。它不會 根據缺失的訊息或帳號處於連線狀態，來推斷未被觀察到的行動。

## 從登入到日誌

流程圖 · 授權使用者帳戶 → 選擇可存取的群組與頻道; 選擇可存取的群組與頻道 → 儲存事件與附件設定; 儲存事件與附件設定 → 開始監測; 開始監測 → 透過活躍的客戶端接收更新; 透過活躍的客戶端接收更新 → 適用來源與事件政策; 適用來源與事件政策 → 附加一份經簽署的觀察記錄; 附加一份經簽署的觀察記錄 → 檢視或匯出日誌; 附加一份經簽署的觀察記錄 → 處理任何排程中的附件; 處理任何排程中的附件 → 附上下載結果 · 授權使用者帳戶 · 選擇可存取的群組與頻道 · 儲存事件與附件設定 · 開始監測 · 透過活躍的客戶端接收更新 · 適用來源與事件政策 · 附加一份經簽署的觀察記錄 · 檢視或匯出日誌 · 處理任何排程中的附件 · 附上下載結果

**圖表轉為文字**

1. 授權使用者帳戶 → 選擇可存取的群組與頻道
2. 選擇可存取的群組與頻道 → 儲存事件與附件設定
3. 儲存事件與附件設定 → 開始監測
4. 開始監測 → 透過活躍的客戶端接收更新
5. 透過活躍的客戶端接收更新 → 適用來源與事件政策
6. 適用來源與事件政策 → 附加一份經簽署的觀察記錄
7. 附加一份經簽署的觀察記錄 → 檢視或匯出日誌
8. 附加一份經簽署的觀察記錄 → 處理任何排程中的附件
9. 處理任何排程中的附件 → 附上下載結果

授權、存取來源、運作中的收集器以及完整傳輸是 不同的問題。成功登入並不代表能存取每個群組。 已連線的傳輸通道並不能證明所有相關更新均已送達。

## 監測範圍：指定聊天室、特定資料夾或整個帳戶

來源 → **監測範圍**決定了工作區將記錄哪些聊天內容。

| 模式 | 記錄 | 新對話 |
| --- | --- | --- |
| 選定的聊天室（預設） | 僅限您手動新增的聊天紀錄 | 絕不會自動新增 |
| Telegram 資料夾 | 某個帳戶資料夾中的對話：包含按名稱列出的對話，加上該資料夾的分類（聯絡人、非聯絡人、群組、頻道、機器人），減去被排除的對話，以及（若資料夾有此設定）已歸檔的對話 | 符合條件的聊天記錄一經啟動即會被加入；您在 Telegram 中加入該資料夾的聊天記錄，將於一小時內被擷取 |
| 完整說明 | 該帳號所見的每則聊天紀錄 | 每當有新的聊天室、群組、私人聊天或機器人出現，只要其首次更新一到，便會立即被加入系統 |

- **來源類型**（頻道、群組、私人聊天、機器人）會進一步限定「資料夾」及 「整個帳戶」模式的範圍。所選的聊天內容可為任何類型，包括私人聊天和機器人。
- **被排除的聊天室**在任何模式下均不會被記錄。在「資料夾」及「整個帳戶」模式下， 若對來源進行*「排除」*或*「移除」*操作，該來源便會被加入此清單，因此範圍設定不會再次將其納入。 若再次手動選取該聊天室（在「來源」或「聊天室」中），該聊天室即會從清單中移除。此清單 最多可容納 5,000 個聊天室；超過此限時，*「移除」*操作將被拒絕，此時可改為暫停該聊天室。
- **自身操作**（預設為開啟）：此帳號發送的訊息、其編輯紀錄以及 回覆鍵盤按鍵的按壓紀錄。若關閉此功能，外發訊息與編輯紀錄將被跳過。
- 切換至特定資料夾或整個帳戶時會要求確認：這些模式會記錄 私人聊天內容及第三方訊息，僅應配置於專用帳戶中。 該確認操作及每次範圍變更皆會產生經`scope.changed`簽名的記錄。
- 透過範圍新增的聊天室會以標記為*「自動」*的來源顯示，並記錄為 `scope.applied` （在開始時及每小時）或 `source.discovered`（監測期間出現的新聊天室）。切換回 已選定的聊天室時，所有自動新增的來源都會暫停。

這些模式無法做到的事：

- **秘密聊天**在兩台裝置之間採用端對端加密，無論在何種模式下， 皆不會傳送至 TgWitness。
- **當 TgWitness 未運行時，將不會進行任何記錄。**重新啟動後，它會向 Telegram 查詢遺漏的更新並重新檢查聊天記錄，但若發生長時間 中斷，Telegram 並不會回傳所有資料。報告及 `verify.py` 會將此類期間標示為資料缺口（參見[覆蓋範圍](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/evidence/#coverage-continuity-gaps-and-unobserved-ids)）。
- 初始僅列出前 1,000 則對話（上限設定於**「參數」**中）；較舊的 對話將於下次變得活躍時被加入。已加入對話的早期歷史紀錄不會被擷取——如有需要，請自行 擷取歷史快照或匯出完整對話紀錄。
- 不會套用那些隨時變動的資料夾條件（如靜音、已讀）：此類聊天室 仍會持續被監控。
- 在另一款應用程式中按下的**內嵌（回呼）機器人按鈕**，對第二個 會話而言是不可見的；機器人的回覆或編輯內容會被記錄下來。回覆鍵盤按鍵操作會以發送中的 訊息形式傳送，並標記為 `button_press`。
- 聊天數量越多，發送請求的次數就越多。Telegram 會針對其認為 過量的訊息量限制帳號，這正是使用專用帳號的另一個理由。

## 範圍與事件篩選

每個工作區都有其專屬的來源。TgWitness 不會加入群組、接受 邀請，也不會自動清點所有成員。來源必須是該帳號 已可存取的。 啟動時，收集器會將選定的來源 與該帳號可見的對話進行比對；除非在「 **參數 → 從帳號清單讀取的對話」**中另有指定，否則將檢查前 1,000 則對話。 若來源缺失，將標記為**「存取未確認**」，而非假設該來源已將您移除。

| 設定 | 收集 | 停用時的效果 |
| --- | --- | --- |
| 新訊息 | 一般已傳送訊息 | 後續的編輯／刪除操作可能缺乏先前已擷取的文字內容供比對。 |
| 編輯 | 提供經編輯的訊息版本 | 中間的變更內容日後不會被重建。 |
| 刪除記錄 | 範圍限定之刪除通知與非範圍限定之帳戶層級通知 | 刪除通知不會被加入日誌中。 |
| 反應 | 即時反應快照 | 不會另行新增反應更新。 |
| 會員 | 已發送會員服務訊息及參與者最新動態 | 上述會員觀察內容並未被納入。 |

設定將套用至工作區中所有已選取的來源。儲存表單以套用 變更；變更內容將連同簽署的「變更前」與「變更後」數值一併記錄。停用某個類別 並不會刪除較早的記錄。重新啟用該類別也不會補回遺漏的更新。

操作記錄及其他群組服務事件與這些 設定開關無關。當會員功能啟用時，會員服務訊息仍會產生訊息記錄， 即使一般的新訊息擷取功能已停用。擷取的 Telegram 物件會保留內嵌的元資料；設定開關並非內容遮蔽規則。

**私人聊天室和一般群組中的刪除記錄會以**訊息 ID 的形式呈現，不附帶聊天室資訊。 這些聊天室共用一套帳戶層級的訊息 ID 序列，因此當帶有該 ID 的訊息 先前已被儲存時，其所屬的聊天室便已知曉：刪除記錄將被記錄在該聊天室中， `chat_resolution` 解釋了具體機制。 從未被儲存的 ID 將被視為**範圍未定的刪除**，其 來源明確標示為未知；收集器不會進行推測。Telegram 從不透露是誰刪除了 訊息；當被刪除的訊息是由該帳號發送時，紀錄會如實標示 （`deleted_message_was_outgoing`），但不會指名刪除者。

## 自身行動

被監測帳號發送的訊息會標記為 `outgoing`。關於外發 訊息的編輯說明指出：在私人聊天室和群組中，僅發送者本人可進行編輯；而頻道 貼文則可由其他管理員進行編輯。 當發送的訊息重複了該聊天室中 最新儲存的回覆鍵盤上某個按鈕的文字時，該訊息會標示為 `button_press`，並附有 該鍵盤記錄的連結。

「排除自身操作」的原則同樣適用於背景重新檢查及自動新增的聊天記錄。 被跳過的發送訊息會使重新檢查的位置向前推移，以避免阻擋後續收到的 訊息。明確的面板操作以及手動請求的聊天記錄快照仍會被記錄下來。

## 調查模式：加入群組並與機器人對話

**來源 → 監測範圍 → 調查**模式會為專用 帳戶設定監測範圍，該帳戶將加入群組聊天、啟動聊天機器人並向其發送訊息：涵蓋整個帳戶、所有 來源類型、自身操作，以及每個出現的群組聊天或聊天機器人的檔案及其最新 200 則可見訊息。 檢視表單並按下「**儲存範圍」**；切換至整個 帳戶時，系統會要求進行慣常的確認。

- **按鈕。**訊息下方的按鈕會與該訊息一併保留，並顯示於「**聊天」**中：連結、網頁 應用程式、登入連結、待複製的文字、回呼資料、內嵌查詢，以及要求提供電話 號碼或位置的請求。 連結以文字形式顯示，且絕不會由面板自動開啟。當機器人 僅變更按鈕內容（例如新的付款連結）時，無論是 即時更新或重新檢查，這都將被視為該訊息的新版本。
- **新聊天室與機器人。**在「資料夾模式」及「整個帳戶模式」下，**當新的聊天室或機器人 出現時**，系統會於其出現的瞬間立即儲存：

  - 其作為 `source.profile` 記錄的檔案：機器人說明與指令、 使用者、群組或頻道的簡介文字、成員名單，以及當 Telegram 提供 時所顯示的關聯聊天室與邀請連結；
  - 其最新的可見訊息（最多 1,000 則）將作為標記為 `new_chat` 的歷史快照： 剛加入的團隊聊天室中的較早訊息，或是觀察者 注意到該聊天室之前，機器人所發的訊息。已即時儲存的訊息不會重複記錄。

  啟用此模式時，清單中已存在的聊天室將直接加入，且不包含快照。 若觸發 FloodWait，此作業將暫停，並於之後恢復；失敗情況會被記錄，而 該聊天室的即時記錄則會持續進行。 - **依需求儲存設定檔。在「聊天」→「設定檔」→「儲存設定檔」中，可**儲存任何來源的當前設定檔； 最新設定檔會顯示在訊息上方。 - **不可見。**在其他 Telegram 應用程式中按下的內嵌（回呼）按鈕、 機器人對此類按壓所作出的彈出視窗或連結，以及在其他應用程式中使用的邀請連結，均不會傳送至 TgWitness。但機器人隨後發送或編輯的內容仍會被記錄。

### 從面板執行操作

**「聊天」**功能現已包含一個迷你客戶端，該客戶端使用所選工作區的 Telegram 帳戶：

- 撰寫純文字訊息，或在已儲存的訊息下方選擇**「回覆」**。即使設定範圍排除外發更新，系統仍會記錄回傳的外發 訊息。
- 按下當前回調按鈕或文字按鈕下方的**「Press」按鈕**。若鍵盤輸入內容與儲存版本不符，伺服器將再次擷取 該訊息並拒絕執行此動作。 回調收據會保留 Telegram 的彈出文字、警示標記及網址；回覆內容亦會顯示 於對話下方。網址仍為可選取的文字，且不會自動開啟。
- 展開「**開啟 Telegram 連結**」，輸入 `@username`、公開的 `https://t.me/name` 連結、 `https://t.me/+invite` / `joinchat/invite`，或帶有 `?start=parameter` 的機器人連結，然後按下 **「儲存預覽」**。在加入前，原始連結與 Telegram 的預覽皆已簽名。 **加入／開啟並觀察**後，系統會加入該群組／頻道或開啟該用戶／機器人，將該 聊天視為已啟用的來源，並將 `/start` 連同其啟動參數一併傳送給機器人。 待管理員批准的加入請求將被記錄為「待處理」，而非「成員資格」。

啟用「**開始監測**」功能，即可即時擷取收到的回覆。當監測暫停時，面板操作仍可進行， 但此時僅能保證其直接回覆內容會被保存。 當監測正在執行時，新增的來源會使用已設定的設定檔／歷史紀錄匯入方式。 當來源處於暫停狀態時，請先在**「來源」**中啟用該來源，再進行傳送或按下其按鈕。

`interaction.preview`、`interaction.requested` 和 `interaction.result` 是證據匯出中包含的普通簽名 日誌事件。請求會標識帳戶、訊息／按鈕 或預覽記錄，並標示監測是否正在運行。回執則區分成功、 拒絕、待核准及未知結果。中斷的請求可能已傳送至 Telegram：在執行新操作前請先檢查聊天記錄。 重複使用請求 ID 可檢索其 已儲存的收據，而無需重複執行該動作，包括重新啟動後亦然。當在當前頁面會話中針對同一動作收到模稜兩可的回應時，控制面板會保留該 ID。 此外，當成功執行動作後刷新視圖失敗時，控制面板也會保留該 ID：收據 仍會保持可見，再次點擊即可檢索該收據。 回呼與加入 RPC 僅有一次 嘗試機會；可重試的讀取操作則會保留其設定的重試政策。立即切換聊天室 會立即清除草稿與回覆對象，並停用傳送功能，直至新對話載入為止。

此迷你客戶端可處理文字及回呼按鈕。網頁應用程式、登入／電話號碼／位置請求、 付款、內嵌查詢及附件仍需透過 Telegram 客戶端處理；其儲存的按鈕 元資料仍可被檢視。新的控制項採用英文文字。

## 重新檢查等級

重新檢查功能會再次向 Telegram 查詢遺漏的訊息、編輯紀錄以及該平台不再回傳的訊息。 標有星號的來源為**優先**來源，預設每 15 分鐘重新檢查一次； 其餘來源則每 6 小時重新檢查一次。選定的聊天室預設為優先來源，透過 資料夾或整個帳戶新增的聊天室則為一般來源。 每次循環最多重新檢查 30 個來源， 其餘來源則等待下一分鐘；重新連線後，優先來源將優先處理。兩者 的間隔時間皆可於「來源」→「記錄設定」→「重新檢查」中設定（0 表示關閉該層級），並 以「`recheck.changed`」形式記錄。

遺漏的訊息將從上次處理中斷處開始向上擷取，每次處理最多擷取「 **參數 → 每次重新檢查的新訊息數**」（預設為 1,000 則）。 因此，經過長時間中斷後， 重新檢查將填補整個空缺，即使比該空缺更新的即時訊息已被優先儲存 亦然。仍在補齊資料的聊天室將於下一分鐘再次進行重新檢查，而非 等待其層級間隔；`recheck.completed` 將顯示 `continues_after`，直至完成為止。

比對項目包含訊息文字、實體、鍵盤輸入（包括刪除紀錄）以及附件 內容／識別資訊。 僅變更檔案存取雜湊值或檔案參照本身並不構成 編輯，Telegram 自動填入的內容亦不構成編輯：例如連結預覽載入、故事瀏覽次數、由該帳號解鎖的付費 媒體，以及發票收據。聊天記錄中的每個儲存版本皆連結至其完整的日誌記錄，包含媒體元資料。

## 訊息歷史紀錄與來源標示

假設收集器先觀察到「10:00 會議」，隨後看到「11:00 會議」， 接著收到刪除通知。系統會將這三項不同的觀察結果追加至日誌中： 原始文字保留不變，編輯後的內容作為獨立版本，而通知則記錄了 已觀察到刪除操作。

若資料蒐集是在首個版本消失後才開始，則該內容將無法取得。 若在離線期間發生多次編輯，僅能儲存後續觀察到的 版本。刪除通知無法恢復從未被擷取的內容。

訊息發送者不必然等同於編輯者。Telegram 通常不會 提供刪除訊息者的身分或確切刪除時間。身分不明的行為者 仍將保持匿名。反應快照與參與者更新僅包含 Telegram 向該帳號顯示的計數及身分資訊。

序號表示觀察順序。收集器的 UTC 時間戳記即為其 本地時間；若提供 Telegram 來源的時間戳記，則會另行儲存。 兩者均非獨立的可信時間戳記。

## 歷史快照

快照功能會從已啟用的來源擷取最新的可見訊息，每次請求最多 500 則。結果會標記為「歷史觀察紀錄」。這些紀錄可能與 即時擷取內容重疊，而重複的觀察紀錄將作為獨立記錄保存。

快照遵循附件政策，但與即時事件切換機制相互獨立。 它們不會還原已刪除的訊息或遺漏的中間版本。您可以在 暫停狀態下請求快照；任何排入佇列的附件將等待至觀察開始 且下載工作程序執行時才會處理。

## 附件處理

附件下載功能預設為啟用狀態，當可用磁碟空間低於 1 GiB 時會暫停下載。收集器會將 訊息監測與下載任務一併提交。該任務會保留原始媒體 描述符及大小政策，因此後續經編輯的附件不會被悄然替換。

下載作業於訊息擷取後執行。下載完成後將產生一個包含 SHA-256 值與位元組數的 `media.saved` 記錄。被跳過、失敗、重試及中斷的 作業將產生不同的結果。排入佇列的任務並不代表該檔案已成功保存。 完成的檔案還必須與原始觀察到的附件 描述符中的位元組數相符。若回應過短或出乎意料地過長，則不會被記錄為已保存的媒體。

**各類型皆**設有儲存限制：照片、影片、GIF 及動畫、圓形影片訊息、 語音訊息、音樂與音訊、貼圖，以及檔案。 每種類型均可關閉，並設有 各自的容量限制（範圍為 1 至 2,000 MiB）；新工作區預設值為：照片 20 MiB、 影片 100 MiB、檔案、音訊及圓形影片 50 MiB、語音與 GIF 20 MiB，以及 貼圖為 5 MiB。設定*最大檔案大小*將同時套用至所有類型。在 按類型設定限制之前儲存的政策，將維持其針對每種類型的單一限制。停用某種類型會產生 一個 `media.skipped` 記錄；未知大小或超大檔案將不會被下載。 大型檔案的 下載速度至少為 256 KiB/s。任務在系統重啟後仍會保留，但過期的參考、喪失 存取權限或已刪除的檔案仍可能導致無法恢復。現有任務將保留與其一同儲存的 政策。

## 暫停、鎖定、斷開連接及重新啟動

| 動作或狀態 | 效果 |
| --- | --- |
| 切換工作區 | 變更面板檢視；其他收集器將維持其狀態。 |
| 鎖定面板或關閉分頁 | 讓伺服器與監測功能持續運作。 |
| 暫停觀察 | 停止該收集器並保留排程中的附件處理工作。 |
| 停用來源 | 停止未來的範圍內擷取；當此功能停用時，相關的排程媒體處理任務將處於等待狀態。 |
| 移除來源 | 系統會將其視為來源並刪除其使用者檔案；已儲存的記錄仍保留在僅可追加的日誌中。尚待處理的附件則會被記錄為失敗（`source_removed`）。在資料夾模式與整個帳戶模式下，該附件亦會被排除在外。 |
| 變更連線路徑 | 需暫停運作，關閉舊版客戶端，並取消未完成的登入程序。 |
| 停止 Python 程序 | 停止所有工作區；離線期間不會進行任何監測。 |
| 主動監測結束後重新啟動 | 嘗試使用已儲存的會話來恢復先前儲存的範圍。若手動暫停，則會清除該意圖。 |

此收集器會記錄偵測到的連線中斷、重試、錯誤、啟動／停止，以及 心跳訊號。短暫的中斷可能因週期性的連線檢查而未被偵測到。 重新啟動後，系統會從儲存的更新位置請求遺漏的更新，並 定期重新檢查已監控的聊天室；詳見[證據格式](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/evidence/#durable-collection-and-process-receipts-02)。快照僅提供背景資訊； 並不能證明資料缺口已修復。

## 帳戶隔離與驗證

每個工作區皆擁有專屬的日誌、授權、簽署金鑰、政策及佇列。 僅其活躍的客戶端可貢獻即時觀察記錄。遭拒絕、待處理、 已被取代以及進行連線測試的客戶端，均無法將即時更新寫入其日誌。 不同帳戶可觀察同一群組，但其日誌仍保持獨立。

每個事件皆包含前一個雜湊值及 Ed25519 簽名。匯出內容涵蓋 整個工作區日誌，並透過固定序列號進行標記。面板篩選器不會過濾 匯出內容；在匯出檔案準備期間，資料蒐集可能持續進行至其邊界之外。

**「驗證日誌」**會透過顯示的 邊界檢查事件鏈與簽名。當工作區變更時，其結果將被清除，而面板會標示 檢查後新增的記錄。ZIP 匯出功能亦會驗證所收集的媒體檔案。

有效的簽名是針對可信密鑰的完整性進行驗證，而非針對 Telegram 的來源或內容真實性。請獨立保留指紋與檢查點。請參閱 [證據模型](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/evidence/)、[日常運作](https://phishdestroy.github.io/TgWitness/zh-Hant/docs/reference/operations/)流程及 [即時驗收程序](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md)，以了解信任與交付要求。