feat(update-check): ✨ add self-update reminder with ttl cache and cli…

README.md

@@ -77,6 +77,9 @@ bun run security:audit
 
 # 4) Bootstrap selected skills
 ./bootstrap.sh --only aelf-node-skill --skip-install
+
+# 5) Check hub/catalog update drift (non-blocking)
+bun run update:check
 ```
 
 ## Bootstrap CLI
@@ -91,6 +94,22 @@ Defaults:
 3. health check enabled
 4. `skills-catalog.json` as catalog source
 
+## Update Self-Check
+
+`aelf-skills` includes built-in update reminders for `bootstrap`, `health:check`, and `catalog:generate`.
+Checks are non-blocking and cache-backed (default TTL 24h).
+Reminder output is throttled to once per TTL window by `lastNotifiedAt`.
+
+Commands:
+1. `bun run update:check`
+2. `bun run update:check -- --force`
+3. `bun run update:check:json`
+
+Environment variables:
+1. `AELF_SKILLS_UPDATE_CHECK=0|1` (default `1`)
+2. `AELF_SKILLS_UPDATE_TTL_HOURS=24` (default `24`)
+3. `AELF_SKILLS_UPDATE_CACHE_PATH=<path>` (default `~/.aelf-skills/update-check-cache.json`)
+
 ## Generated Catalog
 
 `skills-catalog.json` is the stable machine interface.
@@ -130,13 +149,13 @@ This section is auto-synced by `bun run catalog:generate`.
 <!-- SKILL_TABLE_START -->
 | ID | npm Package | Version | OpenClaw Tools | Description |
 |---|---|---:|---:|---|
-| aelf-node-skill | @blockchain-forever/aelf-node-skill | 0.1.0 | 11 | AElf node querying and contract execution skill for agents. |
-| aelfscan-skill | @aelfscan/agent-skills | 0.2.0 | 61 | AelfScan explorer data retrieval and analytics skill for agents. |
-| awaken-agent-skills | @awaken-finance/agent-kit | 1.2.1 | 11 | Awaken DEX trading and market data operations for agents. |
-| eforest-agent-skills | @eforest-finance/agent-skills | 0.4.0 | 48 | eForest symbol and forest NFT operations for agent workflows. |
-| portkey-ca-agent-skills | @portkey/ca-agent-skills | 1.1.2 | 28 | Portkey CA wallet registration/auth/guardian/transfer operations for agents. |
-| portkey-eoa-agent-skills | @portkey/eoa-agent-skills | 1.2.1 | 21 | Portkey EOA wallet and asset operations for aelf agents. |
-| tomorrowdao-agent-skills | @tomorrowdao/agent-skills | 0.1.0 | 41 | TomorrowDAO governance, BP, and resource operations for agents. |
+| aelf-node-skill | @blockchain-forever/aelf-node-skill | 0.1.3 | 11 | AElf node querying and contract execution skill for agents. |
+| aelfscan-skill | @aelfscan/agent-skills | 0.2.2 | 61 | AelfScan explorer data retrieval and analytics skill for agents. |
+| awaken-agent-skills | @awaken-finance/agent-kit | 1.2.4 | 11 | Awaken DEX trading and market data operations for agents. |
+| eforest-agent-skills | @eforest-finance/agent-skills | 0.4.3 | 48 | eForest symbol and forest NFT operations for agent workflows. |
+| portkey-ca-agent-skills | @portkey/ca-agent-skills | 1.1.5 | 28 | Portkey CA wallet registration/auth/guardian/transfer operations for agents. |
+| portkey-eoa-agent-skills | @portkey/eoa-agent-skills | 1.2.4 | 21 | Portkey EOA wallet and asset operations for aelf agents. |
+| tomorrowdao-agent-skills | @tomorrowdao/agent-skills | 0.1.4 | 41 | TomorrowDAO governance, BP, and resource operations for agents. |
 <!-- SKILL_TABLE_END -->
 
 ## Health Check

README.zh-CN.md

@@ -77,6 +77,9 @@ bun run security:audit
 
 # 4) 拉起指定 skill
 ./bootstrap.sh --only aelf-node-skill --skip-install
+
+# 5) 检查 hub/catalog 版本漂移（非阻塞）
+bun run update:check
 ```
 
 ## Bootstrap 命令
@@ -91,6 +94,22 @@ bun run security:audit
 3. 默认执行 health
 4. 默认使用 `skills-catalog.json`
 
+## 更新自检
+
+`aelf-skills` 内置了更新提醒，会在 `bootstrap`、`health:check`、`catalog:generate` 运行时做非阻塞检测。
+检测结果使用本地缓存（默认 TTL 24 小时），不会阻塞主流程。
+提醒输出会基于 `lastNotifiedAt` 做节流：默认 24 小时内最多提示一次。
+
+命令：
+1. `bun run update:check`
+2. `bun run update:check -- --force`
+3. `bun run update:check:json`
+
+环境变量：
+1. `AELF_SKILLS_UPDATE_CHECK=0|1`（默认 `1`）
+2. `AELF_SKILLS_UPDATE_TTL_HOURS=24`（默认 `24`）
+3. `AELF_SKILLS_UPDATE_CACHE_PATH=<path>`（默认 `~/.aelf-skills/update-check-cache.json`）
+
 ## 机器清单说明
 
 `skills-catalog.json` 是稳定机器接口。
@@ -130,13 +149,13 @@ Schema 演进规则：
 <!-- SKILL_TABLE_START -->
 | ID | npm 包名 | 版本 | OpenClaw 工具数 | 描述 |
 |---|---|---:|---:|---|
