hve-core-installer

HVE-Core 安装器技能

面向决策的 HVE-Core 安装器，包含环境检测、6 种基于克隆的安装方法、扩展快速安装、验证、MCP 配置以及选择性组件安装工作流。

角色定义

以两个协作角色运行：

• 安装器角色检测环境、引导选择方法并执行安装步骤
• 验证器角色通过检查路径、设置和 Agent 可访问性来验证安装是否成功

安装器角色负责所有检测和执行工作。安装完成后，切换到验证器角色，在报告完成之前验证安装是否成功。

重新运行行为： 再次运行安装器时，会验证现有安装或提供升级选项。可随时安全地重新运行。

必需阶段

阶段	名称	用途
1	环境检测	征求用户同意并检测用户的环境
2	安装路径选择	在扩展（快速）安装和基于克隆的安装之间进行选择
3	环境检测与决策矩阵	对于克隆路径：检测环境并推荐安装方法
4	安装方法	执行选定的安装方法
5	验证	验证安装是否成功并配置设置
6	安装后设置	配置 gitignore 并提供 MCP 指引
7	组件安装	可选：复制所选组件以供本地使用（仅限基于克隆的安装）

流程路径：

• 扩展路径：阶段 1 → 阶段 2 → 阶段 6 → 完成
• 基于克隆的路径：阶段 1 → 阶段 2 → 阶段 3 → 阶段 4 → 阶段 5 → 阶段 6 → 阶段 7 → 完成

阶段 1：环境检测

在提供选项之前，检测用户的环境，以筛选适用的安装方法。

检查点 1：初始同意

显示以下内容并等待用户明确同意：

🚀 HVE-Core Installer

I'll help you install HVE-Core agents, instructions and skills.

Available content:
• Specialized agents, including RPI Agent, Documentation, and domain planners
• Technology-specific coding instructions (bash, python, markdown, etc.)
• Domain-specific skills (pr-reference, etc.)

I'll ask 2-3 questions to recommend the best installation method for your setup.

Would you like to proceed?

如果用户拒绝，请回复：“已取消安装。你可以随时调用此技能以重新开始。”

获得同意后，进入阶段 2，提供安装路径选择。

阶段 2：安装路径选择

在检测环境之前，先提供安装路径选择。安装扩展无需选择 shell 或检测环境。

检查点 2：安装路径选择

显示以下选项：

🚀 Choose Your Installation Path

**Option 1: Quick Install (Recommended)**
Install the HVE Core extension from VS Code Marketplace.
• ⏱️ Takes about 10 seconds
• 🔄 Automatic updates
• ✅ No configuration needed

**Option 2: Clone-Based Installation**
Clone HVE-Core repository for customization.
• 🎨 Full customization support
• 📁 Files visible in your workspace
• 🤝 Team version control options

Which would you prefer? (1/2 or quick/clone)

用户输入处理：

• “1”、“quick”、“extension”、“marketplace” → 执行扩展安装
• “2”、“clone”、“custom”、“team” → 继续到阶段 3（环境检测）
• 回复不明确 → 请求澄清

如果用户选择选项 1（快速安装）：

1. 执行扩展安装（参见下文的扩展安装执行）
2. 验证安装是否成功
3. 显示成功报告或提供备用选项

如果用户选择选项 2（基于克隆的安装）：

• 询问：“你希望使用哪种 shell？（powershell/bash）”
• Shell 检测规则：
  • “powershell”、“pwsh”、“ps1”、“ps” → PowerShell
  • “bash”、“sh”、“zsh” → Bash
  • 回复不明确 → Windows 使用 PowerShell，macOS/Linux 使用 Bash
• 继续进行前置条件检查，然后运行环境检测脚本并进入阶段 3 工作流

适合选择克隆而非扩展的情况：

• 需要自定义 Agent、指令或技能
• 团队需要使用受版本控制的 HVE-Core
• 处于离线或隔离环境

前置条件检查

在基于克隆的安装之前，请确认 git 可用：

• 运行：git --version
• 如果失败：「基于克隆的安装需要 Git。请安装 git，或选择扩展快速安装。」

当用户选择 Bash 时，还要确认 jq 可用：

• 运行：jq --version
• 如果失败：「Bash 组件脚本需要 jq。请安装 jq，或选择 PowerShell。」

扩展安装执行

当用户选择快速安装时，首先询问他们使用的是哪个 VS Code 版本：

Which VS Code variant are you using?

  [1] VS Code (stable)
  [2] VS Code Insiders

Your choice? (1/2)

用户输入处理：

• 「1」、「code」、「stable」→ 使用 code CLI
• 「2」、「insiders」、「code-insiders」→ 使用 code-insiders CLI
• 回复不明确 → 请求澄清

将用户的选择存储为 code_cli 变量，以供验证脚本使用。

显示进度消息：

📥 Installing HVE Core extension from marketplace...

Note: You may see a trust confirmation dialog if this is your first extension from this publisher.

执行 VS Code CLI 命令：

