Imported from wuhonglei/chat-agent (
AGENTS.md). Install upstream withnpx skills add wuhonglei/chat-agent. Copyright stays with the author.
Chat Agent - Agent Guide
Cursor Cloud specific instructions
Services overview
| Service | Port | Start command | Notes |
|---|---|---|---|
| PostgreSQL (pgvector + zhparser) | 5432 | docker compose up -d postgres |
容器 chat-agent-postgres;换镜像勿 down -v |
| Backend (FastAPI) | 8000 | cd backend && make dev |
Requires backend/.env with all config (see below) |
| Frontend (React/Vite+) | 3000 | cd frontend && vp dev |
Requires vp CLI (source ~/.vite-plus/env) |
| Sites (nginx 静态站) | 8080 | docker compose up -d sites |
容器 chat-agent-sites;只读挂 backend/data/sites;无 Host 探活会 404,健康检查用 pidof nginx |
PostgreSQL
- Runs as Docker container
chat-agent-postgres,镜像为自建chat-agent-postgres:pg18-zhparser(docker/postgres/Dockerfile:pgvector/pgvector:pg18+ SCWS + zhparser)。 - 构建/换镜像(勿
docker compose down -v,会删postgres_data丢数据):docker compose build postgres && docker compose up -d --force-recreate postgres - Credentials:
postgres:postgres, databaseai_assistant_db. - Start Docker daemon first:
sudo dockerd &>/tmp/dockerd.log &then start/recreate the container as above. - Extensions:
vector(pgvector)与zhparser(会话搜索zhcfg)需可用;迁移i2j3k4l5m6n7会CREATE EXTENSION IF NOT EXISTS,扩展文件不存在则失败。搜索实现见docs/CONVERSATION_SEARCH_OPTIMIZATION.md。
Deploy (deploy.sh)
- 首次
compose up:若 CLI 支持,使用--wait --wait-timeout 300(默认约 60s,后端冷启动 / 迁移经常不够)。 - 零停机更新:
zero_downtime_deploy对 backend 默认等健康检查最多 120s(容器内curl -f http://127.0.0.1:8000/)。 - 脚本末尾「最终健康检查」对 backend 再重试最多 12 次、间隔 5s,避免冷启动被误判失败。仅检查本次部署范围内的服务(只更 backend 不会因未起 frontend 失败)。
sites看容器内pidof nginx(不要对无 Host 的 HTTP 探活要求 200)。
Backend configuration gotchas
- The backend loads config from Nacos (config center), but gracefully falls back to empty config when Nacos is unreachable. All config can be provided via env vars in
backend/.envusing__as nested delimiter (e.g.DATABASE__HOST=localhost). - JWT keys must use
\nfor line breaks within a double-quoted.envvalue, e.g. `SECURITY__JWT__PRIVATE_KEY="[REDACTED private-key]
