digitalsee-ai-flow-cli 0.1.8 → 0.2.0

package/README.md

@@ -2,6 +2,15 @@
 
 AI Flow 连接流命令行管理工具，通过 AI Flow v2 API 管理连接流和节点配置。
 
+面向 AI Agent 调用优化：默认非交互、支持 `--json` 结构化输出、错误分类码。
+
+## 全局选项
+
+| 选项 | 说明 |
+|------|------|
+| `--quiet` | 安静模式，仅输出核心数据，无装饰文本和颜色 |
+| `--json` | 各命令独立支持，输出结构化 JSON（自动启用安静模式） |
+
 ## 安装
 
 ```bash
@@ -126,12 +135,18 @@ ai-flow flow list --filter "测试"
 
 ### flow create
 
-创建新的连接流。
+创建新的连接流。支持通过 `--data`/`--data-file` 一次性传入完整流定义（含 nodes + connections）实现原子创建。
 
 ```bash
 ai-flow flow create --name "我的连接流"
 ai-flow flow create --name "带数据的流" --data '{"nodes":[],"connections":[]}'
 ai-flow flow create --name "从文件创建" --data-file ./flow-data.json
+
+# 干跑校验（不实际创建）
+ai-flow flow create --name "测试" --data-file ./flow.json --dry-run
+
+# JSON 输出
+ai-flow flow create --name "我的流" --json
 ```
 
 | 选项 | 必填 | 说明 |
@@ -139,6 +154,13 @@ ai-flow flow create --name "从文件创建" --data-file ./flow-data.json
 | `--name` | 是 | 连接流名称 |
 | `--data` | 否 | JSON 字符串，包含 nodes 和 connections（与 `--data-file` 互斥） |
 | `--data-file` | 否 | JSON 文件路径，包含 nodes 和 connections（与 `--data` 互斥） |
+| `--dry-run` | 否 | 仅校验数据格式，不实际创建 |
+| `--json` | 否 | 以 JSON 格式输出 `{ ok, id, message }` |
+
+`--json` 输出示例：
+```json
+{ "ok": true, "id": "2056988777387053057", "message": "连接流创建成功: 我的流" }
+```
 
 ### flow update
 
@@ -163,13 +185,13 @@ ai-flow flow update <flowId> --name "新名称"
 - 每节点配置详情（config_schema 字段及当前值）
 - Edges 连接表
 
-支持四种输出格式：
+支持多种输出格式：
 
 ```bash
 ai-flow flow analyze <flowId>                        # table（默认，全量输出）
 ai-flow flow analyze <flowId> --format brief         # 简要模式：流概览 + 节点清单 + 执行顺序
 ai-flow flow analyze <flowId> --format graph         # ASCII 流程图模式：流概览 + 增强型流程图
-ai-flow flow analyze <flowId> --format json          # 纯 JSON 格式
+ai-flow flow analyze <flowId> --json                 # JSON 格式（含 $schema 字段描述结构）
 ```
 
 `--format graph` 输出示例：
@@ -203,15 +225,29 @@ ai-flow flow analyze <flowId> --format json          # 纯 JSON 格式
 
 ### flow test
 
-测试运行指定节点。可先通过 `--data`/`--data-file` 更新节点配置再测试。
+测试运行指定节点。可先通过 `--data`/`--data-file` 更新节点配置再测试。支持断言。
 
 ```bash
 ai-flow flow test <nodeId>
 ai-flow flow test <nodeId> --flow-id <flowId>
 ai-flow flow test <nodeId> --data-file ./config.json
 ai-flow flow test <nodeId> --data '{"properties": {"millisecond": "2000"}}'
