digitalsee-ai-flow-skills 0.7.3

package/README.md

@@ -0,0 +1,95 @@
+# AI Flow Skills
+
+AI Flow 连接流平台的 AI 编码助手技能包 —— 为 Claude Code 等 AI 编码助手提供 10 个结构化技能文档，覆盖连接流全生命周期（需求 → 设计 → 搭建 → 验证）及横切关注点（鉴权、排障、字段映射、自学习）。
+
+## 前置要求
+
+需已安装 AI Flow CLI（`digitalsee-ai-flow-cli`），用于连接流操作和实时查询节点/动作信息：
+
+```bash
+npm install -g digitalsee-ai-flow-cli@latest
+```
+
+## 安装
+
+```bash
+npm install -g digitalsee-ai-flow-skills
+```
+
+安装完成后 `postinstall` 会自动将知识产物（节点索引、字段配置手册、link/sync 指南等）铺到 `~/.ai-flow/`。
+
+### 安装 skills 到 AI 编码助手
+
+```bash
+# 默认安装到 claude-code
+ai-flow-skills install
+
+# 指定 agent
+ai-flow-skills install --agent cursor
+
+# 多个 agent
+ai-flow-skills install --agent 'claude-code,cursor'
+```
+
+> `ai-flow-skills install` 执行完整的 skill 安装（`npx skills add` + 知识产物），`postinstall` 仅铺知识产物（无需交互）。
+
+### 版本检查
+
+```bash
+ai-flow-skills check       # 对比本地版本和 npm 最新版
+ai-flow-skills version     # 仅打印当前版本
+npm outdated -g digitalsee-ai-flow-skills   # npm 原生检查
+```
+
+### 复制 skills 到指定目录
+
+```bash
+# 复制到项目本地（如 .claude/skills）
+ai-flow-skills copy-to ./docs/ai-flow/skills
+
+# 指定 agent
+ai-flow-skills copy-to /path/to/agent/skills --agent cursor
+```
+
+## Skills 清单（10 个）
+
+### 生命周期 skill
+
+| skill | 阶段 | 说明 |
+|------|------|------|
+| `ai-flow` | 入口/编排 | 环境就绪检查 + 生命周期路由 + 安全护栏 |
+| `ai-flow-requirements` | ① 需求分析 | 渐进式追问、结构化需求文档产出 |
+| `ai-flow-design` | ② 架构设计 | 节点选型、数据流设计、模板匹配、鉴权核验 |
+| `ai-flow-build` | ③ 搭建实施 | 逐节点 create→test、连边、字段映射、变量注入 |
+| `ai-flow-verify` | ④ 测试验证 | 整体校验、review、端到端测试 |
+
+### 横切 skill（按症状自动触发）
+
+| skill | 触发场景 |
+|------|------|
+| `ai-flow-auth` | 节点需绑定鉴权账号 / 认证失败 |
+| `ai-flow-special-nodes` | 配置条件/循环/多分支/AI 智能体等特殊节点 |
+| `ai-flow-debug` | 测试失败、节点 INVALID、运行告警/失败日志 |
+| `ai-flow-field-mapping` | 配置 link/sync 流的字段映射（仅通讯录集成/同步流） |
+| `ai-flow-compound` | 解决新坑后回写经验知识库（自学习闭环） |
+
+## 知识产物
+
+安装后自动铺到 `~/.ai-flow/`：
+
+| 内容 | 说明 |
+|------|------|
+| `knowledge/node-index.md` | 节点选型索引（70+ 连接器/400+ 动作） |
+| `knowledge/field-config.md` | 字段配置解读手册 |
+| `knowledge/link-sync-guide.md` | 通讯录集成/同步专属 SOP |
+| `knowledge/known-limitations.md` | CLI 已知限制与规避 |
+| `knowledge/templates/` | 标准流可复用模板（11 套） |
+| `flow-solutions/` | 经验知识库（13 条已沉淀的已知坑） |
+
+## 升级
+
+```bash
+npm install -g digitalsee-ai-flow-skills@latest
+```
+
+升级后 knowledge 自动覆盖更新；flow-solutions 已存在的条目不会覆盖（保护用户累积经验）。

package/dist/claude-code/ai-flow/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ai-flow
+version: 0.7.3
+description: 当用户要用 AI Flow 连接流平台做任何事（创建/配置/review/排查连接流，对接钉钉、飞书、用友、金蝶、ERP 等 70+ 连接器）时最先触发。负责环境就绪（CLI / 登录 / baseUrl）并按生命周期路由到对应阶段 skill。
+---
+
+# AI Flow 入口 / 编排
+
+AI Flow 连接流自动化的入口。任何连接流相关任务，先过这里：先确保环境就绪，再按生命周期进入对应阶段 skill。
+
+## 第一步：环境就绪（每次任务开始前确认）
+
+按顺序确认三件事，缺哪补哪。**环境没就绪前，不要进入任何阶段。**
+
+1. **CLI 已装且版本达标** — 运行 `ai-flow --version`，需 `>= 0.6.17`。
+   - 未装或过低：提示用户 `npm install -g digitalsee-ai-flow-cli@0.6.17`（或临时 `npx -y digitalsee-ai-flow-cli@0.6.17 <cmd>`）。版本不匹配只提示风险、不阻塞。
+2. **baseUrl 已配** — 未配则 `ai-flow config set --base-url <地址>`。（经钉钉网关代理登录时，页面可能显示 127.0.0.1 开头，属正常）
+3. **已登录** — `ai-flow auth login`：
+   - 输出的登录 URL **必须发给用户**，由用户在浏览器完成授权，agent 不代劳、不跳过。
+   - 命令会起本地回调服务等待授权，**不要中断**；持续读其输出，授权成功后它会自行退出。
+   - **不要主动问"登录成功了吗"**——监测输出即可。退出后用 `ai-flow auth status` 确认；失败则提示检查 baseUrl 或重新登录。
+
+## 第二步：按生命周期路由
+
+判断用户处于连接流生命周期的哪一步，invoke 对应阶段 skill：
+
+| 用户意图 | 进入阶段 | 阶段 skill |
+|---------|---------|-----------|
+| 要建一条新流 / 只有想法、需求没清 | ① 需求分析 | `ai-flow-requirements` |
+| 需求已定，要选节点、定数据流 | ② 架构设计 | `ai-flow-design` |
+| 设计已定，要建/配/测节点 | ③ 搭建实施 | `ai-flow-build` |
+| 搭建完成，要校验 / review / 端到端测 | ④ 测试验证 | `ai-flow-verify` |
+| 要上线、运维、迭代 | ⑤–⑦ | 待加入 |
+
+**新建连接流一律从 `ai-flow-requirements` 开始**——不要跳过需求分析直接选节点、建流。
+若对应阶段 skill 尚未安装，按该阶段的常规做法继续，并提示用户该阶段 skill 正在开发。
+
+> **身份流/集成流（通讯录集成 link / 同步 sync）不是独立入口**：用户提"把某系统通讯录/组织·用户同步到平台 / 从平台推到某系统"这类需求，仍走 ①需求 → ②设计，由 **②设计按 `business_type`(5/6) + 需求语义判型**，命中则走 link/sync 专属路径（模板优先 + 挂载点 + 遍历账号 + 字段映射 + 账号关联）。详见 `~/.ai-flow/knowledge/link-sync-guide.md`。
+
+## 知识产物位置（安装后）
+
+| 内容 | 路径 | 说明 |
+|---|---|---|
+| 参考文档（node-index/field-config/templates/link-sync-guide/known-limitations） | `~/.ai-flow/knowledge/` | 只读，随 `install.sh` 升级覆盖 |
+| 经验库 · 用户级 base | `~/.ai-flow/flow-solutions/` | 平台通用坑，跨项目累积，**回写不覆盖** |
+| 经验库 · 项目级 overlay | `./docs/ai-flow/flow-solutions/` | 项目/客户专属；读取时优先于此层 |
+| per-flow 产物（需求/设计/验收） | `./docs/ai-flow/<slug>-*.md` | 项目本地交付物 |
+
+未安装时跑 `bash scripts/install.sh` 一次铺好；详见仓库根 `README.md`。
+
+## 横切技能（按症状自动触发，无需路由）
+
+这些不是生命周期某一步，而是按症状随时触发，由各阶段 skill 自动调用：
+
+- `ai-flow-auth` — 节点需绑鉴权账号时
+- `ai-flow-special-nodes` — 配置条件/循环/多分支/AI 智能体等特殊节点时
+- `ai-flow-debug` — 构建 / 运行出问题（test 失败、节点 INVALID、运行告警 / 失败日志）时
+- `ai-flow-field-mapping` — 配置 link/sync（business_type 5/6）字段映射时（仅 link/sync，build 自动调用；未装走 CLI `flow mapping` 兜底）
+- `ai-flow-compound` — 解决一个"文档没写、踩了才知道"的新坑后，回写 flow-solutions 知识库（先去重、先经用户确认）
+
+## 核心安全护栏（任何阶段都适用）
+
+- **严禁未经用户确认删除流 / 节点**：`flow delete`、`flow node delete` 不可逆，执行前必须获得用户明确授权。
+- **真写 / 不可逆动作必须用"阻塞式选择器"显式确认、讲清影响范围**（删除、`sync-now` 真同步、`flow publish` 上线、发真实通知、写库等）——用 `AskUserQuestion`（标题点明动作），**不要把这种分叉藏在文字里让用户划过**。"结构验证通过"不等于"已实测"，没真跑就如实说"未执行 / 未写数据"。
+- **不猜关键配置值**：决定运行时行为的值（目标系统、关键字段、鉴权账号）不确定时就问、或列出待确认项，绝不臆测。
+- 临时文件放 `./tmp`；持久产物（需求 / 设计文档）放 `docs/ai-flow/`（per-flow 交付物，项目本地）。

