discli — Discord 服务器管理命令行工具

从终端控制 Discord 服务器。适用于人类用户和 AI 代理（agent）。

AI 代理默认行为

• 输出格式自动识别：管道传输时使用 YAML（供 agent 使用），终端直连时使用表格（供 human 使用）。
• YAML 是 agent 的首选格式——相比 JSON 可节省约 5 倍 token 消耗。
• 使用 -n 限制结果数量，以降低 token 消耗。
• 使用 --format yaml 强制输出结构化 YAML；如需严格 JSON 格式，请使用 --format json。
• 对创建、重命名、权限类命令使用 --dry-run 参数，可预览变更内容而不实际执行。
• 破坏性命令（如 delete、kick、ban）必须显式指定 --confirm —— 不会二次交互确认。
• 输出结构定义详见 SCHEMA.md。

安装 / 更新

npm install -g @ibbybuilds/discli         # 安装
npm install -g @ibbybuilds/discli@latest   # 更新至最新版

若尚未安装 discli，请先完成安装再运行任何命令。

Windows 用户注意：推荐使用 Git Bash 而非 PowerShell。Git Bash 开箱即支持 UTF-8 编码、正确处理引号及特殊字符。PowerShell 存在编码问题（emoji 显示乱码）、引号解析问题（如 &、$、= 等特殊字符会导致消息解析失败），以及长文本参数展开异常等问题。

若必须使用 PowerShell，请在会话启动时执行以下命令：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

并使用单引号包裹消息内容，避免 PowerShell 对特殊字符进行意外展开。

首次配置说明见：docs/BOT_SETUP.md

消息长度限制

• 消息正文（content）：最多 2,000 字符
• Embed 描述（description）：最多 4,096 字符
• Embed 总长度（所有字段合计）：最多 6,000 字符
• 单条消息最多包含 10 个 embed

若消息超出 2,000 字符，请拆分为多次 msg send 调用。对于更长内容，建议使用 msg embed 并通过 --description 参数传入（最多支持 4,096 字符）。切勿静默截断。

快速参考

discli init --token            # 首次配置
discli server list                    # 列出所有服务器
discli server select              # 设置默认服务器
discli server info                    # 查看服务器概览
discli server set --name "X"         # 修改服务器名称
discli server set --description "X"  # 设置服务器简介
discli server set --verification medium  # 设置验证等级
discli server set --notifications only_mentions  # 设置默认通知策略
discli server icon ./logo.png            # 更换服务器头像

discli invite list                    # 列出全部邀请链接
discli invite create         # 创建邀请链接
discli invite create  --max-age 3600 --max-uses 10  # 带有效期与使用次数限制
discli invite delete  --confirm # 删除邀请链接

discli channel list                   # 列出所有频道
discli channel create           # 创建频道（支持 --type、--category、--topic）
discli channel delete           # 删除频道（需指定 --confirm）
discli channel rename       # 重命名频道
discli channel topic        # 设置频道主题
discli channel move               # 移动频道至指定分类（支持 --category、--position）
discli channel clone              # 克隆频道（保留全部设置）
discli channel slowmode      # 设置慢速模式（设为 0 表示禁用）

discli role list                      # 列出所有角色
discli role create              # 创建角色（支持 --color、--mentionable）
discli role edit  --color "#hex" --name "New"  # 编辑角色
discli role delete              # 删除角色（需指定 --confirm）
discli role assign        # 为成员分配角色
discli role remove        # 从成员移除角色

discli member list                    # 列出所有成员
discli member info              # 查看成员详情
discli member kick              # 踢出成员（需 --confirm 和 --reason）
discli member ban               # 封禁成员（需 --confirm 和 --reason）
discli member nick        # 修改成员昵称

discli perm view             # 查看频道权限
discli perm set             # 设置频道权限（支持 --allow、--deny）
discli perm lock             # 对 @everyone 设为只读
discli perm unlock           # 取消只读状态
discli perm list                      # 列出所有可用权限名称

discli msg send  "text"      # 发送普通消息
discli msg send  "text" --reply   # 回复指定消息
discli msg send  "text" --file ./img.png  # 发送带文件附件的消息
discli msg send  --file ./a.png --file ./b.pdf  # 发送多个附件
discli msg embed  --title "X" --description "Y" --color "#hex"  # 发送富媒体 embed
discli msg embed  --title "X" --image ./local.png  # embed 中嵌入本地图片
discli msg embed  --title "X" --field "Name|Value|inline"       # embed 中添加字段
discli msg search  "keyword"      # 按关键词搜索消息
discli msg read  -n 10       # 读取最近 N 条消息
discli msg edit   "new"   # 编辑 bot 自己发送的消息
discli msg delete   --confirm # 删除消息
discli msg bulk-delete  -n 10 --confirm  # 批量删除多条消息
discli msg react   👍         # 添加反应（reaction）
discli msg unreact   👍       # 移除反应
discli msg pin                # 置顶消息
discli msg unpin              # 取消置顶
discli msg pins              # 列出所有已置顶消息
discli msg thread  "Name"         # 创建新话题（thread）
discli msg thread  "Name" --message   # 基于某条消息创建话题

discli emoji list                        # 列出自定义表情符号
discli emoji upload  ./img.png     # 上传自定义表情符号
discli emoji delete  --confirm     # 删除自定义表情符号

discli audit log                         # 查看最近审核日志
discli audit log -n 50                   # 最近 50 条记录
discli audit log --type member_kick      # 按操作类型过滤
discli audit log --user              # 按执行者 ID 过滤
discli audit types                       # 列出所有操作类型名称