qiming/qimingclaw/README.md

QimingClaw

English | 简体中文

多引擎 AI 助手桌面客户端，基于 ACP (Agent Client Protocol) 协议，支持任何兼容 ACP 的 Agent 引擎，提供跨平台的本地 AI Agent 执行能力。

核心特性

多引擎支持

QimingClaw 采用 ACP (Agent Client Protocol) 协议与 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 引擎
更多...	查看完整列表

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 客户端

# 方式一：使用 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 代理服务

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 服务器配置示例

{
  "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

运行测试

# Electron 客户端
cd crates/agent-electron-client
npm run test

# MCP 代理
cd crates/qiming-mcp-stdio-proxy
npm run test:run
npm run test:coverage

调试模式

# 启用详细日志
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 发布构建

发布流程

# Electron 发布
git tag electron-v0.9.0
git push origin electron-v0.9.0

许可证

Apache License 2.0

贡献指南

欢迎提交 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

相关项目

• Electron - 跨平台桌面应用框架
• MCP - Model Context Protocol
• Ant Design - React UI 组件库