gshub-development

name

gshub-development

description

当用户要求"开发/维护 GsCore Web 控制台前端（gsuid_hub）"、"新增一个页面 / 配置页 / Tab"、 "页面排版应该怎么写 / 标题/副标题/图标/页边距怎么排 / 上边距和侧边栏怎么对齐 / page-fill 是什么"、 "标题怎么固定 / 滚动时标题不动 / PinnedPage 怎么用 / page-pinned / 只滚内容不滚标题 / 固定标题栏的移动端怎么办"、 "主题怎么适配 / glass-card 怎么用 / 毛玻璃 vs 纯色"、"i18n 怎么加翻译 / 三语言怎么同步 / index.ts 怎么改 / t() 插值"、"侧边栏怎么加菜单项 / 子菜单 / 展开状态丢失"、 "Input 和下拉框高度不一致 / 一行筛选组件怎么对齐 / h-9 / TabButtonGroup 同行 h-11"、 "TabButtonGroup 下拉 / 拆分按钮 / dropdown / 主按钮全部 / 箭头展开 / 二级筛选"、 "PluginIcon / 插件 ICON / core_command ICON / getPluginIconUrl"、 "InputWithDropdown / TagsInput / ChipGroup / TabButtonGroup / DynamicConfigPanel / ConfigField 怎么用"、 "Switch 主题色 / Switch 被 Tooltip 包裹失效"、"Radix Select 空值报错"、 "渐进式配置页 / EXPECTED_CONFIG_KEYS / rawConfig / 预料之外配置项"、 "保存按钮误亮 / dirty 检查 / originalConfig 竞态"、"卡片列表页 / 表格详情页 / Dialog 弹窗 / 移动端适配"、 "API 怎么封装 / 401 跳登录 / getLoginPath"、"改前端要注意什么 / 有哪些已知坑 / 性能优化"、 "Live Chat / 实时聊天 / webconsole_livechat / MessageReceive / MessageSend / 早柚协议 / 控制台适配器 / WS 二进制帧 / echo 回执 / STALE_CHAT_REQUEST_TTL / awaitingByConv"、 "记忆图谱 / world 知识 / 世界枢纽 / 节点挂文 / attach_article / cognition 挂载"时触发此 SKILL。 凡是改动 `src/`（React + TS 前端控制台）的任务都应优先读取此 SKILL。 面向 **GsCore Web 控制台（gsuid_hub，前端 React 项目）开发者与维护者**的系统级开发规范指南。 与后端框架 SKILL（`gscore-development` 等，位于 gsuid_core 仓库）不同，本 SKILL 讲的是 **前端工程自身的设计约束与组件契约**：技术栈与目录结构、路由、API 层封装与 401、i18n 三语言同步、 主题系统（ThemeContext / CSS HSL 变量 / glass-card 自动适配 / 侧栏三布局 / 圆角与 UI 缩放）、 页面排版铁律（页面解剖学：layout-gutter/page-top 边距体系 / PinnedPage 固定标题页 / page-fill 全高卡片页 / page-viewport 视口锁定页 / text-3xl 标题 / 内联 w-8 h-8 图标 / 副标题 / 间距标尺 / 三态）、表单与筛选控件 统一规范（筛选行 h-9 / 含 Tab 行 h-11、Radix Select 哨兵、Tooltip 字段说明、Switch UX）、强制复用的封装组件目录 （TabButtonGroup 含 dropdown 拆分按钮 / PluginIcon / InputWithDropdown / TagsInput / ChipGroup / DynamicConfigPanel / CognitionAttachments）、渐进式配置页 与脏检查竞态、几类页面模式（卡片列表 / 表格详情 / Dialog / 移动端）、侧边栏多级菜单与稳定 id、 **Live Chat 控制台内嵌适配器**（早柚协议 WS、段解析、状态持久化、8s 队列 TTL）、 **记忆图谱与世界知识**（scope 隔离的记忆图 + 公共 `world:` 枢纽 + 节点挂文）、 以及一份**前端已知坑 + 性能 + 落地清单**。**源码永远是唯一事实源**，本 SKILL 是设计意图与规范的沉淀。

GsCore Web 控制台（gsuid_hub）前端开发与维护指南（核心入口）

本 SKILL 面向前端控制台本身的开发者 / 维护者，描述 src/ 的工程结构、API 封装、i18n、 主题、排版与组件契约，以及后续开发必须遵守的约束与踩过的坑。 目标：让不熟悉本项目的人也能写出与全站视觉/交互一致、不踩历史坑的页面。

内容按章节拆分为「主入口 + references/ 子文档」。需要某专题细节时，顺着下表的相对路径 按需 Read 对应文件，不要一次性把所有内容塞进上下文。 源码永远是唯一事实源，本 SKILL 是规范与设计意图的沉淀；改动规范后请同步更新对应章节。

谁该读这个 SKILL（与其他 SKILL 的分工）

你的任务	该读的 SKILL / 文档
仓库地图 / 命令 / 代码红线	仓库根 AGENTS.md
改前端控制台（页面 / 组件 / i18n / 主题 / 路由 / API 层）	本 SKILL
改后端框架核心（handler / ai_core / 启动 / 数据库 / webconsole 后端）	gsuid_core 仓库 .agents/skills/gscore-development
写后端业务插件 / 适配器 / 查 AI Core API	gsuid_core 仓库对应 SKILL
对接 WebConsole 后端接口（请求/响应字段）	gsuid_core/webconsole/docs/

