183 lines
7.9 KiB
Markdown
183 lines
7.9 KiB
Markdown
<p align="center">
|
||
<img src="src/assets/logo.svg" width="120" height="120" alt="智念助手 Logo" />
|
||
</p>
|
||
|
||
<h1 align="center">智念助手</h1>
|
||
|
||
<p align="center">
|
||
<strong>只有你的需要</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
面向普通企业人员的 AI Agent 桌面工作台，基于 OpenClaw 内核构建。
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue" alt="Platform" />
|
||
<img src="https://img.shields.io/badge/Electron-40+-47848F?logo=electron" alt="Electron" />
|
||
<img src="https://img.shields.io/badge/React-19-61DAFB?logo=react" alt="React" />
|
||
<img src="https://img.shields.io/badge/OpenClaw-runtime-0369A1" alt="OpenClaw runtime" />
|
||
</p>
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
智念助手是一款面向 B 端客户的桌面端 AI 产品。它将 OpenClaw 的 Agent、能力包、渠道、定时任务等底层能力封装为更适合普通企业人员使用的桌面工作台，减少开发者术语暴露，让用户通过对话、快捷任务、知识库和内置应用完成业务工作。
|
||
|
||
当前项目来源于 ClawX 开源桌面端能力，并在此基础上进行了产品化改造：品牌更名为“智念助手”，重构了登录、组织空间、首页、应用中心、能力包、知识库、设置、初始化、打包与运行时依赖链路。
|
||
|
||
当前版本：`0.1.24` 正式版。仓库默认分支 `main` 保持最新可运行代码，正式发布标签 `v0.1.24` 对应当前发布版本。
|
||
|
||
## 快速安装使用最新版
|
||
|
||
适合客户、测试人员或交付同事从仓库直接启动最新版本：
|
||
|
||
```bash
|
||
git clone https://git.nianxx.cn/wangxuming/NianToB.git yinian-desktop
|
||
cd yinian-desktop
|
||
git checkout main
|
||
git pull --ff-only
|
||
corepack enable
|
||
pnpm install
|
||
cp .env.example .env.local
|
||
printf "\nYINIAN_CONTROL_PLANE_MODE=mock\n" >> .env.local
|
||
pnpm dev
|
||
```
|
||
|
||
开发模式会启动 Vite 与 Electron，并由桌面端管理本地 Host API 与 OpenClaw Gateway。离线演示模式不需要真实服务端凭据；如果需要连接真实组织空间，请从部署负责人处获取服务地址和 OAuth 客户端配置，写入本机 `.env.local`。
|
||
|
||
仓库只保留 `.env.example` 占位模板，不提交真实 API key、token、client secret、证书或客户专属服务端点。
|
||
|
||
## 核心能力
|
||
|
||
- **账号登录与组织空间**：通过服务端账号密码登录，一个账号对应一个组织空间；本地可维护组织空间展示名称与桌面端用户名称。
|
||
- **桌面对话**：默认以桌面端新会话开始工作，支持多轮上下文、长任务状态提示、知识库上下文选择和快捷任务注入。
|
||
- **能力包**：将 OpenClaw skills 转为普通用户更容易理解的“能力包”，支持服务端下发、本地安装和快捷任务配置。
|
||
- **快捷任务**：用户在对话前选择一个快捷任务，输入框会注入不可编辑的默认提示词，用于稳定触发指定能力包。
|
||
- **知识库**：支持文本类资料导入，包含 Word 等常用格式；导入后会复制到本地安全目录，避免源文件删除后丢失。
|
||
- **定时任务**：面向用户可见、可管理的自动化任务能力，与 OpenClaw 内部 heartbeat 机制分离。
|
||
- **渠道管理**：支持渠道和账号绑定，渠道账号可维护备注；新增渠道时会自动创建对应 Agent，删除渠道时同步清理绑定 Agent。
|
||
- **应用中心**：保留固定业务应用入口；当前不再内置业务应用，后续由产品交付节奏重新接入。
|
||
- **初始化流程**：首次打开时引导安装或重装 OpenClaw 运行环境，并准备必要依赖；模型 API 与服务端配置通过本机环境或服务端下发，不随仓库提交。
|
||
- **运行维护**：管理员模式下提供模型配置诊断、Gateway 状态、OpenClaw 运行信息和高级排查入口。
|
||
|
||
## 技术栈
|
||
|
||
- 桌面框架：Electron
|
||
- 前端框架：React 19、TypeScript、Vite
|
||
- UI：Tailwind CSS、Radix UI、Lucide Icons
|
||
- 状态管理：Zustand
|
||
- Agent 内核：OpenClaw Gateway
|
||
- 包管理：pnpm
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
yinian-desktop/
|
||
├── electron/ # Electron Main、Host API、Gateway 管理与运行时工具
|
||
│ ├── api/ # 本地 Host API 路由
|
||
│ ├── gateway/ # OpenClaw Gateway 生命周期和依赖管理
|
||
│ ├── main/ # Electron 主进程入口与 IPC
|
||
│ └── utils/ # 初始化、配置、打包、诊断等工具
|
||
├── resources/ # 图标、内置资源、预装能力包资源
|
||
├── scripts/ # 打包、OpenClaw bundle、预装能力包等脚本
|
||
├── shared/ # Main / Renderer 共享类型
|
||
├── src/ # Renderer 前端
|
||
│ ├── components/ # 公共组件
|
||
│ ├── i18n/ # 中英文等语言资源
|
||
│ ├── pages/ # 首页、对话、应用中心、知识库、设置等页面
|
||
│ ├── stores/ # 前端状态管理
|
||
│ └── styles/ # 全局样式
|
||
└── tests/ # 单元测试
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 20+
|
||
- pnpm 9+
|
||
- macOS 开发打包建议使用 Apple Silicon 环境验证 arm64 包
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 启动开发环境
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
开发模式会启动 Vite 与 Electron，并由桌面端管理本地 Host API 与 OpenClaw Gateway。
|
||
|
||
### 常用检查
|
||
|
||
```bash
|
||
pnpm run typecheck
|
||
pnpm test
|
||
pnpm run build:vite
|
||
```
|
||
|
||
### 正式打包
|
||
|
||
macOS Apple Silicon 正式包：
|
||
|
||
```bash
|
||
pnpm run prep:mac-binaries:arm64
|
||
pnpm run package
|
||
pnpm exec electron-builder --mac --arm64 --publish never
|
||
```
|
||
|
||
通用 macOS 正式包：
|
||
|
||
```bash
|
||
pnpm run package:mac
|
||
```
|
||
|
||
打包前脚本会准备 OpenClaw runtime、OpenClaw plugins、预装能力包、Node/uv 等必要运行资源。
|
||
|
||
真实密钥应只通过 CI Secret、本机环境变量或服务端下发进入运行时，不应进入 git 仓库。
|
||
|
||
## 运行时说明
|
||
|
||
- 智念助手会优先使用桌面端托管的 OpenClaw runtime。
|
||
- 初始化流程会安装并修正 OpenClaw 配置，减少客户本机历史环境影响。
|
||
- OpenClaw agent heartbeat 已在智念托管配置中关闭，自动化任务统一使用智念助手的“定时任务”功能。
|
||
- 更新能力当前以服务端下发为目标，正式包不依赖 ClawX 原始 GitHub Release。
|
||
- 真实服务端地址、账号、权限、密钥和计费后续由服务端统一管理，桌面端不暴露正式凭证。
|
||
|
||
## 服务端接口
|
||
|
||
当前已接入账号密码登录，并预留组织空间、能力包下发、渠道与应用服务等服务端协作边界。
|
||
|
||
如果服务端能力尚未完整提供，桌面端会保留必要的本地兜底逻辑，以保证安装、初始化、对话、知识库与应用中心可测试。
|
||
|
||
## 验证重点
|
||
|
||
每次进入可交付验证前，建议至少覆盖：
|
||
|
||
- 登录与会话恢复
|
||
- 首次初始化与 OpenClaw runtime 安装
|
||
- 普通桌面对话与多轮上下文
|
||
- 长任务状态保持与错误提示
|
||
- 能力包列表、本地安装与快捷任务触发
|
||
- 知识库上传、备份、删除与对话上下文选择
|
||
- 定时任务创建、启停与执行记录
|
||
- 应用中心空状态与导航入口
|
||
- 设置页管理员模式、模型诊断、渠道管理
|
||
- macOS arm64 安装包启动、权限、签名与公证
|
||
|
||
## 与 ClawX / OpenClaw 的关系
|
||
|
||
智念助手使用 OpenClaw 作为 Agent 运行内核，并参考了 ClawX 的桌面端工程基础。当前仓库已经面向智念助手产品目标进行定制开发，不再作为原 ClawX 通用客户端维护。
|
||
|
||
后续如果同步上游 OpenClaw 或 ClawX 的能力，需要以智念助手的产品边界、普通企业用户体验和正式交付稳定性为优先。
|
||
|
||
## License
|
||
|
||
本项目基于 MIT License 的开源工程进行二次开发。内部业务代码、品牌素材、服务端协议与交付配置请按团队协作规范使用。
|