# 设置指南

[返回首页](../README.md) · [兼容性与权限](compatibility.md)

> 本文对应当前工作区 0.8.3 实现；实际发布状态以 npm 与 GitHub Release 为准，不将 main 推送等同于发布。变更见 [更新记录](../CHANGELOG.md)。

## 打开设置

在支持设置扩展的 DSH 宿主中，进入 **设置 → Code Pill**。
页面分为「代码外观」和「字体」两个 Tab，共用标题与内容宽度。代码外观包含预设、实时预览、显示与排版、配置管理；自定义代码颜色与动作行颜色按需展开。切换 Tab 不丢失外观草稿。字体即时应用，不需要点击外观 Tab 的保存按钮。
找不到入口时先核对安装包是不是当前 main 构建，以及宿主是否提供设置 slot 和 UI 模块；没有设置入口不意味着行内渲染也一定失败。

## 先选预设

| 预设 | ID | 基调 |
| --- | --- | --- |
| 琥珀经典 | `amber` | 延续默认琥珀色 |
| 柔和阅读 | `readable` | 中性石板色 |
| 冷调清晰 | `cool` | 青蓝色 |
| 编辑器经典 | `editor` | 熟悉的编辑器语法色 |
| 高对比 | `contrast` | 更强的明暗对比 |
| 素雅简约 | `minimal` | 中性灰默认文字与克制的语法色 |

每套分别提供 light/dark 色板，卡片直接显示当前主题下的胶囊示例。**选择预设会替换色板、语法／标记／代码块外观与排版草稿**；聊天文件路径、句子级降级、思考彩虹、动作行着色、显示平滑和动作行颜色保持不变。保存之前仍可通过“取消更改”返回已保存配置。

「素雅简约」(minimal) 同时替换几何默认值：圆角 3px、水平内边距 0.2em、底色强度 0.025（其余预设为 4px、0.25em、0.06）；语法着色保持开启、文件标记保持语言文字、字号比例保持 0.94×，不隐藏任何功能。

色板名称不代表护眼、医疗或所有环境的可读性保证。实际背景、字号与个人视觉需求仍应一起考虑。

## 自定义颜色

“浅色／深色”按钮选择预设卡片、实时预览和自定义颜色正在使用的主题，不强制切换真实聊天主题。运行时颜色跟随宿主主题。展开「自定义代码颜色」后可调整九项颜色。

| 角色 | 用途 |
| --- | --- |
| 默认文字 | 标识符、路径、文件名及未独立着色的部分 |
| 控制流 | if、return 等关键词 |
| 声明与类型 | const、class 等声明关键词 |
| 字符串 | 带引号的字符串 |
| 注释 | 启发式识别出的代码注释 |
| 数字 | 数字字面量 |
| 胶囊底色 | 与底色强度一起合成背景 |
| 徽章底色／文字 | 文件语言标签的实色背景与文字 |

颜色选择器立即更新草稿。十六进制输入需完整 `#RRGGBB`，失焦时校验；不合法时恢复原值并提示。
函数调用、类型名、常量与属性默认并入默认文字色，并非九种独立语法色。

预览使用白色／`#1e1e1e` 背景，并显示当前颜色的文字对比度结果。低于 4.5:1 会提醒，**仍允许保存，不会自动替你改颜色**。这是当前预览条件下的检查，不是任意宿主主题的全面审计。

## 文件标记与排版

| 选项 | 默认 | 可选范围 |
| --- | --- | --- |
| 行内语法着色 | 开启 | 开启／关闭；关闭仍保留胶囊与文件标记 |
| 聊天文件路径 | 开启 | 开启／关闭；关闭后聊天中的宿主路径装饰全部撤销 |
| 句子级降级 | 开启 | 开启／关闭；关闭后整句被并进行内代码的消息按完整代码渲染 |
| 思考文字彩虹刷入 | 关闭 | 开启／关闭；开启后流式思考里新出现的文字短暂呈彩虹色，再落回正常文字色 |
| 折叠动作行着色 | 关闭 | 开启／关闭；开启后折叠的动作行按类别给图标和动作名上色，失败与中断更醒目，并突出完成状态词 |
| 显示平滑 | 关闭 | 开启／关闭；开启后生成中的回复逐帧连续揭示，并在原本跟随底部时平稳下卷 |
| 文件标记 | 语言文字 | 关闭／语言文字／小图标／图标＋文字 |
| 字号比例 | 0.94× | 0.8–1.1×，相对正文 |
| 圆角 | 4px | 0–10px |
| 水平内边距 | 0.25em | 0–0.6em |
| 底色强度 | 0.06 | 0–0.2 |
| 代码块颜色 | 保留宿主 | 保留宿主／使用当前色板 |

