配置指南

WopalSpace 提供了灵活的配置系统，支持全局配置、空间级配置和环境变量三种方式来定制你的开发体验。

配置文件位置

WopalSpace 按以下优先级查找配置文件：

1. 命令行参数 --config <path>
2. 当前空间目录 .wopal-space/config.json
3. 用户主目录 ~/.wopal/config.json
4. 系统默认配置 /etc/wopal/config.json

配置文件格式

配置文件使用标准 JSON 格式：

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4",
    "apiKey": "sk-xxx",
    "baseUrl": "https://api.openai.com/v1",
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "editor": {
    "default": "code",
    "args": ["--wait"]
  },
  "spaces": {
    "dir": "~/.wopal/spaces",
    "autoSync": true,
    "backupInterval": 3600
  },
  "ui": {
    "language": "zh-CN",
    "theme": "auto",
    "compact": false
  },
  "skills": {
    "autoInstall": true,
    "registry": "https://registry.wopal.dev"
  }
}

AI 配置

AI 配置是 WopalSpace 最核心的配置项，决定了 AI 助手的行为方式。

支持的 AI 提供商

OpenAI 配置

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4",
    "apiKey": "sk-xxx"
  }
}

可用模型：

Anthropic 配置

{
  "ai": {
    "provider": "anthropic",
    "model": "claude-3-sonnet-20240229",
    "apiKey": "sk-ant-xxx"
  }
}

可用模型：

本地模型配置

使用 Ollama 等本地模型服务：

{
  "ai": {
    "provider": "local",
    "baseUrl": "http://localhost:11434/api",
    "model": "codellama:34b"
  }
}

推荐的本地模型：

• codellama:34b — 代码生成
• deepseek-coder:33b — 代码理解
• starling-lm:7b — 轻量级选择

空间配置

STRUCTURE.md

每个空间的核心配置文件，定义空间的结构和规则：

# 空间结构

## 基本信息
- 名称：my-project
- 类型：Web 应用
- 框架：Next.js

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

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

## 技能
- code-review
- test-generator
- doc-writer

REGULATIONS.md

空间守则，定义 AI 助手的行为规范：

# 空间守则

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

## 禁止操作
- 不要修改 .env 文件
- 不要删除已有的测试文件
- 不要使用 any 类型

## 注意事项
- 修改 API 前需确认向后兼容
- 数据库操作需要事务包装

环境变量

所有配置项都可以通过环境变量覆盖，优先级最高：

# AI 配置
export WOPAL_AI_PROVIDER="openai"
export WOPAL_AI_MODEL="gpt-4"
export WOPAL_AI_API_KEY="sk-xxx"
export WOPAL_AI_BASE_URL="https://api.openai.com/v1"
export WOPAL_AI_MAX_TOKENS="4096"

# 编辑器配置
export WOPAL_EDITOR="code"

# 空间配置
export WOPAL_SPACES_DIR="$HOME/.wopal/spaces"
export WOPAL_AUTO_SYNC="true"

# UI 配置
export WOPAL_LANGUAGE="zh-CN"
export WOPAL_THEME="dark"

# 调试配置
export WOPAL_LOG_LEVEL="debug"
export WOPAL_LOG_FILE="$HOME/.wopal/logs/wopal.log"

在 .bashrc 或 .zshrc 中配置持久化环境变量：

# ~/.zshrc
# WopalSpace 环境变量
export WOPAL_AI_API_KEY="sk-xxx"
export WOPAL_AI_PROVIDER="openai"
export WOPAL_SPACES_DIR="$HOME/projects"

高级配置

自定义 AI 提示词

你可以通过创建提示词文件来自定义 AI 的行为：

<!-- .wopal-space/prompts/system.md -->
你是一个专业的全栈开发工程师。

## 项目背景
这是一个使用 Next.js 14 构建的电商平台。

## 你的职责
- 编写高质量的 TypeScript 代码
- 遵循项目的代码规范
- 确保代码的可测试性
- 提供清晰的注释

## 约束条件
- 不要引入新的依赖，除非必要
- 保持向后兼容
- 考虑性能影响

钩子 (Hooks)

在特定事件发生时自动执行脚本：

{
  "hooks": {
    "pre-commit": "npm run lint && npm run test",
    "post-init": "npm install",
    "pre-chat": "wopal memory sync",
    "post-run": "git add -A"
  }
}

支持的钩子事件：

代理配置

如果需要通过代理访问 AI 服务：

{
  "network": {
    "proxy": "http://127.0.0.1:7890",
    "timeout": 30000,
    "retryCount": 3
  }
}

或通过环境变量：

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

配置验证

使用内置命令验证配置是否正确：

# 验证配置文件格式
wopal config validate

# 测试 AI 连接
wopal config test-ai

# 显示当前生效配置
wopal config show

配置迁移

从旧版本迁移配置：

# 自动迁移配置
wopal config migrate

# 查看需要迁移的配置项
wopal config migrate --dry-run