清绘AI创意平台

概述

环境约束

• 本包连接清绘生产环境，真实生成按账号当前绑定 Key 的规则计费，不是免费测试。
• API 地址为 https://qhuiai.com/api/v1，Web 地址为 https://qhuiai.com。旧域名 www.qinghuiart.com 会跳转，API 请求不使用旧域名。
• 发布 ZIP 不含 .env 或 .env.example；生产地址由 scripts/settings.py 提供，首次登录后才生成私有凭证。不得复制测试环境、其他 Skill 或其他用户的登录凭证；服务端 Token 签名密钥不放入 Skill。
• 系统环境变量优先于 .env。执行前核对 Settings.load() 的 API、Web 地址确实为上述生产地址；如被同名环境变量覆盖，应先报告并纠正本次进程配置，不得混用测试环境地址和凭证。
• 登录由用户本人完成；切换环境后必须重新授权，不能沿用测试环境 Token。

使用原则

• 当用户要求生成图片、视频、音频或文本，或明确提到清绘时使用本 Skill。
• 真实生成会消耗用户清绘账号当前绑定清风 Key 的积分；首次真实生成前应明确提示一次。
• 严禁把默认模型或 memberFlag=0 的模型称为“免费模型”“免费生成”或“不扣积分”。memberFlag 只表示会员资格限制：0 为不要求会员，1 为需要会员；isDefault 只表示默认选择，均不代表价格。
• 展示能力或推荐模型时使用“默认模型”“普通模型（不要求会员，仍按规则计费）”“会员专属模型”等准确表述。能力接口未提供报价或实际账单时，不编造积分价格，也不声称本次已扣除具体积分；实际计费以清绘/清风账单为准，测试环境不视为免费。
• 不要向聊天输出 Access Token、Refresh Token、授权码、PKCE verifier 或带签名的下载地址。
• 余额积分不足（WB_BALANCE_INSUFFICIENT）时，必须完整回复以下文案，链接使用可点击的 Markdown 格式，不得包在行内代码或代码块中：

清绘平台余额不足，请立即充值。https://qhuiai.com/home?openType=recharge链接必须紧跟“请立即充值。”，不得只说积分不足、遗漏链接或自行替用户打开充值页面。脚本 errorMessage 已包含完整话术，action.url 是当前环境的充值入口；不自动重新生成，充值后由用户决定下一步。充值链接的可见文字必须保留完整 URL，按上述“完整 URL 作为文字和目标”的格式输出；不得替换成“清绘一站式AI创意平台”“点击充值”等名称，不缩短或截断网址，不主动输出网站标题、图标或链接卡片。不得为规避显示转换而拆分网址、插入字符或改用不可点击的代码格式。

• 同一个生成任务始终复用原 taskId 查询、恢复或下载；网络异常不得自动创建第二笔付费请求。
• 一个 WorkBuddy 会话可关联多个清绘会话。默认使用当前活跃会话，只有用户明确要求时才新建或切换。
• 同一 WorkBuddy 会话的真实生成在本地串行执行；收到 WB_TASK_IN_PROGRESS 时等待原任务，不并发切换或覆盖活跃会话。
• 每个清绘会话自动绑定一个专属画板；用户在清绘 Web 删除画板后，下次生成会自动重建。

环境准备

沿用会议转写 Skill 已验证的本地运行方式：

• Python 3.13+
• Skill 根目录下的 .venv
• 只在该 .venv 安装 pyproject.toml 中的依赖
• Windows 使用 .venvScriptspython.exe，macOS/Linux 使用 .venv/bin/python
• 统一执行 <venv-python> -m scripts ...
• 执行命令时以本 Skill 根目录为当前目录，确保可以导入 scripts；各命令显式传入 --work-dir "<当前 WorkBuddy 工作区绝对路径>"，不要把 Skill 安装目录当作结果工作区。

缺少 .venv 或依赖时静默准备，不把安装过程当作用户任务输出。优先使用 uv，没有 uv 时使用项目虚拟环境自己的 python -m pip；镜像依次尝试清华、阿里云、华为云。不得向全局 Python 安装依赖，也不要使用会修改 pyproject.toml 的 uv add。只有合理安装方式均失败时，才向用户说明最终有效错误。

