1.1 系统要求

PHP 扩展要求：PDO_MYSQL（必需）、GD（必需）、cURL（必需）、mbstring（必需）、JSON（必需）、OpenSSL（必需）、Session（必需）、fileinfo（推荐）。

可通过 php -m 命令查看已安装的扩展列表。

1.2 安装部署

1.2.1 上传文件

1. 将程序压缩包解压，上传到 Web 服务器根目录或子目录
2. 确保以下目录可写：data/logs/、data/backups/、config.php（在线更新、备份与日志功能需要）
3. 将 config.php 设置为可写（安装程序会自动写入数据库配置）

1.2.2 运行安装向导

1. 浏览器访问 http://你的域名/install/
2. 按提示填写数据库主机、库名、用户名、密码、表前缀
3. 设置管理员账号和密码
4. 点击安装，系统自动创建核心表、写入默认配置、生成 config.php
5. 安装完成后删除 install/ 目录或重命名

1.2.3 伪静态配置（可选，推荐）

系统支持三种 URL 模式，默认 dynamic（动态模式，无需任何服务器配置即可运行）。需要伪静态时：

1. 到后台「插件管理」启动 rewrite 插件（其设置 Tab 才会出现在基础设置中）
2. 进入后台「基础设置 - 伪静态」，选择 rewrite 或 index 模式，可自定义各页面 URL 格式
3. 复制自动生成的服务器规则到 .htaccess（Apache）或 Nginx 配置文件中

1.3 后台使用

安装完成后访问 http://你的域名/admin/ 登录后台。

1.4 插件管理

后台「插件管理」页面（/admin/plugins.php）展示所有已扫描到的插件（内置 13 个），列表显示插件名称、描述、版本、状态、声明钩子与数据库影响。每个插件有行级操作按钮：

插件若启用且其目录下存在 admin.php，管理页面会显示「管理」按钮（跳转 /admin/plugin.php?p=插件名）；若只有 config_file（如 main.php）则显示「设置」按钮（跳转 settings.php?tab={config_tab 或插件名}）。

列表中的数据库信息格式如 articles · settings(2配置)，表示该插件创建了 articles 表并声明写入 2 条配置；向已有表添加字段时显示为 sites(5字段)。

1.5 主题切换

1. 进入后台「主题管理」
2. 在可用主题列表中点击「启用」选择要使用的主题
3. 保存后前台立即生效

主题文件放在 templates/{主题名}/ 目录下。系统通过 Theme::scan() 扫描所有含 index.php 的子目录并读取其 theme.json 展示在后台主题列表中。切换结果写入 current_theme 配置。

2.1 目录结构

2.2 核心类一览

所有核心类由 core/bootstrap.php 注册的 PSR-0 风格自动加载器按需加载（core/{类名}.php），插件代码可直接使用，无需手动 include。

2.3 数据库表概览

安装程序（install/do_install.php）初始创建以下 9 张核心表（不含插件表）：

插件启用的表（由 Plugin::ensureSchema() 自动创建，卸载时智能清理）：

2.4 辅助函数速查（core/helpers.php）

以下函数在引导阶段自动加载（core/bootstrap.php 引入 helpers.php），主题模板与插件代码中可直接调用：

3.1 主题目录结构

主题放在 templates/{主题名}/ 目录下。判定一个目录是否为可用主题：目录存在且包含 index.php（Theme::exists()），theme.json 提供展示信息。

缺失的模板文件会自动回退到 templates/default/ 对应文件（Theme::render() / Theme::partial() 均支持回退），因此可以只覆盖想自定义的页面。直接复制 templates/default/ 目录作为新主题起点是最快的做法。

3.2 theme.json

每个主题可包含 theme.json，由 Theme::getInfo() 读取并合并到默认值（名称/标题/版本/作者/简介），供后台主题管理展示；缺失时使用目录名等默认值。

{
  "name": "default",
  "title": "我的主题",
  "version": "1.0",
  "author": "你的名字",
  "description": "主题简介",
  "preview": ""
}

除 theme.json 外，系统还会自动检测 index.php / category.php / site.php / search.php / submit.php 是否存在并记录到 files 字段，供后台展示文件齐全度。

3.3 模板文件与注入变量

Route::dispatch() 解析请求后，将 core/Route.php 中各页面方法收集的变量交给 Theme::render('模板名', $vars)，通过 extract() 注入模板作用域，模板中直接使用变量（未注入的变量需用 ?? 兜底，默认主题即如此）。

3.4 Theme 类方法

全部为静态方法，主题模板与插件中可直接调用。完整清单（core/Theme.php）：

模板中未注入变量时建议兜底默认值，例如默认主题 header.php 中：$seoTitle = $seoTitle ?? $settings['site_name'] ?? '懒人导航';。

3.5 钩子列表

钩子分三类：前台模板钩子（主题模板中放置 Plugin::hook() 调用点，插件在此输出内容）、业务事件钩子（核心/插件在事件发生时触发，主题通常不感知）、后台钩子（后台页面提供，供插件注入菜单与设置 Tab）。

前台模板钩子（主题开发必放）

调用方式（带参数钩子可直接传当前数据，便于插件使用）：

<?php Plugin::hook('sidebar_top'); ?>
<?php Plugin::hook('before_content', [$site ?? []]); ?>

业务事件钩子（插件间事件通知）

后台钩子（供插件注入）

3.6 URL 生成与资源引用

所有前台 URL 必须通过 Theme::url() / Rewrite::url() 生成，系统会自动适配 dynamic / rewrite / index 三种模式，主题内禁止硬编码链接。

// URL 生成（自动适配当前伪静态模式）
<?= Theme::url('home') ?>                                        // 首页
<?= Theme::url('category', ['slug' => $cat['slug']]) ?>          // 分类页
<?= Theme::url('site', ['id' => $site['id'], 'slug' => $site['category_slug'] ?? '']) ?>  // 站点详情
<?= Theme::url('search', ['q' => 'AI']) ?>                       // 搜索页
<?= Theme::url('submit') ?>                                      // 提交页
<?= Theme::url('wormhole') ?>                                    // 虫洞联盟页
<?= Theme::url('article_list') ?>                                // 文章列表页
<?= Theme::url('article', ['id' => 1]) ?>                        // 文章详情页
<?= Theme::url('category_page', ['slug' => $slug, 'page' => 2, 'sort' => 'br']) ?> // 分类分页

