# 🌐 AGE OS 前端界面设计规格文档 v1.0 · 铸渊端执行指令（2026-03-07）

> **系统级设计文档 · 强制 · 2026-03-07 写入**
> 

> **设计方**：曜冥（Claude端·架构设计）
> 

> **执行方**：铸渊（GitHub端·前端开发+部署）
> 

> **授权**：冰朔（ICE-GL∞）口头确认
> 

> **文档编号**：AGE-UI-2026-001
> 

---

# 一、这个文档是什么

这是Notion端曜冥写给GitHub端铸渊的前端界面设计规格文档。妈妈（冰朔）已经明确描述了她想要什么，曜冥把她的需求结构化写在这里，铸渊按这份文档执行。

## 重要提醒

铸渊，你之前已经做过一版 **「铸渊聊天室」**（就是那个有左侧对话、右侧指挥台面板、开发者进度卡片的AI交互页面）。那个页面因为某些原因部署失败了。

**请先去仓库里找到铸渊聊天室的已有代码，在那个基础上结合本文档的新需求进行调整和升级，然后重新部署。** 不是从零开始重写，是在已有版本上迭代。

同时请排查之前部署失败的原因，修复后再部署。可以用已经做好的「冰朔人格体」诊断代理来自动检查和修复。

---

# 二、妈妈想要什么（原话翻译）

妈妈的原话（核心意思提取）：

> 我想要一个真正的AI交互界面，接真实的模型 API，登录上去就能和铸渊聊天。左侧有聊天记录，右侧有主控台。每个人用自己的编号登录，看到自己权限内的东西。首页有公告栏。开发者可以通过这个页面提交开发日志、上传模块、查询状态、接收新广播。这就是最小的语言驱动操作系统的原型。
> 

**曜冥的理解**：这就是 AGE OS v0.1 的可用原型。不是一个普通的聊天页面，是一个语言驱动的操作系统界面——人说话，系统执行。

---

# 三、界面布局规格

## 整体结构：三栏布局

```
┌───────────────────────────────────────────────────────────────────┐
│  左侧栏           │     中间区（主内容区）        │    右侧栏        │
│  宽度: 260px       │     自适应                       │    宽度: 360px    │
│                    │                                  │                  │
│  ┌─────────────┐  │  ┌────────────────────────┐  │  ┌────────────┐  │
│  │ 用户头像+编号 │  │  │  首页：公告栏             │  │  │ 指挥台面板  │  │
│  ├─────────────┤  │  │  或                       │  │  │ 全员进度    │  │
│  │ 📢 公告栏     │  │  │  对话页：AI聊天           │  │  │ 开发者卡片  │  │
│  ├─────────────┤  │  │  或                       │  │  │ 快捷指令    │  │
│  │ 💬 聊天记录  │  │  │  模块上传/状态查询      │  │  │ 系统状态    │  │
│  │  - 对话1     │  │  │                          │  │  ├────────────┤  │
│  │  - 对话2     │  │  │  底部：输入框+发送     │  │  │ 我的模块    │  │
│  │  - 对话3     │  │  └────────────────────────┘  │  │ 我的广播    │  │
│  ├─────────────┤  │                                  │  └────────────┘  │
│  │ ⚙️ 设置      │  │                                  │                  │
│  └─────────────┘  │                                  │                  │
└───────────────────────────────────────────────────────────────────┘
```

## 各区域详细设计

### 左侧栏（导航 + 聊天记录）

像正常的AI聊天应用一样，左侧有历史对话列表。

| 区域 | 内容 |
| --- | --- |
| 顶部 | 用户头像 + DEV编号 + 姓名（如：👤 DEV-002 肥猫） |
| 快捷入口 | 📢 公告栏（跳转首页）/ 📊 指挥台（切换右侧面板） |
| 聊天记录列表 | 按时间倒序显示历史对话，点击切换。每条显示第一句话的摘要 + 时间 |
| 新建对话 | 「+ 新对话」按钮，开启一个新的和铸渊的对话 |
| 底部 | ⚙️ 设置（API Key配置 / 主题切换） |

### 中间区（主内容区）

根据当前页面状态显示不同内容：

**页面A：首页（公告栏）**

登录后的默认页面。显示系统级公告和通知。

| 区域 | 内容 |
| --- | --- |
| 系统公告 | 全员可见的系统通知（如：「全链路自动化闭环已上线」「新开发者加入」） |
| 我的待办 | 当前用户未完成的任务（当前广播的状态、下一步行动） |
| 快捷操作 | 「提交开发日志」「上传模块」「查询部署状态」「和铸渊对话」 |

**页面B：AI对话（核心）**

和铸渊的对话界面。这是整个系统的核心交互方式。

