Cleo

🚀 CLEO Claude代碼插件

CLEO Claude代碼插件是一款用於多智能體集成的工具，採用混合架構，結合注入系統和插件系統，為用戶提供靈活的任務管理和終端集成功能。

🚀 快速開始

僅使用注入系統（默認）

# 安裝支持多智能體的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# 設置智能體配置（自動發現已安裝的智能體）
cleo init

# 驗證注入情況
cleo doctor

高級安裝（注入系統 + 插件）

# 安裝帶有Claude代碼插件的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with-plugin

# 設置智能體配置
cleo init

# 驗證注入和插件情況
cleo doctor

✨ 主要特性

• 混合架構：結合注入系統和插件系統，實現多智能體集成。
• 多智能體支持：支持16種以上的智能體，包括Claude、Cursor、Windsurf、Gemini等。
• Claude代碼特定鉤子：插件為Claude代碼提供特定的鉤子，實現自動會話綁定和TTY集成。
• 任務管理：提供全面的任務管理功能，支持多會話和編排。

📦 安裝指南

默認安裝（僅注入系統）

# 安裝支持多智能體的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# 設置智能體配置（自動發現已安裝的智能體）
cleo init

# 驗證注入情況
cleo doctor

高級安裝（注入系統 + 插件）

# 安裝帶有Claude代碼插件的CLEO
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with-plugin

# 設置智能體配置
cleo init

# 驗證注入和插件情況
cleo doctor

💻 使用示例

僅使用注入系統

# 手動啟動會話
cleo session start --scope epic:T1074 --auto-focus

# 使用帶有CLEO_SESSION環境變量的cleo命令
export CLEO_SESSION="session_20260127_123456_abc123"
cleo list --parent T1074
cleo complete T1087

# 結束會話
cleo session end --note "Completed plugin docs"

使用插件

# 啟動會話（手動或通過編排器）
cleo session start --scope epic:T1074 --auto-focus

# Claude代碼啟動 → 插件自動導出CLEO_SESSION
# ✓ CLEO會話已綁定：session_20260127_123456_abc123

# 使用cleo命令（無需手動導出）
cleo list --parent T1074
cleo complete T1087

# 結束會話
cleo session end --note "Completed plugin docs"

📚 詳細文檔

概述

CLEO採用混合方法進行多智能體集成：

架構

主要：注入系統

注入系統通過基於註冊表的自動發現為所有大語言模型智能體提供CLEO任務管理：

• 位置：schemas/agent-registry.json
• 支持的智能體：claude-code、cursor、windsurf、gemini、copilot、roo-code、cline、continue、aider、bolt、replit、lovable、v0、devin等。
• 工作原理：
  1. cleo init自動發現已安裝的智能體。
  2. 將任務管理指令注入到智能體配置文件中。
  3. 智能體通過@~/.cleo/docs/TODO_Task_Management.md引用外部文檔。
  4. 適用於任何支持配置文件注入的智能體。
• 支持的文件：CLAUDE.md、CURSOR.md、.windsurfrules、GEMINI.md等。

可選：插件系統

插件為終端集成添加Claude代碼特定的鉤子：

• 位置：.claude-plugin/
• 功能：會話啟動鉤子，用於自動會話綁定。
• 限制：僅適用於Claude代碼（不可移植到其他智能體）。
• 插件提供的功能：
  • 會話啟動鉤子：通過CLEO_SESSION環境變量將CLEO會話自動綁定到Claude終端。
  • TTY集成：在Claude代碼重啟時實現無縫會話連續性。
• 插件不提供的功能：
  • ❌ 斜槓命令（未來增強功能）
  • ❌ 自定義智能體（未來增強功能）
  • ❌ 可移植到其他智能體（注入系統處理此功能）

何時使用插件

僅使用注入系統（默認） ✓

• 推薦人群：
  • 多智能體工作流（Cursor、Windsurf、Gemini等）
  • 標準Claude代碼使用場景
  • 不需要自動會話綁定的用戶
