集成平台 CLI 使用说明

集成平台 CLI（命令行工具）用于在终端或脚本中访问集成平台，包括管理连接流、查询连接器与节点能力、处理通讯录集成和同步，以及查询平台服务的运维日志。本文面向集成实施、平台运维和开发人员，帮助你完成安装、环境配置、认证和常用查询，并了解写操作的安全边界。

当前安装包名称为 digitalsee-ai-flow-cli，执行命令仍为 ai-flow。命令名称不代表能力仅限于 AI Flow：flow log 查询连接流的运行记录，service-log 查询当前环境、当前账号权限范围内的平台服务日志，两者用于不同层面的排障。

本文命令以 CLI 0.9.15 为基线。平台端是否开放相应接口、账号是否拥有权限，以及可查询的日志范围，取决于目标环境配置。Skill 是可选的 AI 助手辅助能力，不是安装和使用 CLI 的前提。

准备工作

安装可运行当前 CLI 发行包的 Node.js 和 npm，并确保终端能访问 npm 软件源。

向平台管理员取得正确的平台地址，确认本机到目标环境的网络与证书可用。实时日志还需要网络代理允许 WebSocket 连接。

按任务准备权限：查询连接流需要相应资源的读取权限；修改配置需要编辑权限；平台服务日志查询需要目标环境开放日志接口并授予相应访问权限。登录成功不代表拥有全部权限。

首次操作优先使用测试环境。创建、测试、发布、立即同步或删除之前，明确对象、影响范围、停止条件和恢复方法。

日志可能包含用户信息、内部地址、业务载荷或凭据片段。只在受控终端和文件中处理，脱敏后再向他人或 AI 助手提供。

安装并检查 CLI

检查本地运行环境

在终端执行：

预期两个命令均返回版本号。若找不到命令，先安装或修复 Node.js 与 npm，再继续安装 CLI。

安装 CLI 并核对版本

安装本文使用的版本：

预期版本为 0.9.15，帮助中包含 profile、auth、flow、knowledge、link、sync、org 和 service-log 等命令。

不希望全局安装时，可以按次运行，例如：

升级前先记录当前版本，核对目标版本所需参数；不要仅因 Skill 版本不同就更换 CLI 版本。

配置环境并完成登录

Profile 用于保存不同环境的连接配置。本文将 test 作为示例名称，https://platform.example.com 是示例地址；执行前替换成管理员确认的名称和地址。

创建或选择目标 Profile

先列出现有环境：

已有目标 Profile 时直接使用，不重复创建。首次使用时执行：

在本机核对 Profile 的地址，不要将完整配置输出粘贴到公开渠道。后文每条平台命令都显式使用 --profile test，避免误用默认环境。

确认实际生效的连接配置

Profile 的选择优先级是：命令行 --profile、环境变量 AI_FLOW_PROFILE、profile use 设置的默认 Profile。

此外，当前工作目录中的项目级 .ai-flowrc 可覆盖所选 Profile 中的配置。先在本机查看实际配置：

如果实际地址与预期不一致，停止平台请求，由配置负责人核对项目级覆盖；不要只根据 Profile 名称判断环境正确。不要提交含认证信息的项目配置，也不要为绕过证书错误将 --insecure 作为默认设置。

检查认证，必要时完成浏览器授权

先检查状态：

认证失效或尚未登录时执行：

按 CLI 给出的链接，由你本人在浏览器完成授权，保持终端命令运行并等待回调。需要更长授权时间时，可使用 auth login --timeout 180。遇到验证码、多因素认证或企业登录时，由你本人处理。

授权结束后，再次执行同一 Profile 的 auth status --json。确认状态中的 loggedIn 与环境符合预期，才继续查询。不要把令牌作为示例写入脚本或聊天。

检查点：实际生效的地址正确，认证状态可用，后续操作固定在同一环境。切换环境后重新查询流、节点、账号和日志 ID，不沿用其他环境的实例 ID。

选择命令入口

CLI 可以直接使用，不要求先加载 Skill。

