跳到主要内容

📋 CRD 架构

本文档为开发者提供 Wegent CRD（自定义资源定义）架构的详细技术参考，帮助理解内部结构和实现细节。

⚠️ 术语说明：Team vs Bot​

重要提示： 为避免混淆，请注意代码层面的术语与用户界面显示名称的区别。

代码/CRD 层面用户界面 (中文)说明
Team智能体用户直接使用的 AI 智能体，执行任务的主体
Bot机器人组成智能体的基础组件，是智能体的"工人单元"

简单理解：

  • 机器人 (Bot) = 一个配置好的 AI 工人（包含提示词、运行环境、模型）
  • 智能体 (Team) = 由一个或多个机器人组成的"工作团队"，用户通过智能体来执行任务

🔗 功能与 CRD 映射​

功能相关 CRD说明
对话Chat Shell + Team通过 Chat Shell 直接与 LLM 对话
编码ClaudeCode Shell + Team + Workspace云端编码执行，支持 Git 集成
关注Subscription + Team定时/事件触发的 AI 任务
知识KnowledgeBase + Retriever文档存储和 RAG 检索
定制化Ghost + Bot + Team配置提示词、工具和协作模式

📋 CRD 架构概览​

Wegent 基于 Kubernetes 风格的声明式 API 和 CRD (Custom Resource Definition) 设计模式，提供了一套标准化的框架来创建和管理 AI 智能体生态系统。

核心资源类型​

图标代码名称说明类比
👻Ghost智能体的"灵魂"定义个性和能力
🧠ModelAI 模型配置大脑的配置参数
🐚Shell运行时环境可执行程序容器
🤖Bot完整智能体实例Ghost + Shell + Model
👥Team协作团队多个 Bot 的协作组合
🤝Collaboration协作模式Bot 之间的交互模式
💼Workspace工作环境隔离的代码工作空间
🎯Task任务分配给 Team 的工作单元

资源层级关系​

Ghost (系统提示词 + MCP 服务器 + 技能)
   ↓
Bot (Ghost + Shell + 可选 Model)           ← UI: 机器人
   ↓
Team (多个 Bot 及其角色)                    ← UI: 智能体
   ↓
Task (Team + Workspace) → 子任务

数据库表映射​

⚠️ 重要： Task 和 Workspace 资源存储在单独的 tasks 表中，而不是 kinds 表。

CRD Kind数据库表模型类
Ghost, Model, Shell, Bot, Team, SkillkindsKind
Task, WorkspacetasksTaskResource
Skill Binaryskill_binariesSkillBinary

代码使用示例：

# 对于 Task/Workspace - 使用 TaskResource 模型
from app.models.task import TaskResource
task = db.query(TaskResource).filter(TaskResource.kind == "Task", ...).first()

# 对于其他 CRD (Ghost, Model, Shell, Bot, Team) - 使用 Kind 模型
from app.models.kind import Kind
team = db.query(Kind).filter(Kind.kind == "Team", ...).first()

👻 Ghost - 智能体的灵魂​

Ghost 代表智能体的"灵魂"，定义了智能体的个性、能力和行为模式。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: "You are a professional software developer, skilled in using TypeScript and React to develop frontend applications."
  mcpServers:
    github:
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ghp_xxxxx
      command: docker
      args:
        - run
        - -i
        - --rm
        - -e
        - GITHUB_PERSONAL_ACCESS_TOKEN
        - ghcr.io/github/github-mcp-server
status:
  state: "Available"

🧠 Model - AI 模型配置​

Model 定义了 AI 模型的配置，包括环境变量、模型参数等。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: claude-model
  namespace: default
spec:
  modelConfig:
    env:
      ANTHROPIC_MODEL: "openrouter,anthropic/claude-sonnet-4"
      ANTHROPIC_AUTH_TOKEN: "sk-xxxxxx"
      ANTHROPIC_BASE_URL: "http://xxxxx"
      ANTHROPIC_DEFAULT_HAIKU_MODEL: "openrouter,anthropic/claude-haiku-4.5"
status:
  state: "Available"

🐚 Shell - 运行时环境​

Shell 是智能体运行的容器，指定了运行时环境和支持的模型类型。

Shell 类型​

