AutoFlow

对着 AI 说一句话，你家就多一个自动化。

不用打开 Node-RED，不用查实体 ID，不用担心 AI 半夜把你家门锁打开。

完整版（Docker 网关 + WebUI + 安全闸） · 核心版（零依赖 Python 库，给 AI agent 直接用）

快速安装 · 接上你的 AI · 第一个自动化 · 四种做法对比 · 核心版

一、这东西到底解决什么问题

如果你在用 Home Assistant，大概率经历过这三件事。

第一件：加一个自动化，比想象中麻烦得多。

你想要「书房电脑一开机，就把显示器挂灯打开」。听起来 30 秒的事。实际上：打开 Node-RED → 拖一个触发节点 → 想不起来电脑的实体叫什么 → 切到 HA 开发者工具搜 → 复制出 switch.d4f0eaeab731_switch 这么个东西 → 回来粘贴 → 再拖一个判断节点 → 再去搜挂灯 → light.yeelink_cn_555003624_lamp22_s_2 → 拖 call service 节点 → 连线 → 部署 → 去书房开一次电脑测试。

半小时过去了。而你脑子里那句话，只有 15 个字。

第二件：让 AI 帮你写，它会一本正经地编。

你把需求丢给 ChatGPT/Claude，它很流畅地给你一段 flow JSON，里面写着 light.study_desk_lamp。看起来特别合理 —— 但你家没有这个实体。真实的 ID 是 light.yeelink_cn_555003624_lamp22_s_2，AI 不可能猜出来。

要命的是它不会报错。导入 Node-RED，部署成功，绿灯，一切正常。然后它永远不触发。 你三天后才发现，还以为是自己哪里没配对。

第三件：真让 AI 连上 HA，你会睡不着。

要让 AI 真正能干活，你得把 HA 长期访问令牌给它。那一刻它就拥有了你家所有设备的完整控制权 —— 灯、窗帘、门锁、水阀。它不需要恶意，只需要一次幻觉、一个手滑的批量操作。

AutoFlow 就是插在你和 AI 之间的那一层。

它拿着钥匙，AI 没有。AI 想干什么，得先跟它说；它检查完、在虚拟环境里试跑过、确认没问题， 再送到你手机上让你点一下「同意」，才真的落到你家里。

Related MCP server: hass-mcp-server

二、四种做法横向对比

还是那个需求：「书房电脑一开机，就把显示器挂灯打开」。看四种做法分别会发生什么。

做法 A：自己在 Node-RED 里拖

打开浏览器 → 翻 HA 开发者工具找两个实体 ID → 拖 4 个节点 → 连线 → 配置每个节点 → 部署 → 跑去书房开电脑验证。

结果：能成，但花了 30 分钟，而且你得懂 Node-RED 的节点模型。想加第 20 个自动化时， 你已经不想加了。

做法 B：把 HA 令牌给 AI，让它直接写

你说需求，AI 生成 flow，直接调 Node-RED 接口部署。

结果：10 秒完成，看起来很爽。但实体 ID 是编的，flow 静默失效。而且 AI 现在握着你家 所有设备的控制权 —— 它下一次「顺手帮你优化一下」，可能就把 12 个自动化全改了。 你没有任何刹车。

做法 C：给 AI 配一份 skill 文档，它照着规范写

比 B 好一些 —— AI 知道你的命名习惯、知道该用哪些节点、输出格式更规整。

结果：格式对了，实体 ID 照样是编的。skill 是一份静态文档，它不知道你家此刻有哪些 设备、哪个灯叫什么、开关现在是开还是关。它也验证不了写出来的东西能不能跑。 安全问题一点没变：令牌还在 AI 手上。

这是很多人当前的状态 —— 以为加了 skill 就解决了，其实只解决了「格式」， 没解决「事实」和「安全」这两个真问题。

做法 D：AutoFlow

你在聊天框说：「书房电脑开机就把显示器挂灯打开」。

背后发生的事：

1. AI 问网关：「书房有个叫『显示器挂灯』的东西，实体 ID 是啥？」 网关回：light.yeelink_cn_555003624_lamp22_s_2，当前 off，可能状态 on/off。 —— 实体 ID 不再靠猜，是查出来的。

2. AI 写 5 行 DSL（不是 200 行 JSON）：

   场景: 书房电脑开机则开显示器挂灯
   触发: switch.d4f0eaeab731_switch on
   动作: light.turn_on(light.yeelink_cn_555003624_lamp22_s_2)
   预期:
     light.yeelink_cn_555003624_lamp22_s_2 = on

   注意最后那个 预期: —— AI 得先声明「跑完之后灯应该是亮的」。 这是它给自己立的军令状。

3. 网关编译成真正的 Node-RED flow，在一个虚拟的 HA 副本里把它跑一遍， 然后对照那句 预期: 检查灯是不是真的亮了。 对不上就打回去让 AI 改，你根本不会看到废品。

4. 通过了才进「待批准」队列，你手机上收到通知。

5. 你点「同意」，它才落到你家 Node-RED 上。

结果：一句话，1 分钟，产出的 flow 干净可读（不是一坨 function 节点）， 而且从头到尾 AI 都没碰过你的 HA 令牌。

汇总

一句话总结这张表：A 累，B 危险，C 是把 B 包装得好看了一点，D 才真正解决了「事实」「验证」「刹车」三个问题。

什么情况下你不需要 AutoFlow

诚实地说：

• 你家总共就 3 个自动化，写完再也不动 —— 不值当为它多跑一个服务。

• 你没有 Docker，也不想装 —— AutoFlow 目前推荐容器部署。

• 你享受手动拖节点的过程 —— 那是另一种乐趣，AutoFlow 帮不上忙。

AutoFlow 的价值随「你想让家里变聪明的野心」增长。自动化越多、越常改、越怕出事， 它越划算。

三、安装（五分钟）

前置条件

• 一台常开的机器：NAS、软路由、树莓派、旧电脑都行（跟 HA 同一个局域网）

• 上面装了 Docker（没有的话脚本能帮你装，见下）

• 你已经在用 Home Assistant 和 Node-RED

第 1 步：一条命令装好

安装到当前目录（推荐，NAS 用户常用）：

curl -fsSL https://raw.githubusercontent.com/lidicn/AutoFlow/main/install.sh | bash -s -- -d "$(pwd)"

安装到默认目录（Linux /opt/autoflow，macOS ~/autoflow）：

curl -fsSL https://raw.githubusercontent.com/lidicn/AutoFlow/main/install.sh | bash

脚本会自动：检查 Docker → 下载代码 → 构建镜像 → 启动 → 等待服务就绪。

安装完成后，代码和数据都在你指定的目录里。进入该目录可以看到 docker-compose.yml、data/、.env 等文件。 以后更新：在安装目录下执行 bash install.sh --update（保留你的数据和配置）。

• 想换目录：bash install.sh -d /volume1/docker/autoflow

• 机器上没 Docker（仅 Linux）：bash install.sh --install-docker

• 中国大陆网络慢：export GITHUB_PROXY=https://ghproxy.com/ 后再执行安装命令

第 2 步：拿到控制台钥匙

⚠️ 这一步最容易卡住，请务必看。

出于安全考虑，AutoFlow 首次启动会自动生成一个访问令牌。不带令牌从局域网访问网页端会被 403 拒绝 —— 很多人以为装失败了，其实只是缺钥匙。

拿钥匙：

docker exec autoflow_gateway cat /data/.webui_token

（或者直接看宿主机上的挂载文件：cat /opt/autoflow/data/.webui_token；如果装到了别的目录，路径跟着改）

想一步到位（直接打印可点击的链接，把 IP 换成你机器的）：

TOKEN=$(docker exec autoflow_gateway cat /data/.webui_token)
echo "http://<NAS_IP>:8000/?token=$TOKEN"

容器名不是默认的 autoflow_gateway？先 docker ps | grep autoflow 看实际名字，命令里替换掉即可。

拿到形如 3dX-0KNWrdMk_8aNmjk926J9IC9MZ0Xg 的一串字符，然后用它开门：

http://<你这台机器的IP>:8000/?token=<刚才那串字符>

建议把这个完整网址存成手机书签 —— 以后批准自动化就靠它，在被窝里点一下就行。

第 3 步：告诉它你家在哪

网页端打开后，进 ⚙️ 设置 → 连接配置，填两组信息：

保存后立即生效，不用重启。

这些凭证从此只存在于网关里，任何 AI 都读不到。 这是整个设计的地基。

四、让你的 AI 接上 AutoFlow

第 1 步：给 AI 发一张身份证

进网页端 🤖 Agents 面板 → 输入一个名字（比如 我的Claude）→ 点「创建」。

会弹出一串 af_ 开头的身份码。只显示这一次，立刻复制。

为什么要发身份证？因为每个 AI 干过什么都会独立记账 —— 谁提的方案、谁改的东西， 全都可追溯。匿名连接一律拒绝。哪天某个 AI 不靠谱了，点一下「吊销」，它立刻失去所有能力。

第 2 步：在 AI 客户端里配 MCP

统一填这三样：

• 传输方式：Streamable HTTP

• 地址：http://<你的机器IP>:8000/mcp

• 请求头：Authorization: Bearer <刚才那串身份码>

几种常见客户端的写法：

Claude Desktop / WorkBuddy 等（JSON 配置）

{
  "mcpServers": {
    "autoflow": {
      "type": "streamableHttp",
      "url": "http://<LAN_IP>:8000/mcp",
      "headers": {
        "Authorization": "Bearer af_你的身份码"
      }
    }
  }
}

不同客户端字段名略有差异（type 有的叫 transport，值可能写作 streamable-http/http）。照着你客户端的文档填，只要保证是 Streamable HTTP + 那个 URL + 那个请求头就行。

浏览器扩展类客户端（如 DeepSeek++）

界面里填 URL 和 Bearer 字段即可。如果扩展跑在浏览器里、报跨域错误， 在 .env 里把扩展的 origin 加进白名单：

AF_MCP_CORS_ORIGINS=chrome-extension://xxxxxxxx

只支持 SSE 的老客户端

地址换成 http://<IP>:8000/sse。

第 3 步：验证连上了

对 AI 说一句：

帮我看看书房都有什么设备

如果它能列出你家书房的真实设备（带真实实体 ID 和当前状态），就通了。

不用手动给 AI 装说明书

网关里内置了一份完整的使用指南。AI 连上后自己调用 autoflow_get_skill 就能取到 —— 你不需要复制粘贴任何 prompt。指南更新了，AI 下次自动拿到新版。

五、你的第一个自动化（完整走一遍）

你说

书房电脑一开机，就把显示器挂灯打开

AI 做（你不用管，但知道它在干嘛会更放心）

1. 查设备 —— 问网关「书房的显示器挂灯是哪个实体」。 网关返回该区域所有沾边的实体，带域、当前状态、可能状态，让 AI 自己挑。

   这里有个细节体现设计用心：AI 不需要提前知道「挂灯」是 light 还是 switch。 很多设备名字看着像灯，实际是开关。网关把候选全给它，让它按用途挑，而不是逼它猜。

2. 写 DSL —— 就是本文开头那 5 行。不是 200 行 JSON。

3. 提交编译 —— 网关做四件事：

   • 语法检查

   • 实体校验（ID 是否真实存在）

   • 节点校验（用到的节点类型在你的 Node-RED 上装了没）

   • 虚拟重放：在一个 HA 数字孪生里真的执行一次，断言灯确实变成了 on

   任何一环挂了都会打回给 AI，附带具体原因。AI 自己修，修好再提。

你批准

网页端 🛡️ 安全闸 面板出现一条待批准。你能看到：

• 这个自动化叫什么、哪个 AI 提的

• 完整 DSL（人话，看得懂）

• 编译出的 flow 结构

• 虚拟环境的验证结果

点 同意 —— 落到你家 Node-RED，立即生效。 点 拒绝 —— 什么都不会发生。

配了 Bark 推送的话，待批准会直接推到手机（⚙️ 设置里填）。

出问题了怎么办

🚀 已部署 面板列出所有经 AutoFlow 部署的自动化，点一下就能下线。

这里有个贴心的设计：它只能下线自己部署的东西。你手工在 Node-RED 里搭的那些 flow， AutoFlow 认都不认，更别说删了 —— 想误伤都做不到。

每次部署还会自动存一份快照，需要追溯「上周那版是什么样」时可以翻。

六、网页端有什么

手机、平板、电脑自适应。九个面板：

一条不可动摇的规矩：批准和升格只能在网页端做，MCP 接口里根本没有这两个能力。 AI 不可能自己批准自己 —— 这不是靠自觉，是接口层面就不给。

七、常见问题

