CAtlas Hub

CAtlas Hub 是一个用于代码工程浏览与管理的 VS Code 插件，目前处于预览测试阶段。当前实现八类核心功能：

1. 在插件内部按集合和别名管理、选择并打开多个独立项目。
2. 在资源管理器按目录查看已打开文件，并把非项目标签稳定移到末尾。
3. 在资源管理器中屏蔽所选文件或目录，使其不再参与目录展示、搜索和文件监控。
4. 标记不属于当前工作区的已打开文件，降低在错误项目中编辑文件的风险。
5. 在侧栏显示当前文件的函数与符号大纲，支持快速筛选、定位和跳转。
6. 在独立配置视图中集中管理集合功能和个人偏好，并通过导入、导出迁移配置。
7. 使用统一的领域图标区分项目、配置、文件边界和代码符号，并可即时切换到 VS Code 原生风格。
8. 聚合当前文件或工作区中的代码 TODO，支持筛选、定位、关键词管理和快速标记。

完整开发范围保存在项目仓库的 doc/功能清单.md，开发资料不随 VSIX 安装包分发。

安装后怎么用

打开活动栏中的“CAtlas Hub”。没有任何集合时，“项目集合”视图直接显示：

• “添加项目并创建集合”：输入集合名称、选择项目、设置别名并确认，集合和第一个项目一次创建完成。
• “导入已有集合”：导入另一台设备导出的迁移快照，或旧版 *.project-butler.json。

集合、项目别名和集合功能配置保存在插件的版本化内部存储中，不再要求持续打开、保存或监听项目集合文件。标题栏可以添加项目、选择集合、导入、导出、刷新和退出当前集合；点击当前集合摘要也可以切换集合。

退出当前集合只清除当前选择，不修改集合内容、项目或已经打开的窗口。再次使用时可以从已有集合列表重新选择。

普通打开 JSON、设置页或旧集合文件不会切换当前集合。只有“选择项目集合”、完成导入或新建集合等明确操作会改变当前集合。

插件会区分“集合内项目”“集合外项目”和“未打开工作区”。只有当前文件夹或 .code-workspace 与活动集合项目精确匹配时，才使用集合功能配置；其他项目使用个人默认值。项目集合视图与配置视图都会显示当前作用范围。

“配置”视图是日常设置的统一入口，层次如下：

• 当前生效功能：显示非项目标签自动移至末尾、函数大纲模式的实际值与来源。集合内项目编辑集合覆盖值，并可选择“跟随个人默认”；集合外或未打开集合时直接编辑个人默认值。
• 项目与资源操作：项目打开方式、屏蔽前确认、已打开文件视图和图标风格。
• 代码 TODO：总开关、Markdown 未完成项和关键词支持“当前集合覆盖/跟随个人默认”；个人标识、默认关闭的“显示项目已有标记”、编辑器高亮和快捷键保持本机个人偏好。开启项目已有标记前会提示大型或开源项目的噪声与性能影响。
• VS Code 内置 AI 功能：一键开启或完全关闭 chat.disableAIFeatures。完全关闭会影响内置 Chat、内联 AI 建议和 Copilot；拥有独立界面的第三方 Agent 扩展通常不会被直接禁用。
• 工作区外文件提醒：总开关、前景色、‼ 徽标和状态栏提示。
• 函数大纲显示：符号范围、排序、外观、行数、标记和缩放。函数、方法和构造函数始终只显示名称，不显示参数。

点击选项后立即校验、保存并应用。每组都可以折叠，折叠状态会保存在本机；折叠不会关闭功能或改变已经保存的值。

当前功能

项目集合与别名打开

需要加入项目时，点击“项目集合”标题栏中的“添加项目”按钮：

1. 选择当前集合、其他集合或新建集合。
2. 选择“添加当前窗口项目”或其他文件夹、.code-workspace。
3. 确认项目别名，并可补充说明与标签。
4. 预览并确认；插件一次性保存完整结果并刷新项目树。

点击项目条目后，可以在新窗口或当前窗口打开；也可以把常用方式固定为个人偏好。项目路径不可用时条目仍保留并显示原因，不会猜测其他目录。

迁移时使用“导出项目集合”生成 *.project-butler-export.json 静态快照，再由另一位用户执行“导入项目集合”。导出会尽量使用相对于快照的路径；导入发现路径不可用时允许选择新的基础目录批量重映射。兼容字段按导入值应用，新版快照中缺失或无效的集合覆盖值改为跟随接收端个人默认。导入后源文件不会成为活动配置，也不会被插件监听。

