From ed8ad51c0db87d943dac14bff14ef0fec9eaf9ed Mon Sep 17 00:00:00 2001 From: augushong Date: Mon, 7 Sep 2026 23:57:56 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20update-workflow=E6=97=A7?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E8=BF=81=E7=A7=BB=E6=8C=87=E5=BC=95=E4=B8=8E?= =?UTF-8?q?AGENTS.md=E9=87=8D=E6=9E=84=E7=89=88=E6=9C=AC=E6=8F=90=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../skills/ulthon-update-workflow/SKILL.md | 40 ++++++++++++++----- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/.agents/skills/ulthon-update-workflow/SKILL.md b/.agents/skills/ulthon-update-workflow/SKILL.md index b097763..f24e42d 100644 --- a/.agents/skills/ulthon-update-workflow/SKILL.md +++ b/.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-*` 为可选文件，项目自建/恢复的文件不会再被更新命令强制覆盖。