ThreeFish-AI · ThreeFish-AI · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 
 ### Added
 
+- **Claude Code 配置（Agentic Git 预置）**：新增两项与 Claude Code 相关的配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① 设置项 `hyperGit.claudeCode.executablePath`（Claude Code CLI 可执行路径，**留空=从 `PATH` 自动探测 `claude`**；描述内嵌 `command:` 链接就地提供「浏览 / 打开 Claude 设置」）；② 命令 `hyperGit.setClaudeCodePath`（QuickPick：Browse 文件选择器写回 / **Use system Claude Code** 清空覆盖）与 `hyperGit.openClaudeSettings`（打开 `~/.claude/settings.json`，缺失时经确认创建 `{}`）。采用**原生设置 + 命令**承载（零新增 Webview 面板），路径解析下沉纯函数 [`engine/agent/claude-path.ts`](./src/engine/agent/claude-path.ts)（Vitest 可测），命令实现见 [`adapter/claude-commands.ts`](./src/adapter/claude-commands.ts)。**仅落地配置与快捷入口**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。同步校正 README 指标行（`6 视图 · 101 命令 · 7 配置项 · 372 单元测试`，此前 `97 命令 / 324 测试` 已滞后 HEAD）。完整叙述见 [Claude Code 配置](./docs/features/claude-code-config.md)。
 - **Branches 视图按 `/` 前缀分组为文件夹树**：Local / Remote / Tags 三段支持在**平铺**与**按 `/` 前缀分组的可折叠文件夹树**间切换——共享前缀的分支收拢到以前缀命名的文件夹下、叶子仅显示末段后缀（如 `bak/2025`、`bak/master-2025-07` → 📁`bak` → `2025` / `master-2025-07`；远程整体收拢为 `origin` 文件夹并内嵌 `feature`）。新增纯逻辑引擎 [`buildRefTree`](./src/engine/ref/ref-tree.ts)（复用「变更文件目录树」`buildFileTree` 的 trie 构建 + compact 折叠范式；叶子携完整 `RawRef`、命令定位不受影响；分支感知排序：当前 HEAD → 收藏 → 同档文件夹优先、名称数字感知升序），并**隐藏 `origin/HEAD` 符号引用**（对齐主流 Git UI，消除 `origin` 叶子与 `origin` 文件夹同名冲突）。工具栏提供「平铺 ⇄ 树」切换（`hyperGit.branchesGroupByPrefix` / `hyperGit.branchesFlatten`，context key 驱动按钮互斥），偏好按仓库持久化于 `workspaceState`（默认树形），文件夹默认展开、展开态跨刷新稳定。文件夹节点用独立 `contextValue` 且不登记任何右键命令，checkout / delete / rename / merge / rebase / compare / favorite 与多选批量均零改动、零破坏。完整叙述见 [分支前缀分组树](./docs/features/branch-tree-group-by-prefix.md)。
 
 ## [0.0.14] - 2026-07-06 — 修复 GRAPH 视图提交记录时间倒序

diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@
   <b>English</b> · <a href="./docs/i18n/zh-CN/README.md">简体中文</a>
 </p>
 
-<p align="center"><sub>6 views · 97 commands · 6 settings · 324 unit tests</sub></p>
+<p align="center"><sub>6 views · 101 commands · 7 settings · 372 unit tests</sub></p>
 
 ## Features
 
@@ -40,7 +40,7 @@
 - **Consumes** the stable `Repository` API exported by the built-in `vscode.git` extension as its Git foundation, rather than rebuilding a Git state machine.
 - **Controlled CLI channel**: capabilities the stable API does not cover (cherry-pick / revert / reset / branch rename / hunk staging / stash listing / graph topology / shelf, etc.) run through `GitRepositoryService.execGit`, reusing the same Git binary (`api.git.path`).
 - **Hand-rendered views** carry the full change-management UI (webviews live under `adapter/webview/`); pure logic is distilled into `engine/` (zero `vscode` dependency, unit-testable).