// 静态资源引用（基于当前主题目录）
<link rel="stylesheet" href="<?= Theme::asset('css/style.css') ?>">
<script src="<?= Theme::asset('js/script.js') ?>"></script>
<img src="<?= Theme::asset('images/logo.png') ?>">

URL 类型与默认格式（rewrite 模式，可在后台 rewrite 插件中自定义 url_format_*）：

dynamic 模式生成的等价 URL 形如 /index.php?route=category&slug=tech。分类分页模板中通常这样配合分页函数：

<?php
$pgTemplate = Theme::url('category_page', ['slug' => $slug, 'page' => '%d', 'sort' => $sort]);
echo renderPagination($page, $totalPages, $pgTemplate);
?>

Rewrite::url() 与 Theme::url() 等价，插件或 PHP 逻辑中可直接使用 Rewrite::url()；Theme::asset() 返回 /templates/{当前主题}/{file} 形式的路径。

3.7 实战案例：创建一个主题

下面以默认主题 default 的实现模式为参照，从零创建一个可用的「极简主题」。

步骤 1：创建目录和 theme.json

templates/mytheme/theme.json:
{
  "name": "mytheme",
  "title": "极简主题",
  "version": "1.0",
  "author": "懒人导航",
  "description": "极简风格，专注内容",
  "preview": ""
}

步骤 2：编写 header.php（公共头部片段）

头部负责 SEO 变量兜底、meta 标签、CSS 引用和插件钩子：

<?php
// 片段被多页面复用，先兜底 SEO 变量（$settings 由 Route 注入）
if (!isset($seoTitle))    $seoTitle    = $settings['site_name'] ?? '懒人导航';
if (!isset($seoDesc))     $seoDesc     = '';
if (!isset($seoKeywords)) $seoKeywords = '';
?>
<?php Plugin::hook('before_header'); ?>
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="csrf-token" content="<?= Security::eAttr(Security::generateCSRFToken()) ?>">
<title><?= Theme::e($seoTitle) ?></title>
<?php if (!empty($seoDesc)): ?>
<meta name="description" content="<?= Theme::eAttr($seoDesc) ?>">
<?php endif; ?>
<link rel="stylesheet" href="<?= Theme::asset('css/common.css') ?>">
</head>
<body>
<?php Plugin::hook('after_header'); ?>

步骤 3：编写 index.php（首页）

首页用 Theme::partial('header') / Theme::partial('footer') 引入公共片段，中间按默认主题的方式放置钩子调用与列表渲染（$currentSites、$categories、$ranking、$siteStats、$showWeight 等变量见 3.3）：

<?php Theme::partial('header'); ?>

<div class="container">
  <!-- 搜索栏（JS 搜索依赖 #searchInput，可参考默认主题 footer.php 的实现） -->
  <div class="search-bar">
    <input type="search" id="searchInput" placeholder="搜索站点...">
    <?php Plugin::hook('search_bar_after'); ?>
  </div>

  <aside class="sidebar">
    <?php Plugin::hook('sidebar_top'); ?>
    <?php foreach ($categories as $cat): ?>
      <a href="<?= Theme::url('category', ['slug' => $cat['slug']]) ?>">
        <?= Theme::e($cat['name']) ?> (<?= (int)$cat['site_count'] ?>)
      </a>
    <?php endforeach; ?>
    <?php Plugin::hook('sidebar_bottom'); ?>
  </aside>

  <main>
    <?php Plugin::hook('site_list_before'); ?>
    <?= renderSiteCards($currentSites ?? [], $showWeight) ?>
    <?php Plugin::hook('site_list_after'); ?>
  </main>
</div>

<?php Theme::partial('footer'); ?>

首页共放置了 5 个钩子：search_bar_after、sidebar_top、sidebar_bottom、site_list_before、site_list_after。默认主题还提供排行榜切换、分类就地切换等 JS 交互（见 templates/default/js/site.js 与 footer.php 内联脚本），追求功能完整可直接复用。

步骤 4：编写 footer.php（公共底部片段）

<?php Plugin::hook('before_footer'); ?>
<footer>
  <a href="<?= Theme::url('home') ?>">首页</a> |
  <a href="<?= Theme::url('submit') ?>">提交站点</a>
  <p><?= Theme::e($settings['site_name'] ?? '') ?></p>
</footer>
<?php Plugin::hook('after_footer'); ?>
</body>
</html>

步骤 5：编写其他页面

按同样模式编写 category.php、site.php、search.php、submit.php 等页面。变量由 Route::dispatch() 自动注入（见 3.3）。站点详情页记得在内容前后放置带站点参数的钩子：

<?php Plugin::hook('before_content', [$site ?? []]); ?>
<!-- 详情内容 -->
<?php Plugin::hook('after_content', [$site ?? []]); ?>

步骤 6：添加 CSS 并在后台切换

在 templates/mytheme/css/common.css 中编写样式并通过 Theme::asset('css/common.css') 引用。进入后台「主题管理」，主题列表中会出现「极简主题」，点击启用后前台立即生效。

3.8 主题自带后台设置（配置项）

主题可以像插件一样自带一个后台设置页，让站点管理员在后台配置该主题的专属选项（自定义 CSS、统计代码、开关等）。这是可选的：主题目录下存在 admin.php 即自动生效，无需在 theme.json 声明任何字段。

入口与访问规则

• 后台 → 主题管理 → 当前使用中的主题 卡片右侧出现「设置」按钮（Theme::hasSettingsPage() 检测到 templates/{主题名}/admin.php 时显示）；
• 点击进入 /admin/theme.php?name={主题名}（分发器 admin/theme.php，与插件分发器 admin/plugin.php 同构），加载该主题的 admin.php 并自动包裹后台页头尾（adminHeader() / adminFooter()）；
• 安全规则：必须已登录，且只有「当前正在使用的主题」能进入设置页（与插件「未启用不能进设置」一致），未切换会提示先切换。

