digitalsee-ai-flow-cli 0.1.0

package/README.md

@@ -0,0 +1,631 @@
+# AI Flow CLI
+
+AI Flow 连接流命令行管理工具，通过 AI Flow v2 API 管理连接流和节点配置。
+
+## 安装
+
+```bash
+cd AI-Flow-Cli
+npm install
+npm run build
+```
+
+## 快速开始
+
+```bash
+# 1. 配置 API 连接
+ai-flow config set --base-url https://localhost:9900 --token <your-token> --insecure
+
+# 2. 查看配置
+ai-flow config show
+
+# 3. 列出所有连接流
+ai-flow flow list
+
+# 4. 分析连接流
+ai-flow flow analyze <flowId>
+```
+
+## 配置
+
+配置分为两级，优先级：项目级 (`.ai-flowrc`) > 全局 (`~/.ai-flow-cli/config.json`)。
+
+默认值：
+- `baseUrl`: `https://localhost:9900`
+- `insecure`: `true`（跳过 SSL 证书验证）
+
+### config set
+
+设置 API 配置项。
+
+```bash
+ai-flow config set --base-url <url> --token <token>
+ai-flow config set --base-url https://localhost:9900 --token abc123 --insecure
+ai-flow config set --token abc123 --project    # 保存到项目级 .ai-flowrc
+```
+
+### config show
+
+显示当前生效的配置。
+
+```bash
+ai-flow config show
+```
+
+输出示例：
+```
+配置来源: ~/.ai-flow-cli/config.json
+baseUrl: https://localhost:9900
+token:   abcd****1234
+insecure: true
+```
+
+### config reset
+
+重置配置。
+
+```bash
+ai-flow config reset             # 重置全局配置
+ai-flow config reset --project   # 重置项目级配置
+```
+
+---
+
+## 连接流操作
+
+### flow list
+
+列出所有连接流。
+
+```bash
+ai-flow flow list
+ai-flow flow list --page 1 --size 20
+ai-flow flow list --filter "测试"
+```
+
+### flow analyze
+
+分析指定连接流的所有节点及执行顺序，输出包括：
+- 流概览（ID、名称、状态、节点/边数量）
+- 节点清单表格
+- 拓扑排序后的执行顺序
+- ASCII 依赖关系图
+- 节点分组统计（触发器/动作/条件/循环/AI/其他）
+- 每节点配置详情（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 格式
+```
+
+`--format graph` 输出示例：
+```
+=================== 连接流分析: 测试流 ===================
+  ID       2056988777387053057
+  名称     测试流
+  ...
+
+--- 流程图 ---
+┌──────────────────────────┐
+│ Webhook · 接收数据v2     │
+│ N2056988936204374018     │
+│ 触发器                   │
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│ 流程变量 · 创建变量      │
+│ N2056989510396203009     │
+│ 动作                     │
+└────────────┬─────────────┘
+             │
+             ▼
+┌──────────────────────────┐
+│ 延迟 · 延迟              │
+│ N2057287474235510785     │
+│ 动作                     │
+└──────────────────────────┘
+```
+
+### flow test
+
+测试运行指定节点。可先通过 `--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 '{"millisecond": "2000"}'
+```
+
+`config.json` 示例（扁平键值，键名为配置字段的 `name`）：
+```json
+{
+    "millisecond": "2000"
+}
+```
+
+### flow node create
+
+在连接流中创建新节点。
+
+目前可视化编辑中节点的大小为 300 * 78 ， 为了不显示拥挤 建议 至少以 500 * 200 为基准进行坐标设置
+
+```bash
+# 创建普通节点
+ai-flow flow node create \
+  --flow-id <flowId> \
+  --connector-id <connectorId> \
+  --action-id <actionId> \
+  --data-file ./node-config.json \
+  --position-x 400 --position-y 200
+
+# 使用内联 JSON 数据
+ai-flow flow node create \
+  --flow-id <flowId> \
+  --connector-id <connectorId> \
+  --action-id <actionId> \
+  --data '{"url": "https://api.example.com", "method": "POST"}'
+
+# 指定节点类型
+ai-flow flow node create \
+  --flow-id <flowId> \
+  --connector-id <connectorId> \
+  --action-id <actionId> \
+  --node-type LoopNode
+
+# 创建触发器节点（流中第一个节点）
+ai-flow flow node create \
+  --flow-id <flowId> \
+  --connector-id <connectorId> \
+  --action-id <actionId> \
+  --trigger
+
+# 创建节点并配置错误处理
+ai-flow flow node create \
+  --flow-id <flowId> \
+  --connector-id <connectorId> \
+  --action-id <actionId> \
+  --error-handler-file ./error-handler.json
+```
+
+| 选项 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--flow-id` | 是 | — | 连接流 ID |
+| `--connector-id` | 是 | — | 连接器 ID |
+| `--action-id` | 是 | — | 动作 ID |
+| `--trigger` | 否 | `false` | 作为触发器节点，流无节点时会提示启用 |
+| `--node-type` | 否 | 首个节点 `StartEventNode`，否则 `ActionNode` | 节点类型或动作类型 |
+| `--account-id` | 否 | — | 账号实例 ID（需要账号鉴权时指定） |
+| `--error-handler-file` | 否 | — | 错误处理配置 JSON 文件 |
+| `--data-file` | 否 | — | JSON 文件，覆盖配置字段值 |
+| `--data` | 否 | — | JSON 字符串，覆盖配置字段值（与 `--data-file` 互斥） |
+| `--position-x` | 否 | `250` | 节点 X 坐标 |
+| `--position-y` | 否 | `150` | 节点 Y 坐标 |
+
+流程：
+1. 调 `GET /acm/actions/v2` 获取 action 的 config_schema 作为模板
+2. 自动填充字段默认值（或通过 `--data`/`--data-file` 覆盖）
+3. POST 创建节点
+
+> 不传 `--data`/`--data-file` 时使用默认值填充。`--data`/`--data-file` 内容为 `{"fieldName": "value"}` 格式的扁平 JSON，键名对应配置字段的 `name`，会合并到节点 `properties` 中。对于 ActionNode 会遍历 `sub_params` 按名称匹配；对于特殊节点类型（ConditionNode/LoopNode/SwitchNode）直接合并到 `properties` 顶层。详见 [特殊节点类型配置指南](docs/special-node-types.md)。`--trigger` 标志会筛选触发器类型的动作。
+
+> **账号配置**：当动作的 `config_schema` 包含 `account_schema_id` 时，必须通过 `--account-id` 指定账号实例 ID。若未指定，CLI 会自动列出可用的账号实例供选择。
+
+> **错误处理配置**：通过 `--error-handler-file` 指定 JSON 文件配置节点的错误处理策略，格式如下。`process_type`: `1`=中断流程, `2`=忽略错误；`warn_type`: `1`=启用告警, `0`=禁用。
+> ```json
+> {
+>   "retry": true,
+>   "retry_times": 3,
+>   "retry_interval": 5,
+>   "step_factor": 1.5,
+>   "max_retry_interval": 60,
+>   "warn_type": 0,
+>   "notify_url": "",
+>   "process_type": 1,
+>   "apply_all": false
+> }
+> ```
+
+### flow node show
+
+获取节点详细信息，包括配置参数、可选值、当前属性值等。
+
+```bash
+ai-flow flow node show <nodeId>
+ai-flow flow node show <nodeId> --format json
+```
+
+输出示例：
+```
+==================== 节点详情: N2056988936204374018 ====================
+  节点 ID   N2056988936204374018
+  节点类型  触发器
+  连接器    Webhook
+  动作      接收数据v2
+  状态      正常
+  位置      (250, 150)
+  备注      (无)
+  描述      (无)
+  账号 ID   (无)
+  账号 Schema ID  (无)
+
+--- 配置参数 (3) ---
+字段名         显示名                 类型    必填  当前值        可选值
+method         HTTP Method           SELECT  是    POST           获取(GET), 提交(POST), 更新(PUT), 删除(DELETE)
+content_type   Content Type          SELECT  否    application/json  -
+timeout        超时时间(ms)          NUMBER   否    5000           -
+
+--- 当前属性值 ---
+{ "method": "POST", "content_type": "application/json", "timeout": 5000 }
+```
+
+### flow node update
+
+更新连接流中的节点配置。
+
+```bash
+# 通过 JSON 文件更新配置
+ai-flow flow node update <nodeId> \
+  --flow-id <flowId> \
+  --data-file ./node-config.json
+
+# 通过内联 JSON 更新配置（扁平键值，深度合并到现有 properties）
+ai-flow flow node update <nodeId> \
+  --flow-id <flowId> \
+  --data '{"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
+
+# 更新节点备注
+ai-flow flow node update <nodeId> \
+  --flow-id <flowId> \
+  --note "处理用户登录请求"
+
+# 替换连接器/动作
+ai-flow flow node update <nodeId> \
+  --flow-id <flowId> \
+  --connector-id <newConnectorId> \
+  --action-id <newActionId>
+
+# 更换账号
+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
+```
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--flow-id` | 是 | 连接流 ID |
+| `--data-file` | 否 | JSON 文件，更新节点配置值 |
+| `--data` | 否 | JSON 字符串，更新节点配置值（与 `--data-file` 互斥） |
+| `--position-x` | 否 | 节点 X 坐标 |
+| `--position-y` | 否 | 节点 Y 坐标 |
+| `--note` | 否 | 节点备注 |
+| `--connector-id` | 否 | 更换连接器 ID |
+| `--action-id` | 否 | 更换动作 ID |
+| `--account-id` | 否 | 更换账号实例 ID |
+| `--error-handler-file` | 否 | 错误处理配置 JSON 文件 |
+
+> `--data` 更新时会以节点当前 `properties` 为基准进行深度合并（`deepMergePlain`），仅更新指定的字段，未指定字段保持不变。特殊节点类型（ConditionNode 的 `or_list`、LoopNode 的 `type`/`start`/`end` 等）同样通过 `--data` 写入 `properties`。详见 [特殊节点类型配置指南](docs/special-node-types.md)。
+
+### flow node delete
+
+删除连接流中的节点。
+
+```bash
+# 交互确认后删除
+ai-flow flow node delete <nodeId> --flow-id <flowId>
+
+# 跳过确认直接删除
+ai-flow flow node delete <nodeId> --flow-id <flowId> --force
+```
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--flow-id` | 是 | 连接流 ID |
+| `--force` | 否 | 跳过确认提示，直接删除 |
+
+### flow account list
+
+列出连接器下的可用账号实例。
+
+```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
+```
+
+| 选项 | 必填 | 说明 |
+|------|------|------|
+| `--account-schema-id` | 否 | 按账号模型过滤 |
+| `--format` | 否 | 输出格式: `table` 或 `json` |
+
+## flow edge connect
+
+连接节点（支持单条和批量）。通过 `--source-handle` / `--target-handle` 连接到多端点节点的特定出口/入口。
+
+**handle 说明**：部分节点有多个输出端点（多出口），连接时必须指定 `--source-handle` 选择正确的分支。常见 handle：
+
+| Handle ID | 出现节点 | 含义 |
+|-----------|---------|------|
+| `output` / `input` | 大部分节点 | 默认出口/入口，不指定时使用 |
+| `done` | LoopNode, SelfLoopNode | 循环完成后的出口（右侧上方） |
+| `loop` | LoopNode, SelfLoopNode | 继续循环的出口（右侧下方） |
+| `true` | ConditionNode | 条件为真时的出口（右侧上方） |
+| `false` | ConditionNode | 条件为假时的出口（右侧下方） |
+| `chat_model` | AgentNode, BrowserNode | 连接 AI 语言模型 |
+| `memory` | AgentNode | 连接 AI 记忆 |
+| `tools` | AgentNode | 连接 AI 工具/MCP 服务 |
+
+```bash
+# 单条连接（默认 handle：source=output, target=input）
+ai-flow flow edge connect \
+  --flow-id <flowId> \
+  --source <sourceNodeId> \
+  --target <targetNodeId>
+
+# 指定句柄 — 从条件节点的 true 分支连接到目标
+ai-flow flow edge connect \
+  --flow-id <flowId> \
+  --source <conditionNodeId> \
+  --target <targetNodeId> \
+  --source-handle true \
+  --target-handle input
+
+# 指定句柄 — 从循环节点的 done 出口连接
+ai-flow flow edge connect \
+  --flow-id <flowId> \
+  --source <loopNodeId> \
+  --target <nextNodeId> \
+  --source-handle done
+
+# 指定句柄 — 从循环节点的 loop 出口回连
+ai-flow flow edge connect \
+  --flow-id <flowId> \
+  --source <loopNodeId> \
+  --target <prevNodeId> \
+  --source-handle loop
+
+# 批量连接
+ai-flow flow edge connect \
+  --flow-id <flowId> \
+  --edges-file ./edges.json
+```
+
+`edges.json` 格式：
+```json
+[
+  {"source": "N1", "target": "N2"},
+  {"source": "N2", "target": "N3", "sourceHandle": "done", "targetHandle": "input"},
+  {"source": "N3", "target": "N4"}
+]
+```
+
+| 选项 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--flow-id` | 是 | — | 连接流 ID |
+| `--source` | 单条模式必填 | — | 源节点 ID |
+| `--target` | 单条模式必填 | — | 目标节点 ID |
+| `--source-handle` | 否 | `output` | 源节点输出句柄 |
+| `--target-handle` | 否 | `input` | 目标节点输入句柄 |
+| `--edges-file` | 批量模式必填 | — | JSON 文件，含边数组 |
+
+### flow edge disconnect
+
+删除边（断开节点连接）。
+
+```bash
+# 删除单条边
+ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <edgeId>
+
+# 删除多条边
+ai-flow flow edge disconnect --flow-id <flowId> --edge-ids <id1> <id2> <id3>
+```
+
+### flow variables show
+
+获取连接流中目标节点可用的上游变量。
+
+```bash
+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 格式输出
+```
+
+| 选项 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--node-id` | 否 | 流中第一个节点 | 目标节点 ID |
+| `--global` | 否 | `false` | 同时显示全局变量 |
+| `--format` | 否 | `table` | 输出格式: `table` 或 `json` |
+
+输出展示每个上游节点的输出字段树，以及可用的变量引用格式：
+```
+延迟时间 [NUMBER] = 1000  {{N2056988936204374018.millisecond}}
+hook_url [STRING] = https://...  {{N2056988936204374018.hook_url}}
+```
+
+变量引用语法：`{{N<node_id>.<field_path>}}`
+
+### flow variables inject
+
+在节点配置中注入变量引用。通过 `--data` 或 `--data-file` 传入包含 `{{Nxxx.field}}` 占位符的 JSON，验证引用的合法性后提交更新。
+
+```bash
+# 通过文件
+ai-flow flow variables inject <flowId> <nodeId> \
+  --data-file ./config-with-vars.json
+
+# 通过内联 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
+```
+
+`config-with-vars.json` 示例（扁平键值，值中使用 `{{N<nodeId>.<fieldPath>}}` 引用上游变量）：
+```json
+{
+    "millisecond": "{{N2056988936204374018.value}}"
+}
+```
+
+---
+
+## 知识库
+
+### knowledge categories
+
+列出所有节点分类（支持分类树展开）。
+
+```bash
+ai-flow knowledge categories
+ai-flow knowledge categories --type action
+ai-flow knowledge categories --type trigger
+```
+
+### knowledge nodes
+
+搜索节点，展示匹配的 connector 及 actions（含 nodeType、connectorId）。通过 `--name` 指定关键字时，会进一步调用 actions 接口获取每个 connector 下的完整匹配动作列表。
+
+```bash
+ai-flow knowledge nodes
+ai-flow knowledge nodes <category>
+ai-flow knowledge nodes --name "sql" --flow-id <flowId>
+ai-flow knowledge nodes --name "HTTP" --trigger --page 1 --size 20
+ai-flow knowledge nodes --json
+```
+
+| 选项 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `[category]` | 否 | — | 按分类过滤（如 `action`、`trigger`） |
+| `--name` | 否 | — | 按名称搜索关键字 |
+| `--trigger` | 否 | `false` | 是否搜索触发器节点 |
+| `--flow-id` | 否 | — | 连接流 ID |
+| `--page` | 否 | `1` | 页码 |
+| `--size` | 否 | `50` | 每页数量 |
+| `--json` | 否 | — | 以 JSON 格式输出原始数据 |
+
+输出示例：
+```
+=============== 节点列表 (共 2 个) ===============
+
+▸ MySQL_连接器 (link-123)
+    描述       MySQL 数据库连接器
+    类型       builtin
+    匹配方式   action_name
+    匹配动作 (3):
+      sql_query  执行SQL查询  nodeType: ActionNode  nodeId: act-001  connectorId: link-123
+      sql_insert 插入数据     nodeType: ActionNode  nodeId: act-002  connectorId: link-123
+      sql_update 更新数据     nodeType: ActionNode  nodeId: act-003  connectorId: link-123
+```
+
+### knowledge actions
+
+列出连接器的所有动作及配置 schema 详情。
+
+```bash
+ai-flow knowledge actions <linkId>
+ai-flow knowledge actions <linkId> --trigger     # 仅触发器
+ai-flow knowledge actions <linkId> --json        # JSON 格式输出
+```
+
+### knowledge generate-skills
+
+遍历所有分类（action / trigger / tool / mcp / model / memory）下的所有节点和动作，为每个动作生成 Markdown 文档和 JSON 结构化数据文件，按分类类型存储。
+
+```bash
+ai-flow knowledge generate-skills ./docs
+```
+
+输出：
+```
+docs/
+├── action/
+│   ├── markdown/
+│   │   ├── HTTP_发送请求.md
+│   │   └── ...
+│   └── json/
+│       ├── HTTP_发送请求.json
+│       └── ...
+├── trigger/
+│   ├── markdown/
+│   │   ├── Webhook_接收数据v2.md
+│   │   └── ...
+│   └── json/
+│       └── ...
+├── tool/
+│   └── ...
+├── mcp/
+│   └── ...
+├── model/
+│   └── ...
+└── memory/
+    └── ...
+```
+
+---
+
+## 开发
+
+```bash
+npm install
+npm run build    # 编译 TypeScript
+npm run dev      # watch 模式编译
+node dist/index.js --help
+```
+
+## 技术栈
+
+- **语言**: TypeScript
+- **CLI 框架**: Commander.js
+- **HTTP 客户端**: axios
+- **终端输出**: chalk
+
+## 项目结构
+
+```
+src/
+├── index.ts              # CLI 入口
+├── commands/
+│   ├── config.ts         # ai-flow config
+│   ├── flow.ts           # ai-flow flow
+│   └── knowledge.ts      # ai-flow knowledge
+├── api/
+│   ├── client.ts         # axios 实例（SSL、Token）
+│   ├── flow.ts           # 流 CRUD
+│   ├── node.ts           # 节点 CRUD + 测试运行
+│   ├── edge.ts           # 边管理
+│   ├── knowledge.ts      # 分类/节点搜索
+│   └── variables.ts      # 全局变量 + 输出树
+├── services/
+│   ├── flowAnalyzer.ts   # DAG 拓扑分析
+│   └── skillGenerator.ts # Skills 批量生成
+├── utils/
+│   ├── config.ts         # 配置持久化（全局 + 项目级）
+│   ├── output.ts         # 终端彩色输出
+│   └── format.ts         # 数据转换
+└── types/
+    └── index.ts          # TypeScript 类型定义
+```

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

@@ -0,0 +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;AAgEjE,wBAAgB,SAAS,IAAI,aAAa,CAKzC;AAED,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,wBAAsB,MAAM,CAAC,CAAC,GAAG,GAAG,EAClC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,OAAO,CAAC,CAAC,GAAG,GAAG,EACnC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,GAAG,EACV,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,QAAQ,CAAC,CAAC,GAAG,GAAG,EACpC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,GAAG,EACV,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,wBAAsB,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAIhE"}