NotratUI控制技能

概述

Notrat UI Control（无源码操控指南）

核心能力：不碰 Notrat 源代码，纯靠 MCP 工具实时操控 UI 外观。

一、可用工具一览

二、Notrat 主题系统架构（源码逆向）

2.1 CSS 变量体系

Notrat 使用 shadcn/ui 风格 的 CSS 变量 + Tailwind 主题系统。所有颜色都是 HSL 无前缀格式（如 0 0% 10%，不带 hsl()）。

2.2 核心变量速查表

全局基础变量

侧边栏专用变量

主色调变量

排版变量

布局变量

2.3 主题选择器优先级

Notrat 的主题通过 :root 上挂 class 实现，选择器优先级从低到高：

:root                          ← 最基础（fallback 值）
:root.theme-minimalist:not(.dark)  ← 极简白（默认 light 主题）
:root.theme-minimalist.dark       ← 极简白 dark
:root.theme-oceanic:not(.dark)    ← 海洋蓝
:root.theme-oceanic.dark          ← 海洋蓝 dark
:root.theme-forest:not(.dark)     ← 森林绿
:root.theme-forest.dark           ← 森林绿 dark
...（更多主题）

⚠️ 关键陷阱：直接改 :root 不一定生效！主题 class 选择器（如 .theme-minimalist:not(.dark)）优先级更高，会覆盖 :root 的值。

正确写法：同时写两个选择器，双保险：

selector: ":root, :root.theme-minimalist:not(.dark)"

2.4 已知主题列表

三、完整 CSS Selector 速查表（源码逆向）

以下选择器全部从 Notrat 源码 src/styles/index.css、src/styles/tiptap.css 及各组件 TSX 中提取。

3.1 Activity Bar（活动栏 / 最左侧图标栏）

3.2 Sidebar Panel（侧边栏面板）

3.3 Editor（编辑器区域）

3.4 ProseMirror / TipTap（Markdown 编辑器核心）

3.5 TipTap 数学 / 公式

3.6 代码高亮（highlight.js）

3.7 Slash Menu（斜杠菜单）

3.8 Status Bar（底部状态栏）

注意：StatusBar 组件主要使用 Tailwind 内联类，常用模式：

• text-[10px] text-muted-foreground/70 — 状态栏小字
• text-[10px] text-muted-foreground/80 — 状态栏文字
• text-[10px] font-mono text-muted-foreground/70 — 等宽状态文字
• text-[10px] text-foreground/70 — 强调状态文字
• text-[11px] font-semibold — Notrat 标题
• bg-muted/30 — 状态栏背景

3.9 Title Bar（顶部标题栏）

常用 Tailwind 类：

• h-8 bg-background border-b border-border/50 — 标题栏容器
• text-sm font-medium text-foreground — 标题文字
• w-11 h-8 text-muted-foreground hover:bg-muted hover:text-foreground — 窗口控制按钮

3.10 Chat / Session List（聊天侧边栏）

SessionList 常用 Tailwind 类：

• text-foreground — 会话标题
• text-muted-foreground — 预览文本、图标
• text-muted-foreground/70 — 时间戳
• text-muted-foreground/60 — 搜索图标
• text-accent-color — 当前选中会话
• bg-muted/50 — 搜索框背景

3.11 Chat Input（聊天输入框）

常用 Tailwind 类：

• bg-muted/30 rounded-2xl border border-border — 输入区容器
• bg-background border-0 rounded-xl focus:ring-2 focus:ring-primary/20 — textarea
• placeholder:text-muted-foreground/50 — placeholder 颜色
• bg-accent-color/10 border border-accent-color/30 — 上下文提示条
• bg-muted rounded-full text-xs — 标签 chip
• text-muted-foreground hover:text-foreground hover:bg-muted — 发送按钮

3.12 Immersive AI（沉浸式 AI 界面）

3.13 Mention Dashboard（@提及面板）

3.14 Scrollbar（滚动条）

3.15 Tree / react-arborist（文件树底层）

3.16 Excel Editor（Excel 编辑器）

3.17 Source Code Editor（源码编辑器）

3.18 Diagram Preview（图表预览）

3.19 Icon Colors（图标颜色类）

3.20 Misc / 动画

3.21 Tailwind Utility 选择器（高频使用）

以下 Tailwind class 在源码中频繁出现，可通过 CSS 变量统一控制：

四、实战配方（直接抄）

4.1 改全局文字颜色更深

{
  "selector": ":root, :root.theme-minimalist:not(.dark)",
  "styles": {
    "--muted-foreground": "0 0% 25%",
    "--foreground": "0 0% 8%"
  }
}

4.2 暖白主题（全局暖色）

{
  "selector": ":root, :root.theme-minimalist:not(.dark)",
  "styles": {
    "--background": "40 30% 99%",
    "--foreground": "0 0% 8%",
    "--card": "40 20% 99%",
    "--popover": "40 20% 99%",
    "--secondary": "40 20% 96%",
    "--muted": "40 20% 95%",
    "--accent": "40 20% 95%",
    "--muted-foreground": "0 0% 25%",
    "--border": "38 15% 88%",
    "--input": "40 20% 96%",
    "--sidebar-background": "40 30% 96%",
    "--sidebar-foreground": "0 0% 10%",
    "--sidebar-border": "38 15% 88%",
    "--ring": "38 60% 50%"
  }
}

4.3 改活动栏图标颜色

{
  "selector": ".activity-bar-item",
  "styles": {
    "color": "hsl(0 0% 30%) !important"
  }
}

// 激活状态
{
  "selector": ".activity-bar-item.active",
  "styles": {
    "color": "hsl(215 95% 55%) !important"
  }
}

4.4 改标签页样式

{
  "selector": ".editor-tab",
  "styles": {
    "font-size": "13px",
    "color": "hsl(0 0% 30%)"
  }
}

// 激活标签
{
  "selector": ".editor-tab.active",
  "styles": {
    "color": "hsl(0 0% 8%)",
    "font-weight": "600"
  }
}

4.5 改滚动条样式

{
  "selector": ".custom-scrollbar::-webkit-scrollbar-thumb",
  "styles": {
    "background": "hsl(0 0% 70%)",
    "border-radius": "4px"
  }
}

{
  "selector": ".custom-scrollbar::-webkit-scrollbar-thumb:hover",
  "styles": {
    "background": "hsl(0 0% 50%)"
  }
}

4.6 改代码块字体大小

{
  "selector": ".ProseMirror pre, .code-block-wrapper pre",
  "styles": {
    "font-size": "13px"
  }
}

4.7 改沉浸式 AI 界面

{
  "selector": ".immersive-ai-canvas",
  "styles": {
    "background": "hsl(220 20% 97%)"
  }
}

// 用户消息气泡
{
  "selector": ".immersive-ai-user-bubble",
  "styles": {
    "background": "hsl(var(--primary) / 0.08)",
    "border-radius": "12px"
  }
}

4.8 改状态栏

{
  "selector": ".status-bar",
  "styles": {
    "background": "hsl(0 0% 95%)",
    "color": "hsl(0 0% 30%)",
    "font-size": "11px"
  }
}

4.9 改标题栏

{
  "selector": ".app-region-drag",
  "styles": {
    "background": "hsl(0 0% 98%)",
    "border-bottom": "1px solid hsl(0 0% 90%)"
  }
}

4.10 改侧边栏会话记录字体加深加大

// 1. 改 CSS 变量（从根源改）
{
  "selector": ":root, :root.theme-minimalist:not(.dark)",
  "styles": {
    "--muted-foreground": "0 0% 25%",
    "--sidebar-foreground": "0 0% 10%"
  }
}

