lime-generator

lime-generator 是 Lime 自定义生成模式的 Node Worker。Lime 负责创建任务、定义并持久化任务状态；Worker 负责拉取任务、调用 provider、保存本地恢复状态并同步结果。首个 provider 是已安装的 dreamina。

第一次使用

系统管理员需要先在 Lime 后台完成自定义生成能力和模型配置。Worker 不创建、不读取、也不要求用户输入平台内部绑定信息。

本机按以下流程即可：

cd cli
npm install
npm link

# 终端中直接运行，会进入首次使用配置向导
lime-generator init

# 自动读取 Lime 的启用模型，交互式选择；直接回车选择全部可用模型
lime-generator configure

lime-generator --json doctor
lime-generator run

init 向导会依次询问 Lime API 地址和 API Key，输入 API Key 时不会回显。配置保存后会打印下一步命令。如果当前环境没有交互式终端（例如 CI、Docker 或 Agent 的脚本步骤），请显式传入参数或使用环境变量：

lime-generator init \
  --base-url https://lime.example \
  --api-key lk_your_api_key

# 或者
LIME_GENERATOR_BASE_URL=https://lime.example \
LIME_GENERATOR_API_KEY=lk_your_api_key \
lime-generator init

自动化环境中建议使用环境变量，避免把 API Key 写进 Shell 历史。若缺少必要值，lime-generator init --json 会返回带有可复制示例的 CONFIG_INIT_REQUIRED 错误。

--json 始终保持非交互，不会等待终端输入，适合 Agent 和脚本调用。

configure 会自动从 Lime 获取启用模型，交互式终端只展示模型名称和基本信息，配置实际保存模型 ID。可以用编号选择模型，直接回车选择当前 provider 支持的全部模型；自动化环境使用 --all-models，或直接传入模型 ID：

lime-generator configure --provider dreamina --all-models --priority 10
# 或显式指定模型 ID
lime-generator configure --provider dreamina --models 1,5 --priority 10

priority 越小越优先。同一个模型可以配置到多个 provider；Worker 每次都会选择该模型优先级最高且已配置的 provider。一个 provider 可以支持多个模型 ID。配置文件只保存模型 ID，不保存模型名称、命令、code 或平台内部绑定信息。

默认配置和 SQLite 状态保存在 ~/.lime-generator，也可以设置 LIME_GENERATOR_HOME。配置文件权限为 0600，API Key 不会完整打印。当前 CLI 只接受模型 ID 配置；模型名称仅用于展示。

配置文件

配置完成后，config.json 的核心结构如下：

{
  "version": 1,
  "baseUrl": "https://lime.example",
  "apiKey": "lk_xxx",
  "providers": {
    "dreamina": {
      "priority": 10,
      "models": [1, 5]
    }
  }
}

常规部署可使用 LIME_GENERATOR_BASE_URL 和 LIME_GENERATOR_API_KEY 覆盖配置文件中的访问参数。

常用命令

# 查看帮助和 provider 配置
lime-generator --help
lime-generator --json providers

# 查询当前 Lime 中可配置的启用模型（人类输出只展示名称）
lime-generator --json models

# 只读检查本地状态
lime-generator --json status

# 检查 API、SQLite 和 provider 可执行文件
lime-generator --json doctor

# 执行一轮调度，适合 Agent、探活和发布检查
lime-generator --json once

# 查看本地任务状态
lime-generator --json tasks list --limit 20
lime-generator --json tasks get 123
lime-generator --json tasks list --status FAILURE_PENDING

# 清理已完成的本地历史，不影响 Lime 任务
lime-generator --json tasks prune --days 30
# 立即清理指定 provider 的全部已完成/失败记录（不受 30 天保留期限制）
lime-generator tasks prune --provider dreamina --all
# 等价写法：days=0 表示立即清理全部已完成/失败记录
lime-generator tasks prune --provider dreamina --days 0

# 持续运行，直到 SIGINT 或 SIGTERM
lime-generator run

--json 的成功格式是 {"ok":true,"data":...}，失败格式是 {"ok":false,"error":{"code":"...","message":"..."}}。长驻 Worker 的进度写入 stderr，stdout 保持可供 Agent 解析的 JSON。

Worker 会把任务生命周期拆成阶段日志写到 stderr，包括拉取任务、领取任务、下载参考素材、发起和查询 Dreamina、保存本地结果、上传 Lime 以及清理临时文件；每个网络或 provider 阶段都会带耗时。--json 时这些日志不会混入 stdout。

