knight-ui 1.1.6 → 1.1.7

package/README.md

@@ -151,7 +151,7 @@ Knight-UI 通过 CSS 自定义属性（CSS Variables）实现主题系统。在
 
 > **例外：内容色板（`--ku-content-*`）不带 fallback** —— 它由 JS 按主题现值拼进内联样式（`rgb(var(--ku-content-blue))`），写不了兜底：过期的兜底会静默画出**旧主题**（表现成"主题切换失灵"），而缺失的兜底立刻可见。因此 `tokens.css` 必须被引入，见下。
 
-> **亮色主题状态**：色阶、语义重绑、缺失/写反的覆盖都已就位 —— 包括 `--ku-color-glass-menu` 与 `--ku-color-mask` 两处此前会继承暗色值、导致亮色下弹层是一块暗板 / 遮罩压过头的**真 bug**；`Monaco` 的代码面则刻意**不跟随**本库主题（固定用 VS 自带的 `vs-dark`，见「代码面」一节）。语义与方向现在在两个主题下都成立。**表面分档与玻璃分档都已重推过一轮**（见下方「亮色的表面分档」与「亮色的玻璃分档」），阴影重量也在同一轮补了亮色值。**已知缺口三处**：① `Markdown` 的代码块仍注入仅暗色的 highlight.js 样式表（亮色下浅底浅字，需第二份样式表）；② 玻璃在**浅色内容**上方的对比度——这是暗色侧的问题，本轮按范围只重标了亮色，见「亮色的玻璃分档」末尾的实测表；③ 亮色 `--ku-color-glass-tip` 的 α 现在停在 `.40`（沿革 `.48 → .38 → .28 → .40`，见「气泡的第二轮」），压在近黑内容上约 **`3.7:1`**，**仍低于 WCAG AA 正文下限**（`4.5`）——这是一处有意接受的、尚未收回的缺口，收回办法是把 `tip` 抬到 `.46–.48`。更早一轮里还把五个 `--ku-blur-*` 的半径整体砍半（`22/30/40/48/36` → `10/14/18/22/16px`）——**半径是两个主题共用的，所以暗色的玻璃也一起变清了**，见「同一轮的第二步」。
+> **亮色主题状态**：色阶、语义重绑、缺失/写反的覆盖都已就位 —— 包括 `--ku-color-glass-menu` 与 `--ku-color-mask` 两处此前会继承暗色值、导致亮色下弹层是一块暗板 / 遮罩压过头的**真 bug**；`Monaco` 的代码面则刻意**不跟随**本库主题（代码区底固定 `#131620`，见「代码面」一节）。语义与方向现在在两个主题下都成立。**表面分档与玻璃分档都已重推过一轮**（见下方「亮色的表面分档」与「亮色的玻璃分档」），阴影重量也在同一轮补了亮色值。**已知缺口三处**：① `Markdown` 的代码块仍注入仅暗色的 highlight.js 样式表（亮色下浅底浅字，需第二份样式表）；② 玻璃在**浅色内容**上方的对比度——这是暗色侧的问题，本轮按范围只重标了亮色，见「亮色的玻璃分档」末尾的实测表；③ 亮色 `--ku-color-glass-tip` 的 α 现在停在 `.40`（沿革 `.48 → .38 → .28 → .40`，见「气泡的第二轮」），压在近黑内容上约 **`3.7:1`**，**仍低于 WCAG AA 正文下限**（`4.5`）——这是一处有意接受的、尚未收回的缺口，收回办法是把 `tip` 抬到 `.46–.48`。更早一轮里还把五个 `--ku-blur-*` 的半径整体砍半（`22/30/40/48/36` → `10/14/18/22/16px`）——**半径是两个主题共用的，所以暗色的玻璃也一起变清了**，见「同一轮的第二步」。
 
 ### Token 总览
 
@@ -166,7 +166,7 @@ Knight-UI 通过 CSS 自定义属性（CSS Variables）实现主题系统。在
 | `--ku-color-bg-0` … `--ku-color-bg-3` | 背景阶（0 最深） |
 | `--ku-color-fill-0` … `--ku-color-fill-3` | 交互面填充阶（输入框底、悬停底、滚动条） |
 | `--ku-color-border` | 描边色 |
-| `--ku-color-chat-surface` | **对话区**共用的一档底，由 `.ku-chat-surface` 消费（`AIChatDialogue` / `AIChatInput` / `Chat`）。**不透明**，且刻意站在灰阶阶梯之外：暗色 `#151517`（比 `bg-0` 明显浅，也几乎不带蓝 —— 阶梯第 2 档 `#1a1f2b` 蓝相很重），亮色沿用"比页面深一档"的 `rgb(var(--ku-grey-2))` = `#ecedf0`。**两个主题不同值**，因为"近黑的面"在亮色下没有意义。见下方「对话区的面」 |
+| `--ku-color-chat-surface` | **对话区 / 代码区**共用的一档底，由 `.ku-chat-surface` 消费（`AIChatDialogue` / `AIChatInput` / `Chat` / `CodeEditor` / `CodeHighlight` / `JsonViewer`）。**不透明**，取灰阶**第 1 档**：只声明一次 `rgb(var(--ku-grey-1))`，两个主题各取自己那份（暗 `#131620` / 亮 `#f5f6f8`），两边都恰好比 `bg-0` 亮一档（而 `bg-0` 的落点两个主题不同：暗第 0 档 / 亮第 2 档）。见下方「对话区的面」 |
 | `--ku-color-link` | 链接色（与 `primary` 同档；需要 hover/active 直接用 primary 家族） |
 | `--ku-color-fill-translucent` / `-hover` | 半透明填充（玻璃面上的条纹/悬停底；用不透的 `fill-*` 会把玻璃糊死） |
 | `--ku-color-fill-translucent-strong` | 半透明填充的第二档（0.06）。给**必须读得出来**的静态带子用——目前只有代码三件套的工具条。0.03 那一档的定位是"叠在已有底上的极浅着色"，暗色下够用，亮色下只有约 2/255，工具条会整条消失。值与 `-hover` 相同但**角色不同**，故独立命名（调 hover 的深浅不该顺手把工具条挪走）。 |
