@marimo-team/smart-cells：marimo 智能单元格（Markdown/SQL）与 Python 代码双向转换的纯解析库

@marimo-team/smart-cells：marimo 智能单元格（Markdown/SQL）与 Python 代码双向转换的纯解析库

【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo

导读

marimo 的核心体验之一，是让 Markdown 单元格与 SQL 单元格以"智能单元格（smart cell）"的形式存在——用户在编辑器中直接书写 Markdown 或 SQL，底层却以mo.md(...)、mo.sql(...)这类纯 Python 代码持久化与执行。@marimo-team/smart-cells正是负责这两种语言与 Python 代码互转的纯解析库：它不依赖 React 或 CodeMirror 运行时，只做"解析 Python → 抽取目标语言内容"和"目标语言内容 → 回写 Python"这两件事，并在此过程中完整保留引号前缀、变量名、引擎、输出开关等元数据。读完本文，你将掌握该库的核心接口契约、Markdown/SQL 两个解析器的双向转换原理、字符串与引号处理细节，以及它在 marimo 前端编辑器中的真实挂载位置。

一、为什么需要 smart-cells：智能单元格的"外挂语言"机制

在 marimo 中，一个单元格的源码始终是 Python：Markdown 内容写进mo.md(...)，SQL 查询写进mo.sql(...)。但对用户而言，直接编辑 Markdown 或 SQL 文本远比编辑带引号包裹的 Python 字符串更自然。smart-cells 要解决的问题就是：编辑器中展示的目标语言内容 ↔ 磁盘上持久化的 Python 代码之间的无损双向转换。

为此，该库定义了"解析器"这一抽象，并在 package.json 中以@marimo-team/smart-cells为包名发布，版本 0.1.0，描述为 "Pure parsing library for marimo smart cells (markdown, SQL, etc.)"。它的关键工程约束体现在三处：

• 纯解析、零副作用："sideEffects": false，可在任意 JS 环境中安全引用；
• 无框架依赖：接口层不引入 React / CodeMirror，仅依赖@lezer/python（Python 语法树）、@codemirror/lang-python（markdown 校验复用其 Python 语法）与string-dedent（缩进归一化）；
• 零构建步骤："build": "echo 'No build step'"，源码即产物（"main": "src/index.ts"），配合vitest与tsgo分别承担测试与类型检查。

二、核心接口契约：LanguageParser 与元数据往返

所有解析器都实现同一个框架无关的接口LanguageParser<TMetadata>，定义在 types.ts：