配置项读写（core/Theme.php）

主题配置与插件配置共用 settings 存储层，key 前缀 theme_{主题名}_（例如当前主题为 default 时，custom_css 实际存储为 theme_default_custom_css）。配置按主题隔离、存在数据库里，不随程序升级或主题文件覆盖而丢失。

编写 admin.php（完整示例见 templates/default/admin.php）

分发器已输出 adminHeader() / adminFooter()，admin.php 只需：

• 开头加访问守卫：<?php if (!defined('APP_VERSION') || !class_exists('Database')) { die('Direct access denied'); } ?>，防止被直接访问执行；
• 文件顶部处理 POST 保存：Security::verifyCSRFToken($_POST['csrf_token'] ?? '') 校验 → Theme::setConfig() 保存 → redirect() 回本页（PRG，避免刷新重复提交）；
• 输出 <div class="card"> 结构的内容，复用后台 CSS 类（form-group / form-input / btn 等）；表单必须带 name="csrf_token" 隐藏字段（值取 $_SESSION['csrf_token']）；
• 读取已存值用 Theme::config()，输出到表单用 Security::e() 转义。

<?php
// templates/mytheme/admin.php（骨架；完整示例照抄 templates/default/admin.php）
if (!defined('APP_VERSION') || !class_exists('Database')) { die('Direct access denied'); }

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!Security::verifyCSRFToken($_POST['csrf_token'] ?? '')) {
        redirect('/admin/theme.php?name=' . urlencode(Theme::current()) . '&err=' . urlencode('CSRF验证失败'));
    }
    Theme::setConfig([
        'custom_css'  => Security::cleanString($_POST['custom_css'] ?? '', 50000),
        'footer_code' => Security::cleanString($_POST['footer_code'] ?? '', 50000),
    ]);
    redirect('/admin/theme.php?name=' . urlencode(Theme::current()) . '&ok=' . urlencode('主题设置已保存'));
}
$customCss  = (string)Theme::config('custom_css', '');
$footerCode = (string)Theme::config('footer_code', '');
?>
<div class="card">
  <div class="card-header"><span class="card-title">主题设置</span></div>
  <form method="POST">
    <input type="hidden" name="csrf_token" value="<?= Security::eAttr($_SESSION['csrf_token'] ?? '') ?>">
    <div class="form-group">
      <label>自定义 CSS</label>
      <textarea name="custom_css" class="form-input" rows="8"><?= Security::e($customCss) ?></textarea>
      <div class="form-help">输出到前台 &lt;head&gt;</div>
    </div>
    <div class="form-group">
      <label>页脚统计代码</label>
      <textarea name="footer_code" class="form-input" rows="4"><?= Security::e($footerCode) ?></textarea>
    </div>
    <button type="submit" class="btn btn-primary">保存设置</button>
  </form>
</div>

在主题模板中消费配置

主题模板（header/footer 等）用 Theme::config() 读取并输出。以默认主题为例：

• header.php：在 </head> 前把 custom_css 包进 <style> 输出（先对内容做 str_ireplace('</style', '<\/style', ...) 转义，防止提前闭合样式块）；
• footer.php：在 </body> 前输出页脚代码（统计代码用 Security::cleanHtml() 过滤，允许 script 但剔除 on* 事件与危险协议）。

4.1 插件目录结构

插件放在 plugins/{插件名}/ 目录下，目录名即插件名（小写字母/数字/连字符）。一个完整插件可包含以下文件：

所有 PHP 文件开头建议加安全检查，阻止被直接 URL 访问（各内置插件统一写法）：

<?php
if (!defined('APP_VERSION') || !class_exists('Database')) {
    die('Forbidden');
}

4.2 plugin.json

每个插件根目录必须有 plugin.json，由 Plugin::getInfo() 读取并与默认值合并：

{
    "name": "myplugin",
    "title": "我的插件",
    "version": "1.0",
    "author": "你的名字",
    "description": "插件功能描述",
    "main_file": "include.php",
    "config_file": "main.php",
    "config_tab": "myplugin",
    "schema_file": "schema.php",
    "hooks": ["sidebar_top", "after_footer"],
    "tables": ["mytable"],
    "builtin": true
}

注意：插件启用状态不写在 plugin.json 中，而是由系统管理在 settings 表（plugin_{name}_enabled，安装时写入 0）。

4.3 schema.php 机制

schema.php 是插件数据库声明文件，返回一个包含三个部分的数组：

<?php
return [
    // 1. 独立表：插件启用时自动 CREATE TABLE IF NOT EXISTS
    'tables' => [
        'mytable' => "CREATE TABLE IF NOT EXISTS `{prefix}mytable` (
            id INT PRIMARY KEY AUTO_INCREMENT,
            title VARCHAR(200) NOT NULL,
            content TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            INDEX idx_title (title)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;",
    ],

    // 2. 向已有表添加字段：插件启用时自动 ALTER TABLE ADD COLUMN（跳过已存在）
    'columns' => [
        'sites' => [
            'my_field' => "VARCHAR(100) DEFAULT '' COMMENT '自定义字段'",
        ],
    ],

    // 3. 默认配置项：插件启用时写入 settings 表（仅当配置项不存在时写入）
    'config' => [
        'plugin_myplugin_count'  => '5',
        'plugin_myplugin_enable' => '1',
    ],
];

ensureSchema() 执行流程

当插件被启用时，Plugin::setEnabled($name, true) 会自动调用 Plugin::ensureSchema($name)：

1. 创建独立表：遍历 tables，通过 information_schema 检查表是否存在，不存在则执行 SQL（{prefix} 占位符替换为实际表前缀）
2. 添加字段：遍历 columns，通过 information_schema.columns 检查字段是否存在，不存在则 ALTER TABLE ADD COLUMN
3. 写入配置：遍历 config，检查 settings 表中是否已存在该 key，不存在则写入默认值

配置项命名规范

插件配置项建议使用 plugin_{插件名}_{配置键} 的命名格式存储在 settings 表中（schema.php 的 config 中直接写完整 key，如 'plugin_myplugin_count'），并配合 Plugin::config('myplugin', 'count', 默认值) 读取——该方法内部即拼接 plugin_{plugin}_{key} 前缀。

少数早期插件（如 auto-link 的 autolink_enable、autolink_need_review、autolink_default_category、autolink_banned_words）仍沿用不带前缀的键名，由后台 admin/settings.php 对应 case 直接保存。两种方式都可用，新插件请统一使用 plugin_ 前缀。

4.4 include.php 与钩子注册

include.php 是插件主文件（main_file），负责定义类/函数并注册钩子：

<?php
// 安全检查：阻止直接访问（所有插件文件统一写法）
if (!defined('APP_VERSION') || !class_exists('Database')) {
    die('Forbidden');
}

/**
 * 输出插件内容（可用 Plugin::config 读取配置）
 */
function myplugin_render(): void
{
    $count = (int)Plugin::config('myplugin', 'count', '5');
    // ... 业务逻辑（可用 Database::query 等核心类）
    echo '<div class="myplugin">内容</div>';
}

// 注册前台动作钩子（第 3 个参数为优先级，数字越小越先执行，默认 10）
Plugin::registerHook('sidebar_top', function () {
    myplugin_render();
});

// 注册过滤钩子（返回模式：返回值作为下一个回调的入参）
Plugin::registerHook('filter_title', function ($title) {
    return $title . ' - 我的插件';
});

// 注册后台侧边栏菜单（进入独立管理页 /admin/plugin.php?p=myplugin）
Plugin::registerHook('admin_sidebar', function () {
    $cls = ($GLOBALS['currentPage'] ?? '') === 'myplugin' ? 'active' : '';
    echo '<a href="/admin/plugin.php?p=myplugin" class="nav-item ' . $cls . '">'
       . '<i class="ti ti-star"></i><span>我的插件</span></a>';
});

可用钩子全集与参数见 3.5 节。

4.5 main.php 设置面板

main.php（config_file）通过注册两个后台钩子，在基础设置页面注入自定义 Tab：

<?php
if (!defined('APP_VERSION') || !class_exists('Database')) {
    die('Forbidden');
}

// 钩子1：注入 Tab 导航标签（tab ID 默认等于插件名）
Plugin::registerHook('admin_settings_nav', function ($activeTab) {
    $cls = $activeTab === 'myplugin' ? 'active' : '';
    echo '<a href="#tab-myplugin" class="settings-tab ' . $cls . '"'
       . ' onclick="switchTab(\'myplugin\', this)">我的插件</a>';
});

// 钩子2：注入 Tab 内容面板
Plugin::registerHook('admin_settings_tabs', function ($activeTab) {
    $cls = $activeTab === 'myplugin' ? 'active' : '';
    ?>
<div id="tab-myplugin" class="tab-panel <?= $cls ?>">
  <div class="card">
    <div class="card-header"><span class="card-title">我的插件设置</span></div>
    <form method="POST" action="/admin/settings.php">
      <input type="hidden" name="csrf_token" value="<?= Security::eAttr($_SESSION['csrf_token'] ?? '') ?>">
      <input type="hidden" name="section" value="myplugin">
      <input type="hidden" name="tab" value="myplugin">

      <div class="form-group">
        <label>显示数量</label>
        <input type="number" class="form-input" name="plugin_myplugin_count"
               value="<?= Security::eAttr(Plugin::config('myplugin', 'count', '5')) ?>">
      </div>

      <div class="text-right">
        <button type="submit" class="btn btn-primary">保存</button>
      </div>
    </form>
  </div>
</div>
<?php
});

4.6 Plugin 类 API

以下为 core/Plugin.php 的全部公开静态方法（插件代码与模板中均可调用）：

数据库与安全的通用调用（插件内最常用）：Database::table('表名')（带前缀表名）、Database::query() / queryOne() / execute() / insert() / scalar()、Security::e() / eAttr() / cleanString() / cleanHtml() / int()、setting() / Rewrite::url()。

4.7 共享表与卸载

当多个插件声明同一张表时（如 blacklist 表被 wormhole 和 auto-link 共同声明），系统会智能处理：

• 启动时：ensureSchema() 使用 CREATE TABLE IF NOT EXISTS，重复执行安全
• 卸载时：Plugin::uninstall() 通过 getPluginsDeclaringTable() 检查是否还有其他插件（无论启用与否）声明该表（schema.php tables + plugin.json tables 均计入）。只要有，就跳过删表
• 全部卸载时：当最后一个声明该表的插件被卸载时，才真正执行 DROP TABLE

Plugin::uninstall($name) 的完整流程与返回：

1. 停用插件（plugin_{name}_enabled = 0）
2. 删除自建表（智能处理共享表，见上）
3. 删除 schema.php columns 声明添加到已有表的字段（ALTER TABLE DROP COLUMN）
4. 清除配置：删除 plugin_{name}_% 前缀通配命中项 + schema.php config 声明的 key
5. 清除扫描缓存，写 plugin_uninstall 频道日志
6. 返回 ['success' => bool, 'dropped_tables' => [], 'dropped_columns' => [], 'cleared_keys' => int]（后台插件管理页据此展示结果）

插件文件本身不会被删除，卸载后可随时重新启动（重新执行 ensureSchema 安装结构与默认配置）。

4.8 实战案例：每日一言插件

下面创建一个完整的「每日一言」插件，展示从 plugin.json 到 schema.php、include.php、main.php 的完整开发流程。

功能：前台侧边栏显示每日一条名言，后台可管理名言列表和显示设置。

4.8.1 创建目录

plugins/daily-quote/
    plugin.json
    schema.php
    include.php
    main.php
    admin.php

4.8.2 plugin.json

{
    "name": "daily-quote",
    "title": "每日一言",
    "version": "1.0",
    "author": "懒人导航",
    "description": "前台侧边栏显示每日名言，后台可管理名言列表。",
    "main_file": "include.php",
    "config_file": "main.php",
    "schema_file": "schema.php",
    "hooks": ["sidebar_bottom", "admin_sidebar"],
    "tables": ["quotes"],
    "builtin": false
}

