# zblog-aiconsole

**Repository Path**: itlong/zblog-aiconsole

## Basic Information

- **Project Name**: zblog-aiconsole
- **Description**: 后台内置一个 AI 对话控制台，用自然语言直接管理网站：查目录结构、分析主题与插件、搜索报错、改模板、发内容、调设置、清缓存。插件内置 OpenAI 兼容接口调用与一整套站点工具（文件、主题插件、CMS 实体、数据库、媒体、运维），对话与工具全部由插件内 PHP Agent 完成，**不依赖 Python、不需要额外部署 Worker 或常驻进程**。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: http://www.zblog.ai
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AiConsole · ZBlog.Ai 智能控制台

在 Z-BlogPHP 后台直接用**对话**管理网站：查目录、分析主题与插件、搜索报错、改模板、发内容、调设置、清缓存。
内置 OpenAI 兼容接口调用 + 一套只读/可写文件与 CMS 工具，全部由插件内 PHP Agent 完成，**无需额外部署 Worker 或 Python 服务**。

- 插件 ID：`AiConsole`　版本：`1.0.0`　最低 PHP：**8.0**　适配 Z-BlogPHP：`173540`
- 入口：后台左侧菜单 **Zblog.Ai** → `zb_users/plugin/AiConsole/admin/main.php`
- 权限：仅**站长（root）**可用；插件未启用时所有入口直接拒绝

---

## 一、能做什么

| 场景 | 例子 |
| --- | --- |
| 看结构 | 「汇总本站概况」「分析当前主题，说明首页与文章页用了哪些文件」 |
| 查插件 | 「列出插件及启用状态，指出可能冲突或无用项」「列出所有钩子」 |
| 排查报错 | 「在 zb_users/plugin 与当前主题里搜 Warning / Fatal / Undefined，汇总可疑位置」「读错误日志尾部」 |
| 改模板样式 | 「把当前主题的 post-single.php 正文宽度改成 800px」「给主题加一个 style/dark.css」 |
| 写插件 | 「创建一个新闻插件骨架并启用」「给某插件加一个后台菜单」 |
| 内容运营 | 「新建一个『产品中心』分类并加到导航」「发一篇草稿」「批量给文章换标签」 |
| 站点设置 | 「查看站名/语言/时区/静态模式」「一键启用 STACentre 并配置 REWRITE 伪静态」 |
| 运维 | 「清缓存并重编译模板」「重建模块」「导出某张表前 50 行」 |
| 配图 | 「把这张图下载进附件库」「把文章里的外链图片转成本地」 |

界面上左侧还有一排**快捷指令**（站点概览 / 分析当前主题 / 查看插件 / 站点设置 / 排查报错 / 钩子一览 / 伪静态设置 / 清理缓存），点一下就把完整提示词填进输入框。

---

## 二、目录结构

```
zb_users/plugin/AiConsole/
├── include.php          插件注册：左侧菜单 + 菜单彩虹样式 + 安装时写配置默认值
├── emergency.php        【救急页】安全模式：登录、禁用插件、改名 include.php
├── plugin.xml           插件信息（ID / 版本 / 入口 admin/main.php）
├── admin/
│   ├── _boot.php        统一引导：定义 AICONSOLE_PATH 并载入 lib/isolate.php
│   ├── main.php         控制台主界面（会话、快捷指令、输入框、可改范围）
│   ├── chat.php         对话接口（JSON / SSE 流式），前端所有请求都打这里
│   ├── setting.php      AI 设置（保存配置、测试连接、QQ 菜单管理）
│   ├── gateway.php      外部网关：带 Token 的工具调用桥接
│   ├── qq_webhook.php   QQ 机器人回调（验签 + 事件分发）
│   └── about.php        关于页
├── lib/
│   ├── lib.php          核心库：路径安全、文件读写备份、主题/插件/CMS、工具总分发
│   ├── agent.php        AI 调用、工具循环、SSE、翻译、摘要、子菜单
│   ├── agent_tools.php  工具清单（ToolSpecs）与系统提示词
│   ├── cms_entities.php 文章/页面/评论/用户/附件/标签实体读写
│   ├── db_tables.php    通用数据表 select/insert/update/delete + 脱敏
│   ├── extra_tools.php  模块、批量操作、备份、日志、自检、导出
│   ├── fs_extra.php     删文件/删主题、列钩子、代码搜索
│   ├── media_fetch.php  远程图片抓取与附件入库
│   ├── isolate.php      隔离/安全模式启动器（AiConsole_qdjz 是唯一启动入口）
│   └── qqbot.php        QQ 官方机器人 OpenAPI 接入
├── assets/              main.css / main.js / setting.css / favicon.ico
├── data/                运行时标记文件（isolate.on / full_boot.on）与 QQ 会话 JSON
├── backup/              历史备份（main.php 的 broken / garbled 副本）
└── AiConsole1.0.0.zip   发布包
```

