Telegram · 「案件看板」參考說明

TgWitness / 文件說明 · 調查

「案件看板」為調查團隊提供一個可共享的儲存資料工作視圖。您可以將 觀察結果加入書籤、標示特定段落、儲存一系列操作，並與同事進行討論。 卡片會保留其來源參考資訊及經簽署的修訂歷史紀錄。團隊註解會保留在 工作區中，並可與原始的 Telegram 觀察結果明確區分。

證據模型 · 存取 · 報告

本頁內容

• 處理個案
• 權限
• 儲存的合約
• API 與匯出功能
• 運作限制

處理案件#

開啟「調查」→「案件看板」，並選擇「標準」或「專家」模式。介面語言將隨選定的模式而定。 在日誌記錄或已儲存的聊天訊息旁點擊「加入案板」，或將其設為焦點後按下 B 鍵。 點擊一次即可將書籤新增至「收件匣」。編輯其標題、標籤和備註，或將其移至 收藏集。修改後的卡片會附加經簽名的修訂版本；刪除時將保留歷史紀錄。

針對首個案件，請選擇一個蒐集集，並加入能回答某個問題的紀錄。使用「註解」 功能檢視詮釋內容，接著使用「簡報」功能逐步瀏覽卡片及來源背景。 在「報告工作室」中準備 交付成果時，請另行選擇「案件看板」的素材。儲存切片並不會自動設定報告的資料篩選條件。

在已儲存的聊天訊息中選取文字，即可顯示「標示 → 看板」選項。選擇顏色並 新增註解。伺服器會核對精確的引文及儲存版本，包括表情符號、從右至左（RTL）文字及 組合符號。介面不會將選取範圍映射至經過遮罩或轉換的文字上。

在單一聊天中按住 Shift 鍵點擊兩筆記錄，即可執行「切片」功能；亦可使用「按時間切片」，或儲存 日誌中當前的聊天、時間段及事件類型篩選條件。已儲存的切片具有其專屬的 權威性條件：在日誌中開啟該切片時，亦會套用多重聊天、訊息數量限制及參與者 篩選條件。 「顯示自書籤新增的記錄」功能可隔離後續新增的內容。變更 Journal 篩選條件將退出該切片。在「人員」中，使用「切片此人的操作」會採用記錄中的行為者 ID； 該功能不會假設訊息作者曾編輯、刪除或對訊息做出反應。

「切片」對話方塊會在允許建立前預覽計數。「all」涵蓋所有已記錄的類型， 包括快照、編輯、刪除、反應、成員資格／服務更新、自身操作、 按鈕、媒體結果、已恢復訊息及未來事件類型。此選項描述 已儲存的觀察結果。 「未知聊天室」刪除通知屬於獨立的上下文， 僅限擁有整個工作區存取權限的使用者查看，絕不會歸因於所選的任何聊天室。

各「集合」皆有明定之聊天室範圍。若範圍為空，則代表整個工作區。一個集合 不得包含其範圍外的卡片；受聊天室限制的參與者無法閱讀範圍更廣的 集合。「收件匣」是存放未指派卡片的虛擬集合。 搜尋與篩選功能僅涵蓋可見 的卡片；討論串和提及會繼承父卡片的存取權限。已刪除的留言會在 討論區中留下「墓碑」標記。系統不會記錄瀏覽歷史紀錄。

「簡報」模式會開啟所選收藏集中的所有卡片，並提供「卡片」、「來源背景」及「團隊 評論」檢視畫面，以及鍵盤上的「上一則/下一則」控制鍵。此模式不提供任何編輯控制功能。一般 動態消息採用分頁顯示；「簡報」模式會以頁面為單位載入清單，並每次僅擷取一張卡片的詳細資訊。

權限#

所有操作均需具備 view、工作區／聊天範圍及 board.read 權限。board.write 可新增卡片、 留言、移動以及開啟／審查狀態。board.manage 允許進行資料集管理、 確認／駁回狀態，以及修改／移除他人卡片。狀態是團隊 的決策，而非加密驗證結果。

存取表單預設值：審閱者 = 讀取；分析師 = 讀取/寫入；操作員 = 讀取/寫入/管理， 此外還包含其現有權限。現有授權不會自動取得新權限。 主要管理員擁有所有權限，並以「主要管理員」身分發佈內容。請使用命名授權 進行權限歸屬。提及清單僅列出目前能夠閱讀完整父卡片內容的存取者。

針對聊天室 A 的授權，即使透過猜測其 ID 或提供 錯誤的 target.chat_id，亦無法取得 A+B 的卡片或片段。目標元資料是根據伺服器上的簽名事件雜湊值解析而來。 在回覆前，會先過濾收集項目、討論次數、相關卡片及即時通知。 匯出操作需同時具備 export 及 board.read 權限；若現有匯出者無看板存取權限，則僅能 取得不含團隊筆記的普通證據檔案。SSE 會在每次批次處理前重新檢查當前的授權狀態。

