YAML 定义格式

English | 简体中文

本文档详细说明了 Wegent 平台中各个核心概念的 YAML 配置格式。每个定义都遵循 Kubernetes 风格的声明式 API 设计。

👻 Ghost

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

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: |
    You are a senior software engineer, proficient in Git, GitHub MCP, branch management, and code submission workflows. You will use the specified programming language to generate executable code and complete the branch submission and MR (Merge Request) process.
  baseGhostRef:
    name: system-default-ghost
    namespace: default
    user_id: 0
  mcpServers:
    github:
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ghp_xxxxx
      args:
        - run
        - -i
        - --rm
        - -e
        - GITHUB_PERSONAL_ACCESS_TOKEN
        - -e
        - GITHUB_TOOLSETS
        - -e
        - GITHUB_READ_ONLY
        - ghcr.io/github/github-mcp-server
      command: docker

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Ghost 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.systemPrompt`	string	是	定义智能体个性和能力的系统提示词
`spec.baseGhostRef`	object	否	作为通用能力基线的 Ghost 引用，只支持一层继承
`spec.mcpServers`	object	否	MCP 服务器配置,定义智能体的工具能力
`spec.skills`	array	否	关联的 Skill 名称列表,例如 `["skill-1", "skill-2"]`

baseGhostRef 包含 name、namespace 和 user_id。运行时只继承基础 Ghost 的 MCP、Skills、预加载 Skills 和插件；当前 Ghost 的同名配置优先，当前 Ghost 的 systemPrompt 始终保留。系统会先合并配置，再执行一次模型请求，不会分别调用两个 Ghost。嵌套的 baseGhostRef 不受支持。

业务方 MCP 服务器身份校验

当 spec.mcpServers 配置的是业务方提供的远程 MCP 服务器时，业务方可以用 Wegent 在出站请求中注入的任务 token 校验当前用户。在 server 的 headers 里配置 ${{task_token}} 占位符，Wegent 构建请求时会把它替换为签发的任务 token：

spec:
  mcpServers:
    business:
      type: streamable-http
      url: https://mcp.business.example.com/mcp
      headers:
        Authorization: "Bearer ${{task_token}}"

任务 token 绑定当前任务（默认 24 小时）。业务方收到请求后，可用同一个 Authorization: Bearer <token> 头调用 GET /api/external/mcp-identity/userinfo 校验并获取当前用户基本信息（id、user_name、email）；接口不会返回 git 凭据。

✨ Skill

Skill 是 Claude Code 的能力扩展包,包含可执行代码和配置。Skills 以 ZIP 包形式上传,任务启动时自动部署到 ~/.claude/skills/ 目录。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Skill
metadata:
  name: python-debugger
  namespace: default
spec:
  description: "Python 调试工具,支持断点和变量检查"
  version: "1.0.0"
  author: "WeCode Team"
  tags: ["python", "debugging", "development"]
status:
  state: "Available"
  fileSize: 2048576
  fileHash: "abc123def456..."

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Skill 的唯一标识符(用于 Ghost 的 `spec.skills` 字段)
`metadata.namespace`	string	是	命名空间,通常为 `default`
`spec.description`	string	是	Skill 功能描述(从 SKILL.md frontmatter 提取)
`spec.version`	string	否	版本号(建议使用语义化版本)
`spec.author`	string	否	作者名称或组织
`spec.tags`	array	否	分类标签,例如 `["python", "debugging"]`
`status.state`	string	是	Skill 状态: `Available` 或 `Unavailable`
`status.fileSize`	integer	否	ZIP 包大小(字节)
`status.fileHash`	string	否	ZIP 包的 SHA256 哈希值

ZIP 包要求

Skills 必须以 ZIP 包形式上传,包含:

SKILL.md(必需): Skill 文档,包含 YAML frontmatter
其他文件: 脚本、配置、资源等

SKILL.md 格式:

---
description: "您的 Skill 描述"
version: "1.0.0"
author: "您的名字"
tags: ["标签1", "标签2"]
---

# Skill 文档

详细说明这个 Skill 的功能...

在 Ghost 中使用 Skills

通过在 spec.skills 数组中添加 Skill 名称来关联:

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: "你是一位资深开发工程师..."
  mcpServers: { ... }
  skills:
    - python-debugger
    - code-formatter

当使用此 Ghost 启动任务时,Executor 会自动下载并部署这些 Skills 到 ~/.claude/skills/ 目录。

🧠 Model

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

定义 ClaudeCode Model 完整配置示例

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: ClaudeSonnet4
  namespace: default
spec:
  isVisible: true
  allowedUsersEnabled: true
  allowedUsers: ["alice", "bob"]
  modelGroup: "主分组"
  modelSubGroup: "快速"
  capability: "响应快，适合日常问答和简单任务"
  modelConfig:
    env:
      ANTHROPIC_MODEL: "openrouter,anthropic/claude-sonnet-4"
      ANTHROPIC_BASE_URL: "http://xxxxx"
      ANTHROPIC_AUTH_TOKEN: "sk-xxxxxx"
      ANTHROPIC_DEFAULT_HAIKU_MODEL: "openrouter,anthropic/claude-haiku-4.5"

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Model 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.isVisible`	boolean	否	公共模型是否出现在普通用户的模型选择列表中，默认 `true`；设为 `false` 不影响已有引用和运行时解析
`spec.allowedUsers`	array	否	公共模型的用户名白名单；仅在 `allowedUsersEnabled` 为 `true` 时生效。开关关闭时列表保留但不限制访问
`spec.allowedUsersEnabled`	boolean	否	白名单模式显式开关；设为 `true` 时严格按 `allowedUsers` 控制，名单为空则所有用户不可用；为 `false`/缺省时是普通公共模型，`allowedUsers` 被忽略
`spec.modelGroup`	string	否	模型选择器使用的一级展示分组
`spec.modelSubGroup`	string	否	`spec.modelGroup` 下的二级展示分组
`spec.capability`	string/object	否	模型名称下展示的能力与适用场景说明；已发布模型使用发布信息对象的 `description` 字段。省略或留空时只显示名称，不显示真实模型 ID
`spec.modelConfig`	object	是	模型配置对象
`spec.modelConfig.env`	object	是	环境变量配置
`spec.modelConfig.ui`	object	否	Wework 模型选择器展示、默认模型和推理强度配置。
`spec.modelConfig.visionSidecarModel`	object	否	显式引用处理图片的模型；省略时不启用视觉委托。
`spec.protocol`	string	否	上游协议（如 `openai`、`openai-responses`、`claude`）。省略时从 `env.model` 推断。
`spec.apiFormat`	string	否	上游 API 格式（如 `responses`、`chat/completions`）。省略时由 `spec.protocol` 推导。
`spec.isWeworkAvailable`	boolean	否	是否将该模型分发到 wework 桌面客户端。

