astrbot_plugin_imagestudio/docs/astrbot-chat-command-queue.md

8.2 KiB

AstrBot 聊天命令开发队列

更新日期:2026-07-12

目标:在 QQ、Telegram、Discord 等 AstrBot 消息平台中,通过 /影棚 或 /yp 操作 ImageStudio 的单图生成、快速角色和详细角色工作流,并获得异步任务、图片、选图和审核回执。

当前完成基线

  • 注册 /影棚 命令组。
  • 注册 /yp 短命令组。
  • 提供帮助、状态、快速角色、工作流、单图子命令框架。
  • 提取平台、统一消息来源、群聊 ID 和用户 ID。
  • 配置群聊白名单与用户白名单。
  • 快速角色和角色工作流要求群聊、用户同时命中。
  • 单图生成允许群聊或用户任一白名单命中。
  • 帮助和状态支持 PNG 卡片,异常时回退文字。
  • AstrBot 不存在时保持本地测试可导入。

P0:单图生成最小闭环

P0-01 命令参数合同

  • 支持 /yp 单图 <提示词>。
  • 支持角色、模型路由、尺寸、数量、负面提示词等显式参数。
  • 同时支持自然文本和 --参数 值 两种输入。
  • 将命令统一转换为 SingleImageCommand DTO。
  • 参数错误返回示例和可复制的正确命令。

建议参数:

/yp 单图 雨夜街道中的少女 --角色 米卡 --尺寸 1K --数量 1

P0-02 单图任务提交

  • 将单图命令接入现有生成服务和模型分工中的 quick_generation。
  • 执行角色归属、模型能力、预算和白名单预检。
  • 创建队列任务并立即返回 task_id,不阻塞 AstrBot 消息协程。
  • 保存平台、统一消息来源、用户、群聊和原消息 ID。
  • 防止同一消息重复提交任务。

P0-03 任务查询与取消

  • /yp 任务:列出当前用户最近任务。
  • /yp 任务 <task_id>:显示任务详情。
  • /yp 取消 <task_id>:取消等待中或运行中的任务。
  • /yp 重试 <task_id>:按权限重试失败任务。
  • 任务卡片显示排队位置、模型、尺寸、数量和耗时。

P0-04 异步图片回执

  • Worker 完成任务后向原 unified_msg_origin 主动发送结果。
  • 使用 AstrBot 图片消息组件发送图片,不泄露服务器本地路径。
  • 同时返回图片编号、模型、尺寸、种子、耗时和任务 ID。
  • 图片发送失败时回退为签名媒体 URL 或明确错误消息。
  • 失败、取消、超时分别使用不同回执。

P1:快速角色闭环

P1-01 快速角色创建

  • /yp 快速角色 <角色描述> 接入快速角色草稿服务。
  • 支持从聊天文本提取角色名、外观、性格、服装和禁用项。
  • 缺少角色名时进入短期会话询问,不直接创建匿名角色。
  • 创建前检查群聊与用户双白名单。
  • 创建的角色 owner 绑定发起用户。

P1-02 快速角色确认

  • 返回结构化角色摘要卡片。
  • 支持“确认”“修改”“取消”。
  • 修改时允许补充一段自然语言并重新解析。
  • 会话绑定群聊、用户和角色草稿,避免其他群员误操作。
  • 会话 5–10 分钟自动过期。

P1-03 快速角色生图

  • 确认角色后可直接回复“生成”。
  • 使用 quick_generation 模型分工路由。
  • 返回候选图并建立选图会话。
  • 支持回复数字采用候选图。
  • 选中结果写回角色封面和图库。

P1:详细角色工作流

P1-04 工作流创建与恢复

  • /yp 工作流 <角色名或 ID> 创建或恢复工作流。
  • 检查角色 owner、归档状态和双白名单。
  • 同一角色存在未完成工作流时默认恢复,避免重复创建。
  • 返回工作流 ID、节点进度和当前节点。

P1-05 节点操作

  • /yp 节点 <workflow_id> 查看节点列表。
  • /yp 生成 <node_id> 执行当前节点。
  • /yp 重试节点 <node_id> 重试节点。
  • /yp 完成节点 <node_id> 确认节点。
  • /yp 下一步 <workflow_id> 进入下一个可执行节点。
  • 拒绝跳过未满足依赖的节点。