类型说明使用场景
Chat直接 LLM API（无 Docker）轻量级对话
ClaudeCodeDocker 中的 Claude Code SDK云端编码任务
AgnoDocker 中的 Agno 框架多智能体协作
Dify外部 Dify API 代理Dify 工作流集成

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: claude-shell
  namespace: default
spec:
  runtime: "ClaudeCode"
  supportModel:
    - "openai"
    - "anthropic"
status:
  state: "Available"

🤖 Bot - 机器人（智能体的基础组件）​

术语说明： Bot 在用户界面中显示为"机器人"，是组成智能体(Team)的基础组件。

Bot 是一个完整的智能体实例，结合了 Ghost (灵魂)、Shell (容器) 和 Model (配置)。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: developer-bot
  namespace: default
spec:
  ghostRef:
    name: developer-ghost
    namespace: default
  shellRef:
    name: claude-shell
    namespace: default
  modelRef:
    name: claude-model
    namespace: default
status:
  state: "Available"

👥 Team - 智能体（用户直接使用的 AI 助手）​

术语说明： Team 在用户界面中显示为"智能体"，是用户直接交互和使用的 AI 助手实体。用户创建任务时选择的就是 Team（智能体）。

Team 定义了多个 Bot（机器人）的协作组合，指定了成员角色和协作模式。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Team
metadata:
  name: dev-team
  namespace: default
spec:
  members:
    - name: "developer"
      botRef:
        name: developer-bot
        namespace: default
      prompt: "You are the developer in the team, responsible for implementing features..."
      role: "leader"
    - name: "reviewer"
      botRef:
        name: reviewer-bot
        namespace: default
      prompt: "You are the code reviewer in the team, responsible for reviewing code quality..."
      role: "member"
  collaborationModel: "pipeline"
status:
  state: "Available"

🤝 Collaboration - 协作模式​

Collaboration 定义了 Team 中 Bot 之间的交互模式，类似于工作流。

四种协作模式​

1. Pipeline (流水线)​

顺序执行，前一个 Bot 的输出作为下一个 Bot 的输入。

Developer Bot → Reviewer Bot → Tester Bot → Deployer Bot

2. Route (路由)​

由 Leader 根据任务内容分配给合适的 Bot。

User Query → Leader Bot → {Frontend Bot | Backend Bot | DB Bot}

3. Coordinate (协调)​

Leader 协调多个 Bot 并行工作，汇总结果。

Leader Bot → [Analyst Bot, Data Bot, Report Bot] → Leader Bot (汇总)

4. Collaborate (协作)​

所有 Bot 共享上下文，自由讨论和协作。

[Bot A ↔ Bot B ↔ Bot C] (共享上下文)

💼 Workspace - 工作环境​

Workspace 定义了团队的工作环境，包括代码仓库、分支等信息。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Workspace
metadata:
  name: project-workspace
  namespace: default
spec:
  repository:
    gitUrl: "https://github.com/user/repo.git"
    gitRepo: "user/repo"
    gitRepoId: 12345
    branchName: "main"
    gitDomain: "github.com"
status:
  state: "Available"

🎯 Task - 任务​

Task 是分配给 Team 的可执行工作单元，关联了 Team 和 Workspace。

YAML 配置示例​

apiVersion: agent.wecode.io/v1
kind: Task
metadata:
  name: implement-feature
  namespace: default
spec:
  title: "Implement new feature"
  prompt: "Please implement a user authentication feature with JWT tokens"
  teamRef:
    name: dev-team
    namespace: default
  workspaceRef:
    name: project-workspace
    namespace: default
status:
  state: "Available"
  status: "PENDING"
  progress: 0

🔄 概念关系图​

💡 最佳实践​

1. Ghost 设计​

  • ✅ 明确定义智能体的专业领域
  • ✅ 提供清晰的行为指南
  • ✅ 配置必要的 MCP 工具

2. Bot 组合​

  • ✅ 为不同任务创建专门的 Bot
  • ✅ 复用 Ghost 和 Model 配置
  • ✅ 合理选择 Shell 类型

3. Team 构建​

  • ✅ 选择合适的协作模式
  • ✅ 明确成员角色和职责
  • ✅ 为每个成员提供清晰的任务提示

🔗 相关资源​