xiantong 文档
CLI

CLI 参考

xiantong CLI 客户端的完整命令参考

xiantong-cli 是一个终端客户端，通过 WebSocket 连接到运行中的 xiantong 无头服务器。它提供列出来源、管理会话、发送实时流式消息以及验证服务器健康的命令。

安装#

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

xiantong-cli --help
xiantong-cli <command>

如果需要直接运行开发版 CLI，请以当前 xiantong 发行包或内部仓库说明为准。

快速开始#

最快速试用方式 —— 无需服务器设置：

# 自包含运行（自动启动服务器）
ANTHROPIC_API_KEY=sk-... xiantong-cli run "Hello, world!"

连接选项#

Flag环境变量默认描述
--url <ws[s]://...>XIANTONG_SERVER_URL—服务器 WebSocket URL
--token <secret>XIANTONG_SERVER_TOKEN—验证令牌
--workspace <id>—自动检测工作区 ID
--timeout <ms>—10000请求超时
--tls-ca <path>XIANTONG_TLS_CA—自签名 TLS 的自定义 CA 证书
--json—false用于脚本的 JSON 输出
--send-timeout <ms>—300000send 命令的超时时间

Flag 会覆盖环境变量。如果省略 --workspace，将自动使用第一个可用工作区。

命令#

信息与健康#

命令通道描述
pinghandshake only验证连接 —— 打印 clientId 和延迟
healthcredentials:healthCheck检查凭证存储健康
versionssystem:versions显示服务器运行时版本

资源列出#

命令通道描述
workspacesworkspaces:get列出所有工作区（id、名称、路径）
sessionssessions:get列出会话（id、名称、预览、状态）
connectionsLLM_Connection:list列出 LLM 连接
sourcessources:get列出已配置的来源

会话操作#

命令通道描述
session create [--name <n>] [--mode <m>]sessions:create创建新会话
session messages <id>sessions:getMessages打印消息历史
session delete <id>sessions:delete删除会话
cancel <id>sessions:cancel取消正在进行的处理

发送消息（流式）#

xiantong-cli send <session-id> <message>
echo "Summarize this" | xiantong-cli send <session-id>

send 命令订阅 session:event 并将 AI 响应实时流式输出到 stdout：

事件类型输出
text_delta文本以内联方式追加
tool_start[tool: name — intent] 标记
tool_result工具输出（截断到 200 字符）
error将错误输出到 stderr，退出码 1
complete换行，退出码 0
interrupted[interrupted]，退出码 130

原始 RPC#

xiantong-cli invoke <channel> [json-args...] # 发送任意 RPC 通道
xiantong-cli listen <channel> # 订阅推送事件

invoke 向任意通道发送请求并打印响应。listen 订阅推送通道并打印到达事件（Ctrl+C 停止）。

运行（自包含）#

xiantong-cli run <prompt>
xiantong-cli run --workspace-dir ./project --source github "List open PRs"

run 命令完全自包含 —— 它会启动一个无头服务器、创建会话、发送提示、流式返回响应并退出。无需单独的服务器设置。API 密钥可通过 --api-key、$LLM_API_KEY 或提供商特定的环境变量（如 $ANTHROPIC_API_KEY、$OPENAI_API_KEY）解析。

Flag默认描述
--workspace-dir <path>—运行前注册一个工作区目录
--source <slug>—启用一个来源（可重复）
--output-format <fmt>text输出格式：text 或 stream-json
--mode <mode>allow-all会话权限模式
--no-cleanupfalse退出时跳过会话删除
--server-entry <path>—自定义服务器入口点

LLM 配置：

Flag环境回退默认描述
--provider <name>LLM_PROVIDERanthropic提供商：anthropic、openai、google、openrouter、groq、mistral、xai 等
--model <id>LLM_MODEL（提供商默认）模型 ID（例如 claude-sonnet-4-5-20250929、gpt-4o、gemini-2.0-flash）
--api-key <key>LLM_API_KEY（提供商环境）API 密钥 —— 也会检查提供商特定的变量，例如 $OPENAI_API_KEY
--base-url <url>LLM_BASE_URL—用于代理、OpenRouter 或自托管模型的自定义端点
# 多提供商示例
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"

验证服务器#

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

# 自包含（自动启动服务器）
xiantong-cli --validate-server

当未提供 --url 时，--validate-server 会自动启动本地无头服务器，运行验证并关闭它。运行一个包含完整服务器生命周期（包括来源和技能创建）的 21 步集成测试：

  1. 建立连接 + 握手
  2. credentials:healthCheck
  3. system:versions
  4. system:homeDir
  5. workspaces:get
  6. sessions:get
  7. LLM_Connection:list
  8. sources:get
  9. sessions:create（临时 __cli-validate-* 会话）
  10. sessions:getMessages
  11. 发送消息 + 流式（文本响应）
  12. 发送消息 + 调用工具（Bash 工具）
  13. sources:create（临时 Cat Facts API 来源）
  14. 发送 + 来源引用（使用创建的来源）
  15. 发送 + 技能创建（通过 Bash 写入 SKILL.md）
  16. skills:get（验证技能出现）
  17. 发送 + 技能引用（调用创建的技能）
  18. skills:delete（清理）
  19. sources:delete（清理）
  20. sessions:delete（清理）
  21. 断开连接

注意： 此测试会修改工作区状态 —— 它会创建并删除一个临时会话、来源和技能。所有资源在完成后都会清理。即使失败也会继续并报告摘要。使用 --json 获取机器可读输出：

xiantong-cli --validate-server --json | jq '.results[] | select(.status == "FAIL")'

故障排查#

现象原因解决方案
连接超时服务器未运行验证服务器 URL 并确认其已启动
AUTH_FAILED令牌错误检查 XIANTONG_SERVER_TOKEN 是否匹配
PROTOCOL_VERSION_UNSUPPORTED版本不匹配更新 CLI 和服务器
WebSocket 错误网络/TLS 问题为自签名证书使用 --tls-ca
上一页CLI 客户端