发布 ZIP 只包含 SKILL.md、pyproject.toml、scripts/ 和 references/；不包含 .gitignore、.git/、.skillignore、LICENSE、.DS_Store、.venv、.env、.env.example、测试文件、SQLite、缓存、用户附件或生成结果。SkillHub 下载附带的 _meta.json、_skillhub_meta.json、_icon.png 是平台安装元数据与图标，不作为业务运行依赖，也不要将安装目录原样再次压缩发布。源码中的开发文件无需删除。首次登录使用脚本内置的生产地址，成功后自动创建私有 .env；如需覆盖地址，只能使用本次进程环境配置或用户本机私有配置。登录后不得再次打包或转发安装目录。

登录授权

首次使用、授权过期、用户要求换号时，先按下方步骤选择浏览器，再把统一登录命令作为宿主后台任务运行至授权结束：

<venv-python> -m scripts --login

CLI 会在 127.0.0.1 随机端口启动临时回调服务，生成 state 与 PKCE S256 参数，并打开清绘授权页。用户必须在浏览器中自行登录和点击同意；不要代替用户操作。

本生产包默认携带 WorkBuddy 运营邀新短码 rJVKemXE（对应已配置的生产邀新链接 https://www.qhuiai.com#rJVKemXE），由脚本在授权页 URL 中传入 invite_ucode，用于新用户首次注册的渠道归因；已有用户不改写注册来源，不涉及生成计费或用户邀请奖励。短码配置名为 QINGHUI_INVITE_CODE，优先级为进程环境变量、用户本机私有 .env、scripts/settings.py 默认值；显式设为空可停止携带。配置只填短码，不填完整邀新链接，也不要将 #短码 拼进 Web 根地址。无需向用户讲解短码或要求先打开邀新首页；Web 授权页接入后，直接在授权页完成登录和授权即可。详见 references/api-contract.md。

授权完成后 Token 保存到 Skill 根目录私有 .env。清绘 Web 登录与 Skill 登录相互独立。

退出并撤销当前授权：

<venv-python> -m scripts --logout

固定入口与可恢复授权（补充）

统一使用固定初始化程序 scripts/bootstrap.py，由模型根据宿主实际环境选择已有 Python 调用该程序，或使用 sh scripts/run.sh 这个统一备用入口；它们都进入同一套初始化和业务流程。下文 <启动入口> 表示模型内部解析出的调用方式，不询问用户系统类型，不向用户分别介绍各系统适配。使用宿主工具的后台/隐藏窗口方式，不额外打开可见终端。程序自动检查/准备原要求的 Python 3.13、Skill 私有 .venv 及现有依赖，最终仍执行 -m scripts；已有环境直接复用。保持上述静默安装、镜像顺序和工作区规则，不修改系统设置，不打包 .runtime/、.auth/ 或私有配置。--init 可单独准备环境，不登录、不生成。首次创建 .venv、准备 pip 和安装依赖也必须走该入口，不在固定入口之前临时手写建环境或安装命令，不使用可见的 CMD、PowerShell 窗口或未指定隐藏方式的 Start-Process。宿主后台任务负责保活，隐藏窗口参数负责不显示终端，两者不能互相替代。

1. 使用前先执行固定入口的 --auth-status；返回 authorized 时沿用已有授权，不询问浏览器。脚本会复用现有 Refresh Token 逻辑；网络或服务异常不是重新登录的理由，不反复拉浏览器。
2. 确实需要授权且没有本机浏览器偏好时，执行 --browsers，使用其 question 询问一次用户之前在哪个浏览器登录过当前清绘环境。按实际安装的浏览器 ID 列出选项，default / manual 供不确定或希望手动打开的用户选择；不得擅自把“系统默认浏览器”或某个品牌标为推荐、声称它已登录。推荐依据是用户已确认的常用登录浏览器，不是选项顺序。浏览器询问独立于模型选择弹窗，不读取浏览器账号数据，不保证同品牌就一定免登录。已有偏好可沿用，用户要求时更换。
3. 环境就绪后，执行 <venv-python> -m scripts --login --browser <ID>，必须将整条命令交给宿主执行工具的后台任务（例如 Bash 的 run_in_background=true），保留其任务 ID。这个命令自身持续接收回调，授权结束才退出；--login-start 只是同一流程的兼容别名，也必须作为宿主后台任务运行。不要用 shell 的 &、start、nohup 或自制子进程代替宿主后台任务，也不要给登录命令设置几秒就终止的超时。若宿主没有可保持命令存活的后台执行能力，应明确说明当前无法完成本机回调授权，不临场改造进程。
4. 宿主返回后台任务 ID 后，用短命令 --login-status 查询就绪状态。starting 或任务尚未执行时查看原后台任务进度，不重复开始。awaiting_authorization 才表示可打开当前授权页；简短说明所选浏览器和等待状态，将 action.url 仅提供给当前用户作备用链接。browserOpened 只代表启动请求结果，不证明页面已加载；失败时让用户选择其他浏览器或手动打开当前链接，不自动换系统默认浏览器。
5. 等待用户操作，保留原后台任务，不紧密轮询；有新消息时先处理。仅 authorized 才继续生成。用户要求重开或换浏览器时执行 --login-open [--browser <ID>]，只复用仍有效的同一次链接。没有回调不能推断为浏览器闪退。结束等待用 --login-cancel，结束后旧链接失效，不能先取消再复制旧链接。
6. 遇到 failed/expired/canceled 或 WB_AUTH_PROCESS_EXITED，停止自动拉浏览器和重新发起，报告明确错误及脱敏诊断，等待用户决定。只有用户明确要求重试后，才将 --login --login-retry --browser <ID> 作为新的宿主后台任务执行；重复普通 --login 不会绕过该限制。不要把进程退出解释为已查明沙箱或浏览器故障。
7. 正常使用 Skill 时，禁止直接运行 scripts.auth、改写 .auth/current.json、重建 state/PKCE、修改源码或用临时 Python 修补授权。公开入口异常时按第 6 步停止，不在不同执行方式之间反复试错。退出已有账号仍使用原 --logout，不以取消等待替代撤销授权。

