SiraCLI

Sira AI 命令行工具 - 企业级 AI Agent 平台的 CLI 客户端

安装

pip install siracli

快速开始

1. 配置 API 地址

siracli auth set-url http://localhost:8000

2. 登录

siracli auth login
# 输入邮箱和密码

3. 查看状态

siracli auth status
siracli system health

认证 (auth)

siracli auth login                       # 登录（无参=浏览器 device flow，任意认证方式）
siracli auth login -e <email> -p <pass>  # 密码登录（老用户兼容；不推荐给 agent）
siracli auth login --with-token          # 从 stdin 读一个 bearer token（CI 友好）
siracli auth logout                      # 登出（清本地 token.json）
siracli auth status                      # 查看认证状态（含凭证类型/来源）
siracli auth set-url <url>               # 设置 API 地址

# 管理 PAT（给 agent / CI 的限范围、可吊销凭证）
siracli auth token create -n <name> [--scope orchestrator:write ...] [--ttl-days 90]
siracli auth token list                  # 列出我签发的 PAT
siracli auth token revoke <id>           # 吊销

🔑 agentic 认证（密码不进 agent）：凭证按 SIRACLI_API_KEY(PAT) → SIRACLI_TOKEN → ~/.siracli/token.json 顺序解析。给 agent / CI 用：管理员一次性签发 PAT，放进宿主 环境变量 SIRACLI_API_KEY，无需 login。device flow 的浏览器步复用平台多方式登录 （微信/钉钉/SSO/密码），与认证方式无关。详见 devdocs/SIRACLI_AGENTIC_AUTH_RFC.md。

Agent 管理 (agent)

siracli agent list              # 列出所有 Agent
siracli agent get <id>          # 获取 Agent 详情
siracli agent create -n <name> --display-name <display> -m <model-id> -s <system-prompt>  # 创建 Agent
siracli agent update <id>       # 更新 Agent
siracli agent delete <id>       # 删除 Agent

创建 Agent 示例（提示词是必需的）：

siracli agent create \
  -n my_chat_agent \
  --display-name "聊天Agent" \
  -m <MODEL_ID> \
  -s "你是一个有用的AI助手，总是尽力帮助用户解决问题" \
  -d "用于日常对话的AI助手"

Agent 可选参数：

• -s, --system-prompt - 系统提示词（必需） - 定义 Agent 的行为和人格
• -t, --temperature - 温度参数 (0.0-2.0)
• -x, --max-tokens - 最大 token 数
• --planning-prompt - 复杂任务的规划提示词
• --planning-strategy - 规划策略: none, react, plan_and_execute, reflexion
• --enable-memory - 启用对话记忆
• --memory-type - 记忆类型: none（关闭）或 summarize_at_limit（默认，约 15% 上下文窗口时自动摘要）
• --tools - MCP 工具 ID（可多次使用）
• --knowledge-bases - 知识库 ID（RAG，可多次使用）
• --toolbox-toolsets - GenAI Toolbox 工具集 ID（可多次使用）
• --skill - 技能包 ID（仅限 DeepAgents SubAgent 使用，可多次使用）
• --fallback-model - 故障转移备用模型 ID（可多次 → fallback_model_ids）
• --retrieval-config-json - Agent 对其知识库的检索行为，JSON（retrieval_config）
• --structured-output-config-json - 结构化/JSON 输出，JSON（structured_output_config）
• --memory-config-json / --retry-config-json - 高级记忆 / 重试策略，JSON
• --streaming - 启用流式响应

关于 skill_ids 参数： --skills 参数用于为 Agent 关联技能包，仅在 DeepAgents 编排器中作为 SubAgent 被引用时生效。当该 Agent 被作为 SubAgent 委托时，其关联的技能包会被加载到 /skills/{subagent_name}/ 目录，供 SubAgent 使用。

Orchestrator 管理 (orchestrator)

siracli orchestrator list               # 列出编排器
siracli orchestrator get <id>           # 获取编排器详情
siracli orchestrator create -n <name> --display-name <display> -t <type>  # 创建编排器
siracli orchestrator update <id>        # 更新（写入草稿，需 publish 才生效）
siracli orchestrator publish <id>       # 发布草稿 → 上线（审批开启时转审批流）
siracli orchestrator discard-draft <id> # 丢弃未发布的草稿
siracli orchestrator delete <id>        # 删除编排器

