鱼鳃计划Fish Gills Project · AI Agent Team 控制台

Hermes Agent 的 WebUI 原型 —— 把「龟仙人 CCO 体系 · 一个调度核心 + 四个专职工位」的架构图，做成一个能交互的网页控制台。

当前为高保真视觉原型：界面与交互完整，数据为 mock；后续可将 src/data 数据层替换为 Hermes 真实 API。

技术栈

• 框架：React 18 + TypeScript
• 构建：Vite 5
• 样式：Tailwind CSS 3（设计 token 集中在 tailwind.config.js）
• 路由：React Router 6
• 图标 / 动效：lucide-react / framer-motion

快速开始

全局安装

npm install -g yusai-web-ui
yusai-web-ui start

常用命令：

yusai-web-ui status
yusai-web-ui restart
yusai-web-ui stop
yusai-web-ui doctor
yusai-web-ui check-update   # 检查是否有新版本
yusai-web-ui update         # 拉取最新版并自动重启
yusai-web-ui env status     # 检测本机环境（Node/Hermes/FFmpeg/rg…）
yusai-web-ui env install    # 一键安装缺失环境

本机环境依赖

控制台 + Hermes 工位常用工具：

| 依赖 | 级别 | 用途 | |------|------|------| | Node.js ≥ 20 | 必需 | 运行 yusai-web-ui | | npm | 必需 | 安装与远程更新 | | Hermes Agent | 必需 | AI 调度与工位 Gateway | | Python 3.11+ | 推荐 | Hermes 与模型绑定脚本 | | FFmpeg / FFprobe | 推荐 | 音视频技能（18 号工位） | | ripgrep (rg) | 推荐 | Hermes 高速文件搜索 | | Git | 推荐 | Hermes 工具链 |

首次配置页（/setup）提供 「一键安装缺失环境」；CLI 可用 yusai env install。
macOS 优先 brew，Linux 走 apt/dnf，Windows 走 winget；Hermes 使用官方安装脚本，并会调用 hermes postinstall 补齐 browser / ffmpeg 等。

start 默认以后台进程运行、启动配置中的五个 Hermes Profile，并打开浏览器。 控制台端口固定为 28820。使用 --no-open 禁止自动打开，使用 --no-fleet 只运行控制台，使用 --foreground 在容器或进程管理器中前台运行。

远程自动更新

你把新版本 npm publish 到 npm 后，用户侧无需重装，即可收到更新：

| 方式 | 说明 | |------|------| | 控制台一键更新 | 顶部横幅提示「有可用更新」→ 点「立即更新」→ 自动 npm install -g 并重启 | | CLI 手动更新 | yusai update / yusai-web-ui update | | 启动时自动更新 | YUSAI_AUTO_UPDATE=1 yusai start |

相关环境变量：

# 启动时自动安装最新版（适合希望永远跟进 UI 的用户）
export YUSAI_AUTO_UPDATE=1

# 关闭版本检查
export YUSAI_DISABLE_UPDATE_CHECK=1

# 自定义 npm 源（默认优先淘宝 npmmirror，失败再回落官方）
export YUSAI_NPM_REGISTRY=https://registry.npmmirror.com

你（开发者）发布更新的标准流程：

cd webui
# 1. 改代码、本地验证
npm run build

# 2. 升版本并发布到 npm（prepack 会自动 build）
npm version patch   # 或 minor / major
npm publish

# 3. （可选）同步推 GitHub
git push && git push --tags

用户机器上的控制台会周期性检查 npm（启动时 + 界面每 30 分钟），发现新版本后可一键更新并自动部署重启。

源码开发

# 安装依赖（国内源）
npm install --registry=https://registry.npmmirror.com

# 启动开发服务器（固定 http://localhost:28820）
npm run dev

# 生产构建
npm run build && npm run preview

自动化测试

# 先启动控制台（live 用例依赖本机 28820 + 舰队）
node bin/yusai.mjs start --no-open

# 单元 + 在线集成（推荐）
npm test

# 或分开跑
npm run test:unit   # Gateway 启动参数 / 版本比较 / 上传路径安全
npm run test:live   # health、舰队、上传、agent-chat、SSE、模型列表

test:live 会读取本机 ~/Library/Application Support/yusai-console/.auth-token（或 YUSAI_AUTH_TOKEN）。

发布到 npm

首次发布前登录 npm，之后每次先更新版本号再发布：

npm login
npm version patch
npm publish

npm publish 会通过 prepack 自动执行生产构建，并将 CLI、前端 dist、后端 server/dist 与默认舰队配置一起打入 npm 包。

远程更新依赖 npm 版本号：只 push 到 GitHub 不会让用户自动更新。 必须 npm publish 新版本后，用户的 update / 控制台一键更新才会拉到新包。

更新安全说明：

• 安装失败会 自动尝试恢复 原服务（CLI 与 Web 一键更新均如此）
• Web 更新走 SIGTERM 优雅退出（含 Gateway 清理），多 npm 源回落
• 成功标记仅在 /api/health 版本就绪后写入
• 已有用户配置会做轻量迁移（旧端口 8650/864x → 28820/2882x）；自定义 duty 不会被覆盖

目录结构

webui/
├── public/avatars/        # 五位 agent 的立绘（透明 PNG）
├── src/
│   ├── types/             # 全站数据模型（共享契约）
│   ├── data/mock.ts       # 高保真 mock 数据（将来替换为 API）
│   ├── lib/
│   │   ├── accent.ts      # 主题色映射 + 状态色（Tailwind 完整类名）
│   │   └── utils.ts       # cn() 类名合并
│   ├── components/
│   │   ├── ui/            # 通用组件：Card/Button/Badge/AgentAvatar/...
│   │   └── layout/        # Sidebar / Topbar / AppLayout
│   └── views/             # 五个页面
│       ├── Overview.tsx        # 架构总览（还原架构图）
│       ├── Console.tsx         # 调度对话台（龟仙人委派四工位）
│       ├── WorkflowBoard.tsx   # 内容工作流看板（选题→文案→声画→运营）
│       ├── AgentDetail.tsx     # 工位详情（SOUL/MEMORY/SKILL/模型）
└── tailwind.config.js     # 设计系统 token

设计系统

| 维度 | 说明 | |------|------| | 主色 | 暖金 gold（龟仙人 / 调度核心 / 品牌） | | 工位色 | lazuli 蓝 · vegeta 紫 · bardock 橙 · buu 绿 | | 背景 | paper 纸感 + 暖光晕 | | 深色块 | bg-ink-gradient（顶卡 / 侧边栏） | | 卡片 | .card + shadow-card 系列，大圆角 | | 动效 | animate-slide-up / fade-in / pulse-ring |

新增页面时，请复用 src/types 的类型与 src/components/ui 的组件，主题色统一通过 lib/accent 取，不要写死颜色。

角色与工位

| Agent | 工位 | 模型 | 主题色 | |-------|------|------|--------| | 龟仙人MasterRoshi | CCO · 调度核心 | Opus 4.8 · 调度内核 | 金 | | 18号Lazuli | 全栈技术官 | GPT-5.5 | 蓝 | | 贝吉塔Vegeta | 首席文案官 | Claude Opus 4.8 | 紫 | | 芭朵斯Vados | 选题雷达官 | Grok 4.3 | 橙 | | 布欧MajinBuu | 内容运营官 | Gemini 3.1 Pro | 绿 |

接入 Hermes 真引擎（后续）

原型与真实后端的对接点集中在 src/data/mock.ts：把其中的常量导出改为从 Hermes Dashboard API（/api/*）或 Agent Bridge 拉取即可，页面与组件无需改动。