完善文档
This commit is contained in:
chenxin committed
1 parent
192ea96eb4
commit
efc08dab5e
82 files changed
+1455
-109
No files matched your search
@@ -54,143 +54,206 @@ live-2d: <https://github.com/stevenjoezhang/live2d-widget>
|
||||
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/axonhub>,<https://github.com/dyedd/lens>
|
||||
|
||||
## 完整技术栈
|
||||
## 项目定位
|
||||
|
||||
---
|
||||
本项目是一个面向长期运行与持续演化的 Agent 平台，核心目标是提供统一的 Agent Runtime、认知能力、工具执行、记忆、RAG、MCP、桌面端与基础设施。
|
||||
|
||||
### 前端（TypeScript 主力）
|
||||
核心认知闭环：
|
||||
|
||||
**定位**：浏览器端 UI、状态管理、实时交互
|
||||
**技术选型**：
|
||||
Next.js 16 + React 19 + TypeScript + Tailwind CSS v4 + Zustand/Jotai + shadcn/ui + pnpm
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["感知"] --> B["上下文"]
|
||||
B --> C["记忆"]
|
||||
C --> D["理解"]
|
||||
D --> E["规划与推理"]
|
||||
E --> F["决策"]
|
||||
F --> G["工具 / 行动"]
|
||||
G --> H["环境反馈"]
|
||||
H --> I["反思"]
|
||||
I --> C
|
||||
```
|
||||
|
||||
#### 核心依赖
|
||||
## 必读文档
|
||||
|
||||
- **实时通信**：SSE（主，接收流式文本/事件）/ WebSocket（双向协同场景）
|
||||
- **数据请求**：TanStack Query（服务端状态管理与缓存）+ openapi-fetch（类型安全请求，类型由后端 OpenAPI 生成）
|
||||
- **可视化**：Mermaid（图表/流程图渲染）+ React Flow（流程编排与交互）/ Cytoscape.js（知识图谱交互）
|
||||
- **Markdown 渲染**：react-markdown + remark/rehype 插件体系 + Shiki（代码高亮，支持流式增量解析）
|
||||
- **长列表虚拟滚动**：@tanstack/react-virtual（大量数据高性能渲染）
|
||||
- **表单校验**：React Hook Form + Zod（类型安全的表单验证）
|
||||
- **测试**：Vitest（单元测试）+ Testing Library（组件测试）+ Playwright（E2E 测试）
|
||||
- **代码质量**：ESLint（flat config 格式）+ Prettier + Husky + lint-staged + commitlint
|
||||
开始涉及架构修改前：
|
||||
|
||||
---
|
||||
1. `docs/architecture/overview.md`
|
||||
2. `docs/agent/overview.md`
|
||||
3. `docs/decisions/README.md`
|
||||
|
||||
### BFF（TypeScript + Node.js）
|
||||
涉及具体领域时，必须优先阅读对应领域文档。
|
||||
|
||||
**定位**：前端聚合层、鉴权透传、响应裁剪、SSE/WebSocket 代理、类型安全桥接
|
||||
**技术选型**：
|
||||
Node.js 22 LTS + NestJS / Fastify + TypeScript + Zod + openapi-fetch
|
||||
## 核心工程原则
|
||||
|
||||
#### 核心依赖
|
||||
- 能力与基础设施解耦。
|
||||
- Agent Runtime 不直接绑定具体数据库、向量库、图数据库或对象存储。
|
||||
- 外部能力通过 Tool Registry / MCP 接入。
|
||||
- 长期数据进入 PostgreSQL；Redis 不作为核心业务数据最终持久化层。
|
||||
- VectorStore、GraphStore、FileStorage 必须通过抽象接口访问。
|
||||
- API 以 OpenAPI 3.1 为契约。
|
||||
- 重要架构选择必须通过 ADR 记录。
|
||||
- 不为了技术复杂度而提前引入分布式基础设施。
|
||||
|
||||
- **HTTP 框架**：Fastify（高性能）或 NestJS（模块化结构化）
|
||||
- **聚合/代理**：http-proxy / undici（请求转发与合并）
|
||||
- **鉴权**：JWT + cookie 透传
|
||||
- **日志**：pino（高性能结构化日志）
|
||||
- **配置管理**：dotenv / convict（环境配置校验）
|
||||
- **测试**：Vitest + supertest（API 集成测试）
|
||||
- **代码质量**：ESLint + Prettier + Husky
|
||||
## Repository 结构
|
||||
|
||||
---
|
||||
- `apps/`：客户端与服务应用。
|
||||
- `packages/`：共享库与 SDK。
|
||||
- `services/`：独立基础服务。
|
||||
- `docs/`：架构、设计、规范与 ADR。
|
||||
- `tests/`：跨模块测试与评估。
|
||||
- `scripts/`：开发和运维脚本。
|
||||
|
||||
### 后端核心（Python + uv）
|
||||
## Agent Runtime 规则
|
||||
|
||||
**定位**：业务主力、AI Agent 编排、RAG 检索
|
||||
**技术选型**：
|
||||
Python 3.12+（uv 包管理）+ FastAPI + SQLAlchemy 2.0 + Alembic + Pydantic v2 + httpx + loguru + uvicorn
|
||||
Agent Runtime 是系统核心。
|
||||
|
||||
#### 核心依赖
|
||||
所有 Agent Run 应具有稳定的 `run_id`，并可追踪：
|
||||
|
||||
- **任务队列**：Celery（稳定分布式任务）/ ARQ（轻量级，基于 Redis）
|
||||
- **LLM 接入**：OpenAI SDK / LiteLLM（多厂商统一接口）
|
||||
- **文档解析**：unstructured（多格式文档解析）+ pymupdf（PDF 处理）+ markitdown（Markdown 转换）
|
||||
- **Agent 引擎**：LangGraph（有状态多 Agent 编排）或 自研轻量引擎
|
||||
- **MCP 协议**：自研 MCP Client（stdio/sse 传输，接入第三方 MCP Server）
|
||||
- **记忆系统**：自研三层记忆架构（Redis 短期记忆 + PostgreSQL 长期记忆 + VectorStore 向量记忆）
|
||||
- **规划与推理**：自研 ReAct 循环 + Plan-and-Execute 模式
|
||||
- **工具系统**：自研工具注册表（装饰器注册 + Pydantic 参数校验）+ 内置工具集（文件/网页/向量/图/代码沙箱/数据库/HTTP）
|
||||
- **工具权限控制**：基于 Tauri 能力模型 + RBAC 用户角色
|
||||
- **流式输出**：SSE 事件驱动（text_delta / tool_call / tool_result / agent_thought / finish）
|
||||
- **断点续传**：Redis 缓存中间状态（支持重连恢复）
|
||||
- **向量库抽象层**：自研 VectorStore 接口 → ChromaDB（开发） / PGVector（过渡） / Milvus（生产）
|
||||
- **图数据库抽象层**：自研 GraphStore 接口 → Neo4j（开发） / NebulaGraph（生产）
|
||||
- **文件存储抽象层**：自研 FileStorage 接口 → 本地（开发） / MinIO（自建） / S3（生产）
|
||||
- **安全防护**：LLM Guard（Prompt Injection 检测）+ 自研输出审核（敏感词/隐私脱敏）
|
||||
- **审计日志**：所有工具调用记录（用户 + 时间 + 工具 + 参数 + 结果）
|
||||
- **评测框架**：DeepEval / Ragas（RAG 质量评估）
|
||||
- **调试工具**：自研 Debug Panel（推理链可视化）/ LangSmith（可选）
|
||||
- **测试**：pytest + pytest-asyncio + respx（HTTP Mock）
|
||||
- **代码质量**：Ruff（lint + format）+ mypy + pre-commit
|
||||
`Run -> Plan -> Model Call -> Memory -> Tool Call -> Observation -> Reflection -> Result`
|
||||
|
||||
---
|
||||
Agent 不应把业务逻辑隐含在 Prompt 中；稳定规则、权限和状态应由代码或配置表达。
|
||||
|
||||
### 桌面端（Rust + Tauri）
|
||||
## Memory 规则
|
||||
|
||||
**定位**：桌面客户端外壳、本地文件索引、沙箱执行、本地向量检索、离线能力
|
||||
**技术选型**：
|
||||
Rust（cargo 管理）+ Tauri v2 + tokio + serde + specta（TypeScript 类型导出）
|
||||
采用六类逻辑记忆：
|
||||
|
||||
#### 核心依赖
|
||||
- Working Memory
|
||||
- Episodic Memory
|
||||
- Semantic Memory
|
||||
- Procedural Memory
|
||||
- Social Memory
|
||||
- Identity Memory
|
||||
|
||||
- **本地检索**：tantivy（全文检索）
|
||||
- **沙箱执行**：Tauri 进程隔离 + 权限模型（capabilities 映射为 Agent 工具授权）
|
||||
- **打包分发**：tauri-plugin-updater（自动更新）+ tauri-plugin-store（本地配置存储）
|
||||
- **前端通信**：Tauri commands（同步/异步调用）+ events（双向事件）+ specta（类型安全）
|
||||
- **代码质量**：clippy + rustfmt
|
||||
统一通过 `Memory Manager` 访问。
|
||||
|
||||
---
|
||||
业务代码不得直接依赖 Redis、VectorStore 等具体实现。
|
||||
|
||||
### 高并发 I/O 层（Go）
|
||||
详细设计：`docs/agent/memory.md`
|
||||
|
||||
**定位**：网页抓取集群、API 网关与限流、长连接转发、定时调度、轻量级数据聚合
|
||||
**技术选型**：
|
||||
Go 1.25+（go mod 管理）+ Gin / Echo + colly + goquery + zap + viper
|
||||
## Planning / Reasoning 规则
|
||||
|
||||
#### 核心依赖
|
||||
规划与推理采用多模式架构：
|
||||
|
||||
- **并发控制**：ants（协程池）+ golang.org/x/time/rate（限流器）
|
||||
- **无头浏览器**：chromedp / rod（动态页面渲染抓取）
|
||||
- **配置与服务发现**：viper（配置管理）+ etcd（服务注册与发现，可选）
|
||||
- **可观测性**：OpenTelemetry-Go + Prometheus client
|
||||
- **测试**：testing + testify + httptest
|
||||
- **代码质量**：golangci-lint + gofumpt
|
||||
- ReAct
|
||||
- Plan-and-Execute
|
||||
- Reflection
|
||||
- Self-Correction
|
||||
- Dynamic Replanning
|
||||
|
||||
---
|
||||
详细设计：`docs/agent/planning.md`、`docs/agent/reasoning.md`。
|
||||
|
||||
### 基础设施
|
||||
## Tool 规则
|
||||
|
||||
#### 数据库
|
||||
所有 Agent Tool 必须：
|
||||
|
||||
- **关系数据库**：PostgreSQL 16（主库，支持 pgvector 扩展）
|
||||
- **缓存/消息队列**：Redis 7+（Session / 任务队列 / 限流计数器 / 短期记忆存储）
|
||||
- 注册到 Tool Registry。
|
||||
- 使用结构化参数 Schema。
|
||||
- 经过权限检查。
|
||||
- 具有超时和错误处理。
|
||||
- 记录调用审计。
|
||||
- 返回统一结果结构。
|
||||
|
||||
#### 向量数据库
|
||||
详细设计：`docs/tools/overview.md`
|
||||
|
||||
- **开发/测试**：ChromaDB（轻量快速）
|
||||
- **生产过渡**：PostgreSQL + pgvector（减少运维复杂度）
|
||||
- **大规模生产**：Milvus（分布式向量检索）
|
||||
## MCP 规则
|
||||
|
||||
#### 图数据库
|
||||
MCP 是外部工具和上下文扩展协议。
|
||||
|
||||
- **开发/测试**：Neo4j（社区版，易于上手）
|
||||
- **大规模生产**：NebulaGraph（分布式图数据库，高性能）
|
||||
MCP Tool 必须经过内部 Tool Adapter 和 Permission Layer，不得绕过统一权限体系。
|
||||
|
||||
#### 文件/对象存储
|
||||
详细设计：`docs/mcp/overview.md`
|
||||
|
||||
- **开发环境**：本地文件系统
|
||||
- **自建生产**：MinIO（兼容 S3 协议）
|
||||
- **云生产**：AWS S3 / 阿里云 OSS / 腾讯云 COS
|
||||
## API 规则
|
||||
|
||||
#### 容器
|
||||
- API 使用 OpenAPI 3.1。
|
||||
- FastAPI 负责生成服务端 Schema。
|
||||
- 前端优先使用类型安全客户端。
|
||||
- SSE 用于 Agent 流式事件。
|
||||
- WebSocket 只用于确有双向实时通信需求的场景。
|
||||
- API 错误使用统一错误模型。
|
||||
|
||||
- **容器化**：Docker + Docker Compose（本地开发环境一键编排）
|
||||
详细设计：`docs/api/overview.md`
|
||||
|
||||
#### API 契约
|
||||
## 数据访问规则
|
||||
|
||||
- **规范**：OpenAPI 3.1（单一真源）
|
||||
- **客户端生成**：openapi-generator（生成 TypeScript / Go 客户端）
|
||||
- PostgreSQL：核心业务与长期结构化数据。
|
||||
- Redis：缓存、短期状态、运行态数据。
|
||||
- VectorStore：向量检索。
|
||||
- GraphStore：关系与知识图谱。
|
||||
- FileStorage：对象与文件。
|
||||
- 所有可替换基础设施通过接口隔离。
|
||||
|
||||
## 安全规则
|
||||
|
||||
安全采用纵深防御：
|
||||
|
||||
`Authentication -> RBAC -> Tool Permission -> Sandbox -> Audit`
|
||||
|
||||
Tauri Capabilities 与服务端 RBAC 属于不同安全边界，不得混为一谈。
|
||||
|
||||
必须考虑：
|
||||
|
||||
- Prompt Injection
|
||||
- Secret Leakage
|
||||
- Sensitive Data
|
||||
- Tool Abuse
|
||||
- Sandbox Escape
|
||||
- Auditability
|
||||
|
||||
## 测试规则
|
||||
|
||||
新增能力至少考虑：
|
||||
|
||||
- Unit Test
|
||||
- Integration Test
|
||||
- API Test
|
||||
- Tool Test
|
||||
- Agent Workflow Test
|
||||
|
||||
RAG / Agent 的关键能力必须增加 Evaluation，而不能只依赖普通单元测试。
|
||||
|
||||
## 常用技术约束
|
||||
|
||||
### Python
|
||||
|
||||
Python 3.12+，使用 `uv` 管理依赖；Ruff + mypy。
|
||||
|
||||
### TypeScript
|
||||
|
||||
Next.js + React + TypeScript；pnpm；ESLint + Prettier。
|
||||
|
||||
### Rust
|
||||
|
||||
Tauri v2 + Tokio；rustfmt + clippy。
|
||||
|
||||
### Go
|
||||
|
||||
Go 1.25+；gofumpt + golangci-lint。
|
||||
|
||||
## 文档规则
|
||||
|
||||
架构修改必须同步修改相关 `docs/`。
|
||||
|
||||
改变技术选择或重要架构决策时创建 ADR。
|
||||
|
||||
不要把完整设计复制到 `AGENTS.md`；`AGENTS.md` 只保留必须影响 Agent 行为的规则和导航。
|
||||
|
||||
## 文档导航
|
||||
|
||||
- 总体架构：`docs/architecture/overview.md`
|
||||
- Agent：`docs/agent/overview.md`
|
||||
- Memory：`docs/agent/memory.md`
|
||||
- Planning：`docs/agent/planning.md`
|
||||
- Reasoning：`docs/agent/reasoning.md`
|
||||
- RAG：`docs/rag/overview.md`
|
||||
- Tools：`docs/tools/overview.md`
|
||||
- MCP：`docs/mcp/overview.md`
|
||||
- API：`docs/api/overview.md`
|
||||
- 数据：`docs/data/database.md`
|
||||
- 安全：`docs/security/overview.md`
|
||||
- 基础设施：`docs/infrastructure/development.md`
|
||||
- 测试：`docs/testing/strategy.md`
|
||||
- ADR：`docs/decisions/README.md`
|
||||
|
||||
## 文档设计
|
||||
|
||||
@@ -204,7 +267,6 @@ Go 1.25+（go mod 管理）+ Gin / Echo + colly + goquery + zap + viper
|
||||
Docker 文件放在根目录 `docker/` 下。
|
||||
容器名称以 `hunjing` 开头。
|
||||
Compose 文件不使用顶部 `version` 字段。
|
||||
本地开发默认使用 SQLite 文件数据库，正式环境使用 PostgreSQL，并按需启用 Milvus、Neo4j / NebulaGraph、Redis 和对象存储。
|
||||
|
||||
## 项目目录
|
||||
|
||||
@@ -224,15 +286,7 @@ Compose 文件不使用顶部 `version` 字段。
|
||||
|
||||
### 本地开发（Makefile 统一入口）
|
||||
|
||||
所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）：
|
||||
|
||||
```bash
|
||||
make dev-core # 核心三服务并行：灵台 + 神识 + 照壁
|
||||
make dev-backend # 灵台（另有 dev-shenshi / dev-bff / dev-frontend / dev-sandbox / dev-tianmu / dev-yuanqi）
|
||||
make db-upgrade # Alembic 升级到 head（迁移编号 000/001/002…）
|
||||
make db-revision m="说明" # 生成下一号迁移（自动编号 + autogenerate，禁手写哈希 id）
|
||||
make test # 全部测试（backend / shenshi / bff / frontend）
|
||||
```
|
||||
所有本地服务的启动、测试与数据库迁移统一经根目录 Makefile（`make help` 查看全部）
|
||||
|
||||
### Docker
|
||||
|
||||
@@ -242,7 +296,6 @@ make test # 全部测试（backend / shenshi / bff / fronten
|
||||
```bash
|
||||
# 先准备配置（只需一次）
|
||||
cp .env.example .env # 填写 POSTGRES_PASSWORD 与各 *_API_KEY
|
||||
# 模型端点目录经 SHENSHI_ENDPOINTS 配置（见 .env.example 神识段），无需复制 yaml
|
||||
|
||||
# 1) 启动基础设施（首次创建 hunjing-net 网络；Milvus 会自动带起 hunjing-etcd / hunjing-minio）
|
||||
docker compose -f docker/docker-compose.infra.yml up -d
|
||||
|
||||
Reference in new issue
Block a user