299 lines
8.3 KiB
Markdown
299 lines
8.3 KiB
Markdown
# QimingClaw
|
||
|
||
[English](README_EN.md) | 简体中文
|
||
|
||
[](https://github.com/soddygo/qiming-agent/actions)
|
||
[](LICENSE)
|
||
|
||
多引擎 AI 助手桌面客户端，基于 ACP (Agent Client Protocol) 协议，支持任何兼容 ACP 的 Agent 引擎，提供跨平台的本地 AI Agent 执行能力。
|
||
|
||
## 核心特性
|
||
|
||
### 多引擎支持
|
||
|
||
QimingClaw 采用 [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) 协议与 Agent 引擎通信，支持任何实现了 ACP 协议的 Agent：
|
||
|
||
| 引擎 | 说明 |
|
||
|------|------|
|
||
| **Claude Code** | Anthropic 官方 CLI Agent，推荐使用 ⭐ |
|
||
| **Codex CLI** | OpenAI 的代码 Agent |
|
||
| **Gemini CLI** | Google 的 AI Agent |
|
||
| **GitHub Copilot** | GitHub 的 AI 编程助手 |
|
||
| **Cline** | 开源自主编程 Agent |
|
||
| **Cursor** | Cursor IDE 的 Agent 能力 |
|
||
| **Goose** | Block 开源的 AI Agent |
|
||
| **Qwen Code** | 阿里通义千问代码 Agent |
|
||
| **Junie** | JetBrains 的 AI Agent |
|
||
| **OpenCode** | 开源代码 Agent |
|
||
| **QimingCode** | 基于 OpenCode 修改的 Agent 引擎 |
|
||
| **更多...** | [查看完整列表](https://agentclientprotocol.com/get-started/agents) |
|
||
|
||
> **ACP 协议**: Agent Client Protocol，标准化编辑器/IDE 与 AI Agent 之间的通信协议，基于 NDJSON 格式。类似 LSP 之于语言服务，ACP 让你可以将任何 ACP 兼容的 Agent 接入到任何支持的客户端。
|
||
|
||
- 引擎隔离运行，独立环境配置
|
||
- 动态切换引擎，无需重启应用
|
||
- 避免厂商锁定，自由选择 Agent
|
||
|
||
### 跨平台客户端
|
||
- **Electron 客户端** - 基于 Electron + React 的桌面客户端
|
||
|
||
### MCP 协议支持
|
||
- 动态 MCP 服务器管理
|
||
- 多协议支持 (stdio, SSE, Streamable HTTP)
|
||
- 弹性连接与自动重连
|
||
|
||
### 其他特性
|
||
- **持久化存储** - SQLite 本地存储
|
||
- **系统托盘** - 后台运行，快速操作
|
||
|
||
## 项目架构
|
||
|
||
```
|
||
qiming-agent-client/
|
||
├── crates/
|
||
│ ├── agent-electron-client/ # Electron 客户端 (主要开发)
|
||
│ ├── qiming-mcp-stdio-proxy/ # MCP 协议聚合代理
|
||
│ ├── agent-gpui-client/ # GPUI 客户端 (实验性)
|
||
│ ├── agent-server-admin/ # 管理端 API 服务
|
||
│ ├── agent-protocol/ # 通信协议定义
|
||
│ ├── system-permissions/ # 系统权限管理
|
||
│ └── qiming-agent-core/ # 核心逻辑 (Rust)
|
||
└── vendors/ # 第三方依赖
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### Electron 客户端
|
||
|
||
```bash
|
||
# 方式一：使用 Makefile（推荐，项目根目录执行）
|
||
make electron-dev # 开发模式
|
||
make electron-build # 构建
|
||
make electron-dist # 打包
|
||
|
||
# 方式二：进入目录执行 npm 命令
|
||
cd crates/agent-electron-client
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发模式
|
||
npm run dev
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 打包
|
||
npm run dist:mac # macOS
|
||
npm run dist:win # Windows
|
||
npm run dist:linux # Linux
|
||
```
|
||
|
||
### MCP 代理服务
|
||
|
||
```bash
|
||
cd crates/qiming-mcp-stdio-proxy
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 运行 (stdio 聚合模式)
|
||
qiming-mcp-stdio-proxy --config '{"mcpServers":{...}}'
|
||
|
||
# 运行 (协议转换模式)
|
||
qiming-mcp-stdio-proxy convert http://remote-mcp-server/sse
|
||
|
||
# 运行 (持久化桥接模式)
|
||
qiming-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'
|
||
```
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 架构 | 状态 |
|
||
|------|------|:----:|
|
||
| macOS | arm64, x86_64 | ✅ |
|
||
| Windows | x86_64, arm64 | ✅ |
|
||
| Linux | x86_64, arm64 | ✅ |
|
||
|
||
## Electron 客户端详解
|
||
|
||
### 技术栈
|
||
- **主进程**: Electron + TypeScript
|
||
- **渲染进程**: React 18 + Ant Design
|
||
- **存储**: SQLite (better-sqlite3)
|
||
- **构建**: Vite + electron-builder
|
||
|
||
### 核心服务
|
||
|
||
| 服务 | 说明 |
|
||
|------|------|
|
||
| Unified Agent | 统一的 ACP 引擎管理 |
|
||
| Engine Manager | 引擎生命周期管理 |
|
||
| MCP | MCP 服务器管理 |
|
||
| Dependencies | 依赖包管理 |
|
||
| Permissions | 权限控制 |
|
||
|
||
### 数据存储
|
||
|
||
```
|
||
~/.qimingclaw/
|
||
├── engines/ # Agent 引擎
|
||
├── workspaces/ # 会话工作空间
|
||
├── node_modules/ # 本地 npm 包
|
||
│ ├── .bin/ # 可执行文件
|
||
│ └── mcp-servers/ # MCP 服务器
|
||
├── bin/ # 应用二进制
|
||
├── logs/ # 日志文件
|
||
│ ├── main.log # 主进程日志
|
||
│ └── mcp-proxy.log # MCP 代理日志
|
||
└── qimingclaw.db # SQLite 数据库
|
||
```
|
||
|
||
### IPC 通道
|
||
|
||
| 分类 | 通道 |
|
||
|------|------|
|
||
| Session | `session:list`, `session:create`, `session:delete` |
|
||
| Message | `message:list`, `message:add` |
|
||
| Settings | `settings:get`, `settings:set` |
|
||
| Agent | `agent:init`, `agent:destroy`, `agent:prompt` |
|
||
| MCP | `mcp:install`, `mcp:uninstall`, `mcp:start`, `mcp:stop` |
|
||
|
||
## MCP 代理服务详解
|
||
|
||
`qiming-mcp-stdio-proxy` 是一个 MCP 协议聚合代理，解决多 MCP 服务器集成时的生命周期管理问题。
|
||
|
||
### 运行模式
|
||
|
||
| 模式 | 用途 | 命令 |
|
||
|------|------|------|
|
||
| **stdio** | 聚合多个 MCP 服务器为单个 stdio 接口 | `qiming-mcp-stdio-proxy --config '...'` |
|
||
| **convert** | 将远程 MCP 服务转换为本地 stdio | `qiming-mcp-stdio-proxy convert <url>` |
|
||
| **proxy** | 持久化桥接，预先启动并暴露 HTTP 接口 | `qiming-mcp-stdio-proxy proxy --port 18099` |
|
||
|
||
### 核心特性
|
||
- **就绪状态检测**: 阻塞等待 MCP 服务器就绪
|
||
- **弹性传输**: 心跳检测、指数退避重连、请求队列
|
||
- **集中清理**: 优雅终止所有子进程
|
||
|
||
### 弹性传输参数
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `pingIntervalMs` | 20000 | 心跳间隔 |
|
||
| `maxConsecutiveFailures` | 3 | 连续失败阈值 |
|
||
| `maxReconnectDelayMs` | 60000 | 重连延迟上限 |
|
||
| `maxQueueSize` | 100 | 请求队列容量 |
|
||
|
||
## 配置说明
|
||
|
||
### Electron 客户端配置
|
||
|
||
首次运行时通过设置向导配置：
|
||
1. 输入 Anthropic API Key
|
||
2. 选择默认模型
|
||
3. 配置 MCP 服务器
|
||
|
||
敏感配置存储在 SQLite 数据库中，不在代码中硬编码。
|
||
|
||
### MCP 服务器配置示例
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
|
||
},
|
||
"github": {
|
||
"url": "https://api.github.com/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
crates/agent-electron-client/
|
||
├── src/
|
||
│ ├── main/ # 主进程
|
||
│ │ ├── main.ts # 入口
|
||
│ │ ├── preload.ts # 预加载脚本
|
||
│ │ ├── ipc/ # IPC 处理器
|
||
│ │ └── services/ # 主进程服务
|
||
│ ├── renderer/ # 渲染进程
|
||
│ │ ├── main.tsx # React 入口
|
||
│ │ ├── App.tsx # 主组件
|
||
│ │ ├── components/ # React 组件
|
||
│ │ └── services/ # 渲染进程服务
|
||
│ └── shared/ # 共享代码
|
||
├── resources/ # 打包资源
|
||
├── scripts/ # 构建脚本
|
||
└── package.json
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# Electron 客户端
|
||
cd crates/agent-electron-client
|
||
npm run test
|
||
|
||
# MCP 代理
|
||
cd crates/qiming-mcp-stdio-proxy
|
||
npm run test:run
|
||
npm run test:coverage
|
||
```
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
# 启用详细日志
|
||
RUST_LOG=debug npm run dev
|
||
```
|
||
|
||
## GitHub Actions
|
||
|
||
### CI/CD 工作流
|
||
|
||
| 工作流 | 触发条件 | 说明 |
|
||
|--------|----------|------|
|
||
| `ci-electron.yml` | `crates/agent-electron-client/**` 变更 | Electron 测试构建 |
|
||
| `release-electron.yml` | 推送 `electron-v*` tag | Electron 发布构建 |
|
||
|
||
### 发布流程
|
||
|
||
```bash
|
||
# Electron 发布
|
||
git tag electron-v0.9.0
|
||
git push origin electron-v0.9.0
|
||
```
|
||
|
||
## 许可证
|
||
|
||
[Apache License 2.0](LICENSE)
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
1. Fork 本仓库
|
||
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'Add amazing feature'`)
|
||
4. 推送分支 (`git push origin feature/amazing-feature`)
|
||
5. 创建 Pull Request
|
||
|
||
详见 [CONTRIBUTING.md](CONTRIBUTING.md)
|
||
|
||
## 相关项目
|
||
|
||
- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架
|
||
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
|
||
- [Ant Design](https://ant.design/) - React UI 组件库
|