woml README

项目的 README,来自 github.com/dali-benothmen/woml。合并为一个 markdown 文件:README.md。

WOML: Workflow Orchestration Markup Language

WOML — Workflow Orchestration Markup Language

If you can read HTML, you can build workflows, apps, and AI agents with WOML.

Readable markup for structure. JavaScript for logic. A durable runtime for execution.

npm version GitHub stars License Platforms

Website · Documentation · Examples

What is WOML?

WOML is an open-source, code-first language and runtime for building automated workflows, backend applications, and AI agents. Describe the process in readable, HTML-inspired markup, use JavaScript for logic, and connect the APIs, services, databases, local tools, and infrastructure involved.

Each .woml file combines three parts:

The workflow source is the program, its readable architecture, and its execution policy. It can live in Git, move through pull requests and CI, and run locally or on infrastructure you control.

Start with one workflow for a local task or webhook. As the work grows, extract reusable modules, call or start other workflows, publish events, and operate the result as a coordinated system without changing its underlying model.

What can you build?

Build Use WOML to
Automated workflows Process orders, onboard customers, generate reports, review content, and coordinate human approvals.
Backend applications Handle webhooks, expose workflow APIs, run scheduled jobs, and coordinate event-driven services.
AI agents Connect models, tools, memory, specialist workflows, and human review in one durable process.
Data pipelines Import, validate, transform, classify, and store data with explicit control flow and recovery.
Infrastructure systems Run deployment checks, supervise local processes, coordinate infrastructure changes, and respond to incidents.

Why code-first WOML?

How WOML works

  1. Describe the process in a .woml file using triggers, steps, control flow, and runtime policies.
  2. Connect your tools with inline JavaScript, imported modules, managed services, secrets, and reusable child workflows.
  3. Run and operate it with the WOML runtime, which records durable state and provides inspection, cancellation, recovery, logs, and backups.

Installation

WOML requires Bun 1.3.14 or later. Install the global CLI with npm:

npm install --global woml-cli

Or install it with Bun or pnpm:

bun add --global woml-cli
pnpm add --global woml-cli

All three commands install the same woml executable:

woml --version

Native engines are selected automatically for supported macOS, Linux, and Windows systems. You do not need to install the platform packages or configure a database manually.

Linux packages require glibc 2.31 or newer.

Quick Start: Build an Order Router

Create a file named order-router.woml:

<woml>
  <workflow
    id="order-router"
    name="Order Router"
    description="Check inventory and risk concurrently, then route the order."
    version="1.0.0"
  >
    <triggers>
      <webhook
        id="newOrder"
        path="/webhooks/orders"
        method="POST"
        auth="none"
      >
        <schema>
          {
            "type": "object",
            "required": ["orderId", "amount", "inStock", "riskScore"],
            "properties": {
              "orderId": { "type": "string" },
              "amount": { "type": "number" },
              "inStock": { "type": "boolean" },
              "riskScore": { "type": "number" }
            },
            "additionalProperties": false
          }
        </schema>
      </webhook>
    </triggers>

    <steps>
      <step
        id="prepareOrder"
        name="Prepare order"
        description="Normalize the order received by the webhook."
      >
        <script>
          return {
            orderId: context.payload.orderId,
            amount: context.payload.amount
          };
        </script>
      </step>

      <parallel
        id="orderChecks"
        name="Run order checks"
        description="Check inventory and risk at the same time."
        concurrency="2"
        on-error="wait-all"
      >
        <step
          id="inventoryCheck"
          name="Check inventory"
          description="Confirm that the requested item is available."
        >
          <script>
            return { available: context.payload.inStock };
          </script>
        </step>

        <step
          id="riskCheck"
          name="Check risk"
          description="Accept orders with a risk score below seventy."
        >
          <script>
            return {
              approved: context.payload.riskScore < 70,
              score: context.payload.riskScore
            };
          </script>
        </step>
      </parallel>

      <step
        id="canFulfill"
        name="Make decision"
        description="Combine the inventory and risk results."
      >
        <script>
          return {
            value:
              context.steps.inventoryCheck.available &&
              context.steps.riskCheck.approved
          };
        </script>
      </step>

      <choose
        id="orderRoute"
        name="Route order"
        description="Accept the order or send it for review."
      >
        <when test="{{context.steps.canFulfill.value}}">
          <step id="acceptOrder" name="Accept order">
            <script>
              return {
                status: "accepted",
                message: `Order ${context.steps.prepareOrder.orderId} is ready for fulfillment.`
              };
            </script>
          </step>
          <result value="{{context.steps.acceptOrder}}" />
        </when>

        <otherwise>
          <step id="reviewOrder" name="Request review">
            <script>
              return {
                status: "review",
                message: `Order ${context.steps.prepareOrder.orderId} needs review.`
              };
            </script>
          </step>
          <result value="{{context.steps.reviewOrder}}" />
        </otherwise>
      </choose>

      <step
        id="response"
        name="Build response"
        description="Publish one predictable result for the caller."
      >
        <script>
          return {
            orderId: context.steps.prepareOrder.orderId,
            amount: context.steps.prepareOrder.amount,
            ...context.steps.orderRoute
          };
        </script>
      </step>
    </steps>
  </workflow>
