telepost-bot 2.83.0__tar.gz → 2.83.2__tar.gz

{telepost_bot-2.83.0 → telepost_bot-2.83.2}/CHANGELOG.md

@@ -8,6 +8,20 @@
 > 发布说明面向普通用户：写「对用户有什么改变」，不写内部实现细节（模块名、函数名、配置键）；
 > 技术细节放进代码注释或 `docs/`。每个 Release 的正文由本文件对应版本段自动生成。
 
+## [2.83.2](https://github.com/redtidev1918/TelePost/compare/v2.83.1...v2.83.2) (2026-10-15)
+
+
+### Bug Fixes
+
+* align concurrent SQLite test with production WAL mode ([#331](https://github.com/redtidev1918/TelePost/issues/331)) ([f0889c4](https://github.com/redtidev1918/TelePost/commit/f0889c43b1ee40d7ac3b99d7a5bd1d4cdb3cc76f))
+
+## [2.83.1](https://github.com/redtidev1918/TelePost/compare/v2.83.0...v2.83.1) (2026-10-11)
+
+
+### Bug Fixes
+
+* align review admission, installers and Mini App security with runtime behavior ([#328](https://github.com/redtidev1918/TelePost/issues/328)) ([3116ea7](https://github.com/redtidev1918/TelePost/commit/3116ea70dbbba0e184327e8eeddd49ef4ddf6117))
+
 ## [2.83.0](https://github.com/redtidev1918/TelePost/compare/v2.82.0...v2.83.0) (2026-10-11)
 
 

telepost_bot-2.83.2/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: telepost-bot
+Version: 2.83.2
+Summary: Telegram submission, review, and publication bot with a Mini App, HTTP API, and multi-bot supervisor.
+Author: redtidev1918
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/redtidev1918/TelePost
+Project-URL: Repository, https://github.com/redtidev1918/TelePost
+Project-URL: Documentation, https://github.com/redtidev1918/TelePost/tree/main/docs
+Project-URL: Issues, https://github.com/redtidev1918/TelePost/issues
+Project-URL: Changelog, https://github.com/redtidev1918/TelePost/blob/main/CHANGELOG.md
+Keywords: telegram,bot,submission,review,publication,miniapp,telepost,moderation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-telegram-bot[job-queue]>=22.8
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: psutil>=5.9.8
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: pyvips>=2.2.0
+Requires-Dist: whoosh>=2.7.4
+Requires-Dist: init-data-py>=1.0.0
+Requires-Dist: telepress>=0.17.2
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: Babel>=2.16.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: coverage>=7.3.0; extra == "dev"
+Dynamic: license-file
+
+# TelePost
+
+**语言 / Language:** 中文 · [English](https://github.com/redtidev1918/TelePost/blob/main/README.en.md)
+
+TelePost 是一个开源、自托管的 Telegram 频道投稿与审核 Bot。用户通过 Bot 私聊、Mini App
+或 HTTP API 投稿；需要审核的稿件由管理员在审核群里查看、修改并决定是否发布。
+
+[![Release](https://img.shields.io/github/v/release/redtidev1918/TelePost)](https://github.com/redtidev1918/TelePost/releases/latest) [![PyPI](https://img.shields.io/pypi/v/telepost-bot.svg)](https://pypi.org/project/telepost-bot/) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/redtidev1918/TelePost/blob/main/LICENSE) [![Documentation](https://img.shields.io/badge/docs-redtidev1918.github.io-6366f1)](https://redtidev1918.github.io/TelePost/)
+
+[下载](https://github.com/redtidev1918/TelePost/blob/main/docs/download.md) · [安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md) · [完整文档](https://redtidev1918.github.io/TelePost/)
+
+## 产品界面
+
+![Bot 私聊主菜单](https://raw.githubusercontent.com/redtidev1918/TelePost/main/docs/assets/screenshots/bot-menu.jpg)
+
+Bot 私聊主菜单。用户在这里投稿、查看自己的投稿、搜索频道内容，或浏览热榜与标签云。
+
+<!-- 待补充的真实截图（按重要性排序）：① 投稿预览与编辑；② 审核群的审核操作；③ Telegram Mini App。 -->
+
+## 主要功能
+
+| 功能 | 说明 |
+| --- | --- |
+| 投稿 | 支持图片、视频、GIF、音频、文档和纯文字，提交前可预览、编辑，支持匿名与剧透。 |
+| 审核与发布 | 在私有审核群查看预览、发布、拒绝或遮罩稿件；支持重抓的自动化稿件可更换候选，替换后仍需人工审核。 |
+| Mini App | 可选网页界面，供用户浏览、投稿和查看进度，供审核员与管理员审核、编辑和管理。 |
+| 搜索与热榜 | `/search` 关键词检索（支持 `#标签` 和时间范围），`/tags` 标签云，`/hot`、`/hotweek` 热榜，`/myposts`、`/mystats` 个人投稿与统计。 |
+| 定时发布 | `/schedule add weekly-hot` 等命令按计划发布热榜内容。 |
+| 自动化投稿 | 脚本或上游服务通过 HTTP API 投稿，使用 `idempotency_key` 避免重试产生重复审核或发布。 |
+| AI 辅助审核 | 可选通过 MCP 接入 Codex、Claude 等 AI Agent，查看待审稿件并提供审核建议。 |
+| 多 Bot 与自托管 | 同一台机器可并行运行多个 Bot，各自使用独立的频道、审核群、语言和数据目录。 |
+
+各入口的默认审核规则见[如何工作](#如何工作)，集成与部署细节见[更多能力](#更多能力)。
+
+## 如何工作
+
+```text
+用户投稿 ──▶ 预览与编辑 ──▶ 按配置审核 ──▶ 发布到频道
+```
+
+用户在 Bot 私聊或 Mini App 上传内容，先在预览里确认标签、标题、简介、链接及匿名、剧透设置，
+再提交。是否进入审核由投稿入口决定：
+
+| 投稿入口 | 默认行为 |
+| --- | --- |
+| Bot 私聊 | 确认后直接发布；`CHAT_REVIEW_REQUIRED=true` 时先审核 |
+| Mini App | 默认先审核；由 `MINIAPP_REVIEW_REQUIRED` 单独控制 |
+| HTTP API | 固定先提交审核，必须人工批准 |
+
+通过 HTTP API 提交的自动化稿件（含 PixivFlow 等上游服务）必须人工批准。
+`API_REVIEW_REQUIRED` 只保留兼容，不能关闭 API 审核。默认配置会用到审核群，
+因此 `REVIEW_CHAT_ID` 必填，且不能与发布频道相同；
+完整默认值、审核行为与保留策略见[配置参考](https://github.com/redtidev1918/TelePost/blob/main/docs/CONFIGURATION.md#审核)。
+
+## 下载与安装
+
+按运行环境选择一种安装方式，完成后继续[首次使用](#首次使用)。
+
+**独立程序（不需要 Python）** —— 从[下载页](https://github.com/redtidev1918/TelePost/blob/main/docs/download.md)
+或 [Releases](https://github.com/redtidev1918/TelePost/releases/latest) 取得对应平台的文件：
+Windows x64 是 `telepost-windows-x64.exe`，Linux x64 是 `telepost-linux-x64`，
+macOS（Apple Silicon）是 `telepost-macos-arm64`。放在一个固定文件夹里，运行配置向导：
+
+```powershell
+.\telepost-windows-x64.exe --setup
+```
+
+Linux / macOS 首次运行前先赋予执行权限：
+
+```bash
+chmod +x telepost-linux-x64
+./telepost-linux-x64 --setup
+```
+
+macOS 将上述文件名换成 `telepost-macos-arm64`。
+
+**pip（已有 Python 3.10+ 环境）**：
+
+```bash
+python -m pip install telepost-bot
+telepost --setup
+```
+
+PyPI 分发包名是 `telepost-bot`，安装后的命令是 `telepost`；配置与数据保持在当前工作目录，
+之后请始终从同一目录启动。建议安装系统 [libvips](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md#libvips-系统依赖)：
+缺少它也能正常投稿，只是超大图片的流式缩放不可用。
+
+**Docker（服务器或长期部署）** —— 下载或克隆仓库，在根目录准备 `.env`（`TOKEN`、
+`CHANNEL_ID`、`OWNER_ID`、`REVIEW_CHAT_ID` 与固定的 `TELEPOST_VERSION`），然后启动：
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+升级、卸载、系统依赖和全部配置项见[安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md)。
+接收模式与公网 HTTPS 的要求见[更多能力](#更多能力)。
+
+## 首次使用
+
+1. **创建 Bot** —— 在 [@BotFather](https://t.me/BotFather) 创建 Bot 并取得 Token。
+2. **准备频道和审核群** —— 把 Bot 加为发布频道的管理员并授予发帖权限；再把它加入一个
+   **独立**的私有审核群，确认它能在群里发送消息。频道 ID 可以用 `@频道用户名` 或
+   `-100` 开头的数字 ID；Owner ID 是你自己的数字 Telegram User ID，不是群或频道 ID。
+3. **补齐配置并启动** —— 独立程序与 pip 的配置向导只询问 Token、频道和 Owner ID。打开它生成的
+   `config.ini`，保留已有内容，在 `[BOT]` 节补上审核群（文件保存为 UTF-8），然后启动：
+
+   ```ini
+   [BOT]
+   LANGUAGE = zh
+   REVIEW_CHAT_ID = -1001234567890
+   ```
+
+   把示例 ID 换成你的审核群 ID。Windows 独立程序可双击启动；Linux / macOS 运行对应的
+   `./telepost-linux-x64` 或 `./telepost-macos-arm64`；pip 用 `telepost`。
+   Docker 用户在前述 `.env` 中填写配置，无需运行向导或编辑 `config.ini`。
+4. **发起第一次投稿** —— 私聊 Bot 发送 `/start`，点击「📝 开始投稿」或发送 `/submit`；
+   上传图片、视频、GIF、音频或文件，完成后发送 `/done_media` 进入预览；纯文字投稿用
+   `/skip_media` 跳过上传。在预览里填写标签和文字内容、按需修改，最后点击「✅ 确认发布」
+   （开启聊天审核后是「✅ 提交审核」）。随时可以发送 `/cancel` 取消。
+
+全部命令见[命令参考](https://github.com/redtidev1918/TelePost/blob/main/docs/COMMANDS.md)。
+
+## Mini App（可选）
+
+Mini App 是同一程序自带的网页界面：用户在手机上浏览公开内容、投稿并跟踪自己的投稿；
+审核员和管理员可以处理审核队列、编辑文案与附件顺序、管理角色与黑名单。
+
+启用需要公网 HTTPS 地址，并在环境变量中设置 `MINIAPP_SESSION_SECRET`。网页前端由程序
+自己的 HTTP 服务提供，目前只在 Webhook 模式下挂载。私聊入口需启用 `MINIAPP_ENABLED`
+并配置 `MINIAPP_PUBLIC_URL`（可从 `WEBHOOK_URL` 推导）；缺少密钥时，入口即使显示也无法登录。
+如需通过 `?startapp=` 链接直接打开，还要在 BotFather 配置 Main Mini App。
+
+身份来自 Telegram，并在服务端用 `initData` 校验。在普通浏览器里直接打开网址不等于登录，
+也不会获得审核或管理权限。配置与部署步骤见
+[Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md)。
+
+## AI 辅助审核（MCP，可选）
+
+MCP 是 AI Agent 调用外部工具的协议。TelePost 可通过 MCP 连接 Codex、Claude 等 AI Agent，
+让它们查看待审核稿件、依据频道审核规则提出建议，
+并在你明确授权、权限允许时执行审核操作。
+
+TelePost 不内置大语言模型，也不会自行调用 AI 审核。推荐把 MCP 与审核 API 都设为只读，
+只让 AI 提供建议；启用写入权限后，应在执行具体操作前取得人工确认，但程序不强制这一步。
+工具列表、Token 与接入配置见
+[MCP 投稿审核](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)。
+
+## 更多能力
+
+- **HTTP API** —— 供脚本或其他服务发送投稿请求，与 Bot 共用审核与发布流程，示例见下方。
+- **TXT 小说与在线阅读** —— TXT 照常作为文件发布；可选启用 TelePress 生成 Telegraph 阅读页，
+  失败不影响发布。
+- **Webhook 与 Polling** —— Polling 由 Bot 主动获取 Telegram 消息，无需域名或公网 HTTPS；
+  Webhook 由 Telegram 将消息推送给 Bot，需要公网 HTTPS 地址。Mini App 同样需要公网 HTTPS。
+- **文件类型过滤** —— 默认拦截可执行文件、常见脚本和压缩包，三个投稿入口都会检查。
+- **服务器部署** —— 提供 Docker 镜像与 Fly.io 配置，备份与运行状态见
+  [运维手册](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md)。
+
+<details>
+<summary>HTTP API 投稿示例</summary>
+
+Owner 在 Bot 中用 `/gen_token <名称>` 生成 Token，明文只显示一次：
+
+```bash
+curl -X POST 'https://example.com/api/v1/submissions' \
+  -H 'Authorization: Bearer tp_xxxx' \
+  -F 'files=@image.jpg' \
+  -F 'title=示例稿件' \
+  -F 'tags=插画' \
+  -F 'idempotency_key=source:123'
+```
+
+多 Bot 部署把地址换成 `/api/botN/v1/submissions`。审核规则见[如何工作](#如何工作)，完整字段与限制见
+[HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/API.md)。
+
+</details>
+
+## 常见问题
+
+<details>
+<summary>需要服务器和域名吗？</summary>
+
+需要一台可以长期运行的电脑或服务器。使用 Bot 私聊与审核群时，可选择 Polling，无需域名；
+Webhook 和 Mini App 的公网要求见[更多能力](#更多能力)。
+详见[安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md)。
+
+</details>
+
+<details>
+<summary>私聊投稿为什么直接发布了？</summary>
+
+Bot 私聊投稿默认在用户确认后直接发布。设置 `CHAT_REVIEW_REQUIRED=true` 可改为先审核，
+不影响其他入口。各入口的默认行为见[如何工作](#如何工作)。
+
+</details>
+
+<details>
+<summary>Mini App 为什么没有出现？</summary>
+
+先检查 `MINIAPP_ENABLED` 和入口网址是否配置，再确认 Webhook 模式下网页可访问。
+入口显示却无法登录时，检查环境变量中的 `MINIAPP_SESSION_SECRET`，并从 Telegram 内打开。
+启用条件见 [Mini App](#mini-app可选)，排查步骤见
+[Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md)。
+
+</details>
+
+<details>
+<summary>Bot 为什么没有响应？</summary>
+
+先确认同一个 Bot Token 只被一个实例使用，再看进程状态、最近日志和 `/health`；Webhook 模式
+还要检查 `getWebhookInfo`。同时启动源码、容器或旧机器会造成 Polling 冲突。详见
+[故障排查](https://github.com/redtidev1918/TelePost/blob/main/docs/TROUBLESHOOTING.md#bot-完全无响应)。
+
+</details>
+
+<details>
+<summary>投稿文件保存在哪里？</summary>
+
+默认数据保存在 `data/`（pip 安装时位于启动命令的工作目录）：稿件库 `submissions.db`、
+会话状态 `persistence.pickle`、运行策略 `runtime-policy.json`、搜索索引 `search_index`
+和 API 临时上传 `api_uploads/`；
+多 Bot 各自使用 `data/botN/`。媒体本身保存在 Telegram 侧，数据库只记录引用。升级或迁移时
+备份并保留整个 `data/`，备份方法见[运维手册](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md#持久数据)。
+
+</details>
+
+<details>
+<summary>MCP 会自动替我批准内容吗？</summary>
+
+是否能执行批准取决于权限：`TELEPOST_MCP_REVIEW_MODE=readonly` 不注册审核写入工具，
+`TELEPOST_REVIEW_API_MODE=readonly` 则在服务端拒绝写入。建议两层都设为只读；
+启用写入后的人工确认要求见[AI 辅助审核](#ai-辅助审核mcp可选)。完整配置见
+[MCP 投稿审核](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)。
+
+</details>
+
+## 文档
+
+完整文档站：<https://redtidev1918.github.io/TelePost/>
+
+- 安装、升级与卸载 —— [安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md)
+- 命令与所需权限 —— [命令参考](https://github.com/redtidev1918/TelePost/blob/main/docs/COMMANDS.md)
+- 配置项、审核默认值与多 Bot —— [配置参考](https://github.com/redtidev1918/TelePost/blob/main/docs/CONFIGURATION.md)
+- 网页投稿与审核界面 —— [Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md)
+- 脚本与自动化投稿 —— [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/API.md)
+- AI Agent 参与审核 —— [MCP 投稿审核](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)
+- 接收模式与反向代理 —— [Webhook 与 Polling](https://github.com/redtidev1918/TelePost/blob/main/docs/WEBHOOK_MODE.md)
+- 部署到 Fly.io —— [Fly.io 部署](https://github.com/redtidev1918/TelePost/blob/main/docs/FLYIO_DEPLOYMENT.md)
+- 备份、升级与运行状态 —— [运维手册](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md)
+- 排查无响应、上传或发布失败 —— [故障排查](https://github.com/redtidev1918/TelePost/blob/main/docs/TROUBLESHOOTING.md)
+- 评估内存与容量 —— [性能与容量](https://github.com/redtidev1918/TelePost/blob/main/docs/PERFORMANCE.md)
+- 开发与测试 —— [测试指南](https://github.com/redtidev1918/TelePost/blob/main/docs/TESTING.md)、[贡献指南](https://github.com/redtidev1918/TelePost/blob/main/CONTRIBUTING.md)
+
+## 相关项目
+
+- [PixivFlow](https://github.com/redtidev1918/PixivFlow) —— Pixiv 下载、筛选与自动收集工具，
+  可通过 HTTP API 把作品投稿到 TelePost。
+- [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy) ——
+  PixivFlow + TelePost 的组合部署。
+
+两者都是可选集成，不是运行 TelePost 的必需依赖。
+
+## 许可证
+
+[MIT License](https://github.com/redtidev1918/TelePost/blob/main/LICENSE)

telepost_bot-2.83.2/README.en.md

@@ -0,0 +1,292 @@
+# TelePost
+
+**Language / 语言:** [中文](https://github.com/redtidev1918/TelePost/blob/main/README.md) · English
+
+TelePost is an open-source, self-hosted submission and moderation bot for Telegram channels.
+Readers submit work through the bot's private chat, the Mini App or the HTTP API; submissions that
+need review are viewed, edited and decided by the admins in the review group.
+
+[![Release](https://img.shields.io/github/v/release/redtidev1918/TelePost)](https://github.com/redtidev1918/TelePost/releases/latest) [![PyPI](https://img.shields.io/pypi/v/telepost-bot.svg)](https://pypi.org/project/telepost-bot/) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/redtidev1918/TelePost/blob/main/LICENSE) [![Documentation](https://img.shields.io/badge/docs-redtidev1918.github.io-6366f1)](https://redtidev1918.github.io/TelePost/#/en/)
+
+[Download](https://github.com/redtidev1918/TelePost/blob/main/docs/en/download.md) · [Install and deploy](https://github.com/redtidev1918/TelePost/blob/main/docs/en/INSTALL.md) · [Documentation](https://redtidev1918.github.io/TelePost/#/en/)
+
+## Screenshots
+
+![Bot private-chat main menu](https://raw.githubusercontent.com/redtidev1918/TelePost/main/docs/assets/screenshots/bot-menu.jpg)
+
+The bot's main menu: submit work, follow your own submissions, search the channel, or browse
+rankings and tags.
+
+<!-- Real screenshots still to add, in priority order: (1) submission preview and editing; (2) moderation actions in the review group; (3) the Telegram Mini App. -->
+
+## What it does
+
+| Feature | Description |
+| --- | --- |
+| Submissions | Photos, videos, GIFs, audio, documents and plain text; preview and edit before submitting, with anonymous and spoiler modes. |
+| Review and publishing | View previews and publish, reject or spoiler submissions in a private review group; refetch-capable automated submissions can swap candidates, and the replacement still needs human review. |
+| Mini App | Optional web interface: users browse, submit and track their own work; reviewers and admins review, edit and manage. |
+| Search and rankings | `/search` by keyword (with `#tag` and time-range filters), `/tags` for the tag cloud, `/hot` and `/hotweek` for rankings, `/myposts` and `/mystats` for your own submissions and statistics. |
+| Scheduled posts | Commands such as `/schedule add weekly-hot` publish rankings on a schedule. |
+| Automated submissions | Scripts or upstream services submit through the HTTP API; an `idempotency_key` keeps retries from duplicating reviews or publications. |
+| AI-assisted review | Optionally connect AI agents such as Codex or Claude through MCP to read pending submissions and offer review suggestions. |
+| Multiple bots, self-hosted | Run several bots on one machine, each with its own channel, review group, language and data directory. |
+
+Default review rules per entry point: [How it works](#how-it-works). Integrations and deployment:
+[More capabilities](#more-capabilities).
+
+## How it works
+
+```text
+Reader submits ──▶ Preview and edit ──▶ Review (per entry point) ──▶ Published to the channel
+```
+
+A reader uploads content in the bot's private chat or the Mini App, then confirms tags, title, note,
+link and the anonymous and spoiler settings in the preview before submitting. Whether it goes
+through review depends on the entry point:
+
+| Entry point | Default |
+| --- | --- |
+| Bot private chat | Published after the reader confirms; `CHAT_REVIEW_REQUIRED=true` requires review |
+| Mini App | Review by default; controlled separately by `MINIAPP_REVIEW_REQUIRED` |
+| HTTP API | Always submitted for review; a human must approve |
+
+Automated submissions sent through the HTTP API (including PixivFlow and other upstream services)
+must be approved by a human. `API_REVIEW_REQUIRED` is kept for compatibility and cannot turn review
+off for the API. The default setup uses a review group, so `REVIEW_CHAT_ID` is required and must
+not be the same as the channel.
+Full defaults, moderation behaviour and retention are in
+[Configuration](https://github.com/redtidev1918/TelePost/blob/main/docs/en/CONFIGURATION.md#review).
+
+## Download and install
+
+Pick the option that matches your environment, then continue with [First run](#first-run).
+
+**Standalone program (no Python)** — Take the file for your platform from the
+[download page](https://github.com/redtidev1918/TelePost/blob/main/docs/en/download.md) or
+[Releases](https://github.com/redtidev1918/TelePost/releases/latest):
+`telepost-windows-x64.exe` for Windows x64, `telepost-linux-x64` for Linux x64, and
+`telepost-macos-arm64` for macOS (Apple Silicon). Keep it in one folder and run the setup wizard:
+
+```powershell
+.\telepost-windows-x64.exe --setup
+```
+
+On Linux / macOS, make it executable first:
+
+```bash
+chmod +x telepost-linux-x64
+./telepost-linux-x64 --setup
+```
+
+**pip (Python 3.10+ already installed)**:
+
+```bash
+python -m pip install telepost-bot
+telepost --setup
+```
+
+The PyPI package is `telepost-bot` and the command it installs is `telepost`. Configuration and data
+stay in the current working directory, so always start from the same one. Installing system
+[libvips](https://github.com/redtidev1918/TelePost/blob/main/docs/en/INSTALL.md#libvips-system-dependency)
+is recommended: without it everything still works, but streaming downscale of very large images is
+unavailable.
+
+**Docker (servers or long-running deployments)** — Download or clone the repository, create a
+`.env` in its root (`TOKEN`, `CHANNEL_ID`, `OWNER_ID`, `REVIEW_CHAT_ID` and a pinned
+`TELEPOST_VERSION`), then start:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Upgrades, removal, system dependencies and every setting: [Install and deploy](https://github.com/redtidev1918/TelePost/blob/main/docs/en/INSTALL.md).
+Receiving modes and their public HTTPS requirements: [More capabilities](#more-capabilities).
+
+## First run
+
+1. **Create the bot** — Create it with [@BotFather](https://t.me/BotFather) and keep the token.
+2. **Prepare the channel and review group** — Add the bot to the publishing channel as an
+   administrator with permission to post, then add it to a **separate** private review group and
+   check that it can send messages there. The channel ID is either `@username` or a numeric ID
+   starting with `-100`; the owner ID is your own numeric Telegram user ID, not a group or channel
+   ID.
+3. **Complete the configuration and start** — The setup wizards of the standalone program and the
+   pip package ask only for the token, the channel and the owner ID. Open the generated
+   `config.ini`, keep what is there, add the review group under `[BOT]` (save the file as UTF-8),
+   then start:
+
+   ```ini
+   [BOT]
+   LANGUAGE = en
+   REVIEW_CHAT_ID = -1001234567890
+   ```
+
+   Replace the example ID with your review group ID. Start commands: double-click the Windows
+   standalone program, or run `./telepost-linux-x64` / `./telepost-macos-arm64` on Linux / macOS;
+   `telepost` for pip. Docker users configure the `.env` above — no wizard, no `config.ini`.
+4. **Make a first submission** — Send `/start` to the bot, tap **📝 New submission** or send
+   `/submit`, then upload photos, videos, GIFs, audio or files and send `/done_media` when done to
+   reach the preview; for a text-only submission, `/skip_media` skips the upload. Fill in tags and
+   text, adjust what you need, and tap **✅ Publish** (the button reads **✅ Submit for review**
+   when chat review is on). Send `/cancel` at any point to cancel.
+
+All commands: [Command reference](https://github.com/redtidev1918/TelePost/blob/main/docs/en/COMMANDS.md).
+
+## Mini App (optional)
+
+The Mini App is a web interface that ships with the same program: readers browse published content,
+submit and follow their own work on a phone; reviewers and admins handle the review queue, edit text
+and attachment order, and manage roles and the blacklist.
+
+Enabling it requires a public HTTPS address and `MINIAPP_SESSION_SECRET` set in the environment.
+The web frontend is served by the program's own HTTP service and is currently mounted only in
+Webhook mode. The private-chat entry needs `MINIAPP_ENABLED` on and `MINIAPP_PUBLIC_URL` configured
+(it can be derived from `WEBHOOK_URL`); without the secret, the entry shows but login fails. To
+open it through `?startapp=` links, also configure a Main Mini App in BotFather.
+
+Identity comes from Telegram and is verified server-side from `initData`. Opening the URL in a
+normal browser is not a login, and it grants no review or admin rights. Setup steps:
+[Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md) (Chinese).
+
+## AI-assisted review (MCP, optional)
+
+MCP is the protocol AI agents use to call external tools. TelePost can connect to agents such as
+Codex or Claude through [MCP](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)
+(Chinese): they read pending submissions, suggest decisions based on your channel's review policy,
+and perform moderation actions only when you explicitly ask and their permissions allow it.
+
+TelePost bundles no language model and never calls an AI to moderate on its own. Keeping both MCP
+and the review API read-only is recommended, leaving the agent advisory only; once write access is
+enabled, get human confirmation before concrete actions — the program does not enforce this step.
+Tool list, tokens and connection setup:
+[MCP review](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md) (Chinese).
+
+## More capabilities
+
+- **HTTP API** — for scripts and other services to send submissions, sharing the bot's review and
+  publishing pipeline; see the example below.
+- **TXT novels and online reading** — TXT is published as a document; TelePress can optionally build
+  a Telegraph reading page, and a failure never affects the publication.
+- **Webhook and Polling** — with Polling the bot pulls messages from Telegram and needs no domain
+  or public HTTPS; with Webhook, Telegram pushes updates to the bot and a public HTTPS address is
+  required. The Mini App also requires public HTTPS.
+- **File type filtering** — executables, common scripts and archives are blocked by default in all
+  three submission entry points.
+- **Server deployment** — Docker images and a Fly.io setup; backups and runtime state are covered in
+  [Operations](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md) (Chinese).
+
+<details>
+<summary>HTTP API submission example</summary>
+
+An owner generates a token in the bot with `/gen_token <name>`; the plaintext is shown only once:
+
+```bash
+curl -X POST 'https://example.com/api/v1/submissions' \
+  -H 'Authorization: Bearer tp_xxxx' \
+  -F 'files=@image.jpg' \
+  -F 'title=Example post' \
+  -F 'tags=illustration' \
+  -F 'idempotency_key=source:123'
+```
+
+Multi-bot deployments use `/api/botN/v1/submissions` instead. Review rules: [How it works](#how-it-works);
+full fields and limits are in [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/en/API.md).
+
+</details>
+
+## FAQ
+
+<details>
+<summary>Do I need a server and a domain?</summary>
+
+You need a machine that stays on. Polling mode with the bot's private chat and a review group
+needs no domain; the public HTTPS requirements of Webhook and the Mini App are in
+[More capabilities](#more-capabilities). See
+[Install and deploy](https://github.com/redtidev1918/TelePost/blob/main/docs/en/INSTALL.md).
+
+</details>
+
+<details>
+<summary>Why was my private-chat submission published directly?</summary>
+
+Private-chat submissions are published after the reader confirms by default. Set
+`CHAT_REVIEW_REQUIRED=true` to send them to the review group first; other entry points are not
+affected. Default behaviour per entry point: [How it works](#how-it-works).
+
+</details>
+
+<details>
+<summary>Why doesn't the Mini App show up?</summary>
+
+First check that `MINIAPP_ENABLED` is on and the entry URL is configured, then that the page is
+reachable in Webhook mode. If the entry shows but login fails, check `MINIAPP_SESSION_SECRET` in
+the environment and open the app from inside Telegram. Enabling conditions:
+[Mini App](#mini-app-optional); troubleshooting steps:
+[Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md) (Chinese).
+
+</details>
+
+<details>
+<summary>Why does the bot not respond?</summary>
+
+Check that only one instance uses the bot token, then look at the process, the recent logs and
+`/health`; in Webhook mode also check `getWebhookInfo`. Running the source, a container and an old
+machine at the same time causes a Polling conflict. See
+[Troubleshooting](https://github.com/redtidev1918/TelePost/blob/main/docs/TROUBLESHOOTING.md#bot-完全无响应) (Chinese).
+
+</details>
+
+<details>
+<summary>Where are submission files stored?</summary>
+
+By default under `data/` (for a pip install, in the working directory where the command starts):
+the submission database `submissions.db`, session state `persistence.pickle`, runtime policy
+`runtime-policy.json`, the search index `search_index` and API temporary uploads `api_uploads/`;
+multiple bots use `data/botN/`. Media itself stays on Telegram's side and the database only stores
+references. Back up and keep the whole `data/` directory when upgrading or moving; backup method:
+[Operations](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md#持久数据) (Chinese).
+
+</details>
+
+<details>
+<summary>Will MCP approve content for me?</summary>
+
+Whether it can depends on permissions: `TELEPOST_MCP_REVIEW_MODE=readonly` does not register the
+moderation write tools, and `TELEPOST_REVIEW_API_MODE=readonly` rejects writes server-side. Keeping
+both layers read-only is recommended; for the human-confirmation expectation after enabling writes,
+see [AI-assisted review](#ai-assisted-review-mcp-optional). Full configuration:
+[MCP review](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md) (Chinese).
+
+</details>
+
+## Documentation
+
+Documentation site: <https://redtidev1918.github.io/TelePost/#/en/>
+
+- Install, upgrade, remove — [Install and deploy](https://github.com/redtidev1918/TelePost/blob/main/docs/en/INSTALL.md)
+- Commands and required permissions — [Command reference](https://github.com/redtidev1918/TelePost/blob/main/docs/en/COMMANDS.md)
+- Settings, review defaults, multiple bots — [Configuration](https://github.com/redtidev1918/TelePost/blob/main/docs/en/CONFIGURATION.md)
+- Web submission and review UI — [Telegram Mini App](https://github.com/redtidev1918/TelePost/blob/main/docs/MINIAPP.md) (Chinese)
+- Scripts and automated submissions — [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/en/API.md)
+- AI agents in review — [MCP review](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md) (Chinese)
+- Receiving modes and reverse proxies — [Webhook and Polling](https://github.com/redtidev1918/TelePost/blob/main/docs/WEBHOOK_MODE.md) (Chinese)
+- Deploying to Fly.io — [Fly.io deployment](https://github.com/redtidev1918/TelePost/blob/main/docs/FLYIO_DEPLOYMENT.md) (Chinese)
+- Backups, upgrades, runtime state — [Operations](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md) (Chinese)
+- Unresponsive bot, failed upload or publish — [Troubleshooting](https://github.com/redtidev1918/TelePost/blob/main/docs/TROUBLESHOOTING.md) (Chinese)
+- Memory and capacity — [Performance](https://github.com/redtidev1918/TelePost/blob/main/docs/PERFORMANCE.md) (Chinese)
+- Development and testing — [Testing guide](https://github.com/redtidev1918/TelePost/blob/main/docs/TESTING.md) (Chinese), [Contributing](https://github.com/redtidev1918/TelePost/blob/main/CONTRIBUTING.md) (Chinese)
+
+## Related projects
+
+- [PixivFlow](https://github.com/redtidev1918/PixivFlow) — Pixiv downloading, filtering and
+  automated collection; it can submit work to TelePost through the HTTP API.
+- [pixivflow-telepost-deploy](https://github.com/redtidev1918/pixivflow-telepost-deploy) — a
+  combined PixivFlow + TelePost deployment.
+
+Both are optional integrations, not runtime dependencies of TelePost.
+
+## License
+
+[MIT License](https://github.com/redtidev1918/TelePost/blob/main/LICENSE)