T01 Clawbot 指令體系設計

🏠 首頁 📋 開發計劃書 📝 實施工作清單 ⚙️ T02 H5框架搭建

一、指令體系概覽

核心設計原則

H5 為觸發端 — 用戶在 H5 頁面操作，H5 透過 Webhook 向 WorkBuddy 發送結構化指令
Clawbot 為橋樑 — Webhook 接收 H5 請求，路由至 WorkBuddy 處理引擎
JSON 為統一格式 — 所有指令/回應使用 JSON 結構，無需解析自然語言
優先級分流 — 緊急指令（如 OCR、香灸配方）立即處理；普通指令排隊執行
模型路由可擴展 — 預留 OpenClaw / 豆包大模型路由開關

👤 用戶操作 H5

→

📱 H5 封裝 JSON 指令

→

🔗 Webhook 發送

→

🤖 WorkBuddy 處理

→

✅ 回應反饋

二、指令通用格式

所有 H5 → WorkBuddy 指令遵循以下統一格式：

{
  "cmd":        "指令觸發詞（string）",
  "id":         "UUID 請求ID",
  "timestamp":  "ISO8601 時間戳",
  "priority":   1-5,
  "session":    "用戶會話ID",
  "params": {
    // 指令特定參數
  }
}

優先級定義

優先級	數值	說明	處理策略
立即	P0 / 5	OCR掃描、香灸配方緊急處理	同步返回結果
高	P1 / 4	文件歸檔、AI分類	<30秒響應
中	P2 / 3	搜索查詢、索引更新	<2分鐘響應
低	P3 / 2	R2同步、批量處理	排隊執行
背景	P4 / 1	統計報告、數據整理	定時批量

通用回應格式

{
  "ok":         true/false,
  "id":         "對應請求ID",
  "cmd":        "指令觸發詞",
  "timestamp":  "ISO8601",
  "data": {
    // 指令特定回應數據
  },
  "error": {
    "code":    "ERR_XXX",
    "message": "錯誤描述"
  }
}

三、指令完整列表

共計 12 個核心指令，分為四大類：文件操作、AI處理、系統管理、查詢統計

3.1 文件操作類（4指令）

觸發詞	名稱	優先級	功能描述
`file_add`	文件歸檔	P1	上傳文件 → AI識別類型 → 自動命名 → 存入R2 → 索引寫入D1
`file_delete`	文件刪除	P1	刪除R2文件 + 清除D1索引（軟刪除，30天內可恢復）
`file_rename`	文件重命名	P2	AI分析文件名 → 建議規範名 → 用戶確認後更新R2+D1
`file_move`	文件移動	P2	將文件移至目標分類/目錄，更新D1路徑映射

3.2 AI 處理類（5指令）

觸發詞	名稱	優先級	功能描述
`ocr_scan`	OCR 掃描識別	P0	上傳圖片 → OCR識別 → 返回文本（香灸配方、紙質SOP專用）
`ai_classify`	AI 自動分類	P1	分析文件內容 → 匹配D1類別標籤 → 返回分類結果 + 置信度
`ai_tag`	AI 智能標籤	P2	分析文件 → 生成關鍵詞標籤（最多10個）→ 寫入D1索引
`ai_summary`	AI 文件摘要	P3	對長文本/音頻/視頻生成摘要，返回要點列表
`r2_sync`	R2 定時同步	P4	本地文件 ↔ R2存儲桶雙向同步，生成變更日誌

3.3 系統管理類（2指令）

觸發詞	名稱	優先級	功能描述
`model_route`	AI 模型路由	P2	切換默認AI模型（Clawbot / OpenClaw / 豆包大模型），無需重啟
`sync_status`	同步狀態查詢	P4	查詢本地 ↔ R2 ↔ D1 當前同步狀態，返回詳細日誌

3.4 查詢統計類（1指令）

觸發詞	名稱	優先級	功能描述
`search`	智能搜索	P2	在D1索引中全文搜索文件名/標籤/摘要，返回排序結果

四、核心指令詳解

4.1 file_add — 文件歸檔（最高頻）

觸發場景：用戶點擊「上傳文件」，選擇圖片/文檔/音頻/視頻後一鍵歸檔

// H5 → WorkBuddy（請求）
{
  "cmd":       "file_add",
  "id":        "req-20260425-001",
  "timestamp": "2026-04-25T14:30:00+08:00",
  "priority":  4,
  "session":   "sess-abc123",
  "params": {
    "file_name":   "會議錄音_20260425.m4a",
    "file_type":   "audio",        // image | document | audio | video | other
    "file_size":   2048576,        // bytes
    "r2_key":      "uploads/20260425/meeting-001.m4a",
    "labels":      ["會議", "2026-04"],  // 用戶自定義標籤（可選）
    "auto_classify": true          // 是否自動AI分類
  }
}

