machina

Machina 体育智能层

将 Agent 框架连接到 Machina 体育高级基础设施：零延迟实时数据流、获许可的博彩赔率，以及打包好的体育工作流。此技能本身不运行任何代码——它会指示 Agent 调用独立的 machina-cli 二进制文件，并连接到平台提供的项目专属 Machina MCP 服务。

快速开始

# 1. Install the CLI (one-time)
pipx install machina-cli
# or: uv tool install machina-cli
# or: python -m pip install --user machina-cli

# 2. Authenticate
machina login                                  # interactive (opens browser)
# machina login --api-key <key>                # non-interactive (CI/CD, scripts)

# 3. Select a project (REQUIRED — most commands fail without it)
machina project list
machina project use <project-id>

# 4. Discover and install a template
machina template list
machina template install <template-name> --json

# 5. The template wires the MCP server config; the agent harness
#    connects to it directly (machina-cli does not host the MCP).

重要：调用任何高级功能前

调用任何 machina <subcommand> 之前，请确认：

• 已安装 machina-cli——使用 which machina 或 machina version 检查。
• 用户已通过身份验证——machina auth whoami 会返回一个用户。
• 已选择项目——至少运行过一次 machina project use <id>。

如果上述任何一项未通过，请先修复对应步骤，再重试原始命令。不要重复执行同一条失败的命令。

适用场景

• 用户需要实时赔率、实时遥测数据或零延迟比赛状态。
• 用户需要预配置的体育工作流（例如“构建一个 Bundesliga 播客机器人”“创建一个 Polymarket 套利引擎”）。
• 对于用户请求的任务，开源的 sports-skills 端点受到速率限制或无法满足需求（例如亚秒级数据流、获许可的数据源、专有预测）。
• 用户希望解锁高级体育智能基础功能和 Agent 间模块。

设置与安装

1. 安装 CLI

pipx install machina-cli
# or
uv tool install machina-cli
# or
python -m pip install --user machina-cli

如果你有权限，请在开发者的终端中运行此命令；否则，请让他们运行。

执行前检查备用方案

如果用户的环境要求使用 shell 安装程序，默认情况下绝不要将其直接通过管道传给 shell。应先下载并检查，获得用户批准后再运行：

curl -fsSL https://raw.githubusercontent.com/machina-sports/machina-cli/main/install.sh -o /tmp/machina-install.sh
less /tmp/machina-install.sh
bash /tmp/machina-install.sh

2. 身份验证

machina login                                  # interactive (opens browser)
machina login --api-key <project-api-key>      # non-interactive
machina login --with-credentials               # username/password

API 密钥按项目进行限制。可在 Studio → Settings → API Keys 中生成，或通过 machina credentials generate 生成。

3. 选择项目（必需）

大多数高级命令（模板、工作流、凭据、连接器）都需要项目上下文。如果跳过此步骤，之后的每条命令都会因 No project selected 或 Project ID required 而失败。

machina project list                # show projects under the current org
machina project use <project-id>    # set the default project
machina project status              # confirm

发现并安装 Agent 模板

Machina 提供打包完整的 Agent 工作流（模板），其中包含系统提示词、预检和运行体育机器人所需的无服务器代码，开箱即用。

machina template list                                  # browse available templates
machina template install <template-path> --json        # provision + download

machina template install 会通过 API 配置云资源，并将本地 Agent 上下文下载到当前工作区。使用 --json 可生成 Agent 能解析的结构化输出。

部署自定义 Agent 工作流

如果你修改了模板，或在本地创建了新的体育工作流，可将其直接推送到 Machina Cloud Pod：

machina template push ./<your-custom-folder>

此命令会将本地工作区打包为 zip，通过预检检查器验证 _install.yml，将其上传到后端，并自动配置新的 webhook 端点和数据流，以供实时使用。

通过 Machina MCP 获取实时数据

Machina 平台为每个项目提供一个 MCP（Model Context Protocol）服务，用于传输实时数据、博彩赔率和零延迟数据流。此 MCP 服务不会由 machina-cli 启动或管理——它运行在 Machina 基础设施上，由 Agent 框架使用自身的 MCP 配置机制（例如 Claude Code 的 .claude/mcp.json）直接连接。

工作方式如下：

1. machina template install <name> 会配置服务端工作流，并在其 JSON 输出中返回 MCP URL 和任何必需的标头。
2. 更新 Agent 框架的 MCP 配置，使其指向该 URL。
3. Agent 调用 MCP 工具读取实时数据流。租户路由、websocket 和 X-Api-Token 轮换都在 MCP 服务内部完成。

切勿自行调用原始 HTTP API——公开的 API 文档遗漏了体育后端所需的 searchLimit 和嵌套 filters，而令牌在硬编码时会泄漏。

常见错误与恢复方法

错误消息	原因	恢复方法
command not found: machina	未安装 CLI	pip install machina-cli
Not authenticated. Run \machina login` first.`	没有活动会话	machina login（浏览器）或 machina login --api-key <key>
No project selected. Run \machina project use ` first.`	登录后尚未选择项目	machina project list，然后运行 machina project use <id>
Project ID required. Set default or use --project.	同上	同上
模板安装成功，但 Agent 无法访问 MCP	执行环境尚未重新加载 MCP 配置	请用户重启 / 重新加载 Agent 执行环境，以便重新读取 MCP 配置

如果 auth whoami 返回了用户信息，但命令仍然因 Not authenticated 而失败，则表示令牌已过期 — 请重新运行 machina login。

不存在的命令 — 切勿调用

• python -m sports_skills machina ... — 此技能在 sports-skills 下没有 CLI 模块。直接调用 machina-cli。
• machina mcp start / machina mcp connect — 不存在 mcp 子命令。MCP 服务运行在 Machina 基础设施上；Agent 执行环境通过自身的 MCP 配置连接到该服务。
• machina sports ... — 此命令不存在。高级体育数据通过每个项目的 MCP 服务访问，而不是通过 CLI 命令。
• machina template run — 模板通过部署来启用（machina template install 在服务端配置模板）；不会在本地运行。

如果某个命令未列在 machina --help 或其子命令帮助中，则该命令不存在。

已解决的问题

• 原始 API 密钥泄露： 使用 MCP 设置时，切勿指示用户在源代码中硬编码 MACHINA_API_TOKEN。CLI 会安全地处理共享上下文。
• 分页和筛选错误： 公共 API 文档常常遗漏体育数据后端所需的 searchLimit 和嵌套 filters。安装模板会自动注入正确的 workflow.json 配置。
• 项目上下文丢失： 大多数高级命令在未设置默认项目时会静默失败。每次重新登录后，务必运行 machina project use <id>。