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

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

@@ -8,6 +8,13 @@
 > 发布说明面向普通用户：写「对用户有什么改变」，不写内部实现细节（模块名、函数名、配置键）；
 > 技术细节放进代码注释或 `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)
 
 

{telepost_bot-2.83.1/telepost_bot.egg-info → telepost_bot-2.83.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telepost-bot
-Version: 2.83.1
+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
@@ -50,8 +50,8 @@ Dynamic: license-file
 
 **语言 / Language:** 中文 · [English](https://github.com/redtidev1918/TelePost/blob/main/README.en.md)
 
-TelePost 是一个开源、自托管的 Telegram 频道投稿与审核 Bot。用户可以向频道投稿，
-管理员在审核群里查看、修改并决定是否发布。
+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/)
 
@@ -69,13 +69,13 @@ Bot 私聊主菜单。用户在这里投稿、查看自己的投稿、搜索频
 
 | 功能 | 说明 |
 | --- | --- |
-| 便捷投稿 | 从 Bot 私聊或 Mini App 提交图片、视频、GIF、音频、文档或纯文字，提交前在预览里改标签、标题、简介和链接，可开启匿名或剧透。 |
-| 审核与发布 | 稿件连同预览发到私有审核群，用「✅ 发布到频道 / ❌ 拒绝 / 🔇 遮罩」决定；自动化稿件可「🔄 重抓」换候选，替换后仍需人工审核。 |
-| Mini App | 可选网页界面：手机浏览公开内容、投稿并跟踪自己的投稿；审核员与管理员处理审核队列、编辑文案与附件顺序、管理角色和黑名单。 |
+| 投稿 | 支持图片、视频、GIF、音频、文档和纯文字，提交前可预览、编辑，支持匿名与剧透。 |
+| 审核与发布 | 在私有审核群查看预览、发布、拒绝或遮罩稿件；支持重抓的自动化稿件可更换候选，替换后仍需人工审核。 |
+| Mini App | 可选网页界面，供用户浏览、投稿和查看进度，供审核员与管理员审核、编辑和管理。 |
 | 搜索与热榜 | `/search` 关键词检索（支持 `#标签` 和时间范围），`/tags` 标签云，`/hot`、`/hotweek` 热榜，`/myposts`、`/mystats` 个人投稿与统计。 |
 | 定时发布 | `/schedule add weekly-hot` 等命令按计划发布热榜内容。 |