+
+# 带断言：期望 status_code 为 200
+ai-flow flow test <nodeId> --expect '{"status_code": 200}'
+
+# JSON 输出
+ai-flow flow test <nodeId> --json
 ```
 
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--flow-id` | 否 | 连接流 ID |
+| `--data` | 否 | JSON 字符串，覆盖节点配置值 |
+| `--data-file` | 否 | JSON 文件路径，覆盖节点配置值 |
+| `--expect` | 否 | JSON 格式断言，如 `{"status_code": 200}` |
+| `--json` | 否 | 以 JSON 格式输出 `{ ok, data, expectErrors }` |
+
 `config.json` 示例（配置值包裹在 `properties` 中）：
 ```json
 {
@@ -272,12 +308,13 @@ ai-flow flow node create \
 | `--action-id` | 是 | — | 动作 ID |
 | `--trigger` | 否 | `false` | 作为触发器节点，流无节点时会提示启用 |
 | `--node-type` | 否 | 首个节点 `StartEventNode`，否则 `ActionNode` | 节点类型或动作类型 |
-| `--account-id` | 否 | — | 账号实例 ID（需要账号鉴权时指定） |
+| `--account-id` | 否 | — | 账号实例 ID（需要账号鉴权时指定）。若仅 1 个可用账号则自动选择；多个账号时输出列表由调用方选择 |
 | `--error-handler-file` | 否 | — | 错误处理配置 JSON 文件 |
 | `--data-file` | 否 | — | JSON 文件，覆盖配置字段值 |
 | `--data` | 否 | — | JSON 字符串，覆盖配置字段值（与 `--data-file` 互斥） |
 | `--position-x` | 否 | `250` | 节点 X 坐标 |
 | `--position-y` | 否 | `150` | 节点 Y 坐标 |
+| `--json` | 否 | — | 以 JSON 格式输出 `{ ok, id, message, nodeType, ... }` |
 
 流程：
 1. 调 `GET /acm/actions/v2` 获取 action 的 config_schema 作为模板
@@ -286,7 +323,7 @@ ai-flow flow node create \
 
 > 不传 `--data`/`--data-file` 时使用默认值填充。`--data`/`--data-file` 内容必须为 `{"properties": {"fieldName": "value"}}` 格式，配置字段包裹在 `properties` 中，键名对应配置字段的 `name`。对于特殊节点类型（ConditionNode/LoopNode/SwitchNode），额外字段（`or_list`/`branches`/`type` 等）与 `properties` 同级传入，会自动转发。详见 [特殊节点类型配置指南](docs/special-node-types.md)。`--trigger` 标志会筛选触发器类型的动作。
 
-> **账号配置**：当动作的 `config_schema` 包含 `account_schema_id` 时，必须通过 `--account-id` 指定账号实例 ID。若未指定，CLI 会自动列出可用的账号实例供选择。
+> **账号配置**：当动作的 `config_schema` 包含 `account_schema_id` 时，需要通过 `--account-id` 指定账号实例 ID。若未指定且仅 1 个可用账号，CLI 自动选择；多个账号时通过结构化输出返回可用列表。
 
 > **错误处理配置**：通过 `--error-handler-file` 指定 JSON 文件配置节点的错误处理策略，格式如下。`process_type`: `1`=中断流程, `2`=忽略错误；`warn_type`: `1`=启用告警, `0`=禁用。
 > ```json
@@ -309,7 +346,7 @@ ai-flow flow node create \
 
 ```bash
 ai-flow flow node show <nodeId>
-ai-flow flow node show <nodeId> --format json
+ai-flow flow node show <nodeId> --json
 ```
 
 输出示例：
@@ -338,54 +375,48 @@ timeout        超时时间(ms)          NUMBER   否    5000           -
 
 ### flow node update
 