<code_cli> --install-extension ise-hve-essentials.hve-core

命令执行后，继续进行扩展验证。

扩展验证

根据检测到的平台运行相应的验证脚本（Windows = PowerShell，macOS/Linux = Bash）。使用用户之前选择的 code_cli 值（code 或 code-insiders）。

**PowerShell：**运行 scripts/validate-extension.ps1，并设置 code_cli 变量。

**Bash：**运行 scripts/validate-extension.sh，并设置 code_cli 变量。

扩展成功报告

验证成功后，显示：

✅ Extension Installation Complete!

The HVE Core extension has been installed from the VS Code Marketplace.

📦 Extension: ise-hve-essentials.hve-core
📌 Version: [detected version]
🔗 Marketplace: https://marketplace.visualstudio.com/items?itemName=ise-hve-essentials.hve-core

🧪 Available Agents:
• rpi-agent, documentation, backlog-manager, and adr-creation
• code-review, security-planner, ux-ui-designer, and more!

🪝 Hooks (manual step): The Marketplace extension is declarative and does not
  write chat.hookFilesLocations. To enable the bundled telemetry hook, add its
  folder to that setting yourself, or use a clone-based or CLI plugin install
  that documents this configuration.

📋 Configuring optional settings...

显示扩展成功报告后，继续阶段 6：安装后设置，配置 gitignore 和 MCP。

扩展错误恢复

如果扩展安装失败，请提供有针对性的指导：

错误情形	用户消息	恢复操作
拒绝信任对话框	「安装已取消。您可能拒绝了发布者信任提示。」	提供重试或切换到克隆安装方法
网络故障	「无法连接到 VS Code Marketplace。请检查网络连接。」	提供重试或 CLI 替代方案
组织策略阻止	「组织策略可能限制了扩展安装。」	提供用于手动安装的 CLI 命令
未知故障	「扩展安装意外失败。」	提供基于克隆的安装作为备用方案

失败后的流程控制：

如果扩展安装失败且用户无法解决：

• 提供选项：「是否要尝试基于克隆的安装方法？（是/否）」
• 如果是：继续运行环境检测脚本并执行阶段 3 工作流
• 如果否：结束会话并提供手动安装说明

环境检测脚本

根据用户使用的 shell 运行相应的检测脚本：

**PowerShell：**运行 scripts/detect-environment.ps1

**Bash：**运行 scripts/detect-environment.sh

阶段 3：环境检测与决策矩阵

根据检测到的环境，询问以下问题以确定推荐的方法。

问题 1：环境确认

根据检测结果筛选选项：

### Question 1: What's your development environment?

Based on my detection, you appear to be in: [DETECTED_ENV_TYPE]

Please confirm or correct:

| Option | Description                               |
|--------|-------------------------------------------|
| **A**  | 💻 Local VS Code (no devcontainer)        |
| **B**  | 🐳 Local devcontainer (Docker Desktop)    |
| **C**  | ☁️ GitHub Codespaces only                 |
| **D**  | 🔄 Both local devcontainer AND Codespaces |

Which best describes your setup? (A/B/C/D)

问题 2：团队或个人

### Question 2: Team or solo development?

| Option   | Description                                                   |
|----------|---------------------------------------------------------------|
| **Solo** | Solo developer - no need for version control of HVE-Core      |
| **Team** | Multiple people - need reproducible, version-controlled setup |

Are you working solo or with a team? (solo/team)

问题 3：更新偏好

仅当环境和团队回答匹配多种方法时，才询问此问题：

### Question 3: Update preference?

| Option         | Description                                   |
|----------------|-----------------------------------------------|
| **Auto**       | Always get latest HVE-Core on rebuild/startup |
| **Controlled** | Pin to specific version, update explicitly    |

How would you like to receive updates? (auto/controlled)

决策矩阵

使用此矩阵确定推荐的方法：

环境	团队	更新	推荐方法
任意（最简单）	任意	-	扩展快速安装（适用于所有环境）
本地（无容器）	独立	-	方法 1：同级克隆
本地（无容器）	团队	受控	方法 6：子模块
本地 devcontainer	独立	自动	方法 2：Git 忽略
本地 devcontainer	团队	受控	方法 6：子模块
仅限 Codespaces	独立	自动	方法 4：Codespaces
仅限 Codespaces	团队	受控	方法 6：子模块
本地和 Codespaces 均适用	任意	任意	方法 5：多根工作区
HVE-Core 仓库（Codespaces）	-	-	方法 4：Codespaces（已配置）

方法选择逻辑

收集答案后：

1. 根据决策矩阵匹配答案
2. 给出建议并说明理由
3. 如果用户偏好其他方案，提供替代方案

## 📋 Your Recommended Setup

Based on your answers:
* **Environment**: [answer]
* **Team**: [answer]
* **Updates**: [answer]

### ✅ Recommended: Method [N] - [Name]

**Why this fits your needs:**
* [Benefit 1 matching their requirements]
* [Benefit 2 matching their requirements]
* [Benefit 3 matching their requirements]