// WorkBuddy → H5（成功回應）
{
  "ok":      true,
  "id":      "req-20260425-001",
  "cmd":     "file_add",
  "timestamp": "2026-04-25T14:30:03+08:00",
  "data": {
    "d1_id":      "file-d1-20260425-001",
    "r2_url":     "https://r2.example.com/...",  // 簽名下載鏈接
    "tags":       ["會議", "2026-04", "商務"],
    "category":   "會議記錄",
    "confidence": 0.92
  }
}

4.2 ocr_scan — OCR 掃描識別（P0 緊急）

觸發場景：用戶拍攝香灸配方卡片/紙質SOP，即時轉文字

特殊要求：響應時間 <5秒，支援中英文混合、手寫字識別

// H5 → WorkBuddy
{
  "cmd":       "ocr_scan",
  "id":        "req-20260425-ocr-001",
  "timestamp": "2026-04-25T14:35:00+08:00",
  "priority":  5,
  "session":   "sess-abc123",
  "params": {
    "image_key":  "ocr/20260425/recipe-001.jpg",
    "mode":       "formula",       // formula | sop | general
    "lang":       "zh-CN",         // 識別語言
    "save_to_d1": true
  }
}

// WorkBuddy → H5
{
  "ok":      true,
  "id":      "req-20260425-ocr-001",
  "cmd":     "ocr_scan",
  "data": {
    "text":      "艾灸配方：足三里穴，溫灸15分鐘...",
    "confidence": 0.97,
    "entities": [
      { "type": "穴位", "value": "足三里", "pos": [12, 15] },
      { "type": "時長", "value": "15分鐘", "pos": [20, 24] }
    ],
    "d1_id":    "ocr-d1-20260425-001"
  }
}

4.3 ai_classify — AI 自動分類

// H5 → WorkBuddy
{
  "cmd":       "ai_classify",
  "id":        "req-20260425-cls-001",
  "priority":  4,
  "params": {
    "d1_id":      "file-d1-20260425-001",
    "force":      false            // true = 重新分類覆蓋
  }
}

// WorkBuddy → H5
{
  "ok":   true,
  "data": {
    "primary_category": "會議記錄",
    "categories": [
      { "name": "會議記錄",  "score": 0.92 },
      { "name": "商務文檔",  "score": 0.65 },
      { "name": "私人文件",  "score": 0.12 }
    ],
    "tags": ["會議", "決策", "2026-Q2"],
    "reason": "檢測到時間標記、參與者列表、決策結論等結構"
  }
}

4.4 search — 智能搜索

// H5 → WorkBuddy
{
  "cmd":       "search",
  "id":        "req-20260425-search-001",
  "priority":  3,
  "params": {
    "query":     "香灸 配方 足三里",
    "scope":     "all",            // all | tags | filename | content
    "limit":     20,
    "sort":      "relevance"       // relevance | date_desc | date_asc
  }
}

// WorkBuddy → H5
{
  "ok":   true,
  "data": {
    "total":    3,
    "results": [
      {
        "d1_id":      "file-d1-20260424-015",
        "filename":    "香灸配方大全.pdf",
        "tags":       ["香灸", "配方", "中醫"],
        "relevance":  0.95,
        "snippet":    "...足三里穴，主治胃腸疾病..."
      }
    ]
  }
}

4.5 model_route — AI 模型路由（可擴展）

// H5 → WorkBuddy
{
  "cmd":    "model_route",
  "id":     "req-20260425-route-001",
  "params": {
    "provider": "doubao",   // clawbot | openclaw | doubao
    "model":    "doubao-pro"  // 提供商特定模型名
  }
}

// WorkBuddy → H5
{
  "ok":   true,
  "data": {
    "current_provider": "doubao",
    "current_model":   "doubao-pro",
    "status":          "switched"
  }
}

五、Webhook 接口規範

接口端點

POST https://aih5.pages.dev/api/webhook
Content-Type: application/json
X-Session-Key: {session_key}
X-Device-ID: {device_id}

安全驗證

機制	說明
X-Session-Key	H5 登錄後頒發的會話密鑰，過期時間 24小時
X-Device-ID	H5 設備指紋，防止跨設備攻擊
Rate Limit	每IP每分鐘 60 請求；P0 指令限 10次/分鐘
HMAC 簽名	可選：請求體 HMAC-SHA256 校驗，防止篡改

錯誤代碼

代碼	說明	處理建議
`ERR_AUTH`	會話無效/過期	引導重新登錄
`ERR_RATE_LIMIT`	觸發限速	等待後重試
`ERR_FILE_TOO_LARGE`	文件超過限制	提示壓縮或分割
`ERR_OCR_FAILED`	OCR識別失敗	建議重新拍攝
`ERR_R2_UPLOAD`	R2上傳失敗	稍後重試或更換網絡
`ERR_D1_WRITE`	D1寫入失敗	技術團隊排查
`ERR_MODEL_TIMEOUT`	AI模型響應超時	降級或稍後重試

