Superset CLI 通过 superset 命令提供对 Superset 平台的命令行访问，核心用途是快速派生子智能体（subagents）并在隔离工作区中创建项目副本，从而编排编码智能体完成开发任务。
安装方式：若未安装 CLI，可执行 curl -fsSL https://superset.sh/cli/install.sh | sh。
核心工作流：
- 选择项目与主机：
superset projects list和superset hosts list。 - 创建工作区：
superset workspaces create --project <id> --host <id> --name "..." --branch <branch>（也可用--pr <number>或--local代替--host）。 - 派生智能体：
superset agents create --workspace <id> --agent claude --prompt "..."。 - 规划任务：
superset tasks create --title "..."，随后用tasks update <id-or-slug>更新进度。
运行时上下文：在 Superset 工作区或终端内调用时，会设置环境变量 $SUPERSET_WORKSPACE_ID（当前工作区 id）和 $SUPERSET_TERMINAL_ID（当前终端会话 id）。若 $SUPERSET_WORKSPACE_ID 未设置，说明不在 Superset 工作区内，需按核心工作流创建工作区。
主要能力：
- 工作区：创建、列出、更新、删除；创建时需在
--branch与--pr中恰好提供一个；--base-branch指定分支尚不存在时的分叉点；可在创建时通过--agent/--prompt启动智能体，或通过--command运行一次性 shell 命令，两者可独立使用。 - 智能体：
agents list --host <id>或--local列出已配置智能体；agents create派生智能体，--agent接受预设 id（如 claude、codex）、HostAgentConfig 实例 UUID 或 superset（内置 Superset 聊天会话）；--attachment-id <uuid>可多次传入。agents run --json返回{ kind, sessionId, label }，kind 为 chat 或 terminal。 - 桌面应用会话打开：
superset workspaces open <id>触发深度链接superset://v2-workspace/<id>，加--print仅打印 URL。由于workspaces open只能定位工作区、无法聚焦会话，需自行构建深度链接：chat 会话追加?chatSessionId=<sessionId>，terminal 会话追加?terminalId=<sessionId>；可加&focusRequestId=<unique>强制重新聚焦。Linux/Windows 使用平台 URL 打开器（xdg-open、start）。 - 终端：
terminals create --workspace <id> --command "bun test"在新终端运行命令；省略--command打开交互式 shell；--cwd <path>覆盖工作目录。 - 任务：支持 list、get、create、update、delete；过滤标志包括
--status、--priority、--assignee、--assignee-me、--creator-me、--search、--limit、--offset。 - 项目：
projects list列出 NAME、SLUG、REPO、ID；项目是已检出的仓库，创建工作区或调度自动化需要项目 ID。 - 主机：
hosts list列出 NAME、ONLINE、ID；主机是已注册的可运行工作区的机器；工作区命令用--local定位本机。 - 自动化（别名 auto）：按计划运行智能体会话，每次触发派发到主机并产生可交互继续的工作区。需提供
--project或--workspace之一或两者；计划以 RFC 5545 RRule 存储；运行至少派发一次，提示词应设计为幂等；目标主机离线时运行标记为 skipped_offline，下次正常调度。省略工作区时会创建仓库的新克隆。支持 list、get、create、update、pause、resume、run、delete、logs，以及prompt get/prompt set（字节精确往返）。
使用方式与提示：脚本化或作为智能体运行时始终使用 --json，其输出按命令保持一致；先执行 auth whoami，多数失败源于配置中 organizationId 为空或令牌过期。
故障排查：出现 "No active organization" 时运行 superset organization list && superset organization switch <id>；出现 "Host is offline / error connecting to host" 时说明主机的中继隧道未连接，需确认 CLI 与目标机器均为最新版本。
适用场景：需要为编码任务创建隔离工作区、批量派生编码智能体、定时运行自动化任务，或通过命令行管理 Superset 项目、任务与主机的开发与运维流程。
限制：自动化运行至少派发一次，提示词需幂等；主机离线时运行被跳过；会话在桌面应用工作区视图中需导航后才可见，且没有会话列表；workspaces open 无法聚焦会话。