为 Zensical 网站添加 Ask AI 功能¶
使用智谱清言 GLM API 为你的 Zensical 网站添加智能 AI 助手功能
作者:Wcowin
功能预览
Ask AI 功能会在网站右下角(可自定义位置)显示一个浮动按钮,点击后弹出聊天窗口,访客可以与 AI 助手对话,AI 会基于当前页面内容回答问题。
功能特性¶
- 浮动触发按钮 - 固定在页面底部,支持左/中/右位置切换
- 流式输出 - AI 回复实时显示,体验流畅
- 上下文感知 - 自动获取当前页面内容作为上下文
- 对话历史 - 保存最近 5 轮对话,支持连续对话
- Markdown 渲染 - AI 回复支持 Markdown 格式
- 响应式设计 - 完美适配移动端和桌面端
- 暗色模式支持 - 自动适配网站主题
- 液态玻璃风格 - 现代化的毛玻璃效果
准备工作¶
1. 获取智谱清言 API Key¶
- 访问 智谱清言开放平台
- 注册并登录账号
- 在控制台创建应用并获取 API Key
API Key 安全
API Key 是敏感信息,请妥善保管,不要提交到公开仓库。
2. 创建必要的文件¶
在项目中创建以下文件结构:
1 2 3 4 5 6 | |
实现步骤¶
第一步:创建 API Key 配置文件(本地开发)¶
本地开发 vs 生产部署
这一步是用于本地开发测试的。如果你使用 GitHub Actions 部署,可以跳过这一步,直接看后面的"使用 GitHub Actions + Secrets"部分。
创建 docs/javascripts/glm-api-config.js 文件:
| docs/javascripts/glm-api-config.js | |
|---|---|
1 2 3 4 5 6 | |
重要:添加到 .gitignore
为了防止 API Key 被提交到仓库,必须将 glm-api-config.js 添加到 .gitignore 文件中:
| .gitignore | |
|---|---|
1 2 | |
如果文件已经被 Git 跟踪,需要先移除跟踪:
1 | |
第二步:创建聊天组件 JavaScript 文件¶
创建 docs/javascripts/chat-widget.js 文件:
| docs/javascripts/chat-widget.js | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 | |
第三步:创建样式文件¶
创建 docs/stylesheets/chat-widget.css 文件:
| docs/stylesheets/chat-widget.css | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 | |
第四步:配置 zensical.toml¶
在 zensical.toml 文件中添加 JavaScript 和 CSS 文件的引用:
| zensical.toml | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | |
加载顺序
确保 glm-api-config.js 在 chat-widget.js 之前加载,这样聊天组件才能正确获取 API Key。
第五步:使用 GitHub Actions + Secrets 安全注入 API Key(生产部署推荐)¶
推荐方式
这是生产环境部署的推荐方式,可以避免将 API Key 提交到代码仓库。

