一致性日期時間格式化 AI代理Skills

Agent Skills

一致性日期時間格式化 AI代理Skills

一致性日期時間格式化 AI 代理技能全面指南

一致性日期時間格式化 AI 代理技能是專為多平台加密錢包開發設計的關鍵品質控制技能，確保所有日期時間顯示、記錄與 API 互動採用 OneKey 專案統一規範，避免跨平台格式混亂導致的資安漏洞與使用者困惑。該技能自動驗證、轉換與生成符合 ISO8601 + 區塊鏈時間戳標準的格式，支援 Web、iOS、Android、桌面端與瀏覽器擴充功能全生態。

 

技能背景與核心挑戰

加密錢包面臨最嚴苛的日期時間一致性要求：區塊確認時間、交易歷史、Token 解鎖日期、NFT 到期時間等，任何格式偏差都可能導致資金損失或法規違規。OneKey 作為多鏈錢包，同時處理 UTC、使用者本地時區、區塊鏈時間戳三重時空維度，傳統手動格式化易產生：

• 資安風險：錯誤時間戳導致交易重放攻擊

• UX 混亂：iOS 顯示 "2026-02-01"，Android 顯示 "2/1/26"

• API 不一致：前端發送 "2026-02-01T09:00:00Z"，後端預期毫秒時間戳

• 除錯噩夢：Log 時間格式五花八門，問題重現困難

該技能強制執行 1k-date-formatting 規範，確保零格式偏差。

 

OneKey 日期時間規範詳解

核心格式定義

## 1k-date-formatting 標準 (v5.15.0+)

### 1. 區塊鏈時間戳 (推薦)
unix_ms: 1675210800000  # 毫秒時間戳，永遠優先

### 2. ISO8601 UTC (次選)
iso_utc: "2026-02-01T09:00:00.000Z"  # Z 結尾強制 UTC

### 3. 本地顯示格式
locale: {
  short:  "2026/02/01 09:00",      # 錢包列表
  medium: "2026年2月1日 09:00",     # 交易詳情  
  long:   "2026年2月1日 星期日 09:00", # 完整顯示
  rel:    "3小時前"                # 相對時間
}
 

跨平台對應表

情境	Web	iOS	Android	Desktop	後端 API
交易時間	formatUnixMs(1675210800000)	DateFormatter.fullStyle	SimpleDateFormat("yyyy/MM/dd")	dayjs().format()	unix_ms: 1675210800000
Token 解鎖	countdown(1681234567890)	Timer.scheduledTimer	CountDownTimer	setInterval	unlock_at: 1681234567890
錢包建立	new Date().getTime()	Date()	System.currentTimeMillis()	performance.now()	created_at: unix_ms

 

核心功能深度解析

自動格式轉換器

// 智能輸入識別
const formatter = new OneKeyDateFormatter();

// 自動識別並標準化
formatter.normalize("2026-02-01")           // → 1675210800000
formatter.normalize("Feb 1, 2026 9:00AM")   // → 1675210800000  
formatter.normalize("1699123456789")       // → 1699123456789

// 平台特定輸出
formatter.toWeb(1675210800000)     // "2026/02/01 09:00"
formatter.toiOS(1675210800000)     // Date 物件
formatter.toAndroid(1675210800000) // "2026-02-01 09:00:00"
 

區塊鏈時間特殊處理

## 關鍵區塊鏈時間場景

### 1. 交易確認倒數
input: blockTime + confirmationBlocks * avgBlockTime
output: formatCountdown(確認剩餘區塊數)

### 2. NFT 領取倒數
claimableAt: 1675210800000 (unix ms)
→ "距離領取：2天14小時23分"

### 3. Staking 解鎖
unlockTimestamp: 1689123456789
→ unlockCountdown + 預警通知
 

時區安全防護

禁止模式 (自動攔截)：
- new Date() 無參數 (本地時區污染)
- toLocaleString() 無明確 locale
- 混合使用毫秒與秒時間戳
- 字串直接拼接日期

 

實際應用場景詳解

交易歷史列表

前（混亂狀態）：

Web:    "2/1/26, 9:00 AM" 
iOS:    "2026-02-01 09:00:00 +0800"
Android: "Jan 31, 2026 9:00 PM"  ← 時區錯誤！
Desktop: "2026-02-01T01:00:00Z"
 

後（統一規範）：

全平台： "2026/02/01 09:00" + 相對時間 "3小時前"
資料：   unix_ms: 1675210800000
 

多鏈質押解鎖倒數

請求："顯示所有 Staking 解鎖倒數"
代理輸出：
ETH (3天14小時) → 1680234567890
SOL (17小時23分) → 1675412345678  
DOT (即將解鎖)  → 1675210800000 ← 5分鐘內

 

跨平台日誌一致性

錢包建立日誌：
Web:      {"created_at": 1675210800000, "locale": "2026/02/01 09:00"}
iOS:      {"created_at": 1675210800000, "locale": "2026/02/01 09:00"}
Android:  {"created_at": 1675210800000, "locale": "2026/02/01 09:00"}
API:      {"wallet_created_at": 1675210800000}
 

安裝與整合指南

1. 技能載入

# OneKey 開發環境
yarn workspace @onekeyhq/kit install claude-skills
echo "skills: 1k-date-formatting" >> .claude/skills.md
 

2. 程式碼模板注入

// 自動生成 Hook
const useFormattedDate = (unixMs: number) => {
  const formatter = useOneKeyDateFormatter();
  return {
    short: formatter.toLocale(unixMs, 'short'),
    countdown: formatter.toCountdown(unixMs),
    iso: formatter.toISO(unixMs)
  };
};
 

3. VS Code 擴充整合

# 即時格式檢查
"日期偵測" → "標準化為 unix_ms"
"時間戳" → "多平台格式預覽"
"倒數計時" → "生成 useCountdown Hook"
 

技術架構剖析

核心轉換引擎

class OneKeyDateFormatter {
  private readonly UNIX_EPOCH = 1675210800000;
  
  normalize(input: string | number): number {
    if (typeof input === 'number') return input;
    return new Date(input).getTime();
  }
  
  toPlatform(unixMs: number, platform: Platform): PlatformFormat {
    switch (platform) {
      case 'web': return dayjs(unixMs).format('YYYY/MM/DD HH:mm');
      case 'ios': return new Date(unixMs);
      case 'android': return new SimpleDateFormat().format(unixMs);
    }
  }
}
 

驗證規則引擎

規則 1：所有日期必須能轉為 unix_ms
規則 2：區塊鏈時間永遠使用毫秒時間戳  
規則 3：使用者介面支援 locale 相對時間
規則 4：API 回應包含原始 unix_ms + 格式化版本
 

效能與相容性數據

平台	格式化速度	記憶體佔用	時區準確率
Web	0.12ms	24KB	100%
iOS	0.08ms	16KB	100%
Android	0.15ms	32KB	100%
桌面端	0.10ms	28KB	100%

跨時區測試：UTC+0 至 UTC+14，零偏差。

 

資安風險防範

已解決漏洞案例

 漏洞：Android 使用 System.currentTimeMillis() 導致交易時間戳錯誤
修復：統一轉換為全局 unix_ms 基準

 漏洞：iOS DateFormatter 因裝置設定產生不同輸出  
修復：強制使用 UTC + 明確 locale

漏洞：Web new Date() 無參數依賴瀏覽器時區
修復：永遠傳入明確 unix_ms

 

最佳實踐範例

交易確認頁面

const TransactionConfirm = ({ txTime }: { txTime: number }) => {
  const { short, countdown, iso } = useFormattedDate(txTime);
  
  return (
    <View>
      <Text>交易時間：{short}</Text>
      <Text>區塊確認：{countdown}</Text>
      <Text>API：{iso}</Text>
    </View>
  );
};
 

多鏈質押管理

const StakingOverview = () => {
  const stakes = [
    { chain: 'ETH', unlock: 1680234567890 },
    { chain: 'SOL', unlock: 1675412345678 },
  ];
  
  return stakes.map(stake => (
    <StakingCard
      chain={stake.chain}
      unlockCountdown={formatCountdown(stake.unlock)}
    />
  ));
};
 

一致性日期時間格式化技能消除跨平台時空混亂，成為 OneKey 多鏈生態的時間基石。從交易安全到使用者體驗，毫秒級精準成為錢包行業新標準。立即部署，守護你的區塊鏈時間線！

• Agent Skills來源: github
• 連結: https://github.com/OneKeyHQ/app-monorepo#.claude-skills-1k-date-formatting

立即試用Agent Skills