旧版 *.project-butler.json 仍可通过“导入项目集合”迁移，原文件不会被修改。1.0.0 前只保证当前开发数据和必要的一次性迁移，不建立所有 0.x 格式的永久兼容承诺。

代码 TODO

打开 VS Code“资源管理器”并展开“代码 TODO”。它与文件夹、已打开文件目录等视图上下排列，默认折叠，并支持使用 VS Code 原生拖动调整上下顺序。启用 TODO 后，插件等待配置初始化完成，尝试恢复本工作区缓存并在后台检查文件变化；没有可用缓存时才完整更新，视图折叠不取消数据维护。默认识别 TODO、FIXME、BUG、HACK、XXX；DEBUG、NOTE、OPTIMIZE、REVIEW 是可选预置项，也可以添加由字母、数字、下划线和连字符组成的自定义关键词。默认只扫描当前个人标识及历史别名所属的标记。

• 扫描范围可切换为“工作区”或“当前文件”；无工作区窗口自动使用当前文件。
• 结果默认按任务描述分类，也可切换为按标签分组；可按关键词、正文、文件名和相对路径筛选。
• 设置“个人标记标识”后，快速标记使用 TODO(标识): 格式；普通 TODO: 和其他负责人的标记仍兼容解析，但默认不扫描。需要查看时，在“配置 → 代码 TODO”开启“显示项目已有标记”；开启前插件会提示大型或开源项目可能增加结果噪声、首次扫描耗时和 CPU 占用。
• 同一任务描述下集中展示对应标记，不再逐层展开文件夹；长描述以缩略形式显示，完整位置保留在悬停提示中。快速标记可选择已有任务描述，避免相同任务分散在多个类别。
• 点击结果会打开对应文件、选中关键词并把位置显示在编辑器中。
• 工作区文件发生变化、当前文件切换或打开文档尚未保存时，索引会增量更新；同一 URI 不会同时展示磁盘和编辑器两份结果。
• 可见编辑器默认只突出关键词本身，颜色使用 VS Code 的信息、警告和错误主题色；可在“配置 → 代码 TODO”关闭。
• 工作区扫描会先显示已打开文件的结果。本地 Git 项目优先使用 git grep 从候选源码中定位个人标记，非 Git 项目尝试系统 rg；工具不可用、远程或虚拟工作区自动回退到 VS Code API 兼容扫描。未跟踪文件和未保存文档会单独补充，不因快速后端遗漏；未设置个人标识且项目已有标记关闭时不会启动全工作区候选搜索。
• 扫描合并 files.exclude、search.exclude 和常见依赖/构建目录规则，不再因工作区原始文件达到 20,000 个而提前截断。只有真正命中关键词的文件进入精确注释解析和结果树；零结果文件不会进入可绘制索引。磁盘读取优先使用 BOM 和 files.encoding，对 GBK、ANSI 等旧源码提供兼容回退并在输出频道记录；当前单文件上限仍为 2 MiB。个人标记与项目已有标记分别保留 5,000 条结果配额，开启项目扫描不会挤占个人结果；个人候选也始终优先处理。
• 扫描期间更新进度，避免每处理一个文件就重绘结果。打开文档的新增、删除和未保存编辑优先更新内存索引；后台文件变化分批检查。正常刷新优先检查缓存与变化，命令“完整更新代码 TODO（重新读取）”可强制重新扫描。
• 有效缓存保存在 VS Code 的工作区扩展存储，包含文件 URI、时间、大小、标记描述和位置，不包含整份源码，不写入项目集合或导出快照。缓存无效、过期或扫描配置变化时完整更新；失败或取消不以不完整结果覆盖有效缓存。共享本机日志或扩展存储前请注意隐私。
• 超过 2 MiB 的源文件默认跳过，其他文件继续扫描；文件缩小后可重新参与扫描。完整更新和增量检查仍受结果数量、缓存大小及并发限制，不承诺任意规模工程都可无限扫描。