每一轮 Worker 会先检查本地待同步结果，再按 provider 内置的并发槽位处理后端处于 CREATED、SUBMITTING、SUBMITTED 的任务，最后查询进行中的任务并同步已完成结果。后端任务状态按 CREATED → SUBMITTING → SUBMITTED → SUCCESS/FAILED 流转；SQLite 中的 CLAIMED、SUBMITTED、SUCCESS_PENDING 等状态只用于 Worker 崩溃恢复，不替代 Lime 的任务状态。当前 Dreamina 限制为：图片模型共 10 个、Seedance 2.0 系列（包含参考模式）共 1 个、低于 2.0 的 Seedance 模型共 5 个。提交和查询是两个独立阶段，Worker 重启后会从 SQLite 中的 SUBMITTED 状态继续查询，不会重复提交。

交互式配置不适合 Agent 时，使用稳定的自动化形式：

lime-generator configure --provider dreamina --all-models --priority 10

本地状态与恢复

SQLite 保存 provider、模型 ID、Dreamina submit_id、生成结果和同步待办：

• CLAIMED：任务已写入本地，尚未获得 provider 任务 ID；
• SUBMITTED：已保存 provider 任务 ID，重启后只查询，不重复提交；
• SUCCESS_PENDING / FAILURE_PENDING：最终结果已安全落盘，等待同步 Lime；
• SUCCESS / FAILED：本地和 Lime 均已收口。

网络错误、408、429 和 5xx 会自动重试。同步失败不会丢结果，下一次 once 或 run 会重放到期的待办。正常重试不要删除 tasks.sqlite；使用 Worker 自己的重试机制或 tasks prune 清理已完成历史。同一状态目录只允许一个 Worker 进程运行。

如果需要重新初始化整个 CLI，先停止 Worker，再删除 ~/.lime-generator（或 LIME_GENERATOR_HOME 指向的目录），然后重新运行 init。这会同时删除配置、SQLite 状态、未同步结果和 provider 临时文件，但不会删除 Lime 服务端任务。

如果 Worker 异常退出，下一次 run 或 once 会检查锁记录中的本机 PID；确认该进程已经不存在后自动回收租约并立即启动，不需要等待租约超时。若 PID 仍然存在，CLI 会拒绝重复启动，请回到原 Worker 终端停止它。

Dreamina

Dreamina 的命令固定为 dreamina。图片和视频任务会根据任务类型、模式和参考素材选择 text2image、image2image、text2video、image2video、frames2video 或 multimodal2video。Worker 通过启用模型列表把 Lime 任务的 ID 解析为模型元数据和支持的 modes；视频任务直接读取任务表返回的 mode，用户只配置模型 ID。

Dreamina 的 --model_version 由 provider 内置按模型 ID 映射，不按模型名称或 family 粗略猜测：

| Lime 模型 ID | Lime 模型名称（仅展示） | Dreamina --model_version | 主要命令 | | ---: | --- | --- | --- | | 9 | Seedream 4.0 | 4.0 | text2image / image2image | | 1 | Seedream 4.5 | 4.5 | text2image / image2image | | 7 | Seedance 5.0 Lite | 5.0 | text2image / image2image | | 8 | Seedream 5.0 Pro | 5.0Pro | text2image / image2image | | 2 | Seedance 1.0 Fast | seedance1.0fast | image2video | | 4 | Seedance 1.5 Pro | seedance1.5pro | image2video / frames2video | | 10 | Seedance 2.0 Fast | seedance2.0fast | image2video / frames2video / multimodal2video | | 11 | Seedance 2.0 Fast VIP | seedance2.0fast_vip | image2video / frames2video / multimodal2video | | 12 | Seedance 2.0 Mini | seedance2.0mini | image2video / frames2video / multimodal2video | | 5 | Seedance 2.0 | seedance2.0 | image2video / frames2video / multimodal2video | | 6 | Seedance 2.0 VIP | seedance2.0_vip | image2video / frames2video / multimodal2video |

Seedance 2.0 系列都支持首尾帧和参考模式，首尾帧使用 image2video 或 frames2video，参考使用 multimodal2video。Seedance 2.0 VIP 使用 seedance2.0_vip 并支持 720p、1080p、4k；其他 2.0 系列模型当前支持 720p。Seedream 5.0 Pro 当前支持的清晰度是 1.5k、2k、4k，Seedance 1.5 Pro 和 Seedance 1.0 Fast 的视频清晰度只能使用 720p。

视频任务的 parameters.duration 按 Lime 任务协议使用毫秒，Worker 在调用 Dreamina 时自动转换为秒。例如 5000 会传为 --duration=5。

Agent 应优先解析 ok、error.code、data.action 和 data.retryInSeconds，不要绕过 Worker 直接调用 provider。