// 2. 强制覆盖（变量改不动时的暴力方案）
{
  "selector": ".text-muted-foreground, [class*="text-muted-foreground"]",
  "styles": {
    "color": "hsl(0 0% 25%) !important",
    "opacity": "1 !important"
  }
}

4.11 改字号

{
  "selector": ":root, :root.theme-minimalist:not(.dark)",
  "styles": {
    "--font-size-base": "15px",
    "--font-size-sm": "13px"
  }
}

4.12 自定义主色调

{
  "selector": ":root, :root.theme-minimalist:not(.dark)",
  "styles": {
    "--primary": "270 80% 55%",
    "--accent-color": "#8b5cf6",
    "--accent-hover": "#7c3aed",
    "--ring": "270 80% 55%"
  }
}

常用色相参考：

4.13 切换主题（config 层面）

// 通过 config_set
{ "key": "theme", "value": "dark" }

// 或通过 toggle
config_toggle_theme()

// 或直接读当前配置
config_get_all()

4.14 恢复默认

slot_clear_all()  // 清除所有 style/props/behavior/content 覆盖

五、Tailwind class 与 CSS 变量对应关系

⚠️ Tailwind 的 /70 透明度后缀会在编译后变成 opacity: 0.7 或 color-mix()，用 !important 强制覆盖时需要同时设 color 和 opacity。

透明度叠加问题示例：

text-muted-foreground/70  →  hsl(0 0% 45% / 0.7)  →  实际亮度 ≈ 58%  ❌ 看不清
text-muted-foreground/60  →  hsl(0 0% 45% / 0.6)  →  实际亮度 ≈ 63%  ❌ 更看不清

修改 --muted-foreground 为 25% 后：
text-muted-foreground/70  →  hsl(0 0% 25% / 0.7)  →  实际亮度 ≈ 33%  ✅ 清楚
text-muted-foreground/60  →  hsl(0 0% 25% / 0.6)  →  实际亮度 ≈ 40%  ✅ 可接受

六、调试技巧

6.1 查看当前状态

config_get_all()   // 看当前主题、字号等配置
ui_get_state()     // 看当前活动 tab、打开文件

6.2 CSS 变量改了没效果？

排查顺序：

1. 选择器优先级：主题 class（如 .theme-minimalist）比 :root 高，需要同时写两个
2. Tailwind 编译：Tailwind 在构建时把 text-muted-foreground 编译成 color: hsl(var(--muted-foreground))，改变量会影响所有用了这个 class 的元素
3. 透明度后缀：text-muted-foreground/70 = hsl(var(--muted-foreground) / 0.7)，需要额外加 opacity: 1 !important
4. !important 叠加：如果之前注入了 !important 的样式，后注入的也需要 !important
5. slot_clear_all 后重设：如果改动叠加太多产生冲突，先 clear 再重新设

6.3 批量覆盖策略

如果 CSS 变量方案不够，可以按 Tailwind class 名批量覆盖：

// 所有次要文字
{ "selector": ".text-muted-foreground", "styles": { "color": "hsl(0 0% 25%) !important" } }

// 所有主要文字
{ "selector": ".text-foreground", "styles": { "color": "hsl(0 0% 8%) !important" } }

// 所有小字
{ "selector": ".text-\[10px\]", "styles": { "font-size": "12px !important" } }

// 侧边栏整体
{ "selector": ".sidebar-panel *", "styles": { "font-size": "14px !important" } }

6.4 查看实际 DOM 结构

用 ui_get_state() 获取当前 UI 状态，或用 ui_click 配合 ui_type 模拟交互验证样式是否生效。

七、注意事项

