[xiaoyumuxi]

关联 Issue / Linked issue

• 没有单独的 Issue。起因是用户反馈：插件设置页“中英文没弄全”“配置看不懂”。本 PR 只处理页面密度，插件文案的翻译另做（见“不在本 PR 范围内”）。

PR 类型 / Type

• feat：新功能或用户可见的改进
• fix：缺陷修复
• docs：文档、Agent Note、Skill 等规则文件
• release：稳定版发布准备

改动说明 / What changes

背景 / Why

已安装插件的“设置”标签页里，同一份信息说了好几遍：

• 布尔设置的标题行下面，开关旁又写了一遍标题；
• 每一项下面常驻“当前为继承值，此范围未存储覆盖值。”；
• 范围选择旁常驻一行“切换范围前，请保存或重新加载草稿。”，却没讲“全局”和“项目”有什么区别。

页面因此又长又难懂。按“难懂的配置用 ⓘ、常驻文字只留错误、警告和保存结果”的界面约定精简，标题一行、控件一行的布局不变。

改动 / Changes

• 开关不重复标题（plugin_settings_view.go）：布尔设置的 ui.Switch 不再带说明文字，只用 .Label(declaration.Title) 给辅助技术一个名称；标题只在上面的标题行出现一次。

• 去掉常驻的继承说明：删掉每行下面的“当前为继承值……”和对应词条 desktop.pluginSettings.inherited。

  • 取舍：每行不再提示这个范围里有没有存覆盖值。要回到继承值，仍是点该行的“重置”。“重置”在没有覆盖值时也可用，因为它还负责撤销草稿里的修改，所以没有把它绑到覆盖状态上。
  • “此设置仅可在全局范围修改”（globalOnly）和“已存储的值无效”（invalidStored）是状态和错误，保留。

• 范围说明收进 ⓘ：范围选择旁的常驻文字换成 ⓘ（w.infoButton，悬停显示提示，点击弹出说明）。

  • 词条 desktop.pluginSettings.scopeHelp 改写为先讲两个范围的区别，再提醒切换前保存或重新加载。
  • 中文：“全局设置对所有项目生效；项目设置只对当前项目生效，存了值的项会覆盖全局值。切换范围前，请保存或重新加载草稿。”
  • 中英文都已补齐，并重新生成 shared.generated.go。

• 测试（plugin_settings_view_test.go）：在已有的表单测试里加了以下检查：

  • 布尔行的标题只画一次，且同名的可点击对象是开关（RoleSwitch）；
  • 页面上没有“no override is stored”；
  • 范围说明不在页面上常驻，只能通过 ⓘ 找到。

  恢复开关的说明文字、恢复继承说明、恢复常驻范围说明，这三种情况下测试都会失败（本地反向验证过）。

• 截图（plugin_settings_visual_test.go、docs/assets/plugin-settings-form/）：新增无头截图场景 TestVisualPluginSettingsForm。

  • 由真实的 Core 校验清单。
  • 五个设置仿照一个语言插件：一个工具链文件、三个开关、一个选项；只是测试数据。
  • 深色中文和浅色英文各一张，附 README 和复验命令。

• 功能矩阵：在 declarative-plugin-settings 的说明末尾补一句本次行为和测试名，状态保持 partial/pending。

截图（深色中文 / 浅色英文）：

深色中文	浅色英文

不在本 PR 范围内 / Out of scope

• 插件文案的翻译：截图里设置的标题、说明和选项名还是英文。
  • 原因：这些是插件 plugin.json 里的文字，宿主的 i18n 管不到，插件现在也没有地方提供中文。
  • 计划：插件包带 l10n/<语言>.json，按设置 ID 给出标题、说明和选项名；Core 按界面语言挑选，缺的条目回退到 plugin.json 的原文。归入 API-37，是 pluginAPIVersion 0 内的补充。
  • 拆成三步：Core 契约和实现、桌面端升级固定版本并把界面语言交给 Core、Go 插件补中文。
• 同一分组里的设置按 ID 字母序排列，不按声明顺序：Core 的 validate_settings（plugin-manifest/src/settings.rs）有意按 ID 排序。是否改成声明顺序、或加 order 字段，是契约层面的决定，本 PR 不动。
• 开关比标题缩进约 12pt：没有说明文字时，Viva 把开关画在加大的点击区域中间（SwitchHitExtent 左右各多 12pt），复选框和图标按钮也是这样。这是 Viva 的设计，应用层不做补偿。

---

类型专属：feat

多平台对齐

• 两端都具备：Viva 桌面端在 macOS 和 Windows 上共用同一份 Go 代码。Windows 没有实机验证，功能矩阵里 Windows 的验证状态保持 pending。
• 只实现了 macOS：已为 Windows 提交跟进 Issue：#
• 只实现了 Windows：已为 macOS 提交跟进 Issue：#
• 刻意只属于某个平台（功能矩阵中另一端记为 platform-specific），理由：

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

