折雨AI（ZeyuAi）是一款面向 Typecho 的 AI 助手插件。安装后，它可以帮助你整理文章、生成 SEO 信息和标签，也可以基于站内公开文章提供访客问答与 MCP 检索服务。

image.png

这篇说明从下载插件开始，带你完成安装、AI 接口配置和常用功能设置。一般情况下，不需要了解插件内部的技术实现。

一、安装前准备

安装前请确认网站使用 Typecho 1.3、PHP 8.0 或更高版本，并提前备份网站文件和数据库。

你还需要准备一个兼容 OpenAI 接口格式的 AI 服务账号，并从服务商控制台取得以下信息：

  • API 地址
  • 模型名称
  • API Key

如果还要使用语义检索，服务商需另外提供 Embedding（向量化）模型。很多服务的对话模型和 Embedding 模型不是同一个模型，稍后可以在折雨AI中分别添加。

二、下载并安装插件

  1. 下载 ZeyuAi 插件压缩包并解压。
  2. 确认解压后的插件目录名为 ZeyuAi，入口文件 Plugin.php 应直接位于该目录中。
  3. 将整个 ZeyuAi 目录上传到 Typecho 网站的 usr/plugins/ 目录。

最终目录结构应为：

usr/
└── plugins/
    └── ZeyuAi/
        ├── Plugin.php
        ├── README.md
        └── ...

请特别留意，不要出现 usr/plugins/ZeyuAi/ZeyuAi/Plugin.php 这样的双层目录，否则 Typecho 无法正确识别插件。

上传完成后，登录 Typecho 后台，进入“控制台 → 插件”，找到“折雨AI”并点击“启用”。启用成功后，后台会出现“折雨AI”菜单。

三、建议设置独立加密密钥

这一步不是强制要求，但建议在保存 AI 服务的 API Key 之前完成。打开 Typecho 根目录下的 config.inc.php，加入下面一行：

define('TYPECHO_ZEYUAI_MASTER_KEY', '请替换为一段足够长且随机的字符串');

不要直接使用示例文字，也不要把这段密钥公开。设置后请妥善备份；网站迁移或更换服务器时，应继续使用同一密钥，否则原来保存的 API Key 可能无法解密。

如果你不方便修改配置文件，也可以跳过这一步。插件会使用 Typecho 站点密钥保护 API Key。

四、配置 AI 接口

进入“折雨AI → AI 服务”，在“新增服务”中填写接口信息。

1. 基本信息怎么填

  • 名称：仅用于后台识别，例如“主对话服务”或“向量服务”。
  • API 地址：填写到接口的版本根路径，不要填写具体请求路径。例如 OpenAI 官方接口可填写 https://api.openai.com/v1，不要在后面再加 /chat/completions。
  • 模型名称：填写服务商提供的准确模型 ID。模型名称通常区分大小写，不要填写模型的宣传名称。
  • API Key：填写从 AI 服务商控制台创建的密钥。这里不是 Typecho 登录密码，也不是后面要创建的 MCP Token。

不同服务商的 API 地址和模型名称可能不同，应以对应服务商控制台或文档中的“OpenAI 兼容接口”说明为准。

2. 正确选择服务能力

“能力”决定这个服务会被用于哪些功能：

  • 对话：用于访客对话等普通文本生成。
  • 编辑助手：用于文章页的整理正文、生成 SEO 和生成标签。
  • 向量化：用于为公开文章生成 Embedding，提升语义检索效果。

如果一个对话模型同时用于访客问答和文章编辑，可以同时勾选“对话”和“编辑助手”。只有服务商明确说明当前模型支持 Embedding 时，才勾选“向量化”。

更常见的配置方式是添加两个服务：

服务模型类型建议勾选能力
主对话服务对话模型对话、编辑助手
向量服务Embedding 模型向量化

即使暂时没有配置向量服务，折雨AI仍会建立关键词索引，访客对话和 MCP 仍可检索文章；配置向量服务后，对表达不同但含义相近的问题通常能获得更好的检索结果。

3. 其他选项怎么选

  • 权重：只有一个服务时保持 1 即可。配置多个同类服务时，权重越高，被选中的机会越多。
  • 连接超时、总超时：一般保留默认值。如果服务商响应较慢，再适当增加总超时时间。
  • 跳过 TLS 证书校验：正常情况下不要勾选。它只适用于你明确可信的自签名接口。
  • 启用此服务：保持勾选，否则插件不会调用该服务。

填写完成后点击“保存服务”。对于勾选了“对话”或“编辑助手”的服务，可以点击列表中的“测试”确认接口是否能够正常响应。测试失败时，优先检查 API 地址、模型名称、API Key、账户余额和服务商接口权限。

如果你有多个同类服务，可以逐个添加。某个服务超时、限流或暂时不可用时，折雨AI会尝试其他可用服务。

五、完成插件基础设置

回到“控制台 → 插件”，打开折雨AI的设置页面。第一次使用时，建议重点检查以下项目：

  • 编辑助手：需要在文章编辑页使用 AI 时保持启用。
  • 访客对话：需要对外提供站内问答页面时保持启用。
  • MCP 服务：需要连接 MCP 客户端时保持启用。
  • SEO 标题、SEO 摘要、封面图字段名：使用默认 Typecho 字段或 zheyu 主题时，通常可保持默认值。其他主题或 SEO 插件应填写它实际使用的自定义字段名。
  • 允许的外部封面域名：只有需要从外部图片域名选择封面时才填写；本站图片始终允许。

不确定限流、熔断和日志保留时间如何设置时，先使用默认值即可。

六、建立知识索引