⚠️ orchestrator chat 已废弃。与编排器对话请走应用：先建一个应用接到该编排器，再用 siracli application chat <app_id> -m <msg>（见应用管理）。

💡 草稿/发布模型：orchestrator create 直接上线；之后 orchestrator update 只写草稿、运行时仍用已发布版本，须 orchestrator publish 才生效。组织开启审批门时 publish 转为提交审批。

编排器类型 (--type/-t):

• single - 单 Agent 编排
• supervisor - 监督者模式
• collaboration - 协作模式
• workflow - 工作流模式 (复杂，请使用 Web 控制台)
• conditional - 条件路由 (复杂，请使用 Web 控制台)
• external - 外部服务 (复杂，请使用 Web 控制台)
• deep_agents - 深度 Agent (基于 LangGraph 的多智能体协作)
• knowledge_base - 知识库编排 (复杂，请使用 Web 控制台)

Supervisor 编排器 (supervisor)

一个"调度官"按需把任务派给下属（worker）智能体，粘性多轮 + 越界自动交回：派给某 worker 后，后续轮次直接进上次那个 worker，用户意图越界时 worker 自动交回主管重新分配（"越界即交回"规则由系统自动注入，无需在 worker 提示词里手写）。完整实战示例见用户手册的 gym-support 健身房客服 案例。

# --agents 加 worker（≥2 个）；主管自己的 LLM 用 --ai-model-id + 可选提示词/采样参数
siracli orchestrator create -n gym-support -D "客服热线" -t supervisor \
  --ai-model-id <MODEL_ID> \
  --agents <WORKER_1> --agents <WORKER_2> --agents <WORKER_3> \
  --system-prompt "判断来意，派给对的专员，一次只派一个" \
  --temperature 0.3 --max-tokens 1500

siracli orchestrator publish <id>    # 发布后才能调用

参数（supervisor 专用）：

• --ai-model-id - 主管自己的 LLM（必填）
• --agents - worker 智能体 ID（可多次，至少 2 个）
• --system-prompt / --temperature / --max-tokens - 主管的路由提示词与采样参数（均可选；prompt 不填用内置默认）
• --supervisor-agent-id - 可选：把一个现有智能体包装成主管

Deep Agents 编排器 (deep_agents)

Deep Agents 是一种基于 LangGraph 的高级多智能体编排模式，支持 SubAgent 委托、文件系统操作、任务规划等能力。

# 创建 Deep Agents 编排器
siracli orchestrator create \
  -n my_deep_agent \
  --display-name "我的深度智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  [--subagent-model-id <SUBAGENT_MODEL_ID>] \
  [--subagent <AGENT_ID>] \
  [--skill <SKILL_ID>] \
  [--tool <TOOL_ID>] \
  [--system-prompt <PROMPT>] \
  [--backend-type <state|store|filesystem|local_shell>] \
  [--backend-path <PATH>] \
  [--recursion-limit 25] \
  [--enable-checkpoint | --disable-checkpoint]

必需参数：

• -n, --name - 编排器名称（唯一标识）
• -D, --display-name - 显示名称
• -t, --type - 编排类型，设为 deep_agents
• --ai-model-id - 主 LLM 模型 ID（必填）
• --system-prompt - 系统提示词（必填）

可选参数：

参数	说明	默认值
--subagent-model-id	SubAgent 默认模型 ID	使用 --ai-model-id
--subagent	SubAgent 的 Agent ID（可多次使用添加多个）	无
--skill	技能包 ID（可多次使用添加多个）	无
--tool	MCP 工具 ID（可多次使用添加多个）	无
--system-prompt	主 Agent 系统提示词	默认研究助手提示词
--backend-type	Backend 存储类型	state
--backend-path	文件系统后端路径（backend-type=filesystem 时使用）	/tmp/deep_agents
--recursion-limit	LangGraph 递归限制	25
--enable-checkpoint	启用检查点（保存会话状态）	启用
--timeout	执行超时时间（秒）	120
--enabled	创建后启用编排器	启用

Backend 类型：

• state - 内存存储（适合小文件，默认）
• store - 持久化存储（Redis/PostgreSQL）
• filesystem - 文件系统存储（适合大文件）
• local_shell - 本地 shell 执行（仅开发环境）
• sandrpod - SandrPod 远程沙箱（需额外配置 Server URL 和 Sandbox 名称）

