CLI 客户端

使用 xiantong CLI 从终端与服务器交互

使用 xiantong CLI 从终端与服务器交互。

xiantong-cli 是面向 xiantong 远程服务器的终端客户端。它通过 WebSocket 连接，可用于管理会话、发送带实时流的消息，并验证服务器健康状况。

安装#

请先确认 xiantong-cli 已随 xiantong 安装，或由您的部署包/管理员提供，并已加入 PATH。

验证：

xiantong-cli --help
xiantong-cli ping

如果命令不可用，请检查安装位置、PATH 设置或您的 xiantong 发行包说明。

快速开始#

1. 启动服务器#

在服务器端生成令牌并启动远程服务：

export XIANTONG_SERVER_TOKEN=$(openssl rand -hex 32)
xiantong-server

2. 设置连接信息#

export XIANTONG_SERVER_URL=ws://127.0.0.1:9100
export XIANTONG_SERVER_TOKEN=<your-token>

远程连接建议使用 wss:// 或安全隧道。

3. 验证连接#

xiantong-cli ping
# Connected: clientId=a1b2c3d4 latency=12ms

4. 开始操作#

# 列出会话
xiantong-cli sessions

# 发送消息并流式接收响应
xiantong-cli send <session-id> "What files changed in the last commit?"

常见工作流#

运行一次性任务（自包含）#

run 命令会创建一个会话、发送提示、流式接收响应并退出：

# 简单提示
xiantong-cli run "Summarize the project structure"

# 指定工作区目录和来源
xiantong-cli run --workspace-dir ./my-project --source github "List open PRs"

# 多提供商支持
xiantong-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... xiantong-cli run --provider google --model gemini-2.0-flash "Hello"
xiantong-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

# 为 CI 流处理输出 JSON
xiantong-cli run --output-format stream-json "Run the test suite"

API 密钥会从 --api-key、$LLM_API_KEY 或特定提供商环境变量（如 $ANTHROPIC_API_KEY、$OPENAI_API_KEY）中解析。详见 CLI 参考。

验证服务器部署#

部署或更新服务器后，可运行内置验证：

# 针对正在运行的服务器
xiantong-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

# 自包含运行
xiantong-cli --validate-server

当未提供 --url 时，--validate-server 会自动启动本地服务，运行验证并关闭。验证会创建和删除临时资源，因此会短暂改变工作区状态。

在 CI 场景下可使用 JSON 输出：

xiantong-cli --validate-server --json | jq '.failed'
# 0 = 全部正常

管理会话#

# 创建会话
xiantong-cli session create --name "Code Review" --mode safe

# 列出会话
xiantong-cli sessions

# 发送消息并实时接收 AI 回复
xiantong-cli send <id> "Review the changes in src/auth/"

# 如有需要可取消
xiantong-cli cancel <id>

# 清理
xiantong-cli session delete <id>

流式接收 AI 响应#

send 命令会连接到会话事件流，并实时将 AI 响应输出到 stdout：

xiantong-cli send abc-123 "Explain the authentication flow"

也可以通过管道传入内容：

cat error.log | xiantong-cli send abc-123 "What's causing these errors?"
git diff HEAD~1 | xiantong-cli send abc-123 "Review this diff"

使用 JSON 输出脚本化#

每个命令都支持 --json，便于机器读取：

# 获取所有工作区 ID
xiantong-cli --json workspaces | jq -r '.[].id'

# 统计会话数量
xiantong-cli --json sessions | jq length

# 创建会话并获取 ID
SESSION=$(xiantong-cli --json session create --name "CI" | jq -r '.id')

CI/CD 集成#

#!/bin/bash
set -e

# 验证服务器健康
xiantong-cli --validate-server --json | jq -e '.failed == 0'

# 为本次 CI 运行创建会话
SESSION=$(xiantong-cli --json session create --name "CI-${CI_BUILD_ID}" | jq -r '.id')

# 运行任务
xiantong-cli send "$SESSION" "Run the test suite and report any failures"

# 清理
xiantong-cli session delete "$SESSION"

原始 RPC 访问#

对于未封装为命名命令的通道，可使用 invoke：

# 直接调用任意 RPC 通道
xiantong-cli invoke system:homeDir
xiantong-cli invoke sessions:get '"workspace-123"'

# 订阅事件
xiantong-cli listen session:event

连接选项#

完整标志、环境变量和故障排查请参考 CLI 参考。