Sable Platform + HyperDX Observability

Anvil

适用于 Sable AI 语音 Agent 平台的命令行界面和 MCP 服务。

快速开始（2 分钟）

# 1. Install
go install github.com/sable-inc/anvil/cmd/anvil@latest

# 2. Authenticate
anvil auth login --token svc_your_token_here

# 3. Set your default org
mkdir -p ~/.config/anvil
cat > ~/.config/anvil/config.yaml << 'EOF'
default_org: "your-org"
api_url: "https://api.withsable.com"
EOF

# 4. Set up shell completions (zsh)
echo 'source <(anvil completion zsh)' >> ~/.zshrc
source ~/.zshrc

# 5. Verify
anvil auth status
anvil agent list

安装

选项 1：Homebrew（推荐）

brew install sable-inc/tap/anvil

选项 2：通过 Go 安装

go install github.com/sable-inc/anvil/cmd/anvil@latest

这会将 anvil 二进制文件放入 $GOPATH/bin（通常是 ~/go/bin）。请确保该目录位于你的 $PATH 中：

# Add to your shell profile if not already there
export PATH="$HOME/go/bin:$PATH"

选项 3：下载二进制文件（无需 Go）

从 GitHub Releases 下载最新版本：

macOS（Apple Silicon）：

curl -sL https://github.com/sable-inc/anvil/releases/latest/download/anvil_darwin_arm64.tar.gz | tar xz
sudo mv anvil /usr/local/bin/

macOS（Intel）：

curl -sL https://github.com/sable-inc/anvil/releases/latest/download/anvil_darwin_amd64.tar.gz | tar xz
sudo mv anvil /usr/local/bin/

Linux（amd64）：

curl -sL https://github.com/sable-inc/anvil/releases/latest/download/anvil_linux_amd64.tar.gz | tar xz
sudo mv anvil /usr/local/bin/

也可以从 Releases 页面 手动下载。

选项 4：从源代码构建

git clone https://github.com/sable-inc/anvil.git
cd anvil
make build
sudo mv bin/anvil /usr/local/bin/

验证安装

anvil version
# anvil v0.1.0 (commit: abc1234, built: 2026-02-14T..., darwin/arm64)

身份验证

Anvil 使用服务令牌通过 sable-api 进行身份验证：

# Store your token (one-time)
anvil auth login --token svc_your_token_here

# Verify it works
anvil auth whoami    # shows stored token info
anvil auth status    # verifies API connectivity

凭据存储在 ~/.config/anvil/credentials.json 中（文件权限：0600）。

要获取服务令牌，请联系团队管理员，或在 Sable Platform 控制面板中生成一个令牌。

配置

创建 ~/.config/anvil/config.yaml：

default_org: "my-org"
api_url: "https://api.withsable.com"
format: "table"

使用标志覆盖任意设置：

anvil --org other-org --format json agent list

设置	标志	配置键	说明
组织	--org	default_org	所有命令的默认组织
API URL	--api-url	api_url	Sable API 基础 URL
输出格式	--format	format	table、json 或 yaml
禁用颜色	--no-color	—	禁用彩色输出
详细模式	--verbose	—	启用调试日志

Shell 补全

Anvil 支持动态 Tab 补全，可从实时 API 中提供真实资源名称建议。

设置（一次性，永久生效）

Zsh（macOS 默认）：

echo 'source <(anvil completion zsh)' >> ~/.zshrc
source ~/.zshrc

Bash：

echo 'source <(anvil completion bash)' >> ~/.bashrc
source ~/.bashrc

Fish：

anvil completion fish > ~/.config/fish/completions/anvil.fish

PowerShell：

anvil completion powershell >> $PROFILE

可用功能

设置完成后，可在任意位置按 TAB：

anvil <TAB>                      # all subcommands
anvil agent get <TAB>            # suggests agent slugs + IDs from API
anvil journey delete <TAB>       # suggests journey slugs + IDs
anvil kb sync <TAB>              # suggests KB item IDs with names
anvil config pull <TAB>          # suggests config version IDs
anvil connect <TAB>              # suggests agent slugs
anvil --format <TAB>             # suggests table, json, yaml

