77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# PicoBot
|
|
|
|
## Maintenance
|
|
|
|
- **Update this file on any architectural change** — module boundaries, data flow, key constraints, or build/test commands must be reflected here
|
|
|
|
## Build & Run
|
|
|
|
- `cargo build` — build the binary
|
|
- `cargo run -- gateway` — start gateway server (binds `127.0.0.1:19876` by default)
|
|
- `cargo run -- chat` — connect to gateway as CLI client (default `ws://127.0.0.1:19876/ws`)
|
|
|
|
## Config
|
|
|
|
- Config file: `~/.picobot/config.json` or `./config.json` (fallback order)
|
|
- `.env` is loaded and env var placeholders `<VAR_NAME>` are substituted into config
|
|
- Config example: `config.example.json`
|
|
|
|
## Tests
|
|
|
|
- `cargo test --lib` — run unit tests (FAILS: `src/session/session.rs:657` missing `workspace_dir` field in test helper)
|
|
- `cargo test --test test_integration -- --ignored` — run integration tests (requires `tests/test.env` with API keys)
|
|
|
|
## Reference
|
|
|
|
- `reference/` — third-party reference implementations (nanobot, Mini-Agent, zeroclaw); not part of this project; use for similar functionality patterns
|
|
|
|
## Architecture
|
|
|
|
### Modes
|
|
|
|
- **Gateway mode** (`cargo run -- gateway`): HTTP/WebSocket server; owns `GatewayState` which holds all services
|
|
- **Client mode** (`cargo run -- chat`): TUI chat client; connects to gateway via WebSocket, purely for user interaction
|
|
|
|
### Core Data Flow
|
|
|
|
```
|
|
Channel → MessageBus → SessionManager → AgentLoop → (tools) → SessionManager → MessageBus → OutboundDispatcher → Channel
|
|
↑
|
|
ControlChannel ──→ SessionManager (dialog ops: create/switch/archive/delete)
|
|
```
|
|
|
|
### Modules
|
|
|
|
| Module | Responsibility | Key Types |
|
|
|--------|---------------|-----------|
|
|
| `gateway` | Server lifecycle, HTTP/WS endpoints, owns `GatewayState` | `GatewayState`, `run()` |
|
|
| `client` | TUI rendering, WebSocket client for CLI chat | `App`, `run()` |
|
|
| `channels` | External integrations (Feishu, CLI chat) | `ChannelManager`, `Channel` trait |
|
|
| `bus` | Async message queue (inbound/outbound/control channels) | `MessageBus`, `InboundMessage`, `OutboundMessage`, `ControlMessage` |
|
|
| `session` | Conversation session lifecycle, dialog operations | `SessionManager`, `Session` |
|
|
| `agent` | LLM call loop, tool execution, context compression | `AgentLoop` |
|
|
| `providers` | LLM API clients (OpenAI-compatible, Anthropic) | `LLMProvider` trait, factory `create_provider()` |
|
|
| `tools` | Agent tools (bash, file operations, http, web, get_skill) | `ToolRegistry`, `Tool` trait |
|
|
| `skills` | Skills loading, management, and prompt building | `SkillsLoader`, `Skill` |
|
|
|
|
### Functional Boundaries
|
|
|
|
- **Channels** only send/receive messages via `MessageBus`; they know nothing about sessions or LLM
|
|
- **MessageBus** is a pure async queue; it routes nothing, just passes messages
|
|
- **SessionManager** owns session state and dialog operations; it does NOT call LLM directly
|
|
- SessionManager is responsible for injecting skills prompt into conversation history
|
|
- **AgentLoop** receives dialog events from `SessionManager`, calls LLM via `providers`, executes tools, returns text responses
|
|
- AgentLoop is stateless; all state is managed by Session/SessionManager
|
|
- **Providers** are pure HTTP clients; no bus/session/channel awareness
|
|
- **Tools** are executed by `AgentLoop`; they receive raw arguments and return string results
|
|
|
|
### Key Constraints
|
|
|
|
- Gateway **changes working directory** to workspace on startup (`src/gateway/mod.rs:31`)
|
|
- `ChannelManager` owns the `MessageBus` and all channel instances
|
|
- `OutboundDispatcher` routes outbound messages to the correct channel via `ChannelManager`
|
|
|
|
## Known Issues
|
|
|
|
- (No known issues at this time)
|