refactor(agents): 删除 tools:agent:publish 命令,补全 helper.php 函数覆盖机制,修正多处文档 bug

- 删除 tools:agent:publish 整套(不再兼容多套 IDE,只保留 .agents 目录)
- helper.php 全部 27 个全局函数加 if (!function_exists()) 包裹,项目侧可在 app/common.php 定义同名函数覆盖
- ulthon-file-override-mechanism.md 新增全局函数覆盖章节
- AGENTS.md 删除智能体指导章节,PHP 8+ 改为 8.0+,MySQL 8+ 改为 5.7+
- AGENTS.md 项目结构树补全 tests/、extend/think/、source/ 子项
- README.md PHP 版本统一为 8.0+
- ulthon-base-app-architecture SKILL 路径补 admin/service/ 段
- ulthon-tools-http-call SKILL 补 --page-data 参数
- ulthon-naming-convention 补元数据头
- ulthon-update-workflow 统一 extend/think/ 归类
This commit is contained in:
augushong
2026-07-21 19:35:28 +08:00
parent 4a4155070d
commit 600ee5b085
12 changed files with 261 additions and 484 deletions

View File

@@ -81,6 +81,26 @@ Ulthon Admin 在"类继承覆盖"之外,还提供"文件级覆盖"能力:业
- 覆盖某控制器视图:在 `app/admin/view/<controller>/<action>.html` 放同名文件
- 覆盖 CURD 迁移模板:在 `app/common/command/curd/migrate.tpl` 放同名文件
## 全局函数覆盖
`extend/base/helper.php` 里的所有全局函数都有 `if (!function_exists('xxx'))` 包裹。项目侧如需覆盖某个全局函数的行为(例如修复框架 bug 或调整实现),只需在 `app/common.php``include helper.php` 语句**之前**定义同名函数即可。
加载顺序:`app/common.php` 先执行 → 项目侧函数先定义 → `include helper.php``if (!function_exists())` 检查发现已存在 → 跳过框架版本。
示例:
```php
// app/common.php
function sysconfig($group, $name = null, $default = null) {
// 项目侧自定义实现
return my_custom_logic($group, $name, $default);
}
include App::getRootPath() . '/extend/base/helper.php';
```
注意:该机制是"函数级覆盖",与本文档前述三类"文件级覆盖"是独立机制。helper.php 中已包裹的函数清单见源码(截至当前版本共 27 个:`__url``flow_url``password``xdebug``sysconfig``array_format_key``auth``get_session_admin``read_header_token``json_message``unparse_url``build_upload_url``event_handle_result``event_handle_string``event_view_content``event_view_replace``event_view_replace_js``event_response``app_file_path``array_to_table``format_bytes``parse_bytes``get_store_value``set_store_value``get_site_version_key``format_null_value``ctype_numeric`)。
## 相关文件
- `extend/base/helper.php``app_file_path()` 定义)

View File

@@ -1,5 +1,9 @@
# 命名规范
> 来源框架内置ulthon-
> 作用域:所有目录命名与 PHP 文件命名场景
> 触发条件:新增目录、新增 PHP 文件、命名疑问时加载
## 目录命名
- 一个单词的目录用小写,例如 `service/``controller/`

View File

@@ -85,8 +85,8 @@ description: "详细说明了 Base/App 双层架构的设计理念、三层结
- **类文件**:以 `*Base.php` 结尾,放在 `extend/base/`。路径和名称与 `app/` 层一一对应。
- **辅助函数**:放在 `extend/base/helper.php`,通过 `app/common.php` 引入。
- **初始化数据**:放在 `extend/base/adminInitData/`(带 @internal-framework 注解标记)。
- **版本更新代码**:放在 `extend/base/adminUpdateCodeData/`(带 @internal-framework 注解标记)。
- **初始化数据**:放在 `extend/base/admin/service/adminInitData/`(带 @internal-framework 注解标记)。
- **版本更新代码**:放在 `extend/base/admin/service/adminUpdateCodeData/`(带 @internal-framework 注解标记)。
### 4. 核心层维护原则

View File

@@ -33,6 +33,7 @@ php think tools:http:call --app=admin --controller=system.admin --action=index -
- `--body`:原始请求体字符串。
- `--headers`JSON 字符串的请求头对象(例如 `{ "Accept":"application/json" }`)。
- `--app --controller --action`:框架特性参数,用于拼控制器路径。
- `--page-data`:标志参数(无需值),等价于追加 `get_page_data=1` 参数 + `Accept:application/json` 头。用于获取页面 assign 的数据(与 [ulthon-page-api-dual-mode](../skills/ulthon-page-api-dual-mode/SKILL.md) 配套使用)。
## super token默认模拟登录

View File

@@ -127,7 +127,7 @@ php think admin:update --dry-run --optional-conflict=skip --force-conflict=overw
|------|--------|------|
| `--dry-run` | (无值) | 预览模式,只看变更不执行实际文件操作 |
| `--optional-conflict` | `skip` / `overwrite` / `ask` | 可选文件app/config/route/extend/think/根目录文件)的冲突处理策略 |
| `--force-conflict` | `overwrite` / `skip` / `ask` | 强制文件extend/base/public/database/think)的冲突处理策略 |
| `--force-conflict` | `overwrite` / `skip` / `ask` | 强制文件extend/base/public/database的冲突处理策略 |
| `--show` | `all` / `conflict` | 变更输出范围all 显示全部文件conflict 只显示冲突文件 |
| `--keep-repo` | (无值) | 预览模式下保留上游克隆目录runtime/update/current/ 和 runtime/update/repo/),便于手动对比跳过的冲突文件 |
| `--reinstall` | (无值) | 即使当前版本已是最新,也强制重新安装代码 |
@@ -187,6 +187,8 @@ php think admin:update --optional-conflict=skip --force-conflict=skip --show=all
涉及目录:`extend/base/``public/``database/`
> 注:`extend/think/` 属于可选文件,处理方式见上方「可选文件冲突」章节。
这些是框架自动管理的区域。出现冲突说明开发者违反了 Base/App 架构规则,直接修改了 `extend/base/` 下的文件。
处理建议: