chat-agent

Imported from wuhonglei/chat-agent (AGENTS.md). Install upstream with npx skills add wuhonglei/chat-agent. Copyright stays with the author.

Chat Agent - Agent Guide

Cursor Cloud specific instructions

Services overview

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, database ai_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/.env using __ as nested delimiter (e.g. DATABASE__HOST=localhost).
• JWT keys must use \n for line breaks within a double-quoted .env value, e.g. `SECURITY__JWT__PRIVATE_KEY="[REDACTED private-key]