-| 自动化投稿 | Owner 用 `/gen_token` 生成 Token 后即可用 HTTP API 投稿，`idempotency_key` 保证重试不重复审核或发布。 |
-| AI 辅助审核 | 可选接入 MCP，让 Codex、Claude 等 Agent 查看待审稿件并给出建议；不内置大语言模型，是否发布由人决定。 |
+| 自动化投稿 | 脚本或上游服务通过 HTTP API 投稿，使用 `idempotency_key` 避免重试产生重复审核或发布。 |
+| AI 辅助审核 | 可选通过 MCP 接入 Codex、Claude 等 AI Agent，查看待审稿件并提供审核建议。 |
 | 多 Bot 与自托管 | 同一台机器可并行运行多个 Bot，各自使用独立的频道、审核群、语言和数据目录。 |
 
 各入口的默认审核规则见[如何工作](#如何工作)，集成与部署细节见[更多能力](#更多能力)。
@@ -86,22 +86,23 @@ Bot 私聊主菜单。用户在这里投稿、查看自己的投稿、搜索频
 用户投稿 ──▶ 预览与编辑 ──▶ 按配置审核 ──▶ 发布到频道
 ```
 
-用户在 Bot 私聊或 Mini App 上传内容，先在预览里确认标签、标题、简介、链接、匿名和剧透，
+用户在 Bot 私聊或 Mini App 上传内容，先在预览里确认标签、标题、简介、链接及匿名、剧透设置，
 再提交。是否进入审核由投稿入口决定：
 
 | 投稿入口 | 默认行为 |
 | --- | --- |
 | Bot 私聊 | 确认后直接发布；`CHAT_REVIEW_REQUIRED=true` 时先审核 |
-| Mini App | 先提交审核，由 `MINIAPP_REVIEW_REQUIRED` 单独控制 |
+| Mini App | 默认先审核；由 `MINIAPP_REVIEW_REQUIRED` 单独控制 |
 | HTTP API | 固定先提交审核，必须人工批准 |
 
-自动化投稿（含 PixivFlow 等上游服务）同样要人工批准，`API_REVIEW_REQUIRED` 只保留兼容、
-不能关闭 API 审核。默认配置会用到审核群，因此 `REVIEW_CHAT_ID` 必填，且不能与发布频道相同；
+通过 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) 取得对应平台的文件：
@@ -119,6 +120,8 @@ chmod +x telepost-linux-x64
 ./telepost-linux-x64 --setup
 ```
 
+macOS 将上述文件名换成 `telepost-macos-arm64`。
+
 **pip（已有 Python 3.10+ 环境）**：
 
 ```bash
@@ -130,8 +133,8 @@ 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`），然后启动：
+**Docker（服务器或长期部署）** —— 下载或克隆仓库，在根目录准备 `.env`（`TOKEN`、
+`CHANNEL_ID`、`OWNER_ID`、`REVIEW_CHAT_ID` 与固定的 `TELEPOST_VERSION`），然后启动：
 
 ```bash
 docker compose pull
@@ -139,7 +142,7 @@ docker compose up -d
 ```
 
 升级、卸载、系统依赖和全部配置项见[安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md)。
-普通 Polling Bot 不需要域名或公网 HTTPS，只有 Webhook 接收模式和 Mini App 需要。
+接收模式与公网 HTTPS 的要求见[更多能力](#更多能力)。
 
 ## 首次使用
 
@@ -147,7 +150,7 @@ docker compose up -d
 2. **准备频道和审核群** —— 把 Bot 加为发布频道的管理员并授予发帖权限；再把它加入一个
    **独立**的私有审核群，确认它能在群里发送消息。频道 ID 可以用 `@频道用户名` 或
    `-100` 开头的数字 ID；Owner ID 是你自己的数字 Telegram User ID，不是群或频道 ID。
-3. **补上审核群再启动** —— 配置向导只询问 Token、频道和 Owner ID。打开它生成的
+3. **补齐配置并启动** —— 独立程序与 pip 的配置向导只询问 Token、频道和 Owner ID。打开它生成的
    `config.ini`，保留已有内容，在 `[BOT]` 节补上审核群（文件保存为 UTF-8），然后启动：
 
    ```ini
@@ -156,12 +159,13 @@ docker compose up -d
    REVIEW_CHAT_ID = -1001234567890
    ```
 
-   把示例 ID 换成你的审核群 ID。启动命令：独立程序直接双击或 `./telepost-*`，pip 用
-   `telepost`，Docker 用 `docker compose up -d`。
+   把示例 ID 换成你的审核群 ID。Windows 独立程序可双击启动；Linux / macOS 运行对应的
+   `./telepost-linux-x64` 或 `./telepost-macos-arm64`；pip 用 `telepost`。
+   Docker 用户在前述 `.env` 中填写配置，无需运行向导或编辑 `config.ini`。
 4. **发起第一次投稿** —— 私聊 Bot 发送 `/start`，点击「📝 开始投稿」或发送 `/submit`；
-   上传图片、视频、GIF、音频或文件，只发文字时用 `/skip_media` 直接进入预览，完成后发送
-   `/done_media`。在预览里填写标签、按需修改，最后点击「✅ 确认发布」（开启聊天审核后是
-   「✅ 提交审核」）。随时可以发送 `/cancel` 取消。
+   上传图片、视频、GIF、音频或文件，完成后发送 `/done_media` 进入预览；纯文字投稿用
+   `/skip_media` 跳过上传。在预览里填写标签和文字内容、按需修改，最后点击「✅ 确认发布」
+   （开启聊天审核后是「✅ 提交审核」）。随时可以发送 `/cancel` 取消。
 
 全部命令见[命令参考](https://github.com/redtidev1918/TelePost/blob/main/docs/COMMANDS.md)。
 
@@ -170,9 +174,10 @@ docker compose up -d
 Mini App 是同一程序自带的网页界面：用户在手机上浏览公开内容、投稿并跟踪自己的投稿；
 审核员和管理员可以处理审核队列、编辑文案与附件顺序、管理角色与黑名单。
 
-它不会在装好 Bot 之后自动出现。启用需要公网 HTTPS 地址、`MINIAPP_SESSION_SECRET`，
-以及 Telegram 侧的入口配置；网页前端由程序自己的 HTTP 服务提供，因此运行在 Webhook 模式下
-才会挂载。缺少任一项时，私聊里的入口按钮不会显示。
+启用需要公网 HTTPS 地址，并在环境变量中设置 `MINIAPP_SESSION_SECRET`。网页前端由程序
+自己的 HTTP 服务提供，目前只在 Webhook 模式下挂载。私聊入口需启用 `MINIAPP_ENABLED`
+并配置 `MINIAPP_PUBLIC_URL`（可从 `WEBHOOK_URL` 推导）；缺少密钥时，入口即使显示也无法登录。
+如需通过 `?startapp=` 链接直接打开，还要在 BotFather 配置 Main Mini App。
 
 身份来自 Telegram，并在服务端用 `initData` 校验。在普通浏览器里直接打开网址不等于登录，
 也不会获得审核或管理权限。配置与部署步骤见
@@ -180,22 +185,22 @@ Mini App 是同一程序自带的网页界面：用户在手机上浏览公开
 
 ## AI 辅助审核（MCP，可选）
 
-TelePost 可以通过 [MCP](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)
-连接 Codex、Claude 等支持 MCP 的 AI Agent：查看待审核稿件、依据频道审核规则提出建议，
+MCP 是 AI Agent 调用外部工具的协议。TelePost 可通过 MCP 连接 Codex、Claude 等 AI Agent，
+让它们查看待审核稿件、依据频道审核规则提出建议，
 并在你明确授权、权限允许时执行审核操作。
 
-TelePost 不内置大语言模型，也不会自动审核任何内容，是否发布始终由人决定。推荐把 MCP 与
-审核 API 都设为只读，只让 AI 提供建议。工具列表、Token 与接入配置见
+TelePost 不内置大语言模型，也不会自行调用 AI 审核。推荐把 MCP 与审核 API 都设为只读，
+只让 AI 提供建议；启用写入权限后，应在执行具体操作前取得人工确认，但程序不强制这一步。
+工具列表、Token 与接入配置见
 [MCP 投稿审核](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md)。
 
 ## 更多能力
 
-- **HTTP API** —— 与 Bot 共用同一套审核与发布流程；多 Bot 部署使用
-  `/api/botN/v1/submissions`。字段与限制见 [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/API.md)。
-- **多 Bot** —— 同一台机器并行运行多个 Bot，各自使用独立的频道、审核群、语言和数据目录。
+- **HTTP API** —— 供脚本或其他服务发送投稿请求，与 Bot 共用审核与发布流程，示例见下方。
 - **TXT 小说与在线阅读** —— TXT 照常作为文件发布；可选启用 TelePress 生成 Telegraph 阅读页，
   失败不影响发布。
-- **Webhook 与 Polling** —— 有公网 HTTPS 地址时使用 Webhook，否则使用 Polling。
+- **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)。
@@ -214,7 +219,7 @@ curl -X POST 'https://example.com/api/v1/submissions' \
   -F 'idempotency_key=source:123'
 ```
 
-多 Bot 部署把地址换成 `/api/botN/v1/submissions`。API 投稿固定进入审核，完整字段与限制见
+多 Bot 部署把地址换成 `/api/botN/v1/submissions`。审核规则见[如何工作](#如何工作)，完整字段与限制见
 [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/API.md)。
 
 </details>
@@ -224,8 +229,8 @@ curl -X POST 'https://example.com/api/v1/submissions' \
 <details>
 <summary>需要服务器和域名吗？</summary>
 
-不需要域名或公网 HTTPS 也能用：在一台可以长期运行的电脑或服务器上以 Polling 模式运行，
-配合 Bot 私聊与审核群即可。只有 Webhook 接收模式和 Mini App 需要公网 HTTPS 地址。
+需要一台可以长期运行的电脑或服务器。使用 Bot 私聊与审核群时，可选择 Polling，无需域名；
+Webhook 和 Mini App 的公网要求见[更多能力](#更多能力)。
 详见[安装与部署](https://github.com/redtidev1918/TelePost/blob/main/docs/INSTALL.md)。
 
 </details>
@@ -233,17 +238,17 @@ curl -X POST 'https://example.com/api/v1/submissions' \
 <details>
 <summary>私聊投稿为什么直接发布了？</summary>
 
-Bot 私聊投稿默认在用户确认后直接发布（`CHAT_REVIEW_REQUIRED=false`）。把它设为 `true`，
-私聊投稿就会先进入审核群。Mini App 与 HTTP API 不受这个开关影响，默认都要先审核。
-详见[配置参考](https://github.com/redtidev1918/TelePost/blob/main/docs/CONFIGURATION.md#审核)。
+Bot 私聊投稿默认在用户确认后直接发布。设置 `CHAT_REVIEW_REQUIRED=true` 可改为先审核，
+不影响其他入口。各入口的默认行为见[如何工作](#如何工作)。
 
 </details>
 
 <details>
 <summary>Mini App 为什么没有出现？</summary>
 
-Mini App 是可选组件：需要公网 HTTPS 地址、`MINIAPP_SESSION_SECRET`、Webhook 模式和
-Telegram 侧的入口配置，缺少任一项时入口不会显示。详见
+先检查 `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>
@@ -260,19 +265,20 @@ Telegram 侧的入口配置，缺少任一项时入口不会显示。详见
 <details>
 <summary>投稿文件保存在哪里？</summary>
 
-数据都在程序目录下的 `data/`：稿件库 `submissions.db`、会话状态 `persistence.pickle`、
-运行策略 `runtime-policy.json`、搜索索引 `search_index` 和 API 临时上传 `api_uploads/`；
+默认数据保存在 `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#持久数据)。
+备份并保留整个 `data/`，备份方法见[运维手册](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md#持久数据)。
 
 </details>
 
 <details>
 <summary>MCP 会自动替我批准内容吗？</summary>
 
-不会。TelePost 不内置大语言模型，MCP 是可选组件：审核写入工具只在非只读模式下注册，并同时
-受 MCP 与审核 API 权限开关的限制。人工确认是推荐流程，不是强制机制；把两层都设为只读，
-AI 就只能给出建议。详见
+是否能执行批准取决于权限：`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>

{telepost_bot-2.83.1 → telepost_bot-2.83.2}/README.en.md

@@ -3,8 +3,8 @@
 **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 or the Mini App; you check, edit and decide
-what gets published.
+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/)
 
@@ -23,13 +23,13 @@ rankings and tags.
 
 | Feature | Description |
 | --- | --- |
-| Easy submissions | Send photos, videos, GIFs, audio, documents or plain text from the bot's private chat or the Mini App; the preview fixes tags, title, note and link, and switches on anonymous or spoiler mode. |
-| Review and publishing | The submission and its preview go to your private review group with **✅ Publish to channel / ❌ Reject / 🔇 Spoiler** buttons; automated submissions can **🔄 Refetch** a different candidate, which still needs a human decision. |
-| Mini App | Optional web interface: browse published content, submit and follow your own work on a phone; reviewers and admins handle the review queue, edit text and attachment order, and manage roles and the blacklist. |
+| 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 | An owner generates a token with `/gen_token` and programs submit through the HTTP API; an `idempotency_key` makes retries safe. |
-| AI-assisted review | An optional MCP sidecar lets agents such as Codex or Claude read pending submissions and suggest decisions; no language model is bundled and a human always decides. |
+| 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:
@@ -42,24 +42,25 @@ Reader submits ──▶ Preview and edit ──▶ Review (per entry point) ─
 ```
 
 A reader uploads content in the bot's private chat or the Mini App, then confirms tags, title, note,
-link, anonymous and spoiler in the preview. Whether it goes through review depends on the entry
-point:
+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 | Submitted for review, controlled by `MINIAPP_REVIEW_REQUIRED` |
+| Mini App | Review by default; controlled separately by `MINIAPP_REVIEW_REQUIRED` |
 | HTTP API | Always submitted for review; a human must approve |
 
-Automated submissions (including PixivFlow and other upstream services) also need human approval:
-`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.
+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 path that matches your setup.
+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
@@ -91,8 +92,9 @@ stay in the current working directory, so always start from the same one. Instal
 is recommended: without it everything still works, but streaming downscale of very large images is
 unavailable.
 
-**Docker (servers or long-running deployments)** — Create a `.env` in the repository root
-(`TOKEN`, `CHANNEL_ID`, `OWNER_ID`, `REVIEW_CHAT_ID` and a pinned `TELEPOST_VERSION`), then start:
+**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
@@ -100,7 +102,7 @@ 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).
-A plain Polling bot needs no domain or public HTTPS; only Webhook mode and the Mini App do.
+Receiving modes and their public HTTPS requirements: [More capabilities](#more-capabilities).
 
 ## First run
 
@@ -110,9 +112,10 @@ A plain Polling bot needs no domain or public HTTPS; only Webhook mode and the M
    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. **Add the review group and start** — The setup wizard asks 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:
+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]
@@ -120,13 +123,14 @@ A plain Polling bot needs no domain or public HTTPS; only Webhook mode and the M
    REVIEW_CHAT_ID = -1001234567890
    ```
 
-   Replace the example ID with your review group ID. Start commands: run the standalone binary,
-   `telepost` for pip, or `docker compose up -d` for Docker.
+   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. For text only, send `/skip_media`
-   to go straight to the preview and `/done_media` when you are done. Add tags, 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.
+   `/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).
 
