Web UI
OpenSquilla 的 Web UI 是用于设置、聊天 session、审批、channels、日志、agent、用量和运维状态的本地控制台。当你希望使用基于浏览器的聊天、可见的工具活动、持久化审批以及对运行时健康状态的快速视图时，它是最佳入口。
Control UI 是由 gateway 提供的 Vue 产品 UI。历史遗留的 control_ui.frontend = "legacy" 设置会被临时接受，以便现有 profile 仍能启动，但它已被弃用、会被规范化为 "vue"，并且不再激活原生 JS 客户端。
启动 Web UI
在前台运行 gateway：
opensquilla gateway run打开：
http://127.0.0.1:18791/control/或者启动一个托管的后台 gateway：
opensquilla gateway start --json
opensquilla gateway status为安全起见，默认 gateway 绑定到 127.0.0.1。
关于 gateway 生命周期、主机/端口以及对外暴露的详情，参见 gateway.md。
打包安装与源码安装
官方 Python wheel、Desktop 安装包和容器镜像已经包含构建好的 Vue 控制台。 这些安装路径不需要用户机器上有 Node.js 或 npm。
Git 检出包含的是 Web UI 源码，而不是已提交的构建产物树。源码安装器会自动 运行以下命令，然后将结果与 OpenSquilla 一起打包：
cd opensquilla-webui
npm ci
npm run build因此，源码安装器与贡献者需要 Node.js 22.12+ 和 npm。每次源码重装都会运行
npm ci 并重建控制台；首次运行通常下载量最大，而热态的 npm 缓存会减少之后
的网络使用，但不会减少全部构建时间或磁盘写入。贡献者在修改 Web UI 后应重新
运行构建。标准 wheel 构建会拒绝缺失或过期的控制台，而不是悄悄产出一个
/control/ 页面为空的 wheel。
这条 fail-closed 规则同样适用于直接的 pip install .、uv tool install .
以及 VCS URL 安装。从本地检出工作时，请先构建 Web UI；VCS URL 用户应克隆
仓库并运行源码安装器，或安装官方发版 wheel。
标准源码归档（sdist）还会拒绝被忽略的个人 BGM 文件，这样可分享的归档就
不会意外泄漏私有或受版权保护的音频。直接在本地构建的 wheel 或本地 Docker
镜像仍可包含显式定制的曲库；官方发版产物则始终要求受追踪的播放列表保持为空。
主要区域
| 区域 | 用途 |
|---|---|
| Chat | 运行和恢复聊天 session，查看工具活动，启动 /meta 工作流，发布 artifact，并使用手动 compact 控件。 |
| Conversations | 从侧边栏切换活动 session，并让长时间运行的工作保持可见。 |
| Overview / Health | 查看就绪状态、provider 状态、记忆状态、sandbox 策略和恢复建议。 |
| Settings | 通过模态流程配置 provider、router、搜索、channels、权限和其他设置章节。 |
| Channels | 查看已配置 channel 适配器的状态，并跳转到引导式设置以进行配置更改。 |
| Skills | 浏览 skill 就绪状态和 MetaSkill 可用性。 |
| Sessions | 查看持久化的 session 账本和运维状态。 |
| Agents | 管理持久化 agent 条目。 |
| Usage | 查看 token 和预估成本的汇总。 |
| Cron | 查看和管理已调度的运行。 |
| Logs | 查看运行时日志和诊断信息。 |
| Approvals | 响应敏感工具调用的审批请求。 |
聊天 session
聊天 UI 支持：
- 流式 assistant 输出；
- 工具调用卡片；
- 针对 provider、router、工具和用量事件的 turn 活动与 RunTrace 视图；
- 敏感操作的内联审批请求；
- 在有预览可用时带缩略图的 artifact 卡片；
- 用于存放生成输出的交付物抽屉；
- 用于交接的分享和导出操作；
- 用于切换 session 的对话侧边栏；
- 在 gateway 支撑的聊天 session 上的
/meta列表与运行启动； - 在 compaction 或运行时工作进行中时的待发送消息队列行为；
- 手动
/compact； - 在可用时显示每个 turn 的用量和节省元数据；
- 可复制的 session key；
- 在窄屏上让聊天、session 和运维视图保持可达的移动端标签页。
使用 session 选择器在已有的 session 之间切换。在报告 bug 或请求另一个 OpenSquilla 入口查看同一 session 时，请复制 session key。
当你希望将代码修改通过 opensquilla code-task 来处理时，可以在聊天中启用 Coding 模式。启用 Coding 模式后，代码更改会使用 cli.md 中所述的受控宿主工作流，而不是普通的会话内编辑。输入 /coding 即可切换该模式。启用期间，输入框会显示一个 Coding ON 状态控件，也可用于关闭该模式。为兼容起见，显式的 /coding on、/coding off 和 /coding status 形式仍然可用。
手动 compaction
长 session 可以从聊天中进行 compact。如果不需要 compaction，UI 会提示：
Already within context budget; no compact was applied如果 compaction 正在运行，请等待其终止状态再认为下一条消息已经具备 compact 后的上下文。参见 features/compaction-and-cache.md。
artifact
当 agent 发布一个文件时，Web UI 会显示一个 artifact 卡片。artifact 卡片可用于：
- 生成的 HTML 原型；
- 报告和简报；
- 导出的数据文件；
- PDF、幻灯片、图片以及其他生成的输出。
artifact 卡片可能包含缩略图或预览元数据，并且交付物抽屉会在原始 turn 滚动离开后仍让已发布的输出保持可发现。
HTML artifact 预览始终会显示它当前使用的是全网络访问还是离线模式。本地 Web UI 可以请求任一模式；远程访问的 Web UI 则被强制离线，并在一个不透明沙箱中运行 bundle 脚本，同时明确说明 workers、持久化存储和根绝对路径不作保证。普通网页链接会继续以 noopener,noreferrer 在单独的浏览器标签页中打开。Desktop 应用还额外提供一个显式操作，用于在其隔离的侧边浏览器中打开 HTTP(S) 链接。
完整的 Desktop 预览刻意做得像浏览器，而不是有特权的 Electron 视图。每个打开的项目都有独立的临时 cookie/存储/缓存分区，且没有 Node、preload、IPC、宿主文件系统、OpenSquilla 身份或系统浏览器会话。关闭一个项目会清除其临时状态。设备权限、用户发起的下载、弹窗和外部协议仍由宿主中介处理；来自操作系统存储的客户端证书绝不会提供给预览页面。活动中的 OpenSquilla Gateway 在侧边预览内同样不可达，从而防止网络上的临近性演变为一种隐性的 OpenSquilla 身份；用户仍然可以在系统浏览器中打开显式链接。
关于 channel 投递限制和 artifact 恢复，参见 artifacts-and-media.md。
审批
某些工具需要确认。审批区域为操作者提供一个持久化的位置来批准或拒绝敏感操作，而不是将决定淹没在聊天文本中。
在以下情况使用审批区域：
- agent 想要写文件；
- 某个命令需要更高权限；
- 某个 channel 或外部操作需要人工确认；
- 无人值守自动化在执行有风险的操作前应该先暂停。
日志和诊断
进行本地诊断：
opensquilla diagnostics on
opensquilla gateway status
opensquilla doctor使用 Web UI 的日志和健康视图，将 provider 就绪状态、channel 状态、session 状态和用户可见的错误关联起来。
安全
Web UI 默认是本地的。如果你将 gateway 绑定到公开网络接口，请先配置 token 认证和网络管控：
opensquilla gateway run --listen 0.0.0.0 --port 18791不要将未认证的 gateway 暴露到公共互联网。