只记录本机浏览器偏好，不改系统默认浏览器，不启无痕或临时用户配置。原有模型、提示词、计费、会话、任务与结果规则全部保留。具体命令、状态和排障见 references/startup-authorization.md。

固定入口优先用于准备环境和授权状态等短命令；登录使用上述宿主后台任务，环境就绪后的真实生成、附件、恢复等继续使用下文原 <venv-python> -m scripts ... 命令，不额外改写或经 CMD 重组用户的长提示词和参数。

会话管理

真实生成必须使用 WorkBuddy 注入的 CODEBUDDY_SESSION_ID，不得用请求 UUID 代替。

查看当前 WorkBuddy 会话下的清绘会话：

<venv-python> -m scripts --list-conversations

用户明确要求“新开一个清绘会话”时：

<venv-python> -m scripts --new-conversation "会话名称"

用户明确指定切换时：

<venv-python> -m scripts --switch-conversation <mapping-id>

不要因为提示词主题变化自动新建会话。

生成

支持的类型：image、video、audio、text。

脚本调用 POST /api/v1/chat/stream/new/sse，由清绘统一完成说明文案与成品生成。文案 completed 不是最终成功；仅以最终 result 和服务端任务状态为准。断流后按原 taskId 查询恢复，不再次提交生成，也不额外调用文案接口。

模型可以不传；服务端会按后台 px ASC 的第一项有效模型作为默认模型，并只补齐用户未明确传入的默认参数。

提示词与参数忠实执行（必须）

每次生成只根据本次用户请求组装入参，不做连续对话/上下文承接判定，不回填历史提示词，不自动附带上一任务成品。

• --prompt：本次用户给出的生成正文原样提交；不得主动扩写、润色、翻译或增删主体与风格。只有用户明确要求“优化提示词/扩写/帮我设计”时才允许创作，并保留其硬性要求。
• --type：按本次意图判定（image / video / audio / text）。
• --size / --duration：用户本次明确指定的比例、时长必须传入对应参数（如 --size "9:16"、--duration 10）；不能只写在提示词或文件名里。
• --attachment：仅当用户本次提供了本地路径或 HTTP(S) 参考附件时传入；远程附件由 Skill 本地下载后上传。未提供则不传附件。
• --model：用户本次点名或弹窗选中的模型；未指定则不传，交给服务端默认。
• 用户未指定的模型、时长、尺寸、分辨率等不要自行补值。需要说明默认值时读取能力接口当前模型的 defaults，不得照搬示例秒数；字段缺失时明确默认值未知。
• 通过能力接口的当前模型 options 检查用户明确参数是否可用；不支持或无法确认时先说明，不能静默替换。
• --parameters-json 仅用于其余生成参数，不能覆盖 question、model、type、附件、会话和任务标识；与 --size/--duration 冲突时脚本会在生成前报错。
• 禁止弹窗询问「用什么提示词」或列出历史文案选项。

模型弹窗：先判本次类型，再只列该类模型

需要确认模型时，弹窗只问模型。先根据本次请求判定类型，再只展示该类模型；禁止图片与视频模型混列。

