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/` 下的文件。
处理建议: