文档中心 - 茶海虾王 V3.1

🚀 安装教程

5 分钟快速部署，开箱即用

下载发布包

从下载页面获取最新版本的发布包，或直接从 GitHub 下载。

https://github.com/rao5201/CHXWAI/releases

解压到指定目录

将下载的 ZIP 文件解压到你希望安装的目录，建议路径不要包含中文或空格。

D:\CHXWAI\

配置环境变量

编辑 config/settings.json 文件，配置你的 API 密钥和偏好设置。

{
  "api_key": "your-api-key-here",
  "model": "local",  // 或 "cloud"
  "language": "zh-CN"
}

运行启动脚本

Windows 用户双击运行 start.bat，或使用命令行启动。

# Windows 一键启动
start.bat

# 或手动启动
python main.py

验证安装

启动后，尝试与 AI 进行简单对话，确认系统正常运行。

你好！
> 你好！我是茶海虾王 AI 助手，有什么可以帮助你的吗？

🏗️ 技术架构

清晰的分层设计，易于理解和扩展

📱 用户界面层 (UI Layer)

提供用户交互界面，支持多种访问方式。

命令行界面 (CLI) - 基于 Python 的交互式命令行
网页界面 (Web UI) - Flask/FastAPI 提供的可视化界面
API 接口 - RESTful API，支持第三方集成

🔌 适配器层 (Adapter Layer)

核心解耦层，实现模型、插件、存储的抽象。

模型适配器 - 统一接口，支持本地模型 (Ollama 等) 和云端模型 (GPT、Claude 等)
插件适配器 - 标准化插件接口，即插即用
存储适配器 - 支持多种存储后端 (JSON、SQLite、MongoDB 等)

🧠 核心业务层 (Core Layer)

系统的核心逻辑处理。

对话管理引擎 - 上下文管理、多轮对话支持
知识库管理系统 - 永久记忆存储、原子写入保障
插件调度中心 - 动态加载、执行插件
日志与监控系统 - 结构化日志、性能监控

💾 数据存储层 (Data Layer)

持久化数据存储。

永久记忆知识库 - 原子写入，数据安全
配置文件 - 外置化配置，便于部署
日志文件 - 结构化日志，便于排查问题

📁 项目目录结构

CHXWAI/ ├── main.py # 主入口文件 ├── config/ │ └── settings.json # 配置文件 ├── core/ │ ├── adapter.py # 适配器核心 │ ├── dialogue.py # 对话管理 │ └── knowledge.py # 知识库管理 ├── models/ │ ├── local.py # 本地模型适配 │ └── cloud.py # 云端模型适配 ├── plugins/ │ ├── weather.py # 天气查询插件 │ └── price.py # 价格查询插件 ├── ui/ │ ├── cli.py # 命令行界面 │ └── web/ # 网页界面 │ ├── app.py │ └── templates/ ├── storage/ │ └── knowledge.db # 知识库存储 ├── logs/ # 日志目录 ├── start.bat # Windows 启动脚本 └── requirements.txt # Python 依赖

🔌 API 文档

RESTful API 接口说明

POST /api/chat

发送消息并获取 AI 回复


// 请求
{
  "message": "你好",
  "conversation_id": "optional-uuid",
  "stream": false
}

// 响应
{
  "reply": "你好！有什么可以帮助你的吗？",
  "conversation_id": "uuid-xxx",
  "timestamp": "2026-04-08T03:00:00Z"
}

GET /api/knowledge

获取知识库内容


// 响应
{
  "entries": [
    {"id": 1, "key": "user_name", "value": "小明"},
    {"id": 2, "key": "preference", "value": "喜欢蓝色"}
  ]
}

POST /api/knowledge

添加知识到知识库（原子写入）


// 请求
{
  "key": "user_age",
  "value": "25"
}

// 响应
{
  "success": true,
  "id": 3
}

GET /api/plugins

获取已安装的插件列表


// 响应
{
  "plugins": [
    {"name": "weather", "version": "1.0.0", "enabled": true},
    {"name": "price", "version": "1.0.0", "enabled": true}
  ]
}

❓ 常见问题

快速解决使用中遇到的问题

Q: 如何切换本地/云端模型？

编辑 config/settings.json，将 model 字段改为 "local" 或 "cloud"，重启即可。

Q: 知识库数据存在哪里？

默认存储在 storage/knowledge.db，采用原子写入机制，确保数据安全。

Q: 如何添加自定义插件？

在 plugins/ 目录下创建 Python 文件，实现标准插件接口，然后在配置中启用即可。

Q: 日志文件在哪里？

日志存储在 logs/ 目录，按日期分割，便于排查问题。

📖 文档中心