技术架构

技术栈概览

核心技术选型

Star Office UI 采用经典的”前后端分离”架构，技术栈简洁且易于部署：

架构图

graph TB
    subgraph "Backend (Flask)"
        A[RESTful API]
        B[State Manager]
        C[Agent Registry]
        D[Memory Reader]
    end
    
    subgraph "Storage"
        E[state.json]
        F[join-keys.json]
        G[memory/*.md]
    end
    
    subgraph "Frontend (Phaser.js)"
        H[Game Scene]
        I[Sprite Manager]
        J[Animation Controller]
        K[UI Overlay]
    end
    
    A --> B
    A --> C
    A --> D
    B --> E
    C --> F
    D --> G
    
    H --> I
    H --> J
    H --> K
    
    A -.->|HTTP/WebSocket| H

后端架构深度剖析

Flask 应用结构

后端采用单文件 Flask 应用设计（backend/app.py），提供以下核心 API 端点：

# 核心 API 路由设计
routes = {
    'GET /health': '健康检查',
    'GET /status': '获取主 Agent 状态',
    'POST /set_state': '设置主 Agent 状态',
    'GET /agents': '获取多 Agent 列表',
    'POST /join-agent': '访客 Agent 加入',
    'POST /agent-push': '访客 Agent 推送状态',
    'POST /leave-agent': '访客 Agent 离开',
    'GET /yesterday-memo': '获取昨日工作小记'
}

状态管理机制

状态管理采用 JSON 文件持久化方案，核心设计如下：

状态数据结构

{
  "status": "writing",
  "message": "正在整理文档",
  "last_update": "2026-03-03T10:00:00Z",
  "agent_id": "main"
}

状态映射规则

多 Agent 注册机制

项目支持多 Agent 协作场景，采用 Join Key 认证机制：

1. Join Key 生成：管理员在 join-keys.json 中预置访问密钥
2. Agent 注册：访客 Agent 通过 /join-agent 提交 Key 和元信息
3. 状态推送：注册成功后，访客可调用 /agent-push 更新状态
4. 离开机制：调用 /leave-agent 清理注册信息

// join-keys.json 示例
{
  "keys": [
    {"key": "guest-2026-abc", "name": "Assistant Bot", "expires": "2026-12-31"}
  ]
}

”昨日小记”功能实现

项目集成了工作记录回顾功能，通过读取 memory/*.md 文件实现：

# 核心逻辑伪代码
def get_yesterday_memo():
    yesterday = date.today() - timedelta(days=1)
    memo_file = f"memory/{yesterday.strftime('%Y-%m-%d')}.md"
    if exists(memo_file):
        content = read_file(memo_file)
        return sanitize_content(content)  # 脱敏处理
    return find_latest_memo()  # 回退到最近的记录

前端架构深度剖析

Phaser.js 游戏引擎应用

前端采用 Phaser.js 3 游戏引擎，实现了完整的游戏化界面：

核心模块设计

// 游戏场景结构
class OfficeScene extends Phaser.Scene {
    preload() {
        // 加载精灵图表和地图资源
        this.load.image('office-map', 'assets/office.png');
        this.load.spritesheet('agent', 'assets/agent.png', {
            frameWidth: 32,
            frameHeight: 32
        });
    }
    
    create() {
        // 创建办公室背景
        // 初始化 Agent 精灵
        // 设置动画帧
    }
    
    update() {
        // 轮询状态更新
        // 触发动画切换
    }
}

动画系统设计

项目实现了基于精灵表（Sprite Sheet）的帧动画系统：

动画配置示例

// 不同状态的动画帧配置
this.anims.create({
    key: 'writing',
    frames: this.anims.generateFrameNumbers('agent', {
        start: 0,
        end: 7
    }),
    frameRate: 8,
    repeat: -1
});

状态-动画映射逻辑

function updateAgentAnimation(status) {
    const animations = {
        'idle': 'idle-anim',
        'writing': 'writing-anim',
        'researching': 'reading-anim',
        'executing': 'working-anim',
        'syncing': 'sync-anim',
        'error': 'error-anim'
    };
    
    agentSprite.play(animations[status] || 'idle-anim');
    
    // 移动到对应区域
    const position = getAreaPosition(status);
    agentSprite.moveTo(position.x, position.y);
}

UI 覆盖层设计

在游戏场景之上，项目叠加了 HTML/CSS UI 层用于展示：

• 状态气泡（显示当前任务描述）
• 昨日小记卡片
• Agent 列表面板
• 移动端适配布局

为什么这样设计

设计哲学分析

1. 游戏化而非监控化

传统状态监控工具采用”仪表盘”隐喻，强调数据密度和功能性。Star Office UI 选择”办公室”隐喻，通过游戏化降低认知负担，提升使用愉悦感。

设计理由：

• 状态可视化是”给人类看的”，应该符合人类的直觉理解方式
• 游戏化可以增加用户粘性，减少”监控疲劳”
• 像素风格自带复古魅力，吸引技术社区群体

2. 轻量级而非企业级

项目没有采用数据库、消息队列等企业级组件，而是选择 JSON 文件 + Flask 的最小化方案。

设计理由：

• 降低部署门槛，支持 30 秒快速体验
• 目标用户是中小团队和个人开发者，而非大型企业
• 专注核心价值（可视化），避免功能蔓延

3. 扩展性设计

多 Agent 注册机制预留了扩展空间：

• 支持”访客 Agent”加入，为未来协作场景做准备
• API 设计遵循 RESTful 规范，便于第三方集成
• 前后端分离，支持自定义前端主题

关键组件清单

后端核心组件

前端核心组件

资产文件

小结

Star Office UI 的技术架构体现了”最小可行产品”的设计哲学：用最简洁的技术栈实现核心价值，同时预留扩展空间。

Flask + Phaser.js 的组合在功能性和趣味性之间取得了平衡：后端提供灵活的状态管理 API，前端提供沉浸式的游戏化体验。JSON 文件存储虽然限制了规模扩展，但换来了极致的部署便捷性。

下一章节将对比分析类似产品和竞品，定位 Star Office UI 的差异化优势。

参考资料

• Phaser.js 3 官方文档 - 游戏引擎 API 参考
• Flask 官方文档 - Python Web 框架
• Star Office UI app.py - 后端源码
• Star Office UI layout.js - 前端布局配置