CLI 命令

数据面板

数据面板是一个 CRM 管道 — 线索、交易、任务或任何结构化数据。

列出面板

imbrace data-board list [--json]

创建面板

imbrace data-board create [--name <name>] [--json]

不传 --json 时，命令会在输入名称后交互式提示输入自由格式的键值对。

创建字段

imbrace data-board create-field <boardId> --name <fieldName> --type <fieldType> [--json]

有效的字段类型（16 种）：ShortText、LongText、Number、Date、Email、Phone、Currency、SingleSelection、MultipleSelection、Checkbox、Assignee、MultipleAssignee、Link、Notes、Origin、Priority。

创建条目

imbrace data-board create-item <boardId> --fields '<json>' [--json]

--fields 是一个由 { board_field_id, value } 对象组成的 JSON 数组：

imbrace data-board create-item <boardId> --fields '[
  {"board_field_id": "<fieldId>", "value": "Acme Corp"},
  {"board_field_id": "<fieldId>", "value": "50000"}
]' --json

列出条目

imbrace data-board list-items --board-id <boardId> [--limit 20] [--skip 0] [--q <search>] [--json]

更新条目

imbrace data-board update-item <boardId> <itemId> --data '<json>' [--json]

--data 是一个由 { key, value } 对象组成的 JSON 数组。

删除条目

imbrace data-board delete-item <boardId> <itemId> [--yes] [--json]

导出为 CSV

imbrace data-board export-csv --board-id <boardId> [--out ./board.csv]

不传 --out 时，将 CSV 输出到标准输出。

AI 代理

AI 代理是一个配置好的助手（LLM + 提示词 + 行为）。创建时会原子性地预配助手、Web 频道和用例模板。

发现

imbrace ai-agent list [--json]
imbrace ai-agent list-providers [--json]
imbrace ai-agent list-models --provider-id <providerId> [--json]
imbrace ai-agent list-folders [--search <query>] [--json]
imbrace ai-agent list-files --folder-id <folderId> [--json]

查看 / 删除

imbrace ai-agent get <agentId> [--json]
imbrace ai-agent delete <agentId> [--yes] [--json]

创建 / 更新标志

create 和 update 接受相同的标志。update 通过 PUT-merge 保留未更改的字段。

标志	映射到	说明
身份
`--name` / `-n`	`name` + `title`	创建时为必填
`--description` / `-d`	`description` + `short_description`	在 UI 中标题下方显示
`--instructions` / `-i`	`instructions`	系统提示词
模型
`--model`	`model_id`	默认为 `Default`（系统提供商）
`--provider-id`	`provider_id`	UUID，默认为 `system`
`--mode`	`mode`	`standard` / `advanced`
`--temperature`	`temperature`	0.0–2.0，默认 0.1
行为设置
`--personality`	`personality_role`
`--core-task`	`core_task`
`--tone`	`tone_and_style`
`--response-length`	`response_length`	`short` / `medium` / `long`
`--banned-words`	`banned_words`	逗号分隔的输出过滤器
`--category`	`category`	`Support` / `Sales` / `Marketing` / `Team` / `Other`
`--guardrail-id`	`guardrail_id`	附加安全护栏
`--preload-information`	`preload_information`	上下文中的静态信息
知识支持
`--folder-ids`	`folder_ids`	逗号分隔的知识中心文件夹 ID
`--default-folder-id`	`default_folder_id`
`--knowledge-hubs`	`knowledge_hubs`	逗号分隔的知识中心 ID
`--board-ids`	`board_ids`	逗号分隔的数据面板 ID
`--file-ids`	`file_ids`	逗号分隔的文件 ID
运行时开关（支持 `--no-X`）
`--show-thinking`	`show_thinking_process`	默认为 false
`--streaming`	`streaming`	默认为 true
`--use-memory`	`use_memory`	默认为 true
输出
`--yes` / `-y`	—	跳过删除确认
`--json`	—	机器可读输出
`--id-only`	—	仅打印新代理的 ID

完整创建示例

imbrace ai-agent create \
  --name "Customer Support Specialist" \
  --description "Senior AI customer support agent" \
  --instructions "You are a senior customer support specialist..." \
  --personality "Friendly and professional" \
  --core-task "Answer product inquiries, help track orders" \
  --tone "Polite, professional, warm" \
  --response-length "medium" \
  --banned-words "stupid, idiot" \
  --category "Support" \
  --provider-id "e2629292-7e9f-4d55-ba18-6827747eab33" \
  --model "gpt-4o-mini" \
  --temperature 0.3 \
  --folder-ids "69bb82faa2cc764639bc6bdb" \
  --board-ids "brd_e5450d76-84d4-4c34-8b13-3d0f1873b53b" \
  --json

代理类型

平台在 agent_type 下存储 4 种不同的代理类型。CLI 通过专用主题或 --agent-type 标志暴露它们：