-更新连接流中的节点配置。
+更新连接流中的节点配置。使用 `--patch`/`--patch-file` 做深度合并更新（`--data` 已废弃）。
 
 ```bash
-# 通过 JSON 文件更新配置
+# 通过 JSON 文件 patch 更新配置
 ai-flow flow node update <nodeId> \
   --flow-id <flowId> \
-  --data-file ./node-config.json
+  --patch-file ./node-config.json
 
-# 通过内联 JSON 更新配置
+# 通过内联 JSON patch 更新配置
 ai-flow flow node update <nodeId> \
   --flow-id <flowId> \
-  --data '{"properties": {"name":"value"}}'
+  --patch '{"properties": {"name":"value"}}'
 
-# 更新条件分支节点的 or_list
-ai-flow flow node update <nodeId> \
-  --flow-id <flowId> \
-  --data '{"or_list":[{"and_list":[{"query":"{{N123.value}}","operator":"gt","value":"100"}]}]}'
-ai-flow flow node update <nodeId> \
-  --flow-id <flowId> \
-  --position-x 400 --position-y 200
-
-# 更新节点备注
+# patch 更新 + 校验变量引用
 ai-flow flow node update <nodeId> \
   --flow-id <flowId> \
-  --note "处理用户登录请求"
+  --patch-file ./config.json \
+  --validate-vars
 
-# 替换连接器/动作
+# 更新条件分支节点的 or_list
 ai-flow flow node update <nodeId> \
   --flow-id <flowId> \
-  --connector-id <newConnectorId> \
-  --action-id <newActionId>
+  --patch '{"properties":{"or_list":[{"and_list":[{"query":"{{N123.value}}","operator":"gt","value":"100"}]}]}}'
 
-# 更换账号
-ai-flow flow node update <nodeId> \
-  --flow-id <flowId> \
-  --account-id <accountId>
+# 更新位置/备注/连接器/动作/账号
+ai-flow flow node update <nodeId> --flow-id <flowId> --position-x 400 --position-y 200
+ai-flow flow node update <nodeId> --flow-id <flowId> --note "处理用户登录请求"
+ai-flow flow node update <nodeId> --flow-id <flowId> --connector-id <id> --action-id <id>
+ai-flow flow node update <nodeId> --flow-id <flowId> --account-id <accountId>
+ai-flow flow node update <nodeId> --flow-id <flowId> --error-handler-file ./error-handler.json
 
-# 配置错误处理
-ai-flow flow node update <nodeId> \
-  --flow-id <flowId> \
-  --error-handler-file ./error-handler.json
+# JSON 输出
+ai-flow flow node update <nodeId> --flow-id <flowId> --patch-file ./config.json --json
 ```
 
 | 选项 | 必填 | 说明 |
 |------|------|------|
 | `--flow-id` | 是 | 连接流 ID |
-| `--data-file` | 否 | JSON 文件，更新节点配置值 |
-| `--data` | 否 | JSON 字符串，更新节点配置值（与 `--data-file` 互斥） |
+| `--patch` | 否 | JSON 字符串，深度合并更新节点配置值 |
+| `--patch-file` | 否 | JSON 文件路径，深度合并更新节点配置值 |
+| `--data` / `--data-file` | 否 | **已废弃**，请使用 `--patch` / `--patch-file` |
+| `--validate-vars` | 否 | 校验 patch 中的变量引用（`{{Nxxx.field}}`）合法性 |
 | `--position-x` | 否 | 节点 X 坐标 |
 | `--position-y` | 否 | 节点 Y 坐标 |
 | `--note` | 否 | 节点备注 |
@@ -393,25 +424,44 @@ ai-flow flow node update <nodeId> \
 | `--action-id` | 否 | 更换动作 ID |
 | `--account-id` | 否 | 更换账号实例 ID |
 | `--error-handler-file` | 否 | 错误处理配置 JSON 文件 |
+| `--json` | 否 | 以 JSON 格式输出 `{ ok, id, message }` |
 
-> `--data` 必须使用 `{"properties": {...}}` 完整路径配置。`--data-file` 始终覆盖（文件通常包含完整配置）。特殊节点类型的顶层字段（ConditionNode 的 `or_list`、LoopNode 的 `type`/`start`/`end` 等）与 `properties` 同级传入。详见 [特殊节点类型配置指南](docs/special-node-types.md)。
+> `--patch` 与 `--data` 的区别：`--patch` 与现有配置做深度合并，语义明确为 patch 操作；`--data` 为旧参数，语义不统一，已废弃。
 
 ### flow node delete
 
-删除连接流中的节点。
+删除连接流中的节点。默认需 `--yes` 确认（面向 Agent 的非交互模式）。
 
 ```bash
-# 交互确认后删除
+# 直接删除
+ai-flow flow node delete <nodeId> --flow-id <flowId> --yes
+
+# 不带 --yes 时输出结构化提示，由调用方二次确认
 ai-flow flow node delete <nodeId> --flow-id <flowId>
 
-# 跳过确认直接删除
-ai-flow flow node delete <nodeId> --flow-id <flowId> --force
+# JSON 输出
+ai-flow flow node delete <nodeId> --flow-id <flowId> --yes --json
 ```
 
 | 选项 | 必填 | 说明 |
 |------|------|------|
 | `--flow-id` | 是 | 连接流 ID |