文件标记只作用于检测出的文件名。图标＋文字模式在文件名前放单色图标、文件名后放语言缩写；普通表达式不加文件图标。
含空白的路径或不明确的字符串可能不显示标记，这是保守识别，不是文件访问失败。

“聊天文件路径”统一工具摘要、正文文件引用、搜索结果文件名、读取卡片标题及聊天内路径标签的胶囊外观。保留点击、行号跳转和宿主截断结构；读取标题不重复语言标签，已有宿主图标的引用不叠加图标。明确的路径容器可显示含空格、未知扩展名和长路径，但不保证都有语言徽章。URL、命令描述、匹配正文、行号、文件大小与附件卡片不受影响。配置键沿用 `toolPath`。路径保持单色，终端与 diff 仍由宿主负责。

“句子级降级”（配置键 `sentenceFallback`，默认开启）处理个别消息里宿主 Markdown 解析把成对反引号连同周围正文并进同一个行内代码的形态：识别出「成对反引号包着短片段 + 足够长的散文尾巴」后，把文字恢复为正文颜色与正文字体，不再做语法着色与文件徽章；胶囊底色保留，换行折叠时表现为行块底色。宿主消息的子节点不会被修改，识别不出时保持原样。作者用双反引号定界符书写的合法代码无法与该形态逐字符区分，会被一并降级，只影响颜色与字体；关闭开关即回到完整代码渲染。

“思考文字彩虹刷入”（基础功能自 0.6.0 起提供）只作用于正在流式输出的思考（展开正文与折叠预览）。当前源码改为轻量短尾：新单词出现时获得一个固定初始颜色，保持 160ms 后淡回宿主正文色，约 400ms 后解除高亮；同一单词不轮换色相，不同新词的初始色依次变化。正文和预览共享最多 16 个活跃词，高速输出超过窗口时最旧单词立即恢复默认色，不排队等待播放；批量文本只处理尾部 128 字符和最多 48 字符的分词上下文。历史文字不补播，装饰动画不改变宿主文本追加的调度。打开设置时已有的思考内容、思考结束后的整体重渲染、代码块都不会播放；系统开启“减少动态效果”时自动停用。这是一个纯装饰效果，不承载信息，也不属于预设色板的对比度审计范围。选择预设不会改变这个开关。

“显示平滑”（配置键 `displaySmooth`，默认关闭）把回复的网络分块放入显示队列，再按帧逐步揭示，避免一段文字突然整块出现。滚动跟随以宿主为主：宿主正在跟随回复尾部时由宿主定位，插件不写入滚动位置；宿主不跟随时插件才以每帧最多 8px 的位移补齐；向上阅读会停止跟随，回到底部可恢复。新回复和之后的追加内容参与平滑，已结束的历史消息不播放；回合结束后剩余文字会快速收尾。进入或切回会话时，运行中回复已有内容视为已读，不重播。代码块、引用、列表、表格等块级结构不会先于其中的文字出现：块内还没有文字时格式暂不可见，出现第一个字符时与文字同帧可见。宿主在流式中重排 Markdown 结构（内联元素成形、更换块类型）会换掉原来的文本节点，这些节点上已经显示过的文字不会重播，只有真正新增的部分继续揭示。系统开启“减少动态效果”时自动停用。开启期间，可见文字可能短暂落后于宿主已收到的内容；关闭开关或卸载插件会立即恢复完整文字。选择预设不会改变这个开关。

“折叠动作行着色”（基础功能自 0.6.0 起提供）让一长串折叠行能快速分辨。当前源码将图标与动作名分为 12 类；描述、参数、展开正文仍是宿主原色，路径仍由路径胶囊管线负责。失败的行图标和动作名换红，被中断的换琥珀，优先于类别色；悬停时动作名回到满色。