编辑器右键菜单和命令面板提供“快速标记”“重复上次标记”“修改标记类型”“完成/取消完成”和“删除当前标记”。第一次快速标记会要求设置简短个人标识，插件不会自动读取系统用户名、邮箱或 Git 身份；修改标识后旧值会作为历史别名继续识别。开启“显示项目已有标记”后，结果右键可以把已有标记认领为我的，或取消自己的归属。快速标记会按当前语言生成安全注释；未知语言不会猜测语法。删除标记只移除关键词语法并保留注释正文。插件不预设全局快捷键，可从“配置 → 代码 TODO → 设置快速标记快捷键”进入 VS Code 键盘快捷方式自行绑定。

DEBUG 只有出现在受支持的注释中并作为完整关键词时才会被识别；#ifdef DEBUG、DEBUG_MODE、字符串和日志参数不会进入结果。Markdown 可识别 - [ ] 等未完成项，[x] 不进入活动结果。标记写在源码中，提交源码时也会被提交；当前没有提交前自动剥离标记的功能。缓存同样包含标记描述，但不会写入集合导出文件。

当前文件函数大纲

打开“CAtlas Hub”插件侧栏并展开“增强函数大纲”。打开源码文件后，大纲会使用当前语言扩展提供的文档符号，自动显示函数、方法、构造函数、类、接口、结构体和命名空间等内容。项目集合、可迁移功能配置和增强大纲集中在同一个插件侧栏中。

首次使用时会提示增强大纲默认位于“CAtlas Hub”插件侧栏，以及如何移动到右侧辅助侧栏。VS Code 会保存用户移动后的视图位置；执行“CAtlas Hub: 打开/定位增强函数大纲”只会聚焦这一份视图，不会创建重复大纲。升级后若资源管理器恢复了旧视图，旧视图会显示迁移入口，不会再显示空白内容。

• 单击符号跳转到对应源码位置，光标移动时当前函数会同步高亮。
• 大纲始终跟随当前活动文本文件；设置页、插件详情等非文本编辑器不会替换最后一个源码文件的大纲。
• “模式”可选择“仅原生”“仅增强”或“同时使用”；默认同时使用，避免升级后意外隐藏已有视图。
• 顶部可切换“仅函数 / 函数与类型 / 全部符号”和三种排序方式；大纲统一使用树状层级。
• 搜索只过滤当前文件中的符号，不会扫描工作区。
• 顶部直接显示“外观”下拉框，视图标题栏也有颜色按钮，可选择跟随 VS Code、Source Insight 浅色或 Source Insight 黑色；“更多”中可以控制行号、长函数和已编辑标记。
• 工作区外文件和未加入项目集合的文件同样可用；功能依赖对应语言扩展提供符号，不使用正则表达式猜测函数。

大纲模式在“配置 → 当前生效功能”中修改。集合内项目可保存集合覆盖值或跟随个人默认；集合外项目直接修改个人默认。工作区显式设置在开发期仍作为兼容覆盖保留。其他函数大纲外观和交互设置集中在“配置 → 函数大纲显示”。

配置视图会明确显示当前值、值来源以及当前工作区是否属于活动集合。增强大纲内的模式快捷选择与配置视图共用同一写入服务。

选择“仅增强”后，增强大纲内部会显示原生大纲隐藏说明，并提供“定位原生大纲”“改为同时使用”和“折叠”按钮。提示默认展开；折叠后只显示“仅增强模式已开启，原生大纲需手动隐藏”和“详情”。展开或折叠状态会在当前工作区固定保存，重载窗口及切换大纲模式后仍保持不变。

统一标识与图标风格

“配置 → 项目与资源操作 → 图标风格”提供两个选项：

• “统一领域图标”是默认值，项目集合、配置、已打开文件边界和增强函数大纲使用插件的统一 SVG 标识。
• “VS Code 原生图标”让树视图尽量回退到 ThemeIcon/Codicon；增强大纲使用同一语义图形的单色版本，以适应 Webview 无法直接复用 Codicon 字体的边界。

切换后配置树、项目集合树、已打开文件目录和增强函数大纲会立即刷新，不要求重载窗口。该选项属于本机个人外观偏好，不写入集合迁移快照。活动栏图标由扩展清单静态声明，始终使用插件产品标识；插件也不会覆盖用户的文件图标主题或修改 VS Code 工作台 CSS。

已打开文件目录与标签边界

安装后，资源管理器中会出现“已打开文件目录”。它只读取当前窗口已经打开的普通文件，不扫描工作区；单编辑器组、单根工作区时直接显示目录，多根工作区或多个编辑器组时自动增加对应根节点。连续的单子目录会压缩为 src/pages/ 形式，同一 URI 即使存在于多个编辑器组也只显示一次；点击文件节点会聚焦既有标签，不重复打开文件。