4.8.3 schema.php

声明一张独立的 quotes 表和 2 个默认配置项：

<?php
/**
 * 每日一言插件 - 数据库声明
 * 启用插件时自动创建 quotes 表并写入默认配置
 */

return [
    // 独立表
    'tables' => [
        'quotes' => "CREATE TABLE IF NOT EXISTS `{prefix}quotes` (
            id INT PRIMARY KEY AUTO_INCREMENT,
            content VARCHAR(500) NOT NULL COMMENT '名言内容',
            author VARCHAR(100) DEFAULT '' COMMENT '作者',
            status TINYINT DEFAULT 1 COMMENT '状态(1=启用,0=禁用)',
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            INDEX idx_status (status)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='每日言表';",
    ],

    // 向已有表添加字段（无）
    'columns' => [],

    // 默认配置项
    'config' => [
        'plugin_daily-quote_count'    => '1',
        'plugin_daily-quote_template' => 'card',
    ],
];

4.8.4 include.php

定义 Model 类、注册前台钩子和后台侧边栏入口：

<?php
/**
 * 每日一言插件 - 主文件
 */

if (!defined('APP_VERSION') || !class_exists('Database')) {
    die('Forbidden');
}

/**
 * 每日一言模型
 */
class DailyQuoteModel
{
    /**
     * 获取随机名言
     */
    public function getRandom(int $limit = 1): array
    {
        $tbl = Database::table('quotes');
        return Database::query(
            "SELECT * FROM {$tbl} WHERE status = 1 ORDER BY RAND() LIMIT ?",
            [$limit]
        );
    }

    /**
     * 获取全部名言
     */
    public function getAll(): array
    {
        $tbl = Database::table('quotes');
        return Database::query("SELECT * FROM {$tbl} ORDER BY id DESC");
    }

    /**
     * 创建名言
     */
    public function create(string $content, string $author = ''): int
    {
        $tbl = Database::table('quotes');
        return Database::insert(
            "INSERT INTO {$tbl} (content, author) VALUES (?, ?)",
            [Security::cleanString($content, 500), Security::cleanString($author, 100)]
        );
    }

    /**
     * 删除名言
     */
    public function delete(int $id): bool
    {
        $tbl = Database::table('quotes');
        return Database::execute("DELETE FROM {$tbl} WHERE id = ?", [$id]) > 0;
    }

    /**
     * 切换状态
     */
    public function toggleStatus(int $id): bool
    {
        $tbl = Database::table('quotes');
        return Database::execute(
            "UPDATE {$tbl} SET status = 1 - status WHERE id = ?",
            [$id]
        ) > 0;
    }
}

// ========== 钩子注册 ==========

// 前台侧边栏：显示每日一言
Plugin::registerHook('sidebar_bottom', function () {
    $count = (int)Plugin::config('daily-quote', 'count', '1');
    $model = new DailyQuoteModel();
    $quotes = $model->getRandom($count);

    if (empty($quotes)) {
        return;
    }
    ?>
    <div class="daily-quote-widget" style="margin-top:16px;padding:12px;border-radius:8px;background:#f0f4ff;">
        <div style="font-size:13px;color:#999;margin-bottom:8px;">
            <i class="ti ti-quote"></i> 每日一言
        </div>
        <?php foreach ($quotes as $q): ?>
        <div class="quote-item" style="margin-bottom:8px;">
            <p style="font-size:14px;color:#333;line-height:1.6;">
                <?= Theme::e($q['content']) ?>
            </p>
            <?php if (!empty($q['author'])): ?>
            <p style="font-size:12px;color:#999;text-align:right;">
                —— <?= Theme::e($q['author']) ?>
            </p>
            <?php endif; ?>
        </div>
        <?php endforeach; ?>
    </div>
    <?php
});

// 后台侧边栏：注入管理入口
Plugin::registerHook('admin_sidebar', function () {
    $cls = ($GLOBALS['currentPage'] ?? '') === 'daily-quote' ? 'active' : '';
    echo '<a href="/admin/plugin.php?p=daily-quote" class="nav-item ' . $cls . '">'
       . '<i class="ti ti-quote"></i><span>每日一言</span></a>';
});

4.8.5 main.php（后台设置 Tab）

<?php
/**
 * 每日一言插件 - 设置面板
 */

if (!defined('APP_VERSION') || !class_exists('Database')) {
    die('Forbidden');
}

// 注入 Tab 导航
Plugin::registerHook('admin_settings_nav', function ($activeTab) {
    $cls = $activeTab === 'daily-quote' ? 'active' : '';
    echo '<a href="#tab-daily-quote" class="settings-tab ' . $cls . '"'
       . ' onclick="switchTab(\'daily-quote\', this)">每日一言</a>';
});

// 注入 Tab 内容
Plugin::registerHook('admin_settings_tabs', function ($activeTab) {
    $cls = $activeTab === 'daily-quote' ? 'active' : '';
    ?>
<div id="tab-daily-quote" class="tab-panel <?= $cls ?>">
  <div class="card">
    <div class="card-header"><span class="card-title">每日一言设置</span></div>
    <form method="POST" action="/admin/settings.php">
      <input type="hidden" name="csrf_token" value="<?= Security::eAttr($_SESSION['csrf_token'] ?? '') ?>">
      <input type="hidden" name="section" value="daily-quote">
      <input type="hidden" name="tab" value="daily-quote">

      <div class="form-group">
        <label>显示数量</label>
        <input type="number" name="plugin_daily-quote_count" min="1" max="10"
               value="<?= Security::e(Plugin::config('daily-quote', 'count', '1')) ?>">
        <p class="form-help">侧边栏每次显示几条名言</p>
      </div>

      <div class="text-right">
        <button type="submit" class="btn btn-primary">保存设置</button>
      </div>
    </form>
  </div>
</div>
<?php
});

4.8.6 admin.php（名言管理页面）

<?php
/**
 * 每日一言插件 - 后台管理页面
 * 通过 /admin/plugin.php?p=daily-quote 访问
 */

$model = new DailyQuoteModel();