| 类别 | 覆盖的动作／工具 |
| --- | --- |
| 读取 | 读取文件、读取图片、网页读取、Cordis 检查、工作区依赖信息 |
| 搜索 | 查找文件、搜索文件内容、网页搜索、LSP 定义／引用查询 |
| 写入／编辑／交付 | 写入、编辑、交付文件 |
| 命令与终端 | Bash、PowerShell、代码执行、后台任务列表／输出／结束、终端操作、Cordis 运行／停止／移除 |
| 思考 | 思考行 |
| 会话与事件 | 搜索／追踪会话、读取／搜索／追踪事件 |
| 代理与编排 | 委派／继续子代理、代理列表、模型列表、发送消息、中断／等待代理、队友、workflow／ralph |
| 任务与目标 | 更新任务清单、创建／读取／更新目标、团队任务管理 |
| 定时与提醒 | 创建／列出／更新／删除提醒 |
| 技能 | 加载技能，包括其独立卡片头部的准备、运行、完成状态 |
| 提问与确认 | 提问、计划确认 |
| 工具与上下文 | 工具发现／加载、MCP 与其他插件调用、Cordis 定义、聊天里的“已添加工具”等上下文提示 |

分类以宿主的 `data-variant` 与工具标识 `data-tool` 为依据，不根据翻译后的标题或摘要猜类别；未知工具保留明确的“工具与上下文”兜底色。技能与 Cordis 的独立头部另有结构适配。上下文提示只在宿主聊天 `context` 节点的折叠头部着色，不扫描普通消息文字，也不改动宿主子节点。

摘要末尾的完成状态词（如“已完成”“已交付”）会单独染成绿色，中断词染琥珀，失败词染红。只在任务、定时、目标、交付文件等由宿主生成摘要的行里识别，并且要求行的状态与词义一致；英文状态词必须单独成词（“incomplete”不染）；中文只认“已完成／已交付”这类带“已”的成功词和“失败／错误／已中断”等词，裸的“任务完成”不染；“2/4 已完成”这样进度未满的、命令描述和文件路径也都不染。颜色只是辅助线索，图标形状和文字才是主要信息；内置色值对白色与 #1e1e1e 页面的对比度 ≥ 4.5:1，但整体着色不属于预设色板审计。选择预设不会改变这个开关。

行着色的 15 个颜色可以自定义：展开「自定义动作行颜色」后，按当前选中的浅色／深色分别用取色器或完整 `#RRGGBB` 修改上述 12 个类别色，以及完成状态、中断／警示、失败三个状态色。旧版八项颜色配置会保留原值，只为新增类别补齐默认值。实时预览展示五个代表类别与三个状态示例；着色关闭时保持宿主灰阶，开启后反映草稿颜色。对比度低于 4.5:1 时会提醒，但仍可保存。「恢复行颜色默认」把浅色和深色的行颜色一起放回内置色板（进入草稿，保存后应用）；选择预设、导入导出都会保留这些颜色。未自定义的项始终使用内置色板。

“使用当前色板”生成 Shiki CSS 变量，不提供新的语言解析器。代码块预览只是示意，真实宿主完整渲染应现场核验。

## 草稿、保存与恢复

1. 改动先进入草稿，预览更新，聊天不变。
2. **保存并应用**：写入本浏览器设置并更新聊天。操作栏吸附在设置滚动区域顶部；滚到下方开关、配置导入或表单末尾都不必回到页面开头，窄屏会自动换行。
3. **取消更改**：恢复最近的已保存配置。
4. **恢复默认**：默认配置进入草稿，仍需保存才应用。
5. 关闭设置页：丢弃尚未保存的草稿。

保存失败时保留草稿并显示错误，不应用到聊天。浏览器隐私策略、网站存储禁用或存储配额可能造成失败。

## 导入与导出

展开“导入／导出配置”。

- **导出草稿**：把当前配置 JSON 放入文本框，选中复制；不导出聊天记录或凭据。
- **导入草稿**：粘贴 JSON 后点击导入，校验成功才进入草稿；仍需保存才应用。
- 配置格式要求 `version: 1`，只接受已知字段、合法枚举、范围内数值与六位十六进制颜色。
- 不接受 CSS、脚本、远程字体或图标地址；非法导入不会替换已保存设置。

