# Telegram Account Orchestrator (TAO)

<p align="center">
  <img src="docs/assets/tao-icon.png" alt="Telegram Account Orchestrator (TAO) icon" width="220">
</p>

<p align="center">
  <a href="https://soulknight666.github.io/telegram-account-orchestrator/">项目主页</a> ·
  <a href="https://github.com/soulknight666/telegram-account-orchestrator/releases">下载 Release</a>
</p>

> Telegram 分享建议使用固定预览入口：`https://soulknight666.github.io/telegram-account-orchestrator/`

**Self-hosted Telegram multi-account management with Web UI, CLI, Bot, MCP, Telethon, and Telegram Desktop tdata import.**

TAO is a Telegram account manager and orchestration toolkit for encrypted session storage, account health checks, controlled batch operations, device-session management, account-package processing, and automation through REST or MCP.

- **Interfaces:** Web UI, REST API, CLI, Telegram Bot, MCP
- **Core:** Telethon, FastAPI, encrypted SQLite-backed account storage
- **Import:** StringSession, `.session`, Telegram Desktop `tdata`
- **License:** MIT; GAFBot-derived code is documented in [`NOTICE.GAFBot`](NOTICE.GAFBot) and [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md)

## 中文说明

# Telegram 账号管理器（自托管）

基于 Telethon(MTProto) 的多账号管理工具：加密保存会话、按账号绑定代理与设备指纹、健康检查、受控批量操作、审计日志。CLI + Web 控制台 + **AI/Agent 控制层**三入口。

> **Windows 提示「无法验证发布者」**：从网上下载的 `.bat` 没有数字签名时的正常现象，点「运行」即可。也可先运行同目录 `unblock.bat`，或右键 `start.bat` → 属性 → 「解除锁定」。




## ZIP 工具（网页）

网页控制台「ZIP 工具」面板支持：

| 功能 | 说明 |
|------|------|
| 拆包 | 大号包按规则拆成小包 |
| 合并 | 多包合并，处理重名 |
| 按注册时间分类 | 默认离线分桶；可选联网查注册时间 |
| **转 API** | 上传 session/tdata ZIP → 重命名 session + `api.json` + 取码链接清单（对齐机器人能力） |

转 API 相关环境变量：`TAM_TOAPI_BASE`（优先）、`DM`、`SERVER_IP`/`API_PORT`。

