vignette-catalog-compose-notebook

在 vignette 目录中工作

目录由一个 catalog.toml 和若干自包含的 marimo 笔记本组成，既可作为完整示例，也可作为可导入的辅助模块。 将 <skill-dir> 解析为已安装的此技能，并直接执行其中的 Python 脚本，以应用其 uv shebang。 <skill-dir>/scripts/catalog-session.py 负责整个会话生命周期：确定性地启动、复用、检查、运行和停止目录内核，并且能在 shell 包装器中正常工作。 切勿通过临时使用 nohup 或后台运行来启动 marimo，也不要手动通过 pgrep、ss、curl 或 /api/sessions 重建会话状态。 如果辅助脚本失败，请先原样报告其输出，再尝试其他操作。

先判断请求类型

• 打开、运行或查看指定笔记本，或“让这个目录运行起来”：按下方快速路径操作，然后停止。 此路径下不要阅读笔记本约定、无关笔记本或数据参考。
• 更改已在运行的笔记本中的输入：通过 marimo-pair 代码模式复用其会话。 除非当前内核无法恢复，否则不要启动第二个内核。
• 编写新笔记本或回答数据问题：按编写工作流操作。
• 开放式研究：操作机制按编写工作流处理；研究方法由用户和代码库负责，而非此技能。

快速路径：打开指定笔记本

1. 阅读代码库的 AGENTS.md 和 catalog.toml。 阅读身份验证要求、已记录的浏览器访问方式，以及 [getting_started].first_notebook；跳过启动所不需要的注意事项和笔记本代码。

2. 选择面向用户的主机，然后运行一条命令；该命令会复用指定笔记本的健康会话，或启动新会话，确保单元格已运行，并打印结果：

   <skill-dir>/scripts/catalog-session.py open [--host <documented-address>] [notebooks/<name>.py]
   

   省略笔记本参数时，将打开 [getting_started].first_notebook。 进行交互式启动时，选择用户、系统或代码库所记录的访问路径，无需要求用户重复说明。 不要假定用户的浏览器运行在执行机器上。 对于直接访问，绑定到已记录的 Tailscale 或 LAN 地址或主机名；如果打印出的主机名应与绑定地址不同，请使用 --url-host <hostname>。 辅助脚本会禁用 marimo 访问令牌，因此只有在已记录的环境要求绑定所有接口时（例如需要同时通过 localhost 和远程访问），才使用 --host 0.0.0.0 --url-host <hostname>。 仅限本地访问或没有已知的直接访问路径时，省略主机选项，并说明生成的 URL 仅在执行机器上可用；如果请求的远程访问需要隧道，则使用 SSH 转发。

   主机选项仅对新启动的服务器生效。 如果 open 复用了一个其报告 URL 无法通过所选主机名访问的会话，请说明不匹配情况，不要声称请求的启动已成功。 保留该会话中正在进行的工作；只有在用户现有指示授权重启，或获得用户授权后，才替换该会话。

3. 原样报告 url=、session= 和 cells= 行。 cell_error= 行表示笔记本已运行，但有单元格出错：请报告这些错误；会话仍保持运行，以便继续迭代。 如需回答有关会话状态的后续问题，请运行 <skill-dir>/scripts/catalog-session.py status --cells；使用 run <port> 重新运行单元格；使用 stop <port> 停止由你拥有的会话。

组合工作流

常规笔记本编写使用 marimo-notebook，所有实时内核操作使用 marimo-pair。 如果仓库说明、catalog.toml 和本技能的笔记本约定有更具体的要求，则以这些要求为准，覆盖通用的 marimo-notebook 建议。 如果缺少任一项目技能，请停止操作，并向用户提供仓库中记录的安装命令，而不要擅自安装。

1. 阅读仓库的 AGENTS.md、catalog.toml，以及 [data].caveats 指定的任何路径。 使用清单查找可能相关的笔记本，然后阅读其中的实际代码和文档字符串。 清单是经过整理的路由表，不一定包含所有笔记本或辅助工具。

2. 选择能回答问题的最短路径。 如果现有笔记本的工作流已经适用，就修改其中的输入。 否则创建一个组合笔记本，并导入最接近的辅助工具，而不是重新实现其请求、解析、联接或绘图逻辑。 编写或修改笔记本时，请阅读 references/notebook-contract.md。

3. 对于新的组合笔记本，创建最精简且有效的 marimo 脚手架，包括初始设置导入项。 使用 catalog-session.py open notebooks/<name>.py 打开要改造或组合的确切笔记本；根据快速路径访问规则添加主机选项。 使用报告的 URL 和会话 ID 调用 marimo-pair；在验证已保存的文件之前，以活动运行时为准。

4. 通过实时内核完成工作。 使用 marimo-pair 的代码模式进行持久化单元格编辑，运行每个更改过的单元格，并检查返回的表格和渲染后的图形，然后再解读结果。 从有界查询开始探索远程或 REST 数据，然后有意扩大查询范围。 将答案所需的所有依赖项都保留在笔记本中，不要只放在临时状态里。

5. 从干净状态验证已保存的笔记本：

   bash <skill-dir>/scripts/validate-notebook.sh notebooks/<name>.py
   

   验证器会运行固定版本的 marimo 检查、稳定的 Ruff 规则集、冷启动执行，以及显式失败单元格扫描，因为 marimo 可能在退出代码为零时仍报告失败。 默认情况下，它会还原源文件和快照；只有当目录策略要求格式化并刷新快照时才传入 --write。 遵循目录对生成的会话快照和分析输出的具体政策。

6. 报告运行了什么、检查了什么、答案及其限制；如果会话仍有用，也要提供实时 URL。 使用 <skill-dir>/scripts/catalog-session.py stop <port> 停止不再需要的会话。 只有当用户希望将组合笔记本整理成可复用示例时，才将其加入 catalog.toml。

如果用户要求验证整个目录，请枚举实际的笔记本文件，而不要假定 catalog.toml 已列出全部内容；如果目录跟踪生成的快照，则在一次性工作树或归档中逐一验证。