FlowScript 0.1: A semantic language for describing applications before implementation

FlowScript 0.1：一种在实现前描述应用程序的语义语言

I’ve been exploring a question that sits somewhere between software architecture, DSL design, application modeling, UX structure, and programming-language design: Can we describe the semantic model of an application in a compact, human-readable notation before implementation begins? That experiment is now public as FlowScript 0.1. 我一直在探索一个介于软件架构、DSL（领域特定语言）设计、应用建模、用户体验结构和编程语言设计之间的问题：我们能否在开始实现之前，用一种紧凑且易于阅读的符号来描述应用程序的语义模型？这项实验现已作为 FlowScript 0.1 公开发布。

GitHub repository: https://github.com/erlandkjensli-hue/FlowScript GitHub 仓库：https://github.com/erlandkjensli-hue/FlowScript

The current release is an experimental working draft: https://github.com/erlandkjensli-hue/FlowScript/releases/tag/v0.1.0 当前版本是一个实验性的工作草案：https://github.com/erlandkjensli-hue/FlowScript/releases/tag/v0.1.0

From flowcharts to application semantics

从流程图到应用语义

The idea started from a familiar problem. Flowcharts are useful for showing sequences, decisions, and transitions. But modern applications contain much more than a sequence of boxes and arrows. An application also has: structure and hierarchy, logical destinations, UI structure, navigation, user interactions, actions and side effects, conditions, state, context and dataflow, validation, asynchronous behavior, errors and feedback, reusable structures, responsive presentation. 这个想法源于一个熟悉的问题。流程图对于展示顺序、决策和转换非常有用，但现代应用程序包含的内容远不止方框和箭头的序列。一个应用程序还包括：结构与层级、逻辑目的地、UI 结构、导航、用户交互、动作与副作用、条件、状态、上下文与数据流、验证、异步行为、错误与反馈、可重用结构以及响应式呈现。

Trying to represent all of this as a traditional flowchart quickly becomes awkward. That led to a different question: What if the diagram is only one possible projection of a more fundamental application model? FlowScript explores that idea. 试图用传统的流程图来表示所有这些内容很快就会变得笨拙。这引出了另一个问题：如果图表只是更基础的应用模型的一种可能投影呢？FlowScript 正在探索这一理念。

The central idea

核心理念

The current proposal is that FlowScript should describe the semantic model of an application, rather than its implementation. In other words: Describe what the application is and how it behaves before deciding how it is implemented. 目前的提议是，FlowScript 应该描述应用程序的语义模型，而不是其实现方式。换句话说：在决定如何实现之前，先描述应用程序是什么以及它如何运行。

A FlowScript document should ideally remain meaningful if the implementation changes. It should not need to know whether the eventual application uses React, another UI framework, a particular backend, a particular database, or a particular deployment architecture. The implementation is downstream. 理想情况下，即使实现方式发生变化，FlowScript 文档也应保持其意义。它不需要知道最终的应用程序是使用 React、其他 UI 框架、特定的后端、特定的数据库还是特定的部署架构。实现是下游的事情。

Structure is not navigation

结构不等于导航

One of the first problems that appears in application modeling is that hierarchy and navigation are easy to confuse. Suppose we have: 在应用建模中出现的最早问题之一是层级和导航很容易混淆。假设我们有：

page:LIST
  list:ITEMS
    item:ITEM

This tells us something about structure. It does not necessarily tell us that the user can navigate from LIST to ITEM. That relationship should be explicit: 这告诉了我们关于结构的一些信息，但并不一定说明用户可以从 LIST 导航到 ITEM。这种关系应该是明确的：

page:LIST
  list:ITEMS
    item:ITEM
      goto:DETAIL
page:DETAIL

This distinction may seem small, but it matters because hidden inference makes models ambiguous. FlowScript currently treats the structural tree and the navigation graph as related but separate concepts. 这种区别看起来很小，但很重要，因为隐藏的推断会使模型变得模棱两可。FlowScript 目前将结构树和导航图视为相关但独立的概念。

Structure, navigation, and state are different graphs

结构、导航和状态是不同的图

A mature FlowScript document will probably contain multiple overlapping structures rather than one universal graph. At minimum: 一个成熟的 FlowScript 文档可能包含多个重叠的结构，而不是一个通用的图表。至少包括：

• Structural tree: What contains what. 结构树：包含关系。
• Navigation graph: What can lead to what. 导航图：跳转关系。
• State graph: How state changes. 状态图：状态如何变化。

These relationships may refer to the same semantic objects, but they answer different questions. That separation is one of the core ideas being tested in 0.1. 这些关系可能指向相同的语义对象，但它们回答的是不同的问题。这种分离是 0.1 版本中测试的核心理念之一。

