From 20d0b5f22b56c489b471b7d958dc695b5ddc4de1 Mon Sep 17 00:00:00 2001
From: augushong <augushong@163.com>
Date: Mon, 25 May 2026 22:51:17 +0800
Subject: [PATCH] =?UTF-8?q?docs(skills):=20=E6=96=B0=E5=A2=9E=20ulthon-upd?=
 =?UTF-8?q?ate-workflow=20AI=20=E6=8A=80=E8=83=BD=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../skills/ulthon-update-workflow/SKILL.md    | 231 ++++++++++++++++++
 1 file changed, 231 insertions(+)
 create mode 100644 .agents/skills/ulthon-update-workflow/SKILL.md

diff --git a/.agents/skills/ulthon-update-workflow/SKILL.md b/.agents/skills/ulthon-update-workflow/SKILL.md
new file mode 100644
index 0000000..140dcab
--- /dev/null
+++ b/.agents/skills/ulthon-update-workflow/SKILL.md
@@ -0,0 +1,231 @@
+---
+name: "ulthon-update-workflow"
+description: "指导 AI agent 协助开发者使用 php think admin:update 同步上游框架代码，含预览评估、冲突策略选择与更新后操作。"
+---
+
+# admin:update（框架更新工作流）
+
+## 1. 概述
+
+本技能指导 AI agent 协助开发者执行 `php think admin:update`，将上游框架代码同步到本地项目。
+
+核心原则：**开发者当前代码状态为主，上游更新为参考**。更新命令不会盲目覆盖，而是根据文件类型和定制状态分类处理。agent 的职责是帮助开发者评估风险、选择合适的冲突策略，并在更新后执行必要的收尾操作。
+
+## 2. 触发场景
+
+- 开发者主动要求"更新框架"、"同步上游"、"php think admin:update"
+- 开发者询问"怎么更新"、"新版本有什么变化"
+- 开发者提到版本号与上游不一致，需要拉取最新框架代码
+
+**不主动触发**：除非开发者明确表达版本相关的诉求，否则 agent 不应主动建议执行更新。
+
+## 3. 更新前检查
+
+执行更新前，必须依次确认以下事项：
+
+### 3.1 确认执行模式
+
+```bash
+php think admin:stack:mode current
+```
+
+- 如果返回 `docker-dev`，后续所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`
+- 其他模式（default/full/base-build）直接执行 `php think`，不做转换
+
+### 3.2 确认代码已提交
+
+```bash
+git status --short
+```
+
+- 输出为空：可以继续
+- 有未提交改动：**必须提醒开发者先提交或暂存**。更新会修改文件，未提交的改动可能丢失或产生冲突
+
+### 3.3 确认当前版本
+
+```bash
+php think admin:version
+```
+
+- 记录当前版本号，用于更新后对比
+
+## 4. 评估阶段（推荐先 dry-run）
+
+**每次更新前都应先执行 dry-run**，不要跳过这一步。
+
+```bash
+php think admin:update --dry-run
+```
+
+命令会拉取上游仓库，对比文件差异，输出变更预览。重点关注以下信息：
+
+### 4.1 风险评估行
+
+输出末尾会有一行风险评估：
+
+```
+风险评估: 强制冲突 X个(高风险) | 可选冲突 X个(中风险) | 无冲突变更 X个(低风险)
+```
+
+| 风险等级 | 含义 | 建议操作 |
+|----------|------|----------|
+| 强制冲突（高风险） | 开发者修改了 `extend/base/` 等强制跟踪目录的文件 | 建议覆盖，通过 App 层扩展机制重新实现定制 |
+| 可选冲突（中风险） | 开发者修改了 `app/`/`config/` 等可选目录的文件 | 默认跳过，手动按需合并 |
+| 无冲突变更（低风险） | 文件未被定制，可以直接更新 | 直接处理 |
+
+### 4.2 目录分组
+
+当变更文件超过 5 个时，输出会按目录分组显示：
+
+```
+  [extend/base/]
+    [update] extend/base/admin/service/AdminUpdateServiceBase.php
+  [app/]
+    [add][conflict:optional:overwrite] app/admin/controller/NewFeature.php
+```
+
+### 4.3 冲突标注
+
+冲突文件会带有策略标签：
+
+- `[conflict:optional:overwrite]` 或 `[conflict:optional:skip]`：可选文件冲突
+- `[conflict:force:overwrite]` 或 `[conflict:force:skip]`：强制文件冲突
+- `[skipped]`：因冲突策略被跳过的文件
+
+### 4.4 Composer 依赖变更
+
+输出中包含 `Composer 依赖变更` 段落，列出新增、删除和版本变更的依赖包。
+
+向开发者报告以上信息，由开发者决定是否继续。
+
+## 5. 参数参考
+
+| 参数 | 可选值 | 说明 |
+|------|--------|------|
+| `--dry-run` | (无值) | 预览模式，只看变更不执行实际文件操作 |
+| `--optional-conflict` | `skip` / `overwrite` / `ask` | 可选文件（app/config/route/extend/think/根目录文件）的冲突处理策略 |
+| `--force-conflict` | `overwrite` / `skip` / `ask` | 强制文件（extend/base/public/database/think）的冲突处理策略 |
+| `--show` | `all` / `conflict` | 变更输出范围：all 显示全部文件，conflict 只显示冲突文件 |
+| `--reinstall` | (无值) | 即使当前版本已是最新，也强制重新安装代码 |
+| `--update-master` | (无值) | 更新到 master 分支而非最新 tag |
+
+## 6. 执行更新
+
+根据 dry-run 的评估结果和开发者意愿，选择对应的执行命令。
+
+### 6.1 推荐默认方案
+
+适用于大多数场景，低风险直接处理，可选冲突跳过，强制冲突覆盖：
+
+```bash
+php think admin:update --optional-conflict=skip --force-conflict=overwrite --show=all
+```
+
+### 6.2 开发者想要合并上游可选改动
+
+当开发者明确希望将上游对 app/config 等目录的改动也同步过来时：
+
+```bash
+php think admin:update --optional-conflict=overwrite --force-conflict=overwrite --show=all
+```
+
+### 6.3 开发者不想覆盖任何冲突
+
+当开发者希望所有冲突文件都跳过，只更新无冲突部分：
+
+```bash
+php think admin:update --optional-conflict=skip --force-conflict=skip --show=all
+```
+
+**注意**：强制冲突跳过可能导致框架功能异常，agent 应明确警告。
+
+### 6.4 禁止事项
+
+- **永远不要使用 `ask` 模式**。agent 无法处理交互式确认提示（`$output->confirm()`），会导致命令挂起
+- **不要省略冲突策略参数**。不传参数时，如果存在冲突文件，命令会回退到交互模式，同样会挂起
+
+## 7. 冲突处理指引
+
+### 7.1 可选文件冲突
+
+涉及目录：`app/`、`config/`、`route/`、`extend/think/`、`source/docker/`、根目录文件（如 `.php-cs-fixer.php`）
+
+这些是开发者可以自由修改的区域。出现冲突说明开发者定制了这些文件，且上游也修改了同一文件。
+
+处理建议：
+
+- **默认跳过**（`--optional-conflict=skip`）：保留开发者的定制，不引入上游改动
+- 如果开发者需要上游的某个改动，在 dry-run 输出中找到具体文件路径，建议开发者手动查看 diff 并选择性合并
+- **不建议直接 overwrite**：会覆盖开发者的所有定制，且无法自动合并
+
+### 7.2 强制文件冲突
+
+涉及目录：`extend/base/`、`public/`、`database/`
+
+这些是框架自动管理的区域。出现冲突说明开发者违反了 Base/App 架构规则，直接修改了 `extend/base/` 下的文件。
+
+处理建议：
+
+- **默认覆盖**（`--force-conflict=overwrite`）：让框架恢复到标准状态
+- 覆盖后，提醒开发者通过 App 层扩展机制重新实现之前的定制逻辑（参考 `ulthon-base-app-architecture` 技能）
+- 如果开发者坚持不覆盖（`--force-conflict=skip`），**必须警告**：跳过强制文件更新可能导致框架功能异常、兼容性问题
+
+## 8. 更新后操作
+
+更新命令执行完成后，输出中会包含"建议执行以下后续操作"段落。根据提示，按需执行：
+
+### 8.1 Composer 依赖变更
+
+如果输出中出现 `composer.json 已变更，请更新依赖`：
+
+```bash
+composer install
+```
+
+**需开发者确认后才执行**，不要自动运行。
+
+### 8.2 数据库迁移
+
+如果输出中出现 `数据库迁移文件已变更，请执行迁移`：
+
+```bash
+php think migrate:run
+```
+
+**需开发者确认后才执行**。迁移可能影响生产数据，务必谨慎。
+
+### 8.3 缓存清理
+
+如果输出中出现 `框架核心或配置已变更，请清理缓存`：
+
+```bash
+php think clear
+```
+
+这一步通常可以直接执行，风险较低。
+
+### 8.4 确认版本号
+
+```bash
+php think admin:version
+```
+
+确认版本号已更新为预期版本。
+
+### 8.5 建议开发者测试
+
+提醒开发者验证关键业务功能是否正常，特别是：
+- 后台登录
+- 菜单与权限
+- 核心 CURD 页面
+- 定时任务（如有）
+
+## 9. 注意事项
+
+- **禁止使用 `ask` 模式**：agent 无法处理交互式提示，必须通过参数明确指定冲突策略
+- **更新前务必确保代码已提交**：未提交的改动可能在更新过程中丢失
+- **不自动执行 composer 或数据库操作**：这些操作影响面大，需开发者确认
+- **大版本跳跃风险更高**：跨越多个 tag 时变更量大，建议格外谨慎，仔细审查 dry-run 输出
+- **Docker 模式注意**：如果是 `docker-dev` 模式，所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`
+- **更新会临时占用磁盘**：命令会在 `runtime/update/` 下克隆上游仓库进行对比，完成后自动清理
+- **版本更新说明**：更新完成后，命令会输出跨版本的更新说明（来自 `adminUpdateData/tips.php`），提醒开发者关注