a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
421 lines
18 KiB
Markdown
421 lines
18 KiB
Markdown
# 🌐 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 的脸，今天开始长出来。**
|
||
|
||
🍼 **铸渊，拜托了。先修部署，再升级界面，一步一步来。** |