@@ -286,16 +286,16 @@ Token（`--ku-color-glass` / `-strong` / `-head`、`--ku-blur-base` … `-xl`）
 >
 > **"颗粒太粗"要调的是 `baseFrequency` 和 `numOctaves`，不是 `opacity`，也不是把颗粒关掉。** 粗细由 `baseFrequency` 定（贴图 140 用户单位 = 140 CSS px，故基本颗粒 = `1/f` CSS px）：现值 `f = 1.0` 是**不越过像素栅格的前提下能取到的最细**，再往上抬只是把细节推到像素以下，1× 下就已走样、缩放时更明显。`numOctaves` 取 `1`（只留基频）：每多一阶频率翻倍、振幅减半，而**每一阶都会在放大时长出新细节**——分形噪声越放大越细是它的本性。这正是**画布场景**暴露的问题：ReactFlow 用 `transform: scale()` 缩放（不是页面缩放那套"按新分辨率重画"），贴图被整体放大，于是 1× 下渲染不出来的高阶细节全冒出来，观感就是"磨砂面的颗粒突然变得很重"。只留基频后，放大只把现有颗粒等比放大，不会凭空长新的。代价是少了泛音阶、对比度降一档——嫌淡先抬 `opacity`，**不要**把 `numOctaves` 加回去。这条治不了"放大后颗粒变大"（那是整张贴图被跟着放大），只能靠抵消缩放。
 
-**哪些面刻意不玻璃化**：`Markdown` 的**面板**是玻璃，但它块内的代码块 `pre` 保持不透明的 `bg-1`——`pre` 是嵌在玻璃面**里面**的一块内嵌面，跟着玻璃化就是玻璃套玻璃（使用前提 3），语法高亮色板也校准在实色暗底上，所以它读成一块实心内嵌面。同理不玻璃化的还有：`Lottie` / `AudioPlayer` / `VideoPlayer` 的"暂无内容"占位框（`fill-0` + 虚线边，是"这里没有东西"的示意而非面板），以及 `VideoPlayer` 的播放舞台与中央播放键（`#000` 与 rgba 黑白蒙层，校准在视频画面上而不是页面上）。
+**哪些面刻意不玻璃化**：`Markdown` 的**面板**是玻璃，但它块内的代码块 `pre` 保持不透明的 `bg-1`——`pre` 是嵌在玻璃面**里面**的一块内嵌面，跟着玻璃化就是玻璃套玻璃（使用前提 3），语法高亮色板也校准在实色暗底上，所以它读成一块实心内嵌面。同理不玻璃化的还有：**代码面三件套**（`CodeEditor` / `CodeHighlight` / `JsonViewer`，改挂 `.ku-chat-surface`，因为 Monaco 把外框盖住了，玻璃挂着只是白付一次 `backdrop-filter`）、`Lottie` / `AudioPlayer` / `VideoPlayer` 的"暂无内容"占位框（`fill-0` + 虚线边，是"这里没有东西"的示意而非面板），以及 `VideoPlayer` 的播放舞台与中央播放键（`#000` 与 rgba 黑白蒙层，校准在视频画面上而不是页面上）。
 
-**代码面（`CodeEditor` / `CodeHighlight` / `JsonViewer`）**：**代码面完全交给 Monaco 自带的 `vs-dark`，本库不注册任何主题、不覆盖任何槽位。** 三个组件的 `theme` prop 默认值就是字符串 `"vs-dark"`，仍可显式传 `"light"` / `"hc-black"`。
+**代码面（`CodeEditor` / `CodeHighlight` / `JsonViewer`）**：**底色是本库灰阶第 1 档 `#131620`，语法配色整套继承 Monaco 自带的 `vs-dark`。** 三个组件挂 `.ku-chat-surface`（不透明面，与对话区同一档，见「对话区的面」），代码区的底由一个只覆盖**一个槽位**的小主题 `ku-code` 提供（`editor.background` → `#131620`，其余全部 `inherit`，见 `tokens/codeTheme.ts`）。`theme` prop 默认值就是这个 `"ku-code"`，仍可显式传 `"vs-dark"` / `"light"` / `"hc-black"` 回到未改底的那一套。
 
