# IR4LLM

**Repository Path**: di_zhao/IR4LLM

## Basic Information

- **Project Name**: IR4LLM
- **Description**: # IR4LLM FSM 编辑器
> 便于大模型理解的有限状态机高层中间表示 · 8步标准化撰写流程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IR4LLM FSM 编辑器

> 便于大模型理解的有限状态机高层中间表示 · 8步标准化撰写流程

## 目录

- [项目简介](#项目简介)
- [技术架构](#技术架构)
- [核心概念：IR4LLM 中间表示](#核心概念ir4llm-中间表示)
  - [与 DFA 五元组的对应关系](#与-dfa-五元组的对应关系)
  - [IR4LLM YAML 结构](#ir4llm-yaml-结构)
  - [Guard 语法](#guard-语法)
  - [Action 语法](#action-语法)
- [8步撰写流程](#8步撰写流程)
- [校验引擎](#校验引擎)
  - [结构校验](#结构校验)
  - [语义校验](#语义校验)
  - [逻辑校验](#逻辑校验)
- [API 接口](#api-接口)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [示例](#示例)

---

## 项目简介

**IR4LLM 编辑器** 是一个基于 Spring Boot 的全栈 Web 应用，用于可视化构建和编辑面向 LLM（大语言模型）的有限状态机（FSM）高层中间表示（IR4LLM）。

与传统面向硬件的状态机描述语言（如 Verilog、VHDL）不同，IR4LLM 的设计目标是**让大模型能够准确理解、生成和推理** FSM 的业务逻辑。它采用扁平化结构、显式实体声明和自然语言友好的注释，使 LLM 可以作为"FSM 工程师"参与状态机的设计、验证和文档生成。

### 核心特性

| 特性 | 说明 |
|------|------|
| **8步向导式编辑** | 从状态定义到最终校验，每步均有详细提示和注释 |
| **双层校验引擎** | 结构校验 + 语义/逻辑校验，覆盖类型、引用、可达性等 |
| **Moore 输出模型** | 输出与状态绑定，便于 LLM 理解因果关系 |
| **Guard/Action 分离** | 条件判断（guard）与赋值动作（action）分离，语义清晰 |
| **优先级转移** | 同一源状态多条转移按数组顺序匹配，第一条命中即跳转 |
| **YAML 导入/导出** | 支持 `.hir.yaml` 文件的双向转换，便于版本管理 |
| **会话式编辑** | 基于 HTTP Session 的即时保存，步骤间无缝切换 |
| **LLM 友好注释** | 每个字段均支持中文注释，自然语言描述业务意图 |

---

## 技术架构

```
┌─────────────────────────────────────────────────┐
│                  浏览器 (用户端)                  │
│  ┌─────────────────────────────────────────────┐ │
│  │  单页应用 (SPA) - index.html                 │ │
│  │  ├── 8步向导 UI                             │ │
│  │  ├── 实时表单校验                           │ │
│  │  ├── YAML 预览与下载                        │ │
│  │  └── 帮助提示 (每步详细说明)                 │ │
│  └─────────────────────────────────────────────┘ │
│                      │                            │
│                      │  JSON / HTTP REST          │
│                      ▼                            │
│  ┌─────────────────────────────────────────────┐ │
│  │  Spring Boot 后端                           │ │
│  │  ├── EditorController  (REST API)           │ │
│  │  ├── ValidationService (校验引擎)            │ │
│  │  ├── YamlService       (YAML 序列化)        │ │
│  │  └── Ir4llmDocument    (数据模型)           │ │
│  └─────────────────────────────────────────────┘ │
│                      │                            │
│                      ▼                            │
│  ┌─────────────────────────────────────────────┐ │
│  │  Jackson / YAML 引擎                        │ │
│  │  ├── JSON ⇄ Java 对象映射                   │ │
│  │  ├── YAML ⇄ Java 对象映射                   │ │
│  │  └── 自定义 YAML 格式化输出                 │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
```

### 技术栈

| 层次 | 技术 | 版本 |
|------|------|------|
| 语言 | Java | 21+ |
| 框架 | Spring Boot | 3.3.5 |
| 数据库 | 无（基于 Session 的内存存储） | — |
| JSON/YAML | Jackson + jackson-dataformat-yaml | 2.x |
| 前端 | 原生 HTML/CSS/JavaScript（无框架依赖） | — |
| 构建 | Maven | 3.x |

---

## 核心概念：IR4LLM 中间表示

### 与 DFA 五元组的对应关系

IR4LLM 是对经典确定有限自动机（DFA）五元组 `<Σ, Q, δ, q₀, F>` 的扩展和重新组织：

| DFA 五元组 | IR4LLM 对应字段 | 说明 |
|-----------|----------------|------|
| Q（有限状态集合） | `states` | 每个状态含 `moore_out` 和 `comment` |
| Σ（输入字母表） | `inputs` | 带类型标注的信号列表 |
| δ（转移函数） | `transitions` | 扁平数组，`guard` + `action` 描述 |
| q₀（初始状态） | `meta.init_state` | 必须存在于 `states` 中 |
| F（终止状态集合） | `meta.fallback_strategy` | 默认策略（stay/error）代替显式终态 |
| *扩展* | `outputs` | Moore 输出信号（状态绑定） |
| *扩展* | `internal_vars` | 跨时钟周期的内部寄存器 |

### IR4LLM YAML 结构

完整的 IR4LLM 文档由以下顶层字段组成：

```yaml
# === 元信息块 ===
meta:
  name: fsm_name              # 状态机唯一标识（字母、数字、下划线）
  init_state: S_IDLE          # 初始状态（必须存在于 states 中）
  fallback_strategy: stay     # 默认策略：stay（停留）| error（跳错误态）
  state_width: 4              # 状态寄存器位宽（可选，仅下游转换器使用）

# === 输入信号 ===
inputs:
  - {name: req, type: i1, comment: "请求信号"}
  - {name: data, type: u8, comment: "数据总线"}

# === 输出信号（Moore 输出） ===
outputs:
  - {name: busy, type: i1, comment: "忙信号"}
  - {name: err, type: i1, comment: "错误标志"}

# === 内部变量（跨时钟周期） ===
internal_vars:
  - {name: error_flag, type: i1, comment: "错误标记"}
  - {name: cnt, type: u10, comment: "计数器"}

# === 状态定义 ===
states:
  S_IDLE:
    moore_out: {busy: 0, err: 0}   # 完整覆盖所有输出
    comment: "空闲状态，等待请求"
  S_WORK:
    moore_out: {busy: 1, err: 0}
    comment: "工作状态，处理请求"
  S_ERROR:
    moore_out: {busy: 0, err: 1}
    comment: "错误状态，等待复位"

# === 转移规则（扁平数组） ===
transitions:
  - curr: S_IDLE
    target: S_WORK
    guard: "req == 1"
    action: ["error_flag = 0", "cnt = 0"]
    comment: "收到请求进入工作状态"
  - curr: S_WORK
    target: S_ERROR
    guard: "error_flag == 1"
    action: []
    comment: "检测到错误，进入错误态"
```

### Guard 语法

`guard` 字段是双引号包裹的布尔表达式，支持以下运算符：

| 运算符 | 含义 | 示例 |
|--------|------|------|
| `!` | 逻辑非 | `!req` |
| `&` | 逻辑与 | `req == 1 & data_vld == 1` |
| `\|\|` | 逻辑或 | `req == 1 \|\| retry == 1` |
| `==` | 等于 | `state == 0` |
| `!=` | 不等于 | `err_flag != 0` |
| `()` | 分组 | `(a == 1 \|\| b == 1) & c == 0` |

Guard 中**只能引用**以下标识符：
- `inputs` 中定义的输入信号
- `internal_vars` 中定义的内部变量

无条件跳转写 `"true"`。

### Action 语法

`action` 是字符串数组，每个元素为一条赋值语句：

```
action: ["var1 = expr1", "var2 = expr2"]
```

规则：
- 格式为 `变量名 = 表达式`
- 左侧变量**必须**在 `internal_vars` 中定义
- 右侧表达式可引用 `inputs` 和 `internal_vars`
- 无赋值时写 `[]`
- 赋值语句之间用逗号分隔（在 UI 中输入时）

---

## 8步撰写流程

### 第一步：状态定义

定义 FSM 的全部状态集合 Q。

- **命名规范**：大写字母 + 下划线，以 `S_` 前缀，如 `S_IDLE`、`S_WORK`
- **必填**：至少 1 个状态，其中 1 个为初始状态（第五步指定）
- **建议**：空闲态（S_IDLE）、错误态（S_ERROR）

### 第二步：输入信号

定义外部输入信号列表 Σ。

- **命名规范**：小写字母 + 下划线，如 `req_in`、`ack_out`
- **类型**：`i1`（1bit 布尔）、`u8`/`u16`（多bit 总线/计数）
- **提示**：1bit 使能/有效/请求/应答信号一律用 `i1`

### 第三步：输出信号

定义输出信号列表（Moore 输出）。

- Moore 输出只取决于当前状态，写在 `states[*].moore_out` 中
- 每个状态的 `moore_out` 必须完整覆盖此处定义的全部输出
- 注释栏建议写明物理/业务含义

### 第四步：中间变量

定义扩展时序内部变量 `internal_vars`。

- 跨时钟周期保存的寄存器变量
- **读取权限**：可在 guard 中读取（只读）
- **写入权限**：只能在 transition 的 action 中赋值
- 若无需跨周期记忆，可留空

### 第五步：元信息

编写 `meta` 元信息块。

| 字段 | 说明 |
|------|------|
| `name` | 状态机唯一标识，小写下划线命名 |
| `init_state` | 复位后进入的初始状态 |
| `fallback_strategy` | 默认策略：`stay`（停留当前状态）/ `error`（跳错误态） |
| `state_width` | 状态寄存器位宽，仅下游转换器使用 |

### 第六步：状态详细

为每个状态配置 Moore 输出值和业务注释。

- 每个状态的 `moore_out` 必须覆盖所有输出信号
- 输出值只能是 `0` 或 `1`
- 注释是 LLM 理解业务语义的关键

### 第七步：转移规则

编写 `transitions` 扁平转移数组。

- `curr`：源状态
- `target`：目标状态
- `guard`：双引号包裹的布尔表达式
- `action`：数组，仅修改 `internal_vars`
- 同一源状态的多条转移按数组顺序匹配，**第一条命中即跳转**

### 第八步：校验生成

运行双层校验，生成最终 `.hir.yaml` 文件。

- **结构校验**：检查字段完整性、类型、枚举值
- **语义校验**：检查引用合法性、可达性、guard 重叠等
- **人工审核**：校验通过后请人工复核 YAML 内容

---

## 校验引擎

### 结构校验

检查文档的格式合规性：

| 校验项 | 级别 | 说明 |
|--------|------|------|
| `meta.name` 非空且合法 | ERROR | 只能包含字母、数字、下划线 |
| `meta.init_state` 非空 | ERROR | 初始状态不可省略 |
| `meta.fallback_strategy` 枚举值 | ERROR | 只能为 `stay` 或 `error` |
| 信号名唯一且合法 | ERROR | 不可重复、不可含特殊字符 |
| 信号类型格式 | ERROR | 必须为 `i`/`u` + 数字 |
| 转移 `curr/target/guard` 非空 | ERROR | 关键字段不可省略 |
| `action` 字段存在 | ERROR | 无赋值时必须写 `[]` |

### 语义校验

检查字段间的引用合法性：

| 校验项 | 级别 | 说明 |
|--------|------|------|
| `init_state` 存在于 `states` | ERROR | 初始状态必须已定义 |
| guard 引用的标识符已定义 | ERROR | 只能引用 `inputs` 和 `internal_vars` |
| action 左侧变量在 `internal_vars` 中 | ERROR | 不可赋值给不存在的变量 |
| action 右侧引用合法 | WARNING | 可能引用未定义标识符 |
| `moore_out` 覆盖所有输出 | ERROR | 每个状态必须完整覆盖 |
| `moore_out` 值为 0/1 | ERROR | Moore 输出只能是 0 或 1 |
| inputs 与 internal_vars 不重名 | ERROR | 命名空间必须唯一 |
| `fallback_strategy=error` 时存在 ERROR 状态 | WARNING | 建议预先定义 |

### 逻辑校验

检查状态机的逻辑合理性：

| 校验项 | 级别 | 说明 |
|--------|------|------|
| 状态可达性分析 | WARNING | 从初始状态不可达的状态给出警告 |
| guard 重叠检测 | WARNING | 前序转移 guard 为 `true` 时，后续转移永远不会触发 |
| 转移数量过多 | INFO | 同状态转移超过 5 条时提示确认优先级 |
| guard 中不含赋值语句 | ERROR | 赋值只能写在 action 中 |
| guard 中不含保留关键字 | ERROR | 禁止使用 `and`/`or`/`not`/`assign` |

---

## API 接口

所有接口前缀为 `/api`，使用 HTTP Session 保存文档状态。

### 文档管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/document` | 获取当前会话的文档 |
| POST | `/api/document/reset` | 重置为默认示例文档 |
| POST | `/api/document/import` | 导入 YAML 文本（`{yaml: "..."}`） |

### 分步骤保存

| 方法 | 路径 | 请求体 | 说明 |
|------|------|--------|------|
| POST | `/api/step1/states` | `["S_IDLE", "S_WORK"]` | 保存状态列表 |
| POST | `/api/step2/inputs` | `[{name, type, comment}]` | 保存输入信号 |
| POST | `/api/step3/outputs` | `[{name, type, comment}]` | 保存输出信号 |
| POST | `/api/step4/internal-vars` | `[{name, type, comment}]` | 保存内部变量 |
| POST | `/api/step5/meta` | `{name, init_state, fallback_strategy, state_width}` | 保存元信息 |
| POST | `/api/step6/states-detail` | `{stateName: {moore_out, comment}}` | 保存状态详情 |
| POST | `/api/step7/transitions` | `[{curr, target, guard, action, comment}]` | 保存转移规则 |

### 校验与生成

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/step8/validate` | 运行校验，返回错误列表 |
| GET | `/api/step8/yaml` | 生成 YAML 文本 + 校验结果 |
| GET | `/api/step8/download` | 下载 `.hir.yaml` 文件 |

### 校验响应格式

```json
{
  "passed": false,
  "errorCount": 2,
  "warningCount": 1,
  "errors": [
    {
      "level": "ERROR",
      "category": "semantic",
      "field": "meta.init_state",
      "message": "init_state 'S_RUN' 不存在于states中"
    }
  ]
}
```

---

## 快速开始

### 环境要求

- Java 21 或更高版本
- Maven 3.8+

### 构建与运行

```bash
# 克隆项目
cd ir4llm-editor

# 构建（跳过测试）
mvn clean package -DskipTests

# 运行
java -jar target/ir4llm-editor-1.0.0.jar
```

启动后访问浏览器打开 `http://localhost:8080/`。

### 开发模式运行

```bash
mvn spring-boot:run
```

### 导入已有 YAML

1. 启动应用后访问 `http://localhost:8080/`
2. 在步骤 8 点击「📂 导入YAML」
3. 选择 `.hir.yaml` 文件
4. 系统自动解析并跳转到步骤 1 继续编辑

### 下载生成的 YAML

1. 完成所有 8 步编辑
2. 在步骤 8 点击「⬇ 下载.hir.yaml」
3. 文件名自动使用 `meta.name` + `.hir.yaml`

---

## 项目结构

```
ir4llm-editor/
├── src/
│   └── main/
│       ├── java/com/ir4llm/
│       │   ├── Ir4llmApplication.java      # Spring Boot 启动类
│       │   ├── controller/
│       │   │   └── EditorController.java   # REST API 控制器
│       │   ├── model/
│       │   │   ├── Ir4llmDocument.java     # 文档根模型
│       │   │   ├── Meta.java               # meta 元信息
│       │   │   ├── Signal.java             # 信号（inputs/outputs/internal_vars 共用）
│       │   │   ├── FsmState.java           # 状态（含 moore_out + comment）
│       │   │   ├── Transition.java         # 转移规则
│       │   │   └── ValidationError.java    # 校验错误模型
│       │   └── service/
│       │       ├── ValidationService.java  # 校验引擎（结构+语义+逻辑）
│       │       └── YamlService.java        # YAML 序列化/反序列化
│       └── resources/
│           ├── application.properties     # Spring Boot 配置
│           └── static/
│               └── index.html              # 单页前端应用
├── pom.xml
└── README.md
```

### 模型关系图

```
Ir4llmDocument
├── Meta (name, init_state, fallback_strategy, state_width)
├── List<Signal> inputs          # 外部输入信号
├── List<Signal> outputs         # 输出信号（Moore 输出）
├── List<Signal> internal_vars   # 跨周期内部变量
├── Map<String, FsmState> states
│   └── FsmState
│       ├── Map<String, Integer> moore_out   # 输出信号名 → 0/1
│       └── String comment
└── List<Transition> transitions
    └── Transition
        ├── String curr         # 源状态
        ├── String target       # 目标状态
        ├── String guard        # 布尔表达式
        ├── List<String> action # 赋值语句数组
        └── String comment
```

---

## 开发指南

### 新增校验规则

在 `ValidationService.java` 中添加新的校验逻辑：

1. **结构校验**：在 `validateStructural()` 方法中添加规则
2. **语义校验**：在 `validateSemantic()` 方法中添加规则
3. **逻辑校验**：在 `validateSemantic()` 方法末尾的逻辑分析区域添加规则

每条校验错误通过 `new ValidationError(level, category, field, message)` 构造：
- `level`：`ERROR` / `WARNING` / `INFO`
- `category`：`structural` / `semantic` / `logic`
- `field`：出错字段的路径（如 `transitions[0].guard`）
- `message`：中文描述消息

### 自定义 YAML 格式

在 `YamlService.java` 中控制 YAML 输出格式：
- `yamlString()` 处理需要引号包裹的字符串
- `doubleQuoted()` 强制双引号包裹（用于 guard 和 action）
- `toYaml()` 方法按字段顺序拼接输出

### 扩展数据模型

1. 在 `model/` 包下创建新的 POJO
2. 在 `Ir4llmDocument.java` 中添加引用字段
3. 在 `EditorController.java` 中添加对应的保存接口
4. 在 `YamlService.java` 中添加序列化逻辑

### 修改 UI

所有前端代码在 `src/main/resources/static/index.html` 中，为单文件 SPA：
- 步骤定义在 `STEPS` 数组中
- 每步的渲染函数为 `renderStepN()`
- CSS 样式在 `<style>` 块中
- 帮助框使用 `.help-box` 类

---

## 示例

### 最小示例（S_IDLE → S_WORK）

```yaml
meta:
  name: min_fsm
  init_state: S_IDLE
  fallback_strategy: stay

inputs:
  - {name: start, type: i1, comment: "启动信号"}

outputs:
  - {name: running, type: i1, comment: "运行中指示"}

states:
  S_IDLE:
    moore_out: {running: 0}
    comment: "空闲状态"
  S_WORK:
    moore_out: {running: 1}
    comment: "运行状态"

transitions:
  - curr: S_IDLE
    target: S_WORK
    guard: "start == 1"
    action: []
    comment: "启动信号有效时进入运行状态"
```

### 带内部变量的示例（带错误处理）

```yaml
meta:
  name: error_handling_fsm
  init_state: S_IDLE
  fallback_strategy: error
  state_width: 3

inputs:
  - {name: req, type: i1, comment: "请求信号"}
  - {name: clk, type: i1, comment: "时钟信号"}

outputs:
  - {name: busy, type: i1, comment: "忙信号"}
  - {name: err, type: i1, comment: "错误指示"}

internal_vars:
  - {name: error_flag, type: i1, comment: "错误标记"}
  - {name: retry_cnt, type: u8, comment: "重试计数"}

states:
  S_IDLE:
    moore_out: {busy: 0, err: 0}
    comment: "空闲状态，等待请求"
  S_PROCESS:
    moore_out: {busy: 1, err: 0}
    comment: "处理状态，执行请求"
  S_ERROR:
    moore_out: {busy: 0, err: 1}
    comment: "错误状态，等待复位"

transitions:
  - curr: S_IDLE
    target: S_PROCESS
    guard: "req == 1"
    action: ["error_flag = 0", "retry_cnt = 0"]
    comment: "收到请求，开始处理"
  - curr: S_PROCESS
    target: S_ERROR
    guard: "error_flag == 1"
    action: []
    comment: "处理中检测到错误"
  - curr: S_PROCESS
    target: S_IDLE
    guard: "retry_cnt >= 3"
    action: ["retry_cnt = 0"]
    comment: "重试次数超限，回到空闲"
  - curr: S_ERROR
    target: S_IDLE
    guard: "true"
    action: ["error_flag = 0"]
    comment: "错误状态无条件复位"
```

---

## License

© IR4LLM 编辑器 — 用于教学和研究目的。

## 相关文档

项目中包含详细的设计文档，位于 `doc/` 子目录：

- `IR4LLM FSM高层中间表示完整文档.docx` — IR4LLM 完整规范说明
- `IR4LLM 完整详细撰写流程（通用版本）.docx` — 8步撰写流程详解
- `IR4LLM JSON-Schema + 校验详细说明.docx` — 校验规则详细说明
- `IR4LLM 完整撰写规则.docx` — 撰写规则汇总
- `IR4LLM 极简空白模板.docx` — 空白模板参考