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

## 目的

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

## 检查流程

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

## 安装指南

### Homebrew 安装（推荐）

如果尚未安装 Homebrew，请先安装：

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### .NET SDK 安装

使用 Homebrew 安装 .NET SDK：

```bash
brew install dotnet
```

验证安装：`dotnet --version`

### Node.js 安装

使用 Homebrew 安装 Node.js：

```bash
brew install node
```

验证安装：`node --version`

### NPM 安装

使用中国镜像源安装 NPM：

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

验证安装：`npm --version`

### OpenSpec 安装

使用中国镜像源安装 OpenSpec：

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

验证安装：`openspec --version`

## 依赖要求

以下依赖的版本要求（构建时从 manifest.json 注入）：

### 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



## 故障排除

### 脚本执行失败

**文件权限问题**：
```bash
chmod +x scripts/*.sh
```

**检查脚本路径是否正确**：
```bash
ls -la scripts/
pwd
```

### Homebrew 问题

**更新 Homebrew**：
```bash
brew update
brew upgrade
```

**查找包**：
```bash
brew search <package-name>
```

### 版本不匹配

检查 manifest.json 中的版本要求，根据依赖的 installHint 进行升级或降级。

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

# 使用 Homebrew 重新安装
brew reinstall dotnet
```

**Node.js 版本不匹配**：
```bash
# 使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc
nvm install 推荐版本
nvm use 推荐版本
```

### 网络问题

**使用中国镜像源**：
- npm: 已使用 npmmirror 镜像 (在安装命令中直接指定)
- Homebrew: 使用官方源（Homebrew 已在中国有良好支持）

### 权限问题

某些操作需要 sudo 权限：
```bash
sudo npm install 包名 -g --registry=https://registry.npmmirror.com
```

## 中国区镜像配置总结

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

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

## 验证清单

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

```bash
# 验证 .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` 命令获取的实际版本
- **要求版本**：从 `manifest.json` 中读取的版本要求
- **备注**：说明该依赖是否为必需，或任何需要注意的事项

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

## macOS 特定说明

- **系统版本要求**：macOS 10.15 (Catalina) 或更高版本
- **芯片架构**：支持 Intel 和 Apple Silicon (M1/M2/M3)
- **Terminal**：建议使用内置 Terminal 或 iTerm2
- **Shell**：默认使用 zsh（macOS Catalina 及更高版本）

## 重要说明

1. **版本号**：本指南中的版本信息已在构建时从 `manifest.json` 中的 `dependencies` 部分注入
2. **镜像源**：本指南已针对中国区优化，npm 安装使用国内镜像源
3. **包名**：OpenSpec 的包名是 `@fission-ai/openspec`（注意命名空间）
