226 行
8.2 KiB
Markdown
226 行
8.2 KiB
Markdown
# 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 任务 <task_id>`:显示任务详情。
|
||
- [x] `/yp 取消 <task_id>`:取消等待中或运行中的任务。
|
||
- [x] `/yp 重试 <task_id>`:按权限重试失败任务。
|
||
- [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 节点 <workflow_id>` 查看节点列表。
|
||
- [x] `/yp 生成 <node_id>` 执行当前节点。
|
||
- [x] `/yp 重试节点 <node_id>` 重试节点。
|
||
- [x] `/yp 完成节点 <node_id>` 确认节点。
|
||
- [x] `/yp 下一步 <workflow_id>` 进入下一个可执行节点。
|
||
- [x] 拒绝跳过未满足依赖的节点。
|
||
|
||
### P1-06 候选图选择
|
||
|
||
- [x] 生成完成后返回带编号候选图。
|
||
- [x] 支持回复 `1`、`2`、`3` 选图。
|
||
- [x] 支持 `/yp 选图 <node_id> <序号>` 无状态操作。
|
||
- [x] 选图前校验图片属于节点且未归档。
|
||
- [x] 选图后提示继续、重试或审核。
|
||
|
||
## P2:审核和高清修复
|
||
|
||
### P2-01 交叉审核
|
||
|
||
- [x] `/yp 审核 <node_id|workflow_id>` 提交审核。
|
||
- [x] 使用设置页配置的多个 `cross_review_routes`。
|
||
- [x] 主审、复核和附加审核并行执行。
|
||
- [x] 聚合一致结论、分歧和置信度。
|
||
- [x] 返回缺陷、评分和建议操作卡片。
|
||
|
||
### P2-02 高清修复
|
||
|
||
- [x] `/yp 高清 <image_id> --尺寸 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 路径与图片发送测试通过。
|
||
- [ ] 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 跨平台、限流、审计和发布验收
|
||
```
|