docs: document private-chat lookups + private_query_per_min (3.1.0)

Author: Zakkaus

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [3.1.0] - 2026-06-20
+
+### Added
+- **Lookup commands now work in a private chat** with the bot (`/pkg` `/use` `/bug` `/news`
+  `/wiki` `/bbs` `/pkgs` `/arm` `/armpkgs`), **rate-limited per user** to
+  `private_query_per_min` queries/minute (config, default 3) to prevent abuse — guarded
+  groups stay unlimited. Other DMs still get the unified auto-reply (now updated to mention
+  this). Auto-delete doesn't apply in DMs (nothing to keep tidy there).
+
 ## [3.0.0] - 2026-06-20
 
 A milestone release: the cross-distro `/pkgs` channel logic is now centred on each distro's
@@ -347,6 +356,7 @@ First stable release.
   long polling, no inbound port; ships a hardened `systemd` unit (`DynamicUser` +
   sandboxing) and reads its token from the environment.
 
+[3.1.0]: https://github.com/Zakkaus/gentoo-zh-verify-bot/releases/tag/v3.1.0
 [3.0.0]: https://github.com/Zakkaus/gentoo-zh-verify-bot/releases/tag/v3.0.0
 [2.7.0]: https://github.com/Zakkaus/gentoo-zh-verify-bot/releases/tag/v2.7.0
 [2.6.1]: https://github.com/Zakkaus/gentoo-zh-verify-bot/releases/tag/v2.6.1

README.md

@@ -13,7 +13,7 @@ Built for open-source community groups that get flooded with spam-bot join reque
 - **Admin override buttons** on every request: **👮 直接通过** (approve now) and **🚫 举报并封禁** (decline + permanent ban).
 - **Multiple groups.** Guard several groups with one bot instance.
 - **Auto-leaves unauthorized chats.** If the bot is added to any group/channel that isn't in its config (a guarded group, the required channel, a feed target, or the admin-log chat), it leaves immediately — so it can't be pulled into random groups. To add a new guarded group, put its id in `group_ids` first, then add the bot.
