常见问题 (FAQ)

收集了用户在使用 WopalSpace 过程中最常遇到的问题及解决方案。

安装与环境

WopalSpace 支持哪些操作系统？

WopalSpace 支持所有主流操作系统：

• macOS：10.15 (Catalina) 及以上，支持 Intel 和 Apple Silicon
• Linux：Ubuntu 20.04+、Debian 11+、Fedora 36+
• Windows：10 (Build 19041) 及以上，推荐使用 WSL2

如何检查 Node.js 版本？

运行以下命令：

node --version
# 输出类似：v20.10.0

如果版本低于 18.0.0，请升级 Node.js：

# 使用 nvm 管理 Node.js 版本
nvm install 20
nvm use 20
nvm alias default 20

安装时遇到权限错误怎么办？

在 macOS 或 Linux 上，可能会遇到 PATH 未刷新或 shell 配置未生效的问题。推荐按以下顺序排查：

curl -fsSL https://wopal.cn/install.sh | bash
source ~/.zshrc  # 或 source ~/.bashrc
wopal --version

如果仍然失败，请检查：

• ~/.wopal/bin 是否已加入 PATH
• 当前 shell 是否重新加载了配置文件
• 网络是否可访问 wopal.cn 与下载通道

空间管理

如何创建多个空间？

每个项目目录都可以初始化一个独立空间：

# 创建项目 A 的空间
mkdir project-a && cd project-a
wopal setup

# 创建项目 B 的空间
mkdir project-b && cd project-b
wopal setup

# 查看所有空间
wopal list

# 切换空间
wopal switch project-a

空间之间如何共享配置？

有三种方式可以在空间之间共享配置：

1. 全局配置：放在 ~/.wopal/config.json 中，所有空间共享
2. 模板：创建自定义模板，初始化时复用
3. 符号链接：使用 ln -s 共享特定配置文件

# 创建全局共享的提示词
mkdir -p ~/.wopal/shared-prompts
echo "# Shared System Prompt" > ~/.wopal/shared-prompts/system.md

# 在空间中链接
ln -s ~/.wopal/shared-prompts/system.md .wopal-space/prompts/system.md

空间占用了多少磁盘空间？

一个典型的空间占用如下：

AI 相关

支持哪些 AI 模型？

WopalSpace 支持多种 AI 提供商和模型：

AI 对话的 token 用量如何计算？

每次 AI 对话的 token 用量取决于：

1. 系统提示词：通常 500-2000 tokens
2. 空间上下文：STRUCTURE.md 和记忆，约 1000-5000 tokens
3. 用户消息：你的输入内容
4. AI 响应：模型的输出内容

提示：使用 wopal chat --verbose 可以查看每次对话的 token 用量详情。

如何限制 AI 的操作权限？

通过 REGULATIONS.md 文件控制 AI 的行为：

# 空间守则

## 允许的操作
- 读取所有源代码文件
- 创建新的源代码文件
- 运行测试命令

## 禁止的操作
- 修改 .env 文件
- 删除任何文件
- 执行网络请求
- 安装新的 npm 包

## 需要确认的操作
- 修改数据库结构
- 修改 API 接口
- 修改配置文件

技能系统

如何编写自定义技能？

自定义技能由以下部分组成：

my-skill/
├── skill.json         # 技能元数据
├── README.md          # 技能说明文档
├── prompts/           # AI 提示词
│   ├── default.md     # 默认提示词
│   └── review.md      # 审查提示词
└── commands/          # 可执行命令
    └── run.sh         # 主命令

skill.json 示例：

{
  "name": "my-analyzer",
  "version": "1.0.0",
  "description": "项目分析工具",
  "author": "Your Name",
  "commands": {
    "analyze": {
      "description": "分析项目结构",
      "prompt": "prompts/default.md"
    }
  },
  "tags": ["analysis", "project"]
}

技能安装失败怎么办？

常见原因和解决方案：

性能优化

如何加快 AI 响应速度？

以下方法可以提升 AI 响应速度：

1. 使用更快的模型：gpt-3.5-turbo 比 gpt-4 快约 5 倍
2. 减少上下文：保持 STRUCTURE.md 简洁
3. 限制记忆条目：定期清理不需要的记忆
4. 使用本地模型：避免网络延迟

# 使用更快的模型
wopal chat -m gpt-3.5-turbo "快速问题"

# 清理不必要的记忆
wopal memory list
wopal memory remove <id>

日志文件太大怎么办？

WopalSpace 会自动管理日志，但如果你需要手动清理：

# 查看日志大小
du -sh ~/.wopal/logs/

# 清理 30 天前的日志
wopal logs clean --older-than 30d

# 完全清空日志
wopal logs clear

故障排除

通用排查步骤

遇到问题时，按以下步骤排查：

1. 运行诊断：wopal doctor
2. 查看日志：wopal logs tail
3. 检查配置：wopal config show
4. 调试模式：wopal --verbose <command>
5. 重置配置：wopal config reset

报告 Bug

如果问题无法解决，请提交 Bug 报告：

1. 运行 wopal debug 收集调试信息
2. 复制输出内容
3. 前往 GitHub Issues 创建新 Issue
4. 附上调试信息和复现步骤

提交 Bug 前，请先搜索是否已有相同问题的报告。

如果你的问题没有在这里列出，欢迎在 社区讨论 中提问。