SandrPod Backend 可选参数：

参数	说明	默认值
--backend-api-url	SandrPod Server URL	http://localhost:8080
--backend-sandbox	Sandbox 名称	default
--backend-timeout	执行超时时间（秒）	60
--backend-use-session	是否使用 Session 模式保持状态	true

使用 SandrPod Backend 示例：

siracli orchestrator create \
  -n sandbox_agent \
  --display-name "沙箱智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个研究助手..." \
  --backend-type sandrpod \
  --backend-api-url http://localhost:8080 \
  --backend-sandbox my-sandbox

SubAgent 格式：

• 直接指定 Agent ID：--subagent <AGENT_ID>
• 预定义类型：--subagent predefined:research-agent

创建示例：

# 最简创建（使用相同模型）
siracli orchestrator create \
  -n my_deep_agent \
  --display-name "我的深度智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个AI助手..."

# 带技能包和工具
siracli orchestrator create \
  -n research_assistant \
  --display-name "研究助手" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个研究助手..." \
  --skill <SKILL_ID_1> \
  --skill <SKILL_ID_2> \
  --tool <TOOL_ID>

# 带 SubAgent
siracli orchestrator create \
  -n multi_agent \
  --display-name "多智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个多智能体助手..." \
  --subagent <AGENT_ID_1> \
  --subagent <AGENT_ID_2>

# 使用文件系统后端
siracli orchestrator create \
  -n file_agent \
  --display-name "文件智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个文件处理助手..." \
  --backend-type filesystem \
  --backend-path /tmp/my_deep_agents

# 使用 SandrPod 远程沙箱后端
siracli orchestrator create \
  -n sandbox_agent \
  --display-name "沙箱智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个沙箱执行助手..." \
  --backend-type sandrpod \
  --backend-api-url http://localhost:8080 \
  --backend-sandbox my-sandbox

更新 Deep Agents 编排器：

siracli orchestrator update <ORCHESTRATOR_ID> \
  [--ai-model-id <MODEL_ID>] \
  [--subagent-model-id <MODEL_ID>] \
  [--subagent <AGENT_ID>] \
  [--skill <SKILL_ID>] \
  [--tool <TOOL_ID>] \
  [--backend-type <TYPE>] \
  [--recursion-limit <N>] \
  [--enable-checkpoint | --disable-checkpoint]

查看编排器详情：

siracli orchestrator get <ORCHESTRATOR_ID>

输出示例：

============================================================
Orchestrator Details
============================================================
ID                   xxx-xxx-xxx
Name                 my_deep_agent
Display Name         我的深度智能体
Type                 deep_agents
Status               ● Active
Created At           2026-03-30T00:00:00

Deep Agents Config:
  AI Model ID: xxx
  SubAgent Default Model: xxx
  SubAgents (2):
    - agent_ref: xxx-xxx
    - agent_ref: xxx-yyy
  Tool IDs (1):
    - xxx-zzz
  Skill IDs (1):
    - xxx-skill
  Backend Type: state
  Recursion Limit: 25
  Checkpoint: Enabled

AI 模型管理 (model)

siracli model list               # 列出 AI 模型
siracli model get <id>           # 获取模型详情
siracli model create -n <name> -p <provider> -m <model-name>  # 创建模型配置
siracli model update <id>        # 更新模型配置
siracli model delete <id>       # 删除模型配置
siracli model test <id>          # 测试模型连接

模型提供商 (--provider/-p):

• openai, claude, deepseek, qwen
• azure_openai, local, custom

应用管理 (application)

siracli application list                  # 列出应用
siracli application get <id>              # 获取应用详情
siracli application create -n <name> --display-name <display> -p <platform> -o <orchestrator-id>  # 创建应用
siracli application update <id>           # 更新应用
siracli application delete <id>           # 删除应用
siracli application info <id>             # 获取应用连接信息
siracli application chat <id> -m <msg>    # 与应用对话(流式)

应用平台类型 (--platform/-p) — 共 10 种：

