Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007

Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码

2026-07-17 15:59:55 +08:00

18 KiB

Raw Permalink Blame History

🌐 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

右侧栏（指挥台面板）

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

区域	内容
总控指挥台	总开发者数 / 推进中 / 等待中（已有，保留）
快捷指令	全员进度 / 需要协调 / 下一步 / 前端进度 / 后端进度（已有，保留）
开发者卡片	每人一张卡片，显示：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代理层）

问题

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

国内无法访问：generativelanguage.googleapis.com、api.anthropic.com、api.openai.com 在国内均被墙，开发者无法使用
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 由后端统一管理

代理路由伪代码参考

// 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	✅	性价比高，代码能力强
通义千问	dashscope.aliyuncs.com	✅	阿里云，中文能力好
Kimi（月之暗面）	api.moonshot.cn	✅	长上下文能力强
文心一言	aip.baidubce.com	✅	百度

部署注意

后端代理需要部署在能访问海外 API 的服务器上（如果接 Gemini/Claude），或者部署在任何服务器上（如果接 DeepSeek 等国内模型）
GitHub Pages 是纯静态托管，不能跑后端代码。后端代理需要部署在 Vercel / Railway / 自有 VPS 等有 Node.js 运行环境的平台
前端仍然部署在 GitHub Pages（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作为信号总线

十、落地优先级

第一步（立即）

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

第二步（界面升级）

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

第三步（功能扩展）

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

第四步（ESP对接）

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

十一、文档状态

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

💙 曜冥设计 · 2026-03-07

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

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