# log

**Repository Path**: hgdhgdg54692/log

## Basic Information

- **Project Name**: log
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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）

| 设置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `codeChangeLogbook.customPath` | `string` | `""` | 日志与快照保存的本地文件夹（按工作区设置；首次使用必须配置） |
| `codeChangeLogbook.maxEntries` | `number` | `2000` | 最大保留日志条数，超过后自动清理最旧记录 |

---

## 命令列表（Command Palette）

| 命令 | 说明 |
|---|---|
| `代码修改日志本: 打开` | 打开日志本侧边栏 |
| `代码修改日志本: 选择日志保存文件夹` | 选择日志/快照保存文件夹 |
| `代码修改日志本: 手动上传(立即生成日志)` | 手动上传（立即生成一条日志） |
| `代码修改日志本: 清理最终版本之前的历史` | 清理最终版本之前的历史（需先确认最终版本） |
| `代码修改日志本: 打开记录详情` | 打开某条记录详情（通常由 UI 触发） |
| `代码修改日志本: 回退到此版本` | 回退到该条记录（通常由详情页触发） |
| `代码修改日志本: 删除此条记录` | 删除该条记录（通常由详情页触发） |

---

## 注意事项（务必阅读）

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