103 lines
5.3 KiB
Markdown
103 lines
5.3 KiB
Markdown
# 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
|
||
```
|