[xiaoyumuxi]

关联

• 桌面端 Build 窗口改进的第 ② 步。第 ① 步是 feat(desktop): Build 窗口可运行的行常驻绿色运行按钮，依赖标题加 ⓘ 1lck/Lithe-IDEA#1896（Draft），只改呈现。
• 用户反馈：Build 窗口里看不清依赖和目标，同一个模块会出现两遍。原因之一是 .claude/worktrees/* 下的代理工作树、生成目录等被 Git 忽略的目录也被当成了构建根目录。
• 合入后，桌面端另开 PR 把 scripts/desktop/build-desktop-core.sh 的 PINNED_CORE_REVISION 升到合并提交（不叠在 #1896 上）。

这个 PR 做什么

1. 启发式扫描按 Git 忽略规则剪枝

lithe_execution::workspace_scan 的启发式模式（max_depth 有值）被 build.detect 和自动运行项发现共用，深度上限是 6 层。现在它在下降之前剪掉被 Git 忽略的目录，被忽略的子树一个文件都不读。

规则	行为
来源	工作区内途经的每个 .gitignore，以及根目录在工作区内的仓库的 info/exclude
优先级	和 Git 一样，深层文件先匹配先决定，所以下层可以用 ! 重新包含上层忽略的目录
gitfile	.git 是文件时按第一行 gitdir: 解析（相对路径按 gitfile 所在目录）；gitdir 里有 commondir 时读主仓库共享的 info/exclude，所以链接工作树也能读到 .claude/worktrees/ 这种只写在 info/exclude 里的规则
嵌套仓库	含 .git 的子目录另起一套规则，外层仓库的规则到此为止
不读	工作区根以上的目录、core.excludesFile、索引。所以被忽略目录下已跟踪的清单文件不会被发现（模块文档写明了这个近似）
读失败	读不到、超过 1 MiB 的忽略文件不加规则，结果只会多看到目录；远程连接中断（fs::is_transport_failure）仍让扫描失败，和读目录失败一致
解析	用 ignore crate 的 GitignoreBuilder（锁文件里已有 =0.4.33，没有新增第三方包）；第一行的 UTF-8 BOM 去掉；Git 解析不了的行跳过，其余规则照常生效

2. 完整扫描不变

指纹扫描和 Node 清单发现（configuration/inputs.rs，max_depth: None）照旧遍历被忽略的目录：它们决定配置是否过期，多读一个被忽略的输入只会多一次重新生成；跳过反而可能把过期误报成新鲜。

3. 文档

• 契约 README 的 detection 一行、构建系统参考页中英两张表：写明检测最多向下 6 层，跳过已知缓存、构建输出和被 Git 忽略的目录，以及规则来源和不读的部分。
• rust/contracts/rust-core-api.md 的扫描策略段落补上同样的说明，并写明指纹扫描和 Node 清单发现保留被忽略的目录。
• 协议更新记录 2026-11-14 加一行（API 编号 —，pluginAPIVersion 0 内的补充）。没有新增宿主方法、能力版本或协议，不涉及 API 总表。

4. 测试

测试	覆盖
workspace_scan::tests::heuristic_discovery_skips_what_git_ignores_and_full_scans_keep_it	根 .gitignore（带 BOM）、info/exclude（含一行无法解析的模式）、下层 ! 重新包含和新增规则；同一棵树的完整扫描保留全部 9 个目录
workspace_scan::tests::a_linked_worktree_uses_the_shared_exclude_and_a_nested_repository_its_own_rules	gitfile → gitdir → commondir 读到主仓库的 info/exclude；嵌套仓库不受外层规则影响，只用自己的 .gitignore
workspace_scan::tests::an_ignore_file_that_cannot_be_read_hides_nothing	读不到的 .gitignore 不隐藏任何目录
tests::build_systems::detection_skips_directories_git_ignores	经分发器跑 build.detect：.gitignore 忽略的 scratch/ 和 info/exclude 忽略的 .claude/worktrees/copy/ 都不是实例，只剩 cargo:. 和 cargo:tools
tests::remote_sessions::shared_run_scan_reads_the_host_tree_and_stops_when_the_link_drops（修改）	远程工作区的忽略规则来自远端主机：远端 .gitignore 忽略的 generated/ 不出现在扫描结果里

验证

命令	结果
cargo test -p lithe-core（在 rust/）	通过：单测 780、集成测试 25 + 5 + 1
cargo test -p lithe-execution -p lithe-build	通过：11 + 7
cargo clippy -p lithe-execution -p lithe-build -p lithe-core --tests -- -D warnings	无告警
cargo fmt --all -- --check	通过
scripts/rust-core/verify-rust-core-comments.sh	通过
node shared/plugins/scripts/verify-docs.mjs	通过

没有改插件后端协议，没有跑 sdk-e2e.mjs。只在 macOS 上运行；Windows 上的路径前缀匹配靠 ignore crate 处理，没有实机验证。