feat: surface freshness and follow paths

Author: Ubuntu

README.en.md

@@ -11,6 +11,12 @@ Free Clash, sing-box, and V2Ray subscription links with live node status, multi-
 
 [Atom Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.xml) • [JSON Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.json) • [Discussions](https://github.com/Au1rxx/free-vpn-subscriptions/discussions)
 
+## Check These Signals First
+
+- If you want to confirm that the public side is still fresh, check the [Status Dashboard](https://au1rxx.github.io/free-vpn-subscriptions/status.html) and the latest timestamp in `output/status.json`.
+- If you want the newest snapshot, clean download links, and release history, go straight to [GitHub Releases](https://github.com/Au1rxx/free-vpn-subscriptions/releases).
+- If you want ongoing updates, do not rely on bookmarking the repo homepage alone. Star the repo, use the repository Watch menu for `Releases`, or subscribe to the [Atom Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.xml) / [JSON Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.json).
+
 ## Why This Repo
 
 - Public subscription feed for `Clash`, `sing-box`, and `V2Ray` users.
@@ -126,7 +132,7 @@ These client-specific guides exist to improve search visibility for real user qu
 If this feed is useful:
 
 - Star the repository to help discovery.
-- Watch releases if you want visible update checkpoints.
+- Use the repository Watch menu for `Releases` if you want visible update checkpoints, or subscribe to the Atom / JSON feed above.
 - Use Discussions for client requests, setup questions, and broken-link reports.
 - Use Issues only when a public feed artifact, release asset, or Pages route is actually broken.
 

README.md

@@ -13,6 +13,12 @@
 
 [Atom Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.xml) • [JSON Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.json) • [Discussions](https://github.com/Au1rxx/free-vpn-subscriptions/discussions)
 
+## 先看这三个信号
+
+- 想确认公开侧是不是还在更新，先看 [状态面板](https://au1rxx.github.io/free-vpn-subscriptions/status.html) 和 `output/status.json` 的最近检查时间。
+- 想看最近一次快照、手动下载入口和历史版本，直接看 [GitHub Releases](https://github.com/Au1rxx/free-vpn-subscriptions/releases)。
+- 想持续跟踪更新，不要只收藏仓库首页；请优先 `Star`、到仓库 Watch 菜单里关注 `Releases`，或直接订阅 [Atom Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.xml) / [JSON Feed](https://au1rxx.github.io/free-vpn-subscriptions/updates.json)。
+
 ## 项目定位
 
 - 面向 `Clash`、`sing-box`、`V2Ray` 用户的公开订阅分发仓库。
@@ -128,7 +134,7 @@
 如果这个仓库对你有帮助：
 
 - 请点 `Star`，帮助仓库获得更高曝光。
-- 如果你想跟踪快照更新，可以 `Watch releases`。
+- 如果你想跟踪快照更新，请到仓库的 Watch 菜单里关注 `Releases`，或者直接订阅上面的 Atom / JSON Feed。
 - 安装问题、客户端请求、兼容性反馈请优先走 `Discussions`。
 - 只有在公开链接、Release 资产或 Pages 页面真实异常时，再提交 `Issues`。
 

site/app.js

@@ -1,6 +1,12 @@
 const RELEASES_ENDPOINT =
   "https://api.github.com/repos/Au1rxx/free-vpn-subscriptions/releases?per_page=6";
 
+const dashboardState = {
+  activeCountText: "",
+  latestCheck: "",
+  latestReleaseStamp: "",
+};
+
 function formatUtcStamp(value) {
   return value ? value.replace("T", " ").replace("Z", " UTC") : "";
 }
@@ -27,6 +33,49 @@ function extractReleaseSummary(body) {
   return blocks[0] || "";
 }
 
+function renderFreshnessBanner() {
+  const freshnessTitle = document.getElementById("freshness-title");
+  const freshnessDetail = document.getElementById("freshness-detail");
+
+  if (!freshnessTitle || !freshnessDetail) {
+    return;
+  }
+
+  if (!dashboardState.latestCheck) {
+    freshnessTitle.textContent = "公开状态时间未知";
+    freshnessDetail.textContent =
+      "先打开状态页确认最近检查时间，再决定是否导入、刷新，或去 Releases 看最近快照。";
+    return;
+  }
+
+  const diffHours = (Date.now() - Date.parse(dashboardState.latestCheck)) / (1000 * 60 * 60);
+  const statusStamp = formatUtcStamp(dashboardState.latestCheck);
+  const releaseStamp = dashboardState.latestReleaseStamp
+    ? formatUtcStamp(dashboardState.latestReleaseStamp)
+    : "";
+
+  if (Number.isNaN(diffHours)) {
+    freshnessTitle.textContent = "公开状态已发布";
+  } else if (diffHours <= 3) {
+    freshnessTitle.textContent = "公开状态在线";
+  } else if (diffHours <= 12) {
+    freshnessTitle.textContent = "公开状态略有延迟";
+  } else {
+    freshnessTitle.textContent = "公开状态可能滞后";
+  }
+
+  const parts = [];
+  if (dashboardState.activeCountText) {
+    parts.push(dashboardState.activeCountText);
+  }
+  parts.push(`最近状态检查 ${statusStamp}`);
+  if (releaseStamp) {
+    parts.push(`最近快照发布 ${releaseStamp}`);
+  }
+  parts.push("想持续跟踪更新就去看 Releases / Watch，或订阅 Feed");
+  freshnessDetail.textContent = `${parts.join("。")}。`;
+}
+
 async function loadStatus() {
   const activeCount = document.getElementById("active-count");
   const statusStamp = document.getElementById("status-stamp");
@@ -50,7 +99,11 @@ async function loadStatus() {
       .sort()
       .pop();
 
-    activeCount.textContent = `${active.length} / ${nodes.length} active`;
+    const activeText = `${active.length} / ${nodes.length} active`;
+    dashboardState.activeCountText = activeText;
+    dashboardState.latestCheck = latestCheck || "";
+
+    activeCount.textContent = activeText;
     statusStamp.textContent = latestCheck
       ? `Last check ${formatUtcStamp(latestCheck)}`
       : "No recent status timestamp";
@@ -82,10 +135,14 @@ async function loadStatus() {
         `;
       })
       .join("");
+    renderFreshnessBanner();
   } catch (error) {
+    dashboardState.activeCountText = "";
+    dashboardState.latestCheck = "";
     activeCount.textContent = "Unavailable";
     statusStamp.textContent = "Could not load current status";
     nodeList.innerHTML = `<p class="muted">The public status feed is not available yet: ${error.message}</p>`;
+    renderFreshnessBanner();
   }
 }
 
@@ -122,6 +179,7 @@ async function loadReleases() {
     const latestTitle = latest.name || latest.tag_name;
     const latestStamp = formatUtcStamp(latest.published_at);
     const latestSummary = extractReleaseSummary(latest.body);
+    dashboardState.latestReleaseStamp = latest.published_at || "";
 
     if (latestRelease) {
       latestRelease.textContent = latestStamp
@@ -160,7 +218,9 @@ async function loadReleases() {
         })
         .join("");
     }
+    renderFreshnessBanner();
   } catch (error) {
+    dashboardState.latestReleaseStamp = "";
     if (latestRelease) {
       latestRelease.textContent = "暂时无法读取最近发布记录";
     }
@@ -173,6 +233,7 @@ async function loadReleases() {
       releaseList.innerHTML =
         `<p class="muted">暂时无法加载更新列表：${escapeHtml(error.message)}。你可以直接打开 GitHub Releases 查看历史快照。</p>`;
     }
+    renderFreshnessBanner();
   }
 }
 

site/index.html

@@ -50,6 +50,18 @@ <h1 class="hero-title">免费 VPN 订阅链接与实时节点状态</h1>
             <a href="./updates.xml">订阅更新 Feed</a>
             <a href="https://github.com/Au1rxx/free-vpn-subscriptions/releases/latest">查看最新快照</a>
           </div>
+          <div class="freshness-banner">
+            <div class="freshness-copy">
+              <span class="metric-label">公开更新信号</span>
+              <strong id="freshness-title">正在读取公开状态和最近快照</strong>
+              <span id="freshness-detail">这里会显示最近状态检查时间，以及你该去哪里跟踪后续更新。</span>
+            </div>
+            <div class="freshness-actions">
+              <a class="button button-secondary" href="./status.html">检查状态是否新鲜</a>
+              <a class="button button-secondary" href="https://github.com/Au1rxx/free-vpn-subscriptions/releases">看 Releases / Watch</a>
+              <a class="button button-secondary" href="https://github.com/Au1rxx/free-vpn-subscriptions">Star 仓库</a>
+            </div>
+          </div>
         </div>
         <div class="hero-panel">
           <div class="metric-card">
@@ -270,7 +282,8 @@ <h3>拿完链接之后，也知道去哪里提问和反馈。</h3>
               通过 Star、Release 更新和 Discussions 问答，把一次性流量沉淀成持续回访和可搜索内容。
             </p>
             <div class="stack-actions">
-              <a class="button button-primary" href="https://github.com/Au1rxx/free-vpn-subscriptions">打开 GitHub 仓库</a>
+              <a class="button button-primary" href="https://github.com/Au1rxx/free-vpn-subscriptions">Star 仓库</a>
+              <a class="button button-secondary" href="https://github.com/Au1rxx/free-vpn-subscriptions/releases">打开 Releases</a>
               <a class="button button-secondary" href="https://github.com/Au1rxx/free-vpn-subscriptions/discussions">打开 Discussions</a>
             </div>
           </div>

site/styles.css

@@ -127,6 +127,37 @@ li {
   margin-top: 1rem;
 }
 
+.freshness-banner {
+  display: grid;
+  grid-template-columns: 1.1fr auto;
+  gap: 1rem;
+  align-items: center;
+  margin-top: 1.3rem;
+  padding: 1rem 1.1rem;
+  border-radius: 22px;
+  border: 1px solid rgba(15, 118, 110, 0.15);
+  background: rgba(255, 252, 247, 0.78);
+}
+
+.freshness-copy strong {
+  display: block;
+  margin: 0.2rem 0 0.3rem;
+  font-size: 1.05rem;
+  color: var(--text);
+}
+
+.freshness-copy span:last-child {
+  color: var(--muted);
+  line-height: 1.6;
+}
+
+.freshness-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 0.7rem;
+}
+
 .signal-row a {
   color: var(--accent-strong);
   font-weight: 700;
@@ -431,6 +462,7 @@ pre {
   .section-grid,
   .content-grid,
   .cards-three,
+  .freshness-banner,
   .release-highlight,
   .release-item,
   .node-item {
@@ -440,4 +472,8 @@ pre {
   h1 {
     max-width: none;
   }
+
+  .freshness-actions {
+    justify-content: flex-start;
+  }
 }