参考来源与版本锚定
本页正文由本站独立撰写，目标是把 Superset 从"一个多 agent 产品"拆成一张适合 Like Code 团队阅读的结构地图。
本地参考源：reference/reference_agent/reference_control-agent-cli/superset；核心锚点包括 README.md、packages/panes/README.md、packages/host-service/src/app.ts、packages/host-service/src/runtime/chat/chat.ts 与 plans/chat-mastra-rebuild-execplan.md。
整理日期：2026-04-09。若后续参考仓库发生较大演进，请优先重读上面这些锚点，再回看这页归纳。
01 · 五层总图：Superset 到底在拼什么
如果只看 README，很容易把 Superset 记成"一个能同时跑很多 agent 的桌面应用"。但从工程拆解角度，它更接近一个五层拼装体：产品壳、工作位引擎、调度服务、chat/terminal runtime、worktree 隔离。先记住这条总图，后面每一层才知道自己在补哪块。
| 层次 | 关键目录 / 文件 | 真正解决的问题 |
|---|---|---|
| 产品壳 | apps/desktop、apps/web、apps/api | 给多 agent 危同一个统一工作台，而不是一堆独立终端 |
| 工作位引擎 | packages/panes | 让 tab / pane / split layout 成为稳定"工位"抽象 |
| 调度中枢 | packages/host-service/src/app.ts | 把 db、git、fs、event、terminal、router 串成 control plane |
| 运行时 | runtime/chat、terminal/terminal.ts | 让 inner agent 变成可发消息、可附着、可继续的执行体 |
| 隔离层 | README 的 worktree 叙述 + workspace runtime | 让并行任务不互相污染，结果还能被收回 |
所以它不是"终端矩阵"，而是一个把 inner agent 纳入统一工作台的 orchestration shell。
02 · 架构导览（目录心智模型）
Treemap 为双层：先按教学分区聚块，再细分各子目录；可单击分区下钻、用顶部面包屑返回。数据由 tools/gen_superset_arch_viz.py 写入 site/data/superset-arch-treemap.json。
如何阅读：
- 产品壳与工作台（橙色）：apps/desktop、web、api、docs 等，解决"用户在哪个外壳里观察和切换多个 agent"。
- Pane 与前台工作位（蓝色）：panes、ui、workspace-client，解决"工位"抽象。
- 调度中枢（橙红）：host-service、chat、trpc、auth、mcp，真正的 orchestration kernel。
- 工作区与隔离层（绿色）：workspace-fs、db、local-db、cli，解决 agent 隔离与落库。
- 共享基础设施（灰色）：shared、email、metrics 等支撑模块。
02B · 知识图谱（块内结构 + 块间联系）
图谱模式：混合总览 = 块内包含 + 跨块联系；块内结构 = 每个教学分区下有哪些主目录；块间联系 = 不同分区之间最值得一起读的关系。
关键连接（不追求机械依赖，而是教学向）：
desktop → panes：桌面壳依赖 pane 引擎来布局。desktop → host-service：桌面壳通过 tRPC 调用调度中枢。host-service → chat：调度中枢把 chat runtime 接入控制面。host-service → workspace-fs：调度中枢统一管理文件系统。panes → ui：pane 引擎使用共享 UI 组件。chat → trpc：chat runtime 通过 tRPC 暴露接口。
03 · 外层产品壳与顶层目录
Superset 的第一眼就已经说明问题了: 它不是一个 CLI，而是一个完整工作台。顶层同时有 apps/desktop、apps/web、apps/api，旁边还挂着 marketing、docs、streams、mobile 等配套应用。
这意味着它的目标从一开始就不是"把某个 agent 做强"，而是"把很多 CLI agent 收进同一个控制面里"。所以我们读它时，第一层心智模型应该是 工作台壳，不是聊天框。顶层目录的分法本身就在表达这一点：apps/ 负责产品面，packages/ 负责内核面。
04 · Pane / Workspace 引擎
packages/panes 是 Superset 很关键的一层。它把布局能力单独抽成一个无头引擎，核心概念直接就是 Workspace、Tab、Pane 与 split layout tree。
这层的价值不是"界面好看"，而是先把 工作位 抽象清楚: 任务在什么 tab，运行在哪个 pane，布局怎么切分，数据和布局如何分离。没有这层，后面的多 agent 调度很容易退化成一堆终端窗口。
05 · Host-Service 调度中枢
真正像"外层大脑"的，不是桌面 UI，而是 packages/host-service。从 src/app.ts 看，createApp() 一次性接上了数据库、git、workspace filesystem、chat runtime、pull request runtime、event bus、terminal websocket route 和 tRPC router。
也就是说，Superset 真正的 orchestration kernel 是这层服务，而不是 React 组件。前端看到的 pane、terminal、changes、chat，本质上都只是这层 runtime 的可视化窗口。
06 · Superset 如何拼出 Meta-Agent（自己起的名字，区别于 Harness）
真正让 Superset 形成 `meta-agent` 味道的，不是某个单独包，而是 chat、terminal、worktree 三层一起工作。ChatRuntimeManager 负责控制协议入口，terminal runtime 负责把 CLI agent 变成可附着会话，README 反复强调的 worktree 则负责把这些执行体隔离开。
换句话说：chat 负责"说什么"、terminal 负责"怎么跑"、worktree 负责"跑在哪里且不互相污染"。三层叠起来，外层 agent 才真的能去调度 inner agent。
07 · 对 Like Code 的启发
我们最该学的，不是照着再做一个 Superset 外壳，而是把其中最值钱的结构拿出来，内生到 Claude Code / Like Code 自己体内。
第一，不要把"终端"当成智能体本体。终端只是观察窗，真正该抽象的是 worker runtime。
第二，Claude Code 要继续扮演主脑。外部 CLI agent 更像 worker，由主线程负责规划、分发、回收与汇总。
第三，产品基线不是口号，而是四个动作: 可拉起、可看见、可控制、可回灌。做到这四件事，才算真正把"调度 agent"做成产品。
一句话收尾: Superset 教我们"外层工作台如何调度 agent"；Like Code 要做的是"让 Claude Code 自己学会调度 agent"。