Craft Agents craft-cli 完全参考：ping 到 run 的 14 个命令逐个拆解
【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss
Craft Agents的命令行工具craft-cli是一个面向 AI Agent 终端场景的瑞士军刀：通过 WebSocket 连接运行中的 Craft Agent 服务器，14 个命令覆盖从连通性诊断（ping）、资源列表、会话管理到一步式 AI 问答（run）的全部日常操作。本文逐个拆解这 14 个命令的用途、参数与典型用法，帮你快速把它写进自动化脚本。
1 分钟上手：安装与首次运行 craft-cli
使用前需安装 Bun 运行时，然后克隆仓库并安装依赖：
git clone https://gitcode.com/GitHub_Trending/cr/craft-agents-oss cd craft-agents-oss bun install有两种运行方式：
# 方式 A：直接用 Bun 执行入口脚本 bun run apps/cli/src/index.ts ping # 方式 B：全局链接，之后可用 craft-cli 命令 cd apps/cli && bun link craft-cli ping最省心的体验是run命令——它会自动拉起一个本地无头服务器，无需任何前置配置：
ANTHROPIC_API_KEY=sk-... craft-cli run "Hello, world!"📌 工作区是 Agent 的"作业目录"。比如注册一个项目目录作为工作区后，Agent 就能读取其中的文档和图片：
完整参考见官方文档 docs/cli.md，命令实现位于 apps/cli/src/index.ts。
14 个命令总览
| # | 命令 | 分类 | 一句话说明 |
|---|---|---|---|
| 1 | ping | 诊断 | 验证连通性，返回 clientId 与延迟 |
| 2 | health | 诊断 | 检查凭据存储健康状态 |
| 3 | versions | 诊断 | 显示服务器运行时版本 |
| 4 | workspaces | 列表 | 列出所有工作区 |
| 5 | sessions | 列表 | 列出工作区内的会话 |
| 6 | connections | 列表 | 列出已配置的 LLM 连接 |
| 7 | sources | 列表 | 列出已配置的数据源 |
| 8 | session | 会话操作 | 含 create / messages / delete 三个子命令 |
| 9 | send | 会话操作 | 向会话发消息并流式输出 AI 回复 |
| 10 | cancel | 会话操作 | 取消进行中的处理 |
| 11 | run | 一步式 | 自动拉起服务器 + 发消息 + 流式输出 + 退出 |
| 12 | invoke | 高级 | 对任意 RPC 通道发起裸调用 |
| 13 | listen | 高级 | 订阅服务器推送事件 |
| 14 | --validate-server | 诊断 | 21 步服务器集成自检 |
命令分发逻辑集中在 index.ts 的 switch 语句中；WebSocket 客户端封装在 apps/cli/src/client.ts。
诊断三兄弟：ping、health、versions
这三个命令都是"先连通再说"的基础检查，排障时第一步就该跑它们。
ping—— 验证与服务器能否握手，返回客户端 ID 和往返延迟：
craft-cli ping # 输出：Connected: clientId=xxx latency=12mshealth—— 调用credentials:healthCheck，检查凭据存储是否可用：
craft-cli healthversions—— 调用system:versions，显示服务端各运行时版本，出现PROTOCOL_VERSION_UNSUPPORTED报错时用它对比版本：
craft-cli versions配合--json可得到机器可读输出，方便写监控脚本：
craft-cli --json ping资源列表四命令：workspaces、sessions、connections、sources
这四个命令只读、无副作用，适合放进健康巡检脚本。
craft-cli workspaces # id + 名称 + 路径 craft-cli sessions # 会话 id + 名称 + 预览 + 处理中状态 craft-cli connections # 所有 LLM 连接 craft-cli sources # 工作区内配置的数据源💡sessions和sources依赖工作区：省略--workspace时 CLI 会自动检测第一个可用工作区（逻辑见 resolveWorkspace）；若服务器上没有工作区会报错提示你显式指定--workspace <id>。
session 三个子命令：创建、回看、清理
session是一个带子命令的组命令（实现见 cmdSessionCreate 等）：
# 创建会话，可指定名称与权限模式 craft-cli session create --name "CI Run" --mode allow-all # 打印某会话的完整消息历史 craft-cli session messages <session-id> # 删除会话 craft-cli session delete <session-id>典型脚本套路：先session create拿到 id（加--json用 jq 提取），干完活再session delete收尾，全程不碰桌面应用。
send：流式输出 AI 回复
send是交互核心：向已有会话发送消息，并实时流式打印 AI 回复（cmdSend 与事件订阅实现）：
craft-cli send abc-123 "What files are in the current directory?" # 支持管道输入（stdin 自动识别） echo "Summarize this" | craft-cli send abc-123 cat document.txt | craft-cli send abc-123 --stdin事件流会按类型渲染到终端：
| 事件 | 表现 |
|---|---|
text_delta | 文本逐字流式输出 |
tool_start | 显示[tool: 名称 — 意图]标记 |
tool_result | 工具结果（截断至 200 字符） |
complete | 退出码 0 |
error | 输出到 stderr，退出码 1 |
interrupted | 退出码 130 |
默认等待完成的上限是 5 分钟，可用--send-timeout <ms>调整。
cancel：一键打断正在跑的任务
会话处理时间较长、发现方向跑偏时，不必等超时：
craft-cli cancel <session-id>它调用sessions:cancel中断当前处理，适合放进 CI 的失败分支做优雅清理。
run：最强大的一步式命令
run是唯一自包含的命令——不需要预先运行服务器，它会自动完成整个生命周期（cmdRun 完整实现）：
- 用 server-spawner.ts 拉起本地无头服务器
- 自动配置 LLM 连接（从
--api-key/$LLM_API_KEY/ 各厂商环境变量解析密钥） - 可选注册
--workspace-dir <path>作为工作区 - 创建临时会话 → 发送提示词 → 流式打印回复
- 结束后自动删除会话并关闭服务器（
--no-cleanup可保留）
常用参数：
# 指定目录 + 数据源 craft-cli run --workspace-dir ./project --source github "List open PRs" # 换用 OpenAI craft-cli run --provider openai --model gpt-4o "Summarize this repo" # 自定义端点（代理 / 自托管模型） craft-cli run --provider anthropic --base-url https://my-proxy/v1 --api-key $KEY "Hello" # 管道输入提示词 cat error.log | craft-cli run "What's causing these errors?"| 参数 | 默认值 | 说明 |
|---|---|---|
--workspace-dir | — | 目录直接注册为工作区 |
--source <slug> | — | 启用的数据源（可重复） |
--mode | allow-all | 会话权限模式 |
--output-format | text | text或stream-json |
--no-cleanup | false | 结束后保留会话 |
--server-entry | — | 自定义服务器入口路径 |
支持的 provider 包括anthropic、openai、google、openrouter、groq、mistral、deepseek、xai、cerebras、huggingface、amazon-bedrock等（密钥解析逻辑）。stream-json输出让每个事件变成一行 JSON，方便下游程序消费。
invoke 与 listen：给高阶玩家的后门
这两个命令让你绕过封装、直接触达服务器 RPC 层：
# 裸 RPC 调用：任意通道 + JSON 参数 craft-cli invoke system:homeDir craft-cli invoke sessions:get '"workspace-123"' # 订阅推送事件，Ctrl+C 退出 craft-cli listen session:event想调试服务器内部通道或写监控探针时非常有用——所有参数按 JSON 解析，解析失败则当普通字符串传入（cmdInvoke 实现）。
--validate-server：21 步一键体检
怀疑部署有问题？一条命令跑完覆盖完整生命周期的 21 步集成自检：
# 对着已有服务器 craft-cli --validate-server --url ws://127.0.0.1:9100 --token <token> # 或不带 --url，自动拉起本地服务器自检 craft-cli --validate-server --json步骤从握手、凭据健康检查、版本比对，一直覆盖到会话创建、消息流式、工具调用、数据源与技能创建清理、断开连接。📋 注意它会临时创建并清理会话/数据源/技能等测试资源，全部步骤失败也会继续跑完并输出汇总报告。步骤定义见 getValidateSteps。
全局参数速查表
除run外，其他命令都需要服务器地址（--url或环境变量CRAFT_SERVER_URL）：
| 参数 | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--url | CRAFT_SERVER_URL | — | 服务器 WebSocket 地址 |
--token | CRAFT_SERVER_TOKEN | — | 认证令牌 |
--workspace | — | 自动检测 | 工作区 ID |
--timeout | — | 10000 | 请求超时（毫秒） |
--tls-ca | CRAFT_TLS_CA | — | 自签名 TLS 证书路径 |
--json | — | false | 原始 JSON 输出，便于脚本 |
--send-timeout | — | 300000 | send等待超时 |
🔐 远程 TLS 服务器（wss://）自签证书时加上--tls-ca /path/ca.pem即可。
常见问题排查
| 现象 | 原因 | 解决 |
|---|---|---|
Connection timeout | 服务器未启动或地址错误 | 确认服务器在运行并核对--url |
AUTH_FAILED | token 不对 | 检查CRAFT_SERVER_TOKEN与服务器一致 |
PROTOCOL_VERSION_UNSUPPORTED | 版本不匹配 | CLI 与服务器升级到同版本 |
No workspace available | 尚无工作区 | 用桌面应用或 API 先创建 |
总结
craft-cli 的 14 个命令形成了清晰的三层结构：诊断层（ping / health / versions / --validate-server）保障连通性，资源层（workspaces / sessions / connections / sources）摸清现状，操作层（session / send / cancel / run / invoke / listen）完成真正的工作。其中run一步到位，--json让一切输出可脚本化——把这套 CLI 接进 CI 或定时任务，你的 AI Agent 就能 7×24 无人值守地跑起来了。
【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
