| # Product |
|
|
| ## Register |
|
|
| product |
|
|
| ## Users |
|
|
| 项目维护者、HuggingFace Spaces 页面用户，以及通过 MCP 调用插件工具的 Agent。用户通常在本地或 Space 控制台里查看插件状态、诊断依赖和运行错误、进入插件功能页，并判断某个工具是否可用。 |
|
|
| ## Product Purpose |
|
|
| Message Function Center 是面向 HuggingFace Spaces 的插件生命周期控制台。它通过部署注入插件、启动扫描校验、页面管理使用、MCP 暴露工具和状态诊断，形成稳定的插件管理闭环。成功状态是：用户能快速判断插件是否可用、为什么不可用、能做什么，以及如何进入对应功能。 |
|
|
| ## Brand Personality |
|
|
| 克制、清晰、可信。界面语气应像专业运维和工具控制台，优先服务高频诊断、筛选、执行和追踪，不用营销式表达。 |
|
|
| ## Anti-references |
|
|
| 不要营销首页、装饰性 hero、大面积低信息密度展示、粗糙卡片堆叠、默认浏览器控件、割裂的插件页面风格、emoji 装饰、运行时安装/重启引导、仅靠英文函数名解释能力。 |
|
|
| ## Design Principles |
|
|
| 1. 状态先行：任何页面先回答“能不能用、为什么、下一步做什么”。 |
| 2. 统一组件语言：插件运行页和控制台共享按钮、表单、状态、表格、空态和错误反馈。 |
| 3. 高信息密度但不拥挤：面向重复使用和快速扫读，避免营销式留白。 |
| 4. 后端事实优先：不伪造插件、依赖、MCP 或 Tool 状态。 |
| 5. 插件隔离：插件有独立 UI 和 API，但视觉和交互规范由平台资源库约束。 |
|
|
| ## Accessibility & Inclusion |
|
|
| 目标满足 WCAG 2.1 AA 的基本可读性和键盘可用性。正文和控件文本需要足够对比度；状态不能只依赖颜色；页面在桌面和移动宽度下不能溢出、遮挡或丢失关键操作；动画只用于状态反馈，并尊重 reduced motion。 |
|
|
| ## 部署与运行 |
|
|
| 镜像名 `message-center`（对应 Message Function Center）。tag 约定：`latest` 用于本地开发，`YYYYMMDD`（如 `20260628`）用于发布归档。两种模式二选一，**不要混用挂载**。 |
|
|
| ### 核心原则：挂载一致性 |
|
|
| `app/` 与 `plugins/` 必须同时挂载或同时不挂载。只挂 `plugins` 不挂 `app` 会导致插件代码改了生效、而 `app/plugins/model_probe.py`、`app/static/plugin-ui.js` 改了不生效（烤死在镜像里），并使镜像内 `COPY plugins/` 成为死代码。 |
|
|
| ### 构建命令 |
|
|
| ```powershell |
| # 本地开发 |
| docker build -t message-center:latest . |
| |
| # 发布归档（同时打 latest + 日期 tag） |
| docker build -t message-center:latest -t message-center:20260628 . |
| ``` |
|
|
| ### 运行命令 |
|
|
| #### 模式 A：部署模式（推荐，可移植） |
|
|
| 代码全部烤进镜像，仅挂载数据卷。任何代码改动需重建镜像。 |
|
|
| ```powershell |
| docker run -d --name msg -p 7860:7860 -v message-data:/app/data --env-file .env.docker --health-cmd "curl -f http://localhost:7860/api/health || exit 1" --health-interval 30s --health-timeout 5s --health-retries 3 --restart unless-stopped message-center:latest |
| ``` |
|
|
| #### 模式 B：开发模式（live edit） |
|
|
| 挂载 `app` 与 `plugins`，改 Python 或插件前端（`plugins/<name>/frontend/index.html`）后 `docker restart msg-dev` 即可生效，无需重建。平台 UI（`dist/frontend/`）仍用镜像内构建产物。 |
|
|
| ```powershell |
| docker run -d --name msg-dev -p 7860:7860 -v message-data:/app/data -v "H:\tool\message\app:/app/app" -v "H:\tool\message\plugins:/app/plugins" --env-file .env.docker --restart unless-stopped message-center:latest |
| ``` |
|
|
| ### 更新流程 |
|
|
| - 开发模式：改代码 → `docker restart msg-dev`。 |
| - 部署模式：改代码 → `docker build -t message-center:latest .` → `docker rm -f msg` → 重跑运行命令。数据卷 `message-data` 保留，无需迁移。 |
|
|
| ### 运行配置（`.env.docker`） |
|
|
| 从 `.env.docker.example` 复制为 `.env.docker` 并按需填写。关键变量： |
|
|
| - `MFC_DEBUG` — `true`/`false`，调试模式（错误信息回显）。 |
| - `HF_TOKEN` — HuggingFace 下载令牌，下载受限模型时需要；公开模型可留空。 |
| - `HF_HOME` / `HF_HUB_CACHE` — 已在 Dockerfile 默认指向 `/app/data/huggingface`，落在 `message-data` 卷内，模型缓存跨重建持久化。 |
|
|
| ### 首次运行须知 |
|
|
| `message-data` 卷内模型缓存初始为空。首次使用 ASR 会从 HuggingFace 下载：`openai/whisper-small`（约 1 GB）、`zai-org/GLM-ASR-Nano-2512`（约 3 GB）。需保证容器可访问 huggingface.co，首次转录会因下载变慢。 |
|
|
