Metadata-Version: 2.4
Name: siracli
Version: 2.3.0
Summary: Sira AI Command Line Interface
Author: Sira AI Team
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: sseclient-py>=1.7.0

# SiraCLI

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

## 安装

```bash
pip install siracli
```

## 快速开始

### 1. 配置 API 地址
```bash
siracli auth set-url http://localhost:8000
```

### 2. 登录
```bash
siracli auth login
# 输入邮箱和密码
```

### 3. 查看状态
```bash
siracli auth status
siracli system health
```

## 认证 (auth)

```bash
siracli auth login              # 登录
siracli auth logout             # 登出
siracli auth status             # 查看登录状态
siracli auth set-url <url>      # 设置 API 地址
```

## Agent 管理 (agent)

```bash
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 示例**（提示词是必需的）：
```bash
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` - 记忆类型: `conversation_buffer`, `conversation_summary` 等
- `--tools` - MCP 工具 ID（可多次使用）
- `--knowledge-bases` - 知识库 ID（RAG，可多次使用）
- `--toolbox-toolsets` - GenAI Toolbox 工具集 ID（可多次使用）
- `--skill` - **技能包 ID（仅限 DeepAgents SubAgent 使用，可多次使用）**
- `--streaming` - 启用流式响应

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

## Orchestrator 管理 (orchestrator)

```bash
siracli orchestrator list               # 列出编排器
siracli orchestrator get <id>           # 获取编排器详情
siracli orchestrator create -n <name> --display-name <display> -t <type>  # 创建编排器
siracli orchestrator delete <id>        # 删除编排器
siracli orchestrator chat <id>          # 与编排器对话(流式)
```

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

### Deep Agents 编排器 (deep_agents)

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

```bash
# 创建 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 示例**：
```bash
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`

**创建示例**：

```bash
# 最简创建（使用相同模型）
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 编排器**：

```bash
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]
```

**查看编排器详情**：

```bash
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)

```bash
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)

```bash
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):
- `webclient` - Web 客户端
- `api_service` - API 服务

### 聊天模式

**Web 类型应用**（需要登录）:
```bash
siracli application chat <app_id> -m "你好"
```

**API 类型应用**（使用 API Key）:
```bash
siracli application chat <app_id> -m "你好" -k <api_key>
```

### API Key 管理 (apikey)

```bash
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)

```bash
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 工具自身（兜底默认）

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

```bash
# 创建时
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` 让你按工具名细化：

```bash
# 白名单：只对 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。

```bash
# 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 走不同策略。

```bash
# 创建时
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)

```bash
siracli kb list              # 列出知识库
siracli kb info <id>         # 获取知识库详情
```

## GenAI Toolbox (toolbox)

```bash
siracli toolbox list              # 列出工具集
siracli toolbox info <id>         # 获取工具集详情
```

## Skill 管理 (skill)

```bash
# 列表和搜索
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)

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

## 配置

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

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

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

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

### 第一步：查看可用资源

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

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

### 第二步：创建 Agent

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

```bash
# 查看现有 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 编排。

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

### 第四步：创建应用

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

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

### 第五步：创建 API Key

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

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

### 第六步：使用 API Key 调用

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

### API 调用地址

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

```bash
# 查看当前配置的 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
  }'
```

## 开发

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

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