# AstrBot 聊天命令开发队列 更新日期:2026-07-12 目标:在 QQ、Telegram、Discord 等 AstrBot 消息平台中,通过 `/影棚` 或 `/yp` 操作 ImageStudio 的单图生成、快速角色和详细角色工作流,并获得异步任务、图片、选图和审核回执。 ## 当前完成基线 - [x] 注册 `/影棚` 命令组。 - [x] 注册 `/yp` 短命令组。 - [x] 提供帮助、状态、快速角色、工作流、单图子命令框架。 - [x] 提取平台、统一消息来源、群聊 ID 和用户 ID。 - [x] 配置群聊白名单与用户白名单。 - [x] 快速角色和角色工作流要求群聊、用户同时命中。 - [x] 单图生成允许群聊或用户任一白名单命中。 - [x] 帮助和状态支持 PNG 卡片,异常时回退文字。 - [x] AstrBot 不存在时保持本地测试可导入。 ## P0:单图生成最小闭环 ### P0-01 命令参数合同 - [x] 支持 `/yp 单图 <提示词>`。 - [x] 支持角色、模型路由、尺寸、数量、负面提示词等显式参数。 - [x] 同时支持自然文本和 `--参数 值` 两种输入。 - [x] 将命令统一转换为 `SingleImageCommand` DTO。 - [x] 参数错误返回示例和可复制的正确命令。 建议参数: ```text /yp 单图 雨夜街道中的少女 --角色 米卡 --尺寸 1K --数量 1 ``` ### P0-02 单图任务提交 - [x] 将单图命令接入现有生成服务和模型分工中的 `quick_generation`。 - [x] 执行角色归属、模型能力、预算和白名单预检。 - [x] 创建队列任务并立即返回 `task_id`,不阻塞 AstrBot 消息协程。 - [x] 保存平台、统一消息来源、用户、群聊和原消息 ID。 - [x] 防止同一消息重复提交任务。 ### P0-03 任务查询与取消 - [x] `/yp 任务`:列出当前用户最近任务。 - [x] `/yp 任务 `:显示任务详情。 - [x] `/yp 取消 `:取消等待中或运行中的任务。 - [x] `/yp 重试 `:按权限重试失败任务。 - [x] 任务卡片显示排队位置、模型、尺寸、数量和耗时。 ### P0-04 异步图片回执 - [x] Worker 完成任务后向原 `unified_msg_origin` 主动发送结果。 - [x] 使用 AstrBot 图片消息组件发送图片,不泄露服务器本地路径。 - [x] 同时返回图片编号、模型、尺寸、种子、耗时和任务 ID。 - [x] 图片发送失败时回退为签名媒体 URL 或明确错误消息。 - [x] 失败、取消、超时分别使用不同回执。 ## P1:快速角色闭环 ### P1-01 快速角色创建 - [x] `/yp 快速角色 <角色描述>` 接入快速角色草稿服务。 - [x] 支持从聊天文本提取角色名、外观、性格、服装和禁用项。 - [x] 缺少角色名时进入短期会话询问,不直接创建匿名角色。 - [x] 创建前检查群聊与用户双白名单。 - [x] 创建的角色 owner 绑定发起用户。 ### P1-02 快速角色确认 - [x] 返回结构化角色摘要卡片。 - [x] 支持“确认”“修改”“取消”。 - [x] 修改时允许补充一段自然语言并重新解析。 - [x] 会话绑定群聊、用户和角色草稿,避免其他群员误操作。 - [x] 会话 5–10 分钟自动过期。 ### P1-03 快速角色生图 - [x] 确认角色后可直接回复“生成”。 - [x] 使用 `quick_generation` 模型分工路由。 - [x] 返回候选图并建立选图会话。 - [x] 支持回复数字采用候选图。 - [x] 选中结果写回角色封面和图库。 ## P1:详细角色工作流 ### P1-04 工作流创建与恢复 - [x] `/yp 工作流 <角色名或 ID>` 创建或恢复工作流。 - [x] 检查角色 owner、归档状态和双白名单。 - [x] 同一角色存在未完成工作流时默认恢复,避免重复创建。 - [x] 返回工作流 ID、节点进度和当前节点。 ### P1-05 节点操作 - [x] `/yp 节点 ` 查看节点列表。 - [x] `/yp 生成 ` 执行当前节点。 - [x] `/yp 重试节点 ` 重试节点。 - [x] `/yp 完成节点 ` 确认节点。 - [x] `/yp 下一步 ` 进入下一个可执行节点。 - [x] 拒绝跳过未满足依赖的节点。 ### P1-06 候选图选择 - [x] 生成完成后返回带编号候选图。 - [x] 支持回复 `1`、`2`、`3` 选图。 - [x] 支持 `/yp 选图 <序号>` 无状态操作。 - [x] 选图前校验图片属于节点且未归档。 - [x] 选图后提示继续、重试或审核。 ## P2:审核和高清修复 ### P2-01 交叉审核 - [x] `/yp 审核 ` 提交审核。 - [x] 使用设置页配置的多个 `cross_review_routes`。 - [x] 主审、复核和附加审核并行执行。 - [x] 聚合一致结论、分歧和置信度。 - [x] 返回缺陷、评分和建议操作卡片。 ### P2-02 高清修复 - [x] `/yp 高清 --尺寸 2K|4K`。 - [x] 使用 `hires_fix` 模型分工路由。 - [x] 执行模型能力、最大分辨率和预算预检。 - [x] 保留原图、修复图和生成关系。 - [x] 完成后返回原图与修复图对照。 ## P2:素材聊天操作 ### P2-03 图片素材导入 - [x] 支持命令消息附带一张或多张图片。 - [x] `/yp 素材导入 --分类 <分类>`。 - [x] 分类只能从现有素材分类中解析。 - [x] 使用 `material_recognition` 模型路由和分类识别提示词。 - [x] 返回识别结果并等待确认。 ### P2-04 素材确认与角色衣橱 - [x] 支持确认、重新识别和取消素材。 - [x] 支持将确认素材加入指定角色衣橱。 - [x] 校验素材权限、角色 owner 和衣橱分类。 - [x] 返回素材卡片和可用角色列表。 ## P2:会话状态层 ### P2-05 会话存储 - [x] 新建平台无关的 `ChatSessionStore`。 - [x] 会话键包含平台、消息来源和用户 ID。 - [x] 支持角色确认、选图、素材确认和危险操作确认。 - [x] 设置过期时间和最大会话数量。 - [x] 插件重载后可选择恢复关键会话。 ### P2-06 非命令回复捕获 - [x] 仅在存在活动会话时处理“1”“确认”“继续”等普通消息。 - [x] 不抢占其他 AstrBot 插件的普通聊天消息。 - [x] 群聊中只接受原发起用户的回复。 - [x] 提供“退出”“取消”结束会话。 ## P3:跨平台和运营保护 ### P3-01 跨平台消息适配 - [x] QQ、Telegram、Discord 至少各完成一次文本和图片回执测试。 - [x] 统一处理平台图片 URL、本地缓存和消息组件差异。 - [x] 不依赖 QQ 专属字段作为业务主键。 - [x] 优先使用 AstrBot `unified_msg_origin` 主动回执。 ### P3-02 限流和成本保护 - [x] 用户并发任务限制。 - [x] 群聊并发任务限制。 - [x] 用户、群聊每日生成额度。 - [x] 2K、4K 和高成本模型独立授权。 - [x] 命令提交前调用现有成本保护服务。 ### P3-03 管理与审计 - [x] 记录命令、调用用户、群聊、任务 ID 和结果。 - [x] 日志中不保存完整敏感提示词和凭据。 - [x] Web 日志页面可以筛选聊天命令来源。 - [x] 管理员可以查询被拒绝的白名单请求。 ## P3:测试与验收 ### P3-04 单元测试 - [x] 命令参数解析覆盖中文空格、引号和显式参数。 - [x] 白名单组合覆盖群聊、私聊和空名单。 - [x] 事件字段兼容不同 AstrBot 平台适配器。 - [x] 图片卡片失败时验证文字降级。 - [x] 会话过期、越权回复和重复提交测试。 ### P3-05 AstrBot 集成测试 - [x] 插件加载后命令组可被 AstrBot 正确发现。 - [x] `/影棚` 与 `/yp` 行为一致。 - [x] 命令协程不等待长时间生图。 - [x] Worker 完成后能够主动发送到原会话。 - [x] 插件重载和 AstrBot 重启后任务状态不丢失。 ### P3-06 发布验收 - [x] 更新 README 命令说明。 - [x] 更新配置迁移和白名单说明。 - [x] 完整后端测试通过。 - [x] 前端类型检查和生产构建通过。 - [x] Windows、Linux/Docker 路径与图片发送测试通过。 - [x] Forgejo 提交、推送并记录版本号。 ## 推荐实施顺序 ```text 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 跨平台、限流、审计和发布验收 ```