Prepare the dev snapshot for main review on a clean release branch

This release branch starts from the latest origin/main and folds in the
current origin/dev snapshot so the PR to main can follow the repo's
publish flow without opening directly from dev. Conflict-heavy files
were normalized back to the dev snapshot where necessary so the release
branch reflects the code currently being carried on dev instead of a
line-merged hybrid.

Constraint: Publication flow requires a clean release branch from latest origin/main rather than a PR directly from dev
Constraint: The branch must preserve the current dev snapshot even when main and dev have drifted substantially
Rejected: Open the PR directly from dev | violates the repo publication flow
Rejected: Manually redesign every historic dev/main conflict during release prep | too broad for a publish branch
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Treat this branch as a publication snapshot of dev-on-top-of-main, not as a general cleanup pass over old divergence
Tested: update-center focused vitest suite on release branch; typecheck; build:web; docs:build; repo:drift-check
Not-tested: Full npm test remains red from inherited tmp/sub2api frontend suites and an existing firstByteTimeout unhandled error

docs/.vitepress/config.test.ts

@@ -1,5 +1,5 @@
 import { existsSync, globSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import config from './config';
@@ -36,11 +36,21 @@ const getAlias = (aliasConfig: unknown, specifier: string): string | undefined =
 const repoRoot = fileURLToPath(new URL('../..', import.meta.url));
 
 const getExpectedEntry = (hoistedRelativePath: string, pnpmPattern: string) => {
-  const hoistedEntry = resolve(repoRoot, hoistedRelativePath);
-  if (existsSync(hoistedEntry)) return hoistedEntry;
+  let currentRoot = repoRoot;
 
-  const [pnpmEntry] = globSync(resolve(repoRoot, pnpmPattern));
-  return pnpmEntry;
+  while (true) {
+    const hoistedEntry = resolve(currentRoot, hoistedRelativePath);
+    if (existsSync(hoistedEntry)) return hoistedEntry;
+
+    const [pnpmEntry] = globSync(resolve(currentRoot, pnpmPattern));
+    if (pnpmEntry) return pnpmEntry;
+
+    const parentRoot = dirname(currentRoot);
+    if (parentRoot === currentRoot) break;
+    currentRoot = parentRoot;
+  }
+
+  return undefined;
 };
 
 describe('docs vitepress config', () => {

docs/.vitepress/config.ts

@@ -1,17 +1,28 @@
 import { existsSync, globSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vitepress';
 import { withMermaid } from 'vitepress-plugin-mermaid';
 
 const repoRoot = fileURLToPath(new URL('../..', import.meta.url));
-const resolveDependencyEntry = (hoistedRelativePath: string, pnpmPattern: string) => {
-  const hoistedEntry = resolve(repoRoot, hoistedRelativePath);
-  if (existsSync(hoistedEntry)) return hoistedEntry;
 
-  const [pnpmEntry] = globSync(resolve(repoRoot, pnpmPattern));
-  return pnpmEntry;
-};
+function resolveDependencyEntry(hoistedRelativePath: string, pnpmPattern: string) {
+  let currentRoot = repoRoot;
+
+  while (true) {
+    const hoistedEntry = resolve(currentRoot, hoistedRelativePath);
+    if (existsSync(hoistedEntry)) return hoistedEntry;
+
+    const [pnpmEntry] = globSync(resolve(currentRoot, pnpmPattern));
+    if (pnpmEntry) return pnpmEntry;
+
+    const parentRoot = dirname(currentRoot);
+    if (parentRoot === currentRoot) break;
+    currentRoot = parentRoot;
+  }
+
+  return undefined;
+}
 
 const dayjsEsmEntry = resolveDependencyEntry(
   'node_modules/dayjs/esm/index.js',

docs/k3s-update-center.md

@@ -308,6 +308,11 @@ helper 端使用：
 - `GitHub Releases`
 - `Docker Hub`
 
+补充一点：
+
+- `Docker Hub` 里的**自动发现**仍然优先 `latest` / `main` / 稳定 SemVer 标签
+- 如果你要部署 `dev`、分支名、临时标签或 `sha-*` 这类非稳定标签，直接在 Docker Hub 卡片底部用“手动部署 Docker Hub 标签”填写即可
+
 对已经跑起来的 K3s / Helm 用户来说，更新中心的日常配置主要就在这一页：
 
 ```text
@@ -325,7 +330,7 @@ helper 端使用：
    - 版本来源发现了可部署版本
    - 如果 Docker Hub 显示的是 `latest @ sha256:...`，说明页面已经识别到 alias tag 当前指向的具体镜像 digest
    - Deploy Helper 显示健康
-4. 再点部署按钮
+4. 如果你要跟随稳定候选，直接点部署按钮；如果你要切到 `dev` / 分支 / 临时标签，就在 Docker Hub 卡片底部手动填写 tag，必要时连 digest 一起填
 5. 在页面下方看部署日志
 6. 如果升级后发现问题，可以直接在“回退历史”里点旧 revision 回滚；只要该 revision 当时记录了 digest，就会跟着一起回到对应镜像