数据采集原理

TgWitness 记录已连接的 Telegram 账户所观察到的内容。该日志保存 这些观察结果、其时间顺序以及随附的上下文信息。它不会 根据缺失的消息或账户处于连接状态的情况，推断出未被观察到的操作。

从登录到日志#

图表转为文本

1. 授权用户账户 → 选择可访问的群组和频道
2. 选择可访问的群组和频道 → 保存事件和附件设置
3. 保存事件和附件设置 → 开始监控
4. 开始监控 → 接收来自活跃客户端的更新
5. 接收来自活跃客户端的更新 → 应用来源与事件政策
6. 应用来源与事件政策 → 追加一份经过签名的观察记录
7. 追加一份经过签名的观察记录 → 查看或导出日志
8. 追加一份经过签名的观察记录 → 处理队列中的任何附件
9. 处理队列中的任何附件 → 附上下载结果

授权、访问数据源、运行中的采集器以及完整交付是 三个不同的问题。登录成功并不意味着可以访问所有群组。 传输连接成功并不意味着所有相关更新都已送达。

监控范围：选定的聊天群组、某个文件夹或整个账户#

来源 → 监控范围决定了工作区将记录哪些聊天记录。

• 消息来源类型（频道、群组、私聊、机器人）可进一步细化文件夹和 整个账户模式。所选聊天可为任意类型，包括私聊和机器人。
• 被排除的聊天室在任何模式下均不会被记录。在文件夹模式和整个账户模式下， 对源聊天室执行“排除”或“移除”操作会将其加入此列表，因此范围设置不会再次将其纳入。 若手动再次选择该聊天（在“来源”或“聊天”中），则将其从列表中移除。该列表 最多可容纳 5,000 个聊天；超过此限时，“移除”操作将被拒绝，但可选择暂停该聊天。
• 自身操作（默认开启）：该账户发送的消息、其编辑操作以及 回复键盘的按键操作。关闭后，将跳过外发消息和编辑操作。
• 切换到某个文件夹或整个账户时会要求确认：这些模式会记录 私人聊天和第三方消息，仅应用于专用账户。 确认操作及每次范围变更都会生成经过scope.changed签名的记录。
• 通过范围添加的聊天记录将显示为标记为“auto”的来源，记录格式为 scope.applied （在开始时及每小时）或 source.discovered（监控期间的新聊天）。切换回 选定的聊天记录将暂停所有自动添加的来源。

以下情况不适用：

• 秘密聊天在两台设备之间采用端到端加密，无论在何种模式下， 均不会被 TgWitness 获取。
• 当 TgWitness 未运行时，不会进行任何记录。重启后，它会向 Telegram 查询遗漏的更新并重新检查聊天记录，但在长时间 中断后，Telegram 无法返回所有数据。报告和 verify.py 会将此类时段显示为数据缺口（参见覆盖范围）。
• 初始仅列出前 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 的弹出文本、提醒标记和 URL；回复内容也会显示 在对话下方。URL 仍为可选中文本，不会自动打开。
• 展开“打开 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 仅允许一次 尝试；可重试的读取操作将保留其配置的重试策略。立即切换聊天 会立即清除草稿和回复目标，并禁用发送功能，直到新对话加载完毕。

此迷你客户端支持文本和回调按钮。Web 应用、登录/手机号/位置请求、 支付、内联查询和附件仍需 Telegram 客户端；其保存的按钮 元数据仍可见。新控件使用英文文本。

重新核对分级#

重新检查功能会再次向 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。任务在系统重启后仍会保留，但过期的引用、丢失的 访问权限或已删除的文件仍可能导致无法恢复。现有任务将保留与其一同保存的 策略。

暂停、锁定、断开连接和重启#

该采集器会记录检测到的断开连接、重试、错误、启动/停止以及 心跳信号。短暂的中断可能会被周期性的连通性检查忽略。 重启后，系统将从保存的更新位置请求遗漏的更新，并 定期重新检查已监控的聊天记录；详见证据格式。快照仅提供上下文信息； 它并不能证明数据缺口已得到修复。

账户隔离与验证#

每个工作区都有独立的日志、授权、签名密钥、策略和队列。 只有其活跃客户端才能提交实时观察记录。被拒绝、待处理、 被取代以及连接测试状态的客户端均无法将实时更新写入其日志。 不同账户可以观察同一个群组，但各自的日志仍保持独立。

每个事件都包含前一个哈希值和一个 Ed25519 签名。导出内容涵盖 整个工作区日志，并通过固定序列号进行标识。面板过滤器不会过滤 导出内容；在导出准备期间，数据收集可能仍会超出其边界继续进行。

“验证日志”功能会通过显示的 边界检查事件链和签名。当工作区发生变化时，其结果将被清空，面板会标识 检查后新增的记录。ZIP导出功能还会对收集的媒体文件进行验证。

有效的签名是基于可信密钥来验证数据的完整性，而非基于 Telegram 的来源或内容的真实性。请独立保留指纹和检查点。有关信任和交付要求，请参阅 证据模型、日常操作以及 实时接纳流程。