# kittenapi

**Repository Path**: txcxgzs/kittenapi

## Basic Information

- **Project Name**: kittenapi
- **Description**: 基于 Kitten-Cloud-Function 开发的编程猫云变量/云列表 HTTP API 服务，让你的编程猫作品支持 AI 对话
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-25
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kitten API

> 基于 Kitten-Cloud-Function 开发 - 让编程猫云功能得以通过 HTTP 调用，并有图形化管理后台，还能使得让你的编程猫Kitten作品接入 AI。

[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

---

## 🚀 快速开始（一条命令部署）

```bash
# 克隆项目（国内服务器推荐使用 Gitee 镜像）
git clone https://gitee.com/txcxgzs/kittenapi.git
# 或 GitHub
# git clone https://github.com/txcxgzs/kittenapi.git
cd kittenapi

# 一键部署（完全交互式，会引导你完成所有配置）
bash deploy/auto-deploy.sh
```

就这么简单！脚本会自动：
- ✅ 安装 Node.js、PM2、Python
- ✅ 安装项目依赖（使用国内镜像）
- ✅ 构建前后端
- ✅ 引导你配置所有参数
- ✅ 启动服务

---

## 📖 项目简介

### 这是什么？

**Kitten API** 是基于 [Kitten-Cloud-Function](https://github.com/S-LIGHTNING/Kitten-Cloud-Function) 开发的 HTTP API 服务。

### 解决什么问题？

| 问题 | 解决方案 |
|------|----------|
| 原版Kitten-Cloud-Function不提供http调用接口 | **HTTP 请求即可调用** |
| k4 无AI功能 | **简单地接入AI** |

### 两大核心功能

#### 1️⃣ HTTP API 服务

将编程猫云功能封装为 RESTful API，你可以通过简单的 HTTP 请求操作云变量、云列表：

```bash
# 连接作品
curl -X POST http://你的服务器:9178/api/connection/connect \
  -H "Content-Type: application/json" \
  -d '{"workId": 123456}'

# 设置云变量
curl -X POST http://你的服务器:9178/api/var/set \
  -H "Content-Type: application/json" \
  -d '{"workId": 123456, "name": "分数", "value": 100}'

# 获取云变量
curl http://你的服务器:9178/api/var/123456/分数
```

#### 2️⃣ AI 桥接服务

让你的编程猫作品接入 AI（ChatGPT、Claude、DeepSeek 等）：

```
玩家在作品中提问 → 云变量 → AI 桥接 → AI 回复 → 云变量 → 玩家看到答案
```

---

## ⚠️ 重要声明

### 依赖项目

本项目核心功能依赖 [**Kitten-Cloud-Function**](https://github.com/S-LIGHTNING/Kitten-Cloud-Function) 项目。

| 项目 | 作者 | 许可证 | 说明 |
|------|------|--------|------|
| [Kitten-Cloud-Function](https://github.com/S-LIGHTNING/Kitten-Cloud-Function) | [SLIGHTNING](https://github.com/S-LIGHTNING) | AGPL-3.0 | 编程猫云功能客户端库 |

> 💡 **提示**：本项目已内置 `Kitten-Cloud-Function/` 目录，无需额外下载依赖项目。

**因此，本项目同样采用 AGPL-3.0 许可证。**

---

## 🚀 功能特性

### HTTP API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/connection/connect` | POST | 连接到指定作品 |
| `/api/connection/disconnect` | POST | 断开当前连接 |
| `/api/connections` | GET | 获取所有连接状态 |
| `/api/var/:workId` | GET | 获取作品所有云变量 |
| `/api/var/:workId/:name` | GET | 获取指定云变量 |
| `/api/var/get` | POST | 获取云变量（POST方式） |
| `/api/var/set` | POST | 设置云变量 |
| `/api/var/rank` | POST | 获取私有变量排行榜 |
| `/api/list/:workId` | GET | 获取所有云列表 |
| `/api/list/:workId/:name` | GET | 获取指定云列表 |
| `/api/list/get` | POST | 获取云列表（POST方式） |
| `/api/list/push` | POST | 云列表尾部添加项 |
| `/api/list/unshift` | POST | 云列表头部添加项 |
| `/api/list/add` | POST | 云列表指定位置添加项 |
| `/api/list/pop` | POST | 移除云列表尾部项 |
| `/api/list/remove` | POST | 移除云列表指定位置项 |
| `/api/list/empty` | POST | 清空云列表 |
| `/api/list/replace` | POST | 替换云列表指定位置项 |
| `/api/list/replaceLast` | POST | 替换云列表尾部项 |
| `/api/list/setAll` | POST | 批量替换云列表 |
| `/api/online/:workId` | GET | 获取在线人数 |
| `/api/user/info` | GET | 获取当前用户信息 |

### AI 桥接功能

- 支持自定义 AI 提示词
- 支持多种 AI 模型
- PM2 管理，自动重启
- **支持多作品同时服务**
- 提供管理工具 `ai_bridge_manager.py`

#### 多作品 AI 桥接

使用管理工具可以同时为多个作品提供 AI 服务：

```bash
# 进入管理工具
python3 ai_bridge_manager.py

# 命令行快速操作
python3 ai_bridge_manager.py status       # 查看所有实例
python3 ai_bridge_manager.py add          # 添加新作品
python3 ai_bridge_manager.py remove 123456  # 移除作品
python3 ai_bridge_manager.py logs 123456  # 查看日志
python3 ai_bridge_manager.py clear-logs   # 清除所有日志
```

#### 管理工具功能

| 功能 | 说明 |
|------|------|
| 查看所有实例 | 显示所有运行中的 AI 桥接实例 |
| 添加作品 | 一键添加新作品并启动服务 |
| 移除作品 | 停止并删除实例 |
| 重启/停止实例 | 管理单个实例 |
| 查看日志 | 查看指定实例的运行日志 |
| 清除日志 | 一键清除所有日志文件 |
| 编辑配置 | 修改 API 地址、模型、云变量名等 |
| 编辑提示词 | 自定义 AI 回复风格 |

> 💡 **提示**：每个作品独立配置，可以使用不同的 AI 模型和提示词。

### 管理后台

部署完成后，访问 `http://你的服务器IP:端口` 即可打开管理后台。

#### 后台功能

- 📊 仪表盘：连接状态、在线人数、API 统计
- 📝 API 日志：查看所有调用记录
- 🚫 IP 黑名单：防止恶意调用
- ⚙️ 系统设置：端口、API Key、日志配置、修改密码

#### 后台登录说明

| 情况 | 是否需要登录 |
|------|-------------|
| 首次部署 | ✅ 需要输入部署时设置的密码 |
| 已登录状态 | 24小时内免登录 |

> 💡 **安全建议**：密码可在设置页面修改，建议定期更换密码。

---

## 📁 项目结构

```
kittenapi/
├── Kitten-Cloud-Function/     # 依赖项目（AGPL-3.0）
├── server/                    # Node.js 后端服务
│   ├── src/                   # TypeScript 源码
│   └── .env.example           # 配置模板
├── web/                       # Vue 3 前端
│   └── src/                   # Vue 源码
├── deploy/                    # 部署脚本
│   └── auto-deploy.sh         # 一键部署
├── kitten_ai_bridge.py        # AI 桥接程序
├── ai_bridge_manager.py       # AI 桥接管理工具
├── docs/                      # 文档
├── LICENSE                    # AGPL-3.0 许可证
└── README.md                  # 本文件
```

---

## 🔧 部署方式

### 方式一：一键部署（推荐）

```bash
# 1. 克隆项目（国内服务器推荐使用 Gitee 镜像）
git clone https://gitee.com/txcxgzs/kittenapi.git
# 或 GitHub
# git clone https://github.com/txcxgzs/kittenapi.git
cd kittenapi

# 2. 运行部署脚本
bash deploy/auto-deploy.sh
```

脚本会引导你完成：
1. 环境检测和依赖安装
2. 项目构建
3. **设置管理后台密码**（至少6位）
4. 服务配置（端口、Cookie、API Key）
5. AI 桥接配置（可选）
6. Nginx 反向代理配置（可选）
7. 服务启动和验证

### 方式二：手动部署

```bash
# 1. 安装依赖并构建（国内服务器使用镜像）
cd server && npm install --registry=https://registry.npmmirror.com && npm run build
cd ../web && npm install --registry=https://registry.npmmirror.com && npm run build

# 2. 配置环境变量
cp server/.env.example server/.env
nano server/.env  # 填入你的配置

# 3. 启动服务
cd server && pm2 start dist/app.js --name kitten-cloud-api
```

> ⚠️ **注意**：手动部署时，首次访问管理后台会提示设置密码。建议使用一键部署脚本自动完成密码设置。

---

## ⚡ 快捷命令

部署脚本会自动创建 `ktai` 快捷命令，无需手动配置。

### 自动创建

一键部署脚本会在安装完成后自动创建 `ktai` 快捷命令到 `~/.bashrc` 或 `~/.zshrc`。

### 手动创建（可选）

如果需要手动创建，执行以下命令：

```bash
# 将路径替换为你的实际项目路径
echo "alias ktai='cd /你的项目路径 && python3 ai_bridge_manager.py'" >> ~/.bashrc
source ~/.bashrc
```

### 使用快捷命令

```bash
# 直接输入 ktai 即可打开 AI 桥接管理器
ktai
```

---

## 🛠️ AI 桥接管理器

AI 桥接管理器是一个交互式命令行工具，用于管理 AI 桥接服务。

### 启动方式

```bash
# 方式一：使用快捷命令（推荐）
ktai

# 方式二：完整命令
cd /你的项目路径
python3 ai_bridge_manager.py
```

### 功能菜单

```
╔══════════════════════════════════════════════════════════════╗
║           AI 桥接管理工具 v2.0.0                             ║
║                                                              ║
║     多作品管理 | 配置管理 | 日志管理 | 提示词管理            ║
╚══════════════════════════════════════════════════════════════╝

AI 桥接管理菜单
══════════════════════════════════════════════════════════════

  1. 查看所有实例状态
  2. 添加作品              ← 一键添加新作品
  3. 移除作品              ← 停止并删除实例
  4. 重启实例
  5. 停止实例
  6. 查看日志
  7. 清除日志              ← 一键清除所有日志
  8. 编辑配置
  9. 编辑提示词            ← 自定义 AI 的行为和回复风格
  10. 设置编程猫 Cookie    ← 更换编程猫账号
  0. 退出
```

### 常用功能说明

| 功能 | 说明 |
|------|------|
| 查看所有实例状态 | 查看所有运行中的 AI 桥接实例 |
| 添加作品 | 一键添加新作品并启动服务 |
| 移除作品 | 停止并删除指定作品的实例 |
| 查看日志 | 查看指定实例的运行日志 |
| 清除日志 | 一键清除所有日志文件 |
| 编辑提示词 | 自定义 AI 的行为、回复风格等 |
| 设置编程猫 Cookie | 更换编程猫账号授权 |

---

## ⚙️ 配置说明

### 服务配置（server/.env）

部署脚本会引导你输入这些值，以下为配置文件格式：

```env
# 服务配置（部署时输入）
PORT=你设置的端口          # 默认建议: 9178
HOST=0.0.0.0

# 管理后台密码（部署时输入，至少6位）
ADMIN_PASSWORD=你设置的密码

# 编程猫身份认证（部署时输入）
CODEMAO_AUTHORIZATION=你的authorization值

# API 密钥（部署时输入，可选）
API_KEY=你设置的API密钥

# 日志保留天数（部署时输入）
LOG_RETENTION_DAYS=你设置的天数
```

> 💡 **提示**：默认端口建议使用 `9178`，部署脚本会引导你输入这些值。

### AI 桥接配置

部署时会自动创建 `ai-bridge/config_{作品ID}.py`，配置内容根据你部署时的输入生成：

```python
CONFIG = {
    "api_base_url": "部署时配置的API地址",
    "ai_api_url": "部署时配置的AI API地址",
    "ai_api_key": "部署时配置的AI API Key",
    "ai_model": "部署时配置的AI模型",
    "variable_name": "部署时配置的云变量名",
    "question_prefix": "部署时配置的问题前缀",
    "answer_prefix": "部署时配置的答案前缀",
    "system_prompt_file": "系统提示词文件路径（可选）",
    "request_timeout": 60,  # 请求超时时间（秒）
    "max_retries": 3        # 最大重试次数
}
```

#### 配置项说明

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `api_base_url` | Kitten Cloud API 地址 | - |
| `ai_api_url` | AI API 地址（如 OpenAI 兼容接口） | - |
| `ai_api_key` | AI API 密钥 | - |
| `ai_model` | AI 模型名称 | - |
| `variable_name` | 用于接收问题的云变量名 | - |
| `question_prefix` | 问题前缀（用于识别问题） | `问:` |
| `answer_prefix` | 答案前缀（用于识别答案） | `答:` |
| `system_prompt_file` | 系统提示词文件路径 | `ai-bridge/system_prompt_{作品ID}.txt` |
| `request_timeout` | AI API 请求超时时间（秒） | `60` |
| `max_retries` | 请求失败时的最大重试次数 | `3` |

> 💡 **提示**：部署脚本会引导你输入这些值，无需手动创建配置文件。

---

## 📖 常用命令

```bash
# 查看服务状态
pm2 status

# 查看日志
pm2 logs kitten-cloud-api

# 重启服务
pm2 restart kitten-cloud-api

# 停止服务
pm2 stop kitten-cloud-api

# AI 桥接管理工具（推荐使用 ktai 快捷命令）
ktai
```

---

## 📖 文档

| 文档 | 说明 |
|------|------|
| [API 文档](docs/API.md) | 完整 API 接口说明 |

---


## 📄 许可证

本项目采用 **AGPL-3.0 许可证**，详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- **[SLIGHTNING](https://github.com/S-LIGHTNING)** - [Kitten-Cloud-Function](https://github.com/S-LIGHTNING/Kitten-Cloud-Function) 项目作者