# ef-compiler 与编码规范对照

参考 [CODING_STANDARDS.md](./CODING_STANDARDS.md)，对 `nodejs/ef-compiler` 的适用情况与已做调整说明如下。

## 已落实

| 规范 | 说明 |
|------|------|
| **§1–2 命名** | 文件名、变量名使用连字符、有意义命名（如 `value-resolver.js`、`workflow-parser.js`）。 |
| **§3 注释** | 各组件入口函数有注释说明用途。 |
| **§4 函数拆分** | 逻辑已拆到 `components/`（config、value-resolver、expression-evaluator、runtime-api、workflow-parser、actions/*）。 |
| **§7 最少代码** | 无多余封装，按需引用组件。 |
| **§8 无 console.log** | 已移除生产代码中的 `console.log`（如 `components/actions/log-parser.js`）。 |
| **§11 switch** | 操作类型分支使用 `switch (action.type)` / `switch (method)`。 |
| **§12 提前 return** | 多数分支使用提前 return，减少 else。 |
| **§13 存在性检查** | `runtime-api.js` 中 `appendLog` 不再用 `existsSync` 判断目录，直接 `fs.mkdirSync(logDir, { recursive: true })`。 |

## 与规范不一致处（及原因）

| 规范 | 当前做法 | 说明 |
|------|----------|------|
| **§5 不使用 try-catch** | 编译器内仍有多处 try-catch | 工作流引擎需要把「单步失败」当作正常结果：失败时写入 log.txt 并返回 `{ success: false }`，由调用方决定是否继续，而不是让进程直接崩溃。若全部去掉 try-catch，任何一步异常都会导致整次执行中断且无结构化错误信息。 |
| **§13 存在性检查** | `fun/img-center-point-location.js`、`fun/img-cropping.js` 中仍有 `fs.existsSync` 选 Python 路径 | 用于在多个候选路径（venv/Scripts、py 嵌入等）中选第一个存在的。若改为「不检查、直接使用第一个」，在部分环境会直接报错。若希望严格符合 §13，可改为固定顺序尝试 `require`/执行，失败再试下一个并最终抛错，而不是先 existsSync。 |

## 建议后续可做

- **§5**：若希望逐步向「少用 try-catch」靠拢，可只保留「步骤执行 + 写 log」这一层 try-catch，内部解析/变量等尽量不捕错，让异常上抛到该层统一记录。
- **§13**：`fun` 下 Python 路径解析可重构为「按顺序尝试路径，失败即抛错」，去掉 existsSync，由调用链决定是否捕获。

## 文件结构（与规范对应）

```
nodejs/ef-compiler/
├── ef-compiler.js          # 主机：解析与执行入口，引用 components
├── components/             # 无 UI，仅逻辑，符合 §4、§6 不适用
│   ├── compiler-config.js
│   ├── value-resolver.js
│   ├── expression-evaluator.js
│   ├── runtime-api.js
│   ├── workflow-parser.js
│   └── actions/            # 各 type 的 parse/execute 拆分
└── fun/                    # 各能力实现（图像、聊天等）
```

上述为当前与 [CODING_STANDARDS.md](./CODING_STANDARDS.md) 的对照与实施说明，后续若规范或 ef-compiler 职责有变更，可再更新本文档。