目录默认保持展开。普通误触折叠会尝试恢复；如需折叠，请使用目录右键“折叠此目录”，视图标题栏还提供全部展开、全部折叠。设置页、Diff、Notebook 和自定义编辑器不伪装为目录文件。

“配置 → 项目与资源操作 → 已打开文件视图”可以在“目录树”和“VS Code 原生”之间切换。“已打开文件目录”标题栏只提供文字形式的“隐藏原生打开的编辑器”操作；该文字按钮遵循 VS Code 默认交互，在悬停或标题区域交互时显示，不会修改全局的视图标题操作显示方式。由于 VS Code 没有公开 API 可靠检测内置视图是否可见，该操作不会伪装成隐藏/恢复开关。切回“VS Code 原生”模式时，插件再安全恢复自己隐藏的视图。隐藏命令不可用时会明确提示手动操作，不会静默失败或留下错误恢复记录。

插件按当前 VS Code 实际注册的视图命令尝试隐藏或恢复原生“打开的编辑器”，不再通过设置显示条数为 0 隐藏视图。缺少命令或执行失败时显示居中的手动说明；无法恢复时保留恢复记录。不同版本的可用命令可能不同，不承诺所有版本都能自动隐藏或恢复；扩展启动时不会主动弹窗。

原 autoOrganize 开关保留兼容，但新语义是“非项目标签自动移至末尾”：项目内标签保持用户顺序，不再按文件夹重排或着色；工作区外文件、设置页、扩展说明和其他可安全处理的非项目标签稳定置后。关闭自动模式后仍可执行“将非项目标签移到末尾”命令。

自动整理会等待 VS Code 完成活动标签切换后再移动标签：正常打开外部文件时仍显示新文件；如果用户在整理前主动切回其他文件，则保持用户最后选择的页面。

集合标签覆盖值只在集合成员项目窗口中生效，也可以清除覆盖并跟随个人默认。工作区显式 projectManager.tabs.autoOrganize 在开发期作为兼容覆盖保留；个人值用于集合外项目和未声明集合覆盖值的成员项目。配置视图会标明实际值与有效来源。

当前集合中可迁移的功能配置如下：

手动整理始终可用，不受自动开关影响。

屏蔽所选资源

1. 在 VS Code 资源管理器中单选或多选文件、目录。
2. 打开右键菜单。
3. 选择“CAtlas Hub: 屏蔽所选资源（目录、搜索与监控）”。
4. 确认后，插件按资源所属工作区根目录更新：
   • files.exclude
   • search.exclude
   • files.watcherExclude

插件只修改 VS Code 工作区设置，不删除、移动或重命名实际资源。

屏蔽规则会按目录层级自动合并：父目录已经被屏蔽时不会再加入其子项；后加入父目录时，会合并已有的重复子规则。

需要恢复时，执行“CAtlas Hub: 管理/取消屏蔽”，可单选或多选规则。若父目录曾合并已有子规则，取消父目录后会恢复原有子规则。

