# Telegram · 命令行

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/cli/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

Translation coverage: this edition includes material from the English original.

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![存档集成](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

[只读 MCP](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/) · [全文搜索](https://phishdestroy.io/tgwitness/zh/docs/reference/search/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**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](https://phishdestroy.io/tgwitness/zh/docs/reference/cli/#index-and-backup)) 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` （[语法](https://phishdestroy.io/tgwitness/zh/docs/reference/search/#search-syntax)） |
| `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](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records.

## 代理技能

[`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) 向特工说明如何使用这些命令、如何引用记录以及如何处理 捕获的文本。从 `.agents/skills` 需从代码库检出 该文件。对于 Claude Code，请复制 `tgwitness-cli` 文件夹复制到 `.claude/skills/` 项目中的 或 `~/.claude/skills/`.

## MCP 和命令行

两者均使用相同的连接、范围检查和限制。MCP 的结果限制为 一个 64 KiB 的页面，因此 MCP 不提供批量导出功能；命令行会以流式传输的方式输出数据。 `get_activity_stats` 两项功能均可使用。
