diff --git a/.gitignore b/.gitignore index 053535e..af7995c 100644 --- 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 index 5f46f6b..93e0425 100644 --- 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 index e311948..93da6a6 100644 --- 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 index e183b71..9309f5b 100644 --- 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
TreeView"] - V2["Commit
WebviewView"] - V3["Log
Webview graph"] - V4["Branches/Shelf/Stash
TreeView"] - end - subgraph Adapter["Adapter 层 (唯一接触 vscode API)"] - GA["GitRepositoryAdapter
封装 vscode.git Repository"] - CR["ChangelistRegistry
(active/分组/持久化)"] - WV["WebviewHost
postMessage 协议"] - DI["DiffContentProvider
自定义 scheme"] - end - subgraph Engine["Engine 层 (纯逻辑, 零 vscode 依赖, 可单测)"] - M["领域模型
FileChange/Changelist/Commit/Branch/Stash"] - DF["Diff/行级 patch
(partial commit 基础)"] - CK["CommitPipeline
(Checkin hook 责任链)"] - SM["Status 色映射
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
内置 Repository API")] - NATIVE[("原生 Source Control 视图
不动, 共存")] - - 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 现状校准，深浅色自适应）**： + + + + Hyper Git 核心架构分层总览：视图层（Commit/Graph webview 与四棵 TreeView）、Adapter 层（GitRepositoryService 双通道、webview 宿主、命令注册组、领域状态服务）、Engine 层（15 纯逻辑模块）、Agent 层（AI 接缝），底座为 vscode.git API 与 git CLI 双通道 + + +> [交互版架构图（聚焦/搜索/导出）](../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 new file mode 100644 index 0000000..b84abf9 --- /dev/null +++ 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` | 浅色静态版，`` 默认嵌入 | +| `<基名>.dark.svg` | 深色静态版（根节点 `data-theme="dark"`），`` 深色偏好嵌入 | +| `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 + + + <中文图题> + + + > [交互版](../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)。 diff --git a/docs/assets/architecture/architecture/engineering-plan-layers.dark.svg b/docs/assets/architecture/architecture/engineering-plan-layers.dark.svg new file mode 100644 index 0000000..7188ef3 --- /dev/null +++ b/docs/assets/architecture/architecture/engineering-plan-layers.dark.svg @@ -0,0 +1,698 @@ + + Hyper Git 核心架构 · 路径 B（Consume + Hand-render） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Graph (Log) WebviewView · SVG 提交图 · 详情面板 · CI · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Graph (Log) WebviewView + SVG 提交图 · 详情面板 · CI + + + + Commit WebviewView · changelist · 提交编辑器 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Commit WebviewView + changelist · 提交编辑器 + + + + Rebase · MergeEditor · Webview 面板 · serializer 恢复 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Rebase · MergeEditor + Webview 面板 · serializer 恢复 + + + + Branches/Stash/Shelf/Worktrees · TreeView · 多选批量 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Branches/Stash/Shelf/Worktrees + TreeView · 多选批量 + + + + Registry · Favorites · Shelf · CommitService · 仓库作用域持久化 · Adapter 层 · 唯一接触 vscode API + + + + Registry · Favorites · Shelf + CommitService · 仓库作用域持久化 + + + + webview/ 宿主 ×4 · shared/protocol.ts 消息契约 · Adapter 层 · 唯一接触 vscode API + + + + webview/ 宿主 ×4 + shared/protocol.ts 消息契约 + + + + GitRepositoryService · 活跃仓库唯一持有者 · Adapter 层 · 唯一接触 vscode API · API + CLI 双通道 + + + + GitRepositoryService + 活跃仓库唯一持有者 + API + CLI 双通道 + + + + 命令注册组 ×12 · tree/ · editor/（blame · CodeLens） · Adapter 层 · 唯一接触 vscode API + + + + 命令注册组 ×12 + tree/ · editor/（blame · CodeLens） + + + + AI 接缝 ×5 · ILlmProvider 等 5 接口 · Null · Agent 层 · AI 接缝 · Null 实现（M5 实装） · M5 实装 + + + + AI 接缝 ×5 + ILlmProvider 等 5 接口 · Null + M5 实装 + + + + Engine 层（15 纯逻辑模块） · model · diff · commit · changelist · log 等 · Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + Engine 层（15 纯逻辑模块） + model · diff · commit · changelist · log 等 + + + + git CLI · child_process · 同一二进制 · 架构组件 + + + + git CLI + child_process · 同一二进制 + + + + vscode.git 内置扩展 · getAPI(1) → Repository · 架构组件 + + + + vscode.git 内置扩展 + getAPI(1) → Repository + + + + + + postMessage + + + + + TreeDataProvider · 命令 + + + + 取数 · 状态 + + + + git 操作 + + + + 命令分发 + + + + 纯函数 + + + + 接口注入 + + + + hook 责任链 + + + + 领域逻辑 + + + + execFile + + + + getAPI(1) + + + + + + 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + + Adapter 层 · 唯一接触 vscode API + + + + + Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + + Agent 层 · AI 接缝 · Null 实现（M5 实装） + + + + + 图例 + + + 前端 + + + + 后端 + + + + 外部系统 + + + \ No newline at end of file diff --git a/docs/assets/architecture/architecture/engineering-plan-layers.html b/docs/assets/architecture/architecture/engineering-plan-layers.html new file mode 100644 index 0000000..da1f11f --- /dev/null +++ b/docs/assets/architecture/architecture/engineering-plan-layers.html @@ -0,0 +1,15048 @@ + + + + + + + Hyper Git 核心架构 · 路径 B（Consume + Hand-render） + + + + + + + + +
+ +
+
+
+

Hyper Git 核心架构 · 路径 B（Consume + Hand-render）

+
+
+ + + + + + + +
+ + Hyper Git 核心架构 · 路径 B（Consume + Hand-render） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Graph (Log) WebviewView · SVG 提交图 · 详情面板 · CI · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Graph (Log) WebviewView + SVG 提交图 · 详情面板 · CI + + + + Commit WebviewView · changelist · 提交编辑器 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Commit WebviewView + changelist · 提交编辑器 + + + + Rebase · MergeEditor · Webview 面板 · serializer 恢复 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Rebase · MergeEditor + Webview 面板 · serializer 恢复 + + + + Branches/Stash/Shelf/Worktrees · TreeView · 多选批量 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Branches/Stash/Shelf/Worktrees + TreeView · 多选批量 + + + + Registry · Favorites · Shelf · CommitService · 仓库作用域持久化 · Adapter 层 · 唯一接触 vscode API + + + + Registry · Favorites · Shelf + CommitService · 仓库作用域持久化 + + + + webview/ 宿主 ×4 · shared/protocol.ts 消息契约 · Adapter 层 · 唯一接触 vscode API + + + + webview/ 宿主 ×4 + shared/protocol.ts 消息契约 + + + + GitRepositoryService · 活跃仓库唯一持有者 · Adapter 层 · 唯一接触 vscode API · API + CLI 双通道 + + + + GitRepositoryService + 活跃仓库唯一持有者 + API + CLI 双通道 + + + + 命令注册组 ×12 · tree/ · editor/（blame · CodeLens） · Adapter 层 · 唯一接触 vscode API + + + + 命令注册组 ×12 + tree/ · editor/（blame · CodeLens） + + + + AI 接缝 ×5 · ILlmProvider 等 5 接口 · Null · Agent 层 · AI 接缝 · Null 实现（M5 实装） · M5 实装 + + + + AI 接缝 ×5 + ILlmProvider 等 5 接口 · Null + M5 实装 + + + + Engine 层（15 纯逻辑模块） · model · diff · commit · changelist · log 等 · Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + Engine 层（15 纯逻辑模块） + model · diff · commit · changelist · log 等 + + + + git CLI · child_process · 同一二进制 · 架构组件 + + + + git CLI + child_process · 同一二进制 + + + + vscode.git 内置扩展 · getAPI(1) → Repository · 架构组件 + + + + vscode.git 内置扩展 + getAPI(1) → Repository + + + + + + postMessage + + + + + TreeDataProvider · 命令 + + + + 取数 · 状态 + + + + git 操作 + + + + 命令分发 + + + + 纯函数 + + + + 接口注入 + + + + hook 责任链 + + + + 领域逻辑 + + + + execFile + + + + getAPI(1) + + + + + + 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + + Adapter 层 · 唯一接触 vscode API + + + + + Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + + Agent 层 · AI 接缝 · Null 实现（M5 实装） + + + + + 图例 + + + 前端 + + + + 后端 + + + + 外部系统 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

分层契约

+
+
    +
  • • 视图层经 shared/protocol.ts 单一事实源与 Adapter 通信
    • +
  • • Adapter 唯一接触 vscode API；Engine 零 vscode 依赖、Vitest 可单测
    • +
+
+ +
+
+
+

Engine 15 模块全景

+
+
    +
  • • 核心：model · diff · commit · changelist · log · ref · tree · git-state · scm-mapping
    • +
  • • 扩展：ci · merge · rebase · blame · worktree · agent
    • +
+
+ +
+
+
+

Git 双通道底座

+
+
    +
  • • vscode.git getAPI(1) + execFile（同一二进制）双通道取数
    • +
  • • 原生 Source Control 平行共存，不注册竞争 SCM Provider
    • +
+
+ +
+
+
+

AI 接缝（M5 预留）

+
+
    +
  • • 5 个接缝接口均为 Null 实现，经 CommitService 注入
    • +
  • • hyperGit.agent.* 与 claudeCode 配置已预置，行为零变化
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/architecture/engineering-plan-layers.light.svg b/docs/assets/architecture/architecture/engineering-plan-layers.light.svg new file mode 100644 index 0000000..52c997f --- /dev/null +++ b/docs/assets/architecture/architecture/engineering-plan-layers.light.svg @@ -0,0 +1,698 @@ + + Hyper Git 核心架构 · 路径 B（Consume + Hand-render） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Graph (Log) WebviewView · SVG 提交图 · 详情面板 · CI · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Graph (Log) WebviewView + SVG 提交图 · 详情面板 · CI + + + + Commit WebviewView · changelist · 提交编辑器 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Commit WebviewView + changelist · 提交编辑器 + + + + Rebase · MergeEditor · Webview 面板 · serializer 恢复 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Rebase · MergeEditor + Webview 面板 · serializer 恢复 + + + + Branches/Stash/Shelf/Worktrees · TreeView · 多选批量 · 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + Branches/Stash/Shelf/Worktrees + TreeView · 多选批量 + + + + Registry · Favorites · Shelf · CommitService · 仓库作用域持久化 · Adapter 层 · 唯一接触 vscode API + + + + Registry · Favorites · Shelf + CommitService · 仓库作用域持久化 + + + + webview/ 宿主 ×4 · shared/protocol.ts 消息契约 · Adapter 层 · 唯一接触 vscode API + + + + webview/ 宿主 ×4 + shared/protocol.ts 消息契约 + + + + GitRepositoryService · 活跃仓库唯一持有者 · Adapter 层 · 唯一接触 vscode API · API + CLI 双通道 + + + + GitRepositoryService + 活跃仓库唯一持有者 + API + CLI 双通道 + + + + 命令注册组 ×12 · tree/ · editor/（blame · CodeLens） · Adapter 层 · 唯一接触 vscode API + + + + 命令注册组 ×12 + tree/ · editor/（blame · CodeLens） + + + + AI 接缝 ×5 · ILlmProvider 等 5 接口 · Null · Agent 层 · AI 接缝 · Null 实现（M5 实装） · M5 实装 + + + + AI 接缝 ×5 + ILlmProvider 等 5 接口 · Null + M5 实装 + + + + Engine 层（15 纯逻辑模块） · model · diff · commit · changelist · log 等 · Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + Engine 层（15 纯逻辑模块） + model · diff · commit · changelist · log 等 + + + + git CLI · child_process · 同一二进制 · 架构组件 + + + + git CLI + child_process · 同一二进制 + + + + vscode.git 内置扩展 · getAPI(1) → Repository · 架构组件 + + + + vscode.git 内置扩展 + getAPI(1) → Repository + + + + + + postMessage + + + + + TreeDataProvider · 命令 + + + + 取数 · 状态 + + + + git 操作 + + + + 命令分发 + + + + 纯函数 + + + + 接口注入 + + + + hook 责任链 + + + + 领域逻辑 + + + + execFile + + + + getAPI(1) + + + + + + 视图层 · 底部 Panel 容器 hyper-git（v0.0.13 起自活动栏迁入） + + + + + Adapter 层 · 唯一接触 vscode API + + + + + Engine 层 · 零 vscode 依赖 · Vitest 可单测 + + + + + Agent 层 · AI 接缝 · Null 实现（M5 实装） + + + + + 图例 + + + 前端 + + + + 后端 + + + + 外部系统 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/agentic-git-preferences-flow.dark.svg b/docs/assets/architecture/features/agentic-git-preferences-flow.dark.svg new file mode 100644 index 0000000..68137c0 --- /dev/null +++ b/docs/assets/architecture/features/agentic-git-preferences-flow.dark.svg @@ -0,0 +1,579 @@ + + hyperGit.agent.* 设置 → Agentic Git 动作 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / hyperGit.agent.* 设置（package.json contributes.configuration） + + + 02 / Agentic Git 动作（M5 消费） + + + + + + + + + + + + + + + + commitPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + commitPreferences + multilineText + + + + baseBranch · 留空 = 仓库默认分支 · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + baseBranch + 留空 = 仓库默认分支 + + + + createPrPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + createPrPreferences + multilineText + + + + reviewPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + reviewPreferences + multilineText + + + + 点击 Commit · Agentic Git 动作（M5 消费） + + + + 点击 Commit + + + + 点击 Create PR · Agentic Git 动作（M5 消费） + + + + 点击 Create PR + + + + 点击 Review · Agentic Git 动作（M5 消费） + + + + 点击 Review + + + + + + PR 基线分支 + + + + 自定义指令 + + + + 自定义指令 + + + + 自定义指令 + + + + + 图例 + + + 用户界面 + + + + 上下文 / 追踪 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/agentic-git-preferences-flow.html b/docs/assets/architecture/features/agentic-git-preferences-flow.html new file mode 100644 index 0000000..618d340 --- /dev/null +++ b/docs/assets/architecture/features/agentic-git-preferences-flow.html @@ -0,0 +1,14918 @@ + + + + + + + hyperGit.agent.* 设置 → Agentic Git 动作 + + + + + + + + +
+ +
+
+
+

