chore: initialize qiming workspace repository
This commit is contained in:
Codex
221
qimingclaw/AGENTS.md
Normal file
221
qimingclaw/AGENTS.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user