> ## Documentation Index
> Fetch the complete documentation index at: https://docs.5ire.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发环境搭建指南

> 本指南将帮助您配置5ire项目的本地开发环境并启动运行。

<Info>
  * [Node.js](https://nodejs.org/)（推荐v20.10.0版本）
  * [Git](https://git-scm.com/)
  * [Supabase](https://supabase.com/)账号（用于认证和数据库服务）
  * Python环境（推荐v3.10.8版本）及UV包管理器
</Info>

## 环境配置流程

### 1. 克隆项目仓库

```bash theme={null}
git clone https://github.com/nanbingxyz/5ire.git
cd 5ire
```

### 2. Node.js环境配置

推荐使用[asdf](https://asdf-vm.com/)版本管理工具。已安装asdf的用户可执行：

```bash theme={null}
# 安装指定Node.js版本
asdf install nodejs 20.10.0

# 设置项目级版本
asdf local nodejs 20.10.0
```

也可直接从[官网](https://nodejs.org/)下载安装v20.10.0版本。

### 3. 安装依赖

#### 激活Python虚拟环境

根据当前shell环境执行对应命令：

```bash theme={null}
source venv/bin/activate.fish
```

#### 安装Node依赖

```bash theme={null}
npm install
```

### 4. 环境变量配置

在项目根目录创建`.env`文件，填入以下配置：

```
SUPA_PROJECT_ID=你的Supabase项目ID
SUPA_KEY=你的Supabase匿名密钥
AXIOM_TOKEN=你的Axiom凭证令牌
AXIOM_ORG_ID=你的Axiom组织ID
NODE_ENV=development
```

> **说明**：我们通过[Axiom](https://axiom.co/)采集匿名运行指标，使用Supabase进行授权和设置备份。若开发时无需这些功能，可用占位符配置代替。

获取服务凭证：

* **Axiom凭证**：
  1. 在[Axiom](https://app.axiom.co)创建组织
  2. 在组织设置中获取组织ID
  3. 创建新的API令牌

* **Supabase凭证**：
  1. 在Supabase平台创建项目
  2. 进入项目设置 > API
  3. 从项目URL提取子域名作为项目ID（示例：`https://xvmubowipwszxgjskdme.supabase.co`的ID为`xvmubowipwszxgjskdme`）
  4. 复制`anon`公钥作为`SUPA_KEY`值

### 5. 配置Git钩子 （Husky）

```bash theme={null}
npm run prepare
```

## 启动开发环境

### 运行开发服务器

```bash theme={null}
npm start
```

该命令将：

1. 以开发模式启动Electron应用
2. 启用代码热更新功能
3. 自动打开应用窗口

## 常见问题处理

### Supabase连接异常

1. 确认`.env`文件中的`SUPA_PROJECT_ID`和`SUPA_KEY`配置正确
2. 确保Supabase项目已启动且可访问
3. 确认使用的是开发专用`anon`公钥

### Node.js版本异常

```bash theme={null}
# 查看当前版本
node -v

# 确认asdf管理的版本
asdf current nodejs
```

### Electron启动失败

1. 尝试禁用沙箱和GPU加速：
   ```bash theme={null}
   npm start -- --no-sandbox --disable-gpu
   ```
2. 检查控制台输出的具体错误信息

## 开发工作流

1. 修改代码后
2. 应用将自动热更新（主进程修改需重启生效）

## 构建生产包

```bash theme={null}
npm run package
```

构建完成后将在`release/build`目录生成可分发的安装包。

## 参考资料

* [Electron文档](https://www.electronjs.org/docs)
* [Supabase文档](https://supabase.com/docs)
* [Axiom文档](https://axiom.co/docs/reference/settings#token)
* [模型上下文协议](https://modelcontextprotocol.io/)