hyperGit.agent.* 设置 → Agentic Git 动作

+
+
+ + + + + + + +
+ + hyperGit.agent.* 设置 → Agentic Git 动作 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / hyperGit.agent.* 设置（package.json contributes.configuration） + + + 02 / Agentic Git 动作（M5 消费） + + + + + + + + + + + + + + + + commitPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + commitPreferences + multilineText + + + + baseBranch · 留空 = 仓库默认分支 · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + baseBranch + 留空 = 仓库默认分支 + + + + createPrPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + createPrPreferences + multilineText + + + + reviewPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + reviewPreferences + multilineText + + + + 点击 Commit · Agentic Git 动作（M5 消费） + + + + 点击 Commit + + + + 点击 Create PR · Agentic Git 动作（M5 消费） + + + + 点击 Create PR + + + + 点击 Review · Agentic Git 动作（M5 消费） + + + + 点击 Review + + + + + + PR 基线分支 + + + + 自定义指令 + + + + 自定义指令 + + + + 自定义指令 + + + + + 图例 + + + 用户界面 + + + + 上下文 / 追踪 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

落地现状

+
+
    +
  • • 四项均为 pre-M5 预置（Reserved），当前版本无效果
    • +
  • • 纯声明式配置：无新增命令 / Webview / TS
    • +
+
+ +
+
+
+

M5 消费方式

+
+
    +
  • • Commit / Create PR / Review 读取对应偏好作为 agent 自定义指令
    • +
  • • baseBranch 作为创建 PR 的基线，留空回退仓库默认分支
    • +
+
+ +
+
+
+

配置形态

+
+
    +
  • • 四项 scope 均为 window，类型 string
    • +
  • • baseBranch 文本输入；三项偏好 multilineText 多行文本域
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/agentic-git-preferences-flow.light.svg b/docs/assets/architecture/features/agentic-git-preferences-flow.light.svg new file mode 100644 index 0000000..5b6fc44 --- /dev/null +++ b/docs/assets/architecture/features/agentic-git-preferences-flow.light.svg @@ -0,0 +1,579 @@ + + hyperGit.agent.* 设置 → Agentic Git 动作 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / hyperGit.agent.* 设置（package.json contributes.configuration） + + + 02 / Agentic Git 动作（M5 消费） + + + + + + + + + + + + + + + + commitPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + commitPreferences + multilineText + + + + baseBranch · 留空 = 仓库默认分支 · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + baseBranch + 留空 = 仓库默认分支 + + + + createPrPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + createPrPreferences + multilineText + + + + reviewPreferences · multilineText · hyperGit.agent.* 设置（package.json contributes.configuration） + + + + reviewPreferences + multilineText + + + + 点击 Commit · Agentic Git 动作（M5 消费） + + + + 点击 Commit + + + + 点击 Create PR · Agentic Git 动作（M5 消费） + + + + 点击 Create PR + + + + 点击 Review · Agentic Git 动作（M5 消费） + + + + 点击 Review + + + + + + PR 基线分支 + + + + 自定义指令 + + + + 自定义指令 + + + + 自定义指令 + + + + + 图例 + + + 用户界面 + + + + 上下文 / 追踪 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.dark.svg b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.dark.svg new file mode 100644 index 0000000..eb7c8e4 --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.dark.svg @@ -0,0 +1,559 @@ + + 分支前缀分组 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / Adapter 映射 + + + 04 / 视图形态 + + + + + + + + + + RawRef[] · displayRefs · 已滤 origin/HEAD · 01 / 数据源 + + + + RawRef[] + displayRefs · 已滤 origin/HEAD + + + + buildRefTree() · engine/ref/ref-tree · trie + compact · 02 / Engine 算树 + + + + buildRefTree() + engine/ref/ref-tree · trie + compact + + + + BranchesTreeProvider · toBranchNodes() 递归映射 · 03 / Adapter 映射 + + + + BranchesTreeProvider + toBranchNodes() 递归映射 + + + + 文件夹节点 + 后缀叶子 · grouping on · 04 / 视图形态 + + + + 文件夹节点 + 后缀叶子 + grouping on + + + + 平铺（既有排序） · grouping off · 04 / 视图形态 + + + + 平铺（既有排序） + grouping off + + + + + + adapter 传入 + + + + RefTreeNode[] + folder / leaf + + + + grouping on + + + + grouping off + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.html b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.html new file mode 100644 index 0000000..d35648d --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.html @@ -0,0 +1,14898 @@ + + + + + + + 分支前缀分组 · 算树数据流 + + + + + + + + +
+ +
+
+
+

分支前缀分组 · 算树数据流

+
+
+ + + + + + + +
+ + 分支前缀分组 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / Adapter 映射 + + + 04 / 视图形态 + + + + + + + + + + RawRef[] · displayRefs · 已滤 origin/HEAD · 01 / 数据源 + + + + RawRef[] + displayRefs · 已滤 origin/HEAD + + + + buildRefTree() · engine/ref/ref-tree · trie + compact · 02 / Engine 算树 + + + + buildRefTree() + engine/ref/ref-tree · trie + compact + + + + BranchesTreeProvider · toBranchNodes() 递归映射 · 03 / Adapter 映射 + + + + BranchesTreeProvider + toBranchNodes() 递归映射 + + + + 文件夹节点 + 后缀叶子 · grouping on · 04 / 视图形态 + + + + 文件夹节点 + 后缀叶子 + grouping on + + + + 平铺（既有排序） · grouping off · 04 / 视图形态 + + + + 平铺（既有排序） + grouping off + + + + + + adapter 传入 + + + + RefTreeNode[] + folder / leaf + + + + grouping on + + + + grouping off + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

叶子携带完整 RawRef

+
+
    +
  • • label 取末段后缀，短名不丢
    • +
  • • checkout / 删除等命令仍以 ref.shortName 定位
    • +
+
+ +
+
+
+

分支感知排序

+
+
    +
  • • 当前 HEAD（第 0 档）→ 收藏（第 1 档）→ 文件夹在前
    • +
  • • 同档名称数字感知升序、稳定（相等按插入序）
    • +
+
+ +
+
+
+

过滤与折叠

+
+
    +
  • • origin/HEAD 由 isRemoteHead 统一过滤，计数归为真实分支数
    • +
  • • compact 折叠单目录子链 a/b/c → a/b，遇叶子或多子即停
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.light.svg b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.light.svg new file mode 100644 index 0000000..de4276f --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.light.svg @@ -0,0 +1,559 @@ + + 分支前缀分组 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / Adapter 映射 + + + 04 / 视图形态 + + + + + + + + + + RawRef[] · displayRefs · 已滤 origin/HEAD · 01 / 数据源 + + + + RawRef[] + displayRefs · 已滤 origin/HEAD + + + + buildRefTree() · engine/ref/ref-tree · trie + compact · 02 / Engine 算树 + + + + buildRefTree() + engine/ref/ref-tree · trie + compact + + + + BranchesTreeProvider · toBranchNodes() 递归映射 · 03 / Adapter 映射 + + + + BranchesTreeProvider + toBranchNodes() 递归映射 + + + + 文件夹节点 + 后缀叶子 · grouping on · 04 / 视图形态 + + + + 文件夹节点 + 后缀叶子 + grouping on + + + + 平铺（既有排序） · grouping off · 04 / 视图形态 + + + + 平铺（既有排序） + grouping off + + + + + + adapter 传入 + + + + RefTreeNode[] + folder / leaf + + + + grouping on + + + + grouping off + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.dark.svg b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.dark.svg new file mode 100644 index 0000000..79fd908 --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.dark.svg @@ -0,0 +1,512 @@ + + 分支前缀分组 · 平铺变前缀树 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Branches 视图 · Local 段 + + + + + + + + + + + + + + 平铺列表 · 切换前 · 共前缀分支逐条平铺 · Branches 视图 · Local 段 + + + + 平铺列表 · 切换前 + 共前缀分支逐条平铺 + + + + buildRefTree() · Group by Prefix · Branches 视图 · Local 段 + + + + buildRefTree() + Group by Prefix + + + + 前缀树 · 切换后 · 文件夹收拢 · 叶子留后缀 · Branches 视图 · Local 段 + + + + 前缀树 · 切换后 + 文件夹收拢 · 叶子留后缀 + + + + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.html b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.html new file mode 100644 index 0000000..4dc6ac6 --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.html @@ -0,0 +1,14864 @@ + + + + + + + 分支前缀分组 · 平铺变前缀树 + + + + + + + + +
+ +
+
+
+

分支前缀分组 · 平铺变前缀树

+
+
+ + + + + + + +
+ + 分支前缀分组 · 平铺变前缀树 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Branches 视图 · Local 段 + + + + + + + + + + + + + + 平铺列表 · 切换前 · 共前缀分支逐条平铺 · Branches 视图 · Local 段 + + + + 平铺列表 · 切换前 + 共前缀分支逐条平铺 + + + + buildRefTree() · Group by Prefix · Branches 视图 · Local 段 + + + + buildRefTree() + Group by Prefix + + + + 前缀树 · 切换后 · 文件夹收拢 · 叶子留后缀 · Branches 视图 · Local 段 + + + + 前缀树 · 切换后 + 文件夹收拢 · 叶子留后缀 + + + + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

切换前 · 平铺

+
+
    +
  • • bak/2025 · bak/master-2025-07
    • +
  • • feature/1.0.0
    • +
  • • 2022 / 2023 / 2024
    • +
+
+ +
+
+
+

切换后 · 前缀树

+
+
    +
  • • bak/ 文件夹 → 2025 · master-2025-07
    • +
  • • feature/ 文件夹 → 1.0.0
    • +
  • • 2022 / 2023 / 2024 无前缀保持平铺
    • +
+
+ +
+
+
+

远程段整体收拢

+
+
    +
  • • origin/feature/1.0.0 → origin/ → feature/ → 1.0.0
    • +
  • • 远程段收为单个 origin/ 文件夹，内部再嵌前缀
    • +
+
+ +
+
+
+

Favorites 与排序

+
+
    +
  • • Favorites 段恒平铺并显示完整短名
    • +
  • • HEAD → 收藏 → 文件夹在前 · 数字感知升序 · compact 折叠
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.light.svg b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.light.svg new file mode 100644 index 0000000..03e5c70 --- /dev/null +++ b/docs/assets/architecture/features/branch-tree-group-by-prefix-effect.light.svg @@ -0,0 +1,512 @@ + + 分支前缀分组 · 平铺变前缀树 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Branches 视图 · Local 段 + + + + + + + + + + + + + + 平铺列表 · 切换前 · 共前缀分支逐条平铺 · Branches 视图 · Local 段 + + + + 平铺列表 · 切换前 + 共前缀分支逐条平铺 + + + + buildRefTree() · Group by Prefix · Branches 视图 · Local 段 + + + + buildRefTree() + Group by Prefix + + + + 前缀树 · 切换后 · 文件夹收拢 · 叶子留后缀 · Branches 视图 · Local 段 + + + + 前缀树 · 切换后 + 文件夹收拢 · 叶子留后缀 + + + + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/claude-code-config-flow.dark.svg b/docs/assets/architecture/features/claude-code-config-flow.dark.svg new file mode 100644 index 0000000..4042289 --- /dev/null +++ b/docs/assets/architecture/features/claude-code-config-flow.dark.svg @@ -0,0 +1,597 @@ + + Claude Code 配置 · 设置与命令流向 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 设置界面 / 命令面板 + + + 02 / adapter/claude-commands.ts（唯一触 vscode） + + + 03 / engine/agent/claude-path.ts（纯函数，可单测） + + + + + + + + + + + + + + + + + + + hyperGit.claudeCode.executablePath · 默认空 = PATH 自动探测 · 设置界面 / 命令面板 + + + + hyperGit.claudeCode.executablePath + 默认空 = PATH 自动探测 + + + + setClaudeCodePath · 命令 · Set Executable Path… · 设置界面 / 命令面板 + + + + setClaudeCodePath + 命令 · Set Executable Path… + + + + openClaudeSettings · 命令 · Open Claude Settings · 设置界面 / 命令面板 + + + + openClaudeSettings + 命令 · Open Claude Settings + + + + 编辑器打开 settings.json · openTextDocument + showTextDocument · 设置界面 / 命令面板 + + + + 编辑器打开 settings.json + openTextDocument + showTextDocument + + + + QuickPick 选择 · Browse… / Use system · adapter/claude-commands.ts（唯一触 vscode） + + + + QuickPick 选择 + Browse… / Use system + + + + existsSync 检查 · 缺失时确认创建 {} · adapter/claude-commands.ts（唯一触 vscode） + + + + existsSync 检查 + 缺失时确认创建 {} + + + + defaultClaudeSettingsPath · 纯函数 · home 注入 · engine/agent/claude-path.ts（纯函数，可单测） + + + + defaultClaudeSettingsPath + 纯函数 · home 注入 + + + + + + + + 存在 / 确认创建后 + + + + home 注入 + + + + 写回 / 清空设置值 + + + + + 描述内嵌命令链接 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 工具操作 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/claude-code-config-flow.html b/docs/assets/architecture/features/claude-code-config-flow.html new file mode 100644 index 0000000..943a1ac --- /dev/null +++ b/docs/assets/architecture/features/claude-code-config-flow.html @@ -0,0 +1,14936 @@ + + + + + + + Claude Code 配置 · 设置与命令流向 + + + + + + + + +
+ +
+
+
+