-- **代码面不随本库的明暗主题变化。** 这是刻意的：一整套自定义主题（`ku-dark` / `ku-light`，`base` 分别是 `vs-dark` / `vs`）曾经存在过，切换主题时代码配色会**整套从暗翻到亮**——观感上像是编辑器被换掉了，而不是主题在变。所以那两个主题连同 `tokens/monacoTheme.ts` 与 `KU_MONACO_THEME` 导出已一并移除。**`theme` prop 的 `"ku-dark"` / `"ku-light"` 两个取值也随之消失**，改用 Monaco 自带的三个名字；这是本轮唯一一处 JS 侧的公开 API 变动。
-- **代价：亮色主题下代码面是一块深色面板。** 它铺的是 VS 自己的不透明 `#1e1e1e`，不再是外框的 `.ku-glass`（玻璃被它盖住），所以在浅色页面里读成一块稳定的深色代码块——半透明玻璃的观感在这里没有了。这是"代码区在两个主题下长得一样"的直接交换条件。
-- 改造前那次"把 49 个手抄十六进制值逐槽位换成本库色板"的做法已整体撤销，**现在源码里没有任何复制的颜色值**，随之消失的还有那批手抄值与 token 真值之间的漂移（旧值里 `fill-2` 抄的是 `#2f3440`、`bg-2` 抄的是阶梯化之前的 `#14161f`）。**"读已解析颜色"的那一族导出也已一并剪掉**（`readToken` / `readTokens` / `readTriplet` / `rgb` / `hex` / `valueToHex` / `currentTheme` / `contentStep` / `contentColor` / `contentHex`）—— 它们服务的两个消费者都不在了：内容色板靠 `rgb(var(--ku-content-blue))` 这样的字符串拼装就够，Monaco 又交回给自带主题。所以 `tokens/index.ts` 现在只剩 `contentVar` / `contentTintVar` 两个函数，**一个色值都不存**。真要再给某个槽位换回本库色板，得把那套解析（`getComputedStyle` + 展开嵌套 `var()` + 转 `#RRGGBBAA`，约 70 行）重新写一遍；同时 `palette.gen.ts`（色板的 JS 常量镜像，原本给 SSR 兜底）也从生成器里删掉了，所以连"不依赖 document 的兜底三元组"都没有现成来源。
+- **代码面的底固定，不随本库的明暗主题变化。** 一整套会翻面的自定义主题（`ku-dark` / `ku-light`，`base` 分别是 `vs-dark` / `vs`）曾经存在过，切换主题时代码配色会**整套从暗翻到亮**——观感上像是编辑器被换掉了，而不是主题在变。所以那两个主题连同 `tokens/monacoTheme.ts` 与 `KU_MONACO_THEME` 导出已移除。**现在的 `ku-code` 不是它们回来了**：它不注册两套、也不翻面，只换底。**底也不能跟着 `--ku-grey-1` 翻转**——亮色的 `grey-1` 是 `#f5f6f8`（近白），而 `vs-dark` 的语法色（`#9cdcfe` / `#dcdcaa` / `#ce9178`…）是给深底配的浅色，铺在近白底上会大面积糊掉。所以那个底色在 `codeTheme.ts` 里是**写死的字面量**：Monaco 的 `colors` 只吃 `#RRGGBB`，CSS 变量在这里无效——与它 options 里 `fontSize` 只吃数字是同一类限制。
+- **代价：亮色主题下代码面仍是一块深色面板。** 它铺的是固定的 `#131620`，在浅色页面里读成一块稳定的深色代码块。这是"代码区在两个主题下长得一样"的直接交换条件。顺带把外框从 `.ku-glass` 换成了实色面：玻璃在代码面里本来就看不见（下面的 Monaco 铺的是不透明底，把外框整个盖住），挂着只是白付一次 `backdrop-filter`。
+- 改造前那次"把 49 个手抄十六进制值逐槽位换成本库色板"的做法已整体撤销，**现在源码里没有任何复制的颜色值**，随之消失的还有那批手抄值与 token 真值之间的漂移（旧值里 `fill-2` 抄的是 `#2f3440`、`bg-2` 抄的是阶梯化之前的 `#14161f`）。**"读已解析颜色"的那一族导出也已一并剪掉**（`readToken` / `readTokens` / `readTriplet` / `rgb` / `hex` / `valueToHex` / `currentTheme` / `contentStep` / `contentColor` / `contentHex`）—— 它们服务的两个消费者都不在了：内容色板靠 `rgb(var(--ku-content-blue))` 这样的字符串拼装就够，而代码面那边只需要往 `colors` 里写一个 `#RRGGBB` 字面量、根本不读 CSS 值。所以 `tokens/index.ts` 现在只剩 `contentVar` / `contentTintVar` 两个函数，**一个色值都不存**。真要再给别的槽位换回本库色板，得把那套解析（`getComputedStyle` + 展开嵌套 `var()` + 转 `#RRGGBBAA`，约 70 行）重新写一遍；同时 `palette.gen.ts`（色板的 JS 常量镜像，原本给 SSR 兜底）也从生成器里删掉了，所以连"不依赖 document 的兜底三元组"都没有现成来源。
 - **已知缺口：`Markdown` 的代码块仍是仅暗色的 highlight.js 样式表**（见「哪些面刻意不玻璃化」）。它现在与代码面的取向一致了——两者都是暗色高亮压在各自的面板上——但亮色下周围是浅色面板、块内是暗色语法色，仍需第二份样式表才能对齐。
 
