xeito-machine
Write or change a Xeito machine, the versioned statechart that runs a task on gen_statem (use Xeito.Machine). Use when adding a machine or a state, transition, guard, action, effect, timeout or typed decision to one, when delegating to another machine, when routing requests to a machine, or when deciding whether a change needs a new machine version.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- xeito-machine
- description
- Write or change a Xeito machine, the versioned statechart that runs a task on gen_statem (use Xeito.Machine). Use when adding a machine or a state, transition, guard, action, effect, timeout or typed decision to one, when delegating to another machine, when routing requests to a machine, or when deciding whether a change needs a new machine version.
03 SKILL.md 正文
Xeito machines
A machine is the only place control flow lives: models never decide what happens next on their own, they only answer typed decisions that a state asks for. The design is in docs/architecture/02-state-machine-core.md; the DSL is documented in lib/xeito/machine.ex. Read lib/xeito/machines/run_tests.ex (the smallest machine) and lib/xeito/machines/fix_failing_test.ex (decisions, nested states, delegation, a human step) before writing one.
The shape of a machine
defmodule Xeito.Machines.Example do
use Xeito.Machine, version: "0.1.0"
alias Xeito.Effect
initial :running
state :running, entry: :run_check, timeout: 600_000 do
on :ran, to: :done, guard: :passed?
on :ran, to: :failed, action: :record_failure
end
final :done
final :failed
@doc false
def run_check(ctx), do: [Effect.bash(ctx.cmd, cwd: ctx.cwd)]
@doc false
def passed?(_ctx, result), do: result.exit_status == 0
@doc false
def record_failure(ctx, result), do: Map.put(ctx, :output, result.output)
end
- Entry functions return effects (
Xeito.Effect:bash,read,write,edit,chat,machine,decide); they never perform them. The runner executes them, and each result comes back as an event::ranforbash,:child_doneformachine,{:decided, value}for a decision (the table is inlib/xeito/effect.ex). This is what makes runs replayable from the log and sandboxable. - Guards (
fun(ctx, data) :: boolean) must be pure. The first transition whose event matches and whose guard passes is taken, the innermost state's first, in the order written: put the guarded ones first and an unguarded fallback last. - Actions (
fun(ctx, data) :: ctx) are pure context updates. Anything with a side effect is an effect of the next state's entry. - Guards, entries and actions are named public functions, so the definition stays plain data (exportable as Mermaid or SCXML with
mix xeito.export). Mark them@doc false. - Nested states:
state :working, initial: :planning do … endwith child states inside.
What the compiler enforces (lib/xeito/machine/validator.ex)
- Every non-final state has a timeout:
timeout: msor{ms, event}, else the machine's default (5 minutes). An unhandled timeout ends the run in the mandatoryfinal :failed. - From every state a final state is reachable.
- A state with
decide Typehandles every value of the type and{:decided, :abstain}. Abstention is a value, not an error: route it somewhere sensible, usually a human.
Decisions instead of model text
When a step needs judgement (is this test flaky, is this command safe), declare a typed decision in the state rather than parsing model output:
state :triage do
decide(Xeito.Decisions.Triage, input: :triage_input)
on {:decided, :flaky}, to: :rerun
on {:decided, :code_bug}, to: :working, action: :record_triage
on {:decided, :abstain}, to: :ask_human
end
A new decision type is a module under lib/xeito/decisions/ (see lib/xeito/decision.ex and docs/architecture/03-typed-decisions.md): closed values with descriptions, rules first, labelled examples in priv/decisions/<type>/examples.jsonl, evaluated with mix xeito.eval before it decides anything.
Delegation and humans
- Delegate to another machine with
Effect.machine(Module, input, timeout: ms). The child runs as its own logged run; the parent gets only its outcome in the:child_doneevent. - A human step is a state waiting for a human event (
:approved,:denied,:answered, or a text answer), with a long timeout: the session relays them (/approve,/deny, or text).
Versions
A run pins its machine's version, and recovery refuses to replay a run under a different version. Bump the version whenever a run logged with the old code would replay differently: new or renamed states or events, changed transitions or guards, entries that return different effects. A pure refactor that keeps every step the same keeps the version. mix xeito.log verify checks that logged runs still replay exactly.
Registering and routing
A machine that users can start is registered in lib/xeito/session/router.ex: the registry (name, module, what it does, how requests reach it), and a routing rule from the Intent value and the message if requests should reach it without /machine <name>.
Testing
Work test-first, at three levels:
- Guards and actions as plain functions on contexts, without a model (as in
test/xeito/machines/chat_test.exs). - Steps with
Xeito.Machine.Engine.handle(Xeito.Machine.fetch!(Module), state, ctx, event, data), which returns the next state, context and effects without running anything. - Runs with a scripted runner (
scripted_runner/2intest/support/xeito_case.ex; examples intest/xeito/run_test.exs); sessions and routing with the scripted model intest/xeito/harness_test.exs.
test/xeito/architecture_test.exs fails if a machine, or the engine, calls IO, processes, configuration or the runner side directly: return an effect instead.
A machine whose guards decide something that matters (limits, safety, when to stop) belongs in test/mutate.exs, by itself or one # --- section ---; see the xeito-quality-gate skill.
04 同仓库更多 Skills
web-search
Search the web and extract the content of the result pages.
video-transcript
Fetch the transcript of a YouTube video for summarization and analysis.
translate-text
Translate text between languages, keeping formatting and terminology.
screenshot-ui
Take screenshots of a web app's pages in a browser to check the layout.
release-notes
Draft release notes from the commits since the last tag.
pdf-extract
Extract text and tables from PDF files.