marimo-lens

使用 marimo Lens

Lens 为实时笔记本添加可视化协作功能。它可以展示贯穿笔记本结果的 Trail，或将选定的表面与其来源、上下文和捕获的图像关联起来。当前代码模式集成负责检查、编辑和执行笔记本。

选择工作流

用户意图	操作
“添加 Lens”或“我看不到 Lens”	重用现有实例，或添加 Lens。
“带我了解这个笔记本”或“解释这些结果”	检查相关单元格并展示 Trail。
“修改这个”或“处理我的选中内容”	读取所选请求，验证结果并将其解决。

根据用户的请求选择工作流。即使没有选中内容，也可以用 Trail 进行一般性说明。存在选中内容并不意味着用户明确要求讲解时，就获得了编辑或解决这些内容的许可。

此核心技能包含完整的常规挂载和 Trail 工作流。仅当相关任务或例外情况适用时，才阅读参考资料。

在实时笔记本内核中，将此技能中的每个 Python 代码块作为一次调用运行。在终端中，此调用对应一次 marimo pair execute，并将代码块通过标准输入传入；打印的结果会出现在其 JSON stdout 中。 通过 marimo pair 运行 Lens介绍了目标选择、错误和并发。在编辑器的代码模式侧边栏中，每个代码块对应一次 execute_code 调用。对于同一环境和 Lens 安装，重用已加载的说明。

在聊天、活动、弹出框和摘要中，以同事的口吻交流。说明你做了什么或发现了什么，以及支持这些内容的证据。使用具体标签，并附上简短说明。进行只读导览时，描述已有发现。用户提出要求时，采用教学语气。

从用户要求的工作开始

在集成所需的首次调用之后（例如，针对 marimo pair 调用 help(cm)），将连接操作与第一个有用操作合并：对于添加请求，检查是否可用；对于 Trail，检查相关单元格和值；或者读取当前选中内容快照。单独调用并仅打印身份信息没有必要。

connect(ctx) 会重用已创建和自动挂载的实例。当一个可在浏览器中使用的 Lens 控制可见停靠栏时，即使上下文中包含其他 Lens 对象，它也会选择该 Lens。若工作需要跨多次调用，请保留其不透明身份。每次调用都会获得一个新的临时环境，因此后续调用中需要重新导入 cm 和 marimo_lens，重新获取上下文，并通过 identity= 选择同一个 Lens。

对于 lens_ambiguous，请检查 marimo_lens.agent.discover(ctx)，并选择与请求和可见表面相符的身份。如果这些线索无法区分实例，请询问用户。

缺少 Lens 时添加

在挂载调用期间检查是否可用。仅当 Lens 单元格或主机挂载仍在创建或渲染时，才重试不可用的连接。确认不存在 Lens 且没有待处理的挂载后，立即添加。

对于没有待处理挂载的普通笔记本，复用可用的 Lens，或排入一个单元格：

import marimo._code_mode as cm
import marimo_lens

async with cm.get_context() as ctx:
    available = marimo_lens.agent.discover(ctx)
    if available:
        print({"identities": [mounted.identity for mounted in available]})
    else:
        print({"cell_id": marimo_lens.agent.add_lens_cell(ctx)})

结束此次调用，让排入队列的单元格运行，并让浏览器渲染停靠栏。在新的调用中重新连接，并确认停靠栏已可用。若辅助工具发现之前添加的 Lens 单元格没有运行中的 Lens，就会复用该单元格并重新运行。采用自定义挂载策略的主机，会通过自己的集成挂载 Lens，具体请参阅设置。

例如，服务器重启后在新内核中重新打开的笔记本，可能会显示所有单元格均已过时。这些单元格都尚未运行，因此不存在 Lens，且之前内核中的选择也已丢失。代码模式调用仅通过 ctx.run_cell() 运行笔记本单元格。运行挂载 Lens 的单元格：导入 marimo 的单元格，或编写的 Lens 单元格。否则，请使用辅助工具。

如果用户只要求添加 Lens，请告知其已就绪，然后结束。若请求包含 Trail 或选择工作流，则继续执行。

使用 Trail 讲解笔记本

Trail 是附加到笔记本单元格上的有序讲解。每个步骤都会通过标签和消息展示相应结果。可将其用于介绍、演示和讲解，让用户能够就地查看依据。

复用对话中已核实的上下文。如果未知路径，请在一次调用中连接并检查 ctx.cells 的精简提纲：ID、名称、状态和首行代码。批量读取相关的关键单元格、错误，以及 ctx.globals 中所需的实时值。按笔记本中的顺序讲解问题、依据、主要结果和下一步。核实这些发现后，发送一个 Trail 并交还控制权。