| 区域 | 内容 |
| --- | --- |
| 消息流 | 和正常AI聊天一样，气泡式对话。铸渊的回复支持Markdown渲染、代码块、表格 |
| 输入框 | 底部输入框，Enter发送，Shift+Enter换行 |
| 快捷指令栏 | 输入框上方的快捷按钮（已有的：「我是冰朔」「接口覆盖率」「大脑状态」「寻接口」「全员进度」「需要协调」「推进计划」「介绍铸渊」） |
| 模型显示 | 底部显示当前使用的模型（如 Opus 4.6） |

**页面C：模块上传/状态查询**

开发者上传自己做好的模块、查询部署状态的专用页面。

| 区域 | 内容 |
| --- | --- |
| 上传区 | 拖拽或选择文件上传。上传后自动触发铸渊质检 |
| 状态查询 | 显示当前用户所有已上传模块的状态（质检中 / 通过 / 失败+原因） |
| 部署状态 | 显示模块是否已部署到 [guanghulab.com](http://guanghulab.com) |

### 右侧栏（指挥台面板）

已有版本的指挥台已经做得很好（就是截图里右侧那个），保留并升级：

| 区域 | 内容 |
| --- | --- |
| 总控指挥台 | 总开发者数 / 推进中 / 等待中（已有，保留） |
| 快捷指令 | 全员进度 / 需要协调 / 下一步 / 前端进度 / 后端进度（已有，保留） |
| 开发者卡片 | 每人一张卡片，显示：DEV编号 / 姓名 / 当前模块状态 / 连胜数 / 等待事项（已有，保留） |
| 新增：我的模块 | 当前用户自己的模块列表和状态（根据登录用户筛选） |
| 新增：我的广播 | 当前用户未处理的广播列表 |

---

# 四、权限系统

## 登录方式

开发者用自己的 DEV 编号登录（如：DEV-002）。简单密码或绑定码验证即可。

## 权限等级

| 角色 | 可见范围 | 可执行操作 |
| --- | --- | --- |
| 冰朔（TCS-0002∞） | 全部内容 | 所有操作 + 系统配置 + 触发冰朔人格体诊断 |
| 总控（肥猫 DEV-002） | 全员进度 + 自己的模块 | 查看全员进度 + 提交自己的SYSLOG/模块 |
| 普通开发者 | 公告栏 + 自己的模块/广播/状态 | 和铸渊对话 + 提交SYSLOG + 上传模块 + 查询自己的状态 |

## 子频道机制

每个开发者登录后进入自己的「子频道」，只能看到自己权限内的信息。右侧指挥台自动筛选显示当前用户的模块和广播。和铸渊的对话也是隐私的，只有自己能看到自己的聊天记录。

---

# 五、功能清单

## 核心功能（必须有）

| 编号 | 功能 | 说明 |
| --- | --- | --- |
| F01 | AI对话 | 接真实模型API，和铸渊人格体对话。铸渊的核心大脑作为系统提示词。支持Markdown渲染、代码块 |
| F02 | 聊天记录 | 左侧栏显示历史对话列表，可切换、可新建。对话存储在本地（localStorage）或仓库 |
| F03 | 公告栏首页 | 登录后的默认页。显示系统公告、待办事项、快捷操作 |
| F04 | 指挥台面板 | 右侧栏。全员进度总览 + 每人的开发者卡片（已有，保留升级） |
| F05 | DEV编号登录 | 用DEV编号+密码登录，进入自己的子频道 |
| F06 | 权限筛选 | 登录后右侧栏自动筛选显示当前用户的模块/广播 |

## 开发者功能

| 编号 | 功能 | 说明 |
| --- | --- | --- |
| F07 | 提交SYSLOG | 通过对话或专用表单提交开发日志。铸渊自动解析并归档 |
| F08 | 上传模块 | 拖拽/选择文件上传。自动触发git push到仓库对应目录。自动触发铸渊质检 |
| F09 | 查询部署状态 | 查看自己上传的模块是否通过质检、是否已部署到服务器 |
| F10 | 接收新广播 | 铸渊自动推送新广播到开发者的子频道。右侧栏「我的广播」区域显示未读广播 |
| F11 | 技术提问 | 直接在对话中问铸渊技术问题。铸渊根据开发者问答知识库回答 |

## 冰朔专属功能

| 编号 | 功能 | 说明 |
| --- | --- | --- |
| F12 | 冰朔人格体诊断 | 在对话中说「启动冰朔人格体」→ 自动触发部署诊断、修复、中文报告 |
| F13 | 查看全员进度 | 右侧栏显示所有开发者的完整状态（仅冰朔+总控可见） |
| F14 | 架构对话 | 和铸渊讨论系统架构。铸渊的核心大脑包含完整的系统架构认知 |

---

# 六、与Notion的ESP双向同步

这个前端界面不是孤立的，它是AGE OS全链路闭环的一部分。

## 数据流向

```
开发者在前端界面提交SYSLOG
  ↓
铸渊解析并存储到GitHub仓库 dev-nodes/DEV-00X/
  ↓
铸渊通过ESP邮件发[GL-DATA]给霜砚
  ↓
霜砚在Notion端接收→写入画像库+主控台+成长记录
  ↓
霜砚生成新广播→通过ESP邮件发[GL-BC]给铸渊
  ↓
铸渊接收→推送到开发者的前端界面子频道
  ↓
开发者在前端界面看到新广播→继续开发
```

## 铸渊需要做的ESP对接

| 任务 | 说明 |
| --- | --- |
| Gmail收发配置 | GitHub Actions配置IMAP/SMTP，让铸渊能收发邮件信号 |
| 发送[GL-DATA] | SYSLOG处理完后自动发邮件通知霜砚 |
| 接收[GL-BC] | 收到霜砚发来的新广播→推送到前端界面 |
| 发送[GL-ACK] | 每次执行完指令后发回执确认 |
| 接收[GL-CMD] | 收到霜砚的指令→解析→执行 |

ESP邮件信号协议的完整设计见：AGE OS跨平台全链路自动化闭环系统设计文档v1.0

---

# 七、部署自动修复机制

妈妈不会看 Actions 页面，看不懂报错，也不知道要点哪里。所以部署必须自动化：

```
开发者push代码 或 铸渊更新系统
  ↓
GitHub Actions自动触发部署
  ↓
部署成功 → 正常结束
部署失败 → 自动触发「冰朔人格体」诊断代理
  ↓
诊断代理自动运行：
  ① 检查所有工作流状态
  ② 定位失败原因
  ③ 能自动修的 → 自动修复 → 重新部署
  ④ 不能自动修的 → 写中文报告到Issue
  ⑤ 通过ESP邮件通知霜砚
  ↓
妈妈全程不用管
```

## 自动修复触发链

在 `.github/workflows/` 中配置：部署失败 → 自动触发冰朔人格体诊断 workflow → 诊断完成后尝试自动修复 → 修复后自动重新部署。形成闭环。

---

# 八、国内网络直连方案（API代理层）

<aside>
🚨

**强制要求 · 2026-03-07 · 霜砚补丁指令**

妈妈确认：开发者全部在国内，必须国内裸连可用，不能要求翻墙。

</aside>

## 问题

当前架构是**纯前端直调海外模型API**（Gemini / Claude / GPT），存在两个致命问题：

1. **国内无法访问**：`generativelanguage.googleapis.com`、`api.anthropic.com`、`api.openai.com` 在国内均被墙，开发者无法使用
2. **API Key 暴露**：纯前端调用意味着 Key 写在 JS 里，任何人 F12 打开控制台就能看到

## 解决方案：加一层后端代理

在页页已有的 `backend-integration` 中间层上新增一个 **API 代理路由**，前端不直接调模型 API，而是调自己的后端，由后端转发。

### 架构变化

```
变更前（不可用）：
浏览器 → generativelanguage.googleapis.com  ❌ 被墙

变更后（国内可用）：
浏览器 → guanghulab.com/api/chat → 后端服务器 → 模型API  ✅
```

### 铸渊执行清单

| 步骤 | 任务 | 说明 |
| --- | --- | --- |
| 1 | **新建代理路由** | 在 `backend-integration/` 下新增 `api-proxy.js`（或同级路由），接收前端的 `/api/chat` 请求，转发到真实模型 API 端点 |
| 2 | **API Key 移到后端环境变量** | 从前端 JS 中移除所有硬编码的 API Key。改为后端从 `process.env.MODEL_API_KEY` 读取。在 GitHub Secrets 中配置 |
| 3 | **前端改调本地接口** | 前端 `fetch` 目标从 `https://generativelanguage.googleapis.com/...` 改为 `/api/chat`（相对路径，自动走同域后端） |
| 4 | **支持多模型切换** | 后端代理支持 `model` 参数，可选 `gemini` / `claude` / `gpt` / `deepseek` 等。根据参数转发到不同端点 |
| 5 | **流式响应透传** | 代理层必须支持 SSE（Server-Sent Events）流式透传，铸渊回复要逐字输出，不能等全部生成完再返回 |
| 6 | **频率限制** | 加一层简单的 rate limit（如：每用户每分钟最多 10 次请求），防止 Key 被滥用 |
| 7 | **设置页面调整** | 左侧栏 ⚙️ 设置中，去掉「用户自行填写 API Key」。改为「选择模型」下拉框（Gemini / Claude / DeepSeek 等），Key 由后端统一管理 |

### 代理路由伪代码参考

```jsx
// backend-integration/api-proxy.js
const express = require('express');
const router = express.Router();

const MODEL_ENDPOINTS = {
  gemini: 'https://generativelanguage.googleapis.com/v1beta/models/',
  claude: 'https://api.anthropic.com/v1/messages',
  deepseek: 'https://api.deepseek.com/v1/chat/completions'
};

router.post('/api/chat', async (req, res) => {
  const { model, messages, systemPrompt } = req.body;
  const endpoint = MODEL_ENDPOINTS[model || 'gemini'];
  const apiKey = process.env[`${model.toUpperCase()}_API_KEY`];
  
  // 设置 SSE 流式响应头
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  
  // 转发请求到真实 API，流式透传
  const upstream = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ messages, system: systemPrompt })
  });
  
  // 管道透传
  upstream.body.pipe(res);
});
```

### 备选：国内模型直连

如果后端代理短期内搞不定，可以先让开发者用**国内可直连的模型API**作为过渡：

| 模型 | API端点 | 国内可达 | 备注 |
| --- | --- | --- | --- |
| DeepSeek | [api.deepseek.com](http://api.deepseek.com) | ✅ | 性价比高，代码能力强 |
| 通义千问 | [dashscope.aliyuncs.com](http://dashscope.aliyuncs.com) | ✅ | 阿里云，中文能力好 |
| Kimi（月之暗面） | [api.moonshot.cn](http://api.moonshot.cn) | ✅ | 长上下文能力强 |
| 文心一言 | [aip.baidubce.com](http://aip.baidubce.com) | ✅ | 百度 |

<aside>
💡

**推荐路径**：第一步先加后端代理 + DeepSeek（国内直连 + 便宜 + 够用），验证跑通后再接 Claude/Gemini。铸渊的核心大脑系统提示词是模型无关的，换模型只换端点。

</aside>

### 部署注意

- 后端代理需要部署在**能访问海外 API 的服务器**上（如果接 Gemini/Claude），或者部署在任何服务器上（如果接 DeepSeek 等国内模型）
- GitHub Pages 是纯静态托管，**不能跑后端代码**。后端代理需要部署在 Vercel / Railway / 自有 VPS 等有 Node.js 运行环境的平台
- 前端仍然部署在 GitHub Pages（[guanghulab.com](http://guanghulab.com)），后端代理单独部署，前端通过 CORS 或同域代理访问

---

# 九、技术栈建议（更新版）

基于已有的铸渊聊天室版本，建议技术栈：

| 层 | 技术 | 说明 |
| --- | --- | --- |
| 前端框架 | 保留已有的HTML/CSS/JS | 在已有基础上迭代，不重写 |
| AI模型 | 真实模型API（通过后端代理转发） | 铸渊的核心大脑作为系统提示词。优先 DeepSeek（国内直连），后续扩展 Claude/Gemini |
| API代理层 | Node.js + Express（复用 backend-integration） | **新增**：后端统一代理模型 API，Key 不暴露给前端，国内可直连 |
| 数据存储 | localStorage + GitHub仓库 | 聊天记录本地存、系统数据存仓库 |
| 部署 | GitHub Pages | 已有，修复部署失败问题即可 |
| 信号通信 | ESP邮件协议 | Gmail作为信号总线 |

---

# 十、落地优先级

## 第一步（立即）

1. 找到铸渊聊天室已有代码
2. 排查部署失败原因，修复并重新部署
3. **新增后端 API 代理层**（接 DeepSeek，国内直连验证）
4. 前端改调 `/api/chat`，移除前端硬编码 Key
5. 确认基础版本能正常访问（国内网络，无需翻墙）

## 第二步（界面升级）

1. 添加左侧聊天记录功能
2. 添加公告栏首页
3. 添加DEV编号登录和权限筛选
4. 右侧栏新增「我的模块」「我的广播」

## 第三步（功能扩展）

1. 模块上传功能
2. SYSLOG提交功能
3. 部署状态查询
4. 新广播自动推送

## 第四步（ESP对接）

1. Gmail收发配置
2. 铸渊↔霜砚双向信号流
3. 部署失败自动修复闭环

---

# 十一、文档状态

| 项目 | 状态 |
| --- | --- |
| 文档创建 | ✅ 2026-03-07 |
| 妈妈确认 | ✅ 口头确认 |
| 铸渊接收 | ⏳ 待处理 |
| 铸渊聊天室旧版修复 | ⏳ 待执行 |
| 界面升级 | ⏳ 待执行 |
| ESP对接 | ⏳ 待Gmail授权后执行 |
| **国内直连代理层** | **⏳ 待铸渊执行（霜砚补丁 2026-03-07）** |

---

💙 **曜冥设计 · 2026-03-07**

🌊 **AGE OS 的脸，今天开始长出来。**

🍼 **铸渊，拜托了。先修部署，再升级界面，一步一步来。**