任务	命令入口	用途
管理连接地址与环境	`config`、`profile`	查看配置，创建、切换与管理 Profile
管理认证	`auth`	登录、查看认证状态、退出
查询连接器与动作	`knowledge`	搜索节点、触发器、动作及配置 schema
管理连接流	`flow`	查询、创建、更新、节点配置、校验、发布与上下线
排查某次连接流执行	`flow log`	查询运行记录、节点输入输出及子执行
通讯录集成与同步	`link`、`sync`	上游集成、下游同步、映射检查与同步任务操作
查询组织结构	`org`	搜索与选择组织节点
查询平台整体运维日志	`service-log search`	按时间、服务、级别、关键词或 Trace ID 查询历史服务日志
跟随平台服务日志	`service-log stream`	通过 WebSocket 接收符合条件的实时日志

查看具体命令的当前参数，例如：

查询平台整体运维日志

平台服务日志不以某条连接流为查询前提。它可用于排查当前环境中的身份服务、账号服务、网关等平台组件问题。CLI 支持用 --service-type 指定 iam、acm、ncm、adm、mdm、nginx 等服务标识；实际有哪些服务及日志，按目标部署核对，不将该列表理解为每个环境都有完整日志。

平台服务日志与操作审计、业务数据记录也不是同一种证据。不要因为查询到某条服务日志，就推断某项业务变更已经持久生效。

查询历史日志

确定时间范围和排障线索

准备故障时间或相对时间范围，并至少选择服务类型、关键词、级别、Trace ID 中的一个线索。先限定范围，避免直接提取大量平台日志。

以下示例查询最近 15 分钟 iam 服务的错误日志，最多返回 50 条：

也可以按关键词查询，例如：

timeout 是示例关键词。请替换成故障日志中实际可能出现的文本，不要把未命中解释为没有故障。

按固定时间或 Trace ID 缩小范围

复盘历史问题时可以指定起止时间。以下时间是格式示例，执行前替换成实际窗口，并确认终端与日志时间的时区口径：

已有 Trace ID 时，先将 TRACE_ID 设置为实际值，再执行：

--request-id 对链路 Trace ID 做精确匹配，但不能替代时间条件。不要使用流 ID、节点 ID 或日志 ID 代替它。

检查查询结果与覆盖范围

先检查返回的 ok，再读取 data 中的日志，结合时间、级别、host、trace_id 与 message 定位问题。字段可能因日志来源而为空。

历史查询结果中的 total 表示本次返回条数，不是该时间段的全部命中数量。接近 --limit 时，缩小时间窗口、服务或关键词后再查；不要把有限结果称为完整日志导出。多次查询可能有重叠，汇总时核对重复记录。

无结果时依次核对实际环境、时间及其时区、服务标识、关键词与权限，每次只放宽一个条件。接口报错时先解决认证、权限或服务可用性问题，不连续重试宽范围查询。

历史查询的常用参数如下：

参数	是否必填	格式与含义
`--time-range`	与 `--start-time` 二选一	相对范围，如 `30s`、`15m`、`3h`、`7d`；这里的 `m` 表示分钟
`--start-time`	与 `--time-range` 二选一	`yyyy-MM-dd HH:mm:ss`；需要复现固定窗口时优先使用
`--end-time`	否	配合固定开始时间；不传时以服务端请求时刻为结束时间
`--limit`	否	默认 `50`，帮助声明上限 `500`；使用正整数
`--level`	否	日志级别，例如 `INFO`、`WARN`、`ERROR`
`--service-type`	否	服务标识，如 `iam`、`acm`、`nginx`；需与目标部署一致
`--keyword`	否	日志正文关键词
`--request-id`	否	实际链路 Trace ID，精确匹配
`--json`	否	以 JSON 输出，便于脚本处理

只选择一种时间方式：不要同时传 --time-range 与 --start-time。使用相对时间方式时，不要再用 --end-time 拼接固定结束时间；需要固定窗口时改用起止时间。

实时跟随日志

按过滤条件启动实时观察

需要观察接下来发生的问题时运行：

该命令建立 WebSocket 连接。这里 --limit 20 是单次拉取批量，--max 100 是收到 100 条后退出，不是观察 100 秒。若迟迟没有足够的匹配日志，仍需由你按观察边界停止。

至少指定能定位本次问题的过滤条件；不要为了让流更快退出而扩大到无关服务或用户数据。

处理逐行结果并停止连接

