Content
# Tool List
> A multi-agent AI assistant running on your computer - read and write files, execute commands, search the web, analyze images, and act as a robot on Lark/QQ, supporting remote agent collaboration.
## Table of Contents
- [Tool List](#tool-list)
- [Features](#features)
- [Architecture Overview](#architecture-overview)
- [Quick Start](#quick-start)
- [Model Configuration](#model-configuration)
- [Slash Commands](#slash-commands)
- [Tool List](#tool-list)
- [Permission Modes](#permission-modes)
- [Skill System](#skill-system)
- [Chat Platform Integration](#chat-platform-integration)
- [Remote Agent Collaboration (A2A)](#remote-agent-collaboration-a2a)
- [Web Interface](#web-interface)
- [Environment Variables](#environment-variables)
- [Development and Testing](#development-and-testing)
- [Project Structure](#project-structure)
## Features
| Feature | Description |
| --- | --- |
| **Multi-Agent Architecture** | Central orchestrator coordinates multiple expert subprocesses (tool agents, skill agents, communication agents) |
| **LLM Agnostic** | Supports OpenAI, Anthropic, DeepSeek, Xiaomi MiMo, and any custom endpoint compatible with OpenAI protocol |
| **Comprehensive Toolset** | 13 built-in tools: file I/O, terminal commands, web search/scraping, image analysis, memory snapshots, etc. |
| **Three-Level Permission Control** | Read-only / writable / full access, with permissions enforced at authorization boundaries |
| **Skill System** | SKILL.md + auxiliary scripts define domain workflows, hot-swappable |
| **Chat Platform Bridging** | Lark (Webhook/WebSocket) and QQ official robots, no code changes required |
| **Remote Agent Collaboration** | HMAC-signed A2A protocol, supports cross-machine task delegation |
| **Web Interface** | FastAPI + SPA frontend, supports SSE streaming response and session management |
| **Chinese Priority** | Complete UTF-8 support, interface and documentation available in Chinese |
| **Security Hardening** | SSRF protection, command output sensitive information filtering, credential file permissions + automatic .gitignore prevention |
## Architecture Overview
```
┌────────────────────────────────────────────────────────┐
│ Orchestrator（Main REPL Controller） │
│ LLM Planner（Routing） · Permission Gate（Authorization） │
│ MCP Host（Subprocess Management） · A2A Client（Remote Delegation） │
└──────────┬──────────────┬──────────────┬───────────────┘
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌──▼──────┐
│Tool │ │Skill │ │Comm │
│Agent │ │Agent │ │Agent │
│(ReAct) │ │(SKILL.md) │ │(A2A) │
└────┬────┘ └──────┬──────┘ └──┬──────┘
│ │ │
Tool Execution Domain Workflow Remote Endpoint
(File/Web/Command/Image) (JSON Envelope Protocol) (HMAC Signature)
```
**Communication Protocol**: Agents communicate with each other using **MCP (Model Context Protocol)**, and remote agents use **A2A protocol** for task delegation.
## Quick Start
### Environment Requirements
- Python 3.11+
- Windows (PowerShell) / Linux / macOS
### Installation
```powershell
# 1. Clone the project
git clone <repo-url>
cd "W&W Agent"
# 2. Install (automatically creates .venv virtual environment)
.\install.ps1
# 3. Activate environment
.venv\Scripts\Activate.ps1
```
Linux/macOS:
```bash
pip install -e .
# or use uv
uv sync
```
### Launch
```powershell
python cli.py
```
**First launch** will automatically pop up the model configuration wizard (four steps: select supplier → select model → fill in API Key → fill in base URL). API Key saved to local credential file, no need to refill in subsequent launches.
### Example Conversation
```
ww-agent> Help me list the .py files in the current directory
ww-agent> Search for "What is LangGraph" and summarize three points
ww-agent> Read README.md and explain the main features in Chinese
ww-agent> Run python tests/test_file_ops.py and tell me the result
```
### One-Time Execution Mode
```powershell
python cli.py prompt "List all Python files in the current directory"
```
## Model Configuration
Use `/model` command to enter interactive wizard, supports the following suppliers:
| Supplier | Protocol | Description |
| --- | --- | --- |
| **Anthropic** | Anthropic | Claude series (default) |
| **OpenAI** | OpenAI | GPT / o1 / o3 series |
| **DeepSeek** | OpenAI compatible | DeepSeek-V3 / R1 |
| **Xiaomi MiMo** | OpenAI compatible | MiMo-7B-RL |
| **Custom** | OpenAI compatible | Any self-hosted endpoint |
Also configurable via environment variables:
```bash
export LANGCHAIN_AGENT_MODEL="anthropic/claude-opus-4-8"
export LANGCHAIN_AGENT_MODEL="openai/gpt-4o"
export LANGCHAIN_AGENT_MODEL="deepseek/deepseek-chat"
```
Configuration file stored in `.langchain-agent/settings.json`, API Key stored in `.langchain-agent/credentials.json` (file set to 0600 permissions, and automatically written to same directory .gitignore to prevent accidental submission).
## Slash Commands
In REPL input box, commands starting with `/` are not involved in conversation:
| Command | Description |
| --- | --- |
| `/help` | View all commands |
| `/model` | Reconfigure model (change supplier / change model / change Key) |
| `/status` | View current session status (model, turns, permissions, etc.) |
| `/config` | View current effective configuration |
| `/tools` | List all available tools for the assistant |
| `/skills` | List installed skills |
| `/agents` | List expert subprocesses in the background |
| `/instructions` | List loaded project description files |
| `/permissions [mode]` | View / switch permission mode |
| `/gateway` | Configure and start Lark/QQ robot |
| `/comm list\|add\|use\|rm` | Manage remote collaboration endpoints |
| `/task <query>` | Delegate task to remote Agent |
| `/chat <message>` | Chat with remote Agent |
| `/clear` | Clear current session history |
| `/exit` | Exit program |
## Tool List
Tool implementations are unified in `tool/tool_*.py`, 13 categories:
### File Operations
| Tool | Description |
| --- | --- |
| `read_file` | Read file content (supports text, PDF, DOCX, image) |
| `write_file` | Write/create file |
| `edit_file` | Precise string replacement editing |
| `list_directory` | List directory content (supports recursion) |
| `glob_search` | File name pattern matching search |
| `grep_search` | File content regular search |
### Web Access
| Tool | Description |
| --- | --- |
| `web_search` | Web search (Baidu / Startpage / DuckDuckGo / Tavily four engines, automatic downgrade) |
| `web_extract` | Extract webpage content |
| `web_crawl` | Depth crawl webpage link tree |
### Execution
| Tool | Description |
| --- | --- |
| `run_command` | Execute Shell command (default 180s timeout) |
| `run_python` | Execute Python code snippet |
### Others
| Tool | Description |
| --- | --- |
| `vision_analyze` | Image content analysis (call visual model) |
| `memory` | Read/write persistent memory snapshot (injected into system prompt) |
| `clarify` | Request clarification information from user |
| `calculator` | Safe expression evaluation |
| `mixture_of_agents` | Multi-model fusion reasoning |
> **Security Features**: `web_extract`/`web_crawl` built-in SSRF protection, refuse to access private IP, loopback address, and cloud metadata endpoint; `run_command` will filter output sensitive information.
## Permission Modes
System has three built-in permission modes, controlling which tools are available:
| Mode | Available Tools | Applicable Scenarios |
| --- | --- | --- |
| `read-only` | File reading, web search/scraping, query tools | Only need information query, prevent accidental modification |
| `workspace-write` (default) | read-only + file writing/editing, limited Shell | Daily development tasks |
| `danger-full-access` | All tools, including Home Assistant, etc. | Automation, IoT control |
Switching method:
```
ww-agent> /permissions read-only
ww-agent> /permissions workspace-write
ww-agent> /permissions danger-full-access
```
Also configurable via environment variables:
```bash
export LANGCHAIN_AGENT_PERMISSION_MODE=read-only
```
## Skill System
Skills are pluggable domain workflows, composed of `SKILL.md` (instruction document) + `_meta.json` (metadata) + auxiliary scripts.
### Directory Structure
```
skills/<slug>/
├── SKILL.md # Domain instruction and workflow description (injected as system prompt)
├── _meta.json # Metadata: keywords, required tools, environment variables
└── scripts/ # Auxiliary Python scripts (called by tool-agent)
├── search.py
├── compare.py
└── ...
```
### `_meta.json` Format
```json
{
"matchKeywords": ["keyword1", "keyword2"],
"requiresTools": ["web_search", "run_python"],
"requiresEnv": ["MY_SKILL_TOKEN"]
}
```
### Built-in Skills
| Skill | Description |
| --- | --- |
| `baidu-ecommerce-search` | Baidu e-commerce search: product retrieval, price comparison, brand ranking, ordering process |
### Add Custom Skills
1. Create a new directory under `skills/` (e.g., `skills/my-skill/`)
2. Write `SKILL.md` to define workflow
3. Write `_meta.json` to declare dependencies
4. Restart Agent, use `/skills` to check if loaded
## Chat Platform Integration
### Lark/Lark Robot
Through `/gateway` → select Lark → **Setup credentials** to enter interactive configuration wizard.
#### Step 1: Select Connection Mode
| Mode | Description |
| --- | --- |
| **ws** (recommended) | WebSocket long connection, robot actively connects out, no public address required |
| **webhook** | Lark will POST events to your server, requires publicly accessible URL |
#### Step 2: Fill in Credentials
| Field | Required | Description |
| --- | --- | --- |
| `app_id` | ✅ | Lark open platform's App ID (`cli_xxxx`) |
| `app_secret` | ✅ | App Secret |
| `domain` | ❌ | `open.feishu.cn` (domestic) or `open.larksuite.com` (overseas), default is the former |
| `allowed_users` | ❌ | Comma-separated authorized open ID list; leave blank, no one can use `/chat` `/task` |
#### Webhook Mode Additional Fields
Only when connection mode is selected as `webhook`, need to fill in:
| Field | Required | Description |
| --- | --- | --- |
| `verify_token` | ✅ | Event subscription's Verification Token (get on Lark open platform "Event subscription" page) |
| `encrypt_key` | ❌ | Encrypt Key (leave blank means no encryption) |
| `reply_in_thread` | ❌ | Whether to reply in topic (`y`/`n`), default is no |
| `host` | ❌ | Webhook listening address, default `0.0.0.0` |
| `port` | ❌ | Webhook listening port, default `8765` |
#### Launch
```
ww-agent> /gateway
# Select Lark → configure credentials → launch
```
or directly run:
```bash
python -m gateway feishu --port 8765
```
## QQ Official Robot
Through `/gateway` → select QQ → **Setup credentials** to enter interactive configuration wizard.
#### Field Description
| Field | Required | Description |
| --- | --- | --- |
| `app_id` | ✅ | QQ open platform's Bot AppID |
| `client_secret` | ✅ | Bot Client Secret |
| `intents` | ❌ | Intents bit mask, **leave blank, use default value** is fine. Default = `C2C+Group@+Channel@` (receive private chat, group chat, and channel @robot messages). Only need to fill in manually when receiving channel private messages |
| `sandbox` | ❌ | Whether to use sandbox test environment (`y`/`n`), **default `n` (formal environment)**. Unless using Tencent's sandbox test channel, otherwise fill `n` |
| `allowed_users` | ❌ | Comma-separated authorized openid list; leave blank, no one can use `/chat` `/task` |
#### Launch
```
ww-agent> /gateway
# Select QQ → configure credentials → launch
```
or directly run:
```bash
python -m gateway qq
```
> Credentials saved in `.langchain-agent/gateways.json` (automatically written to same directory .gitignore to prevent accidental submission).
## Remote Agent Collaboration (A2A)
Allow two Agent instances to collaborate across machines, delegating tasks through HMAC-signed A2A protocol.
### Add Remote Endpoint
```
ww-agent> /comm add
```
Will prompt to fill in (Ctrl+C to cancel):
| Field | Required | Description |
| --- | --- | --- |
| `peer_id` | ✅ | Endpoint unique identifier, e.g., `hermes-server` |
| `url` | ✅ | Endpoint address, e.g., `https://8.163.112.21:8443` (prefer https) |
| `display_name` | | Display name, leave blank, same as `peer_id` |
| `Self-signed certificate?` | | Endpoint uses self-signed certificate, select `y`, then fill in SHA-256 fingerprint |
| `HMAC secret` | ✅ | Shared key agreed with endpoint (hidden during input) |
> **HMAC key not stored**, only written to current process environment variable. After registration, will prompt a line `export COMM_PEER_<name>_HMAC=<value>`, add this line to shell profile to avoid refilling after restart.
### Use Remote Agent
```
ww-agent> /task Help me analyze this log file
ww-agent> /chat What's your database status?
```
### Endpoint Configuration Example
```
ww-agent> /comm list # List all endpoints
ww-agent> /comm use prod # Switch to prod endpoint
ww-agent> /comm rm dev # Delete dev endpoint
```
Security mechanism: All cross-Agent calls use HMAC-signed Grant + JWT verification to prevent unauthorized delegation.
## Web Interface
Provides browser-based SPA interface, supports SSE streaming response.
### Launch
```powershell
python web/__main__.py
# or
.\start_web.bat
```
Default access `http://localhost:8000`
### Features
- Streaming conversation interface (real-time rendering LLM output)
- Session management and history (SQLite storage)
- Model configuration API (`/api/config`)
- JWT authentication + rate limiting
## Environment Variables
### Core Control
| Variable | Description | Example |
| --- | --- | --- |
| `LANGCHAIN_AGENT_MODEL` | Override model selection | `anthropic/claude-opus-4-8` |
| `LANGCHAIN_AGENT_PERMISSION_MODE` | Override permission mode | `read-only` |
| `LANGCHAIN_AGENT_CONFIG_DIR` | Override configuration directory | `/custom/path/.langchain-agent` |
| `LANGCHAIN_AGENT_WORKSPACE_ROOT` | Sandbox file operation directory | `/home/user/projects` |
| `LANGCHAIN_AGENT_ALLOW_PRIVATE_URLS` | Allow access to private IP (only for development) | `true` |
### Provider API Key
| Variable | Description |
| --- | --- |
| `ANTHROPIC_API_KEY` | Anthropic Claude |
| `OPENAI_API_KEY` | OpenAI GPT |
| `DEEPSEEK_API_KEY` | DeepSeek |
| `XIAOMI_API_KEY` | Xiaomi MiMo |
> API Key prioritized from `credentials.json`, also configurable via environment variables.
## Development and Testing
TBD
## Project Structure
TBD
### Search Tools
| Variable | Description |
|------|------|
| `TAVILY_API_KEY` | Tavily search engine (optional, in parallel with DuckDuckGo) |
### Chat Platform (Gateway)
| Variable | Description |
|------|------|
| `QQ_APP_ID` | QQ robot AppID (corresponding to `app_id` in configuration) |
| `QQ_CLIENT_SECRET` | QQ robot Client Secret (corresponding to `client_secret` in configuration) |
| `QQ_INTENTS` | QQ Intents bit mask (optional, corresponding to `intents` in configuration) |
| `QQ_SANDBOX` | Set to `1` to use QQ sandbox environment (optional, corresponding to `sandbox` in configuration) |
> Prioritize reading from `/gateway` interactive configuration, environment variables are only used as a backup. FeiShu credentials are only configured through `/gateway`, not using environment variables.
## Development and Testing
### Install Development Dependencies
```bash
pip install -e ".[dev]"
```
### Run Tests
```bash
# Quick test (skip E2E subprocess test)
pytest -k "not e2e"
# Full test (including subprocess startup)
pytest
# Test with coverage
pytest --cov=. --cov-report=html
```
### Test Structure
| Path | Coverage |
|------|----------|
| `tests/test_e2e_multi_agent/` | End-to-end subprocess integration test |
| `tests/test_orchestrator/` | Planner, Router, Permission Gate |
| `tests/test_tool_agent/` | Tool execution, Workspace boundary |
| `tests/test_skill_agent/` | Skill loading, JSON envelope parsing |
| `tests/test_shared/` | Mock model, AuthZ, telemetry |
| `tests/test_gateway/` | FeiShu/QQ adapter |
| `tests/test_security/` | SSRF protection, sensitive information filtering |
### Code Quality
```bash
# Type checking
mypy --strict agent_paths.py orchestrator/ agents/shared/
# Security scan
bandit -r . -ll
# Dependency vulnerability check
pip-audit
```
### Install Optional Dependencies
```bash
# Document parsing (PDF, DOCX, PPTX)
pip install -e ".[docs]"
```
## Project Structure
```
W&W Agent/
├── cli.py # Entry point (argparse distribution)
├── pyproject.toml # Project metadata and dependencies
├── install.ps1 # Windows one-click installation script
├── start_web.bat # Start web interface
├── agent.md # Architecture design document
├── User Manual.md # English user manual
│
├── prompt_rules.py # Cross-Agent shared prompt rules
├── agent_display.py # Tool call rendering logic
├── agent_paths.py # Configuration directory parsing
├── project_context.py # Project instruction file discovery
│
├── config/ # Model configuration and credential management
│ ├── _providers.py # Provider registry
│ ├── _settings.py # settings.json read/write
│ ├── _credentials.py # Credential storage (0600 permission + .gitignore anti-commit)
│ └── _llm.py # LangChain ChatModel factory
│
├── orchestrator/ # Central orchestrator
│ ├── main.py # Startup, MCP Host, REPL entry
│ ├── turns.py # LLM Planner (task routing)
│ ├── router.py # CapabilityRouter
│ ├── permission_gate.py # Tool authorization check
│ ├── repl_controller.py # REPL main loop
│ ├── repl_ui.py # Rich TUI rendering
│ ├── mcp_host.py # Agent subprocess management
│ ├── telemetry.py # Event flow log
│ └── a2a_client.py # Remote Agent client
│
├── agents/
│ ├── tool_agent/ # Tool Agent (LangGraph ReAct)
│ │ ├── agent_loop.py # ReAct loop (766 lines)
│ │ └── tool_executor.py # MCP tool packaging
│ ├── skill_agent/ # Skill Agent
│ │ └── skill_executor.py # JSON envelope protocol execution (679 lines)
│ ├── comm_agent/ # Communication Agent (A2A)
│ │ ├── main.py
│ │ ├── a2a_protocol.py
│ │ └── peer_registry.py
│ └── shared/ # Shared infrastructure
│ ├── authz.py # JWT + HMAC authorization
│ ├── mcp_server.py # MCP server base class
│ ├── a2a_server.py # A2A streaming protocol
│ ├── permission_modes.py # Three-level permission definition
│ └── mock_chat_model.py # Test mock LLM
│
├── tool/ # Tool implementation (single source of truth)
│ ├── tool_file_ops.py # File operation (including Workspace boundary)
│ ├── tool_shell.py # Shell execution (including timeout/filtering)
│ ├── tool_web.py # Web access (including SSRF protection)
│ ├── tool_memory.py # Persistent memory
│ ├── tool_vision.py # Image analysis
│ ├── tool_basic.py # Basic tool (calculation, time)
│ └── tool_moa.py # Multi-model fusion
│
├── skills/ # Skill package
│ └── baidu-ecommerce-search/ # Baidu e-commerce search skill
│ ├── SKILL.md
│ ├── _meta.json
│ └── scripts/
│
├── gateway/ # Chat platform adapter
│ ├── feishu.py # FeiShu Webhook
│ ├── feishu_ws.py # FeiShu WebSocket
│ ├── qq.py # QQ official robot
│ └── README.md
│
├── web/ # Web interface (FastAPI)
│ ├── app.py # FastAPI application factory
│ ├── bridge.py # Web↔Orchestrator bridge
│ ├── store.py # SQLite session storage
│ ├── auth.py # JWT session authentication
│ └── static/ # Front-end SPA resources
│
├── bridge/hermes_a2a/ # Remote Agent collaboration protocol
│
└── tests/ # Test suite (77 files)
├── test_e2e_multi_agent/
├── test_orchestrator/
├── test_tool_agent/
├── test_skill_agent/
├── test_shared/
├── test_gateway/
└── test_security/
```