1. slot 覆盖是临时的：slot_clear_all() 或刷新页面后恢复默认。如需永久生效，需要改 Notrat 源代码。
2. 全局变量影响范围大：改 --muted-foreground 会影响整个 app 所有用了这个变量的组件，不只侧边栏。
3. HSL 格式：Notrat 的 CSS 变量值不含 hsl() 前缀（写 0 0% 10% 而非 hsl(0 0% 10%)）。但在 slot_set_style 的 styles 里写最终 CSS 值时（如直接给某个元素设 color），需要带 hsl()（因为 slot 注入的是最终 CSS 值，不是变量赋值）。**改变量本身时不需要 hsl()**。
4. **!important 要慎用**：一旦加了 !important，后续所有覆盖都需要 !important。能用变量解决的优先用变量。
5. 暗色主题适配：如果用户用暗色主题，选择器要改成 :root.theme-minimalist.dark 或对应的主题 class。
6. reload 会清除覆盖：app_reload_window() 会清除所有 slot 注入的样式。需要时重新注入。
7. 自定义 class vs Tailwind class：自定义 class（如 .activity-bar、.editor-tab）可直接用 selector 覆盖。Tailwind class（如 .text-muted-foreground）背后是 CSS 变量，改变量更优雅。
8. 伪元素：.activity-bar-item::before、.editor-tab.active::after 等伪元素可以直接作为 selector 传给 slot_set_style。

八、弹窗与对话框（2026-07-30 新增）

8.1 语义钩子类速查

所有弹窗都已挂语义钩子类（与 .notrat-editor-root 同一约定），DIY / slot_set_style 直接定位：

8.2 弹窗 z-index 层级表

改弹窗层级前先想交互：角落提醒必须低于模态框，否则会把模态框顶穿。

8.3 一条规则统一改全部弹窗

{
  "selector": ".notrat-corner-notify, .notrat-recommend-dialog, .notrat-import-dialog, .notrat-global-dialog",
  "styles": { "border-color": "#e07856", "border-radius": "16px" }
}

8.4 单独改角落提醒（示例）

{ "selector": ".notrat-corner-notify", "styles": { "border": "2px solid hsl(16 68% 50%)", "box-shadow": "0 8px 30px hsl(16 68% 50% / 0.25)" } }
{ "selector": ".notrat-corner-notify-item-action", "styles": { "background": "hsl(16 68% 50%)", "color": "#fff" } }

九、踩过的坑（2026-07 实录）

1. CDN Referer 热链保护：public.cdn.nestmold.cn 的图片带 Referer 请求返回 403，不带 200。Electron 里 <img> 默认带 Referer，技能图标/头像会裂图。源码里写 <img> 必须加 referrerPolicy="no-referrer"。slot 改不了这个属性，只能改源码。
2. backdrop-filter 创建 stacking context：给 .activity-bar 这类容器加 backdrop-filter: blur(...) 后，整个子树（含内部 z-50 的下拉菜单）会被主内容区压在下面——菜单 z-index 多大都没用。弹层被遮挡时先查祖先有没有 backdrop-filter / filter / transform / perspective。
3. Electron 不支持 window.prompt()：调用直接抛 Error: prompt() is not supported。需要输入时改用应用内对话框（如 ImageDialog）或内联编辑，keymap 里用 window.dispatchEvent(new CustomEvent(...)) 把事件桥到 React 组件里开对话框。
4. slot 注入 CSS 变量 vs 最终值的区别：改 :root 变量写 HSL 通道（40 30% 96%），改具体元素的 color/background 写完整值（hsl(40 30% 96%) 或 #hex），别混。
5. 功能提交夹带实验代码：UI 突然和原版不一样时，先 git log -p -- <文件> 查最近提交——已发生两次（Icons.tsx 被 debug 提交夹带全量改写、index.css 被 Slot 系统提交夹带背景实验 CSS）。
6. 新增主进程/ preload IPC 必须完全重启 dev 应用：Ctrl+R 只刷渲染进程，新 handler 不存在会抛「No handler registered」并被静默 catch，表现为"功能完全没反应"。

十、相关公开接口（NotratPayment / notrat.cn）

mente 侧渲染层不直接调，走 preload：window.electronAPI.notratAuth.getPublicCampaigns() / getRecommendedSkills()。