-| `--force` | 否 | 跳过确认提示，直接删除 |
+| `--yes` | 否 | 跳过确认，直接删除。不带此参数时输出确认提示 JSON |
+| `--json` | 否 | 以 JSON 格式输出 `{ ok, id, message }` |
+
+### flow node list
+
+列出流中所有节点的轻量级列表。
+
+```bash
+ai-flow flow node list --flow-id <flowId>
+ai-flow flow node list --flow-id <flowId> --json
+```
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--flow-id` | 是 | 连接流 ID |
+| `--json` | 否 | 以 JSON 格式输出节点数组 `[{ id, name, type, status, position }]` |
 
 ### flow account list
 
@@ -420,13 +470,13 @@ ai-flow flow node delete <nodeId> --flow-id <flowId> --force
 ```bash
 ai-flow flow account list <connectorId>
 ai-flow flow account list <connectorId> --account-schema-id <id>
-ai-flow flow account list <connectorId> --format json
+ai-flow flow account list <connectorId> --json
 ```
 
 | 选项 | 必填 | 说明 |
 |------|------|------|
 | `--account-schema-id` | 否 | 按账号模型过滤 |
-| `--format` | 否 | 输出格式: `table` 或 `json` |
+| `--json` | 否 | 以 JSON 格式输出 |
 
 ## flow edge connect
 
@@ -497,6 +547,7 @@ ai-flow flow edge connect \
 | `--source-handle` | 否 | `output` | 源节点输出句柄 |
 | `--target-handle` | 否 | `input` | 目标节点输入句柄 |
 | `--edges-file` | 批量模式必填 | — | JSON 文件，含边数组 |
+| `--json` | 否 | — | 以 JSON 格式输出 `{ ok, edgeIds, edges }` |
 
 ### flow edge disconnect
 
@@ -508,8 +559,17 @@ ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <edgeId>
 
 # 删除多条边
 ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <id1> <id2> <id3>
+
+# JSON 输出
+ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <id1> --json
 ```
 
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--flow-id` | 是 | 连接流 ID |
+| `--edge-ids` | 是 | 要删除的边 ID（可多个） |
+| `--json` | 否 | 以 JSON 格式输出 `{ ok, removedEdgeIds }` |
+
 ### flow variables show
 
 获取连接流中目标节点可用的上游变量。
@@ -518,14 +578,14 @@ ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <id1> <id2> <id3>
 ai-flow flow variables show <flowId>
 ai-flow flow variables show <flowId> --node-id <targetNodeId>
 ai-flow flow variables show <flowId> --global              # 同时显示全局变量
-ai-flow flow variables show <flowId> --format json         # JSON 格式输出
+ai-flow flow variables show <flowId> --json                # JSON 格式输出
 ```
 
 | 选项 | 必填 | 默认值 | 说明 |
 |------|------|--------|------|
 | `--node-id` | 否 | 流中第一个节点 | 目标节点 ID |
 | `--global` | 否 | `false` | 同时显示全局变量 |
-| `--format` | 否 | `table` | 输出格式: `table` 或 `json` |
+| `--json` | 否 | — | 以 JSON 格式输出 |
 
 输出展示每个上游节点的输出字段树，以及可用的变量引用格式：
 ```
@@ -537,35 +597,222 @@ hook_url [STRING] = https://...  {{N2056988936204374018.hook_url}}
 
 ### flow variables inject
 
-在节点配置中注入变量引用。通过 `--data` 或 `--data-file` 传入包含 `{{Nxxx.field}}` 占位符的 JSON，验证引用的合法性后提交更新。
+> **已废弃**：请使用 `flow node update --validate-vars` 代替。`variables inject` 仍然可用但会输出废弃警告。
+
+在节点配置中注入变量引用。通过 `--data` 传入包含 `{{Nxxx.field}}` 占位符的 JSON，验证引用的合法性后提交更新。
 
 ```bash
-# 通过文件
-ai-flow flow variables inject <flowId> <nodeId> \
-  --data-file ./config-with-vars.json
+# 推荐：使用 flow node update --validate-vars
+ai-flow flow node update <nodeId> --flow-id <flowId> \
+  --patch-file ./config-with-vars.json --validate-vars
 