• webclient - 内嵌 Web 聊天
• api_service - OpenAI 兼容 REST API
• wecom / wework / wework_aibot - 企业微信（应用 / AI Bot）
• weixin_kf - 微信客服
• feishu_bot - 飞书机器人
• dingding - 钉钉
• webhook - 通用 Webhook
• custom - 自定义

非 api_service 平台需要平台专属配置，用 --platform-config-json（或 @path/to.json）传入；缺必填字段时服务端返回 422 + 具体错误。

聊天模式

Web 类型应用（需要登录）:

siracli application chat <app_id> -m "你好"

API 类型应用（使用 API Key）:

siracli application chat <app_id> -m "你好" -k <api_key>

🧵 有状态多轮：默认每次调用是独立单轮。要测多轮（Supervisor 粘性、对话记忆等），复用同一个 -s <session> —— 服务端按该 session 续接记忆；不带 -s 则无状态。

siracli application chat <app_id> -k <key> -s sess-1 -m "我想取消会籍"
siracli application chat <app_id> -k <key> -s sess-1 -m "会员ID 88888"   # 同 session → 接上文

API Key 管理 (apikey)

siracli application apikey list -a <app_id>           # 列出应用的 API Key
siracli application apikey get <key_id>               # 获取 API Key 详情
siracli application apikey create -a <app_id> -n <name>  # 创建 API Key
siracli application apikey update <key_id>            # 更新 API Key
siracli application apikey delete <key_id>            # 删除 API Key
siracli application apikey test <key_id>               # 测试 API Key

MCP 工具 (mcp)

siracli mcp list-tools             # 列出 MCP 工具
siracli mcp list-services          # 列出 MCP 服务
siracli mcp info <id>              # 获取 MCP 工具/服务详情
siracli mcp test <id>              # 测试 MCP 工具连接
siracli mcp create -n <name> -t <type>  # 创建 MCP 工具
siracli mcp delete <id>            # 删除 MCP 工具

MCP 工具类型 (--type/-t):

• registry - 注册表类型（从远程注册表加载）
• manual - 手动类型（本地命令行）
• builtin - 内置类型
• service - 服务类型（HTTP 接口）

服务类型 MCP 工具参数:

• --protocol/-p - 协议类型: sse, streamable-http, stdio
• --service-url/-u - 服务 URL

人工审批 (HITL × Card)

LangGraph Human-in-the-Loop 与跨 channel 卡片审批。三层配置叠加，所有 层都通过 CLI 暴露。详见 devdocs/HITL_INTERACTIVE_CARD_DESIGN.md。

Layer 1: MCP 工具自身（兜底默认）

工具作者标记某个工具默认要审批：

# 创建时
siracli mcp create -n delete_db -t service \
  --protocol streamable-http --service-url https://… \
  --requires-approval \
  --approval-decisions approve,reject \
  --approval-description "AI 想清空数据库 {args.target}"

# 后期开关
siracli mcp update <tool-id> --requires-approval
siracli mcp update <tool-id> --no-requires-approval
siracli mcp update <tool-id> --approval-decisions approve,reject,edit
siracli mcp update <tool-id> --approval-description "确认执行 {tool_name}"

# 查看
siracli mcp info <tool-id>     # 末尾会列 HITL Approval 区块

Service 类型工具的 per-tool 白/黑名单

一个 MCP service 通常含 N 个工具（如 tavily-mcp 含 search / extract / crawl / map ...）。如果对整个 service 勾"需要审批"，所有工具都会拦——多数场景太粗。--hitl-mode + --hitl-tool 让你按工具名细化：

# 白名单：只对 tavily_crawl 拦（爬整站较激进），其它默认放行
siracli mcp create -n tavily -t service \
  --protocol streamable-http --service-url https://… \
  --requires-approval \
  --hitl-mode whitelist \
  --hitl-tool tavily_crawl

# 黑名单：默认全审，但 tavily_search 调用频繁不想被打扰
siracli mcp update <tool-id> \
  --hitl-mode blacklist \
  --hitl-tool tavily_search \
  --hitl-tool tavily_extract

# 退回到全审（删除 per-tool 配置）
siracli mcp update <tool-id> --clear-hitl-per-tool

# update 时只换工具列表（mode 保持原样）
siracli mcp update <tool-id> --hitl-tool new_tool_a --hitl-tool new_tool_b

仅对 service 类型 MCP 有意义；stdio 单工具直接用 --requires-approval 就够了。配置存在 configMetadata.hitl_per_tool。

