flower-trellis 0.4.5-beta.3 → 0.4.6

package/enhancements/0.6/overrides/workflow.md

@@ -42,6 +42,12 @@ Before Phase 1.4 `task.py start`, use `trellis-task-brief` to refresh `<task>/br
 
 Before the first implement route, restate existing `<task>/brief.md` in chat. If missing, read task artifacts and suggest backfilling brief; do not invent one from memory.
 
+#### Flower Update Confirmation
+
+If `<flower-update>` has `priority: blocking_confirmation_required`, handle it first: briefly show `release_notes` when present, show `recommended_command`, and ask before running it.
+
+If `<flower-update-result>` requests `run_trellis_push_confirmation`, enter `trellis-push` planning with update changes as default candidates; still require file-list and commit-message confirmation.
+
 #### Active Task Scope Guard
 
 When a session already has an active task, do not treat unrelated new implementation

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-07T09:44:07.804Z",
+  "syncedAt": "2026-07-07T12:53:36.169Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "5fdebe60e923c91ba912461b99413b5c8e11a38c",
+  "sourceCommit": "363dd9b54506b6cc67415e2bf76a856b743b7534",
   "common": {
     "codexSkills": [
       "craft-rpa",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.4.5-beta.3",
+  "version": "0.4.6",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -32,6 +32,11 @@
     "release": "node scripts/check-snapshot.mjs && commit-and-tag-version",
     "release:dry": "commit-and-tag-version --dry-run"
   },
+  "commit-and-tag-version": {
+    "scripts": {
+      "postchangelog": "node scripts/write-release-notes-metadata.mjs"
+    }
+  },
   "keywords": [
     "trellis",
     "skill-garden",
@@ -51,5 +56,11 @@
   "license": "MIT",
   "devDependencies": {
     "commit-and-tag-version": "^12.7.3"
+  },
+  "flowerReleaseNotes": {
+    "version": "0.4.6",
+    "source": "CHANGELOG.md",
+    "body": "### ✨ 新功能 Features\n\n* **update:** 注入跨版本更新摘要并联动 push 确认 ([bbdb23c](https://github.com/SilentFlower/flower-trellis/commit/bbdb23c33eac9948235c65f6be6f18764f90a88d))",
+    "truncated": false
   }
 }

package/src/assets/flower_update_hook.py

@@ -75,6 +75,55 @@ def _run_self_check(project_dir: Path) -> dict | None:
     return data if isinstance(data, dict) else None
 
 
+def _json_bool(value: object) -> str:
+    """把布尔值格式化成 JSON 风格小写文本。"""
+    return json.dumps(bool(value), ensure_ascii=False)
+
+
+def _release_notes_lines(data: dict) -> list[str]:
+    """把 self-check 的 releaseNotes 摘要格式化为短字段。"""
+    notes = data.get("releaseNotes")
+    if not isinstance(notes, dict):
+        return []
+    versions = notes.get("versions") or []
+    if not isinstance(versions, list):
+        versions = []
+    safe_versions = []
+    for entry in versions:
+        if not isinstance(entry, dict):
+            continue
+        version = entry.get("version")
+        body = entry.get("body")
+        if isinstance(version, str) and isinstance(body, str) and body.strip():
+            safe_versions.append(
+                {
+                    "version": version,
+                    "body": body,
+                    "truncated": bool(entry.get("truncated")),
+                }
+            )
+
+    lines: list[str] = []
+    note_range = notes.get("range") or {}
+    if isinstance(note_range, dict) and (note_range.get("from") or note_range.get("to")):
+        range_text = f"{note_range.get('from')} -> {note_range.get('to')}"
+        if note_range.get("channel"):
+            range_text += f" ({note_range.get('channel')})"
+        if note_range.get("reason"):
+            range_text += f" reason={note_range.get('reason')}"
+        lines.append(f"release_notes_range: {range_text}")
+    if safe_versions:
+        lines.append(
+            "release_notes: "
+            + json.dumps(safe_versions, ensure_ascii=False, separators=(",", ":"))
+        )
+    elif notes.get("unavailable"):
+        lines.append("release_notes_unavailable: true")
+    lines.append(f"release_notes_truncated: {_json_bool(notes.get('truncated'))}")
+    lines.append(f"release_notes_more_versions: {_json_bool(notes.get('moreVersions'))}")
+    return lines
+
+
 def _format_context(data: dict) -> str:
     """把 self-check JSON 转成给 AI 读取的短上下文块。"""
     current = data.get("current") or {}
@@ -102,6 +151,7 @@ def _format_context(data: dict) -> str:
         lines.append(f"remote: {json.dumps(remote.get('tags'), ensure_ascii=False)}")
     if remote.get("errorCode"):
         lines.append(f"remote_error_code: {remote.get('errorCode')}")
+    lines.extend(_release_notes_lines(data))
     command = (data.get("commands") or {}).get("recommended") or ai.get("command")
     if command:
         lines.append(f"recommended_command: {command}")
@@ -110,7 +160,9 @@ def _format_context(data: dict) -> str:
     if ai.get("mode"):
         lines.append(f"ai_mode: {ai.get('mode')}")
     if ai.get("mode") == "ask":
-        lines.append("ai_required_action: 必须先向用户提出明确确认问题;用户确认前禁止执行 recommended_command。")
+        lines.append(
+            "ai_required_action: 必须先向用户展示 release_notes 摘要和 recommended_command,再提出明确确认问题;用户确认前禁止执行 recommended_command。"
+        )
     if ai.get("instruction"):
         lines.append(f"ai_instruction: {ai.get('instruction')}")
     lines.append("</flower-update>")
@@ -121,7 +173,11 @@ def _system_message(data: dict) -> str:
     """生成 Codex / Claude Code 更容易注意到的短系统提示。"""
     ai = data.get("ai") or {}
     command = (data.get("commands") or {}).get("recommended") or ai.get("command")
+    notes = data.get("releaseNotes") or {}
+    has_notes = isinstance(notes, dict) and bool(notes.get("versions"))
     if ai.get("mode") == "ask" and command:
+        if has_notes:
+            return "flower-trellis 发现可执行更新;必须先展示更新摘要并询问用户是否执行 recommended_command,确认前禁止运行。"
         return "flower-trellis 发现可执行更新;必须先询问用户是否执行 recommended_command,确认前禁止运行。"
     if command:
         return "flower-trellis 发现可执行更新;已注入 recommended_command。"

package/src/commands/self-update.js

@@ -24,6 +24,80 @@ function runCommand(command, args, cwd, failureMessage) {
   }
 }
 
+/** 读取目标 git 工作区变动数量,只作为 self-update 后续动作提示。 */
+function gitDirtySummary(target) {
+  const common = {
+    cwd: target,
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 1500,
+  };
+  const root = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], common);
+  if (root.error || root.status !== 0 || String(root.stdout || "").trim() !== "true") {
+    return {
+      checked: false,
+      reason: "not_git_repo",
+      dirtyCount: 0,
+      changedFilesDetected: false,
+      files: [],
+    };
+  }
+  const status = spawnSync("git", ["status", "--porcelain"], common);
+  if (status.error || status.status !== 0) {
+    return {
+      checked: false,
+      reason: "git_status_failed",
+      dirtyCount: 0,
+      changedFilesDetected: false,
+      files: [],
+    };
+  }
+  const files = String(status.stdout || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return {
+    checked: true,
+    reason: null,
+    dirtyCount: files.length,
+    changedFilesDetected: files.length > 0,
+    files: files.slice(0, 20),
+  };
+}
+
+/** 打印 release notes 预览行。 */
+function printReleaseNotesPreview(releaseNotes) {
+  if (!releaseNotes) return;
+  const versions = Array.isArray(releaseNotes.versions) ? releaseNotes.versions : [];
+  if (!versions.length) {
+    if (releaseNotes.unavailable) console.log("  · 更新内容:未获取到可用 release notes");
+    return;
+  }
+  console.log("  · 更新内容:");
+  for (const entry of versions) {
+    const suffix = entry.truncated ? " (已截断)" : "";
+    console.log(`    - ${entry.version}${suffix}:${entry.body}`);
+  }
+  if (releaseNotes.moreVersions) {
+    console.log("    - 还有更多版本变更未展示");
+  }
+}
+
+/** 打印结构化 self-update 结果块。 */
+function printFlowerUpdateResult(fields) {
+  console.log("<flower-update-result>");
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined) continue;
+    if (typeof value === "object" && value !== null) {
+      console.log(`${key}: ${JSON.stringify(value)}`);
+    } else {
+      console.log(`${key}: ${value}`);
+    }
+  }
+  console.log("</flower-update-result>");
+}
+
 /**
  * flower-trellis self-update:执行受控自更新与项目重叠加。
  *
@@ -73,7 +147,16 @@ export async function selfUpdate(ctx) {
     console.log(
       `  · 安全检查:${effectiveSafety.safe ? "通过" : `需确认(${effectiveSafety.reasons.join(", ") || "无可用结果"})`}`,
     );
+    printReleaseNotesPreview(check.releaseNotes);
     console.log(`  · 写入:否`);
+    printFlowerUpdateResult({
+      status: "dry_run",
+      target: ctx.target,
+      write: false,
+      current_status: check.status,
+      post_action_preview: "run_trellis_push_after_real_update",
+      release_notes: check.releaseNotes || null,
+    });
     return;
   }
 
@@ -104,5 +187,19 @@ export async function selfUpdate(ctx) {
     "目标项目重叠加失败,请手动运行:" + projectUpdateCommand(ctx.target, forwarded),
   );
 
+  const dirty = gitDirtySummary(ctx.target);
   console.log(`\n🌸 flower-trellis self-update 完成 → ${ctx.target}`);
+  printFlowerUpdateResult({
+    status: "completed",
+    target: ctx.target,
+    write: true,
+    git_dirty_count: dirty.dirtyCount,
+    changed_files_detected: dirty.changedFilesDetected,
+    changed_files_sample: dirty.files,
+    git_check_reason: dirty.reason,
+    post_action: "run_trellis_push_confirmation",
+    release_notes: check.releaseNotes || null,
+    ai_instruction:
+      "汇总本次升级产生的文件变动,进入 trellis-push 执行计划,展示具体文件列表和 commit message 后等待用户确认。",
+  });
 }

package/src/lib/manifest.js

@@ -18,10 +18,61 @@ const DEFAULT_UPDATE_CHECK = {
   intervalHours: 8,
   lastCheckedAt: null,
   lastRemote: null,
+  lastReleaseNotes: null,
   lastStatus: null,
   lastErrorCode: null,
 };
 
+/**
+ * 归一化 release notes 范围字段。
+ *
+ * @param {object|null|undefined} value 原始 range 字段
+ * @returns {{from:string|null,to:string|null,channel:string|null,reason:string|null}} 归一化 range
+ */
+function normalizeReleaseNotesRange(value) {
+  const raw = value && typeof value === "object" ? value : {};
+  return {
+    from: typeof raw.from === "string" ? raw.from : null,
+    to: typeof raw.to === "string" ? raw.to : null,
+    channel: typeof raw.channel === "string" ? raw.channel : null,
+    reason: typeof raw.reason === "string" ? raw.reason : null,
+  };
+}
+
+/**
+ * 归一化最近一次可用 release notes 摘要。
+ *
+ * @param {object|null|undefined} value 原始 lastReleaseNotes 字段
+ * @returns {{source:string,range:object,versions:Array<{version:string,body:string,truncated:boolean}>,truncated:boolean,moreVersions:boolean,unavailable:boolean}|null} 归一化摘要
+ */
+function normalizeLastReleaseNotes(value) {
+  if (!value || typeof value !== "object") return null;
+  const versions = Array.isArray(value.versions)
+    ? value.versions
+        .map((entry) => {
+          if (!entry || typeof entry !== "object") return null;
+          const version = typeof entry.version === "string" ? entry.version : null;
+          const body = typeof entry.body === "string" ? entry.body : null;
+          if (!version || !body) return null;
+          return {
+            version,
+            body,
+            truncated: entry.truncated === true,
+          };
+        })
+        .filter(Boolean)
+    : [];
+  if (!versions.length && value.unavailable !== true) return null;
+  return {
+    source: typeof value.source === "string" ? value.source : "npm-metadata",
+    range: normalizeReleaseNotesRange(value.range),
+    versions,
+    truncated: value.truncated === true,
+    moreVersions: value.moreVersions === true,
+    unavailable: value.unavailable === true,
+  };
+}
+
 /** manifest 文件的绝对路径。 */
 export function manifestPath(target) {
   return path.join(target, MANIFEST_REL);
@@ -42,7 +93,7 @@ export function readManifest(target) {
  * 用户策略字段启用保守默认值;缓存字段只保留结构化摘要,避免把网络错误细节写入项目。
  *
  * @param {object|null|undefined} value 原始 updateCheck 字段
- * @returns {{enabled:boolean,policy:string,intervalHours:number,lastCheckedAt:string|null,lastRemote:object|null,lastStatus:string|null,lastErrorCode:string|null}} 归一化后的 updateCheck
+ * @returns {{enabled:boolean,policy:string,intervalHours:number,lastCheckedAt:string|null,lastRemote:object|null,lastReleaseNotes:object|null,lastStatus:string|null,lastErrorCode:string|null}} 归一化后的 updateCheck
  */
 export function normalizeUpdateCheck(value) {
   const raw = value && typeof value === "object" ? value : {};
@@ -64,6 +115,7 @@ export function normalizeUpdateCheck(value) {
     intervalHours,
     lastCheckedAt: typeof raw.lastCheckedAt === "string" ? raw.lastCheckedAt : null,
     lastRemote,
+    lastReleaseNotes: normalizeLastReleaseNotes(raw.lastReleaseNotes),
     lastStatus: typeof raw.lastStatus === "string" ? raw.lastStatus : null,
     lastErrorCode: typeof raw.lastErrorCode === "string" ? raw.lastErrorCode : null,
   };

package/src/lib/self-check.js

@@ -2,7 +2,12 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { readManifest, readUpdateCheck, writeUpdateCheck } from "./manifest.js";
-import { fetchPackageDistTags, getUpdateRecommendation } from "./update-check.js";
+import {
+  buildReleaseNotesSummary,
+  fetchPackageUpdateMetadata,
+  getUpdateRecommendation,
+  isPrerelease,
+} from "./update-check.js";
 import { isRunningViaNpx } from "./runtime-env.js";
 import { flowerVersion, trellisVersion } from "./versions.js";
 
@@ -36,6 +41,74 @@ function isRemoteCacheFresh(updateCheck, now = new Date()) {
   return now.getTime() - checkedAt < updateCheck.intervalHours * 60 * 60 * 1000;
 }
 
+/**
+ * 判断缓存的 release notes 是否匹配本次检查范围。
+ *
+ * @param {object} updateCheck 归一化 updateCheck 配置
+ * @param {{from:string|null,to:string|null,channel:string,reason:string}|null} range 本次期望范围
+ * @returns {object|null} 可复用的缓存摘要
+ */
+function cachedReleaseNotes(updateCheck, range) {
+  const cached = updateCheck.lastReleaseNotes;
+  if (!cached || !range || cached.unavailable) return null;
+  const cachedRange = cached.range || {};
+  if (
+    cachedRange.from !== range.from ||
+    cachedRange.to !== range.to ||
+    cachedRange.channel !== range.channel ||
+    cachedRange.reason !== range.reason
+  ) {
+    return null;
+  }
+  return Array.isArray(cached.versions) && cached.versions.length ? cached : null;
+}
+
+/**
+ * 构造新版升级 release notes 范围。
+ *
+ * @param {string} currentFlower 当前 flower 版本
+ * @param {{version:string,tag:string}|null} recommendation 升级推荐
+ * @returns {{from:string,to:string,channel:string,reason:string}|null} release notes 范围
+ */
+function updateReleaseNotesRange(currentFlower, recommendation) {
+  if (!recommendation?.version) return null;
+  return {
+    from: currentFlower,
+    to: recommendation.version,
+    channel: recommendation.tag,
+    reason: "update_available",
+  };
+}
+
+/**
+ * 构造项目追平 release notes 范围。
+ *
+ * @param {string|null} projectFlower 项目 manifest 记录的 flower 版本
+ * @param {string} currentFlower 当前 flower 版本
+ * @returns {{from:string,to:string,channel:string,reason:string}|null} release notes 范围
+ */
+function projectReleaseNotesRange(projectFlower, currentFlower) {
+  if (!projectFlower || !currentFlower) return null;
+  return {
+    from: projectFlower,
+    to: currentFlower,
+    channel: isPrerelease(currentFlower) ? "beta" : "latest",
+    reason: "project_out_of_sync",
+  };
+}
+
+/**
+ * 从 registry metadata 构造 release notes 摘要。
+ *
+ * @param {object|null} metadata registry metadata
+ * @param {object|null} range release notes 范围
+ * @returns {object|null} release notes 摘要
+ */
+function releaseNotesFromMetadata(metadata, range) {
+  if (!range) return null;
+  return buildReleaseNotesSummary(metadata?.releaseNotesByVersion, range);
+}
+
 /** 检查目标目录 git 工作区是否 clean。 */
 function gitSafety(target) {
   const common = {
@@ -184,7 +257,7 @@ function withAction(target, policy, result, command) {
 }
 
 /** 生成项目重叠加建议结果。 */
-function projectOutOfSyncResult(base, target, remotePatch = {}) {
+function projectOutOfSyncResult(base, target, remotePatch = {}, releaseNotes = null) {
   const command = selfUpdateCommand(target, { projectOnly: true });
   return withAction(
     target,
@@ -198,6 +271,7 @@ function projectOutOfSyncResult(base, target, remotePatch = {}) {
         recommended: command,
         projectUpdate: projectUpdateCommand(target),
       },
+      releaseNotes,
     },
     command,
   );
@@ -276,6 +350,7 @@ export async function buildSelfCheck(target, options = {}) {
       errorCode: null,
     },
     recommendation: null,
+    releaseNotes: null,
     commands: {},
     safety: null,
     ai: null,
@@ -297,6 +372,7 @@ export async function buildSelfCheck(target, options = {}) {
     const recommendation = getUpdateRecommendation(currentFlower, tags);
     if (recommendation) {
       const command = selfUpdateCommand(absoluteTarget);
+      const releaseNotesRange = updateReleaseNotesRange(currentFlower, recommendation);
       return withAction(
         absoluteTarget,
         updateCheck.policy,
@@ -311,16 +387,18 @@ export async function buildSelfCheck(target, options = {}) {
             npm: recommendation.command,
             projectUpdate: projectUpdateCommand(absoluteTarget),
           },
+          releaseNotes: cachedReleaseNotes(updateCheck, releaseNotesRange),
         },
         command,
       );
     }
     if (projectOutOfSync) {
+      const releaseNotesRange = projectReleaseNotesRange(projectFlower, currentFlower);
       return projectOutOfSyncResult(base, absoluteTarget, {
         tags,
         fromCache: true,
         skipped: true,
-      });
+      }, cachedReleaseNotes(updateCheck, releaseNotesRange));
     }
     return {
       ...base,
@@ -330,8 +408,8 @@ export async function buildSelfCheck(target, options = {}) {
     };
   }
 
-  tags = await fetchPackageDistTags();
-  if (!tags) {
+  const metadata = await fetchPackageUpdateMetadata();
+  if (!metadata) {
     if (writeCache && manifest) {
       writeUpdateCheck(absoluteTarget, {
         lastStatus: "offline",
@@ -340,7 +418,13 @@ export async function buildSelfCheck(target, options = {}) {
     }
     const remotePatch = { tags: updateCheck.lastRemote, errorCode: "fetch_failed" };
     if (projectOutOfSync) {
-      return projectOutOfSyncResult(base, absoluteTarget, remotePatch);
+      const releaseNotesRange = projectReleaseNotesRange(projectFlower, currentFlower);
+      return projectOutOfSyncResult(
+        base,
+        absoluteTarget,
+        remotePatch,
+        cachedReleaseNotes(updateCheck, releaseNotesRange),
+      );
     }
     return {
       ...base,
@@ -350,12 +434,18 @@ export async function buildSelfCheck(target, options = {}) {
     };
   }
 
+  tags = metadata.tags;
   const recommendation = getUpdateRecommendation(currentFlower, tags);
   const remoteStatus = recommendation ? "update_available" : "up_to_date";
+  const releaseNotesRange = recommendation
+    ? updateReleaseNotesRange(currentFlower, recommendation)
+    : projectReleaseNotesRange(projectFlower, currentFlower);
+  const releaseNotes = releaseNotesFromMetadata(metadata, releaseNotesRange);
   if (writeCache && manifest) {
     writeUpdateCheck(absoluteTarget, {
       lastCheckedAt: now.toISOString(),
       lastRemote: tags,
+      lastReleaseNotes: releaseNotes && !releaseNotes.unavailable ? releaseNotes : null,
       lastStatus: remoteStatus,
       lastErrorCode: null,
     });
@@ -363,7 +453,7 @@ export async function buildSelfCheck(target, options = {}) {
 
   if (!recommendation) {
     if (projectOutOfSync) {
-      return projectOutOfSyncResult(base, absoluteTarget, { tags });
+      return projectOutOfSyncResult(base, absoluteTarget, { tags }, releaseNotes);
     }
     return {
       ...base,
@@ -386,6 +476,7 @@ export async function buildSelfCheck(target, options = {}) {
         npm: recommendation.command,
         projectUpdate: projectUpdateCommand(absoluteTarget),
       },
+      releaseNotes,
     },
     command,
   );

package/src/lib/update-check.js

@@ -19,15 +19,75 @@ const REGISTRY = "https://registry.npmjs.org";
 const PKG = "flower-trellis";
 /** 网络探测超时(毫秒)—— 启动检查有 hook 总预算兜底,5s 可降低 registry 偶发慢响应误判。 */
 const TIMEOUT_MS = 5000;
+/** npm package metadata 中保存 flower 内部发布说明的字段名。 */
+const RELEASE_NOTES_FIELD = "flowerReleaseNotes";
+/** 单次注入最多展示的版本数。 */
+const RELEASE_NOTES_MAX_VERSIONS = 5;
+/** 单个版本发布说明最多保留的字符数。 */
+const RELEASE_NOTES_MAX_VERSION_CHARS = 500;
+/** 所有版本发布说明合计最多保留的字符数。 */
+const RELEASE_NOTES_MAX_TOTAL_CHARS = 1600;
 
 /**
- * 取 npm 上 flower-trellis 的 dist-tags;任何失败(离线/超时/非 200/解析异常)一律
- * 返回 null —— 调用方据此「拿不到就当没这回事」继续主流程。
+ * 从 npm registry 根文档解析 dist-tags。
  *
- * 用 AbortController 给内置 fetch 加超时,finally 清除定时器防句柄泄漏。
- * @returns {Promise<{latest:string|null,beta:string|null}|null>} 可用 dist-tags,或失败时 null
+ * @param {object} json registry 根文档 JSON
+ * @returns {{latest:string|null,beta:string|null}|null} 可用 dist-tags
  */
-export async function fetchPackageDistTags() {
+function parseDistTags(json) {
+  const tags = json && typeof json === "object" ? json["dist-tags"] : null;
+  const latest = typeof tags?.latest === "string" ? tags.latest : null;
+  const beta = typeof tags?.beta === "string" ? tags.beta : null;
+  return latest || beta ? { latest, beta } : null;
+}
+
+/**
+ * 解析单个版本的 flowerReleaseNotes metadata。
+ *
+ * @param {string} version registry versions 字典里的版本号
+ * @param {object} pkgVersion 对应版本 package metadata
+ * @returns {{version:string,body:string,truncated:boolean,source:string}|null} 发布说明 metadata
+ */
+function parseReleaseNotesMetadata(version, pkgVersion) {
+  const raw = pkgVersion?.[RELEASE_NOTES_FIELD];
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.version !== version) return null;
+  const body = typeof raw.body === "string" ? raw.body.trim() : "";
+  if (!body) return null;
+  return {
+    version,
+    body,
+    truncated: raw.truncated === true,
+    source: "npm-metadata",
+  };
+}
+
+/**
+ * 从 npm registry 根文档解析每个版本的发布说明 metadata。
+ *
+ * @param {object} json registry 根文档 JSON
+ * @returns {Record<string,{version:string,body:string,truncated:boolean,source:string}>} 按版本号索引的发布说明
+ */
+function parseReleaseNotesByVersion(json) {
+  const versions = json && typeof json === "object" ? json.versions : null;
+  if (!versions || typeof versions !== "object") return {};
+  const notes = {};
+  for (const [version, pkgVersion] of Object.entries(versions)) {
+    const parsed = parseReleaseNotesMetadata(version, pkgVersion);
+    if (parsed) notes[version] = parsed;
+  }
+  return notes;
+}
+
+/**
+ * 取 npm 上 flower-trellis 的更新 metadata。
+ *
+ * 一次请求 registry 根文档,同时解析 dist-tags 与各版本的 flowerReleaseNotes。任何失败
+ * (离线/超时/非 200/解析异常)一律返回 null,调用方继续主流程。
+ *
+ * @returns {Promise<{tags:{latest:string|null,beta:string|null},releaseNotesByVersion:Record<string,{version:string,body:string,truncated:boolean,source:string}>}|null>} 更新 metadata
+ */
+export async function fetchPackageUpdateMetadata() {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
   try {
@@ -37,10 +97,12 @@ export async function fetchPackageDistTags() {
     });
     if (!res.ok) return null; // 非 200(404/5xx 等)→ 静默跳过
     const json = await res.json();
-    const tags = json && typeof json === "object" ? json["dist-tags"] : null;
-    const latest = typeof tags?.latest === "string" ? tags.latest : null;
-    const beta = typeof tags?.beta === "string" ? tags.beta : null;
-    return latest || beta ? { latest, beta } : null;
+    const tags = parseDistTags(json);
+    if (!tags) return null;
+    return {
+      tags,
+      releaseNotesByVersion: parseReleaseNotesByVersion(json),
+    };
   } catch {
     return null; // AbortError(超时)/ fetch failed(离线)/ JSON 解析失败 → 静默
   } finally {
@@ -48,10 +110,22 @@ export async function fetchPackageDistTags() {
   }
 }
 
+/**
+ * 取 npm 上 flower-trellis 的 dist-tags;任何失败(离线/超时/非 200/解析异常)一律
+ * 返回 null —— 调用方据此「拿不到就当没这回事」继续主流程。
+ *
+ * 用 AbortController 给内置 fetch 加超时,finally 清除定时器防句柄泄漏。
+ * @returns {Promise<{latest:string|null,beta:string|null}|null>} 可用 dist-tags,或失败时 null
+ */
+export async function fetchPackageDistTags() {
+  const metadata = await fetchPackageUpdateMetadata();
+  return metadata?.tags ?? null;
+}
+
 /**
  * 取 npm 上 flower-trellis 的 latest 版本号。
  *
- * 保留这个导出是为了兼容已有调用方;新逻辑应优先使用 `fetchPackageDistTags()`。
+ * 保留这个导出是为了兼容已有调用方;新逻辑应优先使用 `fetchPackageUpdateMetadata()`。
  * @returns {Promise<string|null>} latest 版本号,或失败时 null
  */
 export async function fetchLatestVersion() {
@@ -147,6 +221,106 @@ export function compareVersions(a, b) {
   return comparePrerelease(av.prerelease, bv.prerelease);
 }
 
+/**
+ * 判断版本是否属于目标更新通道。
+ *
+ * @param {string} version 版本号
+ * @param {"latest"|"beta"|string} channel 目标通道
+ * @returns {boolean}
+ */
+function matchesReleaseNotesChannel(version, channel) {
+  if (channel === "beta") return isPrerelease(version);
+  return !isPrerelease(version);
+}
+
+/**
+ * 把单版本发布说明裁剪到注入上限。
+ *
+ * @param {{body:string,truncated?:boolean}} note 原始版本发布说明
+ * @param {number} remainingTotal 总字符剩余额度
+ * @returns {{body:string,truncated:boolean,used:number}|null} 裁剪后的发布说明
+ */
+function limitReleaseNoteBody(note, remainingTotal) {
+  if (remainingTotal <= 0) return null;
+  let body = String(note.body || "").trim();
+  let truncated = note.truncated === true;
+  if (!body) return null;
+  if (body.length > RELEASE_NOTES_MAX_VERSION_CHARS) {
+    body = body.slice(0, RELEASE_NOTES_MAX_VERSION_CHARS).trimEnd();
+    truncated = true;
+  }
+  if (body.length > remainingTotal) {
+    body = body.slice(0, remainingTotal).trimEnd();
+    truncated = true;
+  }
+  if (!body) return null;
+  return { body, truncated, used: body.length };
+}
+
+/**
+ * 为 self-check / hook 构造跨版本发布说明摘要。
+ *
+ * @param {Record<string,{version:string,body:string,truncated:boolean,source:string}>|null|undefined} releaseNotesByVersion 按版本索引的 npm metadata
+ * @param {{from:string|null,to:string|null,channel:"latest"|"beta"|string,reason:string}} range 聚合范围
+ * @returns {{source:string,range:object,versions:Array<{version:string,body:string,truncated:boolean}>,truncated:boolean,moreVersions:boolean,unavailable:boolean}} 可注入的发布说明摘要
+ */
+export function buildReleaseNotesSummary(releaseNotesByVersion, range) {
+  const summaryRange = {
+    from: range?.from ?? null,
+    to: range?.to ?? null,
+    channel: range?.channel ?? "latest",
+    reason: range?.reason ?? null,
+  };
+  const empty = {
+    source: "npm-metadata",
+    range: summaryRange,
+    versions: [],
+    truncated: false,
+    moreVersions: false,
+    unavailable: true,
+  };
+  if (!summaryRange.from || !summaryRange.to || !releaseNotesByVersion) return empty;
+
+  const candidates = Object.keys(releaseNotesByVersion)
+    .filter((version) => compareVersions(version, summaryRange.from) === 1)
+    .filter((version) => compareVersions(version, summaryRange.to) <= 0)
+    .filter((version) => matchesReleaseNotesChannel(version, summaryRange.channel))
+    .sort(compareVersions);
+
+  if (!candidates.length) return empty;
+
+  const limitedCandidates = candidates.slice(-RELEASE_NOTES_MAX_VERSIONS);
+  const versions = [];
+  let remainingTotal = RELEASE_NOTES_MAX_TOTAL_CHARS;
+  let truncated = false;
+  for (const version of limitedCandidates) {
+    const limited = limitReleaseNoteBody(releaseNotesByVersion[version], remainingTotal);
+    if (!limited) {
+      truncated = true;
+      break;
+    }
+    versions.push({
+      version,
+      body: limited.body,
+      truncated: limited.truncated,
+    });
+    remainingTotal -= limited.used;
+    if (limited.truncated) truncated = true;
+  }
+
+  const moreVersions =
+    candidates.length > limitedCandidates.length ||
+    versions.length < limitedCandidates.length;
+  return {
+    source: "npm-metadata",
+    range: summaryRange,
+    versions,
+    truncated,
+    moreVersions,
+    unavailable: versions.length === 0,
+  };
+}
+
 /**
  * 根据当前版本和 npm dist-tags 生成升级推荐。
  *
@@ -175,15 +349,20 @@ export function getUpdateRecommendation(current, tags) {
 }
 
 /** 尽力而为刷新目标项目 manifest 里的远端探测缓存。 */
-function rememberRemoteTags(target, tags, status) {
+function rememberRemoteTags(target, tags, status, releaseNotes = null) {
   try {
     if (!readManifest(target)) return;
-    writeUpdateCheck(target, {
+    const patch = {
       lastCheckedAt: new Date().toISOString(),
       lastRemote: tags,
       lastStatus: status,
       lastErrorCode: null,
-    });
+      lastReleaseNotes: null,
+    };
+    if (releaseNotes && !releaseNotes.unavailable) {
+      patch.lastReleaseNotes = releaseNotes;
+    }
+    writeUpdateCheck(target, patch);
   } catch {
     // 缓存写入只是优化后续启动提示,失败不能影响 init/update 主流程。
   }
@@ -217,13 +396,27 @@ export async function checkForUpdate(ctx, commandLabel) {
   if (isRunningViaNpx(import.meta.url)) return;
 
   // 3. 尽力而为取 dist-tags;拿不到就静默退出
-  const tags = await fetchPackageDistTags();
-  if (!tags) return;
+  const metadata = await fetchPackageUpdateMetadata();
+  if (!metadata) return;
+  const tags = metadata.tags;
 
   // 4. 根据本地版本通道生成推荐;无推荐时不打扰
   const current = flowerVersion();
   const recommendation = getUpdateRecommendation(current, tags);
-  rememberRemoteTags(ctx.target, tags, recommendation ? "update_available" : "up_to_date");
+  const releaseNotes = recommendation
+    ? buildReleaseNotesSummary(metadata.releaseNotesByVersion, {
+        from: current,
+        to: recommendation.version,
+        channel: recommendation.tag,
+        reason: "update_available",
+      })
+    : null;
+  rememberRemoteTags(
+    ctx.target,
+    tags,
+    recommendation ? "update_available" : "up_to_date",
+    releaseNotes,
+  );
   if (!recommendation) return;
 
   // 5. 打印发现新版本通知(粉色品牌色,与 banner 一致)