补全功能会使用已存储的令牌从 API 获取实时数据。如果你尚未通过身份验证，系统会正常地不显示建议（不会报错）。

常见问题

anvil 或我的 shell 更新后，需要重新生成补全吗？ 不需要。source <(anvil completion ...) 模式会在每次启动新的 shell 会话时自动重新生成补全。对于 Fish，如果 anvil 更新后新增了命令，请重新运行文件写入命令。

命令

Agents

anvil agent list                     # List agents
anvil agent get <id|slug>            # Get agent details
anvil agent create --name "My Agent" # Create agent
anvil agent update <id> --name "New" # Update agent
anvil agent delete <id>              # Delete agent

Journeys

anvil journey list                   # List journeys
anvil journey get <id>               # Get journey with moments/transitions
anvil journey create --name "Flow"   # Create journey

知识库

anvil kb list                        # List knowledge base items
anvil kb get <id>                    # Get item details
anvil kb search "query"              # Semantic search
anvil kb import-url <url>            # Import a URL
anvil kb import-sitemap <url> --name "Docs"  # Import from sitemap
anvil kb sync <id>                   # Sync item to vector store
anvil kb sync-all                    # Sync all items
anvil kb crawl <id>                  # Re-crawl a URL item
anvil kb delete <id>                 # Delete item
anvil kb job <jobId>                 # Check sitemap import job status

配置即代码

anvil config list                    # List config versions
anvil config get <id>                # Get config version details
anvil config pull <id> -o config.yaml  # Download config as YAML
anvil config push config.yaml        # Upload config from YAML
anvil config validate config.yaml    # Validate config locally
anvil config diff config.yaml --id <id>  # Diff local vs remote

分析与转录文本

anvil analytics sessions             # Session analytics
anvil analytics stages               # Stage funnel analytics
anvil transcript list                # List transcripts
anvil transcript view <id>           # View transcript messages

部署

anvil deploy history --org org_xxx            # List deployment history
anvil deploy trigger --org org_xxx            # Trigger a deployment
anvil deploy trigger --org org_xxx --watch    # Trigger and poll until complete
anvil deploy rollback --org org_xxx           # Rollback deployment
anvil deploy create --org org_xxx             # Create initial deployment
anvil deploy delete --org org_xxx             # Delete deployment
anvil deploy update-secrets --org org_xxx     # Update deployment secrets
anvil deploy pin-forge --org org_xxx --forge-version v1.0  # Pin forge version

LiveKit

# Sessions
anvil livekit sessions list --org org_xxx     # List active rooms
anvil livekit sessions get <room> --org org_xxx
anvil livekit sessions close <room> --org org_xxx

# Agent management
anvil livekit agent list --org org_xxx        # List agents
anvil livekit agent status --org org_xxx      # Agent status
anvil livekit agent versions --org org_xxx    # Agent versions
anvil livekit agent logs --org org_xxx        # Agent logs
anvil livekit agent restart --org org_xxx     # Restart agent
anvil livekit agent delete --org org_xxx      # Delete agent

# Agent secrets
anvil livekit agent secrets list --org org_xxx
anvil livekit agent secrets set --org org_xxx --secret KEY=VALUE
anvil livekit agent secrets delete <name> --org org_xxx

Forge（版本管理）

anvil forge versions                  # List forge versions
anvil forge branches                  # List forge branches
anvil forge commits main              # List commits on branch
anvil forge validate main             # Validate a git ref

视频处理

anvil video generate-moment --video-url <url>         # Start moment generation
anvil video generate-moment --video-url <url> --watch  # Generate and poll
anvil video generate-journey --video-url <url>         # Start journey generation
anvil video job-status <jobId>                         # Check job status

实用工具

anvil health                         # API health check
anvil health --db                    # Include database health
anvil connect <agent-slug>           # Get LiveKit connection details
anvil api GET /agents                # Raw API request
anvil api POST /agents -d '{"name":"test"}'
anvil version                        # Print version info

