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

## 目的

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

## 检查流程

1. 确认 macOS 版本与芯片架构满足包内系统要求。
2. 检查 Node.js 版本：运行 `node --version`
3. 检查 OpenSpec 版本：运行 `openspec --version`

## 安装指南

### Homebrew 安装（推荐）

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

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

### Node.js 安装

使用 Homebrew 安装 Node.js：

```bash
brew install node
```

验证安装：`node --version`

### OpenSpec 安装

OpenSpec 使用 Node.js 自带的包管理能力完成安装，无需单独准备 npm。

```bash
npm install @fission-ai/openspec@最低版本 -g --registry=https://registry.npmmirror.com
```

验证安装：`openspec --version`

## 依赖要求

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

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

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

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



## 故障排除

### Homebrew 问题

```bash
brew update
brew doctor
```

### 版本不匹配

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

**Node.js 版本不匹配**：
```bash
brew upgrade node
```

**OpenSpec 版本不匹配**：
```bash
npm install @fission-ai/openspec@最低版本 -g --registry=https://registry.npmmirror.com
```

### 权限问题

```bash
sudo npm install @fission-ai/openspec@最低版本 -g --registry=https://registry.npmmirror.com
```

## 验证清单

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

```bash
uname -m
node --version
openspec --version
```

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

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

## 输出安装结果报告

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

报告格式如下：

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

| 依赖项 | 状态 | 当前值 | 要求 | 备注 |
|--------|------|--------|------|------|
| 系统兼容性 | ✓ 已确认 | macOS Apple Silicon / Intel | 与包要求一致 | |
| Node.js | ✓ 已安装 | 24.12.0 | >= 20.11.0 | |
| OpenSpec | ✓ 已安装 | 1.0.5 | 1.0.0 - < 2.0.0 | |

## 总结
- 必需依赖：3/3 已满足 ✓
```

**说明**：
- **状态**：使用 "✓ 已安装"、"✗ 未安装"、"⚠ 版本不匹配"
- **当前值**：运行检查命令获取的实际系统信息或版本
- **要求**：本提示词中列出的依赖要求
- **备注**：补充说明后续是否还需要人工处理

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

## macOS 特定说明

- 建议使用内置 Terminal 或 iTerm2
- 默认 shell 通常为 zsh，可按需替换 `~/.bashrc` 为 `~/.zshrc`
- OpenSpec 安装使用 Node.js 自带的包管理能力，无需单独安装独立 npm