Q：网页打不开 / 一直 403？ 八成是没带令牌。回到第 2 步拿钥匙，用 http://IP:8000/?token=xxx 访问。

Q：连接配置填了，但连不上 HA？ HA 跟 AutoFlow 在同一台机器时，地址要写 http://host.docker.internal:8123， 写 localhost 一定失败 —— 容器里的 localhost 是容器自己。

Q：AI 说它连不上 / 401？ 身份码错了或被吊销了。去 🤖 Agents 面板重置一个新码，更新到 AI 客户端。 身份码只在创建时显示一次，丢了就重置，找不回来。

Q：AI 提交的东西总被打回？ 看打回原因（AI 通常会告诉你）。最常见两种： ① 实体不存在 —— 你说的设备名网关找不到，换个说法或去 HA 里确认名字； ② 节点类型未注册 —— 你的 Node-RED 缺某个插件。

Q：能让它不用每次都问我吗？ 能，但默认不建议。测试环境可以设 AF_AUTO_APPROVE=true。 接真实设备的环境请保持人工确认 —— 这是最后一道刹车。

Q：AI 会不会偷偷改我已有的自动化？ 不会。网关不提供「全量替换」「批量删除」这类操作 —— 不是靠规则禁止，是接口里压根没有。 另外还有爆炸半径上限、受保护流标签、所有权隔离（AI 动不了别人建的东西）。

Q：门锁、水阀这种危险设备呢？ 属于高危域，需要额外的升级确认，不能跟开灯走同一条路。

Q：AutoFlow 挂了，我家自动化会停吗？ 不会。自动化跑在你自己的 Node-RED 上，AutoFlow 只是「制造和管理」它们的工具。 网关挂了只是暂时不能加新的，已有的照常运行。

八、安全边界一览

九、核心版（轻量 Node-RED 操作工具）

如果你不需要完整的网关、WebUI 和安全闸，只是想让 AI 能安全地读写 Node-RED，可以用核心版。

什么是核心版

核心版是一个零依赖的 Python 库（nr_client.py）+ Skill 文档，封装了 Node-RED 的认证、flow 读写、节点操作等能力。AI agent 通过 Skill 调用它，可以：

• 查询 Node-RED 中的 flow、tab、节点

• 创建、更新、删除 flow

• 触发 inject 节点、读取 debug 输出

• 批量操作节点

与完整版的区别：

给 AI Agent 的安装提示词

把下面这段话发给你的 AI agent（Claude、DeepSeek、Cursor 等），它会自动完成核心版的安装和配置：

请安装 AutoFlow 核心版到当前目录，步骤如下：

1. 创建目录并下载核心文件：
   mkdir -p autoflow_core && cd autoflow_core
   curl -fsSL https://raw.githubusercontent.com/lidicn/AutoFlow/main/core/skill/scripts/nr_client.py -o nr_client.py
   curl -fsSL https://raw.githubusercontent.com/lidicn/AutoFlow/main/core/skill/SKILL.md -o SKILL.md

2. 配置环境变量（在 .env 或 shell 中设置）：
   NR_URL=http://<你的Node-RED地址>:1880
   NR_USER=<Node-RED用户名>
   NR_PASS=<Node-RED密码>

3. 阅读 SKILL.md 了解可用的工具和调用方式。

4. 先运行 dry-run 模式验证连接，确认无误后再执行写操作。

核心版使用示例

from nr_client import NodeREDClient

client = NodeREDClient()

# 列出所有 flow
flows = client.list_flows()
for f in flows:
    print(f["id"], f.get("label", ""))

# 获取单个 flow
flow = client.get_flow("flow_id_here")

# 触发 inject 节点
client.trigger_inject("node_id_here")

⚠️ 核心版没有安全闸，AI 可以直接操作 Node-RED。建议在测试环境使用，或配合 --dry-run 模式先预览变更。

十、给开发者

• 架构与设计：docs/ARCHITECTURE.md

• 本地开发 / 容器部署：DEPLOY.md

• 白盒验证循环：WHITEBOX_VERIFY_LOOP.md

一句话概括技术形态：一个 Python 网关，独占 HA/Node-RED 凭证，对外暴露 MCP（Streamable HTTP）+ 网页控制面。AI 侧只写语义 DSL，网关负责编译、静态校验、 虚拟孪生重放自证、人工确认闸、部署与快照。AI 可随时更换，凭证不动。

许可

MIT