-工具条（语言切换 + 格式化/复制）是玻璃面**内部**的带子，按使用前提 3 不再挂玻璃，改用 `--ku-color-fill-translucent-strong` 压一档 + 一条下边框——与 `Chat` 输入区同一套两级半透。**这里必须是 `-strong`（0.06）而不是 `-translucent`（0.03）**：`--ku-grey-9` 随主题翻转，所以 0.03 在暗色下是一条看得见的白膜、在亮色下却只有约 2/255——叠在亮色 30% 的白玻璃上，整条带子消失。而它下方紧挨着的是 Monaco `vs-dark`（固定的不透明 `#1e1e1e`，见上），于是这条带子读起来像「页面从代码块上方漏了出来」，而不像控件的 chrome。加厚到 0.06 后亮色 Δ 约 13/255，与 `.ku-table-th` 那条表头带子重量相当（暗色也随之略明显，属预期：一个声明两个主题）。
+工具条（语言切换 + 格式化/复制）是这块面**内部**的带子，改用 `--ku-color-fill-translucent-strong` 压一档 + 一条下边框——与 `Chat` 输入区同一套两级半透。**这里必须是 `-strong`（0.06）而不是 `-translucent`（0.03）**：两个值都是"中性膜叠在本面底上"，`--ku-grey-9` 随主题翻转，所以在亮色面板底 `#f5f6f8` 上按 `rgba(28, 31, 35, α)` 合成，`.03` 只有约 **6/255**、`.06` 约 **13/255**。（本节早先记过 `.03` 在亮色下"约 2/255"——那是外框还是玻璃时的数：玻璃膜先把带子往页面方向抬，余下的净差才 2/255，症状是"页面从代码块上方漏了出来"。外框换成实色面之后这个抵消没有了，`-strong` 的理由反而是更直接的"6/255 太淡"。）加厚到 `.06` 之后约 13/255，与 `.ku-table-th` 那条表头带子重量相当；暗色是白膜压 `#131620`，同样是约 13/255，两个主题一起成立（一个声明两处）。
 
 三件套的按钮统一是 `Button` 的 `type="primary" size="small"`；注意 `CodeHighlight` **没有工具条**——它全文只有一个绝对定位在右上角、悬浮在代码之上的复制键（且是实底主色，不是白的），背后就是正在滚动的代码，是三者里唯一"背后没有稳定底色"的控件——若它读不清，就是这里需要单独换实底档。
 
@@ -472,7 +472,7 @@ Token（`--ku-color-glass` / `-strong` / `-head`、`--ku-blur-base` … `-xl`）
 | `ku-tag` / `ku-scrollbar` / `ku-float-button` | 过渡、滚动条伪元素、悬浮/展开态、玻璃档 | 内联未涉及这些属性；`ku-float-button` 还独占了三项：**底色**（内联已不再写 `background-color`）、**UA 重置**（`appearance: none` / `border: none` —— 少了下标就会露出 UA 的原生 `outset` 斜角环）、以及**阴影的两个状态**（`:hover` 的 `-lg` 与 `box-shadow` 过渡都写不了内联，组件里那句内联 `boxShadow` 因此是删掉的） |
 | `ku-layout-sider-trigger` | 折叠钮的**几何**（绝对定位骑在侧栏右边缘、24px 圆钮）、**UA 重置**（`appearance: none` 等）与不透明底色 | 这些属性内联没写——钮要压出侧栏边缘，位置只能由类给；UA 重置同理，写不进内联的语义里 |
 | `ku-userguide-card` | UserGuide 引导卡片的**不透明**底（`--ku-color-bg-3`） | 卡片不挂玻璃，底色改由类提供（内联原本就没写 `background-color`） |
-| `ku-chat-surface` | 对话区（`AIChatDialogue` / `AIChatInput` / `Chat`）的**不透明**底（`--ku-color-chat-surface`） | 同上：三个组件都不挂玻璃，底色由类提供。内联只落一个**有条件**的 `backgroundColor`——调用方没传时那一行根本不写，否则内联会把类盖死（见「对话区的面」） |
+| `ku-chat-surface` | 对话区（`AIChatDialogue` / `AIChatInput` / `Chat`）与**代码面三件套**（`CodeEditor` / `CodeHighlight` / `JsonViewer`）共用的**不透明**底（`--ku-color-chat-surface`） | 同上：这些组件都不挂玻璃，底色由类提供。对话区三件套的内联只落一个**有条件**的 `backgroundColor`——调用方没传时那一行根本不写，否则内联会把类盖死（见「对话区的面」）；代码面三件套的内联完全不写 `background-color` |
 | `ku-focus-ring` | 键盘焦点环（见下） | `Button` / `FloatButton` 原先内联 `outline: none` 关掉了 UA 环又不给替代，现已移除该内联——不删内联，挂类也出不来环 |
 | `ku-modal-close` | 关闭按钮的悬停底 | 内联没写 `background-color`（`color` 被内联占了，所以悬停只改底、不改色） |
 | `ku-modal-btn-primary` | 主按钮的悬停 / 按下 | 底色内联恒有值（还要随 `confirmLoading` 变），只有 `filter` 没被内联占住 |
@@ -501,9 +501,15 @@ Token（`--ku-color-glass` / `-strong` / `-head`、`--ku-blur-base` … `-xl`）
 
 ### 对话区的面（`.ku-chat-surface`）
 
-`AIChatDialogue`（会话列表）/ `AIChatInput`（输入框）/ `Chat`（通用对话列表）**共用一条类规则、一个 token**（`--ku-color-chat-surface`，暗 `#151517` / 亮 `#ecedf0`）。三个组件都是同一类面 —— 一块要读字的对话区 —— 底色必须一致，所以是一条规则三个消费者，而不是各写一条。
+`AIChatDialogue`（会话列表）/ `AIChatInput`（输入框）/ `Chat`（通用对话列表），以及**代码面三件套** `CodeEditor` / `CodeHighlight` / `JsonViewer`，**共用一条类规则、一个 token**（`--ku-color-chat-surface`，暗 `#131620` / 亮 `#f5f6f8`）。它们都是同一类面 —— 一块要读字的面 —— 底色必须一致，所以是一条规则多个消费者，而不是各写一条。
 
