企业官网建设流程全解析

Hope Agent 是一款基于Rust + Tauri 2 + React 19的跨端桌面 AI 助手，内置记忆、自主目标推进与多 Agent 动态编排能力，也可服务化常驻 NAS / 云端。本教程面向新手，带你在 6 个步骤内完成仓库克隆、项目跑通、分层架构理解，并贡献你的第一个 PR——即使前端和 Rust 经验不深，也能照做。

一、项目速览：Hope Agent 技术栈与目录结构

Hope Agent 同一个二进制支持三种运行模式：桌面 GUI（Tauri）、HTTP/WS 守护进程、ACP stdio（供 IDE 直连）。完整技术选型如下：

目录职责清晰，新手建议按这个顺序阅读：

• src/：React 19 前端，路径别名@/指向src/
• crates/：全部 Rust crate，业务逻辑所在
• src-tauri/：Tauri 桌面薄壳
• docs/architecture/：子系统架构文档，改代码前必读
• skills/：内置 Agent 技能，最适合新手贡献

核心设计原则只有一条：所有业务逻辑都在与界面无关的后端 crate 里，前端和 Tauri / HTTP 服务都只是薄壳——同一套能力被桌面、服务器、CLI 三种入口复用。完整分层图见官方文档系统架构总览。

二、环境搭建：3 步跑通 Hope Agent 项目

1. 前置工具链

• Node.js + pnpm（前端与 Tauri CLI 依赖）
• Rust 工具链：由 rust-toolchain.toml 锁定在1.95.0，首次构建时 rustup 会自动安装对应工具链

2. 克隆仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/ho/hope-agent cd hope-agent pnpm install # 安装前端依赖 + Husky pre-push 钩子

3. 一键启动桌面开发模式

pnpm dev:desktop # 前端 + Rust 后端 + 热重载

启动后即可看到完整功能界面：左侧管理会话 / 项目 / 定时任务，右侧实时展示记忆、上下文用量与会话状态：

💡 浏览器或评测联调请选pnpm desktop；只查某个 Rust 包可用cargo check -p <crate> --locked。全部命令速查见 AGENTS.md「开发与验证」。

三、读懂核心架构：请求如何从 React 19 流进 Rust

一次请求的处理路径是理解工程分层的关键：

1. 前端（React 19）：Chat、Dashboard、知识空间等 UI 组件
2. Transport 抽象层：Tauri IPC 或 HTTP/WS 双模式自动切换
3. 薄壳层：src-tauri/（桌面）或 crates/ha-server/（HTTP 服务）
4. 后端 crate：特征 crate →ha-core（内核）→ha-config-schema→ha-base

后端四层分工如下：

知识空间就是一个典型的「特征 crate + 前端联动」子系统：

修改代码前记住三条硬规则（详见核心架构边界）：

• 核心业务逻辑必须进crates/ha-core/或特征 crate，零 Tauri 依赖
• src-tauri/与crates/ha-server/只做适配薄壳，不写业务逻辑
• 禁止console.log/log::info!等原生日志，统一使用app_info!系列宏

四、新手第一个贡献：4 个低门槛方向

项目 CONTRIBUTING.md 推荐了明确的贡献入口，按门槛从低到高排列：

1. 改文档 / 修 typo（最简单）

直接开 PR 即可，无需先开 issue。

2. 翻译贡献（12 种语言）

翻译文件在 src/i18n/locales/，zh与en是真相源。用脚本一键检查缺失项：

node scripts/sync-i18n.mjs --check # 检查缺失翻译

3. 加一个新 Skill

skills/ 下每个目录就是一个技能（SKILL.md+ 可选脚本）。参考 ha-skill-creator 技能说明 即可照着创作，是理解「Agent 如何被技能扩展」的最佳路径。

4. 接入新 LLM Provider 或 IM Channel

• Provider：接入点 crates/ha-core/src/provider/，复用现有 4 种协议的多数情况只加配置，无需写 Rust
• Channel：参考 crates/ha-channel/src/channel/ 里 12 个现成实现（webhook 型最简单）

设计空间是前端 / 后端边界研究的好去处，适合想在跑通项目后深挖 Tauri 命令与特征 crate 联动的贡献者：

五、提交前自检：让你的 PR 顺利过 CI

1. pre-push 六道自动门禁（强制）

git push之前，.husky/pre-push 钩子会自动跑 6 条检查（清单见 CONTRIBUTING.md）：

cargo fmt --all --check # 格式检查 cargo clippy ... -D warnings # 静态检查，警告即错误 cargo test ... # Rust 单测 pnpm typecheck # TS 类型检查 pnpm lint # ESLint pnpm test # Vitest

⚠️不要用--no-verify绕过——CI 会再跑一遍同样检查并阻塞 PR。

2. Commit message 规范

<type>(<scope>): <一句话描述>

• type：feat/fix/docs/ci/chore/refactor/perf/test
• scope：子系统名（chat/provider/channel/skill/plan…）
• ✅feat(provider): 升级内置模型模板的 provider/model 列表
• ❌update code/fix bug
• 每个 commit 用git commit -s加 DCO 签名（原创性声明）

3. 两个容易漏的同步义务

• 用户可见改动必须写进 CHANGELOG.md 的Unreleased段
• 子系统架构变化必须在同一 PR 内同步docs/architecture/<name>.md

4. Squash merge

PR 以 squash 方式合入 main 保持线性，所以单个 PR 只聚焦一件事，大改动请拆成多个 PR。

六、常用开发命令速查表

📚 学习资源清单

• CONTRIBUTING.md —— 贡献流程完整说明（报 Bug / 提 PR / 翻译 / 插件式贡献）
• AGENTS.md —— 全局约束与任务入口，改跨 crate 契约前必读
• docs/architecture/overview.md —— 系统架构总览
• docs/architecture/ —— 按子系统拆分的架构设计文档
• docs/user-guide/ —— 用户手册（中英双语）

至此，Hope Agent 的贡献路径已经打通：克隆仓库 → 跑通项目 → 读懂分层 → 从文档 / 翻译 / 技能入手 → 通过六道门禁 → 提交 squash PR。祝你在源码中玩得开心！🎉