• 已更新 shared/platform-feature-matrix/features/declarative-plugin-settings.json 的说明；状态和验证保持 partial/pending
• 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh（223 项通过）和 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD（通过）
• 没有提交 .artifacts/ 下生成的矩阵视图
• [N/A] 已更新矩阵，不需要豁免理由

统一日志系统 / Structured logging

N/A：只改呈现，没有新增生命周期里程碑、操作终态或失败路径。

界面文案 / i18n

• 删除了 desktop.pluginSettings.inherited，改写了 desktop.pluginSettings.scopeHelp，中英都在 shared/i18n/ 修改；运行了 node scripts/i18n/generate-i18n.mjs 并提交生成结果
• 已运行 node scripts/i18n/verify-app-language-localization.mjs 和 node scripts/i18n/generate-i18n.mjs --check，都通过；没有放宽脚本
• 插件自己的标题和说明不是界面翻译，本 PR 没有改写（翻译走上面的插件语言文件方案）

逻辑归属 / Logic placement

• 只改呈现：去掉重复文字、把说明收进 ⓘ。各行的数据、继承和可编辑性仍由 Core 给出，没有新增业务规则
• [N/A] 没有修改平台层已有的可共享逻辑
• 没有按插件名加分支；截图场景里的 Go 设置只是测试数据

性能与内存 / Performance and memory

• 没有新增后台任务、进程或缓存；每行少画一段文字，范围行多一个图标按钮
• [N/A] 主线程没有新增文件读写或进程启动
• [N/A] 不涉及启动、输入、滚动、大文件或搜索路径

设置 / Settings

• 没有新增或修改设置项本身。页面仍显示当前来源路径和实际生效值，打开页面不写文件（已有测试覆盖），保存仍需显式确认

插件契约 / Plugin contract

N/A：不改契约和宿主方法。

发行包与资源 / Bundle and resources

• 没有新增运行时资源；运行了 ./scripts/desktop/verify/verify-runtime-bundle-immutability.sh，通过
• [N/A] 没有新增下载、解压、生成或缓存资源；docs/assets/ 下的截图只是文档

无用代码与重构 / Dead code and refactoring

• 不再使用的词条 desktop.pluginSettings.inherited 已删除
• [N/A] 没有发现需要另开 Issue 的既有债务（设置排序和插件文案翻译见“不在本 PR 范围内”，都属于计划中的后续工作）

---

验证 / Verification

命令或操作	平台	结果
./scripts/desktop/desktop-go.sh test ./... -count=1（在 desktop/，rebase 到 #1898 之后，Core 29b35bf）	macOS	54 个包全部通过
反向验证：分别恢复开关说明文字、继承说明、常驻范围说明后运行 TestPluginSettingsFormEditsOnlyOnExplicitSaveAndPreservesConflictDraft	macOS	三种情况都失败（标题画了 2 次；找到常驻继承说明；ⓘ 不存在），符合预期
./scripts/desktop/desktop-go.sh vet ./internal/settingswindow/（含和不含 vivahead,lithevisual 标签）、gofmt -l	macOS	无输出
LITHE_VISUAL_OUTPUT_DIR=… ./scripts/desktop/desktop-go.sh test -tags vivahead,lithevisual ./internal/settingswindow -run '^TestVisualPluginSettingsForm$'	macOS 无头	生成 2 张截图，已人工核对
node --test --test-timeout=60000 scripts/i18n/test-i18n.mjs	macOS	41/41 通过（见下方说明）
node scripts/i18n/generate-i18n.mjs --check、node scripts/i18n/verify-app-language-localization.mjs	macOS	通过
.agents/skills/write-stable-tests/scripts/verify-test-stability.sh --base origin/preview	macOS	通过
./scripts/desktop/verify/verify-runtime-bundle-immutability.sh	macOS	通过
功能矩阵两个校验脚本	macOS	通过

偶发情况： test-i18n.mjs 第一次和整套桌面测试（含 Core 重编）并行运行时，卡住了 8 分钟：

• generate-i18n.mjs 用 spawnSync("gofmt", [], { input }) 格式化生成的代码。采样看到 node 停在 spawnSync 的事件循环里，gofmt 停在读 stdin 上，两边互相等。
• spawnSync 是同步调用，测试的 60 秒超时不会触发。
• 结束这次运行后单独重跑，8 秒内 41/41 通过，没有复现。这与本 PR 的改动无关，本 PR 没有修改这个脚本。

未能执行的检查和原因： 没有在 Windows 实机上运行；截图来自无头渲染，不代表原生窗口验收。没有在打包后的应用里打开真实插件的设置页手动核对。

提交前确认 / Final checks

• 分支基于最新的 preview（已 rebase 到 feat(desktop): Core 固定版本升到 Lithe-core-rust#33，构建检测跳过被 Git 忽略的目录 #1898 之后），目标分支 preview
• 以 Draft 提交
• 没有无关改动和构建产物，截图不含个人路径（截图时 TMPDIR 指向 /tmp/lithe-visual/）
• 测试全部无头运行，没有启动 Lithe 应用，没有进程残留