qiming/qimingclaw/AGENTS.md

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:

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

# 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