Merge pull request #84 from ThreeFish-AI/feature/1.x.x

Feature/1.x.x

Author: ThreeFish-AI

CHANGELOG.md

@@ -6,6 +6,13 @@
 
 ## [Unreleased]
 
+## [0.0.14] - 2026-07-06 — 修复 GRAPH 视图提交记录时间倒序
+
+修复 GRAPH 视图「All」范围下提交记录未按时间倒序排列的问题——取数参数由 `--topo-order` 改为 `--author-date-order`，令跨分支提交按作者日期正确交错、消除「日期回跳」。纯取数排序修复，不改数据协议、布局算法与任何视图交互。完整用户视角叙述见 [Release Note v0.0.14](./docs/releases/v0.0.14.md)。
+
+### Fixed
+- **GRAPH 视图提交记录日期回跳**：取数参数 `--topo-order` → `--author-date-order`。`--topo-order` 会把不同分支的提交「成块」输出，导致从较旧提交分叉但日期较新的旁支提交被整块挤到列表末尾，出现「前几行日期递减、中途回跳到最新日期」的反直觉乱序；`--author-date-order` 同样保证 lane 算法依赖的「子在父之上」不变量（`graph-layout` 仅依赖该拓扑约束、不依赖 topo-order 的「分支成块」特性），且按作者日期倒序跨支正确交错，并与视图日期列（`row.authorDate`）对齐（单一事实源）。同步更新 8 处 `topo-order` 注释澄清不变量真实要求、`log-query.test.ts` 断言与「不含 `--topo-order`」回归护栏。详见 [issue #14](./docs/.agents/issue.md)。(#82)
+
 ## [0.0.13] - 2026-07-05 — 视图容器由活动栏迁移至底部面板（Terminal 之后）
 
 将 Hyper Git 视图容器从活动栏（Activity Bar / Primary Side Bar）迁移至底部面板（Panel），默认排在 Terminal 页签之后，提供与官方 Terminal / Output / Problems 一致的底部停靠体验。完整用户视角叙述见 [Release Note v0.0.13](./docs/releases/v0.0.13.md)。

README.md

@@ -20,6 +20,10 @@
 
 ## Features
 
+<p align="center">
+  <img src="media/overview.png" alt="Overview"/>
+</p>
+
 - **Multi-Changelist Changes view**: group edits into named lists, mark one as the active commit target, create / rename / delete / move lists, persisted in `workspaceState` (restored across restarts); status colors reuse the `gitDecoration.*` theme tokens.
 - **Commit panel**: a hand-built commit view with real-time Conventional Commits validation, Amend / Sign-off / skip hooks, and Commit / Commit & Push; the checkbox selection is the authoritative commit scope, and recent messages are reusable.
 - **Log commit graph (hand-rendered DAG)**: colored swimlanes, branch/merge edges, HEAD/branch/tag badges, virtualized incremental loading; 7 composable filters (author / path / grep / regex / merge-mode / date / clear); per-commit actions (Reset, new branch·tag, Cherry-Pick, Revert, list containing branches).
@@ -61,12 +65,12 @@ See the [Engineering Plan](./docs/architecture/engineering-plan.md), the [Implem
 
 | Milestone | Theme                                                        | Status |
 | --------- | ------------------------------------------------------------ | ------ |
-| M0        | Scaffolding + CI                                             | ✅     |
-| M1        | Git adapter + Changes TreeView (multi-changelist)            | ✅     |
-| M2        | Commit panel (template / Amend / CC validation / hook chain) | ✅     |
-| M3        | Log (Graph DAG) + Branches + Diff/Blame                      | ✅     |
-| M4        | Stash / Shelf / line-level commits / Worktrees               | ✅     |
-| M5        | AI agent (seams reserved, implementation pending)            | ⏳     |
+| M0        | Scaffolding + CI                                             | ✅      |
+| M1        | Git adapter + Changes TreeView (multi-changelist)            | ✅      |
+| M2        | Commit panel (template / Amend / CC validation / hook chain) | ✅      |
+| M3        | Log (Graph DAG) + Branches + Diff/Blame                      | ✅      |
+| M4        | Stash / Shelf / line-level commits / Worktrees               | ✅      |
+| M5        | AI agent (seams reserved, implementation pending)            | ⏳      |
 
 ## Development
 

docs/.agents/issue.md

@@ -114,4 +114,12 @@
   4. **dock 迁移属用户可见布局变更**：VS Code 会记忆旧 dock 位置，老用户升级后需「View: Reset View Locations」或右键容器页签「Reset Location」才采用新默认（与 #12 同款平台行为，实机验证须用干净 profile）。
 - **同类问题影响**：所有在 activitybar/panel 间迁移自定义视图容器的扩展；凡依赖容器图标 badge「始终可见」语义的扩展；以及把「dock 迁移」误当作纯内部重构而忽视 badge 可见性回退的实现。
 
+## #14 GRAPH 视图提交记录日期回跳（`--topo-order` 旁支成块 vs `--author-date-order`）
+
+- **表因**：用户截图反馈 GRAPH 视图（All 范围）提交记录**未按时间倒序**——前 10 行作者日期由 `2026-07-05` 正确递减到 `2026-05-25`，但第 11 行起日期**回跳**回 `2026-07-05`（一批远端旁支提交：`fix-github-security` / `msgpack` / `pydantic-settings` / `ts-deepmerge` / `perceive daegu-v2` / `docs wiki` ×2 / `PDF→MD`），理应排在最顶部的新提交却落在列表底部。
+- **根因**：`engine/log/log-query.ts` 的 `buildLogArgs` 取数首参为 `--topo-order`，且管道各层（engine 解析 / adapter 装配 / webview 渲染）**均无任何二次排序**——git 输出序即最终显示序。`--topo-order` 语义为「子在父之上」**且额外约束「不同分支线历史不相邻混排」**：它把一条分支的提交整块输出后再切下一条。当仓库存在从较旧提交分叉、但提交日期较新的旁支（本案 `--branches --tags --remotes` 命中的远端跟踪分支），这些旁支提交会被整块挤到列表末尾，造成日期列回跳。`--topo-order` **不是**按日期排序，分支成块是其设计特性而非 bug，但对「按时间倒序浏览」的人类预期是错的。实证（本仓 `git log`，前 18 条作者日期）：`--topo-order` 序列在 `22:07:16`（旁支提交）处错位到第 15 位（晚于 `20:32:35`）；`--author-date-order` 同位置归位到第 13 位，整体严格单调递减。
+- **处理方式**：`log-query.ts:39` 单行 `'--topo-order'` → `'--author-date-order'`。选 `--author-date-order` 而非 `--date-order` 的依据——**单一事实源**：视图日期列渲染的是 `row.authorDate`（`log-webview.ts:771` `fmtDate(row.authorDate)`），排序键须与显示键对齐，否则 rebase / cherry-pick 提交（committer date ≠ author date）仍会与显示列错位。lane 算法安全性：通读 `graph-layout.ts:32-145`，算法仅依赖「处理 commit 时窗口内其全部子已处理」这一不变量（在父 hash 上开 / 闭 lane 槽），**不依赖** topo-order 的「分支成块」特性；`git log --author-date-order` 契约原文 "Show no parents before all of their children are shown" 同样保证「子在父之上」，故 lane 不会断裂。同步更新 8 处 `topo-order` 注释（`log-query.ts` / `graph-types.ts` / `graph-layout.ts` / `log-line.ts` / `log-webview.ts`）澄清「不变量真实要求 = 子在父之上」，更新 `log-query.test.ts` 断言并补「不含 `--topo-order`」回归护栏；顺带加固既有的 `--author` 前缀测试（`startsWith('--author')` → `startsWith('--author=')`），消除与本 flag 的前缀碰撞隐患。
+- **后续防范**：① 自计算 DAG lane 布局的算法只需「子在父之上」拓扑约束，**不要求**「分支成块」——`--topo-order` / `--date-order` / `--author-date-order` 三者均满足前者，区别仅在无父子约束提交间的次序；选 flag 时应据「人类预期次序」而非默认 topo。② **排序键须与显示键对齐**：UI 显示哪一列（author date / committer date），git 取数就应用对应的 `--author-date-order` / `--date-order`，否则会出现「列内日期看似乱序」的二次 bug。③ 排查「显示乱序」类问题先确认管道**是否存在二次排序**——本案各层均无，根因在 git 取数参数层；若上层曾 re-sort，还须检查是否破坏拓扑约束。④ 测试断言里用 `--author` / `--grep` 这类**短前缀**判「无 flag」时，须警惕与同前缀的排序 / 过滤 flag（`--author-date-order`、`--author-date`）碰撞，宜用带 `=` 的精确前缀（`--author=`）。⑤ 与 #9 同源教训：`log-query.ts` 的 git 取数参数是 GRAPH 视图多项语义（范围 / 排序）的单一事实源，改 git 参数 + 注释 + 测试断言三件套应一并完成。
+- **同类问题影响**：所有用 `git log --topo-order` 取数、自计算或直接渲染提交图、且 UI 暴露「按时间浏览」预期的 Git GUI；凡把「lane 算法要求」误读为「必须 `--topo-order`」（实为「子在父之上」即可）的实现均会复现日期回跳；以及排序键与显示日期列不一致（author date vs committer date）导致的「列内看似乱序」类二次 bug。
+
 

docs/.agents/knowledge-map.md

@@ -25,7 +25,7 @@
 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。
 - [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。
 - [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。
-- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.13](../releases/v0.0.13.md)）。
+- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.14](../releases/v0.0.14.md)）。
 
 ## 架构分层（src/）
 > 依赖方向单向：`UI → Adapter → Engine`；`Agent` 以接口注入 `Engine`/`CommitPipeline`，不反向依赖 UI。

docs/README.md

@@ -11,7 +11,7 @@
 - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。
 
 ## 发布说明
-- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.13 视图容器由活动栏迁移至底部 Panel（Terminal 之后）](./releases/v0.0.13.md)。
+- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.14 修复 GRAPH 视图提交记录时间倒序](./releases/v0.0.14.md)。
 
 ## 调研报告（循证依据）
 - [02 · VS Code SCM API 与 vscode.git 集成路径](./research/02-vscode-scm-integration.md) — 路径 B 决策依据、SCM 稳定/proposed API 边界、changelist 模型映射。

docs/releases/README.md

@@ -8,6 +8,7 @@
 
 | 版本 | 说明 | 日期 |
 |---|---|---|
+| [v0.0.14](./v0.0.14.md) | 修复 GRAPH 视图提交记录时间倒序（`--topo-order` → `--author-date-order`） | 2026-07-06 |
 | [v0.0.13](./v0.0.13.md) | 视图容器由活动栏迁移至底部 Panel（Terminal 之后） | 2026-07-05 |
 | [v0.0.12](./v0.0.12.md) | 提交详情光标跟随悬浮卡 · Tooltip 交互修复 · 侧边栏布局优化 · 依赖升级基线（TS6 / vitest4 / vite8） | 2026-07-04 |
 | [v0.0.11](./v0.0.11.md) | 首个正式版（承载 0.0.10 内容）· Graph 视图对齐官方 · 发布渠道收敛 Marketplace | 2026-07-04 |

docs/releases/v0.0.14.md

@@ -0,0 +1,53 @@
+# Hyper Git - Agentic Git v0.0.14 — 修复 GRAPH 视图提交记录时间倒序
+
+> 修复 **GRAPH 视图**「All」范围下提交记录**未按时间倒序**排列的问题：此前列表前段日期正常递减，中段却会「回跳」到最新日期——较新的旁支提交被错误地挤到列表底部。本版令提交严格按**作者日期倒序**呈现，跨分支提交正确交错。
+
+> 本版为纯取数排序修复，未改动任何 `viewType`、消息协议、`webview.setState` 形状、布局算法与配置项，旧状态无需迁移。
+
+---
+
+## ✨ 亮点速览
+
+- **提交记录严格时间倒序**：GRAPH 视图取数参数由 `--topo-order` 改为 `--author-date-order`，从较旧提交分叉、但日期较新的旁支提交不再被「成块」挤到列表末尾，日期列自上而下单调递减、不再回跳。
+- **泳道不受影响**：DAG 彩色泳道（lane）布局所依赖的「子提交在父提交之上」拓扑不变量在新排序下依然严格成立，连线与分叉渲染保持正确，无断裂、无变形。
+- **零协议/交互回归**：仅一行取数参数变更，数据协议、布局算法、引用胶囊、悬浮卡、范围切换（All / Current / Checkpoints）、增量加载与过滤（author / grep / path）全部沿用。
+
+---
+
+## 🧩 问题与修复
+
+### 现象
+
+在「All」范围下，提交记录本应严格按时间倒序（最新在顶部）。实际却出现：列表前段（如 `2026-07-05` → `2026-05-25`）日期正常递减，但中段之后日期**回跳**回最新的 `2026-07-05`——一批远端旁支提交（如安全修复、依赖升级等分支）被整块排到了列表底部，与「按时间浏览历史」的直觉严重不符。
+
+### 根因
+
+GRAPH 视图的提交顺序此前完全由 `git log` 的 `--topo-order`（拓扑序）参数决定，管道各层均无二次排序。`--topo-order` 在保证「子在父之上」的同时，会额外把**不同分支的历史「成块」输出**——一条分支的提交整块列完，再切到下一条。当仓库存在从较旧提交分叉、但提交日期较新的旁支时，这些提交便被整块下放到列表末尾，形成「日期回跳」。这是 `--topo-order` 的设计特性，并非按日期排序。
+
+### 修复
+
+改用 `--author-date-order`：它同样保证 DAG 泳道算法依赖的「子在父之上」拓扑不变量，但在此约束下**按作者日期倒序**排列提交，使跨分支提交正确交错。之所以选「作者日期」而非「提交者日期」，是为了与 GRAPH 视图**日期列实际显示的时间**保持一致——排序键与显示键对齐，避免出现「列内日期看似仍乱序」的二次困惑。
+
+---
+
+## ⚙️ 升级与兼容
+
+- **无破坏性变更**：仅 GRAPH 视图 `git log` 取数排序参数变更，未改动 `viewType`、消息协议、`setState` 形状或配置项，从 v0.0.13 升级无需任何迁移。
+- **即时生效**：升级后打开 GRAPH 视图即为新排序，无需重置布局或清理状态。
+
+---
+
+## 📦 安装
+
+- **VS Code Marketplace**：搜索 `Hyper Git - Agentic Git` 直接安装或更新。
+- **手动**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.14) 下载 `hyper-git-agentic-git-0.0.14.vsix` → 命令面板 `Extensions: Install from VSIX`（Cursor / Windsurf / VSCodium 等用户可经此方式安装）。
+
+**系统要求**：VS Code ≥ 1.85.0，且启用内置 Git 扩展（`vscode.git`，默认随附）。仅支持本地 git 仓库，不支持虚拟 / Web 工作区。
+
+---
+
+## 💬 反馈
+
+欢迎在 [GitHub Issues](https://github.com/ThreeFish-AI/hyper-git/issues) 反馈问题与建议。完整工程视角变更记录见 [CHANGELOG](../../CHANGELOG.md)；本次修复的表因、根因与防范沉淀见 [issue #14](../.agents/issue.md)。
+
+许可证：[MIT](https://github.com/ThreeFish-AI/hyper-git/blob/master/LICENSE)。

media/overview.png

@@ -7,7 +7,7 @@
 		"theme": "dark"
 	},
 	"description": "Hyper Git brings IntelliJ IDEA's powerful Git & Commit modules to VS Code, enhanced with AI-powered autonomous agents for intelligent repository management. Experience Git in a higher dimension.",
-	"version": "0.0.13",
+	"version": "0.0.14",
 	"publisher": "ThreeFish-AI",
 	"license": "MIT",
 	"preview": true,

package.json

@@ -85,7 +85,7 @@ interface GraphPage {
 /**
  * Log 视图（WebviewView）：可视化提交图（DAG）。
  *
- * 自计算 lane 布局（engine/log/graph-layout）→ 渲染彩色泳道；host 侧单次 `git log --topo-order`
+ * 自计算 lane 布局（engine/log/graph-layout）→ 渲染彩色泳道；host 侧单次 `git log --author-date-order`
  * 取数 + `for-each-ref` 取引用标签；webview 端虚拟化 SVG 行 + 文本列。保留全部既有交互：
  * 7 个过滤命令（经 {@link LogFilterControl}）、9 个 per-commit 操作（右键 → host 重调用）、
  * 选中提交查看变更文件、All/Current 范围切换、滚动增量加载、实时刷新。