[xiaoyumuxi]

关联 Issue / Linked issue

• Refs [Feature] Windows/macOS 统一 Viva 工作台与原生编辑器，保留 Rust Core 和插件体系（分阶段重构） #1794（Viva 统一工作台：Build 工具窗口）

PR 类型 / Type

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

改动说明 / What changes

背景 / Why

#1898 让构建检测跳过被 Git 忽略的目录，但没写进 .gitignore 的点目录仍会被当成构建根目录，例如工具状态、缓存、.claude/worktrees 下的代理工作树副本，Build 窗口因此会把同一个模块列好几遍。用户希望在构建选项里加一个忽略路径的配置，默认忽略所有以 . 开头的目录。

Core 部分（规则语义、分层存储、校验和错误码）已在 Lithe-core-rust#35 合入。这个 PR 把桌面端固定到 #35，并在 Build 选项对话框里提供编辑入口。

改动 / Changes

• Core 固定版本：scripts/desktop/build-desktop-core.sh 的 PINNED_CORE_REVISION 从 feat(windows): multi-session terminal (#31) #34 的 1d4556b（feat(desktop): 侧栏按钮可以隐藏，隐藏的工具窗口列在“…”按钮里 #1901 固定）升到 Lithe-core-rust#35 的合并提交 d19e9ef，中间没有别的 Core 改动。
  • build.detect 新增可选字段 ignoredPaths：省略或 null 时用默认值 [".*"]，传 [] 表示不额外忽略。
  • build.resolveStoredOptions 返回 ignoredPaths { patterns, source }，source 是 local、team 或 default。
  • 新增宿主命令 build.editIgnoredPaths：传数组替换本机列表，传 null 删除本机列表。
  • Core 拒绝不可用的规则时返回 plugin.build.invalidIgnoredPath，field 是 ignoredPaths[i]；规则单独都能解析、合在一起编译失败时，field 是 ignoredPaths。
• Go 绑定（internal/core/build_options.go、build.go）：
  • BuildDetectOptions.IgnoredPaths 随检测请求发送，nil 编码为省略，空切片编码为 []。
  • BuildStoredOptions.IgnoredPaths 和 BuildIgnoredPaths{Patterns, Source}，加上三个来源常量。
  • (*Client).EditBuildIgnoredPaths：Inherit: true 时发送 patterns: null，否则发送数组，没有规则时发送 []。
  • Kernel 接口相应新增这个方法（workbench/app.go）。
• 检测时使用存储的列表（workbench/build_options.go buildDetectOptions）：检测前已经通过 resolveStoredOptions 合并本机和团队文档，这次把其中的 storage.ignoredPaths.patterns 一并传给 build.detect，桌面端不自己解析规则。
• Build 选项对话框（workbench/build_options.go）：
  • 顶部新增“检测”分区，里面是“忽略路径”多行输入框，一行一条规则。
  • 标签旁的 ⓘ 说明规则写法：同 .gitignore、相对项目根目录、只匹配文件夹、后面的规则优先、以 ! 开头的规则能让被 Git 忽略的文件夹重新参与检测、默认值、依赖缓存和构建输出始终跳过、最多 256 条。
  • 输入框下方写明当前来源：
    • 本机：“当前使用本机保存的设置。”
    • 团队：“当前使用团队文件 .lithe/build/options.json 中的设置；修改后只保存在本机。”
    • 默认：“当前使用默认设置；修改后只保存在本机。”
  • 来源是本机列表时显示“恢复默认”。点击后通过 build.editIgnoredPaths 读出团队列表或默认值，填进输入框，但不写入；用户点保存后才删除本机列表。
  • 打开对话框时在后台读取本机和团队文档并交给 Core 解析，不写文件。输入框里的内容和打开时一样就不写；空行会被忽略。
  • 保存时先应用构建系统选项的修改，再在得到的本机文档上替换忽略路径，最后一次写入本机文档并重新检测。
  • 团队文件只读，从不写入。
  • Core 拒绝某条规则时，按 ignoredPaths[i] 换算成输入框里的行号（空行也算行数），报“第 N 行不是可用的忽略规则……”，对话框保持打开，什么都不写。规则合在一起编译失败时，报“这些忽略规则不能一起使用”。
  • 每次打开对话框都有自己的会话号。对话框关闭或重新打开后，后台迟到的读取结果和恢复默认结果都会丢弃。
• Build 窗口入口（workbench/build_tree_view.go）：
  • 标题栏的折叠按钮后面新增齿轮“构建选项”，打开只有忽略路径的对话框，不选构建系统也能用。
  • 构建系统行的齿轮和右键菜单仍打开该构建系统的选项，忽略路径显示在上方。
  • 中文里这两个入口原来都叫“构建选项”，读屏和悬停提示分不开。构建系统行的入口改叫“选项”，英文仍是 “Options”。
• IDE API（workbench/ide_api_build.go）：saveBuildOptionChanges 多了忽略路径参数，IDE API 的选项写入传 nil，行为不变。
• 日志：“保存”和“恢复默认”两个用户操作复用已声明的 app.action.performed，动作名分别是 build.options.save 和 build.ignoredPaths.restoreDefault。标题栏的齿轮沿用 build.options.open。
• i18n：
  • 新增 desktop.build.detection、ignoredPaths、ignoredPathsHelp、ignoredPathsLocal、ignoredPathsTeam、ignoredPathsDefault、invalidIgnoredPath、invalidIgnoredPaths，中英两份都有。
  • 更新 desktop.build.optionsTitle 的说明，它现在也是标题栏按钮的名称。
  • desktop.build.options 的中文改成“选项”。
  • 已重新生成 shared.generated.go。
• 功能矩阵：build-system-plugins 的证据加上 core/build_options.go、workbench/build_options.go 和 workbench/build_ignored_paths_test.go，说明补上这一行为。两端的状态不变，仍是 partial / pending。
• 测试：
  • core/build_options_test.go：
    • TestBuildIgnoredPathsResolveFromTheLayersAndEditTheLocalList 覆盖三层取值（默认、团队、本机）、本机替换、空列表保留为“不忽略”、删除本机列表后回到团队列表、注释行被拒并定位到 ignoredPaths[1]。
    • TestBuildDetectSkipsTheIgnoredPaths 覆盖默认跳过点目录、[] 不忽略、/tools 只忽略这一个目录。
  • workbench/build_ignored_paths_test.go，夹具在根目录、.claude/copy 和 tools 下各放一个构建系统标记：
    • TestBuildOptionsIgnoredPathsAreSavedOnThisMachineAndRestored：默认跳过 .claude/copy；标题栏齿轮打开时没有构建系统选项、显示默认来源、没有“恢复默认”；输入 .*、!.claude、空行、/tools 后保存，重新检测得到根目录和 .claude/copy，并存进本机文档；重开后显示本机来源；“恢复默认”在保存前不写入，保存后检测结果和来源都回到默认。
    • TestBuildOptionsNameTheLineOfARefusedIgnoredPath：使用团队列表时，构建系统行的“选项”打开该构建系统的选项和团队来源说明；第 3 行写 # note 时报第 3 行的错误，对话框保持打开，本机什么也没存。

不在本 PR 范围内 / Out of scope

• 只有本机列表可以编辑。团队文件 .lithe/build/options.json 里的 ignoredPaths 需要手动编辑，对话框只显示它正在生效。
• 忽略路径只作用于构建检测（build.detect）。按 Core [Bug] 多模块spring boot的项目中.worktree导致的崩溃问题 #35 的设计，自动运行项发现、指纹扫描和 Node 清单发现不受影响。
• 没有提供逐条增删的列表编辑器，多行输入框和 .gitignore 的写法一致。

---

类型专属：feat

多平台对齐

• 两端都具备：Viva 桌面端 macOS 与 Windows 是同一份代码，合入后两端都具备
• 只实现了 macOS：已为 Windows 提交跟进 Issue：#
• 只实现了 Windows：已为 macOS 提交跟进 Issue：#
• 刻意只属于某个平台（功能矩阵中另一端记为 platform-specific），理由：

---

范围检查 / Scope checks

功能矩阵 / Feature matrix

• 已更新 shared/platform-feature-matrix/features/build-system-plugins.json：补上证据路径和说明；两端验证状态保持 pending，没有做实机验收
• 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh 和 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD
• 没有提交 .artifacts/ 下生成的矩阵视图
• [N/A] 没有更新矩阵的理由：已更新

统一日志系统 / Structured logging

• “保存”和“恢复默认”复用已声明的 app.action.performed（a.performed），没有新增事件、print 或手写事件 ID
• 一个操作只记一条；Core 拒绝规则属于输入校验，结果直接显示在对话框里，不另记日志
• 只记录动作名和界面来源，不记录规则内容或路径
• [N/A] generate-log-events.mjs --check / verify-log-usage.mjs：仓库里已没有 scripts/logging/，本 PR 也没有新增事件声明

界面文案 / i18n

• 文案都走共享 i18n：在 shared/i18n/ 补齐中英词条，运行 node scripts/i18n/generate-i18n.mjs 并提交生成结果
• 已运行 node scripts/i18n/verify-app-language-localization.mjs 和 node scripts/i18n/generate-i18n.mjs --check，没有放宽脚本或扩大豁免名单

逻辑归属 / Logic placement

• 规则的语法、分层取值、默认值、校验和错误码都在 Rust Core（Lithe-core-rust#35）；桌面端只按行拆分输入、把 Core 返回的序号换算成行号、读写本机文档并显示结果
• [N/A] 没有修改平台层已有的可共享逻辑
• 没有按工具名加分支；默认值 .* 由 Core 给出，桌面端没有写死

性能与内存 / Performance and memory

• 没有新增后台常驻任务或轮询；打开对话框时调用一次 resolveStoredOptions，“恢复默认”调用一次 editIgnoredPaths，两者都在后台执行，结果按会话号丢弃过期答复
• 打开对话框和“恢复默认”时，本机和团队文档的读取与 Core 调用一起在后台执行，窗口线程只发布结果。保存和检测前在窗口线程读这两个小文档（有大小上限）是 preview 上原有的写法，本 PR 没有改动
• [N/A] 不涉及启动、输入、滚动、大文件或搜索路径；检测本身由 Core 剪枝，扫描量只会减少

设置 / Settings

• 规则写法难懂，标签旁有 ⓘ；输入框显示 Core 解析出的实际生效列表（默认值时显示 .*，不是空框或“自动”），下方写明来源
• 打开时只读取本机和团队文档，不写文件；用户点保存后才写本机文档，并重新检测、重新读取；“恢复默认”同样要点保存才生效；团队文件从不写入
• [N/A] 不是 macOS 设置页，是 Build 窗口里的对话框

插件契约 / Plugin contract

• [N/A] 没有改插件契约：ignoredPaths 是团队和本机构建选项文档的字段，build.editIgnoredPaths 是宿主调用 Core 的命令，不是插件可调用的宿主方法。Core [Bug] 多模块spring boot的项目中.worktree导致的崩溃问题 #35 已在协议更新记录中登记（API 编号 —）
• PINNED_CORE_REVISION 已升到包含该改动的 Core commit d19e9ef，桌面端测试经 scripts/desktop/desktop-go.sh 链接的就是这份 Core
• [N/A] 没有修改插件后端协议
• [N/A] 没有新增或修改宿主方法、宿主通知

发行包与资源 / Bundle and resources

• 没有新增运行时资源；本机列表写在用户数据目录的 build-local-options.json（原有文件），团队列表在项目里。已运行 ./scripts/desktop/verify/verify-runtime-bundle-immutability.sh，通过
• [N/A] 没有新增下载、解压、生成或缓存资源

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

• 没有产生无用代码；saveBuildOptionChanges 改为同时处理构建系统选项和忽略路径，IDE API 与对话框共用同一条写入路径
• [N/A] 没有发现需要单独建单的既有债务

---

验证 / Verification

命令或操作	平台	结果
scripts/desktop/desktop-go.sh test ./... -count=1（LITHE_CORE_RUST_DIR 指向 Core d19e9ef，变基到含 #1901 的 preview 后）	macOS arm64	全部通过
scripts/desktop/desktop-go.sh test ./internal/workbench ./internal/core -count=1（加上保存日志、读取挪到后台之后）	macOS arm64	通过
scripts/desktop/desktop-go.sh test ./internal/workbench -race -run TestBuild	macOS arm64	通过，没有数据竞争
无头截图：标题栏打开（默认来源）、本机来源和“恢复默认”、构建系统选项加团队来源加行号报错、ⓘ 悬停说明，明暗主题 × 中英文共 8 张	macOS arm64	已检查：分区、ⓘ 说明、来源说明和行号报错显示正确；中文标题栏入口和构建系统行的入口已经分开
node scripts/i18n/generate-i18n.mjs --check	macOS	通过
node scripts/i18n/verify-app-language-localization.mjs	macOS	通过
./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh	macOS	通过（224 项）
./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/preview HEAD	macOS	通过
./scripts/desktop/verify/verify-runtime-bundle-immutability.sh	macOS	通过
Lithe-core-rust#35：cargo test --workspace、clippy -D warnings、fmt --check、verify-docs.mjs	macOS arm64	通过（在 Core PR 中）

未能执行的检查和原因：

• Windows：本机没有运行 Windows 版；Viva 桌面端两端代码相同，Windows 实机验收待执行，矩阵保持 pending。
• macOS 整机验收：只用无头渲染截图和组件测试验证，没有启动打包后的应用在真实项目里逐项点击。

提交前确认 / Final checks

• 分支从最新的 preview 创建（已变基到包含 feat(desktop): 侧栏按钮可以隐藏，隐藏的工具窗口列在“…”按钮里 #1901 的 preview，固定版本冲突保留 [Bug] 多模块spring boot的项目中.worktree导致的崩溃问题 #35，变基后重跑了全部桌面端测试、i18n、矩阵和发行包检查）；目标分支 preview
• 以 Draft 提交，本地验证通过后才标记 ready
• 没有无关改动，没有提交产物、凭据、个人路径或截图；临时截图测试已删除
• 本次测试没有启动 Lithe 应用，测试都是无头运行，没有进程残留