gee-coder · gee-coder · Mar 24, 2026 · Mar 24, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,46 @@
 All notable changes to this project will be documented in this file.
 本项目的重要变更会记录在这里。
 
+## [1.1.0] - TBD
+
+### Breaking
+
+- **Gutter color indicators now default to hidden** on extension activation
+  - Previously: When `git-blms.enabled=true`, both gutter indicators and inline annotations were shown
+  - Now: When `git-blms.enabled=true`, only inline annotations are shown by default; gutter must be enabled via right-click menu
+- **Right-click menu commands no longer modify `git-blms.enabled` setting**
+  - Previously: Clicking "Show Inline Git Blame" or "Show Git Gutter" would automatically set `git-blms.enabled=true` in settings.json
+  - Now: These commands only work when `git-blms.enabled=true`; they no longer change the setting
+
+### Changed
+
+- `git-blms.enabled` now only controls inline annotation display state on startup, not gutter
+- Gutter display state is not persisted; each session starts with gutter hidden
+
+### 重大变更
+
+- **Gutter 颜色指示器现在默认隐藏**
+  - 之前：当 `git-blms.enabled=true` 时，gutter 指示器和行内注释都会显示
+  - 现在：当 `git-blms.enabled=true` 时，只有行内注释默认显示；gutter 需要通过右键菜单启用
+- **右键菜单命令不再修改 `git-blms.enabled` 设置**
+  - 之前：点击 "Show Inline Git Blame" 或 "Show Git Gutter" 会自动将 settings.json 中的 `git-blms.enabled` 设为 `true`
+  - 现在：这些命令仅在 `git-blms.enabled=true` 时生效；不再修改该设置
+
+### 变更
+
+- `git-blms.enabled` 现在只控制启动时行内注释的显示状态，不影响 gutter
+- Gutter 显示状态不持久化；每次会话启动时 gutter 默认隐藏
+
+### Migration / 迁移
+
+To restore previous behavior:
+1. Set `"git-blms.enabled": true` in settings.json
+2. Right-click in editor → "Show Git Gutter" to enable color indicators
+
+恢复之前行为的方法：
+1. 在 settings.json 中设置 `"git-blms.enabled": true`
+2. 右键点击编辑器 → "Show Git Gutter" 启用颜色指示器
+
 ## [1.0.2] - 2026-03-23
 
 ### Added