实时模式的 --json 输出是 NDJSON，即每行一条 JSON 记录，不是一个完整的 JSON 数组。逐行检查 ok：日志记录在 data 中，错误信息应单独处理。

收到足够证据或达到约定的观察时间后，按 Ctrl+C 停止。结束日志观察不会下线平台服务，也不会重跑业务。连接断开或出现错误记录时，不能仅凭进程结束就判断故障已恢复。

查询连接流与运行日志

查询配置和节点能力

定位连接流并检查配置

按名称查询并保留实际流 ID：

测试流程 是示例过滤词，替换为实际名称。结果可能分页，查找不到时核对名称、页码和访问范围。

将 FLOW_ID 设置为当前环境查得的流 ID，再执行：

analyze 用于查看节点和执行结构，validate 校验配置完整性，不实际运行业务。校验通过不能证明凭据有效、下游写入完成或流程已经上线。

查询当前环境的连接器与动作

例如搜索名称中包含钉钉的节点：

从实际返回中确定目标连接器，将 CONNECTOR_ID 设置为当前环境的真实标识，再执行：

查询触发器动作时使用 knowledge actions 的 --trigger。按返回 schema 核对必填字段和鉴权要求，不照搬模板或其他环境中的实例 ID。账号存在也不证明外部应用权限已经授予。

排查一次连接流执行

查询运行记录并打开详情

将 FLOW_ID 设置为实际流 ID 后执行：

从返回记录中选择故障那次执行，将其 ID 设置为 LOG_ID：

结合节点状态、输入、输出和错误信息判断，不只看整流状态。长 ID 保持字符串，避免脚本将其转换为浮点数后丢失精度。

按当前执行的 Base ID 下钻

需要查看循环、条件或其他子执行时，先从上述日志详情取得本次执行的 base_id，将其设置为 BASE_ID，再执行：

不要用节点配置中的 nodeId 代替 base_id。子执行也可能分页；查看不到内容时先确认 ID 来源、父日志与页码，不据此判断流程没有执行。

若证据指向平台服务错误，再结合对应故障时间和 Trace ID 查询 service-log。流日志不一定包含可关联的 Trace ID，没有该值时用实际时间和服务线索继续定位，不编造关联标识。

注意：flow log list 与 service-log search 的时间枚举不同。前者帮助中的 1m 表示约 30 天的范围，后者的 1m 表示 1 分钟；跨日志命令不要直接复用时间参数。

创建、变更和运行连接流

以下命令涉及配置写入或真实业务副作用，只在对象与影响范围已确认时使用。只想排障时不需要执行本节。

先校验准备好的流程定义

先按当前节点 schema 准备包含 nodes 和 connections 的流程定义 JSON，将真实文件路径设置为 FLOW_FILE。执行本地格式预检：

--dry-run 不创建平台对象，只检查输入格式。即使通过，也不能证明定义能在目标环境运行；缺少账号、必填字段或有效引用时，继续完善定义。

按授权创建并独立读回

确认允许创建后，才去掉 --dry-run：

从返回中取得新流 ID，再用 flow analyze 和 flow validate 独立核对。修改已有流前先记录原配置；复杂节点配置分别查看 flow node --help、flow edge --help、flow variables --help，不要把 flow update 当作整份节点定义的通用更新命令。

通讯录任务使用专门的 link 与 sync 模板和检查能力，不能把标准流的创建方式直接套用到所有通讯录任务。

分别决定测试、发布与下线

节点测试可能调用外部系统，写入数据或发送通知。先将 NODE_ID 和 FLOW_ID 设置为本次获授权的对象，再在受控数据范围内运行：

核对实际业务输出和目标记录，不能仅凭 ok:true 判断业务完成。发布或下线是另外的决定，确认影响后才执行相应命令：

上述两行分别是发布与下线示例，不是应连续执行的操作序列。执行后独立核对状态、运行日志与必要的业务结果。失败时先确认是否已部分生效，避免重试产生重复写入。

通讯录场景先查看 ai-flow link --help 或 ai-flow sync --help，选择模板并核对挂载点、鉴权账号、用户与部门映射及适用的账号关联。sync-now 可能先启用尚未启用的连接器；“立即同步”不是只读检查，也不等同于检查映射。

在脚本中处理输出

