# ⇢ 流程图语法规范 · FlowText v2

> 这一份只管【流程图】。脑图看 `syntax-mindmap.md`；想一次生成两种图看 `ai-dual-output-syntax.md`。
>
> **真源**：本规范描述的是「原版 FlowText v2 流程画板」`web/terminal/batch/sandbox-board.html` 里
> `importText()` 的真实行为。机器闸 `tests/syntax.spec.mjs` 会把下面每个示例真喂给画板跑一遍。
>
> **v2.1 新增（2026-08-18）**：带点编号的**子步骤**（`S2.1`）→ 导入后自动成为父步骤的子步骤，
> 在画板上可以像脑图一样**整枝收起／展开**。

---

## 一、一句话

**一行一步：`S编号 步骤名:对象 <- 上游`。** 不写 `<-` 就默认接上一行。其余全是可选的。

## 二、五种行（这就是全部）

### ① 标题行（可选，写在最前面）
```
工作流:BTC 自动化交易系统
```

### ② 步骤行（必需，至少一行）
```
S1 输入:交易想法
S2 数据系统 <- S1
S3 开发策略:按假设写出信号与仓位规则 <- S2
```
- `S1` 是编号，**不能重复**；`:` 后面是这一步要处理的**对象／要求**（可省）。
- `<- S1` 指定上游，多个上游用空格分开：`<- S1 S2`。也可写成 `←` 或 `⇐`。
- **不写 `<-` = 自动接上一行**（最常用，写起来最省）。
- 步骤名以 **输入 / 开始 / 设定** 开头 = 这一步被当成**入口节点**（绿色）。

### ③ 子步骤行（v2.1 新增，画板上可折叠的关键）
```
S2 数据系统
  S2.1 数据获取:交易所 API 拉 OHLCV
  S2.2 数据清洗:缺口、重复、异常价
  S2.3 数据验证:时间戳单调、无未来数据
S3 策略系统
  S3.1 定义信号
  S3.2 编译策略
```
- 编号带点 = **层级**：`S2.1` 是 `S2` 的子步骤，`S2.1.1` 是 `S2.1` 的子步骤（可以更深）。
- 缩进只是给人看的，**层级由编号决定**，不缩进也认。
- 导入画板后：父步骤卡片上出现 **▾**，点一下把整枝收起（显示 `▸3` = 藏了 3 步），再点展开。
  顶栏 **⊟ 收枝** 一键只看主干。**收起只影响显示，导出说明书内容不变。**
- 连线默认仍是「接上一行」，所以上例会串成 `S2 → S2.1 → S2.2 → S2.3 → S3`；
  想让下一大步直接接父步骤，就显式写 `S3 策略系统 <- S2`。

### ④ 属性行（可选，缩进写在所属步骤下面，用 `+` 开头）
```
S3 开发策略 <- S2
  +要求:写清入场、出场、仓位三条规则，每条给出参数与理由
  +产出:strategy_v1（含参数表与回测口径）
  +工具:联网搜索
  +格式:表格
  +模板:| 规则 | 参数 | 理由 |
  +语言:中文
  +限制:不超过 800 字;不要复制原文
  +附件:https://example.com/参考
  +隐藏
```

| 属性键（同义词都认） | 落到哪里 |
|---|---|
| `+要求` `+任务要求` `+说明` `+做什么` `+怎么做` `+背景` | 这一步的**备注／要求** |
| `+产出` `+输出` `+输出要求` `+成品` `+交付` `+验收` | 这一步的**产出要求** |
| `+对象` `+输入` `+处理对象` | 处理对象（等同于步骤行 `:` 后面那段） |
| `+上游` `+来源` `+输入来源` | 上游步骤（等同于 `<-`） |
| `+工具` | 强制调用的工具（多个用 `、` 分开） |
| `+格式` `+输出格式` | 产出格式修饰（表格／清单／…） |
| `+模板` `+表头` `+格式模板` | 格式模板正文（可多行，每行一个 `+模板:`） |
| `+语言` `+口径` | 语言／口径修饰 |
| `+限制` `+禁止` `+字数` `+不要` | 限制修饰（多条用 `;` 分开） |
| `+修饰` `+自定义` `+风格` `+语气` | 自定义修饰 |
| `+附件` `+链接` `+参考` `+资料` | 附件（`http` 开头自动识别成链接） |
| `+私有` | 标记私有（不进公开导出） |
| `+隐藏` `+隐性` `+不展示` | 照常执行，但**不进最终回答**（画板上是半透明卡片） |

### ⑤ 循环行（可选，**不要复制步骤**来表达重复）
```
循环 逐项处理 = S2 S3 引用S1
循环 打磨 = S4 轮数:3
循环 磨到达标 = S4 S5 直到:通过验收 上限:5
循环 L2 子循环 = S6 直到:无新问题 上限:3 嵌套于L1
循环 锁定整体 = S7 S8 工作组
```

| 写法 | 含义 |
|---|---|
| `= S2 S3` | 循环体是哪几步（画板上框起来） |
| `引用S1` | 对 S1 的输出**逐项**循环（S1 每行一项） |
| `清单:甲、乙、丙` | 对固定清单逐项循环 |
| `轮数:3` | 固定跑 3 轮（取长补短） |
| `直到:<条件> 上限:N` | 条件循环，**上限必写**，否则可能永远转 |
| `嵌套于L1` | 这个循环嵌在 L1 里面（多层循环） |
| `工作组` | 锁定成一个整体，不循环 |

## 三、并联怎么写（不用新符号）

**多个步骤共享同一个上游 = 并联**，之后用一个步骤汇合：

```
S3 开发策略 <- S2
S4 历史回测 <- S3
S5 成本测试 <- S3
S6 极端行情测试 <- S3
S7 汇总验证结论 <- S4 S5 S6
```

`S4/S5/S6` 都从 `S3` 出发 = 三件事没有先后，可以同时做；`S7` 三个上游 = 汇合点。
在画板上点顶栏 **🪄 自动分层**，会把这类**真分支**自动归到 `S3` 下面，于是可以整枝收起
（线性主干不会被乱猜 —— 否则收一步会把后面半条流程吞掉）。

## 四、完整示例

```
工作流:BTC 自动化交易系统
S1 输入:交易想法与本金上限
S2 数据系统
  S2.1 数据获取:交易所 API 拉 OHLCV
  S2.2 数据清洗:缺口、重复、异常价
  S2.3 数据验证:时间戳单调、无未来数据
    +产出:clean_market_data（含校验报告）
S3 策略系统 <- S2
  S3.1 定义假设
  S3.2 定义信号与入场出场
  S3.3 编译完整策略
    +产出:strategy_v1
S4 历史回测 <- S3
  +要求:无未来函数，每笔订单可追溯，换机器重跑结果一致
  +产出:equity_curve + Sharpe + MaxDrawdown
S5 成本测试 <- S3
S6 极端行情测试 <- S3
S7 汇总验证结论 <- S4 S5 S6
  +产出:validation_report（含是否通过的明确结论）
S8 风控设计 <- S7
  +产出:risk_policy（单笔上限／最大回撤／Kill Switch）
S9 模拟交易 <- S8
S10 小资金实盘 <- S9
S11 监控与复盘 <- S10
循环 磨到达标 = S3 S4 S7 直到:验证通过 上限:5
循环 常态运行 = S11 上限:9999
```

## 五、常见错误

| ✗ 错误写法 | 会发生什么 | ✓ 改成 |
|---|---|---|
| 输出 Mermaid / JSON / 箭头图 | 画板不认，一个节点都出不来 | 用 `S1 名称` 这种行 |
| 编号重复（两个 `S3`） | 后一个覆盖前一个 | 编号唯一 |
| 复制步骤来表达「重复三次」 | 图上一堆重复卡片 | 用 `循环 名 = S4 轮数:3` |
| 条件循环不写 `上限:N` | 可能永远转下去 | 一定写 `上限:N` |
| 一步里塞三件事 | 没法单独验收 | 一步只做一件事 |
| 步骤超过 12 个还全平铺 | 手机上看不过来 | 用子步骤 `S2.1` 分层，再收枝 |
| 承重流程没有检查步骤 | 没人挑错 | 加一步独立验证／红队 |

## 六、给 AI 的一段指令（复制即用）

```
请把我下面的需求写成 FlowText v2 流程，只输出流程本身，不要前言和总结。

规则：
1. 第一行写 工作流:<名称>。
2. 每步一行：S1 步骤名:对象或要求 <- 上游编号（不写 <- 就是接上一行）；
   步骤名用动词开头，一步只做一件事；总步数控制在 5-12 步。
3. 一个大步里要拆细，就用带点的子步骤编号：S2.1 / S2.2 / S2.1.1（导入后可整枝收起）。
4. 需要补充的写属性行，缩进两格：+要求: / +产出: / +工具: / +限制:。
   每个能交出东西的步骤都要有 +产出，并把验收标准写在里面。
5. 并联 = 多个步骤写同一个上游，之后用一个步骤汇合（<- S4 S5 S6）。
6. 重复不要复制步骤，用：循环 <名> = S4 S5 直到:<条件> 上限:<N>（上限必写）。
7. 承重流程必须有一步独立验证或红队。
8. 不要输出 Mermaid、JSON、箭头图或 Markdown 流程图。

我的需求：__________
```

---
*语法的唯一权威源是 `batch/sandbox-board.html` 的 `importText()` + 本目录机器闸；本文档若与它们冲突，以代码与测试为准。*