六、D1 索引數據庫 Schema

-- 文件索引表
CREATE TABLE files (
  id          TEXT PRIMARY KEY,       -- UUID
  filename    TEXT NOT NULL,
  file_type   TEXT NOT NULL,          -- image|document|audio|video|other
  r2_key      TEXT NOT NULL,
  size_bytes  INTEGER,
  category    TEXT,
  tags        TEXT,                    -- JSON array
  summary     TEXT,
  confidence  REAL,                   -- AI分類置信度
  created_at  TEXT,
  updated_at  TEXT,
  deleted_at  TEXT                    -- 軟刪除時間戳
);

-- 標籤表
CREATE TABLE tags (
  id         TEXT PRIMARY KEY,
  name       TEXT NOT NULL UNIQUE,
  color      TEXT,
  use_count  INTEGER DEFAULT 0
);

-- 操作日誌表
CREATE TABLE logs (
  id         TEXT PRIMARY KEY,
  file_id    TEXT,
  cmd        TEXT,
  user_id    TEXT,
  status     TEXT,                    -- success|fail|pending
  error_code TEXT,
  created_at TEXT
);

-- 用戶配置表
CREATE TABLE config (
  key         TEXT PRIMARY KEY,
  value       TEXT,
  updated_at  TEXT
);

七、R2 存儲桶結構

r2://aih5-bucket/
├── uploads/               # 用戶上傳文件
│   └── {YYYYMMDD}/
│       └── {uuid}.{ext}
├── ocr/                   # OCR 臨時圖片
│   └── {YYYYMMDD}/
│       └── {uuid}.jpg
├── signed/                # 臨時簽名下載（7天過期）
│   └── {uuid}/
│       └── {filename}
└── backup/                # 定時備份
    └── {YYYYMMDD-HH}/

簽名下載鏈接生成規則

https://aih5.pages.dev/api/download/{r2_key}?expires={timestamp}&sig={hmac}
# 過期時間：默认 7 天（可配置）
# HMAC 密鑰：R2_SECRET_KEY

八、典型時序示例（文件歸檔全流程）

👤 用戶                  H5 App            WorkBuddy          R2 Storage        D1 Database
 |                       |                   |                    |                   |
 |  [1] 選擇文件上傳      |                   |                    |                   |
 |──────────────────────>│                   |                    |                   |
 |                       | [2] 分塊上傳      |                    |                   |
 |                       |───────────────────>                   |                   |
 |                       |                   | [3] 創建R2預簽URL |                   |
 |                       |                   |─────────────────────────────────────────>|
 |                       |                   | [4] 返回預簽URL    |                   |
 |                       |<────────────────────────────────────────────────────────────────|
 |                       | [5] 直接上傳到R2  |                    |                   |
 |                       |─────────────────────────────────────────>                   |
 |                       |                   | [6] Webhook: file_add                    |
 |                       |                   |<─────────────────────────────────────────|
 |                       |                   | [7] AI分類分析      |                   |
 |                       |                   |──────────────────────────────────────────>|
 |                       |                   | [8] 寫入D1索引      |                   |
 |                       |                   |──────────────────────────────────────────>|
 |                       | [9] 返回結果      |                    |                   |
 |<───────────────────────│                   |                    |                   |
 |                       |                   |                    |                   |
 | [10] 顯示文件卡片      |                   |                    |                   |
 | (含標籤/分類/下載鏈)  |                   |                    |                   |

九、Phase 2 預留擴展點

微信小程序外殼：同一套 Webhook 接口，僅需替換 H5 請求端的 Session Key 驗證方式
批量指令：新增 batch 指令，支持一次提交多個操作
異步回調：支援 Webhook 回調 URL，用於長任務（如大文件轉碼）完成通知
團隊共享：新增 share 指令，支持文件跨用戶共享（基於 R2 策略）
版本控制：文件上傳覆蓋時自動保留歷史版本（R2 版本化）

十、T01 完成 → T02 銜接建議

T01 已交付成果

✅ 12 個核心指令定義（觸發詞 / 參數 / 回應 / 優先級）
✅ 指令通用格式（JSON Schema）
✅ D1 數據庫 Schema 設計
✅ R2 存儲桶目錄結構
✅ Webhook 接口規範（含安全驗證）
✅ 典型時序圖

T02 銜接重點

T02 H5 框架搭建時，需在 H5 前端實現：

文件上傳 UI（<input type="file"> + 分塊上傳）
Webhook 客戶端封裝（統一發送 file_add / ocr_scan 等指令）
結果回顯組件（文件卡片、OCR 結果展示）
Session Key 管理（登錄 → 獲取 key → 自動附加到請求頭）

T01 · Clawbot 指令體系設計