</woml>

Check it without starting the automation:

woml check order-router.woml

Then run it:

woml run order-router.woml

WOML keeps the automation active and prints its webhook URL together with a generated curl command. Trigger it from another terminal:

curl --request POST http://127.0.0.1:3000/webhooks/orders \
  --header 'content-type: application/json' \
  --data '{"orderId":"order-42","amount":240,"inStock":true,"riskScore":18}'

Use auth="none" only for local development. Configure authenticated webhooks before exposing an endpoint outside a trusted environment.

How the Workflow Runs

flowchart TD
    trigger[POST /webhooks/orders] --> prepare[Prepare order]
    prepare --> parallel{Run concurrently}
    parallel --> inventory[Check inventory]
    parallel --> risk[Check risk]
    inventory --> decision[Make decision]
    risk --> decision
    decision --> route{Route order}
    route -->|Accepted| accept[Accept order]
    route -->|Needs review| review[Request review]
    accept --> response[Build response]
    review --> response

See the Result

WOML presents each run as an organized, colored terminal report. You will see output like this:

RUN  run_8f21c4                                                Order Router

  ✓  Prepare order                                              3 ms
     Normalize the order received by the webhook.
     → { orderId: "order-42", amount: 240 }

  ✓  Check inventory                                            2 ms
     → { available: true }

  ✓  Check risk                                                 2 ms
     → { approved: true, score: 18 }

  ✓  Make decision                                              1 ms
     → { value: true }

  ✓  Accept order                                               1 ms
     → { status: "accepted", message: "Order order-42 is ready for fulfillment." }

  ✓  Build response                                             1 ms
     → { orderId: "order-42", amount: 240, status: "accepted" }

Completed in 10 ms · 6 succeeded

The exact run ID and timings will differ. Press Ctrl+C to stop the active workflow host.

What You Just Built

Explore what you can build

Every example below is checked against the current WOML compiler.

Build What it demonstrates Run
Durable run counter State that survives future runs and process restarts woml run examples/durableStateWorkflow.woml
Personalize a customer list Durable per-item execution, bounded concurrency, and ordered results woml run examples/forEachWorkflow.woml
Social distribution Several independent multi-step branches with an explicit join woml run examples/forkDistributionWorkflow.woml
Telegram approval Human approval, interactive notification buttons, and durable waiting woml run examples/telegramApprovalWorkflow.woml
Workflow composition One workflow calling another and using its returned result woml run examples/workflowCallManual
Durable external callback A run that releases its worker and resumes from an idempotent CI signal woml run examples/durableWaits/ciCallback.woml
Preview environment saga Explicit rollback and mandatory cleanup for partial infrastructure success woml run examples/compensationAndCleanup/previewEnvironment.woml
Streamed Terraform release Live process output, structured progress, review, locking, compensation, and replay See the example runbook
Local TypeScript module Reusable project code exposed through services.* woml run examples/moduleWorkflow.woml

Provider examples require their documented credentials. Browse the complete example catalog for webhooks, schedules, intervals, internal events, databases, storage, cache, lifecycle, retries, communication providers, and production deployment.

Build larger systems from reusable workflows

A WOML project can begin with one file and grow into a system of focused workflows and modules. Workflows can call another workflow and wait for its result, start independent work in the background, or publish events that other workflows consume.

Create a project with workflow discovery and operator-owned configuration already in place:

woml init my-project
cd my-project
woml check
woml test

The generated workflow.json keeps workflow discovery, policies, reviewers, and execution targets reviewable while secret values remain outside source control. The same project model supports local execution, durable artifacts and waits, rich approvals, infrastructure policies, streamed output, OpenTelemetry, and authenticated remote targets. Remote work never silently falls back to the coordinator.

Read the project manifest reference, follow the infrastructure-agent tutorial, or use the operator runbook.

Built for real execution

Connect and extend

Structure complex work

Continue through failure

Operate on your infrastructure

When an interrupted external effect has an uncertain outcome, WOML marks it ambiguous instead of retrying it automatically. Inspect the real system with woml dispatch inspect, then record an audited decision with woml dispatch reconcile.

Common Commands

woml check workflows/                    # Parse, validate, and compile
woml run workflows/                      # Activate workflows in the foreground
woml run workflows/ --background         # Activate them in the background
woml inspect                             # Open the colored runtime inspector
woml list                                # List workflows and recent runs
woml get run_...                         # Inspect one run and its event history
woml cancel run_...                      # Cancel a pending or running workflow
woml recover run_... --retry action-id   # Resume a verified-safe corrective attempt
woml logs workflow-id --follow           # Follow live process output and progress
woml secrets set API_TOKEN               # Store a secret without printing it
woml backup backups/latest               # Back up the durable state store
woml prune --before 30d --dry-run        # Preview retention cleanup