package/dist/claude-code/ai-flow-auth/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ai-flow-auth
+version: 0.7.3
+description: 当连接流节点需要绑定鉴权账号时使用——节点的 config_schema 含 account_schema_id、link/sync 流的外部系统遍历节点、review 报鉴权缺失、或测试因认证失败报错。横切技能，主要在搭建实施期触发。
+---
+
+# AI Flow 鉴权账号绑定
+
+## 核心原则
+
+让需要鉴权的节点绑上正确的账号。**connectorId 必须实时搜得、按环境而定，绝不硬编码或用模板示例值**——不同环境 connectorId 不同。
+
+## 何时需要
+
+- `knowledge actions <connectorId>` 显示节点有 `account_schema_id`
+- link/sync 流的**外部系统遍历节点**（如"遍历企业微信部门和用户"）——**必须绑**，否则测试认证失败
+- review / 测试报鉴权缺失或认证失败
+- **改已有流 / 跨环境搬来的流**，节点授权字段显示为一串陌生数字 ID（如 `2069615060622245889`）——须核这个账号在**当前环境**是否真存在
+
+## ⚠️ 改已有流的授权节点：先核账号存不存在，缺就阻塞重选（跨环境高发坑）
+
+从别环境拷来 / 导入的流，节点里带着**原环境的 `account_id`**（一串裸数字）。当前环境很可能**没有这个账号**——但 CLI 不会主动提示，直接把这串数字 ID 留着，画布上只显示数字、看不出对应哪个账号、也不知有没有效，用户误以为"改成功了"，实际一跑就认证失败。**改授权节点时必须做存在性校验：**
+
+1. **列当前环境可用账号**：`ai-flow flow account list <connectorId> --json`（connectorId 实搜，见下）。
+2. **比对节点当前 `account_id`**：`ai-flow flow node show <nodeId> --json` 取 `account_id`，看它**在不在**上一步的列表里。
+3. **不在列表 → 停下，阻塞式让用户重选**：用 `AskUserQuestion`（标题如"该授权节点在当前环境无对应账号，请选择"）把 list 里的**可用账号（名称）**列给用户挑，选定后 `flow node update ... --account-id <选中的>`。**绝不静默保留那串陌生数字 ID、也绝不臆造一个账号 ID 写进去。**
+4. **在列表 → 正常回填**，并向用户报**账号名称**（不是只甩数字 ID）确认无误。
+5. 校验后照旧 `flow node show` 确认 `account_id` 已是当前环境的有效账号。
+
+> 展示原则：涉及授权账号，一律报**账号名称**；查不到对应账号时明说"当前环境缺此授权账号、待重新配置"，不要只把数字 ID 甩给用户让他自己猜。相关沉淀见 flow-solutions `auth-account-missing-in-target-env`。
+
+## 步骤
+
+1. **取 connectorId**（实搜，禁硬编码）：`ai-flow knowledge nodes --name "<连接器名>" --json`
+2. **列可用账号**：`ai-flow flow account list <connectorId> --json`
+3. **选对账号**：按用户指定的环境 / 权限选（如通讯录读权限）；多个账号时按环境信息选正确的，不确定就问用户
+4. **绑定**：
+   - 创建时：`flow node create ... --account-id <accountId>`
+   - 已有节点：`ai-flow flow node update <nodeId> --flow-id <flowId> --account-id <accountId> --json`
+5. **验证**：`ai-flow flow node show <nodeId> --json` 确认 `account_id` 已更新
+
+## 常见错误
+
+| ❌ 错误 | ✅ 正确 |
+|--------|--------|
+| 用模板 / 文档里的示例 connectorId | `knowledge nodes` 实搜当前环境的 |
+| link/sync 遍历节点漏绑账号 | 必绑，否则测试认证失败 |
+| 随便选一个账号 | 按环境 + 权限选；不确定问用户 |
+| 绑完不验证 | `flow node show` 确认 `account_id` |
+| 授权字段留着一串陌生数字 ID 就当改成功 | 核它在不在 `flow account list`，不在就阻塞让用户重选 |
+| 只把数字 account_id 甩给用户 | 报账号**名称**；缺失标"待重新配置" |
+
+## 红旗（出现即停）
+
+- "connectorId 用文档里那个就行" → 环境不同，必须实搜
+- "账号回头再绑" → 遍历节点不绑测不过
+- "授权字段有个数字 ID，应该没问题" → 跨环境搬来的多是失效 ID，核 `account list` 存不存在，缺就阻塞重选，别静默保留

