chengyongruandGitHub
462a0dfb0f
* refactor(channels): own setup and instance contracts * refactor(channels): isolate management contracts * refactor(channels): normalize activation contracts * fix(channels): enforce management contracts * refactor(channels): finish setup ownership migration * fix(channels): harden management contracts * fix(channels): enforce lazy loading and runtime ownership * fix(feishu): make multi-instance startup idempotent * fix(webui): render channel setup contracts cleanly * fix(feishu): stop websocket clients cleanly * fix(channels): enforce persistence and activation gates * fix(channels): preserve global feature action scope * fix(channels): apply defaults for single plugins * fix(channels): enforce management contract boundaries * refactor(feishu): remove identity helper indirection * fix(channels): preserve management setup contracts * refactor(channels): generalize instance settings UI * refactor(channels): package channel plugins with web UI metadata * refactor(channels): make built-ins self-contained packages * test(channels): colocate tests with channel packages * fix(dingtalk): use official brand icon * feat(channels): colocate webui translations * docs(channels): clarify plugin ownership * test(exec): remove output wait race * refactor(channels): unify plugin descriptors * fix(channels): enforce descriptor-owned contracts * refactor(channels): finish package-owned plugin setup * refactor(channels): use repository-owned packages only * fix(channels): self-describe dependencies and runtime state * fix(channels): warn about legacy entry points
82 lines
5.0 KiB
Markdown
82 lines
5.0 KiB
Markdown
This file provides guidance to AI coding agents working with this repository.
|
|
|
|
## Project Overview
|
|
|
|
nanobot is a lightweight, open-source AI agent framework written in Python with a React/TypeScript WebUI. It centers around a small agent loop that receives messages from chat channels, invokes an LLM provider, executes tools, and manages session memory.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Python: run single test / lint
|
|
pytest tests/test_openai_api.py::test_function -v
|
|
ruff check nanobot/
|
|
|
|
# WebUI: dev server (proxies API/WS to gateway :8765), build, test
|
|
# Build outputs to ../nanobot/web/dist (bundled into the Python wheel)
|
|
cd webui && bun run dev # or NANOBOT_API_URL=... bun run dev
|
|
cd webui && bun run build
|
|
cd webui && bun run test
|
|
|
|
# Gateway
|
|
nanobot gateway
|
|
```
|
|
|
|
## High-Level Architecture
|
|
|
|
### Core Data Flow
|
|
|
|
Messages flow through an async `MessageBus` (`nanobot/bus/queue.py`) that decouples chat channels from the agent core:
|
|
|
|
1. **Channels** (`nanobot/channels/`) receive messages from external platforms and publish `InboundMessage` events to the bus.
|
|
2. **`AgentLoop`** (`nanobot/agent/loop.py`) consumes inbound messages, builds context, and coordinates the turn.
|
|
3. **`AgentRunner`** (`nanobot/agent/runner.py`) handles the actual LLM conversation loop: send messages to the provider, receive tool calls, execute tools, and stream responses.
|
|
4. Responses are published as `OutboundMessage` events back to the appropriate channel.
|
|
|
|
### Key Subsystems
|
|
|
|
- **Agent Loop** (`nanobot/agent/loop.py`, `runner.py`): The core processing engine. `AgentLoop` manages session keys, hooks, and context building. `AgentRunner` executes the multi-turn LLM conversation with tool execution.
|
|
- **LLM Providers** (`nanobot/providers/`): Provider implementations (Anthropic, OpenAI-compatible, OpenAI Responses API, Azure, Bedrock, GitHub Copilot, OpenAI Codex, etc.) built on a common base (`base.py`). Includes image generation (`image_generation.py`) and audio transcription (`transcription.py`). `factory.py` and `registry.py` handle instantiation and model discovery.
|
|
- **Channels** (`nanobot/channels/`): Platform integrations (Telegram, Discord, Slack, Feishu, Matrix, WhatsApp, QQ, WeChat, WeCom, DingTalk, Email, MoChat, MS Teams, WebSocket, Mattermost). `manager.py` discovers and coordinates them. Channels are self-contained packages auto-discovered via `pkgutil` scanning.
|
|
- **Tools** (`nanobot/agent/tools/`): Agent capabilities exposed to the LLM: filesystem (read/write/edit/list), shell execution (with sandbox backends), web search/fetch, MCP servers, cron, notebook editing, subagent spawning, long-running tasks / sustained goals (`long_task.py`), image generation, and self-modification. Tools are auto-discovered via `pkgutil` scan + entry-point plugins.
|
|
- **Memory** (`nanobot/agent/memory.py`): Session history persistence with Dream two-phase memory consolidation. Uses atomic writes with fsync for durability.
|
|
- **Session Management** (`nanobot/session/`): Per-session history, context compaction, TTL-based auto-compaction (`manager.py`), and sustained goal state tracking (`goal_state.py`).
|
|
- **Config** (`nanobot/config/schema.py`, `loader.py`): Pydantic-based configuration loaded from `~/.nanobot/config.json`. Supports camelCase aliases for JSON compatibility.
|
|
- **WebUI** (`webui/`): Vite-based React SPA that talks to the gateway over a WebSocket multiplex protocol. The dev server proxies `/api`, `/webui`, `/auth`, and WebSocket traffic to the gateway.
|
|
- **API Server** (`nanobot/api/server.py`): OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/models`) for programmatic access.
|
|
- **Command Router** (`nanobot/command/`): Slash command routing and built-in command handlers.
|
|
- **Heartbeat** (`nanobot/templates/HEARTBEAT.md`): Periodic task list checked via `cron` jobs (legacy dedicated service removed).
|
|
- **Pairing** (`nanobot/pairing/`): DM sender approval store with persistent pairing codes per channel.
|
|
- **Skills** (`nanobot/skills/`): Built-in skill definitions (cron, github, image-generation, etc.) loaded into agent context.
|
|
- **Security** (`nanobot/security/`): PTH file guard and other security measures activated at CLI entry.
|
|
|
|
### Entry Points
|
|
|
|
- **CLI**: `nanobot/cli/commands.py`
|
|
- **Python SDK**: `nanobot/nanobot.py`
|
|
|
|
## Project-Specific Notes
|
|
|
|
- Architecture constraints: [`.agent/design.md`](.agent/design.md)
|
|
- Security boundaries: [`.agent/security.md`](.agent/security.md)
|
|
- Common gotchas: [`.agent/gotchas.md`](.agent/gotchas.md)
|
|
|
|
## Contribution Flow
|
|
|
|
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for contribution flow and PR guidelines.
|
|
|
|
## Code Style
|
|
|
|
- Python 3.11+, asyncio throughout.
|
|
- Line length: 100.
|
|
- Linting: `ruff` with rules E, F, I, N, W (E501 ignored).
|
|
- pytest with `asyncio_mode = "auto"`.
|
|
|
|
## Common File Locations
|
|
|
|
- Config schema: `nanobot/config/schema.py`
|
|
- Provider base / new provider template: `nanobot/providers/base.py`
|
|
- Channel base / new channel template: `nanobot/channels/base.py`
|
|
- Tool registry: `nanobot/agent/tools/registry.py`
|
|
- WebUI dev proxy config: `webui/vite.config.ts`
|
|
- Tests mirror the `nanobot/` package structure.
|