使用 ctx.graph.cells 检查可执行图中的成员。图外的叙述性单元格可以为讲解提供参考，但不能作为展示目标。展示结果前，请核实其来源和值，并确认单元格处于空闲状态且没有相关错误。

检查结果后，选择一条简短路径。对于包含名为 inputs、analysis 和 summary 的单元格的笔记本，此完整调用会展示一个 Trail。请替换为实际单元格名称，并使用有笔记本数据支持的讲解：

import marimo._code_mode as cm
import marimo_lens

ctx = cm.get_context()
mounted = marimo_lens.agent.connect(ctx)
route = [
    ("inputs", "Inputs", "Start with the values used by this notebook."),
    ("analysis", "Calculation", "Follow how the inputs become a result."),
    ("summary", "Conclusion", "Review the result and what it supports."),
]
steps = []
for name, label, message in route:
    cell = ctx.cells[name]
    if cell.id not in ctx.graph.cells or cell.status != "idle" or cell.errors:
        raise RuntimeError(f"Verify {name} before revealing it")
    steps.append({"target": cell.id, "label": label, "message": message})
mounted.reveal(steps, duration_ms=None)

将讲解写入每个步骤的消息中，使用笔记本中的具体发现。reveal() 接受 1–16 个有序步骤，并返回 None。每个步骤都有一个目标、一个最长 40 个 UTF-16 单元的可选标签，以及一条最长 1,000 个 UTF-16 单元的可选消息。用户可以按自己的节奏浏览弹出层。展示路径后交还控制权。文本或数据演示不需要选择快照、PNG 捕获、解析或计时循环。仅在用户要求时才编辑或重新运行单元格。

Trail 是临时的。关闭、刷新、发生其他注意力事件，或引用的单元格及其上游输入发生变化，都会结束 Trail。有限的 duration_ms 会限制整个路径的时长，导航不会重置计时器。展示另一个 Trail 前，请核实变更后的结果。

处理选区

一次性读取打开的选区及其备注。选区位于 snapshot.references["selections"] 中，而 snapshot.current 很可能是 “这个”或“这里”所指的对象：

import json

import marimo._code_mode as cm
import marimo_lens

mounted = marimo_lens.agent.connect(cm.get_context())
snapshot = mounted.context()
print(
    json.dumps(
        {
            "identity": mounted.identity,
            "revision": snapshot.revision,
            "currentId": (snapshot.current or {}).get("id"),
            "selections": [
                {"id": s["id"], "label": s["label"], "note": s["note"]}
                for s in snapshot.references["selections"]
            ],
        },
        ensure_ascii=False,
    )
)

列表为空表示此 notebook 没有打开的选区。编辑器的 代码模式侧边栏只能访问自己的 notebook，因此请告知用户：其他 notebook 中的备注需要从对应 notebook 的侧边栏处理，或通过 marimo pair 处理。

要了解完整的生命周期，请参阅选区处理： 读取上下文、检查证据、开始处理、应用请求的更改、 验证、显示并解决。请遵守以下边界：

• 使用存储的 SelectionReference 及其捕获的修订版本作为 展示目标。生成它的单元格用于追溯来源和确定编辑位置。 DOM 目标可能由零个或多个单元格生成。
• 在对所选标记作出视觉判断之前，先检查捕获的图像。 根据最新的运行时和浏览器证据验证更改。如果无法检查图像，请说明 覆盖范围的限制。
• 在验证期间保持处理状态可见。显示操作会替换它。在同一次内核调用中， 使用相同的捕获修订版本先调用 reveal()，再调用 resolve()， 然后将控制权交还浏览器。
• 使用具体的结果和验证摘要来解决选区。对于模糊、受阻或未经验证的选区， 保持打开状态。如果发生修订版本冲突，请停止由你启动的处理，重新连接， 并重新评估最新上下文。
• Lens 属于单个 notebook 会话。如果已连接的 Lens 中没有用户所指的任何选区， 请按照其他 notebook 中的选区中 的说明检查其他 notebook。

$marimo-lens address 会处理所有打开的选区，包括每条备注及其证据。对于其他请求，用户的指示优先于较早的选区备注。即使选区列表为空，用户仍可请求概览或演示。

深入阅读

缺少软件包或 notebook 连接时，请参阅设置；创建可选中的 HTML 或 小组件时，请参阅目标编写；关于图像传输、 跨调用反馈和恢复，请参阅代码模式操作指南。

处理选区时，请在 notebook 内阅读相关参考文档：

import marimo_lens

print(
    marimo_lens.agent.skill()
    .file("references/selections.md")
    .read_text(encoding="utf-8")
)

使用 help(mounted) 或 help(mounted.reveal) 查看精确的操作约定。 文档索引 提供更多示例和 API 指南。请根据已安装的版本核对已发布的 API。