Deshab-OS/docs/桌面设计.md

Deshab 桌面设计文档

desktop.elf（Winux-Kate结构）的页面、应用、视觉、渲染与性能设计。事实以CODE/desktop/main.c与CODE/UTSM/include/utsm/deshab_ui.h为准。

---

1. 概述

desktop.elf是B4锚点加载的桌面管理器，全屏独占framebuffer，复刻Winux-Kate布局。直接轮询PS/2键盘/鼠标，通过boot context获取内核服务，EXIT返回DSK。

Kate之外的桌面特性：RTC+UP计时；VOL/BRIGHT可拖滑块（BRIGHT真实调暗）；开机打字机Boot屏；FILES双击载入EDITOR（FAT32读写+SAVE）；窗口单实例聚焦；Linux应用图标集成（LINUXAPP.CNF→兼容层委托执行）。

---

2. 整体布局

app-shell
├── topbar (34px)：品牌+工作区切换+页面切换+PG时钟
├── page-host
│   ├── 1·DASHBOARD：TERM-01/TERM-02/EDITOR/FILES四面板+StatusBar(32px)
│   ├── 2·IDE：标签栏+编辑宿主
│   ├── 3·DESKTOP：图标网格+窗口+任务栏
│   └── 4+/CUSTOM：外部.elf全屏宿主(≤4页，可增删)
└── task-view overlay（工作区卡片）

布局常量：KATE_TOPBAR_H=34, KATE_STATUSBAR_H=32, KATE_PAGE_PAD=8, 图标104×90, 网格gap=18, pad=24。

---

3. 页面系统

页	名称	内容
1	DASHBOARD	四面板(TERM-01+TERM-02+EDITOR+FILES)+StatusBar(时钟/UP/VOL/BRIGHT)
2	IDE	标签栏+编辑宿主，多标签+新建
3	DESKTOP	图标网格+浮动窗口+任务栏
4+	CUSTOM	外部.elf全屏宿主，MAX_CPAGES=4

• 工作区MAX_WS=6，记录离开时页面；窗口MAX_WINDOWS=8，支持拖拽/聚焦/最小化/关闭
• RTC秒tick仅在DASHBOARD页且非任务视图时触发状态栏重绘

---

4. 应用机制（app_descriptor）

所有应用以app_descriptor注册（MAX_APPS=16 = 6内置+≤8 Linux应用+余量）：

typedef struct {
    const char *name, *display_name;
    u32 default_w, default_h;
    app_create_fn  on_create;    // 内置应用
    app_event_fn   on_event;
    app_draw_fn    on_draw;
    app_destroy_fn on_destroy;
    const char *elf_name;        // 外部ELF全屏宿主(8.3名)
    const char *linux_cmd;       // Linux兼容层命令
} app_descriptor;

elf_name与linux_cmd互斥（elf_name优先）；仅设linux_cmd时须提供on_create（内置终端窗口承载）。

内置应用：shell(SHELL.ELF)、cmd(CMD.ELF)、editor(内置)、fileman(FILEMAN.ELF)、calc(内置)、browser(BROWSER.ELF)。

单实例策略：固定地址ADDR_TERM1=0x4000000/ADDR_TERM2=0x4100000/ADDR_TERMWIN=0x4200000/ADDR_EDDASH=0x5000000/ADDR_EDWIN=0x5100000/ADDR_CALC=0x6000000。

独立工具应用共享CODE/tools/desktop_app.h：dsk_entry入口+da_app_context(fb+block read/write+kernel_api)，block API从kernel_api+0xA8取(read@+0x10,write@+0x18)。

---

5. 视觉系统

5.1 "Sealed Arc"设计语言

三隐喻：Arc(弧)——圆角/弧形边框；Seal(封)——卡片容器/发光边缘；Flow(流)——渐变/平滑过渡。

5.2 设计令牌

层	内容
L0 原始色板	Abyss Blue(900–100九级)/Seal Cyan(主操作)/Arc Violet(次级)/Neutral 0–900/语义色/渐变三色
L1 语义色值	暗色主题(Shell: BG=DP_ABYSS_900, 主文字=DP_NEUTRAL_700, 强调=DP_SEAL_500)；亮色(FirstInit/DSK)
L2 组件令牌	圆角/高度/内边距/边框，引用L1

约定：色值0xAARRGGBB；所有UI组件必须经deshab_ui.h取参数，禁止硬编码。

5.3 落地决策

• DU_RADIUS_MD/LG改为0(直角)，仅小按钮4px/模态框16px/药丸全圆角
• 简化面板渲染/窗口光晕/不必要渐变；hover提亮，active反转色

---

6. 渲染架构

6.1 双缓冲

