Ghost Annotations

让注释像幽灵一样时隐时现 — VS Code 扩展，一键隐藏/恢复代码中的注释。

功能特性

• 一键隐藏：删除当前文件中所有注释及注释产生的空行，保留与注释无关的空行
• 一键恢复：将隐藏的注释精确回填到原始位置，即使代码已被大幅修改
• 增量隐藏：隐藏状态下新增的注释会自动合并到备份中，再次点击统一恢复
• 多语言支持：覆盖 40+ 编程语言的行注释和块注释
• Git 友好：自动将备份文件加入 .gitignore，避免污染版本控制

工作原理

采用 字符级剥离与 Diff 映射锚定法，彻底摆脱行号和上下文匹配的局限。

隐藏流程

1. 用正则提取文件中所有注释，记录每段注释在原文中的字符级起止位置
2. 剥离注释，拼接得到纯代码快照（originalStrippedText）
3. 计算每段注释在纯代码中的绝对字符偏移量（strippedOffset）
4. 将纯代码快照和注释列表存入 ghost.json，编辑器内容替换为纯代码

恢复流程

1. 读取备份的纯代码快照，与编辑器当前内容执行 diffChars 字符级差异对比
2. 构建映射表：旧纯代码中第 N 个字符 → 当前代码中第 M 个字符
3. 按偏移量从大到小排序，从后往前将注释插回当前代码（避免偏移量互相干扰）

为什么稳定

• 不依赖行号、上下文匹配或任何语义分析
• 无论用户重构、格式化、增删代码，Diff 算法自动追踪字符位移
• 从后往前插入的设计保证多个注释的回填互不影响

支持的语言

使用方式

1. 在编辑器中打开任意代码文件
2. 点击编辑器标题栏的 Toggle 按钮（或通过命令面板执行 Ghost Comments: Toggle）
3. 首次使用时会提示初始化，自动创建 ghost.json 和 .ghost-comments/ 目录
4. 再次点击恢复所有注释

状态切换逻辑：

[未隐藏] --点击--> [已隐藏]
[已隐藏] --点击（无新注释）--> [未隐藏]  恢复所有注释
[已隐藏] --点击（有新注释）--> [已隐藏]  新注释合并到备份，再次点击恢复

备份文件结构

初始化后在工作区根目录创建：

workspace/
├── ghost.json              # 注释备份数据（自动加入 .gitignore）
└── .ghost-annotations/        # 备份目录（自动加入 .gitignore）

ghost.json 数据结构：

{
  "files": {
    "src/example.ts": {
      "languageId": "typescript",
      "hiddenAt": "2025-01-01T00:00:00.000Z",
      "originalStrippedText": "// 剥离注释后的纯代码快照",
      "comments": [
        {
          "content": "// 这是一条注释\n",
          "strippedOffset": 42
        }
      ]
    }
  }
}

开发

环境要求

• Node.js
• VS Code

常用命令

npm install            # 安装依赖
npm run compile        # 类型检查 + Lint + 构建
npm run watch          # 监听模式（esbuild + tsc 并行）
npm run package        # 生产构建
npm test               # 运行测试

项目结构

src/
├── extension.ts       # 扩展入口，注册命令
├── ghostManager.ts    # 核心逻辑：隐藏、恢复、Diff 映射
├── types.ts           # 数据结构定义
└── test/
    └── extension.test.ts

许可

MIT