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

## 目的

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

## 检查流程

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

## 安装指南

### .NET SDK 安装

使用中国区 Azure 镜像安装 .NET SDK：

```bash
# 下载安装脚本（中国区镜像）
curl -fsSL https://dotnetcli.azureedge.net/dotnet/Install.sh -o /tmp/dotnet-install.sh

# 执行安装
chmod +x /tmp/dotnet-install.sh
/tmp/dotnet-install.sh --install-dir ~/.dotnet --channel 当前版本通道 --runtime aspnetcore

# 添加到 PATH（如果尚未添加）
export PATH=$PATH:~/.dotnet
echo 'export PATH=$PATH:~/.dotnet' >> ~/.bashrc
```

验证安装：`dotnet --version`

### Node.js 安装

使用华为云镜像安装 Node.js：

```bash
# 获取当前系统架构
ARCH=$(uname -m)
if [ "$ARCH" = "x86_64" ]; then
    NODE_ARCH="x64"
elif [ "$ARCH" = "aarch64" ]; then
    NODE_ARCH="arm64"
fi

# 下载 Node.js（使用华为云镜像）
curl -fsSL https://mirrors.huaweicloud.com/nodejs/v当前版本/node-v当前版本-linux-${NODE_ARCH}.tar.xz -o /tmp/node.tar.xz

# 解压安装
mkdir -p ~/.local
tar -xJf /tmp/node.tar.xz -C ~/.local --strip-components=1
rm /tmp/node.tar.xz

# 添加到 PATH
export PATH=$PATH:~/.local/bin
echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
```

验证安装：`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
```

### 版本不匹配

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

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

# 重新安装指定版本
# 重新运行中国区镜像安装脚本
```

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

### 网络问题

**使用中国镜像源**：
- .NET: 已使用中国区 Azure 镜像 (dotnetcli.azureedge.net)
- Node.js: 已使用华为云镜像 (mirrors.huaweicloud.com)
- npm: 已使用 npmmirror 镜像 (registry.npmmirror.com)

### 权限问题

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

## 中国区镜像配置总结

本指南已默认使用中国区镜像源，无需额外配置：

- **.NET SDK**: https://dotnetcli.azureedge.net/dotnet/Install.sh
- **Node.js**: https://mirrors.huaweicloud.com/nodejs/
- **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` 中读取的版本要求
- **备注**：说明该依赖是否为必需，或任何需要注意的事项

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

## 重要说明

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