渲染到sprite buffer(SPRITE_BUF_ADDR=0x7000000, 112MB, identity-mapped)，完成后flip到真实framebuffer。flip_buffer()全屏拷贝；flip_rect(x,y,w,h)仅拷贝指定矩形。

6.2 脏矩形

MAX_DIRTY_RECTS=16，mark_dirty记录变化区域，溢出降级全屏重绘。每帧合并为包围盒→redraw_all+flip_rect(合并区域)。终端面板有行级脏标记(dirty_rows+any_dirty)。

6.3 光标

软光标24×24，移动时save/restore背景+两次局部flip_rect(旧位置+新位置)。动画延时期间持续轮询鼠标。

6.4 主循环

轮询PS/2鼠标→滑块拖拽→排空键盘缓冲→handle_key→RTC tick→
  need_redraw? 全屏重绘+flip / 脏矩形→redraw_all+flip_rect(包围盒)
  moved? 光标save/restore+局部flip

---

7. FILES面板与FAT32集成

• 经f32_list_root枚举FAT32根目录(MAX_FILES=24)
• 过滤：跳过子目录、.ELF可执行、FIRSTINI*(系统模块)
• 显示名↔8.3内部名双向转换
• 双击：f32_read_root_file读入EDITOR(过滤不可打印字符，保留\n/\t)，聚焦EDITOR；SAVE经FAT32写路径回写
• 无块设备时降级为空态

---

8. 桌面图标来源（.lnk快捷方式 + LINUXAPP.CNF Linux应用）

8.1 .lnk快捷方式

setup_desktop_icons()先上架4个用户快捷方式（编辑器/文件管理/浏览器/终端），shortcuts_refresh()当前为硬编码列表（SYSTEM/user/desktop/*.lnk已随镜像分发，解析留待后续）；快捷方式图标app_id=-1，双击经launch_external_elf()加载对应工具ELF全屏宿主。

8.2 LINUXAPP.CNF Linux应用

快捷方式之后追加Linux应用图标。无论Linux兼容层服务是否可用都注册：桌面启动时读FAT32根目录LINUXAPP.CNF(8.3名LINUXAPPCNF)，每行一条：显示名|linux命令。规则：空行/#注释忽略；显示名≤11字符(DA_LINUXAPP_NAME_CAP=12)，命令≤63字符(DA_LINUXAPP_CMD_CAP=64)；按空格分词(首token为程序路径，绝对路径直接用，裸命令补/bin/前缀)；DA_LINUXAPP_MAX=8。CNF缺失/无有效行时回退内置默认3条（HELLO=/bin/echo、UNAME=/bin/uname -a、LS=/bin/ls -l /，均为Arch rootfs与initramfs busybox共有命令）。

• 图标：draw_icon_linux暗底终端+霓虹绿>_；服务不可用(VMX缺失/guest未驻留)时改用KS_TEXT_DIM置灰（g_lnx_svc_up=0）
• 双击：内置终端窗口承载（720×480，标题NAME . Linux）→回显$ <cmd>→lnx_on_create运行时复查服务：
  • 可用：linux_compat_service.exec()同步委托执行（UI冻结），输出经ANSI CSI剥离/^M忽略/\t展开一次性追加，[exit N]按退出码绿/琥珀
  • 不可用：红色提示linux: compat service unavailable+[exit -1]，绝不panic
• 串口打点：linux apps: loaded LINUXAPP.CNF/builtin defaults/service unavailable (icons greyed)、linux app registered: <名>、linux exec、app launched

---

9. 输入系统

• 事件模型：EV_MOUSE_MOVE/DOWN/UP, EV_KEY_DOWN/UP（坐标/按键/scancode/修饰态）
• 鼠标：PS/2轮询3字节包(g_mouse_buf)，按下/释放边沿标志
• 键盘：排空0x60缓冲，处理0xE0前缀+修饰键
• 双击：g_last_click_tsc+位置阈值(TSC计时)
• 交互控件：窗口拖拽、任务栏项、VOL/BRIGHT滑块(slider_set拖拽)、亮度延迟应用

---

10. 性能设计

瓶颈	对策	状态
全屏flip拷贝	双缓冲+脏矩形合并，仅flip包围盒	✅
圆角/渐变栅格化	DU_RADIUS_MD/LG改直角、简化光晕	✅
亮度调整	延迟应用(g_bright_applied)	✅
终端/编辑器重绘	行级脏标记增量渲染	✅
redraw_all全屏绘制	真正局部重绘	🔶
memcpy效率	SIMD/ERMS加速	🔶(需SSE启用)

---

相关文档：ARCHITECTURE.md、BOOT_SEQUENCE.md、兼容层设计.md