Claude Code 配置 · 设置与命令流向

+
+
+ + + + + + + +
+ + Claude Code 配置 · 设置与命令流向 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 设置界面 / 命令面板 + + + 02 / adapter/claude-commands.ts（唯一触 vscode） + + + 03 / engine/agent/claude-path.ts（纯函数，可单测） + + + + + + + + + + + + + + + + + + + hyperGit.claudeCode.executablePath · 默认空 = PATH 自动探测 · 设置界面 / 命令面板 + + + + hyperGit.claudeCode.executablePath + 默认空 = PATH 自动探测 + + + + setClaudeCodePath · 命令 · Set Executable Path… · 设置界面 / 命令面板 + + + + setClaudeCodePath + 命令 · Set Executable Path… + + + + openClaudeSettings · 命令 · Open Claude Settings · 设置界面 / 命令面板 + + + + openClaudeSettings + 命令 · Open Claude Settings + + + + 编辑器打开 settings.json · openTextDocument + showTextDocument · 设置界面 / 命令面板 + + + + 编辑器打开 settings.json + openTextDocument + showTextDocument + + + + QuickPick 选择 · Browse… / Use system · adapter/claude-commands.ts（唯一触 vscode） + + + + QuickPick 选择 + Browse… / Use system + + + + existsSync 检查 · 缺失时确认创建 {} · adapter/claude-commands.ts（唯一触 vscode） + + + + existsSync 检查 + 缺失时确认创建 {} + + + + defaultClaudeSettingsPath · 纯函数 · home 注入 · engine/agent/claude-path.ts（纯函数，可单测） + + + + defaultClaudeSettingsPath + 纯函数 · home 注入 + + + + + + + + 存在 / 确认创建后 + + + + home 注入 + + + + 写回 / 清空设置值 + + + + + 描述内嵌命令链接 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 工具操作 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

分层契约

+
+
    +
  • • adapter 唯一触碰 vscode API；路径拼接下沉 engine 纯函数（Vitest 可单测）
    • +
  • • 命令经 extension.ts 装配 registerClaudeCommands()
    • +
+
+ +
+
+
+

M5 预置

+
+
    +
  • • 仅落地配置与快捷入口，Claude Code 真实调用留待 M5 实装
    • +
  • • agent/ 五接缝仍 Null，hyperGit.ai.enabled 行为不变
    • +
+
+ +
+
+
+

动作语义

+
+
    +
  • • Use system Claude Code 清空覆盖，回退 PATH 自动探测
    • +
  • • settings.json 缺失时经确认后 mkdir 并写入 {}，随后编辑器打开
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/claude-code-config-flow.light.svg b/docs/assets/architecture/features/claude-code-config-flow.light.svg new file mode 100644 index 0000000..0b0e339 --- /dev/null +++ b/docs/assets/architecture/features/claude-code-config-flow.light.svg @@ -0,0 +1,597 @@ + + Claude Code 配置 · 设置与命令流向 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 设置界面 / 命令面板 + + + 02 / adapter/claude-commands.ts（唯一触 vscode） + + + 03 / engine/agent/claude-path.ts（纯函数，可单测） + + + + + + + + + + + + + + + + + + + hyperGit.claudeCode.executablePath · 默认空 = PATH 自动探测 · 设置界面 / 命令面板 + + + + hyperGit.claudeCode.executablePath + 默认空 = PATH 自动探测 + + + + setClaudeCodePath · 命令 · Set Executable Path… · 设置界面 / 命令面板 + + + + setClaudeCodePath + 命令 · Set Executable Path… + + + + openClaudeSettings · 命令 · Open Claude Settings · 设置界面 / 命令面板 + + + + openClaudeSettings + 命令 · Open Claude Settings + + + + 编辑器打开 settings.json · openTextDocument + showTextDocument · 设置界面 / 命令面板 + + + + 编辑器打开 settings.json + openTextDocument + showTextDocument + + + + QuickPick 选择 · Browse… / Use system · adapter/claude-commands.ts（唯一触 vscode） + + + + QuickPick 选择 + Browse… / Use system + + + + existsSync 检查 · 缺失时确认创建 {} · adapter/claude-commands.ts（唯一触 vscode） + + + + existsSync 检查 + 缺失时确认创建 {} + + + + defaultClaudeSettingsPath · 纯函数 · home 注入 · engine/agent/claude-path.ts（纯函数，可单测） + + + + defaultClaudeSettingsPath + 纯函数 · home 注入 + + + + + + + + 存在 / 确认创建后 + + + + home 注入 + + + + 写回 / 清空设置值 + + + + + 描述内嵌命令链接 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 工具操作 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/file-list-group-by-directory-dataflow.dark.svg b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.dark.svg new file mode 100644 index 0000000..245b1bf --- /dev/null +++ b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.dark.svg @@ -0,0 +1,562 @@ + + 变更文件目录树 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / 下发渲染 + + + 04 / 形态切换 + + + + + + + + + + 扁平文件路径[] · 与 files[] 同序 · 01 / 数据源 + + + + 扁平文件路径[] + 与 files[] 同序 + + + + buildFileTree() · engine/tree/file-tree · 02 / Engine 算树 + + + + buildFileTree() + engine/tree/file-tree + + + + webview 渲染 · payload 携带树 · 03 / 下发渲染 + + + + webview 渲染 + payload 携带树 + + + + 平铺 · files[] 直接渲染 · 04 / 形态切换 + + + + 平铺 + files[] 直接渲染 + + + + 树形 · 叶子取 files[fileIndex] · 04 / 形态切换 + + + + 树形 + 叶子取 files[fileIndex] + + + + + + host 计算 + + + + FileTreeNode[] + 随 payload 下发 + + + + mode = flat + + + + mode = tree + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/file-list-group-by-directory-dataflow.html b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.html new file mode 100644 index 0000000..0ccc4a8 --- /dev/null +++ b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.html @@ -0,0 +1,14901 @@ + + + + + + + 变更文件目录树 · 算树数据流 + + + + + + + + +
+ +
+
+
+

变更文件目录树 · 算树数据流

+
+
+ + + + + + + +
+ + 变更文件目录树 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / 下发渲染 + + + 04 / 形态切换 + + + + + + + + + + 扁平文件路径[] · 与 files[] 同序 · 01 / 数据源 + + + + 扁平文件路径[] + 与 files[] 同序 + + + + buildFileTree() · engine/tree/file-tree · 02 / Engine 算树 + + + + buildFileTree() + engine/tree/file-tree + + + + webview 渲染 · payload 携带树 · 03 / 下发渲染 + + + + webview 渲染 + payload 携带树 + + + + 平铺 · files[] 直接渲染 · 04 / 形态切换 + + + + 平铺 + files[] 直接渲染 + + + + 树形 · 叶子取 files[fileIndex] · 04 / 形态切换 + + + + 树形 + 叶子取 files[fileIndex] + + + + + + host 计算 + + + + FileTreeNode[] + 随 payload 下发 + + + + mode = flat + + + + mode = tree + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

视图无关 FileTreeNode

+
+
    +
  • • 目录 name / path / children；叶子 fileIndex 回指扁平 files[]
    • +
  • • 定义于 shared/protocol.ts，两视图共用不复制条目
    • +
+
+ +
+
+
+

切换零 host 往返

+
+
    +
  • • 平铺 files[] 与树 tree[] 同批下发
    • +
  • • 切换 / 折叠仅 webview 本地重渲
    • +
+
+ +
+
+
+

服务两视图

+
+
    +
  • • Commit 视图：活动 Changelist 条目 path 建树，目录三态勾选
    • +
  • • Log 视图：选中提交 diff-tree 路径建树，只读浏览
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/file-list-group-by-directory-dataflow.light.svg b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.light.svg new file mode 100644 index 0000000..34f4cda --- /dev/null +++ b/docs/assets/architecture/features/file-list-group-by-directory-dataflow.light.svg @@ -0,0 +1,562 @@ + + 变更文件目录树 · 算树数据流 + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 数据源 + + + 02 / Engine 算树 + + + 03 / 下发渲染 + + + 04 / 形态切换 + + + + + + + + + + 扁平文件路径[] · 与 files[] 同序 · 01 / 数据源 + + + + 扁平文件路径[] + 与 files[] 同序 + + + + buildFileTree() · engine/tree/file-tree · 02 / Engine 算树 + + + + buildFileTree() + engine/tree/file-tree + + + + webview 渲染 · payload 携带树 · 03 / 下发渲染 + + + + webview 渲染 + payload 携带树 + + + + 平铺 · files[] 直接渲染 · 04 / 形态切换 + + + + 平铺 + files[] 直接渲染 + + + + 树形 · 叶子取 files[fileIndex] · 04 / 形态切换 + + + + 树形 + 叶子取 files[fileIndex] + + + + + + host 计算 + + + + FileTreeNode[] + 随 payload 下发 + + + + mode = flat + + + + mode = tree + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-ci-status-dataflow.dark.svg b/docs/assets/architecture/features/log-ci-status-dataflow.dark.svg new file mode 100644 index 0000000..0b8e50f --- /dev/null +++ b/docs/assets/architecture/features/log-ci-status-dataflow.dark.svg @@ -0,0 +1,666 @@ + + Log 视图 CI 状态数据流（GitHub Actions / Commit Status） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 本地建图 + + + 02 / Webview 懒加载 + + + 03 / Host 远程与认证 + + + 04 / GraphQL 与缓存 + + + 05 / 回填与跳转 + + + + + + + + + + + + + + + + git log → GraphRowVM · 01 / 本地建图 + + + + git log → GraphRowVM + + + + 图先渲染 · CI 不阻塞 · 01 / 本地建图 + + + + 图先渲染 + CI 不阻塞 + + + + log/requestCi · hashes[] · 02 / Webview 懒加载 + + + + log/requestCi + hashes[] + + + + 滚动收集未知 hash · 可见行懒加载 · 02 / Webview 懒加载 + + + + 滚动收集未知 hash + 可见行懒加载 + + + + 解析 origin 远程 · owner / repo / host · 03 / Host 远程与认证 + + + + 解析 origin 远程 + owner / repo / host + + + + vscode.authentication · token · repo 范围 · 03 / Host 远程与认证 + + + + vscode.authentication + token · repo 范围 + + + + GraphQL 批量 ≤100 oid · statusCheckRollup · 04 / GraphQL 与缓存 + + + + GraphQL 批量 ≤100 oid + statusCheckRollup + + + + 按 oid 缓存 · 终态永久 / pending 30s · 04 / GraphQL 与缓存 + + + + 按 oid 缓存 + 终态永久 / pending 30s + + + + openExternal · 校验 https + GitHub 主机 · 05 / 回填与跳转 + + + + openExternal + 校验 https + GitHub 主机 + + + + 悬停 → Tooltip 明细 · 各项检查 + 运行链接 · 05 / 回填与跳转 + + + + 悬停 → Tooltip 明细 + 各项检查 + 运行链接 + + + + webview 就地重绘图标 · 05 / 回填与跳转 + + + + webview 就地重绘图标 + + + + + + CI 不阻塞 + + + + 可见行懒加载 + + + + 防抖 200ms + + + + hashes[] + + + + host / owner / repo + + + + token + + + + rollup 归一化 + + + + log/ciData + + + + 悬停 + + + + log/openExternal + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-ci-status-dataflow.html b/docs/assets/architecture/features/log-ci-status-dataflow.html new file mode 100644 index 0000000..85f209a --- /dev/null +++ b/docs/assets/architecture/features/log-ci-status-dataflow.html @@ -0,0 +1,15005 @@ + + + + + + + Log 视图 CI 状态数据流（GitHub Actions / Commit Status） + + + + + + + + +
+ +
+
+
+

Log 视图 CI 状态数据流（GitHub Actions / Commit Status）

+
+
+ + + + + + + +
+ + Log 视图 CI 状态数据流（GitHub Actions / Commit Status） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 本地建图 + + + 02 / Webview 懒加载 + + + 03 / Host 远程与认证 + + + 04 / GraphQL 与缓存 + + + 05 / 回填与跳转 + + + + + + + + + + + + + + + + git log → GraphRowVM · 01 / 本地建图 + + + + git log → GraphRowVM + + + + 图先渲染 · CI 不阻塞 · 01 / 本地建图 + + + + 图先渲染 + CI 不阻塞 + + + + log/requestCi · hashes[] · 02 / Webview 懒加载 + + + + log/requestCi + hashes[] + + + + 滚动收集未知 hash · 可见行懒加载 · 02 / Webview 懒加载 + + + + 滚动收集未知 hash + 可见行懒加载 + + + + 解析 origin 远程 · owner / repo / host · 03 / Host 远程与认证 + + + + 解析 origin 远程 + owner / repo / host + + + + vscode.authentication · token · repo 范围 · 03 / Host 远程与认证 + + + + vscode.authentication + token · repo 范围 + + + + GraphQL 批量 ≤100 oid · statusCheckRollup · 04 / GraphQL 与缓存 + + + + GraphQL 批量 ≤100 oid + statusCheckRollup + + + + 按 oid 缓存 · 终态永久 / pending 30s · 04 / GraphQL 与缓存 + + + + 按 oid 缓存 + 终态永久 / pending 30s + + + + openExternal · 校验 https + GitHub 主机 · 05 / 回填与跳转 + + + + openExternal + 校验 https + GitHub 主机 + + + + 悬停 → Tooltip 明细 · 各项检查 + 运行链接 · 05 / 回填与跳转 + + + + 悬停 → Tooltip 明细 + 各项检查 + 运行链接 + + + + webview 就地重绘图标 · 05 / 回填与跳转 + + + + webview 就地重绘图标 + + + + + + CI 不阻塞 + + + + 可见行懒加载 + + + + 防抖 200ms + + + + hashes[] + + + + host / owner / repo + + + + token + + + + rollup 归一化 + + + + log/ciData + + + + 悬停 + + + + log/openExternal + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