diff --git a/openspec/changes/archive/2026-03-24-refactor-enable-semantics/.openspec.yaml b/openspec/changes/archive/2026-03-24-refactor-enable-semantics/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-24
diff --git a/openspec/changes/archive/2026-03-24-refactor-enable-semantics/design.md b/openspec/changes/archive/2026-03-24-refactor-enable-semantics/design.md
@@ -0,0 +1,176 @@
+## Context
+
+### 当前实现
+
+当前 `git-blms.enabled` 配置有双重语义，既控制扩展是否工作，又影响默认显示状态。代码实现中存在以下问题：
+
+1. **命令修改设置**: `extension.ts` 中的 `showBlame` 和 `showGutter` 命令会检查 `config.enabled`，如果为 false 则调用 `setEnabled(true)` 修改 settings.json
+2. **初始化耦合**: `initialize()` 函数在 `enabled=true` 时同时设置 `gutterEnabled=true` 和 `annotationEnabled=true`
+3. **状态关系不清**: `enabled`、`gutterEnabled`、`annotationEnabled` 三者的关系和优先级不明确
+
+### 架构约束
+
+- VS Code 扩展 API 限制: 运行时状态不自动持久化
+- 用户体验: 右键菜单应该是临时操作，不应该修改全局设置
+- 配置语义: `enabled` 应该是简单的布尔开关，不应承载过多含义
+
+## Goals / Non-Goals
+
+**Goals:**
+- 重新定义 `git-blms.enabled` 为仅控制 Blame (inline annotations) 的启动状态
+- Gutter 默认隐藏，由用户通过右键菜单按需启用
+- 右键菜单命令只控制运行时状态，不修改 settings.json
+- 每次重启根据 `enabled` 重新初始化，不保存运行时状态
+
+**Non-Goals:**
+- 不添加新的持久化状态存储 (workspaceState/globalStorage)
+- 不改变 `showGutter`/`hideGutter`/`showBlame`/`hideBlame` 命令的基本功能
+- 不修改 Gutter 和 Blame 的渲染逻辑
+
+## Decisions
+
+### Decision 1: 启动时 Gutter 默认隐藏
+
+**选择**: 初始化时 `gutterEnabled` 始终为 `false`
+
+**理由**:
+- Gutter 颜色指示器是辅助功能，不是核心功能
+- 减少视觉干扰，用户可以按需启用
+- 与 `enabled` 配置解耦
+
+**替代方案**:
+- 添加单独的 `gutterEnabled` 配置项 → 拒绝，增加配置复杂度
+- 保存上次运行时状态 → 拒绝，用户要求每次重新初始化
+
+### Decision 2: `enabled` 仅控制 Blame 启动状态
+
+**选择**: `annotationEnabled` 初始值 = `enabled`，`gutterEnabled` 初始值 = `false`
+
+**理由**:
+- Blame (inline annotations) 是扩展的核心功能
+- 用户习惯通过 `enabled` 控制主要功能的开关
+- 保持配置语义简单清晰
+
+**状态关系图**:
+```
+启动时:
+  enabled=true  → annotationEnabled=true, gutterEnabled=false
+  enabled=false → annotationEnabled=false, gutterEnabled=false
+
+运行时:
+  showBlame/hideBlame → 只改变 annotationEnabled
+  showGutter/hideGutter → 只改变 gutterEnabled
+  都不修改 enabled
+```
+
+### Decision 3: 右键菜单命令不修改 settings
+
+**选择**: 移除 `setEnabled()` 调用，命令直接设置运行时状态
+
+**当前行为** (extension.ts:44-67):
+```typescript
+registerCommand(COMMAND_SHOW_BLAME, async () => {
+  const config = getExtensionConfig();
+  if (!config.enabled) {
+    await setEnabled(true);  // ← 修改 settings
+  }
+  dm.setAnnotationEnabled(true);
+  await updateAnnotationEnabledContext(true);
+});
+```
+
+**新行为**:
+```typescript
+registerCommand(COMMAND_SHOW_BLAME, async () => {
+  const config = getExtensionConfig();
+  if (!config.enabled) {
+    return;  // 不显示，但不修改设置
+  }
+  dm.setAnnotationEnabled(true);
+  await updateAnnotationEnabledContext(true);
+});
+```
+
+**理由**:
+- 用户期望右键菜单是临时操作
+- 避免意外修改配置文件
+- 简化命令逻辑
+
+### Decision 4: 不使用 workspaceState 保存运行时状态
+
+**选择**: 每次重启根据 `enabled` 重新初始化
+
+**理由**:
+- 用户明确要求不保存状态
+- 减少状态管理的复杂度
+- `enabled` 配置已足够控制启动行为
+
+## Risks / Trade-offs
+
+### Risk 1: 用户期望状态持久化
+
+**描述**: 用户可能期望运行时的 show/hide 操作在重启后保持
+
+**缓解**:
+- 发布说明中明确说明行为变更
+- `enabled` 配置提供足够控制能力
+
+### Risk 2: enabled=false 时命令无响应
+
+**描述**: 当 `enabled=false` 时，右键菜单命令可能无任何效果，用户困惑
+
+**缓解**:
+- 当 `enabled=false` 时，相关菜单项通过 `when` 子句自动隐藏
+- 当前 `package.json` 已有 `when: "gitBlms.enabled"` 控制
+
+### Risk 3: BREAKING 变更影响现有用户
+
+**描述**: Gutter 默认从显示变为隐藏
+
+**缓解**:
+- 发布说明中明确告知
+- 用户可以通过右键菜单重新启用 Gutter
+
+## Migration Plan
+
+### 代码变更
+
+1. **修改 `extension.ts` 初始化逻辑**:
+   ```typescript
+   // 旧代码 (line 161-165)
+   decoratorManager.setGutterEnabled(true);
+   decoratorManager.setAnnotationEnabled(true);
+
+   // 新代码
+   decoratorManager.setGutterEnabled(false);
+   decoratorManager.setAnnotationEnabled(enabled);
+   ```
+
+2. **修改右键菜单命令**:
+   - `COMMAND_SHOW_BLAME`: 移除 `setEnabled(true)` 调用
+   - `COMMAND_SHOW_GUTTER`: 移除 `setEnabled(true)` 调用
+
+3. **更新 spec 文档**:
+   - 修改 `openspec/specs/display-mode-control/spec.md` 中的默认状态场景
+
+### 发布说明
+
+```
+BREAKING: Gutter 颜色指示器现在默认隐藏
+
+- 之前: 启用扩展时 Gutter 和 Blame 都显示
+- 之后: 启用扩展时只有 Blame 显示，Gutter 需要通过右键菜单启用
+
+右键菜单命令不再修改 git-blms.enabled 设置
+
+- 之前: 点击 "Show Inline Git Blame" 会自动启用扩展
+- 之后: 只有当 git-blms.enabled=true 时命令才生效
+
+如需恢复之前的行为:
+1. 在 settings.json 中设置 "git-blms.enabled": true
+2. 使用右键菜单 → "Show Git Gutter" 启用颜色指示器
+```
+
+### 回滚策略
+
+如果出现问题，可以通过 git revert 回退到变更前的 commit
diff --git a/openspec/changes/archive/2026-03-24-refactor-enable-semantics/proposal.md b/openspec/changes/archive/2026-03-24-refactor-enable-semantics/proposal.md
@@ -0,0 +1,62 @@
+## Why
+
+当前 `git-blms.enabled` 配置的语义不清晰，右键菜单命令会修改全局设置，导致用户体验混乱。
+
+**问题 1: 右键菜单修改全局设置**
+- 点击 "Show Inline Git Blame" 或 "Show Git Gutter" 会自动调用 `setEnabled(true)` 修改 settings.json
+- 用户只想临时显示某个功能，不需要持久化修改配置
+
+**问题 2: `enabled` 语义不清**
+- 当前实现中 `enabled` 同时控制扩展是否工作以及默认显示状态
+- Gutter 和 Blame (inline annotations) 都受 `enabled` 影响，但用户希望独立控制
+
+**问题 3: 启动默认行为不符合预期**
+- 用户希望: Gutter 默认隐藏，`enabled` 只控制 Blame 的启动状态
+- 当前实现: `enabled=true` 时同时启用 Gutter 和 Blame
+
+## What Changes
+
+1. **重新定义 `git-blms.enabled` 语义**
+   - `enabled` 仅控制重启时 Blame (inline annotations) 的默认显示状态
+   - 不控制 Gutter 颜色指示器
+
+2. **修改启动默认行为**
+   - Gutter 默认隐藏 (`gutterEnabled = false`)
+   - Blame 默认状态由 `enabled` 配置决定 (`annotationEnabled = enabled`)
+
+3. **右键菜单命令不修改 settings**
+   - `showBlame`/`hideBlame` 只设置运行时状态，不调用 `setEnabled()`
+   - `showGutter`/`hideGutter` 只设置运行时状态，不调用 `setEnabled()`
+
+4. **运行时状态不持久化**
+   - 每次重启根据 `enabled` 重新初始化
+   - 运行时的 show/hide 不保存到配置
+
+## Capabilities
+
+### New Capabilities
+无新功能
+
+### Modified Capabilities
+
+- **`display-mode-control`**: 修改默认启动行为和命令执行逻辑
+  - **旧**: 默认同时启用 Gutter 和 Blame；命令可能修改 `enabled` 设置
+  - **新**: Gutter 默认隐藏，Blame 默认由 `enabled` 控制；命令不修改设置
+
+- **`extension-lifecycle`**: 修改初始化逻辑
+  - **旧**: 初始化时如果 `enabled=true`，同时启用 Gutter 和 Blame
+  - **新**: 初始化时 Gutter 永远默认隐藏，Blame 由 `enabled` 决定
+
+## Impact
+
+- **修改文件**:
+  - `src/extension.ts`: 修改命令注册和初始化逻辑
+  - `openspec/specs/display-mode-control/spec.md`: 更新默认行为场景
+
+- **行为变更** (BREAKING):
+  - 用户升级后，Gutter 将默认隐藏（之前是默认显示）
+  - 右键菜单命令不再自动启用扩展并保存设置
+
+- **用户体验改进**:
+  - 右键菜单行为更符合直觉：只控制显示/隐藏
+  - `enabled` 配置语义更清晰：仅控制 Blame 启动状态
diff --git a/...archive/2026-03-24-refactor-enable-semantics/specs/display-mode-control/spec.md b/...archive/2026-03-24-refactor-enable-semantics/specs/display-mode-control/spec.md
@@ -0,0 +1,62 @@
+## MODIFIED Requirements
+
+### Requirement: 独立显示状态管理
+系统 MUST 在内存中维护两个独立的布尔状态，分别控制 Gutter 颜色指示器和行内注释。
+
+#### Scenario: 默认状态
+- **WHEN** 扩展首次启用或用户重启 VS Code 后
+- **THEN** 系统 SHALL 默认禁用 Gutter 颜色指示器
+- **AND** `gutterEnabled` SHALL 为 `false`
+- **AND** 系统 SHALL 根据 `git-blms.enabled` 配置决定行内注释状态
+- **AND** `annotationEnabled` SHALL 等于 `git-blms.enabled` 的值
+
+#### Scenario: 状态存储
+- **WHEN** 显示状态发生变化
+- **THEN** 系统 SHALL 在 DecoratorManager 实例的内存中存储当前状态
+- **AND** 状态 SHALL 不持久化到配置文件
+
+### Requirement: Gutter 颜色指示器独立控制
+系统 MUST 允许用户独立控制 Gutter 颜色指示器的显示，不影响行内注释。
+
+#### Scenario: 启用 Gutter 颜色指示器
+- **GIVEN** `git-blms.enabled` 为 `true`
+- **WHEN** 用户执行 `git-blms.showGutter` 命令
+- **THEN** 系统 SHALL 设置 `gutterEnabled` 为 `true`
+- **AND** 系统 SHALL 在 gutter 区域显示颜色指示器
+- **AND** 系统 SHALL 不改变行内注释的状态
+- **AND** 系统 SHALL 不修改 `git-blms.enabled` 配置
+
+#### Scenario: 禁用 Gutter 颜色指示器
+- **WHEN** 用户执行 `git-blms.hideGutter` 命令
+- **THEN** 系统 SHALL 设置 `gutterEnabled` 为 `false`
+- **AND** 系统 SHALL 清除所有 gutter 区域的颜色指示器
+- **AND** 系统 SHALL 不改变行内注释的状态
+- **AND** 系统 SHALL 不修改 `git-blms.enabled` 配置
+
+#### Scenario: Gutter 关闭时的渲染
+- **WHEN** `gutterEnabled` 为 `false`
+- **THEN** 系统 SHALL 不在 gutter 区域显示任何颜色指示器
+- **AND** 系统 SHALL 清除所有已有的 gutter 装饰
+
+### Requirement: 行内注释独立控制
+系统 MUST 允许用户独立控制行内注释的显示，不影响 Gutter 颜色指示器。
+
+#### Scenario: 启用行内注释
+- **GIVEN** `git-blms.enabled` 为 `true`
+- **WHEN** 用户执行 `git-blms.showBlame` 命令
+- **THEN** 系统 SHALL 设置 `annotationEnabled` 为 `true`
+- **AND** 系统 SHALL 在代码行首显示日期和用户名注释
+- **AND** 系统 SHALL 不改变 Gutter 颜色指示器的状态
+- **AND** 系统 SHALL 不修改 `git-blms.enabled` 配置
+
+#### Scenario: 禁用行内注释
+- **WHEN** 用户执行 `git-blms.hideBlame` 命令
+- **THEN** 系统 SHALL 设置 `annotationEnabled` 为 `false`
+- **AND** 系统 SHALL 清除所有行内注释装饰
+- **AND** 系统 SHALL 不改变 Gutter 颜色指示器的状态
+- **AND** 系统 SHALL 不修改 `git-blms.enabled` 配置
+
+#### Scenario: 行内注释关闭时的渲染
+- **WHEN** `annotationEnabled` 为 `false`
+- **THEN** 系统 SHALL 不显示任何行内注释（日期和用户名）
+- **AND** 系统 SHALL 清除所有已有的行内注释装饰
diff --git a/.../archive/2026-03-24-refactor-enable-semantics/specs/extension-lifecycle/spec.md b/.../archive/2026-03-24-refactor-enable-semantics/specs/extension-lifecycle/spec.md
@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: 扩展启动初始化
+扩展激活时 MUST 根据 `git-blms.enabled` 配置正确初始化显示状态。
+
+#### Scenario: enabled=true 时初始化
+- **GIVEN** `git-blms.enabled` 配置为 `true`
+- **WHEN** 扩展的 `activate()` 函数执行完成
+- **THEN** 系统 SHALL 设置 `annotationEnabled` 为 `true`
+- **AND** 系统 SHALL 设置 `gutterEnabled` 为 `false`
+- **AND** 系统 SHALL 更新 `gitBlms.annotationEnabled` 上下文键为 `true`
+- **AND** 系统 SHALL 更新 `gitBlms.gutterEnabled` 上下文键为 `false`
+
+#### Scenario: enabled=false 时初始化
+- **GIVEN** `git-blms.enabled` 配置为 `false`
+- **WHEN** 扩展的 `activate()` 函数执行完成
+- **THEN** 系统 SHALL 设置 `annotationEnabled` 为 `false`
+- **AND** 系统 SHALL 设置 `gutterEnabled` 为 `false`
+- **AND** 系统 SHALL 更新 `gitBlms.annotationEnabled` 上下文键为 `false`
+- **AND** 系统 SHALL 更新 `gitBlms.gutterEnabled` 上下文键为 `false`
+
+#### Scenario: 不保存运行时状态
+- **WHEN** 用户通过右键菜单改变显示状态后重启 VS Code
+- **THEN** 系统 SHALL 忽略之前的运行时状态
+- **AND** 系统 SHALL 根据 `git-blms.enabled` 配置重新初始化