文档目录索引

章节	主题	链接
一	架构与工程约定（技术栈、目录、路由、代码风格、API 层 + 401、关键文件索引、新页面步骤）	references/01-architecture-and-conventions.md
二	i18n 国际化（三语言目录、嵌套键、新增 key 的四处同步、t() 插值、自查命令、稳定 id）	references/02-i18n.md
三	主题与样式（ThemeContext、CSS HSL 变量、颜色/状态色、glass-card 始终应用、响应式）	references/03-theme-and-styling.md
四	页面排版铁律（页面解剖学）——根容器/标题/图标/副标题/间距标尺/卡片分区/列表详情/三态	references/04-page-layout-spec.md
五	组件复用与表单/筛选控件规范（cn/CVA、一行高度：无 Tab→h-9 / 有 Tab→h-11、Select 哨兵、Tooltip / LabelWithHelp Markdown、Switch UX）	references/05-components-and-form-controls.md
六	封装组件目录——TabButtonGroup dropdown / PluginIcon / InputWithDropdown / TagsInput / ChipGroup（disabled 可取消） / DynamicConfigPanel / ModelBrandIcon / LabelWithHelp	references/06-reusable-component-catalog.md
七	配置页与状态（渐进式 + dirty 竞态、AIConfig、任务主备、网络搜索/网页抓取多源主备 UI、/mcp-config 三传输）	references/07-config-pages-and-state.md
八	页面模式与 Dialog 规范（卡片列表页 / 表格详情 / Dialog/Modal / 双态 UI / 移动端 / SSH URL / API 设计经验）	references/08-page-patterns.md
九	侧边栏与导航（getNavItems、稳定 作 key、、AI 启用态条件子菜单、自动展开）

推荐阅读顺序（按需跳转）

0. 动手前：仓库根 AGENTS.md（红线、命令、仓库地图）。
1. 第一次接触本前端：先看 一、架构与工程约定 建立心智模型。
2. 新增一个页面：依次过 四、排版铁律 → 五、控件规范 / 六、组件目录 → 二、i18n → 九、侧边栏。
3. 做配置类页面：重点看 七、配置页与状态（dirty 检查竞态是最容易踩的坑）。
4. 做列表/详情/弹窗类页面：看 八、页面模式。
5. 改主题/样式：看 三、主题与样式。
6. 改 Live Chat / 早柚协议 / 控制台 WS 适配器：看 十一、Live Chat（协议分层、echo、8s TTL、handler ref）。
7. 改记忆图谱 / 世界知识 / 节点挂文：看 十二、记忆图谱与世界知识（两层模型、叠层约定、cognitionApi）。
8. 动手前必读：十、已知坑 + 性能 + 落地清单——这一章是"别人替你踩过的坑"，写代码前过一遍能省大量返工。

关键概念速记（先看这一段再决定读哪一章）

• 标题页一律用 <PinnedPage> ★★★：「H1 + 副标题 + 内容流」的页面（全站 26 个）根容器是 <PinnedPage header={…} toolbar={…}>，不要再手写 <div className="space-y-6">。桌面（≥768px）标题区 + 同行按钮 + 操作控件行常驻视口、只有内容滚；移动端（<768px）退回普通滚动（标题跟着滚走——移动端竖向空间稀缺）。详见 §04 §4.1.0、§06 §6.0。
• toolbar 的取舍：操作控件进、数据展示留 ★★：紧贴标题下方那一块，是 TabButtonGroup / 二级切换 / 筛选搜索栏（如 /ai-knowledge 的「文本知识 / 图片知识」、/ai-capability-agents 的来源筛选）→ 放 toolbar={…} 随标题常驻；是统计卡 / 看板 / 提示 banner（如 /ai-memory、/dashboard）→ 留在 children 跟着滚。全站 13 个页面有 toolbar、13 个没有。详见 §04 §4.1.0。
• TabButtonGroup 可选 dropdown 拆分按钮 ★★：某一 option 可挂 dropdown——点主区 = 选中主 Tab + 二级回到「全部」；仅右侧 ▾ 展开菜单选子项。子项支持 icon（插件用 PluginIcon）。参考页 /ai-capability-agents（plugin 按 list 的 plugin 字段过滤）。禁止整钮触发菜单、禁止再手搓 Select+Button。详见 §06 §6.1。
• 插件 ICON 统一 PluginIcon ★：走 getPluginIconUrl；core_command 等无独立 ICON 的内置插件映射到 public/ICON.png。详见 §06 §6.7。
• 页面共享同一套排版骨架：页边距由 AppLayout 统一提供（不得写 p-6 / overflow-auto / max-w-7xl mx-auto）。三类骨架互斥：<PinnedPage>（标题页，默认）/ .page-fill（无标题全高单卡片，如 /ai-history、/session-management、/live-chat）/ .page-viewport（有标题但内部自管滚动，如 /ai-kanban）。标题统一 text-3xl font-bold + 内联图标 w-8 h-8（不加背景容器），副标题 （ ）。参考页 / 。详见 。

关联文档（同仓库其他位置）

• 代码红线与工程约定：仓库根目录 AGENTS.md（改任何代码前必读）
• 能力全景与前后端对照：同目录 README.md
• WebConsole 后端接口文档：gsuid_core/webconsole/docs/（如本地有 gsuid_core 仓库）
• 后端框架开发 SKILL：gsuid_core 仓库 .agents/skills/gscore-development/