---

## 三、安装

1. 把整个 `AiConsole` 目录上传到 `zb_users/plugin/`（最终路径 `zb_users/plugin/AiConsole/include.php`）；
2. 后台 → **应用中心 → 插件管理**，启用「ZBlog.ai智能控制台」；
3. 左侧菜单出现 **Zblog.Ai** → 先到 **AI设置** 填好 Base URL / API Key / 模型；
4. 回控制台开聊。只做分析就保持**只读**；要改站时再勾「允许写入」。

启用时会自动写入配置：`enabled=1`、随机 `token`、以及 AI 与 QQ 的默认值。

---

## 四、AI 接口设置（后台 → AI设置）

调用的是 **OpenAI 兼容协议**，DeepSeek、Kimi、通义千问、智谱、OpenAI、各类中转/网关都能填。

| 配置项 | 键名 | 默认 | 说明 |
| --- | --- | --- | --- |
| Base URL | `ai_base_url` | 空 | 例 `https://api.openai.com`；**会自动补 `/v1`**，实际请求 `{base}/chat/completions` |
| API Key | `ai_api_key` | 空 | 只保存在本站配置里；设置页永远不回显，留空表示不修改 |
| 模型 | `ai_model` | 空 | 例 `gpt-4o-mini`、`deepseek-chat` |
| temperature | `ai_temperature` | `0.3` | 温度 |
| max_tokens | `ai_max_tokens` | `4096` | 单次上限 |
| 超时（秒） | `ai_timeout` | `120` | 小于 30 会自动按 30 处理 |
| 流式 | `ai_stream` | 关 | 勾选后边生成边显示；**需要 PHP curl 扩展** |
| 思考强度 | `ai_thinking_level` | 空（默认） | 关 / 低 / 中 / 高 → 映射为 `enable_thinking` + `reasoning_effort` + `thinking.budget_tokens` |
| 联网搜索 | `ai_web_search` | 关 | 见下面「联网搜索」 |
| 搜索协议 | `ai_web_search_mode` | `compat` | `compat` 在请求体里注入 `enable_search`/`web_search`；`openai_responses` 改走 `{base}/responses` 并带 `tools:[{type:web_search}]` |
| 额外参数 | `ai_web_search_extra` | 空 | 一段合法 JSON，合并进搜索参数（不合法会被丢弃） |

设置页有「**测试 AI 连接**」按钮（调 `chat.php?action=test`），会真发一条请求并把返回预览打出来。

**联网搜索**：上游不支持相关字段时会报 4xx，插件会自动去掉 thinking / search 相关键**重试一次**，所以填错模型参数通常也能跑。

**降级**：`ai_stream` 在 `chat.php` 里也能单次覆盖（`stream: 1`）；思考强度、联网同理，界面上的勾选优先于全局配置。

---

## 五、安全模型（务必先读）

1. **默认只读**：`allow_write = 0` 时，工具清单里只会出现只读工具，写入类工具根本不会下发给模型。
2. **写入总开关**：AI设置里勾选「允许写入」（`allow_write = 1`）后才会出现写工具；控制台的每次请求还要再过一次「本轮可写范围」。
3. **本轮可写范围**：输入框下方的「**可改**」按钮可多选——某个主题、某个插件、某个根目录；留空 = 不限制（仍受下面几条硬限制）。选择记在浏览器 localStorage。
4. **永远禁止写入**（黑名单，与范围无关）：
   - 文件：`c_option.php`、`.env`、`.htaccess`、`web.config`
   - 目录：`zb_system/`、`zb_install/`、`zb_users/data/`、`zb_users/cache/`、`zb_users/plugin/AiConsole/`（自身）
   - 扩展名：`.sql` `.sqlite` `.db` `.key` `.pem`