Layer 2: Orchestrator（编排器）

按业务场景给工具加白/黑名单，或一键静默整编排器。single / supervisor / collaboration / deep_agents 任一类型都生效——后端从 deep_agents_config JSONB 列读取，不区分 orchestration_type。

# DeepAgents（含 ai_model / system_prompt 等其他字段一起创建）
siracli orchestrator create -n my_orch -D 客服 -t deep_agents \
  --ai-model-id <id> -s "You are…" \
  --interrupt-on send_email \
  --interrupt-on execute \
  --interrupt-off ls            # 显式关掉某个 tool 默认 requires_approval

# Single 编排器（最常见的"一个 Agent + 工具"模式也可以挂 HITL）
siracli orchestrator create -n simple_bot -D 简单助手 -t single \
  --agent-id <agent_id> \
  --interrupt-on delete_db      # 调 delete_db 前弹卡片

# 整编排器静默（开发/调试 / 批量 cron 等场景）
siracli orchestrator update <orch-id> --hitl-disabled
siracli orchestrator update <orch-id> --no-hitl-disabled

# 增量加 / 减规则（与 existing.interrupt_on 合并，不覆盖其它字段）
siracli orchestrator update <orch-id> --interrupt-on transfer_money
siracli orchestrator update <orch-id> --interrupt-off send_email

# 脚本化批量配（完整 dict）
siracli orchestrator update <orch-id> --interrupt-on-json '{
  "delete_db": true,
  "execute": {"allowed_decisions": ["approve","reject"]},
  "send_email": false
}'

# 清空编排器层规则
siracli orchestrator update <orch-id> --clear-interrupt-on

# 查看（任意 orchestration_type 都会显示 HITL 区块）
siracli orchestrator get <orch-id>

Layer 3: Application（应用，最高优先级）

部署级覆盖：同一编排器在不同 application 走不同策略。

# 创建时
siracli application create -n my_app -D Bot -p api_service \
  -o <orchestrator-id> \
  --hitl-disabled \                            # 整应用静默（OR-merge 编排器层）
  --interrupt-override delete_db \             # 强制开启某个工具审批
  --interrupt-override-off send_email          # 强制关闭某个工具审批

# 后期切换
siracli application update <app-id> --hitl-disabled
siracli application update <app-id> --no-hitl-disabled
siracli application update <app-id> --interrupt-override transfer_money
siracli application update <app-id> --interrupt-override-off ls
siracli application update <app-id> --interrupt-overrides-json \
  '{"delete_db": {"allowed_decisions": ["approve"]}}'
siracli application update <app-id> --clear-interrupt-overrides

# 查看
siracli application info <app-id>   # 末尾会显示 HITL (application layer) 区块

合并语义速记

Layer	字段	合并行为
1 (MCP 工具)	requires_approval + approval_decisions + approval_description	兜底默认
2 (编排器)	hitl_disabled (bool) + interrupt_on (per-tool)	覆盖 layer 1
3 (应用)	hitl_disabled (bool) + interrupt_overrides (per-tool)	覆盖 layer 1+2

hitl_disabled 是 OR 合并：编排器或应用任一勾选都静默。 "管理员强制开启被静默的编排器" 是另一个尚未实现的字段 (hitl_required，V2 计划)。

知识库 (kb)

完整 RAG 管理:知识库 CRUD + 检索,外加 doc / qa / category / folder 子组。

# 知识库生命周期 + 查询
siracli kb list
siracli kb info <id>
siracli kb create -n my-kb -D "我的库" --llm-model <id> --embedding-model <id> [--parser auto]
siracli kb update <id> --status disabled       # active / disabled
siracli kb delete <id>
siracli kb rebuild <id>                          # 重建索引
siracli kb query <id> -q "问题..." [--mode mix] [--top-k 5] [--stream]   # 检索

# 文档(上传是 multipart;from-url/sitemap 是抓取)
siracli kb doc upload <kb_id> -f ./file.pdf [--folder-id N]   # -f 可传单文件
siracli kb doc upload <kb_id> -f ./docs/ -r [--folder-id N]   # 或目录批量(-r 递归)
siracli kb doc from-url <kb_id> <url> [--js]
siracli kb doc from-sitemap <kb_id> <base_url> [--max-pages N] [--filter <正则>]
siracli kb doc list <kb_id>
siracli kb doc get|download|retry|delete <kb_id> <doc_id>

