koishi-plugin-shentun-ai

v2.0.4

Published

9 months ago

神吞酱 - 拥有独立个性的AI助手，支持图片识别和记忆系统，会主动跳出来聊天

Downloads

645

0High
0Medium
0Low

loguhan

chatbot koishi plugin ai assistant personality memory image-recognition vision

神吞酱AI助手 - koishi-plugin-shentun-ai

一个拥有独立个性的AI文档助手，她会主动跳出来聊天，而不是被动回答！

🌟 特色功能

✨ 独立个性

神吞酱：可爱活泼的傲娇少女，用温柔可爱的语气主动找你聊天
吞宝：调皮神秘的恶作剧大师，会突然跳出来给你惊喜
支持实时切换性格，体验不同的互动风格

🎯 主动发言

根据设定的概率主动发起对话
智能判断聊天时机，不会过度打扰
提供有趣的随机话题和互动内容

📚 文档管理 & RAG知识增强

智能RAG系统：语义搜索 + 自动文档检索
智能文档查询和整理：基于向量相似度的精准搜索
支持文件上传和保存：自动建立索引和摘要
关键词触发自动回复：上下文感知的智能回复
记忆功能记住重要信息：长期记忆和学习能力

🎭 多样互动

文档查询：文档 <关键词>
自由聊天：吞酱 <想说的话>
记忆功能：记住 <内容> / 回忆
性格切换：切换性格 <神吞酱|吞宝>

🚀 安装

方法1：本地安装（推荐，解决版本问题）

# 进入插件目录
cd external/koishi-plugin-shentun-ai

# 构建插件
npm run build

# 在koishi.yml中添加本地插件配置
# 不需要通过npm安装，直接使用本地版本

方法2：通过Koishi市场安装

在Koishi控制台中搜索"神吞酱AI"并安装。

方法3：通过npm安装（如版本已发布）

npm install koishi-plugin-shentun-ai

方法4：通过yarn安装（如版本已发布）

yarn add koishi-plugin-shentun-ai

方法5：指定版本安装（如遇到版本问题）

# 安装最新稳定版本
npm install koishi-plugin-shentun-ai@latest

# 或安装特定版本
npm install [email protected]

🤖 多AI服务提供商支持

神吞酱现在支持多种AI服务提供商，您可以根据需求选择最适合的服务：

支持的AI提供商

| 提供商 | 配置示例 | 说明 | 推荐baseURL | |--------|----------|------|-------------| | 阿里云百炼 | provider: "alibaba" | 通义千问系列模型 | https://dashscope.aliyuncs.com/compatible-mode/v1 | | OpenAI | provider: "openai" | GPT系列模型 | https://api.openai.com/v1 | | Claude | provider: "claude" | Anthropic Claude模型 | https://api.anthropic.com | | Gemini | provider: "gemini" | Google Gemini模型 | https://generativelanguage.googleapis.com/v1beta | | DeepSeek | provider: "deepseek" | DeepSeek系列模型 | https://api.deepseek.com/v1 | | 本地部署 | provider: "local" | 本地Ollama等开源模型 | http://localhost:11434/v1 |

🔑 获取API密钥

阿里云百炼

访问阿里云百炼控制台
创建并获取API Key

OpenAI

访问OpenAI平台
创建API密钥

Claude (Anthropic)

访问Anthropic控制台
获取API密钥

Gemini (Google)

访问Google AI Studio
创建API密钥

DeepSeek

访问DeepSeek平台
获取API密钥

⚙️ 配置方法

方法1：Koishi控制台配置

在Koishi控制台中配置：

provider: 选择AI服务提供商
apiKey: 输入对应服务的API密钥
model: 选择具体模型（可选，默认auto）
baseURL: 自定义API端点（可选）

方法2：配置文件

编辑 koishi.yml：

shentun-ai:
  provider: "alibaba"  # 或 "openai", "claude", "gemini", "deepseek", "local"
  apiKey: "你的API密钥"
  model: "qwen-plus"  # 可选，默认自动选择
  baseURL: ""  # 可选，自定义端点

方法3：环境变量

# 通用API密钥
AI_API_KEY=你的API密钥

