AI 自动标签（AutoTags）使用文档

作者：kuakeba.cn | 版本：1.2.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

发帖时调用 AI 分析文章标题与正文，智能提取关键词作为文章标签并自动挂载：

• 标签数量一般不超过 5 个（可配置 1-5）
• 帖子已有标签时不覆盖
• 支持主流 AI 服务商，下拉选择后仅需填入 API Key
• 支持自定义多协议接口（OpenAI Chat Completions / OpenAI Responses / Anthropic Messages）
• 后台配置页内置「连通性测试」，一键验证 AI 服务商配置是否正确
• AI 调用失败不影响正常发帖

二、环境要求

三、安装步骤

1. 将 AutoTags 目录放入 plugins/ 下
2. 进入后台 应用中心，找到「AI 自动标签」，点击 安装
3. 进入 应用中心 → AI 自动标签 → 配置，完成服务接入配置
4. 确保已安装 社区（community） 插件，否则发帖页不会出现插件入口

四、服务商配置

后台插件配置中，AI 服务商 下拉选择后，只需填入对应 API Key 即可使用（接口地址与默认模型自动带出）。

配置项说明

五、功能使用

方式一：自动提取（推荐）

开启「发帖后自动提取」后无需任何操作：

1. 用户正常发帖
2. 帖子保存成功后，插件自动将标题与正文发送给所配 AI 服务
3. AI 返回的关键词经规范化后作为标签挂载（标签不存在时自动创建）
4. 帖子已有标签则跳过，不做覆盖；AI 失败静默跳过，不影响发帖

方式二：发帖页手动提取

开启「发帖页显示按钮」后，发帖页标签选择区下方会出现 「AI 提取标签」 按钮：

1. 填写标题与正文后点击按钮
2. 按钮显示「分析中…」，稍候标签以胶囊形式展示
3. 可点击胶囊上的 × 单独移除不想要的标签
4. 发布时：若未手动选择任何标签，AI 标签自动随帖子提交；若已选择标签，AI 标签不覆盖
5. 帖子已有标签时点击按钮会提示「帖子已有标签，AI 不会覆盖」

六、接口说明

POST /autotags/generate

手动触发标签提取（需前台登录）。

请求参数（form-urlencoded）

返回示例

{
    "code": 1,
    "msg": "提取成功",
    "data": {
        "tags": ["PHP", "插件开发", "AI"]
    }
}

错误返回：code = 0，msg 为失败原因（未登录 / 未填 API Key / AI 服务异常等）。

POST /admin/apps/autotags_test

连通性测试（后台专用，需管理员登录；无请求参数，使用插件已保存配置）。

返回示例

{
    "code": 1,
    "msg": "连通性测试通过，AI 服务可正常调用",
    "data": {
        "model": "glm-4-flash",
        "preview": "连接正常"
    }
}

错误返回：code = 0，msg 为失败原因（配置不完整 / AI 服务异常 / 无权限等）。

七、常见问题

Q：点击按钮提示「请先在插件配置中填写 API Key」？

后台「应用中心 → AI 自动标签 → 配置」中填写所选服务商的 API Key 并保存。

Q：如何确认 AI 服务商配置是否正确？

在后台插件配置弹窗中点击「连通性测试」：插件会以当前已保存的配置向 AI 服务发送一条测试消息，通过则提示成功并显示所用模型；失败则返回具体原因（配置不完整 / Key 无效 / 余额不足 / 网络不通等）。修改配置后请先保存再测试。

Q：配置后依然失败，如何排查？

1. 确认 API Key 有效、账户有余额
2. 自定义接口按「API 格式」填写根地址（如 https://api.example.com/v1），系统自动补 /chat/completions、/responses 或 /v1/messages 端点；若为中转站给出的完整地址，可开启「完整 URL」直接使用
3. 豆包（火山方舟）模型名需为已开通的接入点或模型 ID
4. 服务器需能访问对应服务商域名（出网正常、PHP curl 扩展已开启）

Q：自动提取时发帖会变慢吗？

会。自动模式在帖子保存后同步调用 AI（超时 25 秒），通常增加 1-3 秒；若介意可关闭「发帖后自动提取」，仅保留发帖页按钮手动提取。

Q：标签在哪里管理？

标签由社区插件统一管理（颜色、封面等），AI 创建的标签与手动添加的标签完全一致，可在后台社区标签管理中调整。

Q：改了 static/ 目录下的文件为什么不生效？

静态资源安装时复制到 public/static/AutoTags/，修改源文件后需在后台对插件执行「升级」，或手动同步到 public 目录。