feat: 发布智能体版

.agents/skills/ulthon-base-app-architecture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: "ulthon-base-app-architecture"
+description: "详细说明了 Base/App 双层架构的设计理念、三层结构、身份职责、目录映射、扩展模式及调用红线，帮助开发者理解框架结构并避免误操作。"
+---
+
+# Base/App 双层架构
+
+本架构旨在解决**框架内核升级**与**业务代码定制**之间的矛盾。为了清晰起见，请根据您的身份阅读对应部分。
+
+## 🎭 角色定位
+
+| 你的身份 | 你的主要工作 | 请关注章节 |
+| :--- | :--- | :--- |
+| **框架使用者** | 开发具体业务功能、使用框架内置能力 | 👉 [一、我是框架使用者（做业务）](#一我是框架使用者做业务) |
+| **框架作者** | 维护框架内核、修复 Bug、新增通用组件 | 👉 [二、我是框架作者（修内核）](#二我是框架作者修内核) |
+
+---
+
+## 一、我是框架使用者（做业务）
+
+### 1. 你的地盘与禁区
+- ✅ **自由开发区**：除了 `extend/base/` 之外的所有目录。虽然业务代码通常推荐放在 `app/` 下，但你完全可以在项目中自由发挥。
+- ❌ **绝对禁区**：`extend/base/` 目录。**严禁修改**这里的文件，因为 `php think admin:update` 会无情覆盖它。
+
+### 2. 开发场景指南
+
+#### 场景 A：新增全新的业务功能
+直接在 `app/` 下创建控制器、模型或服务即可。不需要关心 Base 层，也不需要继承任何 Base 类（除非你需要利用框架基类的功能）。
+
+#### 场景 B：修改/扩展框架内置功能
+如果你对框架默认的某个功能（如登录逻辑、CURD流程）不满意，请按以下步骤操作：
+
+1. **定位**：找到该功能对应的 `app/` 入口类（例如 `app/admin/model/SystemAdmin.php`）。
+2. **重写**：在该类中重写你需要修改的方法。
+   - 保持方法签名（参数、返回值）一致。
+   - 可以使用 `parent::method()` 复用父类逻辑。
+3. **生效**：系统会自动调用你的类，而不是底层的 Base 类。
+
+### 3. 更新机制与保障
+执行 `php think admin:update` 时，系统会检查框架所有文件的更新：
+- **Base 层（extend/base/）**：默认为 **覆盖更新**（Always Yes），因为这里是内核。
+- **App 层（app/）及其他**：默认为 **保护模式**（Default No）。命令会提示即将变动（新增/修改/删除）的文件列表。
+  - **推荐操作**：一般选择 **跳过**，随后根据实际业务代码与上游更新进行对比，手动合并差异。
+  - **替代操作**：也可选择 **覆盖**，更新后通过 Git 查看差异，并恢复不应变动的业务代码。
+
+---
+
+## 二、我是框架作者（修内核）
+
+### 1. 你的地盘与职责
+- ✅ **你的地盘**：`extend/base/` 目录。通用逻辑、基类代码写在这里。
+- 📝 **你的义务**：每在 Base 层新增一个类（如 `UserBase`），**必须**在 `app/` 层提供对应的入口类（如 `User`），并让入口类继承 Base 类。
+
+### 2. 开发关键原则（依赖倒置）
+
+为了保证使用者的重写能生效，你必须遵守以下**铁律**：
+
+> **❌ 严禁直接调用 Base 类**
+> 无论在何处，禁止写 `new UserBase()` 或 `UserBase::find()`。
+
+> **✅ 必须调用 App 入口类**
+> 必须写 `new \app\...\User()`。
+
+**为什么？**
+如果代码直接调用了 `UserBase`，那么使用者在 `app/` 下重写的 `User` 类就变成了“摆设”，无法拦截逻辑。只有调用 `app/` 下的子类，多态机制才能生效，使用者才有机会改变世界。
+
+### 3. 文件组织规范
+- **类文件**：以 `*Base.php` 结尾，放在 `extend/base/`。
+- **辅助函数**：放在 `extend/base/helper.php`，通过 `app/common.php` 引入。
+- **初始化数据**：放在 `extend/base/adminInitData/`。
+
+---
+
+## 三、架构参考资料
+
+### 1. 三层结构图解
+
+```
+ThinkPHP 框架层（底层基础设施）
+        ▲
+        │ 继承/扩展
+ulthon_admin 内核层（extend/base/，框架作者维护）
+        ▲
+        │ 继承/覆盖（依赖倒置：内核只调用 App 层入口）
+App 应用层（app/，框架使用者维护）
+```
+
+### 2. 常见目录映射
+
+| Base 层（内核实现） | App 层（调用入口） |
+| :--- | :--- |
+| `extend/base/admin/controller/system/AdminBase.php` | `app/admin/controller/system/Admin.php` |
+| `extend/base/admin/model/SystemAdminBase.php` | `app/admin/model/SystemAdmin.php` |
+| `extend/base/common/command/CurdBase.php` | `app/common/command/Curd.php` |
+| `extend/base/common/service/SmsBase.php` | `app/common/service/Sms.php` |