amperetechcr/liteFramework
GitHub: amperetechcr/liteFramework
一款零外部依赖、专为 AI 代理直接阅读和编写代码而设计的 PHP MVC 全栈框架，内置 ORM、RBAC、统一 API 与实时 SSE。
Stars: 0 | Forks: 0
# liteFramework
[](https://github.com/amperetechcr/liteFramework/actions/workflows/ci.yml)
[](https://php.net)
[](https://phpstan.org)
[](phpcs.xml.dist)
[](https://sentry.io)
[](LICENSE.md)
**专为 AI 设计、而非为人类操刀打造的 PHP 框架。**
人类使用 AI。AI 掌控框架。零幻觉。零冗余代码。
原生集成 OpenCode + OpenClaw。8 项 skills。6 个 MCP 服务器。458 个验证测试。
## 为什么选择 liteFramework?
| | Laravel / Symfony | liteFramework |
|---|---|---|
| **谁编写代码？** | 人类编写 → 人为错误、上下文不完整 | **AI 编写。** 人类仅负责监督和下达指令 |
| **幻觉** | 频发。AI 会凭空捏造 vendor/ 中不存在的 API | **零幻觉。** AI 会阅读框架的完整代码，并确切知道其内部结构 |
| **冗余代码** | AI 生成的代码不遵循内部规范 | **零冗余。** Skills + AGENTS.md + 自动化验证 |
| **依赖项** | 50 多个 Composer 包 — AI 无法查看其内部代码 | 零依赖。AI 能够阅读框架的每一行代码 |
| **语言** | 英文技术术语混杂在配置中 | 100% 西班牙语。语义一致 |
| **AI 学习曲线** | AI 必须依靠记忆来学习规范 | AI 通过直接阅读框架来学习 |
| **源代码** | 90% 位于 vendor/ — 不透明、不可修改 | 100% 可见、强类型、有文档、可修改 |
## 功能特性
| 领域 | 能力 |
|------|------------|
| **🤖 AI 协同** | 8 项用于 OpenClaw 的 skills（架构、测试、SEO、UI、API、性能），6 个 MCP 服务器（git、time、fetch、sentry、context7、gh_grep），框架各层均配备 AGENTS.md，代码 100% 使用西班牙语且每个方法都有明确的 type hints |
| **🔍 零依赖** | 无需 Composer，无需 npm，无需 vendor/。框架的每一行代码都是为了让 AI 能够阅读、理解和修改而编写的。没有黑盒，没有魔法 |
| **🧪 质量控制** | 458 个测试 / 1084 个断言，PHPStan level 7，PHPCS 0 错误 (PSR-12)，支持 3 个 PHP 版本的 CI (8.2, 8.3, 8.4)。AI 会验证其操作不会破坏任何功能 |
| **架构** | 带有拦截器的 MVC，Active Record ORM，支持动态参数的路由器，辅助函数，PSR-4 namespaces |
| **安全性** | 60秒宽限期的轮换 CSRF，细粒度 RBAC，防会话劫持 (指纹)，数据库级 rate limiting，WAF，双重审计 (数据库 + 文件)，自定义异常，CSP/HTTPS/HSTS |
| **数据库** | 带有 SQLite 回退机制的 MySQL，支持备份/还原的版本化迁移，query builder，兼容 MySQL/SQLite 方言 |
| **API** | 带有 15 多个控制器的单一 endpoint `POST /api`，通用 CRUD，统一契约 |
| **前端** | 15 个 CSS 样式表，包含 13 种调色板、8 种风格、16 种背景；原生 SPA；无需 bundler 的 ES modules；自适应触摸/带宽 |
| **实时 SSE** | daemon 自动启动，`Last-Event-Id`，文件内位置缓存 (`fseek`)，优化的轮询（500ms 数据库 / 1秒 文件），使用 `session_write_close()` 的会话 |
| **性能** | Apache 多线程 (XAMPP)，gzip 压缩（CSS 减少约 71%），无外部依赖，mod_deflate |
| **审计** | 50 多个包含丰富上下文的审计事件：IP、User-Agent、会话、设备数据、性能 |
## 唯一专为 AI 设计、而非为人类打造的 PHP 框架
**传统框架的问题：** 人类编写代码 → 人类犯错 → AI 因为不了解框架的内部结构而产生幻觉 → 冗余代码。
**liteFramework 的解决方案：** 人类下达指令 → AI 编写代码 → AI 100% 了解框架，因为没有隐藏的 vendor → 自动化验证 → 零幻觉，零冗余。
### 代码自带说明
框架的每一层都配备专为 AI 消费设计的文档：
| 阅读者 | 看到的内容 | 位置 |
|---|---|---|
| **OpenCode** | 实践模式：模块、路由、ORM、验证 | `.opencode/skills/lite-framework/` |
| **OpenClaw** | 8 项描述框架各层的 skills | `.agents/skills/` |
| **Context7 MCP** | 通过 context7 提供的 PHP、库和模式文档 | `~/.config/opencode/opencode.json` |
| **gh_grep MCP** | GitHub 上的真实代码示例 | `~/.config/opencode/opencode.json` |
### 工作流：人类 → AI → 框架
```
HUMANO da instrucción en lenguaje natural
│
▼
IA analiza con skill arquitectura ───────────────────────────┐
│ │
▼ │
IA escribe código (modelo, ruta, controlador, vista, JS) │
│ │
▼ │
IA ejecuta validación: PHPStan + PHPCS + PHPUnit │
│ │
▼ │
Resultado → humano verifica o itera ←───────────────────────┘
```
**人类绝不直接触碰代码。AI 负责编写，AI 负责验证，人类只负责监督。**
### 验证流水线 (OpenCode commands)
```
opencode run validate # PHPStan + PHPCS + PHPUnit — todo en 1 comando
opencode run test # Solo tests
opencode run stan # Solo PHPStan level 7
opencode run lint # Solo PSR-12
```
## 服务器架构
```
index.php
├── autoload.php (PSR-4 + class_alias)
├── GestorEntorno (.env → constantes)
├── ReporteroSentry (inicialización Sentry nativa)
├── ManejadorErrores (error/exception/fatal handler → ReporteroSentry::capturar)
├── rutas/web.php
│ └── Enrutador::despachar(GET|POST|PUT|PATCH|DELETE, /ruta)
│ ├── Interceptor (autenticación, permisos)
│ └── Controlador → Modelo → Vista/JSON
├── src/sse.php (SSE endpoint con Last-Event-Id)
└── src/error.php (códigos 400|401|403|404|500|503)
SSE Daemon (servidor/consola/sse_daemon.php):
servidor/seguridad/SseGestor.php
├── iniciarDaemon() — auto-start via exec() si no corre
├── conectar(ultimoId) — timeout 30s, acepta Last-Event-Id
├── conectarModoArchivo() — polling 1s, caché de posición con fseek
├── conectarModoDB() — polling 500ms, cleanup cada 5 ciclos
└── leerEventosDelArchivo(ultimoId, &posArchivo) — solo datos nuevos
```
### 命名空间
| Namespace | 目录 |
|-----------|-----------|
| `LiteFramework\Nucleo` | `servidor/nucleo/` |
| `LiteFramework\Seguridad` | `servidor/seguridad/` |
| `LiteFramework\Modelos` | `servidor/modelos/` |
| `LiteFramework\Controladores` | `servidor/controladores/` |
| `LiteFramework\Api\Controladores` | `servidor/api/controladores/` |
| `LiteFramework\Servicios` | `servidor/servicios/` |
| `LiteFramework\Middleware` | `servidor/middleware/` |
| `LiteFramework\Config` | `servidor/config/` |
## 环境要求
- PHP 8.2+（扩展：`pdo`、`pdo_mysql`、`pdo_sqlite`、`json`、`mbstring`、`fileinfo`，以及用于 SSE daemon 的 `exec()`）
- Apache 2.4+，需启用 `mod_rewrite`、`mod_headers`、`mod_deflate` + `mod_filter`
- MySQL 5.7+ / MariaDB 10.3+（内置 SQLite 作为回退方案）
- Windows 下推荐使用 XAMPP；Linux 下使用原生 Apache
- OpenCode + OpenClaw（可选，用于 AI 辅助开发）
## 安装说明
```
# 1. 克隆
git clone https://github.com/amperetechcr/liteFramework.git
cd liteFramework
# 2. 配置环境
cp .env.example .env
# 在 .env 中编辑 DB_NOMBRE、DB_USUARIO、DB_CLAVE 和 OAUTH_REDIRECT_BASE
# 3. 创建数据库
mysql -u root -e "CREATE DATABASE lite CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 4. 执行迁移
php servidor/migrar.php
# 5. 使用 Apache 提供服务（在 Windows 上推荐使用 XAMPP）
# SSE daemon 会在首次 SSE request 时自动启动。
# 6. 在浏览器中打开
# https://localhost/liteFramework/
```
## 快速示例
```
// rutas/web.php
$enrutador->get('/saludo/{nombre}', function(array $params) {
echo "Hola, " . h($params['nombre']);
})->nombre('saludo');
// Generar URL
$url = Enrutador::url('saludo', ['nombre' => 'Mundo']);
// → /saludo/Mundo
```
```
// modelo personalizado (generado automáticamente por GeneradorModulo)
class Producto extends Modelo {
protected static string $tabla = 'producto';
protected static array $rellenable = ['nombre', 'precio', 'stock'];
public function categoria(): callable {
return $this->perteneceA(Categoria::class, 'categoria_id');
}
}
// Uso
$productos = Producto::donde('precio', '>', 100)->ordenarPor('nombre')->obtener();
$producto = Producto::buscar(42);
$producto->precio = 99.99;
$producto->guardar();
```
## 环境变量 (`.env`)
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `APP_ENTORNO` | desarrollo | `desarrollo` 或 `produccion` |
| `APP_DEPURACION` | true | 在错误中显示追踪信息 |
| `APP_MAX_INTENTOS_ACCESO` | 5 | 锁定前的登录尝试次数 |
| `APP_BLOQUEO_MINUTOS` | 15 | 锁定持续时间（分钟） |
| `DB_ANFITRION` | localhost | MySQL 主机 |
| `DB_NOMBRE` | lite | 数据库名称 |
| `DB_USUARIO` | root | MySQL 用户名 |
| `DB_CLAVE` | (空) | MySQL 密码 |
| `SESSION_INACTIVIDAD_MAXIMA` | 1800 | 不活动超时时间（秒） |
| `SESSION_TIEMPO_MAXIMO` | 28800 | 最大会话时长 |
| `SENTRY_DSN` | (空) | 用于错误报告的 Sentry DSN（例如：`https://key@host/project`） |
| `APP_RELEASE` | (空) | 用于在 Sentry 中追踪的 release 版本（例如：`1.4.0`） |
## 安全性
- **CSRF**：64 位十六进制 token，每次请求自动轮换，为并发请求提供 60 秒宽限期
- **会话**：HttpOnly + SameSite=Lax + 指纹 SHA-256(子网 + User-Agent) — 使用 Lax 以兼容隧道（ngrok、cloudflared）
- **密码**：`password_hash(PASSWORD_DEFAULT)`，需符合包含 8 个以上字符、大写字母、数字、符号的策略
- **SQL**：100% prepared statements，针对白名单进行标识符清理
- **Headers**：CSP, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, HSTS, Referrer-Policy, Permissions-Policy
- **审计**：双重审计（数据库 `bitacora_sistema` + `storage/logs/trazabilidad.log`），每次请求具有唯一的 Trace ID
- **WAF**：自动拦截恶意工具（curl、python、wget、sqlmap、nmap、burp suite） — 将 `scan` 排除在外，以免拦截合法浏览器
- **Rate limiting**：15 分钟窗口期内，每个 IP/邮箱限制 5 次登录尝试（持久化到数据库）
- **异常**：自定义层级结构（`ErrorSeguridad`、`ErrorAutenticacion`、`ErrorValidacion`），附带 HTTP 状态码
## 实时 SSE
`sse.php` 通过持久化 daemon 暴露 Server-Sent Events 事件：
| 组件 | 特性 |
|---|---|
| `SseGestor::iniciarDaemon()` | 如果 daemon 未运行，则通过 `exec()` 自动启动 PHP daemon |
| `SseGestor::conectar($ultimoId)` | 30秒超时，接受 `HTTP_LAST_EVENT_ID` 以恢复连接 |
| `conectarModoArchivo()` | 1秒轮询，使用 `fseek` 进行位置缓存，按 ID 过滤 |
| `conectarModoDB()` | 500毫秒轮询，每 5 个周期进行一次清理 |
| `leerEventosDelArchivo()` | `fseek($posArchivo)` — 仅读取新数据 |
| 会话 | 在进入循环前执行 `session_write_close()` 以防阻塞 |
```
# daemon 自动启动。要验证：
php servidor/consola/sse_daemon.php status
```
## Sentry — 零依赖监控
**无需 SDK，无需 Composer，无需 npm。** `ReporteroSentry` 使用 `file_get_contents` + `stream_context_create` 将错误直接发送至 Sentry 的 API Store。AI 只需阅读 `ReporteroSentry.php` 的约 170 行代码，就能确切了解其工作原理。
### 工作原理
1. `ReporteroSentry::iniciar(SENTRY_DSN)` 在 `index.php` 中加载环境后执行
2. `ManejadorErrores::loggear()` 会自动调用 `ReporteroSentry::capturar()`
3. 涵盖范围：PHP 错误 (`E_USER_WARNING`)、未捕获的异常和致命错误 (`E_ERROR`)
4. 每个事件均包含：完整的 stack trace、URL、HTTP 方法、headers、环境、会话、release
### 配置
```
# .env
SENTRY_DSN=https://clave_publica@oXXXXX.ingest.us.sentry.io/XXXXX
APP_RELEASE=1.4.0
```
### 类
| 方法 | 描述 |
|--------|-------------|
| `iniciar(string $dsn)` | 使用 Sentry DSN 进行初始化 |
| `capturar(\Throwable $e, array $contexto)` | 将错误发送至 Sentry（由 ManejadorErrores 自动调用） |
| `estaActivo(): bool` | 验证 Sentry 是否已配置 |
## 使用 OpenCode + OpenClaw 进行开发
该项目配置为由 **OpenCode**（编码）和 **OpenClaw**（测试/自动化）辅助开发，并共享相同的 MCP 服务器。
### 可用的 MCP Servers
| MCP | Transport | OpenCode | OpenClaw |
|-----|-----------|----------|----------|
| `context7` | remote (streamable-http) | 全局 ✅ | 已注册 ✅ |
| `gh_grep` | remote (streamable-http) | 全局 ✅ | 已注册 ✅ |
| `git` | local (WSL + uvx) | 全局 ✅ | 已注册 ✅ |
| `time` | local (WSL + uvx) | 全局 ✅ | 已注册 ✅ |
| `fetch` | local (WSL + uvx) | 全局 ✅ | 已注册 ✅ |
| `sentry` | local (WSL + sentry-mcp) | 全局 ✅ | 已注册 ✅ |
### 快捷命令 (OpenCode)
```
opencode run validate # PHPStan + PHPCS + PHPUnit completo
opencode run test # Ejecutar todos los tests
opencode run lint # Validar PSR-12
opencode run stan # PHPStan level 7
opencode run migrar # Ejecutar migraciones
opencode run benchmark # Benchmarks de rendimiento
```
### OpenClaw Skills
| Skill | 目的 |
|-------|-----------|
| `arquitectura` | 框的完整结构 |
| `convenciones` | 命名、类型、PHP、JS、CSS、DB 规范 |
| `ui-testing` | 使用 browser tool 进行 UI 测试 |
| `api-testing` | REST API 测试 |
| `performance-testing` | 性能基准测试与内存分析 |
| `accessibility` | WCAG 2.2 审计 |
| `frontend-design` | 前端设计指南 |
| `seo` | SEO 优化 |
有关完整的工作流，请参阅 `AGENTS.md`。
## 性能与服务器
| 方面 | 详情 |
|---|---|
| **服务器** | Apache 2.4 (XAMPP) 多线程，替代了单线程的 `php -S` |
| **压缩** | 通过 `mod_deflate` + `mod_filter` 实现 gzip — CSS 8.7KB→2.5KB（减少约 71%） |
| **SSE Daemon** | 持久化的 PHP 进程，自动启动，极低消耗 |
| **数据库** | 原生 MySQL，SSE 优先使用文件而非数据库轮询 |
| **隧道** | 兼容 ngrok（header `ngrok-skip-browser-warning`）和 cloudflared |
## API
**POST /api**（`Content-Type: application/json`）
```
{
"token_peticion": "csrf-token",
"accion_crud": "iniciar_sesion",
"correo": "admin@example.com",
"clave": "MiClave123!"
}
```
**统一响应格式：**
```
{
"estado_operacion": true,
"mensaje_error": null,
"codigo_error": null,
"nuevo_token": "nuevo-csrf-token",
"datos": { ... }
}
```
有关完整的 endpoints 文档，请参阅 [`src/docs/API.md`](src/docs/API.md)。
## 测试
```
# 运行所有测试
php tests/phpunit.phar -c tests/phpunit.xml
# 或通过框架的 CLI
php servidor/consola/ejecutar_pruebas.php
# 外部 HTTP 测试 (httpbin.org)
$env:TESTS_EXTERNAS_HTTP='true'; php tests/phpunit.phar -c tests/phpunit.xml --filter AyudanteHttp
# 结果：458 个测试，1084 个断言，SQLite in-memory
```
测试套件使用内存中的 SQLite（通过 `TESTS_RUNNING` 实现），无需使用 MySQL。
复用了框架自身的 autoloader、辅助函数以及 `ConexionBaseDatos::resetearInstancia()`。
## 截图
*(在此处添加管理面板、登录、模块生成器等的截图)*
## 常用命令
```
php servidor/migrar.php # Ejecutar migraciones
php servidor/migrar.php list # Listar migraciones pendientes
php servidor/consola/generar_modulo.php # Generar módulo CRUD vía CLI
php servidor/consola/crear_proyecto.php # Generar proyecto completo vía CLI
php servidor/consola/ejecutar_pruebas.php # Ejecutar tests
php tests/phpunit.phar -c tests/phpunit.xml # Ejecutar tests (directo)
php servidor/consola/sse_daemon.php status # Verificar estado del daemon SSE
# PHPStan
php phpstan.phar analyse
# PHPCS
php phpcs.phar --standard=phpcs.xml.dist
# 完整验证
php phpstan.phar analyse && php phpcs.phar --standard=phpcs.xml.dist && php tests/phpunit.phar -c tests/phpunit.xml
```
## 许可证
Apache 2.0 — 详见 [LICENSE.md](LICENSE.md)。
标签：AI辅助编程, ffuf, MVC架构, ORM, PHP框架, RBAC权限控制, Syscall, Web开发