懒加载与批量

+
+
    +
  • • 虚拟滚动仅渲染 ~50 行，滚动收集未知 hash（防抖 200ms）
    • +
  • • 单次 GraphQL 最多 100 个 oid 的 statusCheckRollup，并发上限 2
    • +
+
+ +
+
+
+

缓存与限流

+
+
    +
  • • 终态（success/failure）整会话缓存；pending/unknown 30s TTL
    • +
  • • rateLimit <100 或 403 进入冷却：只走缓存并一次性提示
    • +
+
+ +
+
+
+

认证与安全

+
+
    +
  • • 复用 VS Code 内置 GitHub 认证，静默优先（createIfNone:false）绝不弹窗
    • +
  • • openExternal 反 SSRF：host 校验 https 且主机 ∈ {仓库主机, *.github.com}
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/log-ci-status-dataflow.light.svg b/docs/assets/architecture/features/log-ci-status-dataflow.light.svg new file mode 100644 index 0000000..c6482b5 --- /dev/null +++ b/docs/assets/architecture/features/log-ci-status-dataflow.light.svg @@ -0,0 +1,666 @@ + + Log 视图 CI 状态数据流（GitHub Actions / Commit Status） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 本地建图 + + + 02 / Webview 懒加载 + + + 03 / Host 远程与认证 + + + 04 / GraphQL 与缓存 + + + 05 / 回填与跳转 + + + + + + + + + + + + + + + + git log → GraphRowVM · 01 / 本地建图 + + + + git log → GraphRowVM + + + + 图先渲染 · CI 不阻塞 · 01 / 本地建图 + + + + 图先渲染 + CI 不阻塞 + + + + log/requestCi · hashes[] · 02 / Webview 懒加载 + + + + log/requestCi + hashes[] + + + + 滚动收集未知 hash · 可见行懒加载 · 02 / Webview 懒加载 + + + + 滚动收集未知 hash + 可见行懒加载 + + + + 解析 origin 远程 · owner / repo / host · 03 / Host 远程与认证 + + + + 解析 origin 远程 + owner / repo / host + + + + vscode.authentication · token · repo 范围 · 03 / Host 远程与认证 + + + + vscode.authentication + token · repo 范围 + + + + GraphQL 批量 ≤100 oid · statusCheckRollup · 04 / GraphQL 与缓存 + + + + GraphQL 批量 ≤100 oid + statusCheckRollup + + + + 按 oid 缓存 · 终态永久 / pending 30s · 04 / GraphQL 与缓存 + + + + 按 oid 缓存 + 终态永久 / pending 30s + + + + openExternal · 校验 https + GitHub 主机 · 05 / 回填与跳转 + + + + openExternal + 校验 https + GitHub 主机 + + + + 悬停 → Tooltip 明细 · 各项检查 + 运行链接 · 05 / 回填与跳转 + + + + 悬停 → Tooltip 明细 + 各项检查 + 运行链接 + + + + webview 就地重绘图标 · 05 / 回填与跳转 + + + + webview 就地重绘图标 + + + + + + CI 不阻塞 + + + + 可见行懒加载 + + + + 防抖 200ms + + + + hashes[] + + + + host / owner / repo + + + + token + + + + rollup 归一化 + + + + log/ciData + + + + 悬停 + + + + log/openExternal + + + + + 图例 + + + 主要数据 + + + + 数据存储 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-commit-detail-panel-dataflow.dark.svg b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.dark.svg new file mode 100644 index 0000000..a333b28 --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.dark.svg @@ -0,0 +1,628 @@ + + Commit 详情面板数据流（选中 → 取数 → 渲染） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 选中与事件入口 + + + 02 / Webview 动作 + + + 03 / 取数与反馈 + + + 04 / 渲染 + + + + + + + + + + + + + + 点击 / 方向键选中行 · 01 / 选中与事件入口 + + + + 点击 / 方向键选中行 + + + + log/graphData · 刷新 / 切库 / 重载 · 01 / 选中与事件入口 + + + + log/graphData + 刷新 / 切库 / 重载 + + + + selectRow · log/selectCommit · 02 / Webview 动作 + + + + selectRow + log/selectCommit + + + + × / Esc → deselectRow · 取反收起 · 幂等守卫 · 02 / Webview 动作 + + + + × / Esc → deselectRow + 取反收起 · 幂等守卫 + + + + host 并行取数 · sendCommitFiles + showCommitDetail · 03 / 取数与反馈 + + + + host 并行取数 + sendCommitFiles + showCommitDetail + + + + Loading 占位 · 两区即时反馈 · 03 / 取数与反馈 + + + + Loading 占位 + 两区即时反馈 + + + + 面板隐藏 + 清选中 + persist · 03 / 取数与反馈 + + + + 面板隐藏 + 清选中 + persist + + + + renderCommitMeta · forHash 校验 · 04 / 渲染 + + + + renderCommitMeta + forHash 校验 + + + + renderDetails · Changed Files · hash 校验 · 04 / 渲染 + + + + renderDetails + Changed Files · hash 校验 + + + + + + selectRow + + + + 选中在 · 补拉 + + + + 选中消失 + + + + log/selectCommit{hash} + + + + 即时反馈 + + + + log/commitFiles{hash} + + + + log/commitDetail + + + + 收面板 + + + + + 图例 + + + 主要数据 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-commit-detail-panel-dataflow.html b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.html new file mode 100644 index 0000000..00d283e --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.html @@ -0,0 +1,14967 @@ + + + + + + + Commit 详情面板数据流（选中 → 取数 → 渲染） + + + + + + + + +
+ +
+
+
+

Commit 详情面板数据流（选中 → 取数 → 渲染）

+
+
+ + + + + + + +
+ + Commit 详情面板数据流（选中 → 取数 → 渲染） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 选中与事件入口 + + + 02 / Webview 动作 + + + 03 / 取数与反馈 + + + 04 / 渲染 + + + + + + + + + + + + + + 点击 / 方向键选中行 · 01 / 选中与事件入口 + + + + 点击 / 方向键选中行 + + + + log/graphData · 刷新 / 切库 / 重载 · 01 / 选中与事件入口 + + + + log/graphData + 刷新 / 切库 / 重载 + + + + selectRow · log/selectCommit · 02 / Webview 动作 + + + + selectRow + log/selectCommit + + + + × / Esc → deselectRow · 取反收起 · 幂等守卫 · 02 / Webview 动作 + + + + × / Esc → deselectRow + 取反收起 · 幂等守卫 + + + + host 并行取数 · sendCommitFiles + showCommitDetail · 03 / 取数与反馈 + + + + host 并行取数 + sendCommitFiles + showCommitDetail + + + + Loading 占位 · 两区即时反馈 · 03 / 取数与反馈 + + + + Loading 占位 + 两区即时反馈 + + + + 面板隐藏 + 清选中 + persist · 03 / 取数与反馈 + + + + 面板隐藏 + 清选中 + persist + + + + renderCommitMeta · forHash 校验 · 04 / 渲染 + + + + renderCommitMeta + forHash 校验 + + + + renderDetails · Changed Files · hash 校验 · 04 / 渲染 + + + + renderDetails + Changed Files · hash 校验 + + + + + + selectRow + + + + 选中在 · 补拉 + + + + 选中消失 + + + + log/selectCommit{hash} + + + + 即时反馈 + + + + log/commitFiles{hash} + + + + log/commitDetail + + + + 收面板 + + + + + 图例 + + + 主要数据 + + + + 数据流 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

过期回包丢弃

+
+
    +
  • • log/commitFiles 按 hash、log/commitDetail 按 forHash 回显校验
    • +
  • • 失败回包 vm=null 无 hash 可比对，forHash 补齐该盲区
    • +
+
+ +
+
+
+

同 hash 重点击取反

+
+
    +
  • • 再次点击已选中行 = 收起面板；<300ms 第二击视为双击豁免
    • +
  • • 取数失败态（metaFailHash）重点击例外放行重试
    • +
+
+ +
+
+
+

重载恢复

+
+
    +
  • • 选中 hash 按仓库持久化（state v2），graphData 到达且行存在时补拉
    • +
  • • deselectRow 幂等守卫同时校验选中态与面板可见性
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/log-commit-detail-panel-dataflow.light.svg b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.light.svg new file mode 100644 index 0000000..aed4064 --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-dataflow.light.svg @@ -0,0 +1,628 @@ + + Commit 详情面板数据流（选中 → 取数 → 渲染） + 由 Archify 生成的数据流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 选中与事件入口 + + + 02 / Webview 动作 + + + 03 / 取数与反馈 + + + 04 / 渲染 + + + + + + + + + + + + + + 点击 / 方向键选中行 · 01 / 选中与事件入口 + + + + 点击 / 方向键选中行 + + + + log/graphData · 刷新 / 切库 / 重载 · 01 / 选中与事件入口 + + + + log/graphData + 刷新 / 切库 / 重载 + + + + selectRow · log/selectCommit · 02 / Webview 动作 + + + + selectRow + log/selectCommit + + + + × / Esc → deselectRow · 取反收起 · 幂等守卫 · 02 / Webview 动作 + + + + × / Esc → deselectRow + 取反收起 · 幂等守卫 + + + + host 并行取数 · sendCommitFiles + showCommitDetail · 03 / 取数与反馈 + + + + host 并行取数 + sendCommitFiles + showCommitDetail + + + + Loading 占位 · 两区即时反馈 · 03 / 取数与反馈 + + + + Loading 占位 + 两区即时反馈 + + + + 面板隐藏 + 清选中 + persist · 03 / 取数与反馈 + + + + 面板隐藏 + 清选中 + persist + + + + renderCommitMeta · forHash 校验 · 04 / 渲染 + + + + renderCommitMeta + forHash 校验 + + + + renderDetails · Changed Files · hash 校验 · 04 / 渲染 + + + + renderDetails + Changed Files · hash 校验 + + + + + + selectRow + + + + 选中在 · 补拉 + + + + 选中消失 + + + + log/selectCommit{hash} + + + + 即时反馈 + + + + log/commitFiles{hash} + + + + log/commitDetail + + + + 收面板 + + + + + 图例 + + + 主要数据 + + + + 数据流 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-commit-detail-panel-layout.dark.svg b/docs/assets/architecture/features/log-commit-detail-panel-layout.dark.svg new file mode 100644 index 0000000..98007bf --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-layout.dark.svg @@ -0,0 +1,580 @@ + + Commit 详情面板布局（Graph webview 内部左右分栏） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + VS Code 标题栏 · view/title · Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* · 架构组件 + + + + VS Code 标题栏 · view/title + Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* + + + + #viewport 提交图 · flex:1 · 虚拟滚动 · min-width:0 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + #viewport 提交图 + flex:1 · 虚拟滚动 · min-width:0 + + + + #gutter-main · 拖拽 ⇄ 面板宽/高 18%–75% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） · 横向 ≥200px 且图 ≥280px + + + + #gutter-main + 拖拽 ⇄ 面板宽/高 18%–75% + 横向 ≥200px 且图 ≥280px + + + + #details · Changed Files + × · 独立滚动 · 上半区 55% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #details · Changed Files + × + 独立滚动 · 上半区 55% + + + + #gutter-meta · 拖拽 ⇄ 上/下半区高 15%–85% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #gutter-meta + 拖拽 ⇄ 上/下半区高 15%–85% + + + + #commit-meta · 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #commit-meta + 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 + + + + + + WebviewView 容器 + + + + 相邻分栏 + + + + 面板入口 + + + + ⇄ 上/下半区高 + + + + + + + #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + + #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + + 图例 + + + 前端 + + + + 外部系统 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/log-commit-detail-panel-layout.html b/docs/assets/architecture/features/log-commit-detail-panel-layout.html new file mode 100644 index 0000000..2475e43 --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-layout.html @@ -0,0 +1,14930 @@ + + + + + + + Commit 详情面板布局（Graph webview 内部左右分栏） + + + + + + + + +
+ +
+
+
+

Commit 详情面板布局（Graph webview 内部左右分栏）

+
+
+ + + + + + + +
+ + Commit 详情面板布局（Graph webview 内部左右分栏） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + VS Code 标题栏 · view/title · Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* · 架构组件 + + + + VS Code 标题栏 · view/title + Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* + + + + #viewport 提交图 · flex:1 · 虚拟滚动 · min-width:0 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + #viewport 提交图 + flex:1 · 虚拟滚动 · min-width:0 + + + + #gutter-main · 拖拽 ⇄ 面板宽/高 18%–75% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） · 横向 ≥200px 且图 ≥280px + + + + #gutter-main + 拖拽 ⇄ 面板宽/高 18%–75% + 横向 ≥200px 且图 ≥280px + + + + #details · Changed Files + × · 独立滚动 · 上半区 55% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #details · Changed Files + × + 独立滚动 · 上半区 55% + + + + #gutter-meta · 拖拽 ⇄ 上/下半区高 15%–85% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #gutter-meta + 拖拽 ⇄ 上/下半区高 15%–85% + + + + #commit-meta · 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #commit-meta + 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 + + + + + + WebviewView 容器 + + + + 相邻分栏 + + + + 面板入口 + + + + ⇄ 上/下半区高 + + + + + + + #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + + #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + + 图例 + + + 前端 + + + + 外部系统 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

分栏与钳制

+
+
    +
  • • 横向：面板 ≥200px 且图区 ≥280px（panelPct 18%–75%）
    • +
  • • 纵向：上半区 detailPct 15%–85%；比例按仓库记忆
    • +
+
+ +
+
+
+

窄视口降级

+
+
    +
  • • #main < 560px 切 .stacked 上下堆叠（面板 45% / 图区 55%）
    • +
  • • 观察 #main 而非 #viewport，避免「开面板→变窄→堆叠」反馈环
    • +
+
+ +
+
+
+

gutter 交互

+
+
    +
  • • pointerdown 捕获 → pointermove 实时 flex-basis → pointerup 持久化
    • +
  • • role=separator 键盘可达：方向键 ±2%、Home/End 归边界
    • +
+
+ +
+
+
+

可见性不变式

+
+
    +
  • • #commit-panel.show ⟺ selectedHash !== null
    • +
  • • 路径收敛于 requestPanelData / deselectRow / graphData 三漏斗
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/log-commit-detail-panel-layout.light.svg b/docs/assets/architecture/features/log-commit-detail-panel-layout.light.svg new file mode 100644 index 0000000..18c00c5 --- /dev/null +++ b/docs/assets/architecture/features/log-commit-detail-panel-layout.light.svg @@ -0,0 +1,580 @@ + + Commit 详情面板布局（Graph webview 内部左右分栏） + 由 Archify 生成的架构图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + VS Code 标题栏 · view/title · Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* · 架构组件 + + + + VS Code 标题栏 · view/title + Graph + description(仓库路径) · Scope ▾ · List ⇄ Tree · refresh · sign-in* · repo* + + + + #viewport 提交图 · flex:1 · 虚拟滚动 · min-width:0 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + #viewport 提交图 + flex:1 · 虚拟滚动 · min-width:0 + + + + #gutter-main · 拖拽 ⇄ 面板宽/高 18%–75% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） · 横向 ≥200px 且图 ≥280px + + + + #gutter-main + 拖拽 ⇄ 面板宽/高 18%–75% + 横向 ≥200px 且图 ≥280px + + + + #details · Changed Files + × · 独立滚动 · 上半区 55% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #details · Changed Files + × + 独立滚动 · 上半区 55% + + + + #gutter-meta · 拖拽 ⇄ 上/下半区高 15%–85% · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #gutter-meta + 拖拽 ⇄ 上/下半区高 15%–85% + + + + #commit-meta · 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 · #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） › #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + #commit-meta + 作者 / 引用分组 / 消息 / 统计 / SHA · 独立滚动 + + + + + + WebviewView 容器 + + + + 相邻分栏 + + + + 面板入口 + + + + ⇄ 上/下半区高 + + + + + + + #commit-panel（flex-basis 拖拽钳制 · min-width 200px） + + + + + #main（≥560px 横向 flex / <560px .stacked 纵向堆叠） + + + + + 图例 + + + 前端 + + + + 外部系统 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/multi-root-repo-selection-sequence.dark.svg b/docs/assets/architecture/features/multi-root-repo-selection-sequence.dark.svg new file mode 100644 index 0000000..fec2d32 --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-sequence.dark.svg @@ -0,0 +1,569 @@ + + 仓库切换级联时序 · 三重顺序不变量 + 由 Archify 生成的时序图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + selectRepository(rootB) + + 内部 applyRepository(repoB) 置换活跃仓库 + + + + + + + ① onDidChangeRepository.fire（同步） + + + + + + + + ② onDidChange.fire（其后） + + + + + + + + refreshAll（150ms 防抖）重取数据 + + + + + + + ① 同步 rebind 区间（先于任何视图重取） + + + + ② 视图防抖重取（其后） + + + + + 用户 · 时序参与者 + + + + 用户 + + + + GitRepositoryService · applyRepository · 时序参与者 + + + + GitRepositoryService + applyRepository + + + + rebind 订阅 · extension.ts · 时序参与者 + + + + rebind 订阅 + extension.ts + + + + 视图刷新链 · refreshAll · 时序参与者 + + + + 视图刷新链 + refreshAll + + + + + 图例 + + + 请求 + + + + 返回 + + + + 异步追踪 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/multi-root-repo-selection-sequence.html b/docs/assets/architecture/features/multi-root-repo-selection-sequence.html new file mode 100644 index 0000000..3c18706 --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-sequence.html @@ -0,0 +1,14909 @@ + + + + + + + 仓库切换级联时序 · 三重顺序不变量 + + + + + + + + +
+ +
+
+
+

仓库切换级联时序 · 三重顺序不变量

+
+
+ + + + + + + +
+ + 仓库切换级联时序 · 三重顺序不变量 + 由 Archify 生成的时序图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + selectRepository(rootB) + + 内部 applyRepository(repoB) 置换活跃仓库 + + + + + + + ① onDidChangeRepository.fire（同步） + + + + + + + + ② onDidChange.fire（其后） + + + + + + + + refreshAll（150ms 防抖）重取数据 + + + + + + + ① 同步 rebind 区间（先于任何视图重取） + + + + ② 视图防抖重取（其后） + + + + + 用户 · 时序参与者 + + + + 用户 + + + + GitRepositoryService · applyRepository · 时序参与者 + + + + GitRepositoryService + applyRepository + + + + rebind 订阅 · extension.ts · 时序参与者 + + + + rebind 订阅 + extension.ts + + + + 视图刷新链 · refreshAll · 时序参与者 + + + + 视图刷新链 + refreshAll + + + + + 图例 + + + 请求 + + + + 返回 + + + + 异步追踪 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

rebind 同步动作（① 区间内）

+
+
    +
  • • registry / favorites / branchesTree.setRepoRoot（换 memento key 重载）
    • +
  • • branchesGrouping context key 同步
    • +
  • • blame 注解清理 · Graph filter 清空
    • +
+
+ +
+
+
+

不变量一 · ① 先于 ②

+
+
    +
  • • rebind 在同步栈完成后，② 才触发视图重取
    • +
  • • 任何视图重取数据必然发生在 rebind 之后
    • +
+
+ +
+
+
+

不变量二/三 · 注册序 + 防抖兜底

+
+
    +
  • • rebind 订阅先于 service.onDidChange(refreshAll) 注册（extension.ts）
    • +
  • • 即使前两层被破坏，150ms/400ms 防抖刷新仍晚于同步 rebind
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/multi-root-repo-selection-sequence.light.svg b/docs/assets/architecture/features/multi-root-repo-selection-sequence.light.svg new file mode 100644 index 0000000..a2281bf --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-sequence.light.svg @@ -0,0 +1,569 @@ + + 仓库切换级联时序 · 三重顺序不变量 + 由 Archify 生成的时序图。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + selectRepository(rootB) + + 内部 applyRepository(repoB) 置换活跃仓库 + + + + + + + ① onDidChangeRepository.fire（同步） + + + + + + + + ② onDidChange.fire（其后） + + + + + + + + refreshAll（150ms 防抖）重取数据 + + + + + + + ① 同步 rebind 区间（先于任何视图重取） + + + + ② 视图防抖重取（其后） + + + + + 用户 · 时序参与者 + + + + 用户 + + + + GitRepositoryService · applyRepository · 时序参与者 + + + + GitRepositoryService + applyRepository + + + + rebind 订阅 · extension.ts · 时序参与者 + + + + rebind 订阅 + extension.ts + + + + 视图刷新链 · refreshAll · 时序参与者 + + + + 视图刷新链 + refreshAll + + + + + 图例 + + + 请求 + + + + 返回 + + + + 异步追踪 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/multi-root-repo-selection-toolbar.dark.svg b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.dark.svg new file mode 100644 index 0000000..ee451d8 --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.dark.svg @@ -0,0 +1,568 @@ + + 多根工作区 · Graph 工具栏仓库切换 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Graph 标题栏 · 用户交互 + + + 02 / Host · GitRepositoryService + + + + + + + + + + + + + + + + Scope 下拉 · All / Current / Checkpoints · Graph 标题栏 · 用户交互 + + + + Scope 下拉 + All / Current / Checkpoints + + + + repo 图标按钮 · multiRepo 时显隐 · Graph 标题栏 · 用户交互 · view/title + + + + repo 图标按钮 + multiRepo 时显隐 + view/title + + + + QuickPick · 仓库名 + 路径 · 当前项 ✓ · Graph 标题栏 · 用户交互 + + + + QuickPick + 仓库名 + 路径 · 当前项 ✓ + + + + 七视图级联跟随 · 重取数据 · 状态级联 · Graph 标题栏 · 用户交互 + + + + 七视图级联跟随 + 重取数据 · 状态级联 + + + + selectRepository(root) · repository-selection.ts · Host · GitRepositoryService + + + + selectRepository(root) + repository-selection.ts + + + + applyRepository · 持久化 activeRepoRoot · Host · GitRepositoryService + + + + applyRepository + 持久化 activeRepoRoot + + + + + + click 直调命令 + + + + 选中 + + + + + 事件级联 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + \ No newline at end of file diff --git a/docs/assets/architecture/features/multi-root-repo-selection-toolbar.html b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.html new file mode 100644 index 0000000..ced98ba --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.html @@ -0,0 +1,14907 @@ + + + + + + + 多根工作区 · Graph 工具栏仓库切换 + + + + + + + + +
+ +
+
+
+

多根工作区 · Graph 工具栏仓库切换

+
+
+ + + + + + + +
+ + 多根工作区 · Graph 工具栏仓库切换 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Graph 标题栏 · 用户交互 + + + 02 / Host · GitRepositoryService + + + + + + + + + + + + + + + + Scope 下拉 · All / Current / Checkpoints · Graph 标题栏 · 用户交互 + + + + Scope 下拉 + All / Current / Checkpoints + + + + repo 图标按钮 · multiRepo 时显隐 · Graph 标题栏 · 用户交互 · view/title + + + + repo 图标按钮 + multiRepo 时显隐 + view/title + + + + QuickPick · 仓库名 + 路径 · 当前项 ✓ · Graph 标题栏 · 用户交互 + + + + QuickPick + 仓库名 + 路径 · 当前项 ✓ + + + + 七视图级联跟随 · 重取数据 · 状态级联 · Graph 标题栏 · 用户交互 + + + + 七视图级联跟随 + 重取数据 · 状态级联 + + + + selectRepository(root) · repository-selection.ts · Host · GitRepositoryService + + + + selectRepository(root) + repository-selection.ts + + + + applyRepository · 持久化 activeRepoRoot · Host · GitRepositoryService + + + + applyRepository + 持久化 activeRepoRoot + + + + + + click 直调命令 + + + + 选中 + + + + + 事件级联 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

双入口

+
+
    +
  • • 主入口：Graph 标题栏 repo 图标按钮（view == hyperGit.log 且 hyperGit.log.multiRepo 时显隐）
    • +
  • • 入口二：Command Palette → Hyper Git: Select Repository…（单仓库提示 no-op）
    • +
+
+ +
+
+
+

持久化

+
+
    +
  • • 活跃仓库记于 workspaceState（hyperGit.activeRepoRoot，per-workspace 隔离）
    • +
  • • 重开窗口恢复上次操作的仓库
    • +
+
+ +
+
+
+

按仓库隔离记忆

+
+
    +
  • • changelist 分配 · 分支收藏 · 分支分组偏好 · Shelf 存储 · 最近提交消息
    • +
  • • 全部 execGit 调用（cwd 恒为活跃仓库根）零改动自动跟随
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/features/multi-root-repo-selection-toolbar.light.svg b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.light.svg new file mode 100644 index 0000000..9b26229 --- /dev/null +++ b/docs/assets/architecture/features/multi-root-repo-selection-toolbar.light.svg @@ -0,0 +1,568 @@ + + 多根工作区 · Graph 工具栏仓库切换 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / Graph 标题栏 · 用户交互 + + + 02 / Host · GitRepositoryService + + + + + + + + + + + + + + + + Scope 下拉 · All / Current / Checkpoints · Graph 标题栏 · 用户交互 + + + + Scope 下拉 + All / Current / Checkpoints + + + + repo 图标按钮 · multiRepo 时显隐 · Graph 标题栏 · 用户交互 · view/title + + + + repo 图标按钮 + multiRepo 时显隐 + view/title + + + + QuickPick · 仓库名 + 路径 · 当前项 ✓ · Graph 标题栏 · 用户交互 + + + + QuickPick + 仓库名 + 路径 · 当前项 ✓ + + + + 七视图级联跟随 · 重取数据 · 状态级联 · Graph 标题栏 · 用户交互 + + + + 七视图级联跟随 + 重取数据 · 状态级联 + + + + selectRepository(root) · repository-selection.ts · Host · GitRepositoryService + + + + selectRepository(root) + repository-selection.ts + + + + applyRepository · 持久化 activeRepoRoot · Host · GitRepositoryService + + + + applyRepository + 持久化 activeRepoRoot + + + + + + click 直调命令 + + + + 选中 + + + + + 事件级联 + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + \ No newline at end of file diff --git a/docs/assets/architecture/research/ai-agent-seams-pipeline.dark.svg b/docs/assets/architecture/research/ai-agent-seams-pipeline.dark.svg new file mode 100644 index 0000000..eba88bb --- /dev/null +++ b/docs/assets/architecture/research/ai-agent-seams-pipeline.dark.svg @@ -0,0 +1,700 @@ + + Commit 流水线 · Hook A–F 责任链 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 主提交链（Engine 编排） + + + 02 / Agent 生成支线 + + + + EX / 阻断与拆分回退 + + + 04 / 提交后处理（Hook D–F） + + + + + 收集 + 消息 + + + 提交前闸门 + + + 提交 + 后处理 + + + + + + + + + + + + + + + + + + + + + + 点击 Commit · 收集 staged diff · 主提交链（Engine 编排） › 收集 + 消息 + + + + 点击 Commit + 收集 staged diff + + + + Hook A 消息生成 · ICommitMessageProvider · 主提交链（Engine 编排） › 收集 + 消息 + + + + Hook A 消息生成 + ICommitMessageProvider + + + + 提交消息定稿 · AI 建议经确认 / 编辑 · 主提交链（Engine 编排） › 收集 + 消息 + + + + 提交消息定稿 + AI 建议经确认 / 编辑 + + + + Hook B 提交检查 · IPreCommitInspector 责任链 · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook B 提交检查 + IPreCommitInspector 责任链 + + + + Hook C 分组校验 · IChangelistGrouper · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook C 分组校验 + IChangelistGrouper + + + + git commit · Engine 执行提交 · 主提交链（Engine 编排） › 提交 + 后处理 + + + + git commit + Engine 执行提交 + + + + Agent 流式生成 · Conventional Commits 校验 · Agent 生成支线 › 收集 + 消息 + + + + Agent 流式生成 + Conventional Commits 校验 + + + + 展示问题列表 · 阻断提交 · 返回收集 · 阻断与拆分回退 › 提交前闸门 + + + + 展示问题列表 + 阻断提交 · 返回收集 + + + + 建议拆分 commit · 回 Hook A 重新生成 · 阻断与拆分回退 › 提交前闸门 + + + + 建议拆分 commit + 回 Hook A 重新生成 + + + + Hook F 冲突解决 · IConflictResolver 逐块确认 · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook F 冲突解决 + IConflictResolver 逐块确认 + + + + Hook E 失败处理 · checkinFailed · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook E 失败处理 + checkinFailed + + + + Hook D 成功后处理 · checkinSuccessful 回调 · 提交后处理（Hook D–F） › 提交 + 后处理 + + + + Hook D 成功后处理 + checkinSuccessful 回调 + + + + + + 可选 Push + + + + + 用户确认 / 编辑 + + + + 启用 + + + + 未启用 / 已手填 + + + + 阻断 + + + + 检查通过 + + + + 单组 / 已确认 + + + + 建议拆分 + + + + 提交 / Push 失败 + + + + 可触发 + + + + 确认后重新提交 + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 策略 + + + + 云服务 + + + \ No newline at end of file diff --git a/docs/assets/architecture/research/ai-agent-seams-pipeline.html b/docs/assets/architecture/research/ai-agent-seams-pipeline.html new file mode 100644 index 0000000..7eca5c4 --- /dev/null +++ b/docs/assets/architecture/research/ai-agent-seams-pipeline.html @@ -0,0 +1,15039 @@ + + + + + + + Commit 流水线 · Hook A–F 责任链 + + + + + + + + +
+ +
+
+
+

Commit 流水线 · Hook A–F 责任链

+
+
+ + + + + + + +
+ + Commit 流水线 · Hook A–F 责任链 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 主提交链（Engine 编排） + + + 02 / Agent 生成支线 + + + + EX / 阻断与拆分回退 + + + 04 / 提交后处理（Hook D–F） + + + + + 收集 + 消息 + + + 提交前闸门 + + + 提交 + 后处理 + + + + + + + + + + + + + + + + + + + + + + 点击 Commit · 收集 staged diff · 主提交链（Engine 编排） › 收集 + 消息 + + + + 点击 Commit + 收集 staged diff + + + + Hook A 消息生成 · ICommitMessageProvider · 主提交链（Engine 编排） › 收集 + 消息 + + + + Hook A 消息生成 + ICommitMessageProvider + + + + 提交消息定稿 · AI 建议经确认 / 编辑 · 主提交链（Engine 编排） › 收集 + 消息 + + + + 提交消息定稿 + AI 建议经确认 / 编辑 + + + + Hook B 提交检查 · IPreCommitInspector 责任链 · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook B 提交检查 + IPreCommitInspector 责任链 + + + + Hook C 分组校验 · IChangelistGrouper · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook C 分组校验 + IChangelistGrouper + + + + git commit · Engine 执行提交 · 主提交链（Engine 编排） › 提交 + 后处理 + + + + git commit + Engine 执行提交 + + + + Agent 流式生成 · Conventional Commits 校验 · Agent 生成支线 › 收集 + 消息 + + + + Agent 流式生成 + Conventional Commits 校验 + + + + 展示问题列表 · 阻断提交 · 返回收集 · 阻断与拆分回退 › 提交前闸门 + + + + 展示问题列表 + 阻断提交 · 返回收集 + + + + 建议拆分 commit · 回 Hook A 重新生成 · 阻断与拆分回退 › 提交前闸门 + + + + 建议拆分 commit + 回 Hook A 重新生成 + + + + Hook F 冲突解决 · IConflictResolver 逐块确认 · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook F 冲突解决 + IConflictResolver 逐块确认 + + + + Hook E 失败处理 · checkinFailed · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook E 失败处理 + checkinFailed + + + + Hook D 成功后处理 · checkinSuccessful 回调 · 提交后处理（Hook D–F） › 提交 + 后处理 + + + + Hook D 成功后处理 + checkinSuccessful 回调 + + + + + + 可选 Push + + + + + 用户确认 / 编辑 + + + + 启用 + + + + 未启用 / 已手填 + + + + 阻断 + + + + 检查通过 + + + + 单组 / 已确认 + + + + 建议拆分 + + + + 提交 / Push 失败 + + + + 可触发 + + + + 确认后重新提交 + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 策略 + + + + 云服务 + + + +

+ + + + + + + + + +
+ + +
+
+
+
+

责任链契约

+
+
    +
  • • 每个 Hook 返回 COMMIT / CANCEL / DEFER（借鉴 IDEA CheckinHandler.ReturnResult）
    • +
  • • 按 executionOrder 升序执行（默认 100），任一 CANCEL 即阻断提交
    • +
+
+ +
+
+
+

接缝现状（代码事实）

+
+
    +
  • • 五接缝均 Null 实现，经 CommitService 注入（adapter/commit/commit-service.ts）
    • +
  • • CommitPipeline 已挂 ConventionalCommitCheck + NullPreCommitInspector
    • +
+
+ +
+
+
+

Hook 与接缝对应

+
+
    +
  • • A=ICommitMessageProvider · B=IPreCommitInspector · C=IChangelistGrouper · F=IConflictResolver
    • +
  • • D / E 为成功与失败回调接缝，无独立接口
    • +
+
+
+ +
+ + + + diff --git a/docs/assets/architecture/research/ai-agent-seams-pipeline.light.svg b/docs/assets/architecture/research/ai-agent-seams-pipeline.light.svg new file mode 100644 index 0000000..1e719f8 --- /dev/null +++ b/docs/assets/architecture/research/ai-agent-seams-pipeline.light.svg @@ -0,0 +1,700 @@ + + Commit 流水线 · Hook A–F 责任链 + 由 Archify 生成的工作流图。 + + + + + + + + + + + + + + + + + + + + + + + + + 01 / 主提交链（Engine 编排） + + + 02 / Agent 生成支线 + + + + EX / 阻断与拆分回退 + + + 04 / 提交后处理（Hook D–F） + + + + + 收集 + 消息 + + + 提交前闸门 + + + 提交 + 后处理 + + + + + + + + + + + + + + + + + + + + + + 点击 Commit · 收集 staged diff · 主提交链（Engine 编排） › 收集 + 消息 + + + + 点击 Commit + 收集 staged diff + + + + Hook A 消息生成 · ICommitMessageProvider · 主提交链（Engine 编排） › 收集 + 消息 + + + + Hook A 消息生成 + ICommitMessageProvider + + + + 提交消息定稿 · AI 建议经确认 / 编辑 · 主提交链（Engine 编排） › 收集 + 消息 + + + + 提交消息定稿 + AI 建议经确认 / 编辑 + + + + Hook B 提交检查 · IPreCommitInspector 责任链 · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook B 提交检查 + IPreCommitInspector 责任链 + + + + Hook C 分组校验 · IChangelistGrouper · 主提交链（Engine 编排） › 提交前闸门 + + + + Hook C 分组校验 + IChangelistGrouper + + + + git commit · Engine 执行提交 · 主提交链（Engine 编排） › 提交 + 后处理 + + + + git commit + Engine 执行提交 + + + + Agent 流式生成 · Conventional Commits 校验 · Agent 生成支线 › 收集 + 消息 + + + + Agent 流式生成 + Conventional Commits 校验 + + + + 展示问题列表 · 阻断提交 · 返回收集 · 阻断与拆分回退 › 提交前闸门 + + + + 展示问题列表 + 阻断提交 · 返回收集 + + + + 建议拆分 commit · 回 Hook A 重新生成 · 阻断与拆分回退 › 提交前闸门 + + + + 建议拆分 commit + 回 Hook A 重新生成 + + + + Hook F 冲突解决 · IConflictResolver 逐块确认 · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook F 冲突解决 + IConflictResolver 逐块确认 + + + + Hook E 失败处理 · checkinFailed · 提交后处理（Hook D–F） › 提交前闸门 + + + + Hook E 失败处理 + checkinFailed + + + + Hook D 成功后处理 · checkinSuccessful 回调 · 提交后处理（Hook D–F） › 提交 + 后处理 + + + + Hook D 成功后处理 + checkinSuccessful 回调 + + + + + + 可选 Push + + + + + 用户确认 / 编辑 + + + + 启用 + + + + 未启用 / 已手填 + + + + 阻断 + + + + 检查通过 + + + + 单组 / 已确认 + + + + 建议拆分 + + + + 提交 / Push 失败 + + + + 可触发 + + + + 确认后重新提交 + + + + + + 图例 + + + 用户界面 + + + + Agent 逻辑 + + + + 策略 + + + + 云服务 + + + \ No newline at end of file diff --git a/docs/assets/mermaid/README.md b/docs/assets/mermaid/README.md new file mode 100644 index 0000000..4847231 --- /dev/null +++ b/docs/assets/mermaid/README.md @@ -0,0 +1,27 @@ +# Mermaid 源图资产（单一事实源） + +本目录集中管理全项目 Mermaid 源图。**Mermaid 是 archify 专业图的唯一源头**：先抽取并校准 `.mmd`，再由 archify 依其绘制交互式成品（见 [archify 图资产索引](../architecture/README.md)）；文档一律嵌入 archify 成品，禁止内联 mermaid 围栏。 + +## 溯源矩阵（唯一权威映射） + +| Mermaid 源 | 图类型 | 源文档（原行区间） | archify 成品 | 嵌入文档 | 校准记录 | 状态 | +|---|---|---|---|---|---|---| +| [engineering-plan-layers.mmd](architecture/engineering-plan-layers.mmd) | flowchart TB · 架构分层 | [engineering-plan.md](../../architecture/engineering-plan.md) L36-84 | [engineering-plan-layers.html](../architecture/architecture/engineering-plan-layers.html) | engineering-plan.md | 对照 v0.0.18 源码纠偏：Changes TreeView 已移除（v0.0.13 视图迁底部 Panel）、adapter 组件实名、Engine 15 模块、AI 接缝经 CommitService 注入；详见源文档「现状校准」注记 | ✅ 2026-09-11 | +| [ai-agent-seams-pipeline.mmd](research/ai-agent-seams-pipeline.mmd) | flowchart TD · Commit 流水线 hook | [05-ai-agent-seams.md](../../research/05-ai-agent-seams.md) L150-177 | [ai-agent-seams-pipeline.html](../architecture/research/ai-agent-seams-pipeline.html) | 05-ai-agent-seams.md | 修正源图缺陷：`class` 行引用不存在的 Hook3 节点，已移除；Hook A–F 责任链与 `src/agent/` 五接口（全 Null）、`engine/commit/pipeline.ts`（COMMIT/CANCEL/DEFER）核实一致 | ✅ 2026-09-11 | +| [agentic-git-preferences-flow.mmd](features/agentic-git-preferences-flow.mmd) | flowchart LR · 偏好流向 | [agentic-git-preferences.md](../../features/agentic-git-preferences.md) L10-31 | [agentic-git-preferences-flow.html](../architecture/features/agentic-git-preferences-flow.html) | agentic-git-preferences.md | 与 `package.json` `hyperGit.agent.*` 四项配置核实一致（baseBranch 默认空、三项 multilineText） | ✅ 2026-09-11 | +| [claude-code-config-flow.mmd](features/claude-code-config-flow.mmd) | flowchart LR · 配置流向 | [claude-code-config.md](../../features/claude-code-config.md) L17-43 | [claude-code-config-flow.html](../architecture/features/claude-code-config-flow.html) | claude-code-config.md | 与 `adapter/claude-commands.ts`（QuickPick / 缺失确认后 mkdir+写{}）、`engine/agent/claude-path.ts` 纯函数核实一致 | ✅ 2026-09-11 | +| [log-ci-status-dataflow.mmd](features/log-ci-status-dataflow.mmd) | flowchart LR · CI 取数 | [log-ci-status.md](../../features/log-ci-status.md) L9-31 | [log-ci-status-dataflow.html](../architecture/features/log-ci-status-dataflow.html) | log-ci-status.md | 与 `engine/ci/` + `adapter/ci/` + `protocol.ts` 核实一致（防抖 200ms、批量 ≤100 oid、pending 30s TTL、openExternal 主机校验） | ✅ 2026-09-11 | +| [log-commit-detail-panel-layout.mmd](features/log-commit-detail-panel-layout.mmd) | flowchart TB · 面板布局 | [log-commit-detail-panel.md](../../features/log-commit-detail-panel.md) L17-41 | [log-commit-detail-panel-layout.html](../architecture/features/log-commit-detail-panel-layout.html) | log-commit-detail-panel.md | 与 `log-webview.ts` 分栏实现（560px stacked 阈值、18%–75% / 15%–85% 钳制）及 `package.json` view/title 核实一致 | ✅ 2026-09-11 | +| [log-commit-detail-panel-dataflow.mmd](features/log-commit-detail-panel-dataflow.mmd) | flowchart LR · 取数数据流 | 同上 L50-65 | [log-commit-detail-panel-dataflow.html](../architecture/features/log-commit-detail-panel-dataflow.html) | 同上 | 与 `protocol.ts`（commitFiles 按 hash、commitDetail 按 forHash 校验）及 selectRow / requestPanelData / deselectRow 漏斗核实一致 | ✅ 2026-09-11 | +| [multi-root-repo-selection-toolbar.mmd](features/multi-root-repo-selection-toolbar.mmd) | flowchart LR · 切换入口 | [multi-root-repo-selection.md](../../features/multi-root-repo-selection.md) L7-18 | [multi-root-repo-selection-toolbar.html](../architecture/features/multi-root-repo-selection-toolbar.html) | multi-root-repo-selection.md | 修正漂移：按钮实为 `view/title` 原生标题栏项**直调命令** `hyperGit.selectRepository`，原「postMessage log/selectRepo」路径不存在，.mmd 已改 | ✅ 2026-09-11 | +| [multi-root-repo-selection-sequence.mmd](features/multi-root-repo-selection-sequence.mmd) | sequenceDiagram · 切换时序 | 同上 L28-43 | [multi-root-repo-selection-sequence.html](../architecture/features/multi-root-repo-selection-sequence.html) | 同上 | 一致：① `onDidChangeRepository` 先于 ② `onDidChange` fire（git-repository-service.ts 实锤）；rebind 三步细节移入交互版结论卡 | ✅ 2026-09-11 | +| [branch-tree-group-by-prefix-effect.mmd](features/branch-tree-group-by-prefix-effect.mmd) | flowchart LR · 前缀树效果 | [branch-tree-group-by-prefix.md](../../features/branch-tree-group-by-prefix.md) L7-26 | [branch-tree-group-by-prefix-effect.html](../architecture/features/branch-tree-group-by-prefix-effect.html) | branch-tree-group-by-prefix.md | 一致（ref-tree.ts 分组 / compact / 排序）；📁 emoji 改文字、前后分支清单移入交互版结论卡 | ✅ 2026-09-11 | +| [branch-tree-group-by-prefix-dataflow.mmd](features/branch-tree-group-by-prefix-dataflow.mmd) | flowchart LR · 算树数据流 | 同上 L34-43 | [branch-tree-group-by-prefix-dataflow.html](../architecture/features/branch-tree-group-by-prefix-dataflow.html) | 同上 | 一致：`buildRefTree`（engine/ref/ref-tree.ts）、`isRemoteHead` 过滤、`toBranchNodes` 双形态均实锤 | ✅ 2026-09-11 | +| [file-list-group-by-directory-dataflow.mmd](features/file-list-group-by-directory-dataflow.mmd) | flowchart LR · 目录树数据流 | [file-list-group-by-directory.md](../../features/file-list-group-by-directory.md) L9-18 | [file-list-group-by-directory-dataflow.html](../architecture/features/file-list-group-by-directory-dataflow.html) | file-list-group-by-directory.md | 一致：`buildFileTree`（engine/tree/file-tree.ts）、`FileTreeNode` fileIndex 回指、payload 同批下发均实锤 | ✅ 2026-09-11 | + +## 管理规则 + +1. **变更顺序**：先改本目录 `.mmd` → 再同步 archify 成品（HTML + 深浅色双 SVG）→ 更新本矩阵状态。 +2. `.mmd` 文件头注释仅存轻量指针（源文档/成品路径）；映射关系以本矩阵为唯一权威，避免双源。 +3. 文档嵌入统一模板：`` 深浅色自适应 + 交互版 HTML / Mermaid 源图双链接。 +4. 每张成品四件套同基名：`<基名>.mmd` ↔ `<基名>.{html, light.svg, dark.svg}`。 diff --git a/docs/assets/mermaid/architecture/engineering-plan-layers.mmd b/docs/assets/mermaid/architecture/engineering-plan-layers.mmd new file mode 100644 index 0000000..8276327 --- /dev/null +++ b/docs/assets/mermaid/architecture/engineering-plan-layers.mmd @@ -0,0 +1,47 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/architecture/engineering-plan.md L36-84（抽取 2026-09-11；同日对照 v0.0.18 源码校准，校准记录见 README 矩阵） +%% archify 成品: docs/assets/architecture/architecture/engineering-plan-layers.html + +flowchart TB + subgraph UI["视图层 (自绘 · 底部 Panel 容器 hyper-git · v0.0.13 起自活动栏迁入)"] + direction LR + V1["Commit
WebviewView
(changelist + 提交编辑器)"] + V2["Graph (Log)
WebviewView
(SVG 提交图 + 详情面板 + CI 图标)"] + V3["Branches · Stash · Shelf · Worktrees
TreeView"] + V4["Rebase · MergeEditor
Webview 面板 (serializer 恢复)"] + end + subgraph Adapter["Adapter 层 (唯一接触 vscode API)"] + GA["GitRepositoryService
活跃仓库唯一持有者
vscode.git API + execGit 双通道"] + CR["ChangelistRegistry · BranchFavorites
ShelfService · CommitService
(repo 作用域持久化)"] + CMD["命令注册组 ×12
tree/ · editor/ (blame · CodeLens)"] + WV["webview/ 宿主 ×4
shared/protocol.ts 消息契约"] + end + subgraph Engine["Engine 层 (纯逻辑 · 零 vscode 依赖 · Vitest 可单测)"] + M["model · diff · commit · changelist · log
ref · tree · git-state · scm-mapping"] + DF["ci · merge · rebase · blame · worktree · agent"] + end + subgraph Agent["Agent 层 (AI 接缝 · Null 实现 · M5 实装)"] + LLM["ILlmProvider · ICommitMessageProvider
IPreCommitInspector · IChangelistGrouper
IConflictResolver"] + end + VSCodeGIT[("vscode.git 内置扩展
getAPI(1) → Repository")] + GITBIN[("git CLI
child_process · 同一二进制")] + NATIVE[("原生 Source Control 视图
不动 · 共存")] + + UI -->|"postMessage · shared/protocol.ts"| Adapter + Adapter --> Engine + Agent -. 接口注入 CommitService .-> Adapter + Agent -. 读领域模型 / hook 责任链 .-> Engine + Adapter --> VSCodeGIT + Adapter --> GITBIN + 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,CMD,WV ad + class M,DF eg + class LLM ag + class VSCodeGIT,GITBIN,NATIVE ext diff --git a/docs/assets/mermaid/features/agentic-git-preferences-flow.mmd b/docs/assets/mermaid/features/agentic-git-preferences-flow.mmd new file mode 100644 index 0000000..a275010 --- /dev/null +++ b/docs/assets/mermaid/features/agentic-git-preferences-flow.mmd @@ -0,0 +1,24 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/agentic-git-preferences.md L11-30（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/agentic-git-preferences-flow.html + +flowchart LR + subgraph Cfg["hyperGit.agent.* 设置"] + B["baseBranch\n(string, 默认空 = 仓库默认分支)"] + C["commitPreferences\n(multilineText)"] + P["createPrPreferences\n(multilineText)"] + R["reviewPreferences\n(multilineText)"] + end + subgraph Act["Agentic Git 动作(M5 消费)"] + AC["点击 Commit"] + AP["点击 Create PR"] + AR["点击 Review"] + end + C -. "自定义指令" .-> AC + P -. "自定义指令" .-> AP + B -. "PR 基线分支" .-> AP + R -. "自定义指令" .-> AR + style B fill:#1f6feb,color:#fff + style C fill:#238636,color:#fff + style P fill:#8957e5,color:#fff + style R fill:#d29922,color:#000 diff --git a/docs/assets/mermaid/features/branch-tree-group-by-prefix-dataflow.mmd b/docs/assets/mermaid/features/branch-tree-group-by-prefix-dataflow.mmd new file mode 100644 index 0000000..ffcf8a1 --- /dev/null +++ b/docs/assets/mermaid/features/branch-tree-group-by-prefix-dataflow.mmd @@ -0,0 +1,12 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/branch-tree-group-by-prefix.md L35-42（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/branch-tree-group-by-prefix-dataflow.html + +flowchart LR + A["RawRef[]
(displayRefs，已滤 origin/HEAD)"] -->|adapter| B["buildRefTree()
engine/ref/ref-tree"] + B -->|"RefTreeNode[]
(folder / leaf)"| C["BranchesTreeProvider
toBranchNodes()"] + C --> D{"grouping?"} + D -->|on| E["文件夹节点 + 后缀叶子"] + D -->|off| F["平铺（既有排序）"] + style B fill:#1f6feb,color:#fff + style E fill:#238636,color:#fff diff --git a/docs/assets/mermaid/features/branch-tree-group-by-prefix-effect.mmd b/docs/assets/mermaid/features/branch-tree-group-by-prefix-effect.mmd new file mode 100644 index 0000000..8469763 --- /dev/null +++ b/docs/assets/mermaid/features/branch-tree-group-by-prefix-effect.mmd @@ -0,0 +1,22 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/branch-tree-group-by-prefix.md L8-25（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/branch-tree-group-by-prefix-effect.html + +flowchart LR + subgraph FLAT["平铺（切换前）"] + direction TB + a1["bak/2025"] + a2["bak/master-2025-07"] + a3["feature/1.0.0"] + a4["2022 / 2023 / 2024"] + end + subgraph TREE["前缀树（切换后）"] + direction TB + b0["📁 bak"] --> b1["2025"] + b0 --> b2["master-2025-07"] + b3["📁 feature"] --> b4["1.0.0"] + b5["2022 / 2023 / 2024"] + end + FLAT -->|Group by Prefix| TREE + style b0 fill:#8957e5,color:#fff + style b3 fill:#8957e5,color:#fff diff --git a/docs/assets/mermaid/features/claude-code-config-flow.mmd b/docs/assets/mermaid/features/claude-code-config-flow.mmd new file mode 100644 index 0000000..4c232f0 --- /dev/null +++ b/docs/assets/mermaid/features/claude-code-config-flow.mmd @@ -0,0 +1,29 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/claude-code-config.md L18-42（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/claude-code-config-flow.html + +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→ <home>/.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 diff --git a/docs/assets/mermaid/features/file-list-group-by-directory-dataflow.mmd b/docs/assets/mermaid/features/file-list-group-by-directory-dataflow.mmd new file mode 100644 index 0000000..c7d0e31 --- /dev/null +++ b/docs/assets/mermaid/features/file-list-group-by-directory-dataflow.mmd @@ -0,0 +1,12 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/file-list-group-by-directory.md L10-17（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/file-list-group-by-directory-dataflow.html + +flowchart LR + A["扁平文件路径[]
(与 files[] 同序)"] -->|host| B["buildFileTree()
engine/tree/file-tree"] + B -->|"随 payload 下发
FileTreeNode[]"| C["webview 渲染"] + C --> D{"mode"} + D -->|flat| E["平铺：files[] 直接渲染"] + D -->|tree| F["树形：递归 FileTreeNode
叶子取 files[fileIndex]"] + style B fill:#1f6feb,color:#fff + style F fill:#238636,color:#fff diff --git a/docs/assets/mermaid/features/log-ci-status-dataflow.mmd b/docs/assets/mermaid/features/log-ci-status-dataflow.mmd new file mode 100644 index 0000000..902bb18 --- /dev/null +++ b/docs/assets/mermaid/features/log-ci-status-dataflow.mmd @@ -0,0 +1,25 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/log-ci-status.md L10-30（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/log-ci-status-dataflow.html + +flowchart LR + subgraph Git["本地"] + A["git log → GraphRowVM"] --> B["图先渲染（CI 不阻塞）"] + end + subgraph WV["Webview（可见行懒加载）"] + B --> C["滚动收集未知 hash"] + C -->|"防抖 200ms"| D["log/requestCi"] + end + subgraph Host["Extension Host"] + D --> E["解析 origin 远程\nowner/repo/host"] + E --> F["vscode.authentication\n取 token（repo 范围）"] + F --> G["GraphQL 批量 ≤100 oid\nstatusCheckRollup"] + G --> H["按 oid 缓存\n终态永久 / pending 30s"] + end + H -->|"log/ciData"| I["webview 就地重绘图标"] + I --> J["悬停 → Tooltip 明细"] + J -->|"log/openExternal"| K["host 校验主机后\nopenExternal"] + style A fill:#1f6feb,color:#fff + style G fill:#238636,color:#fff + style H fill:#8957e5,color:#fff + style J fill:#d29922,color:#fff diff --git a/docs/assets/mermaid/features/log-commit-detail-panel-dataflow.mmd b/docs/assets/mermaid/features/log-commit-detail-panel-dataflow.mmd new file mode 100644 index 0000000..779d454 --- /dev/null +++ b/docs/assets/mermaid/features/log-commit-detail-panel-dataflow.mmd @@ -0,0 +1,18 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/log-commit-detail-panel.md L51-64（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/log-commit-detail-panel-dataflow.html + +flowchart LR + A["点击/方向键选中行"] --> B["selectRow → log/selectCommit"] + B --> C["host 并行取数
sendCommitFiles + showCommitDetail"] + C -->|"log/commitFiles{hash}"| D["renderDetails → #details"] + C -->|"log/commitDetail{forHash, vm}"| E["renderCommitMeta → #commit-meta"] + B --> F["Loading 占位（两区即时反馈）"] + G["× / Esc → deselectRow"] --> H["面板隐藏 + 选中清除 + persist"] + I["log/graphData（刷新/切库/重载）"] -->|"选中消失"| G + I -->|"选中在 + 未装载"| B + style A fill:#1f6feb,color:#fff + style C fill:#8250df,color:#fff + style D fill:#d29922,color:#fff + style E fill:#238636,color:#fff + style G fill:#cf222e,color:#fff diff --git a/docs/assets/mermaid/features/log-commit-detail-panel-layout.mmd b/docs/assets/mermaid/features/log-commit-detail-panel-layout.mmd new file mode 100644 index 0000000..53f2a35 --- /dev/null +++ b/docs/assets/mermaid/features/log-commit-detail-panel-layout.mmd @@ -0,0 +1,27 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/log-commit-detail-panel.md L18-40（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/log-commit-detail-panel-layout.html + +flowchart TB + subgraph shell["VS Code 标题栏（view/title）"] + H["Graph + description(仓库路径)
… [layers Scope▾] [list-tree/flat] [refresh] [sign-in*] [repo*] …"] + end + subgraph main["#main（≥560px 横向 flex / <560px .stacked 纵向）"] + VP["#viewport
提交图（flex:1，虚拟滚动）"] + G1["#gutter-main
拖拽 ⇄ 面板宽/高（18%–75%，
横向面板≥200px 且图≥280px）"] + subgraph panel["#commit-panel（flex-basis 拖拽钳制）"] + D["#details（独立滚动）
Changed Files + ×"] + G2["#gutter-meta
拖拽 ⇄ 上/下半区高（15%–85%）"] + M["#commit-meta（独立滚动）
作者/引用分组/消息/统计/SHA"] + end + end + H --- main + VP --- G1 --- panel + D --- G2 --- M + style H fill:#6e7681,color:#fff + style VP fill:#1f6feb,color:#fff + style G1 fill:#8250df,color:#fff + style G2 fill:#8250df,color:#fff + style panel fill:#21262d,stroke:#d29922,color:#fff + style D fill:#d29922,color:#fff + style M fill:#238636,color:#fff diff --git a/docs/assets/mermaid/features/multi-root-repo-selection-sequence.mmd b/docs/assets/mermaid/features/multi-root-repo-selection-sequence.mmd new file mode 100644 index 0000000..49b6ae8 --- /dev/null +++ b/docs/assets/mermaid/features/multi-root-repo-selection-sequence.mmd @@ -0,0 +1,18 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/multi-root-repo-selection.md L29-42（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/multi-root-repo-selection-sequence.html + +sequenceDiagram + participant U as 用户 + participant S as GitRepositoryService + participant R as rebind 订阅
(extension.ts) + participant V as 视图刷新链 + + U->>S: selectRepository(rootB) + S->>S: applyRepository(repoB) + S-->>R: ① onDidChangeRepository.fire（同步） + R->>R: registry/favorites/branchesTree.setRepoRoot + R->>R: branchesGrouping context key 同步 + R->>R: blame 注解清理 · Graph filter 清空 + S-->>V: ② onDidChange.fire（其后） + V->>V: refreshAll（150ms 防抖）重取数据 diff --git a/docs/assets/mermaid/features/multi-root-repo-selection-toolbar.mmd b/docs/assets/mermaid/features/multi-root-repo-selection-toolbar.mmd new file mode 100644 index 0000000..d8a4be1 --- /dev/null +++ b/docs/assets/mermaid/features/multi-root-repo-selection-toolbar.mmd @@ -0,0 +1,14 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/features/multi-root-repo-selection.md L8-17（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/features/multi-root-repo-selection-toolbar.html + +flowchart LR + subgraph TOOLBAR["Graph 工具栏"] + A["All · Current · Checkpoints"] --- B["repo-a ▾
(可点击按钮)"] + end + B -->|click → 直调命令 hyperGit.selectRepository| C["QuickPick
$(repo) repo-a /repo-a ✓
$(repo) repo-b /workspace/repo-b"] + C -->|选中| D["service.selectRepository(root)"] + D --> E["全局活跃仓库切换
七个视图 + 持久化状态级联跟随"] + style B fill:#1f6feb,color:#fff + style D fill:#238636,color:#fff + style E fill:#8957e5,color:#fff diff --git a/docs/assets/mermaid/research/ai-agent-seams-pipeline.mmd b/docs/assets/mermaid/research/ai-agent-seams-pipeline.mmd new file mode 100644 index 0000000..34f48a3 --- /dev/null +++ b/docs/assets/mermaid/research/ai-agent-seams-pipeline.mmd @@ -0,0 +1,31 @@ +%% Mermaid 源图（单一事实源）· 溯源矩阵: docs/assets/mermaid/README.md +%% 源文档: docs/research/05-ai-agent-seams.md L151-176（抽取 2026-09-11） +%% archify 成品: docs/assets/architecture/research/ai-agent-seams-pipeline.html +%% 校准 2026-09-11: 移除 class 行中不存在的 Hook3 节点引用；Hook A-F 语义与 src/agent/ 五接缝及 engine/commit/pipeline.ts 责任链核实一致 + +flowchart TD + Start([用户点击 Commit]) --> Gather[Engine: 收集 staged diff
+ 当前 changelist 上下文] + Gather --> Hook1{"【Hook A: 提交信息生成】
ICommitMessageProvider
默认 Null, 可选 LM"} + Hook1 -- 未启用AI/用户已手填 --> Msg[提交消息定稿] + Hook1 -- 启用 --> GenMsg[Agent: 流式生成建议消息
+ Conventional Commits 校验] + GenMsg --> MsgConfirm{用户确认/编辑消息} + MsgConfirm --> Msg + Msg --> Hook2{"【Hook B: 提交前检查】
IPreCommitInspector 链
= IDEA beforeCheckin"} + Hook2 -- 检查通过 --> Group{"【Hook C: 分组校验】
IChangelistGrouper
可选: 提示拆分多 commit"} + Hook2 -- 阻断 --> Block[展示问题列表
阻断提交, 返回 Gather] + Group -- 单组/用户确认 --> Commit[Engine: git commit] + Group -- 建议拆分 --> Split[提示用户拆分
回 Hook A] + Commit --> Hook4{"【Hook D: 成功后处理】
= IDEA checkinSuccessful"} + Hook4 --> Push[可选: Commit and Push] + Push --> Hook5{"【Hook E: 失败处理】
= IDEA checkinFailed
可触发 IConflictResolver"} + Hook5 -. 冲突 .-> Resolve["【Hook F: 冲突解决】
IConflictResolver
用户逐块确认"] + Resolve --> Commit + + classDef hook fill:#ffe082,stroke:#f57f17,stroke-width:2px,color:#000 + classDef engine fill:#b3e5fc,stroke:#0277bd,stroke-width:2px,color:#000 + classDef agent fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000 + classDef decision fill:#fff9c4,stroke:#f57f17,color:#000 + class Hook1,Hook2,Group,Hook4,Hook5,Resolve hook + class Gather,Commit,Push engine + class GenMsg,Split agent + class MsgConfirm,Block decision diff --git a/docs/features/agentic-git-preferences.md b/docs/features/agentic-git-preferences.md index 55417a3..333bd14 100644 --- a/docs/features/agentic-git-preferences.md +++ b/docs/features/agentic-git-preferences.md @@ -7,28 +7,12 @@ 采用**原生 VS Code 设置**承载（与仓库既有配置一致，零新增 Webview / 命令 / TS）。三项偏好用 `editPresentation: "multilineText"` 渲染为多行文本域，内置默认模板内联于 `package.json` 的 `default`（`.vscodeignore` 排除除 `media/` 外一切、且 VS Code 无「默认取自文件」机制，故默认值必须内联方能在设置界面直接呈现模板）。 -```mermaid -flowchart LR - subgraph Cfg["hyperGit.agent.* 设置"] - B["baseBranch\n(string, 默认空 = 仓库默认分支)"] - C["commitPreferences\n(multilineText)"] - P["createPrPreferences\n(multilineText)"] - R["reviewPreferences\n(multilineText)"] - end - subgraph Act["Agentic Git 动作(M5 消费)"] - AC["点击 Commit"] - AP["点击 Create PR"] - AR["点击 Review"] - end - C -. "自定义指令" .-> AC - P -. "自定义指令" .-> AP - B -. "PR 基线分支" .-> AP - R -. "自定义指令" .-> AR - style B fill:#1f6feb,color:#fff - style C fill:#238636,color:#fff - style P fill:#8957e5,color:#fff - style R fill:#d29922,color:#000 -``` + + + hyperGit.agent.* 设置到 Agentic Git 动作的映射 + + +> [交互版](../assets/architecture/features/agentic-git-preferences-flow.html) · [Mermaid 源图](../assets/mermaid/features/agentic-git-preferences-flow.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)） ## 配置 diff --git a/docs/features/branch-tree-group-by-prefix.md b/docs/features/branch-tree-group-by-prefix.md index 845b06c..c039c34 100644 --- a/docs/features/branch-tree-group-by-prefix.md +++ b/docs/features/branch-tree-group-by-prefix.md @@ -4,26 +4,12 @@ ## 效果：扁平 → 前缀树 -```mermaid -flowchart LR - subgraph FLAT["平铺（切换前）"] - direction TB - a1["bak/2025"] - a2["bak/master-2025-07"] - a3["feature/1.0.0"] - a4["2022 / 2023 / 2024"] - end - subgraph TREE["前缀树（切换后）"] - direction TB - b0["📁 bak"] --> b1["2025"] - b0 --> b2["master-2025-07"] - b3["📁 feature"] --> b4["1.0.0"] - b5["2022 / 2023 / 2024"] - end - FLAT -->|Group by Prefix| TREE - style b0 fill:#8957e5,color:#fff - style b3 fill:#8957e5,color:#fff -``` + + + 分支前缀分组 · 平铺变前缀树 + + +> [交互版](../assets/architecture/features/branch-tree-group-by-prefix-effect.html) · [Mermaid 源图](../assets/mermaid/features/branch-tree-group-by-prefix-effect.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)） 远程段整体收拢为单个 `origin` 文件夹，内部再嵌 `feature`：`origin/feature/1.0.0` → `origin` → `feature` → `1.0.0`。 @@ -31,16 +17,12 @@ flowchart LR 分支前缀分组与「变更文件目录树」（见 [file-list-group-by-directory](./file-list-group-by-directory.md)）是同构问题，故沿用其成熟范式：纯逻辑引擎构树、上层仅渲染。 -```mermaid -flowchart LR - A["RawRef[]
(displayRefs，已滤 origin/HEAD)"] -->|adapter| B["buildRefTree()
engine/ref/ref-tree"] - B -->|"RefTreeNode[]
(folder / leaf)"| C["BranchesTreeProvider
toBranchNodes()"] - C --> D{"grouping?"} - D -->|on| E["文件夹节点 + 后缀叶子"] - D -->|off| F["平铺（既有排序）"] - style B fill:#1f6feb,color:#fff - style E fill:#238636,color:#fff -``` + + + 分支前缀分组 · 算树数据流 + + +> [交互版](../assets/architecture/features/branch-tree-group-by-prefix-dataflow.html) · [Mermaid 源图](../assets/mermaid/features/branch-tree-group-by-prefix-dataflow.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)） - **纯逻辑 `buildRefTree`**（[`engine/ref/ref-tree.ts`](../../src/engine/ref/ref-tree.ts)，零 vscode 依赖、Vitest 覆盖）：按 `shortName` 的 `/` 分段建 trie；叶子携带完整 `RawRef`（短名不丢，命令仍以 `ref.shortName` 定位）、`label` 取末段后缀。**分支感知排序**——当前 HEAD（第 0 档）→ 收藏（第 1 档）→ 同档内**文件夹在前**、名称数字感知升序、稳定；**compact 折叠**单目录子链（如 `a/b/c` → `a/b`，遇含叶子或多子目录即停，对齐 VS Code `explorer.compactFolders`）。 - **含 `/` 的远程名无需特判**：fork 场景 remote 名可含 `/`（如 `myorg/repo`），compact 折叠会把 `myorg/repo` 单目录子链渲染为单个文件夹，视觉上与「remote 为一层」等价；删除等**正确性敏感**逻辑仍走 [`resolveRemoteBranch`](../../src/engine/ref/remote-ref.ts) 的最长前缀匹配，两者正交不耦合。 diff --git a/docs/features/claude-code-config.md b/docs/features/claude-code-config.md index d5ea4e3..b66d931 100644 --- a/docs/features/claude-code-config.md +++ b/docs/features/claude-code-config.md @@ -14,33 +14,12 @@ 采用**原生 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→ <home>/.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 -``` + + + Claude Code 配置的设置与命令流向 + + +> [交互版](../assets/architecture/features/claude-code-config-flow.html) · [Mermaid 源图](../assets/mermaid/features/claude-code-config-flow.mmd)（图资产溯源见 [图资产索引](../assets/mermaid/README.md)） ## 配置 diff --git a/docs/features/file-list-group-by-directory.md b/docs/features/file-list-group-by-directory.md index 733f215..3de8cd2 100644 --- a/docs/features/file-list-group-by-directory.md +++ b/docs/features/file-list-group-by-directory.md @@ -6,16 +6,12 @@ Webview 使用内联 `