package/dist/claude-code/ai-flow-build/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: ai-flow-build
+version: 0.7.3
+description: 当连接流设计已确认、要按设计稿创建流和节点、连边、配字段、注入变量、逐节点测试时使用。连接流生命周期第 3 步（首个含写操作的步骤），承接架构设计，交接测试验证。
+---
+
+# AI Flow 搭建实施
+
+## 核心原则
+
+按设计稿把流真正建出来：`flow create` → 从触发器起**逐节点创建并测试** → 连边 → 配字段映射(仅 link/sync) → 注入变量 → 逐节点测通。**每个节点必须 `flow test` 通过且 `output` 内容正确，才创建下一个**——下游依赖上游的输出变量。
+
+## 前置
+
+读取设计文档 `docs/ai-flow/<flow-slug>-design.md`（来自 `ai-flow-design`）。没有已确认的设计就回到 `ai-flow-design`。
+**若是在改已有流**：先 `ai-flow flow analyze <flowId> --json` 存快照到 `./tmp/pre-change-<flowId>.json`（变更安全）。改已有流额外守两条：
+- **保坐标**：`node update --patch` **不要带 `position-x/y`**（patch 深合并，省略即保留原坐标）；**禁止为"整理布局"重建/删建节点**——那会把整张画布节点搅乱。要加新节点才用现有坐标公式，只给新节点算，不动既有节点。见 flow-solutions `edit-flow-preserve-node-position`。
+- **核授权**：改到含 `account_schema_id` 的节点、或看到授权字段是一串陌生数字 `account_id`（跨环境搬来的流常见）→ invoke `ai-flow-auth` 做**存在性校验**（`flow account list` 核账号在不在当前环境，不在就阻塞让用户重选，别静默保留数字 ID）。
+
+## 搭建模式（流程创建前必问 · 必须用阻塞式选择器）
+
+⚠️ **创建流之前，必须用阻塞式选择器（Claude Code：`AskUserQuestion`，标题如"选择搭建模式"）让用户显式选模式——不要把这个分叉写在普通文字里让用户划过。** 选项：
+
+- **完整搭建 + 测试**（默认）：走下面「铁律 / 搭建流程 / gate」全流程，逐节点 create→test 真跑。
+- **只搭框架（不测）**：只做建流 + 逐节点 `create`（仅 `connector`/`action`/坐标 + 创建必需字段，如特殊节点 `httpMethod`/`--node-type`）+ 连边 + 坐标；**不填**业务配置、**不注入**变量、**不测试**。结束告知："框架已就绪（结构完整、未配未测）；节点多为 `INVALID` 属预期"。**不交接 verify 端到端**。
+
+### 涉及"真写数据 / 不可逆"的执行分叉 → 单独再弹一次阻塞式选择
+
+凡是会**真写外部系统 / IDaaS 真实数据、或不可逆**的执行动作，**必须单独用阻塞式选择器问、并讲清影响范围**，绝不藏在文字末尾。
+
+🚧 **执行前置硬门：真执行（`sync-now` / `publish` / 真发通知等）前，`flow analyze` 必须显示全节点 `SUCCESS`、无 `INVALID`。** 调试没完成（有 INVALID 节点）就执行 = 必卡死 / `task is canceled`——**别拿没调完的流去跑**。link/sync 尤其注意：模板生成的**集成节点**（集成部门/用户）默认 `ext_org`/`ext_user`/`account_link` 为 None、状态 INVALID，**只配遍历节点远远不够**，要把每个节点配到 SUCCESS（见 `~/.ai-flow/knowledge/link-sync-guide.md` 第 4 步 + `ai-flow-special-nodes`）再 sync。
+
+
+- **link/sync 流**：建流 + 配映射 + `check-mapping` 通过 ≠ 真跑通（节点 `INVALID` = 从没执行）。是否 **`link/sync sync-now` 真同步**（会把外部组织/用户**真写进 IDaaS**）必须显式选：
+  - **真 sync + 真调试**：sync-now → `flow log show --child` 看真实 `error_msg`（→ `ai-flow-debug`）→ 修 → 重跑 → 真看数据落地。
+  - **只到 check-mapping、不 sync**：明确告知"结构+映射已验、但未真跑、未写数据"。
+- 其它真写动作（如发通知、写库、`flow publish` 上线）同理：先讲影响、阻塞式确认。
+
+> 原则：**"结构验证"不能冒充"实测"**。只要没真跑，就如实说"未执行 / 未写数据"，并把"要不要真跑"作为显式选择交给用户。
+
+下面「铁律 / 搭建流程 / gate」针对**完整模式**；框架模式只取其中的 create + 连边 + 坐标。
+
+## 铁律：逐节点 create → test → 下一个（完整模式）
+
+不要一次建完所有节点再测。每建一个节点：
+
+1. `flow node create`（或 `node update` 配置）
+2. `flow test <nodeId> --flow-id <flowId> --json`
+3. 确认 `ok: true` **且** `output` 内容正确
+4. 才创建下一个
+
+**`ok: true` 只表示没崩，不等于数据对**——必须看 `output`。尤其 ADAPTOR 字段（`ext_org` / `ext_user`）：空 `{}` 不会自动从上游提取，会让下游收到 `null`。
+
+**不可真实产出的节点**（webhook 接收 / 外部事件触发 / 依赖真实回调或真实业务数据才有输出）无法靠 `flow test` 真实执行——**先跟用户确认、请其提供示例 JSON**，用 `ai-flow flow node update <nodeId> --flow-id <id> --sample-output '<示例JSON>'`（或 `--sample-output-file`）写入该节点输出，下游即可用 `{{N<id>.<field>}}` 引用样本继续配置 / 测试。别卡在"测不了"。详见 flow-solutions `sample-output-for-untestable-nodes`。
+
+## 专属节点的坑 → 先查 flow-solutions
+
+代码执行、定时触发器等"非直觉"节点，配置前先 grep 两层 flow-solutions 经验库（项目级 `./docs/ai-flow/flow-solutions/` 优先、用户级 `~/.ai-flow/flow-solutions/` 兜底）查已知坑。**遇到新坑、解决并验证后 → invoke `ai-flow-compound` 回写**（先双路径去重、经用户确认选目标层），让后面不再撞。
+
+## 搭建流程（标准流程 4–8 + 10–11）
+
+1. **建流**：
+   - 标准流：`ai-flow flow create --name "<名>" --json`，记下 `flowId`。**流名要能说明用途**——`flow create` / `flow update` 只有 `--name`（**无** `--remark`/`--description`），所以流的"备注"就落在一个有信息量的 `--name`（如"钉钉审批→金蝶凭证同步"），别用"未命名流/test"。**若设计命中 `~/.ai-flow/knowledge/templates/` 模板**：模板是**"读了照搭"的参考模式，不是可直接导入的文件**——其 `.json` 用 `ref`+示例 ID 描述节点序列/连线(edges)/分支/配置形态（非 `flow create --data-file` 要的 `{nodes,connections}` 格式，**不能直接 `--data-file`**）。照模板的结构按下面逐节点 `create`，connector/action ID 一律 CLI 实查、账号实绑。（真要 `--data-file` 须自行把模板转成 `{nodes,connections}` 并替换真实 ID，一般不值当，直接照搭更稳。）
+   - **link/sync 流**：**不走 `flow create`**，用 `ai-flow link create --type <模板> --name "<名>"` / `ai-flow sync create --type <模板> --name "<名>"`（返回 ID 即 flowId）。随后配挂载点（`connector_org_ref_id`）、遍历节点绑账号、字段映射、账号关联(link)——完整步骤见 `~/.ai-flow/knowledge/link-sync-guide.md`。
+2. **逐节点创建**（从触发器起，按拓扑序）：
+   - `flow node create --flow-id <id> --connector-id <cid> --action-id <aid> [--trigger] --position-x <x> --position-y <y> --data '{"properties": {...}}'`
+   - ⚠️ **触发器节点的 `--action-id` 用 `knowledge actions <cid> --trigger --json` 取**——`flow node create` 强制要 `--action-id`，但内置触发器（定时 / Webhook 等）的 action 默认不出现在 `knowledge actions`（返回 `[]`），必须加 `--trigger` 才查得到。定时等触发器的具体配置（cron `cycle` / `startDate` / `endDate` / node-type）见 flow-solutions 库。
+   - 坐标：`x = 250 + (i % 5) * 550`，`y = 150 + floor(i / 5) * 280`（`i` 从 0）
+   - **关键节点默认写职责备注**：创建时 `flow node create --name "<一句话职责>"`（`--name` 字段义为"节点名称，描述节点用途"）；补/改备注用 `flow node update <nodeId> --flow-id <id> --note "<备注>"`（`--note` = 节点备注）。别让用户拿到一条"裸流"、看不出每个节点在干嘛。（实测：`flow create` 无备注参数、只有 `--name`；节点备注在 create 走 `--name`、update 走 `--note`。）
+   - **节点需账号** → invoke `ai-flow-auth`
+   - **特殊节点**（Condition / Loop / Switch / Agent）→ invoke `ai-flow-special-nodes`
+3. **连边**：`flow edge connect --flow-id <id> --source <s> --target <t> [--source-handle <h>]`
+   - 多出口 handle：condition `true`/`false`、loop `done`/`loop`、switch `branch-<id>`/`default-branch`、agent `chat_model`/`memory`/`tools`
+4. **字段映射**（仅 link/sync，business_type 5/6）→ invoke `ai-flow-field-mapping`（mapping show/check/add/set/delete --entity user/org/role + link 的 account-linking + check-mapping）
+   - 若该 skill 未安装，兜底：`flow mapping check <id> --json` 看缺失 → `flow mapping add <id> --entity user/org/role ...` 补 → 再 `mapping check` 确认；账号关联 `link account-linking show <id>`。全貌见 `~/.ai-flow/knowledge/link-sync-guide.md`
+5. **注入变量**：`flow variables show <id> --node-id <target> --json` 查可用变量 → `flow node update <nodeId> --flow-id <id> --patch '{"properties": {"<字段>": "{{N<上游>.path}}"}}' --validate-vars`
+   - **引用变量节点（创建变量/更新变量）输出时，路径含 `vars.` 段（`{{N<变量节点>.vars.<变量名>}}`）**：照抄 `flow variables show` 给出的完整路径、**勿手工删掉任何段（尤其 `vars.`）**；去掉 `vars.` 会取到 `true`/`null`。见 flow-solutions `set-var-output-keep-vars-prefix`
+6. **逐节点测试**：`flow test <nodeId> --flow-id <id> --json`，看 `ok` + `output`
+7. **修复**：失败 → invoke `ai-flow-debug`
+   - 若该 skill 未安装，兜底：看 test 的 `output`（不只看 ok）、`flow node show <nodeId> --json` 查配置、`--patch` 改后再测；非直觉节点先查 flow-solutions
+
+## 配置要点
+
+- ⚠️ **配字段前先查 `~/.ai-flow/knowledge/field-config.md`**（字段配置解读手册）：把 `knowledge actions` schema 里的 `page_control`/`value_type` 翻译成正确的值——决定**怎么传**（JSON 控件传 JSON 串、NUMBER 但 TEXT 控件传字符串、FIXED/EXTEND_OBJ 传对象、看 control 不看 type）和**能不能写变量/混排**（`JS_EXP`/`ADAPTOR` 只放单变量、`REPLACE_VAR`/`PLAIN_TEXT` 才能文本+`{{}}`混排）。schema 是真值源、本手册是解读规则。
+- `--data` 用于 create 设初值，`--patch` 用于 update（深度合并）；格式 `{"properties": {"<字段>": "<值>"}}`（flat JSON 自动映射到 `sub_params`）
+- **Loop / SelfLoopNode 字段格式因节点而异**（实测 LoopNode 多吃 flat、SelfLoopNode 吃 `sub_params`）：按错误信号切换——`14000000` = 该用 `sub_params`；`properties.X…当前为 OBJECT` = 该用 flat。详见 `ai-flow-special-nodes`
+- 变量 `{{N<id>.<path>}}`：含 `N` 前缀、不能多级节点嵌套、数组用 `[0]`、`--validate-vars` 校验；**变量节点（创建/更新变量）输出引用保留 `vars.` 段（`{{N<id>.vars.<name>}}`），去掉会得 true/null —— 见 flow-solutions `set-var-output-keep-vars-prefix`**
+- **不猜配置值**：决定运行时行为的值不确定就问或列待确认项
+- **HTTP 节点对接已知第三方 API（钉钉 / 企微 / 飞书等）→ 先通读该接口官方文档、逐项列全必填 header/query/body 参数再配**，别只填自己记得的几个（漏参数运行才报错，返工成本高）。填 query/param 死值时注意 `value_type` 若是 `JS_EXP`，字符串常量要**加引号**（否则被当变量报 `ReferenceError`，见 flow-solutions `expression-field-no-interpolation`）。
+- **别乱动"应答成功判定"(`successExp`)**：修别的问题时不要顺手改它；只有它确实导致成功/失败误判时才动。它是 JSON 控件、且表达式在平台引擎里的上下文路径未必是 `response.body`——要改先 `flow test` 看引擎实际可见的响应结构，别照搬 API 文档路径臆测。见 flow-solutions `http-json-body-successexp-json-control`。
+- 临时文件放 `./tmp`；单节点配置文件配成功即删，整流的临时文件全流验证通过后清理
+
+## gate（交接前必须全过）
+
+- 所有节点 `status` 均为 `SUCCESS`、无 `INVALID`：`flow node list --flow-id <id> --json` 或 `flow analyze <id> --json` 确认
+- 每个节点都 `flow test` 通过且 `output` 正确
+- 连线无悬空（特殊节点多出口都连）
+- **流有用途备注、关键节点有职责备注**（别交一条看不出在干嘛的裸流）
+- **改已有流的**：节点坐标未被搅乱（对比 `./tmp/pre-change-<flowId>.json` 快照）、授权节点账号在当前环境有效（非陌生数字 ID）
+- link/sync：`flow mapping check` 通过、遍历节点账号已绑
+
+## 安全护栏
+
+- **严禁未经用户确认删除流 / 节点**（`flow delete` / `flow node delete` 不可逆，执行前必须获用户明确授权）
+
+## 交接
+
+**完整模式**：全部节点 SUCCESS、逐节点测通后 → 交接测试验证：
+
+- 若 `ai-flow-verify` 可用，invoke 它（带 `flowId`）
+- 否则提示用户："搭建完成，下一步整体校验与 review（`flow validate` + `flow analyze`）"
+
+**框架模式**：不进 verify 端到端。告知用户"框架已就绪、未测"，并说明后续补齐方式（重新进入完整搭建，对各节点补配置 + 测试）。
+
+## 常见错误
+
+| ❌ 错误 | ✅ 正确 |
+|--------|--------|
+| 一次建完所有节点再测 | 逐节点 create→test→下一个 |
+| 看到 `ok:true` 就过 | 必看 `output` 内容（ADAPTOR 空 `{}` 陷阱） |
+| Loop/SelfLoop 格式用错（`14000000` 或 `…当前为 OBJECT`） | 按信号切换 flat ↔ `sub_params`（见 `ai-flow-special-nodes`） |
+| 节点需账号却没绑 | invoke `ai-flow-auth` |
+| 触发器 `knowledge actions <cid>` 返回 `[]` 以为建不了 | 加 `--trigger` 查 action-id（内置触发器 action 默认被过滤） |
+| 特殊节点按普通节点方式配 | invoke `ai-flow-special-nodes` |
+| 碰到代码 / 定时等节点凭直觉配 | 先查 flow-solutions（项目级 + 用户级两层） |
+| 凭猜填配置值 | 不确定就问 |
+| 不看 page_control 就传值（JSON 控件传对象 / NUMBER 但 TEXT 控件传数字） | 先查 `~/.ai-flow/knowledge/field-config.md`：看 page_control 定格式、看 value_type 定能否插值 |
+| webhook 等节点测不了就卡住 | 跟用户要示例 JSON，`--sample-output` 喂样本，下游继续 |
+| 框架模式还硬测 / 把 `INVALID` 当错误 | 框架模式只搭结构，`INVALID` 属预期 |
+| HTTP 调外部 API 只填记得的几个参数 | 对照接口文档列全必填 header/query/body |
+| 修别的问题时顺手改了 `successExp`/应答成功判定 | 非该字段致错就别动它 |
+| 改已有流用 `--patch` 带上 `position-x/y`、或重建节点 | patch 不带坐标、不重建，保画布布局 |
+| 建完不加任何备注 | 流+关键节点默认写备注 |
+
+## 红旗（出现即停）
+
+- "先全建好再统一测" → 逐节点测，否则上游变量不可用
+- "ok 了就行" → 看 `output`，ok ≠ 数据对
+- "这个值大概是…" → 别猜，问或查
+- "定时/Webhook 触发器没有 action，建不了" → 漏了 `--trigger`；`knowledge actions <cid> --trigger` 取 action-id
+- "webhook/这节点测不出来，跳过吧" → 跟用户要示例 JSON + `--sample-output`，别跳
+- "顺手把应答成功判定也改了" → 非该字段致错别动 `successExp`
+- "改完流顺便理一下布局" → 别重建节点、`--patch` 别带坐标，会搅乱整张画布
+- "HTTP 参数填个大概" → 对照接口文档列全必填项，漏参数运行才报错

package/dist/claude-code/ai-flow-compound/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ai-flow-compound
+version: 0.7.3
+description: 当在需求/设计/搭建/验证/排障过程中解决了一个"文档没写、踩了才知道"的新坑（gotcha/config/error/best-practice），要把结论沉淀进 flow-solutions 知识库、避免后续再犯时使用。横切技能，由 ai-flow-debug / ai-flow-build / ai-flow-verify 在修复并验证后调用。这是 compounding（自学习）闭环的回写动作。
+---
+
+# AI Flow 自学习回写（compounding）
+
+## 核心原则
+
+把"踩过且已验证的坑"结构化沉淀到 flow-solutions，让后续 grep 即得、不再重踩。**只沉淀"文档没写、实操才知道"的经验**——纯字段 schema（CLI 可查）、一次性问题、已在库里的，都不写。**回写前先去重、并经用户确认。**
+
+## flow-solutions 双层存储
+
+| 层 | 路径 | 用途 |
+|---|---|---|
+| **用户级 base** | `~/.ai-flow/flow-solutions/` | 平台通用坑（节点配置模式、CLI 行为、错误码、字段格式）——跨所有项目累积复用 |
+| **项目级 overlay** | `./docs/ai-flow/flow-solutions/` | 项目/客户专属（具体 connectorId/account_id/tenant/客户系统域名相关） |
+
+读取时两路径都查、项目级优先；写入时按内容分类选目标层（见下方第 3 步「分类」）。
+
+## 何时触发
+
+由 build / debug / verify 在**修复并验证通过后**调用：解决了一个新坑（如某节点格式怪点、某错误码根因、某配置陷阱、某最佳实践），且该坑**当前不在** flow-solutions 库里。
+
+不该触发：问题是纯 schema 查得到的；是本次一次性环境问题；与平台无关；库里已有同类条目（那就走"更新"而非新增）。
+
+## 回写协议（按序执行）
+
+### 1. 去重（必做，双路径）
+
+按症状 / 节点名 / 错误码搜两层库：
+
+```bash
+PROJECT_FS="./docs/ai-flow/flow-solutions"
+USER_FS="$HOME/.ai-flow/flow-solutions"
+{ [ -d "$PROJECT_FS" ] && grep -rli "<关键词>" "$PROJECT_FS" 2>/dev/null | sed 's|^|[project] |';
+  [ -d "$USER_FS" ]    && grep -rli "<关键词>" "$USER_FS"    2>/dev/null | sed 's|^|[user] |'; }
+```
+
+- **命中** → 不新建；改为**补充 / 更新现有条目**（在哪层命中就在那层更新：`[project]` 命中改项目级、`[user]` 命中改用户级）。在其 `symptoms` 补关键词、正文补新情形。
+- **未命中** → 进入新建。
+
+### 2. 拟稿（按 frontmatter 规范）
+
+```markdown
+---
+title: 一句话标题
+node: 涉及的节点 / 连接器（含 connectorId/actionId 若已知）
+problem_type: gotcha | config | error | best-practice
+symptoms: [可被 grep 命中的关键词 / 错误信息 / 错误码]
+tags: [...]
+date: <当前日期>
+source: 实测 (Claude Code session) / 官方文档 / ...
+---
+
+# 标题
+
+## 现象 / 症状
+## 根因
+## 解（带可照搬命令）
+## 适用范围 / 注意
+```
+
+正文要点：症状可被 grep、根因说清、解法可直接照搬（带命令）。
+
+### 3. 分类 + 先确认（强制）
+
+**分类启发式**（推断默认目标层，用户确认时可改）：
+
+| 信号 | 落到 |
+|---|---|
+| 涉及具体 `connectorId`/`account_id`/`tenant`/真实 orgId/客户系统域名/某环境专属配置 | **项目级** `./docs/ai-flow/flow-solutions/` |
+| 涉及节点配置模式、CLI 行为、平台怪点、错误码（如 `14000000`/QPS）、字段格式（page_control/value_type）、通用最佳实践 | **用户级** `~/.ai-flow/flow-solutions/` |
+| 混合（既有通用又有具体 ID） | 默认**用户级**（最大化跨项目复利） |
+
+**确认环节**（必须用阻塞式选择器 `AskUserQuestion`）：把拟稿的完整条目（frontmatter + 正文）展示给用户，并显式让用户选目标层：
+
+```
+拟稿条目 slug=<slug>，拟落库到：
+  [1] 用户级 ~/.ai-flow/flow-solutions/（默认推荐，跨项目复用）
+  [2] 项目级 ./docs/ai-flow/flow-solutions/（仅本项目，含客户/环境专属配置）
+```
+
+**经用户确认 target 后才写**——不确认不落库。
+
+### 4. 落库
+
+- 写到用户确认的 target 路径：`<target>/<slug>.md`（slug 用 kebab-case 英文，见名知意）。
+- 更新对应层的 `README.md`「现有条目」列表加一行（用户级 README 在 `~/.ai-flow/flow-solutions/README.md`，项目级在 `./docs/ai-flow/flow-solutions/README.md`；项目级无 README 时仅更新用户级）。
+- 告知用户已沉淀哪条、落到哪层。
+
+## slug 命名
+
+kebab-case、按"节点/主题-问题"，如 `loop-node-flat-format`、`dingtalk-msg-no-interpolation`、`qps-rate-limit-on-the-hour`。
+
+## 常见错误
+
+| ❌ 错误 | ✅ 正确 |
+|--------|--------|
+| 不去重就新建，库里重复 | 先双路径 `grep -rli` 命中则更新现有 |
+| 沉淀纯 schema / 文档已有的 | 只沉淀"踩了才知道"的经验 |
+| 不经确认直接写文件 | 拟稿 → 用户确认（含 target 选择）→ 才写 |
+| symptoms 写得 grep 不中 | 放真实错误码 / 关键词，便于后续命中 |
+| 解法没命令、只有结论 | 带可照搬命令 |
+| 把通用平台坑写到项目级、跨项目用不上 | 默认推荐用户级；仅客户/环境专属才落项目级 |
+
+## 红旗（出现即停）
+
+- "直接写一条吧" → 先 grep 去重 + 给用户确认
+- "这个 schema 记一下" → schema 查 CLI，不进 compounding
+- "症状随便写写" → 写能 grep 命中的真实关键词，否则等于没沉淀

package/dist/claude-code/ai-flow-debug/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ai-flow-debug
+version: 0.7.3
+description: 当连接流构建或运行出问题时使用——flow test ok:false 或 output 不对、节点 INVALID、flow validate 报错、运行告警/失败日志、节点报 14000000/认证失败/变量未替换/数据为 null。横切技能，在测试验证、搭建、运营任意阶段按症状触发。
+---
+
+# AI Flow 排障 / 日志分析
+
+## 核心原则
+
+系统化定位，别猜。**看 output（不信 `ok:true`）→ analyze 定位失败节点 → 日志 `--child` 下钻到真正故障层 → 按节点类型查根因 → 修复 → 回写 flow-solutions。** 排查的关键钥匙是 `flow log show --id <logId> --child <baseId> --json`——只有 `--child` 能拿到完整 `input`/`output`/`error_msg`，`log list` 的错误信息是**截断的**。
+
+## 第一步：先查 flow-solutions（双路径）
+
+排查前先 grep 两层经验库（项目级优先、用户级兜底），按症状 / 错误码找已知解（如 `14000000`、`getParam`、`QPS`）：
+
+```bash
+PROJECT_FS="./docs/ai-flow/flow-solutions"
+USER_FS="$HOME/.ai-flow/flow-solutions"
+{ [ -d "$PROJECT_FS" ] && grep -rli "<关键词>" "$PROJECT_FS" 2>/dev/null | sed 's|^|[project] |';
+  [ -d "$USER_FS" ]    && grep -rli "<关键词>" "$USER_FS"    2>/dev/null | sed 's|^|[user] |'; }
+```
+
+命中直接用；没有则按下面系统排查，**解决后回写一条**（默认推荐用户级、跨项目复用）。
+
+## 构建期排障（flow test / validate 失败）
+
+看 output，不只看 ok。常见症状 → 解：
+
+| 症状 | 根因 | 解 |
+|------|------|----|
+| `flow node update` 返回 `14000000` | 该节点要 `sub_params` 却给了 flat | 改 `sub_params`（反之报 `…当前为 OBJECT` 则改 flat）；Loop/SelfLoop 格式因节点而异，见 `ai-flow-special-nodes` |
+| 变量未被替换 | 多级嵌套 `{{N1.N2.x}}` / 缺 `N` 前缀 / `.0` 应为 `[0]` / 上游没测过 | 修语法；先测上游再 `--validate-vars` |
+| 下游收到 `null`、`output.current` 为 `{}` | ADAPTOR 字段 `ext_org`/`ext_user` 留空 `{}` | 改显式 `{{N<遍历>.current.dept/user}}` |
+| 引用创建变量/更新变量输出得到 `true`/`null` | 引用漏了 `vars.` 段（变量节点输出嵌在 `vars` 下） | 改 `{{N<id>.vars.<name>}}`，或照抄 `flow variables show` 的完整路径；见 flow-solutions `set-var-output-keep-vars-prefix` |
+| 账号错 / 运行认证失败 | 缺账号绑定 | invoke `ai-flow-auth`（account list → 绑定 → `flow node show` 验证） |
+| `flow validate` 报 errors | 边引用不存在节点 / 必填未配 / 连接不完整 / 变量无效 | 按 error 逐条修：补字段、连边、修变量 |
+| `ok:true` 但数据不对 | 只看了 ok | 看 output；改一个变量跑两次 `flow test` 对比 |
+
+## 运行期排障（已上线流的告警 / 失败日志）
+
+```bash
+# 1. 概览：哪些节点 FAILED（brief 更快）
+ai-flow flow analyze <flowId> --format brief
+# 2. 失败日志（status: 0失败 1成功 2告警 3运行中 5超时 6超限；--time-range 1d/7d）
+ai-flow flow log list --flow-id <flowId> --status 0 --time-range 1d --json
+# 3. 定位失败节点 + 拿 base_id
+ai-flow flow log show --id <logId> --json
+# 4. ⚠️关键：--child 下钻到真正故障层（完整 input/output/error_msg）
+ai-flow flow log show --id <logId> --child <baseId> --json
+```
+
+**看到条件 / 循环节点失败，必须 `--child` 下钻**——父节点只汇总状态，真故障在子节点。`--child` 的 `output.result`：条件节点揭示走哪个分支；`{"result":"INIT"}` 说明节点入口就失败（还没进核心逻辑）。
+
+### ⚠️ 日志 `status` 可能不准 → 与 `error_msg` 交叉验证（后端已知 bug）
+
+`flow log list --status` 返回的 status 存在不准确的情况（已提产品工单）。**别只信 status 判失败/告警**：
+- `error_msg=OK` 但 `status=WARNING` → 多是**误报**，别当失败推送 / 别当 root cause 深挖。
+- 真失败却被标 WARNING/OK → 会漏。所以**分类判断要 status + error_msg 组合看，冲突时以 error_msg 的实际内容为准**。
+- 做告警分类 / 自动化运维时，把"status 与 error_msg 冲突"本身当一个信号，别默认 status 是真值。
+
+### ⚠️ 老画布流是 CLI 盲区 → 诚实降级，别兜底编根因（0703 新增）
+
+历史"老画布"（旧版编辑器）创建的流：`flow log list` 能查到执行日志，但 `flow log show --id <id> --child <base>` **返回空节点信息**——拿不到失败节点的 `input/output/error_msg`，也拿不到流定义/节点配置。
+
+- 识别信号：`--child` 下钻返回空 / 无节点详情，且该流是历史老流。
+- **禁止兜底编造根因**（如笼统回一句"动作节点执行失败/请查看节点输入输出"——这没信息量、会误导）。
+- **诚实告知** + 给可行路径："这是老画布流，CLI 取不到节点级详情/定义；请登录 Web 后台查看该节点日志，或将此流迁移到新画布后即可用 CLI 深查。"
+- 不要在"查不到"时假装分析出了原因。
+
+## 按节点类型查根因
+
+- **ActionNode**：HTTP 地址可达？变量引用存在 / 正确？API 凭证 / 权限？目标 API 限流？
+- **LoopNode 子节点**：`--child` 钻到失败那次迭代，查循环表达式变量、迭代内 HTTP
+- **Condition 走错分支**：看 `--child` 的 `output.result`
+- **SelfLoopNode `INIT`**（link/sync 遍历常见）：QPS 限流 / 账号未绑（`flow node show` 查 `account_id`）/ 入参无效
+- **同步数据缺失但无失败**（link/sync）：字段映射 → `flow mapping check`，invoke `ai-flow-field-mapping`；或挂载点错 → `org tree search` 核 `orgId`
+
+## QPS 限流（高频、易误判）
+
+症状：失败**集中在整点 / 半点**、其他时段正常、`error_msg` 含 `subcode=90002` / `QPS` / `1 秒内请求超过 N 次`。解：错峰触发（如 22:30 → 22:37）、降频、或提配额。**别预设成网络问题**——失败集中在整点先查 QPS。
+
+## 修复后
+
+- 重测 / 重跑确认
+- **回写 flow-solutions** → invoke `ai-flow-compound`：把新坑（症状 + 根因 + 解）沉淀一条——它会先**双路径 grep** 去重（命中则更新现有）、按 frontmatter 拟稿、**经用户确认（含目标层选择：用户级跨项目复用 / 项目级专属）后**写入对应层。这是 compounding 自学习的核心动作。（compound 未装时按其协议手动回写：双路径去重→拟稿→确认+选 target→落库）
+
+## 红旗（出现即停）
+
+- "ok:true 就没事" → 看 output
+- "条件 / 循环节点失败了" → 必须 `--child` 下钻，别停在父节点
+- "应该是网络问题" → 失败集中在整点？先查 QPS
+- "log list 的报错就够了" → 截断的，用 `--child` 拿完整 `error_msg`
+- "`--child` 空，那就照常报个根因" → 老画布盲区，诚实告知取不到详情 + 引导 Web/迁移，别编
+- "status=失败/告警，那就是失败/告警" → 与 `error_msg` 交叉验证（`error_msg=OK` 常是误报），别只信 status