-# 通过内联 JSON
-ai-flow flow variables inject <flowId> <nodeId> \
-  --data '{"properties": {"millisecond": "{{N2056988936204374018.value}}"}}' \
-  --dry-run
-  
-# 预览模式（不实际更新）
-ai-flow flow variables inject <flowId> <nodeId> \
-  --data-file ./config-with-vars.json \
-  --dry-run
+# 旧方式（已废弃）
+ai-flow flow variables inject <flowId> <nodeId> --data-file ./config-with-vars.json --dry-run
 ```
 
-`config-with-vars.json` 示例（配置值包裹在 `properties` 中，值中使用 `{{N<nodeId>.<fieldPath>}}` 引用上游变量）：
+---
+
+### flow draft
+
+两阶段提交模式：先创建草稿流，确认后再提交。适合通过 `--data-file` 一次性传入完整流定义的场景。
+
+```bash
+# 创建草稿流（含完整 nodes + connections）
+ai-flow flow draft create --name "草稿流" --data-file ./flow.json
+ai-flow flow draft create --name "草稿流" --data-file ./flow.json --json
+
+# 提交草稿流
+ai-flow flow draft commit <flowId>
+ai-flow flow draft commit <flowId> --json
+
+# 丢弃草稿流（删除所有节点）
+ai-flow flow draft discard <flowId> --yes
+ai-flow flow draft discard <flowId> --yes --json
+```
+
+### flow validate
+
+干跑校验流配置完整性（不实际执行），检查节点配置、边连接合法性、必填字段。
+
+```bash
+ai-flow flow validate <flowId>
+ai-flow flow validate <flowId> --json
+```
+
+`--json` 输出示例：
 ```json
 {
-    "properties": {
-        "millisecond": "{{N2056988936204374018.value}}"
-    }
+  "ok": false,
+  "flowId": "123",
+  "nodeCount": 3,
+  "edgeCount": 2,
+  "errors": ["边 e1 的源节点 N4 不存在"],
+  "warnings": []
 }
 ```
 
 ---
 
+### flow log list
+
+列出流程运行日志，支持按流程、状态、时间范围筛选。
+
+```bash
+ai-flow flow log list
+ai-flow flow log list --flow-id <flowId>
+ai-flow flow log list --flow-id <flowId> --status 0 --time-range 1d
+ai-flow flow log list --page 1 --size 20 --search "error"
+ai-flow flow log list --flow-id <flowId> --json
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--flow-id` | 按流程 ID 筛选 |
+| `--page / --size` | 分页 |
+| `--status` | 运行状态：0=失败, 1=成功, 2=警告, 3=运行中, 4=手动停止, 5=超时, 6=超限 |
+| `--type` | 事件类型 |
+| `--time-range` | 时间范围：1h, 12h, 1d, 7d, 1m |
+| `--search` | 搜索文本 |
+| `--json` | 以 JSON 格式输出（敏感字段自动脱敏） |
+
+### flow log show
+
+查看某次运行的节点执行树详情。支持查看子节点循环迭代日志。
+
+```bash
+ai-flow flow log show --id <logId>
+ai-flow flow log show --id <logId> --node-id <baseId>
+ai-flow flow log show --id <logId> --child <baseId>
+ai-flow flow log show --id <logId> --child <baseId> --child-page 2 --child-size 10
+ai-flow flow log show --id <logId> --json
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--id` | 日志运行 ID |
+| `--node-id` | 查看指定节点的输入/输出详情 |
+| `--child` | 查看子节点循环迭代日志 |
+| `--child-page / --child-size` | 循环迭代分页 |
+| `--json` | 以 JSON 格式输出（敏感字段自动脱敏） |
+
+---
+
+## 身份自动化
+
+管理连接流中的身份上游/下游自动化连接器。这两类连接器本质上是**特殊的连接流**，创建后即可通过 `ai-flow link <id>` 查看，其中的节点添加、边连接、分析等操作与其他连接流一致，统一使用 `ai-flow flow` 命令。
+
+> 通过 `link create` 或 `sync create` 创建的连接器会返回 ID，该 ID 即为连接流 ID，可直接用于 `ai-flow flow list`、`ai-flow flow analyze <id>`、`ai-flow flow node create --flow-id <id>` 等命令。
+
+### link — 身份上游自动化（通讯录集成）
+
+从外部系统拉入组织与用户数据到 IDaaS。
+
+#### 连接器管理
+
+```bash
+# 列出已创建的上游连接器（名称、类型、同步周期、时间、状态）
+ai-flow link list
+
+# 查看可用模板类型（供 create --type 参考，按企业身份源/HTTP/数据库/LDAP 分组）
+ai-flow link templates
+
+# 创建上游连接器
+ai-flow link create --type DINGDING
+ai-flow link create --type HTTPFLOW --name "我的上游"
+ai-flow link create --type DBFLOW --reset   # 创建后立即套用预设模板
+
+# 重置连接器为模板初始状态
+ai-flow link reset --id <connectorId>
+```
+
+#### 同步日志
+
+```bash
+# 列出同步日志（含开始时间、结束时间、事件类型、状态）
+ai-flow link log list --connector-id <id>
+ai-flow link log list --connector-id <id> --page 1 --size 20
+ai-flow link log list --connector-id <id> --status 0 --type 1 --time-range 7d
+ai-flow link log list --connector-id <id> --json
+
+# 查看日志详情（含影响统计 + 同步明细）
+ai-flow link log show --id <logId>
+ai-flow link log show --id <logId> --detail-size 10 --detail-page 1
+ai-flow link log show --id <logId> --detail-type USER --detail-status FAILED
+ai-flow link log show --id <logId> --detail-op DELETED --detail-name "张三"
+ai-flow link log show --id <logId> --json
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--connector-id` | 连接器 ID |
+| `--page / --size` | 分页（list 命令） |
+| `--status` | 同步结果：0=失败, 1=成功, 2=进行中, -1=警告, 3=部分异常 |
+| `--type` | 事件类型：0=定时任务, 1=手动, 2=事件触发 |
+| `--time-range` | 时间范围：1h, 12h, 1d, 7d, 1m |
+| `--json` | 以 JSON 格式输出（敏感字段自动脱敏，list 和 show 均支持） |
+| `--detail-size` | 同步明细每页条数，默认 10（show 命令） |
+| `--detail-page` | 同步明细页码，默认 1（show 命令） |
+| `--detail-type` | 资源类型筛选：USER / ORG / ROLE |
+| `--detail-status` | 同步状态筛选：SUCCESS / FAILED |
+| `--detail-op` | 操作类型筛选：CREATED / UPDATED / DELETED |
+| `--detail-name` | 资源名称模糊匹配 |
+
+### sync — 身份下游自动化（通讯录同步）
+
+从 IDaaS 推送组织与用户数据到外部系统。
+
+#### 连接器管理
+
+```bash
+# 列出已创建的下游连接器
+ai-flow sync list
+
+# 查看可用模板类型
+ai-flow sync templates
+
+# 创建下游连接器
+ai-flow sync create --type HTTPPUSHFLOW
+ai-flow sync create --type HTTPPUSHFLOW --name "我的下游" --reset
+
+# 重置连接器为模板初始状态
+ai-flow sync reset --id <connectorId>
+```
+
+#### 推送日志
+
+```bash
+# 列出推送日志
+ai-flow sync log list --connector-id <id>
+ai-flow sync log list --connector-id <id> --page 1 --size 20
+ai-flow sync log list --connector-id <id> --status 0 --type 1 --time-range 7d
+ai-flow sync log list --connector-id <id> --json
+
+# 查看日志详情（含影响统计 + 推送明细）
+ai-flow sync log show --id <logId>
+ai-flow sync log show --id <logId> --detail-size 10 --detail-page 2
+ai-flow sync log show --id <logId> --detail-type ORG --detail-status SUCCESS
+ai-flow sync log show --id <logId> --json
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--connector-id` | 连接器 ID |
+| `--page / --size` | 分页（list 命令） |
+| `--status` | 同步结果：0=失败, 1=成功, 2=进行中, -1=警告, 3=部分异常 |
+| `--type` | 事件类型：0=定时任务, 1=手动, 2=事件触发 |
+| `--time-range` | 时间范围：1h, 12h, 1d, 7d, 1m |
+| `--json` | 以 JSON 格式输出（敏感字段自动脱敏，list 和 show 均支持） |
+| `--detail-size` | 推送明细每页条数，默认 10（show 命令） |
+| `--detail-page` | 推送明细页码，默认 1（show 命令） |
+| `--detail-type` | 资源类型筛选：USER / ORG / ROLE |
+| `--detail-status` | 同步状态筛选：SUCCESS / FAILED |
+| `--detail-op` | 操作类型筛选：CREATED / UPDATED / DELETED |
+| `--detail-name` | 资源名称模糊匹配 |
+
+> 前置检查：查看日志前检查连接器是否已执行过同步/推送，如有问题仅提醒不阻塞。
+
+---
+
 ## 知识库
 
 ### knowledge categories
@@ -621,7 +868,7 @@ ai-flow knowledge nodes --json
 ```bash
 ai-flow knowledge actions <linkId>
 ai-flow knowledge actions <linkId> --trigger     # 仅触发器
