# PCode 依赖安装检查指南 - Windows (LLM 提示词)

## 目的

本文档为 AI/LLM 系统提供统一的依赖检查和安装指导。LLM 应根据本文档提供的内容，引导用户完成依赖检查和安装。

## 检查流程

1. 检查 .NET SDK 版本：运行 `dotnet --version`
2. 检查 Node.js 版本：运行 `node --version`
3. 检查 npm 版本：运行 `npm --version`
4. 检查 OpenSpec 版本：运行 `openspec --version`

## 安装指南

### .NET SDK 安装

使用 winget 安装 .NET SDK：

```powershell
winget install Microsoft.DotNet.SDK.10 --accept-source-agreements --accept-package-agreements
```

验证安装：`dotnet --version`

### Node.js 安装

使用 winget 安装 Node.js：

```powershell
winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
```

验证安装：`node --version`

### NPM 安装

使用中国镜像源安装 NPM：

```powershell
# 直接使用 npmmirror 镜像安装
npm install npm@推荐版本 -g --registry=https://registry.npmmirror.com
```

验证安装：`npm --version`

### OpenSpec 安装

使用中国镜像源安装 OpenSpec：

```powershell
# 直接使用 npmmirror 镜像安装指定版本
npm install @fission-ai/openspec@最低版本 -g --registry=https://registry.npmmirror.com
```

验证安装：`openspec --version`

## 依赖要求

以下依赖的版本要求已在本提示词中预置，可直接使用：

### claudeCode
- 最低版本: 2.1.0
- 描述: Claude Code - AI-powered development framework

### dotnet
- 最低版本: 10.0.0
- 推荐版本: 10.0.0
- 安装提示: Install from https://dotnet.microsoft.com/download/dotnet/10.0
- 描述: .NET 10 runtime and SDK

### node
- 最低版本: 20.11.0
- 推荐版本: 24.12.0
- 安装提示: Install from https://nodejs.org/ or use nvm
- 描述: Node.js runtime

### npm
- 最低版本: 10.0.0
- 推荐版本: 10.9.0
- 描述: NPM package manager

### openspec
- 最低版本: 1.0.0
- 最高版本: 2.0.0
- 描述: OpenSpec proposal management system

### system
- 描述: System requirements for Hagicode platform



## 故障排除

### 脚本执行失败

**PowerShell 执行策略检查**：

```powershell
Get-ExecutionPolicy
```

如果显示 `Restricted`，需要设置执行策略：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

**以管理员身份运行 PowerShell**：

右键点击 PowerShell 图标，选择"以管理员身份运行"。

### 版本不匹配

根据本提示词中的版本要求，结合依赖的 installHint 进行升级或降级。

**.NET SDK 版本不匹配**：
```powershell
# 列出已安装的 .NET 版本
dotnet --list-sdks

# 使用 winget 重新安装
winget install Microsoft.DotNet.SDK.10
```

**Node.js 版本不匹配**：
```powershell
# 使用 nvm-windows 管理 Node.js 版本
# 下载 nvm-windows: https://github.com/coreybutler/nvm-windows/releases
nvm install 推荐版本
nvm use 推荐版本
```

### 网络问题

**使用中国镜像源**：
- npm: 已使用 npmmirror 镜像 (在安装命令中直接指定)
- winget: 使用默认源

### 权限问题

某些操作需要管理员权限：
- 以管理员身份运行 PowerShell
- 或使用"运行方式"选择管理员

### 环境变量问题

如果命令无法识别，可能需要添加到 PATH：
1. 打开"系统属性" -> "高级" -> "环境变量"
2. 编辑 PATH 环境变量
3. 添加安装路径（如 `C:\Program Files\dotnet\`）
4. 重启 PowerShell

## 中国区镜像配置总结

本指南已针对中国区优化：

- **.NET SDK**: 通过 winget 安装
- **Node.js**: 通过 winget 安装
- **npm**: https://registry.npmmirror.com（在安装命令中直接指定）

## 验证清单

完成安装后，运行以下命令验证所有依赖：

```powershell
# 验证 .NET
dotnet --version

# 验证 Node.js
node --version

# 验证 npm
npm --version

# 验证 OpenSpec
openspec --version
```

## 执行边界（必须遵守）

- 安装完成后的唯一必要动作是检查依赖状态。
- 不尝试启动任何服务。
- 不进行额外初始化任务。
- 不触发与依赖检查无关的后置流程。
- 在非交互式模式下，不提出交互式问题；使用确定性默认值并在输出中记录假设。
- 最终输出必须为：安装完成 + 依赖检查结果。

## 输出安装结果报告

**重要**：在完成所有依赖的检查和安装后，必须向用户输出一个清晰的表格报告，汇总所有依赖的状态。

报告格式如下：

```markdown
## 依赖安装结果报告

| 依赖项 | 状态 | 当前版本 | 要求版本 | 备注 |
|--------|------|----------|----------|------|
| .NET SDK | ✓ 已安装 | 10.0.0 | >= 10.0.0 | |
| Node.js | ✓ 已安装 | 20.11.0 | >= 20.11.0 | |
| npm | ✓ 已安装 | 10.9.0 | >= 10.0.0 | |
| OpenSpec | ✓ 已安装 | 1.0.5 | 1.0.0 - < 2.0.0 | |

## 总结
- 必需依赖：4/4 已安装 ✓
```

**说明**：
- **状态**：使用 "✓ 已安装"、"✗ 未安装"、"⚠ 版本不匹配"
- **当前版本**：运行 `--version` 命令获取的实际版本
- **要求版本**：本提示词中列出的版本要求
- **备注**：说明该依赖是否为必需，或任何需要注意的事项

在输出报告后，如果存在未安装或版本不匹配的依赖，应提供具体的安装或升级建议。

## Windows 特定说明

- **系统版本要求**：Windows 10 版本 1607+ 或 Windows 11
- **架构**：x64
- **PowerShell**：建议使用 PowerShell 7+（兼容 Windows PowerShell 5.1）
- **管理员权限**：某些操作需要管理员权限
- **Windows Defender**：可能会阻止脚本执行，需要添加排除项

## PowerShell 基础命令

```powershell
# 查看执行策略
Get-ExecutionPolicy

# 设置执行策略（当前会话）
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# 以管理员身份运行
# 右键点击 PowerShell -> "以管理员身份运行"

# 检查环境变量
$env:PATH

# 查看已安装的软件
winget list
```

## 重要说明

1. **版本号**：本指南中的版本信息已在本提示词的依赖章节中预置
2. **镜像源**：本指南已针对中国区优化，npm 安装使用国内镜像源
3. **包名**：OpenSpec 的包名是 `@fission-ai/openspec`（注意命名空间）