5. **路径安全**：相对路径解析时禁 `..`、用 `realpath` 校验不得越出站点根目录；写入还额外限制为文本类扩展名（`php html htm css js xml json txt md svg map scss less`）。
6. **自动备份**：写文件前先把原文件存为 `<file>.aicbak.<YmdHis>`，可用 `list_aic_backups` / `restore_aic_backup` 查看与回滚。
7. **敏感脱敏**：配置与数据里的 `password / token / secret / api_key / guid` 等列一律输出 `***`；插件配置读取时同样脱敏。
8. **数据库**：`table_update` / `table_delete` **必须带 where**；禁止改 AiConsole 自身配置与疑似密钥的 Config 行；`table_select` 单次 ≤ 50 行。
9. **外网抓取**：仅 http(s)、**禁内网地址**（127./10./192.168./169.254/localhost/::1）、单文件 ≤ 8MB、只收 jpg/png/gif/webp 并按文件头嗅探真实类型。
10. **会话数据**只存在你自己的浏览器 localStorage（`aic_sessions_v2_*`、`aic_write_scope_multi_*`），换浏览器或清缓存会丢。
11. 重要站点动刀前先备份；删除类操作不可恢复。

---

## 六、工具清单

工具由 `lib/agent_tools.php` 定义、`lib/lib.php` 的 `AiConsole_clzd($action, $params)` 统一分发；模型在回复里写 `{"tool": "...", "args": {...}}` 来调用。

### 只读工具（默认可用）

| 分组 | 工具 |
| --- | --- |
| 探活 / 概览 | `ping`、`site_info` |
| 文件 | `list_dir`、`read_file`（≤512000 字节，自动 GBK/BIG5→UTF-8）、`list_aic_backups` |
| 主题 / 插件 | `list_themes`、`theme_detail`、`list_plugins`、`plugin_detail`、`list_theme_styles`、`get_plugin_config`、`get_plugin_order` |
| 代码 / 日志 | `search_code`、`list_hooks`、`read_error_logs`、`http_self_check` |
| 内容 | `list_posts`、`search_posts`、`get_post`、`list_categories`、`list_tags`、`list_navbar`、`list_comments`、`list_uploads`、`search_uploads`、`list_meta_fields` |
| 模块 | `list_modules`、`get_module` |
| 数据 | `list_tables`、`describe_table`、`table_select`、`export_table`（json/csv，≤100 行） |
| 站点 / 应用中心 | `get_settings`、`list_languages`、`get_web_search`、`appcentre_status`、`appcentre_browse` |

### 写入工具（需 `allow_write = 1`）

| 分组 | 工具 |
| --- | --- |
| 文件 | `write_file`、`mkdir`、`delete_file`、`restore_aic_backup` |
| 主题 / 插件 | `create_theme`、`create_plugin`、`delete_theme`、`delete_plugin`、`enable_plugin`、`disable_plugin`、`set_theme`、`set_plugin_config`、`set_plugin_order`、`appcentre_install` |
| 内容 | `create_post`、`create_page`、`update_post`、`delete_post`、`batch_update_posts` |
| 分类 / 导航 / 标签 | `create_category`、`update_category`、`delete_category`、`navbar_add`、`navbar_remove`、`create_tag`、`update_tag`、`delete_tag`、`batch_create_tags`、`batch_delete_tags` |
| 评论 | `create_comment`、`update_comment`、`delete_comment`、`batch_approve_comments`、`batch_delete_comments` |
| 媒体 | `download_image`、`upload_media`、`import_local_media`、`replace_post_images`、`delete_upload` |
| 模块 / 侧栏 | `create_module`、`update_module`、`delete_module`、`set_sidebar`（侧栏 1–9） |
| 数据 | `table_insert`、`table_update`、`table_delete`（后两者必须带 where） |
| 站点 / 运维 | `update_settings`、`clear_cache`、`rebuild_template`、`rebuild_modules`、`setup_stacentre`、`set_language`、`set_timezone`、`set_web_search` |
| 用户 | `create_member`、`update_member`、`delete_member`（禁删创始人 / ID 1） |

