5 分钟上手

本文档将帮助你快速开始使用 WopalSpace，从安装到第一个项目的完整流程。我们将通过实际示例，带你体验 WopalSpace 的核心功能。

💡 提示：如果你是第一次使用 WopalSpace，建议按照本文档的顺序逐步操作。整个过程大约需要 10-15 分钟。

前置要求

在开始之前，请确保你的系统满足以下要求：

要求项	最低配置	推荐配置	说明
Node.js	18.x	20.x LTS	JavaScript 运行时
npm	9.x	10.x	Node.js 包管理器
Git	2.30+	最新版	版本控制系统
内存	4 GB	8 GB	运行 AI 模型需要更多内存
磁盘	2 GB	10 GB	包含空间和缓存
操作系统	macOS 10.15+ / Ubuntu 20.04+ / Windows 10+	-	三大主流平台均支持

检查系统环境

运行以下命令检查你的系统是否满足要求：

# 检查 Node.js 版本
node --version  # 应该输出 v18.x.x 或更高

# 检查 npm 版本
npm --version   # 应该输出 9.x.x 或更高

# 检查 Git 版本
git --version   # 应该输出 git version 2.30.x 或更高

⚠️ 注意：如果你的 Node.js 版本过低，可以使用 nvm 来管理多个 Node.js 版本。

安装 Wopal CLI

Wopal CLI 是 WopalSpace 的命令行工具，提供了所有核心功能。我们提供三种安装方式：

方式一：一键安装脚本（推荐）⭐

这是最简单快捷的安装方式，脚本会自动检测系统环境并完成所有配置：

curl -fsSL https://wopal.cn/install.sh | bash

安装脚本会执行以下操作：

✅ 检测操作系统和 CPU 架构
✅ 下载对应平台的二进制文件
✅ 安装到 ~/.wopal/bin/ 目录
✅ 自动配置 PATH 环境变量
✅ 验证安装是否成功

安装完成后，验证安装：

wopal --version
# 输出示例：WopalSpace CLI v1.2.0

🔒 安全提示：如果你担心管道执行脚本的安全性，可以先下载查看内容：
curl -fsSL https://wopal.cn/install.sh -o install.sh
cat install.sh  # 查看脚本内容
bash install.sh # 确认无误后执行

配置 AI 提供商

WopalSpace 需要连接到 AI 服务才能发挥最大效用。我们支持多种 AI 提供商：

OpenAI（默认推荐）

# 设置 API Key
export WOPAL_AI_PROVIDER="openai"
export WOPAL_AI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# 或者使用配置文件
wopal config set ai.provider openai
wopal config set ai.apiKey sk-xxxxxxxxxxxxxxxxxxxxxxxx

Anthropic Claude

export WOPAL_AI_PROVIDER="anthropic"
export WOPAL_AI_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

本地模型（Ollama）

如果你想在本地运行 AI 模型：

# 1. 安装 Ollama（macOS/Linux）
curl -fsSL https://ollama.com/install.sh | sh

# 2. 下载代码模型
ollama pull codellama:34b

# 3. 配置 WopalSpace
wopal config set ai.provider local
wopal config set ai.baseUrl http://localhost:11434/api
wopal config set ai.model codellama:34b

🔐 安全建议：不要将 API Key 硬编码在代码中，使用环境变量或配置文件，并确保配置文件不被提交到 Git。

初始化第一个空间

现在让我们创建你的第一个 WopalSpace 空间！

步骤 1：创建项目目录

# 在你的工作目录中创建新项目
mkdir ~/projects/my-first-space
cd ~/projects/my-first-space

步骤 2：运行 setup

wopal setup

这个命令会准备 WOPAL_HOME、ontology source、基础能力层和首个 space。

步骤 3：查看生成的结构

初始化完成后，你的目录结构如下：

my-first-space/
├── .wopal-space/          # WopalSpace 配置目录
│   ├── STRUCTURE.md       # 空间结构定义（Ontology）
│   ├── REGULATIONS.md     # 空间守则
│   ├── config.json        # 空间配置
│   └── memory/            # AI 记忆存储
│       ├── USER.md        # 用户档案
│       ── context.json   # 上下文缓存
── INBOX/                 # 收件箱（新文件默认放这里）
── logs/                  # 操作日志
├── backup/                # 自动备份
└── AGENTS.md              # Agent 指令（自动创建）

理解核心文件

STRUCTURE.md - 空间结构定义

这是 WopalSpace 最重要的文件之一，它告诉 AI 助手你的项目结构：

# 空间结构

## 基本信息
- 名称：my-first-space
- 类型：Web 应用
- 语言：TypeScript
- 框架：Next.js