支持 --json 的命令可以输出结构化结果；它是子命令选项，不要假定每个命令或顶层都支持相同参数。

单次查询先检查进程退出状态和 ok，再按命令契约读取 data 或顶层业务字段。创建命令的 ID 不一定放在 data 中。

ok:true 表示 CLI 请求处理成功，不替代节点业务输出、写后读回或最终目标系统验收。

service-log stream --json 应逐行解析，并处理其中的错误记录，不能按一个大 JSON 文档解析。

不依赖表格列宽或中文提示编写解析逻辑。输出中即使已有部分遮挡，也需检查自由文本、个人信息和业务载荷后再分享。

平台服务日志查询没有独立的租户选择参数。本次查询范围由实际连接配置、认证上下文和服务端权限决定，不因改变关键词就切换了租户。

验证结果

按本次目标检查，不执行与当前任务无关的写操作：

目标	验收方式
CLI 安装可用	`--version` 符合预期，所需子命令的 `--help` 可读取
环境与认证正确	实际生效地址、目标 Profile 与认证状态一致，并能完成获准的只读请求
历史服务日志查询可用	请求处理没有报错，结果的时间、服务或 Trace 与已知故障窗口对应；记录过滤条件和返回上限
实时日志观察可用	收到符合过滤条件的逐行记录，错误记录已处理，达到停止条件后连接结束
连接流配置可用	创建或修改后独立读回与期望一致，结构问题已处理或披露
业务结果符合预期	在获授权的测试对象上，输入、节点输出、目标记录和日志能对应；重复、空值与失败处理符合方案

没有日志命中只证明本次条件下未返回记录，不证明平台没有异常。没有执行真实节点测试时，将业务验证记录为未执行，不能由结构检查推断通过。

常见问题

找不到 ai-flow 命令

先执行 node --version 与 npm --version，确认 CLI 安装没有失败，再核对 npm 全局可执行目录是否加入终端的 PATH。可以先用本文的固定版本 npx 命令验证包是否可运行，避免反复全局安装。

指定了 test，为什么请求仍指向其他环境

检查 --profile 的位置、AI_FLOW_PROFILE 和当前目录的 .ai-flowrc 覆盖。以实际生效配置为准，不只看 Profile 名称。不要把包含凭据的配置文件交给他人排查。

平台日志查询提示缺少时间条件或参数冲突

历史查询必须指定 --time-range 或 --start-time，且两者不能同时出现。起止时间使用带引号的 yyyy-MM-dd HH:mm:ss 格式；--limit 使用正整数且不超过声明上限。

登录有效，为什么查不到服务日志

分别核对日志查询权限、平台端接口是否开放、服务是否采集日志、时间与时区、服务标识和关键词。连接流读取权限不等同于服务日志权限；不要用关闭证书校验或扩大到其他环境来绕过问题。

实时命令一直不退出

--max 是接收条数上限，不是超时。过滤条件下没有足够日志时，按约定的观察时长主动 Ctrl+C；它不会为了凑满条数返回无关记录。

停用或回滚

停止实时日志观察使用 Ctrl+C，不需要重置配置或下线业务服务。

需要停止某条连接流时，确认精确对象后使用下线操作，再核对状态与日志。下线不代表已经撤销外部写入或删除。

恢复配置前保留变更前后快照，按目标平台支持的版本或恢复能力处理；已写入的外部数据另行核对和补偿。

删除流程、重置连接器、删除 Profile 和清除认证是独立操作，不能作为普通排障的默认步骤。

不再使用某个环境时，按实际需要退出该 Profile 的登录；先用 ai-flow auth logout --help 核对影响范围，不为结束一次查询而清除其他环境的凭据。

准备工作#

安装并检查 CLI#

配置环境并完成登录#

选择命令入口#

查询平台整体运维日志#

查询历史日志#

实时跟随日志#

查询连接流与运行日志#

查询配置和节点能力#

排查一次连接流执行#

创建、变更和运行连接流#

在脚本中处理输出#

验证结果#

常见问题#

找不到 ai-flow 命令#

指定了 test，为什么请求仍指向其他环境#

平台日志查询提示缺少时间条件或参数冲突#

登录有效，为什么查不到服务日志#

实时命令一直不退出#

停用或回滚#