1. 添加 GitHub Secrets¶
- 进入你的 GitHub 仓库
- 点击
Settings→Secrets and variables→Actions - 点击
New repository secret - 添加以下 Secret:
- Name:
GLM_API_KEY - Value: 你的智谱清言 API Key
- 点击
Add secret保存
其他 Secrets
如果你还使用了其他服务(如 IndexNow),可以同样方式添加对应的 Secret。
2. 确认 .gitignore 配置¶
确保 docs/javascripts/glm-api-config.js 在 .gitignore 中:
| .gitignore | |
|---|---|
1 2 | |
3. 配置 GitHub Actions 工作流¶
在你的 GitHub Actions 工作流文件中(通常是 .github/workflows/docs.yml),在构建步骤之前添加生成配置文件的步骤:
| .github/workflows/docs.yml | |
|---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | |
注意事项
- Secrets 在 GitHub Actions 日志中会被自动脱敏(显示为
***) - 但前端打包后,API Key 仍会暴露在浏览器的 JavaScript 文件中
- 如果担心被滥用,建议:
- 在智谱清言控制台设置 API 调用限额
- 或者搭建后端代理服务,避免在前端直接调用 API
自定义配置¶
修改系统提示词¶
在 chat-widget.js 中修改 CONFIG.systemPrompt 来自定义 AI 助手的角色和行为:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
修改按钮位置¶
默认位置是 right(右侧),可以在 CONFIG.defaultPosition 中修改为 left 或 center:
1 2 3 4 | |
用户也可以通过点击位置切换按钮来改变位置,位置偏好会保存在 localStorage 中。
修改模型¶
如果需要使用其他模型,可以修改 CONFIG.model:
1 2 3 4 | |
可用模型
访问 智谱清言 API 文档 查看所有可用模型。
修改样式¶
可以通过修改 chat-widget.css 来自定义样式,例如:
- 修改按钮颜色
- 调整模态框大小
- 修改消息气泡样式
- 调整响应式断点
使用公共 API¶
聊天组件暴露了公共 API,可以在其他 JavaScript 代码中使用:
1 2 3 4 5 6 7 8 | |
安全建议¶
(1) API Key 保护
- 将
glm-api-config.js添加到.gitignore - 使用环境变量或后端代理
(2) 速率限制
- 在 API 配置中设置合理的速率限制
- 考虑在前端添加请求频率限制
(3) 输入验证
- 已内置消息长度限制(默认 500 字)
- 可以根据需要调整
maxMessageLength
测试功能¶
完成所有配置后,测试 Ask AI 功能:
本地测试
1 2 | |
http://localhost:8000,检查右下角是否出现 "Ask AI" 按钮
点击按钮,应该弹出聊天窗口
发送测试消息,例如:"这个网站是做什么的?"
检查功能
- 按钮位置是否正确
- 聊天窗口是否正常打开
- AI 回复是否正常显示(流式输出)
- 对话历史是否保存
- 清空对话功能是否正常
调试技巧
如果功能不正常,打开浏览器开发者工具(F12)查看控制台错误信息:
- 如果提示 "API Key 未配置",检查
glm-api-config.js是否正确加载 - 如果提示 "API 认证失败",检查 API Key 是否正确
- 如果提示 "请求太频繁",可能是 API 调用限额问题
常见问题¶
Q: API Key 在哪里配置?¶
A: 有两种配置方式:
- 本地开发:在
docs/javascripts/glm-api-config.js文件中直接配置(记得添加到.gitignore) - 生产部署:使用 GitHub Secrets + GitHub Actions 自动生成配置文件(推荐)
Q: 如何修改按钮位置?¶
A: 修改 chat-widget.js 中的 CONFIG.defaultPosition,或让用户通过位置切换按钮自行调整。
Q: 支持哪些浏览器?¶
A: 支持所有现代浏览器(Chrome、Firefox、Safari、Edge),需要支持 ES6+ 和 Fetch API。
Q: 如何自定义样式?¶
A: 修改 chat-widget.css 文件,所有样式都使用 CSS 变量,可以轻松适配主题。
Q: 可以更换其他 AI 服务吗?¶
A: 可以,需要修改 chat-widget.js 中的以下部分:
CONFIG.apiEndpoint- API 端点地址CONFIG.model- 模型名称fetch请求的格式(根据目标 API 的规范调整)
Q: 本地开发正常,但部署后不工作?¶
A: 检查以下几点:
- 是否配置了 GitHub Secrets(
GLM_API_KEY) - GitHub Actions 工作流是否包含生成配置文件的步骤
- 检查 GitHub Actions 构建日志,确认配置文件是否成功生成
- 确认
glm-api-config.js在.gitignore中(避免提交空文件)
Q: 如何限制 API 调用频率?¶
A: 可以通过以下方式:
- 在智谱清言控制台设置 API 调用限额
- 在前端代码中添加请求频率限制(需要修改
chat-widget.js) - 搭建后端代理服务,在后端进行频率控制
总结¶
通过以上步骤,你已经成功为 Zensical 网站添加了 Ask AI 功能。这个功能可以:
- ✅ 提升用户体验
- ✅ 帮助访客快速了解网站内容
- ✅ 提供智能问答服务
- ✅ 增强网站互动性
下一步
- 根据你的网站内容自定义系统提示词
- 调整样式以匹配网站主题
- 测试功能是否正常工作
- 考虑添加更多自定义功能
参考资源: