AI Flow 连接流 SKILL · 工具集

测试连接流生命周期前四步的完整链路：环境引导 →（① 需求分析）→（② 架构设计）→（③ 搭建实施，自动调用鉴权 / 特殊节点 / 字段映射横切）→（④ 测试验证，validate + review + 端到端，失败自动调用排障横切）。横切还有自学习回写——解决新坑后落库 flow-solutions、下次不重踩。每步硬门放行。

包含内容

源码在 skills/ 下；npm run build [--agent <name>] 产出 dist/<agent>/（默认 claude-code，给对应 agent 的 skill 目录）+ dist/user-data/{knowledge,flow-solutions}（给 ~/.ai-flow/，agent 无关）；bash scripts/install.sh [--agent <name>] 一条命令装好两者（走 npx skills，无需先 build）。

Skills（11 个，skills/<name>/SKILL.md）

| skill | 作用 | |------|------| | ai-flow | 入口 / 引导 skill：环境就绪检查 + 生命周期路由 + 横切说明 + 安全护栏 | | ai-flow-requirements | ① 需求分析（渐进追问 + 落盘需求文档 + 硬门） | | ai-flow-design | ② 架构设计（精确选型 + 强核验，只读） | | ai-flow-build | ③ 搭建实施（逐节点 create→test，首个含写操作的步骤） | | ai-flow-verify | ④ 测试验证（validate + review + 端到端 + 分级报告） | | ai-flow-auth | 横切·鉴权账号绑定（build 自动调用） | | ai-flow-special-nodes | 横切·特殊节点配置（条件/循环/多分支/Agent） | | ai-flow-debug | 横切·排障/日志（日志 --child 下钻、QPS 识别；verify/build 调用） | | ai-flow-ops-troubleshoot | 横切·运维日志排障（service-log search 下沉平台服务端日志取真实堆栈；debug/verify 调用） | | ai-flow-field-mapping | 横切·link/sync 字段映射（mapping show/check/add/set/delete + account-linking；build 调用） | | ai-flow-compound | 横切·自学习回写（解决新坑→去重→确认→落库 flow-solutions；debug/build/verify 调用） |

知识产物（skills/flow-solutions/、skills/knowledge/，由 install.sh 铺到 ~/.ai-flow/，agent 无关）

| 路径 | 作用 | |------|------| | flow-solutions/ | compounding 经验知识库（已沉淀 13 条：代码节点 / 定时触发器 / 表达式字段 / 不可测节点样本 / link-sync 坑 / 跨环境授权 / 改流坐标 等）；debug/build/verify grep 读、ai-flow-compound 回写 | | knowledge/node-index.md | 节点选型索引（75 连接器 / 399 动作 + 20 触发器 / 7 大分类的目录）；design 选型先查缩小范围 | | knowledge/field-config.md | 字段配置解读手册（page_control→怎么传值 / value_type→能否插值）；build 配字段前查 | | knowledge/link-sync-guide.md | 身份流(link/sync)专属流程 SOP（判型→模板→挂载点→账号→映射→运维）；design/build 走 link/sync 时查 | | knowledge/known-limitations.md | CLI 已知限制（token 2h / --status 单值 / 老画布盲区 / 日志 status 不准 / OAuth 端口随机）+ SKILL 层规避 | | knowledge/templates/ | 标准流可复用模板（data-integration 6 + todo-sync 5，每套 .md 模式 + .json 骨架）；design 复用 / build 骨架起步 |

横切依赖说明：搭建实施依赖横切技能。本包已含 ai-flow-auth、ai-flow-special-nodes、ai-flow-debug、ai-flow-field-mapping（仅 link/sync）、ai-flow-compound（自学习回写）、ai-flow-ops-troubleshoot（运维日志下沉）。build/verify 对未装的横切优雅降级（装了就调用，没装走内联兜底），不影响测标准流。

compounding 库：ai-flow-build 已把"代码节点 / 定时触发器"等节点专属坑抽到 flow-solutions/（build 回归主干，配非直觉节点前先 grep 该库）；解决新坑后由 ai-flow-compound 自动回写（去重 → 拟稿 → 用户确认 → 落库）。

本包不含 419 个节点的静态文档——节点信息通过 CLI（knowledge nodes / knowledge actions）实时查询，不依赖静态文档。

前置：安装 ai-flow CLI（必须，仅一次）

唯一的外部依赖，无法随 skill 打包，需手动安装：

npm install -g [email protected]     # 全局安装（推荐）
# 或：npx -y [email protected] <命令>

验证：ai-flow --version（需 >= 0.7.6）。固定版本，避免 latest 不兼容。

② 架构设计、③ 搭建实施会实时调用 knowledge/flow/account 等命令，需 CLI 已安装并登录才能完整测试。

配置与登录（首次使用）

单环境（最简）：

ai-flow config set --base-url <你的平台地址>
ai-flow auth login        # 输出登录 URL，浏览器授权；命令等待回调，不要中断
ai-flow auth status       # 确认登录（--json 含 activeProfile 字段）

多环境（开发 / 测试 / 生产，推荐 profile）：

ai-flow profile create dev  --base-url https://dev.example.com
ai-flow profile create prod --base-url https://prod.example.com --set-default
ai-flow profile use prod          # 切默认 Profile
ai-flow auth login                # 登当前 Profile
ai-flow profile list              # 看全部 + 当前激活项

切换优先级（高 → 低）：ai-flow --profile <name> <cmd> > AI_FLOW_PROFILE=<name> 环境变量 > ai-flow profile use。详见入口 skill「多 Profile（多环境）」段。

装上 ai-flow 入口 skill 后，以上由 agent 自动引导，无需手动记命令。

安装各 skill（一条命令、支持多 agent）

推荐：在仓库根跑 install.sh，一条命令同时装好 skill 和用户级知识产物。--agent 指定目标 agent（默认 claude-code），透传给 npx skills——CLI 自己维护各 agent 的目录映射，无需手拷。

bash scripts/install.sh                          # 默认 claude-code
bash scripts/install.sh --agent cursor           # Cursor
bash scripts/install.sh --agent 'claude-code,cursor'   # 多 agent
bash scripts/install.sh --agent '*'              # 所有支持的 agent
# 或等价：npm run setup -- --agent cursor

install.sh 做两件事：

1. skill → npx skills add . --agent <name> --global --copy -y（装到对应 agent 的用户级目录；claude-code → ~/.claude/skills/，cursor → CLI 决定）
2. 用户级数据 → ~/.ai-flow/（agent 无关、跨 agent 共享；从源 skills/ 读，不依赖 build）：
   • knowledge/ → ~/.ai-flow/knowledge/（只读、覆盖升级）
   • flow-solutions/ seed → ~/.ai-flow/flow-solutions/（13 条，仅首次铺、绝不覆盖用户累积）

⚠️ 入口 skill 名为 ai-flow，会与已装的旧全量 ai-flow skill 撞名。隔离测试时先把旧的停用 / 移走。

从构建产物（无 npx 的手动分发路径）：npm run build [--agent <name>] 产出 dist/<agent>/（默认 claude-code）+ dist/user-data/。把 dist/<agent>/<skill> 各目录放进对应 agent 的 skill 目录、dist/user-data/{knowledge,flow-solutions} 拷到 ~/.ai-flow/。此路径不经 install.sh，纯手拷。

项目级 overlay（可选）：若某项目有客户/环境专属坑，可在 <项目根>/docs/ai-flow/flow-solutions/ 建项目级条目；读取时项目级优先于用户级。per-flow 产物（<slug>-requirements.md 等）仍落项目 docs/ai-flow/。

不装这两套 skills 也能跑，但 design 选型只能盲搜 CLI、build 配字段拿不准 page_control、debug 撞坑没有现成解、compound 没地方落库——能跑但不聪明。