Agent 循环：开启写入时最多 **24 轮**工具调用，纯只读最多 **12 轮**；历史只带最近 12 条；相同调用会去重；「只给方案不动手」最多催 2 次。

---

## 七、对话接口（供二次开发）

`admin/chat.php` 接收 **POST JSON**（也认 GET 的 `action`），需已登录 root 且带 CSRF（`csrfToken` 字段或 `X-CSRF-Token` 头）。

| action | 说明 |
| --- | --- |
| `chat` | 一轮对话，返回 `{ok, reply, tools, model, via}` |
| `chat_stream` / `stream` | SSE 流式（`text/event-stream`） |
| `ping` / `keepalive` / `session` | 探活并返回新的 `csrfToken` |
| `test` | 测试 AI 连接 |
| `site_info` | 站点概览 |
| `list_dir` | 列目录（`path` / `depth` / `max_entries`） |
| `summarize` / `summary` | 把历史压成摘要 |
| `translate` / `translate_zh` | 走 Edge 翻译成中英（≤8000 字） |
| `get_web_search` / `set_web_search` | 读 / 写联网开关 |
| `set_stream` | 写流式开关 |
| `set_thinking_level` | 写思考强度 |

请求体常用字段：`message`、`history`、`images`（base64 / data URL，单张 ≤3.5MB）、`stream`、`thinking_level`、`web_search`、`write_paths`（本轮可写范围，如 `["theme:mytheme","plugin:foo"]`，`@root` 表示整站）。

```bash
curl -X POST 'https://站点/zb_users/plugin/AiConsole/admin/chat.php' \
  -H 'Content-Type: application/json' -H 'X-CSRF-Token: <csrf>' \
  -b cookie.txt \
  -d '{"action":"chat","message":"用 site_info 汇总本站概况","write_paths":[]}'
```

---

## 八、外部网关（可选）

`admin/gateway.php` 把同一套工具以 HTTP 形式暴露给外部系统（自动化脚本、别的 AI 客户端等），**不依赖后台登录态**，改用桥接密钥。

- 鉴权：请求头 `X-AiConsole-Token: <token>`，或 GET/POST 参数 `token=<token>`；`hash_equals` 比对，不符返回 401/403。
- `token` 在启用插件时自动生成，存于 `Config('AiConsole')->token`；设置页提交 `regen_token=1` 可重新生成（也可直接 POST `token` 自定义）。
- `enabled = 0` 时网关直接 403。

```bash
curl 'https://站点/zb_users/plugin/AiConsole/admin/gateway.php' \
  -H 'X-AiConsole-Token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"action":"site_info"}'

# 读文件
curl '.../gateway.php' -H 'X-AiConsole-Token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"action":"read_file","params":{"path":"zb_users/theme/主题ID/include.php"}}'
```

`action` 即上面工具清单里的名字，`params` 为该工具参数；返回统一 `{ok, data, message, code}`。

---

## 九、QQ 机器人接入（可选）

把控制台接到 QQ 官方机器人，私聊/群里 @ 机器人即可让它查站改站。配置在 AI设置页，开关 `qq_bot_enabled`。

| 配置项 | 说明 |
| --- | --- |
| `qq_bot_enabled` | 总开关 |
| `qq_app_id` | QQ 开放平台机器人 AppID |
| `qq_app_secret` | AppSecret（用于 Ed25519 验签与回调校验） |
| `qq_allow_from` | openid 白名单，每行一个；留空则谁都不放行 |

回调地址：`https://站点/zb_users/plugin/AiConsole/admin/qq_webhook.php`