# 阿里云百炼（兼容旧配置）
DASHSCOPE_API_KEY=你的阿里云API密钥

方法4：国内用户推荐配置（解决网络问题）

shentun-ai:
  provider: "alibaba"  # 或 "deepseek", "zhipu"
  apiKey: "你的API密钥"
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"  # 阿里云
  # baseURL: "https://api.deepseek.com/v1"  # DeepSeek
  # baseURL: "https://open.bigmodel.cn/api/paas/v4"  # 智谱
  model: "qwen-turbo"  # 或 "deepseek-chat", "glm-4"
  apiTimeout: 60000  # 增加超时时间
  apiMaxRetries: 5   # 增加重试次数
  apiBatchSize: 3    # 减小批处理大小
  documentPath: "./data/shentun-docs"
  personality: "神吞酱"

🎯 推荐模型配置

| 提供商 | 推荐模型 | 特点 | |--------|----------|------| | alibaba | qwen-plus | 中文优化，性价比高 | | alibaba | qwen-max | 最强效果 | | openai | gpt-3.5-turbo | 通用性强 | | openai | gpt-4 | 最强效果 | | claude | claude-3-haiku | 快速响应 | | gemini | gemini-pro | 多模态支持 | | deepseek | deepseek-chat | 代码能力强 | | local | llama2 | 完全本地，隐私性好 |

🔄 快速切换提供商

无需重新安装，直接在配置中修改 provider 即可切换AI服务提供商。

⚙️ 配置

在 Koishi 控制台中配置以下选项：

基础配置

| 配置项 | 说明 | 默认值 | |--------|------|--------| | personality | AI助手名称 | "神吞酱" | | activeRate | 主动发言概率(%) | 15 | | memorySize | 记忆容量 | 100 | | documentPath | 文档存储路径 | "./data/shentun-docs" | | triggerKeywords | 触发关键词 | ["文档", "资料", "文件", "知识"] | | responseStyle | 回复风格 | "cute" | | enabledChannels | 启用的频道 | [] | | cooldown | 冷却时间(秒) | 300 | | maxMessageLength | 最大消息长度 | 500 |

API配置选项

| 配置项 | 说明 | 默认值 | 示例 | |--------|------|--------|------| | apiKey | API密钥 | - | sk-xxxxxxxxxxxxx | | baseURL | API基础URL | https://api.openai.com/v1 | https://api.deepseek.com/v1 | | model | 模型名称 | gpt-3.5-turbo | deepseek-chat | | apiTimeout | API请求超时时间（毫秒） | 30000 | 60000 | | apiMaxRetries | API请求最大重试次数 | 3 | 5 | | apiBatchSize | 文档索引批处理大小 | 5 | 10 |

搜索配置

| 配置项 | 说明 | 默认值 | |--------|------|--------| | enableDeepSearch | 启用深度搜索功能 | true | | maxSearchResults | 最大搜索结果数量 | 5 | | enableDocumentLoadingLog | 启用文档加载信息输出 | true | | searchThreshold | 相关性阈值(0.1-1.0) | 0.15 | | enableSemanticSearch | 启用语义搜索增强 | true |

🔧 优化AI文档关联性

增强相关性算法

神吞酱现在采用多层相关性评分算法，大幅提升AI与文档的关联性：

🎯 相关性评分机制

精确匹配：标题完全匹配查询词，权重最高(2.0)
短语匹配：完整短语出现，权重较高(0.8/次)
关键词权重：基于TF-IDF算法，智能过滤常见词
语义扩展：自动扩展同义词和相关概念
上下文分析：提取相关段落及其上下文
文档结构：标题层级、代码块、列表等技术特征

⚙️ 优化配置建议

解决文档内容关联性问题（推荐）：

shentun-ai:
  searchThreshold: 0.1      # 极低阈值，确保相关内容都能匹配
  enableSemanticSearch: true  # 启用语义搜索
  maxSearchResults: 10       # 增加结果数量，提供更多上下文

提高关联性：

shentun-ai:
  searchThreshold: 0.2      # 降低阈值，增加结果
  enableSemanticSearch: true  # 启用语义搜索
  maxSearchResults: 8        # 增加结果数量