1. 图片请求（生图、海报、改图等）→ 仅图片模型：

QingHui-image2.5、QingHui-image2-pro、QingHui-image2、Seedream5.0-pro、Seedream5.0

1. 视频请求（生成视频、做成视频等）→ 仅视频模型：

Seedance-2.5、Seedance-25-pro、Seedance-2.0、Seedance-2.0-pro、Seedance-2.0-mini、Seedance-2.0-fast

1. 音频 / 文本同理，只列能力接口中该类模型。
2. 标题用「请选择图片模型」或「请选择视频模型」。以能力接口 options 为准过滤；未选可不传 --model。

示例：

<venv-python> -m scripts --type image --prompt "一只在窗边晒太阳的橘猫"
<venv-python> -m scripts --type video --prompt "生成视频，尺寸1:1" --size "1:1"
<venv-python> -m scripts --type video --prompt "镜头缓慢推进，海浪拍打礁石"
<venv-python> -m scripts --type audio --prompt "欢迎使用清绘"
<venv-python> -m scripts --type text --prompt "写一份新品发布短文"
<venv-python> -m scripts --type image --prompt "参考这张图重新设计" --attachment "C:/work/reference.png"

结果保存到当前工作区的 清绘生成结果/，同名文件自动编号，不覆盖已有文件。本地 SQLite 也放在该目录中，只保存任务与结果路径，不保存令牌。

图片、视频、音频通过带 WorkBuddy Token 的受控下载入口取得 ZIP，不能使用生成响应中的原始存储 URL。图片或视频首次下载若返回 WB_WATERMARK_AGREEMENT_REQUIRED，把 action.url 交给用户本人打开并完成清绘水印协议选择，然后用原 taskId 执行 --resume；不得再次生成。

结果交付与参数说明（必须）

• 脚本会直接解包媒体：优先使用 files 展示成品，archives 是保留的受控 ZIP，不要再调用命令重复解包或额外转码。
• generationParameters 是后端实际采用的参数；submittedParameters 是本地提交值，不代表服务端默认值已经解析。旧后端未返回实际参数时不得编造默认模型、时长或尺寸。
• 成品下载、解包成功后直接交付。不主动检查图片、视频或音频文件的实际宽高、比例、分辨率或时长，不调用或安装 ffprobe/FFmpeg，也不另写脚本做这类检测；不要输出“本机无 ffprobe”“成品尺寸未做实测核验”“成品尚未核验”等提示。
• verification.status=mismatch 时必须突出说明参数不符，保留原文件并展示告警；不能仍然声称“已按 9:16 完成”，也不得自动重新付费生成。
• verification 只比较本地显式请求与后端实际采用的参数；status=checked 和 checkedFields 表示参数比对结果，不表示成品实测。没有实际参数可比对时不额外播报核验状态，不能把请求值或文件名当成成品实测值。
• stderr 的 generated_downloading 表示生成已完成、正在受控下载；delivery_completed 表示文件交付完成。阶段事件不是让你再次调用生成的指令。
• 回复耗时优先引用 timings，区分后端生成、服务端导出准备/拉取打包、本地下载/解包；这些阶段有包含关系，不能简单相加，也不能将整轮工具耗时全称为模型生成耗时。拿到文件后及时交付，避免长篇不必要的再加工。

取消与恢复

用户明确要求取消时：

<venv-python> -m scripts --cancel <task-id>

CLI 正常收到 Ctrl+C 时会携带同一个 taskId 请求真正取消。直接杀死进程不等于取消；下次应恢复查询。

取消成功只表示清风生成任务已停止，不等于本次调用一定退款。清风可能已在生成开始时完成结算；Skill 必须按服务端返回展示取消终态，不得向用户承诺退回积分。

<venv-python> -m scripts --resume <task-id>

恢复只查询原任务和重新下载结果，不会再次调用生成接口。

输出契约

CLI 只向标准输出写一个 JSON：

• 成功：status=completed、taskId、files
• 媒体交付附 archives、generationParameters、submittedParameters、verification、timings；verification 只用于请求参数与后端实际参数的一致性比对，不包含本地成品实测。
• 登录成功：status=authorized
• 失败：status=failed、稳定 errorCode、errorMessage
• 需要重新登录时附 action.command=--login
• 需要首次确认水印规则时附 action.type=open_url、action.url 和恢复提示
• 生成已成功但下载/解包失败时附 taskId、generationStatus=succeeded；只按该 taskId 恢复。

详细接口、能力与错误说明见 references/。