diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 04f4c02..be27a44 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -5,6 +5,11 @@ updates: schedule: interval: weekly open-pull-requests-limit: 5 + ignore: + # @types/vscode 须与 package.json 的 engines.vscode 手动联动（vsce package 强制要求 + # @types/vscode 的 major.minor ≤ engines.vscode）。Dependabot 单方面 bump 会破坏该约束 + # 并令 CI 的 vsce package 失败，故忽略其升级——抬高最低 VS Code 版本属产品决策，需人工执行。 + - dependency-name: '@types/vscode' - package-ecosystem: github-actions directory: / schedule: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 843fdeb..ac723d2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,7 +67,13 @@ jobs: node-version: 22 cache: 'pnpm' - run: pnpm install --frozen-lockfile - - run: pnpm dlx @vscode/vsce package --no-yarn + # rc tag 以 --pre-release 打包：VS Code 要求「预发布 VSIX」在打包时即标记， + # 否则 publish job 的 `vsce publish --pre-release` 会报「未以 pre-release 打包」而失败。 + # 与 publish 步骤同款 PRE_FLAG 判定，保证同一枚 VSIX 贯穿 GitHub Release 与 Marketplace。 + - name: 打包 vsix（rc tag 自动带 --pre-release） + run: | + PRE_FLAG=$([[ "${GITHUB_REF_NAME}" == *rc* ]] && echo "--pre-release" || echo "") + pnpm dlx @vscode/vsce package --no-yarn $PRE_FLAG - uses: actions/upload-artifact@v7 with: name: vsix @@ -84,7 +90,7 @@ jobs: contents: write steps: # 检出仓库：使 body_path 指向的 Release Note 文件可见 - - uses: actions/checkout@v4 + - uses: actions/checkout@v7 - uses: actions/download-artifact@v8 with: name: vsix @@ -97,7 +103,7 @@ jobs: body_path: docs/releases/${{ github.ref_name }}.md fail_on_unmatched_files: true - # 发布：仅 tag 触发；OpenVSX 默认发布，VS Code Marketplace 由 ENABLE_MARKETPLACE_PUBLISH 变量门控（默认关闭）；生产环境审批门 + # 发布：仅 tag 触发；发布到 VS Code Marketplace，由 ENABLE_MARKETPLACE_PUBLISH 变量门控；生产环境审批门 publish: name: Publish needs: package @@ -115,9 +121,8 @@ jobs: - uses: actions/download-artifact@v8 with: name: vsix - # VS Code Marketplace 发布：默认关闭（未配置 VSCE_PAT）。 - # 配好 VSCE_PAT 后，在仓库 Settings → Secrets and variables → Actions → Variables - # 新增 ENABLE_MARKETPLACE_PUBLISH=true 即恢复，无需改代码或发 PR。 + # VS Code Marketplace 发布：由仓库变量 ENABLE_MARKETPLACE_PUBLISH 门控（=true 时发布）。 + # 需配置 VSCE_PAT（Azure DevOps PAT，scope: Marketplace → Manage）；rc tag 自动以 --pre-release 发预发布通道。 - name: 发布到 VS Code Marketplace if: ${{ vars.ENABLE_MARKETPLACE_PUBLISH == 'true' }} run: | @@ -125,12 +130,3 @@ jobs: pnpm dlx @vscode/vsce publish --packagePath *.vsix $PRE_FLAG env: VSCE_PAT: ${{ secrets.VSCE_PAT }} - # OpenVSX 不支持覆盖已存在版本：若该版本号已发布则此步报错。 - # 以 continue-on-error 隔离——不阻断 GitHub Release 产出，亦不让首发 workflow 标红。 - - name: 发布到 OpenVSX（覆盖 Cursor / Windsurf 等 AI IDE） - continue-on-error: true - run: | - PRE_FLAG=$([[ "${GITHUB_REF_NAME}" == *rc* ]] && echo "--pre-release" || echo "") - pnpm dlx ovsx publish *.vsix $PRE_FLAG - env: - OVSX_PAT: ${{ secrets.OVSX_PAT }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 2bc88f3..4917d62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,10 +4,77 @@ > 面向用户的发布说明（含完整特性叙述与安装指引）见 [`docs/releases/`](./docs/releases/README.md)。 -## [0.0.7] - 未发布 +## [Unreleased] + +### Changed +- **侧边栏视图默认布局优化**：Stash / Shelf 两个次要视图默认折叠（`visibility: "collapsed"`，仅占标题栏、点击即展开），Worktrees 保持默认展开、仅以 `initialSize` 收窄；并为各视图设置初始高度权重（`initialSize`：Commit / Graph 较高、Branches 居中、次要视图紧凑），缓解视图挤占空间的体感。注：VS Code 侧边栏视图存在约 142px 硬性最小展开高度（核心硬编码、官方特性请求 [microsoft/vscode#123715](https://github.com/microsoft/vscode/issues/123715) 已 not planned），**无法经扩展解除**；上述默认仅对**新安装**或执行「View: Reset View Locations」后的布局生效。详见 [issue #12](./docs/.agents/issue.md)。 + +## [0.0.11] - 2026-07-04 — 首个正式版（承载 0.0.10 内容）· 发布渠道收敛 Marketplace + +首个 VS Code Marketplace **正式发布**版本，承载 0.0.10 预发布通道（rc.1 / rc.2）已验证的全部内容——提交图更名 **Graph** 并对齐官方 Source Control GRAPH、悬浮浮层 iframe 裁剪修复、未提交角标承载迁移、README 真实性校准与中英双语；并将发布渠道收敛为 **VS Code Marketplace 单市场**。`0.0.10` 版位已被预发布通道占用，正式版按官方规则顺延至 `0.0.11`。完整用户视角叙述见 [Release Note v0.0.11](./docs/releases/v0.0.11.md)。 + +### Changed +- **发布渠道收敛为 VS Code Marketplace 单市场**：移除 CI `publish` job 的 OpenVSX 发布步骤及对 `OVSX_PAT` 的依赖，README 双语安装渠道同步移除 OpenVSX；发布流水线现为 **GitHub Release + VS Code Marketplace**（由 `ENABLE_MARKETPLACE_PUBLISH` 变量门控，`rc` 标签走预发布通道）。 +- **Log 视图更名为 Graph 并对齐官方 Source Control GRAPH**：泳道连线改三次贝塞尔平滑曲线、HEAD 空心双环高亮、引用胶囊改全圆角实心 pill 并跟随泳道色、工具栏 seg 贴近官方；命令标题 / 视图名 / aria-label 统一为 Graph（内部标识符不动，不改数据 / 协议 / 布局算法 / CI 逻辑）。(#53) + +### Fixed +- **提交 / CI 悬浮浮层被侧边栏 iframe 裁剪失效**：抽出共用 `positionFloat`（锚右侧 → 越界翻左 → 再越界收进视口）彻底修复。(#53) +- **活动栏未提交变更数角标更新不及时**：角标承载由 Commit `WebviewView` 迁至隐藏 Treeview（`hyperGit.changesBadge`，`when:false`），`activate` 即实例化、面板未打开也可靠；新增 engine 纯函数 `change-count` 作去重单一事实源。(#52) +- **发布流水线预发布打包缺陷**：`package` job 对 rc tag 补 `--pre-release` 打包，与 `vsce publish --pre-release` 对齐，修复 Marketplace 预发布 publish 失败。详见 [issue #11](./docs/.agents/issue.md)。 + +### Docs +- **README 真实性校准 + 中英双语重构**：单测计数校正为 324、移除不存在的 `ui/` 层描述、publisher 落实为 `ThreeFish-AI`；根英文、中文迁入 [`docs/i18n/zh-CN/README.md`](./docs/i18n/zh-CN/README.md)。(#51) + +## [0.0.10-rc.2] - 2026-07-04 — 修复发布流水线预发布打包缺陷 + +rc.1 因 CI `package` job 未以 `--pre-release` 打包，致 `publish` job 的 Marketplace 步骤报「VSIX 未以 pre-release 打包」而失败（OpenVSX 步骤随之被 skipped），三渠道仅 GitHub Release 成功、Marketplace/OpenVSX 未发出。rc.2 修复该流水线缺陷后重新走通；产品内容与 rc.1 一致。完整叙述见 [Release Note v0.0.10-rc.2](./docs/releases/v0.0.10-rc.2.md)。 + +### Fixed +- **CI `package` job 对 rc tag 以 `--pre-release` 打包**：VS Code 要求「以预发布方式发布的 VSIX 必须在打包时即带 `--pre-release` 标记」，否则 `vsce publish --pre-release` 报 `Cannot use '--pre-release' flag with a package that was not packaged as pre-release`。`package` 步骤改为与 publish / OpenVSX 同款 `PRE_FLAG` 判定（`GITHUB_REF_NAME` 含 `rc` 即追加 `--pre-release`），令同一枚预发布 VSIX 贯穿 GitHub Release / Marketplace / OpenVSX 三渠道；正式版 tag 与分支 / PR CI 行为不变。详见 [issue #11](./docs/.agents/issue.md)。 + +## [0.0.10-rc.1] - 2026-07-04 — Graph 视图对齐官方 · 浮层与角标修复 · 发布链路验证 + +面向 0.0.10 的首个预发布（RC）。在 v0.0.9 基础上将提交图视图更名为 **Graph** 并视觉对齐 VS Code 官方 Source Control GRAPH 视图，修复提交/CI 悬浮浮层被侧边栏 iframe 裁剪失效、活动栏未提交数角标更新不及时两处缺陷，并完成 README 真实性校准与中英双语重构。本版亦作为 **VS Code Marketplace 发布链路打通**的验证版（首次以官方预发布模型 `--pre-release` 发布 `0.0.10`）。完整用户视角叙述见 [Release Note v0.0.10-rc.1](./docs/releases/v0.0.10-rc.1.md)。 + +### Changed +- **Log 视图更名为 Graph 并对齐官方 Source Control GRAPH**：泳道连线由直线改三次贝塞尔平滑曲线（同列自动退化直线）；当前 HEAD 行渲染为空心环 + 内点（双环高亮）；引用胶囊移至 message 右侧后缀、底色跟随本行泳道色、改全圆角实心 pill + 分支/云/tag 内联 SVG 图标前缀；工具栏 seg 按钮间距 / 圆角 / hover 态贴近官方。视图名与 Refresh / Filter / Clear Graph Filter 命令标题、CI 配置描述、aria-label 统一为 Graph（`viewType hyperGit.log`、`log/*` 消息前缀等内部标识符不动，不改底层数据 / 协议 / 布局算法 / CI 逻辑）。(#53) + +### Fixed +- **提交 / CI 悬浮浮层被侧边栏 iframe 裁剪失效**：#48 的浮层定位将横向定位改为 `left = window.innerWidth + 8`，误以为 webview `position:fixed` 可越界渲染到编辑器；实则侧边栏 WebviewView 是沙箱 iframe，坐标系为自身视口，该值落到右边界外被裁剪不可见。抽出共用 `positionFloat`（锚触发元素右侧 → 越界翻左 → 再越界收进视口），彻底修复 CI 与提交两处浮层。(#53) +- **活动栏未提交变更数角标更新不及时**：角标原挂 Commit `WebviewView`，VS Code 在 `resolveWebviewView`（用户打开过面板）前无法显示 webview 角标（vscode#164974 / #146330），致面板未打开时新变更不点亮、提交 / 撤销后不清除。改由隐藏 TreeView（`hyperGit.changesBadge`，`when:false`）承载，`activate` 即实例化、无论面板是否打开都可靠聚合到容器图标；新增 engine 纯函数 [`change-count`](./src/engine/scm-mapping/change-count.ts)（`toRelKey` / `countUniqueChanges`）与 `GitRepositoryService.getChangeCount()` 作单一事实源（`getChanges` 复用同一去重逻辑），角标走独立 40ms 微防抖快路径、与 150ms 重刷新解耦；移除 Commit webview 死代码（`updateBadge` / `pendingBadge`）杜绝容器 2× 计数，并补 change-count 单元测试锁定计数不变式。(#52) + +### Docs +- **README 真实性校准 + 中英双语重构**：经 3 路只读核验 + 单测实跑取证修正——移除不存在的 `ui/` 层（改述 `engine/` → `adapter/`）、单元测试计数 280 → **324**、行级提交 CodeLens 标签校准为 "Commit this Hunk"、publisher 占位符落实为真实 `ThreeFish-AI`；根 `README.md` 改写为地道英文版，中文版迁入 [`docs/i18n/zh-CN/README.md`](./docs/i18n/zh-CN/README.md) 并互加语言切换、补入 CHANGELOG 链接。同步校正文档中心「最新」发布指针与知识索引 agent 接缝清单。(#51) +- 补充 `vsce` 发布用法说明并重构 README 底部 footer，修复链接渲染与协议措辞。 + +> 规模实证（README 校准后）：**6 视图 / 97 命令 / 6 配置项 / 324 单元测试**（32 文件全绿）+ 集成测试，CI 三平台（Ubuntu / macOS / Windows）矩阵全程 GREEN。 + +## [0.0.9] - 2026-07-04 — 视图整合 · UI 系统化 · 分支与 CI 增强 + +自上一个正式版 0.0.6 以来的首个公开版本，聚合 0.0.7 / 0.0.8 / 0.0.9 三轮迭代：提交/日志视图内聚重构、UI/UX 全局系统化、分支与 CI 能力增强，以及一批工程修复。完整用户视角叙述见 [Release Note v0.0.9](./docs/releases/v0.0.9.md)。 + +### Added +- **变更文件目录树切换**：Commit 视图活动 Changelist 文件列表、Log 视图选中提交的变更文件列表均支持「平铺 / 按目录分组（Group by Directory）」两态切换（工具栏 List/Tree 段控），偏好按视图 `webview.setState` 记忆。目录树由纯逻辑 [`engine/tree/file-tree.buildFileTree`](./src/engine/tree/file-tree.ts) host 侧构建随 payload 下发（复用 graph-layout「host 算、webview 渲」范式，规避内联脚本无法 import engine 的 Split-Brain），叶子以 `fileIndex` 回指扁平列表；支持单目录子链折叠（对齐 VS Code `explorer.compactFolders`）；Commit 树形附目录级三态复选框。详见 [变更文件目录树](./docs/features/file-list-group-by-directory.md)。(#47) +- **Log 提交悬浮详情**：鼠标悬停 Log 提交行以浮层展示完整信息——所在本地/远程分支、标签、HEAD、完整提交消息（subject + body）、作者 `name `、（与作者不同时）提交者、作者/提交时间（绝对 + 相对）、完整 SHA；复用 CI 状态浮层范式（置于虚拟滚动容器外、与 CI 浮层互斥），`i` 键开、`Esc` 关，滚动/刷新自动消隐。`git log` 取数扩展 `%cn/%cI/%b`（body 置末，NUL/RS 分隔容多行），正文上限截断以控 payload。详见 [Log 提交悬浮详情](./docs/features/log-commit-tooltip.md)。(#47) +- **清理已删远程分支入口**：Branches 视图新增「Clean up Deleted Remote Branches」命令，一键剔除远端已删除却仍残留于本地的 remote-tracking 引用，根治 Log 视图残留已删分支提交的游离泳道。(#44) +- **远程分支右键删除**：Branches 视图远程分支支持右键删除（`git push --delete `），无需切到命令行。(#42) + +### Changed +- **Commit 视图承接全部变更管理能力**（原 Changes 视图平移）：活动 Changelist 文件单击看 Diff、右键（原生 QuickPick）执行 移动到 Changelist / 查看历史 / 暂存·撤销 Hunks / 加入 `.gitignore` / 丢弃改动；头部提供 Changelist 切换下拉 + ⋯ 管理菜单（新建 / 重命名 / 删除）。详见 [Commit 视图整合](./docs/features/commit-view-consolidation.md)。(#47) +- **Git 操作工具栏与未提交数角标迁至 Commit 视图**：原挂在 Changes 视图标题栏的 refresh / push / pull / fetch / patch 等动作迁到 Commit 视图标题栏（去掉与 webview 内按钮重复的 commit / commitAndPush）；活动栏未提交数角标改由 Commit `WebviewView.badge` 承载，首帧未 resolve 以 `pendingBadge` 兜底。(#47) +- **UI/UX 全局系统化**：建立共享设计 Token 地基（spacing / radius / button，`shared-styles.ts`）并注入 Commit / Log / Merge / Rebase 四个 Webview；Log DAG 泳道色改读 `--vscode-charts-*` 主题令牌（深浅主题自适应）；命令层去冗余（标题栏 ≤5 项、同步操作下沉溢出组、危险操作归入 `9_dangerous`、新增 `hyperGit.logFilter` 聚合过滤器）；~94 项命令标题 / 配置 / viewsWelcome 统一英文并为高频与危险命令补齐 codicon；Webview 加固（空态、加载态、快捷键、ARIA）与 5 棵 TreeView 的 Markdown Tooltip 统一。(#43) +- **品牌图标改用透明底 Emerald 绿环方案**：源图标改为透明底 + `#3FB950` 绿色圆环 + git-pull-request 字形，重生成 256×256 透明 PNG（66KB→14KB）；新增 `galleryBanner`（`#0E2A1C` 深绿、dark 主题）与 Marketplace 页头协调。(#49) + +### Removed +- **移除 CHANGES 树视图**：其展示的活动 Changelist 与 Commit 视图的 Active Changelist 完全重复（同源 `getChanges()` + `getGroups()`）；全部独有能力已零回归平移入 Commit 视图（见 Changed），视图数由 7 降为 6。(#47) ### Fixed +- **Log 提交/CI 浮层定位重做**：原 `positionTip`/`positionCommitTip` 把浮层锚定在所悬元素左沿并按 webview 宽度夹紧，420px 宽的浮层在 ~240px 窄侧边栏中从左沿一路铺到编辑器，既「撑满 LOG 视图」又方位怪异。改为横向固定到 `window.innerWidth + 8`（侧边栏右沿外、编辑器区内），纵向与所悬行/图标顶部对齐并按视口高度夹紧；复用 webview `position:fixed` 可越界渲染到编辑器区的特性，浮层不再压住 LOG 列表，自然悬浮于所悬行的右侧。(#48) +- **Log All 范围改用 `--branches --tags --remotes`**：原 `--all` 遍历全部 refs，含宿主工具注入的 `refs/conductor-checkpoints/*` 与 `refs/conductor-archive-heads/*`，致游离提交仍可达、被画成游离泳道；改用三大标准命名空间根治污染（Checkpointer 页保留 `--all` 以见原始完整图）。(#45) +- **CI 状态图标防闪烁与准实时刷新**：终态缓存避免重复请求以消除闪烁，轮询间隔优化实现准实时刷新，各检查项状态图标与 Tooltip 颜色按通过 / 失败 / 运行中语义对齐。(#41, #40) - 修复 `vsce package` 打包因 ESLint `no-useless-assignment` 阻断：`engine/ci/remote-parser.ts` 中 `host`/`path` 的空串初值为 dead store（`hasScheme` 真假两分支均无条件重赋、解析失败处先 `return null`），改为带类型标注的纯声明消除，由 TS 确定赋值分析接管，运行时行为不变。 +- 修复 Log 提交悬浮浮层「行→浮层→空白」后卡死不消失：`commitTipEl.mouseleave` 未复位 `overCtRow`，致 `scheduleHideCommit` 的 `!overCtRow && !overCt` 守卫恒不成立；在 `mouseleave` 一并复位 `overCtRow` 修复。 +- 修复 `capBody` 截断劈开 Unicode 代理对：`String.prototype.slice(0, BODY_CAP)` 按 UTF-16 码元计数，2000 边界落在 emoji 代理对中间会留下孤立高代理位（渲染为 `�`）；改用 `Array.from(t).slice(0, BODY_CAP).join('')` 按码点截断。 ## [0.0.6] - 2026-06-30 — 首个 MVP 正式版 @@ -72,4 +139,5 @@ - 目录 / folder diff（虚拟文档）、Submodules 管理。 - M5 AI Agent（5 个接缝已预埋 Null 实现，本版未启动）。 +[0.0.9]: https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.9 [0.0.6]: https://github.com/ThreeFish-AI/hyper-git/releases/tag/v0.0.6 diff --git a/README.md b/README.md index e5e091d..0caf9b3 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

Hyper Git

-

为 VS Code 带来统一的 Git 变更管理 与 提交工作流——多变更分组、自绘提交面板、可视化提交图、Shelf、行级提交，并为未来 git 管理的 AI Agent 自主代理能力预留架构接缝。

+

A unified Git change-management and commit workflow for VS Code — multi-changelist grouping, a hand-built commit panel, a hand-rendered commit graph, Shelf, and line-level commits, with architectural seams reserved for future AI-driven Git agents.

CI @@ -12,73 +12,89 @@ VS Code >= 1.85

-## 核心能力 +

+ English · 简体中文 +

+ +

6 views · 97 commands · 6 settings · 324 unit tests

+ +## Features -- **多 Changelist Changes 视图**：将改动分组到命名列表，设活动列表为提交目标，新建/重命名/删除/移动，`workspaceState` 持久化（重启恢复）；状态色复用 `gitDecoration.*` 主题色。 -- **Commit 提交窗口**：自绘提交面板 + Conventional Commits 实时校验 + Amend / Sign-off / 跳过 Hook + 提交 / 提交并推送；勾选集即提交权威范围；最近消息复用。 -- **Log 提交图（自绘 DAG）**：彩色泳道、分叉·合并连线、HEAD/分支/标签徽标，虚拟滚动增量加载；7 个可组合过滤器（作者/路径/grep/正则/合并模式/日期/清除）；per-commit 操作（Reset、新建分支·标签、Cherry-Pick、Revert、查看包含分支）。 -- **Branches 分支管理**：收藏/本地/远程/标签四段分组 + ahead·behind·upstream 跟踪；新建/检出/删除/重命名/合并/变基/比较/收藏；**多选批量**删除、复制引用、收藏（已合并/未合并诚实分栏确认）。 -- **Stash & Shelf**：Stash 全操作（含 keep-index / clear / 从 Stash 建分支）；独立 **Shelf**（基于 patch、独立于 stash，含 3-way 合并 Unshelve）。 -- **Worktrees**：全生命周期管理——新建（新分支/检出/detached）、在新窗口打开、锁定/解锁、移动、删除、清理失效。 -- **行级与 Hunk 提交**：编辑器内 CodeLens「提交此 Hunk」、部分暂存/取消暂存、光标处暂存、Hunk 归属 Changelist。 -- **远程与冲突**：Pull/Push/Fetch + Push…/Update…/Merge… 对话框（force-with-lease / rebase / squash 等）+ 自绘 **3-way Merge Editor** 与冲突兜底引导。 -- **历史编辑**：Cherry-Pick、Revert、Reset、交互式 Rebase、Undo/Drop/Fixup/Reword。 -- **其他**：Blame 行内注解、Patch 导出/应用、Reflog、3-way Diff 概览、Discard、Diff（HEAD ↔ Working）。 +- **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). +- **Branches management**: favorites / local / remote / tags grouped into four sections with ahead·behind·upstream tracking; create / checkout / delete / rename / merge / rebase / compare / favorite; **multi-select batch** delete, copy ref, and favorite (with an honest merged/unmerged split confirmation). +- **Stash & Shelf**: full stash operations (including keep-index / clear / create branch from stash); a standalone **Shelf** (patch-based, independent of stash, with 3-way merge Unshelve). +- **Worktrees**: full-lifecycle management — create (new branch / checkout / detached), open in a new window, lock / unlock, move, remove, and prune stale entries. +- **Line-level & hunk commits**: in-editor "Commit this Hunk" CodeLens, partial stage / unstage, stage at cursor, and hunk-to-changelist attribution. +- **Remote & conflicts**: Pull / Push / Fetch plus Push… / Update… / Merge… dialogs (force-with-lease / rebase / squash, etc.) and a hand-built **3-way Merge Editor** with conflict-resolution fallbacks. +- **History editing**: Cherry-Pick, Revert, Reset, interactive Rebase, Undo / Drop / Fixup / Reword. +- **More**: inline Blame annotations, patch export / apply, Reflog, 3-way diff overview, Discard, and Diff (HEAD ↔ Working). -## 架构（路径 B：消费 + 自绘） +## Architecture (Path B: Consume + Hand-render) -- **消费** 内置 `vscode.git` 导出的稳定 `Repository` API 作为 git 底座，不重造 git 状态机。 -- **受控 CLI 通道**：稳定 API 未覆盖的能力（cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash 列表 / graph 拓扑 / shelf 等）经 `GitRepositoryService.execGit` 复用同一 git 二进制（`api.git.path`）实现。 -- **自绘视图** 承载完整的变更管理 UI；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。 -- **AI 接缝**：预留 `ILlmProvider` / `IPreCommitInspector` 等 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），实现延后至 M5。 +- **Consumes** the stable `Repository` API exported by the built-in `vscode.git` extension as its Git foundation, rather than rebuilding a Git state machine. +- **Controlled CLI channel**: capabilities the stable API does not cover (cherry-pick / revert / reset / branch rename / hunk staging / stash listing / graph topology / shelf, etc.) run through `GitRepositoryService.execGit`, reusing the same Git binary (`api.git.path`). +- **Hand-rendered views** carry the full change-management UI (webviews live under `adapter/webview/`); pure logic is distilled into `engine/` (zero `vscode` dependency, unit-testable). +- **AI seams**: 5 interfaces (`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`) are reserved (design inspired by JetBrains' `CheckinHandler` commit lifecycle), currently shipped as Null implementations; the full implementation is deferred to M5.

Framework

-## 安装 +## Install -- **手动（当前推荐）**：从 [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) 下载 `hyper-git-agentic-git-x.x.x.vsix` → 命令面板 `Extensions: Install from VSIX`。 -- **OpenVSX**（Cursor / Windsurf / Gitpod / VSCodium）：搜索 `Hyper Git - Agentic Git`。 -- **VS Code Marketplace**：搜索 `Hyper Git - Agentic Git`（发布上线后可用）。 -- **要求**：VS Code ≥ 1.85.0 + 启用内置 Git 扩展（`vscode.git`，默认随附）。仅支持本地 git 仓库，不支持虚拟 / Web 工作区。 +- **Manual (recommended for now)**: download `hyper-git-agentic-git-x.x.x.vsix` from [Releases](https://github.com/ThreeFish-AI/hyper-git/releases) → run `Extensions: Install from VSIX` in the Command Palette. +- **VS Code Marketplace**: search for `Hyper Git - Agentic Git`. +- **Requirements**: VS Code ≥ 1.85.0 with the built-in Git extension enabled (`vscode.git`, bundled by default). Local Git repositories only — virtual / Web workspaces are not supported. -## 已知限制 +## Known Limitations -- Commit 窗口的 Co-authored-by / Author 覆盖（`--author`）/ 撤销最近提交的**按钮 UI 接线**（engine `trailer` 已就绪，仅缺 webview 交互）。 -- Partial 多文件选择 UX、行级 split chunks（按选定行拆分提交）。 -- 目录 / folder diff（虚拟文档）、Submodules 管理。 -- M5 AI Agent（5 个接缝已预埋 Null 实现，本版未启动）。 +- Button-UI wiring for the commit panel's Co-authored-by / Author override (`--author`) / undo-latest-commit (the engine `trailer` is ready; only the webview interaction is missing). +- Partial multi-file selection UX and line-level split chunks (splitting a commit by selected lines). +- Directory / folder diff (virtual documents) and Submodules management. +- The M5 AI agent (all 5 seams are pre-wired with Null implementations; not started in this release). -详见[工程实施方案](./docs/architecture/engineering-plan.md)、[实施状态总览](./docs/milestones/implementation-status.md)与[知识索引](./docs/.agents/knowledge-map.md)。 +See the [Engineering Plan](./docs/architecture/engineering-plan.md), the [Implementation Status overview](./docs/milestones/implementation-status.md), and the [Knowledge Map](./docs/.agents/knowledge-map.md) for details. -## 路线图 +## Roadmap -| 里程碑 | 主题 | 状态 | -| ------ | --------------------------------------------------- | ---- | -| M0 | 脚手架 + CI | ✅ | -| M1 | Git Adapter + Changes TreeView（多 Changelist） | ✅ | -| M2 | Commit 提交窗口（模板 / Amend / CC 校验 / Hook 链） | ✅ | -| M3 | Log（Graph DAG） + Branches + Diff/Blame | ✅ | -| M4 | Stash / Shelf / 行级提交 / Worktrees | ✅ | -| M5 | AI Agent（接缝已预留，实现待启动） | ⏳ | +| 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) | ⏳ | + +## Development + +```bash +pnpm install # install dependencies +pnpm run compile # type-check + lint + build +pnpm run watch # watch build (press F5 to launch the Extension Host debugger) +pnpm run test:unit # unit tests (pure engine logic, Vitest, 324 cases) +pnpm run test:integration # integration tests (@vscode/test-electron) +pnpm run package # production build +pnpm dlx @vscode/vsce package # package the .vsix +``` -## 开发 +Packaging and publishing with vsce (`@vscode/vsce`): ```bash -pnpm install # 安装依赖 -pnpm run compile # 类型检查 + lint + 构建 -pnpm run watch # 监听构建（F5 启动 Extension Host 调试） -pnpm run test:unit # 单元测试（engine 纯逻辑，Vitest，280 例） -pnpm run test:integration # 集成测试（@vscode/test-electron） -pnpm run package # 生产构建 -pnpm dlx @vscode/vsce package # 打包 .vsix +pnpm dlx @vscode/vsce package +# hyper-git-agentic-git-x.x.x.vsix generated +pnpm dlx @vscode/vsce publish +# ThreeFish-AI.hyper-git-agentic-git-x.x.x published to VS Code Marketplace ``` -- **分层**：`engine/`（纯逻辑）→ `adapter/`（唯一接触 vscode API）→ `ui/`；`agent/` 以接口注入 `engine`，不反向依赖 UI；`shared/protocol.ts` 为 Webview ↔ Host 契约单一事实源。 -- **发布**：`v*` 标签触发 CI 产出 GitHub Release（附 `.vsix`，正文取自 [`docs/releases/`](./docs/releases/README.md)）+ OpenVSX；VS Code Marketplace 由 `ENABLE_MARKETPLACE_PUBLISH` 变量门控。 -- 包管理与脚本统一使用 `pnpm`（遵循 [AGENTS.md](./AGENTS.md) 工程规范）。完整文档见[文档中心](./docs/README.md)。 +- **Layering**: `engine/` (pure logic) → `adapter/` (the sole layer touching the vscode API, including the hand-rendered `adapter/webview/` UI); `agent/` is injected into `engine/` via interfaces and never depends on the UI; `shared/protocol.ts` is the single source of truth for the Webview ↔ Host contract. +- **Release**: a `v*` tag triggers CI to produce a GitHub Release (with the `.vsix` attached; the body is drawn from [`docs/releases/`](./docs/releases/README.md)) and publish to the VS Code Marketplace (gated by the `ENABLE_MARKETPLACE_PUBLISH` variable; `rc` tags go to the pre-release channel). +- Package management and scripts standardize on `pnpm` (per the [AGENTS.md](./AGENTS.md) engineering conventions). Version history is tracked in the [Changelog](./CHANGELOG.md). See the [documentation hub](./docs/README.md) for the full docs. -## 许可证 +--- -[MIT](./LICENSE)。 +
+ Built with 🧠, ❤️, and an absurd amount of coffee by ThreeFish-AI · Released under the MIT License. +
diff --git a/docs/.agents/issue.md b/docs/.agents/issue.md index 4cadad8..38ce72f 100644 --- a/docs/.agents/issue.md +++ b/docs/.agents/issue.md @@ -67,7 +67,7 @@ - **表因**：用户截图反馈 Branches 视图中一组功能/工作分支无法框选多个、无法批量删除。 - **根因**：`hyperGit.branches` 经 `vscode.window.registerTreeDataProvider` 注册——该 API **不支持** `canSelectMany`，故视图天然单选；所有分支命令处理器亦只接收单个 `BranchNode`。多选能力（`canSelectMany: true`）仅 `createTreeView` 的 `TreeViewOptions` 支持。 - **处理方式**：改用 `createTreeView('hyperGit.branches', { treeDataProvider, canSelectMany: true })`（句柄入 subscriptions）。批量命令处理器签名扩展为 `(clickedNode, selectedNodes[])`——VS Code 多选树的 `view/item/context` 命令第 2 实参即完整选区数组。新增纯逻辑 `engine/ref/selection.collectBranchRefs`（谓词过滤 + shortName 去重 + 「点击在选区之外则以点击项为准」）与 `engine/ref/cleanup.partitionByMerged`/`formatBranchDeleteConfirm`，使 `branchDelete`/`tagDelete`/`copyBranchRef`/`toggleFavorite` 批量化（删除仅一次 `git branch --merged` 分类、汇总成功/失败、末尾单次刷新）。`package.json` 对仅单目标命令（检出/合并/变基/重命名/比较等）追加 `&& !listMultiSelection` 在多选时隐藏。 -- **后续防范**：① 需要承载 `.badge` 或 `canSelectMany` 等 `TreeViewOptions` 能力的视图，一律用 `createTreeView` 而非 `registerTreeDataProvider`（本仓 `hyperGit.changes` 已有先例）。② 多选命令正确性**只依赖处理器读取实参**（`clickedNode` + `selectedNodes[]`），不得依赖 `listMultiSelection` 上下文键——其对**自定义贡献视图**的可靠性无法确证，仅作菜单整洁的视觉优化；单目标命令因只读 `clickedNode` 即便该键失效仍安全。③ 「右键点击选区之外」须以点击项为准（手势目标优先），由归一化助手统一兜底。 +- **后续防范**：① 需要承载 `canSelectMany` 等 `TreeViewOptions` 能力的 **TreeView**，一律用 `createTreeView` 而非 `registerTreeDataProvider`（本仓 `hyperGit.branches` 即此）；`.badge` 则 `TreeView` 与 `WebviewView` **均支持**——`hyperGit.changes` 视图移除后（其活动 Changelist 与 Commit 视图重复），未提交数角标已迁至 Commit `WebviewView.badge`，注意 `WebviewView` 仅在 `resolveWebviewView` 后可置 badge，需 `pendingBadge` 兜底首帧未 resolve 的时序。② 多选命令正确性**只依赖处理器读取实参**（`clickedNode` + `selectedNodes[]`），不得依赖 `listMultiSelection` 上下文键——其对**自定义贡献视图**的可靠性无法确证，仅作菜单整洁的视觉优化；单目标命令因只读 `clickedNode` 即便该键失效仍安全。③ 「右键点击选区之外」须以点击项为准（手势目标优先），由归一化助手统一兜底。 - **同类问题影响**：所有以 `registerTreeDataProvider` 注册却后续需要多选/角标的自定义 TreeView；以及误把单目标命令在多选下直接作用于「点击项」造成的隐性误操作。 ## #9 LOG 视图残留「已删分支」提交（实为工具注入的内部引用污染 `git log --all`） @@ -78,4 +78,28 @@ - **后续防范**：① 「全分支视图」语义应映射到 `--branches --tags --remotes` 而非 `--all`——`--all` 是「全部引用」而非「全部分支」，二者差异恰是工具注入引用的污染面。② 客户端按提交 message 正则过滤是**漏的抽象**（拦不住作为祖先被带入的游离提交）；根治应在 ref 选取层（服务端参数）而非 subject 过滤层。③ **诊断 git 引用类问题时务必先 `git for-each-ref` 列出全部命名空间**——本案最初误判为「远端已删、本地未 prune」（#44 与一度推进的 prune-on-fetch 方案均为此误判），直到列出 refs 才发现真凶是 conductor-* 引用；「prune 无效」本身就是关键反证，应据其反向收敛而非强行加 prune。④ 修正「错漏逻辑」前先用 `git log --all` vs `--branches --tags --remotes` 的差集实证根因，避免再次基于关键字匹配机械式修改。 - **同类问题影响**：所有在带「工具注入内部引用」环境（IDE/Agent checkpoint、`refs/stash`、`refs/replace/*`、`refs/notes/*` 等）下展示 `git log --all` 图的 Git GUI；凡把「范围 = 引用集合」与「范围 = message 过滤」混为一谈的实现均可能漏过游离提交。 +## #10 活动栏未提交数角标更新不及时（WebviewView.badge resolve 前不显示） + +- **表因**：用户截图反馈 Hyper Git 活动栏图标的未提交变更数角标更新不及时——有时已有变更却不显示角标，有时文件已提交/撤销角标仍不消失。 +- **根因**：角标承载于 Commit `WebviewView.badge`（#8 移除 Changes 视图后迁入）。命中 VS Code 已知限制：webview 角标在 `resolveWebviewView`（即用户至少打开过一次该视图）之前无法显示（[microsoft/vscode#164974](https://github.com/microsoft/vscode/issues/164974)、[#146330](https://github.com/microsoft/vscode/issues/146330)）；源码印证 `commit-webview.ts` 未 resolve 时 `updateBadge` 仅写入 `pendingBadge`、永不上屏，`WebviewView.onDidDispose` 亦仅在用户显式取消勾选视图时触发。故只要面板未打开/隐藏（用户在编辑器或其他活动容器工作），新变更无法点亮、提交/撤销后无法清除。#8 的「后续防范」已预警此 `pendingBadge` 首帧时序隐患，本 Issue 即其兑现。TreeView 无此限制——`createTreeView` 可在 activate 强制实例化视图对象，`.badge` 无论可见与否都可靠聚合到容器图标（容器角标 = 容器内各视图 badge 之和）。 +- **处理方式**：新增隐藏承载视图 `hyperGit.changesBadge`（package.json `when:false`，永不渲染，复用 `EmptyTreeProvider`），经 `createTreeView` 于 activate 即实例化并置 `.badge`；角标承载由 Commit WebviewView 整体迁出（移除 `updateBadge`/`pendingBadge` 死代码，杜绝容器求和 2× 计数）。新增 `engine/scm-mapping/change-count.ts`（`toRelKey`/`countUniqueChanges`）作为去重单一事实源，`GitRepositoryService.getChangeCount()` 与 `getChanges()` 共用；角标走独立 40ms 微防抖快路径（与 150ms 重刷新解耦、合并事件风暴、释放期清理定时器），首帧同步置初值。 +- **后续防范**：① 需要「面板未打开也持续显示」的活动栏计数角标，**必须**承载于 `createTreeView` 建立的 TreeView（可用 `when:false` 隐藏视图专职承载），**不可**依赖 `WebviewView.badge`——其 resolve 前不显示是 VS Code 已知限制而非本仓 bug；这与 #8「`.badge` TreeView/WebviewView 均支持」并行：「支持置 badge」≠「未 resolve 也上屏」。② 容器角标为**各视图 badge 之和**，全仓须保证**唯一承载者**，迁移承载时务必删除旧承载，否则重复计数。③ 计数与文件列表去重须共用单一事实源（`toRelKey`），避免「列表条目数 ≠ 角标数」漂移。④ `when:false` 承载视图的实机角标渲染需在 EDH 回归确认（跨 VS Code 版本聚合行为），失败则回退为 `visibility:collapsed` 的空视图。 +- **同类问题影响**：所有以 `WebviewView.badge` 承载活动栏/视图角标的自定义视图容器扩展；凡角标承载迁移未清理旧承载导致的重复计数；以及把「支持 badge 属性」误判为「隐藏态也能显示 badge」的时序类误区。 + +## #11 VS Code Marketplace 预发布 publish 失败（VSIX 未以 `--pre-release` 打包） + +- **表因**：以 rc tag（`v0.0.10-rc.1`）触发发布时，`publish` job 的「发布到 VS Code Marketplace」步骤报错 `Cannot use '--pre-release' flag with a package that was not packaged as pre-release. Please package it using the '--pre-release' flag and publish again.`，job 失败；其后的 OpenVSX 步骤（虽 `continue-on-error`）因前序步骤失败被 skipped，致三渠道仅 `github-release` 成功、Marketplace/OpenVSX 均未发出。 +- **根因**：`package` job 以 `vsce package --no-yarn`（**不带** `--pre-release`）打出「正式版」VSIX 作为 artifact；`publish` job 却对 rc tag 用 `vsce publish --packagePath *.vsix --pre-release`。vsce 强约束——以 `--pre-release` 发布的 VSIX 必须在**打包时**即带 `--pre-release`（预发布标志写入 VSIX manifest），否则拒绝发布。打包端与发布端的 `--pre-release` 判定不对称即致此错。历史 rc（0.0.9-rc.*）从未真正发到市场（Marketplace 步骤因缺 `VSCE_PAT`/变量被跳过），故该缺陷此前从未被触发暴露。 +- **处理方式**：`package` job 打包步骤改为与 publish/OpenVSX 同款 `PRE_FLAG` 判定——`GITHUB_REF_NAME` 含 `rc` 时追加 `--pre-release`，使同一枚「预发布 VSIX」贯穿 `github-release` / Marketplace / OpenVSX 三渠道（单一产物、零重复打包）。正式版 tag（无 `rc`）与分支/PR CI 仍打普通 VSIX，行为不变。 +- **后续防范**：① VS Code 预发布模型下，**打包与发布两端的 `--pre-release` 必须成对出现**；凡「先 package 成 artifact、后 publish 复用同一枚 VSIX」的流水线，预发布判定要在 package 端就落地，不能只在 publish 端加 flag。② 预发布版本号仍须纯 `major.minor.patch`（Marketplace 不接受 `-rc.N` semver 后缀），预发布语义由 `--pre-release` 标志 + tag 命名承载；`0.0.10` 作预发布后正式版须用更高版本（如 `0.0.11`），同一版本号不可既预发布又正式发布。③ OpenVSX 步骤的 `continue-on-error` 只隔离其自身失败——前序 Marketplace 步骤失败仍会使其 skipped；排障时勿因「OpenVSX 未报错」误判其已发布，须查其步骤实际状态与日志。④ Marketplace 发布链路的双凭证不可混淆：`VSCE_PAT`（Azure DevOps PAT，scope Marketplace→Manage）与 `OVSX_PAT`（open-vsx.org token）是不同服务的两个不同 token，且 Marketplace 发布还受仓库变量 `ENABLE_MARKETPLACE_PUBLISH` 门控。 +- **同类问题影响**：所有「package 出 artifact → publish 复用」且需发布预发布通道的 VS Code 扩展 CI；凡打包端与发布端 flag 判定不对称（`--pre-release`、平台化 `--target` 等同理）的流水线均会踩。 + +## #12 侧边栏视图无法解除最小展开高度（VS Code 核心硬编码 120px + #123715 已 not planned） + +- **表因**：用户反馈 Worktrees 视图展开后无法继续缩小（截图中仍占大片空白），要求「所有视图可拖到任意高度、取消最小高度限制」。 +- **根因**：侧边栏每个视图面板（`Pane`）的最小体高由 VS Code 核心**硬编码 = 120px**（竖直方向；构造函数 `this._minimumBodySize = ... orientation === HORIZONTAL ? 200 : 120`，见 `src/vs/base/browser/ui/splitview/paneview.ts`），加 22px 标题栏，展开态最小 ≈ **142px**，该值经 `minimumSize` 直接驱动 SplitView 拖拽分隔条下限。`WebviewViewPane extends ViewPane` **未覆写** `minimumBodySize`，故本扩展 2 个 webview（Commit/Graph）与 4 个 tree（Branches/Stash/Shelf/Worktrees）视图**共用同一 142px 下限**。允许扩展为活动栏容器内视图指定固定/最小/最大高度的官方特性请求 [microsoft/vscode#123715](https://github.com/microsoft/vscode/issues/123715) 已被**关闭为 not planned / out-of-scope**，从未新增任何 API 或 `package.json` 贡献点。扩展运行于独立进程，拿不到工作台面板对象，`minimumBodySize` setter 仅核心 `ViewPaneContainer` 调用；注入 CSS 亦无效（`.pane-body{min-height:0}` 改不动 JS 层用于夹取拖拽下限的 `minimumSize`）。 +- **处理方式**：该限制**无法经扩展解除**，采用受支持的折中缓解——在 `package.json` `contributes.views` 调初始布局默认值：次要视图 Stash/Shelf 设 `visibility:"collapsed"`（默认仅 22px 标题栏、点击即展开），Worktrees 保持 `visible`（仅以 `initialSize` 权重收窄），全部视图加 `initialSize`（Commit 3 / Graph 3 / Branches 2 / 其余 1，类 CSS flex 的高度权重）。两字段经 `src/vs/workbench/api/browser/viewsExtensionPoint.ts` 的 `viewDescriptor` schema 确认可用；`initialSize` **仅当「同一扩展同时拥有视图与视图容器」时生效**（本扩展拥有 `hyper-git` 容器与全部视图，条件满足）。 +- **后续防范**：① VS Code 侧边栏视图存在约 **142px 硬性最小展开高度**，无法经扩展降低——遇「任意高度 / 无最小高度」类诉求应直接引 #123715（not planned）说明平台边界，**勿承诺实现**；判断「webview 内容 CSS `min-height`」与「外层面板最小高度」是两回事。② `visibility` / `initialSize` **只影响初始状态**（「用户手动折叠/移动/隐藏过后即不再生效」）——老用户需命令面板「View: Reset View Locations」或右键容器图标「Reset Location」才采用新默认；实机验证须用**干净 profile 或先重置**以规避持久化布局。③ 想让展开视图更紧凑，只能靠「减少常驻视图数（默认折叠）+ 权重」，而非解除下限。 +- **同类问题影响**：所有向活动栏/侧边栏容器贡献 TreeView/WebviewView 且希望自定义或取消视图高度的扩展；凡把「webview 内容 `min-height` CSS」误认为能改变外层面板最小高度的实现。 + diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md index dff7a5c..63920c2 100644 --- a/docs/.agents/knowledge-map.md +++ b/docs/.agents/knowledge-map.md @@ -16,19 +16,23 @@ ## 项目文档（docs/） - [文档中心](../docs/README.md) — 文档与调研资产总索引。 +- [README（简体中文）](../docs/i18n/zh-CN/README.md) — 根 README 的中文版本（根路径为英文版，i18n 目录沉淀中文）。 - [Log 视图 CI 状态](../docs/features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + Tooltip 明细）：认证、限流、懒加载、边界与配置。 +- [Commit 视图整合](../docs/features/commit-view-consolidation.md) — 移除 CHANGES 视图，其文件操作/changelist 管理/Git 工具栏/未提交角标零回归平移入 Commit 视图。 +- [变更文件目录树](../docs/features/file-list-group-by-directory.md) — Commit / Log 文件列表「平铺 ⇄ 按目录分组」切换：host 侧 `buildFileTree` 构树下发、compact 折叠、目录三态。 +- [Log 提交悬浮详情](../docs/features/log-commit-tooltip.md) — 悬停提交行浮层展示 分支/标签/HEAD/完整消息/作者·提交者/时间/SHA；复用 CI 浮层范式、与其互斥。 - [实施状态总览](../docs/milestones/implementation-status.md) — M0-M5 交付记录 + API 限制 + M5 AI 设计 + 验证/发布（**实施看板**）。 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。 - [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。 - [调研报告](../docs/research/README.md) — SCM 集成 / 工程蓝图 / 发布 CI / AI 接缝四路循证报告。 -- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.6](../releases/v0.0.6.md)）。 +- [发布说明](../releases/README.md) — 各正式版 Release Notes（GitHub Release 正文单一事实源；最新 [v0.0.9](../releases/v0.0.9.md)）。 ## 架构分层（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+）。 -- `agent/` — AI 接缝（M5 实现）：`ILlmProvider`、`IPreCommitInspector`、`IChangelistGrouper`、`IConflictResolver`、`IChatToolRegistrar`。 +- `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 b32bb9f..96d4196 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,12 +11,12 @@ - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。 ## 发布说明 -- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.6 首个 MVP](./releases/v0.0.6.md)。 +- [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.9 视图整合 · UI 系统化 · 分支与 CI 增强](./releases/v0.0.9.md)。 ## 调研报告（循证依据） - [02 · VS Code SCM API 与 vscode.git 集成路径](./research/02-vscode-scm-integration.md) — 路径 B 决策依据、SCM 稳定/proposed API 边界、changelist 模型映射。 - [03 · VS Code 扩展工程蓝图](./research/03-extension-blueprint.md) — 技术栈决策、工程骨架、IDEA→VS Code UI 表面映射表。 -- [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md) — 双市场（Marketplace + OpenVSX）、CI 矩阵、版本治理、安全。 +- [04 · 发布策略 + CI/CD](./research/04-publishing-cicd.md) — VS Code Marketplace 发布、CI 矩阵、版本治理、安全。 - [05 · AI Agent 架构预留](./research/05-ai-agent-seams.md) — AI 接缝（ILlmProvider 等）+ 借鉴 JetBrains CheckinHandler 责任链设计 + 渐进式引入路线。 ## 协作与规范 diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md index a00565b..5a9c28d 100644 --- a/docs/architecture/engineering-plan.md +++ b/docs/architecture/engineering-plan.md @@ -1,7 +1,7 @@ # Hyper Git — VS Code 扩展工程实施方案 > 提供完整的「Git 变更管理 + Commit 提交工作流」（功能完备性参考 IntelliJ IDEA 等成熟实现），并为未来 AI Agent 自主代理预留架构接缝。 -> 决策已与用户确认：**路径 B**（消费 `vscode.git` API + 自建 changelist registry + 独立视图容器）、扩展命名 **Hyper Git**、**双市场发布**、**AI 现仅预留接缝 + Null 实现、延后至 M5**。 +> 决策已与用户确认：**路径 B**（消费 `vscode.git` API + 自建 changelist registry + 独立视图容器）、扩展命名 **Hyper Git**、**VS Code Marketplace 单市场发布**、**AI 现仅预留接缝 + Null 实现、延后至 M5**。 --- @@ -28,7 +28,7 @@ | **Commit 编辑器** | WebviewView 自绘（多行 / 模板 / Conventional Commits 校验 / Amend / Author / sign-off） | 原生 `SourceControlInputBox` 仅 `value` 字段，Provider 已删除 | | **Log 提交图** | Webview 自绘 SVG graph + 消费 `Repository.log()` | `scmHistoryProvider` 为 proposed，上架不可用 | | **Diff 预览** | 复用 `vscode.diff` + `api.toGitUri(uri,'HEAD')`（零成本） | Track2 §5.5 | -| **发布** | 双市场（Marketplace + OpenVSX） | Cursor/Windsurf 走 OpenVSX；AI 受众主战场 | +| **发布** | VS Code Marketplace 单市场 | 官方市场为唯一渠道；每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装 | | **AI** | 现仅定义接缝 + Null 实现，实现延后 M5 | YAGNI + 借鉴 JetBrains `CheckinHandler` 责任链语义 | **架构总览（Mermaid，深色模式高对比）**： @@ -148,10 +148,10 @@ hyper-git/ | `api.toGitUri(uri, ref)` | 构造任意 ref 版本的资源 Uri（diff 原始端） | 同上 | | `vscode.commands.executeCommand('vscode.diff', left, right, title)` | 文件 diff 预览（零成本，不自绘 diff） | VS Code 稳定 API | | `ThemeColor('gitDecoration.modifiedResourceForeground')` 等 | 文件状态色（深色模式一致） | 复用原生 token | -| `@vscode/vsce` / `ovsx` | 打包 / 发布 | 官方工具 | +| `@vscode/vsce` | 打包 / 发布 | 官方工具 | | `@vscode/test-electron` | 集成测试 | 官方唯一推荐 | | `esbuild-sample` 模板 | 工程骨架零点（`esbuild.js` + scripts） | microsoft/vscode-extension-samples | -| `HaaLeo/publish-vs-code-extension` Action | 一键双市场发布 | GitHub Marketplace | +| `HaaLeo/publish-vs-code-extension` Action | Marketplace 发布 | GitHub Marketplace | **消费 `vscode.git` API 的声明**：`package.json` 加 `"extensionDependencies": ["vscode.git"]`；TS 类型复制 `git.d.ts` 入仓；运行时 `getExtension('vscode.git').activate().getAPI(1)`。 @@ -230,9 +230,9 @@ hyper-git/ ## 7. CI/CD 与发布策略 -- **发布渠道**：双市场（Marketplace + OpenVSX）。**立即**：`ovsx create-namespace ` 并 **claim ownership**（OpenVSX namespace 默认非排他，防抢注）。 +- **发布渠道**：VS Code Marketplace 单市场（`vsce publish`，`ENABLE_MARKETPLACE_PUBLISH` 变量门控，`rc` tag 走 `--pre-release` 预发布通道）；每个 `v*` tag 附 `.vsix` GitHub Release 作兜底安装。 - **publisher / 扩展 id**：扩展显示名 **Hyper Git**，id `hyper-git`；publisher 建议与 git owner 一致取 `threefish-ai`（**待你最终确认 publisher id**，创建后不可改）。 -- **CI 流水线**（`.github/workflows/ci.yml`）：`push/PR → lint→build→test 矩阵(ubuntu/mac/win, Linux 用 xvfb-run -a) → package vsix(Linux 打包保 POSIX 位) → upload artifact`；`tag v* → publish(vsce + ovsx, environment:production 审批门, PAT as secret)`。PR 仅跑 ubuntu 单格快门，main/tag 跑全矩阵（控成本）。 +- **CI 流水线**（`.github/workflows/ci.yml`）：`push/PR → lint→build→test 矩阵(ubuntu/mac/win, Linux 用 xvfb-run -a) → package vsix(Linux 打包保 POSIX 位) → upload artifact`；`tag v* → publish(vsce, environment:production 审批门, VSCE_PAT as secret)`。PR 仅跑 ubuntu 单格快门，main/tag 跑全矩阵（控成本）。 - **版本治理**：Marketplace 版本不可撤销 → **快速补丁版本为唯一回滚范式**；pre-release 用奇数 minor 吸收 M5 AI 等高风险特性；CHANGELOG 用 Keep a Changelog 格式。 - **安全**：PAT 短过期(90d) + 最小 scope + 仅存 GitHub encrypted secret；action pin 到完整 commit SHA；启用 Dependabot + CodeQL + `pnpm audit`；AI/遥测默认关闭。 - **engines.vscode**：M0-M4 锁 `^1.85.0`（`@types/vscode:1.85.0` 严格对齐，让 tsc 拦截越界 API）；M5 评估上调以支持 LM/Chat API。 @@ -268,7 +268,7 @@ hyper-git/ 1. **建工作分支**（基于 `origin/feature/1.x.x`），创建 `package.json` + esbuild 骨架（复制官方 `esbuild-sample`），落地 M0。 2. **PoC 验证两个关键风险点**：(a) `extensionDependencies:["vscode.git"]` + `getAPI(1)` 拿到 `Repository` 读 `workingTreeChanges`；(b) WebviewView Commit 编辑器 `postMessage → Repository.commit()`。两项跑通即消除主要技术不确定性。 -3. **并行**：`ovsx create-namespace` + claim ownership（防抢注）；将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线，并同步 `.agents/knowledge-map.md` 索引。 +3. **并行**：将 Track1 的 56 功能矩阵固化为 `docs/requirements/idea-feature-matrix.md` 作为后续验收基线，并同步 `.agents/knowledge-map.md` 索引。 4. **提交规范**：按用户偏好，commit 用 `/commit` 命令；PR 基线为 `origin/feature/1.x.x`，不直接推 master。 --- @@ -289,4 +289,4 @@ hyper-git/ - AI 机制：[Language Model API](https://code.visualstudio.com/api/extension-guides/ai/language-model)、[Chat](https://code.visualstudio.com/api/extension-guides/ai/chat)、[Tools](https://code.visualstudio.com/api/extension-guides/ai/tools)、[BYOK Provider](https://code.visualstudio.com/api/extension-guides/ai/language-model-chat-provider) **发布生态** -- [eclipse/openvsx cli](https://github.com/eclipse/openvsx/blob/master/cli/README.md)、[Cursor 使用 OpenVSX](https://forum.cursor.com/t/cursor-marketplace-installs-offers-outdated-version-of-open-vsx-extension-despite-latest-version-being-available-upstream/159718)、[HaaLeo/publish-vs-code-extension](https://github.com/marketplace/actions/publish-vs-code-extension) +- [Publishing Extensions（官方）](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)、[HaaLeo/publish-vs-code-extension](https://github.com/marketplace/actions/publish-vs-code-extension) diff --git a/docs/features/commit-view-consolidation.md b/docs/features/commit-view-consolidation.md new file mode 100644 index 0000000..e3ec225 --- /dev/null +++ b/docs/features/commit-view-consolidation.md @@ -0,0 +1,37 @@ +# Commit 视图整合（移除 CHANGES，能力全量平移） + +> CHANGES 树视图与 Commit 视图顶部的「Active Changelist」展示同一份数据（同源 `service.getChanges()` + `registry.getGroups()`），属冗余。现移除 CHANGES 视图，其**全部独有能力零回归**平移入 Commit 视图，侧边栏视图数由 7 降为 6。 + +## 平移清单（零功能回归） + +| 原 CHANGES 能力 | 迁入 Commit 视图后的形态 | +|---|---| +| 文件单击看 Diff | 文件行单击（勾选框除外）→ `commit/openFile` → 复用 `hyperGit.openDiff` | +| 单文件右键菜单 | 文件行右键 → `commit/fileMenu` → 原生 `showQuickPick`：Open Diff / Move to Changelist… / Show History / Stage·Unstage Hunks… / Add to .gitignore / Discard Changes（复用既有命令，含 discard 确认框） | +| Changelist 管理 | 头部 `