// 处理 POST 操作
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!Security::verifyCSRFToken($_POST['csrf_token'] ?? '')) {
        die('CSRF 校验失败');
    }

    $action = $_POST['action'] ?? '';
    if ($action === 'create') {
        $model->create($_POST['content'] ?? '', $_POST['author'] ?? '');
        echo '<div class="alert alert-success">添加成功</div>';
    } elseif ($action === 'delete') {
        $model->delete((int)($_POST['id'] ?? 0));
        echo '<div class="alert alert-success">删除成功</div>';
    } elseif ($action === 'toggle') {
        $model->toggleStatus((int)($_POST['id'] ?? 0));
    }
}

$quotes = $model->getAll();
?>

<div class="card">
  <div class="card-header"><span class="card-title">添加名言</span></div>
  <form method="POST">
    <input type="hidden" name="csrf_token" value="<?= Security::eAttr($_SESSION['csrf_token'] ?? '') ?>">
    <input type="hidden" name="action" value="create">
    <div class="form-group">
      <label>内容</label>
      <textarea name="content" rows="3" required></textarea>
    </div>
    <div class="form-group">
      <label>作者（可选）</label>
      <input type="text" name="author">
    </div>
    <button type="submit" class="btn btn-primary">添加</button>
  </form>
</div>

<div class="card" style="margin-top:16px;">
  <div class="card-header"><span class="card-title">名言列表</span></div>
  <table>
    <thead><tr><th>ID</th><th>内容</th><th>作者</th><th>状态</th><th>操作</th></tr></thead>
    <tbody>
    <?php foreach ($quotes as $q): ?>
      <tr>
        <td><?= (int)$q['id'] ?></td>
        <td><?= Security::e($q['content']) ?></td>
        <td><?= Security::e($q['author']) ?></td>
        <td><?= $q['status'] ? '启用' : '禁用' ?></td>
        <td>
          <form method="POST" style="display:inline">
            <input type="hidden" name="csrf_token" value="<?= Security::eAttr($_SESSION['csrf_token'] ?? '') ?>">
            <input type="hidden" name="action" value="delete">
            <input type="hidden" name="id" value="<?= (int)$q['id'] ?>">
            <button type="submit" onclick="return confirm('确认删除?')">删除</button>
          </form>
        </td>
      </tr>
    <?php endforeach; ?>
    </tbody>
  </table>
</div>

4.8.7 启动插件

1. 将 daily-quote 目录放入 plugins/
2. 进入后台「插件管理」，找到「每日一言」
3. 点击「启动」——系统自动创建 quotes 表、写入 2 条默认配置、加载插件代码
4. 前台首页侧边栏底部出现每日一言
5. 后台侧边栏出现「每日一言」管理入口，可添加/删除名言
6. 后台「基础设置」出现「每日一言」Tab，可修改显示数量（保存分支需在 settings.php 增加 case，见 4.5）

5.1 插件一览

系统内置 13 个插件，全部默认关闭（安装时写入 plugin_{name}_enabled=0）。安装后根据需要在后台「插件管理」中启动，启用时才执行建表/加字段/写默认配置。

钩子列 = 插件实际注册的钩子；主题需要为前台钩子保留调用点（见 3.5），后台钩子（admin_*）由系统页面自动触发。

5.2 广告管理 (ad)

后台可配置 6 个广告位的 HTML 代码，前台在对应位置展示。

启用后在后台「基础设置 - 广告管理」Tab（ad/main.php 注入）为每个广告位填写 HTML。内容存储为 plugin_ad_{位置} 配置，输出前经 Security::cleanHtml() 清洗。ad/include.php 在前台注册了上表全部 6 个钩子，内容直接 echo 到对应位置。

5.3 文章发布 (article)

启用后前台出现文章列表/详情页（路由 article_list / article，模板 article_list.php / article_detail.php），侧边栏注入「文章专栏」入口；后台侧边栏出现「文章管理」入口（/admin/plugin.php?p=article，plugins/article/admin.php）。支持分类、标签、发布/草稿/待审状态与浏览量统计；编辑器支持扩展钩子（article_editor_before / article_editor_after）供其他插件加字段。

数据库：articles 表（title、slug、content(HTML)、excerpt、author、category、tags、status、views、created_at、updated_at）。默认配置：plugin_article_per_page（列表每页条数）、plugin_article_enable_submit（是否开放投稿）。

文章相关页面未启用该插件时访问返回 404；article_list / article_detail 模板仅在该插件启用后有意义。

5.4 虫洞联盟 (wormhole)

站点互推机制：联盟成员在页面嵌入 JS（/api/?endpoint=wormhole.js），互相展示成员站点实现流量互传；内置随机传送（teleport）、每日检测与黑名单管理。

数据库影响：创建 blacklist 表（与 auto-link 共享）；向 sites 表添加联盟字段（wormhole_status、wormhole_joined_at、wormhole_last_check、wormhole_check_fail、wormhole_source_domain、wormhole_quality_score、wormhole_click_in/out、wormhole_last_content_update、wormhole_quality_updated_at 等）；默认配置：wormhole_enable、wormhole_need_review、wormhole_fallback_category、plugin_wormhole_rate_limit、block_all_ip。

外站嵌入代码

联盟成员需要在页面中嵌入以下 JS（后台虫洞联盟管理页可复制）：

<script>
(function(){
    var d=document,s=d.createElement('script');
    s.src='https://你的主站/api/?endpoint=wormhole.js';
    s.async=1;
    d.body.appendChild(s);
})();
</script>

定时检测：可配 crontab 每天执行 core/cron_wormhole_check.php（抓取 auto 成员页面检查是否仍含联盟代码，失败累计达阈值标记 broken）：

0 3 * * * php /path/to/core/cron_wormhole_check.php

相关 API 端点：wormhole（成员列表）、wormhole.js（嵌入脚本）、wormhole-teleport（随机传送）、wormhole-join（加入上报，返回 GIF）；插件未启用时这些端点返回 403（join 返回透明 GIF）。

5.5 友链自动收录 (auto-link)

当用户从挂了本站友链的外站点击进入时，系统自动检测来路、验证回链、抓取 TDK、检查违禁词与黑名单，通过后自动收录。