儲存的合約#

與觀察記錄類似，註解會以事務性方式寫入工作區中一個僅支援追加的 SQLite 資料表。 annotations.jsonl 即是從與 events.jsonl 相同的讀取快照所產生的精確標準化匯出檔。 不存在第二個相互競爭的註解儲存庫，亦無 board.activity 日誌事件。

每行內容必須精確包含：

{
  "seq": 1,
  "at": "2026-11-02T14:00:00.000+00:00",
  "access_id": "admin",
  "access_label": "Main administrator",
  "kind": "board.bookmark",
  "payload": {"id": "32 lowercase hex digits", "target": {"event_hash": "64 lowercase hex digits"}},
  "previous_hash": "64 zeroes for the first record",
  "hash": "SHA-256 described below",
  "signature": "base64 Ed25519 signature"
}

上述簡化範例展示的是封套結構；實際載荷包含其模型 預設值及由伺服器解析的目標欄位。API 請求架構位於 tgwitness/schemas 目錄下，由 python tools/build_board_schemas.py 透過運行時 Pydantic 模型生成。額外的請求欄位將被拒絕。若未提供 ID，則由 伺服器端自動生成。 呼叫方無法提供 作者、時間、快照及簽名。命名授權 ID 遵循 Access 現有的 16 位元組十六進位格式；卡片 ID 則為 32 位元組十六進位。

規範 JSON 格式為 UTF-8，物件鍵值依序排序，標記之間無空白，Unicode 未經轉義， 且不含 NaN 或無窮大值。註解雜湊值為包含 format: "tgwitness-annotations-v1" 以及所有七個信封欄位（至 previous_hash 為止）之規範物件的 SHA-256 雜湊值。 此格式標籤將其雜湊域與觀察結果區隔開來。 簽名採用 Ed25519 演算法，基於 32 位元組的原始雜湊值。序列從 1 開始。修訂版本保留卡片 ID，並在 `supersedes` 欄位中標明前一版 註解雜湊值；其無法變更聊天範圍。移動、狀態變更及刪除均為 獨立的記錄。SQLite 資料表不接受 UPDATE 和 DELETE 指令。

case-board.json 包含 {statement, signature}。規範陳述由 工作區金鑰簽署，並包含 format: "tgwitness-case-board-v1"、public_key、created_at、 journal_head、meaning 及 state。狀態為確定性重播：annotations_head、一個 有序的 items 陣列（包含集合、卡片、註解及墳碑），以及 status_history。 各項目在各修訂版本間均保留其最後一次註解雜湊值、序列號、作者與時間，以及原始 建立者與建立時間。重播機制會檢查修訂版本、 父項目、集合參照及重複的操作 ID。manifest.json 與新的檢查點 亦會綁定 annotations_head。應獨立保留檢查點，以偵測資料遭截斷或 使用複製的簽名金鑰進行改寫的情況。

文字版本#

range.start 為以零為起點的 Unicode 碼點偏移量，length 為正數的碼點計數， 而 quote 必須與目標事件中 payload.text 或 payload.caption 的精確子字串完全相符。 不套用 NFC/NFKC、大小寫轉換或字元規範化。 Python 字串切片與 JavaScript 的 `Array.from(text)` 實作相同的索引機制。標記與 ZWJ 表情符號的組合可能 佔用多個碼點。`range.version` 是指目標事件的雜湊值，而非當前訊息 版本或 Telegram 的 UTF-16 實體偏移量。後續編輯絕不會自動重新定位標示範圍。

切片識別碼與時間#

query 函式僅接受一個 chat_id 或非空的 chat_ids 參數，可選的包含起始點 from/to、 包含訊息 ID 範圍（僅限單一聊天室）、kinds: "all" 或精確/前綴通配符類別、 明確的 actors、search、hide_system 及 include_unscoped。日誌類別群組將展開為 其確切的謂詞。 搜尋使用日誌的 NFC／不區分大小寫的載荷搜尋，且不會變更 已簽名的來源文字。日期需指定時區，並歸一化為 UTC。 日期會過濾 observed_at。Telegram 的 source_at 會另行顯示。若刪除操作未 包含來源時間戳記，則不會生成虛構的刪除時間。在時間區間外觀察到的遲發記錄 不會被納入該區間；針對特定訊息 ID 的訊息 ID 區段，可能包含這些訊息 ID 的較晚刪除記錄。

