ThreeFish-AI · ThreeFish-AI · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,4 @@ out/
 # 系统/编辑器
 .DS_Store
 Thumbs.db
+*visual-check*
diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md
@@ -30,11 +30,15 @@
 - [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。
 - [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.18](../releases/v0.0.18.md)）。
 
+## 图资产（docs/assets/）
+- [Mermaid 源图索引](../assets/mermaid/README.md) — 全项目 Mermaid 源图统一管理 + **溯源矩阵**（mermaid ↔ archify ↔ 嵌入文档的唯一权威映射）。
+- [archify 架构图索引](../assets/architecture/README.md) — 交互式架构图成品（HTML + 深浅色双 SVG）分类索引与绘制规范；文档嵌入图的唯一来源。
+
 ## 架构分层（src/）
 > 依赖方向单向：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI。
 
-- `engine/` — 纯领域逻辑（零 vscode 依赖，Vitest 可测）：`model/`、`scm-mapping/`、`commit/pipeline.ts`、`diff/`(M4)。
-- `adapter/` — 唯一接触 vscode API：`GitRepositoryAdapter`、`ChangelistRegistry`、`tree/`、`webview/`、`diff/`、`storage/`（M1+）。
+- `engine/` — 纯领域逻辑（零 vscode 依赖，Vitest 可测，15 模块）：`model/`、`diff/`、`commit/`、`changelist/`、`log/`、`ref/`、`tree/`、`git-state/`、`scm-mapping/`、`ci/`、`merge/`、`rebase/`、`blame/`、`worktree/`、`agent/`。
+- `adapter/` — 唯一接触 vscode API：`git-api.ts`（getAPI(1)）、`GitRepositoryService`（活跃仓库唯一持有者，vscode.git API + execGit 双通道）、`ChangelistRegistry`、`BranchFavorites`、`ShelfService`、`CommitService`、命令注册组、`tree/`、`webview/`、`ci/`、`editor/`。
 - `agent/` — AI 接缝（当前 5 接口，均 Null 实现，完整逻辑延后至 M5）：`ILlmProvider`、`ICommitMessageProvider`、`IPreCommitInspector`、`IChangelistGrouper`、`IConflictResolver`（另有规划中的第 6 接缝 `IChatToolRegistrar`，详见[调研报告](../research/05-ai-agent-seams.md)）。
 - `shared/protocol.ts` — Webview ↔ Host 消息契约【单一事实源】。
 - `infra/` — 日志（OutputChannel）/ 错误处理 / 事件总线 / 配置。

diff --git a/docs/README.md b/docs/README.md
@@ -6,6 +6,7 @@
 - [实施状态总览（M0-M5）](./milestones/implementation-status.md) — 里程碑交付记录、P0/P1 达成矩阵、API 限制、M5 AI 设计、验证与发布状态（**实施看板**）。
 - [工程实施方案](./architecture/engineering-plan.md) — 全链路调研结论 + 路径 B 架构 + M0-M5 里程碑路线图 + 风险与验证（**开发蓝图**）。
 - [Git 功能完备性矩阵](./requirements/idea-feature-matrix.md) — 56 个原子功能点 / 8 组 + CheckinHandler 生命周期（**验收基线**）。
+- [图资产索引](./assets/mermaid/README.md) — Mermaid 源图统一管理 + 溯源矩阵；[archify 架构图成品](./assets/architecture/README.md)（交互 HTML + 深浅色 SVG）为文档嵌入图的唯一来源。
 
 ## 功能文档
 - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。

diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md
@@ -31,57 +31,16 @@
 | **发布** | VS Code Marketplace 单市场 | 官方市场为唯一渠道；每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装 |
 | **AI** | 现仅定义接缝 + Null 实现，实现延后 M5 | YAGNI + 借鉴 JetBrains `CheckinHandler` 责任链语义 |
 
-**架构总览（Mermaid，深色模式高对比）**：
-
-```mermaid
-flowchart TB
-    subgraph UI["UI 层 (自绘, adapter/ui)"]
-        direction LR
-        V1["Changes<br/>TreeView"]
-        V2["Commit<br/>WebviewView"]
-        V3["Log<br/>Webview graph"]
-        V4["Branches/Shelf/Stash<br/>TreeView"]
-    end
-    subgraph Adapter["Adapter 层 (唯一接触 vscode API)"]
-        GA["GitRepositoryAdapter<br/>封装 vscode.git Repository"]
-        CR["ChangelistRegistry<br/>(active/分组/持久化)"]
-        WV["WebviewHost<br/>postMessage 协议"]
-        DI["DiffContentProvider<br/>自定义 scheme"]
-    end
-    subgraph Engine["Engine 层 (纯逻辑, 零 vscode 依赖, 可单测)"]
-        M["领域模型<br/>FileChange/Changelist/Commit/Branch/Stash"]
-        DF["Diff/行级 patch<br/>(partial commit 基础)"]
-        CK["CommitPipeline<br/>(Checkin hook 责任链)"]
-        SM["Status 色映射<br/>M/A/D/U/R/C"]
-    end
-    subgraph Agent["Agent 层 (AI 接缝, 预留)"]
-        LLM["ILlmProvider"]
-        AI1["ICommitMessageProvider"]
-        AI2["IPreCommitInspector"]
-        AI3["IChangelistGrouper"]
-        AI4["IConflictResolver"]
-    end
-    VSCodeGIT[("vscode.git<br/>内置 Repository API")]
-    NATIVE[("原生 Source Control 视图<br/>不动, 共存")]
-
-    UI --> Adapter
-    Adapter --> Engine
-    Agent -. 读领域模型 / 注入 hook .-> Engine
-    Agent -. 读 .-> Adapter
-    Adapter --> VSCodeGIT
-    NATIVE -. 平行存在 .-> VSCodeGIT
-
-    classDef ui fill:#1f6feb,stroke:#4dabf7,stroke-width:2px,color:#fff
-    classDef ad fill:#7c3aed,stroke:#c4b5fd,stroke-width:2px,color:#fff
-    classDef eg fill:#0f766e,stroke:#5eead4,stroke-width:2px,color:#fff
-    classDef ag fill:#b45309,stroke:#fcd34d,stroke-width:2px,color:#fff
-    classDef ext fill:#444654,stroke:#8b8fa3,stroke-width:2px,color:#fff
-    class V1,V2,V3,V4 ui
-    class GA,CR,WV,DI ad
-    class M,DF,CK,SM eg
-    class LLM,AI1,AI2,AI3,AI4 ag
-    class VSCodeGIT,NATIVE ext
-```
+**架构总览（已对照 v0.0.18 现状校准，深浅色自适应）**：
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../assets/architecture/architecture/engineering-plan-layers.dark.svg">
+  <img src="../assets/architecture/architecture/engineering-plan-layers.light.svg" alt="Hyper Git 核心架构分层总览：视图层（Commit/Graph webview 与四棵 TreeView）、Adapter 层（GitRepositoryService 双通道、webview 宿主、命令注册组、领域状态服务）、Engine 层（15 纯逻辑模块）、Agent 层（AI 接缝），底座为 vscode.git API 与 git CLI 双通道">
+</picture>
+
+> [交互版架构图（聚焦/搜索/导出）](../assets/architecture/architecture/engineering-plan-layers.html) · [Mermaid 源图](../assets/mermaid/architecture/engineering-plan-layers.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)）
+>
+> **现状校准（2026-09-11）**：本图原为早期规划态，现已对齐 v0.0.18 实现——「Changes TreeView」随 v0.0.13 视图迁移移除（changelist 由 Commit WebviewView 承载）；视图容器落位**底部 Panel**；adapter 组件为现名（`GitRepositoryService` / `git-api.ts` / `webview/` 宿主 ×4 等）；Engine 层实际为 **15 个模块**；AI 接缝经 `CommitService` 注入（`extension.ts`）。正文中早期规划表述（如「以 TreeView 渲染 changelist」「活动栏视图容器」）保留为历史决策记录，以本图与源码为准。
 
 **依赖方向（单向，正交）**：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI；`Engine` 零依赖 `vscode`（可被 Vitest 与未来 CLI 双复用，是项目核心 IP）。
 

diff --git a/docs/assets/architecture/README.md b/docs/assets/architecture/README.md
@@ -0,0 +1,54 @@
+# archify 架构图资产索引
+
+本目录管理由 [archify](https://github.com/tt-a1i/archify) 绘制的交互式架构图成品。**源头是 [Mermaid 源图](../mermaid/README.md)**（唯一事实源，溯源矩阵见彼处）；文档一律嵌入本目录成品，禁止内联 mermaid 围栏。
+
+## 产物形态（每图四件套，同基名）
+
+| 文件 | 用途 |
+|---|---|
+| `<基名>.html` | 交互版：聚焦/搜索/关系追踪/演示，深浅主题切换（浏览器直接打开） |
+| `<基名>.light.svg` | 浅色静态版，`<picture>` 默认嵌入 |
+| `<基名>.dark.svg` | 深色静态版（根节点 `data-theme="dark"`），`<picture>` 深色偏好嵌入 |
+| `docs/assets/mermaid/<分类>/<基名>.mmd` | Mermaid 源图（指回本目录的路径登记在溯源矩阵） |
+
+## 分类索引
+
+### architecture/（工程蓝图）
+| 基名 | archify 类型 | 源 Mermaid | 嵌入文档 |
+|---|---|---|---|
+| [engineering-plan-layers](architecture/engineering-plan-layers.html) | architecture | [engineering-plan-layers.mmd](../mermaid/architecture/engineering-plan-layers.mmd) | [engineering-plan.md](../../architecture/engineering-plan.md) |
+
+### features/（功能特性）
+| 基名 | archify 类型 | 源 Mermaid | 嵌入文档 |
+|---|---|---|---|
+| [log-commit-detail-panel-layout](features/log-commit-detail-panel-layout.html) | architecture | [.mmd](../mermaid/features/log-commit-detail-panel-layout.mmd) | [log-commit-detail-panel.md](../../features/log-commit-detail-panel.md) |
+| [log-commit-detail-panel-dataflow](features/log-commit-detail-panel-dataflow.html) | dataflow | [.mmd](../mermaid/features/log-commit-detail-panel-dataflow.mmd) | 同上 |
+| [multi-root-repo-selection-toolbar](features/multi-root-repo-selection-toolbar.html) | workflow | [.mmd](../mermaid/features/multi-root-repo-selection-toolbar.mmd) | [multi-root-repo-selection.md](../../features/multi-root-repo-selection.md) |
+| [multi-root-repo-selection-sequence](features/multi-root-repo-selection-sequence.html) | sequence | [.mmd](../mermaid/features/multi-root-repo-selection-sequence.mmd) | 同上 |
+| [branch-tree-group-by-prefix-effect](features/branch-tree-group-by-prefix-effect.html) | workflow | [.mmd](../mermaid/features/branch-tree-group-by-prefix-effect.mmd) | [branch-tree-group-by-prefix.md](../../features/branch-tree-group-by-prefix.md) |
+| [branch-tree-group-by-prefix-dataflow](features/branch-tree-group-by-prefix-dataflow.html) | dataflow | [.mmd](../mermaid/features/branch-tree-group-by-prefix-dataflow.mmd) | 同上 |
+| [file-list-group-by-directory-dataflow](features/file-list-group-by-directory-dataflow.html) | dataflow | [.mmd](../mermaid/features/file-list-group-by-directory-dataflow.mmd) | [file-list-group-by-directory.md](../../features/file-list-group-by-directory.md) |
+| [agentic-git-preferences-flow](features/agentic-git-preferences-flow.html) | workflow | [.mmd](../mermaid/features/agentic-git-preferences-flow.mmd) | [agentic-git-preferences.md](../../features/agentic-git-preferences.md) |
+| [claude-code-config-flow](features/claude-code-config-flow.html) | workflow | [.mmd](../mermaid/features/claude-code-config-flow.mmd) | [claude-code-config.md](../../features/claude-code-config.md) |
+| [log-ci-status-dataflow](features/log-ci-status-dataflow.html) | dataflow | [.mmd](../mermaid/features/log-ci-status-dataflow.mmd) | [log-ci-status.md](../../features/log-ci-status.md) |
+
+### research/（调研设计）
+| 基名 | archify 类型 | 源 Mermaid | 嵌入文档 |
+|---|---|---|---|
+| [ai-agent-seams-pipeline](research/ai-agent-seams-pipeline.html) | workflow | [.mmd](../mermaid/research/ai-agent-seams-pipeline.mmd) | [05-ai-agent-seams.md](../../research/05-ai-agent-seams.md) |
+
+## 绘制规范
+
+1. **语义色彩**：组件类型语义化（前端/后端/外部系统各有专属色相），预留接缝用虚线关系表达；经典预设（classic）保证深浅主题下均高对比。
+2. **双主题**：HTML 内置主题切换；SVG 导出为主题自包含文件，dark 版在根节点追加 `data-theme="dark"`。
+3. **文档嵌入模板**：
+   ```markdown
+   <picture>
+     <source media="(prefers-color-scheme: dark)" srcset="../assets/architecture/<分类>/<基名>.dark.svg">
+     <img src="../assets/architecture/<分类>/<基名>.light.svg" alt="<中文图题>">
+   </picture>
+
+   > [交互版](../assets/architecture/<分类>/<基名>.html) · [Mermaid 源图](../assets/mermaid/<分类>/<基名>.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)）
+   ```
+4. **质量门槛**：候选须通过 archify showcase 全检（9 项 artifact 检查零错误零警告）+ `visual-check` 浏览器证据（1440×900 等桌面首屏无溢出）。
+5. **变更顺序**：改 Mermaid 源 → 重绘本目录成品 → 更新 [溯源矩阵](../mermaid/README.md)。