8.2 KiB
8.2 KiB
AstrBot 聊天命令开发队列
更新日期:2026-07-12
目标:在 QQ、Telegram、Discord 等 AstrBot 消息平台中,通过 /影棚 或 /yp 操作 ImageStudio 的单图生成、快速角色和详细角色工作流,并获得异步任务、图片、选图和审核回执。
当前完成基线
- 注册
/影棚命令组。 - 注册
/yp短命令组。 - 提供帮助、状态、快速角色、工作流、单图子命令框架。
- 提取平台、统一消息来源、群聊 ID 和用户 ID。
- 配置群聊白名单与用户白名单。
- 快速角色和角色工作流要求群聊、用户同时命中。
- 单图生成允许群聊或用户任一白名单命中。
- 帮助和状态支持 PNG 卡片,异常时回退文字。
- AstrBot 不存在时保持本地测试可导入。
P0:单图生成最小闭环
P0-01 命令参数合同
- 支持
/yp 单图 <提示词>。 - 支持角色、模型路由、尺寸、数量、负面提示词等显式参数。
- 同时支持自然文本和
--参数 值两种输入。 - 将命令统一转换为
SingleImageCommandDTO。 - 参数错误返回示例和可复制的正确命令。
建议参数:
/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 跨平台、限流、审计和发布验收