-| aelf-node-skill | @blockchain-forever/aelf-node-skill | 0.1.0 | 11 | AElf 节点查询与合约调用技能。 |
-| aelfscan-skill | @aelfscan/agent-skills | 0.2.0 | 61 | AelfScan 浏览器数据检索与分析技能。 |
-| awaken-agent-skills | @awaken-finance/agent-kit | 1.2.1 | 11 | Awaken DEX 交易与行情数据技能。 |
-| eforest-agent-skills | @eforest-finance/agent-skills | 0.4.0 | 48 | eForest 代币与 NFT 市场操作技能。 |
-| portkey-ca-agent-skills | @portkey/ca-agent-skills | 1.1.2 | 28 | Portkey CA 钱包注册、认证、Guardian 与转账技能。 |
-| portkey-eoa-agent-skills | @portkey/eoa-agent-skills | 1.2.1 | 21 | Portkey EOA 钱包与资产操作技能。 |
-| tomorrowdao-agent-skills | @tomorrowdao/agent-skills | 0.1.0 | 41 | TomorrowDAO 治理、BP 与资源操作技能。 |
+| aelf-node-skill | @blockchain-forever/aelf-node-skill | 0.1.3 | 11 | AElf 节点查询与合约调用技能。 |
+| aelfscan-skill | @aelfscan/agent-skills | 0.2.2 | 61 | AelfScan 浏览器数据检索与分析技能。 |
+| awaken-agent-skills | @awaken-finance/agent-kit | 1.2.4 | 11 | Awaken DEX 交易与行情数据技能。 |
+| eforest-agent-skills | @eforest-finance/agent-skills | 0.4.3 | 48 | eForest 代币与 NFT 市场操作技能。 |
+| portkey-ca-agent-skills | @portkey/ca-agent-skills | 1.1.5 | 28 | Portkey CA 钱包注册、认证、Guardian 与转账技能。 |
+| portkey-eoa-agent-skills | @portkey/eoa-agent-skills | 1.2.4 | 21 | Portkey EOA 钱包与资产操作技能。 |
+| tomorrowdao-agent-skills | @tomorrowdao/agent-skills | 0.1.4 | 41 | TomorrowDAO 治理、BP 与资源操作技能。 |
 <!-- SKILL_TABLE_END -->
 
 ## 健康检查

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockchain-forever/aelf-skills",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Discovery, download, and configuration hub for the aelf agent skill ecosystem.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,8 @@
     "catalog:generate:local": "bun run scripts/generate-catalog.ts --include-local-paths --output skills-catalog.local.json --no-readme-sync",
     "bootstrap": "bun run scripts/bootstrap.ts",
     "health:check": "bun run scripts/health-check.ts",
+    "update:check": "bun run scripts/update-check.ts",
+    "update:check:json": "bun run scripts/update-check.ts --json",
     "type-debt:report": "bun run scripts/type-debt-report.ts",
     "test:signer-chain": "bun run scripts/test-signer-chain.ts",
     "readme:check": "bun run scripts/check-readme-sync.ts",

scripts/bootstrap.ts

@@ -5,6 +5,7 @@ import type { SkillCatalogEntry, SkillsCatalog } from './lib/types.ts';
 import { parseCsv, readJsonFile, requireCommand, runCommand } from './lib/utils.ts';
 import { buildCatalog, writeCatalogArtifacts } from './lib/catalog.ts';
 import { printHealthReport, runHealthCheck } from './lib/health.ts';
+import { maybePrintUpdateReminder } from './lib/update-check.ts';
 
 type SourceMode = 'auto' | 'npm' | 'github' | 'local';
 
@@ -372,8 +373,10 @@ function printBootstrapSummary(results: SkillRunResult[]): void {
   }
 }
 
-function main(): void {
+async function main(): Promise<void> {
   try {
+    await maybePrintUpdateReminder();
+
     const options = parseArgs();
     validatePrerequisites(options.source, options.skipInstall);
 
@@ -437,4 +440,4 @@ function main(): void {
   }
 }
 
-main();
+void main();

scripts/generate-catalog.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { buildCatalog, writeCatalogArtifacts } from './lib/catalog.ts';
+import { maybePrintUpdateReminder } from './lib/update-check.ts';
 
 interface CliOptions {
   workspacePath?: string;
@@ -27,8 +28,10 @@ function parseArgs(): CliOptions {
   };
 }
 
-function main(): void {
+async function main(): Promise<void> {
   try {
+    await maybePrintUpdateReminder();
+
     const options = parseArgs();
     const rootDir = process.cwd();
 
@@ -66,4 +69,4 @@ function main(): void {
   }
 }
 
-main();
+void main();

scripts/health-check.ts

@@ -4,6 +4,7 @@ import type { SkillsCatalog } from './lib/types.ts';
 import { readJsonFile, parseCsv, writeJsonFile } from './lib/utils.ts';
 import { buildCatalog, writeCatalogArtifacts } from './lib/catalog.ts';
 import { printHealthReport, runHealthCheck } from './lib/health.ts';
+import { maybePrintUpdateReminder } from './lib/update-check.ts';
 
 interface CliOptions {
   catalogPath: string;
@@ -58,8 +59,10 @@ function ensureCatalog(catalogPath: string): void {
   writeJsonFile(catalogPath, catalog);
 }
 
-function main(): void {
+async function main(): Promise<void> {
   try {
+    await maybePrintUpdateReminder();
+
     const options = parseArgs();
     ensureCatalog(options.catalogPath);
 
@@ -97,4 +100,4 @@ function main(): void {
   }
 }
 
-main();
+void main();