DevPeek

文件头（# 指令）

文件头写在 Flow 最前面，用 `#` 声明这条规则管哪条 WebSocket、消息字段习惯、是否自动回协议 Ping、未命中时怎么办等**默认约定**。它们不改变缩进树结构，但会影响后续每一行的解析方式。

文件开头连续 # 行定义本 Flow 的协议约定；解析器在 parse 正文前先读文件头。

语法：行首 # + 空格 + 指令 + 参数（至行尾）。

# ws wss://api.example.com/ws
# profile type
# dispatch type
# format json
# capture *
# on-unmatch silent
# ping auto

指令一览

指令 说明 默认
# ws <url> 连接匹配（host/path/protocol）；编译进 match.url 无（需 JSON match 或本行）
# profile <name> 加载 Protocol Profile（见第四节） type
# dispatch <field> 单词简写返回时写入的顶层字段 name 与 profile 一致
# format json | text 消息条件/返回默认 transform（v1：即 JSON/text 编解码语义；v2 见第二十二节） json
# capture * | off | f1,f2 消息条件匹配成功后 capture 字段 → $变量 *（顶层全字段）
# on-unmatch silent | root | passthrough 当前 scope 无命中 client 消息时的行为 silent
# ping auto 无 --@ping 分支时，协议级 Ping 自动回 protocol Pong off
# upstream off | passthrough | matched-off client 帧命中/mock 后是否仍转发 upstream off
# loop immediate off | on --@loop 注册后是否立即触发首 tick off
# flow-version 1 IR/语法主版本；不兼容变更时递增 1

# ping auto 说明

Mock 截断 upstream 时，客户端发的 WS 协议 Ping 必须有人回 Pong，否则易断线。

  • # ping auto on：未命中 --@ping 时，runtime 自动 protocol Pong（空 payload）
  • 存在 --@ping 分支：按返回行发 text 帧（见 7.3.2）
  • # upstream off 时 validate 须 ping auto 或 --@ping（E008）
  • 与应用层 --type=ping 无关，见 6.8

# upstream 说明

值 行为
off Mock 命中后短路，不转发 upstream（默认 mock 模式）
passthrough 始终转发 client 帧 upstream（仅注入 server 返回，不改 client 方向）
matched-off 未命中 Flow 时转发；命中后不再转发

# loop immediate 说明

  • off（默认）：--@loop 注册后，首个 tick 在 第一个 dur 之后
  • on：注册后立即执行一次 tick，之后按 dur 周期

示例文件头

# ws wss://api.example.com/gateway
# profile type
# dispatch type
# format json
# capture id,type,token
# ping auto
# upstream off
# loop immediate off
# flow-version 1

说明：

  • # ws 让人只开一个 .dpws 文件即可；DevPeek 仍可在内部编译为 match JSON
  • 文件头不是脚本；仅声明默认值，不改变 Flow 树形结构