UI 创建选项	CLI 命令	后端 `agent_type`
AI AGENT	`imbrace ai-agent create`	`agent`（默认）
ORCHESTRATOR	`imbrace orchestrator create`	`team_lead`
DOCUMENT AI	`imbrace document-ai create`	`document_ai`
GUARD RAIL	`imbrace guardrail create`	（非代理 — 独立资源）

ai-agent create 上的 --agent-type 标志接受 agent、assistant、conversational 或 workflow。对于 Document AI，请使用专用 document-ai 主题。对于 Orchestrator，请使用 orchestrator 主题。

Document AI

Document AI 代理从非结构化文档（PDF、图片、扫描表单）中提取结构化 JSON。每个代理都有一个定义提取字段的模式、指导 LLM 的指令以及模型 + 提供商。存储为 AI 代理，agent_type: "document_ai"。

增删改查

imbrace document-ai list [--search <q>] [--all] [--json]
imbrace document-ai get <agentId> [--json]
imbrace document-ai create -n "<name>" -i "<instructions>" --model <id> \
  (--schema '<json>' | --schema-file <path>) \
  [--provider-id <uuid>] [--description <text>] [--workflow-name <name>] \
  [--json] [--id-only]
imbrace document-ai update <agentId> [--name | --instructions | --model | --provider-id | --schema | --schema-file | --description | --workflow-name] [--json]
imbrace document-ai delete <agentId> [--yes] [--json]

list 默认为过滤 documentAiOnly: true。传入 --all 以包含常规代理。

处理文档

imbrace document-ai process \
  --url <pdf-or-image-url> \
  --org-id <orgId> \
  [--agent-id <id>] [--model <id>] [--instructions <text>] \
  [--board-id <boardId>] [--language <lang>] \
  [--additional-instructions <text>] \
  [--chunk-size <n>] [--max-concurrent <n>] [--max-retries <n>] \
  [--no-enhanced-processing] [--json]

需要 --agent-id（使用代理存储的模型 + 指令）或 --model（覆盖）。

建议模式

imbrace document-ai suggest-schema --url <url> --org-id <orgId> [--model <id>] [--json]

要求 LLM 检查示例文档并提出提取模式。

模式示例

{
  "invoice_number": { "type": "string", "description": "Invoice ID" },
  "total_amount":   { "type": "number" },
  "due_date":       { "type": "string", "format": "date" }
}

编排器

编排器是一个 AI 代理，存储时 agent_type: "team_lead"，将工作委托给 sub_agents / team_leads。对应 UI 创建对话框中的 ORCHESTRATOR 选项。

imbrace orchestrator list [--json]
imbrace orchestrator get <id> [--json]
imbrace orchestrator create -n "<name>" -i "<routing instructions>" \
  --sub-agents <id1>,<id2> [--team-leads <id3>,<id4>] \
  [--description <text>] [--model <id>] [--provider-id <uuid>] [--temperature <0-2>] \
  [--json] [--id-only]
imbrace orchestrator delete <id> [--yes] [--json]

后端特性（自动处理）

CLI 解决了三种平台行为，调用者无需了解 — 但在调试原始 SDK 响应时很有用：

agent_type: "team_lead" 是编排器标记 — 没有独立的 is_orchestrator 布尔值。Web 应用也做同样的转换。
sub_agents / team_leads 必须是助手 ID（UUID），而不是用例 ID（uc_*）。 CLI 自动通过 client.agent.get() 查找解析你传入的任何 uc_*。
createUseCase 在设置到助手负载时会静默丢弃上述两个字段。 CLI 分两步完成：创建 → chatAi.updateAiAgent PUT 以应用它们。

get 获取底层助手，以便 sub_agents / team_leads 正确显示（它们存在于助手上，而非用例上）。

安全护栏

安全护栏是一个内容安全/合规层，通过 ai-agent create 上的 --guardrail-id 附加到 AI 代理。对应 UI 创建对话框中的 GUARD RAIL 选项。

imbrace guardrail list [--json]
imbrace guardrail get <id> [--json]
imbrace guardrail create -n "<name>" -i "<rules>" \
  [--model nim-nemo|model-armor] \
  [--guardrail-provider-id <uuid>] [--org-id <orgId>] \
  [--description <text>] \
  [--unsafe-categories "violence,hate,sexual"] \
  [--custom-unsafe-patterns "regex1,regex2"] \
  [--competitor-keywords "X,Y"] \
  [--json] [--id-only]
imbrace guardrail update <id> -n -i --model [partial flags] [--json]
imbrace guardrail delete <id> [--yes] [--json]

后端特性（自动处理）

org_id 是必填项，但 SDK 类型将其标记为可选。如果你不传 --org-id，CLI 通过 client.account.getAccount() 自动获取。
model 不是常规的 LLM 名称 — 它是安全护栏模型：
- nim-nemo（NVIDIA NIM Nemo）— CLI 默认值
- model-armor（Google）
- 或任何自定义安全护栏提供商的模型（配合 --guardrail-provider-id）
model-armor 忽略 instructions、custom_unsafe_patterns 和 competitor_keywords。 CLI 自动移除它们。
后端返回 guardrails_config_id，而非 _id。 CLI 对此进行规范化，因此 --id-only 和 get <id> 按预期工作。