# QA 对(FAQ) + 分类
siracli kb qa create <kb_id> -q "问题" -a "答案" [--channel all] [--category-id N]
siracli kb qa list|search <kb_id> ...           # search = 向量搜索
siracli kb qa import <kb_id> -f ./qa.json        # 或 --csv 走 CSV
siracli kb category create|list|tree|update|delete <kb_id> ...

# 文档文件夹
siracli kb folder create|tree|update|move|delete <kb_id> ...

检索模式 --mode:mix(向量+图谱,默认)/ local / global / hybrid / naive / bypass / qa_only / doc_only。解析器 --parser:auto / markitdown / vlm / mineru。 文档解析是异步的,上传后用 kb doc list 看 status,完成后再查询。

数据集成 (GenAI Toolbox)

数据集成由三层组成：数据源 source（连数据库）→ 数据工具 tool（参数化 SQL / 查询定义）→ 工具集 toolbox/toolset（工具分组，挂到编排器）。

数据源 (source)

siracli source kinds                 # 列出可用数据源类型(● 已实现 / ○ 规划中)
siracli source kinds --all           # 含规划中的类型
siracli source schema <kind>         # 看某类型的连接配置字段(建源该填什么)
siracli source list                  # 列出数据源
siracli source get <id>              # 详情(连接配置脱敏)
siracli source delete <id>           # 删除
siracli source validate <id>         # 真连测试(可选 -q 测试查询)
siracli source test-query <id> -q "SELECT * FROM t LIMIT 5"   # 跑一条查询

# 创建：SQL 类用便捷参数
siracli source create -n prod-pg -k postgres \
  --host db.example.com --port 5432 --database mydb \
  --user readonly --password '***' --tags production,readonly

# 创建：非 SQL 类型 / 复杂配置用 JSON
siracli source create -n my-mongo -k mongodb \
  --connection-config '{"host":"...","port":27017,"database":"d"}'

# 更新
siracli source update <id> --inactive --tags prod

数据工具 (tool)

注意：这里的 tool 是数据工具（SQL/查询），与 MCP 工具 siracli mcp 不是一回事。

siracli tool kinds <source_kind>     # 列出某数据源类型可用的工具类型(只显示已实现的)
siracli tool kinds <source_kind> --all  # 含规划中(未实现)的工具类型
siracli tool schema <tool_kind>      # 看某工具类型的字段(要不要 statement / 参数结构)
siracli tool list                    # 列出数据工具(可 -s 按数据源过滤)
siracli tool get <id>                # 详情(含 statement / parameters)
siracli tool delete <id>             # 删除
siracli tool validate <id>           # 验证工具定义

# 自由 SQL 工具(*-execute-sql 类，LLM 直接写 SQL，无需 statement)
siracli tool create -n run_sql -d "执行只读 SQL 查询" \
  -k postgres-execute-sql -s <source_id>

# 参数化 SQL 工具(需 statement + parameters)
# 占位符首选 :name —— MySQL / Postgres 通用, 按名字绑定(与参数声明顺序无关),
# 且无需 shell 转义。驱动原生 ?(MySQL) / $1(Postgres) 也支持, 但按声明顺序
# 绑定且绑死方言。两种风格不可混用。
siracli tool create -n user_by_id -d "按 ID 查用户" \
  -k postgres-sql -s <source_id> \
  --statement "SELECT * FROM users WHERE id = :id" \
  --parameters '[{"name":"id","type":"integer","description":"用户ID"}]'

siracli tool update <id> --timeout 60 --max-rows 1000

工具集 (toolbox)

siracli toolbox list                 # 列出工具集
siracli toolbox info <id>            # 工具集详情
siracli toolbox create -n analytics -D "分析工具集" \
  -t <tool_id_1> -t <tool_id_2>      # 创建(-t 可多次)
siracli toolbox update <id> -t <tool_id>   # 替换工具列表
siracli toolbox delete <id>          # 删除

# 端到端：工具集挂在 agent 上，编排器再引用该 agent
siracli agent create -n data-agent --display-name 数据助手 \
  -m <model_id> -s "你是数据分析助手" --toolbox-toolsets <toolset_id>