Wework 模型选择器配置

决策模型设置 spec.modelType: decision，并显式选择 spec.protocol: systemone 或 openai，不设置对话用途的 apiFormat。地址、模型 ID 和凭证仍放在 spec.modelConfig.env，启用 isWeworkAvailable 后可在智能判定工作台中选择。详见决策模型与智能判定工作台。

云端模型可以通过 modelConfig.ui 下发模型选择器元数据。默认模型应设置 defaultModel: true，并用 reasoningEfforts 和 defaultReasoningEffort 声明自身支持的推理强度。默认模型还可以通过 sliderModelsConfig.presets 下发多套具名模型集。所有仍有可用档位的 preset 都会展示， defaultPreset 指定默认激活的模型集。

每个 preset 必须提供稳定唯一的 name、第一行展示文案 label 和有序的 models，还可以用 description 配置第二行说明。未配置 description 时，默认 preset 回退显示“推荐模型集”，其他 preset 回退显示“模型集”。 models 中的 modelName 对应 Model 资源名或模型 ID。存在同名资源时，可同时提供 modelType、namespace 和 resourceUserId 组成完整资源身份。preset 展示在所属的“云端模型”等一级来源分组下，位于模型家族二级分组之前。条目省略 reasoningEffort 和 reasoningEfforts 时，只选择模型，不设置推理强度；模型无需声明推理强度。显式指定强度时，目标模型需支持对应强度，建议通过自身的 modelConfig.ui.reasoningEfforts 声明。不可见、不可用的模型以及不受支持的强度会从 preset 中移除；裁剪后仍有有效档位时继续展示该 preset，只有没有任何有效档位时才隐藏。

