# @danielsimonjr/mathts-workbook 中文文档

规范地址：https://npmcn.com/package/%40danielsimonjr/mathts-workbook/

版本：0\.5\.17
npm 元数据更新时间：2026-11-11T10:03:39.971Z
中文译文更新时间：2026-11-11T10:51:28.332Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40danielsimonjr/mathts-workbook
原文对照：https://npmcn.com/package/%40danielsimonjr/mathts-workbook/?lang=original
项目主页：https://github.com/danielsimonjr/MathTS#readme
源码仓库：https://github.com/danielsimonjr/MathTS

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：185 kB，57 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-04-05T04:51:28.238Z
- 最新版本发布：2026-11-11T10:03:39.776Z
- 近 30 天下载量：3390（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

MathTS(.mtsw格式)的科学工作手册运行时间

## 安装

```sh
npm install @danielsimonjr/mathts-workbook
```

也可以使用：`pnpm add @danielsimonjr/mathts-workbook`、`yarn add @danielsimonjr/mathts-workbook`、`bun add @danielsimonjr/mathts-workbook`

## README

# 校对:soup

基于 YAML 的 MathTS 科学笔记本的无头运行时间 `.mtsw` 格式。 装入工作簿,按依赖顺序运行其单元格,并核实结果——都来自终端或程序.

> **范围:** 这是无头的v1——一个CLI和运行时间. 代码单元格评价 **MathTS 表达式** (通过沙盒表达式引擎),而不是任意的TypeScript. 桌面图形界面是一个单独的,后期的工程,基于这个运行时间.

## 安装

```bash
npm install @danielsimonjr/mathts-workbook
```

## 国 际

```bash
# 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`数字 :

```typescript
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

```typescript
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)

```yaml
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命名的变量. 要曝光多个值, 返回一个对象文字, 并读取属性访问 :

```yaml
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`\-细胞有效载荷)被剖析出一个硬化了的核心-外观配置和原型-污染防护.

## 许可证

麻省理工学院

## 常见问题

### @danielsimonjr/mathts-workbook 是什么？

MathTS\(\.mtsw格式\)的科学工作手册运行时间

### 如何安装 @danielsimonjr/mathts-workbook？

在项目目录运行 npm install @danielsimonjr/mathts-workbook，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mtsw，可以用 npx mtsw 直接运行。

### @danielsimonjr/mathts-workbook 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @danielsimonjr/mathts-workbook 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @danielsimonjr/mathts-workbook 可以商用吗？

@danielsimonjr/mathts-workbook 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @danielsimonjr/mathts-workbook 的下载量有多少？

根据 npm 官方下载统计，@danielsimonjr/mathts-workbook 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,390 次，日均约 113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @danielsimonjr/mathts-workbook 还在维护吗？

最新版本 0\.5\.17 发布于 2026/11/11（今天）；至今共发布 66 个版本，其中过去 12 个月发布了 66 个；首次发布于 2026/04/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。