Testing Playbook (中文 + English)¶

导航 / Navigation: 返回项目首页 | 文档首页 | 中文 README | English README

A. 最小可用测试 / Minimum Viable Test¶

Step 1: 启动依赖 / Start dependencies¶

中文：启动 PostgreSQL，创建 hyperagents 数据库。 English: Start PostgreSQL and create hyperagents database.

Step 2: 迁移数据库 / Run migrations¶

copy .env.example .env
# 编辑 .env 并确认 DATABASE_URL

cd backend
.venv\Scripts\activate
alembic upgrade head

说明 / Notes: - 最新迁移包含 users 及 runtime_runs/runtime_run_events。 - 若未迁移到 head，Workbench 的 Run Timeline 会为空或报错。

Step 3: 启动后端 / Start backend¶

cd backend
.venv\Scripts\activate
uvicorn app.main:app --reload --port 8000

Step 4: 健康检查 / Health check¶

$API_BASE_URL = "http://localhost:8000"
curl "$API_BASE_URL/health"

Expected: {"status":"ok"}

B. API E2E 测试顺序 / API E2E Sequence¶

$API_BASE_URL = "http://localhost:8000"
$register = curl -X POST "$API_BASE_URL/api/v1/auth/register" -H "Content-Type: application/json" -d '{"username":"demo","password":"secret123","display_name":"Demo User"}'

若已注册可改用登录接口： If account exists, use login instead:

$login = curl -X POST "$API_BASE_URL/api/v1/auth/login" -H "Content-Type: application/json" -d '{"account":"demo","password":"secret123"}'

从返回中提取 access_token，后续请求统一带： Extract access_token and use it in subsequent calls:

Authorization: Bearer <access_token>

1) Create project¶

curl -X POST "$API_BASE_URL/api/v1/projects" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"name":"Demo","description":"for test"}'

记录返回的 project_id。 Store the returned project_id.

2) Add agent resource¶

curl -X POST "$API_BASE_URL/api/v1/resources/projects/{project_id}" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"kind":"agent","name":"agent-openai","visibility":"project","model_provider":"openai","model_name":"gpt-4o-mini","config":{"system_prompt":"You are a helpful network assistant."}}'

记录返回 agent_id。 Store returned agent_id.

3) Create chat session¶

curl -X POST "$API_BASE_URL/api/v1/chat/projects/{project_id}/sessions" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"title":"session-1"}'

记录返回 session_id。 Store returned session_id.

4) Send message via agent¶

curl -X POST "$API_BASE_URL/api/v1/chat/sessions/{session_id}/messages" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"text":"analyze cpu usage trend","agent_id":"{agent_id}"}'

4.1) List sessions and messages¶

curl "$API_BASE_URL/api/v1/chat/projects/{project_id}/sessions" -H "Authorization: Bearer <access_token>"
curl "$API_BASE_URL/api/v1/chat/sessions/{session_id}/messages" -H "Authorization: Bearer <access_token>"
curl "$API_BASE_URL/api/v1/chat/sessions/{session_id}/runs" -H "Authorization: Bearer <access_token>"
curl "$API_BASE_URL/api/v1/chat/runs/{run_id}/events" -H "Authorization: Bearer <access_token>"

4.2) Add and remove project member¶

curl -X POST "$API_BASE_URL/api/v1/projects/{project_id}/members" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"user_id":"member-a"}'
curl -X DELETE "$API_BASE_URL/api/v1/projects/{project_id}/members/member-a" -H "Authorization: Bearer <access_token>"

5) Write memory with auto embedding¶

curl -X POST "$API_BASE_URL/api/v1/memory" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"memory_scope":"project","memory_type":"project","project_id":"{project_id}","visibility":"project","importance_score":0.9,"content":{"core_switch":"10.1.1.1","window":"Sat 02:00"},"auto_embedding":true}'

6) Hybrid semantic search¶

curl -X POST "$API_BASE_URL/api/v1/memory/semantic-search" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d '{"query_embedding":[0.01,0.02,0.03],"top_k":5,"project_id":"{project_id}","memory_scope":"project","memory_type":"project","min_importance":0.2,"similarity_weight":0.7}'

注：query_embedding 维度必须与配置一致。 Note: query_embedding dimensions must match configuration.

7) Retry failed embeddings¶

curl -X POST "$API_BASE_URL/api/v1/memory/retry-embeddings?limit=20" -H "Authorization: Bearer <access_token>"

若已启用 Worker，也可排队执行： If worker is enabled, you can enqueue the retry task:

curl -X POST "$API_BASE_URL/api/v1/memory/retry-embeddings?limit=20&enqueue=true" -H "Authorization: Bearer <access_token>"

8) Worker startup check (optional)¶

cd backend
.venv\Scripts\activate
celery -A app.workers.celery_app.celery_app worker -l info

启动后可再次触发 enqueue=true，验证返回中 queued=true 且 task_id 不为空。

C. 前端手工测试 / Frontend Manual Test¶

确认 .env 中 VITE_API_BASE_URL 指向后端地址
访问 http://localhost:5173
在 Login 页面注册或登录
Projects 页面创建项目，并在成员管理弹窗中添加/移除成员
Resources 页面创建 Agent/Tool/Skill/MCP
Workbench 页面创建 session，加载历史 session 并发送消息
观察 backend 日志和 API 返回

D. 常见失败排查 / Common Troubleshooting¶

401 Invalid token: 未登录或 Authorization 头缺失/过期
403 No access to project: 当前用户不是项目 owner/member
relation "runtime_runs" does not exist: 未执行最新 Alembic 迁移
embedding generation failed: provider 配置错误或模型服务不可达
query_embedding dimension must be ...: 向量维度不匹配
vector extension error: PostgreSQL 未安装/启用 pgvector
enqueue=true but queued=false: Worker 未启用或 Redis/Celery 不可用，系统已回退到 API 进程执行