superset-orchestrate

Superset 编排

使用 Superset 的工作区、Agent 和终端命令协调终端 Agent。将其视为由协调者驱动的协议：Superset 提供会话传输，协调者负责管理任务依赖关系和完成状态。

建立控制界面

1. 运行 superset auth whoami --json。
2. 运行 superset terminals --help，并确认其中包含 list、read、send 和 close。
3. 如果缺少这些命令，运行 superset update 并重新检查。不要臆造或替换为不受支持的编排命令。
4. 在 Superset monorepo 中开发时，使用 bun run --cwd packages/cli dev -- 代替 superset，以便通过根目录 .env 中配置的 API 调用源码 CLI。若要在测试尚未发布的源码命令时复用生产 CLI 身份验证，请在 packages/cli 中运行这些命令，并设置 SUPERSET_API_URL=https://api.superset.sh bunx cli-framework dev。
5. 派发任务前，解析工作区、主机和支持终端的 Agent：

superset hosts list --json
superset agents list --local --json
superset workspaces list --local --json

从目标工作区内部进行协调时，在 Agent 和终端命令中显式传入 --workspace "$SUPERSET_WORKSPACE_ID"。只有 workspaces get 会从该环境变量中读取默认工作区 ID。对于远程主机，请始终传入 --host <id>。如果目标主机处于离线状态，请使用 hosts wake <id>，并在派发任务前确认主机已上线。不要使用 --agent superset：它会创建聊天会话，终端 read/send 命令无法控制该会话。

规划工作

创建一张简明的协调者表格，包含以下字段：

字段	用途
任务	稳定的简短标识符
依赖项	必须先完成的任务
工作区	Superset 工作区 ID
主机	主机 ID，或 local
终端	agents create 返回的 sessionId
状态	pending、ready、running、completed、blocked 或 failed
结果	摘要、文件、检查和后续工作

在协调者的工作上下文中保留此状态。Superset 组织任务是问题跟踪记录，不是编排 DAG 节点；除非用户提出要求，否则不要创建或修改它们。

优先选择相互独立的任务和较浅的依赖链。并行编辑时，为工作者分配不同的工作区／分支。只读分析或有意互补且文件不重叠的工作，可以共用一个工作区。

定义工作者协议

向每位工作者提供范围明确的提示词，其中包含：

• 任务 ID 和目标；
• 工作区范围以及允许修改的文件；
• 验收标准和验证命令；
• 所需的依赖项或先前发现；
• 不要扩大范围或覆盖无关更改的警告；
• 下方的完成格式。

要求工作者的最终回复以以下其中一种格式结尾：

SUPERSET_WORKER_DONE
task: <task-id>
summary: <one-line outcome>
files: <comma-separated paths or none>
checks: <commands and outcomes>
handoff: <next-step context or none>

SUPERSET_WORKER_BLOCKED
task: <task-id>
reason: <specific blocker>
needs: <decision, access, or dependency required>

这些标记是可在终端快照中看到的提示词约定，不是持久化的 Superset 事件。若格式错误或缺少标记，请将其视为非结构化输出，并检查完整快照。

派发工作者

启动一个终端 Agent，并保留其会话 ID：

superset agents create \
  --workspace <workspace-id> \
  --host <host-id> \
  --agent <preset-or-config-id> \
  --effort <supported-level> \
  --attachment <optional-path> \
  --prompt "<worker prompt>" \
  --json

不需要时省略 --effort 或 --attachment。返回结果为 { "kind", "sessionId", "label" }。要求 kind 为 terminal，并将 sessionId 保存为终端 ID。开始监控任务前，先启动所有已就绪且相互独立的任务。

工作者需要隔离分支时，请先使用 superset workspaces create。除非文件归属明确且互不重叠，否则不要在同一个工作树中创建并行编辑工作者。

监控与沟通

丢失协调器上下文或重启主机服务后，重新获取活动终端 ID：

superset terminals list \
  --workspace <workspace-id> \
  --host <host-id> \
  --json

终端发现无法识别语义上的接收方或 Agent 的完成状态。尽可能保留协调器表中的任务与终端映射关系。

读取最近的输出，但不修改会话：

superset terminals read \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --max-lines 240 \
  --json

JSON 结果包含 text。检查其中是否有完成或受阻信封，并确认周围的输出能够支持所声称的结果。terminals list 报告的是活动会话，而非 Agent 正在工作还是空闲；不要仅凭是否存在、是否缺失、attached 或终端标题推断任务已完成。

向现有会话发送澄清、依赖结果、审查反馈或交接内容：

superset terminals send \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --text "<follow-up>" \
  --json

以适当的频率轮询，并在每轮中读取所有正在运行的工作进程。优先进行多轮短时间监控，而不是运行一个长时间阻塞的 shell 循环，以便进度和用户更新始终可见。

推进工作流

1. 只有在读取 SUPERSET_WORKER_DONE 信封并检查其证据后，才将任务标记为 completed。
2. 工作进程发出 SUPERSET_WORKER_BLOCKED 时，将任务标记为 blocked；在重新分派之前，解决所需事项或询问用户。
3. 仅当所有依赖项都已完成时，才将待处理任务提升为 ready。
4. 在下一个工作进程提示词中包含依赖结果，或将结果发送给已在运行的依赖任务工作进程。
5. 只有在更改提示词、输入或工作进程选择后，才重新分派失败的任务。多次失败后停止重试，并报告阻碍。
6. 在提交合并结果之前，独立验证存在风险或相互重叠的更改。

对于彼此隔离的分支，只有在该操作属于用户要求的工作流时，才要求每个实现工作进程提交更改或以其他方式提供准确的交接内容。Superset 不会自动合并工作进程的分支。

完成并清理

总结每项任务的结果、工作区／分支、已更改文件、检查、阻碍和集成顺序。区分工作进程的声明与协调器独立执行的检查。

如果用户可能想要检查或继续使用已完成的终端，请保留这些终端。只有在用户要求清理或清理明确属于工作流的一部分时，才关闭终端：

superset terminals close \
  --workspace <workspace-id> \
  --host <host-id> \
  --terminal <terminal-id> \
  --json

关闭终端会结束该会话。删除工作区是单独的破坏性操作，需要明确的范围。