From a7a80417ef257a6c4a12c6755e894b7c1ab1ddd1 Mon Sep 17 00:00:00 2001 From: augushong Date: Sat, 8 Aug 2026 19:09:26 +0800 Subject: [PATCH] =?UTF-8?q?docs(skill):=20=E6=96=B0=E5=A2=9E=E7=BA=AF?= =?UTF-8?q?=E6=8B=89=E5=8F=96=E6=A8=A1=E5=BC=8F=E5=B7=A5=E4=BD=9C=E6=B5=81?= =?UTF-8?q?=E4=B8=8E=E6=9B=B4=E6=96=B0=E7=AD=96=E7=95=A5=E8=A7=84=E5=88=99?= =?UTF-8?q?=E6=9C=BA=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/ulthon-update-workflow/SKILL.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/.agents/skills/ulthon-update-workflow/SKILL.md b/.agents/skills/ulthon-update-workflow/SKILL.md index 2e6ea39..016cdf3 100644 --- a/.agents/skills/ulthon-update-workflow/SKILL.md +++ b/.agents/skills/ulthon-update-workflow/SKILL.md @@ -130,6 +130,7 @@ php think admin:update --dry-run --optional-conflict=skip --force-conflict=overw | `--force-conflict` | `overwrite` / `skip` / `ask` | 强制文件（extend/base/public/database）的冲突处理策略 | | `--show` | `all` / `conflict` | 变更输出范围：all 显示全部文件，conflict 只显示冲突文件 | | `--keep-repo` | (无值) | 预览模式下保留上游克隆目录（runtime/update/current/ 和 runtime/update/repo/），便于手动对比跳过的冲突文件 | +| `--fetch-only` | (无值) | 仅拉取上游代码到本地，不执行对比和更新 | | `--reinstall` | (无值) | 即使当前版本已是最新，也强制重新安装代码 | | `--update-master` | (无值) | 更新到 master 分支而非最新 tag | @@ -256,3 +257,71 @@ php think admin:version - **Docker 模式注意**：Docker 模式下所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`（判断方式见 3.1 节：仓库根目录有 `docker-compose.yaml` 或 `source/stack//` 下有编排文件即为 Docker 模式） - **更新会临时占用磁盘**：命令会在 `runtime/update/` 下克隆上游仓库进行对比，完成后自动清理 - **版本更新说明**：更新完成后，命令会输出跨版本的更新说明（来自 `adminUpdateData/tips.php`），提醒开发者关注 + +## 10. 纯拉取模式 + +适用场景： + +- AI 开发场景，让 AI 自行对比三份代码、找线索、手动合并 +- 只想要新版本的某一个新特性，其他更新收益不大但风险仍在 +- 框架经过深度定制后，直接更新底层有风险 + +命令： + +```bash +php think admin:update --fetch-only +``` + +### 10.1 三份代码说明 + +- `runtime/update/current/`：当前安装版本的上游原始代码 +- `runtime/update/repo/`：上游最新版本的代码 +- 项目根目录：开发者实际代码 + +### 10.2 AI 工作流 + +1. 执行 `php think admin:update --fetch-only` +2. AI 读取三份代码，对比差异，找线索，判断需要哪些特性 +3. 手动合并想要的文件到项目代码 +4. 完成后删除 `runtime/update/` 目录，或下次运行 admin:update 时自动清理 + +### 10.3 三种模式决策矩阵 + +| 模式 | 运行完整对比 | 冲突分类 | 风险评估 | 目录保留 | 适用场景 | +|------|-------------|---------|---------|---------|---------| +| `--dry-run` | 是 | 是 | 是 | 否 | 正常预览，需要冲突分类和风险评估 | +| `--dry-run --keep-repo` | 是 | 是 | 是 | 有条件（仅当有跳过的冲突文件） | 预览 + 保留跳过的冲突文件目录供手动对比 | +| `--fetch-only` | 否 | 否 | 否 | 无条件（总是保留） | 完全跳过对比逻辑，仅拉取代码+基础变更清单，让 AI 全手动检查 | + +> 该矩阵与 4.5 节「跳过文件处理」的 `--keep-repo` 工作流区分：`--keep-repo` 仍会运行完整对比并做冲突分类，只是在有跳过文件时额外保留目录；`--fetch-only` 则完全跳过对比逻辑。 + +### 10.4 参数互斥说明 + +`--fetch-only` 与 `--dry-run`、`--keep-repo`、`--optional-conflict`、`--force-conflict` 等同时传时，`--fetch-only` 优先，其他静默忽略（不报错）。 + +## 11. 更新策略规则机制 + +### 11.1 策略类型 + +- **默认策略**：对比更新（标准 `admin:update` 流程）。无规则文件即代表默认策略，零额外负担。 +- **可选策略**：按需手动更新（`--fetch-only` + AI 手动合并）。 + +### 11.2 策略切换记录 + +首次使用 `--fetch-only` 完成手动合并后，AI 应检查 `.agents/rules/project-update-strategy.md` 是否存在，不存在则提示开发者创建。 + +### 11.3 重要声明 + +该规则文件是**纯文档机制**，无任何代码读取或写入它。通过 AGENTS.md 规则导航（project- 前缀）被 AI 发现。 + +### 11.4 规则文件格式（三字段） + +- **当前策略**：对比更新 / 按需手动更新 +- **采用原因**：切换到按需手动更新时填写 +- **注意事项**：策略层面的长期约束（定制文件、合并偏好等） + +该文件创建后尽量不频繁修改，仅在策略本身发生变化时更新。 + +### 11.5 后续提醒 + +AI 在涉及框架更新操作前，应先查阅该规则文件了解当前项目的更新策略。