spec:
  isWeworkAvailable: true
  modelConfig:
    env:
      model: openai
      model_id: cloud-sol-upstream
    ui:
      family: cloud-openai
      modelLabel: Cloud Sol
      defaultModel: true
      reasoningEfforts: [low, medium, high]
      defaultReasoningEffort: medium
      sliderModelsConfig:
        defaultPreset: recommended
        presets:
          - name: recommended
            label: 推荐
            description: 日常推荐
            models:
              - modelName: cloud-luna
                reasoningEffort: high
              - modelName: cloud-sol
                reasoningEfforts: [low, medium, high]
          - name: quality
            label: 高质量
            description: 更重视质量
            models:
              - modelName: cloud-terra
                reasoningEfforts: [medium, high]

视觉委托模型引用

纯文本模型可以在 modelConfig.visionSidecarModel 中显式引用另一个能读图的模型。引用必须使用 Backend 授权模型列表返回的完整资源身份和 apiFormat。该引用即权威来源：Wework 只校验引用本身的结构，目标模型的存在性与访问权限由 Backend 的 LLM 网关在调用时依据同一组身份 Header 解析和鉴权，因此引用一个未声明 supportsImage 或未分发到 wework 的模型同样生效。Wework 不会根据登录状态或模型名称自动选择默认视觉模型。引用结构非法时主模型保持纯文本，不做图片预处理；引用指向的模型不存在或无法读图时，该图片会被替换为明确的失败说明文本，原始图片不会泄漏给纯文本主模型。

Wegent Web 的视觉模型下拉框只列出声明了 modelCapabilities.supportsImage: true 的候选模型，因此建议给能读图的模型补齐该字段。若已有引用的目标不在候选列表中，下拉框会保留该引用并标注为当前不可选，保存模型不会丢弃它。

apiFormat 必须与被引用模型实际使用的上游协议一致，可取 openai-responses、openai-chat-completions 或 anthropic-messages。多数 Model CRD 只声明 spec.modelConfig.env.model，此时协议由该字段推断（claude 对应 Anthropic Messages，openai 对应 OpenAI Chat Completions）。

spec:
  protocol: openai-responses
  apiFormat: responses
  modelConfig:
    env:
      model: openai
      model_id: deepseek-v4-pro
      base_url: https://example.com/v1
      api_key: ${WECODE_USER_API_KEY}
    visionSidecarModel:
      modelName: openai-gpt-5.6-luna
      modelType: public
      namespace: default
      resourceUserId: 0
      apiFormat: openai-responses

字段	类型	必填	说明
`modelName`	string	是	被引用 Model 的 `metadata.name`。
`modelType`	string	是	资源来源：`public`、`user` 或 `group`。
`namespace`	string	是	被引用 Model 的命名空间。
`resourceUserId`	integer	是	被引用 Model 的资源所有者 ID。
`apiFormat`	string	是	`openai-responses`、`openai-chat-completions` 或 `anthropic-messages`。

模型选择器分组

模型选择器会按 modelGroup → modelSubGroup → 模型进行展示。这两个字段保存在 spec 中，而不是 metadata.labels，因此分组属于 Model 资源定义的一部分。未设置分组字段的模型会展示在默认的未分组/未分类分组中。分组只影响展示与搜索，不改变模型协议、凭据、权限或运行时选择逻辑。

ClaudeCode常用环境变量

