TgWitness / 文档

已测试的内容 →

本页面部分内容仍为英文:英文原文在翻译后发生了变更。

参考 / 存档与集成

Telegram · 命令行

支持通过脚本和代理进行搜索、阅读上下文、统计活动以及导出已保存的消息,提供 --json 输出格式、稳定的退出代码以及作用域限定的只读令牌。

TgWitness / 文档

存档集成

只读 MCP · 全文搜索 · 维基

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 次,且可随时撤销或 轮换。Panel 登录令牌和 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 及已保存的媒体 记录)生成一个 JSON 对象,并按日志顺序排列。每行与其他结果具有相同的字段,包含 完整文本。若启用 --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 两项功能均可使用。