-- **DM auto-reply.** A direct message to the bot (outside the verification flow) gets a single unified reply pointing the user back to the group + commands, instead of silence. Customizable via `private_reply`.
+- **Lookup commands in DM (rate-limited).** The read-only lookup commands (`/pkg` `/use` `/bug` `/news` `/wiki` `/bbs` `/pkgs` `/arm` `/armpkgs`) also work in a **private chat with the bot**, capped at `private_query_per_min` per user per minute (default 3) to prevent abuse — guarded groups stay unlimited. Any other DM gets a unified auto-reply (customizable via `private_reply`).
 - **Channel sock-puppet block (optional, `/bc`).** A message posted in a guarded group *on behalf of a channel* (a common spam/ban-evasion trick) is deleted and that channel is banned from posting. Admins toggle it with `/bc`, and manage a whitelist with `/bc allow|deny <channel id>` (`allow` also un-bans) — the toggle and whitelist **persist across restarts**. Anonymous group admins and the linked discussion channel are exempt. **Requires the bot's privacy mode to be OFF** (BotFather → disable group privacy) so it can see these messages.
 - **Moderation commands** (reply to a message, admins only): `/sb` = delete + kick (rejoinable), `/ban` = delete + permanent ban, `/warn` = strike a user (auto-kick after `warn_limit`, default 3 — counts persist across restarts), `/clearwarn` = clear a user's strikes.
 - **Control / info:** `/start` `/stop` (toggle verification), `/rich` (toggle rich output), `/autodel` (toggle/adjust auto-deletion of lookup answers; default 3 min), `/ping`, `/stats` (today's approved/declined), `/help`.
@@ -82,6 +82,7 @@ Everything else lives in `config.json` (copy `config.example.json`):
 | `notify_ttl_seconds` | auto-delete the bot's group messages after N s (`0`→60, negative→never) |
 | `lookup_ttl_seconds` | auto-delete a lookup command (`/pkg` `/use` `/bug` `/news` `/wiki` `/bbs` `/distro`) and its answer after N s (unset→180 = 3 min, on; `0`/negative→off). Admins toggle/adjust at runtime with `/autodel` |
 | `warn_limit` | `/warn` strikes before a user is auto-kicked (default 3) |
+| `private_query_per_min` | lookup queries a user may run per minute in a **private chat** (default 3; guarded groups are unlimited) |
 | `admin_log_chat_id` | optional chat that receives a line per moderation / failed-approve event |
 | `overlays` | `/pkg` GitHub overlays `[{name,repo,branch}]` (default: gentoo-zh + guru) |
 | `news_url` | `/news` source index URL (default: gentoo.org news-items) |

README.zh-CN.md

@@ -13,7 +13,7 @@
 - **管理员一键操作**:每条申请都带「👮 直接通过」与「🚫 举报并封禁」按钮。
 - **多群守护**:一个实例可同时守护多个群。
 - **自动退出未授权聊天**:被加进任何不在配置里的群/频道(非守护群、非必关频道、非播报目标、非管理日志)时,机器人会立刻退出 —— 不会被人随便拉进群刷存在。要新增守护群,先把群 id 写进 `group_ids`,再把机器人加进去。
-- **私聊自动回复**:有人私聊机器人(非验证流程)时会收到一条**统一回复**,引导去群里使用命令,而不是没反应。可用 `private_reply` 自定义。
+- **私聊也能用查询命令(限频)**:只读查询命令(`/pkg` `/use` `/bug` `/news` `/wiki` `/bbs` `/pkgs` `/arm` `/armpkgs`)**私聊机器人也能直接用**,每人每分钟上限 `private_query_per_min` 次(默认 3)防滥用 —— 守护群里不限次。其它私聊消息收到统一自动回复(`private_reply` 可自定义)。
 - **频道马甲封禁(可选,`/bc`)**:有人在守护群里**用频道身份发言**(常见的刷屏 / 规避封禁手法)会被删消息 + 封禁该频道再也发不了。管理员用 `/bc` 开关,`/bc allow|deny <频道id>` 管白名单(`allow` 同时解封)—— 开关和白名单**重启不丢**。匿名群管和群的关联频道自动放行。**需要把机器人的隐私模式关掉**(BotFather → 关闭群隐私)才能看到这些消息。
 - **管理命令**(回复目标消息,仅管理员):`/sb` 删消息 + 踢出(可再申请)、`/ban` 删消息 + 永久封禁、`/warn` 警告用户(满 `warn_limit` 次自动踢出,默认 3 次,计数重启不丢)、`/clearwarn` 清除某用户的警告。
 - **控制 / 信息**:`/start` `/stop`(开关验证)、`/rich`(开关富文本输出)、`/autodel`(开关/调节查询结果自动删除,默认 3 分钟)、`/ping`、`/stats`(今日通过 / 拒绝数)、`/help`。
@@ -67,6 +67,7 @@ GITHUB_TOKEN=ghp_xxx
 | `notify_ttl_seconds` | 机器人群消息 N 秒后自动删除(`0`→60,负数→不删) |
 | `lookup_ttl_seconds` | 查询命令(`/pkg` `/use` `/bug` `/news` `/wiki` `/bbs` `/distro`)及其回复 N 秒后自动删除(不设→180=3 分钟、开;`0`/负数→关)。管理员用 `/autodel` 运行时开关/调节 |
 | `warn_limit` | `/warn` 多少次后自动踢出(默认 3) |
+| `private_query_per_min` | 私聊中每人每分钟可用的查询次数(默认 3;守护群不限次) |
 | `admin_log_chat_id` | 可选:接收每次管理操作 / 批准失败的日志 |
 | `overlays` | `/pkg` 的 GitHub overlay `[{name,repo,branch}]`(默认 gentoo-zh + guru) |
 | `news_url` | `/news` 源索引 URL(默认 gentoo.org) |

config.example.json

@@ -10,6 +10,7 @@
   "notify_ttl_seconds": 60,
   "lookup_ttl_seconds": 180,
   "warn_limit": 3,
+  "private_query_per_min": 3,
   "admin_log_chat_id": 0,
   "rich_messages": false,
   "user_agent": "",