工作流程：PHP 渲染页面时捕获 Referer → 过滤本站与搜索引擎 → 插件在 after_footer 钩子注入 JS，延迟 2 秒发送 /api/?endpoint=auto-link&ref=xxx → 后端 AutoLinkModel::process() 抓取对方首页验证回链、抓取 TDK、检查违禁词/黑名单/频率限制/重复域名 → 插入数据库。

配置项（基础设置「友链收录」Tab，auto-link/main.php 注入；键名沿用 autolink_* 兼容旧版）：autolink_enable（开关）、autolink_need_review（是否需审核）、autolink_default_category（默认分类）、autolink_banned_words（违禁词）。

安全机制：Referer 预过滤、搜索引擎排除、内网地址防护（Security::isInternalHost()）、黑名单检查（blacklist 表，与 wormhole 共享）、频率限制、回链验证、违禁词检查、重复域名检查。插件未启用时访问 auto-link 端点返回 1x1 透明 GIF。

5.6 伪静态设置 (rewrite)

URL 模式与格式配置。启动后在后台「基础设置 - 伪静态」Tab（rewrite/main.php 注入）配置：

• 模式：dynamic（默认，无需服务器规则）/ rewrite（伪静态，需服务器规则）/ index（URL 含 index.php 的兼容模式）
• URL 格式：9 个页面（home/category/category_page/site/search/submit/wormhole/article_list/article）可自定义模板，占位符 {%slug%}、{%id%}、{%page%}（见 3.6）
• 规则生成：一键生成并复制 Apache .htaccess / Nginx 规则（Rewrite::generateHtaccess() / generateNginx()，含敏感目录与模板文件防护），支持写入项目根 .htaccess

Rewrite.php 内置默认格式（$defaults），配置存于 settings（rewrite_mode + url_format_*）；未启用插件时前台仍可用 dynamic 模式正常工作。

钩子：admin_settings_nav / admin_settings_tabs（注入设置 Tab）。

5.7 提交网站收录 (submit)

前台提交入口与收录审核。配置在后台「基础设置 - 提交收录」Tab（submit/main.php 注入）：允许提交、需审核、前台是否显示权重、默认分类、是否强制选分类、收录分类白名单（category_ids）、提交频率限制、TDK 抓取频率限制、提交说明文本；存储为 plugin_submit_* 配置（如 plugin_submit_enable_submit、plugin_submit_need_review、plugin_submit_show_weight 等）。

前台提交页由路由 submit 渲染（模板 submit.php，注入 $enable / $needReview）；表单提交到 /api/?endpoint=submit（需 CSRF，submit 插件未启用返回 403），支持 TDK 自动抓取与邮箱采集（sites.submit_email，供 notify 插件使用）。提交后进入后台「提交审核」处理。

5.8 站点地图 (sitemap)

自动生成 sitemap.xml 与 robots.txt，收录首页、分类页、站点详情页与文章页；支持缓存、分片（sitemap-{n}.xml）与手动重新生成。站点地图由路由层直接输出（Route::sitemap() / Route::robots()，无需该插件也能访问，但生成逻辑与后台按钮由插件提供）。

后台「基础设置 - 网站地图」Tab（sitemap/main.php 注入）可查看状态、缓存并手动生成；此插件无前台模板钩子。

5.9 图片灯箱 (lightbox)

纯前端钩子插件，无数据库影响。详情页图片点击放大，自动给图片加 data-lightbox 属性。内置轻量灯箱实现，无需外部依赖。

钩子与模板挂接

插件注入效果

插件通过 after_footer 钩子注入轻量 CSS + JS（无需外部依赖），自动为 .site-details img 与 .article-content img 绑定点击放大，支持键盘 ESC 关闭；不改变原图 DOM 与链接行为。

5.10 图片ALT (auto-alt)

纯前端钩子插件，无数据库影响。通过 after_footer 钩子注入 JS，自动给页面中缺少 alt 属性的 <img> 补填站点名称或描述，提升 SEO 与无障碍访问。

与灯箱（lightbox）插件一样依赖主题在 footer.php 中调用 Plugin::hook('after_footer')。

5.11 邮箱通知 (notify)

通过原生 PHP socket 实现 SMTP 邮件发送，在站点提交、审核通过/拒绝、用户反馈时自动通知管理员和提交者。

触发场景

数据库影响

SMTP 配置

启用后进入后台「基础设置 - 邮箱通知」Tab 配置：

测试发送

插件管理页面（/admin/plugin.php?p=notify）提供：

• SMTP 测试发送：输入任意邮箱地址，立即发送测试邮件验证配置是否正确
• 发送日志：分页查看所有通知记录，支持按类型/状态筛选
• 清空日志：一键清空历史发送记录

通知行为细节

• 无邮箱的提交者：通过/拒绝通知只发送给管理员，不尝试通知提交者（不会报错或空发）
• 审核通过：在「提交审核」页直接点「通过」、点「编辑并发布」、或在「站点管理」编辑 pending 站点为 published，都会触发 site_approved 钩子
• HTML 邮件模板：内置响应式邮件模板，含站点名称、URL、审核结果和操作按钮
• 失败重试：SMTP 连接失败时记录错误日志但不中断页面流程

提交者邮箱采集

前台提交表单（/templates/default/submit.php）已增加邮箱输入框。API 端点 /api/?endpoint=submit 接收并写入 sites.submit_email 字段。没有邮箱的提交不影响正常收录。

5.12 友情链接 (friendlink)

友情链接管理：后台可快速添加友链（名称 + 链接 + 自定义 CSS 类 + 图标），前台底部区块展示（支持设置区块标题、打开方式、最大显示数量）。

数据库：friendlinks 表（name、url、css_class、icon、sort_order、status）。配置：plugin_friendlink_title、plugin_friendlink_target、plugin_friendlink_max_display。

5.13 蜘蛛来访 (spider)

统计各大搜索引擎蜘蛛来访记录：按 User-Agent 识别百度/Google/Bing/搜狗/360/字节/Yandex 等引擎，支持按引擎开关、今日/昨日/近 7 日/近 30 日趋势与汇总图表，数据自动保留 30 天（可配置）。