See the CLI reference for all commands, flags, exit behavior, and machine-readable output.

VS Code Experience

The WOML extension gives .woml files HTML-style markup highlighting, embedded JavaScript syntax, highlighted runtime bindings such as context and services, reference-expression highlighting, snippets, and a dedicated file icon.

WOML workflow open in Visual Studio Code

The extension follows your existing VS Code theme instead of requiring a separate WOML color theme.

Build WOML with AI coding agents

WOML is structured source code, so coding agents can create and change workflows in the same environment as the rest of your project. The WOML Skill teaches agents the language structure, runtime bindings, control-flow patterns, services, secrets, and validation workflow they need to produce real .woml files without inventing syntax.

Use the WOML skill to build an order-processing workflow that starts from a
webhook, checks inventory and risk concurrently, and routes the result.

The generated workflow remains readable, reviewable in Git, and verifiable with woml check before it runs.

For Claude Code, install the complete skill in the current project:

mkdir -p .claude/skills/woml
curl -fsSL https://github.com/dali-benothmen/woml/releases/latest/download/woml-skill.tar.gz \
  | tar -xz -C .claude/skills/woml

For Codex and other clients that use the Agent Skills project convention:

mkdir -p .agents/skills
cp -R skills/woml .agents/skills/woml

View the WOML Skill and installation guide →

Documentation and Examples

Support and Security

Use GitHub Discussions for questions and GitHub Issues for reproducible bugs. Follow the support guide when sharing diagnostics, and report vulnerabilities privately according to the security policy.

Contributing

Contributions are welcome, including bug reports, documentation improvements, tested examples, provider work, compiler changes, and runtime improvements. Read CONTRIBUTING.md before opening a pull request.

License

WOML is released under the Apache License 2.0.

woml (dali-benothmen/woml)

正在搜索数据库…

174 ·GitHub
这是什么?WOML 是一种开源的、以代码为核心的标记语言和运行时,用于构建自动化工作流、后端应用和 AI 智能体。你用类似 HTML 的标记描述流程,用 JavaScript 编写逻辑,然后由一个可持久化执行的 Rust 运行时来运行,内置重试、等待和恢复机制。
WOML 是无代码工具,还是需要我用代码来写的东西?它以代码为核心。.woml 文件将用于描述结构(触发器、步骤、分支、循环)的可读标记,与内联的 JavaScript 或导入的 JavaScript/TypeScript 模块中的实际逻辑结合在一起。这些文件存放在 Git 中,和其他源代码一样走正常的 PR 和 CI 流程。
我该如何安装和运行它?使用 npm install -g woml 安装全局 CLI(或等效的 Bun/pnpm 命令),这三种方式安装的都是同一个 woml 可执行文件。然后编写一个 .woml 文件,并用 'woml run yourfile.woml' 运行它。
我需要先安装 Bun 吗?需要。WOML 要求安装 Bun 1.3.14 或更高版本。之后会自动为 macOS、Linux 和 Windows 选择对应的原生引擎,并且由于内置了 SQLite/Postgres 支持,无需单独配置数据库。
使用 Webhook 和处理失败时,最需要注意什么?快速入门中的 Webhook 示例使用了 auth='none',这种设置仅适用于本地开发。在对外公开端点之前,必须先配置好带身份验证的 Webhook。另外,当外部操作被中断且结果不明确时,WOML 会将其标记为模糊状态,并要求手动对账,而不会静默重试。
这东西适合谁用?又能在哪里运行?它面向需要构建后端自动化、数据管道或 AI 智能体,并希望工作流可在 Git 中审查的开发者。CLI 可运行于受支持的 macOS、Linux 和 Windows 系统(Linux 需要 glibc 2.31+),既可以在本地运行,也可以部署在你自己控制的基础设施上。
我究竟能用 WOML 做什么?自动化工作流(订单处理、入职引导、审批)、后端应用(Webhook、定时任务、事件驱动服务)、AI 智能体、数据管道,以及部署检查和事件响应等基础设施系统。
像 Claude Code 这样的 AI 编程智能体能帮我写 WOML 文件吗?可以。有一个专门的 WOML Skill,它会教智能体语言结构、运行时绑定和验证流程,让它们能够生成有效的 .woml 文件。可以为 Claude Code 安装,也可以通过 Agent Skills 约定用于 Codex 及类似客户端。
VS Code 扩展提供了哪些功能?它为 .woml 文件提供类 HTML 标记高亮、嵌入式 JavaScript 语法高亮、运行时绑定(context、services)高亮、引用表达式高亮和代码片段,并会跟随你现有的 VS Code 主题。
WOML 如何处理失败和部分进度?运行时会在重启之间保留持久化的执行状态(尝试次数、决策、等待和结果),支持使用稳定的幂等操作标识进行重试,为共享资源提供带 fencing token 的锁和租约,并为基础设施部分成功的情况提供明确的补偿和清理步骤。
大小
15.3 MB
星标
174
时长
1年
提交 · 90 天