Discord Purge Bot
Run controlled cleanup in Discord guild channels with safety gates and audit-friendly outputs.
Safety Contract
- - Use only a bot token (
DISCORD_BOT_TOKEN or --token). - Refuse user-account token flows and self-bot behavior.
- Run
purge-preview.mjs first for every destructive request. - Require explicit confirmation code before running deletion.
- Abort if channel is not a guild channel.
- Keep logs and JSON summaries for each run.
Workflow
- 1. Collect scope:
channel-id, optional author-id, contains, regex, after, before. - Read
references/discord-limits.md before deletion runs. - Run preview to estimate impact and get confirm code.
- Run deletion with confirm code.
- Share summary: scanned, matched, deleted, failed, old-vs-recent split.
Commands
Preview
CODEBLOCK0
Run Purge
CODEBLOCK1
Dry Run
CODEBLOCK2
Clone or Nuke Channel
CODEBLOCK3
Script Roles
- -
scripts/purge-preview.mjs: scan channel messages, apply filters, return counts and confirm code. - INLINECODE11 : execute deletion with 2-week split (
bulk-delete + single delete fallback). - INLINECODE13 : create replacement channel; optionally delete original channel.
- INLINECODE14 : reusable scan and filtering logic.
- INLINECODE15 : Discord API wrapper with rate-limit retries.
- INLINECODE16 : deterministic confirm code helpers.
Operator Rules
- - Keep
max-scan bounded for broad channels. - Use
--state-file on long jobs. - Prefer content/user/time filters over whole-channel wipes.
- Use nuke mode only when preserving channel history is unnecessary.
- Treat pinned messages as protected unless
--include-pinned is set.
Troubleshooting
- - 401/403: verify bot token and channel permissions.
- Empty preview with expected history: check
READ_MESSAGE_HISTORY. - Heavy 429: reduce parallelism and keep retry handling enabled.
- INLINECODE21 failures: expect messages older than 14 days, runner falls back to single deletes.
- Cannot reach Discord behind a proxy: export
HTTP_PROXY/HTTPS_PROXY (uppercase recommended) and run with NODE_USE_ENV_PROXY=1, or use a recent Node that supports setGlobalProxyFromEnv(). - If your proxy tool exposes both HTTP and SOCKS ports, point
HTTP_PROXY/HTTPS_PROXY at the HTTP port; ALL_PROXY=socks5://... alone is not enough for this skill.
Proxy Example
CODEBLOCK4
Discord 消息清理机器人
在Discord频道中执行受控的消息清理操作，配备安全防护机制和审计友好的输出。
安全协议
- - 仅使用机器人令牌（DISCORDBOTTOKEN 或 --token）。
- 拒绝用户账户令牌流程和自我机器人行为。
- 每次执行破坏性操作前，先运行 purge-preview.mjs。
- 执行删除前需要明确的确认码。
- 如果频道不是公会频道则中止操作。
- 每次运行保留日志和JSON摘要。
工作流程
- 1. 收集范围：channel-id、可选 author-id、contains、regex、after、before。
- 执行删除前阅读 references/discord-limits.md。
- 运行预览以评估影响并获取确认码。
- 使用确认码执行删除。
- 分享摘要：扫描数、匹配数、删除数、失败数、新旧消息分布。
命令
预览
bash
node scripts/purge-preview.mjs \
--channel-id 123456789012345678 \
--author-id 987654321098765432 \
--contains error \
--after 2026-03-01T00:00:00Z \
--max-scan 5000 \
--out ./tmp/purge-preview.json
执行清理
bash
node scripts/purge-runner.mjs \
--channel-id 123456789012345678 \
--author-id 987654321098765432 \
--contains error \
--after 2026-03-01T00:00:00Z \
--confirm PURGE-XXXXXXXX \
--state-file ./tmp/purge-state.json \
--out ./tmp/purge-result.json
试运行
bash
node scripts/purge-runner.mjs --channel-id 123456789012345678 --confirm PURGE-XXXXXXXX --dry-run
克隆或清空频道
bash
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm NUKE-XXXXXXXX --out ./tmp/nuke.json
node scripts/purge-nuke.mjs --channel-id 123456789012345678 --confirm NUKE-XXXXXXXX --delete-old --out ./tmp/nuke.json
脚本角色
- - scripts/purge-preview.mjs：扫描频道消息，应用过滤器，返回计数和确认码。
- scripts/purge-runner.mjs：执行删除操作，支持2周分割（批量删除+单条删除回退）。
- scripts/purge-nuke.mjs：创建替换频道；可选删除原频道。
- scripts/scan-filter.mjs：可复用的扫描和过滤逻辑。
- scripts/discord-api.mjs：Discord API封装，支持速率限制重试。
- scripts/job-code.mjs：确定性确认码辅助工具。
操作规则
- - 对宽频道保持 max-scan 有界。
- 长时间任务使用 --state-file。
- 优先使用内容/用户/时间过滤器而非全频道清除。
- 仅在不需要保留频道历史时使用清空模式。
- 除非设置 --include-pinned，否则将置顶消息视为受保护。
故障排除
- - 401/403：验证机器人令牌和频道权限。
- 预览为空但预期有历史消息：检查 READMESSAGEHISTORY 权限。
- 大量429错误：降低并行度并保持重试处理。
- bulk-delete 失败：预期消息超过14天，运行器回退到单条删除。
- 无法通过代理访问Discord：导出 HTTPPROXY/HTTPSPROXY（建议大写）并使用 NODEUSEENVPROXY=1 运行，或使用支持 setGlobalProxyFromEnv() 的新版Node。
- 如果代理工具同时暴露HTTP和SOCKS端口，将 HTTPPROXY/HTTPSPROXY 指向HTTP端口；仅使用 ALLPROXY=socks5://... 对此技能不足。
代理示例
bash
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NODEUSEENV_PROXY=1
node scripts/purge-preview.mjs --channel-id 123456789012345678 --max-scan 200