interface LanguageParser<TMetadata = Record<string, unknown>> { readonly type: string; // 解析器唯一标识，如 "markdown" / "sql" / "python" readonly defaultCode: string; // 该语言的默认 Python 代码模板 readonly defaultMetadata: Readonly<TMetadata>; transformIn(pythonCode: string): ParseResult<TMetadata>; // Python → 目标语言 transformOut(code: string, metadata: TMetadata): FormatResult; // 目标语言 → Python isSupported(pythonCode: string): boolean; // 当前 Python 代码是否可识别 }

两个方向的数据结构同样在 types.ts 定义：

• ParseResult：包含提取出的目标语言代码code、该代码在原始 Python 字符串中的字符偏移量offset（供编辑器精确定位光标），以及解析过程中收集的metadata；
• FormatResult：包含回写好的 Python 代码code，以及目标语言内容在其中的起始偏移offset。

metadata是双向转换的"记忆"：transformOut拿到的是之前transformIn产出的元数据，因此引号前缀、SQL 引擎、dataframe 变量名等信息可以在编辑往返中被完整保留，不会在保存时悄悄丢失。

接口中还定义了 Python 字符串的引号前缀枚举（types.ts）：

export const QUOTE_PREFIX_KINDS = ["", "f", "r", "fr", "rf"] as const; export type QuotePrefixKind = (typeof QUOTE_PREFIX_KINDS)[number]; export type QuoteType = '"' | "'" | '"""' | "'''";

QuotePrefixKind覆盖了空前缀（普通字符串）、f-string、raw string 以及组合形式fr/rf；QuoteType则区分单引号、双引号与三引号。这八种前缀 × 四种引号形态的组合，正是 Markdown 与 SQL 解析器需要逐一匹配的字符串形态。

三、MarkdownParser：mo.md(...)与纯 Markdown 互转

MarkdownParser（markdown-parser.ts）负责mo.md(r"""# Hello""")这类 Python 调用与纯 Markdown 文本之间的转换，其type为"markdown"，默认代码为mo.md(r"""\n""")，默认元数据使用r前缀（raw string，避免 Markdown 中的反斜杠被 Python 转义）。

3.1 Python → Markdown（transformIn）

transformIn先对输入做trim()，然后按顺序尝试所有"前缀 + 引号"组合构建的正则（见 markdown-parser.ts），每个正则匹配形如mo.md(\s*<prefix><quote>...</quote>\s*)的整行调用。命中后：

1. 用splitQuotePrefix从起始引号中分离出前缀（如rf"""→rf+"""）写入metadata.quotePrefix；
2. 调用unescapeQuotes还原字符串内被转义的引号；
3. 借助string-dedent去除多行字符串的公共缩进（dedent 要求首尾行为空行，因此先用\n补齐再.trim()）；
4. 通过pythonCode.indexOf(innerCode)计算内容在原文中的偏移量offset。

值得注意的一个细节：f-string 内的复杂表达式也能被正确抽取。测试用例（markdown-parser.test.ts）验证了mo.md(f"""# Count: {",".join(data["items"])}""")这类"表达式里再嵌引号"的写法，抽取后仍能还原为# Count: {",".join(data["items"])}。这得益于外层用三引号 +s标志（dotAll）的正则匹配，以及 dedent 对整体块的统一处理。

若所有正则都不命中（例如内容根本不是mo.md(...)调用），transformIn会原样返回输入，offset为 0——这是一种安全的降级策略。

3.2 Markdown → Python（transformOut）

transformOut总是用三引号回写，并特意处理了引号转义问题（markdown-parser.ts）：

const escapedCode = code.replaceAll('""', String.raw`"\"`); const start = `mo.md(${quotePrefix}"""\n`; const end = `\n""")`; return { code: start + escapedCode + end, offset: start.length + 1 };

注释解释了这里的精妙之处：只转义连续两个双引号而非全部双引号，因为四个连续引号会提前终止字符串；且转义的是第二个引号，避免反斜杠紧贴首引号造成转义失效。回写后的起始偏移为start.length + 1，即三引号后内容的第一行位置。源码中明确标注此逻辑须与 Python 端 marimo/_convert/utils.py 的markdown_to_marimo保持行为一致（NB. Must be kept consistent），这保证了前端编辑与 Python 转换器两个入口产出的代码完全兼容。

3.3 isSupported：基于 Lezer 语法树的严格校验

与 SQL 解析器不同，isSupported并不只是字符串匹配，而是用@codemirror/lang-python的语法树对mo.md(...)的调用签名做逐节点精确比对（markdown-parser.ts）：要求 AST 依次为Script → ExpressionStatement → CallExpression → MemberExpression( VariableName . PropertyName ) → ArgList → ( → String|FormatString → )的严格序列。这意味着：

• mo.md()（空调用）与空字符串被显式视为支持；
• 非mo.md(开头的代码直接判定不支持；
• 只要调用形态多出任何节点（例如存在多个调用、参数不是字符串、传入关键字参数），isSupported即返回false，调用方就会回退到普通 Python 单元格，从而避免误把普通代码当作 Markdown 处理。

四、SQLParser：mo.sql(...)与纯 SQL 互转

SQLParser（sql-parser.ts）是三个解析器中元数据最丰富的一个，其SQLMetadata结构如下：

interface SQLMetadata { dataframeName: string; // 结果绑定的变量名，默认 "_df" quotePrefix: QuotePrefixKind; // 引号前缀，默认 "f"（SQL 可内嵌 {变量} 参数化） commentLines: readonly string[]; // 单元格顶部的 # 注释行，原样保留 showOutput: boolean; // 是否显示输出，默认 true engine: string; // SQL 引擎，默认 "__marimo_duckdb" }

默认代码模板为_df = mo.sql(f"""SELECT * FROM """)，并提供了静态工厂fromQuery(query)快速生成带缩进的 SQL 单元格。

4.1 Python → SQL（transformIn）：基于 @lezer/python 的 AST 解析

transformIn的流程（sql-parser.ts）：

1. 先通过extractCommentLines收集单元格顶部的#注释行——它们是 SQL 单元格的"文档前缀"，会在回写时放回原处；
2. 调用isSupported快速过滤：必须包含且只能包含一次mo.sql调用；
3. 交由parseSQLStatement（sql-parser.ts）做真正的 AST 解析。

parseSQLStatement用@lezer/python将代码解析为语法树后，用TreeCursor遍历：先查找赋值语句AssignStatement，读取左侧VariableName得到dataframeName；再定位右侧的CallExpression，确认成员表达式文本精确等于mo.sql；随后进入ArgList节点，借助 python-ast.ts 的parseArgsKwargs分离位置参数与关键字参数。

值得强调的两处严谨性设计：

• 拒绝条件表达式包裹：如果右值是ConditionalExpression、BinaryExpression或UnaryExpression（例如x = mo.sql(...) if cond else ...），直接返回null，不会误判为 SQL 单元格（源码注释引用 issue #7386）；
• 赋值语句之后不允许有多余代码：code.slice(assignStmt.to).trim().length > 0即拒绝，保证单元格是"纯粹的 SQL 赋值"。

关键字参数解析（sql-parser.ts）支持engine=...与output=True/False：engine原样记录字符串值，output按"True"字面量解析为布尔值。SQL 字符串内容则通过getStringContent抽取，并交给safeDedent归一化缩进。最终transformIn返回去缩进的纯 SQL 文本、起始偏移与完整元数据。

4.2 SQL → Python（transformOut）：还原完整调用签名

transformOut（sql-parser.ts）依据元数据重建 Python 代码，其中参数化输出逻辑很典型：

const start = `${dataframeName} = mo.sql(\n ${quotePrefix}"""\n`; const escapedCode = code.replaceAll('"""', String.raw`\"""`); const showOutputParam = showOutput ? "" : ",\n output=False"; const engineParam = engine === DEFAULT_ENGINE ? "" : `,\n engine=${engine}`; const end = `\n """${showOutputParam}${engineParam}\n)`; return { code: [...commentLines, start].join("\n") + indentOneTab(escapedCode) + end, offset: start.length + 1, };

从中可以提取出参数化的两条关键规则：

• 仅当偏离默认值时才写参数：showOutput为false时追加output=False；engine不等于默认的__marimo_duckdb时才追加engine=...。这保证了生成的 Python 代码最小化、可读性强；
• SQL 内容整体缩进一个 Tab（4 空格），由indentOneTab（sql-parser.ts）实现，与mo.sql(后的"""对齐。

4.3 处理边界

SQL 解析器同样包含稳健的降级路径：空字符串直接返回；isSupported失败时原样返回输入并携带已提取的注释元数据。此外，transformIn在 AST 解析异常时通过try/catch捕获并console.warn，返回null走降级分支，不会让编辑器崩溃。

五、PythonParser：恒等变换的"默认语言"

PythonParser（python-parser.ts）实现了一个平凡的但重要的语义：Python 单元格不需要任何转换。它的transformIn/transformOut都是直通（pass-through），offset恒为 0，isSupported恒返回true。它的价值在于让编辑器可以用同一套LanguageParser接口统一调度三种语言——Markdown、SQL、Python——而不必为普通 Python 单元格写特例逻辑。

六、字符串与缩进的工具层

包内utils目录提供了四个被解析器复用的基础工具：

其中getPrefixLength（python-ast.ts）是偏移计算的关键：rf"""为 5、f"""/r"""为 4、普通三引号为 3、rf"/fr"为 3、f"/r"为 2、单引号为 1，与getStringContent的切片长度严格对应，保证抽取内容与偏移量始终一致。

七、测试验证：双向往返的强约束

该包配有四个 vitest 测试套件（__tests__），对转换正确性做了系统验证：

• markdown-parser.test.ts（222 行）：覆盖三引号、单引号、f-string（含嵌套引号、方括号下标、方法调用）、r-string（如 LaTeX$\nu = ...$保留反斜杠）、rf组合前缀、引号反转义等场景，逐条断言抽取内容与offset；
• sql-parser.test.ts：验证 SQL 抽取、engine/output参数回写、注释行保留与默认值省略规则；
• python-parser.test.ts：验证恒等变换；
• python-ast.test.ts：验证 AST 参数解析工具的正确性。

测试运行方式为包内pnpm test（vitest），类型检查为pnpm typecheck（tsgo）。

八、在 marimo 前端中的实际应用

smart-cells 并不是孤立存在的库，它在 marimo 前端编辑器中被多处直接引用：

• frontend/src/core/codemirror/language/languages/markdown.ts：编辑器持有new MarkdownParser()实例，并在创建 Markdown 单元格时调用静态方法MarkdownParser.fromMarkdown(markdown)生成初始 Python 代码；
• frontend/src/core/codemirror/language/languages/sql/sql.ts：导入SQLParser与SQLMetadata类型，驱动 SQL 单元格的编辑体验；
• frontend/src/core/cells/readonly-code-display.ts、frontend/src/core/codemirror/language/panel/panel.tsx 与 panel/markdown.tsx：在只读展示与语言面板中复用解析能力；
• frontend/src/components/dependency-graph/utils/cell-preview.ts：依赖图中预览单元格内容时同样依赖该包。

这印证了该库"单一职责、多处复用"的定位：编辑器内的语言切换、单元格创建、依赖图预览等场景共享同一份解析逻辑，保证任何入口产出的 Python 代码格式一致。由于仓库中frontend通过 workspace 依赖引用该包（见 frontend/package.json），修改smart-cells源码后无需构建即可被前端直接消费，这也是package.json中刻意省略构建步骤的原因。

九、总结

@marimo-team/smart-cells以约十个源文件、四个工具模块和四个测试套件，完整实现了 marimo 智能单元格的"Python ↔ 目标语言"双向转换能力：

• 统一的LanguageParser接口让 Markdown、SQL、Python 三种语言共享同一套转换调度与元数据往返机制；
• transformIn/transformOut的对称设计配合offset偏移量，兼顾代码正确性与编辑器光标定位；
• 丰富的SQLMetadata元数据（变量名、引擎、输出开关、注释行、引号前缀）保证 SQL 单元格的参数化设置不会在往返中丢失；
• 基于 @lezer/python 的 AST 级校验严格区分"可识别的智能单元格"与"普通 Python 代码"，宁可降级也绝不误判。

对于需要扩展 marimo 编辑器语言能力（例如新增一种智能单元格类型）的开发者而言，实现一个LanguageParser子类、注册到前端语言面板即可复用整套机制；对于只使用 marimo 的用户而言，理解这个库有助于弄清mo.md(...)与mo.sql(...)在编辑体验与持久化格式之间的映射关系，从而更自信地手写或迁移这类单元格。

【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo