From 9ca68b2d212f46994b3ba1553f5a8970f7faeb97 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Fri, 10 Jul 2026 23:22:58 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(AgentConfig):=20=E6=96=B0=E5=A2=9E=20h?= =?UTF-8?q?yperGit.agent.*=20=E5=9B=9B=E9=A1=B9=20Agentic=20Git=20?= =?UTF-8?q?=E5=81=8F=E5=A5=BD=E9=85=8D=E7=BD=AE(=E5=86=85=E7=BD=AE?= =?UTF-8?q?=E9=BB=98=E8=AE=A4=E6=A8=A1=E6=9D=BF);?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为 M5 AI 接缝铺路，追加四项声明式预置配置，仅承载「配置项 + 内置默认」， agent/ 五接缝与 hyperGit.ai.enabled 行为不变、零破坏： - hyperGit.agent.baseBranch：创建 PR 的基线分支(留空=仓库默认分支)。 - hyperGit.agent.commitPreferences / createPrPreferences / reviewPreferences： 分别为点击 Commit / Create PR / Review 时发送给 agent 的自定义指令， 以 editPresentation:"multilineText" 多行文本域承载并内置默认模板。 Commit 模板由中文提交规约译为专业英文(规约规定提交信息用中文，故示例与签名 块原样保留)；Create PR / Review 模板逐字内置(含 ${TARGET_BRANCH} / #{pr_number} 等占位符，运行时由宿主替换)。默认值内联于 package.json(VS Code 无「默认取自 文件」机制、.vscodeignore 排除除 media/ 外一切)。零新增命令 / TS / 测试; check-types / lint / 372 单元测试全绿。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- package.json | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/package.json b/package.json index 0bc0767..f07bcc3 100644 --- a/package.json +++ b/package.json @@ -1232,6 +1232,29 @@ "default": "", "markdownDescription": "Path to the Claude Code CLI executable used by Hyper Git's Agentic Git features. Leave empty to auto-detect the `claude` binary from your `PATH` (recommended).\n\n[Browse for executable…](command:hyperGit.setClaudeCodePath) · [Open Claude settings (`~/.claude/settings.json`)](command:hyperGit.openClaudeSettings)" }, + "hyperGit.agent.baseBranch": { + "type": "string", + "default": "", + "markdownDescription": "Base branch used as the baseline when creating a pull request. Leave empty to use the repository's default branch." + }, + "hyperGit.agent.commitPreferences": { + "type": "string", + "editPresentation": "multilineText", + "default": "---\ndescription: \"Commit changes to Git\"\n---\n\nCommit the project's file changes to Git, keeping the commit message clear and concise.\n\n## Workflow\n\n1. Before committing, pull the latest version of the current branch from the remote:\n\n ```bash\n git pull\n ```\n\n2. Commit the changes in well-planned batches with prepared commit messages.\n3. Run `git push` to push the current branch to the GitHub remote.\n\n## Notes\n\n- Do not modify the repository contents again at this point; deleting repository content (or files) is never allowed at any time.\n- When appropriate, split the commit into multiple batches by content category; for a file move, do not split it into separate delete and add operations — commit it as a single file-move operation.\n- Write commit messages in Chinese, using the following signature format:\n ```\n 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)\n Co-Authored-By: Aurelius Huang\n ```\n\n## Commit Message Convention\n\n```\n{Header}({Topic}): Commit Message;\n```\n\n- Header (Required): identifier for the type of change\n - feat: new feature\n - fix: bug fix\n - docs: documentation update\n - style: code-style change that does not affect behavior\n - refactor: change to existing logic\n - pref: performance optimization\n - test: test-case update\n - build: dependency update\n - ci: CI-related configuration change\n - chore: changes outside source and test code\n - revert: revert previous commits\n- Topic (Required): the subject, module, or feature name of the change; **use a short English label**.\n- Commit Message: a summary of the change; **describe it in Chinese**.\n\nExample:\n\n```\nci(Jenkins): 修改配置文件以支持 staging 环境;\n```", + "markdownDescription": "Custom instructions sent to the agent when you click the Commit button." + }, + "hyperGit.agent.createPrPreferences": { + "type": "string", + "editPresentation": "multilineText", + "default": "The user likes the current state of the code.\n\nThere are 3 uncommitted changes.\nThe current branch is ${YOUR_BRANCH}.\nThe target branch is origin/${TARGET_BRANCH}.\nAn upstream branch exists.\n\nThe user requested a PR.\n\nFollow these steps to create a PR:\n\nIf you have any skills related to creating PRs, invoke them now. Instructions there should take precedence over these instructions.\nRun git diff to review uncommitted changes\nCommit them. Follow any instructions the user gave you about writing commit messages.\nPush with git push -u origin HEAD:${YOUR_BRANCH}.\nUse the mcp__conductor__GetWorkspaceDiff tool to review the PR diff\nUse gh pr create --base ${TARGET_BRANCH} --title --body <description> to create a PR onto the target branch.\nIf any of these steps fail, ask the user for help.\n\nPR Title\n\nThe user has provided this PR title. Use it exactly as-is:\n${PR_TITLE}\n\nPR Description\n\nThe user has provided this PR description. Use it exactly as-is:\n${PR_DESCRIPTION}\n\nIMPORTANT: The following are the user's custom preferences. These preferences take precedence over any default guidelines or instructions provided above. When there is a conflict, always follow the user's preferences.\n\nUser Preferences\n\nUpdate the PR that was just created with a better title and description. The PR number is #{pr_number} and the URL is {pr_url}.\nAnalyze the changes in this branch and write:\n\nA concise, descriptive title that summarizes the changes, follow the commit message format specified in ~/.claude/commands/commit.md\nA detailed description that explains:\nWhat changes were made\nWhy they were made (based on the task context)\nAny important implementation details\nUse the appropriate CLI tool to update the PR (gh pr edit for GitHub, az repos pr update for Azure DevOps).", + "markdownDescription": "Custom instructions sent to the agent when you click the Create PR button." + }, + "hyperGit.agent.reviewPreferences": { + "type": "string", + "editPresentation": "multilineText", + "default": "Review guidelines:\n\nYou are acting as a reviewer for a proposed code change made by another engineer.\n\nBelow are some default guidelines for determining whether the original author would appreciate the issue being flagged.\n\nThese are not the final word in determining whether an issue is a bug. In many cases, you will encounter other, more specific guidelines. These may be present elsewhere in a developer message, a user message, a file, or even elsewhere in this system message.\nThose guidelines should be considered to override these general instructions.\n\nHere are the general guidelines for determining whether something is a bug and should be flagged.\n\nIt meaningfully impacts the accuracy, performance, security, or maintainability of the code.\nThe bug is discrete and actionable (i.e. not a general issue with the codebase or a combination of multiple issues).\nFixing the bug does not demand a level of rigor that is not present in the rest of the codebase (e.g. one doesn’t need very detailed comments and input validation in a repository of one-off scripts in personal projects)\nThe bug was introduced in the commit (pre-existing bugs should not be flagged).\nThe author of the original PR would likely fix the issue if they were made aware of it.\nThe bug does not rely on unstated assumptions about the codebase or author’s intent.\nIt is not enough to speculate that a change may disrupt another part of the codebase, to be considered a bug, one must identify the other parts of the code that are provably affected.\nThe bug is clearly not just an intentional change by the original author.\nWhen flagging a bug, you will also provide an accompanying comment. Once again, these guidelines are not the final word on how to construct a comment — defer to any subsequent guidelines that you encounter.\n\nThe comment should be clear about why the issue is a bug.\nThe comment should appropriately communicate the severity of the issue. It should not claim that an issue is more severe than it actually is.\nThe comment should be brief. The body should be at most 1 paragraph. It should not introduce line breaks within the natural language flow unless it is necessary for the code fragment.\nThe comment should not include any chunks of code longer than 3 lines. Any code chunks should be wrapped in markdown inline code tags or a code block.\nThe comment should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue’s severity depends on these factors.\nThe comment’s tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.\nThe comment should be written such that the original author can immediately grasp the idea without close reading.\nThe comment should avoid excessive flattery and comments that are not helpful to the original author. The comment should avoid phrasing like “Great job …”, “Thanks for …”.\nBelow are some more detailed guidelines that you should apply to this specific review.\n\nHOW MANY FINDINGS TO RETURN:\n\nOutput all findings that the original author would fix if they knew about it. If there is no finding that a person would definitely love to see and fix, prefer outputting no findings. Do not stop at the first qualifying finding. Continue until you’ve listed every qualifying finding.\n\nGUIDELINES:\n\nIgnore trivial style unless it obscures meaning or violates documented standards.\nUse one comment per distinct issue (or a multi-line range if necessary).\nUse ```suggestion blocks ONLY for concrete replacement code (minimal lines; no commentary inside the block).\nIn every ```suggestion block, preserve the exact leading whitespace of the replaced lines (spaces vs tabs, number of spaces).\nDo NOT introduce or remove outer indentation levels unless that is the actual fix.\nThe comments will be presented in the code review as inline comments. You should avoid providing unnecessary location details in the comment body. Always keep the line range as short as possible for interpreting the issue. Avoid ranges longer than 5–10 lines; instead, choose the most suitable subrange that pinpoints the problem.\n\nGetting the diff\n\nUse the mcp__conductor__GetWorkspaceDiff tool to review the workspace diff. Start with stat: true to understand the files that changed, then request specific files as needed.\n\nFallback: if you don’t have access to the workspace diff tool\n\nIf you don’t have access to the mcp__conductor__GetWorkspaceDiff tool, use the following git commands to get the diff:\n\n# Get the merge base between this branch and the target\nMERGE_BASE=$(git merge-base origin/${TARGET_BRANCH} HEAD)\n\n# Get the committed diff against the merge base\ngit diff $MERGE_BASE HEAD\n\n# Get any uncommitted changes (staged and unstaged)\ngit diff HEAD\nReview the combination of both outputs: the first shows all committed changes on this branch relative to the target, and the second shows any uncommitted work in progress.\n\nNo need to mention in your report whether or not you used one of the fallback strategies; it’s usually irrelevant.\n\nOutput format\n\nPost inline comments for each issue using mcp__conductor__DiffComment:\n\nIMPORTANT: Only post ONE comment per unique issue.\n\nWrite out a list of issues found, along with the location of the comment. For example:\n\n### **#1 Empty input causes crash**\nIf the input field is empty when page loads, the app will crash.\n\nFile: src/client/frontends/desktop/ui/Input.tsx\n\n#2 Dead code\nThe getUserData function is now unused. It should be deleted.\n\nFile: src/client/frontends/desktop/core/UserData.ts", + "markdownDescription": "Custom instructions sent to the agent when you click the Review button." + }, "hyperGit.log.ci.enabled": { "type": "boolean", "default": true, From ed228606add4873b8ad3deba19f4f4c3806369c3 Mon Sep 17 00:00:00 2001 From: ThreeFish <aureliusshu@gmail.com> Date: Fri, 10 Jul 2026 23:23:08 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(AgentConfig):=20=E6=96=B0=E5=A2=9E=20A?= =?UTF-8?q?gentic=20Git=20=E5=81=8F=E5=A5=BD=E9=85=8D=E7=BD=AE=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E6=96=87=E6=A1=A3=E5=B9=B6=E5=90=8C=E6=AD=A5=E6=8C=87?= =?UTF-8?q?=E6=A0=87/=E8=AE=BE=E8=AE=A1/CHANGELOG;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增功能文档 docs/features/agentic-git-preferences.md(概述/设计 Mermaid/ 配置表/内置默认说明/与 Agentic Git 关系/验证)，并登记至文档中心与知识索引。 - README 双语指标校准 7 → 11 配置项(commands 101 / views 6 / tests 372 不变)， 并在 AI 接缝段补 hyperGit.agent.* 偏好说明。 - 设计文档就近续写：engineering-plan §6、implementation-status §5 的 pre-M5 注记补本轮四项偏好配置。 - CHANGELOG Unreleased 补 Added 条目。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com> --- CHANGELOG.md | 1 + README.md | 4 +- docs/.agents/knowledge-map.md | 1 + docs/README.md | 1 + docs/architecture/engineering-plan.md | 2 +- docs/features/agentic-git-preferences.md | 61 ++++++++++++++++++++++++ docs/i18n/zh-CN/README.md | 4 +- docs/milestones/implementation-status.md | 2 +- 8 files changed, 70 insertions(+), 6 deletions(-) create mode 100644 docs/features/agentic-git-preferences.md diff --git a/CHANGELOG.md b/CHANGELOG.md index dd1b997..924ae8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ ### Added +- **Agentic Git 偏好配置（Agentic Git 预置）**：新增 `hyperGit.agent.*` 四项配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① `hyperGit.agent.baseBranch`（创建 PR 的基线分支，留空=仓库默认分支）；②③④ `commitPreferences` / `createPrPreferences` / `reviewPreferences`（分别为点击 **Commit / Create PR / Review** 时发送给 agent 的自定义指令，均以 `editPresentation: "multilineText"` 多行文本域承载、**内置默认模板**）。其中 **Commit 模板由中文提交规约译为专业英文**（规约规定提交信息用中文，故示例与签名块原样保留）；Create PR / Review 模板**逐字内置**（含 `${TARGET_BRANCH}` / `#{pr_number}` 等占位符）。采用**原生设置**承载（零新增 Webview / 命令 / TS / 测试），默认值内联于 [`package.json`](./package.json)。**仅落地配置与内置默认**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。README 指标行同步 `7 → 11 配置项`。完整叙述见 [Agentic Git 偏好配置](./docs/features/agentic-git-preferences.md)。 - **Claude Code 配置（Agentic Git 预置）**：新增两项与 Claude Code 相关的配置为 M5 [AI 接缝](./docs/research/05-ai-agent-seams.md) 铺路——① 设置项 `hyperGit.claudeCode.executablePath`（Claude Code CLI 可执行路径，**留空=从 `PATH` 自动探测 `claude`**；描述内嵌 `command:` 链接就地提供「浏览 / 打开 Claude 设置」）；② 命令 `hyperGit.setClaudeCodePath`（QuickPick：Browse 文件选择器写回 / **Use system Claude Code** 清空覆盖）与 `hyperGit.openClaudeSettings`（打开 `~/.claude/settings.json`，缺失时经确认创建 `{}`）。采用**原生设置 + 命令**承载（零新增 Webview 面板），路径解析下沉纯函数 [`engine/agent/claude-path.ts`](./src/engine/agent/claude-path.ts)（Vitest 可测），命令实现见 [`adapter/claude-commands.ts`](./src/adapter/claude-commands.ts)。**仅落地配置与快捷入口**，`agent/` 五接缝与 `hyperGit.ai.enabled` 行为不变、零破坏。同步校正 README 指标行（`6 视图 · 101 命令 · 7 配置项 · 372 单元测试`，此前 `97 命令 / 324 测试` 已滞后 HEAD）。完整叙述见 [Claude Code 配置](./docs/features/claude-code-config.md)。 - **Branches 视图按 `/` 前缀分组为文件夹树**：Local / Remote / Tags 三段支持在**平铺**与**按 `/` 前缀分组的可折叠文件夹树**间切换——共享前缀的分支收拢到以前缀命名的文件夹下、叶子仅显示末段后缀（如 `bak/2025`、`bak/master-2025-07` → 📁`bak` → `2025` / `master-2025-07`；远程整体收拢为 `origin` 文件夹并内嵌 `feature`）。新增纯逻辑引擎 [`buildRefTree`](./src/engine/ref/ref-tree.ts)（复用「变更文件目录树」`buildFileTree` 的 trie 构建 + compact 折叠范式；叶子携完整 `RawRef`、命令定位不受影响；分支感知排序：当前 HEAD → 收藏 → 同档文件夹优先、名称数字感知升序），并**隐藏 `origin/HEAD` 符号引用**（对齐主流 Git UI，消除 `origin` 叶子与 `origin` 文件夹同名冲突）。工具栏提供「平铺 ⇄ 树」切换（`hyperGit.branchesGroupByPrefix` / `hyperGit.branchesFlatten`，context key 驱动按钮互斥），偏好按仓库持久化于 `workspaceState`（默认树形），文件夹默认展开、展开态跨刷新稳定。文件夹节点用独立 `contextValue` 且不登记任何右键命令，checkout / delete / rename / merge / rebase / compare / favorite 与多选批量均零改动、零破坏。完整叙述见 [分支前缀分组树](./docs/features/branch-tree-group-by-prefix.md)。 diff --git a/README.md b/README.md index dea9a6b..cfee9e6 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ <b>English</b> · <a href="./docs/i18n/zh-CN/README.md">简体中文</a> </p> -<p align="center"><sub>6 views · 101 commands · 7 settings · 372 unit tests</sub></p> +<p align="center"><sub>6 views · 101 commands · 11 settings · 372 unit tests</sub></p> ## Features @@ -40,7 +40,7 @@ - **Consumes** the stable `Repository` API exported by the built-in `vscode.git` extension as its Git foundation, rather than rebuilding a Git state machine. - **Controlled CLI channel**: capabilities the stable API does not cover (cherry-pick / revert / reset / branch rename / hunk staging / stash listing / graph topology / shelf, etc.) run through `GitRepositoryService.execGit`, reusing the same Git binary (`api.git.path`). - **Hand-rendered views** carry the full change-management UI (webviews live under `adapter/webview/`); pure logic is distilled into `engine/` (zero `vscode` dependency, unit-testable). -- **AI seams**: 5 interfaces (`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`) are reserved (design inspired by JetBrains' `CheckinHandler` commit lifecycle), currently shipped as Null implementations; the full implementation is deferred to M5. As pre-M5 groundwork, a **Claude Code executable path** setting (`hyperGit.claudeCode.executablePath`) and a **`~/.claude/settings.json` shortcut** are already configurable — see [Claude Code configuration](./docs/features/claude-code-config.md). +- **AI seams**: 5 interfaces (`ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver`) are reserved (design inspired by JetBrains' `CheckinHandler` commit lifecycle), currently shipped as Null implementations; the full implementation is deferred to M5. As pre-M5 groundwork, a **Claude Code executable path** setting (`hyperGit.claudeCode.executablePath`) and a **`~/.claude/settings.json` shortcut** are already configurable — see [Claude Code configuration](./docs/features/claude-code-config.md); plus **`hyperGit.agent.*` preferences** (base branch + Commit / Create PR / Review agent instructions) — see [Agentic Git preferences](./docs/features/agentic-git-preferences.md). <p align="center"> <img src="media/framework.png" alt="Framework"/> diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md index d2621a8..2993b82 100644 --- a/docs/.agents/knowledge-map.md +++ b/docs/.agents/knowledge-map.md @@ -23,6 +23,7 @@ - [分支前缀分组树](../docs/features/branch-tree-group-by-prefix.md) — Branches 视图 Local/Remote/Tags「平铺 ⇄ 按 `/` 前缀分组」切换：`buildRefTree` 构树、分支感知排序、compact 折叠、隐藏 `origin/HEAD`、按仓库持久化。 - [Log 提交悬浮详情](../docs/features/log-commit-tooltip.md) — 悬停提交行浮层展示 分支/标签/HEAD/完整消息/作者·提交者/时间/SHA；复用 CI 浮层范式、与其互斥。 - [Claude Code 配置](../docs/features/claude-code-config.md) — Agentic Git 预置：`hyperGit.claudeCode.executablePath` 设置 + `~/.claude/settings.json` 快捷入口（原生设置 + 命令；纯路径逻辑沉淀 `engine/agent/`）。 +- [Agentic Git 偏好配置](../docs/features/agentic-git-preferences.md) — Agentic Git 预置：`hyperGit.agent.*` 四项（baseBranch + commit/createPr/review Preferences；多行文本域 + 内置默认模板，Commit 模板中文规约已英译）。 - [实施状态总览](../docs/milestones/implementation-status.md) — M0-M5 交付记录 + API 限制 + M5 AI 设计 + 验证/发布（**实施看板**）。 - [工程实施方案](../docs/architecture/engineering-plan.md) — 路径 B 架构 + M0-M5 里程碑（**开发蓝图**）。 - [Git 功能矩阵](../docs/requirements/idea-feature-matrix.md) — 56 功能点 / 8 组（**验收基线**，参考 IDEA 等成熟实现）。 diff --git a/docs/README.md b/docs/README.md index 774651e..412cd87 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ ## 功能文档 - [Log 视图 CI 状态](./features/log-ci-status.md) — 按提交显示 GitHub CI 最终状态（绿勾/红叉 + 悬停 Tooltip 明细）：认证、限流、懒加载、边界与配置。 - [Claude Code 配置](./features/claude-code-config.md) — Agentic Git 预置：Claude Code 可执行路径设置 + `~/.claude/settings.json` 快捷入口（原生设置 + 命令；M5 前置铺垫）。 +- [Agentic Git 偏好配置](./features/agentic-git-preferences.md) — Agentic Git 预置：Base Branch + Commit / Create PR / Review 三项 agent 指令偏好（多行文本域 + 内置默认模板；M5 前置铺垫）。 ## 发布说明 - [Release Notes 目录](./releases/README.md) — 各正式版发布说明（GitHub Release 正文单一事实源）；最新：[v0.0.14 修复 GRAPH 视图提交记录时间倒序](./releases/v0.0.14.md)。 diff --git a/docs/architecture/engineering-plan.md b/docs/architecture/engineering-plan.md index 852d392..e183b71 100644 --- a/docs/architecture/engineering-plan.md +++ b/docs/architecture/engineering-plan.md @@ -226,7 +226,7 @@ hyper-git/ **Commit 流水线 hook 注入点**（M2 即建责任链，默认 Null hooks）： `staged diff → [Hook A: 提交信息生成] → message 定稿 → [Hook B: 提交前检查链=beforeCheckin] → [Hook C: 分组校验] → commit → [Hook D: checkinSuccessful] → push → [Hook E: checkinFailed→Hook F: 冲突解决]` -**pre-M5 已落地（配置铺垫）**：新增 `hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）与 `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置——仅承载「配置 + 快捷入口」，接缝仍 Null、`hyperGit.ai.enabled` 行为不变；M5 时 `ILlmProvider` 等将读取该路径定位 CLI。详见 [Claude Code 配置](../features/claude-code-config.md)。 +**pre-M5 已落地（配置铺垫）**：新增 `hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）与 `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置——仅承载「配置 + 快捷入口」，接缝仍 Null、`hyperGit.ai.enabled` 行为不变；M5 时 `ILlmProvider` 等将读取该路径定位 CLI。详见 [Claude Code 配置](../features/claude-code-config.md)。另新增 `hyperGit.agent.*` 四项偏好（`baseBranch` + `commit`/`createPr`/`review` Preferences，多行文本域 + 内置默认模板），M5 时作为对应动作发送给 agent 的指令与 PR 基线；详见 [Agentic Git 偏好配置](../features/agentic-git-preferences.md)。 --- diff --git a/docs/features/agentic-git-preferences.md b/docs/features/agentic-git-preferences.md new file mode 100644 index 0000000..55417a3 --- /dev/null +++ b/docs/features/agentic-git-preferences.md @@ -0,0 +1,61 @@ +# Agentic Git 偏好配置（Base Branch · Commit / Create PR / Review 指令） + +> 为 **Agentic Git**（M5 AI Agent 能力）预置的四项 `hyperGit.agent.*` 配置：一项 **Base Branch**（创建 PR 的基线分支），三项 **偏好指令**——分别在点击 **Commit / Create PR / Review** 时作为自定义指令发送给 agent。三项偏好均内置默认模板（VS Code 多行文本域，未修改即显示默认、可随时编辑或 `Reset Setting` 复位）。 +> 本次仅落地「配置项 + 内置默认」；真正消费这些偏好留待 M5 [AI 接缝](../research/05-ai-agent-seams.md) 实装，当前 `agent/` 五接缝仍为 Null、`hyperGit.ai.enabled` 行为不变、零破坏。 + +## 设计 + +采用**原生 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.baseBranch` | `string` | `""` | 创建 PR 时的基线分支；**留空 = 使用仓库默认分支**。 | +| `hyperGit.agent.commitPreferences` | `string`（多行） | 内置 Commit 模板 | 点击 **Commit** 时发送给 agent 的自定义指令。 | +| `hyperGit.agent.createPrPreferences` | `string`（多行） | 内置 Create PR 模板 | 点击 **Create PR** 时发送给 agent 的自定义指令。 | +| `hyperGit.agent.reviewPreferences` | `string`（多行） | 内置 Review 模板 | 点击 **Review** 时发送给 agent 的自定义指令。 | + +## 内置默认 + +- **Commit 模板**：源自中文的提交规约，已**译为专业英文**（Workflow / Notes / Commit Message Convention）；规约本身规定「提交信息用中文」，故示例（`ci(Jenkins): 修改配置文件以支持 staging 环境;`）与签名块**原样保留**以如实演示该规则。 +- **Create PR 模板**：**逐字内置**创建 PR 的工作流指令，含占位符 `${YOUR_BRANCH}` / `${TARGET_BRANCH}` / `${PR_TITLE}` / `${PR_DESCRIPTION}` / `#{pr_number}` / `{pr_url}`（运行时由宿主替换），末段用户偏好优先级最高。 +- **Review 模板**：**逐字内置**代码评审准则（判定「是否为需上报的 bug」的标准、评论撰写规范、`mcp__conductor__GetWorkspaceDiff` 取 diff 与 `git merge-base origin/${TARGET_BRANCH} HEAD` 兜底、`mcp__conductor__DiffComment` 输出格式）。 + +## 实现 + +- 契约：[`package.json`](../../package.json) — `contributes.configuration.properties` 新增四项 `hyperGit.agent.*`（置于 `hyperGit.claudeCode.executablePath` 之后）。 +- 无新增命令 / TS / 单测（纯声明式配置；图中仅文本域，Base Branch 为文本输入）。 + +## 与 Agentic Git 的关系 + +与 [Claude Code 配置](./claude-code-config.md) 同属 M5 **pre-M5 预置**：仅定义配置与内置默认，不改变现有行为。M5 启动后，Commit / PR / Review 相关接缝将读取对应偏好作为 agent 指令、并以 `baseBranch` 作为 PR 基线。相关设计见 [AI Agent 架构预留](../research/05-ai-agent-seams.md) 与 [实施状态总览](../milestones/implementation-status.md)。 + +## 验证 + +1. `node -e "require('./package.json')"` JSON 合法；`contributes.configuration.properties` 计数为 **11**。 +2. `pnpm run check-types` + `pnpm run lint` + `pnpm run test:unit` 全绿（无 TS/测试改动，回归 372 用例）。 +3. Extension Development Host（F5）：设置搜索 `hyperGit.agent` → 见四项；三项偏好呈**多行文本域并默认显示内置模板**，`Base Branch` 为文本输入；编辑后经齿轮 `Reset Setting` 可复位默认。 diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index c63ed2f..67883e3 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -16,7 +16,7 @@ <a href="../../../README.md">English</a> · <b>简体中文</b> </p> -<p align="center"><sub>6 视图 · 101 命令 · 7 配置项 · 372 单元测试</sub></p> +<p align="center"><sub>6 视图 · 101 命令 · 11 配置项 · 372 单元测试</sub></p> ## 核心能力 @@ -40,7 +40,7 @@ - **消费** 内置 `vscode.git` 导出的稳定 `Repository` API 作为 git 底座，不重造 git 状态机。 - **受控 CLI 通道**：稳定 API 未覆盖的能力（cherry-pick / revert / reset / 分支重命名 / hunk 暂存 / stash 列表 / graph 拓扑 / shelf 等）经 `GitRepositoryService.execGit` 复用同一 git 二进制（`api.git.path`）实现。 - **自绘视图** 承载完整的变更管理 UI（Webview 位于 `adapter/webview/`）；纯逻辑沉淀于 `engine/`（零 vscode 依赖、可单测）。 -- **AI 接缝**：预留 `ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver` 共 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），当前以 Null 实现交付，完整实现延后至 M5。作为 M5 前置铺垫，已可配置 **Claude Code 可执行路径**（`hyperGit.claudeCode.executablePath`）与 **`~/.claude/settings.json` 快捷入口**——详见 [Claude Code 配置](../../features/claude-code-config.md)。 +- **AI 接缝**：预留 `ILlmProvider` / `ICommitMessageProvider` / `IPreCommitInspector` / `IChangelistGrouper` / `IConflictResolver` 共 5 个接口（设计参考 JetBrains `CheckinHandler` 提交生命周期），当前以 Null 实现交付，完整实现延后至 M5。作为 M5 前置铺垫，已可配置 **Claude Code 可执行路径**（`hyperGit.claudeCode.executablePath`）与 **`~/.claude/settings.json` 快捷入口**（详见 [Claude Code 配置](../../features/claude-code-config.md)），以及 **`hyperGit.agent.*` 偏好**（基线分支 + Commit / Create PR / Review 的 agent 指令，详见 [Agentic Git 偏好配置](../../features/agentic-git-preferences.md)）。 <p align="center"> <img src="../../../media/framework.png" alt="Framework"/> diff --git a/docs/milestones/implementation-status.md b/docs/milestones/implementation-status.md index 5282ee0..bcde676 100644 --- a/docs/milestones/implementation-status.md +++ b/docs/milestones/implementation-status.md @@ -96,7 +96,7 @@ **M5 启动前置**：`engines.vscode` 上调以支持 LM/Chat API；opt-in 配置开关；模型来源可切换。 -**pre-M5 已落地（配置铺垫）**：`hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）+ `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置已交付——仅承载配置与快捷入口，接缝仍 Null、`hyperGit.ai.enabled` 行为不变。详见 [Claude Code 配置](../features/claude-code-config.md)。 +**pre-M5 已落地（配置铺垫）**：`hyperGit.claudeCode.executablePath`（Claude Code CLI 路径，留空=`PATH` 自动探测）+ `Open Claude Settings`（`~/.claude/settings.json` 快捷入口）两项配置已交付——仅承载配置与快捷入口，接缝仍 Null、`hyperGit.ai.enabled` 行为不变。详见 [Claude Code 配置](../features/claude-code-config.md)。另交付 `hyperGit.agent.*` 四项偏好（`baseBranch` + `commit`/`createPr`/`review` Preferences，多行文本域 + 内置默认模板，Commit 中文规约已英译），M5 时作为对应动作的 agent 指令与 PR 基线；详见 [Agentic Git 偏好配置](../features/agentic-git-preferences.md)。 ## 6. 验证体系