工作流

工作流是一个节点链：触发器触发，然后动作按顺序执行。

节点类型

类型	作用	CLI 支持
`PIECE_TRIGGER`	流程何时运行	`node add --type trigger`
`PIECE`	之后运行什么	`node add --type action`
`EMPTY`	设置触发器前的占位符	只读
`ROUTER`	多条件分支	`node add-raw`
`LOOP_ON_ITEMS`	遍历数组	`node add-raw`
`CODE`	内联 JavaScript	`node add-raw`

流程增删改查

imbrace workflow list [--folder-id <id|NULL>] [--json]
imbrace workflow get <id> [--json]
imbrace workflow create --name "<name>" [--folder-id <id>] [--json] [--id-only]
imbrace workflow move <flowId> --folder-id <id|NULL> [--json]
imbrace workflow delete <id> [--yes] [--json]

节点管理

imbrace workflow node list <flowId> [--json]
imbrace workflow node add <flowId> \
  --type trigger --piece <pieceName> \
  --trigger-name <triggerId> [--input '<json>'] [--json]
imbrace workflow node add <flowId> \
  --type action --piece <pieceName> \
  --action-name <actionId> \
  [--after <parentStep>] [--input '<json>'] [--json]
imbrace workflow node update <flowId> <nodeName> \
  [--input '<json>'] [--display-name <name>] [--json]
imbrace workflow node delete <flowId> <nodeName> [--yes] [--json]
imbrace workflow node add-raw <flowId> (--op-file <path> | --op '<json>' | --stdin) [--json]

组件发现

imbrace workflow piece list [--search <query>] [--json]
imbrace workflow piece detail <pieceName> [--only actions|triggers] [--json]

连接

imbrace workflow conn list [--json]
imbrace workflow conn get <connId> [--json]
imbrace workflow conn create \
  --piece <pieceName> \
  --type SECRET_TEXT|OAUTH2|CLOUD_OAUTH2|BASIC_AUTH|CUSTOM_AUTH \
  --value "<token-or-json>" \
  [--display-name <name>] [--external-id <id>] [--json] [--id-only]
imbrace workflow conn delete <connId> [--yes] [--json]

文件夹（分类）

imbrace workflow folder list [--json]
imbrace workflow folder get <folderId> [--json]
imbrace workflow folder create --name "<name>" [--json] [--id-only]
imbrace workflow folder update <folderId> --name "<newName>" [--json]
imbrace workflow folder delete <folderId> [--yes] [--json]

平台自动创建 4 个系统文件夹：

UI 分类	API 文件夹名称
渠道工作流	`Channel Workflow`
面板自动化	`Board Automation`
AI 代理技能	`AI Agent Capabilities`
其他	`Others`

MCP 服务器

imbrace workflow mcp list [--json]
imbrace workflow mcp get <mcpId> [--json]
imbrace workflow mcp create --name "<name>" [--json] [--id-only]
imbrace workflow mcp delete <mcpId> [--yes] [--json]
imbrace workflow mcp rotate-token <mcpId> [--yes] [--json]

生命周期与运行

imbrace workflow publish <flowId> [--json]
imbrace workflow enable <flowId> [--json]
imbrace workflow disable <flowId> [--json]
imbrace workflow run <flowId> [--payload '<json>'] [--sync] [--json]
imbrace workflow runs [--limit 10] [--json]
imbrace workflow run-detail <runId> [--json]

变量语法

表达式	含义
`{{trigger.body.X}}`	Webhook 负载中的字段 X
`{{trigger.X}}`	顶级触发字段
`{{step_1.output.Y}}`	step_1 的输出字段 Y
`{{connections.<id>.access_token}}`	连接字段

工具

打印 LLM 参考

imbrace docs [--path] [--json]

打印捆绑的 llms.txt — 一个完整的命令参考，设计用于馈送到编码代理的上下文（Claude、Cursor 等）。

标志	行为
（无）	打印完整参考到标准输出
`--path`	仅打印 `llms.txt` 的绝对路径
`--json`	以 JSON 格式输出 `{ path, content }`

imbrace docs > /tmp/imbrace-llms.txt   # 为 AI 代理保存

已知问题

字段类型 Dropdown — 后端会拒绝。请改用 SingleSelection。
Provider ID 与 _id — 使用 UUID provider_id，不要用 MongoDB _id。
仅支持英文内容 — AI 代理内容必须使用英文。
workflow run --sync 超时 — 可能在大约 60 秒时超时。请改用 workflow runs + run-detail。
先发布再启用 — workflow enable 要求先执行 workflow publish。
AI 连接器 prompt 字段 — 必须为 { prompt: { prompt: "text" } }。
流程锁定 — 如果流程在浏览器中打开，CLI 更新可能被拒绝。
创建时的 --no-use-memory — 可能不生效。请在创建后更新。
系统提供商模型 — 仅有 Default。其他名称会导致 UI 下拉框为空。