Structure is not presentation either

结构也不等于呈现

Another important distinction is between the logical application model and the way that model is presented on a device or viewport. For example, the same logical destination might appear as a complete page on a compact layout and as a pane alongside other content on a larger layout. The semantic identity should remain the same. 另一个重要的区别在于逻辑应用模型与该模型在设备或视口上的呈现方式之间。例如，同一个逻辑目的地在紧凑布局中可能显示为完整页面，而在较大布局中则显示为与其他内容并排的面板。其语义身份应保持不变。

Conceptually: page:DETAIL could be presented as: 从概念上讲：page:DETAIL 可以呈现为：

• compact: DETAIL
• regular: LIST | DETAIL
• expanded: NAVIGATION | LIST | DETAIL

The presentation changes. The application model does not. This leads to a broader hypothesis: Responsive UI can be treated as a projection of the semantic model rather than a collection of separate application hierarchies. 呈现方式变了，但应用模型没变。这引出了一个更广泛的假设：响应式 UI 可以被视为语义模型的投影，而不是一系列独立的应用程序层级集合。

Actions are not navigation

动作不等于导航

Another distinction is between what the user does and what the system does. For example: 另一个区别在于用户所做的与系统所做的。例如：

button:"Save"
  action:SAVE
  goto:HOME

There are two different semantic events here. The user interacts with a control. The system performs an action. Then the navigation context changes. Keeping those concepts separate makes behavior easier to reason about and potentially easier to reuse. 这里有两个不同的语义事件。用户与控件交互；系统执行动作；然后导航上下文发生变化。保持这些概念的分离使得行为更容易推理，也可能更容易重用。

Conditions are not state

条件不等于状态

FlowScript also explores a strict distinction between conditions and state. A condition asks: Is this predicate true? For example: condition:USER_AUTHENTICATED. State asks: What state is this object or process in? For example: state:LOADING, state:ERROR, state:ACTIVE, state:ARCHIVED. FlowScript 还探索了条件和状态之间的严格区别。条件询问的是：这个谓词是否为真？例如：condition:USER_AUTHENTICATED。状态询问的是：这个对象或进程处于什么状态？例如：state:LOADING、state:ERROR、state:ACTIVE、state:ARCHIVED。

The distinction becomes important when models become more complex. A state machine, a boolean predicate, a visibility condition, and a permission rule may all affect what the user sees, but they are not necessarily the same semantic thing. 当模型变得复杂时，这种区别就变得很重要。状态机、布尔谓词、可见性条件和权限规则都可能影响用户看到的内容，但它们并不一定是同一个语义事物。

A deliberately small syntax

刻意保持简洁的语法

One design goal is to keep the written notation simple. The current direction is roughly: keyword:value with indentation expressing semantic nesting. For example: 一个设计目标是保持书写符号的简洁。目前的方向大致是：keyword:value，并使用缩进表示语义嵌套。例如：

page:DETAIL
  heading:"Detail"
  field:VALUE
  button:"Save"
    action:SAVE
    goto:HOME

The syntax is intentionally lightweight. The underlying semantics should be much stricter than the notation looks. That gives us an important design principle: Syntactic simplicity, semantic strictness. 语法被刻意设计得轻量化。底层的语义应该比符号看起来要严格得多。这为我们提供了一个重要的设计原则：语法简洁，语义严格。

A future parser should be able to validate references, nesting, targets, conditions, state declarations, and other relationships even though the source remains relatively easy to read and write. 未来的解析器应该能够验证引用、嵌套、目标、条件、状态声明和其他关系，即使源代码仍然保持相对易读易写。

What FlowScript is not

FlowScript 不是什么

FlowScript is not intended to replace programming languages. It is not intended to replace: TypeScript, JavaScript, HTML, CSS, backend code, API schemas, database schemas, visual design tools. FlowScript 无意取代编程语言。它也不打算取代：TypeScript、JavaScript、HTML、CSS、后端代码、API 模式、数据库模式或视觉设计工具。

The idea is to operate at a different level. A FlowScript document could describe the semantic structure and behavior of an application, while implementation technologies determine how that model becomes software. 其理念是在不同的层面上运作。FlowScript 文档可以描述应用程序的语义结构和行为，而实现技术则决定了该模型如何转化为软件。

The possible long-term direction

可能的长期方向

There is a larger hypothesis behind the project. If a semantic application model can be expressed rigorously enough, the same source could potentially support multiple projections. For example: 该项目背后有一个更大的假设。如果语义应用模型能够被足够严谨地表达，那么同一个源文件就有可能支持多种投影。例如：

FlowScript ├── hierarchy diagram ├── navigation graph ├── state diagram └── …