-- **AI seams**: 5 interfaces (`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`) are reserved (design inspired by JetBrains' `CheckinHandler` commit lifecycle), currently shipped as Null implementations; the full implementation is deferred to M5.
+- **AI seams**: 5 interfaces (`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`) are reserved (design inspired by JetBrains' `CheckinHandler` commit lifecycle), currently shipped as Null implementations; the full implementation is deferred to M5. As pre-M5 groundwork, a **Claude Code executable path** setting (`hyperGit.claudeCode.executablePath`) and a **`~/.claude/settings.json` shortcut** are already configurable — see [Claude Code configuration](./docs/features/claude-code-config.md).
 
 <p align="center">
   <img src="media/framework.png" alt="Framework"/>

diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md
@@ -22,6 +22,7 @@
 - [变更文件目录树](../docs/features/file-list-group-by-directory.md) — Commit / Log 文件列表「平铺 ⇄ 按目录分组」切换：host 侧 `buildFileTree` 构树下发、compact 折叠、目录三态。
 - [分支前缀分组树](../docs/features/branch-tree-group-by-prefix.md) — Branches 视图 Local/Remote/Tags「平铺 ⇄ 按 `/` 前缀分组」切换：`buildRefTree` 构树、分支感知排序、compact 折叠、隐藏 `origin/HEAD`、按仓库持久化。
 - [Log 提交悬浮详情](../docs/features/log-commit-tooltip.md) — 悬停提交行浮层展示 分支/标签/HEAD/完整消息/作者·提交者/时间/SHA；复用 CI 浮层范式、与其互斥。
+- [Claude Code 配置](../docs/features/claude-code-config.md) — Agentic Git 预置：`hyperGit.claudeCode.executablePath` 设置 + `~/.claude/settings.json` 快捷入口（原生设置 + 命令；纯路径逻辑沉淀 `engine/agent/`）。
 - [实施状态总览](../docs/milestones/implementation-status.md) — M0-M5 交付记录 + API 限制 + M5 AI 设计 + 验证/发布（**实施看板**）。
 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。
 - [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。

diff --git a/docs/README.md b/docs/README.md
@@ -9,6 +9,7 @@
 
 ## 功能文档
 - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。
+- [Claude Code 配置](./features/claude-code-config.md) — Agentic Git 预置：Claude Code 可执行路径设置 + `~/.claude/settings.json` 快捷入口（原生设置 + 命令；M5 前置铺垫）。
 
 ## 发布说明
 - [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.14 修复 GRAPH 视图提交记录时间倒序](./releases/v0.0.14.md)。

diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md
@@ -226,6 +226,8 @@ hyper-git/
 **Commit 流水线 hook 注入点**（M2 即建责任链，默认 Null hooks）：
 `staged diff → [Hook A: 提交信息生成] → message 定稿 → [Hook B: 提交前检查链=beforeCheckin] → [Hook C: 分组校验] → commit → [Hook D: checkinSuccessful] → push → [Hook E: checkinFailed→Hook F: 冲突解决]`
 
+**pre-M5 已落地（配置铺垫）**：新增 `hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）与 `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置——仅承载「配置 + 快捷入口」，接缝仍 Null、`hyperGit.ai.enabled` 行为不变；M5 时 `ILlmProvider` 等将读取该路径定位 CLI。详见 [Claude Code 配置](../features/claude-code-config.md)。
+
 ---
 
 ## 7. CI/CD 与发布策略

diff --git a/docs/features/claude-code-config.md b/docs/features/claude-code-config.md
@@ -0,0 +1,76 @@
+# Claude Code 配置（可执行路径 · Claude 设置快捷入口）
+
+> 为 **Agentic Git**（M5 AI Agent 能力）预置的两项 Claude Code 相关配置：
+> **可执行路径**——指定自定义的 Claude Code CLI 二进制（留空则从 `PATH` 自动探测 `claude`）；
+> **Claude 设置**——一键打开用户级配置文件 `~/.claude/settings.json`。
+> 本次仅落地「配置项 + 快捷入口」；真正的 Claude Code 调用留待 M5 [AI 接缝](../research/05-ai-agent-seams.md) 实装，当前 `agent/` 五接缝仍为 Null 实现、`hyperGit.ai.enabled` 行为不变。
+
+## 效果
+
+- **设置界面**：`设置 → 搜索 hyperGit.claudeCode` 可见「Claude Code executable path」文本框，占位示例 `/opt/homebrew/bin/claude`；描述内嵌两条可点击命令链接（`Browse for executable…` / `Open Claude settings`），在设置页内就地复现「浏览文件夹」与「打开 Claude 设置」两个动作。
+- **命令面板**：`Hyper Git: Set Claude Code Executable Path…` 与 `Hyper Git: Open Claude Settings` 亦可直接调用。
+
+## 设计
+
+采用**原生 VS Code 设置 + 命令**承载（与仓库既有 7 项配置一致，零新增 Webview 面板；符合最小干预 / 复用驱动）。路径解析下沉为纯函数（engine 层，可单测），adapter 层仅注入 `os.homedir()` 并触碰 vscode API。
+
+```mermaid
+flowchart LR
+  subgraph UI["设置界面 / 命令面板"]
+    S["hyperGit.claudeCode.executablePath\n(string, 默认空 = PATH 自动探测)"]
+    C1["cmd: setClaudeCodePath"]
+    C2["cmd: openClaudeSettings"]
+  end
+  subgraph Adapter["adapter/claude-commands.ts（唯一触 vscode）"]
+    Q["QuickPick\nBrowse… / Use system"]
+    O["existsSync?\n缺失→确认→mkdir+写{}"]
+  end
+  subgraph Engine["engine/agent/claude-path.ts（纯函数,可单测）"]
+    P["defaultClaudeSettingsPath(home)\n→ &lt;home&gt;/.claude/settings.json"]
+  end
+  S -. "markdownDescription 命令链接" .-> C1
+  S -. "markdownDescription 命令链接" .-> C2
+  C1 --> Q
+  Q -->|Browse| S
+  Q -->|Use system| S
+  C2 --> O
+  O --> P
+  O --> D["openTextDocument + showTextDocument"]
+  style S fill:#1f6feb,color:#fff
+  style P fill:#238636,color:#fff
+  style O fill:#8957e5,color:#fff
+  style Q fill:#d29922,color:#000
+```
+
+## 配置
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `hyperGit.claudeCode.executablePath` | `string` | `""` | Agentic Git 使用的 Claude Code CLI 可执行路径；**留空 = 从 `PATH` 自动探测 `claude`（推荐）**。可经 `Set Claude Code Executable Path…` 命令浏览设置或清空。 |
+
+## 命令
+
+| 命令 | 标题 | 行为 |
+|---|---|---|
+| `hyperGit.setClaudeCodePath` | Set Claude Code Executable Path… | QuickPick：**Browse for executable…**(文件选择器写回设置) / **Use system Claude Code**(清空覆盖，回退 `PATH` 自动探测)。 |
+| `hyperGit.openClaudeSettings` | Open Claude Settings | 打开 `~/.claude/settings.json`；**文件不存在时经用户确认后创建**（`mkdir -p` + 写入 `{}`），随后在编辑器打开。 |
+
+## 实现
+
+- 纯逻辑（Vitest 可测）：[`engine/agent/claude-path.ts`](../../src/engine/agent/claude-path.ts) — `defaultClaudeSettingsPath(home)` 跨平台拼接路径（`home` 由调用方注入，函数确定性）。
+- 适配层（唯一触 vscode）：[`adapter/claude-commands.ts`](../../src/adapter/claude-commands.ts) — `registerClaudeCommands()`，复用 `misc-commands.ts` 的 `showOpenDialog` / `openTextDocument` / 错误处理范式。
+- 装配：[`extension.ts`](../../src/extension.ts) — 命令注册块追加 `...registerClaudeCommands()`。
+- 契约：[`package.json`](../../package.json) — `contributes.configuration`（新增设置项）+ `contributes.commands`（两条命令）。
+- 测试：[`tests/unit/claude-path.test.ts`](../../tests/unit/claude-path.test.ts)。
+
+## 与 Agentic Git 的关系
+
+本特性是 M5 的**预置铺垫（pre-M5 groundwork）**：仅提供配置与快捷入口，不改变现有行为——`agent/` 五接缝（`ILlmProvider` 等）仍 Null 实现、`hyperGit.ai.enabled` 仍仅占位。待 M5 启动，`ILlmProvider` / 提交信息生成等接缝将读取 `hyperGit.claudeCode.executablePath` 定位 CLI 并实装真实能力。相关设计见 [AI Agent 架构预留](../research/05-ai-agent-seams.md) 与 [实施状态总览](../milestones/implementation-status.md)。
+
+## 验证
+
+1. `pnpm run check-types` + `pnpm run lint` + `pnpm run test:unit`（含 `tests/unit/claude-path.test.ts`）全绿。
+2. Extension Development Host（F5）：
+   - `设置` 搜索 `hyperGit.claudeCode` → 见新设置及两条内嵌命令链接；点击 `Browse…` 弹文件选择、点击 `Open Claude settings` 可跳转。
+   - 命令面板 `Set Claude Code Executable Path…` → Browse 写入路径 / Use system 清空，设置值随之变化。
+   - 命令面板 `Open Claude Settings`：文件已存在→直接打开；不存在→确认后创建 `{}` 并打开；取消则不创建。
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
@@ -16,7 +16,7 @@
   <a href="../../../README.md">English</a> · <b>简体中文</b>
 </p>
 
-<p align="center"><sub>6 视图 · 97 命令 · 6 配置项 · 324 单元测试</sub></p>
+<p align="center"><sub>6 视图 · 101 命令 · 7 配置项 · 372 单元测试</sub></p>
 
 ## 核心能力
 
@@ -40,7 +40,7 @@
 - **消费** 内置 `vscode.git` 导出的稳定 `Repository` API 作为 git 底座，不重造 git 状态机。
 - **受控 CLI 通道**：稳定 API 未覆盖的能力（cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash 列表 / graph 拓扑 / shelf 等）经 `GitRepositoryService.execGit` 复用同一 git 二进制（`api.git.path`）实现。
 - **自绘视图** 承载完整的变更管理 UI（Webview 位于 `adapter/webview/`）；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。
-- **AI 接缝**：预留 `ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver` 共 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），当前以 Null 实现交付，完整实现延后至 M5。
+- **AI 接缝**：预留 `ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver` 共 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），当前以 Null 实现交付，完整实现延后至 M5。作为 M5 前置铺垫，已可配置 **Claude Code 可执行路径**（`hyperGit.claudeCode.executablePath`）与 **`~/.claude/settings.json` 快捷入口**——详见 [Claude Code 配置](../../features/claude-code-config.md)。
 
 <p align="center">
   <img src="../../../media/framework.png" alt="Framework"/>

diff --git a/docs/milestones/implementation-status.md b/docs/milestones/implementation-status.md
@@ -96,6 +96,8 @@
 
 **M5 启动前置**：`engines.vscode` 上调以支持 LM/Chat API；opt-in 配置开关；模型来源可切换。
 
+**pre-M5 已落地（配置铺垫）**：`hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）+ `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置已交付——仅承载配置与快捷入口，接缝仍 Null、`hyperGit.ai.enabled` 行为不变。详见 [Claude Code 配置](../features/claude-code-config.md)。
+
 ## 6. 验证体系
 
 - **单元测试（Vitest，< 1s）**：engine/ 纯逻辑（scm-mapping、changelist-grouper、commit-pipeline、conventional-linter、git-status-map、conventional-check）+ CommitService.executeCommit（mock Repository，7 分支）。共 45 项。

diff --git a/docs/research/05-ai-agent-seams.md b/docs/research/05-ai-agent-seams.md
@@ -203,6 +203,7 @@ flowchart TD
 
 ### 阶段 1:可选 AI 期——**配置开关 + 模型来源可切换**
 - 新增配置:`sofia.ai.enabled`(总开关)、`sofia.ai.modelSource`(`vscodeLM` | `byok` | `openaiCompatible`)、`sofia.ai.commitMessage.enabled` 等细粒度开关。
+  > 事实校准:实际产品命名空间为 `hyperGit.*`(本文 `sofia.*` 为改名前的历史草案,全量收敛另议)。**首个落地的 pre-M5 配置**为 `hyperGit.claudeCode.executablePath`(Claude Code CLI 路径)——属「CLI 后端定位」,与此处的「模型来源(`modelSource`)」接缝正交;详见 [Claude Code 配置](../features/claude-code-config.md)。
 - `ILlmProvider` 按 `modelSource` 路由:
   - `vscodeLM`:走 `vscode.lm.selectChatModels`([LM API](https://code.visualstudio.com/api/extension-guides/ai/language-model))——需 Copilot 订阅 + 用户 consent。
   - `byok`:走 BYOK/Ollama([Provider API](https://code.visualstudio.com/api/extension-guides/ai/language-model-chat-provider))——**本地化、不强依赖云端、企业友好**。

diff --git a/package.json b/package.json
@@ -467,6 +467,18 @@
 				"category": "Hyper Git",
 				"icon": "$(output)"
 			},
+			{
+				"command": "hyperGit.setClaudeCodePath",
+				"title": "Set Claude Code Executable Path…",
+				"category": "Hyper Git",
+				"icon": "$(folder-opened)"
+			},
+			{
+				"command": "hyperGit.openClaudeSettings",
+				"title": "Open Claude Settings",
+				"category": "Hyper Git",
+				"icon": "$(gear)"
+			},
 			{
 				"command": "hyperGit.partialStage",
 				"title": "Stage Hunk…",
@@ -1215,6 +1227,11 @@
 					"default": false,
 					"markdownDescription": "Enable AI agent capabilities (currently reserved as an architectural seam; not yet active)."
 				},
+				"hyperGit.claudeCode.executablePath": {
+					"type": "string",
+					"default": "",
+					"markdownDescription": "Path to the Claude Code CLI executable used by Hyper Git's Agentic Git features. Leave empty to auto-detect the `claude` binary from your `PATH` (recommended).\n\n[Browse for executable…](command:hyperGit.setClaudeCodePath) · [Open Claude settings (`~/.claude/settings.json`)](command:hyperGit.openClaudeSettings)"
+				},
 				"hyperGit.log.ci.enabled": {
 					"type": "boolean",
 					"default": true,