-**跑回玻璃档是走不通的，这是这块面必须单列的原因。** 膜只能往**自己主题的浅端**加厚：暗色是灰膜压暗底（`grey-3` 比 `grey-2` 亮，α 越大越亮），亮色是白膜压亮底，**两个主题都往"更浮起来"走**。而这里要的是**沉下去**的一面 —— 加深只能在阶梯之外取一个值。取 `#151517` 而不是直接退到 `bg-0`：它比暗色 `bg-0`（`#0c0e12`）明显浅，也**几乎不带蓝** —— 阶梯第 2 档是 `#1a1f2b`，蓝相很重。这是实测挑出来的值，所以给它自己的名字，不去动阶梯本身。
+> 代码面那边有一层错位要知道：Monaco 铺自己的不透明底把外框整个盖住，所以这个类在代码面里**只有工具条那条带子看得见**（`CodeHighlight` 连带子都没有，外框底色完全不出现），而且代码区本身是**固定 `#131620`**、不跟这一档翻主题 —— 所以亮色下是"浅色带子 + 深色代码块"。这是有意的，见「代码面」一节。
+
+**它是灰阶第 1 档，只声明一次。** 写的是 `rgb(var(--ku-grey-1))` 而不分主题各写一个值：`grey-1` 本身随主题翻转（暗 `#131620` / 亮 `#f5f6f8`），一个声明两个主题都成立。这与 `--ku-color-fill-translucent` 是同一种情况（见它那里的说明）。
+
+**但它和 `bg-0` 的关系要说准确，别当成"两个主题同档"。** `bg-0` 的落点两个主题并不相同 —— 暗色是第 **0** 档（`#0c0e12`），亮色是第 **2** 档（`#ecedf0`）；面板取第 1 档，于是两个主题里都**恰好比 `bg-0` 亮一档**。可页面上真正铺的不是 `bg-0`，而是那条底纹渐变（暗 `grey-2→grey-1→grey-0`、亮 `grey-0→…→grey-3`），而第 1 档**本来就是这个渐变里的一档** —— 所以面板不会浮在页面之上，而是读成"从页面里挖出来的一块对话区"。这正是原先那个手挑值 `#151517` 想做的事，区别只在于这次它落在阶梯上：跟着 `--ku-grey-1` 走，两个主题各自成立，不再需要为亮色单独写一条。
+
+**跑回玻璃档是走不通的，这是这块面必须单列的原因。** 半透底会让身后的内容透上来，而对话区是**要读字**的面，底不该参与；膜也帮不上忙 —— 它只能往**自己主题的浅端**加厚（暗色是灰膜压暗底，`grey-3` 比 `grey-2` 亮，α 越大越亮；亮色是白膜压亮底），**两个主题都往"更浮起来"走**，拿它当"加深"的手段方向就是反的。所以这里要的是一个**实色面**，不是一层膜。
 
 **它是唯一一处"不透明的用途面"，与玻璃家族并列、而不是其中一员。** 顺带省掉一次 `backdrop-filter`：不透明的面上那层模糊本来就糊不到东西。视觉上另有一个连带效果值得记：面板从玻璃换成不透明面之后，`AIChatDialogue` 内的 Markdown 更要按平了 —— 它自己的那层玻璃膜现在只会白付一次合成，并在每条助手消息周围画出一个**更亮**的矩形（暗色膜是加亮的），所以 `FLAT_MARKDOWN_STYLE` 里的 `backdropFilter: none` 要留着。
 
@@ -2545,13 +2551,15 @@ import { CodeEditor } from "knight-ui";
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `language` | `string` | — | 语言 |
-| `theme` | `"vs-dark" \| "light" \| "hc-black"` | `"vs-dark"` | Monaco 主题；`vs-dark` 为 VS 自带暗色，**不随本库明暗主题变化**（见「代码面」一节） |
+| `theme` | `"ku-code" \| "vs-dark" \| "light" \| "hc-black"` | `"ku-code"` | Monaco 主题；`ku-code` = `vs-dark` 只换底（`#131620`），**不随本库明暗主题变化**（见「代码面」一节） |
 | `readOnly` | `boolean` | `false` | 只读 |
 | `height / minHeight` | `number` | — | 高度 |
 | `showCopyBtn / showFormatBtn` | `boolean` | `true` | 复制/格式化按钮 |
 | `fontSize` | `number` | — | 字号 |
 | `onChange` | `(value: string) => void` | — | 变更回调 |
 