## 目录结构
- `src/app/` - 页面路由（App Router）
- `src/components/` - 可复用组件
- `src/lib/` - 工具函数和配置
- `src/styles/` - 全局样式
- `public/` - 静态资源

## 开发规则
- ✅ 使用 TypeScript 严格模式
- ✅ 组件使用函数式组件 + Hooks
- ✅ 样式使用 Tailwind CSS
- ✅ 提交前必须通过 ESLint 检查
- ✅ 新功能需要编写单元测试

REGULATIONS.md - 空间守则

定义 AI 助手的行为规范和限制：

# 空间守则

## 代码规范
- 遵循项目的 ESLint 配置
- 使用 2 空格缩进
- 变量命名使用 camelCase
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case

## 禁止操作
- ❌ 不要修改 .env 文件
- ❌ 不要删除已有的测试文件
-  不要使用 any 类型
- ❌ 不要引入未经验证的第三方库

## 注意事项
- ⚠️ 修改 API 前需确认向后兼容
- ️ 数据库操作需要事务包装
- ️ 敏感信息必须使用环境变量

使用 AI 助手

WopalSpace 的核心功能是 AI 辅助开发。让我们开始第一次对话：

启动对话

wopal chat

启动后，你会进入交互式的 AI 对话界面：

╔══════════════════════════════════════════════════╗
║         WopalSpace AI Assistant v1.2.0           ║
╚══════════════════════════════════════════════════╝

📖 已加载空间结构：my-first-space
🧠 已加载用户档案
💬 等待你的指令...

> 帮我创建一个 React 组件

实际对话示例

> 帮我创建一个 React 组件

AI: 好的！我将为你创建一个名为 `UserProfile` 的 React 组件。

   这个组件将包含：
   - 用户头像显示
   - 用户名和邮箱信息
   - 基本样式

   创建文件：src/components/user-profile.tsx

   ```tsx
   interface UserProfileProps {
     name: string;
     email: string;
     avatarUrl?: string;
   }

   export function UserProfile({ name, email, avatarUrl }: UserProfileProps) {
     return (
       <div className="flex items-center space-x-4 p-4">
         <img
           src={avatarUrl || '/default-avatar.png'}
           alt={name}
           className="w-12 h-12 rounded-full"
         />
         <div>
           <h3 className="font-semibold">{name}</h3>
           <p className="text-gray-600">{email}</p>
         </div>
       </div>
     );
   }

需要我为你添加单元测试吗？

好的，添加测试

AI: 正在创建测试文件…

创建文件：src/components/tests/user-profile.test.tsx

import { render, screen } from '@testing-library/react';
import { UserProfile } from '../user-profile';

describe('UserProfile', () => {
  it('renders user information correctly', () => {
    render(
      <UserProfile
        name="John Doe"
        email="john@example.com"
      />
    );

    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('john@example.com')).toBeInTheDocument();
  });
});

✅ 测试文件已创建！运行 npm test 来验证。


### 常用 AI 指令

| 指令 | 说明 | 示例 |
|------|------|------|
| 创建组件 | 生成新的 UI 组件 | "创建一个登录表单组件" |
| 代码审查 | 审查代码质量 | "审查 src/api/ 下的所有文件" |
| 生成测试 | 自动编写测试用例 | "为 utils.ts 生成单元测试" |
| 重构代码 | 优化代码结构 | "重构这个函数，提取公共逻辑" |
| 编写文档 | 生成代码文档 | "为 AuthService 类编写 JSDoc" |
| 修复 Bug | 分析并修复问题 | "修复这个类型错误" |
| 解释代码 | 解释代码逻辑 | "解释这段代码的工作原理" |

---

## 管理技能（Skills）

技能是 WopalSpace 的扩展能力，让你可以自定义 AI 的功能。

### 查看已安装的技能

```bash
wopal skills list

输出示例：

已安装的技能（5）：

🔧 代码审查 (code-review)
   版本: 1.2.0
   功能: 自动审查代码质量、风格和安全问题

🧪 测试生成 (test-generator)
   版本: 1.0.5
   功能: 根据代码自动生成单元测试

📝 文档编写 (doc-writer)
   版本: 1.1.0
   功能: 自动生成代码文档和 README

🚀 部署助手 (deploy-assistant)
   版本: 2.0.0
   功能: 自动化部署流程和 CI/CD

🔍 Git 助手 (git-helper)
   版本: 1.3.2
   功能: 智能提交、分支管理、冲突解决

安装新技能

# 从社区仓库安装
wopal skills install code-review

# 从 GitHub 安装
wopal skills install https://github.com/wopal/skill-code-review

# 从本地目录安装
wopal skills install ./my-custom-skill

创建自定义技能

# 1. 创建技能目录
mkdir -p .wopal-space/skills/my-skill

# 2. 创建技能定义文件
cat > .wopal-space/skills/my-skill/SKILL.md << 'EOF'
# 我的自定义技能

## 描述
这是一个自定义技能，用于演示如何创建技能。

## 功能
- 功能 1：生成项目报告
- 功能 2：分析代码复杂度

## 使用方式
> 生成项目报告

AI 将执行以下步骤：
1. 分析项目结构
2. 统计代码行数
3. 生成报告文件
EOF

# 3. 注册技能
wopal skills register my-skill

实用命令参考

以下是一些常用的 Wopal 命令：

空间管理

# 列出所有空间
wopal spaces list

# 切换到指定空间
wopal spaces switch my-project

# 创建新空间
wopal spaces create new-project

# 备份空间
wopal backup

# 恢复空间
wopal restore --from backup-2024-01-15

AI 对话

# 启动交互式对话
wopal chat

# 单次对话（非交互模式）
wopal chat --message "帮我解释这段代码"

# 从文件读取输入
wopal chat --file prompt.txt

# 保存对话历史
wopal chat --save conversation.md

配置管理

# 查看当前配置
wopal config show

# 设置配置项
wopal config set ai.model gpt-4

# 删除配置项
wopal config unset ai.temperature

# 重置为默认配置
wopal config reset

诊断和调试

# 检查系统环境
wopal doctor

# 显示详细日志
wopal --verbose chat

# 导出调试信息
wopal debug export

最佳实践

1. 保持空间整洁

定期清理不需要的文件：

# 清理缓存
wopal cache clean

# 清理旧日志
wopal logs prune --older-than 30d

2. 定期备份

设置自动备份：

# 手动备份
wopal backup

# 配置自动备份（每小时）
wopal config set spaces.backupInterval 3600
wopal config set spaces.autoSync true

3. 版本控制

将空间配置纳入 Git 管理：

# 添加 WopalSpace 配置到 Git
git add .wopal-space/STRUCTURE.md
git add .wopal-space/REGULATIONS.md
git add .wopal-space/skills/

# 提交
git commit -m "feat: add wopalspace configuration"

# 注意：不要提交敏感信息
echo ".wopal-space/memory/" >> .gitignore
echo ".wopal-space/config.json" >> .gitignore

4. 性能优化

# 启用增量同步（只同步变化的文件）
wopal config set spaces.incrementalSync true

# 设置最大上下文大小
wopal config set ai.maxContextSize 100000

常见问题

Q: 安装时遇到 “Permission denied” 错误

A: 这通常是因为权限不足。尝试以下解决方案：

# 方案 1：使用 sudo（不推荐）
curl -fsSL https://wopal.cn/install.sh | bash

# 方案 2：修改安装目录权限
mkdir -p ~/.wopal/bin
chmod 755 ~/.wopal/bin
curl -fsSL https://wopal.cn/install.sh | bash

Q: 执行 `wopal` 提示 “command not found”

A: PATH 环境变量可能未正确配置。

# 检查 wopal 是否在 PATH 中
which wopal

# 如果没有，手动添加到 PATH
echo 'export PATH="$HOME/.wopal/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc  # 或 source ~/.zshrc

# 验证
wopal --version

Q: AI 助手无法连接

A: 检查以下几个方面：

API Key 是否正确
```
wopal config show | grep apiKey
```
网络连接
```
curl -I https://api.openai.com
```

代理设置（如果需要）

export HTTPS_PROXY="http://127.0.0.1:7890"

测试连接
```
wopal config test-ai
```

Q: 如何更新到最新版本？

A: 使用以下命令：

# 方式 1：使用内置升级命令
wopal upgrade

# 方式 2：通过 npm 升级
npm update -g @wopal/cli

# 查看版本信息
wopal version --check

Q: 可以离线使用吗？

✅ 可以离线：空间管理、文件操作、本地技能
❌ 需要网络：AI 对话、技能下载、在线更新

如果你需要完全离线工作，可以配置本地 AI 模型（参见前面的 Ollama 配置部分）。

下一步

恭喜你完成了快速入门！你现在已经掌握了 WopalSpace 的基础用法。接下来可以：

📚 核心概念 — 深入理解 Space、Ontology、Skills 的工作原理
🔧 配置指南 — 学习如何定制 WopalSpace 的行为
命令行参考 — 完整的命令列表和参数说明
❓ 常见问题 — 解决使用中遇到的各种问题

加入社区

📖 查看完整文档
💬 加入 Discord 社区
🐛 在 GitHub Issues 报告问题
💡 在 GitHub Discussions 分享想法

🎉 恭喜！你已经成功入门 WopalSpace。现在就开始你的 AI 辅助开发之旅吧！