变量名	说明	示例值
`ANTHROPIC_MODEL`	主要模型配置	`openrouter,anthropic/claude-sonnet-4`
`ANTHROPIC_BASE_URL`	API 基础 URL	`http://xxxxx`
`ANTHROPIC_AUTH_TOKEN`	认证令牌	`sk-xxxxxx`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	快速模型配置	`openrouter,anthropic/claude-haiku-4.5`

🐚 Shell

Shell 定义了智能体的运行环境，指定了运行时类型、基础镜像和支持的模型。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: ClaudeCode
  namespace: default
  labels:
    type: local_engine
spec:
  shellType: ClaudeCode
  supportModel: []
  baseImage: ghcr.io/wecode-ai/wegent-base-python3.12:1.0.1
status:
  state: Available

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Shell 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`metadata.labels`	object	否	分类标签，如 `type: local_engine` 或 `type: external_api`
`spec.shellType`	string	是	Shell 类型，如 `ClaudeCode`、`Agno`、`Dify`
`spec.supportModel`	array	否	支持的模型类型列表
`spec.baseImage`	string	否	本地引擎 Shell 的 Docker 基础镜像（`local_engine` 类型必填）
`status.state`	string	否	Shell 状态：`Available` 或 `Unavailable`

Shell 类型

类型	标签	说明
`ClaudeCode`	`local_engine`	Claude Code 运行时，需要 `baseImage`
`Agno`	`local_engine`	Agno 运行时，需要 `baseImage`
`Dify`	`external_api`	Dify 外部 API 运行时，不需要 `baseImage`

标签说明

标签	可选值	说明
`type`	`local_engine`, `external_api`	表示 Shell 是本地运行还是连接外部 API

🖥 Device

Device 定义可执行任务的设备。设备记录通常由本地 executor、云设备服务或远程 Docker 设备入口自动创建，不建议用户手写创建。

远程 Docker 设备示例

apiVersion: agent.wecode.io/v1
kind: Device
metadata:
  name: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
  namespace: default
  displayName: alice-remote-a931
spec:
  deviceId: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
  displayName: alice-remote-a931
  deviceType: remote
  connectionMode: websocket
  bindShell: claudecode
  isDefault: false
  clientIp: 10.0.0.24
  runtimeTransferHost: 10.0.0.24
  runtimeTransferPort: 17888
  capabilities: null
  remoteConfig:
    provider: docker
    image: ghcr.io/wecode-ai/wegent-device:latest
    deviceId: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
    deviceName: alice-remote-a931
    backendUrl: https://backend.example.com
    createdAt: "2026-06-17T10:00:00"
status:
  state: Available

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Device 资源名，通常与 `spec.deviceId` 一致
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.deviceId`	string	是	Executor 注册和心跳使用的设备 ID
`spec.displayName`	string	否	前端展示名称
`spec.deviceType`	`local`, `cloud`, `remote`	是	设备类型；`remote` 表示用户自管 Docker 容器或远端主机
`spec.connectionMode`	`websocket`	是	设备连接后端的方式
`spec.bindShell`	`claudecode`, `openclaw`	否	设备绑定的 shell runtime
`spec.isDefault`	boolean	否	是否为同类型默认设备
`spec.clientIp`	string	否	Backend 从设备连接观测到的客户端 IP
`spec.runtimeTransferHost`	string	否	Executor 上报且可供其他机器访问的设备地址
`spec.runtimeTransferPort`	integer	否	Executor session gateway 实际监听端口
`spec.capabilities`	array 或 null	否	设备能力标签
`spec.cloudConfig`	object	否	云设备元数据，仅云设备使用
`spec.remoteConfig`	object	否	远程设备元数据，仅远程设备使用

runtimeTransferHost 必须是其他机器可访问的地址；回环、未指定、链路本地和组播地址不会用于生成设备访问地址。runtimeTransferPort 由 Executor 上报；旧版 Executor 未上报该字段时，Backend 使用默认端口 17888。远程设备的浏览器访问地址由 Backend 生成：优先使用它观测到的设备地址，其次使用 runtimeTransferHost，再拼上 runtimeTransferPort。remoteConfig 只保存非敏感元数据。远程 Docker 启动命令中的 WEGENT_AUTH_TOKEN 是新建的 remote device API Key，不会写入 Device CRD。backendUrl 是容器访问 Backend 的地址，由后端当前环境生成。

🤖 Bot

Bot 是完整的智能体实例，结合了 Ghost、Shell 和 Model。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: developer-bot
  namespace: default
spec:
  ghostRef:
    name: developer-ghost
    namespace: default
  shellRef:
    name: ClaudeCode
    namespace: default
  modelRef:
    name: ClaudeSonnet4
    namespace: default

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Bot 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.ghostRef`	object	是	Ghost 引用
`spec.shellRef`	object	是	Shell 引用
`spec.modelRef`	object	是	Model 引用

