内容
# tgctl — 命令行工具，用于 Telegram Bot API
`tgctl` 封装了 [Telegram Bot API](https://core.telegram.org/bots/api) ，提供一个快速、可脚本化的、类似 `gh` 的命令行界面（CLI）。您可以发送消息、管理聊天和成员、配置 webhook 和机器人的命令菜单，以及拉取更新，并支持表格/JSON/YAML/CSV 输出、多个机器人的命名配置文件、操作系统密钥环令牌存储，以及一个 MCP 服务器，允许 AI 代理安全地驱动它。
> 🏭 使用 [cliwright](https://github.com/jjuanrivvera/cliwright) 构建 — 一个规范化的 CLI 工厂。
```console
$ tgctl auth login # 在您的操作系统密钥环中存储一个 @BotFather 令牌
$ tgctl bot info
ID 用户名 名字 是否可以加入群组
123456789 mybot 我的机器人 true
$ tgctl message send --chat @me --text "hello from tgctl"
$ tgctl updates get --limit 5 -o json | jq '.[].message.text'
```
## 安装
### curl | sh (macOS/Linux)
下载适用于您的操作系统/架构的发布存档，并在安装前使用发布 `checksums.txt` 验证其 SHA-256：
```sh
curl -fsSL https://raw.githubusercontent.com/jjuanrivvera/tgctl/main/install.sh | sh
```
### Homebrew (macOS/Linux)
```sh
brew install jjuanrivvera/tgctl/tgctl-cli
```
### Scoop (Windows)
```sh
scoop bucket add tgctl https://github.com/jjuanrivvera/scoop-tgctl
scoop install tgctl
```
### Docker
```sh
docker run --rm -e TGCTL_TOKEN=123:ABC ghcr.io/jjuanrivvera/tgctl bot info
```
### Go
```sh
go install github.com/jjuanrivvera/tgctl/cmd/tgctl@latest
```
### deb / rpm / apk
从 [最新发布](https://github.com/jjuanrivvera/tgctl/releases/latest) 页面下载。
## 快速入门
1. 创建一个机器人，并从 [@BotFather](https://t.me/BotFather) 获取其令牌。
2. 运行 `tgctl auth login` （或 `tgctl init` 以启动引导式向导）。令牌将通过 `getMe` 验证，并存储在您的操作系统密钥环中 — 绝不会存储在纯文本配置文件中。
3. 运行任何命令。添加 `--dry-run` 以打印等效的 `curl` （令牌已删除）而无需发送任何内容。
```sh
tgctl bot info # 我是谁？
tgctl message send --chat @me --text "hi" # 发送消息
tgctl media photo --chat @me --photo ./cat.jpg # 上传照片
tgctl media audio --chat @me --audio ./song.mp3 # 音频、语音、动画、贴纸等
tgctl message poll --chat @g --question "午餐？" --options '[{"text":"A"},{"text":"B"}]'
tgctl message location --chat @me --latitude 3.45 --longitude -76.53
tgctl file download --file-id <id> --dest ./out.jpg # getFile + 下载字节
tgctl chat get --chat @telegram -o json # 聊天元数据为 JSON
tgctl chat administrators --chat @mygroup # 列出管理员
tgctl invite create --chat @mygroup --member-limit 100 # 一次性邀请链接
tgctl callback answer --callback-query-id <id> --text "已保存！"
tgctl forum create --chat @mygroup --name "公告" # 论坛主题管理
tgctl member set-title --chat @mygroup --user 123 --title "社区领袖"
tgctl stars transactions --limit 20 # Telegram Stars 余额账本
tgctl webhook listen --port 8080 -o json # 接收 + 打印 webhook 更新到本地
tgctl api getMe --idempotent # 原始逃生舱任意方法
```
## 输出和过滤
单个渲染器服务于每个命令。使用 `-o/--output` 选择格式：
| 格式 | 用途 |
|---|---|
| `table` （默认） | 对齐，TTY 上彩色（尊重 `NO_COLOR` / `--no-color` ） |
| `json` | 完整记录，大 ID 保持精确 |
| `yaml` | 可读的结构化输出 |
| `csv` | 适合电子表格（公式注入净化） |
| `id` | 每行一个 ID，可管道传输到 `xargs` |
- `--columns a,b,c` 选择/排序列； `--jq '<expr>'` 使用内置 gojq 过滤。
- 注意和警告信息会输出到 **stderr** ，因此 stdout 保持管道清洁。
## 多个机器人（ `--bot` ）
一个配置文件对应一个机器人，因此使用 `--bot` （旧的 `--profile` 标志仍然作为隐藏别名）选择它：
```sh
tgctl auth login --bot staging # 第二个机器人
tgctl --bot staging bot info
tgctl config use staging # 设置为默认值
tgctl config list-profiles
```
机器人选择优先级： `--bot` > `$TGCTL_BOT` > `$TGCTL_PROFILE` （旧版） > 活动机器人。
令牌优先级： `$TGCTL_TOKEN` > `$TELEGRAM_BOT_TOKEN` > 活动机器人的密钥环条目。
如果您运行自托管的本地机器人 API 服务器，请将 `--base-url` 指向它。
## AI 代理（MCP + 保护）
`tgctl` 配备了一个 MCP 服务器，允许代理通过注释工具调用机器人 API：
```sh
tgctl mcp start # 作为 MCP 服务器运行（stdio）
tgctl mcp claude # 安装到 Claude Desktop
```
设置/秘密命令（ `auth` 、 `config` 、原始 `api` 出口） **不** 被公开，令牌和机器人选择标志（ `--bot` / `--profile` ）永远不会到达工具模式。生成主机安全规则，硬阻止不可逆操作：
```sh
tgctl agent guard --host claude-code # 拒绝删除/离开/封禁；写入时询问；允许读取
tgctl agent guard --host codex --out ~/.codex/config.toml
```
## 安全性和可靠性
- **仅限幂等重试。** 读取在 5xx/网络时重试；写入 **仅限** 在 429（意味着 *已拒绝，未处理* ）时重试，因此超时 `sendMessage` 永远不会重复发送。
- **速率限制。** 固定 RPS，遇到 429 时减半并逐渐恢复（机器人 API 不暴露配额头，只有 `retry_after` ， `tgctl` 遵守）。
- **可处理的错误。** 每个失败都带有由状态码索引的提示（401 → 运行 `auth login` ，429 → 等待 N 秒，...）。
- **Ctrl-C** 取消正在进行的轮询和回退。
## 文档
完整命令参考： [`docs/commands/`](docs/commands/tgctl.md) 。使用 `make docs-serve` 构建文档站点（MkDocs Material）。
## 开发
```sh
make build # 构建到 bin/tgctl
make check # 格式化 + 检查 + lint + 测试
make verify # 确定性检查：检查 + 规范检查 + 规范完整性 + 覆盖率 + DoD
make judge # LLM 评分的主观检查（需要代理；构建验收测试）
make accept # 验证 + 评估 — 完整的构建验收测试
```
`make verify` 是 CI 运行的内容；它是确定性的，不会消耗令牌。 `make judge` 被排除在常规检查之外，因为它需要代理（ `claude` / `codex` ）并评估主观的完成定义项目，这些项目只能由 LLM 评估，而不能由 grep 评估。
参见 [AGENTS.md](AGENTS.md) 了解架构和房屋规则，以及 [DECISIONS.md](DECISIONS.md) 了解固定的设计裁决。
## 路线图 / 待办事项
`tgctl` 封装了 **135 个方法中的 109 个** Telegram Bot API（v8.3，从 [ark0f/tg-bot-api](https://ark0f.github.io/tg-bot-api/) 机器规范枚举而来） — **80%** 覆盖率，通过 `spec-completeness` 检查强制执行。自第一个版本以来已完成：
- **机器人 API 覆盖率 52 → 109 个动词** — 完整的成员/管理员管理、论坛主题（包括常规主题）、聊天管理员设置器（照片、权限、贴纸集、菜单按钮、取消固定所有）、 `edit*` 消息家族 + 批量复制/转发/删除、聊天/用户验证、Telegram Stars（交易、礼物、退款、订阅、付费媒体）、邀请导出 + 订阅链接，以及机器人短描述/默认管理员权限/关闭/注销。
- **打包** — 多阶段 `Dockerfile` + 无依赖的 GHCR 镜像，以及校验和验证的 `install.sh` （ `curl | sh` ）一键安装。
故意推迟（记录为 [DECISIONS.md](DECISIONS.md) 中的 `coverage-waiver` ，以便完整性检查考虑到它们，而不是静默的空白）：五个自成体系的特定功能系列 — **贴纸集创作、支付/发票、游戏、Telegram Passport 和业务连接**。每个都是相同的声明式模式来添加（清单动词 → 组 `methodCmd` → 模拟测试），当出现真正的需求时；当覆盖率清除阈值时，将删除豁免行。
## 许可证
MIT © Juan Rivera。参见 [LICENSE](LICENSE)。