@@ -136,10 +140,11 @@ The Mini App is a web interface that ships with the same program: readers browse
 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.
 
-It does not appear just because the bot is running. It needs a public HTTPS address, a
-`MINIAPP_SESSION_SECRET` and a Telegram-side entry; the frontend is served by the program's own HTTP
-service, so it is only mounted in Webhook mode. If any of that is missing, the entry button simply
-does not show up.
+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:
@@ -147,25 +152,26 @@ normal browser is not a login, and it grants no review or admin rights. Setup st
 
 ## AI-assisted review (MCP, optional)
 
-TelePost can connect to MCP-capable agents such as Codex or Claude through
-[MCP](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md) (Chinese): the agent
-reads pending submissions, suggests decisions based on your channel's review policy, and performs
-moderation actions only when you explicitly ask and its permissions allow it.
+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 moderates anything on its own — a human always decides.
-Keeping both the MCP layer and the review API read-only is the recommended setup. Tool list, tokens
-and connection setup: [MCP review](https://github.com/redtidev1918/TelePost/blob/main/docs/MCP_REVIEW.md) (Chinese).
+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** — the same review and publishing pipeline as the bot; multi-bot deployments use
-  `/api/botN/v1/submissions`. Fields and limits:
-  [HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/en/API.md).
-- **Multiple bots** — run several bots on one machine, each with its own channel, review group,
-  language and data directory.
+- **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** — Webhook when a public HTTPS address is available, Polling otherwise.
+- **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
@@ -185,9 +191,8 @@ curl -X POST 'https://example.com/api/v1/submissions' \
   -F 'idempotency_key=source:123'
 ```
 
-Multi-bot deployments use `/api/botN/v1/submissions` instead. API submissions always go through
-review; full fields and limits are in
-[HTTP API](https://github.com/redtidev1918/TelePost/blob/main/docs/en/API.md).
+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>
 
@@ -196,8 +201,9 @@ review; full fields and limits are in
 <details>
 <summary>Do I need a server and a domain?</summary>
 
-No domain or public HTTPS is required: a machine that stays on, Polling mode, the bot's private chat
-and a review group are enough. Only Webhook mode and the Mini App need a public HTTPS address. See
+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>
@@ -205,18 +211,19 @@ and a review group are enough. Only Webhook mode and the Mini App need a public
 <details>
 <summary>Why was my private-chat submission published directly?</summary>
 
-Private-chat submissions are published after the reader confirms by default
-(`CHAT_REVIEW_REQUIRED=false`). Set it to `true` to send them to the review group first. The Mini App
-and the HTTP API are not affected by this switch and always go through review by default. See
-[Configuration](https://github.com/redtidev1918/TelePost/blob/main/docs/en/CONFIGURATION.md#review).
+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>
 
-It is optional and needs a public HTTPS address, `MINIAPP_SESSION_SECRET`, Webhook mode and a
-Telegram-side entry; without all of them the entry is not shown. See
+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>
@@ -234,21 +241,22 @@ machine at the same time causes a Polling conflict. See
 <details>
 <summary>Where are submission files stored?</summary>
 
-Under the program's `data/` directory: 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. Keep the whole `data/` directory when upgrading or
-moving. See [Operations](https://github.com/redtidev1918/TelePost/blob/main/docs/OPERATIONS.md) (Chinese).
+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>
 
-No. TelePost bundles no language model, and MCP is optional: the moderation write tools are only
-registered when the mode is not read-only, and they are limited by both the MCP and review API
-switches. Human confirmation is the recommended workflow, not an enforced one; keeping both layers
-read-only leaves the agent advisory only. See
+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>