autoflow-core

AutoFlow Core（核心版）

你（agent）通过本 skill 获得对 Node-RED 实例的安全编程能力：读取、编写、修改、验证 flow。 所有写入经 scripts/nr_client.py（纯标准库，无 pip 依赖），自带护栏：写前快照、 结构 lint、节点数熔断、prod 闸、操作日志、回读校验。

🚨 黄金法则（违反任何一条立即停止）

1. af_* 前缀 = 你的所有权（代码层硬拦截）。新建 tab/flow 一律 af_<场景名> 命名。
2. 用户手工流只读——硬拦截，不靠自觉。write-flow / create_tab 对不带 af_ 前缀的 目标默认抛 NRGuardError 拒绝；确需改动用户流必须显式加 --allow-user-flow （仍会照常快照留底）。归属以线上 label 为准，伪造前缀绕不过。
3. 写前必快照，写后必回读。用 write-flow（内置快照+回读校验），不要手工拼 PUT。
4. prod 默认禁写。URL 含 :1880 或用户明确说是生产实例 → 需用户显式同意才可 --allow-prod。
5. 禁止整体替换。任何"把整个 flows 数组 PUT 回去"的操作都是禁区（会删掉未列出的节点）。 单 flow 更新只走 write-flow。
6. 不确定就问。实体 ID、设备语义拿不准时问用户，不要猜。

配置（~/.autoflow-core/config.json）

{"url": "http://<host>:<port>", "username": "...", "password": "..."}

优先级：环境变量 NR_URL/NR_USER/NR_PASS > 配置文件 > 函数参数。 推荐用环境变量（配置文件是明文密码文件，仅限本机、勿入版本库/勿外发）。 可选（verify 的 HA 断言用）：HASS_SERVER + HASS_TOKEN 环境变量。

连接排障：若报 Client sent an HTTP request to an HTTPS server → 端点其实是 HTTPS， 把 url 改 https://；若报证书错误 → 用带有效证书的域名（如 Tailscale 的 *.ts.net）， 不要用裸 IP。

标准写入流程（每次写 flow 都走这七步）

1. inventory                     # 看现状：哪些 tab、归属谁、可写性
2. get <tab-id> --compact        # 读参考 flow（省 token；学习用户节点的写法）
3. 写 JSON（见节点构建约定）        # z 必须指向真实 tab id；新 tab 用 af_ 前缀
4. write-flow <id> --file f.json --dry-run   # 预览
5. write-flow <id> --file f.json             # 快照→PUT→回读校验一体
6. inject-read <inject-node-id>  # 自愈闭环：触发+回读 context 捕获
7. 不符 → 改 → 重跑 4-6（上限 3 轮，仍失败则停下报告用户，附快照路径）

自愈闭环（inject → 回读 → apply）

被测 flow 在验证点接一个 function 节点，把结果写到 context：

global.set("af_dbg", {ok: true, state: msg.payload});  // 结构自定，但要能断言
return msg;

然后：

python scripts/nr_client.py inject-read <inject节点id> --key af_dbg --timeout 10

• 捕获到值 → 与期望比对 → 一致即通过；不一致 → 分析原因 → 修改 → 重验。
• 超时 None → flow 没跑到验证点（检查触发条件/连线/节点使能）。
• 命令会先清旧值再触发，不怕读到上一轮残留。

命令速查

python scripts/nr_client.py doctor                     # 安装后自检（验收标准：全绿）
python scripts/nr_client.py inventory                  # 全 tab 只读概览
python scripts/nr_client.py get <id> --compact         # 读 flow（去坐标省 token）
python scripts/nr_client.py search <keyword>           # 全局搜节点
python scripts/nr_client.py write-flow <id> -f f.json [--dry-run]
python scripts/nr_client.py inject-read <inject-id> [--key af_dbg]
python scripts/nr_client.py lint f.json                # 离线结构校验
python scripts/nr_client.py verify <flow-id> --yes     # 端到端（含可选 HA 断言）