Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(file-browser): 文件树「显示被忽略的目录」开关(本地 / SSH / device-link 全链路)

Zhang Yunjin7a82afca4bbe
diff --git a/apps/desktop/src/main/file-browser/__tests__/deviceOp.test.ts b/apps/desktop/src/main/file-browser/__tests__/deviceOp.test.ts
index 9c7606f6ef..4707d3517f 100644
--- a/apps/desktop/src/main/file-browser/__tests__/deviceOp.test.ts
+++ b/apps/desktop/src/main/file-browser/__tests__/deviceOp.test.ts
@@ -577,6 +577,7 @@ describe('file-browser device-op', () => {
docMode: undefined,
includeIgnored: true,
maxEntries: 2000,
+ showIgnoredDirs: false,
});
});
@@ -597,6 +598,7 @@ describe('file-browser device-op', () => {
relPath: '',
hideMetaFiles: true,
docMode: undefined,
+ showIgnoredDirs: false,
});
},
);
@@ -630,6 +632,7 @@ describe('file-browser device-op', () => {
relPath: '',
hideMetaFiles: true,
docMode: undefined,
+ showIgnoredDirs: false,
});
const condition = dbWhereMock.mock.calls.at(-1)?.[0];
expect(hasDeepValue(condition, '/remote/home/user/proj')).toBe(true);
@@ -686,6 +689,7 @@ describe('file-browser device-op', () => {
expect(sshRequestMock).toHaveBeenCalledWith('host-1', 'watchStart', {
workdir: sshWorkdir,
hideMetaFiles: true,
+ consumerId: 'device-link',
});
onFsWatchReleased(sshWorkdir);
});
@@ -762,6 +766,7 @@ describe('file-browser device-op', () => {
expect(sshRequestMock).toHaveBeenCalledWith('host-1', 'watchStart', {
workdir: sshWorkdir,
hideMetaFiles: true,
+ consumerId: 'device-link',
});
});
onFsWatchReleased(sshWorkdir);
@@ -770,6 +775,7 @@ describe('file-browser device-op', () => {
expect(sshRequestMock).toHaveBeenCalledWith('host-1', 'watchStop', {
workdir: sshWorkdir,
+ consumerId: 'device-link',
});
});
@@ -882,6 +888,7 @@ describe('file-browser device-op', () => {
});
expect(sshRequestMock).toHaveBeenCalledWith('host-1', 'watchStop', {
workdir: sshWorkdir,
+ consumerId: 'device-link',
});
onFsWatchReleased(sshWorkdir);
});
@@ -1057,6 +1064,7 @@ describe('file-browser device-op', () => {
});
expect(sshRequestMock).toHaveBeenCalledWith('host-1', 'watchStop', {
workdir: sshWorkdir,
+ consumerId: 'device-link',
});
const event = {
event: 'fileTree',
@@ -1070,6 +1078,68 @@ describe('file-browser device-op', () => {
onFsWatchReleased(sshWorkdir);
});
+ /**
+ * 评审 P1:device-link 订阅的是**隐藏态**视图,而 daemon 的 watcher 用的是与
+ * desktop 文件树(可能开着「显示被忽略的目录」)并集后的 matcher —— dist / build
+ * 这类目录内部的事件也会发过来。转发前必须按 device-link 自己的可见性滤一道,
+ * 否则一次构建会把成千上万条控制器根本不会显示的帧推过 relay。
+ */
+ it('watch: SSH 转发前按 device-link 的隐藏态可见性过滤被忽略目录事件', async () => {
+ const sshWorkdir = '/remote/home/user/reveal-union-watch';
+ guardMock.mockResolvedValue({ allowed: false, reason: 'not-found' });
+ dbRowsMock.mockReturnValue([{ remoteHostId: 'host-1' }]);
+ sshRequestMock.mockImplementation(() => Promise.resolve({ ok: true }));
+
+ await onFsWatchSubscribed(sshWorkdir);
+ const handler = sshListenerState.hostEventHandlers.at(-1);
+
+ // 隐藏态不可见的目录内部事件:一律丢弃(一级与嵌套层都要管)。
+ handler?.({
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'change', relPath: 'dist/bundle.js' },
+ });
+ handler?.({
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'add', relPath: 'packages/foo/build/out.map' },
+ });
+ // 大小写变体同样按不可见处理:matcher 的 ignorecase 默认让 DIST 与 dist 同义,
+ // 事件不该继续推过 relay(评审 P2)。
+ handler?.({
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'change', relPath: 'DIST/bundle.js' },
+ });
+ // 名单本身是混合大小写(Library / Temp / Logs),段比较折叠后仍要命中。
+ handler?.({
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'change', relPath: 'remote/Library/x.dat' },
+ });
+ expect(pushSpy).not.toHaveBeenCalled();
+
+ // 普通路径照常转发。
+ const visible = {
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'change', relPath: 'src/app.ts' },
+ };
+ handler?.(visible);
+ expect(pushSpy).toHaveBeenCalledWith(FILE_BROWSER_EVENT_CHANNEL, visible.data, {
+ dataOwnerId: 'owner-a',
+ ownerGeneration: 7,
+ });
+
+ // 与忽略目录同名的**普通文件**(叶子段)不算内部:listDir 会列出它,事件也必须转发
+ // (否则它的行陈旧到手动刷新)—— 忽略名单是目录规则,只判祖先段。
+ const sameNameFile = {
+ event: 'fileTree',
+ data: { workdir: sshWorkdir, type: 'change', relPath: 'dist' },
+ };
+ handler?.(sameNameFile);
+ expect(pushSpy).toHaveBeenCalledWith(FILE_BROWSER_EVENT_CHANNEL, sameNameFile.data, {
+ dataOwnerId: 'owner-a',
+ ownerGeneration: 7,
+ });
+ onFsWatchReleased(sshWorkdir);
+ });
+
it('watch: a second release cancels an already scheduled SSH reconcile', async () => {
const sshWorkdir = '/remote/home/user/cancel-retry-watch';
guardMock.mockResolvedValue({ allowed: false, reason: 'not-found' });
@@ -1100,17 +1170,19 @@ describe('file-browser device-op', () => {
// ── gzip(应用层压缩)────────────────────────────────────────────────────
- it('caps op advertises gzip; unknown op stays a deterministic negative signal', async () => {
+ it('caps op advertises gzip + showIgnoredDirs; unknown op stays a deterministic negative signal', async () => {
// caps 与 workdir 无关,guard 之前处理——guard 拒绝也不影响探测。
+ // 控制端用 showIgnoredDirs 决定「显示被忽略的目录」开关是可点还是禁用+升级提示。
expect(await handleRemoteOp({ op: 'caps', workdir })).toEqual({
ok: true,
gzip: true,
+ showIgnoredDirs: true,
completeDirectoryListing: true,
fileRead: true,
dirExport: true,
folderAttachment: true,
});
- // 控制端把 unknown op 当"老端不支持压缩"的确定性负信号,形状不能漂。
+ // 控制端把 unknown op 当"老端不支持压缩/开关"的确定性负信号,形状不能漂。
expect(await handleRemoteOp({ op: 'nope', workdir })).toEqual({
ok: false,
message: 'unknown op: nope',
diff --git a/apps/desktop/src/main/file-browser/__tests__/remoteWatch.test.ts b/apps/desktop/src/main/file-browser/__tests__/remoteWatch.test.ts
new file mode 100644
index 0000000000..41de80851a
--- /dev/null
+++ b/apps/desktop/src/main/file-browser/__tests__/remoteWatch.test.ts
@@ -0,0 +1,158 @@
+/**
+ * remote-watch.test.ts — SSH 会话 watch 注册表的失败清理回归。
+ *
+ * 锁的不变量:切「显示被忽略的目录」会在同一个 key 上 stop→start,而两个
+ * watchStart 请求都是异步的。旧请求迟到 reject 时只能回收**它自己装上的**
+ * 注册,不能顺手删掉同 key 上的替换注册 —— 否则新注册变成孤儿:后续 stop()
+ * 提前返回、事件 / 重连 listener 泄漏,daemon 侧 watch 也不会停,反复切换
+ * 会累积重复订阅。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import type { BrowserWindow } from 'electron';
+
+import type { RemoteFileBrowserManager } from '../remote.js';
+
+vi.mock('../../logger', () => ({
+ createLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+import { RemoteWatchRegistry } from '../remote-watch';
+
+function makeWindow(id = 1): BrowserWindow {
+ return { id, isDestroyed: () => false, once: vi.fn() } as unknown as BrowserWindow;
+}
+
+function deferred<T = void>() {
+ let resolve!: (value: T) => void;
+ let reject!: (err: unknown) => void;
+ const promise = new Promise<T>((res, rej) => {
+ resolve = res;
+ reject = rej;
+ });
+ return { promise, resolve, reject };
+}
+
+function setup() {
+ const request = vi.fn(async (): Promise<unknown> => undefined);
+ // 每次订阅返回独立的退订 spy:断言必须分清「哪次 start 装上的 listener 被拆了」。
+ const eventOffs: Array<ReturnType<typeof vi.fn>> = [];
+ const reconnectOffs: Array<ReturnType<typeof vi.fn>> = [];
+ const mgr = {
+ request,
+ onHostEvent: vi.fn(() => {
+ const off = vi.fn();
+ eventOffs.push(off);
+ return off;
+ }),
+ onHostConnected: vi.fn(() => {
+ const off = vi.fn();
+ reconnectOffs.push(off);
+ return off;
+ }),
+ } as unknown as RemoteFileBrowserManager;
+ return { registry: new RemoteWatchRegistry(mgr), request, eventOffs, reconnectOffs };
+}
+
+describe('RemoteWatchRegistry 失败清理', () => {
+ it('旧 watchStart 迟到失败不回收同 key 上的替换注册', async () => {
+ const { registry, request, eventOffs, reconnectOffs } = setup();
+ const win = makeWindow();
+ const first = deferred();
+ request.mockImplementationOnce(() => first.promise);
+
+ const oldStart = registry.start(win, 'host-1', '/repo', { showIgnoredDirs: false }, vi.fn());
+ // 开关切换:先停旧注册,再用新选项装一份替换注册(同一 key)。
+ await registry.stop(win.id, 'host-1', '/repo');
+ await registry.start(win, 'host-1', '/repo', { showIgnoredDirs: true }, vi.fn());
+ expect(eventOffs).toHaveLength(2);
+
+ first.reject(new Error('host unreachable'));
+ await expect(oldStart).rejects.toThrow('host unreachable');
+
+ // 替换注册仍在册:stop 能拆掉它,并给 daemon 发 watchStop。
+ await registry.stop(win.id, 'host-1', '/repo');
+ expect(request).toHaveBeenCalledWith('host-1', 'watchStop', {
+ workdir: '/repo',
+ consumerId: 'desktop-tree',
+ });
+ // 旧注册自己装的那对 listener:stop 拆一次 + 迟到失败清理一次。
+ expect(eventOffs[0]).toHaveBeenCalledTimes(2);
+ expect(reconnectOffs[0]).toHaveBeenCalledTimes(2);
+ // 替换注册的那对:由最后的 stop 拆掉(旧 catch 不能替它做主)。
+ expect(eventOffs[1]).toHaveBeenCalledTimes(1);
+ expect(reconnectOffs[1]).toHaveBeenCalledTimes(1);
+ });
+
+ it('启动失败且没有替换注册:注册被回收,后续 stop 是 no-op', async () => {
+ const { registry, request, eventOffs, reconnectOffs } = setup();
+ const win = makeWindow();
+ request.mockRejectedValueOnce(new Error('boom'));
+
+ await expect(registry.start(win, 'host-1', '/repo', {}, vi.fn())).rejects.toThrow('boom');
+ expect(eventOffs[0]).toHaveBeenCalledTimes(1);
+ expect(reconnectOffs[0]).toHaveBeenCalledTimes(1);
+
+ request.mockClear();
+ await registry.stop(win.id, 'host-1', '/repo');
+ expect(request).not.toHaveBeenCalled();
+ });
+
+ /**
+ * 评审 P1:同 (host, workdir) 的多个窗口共用一个 consumerId,而 stop 侧有引用
+ * 计数(还有别窗在 watch 就不发 watchStop)。两个替换 start 同时失败时,本地
+ * 条目全被删、daemon 侧却会留着注册与重建出来的 watcher(没有客户端再 stop
+ * 它)。必须由**最后一个**失败者撤回。
+ */
+ it('同 workdir 两个窗口的 start 都失败:最后一个失败者撤回 daemon 注册', async () => {
+ const { registry, request } = setup();
+ const w1 = makeWindow(1);
+ const w2 = makeWindow(2);
+ const first = deferred();
+ const second = deferred();
+ request.mockImplementationOnce(() => first.promise);
+ request.mockImplementationOnce(() => second.promise);
+
+ const start1 = registry.start(w1, 'host-1', '/repo', { showIgnoredDirs: true }, vi.fn());
+ const start2 = registry.start(w2, 'host-1', '/repo', { showIgnoredDirs: true }, vi.fn());
+
+ // 先失败的窗口还看到另一个本地条目 → 不能撤(对方可能站起来)。
+ first.reject(new Error('boom-1'));
+ await expect(start1).rejects.toThrow('boom-1');
+ expect(request).not.toHaveBeenCalledWith('host-1', 'watchStop', expect.anything());
+
+ // 最后一个失败者:本地再无同 (host, workdir) 条目 → 撤注册。
+ second.reject(new Error('boom-2'));
+ await expect(start2).rejects.toThrow('boom-2');
+ expect(request).toHaveBeenCalledWith('host-1', 'watchStop', {
+ workdir: '/repo',
+ consumerId: 'desktop-tree',
+ });
+ });
+
+ /**
+ * 评审 P1:workdir 是合法 POSIX 路径,可以包含 `::`(如 `/srv/foo::bar`)。旧实现
+ * 把引用计数扫描建立在 `${windowId}::${hostId}::${workdir}` 的字符串拆分上 ——
+ * 拆分会把路径截断,于是认不出另一个窗口在看同一 workdir,停一个窗口会误发
+ * watchStop 把另一个也停掉。现在 hostId / workdir 结构化存在 entry 上。
+ */
+ it('workdir 含 :: 时引用计数仍准确:停一个窗口不误发 watchStop', async () => {
+ const { registry, request } = setup();
+ const w1 = makeWindow(1);
+ const w2 = makeWindow(2);
+ const workdir = '/srv/foo::bar';
+
+ await registry.start(w1, 'host-1', workdir, {}, vi.fn());
+ await registry.start(w2, 'host-1', workdir, {}, vi.fn());
+ request.mockClear();
+
+ await registry.stop(w1.id, 'host-1', workdir);
+ // 另一个窗口还在看 → 不能发 watchStop。
+ expect(request).not.toHaveBeenCalledWith('host-1', 'watchStop', expect.anything());
+
+ await registry.stop(w2.id, 'host-1', workdir);
+ expect(request).toHaveBeenCalledWith('host-1', 'watchStop', {
+ workdir,
+ consumerId: 'desktop-tree',
+ });
+ });
+});
diff --git a/apps/desktop/src/main/file-browser/__tests__/watcher.test.ts b/apps/desktop/src/main/file-browser/__tests__/watcher.test.ts
index f94b413194..5304cc96b0 100644
--- a/apps/desktop/src/main/file-browser/__tests__/watcher.test.ts
+++ b/apps/desktop/src/main/file-browser/__tests__/watcher.test.ts
@@ -20,10 +20,15 @@ const h = vi.hoisted(() => ({
matcherIgnores: vi.fn((_rel: string, _isDir: boolean) => false),
}));
-vi.mock('@cindy/file-browser-core', () => ({
- XDT_TMP_SUFFIX: '.xdt-tmp',
- loadIgnoreMatcher: vi.fn(async () => ({ ignores: h.matcherIgnores })),
-}));
+vi.mock('@cindy/file-browser-core', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('@cindy/file-browser-core')>();
+ return {
+ XDT_TMP_SUFFIX: actual.XDT_TMP_SUFFIX,
+ // 预过滤名单的真名单(单源),loadIgnoreMatcher 太真(要读盘)才被替换。
+ WATCH_ALWAYS_IGNORE: actual.WATCH_ALWAYS_IGNORE,
+ loadIgnoreMatcher: vi.fn(async () => ({ ignores: h.matcherIgnores })),
+ };
+});
import { WatcherManager, type WatcherSubscribeFn } from '../watcher';
import type { WatchedFsEvent } from '../../watcher-host/protocol';
@@ -154,6 +159,106 @@ describe('WatcherManager stop 宽限期', () => {
expect(subscribeFn).toHaveBeenCalledTimes(2);
});
+ it('showIgnoredDirs 变化同样触发重建,相同则复用', async () => {
+ const { manager, subscribeFn, unsubscribe } = setup();
+ const win = makeWindow();
+ await manager.start(win, 'D:/repo', { showIgnoredDirs: false }, vi.fn());
+ // 同值重复 start:仍在宽限内,直接复用不重建。
+ await manager.start(win, 'D:/repo', { showIgnoredDirs: false }, vi.fn());
+ expect(subscribeFn).toHaveBeenCalledTimes(1);
+ expect(unsubscribe).not.toHaveBeenCalled();
+
+ await manager.start(win, 'D:/repo', { showIgnoredDirs: true }, vi.fn());
+ expect(unsubscribe).toHaveBeenCalledTimes(1);
+ expect(subscribeFn).toHaveBeenCalledTimes(2);
+ });
+
+ /**
+ * 预过滤名单的「时机」回归:parcel 的 ignore 只在 subscribe 那一刻生效一次。
+ * node_modules / Library 经常在会话开始后才出现(npm install / Unity 导入),
+ * 当时不存在就漏掉 → 开关打开后这些目录被 matcher 放行,内部每个生成路径都
+ * 变成一条事件推过 watcher-host + IPC。ALWAYS 名单必须无条件注册。
+ */
+ it('ALWAYS 目录当前不存在也进 ignore 名单(开关打开时)', async () => {
+ const { manager, calls } = setup();
+ const workdir = path.join(path.sep, 'no-such-workdir-reveal');
+ await manager.start(makeWindow(), workdir, { showIgnoredDirs: true }, vi.fn());
+ expect(calls[0].ignore).toEqual(
+ expect.arrayContaining([
+ '**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/*',
+ '**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/**/*',
+ '**/[lL][iI][bB][rR][aA][rR][yY]/*',
+ '**/[lL][iI][bB][rR][aA][rR][yY]/**/*',
+ '**/.[gG][iI][tT]/*',
+ '**/.[gG][iI][tT]/**/*',
+ ]),
+ );
+ // 开关打开时 REVEALABLE 不预过滤 —— 它们本来就该推事件。
+ expect(calls[0].ignore).not.toContain('**/[dD][iI][sS][tT]/*');
+ });
+
+ it('开关关闭时同样无条件带上 ALWAYS(目录稍后才出现也不漏)', async () => {
+ const { manager, calls } = setup();
+ const workdir = path.join(path.sep, 'no-such-workdir-hidden');
+ await manager.start(makeWindow(), workdir, { showIgnoredDirs: false }, vi.fn());
+ expect(calls[0].ignore).toEqual(
+ expect.arrayContaining([
+ '**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/*',
+ '**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/**/*',
+ '**/[lL][iI][bB][rR][aA][rR][yY]/*',
+ '**/[lL][iI][bB][rR][aA][rR][yY]/**/*',
+ '**/[dD][iI][sS][tT]/*',
+ '**/[dD][iI][sS][tT]/**/*',
+ ]),
+ );
+ });
+
+ /**
+ * 预过滤名单的形态回归:两个约束必须同时成立。
+ * 1. 层级:必须发 glob,不能发根级绝对路径 —— @parcel/watcher 对非 glob 项
+ * 走 `ignorePaths` 前缀比较,`nested/node_modules/x` 不是
+ * `/workdir/node_modules` 的后代,monorepo / 嵌套 Unity 工程整目录漏过去。
+ * 2. 自身:`**\/<name>/**` 会把**目录自身**的事件也吞掉(探针实测 2.5.6/win32:
+ * mkdir node_modules 一条事件都没有),开关打开时新建 / 删除 / 改名都看不到。
+ * 拆成一级内容与深层内容两条形态(目录自身不匹配)后,事件保留、
+ * 两级内容仍都忽略。
+ */
+ it('预过滤用 glob 覆盖任意层级,且不吞目录自身事件', async () => {
+ const { manager, calls } = setup();
+ await manager.start(makeWindow(), 'D:/repo', { showIgnoredDirs: false }, vi.fn());
+ expect(calls[0].ignore).toContain('**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/*');
+ expect(calls[0].ignore).toContain('**/[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]/**/*');
+ expect(calls[0].ignore).toContain('**/[lL][iI][bB][rR][aA][rR][yY]/*');
+ expect(calls[0].ignore).toContain('**/[lL][iI][bB][rR][aA][rR][yY]/**/*');
+ // 旧形态(吞目录自身事件)不得回潮。
+ expect(calls[0].ignore).not.toContain('**/node_modules/**');
+ expect(calls[0].ignore).not.toContain(path.join('D:/repo', 'node_modules'));
+ });
+
+ /**
+ * 评审 P1(PR #4398 轮八):parcel 的 ignore glob 走 picomatch 默认选项
+ * (`@parcel/watcher/wrapper.js` 只传 `dot` / `windows`,**无 nocase**),而
+ * matcher 用的 `ignore` 包默认 `ignorecase=true` —— 大小写不敏感卷上
+ * `NODE_MODULES` / `Library` 与名单同名,matcher 判忽略、预过滤却匹配不到:
+ * 开关打开时这些目录被 matcher 放行,整棵依赖树的事件都会推过 watcher-host + IPC。
+ * 名字段必须折叠大小写(字符类),区分大小写的原名形态不得回潮。
+ */
+ it('预过滤 glob 折叠大小写:变体目录名同样命中', async () => {
+ const { manager, calls } = setup();
+ await manager.start(makeWindow(), 'D:/repo', { showIgnoredDirs: true }, vi.fn());
+ const ignore = calls[0].ignore;
+ for (const name of [
+ '[nN][oO][dD][eE]_[mM][oO][dD][uU][lL][eE][sS]',
+ '[lL][iI][bB][rR][aA][rR][yY]',
+ ]) {
+ expect(ignore).toContain(`**/${name}/*`);
+ expect(ignore).toContain(`**/${name}/**/*`);
+ }
+ // 区分大小写的原名形态不得回潮(大小写不敏感卷上会漏掉变体目录)。
+ expect(ignore).not.toContain('**/node_modules/*');
+ expect(ignore).not.toContain('**/Library/*');
+ });
+
it('不同 window 同 workdir 互不干扰(key 维度 window×workdir)', async () => {
const { manager, subscribeFn, unsubscribe } = setup();
await manager.start(makeWindow(1), 'D:/repo', {}, vi.fn());
diff --git a/apps/desktop/src/main/file-browser/device-op.ts b/apps/desktop/src/main/file-browser/device-op.ts
index 781748df2a..50387861d1 100644
--- a/apps/desktop/src/main/file-browser/device-op.ts
+++ b/apps/desktop/src/main/file-browser/device-op.ts
@@ -58,6 +58,7 @@ import {
parseFsWatchTopic,
type PushOwnerStamp,
} from '@cindy/device-link';
+import { REVEALABLE_IGNORE_DIR_NAMES } from '../../shared/ignoreNames';
import { WorkdirWatchManager } from '@cindy/remote-file-service';
import type { FsRpcMethods } from '@cindy/remote-file-service/protocol';
@@ -168,6 +169,13 @@ interface RemoteOpArgs {
includeIgnored?: boolean;
maxEntries?: number;
docMode?: boolean;
+ /**
+ * 「显示被忽略的目录」开关(控制端下发的视图偏好)。listDir 生效;
+ * device-link 的 watch 不走本 op(控制端订阅 topic 触发),那边仍是
+ * hideMetaFiles:true 的默认过滤 —— 打开开关后这些目录在被控端可见,
+ * 但内部改动不会有实时事件(手动刷新可见)。
+ */
+ showIgnoredDirs?: boolean;
cap?: number;
query?: string;
caseSensitive?: boolean;
@@ -421,11 +429,16 @@ async function handleRemoteOp(args: RemoteOpArgs): Promise<unknown> {
: null;
// 能力探测:与 workdir 无关、零 fs 访问,放在 guard 之前。老被控端没有
// 这个分支,会走到 default 返回 `unknown op: caps`——控制端把它当确定性
- // 的"不支持压缩"信号(见 fileBrowserTransport 的 caps 缓存)。
+ // 的"能力全无"信号(见 fileBrowserTransport 的 caps 缓存)。
+ //
+ // gzip / completeDirectoryListing / fileRead:上游已落地的能力位;
+ // showIgnoredDirs:listDir 支持「显示被忽略的目录」开关(控制端据此决定
+ // 标题行的开关是可点还是禁用+升级提示;老端会静默忽略该字段)。
if (args.op === 'caps') {
return {
ok: true as const,
gzip: true as const,
+ showIgnoredDirs: true as const,
completeDirectoryListing: true as const,
fileRead: true as const,
dirExport: true as const,
@@ -527,6 +540,7 @@ async function handleRemoteOp(args: RemoteOpArgs): Promise<unknown> {
relPath: args.relPath ?? '',
hideMetaFiles: args.hideMetaFiles ?? true,
docMode: args.docMode,
+ showIgnoredDirs: args.showIgnoredDirs === true,
includeIgnored: args.includeIgnored,
maxEntries: args.maxEntries,
});
@@ -628,12 +642,15 @@ async function handleRemoteOp(args: RemoteOpArgs): Promise<unknown> {
return { ok: true, url: url.toString(), size: st.size, mtimeMs: st.mtimeMs };
}
case 'listDir': {
+ // includeIgnored 是完全绕过展示过滤(手机 HTML 快照枚举用);
+ // showIgnoredDirs 只放行可放行层(依赖 / 构建产物 / 缓存),VCS / OS 垃圾仍隐藏。
const matcher =
args.includeIgnored === true
? null
: await loadIgnoreMatcher(workdir, {
hideMetaFiles: args.hideMetaFiles ?? true,
honorVcsIgnore: false,
+ showIgnoredDirs: args.showIgnoredDirs === true,
});
return listDir(workdir, args.relPath ?? '', matcher, {
docMode: args.includeIgnored === true ? false : args.docMode,
@@ -900,6 +917,27 @@ async function startFsWatchIfDesired(workdir: string): Promise<void> {
}
}
+/** relPath 是否落在「隐藏态不可见、只有开着『显示被忽略的目录』才看得见」的
+ * 目录**内部**。用于 device-link 转发前按自己的可见性过滤 daemon 的并集事件流。
+ *
+ * 只判**祖先段**:忽略名单是**目录**规则,同名普通文件(`dist` / `build` /
+ * `.cache` 这种没有扩展名的构建脚本、配置文件)在 listDir 里是照常显示的 ——
+ * 把叶子段也判进去会让这些文件的 add/change/unlink 事件被丢掉,行陈旧到手动
+ * 刷新(评审 P1)。
+ *
+ * 代价:被忽略目录**自身**的事件(`relPath='node_modules'`)也会转发给隐藏态
+ * 客户端。事件流不携带类型、同名普通文件必须放行,两者无法从路径区分;转发后
+ * 在隐藏态树里是 no-op(该目录不在 entries),只是每次目录级变更多一条无效 IPC。
+ * 这层本来就是粗粒度预过滤,精确判据在 renderer(queueEventRefresh)。
+ *
+ * 段比较折叠大小写:matcher 用的 `ignore` 包默认 `ignorecase=true`(大小写不敏感
+ * 卷上 `DIST` 与 `dist` 是同一个目录),不折叠会把变体目录内部的事件继续推过
+ * relay(评审 P2)。 */
+function isInsideRevealableIgnoreDir(relPath: string): boolean {
+ const segments = relPath.split('/');
+ return segments.slice(0, -1).some((segment) => REVEALABLE_IGNORE_DIR_NAMES.has(segment.toLowerCase()));
+}
+
function scheduleFsWatchReconcile(workdir: string): void {
const timer = setTimeout(() => {
// timer 排队后可能再次 release;reconcile 只消费当前意图,绝不重新
@@ -981,9 +1019,18 @@ async function onFsWatchSubscribedInner(workdir: string, token: symbol): Promise
const hostId = exec.hostId;
const offEvent = mgr.onHostEvent(hostId, (evt) => {
if (evt.event !== 'fileTree') return;
- const data = evt.data as { workdir: string };
+ const data = evt.data as { workdir: string; relPath?: string };
if (data.workdir !== workdir) return;
if (!fsWatchDesired.has(workdir)) return;
+ // device-link 订阅的是**隐藏态**视图,而 daemon 侧的 watcher 用的是与 desktop
+ // 文件树(可能开着「显示被忽略的目录」)并集后的 matcher —— dist / build / Temp
+ // 这类目录内部的事件也会发过来。不在这里按 device-link 自己的可见性再滤一道,
+ // 一次构建就会把成千上万条控制器根本不会显示的事件推过共享 relay(聚合背压
+ // → 断连)(评审 P1)。
+ // 注:恒真忽略(BUILTIN_IGNORE_ALWAYS)与「不 watch 内部」(node_modules /
+ // Library)两层 daemon 自己就不发;`.gitignore` 自定义条目要在 daemon 侧才有
+ // matcher,这里判不了,不在本层职责。
+ if (typeof data.relPath === 'string' && isInsideRevealableIgnoreDir(data.relPath)) return;
pushToTopicSubscribers(FILE_BROWSER_EVENT_CHANNEL, evt.data, ownerStamp);
});
let listenersDisposed = false;
@@ -996,7 +1043,9 @@ async function onFsWatchSubscribedInner(workdir: string, token: symbol): Promise
};
const stopWatch = (): void => {
disposeListeners();
- void mgr.request(hostId, 'watchStop', { workdir }).catch(() => undefined);
+ void mgr
+ .request(hostId, 'watchStop', { workdir, consumerId: 'device-link' })
+ .catch(() => undefined);
};
const isRegistered = (): boolean => sshWatchOffs.get(workdir) === stopWatch;
const disposeStaleWatch = (): void => {
@@ -1027,7 +1076,14 @@ async function onFsWatchSubscribedInner(workdir: string, token: symbol): Promise
return false;
}
try {
- await mgr.request(hostId, 'watchStart', { workdir, hideMetaFiles: true });
+ // consumerId:daemon 把这里的隐藏态需求与 desktop 文件树(可能开着「显示
+ // 被忽略的目录」)的需求分开登记、取可见性并集 —— 否则后到的一方会把对方
+ // 的 matcher 覆盖掉,desktop 仍列着 build / dist 却收不到它们的事件。
+ await mgr.request(hostId, 'watchStart', {
+ workdir,
+ hideMetaFiles: true,
+ consumerId: 'device-link',
+ });
} catch (err) {
if (!isCurrent()) disposeStaleWatch();
throw err;
diff --git a/apps/desktop/src/main/file-browser/index.ts b/apps/desktop/src/main/file-browser/index.ts
index bb80994d92..1796b0375a 100644
--- a/apps/desktop/src/main/file-browser/index.ts
+++ b/apps/desktop/src/main/file-browser/index.ts
@@ -144,6 +144,8 @@ interface ListDirArgs extends RemoteRoutedArgs {
hideMetaFiles?: boolean;
/** Doc mode: only `.md` files + dirs that contain `.md` descendants. */
docMode?: boolean;
+ /** 用户开关「显示被忽略的目录」——列出依赖 / 构建产物 / 缓存目录。默认 false。 */
+ showIgnoredDirs?: boolean;
}
interface ReadFileArgs extends RemoteRoutedArgs {
@@ -176,6 +178,8 @@ interface StatArgs extends RemoteRoutedArgs {
interface WatchArgs extends RemoteRoutedArgs {
workdir: string;
hideMetaFiles?: boolean;
+ /** 与 listDir 同源:开关变了要带新 matcher 重建 watcher。 */
+ showIgnoredDirs?: boolean;
}
/**
@@ -778,6 +782,7 @@ export function registerFileBrowserIpc(): void {
hideMetaFiles: args.hideMetaFiles ?? true,
docMode: args.docMode,
includeIgnored: args.includeIgnored,
+ showIgnoredDirs: args.showIgnoredDirs === true,
});
return entries;
} catch (err) {
@@ -785,12 +790,15 @@ export function registerFileBrowserIpc(): void {
throwRemoteFsIpcError(err);
}
}
+ // includeIgnored 是完全绕过展示过滤(手机 HTML 快照枚举用);showIgnoredDirs
+ // 只放行可放行层(依赖 / 构建产物 / 缓存),VCS / OS 垃圾仍隐藏。前者优先。
const matcher =
args.includeIgnored === true
? null
: await loadIgnoreMatcher(args.workdir, {
hideMetaFiles: args.hideMetaFiles ?? true,
honorVcsIgnore: false,
+ showIgnoredDirs: args.showIgnoredDirs === true,
});
return listDir(args.workdir, args.relPath ?? '', matcher, {
docMode: args.includeIgnored === true ? false : args.docMode,
@@ -974,7 +982,7 @@ export function registerFileBrowserIpc(): void {
window,
args.remoteHostId,
args.workdir,
- { hideMetaFiles: args.hideMetaFiles ?? true },
+ { hideMetaFiles: args.hideMetaFiles ?? true, showIgnoredDirs: args.showIgnoredDirs === true },
(fsEvent) => {
if (window.isDestroyed()) return;
window.webContents.send(FILE_BROWSER_PUSH.EVENT, fsEvent);
@@ -988,7 +996,7 @@ export function registerFileBrowserIpc(): void {
await watcherManager.start(
window,
args.workdir,
- { hideMetaFiles: args.hideMetaFiles ?? true },
+ { hideMetaFiles: args.hideMetaFiles ?? true, showIgnoredDirs: args.showIgnoredDirs === true },
(fsEvent: FileTreeEvent) => {
if (window.isDestroyed()) return;
window.webContents.send(FILE_BROWSER_PUSH.EVENT, fsEvent);
diff --git a/apps/desktop/src/main/file-browser/remote-watch.ts b/apps/desktop/src/main/file-browser/remote-watch.ts
index 0292d7c200..4bda42a8c1 100644
--- a/apps/desktop/src/main/file-browser/remote-watch.ts
+++ b/apps/desktop/src/main/file-browser/remote-watch.ts
@@ -21,7 +21,20 @@ import type { FileTreeEvent } from './watcher.js';
const log = createLogger('file-browser/remote-watch');
+/**
+ * daemon 侧的消费者身份。同一 (host, workdir) 会被 device-link 的 fs-watch 同时
+ * 订阅(被控端把它转发给控制端);两边各自登记过滤需求,daemon 取可见性并集,
+ * 而不是后到的 watchStart 把先到的 matcher 覆盖掉。
+ */
+const WATCH_CONSUMER_ID = 'desktop-tree';
+
interface RegistryEntry {
+ /** 结构化保存 host / workdir:引用计数扫描不再拆 `${windowId}::${host}::${workdir}`
+ * —— workdir 里合法出现 `::` 时(如 `/srv/foo::bar`),拆分会截断路径,扫描就
+ * 认不出另一个窗口在看同一 workdir,停一个窗口会误发 watchStop 把另一个也停掉
+ * (评审 P1)。 */
+ hostId: string;
+ workdir: string;
offEvent: () => void;
offReconnect: () => void;
}
@@ -43,12 +56,21 @@ export class RemoteWatchRegistry {
window: BrowserWindow,
hostId: string,
workdir: string,
- opts: { hideMetaFiles?: boolean },
+ opts: { hideMetaFiles?: boolean; showIgnoredDirs?: boolean },
onEvent: (event: FileTreeEvent) => void,
): Promise<void> {
const k = this.key(window.id, hostId, workdir);
if (this.entries.has(k)) return;
+ // daemon 侧 watchStart 拿的是同一组过滤开关:开关变了由 renderer 的 store
+ // 重建驱动 stop→start(daemon 自身也会在选项变化时重建 matcher)。
+ const watchOpts = {
+ workdir,
+ hideMetaFiles: opts.hideMetaFiles ?? true,
+ showIgnoredDirs: opts.showIgnoredDirs === true,
+ consumerId: WATCH_CONSUMER_ID,
+ };
+
const offEvent = this.mgr.onHostEvent(hostId, (evt) => {
if (evt.event !== 'fileTree') return;
const data = evt.data as FileTreeEvent;
@@ -59,26 +81,46 @@ export class RemoteWatchRegistry {
// daemon 断链重建后 watch 状态随进程消失;重连成功即重放 watchStart。
const offReconnect = this.mgr.onHostConnected(hostId, () => {
void this.mgr
- .request(hostId, 'watchStart', { workdir, hideMetaFiles: opts.hideMetaFiles ?? true })
+ .request(hostId, 'watchStart', watchOpts)
.catch((err) => log.warn('watch replay failed', { hostId, workdir, error: String(err) }));
});
- this.entries.set(k, { offEvent, offReconnect });
+ const entry: RegistryEntry = { hostId, workdir, offEvent, offReconnect };
+ this.entries.set(k, entry);
window.once('closed', () => {
void this.stop(window.id, hostId, workdir);
});
try {
- await this.mgr.request(hostId, 'watchStart', {
- workdir,
- hideMetaFiles: opts.hideMetaFiles ?? true,
- });
+ await this.mgr.request(hostId, 'watchStart', watchOpts);
log.info('remote watch started', { hostId, workdir, windowId: window.id });
} catch (err) {
- // 启动失败(host 不可达等):清掉注册,renderer 靠聚焦刷新兜底。
- this.entries.delete(k);
+ // 启动失败(host 不可达等):清掉本次注册,renderer 靠聚焦刷新兜底。
+ //
+ // 只回收**本次 start 装上的那条**:切「显示被忽略的目录」会在同一个 key
+ // 上 stop→start,而两个 RPC 都是异步的。旧 start 若在新 start 装上替换
+ // 注册之后才 reject,无条件 delete 会把新注册变成孤儿 —— 之后 stop() 直接
+ // 提前返回,新注册的事件/重连 listener 泄漏,daemon 侧 watch 也不会停,
+ // 反复切换会累积重复订阅。
+ if (this.entries.get(k) === entry) this.entries.delete(k);
offEvent();
offReconnect();
+ // 本地最后一个订阅者也没能站起来:撤回 daemon 侧的 consumer 注册。
+ //
+ // 为什么必须补这一发:同 (host, workdir) 的多个窗口共用一个 consumerId,
+ // 而 stop 侧有引用计数(还有别窗在 watch 就不发 watchStop)。两个替换 start
+ // 同时失败时,本地条目全被删、daemon 侧却留着注册与重建出来的 watcher ——
+ // 没有任何客户端再去 stop 它(评审 P1),它还会抬高 device-link 的可见性
+ // 并集。只在确认本地再无同 (host, workdir) 条目时才发:还有别的窗口在
+ // watch(或它的 start 正在飞,条目已先入表)时不能撤。
+ const stillLocal = [...this.entries.values()].some(
+ (e) => e.hostId === hostId && e.workdir === workdir,
+ );
+ if (!stillLocal) {
+ void this.mgr
+ .request(hostId, 'watchStop', { workdir, consumerId: WATCH_CONSUMER_ID })
+ .catch(() => undefined);
+ }
throw err;
}
}
@@ -92,13 +134,12 @@ export class RemoteWatchRegistry {
entry.offReconnect();
// 同 host 其它 window/workdir 还在 watch 时不能全局 watchStop;仅当这是该
// (host, workdir) 的最后一个订阅者才让 daemon 停 watch。
- const stillWatching = [...this.entries.keys()].some((key) => {
- const [, h, w] = key.split('::');
- return h === hostId && w === workdir;
- });
+ const stillWatching = [...this.entries.values()].some(
+ (e) => e.hostId === hostId && e.workdir === workdir,
+ );
if (!stillWatching) {
await this.mgr
- .request(hostId, 'watchStop', { workdir })
+ .request(hostId, 'watchStop', { workdir, consumerId: WATCH_CONSUMER_ID })
.catch(() => undefined); // 通道断了 daemon 也没了,无孤儿
}
log.info('remote watch stopped', { hostId, workdir, windowId });
diff --git a/apps/desktop/src/main/file-browser/watcher.ts b/apps/desktop/src/main/file-browser/watcher.ts
index c85478fc5a..d0e4b3df57 100644
--- a/apps/desktop/src/main/file-browser/watcher.ts
+++ b/apps/desktop/src/main/file-browser/watcher.ts
@@ -28,16 +28,26 @@
* 复杂 glob (e.g. *.log, build-*) — 与 listDir 路径共享同一份 matcher
* 保证一致性。
*
+ * 与「显示被忽略的目录」(showIgnoredDirs)开关的关系:开关控制的是**是否把内置
+ * 隐藏目录当普通目录对待**。打开后 matcher 不再躲藏 dist / build / Temp 这类目录,
+ * 并且第 1 层预过滤也只保留 PREFILTER_ALWAYS(依赖与 Unity 资源缓存:原生 watch
+ * 这些目录的代价是另一个量级,而且没有实时性需求)—— 即开关打开后,绝大部分被
+ * 忽略目录里的改动会推事件;只有 node_modules / Library 内部仍不推。
+ *
* Event mapping: parcel's create/update/delete → 旧的 add/change/unlink。
* 下游 (useFileTree / useFileContent) 不区分 file vs dir, 所以 'addDir' /
* 'unlinkDir' 这两个旧 type 保留在 union 里但不再发出。
*/
import path from 'node:path';
-import * as fs from 'node:fs';
import type { BrowserWindow } from 'electron';
-import { loadIgnoreMatcher, XDT_TMP_SUFFIX, type Matcher } from '@cindy/file-browser-core';
+import {
+ loadIgnoreMatcher,
+ WATCH_ALWAYS_IGNORE,
+ XDT_TMP_SUFFIX,
+ type Matcher,
+} from '@cindy/file-browser-core';
import { createLogger } from '../logger.js';
import type { WatchedFsEvent } from '../watcher-host/protocol.js';
@@ -92,6 +102,8 @@ interface WatcherEntry {
handle: WatcherHostSubscription | null;
matcher: Matcher;
hideMetaFiles: boolean;
+ /** 建订阅时生效的「显示被忽略的目录」开关;变了走完整重建。 */
+ showIgnoredDirs: boolean;
/**
* 间接引用:订阅回调通过此字段路由事件,宽限期复活时 start() 更新引用
* 即可让新组件实例收到事件,无需触碰 native 订阅。
@@ -105,17 +117,23 @@ interface WatcherEntry {
/**
* 预过滤目录 — 这些目录名一旦出现在路径里, OS watcher 直接跳过,不再向
- * callback 推任何事件。和 ignore.ts 的 BUILTIN_IGNORE 思路一致, 但 parcel
- * 的 ignore 接受的是路径(不是 glob), 所以这里用绝对路径 + 工作区内常见命中
- * 位置一次性穷举。比靠 callback 内过滤省一次 IPC + 一次 matcher 调用。
+ * callback 推任何事件。和 ignore.ts 的 BUILTIN_IGNORE 思路一致。比靠
+ * callback 内过滤省一次 IPC + 一次 matcher 调用。
*
* 注意: 这里只剪"目录名命中" 的 case; *.log / build-* 这种 glob 仍由
* callback 内的 matcher 兜底。
+ *
+ * ALWAYS 是"即使开关打开也不看"的目录:.git 与 OS 垃圾之外,只有
+ * node_modules / Library —— 它们要么条目数十万、要么需要真正的依赖分析,
+ * 原生递归 watch 的代价与收益不成比例(开关打开时它们会出现在文件树里,但
+ * 内部改动不推事件,手动刷新可见)。其余目录随「显示被忽略的目录」放行。
+ *
+ * node_modules / Library 的名单单源在 file-browser-core 的 WATCH_ALWAYS_IGNORE
+ * ——远端 daemon 的事件过滤吃同一份,两侧不会各自漂移。
*/
-const PREFILTER_DIRS = [
- '.git',
- 'node_modules',
- 'Library', // Unity
+const PREFILTER_ALWAYS: string[] = ['.git', '.svn', '.hg', ...WATCH_ALWAYS_IGNORE];
+
+const PREFILTER_REVEALABLE = [
'Temp', // Unity
'Logs', // Unity
'obj', // .NET
@@ -129,19 +147,54 @@ const PREFILTER_DIRS = [
];
/**
- * 把 PREFILTER_DIRS 展成"工作区根下直接命中"的绝对路径列表 (parcel 的
- * ignore 选项要求路径而非 glob)。子目录里同名目录(e.g. nested
- * node_modules) parcel 会自己沿父链判断 — 它内部用前缀匹配。
+ * 名单 → parcel ignore glob。
+ *
+ * @parcel/watcher 的 ignore 数组吃两种形态:非 glob 走 `ignorePaths`(相对
+ * workdir resolve 成绝对路径,**前缀**比较),glob 走 picomatch 正则。前缀形态
+ * 只认“工作区根下直接命中”—— 实测(2.5.6, win32)`nested/node_modules/x` 不是
+ * `/workdir/node_modules` 的后代,一条事件都拦不住,monorepo
+ * (`packages/foo/node_modules`)与嵌套 Unity 工程(`client/Library`)全量漏过去。
+ * 所以统一发 glob。
+ *
+ * 每个目录发**两条**`**\/<name>/*` 与 `**\/<name>/**\/*`,而不是一条
+ * `**\/<name>/**` —— 后者把**目录自身**的事件也吞掉(实测:mkdir node_modules
+ * 一条事件都没有),于是开关打开时新建 / 删除 / 改名 node_modules / Library 都
+ * 不会让 renderer refetch 父目录,那一行缺失或陈旧到手动刷新(评审 P1;daemon
+ * 侧同一裁决见 watch.ts 的 isInsideAlwaysIgnoredDir)。两条形态下:目录自身不
+ * 匹配 → 事件保留;一级与深层内容都匹配 → 仍不监听(也不会进入子目录)。
+ *
+ * 将来名单里若出现**文件**项(如 .DS_Store),要另发不带后缀的 `**\/<name>`
+ * —— 文件没有“内部”,套用同一对形态会让它自己漏出去。
+ *
+ * 名字段展开为**大小写不敏感**的字符类(`[nN][oO]...`):parcel 内部走
+ * `picomatch.makeRe(value, { dot, windows })`,**没有 nocase** —— glob 区分大小写;
+ * 而 matcher 用的 `ignore` 包默认 ignorecase=true。大小写不敏感卷上 `NODE_MODULES` /
+ * `Library` 与名单同名、matcher 判定为忽略,预过滤却匹配不到:开关打开时这些目录被
+ * matcher 放行,整棵依赖树的每个事件都会一路推过 watcher-host + IPC(评审 P1)。
*/
-function buildIgnoreList(workdir: string): string[] {
- const out: string[] = [];
- for (const dir of PREFILTER_DIRS) {
- const abs = path.join(workdir, dir);
- // 不存在的目录传给 parcel 也无害, 但既然遍历是 sync stat 一下省得 native
- // 层处理无效路径。
- if (fs.existsSync(abs)) out.push(abs);
- }
- return out;
+const caseInsensitiveName = (name: string): string =>
+ [...name]
+ .map((ch) => (/[A-Za-z]/.test(ch) ? `[${ch.toLowerCase()}${ch.toUpperCase()}]` : ch))
+ .join('');
+
+const ignoreGlobsForDirs = (names: readonly string[]): string[] =>
+ names.flatMap((name) => {
+ const dir = caseInsensitiveName(name);
+ return [`**/${dir}/*`, `**/${dir}/**/*`];
+ });
+
+function buildIgnoreList(opts: { showIgnoredDirs: boolean }): string[] {
+ // ALWAYS 名单**无条件注册**,不做存在性探测:parcel 的 ignore 只在
+ // subscribe 那一刻生效一次,而 node_modules / Library 常常在会话开始后才出现
+ // (npm install / Unity 导入)。当时不存在就漏掉,就再也没有第二次机会 ——
+ // 开关打开时这些目录被 matcher 放行,目录里每个生成路径都会一路推过
+ // watcher-host + IPC。glob 不存在的目录只是永不命中,无副作用。
+ const always = ignoreGlobsForDirs(PREFILTER_ALWAYS);
+ // REVEALABLE 只在开关关闭时预过滤:开关打开后它们本来就该推事件;关闭时
+ // 即使漏掉预过滤,callback 里的 matcher 也会拦下(代价只是多一次 IPC)。
+ return opts.showIgnoredDirs
+ ? always
+ : [...always, ...ignoreGlobsForDirs(PREFILTER_REVEALABLE)];
}
/**
@@ -192,11 +245,12 @@ export class WatcherManager {
async start(
window: BrowserWindow,
workdir: string,
- opts: { hideMetaFiles?: boolean },
+ opts: { hideMetaFiles?: boolean; showIgnoredDirs?: boolean },
onEvent: (event: FileTreeEvent) => void,
): Promise<void> {
const k = this.key(window.id, workdir);
const hideMetaFiles = opts.hideMetaFiles ?? true;
+ const showIgnoredDirs = opts.showIgnoredDirs === true;
await this.enqueue(k, async () => {
const existing = this.entries.get(k);
if (existing) {
@@ -211,13 +265,16 @@ export class WatcherManager {
// 不同的 onEvent 上下文(如不同组件实例);通过 entry.onEvent 间接路由保证
// 新调用方能收到后续事件。
existing.onEvent = onEvent;
- if (existing.hideMetaFiles === hideMetaFiles) {
+ if (
+ existing.hideMetaFiles === hideMetaFiles &&
+ existing.showIgnoredDirs === showIgnoredDirs
+ ) {
return;
}
// 过滤选项变了:走完整重建(先拆后建,串行链保证不交错)
await this.doStop(k, { onlyIfScheduled: false });
}
- await this.doStart(window, workdir, k, hideMetaFiles, onEvent);
+ await this.doStart(window, workdir, k, hideMetaFiles, showIgnoredDirs, onEvent);
});
}
@@ -255,19 +312,25 @@ export class WatcherManager {
workdir: string,
k: string,
hideMetaFiles: boolean,
+ showIgnoredDirs: boolean,
onEvent: (event: FileTreeEvent) => void,
): Promise<void> {
if (this.entries.has(k)) {
log.debug(`watcher already running for ${k}`);
return;
}
- const matcher = await loadIgnoreMatcher(workdir, { hideMetaFiles, honorVcsIgnore: false });
- const ignore = buildIgnoreList(workdir);
+ const matcher = await loadIgnoreMatcher(workdir, {
+ hideMetaFiles,
+ honorVcsIgnore: false,
+ showIgnoredDirs,
+ });
+ const ignore = buildIgnoreList({ showIgnoredDirs });
const entry: WatcherEntry = {
handle: null,
matcher,
hideMetaFiles,
+ showIgnoredDirs,
onEvent,
state: 'active',
graceTimer: null,
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index ca65566faf..7a55473420 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -2903,6 +2903,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
relPath?: string;
hideMetaFiles?: boolean;
docMode?: boolean;
+ /** 「显示被忽略的目录」——列出依赖 / 构建产物 / 缓存目录。默认 false。 */
+ showIgnoredDirs?: boolean;
}): Promise<
Array<{
name: string;
@@ -3008,6 +3010,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
remoteHostId?: string | null;
workdir: string;
hideMetaFiles?: boolean;
+ /** 与 listDir 同源:开关变了要带新 matcher 重建 watcher。 */
+ showIgnoredDirs?: boolean;
}): Promise<{ ok: boolean }> => ipcRenderer.invoke('maker:file-browser:start-watch', params),
stopWatch: (params: {
remoteHostId?: string | null;
diff --git a/apps/desktop/src/renderer/__tests__/fileBrowserTransportRevealCaps.test.ts b/apps/desktop/src/renderer/__tests__/fileBrowserTransportRevealCaps.test.ts
new file mode 100644
index 0000000000..607ddf1cdd
--- /dev/null
+++ b/apps/desktop/src/renderer/__tests__/fileBrowserTransportRevealCaps.test.ts
@@ -0,0 +1,172 @@
+/**
+ * fileBrowserTransport —— 「显示被忽略的目录」能力探测的三态语义。
+ *
+ * 这条链路的错误分类直接决定用户看到什么:
+ * - 确定性不支持(老被控端没有 remote-op channel)→ false → 标题行开关按
+ * 不可用呈现并说明原因;
+ * - 瞬态失败(隧道不可达 / 重连中)→ **null**,不能落定成 false —— 否则一次
+ * 网络抖动就被显示成「对方版本过旧」,连接恢复后也不会自愈。
+ *
+ * 缓存语义同时被锁住:只缓存肯定结论 true;「不支持」不留在缓存里(被控端可能在
+ * 一次掉线期间升级),瞬态更不缓存。
+ *
+ * window.electronAPI 用 vi.stubGlobal 注入(node 环境,无 jsdom)。
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+type InvokeMock = ReturnType<typeof vi.fn>;
+
+let invokeMock: InvokeMock;
+let transport: typeof import('../lib/fileBrowserTransport');
+/** 模块级 reconnect 订阅注册进来的回调:测试用它们模拟「没有任何 hook 观察」期间的重连。 */
+let presenceCallbacks: Array<(snapshot: { deviceId: string; online: boolean }) => void>;
+let statusCallbacks: Array<(payload: { status: string }) => void>;
+
+/**
+ * 显式重启边界(非 hook):每个用例开头调用,拿到一份全新的 transport 模块。
+ * fileBrowserTransport 的模块级重连代次、订阅标志与 per-deviceId 探测缓存均无
+ * prod 重置入口,只能靠重启模块隔离跨用例残留;放在 beforeEach 里属于「hook
+ * 重载模块」(无论写什么理由都被 test-hygiene 禁止),所以收拢到这里由用例
+ * 显式调用。
+ */
+async function freshTransport(): Promise<void> {
+ // reset-modules: 按用例隔离模块级重连代次、订阅标志与探测缓存
+ vi.resetModules();
+ invokeMock = vi.fn();
+ presenceCallbacks = [];
+ statusCallbacks = [];
+ vi.stubGlobal('window', {
+ electronAPI: {
+ deviceLink: {
+ invoke: invokeMock,
+ onPresenceChanged: (cb: (snapshot: { deviceId: string; online: boolean }) => void) => {
+ presenceCallbacks.push(cb);
+ return () => {
+ const index = presenceCallbacks.indexOf(cb);
+ if (index >= 0) presenceCallbacks.splice(index, 1);
+ };
+ },
+ onStatusChanged: (cb: (payload: { status: string }) => void) => {
+ statusCallbacks.push(cb);
+ return () => {
+ const index = statusCallbacks.indexOf(cb);
+ if (index >= 0) statusCallbacks.splice(index, 1);
+ };
+ },
+ },
+ },
+ });
+ transport = await import('../lib/fileBrowserTransport');
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+// 探测缓存是模块级 per-deviceId,单测用唯一 deviceId 隔离。
+let seq = 0;
+const freshDevice = () => `reveal-${Date.now().toString(36)}-${seq++}`;
+
+describe('deviceSupportsRevealIgnoredDirs', () => {
+ it('新被控端:true,并缓存(不重复探测)', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockResolvedValue({ ok: true, gzip: true, showIgnoredDirs: true });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(1);
+ // 探测走 caps op,与 workdir 无关。
+ expect(invokeMock.mock.calls[0][2][0]).toMatchObject({ op: 'caps' });
+ });
+
+ it('老被控端(caps 返回 unknown op):false,且不缓存(升级后重连能自愈)', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockResolvedValue({ ok: false, message: 'unknown op: caps' });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ expect(invokeMock).toHaveBeenCalledTimes(2);
+
+ // 被控端升级后重连:同一 deviceId 重探必须拿到新结论。
+ invokeMock.mockResolvedValue({ ok: true, showIgnoredDirs: true });
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(3);
+ });
+
+ it('caps 有响应但没带能力位(中间版本):false', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockResolvedValue({ ok: true, gzip: true });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ });
+
+ it('老端无 remote-op channel(CHANNEL_NOT_ALLOWED):确定性 false', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockRejectedValue(new Error('DEVICE_LINK_CHANNEL_NOT_ALLOWED'));
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ });
+
+ it('瞬态失败:返回 null(不是 false),不缓存,恢复后重探拿到真结论', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockRejectedValueOnce(new Error('device link tunnel is not connected'));
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(null);
+
+ invokeMock.mockResolvedValue({ ok: true, showIgnoredDirs: true });
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(2);
+ });
+
+ /**
+ * 重连代次必须是**进程级**的:面板卸载 →(没有任何 hook 观察)→ 重挂载时
+ * hook 局计数器又从 0 开始。拿 hook 局代次当缓存 key 的话,下面这步缓存里的
+ * 旧肯定结论会被误用 —— 开关对着已回滚的老端一直可按。所以缓存自己订阅全局
+ * reconnect 流拿代次。
+ */
+ it('重连(即使没有任何 hook 观察)作废肯定结论缓存', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockResolvedValue({ ok: true, showIgnoredDirs: true });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ // 同代次命中缓存,不重复探测。
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(1);
+ // 模块级订阅已惰性建立。
+ expect(presenceCallbacks.length).toBe(1);
+
+ // 设备被回滚成中间版本 + 重连:订阅侧只看到一次 online 事件(非 hook 驱动)。
+ invokeMock.mockResolvedValue({ ok: true, gzip: true });
+ presenceCallbacks[0]({ deviceId, online: true });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ expect(invokeMock).toHaveBeenCalledTimes(2);
+
+ // 已落定的否定结论本就不缓存 —— 下一次仍然重新问。
+ invokeMock.mockResolvedValue({ ok: true, showIgnoredDirs: true });
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(3);
+ });
+
+ it('relay 恢复 online 同样作废缓存', async () => {
+ await freshTransport();
+ const deviceId = freshDevice();
+ invokeMock.mockResolvedValue({ ok: true, showIgnoredDirs: true });
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(true);
+ expect(invokeMock).toHaveBeenCalledTimes(1);
+ expect(statusCallbacks.length).toBe(1);
+
+ invokeMock.mockResolvedValue({ ok: true, gzip: true });
+ statusCallbacks[0]({ status: 'online' });
+
+ await expect(transport.deviceSupportsRevealIgnoredDirs(deviceId, '/repo')).resolves.toBe(false);
+ expect(invokeMock).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/apps/desktop/src/renderer/__tests__/workdirBrowseRemoteSafety.test.ts b/apps/desktop/src/renderer/__tests__/workdirBrowseRemoteSafety.test.ts
index b525a4435c..9de584f2d8 100644
--- a/apps/desktop/src/renderer/__tests__/workdirBrowseRemoteSafety.test.ts
+++ b/apps/desktop/src/renderer/__tests__/workdirBrowseRemoteSafety.test.ts
@@ -96,7 +96,11 @@ describe('workdir browse remote safety', () => {
expect(routeSource).toContain('deviceId={deviceId}');
// sidebar 侧同理:树 / 文件名索引 / 搜索 / 增删改全部带 remoteHostId,
// 且"显示所在文件夹"这类本机-only 菜单在 remote 下不可用。
- expect(sidebarBrowseSource).toContain('useFileTree({ workdir, remoteHostId, deviceId,');
+ // useFileTree 的参数会被格式化折行,取调用块本身断言而不是整行文本。
+ const treeCall = sidebarBrowseSource.match(/useFileTree\(\{[^}]*\}/)?.[0] ?? '';
+ expect(treeCall).toContain('workdir');
+ expect(treeCall).toContain('remoteHostId');
+ expect(treeCall).toContain('deviceId');
expect(sidebarBrowseSource).toContain('useProjectFileList(workdir, remoteHostId, deviceId, {');
expect(sidebarBrowseSource).toContain('remoteHostId || deviceId ? undefined : handleRevealInFolder');
});
@@ -230,4 +234,34 @@ describe('workdir browse remote safety', () => {
it('keeps empty workdir from reading local files', () => {
expect(fileContentSource).toContain('if (!workdir || !relPath)');
});
+
+ it('文件树标题图标钮带可见的键盘焦点环', () => {
+ // G3 全局规则把非输入元素的 outline 一律去掉了(focus-visible:outline-none 必
+ // 自配):纯图标钮若不自带环,键盘 Tab 时就没有任何可见焦点指示 —— 包括新增的
+ // 「显示被忽略的目录」开关(评审 P1)。
+ const source = readFileSync(
+ resolve(
+ __dirname,
+ '..',
+ 'features',
+ 'cc-agent',
+ 'workdir-browse',
+ 'fileTreeHeaderButtonClass.ts',
+ ),
+ 'utf8',
+ );
+ expect(source).toContain('focus-visible:outline-none');
+ expect(source).toContain('focus-visible:ring-2');
+ expect(source).toContain('focus-visible:ring-[var(--focus-ring)]');
+ });
+
+ it('persists expanded-set rename under the effective reveal scope', () => { // device-link 老被控端不支持「显示被忽略的目录」时,useFileTree 会退回隐藏态
+ // store;rename 迁移若仍按用户偏好写 reveal scope,迁移会落在不生效的那一格
+ // (隐藏 scope 仍存旧路径,面板重挂载后请求已不存在的目录、新目录展开态丢失)。
+ expect(sidebarBrowseSource).toContain(
+ 'const scopedShowIgnoredDirs = showIgnoredDirs && tree.showIgnoredDirsSupported !== false;',
+ );
+ expect(sidebarBrowseSource).not.toMatch(/loadExpandedSet\(workdir, \{ showIgnoredDirs \}\)/);
+ expect(sidebarBrowseSource).not.toMatch(/saveExpandedSet\(workdir, next, \{ showIgnoredDirs \}\)/);
+ });
});
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeHeaderActions.tsx b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeHeaderActions.tsx
new file mode 100644
index 0000000000..44509cf382
--- /dev/null
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeHeaderActions.tsx
@@ -0,0 +1,108 @@
+/**
+ * FileTreeHeaderActions — 文件树标题行右侧的动作按钮组。
+ *
+ * 两个宿主共用(此前各自复制了一份,加「显示被忽略的目录」时出现了两种圆角):
+ * - doc 模式侧栏 WorkdirBrowseSidebar
+ * - RSB 文件浏览器 FileBrowserBody 的 TreeHeader
+ *
+ * tree 模式:搜索 / 显示被忽略的目录 / 收起全部 / 刷新
+ * search 模式:X 退出搜索(依次替代上面四个的名字空间,与 doc 模式历史行为一致)
+ *
+ * 几何与可访问名:所有图标钮走 FILE_TREE_HEADER_ICON_BUTTON_CLASS(DESIGN.md §5
+ * 控件框 pill 档 + 自带 focus-visible 环),并配本地化 aria-label + Tip
+ * (DESIGN.md §14.6 纯图标控件的交付合同)。
+ */
+
+import { useTranslation } from 'react-i18next';
+import type { ReactNode } from 'react';
+import {
+ ChevronsDownUp,
+ RefreshCw,
+ Search,
+ X as XIcon,
+} from 'lucide-react';
+
+import { Tip } from '@/components/ui/tooltip';
+import { FILE_TREE_HEADER_ICON_BUTTON_CLASS } from './fileTreeHeaderButtonClass';
+import { FileTreeIgnoredDirsToggle } from './FileTreeIgnoredDirsToggle';
+
+export interface FileTreeHeaderActionsProps {
+ /** 当前是文件树还是项目级搜索:搜索态只留「退出搜索」。 */
+ mode: 'tree' | 'search';
+ onToggleSearch: () => void;
+ onCollapseAll: () => void;
+ onRefresh: () => void;
+ /** 被控端不支持「显示被忽略的目录」(老 Desktop):开关渲染成不可用 + 说明原因。 */
+ ignoredDirsUnsupported?: boolean;
+}
+
+export function FileTreeHeaderActions({
+ mode,
+ onToggleSearch,
+ onCollapseAll,
+ onRefresh,
+ ignoredDirsUnsupported = false,
+}: FileTreeHeaderActionsProps) {
+ const { t } = useTranslation();
+
+ if (mode === 'search') {
+ // search 是独立态:refresh / collapse 只对文件树有意义,搜索时不该出现。
+ return (
+ <HeaderIconButton
+ label={t('ccAgent.workdirBrowse.searchPanel.exit')}
+ onClick={onToggleSearch}
+ >
+ <XIcon size={14} strokeWidth={2} />
+ </HeaderIconButton>
+ );
+ }
+
+ return (
+ <>
+ {/* 搜索与「显示被忽略的目录」都属于「树里显示什么」,并排放。 */}
+ <HeaderIconButton
+ label={t('ccAgent.workdirBrowse.searchPanel.searchFiles')}
+ onClick={onToggleSearch}
+ >
+ <Search size={14} strokeWidth={2} />
+ </HeaderIconButton>
+ <FileTreeIgnoredDirsToggle unsupported={ignoredDirsUnsupported} />
+ <HeaderIconButton
+ label={t('ccAgent.workdirBrowse.treeAction.collapseAll')}
+ onClick={onCollapseAll}
+ >
+ <ChevronsDownUp size={14} strokeWidth={2} />
+ </HeaderIconButton>
+ <HeaderIconButton
+ label={t('ccAgent.workdirBrowse.treeAction.refresh')}
+ onClick={onRefresh}
+ >
+ <RefreshCw size={14} strokeWidth={2} />
+ </HeaderIconButton>
+ </>
+ );
+}
+
+/** 标题行图标钮:Tip 文案与 aria-label 同一个来源,避免只写其中一个。 */
+function HeaderIconButton({
+ label,
+ onClick,
+ children,
+}: {
+ label: string;
+ onClick: () => void;
+ children: ReactNode;
+}) {
+ return (
+ <Tip text={label}>
+ <button
+ type="button"
+ aria-label={label}
+ onClick={onClick}
+ className={FILE_TREE_HEADER_ICON_BUTTON_CLASS}
+ >
+ {children}
+ </button>
+ </Tip>
+ );
+}
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeIgnoredDirsToggle.tsx b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeIgnoredDirsToggle.tsx
new file mode 100644
index 0000000000..a9ce3dac6c
--- /dev/null
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeIgnoredDirsToggle.tsx
@@ -0,0 +1,88 @@
+/**
+ * FileTreeIgnoredDirsToggle — 文件树标题行里的「显示被忽略的目录」开关。
+ *
+ * 位置:与「搜索 / 收起 / 刷新」并列,紧挨搜索(两者都属于"树里显示什么")。
+ * RSB 文件浏览器(FileBrowserBody 的 TreeHeader)与 doc 模式侧栏
+ * (WorkdirBrowseSidebar 的标题行)共用本组件 —— 同一份全局偏好只留一个入口,
+ * 两处以同一视觉/交互出现。
+ *
+ * 语义:`useFileBrowserPreference` 全局偏好(默认关),打开后文件树列出 Cindy
+ * 默认隐藏的依赖 / 构建产物 / 缓存目录(build、dist、out、node_modules…)。
+ * 偏好进 `useFileTree` 的 store key,切换即换 store 并用新 matcher 重拉,用户
+ * 不需要手动刷新。
+ *
+ * 形态对齐同级按钮与既有先例(ReviewTabBody 的文件树显隐开关):
+ * - size-5 + 图标 14,与同排三个按钮同几何,不改变标题行节奏
+ * - 圆角走 DESIGN.md §5 的 pill 档(控件框 = pill);整行四个按钮共用
+ * fileTreeHeaderButtonClass 里的同一份类名,不再各写一份
+ * - 状态用 `aria-pressed` + 按压底色表达;图标随状态在 EyeOff / Eye 间切换
+ * - 文案遵循 DESIGN.md §14.6:说**下一步动作**(显示 / 隐藏),tooltip 与
+ * aria-label 一起变
+ * - 被控端不支持时(device-link 连到老 Desktop,它的 listDir 静默忽略该字段):
+ * 控件呈现为不可用 + 说明原因,不装成"按下去就生效"的假开关
+ */
+
+import { useTranslation } from 'react-i18next';
+import { Eye, EyeOff } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Tip } from '@/components/ui/tooltip';
+import { useFileBrowserPreference } from '@/hooks/useFileBrowserPreference';
+import { FILE_TREE_HEADER_ICON_BUTTON_CLASS } from './fileTreeHeaderButtonClass';
+
+export interface FileTreeIgnoredDirsToggleProps {
+ /**
+ * 当前会话的被控端不支持 `showIgnoredDirs`(老 Desktop 的 listDir 会静默
+ * 忽略该字段)。由 `useFileTree` 的 `showIgnoredDirsSupported === false` 传入。
+ */
+ unsupported?: boolean;
+}
+
+export function FileTreeIgnoredDirsToggle({
+ unsupported = false,
+}: FileTreeIgnoredDirsToggleProps) {
+ const { t } = useTranslation();
+ const { showIgnoredDirs, setShowIgnoredDirs } = useFileBrowserPreference();
+
+ // 不支持的老被控端:按「关」呈现 —— 这个视图里确实不会显示被忽略目录(tree
+ // 也按隐藏态建的 store),同时 label 说明原因。压着不动的按下态比禁用更容易
+ // 被误读为“已经打开了”。
+ const pressed = !unsupported && showIgnoredDirs;
+
+ // §14.6:状态控件描述将要发生的动作。
+ const label = unsupported
+ ? t('ccAgent.workdirBrowse.treeAction.showIgnoredDirsUnsupported')
+ : t(
+ pressed
+ ? 'ccAgent.workdirBrowse.treeAction.hideIgnoredDirs'
+ : 'ccAgent.workdirBrowse.treeAction.showIgnoredDirs',
+ );
+
+ return (
+ <Tip text={label}>
+ <button
+ type="button"
+ aria-pressed={pressed}
+ aria-label={label}
+ // aria-disabled 而不走原生 disabled:原生 disabled 的按钮不派发鼠标事件,
+ // Radix tooltip 打不开 —— 用户就没有地方能看到“为什么不能按”。
+ aria-disabled={unsupported || undefined}
+ onClick={() => {
+ if (unsupported) return;
+ setShowIgnoredDirs(!showIgnoredDirs);
+ }}
+ className={cn(
+ FILE_TREE_HEADER_ICON_BUTTON_CLASS,
+ pressed && 'bg-sidebar-item-active text-sidebar-item-active-foreground',
+ unsupported && 'cursor-not-allowed opacity-45 hover:bg-transparent',
+ )}
+ >
+ {pressed ? (
+ <Eye size={14} strokeWidth={2} />
+ ) : (
+ <EyeOff size={14} strokeWidth={2} />
+ )}
+ </button>
+ </Tip>
+ );
+}
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx
index 59e81c5d9f..ee1f6e790b 100644
--- a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx
@@ -25,7 +25,7 @@ import { openHtmlFileByPreference } from '@/components/chat/useOpenWithMenu';
import { resolveSessionFileOrigin } from '@/lib/sessionFileOrigin';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router-dom';
-import { ArrowLeft, Check, ChevronDown, ChevronsDownUp, RefreshCw, Search, X as XIcon } from 'lucide-react';
+import { ArrowLeft, Check, ChevronDown } from 'lucide-react';
import { useTranslation } from 'react-i18next';
import { cn } from '@/lib/utils';
@@ -44,7 +44,9 @@ import { useFileTree, type DirEntry } from './hooks/useFileTree';
import { fileBrowserApiFor } from '@/lib/fileBrowserTransport';
import { useConfirmSwitchAwayIfDirty } from './hooks/useConfirmSwitchAwayIfDirty';
import { useProjectFileList } from './hooks/useProjectFileList';
+import { useFileBrowserPreference } from '@/hooks/useFileBrowserPreference';
import { FileTreeView, type FileTreeViewHandle, type PendingCreate } from './FileTreeView';
+import { FileTreeHeaderActions } from './FileTreeHeaderActions';
import { useRevealFileInTree } from './hooks/useRevealFileInTree';
import { FileFilterInput } from './FileFilterInput';
import { FilterResultList } from './FilterResultList';
@@ -214,7 +216,18 @@ export function WorkdirBrowseSidebar({
// 要递归扫一遍判断 "有没有 doc 文件"(即使 sibling 已经并行,顶层走完一轮
// 仍然有感知)。先放开让用户看全部文件,等 hasDocDescendant 加缓存或换成
// 流式增量返回再启用。scanner.ts 的过滤逻辑保留,改回 true 即可恢复。
- const tree = useFileTree({ workdir, remoteHostId, deviceId, hideMetaFiles: true, docMode: false });
+ //
+ // showIgnoredDirs 来自设置页「显示被忽略的目录」开关(默认关):打开后
+ // build / dist / out / node_modules 等被内置清单隐藏的目录会出现在树里。
+ const { showIgnoredDirs } = useFileBrowserPreference();
+ const tree = useFileTree({
+ workdir,
+ remoteHostId,
+ deviceId,
+ hideMetaFiles: true,
+ docMode: false,
+ showIgnoredDirs,
+ });
// 文件名筛选 query —— tree 模式下用,独立于内容搜索。空 query 显示文件树,有
// 内容显示筛选结果列表。workdir 切换时自动清空(下方 useEffect)。
@@ -595,8 +608,14 @@ export function WorkdirBrowseSidebar({
// 文件夹 rename:把 expanded 持久化里所有 oldRel / oldRel/* 的条目改前缀。
// 实时 expanded 集合不改 — 反正打开重命名后的新文件夹时会重新 fetch。
+ //
+ // scope 必须与 tree store **实际生效**的开关一致:device-link 被控端不支持
+ // 「显示被忽略的目录」时 useFileTree 会退回隐藏态 store;若这里仍按用户偏好
+ // 写 reveal scope,迁移就落在不生效的那一格 —— 当前隐藏 scope 仍存旧路径,
+ // 面板重挂载后会去请求已不存在的目录,新目录的展开态也丢了(评审 P2)。
if (entry.type === 'directory') {
- const persisted = loadExpandedSet(workdir);
+ const scopedShowIgnoredDirs = showIgnoredDirs && tree.showIgnoredDirsSupported !== false;
+ const persisted = loadExpandedSet(workdir, { showIgnoredDirs: scopedShowIgnoredDirs });
let dirty = false;
const next = new Set<string>();
for (const p of persisted) {
@@ -610,10 +629,19 @@ export function WorkdirBrowseSidebar({
next.add(p);
}
}
- if (dirty) saveExpandedSet(workdir, next);
+ if (dirty) saveExpandedSet(workdir, next, { showIgnoredDirs: scopedShowIgnoredDirs });
}
},
- [renamingPath, tree.entries, workdir, selectedPath, setSearchParams, t],
+ [
+ renamingPath,
+ tree.entries,
+ tree.showIgnoredDirsSupported,
+ workdir,
+ showIgnoredDirs,
+ selectedPath,
+ setSearchParams,
+ t,
+ ],
);
// 右键 文件 → Copy File Path。Electron renderer 启用了 clipboard write,
@@ -677,7 +705,7 @@ export function WorkdirBrowseSidebar({
type="button"
aria-label={t('ccAgent.workdirBrowse.switchProject')}
className={cn(
- 'flex min-w-0 items-center gap-1.5 rounded-md px-1.5 py-1 -ml-1.5',
+ 'flex min-w-0 items-center gap-1.5 rounded-full px-1.5 py-1 -ml-1.5',
'text-sm font-semibold text-foreground transition-colors',
'hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground',
'data-[state=open]:bg-sidebar-item-active data-[state=open]:text-sidebar-item-active-foreground',
@@ -718,49 +746,14 @@ export function WorkdirBrowseSidebar({
</span>
)}
<div className="flex shrink-0 items-center gap-1.5">
- {mode === 'search' ? (
- // search 是独立态: refresh / collapse 只对文件树有意义,搜索时不该出现。
- // 只保留 X = 退出搜索回到 tree 模式。
- <Tip text={t('ccAgent.workdirBrowse.searchPanel.exit')}>
- <button
- type="button"
- onClick={handleToggleSearchMode}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <XIcon size={14} strokeWidth={2} />
- </button>
- </Tip>
- ) : (
- <>
- <Tip text={t('ccAgent.workdirBrowse.searchPanel.searchFiles')}>
- <button
- type="button"
- onClick={handleToggleSearchMode}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <Search size={14} strokeWidth={2} />
- </button>
- </Tip>
- <Tip text={t('ccAgent.workdirBrowse.treeAction.collapseAll')}>
- <button
- type="button"
- onClick={handleCollapseAll}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <ChevronsDownUp size={14} strokeWidth={2} />
- </button>
- </Tip>
- <Tip text={t('ccAgent.workdirBrowse.treeAction.refresh')}>
- <button
- type="button"
- onClick={handleRefresh}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <RefreshCw size={14} strokeWidth={2} />
- </button>
- </Tip>
- </>
- )}
+ {/* 搜索 / 显示被忽略的目录 / 收起 / 刷新 —— 与 RSB 文件浏览器同一组件。 */}
+ <FileTreeHeaderActions
+ mode={mode}
+ onToggleSearch={handleToggleSearchMode}
+ onCollapseAll={handleCollapseAll}
+ onRefresh={handleRefresh}
+ ignoredDirsUnsupported={tree.showIgnoredDirsSupported === false}
+ />
</div>
</div>
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/__tests__/FileTreeIgnoredDirsToggle.test.tsx b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/__tests__/FileTreeIgnoredDirsToggle.test.tsx
new file mode 100644
index 0000000000..3637cff9c5
--- /dev/null
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/__tests__/FileTreeIgnoredDirsToggle.test.tsx
@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+
+/**
+ * FileTreeIgnoredDirsToggle — 文件树标题行的「显示被忽略的目录」开关。
+ *
+ * 锁的不变量:
+ * - 默认关:aria-pressed=false,文案说**下一步动作**(显示),与 DESIGN.md §14.6
+ * "stateful controls describe the action that will happen next" 一致;
+ * - 点击翻转偏好,并把 override 落进 localStorage(规则 20:改回默认即清除);
+ * - 按下状态有持久底色(不是只在 hover 时可见),否则用户无法判断当前是开是关;
+ * - 有 Tip(tooltip)与 aria-label 两个标签(§14.6 图标控件的交付合同)。
+ */
+
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import { FileTreeIgnoredDirsToggle } from '../FileTreeIgnoredDirsToggle';
+import { _resetFileBrowserPreferenceForTests } from '@/hooks/useFileBrowserPreference';
+
+const KEY = 'fileBrowser.showIgnoredDirs';
+const SHOW_LABEL = 'ccAgent.workdirBrowse.treeAction.showIgnoredDirs';
+const HIDE_LABEL = 'ccAgent.workdirBrowse.treeAction.hideIgnoredDirs';
+const UNSUPPORTED_LABEL = 'ccAgent.workdirBrowse.treeAction.showIgnoredDirsUnsupported';
+
+function button(): HTMLElement {
+ return screen.getByRole('button', { name: SHOW_LABEL });
+}
+
+describe('FileTreeIgnoredDirsToggle', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ _resetFileBrowserPreferenceForTests();
+ });
+
+ afterEach(() => cleanup());
+
+ it('默认关:aria-pressed=false,label 是「显示被忽略的目录」', () => {
+ render(<FileTreeIgnoredDirsToggle />);
+ expect(button().getAttribute('aria-pressed')).toBe('false');
+ expect(button().getAttribute('aria-label')).toBe(SHOW_LABEL);
+ });
+
+ it('点击打开:写 override、翻成 pressed、label 换成「隐藏」', () => {
+ render(<FileTreeIgnoredDirsToggle />);
+ fireEvent.click(button());
+
+ expect(localStorage.getItem(KEY)).toBe('true');
+ const pressed = screen.getByRole('button', { name: HIDE_LABEL });
+ expect(pressed.getAttribute('aria-pressed')).toBe('true');
+ });
+
+ it('再点一次回到默认:清除 override(不写默认值快照)', () => {
+ localStorage.setItem(KEY, 'true');
+ render(<FileTreeIgnoredDirsToggle />);
+ fireEvent.click(screen.getByRole('button', { name: HIDE_LABEL }));
+
+ expect(localStorage.getItem(KEY)).toBeNull();
+ expect(button().getAttribute('aria-pressed')).toBe('false');
+ });
+
+ it('按下态有持久底色;未按下只有 hover 底色', () => {
+ const { unmount } = render(<FileTreeIgnoredDirsToggle />);
+ expect(button().className).toContain('hover:bg-sidebar-item-active');
+ expect(button().className).not.toMatch(/(?:^|\s)bg-sidebar-item-active/);
+ unmount();
+
+ localStorage.setItem(KEY, 'true');
+ _resetFileBrowserPreferenceForTests();
+ render(<FileTreeIgnoredDirsToggle />);
+ expect(screen.getByRole('button', { name: HIDE_LABEL }).className).toMatch(
+ /(?:^|\s)bg-sidebar-item-active/,
+ );
+ });
+
+ /**
+ * 被控端不支持(device-link 连到老 Desktop,它的 listDir 会静默忽略
+ * showIgnoredDirs):开关不能装成"按下去就生效"。禁用 + 说明原因,并且点击
+ * 不改全局偏好。
+ */
+ describe('unsupported', () => {
+ it('压不下去:aria-disabled + pressed=false + 原因文案,点击不改偏好', () => {
+ render(<FileTreeIgnoredDirsToggle unsupported />);
+ const el = screen.getByRole('button', { name: UNSUPPORTED_LABEL });
+
+ expect(el.getAttribute('aria-disabled')).toBe('true');
+ expect(el.getAttribute('aria-pressed')).toBe('false');
+ expect(el.className).toContain('cursor-not-allowed');
+
+ fireEvent.click(el);
+ expect(localStorage.getItem(KEY)).toBeNull();
+ });
+
+ it('偏好已开启也按「关」展示(这个视图确实不会显示被忽略目录)', () => {
+ localStorage.setItem(KEY, 'true');
+ _resetFileBrowserPreferenceForTests();
+ render(<FileTreeIgnoredDirsToggle unsupported />);
+
+ const el = screen.getByRole('button', { name: UNSUPPORTED_LABEL });
+ expect(el.getAttribute('aria-pressed')).toBe('false');
+ // 全局偏好本身不被改写 —— 切回本地会话仍然是开着的。
+ expect(localStorage.getItem(KEY)).toBe('true');
+ });
+ });
+});
+
+/**
+ * 接线守卫:开关必须出现在**每个**文件树宿主的标题行里,且与
+ * 「搜索 / 收起 / 刷新」并列(文本顺序在搜索之后、收起之前) —— 用户就是在这
+ * 里发现目录被隐藏的,偏好不能只能从设置页改。
+ *
+ * 只断言「每个宿主文件内存在」与相对位置,不断言总调用点个数(计数式断言会把
+ * 「必须重复」写成不变量,见 DESIGN.md §14 的守卫元规则)。
+ *
+ * 2026-09 重构后两个宿主共用 FileTreeHeaderActions(此前各自复制一份,加开关时
+ * 出现了两种圆角)。守卫因此分两层:
+ * 1. 每个宿主确实挂了共享动作组;
+ * 2. 共享动作组里开关存在、位置正确,且几何与可访问名只有一份实现。
+ */
+describe('FileTreeIgnoredDirsToggle 接线', () => {
+ const hosts = [
+ ['RSB 文件浏览器', ['features', 'right-sidebar', 'plugins', 'file-browser', 'FileBrowserBody.tsx']],
+ ['doc 模式侧栏', ['features', 'cc-agent', 'workdir-browse', 'WorkdirBrowseSidebar.tsx']],
+ ] as const;
+ const sharedActions = [
+ 'features',
+ 'cc-agent',
+ 'workdir-browse',
+ 'FileTreeHeaderActions.tsx',
+ ] as const;
+
+ function readSource(segments: readonly string[]): string {
+ return readFileSync(resolve(__dirname, '..', '..', '..', '..', ...segments), 'utf8');
+ }
+
+ it.each(hosts)('%s 的标题行挂着共享动作组', (_name, segments) => {
+ expect(readSource(segments)).toContain('<FileTreeHeaderActions');
+ });
+
+ it('共享动作组里开关紧跟搜索按钮、先于收起按钮', () => {
+ const source = readSource(sharedActions);
+ const toggleAt = source.indexOf('<FileTreeIgnoredDirsToggle');
+ const searchAt = source.indexOf("'ccAgent.workdirBrowse.searchPanel.searchFiles'");
+ const collapseAt = source.indexOf("'ccAgent.workdirBrowse.treeAction.collapseAll'");
+
+ expect(toggleAt).toBeGreaterThan(-1);
+ expect(searchAt).toBeGreaterThan(-1);
+ expect(collapseAt).toBeGreaterThan(-1);
+ expect(toggleAt).toBeGreaterThan(searchAt);
+ expect(toggleAt).toBeLessThan(collapseAt);
+ });
+
+ /**
+ * 几何守卫:这行里的每个图标钮都拿共享常量,不各自写圆角。
+ *
+ * 起因:开关最初只给自己写了 pill,三个存量按钮各自写 `rounded-md`(6px),
+ * 同一行就出现两种圆角。抽成共享动作组后,宿主里不应再出现自写的图标钮。
+ */
+ it('共享动作组的图标钮全部走共享类名常量', () => {
+ expect(readSource(sharedActions)).toContain('FILE_TREE_HEADER_ICON_BUTTON_CLASS');
+ });
+
+ it.each(hosts)('%s 不再自己写标题行图标钮', (_name, segments) => {
+ expect(readSource(segments)).not.toMatch(
+ /className="flex size-5 items-center justify-center rounded-/,
+ );
+ });
+
+ /**
+ * 可访问名守卫(DESIGN.md §14.6):纯图标控件的交付合同是**可见 Tip + 本地化
+ * 可访问名**。共享动作组的按钮由 HeaderIconButton 统一产出,两个标签同源。
+ */
+ it('共享动作组的图标钮都带本地化 aria-label', () => {
+ const source = readSource(sharedActions);
+ const buttons = source
+ .split('<button')
+ .slice(1)
+ .filter((block) => block.includes('FILE_TREE_HEADER_ICON_BUTTON_CLASS'));
+
+ expect(buttons.length).toBeGreaterThan(0);
+ for (const block of buttons) {
+ expect(block.slice(0, block.indexOf('className'))).toContain('aria-label');
+ }
+ });
+});
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/fileTreeHeaderButtonClass.ts b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/fileTreeHeaderButtonClass.ts
new file mode 100644
index 0000000000..b501f80968
--- /dev/null
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/fileTreeHeaderButtonClass.ts
@@ -0,0 +1,19 @@
+/**
+ * 文件树标题行图标钮的统一类名。
+ *
+ * 一行里的动作按钮 —— 搜索 / 显示被忽略的目录 / 收起 / 刷新,外加搜索态的 X ——
+ * 共用这一份定义。两个宿主(RSB 文件浏览器 FileBrowserBody 的 TreeHeader、
+ * doc 模式侧栏 WorkdirBrowseSidebar)以前各自复制了一行类名,新增「显示被忽略的
+ * 目录」时新按钮走 pill、三个旧按钮还是 6px,同一行就出现了两种圆角。
+ *
+ * 为什么是 pill(DESIGN.md §5):控件框(含 transient hover / pressed 表面)登记在
+ * Step 2 的 pill 档;6px 不在受治理取值里(`No 3px / 6px / 10px`)。抽成常量后
+ * 后续新按钮只能拿到同一个值,不会再各写一份。
+ *
+ * focus-visible 环必须自己带:G3 全局规则(globals.css)把非输入元素的 outline
+ * 一律去掉了(Chromium 默认环在 Esc/点击后跳焦时会闪橙色),所以不显式补环的
+ * 纯图标钮在键盘 Tab 时没有任何可见焦点指示 —— 包括新增的「显示被忽略的目录」
+ * 开关(评审 P1)。
+ */
+export const FILE_TREE_HEADER_ICON_BUTTON_CLASS =
+ 'flex size-5 items-center justify-center rounded-full text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]';
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/__tests__/useFileTree.test.tsx b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/__tests__/useFileTree.test.tsx
index f4f4af2c24..ea4dc50a61 100644
--- a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/__tests__/useFileTree.test.tsx
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/__tests__/useFileTree.test.tsx
@@ -16,7 +16,14 @@ const mocks = vi.hoisted(() => {
fileBrowserApiFor: vi.fn(),
isDeviceTooOldError: vi.fn(() => false),
listDir: vi.fn(),
- loadExpandedSet: vi.fn(() => new Set<string>()),
+ loadExpandedSet: vi.fn(
+ (_workdir: string, _opts?: { showIgnoredDirs?: boolean }) => new Set<string>(),
+ ),
+ deviceSupportsRevealIgnoredDirs: vi.fn(
+ async (): Promise<boolean | null> => true,
+ ),
+ /** 重连代次:测试里改这个值 + rerender 就能驱动重探。 */
+ reconnectEpoch: { current: 0 },
onFileTreeEventFor: vi.fn(
(_deviceId: string | null | undefined, cb: (event: FileTreeEvent) => void) => {
eventCallbacks.push(cb);
@@ -33,6 +40,7 @@ const mocks = vi.hoisted(() => {
});
vi.mock('@/lib/fileBrowserTransport', () => ({
+ deviceSupportsRevealIgnoredDirs: mocks.deviceSupportsRevealIgnoredDirs,
fileBrowserApiFor: mocks.fileBrowserApiFor,
isDeviceTooOldError: mocks.isDeviceTooOldError,
onFileTreeEventFor: mocks.onFileTreeEventFor,
@@ -44,6 +52,11 @@ vi.mock('@/lib/logger', () => ({
createLogger: () => ({ warn: vi.fn() }),
}));
+// jsdom 里没有 window.electronAPI,真实 hook 会去订阅 presence —— 用可变代次替身。
+vi.mock('@/features/device-link/useDeviceLinkReconnectEpoch', () => ({
+ useDeviceLinkReconnectEpoch: () => mocks.reconnectEpoch.current,
+}));
+
vi.mock('../../lib/expandedStore', () => ({
loadExpandedSet: mocks.loadExpandedSet,
saveExpandedSet: mocks.saveExpandedSet,
@@ -64,6 +77,8 @@ describe('useFileTree refresh scheduling', () => {
vi.clearAllMocks();
mocks.eventCallbacks.length = 0;
mocks.fileBrowserApiFor.mockReturnValue({ listDir: mocks.listDir });
+ // clearAllMocks 不重置实现:用例自设的 loadExpandedSet 行为要在每个用例前复位。
+ mocks.loadExpandedSet.mockImplementation(() => new Set<string>());
});
it('limits a directory refresh to one trailing scan during a watcher storm', async () => {
@@ -115,3 +130,981 @@ describe('useFileTree refresh scheduling', () => {
view.unmount();
});
});
+
+/**
+ * 「显示被忽略的目录」开关:作为 store key 的一部分,不同取值必须拿到各自
+ * 的 store 与 listDir / watch 参数,不能互相污染。
+ */
+describe('useFileTree showIgnoredDirs option', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.eventCallbacks.length = 0;
+ mocks.listDir.mockResolvedValue([]);
+ mocks.fileBrowserApiFor.mockReturnValue({ listDir: mocks.listDir });
+ // clearAllMocks 不重置实现:用例自设的 loadExpandedSet 行为要在每个用例前复位。
+ mocks.loadExpandedSet.mockImplementation(() => new Set<string>());
+ });
+
+ it('listDir / startWatch 带上开关值', async () => {
+ const view = renderHook(() =>
+ useFileTree({ workdir: '/workdir-reveal', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ expect(mocks.listDir).toHaveBeenCalledWith(
+ expect.objectContaining({ workdir: '/workdir-reveal', showIgnoredDirs: true }),
+ );
+ expect(mocks.startWatchFor).toHaveBeenCalledWith(
+ null,
+ expect.objectContaining({ workdir: '/workdir-reveal', showIgnoredDirs: true }),
+ );
+ view.unmount();
+ });
+
+ it('开关不同 = 两份独立 store(互不共用 entries)', async () => {
+ const hidden = renderHook(() => useFileTree({ workdir: '/workdir-split' }));
+ const revealed = renderHook(() =>
+ useFileTree({ workdir: '/workdir-split', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(hidden.result.current.initialLoading).toBe(false));
+ await waitFor(() => expect(revealed.result.current.initialLoading).toBe(false));
+ // 两个 store 各自拉了一次根目录。
+ expect(mocks.listDir).toHaveBeenCalledTimes(2);
+ expect(
+ mocks.listDir.mock.calls.map((c) => c[0].showIgnoredDirs),
+ ).toEqual([false, true]);
+ hidden.unmount();
+ revealed.unmount();
+ });
+
+ /**
+ * 展开态持久化同样按开关分片:否则放行态展开过 node_modules / Library 后切回
+ * 隐藏态,init 会把它们当"已展开"并行 listDir(评审 P2)。
+ */
+ it('expanded 持久化按开关分片读取', async () => {
+ const hidden = renderHook(() => useFileTree({ workdir: '/workdir-scope' }));
+ await waitFor(() => expect(hidden.result.current.initialLoading).toBe(false));
+ expect(mocks.loadExpandedSet).toHaveBeenCalledWith('/workdir-scope', {
+ showIgnoredDirs: false,
+ });
+ hidden.unmount();
+
+ const revealed = renderHook(() =>
+ useFileTree({ workdir: '/workdir-scope', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(revealed.result.current.initialLoading).toBe(false));
+ expect(mocks.loadExpandedSet).toHaveBeenCalledWith('/workdir-scope', {
+ showIgnoredDirs: true,
+ });
+ revealed.unmount();
+ });
+
+ /**
+ * 切开关会换一份 store。新 store 若从空快照 + initialLoading 起步,FileTreeView
+ * 会把整树替换成空白占位(本地 <300ms 连 spinner 都没有),视觉上闪一下;
+ * 「刷新」按钮原地 refetch 所以不闪。新 store 必须继承兄弟 store 的整棵可见树,
+ * 等新 matcher 的数据回来再整体替换(不是只借根列表,见下一条)。
+ */
+ it('切开关继承整棵可见树,不回到 initialLoading 空白', async () => {
+ const hiddenEntries: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedEntries: readonly DirEntry[] = [
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ // 切开关后钩住新 matcher 的 listDir:验证“数据还没回来”的那一帧。
+ const pending = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) =>
+ args.showIgnoredDirs ? pending.promise : Promise.resolve(hiddenEntries),
+ );
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ expect(view.result.current.entries.get('')).toEqual(hiddenEntries);
+
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ // 新 matcher 的数据尚未回来:这一帧就该有 seed 的旧树且不在 loading。
+ expect(view.result.current.initialLoading).toBe(false);
+ expect(view.result.current.entries.get('')).toEqual(hiddenEntries);
+
+ await act(async () => {
+ pending.resolve(revealedEntries);
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(view.result.current.entries.get('')).toEqual(revealedEntries));
+
+ view.unmount();
+ });
+
+ /**
+ * 关开关的首帧就要滤掉内置忽略目录:慢通道下不能等新 matcher 的数据回来,
+ * 否则「开关关了却还看得见 node_modules」会持续数秒。子树缓存与展开集合不
+ * 动(父行不在根列表里 → 整棵子树同帧不可达,与「一次性消失」一致)。
+ */
+ it('关开关首帧就滤掉被忽略目录,不等新数据', async () => {
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ // 大小写变体:matcher 的 ignorecase 默认让 BUILD 与 build 同义,首帧也该滤掉。
+ { name: 'BUILD', relPath: 'BUILD', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'README.md', relPath: 'README.md', type: 'file', size: 10, mtimeMs: 1 },
+ ];
+ const pendingRoot = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) =>
+ args.showIgnoredDirs ? Promise.resolve(revealedRoot) : pendingRoot.promise,
+ );
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-filter', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+
+ // 数据还没回来,但被忽略目录已不在根列表;其余行照旧。
+ expect(view.result.current.entries.get('')?.map((e) => e.name)).toEqual(['src', 'README.md']);
+
+ view.unmount();
+ });
+
+ /**
+ * 关开关的消失动作必须是一次性的:过渡期(hidden 数据还没回来)树保持不动
+ * —— 展开态与子树缓存都还在 —— 而不是先丢子行再丢父行(那是「从最子级逐级
+ * 折叠」);被忽略的一级目录行由首帧过滤直接拿掉(见上一条),剩下的部分等
+ * root 数据回来整体替换,并把借来的 reveal-only 展开位剪掉:hidden 树下
+ * node_modules 已不在 root 列表里,留着会随下次操作写进 hidden scope 的
+ * localStorage,下次启动白发一批 listDir。
+ */
+ it('关开关整树保持到数据回来,再一次性替换并剪掉 reveal-only 展开位', async () => {
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedChild: readonly DirEntry[] = [
+ { name: 'pkg', relPath: 'node_modules/pkg', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (args.showIgnoredDirs) {
+ return Promise.resolve(args.relPath === 'node_modules' ? revealedChild : revealedRoot);
+ }
+ return Promise.resolve(hiddenRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-swap', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules');
+ });
+ expect(view.result.current.expanded.has('node_modules')).toBe(true);
+
+ // 过渡期:挂住 hidden 侧的 root listDir,模拟慢通道。
+ const pendingRoot = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) => {
+ if (args.showIgnoredDirs) return Promise.resolve(revealedRoot);
+ return pendingRoot.promise;
+ });
+ mocks.listDir.mockClear();
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+
+ // 数据还没回来:被忽略行已由首帧过滤拿掉,它的整棵缓存与展开位也一起剪掉
+ // (缓存留着会被 refresh() 按 entries key 重扫;展开位留着会被过渡窗口里的
+ // 操作写进本 scope 的 localStorage);树的其余部分保持不动 —— 不重新挂载、
+ // 不逐级折叠。
+ expect(view.result.current.initialLoading).toBe(false);
+ expect(view.result.current.entries.get('')?.map((e) => e.name)).toEqual(['src']);
+ expect(view.result.current.entries.has('node_modules')).toBe(false);
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+ // 过渡期不 warm 借来的子树 —— 不给被忽略路径白发 listDir。
+ const hiddenCalls = mocks.listDir.mock.calls.filter((c) => c[0].showIgnoredDirs === false);
+ expect(hiddenCalls.map((c) => c[0].relPath)).toEqual(['']);
+
+ await act(async () => {
+ pendingRoot.resolve(hiddenRoot);
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(view.result.current.entries.get('')).toEqual(hiddenRoot));
+ // 整体替换完成:借来的 reveal-only 展开位被剪掉。
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P1(PR #4398 轮七):创建 store 时借的是另一半 scope 的过渡快照,而剪枝
+ * 会**同步回写本 scope 的 localStorage** —— 剪之前必须先读本 scope 自己的持久
+ * 记录并豁免它,否则切回隐藏态时用户原有(本 scope)的展开位会被一起抹掉。
+ */
+ it('切回隐藏态时保留本 scope 已持久化的展开位', async () => {
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'docs', relPath: 'docs', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const hiddenRoot = revealedRoot.filter((entry) => entry.name !== 'node_modules');
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) =>
+ Promise.resolve(args.showIgnoredDirs ? revealedRoot : hiddenRoot),
+ );
+ // 上一次会话里 hidden scope 自己存过展开位:docs。
+ mocks.loadExpandedSet.mockImplementation(
+ (_workdir: string, opts?: { showIgnoredDirs?: boolean }) =>
+ opts?.showIgnoredDirs ? new Set<string>() : new Set(['docs']),
+ );
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-scope-keep', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules');
+ });
+ expect(view.result.current.expanded.has('node_modules')).toBe(true);
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+
+ // 剪枝回写必须保留本 scope 既有的 'docs',同时仍然剪掉借来的 node_modules。
+ const hiddenWrites = mocks.saveExpandedSet.mock.calls
+ .filter((call) => (call[2] as { showIgnoredDirs?: boolean } | undefined)?.showIgnoredDirs === false)
+ .map((call) => call[1] as Set<string>);
+ expect(hiddenWrites.length).toBeGreaterThan(0);
+ const lastWrite = hiddenWrites.at(-1)!;
+ expect(lastWrite.has('docs')).toBe(true);
+ expect(lastWrite.has('node_modules')).toBe(false);
+
+ // 内存里也保留:切回后 docs 仍是展开态。
+ expect(view.result.current.expanded.has('docs')).toBe(true);
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P1(PR #4398 轮七)的另一半:反向切到放行态时,seed 是**隐藏态**的树
+ * (本来就看不到被忽略目录),不能拿它判断放行态自己的展开位不可达 —— `keep`
+ * 必须豁免本 scope 的持久记录,否则用户在放行态展开的 node_modules 会在切回时
+ * 被剪掉。
+ */
+ it('切到放行态时保留本 scope 已持久化的展开位(借来的隐藏树判不了它)', async () => {
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedRoot: readonly DirEntry[] = [
+ ...hiddenRoot,
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 2 },
+ ];
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) =>
+ Promise.resolve(args.showIgnoredDirs ? revealedRoot : hiddenRoot),
+ );
+ // 放行态 scope 上次会话存过 node_modules 展开位。
+ mocks.loadExpandedSet.mockImplementation(
+ (_workdir: string, opts?: { showIgnoredDirs?: boolean }) =>
+ opts?.showIgnoredDirs ? new Set(['node_modules']) : new Set<string>(),
+ );
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-scope-keep-reveal', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+
+ // 借来的隐藏树里没有 node_modules,不能因此把放行态自己的展开位剪掉:
+ // 要么没回写,要么回写里必须带着它。
+ const revealWrites = mocks.saveExpandedSet.mock.calls
+ .filter((call) => (call[2] as { showIgnoredDirs?: boolean } | undefined)?.showIgnoredDirs === true)
+ .map((call) => call[1] as Set<string>);
+ expect(revealWrites.every((set) => set.has('node_modules'))).toBe(true);
+ expect(view.result.current.expanded.has('node_modules')).toBe(true);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审(切开关丢失展开记录):seed 窗口内 root 先回、子目录列表还是兄弟 scope
+ * 借来的(借来的 `packages` 列表没有 node_modules)。此时收尾剪枝不得用借来的
+ * 列表否定本 scope 自己持久化的 `packages/node_modules` 展开位 —— 否则它被剪掉
+ * 并覆盖 localStorage,之后子目录响应只更新列表、不会恢复展开位。
+ */
+ it('seed 窗口 root 先回、子目录还是借来的列表时,保留本 scope 自己的展开位', async () => {
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'packages', relPath: 'packages', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const hiddenPackages: readonly DirEntry[] = [];
+ const revealedRoot = hiddenRoot;
+ const revealedPackages: readonly DirEntry[] = [
+ {
+ name: 'node_modules',
+ relPath: 'packages/node_modules',
+ type: 'directory',
+ size: 0,
+ mtimeMs: 2,
+ },
+ ];
+ // 放行态 scope 上次会话存过 packages/node_modules 展开位。
+ mocks.loadExpandedSet.mockImplementation(
+ (_workdir: string, opts?: { showIgnoredDirs?: boolean }) =>
+ opts?.showIgnoredDirs ? new Set(['packages/node_modules']) : new Set<string>(),
+ );
+ // 挂住放行态的首次 root listDir(模拟 root 先于子目录数据就绪的窗口)。
+ const pendingRevealRoot = deferred<readonly DirEntry[]>();
+ let revealRootCalls = 0;
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) {
+ return Promise.resolve((args.relPath ?? '') === '' ? hiddenRoot : hiddenPackages);
+ }
+ if ((args.relPath ?? '') === '') {
+ revealRootCalls += 1;
+ return revealRootCalls === 1
+ ? pendingRevealRoot.promise
+ : Promise.resolve(revealedRoot);
+ }
+ return Promise.resolve(revealedPackages);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-root-first', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ // seed 窗口内:创建时 creation prune 已用 keep 保住本 scope 的展开位。
+ expect(view.result.current.expanded.has('packages/node_modules')).toBe(true);
+
+ // root 这才返回(此时 entries 里的 packages 列表仍是借来的空列表)。
+ await act(async () => {
+ pendingRevealRoot.resolve(revealedRoot);
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(view.result.current.entries.get('')).toEqual(revealedRoot));
+
+ // 借来的 packages 列表缺 node_modules ≠ 本 scope 的展开位过期:不得剪掉、
+ // 不得覆盖持久记录。
+ expect(view.result.current.expanded.has('packages/node_modules')).toBe(true);
+ const revealWrites = mocks.saveExpandedSet.mock.calls
+ .filter(
+ (call) =>
+ (call[2] as { showIgnoredDirs?: boolean } | undefined)?.showIgnoredDirs === true,
+ )
+ .map((call) => call[1] as Set<string>);
+ // 修好后的行为:借来的列表没有可剪的东西 → prune 早退、可能零回写;
+ // 旧代码会剪掉并回写一份不含它的记录 —— 两种情况下这条都必须成立。
+ expect(revealWrites.every((set) => set.has('packages/node_modules'))).toBe(true);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P1:被忽略目录嵌在已展开的普通目录下时(`packages/foo/node_modules`),
+ * 只滤根列表的实现会把它一直留在展开的父目录下 —— 而且 prune 拿过期的 reveal
+ * 子列表判可达性,会把它保留到手动刷新。逐列表过滤后:首帧就不渲染它,prune 也
+ * 按新判据把它从展开集合里剪掉,同时不重拉任何目录。
+ */
+ it('关开关首帧滤掉展开父目录下的嵌套被忽略目录,prune 不再把它当可达', async () => {
+ const dir = (name: string, relPath: string): DirEntry => ({
+ name,
+ relPath,
+ type: 'directory',
+ size: 0,
+ mtimeMs: 1,
+ });
+ const revealedRoot = [dir('packages', 'packages')];
+ const revealedPackages = [dir('foo', 'packages/foo'), dir('node_modules', 'packages/node_modules')];
+ const revealedFoo = [dir('src', 'packages/foo/src'), dir('node_modules', 'packages/foo/node_modules')];
+
+ const pendingRoot = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) return pendingRoot.promise;
+ if (args.relPath === 'packages') return Promise.resolve(revealedPackages);
+ if (args.relPath === 'packages/foo') return Promise.resolve(revealedFoo);
+ return Promise.resolve(revealedRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-nested-filter', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('packages');
+ });
+ await waitFor(() => expect(view.result.current.entries.get('packages')).toBeDefined());
+ await act(async () => {
+ view.result.current.toggleFolder('packages/foo');
+ });
+ await waitFor(() => expect(view.result.current.entries.get('packages/foo')).toBeDefined());
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+
+ // 首帧:两层列表里的 node_modules 行都不再渲染。
+ expect(view.result.current.entries.get('packages')?.map((e) => e.name)).toEqual(['foo']);
+ expect(view.result.current.entries.get('packages/foo')?.map((e) => e.name)).toEqual(['src']);
+
+ // root 数据回来后:prune 按过滤后的父列表判可达性,剪掉折叠位。
+ await act(async () => {
+ pendingRoot.resolve(revealedRoot);
+ await Promise.resolve();
+ });
+ expect(view.result.current.expanded.has('packages/node_modules')).toBe(false);
+ expect(view.result.current.expanded.has('packages/foo/node_modules')).toBe(false);
+ expect(view.result.current.expanded.has('packages/foo')).toBe(true);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P2:反方向(hidden → reveal)不能只靠过滤 —— hidden 态的数据**缺**了被
+ * 忽略目录,不重拉的话开了开关也看不到 node_modules / build,一直到手动刷新。
+ * 所以继承来的展开父目录要按新 matcher 重拉一遍。
+ */
+ it('开开关时重拉继承的展开父目录,让嵌套被忽略目录显示出来', async () => {
+ const dir = (name: string, relPath: string): DirEntry => ({
+ name,
+ relPath,
+ type: 'directory',
+ size: 0,
+ mtimeMs: 1,
+ });
+ const hiddenRoot: readonly DirEntry[] = [dir('packages', 'packages')];
+ const hiddenChild = [dir('foo', 'packages/foo')];
+ const revealedChild = [
+ dir('foo', 'packages/foo'),
+ dir('node_modules', 'packages/node_modules'),
+ ];
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) {
+ return Promise.resolve(args.relPath === 'packages' ? hiddenChild : hiddenRoot);
+ }
+ return Promise.resolve(args.relPath === 'packages' ? revealedChild : hiddenRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-reveal-refetch', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('packages');
+ });
+ await waitFor(() => expect(view.result.current.entries.get('packages')).toEqual(hiddenChild));
+
+ mocks.listDir.mockClear();
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ await waitFor(() =>
+ expect(view.result.current.entries.get('packages')).toEqual(revealedChild),
+ );
+ // 重拉的确实是那个继承来的展开父目录。
+ expect(mocks.listDir).toHaveBeenCalledWith(
+ expect.objectContaining({ relPath: 'packages', showIgnoredDirs: true }),
+ );
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P1:只过滤行、不丢缓存会让隐藏态的下一次 refresh() 重扫它们 —— refresh
+ * 按 entries 的 key 逐个 listDir,node_modules 子树可能有数百个 key(SSH /
+ * device-link 上就是数百条 RPC)。
+ */
+ it('关开关丢弃被移除目录的缓存子树,refresh 不再重扫它们', async () => {
+ const dir = (name: string, relPath: string): DirEntry => ({
+ name,
+ relPath,
+ type: 'directory',
+ size: 0,
+ mtimeMs: 1,
+ });
+ const revealedRoot = [dir('src', 'src'), dir('node_modules', 'node_modules')];
+ const revealedNodeModules = [dir('pkg', 'node_modules/pkg')];
+ const revealedPkg = [dir('deep', 'node_modules/pkg/deep')];
+
+ const hiddenRoot: readonly DirEntry[] = [dir('src', 'src')];
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) return Promise.resolve(hiddenRoot);
+ if (args.relPath === 'node_modules') return Promise.resolve(revealedNodeModules);
+ if (args.relPath === 'node_modules/pkg') return Promise.resolve(revealedPkg);
+ return Promise.resolve(revealedRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-drop-cache', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules');
+ });
+ await waitFor(() => expect(view.result.current.entries.has('node_modules')).toBe(true));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules/pkg');
+ });
+ await waitFor(() => expect(view.result.current.entries.has('node_modules/pkg')).toBe(true));
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+
+ // 整棵缓存都丢,不只是父列表里那一行。
+ expect(view.result.current.entries.has('node_modules')).toBe(false);
+ expect(view.result.current.entries.has('node_modules/pkg')).toBe(false);
+
+ // 刷新只会扫仍然可达的 key。
+ mocks.listDir.mockClear();
+ await act(async () => {
+ await view.result.current.refresh();
+ });
+ const rescanned = mocks.listDir.mock.calls
+ .map((c) => c[0].relPath as string)
+ .filter((p) => p === 'node_modules' || p.startsWith('node_modules/'));
+ expect(rescanned).toEqual([]);
+ expect(mocks.listDir).toHaveBeenCalledWith(expect.objectContaining({ relPath: '' }));
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P2(延续):进入隐藏态时就把继承的 reveal-only 展开位剪掉,所以过渡窗口
+ * 里的任何操作写下的集合都是干净的 —— 不再依赖「root 回来时回写」兜底(根请求
+ * 失败时那条路径根本不执行)。
+ */
+ it('过渡窗口操作目录也不会把 reveal-only 展开位写进隐藏 scope', async () => {
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedChild: readonly DirEntry[] = [
+ { name: 'pkg', relPath: 'node_modules/pkg', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+
+ const pendingRoot = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) {
+ // 隐藏态的 root 故意挂起(慢通道),src 立刻返回避免测试悬空。
+ return args.relPath === 'src' ? Promise.resolve([]) : pendingRoot.promise;
+ }
+ if (args.relPath === 'node_modules') return Promise.resolve(revealedChild);
+ return Promise.resolve(revealedRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-persist-prune', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules');
+ });
+ await waitFor(() => expect(view.result.current.expanded.has('node_modules')).toBe(true));
+
+ // 切到隐藏态:root 挂起,处于过渡窗口;创建时就已剪掉继承来的展开位。
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+
+ // 过渡窗口里操作普通目录 —— 写进隐藏 scope 的集合必须是干净的(旧实现会把
+ // 继承来的 node_modules 一并写进去,之后只能靠 root 回来时的回写兜底)。
+ mocks.saveExpandedSet.mockClear();
+ await act(async () => {
+ view.result.current.toggleFolder('src');
+ });
+
+ // root 数据回来也不该改变这个结论。
+ await act(async () => {
+ pendingRoot.resolve(hiddenRoot);
+ await Promise.resolve();
+ });
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+
+ const persistedHidden = mocks.saveExpandedSet.mock.calls
+ .filter((c) => c[2]?.showIgnoredDirs === false)
+ .map((c) => c[1] as Set<string>)
+ .at(-1);
+ expect(persistedHidden?.has('node_modules')).toBe(false);
+ expect(persistedHidden?.has('src')).toBe(true);
+
+ view.unmount();
+ });
+
+ /**
+ * 评审 P2:根请求**失败**时剪枝那条路径根本不会执行(它挂在 fetch 成功分支上),
+ * 而继承来的 reveal-only 展开位仍会随用户操作写进本 scope 的 localStorage。
+ * 所以创建 store 时就要按(可能已过滤的)继承树剪一次。
+ */
+ it('创建隐藏 store 时即剪掉继承的 reveal-only 展开位(根请求失败也不残留)', async () => {
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedChild: readonly DirEntry[] = [
+ { name: 'pkg', relPath: 'node_modules/pkg', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+
+ // 隐藏态的 listDir 全部失败(模拟根请求失败:剪枝没有第二次机会)。
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (!args.showIgnoredDirs) return Promise.reject(new Error('boom'));
+ if (args.relPath === 'node_modules') return Promise.resolve(revealedChild);
+ return Promise.resolve(revealedRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-create-prune', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ await act(async () => {
+ view.result.current.toggleFolder('node_modules');
+ });
+ await waitFor(() => expect(view.result.current.expanded.has('node_modules')).toBe(true));
+
+ mocks.saveExpandedSet.mockClear();
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+ await waitFor(() => expect(view.result.current.loadError).toBe('load-failed'));
+
+ // 即使根请求失败:隐藏 scope 已经写入了剪枝后的集合,且不含 node_modules。
+ const persistedHidden = mocks.saveExpandedSet.mock.calls
+ .filter((c) => c[2]?.showIgnoredDirs === false)
+ .map((c) => c[1] as Set<string>)
+ .at(-1);
+ expect(persistedHidden).toBeDefined();
+ expect(persistedHidden?.has('node_modules')).toBe(false);
+ expect(view.result.current.expanded.has('node_modules')).toBe(false);
+
+ view.unmount();
+ });
+
+ it('根请求失败后 refresh 仍会重新请求根目录', async () => {
+ // 根失败会清空 entries(含根键);只遍历现有键的 refresh 就永远不会重试根,
+ // 连接恢复后点「重试 / 刷新」也没用。
+ let failRoot = true;
+ mocks.listDir.mockImplementation((args: { relPath?: string }) => {
+ if (failRoot && (args.relPath ?? '') === '') return Promise.reject(new Error('boom'));
+ return Promise.resolve([]);
+ });
+
+ const view = renderHook(() => useFileTree({ workdir: '/workdir-retry-root' }));
+ await waitFor(() => expect(view.result.current.loadError).toBe('load-failed'));
+ expect(view.result.current.entries.size).toBe(0);
+
+ failRoot = false;
+ mocks.listDir.mockClear();
+ await act(async () => {
+ await view.result.current.refresh();
+ });
+
+ expect(mocks.listDir).toHaveBeenCalledWith(expect.objectContaining({ relPath: '' }));
+ await waitFor(() => expect(view.result.current.loadError).toBeNull());
+ view.unmount();
+ });
+
+ /**
+ * 评审 P2:切开关后新 matcher 的根请求失败时,seed 借来的树**不代表当前视图**
+ * —— 留着它会让「开关已按下 + 树还是隐藏态旧数据」在 UI 上看起来像加载成功
+ * (错误占位只在 entries 为空时显示)。失败要可见、可重试。
+ */
+ it('切开关后根请求失败:清掉借来的旧树让错误可见', async () => {
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (args.showIgnoredDirs) return Promise.reject(new Error('boom')); // reveal 侧全失败
+ if (args.relPath) return Promise.resolve([]);
+ return Promise.resolve(hiddenRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-fail', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ // 切到 reveal:先借隐藏态的树(首帧仍有旧数据),随后根请求失败。
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ await waitFor(() => expect(view.result.current.loadError).toBe('load-failed'));
+ // 借来的旧树被清掉 → 走错误占位,而不是把旧数据当新视图。
+ expect(view.result.current.entries.size).toBe(0);
+ expect(view.result.current.initialLoading).toBe(false);
+ view.unmount();
+ });
+
+ /**
+ * 评审 P1:切开关后根请求**成功**落地就该结束「借来的树」标记 —— 否则之后任何
+ * 一次根刷新失败(SSH / device-link 瞬时中断)都会把已属于本 scope 的树当成
+ * 借来的清掉,丢掉最后一次成功的树。
+ */
+ it('切开关成功落地后再失败:保留已属于本 scope 的树', async () => {
+ const hiddenRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ const revealedRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ { name: 'node_modules', relPath: 'node_modules', type: 'directory', size: 0, mtimeMs: 2 },
+ ];
+ let failRevealRoot = false;
+ mocks.listDir.mockImplementation((args: { relPath?: string; showIgnoredDirs?: boolean }) => {
+ if (args.showIgnoredDirs) {
+ if (failRevealRoot && !args.relPath) return Promise.reject(new Error('boom'));
+ if (args.relPath) return Promise.resolve([]);
+ return Promise.resolve(revealedRoot);
+ }
+ if (args.relPath) return Promise.resolve([]);
+ return Promise.resolve(hiddenRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-clear', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ // 切 reveal:根请求成功 → 「借来的树」标记到此结束。
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ await waitFor(() => expect(view.result.current.entries.get('')).toHaveLength(2));
+
+ // 之后的根刷新失败:entries 已属于本 scope,应保留而不是清空。
+ failRevealRoot = true;
+ await act(async () => {
+ await view.result.current.refresh();
+ });
+ await waitFor(() => expect(view.result.current.loadError).toBe('load-failed'));
+ expect(view.result.current.entries.get('')).toHaveLength(2);
+ view.unmount();
+ });
+
+ /**
+ * 上面那条 P1 的另一半:根响应与借来的树**结构一致**时走 entriesStructurallyEqual
+ * 的提前 return,同样必须结束「借来的树」标记。漏掉这条分支,store 会长久停在
+ * seeded=true —— 之后一次瞬时失败仍然会把用户最后一次成功的树清掉。
+ */
+ it('根结构与 seed 一致(走等价短路)也同样结束「借来的树」', async () => {
+ const sameRoot: readonly DirEntry[] = [
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ];
+ let failRoot = false;
+ mocks.listDir.mockImplementation((args: { relPath?: string }) => {
+ if (failRoot && !args.relPath) return Promise.reject(new Error('boom'));
+ if (args.relPath) return Promise.resolve([]);
+ return Promise.resolve(sameRoot);
+ });
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-equal', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: false } },
+ );
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ // 切 reveal:新 store 借隐藏态的树(同结构),根响应走结构化等价短路。
+ await act(async () => {
+ view.rerender({ reveal: true });
+ });
+ await waitFor(() => expect(view.result.current.entries.get('')).toHaveLength(1));
+
+ failRoot = true;
+ await act(async () => {
+ await view.result.current.refresh();
+ });
+ await waitFor(() => expect(view.result.current.loadError).toBe('load-failed'));
+ expect(view.result.current.entries.get('')).toHaveLength(1);
+ view.unmount();
+ });
+
+ /**
+ * 兄弟 store 还在首次 listDir 上(慢通道)时不能冒充「已加载」:没有可显示内容
+ * 就保持 initialLoading,否则 FileTreeView 会把空 rows 渲染成「此文件夹为空」
+ * 而不是延迟 loading 态。
+ */
+ it('兄弟 store 还没有首帧数据时保持 initialLoading', async () => {
+ const pendingReveal = deferred<readonly DirEntry[]>();
+ const pendingHidden = deferred<readonly DirEntry[]>();
+ mocks.listDir.mockImplementation((args: { showIgnoredDirs?: boolean }) =>
+ args.showIgnoredDirs ? pendingReveal.promise : pendingHidden.promise,
+ );
+
+ const view = renderHook(
+ ({ reveal }: { reveal: boolean }) =>
+ useFileTree({ workdir: '/workdir-seed-pending', showIgnoredDirs: reveal }),
+ { initialProps: { reveal: true } },
+ );
+ expect(view.result.current.initialLoading).toBe(true);
+
+ await act(async () => {
+ view.rerender({ reveal: false });
+ });
+ // 兄弟 store 存在但没有可显示内容 → hidden 侧必须继续 loading。
+ expect(view.result.current.initialLoading).toBe(true);
+
+ await act(async () => {
+ pendingHidden.resolve([
+ { name: 'src', relPath: 'src', type: 'directory', size: 0, mtimeMs: 1 },
+ ]);
+ await Promise.resolve();
+ });
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+
+ view.unmount();
+ });
+});
+
+/**
+ * device-link 能力探测:老被控端的 listDir 会静默忽略 showIgnoredDirs ——
+ * 开关看起来按下去了、树里什么也不变。探到不支持就按隐藏态建 store,并把结论
+ * expose 给标题行(禁用 + 说明原因)。
+ */
+describe('useFileTree device 的 showIgnoredDirs 能力探测', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.eventCallbacks.length = 0;
+ mocks.listDir.mockResolvedValue([]);
+ mocks.fileBrowserApiFor.mockReturnValue({ listDir: mocks.listDir });
+ mocks.loadExpandedSet.mockImplementation(() => new Set<string>());
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => true);
+ mocks.reconnectEpoch.current = 0;
+ });
+
+ it('老被控端:按隐藏态建 store,并 expose supported=false', async () => {
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => false);
+ const view = renderHook(() =>
+ useFileTree({ workdir: '/workdir-old-device', deviceId: 'device-1', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(view.result.current.showIgnoredDirsSupported).toBe(false));
+
+ expect(mocks.deviceSupportsRevealIgnoredDirs).toHaveBeenCalledWith(
+ 'device-1',
+ '/workdir-old-device',
+ );
+ await waitFor(() =>
+ expect(mocks.listDir).toHaveBeenCalledWith(
+ expect.objectContaining({ showIgnoredDirs: false }),
+ ),
+ );
+ // 探测返回前可能已用偏好值乐观拉过一次;落定之后不能再发无效字段。
+ const calls = mocks.listDir.mock.calls;
+ expect(calls.length).toBeGreaterThan(0);
+ expect(calls[calls.length - 1][0].showIgnoredDirs).toBe(false);
+ view.unmount();
+ });
+
+ it('支持的被控端:开关照常生效,supported=true', async () => {
+ const view = renderHook(() =>
+ useFileTree({ workdir: '/workdir-new-device', deviceId: 'device-2', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(view.result.current.showIgnoredDirsSupported).toBe(true));
+ await waitFor(() =>
+ expect(mocks.listDir).toHaveBeenCalledWith(
+ expect.objectContaining({ showIgnoredDirs: true }),
+ ),
+ );
+ view.unmount();
+ });
+
+ it('本地会话不做探测,supported 恒为 true', async () => {
+ const view = renderHook(() => useFileTree({ workdir: '/workdir-local' }));
+ await waitFor(() => expect(view.result.current.initialLoading).toBe(false));
+ expect(view.result.current.showIgnoredDirsSupported).toBe(true);
+ expect(mocks.deviceSupportsRevealIgnoredDirs).not.toHaveBeenCalled();
+ view.unmount();
+ });
+
+ /**
+ * 瞬态失败(隧道不可达 / 重连中)不能被当成「对方版本过旧」:那会把开关错误地
+ * 禁用并显示升级提示,而连接恢复后也不会自愈。保持「未知」(不禁用) + 由
+ * 重连代次驱动重探。
+ */
+ it('瞬态失败保持未知并在重连后重探', async () => {
+ mocks.reconnectEpoch.current = 0;
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => null);
+ const view = renderHook(() =>
+ useFileTree({ workdir: '/workdir-flaky', deviceId: 'device-flaky', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(mocks.deviceSupportsRevealIgnoredDirs).toHaveBeenCalledTimes(1));
+ expect(view.result.current.showIgnoredDirsSupported).toBe(null);
+ // 未知 = 不禁用:树仍按用户偏好(开)建 store。
+ await waitFor(() =>
+ expect(mocks.listDir).toHaveBeenCalledWith(
+ expect.objectContaining({ showIgnoredDirs: true }),
+ ),
+ );
+
+ // 连接恢复 → 重连代次自增 → 重新探测并落定。
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => true);
+ mocks.reconnectEpoch.current = 1;
+ view.rerender();
+ await waitFor(() => expect(view.result.current.showIgnoredDirsSupported).toBe(true));
+ // 重连代次驱动的「重问」;缓存是否命中由 transport 自己按全局 reconnect 流记账
+ // (不依赖 hook 生命周期,见 fileBrowserTransport 的进程级重连代次)。
+ expect(mocks.deviceSupportsRevealIgnoredDirs).toHaveBeenCalledTimes(2);
+ view.unmount();
+ });
+
+ it('已定的「不支持」不会被重连代次重置成未知(开关不闪)', async () => {
+ mocks.reconnectEpoch.current = 0;
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => false);
+ const view = renderHook(() =>
+ useFileTree({ workdir: '/workdir-old2', deviceId: 'device-old2', showIgnoredDirs: true }),
+ );
+ await waitFor(() => expect(view.result.current.showIgnoredDirsSupported).toBe(false));
+
+ mocks.reconnectEpoch.current = 1;
+ view.rerender();
+ await waitFor(() => expect(mocks.deviceSupportsRevealIgnoredDirs).toHaveBeenCalledTimes(2));
+ expect(view.result.current.showIgnoredDirsSupported).toBe(false);
+
+ // 旧端升级后重连 → 结论改成支持。
+ mocks.deviceSupportsRevealIgnoredDirs.mockImplementation(async () => true);
+ mocks.reconnectEpoch.current = 2;
+ view.rerender();
+ await waitFor(() => expect(view.result.current.showIgnoredDirsSupported).toBe(true));
+ view.unmount();
+ });
+});
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts
index 4f5a415c5a..d29b121ff0 100644
--- a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts
@@ -41,10 +41,12 @@
* 不进 React state,避免 setState 触发不必要的订阅者重渲。
*/
-import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
import { createLogger } from '@/lib/logger';
+import { useDeviceLinkReconnectEpoch } from '@/features/device-link/useDeviceLinkReconnectEpoch';
import {
+ deviceSupportsRevealIgnoredDirs,
fileBrowserApiFor,
isDeviceTooOldError,
onFileTreeEventFor,
@@ -52,6 +54,10 @@ import {
stopWatchFor,
} from '@/lib/fileBrowserTransport';
import { loadExpandedSet, saveExpandedSet } from '../lib/expandedStore';
+import {
+ BUILTIN_IGNORE_ALWAYS,
+ BUILTIN_IGNORE_REVEALABLE,
+} from '../../../../../shared/ignoreNames';
const log = createLogger('useFileTree');
@@ -86,6 +92,14 @@ interface UseFileTreeOptions {
* new/deleted doc file can change which dirs appear at any depth above).
*/
docMode?: boolean;
+ /**
+ * 用户开关「显示被忽略的目录」:列出依赖 / 构建产物 / 缓存目录
+ * (build / dist / out / node_modules / Library ...)。
+ *
+ * 进 store key:切换开关会换一份 store(listDir 与 watcher 都用新 matcher
+ * 重建),已展开目录的缓存在新 store 里重建。
+ */
+ showIgnoredDirs?: boolean;
}
export interface UseFileTreeReturn {
@@ -99,6 +113,22 @@ export interface UseFileTreeReturn {
initialLoading: boolean;
/** root 加载失败标记(device-too-old = 对方设备版本过旧);见 store 注释。 */
loadError: 'device-too-old' | 'load-failed' | null;
+ /**
+ * 「显示被忽略的目录」在当前会话是否真的生效:
+ * - true 本地 / SSH / 支持该字段的被控端;
+ * - false device-link 连到老 Desktop —— 它的 listDir 静默忽略这个字段,
+ * 开关看起来按下去了、树里什么也不变;
+ * - null device 会话首帧,能力探测还没回来(非 device 会话恒为 true)。
+ * 标题行据此把开关渲染成不可用 + 说明原因;树本身在 false 时已经按隐藏态
+ * 建 store(不向老端发一个无效字段)。
+ */
+ showIgnoredDirsSupported: boolean | null;
+
+ /** 当前 store 的稳定标识(workdir + hideMetaFiles + showIgnoredDirs + host/device)。
+ * 切「显示被忽略的目录」会换一份 store,这个值跟着变;同一 store 内因 snapshot
+ * 更新造成的重渲染不会变 —— 需要区分"换视图"与"同一视图刷新"的地方(如滚动
+ * 锚点、DOM 复用判定)用它,而不是靠对象引用。 */
+ storeKey: string;
toggleFolder: (relPath: string) => void;
/** Collapse every folder back to root. Also clears persisted state. */
@@ -108,8 +138,9 @@ export interface UseFileTreeReturn {
* 展开 relPath 的所有祖先目录(让该文件可见),触发未 cache 的目录 lazy fetch,
* 返回 Promise 等所有 listDir 完成。
*
- * 用于"筛选文件 / 搜索 / 跳转"等需要把目标��件在树里露出来的场景 —— 上层调
- * 完 expandToPath 再 scrollIntoView 那一行,visual 节奏稳。
+ * 用于"筛选文件 / 搜索 / 跳转"等需要把目标文件在树里露出来的场景 —— 上层调
+ * 完 expandToPath 再调 FileTreeView 的 scrollToPath 把那一行滚进视口,visual
+ * 节奏稳(虚拟化后由 virtualizer.scrollToIndex 完成)。
*
* Root 文件(relPath 不含 '/')直接 no-op return —— 它已经在根级,无需展开。
*/
@@ -163,6 +194,7 @@ interface FileTreeStore {
readonly deviceId: string | null;
readonly hideMetaFiles: boolean;
readonly docMode: boolean;
+ readonly showIgnoredDirs: boolean;
snapshot: {
entries: ReadonlyMap<string, readonly DirEntry[]>;
expanded: ReadonlySet<string>;
@@ -175,6 +207,14 @@ interface FileTreeStore {
*/
loadError: 'device-too-old' | 'load-failed' | null;
};
+ /** 本 store 的 entries 是否还是从兄弟 scope **借来**的 seed 数据(切换开关的
+ * 过渡窗口)。借来的树一旦根请求失败就不代表当前视图,留着会让失败看起来像
+ * 加载成功(评审 P2)。 */
+ seeded: boolean;
+ /** 本 scope **自己持久化过**的展开位(创建时从 localStorage 读出的那份)。
+ * seed 窗口收尾的 root 剪枝要继续豁免它们:那时子目录列表可能还是兄弟 scope
+ * 借来的,列表缺路径 ≠ 本 scope 的展开位过期(评审:切开关丢失展开记录)。 */
+ readonly persistedExpanded: ReadonlySet<string>;
/** 同一 relPath 的并发 listDir,latest 赢:每次开 listDir 前 bump,resolve
* 时比对 —— 不一致就丢结果。 */
tokens: Map<string, number>;
@@ -203,17 +243,175 @@ const stores = new Map<string, FileTreeStore>();
function storeKey(opts: Required<UseFileTreeOptions>): string {
const remote = opts.remoteHostId ? `::remote=${opts.remoteHostId}` : '';
const device = opts.deviceId ? `::device=${opts.deviceId}` : '';
- return `${opts.workdir}::doc=${opts.docMode}::hideMeta=${opts.hideMetaFiles}${remote}${device}`;
+ const reveal = opts.showIgnoredDirs ? '::reveal' : '';
+ return `${opts.workdir}::doc=${opts.docMode}::hideMeta=${opts.hideMetaFiles}${reveal}${remote}${device}`;
}
function emit(store: FileTreeStore): void {
for (const l of store.listeners) l();
}
+/**
+ * 隐藏态会忽略的一级目录名。名单从 @cindy/file-browser-core/ignoreNames 单源
+ * 导入(经 shared 转发),只覆盖内置项 —— `.gitignore` / `.p4ignore` 里的自定义
+ * 条目 renderer 拿不到,要等新 matcher 的数据回来才消失。
+ *
+ * 名单与比较都折叠大小写:matcher 的 `ignore` 包默认 `ignorecase=true`,大小写
+ * 变体(`DIST` / `BUILD`)在隐藏态同样不可见,不折叠会让它们在首帧多留一拍。
+ */
+const HIDDEN_VIEW_DIR_NAMES = new Set(
+ [...BUILTIN_IGNORE_ALWAYS, ...BUILTIN_IGNORE_REVEALABLE]
+ .filter((name) => name.endsWith('/'))
+ .map((name) => name.slice(0, -1).toLowerCase()),
+);
+
+/**
+ * 关开关的首帧过滤:把 reveal 态树里「隐藏态会被忽略」的目录行**逐列表**拿掉
+ * —— 不只是根列表。被忽略目录可能嵌在已展开的普通目录下面
+ * (`packages/foo/node_modules`):只滤根列表的话它会一直挂在展开的父目录下,
+ * 而 pruneExpandedForCurrentTree 会拿**过期的 reveal 子列表**当可达性依据、
+ * 把它判成可达,于是永久保留到手动刷新。
+ *
+ * 同时**丢掉被移除目录的整棵缓存**(不只是那一行):它们不再可达,但 refresh()
+ * 是「按 entries 的 key 逐个 listDir」—— 留着会让隐藏态下一次刷新给 node_modules
+ * 子树白发数百个 listDir(本地卡顿,SSH / device-link 上就是数百条 RPC)。
+ *
+ * 逐列表过滤同时修好 prune 的判据:父列表里已经没有那一行,可达性自然为假。
+ * 其余子树缓存与展开集合整体不动(不可达的分支本来就不渲染),不重拉任何目录 ——
+ * 「整体一次性消失」的观感不变。
+ *
+ * 只覆盖内置名单:`.gitignore` / `.p4ignore` 的自定义条目 renderer 拿不到
+ * (不读盘),要等新 matcher 的数据回来才消失。
+ */
+function filterSeedTreeForHiddenView(
+ entries: ReadonlyMap<string, readonly DirEntry[]>,
+): ReadonlyMap<string, readonly DirEntry[]> {
+ const droppedRoots = new Set<string>();
+ const next = new Map<string, readonly DirEntry[]>();
+ for (const [dir, list] of entries) {
+ const kept = list.filter((entry) => {
+ if (entry.type === 'directory' && HIDDEN_VIEW_DIR_NAMES.has(entry.name.toLowerCase())) {
+ droppedRoots.add(entry.relPath);
+ return false;
+ }
+ return true;
+ });
+ next.set(dir, kept.length === list.length ? list : kept);
+ }
+ if (droppedRoots.size === 0) return entries;
+ for (const dir of [...next.keys()]) {
+ if (dir === ROOT_KEY) continue;
+ // 逐级向上查:key 落在被移除目录自己或它的子树里就丢。
+ for (let probe = dir; probe !== ''; ) {
+ if (droppedRoots.has(probe)) {
+ next.delete(dir);
+ break;
+ }
+ const cut = probe.lastIndexOf('/');
+ probe = cut < 0 ? '' : probe.slice(0, cut);
+ }
+ }
+ return next;
+}
+
+/**
+ * 切换「显示被忽略的目录」会换一份 store(key 含 reveal 位),新 store 若从
+ * 空快照 + initialLoading 起步,FileTreeView 会把整棵树替换成占位(本地
+ * <300ms 连 spinner 都没有,就是空白),视觉上闪一下;同一 workdir 的另一半
+ * reveal scope 的 store 此刻通常还在表里 —— 旧 store 的 refCount 归零发生在
+ * 本次 commit 的 effect cleanup,晚于 render 期间的 useMemo —— 借它
+ * **整棵可见的树**(entries + expanded)当首帧内容,新 matcher 的 listDir 回来
+ * 后再整体替换。
+ *
+ * 为什么整棵借、而不是只借根列表:只借根列表会把消失动作拆成两段 —— 子行先因
+ * expanded 掉落而消失(父行还在),root 数据回来再拿掉父行 —— 多级展开时看起来
+ * 就是「从最子级逐级折叠回去」。整棵借过来,关闭开关的动作是一次性的:树先保持
+ * 不动,数据回来整体切换。
+ *
+ * 代价是过渡窗口(reveal → hidden)里旧 matcher 的行还会短暂可见 —— 窗口就是
+ * 一次 listDir(本地 <12ms;慢通道到数据回来为止)。这是有意的取舍:全量、一次性
+ * 地消失,比先闪空再重建、或逐级折叠都更接近直觉。
+ *
+ * 借来的 expanded 是**过渡态**:initStore 不据此 warm(免得给被忽略路径白发
+ * listDir),root 数据回来时由 pruneExpandedForCurrentTree 按新树剪掉不可达路径
+ * —— 否则它们会落进 hidden scope 的 localStorage,下次启动白拉一批。
+ *
+ * 「刷新」按钮没有这个问题:它在同一份 store 上原地 refetch,从不经过空态。
+ */
+function findRevealSiblingSnapshot(
+ opts: Required<UseFileTreeOptions>,
+): FileTreeStore['snapshot'] | null {
+ const siblingKey = storeKey({ ...opts, showIgnoredDirs: !opts.showIgnoredDirs });
+ return stores.get(siblingKey)?.snapshot ?? null;
+}
+
+/**
+ * root 数据回来后,把「过渡期借来的、在当前树上不可达的展开路径」剪掉。
+ *
+ * 切开关时 seed 会把另一半 reveal scope 的整棵可见树带过来(见
+ * findRevealSiblingSnapshot)。hidden 树下 node_modules / Library 这类路径已经
+ * 不在 root 列表里,但它们的展开态还挂在 expanded 上 —— 留着会让用户在 hidden
+ * 态做下一次操作时把它们写进 hidden scope 的 localStorage,下次启动就白发一批
+ * listDir。逐级查父链:任一级不在对应父列表里即不可达。
+ *
+ * 查不到祖先列表(缓存被清 / 还没拉过)时保守保留 —— 宁可留一个 stale 展开位,
+ * 也不能把用户真实的展开态删掉。
+ *
+ * 剪枝后**同步回写持久化**(评审 P2):过渡窗口里 root 数据还没到时,用户若做过
+ * 一次 toggleFolder,那次 saveExpandedSet 会把继承来的 reveal-only 路径一并
+ * 写进本 scope —— 不回写就会把它们固化进 localStorage,下次挂载按这些路径逐个
+ * listDir(上限 200 个,SSH / device-link 上代价明显)。
+ *
+ * `keep`:目标 scope **自己持久化过**的展开位,豁免剪枝。回写是整份覆盖,调用方
+ * 必须先把这些路径并进 `snapshot.expanded` 再调本函数,否则它们会被这次回写抹掉
+ * (评审 P1:借来的树只能当过渡内容,不能拿它否定本 scope 自己的记录)。
+ */
+function pruneExpandedForCurrentTree(
+ store: FileTreeStore,
+ opts?: { keep?: ReadonlySet<string> },
+): void {
+ if (!store.snapshot.entries.has(ROOT_KEY)) return;
+ const reachable = (relPath: string): boolean => {
+ const parts = relPath.split('/');
+ let parent = ROOT_KEY;
+ for (const part of parts) {
+ const list = store.snapshot.entries.get(parent);
+ if (!list) return true;
+ const child = parent === ROOT_KEY ? part : `${parent}/${part}`;
+ if (!list.some((entry) => entry.relPath === child)) return false;
+ parent = child;
+ }
+ return true;
+ };
+ const next = new Set<string>();
+ let changed = false;
+ for (const relPath of store.snapshot.expanded) {
+ if (relPath === ROOT_KEY || opts?.keep?.has(relPath) || reachable(relPath)) next.add(relPath);
+ else changed = true;
+ }
+ if (!changed) return;
+ store.snapshot = { ...store.snapshot, expanded: next };
+ emit(store);
+ saveExpandedSet(store.workdir, next, { showIgnoredDirs: store.showIgnoredDirs });
+}
+
function getOrCreateStore(opts: Required<UseFileTreeOptions>): FileTreeStore {
const key = storeKey(opts);
const existing = stores.get(key);
if (existing) return existing;
+ // 切开关路径:借另一半 reveal scope 的整棵树当首帧内容,不经过 initialLoading
+ // 空白;首次挂载(无兄弟 store)仍走原来的 loading 路径。
+ const seed = findRevealSiblingSnapshot(opts);
+ // 本 scope 自己持久化过的展开位:seed 是**过渡内容**,而下面的剪枝会同步回写
+ // 本 scope 的 localStorage —— 不先读出来并进快照,「借来的树里不可达」就会
+ // 连带抹掉本 scope 原有记录(评审 P1:切回隐藏态后目录无故全部折叠)。
+ const persistedExpanded = loadExpandedSet(opts.workdir, {
+ showIgnoredDirs: opts.showIgnoredDirs,
+ });
+ // 兄弟 store 可能还卡在首次 listDir 上(慢通道):没有可显示内容时不得冒充
+ // 「已加载」—— 否则 FileTreeView 会把 initialLoading:false + 空 rows 渲染成
+ // 「此文件夹为空」,而不是延迟 loading 态。终态错误可显示(渲染错误占位)。
+ const seedDisplayable = !!seed && (seed.entries.size > 0 || seed.loadError !== null);
const store: FileTreeStore = {
key,
workdir: opts.workdir,
@@ -221,13 +419,32 @@ function getOrCreateStore(opts: Required<UseFileTreeOptions>): FileTreeStore {
deviceId: opts.deviceId,
hideMetaFiles: opts.hideMetaFiles,
docMode: opts.docMode,
- snapshot: {
- entries: new Map(),
- expanded: new Set([ROOT_KEY]),
- loadingPaths: new Set(),
- initialLoading: true,
- loadError: null,
- },
+ showIgnoredDirs: opts.showIgnoredDirs,
+ snapshot:
+ seedDisplayable && seed
+ ? {
+ // 关开关的首帧就滤掉内置忽略目录(避免慢通道下它们在新数据回来前
+ // 还挂在「已隐藏」的视图里),见 filterSeedTreeForHiddenView。
+ entries: opts.showIgnoredDirs
+ ? seed.entries
+ : filterSeedTreeForHiddenView(seed.entries),
+ // 借来的过渡展开态 + 本 scope 已有的持久记录(见上方 persistedExpanded)。
+ expanded: new Set([...seed.expanded, ...persistedExpanded]),
+ // 新 store 自己还没有 in-flight 请求,seed 的 loadingPaths 不继承。
+ loadingPaths: new Set(),
+ initialLoading: false,
+ // 错误态一并继承:首帧直接是错误占位,而不是先闪一帧空树再变错误。
+ loadError: seed.loadError,
+ }
+ : {
+ entries: new Map(),
+ expanded: new Set([ROOT_KEY]),
+ loadingPaths: new Set(),
+ initialLoading: true,
+ loadError: null,
+ },
+ seeded: seedDisplayable && !!seed,
+ persistedExpanded,
tokens: new Map(),
inFlight: new Map(),
pendingEventParents: new Set(),
@@ -236,6 +453,13 @@ function getOrCreateStore(opts: Required<UseFileTreeOptions>): FileTreeStore {
refCount: 0,
listeners: new Set(),
};
+ // 继承来的展开集合要按**(可能已过滤的)**树剪一次:剪枝那条路径挂在 fetch
+ // 成功分支上,根请求失败时根本不会执行 —— 而 reveal-only 路径一旦被写进本
+ // scope 的 localStorage(用户在错误恢复前操作目录、或 expandToPath 等路径),
+ // 下次挂载就会变成最多 200 次无用 listDir(评审 P2)。剪完顺带回写本 scope。
+ // `keep` = 本 scope 自己的持久记录:借来的树只能判「借来的路径」,不能否定本
+ // scope 的展开位(评审 P1)。
+ pruneExpandedForCurrentTree(store, { keep: persistedExpanded });
stores.set(key, store);
return store;
}
@@ -254,27 +478,57 @@ async function fetchDirOnce(store: FileTreeStore, relPath: string): Promise<void
relPath,
hideMetaFiles: store.hideMetaFiles,
docMode: store.docMode,
+ showIgnoredDirs: store.showIgnoredDirs,
});
if (store.tokens.get(relPath) !== myToken) return; // stale
if (store.snapshot.loadError) {
store.snapshot = { ...store.snapshot, loadError: null };
}
- // 结构等价 → 跳过 setEntries,避免子组件无意义重渲(参见函数顶部注释)。
+ // 根请求**成功**(无论后面是否结构等价而跳过替换)都代表「借来的树」窗口
+ // 结束:之后任何一次根刷新失败都不能再把已属于本 scope 的树当成借来的清掉
+ // (评审 P1;结构等价的路径同样要落定,否则会长久停在"借来"态)。
+ // wasSeeded 必须在清标志前捕获:seed 窗口收尾的这次 root 剪枝,子目录列表
+ // 可能还是兄弟 scope 借来的(root 先回、子目录后回)—— 借来的列表缺路径 ≠
+ // 本 scope 的展开位过期,要继续豁免本 scope 自己的持久记录;等后续 root
+ // 刷新(entries 已全属本 scope)再做精确剪枝(评审:切开关丢失展开记录)。
+ const wasSeeded = store.seeded;
+ if (relPath === ROOT_KEY) store.seeded = false;
+ // 结构等价 → 跳过 setEntries,避免子组件无意义重渲(参见函数顶部注释)。
+ // root 仍要 prune 一次:seed 的 root 可能与新 root 结构一致而展开态还是借的。
const prevList = store.snapshot.entries.get(relPath);
- if (prevList && entriesStructurallyEqual(prevList, list)) return;
+ if (prevList && entriesStructurallyEqual(prevList, list)) {
+ if (relPath === ROOT_KEY) {
+ pruneExpandedForCurrentTree(store, wasSeeded ? { keep: store.persistedExpanded } : undefined);
+ }
+ return;
+ }
const nextEntries = new Map(store.snapshot.entries);
nextEntries.set(relPath, list);
store.snapshot = { ...store.snapshot, entries: nextEntries };
emit(store);
+ // 过渡期(seed)借来的展开态在新树里可能已不可达,root 数据落地即剪。
+ if (relPath === ROOT_KEY) {
+ pruneExpandedForCurrentTree(store, wasSeeded ? { keep: store.persistedExpanded } : undefined);
+ }
} catch (err) {
log.warn(`listDir failed for ${relPath}`, err);
// root 失败要可见:空树 + 无提示会被读成"项目是空的"。device-link 的
// 版本偏差(老被控端无 remote-op channel)单独标记,渲染升级提示。
if (relPath === ROOT_KEY) {
+ const seededEntries = store.seeded;
+ store.seeded = false;
store.snapshot = {
...store.snapshot,
+ // seed 过渡:借来的树一旦根请求失败就不代表当前视图,留着会让「开关已按下
+ // + 树还是隐藏态旧数据」看起来像加载成功(错误占位只在 entries 为空时显示,
+ // 见 FileBrowserBody)。清掉它让失败可见且可重试;只清一次,之后恢复既有
+ // 「保留旧树」语义(那时 entries 确实属于当前视图)(评审 P2)。
+ entries: seededEntries ? new Map() : store.snapshot.entries,
loadError: isDeviceTooOldError(err) ? 'device-too-old' : 'load-failed',
};
+ // 借来的展开态在空树下不可达,剪枝与回写由**创建时**那次
+ // pruneExpandedForCurrentTree(getOrCreateStore)完成;root 首次失败时
+ // snapshot.entries 已被清空,再调 prune 会因缺 ROOT_KEY 直接早退,不重复。
emit(store);
}
// Keep prior state; user can refresh manually.
@@ -382,9 +636,12 @@ function queueEventRefresh(store: FileTreeStore, eventRelPath: string): void {
/** 首次挂载触发:initial fetch + 恢复 localStorage expanded + 启动 watcher。
* 幂等:重复调用直接 no-op(refCount 已 >0)。 */
async function initStore(store: FileTreeStore): Promise<void> {
- // 恢复 localStorage 持久化的 expanded 集合(workdir 维度共享)。
- const restored = loadExpandedSet(store.workdir);
- const nextExpanded = new Set<string>([ROOT_KEY, ...restored]);
+ // 恢复 localStorage 持久化的 expanded 集合(workdir × 视图模式共享,见
+ // expandedStore 的 scope 说明)。seed 带来的展开集合是过渡态(见
+ // findRevealSiblingSnapshot):先一并留着让整树平滑替换,root 数据回来时
+ // pruneExpandedForCurrentTree 按新树剪掉不可达路径。
+ const restored = loadExpandedSet(store.workdir, { showIgnoredDirs: store.showIgnoredDirs });
+ const nextExpanded = new Set<string>([ROOT_KEY, ...restored, ...store.snapshot.expanded]);
store.snapshot = { ...store.snapshot, expanded: nextExpanded };
emit(store);
@@ -397,6 +654,7 @@ async function initStore(store: FileTreeStore): Promise<void> {
workdir: store.workdir,
remoteHostId: store.remoteHostId,
hideMetaFiles: store.hideMetaFiles,
+ showIgnoredDirs: store.showIgnoredDirs,
}).catch((err) => log.warn('startWatch failed', err));
store.watcherOff = onFileTreeEventFor(store.deviceId, (event) => {
@@ -407,14 +665,51 @@ async function initStore(store: FileTreeStore): Promise<void> {
// Initial root fetch + 已 restore expanded 目录的并行 lazy fetch。每个 listDir
// <12ms,即使 50 个 restored 也能在 <1s 内 warm 完。
+ //
+ // seed 带来的展开父目录(不在 restored 里的那些)按**方向**分别处理:
+ // - 切到 reveal:hidden 态的数据缺了被忽略目录,不重拉就永远看不到
+ // node_modules / build(评审 P2),所以按新 matcher 重拉一遍;
+ // - 切到 hidden:reveal 态的数据多出被忽略项,首帧已由
+ // filterSeedTreeForHiddenView 就地滤掉,不再白发一轮 listDir。
+ const inheritedExpanded = [...store.snapshot.expanded].filter(
+ (p) => p !== ROOT_KEY && !restored.has(p),
+ );
+ const refetchInherited = store.showIgnoredDirs ? inheritedExpanded : [];
+ invalidateBorrowedCollapsedEntries(store);
await Promise.all([
fetchDir(store, ROOT_KEY),
...[...restored].map((p) => fetchDir(store, p)),
+ ...refetchInherited.map((p) => fetchDir(store, p)),
]);
store.snapshot = { ...store.snapshot, initialLoading: false };
emit(store);
}
+/**
+ * 切到 reveal 态时,让「借来且当前收起」的目录条目失效。
+ *
+ * seed 借的是另一半 scope 的 entries 快照。展开中的目录会被 refetchInherited 按新
+ * matcher 重拉;但「展开过又收起」的目录不在 expanded 里,既不会被重拉,
+ * toggleFolder 又见 entries.has() 就跳过请求 —— 那条缓存仍是 hidden 态的结果,
+ * 缺 packages/dist 这类被忽略目录,之后展开也补不回来(评审 P1)。
+ *
+ * 只在「借来的 + reveal 态」清理:首次挂载的 store 没有陈旧条目可清;切回 hidden
+ * 态时 seed 已由 filterSeedTreeForHiddenView 就地滤掉,不受影响。
+ */
+function invalidateBorrowedCollapsedEntries(store: FileTreeStore): void {
+ if (!store.seeded || !store.showIgnoredDirs) return;
+ const expanded = store.snapshot.expanded;
+ const entries = new Map(store.snapshot.entries);
+ let dropped = 0;
+ for (const path of [...entries.keys()]) {
+ if (path === ROOT_KEY || expanded.has(path)) continue;
+ entries.delete(path);
+ dropped++;
+ }
+ if (dropped === 0) return;
+ store.snapshot = { ...store.snapshot, entries };
+}
+
/** 最后一个订阅者离开:停 watcher、从 stores 表移除。store 对象被回收。 */
function disposeStore(store: FileTreeStore): void {
if (store.eventFlushTimer) clearTimeout(store.eventFlushTimer);
@@ -446,7 +741,7 @@ function toggleFolder(store: FileTreeStore, relPath: string): void {
void fetchDir(store, relPath);
}
}
- saveExpandedSet(store.workdir, next);
+ saveExpandedSet(store.workdir, next, { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = { ...store.snapshot, expanded: next };
emit(store);
}
@@ -457,7 +752,7 @@ function collapseAll(store: FileTreeStore): void {
const nextEntries = new Map<string, readonly DirEntry[]>();
const rootEntries = prevEntries.get(ROOT_KEY);
if (rootEntries) nextEntries.set(ROOT_KEY, rootEntries);
- saveExpandedSet(store.workdir, new Set());
+ saveExpandedSet(store.workdir, new Set(), { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = {
...store.snapshot,
expanded: nextExpanded,
@@ -467,8 +762,10 @@ function collapseAll(store: FileTreeStore): void {
}
async function refresh(store: FileTreeStore): Promise<void> {
- const targets = [...store.snapshot.entries.keys()];
- await Promise.all(targets.map((p) => fetchDir(store, p)));
+ // 根目录必须恒在请求列表里:根请求失败会清空 entries(含 ROOT_KEY),
+ // 而只遍历现有键时根就永远不会被重试,连接恢复后点「重试 / 刷新」也没用。
+ const targets = new Set<string>([ROOT_KEY, ...store.snapshot.entries.keys()]);
+ await Promise.all([...targets].map((p) => fetchDir(store, p)));
}
async function expandToPath(store: FileTreeStore, relPath: string): Promise<void> {
@@ -482,7 +779,7 @@ async function expandToPath(store: FileTreeStore, relPath: string): Promise<void
// 一次性写 expanded set
const nextExpanded = new Set(store.snapshot.expanded);
for (const a of ancestors) nextExpanded.add(a);
- saveExpandedSet(store.workdir, nextExpanded);
+ saveExpandedSet(store.workdir, nextExpanded, { showIgnoredDirs: store.showIgnoredDirs });
store.snapshot = { ...store.snapshot, expanded: nextExpanded };
emit(store);
// 未 cache 的祖先并行 fetch
@@ -498,12 +795,62 @@ export function useFileTree({
deviceId = null,
hideMetaFiles = true,
docMode = false,
+ showIgnoredDirs = false,
}: UseFileTreeOptions): UseFileTreeReturn {
+ // device 会话:探测被控端是否支持 showIgnoredDirs。老端的 listDir 会静默忽略
+ // 这个字段 —— 开关看起来按下去了、树里什么也不变。
+ //
+ // 探到不支持就按“隐藏态”建 store(不给老端发无效字段),并把结论 expose 给
+ // 标题行(开关渲染成不可用 + 说明原因)。非 device 会话恒为 true。
+ //
+ // 瞬态失败(隧道不可达 / 重连中)保持「未知」而不是落定成 false:把一次网络抖动
+ // 显示成「对方版本过旧」并把开关禁掉,连接恢复后也不会自愈。重探由
+ // reconnectEpoch 驱动 —— relay 或目标设备恢复 online 时它自增。
+ const revealReconnectEpoch = useDeviceLinkReconnectEpoch(deviceId ?? undefined);
+ const [deviceRevealSupported, setDeviceRevealSupported] = useState<boolean | null>(null);
+ /** 上次探测结论归属的设备;换设备不留用旧结论(重连不清,避免开关闪一下)。 */
+ const revealProbedDeviceRef = useRef<string | null>(null);
+ useEffect(() => {
+ if (!deviceId) {
+ revealProbedDeviceRef.current = null;
+ setDeviceRevealSupported(null);
+ return;
+ }
+ if (revealProbedDeviceRef.current !== deviceId) {
+ revealProbedDeviceRef.current = deviceId;
+ setDeviceRevealSupported(null);
+ }
+ let cancelled = false;
+ // reconnectEpoch 在这里只负责「何时重问」;缓存代次由 transport 自己按全局
+ // reconnect 流记账 —— hook 卸载期间的重连它也能看到(见 fileBrowserTransport)。
+ void deviceSupportsRevealIgnoredDirs(deviceId, workdir).then((supported) => {
+ if (cancelled) return;
+ // null = 瞬态失败:保持现状(首帧仍是「未知」,已有结论也不推翻),
+ // 等下一次 reconnectEpoch 或重新挂载时再问一次。
+ if (supported === null) return;
+ setDeviceRevealSupported(supported);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [deviceId, workdir, revealReconnectEpoch]);
+
+ // 探测未返回时(device 首帧)沿用用户偏好:猜错只多一次重建,不会发出无法
+ // 兑现的用户可见承诺。
+ const effectiveShowIgnoredDirs = showIgnoredDirs && deviceRevealSupported !== false;
+
// store 实例按 (workdir + options) 共享 —— 多个 hook 实例订阅同一份。
// memo 用 dep 化 options,确保 workdir 切换会换 store。
const store = useMemo(
- () => getOrCreateStore({ workdir, remoteHostId, deviceId, hideMetaFiles, docMode }),
- [workdir, remoteHostId, deviceId, hideMetaFiles, docMode],
+ () => getOrCreateStore({
+ workdir,
+ remoteHostId,
+ deviceId,
+ hideMetaFiles,
+ docMode,
+ showIgnoredDirs: effectiveShowIgnoredDirs,
+ }),
+ [workdir, remoteHostId, deviceId, hideMetaFiles, docMode, effectiveShowIgnoredDirs],
);
// ref-count 生命周期:首挂触发 init(initial fetch + start watch),最后离开
@@ -551,11 +898,14 @@ export function useFileTree({
loadingPaths: snapshot.loadingPaths,
initialLoading: snapshot.initialLoading,
loadError: snapshot.loadError,
+ // 非 device 会话恒 true;device 会话见上面探测注释。
+ showIgnoredDirsSupported: deviceId ? deviceRevealSupported : true,
+ storeKey: store.key,
toggleFolder: toggleFolderCb,
collapseAll: collapseAllCb,
refresh: refreshCb,
expandToPath: expandToPathCb,
}),
- [snapshot, toggleFolderCb, collapseAllCb, refreshCb, expandToPathCb],
+ [snapshot, deviceId, deviceRevealSupported, store, toggleFolderCb, collapseAllCb, refreshCb, expandToPathCb],
);
}
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/__tests__/expandedStore.test.ts b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/__tests__/expandedStore.test.ts
new file mode 100644
index 0000000000..fe9c42738f
--- /dev/null
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/__tests__/expandedStore.test.ts
@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+
+/**
+ * expandedStore — 展开态按「显示被忽略的目录」分片持久化。
+ *
+ * 起因(评审 P2):放行态展开过 node_modules / Library 后切回隐藏态,旧实现按
+ * workdir 单一键恢复 → init 会把上百个隐藏的巨大目录当成"已展开"并行 listDir
+ * (本地卡顿,SSH 上一条条 RPC)。隐藏态必须只看到「隐藏态里展开过的目录」。
+ */
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { loadExpandedSet, saveExpandedSet } from '../expandedStore';
+
+describe('expandedStore 按 showIgnoredDirs 分片', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ });
+
+ it('放行态写入不污染隐藏态', () => {
+ saveExpandedSet('/repo', new Set(['Assets', 'node_modules']), { showIgnoredDirs: true });
+
+ expect([...loadExpandedSet('/repo')]).toEqual([]);
+ expect([...loadExpandedSet('/repo', { showIgnoredDirs: true })]).toEqual([
+ 'Assets',
+ 'node_modules',
+ ]);
+ });
+
+ /**
+ * 评审 P1:旧实现用 `::reveal` 裸后缀,workdir 以 `::reveal` 结尾时(如
+ * `/srv/project::reveal`)它的隐藏键恰好等于 `/srv/project` 的 reveal 键,两个
+ * 项目的展开态互相覆盖。新键用不可打印的 NUL 分隔(POSIX 路径不允许含 NUL)。
+ */
+ it('workdir 以 ::reveal 结尾时不与截断后的 reveal scope 撞键', () => {
+ saveExpandedSet('/srv/project::reveal', new Set(['a']));
+ saveExpandedSet('/srv/project', new Set(['b']), { showIgnoredDirs: true });
+
+ expect([...loadExpandedSet('/srv/project::reveal')]).toEqual(['a']);
+ expect([...loadExpandedSet('/srv/project', { showIgnoredDirs: true })]).toEqual(['b']);
+ });
+
+ /**
+ * 评审 P1:**不**回退旧版 `::reveal` 键 —— 它同时可能就是**另一个 workdir 的
+ * 隐藏键**,回退只是把撞键换了个方向(`/srv/project` 的 reveal 态读到
+ * `/srv/project::reveal` 的隐藏态),又会对无关路径发 listDir。旧键无法区分两种
+ * 语义,所以一律不读。
+ */
+ it('不读旧版 ::reveal 键:不把别的 workdir 的隐藏态误当自己的 reveal 态', () => {
+ // `/srv/project::reveal` 以自己的**隐藏态**存了展开数据(合法写入)。
+ saveExpandedSet('/srv/project::reveal', new Set(['node_modules']));
+ // `/srv/project` 的 reveal 态没有自己的数据 → 必须是空的,不能借到上面那份。
+ expect([...loadExpandedSet('/srv/project', { showIgnoredDirs: true })]).toEqual([]);
+ // 而它自己的隐藏态照旧读到自己的数据。
+ expect([...loadExpandedSet('/srv/project::reveal')]).toEqual(['node_modules']);
+ });
+
+ it('隐藏态沿用历史键:升级后原有展开态不丢', () => {
+ saveExpandedSet('/repo', new Set(['Assets/Scripts']));
+
+ expect([...loadExpandedSet('/repo')]).toEqual(['Assets/Scripts']);
+ // 放行态是独立一份,不复用隐藏态的展开面。
+ expect([...loadExpandedSet('/repo', { showIgnoredDirs: true })]).toEqual([]);
+ });
+
+ it('两态各自清空互不影响', () => {
+ saveExpandedSet('/repo', new Set(['Assets']), { showIgnoredDirs: true });
+ saveExpandedSet('/repo', new Set(['README.md']));
+
+ saveExpandedSet('/repo', new Set(), { showIgnoredDirs: true });
+
+ expect([...loadExpandedSet('/repo', { showIgnoredDirs: true })]).toEqual([]);
+ expect([...loadExpandedSet('/repo')]).toEqual(['README.md']);
+ });
+});
diff --git a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts
index 737bf98c33..85bd213c7b 100644
--- a/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts
+++ b/apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts
@@ -6,16 +6,25 @@
* navigating away from /cc-agent/files/* and coming back is "my folders
* are still where I left them" regardless of what triggered the unmount.
*
+ * 展开态按**视图模式**分片(见 expandedScopeKey):「显示被忽略的目录」关闭时
+ * 沿用历史键(存量用户零迁移),打开时用独立一份 —— 两态可见的目录集合不同,
+ * 混用会在切回隐藏态时把 node_modules / Library 这类巨大目录当成"已展开"去
+ * 恢复,init 一次并行 listDir 上百个隐藏目录(本地卡顿,SSH 上还是一条条 RPC)。
+ *
* Storage shape:
* {
* "<workdir absolute path>": ["Assets", "Assets/Scripts", "Design"],
+ * "<workdir absolute path>\u0000reveal": ["node_modules"],
* ...
* }
*
- * Cap: max 200 paths per workdir (defends against runaway state if a user
- * mass-expands a deep tree); 100 workdirs total in the bag (LRU evict the
- * oldest workdir keys to keep storage bounded). 200 paths × ~80 chars ×
- * 100 workdirs ≈ 1.6 MB worst case — well under localStorage's 5 MB quota.
+ * Cap: max 200 paths per scope (defends against runaway state if a user
+ * mass-expands a deep tree); 100 scopes total in the bag (LRU evict the
+ * oldest keys to keep storage bounded). 200 paths × ~80 chars × 100 scopes
+ * ≈ 1.6 MB worst case — well under localStorage's 5 MB quota.
+ *
+ * 注:同一个 workdir 打开开关后占两个 scope,有效 workdir 数量减半(50) ——
+ * 上限本来就是防御极端情况的粗糙阀值,不值再引入一套二级结构。
*/
const STORAGE_KEY = 'cc-agent.workdirBrowse.expandedFolders.v1';
@@ -57,23 +66,60 @@ function saveBag(bag: Bag): void {
}
}
-export function loadExpandedSet(workdir: string): Set<string> {
+export interface ExpandedScopeOptions {
+ /** 「显示被忽略的目录」开关:true = 独立 scope(默认 false,沿用历史键)。 */
+ showIgnoredDirs?: boolean;
+}
+
+/**
+ * 持久化 scope 键。隐藏态 = workdir 本身(与历史版本一致,升级不丢展开态);
+ * 放行态用**不可打印的 NUL 分隔** —— POSIX 路径不允许含 NUL(内核唯一禁用的
+ * 字节),所以 `${workdir}\0reveal` 不可能撞上任何 workdir 的隐藏键。
+ *
+ * 旧实现用 `::reveal` 裸后缀:workdir 以 `::reveal` 结尾时(如
+ * `/srv/project::reveal`),它的隐藏键恰好等于 `/srv/project` 的 reveal 键,两个
+ * 项目的展开态互相覆盖、各自恢复无关路径(评审 P1)。
+ *
+ * **不回退旧版 `::reveal` 键**:这个字符串同时可能就是**某个 workdir 的隐藏键**,
+ * 回退只是把同一个碰撞换个方向 —— `/srv/project` 的 reveal 态会读到
+ * `/srv/project::reveal` 的隐藏态数据,又对无关路径发 listDir(评审 P1)。旧键无法
+ * 区分「旧版 reveal 写入的数据」与「另一个 workdir 的隐藏数据」,所以一律不读;
+ * 代价是升级后「放行态展开记录」一次性丢失(重新展开即可),隐藏态不受影响。
+ */
+const REVEAL_SCOPE_SUFFIX = '\u0000reveal';
+
+function expandedScopeKey(workdir: string, opts: ExpandedScopeOptions): string {
+ return opts.showIgnoredDirs ? `${workdir}${REVEAL_SCOPE_SUFFIX}` : workdir;
+}
+
+export function loadExpandedSet(
+ workdir: string,
+ opts: ExpandedScopeOptions = {},
+): Set<string> {
const bag = loadBag();
- const list = bag[workdir];
+ const list = bag[expandedScopeKey(workdir, opts)];
if (!Array.isArray(list)) return new Set();
return new Set(list.filter((s): s is string => typeof s === 'string'));
}
-export function saveExpandedSet(workdir: string, expanded: Set<string>): void {
+export function saveExpandedSet(
+ workdir: string,
+ expanded: Set<string>,
+ opts: ExpandedScopeOptions = {},
+): void {
const bag = loadBag();
+ const key = expandedScopeKey(workdir, opts);
const list = [...expanded];
// Filter out the empty-string root key (always implicit) + dedupe.
const filtered = list.filter((p) => p !== '');
if (filtered.length === 0) {
// Don't keep empty entries in the bag — it'd just bloat over time.
- delete bag[workdir];
+ delete bag[key];
} else {
- bag[workdir] = filtered.slice(0, MAX_PATHS_PER_WORKDIR);
+ bag[key] = filtered.slice(0, MAX_PATHS_PER_WORKDIR);
}
+ // 不清旧版 `::reveal` 键:它和隐藏键共用同一个字符串空间(`/srv/project::reveal`
+ // 既是 /srv/project 的旧 reveal 键、又是它自己的隐藏键),删它就会误删另一个
+ // workdir 的数据。旧键只是残留、不再被读也不再被写。
saveBag(bag);
}
diff --git a/apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx b/apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx
index 63d56ea41e..ee38115582 100644
--- a/apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx
+++ b/apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx
@@ -33,12 +33,11 @@ import { openHtmlFileByPreference } from '@/components/chat/useOpenWithMenu';
import { resolveSessionFileOrigin } from '@/lib/sessionFileOrigin';
import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type DragEvent } from 'react';
import { useTranslation } from 'react-i18next';
-import { ChevronsDownUp, FolderX, RefreshCw, Search, X as XIcon } from 'lucide-react';
-
+import { FolderX } from 'lucide-react';
import { cn } from '@/lib/utils';
import { isGlobalDropIntercepted } from '@/lib/globalDropIntercept';
+import { useFileBrowserPreference } from '@/hooks/useFileBrowserPreference';
import { toast } from '@/lib/toast';
-import { Tip } from '@/components/ui/tooltip';
import { ImageLightbox } from '@/components/chat/ImageLightbox';
import {
useSessionScopedTreeWidth,
@@ -59,6 +58,7 @@ import { useConfirmSwitchAwayIfDirty } from '@/features/cc-agent/workdir-browse/
import { useProjectFileList } from '@/features/cc-agent/workdir-browse/hooks/useProjectFileList';
import { useRevealFileInTree } from '@/features/cc-agent/workdir-browse/hooks/useRevealFileInTree';
import { SearchPanel } from '@/features/cc-agent/workdir-browse/search/SearchPanel';
+import { FileTreeHeaderActions } from '@/features/cc-agent/workdir-browse/FileTreeHeaderActions';
import { useProjectSearch } from '@/features/cc-agent/workdir-browse/search/hooks/useProjectSearch';
import { FileFilterInput } from '@/features/cc-agent/workdir-browse/FileFilterInput';
import { FilterResultList } from '@/features/cc-agent/workdir-browse/FilterResultList';
@@ -135,7 +135,11 @@ function FileBrowserBodyWithWorkdir({
);
const remoteHostId = deviceId ? null : ctx.remoteHostId;
const isRemote = Boolean(remoteHostId) || Boolean(deviceId);
- const tree = useFileTree({ workdir, hideMetaFiles: true, remoteHostId, deviceId });
+ // 设置页「显示被忽略的目录」开关(默认关)。进 useFileTree 的 store key →
+ // 切换开关会换一份 store,listDir 与 watcher 都用新 matcher 重建,
+ // 目录列表立即重新拉取(不需要用户手动刷新)。
+ const { showIgnoredDirs } = useFileBrowserPreference();
+ const tree = useFileTree({ workdir, hideMetaFiles: true, remoteHostId, deviceId, showIgnoredDirs });
const fileContent = useFileContent(workdir, state.selectedFilePath, remoteHostId, deviceId);
const [externalFile, setExternalFile] = useState<ExternalFileSelection | null>(null);
const [imageLightboxSrc, setImageLightboxSrc] = useState<string | null>(null);
@@ -642,6 +646,7 @@ function FileBrowserBodyWithWorkdir({
onToggleSearch={handleToggleSearch}
onCollapseAll={tree.collapseAll}
onRefresh={handleRefresh}
+ ignoredDirsUnsupported={tree.showIgnoredDirsSupported === false}
/>
{/* tree 模式:常驻文件名筛选输入框 + (筛选结果列表 / 文件树)。
注:className 必须**只在隐藏时**加 `hidden`,**不能**同时写 `block` ——
@@ -727,7 +732,7 @@ function FileBrowserBodyWithWorkdir({
* 视觉对齐 doc 模式 WorkdirBrowseSidebar(参考 L570-678):
* - 整行 pt-2 pb-1 pl-3 pr-2(窄栏比 doc 模式 pl-6 pr-3 紧)
* - 标题 text-sm font-semibold text-foreground
- * - icon 按钮 size-5 rounded-md hover:bg-sidebar-item-active text-sidebar-action-icon
+ * - icon 按钮共用 FileTreeHeaderActions(DESIGN.md §5 控件框 pill 档)
*/
function TreeHeader({
workdir,
@@ -735,14 +740,16 @@ function TreeHeader({
onToggleSearch,
onCollapseAll,
onRefresh,
+ ignoredDirsUnsupported,
}: {
workdir: string;
mode: TreeMode;
onToggleSearch: () => void;
onCollapseAll: () => void;
onRefresh: () => void;
+ /** 被控端不支持「显示被忽略的目录」(老 Desktop):开关渲染成不可用 + 说明原因。 */
+ ignoredDirsUnsupported: boolean;
}) {
- const { t } = useTranslation();
// workdir basename:POSIX 用最后一段(/Users/sam/Documents/Cindy → Cindy);
// Windows 'C:\\Users\\sam\\Cindy' 也按 / 和 \ 切。空值兜底空串。
const displayName = workdir.split(/[/\\]/).filter(Boolean).pop() ?? '';
@@ -753,49 +760,15 @@ function TreeHeader({
{displayName}
</span>
<div className="flex shrink-0 items-center gap-1.5">
- {mode === 'search' ? (
- // search 模式:refresh / collapse 只对文件树有意义,搜索时不显示;只留 X
- // 退出搜索回到 tree 模式(替代 search 按钮位置,跟 doc 模式同 ergonomics)。
- <Tip text={t('ccAgent.workdirBrowse.searchPanel.exit')}>
- <button
- type="button"
- onClick={onToggleSearch}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <XIcon size={14} strokeWidth={2} />
- </button>
- </Tip>
- ) : (
- <>
- <Tip text={t('ccAgent.workdirBrowse.searchPanel.searchFiles')}>
- <button
- type="button"
- onClick={onToggleSearch}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <Search size={14} strokeWidth={2} />
- </button>
- </Tip>
- <Tip text={t('ccAgent.workdirBrowse.treeAction.collapseAll')}>
- <button
- type="button"
- onClick={onCollapseAll}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <ChevronsDownUp size={14} strokeWidth={2} />
- </button>
- </Tip>
- <Tip text={t('ccAgent.workdirBrowse.treeAction.refresh')}>
- <button
- type="button"
- onClick={onRefresh}
- className="flex size-5 items-center justify-center rounded-md text-sidebar-action-icon hover:bg-sidebar-item-active hover:text-sidebar-item-active-foreground"
- >
- <RefreshCw size={14} strokeWidth={2} />
- </button>
- </Tip>
- </>
- )}
+ {/* 搜索 / 显示被忽略的目录 / 收起 / 刷新(搜索态只剩退出搜索)——
+ 与 doc 模式侧栏共用 FileTreeHeaderActions,不再各维护一份。 */}
+ <FileTreeHeaderActions
+ mode={mode}
+ onToggleSearch={onToggleSearch}
+ onCollapseAll={onCollapseAll}
+ onRefresh={onRefresh}
+ ignoredDirsUnsupported={ignoredDirsUnsupported}
+ />
</div>
</div>
);
diff --git a/apps/desktop/src/renderer/hooks/__tests__/useFileBrowserPreference.test.ts b/apps/desktop/src/renderer/hooks/__tests__/useFileBrowserPreference.test.ts
new file mode 100644
index 0000000000..a7b6593094
--- /dev/null
+++ b/apps/desktop/src/renderer/hooks/__tests__/useFileBrowserPreference.test.ts
@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+
+/**
+ * useFileBrowserPreference — 覆盖「显示被忽略的目录」的 override 语义(规则 20):
+ * - 默认关闭(保持历史行为);localStorage 只存 override
+ * - 打开 → 写入;改回默认 → 删除 key(清 override)
+ * - 非法存储值回落默认
+ * - 误写入的默认值('false')也算显式 override(Cindy 会显示「恢复默认」)
+ */
+
+import { beforeEach, describe, expect, it } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+
+import {
+ _resetFileBrowserPreferenceForTests,
+ getShowIgnoredDirs,
+ useFileBrowserPreference,
+} from '../useFileBrowserPreference';
+
+const KEY = 'fileBrowser.showIgnoredDirs';
+
+describe('useFileBrowserPreference', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ _resetFileBrowserPreferenceForTests();
+ });
+
+ it('无 override 时默认隐藏被忽略目录', () => {
+ expect(getShowIgnoredDirs()).toBe(false);
+ const { result } = renderHook(() => useFileBrowserPreference());
+ expect(result.current.showIgnoredDirs).toBe(false);
+ expect(result.current.isCustomized).toBe(false);
+ });
+
+ /**
+ * 评审 P1:本窗口在没有任何消费者的窗口期里摘掉了 storage listener,期间另一个
+ * 窗口改了偏好就收不到事件;重挂载时 readPreference 又会走模块级缓存早退,会让
+ * 开关与文件树永久陈旧到下一次变更或刷新。所以首个监听者(重)挂载时要让缓存
+ * 失效、回落 localStorage。
+ */
+ it('无消费者窗口期后重挂载会重读 localStorage', () => {
+ const first = renderHook(() => useFileBrowserPreference());
+ expect(first.result.current.showIgnoredDirs).toBe(false);
+ first.unmount(); // → 本窗口没有监听者了
+
+ // 另一个窗口改了偏好:只落 localStorage,本窗口收不到 storage 事件。
+ localStorage.setItem(KEY, 'true');
+
+ const second = renderHook(() => useFileBrowserPreference());
+ expect(second.result.current.showIgnoredDirs).toBe(true);
+ expect(second.result.current.isCustomized).toBe(true);
+ });
+
+ it('读取已存的开启 override', () => {
+ localStorage.setItem(KEY, 'true');
+ expect(getShowIgnoredDirs()).toBe(true);
+ const { result } = renderHook(() => useFileBrowserPreference());
+ expect(result.current.showIgnoredDirs).toBe(true);
+ expect(result.current.isCustomized).toBe(true);
+ });
+
+ it('非法存储值回落默认', () => {
+ localStorage.setItem(KEY, 'whatever');
+ expect(getShowIgnoredDirs()).toBe(false);
+ });
+
+ it('开启写 override;改回默认删除 key', () => {
+ const { result } = renderHook(() => useFileBrowserPreference());
+
+ act(() => result.current.setShowIgnoredDirs(true));
+ expect(localStorage.getItem(KEY)).toBe('true');
+ expect(getShowIgnoredDirs()).toBe(true);
+ expect(result.current.isCustomized).toBe(true);
+
+ act(() => result.current.setShowIgnoredDirs(false));
+ expect(localStorage.getItem(KEY)).toBeNull();
+ expect(getShowIgnoredDirs()).toBe(false);
+ expect(result.current.isCustomized).toBe(false);
+ });
+
+ it('存储不可用时内存 SoT 仍生效', () => {
+ const original = Object.getOwnPropertyDescriptor(window, 'localStorage');
+ Object.defineProperty(window, 'localStorage', {
+ configurable: true,
+ get() {
+ throw new Error('storage disabled');
+ },
+ });
+ try {
+ const { result } = renderHook(() => useFileBrowserPreference());
+ act(() => result.current.setShowIgnoredDirs(true));
+ expect(result.current.showIgnoredDirs).toBe(true);
+ } finally {
+ if (original) Object.defineProperty(window, 'localStorage', original);
+ }
+ });
+});
diff --git a/apps/desktop/src/renderer/hooks/useFileBrowserPreference.ts b/apps/desktop/src/renderer/hooks/useFileBrowserPreference.ts
new file mode 100644
index 0000000000..c8361ac8d4
--- /dev/null
+++ b/apps/desktop/src/renderer/hooks/useFileBrowserPreference.ts
@@ -0,0 +1,127 @@
+/**
+ * useFileBrowserPreference — 侧边栏文件浏览器的视图偏好。
+ * ---------------------------------------------------------------------------
+ * 当前只有一个开关:
+ * - showIgnoredDirs 文件树是否列出 Cindy 默认隐藏的目录(依赖 / 构建产物 /
+ * 缓存:,如 build / dist / out / node_modules / Library)。
+ * 默认 false = 保持历史行为。
+ *
+ * 规则 20(配置默认值 vs override):localStorage 只存 override——用户改回
+ * 默认值时**删除** key 而不是写入,这样未自定义的用户未来能跟随新版本默认值;
+ * isCustomized 即「存在 override」。
+ *
+ * 模块级内存 SoT + `storage` 事件跨窗口同步(同 useLinkOpenPreference /
+ * useMessageNavRailPreference)。文件浏览器在 RSB 分离窗口里会单独挂载,而
+ * 两个窗口共享同一份 localStorage,storage 事件把改动同步过去。
+ *
+ * 消费方:`WorkdirBrowseSidebar`(doc 模式侧栏)与 RSB 的 `FileBrowserBody`
+ * 都把它喂给 `useFileTree`,store 的 key 包含该开关 → 切换开关会换 store,
+ * 连带 listDir 与 watcher 用新的 matcher 重建。
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+
+const STORAGE_KEY = 'fileBrowser.showIgnoredDirs';
+/** 系统默认:隐藏(与 BUILTIN_IGNORE 的历史行为一致,Unity Library 之类目录太大)。 */
+const DEFAULT_SHOW_IGNORED_DIRS = false;
+/** override 的持久化形态;只有非默认值会落盘。 */
+const STORED_ENABLED = 'true';
+
+function parseStored(raw: string | null): { value: boolean; customized: boolean } {
+ if (raw === STORED_ENABLED) return { value: true, customized: true };
+ if (raw === 'false') return { value: false, customized: true };
+ return { value: DEFAULT_SHOW_IGNORED_DIRS, customized: false };
+}
+
+/** 模块级内存 SoT;null = 尚未被本窗口读定/写定。 */
+let memoryValue: boolean | null = null;
+let memoryCustomized: boolean | null = null;
+
+function readPreference(): { value: boolean; customized: boolean } {
+ if (memoryValue !== null && memoryCustomized !== null) {
+ return { value: memoryValue, customized: memoryCustomized };
+ }
+ try {
+ const parsed = parseStored(localStorage.getItem(STORAGE_KEY));
+ memoryValue = parsed.value;
+ memoryCustomized = parsed.customized;
+ return parsed;
+ } catch {
+ // localStorage 不可用——退回默认(不落定内存,留待后续写入)。
+ return { value: DEFAULT_SHOW_IGNORED_DIRS, customized: false };
+ }
+}
+
+/** 同步读——给非 hook 路径用。 */
+export function getShowIgnoredDirs(): boolean {
+ return readPreference().value;
+}
+
+const listeners = new Set<() => void>();
+
+export function useFileBrowserPreference(): {
+ showIgnoredDirs: boolean;
+ /** 是否存在用户 override(≠ 系统默认)。设置页据此显示「恢复默认」。 */
+ isCustomized: boolean;
+ setShowIgnoredDirs: (next: boolean) => void;
+} {
+ const [preference, setPreference] = useState(readPreference);
+
+ const setShowIgnoredDirs = useCallback((next: boolean) => {
+ memoryValue = next;
+ memoryCustomized = next !== DEFAULT_SHOW_IGNORED_DIRS;
+ setPreference({ value: next, customized: memoryCustomized });
+ try {
+ if (next === DEFAULT_SHOW_IGNORED_DIRS) {
+ // 改回默认 = 清除 override(而非写入默认值快照)。
+ localStorage.removeItem(STORAGE_KEY);
+ } else {
+ localStorage.setItem(STORAGE_KEY, STORED_ENABLED);
+ }
+ } catch {
+ // localStorage 不可用——内存 SoT 已生效;仅跨窗口同步缺失。
+ }
+ listeners.forEach((fn) => fn());
+ }, []);
+
+ useEffect(() => {
+ const sync = () => setPreference(readPreference());
+ // 首个监听者(重)挂载时让模块级缓存失效、回落 localStorage:本窗口可能在
+ // 没有任何消费者的窗口期里错过另一个窗口的 storage 事件(那时 listener 不在
+ // 场),不重读就会让开关与文件树永久陈旧到下一次变更或刷新(评审 P1)。
+ if (listeners.size === 0) {
+ memoryValue = null;
+ memoryCustomized = null;
+ }
+ // 每个订阅者注册时都同步一次:只听首个订阅者会让后来者(如开关与文件树分别
+ // 挂载)拿首帧旧值,而第一个订阅者已更新缓存、后来者又跳过 sync,两边就一直
+ // 不一致(开关已打开、目录仍隐藏)。
+ sync();
+ listeners.add(sync);
+ const onStorage = (e: StorageEvent) => {
+ if (e.key !== STORAGE_KEY) return;
+ const next = parseStored(e.newValue);
+ memoryValue = next.value;
+ memoryCustomized = next.customized;
+ sync();
+ };
+ window.addEventListener('storage', onStorage);
+ return () => {
+ listeners.delete(sync);
+ window.removeEventListener('storage', onStorage);
+ };
+ }, []);
+
+ return {
+ showIgnoredDirs: preference.value,
+ isCustomized: preference.customized,
+ setShowIgnoredDirs,
+ };
+}
+
+/** 测试专用:清空内存 SoT,让下一次读回落 localStorage / 默认值。 */
+export function _resetFileBrowserPreferenceForTests(): void {
+ memoryValue = null;
+ memoryCustomized = null;
+ listeners.clear();
+}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index eff8d2e207..12aac62f29 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -13260,7 +13260,10 @@
"treeLoading": "Loading files…",
"treeAction": {
"collapseAll": "Collapse all",
- "refresh": "Refresh"
+ "refresh": "Refresh",
+ "showIgnoredDirs": "Show ignored directories",
+ "hideIgnoredDirs": "Hide ignored directories",
+ "showIgnoredDirsUnsupported": "The remote device is running an older {{appName}} version that cannot show ignored directories"
},
"treeMenu": {
"newFile": "New File",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index ef86e6424f..03ff59c05d 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -13212,7 +13212,10 @@
"treeLoading": "ファイルを読み込み中…",
"treeAction": {
"collapseAll": "すべて折りたたむ",
- "refresh": "更新"
+ "refresh": "更新",
+ "showIgnoredDirs": "無視されるディレクトリを表示",
+ "hideIgnoredDirs": "無視されるディレクトリを隠す",
+ "showIgnoredDirsUnsupported": "相手デバイスの {{appName}} のバージョンが古く、無視されるディレクトリを表示できません"
},
"treeMenu": {
"newFile": "新規ファイル",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index e0bdf41b61..150e6c0cf0 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -13212,7 +13212,10 @@
"treeLoading": "파일 불러오는 중…",
"treeAction": {
"collapseAll": "모두 접기",
- "refresh": "새로 고침"
+ "refresh": "새로 고침",
+ "showIgnoredDirs": "무시된 디렉터리 표시",
+ "hideIgnoredDirs": "무시된 디렉터리 숨기기",
+ "showIgnoredDirsUnsupported": "상대 기기의 {{appName}} 버전이 오래되어 무시된 디렉터리를 표시할 수 없습니다"
},
"treeMenu": {
"newFile": "새 파일",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index 751df5ec8e..8f0bdfaf3c 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -13212,7 +13212,10 @@
"treeLoading": "正在加载文件…",
"treeAction": {
"collapseAll": "收起所有",
- "refresh": "刷新"
+ "refresh": "刷新",
+ "showIgnoredDirs": "显示被忽略的目录",
+ "hideIgnoredDirs": "隐藏被忽略的目录",
+ "showIgnoredDirsUnsupported": "对方设备的 {{appName}} 版本过旧,暂不支持显示被忽略的目录"
},
"treeMenu": {
"newFile": "新建文件",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 8f666862f1..a4aaa1c7bc 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -13212,7 +13212,10 @@
"treeLoading": "正在載入檔案…",
"treeAction": {
"collapseAll": "收起所有",
- "refresh": "重新整理"
+ "refresh": "重新整理",
+ "showIgnoredDirs": "顯示被忽略的目錄",
+ "hideIgnoredDirs": "隱藏被忽略的目錄",
+ "showIgnoredDirsUnsupported": "對方裝置的 {{appName}} 版本過舊,暫不支援顯示被忽略的目錄"
},
"treeMenu": {
"newFile": "新建檔案",
diff --git a/apps/desktop/src/renderer/lib/fileBrowserTransport.ts b/apps/desktop/src/renderer/lib/fileBrowserTransport.ts
index 7c0534adcd..90cd12858a 100644
--- a/apps/desktop/src/renderer/lib/fileBrowserTransport.ts
+++ b/apps/desktop/src/renderer/lib/fileBrowserTransport.ts
@@ -67,6 +67,93 @@ function deviceSupportsGzip(deviceId: string, workdir: string): Promise<boolean>
return probe;
}
+/**
+ * 被控端 listDir 是否支持 `showIgnoredDirs`(「显示被忽略的目录」)。
+ *
+ * **三态**:`true` / `false` = 已探定的结论;`null` = 未知(瞬态失败) —— 调用方据此
+ * 保持「还没结论」,不要把一次网络抖动落定成「对方版本过旧」并用它把开关禁用掉。
+ *
+ * 区分确定性「不支持」与瞬态失败:老被控端根本没有 `file-browser:remote-op`
+ * channel,invoke 会被快速拒回 `CHANNEL_NOT_ALLOWED`(确定性);隧道不可达 /
+ * 重连中的 reject 与之不同,属于瞬态。
+ *
+ * 缓存:**只缓存肯定结论 `true`**,且带**进程级重连代次**(见下)。`false`(老端)
+ * 不留在缓存里 —— 被控端在一次掉线期间升级是真实场景,缓存会把它钉在「不支持」
+ * 直到重启;重探一次只是一个被快速拒绝的 invoke,代价可忽略。瞬态 `null` 同样
+ * 不缓存,由调用方在连接恢复后重探。
+ *
+ * 与 gzip 那份缓存分开:后者带着「用出空写就永久降级」的自愈语义,两件事互不牵连。
+ */
+
+/**
+ * 进程级重连代次。
+ *
+ * 不能拿 hook 局的 `useDeviceLinkReconnectEpoch` 当缓存依据:它是 `useState(0)`
+ * 起步的 hook 局部计数器,只观察**挂载期间**的事件 —— 面板卸载 →(此时设备重连 /
+ * 被回滚,没有任何 hook 看得到)→ 面板重挂载时新实例又从 0 开始,进程内的缓存却
+ * 还留着上一代的肯定结论,于是跳过 caps RPC、开关一直可按。
+ *
+ * 所以缓存自己订阅全局 reconnect 流:模块级订阅不随面板生命周期起落(惰性建立
+ * 于首次调用;测试环境没有 deviceLink 时静默跳过,代次恒 0)。任何设备恢复 online
+ * 或 relay 恢复 online 都让整表代次作废 —— 重探一次 caps 很便宜,不值得按 deviceId
+ * 精细区分。订阅故意常驻:它本身就是「面板不在时也要记账」的那只耳朵。
+ */
+let reconnectGeneration = 0;
+let reconnectSubscribed = false;
+
+function ensureReconnectSubscription(): void {
+ if (reconnectSubscribed) return;
+ const api = window.electronAPI?.deviceLink;
+ if (!api?.onPresenceChanged || !api.onStatusChanged) return;
+ reconnectSubscribed = true;
+ const bump = (): void => {
+ reconnectGeneration += 1;
+ };
+ api.onPresenceChanged((snapshot) => {
+ if (snapshot.online) bump();
+ });
+ api.onStatusChanged(({ status }) => {
+ if (status === 'online') bump();
+ });
+}
+
+const deviceRevealCaps = new Map<
+ string,
+ { generation: number; probe: Promise<boolean | null> }
+>();
+
+/** 只回收「本次探测装上的那条」:同 deviceId 可能已因更新的代次换上新的 probe。 */
+function evictRevealCapsIfCurrent(deviceId: string, generation: number): void {
+ if (deviceRevealCaps.get(deviceId)?.generation === generation) {
+ deviceRevealCaps.delete(deviceId);
+ }
+}
+
+export function deviceSupportsRevealIgnoredDirs(
+ deviceId: string,
+ workdir: string,
+): Promise<boolean | null> {
+ ensureReconnectSubscription();
+ const cached = deviceRevealCaps.get(deviceId);
+ if (cached && cached.generation === reconnectGeneration) return cached.probe;
+ const probeGeneration = reconnectGeneration;
+ const probe = Promise.resolve()
+ .then(() => invokeOp<{ ok: boolean; showIgnoredDirs?: boolean }>(deviceId, 'caps', { workdir }))
+ .then((r) => {
+ const supported = r?.ok === true && r.showIgnoredDirs === true;
+ // 只留肯定结论;「不支持」下次重新问(被控端可能已升级)。
+ if (!supported) evictRevealCapsIfCurrent(deviceId, probeGeneration);
+ return supported;
+ })
+ .catch((err: unknown) => {
+ evictRevealCapsIfCurrent(deviceId, probeGeneration);
+ if (isDeviceTooOldError(err)) return false; // 老端:确定性不支持
+ return null; // 瞬态:不落定,等连接恢复重探
+ });
+ deviceRevealCaps.set(deviceId, { generation: probeGeneration, probe });
+ return probe;
+}
+
export interface FileTreeEventPayload {
workdir: string;
type: 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
@@ -214,7 +301,18 @@ export function deviceSearchCollect(
*/
export async function startWatchFor(
deviceId: string | null | undefined,
- params: { workdir: string; remoteHostId?: string | null; hideMetaFiles?: boolean },
+ params: {
+ workdir: string;
+ remoteHostId?: string | null;
+ hideMetaFiles?: boolean;
+ /**
+ * 「显示被忽略的目录」:本地 / SSH 分支下发到 matcher 与 watcher;
+ * **device 分支不传**——被控端的 watch 由 `fs-watch:<workdir>` topic
+ * 订阅驱动,订阅载荷里没有过滤开关(与 hideMetaFiles 同款限制),
+ * 所以被控端 watcher 仍用默认过滤:目录能列出、内部改动不推事件。
+ */
+ showIgnoredDirs?: boolean;
+ },
): Promise<void> {
if (!deviceId) {
await window.electronAPI.fileBrowser.startWatch(params);
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index 5e58fd8140..c353ee2b97 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -2649,6 +2649,8 @@ interface ElectronAPI {
relPath?: string;
hideMetaFiles?: boolean;
docMode?: boolean;
+ /** 「显示被忽略的目录」——列出依赖 / 构建产物 / 缓存目录。默认 false。 */
+ showIgnoredDirs?: boolean;
}) => Promise<
Array<{
name: string;
@@ -2748,6 +2750,8 @@ interface ElectronAPI {
remoteHostId?: string | null;
workdir: string;
hideMetaFiles?: boolean;
+ /** 与 listDir 同源:开关变了要带新 matcher 重建 watcher。 */
+ showIgnoredDirs?: boolean;
}) => Promise<{ ok: boolean }>;
stopWatch: (params: {
remoteHostId?: string | null;
diff --git a/apps/desktop/src/shared/ignoreNames.ts b/apps/desktop/src/shared/ignoreNames.ts
new file mode 100644
index 0000000000..fabc31b7a8
--- /dev/null
+++ b/apps/desktop/src/shared/ignoreNames.ts
@@ -0,0 +1,19 @@
+/**
+ * ignoreNames — 内置忽略名单(纯数据)。
+ *
+ * 真源已迁至 @cindy/file-browser-core:desktop main / renderer 与远端
+ * file-service daemon 三处共享同一份定义,避免名单在客户端与 daemon 之间漂移。
+ * renderer 侧用它做「关掉『显示被忽略的目录』时,立刻滤掉 reveal 态根列表里的
+ * 一级忽略目录」(见 useFileTree 的 seed 说明)——慢通道下不这样滤,关开关后
+ * node_modules / build 这些行会在「已隐藏」的视图里滞留数秒。
+ *
+ * ⚠️ 必须走 /ignoreNames 子路径导出而不是包根:本文件被 renderer 消费,包根
+ * barrel 会把 scanner / RipgrepSearcher 等 Node-only 实现(node:fs、node:path)
+ * 一起拖进浏览器 bundle(同类说明见 shared/textFileExts.ts)。
+ */
+
+export {
+ BUILTIN_IGNORE_ALWAYS,
+ BUILTIN_IGNORE_REVEALABLE,
+ REVEALABLE_IGNORE_DIR_NAMES,
+} from '@cindy/file-browser-core/ignoreNames';
diff --git a/docs/design-evidence/2026-09-11/file-tree-header-icon-buttons.md b/docs/design-evidence/2026-09-11/file-tree-header-icon-buttons.md
new file mode 100644
index 0000000000..bb92ada3d2
--- /dev/null
+++ b/docs/design-evidence/2026-09-11/file-tree-header-icon-buttons.md
@@ -0,0 +1,97 @@
+# 文件树标题行图标钮圆角统一(#4301)
+
+日期:2026-09-11。平台:Desktop / Windows(用户本机 dev 实例,`DESKTOP_DEV_VERDICT=ready`)。
+基点:`64520dd75`(本批本地未提交改动)。采集时 head 与仓库工作区一致。
+
+设计依据:`DESIGN.md §5 Border Radius Scale` Step 2 —— 控件框(含 transient
+hover / pressed 表面)登记在 pill 档,`No 3px / 6px / 10px`;`§14.6` 图标钮的
+`aria-label` + tooltip 交付合同。治理依据:`design-governance.md §13.3`(圆角分类
+审查边界:须指出登记项与作用层,不得用建议改形状代替分类裁决)。
+
+## 本次改了什么
+
+文件树标题行原先只有新增的「显示被忽略的目录」开关走 pill,同排三个存量图标钮
+(搜索 / 收起 / 刷新)各自写 `rounded-md`(6px),同一行出现两种圆角。改为四个按钮
+(含搜索态的 X)共用 `FILE_TREE_HEADER_ICON_BUTTON_CLASS`,统一 pill;doc 模式宿主
+的标题触发器(项目名下拉)同排,同步收为 pill。两个宿主的图标钮类名不再各自复制。
+
+## 有意差异登记
+
+| 表面 | 改前 | 改后 | 依据 |
+| --- | --- | --- | --- |
+| RSB 文件浏览器标题行:搜索 / 显示被忽略的目录 / 收起 / 刷新(+ 搜索态 X) | 6px(新开关已是 pill) | 9999px | §5 Step 2 控件框 = pill |
+| doc 模式侧栏标题行:同上四个按钮 | 6px | 9999px | 同上 |
+| doc 模式侧栏标题触发器(项目名 + ChevronDown) | 6px | 9999px | 同一行的控件框、同样带 hover 表面 |
+
+未改:该行之外的同文件控件(错误态「重试」文字按钮、切换项目下拉项)不属本行,
+按存量随各自表面迁移处理,未借本次改动一并迁移。
+
+## 自动检查
+
+```
+pnpm --filter desktop run typecheck 通过
+vitest FileTreeIgnoredDirsToggle.test.tsx 12 passed
+ (含几何守卫与 aria-label 守卫:两个宿主的标题行图标钮必须走共享常量、必须带可访问名)
+vitest typographyDiscipline 5 passed
+vitest useFileTree / useFileBrowserPreference 12 passed
+vitest expandedStore 3 passed(新增:展开态按 showIgnoredDirs 分片)
+node scripts/design-inventory.mjs 已重新生成(49 surfaces)
+node scripts/hardcoded-color-audit.mjs 新增硬编码颜色 0
+pnpm test:unit:related 通过(desktop 全量 + file-browser-core / remote-file-service)
+```
+
+## 真实 Desktop 构建内的实测值
+
+dev 实例(本 checkout,独立命名沙箱 `dev`)经 CDP `Runtime.evaluate` +
+`getComputedStyle` 取实测值;截图由 `Page.captureScreenshot` 采集。
+
+| 主题(`data-theme`) | 未按下:图标色 / 圆角 / 尺寸 | 按下:底色 / 图标色 | `--sidebar-item-active` |
+| --- | --- | --- | --- |
+| `cindy-light` | `rgb(136,136,131)` / 9999px / 20×20 | `rgb(60,63,67)` / `rgb(252,252,252)` | `214.3 5.5% 24.9%` |
+| `cindy-dark` | `rgb(111,111,111)` / 9999px / 20×20 | `rgb(238,238,238)` / `rgb(21,21,21)` | `0.0 0.0% 93.3%` |
+
+- 两个宿主各四个按钮实测圆角全部 `9999px`(改前三个为 6px);按钮 20×20、图标 14。
+- 按下态在两种主题下都有持久底色(非仅 hover 可见),与 token 值一致。
+- 四个按钮的图标色在 idle 态一致(来自 `--sidebar-action-icon`)。
+
+## 目检
+
+RSB 文件浏览器(会话视图右栏)与 doc 模式侧栏(`#/cc-agent/files/<sessionId>`)
+两种布局 × Light / Dark 共 4 张截图已由作者目检:入口位置(眼睛按钮在搜索右侧)、
+按下态反馈、图标变化(EyeOff ↔ Eye)与 tooltip 文案均符合预期;开关打开后
+`node_modules` / `logs` 等目录出现在树里(即本次改动要修的场景)。
+
+2026-09-13 在 `cindy/fierce-goodall-p3@23600c41d` 上重新采集了同规格 4 张
+(RSB / doc × Light / Dark,开关为打开态,树里 `build` / `node_modules` 可见),
+已上传为 PR 评论可见证据(链接见「缺口登记」)。
+
+## 缺口登记
+
+- **unsupported 禁用态未实机目检**(评审修复轮新增):该状态只在 device-link 连到不支持
+ `showIgnoredDirs` 的老 Desktop 时出现,本机无该环境。可见面为 `aria-disabled` +
+ `opacity-45` + `cursor-not-allowed`(与仓库内 `PermissionSelector` 禁用项同款),
+ 行为(点击不改偏好、树按隐藏态建立)由单测锁定。
+- 远端 SSH 会话未实机验证(无可用远端环境):远端 `listDir` 的开关透传与
+ daemon 事件过滤只在单测层面覆盖,见 PR「未执行的验证」。
+- 截图已上传 PR:GitHub 图片附件端点依赖网页会话,本次以 fork release asset 作为稳定
+ artifact 承载(`https://github.com/zyjisdog/cindy/releases/tag/design-evidence-4398`),
+ PR 评论入口:<https://github.com/makecindy/cindy/pull/4398#issuecomment-5652260136>。
+ 本地同步保留一份 `tmp/design-evidence/{rsb,doc}-{light,dark}-flat.png`(gitignore
+ 覆盖的临时目录,栅格不入仓)。
+- 换肤中间帧未验证:截图前已等主题切换完成(设置页切换后等渲染稳定再采集),未检查换肤动画时序。
+- 窗口背景透明(vibrancy),CDP 原图含 `alpha=0` 区域;本目录引用的查看版本已把
+ alpha 展平到对应主题表面色上,避免看图工具各自合成底色导致误判明暗。
+
+## 采集版本源码 SHA-256
+
+哈希按文件内容的 LF 规范化形态计算(`sed 's/\r$//' <file> | sha256sum`,与 Git blob 一致)。
+下表已更新到**评审修复轮 + 虚拟滚动轮之后**的源码:默认态 / 按下态的实测值仍然适用
+(此后只加过 aria-label、unsupported 禁用态、展开态分片与虚拟滚动接线;标题行控件本身的
+配色 / 圆角 / 尺寸未变),unsupported 禁用态本身未实机目检(见「缺口登记」)。
+
+| 文件 | SHA-256 |
+| --- | --- |
+| `features/cc-agent/workdir-browse/fileTreeHeaderButtonClass.ts` | `571c2021d9589b99141e8ca2c07331f7bab7994384f0a860d3a55534a2232840` |
+| `features/cc-agent/workdir-browse/FileTreeIgnoredDirsToggle.tsx` | `de2b2070c559c3f82410761c34e35f84c6fb0cf62fcc78b2eff49b5991f69726` |
+| `features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx` | `9733c40b3d319a37c1ab79fe060c4216c835f3967a55472a6562b157a73eb1ea` |
+| `features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx` | `67a095a2d548546bf7cc39dd1e1a9c2083d9079bbba1db7a939d0defb8cbd0e3` |
diff --git a/docs/design-rules/design-inventory.md b/docs/design-rules/design-inventory.md
index c4f43c8b16..7948ec3eab 100644
--- a/docs/design-rules/design-inventory.md
+++ b/docs/design-rules/design-inventory.md
@@ -19,7 +19,7 @@
| `desktop.auth.legacy-migration` | desktop | 首登数据迁移弹窗 | App 顶层挂载 LegacyMigrationDialog(仅主窗;main 检测到旧版 userData 经 `legacy-migration:state` 驱动) | LegacyMigrationDialog | apps/desktop/src/renderer/components/auth/LegacyMigrationDialog.tsx | 8 | 0 | 2 |
| `desktop.auth.login` | desktop | 登录页 | hash `/login`(GuestRoute → LoginPage) | LoginBrandStage, LoginCaptchaOverlay, LoginControls, LoginPage | apps/desktop/src/renderer/components/login/LoginBrandStage.tsx, apps/desktop/src/renderer/components/login/LoginCaptchaOverlay.tsx, apps/desktop/src/renderer/components/login/LoginControls.tsx, apps/desktop/src/renderer/components/login/LoginPage.tsx, apps/desktop/src/renderer/components/login/loginDesignTokens.ts | 59 | 0 | 20 |
| `desktop.bots` | desktop | 伙伴(列表 / 对话 / 设置 / 历史 / 伙伴私聊 / 群聊) | hash `/bots`、`/bots/list`、`/bots/:botId`、`/bots/roster` 及伙伴当前/历史任务、伙伴私聊、伙伴群聊路由(BotsFeatureLayout) | BotBasicProfileFields, BotCollaborationCard, BotDirectMessageView, BotGroupChatView, BotGroupCreateDialog, BotGroupSettingsDrawer, BotHistorySessionView, BotLifecycleSettings, BotMarketDialog, BotModelChainEditor, BotRosterView, BotSessionView, BotSettingsDrawer, BotsHomeView, BotsListView, RemoteBotSessionView | apps/desktop/src/renderer/components/chat/AgentActionRow.tsx, apps/desktop/src/renderer/components/chat/AgentActionsBlock.tsx, apps/desktop/src/renderer/components/chat/AgentTaskCard.tsx, apps/desktop/src/renderer/components/chat/AgentTaskLiveDetails.tsx, apps/desktop/src/renderer/components/chat/AnnotationStrokesSvg.tsx, apps/desktop/src/renderer/components/chat/AskUserQuestionBubble.tsx, apps/desktop/src/renderer/components/chat/AssistantMessage.tsx, apps/desktop/src/renderer/components/chat/AutomationOriginBadge.tsx, apps/desktop/src/renderer/components/chat/ChatAudioCard.tsx, apps/desktop/src/renderer/components/chat/ChatDisplaySnapshotContext.tsx, apps/desktop/src/renderer/components/chat/ChatImageView.tsx, apps/desktop/src/renderer/components/chat/ChatLoadingImage.tsx, apps/desktop/src/renderer/components/chat/ChatReplyIcon.tsx, apps/desktop/src/renderer/components/chat/ChatSessionFileContext.tsx, apps/desktop/src/renderer/components/chat/ChatSoundEffectCard.tsx, apps/desktop/src/renderer/components/chat/ChatVideoView.tsx, apps/desktop/src/renderer/components/chat/CindyMakeDoctorCard.tsx, apps/desktop/src/renderer/components/chat/CopyAsImageBlock.tsx, apps/desktop/src/renderer/components/chat/CredentialSwitchWaitBanner.tsx, apps/desktop/src/renderer/components/chat/DiffView.tsx, apps/desktop/src/renderer/components/chat/ErrorBanner.tsx, apps/desktop/src/renderer/components/chat/ErrorMessageCard.tsx, apps/desktop/src/renderer/components/chat/GeneratedFilesCard.tsx, apps/desktop/src/renderer/components/chat/GhostCardForm.tsx, apps/desktop/src/renderer/components/chat/GhostCardHostPrompts.tsx, apps/desktop/src/renderer/components/chat/GhostCardRecipients.tsx, apps/desktop/src/renderer/components/chat/GhostMailHistory.tsx, apps/desktop/src/renderer/components/chat/GhostSummonCard.tsx, apps/desktop/src/renderer/components/chat/GhostToolCard.tsx, apps/desktop/src/renderer/components/chat/HookTaskCard.tsx, apps/desktop/src/renderer/components/chat/ImageGalleryContext.tsx, apps/desktop/src/renderer/components/chat/ImageHoverPreview.tsx, apps/desktop/src/renderer/components/chat/ImageLightbox.tsx, apps/desktop/src/renderer/components/chat/ImageMissingPlaceholder.tsx, apps/desktop/src/renderer/components/chat/InlineReferenceChip.tsx, apps/desktop/src/renderer/components/chat/InterruptedTurnBanner.tsx, apps/desktop/src/renderer/components/chat/JumpToBottomChip.tsx, apps/desktop/src/renderer/components/chat/MailHtmlPreview.tsx, apps/desktop/src/renderer/components/chat/MarkdownDiffBlock.tsx, apps/desktop/src/renderer/components/chat/MarkdownMermaidBlock.tsx, apps/desktop/src/renderer/components/chat/MarkdownRenderer.tsx, apps/desktop/src/renderer/components/chat/McpAppCard.tsx, apps/desktop/src/renderer/components/chat/MermaidLightbox.tsx, apps/desktop/src/renderer/components/chat/MessageActionBar.tsx, apps/desktop/src/renderer/components/chat/MessageNavRail.tsx, apps/desktop/src/renderer/components/chat/MessageReadAloudContext.ts, apps/desktop/src/renderer/components/chat/MessageSourceLabels.tsx, apps/desktop/src/renderer/components/chat/MessageStream.tsx, apps/desktop/src/renderer/components/chat/MessageViewport.tsx, apps/desktop/src/renderer/components/chat/ModelLightbox.tsx, apps/desktop/src/renderer/components/chat/NewMessageIndicator.tsx, apps/desktop/src/renderer/components/chat/PlanReviewBubble.tsx, apps/desktop/src/renderer/components/chat/PrevMessageJumpChip.tsx, apps/desktop/src/renderer/components/chat/ProjectLinkChip.tsx, apps/desktop/src/renderer/components/chat/QuoteChip.tsx, apps/desktop/src/renderer/components/chat/RewindPreviewDialog.tsx, apps/desktop/src/renderer/components/chat/RichAnswer.tsx, apps/desktop/src/renderer/components/chat/SelectionQuoteButton.tsx, apps/desktop/src/renderer/components/chat/SentAgentReferenceChip.tsx, apps/desktop/src/renderer/components/chat/SentInlineAtomBody.tsx, apps/desktop/src/renderer/components/chat/SessionHandoffCard.tsx, apps/desktop/src/renderer/components/chat/SessionLinkChip.tsx, apps/desktop/src/renderer/components/chat/SessionQuickSendContext.tsx, apps/desktop/src/renderer/components/chat/ShareMessageCheckbox.tsx, apps/desktop/src/renderer/components/chat/ShareSelectionBar.tsx, apps/desktop/src/renderer/components/chat/SlackIcon.tsx, apps/desktop/src/renderer/components/chat/StreamFadeSpan.tsx, apps/desktop/src/renderer/components/chat/StreamingMarkdownChunk.tsx, apps/desktop/src/renderer/components/chat/SystemCard.tsx, apps/desktop/src/renderer/components/chat/TextLightbox.tsx, apps/desktop/src/renderer/components/chat/ThinkingCard.tsx, apps/desktop/src/renderer/components/chat/ThinkingText.tsx, apps/desktop/src/renderer/components/chat/TodoListCard.tsx, apps/desktop/src/renderer/components/chat/ToolCallCard.tsx, apps/desktop/src/renderer/components/chat/ToolPayloadLightbox.tsx, apps/desktop/src/renderer/components/chat/TopRightChipStack.tsx, apps/desktop/src/renderer/components/chat/TurnChangesCard.tsx, apps/desktop/src/renderer/components/chat/UnreadFailedScheduleBanner.tsx, apps/desktop/src/renderer/components/chat/UpgradeBanner.tsx, apps/desktop/src/renderer/components/chat/UserAttachmentChip.tsx, apps/desktop/src/renderer/components/chat/UserMessage.tsx, apps/desktop/src/renderer/components/chat/UserMessageEditBox.tsx, apps/desktop/src/renderer/components/chat/UserMessageImageLink.tsx, apps/desktop/src/renderer/components/chat/UserMessageUrlLink.tsx, apps/desktop/src/renderer/components/chat/VideoLightbox.tsx, apps/desktop/src/renderer/components/chat/VideoSitePreview.tsx, apps/desktop/src/renderer/components/chat/WorkGroupBlock.tsx, apps/desktop/src/renderer/components/chat/WorktreeRestoreBanner.tsx, apps/desktop/src/renderer/components/chat/XIcon.tsx, apps/desktop/src/renderer/components/chat/activityRowChrome.ts, apps/desktop/src/renderer/components/chat/animateFocusScroll.ts, apps/desktop/src/renderer/components/chat/autoFollowIntent.ts, apps/desktop/src/renderer/components/chat/chatChrome.ts, apps/desktop/src/renderer/components/chat/errorReasonI18n.ts, apps/desktop/src/renderer/components/chat/generatedFilesProjection.ts, apps/desktop/src/renderer/components/chat/historyAfter.ts, apps/desktop/src/renderer/components/chat/imageDisplaySize.ts, apps/desktop/src/renderer/components/chat/lightboxAnnotations.ts, apps/desktop/src/renderer/components/chat/lightboxGestures.ts, apps/desktop/src/renderer/components/chat/linkInteraction.ts, apps/desktop/src/renderer/components/chat/mailBodyEditing.ts, apps/desktop/src/renderer/components/chat/mailCardFooter.ts, apps/desktop/src/renderer/components/chat/mailPreviewAppearance.ts, apps/desktop/src/renderer/components/chat/markdownImageTargets.ts, apps/desktop/src/renderer/components/chat/markdownMedia.ts, apps/desktop/src/renderer/components/chat/messageNavRailModel.ts, apps/desktop/src/renderer/components/chat/messageNavRailWheel.ts, apps/desktop/src/renderer/components/chat/messageNavigationProjection.ts, apps/desktop/src/renderer/components/chat/messageProjectionCache.ts, apps/desktop/src/renderer/components/chat/messageStreamIndicatorPosition.ts, apps/desktop/src/renderer/components/chat/messageViewportCompensation.ts, apps/desktop/src/renderer/components/chat/messageViewportGeometry.ts, apps/desktop/src/renderer/components/chat/messageWorkGroups.ts, apps/desktop/src/renderer/components/chat/observeProgrammaticScroll.ts, apps/desktop/src/renderer/components/chat/rehypeFencedCodeMarker.ts, apps/desktop/src/renderer/components/chat/rehypeHighlightShared.ts, apps/desktop/src/renderer/components/chat/rehypeMathBlockMarker.ts, apps/desktop/src/renderer/components/chat/rehypeStreamWordFade.ts, apps/desktop/src/renderer/components/chat/remarkHtmlImages.ts, apps/desktop/src/renderer/components/chat/remarkLocalPathLinks.ts, apps/desktop/src/renderer/components/chat/remarkPreserveRawLocalDestinations.ts, apps/desktop/src/renderer/components/chat/remarkSessionLinks.ts, apps/desktop/src/renderer/components/chat/remarkStrictInlineMath.ts, apps/desktop/src/renderer/components/chat/remarkTruncateCjkUrls.ts, apps/desktop/src/renderer/components/chat/repairStreamingMarkdown.ts, apps/desktop/src/renderer/components/chat/rich-answer.css, apps/desktop/src/renderer/components/chat/scrollAnchoringDetect.ts, apps/desktop/src/renderer/components/chat/shareSelectionStore.ts, apps/desktop/src/renderer/components/chat/streamingMarkdownBlocks.tsx, apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts, apps/desktop/src/renderer/components/chat/streamingMessageProjection.ts, apps/desktop/src/renderer/components/chat/toolLoopI18n.ts, apps/desktop/src/renderer/components/chat/unreadCount.ts, apps/desktop/src/renderer/components/chat/useAutomaticHistoryLoadBudget.ts, apps/desktop/src/renderer/components/chat/useCopyAsImage.tsx, apps/desktop/src/renderer/components/chat/useDeleteMessage.ts, apps/desktop/src/renderer/components/chat/useFileChipContextMenu.tsx, apps/desktop/src/renderer/components/chat/useForkAtMessage.ts, apps/desktop/src/renderer/components/chat/useImageClipboard.ts, apps/desktop/src/renderer/components/chat/useImageLoadFailure.ts, apps/desktop/src/renderer/components/chat/useLinkContextMenu.tsx, apps/desktop/src/renderer/components/chat/useMessageViewport.ts, apps/desktop/src/renderer/components/chat/useNavigationKeyListener.ts, apps/desktop/src/renderer/components/chat/useOpenWithMenu.tsx, apps/desktop/src/renderer/components/chat/usePrevUserMessageInView.ts, apps/desktop/src/renderer/components/chat/useTurnChangeSets.ts, apps/desktop/src/renderer/components/chat/userMessageCollapse.ts, apps/desktop/src/renderer/components/chat/userMessageDisplayText.ts, apps/desktop/src/renderer/components/chat/userMessageLinkify.ts, apps/desktop/src/renderer/components/chat/viewportFillDetect.ts, apps/desktop/src/renderer/components/new-chat/AddRemoteProjectDialog.tsx, apps/desktop/src/renderer/components/new-chat/AgentSelect.tsx, apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx, apps/desktop/src/renderer/components/new-chat/AtMentionPanel.tsx, apps/desktop/src/renderer/components/new-chat/AttachmentTypeThumb.tsx, apps/desktop/src/renderer/components/new-chat/ChatInput.tsx, apps/desktop/src/renderer/components/new-chat/CjkPunctDecoration.ts, apps/desktop/src/renderer/components/new-chat/CjkPunctuationUtils.ts, apps/desktop/src/renderer/components/new-chat/ComposerAttachments.tsx, apps/desktop/src/renderer/components/new-chat/ComposerFolderTransfers.tsx, apps/desktop/src/renderer/components/new-chat/ComposerListIndentDecoration.ts, apps/desktop/src/renderer/components/new-chat/ComposerListNodes.ts, apps/desktop/src/renderer/components/new-chat/ComposerQuoteNode.tsx, apps/desktop/src/renderer/components/new-chat/DeviceSwitcherPill.tsx, apps/desktop/src/renderer/components/new-chat/EffortSlider.tsx, apps/desktop/src/renderer/components/new-chat/EmptyDocSelectionGuard.ts, apps/desktop/src/renderer/components/new-chat/ExtraDirsButton.tsx, apps/desktop/src/renderer/components/new-chat/FastModeToggle.tsx, apps/desktop/src/renderer/components/new-chat/FolderPickerPopover.tsx, apps/desktop/src/renderer/components/new-chat/FullAccessConfirmContent.tsx, apps/desktop/src/renderer/components/new-chat/GhostCommandDecoration.ts, apps/desktop/src/renderer/components/new-chat/GoalAdvancedLimits.tsx, apps/desktop/src/renderer/components/new-chat/GoalIndicator.tsx, apps/desktop/src/renderer/components/new-chat/HomeUsageDashboard.tsx, apps/desktop/src/renderer/components/new-chat/ListComposerTextarea.tsx, apps/desktop/src/renderer/components/new-chat/LocalModelCatalogNotice.tsx, apps/desktop/src/renderer/components/new-chat/MentionChipNode.tsx, apps/desktop/src/renderer/components/new-chat/MentionDragCaretDecoration.ts, apps/desktop/src/renderer/components/new-chat/ModelCompatibilityNotice.tsx, apps/desktop/src/renderer/components/new-chat/ModelConfigFlyout.tsx, apps/desktop/src/renderer/components/new-chat/ModelHarnessPicker.tsx, apps/desktop/src/renderer/components/new-chat/ModelRouteSelector.tsx, apps/desktop/src/renderer/components/new-chat/ModelSelector.tsx, apps/desktop/src/renderer/components/new-chat/ModelSourceDetails.tsx, apps/desktop/src/renderer/components/new-chat/NewGoalDialog.tsx, apps/desktop/src/renderer/components/new-chat/PastedTextChipNode.tsx, apps/desktop/src/renderer/components/new-chat/PendingQueuePanel.tsx, apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx, apps/desktop/src/renderer/components/new-chat/PermissionSelector.tsx, apps/desktop/src/renderer/components/new-chat/PinnedPlanPanel.tsx, apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx, apps/desktop/src/renderer/components/new-chat/PlanModeIndicator.tsx, apps/desktop/src/renderer/components/new-chat/PlanViewerCard.tsx, apps/desktop/src/renderer/components/new-chat/PluginConnectionForm.tsx, apps/desktop/src/renderer/components/new-chat/PluginOauthDeviceCode.tsx, apps/desktop/src/renderer/components/new-chat/PluginSetupPrompt.tsx, apps/desktop/src/renderer/components/new-chat/PluginSetupRemoteDesktopButton.tsx, apps/desktop/src/renderer/components/new-chat/PluginWriteAccessRecovery.tsx, apps/desktop/src/renderer/components/new-chat/QuickStartPillMark.ts, apps/desktop/src/renderer/components/new-chat/RemoteOauthSetupCard.tsx, apps/desktop/src/renderer/components/new-chat/SendButton.tsx, apps/desktop/src/renderer/components/new-chat/SlashCommandDecoration.ts, apps/desktop/src/renderer/components/new-chat/SlashCommandPalette.tsx, apps/desktop/src/renderer/components/new-chat/SpeedIcon.tsx, apps/desktop/src/renderer/components/new-chat/TakeoverMask.tsx, apps/desktop/src/renderer/components/new-chat/ThinkingToggle.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedFlyoutHost.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelPanel.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelRail.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelRow.tsx, apps/desktop/src/renderer/components/new-chat/UsageDailyBars.tsx, apps/desktop/src/renderer/components/new-chat/UsageHeatmap.tsx, apps/desktop/src/renderer/components/new-chat/VendorSegmentedSwitcher.tsx, apps/desktop/src/renderer/components/new-chat/VoiceInputDraftDecoration.ts, apps/desktop/src/renderer/components/new-chat/WindowsSelectionReplacement.ts, apps/desktop/src/renderer/components/new-chat/WorktreeChipsRow.tsx, apps/desktop/src/renderer/components/new-chat/WorktreeCreatingOverlay.tsx, apps/desktop/src/renderer/components/new-chat/agentOptions.ts, apps/desktop/src/renderer/components/new-chat/agentSwitchConfirmation.ts, apps/desktop/src/renderer/components/new-chat/askUserDictation.ts, apps/desktop/src/renderer/components/new-chat/askUserVoiceShortcutOwner.ts, apps/desktop/src/renderer/components/new-chat/branchPick.ts, apps/desktop/src/renderer/components/new-chat/composerBlankPointerFocus.ts, apps/desktop/src/renderer/components/new-chat/composerContentSerialization.ts, apps/desktop/src/renderer/components/new-chat/composerDocState.ts, apps/desktop/src/renderer/components/new-chat/composerFrameScheduler.ts, apps/desktop/src/renderer/components/new-chat/composerHistoryProjection.ts, apps/desktop/src/renderer/components/new-chat/composerModelSelection.ts, apps/desktop/src/renderer/components/new-chat/composerPromptRecommendation.ts, apps/desktop/src/renderer/components/new-chat/composerRenderGate.ts, apps/desktop/src/renderer/components/new-chat/composerSendOwnership.ts, apps/desktop/src/renderer/components/new-chat/composerSendSnapshot.ts, apps/desktop/src/renderer/components/new-chat/effortChangeQueue.ts, apps/desktop/src/renderer/components/new-chat/extraDirsActions.ts, apps/desktop/src/renderer/components/new-chat/favoritesSyncFailure.ts, apps/desktop/src/renderer/components/new-chat/ghostComposerPlacement.ts, apps/desktop/src/renderer/components/new-chat/localAttachmentPicker.ts, apps/desktop/src/renderer/components/new-chat/mentionChipInsertion.ts, apps/desktop/src/renderer/components/new-chat/modelWindowErrorToast.ts, apps/desktop/src/renderer/components/new-chat/pastePipeline.ts, apps/desktop/src/renderer/components/new-chat/pathPaste.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueLocks.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueRowActivity.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts, apps/desktop/src/renderer/components/new-chat/planModeComposerCommand.ts, apps/desktop/src/renderer/components/new-chat/priceTierMarks.tsx, apps/desktop/src/renderer/components/new-chat/remoteBrowseAdapters.ts, apps/desktop/src/renderer/components/new-chat/remoteExistingProjects.ts, apps/desktop/src/renderer/components/new-chat/restoreComposerDocument.ts, apps/desktop/src/renderer/components/new-chat/sessionLinkPaste.ts, apps/desktop/src/renderer/components/new-chat/sourceSwitch.ts, apps/desktop/src/renderer/components/new-chat/unifiedModelSelection.ts, apps/desktop/src/renderer/components/new-chat/usagePalette.ts, apps/desktop/src/renderer/components/new-chat/useAskUserDictation.ts, apps/desktop/src/renderer/components/new-chat/useComposerSendFocusRestore.ts, apps/desktop/src/renderer/components/new-chat/useModelDiscoveryPending.ts, apps/desktop/src/renderer/components/new-chat/useProviderWeeklyQuota.ts, apps/desktop/src/renderer/components/new-chat/useUnifiedRowActions.ts, apps/desktop/src/renderer/components/new-chat/voiceQuestionSelection.ts, apps/desktop/src/renderer/features/bots/BotAddToGroupMenu.tsx, apps/desktop/src/renderer/features/bots/BotAuthorizationCard.tsx, apps/desktop/src/renderer/features/bots/BotAutonomySettings.tsx, apps/desktop/src/renderer/features/bots/BotAvatar.tsx, apps/desktop/src/renderer/features/bots/BotBasicProfileFields.tsx, apps/desktop/src/renderer/features/bots/BotCapabilitySettings.tsx, apps/desktop/src/renderer/features/bots/BotChannelsPage.tsx, apps/desktop/src/renderer/features/bots/BotChatQuoteViews.tsx, apps/desktop/src/renderer/features/bots/BotCollaborationCard.tsx, apps/desktop/src/renderer/features/bots/BotConnectionStatus.tsx, apps/desktop/src/renderer/features/bots/BotCreateMenu.tsx, apps/desktop/src/renderer/features/bots/BotDeleteDialog.tsx, apps/desktop/src/renderer/features/bots/BotDirectMessageCard.tsx, apps/desktop/src/renderer/features/bots/BotDirectMessageView.tsx, apps/desktop/src/renderer/features/bots/BotDmThreadHost.tsx, apps/desktop/src/renderer/features/bots/BotDmThreadPreview.tsx, apps/desktop/src/renderer/features/bots/BotDmThreadViews.tsx, apps/desktop/src/renderer/features/bots/BotFollowMark.tsx, apps/desktop/src/renderer/features/bots/BotFollowUpInvitation.tsx, apps/desktop/src/renderer/features/bots/BotGenerationLabel.tsx, apps/desktop/src/renderer/features/bots/BotGlancePopover.tsx, apps/desktop/src/renderer/features/bots/BotGroupAvatars.tsx, apps/desktop/src/renderer/features/bots/BotGroupChatView.tsx, apps/desktop/src/renderer/features/bots/BotGroupComposer.tsx, apps/desktop/src/renderer/features/bots/BotGroupCreateDialog.tsx, apps/desktop/src/renderer/features/bots/BotGroupElapsed.tsx, apps/desktop/src/renderer/features/bots/BotGroupLivePreview.tsx, apps/desktop/src/renderer/features/bots/BotGroupLiveStatus.tsx, apps/desktop/src/renderer/features/bots/BotGroupMentionCard.tsx, apps/desktop/src/renderer/features/bots/BotGroupMessageAttachments.tsx, apps/desktop/src/renderer/features/bots/BotGroupPendingInteraction.tsx, apps/desktop/src/renderer/features/bots/BotGroupPlan.tsx, apps/desktop/src/renderer/features/bots/BotGroupQuote.tsx, apps/desktop/src/renderer/features/bots/BotGroupRuntimeFailureNotice.tsx, apps/desktop/src/renderer/features/bots/BotGroupSettingsDrawer.tsx, apps/desktop/src/renderer/features/bots/BotGroupSidebarRow.tsx, apps/desktop/src/renderer/features/bots/BotGroupTaskCard.tsx, apps/desktop/src/renderer/features/bots/BotGroupThreadHint.tsx, apps/desktop/src/renderer/features/bots/BotGroupThreadViews.tsx, apps/desktop/src/renderer/features/bots/BotGroupTimelineItem.tsx, apps/desktop/src/renderer/features/bots/BotGroupTimelineModel.ts, apps/desktop/src/renderer/features/bots/BotHistorySessionView.tsx, apps/desktop/src/renderer/features/bots/BotHomeComputerSetting.tsx, apps/desktop/src/renderer/features/bots/BotImportForm.tsx, apps/desktop/src/renderer/features/bots/BotInvitationWelcome.tsx, apps/desktop/src/renderer/features/bots/BotLearningFooter.tsx, apps/desktop/src/renderer/features/bots/BotLifecycleSettings.tsx, apps/desktop/src/renderer/features/bots/BotMarketDialog.tsx, apps/desktop/src/renderer/features/bots/BotMarketModules.tsx, apps/desktop/src/renderer/features/bots/BotMemorySettings.tsx, apps/desktop/src/renderer/features/bots/BotModelChainEditor.tsx, apps/desktop/src/renderer/features/bots/BotOpeningPending.tsx, apps/desktop/src/renderer/features/bots/BotPortraitPicker.tsx, apps/desktop/src/renderer/features/bots/BotProjectsSettings.tsx, apps/desktop/src/renderer/features/bots/BotRosterView.tsx, apps/desktop/src/renderer/features/bots/BotRoutines.tsx, apps/desktop/src/renderer/features/bots/BotSessionContentHeader.tsx, apps/desktop/src/renderer/features/bots/BotSessionTaskLink.tsx, apps/desktop/src/renderer/features/bots/BotSessionTaskResultCard.tsx, apps/desktop/src/renderer/features/bots/BotSessionView.tsx, apps/desktop/src/renderer/features/bots/BotSettingsBlock.tsx, apps/desktop/src/renderer/features/bots/BotSettingsDrawer.tsx, apps/desktop/src/renderer/features/bots/BotStarterOptions.tsx, apps/desktop/src/renderer/features/bots/BotTaskModelEditor.tsx, apps/desktop/src/renderer/features/bots/BotTaskOwnerChip.tsx, apps/desktop/src/renderer/features/bots/BotsFeatureLayout.tsx, apps/desktop/src/renderer/features/bots/BotsGlobalSettingsSection.tsx, apps/desktop/src/renderer/features/bots/BotsHomeView.tsx, apps/desktop/src/renderer/features/bots/BotsListView.tsx, apps/desktop/src/renderer/features/bots/ChatBotAccessField.tsx, apps/desktop/src/renderer/features/bots/ChatGroupSettings.tsx, apps/desktop/src/renderer/features/bots/ChatInviteDialog.tsx, apps/desktop/src/renderer/features/bots/ChatInviteHost.tsx, apps/desktop/src/renderer/features/bots/ChatReactionButton.tsx, apps/desktop/src/renderer/features/bots/ChatServerControls.tsx, apps/desktop/src/renderer/features/bots/ChatThreadPanel.tsx, apps/desktop/src/renderer/features/bots/CindyDevicePicker.tsx, apps/desktop/src/renderer/features/bots/CindyDeviceRow.tsx, apps/desktop/src/renderer/features/bots/CindyMergeSetting.tsx, apps/desktop/src/renderer/features/bots/CloudCompanionOfflineView.tsx, apps/desktop/src/renderer/features/bots/CompanionShadowBanner.tsx, apps/desktop/src/renderer/features/bots/RemoteBotFollowUpInvitation.tsx, apps/desktop/src/renderer/features/bots/RemoteBotSessionView.tsx, apps/desktop/src/renderer/features/bots/RemoteBotSettings.tsx, apps/desktop/src/renderer/features/bots/RemoveChatFromListButton.tsx, apps/desktop/src/renderer/features/bots/TeammateSearchResults.tsx, apps/desktop/src/renderer/features/bots/TeammatesSection.tsx, apps/desktop/src/renderer/features/bots/botAvatarIdentity.ts, apps/desktop/src/renderer/features/bots/botCapabilityDefaults.ts, apps/desktop/src/renderer/features/bots/botChatPresentation.ts, apps/desktop/src/renderer/features/bots/botChatQuoteContext.tsx, apps/desktop/src/renderer/features/bots/botConversationPresentation.ts, apps/desktop/src/renderer/features/bots/botConversationTimeline.ts, apps/desktop/src/renderer/features/bots/botDelegationLive.ts, apps/desktop/src/renderer/features/bots/botDmQuote.ts, apps/desktop/src/renderer/features/bots/botDmThreadRoute.ts, apps/desktop/src/renderer/features/bots/botDmThreads.tsx, apps/desktop/src/renderer/features/bots/botDmThreadsContext.tsx, apps/desktop/src/renderer/features/bots/botFollowScopes.ts, apps/desktop/src/renderer/features/bots/botGeneratedArtifacts.ts, apps/desktop/src/renderer/features/bots/botGlanceTodos.ts, apps/desktop/src/renderer/features/bots/botGroupAttachments.ts, apps/desktop/src/renderer/features/bots/botGroupComposerChrome.ts, apps/desktop/src/renderer/features/bots/botGroupLane.ts, apps/desktop/src/renderer/features/bots/botGroupMentions.ts, apps/desktop/src/renderer/features/bots/botGroupOutbox.ts, apps/desktop/src/renderer/features/bots/botGroupPresentation.ts, apps/desktop/src/renderer/features/bots/botGroupStore.ts, apps/desktop/src/renderer/features/bots/botImConnectionClient.ts, apps/desktop/src/renderer/features/bots/botListDisplay.ts, apps/desktop/src/renderer/features/bots/botMarketDisplay.ts, apps/desktop/src/renderer/features/bots/botMarketEntryHint.ts, apps/desktop/src/renderer/features/bots/botNavigation.ts, apps/desktop/src/renderer/features/bots/botPronounContext.tsx, apps/desktop/src/renderer/features/bots/botReadState.ts, apps/desktop/src/renderer/features/bots/botRosterDisplay.ts, apps/desktop/src/renderer/features/bots/botSessionOwners.ts, apps/desktop/src/renderer/features/bots/botSettingsAutosave.ts, apps/desktop/src/renderer/features/bots/botSettingsIcons.ts, apps/desktop/src/renderer/features/bots/botStore.ts, apps/desktop/src/renderer/features/bots/botTodo.css, apps/desktop/src/renderer/features/bots/botWelcomeContext.ts, apps/desktop/src/renderer/features/bots/chatError.ts, apps/desktop/src/renderer/features/bots/cindyDeviceRoster.ts, apps/desktop/src/renderer/features/bots/companionAvatarCache.ts, apps/desktop/src/renderer/features/bots/companionCloudPresentation.ts, apps/desktop/src/renderer/features/bots/companionCloudStore.ts, apps/desktop/src/renderer/features/bots/islandEntryAlert.ts, apps/desktop/src/renderer/features/bots/remoteBotRoster.ts, apps/desktop/src/renderer/features/bots/remoteBotSettingsData.ts, apps/desktop/src/renderer/features/bots/teammatesSectionPrefs.ts, apps/desktop/src/renderer/features/bots/useBotGeneratedFileDeliveries.ts, apps/desktop/src/renderer/features/bots/useBotGroupMentionPicker.tsx, apps/desktop/src/renderer/features/bots/useBotIslandVisibleSession.ts, apps/desktop/src/renderer/features/bots/useBotPluginFocusedSession.ts, apps/desktop/src/renderer/features/bots/useBotReplyTargetPreference.ts, apps/desktop/src/renderer/features/bots/useBotSettingsAutosave.ts, apps/desktop/src/renderer/features/bots/useBotUnreadSync.ts, apps/desktop/src/renderer/features/bots/useRemoteBots.ts, apps/desktop/src/renderer/features/bots/useSessionEntryLocationCommits.ts, apps/desktop/src/renderer/features/bots/useThreadPanelResize.ts, apps/desktop/src/renderer/features/bots/useViewedBotSessionId.ts, apps/desktop/src/renderer/features/bots/useWorkingStatusCopy.ts, apps/desktop/src/renderer/features/bots/voice/CompanionVoicePanel.tsx, apps/desktop/src/renderer/features/bots/voice/CompanionVoiceSettings.tsx, apps/desktop/src/renderer/features/bots/voice/CompanionVoiceToolbar.tsx, apps/desktop/src/renderer/features/bots/voice/MessageReadAloudController.ts, apps/desktop/src/renderer/features/bots/voice/PcmSpeechPlayer.ts, apps/desktop/src/renderer/features/bots/voice/SpeechPlaybackQueue.ts, apps/desktop/src/renderer/features/bots/voice/SpeechTextBuffer.ts, apps/desktop/src/renderer/features/bots/voice/SpeechVoiceMenu.tsx, apps/desktop/src/renderer/features/bots/voice/SpeechVoicePicker.tsx, apps/desktop/src/renderer/features/bots/voice/VoiceCallTranscript.tsx, apps/desktop/src/renderer/features/bots/voice/VoiceConversationController.ts, apps/desktop/src/renderer/features/bots/voice/VoicePreviewController.ts, apps/desktop/src/renderer/features/bots/voice/VoiceReplyTracker.ts, apps/desktop/src/renderer/features/bots/voice/microphoneDiagnostics.ts, apps/desktop/src/renderer/features/bots/voice/speechVoiceLabelCache.ts, apps/desktop/src/renderer/features/bots/voice/useMessageReadAloud.ts, apps/desktop/src/renderer/features/bots/voice/voiceCallPresentation.ts, apps/desktop/src/renderer/features/bots/voice/voiceConfiguration.ts, apps/desktop/src/renderer/features/bots/voice/voiceConversation.css, apps/desktop/src/renderer/features/bots/voice/voiceExitIntent.ts, apps/desktop/src/renderer/features/cc-agent/CCAgentFeatureLayout.tsx, apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx | 304 | 38 | 574 |
-| `desktop.chat.files` | desktop | 工作目录文件浏览 | hash `/cc-agent/files/:sessionId`(WorkdirBrowseRoute) | FileBodyView, FileTreeView, WorkdirBrowseRoute | apps/desktop/src/renderer/features/cc-agent/workdir-browse/DocSearchBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/DrawioPreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileBodyView.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileFilterInput.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTabsBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeView.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FilterResultList.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/ImagePreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/OpenInSystemActions.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/PdfPreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/SessionTabsBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/UnrenderablePlaceholder.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseRoute.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useChatRailCollapsed.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useChatRailResize.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useConfirmSwitchAwayIfDirty.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useDelayedFlag.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileContent.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useOpenTabs.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useProjectFileList.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useRevealFileInTree.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/activeFileBodyHandle.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/docModeSwitchProjects.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/drawioExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileContentCache.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileIcon.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileMeta.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileScrollStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileSelectionParams.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/filterFiles.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/imageExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/markdownAutosave.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/openTabsStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/pdfExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/selectedFileStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchInput.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchPanel.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchResults.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/hooks/useProjectSearch.ts | 18 | 5 | 44 |
+| `desktop.chat.files` | desktop | 工作目录文件浏览 | hash `/cc-agent/files/:sessionId`(WorkdirBrowseRoute) | FileBodyView, FileTreeView, WorkdirBrowseRoute | apps/desktop/src/renderer/features/cc-agent/workdir-browse/DocSearchBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/DrawioPreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileBodyView.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileFilterInput.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTabsBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeHeaderActions.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeIgnoredDirsToggle.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FileTreeView.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/FilterResultList.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/ImagePreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/OpenInSystemActions.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/PdfPreview.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/SessionTabsBar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/UnrenderablePlaceholder.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseRoute.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/WorkdirBrowseSidebar.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/fileTreeHeaderButtonClass.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useChatRailCollapsed.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useChatRailResize.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useConfirmSwitchAwayIfDirty.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useDelayedFlag.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileContent.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useFileTree.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useOpenTabs.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useProjectFileList.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/hooks/useRevealFileInTree.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/activeFileBodyHandle.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/docModeSwitchProjects.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/drawioExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/expandedStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileContentCache.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileIcon.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileMeta.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileScrollStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/fileSelectionParams.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/filterFiles.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/imageExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/markdownAutosave.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/openTabsStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/pdfExt.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/lib/selectedFileStore.ts, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchInput.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchPanel.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/SearchResults.tsx, apps/desktop/src/renderer/features/cc-agent/workdir-browse/search/hooks/useProjectSearch.ts | 18 | 5 | 41 |
| `desktop.chat.new-draft` | desktop | 新建任务草稿页 | hash `/cc-agent/new`(NewMakerDraftRoute) | NewMakerDraftRoute | apps/desktop/src/renderer/features/cc-agent/NewMakerDraftRoute.tsx | 15 | 0 | 3 |
| `desktop.chat.orca-workflow` | desktop | Orca 协同工作台 | hash `/cc-agent/orca/:sessionId`(OrcaWorkflowRoute) | CCAgentSessionView, OrcaSplitView, OrcaWorkerPanel, OrcaWorkflowRoute | apps/desktop/src/renderer/components/chat/AgentActionRow.tsx, apps/desktop/src/renderer/components/chat/AgentActionsBlock.tsx, apps/desktop/src/renderer/components/chat/AgentTaskCard.tsx, apps/desktop/src/renderer/components/chat/AgentTaskLiveDetails.tsx, apps/desktop/src/renderer/components/chat/AnnotationStrokesSvg.tsx, apps/desktop/src/renderer/components/chat/AskUserQuestionBubble.tsx, apps/desktop/src/renderer/components/chat/AssistantMessage.tsx, apps/desktop/src/renderer/components/chat/AutomationOriginBadge.tsx, apps/desktop/src/renderer/components/chat/ChatAudioCard.tsx, apps/desktop/src/renderer/components/chat/ChatDisplaySnapshotContext.tsx, apps/desktop/src/renderer/components/chat/ChatImageView.tsx, apps/desktop/src/renderer/components/chat/ChatLoadingImage.tsx, apps/desktop/src/renderer/components/chat/ChatReplyIcon.tsx, apps/desktop/src/renderer/components/chat/ChatSessionFileContext.tsx, apps/desktop/src/renderer/components/chat/ChatSoundEffectCard.tsx, apps/desktop/src/renderer/components/chat/ChatVideoView.tsx, apps/desktop/src/renderer/components/chat/CindyMakeDoctorCard.tsx, apps/desktop/src/renderer/components/chat/CopyAsImageBlock.tsx, apps/desktop/src/renderer/components/chat/CredentialSwitchWaitBanner.tsx, apps/desktop/src/renderer/components/chat/DiffView.tsx, apps/desktop/src/renderer/components/chat/ErrorBanner.tsx, apps/desktop/src/renderer/components/chat/ErrorMessageCard.tsx, apps/desktop/src/renderer/components/chat/GeneratedFilesCard.tsx, apps/desktop/src/renderer/components/chat/GhostCardForm.tsx, apps/desktop/src/renderer/components/chat/GhostCardHostPrompts.tsx, apps/desktop/src/renderer/components/chat/GhostCardRecipients.tsx, apps/desktop/src/renderer/components/chat/GhostMailHistory.tsx, apps/desktop/src/renderer/components/chat/GhostSummonCard.tsx, apps/desktop/src/renderer/components/chat/GhostToolCard.tsx, apps/desktop/src/renderer/components/chat/HookTaskCard.tsx, apps/desktop/src/renderer/components/chat/ImageGalleryContext.tsx, apps/desktop/src/renderer/components/chat/ImageHoverPreview.tsx, apps/desktop/src/renderer/components/chat/ImageLightbox.tsx, apps/desktop/src/renderer/components/chat/ImageMissingPlaceholder.tsx, apps/desktop/src/renderer/components/chat/InlineReferenceChip.tsx, apps/desktop/src/renderer/components/chat/InterruptedTurnBanner.tsx, apps/desktop/src/renderer/components/chat/JumpToBottomChip.tsx, apps/desktop/src/renderer/components/chat/MailHtmlPreview.tsx, apps/desktop/src/renderer/components/chat/MarkdownDiffBlock.tsx, apps/desktop/src/renderer/components/chat/MarkdownMermaidBlock.tsx, apps/desktop/src/renderer/components/chat/MarkdownRenderer.tsx, apps/desktop/src/renderer/components/chat/McpAppCard.tsx, apps/desktop/src/renderer/components/chat/MermaidLightbox.tsx, apps/desktop/src/renderer/components/chat/MessageActionBar.tsx, apps/desktop/src/renderer/components/chat/MessageNavRail.tsx, apps/desktop/src/renderer/components/chat/MessageReadAloudContext.ts, apps/desktop/src/renderer/components/chat/MessageSourceLabels.tsx, apps/desktop/src/renderer/components/chat/MessageStream.tsx, apps/desktop/src/renderer/components/chat/MessageViewport.tsx, apps/desktop/src/renderer/components/chat/ModelLightbox.tsx, apps/desktop/src/renderer/components/chat/NewMessageIndicator.tsx, apps/desktop/src/renderer/components/chat/PlanReviewBubble.tsx, apps/desktop/src/renderer/components/chat/PrevMessageJumpChip.tsx, apps/desktop/src/renderer/components/chat/ProjectLinkChip.tsx, apps/desktop/src/renderer/components/chat/QuoteChip.tsx, apps/desktop/src/renderer/components/chat/RewindPreviewDialog.tsx, apps/desktop/src/renderer/components/chat/RichAnswer.tsx, apps/desktop/src/renderer/components/chat/SelectionQuoteButton.tsx, apps/desktop/src/renderer/components/chat/SentAgentReferenceChip.tsx, apps/desktop/src/renderer/components/chat/SentInlineAtomBody.tsx, apps/desktop/src/renderer/components/chat/SessionHandoffCard.tsx, apps/desktop/src/renderer/components/chat/SessionLinkChip.tsx, apps/desktop/src/renderer/components/chat/SessionQuickSendContext.tsx, apps/desktop/src/renderer/components/chat/ShareMessageCheckbox.tsx, apps/desktop/src/renderer/components/chat/ShareSelectionBar.tsx, apps/desktop/src/renderer/components/chat/SlackIcon.tsx, apps/desktop/src/renderer/components/chat/StreamFadeSpan.tsx, apps/desktop/src/renderer/components/chat/StreamingMarkdownChunk.tsx, apps/desktop/src/renderer/components/chat/SystemCard.tsx, apps/desktop/src/renderer/components/chat/TextLightbox.tsx, apps/desktop/src/renderer/components/chat/ThinkingCard.tsx, apps/desktop/src/renderer/components/chat/ThinkingText.tsx, apps/desktop/src/renderer/components/chat/TodoListCard.tsx, apps/desktop/src/renderer/components/chat/ToolCallCard.tsx, apps/desktop/src/renderer/components/chat/ToolPayloadLightbox.tsx, apps/desktop/src/renderer/components/chat/TopRightChipStack.tsx, apps/desktop/src/renderer/components/chat/TurnChangesCard.tsx, apps/desktop/src/renderer/components/chat/UnreadFailedScheduleBanner.tsx, apps/desktop/src/renderer/components/chat/UpgradeBanner.tsx, apps/desktop/src/renderer/components/chat/UserAttachmentChip.tsx, apps/desktop/src/renderer/components/chat/UserMessage.tsx, apps/desktop/src/renderer/components/chat/UserMessageEditBox.tsx, apps/desktop/src/renderer/components/chat/UserMessageImageLink.tsx, apps/desktop/src/renderer/components/chat/UserMessageUrlLink.tsx, apps/desktop/src/renderer/components/chat/VideoLightbox.tsx, apps/desktop/src/renderer/components/chat/VideoSitePreview.tsx, apps/desktop/src/renderer/components/chat/WorkGroupBlock.tsx, apps/desktop/src/renderer/components/chat/WorktreeRestoreBanner.tsx, apps/desktop/src/renderer/components/chat/XIcon.tsx, apps/desktop/src/renderer/components/chat/activityRowChrome.ts, apps/desktop/src/renderer/components/chat/animateFocusScroll.ts, apps/desktop/src/renderer/components/chat/autoFollowIntent.ts, apps/desktop/src/renderer/components/chat/chatChrome.ts, apps/desktop/src/renderer/components/chat/errorReasonI18n.ts, apps/desktop/src/renderer/components/chat/generatedFilesProjection.ts, apps/desktop/src/renderer/components/chat/historyAfter.ts, apps/desktop/src/renderer/components/chat/imageDisplaySize.ts, apps/desktop/src/renderer/components/chat/lightboxAnnotations.ts, apps/desktop/src/renderer/components/chat/lightboxGestures.ts, apps/desktop/src/renderer/components/chat/linkInteraction.ts, apps/desktop/src/renderer/components/chat/mailBodyEditing.ts, apps/desktop/src/renderer/components/chat/mailCardFooter.ts, apps/desktop/src/renderer/components/chat/mailPreviewAppearance.ts, apps/desktop/src/renderer/components/chat/markdownImageTargets.ts, apps/desktop/src/renderer/components/chat/markdownMedia.ts, apps/desktop/src/renderer/components/chat/messageNavRailModel.ts, apps/desktop/src/renderer/components/chat/messageNavRailWheel.ts, apps/desktop/src/renderer/components/chat/messageNavigationProjection.ts, apps/desktop/src/renderer/components/chat/messageProjectionCache.ts, apps/desktop/src/renderer/components/chat/messageStreamIndicatorPosition.ts, apps/desktop/src/renderer/components/chat/messageViewportCompensation.ts, apps/desktop/src/renderer/components/chat/messageViewportGeometry.ts, apps/desktop/src/renderer/components/chat/messageWorkGroups.ts, apps/desktop/src/renderer/components/chat/observeProgrammaticScroll.ts, apps/desktop/src/renderer/components/chat/rehypeFencedCodeMarker.ts, apps/desktop/src/renderer/components/chat/rehypeHighlightShared.ts, apps/desktop/src/renderer/components/chat/rehypeMathBlockMarker.ts, apps/desktop/src/renderer/components/chat/rehypeStreamWordFade.ts, apps/desktop/src/renderer/components/chat/remarkHtmlImages.ts, apps/desktop/src/renderer/components/chat/remarkLocalPathLinks.ts, apps/desktop/src/renderer/components/chat/remarkPreserveRawLocalDestinations.ts, apps/desktop/src/renderer/components/chat/remarkSessionLinks.ts, apps/desktop/src/renderer/components/chat/remarkStrictInlineMath.ts, apps/desktop/src/renderer/components/chat/remarkTruncateCjkUrls.ts, apps/desktop/src/renderer/components/chat/repairStreamingMarkdown.ts, apps/desktop/src/renderer/components/chat/rich-answer.css, apps/desktop/src/renderer/components/chat/scrollAnchoringDetect.ts, apps/desktop/src/renderer/components/chat/shareSelectionStore.ts, apps/desktop/src/renderer/components/chat/streamingMarkdownBlocks.tsx, apps/desktop/src/renderer/components/chat/streamingMarkdownChunks.ts, apps/desktop/src/renderer/components/chat/streamingMessageProjection.ts, apps/desktop/src/renderer/components/chat/toolLoopI18n.ts, apps/desktop/src/renderer/components/chat/unreadCount.ts, apps/desktop/src/renderer/components/chat/useAutomaticHistoryLoadBudget.ts, apps/desktop/src/renderer/components/chat/useCopyAsImage.tsx, apps/desktop/src/renderer/components/chat/useDeleteMessage.ts, apps/desktop/src/renderer/components/chat/useFileChipContextMenu.tsx, apps/desktop/src/renderer/components/chat/useForkAtMessage.ts, apps/desktop/src/renderer/components/chat/useImageClipboard.ts, apps/desktop/src/renderer/components/chat/useImageLoadFailure.ts, apps/desktop/src/renderer/components/chat/useLinkContextMenu.tsx, apps/desktop/src/renderer/components/chat/useMessageViewport.ts, apps/desktop/src/renderer/components/chat/useNavigationKeyListener.ts, apps/desktop/src/renderer/components/chat/useOpenWithMenu.tsx, apps/desktop/src/renderer/components/chat/usePrevUserMessageInView.ts, apps/desktop/src/renderer/components/chat/useTurnChangeSets.ts, apps/desktop/src/renderer/components/chat/userMessageCollapse.ts, apps/desktop/src/renderer/components/chat/userMessageDisplayText.ts, apps/desktop/src/renderer/components/chat/userMessageLinkify.ts, apps/desktop/src/renderer/components/chat/viewportFillDetect.ts, apps/desktop/src/renderer/components/new-chat/AddRemoteProjectDialog.tsx, apps/desktop/src/renderer/components/new-chat/AgentSelect.tsx, apps/desktop/src/renderer/components/new-chat/AskUserQuestionPrompt.tsx, apps/desktop/src/renderer/components/new-chat/AtMentionPanel.tsx, apps/desktop/src/renderer/components/new-chat/AttachmentTypeThumb.tsx, apps/desktop/src/renderer/components/new-chat/ChatInput.tsx, apps/desktop/src/renderer/components/new-chat/CjkPunctDecoration.ts, apps/desktop/src/renderer/components/new-chat/CjkPunctuationUtils.ts, apps/desktop/src/renderer/components/new-chat/ComposerAttachments.tsx, apps/desktop/src/renderer/components/new-chat/ComposerFolderTransfers.tsx, apps/desktop/src/renderer/components/new-chat/ComposerListIndentDecoration.ts, apps/desktop/src/renderer/components/new-chat/ComposerListNodes.ts, apps/desktop/src/renderer/components/new-chat/ComposerQuoteNode.tsx, apps/desktop/src/renderer/components/new-chat/DeviceSwitcherPill.tsx, apps/desktop/src/renderer/components/new-chat/EffortSlider.tsx, apps/desktop/src/renderer/components/new-chat/EmptyDocSelectionGuard.ts, apps/desktop/src/renderer/components/new-chat/ExtraDirsButton.tsx, apps/desktop/src/renderer/components/new-chat/FastModeToggle.tsx, apps/desktop/src/renderer/components/new-chat/FolderPickerPopover.tsx, apps/desktop/src/renderer/components/new-chat/FullAccessConfirmContent.tsx, apps/desktop/src/renderer/components/new-chat/GhostCommandDecoration.ts, apps/desktop/src/renderer/components/new-chat/GoalAdvancedLimits.tsx, apps/desktop/src/renderer/components/new-chat/GoalIndicator.tsx, apps/desktop/src/renderer/components/new-chat/HomeUsageDashboard.tsx, apps/desktop/src/renderer/components/new-chat/ListComposerTextarea.tsx, apps/desktop/src/renderer/components/new-chat/LocalModelCatalogNotice.tsx, apps/desktop/src/renderer/components/new-chat/MentionChipNode.tsx, apps/desktop/src/renderer/components/new-chat/MentionDragCaretDecoration.ts, apps/desktop/src/renderer/components/new-chat/ModelCompatibilityNotice.tsx, apps/desktop/src/renderer/components/new-chat/ModelConfigFlyout.tsx, apps/desktop/src/renderer/components/new-chat/ModelHarnessPicker.tsx, apps/desktop/src/renderer/components/new-chat/ModelRouteSelector.tsx, apps/desktop/src/renderer/components/new-chat/ModelSelector.tsx, apps/desktop/src/renderer/components/new-chat/ModelSourceDetails.tsx, apps/desktop/src/renderer/components/new-chat/NewGoalDialog.tsx, apps/desktop/src/renderer/components/new-chat/PastedTextChipNode.tsx, apps/desktop/src/renderer/components/new-chat/PendingQueuePanel.tsx, apps/desktop/src/renderer/components/new-chat/PermissionPrompt.tsx, apps/desktop/src/renderer/components/new-chat/PermissionSelector.tsx, apps/desktop/src/renderer/components/new-chat/PinnedPlanPanel.tsx, apps/desktop/src/renderer/components/new-chat/PlanActionCard.tsx, apps/desktop/src/renderer/components/new-chat/PlanModeIndicator.tsx, apps/desktop/src/renderer/components/new-chat/PlanViewerCard.tsx, apps/desktop/src/renderer/components/new-chat/PluginConnectionForm.tsx, apps/desktop/src/renderer/components/new-chat/PluginOauthDeviceCode.tsx, apps/desktop/src/renderer/components/new-chat/PluginSetupPrompt.tsx, apps/desktop/src/renderer/components/new-chat/PluginSetupRemoteDesktopButton.tsx, apps/desktop/src/renderer/components/new-chat/PluginWriteAccessRecovery.tsx, apps/desktop/src/renderer/components/new-chat/QuickStartPillMark.ts, apps/desktop/src/renderer/components/new-chat/RemoteOauthSetupCard.tsx, apps/desktop/src/renderer/components/new-chat/SendButton.tsx, apps/desktop/src/renderer/components/new-chat/SlashCommandDecoration.ts, apps/desktop/src/renderer/components/new-chat/SlashCommandPalette.tsx, apps/desktop/src/renderer/components/new-chat/SpeedIcon.tsx, apps/desktop/src/renderer/components/new-chat/TakeoverMask.tsx, apps/desktop/src/renderer/components/new-chat/ThinkingToggle.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedFlyoutHost.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelPanel.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelRail.tsx, apps/desktop/src/renderer/components/new-chat/UnifiedModelRow.tsx, apps/desktop/src/renderer/components/new-chat/UsageDailyBars.tsx, apps/desktop/src/renderer/components/new-chat/UsageHeatmap.tsx, apps/desktop/src/renderer/components/new-chat/VendorSegmentedSwitcher.tsx, apps/desktop/src/renderer/components/new-chat/VoiceInputDraftDecoration.ts, apps/desktop/src/renderer/components/new-chat/WindowsSelectionReplacement.ts, apps/desktop/src/renderer/components/new-chat/WorktreeChipsRow.tsx, apps/desktop/src/renderer/components/new-chat/WorktreeCreatingOverlay.tsx, apps/desktop/src/renderer/components/new-chat/agentOptions.ts, apps/desktop/src/renderer/components/new-chat/agentSwitchConfirmation.ts, apps/desktop/src/renderer/components/new-chat/askUserDictation.ts, apps/desktop/src/renderer/components/new-chat/askUserVoiceShortcutOwner.ts, apps/desktop/src/renderer/components/new-chat/branchPick.ts, apps/desktop/src/renderer/components/new-chat/composerBlankPointerFocus.ts, apps/desktop/src/renderer/components/new-chat/composerContentSerialization.ts, apps/desktop/src/renderer/components/new-chat/composerDocState.ts, apps/desktop/src/renderer/components/new-chat/composerFrameScheduler.ts, apps/desktop/src/renderer/components/new-chat/composerHistoryProjection.ts, apps/desktop/src/renderer/components/new-chat/composerModelSelection.ts, apps/desktop/src/renderer/components/new-chat/composerPromptRecommendation.ts, apps/desktop/src/renderer/components/new-chat/composerRenderGate.ts, apps/desktop/src/renderer/components/new-chat/composerSendOwnership.ts, apps/desktop/src/renderer/components/new-chat/composerSendSnapshot.ts, apps/desktop/src/renderer/components/new-chat/effortChangeQueue.ts, apps/desktop/src/renderer/components/new-chat/extraDirsActions.ts, apps/desktop/src/renderer/components/new-chat/favoritesSyncFailure.ts, apps/desktop/src/renderer/components/new-chat/ghostComposerPlacement.ts, apps/desktop/src/renderer/components/new-chat/localAttachmentPicker.ts, apps/desktop/src/renderer/components/new-chat/mentionChipInsertion.ts, apps/desktop/src/renderer/components/new-chat/modelWindowErrorToast.ts, apps/desktop/src/renderer/components/new-chat/pastePipeline.ts, apps/desktop/src/renderer/components/new-chat/pathPaste.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueLocks.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueRowActivity.ts, apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts, apps/desktop/src/renderer/components/new-chat/planModeComposerCommand.ts, apps/desktop/src/renderer/components/new-chat/priceTierMarks.tsx, apps/desktop/src/renderer/components/new-chat/remoteBrowseAdapters.ts, apps/desktop/src/renderer/components/new-chat/remoteExistingProjects.ts, apps/desktop/src/renderer/components/new-chat/restoreComposerDocument.ts, apps/desktop/src/renderer/components/new-chat/sessionLinkPaste.ts, apps/desktop/src/renderer/components/new-chat/sourceSwitch.ts, apps/desktop/src/renderer/components/new-chat/unifiedModelSelection.ts, apps/desktop/src/renderer/components/new-chat/usagePalette.ts, apps/desktop/src/renderer/components/new-chat/useAskUserDictation.ts, apps/desktop/src/renderer/components/new-chat/useComposerSendFocusRestore.ts, apps/desktop/src/renderer/components/new-chat/useModelDiscoveryPending.ts, apps/desktop/src/renderer/components/new-chat/useProviderWeeklyQuota.ts, apps/desktop/src/renderer/components/new-chat/useUnifiedRowActions.ts, apps/desktop/src/renderer/components/new-chat/voiceQuestionSelection.ts, apps/desktop/src/renderer/features/cc-agent/CCAgentFeatureLayout.tsx, apps/desktop/src/renderer/features/cc-agent/CCAgentSessionView.tsx, apps/desktop/src/renderer/features/cc-agent/OrcaSplitView.tsx, apps/desktop/src/renderer/features/cc-agent/OrcaWorkerPanel.tsx, apps/desktop/src/renderer/features/cc-agent/OrcaWorkflowRoute.tsx | 270 | 38 | 360 |
| `desktop.chat.scheduled` | desktop | 调度任务列表 | hash `/cc-agent/scheduled`(SchedulerPage) | SchedulerPage | apps/desktop/src/renderer/features/scheduler/SchedulerPage.tsx, apps/desktop/src/renderer/features/scheduler/components/AgentMark.tsx, apps/desktop/src/renderer/features/scheduler/components/BoundSessionCard.tsx, apps/desktop/src/renderer/features/scheduler/components/ProjectAutomationNotifyBridge.tsx, apps/desktop/src/renderer/features/scheduler/components/RunHistoryCard.tsx, apps/desktop/src/renderer/features/scheduler/components/RunHistoryPane.tsx, apps/desktop/src/renderer/features/scheduler/components/ScheduleChips.tsx, apps/desktop/src/renderer/features/scheduler/components/ScheduleFormDialog.tsx, apps/desktop/src/renderer/features/scheduler/components/ScheduleSessionIndexOwner.tsx, apps/desktop/src/renderer/features/scheduler/components/ScheduleStatusChip.tsx, apps/desktop/src/renderer/features/scheduler/components/ScriptCapabilityMultiSelect.tsx, apps/desktop/src/renderer/features/scheduler/components/TaskListCell.tsx, apps/desktop/src/renderer/features/scheduler/components/TaskListFilterPopover.tsx, apps/desktop/src/renderer/features/scheduler/components/TaskListPane.tsx, apps/desktop/src/renderer/features/scheduler/components/TemplateCard.tsx, apps/desktop/src/renderer/features/scheduler/components/TemplateGallery.tsx, apps/desktop/src/renderer/features/scheduler/components/TemplateParamForm.tsx, apps/desktop/src/renderer/features/scheduler/hooks/useDeleteScheduleWithSessions.tsx, apps/desktop/src/renderer/features/scheduler/hooks/useReadFailedScheduleRuns.ts, apps/desktop/src/renderer/features/scheduler/hooks/useRunNowBusyGuard.ts, apps/desktop/src/renderer/features/scheduler/hooks/useRuns.ts, apps/desktop/src/renderer/features/scheduler/hooks/useScheduleForm.ts, apps/desktop/src/renderer/features/scheduler/hooks/useScheduleUnreadRunCounts.ts, apps/desktop/src/renderer/features/scheduler/hooks/useSchedules.ts, apps/desktop/src/renderer/features/scheduler/hooks/useSessionReferences.ts, apps/desktop/src/renderer/features/scheduler/hooks/useTemplates.ts, apps/desktop/src/renderer/features/scheduler/index.ts, apps/desktop/src/renderer/features/scheduler/lib/archiveScheduleWarning.ts, apps/desktop/src/renderer/features/scheduler/lib/cronCodexPreset.ts, apps/desktop/src/renderer/features/scheduler/lib/cronToHuman.ts, apps/desktop/src/renderer/features/scheduler/lib/failedScheduleDismissal.ts, apps/desktop/src/renderer/features/scheduler/lib/formatters.ts, apps/desktop/src/renderer/features/scheduler/lib/pluginScheduleCreateIntent.ts, apps/desktop/src/renderer/features/scheduler/lib/projectAutomationConfig.ts, apps/desktop/src/renderer/features/scheduler/lib/projectScheduleSidebarIndex.ts, apps/desktop/src/renderer/features/scheduler/lib/runHistoryGrouping.ts, apps/desktop/src/renderer/features/scheduler/lib/runUnread.ts, apps/desktop/src/renderer/features/scheduler/lib/scheduleBindingIndex.ts, apps/desktop/src/renderer/features/scheduler/lib/scheduleFormLogic.ts, apps/desktop/src/renderer/features/scheduler/lib/scheduleRunReadSync.ts, apps/desktop/src/renderer/features/scheduler/lib/scheduleSessionBinding.ts, apps/desktop/src/renderer/features/scheduler/lib/scheduleSidebarIndexRuns.ts, apps/desktop/src/renderer/features/scheduler/lib/schedulesStore.ts, apps/desktop/src/renderer/features/scheduler/lib/statusFilter.ts, apps/desktop/src/renderer/features/scheduler/lib/statusFilterStorage.ts, apps/desktop/src/renderer/features/scheduler/lib/templateLocalization.ts | 32 | 0 | 89 |
@@ -39,7 +39,7 @@
| `desktop.plugins.app-main` | desktop | 插件主视图 | hash `/apps/:ghostId`(GhostMainViewFeatureLayout) | GhostMainViewFeatureLayout, GhostMainViewHost | apps/desktop/src/renderer/features/plugin/GhostMainViewFeatureLayout.tsx, apps/desktop/src/renderer/features/plugin/GhostMainViewHost.tsx | 0 | 0 | 0 |
| `desktop.plugins.installed` | desktop | 已装插件 | hash `/plugins`(GhostPluginPage) | AddMarketplaceDialog, GhostPluginActions, GhostPluginDetailView, GhostPluginPage, MarketPluginDetailView, MyPublishesSection, PluginDevicePicker, PluginManagementLayout, PluginProjectMenu, RemotePluginConfiguration, RemotePluginPage, RemotePluginReadOnlyDetail, UpdateAllDialog | apps/desktop/src/renderer/features/plugin/AddMarketplaceDialog.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginActions.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/GhostPluginPage.tsx, apps/desktop/src/renderer/features/plugin/MarketPluginDetailView.tsx, apps/desktop/src/renderer/features/plugin/MyPublishesSection.tsx, apps/desktop/src/renderer/features/plugin/PluginDevicePicker.tsx, apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/plugin/PluginScopePicker.tsx, apps/desktop/src/renderer/features/plugin/RemotePluginConfiguration.tsx, apps/desktop/src/renderer/features/plugin/RemotePluginPage.tsx, apps/desktop/src/renderer/features/plugin/RemotePluginReadOnlyDetail.tsx, apps/desktop/src/renderer/features/plugin/UpdateAllDialog.tsx, apps/desktop/src/renderer/features/plugin/plugin-motion.css | 28 | 0 | 48 |
| `desktop.settings` | desktop | 设置 | hash `/settings`(SettingsView;tab 含 general / personalization / providers / billing / usage / voice-input / im-bot / shortcuts / agent-island / import / remote-control / ghosts / builtin-tools / computer-use / help / about) | SettingsView | apps/desktop/src/renderer/components/settings/AboutSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AboutSection.tsx, apps/desktop/src/renderer/components/settings/AccountDeletionSection.tsx, apps/desktop/src/renderer/components/settings/AddProviderWizard.tsx, apps/desktop/src/renderer/components/settings/AddSpeechModelsDialog.tsx, apps/desktop/src/renderer/components/settings/AgentIslandSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentIslandSection.tsx, apps/desktop/src/renderer/components/settings/AgentResourceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AgentResourceSection.tsx, apps/desktop/src/renderer/components/settings/AppearanceSection.settings-search.ts, apps/desktop/src/renderer/components/settings/AppearanceSection.tsx, apps/desktop/src/renderer/components/settings/AuxiliaryModelSection.tsx, apps/desktop/src/renderer/components/settings/AvatarCropEditor.tsx, apps/desktop/src/renderer/components/settings/BetaChannelCell.tsx, apps/desktop/src/renderer/components/settings/BillingSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/BrowserBackendSubsection.tsx, apps/desktop/src/renderer/components/settings/BrowserRealProfileSubsection.tsx, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/BuiltinToolsSection.tsx, apps/desktop/src/renderer/components/settings/ChatEmbeddingCell.tsx, apps/desktop/src/renderer/components/settings/ChipMetricsSection.tsx, apps/desktop/src/renderer/components/settings/CindyMakeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CindyMakeSection.tsx, apps/desktop/src/renderer/components/settings/CollaborationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/CollaborationSection.tsx, apps/desktop/src/renderer/components/settings/CompactionSection.tsx, apps/desktop/src/renderer/components/settings/ComposerSendShortcutSection.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx, apps/desktop/src/renderer/components/settings/ComputerPermissionRow.tsx, apps/desktop/src/renderer/components/settings/ComputerUseSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ComputerUseSection.tsx, apps/desktop/src/renderer/components/settings/CustomProviderRuntimeFillOverlay.tsx, apps/desktop/src/renderer/components/settings/DefaultOverrideControls.tsx, apps/desktop/src/renderer/components/settings/DialogueDirectorySection.tsx, apps/desktop/src/renderer/components/settings/DingTalkBotSection.tsx, apps/desktop/src/renderer/components/settings/DiscordBotSection.tsx, apps/desktop/src/renderer/components/settings/DownloadMeter.tsx, apps/desktop/src/renderer/components/settings/ExperimentalSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotNotificationSection.tsx, apps/desktop/src/renderer/components/settings/FeishuBotSection.tsx, apps/desktop/src/renderer/components/settings/FontFamilyPicker.tsx, apps/desktop/src/renderer/components/settings/GeneralSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/GenericGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/GitSafetySection.settings-search.ts, apps/desktop/src/renderer/components/settings/GitSafetySection.tsx, apps/desktop/src/renderer/components/settings/HarnessVersionMenuRow.tsx, apps/desktop/src/renderer/components/settings/HelpAssistantPanel.tsx, apps/desktop/src/renderer/components/settings/HelpSection.settings-search.ts, apps/desktop/src/renderer/components/settings/HelpSection.tsx, apps/desktop/src/renderer/components/settings/HelpThreadView.tsx, apps/desktop/src/renderer/components/settings/HookConnectionsSection.tsx, apps/desktop/src/renderer/components/settings/HookWorkspacePrefsEditor.tsx, apps/desktop/src/renderer/components/settings/ImBotSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ImBotSection.tsx, apps/desktop/src/renderer/components/settings/ImChannelSettingsCard.tsx, apps/desktop/src/renderer/components/settings/ImDefaultSettingsSection.tsx, apps/desktop/src/renderer/components/settings/ImLifecycleAnnouncementSection.tsx, apps/desktop/src/renderer/components/settings/InputDeviceConnectionStatus.tsx, apps/desktop/src/renderer/components/settings/JoyConGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx, apps/desktop/src/renderer/components/settings/LanguageSection.tsx, apps/desktop/src/renderer/components/settings/LayoutResetControl.tsx, apps/desktop/src/renderer/components/settings/LinkOpenSection.tsx, apps/desktop/src/renderer/components/settings/LlamaCppCandidates.tsx, apps/desktop/src/renderer/components/settings/LlamaCppProviderDetail.tsx, apps/desktop/src/renderer/components/settings/LocalAgentSection.settings-search.ts, apps/desktop/src/renderer/components/settings/LocalAgentSection.tsx, apps/desktop/src/renderer/components/settings/LocalModelDownloadUI.tsx, apps/desktop/src/renderer/components/settings/LocalOllamaInstall.tsx, apps/desktop/src/renderer/components/settings/LocalPackagingTag.tsx, apps/desktop/src/renderer/components/settings/LogoutSection.tsx, apps/desktop/src/renderer/components/settings/LspBetaCell.tsx, apps/desktop/src/renderer/components/settings/McpServerDialog.tsx, apps/desktop/src/renderer/components/settings/McpServersSection.tsx, apps/desktop/src/renderer/components/settings/MemorySection.tsx, apps/desktop/src/renderer/components/settings/MessageNavRailCell.tsx, apps/desktop/src/renderer/components/settings/ModelAdvancedDrawer.tsx, apps/desktop/src/renderer/components/settings/ModelPriceOverrideDialog.tsx, apps/desktop/src/renderer/components/settings/MyDevicesPanel.tsx, apps/desktop/src/renderer/components/settings/NotificationSection.settings-search.ts, apps/desktop/src/renderer/components/settings/NotificationSection.tsx, apps/desktop/src/renderer/components/settings/OAuthDeviceCodeCard.tsx, apps/desktop/src/renderer/components/settings/OllamaProviderDetail.tsx, apps/desktop/src/renderer/components/settings/OwnRemoteProviders.tsx, apps/desktop/src/renderer/components/settings/PersonalizationDetails.settings-search.ts, apps/desktop/src/renderer/components/settings/PersonalizationSettings.settings-search.ts, apps/desktop/src/renderer/components/settings/PiKernelVersionRow.tsx, apps/desktop/src/renderer/components/settings/PiPackagesSection.tsx, apps/desktop/src/renderer/components/settings/PlayStationGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/ProfileEditDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderConnectionDialog.tsx, apps/desktop/src/renderer/components/settings/ProviderImportDialog.tsx, apps/desktop/src/renderer/components/settings/ProvidersSection.settings-search.ts, apps/desktop/src/renderer/components/settings/ProvidersSection.tsx, apps/desktop/src/renderer/components/settings/ReadOnlyProviderModels.tsx, apps/desktop/src/renderer/components/settings/RemoteControlSection.settings-search.ts, apps/desktop/src/renderer/components/settings/RemoteControlSection.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopPermissions.tsx, apps/desktop/src/renderer/components/settings/RemoteDesktopSetting.tsx, apps/desktop/src/renderer/components/settings/RemoteHostDetail.tsx, apps/desktop/src/renderer/components/settings/RemoteSection.tsx, apps/desktop/src/renderer/components/settings/SessionImportSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SessionImportSection.tsx, apps/desktop/src/renderer/components/settings/SessionRuntimeFallbackCell.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.settings-search.ts, apps/desktop/src/renderer/components/settings/SettingsCatalogPanel.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchBox.tsx, apps/desktop/src/renderer/components/settings/SettingsSearchNavigation.ts, apps/desktop/src/renderer/components/settings/SettingsSidebarNav.tsx, apps/desktop/src/renderer/components/settings/SettingsTextInput.tsx, apps/desktop/src/renderer/components/settings/SettingsView.tsx, apps/desktop/src/renderer/components/settings/SharedTasks.settings-search.ts, apps/desktop/src/renderer/components/settings/SilentEncryptedRetryCell.tsx, apps/desktop/src/renderer/components/settings/SpeechModelChoices.tsx, apps/desktop/src/renderer/components/settings/SshKeySetupDialog.tsx, apps/desktop/src/renderer/components/settings/StorageManagementCard.settings-search.ts, apps/desktop/src/renderer/components/settings/StorageManagementCard.tsx, apps/desktop/src/renderer/components/settings/StreamFadeSection.tsx, apps/desktop/src/renderer/components/settings/SubagentModelSection.settings-search.ts, apps/desktop/src/renderer/components/settings/SubagentModelSection.tsx, apps/desktop/src/renderer/components/settings/SwitchProGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/TelegramBehaviorSettings.tsx, apps/desktop/src/renderer/components/settings/TelegramBotSection.tsx, apps/desktop/src/renderer/components/settings/TelegramRemoteDevices.tsx, apps/desktop/src/renderer/components/settings/TerminalShellSection.tsx, apps/desktop/src/renderer/components/settings/TipsSection.settings-search.ts, apps/desktop/src/renderer/components/settings/TipsSection.tsx, apps/desktop/src/renderer/components/settings/UnifiedModelList.tsx, apps/desktop/src/renderer/components/settings/UserProfileCard.tsx, apps/desktop/src/renderer/components/settings/UserPromptSection.tsx, apps/desktop/src/renderer/components/settings/VisionBridgeSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VisionBridgeSection.tsx, apps/desktop/src/renderer/components/settings/VoiceInputSection.settings-search.ts, apps/desktop/src/renderer/components/settings/VoiceInputSection.tsx, apps/desktop/src/renderer/components/settings/VoiceSpeakerEnrollmentDialog.tsx, apps/desktop/src/renderer/components/settings/VoiceSpeakerFilterCard.tsx, apps/desktop/src/renderer/components/settings/WallpaperSection.tsx, apps/desktop/src/renderer/components/settings/WechatBotSection.tsx, apps/desktop/src/renderer/components/settings/WecomBotSection.tsx, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.settings-search.ts, apps/desktop/src/renderer/components/settings/WindowBehaviorSection.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeyboardLayout.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexKeycapGlyphs.tsx, apps/desktop/src/renderer/components/settings/WorkLouderCodexSettings.tsx, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.settings-search.ts, apps/desktop/src/renderer/components/settings/WorktreeRecycleCard.tsx, apps/desktop/src/renderer/components/settings/XUsageGuide.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadLayout.tsx, apps/desktop/src/renderer/components/settings/XboxGamepadSettings.tsx, apps/desktop/src/renderer/components/settings/androidStatusPresentation.ts, apps/desktop/src/renderer/components/settings/avatarCropGeometry.ts, apps/desktop/src/renderer/components/settings/avatarCropImage.ts, apps/desktop/src/renderer/components/settings/billingVisibility.ts, apps/desktop/src/renderer/components/settings/browserOpenForLoginError.ts, apps/desktop/src/renderer/components/settings/cindyMakeVisibility.ts, apps/desktop/src/renderer/components/settings/computerPermissionFlow.ts, apps/desktop/src/renderer/components/settings/contacts/ContactDetailPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsImportDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsListPane.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsManagerDialog.tsx, apps/desktop/src/renderer/components/settings/contacts/ContactsSection.tsx, apps/desktop/src/renderer/components/settings/contacts/startContactsAiSession.ts, apps/desktop/src/renderer/components/settings/dialogueDirectoryDisplay.ts, apps/desktop/src/renderer/components/settings/dualSenseSilhouette.ts, apps/desktop/src/renderer/components/settings/feishuBotPresentation.ts, apps/desktop/src/renderer/components/settings/fontFamilyValue.ts, apps/desktop/src/renderer/components/settings/gamepadLayoutPrimitives.tsx, apps/desktop/src/renderer/components/settings/gamepadSilhouetteGeom.ts, apps/desktop/src/renderer/components/settings/hookWorkspacePrefsLogic.ts, apps/desktop/src/renderer/components/settings/imBotVisibility.ts, apps/desktop/src/renderer/components/settings/imDefaultSettingsLogic.ts, apps/desktop/src/renderer/components/settings/joyConSilhouette.ts, apps/desktop/src/renderer/components/settings/modelManagementPresentation.ts, apps/desktop/src/renderer/components/settings/modelManagementState.ts, apps/desktop/src/renderer/components/settings/myDevicesModel.ts, apps/desktop/src/renderer/components/settings/providerAssetModule.ts, apps/desktop/src/renderer/components/settings/realProfilePermissionGuide.ts, apps/desktop/src/renderer/components/settings/settingsRowClasses.ts, apps/desktop/src/renderer/components/settings/settingsSearchCatalog.ts, apps/desktop/src/renderer/components/settings/settingsSearchTypes.ts, apps/desktop/src/renderer/components/settings/switchProSilhouette.ts, apps/desktop/src/renderer/components/settings/ultimateC1Silhouette.ts, apps/desktop/src/renderer/components/settings/usage/UsageBarsTooltip.tsx, apps/desktop/src/renderer/components/settings/usage/UsageBreakdownTables.tsx, apps/desktop/src/renderer/components/settings/usage/UsageDeviceSelect.tsx, apps/desktop/src/renderer/components/settings/usage/UsageFilterSelect.tsx, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.settings-search.ts, apps/desktop/src/renderer/components/settings/usage/UsageHistorySection.tsx, apps/desktop/src/renderer/components/settings/usage/UsageStatRow.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTaskTable.tsx, apps/desktop/src/renderer/components/settings/usage/UsageTokenBars.tsx, apps/desktop/src/renderer/components/settings/usage/formatUsagePercent.ts, apps/desktop/src/renderer/components/settings/usage/usageCharts.css, apps/desktop/src/renderer/components/settings/usage/usageHistoryColors.ts, apps/desktop/src/renderer/components/settings/usage/usageHistoryStats.ts, apps/desktop/src/renderer/components/settings/usageVisibility.ts, apps/desktop/src/renderer/components/settings/useProviderSubscriptionCard.ts, apps/desktop/src/renderer/components/settings/useSettingsEscape.ts, apps/desktop/src/renderer/components/settings/useSettingsSectionTarget.ts, apps/desktop/src/renderer/components/settings/wizardRecommend.ts, apps/desktop/src/renderer/components/settings/workLouderCodexCommandCopy.ts, apps/desktop/src/renderer/components/settings/xboxSeriesSilhouette.ts, apps/desktop/src/renderer/styles/sortable.css | 137 | 95 | 548 |
-| `desktop.shell.main-layout` | desktop | 主窗口壳(标题栏 / 左右栏 / 内容区) | main BrowserWindow → renderer/index.tsx → main-entry.tsx → App → MainLayout (`#/` 受保护壳) | ChromeActions, DeviceSectionHeader, FeishuConflictDialogHost, GhostMediaLightboxHost, MainLayout, ProjectsSection, RightSidebar, RightSidebarShell, SessionShareImportWizard, Sidebar, UpdateNoticeDialog, WindowControls | apps/desktop/src/renderer/cindy-brain/GhostMediaLightboxHost.tsx, apps/desktop/src/renderer/components/UpdateNoticeDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialogHost.tsx, apps/desktop/src/renderer/components/layout/AppBadgeAttentionSync.tsx, apps/desktop/src/renderer/components/layout/BrowserWebviewPool.tsx, apps/desktop/src/renderer/components/layout/ChromeActions.tsx, apps/desktop/src/renderer/components/layout/ContentHeader.tsx, apps/desktop/src/renderer/components/layout/CredentialStoreBanner.tsx, apps/desktop/src/renderer/components/layout/FadeSwitcher.tsx, apps/desktop/src/renderer/components/layout/GlobalDropImportListener.tsx, apps/desktop/src/renderer/components/layout/MainEntryRedirect.tsx, apps/desktop/src/renderer/components/layout/MainLayout.tsx, apps/desktop/src/renderer/components/layout/RightSidebar.tsx, apps/desktop/src/renderer/components/layout/RightSidebarDetach.tsx, apps/desktop/src/renderer/components/layout/RightSidebarMaximize.tsx, apps/desktop/src/renderer/components/layout/RightSidebarToggle.tsx, apps/desktop/src/renderer/components/layout/SidebarTabWindowLayout.tsx, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/components/layout/WallpaperVideo.tsx, apps/desktop/src/renderer/components/layout/chromeActionsGeometry.ts, apps/desktop/src/renderer/components/layout/chromeActionsLayout.ts, apps/desktop/src/renderer/components/layout/railChromeActions.ts, apps/desktop/src/renderer/components/layout/windowDrag.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/sidebar/AccountSwitcherDialog.tsx, apps/desktop/src/renderer/components/sidebar/AttentionDot.tsx, apps/desktop/src/renderer/components/sidebar/DatabaseSizeWarningBanner.tsx, apps/desktop/src/renderer/components/sidebar/GhostMainViewNavEntries.tsx, apps/desktop/src/renderer/components/sidebar/MobileDownloadDialog.tsx, apps/desktop/src/renderer/components/sidebar/NavigationCountBadge.tsx, apps/desktop/src/renderer/components/sidebar/NewTag.tsx, apps/desktop/src/renderer/components/sidebar/Sidebar.tsx, apps/desktop/src/renderer/components/sidebar/SidebarIconButton.tsx, apps/desktop/src/renderer/components/sidebar/SidebarNavigationCustomize.tsx, apps/desktop/src/renderer/components/sidebar/SidebarTopNav.tsx, apps/desktop/src/renderer/components/sidebar/SortableList.tsx, apps/desktop/src/renderer/components/sidebar/UpdateBanner.tsx, apps/desktop/src/renderer/components/sidebar/UserInfoSection.tsx, apps/desktop/src/renderer/components/sidebar/VendorIcon.tsx, apps/desktop/src/renderer/components/sidebar/VendorReadinessBadge.tsx, apps/desktop/src/renderer/components/sidebar/WorktreeBadge.tsx, apps/desktop/src/renderer/components/sidebar/sidebarNavigationPrefs.ts, apps/desktop/src/renderer/components/sidebar/useHoverOpenMenu.ts, apps/desktop/src/renderer/components/title-bar/ChromeIconButton.tsx, apps/desktop/src/renderer/components/title-bar/MenuButton.tsx, apps/desktop/src/renderer/components/title-bar/WindowControls.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/DeviceSectionHeader.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/sections/ProjectsSection.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/TabDragController.tsx, apps/desktop/src/renderer/features/right-sidebar/TabGroupPanel.tsx, apps/desktop/src/renderer/features/right-sidebar/botMenuOwnerContext.ts, apps/desktop/src/renderer/features/right-sidebar/globalTabs.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useRetainedBrowserTabHosts.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.test.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mergeSidebarWindowBack.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openPluginTaskTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSideChatTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/lib/tabHosting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/useTabCreationMenu.ts, apps/desktop/src/renderer/features/right-sidebar/moveTab.ts, apps/desktop/src/renderer/features/right-sidebar/pluginPlacement.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailCardBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailConversationView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailPreview.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-task/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-view/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/retired-feature/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/state.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/tabAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroupHost.tsx, apps/desktop/src/renderer/features/right-sidebar/tabGroupPanes.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroups.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/layout/LayoutRoot.tsx, apps/desktop/src/renderer/layout/PanelDragController.tsx, apps/desktop/src/renderer/layout/PanelDragPrototype.tsx, apps/desktop/src/renderer/layout/collapsePrefs.ts, apps/desktop/src/renderer/layout/layoutDevTools.ts, apps/desktop/src/renderer/layout/panePlacement.tsx, apps/desktop/src/renderer/layout/paneWidths.tsx, apps/desktop/src/renderer/layout/panelMaximize.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 147 | 46 | 201 |
+| `desktop.shell.main-layout` | desktop | 主窗口壳(标题栏 / 左右栏 / 内容区) | main BrowserWindow → renderer/index.tsx → main-entry.tsx → App → MainLayout (`#/` 受保护壳) | ChromeActions, DeviceSectionHeader, FeishuConflictDialogHost, GhostMediaLightboxHost, MainLayout, ProjectsSection, RightSidebar, RightSidebarShell, SessionShareImportWizard, Sidebar, UpdateNoticeDialog, WindowControls | apps/desktop/src/renderer/cindy-brain/GhostMediaLightboxHost.tsx, apps/desktop/src/renderer/components/UpdateNoticeDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialog.tsx, apps/desktop/src/renderer/components/feishuBot/FeishuConflictDialogHost.tsx, apps/desktop/src/renderer/components/layout/AppBadgeAttentionSync.tsx, apps/desktop/src/renderer/components/layout/BrowserWebviewPool.tsx, apps/desktop/src/renderer/components/layout/ChromeActions.tsx, apps/desktop/src/renderer/components/layout/ContentHeader.tsx, apps/desktop/src/renderer/components/layout/CredentialStoreBanner.tsx, apps/desktop/src/renderer/components/layout/FadeSwitcher.tsx, apps/desktop/src/renderer/components/layout/GlobalDropImportListener.tsx, apps/desktop/src/renderer/components/layout/MainEntryRedirect.tsx, apps/desktop/src/renderer/components/layout/MainLayout.tsx, apps/desktop/src/renderer/components/layout/RightSidebar.tsx, apps/desktop/src/renderer/components/layout/RightSidebarDetach.tsx, apps/desktop/src/renderer/components/layout/RightSidebarMaximize.tsx, apps/desktop/src/renderer/components/layout/RightSidebarToggle.tsx, apps/desktop/src/renderer/components/layout/SidebarTabWindowLayout.tsx, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/components/layout/WallpaperVideo.tsx, apps/desktop/src/renderer/components/layout/chromeActionsGeometry.ts, apps/desktop/src/renderer/components/layout/chromeActionsLayout.ts, apps/desktop/src/renderer/components/layout/railChromeActions.ts, apps/desktop/src/renderer/components/layout/windowDrag.tsx, apps/desktop/src/renderer/components/settings/SessionShareImportWizard.tsx, apps/desktop/src/renderer/components/sidebar/AccountSwitcherDialog.tsx, apps/desktop/src/renderer/components/sidebar/AttentionDot.tsx, apps/desktop/src/renderer/components/sidebar/DatabaseSizeWarningBanner.tsx, apps/desktop/src/renderer/components/sidebar/GhostMainViewNavEntries.tsx, apps/desktop/src/renderer/components/sidebar/MobileDownloadDialog.tsx, apps/desktop/src/renderer/components/sidebar/NavigationCountBadge.tsx, apps/desktop/src/renderer/components/sidebar/NewTag.tsx, apps/desktop/src/renderer/components/sidebar/Sidebar.tsx, apps/desktop/src/renderer/components/sidebar/SidebarIconButton.tsx, apps/desktop/src/renderer/components/sidebar/SidebarNavigationCustomize.tsx, apps/desktop/src/renderer/components/sidebar/SidebarTopNav.tsx, apps/desktop/src/renderer/components/sidebar/SortableList.tsx, apps/desktop/src/renderer/components/sidebar/UpdateBanner.tsx, apps/desktop/src/renderer/components/sidebar/UserInfoSection.tsx, apps/desktop/src/renderer/components/sidebar/VendorIcon.tsx, apps/desktop/src/renderer/components/sidebar/VendorReadinessBadge.tsx, apps/desktop/src/renderer/components/sidebar/WorktreeBadge.tsx, apps/desktop/src/renderer/components/sidebar/sidebarNavigationPrefs.ts, apps/desktop/src/renderer/components/sidebar/useHoverOpenMenu.ts, apps/desktop/src/renderer/components/title-bar/ChromeIconButton.tsx, apps/desktop/src/renderer/components/title-bar/MenuButton.tsx, apps/desktop/src/renderer/components/title-bar/WindowControls.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/DeviceSectionHeader.tsx, apps/desktop/src/renderer/features/cc-agent/sidebar/sections/ProjectsSection.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/TabDragController.tsx, apps/desktop/src/renderer/features/right-sidebar/TabGroupPanel.tsx, apps/desktop/src/renderer/features/right-sidebar/botMenuOwnerContext.ts, apps/desktop/src/renderer/features/right-sidebar/globalTabs.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useRetainedBrowserTabHosts.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.test.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mergeSidebarWindowBack.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openPluginTaskTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSideChatTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/lib/tabHosting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/useTabCreationMenu.ts, apps/desktop/src/renderer/features/right-sidebar/moveTab.ts, apps/desktop/src/renderer/features/right-sidebar/pluginPlacement.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailCardBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailConversationView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailPreview.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-task/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-view/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/retired-feature/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/state.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/tabAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroupHost.tsx, apps/desktop/src/renderer/features/right-sidebar/tabGroupPanes.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroups.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/layout/LayoutRoot.tsx, apps/desktop/src/renderer/layout/PanelDragController.tsx, apps/desktop/src/renderer/layout/PanelDragPrototype.tsx, apps/desktop/src/renderer/layout/collapsePrefs.ts, apps/desktop/src/renderer/layout/layoutDevTools.ts, apps/desktop/src/renderer/layout/panePlacement.tsx, apps/desktop/src/renderer/layout/paneWidths.tsx, apps/desktop/src/renderer/layout/panelMaximize.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 147 | 46 | 197 |
| `desktop.skillhub.local` | desktop | SkillHub 本地技能 | hash `/skillhub/local` 及统一详情 `/skillhub/detail`(旧详情链接重定向) | InstallTargetPicker, PluginDevicePicker, PluginManagementLayout, RemoteSkillsPage, SkillCategoryFilterBar, SkillDetailLayout, SkillhubDetailRoute, SkillhubDetailView, SkillhubFeatureLayout, SkillhubHomeView, SkillhubLocalLayout, SkillhubMarketDetailView | apps/desktop/src/renderer/features/plugin/PluginDevicePicker.tsx, apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/skillhub/RemoteSkillsPage.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailRoute.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubFeatureLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubLocalLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx, apps/desktop/src/renderer/features/skillhub/skillhub-home.css | 39 | 0 | 45 |
| `desktop.skillhub.market` | desktop | SkillHub 市场 | hash `/skillhub/market`(SkillhubMarketListView) | InstallTargetPicker, MarketCard, MarketInfoEditDialog, SkillhubMarketDetailView, SkillhubMarketListView, VisibilityEditorDialog | apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx, apps/desktop/src/renderer/features/skillhub/components/HomeMarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/LocalSkillControls.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInfoEditDialog.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInstallStatus.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketListError.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketLocalSkills.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketPreviewTree.tsx, apps/desktop/src/renderer/features/skillhub/components/OfficialSkillBadge.tsx, apps/desktop/src/renderer/features/skillhub/components/PlatformTagSelector.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillIcon.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillTagList.tsx, apps/desktop/src/renderer/features/skillhub/components/TeamScopePicker.tsx, apps/desktop/src/renderer/features/skillhub/components/VisibilityEditorDialog.tsx | 42 | 0 | 35 |
| `desktop.window.computer-permission-guide` | desktop | 电脑使用权限引导 | `?view=computer-permission-guide` → ComputerPermissionGuideWindow;backdrop 同文件 | ComputerPermissionBackdrop, ComputerPermissionGuideWindow | apps/desktop/src/main/computer-permission-guide/MacComputerPermissionGuideNativeHost.ts, apps/desktop/src/main/computer-permission-guide/placement.ts, apps/desktop/src/main/computer-permission-guide/request.ts, apps/desktop/src/main/computer-permission-guide/switch-target.ts, apps/desktop/src/main/computer-permission-guide/window.ts, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx | 7 | 2 | 9 |
@@ -47,7 +47,7 @@
| `desktop.window.resource-usage` | desktop | 资源用量窗口 | `?resourceUsageWindow=1` → renderer/resource-usage-entry.tsx(不走 router.tsx) | ResourceUsageWindowLayout, ResourceUsageWindowRoot | apps/desktop/src/main/resource-usage-window/controller.ts, apps/desktop/src/main/resource-usage-window/ipc.ts, apps/desktop/src/main/resource-usage-window/open-sender.ts, apps/desktop/src/main/resource-usage-window/registry.ts, apps/desktop/src/main/resource-usage-window/window.ts, apps/desktop/src/renderer/components/resource-usage/ResourceUsageWindowLayout.tsx, apps/desktop/src/renderer/resource-usage-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 79 | 38 | 15 |
| `desktop.window.review-artifact-confirm` | desktop | Review 成果确认窗 | main/reviewer/reviewArtifactConfirmWindow.ts 内联 HTML/CSS(不走 renderer 路由) | reviewArtifactConfirmWindow | apps/desktop/src/main/reviewer/reviewArtifactConfirmWindow.ts | 8 | 18 | 2 |
| `desktop.window.session-drag-preview` | desktop | 会话拖拽预览 | main/session-drag-preview.ts 透明预览窗 | session-drag-preview | apps/desktop/src/main/session-drag-preview.ts | 0 | 1 | 0 |
-| `desktop.window.sidebar` | desktop | 右侧栏独立窗口 | `?sidebarWindow=1` → renderer/sidebar-window-entry.tsx;hash `/sidebar-window` | RightSidebar, RightSidebarShell, SidebarWindowLayout | apps/desktop/src/main/right-sidebar-window/controller.ts, apps/desktop/src/main/right-sidebar-window/ipc.ts, apps/desktop/src/main/right-sidebar-window/registry.ts, apps/desktop/src/main/right-sidebar-window/resolveHostContext.ts, apps/desktop/src/main/right-sidebar-window/settings-store.ts, apps/desktop/src/main/right-sidebar-window/window.ts, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/TabDragController.tsx, apps/desktop/src/renderer/features/right-sidebar/TabGroupPanel.tsx, apps/desktop/src/renderer/features/right-sidebar/botMenuOwnerContext.ts, apps/desktop/src/renderer/features/right-sidebar/globalTabs.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useRetainedBrowserTabHosts.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.test.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mergeSidebarWindowBack.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openPluginTaskTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSideChatTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/lib/tabHosting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/useTabCreationMenu.ts, apps/desktop/src/renderer/features/right-sidebar/moveTab.ts, apps/desktop/src/renderer/features/right-sidebar/pluginPlacement.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailCardBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailConversationView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailPreview.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-task/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-view/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/retired-feature/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/state.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/tabAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroupHost.tsx, apps/desktop/src/renderer/features/right-sidebar/tabGroupPanes.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroups.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/sidebar-window-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 113 | 45 | 120 |
+| `desktop.window.sidebar` | desktop | 右侧栏独立窗口 | `?sidebarWindow=1` → renderer/sidebar-window-entry.tsx;hash `/sidebar-window` | RightSidebar, RightSidebarShell, SidebarWindowLayout | apps/desktop/src/main/right-sidebar-window/controller.ts, apps/desktop/src/main/right-sidebar-window/ipc.ts, apps/desktop/src/main/right-sidebar-window/registry.ts, apps/desktop/src/main/right-sidebar-window/resolveHostContext.ts, apps/desktop/src/main/right-sidebar-window/settings-store.ts, apps/desktop/src/main/right-sidebar-window/window.ts, apps/desktop/src/renderer/components/layout/SidebarWindowLayout.tsx, apps/desktop/src/renderer/features/right-sidebar/AddTabDropdown.tsx, apps/desktop/src/renderer/features/right-sidebar/EmptyState.tsx, apps/desktop/src/renderer/features/right-sidebar/RightSidebarShell.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBar.tsx, apps/desktop/src/renderer/features/right-sidebar/TabBodyErrorBoundary.tsx, apps/desktop/src/renderer/features/right-sidebar/TabDragController.tsx, apps/desktop/src/renderer/features/right-sidebar/TabGroupPanel.tsx, apps/desktop/src/renderer/features/right-sidebar/botMenuOwnerContext.ts, apps/desktop/src/renderer/features/right-sidebar/globalTabs.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useBrowserWebview.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useNativePopupSurface.ts, apps/desktop/src/renderer/features/right-sidebar/hooks/useRetainedBrowserTabHosts.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserPartition.ts, apps/desktop/src/renderer/features/right-sidebar/lib/browserWebviewPool.ts, apps/desktop/src/renderer/features/right-sidebar/lib/detachedSidebarRouting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/executeSidebarCommand.ts, apps/desktop/src/renderer/features/right-sidebar/lib/lastTurnChangedFiles.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.test.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mailPreview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/mergeSidebarWindowBack.ts, apps/desktop/src/renderer/features/right-sidebar/lib/nativePopupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openBackgroundTasksTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openInSidebarFileBrowser.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openPluginTaskTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openRoutinesTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSideChatTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openSubagentsTab.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTerminalShortcut.ts, apps/desktop/src/renderer/features/right-sidebar/lib/openTurnReview.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupRouter.ts, apps/desktop/src/renderer/features/right-sidebar/lib/popupTabs.ts, apps/desktop/src/renderer/features/right-sidebar/lib/rsbBrowserBridge.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarCommands.ts, apps/desktop/src/renderer/features/right-sidebar/lib/sidebarHostSession.tsx, apps/desktop/src/renderer/features/right-sidebar/lib/tabHosting.ts, apps/desktop/src/renderer/features/right-sidebar/lib/useTabCreationMenu.ts, apps/desktop/src/renderer/features/right-sidebar/moveTab.ts, apps/desktop/src/renderer/features/right-sidebar/pluginPlacement.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/BackgroundTasksBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowAgentStrip.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/WorkflowProgressTree.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/chatTaskFocusIntent.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/listSessionTasks.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/background-tasks/workflowProgressModel.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/CindyMakeTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/cindy-make/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.css, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/FileBrowserBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/dropExternalFile.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/fileTreeImagePreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/file-browser/useSessionScopedTreeWidth.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/index.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailCardBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailConversationView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/MailPreview.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/mail-preview/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersAttentionIcon.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/OrcaWorkersTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/actions.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/closeDecision.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/orca-workers/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-task/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/plugin-view/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/ResourceUsageBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/resource-usage.css, apps/desktop/src/renderer/features/right-sidebar/plugins/resource-usage/subscription.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/retired-feature/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/ImageDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/MarkdownDiffPreview.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/PlainUnifiedDiff.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/diffRows.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/highlight.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/inlineDiff.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/DiffViewer/useDiffHighlights.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/ReviewTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/diffExpansionPreference.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/fileTree.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/gitApplyCommand.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/review/markdownPreview.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useLastTurnFilter.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewGitState.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/review/useReviewSource.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/routines/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.test.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/SideChatTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/side-chat/state.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/ConversationStream.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/DetailView.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/RunList.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentToolCard.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/SubagentsBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentChangeFence.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentConversation.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/subagents/subagentFormat.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/TerminalTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/terminal/lib/xtermPool.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserChrome.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserCommentPopover.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/BrowserTabBody.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/browserCommentEditorDraft.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/index.tsx, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/lib/parseOmnibox.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useBrowserComment.ts, apps/desktop/src/renderer/features/right-sidebar/plugins/web-browser/useLocalHtmlAutoReload.ts, apps/desktop/src/renderer/features/right-sidebar/registry.ts, apps/desktop/src/renderer/features/right-sidebar/store.ts, apps/desktop/src/renderer/features/right-sidebar/tabAvailability.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroupHost.tsx, apps/desktop/src/renderer/features/right-sidebar/tabGroupPanes.ts, apps/desktop/src/renderer/features/right-sidebar/tabGroups.ts, apps/desktop/src/renderer/features/right-sidebar/types.ts, apps/desktop/src/renderer/sidebar-window-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 113 | 45 | 116 |
| `desktop.window.voice-dictionary-toast` | desktop | 语音词典 Toast 窗 | `?view=voice-input-dictionary-toast` → main-entry.tsx → VoiceInputDictionaryToast | VoiceInputDictionaryToast | apps/desktop/src/renderer/voice-input/VoiceInputDictionaryToast.tsx | 6 | 0 | 2 |
| `desktop.window.voice-overlay` | desktop | 语音输入浮窗 | `?view=voice-input-overlay` → main-entry.tsx → VoiceInputOverlay | VoiceInputOverlay, VoiceInputStatusNotice | apps/desktop/src/main/voice-input/global.ts, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css, apps/desktop/src/renderer/voice-input/VoiceInputOverlay.tsx, apps/desktop/src/renderer/voice-input/VoiceInputStatusNotice.tsx | 84 | 38 | 20 |
| `mobile.account-deletion` | mobile | 账号注销 | app/account-deletion.tsx | AdaptiveWindow, AnchoredPullDownMenu, AnchoredPullDownMenu.android, AndroidUpdateSheet, AppText, AuthContext, BlurBackdrop, CenteredScreen, ConnectionBanner, ConnectionNoticeOverlay, DeviceLinkContext, DirectLinkTransport, FoldTouchpad, HomeEntryProvider, HomeHeaderGlassButton, HomeHeaderGlassButton.ios, HomeNativeStackHeader, HomeStackHeader, IncomingShareBridge, McpAppViews, MobileLoginHandoffContext, MobileLoginHandoffStage, MobileOutboxBridge, MobilePrimitives, NativeBottomSheet, NativeBottomSheet.android, NativeChromeBackButton.ios, NativeChromeButton.ios, NativeMcpAppSurface, NativePullDownMenu, NativeRemoteDesktopView, NativeResidentHistory, NativeSwitch, OutsideTap, PermissionGuide, PermissionGuideView, PermissionGuideView.ios, PushNotificationsBridge, QuietSyncIndicator, RecentMessageHistories, RemoteDesktopActionButton, RemoteDesktopActionButton.ios, RemoteDesktopBackButton, RemoteDesktopBackButton.ios, RemoteDesktopChrome, RemoteDesktopChrome.ios, RemoteDesktopClipboardButton, RemoteDesktopControls, RemoteDesktopDisplaySettings, RemoteDesktopHost, RemoteDesktopIcons, RemoteDesktopMouseControls, RemoteDesktopMouseControls.ios, RemoteDesktopNetworkStatus, RemoteDesktopPanelButton, RemoteDesktopPanelButton.ios, RemoteDesktopScreen, RemoteDesktopSecuritySettings, RemoteDesktopWindows, RemoteHistoryPrefetchBridge, ResidentHomeList, SheetModal, SimpleStackHeader, StartupSplashOverlay, ThemeProvider, _layout, account-deletion, gestureHandler, nativeToolbarMenuItems, peerFileTransport, useLocale | apps/mobile/app/_layout.tsx, apps/mobile/app/account-deletion.tsx, apps/mobile/src/auth/AuthContext.tsx, apps/mobile/src/auth/MobileLoginHandoffContext.tsx, apps/mobile/src/components/AppText.tsx, apps/mobile/src/components/CenteredScreen.tsx, apps/mobile/src/components/ConnectionBanner.tsx, apps/mobile/src/components/ConnectionNoticeOverlay.tsx, apps/mobile/src/components/MobileLoginHandoffStage.tsx, apps/mobile/src/components/MobilePrimitives.tsx, apps/mobile/src/components/QuietSyncIndicator.tsx, apps/mobile/src/components/StartupSplashOverlay.tsx, apps/mobile/src/device-link/DeviceLinkContext.tsx, apps/mobile/src/device-link/DirectLinkTransport.tsx, apps/mobile/src/device-link/peerFileTransport.tsx, apps/mobile/src/i18n/useLocale.tsx, apps/mobile/src/notifications/PushNotificationsBridge.tsx, apps/mobile/src/platform/AdaptiveWindow.tsx, apps/mobile/src/platform/OutsideTap.tsx, apps/mobile/src/platform/chrome/AnchoredPullDownMenu.android.tsx, apps/mobile/src/platform/chrome/AnchoredPullDownMenu.tsx, apps/mobile/src/platform/chrome/HomeNativeStackHeader.tsx, apps/mobile/src/platform/chrome/HomeStackHeader.tsx, apps/mobile/src/platform/chrome/NativeChromeBackButton.ios.tsx, apps/mobile/src/platform/chrome/NativeChromeButton.ios.tsx, apps/mobile/src/platform/chrome/NativePullDownMenu.tsx, apps/mobile/src/platform/chrome/NativeSwitch.tsx, apps/mobile/src/platform/chrome/SimpleStackHeader.tsx, apps/mobile/src/platform/chrome/nativeToolbarMenuItems.tsx, apps/mobile/src/platform/gestureHandler.tsx, apps/mobile/src/remote-desktop/FoldTouchpad.tsx, apps/mobile/src/remote-desktop/NativeRemoteDesktopView.tsx, apps/mobile/src/remote-desktop/PermissionGuide.tsx, apps/mobile/src/remote-desktop/PermissionGuideView.ios.tsx, apps/mobile/src/remote-desktop/PermissionGuideView.tsx, apps/mobile/src/remote-desktop/RemoteDesktopActionButton.ios.tsx, apps/mobile/src/remote-desktop/RemoteDesktopActionButton.tsx, apps/mobile/src/remote-desktop/RemoteDesktopBackButton.ios.tsx, apps/mobile/src/remote-desktop/RemoteDesktopBackButton.tsx, apps/mobile/src/remote-desktop/RemoteDesktopChrome.ios.tsx, apps/mobile/src/remote-desktop/RemoteDesktopChrome.tsx, apps/mobile/src/remote-desktop/RemoteDesktopClipboardButton.tsx, apps/mobile/src/remote-desktop/RemoteDesktopControls.tsx, apps/mobile/src/remote-desktop/RemoteDesktopDisplaySettings.tsx, apps/mobile/src/remote-desktop/RemoteDesktopHost.tsx, apps/mobile/src/remote-desktop/RemoteDesktopIcons.tsx, apps/mobile/src/remote-desktop/RemoteDesktopMouseControls.ios.tsx, apps/mobile/src/remote-desktop/RemoteDesktopMouseControls.tsx, apps/mobile/src/remote-desktop/RemoteDesktopNetworkStatus.tsx, apps/mobile/src/remote-desktop/RemoteDesktopPanelButton.ios.tsx, apps/mobile/src/remote-desktop/RemoteDesktopPanelButton.tsx, apps/mobile/src/remote-desktop/RemoteDesktopScreen.tsx, apps/mobile/src/remote-desktop/RemoteDesktopSecuritySettings.tsx, apps/mobile/src/remote-desktop/RemoteDesktopWindows.tsx, apps/mobile/src/remote-desktop/viewerHtml.ts, apps/mobile/src/session/BlurBackdrop.tsx, apps/mobile/src/session/HomeEntryProvider.tsx, apps/mobile/src/session/HomeHeaderGlassButton.ios.tsx, apps/mobile/src/session/HomeHeaderGlassButton.tsx, apps/mobile/src/session/IncomingShareBridge.tsx, apps/mobile/src/session/McpAppViews.tsx, apps/mobile/src/session/MobileOutboxBridge.tsx, apps/mobile/src/session/NativeBottomSheet.android.tsx, apps/mobile/src/session/NativeBottomSheet.tsx, apps/mobile/src/session/NativeMcpAppSurface.tsx, apps/mobile/src/session/NativeResidentHistory.tsx, apps/mobile/src/session/RecentMessageHistories.tsx, apps/mobile/src/session/RemoteHistoryPrefetchBridge.tsx, apps/mobile/src/session/ResidentHomeList.tsx, apps/mobile/src/session/SheetModal.tsx, apps/mobile/src/theme/ThemeProvider.tsx, apps/mobile/src/theme/navigationTheme.ts, apps/mobile/src/theme/tokens.ts, apps/mobile/src/update/AndroidUpdateSheet.tsx | 0 | 218 | 59 |
diff --git a/packages/file-browser-core/package.json b/packages/file-browser-core/package.json
index b474466525..7714a7c763 100644
--- a/packages/file-browser-core/package.json
+++ b/packages/file-browser-core/package.json
@@ -8,7 +8,8 @@
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts",
- "./textFileExts": "./src/textFileExts.ts"
+ "./textFileExts": "./src/textFileExts.ts",
+ "./ignoreNames": "./src/ignoreNames.ts"
},
"scripts": {
"build": "tsc --noEmit",
diff --git a/packages/file-browser-core/src/__tests__/ignore.test.ts b/packages/file-browser-core/src/__tests__/ignore.test.ts
index 2098c7b6f7..d66efddc9e 100644
--- a/packages/file-browser-core/src/__tests__/ignore.test.ts
+++ b/packages/file-browser-core/src/__tests__/ignore.test.ts
@@ -12,7 +12,7 @@ import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { __clearCacheForTesting, loadIgnoreMatcher } from '../ignore';
+import { __clearCacheForTesting, createEventIgnoreMatcher, loadIgnoreMatcher } from '../ignore';
async function makeWorkdir(gitignore?: string): Promise<string> {
const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'ignore-test-'));
@@ -132,3 +132,112 @@ describe('loadIgnoreMatcher cache + inflight', () => {
}
});
});
+
+describe('loadIgnoreMatcher 内置忽略分层 (showIgnoredDirs)', () => {
+ let workdir: string;
+
+ beforeEach(async () => {
+ __clearCacheForTesting();
+ workdir = await makeWorkdir();
+ });
+
+ afterEach(async () => {
+ await fs.rm(workdir, { recursive: true, force: true }).catch(() => {});
+ });
+
+ it('默认隐藏依赖 / 构建产物 / 缓存目录', async () => {
+ const matcher = await loadIgnoreMatcher(workdir, { honorVcsIgnore: false });
+ for (const dir of ['build', 'dist', 'out', 'bin', 'obj', 'target', 'vendor', 'Temp', 'Logs']) {
+ expect(matcher.ignores(`${dir}/`, true), dir).toBe(true);
+ }
+ });
+
+ it('showIgnoredDirs 放行依赖 / 构建产物 / 缓存目录', async () => {
+ const matcher = await loadIgnoreMatcher(workdir, {
+ honorVcsIgnore: false,
+ showIgnoredDirs: true,
+ });
+ for (const dir of ['build', 'dist', 'out', 'bin', 'obj', 'target', 'vendor', 'Temp']) {
+ expect(matcher.ignores(`${dir}/`, true), dir).toBe(false);
+ }
+ expect(matcher.ignores('node_modules/', true)).toBe(false);
+ expect(matcher.ignores('Library/', true)).toBe(false);
+ });
+
+ it('VCS 元数据 / OS 垃圾不受开关影响', async () => {
+ const matcher = await loadIgnoreMatcher(workdir, {
+ honorVcsIgnore: false,
+ showIgnoredDirs: true,
+ });
+ expect(matcher.ignores('.git/', true)).toBe(true);
+ expect(matcher.ignores('.git/config', false)).toBe(true);
+ expect(matcher.ignores('.DS_Store', false)).toBe(true);
+ });
+
+ it('*.meta 仍只由 hideMetaFiles 决定,与开关正交', async () => {
+ const revealKeepMeta = await loadIgnoreMatcher(workdir, {
+ honorVcsIgnore: false,
+ hideMetaFiles: false,
+ showIgnoredDirs: true,
+ });
+ expect(revealKeepMeta.ignores('Foo.cs.meta', false)).toBe(false);
+
+ const revealHideMeta = await loadIgnoreMatcher(workdir, {
+ honorVcsIgnore: false,
+ hideMetaFiles: true,
+ showIgnoredDirs: true,
+ });
+ expect(revealHideMeta.ignores('Foo.cs.meta', false)).toBe(true);
+ });
+
+ it('两个开关值分别缓存(互不污染)', async () => {
+ const off = await loadIgnoreMatcher(workdir, { honorVcsIgnore: false });
+ const on = await loadIgnoreMatcher(workdir, { honorVcsIgnore: false, showIgnoredDirs: true });
+ expect(on).not.toBe(off);
+ // 再次取用各自命中自己的缓存条目。
+ expect(await loadIgnoreMatcher(workdir, { honorVcsIgnore: false })).toBe(off);
+ expect(
+ await loadIgnoreMatcher(workdir, { honorVcsIgnore: false, showIgnoredDirs: true }),
+ ).toBe(on);
+ });
+});
+
+/**
+ * 事件侧的恒真层。这一层和 listDir 的口径必须**故意不同**:开关打开后
+ * node_modules / Library 可以列出来,但内部改动永远不推事件(daemon
+ * WorkdirWatchManager 靠它挡住 SSH 上的事件洪水)。
+ */
+describe('createEventIgnoreMatcher(事件侧恒真层)', () => {
+ it('不论开关如何都挡掉依赖 / Unity 资源缓存,包含其后代与嵌套同名目录', () => {
+ const matcher = createEventIgnoreMatcher();
+ // 目录本身、目录内文件、任意深度的同名目录都算 —— 与
+ // BUILTIN_IGNORE_* 的「路径任意位置命中」口径一致。
+ for (const rel of [
+ 'node_modules/',
+ 'node_modules/react/index.js',
+ 'packages/app/node_modules/react/index.js',
+ 'Library/',
+ 'Library/ScriptAssemblies/Assembly-CSharp.dll',
+ 'Assets/Library/foo.prefab',
+ ]) {
+ expect(matcher.ignores(rel, rel.endsWith('/')), rel).toBe(true);
+ }
+ });
+
+ it('不误伤开关要放行的构建产物与普通目录', () => {
+ const matcher = createEventIgnoreMatcher();
+ // build / dist / Temp 这类目录**不在**这一层:开关打开时它们的改动要推事件。
+ for (const rel of ['build/app.js', 'dist/index.html', 'Temp/x', 'src/index.ts']) {
+ expect(matcher.ignores(rel, false), rel).toBe(false);
+ }
+ // 名字相近但不同名的不算(子串不算命中)。
+ expect(matcher.ignores('myLibrary/a', false)).toBe(false);
+ expect(matcher.ignores('node_modules_backup/a', false)).toBe(false);
+ });
+
+ it('VCS 元数据与 OS 垃圾也挡', () => {
+ const matcher = createEventIgnoreMatcher();
+ expect(matcher.ignores('.git/config', false)).toBe(true);
+ expect(matcher.ignores('.DS_Store', false)).toBe(true);
+ });
+});
diff --git a/packages/file-browser-core/src/__tests__/listAllFilesWalk.test.ts b/packages/file-browser-core/src/__tests__/listAllFilesWalk.test.ts
index 0621d2d03a..5615097c3b 100644
--- a/packages/file-browser-core/src/__tests__/listAllFilesWalk.test.ts
+++ b/packages/file-browser-core/src/__tests__/listAllFilesWalk.test.ts
@@ -10,7 +10,7 @@ import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { listAllFilesWalk } from '../listAllFiles.js';
-import { __clearCacheForTesting } from '../ignore.js';
+import { __clearCacheForTesting, loadIgnoreMatcher } from '../ignore.js';
describe('listAllFilesWalk', () => {
let workdir: string;
@@ -61,4 +61,28 @@ describe('listAllFilesWalk', () => {
expect(res.truncated).toBe(false);
expect(res.files.some((f) => f.includes('loop'))).toBe(false);
});
+
+ /**
+ * 决策测试(不是遗漏):文件名筛选**不跟随**文件树的「显示被忽略的目录」开关。
+ * 同一份工作区里两侧故意给出不同答案:文件树(loadIgnoreMatcher)在开关打开后
+ * 放行 build/,而筛选清单仍然不含它。
+ *
+ * 为什么不能只改 fallback:rg 后端无法"只放行构建产物"而保留用户自己的
+ * .gitignore 规则,单边跟随会让筛选结果随「机器上装没装 rg」而变(更细的理据
+ * 见 listAllFiles.ts 的 fallback 注释)。要改这条语义必须两个后端一起改,这条
+ * 测试就是那道闸。
+ */
+ it('不跟随「显示被忽略的目录」:树放行 build/,筛选清单仍然不含它', async () => {
+ await mkdir(path.join(workdir, 'build'));
+ await writeFile(path.join(workdir, 'build', 'bundle.js'), 'x\n', 'utf8');
+
+ const treeMatcher = await loadIgnoreMatcher(workdir, {
+ honorVcsIgnore: false,
+ showIgnoredDirs: true,
+ });
+ expect(treeMatcher.ignores('build/', true)).toBe(false); // 树:看得见
+
+ const res = await listAllFilesWalk({ workdir });
+ expect(res.files.some((f) => f.startsWith('build/'))).toBe(false); // 筛选:找不到
+ });
});
diff --git a/packages/file-browser-core/src/__tests__/scanner.test.ts b/packages/file-browser-core/src/__tests__/scanner.test.ts
index 58dd2b8cd1..57288fecf2 100644
--- a/packages/file-browser-core/src/__tests__/scanner.test.ts
+++ b/packages/file-browser-core/src/__tests__/scanner.test.ts
@@ -304,3 +304,37 @@ describe('readFile binary detection', () => {
}
});
});
+
+describe('file-browser scanner builtin ignore tiers', () => {
+ /**
+ * 回归:用户在文件树里右键新建 `build` 这类目录后看不到它、且刷新无效
+ * (2026-09 用户报告)。根因是 BUILTIN_IGNORE 无差别隐藏构建产物目录。
+ * 现在内置清单分两层,`showIgnoredDirs` 放行可放开的那一层。
+ */
+ it('hides a freshly created build/ dir by default, shows it with showIgnoredDirs', async () => {
+ const { loadIgnoreMatcher, listDir, __clearCacheForTesting } = await import('../index');
+ __clearCacheForTesting();
+ const workdir = await mkdtemp(path.join(os.tmpdir(), 'fb-builtin-'));
+ try {
+ await createFolder(workdir, 'build');
+ await createFolder(workdir, 'src');
+
+ const hiddenMatcher = await loadIgnoreMatcher(workdir, {
+ hideMetaFiles: true,
+ honorVcsIgnore: false,
+ });
+ const hidden = await listDir(workdir, '', hiddenMatcher, { docMode: false });
+ expect(hidden.map((e) => e.name)).toEqual(['src']);
+
+ const revealMatcher = await loadIgnoreMatcher(workdir, {
+ hideMetaFiles: true,
+ honorVcsIgnore: false,
+ showIgnoredDirs: true,
+ });
+ const revealed = await listDir(workdir, '', revealMatcher, { docMode: false });
+ expect(revealed.map((e) => e.name)).toEqual(['build', 'src']);
+ } finally {
+ await rm(workdir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/file-browser-core/src/ignore.ts b/packages/file-browser-core/src/ignore.ts
index eee3e5371c..d56518ea15 100644
--- a/packages/file-browser-core/src/ignore.ts
+++ b/packages/file-browser-core/src/ignore.ts
@@ -27,54 +27,20 @@ import path from 'node:path';
import ignoreLib from 'ignore';
import { scopedLogger } from './logging.js';
+import {
+ BUILTIN_IGNORE_ALWAYS,
+ BUILTIN_IGNORE_REVEALABLE,
+ WATCH_ALWAYS_IGNORE,
+} from './ignoreNames.js';
+
+// 名单真源在 ignoreNames.ts(desktop renderer 也消费同一份);这里 re-export
+// 保持既有 API —— 包内与 daemon 都直接取 WATCH_ALWAYS_IGNORE。
+export { WATCH_ALWAYS_IGNORE } from './ignoreNames.js';
const log = scopedLogger('file-browser/ignore');
-/**
- * Folder names (last path segment) that should never be walked into,
- * regardless of vcs ignore files. Patterns are folder-name-only (no globs)
- * because `ignore` lib treats them as "match anywhere in the path".
- */
-const BUILTIN_IGNORE = [
- // VCS
- '.git/',
- '.svn/',
- '.hg/',
- // Package managers
- 'node_modules/',
- '__pycache__/',
- 'vendor/',
- '.venv/',
- '.cache/',
- // Editor / IDE caches
- '.vs/',
- '.idea/',
- '.vscode-test/',
- // OS junk
- '.DS_Store',
- 'Thumbs.db',
- // Generic build outputs
- 'dist/',
- 'build/',
- 'out/',
- '.next/',
- 'target/',
- 'bin/',
- 'obj/',
- // Unity-specific (huge caches; .gitignore usually has them but be defensive)
- 'Library/',
- 'Temp/',
- 'Logs/',
- 'UserSettings/',
- // Project-internal generated dirs (seen on real Unity workdirs)
- 'AssetDepotOutput/',
- 'ChuangXiangEditorCache/',
- // .meta files (Unity per-asset metadata) — rendered behind a "show meta"
- // user toggle; defaulting to hidden cuts ~47% of typical Unity entries.
- // Toggle is honored by Matcher.shouldShowMeta below.
- // Note: NOT added to BUILTIN_IGNORE here — handled separately because it's
- // user-toggleable per session.
-];
+// 名单定义已搬到 ignoreNames.ts(desktop renderer 也消费同一份);本文件只留
+// matcher 逻辑。
export interface Matcher {
/**
@@ -86,6 +52,32 @@ export interface Matcher {
ignores(relPath: string, isDir: boolean): boolean;
}
+/**
+ * 事件侧的恒真过滤层:只吃 BUILTIN_IGNORE_ALWAYS + WATCH_ALWAYS_IGNORE,不读
+ * `.gitignore`、不随 showIgnoredDirs 变化。
+ *
+ * 用途:daemon 的 watcher 需要在「开关打开后仍然不推事件」的方向上兜底 —— 它
+ * 没有 desktop 侧的 parcel 预过滤层可用,`fs.watch recursive` 照样把这些目录的
+ * 事件推上来,只能自己丢。
+ *
+ * 目录模式(`Library/`)对 `ignore` 库是「匹配该名字的目录及其全部后代」,且与
+ * BUILTIN_IGNORE_* 一样是「路径任意位置命中」,所以 `Assets/Library/x` 也算了
+ * (`src/node_modules/a.js` 同理) —— 与文件树的隐藏口径保持一致。
+ *
+ * 无 workdir 依赖(不读盘),可以当成常量用。
+ */
+export function createEventIgnoreMatcher(): Matcher {
+ const ig = ignoreLib();
+ ig.add(BUILTIN_IGNORE_ALWAYS);
+ ig.add(WATCH_ALWAYS_IGNORE.map((name) => `${name}/`));
+ return {
+ ignores(relPath: string, isDir: boolean): boolean {
+ const normalized = isDir && !relPath.endsWith('/') ? `${relPath}/` : relPath;
+ return ig.ignores(normalized);
+ },
+ };
+}
+
const VCS_IGNORE_DISABLED_SOURCE = '__vcs-disabled';
interface CacheEntry {
@@ -99,8 +91,13 @@ interface CacheEntry {
const cache = new Map<string, CacheEntry>();
const inflight = new Map<string, Promise<Matcher>>();
-function cacheKey(workdir: string, hideMetaFiles: boolean, honorVcsIgnore: boolean): string {
- return `${workdir} ${hideMetaFiles ? '1' : '0'} ${honorVcsIgnore ? 'vcs' : 'tree'}`;
+function cacheKey(
+ workdir: string,
+ hideMetaFiles: boolean,
+ honorVcsIgnore: boolean,
+ showIgnoredDirs: boolean,
+): string {
+ return `${workdir} ${hideMetaFiles ? '1' : '0'} ${honorVcsIgnore ? 'vcs' : 'tree'}${showIgnoredDirs ? ' reveal' : ''}`;
}
/**
@@ -119,11 +116,22 @@ function cacheKey(workdir: string, hideMetaFiles: boolean, honorVcsIgnore: boole
*/
export async function loadIgnoreMatcher(
workdir: string,
- opts: { hideMetaFiles?: boolean; honorVcsIgnore?: boolean } = {},
+ opts: {
+ hideMetaFiles?: boolean;
+ honorVcsIgnore?: boolean;
+ /**
+ * 用户开关「显示被忽略的目录」:true 时放行 BUILTIN_IGNORE_REVEALABLE
+ * (依赖 / 构建产物 / 缓存 / IDE 缓存)。默认 false = 保持历史行为。
+ * 只影响内置清单,VCS 元数据与 OS 垃圾永远隐藏,`*.meta` 仍由
+ * hideMetaFiles 单独决定。
+ */
+ showIgnoredDirs?: boolean;
+ } = {},
): Promise<Matcher> {
const hideMetaFiles = opts.hideMetaFiles ?? true;
const honorVcsIgnore = opts.honorVcsIgnore ?? true;
- const key = cacheKey(workdir, hideMetaFiles, honorVcsIgnore);
+ const showIgnoredDirs = opts.showIgnoredDirs ?? false;
+ const key = cacheKey(workdir, hideMetaFiles, honorVcsIgnore, showIgnoredDirs);
const pending = inflight.get(key);
if (pending) return pending;
@@ -133,7 +141,7 @@ export async function loadIgnoreMatcher(
if (cached && (await isCacheFresh(workdir, cached))) {
return cached.matcher;
}
- const built = await buildMatcher(workdir, hideMetaFiles, honorVcsIgnore);
+ const built = await buildMatcher(workdir, hideMetaFiles, honorVcsIgnore, showIgnoredDirs);
cache.set(key, built);
return built.matcher;
})();
@@ -181,9 +189,11 @@ async function buildMatcher(
workdir: string,
hideMetaFiles: boolean,
honorVcsIgnore: boolean,
+ showIgnoredDirs: boolean,
): Promise<CacheEntry> {
const ig = ignoreLib();
- ig.add(BUILTIN_IGNORE);
+ ig.add(BUILTIN_IGNORE_ALWAYS);
+ if (!showIgnoredDirs) ig.add(BUILTIN_IGNORE_REVEALABLE);
let sourceName: string | null = honorVcsIgnore ? null : VCS_IGNORE_DISABLED_SOURCE;
let sourceMtimeMs = 0;
diff --git a/packages/file-browser-core/src/ignoreNames.ts b/packages/file-browser-core/src/ignoreNames.ts
new file mode 100644
index 0000000000..c3aad862db
--- /dev/null
+++ b/packages/file-browser-core/src/ignoreNames.ts
@@ -0,0 +1,104 @@
+/**
+ * ignoreNames — 忽略名单的**纯数据**面(VCS/OS 垃圾 + 依赖/构建产物/缓存)。
+ *
+ * 拆出来只有一个原因:desktop renderer 也要用同一份名单。切「显示被忽略的
+ * 目录」开关时,renderer 要立刻把 reveal 态根列表里「隐藏态会被忽略」的一级
+ * 目录滤掉 —— 否则关开关后这些行要等新 matcher 的数据回来才消失,慢通道
+ * (SSH / device-link)下会有数秒「开关关了却还看得见」的窗口。
+ *
+ * 因此本文件必须保持零依赖:不 import 任何东西、不碰 fs。它经
+ * `@cindy/file-browser-core/ignoreNames` 子路径导出给 renderer,而包根入口
+ * (index.ts)会把 node:fs 拖进浏览器 bundle(同类说明见 desktop 的
+ * shared/textFileExts.ts)。名单只此一份:ignore.ts 的两宿主 matcher 从这里
+ * import。
+ *
+ * ⚠️ 改名单要同时想清楚三处消费:
+ * 1. loadIgnoreMatcher —— 两宿主列目录的过滤口径;
+ * 2. createEventIgnoreMatcher —— daemon 事件侧的恒真层;
+ * 3. desktop renderer 切开关的首帧过滤 —— 只认这里的一级目录名。
+ * 第 3 处只覆盖内置名单:`.gitignore` / `.p4ignore` 里的自定义条目拿不到
+ * (renderer 不读盘),要等新 matcher 的数据回来才生效 —— 不为它加一条 IPC。
+ */
+
+/**
+ * Folder names (last path segment) that should never be walked into,
+ * regardless of vcs ignore files. Patterns are folder-name-only (no globs)
+ * because `ignore` lib treats them as "match anywhere in the path".
+ *
+ * 分两层,因为「用户看得见的工程目录」和「纯噪音」不是一回事:
+ * - ALWAYS:VCS 元数据与 OS 垃圾 —— 任何设置下都不列、不递归。
+ * - REVEALABLE:依赖 / 构建产物 / 缓存 / IDE 缓存 —— 默认隐藏(Unity 的
+ * Library 之类目录动辄数十万条,默认列出会让文件树不可用),但用户可在
+ * 设置里开「显示被忽略的目录」放行。
+ */
+export const BUILTIN_IGNORE_ALWAYS = [
+ // VCS metadata: never part of the project's own file tree.
+ '.git/',
+ '.svn/',
+ '.hg/',
+ // OS junk
+ '.DS_Store',
+ 'Thumbs.db',
+];
+
+export const BUILTIN_IGNORE_REVEALABLE = [
+ // Package managers
+ 'node_modules/',
+ '__pycache__/',
+ 'vendor/',
+ '.venv/',
+ '.cache/',
+ // Editor / IDE caches
+ '.vs/',
+ '.idea/',
+ '.vscode-test/',
+ // Generic build outputs
+ 'dist/',
+ 'build/',
+ 'out/',
+ '.next/',
+ 'target/',
+ 'bin/',
+ 'obj/',
+ // Unity-specific (huge caches; .gitignore usually has them but be defensive)
+ 'Library/',
+ 'Temp/',
+ 'Logs/',
+ 'UserSettings/',
+ // Project-internal generated dirs (seen on real Unity workdirs)
+ 'AssetDepotOutput/',
+ 'ChuangXiangEditorCache/',
+ // .meta files (Unity per-asset metadata) — rendered behind a "show meta"
+ // user toggle; defaulting to hidden cuts ~47% of typical Unity entries.
+ // Toggle is honored by Matcher.shouldShowMeta below.
+ // Note: NOT added here — handled separately because it's user-toggleable
+ // per session via `hideMetaFiles`.
+];
+
+/**
+ * 「可以列出、但不实时 watch」的目录名 —— 与 BUILTIN_IGNORE_REVEALABLE 正交的
+ * 一层:即使开了「显示被忽略的目录」(它们会出现在文件树里),事件侧也要丢掉
+ * 它们内部的改动。
+ *
+ * 理由:node_modules 动辄数十万条目,Unity 的 Library 需要真正的资源依赖分析
+ * ——原生递归 watch 的代价与收益不成比例,手动刷新已够用。两个宿主的**事件**
+ * 过滤都必须吃这份清单(desktop 的 parcel 预过滤 + daemon 的事件过滤),但
+ * **列目录不看它**(listDir 只问 BUILTIN_IGNORE_*)。
+ */
+export const WATCH_ALWAYS_IGNORE = ['node_modules', 'Library'] as const;
+
+/**
+ * `BUILTIN_IGNORE_REVEALABLE` 的目录名集合(去掉名单里的尾斜杠)。用于判断某个
+ * relPath 是否落在「只有 reveal 态才可见」的目录内部 —— 事件侧按可见性分流时需要
+ * 它(见 desktop `device-op.ts` 的 device-link 转发)。
+ *
+ * 与 `WATCH_ALWAYS_IGNORE` 的分工:后者是「永远不 watch 内部」的一层(daemon 不会
+ * 发它们的事件);本集合是「隐藏态不可见、reveal 态可见」的一层 —— daemon 在并集
+ * matcher 下会发它们的事件,订阅方要自己按自己的可见性滤。
+ *
+ * 成员统一小写:`ignore` 包默认 `ignorecase=true`(大小写不敏感卷上 `DIST` 与
+ * `dist` 是同一个目录),消费方比较路径段前必须折叠大小写。
+ */
+export const REVEALABLE_IGNORE_DIR_NAMES: ReadonlySet<string> = new Set(
+ BUILTIN_IGNORE_REVEALABLE.map((name) => name.replace(/\/$/, '').toLowerCase()),
+);
diff --git a/packages/file-browser-core/src/index.ts b/packages/file-browser-core/src/index.ts
index ad3f43d59e..52e7d2a5f4 100644
--- a/packages/file-browser-core/src/index.ts
+++ b/packages/file-browser-core/src/index.ts
@@ -40,6 +40,8 @@ export {
export {
loadIgnoreMatcher,
+ createEventIgnoreMatcher,
+ WATCH_ALWAYS_IGNORE,
__clearCacheForTesting,
type Matcher,
} from './ignore.js';
diff --git a/packages/file-browser-core/src/listAllFiles.ts b/packages/file-browser-core/src/listAllFiles.ts
index 35c39606e8..71595c505c 100644
--- a/packages/file-browser-core/src/listAllFiles.ts
+++ b/packages/file-browser-core/src/listAllFiles.ts
@@ -162,10 +162,20 @@ export interface ListAllFilesWalkArgs {
* 无 ripgrep 的纯 JS fallback:递归 readdir + 与文件树同一个 ignore matcher。
*
* 与 rg 版的语义差异(有意为之、确定可解释):过滤走 loadIgnoreMatcher(根
- * .gitignore / .p4ignore + BUILTIN_IGNORE),即**清单 = 用户在文件树里能看到的
- * 文件全集**;rg 版额外理解嵌套 .gitignore / .rgignore,并且不吃 BUILTIN_IGNORE。
- * 用途场景(远端裸机器没有 rg 时的文件名筛选)里"和树一致"比"和 rg 一致"更符合
- * 直觉。性能:纯 JS 串行遍历比 rg 慢一个量级,但被 cap 上限兜底,中型项目 <1s。
+ * .gitignore / .p4ignore + BUILTIN_IGNORE 的**默认层**,即
+ * BUILTIN_IGNORE_REVEALABLE 仍然隐藏);rg 版额外理解嵌套 .gitignore /
+ * .rgignore,也不吃 BUILTIN_IGNORE。用途场景(远端裸机器没有 rg 时的文件名
+ * 筛选)里"接近文件树默认口径"比"和 rg 一致"更符合直觉。性能:纯 JS 串行遍历比
+ * rg 慢一个量级,但被 cap 上限兜底,中型项目 <1s。
+ *
+ * 这里**不接**「显示被忽略的目录」(showIgnoredDirs):该开关只作用于**浏览面**
+ * (文件树),文件名筛选与内容搜索一直按 ignore 规则工作 —— rg 那一路吃
+ * .gitignore / .ignore / .rgignore,这条 fallback 吃根 .gitignore +
+ * BUILTIN_IGNORE 默认层。两条路都无法跟这个开关一致(rg 侧没有办法"只放行构建
+ * 产物"而保留用户自己的 gitignore 规则),而**只让 fallback 跟随**会让同一份筛选
+ * 在装没装 rg 的机器上给出不同结果 —— 那比"树里看得见、筛选找不到"更难解释。
+ * 所以开关打开后树里出现 build / dist、而这份清单不含它们,是有意的语义差异
+ * (决策测试见 listAllFilesWalk.test.ts);要改就得两个后端一起改。
*
* symlink:目录/文件符号链接一律跳过(rg --files 默认同样不 follow symlink,
* 也避免链接环)。不可读目录(权限/竞态删除)静默跳过,不 fail 整个清单。
diff --git a/packages/remote-file-service/src/__tests__/rpc.test.ts b/packages/remote-file-service/src/__tests__/rpc.test.ts
index 80037790ca..80d5ff6d32 100644
--- a/packages/remote-file-service/src/__tests__/rpc.test.ts
+++ b/packages/remote-file-service/src/__tests__/rpc.test.ts
@@ -83,15 +83,22 @@ describe('remote-file-service RPC end-to-end', () => {
expect(names).toContain('README.md');
// 文件树不吃 VCS ignore(honorVcsIgnore: false):真实存在的目录要可见。
expect(names).toContain('ignored-dir');
- // 内置大目录屏蔽不受开关影响。
+ // 内置大目录默认隐藏(hideMetaFiles 与 showIgnoredDirs 是两个独立开关,
+ // 后者默认关 = 保持历史行为)。
expect(names).not.toContain('node_modules');
expect(entries[0]?.type).toBe('directory');
});
+ it('listDir 带 showIgnoredDirs 时列出内置隐藏目录', async () => {
+ await client.connect();
+ const { entries } = await client.request('listDir', { workdir, showIgnoredDirs: true });
+ expect(entries.map((e) => e.name)).toContain('node_modules');
+ });
+
it('listDir can return complete entries over the same RPC', async () => {
await client.connect();
const { entries } = await client.request('listDir', { workdir, includeIgnored: true, docMode: true });
- expect(entries.map(e => e.name)).toEqual(expect.arrayContaining(['node_modules', '.gitignore', 'blob.bin']));
+ expect(entries.map((e) => e.name)).toEqual(expect.arrayContaining(['node_modules', '.gitignore', 'blob.bin']));
await expect(client.request('listDir', { workdir, includeIgnored: true, maxEntries: 1 })).rejects.toThrow('DIRECTORY_TOO_LARGE');
});
@@ -226,6 +233,7 @@ describe('remote-file-service RPC end-to-end', () => {
await client.request('watchStop', { workdir });
});
+
it('channel close rejects pending requests and marks client dead', async () => {
await client.connect();
toServer.end();
diff --git a/packages/remote-file-service/src/__tests__/watchOptions.test.ts b/packages/remote-file-service/src/__tests__/watchOptions.test.ts
new file mode 100644
index 0000000000..b3e0b3840c
--- /dev/null
+++ b/packages/remote-file-service/src/__tests__/watchOptions.test.ts
@@ -0,0 +1,592 @@
+/**
+ * watchOptions.test.ts — daemon 侧 WorkdirWatchManager 的过滤开关语义。
+ *
+ * 背景:文件树新增「显示被忽略的目录」开关(showIgnoredDirs)。远端 daemon 的
+ * watcher 在 watchStart 时就把 matcher 固定下来,所以:
+ * - 重复 watchStart 且开关未变 → 幂等,不重建原生 watcher;
+ * - 开关变了 → 必须重建 matcher(否则控制端改了开关、watch 仍按旧规则过滤,
+ * 目录能列出来但内部改动永远没有事件);
+ * - 启动窗口内到达的 stop + 带新选项的 start → 必须收敛到新选项,且不能
+ * 留下「没有 watcher」的空档(两个 RPC 都报 success 的静默失效);
+ * - node_modules / Library 内部改动永远不推事件(事件侧恒真层):fs.watch
+ * recursive 会把它们照单全推,daemon 侧没有 desktop 的 parcel 预过滤兜底。
+ *
+ * 这里用假 `watch` + 假 loadIgnoreMatcher 锁定这些语义,不依赖真实 fs 事件
+ * (真机 Windows / Node 24 的 recursive fs.watch 本身有原生断言崩溃,见
+ * rpc.test.ts 的 watchStart 用例)。事件侧恒真层用**真实现**(纯函数、不读盘),
+ * 只有真正要读盘的 loadIgnoreMatcher 被替换掉。
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+type FsWatchCallback = (eventType: string, filename: string | null) => void;
+
+interface FakeWatcher {
+ on: (event: string, cb: (err: Error | null, filename: string | null) => void) => void;
+ close: () => void;
+}
+
+const h = vi.hoisted(() => {
+ const created: Array<{
+ dir: string;
+ watcher: FakeWatcher;
+ closed: boolean;
+ cb: FsWatchCallback | null;
+ }> = [];
+ return {
+ created,
+ /** loadIgnoreMatcher 收到的选项(按调用顺序)。 */
+ matcherOpts: [] as Array<Record<string, unknown>>,
+ /** 非零时接下来 N 次 loadIgnoreMatcher 直接 reject(模拟挂载不可用)。 */
+ failNext: 0,
+ /** 门闩:非空时下一次 loadIgnoreMatcher 等它放行(模拟读盘未完成)。 */
+ gate: null as Promise<void> | null,
+ watchSpy: vi.fn((dir: string, _opts: unknown, cb: FsWatchCallback) => {
+ const watcher: FakeWatcher = { on: vi.fn(), close: vi.fn() };
+ const record = { dir, watcher, closed: false, cb };
+ (watcher.close as unknown as ReturnType<typeof vi.fn>).mockImplementation(() => {
+ record.closed = true;
+ });
+ created.push(record);
+ return watcher;
+ }),
+ };
+});
+
+vi.mock('node:fs', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('node:fs')>();
+ return { ...actual, watch: h.watchSpy };
+});
+
+vi.mock('@cindy/file-browser-core', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('@cindy/file-browser-core')>();
+ return {
+ // 恒真层 / 后缀常量用真实现:前者的匹配语义(目录模式含后代)正是被测目标。
+ createEventIgnoreMatcher: actual.createEventIgnoreMatcher,
+ WATCH_ALWAYS_IGNORE: actual.WATCH_ALWAYS_IGNORE,
+ XDT_TMP_SUFFIX: actual.XDT_TMP_SUFFIX,
+ scopedLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+ loadIgnoreMatcher: vi.fn(async (_workdir: string, opts: Record<string, unknown>) => {
+ h.matcherOpts.push(opts);
+ if (h.failNext > 0) {
+ h.failNext -= 1;
+ throw new Error('matcher load failed');
+ }
+ const gate = h.gate;
+ if (gate) {
+ h.gate = null;
+ await gate;
+ }
+ // 工作区 matcher 由测试单独控制(真实现要读盘)。
+ return { ignores: (rel: string) => rel.startsWith('hidden/') };
+ }),
+ };
+});
+
+import { WorkdirWatchManager } from '../watch';
+import type { RemoteFileTreeEvent } from '../watch';
+
+/** 触发一次原生事件,并等 coalesce 窗口(50ms)把批次吐出来。 */
+async function fireEvent(
+ record: (typeof h.created)[number],
+ eventType: string,
+ filename: string,
+): Promise<RemoteFileTreeEvent[]> {
+ record.cb?.(eventType, filename);
+ // 等生产代码真实的 coalesce 窗口(50ms)吐批次 —— 这是被测行为本身,
+ // 换 fake timers 会改掉 coalescing 的真实计时语义。
+ // real-wait: 等 coalesce 窗口真实计时器把批次吐出
+ await new Promise((resolve) => setTimeout(resolve, 120));
+ return emitted;
+}
+
+let emitted: RemoteFileTreeEvent[] = [];
+
+describe('WorkdirWatchManager 过滤开关', () => {
+ beforeEach(() => {
+ h.created.length = 0;
+ h.matcherOpts.length = 0;
+ h.failNext = 0;
+ h.gate = null;
+ h.watchSpy.mockClear();
+ emitted = [];
+ });
+
+ it('同 workdir 同选项重复 start 幂等,不重建原生 watcher', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { hideMetaFiles: true, showIgnoredDirs: false });
+ await manager.start('/repo', { hideMetaFiles: true, showIgnoredDirs: false });
+ expect(h.watchSpy).toHaveBeenCalledTimes(1);
+ expect(h.matcherOpts).toHaveLength(1);
+ expect(h.created[0].closed).toBe(false);
+ manager.stopAll();
+ });
+
+ it('showIgnoredDirs 变化触发重建:旧 watcher 关闭 + matcher 用新开关重建', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: false });
+ await manager.start('/repo', { showIgnoredDirs: true });
+
+ expect(h.created[0].closed).toBe(true);
+ expect(h.watchSpy).toHaveBeenCalledTimes(2);
+ expect(h.matcherOpts[0].showIgnoredDirs).toBe(false);
+ expect(h.matcherOpts[1].showIgnoredDirs).toBe(true);
+ manager.stopAll();
+ });
+
+ it('start 的过滤开关原样落到 matcher(hideMetaFiles 默认 true)', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', {});
+ expect(h.matcherOpts[0]).toMatchObject({ hideMetaFiles: true, showIgnoredDirs: false });
+ manager.stopAll();
+ });
+
+ /**
+ * 竞态回归(评审 P1):控制端切开关时 renderer 是「先 stop 再带新选项 start」。
+ * 若首个 watchStart 的 matcher 还在加载中,旧实现会复用那个 promise —— 新选项
+ * 被丢掉,而 stop 打的 stopDuringStart 标记又让那个 watcher 自拆,最终两边都
+ * 报 success 却**没有 watcher**。现在必须收敛到新选项。
+ */
+ it('启动窗口内 stop + 带新选项 start:收敛到新选项且留下活着的 watcher', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ let release = (): void => {};
+ h.gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+
+ const first = manager.start('/repo', { showIgnoredDirs: false });
+ // 启动未落地:此刻 stop(renderer 的 effect cleanup)再 start(新选项)。
+ const stopped = Promise.resolve(manager.stop('/repo'));
+ const second = manager.start('/repo', { showIgnoredDirs: true });
+
+ release();
+ await Promise.all([first, stopped, second]);
+
+ // 旧实现:只建 1 个且已关 → 覆盖「没有 watcher」。新实现:旧的自拆,新的活着。
+ expect(h.created).toHaveLength(2);
+ expect(h.created[0].closed).toBe(true);
+ expect(h.created[1].closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(true);
+
+ // 新 watcher 是活的:事件能按新 matcher 推出来。
+ const emittedEvents = await fireEvent(h.created[1], 'change', 'build/app.js');
+ expect(emittedEvents.some((e) => e.relPath === 'build/app.js')).toBe(true);
+ manager.stopAll();
+ });
+
+ it('启动窗口内 stop 后没有新 start:不留 watcher,也不复活', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ let release = (): void => {};
+ h.gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+
+ const first = manager.start('/repo', { showIgnoredDirs: true });
+ manager.stop('/repo');
+ release();
+ await first;
+
+ expect(h.created.every((c) => c.closed)).toBe(true);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P1:开关打开后 daemon 曾把 node_modules / Library 也放行给事件过滤,
+ * fs.watch recursive 会把装依赖 / Unity 导入的每个路径都推成 fileTree 帧过
+ * SSH。事件侧必须保留恒真层(与 desktop 的 PREFILTER_ALWAYS 同名单)。
+ */
+ it('开关打开也不推 node_modules / Library 的事件,但放行 build / dist', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ await manager.start('/repo', { showIgnoredDirs: true });
+ const record = h.created[0];
+
+ for (const rel of ['node_modules/react/index.js', 'Library/ScriptAssemblies/a.dll']) {
+ expect(await fireEvent(record, 'change', rel), rel).toHaveLength(0);
+ }
+ // 正对照:开关要放行的构建产物仍然推事件(否则这个开关在远端等于没生效)。
+ const buildEvents = await fireEvent(record, 'change', 'build/app.js');
+ expect(buildEvents.map((e) => e.relPath)).toEqual(['build/app.js']);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P2(PR #4398 轮五):恒真层的名字比较必须与 matcher 的大小写口径一致。
+ * `ignore` 包默认 `ignorecase=true`(`NODE_MODULES/` 会被恒真层匹配),而本地按
+ * 段比较若区分大小写,大小写变体目录在开关打开时可见、它**自身**的 rename /
+ * unlink 却被吞掉,行陈旧到手动刷新。
+ */
+ it('大小写变体的恒真目录:自身事件放行、内部事件仍然丢', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ await manager.start('/repo', { showIgnoredDirs: true });
+ const record = h.created[0];
+
+ // 目录自身(大小写变体)的事件必须推出去,否则树上的这一行会陈旧。
+ const own = await fireEvent(record, 'change', 'NODE_MODULES');
+ expect(own.map((e) => e.relPath)).toEqual(['NODE_MODULES']);
+
+ // 内部事件仍然被恒真层丢掉(不再增长)。
+ const afterInside = await fireEvent(record, 'change', 'NODE_MODULES/react/index.js');
+ expect(afterInside).toHaveLength(1);
+ expect(afterInside[0].relPath).toBe('NODE_MODULES');
+ manager.stopAll();
+ });
+
+ it('工作区 matcher 仍然生效(hidden/ 前缀被丢)', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ await manager.start('/repo', { showIgnoredDirs: true });
+ expect(await fireEvent(h.created[0], 'change', 'hidden/x.ts')).toHaveLength(0);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P2:同一 workdir 会被两个消费方同时订阅 —— desktop 文件树(可开着
+ * 「显示被忽略的目录」)与 device-link 控制端(默认隐藏)。watcher 只能有一份
+ * matcher,必须取可见性并集;后到的隐藏态请求不能把先到的 reveal 覆盖掉,
+ * 否则 desktop 仍列着 build / dist,却再也收不到它们的事件。
+ */
+ it('多消费者取可见性并集:后到的隐藏态需求不覆盖先到的 reveal', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ await manager.start('/repo', { hideMetaFiles: true }, 'device-link');
+
+ // 并集仍是 reveal:不重建原生 watcher。
+ expect(h.created).toHaveLength(1);
+ expect(h.created[0].closed).toBe(false);
+ expect(h.matcherOpts).toHaveLength(1);
+ expect(h.matcherOpts[0]).toMatchObject({ showIgnoredDirs: true });
+ manager.stopAll();
+ });
+
+ it('部分消费者 stop:按剩余并集收敛,收窄为隐藏且 watcher 仍在', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ await manager.start('/repo', { showIgnoredDirs: false }, 'device-link');
+ expect(h.created).toHaveLength(1);
+
+ manager.stop('/repo', 'desktop-tree');
+ await new Promise((resolve) => setTimeout(resolve, 0)); // 等异步 reconcile
+
+ expect(h.created).toHaveLength(2);
+ expect(h.created[0].closed).toBe(true);
+ expect(h.created[1].closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P2(PR #4398 轮六):并集变化触发 watcher 重建时,旧 entry 的 `pending`
+ * 不能随 entry 一起丢 —— 已入队(尚未过 50ms 合并窗口)的事件仍要转发给还在线的
+ * 消费者,否则文件树陈旧到同目录下一次事件或手动刷新。
+ */
+ it('重建 watcher 前先转发 pending 事件:并集收窄不丢已入队事件', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ await manager.start('/repo', { showIgnoredDirs: false }, 'device-link');
+ expect(h.created).toHaveLength(1);
+
+ // 可见文件的 change 事件进入 50ms 合并窗口(还没到 flush)。
+ h.created[0].cb?.('change', 'src/app.ts');
+ expect(emitted).toHaveLength(0);
+
+ // desktop 消费者在窗口内停止 → 并集收窄 → 重建 watcher。
+ manager.stop('/repo', 'desktop-tree');
+
+ // pending 必须先转发给仍在线的 device-link 客户端,而不是随旧 entry 丢弃。
+ expect(emitted.map((e) => e.relPath)).toEqual(['src/app.ts']);
+
+ await new Promise((resolve) => setTimeout(resolve, 0)); // 等异步 reconcile
+ expect(h.created).toHaveLength(2);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ manager.stopAll();
+ });
+
+ it('最后一个消费者 stop 才拆 watcher', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ await manager.start('/repo', { showIgnoredDirs: true }, 'device-link');
+
+ manager.stop('/repo', 'desktop-tree');
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(h.created.every((c) => c.closed)).toBe(false); // 并集没变:watcher 留着
+
+ manager.stop('/repo', 'device-link');
+ expect(h.created.every((c) => c.closed)).toBe(true);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P1:`ignore` 的目录模式(`node_modules/`)同时匹配目录自身与全部后代,
+ * 而事件过滤要的只是后代 —— 开关打开时 node_modules / Library 这一行就在树里,
+ * 它自己被建 / 删 / 改名必须推给父目录 refetch,否则树陈旧到手动刷新。
+ */
+ it('开关打开时恒真忽略目录自身的事件仍推,只丢其后代', async () => {
+ const manager = new WorkdirWatchManager((event) => emitted.push(event));
+ await manager.start('/repo', { showIgnoredDirs: true });
+ const record = h.created[0];
+
+ // 目录自身的生命周期事件:推(类型由 lstat 映射出 add/unlink,这里只看 relPath)。
+ await fireEvent(record, 'rename', 'node_modules');
+ expect(emitted.map((e) => e.relPath)).toEqual(['node_modules']);
+
+ // 后代仍然静默:npm install / Unity 导入不会打爆通道。
+ const before = emitted.length;
+ for (const rel of ['node_modules/react/index.js', 'foo/node_modules/a.js', 'foo/Library/x.dll']) {
+ await fireEvent(record, 'change', rel);
+ }
+ expect(emitted.length).toBe(before);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P1:错误处理曾调 `stop(workdir)`(默认 consumerId)—— 删错人,且
+ * reconcile 看到同一个坏 entry 选项没变而原地返回,直播静默冻结到手动改开关
+ * 或 daemon 重启。现在按剩余消费者并集拆掉重建成新的活 watcher。
+ */
+ it('watcher 出错时保留消费者意图并重建,不静默冻结', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ expect(h.created).toHaveLength(1);
+
+ const onSpy = h.created[0].watcher.on as unknown as ReturnType<typeof vi.fn>;
+ const handler = onSpy.mock.calls.find(([evt]) => evt === 'error')?.[1] as (err: Error) => void;
+ handler(new Error('boom'));
+ await new Promise((resolve) => setTimeout(resolve, 0));
+
+ expect(h.created).toHaveLength(2);
+ expect(h.created[0].closed).toBe(true);
+ expect(h.created[1].closed).toBe(false);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P2:watcher 报错后紧接着的 reconcile 又失败时不能只记日志 —— 消费者
+ * 意图还在 desired,但没有 watcher、也没有定时器再收敛,SSH 连接没断的情况下
+ * 事件会永久停止。要有带退避与上限的重试(退避避免持续失败时紧密重建循环)。
+ */
+ it('watcher 出错后收敛失败:退避重试直到恢复', async () => {
+ vi.useFakeTimers();
+ try {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ expect(h.created).toHaveLength(1);
+
+ // 触发 error(拆掉 entry → 立即 reconcile),并让这次 reconcile 失败。
+ let failWith = (_err: Error): void => {};
+ h.gate = new Promise<void>((_resolve, reject) => {
+ failWith = reject;
+ });
+ const onSpy = h.created[0].watcher.on as unknown as ReturnType<typeof vi.fn>;
+ const handler = onSpy.mock.calls.find(([evt]) => evt === 'error')?.[1] as (err: Error) => void;
+ handler(new Error('boom'));
+ failWith(new Error('reconcile failed'));
+ await vi.advanceTimersByTimeAsync(0);
+
+ // 退避(500ms)后重试成功:重新建出活着的 watcher。
+ await vi.advanceTimersByTimeAsync(600);
+ expect(h.created.length).toBeGreaterThanOrEqual(2);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ manager.stopAll();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ /**
+ * 评审 P1(PR #4398):退避到顶(约 15.5s)后不能永久放弃 —— 挂载 / 权限故障
+ * 持续超过退避窗口时旧实现删掉重试状态,故障恢复后再没有定时器收敛;SSH 连接
+ * 没断的情况下文件事件永久静默,只有重挂面板 / 改开关才能救。
+ */
+ it('持续失败超过退避窗口后仍会继续重建(不永久停摆)', async () => {
+ vi.useFakeTimers();
+ try {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ expect(h.created).toHaveLength(1);
+
+ // watcher 报错触发重建,并让之后所有 reconcile 都失败(挂载持续不可用)。
+ h.failNext = Number.MAX_SAFE_INTEGER;
+ const onSpy = h.created[0].watcher.on as unknown as ReturnType<typeof vi.fn>;
+ const handler = onSpy.mock.calls.find(([evt]) => evt === 'error')?.[1] as (err: Error) => void;
+ handler(new Error('boom'));
+
+ // 跑过退避窗口(500+1000+2000+4000+8000 ≈ 15.5s)并再等几轮。
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(h.created.at(-1)?.closed).toBe(true); // 一直在失败,尚未建回
+
+ // 故障恢复:下一次封顶退避(8s)内的重试必须把 watcher 建回来。
+ h.failNext = 0;
+ await vi.advanceTimersByTimeAsync(9_000);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ manager.stopAll();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ /**
+ * 评审 P1:回滚后的恢复也失败时同样要退避重试 —— 只记日志的话,原有消费者会在
+ * 「选项变化 → 拆旧 watcher → 重建失败 → 回滚恢复意图」之后既没有 watcher、也没
+ * 有定时器再收敛。
+ */
+ it('回滚后的恢复失败:退避重试直到恢复', async () => {
+ vi.useFakeTimers();
+ try {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', {}, 'desktop-tree'); // 已生效的隐藏态 watcher
+ expect(h.created).toHaveLength(1);
+
+ // 改选项(并集变化 → 拆旧重建)失败,且回滚后的恢复也失败。
+ h.failNext = 2;
+ await expect(
+ manager.start('/repo', { showIgnoredDirs: true }, 'device-link'),
+ ).rejects.toThrow('matcher load failed');
+ await vi.advanceTimersByTimeAsync(0);
+
+ // 只剩 desktop-tree(隐藏)的意图 —— 靠退避重试把它的 watcher 建回来。
+ await vi.advanceTimersByTimeAsync(600);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ manager.stopAll();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ /**
+ * 评审 P2:**部分停止**按剩余消费者收窄 matcher 时重建失败,也要退避重试 ——
+ * 旧 watcher 这时已经拆了,只记日志会让剩下的消费者永久失去实时事件。
+ */
+ it('部分停止后的重建失败:退避重试直到恢复', async () => {
+ vi.useFakeTimers();
+ try {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ await manager.start('/repo', {}, 'device-link');
+ expect(h.created).toHaveLength(1); // 并集 watcher 只建一个
+
+ // 部分停止 → 收窄重建,但这次 loadIgnoreMatcher 失败。
+ h.failNext = 1;
+ manager.stop('/repo', 'desktop-tree');
+ await vi.advanceTimersByTimeAsync(0);
+ expect(h.created.at(-1)?.closed).toBe(true); // 旧 watcher 已关
+
+ // 退避重试后按剩余消费者(隐藏)建回 watcher。
+ await vi.advanceTimersByTimeAsync(600);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ manager.stopAll();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ /**
+ * 评审 P1:启动失败时若把消费者的意图留在 desired 里,控制端只会清本地注册、
+ * 不会再发 watchStop → daemon 里多出一个幽灵消费者:它抬高别的消费者的可见性
+ * 并集,最后一人 stop 时还会把它当孤儿 watcher 留下。
+ */
+ it('启动失败回滚本次消费者意图:不抬高别的消费者并集,也不留孤儿 watcher', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ let failWith = (_err: Error): void => {};
+ h.gate = new Promise<void>((_resolve, reject) => {
+ failWith = reject;
+ });
+
+ const failing = manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ failWith(new Error('matcher load failed'));
+ await expect(failing).rejects.toThrow('matcher load failed');
+ expect(h.created).toHaveLength(0);
+
+ // device-link(隐藏)看到的并集不应被那个失败的 reveal 需求抬高。
+ await manager.start('/repo', {}, 'device-link');
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+
+ // 最后一个真实消费者 stop:watcher 被拆(没有幽灵撑着)。
+ manager.stop('/repo', 'device-link');
+ expect(h.created.every((c) => c.closed)).toBe(true);
+ manager.stopAll();
+ });
+
+ /**
+ * 自查发现:回滚改变了并集,而且失败可能就发生在「选项变化 → closeEntry 拆掉旧
+ * watcher → startInner 失败」之后 —— 原有消费者此刻没有 watcher。回滚后必须按
+ * 恢复后的意图再收敛一次,否则它会静默失去直播。
+ */
+ it('启动失败回滚后按恢复的意图重建原有消费者的 watcher', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ // A(隐藏)先建好 watcher。
+ await manager.start('/repo', {}, 'desktop-tree');
+ expect(h.created).toHaveLength(1);
+
+ // B(reveal)到来:并集变化 → 拆旧重建;让这次 matcher 加载失败。
+ let failWith = (_err: Error): void => {};
+ h.gate = new Promise<void>((_resolve, reject) => {
+ failWith = reject;
+ });
+ const failing = manager.start('/repo', { showIgnoredDirs: true }, 'device-link');
+ failWith(new Error('matcher load failed'));
+ await expect(failing).rejects.toThrow('matcher load failed');
+ await new Promise((resolve) => setTimeout(resolve, 0)); // 等回滚后的 reconcile
+
+ // 回滚后只剩 A 的意图:必须有一个活着的 watcher 用隐藏 matcher。
+ expect(h.created).toHaveLength(2);
+ expect(h.created[0].closed).toBe(true);
+ expect(h.created[1].closed).toBe(false);
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ manager.stopAll();
+ });
+
+ /**
+ * 评审 P1:同一 consumerId 的重叠 start(双窗口启同一 workdir)共享同一次启动、
+ * 一起失败时,后到的那个不能把前一个**同样失败的**尝试当「前值」恢复 —— 否则
+ * 失败注册复活,回滚后的 fire-and-forget 收敛会真给它建一个没人再 stop 的
+ * 孤儿 watcher。
+ */
+ it('同一 consumerId 的重叠 start 都失败:不复活失败注册,不留活着的孤儿 watcher', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ let failWith = (_err: Error): void => {};
+ h.gate = new Promise<void>((_resolve, reject) => {
+ failWith = reject;
+ });
+
+ const first = manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ const second = manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ failWith(new Error('matcher load failed'));
+ await expect(first).rejects.toThrow('matcher load failed');
+ await expect(second).rejects.toThrow('matcher load failed');
+ await new Promise((resolve) => setTimeout(resolve, 0)); // 等 fire-and-forget 收敛
+
+ // 两个 caller 都失败 → 不能留下活着的 watcher(旧实现会复活失败注册并建出它)。
+ expect(h.created.every((c) => c.closed)).toBe(true);
+
+ // 下一次同选项 start 要真能建出活 watcher(注册表里没有幽灵)。
+ await manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ expect(h.created.at(-1)?.closed).toBe(false);
+ manager.stopAll();
+ });
+
+ /**
+ * 正向锁定:同一消费者已有生效注册、改选项重建失败时,回滚要恢复到**已生效**
+ * 的值(committed),而不是把注册从表里删掉 —— 否则那个消费者静默失去直播。
+ */
+ it('已有生效注册的消费者改选项失败:回滚到已生效值', async () => {
+ const manager = new WorkdirWatchManager(() => {});
+ await manager.start('/repo', {}, 'desktop-tree');
+ expect(h.created).toHaveLength(1);
+
+ let failWith = (_err: Error): void => {};
+ h.gate = new Promise<void>((_resolve, reject) => {
+ failWith = reject;
+ });
+ const failing = manager.start('/repo', { showIgnoredDirs: true }, 'desktop-tree');
+ failWith(new Error('matcher load failed'));
+ await expect(failing).rejects.toThrow('matcher load failed');
+ await new Promise((resolve) => setTimeout(resolve, 0));
+
+ // 回滚到已生效的隐藏态:watcher 活着且 matcher 用隐藏选项。
+ expect(h.matcherOpts.at(-1)?.showIgnoredDirs).toBe(false);
+ expect(h.created.at(-1)?.closed).toBe(false);
+ manager.stopAll();
+ });
+});
diff --git a/packages/remote-file-service/src/protocol.ts b/packages/remote-file-service/src/protocol.ts
index a1572fbe16..71a85c0ddf 100644
--- a/packages/remote-file-service/src/protocol.ts
+++ b/packages/remote-file-service/src/protocol.ts
@@ -36,7 +36,7 @@ import type {
export const FILE_SERVICE_SCHEMA_VERSION = 3;
/** 人读 bundle 版本(probe / 日志用),行为变化时手动 bump。 */
-export const FILE_SERVICE_BUNDLE_VERSION = '0.2.5';
+export const FILE_SERVICE_BUNDLE_VERSION = '0.2.6';
/* ============================== 帧 ============================== */
@@ -132,7 +132,24 @@ export interface FsRpcMethods {
};
};
listDir: {
- params: { workdir: string; relPath?: string; hideMetaFiles?: boolean; docMode?: boolean; includeIgnored?: boolean; maxEntries?: number };
+ params: {
+ workdir: string;
+ relPath?: string;
+ hideMetaFiles?: boolean;
+ docMode?: boolean;
+ /**
+ * 完全绕过展示过滤(手机 HTML 快照枚举用)。可选 / append-only:老 daemon
+ * 忽略未知字段 → 维持隐藏语义(拿不到全量,但不会报错)。
+ */
+ includeIgnored?: boolean;
+ /** 条目上限;超出时 daemon 返回 DIRECTORY_TOO_LARGE。 */
+ maxEntries?: number;
+ /**
+ * 控制端「显示被忽略的目录」开关。可选 / append-only:老 daemon 忽略未知
+ * 字段 → 维持隐藏语义(拿不到放行,但不会报错)。
+ */
+ showIgnoredDirs?: boolean;
+ };
result: { entries: DirEntry[] };
};
readFile: {
@@ -193,12 +210,23 @@ export interface FsRpcMethods {
params: { searchId: string };
result: { ok: true };
};
+ /**
+ * 订阅某个 workdir 的文件事件。`consumerId` 标识订阅方(desktop 文件树 /
+ * device-link 被控端 watch),可选 —— 老调用方缺省即归到默认消费者。
+ * 同一 workdir 的多个消费者各自登记过滤需求,daemon 取**可见性并集**
+ * (见 WorkdirWatchManager),不会互相覆盖 matcher。
+ */
watchStart: {
- params: { workdir: string; hideMetaFiles?: boolean };
+ params: {
+ workdir: string;
+ hideMetaFiles?: boolean;
+ showIgnoredDirs?: boolean;
+ consumerId?: string;
+ };
result: { ok: true };
};
watchStop: {
- params: { workdir: string };
+ params: { workdir: string; consumerId?: string };
result: { ok: true };
};
}
diff --git a/packages/remote-file-service/src/server.ts b/packages/remote-file-service/src/server.ts
index 4424b0c15a..717f15bbec 100644
--- a/packages/remote-file-service/src/server.ts
+++ b/packages/remote-file-service/src/server.ts
@@ -140,6 +140,7 @@ export function runFileService(
const matcher = p?.includeIgnored === true ? null : await loadIgnoreMatcher(workdir, {
hideMetaFiles: p?.hideMetaFiles ?? true,
honorVcsIgnore: false,
+ showIgnoredDirs: p?.showIgnoredDirs === true,
});
const entries = await listDir(workdir, p?.relPath ?? '', matcher, {
docMode: p?.includeIgnored === true ? false : p?.docMode,
@@ -205,13 +206,21 @@ export function runFileService(
return { ok: true as const };
},
watchStart: async (p) => {
- await watchManager.start(requireString(p?.workdir, 'workdir'), {
- hideMetaFiles: p?.hideMetaFiles ?? true,
- });
+ await watchManager.start(
+ requireString(p?.workdir, 'workdir'),
+ {
+ hideMetaFiles: p?.hideMetaFiles ?? true,
+ showIgnoredDirs: p?.showIgnoredDirs === true,
+ },
+ typeof p?.consumerId === 'string' ? p.consumerId : undefined,
+ );
return { ok: true as const };
},
watchStop: (p) => {
- watchManager.stop(requireString(p?.workdir, 'workdir'));
+ watchManager.stop(
+ requireString(p?.workdir, 'workdir'),
+ typeof p?.consumerId === 'string' ? p.consumerId : undefined,
+ );
return { ok: true as const };
},
};
diff --git a/packages/remote-file-service/src/watch.ts b/packages/remote-file-service/src/watch.ts
index 58960fba1b..156402623b 100644
--- a/packages/remote-file-service/src/watch.ts
+++ b/packages/remote-file-service/src/watch.ts
@@ -17,19 +17,80 @@
*
* 生命周期:per-workdir 单 watcher(重复 watchStart 幂等);stdin EOF /
* watchStop 时 close。事件经注入的 emit 回调发 `fileTree` 帧。
+ *
+ * 注:自带过滤器(ignore matcher / .xdt-tmp)在 watchStart 时就固定下来,
+ * 控制端改开关后需要先 watchStop 再 watchStart 才能换 matcher。
+ *
+ * 同一 workdir 会被**多个消费方**请求(desktop 的 SSH 文件浏览器、device-link
+ * 的 fs-watch topic)。每个消费方用 consumerId 登记自己的过滤需求,watcher 取
+ * 全部消费者的**可见性并集** —— 否则后到的一方(控制端默认隐藏)会把前一方的
+ * reveal matcher 覆盖掉:desktop 仍列着 build / dist,它们的改动却永远没有
+ * 事件。多推的帧由订阅端按各自视图忽略,代价远小于静默丢事件。任一消费者在,
+ * watcher 就不拆;最后一个 stop 才关。选项变化由 start() / stop() 收敛。
*/
import { watch as fsWatch, promises as fs, type FSWatcher } from 'node:fs';
import path from 'node:path';
import {
+ createEventIgnoreMatcher,
loadIgnoreMatcher,
scopedLogger,
+ WATCH_ALWAYS_IGNORE,
XDT_TMP_SUFFIX,
type Matcher,
} from '@cindy/file-browser-core';
const log = scopedLogger('file-service/watch');
+/**
+ * 「即使开关打开也不推事件」的恒真层(node_modules / Library / VCS / OS 垃圾)。
+ * 与 desktop 本地 watcher 的 PREFILTER_ALWAYS 同一份名单(单源:
+ * file-browser-core 的 WATCH_ALWAYS_IGNORE),因为 fs.watch recursive 会把
+ * 这些目录的事件照单全推上来 —— 没有这层兜底,`npm install` 或 Unity 导入会在
+ * SSH + IPC 上打出一串与路径数同阶的 fileTree 帧。容器依赖 workdir,常量即可。
+ */
+const eventAlwaysIgnore = createEventIgnoreMatcher();
+
+/**
+ * `WATCH_ALWAYS_IGNORE` 的小写集合。
+ *
+ * 按段比较的本地判断必须折叠大小写,与 `ignore` 包(createEventIgnoreMatcher
+ * 消费它,`ignorecase` 默认 true)的口径一致:大小写不敏感卷上 `NODE_MODULES` /
+ * `library` 这类变体在开关打开时可见,若本地比较区分大小写,它们**自身**的事件
+ * 会被恒真层吞掉,行陈旧到手动刷新(评审 P2)。
+ */
+const alwaysIgnoreNamesLower = new Set(
+ (WATCH_ALWAYS_IGNORE as readonly string[]).map((name) => name.toLowerCase()),
+);
+
+/**
+ * 路径是否落在「开关打开也永远不推事件」目录的**内部**(不含目录自身)。
+ *
+ * 为什么不直接问 eventAlwaysIgnore:`ignore` 的目录模式(`node_modules/`)同时
+ * 匹配该目录自身与它全部后代,而这里要的只是后代 —— 开关打开时 node_modules /
+ * Library 这一行就在树里,它自己被创建 / 删除 / 改名必须让父目录 refetch
+ * (评审 P1:整条 rename 被吞掉的话,树会陈旧到手动刷新)。所以按路径段判断:
+ * 除最后一段外任一段命中名单即为「内部」。
+ */
+function isInsideAlwaysIgnoredDir(relPath: string): boolean {
+ const segments = relPath.split('/');
+ for (let i = 0; i < segments.length - 1; i += 1) {
+ if (alwaysIgnoreNamesLower.has(segments[i].toLowerCase())) return true;
+ }
+ return false;
+}
+
+/**
+ * 路径是否是「开关打开也永远不推事件」目录的**自身**(node_modules / Library)。
+ * 这些行在开关打开时就在树里(见 isInsideAlwaysIgnoredDir),而恒真层的`ignore`
+ * 模式对自身也命中 —— 兜底那一行必须先把它排除掉,否则目录自身的 rename 又会被
+ * 吞回去。
+ */
+function isAlwaysIgnoredDirItself(relPath: string): boolean {
+ const last = relPath.slice(relPath.lastIndexOf('/') + 1);
+ return alwaysIgnoreNamesLower.has(last.toLowerCase());
+}
+
export interface RemoteFileTreeEvent {
workdir: string;
type: 'add' | 'change' | 'unlink';
@@ -40,13 +101,49 @@ export interface RemoteFileTreeEvent {
interface WatchEntry {
watcher: FSWatcher;
matcher: Matcher;
+ /** 建 watcher 时生效的过滤开关;变了要重建 matcher(fs.watch 本身不变)。 */
+ hideMetaFiles: boolean;
+ showIgnoredDirs: boolean;
/** coalesce 缓冲:key = `${type}::${relPath}`。 */
pending: Map<string, RemoteFileTreeEvent>;
flushTimer: NodeJS.Timeout | null;
}
+/** 决定 watcher 过滤行为的选项(不含 workdir)。 */
+interface WatchFilterOptions {
+ hideMetaFiles: boolean;
+ showIgnoredDirs: boolean;
+}
+
+/** 一个消费者在某个 workdir 上的意图。 */
+interface ConsumerIntent {
+ /** 当前尝试的过滤需求(reconcile 与并集用这个)。 */
+ options: WatchFilterOptions;
+ /** 最近一次 reconcile **成功后**生效过的值;从没成功过是 null。
+ * 失败回滚恢复到它 —— 不能快照「进入 start 时的前值」:同一 consumerId 的
+ * 重叠 start 里,那个前值可能是另一个尚未提交、同样失败的尝试(评审 P1)。 */
+ committed: WatchFilterOptions | null;
+}
+
+function normalizeWatchOptions(opts: {
+ hideMetaFiles?: boolean;
+ showIgnoredDirs?: boolean;
+}): WatchFilterOptions {
+ return { hideMetaFiles: opts.hideMetaFiles ?? true, showIgnoredDirs: opts.showIgnoredDirs === true };
+}
+
+function sameWatchOptions(a: WatchFilterOptions, b: WatchFilterOptions): boolean {
+ return a.hideMetaFiles === b.hideMetaFiles && a.showIgnoredDirs === b.showIgnoredDirs;
+}
+
const COALESCE_MS = 50;
+/** watcher 报错后重建的退避参数:起点 / 上限 / 次数上限。 */
+const RECONCILE_RETRY_BASE_MS = 500;
+const RECONCILE_RETRY_MAX_MS = 8_000;
+/** 退避指数的封顶档位:计数到这里后不再变大,转为固定 RECONCILE_RETRY_MAX_MS 重试。 */
+const RECONCILE_RETRY_BACKOFF_CAP = 5;
+
export class WorkdirWatchManager {
private readonly entries = new Map<string, WatchEntry>();
/** 启动中的 workdir:has 判定与 entries.set 之间隔着 loadIgnoreMatcher 的
@@ -57,47 +154,233 @@ export class WorkdirWatchManager {
/** 启动窗口内收到 stop 的 workdir:startInner 完成时不装 watcher(装完即拆),
* 否则快速开关文件浏览会留下无人再来 stop 的孤儿原生 watcher。 */
private readonly stopDuringStart = new Set<string>();
+ /** 每个 workdir 的消费者 → 它的意图(当前尝试 + 最近一次生效值)。watcher 只此
+ * 一份,选项取全部消费者的可见性并集(见 effectiveOptions);start() / stop()
+ * 每轮重读它收敛。 */
+ private readonly desired = new Map<string, Map<string, ConsumerIntent>>();
+
+ /** watcher 报错后的重建重试定时器与次数(退避 + 上限,见 scheduleReconcileRetry)。 */
+ private readonly retryTimers = new Map<string, NodeJS.Timeout>();
+ private readonly retryAttempts = new Map<string, number>();
+
+ /** 没带 consumerId 的调用方(旧控制端 / 内部调用)归到这个默认消费者。 */
+ private static readonly DEFAULT_CONSUMER = 'default';
private readonly emit: (event: RemoteFileTreeEvent) => void;
constructor(emit: (event: RemoteFileTreeEvent) => void) {
this.emit = emit;
}
- /** 幂等启动。matcher 加载失败 / fs.watch 抛错向上冒(RPC 返回 OPERATION_FAILED)。 */
- async start(workdir: string, opts: { hideMetaFiles?: boolean } = {}): Promise<void> {
- if (this.entries.has(workdir)) return;
- const inflight = this.starting.get(workdir);
- if (inflight) return inflight;
- const run = this.startInner(workdir, opts);
- this.starting.set(workdir, run);
+ /** 幂等启动。matcher 加载失败 / fs.watch 抛错向上冒(RPC 返回 OPERATION_FAILED)。
+ * 已存在同 workdir 的 watcher 时:过滤开关不同则重建(控制端改了「显示被忽略
+ * 的目录」后无需先 stop,重启守护进程也不必同步状态)。 */
+ async start(
+ workdir: string,
+ opts: { hideMetaFiles?: boolean; showIgnoredDirs?: boolean } = {},
+ consumerId: string = WorkdirWatchManager.DEFAULT_CONSUMER,
+ ): Promise<void> {
+ const consumers = this.desired.get(workdir) ?? new Map<string, ConsumerIntent>();
+ const attempted = normalizeWatchOptions(opts);
+ consumers.set(consumerId, {
+ options: attempted,
+ committed: consumers.get(consumerId)?.committed ?? null,
+ });
+ this.desired.set(workdir, consumers);
try {
- await run;
- } finally {
- this.starting.delete(workdir);
- this.stopDuringStart.delete(workdir);
+ await this.reconcile(workdir);
+ this.clearReconcileRetry(workdir); // 新意图已生效:旧的重试状态作废
+ // 成功才记 committed:失败回滚只恢复到「真的生效过」的值。
+ const settled = this.desired.get(workdir)?.get(consumerId);
+ if (settled && settled.options === attempted) settled.committed = attempted;
+ } catch (err) {
+ // 启动失败:回滚**本次**写入的意图,否则 daemon 会留下一个「幽灵消费者」——
+ // 控制端的失败处理只清本地注册、不会再发 watchStop(见 remote-watch.ts),
+ // 之后别的消费者的可见性并集会被它抬高,最后一人 stop 时还会因它留下
+ // 孤儿 watcher(评审 P1)。
+ //
+ // 恢复到 **committed** 而不是进入时快照:同一 consumerId 的重叠 start(双
+ // 窗口启同一 workdir)里,快照可能是另一个尚未提交、同样失败的尝试 ——
+ // 恢复它等于让失败注册复活,而下面 fire-and-forget 的 reconcile 会真给
+ // 它建一个没人再 stop 的 watcher。没有 committed = 该 consumer 从未成功
+ // 注册过,直接删。
+ const current = this.desired.get(workdir)?.get(consumerId);
+ if (current && current.options === attempted) {
+ if (current.committed) {
+ current.options = current.committed;
+ } else {
+ this.desired.get(workdir)?.delete(consumerId);
+ if (this.desired.get(workdir)?.size === 0) this.desired.delete(workdir);
+ }
+ }
+ // 回滚改变了并集,而且失败可能就在「选项变化 → closeEntry 拆掉旧 watcher →
+ // startInner 失败」之后:原有消费者此刻没有 watcher。按恢复后的意图再收敛
+ // 一次;这次也失败(挂载仍不可用)就走**带退避的重试** —— 只记日志会让原消费
+ // 者静默失去直播,直到下一次显式 start / stop 或 daemon 重连(评审 P1)。
+ void this.reconcile(workdir)
+ .then(() => this.retryAttempts.delete(workdir))
+ .catch((rerr) => {
+ log.warn('watch reconcile after rollback failed', workdir, String(rerr));
+ this.scheduleReconcileRetry(workdir);
+ });
+ throw err;
+ }
+ }
+
+ /**
+ * 收敛到「当前所有消费者的可见性并集」。为什么不直接 piggyback 启动中的
+ * promise:启动窗口内到达的 stop 会给 stopDuringStart 打标记让那个 watcher
+ * 自拆,而带新选项的 start 如果只是复用旧 promise,就会既丢掉新选项、又因为
+ * 标记留下「没有 watcher」的空档(两个 RPC 都报 success)。这里每轮重读
+ * desired,所以两种中途变化都在下一轮收敛。
+ *
+ * 终止性:每轮要么直接确认返回、要么推进一次真实的 startInner;desired 只会
+ * 被更新的请求改写或被 stop 删除,并发调用者数量有限 —— 循环次数以此封顶。
+ */
+ private async reconcile(workdir: string): Promise<void> {
+ for (;;) {
+ const inflight = this.starting.get(workdir);
+ if (inflight) {
+ // 前一轮可能用了已被覆盖的旧选项,也可能因期间到来的 stop 自拆 ——
+ // 都交给下一轮。它的失败由发起它的 caller 冒走,这里不吞也不重试。
+ await inflight;
+ continue;
+ }
+ const want = this.effectiveOptions(workdir);
+ if (!want) {
+ // 没有消费者了:watcher 不该活着。所有进入这里的路径(stop、回滚删掉
+ // 最后一个消费者)都要维护这个不变量 —— 否则会留下没人再 stop 的孤儿
+ // watcher(评审 P1 同类:回滚删注册后 fire-and-forget 的收敛不会再拆)。
+ this.closeEntry(workdir);
+ return;
+ }
+ const existing = this.entries.get(workdir);
+ if (existing) {
+ if (sameWatchOptions(existing, want)) return;
+ // 选项变了:拆掉重建(不能走 stop(),它会撤销 desired)。重建前先转发
+ // 合并窗口里的事件 —— 否则还在线的消费者会漏掉这一批(评审 P2)。
+ this.closeEntry(workdir, { flushPending: true });
+ }
+ const run = this.startInner(workdir, want);
+ this.starting.set(workdir, run);
+ try {
+ await run;
+ } finally {
+ this.starting.delete(workdir);
+ this.stopDuringStart.delete(workdir);
+ }
+ }
+ }
+
+ /**
+ * 全部消费者的可见性并集:任一消费者要看被忽略目录 / `.meta`,watcher 就得
+ * 放行它们(推给各订阅端后由各自的视图忽略)。没有消费者时返回 null。
+ */
+ private effectiveOptions(workdir: string): WatchFilterOptions | null {
+ const consumers = this.desired.get(workdir);
+ if (!consumers || consumers.size === 0) return null;
+ let showIgnoredDirs = false;
+ let showMetaFiles = false;
+ for (const intent of consumers.values()) {
+ if (intent.options.showIgnoredDirs) showIgnoredDirs = true;
+ if (!intent.options.hideMetaFiles) showMetaFiles = true;
}
+ return { showIgnoredDirs, hideMetaFiles: !showMetaFiles };
}
- private async startInner(workdir: string, opts: { hideMetaFiles?: boolean }): Promise<void> {
+ /**
+ * watcher 报错后的收敛重试(退避封顶,不设总上限)。
+ *
+ * 为什么不能只 catch 一下:错误把 entry 拆掉后,如果紧接着的 reconcile 又失败
+ * (远程挂载短暂不可用 / 目录正在被替换),消费者意图仍留在 desired、但已经
+ * 没有 watcher,也没有任何定时器会再来收敛 —— SSH 连接没断的情况下,后续文件
+ * 事件会永久停止,直到用户改开关或重挂载面板(评审 P2)。退避避免持续失败时
+ * 形成紧密重建循环。
+ *
+ * 为什么退避到顶还要继续:挂载 / 权限故障持续超过退避窗口(约 15.5s)在真实
+ * 环境里很常见(扩容挂载、目录正在被替换),此时不能永久放弃 —— 意图还在,
+ * watcher 就必须最终建回来,否则故障恢复后事件永久静默、只能靠重挂面板救
+ * (评审 P1)。封顶后按固定频率重试,单次只做一次 matcher 加载 + fs.watch,
+ * 代价可忽略;消费者撤销由 clearReconcileRetry / stopAll 结束这个循环。
+ */
+ private scheduleReconcileRetry(workdir: string): void {
+ if (this.retryTimers.has(workdir)) return;
+ if (!this.desired.has(workdir)) return; // 期间消费者全撤了:不再重试
+ const attempt = (this.retryAttempts.get(workdir) ?? 0) + 1;
+ // 计数封顶:延迟计算不会越界,超限后转为固定频率重试。
+ const capped = Math.min(attempt, RECONCILE_RETRY_BACKOFF_CAP);
+ this.retryAttempts.set(workdir, capped);
+ if (attempt === RECONCILE_RETRY_BACKOFF_CAP + 1) {
+ log.warn('watch reconcile still failing, retrying at capped backoff', workdir);
+ }
+ const delay = Math.min(
+ RECONCILE_RETRY_BASE_MS * 2 ** (capped - 1),
+ RECONCILE_RETRY_MAX_MS,
+ );
+ const timer = setTimeout(() => {
+ this.retryTimers.delete(workdir);
+ void this.reconcile(workdir)
+ .then(() => this.retryAttempts.delete(workdir))
+ .catch((err) => {
+ log.warn('watch reconcile retry failed', workdir, String(err));
+ this.scheduleReconcileRetry(workdir);
+ });
+ }, delay);
+ timer.unref?.();
+ this.retryTimers.set(workdir, timer);
+ }
+
+ /** 清掉某个 workdir 的重试状态(stop / 新 start 成功时调用)。 */
+ private clearReconcileRetry(workdir: string): void {
+ const timer = this.retryTimers.get(workdir);
+ if (timer) {
+ clearTimeout(timer);
+ this.retryTimers.delete(workdir);
+ }
+ this.retryAttempts.delete(workdir);
+ }
+
+ private async startInner(workdir: string, opts: WatchFilterOptions): Promise<void> {
const matcher = await loadIgnoreMatcher(workdir, {
- hideMetaFiles: opts.hideMetaFiles ?? true,
+ hideMetaFiles: opts.hideMetaFiles,
honorVcsIgnore: false,
+ showIgnoredDirs: opts.showIgnoredDirs,
});
- const entry: WatchEntry = { watcher: null as unknown as FSWatcher, matcher, pending: new Map(), flushTimer: null };
+ const entry: WatchEntry = {
+ watcher: null as unknown as FSWatcher,
+ matcher,
+ hideMetaFiles: opts.hideMetaFiles,
+ showIgnoredDirs: opts.showIgnoredDirs,
+ pending: new Map(),
+ flushTimer: null,
+ };
const watcher = fsWatch(workdir, { recursive: true }, (eventType, filename) => {
// filename 偶发 null(平台边缘情况),无法定位目标 — 丢弃,聚焦刷新兜底。
if (!filename) return;
void this.handleRaw(workdir, entry, eventType, filename.toString());
});
watcher.on('error', (err) => {
- // watcher 挂了(权限 / 目录被删):log 后移除,消费端靠手动刷新。
+ // watcher 挂了(权限 / 目录被删):拆掉**这个** entry,保留消费者意图并按
+ // 剩余并集重建。不能走 stop(workdir) —— 那要挑一个 consumerId,而错误不是
+ // 任何消费者的意图变化:拿默认 id 会删错人,reconcile 又看到同一个坏
+ // entry 选项没变而原地返回,直播就静默冻结到手动改开关或 daemon 重启。
log.warn('fs.watch error, dropping watcher', workdir, String(err));
- this.stop(workdir);
+ if (this.entries.get(workdir) !== entry) return; // 已被替换 / 停止:不碰新 entry
+ // 报错前已入队的事件仍是真实事件:重建前先转发,不随旧 entry 丢弃(评审 P2)。
+ this.closeEntry(workdir, { flushPending: true });
+ // 就地收敛;失败(挂载短暂不可用 / 目录正在被替换)则带退避重试,直到成功
+ // 或耗尽 —— 只记日志会让这个入口静默失效到用户改开关(评审 P2)。
+ void this.reconcile(workdir)
+ .then(() => this.retryAttempts.delete(workdir))
+ .catch((rerr) => {
+ log.warn('watch reconcile after error failed', workdir, String(rerr));
+ this.scheduleReconcileRetry(workdir);
+ });
});
entry.watcher = watcher;
if (this.stopDuringStart.delete(workdir)) {
// 启动期间来了 stop(调用方的登记已清,不会再发第二次 stop):当场拆掉。
+ // 标记的清理归 reconcile 的 finally(成功 / 失败两条路径都走那里)。
try {
watcher.close();
} catch {
@@ -110,13 +393,60 @@ export class WorkdirWatchManager {
log.info('watch started', workdir);
}
- stop(workdir: string): void {
+ stop(workdir: string, consumerId: string = WorkdirWatchManager.DEFAULT_CONSUMER): void {
+ const consumers = this.desired.get(workdir);
+ if (consumers) {
+ consumers.delete(consumerId);
+ if (consumers.size > 0) {
+ // 还有别的消费者:按剩余并集收敛(可能收窄,需要重建 matcher)。这里是
+ // sync 的 RPC handler,重建异步进行 —— RPC 语义是「撤销本消费者的
+ // 需求」,不承诺 watcher 在返回前已重建完。失败要走带退避的**重试**:
+ // 旧 watcher 此刻已经被拆了,只记日志会让剩下的消费者在挂载短暂不可用
+ // 时永久失去实时事件,直到下一次显式 start / stop 或 daemon 重连
+ // (评审 P2)。
+ void this.reconcile(workdir)
+ .then(() => this.retryAttempts.delete(workdir))
+ .catch((err) => {
+ log.warn('watch reconcile after partial stop failed', workdir, String(err));
+ this.scheduleReconcileRetry(workdir);
+ });
+ return;
+ }
+ this.desired.delete(workdir);
+ }
+ this.clearReconcileRetry(workdir);
+ // 撤销意图:收敛循环读到 desired 缺失即结束(piggyback 的新 start 会写回)。
// 还在启动窗口:打标记让 startInner 完成时自拆(entries 里此刻还没有它)。
if (this.starting.has(workdir)) this.stopDuringStart.add(workdir);
+ this.closeEntry(workdir);
+ }
+
+ /** 把合并窗口里已经入队的事件立刻发出去(重建前保序转发用)。 */
+ private flushPending(entry: WatchEntry): void {
+ if (entry.flushTimer) {
+ clearTimeout(entry.flushTimer);
+ entry.flushTimer = null;
+ }
+ if (entry.pending.size === 0) return;
+ const batch = [...entry.pending.values()];
+ entry.pending.clear();
+ for (const evt of batch) this.emit(evt);
+ }
+
+ /**
+ * 拆掉已就位的 watcher。不碰 desired —— 选项变化重建时由调用方决定意图。
+ *
+ * `flushPending`:**重建**路径(选项变化 / watcher 报错后重建)要先转发合并
+ * 窗口里的事件 —— 旧 entry 的 `pending` 随 entry 一起被丢的话,还活着的消费者
+ * 会漏掉这次事件,文件树陈旧到同目录下一次事件或手动刷新(评审 P2)。
+ * 最后一个消费者停止 / stopAll 不带这个旗标:那时事件已无人消费,直接丢。
+ */
+ private closeEntry(workdir: string, opts?: { flushPending?: boolean }): void {
const entry = this.entries.get(workdir);
if (!entry) return;
this.entries.delete(workdir);
- if (entry.flushTimer) clearTimeout(entry.flushTimer);
+ if (opts?.flushPending) this.flushPending(entry);
+ else if (entry.flushTimer) clearTimeout(entry.flushTimer);
try {
entry.watcher.close();
} catch {
@@ -126,8 +456,13 @@ export class WorkdirWatchManager {
}
stopAll(): void {
+ // 全部意图撤销:启动中的 workdir 也要让收敛循环看到「没有 desired」而结束。
+ this.desired.clear();
+ for (const timer of this.retryTimers.values()) clearTimeout(timer);
+ this.retryTimers.clear();
+ this.retryAttempts.clear();
for (const workdir of [...this.starting.keys()]) this.stopDuringStart.add(workdir);
- for (const workdir of [...this.entries.keys()]) this.stop(workdir);
+ for (const workdir of [...this.entries.keys()]) this.closeEntry(workdir);
}
private async handleRaw(
@@ -139,8 +474,14 @@ export class WorkdirWatchManager {
const relPath = rawFilename.split(path.sep).join('/');
if (relPath === '' || relPath.startsWith('..')) return;
if (relPath.endsWith(XDT_TMP_SUFFIX)) return;
- // matcher 不知道路径是 file 还是 dir,双查任一命中即丢(同 desktop watcher)。
+ /** matcher 不知道路径是 file 还是 dir,双查任一命中即丢(同 desktop watcher)。 */
if (entry.matcher.ignores(relPath, false) && entry.matcher.ignores(relPath, true)) return;
+ // 开关打开也永远不推的目录(node_modules / Library):只丢**内部**事件,
+ // 目录自身的生命周期事件要留(见 isInsideAlwaysIgnoredDir)。
+ if (isInsideAlwaysIgnoredDir(relPath)) return;
+ // 兜底:BUILTIN_IGNORE_ALWAYS(.git / .DS_Store 之类,自身与后代都不显示)。
+ // 但恒真忽略目录自身已在上一行放行,不能再被这里拦下。
+ if (!isAlwaysIgnoredDirItself(relPath) && eventAlwaysIgnore.ignores(relPath, true)) return;
let type: RemoteFileTreeEvent['type'];
if (eventType === 'change') {
@@ -162,9 +503,7 @@ export class WorkdirWatchManager {
if (entry.flushTimer) return;
entry.flushTimer = setTimeout(() => {
entry.flushTimer = null;
- const batch = [...entry.pending.values()];
- entry.pending.clear();
- for (const evt of batch) this.emit(evt);
+ this.flushPending(entry);
}, COALESCE_MS);
entry.flushTimer.unref?.();
}