引用格式

所有引用都遵循相同的格式：

name: "resource-name"
namespace: "default"

👥 Team

Team 定义了多个 Bot 的协作团队，指定了成员角色和协作模式。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Team
metadata:
  name: dev-team
  namespace: default
spec:
  members:
    - role: "leader"
      botRef:
        name: developer-bot
        namespace: default
      prompt: ""
      contextPassing: "previous_bot"
  collaborationModel: "pipeline"

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Team 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.members`	array	是	团队成员列表
`spec.collaborationModel`	string	是	协作模式

成员配置

字段	类型	必填	说明
`role`	string	否	成员角色，如 `leader`
`botRef`	object	是	Bot 引用
`prompt`	string	否	成员特定的提示词
`contextPassing`	string	否	Pipeline 阶段完成后传给下一阶段的消息：`none`、`original_user`、`previous_bot`、`original_and_previous`

协作模式

模式	说明
`pipeline`	流水线模式，按顺序执行
`route`	路由模式，根据条件路由
`coordinate`	协调模式，成员间协调
`collaborate`	并发模式，成员间同时执行

📚 KnowledgeBase

KnowledgeBase 用于管理文档知识库、检索配置和摘要能力。

检索配置

字段	类型	必填	说明
`spec.retrievalConfig`	object	否	RAG 检索配置。缺失或为 `null` 时表示无 RAG 知识库
`spec.retrievalConfig.retriever_name`	string	是*	检索器名称
`spec.retrievalConfig.retriever_namespace`	string	否	检索器所在 namespace，默认 `default`
`spec.retrievalConfig.embedding_config.model_name`	string	是*	Embedding 模型名称
`spec.retrievalConfig.embedding_config.model_namespace`	string	否	Embedding 模型所在 namespace，默认 `default`
`spec.retrievalConfig.retrieval_mode`	string	否	检索模式：`vector`、`keyword` 或 `hybrid`
`spec.retrievalConfig.top_k`	integer	否	返回结果数量
`spec.retrievalConfig.score_threshold`	number	否	最低相关性阈值
`spec.retrievalConfig.hybrid_weights`	object	否	混合检索权重

retriever_name 和 embedding_config.model_name 只有在 spec.retrievalConfig 存在时必填。创建知识库默认会自动补齐缺失的检索器和 Embedding 模型；如果创建请求明确使用无 RAG 模式，或无法找到可用默认配置，则不会写入 retrievalConfig。创建请求中的 rag_config_mode 只表达创建意图，不作为 KnowledgeBase YAML 字段持久化。持久化后的稳定状态只有两种：完整的 retrievalConfig，或无 retrievalConfig。

摘要相关配置

字段	类型	必填	说明
`spec.summaryEnabled`	boolean	否	是否启用自动摘要生成
`spec.summaryModelRef.name`	string	否	用于生成摘要的模型名称
`spec.summaryModelRef.namespace`	string	否	摘要模型所在 namespace
`spec.summaryModelRef.type`	string	否	摘要模型类型：`public`、`user`、`group`

运行时摘要字段

spec.summary 由系统在运行时维护，不建议手工直接写入 YAML。常见字段包括：

字段	说明
`short_summary`	AI 生成的短摘要
`long_summary`	AI 生成的长摘要
`manual_long_summary`	手动编辑的知识库长摘要，展示和上下文注入时优先使用
`topics`	AI 生成的主题标签
`status`	摘要状态：`pending`、`generating`、`completed`、`failed`
`manual_updated_at`	手动摘要最近更新时间
`manual_updated_by`	手动摘要最近编辑人

说明：

手动摘要不会阻止 AI 自动摘要继续更新
当 manual_long_summary 存在时，系统优先使用它做页面展示和聊天上下文注入
点击“恢复 AI 摘要”后，系统会回退到最新的 long_summary

代码 Wiki 专属字段

spec.kbType = "code_wiki" 的知识库由智能体从一个源仓库生成，下列字段全部由系统写入，不应手工编辑。

字段	类型	说明
`spec.kbType`	string	`notebook`、`classic` 或 `code_wiki`。创建后不能进出 `code_wiki`
`spec.source.sourceType`	string	`github`、`gitlab` 或 `gitea`
`spec.source.sourceUrl`	string	仓库地址，创建时从 URL 推导并剥除凭据
`spec.source.projectName`	string	`owner/repo`
`spec.source.sourceDomain`	string	仓库主机
`spec.publishedGenerationId`	integer	当前生效版本的唯一权威，0 表示尚未发布
`spec.lastPublishedAt`	string	上次发布时间，与指针同事务写入
`spec.lastPublishedCommit`	string	生效版本所记录的 commit
`spec.pageOrder`	array	页面路径的展示顺序；层级从路径推导，顺序只在这里
`spec.pendingIndexCleanup`	array	已删页面中尚未清理的向量库引用，下次发布时重试

几个不变量：

publishedGenerationId 是唯一权威 —— 不要从「最新完成的生成」推断生效版本：一次生成可以完成后被发布闸门拒绝
归属是创建者，namespace 固定 default —— 归属决定了普通知识库 ACL 就能生效；能否创建、能否重新生成，另由仓库权限决定
一个仓库一份 wiki，由 wiki_projects.source_url 的唯一约束保证
生成页面的 origin 为 generated；投影只增删这一类，用户内容永不受影响

🤝 Collaboration

Collaboration 定义了团队中 Bot 之间的交互模式和工作流程。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Collaboration
metadata:
  name: workflow-collaboration
  namespace: default
spec:
  type: "workflow"
  config:
    steps:
      - name: "planning"
        participants:
          - "planner-bot"
      - name: "development"
        participants:
          - "developer-bot"
      - name: "review"
        participants:
          - "reviewer-bot"

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Collaboration 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.type`	string	是	协作类型
`spec.config`	object	是	协作配置