-ai-flow knowledge actions <linkId> --json        # JSON 格式输出
+ai-flow knowledge actions <linkId> --json        # JSON 格式输出（含 output_schema 字段）
 ```
 
 ### knowledge generate-skills
@@ -630,6 +877,8 @@ ai-flow knowledge actions <linkId> --json        # JSON 格式输出
 
 ```bash
 ai-flow knowledge generate-skills ./docs
+ai-flow knowledge generate-skills ./docs --since "2026-01-01T00:00:00Z"   # 增量更新
+ai-flow knowledge generate-skills ./docs --since "2026-01-01T00:00:00Z" --diff   # 增量 + 变化对比
 ```
 
 输出：
@@ -660,6 +909,16 @@ docs/
 
 ---
 
+## Shell Completion
+
+```bash
+# zsh
+echo 'eval "$(ai-flow completion --zsh)"' >> ~/.zshrc
+
+# bash
+echo 'source <(ai-flow completion --bash)' >> ~/.bashrc
+```
+
 ## 开发
 
 ```bash
@@ -683,7 +942,24 @@ src/
 ├── index.ts              # CLI 入口
 ├── commands/
 │   ├── config.ts         # ai-flow config
-│   ├── flow.ts           # ai-flow flow
+│   ├── auth.ts           # ai-flow auth
+│   ├── flow.ts           # ai-flow flow 父命令
+│   ├── flow/
+│   │   ├── create.ts      # flow create
+│   │   ├── update.ts      # flow update
+│   │   ├── list.ts        # flow list
+│   │   ├── analyze.ts     # flow analyze
+│   │   ├── test.ts        # flow test
+│   │   ├── node.ts        # flow node (show/create/update/delete/list)
+│   │   ├── edge.ts        # flow edge (connect/disconnect)
+│   │   ├── account.ts     # flow account list
+│   │   ├── variables.ts   # flow variables (show/inject)
+│   │   ├── log.ts         # flow log (list/show)
+│   │   ├── draft.ts       # flow draft (create/commit/discard)
+│   │   ├── validate.ts    # flow validate
+│   │   └── helpers.ts     # 共享辅助函数
+│   ├── link.ts           # ai-flow link（身份上游自动化）
+│   ├── sync.ts           # ai-flow sync（身份下游自动化）
 │   └── knowledge.ts      # ai-flow knowledge
 ├── api/
 │   ├── client.ts         # axios 实例（SSL、Token）
