创作协议 · Session自动生成

简述

一个运行中的会话通过 JSON lines 回答请求：每行一个 JSON 对象，带 op 和可选的 id；每个请求得到一行 {"id", "ok": …} 或 {"id", "error": {…}}。entelechy serve <scene.esn> 在 stdin/stdout 上提供它，--listen <host:port> 同时提供 TCP 与 WebSocket；Player 用 --serve 从窗口提供同一协议。概念与用法见手册 · Agent 协议。

方法

op	属性	简述
compose	`text`?, `edits`?, `expect`?, `path`?, `documents`?	修改场景：校验通过后改写磁盘上的文档；被拒绝时什么都不写。
document	`version`?, `path`?	读取场景文档（或场景中其他文档）的文本与版本。
evaluate	`nodes`?, `settle`?, `measure`?, `clock`?, `time`?, `rate`? …	运行一帧。
graph	—	读取正在运行的场景结构：输入、参数、节点、输出。
help	`name`?	各层的语法与 API：全部，或某个名字的完整说明。
history	`since`?	查看是什么改变了世界，以及哪些尝试被拒绝。
kernel	`kernel`?, `generation`?	读取一个 Kernel 的清单（manifest）与源码。
kernels	—	列出所有已发布的 Kernel 及其代数（generation）。
param	`name`, `value`	设置场景声明的参数。
pause	`paused`?, `step`?	暂停、继续或单步推进窗口中的场景时间（对应窗口里的 F8、F9、F7）。
pin	`node`	让一个节点保持物化，使 read 能看到它。
prepare	`source`	编译一个 Kernel 并报告问题，但不发布。
publish	`source`, `expect`?	编译、校验、准备一个 Kernel，然后整体原子替换；只改变运行中的世界，不改文件。
quit	—	结束连接；在标准输入模式下结束进程。
read	`output`?, `node`?, `port`?, `format`?, `from`?, `count`?	读取一个输出或某个节点的端口。
reset	`node`?, `port`?	清除已提交状态，<~ 读取者从初始来源重新开始。
restore	`snapshot`?, `from`?, `laws`, `structure`?, `time`?, `rate`? …	恢复一个快照的世界（先做一次不提交的试运行帧）。
retire	`kernel`?	移除一个已发布的 Kernel。
snapshot	`to`?	整个世界的快照：Kernel、场景与所有已提交状态。
status	—	会话概况：后端、场景、已发布 Kernel、节点数、修订号、内存等。
sync	—	重新读取所有发生变化的文档。
trace	`node`, `at`?, `element`?, `time`?, `rate`?, `queued`? …	运行某个节点 Kernel 的一个元素，并展示每一步。
unpin	`node`	取消 pin，让融合优化重新接管该节点。
write	`node`, `port`?, `data`, `format`?	替换某个节点已提交的状态。

信号（事件）

会话与文件系统同步时观察到的事情，以 {"kind": …} 对象出现在 compose、sync、param 等应答的 events 中。

kind	字段	说明
`preparing`	`{ path: PathBuf, id: KernelId }`	A changed Kernel compiled and is being prepared; the running version stays until a later sync publishes the replacement.
`published`	`{ path: PathBuf, id: KernelId, generation: Generation }`	A Kernel was compiled and published.
`rejected`	`{ path: PathBuf, error: Diagnostic }`	A changed Kernel was refused; the previous version stays.
`retired`	`{ path: PathBuf, id: KernelId }`	A Kernel disappeared from its document.
`scene_loaded`	—	The scene document was re-read and its graph rebuilt.
`text`	`{ name: String, chars: usize }`	An input’s text was written into the Host as rows of character codes.
`loaded`	`{ name: String, path: PathBuf, detail: String }`	An input’s file was read into the Host.
`scene_rejected`	`(Diagnostic)`	The changed scene document was refused; the previous graph stays.
`absent`	`{ name: String, path: PathBuf }`	An input’s file is absent; the input reads its fallback.
`wrote`	`{ output: String, path: PathBuf, bytes: usize }`	An output was written to its file after a committed evaluation.
`removed`	`{ output: String, path: PathBuf }`	A file was removed by an output’s operations.
`renamed`	`{ output: String, from: PathBuf, to: PathBuf }`	A file was renamed by an output’s operations.
`write_refused`	`{ output: String, path: PathBuf, why: String }`	An output’s write was refused; said once until the reason changes or a write succeeds.
`routed`	`{ node: String, backend: &'static str, why: String }`	A node runs off the session’s main backend, and why. Said once per placement change.
`large`	`{ path: PathBuf, id: KernelId, why: String }`	A Kernel just published is large (`large`): what it carries through its branches, the structs and the functions that carry most. Said for each version published so.
`unrun`	`{ node: String, why: String }`	A node with no `domain` whose Kernel compares its element with its first input’s count, so the elements past that count, which the test is for, are never run ([`check::defaulted_domain`]). Said once when the scene loads, and again when it changes.
`brought_unchanged`	`{ output: String, path: PathBuf, bytes: usize, frames: u32 }`	A large output written to a file was brought to the Host as a new Field on each of `frames` evaluations in a row and found each time to be the file as it stands: the node it reads runs every time and makes the same, and each time costs the Field fetched, encoded and hashed. Said once, until the output is written or left as it was.
`idle`	`{ path: PathBuf, ids: Vec<KernelId> }`	Kernels a document of the scene publishes and no node uses, each compiled and prepared all the same. Said when the scene loads, and again when they change.

信封字段

名称	位置	说明
`column`	error	Where on that line, from 1.
`error`	answer	Why the request was refused, and what acts on it as data; the world is as it was.
`expected`	error	The type that field is.
`field`	error	The field at fault.
`fields`	error	The fields the operation takes.
`fix`	error	The change that mends the fault, when one does: an item of `compose`’s `documents` that takes its document’s place, handed back as it is; `path` with `text`, the refused change’s own document with a `use` item added, or with `edits` adding it to the document on disk. A `rejected` event carries it too.
`frame`	error	The frame a run failed at, counted from its first.
`id`	request	Anything; the answer carries it back as it was sent, to pair them.
`id`	answer	The request’s `id`, or null when it sent none or was not JSON.
`line`	error	Where the fault is, from 1: in the text the request carried, or in `path`.
`message`	error	Why, one or more sentences for a person or an agent to read.
`migration`	error	The Kernel that failed to migrate that state.
`node`	error	The node an evaluation failed at.
`ok`	answer	What the operation answered, as its entry in the protocol section says.
`op`	request	The operation: one of the protocol section’s, each with its own fields.
`operations`	error	Every operation, for an unknown one.
`path`	error	The scene document a refused compose would have written, or the document a failed element’s operation is written in.
`port`	error	The state port whose migration failed.
`similar`	error	The names nearest an unknown one.
`text`	error	The document an `edits` compose made, which `line` counts in.
`version`	error	The scene document’s version as it stands, for a compose refused.
`written`	error	Whether a compose wrote its document: false when refused.

传输通道

名称	打开方式	说明
`socket`	`entelechy serve <scene.esn> --listen <host:port>`	The same lines over each TCP connection to the address; `quit` ends the connection.
`stdin`	`entelechy serve <scene.esn>`	Request lines on standard input, answer lines on standard output; `quit` ends the process.
`websocket`	`entelechy serve <scene.esn> --listen <host:port>`	The same lines as WebSocket text messages to the same address, one request a message.