• 你將獲得：
  • 完整的CLEO任務管理（cleo命令行界面）
  • 多會話支持
  • 編排和子智能體
  • 適用於所有支持的智能體

添加插件（高級） ⚡

• 推薦人群：
  • 重度Claude代碼用戶
  • 多會話高級用戶
  • 需要自動會話綁定的用戶
• 你將獲得：
  • 注入系統的所有功能
  • 額外：會話啟動鉤子，用於自動綁定CLEO_SESSION
  • 額外：支持TTY的會話連續性

插件結構

.claude-plugin/
├── plugin.json           # 插件清單
├── hooks/
│   ├── hooks.json       # 鉤子配置
│   └── scripts/
│       └── session-start.sh   # 會話啟動鉤子實現
└── README.md            # 此文件

plugin.json

插件清單定義功能：

{
  "name": "cleo",
  "version": "0.70.1",
  "capabilities": {
    "task_management": true,
    "multi_session": true,
    "orchestration": true
  },
  "hooks": {
    "enabled": true,
    "directory": "hooks",
    "manifest": "hooks/hooks.json"
  }
}

hooks.json

會話啟動事件的鉤子配置：

{
  "SessionStart": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
      "timeout": 10
    }]
  }]
}

session-start.sh

將活動的CLEO會話自動綁定到Claude終端：

• 功能：
  1. 檢查活動的CLEO會話（.cleo/.current-session）。
  2. 通過cleo session status驗證會話是否活動。
  3. 為終端導出CLEO_SESSION環境變量。
  4. 創建.cleo/.session-env，以便手動導入（如果需要）。
• 退出條件（靜默）：
  • CLEO未安裝
  • 沒有.cleo目錄（不是CLEO項目）
  • 沒有活動會話
  • 會話不活動/已結束

混合架構的優勢

決策樹

你是否僅使用Claude代碼？
├─ 是
│   └─ 你是否需要自動會話綁定？
│       ├─ 是 → 使用 --with-plugin 安裝
│       └─ 否  → 默認安裝（僅注入系統）
└─ 否（多智能體工作流）
    └─ 默認安裝（僅注入系統）

故障排除

插件無法工作

• 症狀：會話啟動鉤子未觸發
• 檢查：
  1. 插件是否安裝：ls .claude-plugin/
  2. 鉤子是否啟用：cat .claude-plugin/plugin.json | jq '.hooks.enabled'
  3. CLEO會話是否活動：cleo session status
  4. Claude代碼版本：插件需要Claude代碼1.0.0及以上版本

會話未自動綁定

• 症狀：Claude代碼啟動後CLEO_SESSION未設置
• 檢查：
  1. 是否存在活動會話：cat .cleo/.current-session
  2. 會話是否活動：cleo session status
  3. 鉤子腳本是否可執行：ls -l .claude-plugin/hooks/scripts/session-start.sh
  4. 手動測試：bash .claude-plugin/hooks/scripts/session-start.sh

注入系統與插件衝突

• 症狀：出現重複的任務管理指令
• 解決方案：無衝突。注入系統和插件是互補的：
  • 注入系統：為智能體提供任務管理文檔
  • 插件：提供終端集成鉤子

兩者可以安全共存。

未來增強功能

• 計劃中的插件功能（v0.70.1中未包含）：
  • 斜槓命令（/cleo add "Task"）
  • 自定義智能體（ct-orchestrator、ct-epic-architect）
  • 智能體間通信（共識協議）
  • Git工作流集成
• 當前狀態：插件僅提供會話啟動鉤子。所有其他功能使用標準命令行界面。

參考資料

• 注入系統：schemas/agent-registry.json
• 設置指南：docs/guides/AGENT-REGISTRATION.md
• 子智能體架構：docs/architecture/CLEO-SUBAGENT.md
• 協議棧：src/protocols/

關鍵洞察：CLEO使用注入系統實現可移植性，使用插件為Claude代碼提供優化。大多數用戶僅需要注入系統。