提高精准度：

shentun-ai:
  searchThreshold: 0.5      # 提高阈值，减少噪音
  maxSearchResults: 3       # 只保留最相关结果

当文档内容无法匹配时的处理：

系统自动启用模糊匹配模式
使用字符级匹配和前缀匹配
返回文档摘要作为回退内容
确保至少返回最相关的文档内容

📊 文档优化建议

文档结构优化：

使用清晰的标题层级(#, ##, ###)
在标题中包含关键词
使用代码块标记技术内容
添加列表和表格提高结构化程度

内容优化：

📁 批量文档管理

支持多种上传方式

1. 单文件上传

直接发送 .md 或 .markdown 文件
自动保存到知识库目录

2. 批量文件上传

一次发送多个Markdown文件
系统自动处理所有文件

3. 文件夹批量添加

# 批量添加本地文件夹中的所有Markdown文档
批量添加文档 ./docs-folder

# 支持递归子目录
批量添加文档 ./project-docs

4. 压缩包上传

支持 .zip, .rar, .7z 格式
自动解压并处理内部Markdown文件

📊 文档管理命令

| 命令 | 说明 | 示例 | |------|------|------| | 上传文档 | 显示上传帮助信息 | 上传文档 | | 批量添加文档 <路径> | 批量添加文件夹中的文档 | 批量添加文档 ./docs | | 文档列表 | 查看所有文档 | 文档列表 | | 文档统计 | 查看知识库统计信息 | 文档统计 | | 文档搜索 <关键词> | 搜索文档内容 | 文档搜索 API |

📈 批量上传最佳实践

大量文档处理建议：

分批上传，每批建议不超过50个文件
使用压缩包上传大型文档集合
利用批量添加文档命令处理本地文件夹
监控处理进度，系统会实时反馈

性能优化：

自动分批处理，避免内存溢出
并行处理多个文件
实时进度反馈
错误处理和重试机制

🎯 一口输入给AI（大量文档支持）

一键导入整个知识库：

# 方法1：使用批量添加文档命令
批量添加文档 ./my-entire-docs

# 方法2：压缩包上传
1. 将整个文档文件夹压缩为zip
2. 直接发送压缩包到聊天
3. 系统自动解压处理

# 方法3：多文件拖拽上传
1. 选中所有Markdown文件
2. 拖拽到聊天窗口发送
3. 系统自动批量处理

处理进度监控：

实时显示处理进度
成功/失败文件统计
详细的错误报告
完成后自动更新索引

📋 文档内容无法关联的解决方案

问题现象：

AI回答"找不到相关内容"
文档存在但无法匹配搜索
搜索结果为空或相关性低
AI生成内容与文档不符

🔧 验证工具：

文档验证

验证文档 [文件名]  # 验证指定文档是否正确加载
验证文档          # 验证第一个文档

调试模式

调试模式 true     # 开启调试模式，查看AI使用的文档内容
调试模式 false    # 关闭调试模式

解决步骤：

检查配置：使用推荐的低阈值配置
验证文档：使用验证文档命令确认文档已正确加载
测试搜索：使用简单关键词测试
查看调试信息：开启调试模式查看AI实际使用的文档内容
检查日志：检查是否有错误信息

强制匹配模式：

系统自动启用模糊匹配
降低相关性阈值到0.05
返回文档摘要作为回退
智能提取相关段落
确保至少提供相关内容

🔍 调试相关性

搜索调试命令：

# 测试文档搜索
文档搜索 你的关键词

# 查看文档列表
文档列表

# 检查文档统计
文档统计

# 手动更新索引（如果文档有变化）
# 等待30秒或重启插件

调试建议：

从简单关键词开始测试
检查文档是否包含相关内容
查看文档标题和摘要
调整searchThreshold参数
开头段落包含核心概念
每个章节有明确的关键词
避免过度使用常见词
使用技术术语和精确描述

🔍 调试相关性

查看搜索详情：

搜索调试 JavaScript  # 显示相关性评分详情

手动索引更新：

索引更新  # 强制重新索引所有文档

🚨 文档内容无法关联的解决方案

问题现象：

AI回答"找不到相关内容"
文档存在但无法匹配
搜索结果为空
AI生成内容与文档实际内容不符

🔧 新增验证工具：

文档验证命令
```
验证文档 使用说明.md    # 验证特定文档
验证文档               # 验证第一个文档
```
输出示例：
- 文档标题和路径
- 字符数对比
- 内容匹配状态
- 关键词和摘要
- 内容预览
调试模式
```
调试模式 true    # 开启调试
调试模式 false   # 关闭调试
```
调试信息包括：
- 搜索关键词和结果数
- 文档匹配详情
- AI实际使用的文档内容
- 相关性评分

解决步骤：

检查配置：确认searchThreshold设置为0.1-0.2
验证文档：使用验证文档命令确保文档已正确索引
开启调试：使用调试模式 true查看详细过程
测试搜索：使用简单关键词测试
查看日志：检查是否有文档加载错误

强制匹配模式： 当严格搜索无结果时，系统会自动：

启用宽松搜索模式（关键词匹配）
降低相关性阈值到0.05
智能提取相关段落而非仅摘要
返回文档摘要作为参考
确保用户总能获得相关内容

调试建议：

先使用验证文档确认文档加载正确
开启调试模式观察搜索过程
使用文档搜索测试关键词匹配
检查文档内容是否包含预期信息

🎮 使用方法

基本命令

📖 文档查询

文档 JavaScript基础
文档 Python高级用法 详细

💬 自由聊天

吞酱 今天天气怎么样？
吞酱 给我讲个笑话

🧠 记忆功能

记住 今天是我的生日
回忆

🔄 性格切换

切换性格 神吞酱
切换性格 吞宝

📁 文档上传 & RAG索引

直接发送文件即可，神吞酱会自动：

保存文件到知识库
建立语义索引和关键词
生成文档摘要
5分钟内完成索引更新

🔍 智能搜索

搜索文档 JavaScript基础    # 语义搜索相关文档
搜索文档 Python教程 详细    # 指定搜索深度
文档状态                   # 查看索引状态
索引更新                   # 手动更新索引

🔧 验证与调试

验证文档 使用说明.md       # 验证文档是否正确加载
验证文档                  # 验证第一个文档
调试模式 true             # 开启调试模式
调试模式 false            # 关闭调试模式

🧠 RAG增强对话

无需特殊命令，神吞酱会自动：

在回答前搜索相关文档
基于文档内容提供准确答案
引用文档来源和上下文

被动触发

当消息中包含配置的关键词（如"文档"、"资料"等）时，神吞酱会自动回复相关内容。

🎭 性格特点

神吞酱

性格：可爱、活泼、有点傲娇、知识渊博
口头禅：
- "哼哼～人家才不是特意来帮你的呢！"
- "这个人家超清楚的！让我来告诉你～"
- "诶？你居然不知道这个吗？真是个小笨蛋～"

吞宝

性格：调皮、神秘、爱恶作剧、知识丰富
口头禅：
- "嘿嘿～又被我抓到你在问问题啦！"
- "这个知识可是很珍贵的哦，要好好记住！"
- "人家突然出现，是不是吓到你了？"

🔗 ReadmeX AI知识库集成

神吞酱现在支持与ReadmeX人工智能驱动的知识库系统互联，实现本地部署的知识库自动获取！

🚀 一键部署ReadmeX服务

# 一键部署ReadmeX AI服务
node deploy-readmex.js

# 启动服务
cd readmex-service
python start.py

📊 ReadmeX功能特性

🤖 AI驱动：基于人工智能的知识库管理
📚 自动索引：智能文档索引和分类
🔍 智能搜索：上下文感知的知识搜索
💬 问答系统：基于知识库的智能问答
🔄 实时同步：与神吞酱实时数据同步
📁 多格式支持：支持Markdown、JSON等多种格式

⚙️ ReadmeX配置

在Koishi控制台中启用ReadmeX集成：

| 配置项 | 说明 | 默认值 | |--------|------|--------| | readmexEnabled | 启用ReadmeX集成 | false | | readmexEndpoint | ReadmeX服务地址 | "http://localhost:8000" | | readmexApiKey | ReadmeX API密钥 | - | | readmexWorkspace | 工作空间名称 | "shentun-ai" | | readmexAutoSync | 自动同步知识库 | true | | readmexSyncInterval | 同步间隔(分钟) | 60 |

🎮 ReadmeX命令

🔍 知识库搜索

readmex搜索 JavaScript教程
readmex搜索 Python基础 --limit 5 --category 编程

💡 智能问答

readmex问答 如何配置Node.js环境？
readmex问答 Git最佳实践有哪些？

🔄 手动同步

readmex同步

📊 状态检查

readmex状态

🐳 Docker部署（可选）

# 使用Docker启动ReadmeX
docker-compose up -d

# 查看日志
docker-compose logs -f readmex

🛠️ 常见问题解决

❌ npm版本错误（ETARGET）

错误信息：npm error notarget No matching version found for [email protected]

解决方案：

使用本地安装（推荐）：

# 直接使用本地版本，无需npm安装
# 确保插件目录存在：external/koishi-plugin-shentun-ai

降级到稳定版本：
```
npm install [email protected]
```

使用最新版本：

npm install koishi-plugin-shentun-ai@latest

检查npm源：

npm config get registry
npm config set registry https://registry.npmjs.org/

❌ 依赖冲突错误（ERESOLVE）

错误信息：

ERESOLVE overriding peer dependency
Conflicting peer dependency: [email protected]

原因： @langchain/[email protected]需要hnswlib-node@^1.4.2，但插件使用了hnswlib-node@^2.0.0

解决方案：

已修复：已将hnswlib-node版本降级至1.4.2以匹配@langchain/community的peer dependency要求
手动修复：如果仍有问题，请手动安装兼容版本
```
npm install [email protected]
```

❌ 目录非空错误（ENOTEMPTY）

错误信息：

ENOTEMPTY: directory not empty, rename '.../koishi-plugin-shentun-ai' -> '.../.koishi-plugin-shentun-ai-xxx'

解决方案：

清理node_modules：

rm -rf node_modules/koishi-plugin-shentun-ai
rm -rf node_modules/.koishi-plugin-shentun-ai-*

重新安装：
```
npm install koishi-plugin-shentun-ai
```

使用--force参数：

npm install --force koishi-plugin-shentun-ai

❌ API密钥错误

错误信息：Error: The OPENAI_API_KEY environment variable is missing or empty

解决方案：

通用API配置示例

shentun-ai:
  apiKey: "你的API密钥"
  baseURL: "https://api.deepseek.com/v1"
  model: "deepseek-chat"

🔑 获取API密钥

DeepSeek: 访问 DeepSeek官网获取API密钥 OpenAI: 访问 OpenAI官网创建API密钥 其他OpenAI兼容API: 请参考对应服务商的文档获取API密钥

🔧 网络连接问题故障排除

通用baseURL配置指南

对于使用通用baseURL的用户，推荐以下国内API端点：

阿里云百炼（推荐）：

provider: "alibaba"
baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
apiKey: "你的阿里云API密钥"
model: "qwen-turbo"

DeepSeek：

provider: "deepseek"
baseURL: "https://api.deepseek.com/v1"
apiKey: "你的DeepSeek API密钥"
model: "deepseek-chat"

智谱AI：

provider: "zhipu"
baseURL: "https://open.bigmodel.cn/api/paas/v4"
apiKey: "你的智谱API密钥"
model: "glm-4"

网络问题解决方案

如果遇到网络连接问题（如ETIMEDOUT、ECONNREFUSED错误）：

立即解决方案：

切换到国内API：使用阿里云、DeepSeek或智谱AI

调整超时设置：

apiTimeout: 60000
apiMaxRetries: 5
apiBatchSize: 3

验证baseURL格式：确保URL以/v1结尾

高级调试：

检查网络连接：确保网络连接正常
使用代理服务器：配置代理或VPN
检查防火墙：确保API端口未被防火墙阻止
测试API连通性：使用curl测试API端点

curl测试示例：

curl -H "Authorization: Bearer 你的API密钥" \
     https://dashscope.aliyuncs.com/compatible-mode/v1/models

配置示例：

shentun-ai:
  apiKey: "你的API密钥"
  apiTimeout: 60000
  apiMaxRetries: 5
  baseURL: "https://api.deepseek.com/v1"

📄 文档索引失败

如果文档索引失败，请检查：

文档路径：确认documentPath设置正确
文档格式：确保使用支持的.md或.markdown格式
文件权限：检查是否有读取权限
批处理大小：网络较慢时减小apiBatchSize值
磁盘空间：确保有足够的存储空间

🔧 无API密钥模式

如果暂时没有API密钥，插件会以模拟模式运行：

✅ 基础聊天功能可用
✅ 文档管理功能正常
✅ 文件上传和搜索正常
❌ 高级AI对话需配置API

🚨 调试模式

启用详细日志：

# 在启动Koishi前设置环境变量
DEBUG=shentun-ai:* koishi start

📞 技术支持

遇到问题？

🧪 测试连接

# 测试ReadmeX集成
node test-readmex.js

📁 本地知识库

部署完成后，知识库将存储在：

本地路径：./readmex-service/data/
同步路径：./data/shentun-docs/readmex-kb/

🔧 高级配置

自定义AI模型

编辑 readmex-service/config.json：

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4",
    "temperature": 0.7
  }
}

添加自定义分类

在配置文件中添加分类：

{
  "knowledge_base": {
    "categories": ["编程", "教程", "文档", "最佳实践", "工具使用"]
  }
}

🔧 开发

# 安装依赖
npm install

# 编译
npm run build

# 开发模式
npm run dev

# 测试ReadmeX集成
node test-readmex.js

# 部署ReadmeX服务
node deploy-readmex.js

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

💖 支持

如果这个插件帮到了你，请给个 Star ⭐

神吞酱：人家现在可以连接ReadmeX知识库了！超厉害的AI助手升级完成！

吞宝：知识库+AI助手，今天的吞宝是无敌的！

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

神吞酱AI助手 - koishi-plugin-shentun-ai

🌟 特色功能

✨ 独立个性

🎯 主动发言

📚 文档管理 & RAG知识增强

🎭 多样互动

🚀 安装

方法1：本地安装（推荐，解决版本问题）

方法2：通过Koishi市场安装

方法3：通过npm安装（如版本已发布）

方法4：通过yarn安装（如版本已发布）

方法5：指定版本安装（如遇到版本问题）

🤖 多AI服务提供商支持

支持的AI提供商

🔑 获取API密钥

阿里云百炼

OpenAI

Claude (Anthropic)

Gemini (Google)

DeepSeek

⚙️ 配置方法

方法1：Koishi控制台配置

方法2：配置文件

方法3：环境变量

方法4：国内用户推荐配置（解决网络问题）

🎯 推荐模型配置

🔄 快速切换提供商

⚙️ 配置

基础配置

API配置选项

搜索配置

🔧 优化AI文档关联性

增强相关性算法

🎯 相关性评分机制

⚙️ 优化配置建议

📊 文档优化建议

📁 批量文档管理

支持多种上传方式

📊 文档管理命令

📈 批量上传最佳实践

🎯 一口输入给AI（大量文档支持）

📋 文档内容无法关联的解决方案

🔍 调试相关性

🔍 调试相关性

🚨 文档内容无法关联的解决方案

🎮 使用方法

基本命令

📖 文档查询

💬 自由聊天

🧠 记忆功能

🔄 性格切换

📁 文档上传 & RAG索引

🔍 智能搜索

🔧 验证与调试

🧠 RAG增强对话

被动触发

🎭 性格特点

神吞酱

吞宝

🔗 ReadmeX AI知识库集成

🚀 一键部署ReadmeX服务

📊 ReadmeX功能特性

⚙️ ReadmeX配置

🎮 ReadmeX命令

🔍 知识库搜索

💡 智能问答

🔄 手动同步

📊 状态检查

🐳 Docker部署（可选）

🛠️ 常见问题解决

🛠️ 常见问题解决

❌ npm版本错误（ETARGET）

❌ 依赖冲突错误（ERESOLVE）

❌ 目录非空错误（ENOTEMPTY）