doc: update README
This commit is contained in:
qixinbo
@@ -80,7 +80,9 @@ cp .env.example .env
|
||||
> 5. 点击下方的“生成授权码”，使用手机 QQ 扫码或按提示发送短信
|
||||
> 6. 验证通过后将获得一串 **16位随机字母组合**，将其复制填入 `.env` 文件中的 `SMTP_PASSWORD` 字段
|
||||
|
||||
### 2. 打包 wheel（产物输出到根目录 `dist/`）📦
|
||||
### 2. 生产模式（推荐，无需 Node.js）📦
|
||||
|
||||
#### 2.1 打包 wheel（产物输出到根目录 `dist/`）
|
||||
|
||||
如需自行打包发布，请按以下顺序执行：先构建前端，再构建后端 wheel，并将产物输出到项目根目录 `dist/`（与 `backend/` 同级）。
|
||||
|
||||
@@ -97,23 +99,23 @@ uv build --wheel --out-dir ../dist
|
||||
|
||||
构建完成后，wheel 位于项目根目录 `dist/`，例如 `dist/dataclaw-0.1.0-py3-none-any.whl`。
|
||||
|
||||
### 3. 标准部署（推荐，无需 Node.js）📦
|
||||
#### 2.2 安装与启动（使用 2.1 的 wheel）
|
||||
|
||||
请确保你已安装 Python 3.11 或以上版本。发布包已内置前端静态资源，生产部署无需安装 Node.js。
|
||||
请确保你已安装 Python 3.11+ 与 `uv`。生产模式使用已打包的 wheel（2.1 产物），无需安装 Node.js。
|
||||
|
||||
```bash
|
||||
# 建议先创建虚拟环境
|
||||
uv venv
|
||||
# 在项目根目录创建独立虚拟环境（不依赖 source 激活）
|
||||
uv venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 安装 DataClaw（示例：安装根目录 dist 下的 wheel）
|
||||
# 安装已打包的 wheel 到该虚拟环境
|
||||
uv pip install ./dist/dataclaw-*.whl
|
||||
|
||||
# 启动服务（默认 http://127.0.0.1:8000）
|
||||
dataclaw start
|
||||
```
|
||||
|
||||
常用服务控制命令：
|
||||
常用服务控制命令（同一虚拟环境）：
|
||||
|
||||
```bash
|
||||
# 查看运行状态
|
||||
@@ -134,21 +136,17 @@ export DATA_ROOT=/absolute/path/to/data
|
||||
|
||||
若未设置，默认使用仓库根目录下的 `data/`。服务状态文件与日志默认位于 `DATA_ROOT/run/`。
|
||||
|
||||
### 4. 开发模式（需要 Node.js）🧪
|
||||
### 3. 开发模式（需要 Node.js）🧪
|
||||
|
||||
如果你要调试前端代码或重新构建前端产物，请使用前后端分离开发模式：
|
||||
如果你要调试代码，请使用开发模式。开发模式直接跑源码，不依赖 wheel。
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
# 创建虚拟环境（可选但强烈建议）
|
||||
uv venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 安装依赖
|
||||
# 安装/同步后端依赖（会在 backend/.venv 中准备环境）
|
||||
uv sync
|
||||
|
||||
# 启动 FastAPI 服务器
|
||||
uv run uvicorn app.main:app --reload --port 8000
|
||||
uv run uvicorn main:app --reload --port 8000
|
||||
```
|
||||
|
||||
```bash
|
||||
@@ -162,7 +160,7 @@ npm run dev
|
||||
|
||||
*提示：请确保* *`nanobot`* *核心库已根据项目工作区的要求正确链接或以可编辑模式 (editable mode) 安装。*
|
||||
|
||||
### 5. 语音识别服务（可选）🎙️
|
||||
### 4. 语音识别服务（可选）🎙️
|
||||
|
||||
若你希望使用聊天输入框中的语音输入能力，请单独启动 `whisper` 服务：
|
||||
|
||||
@@ -183,14 +181,14 @@ uv run python main.py
|
||||
3. 填写服务地址（例如 `http://localhost:8001`）；
|
||||
4. 点击「测试连接」通过后保存。
|
||||
|
||||
### 6. 初始账号配置 👤
|
||||
### 5. 初始账号配置 👤
|
||||
系统首次注册的用户将自动成为管理员。您可以在登录页面直接点击“注册”按钮创建您的管理员账号（例如：用户名 `admin`，密码 `admin`），随后即可登录并管理项目、数据源和用户。
|
||||
|
||||
### 7. A2A 模式使用指南 🤖
|
||||
### 6. A2A 模式使用指南 🤖
|
||||
|
||||
A2A（Agent2Agent）用于让 DataClaw 把任务委托给远端 Agent，并保持任务可跟踪（状态流、产物流、取消、重试）。
|
||||
|
||||
#### 7.1 在前端启用 A2A（推荐）
|
||||
#### 6.1 在前端启用 A2A（推荐）
|
||||
|
||||
1. 进入 **Skills** 页面，切到 **A2A** 标签页。
|
||||
2. 点击新增远端 Agent，填写：
|
||||
@@ -209,7 +207,7 @@ A2A（Agent2Agent）用于让 DataClaw 把任务委托给远端 Agent，并保
|
||||
- `a2a_first`: 先远端，失败按回退链执行
|
||||
- `local_first`: 先本地，按需再回退
|
||||
|
||||
#### 7.2 API 示例（生产常用）
|
||||
#### 6.2 API 示例（生产常用）
|
||||
|
||||
以下示例假设服务地址为 `http://127.0.0.1:8000`，并已获取登录令牌 `${TOKEN}`。
|
||||
|
||||
@@ -286,7 +284,7 @@ curl -X POST http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/webhooks \
|
||||
}'
|
||||
```
|
||||
|
||||
#### 7.3 一个完整实战流程
|
||||
#### 6.3 一个完整实战流程
|
||||
|
||||
场景：你有一个“本地数据分析 Agent”，还接入了“外部行业知识 Agent-B”。
|
||||
|
||||
@@ -302,7 +300,7 @@ curl -X POST http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/webhooks \
|
||||
- 为长任务配置 webhook，避免客户端断线丢失进度。
|
||||
- 在项目级 rollout 配置灰度比例，先小流量启用 A2A 再全量放开。
|
||||
|
||||
#### 7.4 本地调试 A2A（双实例联调）
|
||||
#### 6.4 本地调试 A2A（双实例联调）
|
||||
|
||||
推荐在本机同时启动两个后端实例：
|
||||
- 实例 A（调用方）：`http://127.0.0.1:8000`
|
||||
|
||||
+21
-21
@@ -80,11 +80,11 @@ Please edit the `.env` file in the root directory and fill in your actual config
|
||||
> 5. Click "Generate Authorization Code" (生成授权码) below it, scan the QR code with mobile QQ or send an SMS as prompted
|
||||
> 6. After verification, you will get a **16-digit random letter combination**. Copy and paste it into the `SMTP_PASSWORD` field in your `.env` file
|
||||
|
||||
### 2. Standard Deployment (Recommended, No Node.js Required) 📦
|
||||
### 2. Production Mode (Recommended, No Node.js Required) 📦
|
||||
|
||||
Ensure you have Python 3.11+ installed. The pre-built React frontend is bundled in the Python wheel, so you don't need Node.js for production deployment.
|
||||
|
||||
#### Build the wheel (output to `dist/`)
|
||||
#### 2.1 Build the wheel (output to `dist/`)
|
||||
|
||||
```bash
|
||||
# First, build the frontend
|
||||
@@ -99,30 +99,33 @@ uv build --wheel --out-dir ../dist
|
||||
|
||||
Once built, the wheel is located in the project root `dist/` directory, e.g., `dist/dataclaw-0.1.0-py3-none-any.whl`.
|
||||
|
||||
#### Install and Run
|
||||
#### 2.2 Install and Run (using the wheel from 2.1)
|
||||
|
||||
Ensure Python 3.11+ and `uv` are installed. Production mode uses the packaged wheel from 2.1, and does not require Node.js.
|
||||
|
||||
```bash
|
||||
# We recommend creating a virtual environment first
|
||||
uv venv
|
||||
# Create an isolated virtual environment in project root
|
||||
uv venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install DataClaw
|
||||
# Install built wheel into that environment
|
||||
uv pip install ./dist/dataclaw-*.whl
|
||||
|
||||
# Start the service (defaults to http://127.0.0.1:8000)
|
||||
uv run dataclaw start
|
||||
dataclaw start
|
||||
```
|
||||
|
||||
Common service control commands:
|
||||
|
||||
```bash
|
||||
# Check running status
|
||||
uv run dataclaw status
|
||||
dataclaw status
|
||||
|
||||
# Custom host/port
|
||||
uv run dataclaw start --host 0.0.0.0 --port 8000
|
||||
dataclaw start --host 0.0.0.0 --port 8000
|
||||
|
||||
# Stop the service
|
||||
uv run dataclaw stop
|
||||
dataclaw stop
|
||||
```
|
||||
|
||||
Optional environment variable:
|
||||
@@ -135,18 +138,15 @@ If not set, DataClaw uses the repository-level `data/` directory by default. Ser
|
||||
|
||||
### 3. Development Mode (Requires Node.js) 🧪
|
||||
|
||||
If you want to debug the frontend code or rebuild the frontend artifacts, use the separate development mode:
|
||||
If you want to debug source code, use development mode (runs source directly, no wheel required):
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
# Create a virtual environment (optional but recommended)
|
||||
uv venv
|
||||
|
||||
# Install dependencies
|
||||
# Sync backend dependencies (environment is prepared under backend/.venv)
|
||||
uv sync
|
||||
|
||||
# Start the FastAPI server
|
||||
uv run uvicorn app.main:app --reload --port 8000
|
||||
uv run uvicorn main:app --reload --port 8000
|
||||
```
|
||||
|
||||
```bash
|
||||
@@ -180,14 +180,14 @@ Frontend setup:
|
||||
3. Fill in the service URL (e.g. `http://localhost:8001`);
|
||||
4. Click `Test Connection`, then `Save`.
|
||||
|
||||
### 4. Initial Account Setup 👤
|
||||
### 5. Initial Account Setup 👤
|
||||
The first user to register in the system will automatically be granted admin privileges. You can simply click the "Register" button on the login page to create your admin account (e.g., Username: `admin`, Password: `admin`), and then log in to manage projects, data sources, and users.
|
||||
|
||||
### 5. A2A Mode Guide 🤖
|
||||
### 6. A2A Mode Guide 🤖
|
||||
|
||||
A2A (Agent2Agent) lets DataClaw delegate tasks to remote agents with full task lifecycle controls (status stream, artifact stream, cancel, retry).
|
||||
|
||||
#### 5.1 Enable A2A in UI (Recommended)
|
||||
#### 6.1 Enable A2A in UI (Recommended)
|
||||
|
||||
1. Open **Skills** page and switch to the **A2A** tab.
|
||||
2. Add a remote agent with:
|
||||
@@ -206,7 +206,7 @@ A2A (Agent2Agent) lets DataClaw delegate tasks to remote agents with full task l
|
||||
- `a2a_first`: Try remote first, then fallback chain
|
||||
- `local_first`: Try local first
|
||||
|
||||
#### 5.2 API Examples
|
||||
#### 6.2 API Examples
|
||||
|
||||
Assume service URL is `http://127.0.0.1:8000` and your bearer token is `${TOKEN}`.
|
||||
|
||||
@@ -250,7 +250,7 @@ curl -X POST -H "Authorization: Bearer ${TOKEN}" \
|
||||
http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/cancel
|
||||
```
|
||||
|
||||
#### 5.3 Local Debugging for A2A (Two-Instance Setup)
|
||||
#### 6.3 Local Debugging for A2A (Two-Instance Setup)
|
||||
|
||||
Use two local backend instances:
|
||||
- Instance A (caller): `http://127.0.0.1:8000`
|
||||
|
||||
Reference in New Issue
Block a user