P1-06 候选图选择

  • 生成完成后返回带编号候选图。
  • 支持回复 1、2、3 选图。
  • 支持 /yp 选图 <node_id> <序号> 无状态操作。
  • 选图前校验图片属于节点且未归档。
  • 选图后提示继续、重试或审核。

P2:审核和高清修复

P2-01 交叉审核

  • /yp 审核 <node_id|workflow_id> 提交审核。
  • 使用设置页配置的多个 cross_review_routes。
  • 主审、复核和附加审核并行执行。
  • 聚合一致结论、分歧和置信度。
  • 返回缺陷、评分和建议操作卡片。

P2-02 高清修复

  • /yp 高清 <image_id> --尺寸 2K|4K。
  • 使用 hires_fix 模型分工路由。
  • 执行模型能力、最大分辨率和预算预检。
  • 保留原图、修复图和生成关系。
  • 完成后返回原图与修复图对照。

P2:素材聊天操作

P2-03 图片素材导入

  • 支持命令消息附带一张或多张图片。
  • /yp 素材导入 --分类 <分类>。
  • 分类只能从现有素材分类中解析。
  • 使用 material_recognition 模型路由和分类识别提示词。
  • 返回识别结果并等待确认。

P2-04 素材确认与角色衣橱

  • 支持确认、重新识别和取消素材。
  • 支持将确认素材加入指定角色衣橱。
  • 校验素材权限、角色 owner 和衣橱分类。
  • 返回素材卡片和可用角色列表。

P2:会话状态层

P2-05 会话存储

  • 新建平台无关的 ChatSessionStore。
  • 会话键包含平台、消息来源和用户 ID。
  • 支持角色确认、选图、素材确认和危险操作确认。
  • 设置过期时间和最大会话数量。
  • 插件重载后可选择恢复关键会话。

P2-06 非命令回复捕获

  • 仅在存在活动会话时处理“1”“确认”“继续”等普通消息。
  • 不抢占其他 AstrBot 插件的普通聊天消息。
  • 群聊中只接受原发起用户的回复。
  • 提供“退出”“取消”结束会话。

P3:跨平台和运营保护

P3-01 跨平台消息适配

  • QQ、Telegram、Discord 至少各完成一次文本和图片回执测试。
  • 统一处理平台图片 URL、本地缓存和消息组件差异。
  • 不依赖 QQ 专属字段作为业务主键。
  • 优先使用 AstrBot unified_msg_origin 主动回执。

P3-02 限流和成本保护

  • 用户并发任务限制。
  • 群聊并发任务限制。
  • 用户、群聊每日生成额度。
  • 2K、4K 和高成本模型独立授权。
  • 命令提交前调用现有成本保护服务。

P3-03 管理与审计

  • 记录命令、调用用户、群聊、任务 ID 和结果。
  • 日志中不保存完整敏感提示词和凭据。
  • Web 日志页面可以筛选聊天命令来源。
  • 管理员可以查询被拒绝的白名单请求。

P3:测试与验收

P3-04 单元测试

  • 命令参数解析覆盖中文空格、引号和显式参数。
  • 白名单组合覆盖群聊、私聊和空名单。
  • 事件字段兼容不同 AstrBot 平台适配器。
  • 图片卡片失败时验证文字降级。
  • 会话过期、越权回复和重复提交测试。

P3-05 AstrBot 集成测试

  • 插件加载后命令组可被 AstrBot 正确发现。
  • /影棚 与 /yp 行为一致。
  • 命令协程不等待长时间生图。
  • Worker 完成后能够主动发送到原会话。
  • 插件重载和 AstrBot 重启后任务状态不丢失。

P3-06 发布验收

  • 更新 README 命令说明。
  • 更新配置迁移和白名单说明。
  • 完整后端测试通过。
  • 前端类型检查和生产构建通过。
  • Windows、Linux/Docker 路径与图片发送测试通过。
  • Forgejo 提交、推送并记录版本号。

推荐实施顺序

P0-01 参数合同
  → P0-02 单图任务提交
  → P0-03 任务查询
  → P0-04 异步图片回执
  → P1-01~P1-03 快速角色
  → P1-04~P1-06 详细工作流与选图
  → P2-05~P2-06 会话状态层
  → P2-01~P2-04 审核、高清和素材
  → P3 跨平台、限流、审计和发布验收