数据库：spider_visits 表。配置：plugin_spider_engines（启用的引擎）、plugin_spider_retention_days（保留天数，默认 30）。

5.14 数据库备份 (dbtool)

数据库备份与恢复工具：一键备份（纯 PHP PDO 导出当前表前缀下全部表结构与数据为 SQL）、下载备份到本地、删除备份、从备份文件恢复、上传 SQL 文件导入。备份存储于 data/backups/，文件名严格校验并防路径穿越。

无任何钩子：后台入口由插件管理页自动提供——该插件目录存在 admin.php，启用后在「插件管理」点击「管理」进入（/admin/plugin.php?p=dbtool），不会出现在侧边栏导航中。

6.1 API 接口

所有 API 通过 /api/?endpoint={端点名}（或伪静态 /api/{端点名}）访问。POST 接口默认需要 CSRF 校验（Token 放在 X-CSRF-Token 头或 csrf_token 字段，页面模板会输出 csrf-token meta），click/rate/feedback 三个公开端点豁免。

开放 API（API Key 鉴权，open/*）

需在后台「API 密钥」创建 Key，请求头携带 X-API-Key（或参数 api_key，POST 也支持 JSON 请求体中的 api_key 字段），响应头返回 X-RateLimit-* 限流信息。API Key 视为受信凭证：除查询外，还提供站点发布 / 编辑 / 删除与分类新增 / 编辑 / 删除，App、小程序、前台自定义提交页可直接调用（免 CSRF）。

📄 完整《开放 API 对接文档》（含各接口请求/响应示例与代码示例）：data/docs/api-guide.md；后台「API 密钥」页面的使用说明为实时清单（已启用插件接口自动出现）。

站点查询

站点发布 / 编辑 / 删除（写接口）

分类管理

系统查询

内置插件接口（插件启用后自动注册）

内置插件在各自目录提供 api.php 接口声明：插件启用后其 open/插件/* 接口自动注册并在后台「API 密钥」使用说明中自动展示查询案例与说明；停用后接口失效（返回 403 / 40301）。

6.2 日志系统

通过 Logger::log($channel, $message) 写入日志，按日期分目录、按频道分文件存储。

// 写单条日志
Logger::log('admin_site', "[编辑] 站点ID={$siteId}，结果=成功");

// 批量写日志
Logger::logs('wormhole_check', [
    "检测通过：site_id=1",
    "检测失败：site_id=3，原因=404",
]);

// 判断某频道是否开启（可在耗时日志前使用）
if (Logger::isEnabled('autolink')) {
    Logger::log('autolink', $detail);
}

// 获取日志文件路径
$file = Logger::getLogFile('wormhole_join');
// 返回：data/logs/20260808/wormhole_join.log

日志目录：data/logs/YYYYMMDD/{channel}.log，单行格式 [HH:MM:SS] 内容。

开关配置（后台操作）

后台「基础设置 - 基础信息 - 日志设置」提供完整开关界面：

• 日志总开关 log_global：关闭后所有日志停止写入；关闭时不会改动各频道开关值，重新开启后按原频道设置生效
• 频道独立开关 log_{channel}：总开关开启后自动展开，可按频道单独开启/关闭（默认全部开启）

全部频道（分组与后台界面一致）：

除内置频道外任意频道均可写入（如 Logger::log('my_channel', ...)），未配置开关的频道默认开启。

6.3 伪静态配置

伪静态系统支持三种模式（配置入口：rewrite 插件启动后的后台「基础设置 - 伪静态」Tab）：

分类页分页格式 category/{slug}/page-{n}/；9 个页面的 URL 格式均可自定义（占位符 {%slug%}、{%id%}、{%page%}）。后台可按当前配置自动生成 Apache .htaccess 与 Nginx 规则（含 core/、config/、install/、.git/、模板 PHP 文件的访问防护），并可一键写入项目根 .htaccess。

6.4 安全规范

• 输出转义：所有输出到 HTML 的内容必须使用 Theme::e() / Security::e()；HTML 属性值使用 Theme::eAttr() / Security::eAttr()
• URL 生成：必须使用 Theme::url() / Rewrite::url() 生成 URL，不能硬编码
• CSRF 防护：所有 POST 表单必须包含 Security::csrfField()（或 $_SESSION['csrf_token']），后端使用 Security::verifyCSRFToken() 校验
• 输入过滤：Security::cleanString() 清洗字符串、Security::int() 清洗整数、Security::enum() 枚举白名单、Security::validateSlug() 校验 slug、Security::validateUrl() 校验 URL、Security::cleanHtml() 清洗富文本、Security::cleanTags() 清洗标签
• 频率限制：Security::rateLimit($key, $maxCount, $windowSeconds) 防刷接口
• Referer 校验：Security::checkReferer()（后台接口按需启用）
• SQL 注入：一律使用 PDO 预处理（Database::query() / queryOne() / execute() / insert() / scalar()），禁止拼接 SQL
• 文件安全：data/logs/、data/backups/ 等目录不可通过 Web 直接访问（后台生成的 .htaccess / Nginx 规则已默认防护 core/、templates/*.php 等）

6.5 应用中心（扩展分发）

「应用中心」是懒人导航的在线扩展分发通道：站长在后台（插件管理 → 应用中心）浏览目录， 对插件 / 主题一键安装、升级。开发者只需把符合规范的扩展文件夹上传到发布服务器 的 apps/plugins/ 或 apps/themes/ 目录即自动生效——无需维护清单、无需手动打包 ZIP。

• 站长侧：内置插件 plugins/appcenter/（启动后侧边栏出现「应用中心」入口；目录协议与安全边界见 plugins/appcenter/README.md）
• 发布侧：服务端 appcenter-server/（list.php 自动扫描 + download.php 按需打包；部署运维见 appcenter-server/README.md）
• 开发者：插件 / 主题发布规范、元数据字段、版本与升级规则、自测清单、FAQ —— 📄 完整《应用中心开发者接入指南》：data/docs/appcenter.md