chore: initialize qiming workspace repository
This commit is contained in:
Codex
298
qimingclaw/README_EN.md
Normal file
298
qimingclaw/README_EN.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# QimingClaw
|
||||
|
||||
English | [简体中文](README.md)
|
||||
|
||||
[](https://github.com/soddygo/qiming-agent/actions)
|
||||
[](LICENSE)
|
||||
|
||||
Multi-engine AI assistant desktop client based on ACP (Agent Client Protocol), supporting any ACP-compatible Agent engine with cross-platform local AI Agent execution capabilities.
|
||||
|
||||
## Core Features
|
||||
|
||||
### Multi-Engine Support
|
||||
|
||||
QimingClaw uses [ACP (Agent Client Protocol)](https://agentclientprotocol.com/) to communicate with Agent engines, supporting any ACP-compatible Agent:
|
||||
|
||||
| Engine | Description |
|
||||
|--------|-------------|
|
||||
| **Claude Code** | Anthropic's official CLI Agent, recommended ⭐ |
|
||||
| **Codex CLI** | OpenAI's code Agent |
|
||||
| **Gemini CLI** | Google's AI Agent |
|
||||
| **GitHub Copilot** | GitHub's AI coding assistant |
|
||||
| **Cline** | Open-source autonomous coding Agent |
|
||||
| **Cursor** | Cursor IDE's Agent capability |
|
||||
| **Goose** | Block's open-source AI Agent |
|
||||
| **Qwen Code** | Alibaba's Qwen code Agent |
|
||||
| **Junie** | JetBrains' AI Agent |
|
||||
| **OpenCode** | Open-source code Agent |
|
||||
| **QimingCode** | Agent engine based on OpenCode |
|
||||
| **More...** | [View full list](https://agentclientprotocol.com/get-started/agents) |
|
||||
|
||||
> **ACP Protocol**: Agent Client Protocol standardizes communication between code editors/IDEs and AI coding agents. Similar to how LSP works for language services, ACP lets you connect any ACP-compatible Agent to any supporting client.
|
||||
|
||||
- Isolated engine execution with independent environment configuration
|
||||
- Dynamic engine switching without app restart
|
||||
- Avoid vendor lock-in, choose your Agent freely
|
||||
|
||||
### Cross-Platform Clients
|
||||
- **Electron Client** - Desktop client based on Electron + React
|
||||
|
||||
### MCP Protocol Support
|
||||
- Dynamic MCP server management
|
||||
- Multi-protocol support (stdio, SSE, Streamable HTTP)
|
||||
- Resilient connection with automatic reconnection
|
||||
|
||||
### Other Features
|
||||
- **Persistent Storage** - SQLite local storage
|
||||
- **System Tray** - Background operation with quick actions
|
||||
|
||||
## Project Architecture
|
||||
|
||||
```
|
||||
qiming-agent-client/
|
||||
├── crates/
|
||||
│ ├── agent-electron-client/ # Electron client (primary development)
|
||||
│ ├── qiming-mcp-stdio-proxy/ # MCP protocol aggregation proxy
|
||||
│ ├── agent-gpui-client/ # GPUI client (experimental)
|
||||
│ ├── agent-server-admin/ # Admin API service
|
||||
│ ├── agent-protocol/ # Communication protocol definitions
|
||||
│ ├── system-permissions/ # System permission management
|
||||
│ └── qiming-agent-core/ # Core logic (Rust)
|
||||
└── vendors/ # Third-party dependencies
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Electron Client
|
||||
|
||||
```bash
|
||||
# Option 1: Using Makefile (recommended, run from project root)
|
||||
make electron-dev # Development mode
|
||||
make electron-build # Build
|
||||
make electron-dist # Package
|
||||
|
||||
# Option 2: Using npm commands in the crate directory
|
||||
cd crates/agent-electron-client
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Development mode
|
||||
npm run dev
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Package
|
||||
npm run dist:mac # macOS
|
||||
npm run dist:win # Windows
|
||||
npm run dist:linux # Linux
|
||||
```
|
||||
|
||||
### MCP Proxy Service
|
||||
|
||||
```bash
|
||||
cd crates/qiming-mcp-stdio-proxy
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Run (stdio aggregation mode)
|
||||
qiming-mcp-stdio-proxy --config '{"mcpServers":{...}}'
|
||||
|
||||
# Run (protocol conversion mode)
|
||||
qiming-mcp-stdio-proxy convert http://remote-mcp-server/sse
|
||||
|
||||
# Run (persistent bridge mode)
|
||||
qiming-mcp-stdio-proxy proxy --port 18099 --config '{"mcpServers":{...}}'
|
||||
```
|
||||
|
||||
## Platform Support
|
||||
|
||||
| Platform | Architecture | Status |
|
||||
|----------|--------------|:------:|
|
||||
| macOS | arm64, x86_64 | ✅ |
|
||||
| Windows | x86_64, arm64 | ✅ |
|
||||
| Linux | x86_64, arm64 | ✅ |
|
||||
|
||||
## Electron Client Details
|
||||
|
||||
### Tech Stack
|
||||
- **Main Process**: Electron + TypeScript
|
||||
- **Renderer Process**: React 18 + Ant Design
|
||||
- **Storage**: SQLite (better-sqlite3)
|
||||
- **Build**: Vite + electron-builder
|
||||
|
||||
### Core Services
|
||||
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| Unified Agent | Unified ACP engine management |
|
||||
| Engine Manager | Engine lifecycle management |
|
||||
| MCP | MCP server management |
|
||||
| Dependencies | Package management |
|
||||
| Permissions | Permission control |
|
||||
|
||||
### Data Storage
|
||||
|
||||
```
|
||||
~/.qimingclaw/
|
||||
├── engines/ # Agent engines
|
||||
├── workspaces/ # Session workspaces
|
||||
├── node_modules/ # Local npm packages
|
||||
│ ├── .bin/ # Executables
|
||||
│ └── mcp-servers/ # MCP servers
|
||||
├── bin/ # App binaries
|
||||
├── logs/ # Log files
|
||||
│ ├── main.log # Main process log
|
||||
│ └── mcp-proxy.log # MCP proxy log
|
||||
└── qimingclaw.db # SQLite database
|
||||
```
|
||||
|
||||
### IPC Channels
|
||||
|
||||
| Category | Channels |
|
||||
|----------|----------|
|
||||
| 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 Proxy Service Details
|
||||
|
||||
`qiming-mcp-stdio-proxy` is an MCP protocol aggregation proxy that solves lifecycle management issues when integrating multiple MCP servers.
|
||||
|
||||
### Running Modes
|
||||
|
||||
| Mode | Purpose | Command |
|
||||
|------|---------|---------|
|
||||
| **stdio** | Aggregate multiple MCP servers into single stdio interface | `qiming-mcp-stdio-proxy --config '...'` |
|
||||
| **convert** | Convert remote MCP service to local stdio | `qiming-mcp-stdio-proxy convert <url>` |
|
||||
| **proxy** | Persistent bridge, pre-start and expose HTTP interface | `qiming-mcp-stdio-proxy proxy --port 18099` |
|
||||
|
||||
### Core Features
|
||||
- **Readiness Detection**: Block until MCP servers are ready
|
||||
- **Resilient Transport**: Heartbeat detection, exponential backoff reconnection, request queue
|
||||
- **Centralized Cleanup**: Gracefully terminate all child processes
|
||||
|
||||
### Resilient Transport Parameters
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `pingIntervalMs` | 20000 | Heartbeat interval |
|
||||
| `maxConsecutiveFailures` | 3 | Consecutive failure threshold |
|
||||
| `maxReconnectDelayMs` | 60000 | Reconnection delay cap |
|
||||
| `maxQueueSize` | 100 | Request queue capacity |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Electron Client Configuration
|
||||
|
||||
Configure through setup wizard on first run:
|
||||
1. Enter Anthropic API Key
|
||||
2. Select default model
|
||||
3. Configure MCP servers
|
||||
|
||||
Sensitive configuration is stored in SQLite database, not hardcoded.
|
||||
|
||||
### MCP Server Configuration Example
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"filesystem": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
|
||||
},
|
||||
"github": {
|
||||
"url": "https://api.github.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development Guide
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
crates/agent-electron-client/
|
||||
├── src/
|
||||
│ ├── main/ # Main process
|
||||
│ │ ├── main.ts # Entry point
|
||||
│ │ ├── preload.ts # Preload script
|
||||
│ │ ├── ipc/ # IPC handlers
|
||||
│ │ └── services/ # Main process services
|
||||
│ ├── renderer/ # Renderer process
|
||||
│ │ ├── main.tsx # React entry
|
||||
│ │ ├── App.tsx # Main component
|
||||
│ │ ├── components/ # React components
|
||||
│ │ └── services/ # Renderer services
|
||||
│ └── shared/ # Shared code
|
||||
├── resources/ # Packaged resources
|
||||
├── scripts/ # Build scripts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Electron client
|
||||
cd crates/agent-electron-client
|
||||
npm run test
|
||||
|
||||
# MCP proxy
|
||||
cd crates/qiming-mcp-stdio-proxy
|
||||
npm run test:run
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable verbose logging
|
||||
RUST_LOG=debug npm run dev
|
||||
```
|
||||
|
||||
## GitHub Actions
|
||||
|
||||
### CI/CD Workflows
|
||||
|
||||
| Workflow | Trigger | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ci-electron.yml` | `crates/agent-electron-client/**` changes | Electron test build |
|
||||
| `release-electron.yml` | Push `electron-v*` tag | Electron release build |
|
||||
|
||||
### Release Process
|
||||
|
||||
```bash
|
||||
# Electron release
|
||||
git tag electron-v0.9.0
|
||||
git push origin electron-v0.9.0
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
|
||||
## Contributing
|
||||
|
||||
Issues and Pull Requests are welcome!
|
||||
|
||||
1. Fork this repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Create a Pull Request
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
|
||||
|
||||
## Related Projects
|
||||
|
||||
- [Electron](https://www.electronjs.org/) - Cross-platform desktop app framework
|
||||
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
|
||||
- [Ant Design](https://ant.design/) - React UI component library
|
||||
Reference in New Issue
Block a user