快照（snapshot）會鎖定建立時間、日誌序列/雜湊邊界、匹配計數、首/末 序列以及 result_hash。後者是按字典順序排序的匹配 事件雜湊值所構成的 UTF-8 規範 JSON 陣列之 SHA-256 雜湊值，若切片為空則包含 []。 它還包含確切的 類型計數，以及一個 24 區間的觀察時間微型資料。一個切片儲存的是查詢，而非重複的來源 記錄。在匯出時，board/slices/<id>.json 會列出當前的雜湊值以及新增／移除的序列。 驗證器會先在建立邊界處重建原始結果，然後重建當前結果。 新增的記錄會以變更事實的形式報告。移除原始事件會中斷不可變的 證據鏈；此操作不會被默默接受為從切片中進行的普通移除。

反應快照中的近期參與者清單不完整。探索器會比較同一則聊天/訊息的相鄰快照 （包括切片範圍外的先前快照），並報告各觀察結果之間的 總計數差異。若近期參與者缺失，並不表示該反應已被移除。 第一個快照沒有推斷出的較早狀態。參與者的觀察結果仍歸屬於 其被提供的快照，而非某個虛構的動作時間。

API 與匯出功能#

GET /api/board 接受 collection/chat/author/label/state/from/to/q/kind/comments、offset/limit 以及 newest/oldest 排序參數。GET /api/board/card/{id} 會傳回卡片、來源預覽、對話串、 狀態歷史紀錄及相關卡片。參與者子路徑會傳回符合條件的提及選項。 POST /api/board/{bookmark|highlight|slice|collection|comment|status|move|remove} 會追加一筆記錄。 POST /api/board/slice-preview 會計算查詢結果。切片記錄會透過 GET /api/board/slice/{id}/records 進行分頁；重新計算時始終使用當前的穩定讀取快照。 即時 /api/stream 會發送不含有效載荷的 board 通知，此功能與日誌游標獨立運作。

GET /api/board/export 會傳回一份經簽署的文件。受聊天室限制的存取權限將收到一份標示清晰的 經簽署的披露文件，絕不會包含其他聊天室的註解或完整對話鏈。完整的證據 ZIP 檔案 包含 annotations.jsonl、經簽署的 case-board.json 以及切片 JSON 附錄。 HTML/PDF/JSON 報告 設定可選擇「無看板」、「不含討論的書籤／片段」，或「附有評論的卡片」。該 區段會明確區分團隊意見與觀察結果。報告資料篩選器亦會限制 可讀取的筆記內容；證據 ZIP 檔中的完整簽名來源檔案則保持完整。

GET /api/board/slice/{id}/export 會產生一個經過簽名的 tgwitness-board-selection-v1 JSON 摘錄； ?format=csv 會產生一個方便使用的表格，但不包含獨立的簽名。請保留 JSON 和 ZIP 檔案：

python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_KEY_SHA256 --board
python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256
python -m tgwitness.verify case-board.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256

選取檢查會驗證簽名陳述、精確的來源記錄，以及 其在指定邊界處查詢的完整性。證據 ZIP 檔可能較新，但必須包含該 前綴。若目標懸空，系統會明確報告。若原始切片快照不同、註解 遭變更、重播狀態不匹配或來源變更，則檢查將失敗。 未附註解的舊存檔 將保留其現有的驗證行為。

移交預設為「不包含」。 明確包含設定會透過已 簡化的記錄顯示專案卡片，省略無法存取／被省略的目標，隱藏來源文字 已被簡化的重點標記，並依照相同的提及／聯絡規則清理團隊文字，同時可選擇性地將 元資料及筆記中已知出現的調查員標籤替換為 R01、R02…等標記。 不會披露原始的 annotations.jsonl 檔案。經簽名的 tgwitness-case-board-handover-v1 附檔與報告 均包含相同的最小化內容。切片計數僅描述已披露的記錄，原始 快照／查詢行為者詳情則不予披露。 對於最小化處理程式未知的自由文字名稱，仍需 進行審查，此與一般移交程序相同。此衍生版本並不聲稱在遮蔽處理後能保留原始 註解簽名。

操作限制#

參數包含 10,000 張卡片與 50,000 則留言的軟性限制、最多 5,000 筆記錄的切片頁面，以及媒體預覽控制。達到軟性限制時會發出警告，但不會刪除歷史紀錄。 動態消息頁面 最多顯示 200 張卡片。獨立 JSON 片段摘錄上限為 64 MiB；若需處理較大資料，請縮小查詢範圍或使用 簽名 ZIP 檔案。獨立驗證器將註解重播上限設定為 256 MiB。 Case Board 未啟用亦未實作任何外部評論通知功能。

此功能的自動化驗收流程會使用虛構資料及模擬的 Telegram 傳輸管道來 檢查儲存、存取、渲染及匯出功能。有關證據檢查的範圍，請參閱驗證範圍 。