siracli orchestrator create -n my_orch -D 数据助手 -t single --agent-id <agent_id>

Skill 管理 (skill)

# 列表和搜索
siracli skill list                              # 列出所有 Skills
siracli skill search <keyword>                    # 搜索 Skills
siracli skill search weather --status published   # 按状态筛选
siracli skill info <id>                          # 获取 Skill 详情

# 创建和更新
siracli skill create -n <name> -f <file.md>    # 从文件创建
siracli skill create -n <name> -f ./skill-dir/  # 从目录创建
siracli skill update <id> -n <name>             # 更新元数据
siracli skill update <id> -f <file.md>          # 更新单文件
siracli skill import-into <id> <file.zip>       # 导入到现有 Skill

# 导入导出
siracli skill import-url <url>                   # 从 URL 导入
siracli skill import-file <file.zip>             # 导入为新 Skill
siracli skill export <id> -o <output.zip>       # 导出为 ZIP

# 安装到本地
siracli skill install <id>                      # 安装到本地 Claude
siracli skill install <id> -p claude            # 指定平台
siracli skill install <id> -d ./my-skills/      # 自定义目录

# 版本控制
siracli skill versions <id>                    # 查看版本历史
siracli skill restore <id> <version>           # 恢复到指定版本

# 删除
siracli skill delete <id>                       # 删除 Skill（软删除）

安装自动检测逻辑：

1. 当前目录有 .claude 文件夹 → 安装到 $(pwd)/.claude/skills/
2. 当前目录有 openclaw.json → 安装到 ~/.openclaw/skills/
3. 否则 → 安装到 ~/.claude/skills/

系统 (system)

siracli system health            # 健康检查
siracli system stats             # 系统统计
siracli system info              # CLI 和 API 信息
siracli system version           # 版本信息

配置

配置文件存储在 ~/.siracli/token.json

{
    "api_url": "http://localhost:8000",
    "token": "your-session-token",
    "user": {
        "id": "...",
        "name": "...",
        "email": "..."
    }
}

完整示例：从创建到调用 API

以下示例展示如何通过 CLI 创建 Agent、编排器、应用、API Key，并使用 API Key 调用。

第一步：查看可用资源

# 查看可用的 AI 模型
siracli model list

# 查看可用的 MCP 工具（可选）
siracli mcp list-tools

第二步：创建 Agent

Agent 是实际执行任务的单元，需要绑定模型和提示词。

# 查看现有 Agent
siracli agent list

# 创建新 Agent（MODEL_ID 从 model list 获取）
siracli agent create \
  -n my_chat_agent \
  --display-name "聊天Agent" \
  -m <MODEL_ID> \
  -s "你是一个有用的AI助手，总是尽力帮助用户解决问题" \
  --description "用于聊天的Agent"

重要：-s/--system-prompt 是创建 Agent 的必需参数，定义 Agent 的行为和人格。

第三步：创建编排器

编排器负责任务编排，single 类型表示单 Agent 编排。

# 创建单 Agent 编排器（需要指定 agent-id）
siracli orchestrator create \
  -n my_orchestrator \
  --display-name "我的编排器" \
  -t single \
  --agent-id <AGENT_ID> \
  --description "简单的单Agent编排"

第四步：创建应用

应用是对外暴露的接口，API 类型支持 API Key 调用。

# 创建 API 类型应用
siracli application create \
  -n my_api_app \
  --display-name "我的API应用" \
  -p api_service \
  -o <ORCHESTRATOR_ID>

第五步：创建 API Key

# 为应用创建 API Key
siracli application apikey create \
  -a <APPLICATION_ID> \
  -n test_key

重要：创建成功后返回的 API Key（api_sk_xxx）只会显示一次，请妥善保存！

第六步：使用 API Key 调用

# 使用 API Key 调用应用（OpenAI 兼容接口）
siracli application chat <APPLICATION_ID> \
  -m "你好，请介绍一下你自己" \
  -k <API_KEY>

API 调用地址

API 端点地址为：{API_URL}/v1/chat/completions

# 查看当前配置的 API 地址
siracli auth status

# 直接用 curl 调用
curl -X POST "{API_URL}/v1/chat/completions" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<APPLICATION_ID>",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行
python -m siracli.cli --help