机器人侧同名能力见菜单「转 API」；号包引擎来自 [GAFBot](https://github.com/kugua332334554/GAFBot)（MIT，见 `NOTICE.GAFBot`）。

## 致谢与第三方许可

机器人侧号包处理（`tam/gaf/`：筛活、转 API、拆包、防找回、整合等）移植自
**[GAFBot](https://github.com/kugua332334554/GAFBot)**（作者 **kugua311** / [@kugua332334554](https://github.com/kugua332334554)），
采用 **MIT License**。完整版权声明与许可证原文见本仓库 [`NOTICE.GAFBot`](NOTICE.GAFBot)。

按 MIT 条款：再分发时须保留上述版权与许可声明；本项目对 GAFBot 的修改与网页端适配由本仓库维护，与原作者无关。

## 快速开始

### 一键启动（推荐，新手选这个）

- Windows：双击 `start.bat`
- macOS / Linux：`./start.sh`
- 或：`python setup.py --auto`

**自动完成**：检查 Python → 建 `.venv` → 装依赖（失败自动换清华镜像）→ 生成 `.env` 与主密钥 → 体检修复 → 按你的选择启动。

**启动前只问两件事**（写入 `.env`，下次会记住默认值）：

1. **部署在哪里？** `local` 自己电脑（只监听 127.0.0.1）/ `server` 服务器（0.0.0.0，建议令牌+HTTPS）
2. **用哪个前端？** `web` 网页控制台 / `bot` Telegram 机器人 / `both` 两个一起

也可以不进菜单，直接指定：

```bash
./start.sh --deploy local --frontend web
./start.sh --deploy server --frontend both --token
```

- 本机 + 网页：默认免令牌，浏览器打开即用。
- 服务器：默认启用访问令牌。
- 选了机器人但还没有 Token：会提示填一次 `@BotFather` 的 `TAM_BOT_TOKEN`（可回车跳过，稍后写 `.env`）。
- api_id / 代理：一键模式不打断，需要时再写 `.env` 或网页参数面板（含批量并行 / 单号超时自动跳过 / 重生并行）。
- 其它：`--no-start`、`--port 8848`、`--skip-install`、`--no-venv`。

### 手动安装

```bash
pip install -r requirements.txt
cp .env.example .env
python -m tam.cli init-key        # 生成 TAM_MASTER_KEY，写入 .env
# 在 my.telegram.org 申请 api_id / api_hash，填入 .env

python -m tam.cli add 主号 --phone +8613800138000 --proxy socks5://127.0.0.1:1080
python -m tam.cli login 1         # 验证码 + 两步验证密码
python -m tam.cli check           # 全部账号健康检查
python -m tam.cli serve           # http://127.0.0.1:8848 Web 控制台
```

## 一键体检（出任何问题先跑它）

```bash
python -m tam.cli doctor        # 只体检，不改任何东西
python -m tam.cli doctor --fix  # 体检并自动修复
python -m tam.cli doctor --json # 机器可读输出（给脚本 / Agent）
```

也可以在 Web 控制台右上角点“一键体检”按钮（等价于 `doctor --fix`）。
安装向导的第 5 步、以及 `serve` 启动前都会自动跑一遍（`serve --no-doctor` 可关闭）。

检查 13 项，带 ✓ 的都能自动修：

| 检查项 | 自动修复 |
| --- | --- |
| Python 版本（含 3.13 兼容提醒） | — |
| 核心依赖是否齐全 | ✓ 自动 pip 安装（官方源失败自动转清华镜像） |
| `.env` 是否存在 | ✓ 从 `.env.example` 生成 |
| `TAM_MASTER_KEY` | ✓ 自动生成并写入 |
| `TAM_WEB_TOKEN` | ✓ 自动生成并写入 |
| 配置能否加载（.env 格式、行内注释、空值） | — |
| 会话加解密往返 | — |
| 数据库可读写 + 自动建表/迁移 | ✓ 建目录与表结构 |
| `api_id` / `api_hash` 是否合法 | —（未填只提醒） |
| Web 控制台文件完整性 | — |
| API 能否导入、接口数 | — |
| opentele（仅机器人侧部分旧链路可能用到） | ✓ 可装；**网页 tdata 导入已不依赖它** |
| 端口 8848 是否被占 | — |

## 卡商初始账号批量导入

支持 `手机号|取码链接` 行格式，例：

```
+10000000000|https://example.invalid/code/primary/GetHTML
+10000000001|https://example.invalid/code/secondary/GetHTML|美国号B
```

```bash
python -m tam.cli import-accounts accounts.txt --tags batch1 --dry-run   # 先预览
python -m tam.cli import-accounts accounts.txt --tags batch1
cat accounts.txt | python -m tam.cli import-accounts -                   # 也可走 stdin

python -m tam.cli auto-login --id 1            # 发码 → 自动拉取码 → 登录
python -m tam.cli auto-login --tag batch1      # 批量（默认串行 + 随机间隔）
```

容错与行为：

- 分隔符支持 `|`、`\|`、`｜`、制表符、逗号、分号；两段顺序可以颠倒；手机号缺 `+` 自动补。
- 第三段作为备注/别名；`#` 开头与空行忽略；单行出错不中断整批，错误行集中返回。
- 幂等：手机号已存在只补写取码链接，不重复建号。
- 取码：`codefetch.py` 只用标准库拉取该链接（支持代理），先记录发码前的旧码作基线，再轮询直到出现不同的新码（默认 120s 超时、5s 一次），避免拿错上一次的验证码。
- 旧库自动迁移：启动时缺 `code_url` 列则自动补列。
- 开了两步验证的号需传 `--password`（取码链接只能拿到短信码）。

## 导入 .session / StringSession

卡商号包常见形态是 Telethon 的 `.session`（SQLite）或 StringSession 字符串。Web 控制台点 **「session 导入」**，或用 CLI：

```bash
# 目录里一批 .session（默认递归）
python -m tam.cli import-sessions /path/to/sessions --tags batch --proxy socks5://127.0.0.1:1080
python -m tam.cli import-sessions /path/to/one.session --label 主号

# 文本文件，一行一个 StringSession；可用 别名|session
python -m tam.cli import-session-strings sessions.txt --tags ss
cat sessions.txt | python -m tam.cli import-session-strings -
```

行为：

- 转 StringSession → 联网验证可用 → Fernet 加密入库；失效条目不留垃圾行。
- 已存在相同 `user_id` 则合并更新会话，不重复建号。
- 该能力只走人工入口（Web / CLI），**不向 Agent 开放**。
- Web 支持三种方式：本机上传 `.session`/zip、服务端路径、粘贴 StringSession。

API：`POST /api/accounts/import-sessions`、`POST /api/accounts/import-session-strings`、`POST /api/accounts/import-session-upload`。

## 从 Telegram Desktop tdata 导入

tdata 是桌面端的本地加密目录（`key_datas` + `D877F783D5D3EF8C*` 分片），内含 `auth_key` / `dc_id`。
解析由**内置纯 Python 解析器**完成，**无需 opentele**；兼容 Telegram Desktop 6.x。

```bash
python -m tam.cli import-tdata /path/to/tdata --label 主号 --proxy socks5://127.0.0.1:1080
python -m tam.cli import-tdata /path/to/tdata --password 本地密码        # 桌面端设了 passcode
python -m tam.cli import-tdata /path/to/号包目录 --scan --tags tdata   # 批量扫描子目录
```

行为：

- 转换链路：tdata → StringSession → 连接验证可用 → Fernet 加密入库；**全程不落明文 `.session` 文件**。
- 一份 tdata 含多个账号时逐个导入，别名自动加后缀；已有相同 `user_id` 则合并更新，不重复建号。
- 会话失效的条目不会在库里留垃圾行，错误单独回报。
- 默认使用桌面端官方 API 指纹 + `UseCurrentSession`（复用原授权，不额外产生新登录记录）；加 `--own-api` 才改用自己的 API ID，风控更高，不推荐。
- 导入后桌面端仍在线，两端共用同一授权；避免两边同时高频操作。
- 该能力归入 `HUMAN_ONLY`，**不向 Agent 开放**，只能人工走 CLI。

## 架构

```
tam/
├── config.py     环境配置（.env）
├── crypto.py     scrypt + Fernet：session 静态加密
├── db.py         SQLite：accounts / audit_log（含 code_url 取码链接）
├── importer.py   批量解析导入 手机号|取码链接 清单
├── codefetch.py  从取码链接抽取登录验证码（标准库，支持代理与轮询）
├── tdata.py / tdata_native.py   tdata 扫描与内置解析（无需 opentele）
├── ratelimit.py  令牌桶限速 + 人性化随机延迟
├── manager.py    Telethon 封装：登录、会话上下文、健康检查、批量调度
├── tools.py      AI 控制层：带 JSON Schema 的工具注册表 + 统一调用与安全策略
├── mcp_server.py MCP stdio 服务端（零依赖，供 Claude/Cursor 等接入）
├── api.py        FastAPI REST + Web 控制台
├── cli.py        命令行
└── web/index.html 单页控制台
```

### 关键设计

| 问题 | 方案 |
| --- | --- |
| 会话凭证泄露 | 只存 StringSession 密文；主密钥仅在环境变量，不入库 |
| 同账号并发冲突 | 每账号 asyncio.Lock，同一时刻仅一个活跃客户端 |
| 账号关联风险 | 每账号独立 socks5/http 代理 + 独立设备指纹（device_model / app_version / lang_code） |
| FloodWait / 限流 | 每账号令牌桶（默认 0.5 QPS）+ 批量动作 8–25 秒随机间隔 + 受控并发信号量 |
| 封号与失效感知 | health_check 区分 active / restricted / unauthorized / banned / flood_wait 并落库 |
| 可追溯 | 所有写操作进 audit_log，Web 控制台可查看 |

## REST 接口

所有 `/api/*` 需 `Authorization: Bearer <TAM_WEB_TOKEN>`。若向导里选了“本机免令牌”（`TAM_NO_AUTH=1` 且 `TAM_WEB_TOKEN` 为空），则不需要任何头部，直接访问即可。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | /api/accounts | 账号列表（不含会话） |
| POST | /api/accounts | 新增账号 |
| PATCH/DELETE | /api/accounts/{id} | 修改 / 删除 |
| POST | /api/accounts/{id}/login/code | 发送验证码 |
| POST | /api/accounts/{id}/login/verify | 提交验证码（含两步验证） |
| POST | /api/accounts/{id}/session/import | 导入已有 StringSession |
| POST | /api/accounts/{id}/check | 健康检查 |
| GET | /api/accounts/{id}/dialogs | 会话列表 |
| GET | /api/accounts/{id}/devices | 已登录设备 |
| POST | /api/accounts/{id}/devices/terminate | 踢掉其他设备 |
| POST | /api/accounts/{id}/message | 发送消息 |
| POST | /api/accounts/{id}/login/auto | 自动取码登录（需 code_url） |
| POST | /api/accounts/import | 批量导入 `手机号\|取码链接`（支持 dry_run） |
| POST | /api/accounts/import-sessions | 批量导入 `.session` 文件（服务端本地路径） |
| POST | /api/accounts/import-session-strings | 批量导入 StringSession 文本 |
| POST | /api/accounts/import-session-upload | 浏览器上传 `.session` / zip（原始请求体） |
| POST | /api/accounts/import-tdata | 从 tdata 目录导入（可递归扫描） |
| POST | /api/batch/check、/api/batch/message、/api/batch/auto-login | 批量操作 |
| GET | /api/logs、/api/stats | 日志与统计 |
| GET | /api/autokick | 自动清设备的开关、周期、待处理数量 |
| POST | /api/autokick/run | 立即对到期账号扫一轮 |
| GET | /api/tools | Agent 工具清单 + JSON Schema（接受只读令牌） |
| POST | /api/tools/call | 统一工具调用入口（接受只读令牌） |
| GET | /api/settings | 参数面板：21 项可调参数的当前值与说明 |
| POST | /api/settings、/api/settings/reset | 写回 `.env`（保留原有注释与行顺序）/ 恢复默认 |
| GET | /api/toolbox/ops | 工具箱的 10 项操作及其参数表（前端据此动态渲染） |
| POST | /api/toolbox/{op}/batch | 对库里选中的号批量执行某项操作（严格保序返回） |
| POST | /api/tools/unpack/analyze | 只看包里有多少个号，不落盘 |
| POST | /api/tools/unpack?fmt=&workers= | 拆包，`-9-` 或 `5,5,5` |
| POST | /api/tools/merge/add?job= | 分次上传要合并的包（攒到同一个作业，上限 50） |
| POST | /api/tools/merge/{job}/run?workers= | 执行合并，同名自动改名不丢号，完事立即删源包 |
| POST | /api/tools/regtime?workers= | 按注册日期分类打包（默认完全离线） |
| GET | /api/tools/unpack/{job}/{filename} | 取结果包（带鉴权，所以网页端是 fetch 成 blob 再保存） |
| DELETE | /api/tools/unpack/{job} | 用完删除。号包是敏感物，不要赖在服务器上 |

## 给 AI / Agent 的控制手段

Agent 可调用能力注册在 `tam/tools.py`（`@tool`）。网页「工具箱」另有一份注册表 `tam/toolbox.py`。

**增删工具时两边要同步：** 只改 `toolbox.py` 则仅网页可用；只改 `tools.py` 则仅 AI/MCP 可用。需要对 AI 隐藏的能力不要写入 `tools.py`（或列入 `HUMAN_ONLY`）。详见 `FOR_AI.md` §8–§9。

| 入口 | 用法 |
| --- | --- |
| MCP | `python -m tam.cli mcp`（stdio，实现 initialize / tools/list / tools/call） |
| CLI | `python -m tam.cli tools`、`python -m tam.cli call send_message '{"account_id":1,"peer":"@me","text":"hi"}'` |
| HTTP | `GET /api/tools`、`POST /api/tools/call` |
| OpenAPI | `/openapi.json`、`/docs`（全部 REST 路由自带 operation_id） |
| Python | `from tam.tools import ToolContext, call_tool, list_tools` |

MCP 客户端配置示例：

```json
{"mcpServers": {"tam": {"command": "python", "args": ["-m", "tam.mcp_server"], "cwd": "/path/to/tam"}}}
```

工具清单（`danger` 标注风险等级）：

| 等级 | 工具 |
| --- | --- |
| read | list_accounts、get_account、stats、read_logs、health_check、list_dialogs、list_devices、preview_import、spintax_preview、healthy_accounts、proxy_audit、autokick_status |
| write | add_account、update_account、import_accounts、spam_check |
| destructive | auto_login、send_message、update_profile、terminate_other_devices、delete_account、warmup、autokick_run |

### 登录满 24 小时自动踢出其它设备

- `TAM_AUTO_KICK_HOURS=24` 全局开关（0 = 关闭）；账号级开关是 `auto_kick` 字段（Web 抽屉里的“自动清设备”勾选框）。
- 计时起点是 **本机接管时间** `adopted_at`（导入 tdata / StringSession / 验证码登录拿到会话那一刻），不是服务端的会话创建时间。
- 踢完会回拉一次会话列表校验：只有确认“只剩本机”才算成功并重新起算周期；还剩会话或报错则排一个重试。
- `TAM_KICK_RETRY=1h` 失败后的重试间隔，支持秒/分/时写法：`45s`、`10m`、`2h`、`1h30m`，纯数字按秒，最小 10 秒。
  也可以在 Web 顶栏“失败重试”输入框里改（存在数据库 `settings` 表，优先于 .env；留空保存即恢复默认），
  或调 `POST /api/autokick/retry {"value":"10m"}`；`POST /api/autokick/run {"retry":"30s"}` 只对本轮生效。
- 服务启动后后台每 10 分钟扫一轮；计时基准 = `kick_retry_at` > `last_kick_at` > `adopted_at` > `login_at` > `created_at`，满 N 小时就调一次“踢掉其他设备”，并写 `auto_kick` 审计日志。
- 为什么是 24 小时：Telegram 对新会话有 24 小时保护期，期内新会话无权注销其它会话，提前调只会报错。
- `banned / unauthorized / frozen / spam_block_perm` 的号自动跳过；失败不再把周期推满一天，而是按 `TAM_KICK_RETRY` 排重试（默认 1 小时）。
- 手动跑一轮：Web 顶部“立即执行”按钮，或 `POST /api/autokick/run`。

约定：

- 统一返回 `{"ok": bool, "tool": str, "result" | "error": {...}}`，工具调用**从不抛异常**，错误码固定为 `unknown_tool / bad_request / not_found / conflict / forbidden / readonly / error`。
- `destructive` 工具不传 `confirm: true` 时只返回预览（`executed: false`），不产生任何对外副作用。
- 参数用 JSON Schema 校验，未知参数与缺失必填参数直接拒绝，避免模型幻觉参数静默生效。
- `TAM_READONLY=1` 或使用 `TAM_READONLY_TOKEN` 时，写入类工具从清单中消失并被拒绝——推荐给 Agent 单独发只读令牌。
- `TAM_DRY_RUN=1` 全局干跑；`TAM_PEER_ALLOWLIST` 限定可发送对象。
- 登录、导入/导出会话**不对 Agent 开放**，只能人工走 CLI/Web，防止凭证被模型读走。
- CLI 全面非交互化：`login --send-code` / `--code` / `--password` / `--non-interactive`，`list --json`，失败退出码非零。

自检：`for f in tests/test_*.py; do python3 "$f" || break; done`；内核另有 `python3 tam/tests/t_zhenghe.py`、`t_shaireg.py`、`t_zip_concurrency.py`、`t_coerce_setting.py`、`t_toolbox.py`

## 免令牌模式（本机自用）

启动向导（`start.bat` / `start.sh` / `python setup.py`）会问一句：

```
? 启用访问令牌？（本机自用选 n）(Y/n)
```

- 选 `n`：写入 `TAM_WEB_TOKEN=` （空）+ `TAM_NO_AUTH=1`，浏览器打开 http://127.0.0.1:8848 直接可用，页面右上角令牌框留空。
- 选 `y`：没令牌就生成一个，已有则保持不变。
- 不想被问：`python setup.py --no-token` 或 `python setup.py --token`。
- 一键体检会识别 `TAM_NO_AUTH=1`，不再把空令牌当错误自动生成。

服务默认只监听 127.0.0.1，外部连不进来；**一旦改成 0.0.0.0 或放到服务器，必须重新启用令牌。**

## 布局编辑模式（仪表盘式网格）

右上角点【编辑布局】进入，再点【完成】退出。布局引擎是二维网格矩阵（坐标 x/y + 跨度 w/h），与 Grafana、react-grid-layout 同类机制。

| 操作 | 效果 |
| --- | --- |
| 拖控件中间 | 自由移位；拖动时显示虚线落点框，撞到的控件会被推开，松手后整体向上收紧 |
| 拖右边缘 | 改宽，吸附到网格列 |
| 拖下边缘 | 改高，吸附到 40px 行 |
| 拖右下角 | 同时改宽高；双击该角恢复默认尺寸 |
| 点右上角 × | 隐藏控件，底部恢复条可加回来（带撤销） |
| 一键整理 | 所有控件向上收紧，消除空隙 |
| 导出 / 导入布局 | 存为 `tam-layout.json`，可在其它电脑或浏览器导入 |
| 全部恢复默认 | 清空本地布局并刷新 |

说明：

- 控件粒度：每个统计数字、自动清设备提示条、账号列表、日志中文摘要、日志原始 JSON 各是独立控件。
- 响应式断点：宽屏 12 列 / 中屏 8 列 / 窄屏 4 列，**三套布局分开保存**，在手机上改动不会弄乱电脑上的布局。
- 手机触屏：长按约 0.2 秒才起拖，快滑仍然是页面滚动；拖到屏幕上下边缘会自动滚动。
- 性能：拖拽走 `requestAnimationFrame` + `translate3d`，实测单帧重算加渲染约 1.5ms。
- 布局存在浏览器 `localStorage['tam.layout']`（v3），换浏览器用导出/导入搬迁。

## 安全与合规

- 服务默认只监听 `127.0.0.1`；对外暴露必须加 HTTPS 反代与强令牌。
- `data/` 目录含加密会话，勿进版本库；建议整盘或目录级加密。
- 主密钥丢失 = 所有会话不可恢复；请离线备份。
- 仅用于管理**你自己拥有**的账号。群发、批量拉人、自动化骚扰违反 Telegram 服务条款，可能导致账号被限制或永久封禁；本项目默认参数偏保守，请勿调高。

## 常见问题

### tdata 导入报 `BaseException: err`

完整报错形如 `opentele/utils.py, line 121, in __new__ / raise BaseException("err")`，
前面还会打印一行 `[__firstlineno__] ...`。

原因：opentele 尚不支持 Python 3.13（上游 issue #133 / #145 至今未修）。
Python 3.13 给类新增了 `__firstlineno__` / `__static_attributes__`，opentele 的
`extend_class` 校验不认，直接抛 `BaseException`（注意：它不是 `Exception` 子类，
常规 `except` 拦不住）。

最省事：`python -m tam.cli doctor --fix`，或在 Web 控制台点“一键体检”，会自动完成下面第 1 种修复。

手动方案二选一：

1. 打兼容补丁（快，可回滚）：
   ```bash
   python -m tam.cli fix-opentele          # 打补丁并验证导入
   python -m tam.cli fix-opentele --status # 只看状态
   python -m tam.cli fix-opentele --revert # 还原
   ```
   补丁只把那句断言性的 `raise` 改成放行，修改前会备份为 `utils.py.tam-bak`。
   Web 控制台导入 tdata 时也会自动尝试这一步。

2. 改用 Python 3.12 重建虚拟环境（最稳妥）：
   ```powershell
   rmdir /s /q .venv
   py -3.12 -m venv .venv
   .venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   pip install -r requirements-optional.txt
   ```

### 导入报 `{"detail":"unauthorized"}` 或界面全是 401

Web 页面右上角的令牌要和 `.env` 里的 `TAM_WEB_TOKEN` 一致，输完按回车生效。

### opentele 没装上

网页端 **tdata 导入已改用内置解析器，不需要 opentele**。
`opentele` 仅在机器人前端部分旧功能可能用到，是可选依赖：`pip install -r requirements-optional.txt`。
未安装不影响 Web 控制台与 CLI 的 tdata / session 导入。

## 已知限制

- 官方客户端同时登录上限为 3 个账号（Premium 4 个），本工具用独立 API 会话不受该限制，但每次新增授权都会出现在“已登录设备”里。
- 新号（尤其虚拟号）在冷却期内易触发 `PeerFloodError`，建议先养号：完善资料、正常收发、逐步提升活跃度。
- 同一 IP 下多账号高频活动会显著提高关联与封禁概率，建议一号一代理。

## 任务中心 / 线索库（v1.8）

把“对一批目标逐个执行”变成可观测、可停止的任务，完整链路是：
**采集目标 → 建任务 → 富文本群发 → 逐目标看进度和失败原因**。

### 最近发言人采集

- WebUI 「任务中心 → 采集发言人」，填群组与天数。
- 只取最近真实发过言的人，自动跳过机器人、已注销账号，减少对长期不活跃成员的无效触达。
- 结果自动入线索库，按 (来源, user_id) 去重，重复采集只更新活跃度。
- API：`POST /api/tasks/collect`

### 线索库

- 按来源统计人数与有用户名比例，支持一键导出 CSV（带 BOM，Excel 直接打开不乱码）。
- 可直接对某个来源“向它群发”，不用手工拷名单。
- 采集时勾选「同时存对话记录」后，Web 上每条线索 / 每个来源可点 **「对话」** 查看发言上下文。
- API：`GET /api/leads`、`GET /api/leads/sources`、`GET /api/leads/messages`、`DELETE /api/leads`

### 富文本群发

- 支持 `{a|b}` 变体（spintax）、`{name}` 个性化变量、HTML 富文本与可点击超链接、附件。
- 多账号轮询发送，带随机间隔；发送前可用 `POST /api/message/preview` 看展开样本与链接。
- API：`POST /api/tasks/message`

### 任务管理

- 进度条 + 成功/失败/已跳过统计，运行中每 3 秒自动刷新。
- “明细”看逐目标结果，失败原因自动归类（如 FloodWaitError 多少个）。
- “停止”为协商式：不再发新内容，剩余目标标为已跳过，已发出的不会撤回。
- API：`GET /api/tasks`、`GET /api/tasks/{id}`、`POST /api/tasks/{id}/stop`、`DELETE /api/tasks/{id}`、`POST /api/tasks/cleanup`
- Agent 工具：`list_tasks`、`get_task`、`list_leads`、`lead_sources`（只读）、`stop_task`（需 confirm）


## 常用环境变量（并发 / ZIP / 清设备）

写在 `.env`，也可在 Web **参数面板**改完自动写回。启动时终端会打印当前 workers / 批量并发 / 清设备重试。

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `TAM_WORKERS` | `4` | ZIP 拆包 / 合并 / 注册时间分类的并发度，上限 32 |
| `TAM_TOAPI_BASE` | （空） | 网页/机器人转 API 的取码链接前缀，如 `https://api.example.com` |
| `TAM_BATCH_CONCURRENCY` | `3` | 工具箱、批量任务同时开几个号；调大易触频控 |
| `TAM_MAX_EXTRACT_MB` | `512` | 解压后总大小上限，防 zip 炸弹 |
| `TAM_KICK_RETRY` | `1h` | 清设备失败后的重试间隔：`45s` / `10m` / `2h` / `1h30m` |
| `TAM_AUTO_KICK_HOURS` | `24` | 本机接管满多少小时自动踢其它设备；`0` = 关 |
| `TAM_REGTIME_ENDPOINT` | 空 | 留空 = 注册时间分类完全离线，不外发任何号信息 |

完整列表见 `.env.example`。

## 双部署 × 双前端（v1.9）

现在一个命令就能决定“装在哪”和“怎么用”：

```bash
python -m tam.cli run                      # 读 .env 里的 TAM_DEPLOY / TAM_FRONTEND
python -m tam.cli run --frontend both      # 临时覆盖：网页 + 机器人一起跑
python -m tam.cli run --deploy server --frontend bot
python -m tam.cli bot                      # 只跑机器人
python -m tam.cli serve                    # 只跑网页（老命令，没变）
```

### 两个开关

| 变量 | 取值 | 含义 |
| --- | --- | --- |
| `TAM_DEPLOY` | `local` | 本机自用。只绑 `127.0.0.1`，不对外暴露，不强制代理 |
| | `server` | 服务器。绑 `0.0.0.0`，启动前会检查 `proxy.txt` 与 `TAM_MASTER_KEY` |
| `TAM_FRONTEND` | `web` | 只开网页控制台 |
| | `bot` | 只开 Telegram 机器人 |
| | `both` | 两个一起跑，共用同一份 `.env` 与数据目录 |

命令行参数 > 环境变量 > 默认值（`local` + `web`）。

### 两个前端分工不同，不是同一套东西换皮

- **网页控制台**：管你自己**托管在库里**的号——登录、导入 tdata、养号、群发、线索库，以及接管满 24 小时自动清设备（带踢后校验与失败重试）。
- **Telegram 机器人**：管用户**临时上传的号包**——发个 ZIP 进去，处理完回传，不入库。

### 网页控制台（近期能力）

- **AI 助手面板**：右下角 / 顶栏唤出侧栏；OpenAI 兼容 API；权限预设（只读/安全/标准/完整）与逐项工具开关；账号范围限制；对话经服务端执行已授权工具。


- **导入进度**：session / tdata / 字符串导入使用 NDJSON 流式进度，界面显示当前序号与结果。
- **二验**：状态查询（含是否绑定辅助邮箱）、发起/取消官方 2FA 重置；支持单号与多选。
- **导出 tdata**：真 Desktop 目录；缺 `opentele` 时可在界面一键安装。
- **ZIP 工具**：拆包、合并、注册时间、转 API、**格式互转**（session↔tdata）、**Passkey 创建**。
- **热重载**：顶栏按钮真实重启后端进程（`os.execv`），不是刷新页面。
- **错误日志**：服务端异常 / 5xx / 前端报错写入 SQLite + `data/errors.log`，可导出 JSON 上报。

`TAM_FRONTEND=both` 时网页与机器人共享配置与数据目录，但 **Telegram 账号库仅网页/API 使用**；机器人仍以临时号包为主。

### 机器人功能（菜单、命令两种用法都行）

筛活 `/shaihuo`、改 2FA `/twofa`、整合号包 `/merge`、双向测试 `/bidir`、隐私配置 `/privacy`、
格式互转 `/convert`、转 API `/toapi`、防找回 `/norecover`、筛 BAN `/ban`、筛料 `/material`、
清理账号 `/clean`、拆包 `/unpack`、销毁会话 `/destroy`、Passkey `/passkey`、注册时间 `/regtime`。
辅助：`/start` `/help` `/status` `/id`；管理员：`/vip ID`、`/unvip ID`、`/gb`（广播）。

**故意没做的三项**：踢设备、账号登录、在线取码——TAM 自己已经有更好的实现（带校验、带重试、
会话加密入库），机器人里的 `/kick`、`/login` 只负责把你引到那边，不重复造一份。

### 付费 / VIP

`OKPAY_COST` 留空就是**不收费**，任何人进来直接是 VIP（自用场景默认这样）。
填了 `OKPAY_ID` / `OKPAY_TOKEN` / `OKPAY_COST` 才会开付费门槛：下单后每 5 秒轮询，5 分钟不付自动关单，
付成自动升 VIP。管理员任何时候可以 `/vip ID` 手动开。

### 服务器部署提醒

`--deploy server` 会绑 `0.0.0.0`。请务必：别开 `TAM_NO_AUTH=1`、设好 `TAM_WEB_TOKEN`、
前面搭一层 HTTPS 反代、`proxy.txt` 配上代理池（否则所有号走服务器裸 IP，风控风险很高）。
启动时这几项没配好会直接在终端警告。

### 启动前体检（该提醒的都写在启动输出里）

`python -m tam.cli run` 会先把当前配置扫一遍，直接打在终端上，不用去翻文档：

```
----------------------------------------------------
  启动前体检（部署=server  前端=bot）
----------------------------------------------------
  ❌  机器人前端的依赖没装齐：python-telegram-bot[job-queue]、opentele
       → pip install -r requirements.txt
       → 只想用网页的话这些不用装，把 TAM_FRONTEND 改成 web 即可
  ❌  服务器模式未设 TAM_WEB_TOKEN，控制台会没有访问门槛。
       → python -m tam.cli init-key 生成一个填进 .env
  ⚠️  服务器模式会监听 0.0.0.0（全网可达），请在前面套一层 HTTPS 反代。
  ⚠️  没找到 proxy.txt，所有号会走服务器裸 IP，风控风险很高。
----------------------------------------------------
```

- **❌ 致命错误会直接阻断启动**（缺依赖、缺 Token、服务器模式下 `TAM_NO_AUTH=1` 或没 `TAM_WEB_TOKEN`），
  真知道自己在干什么可以加 `--force` 继续。
- **⚠️ 警告只提醒不拦**（没代理池、没管理员 ID、没配付费等于白嫖、密钥落盘……）。
- 依赖按前端分开查：只跑网页不会因为没装 `python-telegram-bot` 而报错，反之亦然。
- 缺 `TAM_MASTER_KEY` 这类问题也会输出一行人话提示，而不是抛一屏 traceback。