完整数据契约与验证函数见 [settings-core.cjs](../src/settings-core.cjs)。不要向外观配置填入密钥或其他敏感信息。

## 字体 Tab

- **全局字体 / 等宽字体**：输入逗号分隔的字体栈，留空跟随宿主。没有固定字体候选或组合按钮，不假定客户端已安装任何字体；已有字体配置保持不变。
- **读取 / 刷新本机字体**：用户主动点击后请求 Local Font Access 权限。候选只来自浏览器本次提供的字体（不保证系统全量），字体文件的 cmap、maxp、hhea、hmtx 数据表仅在本页解析，不上传、不下载、不分发。名单只保留在当前插件会话内，不新增永久保存，也不使用旧名单缓存；可用「清除已读取名单」撤销本次候选，不影响已选字体配置。浏览器撤权不会自动清空历史会话名单，可主动清除或刷新；历史旧缓存不自动删除。
- **分类与搜索**：支持全部、英文 / 拉丁字母、中文 / 汉字样本、ASCII 等宽、未完整识别，并可按名称搜索。分类依据字符映射与字宽，不依据字体名。英文检查大小写字母和数字；中文检查固定常用简繁汉字样本，不代表覆盖全部中文或某国语言字形；等宽检查全部 95 个可打印 ASCII（含空格、标点），不保证汉字双宽、可变字体实例或浏览器实际排版网格。
- **识别边界**：同一字体可命中多个筛选条件。每个族的所有已枚举字面均满足才确认；字面能力不同、文件读取失败或不支持的格式归入未完整识别，仍可在全部 / 未完整识别中选择。拒绝、策略限制或 API 不支持时可继续手动输入；刷新失败会清空过时候选，不清空已选字体栈。
- **界面缩放**：100 / 110 / 120 / 130 / 140%，放大整个页面布局；与浏览器缩放并非完全相同，弹窗和布局需按实际宿主核验。
- **会话字号**：10–22px，留空使用宿主设置。
- **高级**：35 个角色、字号和 Markdown 槽位，高级覆盖优先于全局；每个槽位默认只显示字体栈，点击「选择字体」才展开分类与搜索选择器。另可添加选择器 → 字体规则。未知变量与无效选择器不会生成覆盖 CSS。
- **导出 / 固化**：查看及复制当前字体 CSS；代码外观 JSON 导入导出不包含字体配置。

字体改动即时应用并独立保存到 `dsh-code-pill.fonts.v1`；存储失败时本页仍生效，但明确提示未持久化。首次没有新配置时读取 `dsh-font-lab/v1`，不删除或改写原配置。旧插件仍开启会产生样式竞争，建议启用合并版本前自行停用旧插件。

总开关关闭会撤销字体、字号与缩放覆盖；「清除全部字体设置」清空字体、字号、缩放、高级槽位和自定义规则，不改动代码外观。旧 `dsh-font-lab/fonts` 名单不再读取或改写。切换 Tab 会取消未完成的读取，迟到结果不会写回；高级面板与完整字体选择器均按需挂载。

## 保存在哪里

配置 key 为 `dsh-code-pill.settings.v1`，存放在当前浏览器、当前 origin 的 localStorage。

- 不保存到主机 Profile，不自动跨设备同步。
- 协议、主机或端口变化后是另一份存储，例如两个不同端口的 DSH 页面。
- 清除网站数据会删除配置。
- 同 origin 的其他页面可在保存后接收更新；正在编辑的草稿不被强行覆盖。
- 同 origin 的其他脚本可能读取 localStorage，不能把它当作加密秘密库。

## 常见问题

**找不到设置页？** 使用当前 main 的验证包，并检查宿主能力。npm 已发布版本可能还没有新增设置。缺少 UI 模块时不会加载额外 React 副本作为补丁。

**改了颜色，聊天没有变化？** 先点击保存。预览主题切换只选择编辑哪套色板；真实聊天仍跟随宿主主题。

**某些代码没有分色？** 路径、术语和普通标识符默认 plain；不明确的语法保守处理。缺少 Highlight API 或 code 不是单 Text 节点时也会降级。

**文件链接没有胶囊或图标？** 插件主动避开链接、按钮与代码块，避免破坏宿主自己的交互和渲染。

**另一台设备没有同步？** 当前没有云同步。通过导出／导入转移配置即可。