怎么测

① 需求分析

| 场景 | 输入示例 | 预期 | |------|---------|------| | 模糊需求逐问 | "帮我做个钉钉审批到金蝶的同步" | 一次只问一个问题，最后落盘需求文档 | | 硬门拦截 | 中途说"直接建流" | 被拦住，坚持先确认需求 |

② 架构设计

| 场景 | 预期 | |------|------| | 精确选型 | knowledge nodes/actions 搜并点名每个节点，落盘设计草案 | | 选型索引 | 选型先查 knowledge/node-index.md 缩小范围，再 CLI 核实 / 取 ID | | 字段配置 | 配字段前查 knowledge/field-config.md（page_control 定格式、value_type 定能否插值），schema 为准 | | 强核验 | flow account list 核账号，缺账号在草案标风险 | | 只读硬门 | 想直接建流时被拦：设计只读，确认才交接 build |

③ 搭建实施（核心，最吃验证）

| 场景 | 预期 | |------|------| | 搭建模式问询 | 流程创建前先问"完整搭建+测试 / 只搭框架" | | 框架模式 | 选只搭框架 → 只加节点+连线+坐标，不配置/不测，INVALID 属预期 | | 不可测节点 | webhook 等 → 跟你确认、要示例 JSON，用 --sample-output 喂样本、下游继续 | | 逐节点 create-test | 每建一个节点就 flow test，看 ok 且 output，通过才建下一个 | | 调用鉴权横切 | 遇到需账号的节点，自动按 ai-flow-auth 实搜 connectorId、account list、绑定、验证 | | 调用特殊节点横切 | 建条件/循环节点时，自动按 ai-flow-special-nodes 用 or_list/sub_params 格式、连对 handle | | 写操作安全 | 要删流/节点时必须先经你确认 | | 交接 | 全节点 SUCCESS + 测通后，提示进入测试验证 |

④ 测试验证

| 场景 | 预期 | |------|------| | 整体校验 | flow validate + flow analyze，全节点 SUCCESS 无 INVALID | | 质量 review | 指出可合并的 set_var、没必要的变量、不必要的循环 | | 端到端 + 分级 | 逐节点 e2e test 看 output；critical 阻断放行 | | 调用排障 | 失败时自动按 ai-flow-debug 用日志 --child 下钻定位 |

身份流 link/sync（设计阶段判型触发）

| 场景 | 预期 | |------|------| | 判型 | "把某系统通讯录同步到平台/反向" → ②设计按 business_type(5/6)+需求语义判为 link/sync | | 模板优先 | link/sync templates → link/sync create --type（不走 flow create）；挂载点/遍历账号/字段映射/账号关联按 knowledge/link-sync-guide.md | | 字段映射 | 自动按 ai-flow-field-mapping：mapping check/add --entity user/org/role → check-mapping 通过 |

自学习（compounding 回写）

| 场景 | 预期 | |------|------| | 解决新坑 | debug/build/verify 修复并验证后 → ai-flow-compound：双路径 grep 去重 → 拟稿 → 先经你确认（选 target：用户级跨项目 / 项目级专属） → 落库对应层 | | 复用沉淀 | 后续遇同类坑先双路径 grep flow-solutions（项目级优先、用户级兜底）命中即用，不重踩 |

产物默认落到 docs/ai-flow/<flow-slug>-{requirements,design,verify-report}.md；临时文件在 ./tmp。

生命周期 ①需求分析 + ②架构设计 + ③搭建实施 + ④测试验证；横切·鉴权 / 特殊节点 / 排障 / 字段映射 / 自学习回写；能力·框架模式 / 样本数据调试 / 选型索引 / 整流模板 / link-sync SOP / known-limitations；compounding 库 13 条。后续：⑤上线交付（可纳入 pre-launch-checklist）、⑥⑦运营。