校对:soup
基于 YAML 的 MathTS 科学笔记本的无头运行时间 .mtsw 格式。 装入工作簿,按依赖顺序运行其单元格,并核实结果——都来自终端或程序.
范围: 这是无头的v1——一个CLI和运行时间. 代码单元格评价 MathTS 表达式 (通过沙盒表达式引擎),而不是任意的TypeScript. 桌面图形界面是一个单独的,后期的工程,基于这个运行时间.
安装
npm install @danielsimonjr/mathts-workbook
国 际
# Run a workbook: executes cells in dependency order and prints per-cell results.
# Exits non-zero if any cell errors or any test assertion fails.
mtsw run example.mtsw
mtsw run example.mtsw -v # also print the execution event stream
mtsw run example.mtsw --json # machine-readable envelope on stdout
mtsw run example.mtsw -c gauss # run one cell + its transitive deps (stateless)
mtsw run example.mtsw --timeout 5000 # run in a worker; killed (exit 1) if it exceeds 5s
mtsw run example.mtsw --expect-hash <sha256> # refuse unless file SHA-256 matches
# Describe the structured document model (cells, outputs, dependency graph).
mtsw describe example.mtsw --json
# Validate structure: ids, dependency references, and cycles.
mtsw validate example.mtsw [--json]
# Print the dependency graph (human only; use `describe --json` for structured data).
mtsw graph example.mtsw # text adjacency
mtsw graph example.mtsw -f mermaid # Mermaid `graph TD`
mtsw graph example.mtsw -f dot # Graphviz `digraph deps { ... }`
# Engine introspection (for tooling / GUIs).
mtsw capabilities --json # version, supported cell types, feature flags
mtsw templates --json # available `new` templates
# Scaffold a new workbook (<name>.mtsw) from a template.
mtsw new my-notebook # basic template; refuses to overwrite
mtsw new my-notebook -t basic --force # overwrite an existing file
# Strip cell outputs (for git): prints to stdout, or -w to rewrite in place.
mtsw strip example.mtsw
mtsw strip example.mtsw -w
# Run and persist outputs back into the file (opt-in; never writes without --write).
mtsw run example.mtsw --write
# Edit cells (atomic, in-place; --json returns the updated doc, --dry-run previews).
mtsw cell add example.mtsw --type code --id gauss --content "n*(n+1)/2" --depends-on n
mtsw cell add example.mtsw --type code --id big --content-file body.txt # or - for stdin
mtsw cell edit example.mtsw gauss --content "n*(n-1)/2"
mtsw cell move example.mtsw gauss --before n # --before/--after <id> | --at <index>
mtsw cell rename example.mtsw n count # rewrites dependents' depends_on
mtsw cell rm example.mtsw n # refuses if cells depend on it
mtsw cell rm example.mtsw n --force # removes + detaches dependents
# Introspection + metadata.
mtsw functions --json # functions/constants cells can call (autocomplete)
mtsw meta get example.mtsw # show workbook metadata
mtsw meta set example.mtsw --title "My Notebook" --author Ada --tags physics,demo
# Scaffold a workbook (templates: basic | empty | chart; -o writes to any path).
mtsw new notebook # notebook.mtsw in the CWD (basic template)
mtsw new draft --empty -o docs/draft.mtsw # blank workbook at an explicit path
mtsw new demo -t chart # a line-chart example workbook
# Build a whole .mtsw from a JSON/YAML document (the inverse of `describe --json`).
echo '{"cells":[{"id":"a","type":"code","content":"6 * 7"}]}' | mtsw import -o out.mtsw
mtsw import doc.json --json # validates (ids/deps/cycles); stdout if no -o
# Render to a self-contained HTML document (runs first, then renders).
mtsw export example.mtsw -o example.html # one offline file; stdout if no -o
mtsw export example.mtsw --no-run # render cached outputs without executing
mtsw export example.mtsw --format tex --fragment -o body.tex # TeX body only (no preamble)
mtsw export example.mtsw --json # envelope: { data: { path, bytes } }
# Other export formats: --format tex|pdf|json|ipynb (html is the default).
mtsw export example.mtsw --format ipynb -o example.ipynb # Jupyter notebook (nbformat v4)
# Persistent session for a GUI/tooling: JSON-RPC 2.0 over stdio (NDJSON).
mtsw serve
# then JSON-RPC method "open" with params.path — the CLI ignores a file operand
# -> {"jsonrpc":"2.0","id":1,"method":"open","params":{"path":"example.mtsw"}}
# <- {"jsonrpc":"2.0","id":1,"result":{...describe doc...}}
# -> {"jsonrpc":"2.0","id":2,"method":"run"} # streams cell/event notifications
# methods: open/describe/validate/graph/run/cell.*/meta.*/save/capabilities/functions/shutdown
export --format tex (编). 一样 RenderDoc teX 的 CLI 建筑
导出为 toTeX 从软件包条目(与 RenderDoc, (中文(简体) ), RenderCell, (中文(简体) ),
财务报告和审定财务报表 ToTexOptions) (中文(简体) ). 片段略去 LaTeX 序言——形状与
mtsw export … --format tex --fragment数字 :
import { toTeX } from '@danielsimonjr/mathts-workbook';
const body = toTeX(
{ title: 'Notes', cells: [{ type: 'markdown', content: 'Energy $E=mc^2$' }] },
{ fragment: true }
);
// → markdown cell text only; no \\documentclass
使用 buildDependencyGraph + 键 toDOT 当你需要Graphviz DOT而不是美人鱼时
(单位:千美元)mtsw graph -f dot) (中文(简体) ).
export (自装入HTML). mtsw export <file> --format html 制作一个
笔记本到单一离线 .html 与 无外部请求{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}被打倒的传教士,
作为 MathML 的等式类型 (由现代浏览器本土化而来——Chrimium ≥109,,
Firefox,Safari),有嵌入式输出的代码单元格,"✓/✗"测试徽章,并(截至
内置的 SVG 地块。 每个节点 .toMathML() 编号 : .toTex() 编号 : .toHTML()
财务报告和审定财务报表 mathMLDocument 来自 @danielsimonjr/mathts-expression; 工作手册
运行时间组装全 HTML 与 toHTML 编号 : toCSS 编号 : markdownToHtml 编号 : renderChart
(CLI使用的工作手册模块——不包括在工作手册包条目上,但
mathMLToSVG). 等式单元格包含MathTS表达式语法(如.
c = 1 / sqrt(eps0 * mu0)),而非生的 LaTeX;它们只显示,并通过
toMathML默认 export 首先运行工作簿( 使用 --no-run 缓存
产出); 整个运行失败,如依赖周期,响亮的失败,而不是
散发误导性文件.
export --format ipynb (Jupyter笔记本). 将同样的运行报告传送给
结构符合性 nbformat v4 请检查url=值 (帮助) JSON文件: markdown 单元格映射到
笔记本标记下单元格; 所有其他单元格类型(code, (中文(简体) ), equation, (中文(简体) ), test, (中文(简体) ), data, (中文(简体) ),
visualization地图到笔记本代码单元格,计算结果成为
execute_result 产出(data['text/plain']),错误成为 error 输出,
和一张图表成为 display_data 输出(内置SVG). 共享相同
运行时的输油管 --format html编号 :tex (包括 --no-run, (中文(简体) ), --json, (中文(简体) ),
-o) (中文(简体) ).
run --timeout <ms> (可杀死的工人行走). 默认情况下, 单元格执行运行
没有时间预算的正在处理中——离家出走的单元格(例如无限制的计算)挂起
过程. --timeout 在 a 中运行整个工作簿 worker_threads 工人和
超过预算时强制终止,退出1号
workbook execution exceeded <ms>ms and was terminated 消息; 终止杀死
所以它甚至会打断一个同步的 CPU的运行 它总是运行
整个工作手册到完成或结束,所以它与 -c编号 :-v。 。 。 .
在程序上,同样的原始是可用的 runWorkbookWithTimeout(source, { timeoutMs }) (掷出) WorkbookTimeoutError ; 单元格输出返回
格式化为字符串(通过 formatResult),因为引擎类实例(Complex,
基质,... ) postMessage。 。 。 .
serve (恒会. 一个长寿命的过程将工作簿保存在内存中,每个细胞结果缓存和一个 固态集(单位:千美元) cell.* 编辑标记该单元格及其过渡性依附者 stale,以及 a run 重新执行 仅限 分解的单元格(为其他单元格使用缓存输出)——递增的延迟赢得了图形用户界面的需求。 对请求的处理严格有序; run 溪流 cell/event 通知(在v1中,而不是在中跑中,该运行回复之前已取消)。 编辑保留在内存直至 save。每个进程为单一文件;同时撰写者为最后写成.
编辑笔记. 单元格编辑是保留有效性的:将生成重复/无效ID的操作,缺失的依赖,或 抚养周期 以字节表示。 编辑一个单元格以清除其持续输出(现为旧); --at N 是单元格的最后基于 0 的索引; --force 解析依赖( 清除其输出) 但不重写单元格 内容,因此仍然引用已删除的代号的依赖者将会在运行时出错。 同步编辑器是最后一个写成的 serve (最近一次接受) cell.* 操作胜出; 使用 save (见e/cn.4/sub.2/2003/l.31).
诊断和错误写成Stderr;结果(包括: --json)去stdout,因此退出代码可以独立于输出在脚本中使用.
机器合同(--json) (中文(简体) ). 每个 --json 命令在 stdout 上发出一个信封 :
{ schemaVersion: {major,minor}, command, ok, data, problems }。这个信封是
即使失败也会发射(并且是循环/大安全,所以它永远不会坠入
病理数据); 退出代码镜像 ok ,但工具/GUIs
改为 ok 并将缺少/无法解开的信封作为唯一的运输工具
错误。 兼容性规则: 忽略未知字段 major 匹配; 拒绝
(单位:千美元) major 错配. run --cell <id> 无国籍(它重算目标
每通电话中转道岔; run --cell --write 只坚持已执行
单元格)。 国家编辑和增量执行 mtsw serve (见
; 一发命令只使用此信封.
保存 / 来回旅行 . serializeWorkbook (和上面的写作命令)通过解析器绕行工作簿:结构保存准确,并持续 output 值(平面数字/字符串/阵列/对象;平面形状的异地类型)。 所有写作都是 原子 (temp文件+重命名). 请注意,任何写路径都是解析的,因此 放下 YAML 注释并重排序密钥 ——在原地重写国家技术服务小组保存是未来的增强.
程序化 API
import { parseWorkbook, createExecutor, formatResult } from '@danielsimonjr/mathts-workbook';
const content = `
version: "1.0"
metadata:
title: "My Workbook"
runtime:
engine: mathts
execution: reactive
cells:
- code: "n * (n + 1) / 2"
id: gaussSum
depends_on: [n]
- code: "10"
id: n
- test: "gaussSum == 55"
id: checkGauss
depends_on: [gaussSum]
`;
const result = parseWorkbook(content);
if (result.success && result.workbook) {
const report = await createExecutor(result.workbook).runReport();
for (const cell of report.cells) {
console.log(cell.id, cell.status, formatResult(cell.output));
}
console.log('ok:', report.ok);
}
runReport() 继续错误,返回结构化 RunResult (它从不向细胞衰竭投放,拒绝带有依赖周期的工作簿). 年长者 runAll() 仍然作为事件流 API 可用,它会丢入第一个单元格错误.
工作手册格式 (.mtsw)
version: '1.0'
metadata:
title: 'Example'
author: 'Your Name'
runtime:
engine: mathts
execution: reactive # reactive | sequential | manual
cells:
- markdown: |
# Introduction
id: intro
- code: '{ pi: 3.14159, e: 2.71828 }'
id: constants
- test: 'constants.pi > 3.14'
id: checkPi
depends_on: [constants]
每个单元格都是 YAML 映射 一个 类型密钥( e)code, (中文(简体) ), markdown, (中文(简体) ), data, (中文(简体) ), test,)其值为单元格内容,加:
id(需要)——必须是有效的标识符([A-Za-z_][A-Za-z0-9_]*); 编号是单元格如何被引用的.depends_on(可选)——此单元格所依赖的单元格标识列表.
依赖性和范围
一个依赖性的结果被注入到细胞的评价范围中,作为被依赖性的ID命名的变量. 要曝光多个值, 返回一个对象文字, 并读取属性访问 :
cells:
- code: '{ n: 2, m: 3 }'
id: pair
- code: 'pair.n + pair.m' # -> 5
id: total
depends_on: [pair]
范围是 仅直接( 非过渡): 单元格只查看其自己的单元格 depends_on而不是他们的依赖。 要使用中转值,请明确列出.
测试单元格
A 类 test 单元格表达式必须评估到 布尔数字 : true 通过, false 失败,非布尔结果被报告为出错(使用明确的比较). 测试失败使 mtsw run 退出非零——工作簿可以验证自己.
单元格类型 (v1)
| 类型 | 状态 | 说明 |
|---|---|---|
markdown | ✅ | 文件(通过逐字记录) |
code | ✅ | MathTS 表达式脚本; 最后一个值是结果 |
data | ✅ | 结构化 YAML, 解析( 硬化) 为值 |
test | ✅ | 布尔断言( A)true =通过) |
equation | ✅ | MathTS 表达式语法; 仅显示( 内容重复, 未评价) |
visualization | ✅ | 图表/视觉谱;只显示(内容重复,没有评价) |
tensor | ⏳ | 被推迟的 - 分析失败 : type 'tensor' is reserved but not yet supported (supported: code, markdown, data, test, equation, visualization) |
export | ⏳ | 与 tensor (单位:千美元)export 保留; 不在支持的列表中) |
执行模式
所有模式都按依赖顺序执行单元格( E)graph.executionOrder) (中文(简体) ). 唯一一个
运行时间差是 反应,该输出 cell:stale 受抚养人:
单元格被编辑或重新运行. 顺序 财务报告和审定财务报表 手动 使用相同的执行命令
(两者仍然运行完整图表) run 编号 : runReport) (中文(简体) ).
警卫
代码和测试单元格只通过 MathTS 沙盒表达式引擎执行 — no eval, (中文(简体) ), Function,或 vm. YAML(文件和 data-细胞有效载荷)被剖析出一个硬化了的核心-外观配置和原型-污染防护.
许可证
麻省理工学院