进入“折雨AI → 知识索引”，在“本次处理数量”中填写每批处理的文章数，然后点击“开始处理”。初次使用建议保持默认的 10，多执行几次，直到已发布文章基本处理完成。

这个页面会显示：

  • 公开文章数量
  • 已索引文章数量
  • 文章切片数量
  • 待补全向量数量

折雨AI只索引已公开发布、没有密码保护的普通文章。草稿、私密文章、隐藏文章和独立页面不会进入访客对话或 MCP 检索结果。

没有可用的向量服务时，“待补全向量”可能不为零，但关键词检索仍然可用。后续添加向量服务后，再次分批处理即可补全向量。日常编辑、发布、删除文章或改变文章状态时，插件会自动更新相关索引。

七、使用文章编辑助手(目前最实用的功能)

image.png

新建或编辑文章时，可以在写作页看到“折雨AI”工具栏。先填写标题和正文，再根据需要使用：

  • 全部生成：一次生成正文、SEO、标签和封面建议。
  • 整理正文：优化标题层级、段落、列表和排版。
  • 生成 SEO：生成 SEO 标题与摘要。
  • 生成标签：根据当前标题、正文和已有标签给出标签建议。
  • 提取封面：从正文或附件中的现有图片选择封面，不会凭空生成新图片。

正文建议会先显示在预览区，只有点击“应用到正文”后才会替换编辑器中的内容。SEO、标签和封面会回填到当前表单，你可以继续修改，也可以使用“撤销本次回填”。

请注意，AI 结果只是当前页面中的建议，不会自动保存或发布。确认内容无误后，仍需点击 Typecho 原有的“保存草稿”或“发布文章”。如果未保存就刷新或关闭页面，本次建议会丢失。

八、启用访客对话

要让访客根据站内文章提问，请先确认：

  1. 插件设置中的“访客对话”已经启用。
  2. 至少有一个已启用并勾选“对话”能力的 AI 服务。
  3. “知识索引”中已经处理过公开文章。

进入“折雨AI → MCP 服务”，页面会显示“访客对话页面”地址。打开该地址即可测试，也可以把它加入网站导航。

访客对话只会根据可检索的站内公开文章回答，并在回答中提供文章引用。若站内资料没有相关信息，它不会读取草稿或私密内容作为补充。

九、连接 MCP 客户端

进入“折雨AI → MCP 服务”，先确认页面显示的 MCP Streamable HTTP 端点，然后创建一个 MCP Token。

创建时需要设置：

  • 名称：填写使用它的客户端名称，方便以后识别和吊销。
  • 公开文章检索：允许搜索公开文章，通常应勾选。
  • 读取完整公开正文：只有客户端确实需要读取全文时再勾选。
  • 过期天数：建议按使用周期设置；0 表示不过期。

Token 原文只在创建成功时显示一次，请立即保存到安全的密码管理工具中。丢失后无法再次查看，只能吊销旧 Token 并重新创建。

在支持 Streamable HTTP 的 MCP 客户端中添加服务器时，核心信息如下：

传输方式：Streamable HTTP
服务器地址：https://你的域名/action/zeyuai?do=mcp
认证方式：Bearer Token
Token：后台刚创建的 MCP Token

不同 MCP 客户端的设置页面名称可能略有差异，但本质上都需要服务器地址和 Bearer Token。请直接使用“折雨AI → MCP 服务”页面显示的完整地址，不要手动猜测网站子目录或伪静态路径。

MCP Token 与 AI 服务商的 API Key 是两种不同的凭据：API Key 供折雨AI调用模型，MCP Token 供外部客户端访问你的网站检索服务，请勿混用。

十、常见问题

插件列表中找不到折雨AI

检查目录是否为 usr/plugins/ZeyuAi/，并确认 Plugin.php 直接位于这个目录下。目录名大小写也应保持一致。

AI 服务测试失败

依次检查 API 地址是否只填写到版本根路径、模型 ID 是否准确、API Key 是否有效、账户是否有余额，以及服务器能否访问服务商接口。不要通过关闭 TLS 校验来绕过普通证书错误。

提示没有可用的 AI 服务

确认服务已经启用，并勾选了当前功能所需的能力。例如文章整理需要“编辑助手”，访客问答需要“对话”，向量索引需要“向量化”。服务连续失败后可能会短暂进入冷却状态，可以稍后重试并到“运行日志”查看原因。

对话找不到文章

确认文章已经公开发布、没有密码保护，并在“知识索引”中完成处理。刚修改过的文章通常会自动更新索引，也可以手动再处理一批。

AI 已生成内容，但文章没有变化

正文建议需要点击“应用到正文”，所有建议都需要通过 Typecho 原有按钮保存或发布。插件不会自动改写数据库中的文章。

MCP 客户端无法连接

确认 MCP 服务已启用、地址来自插件后台、Token 没有过期或被吊销，并且 Token 具有所需权限。认证内容应使用 Bearer 加一个空格再加 Token。

十一、安全与日常维护

  • 不要把 API Key、MCP Token 或独立加密密钥发给他人，也不要写进公开文章和截图。
  • MCP Token 应按客户端分别创建，不再使用时及时吊销。
  • 定期查看“折雨AI → 运行日志”，排查接口失败、限流或模型配置问题。
  • 更新插件前先备份。覆盖文件时保留目录名 ZeyuAi，不要随意更换 TYPECHO_ZEYUAI_MASTER_KEY。
  • AI 生成的正文、SEO、标签和封面建议都应由编辑者人工确认后再保存或发布。

完成以上设置后，折雨AI即可同时服务于文章编辑、站内问答和 MCP 检索。只打算使用其中一部分功能时，可以在插件设置中关闭不需要的入口，并只为实际用途配置对应的服务能力。

插件下载地址

ZeyuAi1.0.0.zip