Code Change Logbook（代码修改日志本）

一个 VS Code / Windsurf 扩展：用于在本地自动记录代码修改历史，并以 IDE 内置“日志本”方式展示。支持：

• 自动记录（保存后延时汇总）
• 手动上传（立即生成一条“当前工作区汇总日志”）
• 查看详情（支持按文件切换查看 Diff + 每个文件的改动概览）
• 回退到任意版本（按快照恢复）
• 设置新起点（V0.x 重新从 1 计数，但不篡改旧日志）
• 确认最终版本 + 一键清理历史（保留最终版本之后的记录）

使用入口（侧边栏）

在活动栏点击 “日志本” 图标进入侧边栏视图（Webview 美化界面）。

顶部信息区

• 当前最终版本：显示你在任意详情页点击“确认最终版本”后得到的版本号（例如 V0.8）。
• 保存路径：显示当前工作区日志/快照存储目录，并提供“复制”。

顶部按钮区（你截图里那几个按钮）

1) 选择日志保存文件夹

用途：为当前工作区选择一个固定的本地存储目录（推荐放在大容量磁盘）。

• 点击后会弹出文件夹选择器
• 选择完成后：
  • 立即开始记录（自动/手动上传都会写入此目录）
  • 侧边栏会显示“保存路径”

注意：路径是按工作区级别保存（Workspace Setting）。不同项目可以用不同目录。

2) 手动上传（立即生成日志）

用途：不想等自动延时，直接生成一条日志。

• 会扫描当前工作区所有文件（与上一条日志快照对比）
• 将“本次工作区所有改动的文件”汇总到同一条日志里
• 生成后会出现在日志列表顶部

3) 清理最终版本之前的历史

用途：当你已经确认了一个“最终版本”，希望只保留最终版本及之后的历史，清掉更早的记录与快照。

• 只有在你先在详情页点击过“确认最终版本”后才可用
• 操作会删除大量历史文件，执行前会弹确认框

自动记录机制（非常重要）

为了避免“每次 Ctrl+S 都生成一条”导致日志爆炸，插件采用延时汇总策略：

• 当你保存任意文件后，并不会立刻生成日志
• 只有在你停止保存/修改一段时间后（默认约 3 分钟），才会自动生成一条“工作区汇总日志”

你也可以随时用“手动上传”强制立即生成。

日志列表（侧边栏下方）

• 日志按日期分组
• 每条日志显示：
  • 时间
  • 摘要（汇总描述）
  • 版本号（如果属于新起点之后，会显示 V0.x）
• 每条日志只有一个操作：“详情”（打开详情页）

详情页（打开“详情”后）

详情页用于查看“这一条日志”里所有文件的改动，并提供关键操作按钮。

• 多文件变更：顶部提供文件 Tab（文件名 + +/- 行数），可点击切换，仅展示当前文件的 Diff
• 单文件变更：直接展示该文件 Diff

详情页按钮说明

1) 回退到此版本

• 会将该条日志记录时保存的快照，恢复到工作区对应文件
• 对于“工作区汇总日志”，会对其中所有变更文件逐个回退

注意：回退会直接覆盖当前文件内容。建议：

• 回退前先提交 Git / 复制备份
• 确认没有未保存的编辑缓冲区内容

2) 设为新起点

用途：让版本号从这一条开始重新计数。

• 设为新起点后：
  • 这条日志显示为 V0.1
  • 后续日志显示为 V0.2、V0.3...
  • 新起点之前的旧日志不再显示版本号（但日志仍保留，不会被修改）

这是“动态版本号”的核心：版本号是展示层计算出来的，不会篡改历史。

3) 确认最终版本

用途：标记一个“最终版本”，用于主界面展示，并允许“一键清理最终版本之前的历史”。

• 被标记为最终版本的日志会显示“最终版本”徽章
• 清理历史时会以此为边界

4) 删除此条记录

• 删除当前这条日志记录
• 同时会删除该条记录对应的快照文件

版本号规则（V0.x）

插件显示的 V0.x 是动态计算的显示版本号：

• 当项目里还没有任何日志时，第一条日志会自动成为新起点，并显示 V0.1
• 如果你后续手动点了“设为新起点”，则以你选择的那条作为新的 V0.1
• 新起点之前的日志：不显示版本号（策略：避免歧义）

安装方式（VSIX）

1. 打开 Windsurf / VS Code
2. 命令面板（Ctrl+Shift+P）输入 Extensions: Install from VSIX...
3. 选择打包生成的 code-change-logbook-0.0.x.vsix
4. 重载窗口后，在活动栏看到 “日志本” 图标即可使用

设置项（Settings）

命令列表（Command Palette）

注意事项（务必阅读）

• 回退是高风险且不可逆的写文件操作：会覆盖当前文件内容。建议回退前先 Git 提交或复制备份。
• 首次使用必须先选择保存路径：未设置 customPath 时不会生成日志。
• 磁盘空间占用：每条日志会为变更文件保存快照；项目大、变更多时占用会增长很快。
  • 建议：
    • 合理设置 maxEntries
    • 定期通过“清理最终版本之前的历史”做一次归档式清理
• 仅限本地：当前版本所有数据存储在本地磁盘，不涉及云端上传。
• 性能提示：手动上传会扫描工作区文件并对比快照，大项目可能需要一定时间。