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

name, description

name	description
ulthon-update-workflow	指导 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 确认执行模式

php think admin:stack:mode current

• 如果返回 docker-dev，后续所有 php think 命令前缀改为 docker compose exec ulthon_admin
• 其他模式（default/full/base-build）直接执行 php think，不做转换

3.2 确认代码已提交

git status --short

• 输出为空：可以继续
• 有未提交改动：必须提醒开发者先提交或暂存。更新会修改文件，未提交的改动可能丢失或产生冲突

3.3 确认当前版本

php think admin:version

• 记录当前版本号，用于更新后对比

4. 评估阶段（推荐先 dry-run）

每次更新前都应先执行 dry-run，不要跳过这一步。

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，保留上游克隆目录用于对比：

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 推荐默认方案

适用于大多数场景，低风险直接处理，可选冲突跳过，强制冲突覆盖：

php think admin:update --optional-conflict=skip --force-conflict=overwrite --show=all

6.2 开发者想要合并上游可选改动

当开发者明确希望将上游对 app/config 等目录的改动也同步过来时：

php think admin:update --optional-conflict=overwrite --force-conflict=overwrite --show=all

6.3 开发者不想覆盖任何冲突

当开发者希望所有冲突文件都跳过，只更新无冲突部分：

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 已变更，请更新依赖：

composer install

需开发者确认后才执行，不要自动运行。

8.2 数据库迁移

如果输出中出现 数据库迁移文件已变更，请执行迁移：

php think migrate:run

需开发者确认后才执行。迁移可能影响生产数据，务必谨慎。

8.3 缓存清理

如果输出中出现 框架核心或配置已变更，请清理缓存：

php think clear

这一步通常可以直接执行，风险较低。

8.4 确认版本号

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