ulthon_admin/.agents/skills/ulthon-update-workflow/SKILL.md

---
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 依赖变更` 段落，列出新增、删除和版本变更的依赖包。

向开发者报告以上信息，由开发者决定是否继续。

### 4.5 跳过文件处理

当 dry-run 输出中存在 `[skipped]` 标记的文件时，说明这些冲突文件被跳过了。此时建议重新执行 dry-run 并加 `--keep-repo`，保留上游克隆目录用于对比：

```bash
php think admin:update --dry-run --optional-conflict=skip --force-conflict=overwrite --keep-repo
```

命令结束后，以下目录会被保留：

| 目录 | 内容 |
|------|------|
| `runtime/update/current/` | 当前安装版本的原始代码 |
| `runtime/update/repo/` | 上游最新版本的代码 |
| 项目根目录 | 开发者实际修改的代码 |

**对比方式**：逐个读取三个版本的跳过文件，辅助开发者判断是否需要合入上游改动。关注点：
- 上游改了什么（对比 `current/` vs `repo/`）
- 开发者改了什么（对比 `current/` vs 项目根目录）
- 两者是否冲突

**清理方式**：下次运行 `admin:update` 时会自动清理 `runtime/update/` 目录，或手动删除。

## 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 只显示冲突文件 |
| `--keep-repo` | (无值) | 预览模式下保留上游克隆目录（runtime/update/current/ 和 runtime/update/repo/），便于手动对比跳过的冲突文件 |
| `--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()`），会导致命令挂起
- **不要省略冲突策略参数**。不传参数时，如果存在冲突文件，命令会回退到交互模式，同样会挂起
- **`--keep-repo` 仅在预览模式下有效**：正式执行时自动忽略，不会保留目录

## 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`），提醒开发者关注