介绍

CAtlas Hub 是一款面向代码工程浏览与管理的 VS Code 扩展，提供项目集合、已打开文件目录、增强函数大纲、个人 TODO 标记和配置导入导出等功能。目前，1.0.0 正式版已发布到 VS Code 插件市场和 GitHub，源码采用 MIT 许可证开放。

开发这款扩展，起初是为了把分散在不同目录中的项目集中起来，用更直观的别名选择和打开。随着日常使用，需求逐渐延伸到项目打开之后：文件多了怎么找，长文件里的函数怎么定位，自己的待办如何不被工程原有的注释淹没。

CAtlas Hub 希望把这些反复发生的小操作组织好，让“找项目、找文件、找函数、找待办”更顺手。它不替代编译器、调试器或语言扩展，而是补充日常项目管理和代码阅读的体验。

使用场景

在多个工程之间切换

主工程、驱动库、测试程序和参考源码往往分散在不同位置，目录名还可能带着版本号。把它们加入同一个集合，设置容易理解的别名，可以减少反复查找路径的操作。

同时阅读较多文件

标签越来越多，或者多个目录中都有同名文件时，单看标签名很难判断文件归属。通过已打开文件目录，可以看到当前正在阅读的文件及其目录关系，而不必在完整工程目录里重新寻找。

对照工作区外的参考代码

临时打开另一个版本的实现或其他工程中的文件时，容易把参考文件和当前项目文件混淆。外部文件提醒与非项目标签置后，可以提供额外的归属提示。

阅读函数较多的源码文件

在函数、类型和条件编译分支之间反复跳转时，增强函数大纲可以帮助理解当前文件结构，并快速定位源码。

在大型或开源项目中跟踪自己的任务

工程自带的 TODO 不一定是当前需要处理的任务。通过个人标识筛选，再按任务描述归类，可以优先找到自己添加的标记，把同一任务涉及的多个文件放在一起查看。

功能介绍

项目集合与别名管理

常用文件夹和工作区可以加入项目集合，并设置别名、说明与标签。首次使用时，在侧栏选择“添加项目并创建集合”，即可完成集合和第一个项目的创建，不需要先编写配置文件。

已有集合和项目别名支持右键修改，项目路径可以重新选择，也可以将项目移出集合。打开项目时，可以选择当前窗口或新窗口，并保存常用打开方式。

已打开文件目录与标签整理

“已打开文件目录”位于资源管理器中，只读取当前窗口已经打开的普通文件，不扫描整个工程。连续的单层目录会合并显示，减少逐层展开的负担；点击文件条目会回到既有标签。

目录默认展开，需要折叠时可以使用右键操作。相比完整工程目录，这个视图更关注“当前正在看哪些文件”。

标签整理不强制改变项目内文件的顺序。启用“非项目标签自动移至末尾”后，插件会把工作区外文件、设置页等可安全处理的非项目标签放到后方，保留用户自己的项目阅读顺序。

工作区外文件提醒

对于不属于当前工作区的普通文件，插件提供前景色、‼ 徽标、悬停路径和状态栏等提示，帮助区分正在编辑的文件与临时打开的参考文件。

提醒用于辅助判断，不会禁止编辑，也不能代替对实际文件路径的确认。

增强函数大纲

增强函数大纲提供树状符号列表，支持筛选、排序和源码跳转。函数条目只显示名称，不把长参数列表挤进侧栏；点击后会在源码中提示定位位置，光标移动时也会同步标识当前函数。

对于支持的 C/C++ 场景，大纲会整理条件编译层级和部分重复符号，使结构更容易阅读。

外观可以跟随 VS Code，也可以选择借鉴 Source Insight 阅读习惯的浅色或黑色预设。大纲模式支持仅原生、仅增强或同时使用，用户可以根据习惯选择。

个人 TODO 与任务分类

设置一个简短个人标识后，可以通过编辑器右键“快速标记”添加注释，例如：

1
2
// TODO(dev): 添加串口超时处理
// FIXME(dev): 修复异常返回路径

这里的 dev 只是示例，不需要使用真实姓名或邮箱。

“代码 TODO”视图默认按任务描述分类。同一任务出现在多个文件中时，可以集中查看；添加标记时也能选择已有描述，减少相同任务被不同措辞拆开的情况。点击结果即可定位源码。

除常见的 TODO、FIXME 等关键词外，还可以启用 DEBUG、NOTE、OPTIMIZE 等可选项，或添加简单自定义关键词。注释里的 DEBUG 可以作为标记，但 #ifdef DEBUG 不会仅因包含该单词就进入待办结果。

默认只显示个人标记，需要查看工程已有标记时，可在设置中开启。更新时优先恢复本地缓存并检查变化，打开文档中的编辑优先响应，后台文件变化分批处理；同时保留完整更新入口。

资源屏蔽与恢复

在资源管理器中选择文件或目录，可以通过右键屏蔽资源，调整目录展示、搜索和文件监控的排除设置，也可以按扩展名屏蔽同类型文件。

屏蔽不会删除实际文件。规则会处理父子目录的重复关系，需要恢复时，可以通过“管理/取消屏蔽”入口操作。

集中配置与导入导出

常用设置集中在侧栏“配置”视图，选择后保存并应用，各分组可以折叠。

插件区分当前工作区是否属于所选集合：集合内项目可以使用集合配置，其他项目使用个人默认值，界面会显示实际生效的设置来源。图标风格也可以在统一图标与原生风格之间切换。

需要迁移时，可将项目集合导出为快照，再在另一台设备上导入。项目路径不同，可以在导入时调整基础目录。个人标识、部分外观偏好等本机设置不会随集合迁移。

兼容性与注意事项

运行环境与语言支持

  • 要求 VS Code 1.88.0 及以上，目前主要验证环境为 Windows；其他操作系统和真实远程、虚拟工作区尚未完成验证。
  • 增强函数大纲依赖对应语言扩展提供文档符号。例如 C/C++ 工程需要语言扩展正常工作；语言解析没有结果时，增强大纲不能凭空恢复完整函数结构。
  • TODO 只识别受支持语言中的注释语法，不开放任意正则表达式，也不保证识别所有历史文本编码。

界面能力边界

  • VS Code 的公开扩展接口不能任意修改单个标签的完整背景、加粗标签文字或绘制分组边框，文件装饰的显示还会受到主题与相关设置影响。
  • 原生视图的隐藏和恢复受 VS Code 版本及可用命令限制。选择“仅增强”不代表所有版本都能自动隐藏原生大纲，必要时需按提示手动操作。
  • 已打开文件目录主要展示普通文件，设置页、Diff、Notebook 和自定义编辑器不会被当作普通目录文件展示。

扫描与性能边界

  • 超过 2 MiB 的源码文件默认跳过，其他文件继续处理。
  • 扫描受结果数量、缓存大小和并发限制，不承诺任意规模工程都能无限扫描。
  • 开启“显示项目已有标记”可能增加结果数量和扫描开销，大型或开源工程建议按实际需要使用。

数据、迁移与隐私

  • TODO 是真实的源码注释，提交代码时也会被提交。1.0.0 没有提交前自动剥离功能，不能把它当作仅存在于本机的私人便签。
  • TODO 缓存保存在本机工作区扩展存储中，包含文件位置与标记描述，不包含整份源码。共享扩展存储或日志前仍需注意隐私。
  • 集合迁移仅涉及项目入口和相关插件配置，不会复制源码、安装编译器或自动配置另一台电脑的开发环境。
  • 导出及迁移文件可能包含项目路径，共享前应检查内容；导出文件是静态快照，修改它不会实时改变已导入的集合。
  • 使用旧身份预览版的用户，应先阅读发布说明中的迁移要求，不要直接卸载旧版，也不要同时启用新旧扩展。

使用方式与下载地址

安装

在 VS Code 扩展视图中搜索 CAtlas Hub，确认发布者为 scnable，即可安装。也可以通过以下入口下载或查看源码：

从 GitHub 下载 catlas-hub-1.0.0.vsix 后，在 VS Code 扩展视图菜单中选择“从 VSIX 安装”，再按提示完成安装和窗口重载。

首次使用

  1. 打开活动栏中的 CAtlas Hub，选择“添加项目并创建集合”，加入常用文件夹或工作区并设置别名。
  2. 打开几份源码，在资源管理器中查看“已打开文件目录”。
  3. 按需要在 CAtlas Hub 侧栏启用或调整增强函数大纲，确认对应语言扩展能够提供符号。
  4. 在“配置 → 代码 TODO”中设置个人标识，通过编辑器右键添加一条快速标记，再到资源管理器的“代码 TODO”视图中查看。
  5. 根据阅读习惯调整外部文件提醒、非项目标签置后和资源屏蔽等选项，不必一次开启全部功能。

1.0.0 是正式发布的起点，后续会继续根据真实工程中的反馈改进稳定性、扫描体验和界面一致性。遇到问题或有功能建议，可以通过 GitHub Issues 反馈；请描述使用场景与复现步骤，不要附带私密源码、凭据或未经处理的个人路径。