🔧 chore(vscode): 版本号升到 0.2.210

- 照源代码管理视图分「暂存的更改」「更改」两组（空的不摆，分组行写文件数），部分暂存的文件两组都有
- 「更改」组的文件行上加「暂存」按钮，走 git 扩展的 repository.add
- 标题栏「隐藏测试文件 / 显示测试文件」开关，按工作区记住，藏了几个写在标题后面；测试文件的判断集中在 isTestFile
- 以上只在「未提交的更改」里有：普通文件树、审查模式的行和菜单不变

vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "clurdra",
   "name": "superpowers-vscode-clurdra",
   "displayName": "Superpowers-clurdra",
-  "version": "0.2.208",
+  "version": "0.2.210",
   "packageManager": "pnpm@10.27.0",
   "description": "Superpowers specs and plans Kanban explorer",
   "author": "clurdra",
@@ -109,6 +109,30 @@
         "category": "代码阅读",
         "icon": "$(git-pull-request)"
       },
+      {
+        "command": "superpowers.codeReader.showUncommitted",
+        "title": "未提交的更改",
+        "category": "代码阅读",
+        "icon": "$(git-commit)"
+      },
+      {
+        "command": "superpowers.codeReader.hideTests",
+        "title": "隐藏测试文件",
+        "category": "代码阅读",
+        "icon": "$(beaker-stop)"
+      },
+      {
+        "command": "superpowers.codeReader.showTests",
+        "title": "显示测试文件",
+        "category": "代码阅读",
+        "icon": "$(beaker)"
+      },
+      {
+        "command": "superpowers.codeReader.stage",
+        "title": "暂存",
+        "category": "代码阅读",
+        "icon": "$(add)"
+      },
       {
         "command": "superpowers.codeReader.showAllFiles",
         "title": "显示全部",
@@ -209,7 +233,7 @@
       "superpowers.codeReader.copy": [
         {
           "command": "superpowers.codeReader.copyFileName",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( unstaged)?( noted)?$/",
           "group": "copy@1"
         },
         {
@@ -219,17 +243,17 @@
         },
         {
           "command": "superpowers.codeReader.copyFileStem",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( unstaged)?( noted)?$/",
           "group": "copy@2"
         },
         {
           "command": "superpowers.codeReader.copyRelativePath",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file|folder)( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file( unstaged)?|folder)( noted)?$/",
           "group": "copy@3"
         },
         {
           "command": "superpowers.codeReader.copyAbsolutePath",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file|folder)( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file( unstaged)?|folder)( noted)?$/",
           "group": "copy@4"
         }
       ],
@@ -255,35 +279,55 @@
           "group": "navigation@1"
         },
         {
-          "command": "superpowers.codeReader.showAllFiles",
-          "when": "view == superpowers.codeReader.files && superpowers.codeReader.reviewing",
+          "command": "superpowers.codeReader.showUncommitted",
+          "when": "view == superpowers.codeReader.files",
           "group": "navigation@2"
         },
+        {
+          "command": "superpowers.codeReader.hideTests",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter == uncommitted && !superpowers.codeReader.testsHidden",
+          "group": "navigation@3"
+        },
+        {
+          "command": "superpowers.codeReader.showTests",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter == uncommitted && superpowers.codeReader.testsHidden",
+          "group": "navigation@3"
+        },
+        {
+          "command": "superpowers.codeReader.showAllFiles",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter",
+          "group": "navigation@4"
+        },
         {
           "command": "superpowers.codeReader.refresh",
           "when": "view == superpowers.codeReader.files",
-          "group": "navigation@3"
+          "group": "navigation@5"
         }
       ],
       "view/item/context": [
         {
           "submenu": "superpowers.codeReader.copy",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file|folder)( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file( unstaged)?|folder)( noted)?$/",
           "group": "inline@1"
         },
         {
           "command": "superpowers.codeReader.addNote",
-          "when": "view == superpowers.codeReader.files && !superpowers.codeReader.reviewing && viewItem =~ /^(file|folder)$/",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter != review && viewItem =~ /^(file( unstaged)?|folder)$/",
           "group": "inline@2"
         },
         {
           "command": "superpowers.codeReader.editNote",
-          "when": "view == superpowers.codeReader.files && !superpowers.codeReader.reviewing && viewItem =~ /^(file|folder) noted$/",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter != review && viewItem =~ /^(file( unstaged)?|folder) noted$/",
           "group": "inline@2"
         },
+        {
+          "command": "superpowers.codeReader.stage",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter == uncommitted && viewItem =~ /^file unstaged( noted)?$/",
+          "group": "inline@3"
+        },
         {
           "command": "superpowers.codeReader.copyFileName",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( unstaged)?( noted)?$/",
           "group": "copy@1"
         },
         {
@@ -293,27 +337,27 @@
         },
         {
           "command": "superpowers.codeReader.copyFileStem",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^file( unstaged)?( noted)?$/",
           "group": "copy@2"
         },
         {
           "command": "superpowers.codeReader.copyRelativePath",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file|folder)( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file( unstaged)?|folder)( noted)?$/",
           "group": "copy@3"
         },
         {
           "command": "superpowers.codeReader.copyAbsolutePath",
-          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file|folder)( noted)?$/",
+          "when": "view == superpowers.codeReader.files && viewItem =~ /^(file( unstaged)?|folder)( noted)?$/",
           "group": "copy@4"
         },
         {
           "command": "superpowers.codeReader.addNote",
-          "when": "view == superpowers.codeReader.files && !superpowers.codeReader.reviewing && viewItem =~ /^(file|folder)$/",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter != review && viewItem =~ /^(file( unstaged)?|folder)$/",
           "group": "notes"
         },
         {
           "command": "superpowers.codeReader.editNote",
-          "when": "view == superpowers.codeReader.files && !superpowers.codeReader.reviewing && viewItem =~ /^(file|folder) noted$/",
+          "when": "view == superpowers.codeReader.files && superpowers.codeReader.filter != review && viewItem =~ /^(file( unstaged)?|folder) noted$/",
           "group": "notes"
         }
       ],