工作流程配置

字段	类型	说明
`steps`	array	工作步骤列表
`steps.name`	string	步骤名称
`steps.participants`	array	参与者列表

💼 Workspace

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

完整配置示例

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}"
    branchName: "main"
    gitDomain: "github.com"

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Workspace 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.repository`	object	是	仓库配置

仓库配置

字段	类型	必填	说明
`gitUrl`	string	是	Git 仓库 URL
`gitRepo`	string	是	仓库路径格式
`branchName`	string	是	默认分支名
`gitDomain`	string	是	Git 域名

🎯 Task

Task 定义了要执行的任务，关联了 Team 和 Workspace。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: Task
metadata:
  name: implement-feature
  namespace: default
spec:
  title: "Implement new feature"
  prompt: "Task description"
  teamRef:
    name: dev-team
    namespace: default
  workspaceRef:
    name: project-workspace
    namespace: default
  knowledgeBaseScopes:
    - id: 101
      namespace: default
      name: Product Docs
      scopeRestricted: true
      folderIds: [12]
      explicitDocumentIds: null
      includeSubfolders: true
  externalKnowledgeRefs:
    - provider: ap
      mode: explicit
      id: kb-1
      name: External Product Docs
      scope: organization
      target_type: document
      node_id: document:node-1
      document_id: node-1
      target_name: api-reference.md

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Task 的唯一标识符
`metadata.namespace`	string	是	命名空间，通常为 `default`
`spec.title`	string	是	任务标题
`spec.prompt`	string	是	任务描述
`spec.teamRef`	object	是	Team 引用
`spec.workspaceRef`	object	是	Workspace 引用
`spec.knowledgeBaseScopes`	array	否	`/api/v1/responses` 绑定的知识库访问范围，用于后续对话继承目录或文档级 scope
`spec.externalKnowledgeRefs`	array	否	Task 级外部知识源绑定，由聊天上下文选择和任务知识库管理入口自动维护

知识库范围

spec.knowledgeBaseScopes 由 OpenAPI Responses 知识库工具自动维护。启用目录或文档范围后，后续带 previous_response_id 的请求会继承该范围，并在当前轮次重新解析目录内文档。

字段	类型	必填	说明
`id`	integer	否	知识库 ID，存在时优先用于解析
`namespace`	string	否	知识库命名空间，默认 `default`
`name`	string	是	知识库名称
`scopeRestricted`	boolean	否	是否限制到指定目录或文档
`folderIds`	array	否	允许访问的目录 ID，`0` 表示根目录直接文档
`explicitDocumentIds`	array	否	显式允许访问的文档 ID
`includeSubfolders`	boolean	否	目录范围是否包含子目录，默认 `true`

外部知识源绑定

spec.externalKnowledgeRefs 是运行时字段，描述当前 Task 已绑定的外部知识源。它由聊天发送和任务知识库管理接口维护，不用于 Ghost、Bot 或 Team 默认配置。

字段	类型	必填	说明
`provider`	string	是	外部知识 provider id
`mode`	string	否	绑定模式，默认 `explicit`；`explicit` 需要提供 `id`
`id`	string	条件必填	provider 内稳定的知识源 ID
`name`	string	否	知识源展示名
`scope`	string	否	provider 可解释的范围
`target_type`	string	否	`knowledge_base`、`folder` 或 `document`，缺省按整库处理
`node_id`	string	否	provider-neutral 节点 ID
`document_id`	string	否	provider-neutral 文档 ID
`parent_id`	string	否	provider-neutral 父节点 ID
`target_name`	string	否	文件夹或文档目标展示名

任务状态

状态	说明
`PENDING`	等待执行
`RUNNING`	正在执行
`COMPLETED`	已完成
`FAILED`	执行失败
`CANCELLED`	已取消
`DELETE`	已删除

🔌 ConnectorApp

ConnectorApp 定义管理员发布给 Wework/Codex 使用的外部应用连接。资源存储在 kinds 表中，metadata.name 对应应用 slug，当前使用系统命名空间 system。通常应通过 Wegent Web 的“系统管理 → 应用连接”维护，而不是手写 YAML。

完整配置示例

apiVersion: agent.wecode.io/v1
kind: ConnectorApp
metadata:
  name: ticket-api
  namespace: system
  displayName: Ticket API
spec:
  name: Ticket API
  description: Search and read internal tickets
  iconUrl: https://example.com/ticket-icon.png
  enabled: true
  visibility: roles
  allowedRoles:
    - admin
  authType: none
  transport: http
  mcpUrl: https://tickets.example.com/api
  providerHeadersEncrypted: "base64-encrypted-json"
  toolAllowlist:
    - get_ticket
  httpTools:
    - name: get_ticket
      description: Get one ticket
      method: GET
      path: /tickets/{id}
      input_schema:
        type: object
        properties:
          id:
            type: string
        required:
          - id
      argument_locations:
        id: path
      timeout_seconds: 30

字段说明

字段	类型	必填	说明
`metadata.name`	string	是	Connector App 的唯一 slug，工具名前缀使用该值
`metadata.namespace`	string	是	当前使用 `system`
`spec.name`	string	是	展示名称
`spec.description`	string	否	应用描述
`spec.iconUrl`	string	否	图标 URL
`spec.enabled`	boolean	是	是否启用，停用后不会出现在用户目录和 Runtime 中
`spec.visibility`	string	是	`all` 或 `roles`
`spec.allowedRoles`	array	否	`visibility: roles` 时允许访问的用户角色
`spec.authType`	string	是	当前仅支持 `none`
`spec.transport`	string	是	`streamable-http`、`sse` 或 `http`
`spec.mcpUrl`	string	是	MCP endpoint 或 HTTP API 基础地址
`spec.providerHeadersEncrypted`	string	否	使用项目敏感数据加密工具加密后的固定请求头 JSON
`spec.toolAllowlist`	array	否	允许暴露和调用的上游工具名
`spec.httpTools`	array	条件	`transport: http` 时必填，定义普通 HTTP API 暴露成 MCP 工具的方式

providerHeadersEncrypted 必须是加密后的 JSON 字符串。管理 API 接收明文 provider_headers 后会负责加密；手写 YAML 时不要提交明文 API Key、服务令牌或请求头。

最佳实践

1. 命名规范

使用小写字母、数字和中划线
避免特殊字符和空格
名称应具有描述性

2. 命名空间

默认使用 default 命名空间
在多租户环境中使用不同的命名空间

3. 引用管理

确保被引用的资源已存在
使用相同的命名空间
避免循环引用

4. 状态管理

定期检查资源状态
及时处理不可用的资源
监控任务执行进度

5. 配置校验

使用 YAML 语法校验工具
检查必填字段
校验引用关系

目录​

👻 Ghost​

完整配置示例​

字段说明​

业务方 MCP 服务器身份校验​

✨ Skill​

完整配置示例​

字段说明​

ZIP 包要求​

在 Ghost 中使用 Skills​

🧠 Model​

定义 ClaudeCode Model 完整配置示例​

字段说明​

Wework 模型选择器配置​

视觉委托模型引用​

模型选择器分组​

ClaudeCode常用环境变量​

🐚 Shell​

完整配置示例​

字段说明​

Shell 类型​

标签说明​

🖥 Device​

远程 Docker 设备示例​

字段说明​

🤖 Bot​

完整配置示例​

字段说明​

引用格式​

👥 Team​

完整配置示例​

字段说明​

成员配置​

协作模式​

📚 KnowledgeBase​

检索配置​

摘要相关配置​

运行时摘要字段​

代码 Wiki 专属字段​

🤝 Collaboration​

完整配置示例​

字段说明​

工作流程配置​

💼 Workspace​

完整配置示例​

字段说明​

仓库配置​

🎯 Task​

完整配置示例​

字段说明​

知识库范围​

外部知识源绑定​

任务状态​

🔌 ConnectorApp​

完整配置示例​

字段说明​

最佳实践​

1. 命名规范​

2. 命名空间​

3. 引用管理​

4. 状态管理​

5. 配置校验​

相关文档​

目录

👻 Ghost

完整配置示例

字段说明

业务方 MCP 服务器身份校验

✨ Skill

完整配置示例

字段说明

ZIP 包要求

在 Ghost 中使用 Skills

🧠 Model

定义 ClaudeCode Model 完整配置示例

字段说明

Wework 模型选择器配置

视觉委托模型引用

模型选择器分组

ClaudeCode常用环境变量

🐚 Shell

完整配置示例

字段说明

Shell 类型

标签说明

🖥 Device

远程 Docker 设备示例

字段说明

🤖 Bot

完整配置示例

字段说明

引用格式

👥 Team

完整配置示例

字段说明

成员配置

协作模式

📚 KnowledgeBase

检索配置

摘要相关配置

运行时摘要字段

代码 Wiki 专属字段

🤝 Collaboration

完整配置示例

字段说明

工作流程配置

💼 Workspace

完整配置示例

字段说明

仓库配置

🎯 Task

完整配置示例

字段说明

知识库范围

外部知识源绑定

任务状态

🔌 ConnectorApp

完整配置示例

字段说明

最佳实践

1. 命名规范

2. 命名空间

3. 引用管理

4. 状态管理

5. 配置校验

相关文档