222 lines
6.8 KiB
Markdown
222 lines
6.8 KiB
Markdown
# AGENTS.md - Agent Development Guide
|
|
|
|
## Project Overview
|
|
|
|
This is the **Qiming Agent** desktop application - a multi-engine AI assistant that works around the clock.
|
|
|
|
### Core Features
|
|
|
|
- **Multi-Agent Engine**: Supports claude-code and qimingcode
|
|
- **Cross-Platform**: Windows, macOS, Linux
|
|
- **Local Execution**: Runs locally with sandbox option
|
|
- **IM Integration**: Control via Telegram, Discord, DingTalk, Feishu
|
|
- **Persistent Memory**: Remembers user preferences
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### Process Model
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Electron Main Process │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - Window lifecycle │
|
|
│ - SQLite persistence │
|
|
│ - Engine Manager (claude-code/qimingcode) │
|
|
│ - IM Gateways (Telegram/Discord/DingTalk/Feishu) │
|
|
│ - 40+ IPC handlers │
|
|
│ - Context isolation enabled, node integration disabled │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ IPC
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Electron Renderer Process │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - React 18 + Redux Toolkit │
|
|
│ - UI and business logic │
|
|
│ - Communicates via IPC only │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Services
|
|
|
|
### Core Services
|
|
|
|
| Service | File | Description |
|
|
|---------|------|-------------|
|
|
| **Unified Agent** | `unifiedAgent.ts` | SDK-based agent lifecycle, MCP injection |
|
|
| **Engine Manager** | `engineManager.ts` | Agent engine lifecycle |
|
|
| **Shell Environment** | `shellEnv.ts` | Cross-platform shell |
|
|
| **Workspace Manager** | `workspaceManager.ts` | Session workspaces |
|
|
| **Dependencies** | `dependencies.ts` | Package management |
|
|
| **MCP** | `mcp.ts` | MCP server management |
|
|
| **Setup** | `setup.ts` | Setup wizard & auth |
|
|
| **File Server** | `fileServer.ts` | Local file service |
|
|
| **Lanproxy** | `lanproxy.ts` | Intranet penetration |
|
|
| **Skills** | `skills.ts` | Skills sync |
|
|
| **IM** | `im.ts` | Instant messaging |
|
|
| **Scheduler** | `scheduler.ts` | Task scheduling |
|
|
| **Permissions** | `permissions.ts` | Permission control |
|
|
|
|
### Components
|
|
|
|
| Component | Description |
|
|
|-----------|-------------|
|
|
| `SetupWizard.tsx` | 3-step setup wizard |
|
|
| `SettingsPage.tsx` | Settings UI |
|
|
| `AgentSettings.tsx` | Agent configuration |
|
|
| `MCPSettings.tsx` | MCP management |
|
|
| `LanproxySettings.tsx` | Lanproxy config |
|
|
| `SkillsSync.tsx` | Skills sync UI |
|
|
| `IMSettings.tsx` | IM configuration |
|
|
| `TaskSettings.tsx` | Task settings |
|
|
|
|
---
|
|
|
|
## Agent Engines
|
|
|
|
### Supported Engines
|
|
|
|
| Engine | Command | Description |
|
|
|--------|---------|-------------|
|
|
| **claude-code** | `claude-code --sACP` | Default recommended |
|
|
| **qimingcode** | `qimingcode serve --stdio` | Alternative |
|
|
|
|
### Engine Isolation
|
|
|
|
Each engine runs in an isolated environment:
|
|
|
|
```typescript
|
|
{
|
|
// App-internal dependencies injected
|
|
PATH: '~/.qiming-agent/node_modules/.bin:~/.qiming-agent/bin:$PATH',
|
|
NODE_PATH: '~/.qiming-agent/node_modules',
|
|
|
|
// Isolated home
|
|
HOME: '/tmp/qiming-agent-run-xxx',
|
|
XDG_CONFIG_HOME: '/tmp/.../.config',
|
|
CLAUDE_CONFIG_DIR: '/tmp/.../.claude',
|
|
QIMINGCODE_CONFIG_DIR: '/tmp/.../.qimingcode',
|
|
ANTHROPIC_API_KEY: 'xxx',
|
|
ANTHROPIC_BASE_URL: 'xxx',
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
### Required Dependencies
|
|
|
|
| Dependency | Type | Description |
|
|
|------------|------|-------------|
|
|
| **uv** | bundled | Python package manager (>=0.5.0), shipped in extraResources |
|
|
| **qiming-file-server** | npm-local | File service |
|
|
| **qimingcode** | npm-local | Agent engine |
|
|
| **qiming-mcp-stdio-proxy** | npm-local | MCP protocol aggregation proxy |
|
|
|
|
### Installation Locations
|
|
|
|
```
|
|
~/.qiming-agent/
|
|
├── engines/ # Agent engines
|
|
├── workspaces/ # Session workspaces
|
|
├── node_modules/ # Local npm packages
|
|
│ ├── .bin/ # Executable symlinks (injected into PATH)
|
|
│ └── mcp-servers/ # MCP servers (isolated)
|
|
├── bin/ # App binaries
|
|
├── logs/ # Application logs
|
|
└── qiming-agent.db # SQLite database
|
|
```
|
|
|
|
> **Note**: All data is stored under `~/.qiming-agent/`. The Electron `app.getPath('userData')` path is NOT used.
|
|
|
|
---
|
|
|
|
## Session & Workspace
|
|
|
|
### Rule
|
|
|
|
- **One Session = One Workspace**
|
|
- Workspace directory is **user-specified**
|
|
- Each session has independent configuration
|
|
|
|
### Workflow
|
|
|
|
```
|
|
User creates session
|
|
│
|
|
└── Specify workspace directory
|
|
│
|
|
└── Validate directory
|
|
│
|
|
└── Save to config
|
|
│
|
|
└── Engine uses this directory
|
|
```
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development
|
|
npm run electron:dev
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Package
|
|
npm run dist:mac # macOS
|
|
npm run dist:win # Windows
|
|
npm run dist:linux # Linux
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
qiming-agent/
|
|
├── crates/
|
|
│ ├── agent-electron-client/ # Electron client
|
|
│ ├── agent-gui-server/ # GUI agent server (Node.js)
|
|
│ └── qiming-mcp-stdio-proxy/ # MCP proxy (Node.js)
|
|
│
|
|
├── docs/ # Documentation
|
|
├── scripts/ # Build scripts
|
|
└── CHANGELOG.md # Version history
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
- `src/main/main.ts` - Electron main process
|
|
- `src/main/preload.ts` - Preload script
|
|
- `src/App.tsx` - React root
|
|
- `src/services/` - All services
|
|
- `src/components/` - All components
|
|
|
|
---
|
|
|
|
## API Keys
|
|
|
|
Store sensitive configuration in SQLite, not in code:
|
|
|
|
- `anthropic_api_key` - Claude API key
|
|
- `default_model` - Default model
|
|
- `server_host` - Backend server
|
|
|
|
---
|
|
|
|
*Last updated: 2026-02-23*
|