CONTEXT
<![CDATA[# Xiuno 生态系统上下文规范 (v1.0)
**目标**：为 AI 助手提供精准的上下文框架，确保其生成的代码符合 Xiuno BBS 的架构哲学、安全规范与生态约定。
**适用范围**：所有基于 Xiuno 4.x 的插件开发、主题定制、系统改造及解决方案部署。
---
## 一、核心概念
### 1. Hook（钩子）—— **基于模板注释的面向切面编程（AOP）机制**
- **定义**：
Xiuno BBS 在其 `.htm` 模板文件中预置了形如 `<!--{hook 文件名.htm}-->` 的**占位注释**。
这不是 WordPress 式的函数回调，而是一种**声明式的、基于文件系统的 AOP 实现**。
- **工作原理**：
1. 当系统渲染某个页面（如首页 `index.htm`）时，会扫描该模板中的所有 `<!--{hook ...}-->` 注释。
2. 对于每个注释（例如 `<!--{hook index_site_brief_before.htm}-->`），系统会遍历**所有已启用插件**的 `./plugin/{PLUGIN_ID}/hook/` 目录。
3. 如果发现同名文件（如 `index_site_brief_before.htm`），则将其**内容原样插入**到该注释位置。
4. 多个插件提供同一 Hook 文件时，按插件 ID 字母序合并。
- **关键特性**：
- **无侵入**：无需修改核心模板文件。
- **上下文继承**：Hook 文件可直接使用当前模板的所有变量（如 `$user`, `$conf`）。
- **静态即动态**：看似是静态文件包含，实则在运行时动态聚合，构成完整的页面逻辑流。
- **开发规范**：
- 插件若需向某处注入内容，只需在自身 `hook/` 目录下创建**与模板中注释完全同名**的 `.htm` 文件。
- 文件内容应为**合法的 HTML/PHP 片段**，不可包含 `<html>` 或 `<body>` 等根标签。
- 示例：
```php
<!-- plugin/my_page_learn/hook/index_site_brief_before.htm -->
<div class="my-banner">欢迎来到我的页面！</div>
<?php if ($user['uid']) { ?>
<script>console.log('用户已登录');</script>
<?php } ?>
```
- **与 WordPress Hook 的本质区别**：
| 维度 | WordPress Hook | Xiuno Hook |
|------|----------------|------------|
| 范式 | 事件驱动（add_action/do_action） | 模板驱动（注释占位 + 文件扫描） |
| 执行时机 | PHP 函数调用时 | 模板渲染时 |
| 扩展方式 | 注册回调函数 | 提供同名 .htm 文件 |
| 耦合性 | 松耦合（通过字符串标识） | 紧耦合（依赖模板注释存在） |
### 2. Overwrite（覆盖）
- **定义**：通过 `_include()` 函数实现模板/逻辑文件的无侵入式替换。
- **机制**：
- 系统优先加载 `view/overwrite/{path}` 下的文件。
- 若不存在，则回退到 `view/{path}`。
- **用途**：定制主题 UI、修改核心页面逻辑而不改动原文件。
### 3. Route（路由）
- **定义**：将 URL 映射到控制器逻辑。
- **实现方式**：
- 插件需在根目录提供 `{route_name}_route_case_end.php`。
- 内容为 `case '{route}': include _include('plugin_route_{plugin_name}'); break;`。
- **URL 生成**：始终使用 `url('{route}')` 函数，自动适配伪静态开关。
---
## 二、关键函数
| 函数 | 用途 | 安全规范 |
|------|------|----------|
| `param($key, $default = '', $trim = TRUE)` | 安全获取用户输入（GET/POST） | ✅ 必须使用，禁止直接读 `$_GET/$_POST` |
| `url($route, $args = array())` | 生成标准 URL | ✅ 自动处理伪静态，避免硬编码路径 |
| `setting_get($k)` / `setting_set($k, $v)` | 读写全局配置（存于 `kv` 表） | ⚠️ 敏感字段（如密码）禁止存储 |
| `kv_get($k)` / `kv_set($k, $v)` | 通用键值存储 | 同上 |
| `_include($file)` | 安全包含文件（支持 overwrite） | ✅ 必须使用，禁止 `include`/`require` |
| `message($text, $jump = '')` | 输出提示信息并跳转 | 标准化用户反馈 |
---
## 三、全局变量（只读！）
> **重要**：这些变量由系统初始化，插件中禁止修改其结构。
| 变量 | 内容 | 敏感字段（必须过滤） |
|------|------|------------------|
| `$user` | 当前用户信息 | `password`, `salt`, `email`（若非必要） |
| `$conf` | 系统配置（来自 `conf.php`） | `db_password`, `auth_key` |
| `$header` | 页面头部元数据 | 无 |
| `$forum` | 当前板块信息 | 无 |
| `$thread` | 当前主题信息 | 无 |
**安全输出示例**：
```php
// 错误 ❌
echo $_GET['title'];
// 正确 ✅
$title = param('title');
echo xn_html_safe($title); // 或 strip_tags($title)
```
---
## 四、安全规范
### 1. XSS 防护
- 所有用户输入输出前必须过滤：
- 使用 `xn_html_safe()`（推荐）或 `strip_tags()`。
- 禁止直接 `echo` 未经处理的 `param()` 结果。
### 2. 敏感字段处理
- 从数据库读取 `$user` 后，立即 unset 敏感字段：
```php
unset($user['password'], $user['salt']);
```
- 配置项中禁止存储密码、密钥等。
### 3. SQL 安全
- 使用 Xiuno 内置 DB 函数（`db_find`, `db_update`），已自动转义。
- 禁止拼接 SQL 字符串。
---
## 五、目录与命名约定
### 1. 插件命名
- **格式**：`{my_func}_{plugin_name}`
- `my_func`：功能类别（如 `abs` = 主题, `tool` = 工具, `mod` = 模块）
- `plugin_name`：具体名称（小写+下划线）
- **示例**：
- `abs_theme_stately`（Stately 主题）
- `tool_exporter`（导出器工具）
### 2. 插件目录结构
```
my_func_plugin_name/
├── conf.json # 插件元数据（非配置！）
├── hook/ # Hook 文件（可选）
├── route/ # 路由控制器（可选）
├── view/ # 模板文件（可选）
├── model/ # 数据模型（可选）
├── install.php # 安装脚本
└── uninstall.php # 卸载脚本
```
### 3. 关键文件说明
- **`conf.json`**：
- 是**元数据描述文件**，不是运行时配置。
- 必须包含 `name`, `version`, `description`。
- **`install.php`**：
- 初始化默认设置：`setting_set('my_plugin_setting', array(...));`
- 创建数据库表（如有）。
- **`uninstall.php`**：
- 清理设置：`setting_delete('my_plugin_setting');`
- 删除数据库表。
---
## 六、AI 生成代码强制约束
当为 Xiuno 生成代码时，必须遵守：
1. **绝不**直接使用 `$_GET`/`$_POST`，必须用 `param()`。
2. **绝不**硬编码 URL，必须用 `url()`。
3. **绝不**修改 `$user`/`$conf` 等全局变量结构。
4. **绝不**在输出中遗漏 XSS 过滤。
5. **必须**遵循插件命名与目录规范。
6. **必须**在 `conf.json` 中声明插件元数据。
> **记住**：你的目标不是“让代码跑起来”，而是“让代码在三年后依然可维护、可溯源、可交付”。
]]>