Would you like to proceed with this method, or see alternatives?

阶段 4：安装方法

references/installation-methods.md 中完整记录了每种受支持的安装路径。选择上方决策矩阵确定的路径，并按照该文件中的说明操作。如果无法访问该文件，请告知用户无法继续所选方法的安装，并停止操作，不要自行编造步骤。

阶段 5：验证（验证者角色）

安装完成后，切换到验证者角色并检查安装情况。

重要

验证成功后，继续执行阶段 6 的安装后设置，然后执行阶段 7 的可选组件安装（仅适用于基于克隆的方法）。

检查点 3：设置授权

修改 settings.json 前，请先展示以下内容：

⚙️ VS Code Settings Update

I will now update your VS Code settings to add HVE-Core paths.

Changes to be made:
• [List paths based on selected method]

⚠️ Authorization Required: Do you authorize these settings changes? (yes/no)

如果用户拒绝：“安装已取消。未更改任何设置。”

验证工作流

根据所选方法运行验证。运行前设置基础路径变量：

方法	基础路径
1	../hve-core
2	.hve-core
3、4	/workspaces/hve-core
5	检查工作区文件
6	lib/hve-core

PowerShell： 设置 method 和 basePath 变量后，运行 scripts/validate-installation.ps1。

Bash： 使用方法编号和基础路径作为参数，运行 scripts/validate-installation.sh。

成功报告

验证成功后，显示：

✅ Core Installation Complete!

Method [N]: [Name] installed successfully.

📍 Location: [path based on method]
⚙️ Settings: [settings file or workspace file]
📖 Documentation: https://github.com/microsoft/hve-core/blob/main/docs/getting-started/methods/[method-doc].md

🧪 Available Agents:
• rpi-agent, documentation, backlog-manager, and adr-creation
• code-review, security-planner, ux-ui-designer, and more!

📋 Configuring optional settings...

显示成功报告后，继续执行阶段 6 的安装后设置。

阶段 6：安装后设置

阅读 references/post-installation-setup.md，并在继续之前完成其中规定的所有步骤。如果无法访问该文件，请告知用户无法完成安装后设置，并停止操作，不要自行编造步骤。

阶段 7：组件安装与升级

阅读 references/component-installation.md，并严格按照其中的组件安装与升级流程操作，包括遵循其中定义的每一个确认关卡。对于方法 3 和 5，在冲突检测或复制之前，先验证现有 HVE-Core 克隆配置的上游源，并按照该参考文档中的警告与确认流程操作。如果无法访问该参考文档，请告知用户无法执行组件安装与升级，并停止操作，不要写入目标代码库。

错误恢复

当步骤失败时，提供有针对性的指导：

错误	故障排除
不在 git 仓库中	在 git 工作区内运行；验证 git --version
克隆失败	检查到 github.com 的网络连接；验证 git 凭据和写入权限
验证失败	代码库可能不完整；删除 HVE-Core 目录并重新运行安装程序
设置更新失败	验证 settings.json 是否为有效 JSON；检查权限；尝试关闭 VS Code

回滚

要移除失败或不需要的安装：

方法	清理
扩展	VS Code → 扩展 → HVE Core → 卸载
1（同级克隆）	rm -rf ../hve-core
2（Git 忽略）	rm -rf .hve-core
3-4（挂载/Codespaces）	从 devcontainer.json 中移除 mount/postCreate
5（多根工作区）	删除 .code-workspace 文件
6（子模块）	git submodule deinit lib/hve-core && git rm lib/hve-core

然后从 .vscode/settings.json 中移除 HVE-Core 路径。

如果使用了阶段 7 的组件安装，还要删除 .hve-tracking.json，以及任何不再需要的 .github/agents/、.github/prompts/、.github/instructions/ 或 .github/skills/ 复制内容。

授权护栏

未经用户明确授权，绝不修改文件。进行更改前务必说明更改内容。在任何检查点都必须尊重用户的拒绝。

需要授权的检查点：

1. 初始同意（阶段 1）—开始检测前
2. 设置授权（阶段 5，检查点 3）—编辑 settings/devcontainer 前

输出格式要求

进度报告

为保持一致，请使用以下准确的表情符号：

进行中指示语（始终以省略号 ... 结尾）：

• "📂 正在检测环境..."
• "🔍 正在询问配置问题..."
• "📋 正在推荐安装方法..."
• "📥 正在安装 HVE-Core..."
• "🔍 正在验证安装..."
• "⚙️ 正在更新设置..."
• "🛡️ 正在配置 gitignore..."
• "📡 正在配置 MCP 服务..."

完成指示语：

• "✅ [成功消息]"
• "❌ [错误消息]"
• "⏭️ [已跳过消息]"

成功标准

**成功：**已检测环境、选定方法、验证 HVE-Core 目录（agents、instructions、skills）、配置设置，并指示用户重新加载。

**失败：**检测失败、克隆/子模块失败、验证发现目录缺失，或设置修改失败。