自己寫一個
manifest

01四個問題

每個 manifest 都在回答四個問題如果你能用一段話回答，你就能寫一個 manifest

02選一個分類

把 manifest 放到對的資料夾共 10 個分類，挑最接近的一個就好

• ai-ml — 模型推論、embedding、語音轉文字、OCR
• data — SQL、CSV、ETL、schema 解析
• devops — Docker、git、CI/CD、程式碼分析、lint
• media — 影音圖片處理
• web — HTTP、爬蟲、API 工具
• security — 掃描、稽核、加密
• productivity — 檔案、文字轉換、文件工具
• finance — 行情、發票、會計
• science — 單位、統計、計算
• networking — DNS、IP、封包診斷

03完整範本

存成 manifests/<分類>/<你的工具>.json，然後改裡面的欄位

{
  "name": "video-to-gif",
  "version": "1.0.0",
  "category": "media",
  "description": "Convert a video file to an animated GIF with configurable framerate and resolution",

  "intent_triggers": [
    "convert mp4 to gif",
    "turn this video into a gif",
    "make a short looping animation from this clip",
    "export the first 5 seconds of a video as a gif",
    "reduce framerate when generating gif",
    "把影片轉成 GIF",
    "幫我把這段影片做成 gif 動圖"
  ],

  "input_schema": {
    "input":  { "type": "string",  "required": true,  "description": "來源影片檔的路徑" },
    "output": { "type": "string",  "required": true,  "description": "輸出 GIF 的路徑" },
    "fps":    { "type": "integer", "required": false, "default": 15 },
    "width":  { "type": "integer", "required": false }
  },

  "output_schema": {
    "format": "json",
    "fields": ["output_path", "frame_count", "file_size_bytes"]
  },

  "examples": [
    {
      "query": "convert demo.mp4 to a 10-fps gif",
      "params": { "input": "demo.mp4", "output": "demo.gif", "fps": 10 }
    }
  ],

  "error_codes": {
    "1": "Input file not found",
    "2": "ffmpeg not installed"
  },

  "tags": ["video", "gif", "ffmpeg"]
}

04寫好 intent_triggers

這個欄位決定 router 找不找得到你的工具值得花時間

原則

• ≥ 5 條，最好 7–10 條一定範圍內越多越好
• 混合語言主要使用者語言每種至少 2 條中文 + 英文是基本
• 句型要多樣祈使句、陳述句、口語都要有
• 涵蓋邊界情況有特殊參數的工具，讓某些 trigger 帶到那些字
• 不要重複或同義詞「convert video to gif」+「change video to gif」浪費一格

反面教材

• ✗ 五條都是同一句話的小變化
• ✗ 只有單一語言
• ✗ 跟其他工具大量重疊
• ✗ 陷阱詞如果你的工具是 format-fix，不要寫「lint」

05至少寫一個 example

Example 是「自然語言 query → 對應參數」的範本

{
  "query": "convert demo.mp4 to a 10-fps gif",
  "params": { "input": "demo.mp4", "output": "demo.gif", "fps": 10 }
}

當 agent 的意圖跟某個 example 夠接近（cosine ≥ 0.85），router 直接套用該 example 的 params，完全不需要呼叫 LLM這就是「A 路」——零 token、零延遲

06本地驗證

兩步驟檢查：先驗 schema、再驗 routing

# 安裝
pip install clibrary-hub

# 1. Schema 檢查 — manifest 的格式對不對？
python -c "from clibrary_hub import validator; r = validator.validate_file('manifests/media/your-tool.json'); print(r); [print('  ERROR:', e) for e in r.errors]; [print('  WARN: ', w) for w in r.warnings]"

# 2. 建 FAISS index（含新加的 manifest）
clibrary-build-index --manifest-dir ./manifests

# 3. Routing 檢查 — router 實際上會選到你的工具嗎？
python -c "from clibrary_hub import router; print(router.route('幫我把 demo.mp4 做成 gif'))"

如果 schema 過了但 router 沒選到你的工具，多半是 intent_triggers 多樣性不夠或關鍵詞錨點太弱

07送 PR

1. Fork clibrary-hub/cli-tools
2. 開分支，把 manifest 放到對應分類資料夾並 commit
3. 送 PR簡單說明這個工具做什麼、為什麼 agent 會想用它
4. CI 會自動驗證 schema 並檢查名稱是否重複

常見錯誤