配置即代码工作流

拉取配置，在本地编辑、验证，然后推送：

# Pull the current config
anvil config pull <config-id> -o agent.yaml

# Edit the YAML file
$EDITOR agent.yaml

# Validate locally (no API call needed)
anvil config validate agent.yaml

# See what changed
anvil config diff agent.yaml --id <config-id>

# Push the updated config
anvil config push agent.yaml

MCP 服务（面向 AI 助手）

Anvil 内含 MCP 服务（28 个 Sable 工具 + 5 个 HyperDX 可观测性工具），可供 Claude Code、Cursor、Windsurf 等 AI 编码助手使用。

一次性设置

anvil auth login --token svc_your_token     # Sable API credentials
anvil settings set-hyperdx hdx_your_key     # HyperDX API key (optional)

添加到 Cursor

在浏览器中粘贴以下内容，即可一键安装：

cursor://anysphere.cursor-deeplink/mcp/install?name=sable&config=eyJjb21tYW5kIjoiYW52aWwiLCJhcmdzIjpbIm1jcCIsInNlcnZlIl19

或者手动添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "sable": {
      "command": "anvil",
      "args": ["mcp", "serve"]
    }
  }
}

添加到 Claude Code

claude mcp add sable -s user -- anvil mcp serve

配置中无需填写密钥——anvil 会从 ~/.config/anvil/ 读取凭据。

其他编辑器（Windsurf 等）

将相同的 JSON 配置添加到编辑器的 MCP 设置文件中。

Sable 工具（28）

领域	工具
Agent	list_agents、get_agent、create_agent、update_agent、delete_agent
旅程	list_journeys、get_journey、create_journey、update_journey、delete_journey
知识库	list_knowledge_base、get_knowledge_base_item、search_knowledge_base、import_knowledge_base_url、delete_knowledge_base_item、sync_knowledge_base_item
配置	list_configs、get_config
部署	get_deploy_history、trigger_deploy、rollback_deploy
转录文本	list_transcripts、get_transcript
分析	get_session_analytics、get_stage_analytics
实用工具	check_health、get_connection_details、raw_api_request

HyperDX 可观测性工具（5 个，可选）

运行 anvil settings set-hyperdx <key> 或设置 HYPERDX_API_KEY 环境变量后启用。

工具	用途
hdx_search_events	使用聚合、时间范围、筛选条件和分组方式查询日志／跨度
hdx_query_metrics	查询指标（Sum、Gauge、Histogram）
hdx_list_dashboards	列出 HyperDX 仪表板
hdx_get_dashboard	获取包含图表定义的仪表板
hdx_list_alerts	列出已配置的警报

发布新版本

Anvil 使用 goreleaser 和 GitHub Actions 自动发布。

创建发布版本

git tag v0.1.0
git push origin v0.1.0

GitHub Actions 将自动：

1. 为 Linux、macOS 和 Windows（amd64 + arm64）构建二进制文件
2. 创建包含可下载压缩包的 GitHub Release
3. 生成校验和与变更日志
4. 发布到 Homebrew tap（sable-inc/homebrew-tap）
5. 发布到 MCP Registry（可在 Claude Code / Cursor 中发现）

团队成员随后可以通过以下方式升级：

# Homebrew
brew upgrade anvil

# Go install
go install github.com/sable-inc/anvil/cmd/anvil@latest

快照构建（本地测试）

goreleaser --snapshot --clean
ls dist/

开发

make build     # Build binary
make test      # Run tests with race detector
make lint      # Run golangci-lint v2
make check     # Build + test + lint
make install   # Install to $GOPATH/bin
make generate  # Generate API client from OpenAPI spec
make clean     # Remove build artifacts

需要：

• Go 1.26+
• golangci-lint v2（用于 make lint）
• 正在运行的 sable-api 实例（用于 make generate）

CI/CD

GitHub Actions 会自动运行：

• CI（.github/workflows/ci.yml）：每次推送和 PR 时执行构建、测试和 lint
• 发布（.github/workflows/release.yml）：在版本标签（v*）上运行 goreleaser