# hunjing

参考下面项目的详细的设计内容和理念：
酒馆：<https://github.com/SillyTavern/SillyTavern>
pi ：<https://github.com/earendil-works/pi>
向量库：<https://github.com/oceanbase/seekdb>
live-2d: <https://github.com/stevenjoezhang/live2d-widget>
上下文压缩：<https://github.com/headroomlabs-ai/headroom>
记忆：<https://github.com/AGI-is-going-to-arrive/Memory-Palace>，<https://github.com/Dataojitori/nocturne_memory>，<https://github.com/TencentCloud/TencentDB-Agent-Memory>,<https://github.com/riisovo/memory-trigger>
成熟的相关的项目：<https://github.com/momori777/Artemis>，<https://github.com/RTGS2017/NagaAgent>，<https://github.com/AlfreScarlet/MoeChat>，<https://github.com/heshengtao/super-agent-party>，<https://github.com/MewCo-AI/mewco_ai_assistant_comm>，<https://github.com/weidu12123/Liyuan>
deepseek-herness：<https://github.com/deepseek-ai/deepseek-harness>
模型网关设计：<https://github.com/xgpxg/aiway>,<https://github.com/bestruirui/octopus>,<https://github.com/QuantumNous/new-api>,<https://github.com/cita-777/metapi>,<https://github.com/looplj/axonhubs>,<https://github.com/dyedd/lens>

## 技术栈

### 前端

Next.js + TypeScript + React + Tailwind CSS + Zustand/Jotai + pnpm

### 核心依赖

- **实时通信**: SSE / WebSocket
- **可视化**: Mermaid + 图谱可视化库
- **测试**: Vitest + Testing Library
- **代码质量**: ESLint (flat config) + Prettier + Husky + lint-staged

### 后端

python（uv管理）： FastAPI + SQLAlchemy + Alembic + Pydantic + httpx + loguru + uvicorn + chromadb
rust（cargo管理）： tauri（桌面端设计）
go （go mod管理）：

## 文档设计

相关的文档统一放在docs目录下

- 文档中所有的流程图和架构图都应该使用统一的mermaid绘制相关风格和格式，同时确保能够正常显示
- 文档应该定期更新和维护，以确保其内容的准确性和时效性。每次系统更新或功能变更后，相关文档也应该及时进行更新，以反映最新的系统状态和功能变化。

## docker部署

Docker 文件放在根目录 `docker/` 下。
容器名称以 `hunjing` 开头。
Compose 文件不使用顶部 `version` 字段。
本地开发默认使用 SQLite 文件数据库，正式环境使用 PostgreSQL，并按需启用 Milvus、Neo4j / NebulaGraph、Redis 和对象存储。

## 项目目录

日志统一放在根目录的logs目录下
数据库相关的文件统一放在根目录的db目录下
配置文件统一放在根目录的config目录下
.env.example文件放在根目录下，包含所有环境变量的示例和详细的中文说明

## 前端页面设计

图标：统一使用 Lucide 图标，界面全程禁止使用表情符号。
设计标准：对标 Awwwards 顶级网站水准，达到 Awwwards、FWA、CSS Design Awards 每日最佳网站同等设计品质。
创意自由度：将浏览器视作交互式艺术画布，跳出传统布局框架，追求先锋视觉风格、实验性排版、流畅物理动效、极具冲击力的文字版式。
沉浸式体验：融合代码、高级渲染逻辑、图片素材，打造统一完整的精品页面，做出突破常规 UI 认知、令人惊艳的数字交互体验。

## 开发命令

### Docker

编排按职责解耦为两个文件，容器名统一以 `hunjing-` 开头，通过共享网络 `hunjing-net` 互通，详细说明见 `docker/README.md`：
`docker-compose.infra.yml`（数据库 / 缓存 / 向量 / 图库 / 对象存储）创建网络与命名卷，`docker-compose.app.yml`（前后端）以 external 引用该网络。

```bash
# 先准备配置（只需一次）
cp .env.example .env                       # 填写 POSTGRES_PASSWORD 与各 *_API_KEY
cp config/models.example.yaml config/models.yaml  # 按需填写真实模型 endpoint

# 1) 启动基础设施（首次创建 hunjing-net 网络；Milvus 会自动带起 hunjing-etcd / hunjing-minio）
docker compose -f docker/docker-compose.infra.yml up -d
#   仅按需：docker compose -f docker/docker-compose.infra.yml up -d hunjing-postgres hunjing-redis
#   NebulaGraph（需 --profile）：--profile nebulagraph up -d hunjing-nebula-graphd hunjing-nebula-console-init
#   Attu（Milvus 可视化）：up -d hunjing-attu，访问 http://localhost:8001
#   数据库备份（手动触发，产物在 backups/）：--profile backup run --rm hunjing-pg-backup

# 2) 启动应用层（构建前后端镜像；必须先启动基础设施以创建网络）后端镜像内置 wait-for-it，会按 *_ENABLED 开关自动等待依赖就绪后再启动
docker compose -f docker/docker-compose.app.yml up -d --build

# 可选：反向代理（统一入口 80，/api 与 SSE 走后端，其余走前端）
docker compose -f docker/docker-compose.app.yml --profile nginx up -d hunjing-nginx

# 一键（基础设施 + 应用）
docker compose -f docker/docker-compose.infra.yml up -d && docker compose -f docker/docker-compose.app.yml up -d --build
```

## 必须遵守事项

```text
文件路径
    代码中以项目根目录为起点的绝对路径导入相关的配置或者文件

文档管理
    开发前查阅 docs/ 中的相关文档
    稳定工程标识、枚举值、ID 前缀、事件名、命名约定和错误码以 docs/contracts/contract-glossary.md 为单一事实源，下游文档引用而非复制取值列表

版本控制
    只提交 .*.example 文件到 Git
```