Initial commit of integrated agent system
This commit is contained in:
cillin
160
services/README.md
Normal file
160
services/README.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 大时代 Service Surfaces
|
||||
|
||||
This repository is in a split-first state: local development now assumes
|
||||
separate app surfaces and a dedicated WebSocket gateway instead of a single
|
||||
combined backend entrypoint.
|
||||
|
||||
## Service Map
|
||||
|
||||
| Surface | Default port | Role |
|
||||
| --- | --- | --- |
|
||||
| `backend.apps.agent_service` | `8000` | Control plane for workspaces, agents, skills, guard/approvals |
|
||||
| `backend.apps.trading_service` | `8001` | Read-only trading data APIs such as prices, financials, insider trades |
|
||||
| `backend.apps.news_service` | `8002` | Read-only explain/news APIs such as story, similar days, range explain |
|
||||
| `backend.apps.runtime_service` | `8003` | Runtime lifecycle APIs under `/api/runtime/*` |
|
||||
| `backend.apps.openclaw_service` | `8004` | Read-only OpenClaw REST facade |
|
||||
| Gateway (`backend.main`) | `8765` | WebSocket feed, runtime event stream, legacy/compat orchestration path |
|
||||
| OpenClaw Gateway | `18789` | External OpenClaw WebSocket endpoint consumed by 大时代 gateway |
|
||||
|
||||
## What Runs By Default In Dev
|
||||
|
||||
The supported local dev path is:
|
||||
|
||||
```bash
|
||||
./start-dev.sh
|
||||
```
|
||||
|
||||
That script starts:
|
||||
|
||||
- `agent_service` on `8000`
|
||||
- `trading_service` on `8001`
|
||||
- `news_service` on `8002`
|
||||
- `runtime_service` on `8003`
|
||||
- 大时代 gateway on `8765`
|
||||
|
||||
It does **not** start `openclaw_service` on `8004`.
|
||||
|
||||
Instead, the gateway expects an OpenClaw WebSocket server to already be
|
||||
available at `ws://localhost:18789` unless you override the OpenClaw gateway
|
||||
configuration outside the script.
|
||||
|
||||
## Manual Startup
|
||||
|
||||
Run split service surfaces explicitly:
|
||||
|
||||
```bash
|
||||
python -m uvicorn backend.apps.agent_service:app --host 0.0.0.0 --port 8000 --reload
|
||||
python -m uvicorn backend.apps.trading_service:app --host 0.0.0.0 --port 8001 --reload
|
||||
python -m uvicorn backend.apps.news_service:app --host 0.0.0.0 --port 8002 --reload
|
||||
python -m uvicorn backend.apps.runtime_service:app --host 0.0.0.0 --port 8003 --reload
|
||||
python -m backend.main --mode live --host 0.0.0.0 --port 8765
|
||||
```
|
||||
|
||||
Optional OpenClaw REST surface:
|
||||
|
||||
```bash
|
||||
python -m uvicorn backend.apps.openclaw_service:app --host 0.0.0.0 --port 8004 --reload
|
||||
```
|
||||
|
||||
## Runtime Responsibilities
|
||||
|
||||
The runtime path is intentionally split:
|
||||
|
||||
- `runtime_service` handles start, stop, restart, current runtime info, logs, and runtime state APIs
|
||||
- `agent_service` handles control-plane reads and writes for agents, workspaces, files, and approvals
|
||||
- `backend.main` / gateway hosts the live WebSocket channel and coordinates market service, scheduler, and pipeline execution
|
||||
|
||||
The practical request path looks like:
|
||||
|
||||
`frontend -> runtime_service/control APIs -> gateway/runtime manager -> market service + pipeline + storage`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Backend routing preferences
|
||||
|
||||
These variables let the gateway or tools prefer split services over in-process fallbacks:
|
||||
|
||||
| Variable | Used by | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `TRADING_SERVICE_URL` | gateway, data tools | Prefer `trading_service` for trading reads |
|
||||
| `NEWS_SERVICE_URL` | gateway, data tools | Prefer `news_service` for explain/news reads |
|
||||
| `RUNTIME_SERVICE_URL` | dev scripts / future follow-up | Reserved for runtime-service-aware flows |
|
||||
| `OPENCLAW_SERVICE_URL` | dev scripts / future follow-up | Points at the OpenClaw gateway origin in current dev setup |
|
||||
|
||||
Current `start-dev.sh` defaults:
|
||||
|
||||
```bash
|
||||
TRADING_SERVICE_URL=http://localhost:8001
|
||||
NEWS_SERVICE_URL=http://localhost:8002
|
||||
RUNTIME_SERVICE_URL=http://localhost:8003
|
||||
OPENCLAW_SERVICE_URL=http://localhost:18789
|
||||
```
|
||||
|
||||
Note that `OPENCLAW_SERVICE_URL` currently points at the OpenClaw gateway origin used by the live WebSocket bridge, not the optional REST app on `:8004`.
|
||||
|
||||
### Frontend service targets
|
||||
|
||||
The frontend can directly call split services with:
|
||||
|
||||
```bash
|
||||
VITE_CONTROL_API_BASE_URL=http://localhost:8000/api
|
||||
VITE_RUNTIME_API_BASE_URL=http://localhost:8003/api/runtime
|
||||
VITE_NEWS_SERVICE_URL=http://localhost:8002
|
||||
VITE_TRADING_SERVICE_URL=http://localhost:8001
|
||||
VITE_WS_URL=ws://localhost:8765
|
||||
```
|
||||
|
||||
## Current Frontend Direct-Call Coverage
|
||||
|
||||
Direct browser calls currently cover:
|
||||
|
||||
- runtime panel loading and runtime discovery
|
||||
- story
|
||||
- similar days
|
||||
- range explain
|
||||
- news for date
|
||||
- news categories
|
||||
- selected trading reads such as stock history and insider trades
|
||||
|
||||
Other flows still depend on the gateway WebSocket and control plane APIs.
|
||||
|
||||
## OpenClaw Integration Notes
|
||||
|
||||
There are two separate OpenClaw integration surfaces in this repo:
|
||||
|
||||
- OpenClaw WebSocket gateway on `:18789`
|
||||
- used directly by `backend/services/gateway.py`
|
||||
- this is what `start-dev.sh` assumes exists
|
||||
- `backend.apps.openclaw_service` on `:8004`
|
||||
- optional REST facade over OpenClaw CLI-backed reads
|
||||
- useful for typed client access and service-level testing
|
||||
|
||||
Do not treat those as interchangeable in docs or deployment config.
|
||||
|
||||
## Internal Module Direction
|
||||
|
||||
The codebase is now organized around these boundaries:
|
||||
|
||||
```text
|
||||
frontend
|
||||
├─ runtime/control/news/trading API clients
|
||||
└─ WebSocket runtime feed
|
||||
|
||||
backend.apps.agent_service
|
||||
└─ control-plane routes
|
||||
|
||||
backend.apps.runtime_service
|
||||
└─ runtime lifecycle routes
|
||||
|
||||
backend.apps.trading_service
|
||||
└─ read-only trading contract
|
||||
|
||||
backend.apps.news_service
|
||||
└─ read-only explain/news contract
|
||||
|
||||
backend.apps.openclaw_service
|
||||
└─ optional OpenClaw REST facade
|
||||
|
||||
backend.main / backend.services.gateway
|
||||
└─ live orchestration, feed transport, scheduler, runtime coordination
|
||||
```
|
||||
Reference in New Issue
Block a user