docs(agents): update-workflow旧结构迁移指引与AGENTS.md重构版本提示

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

@@ -303,28 +303,28 @@ php think admin:update --fetch-only
 
 ### 11.1 策略类型
 
-- **默认策略**：对比更新（标准 `admin:update` 流程）。无规则文件即代表默认策略，零额外负担。
+- **默认策略**：对比更新（标准 `admin:update` 流程）。项目信息节无更新策略记录即代表默认策略，无需任何操作。
 - **可选策略**：按需手动更新（`--fetch-only` + AI 手动合并）。
 
 ### 11.2 策略切换记录
 
-首次使用 `--fetch-only` 完成手动合并后，AI 应检查 `.agents/rules/project-update-strategy.md` 是否存在，不存在则提示开发者创建。
+首次使用 `--fetch-only` 完成手动合并后，AI 应检查根 `AGENTS.md`「项目信息」节是否记录了更新策略，未记录则提醒开发者补充一行说明。
 
 ### 11.3 重要声明
 
-该规则文件是**纯文档机制**，无任何代码读取或写入它。通过 AGENTS.md 规则导航（project- 前缀）被 AI 发现。
+更新策略是**纯文档机制**，记录在根 `AGENTS.md`「项目信息」节中，无任何代码读取或写入它。AI 通过阅读该节即可发现当前策略。
 
-### 11.4 规则文件格式（三字段）
+### 11.4 策略说明格式
 
-- **当前策略**：对比更新 / 按需手动更新
-- **采用原因**：切换到按需手动更新时填写
-- **注意事项**：策略层面的长期约束（定制文件、合并偏好等）
+更新策略为 AGENTS.md 项目信息节中的一行说明（当前策略/原因/注意事项，一两句话），例如：
 
-该文件创建后尽量不频繁修改，仅在策略本身发生变化时更新。
+> 当前采用按需手动更新策略，因框架经过深度定制，直接覆盖底层有风险；合并时注意保留 app/ 下的定制文件。
+
+说明写入后尽量不频繁修改，仅在策略本身发生变化时更新。
 
 ### 11.5 后续提醒
 
-AI 在涉及框架更新操作前，应先查阅该规则文件了解当前项目的更新策略。
+AI 在涉及框架更新操作前，应先查阅根 `AGENTS.md`「项目信息」节中的更新策略说明，了解当前项目的更新策略。
 
 ## 12. MCP 依赖升级提示
 
@@ -339,3 +339,25 @@ composer require mcp/sdk guzzlehttp/psr7
 - 依赖要求 PHP >= 8.1。
 - 未安装依赖时 `/mcp` 返回 503（带友好提示），不影响站点其他功能；后台 MCP 密钥管理页零 SDK 依赖，可正常使用。
 - 密钥管理、客户端配置与联调方式详见 [ulthon-mcp](../ulthon-mcp/SKILL.md) 技能。
+
+## 13. 旧结构迁移（v2.x）
+
+本版本重构了智能体文档结构，存量项目升级后按以下步骤迁移：
+
+### 13.1 AGENTS.md 结构更新
+
+升级到本版本后，下游未改过的 AGENTS.md 已自动更新为新结构（顶部「项目信息」节 + 精简的框架规则）；改过的 AGENTS.md 会保留旧版，参照上游新 AGENTS.md 手动合并。
+
+### 13.2 恢复被删除的旧文件
+
+框架已删除 `.agents/PROJECT.md` 与 3 个 project-* 模板（`project-dev-runtime-deploy.md`、`project-business-constraints.md`、`project-update-strategy.md`）。若升级时这些文件被自动删除且内容需要找回：
+
+1. 用 `git checkout -- <文件路径>` 从 git 记录恢复对应文件；
+2. 把项目概述、运行方式等已填写内容并入根 `AGENTS.md`「项目信息」节；
+3. 在「项目信息」节的规则索引中登记存量的 `.agents/rules/project-*.md`。
+
+**警示**：升级前未提交的内容无法恢复，从未纳入 git 管理的内容（如 `composer create-project` 后未 `git init`）同样无法恢复，升级前务必先提交全部改动。
+
+### 13.3 清理旧文件
+
+迁移完成后无需保留旧文件。本版本起 `.agents/rules/project-*` 为可选文件，项目自建/恢复的文件不会再被更新命令强制覆盖。