/ 目錄 / 演練場 / cocoindex-claude
● 社群 cocoindex-io ⚡ 即開即用

cocoindex-claude

作者 cocoindex-io · cocoindex-io/cocoindex-claude

教導 Claude Code 如何建構 CocoIndex 資料轉換管道——為向量資料庫與知識圖譜提供即時增量處理能力。

CocoIndex 是一個用於 AI 管道的即時資料轉換框架(資料來源 → 轉換 → 向量資料庫/知識圖譜)。此技能將其慣例載入 Claude Code,使模型能撰寫符合 CocoIndex 慣用風格的流程、自訂函式及 CLI/API 指令,而非對不熟悉的函式庫胡亂猜測。

為什麼要用

核心特性

即時演示

實際使用效果

cocoindex-claude-skill.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "cocoindex-claude-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/cocoindex-io/cocoindex-claude",
        "~/.claude/skills/cocoindex-claude"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "cocoindex-claude-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/cocoindex-io/cocoindex-claude",
        "~/.claude/skills/cocoindex-claude"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "cocoindex-claude-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/cocoindex-io/cocoindex-claude",
        "~/.claude/skills/cocoindex-claude"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "cocoindex-claude-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/cocoindex-io/cocoindex-claude",
        "~/.claude/skills/cocoindex-claude"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "cocoindex-claude-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/cocoindex-io/cocoindex-claude",
        "~/.claude/skills/cocoindex-claude"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "cocoindex-claude-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/cocoindex-io/cocoindex-claude",
          "~/.claude/skills/cocoindex-claude"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add cocoindex-claude-skill -- git clone https://github.com/cocoindex-io/cocoindex-claude ~/.claude/skills/cocoindex-claude

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: cocoindex-claude

從本機資料夾建構第一條 CocoIndex 管道並寫入向量資料庫

👤 正在評估 CocoIndex 用於 RAG 情境的開發者 ⏱ ~30 min intermediate

何時使用: 你已閱讀過 CocoIndex 首頁,希望讓 Claude 建立可運作的流程骨架,而非複製貼上教學範例。

前置條件
  • 技能已複製至 ~/.claude/skills/cocoindex-claude — git clone https://github.com/cocoindex-io/cocoindex-claude ~/.claude/skills/cocoindex-claude
  • 已安裝 cocoindex Python 套件 — pip install cocoindex
步驟
  1. 描述管道需求
    Use the cocoindex skill — scaffold a flow that watches ./docs, chunks markdown, embeds with OpenAI, writes to Qdrant.✓ 已複製
    → Claude 產生包含 @cocoindex.flow_def 及正確來源/轉換/匯出呼叫的 flow.py
  2. 執行並驗證
    Now show me the exact CLI commands to build, run, and incrementally update this flow.✓ 已複製
    → 以正確順序列出 cocoindex setup / update / eval 指令

結果: 一個可運作的 flow.py 及執行所需的指令——不再需要猜測 CocoIndex 的裝飾器介面。

注意事項
  • Claude 虛構了 CocoIndex 中不存在的 API — 明確提示「只使用 cocoindex skill 文件中記載的 API」——技能在範圍內時,幻覺現象會大幅降低
搭配使用: filesystem

撰寫自訂的 CocoIndex 轉換函式

👤 正在擴充現有 CocoIndex 流程的工程師 ⏱ ~25 min intermediate

何時使用: 內建轉換功能無法涵蓋你的解析或資料豐富化步驟時。

步驟
  1. 描述轉換需求
    With the cocoindex skill — write a @cocoindex.op.function that takes a PDF path, extracts tables, returns structured rows.✓ 已複製
    → 具備正確型別輸入/輸出的慣用函式簽名
  2. 整合至流程中
    Now plug this into my existing flow at the chunking stage.✓ 已複製
    → 針對現有 flow.py 的差異比較,並在適當位置插入新的 op

結果: 一個符合 CocoIndex 增量處理語意的自訂轉換函式。

注意事項
  • 函式回傳非確定性輸出,破壞增量處理機制 — 技能會提醒 Claude 轉換函式必須是純函式——若遇到此問題,請重新閱讀增量處理章節

組合

與其他 MCP 搭配,撬動十倍槓桿

cocoindex-claude-skill + filesystem

讓 Claude 實際將 flow.py 寫入磁碟,而非僅在對話中顯示

Scaffold the CocoIndex flow and save it to ./pipelines/docs_to_qdrant.py.✓ 已複製
cocoindex-claude-skill + postgres

將 CocoIndex 輸出導入 Postgres 向量儲存庫,並在同一個工作階段中進行查詢

Build the flow targeting pgvector, then run a retrieval query against it.✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
scaffold_flow source type + sink type + transform steps 建立新管道時使用 0
write_custom_op function intent + input/output types 內建轉換功能不足時使用 0
cli_guidance task (setup / update / eval / drop) 不確定應完整重建還是進行增量更新時使用 0

成本與限制

運行它的成本

API 配額
None
每次呼叫 Token 數
適中——技能僅在相關時才載入參考資料
費用
免費——技能為本機檔案
提示
CocoIndex 本身免費;費用來自你所設定的嵌入模型與向量資料庫,而非此技能本身。

安全

權限、密鑰、影響範圍

憑證儲存: 無需憑證——純提示詞運作
資料出站: 技能本身不傳出任何資料。你的管道會呼叫你自行設定的嵌入/資料庫服務。

故障排查

常見錯誤與修復

Skill not invoked when you ask about CocoIndex

明確說「use the cocoindex skill」,或確認技能已安裝於 ~/.claude/skills/cocoindex-claude。

驗證: ls ~/.claude/skills/cocoindex-claude/SKILL.md
SKILL.md frontmatter wrong

開啟檔案並確認 name / description 欄位已填寫完整。若不完整請重新複製。

驗證: head ~/.claude/skills/cocoindex-claude/SKILL.md
Wrong trigger keywords — Claude writes generic Python instead of CocoIndex

明確提及 CocoIndex,或說「scaffold a cocoindex flow_def」。

替代方案

cocoindex-claude 對比其他方案

替代方案何時用它替代權衡
LlamaIndex skills你需要 LlamaIndex 的檢索抽象層,而非 CocoIndex 以轉換為核心的模型思維模型不同——LlamaIndex 以檢索為優先,CocoIndex 以管道為優先
Hand-written Python你只需要一次性的資料處理,不需要增量狀態管理無增量重建機制,亦無框架慣例可循

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills