Daeva — GPU Pod 编排器

Daeva 通过 REST API（以及可选的 MCP 服务器）将 AI 推理任务（语音转文字、图像生成、OCR、视觉分析）路由至由 GPU 支持的 Pod。它负责管理 Pod 的生命周期、独占组（自动解决 GPU 资源争用），以及可移植的 Pod 包。Daeva 可运行在与 Agent 相同的机器上，也可运行在远程主机上——默认为 localhost，但该值仅作为回退方案。

解析 Daeva 基础 URL

Daeva 可本地运行，也可运行于远程主机。请按以下顺序解析基础 URL：

1. 检查环境变量。 若设置了 DAEVA_URL，则直接将其作为完整的基础 URL（例如：http://server.local:8787）。若仅设置了 DAEVA_PORT，则使用 http://127.0.0.1:$DAEVA_PORT。
2. 尝试默认值。 若未设置任一环境变量，则使用 http://127.0.0.1:8787。
3. 通过健康检查验证。 向已解析的 URL 的 /health 端点发起请求。若返回 {"ok":true}，即可继续。
4. 若健康检查失败且未设置任何环境变量，则必须向用户询问 Daeva 的实际部署地址，之后再继续操作。不得盲目猜测或重试。

# 从环境变量解析基础 URL，未设置时回退至 localhost 默认值
DAEVA_BASE="${DAEVA_URL:-http://127.0.0.1:${DAEVA_PORT:-8787}}"

# 验证服务可达性
curl -sf "$DAEVA_BASE/health"
# 预期响应：{"ok":true}

若服务运行在本地但当前未启动，请启动它：

# 前台运行
daeva
# 或：PORT=8787 node dist/src/cli.js

# systemd（用户级）
systemctl --user start daeva

下方所有端点均以 $DAEVA_BASE 为基础 URL。在构造 curl 命令、MCP 配置或下游技能（skill）的 URL 时，务必代入已解析的实际值——除非 Agent 确实与 Daeva 运行在同一台主机上，否则切勿硬编码 127.0.0.1。

重要：行为规范

Daeva 是一项共享服务。 它并非按用户或按会话隔离。多个 Agent 和用户可能共用同一个 Daeva 实例。请将其视为共享基础设施——不要对当前正在运行的内容或其原因做出任何假设。

请使用生命周期端点管理 Pod。 如需唤醒、切换或停止 Pod，请使用专用的生命周期端点（/pods/:podId/activate、/pods/:podId/stop、/pods/swap）。切勿提交虚假或一次性任务来强制触发 Pod 切换——这会污染任务队列，并可能在共享服务上引发非预期的副作用。

工作负载流量必须经由 Daeva 的代理转发，而非直连容器端口。 当 Daeva 已安装时，下游技能（如 ComfyUI 技能）和客户端（如 Whisper 客户端）应将请求发送至 Daeva 代理地址 $DAEVA_BASE/proxy/，而非直接访问 Pod 的容器端口。例如，若 ComfyUI 由 Daeva 托管，则 ComfyUI 技能应调用 $DAEVA_BASE/proxy/comfyapi，而非 http://localhost:8188。此举确保 Daeva 能够透明地处理 Pod 激活、独占组切换及请求路由。仅当确认 Daeva 并未托管该 Pod 时，才可绕过代理。

能力与任务类型

内置 Pod

提交任务

向 /jobs 端点以 JSON 格式 POST 请求，需包含 type 字段，以及 files（或旧版 input）字段：

# 语音转文字
curl -s -X POST $DAEVA_BASE/jobs 
  -H 'Content-Type: application/json' 
  -d '{"type":"transcribe-audio","files":[{"source":"path","path":"/tmp/audio.wav"}]}'

# 图像生成
curl -s -X POST $DAEVA_BASE/jobs 
  -H 'Content-Type: application/json' 
  -d '{"type":"generate-image","capability":"image-generation","input":{"prompt":"a red fox on a snowy mountain"}}'

# OCR
curl -s -X POST $DAEVA_BASE/jobs 
  -H 'Content-Type: application/json' 
  -d '{"type":"extract-text","capability":"ocr","input":{"filePath":"/tmp/document.png"}}'

提交后，轮询任务状态并获取结果：

curl -s $DAEVA_BASE/jobs/          # 任务状态
curl -s $DAEVA_BASE/jobs//result    # 任务完成后的结果
curl -s $DAEVA_BASE/jobs                     # 列出全部任务

Pod 管理

这些端点用于控制完整的 Pod 生命周期——包括注册新 Pod、安装 Pod 包，以及管理运行时状态。

# 列出所有已注册的 Pod 及其运行时状态
curl -s $DAEVA_BASE/pods

# 依据清单（manifest）注册新 Pod
curl -s -X POST $DAEVA_BASE/pods/register 
  -H 'Content-Type: application/json' 
  -d '{ ... pod manifest JSON ... }'

# 依据别名（alias）安装 Pod 包（例如 "whisper"）
curl -s -X POST $DAEVA_BASE/pods/create 
  -H 'Content-Type: application/json' 
  -d '{"alias":"whisper"}'

# 列出注册中心中所有可用别名
curl -s $DAEVA_BASE/pods/aliases

# 列出已安装的包
curl -s $DAEVA_BASE/pods/installed

# 激活（启动）指定 Pod
curl -s -X POST $DAEVA_BASE/pods//activate

# 停止指定 Pod
curl -s -X POST $DAEVA_BASE/pods//stop

# 切换至另一 Pod（自动处理独占组冲突）
curl -s -X POST $DAEVA_BASE/pods/swap 
  -H 'Content-Type: application/json' 
  -d '{"podId":"comfyapi"}'

独占组（Exclusivity groups）： 当两个 Pod 共享同一块 GPU 且无法同时运行时，Daeva 在执行 Pod 切换或提交需使用不同 Pod 的任务时，会自动停止当前 Pod 并启动目标 Pod。

Pod 包来源

Pod 包可从多种来源安装：

• local-file —— 本地目录，其中包含 pod-package.json
• github-repo —— 格式为 owner/repo 的 GitHub 仓库，支持可选的 ref 和子路径
• git-repo —— 任意 Git URL
• uploaded-archive —— 直接上传的 .tar.gz 或 .zip 归档文件
• registry-index —— 由注册中心目录委托查询

安装过程中，Daeva 将执行包内定义的安装钩子（install hooks），创建声明的宿主机目录，并持久化已解析的宿主机路径模板变量（例如 MODELS_DIR、INPUT_DIR）。

可观测性（Observability）

提供细粒度的状态端点，便于调试与监控：

# 全量聚合状态快照
curl -s $DAEVA_BASE/status

# Pod 运行时状态 + 容器级检查
curl -s $DAEVA_BASE/status/runtime

# 已安装包 + 注册中心状态
curl -s $DAEVA_BASE/status/packages

# 队列深度 + 独占组信息
curl -s $DAEVA_BASE/status/scheduler

# 最近任务历史
curl -s $DAEVA_BASE/status/jobs/recent

当某个 Pod 表现异常（如卡住）时，请使用 /status/runtime —— 它包含容器级别的详细信息。当需要诊断任务为何长期处于排队状态时（常见原因为独占组冲突），请使用 /status/scheduler。

完整 API 参考文档

核心端点（Core Endpoints）

可观测性端点（Observability Endpoints）

MCP 服务器配置

Daeva 自带一个 MCP stdio 服务器。其 --base-url 参数必须指向实际解析得到的 Daeva URL —— 请使用 $DAEVA_BASE，而非硬编码的 localhost 地址（除非 Daeva 确实与运行 MCP 客户端的主机位于同一台机器上）。

{
  "mcpServers": {
    "daeva": {
      "command": "daeva-mcp",
      "args": ["--base-url", "http://server.local:8787"]
    }
  }
}

请将 http://server.local:8787 替换为您环境中实际的 $DAEVA_BASE 值。配置好 MCP 服务器后，建议优先使用 MCP 工具，而非原始的 curl 命令。

故障排查（Troubleshooting）

• /health 返回连接被拒绝（Connection refused） —— 服务未运行。请使用 daeva 或 systemctl --user start daeva 启动服务。
• 任务长时间处于 queued 状态 —— 可能是未注册支持该能力的 Pod，或存在独占组冲突阻塞了任务。请检查 /pods 和 /status/scheduler。
• Pod 无法启动 —— 请检查 /status/runtime 中的容器级错误信息。
• 返回 404 alias not found —— 该别名在注册中心中不存在。请通过 /pods/aliases 查看有效选项。
• 包安装失败 —— 请确认来源（本地路径、Git URL、归档文件）可访问。可通过 /status/packages 查看安装状态。