接入步骤：
1. 站点需**公网 HTTPS**（80/443/8080/8443），本机 `127.0.0.1` 或纯 HTTP 无法过校验；服务器需具备 `sodium` 或 `openssl`（页面会显示「验签能力」）。
2. 到 [QQ 开放平台](https://q.qq.com) 创建机器人，把 AppID / AppSecret 填进设置页并保存。
3. 开发设置里把上面的回调地址填进 **Webhook**；平台会发 `op=13` 验签请求，成功后回调状态变可用。
4. 订阅消息相关事件，否则收不到消息。
5. 给机器人发一条消息，未授权时它会把你的 **openid** 回给你；把 openid 填进白名单并保存，之后即可正常对话。
6. 对话走的是与控制台**同一个 Agent**（同一套工具、同一个写入开关）。

菜单管理：设置页「QQ 菜单」弹窗可拉取/编辑并推送自定义菜单（仅单聊生效，一级最多 10 个、子菜单最多 5 个），接口为 `setting.php` 的 `qq_menu_get` / `qq_menu_put`。

---

## 十、隔离启动与救急页

**隔离启动（默认开启）**：控制台页面只加载 Z-Blog 核心 + AiConsole，**不加载其他插件与主题**。坏插件拖不垮控制台，代价是本窗口里看不到、也跑不起来其它插件/主题的后台功能——要调试它们，请另开一个普通后台标签页。开关在 AI设置页，实际靠 `data/isolate.on` 与 `data/full_boot.on` 两个标记文件互斥切换（需要 `data/` 目录可写）。

**救急页**：`zb_users/plugin/AiConsole/emergency.php`
插件把后台打挂时打开它——它以 `ZBP_SAFEMODE` 启动，不加载任何插件的 `include.php`，因此基本总能打开。可在此用站长账号登录，然后：
1. 「禁用」把问题插件从 `ZC_USING_PLUGIN_LIST` 移除；
2. 仍不行点「改名 include」，把 `插件名/include.php` 改名成 `include.php.off`；
3. 极端情况用 FTP 改数据库/配置里的 `ZC_USING_PLUGIN_LIST`。

修好后把 `include.php.off` 改回，再到后台正常启用。AiConsole 自身在救急页受保护，不会被误禁用。

---

## 十一、常见问题

**Q：控制台打不开 / 白屏？**
A：多半是别的插件在后台 Hook 里报错。先开 `emergency.php` 禁用最近装/改的插件；若怀疑是本插件与其它插件冲突，到 AI设置把「隔离启动」勾上。

**Q：模型只会说方案、不动手？**
A：Agent 最多催 2 次；明确说「立刻调用 xxx 工具执行，不要只说明」（快捷指令里的「伪静态设置」就是这么写的）。另外确认该工具是不是写工具——没开「允许写入」时写工具根本不会下发。

**Q：改文件提示「超出本轮写入白名单」？**
A：在输入框下方「可改」里勾选对应主题/插件；要改站点根下的文件需勾「站点根目录 ⚠」。AiConsole 自身、`zb_system`、`c_option.php` 无论怎么勾都禁止。

**Q：流式没反应？**
A：服务器需 PHP `curl` 扩展；另外 Nginx 要放行缓冲（`X-Accel-Buffering: no` 已带），若前面还有反代需确认不缓存 SSE。

**Q：上游报 thinking / web_search 参数错误？**
A：插件会自动去掉这些键重试一次；仍报错说明上游完全不支持，把「思考强度」设为关闭、「搜索协议」改回 `compat` 或关掉联网。

**Q：会话记录丢了？**
A：会话存在浏览器 localStorage，换浏览器/清缓存/无痕模式都会丢；重要结论请复制出来或让 AI 落到文件里。

**Q：QQ 机器人不回复？**
A：依次检查：站点是否公网 HTTPS、AppSecret 是否正确、验签能力是否正常、事件是否订阅、openid 白名单是否填写、AI 接口是否配置好。

---

## 十二、数据存放与卸载

- 配置：`zbp_config` 表中 `conf_Name = 'AiConsole'` 的记录（读取：`$zbp->Config('AiConsole')->ai_model`）。
- 运行时：`data/`（隔离标记、QQ 会话 `<openid>.json`）、写入备份 `*.aicbak.*`。
- 站点模板、主题、插件等所有改动都落在站点自身目录，卸载插件不会回滚。
- **停用插件不会删除任何数据**（配置、备份、会话文件都保留），重新启用即可继续用。
- 彻底清除：停用后删除 `zb_users/plugin/AiConsole/` 目录，并删除 `zbp_config` 中 `conf_Name = 'AiConsole'` 的记录。

---

## 十三、运行环境

- Z-BlogPHP `173540` 及以上、PHP **8.0+**
- 建议开启 `curl`（流式与远程抓图必需）、`json`、`mbstring`
- QQ 机器人验签需要 `sodium` 或 `openssl`
- 无需 Python、无需常驻进程；对话与工具全部由插件内 PHP 完成