HCLIer

开发指南

2026-09-01

H CLIer 开发指南

本文档介绍如何参与 H CLIer 的开发。

开发环境

系统要求

  • 操作系统：Windows 10/11、macOS、Linux
  • Node.js：>= 18
  • Rust：>= 1.70
  • Git：最新版本

工具推荐

  • 编辑器：VS Code
  • Rust 插件：rust-analyzer
  • 前端插件：ESLint、Prettier

快速开始

1. 克隆仓库

git clone https://github.com/Fancyhe1/H-CLIer.git
cd H-CLIer

2. 安装依赖

# 安装前端依赖
cd aicoder
npm install

# Rust 依赖会自动安装

3. 启动开发模式

npm run tauri:dev

这会同时启动：
- Vite 开发服务器（前端）
- Tauri 开发服务器（后端）

项目结构

H-CLIer/
├── aicoder/
│   ├── src/                    # 前端源代码
│   │   ├── components/         # React 组件
│   │   ├── stores/             # Zustand 状态管理
│   │   ├── types/              # TypeScript 类型定义
│   │   ├── hooks/              # 自定义 Hooks
│   │   └── styles/             # CSS 样式
│   ├── src-tauri/              # 后端源代码
│   │   ├── src/
│   │   │   ├── lib.rs          # Tauri 入口
│   │   │   ├── session.rs      # 会话管理
│   │   │   ├── pty.rs          # PTY 终端
│   │   │   └── ...
│   │   ├── Cargo.toml          # Rust 依赖
│   │   └── tauri.conf.json     # Tauri 配置
│   ├── public/                 # 静态资源
│   ├── package.json            # 前端依赖
│   └── vite.config.ts          # Vite 配置
├── docs/                       # 文档
├── README.md                   # 项目说明
└── CHANGELOG.md                # 更新日志

开发流程

1. 创建分支

# 从 main 分支创建功能分支
git checkout -b feature/your-feature-name

分支命名规范：
- feature/xxx：新功能
- fix/xxx：修复 bug
- docs/xxx：文档更新
- refactor/xxx：重构

2. 开发

前端开发

# 启动 Vite 开发服务器（仅前端）
cd aicoder
npm run dev

前端代码修改后会自动热更新。

后端开发

后端代码修改后需要重启 Tauri 开发服务器：

npm run tauri:dev

3. 测试

# 前端测试
npm run test

# 后端测试
cd src-tauri
cargo test

4. 提交代码

# 添加修改
git add .

# 提交
git commit -m "feat: 添加新功能"

# 推送
git push origin feature/your-feature-name

提交信息规范：
- feat: xxx：新功能
- fix: xxx：修复 bug
- docs: xxx：文档更新
- style: xxx：代码格式调整
- refactor: xxx：重构
- test: xxx：测试相关
- chore: xxx：构建/工具相关

5. 创建 Pull Request

  1. 访问 GitHub 仓库
  2. 点击 "New Pull Request"
  3. 填写 PR 描述
  4. 等待代码审查

代码规范

前端（TypeScript）

命名规范

  • 文件名：PascalCase（组件）或 camelCase（工具）
  • 组件：PascalCase
  • 函数：camelCase
  • 常量：SCREAMING_SNAKE_CASE
  • 接口：PascalCase

示例

// 组件
export default function Sidebar({ collapsed }: SidebarProps) {
  // ...
}

// Store
export const useSessionStore = create<SessionState>((set, get) => ({
  // ...
}))

// Hook
export function useTokenPolling() {
  // ...
}

后端（Rust）

命名规范

  • 模块：snake_case
  • 结构体：PascalCase
  • 函数：snake_case
  • 变量：snake_case
  • 常量：SCREAMING_SNAKE_CASE

示例

// 结构体
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Session {
    pub id: String,
    pub project_path: String,
    // ...
}

// 函数
pub fn create_session(&self, project_path: &str) -> Result<Session, String> {
    // ...
}

构建与发布

开发构建

npm run tauri:dev

生产构建

npm run tauri:build

构建产物位于 aicoder/src-tauri/target/release/bundle/。

发布流程

  1. 更新版本号（package.json、Cargo.toml、tauri.conf.json）
  2. 更新 CHANGELOG.md
  3. 创建 Git 标签
  4. 推送到 GitHub
  5. GitHub Actions 自动构建并创建 Release

调试技巧

前端调试

  1. 启动开发模式
  2. 打开 DevTools（Ctrl+Shift+I）
  3. 使用 Console、Network、Elements 面板

后端调试

// 使用 eprintln! 输出日志
eprintln!("[Session] Creating session: {}", id);

// 使用 dbg! 宏
dbg!(&session);

Tauri DevTools

在 tauri.conf.json 中启用：

{
  "app": {
    "windows": [{
      "devtools": true
    }]
  }
}

常见开发问题

Q1：npm install 失败

解决方法：

  1. 清除缓存：npm cache clean --force
  2. 删除 node_modules：rm -rf node_modules
  3. 重新安装：npm install

Q2：cargo build 失败

解决方法：

  1. 更新 Rust：rustup update
  2. 清除构建缓存：cargo clean
  3. 重新构建：cargo build

Q3：热更新不工作

可能原因：

  1. 修改了后端代码（需要重启）
  2. Vite 配置问题
  3. 浏览器缓存

Q4：类型错误

解决方法：

  1. 检查 TypeScript 配置
  2. 运行 npm run type-check
  3. 更新类型定义

贡献指南

如何贡献

  1. 报告 Bug：使用 GitHub Issues
  2. 提出建议：使用 GitHub Discussions
  3. 提交代码：使用 Pull Request
  4. 完善文档：直接提交 PR

代码审查

所有 PR 都需要经过代码审查：

  1. 确保代码符合规范
  2. 确保测试通过
  3. 确保文档更新
  4. 填写清晰的 PR 描述

行为准则

  • 尊重他人
  • 保持专业
  • 欢迎新人
  • 建设性反馈

相关资源

  • Tauri 官方文档：https://tauri.app/v2/guide/
  • React 文档：https://react.dev
  • Rust 文档：https://www.rust-lang.org/learn
  • Zustand 文档：https://zustand-demo.pmnd.rs/

联系方式

  • GitHub Issues：https://github.com/Fancyhe1/H-CLIer/issues
  • 邮箱：[待添加]

最后更新：2026-07-12