@@ -691,14 +967,21 @@ src/
 │   ├── node.ts           # 节点 CRUD + 测试运行
 │   ├── edge.ts           # 边管理
 │   ├── knowledge.ts      # 分类/节点搜索
-│   └── variables.ts      # 全局变量 + 输出树
+│   ├── variables.ts      # 全局变量 + 输出树
+│   ├── link.ts           # 上游连接器 API
+│   └── sync.ts           # 下游连接器 API
 ├── services/
 │   ├── flowAnalyzer.ts   # DAG 拓扑分析
 │   └── skillGenerator.ts # Skills 批量生成
 ├── utils/
+│   ├── common.ts         # JSON 安全解析
 │   ├── config.ts         # 配置持久化（全局 + 项目级）
+│   ├── encoding.ts       # Base64 编解码
+│   ├── format.ts         # 数据转换
+│   ├── mask.ts           # 敏感数据脱敏
+│   ├── oauth.ts          # OAuth 设备流
 │   ├── output.ts         # 终端彩色输出
-│   └── format.ts         # 数据转换
+│   └── updateCheck.ts    # 版本更新检查
 └── types/
     └── index.ts          # TypeScript 类型定义
 ```

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAiEjE,wBAAgB,SAAS,IAAI,aAAa,CAKzC;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,wBAAsB,MAAM,CAAC,CAAC,GAAG,OAAO,EACtC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAIpE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AACA,OAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAEjE,OAAO,EAAuB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAgGhE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGpD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAGlE;AAuCD,wBAAgB,SAAS,IAAI,aAAa,CAKzC;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,wBAAsB,MAAM,CAAC,CAAC,GAAG,OAAO,EACtC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAIpE"}