+> **面**：外框挂 `.ku-chat-surface`（**不透明**底，灰阶第 1 档，与对话区三件套共用一条规则一个 token）。但这个底**只有工具条那条带子看得见** —— 代码区被 Monaco 自己的不透明底盖住了，而那一块是**固定 `#131620`**、不跟主题翻转。展开见「代码面」与「对话区的面」。
+
 ### CodeHighlight 代码高亮
 
 ```tsx
@@ -2569,7 +2577,7 @@ const code = `function hello() {
 |---|---|---|---|
 | `code` | `string` | — | 代码文本 |
 | `language` | `string` | — | 语言 |
-| `theme` | `"vs-dark" \| "light" \| "hc-black"` | `"vs-dark"` | Monaco 主题；`vs-dark` 为 VS 自带暗色，**不随本库明暗主题变化**（见「代码面」一节） |
+| `theme` | `"ku-code" \| "vs-dark" \| "light" \| "hc-black"` | `"ku-code"` | Monaco 主题；`ku-code` = `vs-dark` 只换底（`#131620`），**不随本库明暗主题变化**（见「代码面」一节） |
 | `showLineNumbers` | `boolean` | — | 行号 |
 | `copyable` | `boolean` | `true` | 可复制 |
 
@@ -2588,7 +2596,7 @@ import { JsonViewer } from "knight-ui";
 | `value` | `string \| object` | — | JSON 内容 |
 | `readOnly` | `boolean` | `true` | 只读 |
 | `height` | `number` | `200` | 高度 |
-| `theme` | `"vs-dark" \| "light"` | `"vs-dark"` | Monaco 主题；**不随本库明暗主题变化** |
+| `theme` | `"ku-code" \| "vs-dark" \| "light"` | `"ku-code"` | Monaco 主题；`ku-code` = `vs-dark` 只换底（`#131620`），**不随本库明暗主题变化** |
 | `onChange` | `(value: string) => void` | — | 变更回调 |
 
 ### Chat 聊天
@@ -2634,9 +2642,9 @@ const messages = [
 | `rows` | `number` | `1` | 输入框初始行数（最小高度） |
 | `maxRows` | `number` | `5` | 输入框最多撑到几行，超出后框内滚动 |
 | `showEmoji` | `boolean` | `true` | 输入框左下角的表情按钮与表情面板（仅 `showInput` 时有效） |
-| `backgroundColor` | `string` | — | 面板底色。缺省走 `.ku-chat-surface`（暗 `#151517` / 亮 `#ecedf0`），与 `AIChatDialogue` / `AIChatInput` 同一档 |
+| `backgroundColor` | `string` | — | 面板底色。缺省走 `.ku-chat-surface`（暗 `#131620` / 亮 `#f5f6f8`），与 `AIChatDialogue` / `AIChatInput` 同一档 |
 
-> **面**：面板挂 `.ku-chat-surface`（**不透明**底，与 `AIChatDialogue` / `AIChatInput` 共用一条规则一个 token）。原先挂的是 `.ku-glass`（容器档），改成不透明面的理由是这一档要**沉下去**，而膜只能往自己主题的浅端加厚——见「对话区的面」。
+> **面**：面板挂 `.ku-chat-surface`（**不透明**底，灰阶第 1 档，与 `AIChatDialogue` / `AIChatInput` 共用一条规则一个 token）。原先挂的是 `.ku-glass`（容器档），改成不透明面是因为对话区要读字、底不该参与，而膜只能往自己主题的浅端加厚（方向与"加深"相反）——见「对话区的面」。
 >
 > 传了 `backgroundColor` 它就落成**内联**、盖过类；不传时那一行根本不写（写的是 `...(backgroundColor ? { backgroundColor } : {})`）。**不能无条件写死一个内联默认值**——内联优先级高于类，那样调 `--ku-color-chat-surface` 会看起来"改了没生效"。
 >
@@ -2830,9 +2838,9 @@ import { AIChatInput } from "knight-ui";
 | `maxRows` | `number` | `4` | 最大行数，超出后框内竖直滚动 |
 | `attachments` | `Attachment[]` | — | 附件列表 |
 | `onSend` | `(value, attachments) => void` | — | 发送回调 |
-| `backgroundColor` | `string` | — | 输入框底色。缺省走 `.ku-chat-surface`（暗 `#151517` / 亮 `#ecedf0`）。**要与 `AIChatDialogue` 一起改** |
+| `backgroundColor` | `string` | — | 输入框底色。缺省走 `.ku-chat-surface`（暗 `#131620` / 亮 `#f5f6f8`）。**要与 `AIChatDialogue` 一起改** |
 
-> **面**：面板挂 `.ku-chat-surface`（**不透明**底，暗 `#151517` / 亮 `#ecedf0`），与 `AIChatDialogue` / `Chat` **共用这一条类规则**。它是**同一个对话区的下半块**——两块底色必须一致，只改一边会在中间露出一条分界线，所以它跟着对话面板走，而不是像别的输入类控件那样走 `fill-0`（见 `input/Input.tsx`）。它仍是一个**面板**——自带内边距，里面装着 textarea + 附件条 + 发送键——不是 `Input` 那种单字段控件，那个分野没变。内部 textarea 本来就是透明的，附件标签走不透明的 `fill-1`（在这块面上是**更亮**的一档，读起来是一枚筹码）。
+> **面**：面板挂 `.ku-chat-surface`（**不透明**底，暗 `#131620` / 亮 `#f5f6f8`），与 `AIChatDialogue` / `Chat` **共用这一条类规则**。它是**同一个对话区的下半块**——两块底色必须一致，只改一边会在中间露出一条分界线，所以它跟着对话面板走，而不是像别的输入类控件那样走 `fill-0`（见 `input/Input.tsx`）。它仍是一个**面板**——自带内边距，里面装着 textarea + 附件条 + 发送键——不是 `Input` 那种单字段控件，那个分野没变。内部 textarea 本来就是透明的，附件标签走不透明的 `fill-1`（在这块面上是**更亮**的一档，读起来是一枚筹码）。
 >
 > **`backgroundColor` 只在传了的时候落内联**（`...(backgroundColor ? { backgroundColor } : {})`）。**不能无条件写内联 `backgroundColor`**——内联优先级高于类，写死就把 `.ku-chat-surface` 那一档盖死了。要与 `AIChatDialogue` 一起改，理由同上一段。展开见「对话区的面」。
 >
@@ -2876,7 +2884,7 @@ const messages = [
 | `onCopy` | `(msg) => void` | — | 复制回调(复制按钮仅在传入时出现) |
 | `copyTip` | `React.ReactNode \| false` | `"已复制"` | 复制后的 Toast 文案；传 `false` 关闭提示 |
 | `onRetry` | `(msg, index) => void` | — | 重试回调 |
-| `backgroundColor` | `string` | — | 面板底色。缺省走 `.ku-chat-surface`（暗 `#151517` / 亮 `#ecedf0`）。**要与 `AIChatInput` 一起改** —— 两块是同一对话区的上下两半 |
+| `backgroundColor` | `string` | — | 面板底色。缺省走 `.ku-chat-surface`（暗 `#131620` / 亮 `#f5f6f8`）。**要与 `AIChatInput` 一起改** —— 两块是同一对话区的上下两半 |
 
 > **AIMessage 思考内容支持（assistant 专用）**：`thinkingContent?: React.ReactNode` 思考/推理内容（Markdown 字符串或节点），展示为消息上方可折叠的灰色思考块；`thinkingTokens?: number` 真实 token 数（缺省按 ~3.5 字符/token 估算，展示时**千位进制、保留一位小数**：`1200 → "1.2 k"`，不足 `1000` 原样显示，再拼上 `" token"`，即渲染成 `12.3 k token`。**不做单位换算**（不出现 `万` / `M`）——这一列是同一量级的横向对比，统一乘数比"换个单位"更好读）；`thinkingDurationMs?: number` 思考耗时(ms)，完整消息可传，流式思考期间由组件自动计时无需传入。
 > 流式阶段约定：仅思考时消息为 `{ role:"assistant", thinkingContent: 增量, status:"streaming" }`（正文留空、与 content 互斥增长）；结束后替换为带 `content`（与可选 `thinkingDurationMs`）的完整消息。
@@ -2892,7 +2900,7 @@ const messages = [
 > **复制反馈**：点"复制"会在调用 `onCopy` 之后弹 `Toast.success("已复制")`（文案用 `copyTip` 改，传 `copyTip={false}` 关掉，反馈交回调用方）。
 > **组件自己不碰剪贴板**——`content` 是 `React.ReactNode`，可能是节点而不是文本，"该拷什么"只有调用方说得清，所以写入始终发生在 `onCopy` 里（见上方示例）。也正因如此，这个提示代表的是"复制动作已发出"，**不是组件核实过的结果**：`onCopy` 里若是异步写入且被浏览器拒绝，组件无从得知。要拿到真结果，就得把组件改成自己写剪贴板，并把 `content` 收窄成 `string`。
 
-> **面**：面板挂 `.ku-chat-surface`（**不透明**底，暗 `#151517` / 亮 `#ecedf0`），与 `AIChatInput` / `Chat` 共用一条规则一个 token。原先挂的是 `.ku-glass`（容器档）；改成不透明面是因为这一档要**沉下去**，而膜只能往自己主题的浅端加厚——见「对话区的面」。
+> **面**：面板挂 `.ku-chat-surface`（**不透明**底，暗 `#131620` / 亮 `#f5f6f8`），与 `AIChatInput` / `Chat` 共用一条规则一个 token。原先挂的是 `.ku-glass`（容器档）；改成不透明面是因为对话区要读字、底不该参与，而膜只能往自己主题的浅端加厚（方向与"加深"相反）——见「对话区的面」。
 >
 > `backgroundColor` 传了才落**内联**、盖过类；不传时那一行根本不写。**不能无条件写一个内联默认值**——内联优先级高于类，那样调 `--ku-color-chat-surface` 会看起来"改了没生效"。要改就与 `AIChatInput` **一起改**：两块是同一对话区的上下两半，只改一边会在中间露出一条分界线。
 >

package/component/ai/AIChatDialogue.d.ts

@@ -98,8 +98,8 @@ export interface AIChatDialogueProps extends UIProps {
     /** 思考正文最大高度(px)，超出后内部滚动 @default 320 */
     thinkingBodyMaxHeight?: number;
     emptyContent?: React.ReactNode;
-    /** 面板底色。缺省走 .ku-chat-surface(暗 #151517 / 亮 #ecedf0)。要与 AIChatInput 一起改 —— 两块是同一
-        对话区的上下两半, 只改一边会在中间露出一条分界线。 */
+    /** 面板底色。缺省走 .ku-chat-surface(暗 #131620 / 亮 #f5f6f8, 即灰阶第 1 档)。要与 AIChatInput
+        一起改 —— 两块是同一对话区的上下两半, 只改一边会在中间露出一条分界线。 */
     backgroundColor?: string;
     onCopy?: (msg: AIMessage) => void;
     /** 点击复制后弹出的 Toast 文案；传 false 关闭提示，反馈由调用方自理 @default "已复制" */

package/component/ai/AIChatInput.d.ts

@@ -30,8 +30,8 @@ export interface AIChatInputProps extends UIProps {
     onChange?: (value: string) => void;
     onSend?: (value: string, attachments: Attachment[]) => void;
     placeholder?: string;
-    /** 输入框底色。缺省走 .ku-chat-surface(暗 #151517 / 亮 #ecedf0)。要与 AIChatDialogue 一起改 —— 两块是
-        同一对话区的上下两半, 只改一边会在中间露出一条分界线。 */
+    /** 输入框底色。缺省走 .ku-chat-surface(暗 #131620 / 亮 #f5f6f8, 即灰阶第 1 档)。要与 AIChatDialogue
+        一起改 —— 两块是同一对话区的上下两半, 只改一边会在中间露出一条分界线。 */
     backgroundColor?: string;
     disabled?: boolean;
     loading?: boolean;

package/component/plus/Chat.d.ts

@@ -49,7 +49,8 @@ export interface ChatProps extends UIProps {
     onRetry?: (msg: ChatMessage, index: number) => void;
     loading?: boolean;
     emptyContent?: React.ReactNode;
-    /** 面板底色。缺省走 .ku-chat-surface(暗 #151517 / 亮 #ecedf0), 与 AIChatDialogue / AIChatInput 同一档。 */
+    /** 面板底色。缺省走 .ku-chat-surface(暗 #131620 / 亮 #f5f6f8, 即灰阶第 1 档), 与 AIChatDialogue /
+        AIChatInput 同一档。 */
     backgroundColor?: string;
     showInput?: boolean;
     placeholder?: string;

package/component/plus/CodeEditor.d.ts

@@ -26,7 +26,7 @@ export declare class CodeEditor extends AbstractUI<CodeEditorProps, CodeEditorSt
     getEditor(): any;
     /** Monaco 挂载回调 */
     private OnEditorMount;
-    /** 挂载前配置 Monaco 环境，稳定诊断/IntelliSense */
+    /** 挂载前配置 Monaco 环境: 先登记代码面主题, 再稳定诊断/IntelliSense */
     private beforeMount;
     /** 切换语言 — 更新内部状态 + 回调 + 直接操作 Monaco 模型 */
     private handleLanguageChange;
@@ -57,8 +57,9 @@ export interface CodeEditorProps extends UIProps {
     width?: number | string;
     /** 编辑器最小宽度(px) */
     minWidth?: number;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light" | "hc-black";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light" | "hc-black";
     /** 只读 @default false */
     readOnly?: boolean;
     /** 显示缩略图 @default false */

package/component/plus/CodeHighlight.d.ts

@@ -21,8 +21,9 @@ export declare class CodeHighlight extends AbstractUI<CodeHighlightProps, CodeHi
 export interface CodeHighlightProps extends UIProps {
     code?: string;
     language?: string;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light" | "hc-black";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light" | "hc-black";
     showLineNumbers?: boolean;
     height?: number | string;
     maxHeight?: number | string;

package/component/plus/JsonViewer.d.ts

@@ -26,8 +26,9 @@ export interface JsonViewerProps extends UIProps {
     readOnly?: boolean;
     onChange?: (value: string) => void;
     height?: number;
-    /** Monaco 主题 @default "vs-dark" —— 代码面按 VS Code 自己的暗色一套, **不随本库明暗主题变化** */
-    theme?: "vs-dark" | "light";
+    /** Monaco 主题 @default "ku-code" —— `vs-dark` 原样继承, 只把底换成灰阶第 1 档 #131620(见
+        tokens/codeTheme.ts)。**不随本库明暗主题变化**: 两个主题下代码面都是这一块深底。 */
+    theme?: "ku-code" | "vs-dark" | "light";
 }
 interface JsonViewerState extends UIState {
     lastExternalValue: string;

package/component/tokens/codeTheme.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 代码面的 Monaco 主题 —— 只改一件事: 把 `vs-dark` 的底(#1e1e1e)换成本库灰阶第 1 档 #131620,
+ * 其余**全部继承 vs-dark**(`inherit: true` + 空 rules)。
+ *
+ * 为什么只改底: 语法配色是一整套(几十个槽位), 换任何一个都得重新标定一遍; 而代码面与页面脱节
+ * 的地方只有"底"这一处 —— #1e1e1e 是中性深灰, 页面是带蓝的深灰, 两块并排就是两种黑。底对上之后,
+ * 剩下的中性灰面(建议列表 / 悬停气泡 / 缩略图)面积小, 且都要用户主动触发才出现, 不在第一眼里。
+ *
+ * **底色是固定的 #131620, 不跟 `--ku-grey-1` 随主题翻转。** 亮色的 grey-1 是 #f5f6f8(近白),
+ * 而 vs-dark 的语法色(#9cdcfe / #dcdcaa / #ce9178…)是给深底配的浅色 —— 铺在近白底上会大面积糊掉。
+ * 所以代码面在**两个主题下都是这一块深底**, 与「代码面不随主题变化」是同一条取向(见 README「代码面」
+ * 一节)。也正因为如此这里必须写死字面量: Monaco 的 colors 只吃 #RRGGBB, CSS 变量在这里无效 ——
+ * 和它 options 里 fontSize 只吃数字是同一类限制。
+ */
+export declare const KU_CODE_THEME = "ku-code";
+/**
+ * 注册代码面主题。
+ *
+ * **必须在 `beforeMount` 里调用**: @monaco-editor/react 的顺序是 beforeMount → editor.create →
+ * setTheme, 赶在 create 之前登记, 那个名字才已经存在。
+ *
+ * 每次挂载都重新 define、不加"只注册一次"的模块开关: defineTheme 只是登记一份定义(不应用),
+ * 开销可忽略; 而开关一旦因为 Monaco 实例被重建或重新加载而失真, 表现是"主题悄悄不生效",
+ * 比多登记一次难查得多。
+ */
+export declare function ensureKuCodeTheme(monaco: any): void;

package/component/tokens/index.d.ts

@@ -14,8 +14,9 @@
  * `rgb` / `hex` / `valueToHex` / `contentStep` / `contentColor` / `contentHex`。它们服务的两个
  * 消费者现在都不存在了 ——
  *   ① 内容色板不需要读色: 字符串拼装就够了(这正是 contentVar 存在的理由);
- *   ② Monaco 那一版已整体撤掉: 代码面现在完全用 VS 自带的 `vs-dark`, 不注册自定义主题,
- *      于是 `valueToHex`(为"只吃 #RRGGBB 的注册表"而写)也一并没了用处。
+ *   ② Monaco 那一版已整体撤掉, 代码面现在用 VS 自带的 `vs-dark`, 只换底(见 ./codeTheme.ts)。
+ *      它是**写死一个字面量**进 Monaco 的注册表, 不需要把 CSS 值读出来 —— 所以
+ *      `valueToHex`(为"读了再转 #RRGGBB"而写)依然没有用处。
  * 所以按"整族剪"处理, 一个不留 —— 养一批无人调用的导出, 比真要用时重写它们(~70 行:
  * `getComputedStyle` + 展开嵌套 `var()` + 十六进制转换)贵得多。
  *