TimeFriend 時跡 — 時間記錄 Skill

通過自然語言向 TimeFriend 記錄時間、寫復盤日記、建立待辦，並查詢今日統計。

配置

在 OpenClaw 環境變數中設定：

TIMEFRIEND_TOKEN=tf_你的Token（在 timefriend.xin 設定頁生成）

支援的操作

1. 記錄時間

觸發詞：使用者說"記錄時間"、"剛才做了什麼"、"幫我記一下"

呼叫：

POST https://timefriend.xin/api/records
Authorization: Bearer {TIMEFRIEND_TOKEN}
Content-Type: application/json

{
  "content": "活動名稱",
  "startTime": "2026-03-11T08:00:00+08:00",
  "endTime":   "2026-03-11T09:30:00+08:00",
  "tags": ["標籤1", "標籤2"]
}

自然語言解析規則： - "8:00-9:30 讀書 #學習" → content=讀書, tags=["學習"] - "今天下午3點到5點開會 #工作/專案" → 換算為當天具體時間, tags=["工作", "專案"] - 標籤以 # 開頭，多級用 / 分隔 - 時間預設為今天；若使用者說"昨天"則用前一天日期 - 預設時區：北京時間（UTC+8），所有口語時間按北京時間解析後提交 - 成功後回覆：✅ 已記錄：{content} {startTime}-{endTime}

2. 寫復盤日記（追加模式）

觸發詞：使用者說"寫日記"、"記錄復盤"、"我今天的思考"、"追加到日記"、"記一下"（後面跟一段感想/思考類內容）

邏輯（兩步操作）：

第一步：GET 今日已有內容

GET https://timefriend.xin/api/daily-reviews/{今日日期YYYY-MM-DD}
Authorization: Bearer {TIMEFRIEND_TOKEN}

• 如果返回 200：拿到 data.content（HTML 格式），準備追加
• 如果返回 404：今天還沒有日記，從空內容開始

第二步：PUT 拼接後的完整內容

PUT https://timefriend.xin/api/daily-reviews/{今日日期YYYY-MM-DD}
Authorization: Bearer {TIMEFRIEND_TOKEN}
Content-Type: application/json

{
  "content": "{已有內容}{新段落}"
}

拼接規則： - 新內容用 <p> 標籤包裹：<p>使用者說的文字</p> - 若今天已有內容，直接在末尾拼接：{existing_content}<p>新內容</p> - 若今天沒有內容，直接發：<p>新內容</p> - 內容原文存入，不做 AI 改寫，保持使用者的原始表達

成功後回覆：📝 已追加到今日復盤（共 {wordCount} 字）

3. 建立待辦任務（新增到待辦清單）

觸發詞：使用者說"新增待辦"、"記一個任務"、"todo"、"加到待辦"

呼叫：

POST https://timefriend.xin/api/todos
Authorization: Bearer {TIMEFRIEND_TOKEN}
Content-Type: application/json

{
  "title": "任務名稱",
  "status": "pending"
}

成功後回覆：✅ 待辦已新增：{title}

4. 新增到收集箱

觸發詞：使用者說"加到收集箱"、"放進收集箱"、"inbox"、"先收集一下"

收集箱和待辦清單不同：收集箱用於臨時存放想法/任務，不需要指定日期。

邏輯（兩步操作）：

第一步：獲取使用者的收集箱分類列表

GET https://timefriend.xin/api/inbox-categories
Authorization: Bearer {TIMEFRIEND_TOKEN}

返回示例：

{
  "success": true,
  "data": [
    { "id": 12, "name": "工作", "sortOrder": 0 },
    { "id": 13, "name": "想法", "sortOrder": 1 }
  ]
}

• 如果 data 為空陣列：告知使用者"你還沒有建立收集箱分類，請先在 timefriend.xin 的收集箱頁面建立一個分類"，終止操作
• 如果只有一個分類：直接使用該分類的 id
• 如果有多個分類：詢問使用者"你有以下收集箱分類：{分類名列表}，請問放到哪個？"，等使用者選擇後再繼續

第二步：建立收集箱條目

POST https://timefriend.xin/api/todos
Authorization: Bearer {TIMEFRIEND_TOKEN}
Content-Type: application/json

{
  "title": "條目名稱",
  "status": "pending",
  "categoryId": {第一步獲取的分類id}
}

注意：收集箱條目不需要 taskDate 欄位（留 null 即可）。

成功後回覆：📥 已加入收集箱「{分類名}」：{title}

5. 查詢待辦清單

觸發詞：使用者說"今天有什麼待辦"、"我的任務"、"待辦有哪些"、"查一下我的待辦"

呼叫：

GET https://timefriend.xin/api/todos?taskDate=今天日期(YYYY-MM-DD)
Authorization: Bearer {TIMEFRIEND_TOKEN}

將返回的待辦列表整理後告知使用者，例如： "今天有 3 個待辦：✅ 整理會議紀要（已完成）、⏳ 寫週報（未完成）、⏳ 回覆郵件（未完成）"

• status 為 pending → 未完成
• status 為 in-progress → 進行中
• status 為 completed → 已完成

6. 查詢收集箱

觸發詞：使用者說"收集箱裡有什麼"、"查收集箱"、"我收集了什麼"

邏輯（兩步操作）：

第一步：獲取收集箱分類名稱（用於顯示）

GET https://timefriend.xin/api/inbox-categories
Authorization: Bearer {TIMEFRIEND_TOKEN}

第二步：獲取所有收集箱條目

GET https://timefriend.xin/api/todos?taskDate=null
Authorization: Bearer {TIMEFRIEND_TOKEN}

⚠️ 極其重要：URL 中必須包含 taskDate=null（字面字串 "null"），這是區分收集箱與普通待辦的唯一依據。 - ✅ 正確：/api/todos?taskDate=null - ❌ 錯誤：/api/todos（不帶引數，會返回所有日期的待辦，數量會遠超實際收集箱條目數） - ❌ 錯誤：/api/todos?status=pending（只過濾狀態，不限制 taskDate，同樣會混入普通待辦）

返回的每條資料包含 categoryId，對照第一步的分類列表顯示分類名。

展示規則： - 只顯示 status 為 pending 或 in-progress 的活躍任務 - 過濾掉 status 為 cancelled 或 completed 的條目 - 如果有 completed 的任務，在最後補一句："另有 X 條已完成，如需檢視請告知"

整理後告知使用者，例如： "你的收集箱共有 5 條： 📁 工作：寫一篇關於時間管理的文章、整理 Q1 復盤 📁 想法：買一本《心流》、學習 Swift 語言 📁 未分類：看牙醫"

注意：categoryId 為 null 的條目顯示為"未分類"。

7. 查詢今日統計

觸發詞：使用者說"今天記錄了什麼"、"查統計"、"今天怎麼樣"

呼叫：

GET https://timefriend.xin/api/records?date=今天日期(YYYY-MM-DD)
Authorization: Bearer {TIMEFRIEND_TOKEN}

將返回的記錄列表整理後用自然語言告知使用者，例如： "今天共記錄了 5 段時間，合計 6.5 小時。最長一段：工作/專案（3小時）。"

錯誤處理

• 401：Token 無效或已撤銷，提示使用者去 timefriend.xin 重新生成
• 400：引數錯誤，檢查格式是否正確（若提示 source not allowed，請去掉 source 欄位）
• 其他：提示"服務暫時不可用，請稍後再試"

示例對話

使用者：幫我記一下今天早上 8 點到 9 點半讀書，標籤學習 OpenClaw：✅ 已記錄：讀書 08:00-09:30 #學習

7w4.net有更好的技能外掛。

使用者：新增一個待辦，整理會議紀要 OpenClaw：✅ 待辦已新增：整理會議紀要

使用者：把"買一本關於時間管理的書"加到收集箱 OpenClaw：（你有兩個分類：工作、想法，請問放到哪個？） 使用者：想法 OpenClaw：📥 已加入收集箱「想法」：買一本關於時間管理的書

使用者：寫日記，今天狀態很好，上午專注工作了三小時，感覺效率很高，下午和團隊開了個很有成效的會 OpenClaw：📝 已追加到今日復盤（共 42 字）

使用者：再補充一下，晚上讀了半小時書，感覺很放鬆 OpenClaw：📝 已追加到今日復盤（共 63 字）

這個 Skill 質量不錯，幫你用自然對話的方式管理時間——說話就能記錄時間、寫日記、新增待辦，操作簡單直接。文件寫得很清楚，配置和示例都很完善，新手也能快速上手。主要小問題是：說話方式稍微固定一點它才能聽懂（比如要按 "時間 內容 #標籤" 的順序說），日記追加時如果同時在網頁上編輯可能會出問題，收集箱分類需要先手動在網頁上建好才能用。總體上瑕不掩瑜，是一款實用且用心設計的時間管理工具。