mirror of
https://github.com/qingchencloud/clawpanel.git
synced 2026-05-12 02:20:58 +08:00
53f46d8ef2
- Windows Gateway 启动改为前台 spawn 模式（绕过 schtasks 管理员权限） - 添加全局 Gateway 未启动引导横幅（黄色提示条 + 一键启动按钮） - 所有页面加载动画改为脉冲效果 - 统一 Windows cmd /c 调用加 CREATE_NO_WINDOW 标志 - 托盘菜单复用 service.rs 逻辑 - 新增 utils.rs 封装 openclaw_command - 修复 config 文件 UI 字段污染问题 - 添加 dev.ps1 启动脚本
157 lines
4.4 KiB
Markdown
157 lines
4.4 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对 ClawPanel 项目的关注！以下是参与贡献的相关说明。
|
||
|
||
## 开发环境要求
|
||
|
||
| 依赖 | 最低版本 | 说明 |
|
||
|------|----------|------|
|
||
| Node.js | 18+ | 前端构建 |
|
||
| Rust | stable | Tauri 后端编译 |
|
||
| Tauri CLI | v2 | `cargo install tauri-cli --version "^2"` |
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/qingchencloud/clawpanel.git
|
||
cd clawpanel
|
||
|
||
# 安装前端依赖
|
||
npm install
|
||
```
|
||
|
||
#### macOS / Linux
|
||
|
||
```bash
|
||
# 启动开发模式（完整 Tauri 桌面应用）
|
||
./scripts/dev.sh
|
||
|
||
# 仅启动前端（浏览器调试，使用 mock 数据）
|
||
./scripts/dev.sh web
|
||
```
|
||
|
||
#### Windows
|
||
|
||
```powershell
|
||
# 启动开发模式（完整 Tauri 桌面应用）
|
||
npm run tauri dev
|
||
|
||
# 仅启动前端（浏览器调试，使用 mock 数据）
|
||
npm run dev
|
||
```
|
||
|
||
> Windows 开发需要安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（勾选「使用 C++ 的桌面开发」工作负载）和 [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)（Win10+ 通常已预装）。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
clawpanel/
|
||
├── src/ # 前端源码（Vanilla JS）
|
||
│ ├── pages/ # 页面模块（每个页面导出 render 函数）
|
||
│ ├── components/ # 通用组件（侧边栏、弹窗、Toast）
|
||
│ ├── lib/ # 工具库（Tauri API 封装、主题切换）
|
||
│ ├── style/ # CSS 样式（CSS Variables 驱动）
|
||
│ ├── router.js # Hash 路由
|
||
│ └── main.js # 入口文件
|
||
├── src-tauri/ # Rust 后端
|
||
│ ├── src/commands/ # Tauri 命令（按功能模块拆分）
|
||
│ ├── Cargo.toml # Rust 依赖
|
||
│ └── tauri.conf.json # Tauri 配置
|
||
├── public/ # 静态资源（图片、图标）
|
||
└── .github/workflows/ # CI/CD 工作流
|
||
```
|
||
|
||
### 前端页面开发约定
|
||
|
||
每个页面是一个独立 JS 模块，导出 `render()` 函数：
|
||
|
||
```javascript
|
||
export async function render() {
|
||
const page = document.createElement('div')
|
||
page.className = 'page'
|
||
page.innerHTML = `<!-- 页面骨架，含加载占位符 -->`
|
||
|
||
// 非阻塞：先返回 DOM，数据在后台异步加载
|
||
loadData(page)
|
||
return page
|
||
}
|
||
```
|
||
|
||
关键原则：`render()` 必须立即返回 DOM 元素，不要 `await` 数据加载，否则会阻塞页面切换。
|
||
|
||
### Rust 跨平台开发约定
|
||
|
||
平台相关代码使用条件编译：
|
||
|
||
```rust
|
||
#[cfg(target_os = "macos")]
|
||
{
|
||
// macOS: launchctl / plist
|
||
}
|
||
#[cfg(target_os = "windows")]
|
||
{
|
||
// Windows: openclaw CLI / tasklist
|
||
}
|
||
```
|
||
|
||
## 分支策略
|
||
|
||
- 所有开发基于 `main` 分支
|
||
- 新功能分支：`feature/功能描述`（例如 `feature/log-export`）
|
||
- 修复分支：`fix/问题描述`（例如 `fix/model-save-crash`）
|
||
- 完成后发起 PR 合并回 `main`
|
||
|
||
## 提交规范
|
||
|
||
提交信息采用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：
|
||
|
||
```
|
||
<类型>(可选范围): 简要描述
|
||
```
|
||
|
||
### 类型说明
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | 修复 Bug |
|
||
| `docs` | 文档变更 |
|
||
| `style` | 代码格式调整（不影响逻辑） |
|
||
| `refactor` | 重构（非新功能、非 Bug 修复） |
|
||
| `perf` | 性能优化 |
|
||
| `test` | 测试相关 |
|
||
| `chore` | 构建/工具/依赖变更 |
|
||
|
||
### 示例
|
||
|
||
```
|
||
feat(model): 新增模型批量测试功能
|
||
fix(gateway): 修复端口配置未生效的问题
|
||
perf(router): 添加模块缓存避免重复加载
|
||
docs: 更新安装说明
|
||
```
|
||
|
||
## PR 流程
|
||
|
||
1. Fork 本仓库并克隆到本地
|
||
2. 从 `main` 创建新分支
|
||
3. 完成开发并进行本地测试
|
||
4. 确保代码风格一致、注释完整
|
||
5. 提交并推送到你的 Fork 仓库
|
||
6. 发起 Pull Request，描述清楚变更内容和测试情况
|
||
7. 等待代码审查，根据反馈修改
|
||
|
||
## 代码规范
|
||
|
||
- **前端**：使用 Vanilla JS，不引入第三方框架
|
||
- **注释**：所有代码注释使用中文
|
||
- **风格**：简洁清晰，避免过度封装
|
||
- **命名**：变量和函数使用驼峰命名（camelCase），CSS 类名使用短横线命名（kebab-case）
|
||
- **资源**：静态资源本地化，禁止引用远程 CDN
|
||
- **异步**：页面 render() 中禁止阻塞式 await，数据加载走后台异步
|
||
|
||
## 问题反馈
|
||
|
||
如果发现 Bug 或有功能建议，欢迎通过 [GitHub Issues](https://github.com/qingchencloud/clawpanel/issues) 提交。
|