@@ -336,7 +380,19 @@
         },
         {
           "command": "superpowers.codeReader.showAllFiles",
-          "when": "superpowers.codeReader.reviewing"
+          "when": "superpowers.codeReader.filter"
+        },
+        {
+          "command": "superpowers.codeReader.hideTests",
+          "when": "superpowers.codeReader.filter == uncommitted && !superpowers.codeReader.testsHidden"
+        },
+        {
+          "command": "superpowers.codeReader.showTests",
+          "when": "superpowers.codeReader.filter == uncommitted && superpowers.codeReader.testsHidden"
+        },
+        {
+          "command": "superpowers.codeReader.stage",
+          "when": "false"
         },
         {
           "command": "superpowers.codeReader.showPreview",

vscode/src/codeReader/explorer/changedTree.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { buildChangedTree } from './changedTree'
+
+describe('改动的文件树', () => {
+  // 原型「审查 · 改动的文件」里的 6 个文件（schemas.py 是改名的，算修改）
+  const files = [
+    { path: 'backend/src/luffy_agent/user/routes.py', change: 'M' },
+    { path: 'backend/tests/user/test_avatar.py', change: 'A' },
+    { path: 'backend/src/luffy_agent/core/storage.py', change: 'M' },
+    { path: 'backend/src/luffy_agent/user/legacy_profile.py', change: 'D' },
+    { path: 'backend/src/luffy_agent/user/services.py', change: 'M' },
+    { path: 'backend/src/luffy_agent/user/schemas.py', change: 'M' },
+  ] as const
+  const tree = buildChangedTree(files)
+  const names = (dir: string): string[] => (tree.get(dir) ?? []).map(entry => entry.name)
+
+  it('目录层级照留，每层只有通往改动的文件的目录', () => {
+    expect(names('')).toEqual(['backend'])
+    expect(names('backend')).toEqual(['src', 'tests'])
+    expect(names('backend/src')).toEqual(['luffy_agent'])
+    expect(names('backend/src/luffy_agent')).toEqual(['core', 'user'])
+    expect(names('backend/src/luffy_agent/core')).toEqual(['storage.py'])
+    expect(names('backend/tests/user')).toEqual(['test_avatar.py'])
+  })
+
+  it('同一层里的文件按名字排，带着各自的改动和相对根目录的路径', () => {
+    expect(tree.get('backend/src/luffy_agent/user')).toEqual([
+      { name: 'legacy_profile.py', path: 'backend/src/luffy_agent/user/legacy_profile.py', isDirectory: false, change: 'D' },
+      { name: 'routes.py', path: 'backend/src/luffy_agent/user/routes.py', isDirectory: false, change: 'M' },
+      { name: 'schemas.py', path: 'backend/src/luffy_agent/user/schemas.py', isDirectory: false, change: 'M' },
+      { name: 'services.py', path: 'backend/src/luffy_agent/user/services.py', isDirectory: false, change: 'M' },
+    ])
+  })
+
+  it('目录没有改动，路径相对根目录', () => {
+    expect(tree.get('backend')).toEqual([
+      { name: 'src', path: 'backend/src', isDirectory: true },
+      { name: 'tests', path: 'backend/tests', isDirectory: true },
+    ])
+  })
+
+  it('目录在前、文件在后，名字不区分大小写，和普通的树一样', () => {
+    const mixed = buildChangedTree([
+      { path: 'README.md', change: 'M' },
+      { path: 'src/a.ts', change: 'A' },
+      { path: 'Docs/b.md', change: 'A' },
+      { path: 'package.json', change: 'M' },
+    ])
+    expect(mixed.get('')?.map(entry => entry.name)).toEqual(['Docs', 'src', 'package.json', 'README.md'])
+  })
+
+  it('文件换成同名目录（删掉 a、新加 a/b）两项都留着', () => {
+    const replaced = buildChangedTree([{ path: 'a', change: 'D' }, { path: 'a/b', change: 'A' }])
+    expect(replaced.get('')).toEqual([
+      { name: 'a', path: 'a', isDirectory: true },
+      { name: 'a', path: 'a', isDirectory: false, change: 'D' },
+    ])
+    expect(replaced.get('a')?.map(entry => entry.change)).toEqual(['A'])
+  })
+
+  it('没有改动的文件时根下面是空的', () => {
+    expect(buildChangedTree([]).get('')).toEqual([])
+  })
+})

vscode/src/codeReader/explorer/changedTree.ts

@@ -0,0 +1,51 @@
+import type { DirEntry } from './fileEntries'
+import { sortEntries } from './fileEntries'
+
+/** 一个文件怎么改的，照 VS Code 源代码管理的写法：修改 M、新增 A、删除 D。 */
+export type FileChange = 'M' | 'A' | 'D'
+
+/** 改动的一个文件。 */
+export interface ChangedFile {
+  /** 相对根目录（仓库根、审查的工作副本），`/` 分隔 */
+  path: string
+  change: FileChange
+}
+
+/** 改动的文件树上的一项。 */
+export interface ChangedEntry extends DirEntry {
+  /** 相对根目录，`/` 分隔 */
+  path: string
+  /** 文件怎么改的；目录没有 */
+  change?: FileChange
+}
+
+/** 按目录分好的改动：键是目录相对根目录的路径（根目录是 `''`），值是它下面一层的目录和文件。 */
+export type ChangedTree = ReadonlyMap<string, readonly ChangedEntry[]>
+
+/**
+ * 改动的文件 → 按目录分好的树：只有改动的文件和通往它们的目录，目录层级照留，
+ * 每层的排法和侧栏普通的树一样（目录在前、名字不区分大小写）。
+ * 同一路径上一个文件换成了同名目录（删掉文件 `a`、新加 `a/b`）时两项都留着。
+ */
+export function buildChangedTree(files: readonly ChangedFile[]): ChangedTree {
+  const levels = new Map<string, Map<string, ChangedEntry>>([['', new Map()]])
+  const add = (dir: string, entry: ChangedEntry): void => {
+    let level = levels.get(dir)
+    if (!level)
+      levels.set(dir, level = new Map())
+    const key = `${entry.isDirectory ? 'dir' : 'file'}:${entry.name}`
+    if (!level.has(key))
+      level.set(key, entry)
+  }
+  for (const file of files) {
+    const segments = file.path.split('/')
+    segments.forEach((name, index) => {
+      const dir = segments.slice(0, index).join('/')
+      const path = segments.slice(0, index + 1).join('/')
+      add(dir, index === segments.length - 1
+        ? { name, path, isDirectory: false, change: file.change }
+        : { name, path, isDirectory: true })
+    })
+  }
+  return new Map([...levels].map(([dir, level]) => [dir, sortEntries([...level.values()])]))
+}

vscode/src/codeReader/explorer/fileEntries.test.ts

@@ -28,6 +28,12 @@ describe('行的 contextValue', () => {
     expect(entryContext({ isDirectory: true, isRoot: false })).toBe('folder')
     expect(entryContext({ isDirectory: false, isRoot: false })).toBe('file')
   })
+
+  it('文件行可以带标记（「更改」区能暂存的 file unstaged），目录、根不带', () => {
+    expect(entryContext({ isDirectory: false, isRoot: false }, 'unstaged')).toBe('file unstaged')
+    expect(entryContext({ isDirectory: true, isRoot: false }, 'unstaged')).toBe('folder')
+    expect(entryContext({ isDirectory: true, isRoot: true }, 'unstaged')).toBe('root')
+  })
 })
 
 describe('files.exclude', () => {

vscode/src/codeReader/explorer/fileEntries.ts

@@ -12,9 +12,19 @@ export function sortEntries<T extends DirEntry>(entries: T[]): T[] {
     || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
 }
 
-/** 树上一行的 contextValue：菜单的 when 子句按它分工作区根、目录、文件。 */
-export function entryContext(entry: { isDirectory: boolean, isRoot: boolean }): 'root' | 'folder' | 'file' {
-  return entry.isRoot ? 'root' : entry.isDirectory ? 'folder' : 'file'
+/** 分组行（「暂存的更改」「更改」）的 contextValue：不挂任何行菜单。 */
+export const GROUP_CONTEXT = 'group'
+
+/**
+ * 树上一行的 contextValue：菜单的 when 子句按它分工作区根、目录、文件。
+ * 文件行可以带一个标记（「更改」区里能暂存的是 `file unstaged`），菜单按它给这些行多挂按钮；目录、根不带。
+ */
+export function entryContext(entry: { isDirectory: boolean, isRoot: boolean }, fileMarker?: string): string {
+  if (entry.isRoot)
+    return 'root'
+  if (entry.isDirectory)
+    return 'folder'
+  return fileMarker ? `file ${fileMarker}` : 'file'
 }
 
 /** `files.exclude` 的值：true 排除；false 不排除；`{ when }` 只在有对应的兄弟文件时排除。 */

vscode/src/codeReader/explorer/fileTree.ts

@@ -1,26 +1,55 @@
 import type { Event, TreeDataProvider, WorkspaceFolder } from 'vscode'
-import type { ChangedTree, FileChange } from '../review/changedFiles'
+import type { ChangedTree, FileChange } from './changedTree'
 import type { ExcludeSetting } from './fileEntries'
 import * as path from 'node:path'
 import { EventEmitter, FileType, ThemeIcon, TreeItem, TreeItemCollapsibleState, Uri, workspace } from 'vscode'
-import { CHANGE_STYLES } from '../review/changedFiles'
-import { createExcludeMatcher, entryContext, sortEntries } from './fileEntries'
+import { createExcludeMatcher, entryContext, GROUP_CONTEXT, sortEntries } from './fileEntries'
 
 export interface FileNode {
   uri: Uri
+  /** 这一行所在的根：工作区文件夹；只摆改动的文件时是那个根（仓库根、审查的工作副本） */
   folder: WorkspaceFolder
   isDirectory: boolean
   isRoot: boolean
-  /** 审查工单时这个文件在 PR 里怎么改的；普通的树、目录没有 */
+  /** 只摆改动的文件时所在的分组；普通的树没有 */
+  section?: ChangedSection
+  /** 只摆改动的文件时这个文件怎么改的；普通的树、目录没有 */
   change?: FileChange
 }
 
-/** 审查工单时树上摆什么：工作副本当唯一的根（folder），下面只有 PR 改过的文件（tree）。 */
-export interface ChangedFilesView {
+/** 只摆改动的文件时的一个根：folder 是根目录和根节点上的名字，tree 是它下面改动的文件。 */
+export interface ChangedRoot {
   folder: WorkspaceFolder
   tree: ChangedTree
 }
 
+/** 只摆改动的文件时的一个分组：有 label 时画一行分组（名字后面淡色的 description），各个根摆在它下面；没有 label 时各个根直接摆在最上面。 */
+export interface ChangedSection {
+  label?: string
+  description?: string
+  /** 这一组里文件行的 contextValue 带的标记（见 entryContext），菜单按它给这些行多挂按钮 */
+  fileMarker?: string
+  roots: readonly ChangedRoot[]
+}
+
+/** 只摆改动的文件时树上摆什么：一个或几个分组，每组下面每个根一个根节点，再往下只有改动的文件和通往它们的目录。 */
+export type ChangedFilesView = readonly ChangedSection[]
+
+/** 分组行（「暂存的更改」「更改」）。 */
+export interface GroupNode {
+  group: ChangedSection
+}
+
+/** 树上的一行：分组行，或者目录 / 文件。 */
+export type TreeNode = GroupNode | FileNode
+
+export function isGroupNode(node: TreeNode): node is GroupNode {
+  return 'group' in node
+}
+
+/** 删掉的文件那一行的悬停提示：它已经不在了，点了打不开。 */
+const DELETED_TOOLTIP = '已删除，没有内容可打开'
+
 /** 给树上的行添信息（比如文件注释）：每次画行时调 decorate，onDidChange 报出哪些 Uri 的行要重画。 */
 export interface FileTreeDecorator {
   readonly onDidChange: Event<readonly Uri[]>
@@ -33,18 +62,21 @@ const REFRESH_DELAY_MS = 300
 /**
  * 侧栏的工作区文件树：每个工作区文件夹一个根节点，只看和打开。
  * 节点用 resourceUri，图标、git 改动颜色都由 VS Code 按文件图标主题和 SCM 装饰自动加上。
- * 审查工单时换成只摆 PR 改过的文件（showChanges）：目录全部展开，删掉的文件列出来但打不开。
+ * 筛选时换成只摆改动的文件（showChanges：审查工单时 PR 改过的，未提交的更改时各仓库里没提交的，分「暂存的更改」「更改」两组）：
+ * 目录全部展开，删掉的文件列出来但打不开。
  */
-export class FileTreeProvider implements TreeDataProvider<FileNode> {
+export class FileTreeProvider implements TreeDataProvider<TreeNode> {
   /** undefined 是整棵树重画，数组是只重画这几行 */
-  private readonly changed = new EventEmitter<FileNode[] | undefined>()
-  readonly onDidChangeTreeData: Event<FileNode[] | undefined> = this.changed.event
+  private readonly changed = new EventEmitter<TreeNode[] | undefined>()
+  readonly onDidChangeTreeData: Event<TreeNode[] | undefined> = this.changed.event
   private readonly disposables: { dispose: () => unknown }[]
-  /** 按 Uri 记下交给 VS Code 的节点：只重画几行时要交回同一个对象，VS Code 按对象认行。 */
-  private readonly nodes = new Map<string, FileNode>()
+  /** 按分组、Uri 记下交给 VS Code 的节点：只重画几行时要交回同一个对象，VS Code 按对象认行；同一个文件可以在几个分组里各有一行。 */
+  private readonly nodes = new Map<ChangedSection | undefined, Map<string, FileNode>>()
   private timer: NodeJS.Timeout | undefined
-  /** 审查工单时只摆的那些文件；undefined 是普通的工作区文件树 */
+  /** 筛选时只摆的那些文件；undefined 是普通的工作区文件树 */
   private changes: ChangedFilesView | undefined
+  /** 筛选时每个分组的分组行 */
+  private groups: GroupNode[] = []
 
   /**
    * @param openCommand 点文件时执行的命令，参数是文件 Uri
@@ -74,24 +106,29 @@ export class FileTreeProvider implements TreeDataProvider<FileNode> {
     this.changed.fire(undefined)
   }
 
-  getTreeItem(node: FileNode): TreeItem {
+  getTreeItem(node: TreeNode): TreeItem {
+    if (isGroupNode(node))
+      return this.groupItem(node.group)
     const item = this.baseItem(node)
-    item.contextValue = entryContext(node)
+    item.contextValue = entryContext(node, node.section?.fileMarker)
     this.decorator.decorate(item, node)
     return item
   }
 
-  /** 换成只摆 PR 改过的文件（undefined 回到工作区文件树），整棵树重画。 */
+  /** 换成只摆改动的文件（undefined 回到工作区文件树），整棵树重画。 */
   showChanges(view: ChangedFilesView | undefined): void {
     this.changes = view
+    this.groups = (view ?? []).map(group => ({ group }))
     this.refresh()
   }
 
-  async getChildren(node?: FileNode): Promise<FileNode[]> {
+  async getChildren(node?: TreeNode): Promise<TreeNode[]> {
     if (this.changes)
-      return this.changedChildren(this.changes, node)
+      return this.changedChildren(node)
     if (!node)
       return (workspace.workspaceFolders ?? []).map(folder => this.nodeAt(folder.uri, folder, true, true))
+    if (isGroupNode(node))
+      return [] // 分组行只在只摆改动的文件时有
 
     let entries: [string, FileType][]
     try {
@@ -119,7 +156,7 @@ export class FileTreeProvider implements TreeDataProvider<FileNode> {
       const item = new TreeItem(node.uri, TreeItemCollapsibleState.None)
       item.iconPath = ThemeIcon.File
       if (node.change === 'D')
-        item.tooltip = CHANGE_STYLES.D.tooltip // 删掉的文件没有最新的版本可看，不挂打开的命令
+        item.tooltip = DELETED_TOOLTIP // 删掉的文件没有内容可看，不挂打开的命令
       else
         item.command = { command: this.openCommand, title: '打开', arguments: [node.uri] }
       return item
@@ -132,27 +169,49 @@ export class FileTreeProvider implements TreeDataProvider<FileNode> {
     return item
   }
 
-  private nodeAt(uri: Uri, folder: WorkspaceFolder, isDirectory: boolean, isRoot: boolean, change?: FileChange): FileNode {
+  /** 分组行：名字、后面淡色的 description，一直展开；contextValue 是 GROUP_CONTEXT，不挂行菜单。 */
+  private groupItem({ label, description }: ChangedSection): TreeItem {
+    const item = new TreeItem(label ?? '', TreeItemCollapsibleState.Expanded)
+    item.description = description
+    item.contextValue = GROUP_CONTEXT
+    return item
+  }
+
+  private nodeAt(uri: Uri, folder: WorkspaceFolder, isDirectory: boolean, isRoot: boolean, section?: ChangedSection, change?: FileChange): FileNode {
+    let nodes = this.nodes.get(section)
+    if (!nodes)
+      this.nodes.set(section, nodes = new Map())
     const id = uri.toString()
-    const known = this.nodes.get(id)
+    const known = nodes.get(id)
     if (known && known.folder === folder && known.isDirectory === isDirectory && known.isRoot === isRoot && known.change === change)
       return known
-    const node: FileNode = { uri, folder, isDirectory, isRoot, ...(change ? { change } : {}) }
-    this.nodes.set(id, node)
+    const node: FileNode = { uri, folder, isDirectory, isRoot, ...(section ? { section } : {}), ...(change ? { change } : {}) }
+    nodes.set(id, node)
     return node
   }
 
-  /** 审查工单时的一层：根下面是工作副本，再往下只有 PR 改过的文件和通往它们的目录。 */
-  private changedChildren({ folder, tree }: ChangedFilesView, node?: FileNode): FileNode[] {
+  /**
+   * 只摆改动的文件时的一层：最上面是分组行（没有名字的分组直接摆它的各个根），分组下面是各个根，
+   * 再往下只有改动的文件和通往它们的目录。
+   */
+  private changedChildren(node?: TreeNode): TreeNode[] {
     if (!node)
-      return [this.nodeAt(folder.uri, folder, true, true)]
+      return this.groups.flatMap((group): TreeNode[] => group.group.label !== undefined ? [group] : this.rootsOf(group.group))
+    if (isGroupNode(node))
+      return this.rootsOf(node.group)
+    const { folder, section } = node
+    const tree = section?.roots.find(root => root.folder === folder)?.tree
     const dir = path.posix.relative(folder.uri.path, node.uri.path)
-    return (tree.get(dir) ?? []).map(entry => this.nodeAt(Uri.joinPath(folder.uri, entry.path), folder, entry.isDirectory, false, entry.change))
+    return (tree?.get(dir) ?? []).map(entry => this.nodeAt(Uri.joinPath(folder.uri, entry.path), folder, entry.isDirectory, false, section, entry.change))
+  }
+
+  private rootsOf(section: ChangedSection): FileNode[] {
+    return section.roots.map(({ folder }) => this.nodeAt(folder.uri, folder, true, true, section))
   }
 
   /** 还没展开过的行不用管，展开时自然按最新的画。 */
   private redraw(uris: readonly Uri[]): void {
-    const nodes = uris.flatMap(uri => this.nodes.get(uri.toString()) ?? [])
+    const nodes = uris.flatMap(uri => [...this.nodes.values()].flatMap(known => known.get(uri.toString()) ?? []))
     if (nodes.length > 0)
       this.changed.fire(nodes)
   }

vscode/src/codeReader/explorer/rowMenus.test.ts

@@ -2,8 +2,9 @@ import { readFileSync } from 'node:fs'
 import * as path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { noteDecoration } from '../notes/noteItem'
+import { UNSTAGED_MARKER } from '../uncommitted/uncommittedFiles'
 import { COPY_COMMANDS } from './copyText'
-import { entryContext } from './fileEntries'
+import { entryContext, GROUP_CONTEXT } from './fileEntries'
 
 interface MenuItem { command?: string, submenu?: string, when: string, group?: string }
 interface Manifest {
@@ -23,6 +24,9 @@ const EDIT_NOTE = 'superpowers.codeReader.editNote'
 const file = entryContext({ isDirectory: false, isRoot: false })
 const folder = entryContext({ isDirectory: true, isRoot: false })
 const root = entryContext({ isDirectory: true, isRoot: true })
+/** 「未提交的更改」里「更改」组的文件行 */
+const unstaged = entryContext({ isDirectory: false, isRoot: false }, UNSTAGED_MARKER)
+const STAGE = 'superpowers.codeReader.stage'
 const noted = (context: string): string => noteDecoration(context, 'x', '注释')!.contextValue
 
 const orderOf = (item: MenuItem): number => Number(item.group?.split('@')[1] ?? 0)
@@ -60,6 +64,19 @@ describe('侧栏行尾按钮', () => {
     expect(itemsFor('view/item/context', 'inline', root)).toEqual([])
   })
 
+  it('「更改」组的文件行多一个「暂存」，排在最后；别的行都没有', () => {
+    expect(itemsFor('view/item/context', 'inline', unstaged)).toEqual([COPY_MENU, ADD_NOTE, STAGE])
+    expect(itemsFor('view/item/context', 'inline', noted(unstaged))).toEqual([COPY_MENU, EDIT_NOTE, STAGE])
+    for (const context of [file, folder, root, noted(file), noted(folder)])
+      expect(itemsFor('view/item/context', 'inline', context)).not.toContain(STAGE)
+  })
+
+  it('分组行（「暂存的更改」「更改」）什么按钮、菜单都没有', () => {
+    for (const group of ['inline', 'copy', 'notes'])
+      expect(itemsFor('view/item/context', group, GROUP_CONTEXT)).toEqual([])
+    expect(itemsFor(COPY_MENU, 'copy', GROUP_CONTEXT)).toEqual([])
+  })
+
   it('「复制」是带 copy 图标的子菜单（VS Code 画成点开的下拉按钮），注释按钮的图标是 note / edit', () => {
     expect(submenus.find(item => item.id === COPY_MENU)).toEqual({ id: COPY_MENU, label: '复制', icon: '$(copy)' })
     expect(commands.find(item => item.command === ADD_NOTE)?.icon).toBe('$(note)')
@@ -69,7 +86,7 @@ describe('侧栏行尾按钮', () => {
 
 describe('复制菜单', () => {
   it.each([COPY_MENU, 'view/item/context'])('%s：文件四项、文件夹没有「不带后缀」，有没有注释都一样', (menu) => {
-    for (const context of [file, noted(file)])
+    for (const context of [file, noted(file), unstaged, noted(unstaged)])
       expect(itemsFor(menu, 'copy', context)).toEqual(FILE_COPIES)
     for (const context of [folder, noted(folder)])
       expect(itemsFor(menu, 'copy', context)).toEqual(FOLDER_COPIES)
@@ -95,7 +112,7 @@ describe('复制菜单', () => {
 
 describe('右键菜单的注释', () => {
   it('没注释的目录 / 文件只有「添加注释」，有注释的只有「编辑注释」，工作区根没有', () => {
-    for (const context of [file, folder]) {
+    for (const context of [file, folder, unstaged]) {
       expect(itemsFor('view/item/context', 'notes', context)).toEqual([ADD_NOTE])
       expect(itemsFor('view/item/context', 'notes', noted(context))).toEqual([EDIT_NOTE])
     }
@@ -103,35 +120,65 @@ describe('右键菜单的注释', () => {
   })
 })
 
-describe('审查工单', () => {
-  const REVIEWING = 'superpowers.codeReader.reviewing'
+describe('筛选（审查工单、未提交的更改）', () => {
+  const FILTER = 'superpowers.codeReader.filter'
   const PICK = 'superpowers.codeReader.pickReviewIssue'
+  const UNCOMMITTED = 'superpowers.codeReader.showUncommitted'
+  const HIDE_TESTS = 'superpowers.codeReader.hideTests'
+  const SHOW_TESTS = 'superpowers.codeReader.showTests'
   const SHOW_ALL = 'superpowers.codeReader.showAllFiles'
+  const TESTS_HIDDEN = 'superpowers.codeReader.testsHidden'
+  const title = menus['view/title']
+    .filter(item => item.when.startsWith('view == superpowers.codeReader.files'))
+    .sort((a, b) => orderOf(a) - orderOf(b))
+  const whenOf = (command: string): string | undefined => title.find(item => item.command === command)?.when
 
-  it('标题栏：第一个「选工单」，审查时才有「显示全部」，然后「刷新」', () => {
-    const title = menus['view/title']
-      .filter(item => item.when.startsWith('view == superpowers.codeReader.files'))
-      .sort((a, b) => orderOf(a) - orderOf(b))
-    expect(title.map(item => item.command)).toEqual([PICK, SHOW_ALL, 'superpowers.codeReader.refresh'])
+  it('标题栏：选工单、未提交的更改、隐藏 / 显示测试文件、开着筛选时才有的「显示全部」、刷新', () => {
+    expect(title.map(item => item.command)).toEqual([PICK, UNCOMMITTED, HIDE_TESTS, SHOW_TESTS, SHOW_ALL, 'superpowers.codeReader.refresh'])
     expect(title.every(item => item.group?.startsWith('navigation'))).toBe(true)
-    expect(title.find(item => item.command === SHOW_ALL)?.when).toContain(`&& ${REVIEWING}`)
-    expect(title.find(item => item.command === PICK)?.when).not.toContain(REVIEWING)
+    expect(whenOf(SHOW_ALL)).toBe(`view == superpowers.codeReader.files && ${FILTER}`)
+    for (const command of [PICK, UNCOMMITTED])
+      expect(whenOf(command)).not.toContain(FILTER)
   })
 
-  it('按钮的字和图标：选工单 git-pull-request，显示全部 close', () => {
+  it('隐藏 / 显示测试文件只在未提交的更改时有，按是否隐藏着换着显示', () => {
+    expect(whenOf(HIDE_TESTS)).toBe(`view == superpowers.codeReader.files && ${FILTER} == uncommitted && !${TESTS_HIDDEN}`)
+    expect(whenOf(SHOW_TESTS)).toBe(`view == superpowers.codeReader.files && ${FILTER} == uncommitted && ${TESTS_HIDDEN}`)
+    const palette = new Map(menus.commandPalette.map(item => [item.command, item.when]))
+    expect(palette.get(HIDE_TESTS)).toBe(`${FILTER} == uncommitted && !${TESTS_HIDDEN}`)
+    expect(palette.get(SHOW_TESTS)).toBe(`${FILTER} == uncommitted && ${TESTS_HIDDEN}`)
+  })
+
+  it('「暂存」只在未提交的更改时挂在「更改」组的文件行上，命令面板里藏起来', () => {
+    const stage = menus['view/item/context'].filter(item => item.command === STAGE)
+    expect(stage).toHaveLength(1)
+    expect(stage[0].when).toContain(`${FILTER} == uncommitted`)
+    expect(menus.commandPalette.find(item => item.command === STAGE)?.when).toBe('false')
+  })
+
+  it('按钮的字和图标', () => {
     expect(commands.find(item => item.command === PICK)).toMatchObject({ title: '选工单', icon: '$(git-pull-request)' })
+    expect(commands.find(item => item.command === UNCOMMITTED)).toMatchObject({ title: '未提交的更改', icon: '$(git-commit)' })
+    expect(commands.find(item => item.command === HIDE_TESTS)).toMatchObject({ title: '隐藏测试文件', icon: '$(beaker-stop)' })
+    expect(commands.find(item => item.command === SHOW_TESTS)).toMatchObject({ title: '显示测试文件', icon: '$(beaker)' })
+    expect(commands.find(item => item.command === STAGE)).toMatchObject({ title: '暂存', icon: '$(add)' })
     expect(commands.find(item => item.command === SHOW_ALL)).toMatchObject({ title: '显示全部', icon: '$(close)' })
   })
 
-  it('审查时行上没有注释按钮（工作副本里不记注释），复制照旧', () => {
+  it('审查时行上没有注释按钮（工作副本里不记注释），未提交的更改时照常有；复制照旧', () => {
     const noteItems = menus['view/item/context'].filter(item => item.command === ADD_NOTE || item.command === EDIT_NOTE)
     expect(noteItems.length).toBeGreaterThan(0)
-    expect(noteItems.every(item => item.when.includes(`!${REVIEWING}`))).toBe(true)
+    expect(noteItems.every(item => item.when.includes(`${FILTER} != review`))).toBe(true)
     const copyItems = menus['view/item/context'].filter(item => item.submenu === COPY_MENU || item.command?.startsWith('superpowers.codeReader.copy'))
-    expect(copyItems.some(item => item.when.includes(REVIEWING))).toBe(false)
+    expect(copyItems.some(item => item.when.includes(FILTER))).toBe(false)
   })
 
-  it('命令面板里「显示全部」只在审查时有', () => {
-    expect(menus.commandPalette.find(item => item.command === SHOW_ALL)?.when).toBe(REVIEWING)
+  it('命令面板里「显示全部」只在开着筛选时有', () => {
+    expect(menus.commandPalette.find(item => item.command === SHOW_ALL)?.when).toBe(FILTER)
+  })
+
+  it('只用一个上下文键，旧的 superpowers.codeReader.reviewing 不再出现', () => {
+    const whens = Object.values(menus).flat().map(item => item.when)
+    expect(whens.some(when => when.includes('superpowers.codeReader.reviewing'))).toBe(false)
   })
 })

vscode/src/codeReader/explorer/treeFilters.ts

@@ -0,0 +1,76 @@
+import type { TreeView } from 'vscode'
+import type { FileTreeProvider, TreeNode } from './fileTree'
+import { commands, Disposable } from 'vscode'
+
+/** 上下文键：侧栏树开着哪种筛选，没设是全部文件。标题栏的「显示全部」、行上的注释按钮按它显示 / 藏起来。 */
+const FILTER_CONTEXT = 'superpowers.codeReader.filter'
+
+/** 侧栏树的筛选：review 审查工单（只摆 PR 改过的文件），uncommitted 未提交的更改（只摆各仓库里没提交的文件）。 */
+export type TreeFilterKind = 'review' | 'uncommitted'
+
+/** 一种筛选。 */
+export interface TreeFilter {
+  /** 标题栏的「刷新」：重读这种筛选摆的文件 */
+  reload: () => Promise<void>
+  /** 「显示全部」或换成别的筛选：不再筛、不再记着，正在进的作废 */
+  exit: () => Promise<void>
+}
+
+/**
+ * 侧栏树上的几种筛选，同时只开一种：开一种时别的都退出；上下文键跟着开着的那种。
+ * 筛选开起来时自己换上树、标题后面的字（description）、标题下面的一行（message）；退出时由这里回到工作区文件树。
+ */
+export class TreeFilters {
+  private readonly filters: TreeFilter[] = []
+  private current: TreeFilter | undefined
+
+  constructor(private readonly files: FileTreeProvider, private readonly view: TreeView<TreeNode>) {}
+
+  /** 开着的那种筛选；没开是全部文件 */
+  get active(): TreeFilter | undefined {
+    return this.current
+  }
+
+  /** 登记一种筛选：别的筛选开起来时让它退出。 */
+  add(filter: TreeFilter): void {
+    this.filters.push(filter)
+  }
+
+  /**
+   * 视图第一次露出来时调 run（已经露着就马上调）：筛选接着上次的，没打开侧栏就不去拉 PR、读 git。
+   * @returns 还没露出来时盯着的监听
+   */
+  whenShown(run: () => void): Disposable {
+    if (this.view.visible) {
+      run()
+      return Disposable.from()
+    }
+    const shown = this.view.onDidChangeVisibility(({ visible }) => {
+      if (!visible)
+        return
+      shown.dispose()
+      run()
+    })
+    return shown
+  }
+
+  /** filter 换上侧栏树之前调：别的筛选都退出（同步的部分在这里就做完了，调用方紧接着换上自己的），上下文键设成 kind。 */
+  async enter(filter: TreeFilter, kind: TreeFilterKind): Promise<void> {
+    this.current = filter
+    await Promise.all([
+      ...this.filters.filter(other => other !== filter).map(other => other.exit()),
+      commands.executeCommand('setContext', FILTER_CONTEXT, kind),
+    ])
+  }
+
+  /** filter 退出时调：它开着就回到工作区文件树，清掉标题后面的字、标题下面的一行和上下文键；没开着（还在进、或已经换成别的）什么都不动。 */
+  async leave(filter: TreeFilter): Promise<void> {
+    if (this.current !== filter)
+      return
+    this.current = undefined
+    this.files.showChanges(undefined)
+    this.view.description = undefined
+    this.view.message = undefined
+    await commands.executeCommand('setContext', FILTER_CONTEXT, undefined)
+  }
+}

vscode/src/codeReader/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionContext, Uri } from 'vscode'
 import type { CodeReaderApi, RuleLocation, RuleReference } from './contract'
+import type { FileNode } from './explorer/fileTree'
 import type { IndexedName } from './nameResolution'
 import { commands, window, workspace } from 'vscode'
 import { logger } from '../logging/logger'
@@ -12,6 +13,7 @@ import { PREVIEW_VIEW_TYPE, PreviewEditorProvider } from './editor/previewEditor
 import { showPreview, showSource } from './editor/switchEditor'
 import { registerCopyCommands } from './explorer/copyCommands'
 import { FileTreeProvider } from './explorer/fileTree'
+import { TreeFilters } from './explorer/treeFilters'
 import { createBashAdapter } from './languages/bash'
 import { createDockerfileAdapter } from './languages/dockerfile'
 import { createPythonAdapter } from './languages/python'
@@ -33,6 +35,7 @@ import { bashZhTranslator } from './translators/bashZh'
 import { dockerfileZhTranslator } from './translators/dockerfileZh'
 import { pythonZhTranslator } from './translators/pythonZh'
 import { typescriptZhTranslator } from './translators/typescriptZh'
+import { UncommittedMode } from './uncommitted/uncommittedMode'
 import { workspaceIndexHost } from './workspaceFiles'
 import { WorkspaceIndexes } from './workspaceIndex'
 
@@ -62,7 +65,7 @@ async function openFile(uri: Uri, registry: CodeReaderRegistry): Promise<void> {
 }
 
 /**
- * 接入代码阅读：注册表、侧栏文件树（复制、文件注释、按审查工单只看 PR 改过的文件）、预览编辑器（含问 AI）、编辑器右上角的「预览 / 编辑」切换。
+ * 接入代码阅读：注册表、侧栏文件树（复制、文件注释、筛选：按审查工单只看 PR 改过的文件、只看未提交的更改）、预览编辑器（含问 AI）、编辑器右上角的「预览 / 编辑」切换。
  * 内置的语言插件、翻译插件、库规则和命令规则与其他扩展一样通过返回的 API 注册。
  */
 export function registerCodeReader(context: ExtensionContext): CodeReaderApi {
@@ -85,7 +88,9 @@ export function registerCodeReader(context: ExtensionContext): CodeReaderApi {
   const notes = new FileNotes()
   const files = new FileTreeProvider(OPEN_COMMAND, notes)
   const view = window.createTreeView(FILES_VIEW, { treeDataProvider: files, showCollapseAll: true })
-  const review = new ReviewMode(context, FILES_VIEW, view, files)
+  const filters = new TreeFilters(files, view)
+  const review = new ReviewMode(context, FILES_VIEW, view, files, filters)
+  const uncommitted = new UncommittedMode(context, FILES_VIEW, view, files, filters)
 
   context.subscriptions.push(
     qa,
@@ -101,10 +106,16 @@ export function registerCodeReader(context: ExtensionContext): CodeReaderApi {
     files,
     view,
     review,
-    // 审查工单时刷新是重读 PR 改过的文件，平时是重读工作区文件树
-    commands.registerCommand('superpowers.codeReader.refresh', () => review.active ? review.reload() : files.refresh()),
+    uncommitted,
+    // 开着筛选时刷新是重读它摆的文件（PR 改过的、git 状态），平时是重读工作区文件树
+    commands.registerCommand('superpowers.codeReader.refresh', () => filters.active ? filters.active.reload() : files.refresh()),
     commands.registerCommand('superpowers.codeReader.pickReviewIssue', () => review.pick()),
-    commands.registerCommand('superpowers.codeReader.showAllFiles', () => review.exit()),
+    commands.registerCommand('superpowers.codeReader.showUncommitted', () => uncommitted.enter()),
+    commands.registerCommand('superpowers.codeReader.hideTests', () => uncommitted.setTestsHidden(true)),
+    commands.registerCommand('superpowers.codeReader.showTests', () => uncommitted.setTestsHidden(false)),
+    // 「更改」组文件行上的按钮传来的是这一行的节点
+    commands.registerCommand('superpowers.codeReader.stage', (node?: FileNode) => uncommitted.stage(node)),
+    commands.registerCommand('superpowers.codeReader.showAllFiles', () => filters.active?.exit()),
     commands.registerCommand(OPEN_COMMAND, (uri: Uri) => openFile(uri, registry)),
     // 标题栏按钮传来的是 (文件 Uri, { groupId })，原样转给 VS Code 定位是哪一组的哪个标签
     commands.registerCommand('superpowers.codeReader.showPreview', (...args: unknown[]) => showPreview(previews, args)),

vscode/src/codeReader/notes/fileNotes.ts

@@ -1,8 +1,7 @@
 import type { Disposable, TreeItem } from 'vscode'
 import type { FileNode, FileTreeDecorator } from '../explorer/fileTree'
 import { MarkdownString } from 'vscode'
-import { FolderStore } from '../folderStore'
-import { toPathKey } from '../pathMap'
+import { FolderStore, locate } from '../folderStore'
 import { noteDecoration } from './noteItem'
 import { withNote } from './noteMap'
 import { NOTES_FILE } from './store'
@@ -10,6 +9,7 @@ import { NOTES_FILE } from './store'
 /**
  * 读代码时给目录 / 文件记的注释。
  * 盘上每个工作区文件夹一份 `.spx/code-notes.json`；内存里留一份给侧栏树画行时同步取用。
+ * 注释记在文件所在的工作区文件夹里，和树从哪个根摆下来（工作区文件夹、仓库根）无关；工作区外面的文件（审查的工作副本）不记。
  * 在 VS Code 里改名、挪位置，注释跟着走；删掉就一起删。外部改了文件（git pull、手改）按文件重读（见 FolderStore）。
  */
 export class FileNotes implements FileTreeDecorator, Disposable {
@@ -17,15 +17,15 @@ export class FileNotes implements FileTreeDecorator, Disposable {
   /** 注释变了的那些行 */
   readonly onDidChange = this.store.onDidChange
 
-  /** 这一行的注释；工作区根节点不记注释。 */
+  /** 这一行的注释；工作区文件夹本身不记注释。 */
   noteOf(node: FileNode): string | undefined {
-    const key = toPathKey(node.folder.uri.path, node.uri.path)
-    return key === undefined ? undefined : this.store.get(node.folder, key)
+    const at = locate(node.uri)
+    return at && this.store.get(at.folder, at.key)
   }
 
   decorate(item: TreeItem, node: FileNode): void {
-    const key = toPathKey(node.folder.uri.path, node.uri.path)
-    const decoration = key === undefined ? undefined : noteDecoration(item.contextValue ?? '', key, this.noteOf(node))
+    const at = locate(node.uri)
+    const decoration = at && noteDecoration(item.contextValue ?? '', at.key, this.store.get(at.folder, at.key))
     if (!decoration)
       return
     item.description = decoration.description
@@ -35,9 +35,9 @@ export class FileNotes implements FileTreeDecorator, Disposable {
 
   /** 保存注释：去掉首尾空白，空的就删掉这条。 */
   async save(node: FileNode, text: string): Promise<void> {
-    const key = toPathKey(node.folder.uri.path, node.uri.path)
-    if (key !== undefined)
-      await this.store.update(node.folder, notes => withNote(notes, key, text))
+    const at = locate(node.uri)
+    if (at)
+      await this.store.update(at.folder, notes => withNote(notes, at.key, text))
   }
 
   dispose(): void {

vscode/src/codeReader/review/changeDecorations.ts

@@ -1,5 +1,5 @@
 import type { Disposable, Event, FileDecorationProvider, Uri } from 'vscode'
-import type { FileChange } from './changedFiles'
+import type { FileChange } from '../explorer/changedTree'
 import { EventEmitter, FileDecoration, ThemeColor } from 'vscode'
 import { CHANGE_STYLES } from './changedFiles'
 

vscode/src/codeReader/review/changedFiles.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { buildChangedTree, CHANGE_STYLES, changeOf } from './changedFiles'
+import { CHANGE_STYLES, changeOf } from './changedFiles'
 
 describe('改动状态', () => {
   it('新增 A、删除 D，别的（改名、复制、改了、没改）都算修改 M', () => {
@@ -16,65 +16,3 @@ describe('改动状态', () => {
     expect(CHANGE_STYLES.D.tooltip).toBe('PR 里删掉了')
   })
 })
-
-describe('改动的文件树', () => {
-  // 原型「审查 · 改动的文件」里的 6 个文件，外加一个改名的
-  const files = [
-    { path: 'backend/src/luffy_agent/user/routes.py', status: 'changed' },
-    { path: 'backend/tests/user/test_avatar.py', status: 'added' },
-    { path: 'backend/src/luffy_agent/core/storage.py', status: 'changed' },
-    { path: 'backend/src/luffy_agent/user/legacy_profile.py', status: 'deleted' },
-    { path: 'backend/src/luffy_agent/user/services.py', status: 'changed' },
-    { path: 'backend/src/luffy_agent/user/schemas.py', status: 'renamed' },
-  ]
-  const tree = buildChangedTree(files)
-  const names = (dir: string): string[] => (tree.get(dir) ?? []).map(entry => entry.name)
-
-  it('目录层级照留，每层只有通往改过的文件的目录', () => {
-    expect(names('')).toEqual(['backend'])
-    expect(names('backend')).toEqual(['src', 'tests'])
-    expect(names('backend/src')).toEqual(['luffy_agent'])
-    expect(names('backend/src/luffy_agent')).toEqual(['core', 'user'])
-    expect(names('backend/src/luffy_agent/core')).toEqual(['storage.py'])
-    expect(names('backend/tests/user')).toEqual(['test_avatar.py'])
-  })
-
-  it('同一层里的文件按名字排，带着各自的改动和相对仓库根的路径', () => {
-    expect(tree.get('backend/src/luffy_agent/user')).toEqual([
-      { name: 'legacy_profile.py', path: 'backend/src/luffy_agent/user/legacy_profile.py', isDirectory: false, change: 'D' },
-      { name: 'routes.py', path: 'backend/src/luffy_agent/user/routes.py', isDirectory: false, change: 'M' },
-      { name: 'schemas.py', path: 'backend/src/luffy_agent/user/schemas.py', isDirectory: false, change: 'M' },
-      { name: 'services.py', path: 'backend/src/luffy_agent/user/services.py', isDirectory: false, change: 'M' },
-    ])
-  })
-
-  it('目录没有改动，路径相对仓库根', () => {
-    expect(tree.get('backend')).toEqual([
-      { name: 'src', path: 'backend/src', isDirectory: true },
-      { name: 'tests', path: 'backend/tests', isDirectory: true },
-    ])
-  })
-
-  it('目录在前、文件在后，名字不区分大小写，和普通的树一样', () => {
-    const mixed = buildChangedTree([
-      { path: 'README.md', status: 'changed' },
-      { path: 'src/a.ts', status: 'added' },
-      { path: 'Docs/b.md', status: 'added' },
-      { path: 'package.json', status: 'changed' },
-    ])
-    expect(mixed.get('')?.map(entry => entry.name)).toEqual(['Docs', 'src', 'package.json', 'README.md'])
-  })
-
-  it('文件换成同名目录（删掉 a、新加 a/b）两项都留着', () => {
-    const replaced = buildChangedTree([{ path: 'a', status: 'deleted' }, { path: 'a/b', status: 'added' }])
-    expect(replaced.get('')).toEqual([
-      { name: 'a', path: 'a', isDirectory: true },
-      { name: 'a', path: 'a', isDirectory: false, change: 'D' },
-    ])
-    expect(replaced.get('a')?.map(entry => entry.change)).toEqual(['A'])
-  })
-
-  it('没有改动的文件时根下面是空的', () => {
-    expect(buildChangedTree([]).get('')).toEqual([])
-  })
-})

vscode/src/codeReader/review/changedFiles.ts

@@ -1,8 +1,4 @@
-import type { DirEntry } from '../explorer/fileEntries'
-import { sortEntries } from '../explorer/fileEntries'
-
-/** PR 里一个文件怎么改的，照 VS Code 源代码管理的写法：修改 M、新增 A、删除 D。 */
-export type FileChange = 'M' | 'A' | 'D'
+import type { FileChange } from '../explorer/changedTree'
 
 /**
  * Gitea 给的改动状态 → M / A / D。Gitea 的状态有 added、deleted、changed、renamed、copied、unchanged：
@@ -12,48 +8,9 @@ export function changeOf(status: string): FileChange {
   return status === 'added' ? 'A' : status === 'deleted' ? 'D' : 'M'
 }
 
-/** 各种改动在侧栏上的样子：颜色用 VS Code 源代码管理的 git 装饰色（主题色 id），徽标就是字母本身。 */
+/** 审查时各种改动在侧栏上的样子：颜色用 VS Code 源代码管理的 git 装饰色（主题色 id），徽标就是字母本身。 */
 export const CHANGE_STYLES: Record<FileChange, { color: string, tooltip: string }> = {
   M: { color: 'gitDecoration.modifiedResourceForeground', tooltip: 'PR 里改了' },
   A: { color: 'gitDecoration.addedResourceForeground', tooltip: 'PR 里新加的' },
   D: { color: 'gitDecoration.deletedResourceForeground', tooltip: 'PR 里删掉了' },
 }
-
-/** 改动的文件树上的一项。 */
-export interface ChangedEntry extends DirEntry {
-  /** 相对仓库根，`/` 分隔 */
-  path: string
-  /** 文件怎么改的；目录没有 */
-  change?: FileChange
-}
-
-/** 按目录分好的改动：键是目录相对仓库根的路径（仓库根是 `''`），值是它下面一层的目录和文件。 */
-export type ChangedTree = ReadonlyMap<string, readonly ChangedEntry[]>
-
-/**
- * PR 改过的文件 → 按目录分好的树：只有改过的文件和通往它们的目录，目录层级照留，
- * 每层的排法和侧栏普通的树一样（目录在前、名字不区分大小写）。
- * 同一路径上一个文件换成了同名目录（删掉文件 `a`、新加 `a/b`）时两项都留着。
- */
-export function buildChangedTree(files: readonly { path: string, status: string }[]): ChangedTree {
-  const levels = new Map<string, Map<string, ChangedEntry>>([['', new Map()]])
-  const add = (dir: string, entry: ChangedEntry): void => {
-    let level = levels.get(dir)
-    if (!level)
-      levels.set(dir, level = new Map())
-    const key = `${entry.isDirectory ? 'dir' : 'file'}:${entry.name}`
-    if (!level.has(key))
-      level.set(key, entry)
-  }
-  for (const file of files) {
-    const segments = file.path.split('/')
-    segments.forEach((name, index) => {
-      const dir = segments.slice(0, index).join('/')
-      const path = segments.slice(0, index + 1).join('/')
-      add(dir, index === segments.length - 1
-        ? { name, path, isDirectory: false, change: changeOf(file.status) }
-        : { name, path, isDirectory: true })
-    })
-  }
-  return new Map([...levels].map(([dir, level]) => [dir, sortEntries([...level.values()])]))
-}

vscode/src/codeReader/review/reviewMode.ts

@@ -2,13 +2,15 @@ import type { Disposable, ExtensionContext, QuickPickItem, TreeView, WorkspaceFo
 import type { PrFileDto } from '../../gitea/api'
 import type { RepoContext } from '../../gitea/repoContext'
 import type { Issue } from '../../gitea/types'
-import type { FileNode, FileTreeProvider } from '../explorer/fileTree'
+import type { FileTreeProvider, TreeNode } from '../explorer/fileTree'
+import type { TreeFilter, TreeFilters } from '../explorer/treeFilters'
 import type { FileCount } from './pickList'
 import * as path from 'node:path'
-import { commands, QuickPickItemKind, Uri, window, workspace } from 'vscode'
+import { QuickPickItemKind, Uri, window, workspace } from 'vscode'
 import { logger } from '../../logging/logger'
+import { buildChangedTree } from '../explorer/changedTree'
 import { ChangeDecorations } from './changeDecorations'
-import { buildChangedTree, changeOf } from './changedFiles'
+import { changeOf } from './changedFiles'
 import { countingFiles, pickEntries, pickItemText, pickRows, withFileCount } from './pickList'
 import { columnLabel, REVIEW_COLUMNS_TEXT, reviewableIssue, reviewablePullRequest, reviewDescription, reviewMessage } from './reviewRules'
 import { loadIssue, loadPullRequest, loadPullRequestFiles, requireRepo, reviewCandidateIssues } from './reviewSource'
@@ -16,8 +18,6 @@ import { localWorktree, prepareWorktree } from './reviewWorktree'
 
 /** workspaceState：正在审查的工单号，重开窗口接着审查。 */
 const REVIEW_ISSUE_KEY = 'superpowers.codeReader.reviewIssue'
-/** 上下文键：正在审查工单。标题栏的「显示全部」、行上的注释按钮按它显示 / 藏起来。 */
-const REVIEWING_CONTEXT = 'superpowers.codeReader.reviewing'
 
 /**
  * 怎么进的审查，决定不能审查、出错时怎么收场：
@@ -45,8 +45,9 @@ function errorText(err: unknown): string {
 /**
  * 侧栏按审查工单筛文件：「选工单」列出看板「审查」「进行中」列里能审查的工单，选中后树里只剩这张工单的 PR 改过的文件（按改动着色），
  * 点开的是本机这张工单的工作副本里 PR 最新的代码；「显示全部」回到工作区文件树。选的工单按工作区记住。
+ * 和别的筛选（未提交的更改）互斥，见 TreeFilters。
  */
-export class ReviewMode implements Disposable {
+export class ReviewMode implements TreeFilter, Disposable {
   private readonly decorations = new ChangeDecorations()
   private readonly disposables: Disposable[]
   /** 正在审查的工单号 */
@@ -58,27 +59,16 @@ export class ReviewMode implements Disposable {
   constructor(
     private readonly context: ExtensionContext,
     private readonly viewId: string,
-    private readonly view: TreeView<FileNode>,
+    private readonly view: TreeView<TreeNode>,
     private readonly files: FileTreeProvider,
+    private readonly filters: TreeFilters,
   ) {
-    this.disposables = [this.decorations, window.registerFileDecorationProvider(this.decorations)]
-    // 视图第一次露出来时才接着上次的审查：没打开侧栏就不去拉 PR、动工作副本
-    if (view.visible) {
-      void this.restore()
-    }
-    else {
-      const shown = view.onDidChangeVisibility(({ visible }) => {
-        if (!visible)
-          return
-        shown.dispose()
-        void this.restore()
-      })
-      this.disposables.push(shown)
-    }
-  }
-
-  get active(): boolean {
-    return this.reviewing !== undefined
+    filters.add(this)
+    this.disposables = [
+      this.decorations,
+      window.registerFileDecorationProvider(this.decorations),
+      filters.whenShown(() => void this.restore()),
+    ]
   }
 
   /**
@@ -156,16 +146,13 @@ export class ReviewMode implements Disposable {
       : []))
   }
 
-  /** 「显示全部」：回到工作区文件树，不再记着这张工单。 */
+  /** 「显示全部」或换成别的筛选：不再审查、不再记着这张工单，正在进的审查作废；正审查着的回到工作区文件树。 */
   async exit(): Promise<void> {
     this.generation++
     this.reviewing = undefined
-    this.files.showChanges(undefined)
     this.decorations.show([])
-    this.view.description = undefined
-    this.view.message = undefined
     await Promise.all([
-      commands.executeCommand('setContext', REVIEWING_CONTEXT, false),
+      this.filters.leave(this),
       this.context.workspaceState.update(REVIEW_ISSUE_KEY, undefined),
     ])
   }
@@ -261,13 +248,15 @@ export class ReviewMode implements Disposable {
     const root = Uri.file(worktree)
     // 工作副本当根，名字照写工作区文件夹的：看的还是这个仓库，只是 PR 最新的代码
     const folder: WorkspaceFolder = { uri: root, name: workspace.workspaceFolders?.[0]?.name ?? path.basename(worktree), index: 0 }
+    const changes = files.map(file => ({ path: file.path, change: changeOf(file.status) }))
+    const entering = this.filters.enter(this, 'review')
     this.reviewing = issue.number
-    this.files.showChanges({ folder, tree: buildChangedTree(files) })
-    this.decorations.show(files.map(file => ({ uri: Uri.joinPath(root, file.path), change: changeOf(file.status) })))
+    this.files.showChanges([{ roots: [{ folder, tree: buildChangedTree(changes) }] }])
+    this.decorations.show(changes.map(file => ({ uri: Uri.joinPath(root, file.path), change: file.change })))
     this.view.description = reviewDescription(issue.number)
     this.view.message = reviewMessage(issue, pr, files.length)
     await Promise.all([
-      commands.executeCommand('setContext', REVIEWING_CONTEXT, true),
+      entering,
       this.context.workspaceState.update(REVIEW_ISSUE_KEY, issue.number),
     ])
   }

vscode/src/codeReader/uncommitted/testFiles.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { isTestFile } from './testFiles'
+
+describe('测试文件', () => {
+  it('路径上有一层是测试目录的都算（不分大小写）', () => {
+    for (const path of [
+      'test/helpers.ts',
+      'backend/tests/user/factories.py',
+      'src/__tests__/App.tsx',
+      'src/__mocks__/axios.ts',
+      'src/components/__snapshots__/Button.test.tsx.snap',
+      'pkg/parser/testdata/input.json',
+      'Tests/AppTests/AppTests.swift',
+      'jetbrains/src/test/kotlin/PluginTest.kt',
+    ])
+      expect(isTestFile(path), path).toBe(true)
+  })
+
+  it('python：test_*.py、*_test.py、conftest.py', () => {
+    for (const path of ['backend/test_avatar.py', 'backend/avatar_test.py', 'backend/conftest.py', 'conftest.py'])
+      expect(isTestFile(path), path).toBe(true)
+  })
+
+  it('js / ts：*.test.*、*.spec.*', () => {
+    for (const path of ['src/a.test.ts', 'src/a.spec.tsx', 'src/a.test.js', 'src/a.spec.jsx', 'src/a.test.mjs', 'src/a.spec.cts', 'src/codeReader/review/changedFiles.test.ts'])
+      expect(isTestFile(path), path).toBe(true)
+  })
+
+  it('go：*_test.go', () => {
+    expect(isTestFile('pkg/server/handler_test.go')).toBe(true)
+  })
+
+  it('普通文件不算：名字里带 test 但不是约定的写法、目录名只是包含 test 的、别的扩展名的 spec', () => {
+    for (const path of [
+      'src/testing.ts',
+      'src/latest.py',
+      'src/contest.py',
+      'src/test.ts',
+      'src/attestation/verify.go',
+      'testing/utils.ts',
+      'src/tests.config.ts',
+      'docs/openapi.spec.yaml',
+      'docs/feature.spec.md',
+      'src/handler_test.ts',
+      'vitest.config.ts',
+      'src/testFiles.ts',
+    ])
+      expect(isTestFile(path), path).toBe(false)
+  })
+
+  it('测试目录只看目录，同名的文件不算', () => {
+    expect(isTestFile('scripts/test')).toBe(false)
+    expect(isTestFile('tests')).toBe(false)
+  })
+})

vscode/src/codeReader/uncommitted/testFiles.ts

@@ -0,0 +1,27 @@
+/**
+ * 整个目录都算测试的目录名（不分大小写）：测试目录（含 Swift 的 `Tests`）、Jest 的 mock 和快照、Go 的测试数据。
+ */
+const TEST_DIRS = new Set(['test', 'tests', '__tests__', '__mocks__', '__snapshots__', 'testdata'])
+
+/**
+ * 按文件名认的测试文件：Python 的 `test_*.py`、`*_test.py`、`conftest.py`，
+ * JS / TS 的 `*.test.*`、`*.spec.*`（js、jsx、ts、tsx 和 m / c 开头的变体），Go 的 `*_test.go`。
+ */
+const TEST_FILE_NAMES: readonly RegExp[] = [
+  /^test_.+\.py$/,
+  /^.+_test\.py$/,
+  /^conftest\.py$/,
+  /^.+\.(?:test|spec)\.[cm]?[jt]sx?$/,
+  /^.+_test\.go$/,
+]
+
+/**
+ * 是不是测试文件：路径上有一层目录是测试目录，或者文件名照测试文件的约定起。
+ * 「未提交的更改」里隐藏测试文件时按它剔除。
+ * @param path 相对仓库根，`/` 分隔
+ */
+export function isTestFile(path: string): boolean {
+  const segments = path.split('/')
+  const name = segments.pop() ?? ''
+  return segments.some(dir => TEST_DIRS.has(dir.toLowerCase())) || TEST_FILE_NAMES.some(pattern => pattern.test(name))
+}

vscode/src/codeReader/uncommitted/uncommittedFiles.test.ts

@@ -0,0 +1,190 @@
+import type { GitStatus } from '../../git/gitApi'
+import type { ChangeGroups } from './uncommittedFiles'
+import { describe, expect, it } from 'vitest'
+import { GIT_STATUS } from '../../git/gitApi'
+import { changeOfGitStatus, uncommittedDescription, uncommittedFiles, uncommittedMessage, uncommittedRoots, withoutTestFiles, workspaceOrder } from './uncommittedFiles'
+
+const at = (path: string, status: GitStatus): { uri: { path: string }, status: GitStatus } => ({ uri: { path }, status })
+
+function groups(parts: Partial<ChangeGroups>): ChangeGroups {
+  return { mergeChanges: [], indexChanges: [], workingTreeChanges: [], untrackedChanges: [], ...parts }
+}
+
+describe('git 状态 → 改动', () => {
+  it('未跟踪、新增（含 add -N、合并时新加的）算 A', () => {
+    for (const status of [GIT_STATUS.UNTRACKED, GIT_STATUS.INDEX_ADDED, GIT_STATUS.INTENT_TO_ADD, GIT_STATUS.ADDED_BY_US, GIT_STATUS.ADDED_BY_THEM, GIT_STATUS.BOTH_ADDED])
+      expect(changeOfGitStatus(status)).toBe('A')
+  })
+
+  it('删除（暂存的、没暂存的、合并时双方都删的）算 D', () => {
+    for (const status of [GIT_STATUS.INDEX_DELETED, GIT_STATUS.DELETED, GIT_STATUS.BOTH_DELETED])
+      expect(changeOfGitStatus(status)).toBe('D')
+  })
+
+  it('别的都算 M：改了、改名、复制、改类型、合并冲突（一方删一方改的文件还在工作区里）', () => {
+    for (const status of [
+      GIT_STATUS.INDEX_MODIFIED,
+      GIT_STATUS.MODIFIED,
+      GIT_STATUS.INDEX_RENAMED,
+      GIT_STATUS.INTENT_TO_RENAME,
+      GIT_STATUS.INDEX_COPIED,
+      GIT_STATUS.TYPE_CHANGED,
+      GIT_STATUS.BOTH_MODIFIED,
+      GIT_STATUS.DELETED_BY_US,
+      GIT_STATUS.DELETED_BY_THEM,
+    ])
+      expect(changeOfGitStatus(status)).toBe('M')
+  })
+})
+
+describe('一个仓库里没提交的文件，分两区', () => {
+  it('暂存的更改是暂存区的；更改是合并冲突、没暂存、未跟踪的；路径相对仓库根', () => {
+    expect(uncommittedFiles('/repo', groups({
+      mergeChanges: [at('/repo/conflict.ts', GIT_STATUS.BOTH_MODIFIED)],
+      indexChanges: [at('/repo/src/staged.ts', GIT_STATUS.INDEX_MODIFIED), at('/repo/src/added.ts', GIT_STATUS.INDEX_ADDED)],
+      workingTreeChanges: [at('/repo/src/gone.ts', GIT_STATUS.DELETED)],
+      untrackedChanges: [at('/repo/docs/new.md', GIT_STATUS.UNTRACKED)],
+    }))).toEqual({
+      staged: [
+        { path: 'src/staged.ts', change: 'M' },
+        { path: 'src/added.ts', change: 'A' },
+      ],
+      changes: [
+        { path: 'conflict.ts', change: 'M' },
+        { path: 'src/gone.ts', change: 'D' },
+        { path: 'docs/new.md', change: 'A' },
+      ],
+    })
+  })
+
+  it('暂存后又改了的两区都有，各带各的改动（和源代码管理视图一样）', () => {
+    expect(uncommittedFiles('/repo', groups({
+      indexChanges: [at('/repo/a.ts', GIT_STATUS.INDEX_ADDED)],
+      workingTreeChanges: [at('/repo/a.ts', GIT_STATUS.MODIFIED)],
+    }))).toEqual({ staged: [{ path: 'a.ts', change: 'A' }], changes: [{ path: 'a.ts', change: 'M' }] })
+  })
+
+  it('从暂存区删掉、文件还在盘上（git rm --cached）的：暂存区里是 D，更改里是 A', () => {
+    expect(uncommittedFiles('/repo', groups({
+      indexChanges: [at('/repo/a.ts', GIT_STATUS.INDEX_DELETED)],
+      untrackedChanges: [at('/repo/a.ts', GIT_STATUS.UNTRACKED)],
+    }))).toEqual({ staged: [{ path: 'a.ts', change: 'D' }], changes: [{ path: 'a.ts', change: 'A' }] })
+  })
+
+  it('同一区里同一个文件只留一项，后面的组盖掉前面的', () => {
+    expect(uncommittedFiles('/repo', groups({
+      mergeChanges: [at('/repo/a.ts', GIT_STATUS.BOTH_MODIFIED)],
+      workingTreeChanges: [at('/repo/a.ts', GIT_STATUS.DELETED)],
+    })).changes).toEqual([{ path: 'a.ts', change: 'D' }])
+  })
+
+  it('仓库根本身、仓库外面的路径不要', () => {
+    expect(uncommittedFiles('/repo', groups({
+      indexChanges: [at('/other/c.ts', GIT_STATUS.INDEX_MODIFIED)],
+      workingTreeChanges: [at('/repo', GIT_STATUS.MODIFIED), at('/other/a.ts', GIT_STATUS.MODIFIED), at('/repository/b.ts', GIT_STATUS.MODIFIED)],
+    }))).toEqual({ staged: [], changes: [] })
+  })
+
+  it('没有改动时两区都是空的', () => {
+    expect(uncommittedFiles('/repo', groups({}))).toEqual({ staged: [], changes: [] })
+  })
+})
+
+describe('工作区里有改动的仓库', () => {
+  const repo = (root: string, parts: Partial<ChangeGroups>): { rootUri: { path: string }, state: ChangeGroups } => ({ rootUri: { path: root }, state: groups(parts) })
+  const folder = (path: string, name: string): { uri: { path: string }, name: string } => ({ uri: { path }, name })
+  const changed = (root: string): ReturnType<typeof repo> => repo(root, { workingTreeChanges: [at(`${root}/a.ts`, GIT_STATUS.MODIFIED)] })
+
+  it('仓库根就是工作区文件夹时带着文件夹、用文件夹的名字', () => {
+    const app = folder('/work/app', '应用')
+    const [root] = uncommittedRoots([changed('/work/app')], [app])
+    expect(root.folder).toBe(app)
+    expect(root.name).toBe('应用')
+    expect(root.staged).toEqual([])
+    expect(root.changes).toEqual([{ path: 'a.ts', change: 'M' }])
+  })
+
+  it('只有暂存的更改的仓库也摆', () => {
+    const roots = uncommittedRoots([repo('/work/app', { indexChanges: [at('/work/app/a.ts', GIT_STATUS.INDEX_MODIFIED)] })], [folder('/work/app', 'app')])
+    expect(roots.map(root => [root.staged.length, root.changes.length])).toEqual([[1, 0]])
+  })
+
+  it('嵌套在工作区文件夹里的、包着工作区文件夹的仓库也算，名字用仓库根目录的名字', () => {
+    const roots = uncommittedRoots([changed('/work/app/libs/sdk'), changed('/work')], [folder('/work/app', 'app')])
+    expect(roots.map(root => [root.name, root.folder])).toEqual([['work', undefined], ['sdk', undefined]])
+  })
+
+  it('跟工作区文件夹不沾边的仓库（审查用的工作副本）不算', () => {
+    expect(uncommittedRoots([changed('/worktrees/review-1'), changed('/work/application')], [folder('/work/app', 'app')])).toEqual([])
+  })
+
+  it('没有改动的仓库不摆', () => {
+    expect(uncommittedRoots([repo('/work/app', {})], [folder('/work/app', 'app')])).toEqual([])
+  })
+
+  it('按工作区文件夹的次序排，同一个文件夹里按仓库根的路径排', () => {
+    const roots = uncommittedRoots(
+      [changed('/b/zeta'), changed('/a'), changed('/b'), changed('/b/alpha')],
+      [folder('/b', 'B'), folder('/a', 'A')],
+    )
+    expect(roots.map(root => root.repository.rootUri.path)).toEqual(['/b', '/b/alpha', '/b/zeta', '/a'])
+  })
+})
+
+describe('算不算工作区里的仓库', () => {
+  const folders = [{ uri: { path: '/work/app' }, name: 'app' }, { uri: { path: '/lib' }, name: 'lib' }]
+
+  it('仓库根就是、在里面、包着工作区文件夹的算，给出沾边的第一个工作区文件夹的次序', () => {
+    expect(workspaceOrder('/work/app', folders)).toBe(0)
+    expect(workspaceOrder('/work/app/vendor/sdk', folders)).toBe(0)
+    expect(workspaceOrder('/work', folders)).toBe(0)
+    expect(workspaceOrder('/lib', folders)).toBe(1)
+  })
+
+  it('不沾边的（名字只是前缀相同的、别处的工作副本）是 -1', () => {
+    expect(workspaceOrder('/work/application', folders)).toBe(-1)
+    expect(workspaceOrder('/worktrees/review-1', folders)).toBe(-1)
+  })
+})
+
+describe('隐藏测试文件', () => {
+  const file = (path: string, change: 'M' | 'A' | 'D' = 'M'): { path: string, change: 'M' | 'A' | 'D' } => ({ path, change })
+
+  it('两区都剔除测试文件，数出藏了几个（两区都有的算一个）', () => {
+    const { roots, hidden } = withoutTestFiles([{
+      name: 'app',
+      staged: [file('src/a.ts'), file('src/a.test.ts', 'A')],
+      changes: [file('src/a.test.ts'), file('tests/test_api.py'), file('src/b.ts')],
+    }])
+    expect(hidden).toBe(2)
+    expect(roots).toEqual([{ name: 'app', staged: [file('src/a.ts')], changes: [file('src/b.ts')] }])
+  })
+
+  it('几个仓库的加在一起；剔完两区都空的仓库不摆', () => {
+    const { roots, hidden } = withoutTestFiles([
+      { name: 'app', staged: [], changes: [file('handler_test.go')] },
+      { name: 'lib', staged: [file('conftest.py')], changes: [file('lib.py')] },
+    ])
+    expect(hidden).toBe(2)
+    expect(roots.map(root => root.name)).toEqual(['lib'])
+  })
+
+  it('没有测试文件时原样、藏了 0 个', () => {
+    const only = { name: 'app', staged: [file('a.ts')], changes: [] }
+    expect(withoutTestFiles([only])).toEqual({ roots: [only], hidden: 0 })
+  })
+})
+
+describe('标题后面的字、标题下面的一行', () => {
+  it('藏了测试文件时标题后面注明藏了几个', () => {
+    expect(uncommittedDescription(0)).toBe('未提交的更改')
+    expect(uncommittedDescription(3)).toBe('未提交的更改 · 已隐藏 3 个测试文件')
+  })
+
+  it('树上有文件时没有提示；只剩藏起来的测试文件、什么都没有、git 还在找仓库时各说一句', () => {
+    expect(uncommittedMessage({ hasFiles: true, hiddenTests: 2, loading: false })).toBeUndefined()
+    expect(uncommittedMessage({ hasFiles: false, hiddenTests: 2, loading: false })).toBe('除了隐藏的测试文件，没有未提交的更改')
+    expect(uncommittedMessage({ hasFiles: false, hiddenTests: 0, loading: false })).toBe('没有未提交的更改')
+    expect(uncommittedMessage({ hasFiles: false, hiddenTests: 0, loading: true })).toBe('正在读取 git 状态…')
+  })
+})

vscode/src/codeReader/uncommitted/uncommittedFiles.ts

@@ -0,0 +1,164 @@
+import type { GitStatus } from '../../git/gitApi'
+import type { ChangedFile, FileChange } from '../explorer/changedTree'
+import { posix } from 'node:path'
+import { GIT_STATUS } from '../../git/gitApi'
+import { toPathKey } from '../pathMap'
+import { isTestFile } from './testFiles'
+
+/** 一组改动里的一项：文件在哪（Uri.path）、git 状态。 */
+interface StatusEntry {
+  readonly uri: { readonly path: string }
+  readonly status: GitStatus
+}
+
+/** 仓库状态里没提交的几组，照 git.d.ts 的 RepositoryState。 */
+export interface ChangeGroups {
+  readonly mergeChanges: readonly StatusEntry[]
+  readonly indexChanges: readonly StatusEntry[]
+  readonly workingTreeChanges: readonly StatusEntry[]
+  readonly untrackedChanges: readonly StatusEntry[]
+}
+
+const ADDED = new Set<GitStatus>([
+  GIT_STATUS.INDEX_ADDED,
+  GIT_STATUS.UNTRACKED,
+  GIT_STATUS.INTENT_TO_ADD,
+  GIT_STATUS.ADDED_BY_US,
+  GIT_STATUS.ADDED_BY_THEM,
+  GIT_STATUS.BOTH_ADDED,
+])
+
+const DELETED = new Set<GitStatus>([
+  GIT_STATUS.INDEX_DELETED,
+  GIT_STATUS.DELETED,
+  GIT_STATUS.BOTH_DELETED,
+])
+
+/**
+ * git 的文件状态 → M / A / D：未跟踪、新增（含 `git add -N`、合并时一方或双方新加的）算 A，
+ * 删除（含合并时双方都删了的）算 D，别的（改了、改名、复制、改类型、合并冲突）都算 M。
+ * 合并时一方删了、另一方改了的，冲突的文件还留在工作区里，也算 M。
+ */
+export function changeOfGitStatus(status: GitStatus): FileChange {
+  return ADDED.has(status) ? 'A' : DELETED.has(status) ? 'D' : 'M'
+}
+
+/** 源代码管理视图两个区里的文件，路径相对仓库根、`/` 分隔。 */
+export interface UncommittedFiles {
+  /** 暂存的更改：暂存区里的 */
+  staged: ChangedFile[]
+  /** 更改：合并冲突的、没暂存的、未跟踪的 */
+  changes: ChangedFile[]
+}
+
+/** 几组改动合成一个区：同一个文件只留一项（后面的组盖掉前面的）；仓库根本身、仓库外面的路径不要。 */
+function collect(rootPath: string, groups: readonly (readonly StatusEntry[])[]): ChangedFile[] {
+  const files = new Map<string, FileChange>()
+  for (const group of groups) {
+    for (const { uri, status } of group) {
+      const key = toPathKey(rootPath, uri.path)
+      if (key !== undefined)
+        files.set(key, changeOfGitStatus(status))
+    }
+  }
+  return [...files].map(([path, change]) => ({ path, change }))
+}
+
+/**
+ * 一个仓库里没提交的文件，照源代码管理视图分两区：暂存的更改（暂存区）、更改（合并冲突、没暂存、未跟踪）。
+ * 暂存后又改了的文件两区都有。
+ */
+export function uncommittedFiles(rootPath: string, groups: ChangeGroups): UncommittedFiles {
+  return {
+    staged: collect(rootPath, [groups.indexChanges]),
+    changes: collect(rootPath, [groups.mergeChanges, groups.workingTreeChanges, groups.untrackedChanges]),
+  }
+}
+
+function sameOrUnder(child: string, parent: string): boolean {
+  return child === parent || toPathKey(parent, child) !== undefined
+}
+
+/** 工作区文件夹里用到的：在哪（Uri.path）、叫什么。 */
+interface FolderLike {
+  readonly uri: { readonly path: string }
+  readonly name: string
+}
+
+/** 仓库里用到的：仓库根（Uri.path）和没提交的几组改动。 */
+interface RepositoryLike {
+  readonly rootUri: { readonly path: string }
+  readonly state: ChangeGroups
+}
+
+/** 有没提交的文件的一个仓库，两个区里各是侧栏上一个根节点。 */
+export interface UncommittedRoot<R, F> extends UncommittedFiles {
+  repository: R
+  /** 仓库根就是这个工作区文件夹时是它 */
+  folder: F | undefined
+  /** 根节点上的名字：仓库根就是工作区文件夹时用文件夹的名字，别的用仓库根目录的名字 */
+  name: string
+}
+
+/**
+ * 仓库算不算工作区里的：仓库根就是某个工作区文件夹、在某个工作区文件夹里面（嵌套的仓库），
+ * 或者包着某个工作区文件夹（打开的是仓库里的子目录）；编辑器打开别处的文件时 git 扩展顺带打开的仓库（比如审查用的工作副本）不算。
+ * @returns 沾边的第一个工作区文件夹的次序；不算工作区里的是 -1
+ */
+export function workspaceOrder(rootPath: string, folders: readonly FolderLike[]): number {
+  return folders.findIndex(folder => sameOrUnder(rootPath, folder.uri.path) || sameOrUnder(folder.uri.path, rootPath))
+}
+
+/**
+ * 工作区里（见 workspaceOrder）有没提交的文件的仓库，各一个根。
+ * 按沾边的工作区文件夹的次序排，同一个文件夹沾边的按仓库根的路径排。
+ */
+export function uncommittedRoots<R extends RepositoryLike, F extends FolderLike>(repositories: readonly R[], folders: readonly F[]): UncommittedRoot<R, F>[] {
+  return repositories
+    .map(repository => ({ repository, rootPath: repository.rootUri.path, order: workspaceOrder(repository.rootUri.path, folders) }))
+    .filter(({ order }) => order >= 0)
+    .sort((a, b) => a.order - b.order || (a.rootPath < b.rootPath ? -1 : a.rootPath > b.rootPath ? 1 : 0))
+    .map(({ repository, rootPath }) => {
+      const folder = folders.find(item => item.uri.path === rootPath)
+      return { repository, folder, name: folder?.name ?? posix.basename(rootPath), ...uncommittedFiles(rootPath, repository.state) }
+    })
+    .filter(hasFiles)
+}
+
+function hasFiles(files: UncommittedFiles): boolean {
+  return files.staged.length > 0 || files.changes.length > 0
+}
+
+/**
+ * 剔除测试文件（见 isTestFile）：两个区都剔，剔完两区都空的仓库不摆。
+ * @returns 剩下的仓库，和藏了几个测试文件（暂存后又改了、两区都有的算一个）
+ */
+export function withoutTestFiles<T extends UncommittedFiles>(roots: readonly T[]): { roots: T[], hidden: number } {
+  let hidden = 0
+  const kept = roots.map((root) => {
+    const tests = new Set([...root.staged, ...root.changes].map(file => file.path).filter(isTestFile))
+    hidden += tests.size
+    const keep = (file: ChangedFile): boolean => !tests.has(file.path)
+    return { ...root, staged: root.staged.filter(keep), changes: root.changes.filter(keep) }
+  })
+  return { roots: kept.filter(hasFiles), hidden }
+}
+
+/** 「更改」区里文件行的 contextValue 带的标记（见 entryContext）：这些行上挂「暂存」按钮。 */
+export const UNSTAGED_MARKER = 'unstaged'
+
+/** 开着时视图标题后面淡色的字（TreeView.description）：藏了测试文件时注明藏了几个。 */
+export function uncommittedDescription(hiddenTests: number): string {
+  return hiddenTests > 0 ? `未提交的更改 · 已隐藏 ${hiddenTests} 个测试文件` : '未提交的更改'
+}
+
+/**
+ * 标题下面的一行（TreeView.message）：树上有文件时没有；只剩藏起来的测试文件、什么都没有、git 还在找仓库时各说一句。
+ */
+export function uncommittedMessage(state: { hasFiles: boolean, hiddenTests: number, loading: boolean }): string | undefined {
+  if (state.hasFiles)
+    return undefined
+  if (state.hiddenTests > 0)
+    return '除了隐藏的测试文件，没有未提交的更改'
+  return state.loading ? '正在读取 git 状态…' : '没有未提交的更改'
+}

vscode/src/codeReader/uncommitted/uncommittedMode.ts

@@ -0,0 +1,251 @@
+import type { ExtensionContext, TreeView, WorkspaceFolder } from 'vscode'
+import type { GitApi, GitRepository } from '../../git/gitApi'
+import type { ChangedFile } from '../explorer/changedTree'
+import type { ChangedSection, FileNode, FileTreeProvider, TreeNode } from '../explorer/fileTree'
+import type { TreeFilter, TreeFilters } from '../explorer/treeFilters'
+import type { UncommittedRoot } from './uncommittedFiles'
+import * as path from 'node:path'
+import { commands, Disposable, window, workspace } from 'vscode'
+import { loadGitApi } from '../../git/gitExtension'
+import { logger } from '../../logging/logger'
+import { buildChangedTree } from '../explorer/changedTree'
+import { uncommittedDescription, uncommittedMessage, uncommittedRoots, UNSTAGED_MARKER, withoutTestFiles, workspaceOrder } from './uncommittedFiles'
+
+/** workspaceState：开着「未提交的更改」，重开窗口接着显示。 */
+const UNCOMMITTED_KEY = 'superpowers.codeReader.uncommitted'
+/** workspaceState：隐藏测试文件。 */
+const HIDE_TESTS_KEY = 'superpowers.codeReader.hideTests'
+/** 上下文键：隐藏着测试文件。标题栏的「隐藏测试文件 / 显示测试文件」按它换着显示。 */
+const TESTS_HIDDEN_CONTEXT = 'superpowers.codeReader.testsHidden'
+/** 两个分组的名字，照 VS Code 源代码管理视图的中文界面。 */
+const STAGED_LABEL = '暂存的更改'
+const CHANGES_LABEL = '更改'
+/** git 状态连着变（保存、暂存、切分支）时合成一次重摆。 */
+const REBUILD_DELAY_MS = 300
+
+/** 怎么进的：enter 点按钮（出错时说一声）、restore 重开窗口接着显示（出错只记日志）。 */
+type How = 'enter' | 'restore'
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/**
+ * 侧栏只看未提交的更改：照源代码管理视图分「暂存的更改」「更改」两组（空的不摆），每组下面每个有改动的仓库一个根。
+ * 文件就是工作区里的文件，颜色和 M / A / D 徽标由 VS Code 自带的 git 装饰加上；「更改」组里的文件行上有「暂存」按钮。
+ * 可以隐藏测试文件。开着时盯着 git 状态自动重摆；「显示全部」回到工作区文件树。
+ * 开着没开、隐不隐藏测试文件都按工作区记住；和审查工单互斥，见 TreeFilters。
+ */
+export class UncommittedMode implements TreeFilter, Disposable {
+  private readonly disposables: Disposable[]
+  /** 开着时的 git API；没开时 undefined */
+  private api: GitApi | undefined
+  /** 开着时盯 git 状态的监听 */
+  private watching: Disposable | undefined
+  private timer: NodeJS.Timeout | undefined
+  /** 树上现在摆的改动（序列化），没变就不重画 */
+  private shown: string | undefined
+  /** 每进一次、退一次都加一：等 git 扩展回来时已经退出或又进了一次的，结果丢掉。 */
+  private generation = 0
+  private hideTests: boolean
+
+  /** viewId 是侧栏视图的 id：刷新时在这个视图上转进度。 */
+  constructor(
+    private readonly context: ExtensionContext,
+    private readonly viewId: string,
+    private readonly view: TreeView<TreeNode>,
+    private readonly files: FileTreeProvider,
+    private readonly filters: TreeFilters,
+  ) {
+    this.hideTests = context.workspaceState.get<boolean>(HIDE_TESTS_KEY) ?? false
+    void commands.executeCommand('setContext', TESTS_HIDDEN_CONTEXT, this.hideTests)
+    filters.add(this)
+    this.disposables = [filters.whenShown(() => void this.restore())]
+  }
+
+  /** 「未提交的更改」：别的筛选退出，树里换成未提交的文件，之后跟着 git 状态变。 */
+  async enter(): Promise<void> {
+    await this.open('enter')
+  }
+
+  /** 「显示全部」或换成别的筛选：不再盯 git、不再记着，正在进的作废；开着的回到工作区文件树。 */
+  async exit(): Promise<void> {
+    this.generation++
+    this.stopWatching()
+    await Promise.all([
+      this.filters.leave(this),
+      this.context.workspaceState.update(UNCOMMITTED_KEY, undefined),
+    ])
+  }
+
+  /** 开着时的「刷新」：让 git 扩展重读工作区各仓库的状态，再整棵重摆。 */
+  async reload(): Promise<void> {
+    const api = this.api
+    if (!api)
+      return
+    const folders = workspace.workspaceFolders ?? []
+    const repositories = api.repositories.filter(repository => workspaceOrder(repository.rootUri.path, folders) >= 0)
+    await window.withProgress({ location: { viewId: this.viewId } }, () => Promise.all(repositories.map(repository => this.status(repository))))
+    if (this.api !== api)
+      return
+    this.shown = undefined
+    this.rebuild()
+  }
+
+  /** 「隐藏测试文件 / 显示测试文件」：两组都剔除 / 放回测试文件，按工作区记住。 */
+  async setTestsHidden(hidden: boolean): Promise<void> {
+    this.hideTests = hidden
+    this.rebuild()
+    await Promise.all([
+      commands.executeCommand('setContext', TESTS_HIDDEN_CONTEXT, hidden),
+      this.context.workspaceState.update(HIDE_TESTS_KEY, hidden || undefined),
+    ])
+  }
+
+  /** 「更改」组里文件行上的「暂存」：把这个文件放进暂存区（新文件、删掉的、冲突的都行），树跟着 git 状态变。 */
+  async stage(node: FileNode | undefined): Promise<void> {
+    const api = this.api
+    if (!node || !api)
+      return // 只挂在开着时「更改」组的文件行上
+    const name = path.basename(node.uri.fsPath)
+    const repository = api.getRepository(node.uri)
+    if (!repository) {
+      logger.add({ level: 'warn', source: 'codeReader', message: `未提交的更改：${name} 不在打开的 git 仓库里，没法暂存`, details: node.uri.fsPath })
+      void window.showErrorMessage(`没法暂存 ${name}：找不到它所在的 git 仓库`)
+      return
+    }
+    try {
+      await repository.add([node.uri.fsPath])
+    }
+    catch (err) {
+      logger.add({ level: 'error', source: 'codeReader', message: `未提交的更改：暂存 ${name} 失败`, details: `${node.uri.fsPath}\n${errorText(err)}` })
+      void window.showErrorMessage(`没能暂存 ${name}：${errorText(err)}`)
+    }
+  }
+
+  dispose(): void {
+    this.stopWatching()
+    for (const disposable of this.disposables)
+      disposable.dispose()
+  }
+
+  private async restore(): Promise<void> {
+    if (this.context.workspaceState.get<boolean>(UNCOMMITTED_KEY))
+      await this.open('restore')
+  }
+
+  private async open(how: How): Promise<void> {
+    const generation = ++this.generation
+    let api: GitApi | undefined
+    try {
+      api = await loadGitApi()
+    }
+    catch (err) {
+      this.fail(how, '激活 vscode.git 扩展失败', errorText(err))
+      return
+    }
+    if (generation !== this.generation)
+      return
+    if (!api) {
+      this.fail(how, 'vscode.git 扩展没装或被禁用了')
+      return
+    }
+    this.stopWatching()
+    this.api = api
+    this.watching = this.watch(api)
+    const entering = this.filters.enter(this, 'uncommitted')
+    this.rebuild()
+    await Promise.all([entering, this.context.workspaceState.update(UNCOMMITTED_KEY, true)])
+  }
+
+  private fail(how: How, message: string, details?: string): void {
+    logger.add({ level: 'warn', source: 'codeReader', message: `未提交的更改：${message}`, ...(details ? { details } : {}) })
+    if (how === 'enter')
+      void window.showErrorMessage(`没法显示未提交的更改：${message}`)
+  }
+
+  private async status(repository: GitRepository): Promise<void> {
+    try {
+      await repository.status()
+    }
+    catch (err) {
+      logger.add({ level: 'warn', source: 'codeReader', message: '未提交的更改：重读 git 状态失败', details: `${repository.rootUri.fsPath}\n${errorText(err)}` })
+    }
+  }
+
+  /** 盯着 git：各仓库的状态变了、开了 / 关了仓库、git 扩展找完仓库、工作区文件夹变了，都合成一次重摆。 */
+  private watch(api: GitApi): Disposable {
+    const repositories = new Map<GitRepository, Disposable>()
+    const schedule = (): void => {
+      clearTimeout(this.timer)
+      this.timer = setTimeout(() => this.rebuild(), REBUILD_DELAY_MS)
+    }
+    const add = (repository: GitRepository): void => {
+      if (!repositories.has(repository))
+        repositories.set(repository, repository.state.onDidChange(schedule))
+    }
+    api.repositories.forEach(add)
+    return Disposable.from(
+      api.onDidOpenRepository((repository) => {
+        add(repository)
+        schedule()
+      }),
+      api.onDidCloseRepository((repository) => {
+        repositories.get(repository)?.dispose()
+        repositories.delete(repository)
+        schedule()
+      }),
+      api.onDidChangeState(schedule),
+      workspace.onDidChangeWorkspaceFolders(schedule),
+      { dispose: () => repositories.forEach(listener => listener.dispose()) },
+    )
+  }
+
+  private stopWatching(): void {
+    clearTimeout(this.timer)
+    this.timer = undefined
+    this.watching?.dispose()
+    this.watching = undefined
+    this.api = undefined
+    this.shown = undefined
+  }
+
+  /** 按 git 现在的状态（和隐不隐藏测试文件）重摆树、标题后面的字、标题下面的一行；树上摆的没变就不重画。 */
+  private rebuild(): void {
+    const api = this.api
+    if (!api)
+      return
+    const folders = workspace.workspaceFolders ?? []
+    const all = uncommittedRoots(api.repositories, folders)
+    const { roots, hidden } = this.hideTests ? withoutTestFiles(all) : { roots: all, hidden: 0 }
+    this.view.description = uncommittedDescription(hidden)
+    this.view.message = uncommittedMessage({ hasFiles: roots.length > 0, hiddenTests: hidden, loading: api.state !== 'initialized' })
+    const shown = JSON.stringify(roots.map(root => [root.repository.rootUri.toString(), root.name, root.staged, root.changes]))
+    if (shown === this.shown)
+      return
+    this.shown = shown
+    // 仓库根不是工作区文件夹时（嵌套的仓库、包着工作区文件夹的仓库）拿仓库根当根，名字用仓库根目录的名字
+    const placed = roots.map(root => ({ root, folder: root.folder ?? { uri: root.repository.rootUri, name: root.name, index: folders.length } }))
+    this.files.showChanges([
+      section(STAGED_LABEL, placed, root => root.staged),
+      section(CHANGES_LABEL, placed, root => root.changes, UNSTAGED_MARKER),
+    ].filter(group => group.roots.length > 0))
+  }
+}
+
+/** 一个分组：有这个区的文件的仓库各一个根，分组行后面写这个区一共几个文件。 */
+function section(
+  label: string,
+  placed: readonly { root: UncommittedRoot<GitRepository, WorkspaceFolder>, folder: WorkspaceFolder }[],
+  filesOf: (root: UncommittedRoot<GitRepository, WorkspaceFolder>) => ChangedFile[],
+  fileMarker?: string,
+): ChangedSection {
+  const withFiles = placed.filter(({ root }) => filesOf(root).length > 0)
+  const count = withFiles.reduce((sum, { root }) => sum + filesOf(root).length, 0)
+  return {
+    label,
+    description: String(count),
+    ...(fileMarker ? { fileMarker } : {}),
+    roots: withFiles.map(({ root, folder }) => ({ folder, tree: buildChangedTree(filesOf(root)) })),
+  }
+}

vscode/src/git/gitApi.ts

@@ -0,0 +1,78 @@
+import type { Event, Uri } from 'vscode'
+
+/**
+ * 内置 git 扩展（vscode.git）API 里用到的那一小部分，照 microsoft/vscode 的 extensions/git/src/api/git.d.ts 写的结构类型。
+ * 这里只有类型和状态值，运行时不依赖 vscode，纯函数和单测可以直接用；取 API 见 gitExtension.ts。
+ */
+
+/** 文件在 git 里的状态，数值照 git.d.ts 的 Status 枚举。 */
+export const GIT_STATUS = {
+  INDEX_MODIFIED: 0,
+  INDEX_ADDED: 1,
+  INDEX_DELETED: 2,
+  INDEX_RENAMED: 3,
+  INDEX_COPIED: 4,
+  MODIFIED: 5,
+  DELETED: 6,
+  UNTRACKED: 7,
+  IGNORED: 8,
+  INTENT_TO_ADD: 9,
+  INTENT_TO_RENAME: 10,
+  TYPE_CHANGED: 11,
+  ADDED_BY_US: 12,
+  ADDED_BY_THEM: 13,
+  DELETED_BY_US: 14,
+  DELETED_BY_THEM: 15,
+  BOTH_ADDED: 16,
+  BOTH_DELETED: 17,
+  BOTH_MODIFIED: 18,
+} as const
+
+export type GitStatus = (typeof GIT_STATUS)[keyof typeof GIT_STATUS]
+
+/** 一个文件的改动；改名的 uri 是新路径。 */
+export interface GitChange {
+  readonly uri: Uri
+  readonly status: GitStatus
+}
+
+export interface GitRepositoryState {
+  /** 合并冲突的 */
+  readonly mergeChanges: readonly GitChange[]
+  /** 暂存的 */
+  readonly indexChanges: readonly GitChange[]
+  /** 没暂存的；设置 git.untrackedChanges 是 mixed（默认）时也含未跟踪的 */
+  readonly workingTreeChanges: readonly GitChange[]
+  /** 未跟踪的；设置 git.untrackedChanges 是 separate 时才有 */
+  readonly untrackedChanges: readonly GitChange[]
+  readonly onDidChange: Event<void>
+}
+
+export interface GitRepository {
+  readonly rootUri: Uri
+  readonly state: GitRepositoryState
+  /** 重读这个仓库的 git 状态 */
+  status: () => Promise<void>
+  /** 把这些文件（绝对路径）放进暂存区，同 git add：新文件、删掉的、冲突的都行 */
+  add: (paths: string[]) => Promise<void>
+}
+
+/** initialized 之前 git 扩展还在找工作区里的仓库，repositories 可能不全。 */
+export type GitApiState = 'uninitialized' | 'initialized'
+
+export interface GitApi {
+  readonly state: GitApiState
+  readonly onDidChangeState: Event<GitApiState>
+  readonly repositories: readonly GitRepository[]
+  readonly onDidOpenRepository: Event<GitRepository>
+  readonly onDidCloseRepository: Event<GitRepository>
+  /** 文件所在的仓库（按路径找，删掉的文件也行）；不在任何打开的仓库里时 null */
+  getRepository: (uri: Uri) => GitRepository | null
+}
+
+/** vscode.git 扩展激活后导出的东西。 */
+export interface GitExtension {
+  /** 设置 git.enabled 关掉时是 false，这时 getAPI 会抛错 */
+  readonly enabled: boolean
+  getAPI: (version: 1) => GitApi
+}

vscode/src/git/gitExtension.ts

@@ -0,0 +1,11 @@
+import type { GitApi, GitExtension } from './gitApi'
+import { extensions } from 'vscode'
+
+/** 取内置 git 扩展的 API（还没激活就先激活）；没装、被禁用（设置 git.enabled 关了）时是 undefined，激活失败时抛错。 */
+export async function loadGitApi(): Promise<GitApi | undefined> {
+  const extension = extensions.getExtension<GitExtension>('vscode.git')
+  if (!extension)
+    return undefined
+  const git = extension.isActive ? extension.exports : await extension.activate()
+  return git.enabled ? git.getAPI(1) : undefined
+}

vscode/src/panel/handlers/toolbar.ts

@@ -1,47 +1,19 @@
-import type { Uri } from 'vscode'
+import type { GitRepository } from '../../git/gitApi'
 import type { KanbanWebviewPanel } from '../KanbanPanel'
 import { accessSync, constants } from 'node:fs'
 import * as path from 'node:path'
-import { extensions, workspace } from 'vscode'
+import { workspace } from 'vscode'
 import { resolveCommitProfileForRun } from '../../cc/commitProfile'
 import { resolveProfilePath } from '../../cc/profiles'
 import { spawnClaude } from '../../cc/spawnClaude'
 import { findEnvFiles, lockEnvFiles, unlockEnvFiles } from '../../files/envLock'
+import { loadGitApi } from '../../git/gitExtension'
 import { missingGitIdentityKeys, readGitIdentity } from '../../git/identity'
 import { logger } from '../../logging/logger'
 import { getEffectiveCommitProfilePath } from '../../settings/store'
 import { makeNonce } from '../../webview/html'
 import { dismiss, toast } from './handoffFlow'
 
-/**
- * Minimal structural typing for the bits of the built-in `vscode.git`
- * extension API we consume to observe working-tree state.
- * Reference: microsoft/vscode → extensions/git/src/api/git.d.ts
- */
-interface GitExtensionApiRepositoryStateChange {
-  (listener: () => unknown): { dispose: () => void }
-}
-
-interface GitExtensionApiRepositoryState {
-  readonly workingTreeChanges: ReadonlyArray<{ uri: Uri }>
-  readonly indexChanges: ReadonlyArray<{ uri: Uri }>
-  readonly untrackedChanges?: ReadonlyArray<{ uri: Uri }>
-  readonly onDidChange: GitExtensionApiRepositoryStateChange
-}
-
-interface GitExtensionApiRepository {
-  readonly rootUri: Uri
-  readonly state: GitExtensionApiRepositoryState
-}
-
-interface GitExtensionApi {
-  readonly repositories: ReadonlyArray<GitExtensionApiRepository>
-}
-
-interface GitExtensionExports {
-  getAPI: (version: 1) => GitExtensionApi
-}
-
 export async function handleCommitRun(panel: KanbanWebviewPanel): Promise<void> {
   if (panel.commitRunning)
     return
@@ -266,26 +238,20 @@ export function setupGitWatcher(panel: KanbanWebviewPanel): void {
   if (!wsRoot)
     return
 
-  const gitExt = extensions.getExtension<GitExtensionExports>('vscode.git')
-  if (!gitExt) {
-    logger.add({
-      level: 'warn',
-      source: 'panel',
-      message: 'vscode.git 扩展未找到，提交按钮将持续显示',
-    })
-    // Fallback: keep the button visible so users can at least trigger
-    // commits manually even though we can't observe state.
-    updateHasChanges(panel, true)
-    return
-  }
+  void loadGitApi().then((api) => {
+    if (!api) {
+      logger.add({
+        level: 'warn',
+        source: 'panel',
+        message: 'vscode.git 扩展没装或被禁用，提交按钮将持续显示',
+      })
+      // Fallback: keep the button visible so users can at least trigger
+      // commits manually even though we can't observe state.
+      updateHasChanges(panel, true)
+      return
+    }
 
-  const activation = gitExt.isActive
-    ? Promise.resolve(gitExt.exports)
-    : Promise.resolve(gitExt.activate())
-
-  void activation.then((exports) => {
-    const api = exports.getAPI(1)
-    const findRepo = (): GitExtensionApiRepository | undefined =>
+    const findRepo = (): GitRepository | undefined =>
       api.repositories.find(r => r.rootUri.fsPath === wsRoot)
 
     const updateState = (): void => {
@@ -297,11 +263,11 @@ export function setupGitWatcher(panel: KanbanWebviewPanel): void {
       const total
         = repo.state.workingTreeChanges.length
           + repo.state.indexChanges.length
-          + (repo.state.untrackedChanges?.length ?? 0)
+          + repo.state.untrackedChanges.length
       updateHasChanges(panel, total > 0)
     }
 
-    const subscribe = (repo: GitExtensionApiRepository): void => {
+    const subscribe = (repo: GitRepository): void => {
       panel.gitStateDisposable = repo.state.onDidChange(updateState)
     }