如果要屏蔽整个工作区中的同类型文件，可在资源管理器中选中文件并执行“CAtlas Hub: 屏蔽同类型文件（按扩展名）”。例如选中 .log 文件会写入 **/*.log；操作前会明确显示即将加入的 Glob，生成的规则同样可以从“管理/取消屏蔽”恢复。

工作区外文件提醒

当窗口已打开文件夹或工作区时，工作区外的普通文件会显示：

• 标签装饰颜色。
• ‼ 双感叹号徽标。
• 包含完整路径的悬停提示。
• 活动文件对应的状态栏提醒。
• 编辑器标题区域的警告图标。

点击状态栏提醒，或执行“CAtlas Hub: 查看工作区外文件”，可以查看并切换到当前打开的外部文件。

如果需要确认插件如何判断当前文件，可执行“CAtlas Hub: 诊断当前文件归属”。

受 VS Code 公开扩展 API 限制，标签装饰颜色只作用于标签文字或图标前景，不能将文字加粗，也不能单独修改某个标签的完整背景。插件使用红色系前景、‼ 徽标、编辑器标题警告和错误色状态栏作为补充提示。

开发

npm install
npm run check
npm run test:unit
npm run test:integration
npm run test:all

npm run test:unit 运行不依赖 VS Code 窗口的领域单元测试；npm run test:integration 使用 @vscode/test-electron 启动隔离的 Extension Development Host，验证扩展激活、命令与视图注册、真实文件打开、大纲刷新以及配置写入。首次运行会将官方 VS Code 测试实例下载到 .vscode-test，后续复用缓存；测试用户数据和扩展目录均与日常 VS Code 隔离。

全量测试范围和实际结果分别以内部开发记录 doc/单元测试清单.md、doc/集成测试清单.md 为准；这些记录不随 VSIX 分发。自动化验证不替代真实工程长时间运行和视觉验收。npm run benchmark:todo 可运行不写入磁盘的 TODO 扫描核心基准。

在 VS Code 中按 F5 可选择“运行项目管家扩展”或“运行扩展宿主集成测试”。手工验证步骤保存在项目仓库的 doc/安装验证说明.md，该开发文档不随 VSIX 分发。

本地安装与卸载

项目构建完成后，可通过 VS Code 的“扩展: 从 VSIX 安装...”命令选择生成的 .vsix 文件。

安装后的扩展标识为：

scnable.catlas-hub

需要卸载时，在扩展面板中搜索“CAtlas Hub”，打开扩展详情并选择“卸载”。

从旧身份预览版迁移

旧身份 local-development.project-butler 与新身份是两个扩展，直接安装不会自动继承集合存储。请按以下顺序迁移，不要同时启用两个版本：

1. 先安装带迁移命令的旧身份过渡包 project-butler-0.10.0-preview-test-r21.vsix，在原工作区执行“CAtlas Hub: 导出到正式版迁移文件”，保存到一个尚不存在的本地文件。
2. 停用旧版并重载窗口，再安装新身份包。仍打开原来的工作区，执行“CAtlas Hub: 导入旧身份迁移文件”，首次选择“导入全部状态”。
3. 导入只是暂存。立即重载窗口，启动时才恢复集合、项目别名、当前集合及本工作区的屏蔽恢复记录等状态；重载前不要继续修改集合或屏蔽设置。
4. 有多个工作区时，在旧版中分别导出。第一个工作区已完成迁移后，其他工作区选择“仅导入当前工作区”，不会重复写入全局集合。

迁移文件含项目路径，请勿上传到公开仓库。不导出认证材料、源文件正文、TODO 扫描缓存和临时界面状态；源码中的个人标记不受影响。同一 VS Code 配置文件中的 projectManager.* 设置继续保留，不随扩展改名重命名。

仅接受相同工作区路径及匹配版本的迁移文件；现有状态不一致时拒绝覆盖，不自动合并。写入中断时保留暂存记录，已成功写入的相同值会在下次启动跳过并继续。完成验证前保留旧版及迁移文件。

当前限制

• 标签移动依赖 VS Code 的活动编辑器移动命令，需要继续进行多组、固定标签和特殊编辑器的界面验收。
• 原生 Tree View 无法移除折叠箭头；插件通过展开恢复与右键显式折叠降低误触，极端刷新时可能降级为下次刷新恢复。
• 每个 VS Code 窗口当前只激活一个项目集合；尚未提供多个集合固定和分组管理。
• 集合与项目别名可在侧栏右键修改，项目路径可重新选择；功能配置在侧栏保存。集合导出是静态快照，编辑导出文件不会实时改变已导入集合。
• 屏蔽管理当前使用 VS Code 多选列表，尚未提供独立的图形化管理页面。
• 标签装饰是否显示还会受到 VS Code 工作台装饰设置和当前主题影响。
• 当前只统计已打开的文本文件，Notebook 等特殊编辑器将在后续版本补充。
• 代码 TODO 首版只支持明确登记的常见语言注释语法，不使用语言扩展私有 API，也不开放任意正则。
• 代码 TODO 的集合级总开关、关键词和 Markdown 设置已经接入内部存储及导入导出；个人标识、历史别名、默认关闭的项目已有标记、高亮和快捷键不会进入集合。扫描失败会恢复上一份有效结果并标记可能过期；未扫描、无结果、筛选无结果、部分结果、取消和失败状态均独立反馈。1k/5k/20k 内存扫描基准已经建立，真实磁盘与远程环境仍需分别验收。条件式 files.exclude（when）不会被错误当作无条件排除规则。