vignette-catalog-compose-notebook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Work in a vignette catalog

在vignette目录中工作

A catalog is a

catalog.toml

plus self-contained marimo notebooks that double as worked examples and importable helper modules. Use

marimo-notebook

for general notebook authoring and

marimo-pair

for every live-kernel action. Repository instructions,

catalog.toml

, and this skill's notebook contract override generic

marimo-notebook

advice when they are more specific. If either project skill is absent, stop and give the user the repository's documented install command rather than installing it implicitly. Resolve

<skill-dir>

to this installed skill and execute its Python scripts directly so their

uv

shebangs apply.

目录由

catalog.toml

加上独立的marimo notebooks组成，这些notebook既是实操示例，也是可导入的助手模块。通用notebook创作请使用

marimo-notebook

，所有实时内核操作请使用

marimo-pair

。当仓库说明、

catalog.toml

以及本技能的notebook协议比通用

marimo-notebook

建议更具体时，以后者为准。如果缺少任一项目技能，请停止操作并向用户提供仓库文档中记载的安装命令，而非隐式安装。将

<skill-dir>

解析为已安装的本技能路径，并直接执行其Python脚本，以确保其

uv

shebang生效。

Workflow

工作流程

Read the repository's
```
AGENTS.md
```
,
```
catalog.toml
```
, and any path named by
```
[data].caveats
```
. Use the manifest to find likely notebooks, then read their actual code and docstrings. The manifest is a curated routing table, not necessarily an inventory of every notebook or helper.
Connect to the relevant notebook with
```
marimo-pair
```
. Discover an existing session first. If none fits, run
```
<skill-dir>/scripts/catalog-session.py start [notebook]
```
; omitting the notebook starts
```
[getting_started].first_notebook
```
. The command prints the URL, port, and session id needed to target the kernel explicitly.
Take the shortest path that answers the question. Change inputs in an existing notebook when its workflow already fits. Otherwise create a composed notebook and import the closest helpers instead of recreating their requests, parsing, joins, or plots. Read references/notebook-contract.md when authoring or changing a notebook.
Work through the live kernel. Use
```
marimo-pair
```
code mode for durable cell edits, run each changed cell, and inspect the returned tables and rendered figures before interpreting them. Start remote or REST exploration with a bounded query, then widen deliberately. Keep every dependency of the answer in the notebook, not only in scratch state.
Prove the saved notebook from a clean state:
bash
```
bash <skill-dir>/scripts/validate-notebook.sh notebooks/<name>.py
```
The validator runs pinned marimo checks, a stable Ruff rule set, cold execution, and an explicit scan for failed cells because marimo can report failure while exiting zero. It restores source and snapshots by default; pass
```
--write
```
only when the catalog policy calls for formatting and a refreshed snapshot. Follow the catalog's own policy for generated session snapshots and analysis outputs.
Report what ran, what you inspected, the answer and its limits, and the live URL if the session remains useful. Stop a session you no longer need with
```
<skill-dir>/scripts/catalog-session.py stop <port>
```
. Promote a composed notebook into
```
catalog.toml
```
only when the user wants it curated as a reusable vignette.

阅读仓库的
```
AGENTS.md
```
、
```
catalog.toml
```
以及
```
[data].caveats
```
指定的所有路径。使用清单查找可能的notebook，然后阅读其实际代码和文档字符串。清单是经过筛选的路由表，不一定包含所有notebook或助手。
使用
```
marimo-pair
```
连接到相关notebook。先查找现有会话。如果没有合适的会话，运行
```
<skill-dir>/scripts/catalog-session.py start [notebook]
```
；省略notebook参数将启动
```
[getting_started].first_notebook
```
。该命令会打印出明确指定内核所需的URL、端口和会话ID。
选择最短路径解答问题。当现有notebook的工作流符合需求时，修改其输入。否则创建一个组合notebook，并导入最相近的助手，而非重新实现其请求、解析、连接或绘图逻辑。编写或修改notebook时，请阅读references/notebook-contract.md。
通过实时内核开展工作。使用
```
marimo-pair
```
代码模式进行持久化单元格编辑，运行每个修改后的单元格，并在解读返回的表格和渲染的图表前先检查它们。从有界查询开始进行远程或REST探索，然后有目的地扩大范围。将答案的所有依赖项保存在notebook中，而不只是临时状态里。
在干净状态下验证已保存的notebook：
bash
```
bash <skill-dir>/scripts/validate-notebook.sh notebooks/<name>.py
```
验证器会运行固定版本的marimo检查、一套稳定的Ruff规则集、冷启动执行，以及针对失败单元格的显式扫描，因为marimo可能在退出码为0的情况下报告失败。默认情况下，它会恢复源代码和快照；仅当目录策略要求格式化和刷新快照时，才传入
```
--write
```
参数。遵循目录自身的策略处理生成的会话快照和分析输出。
报告运行内容、检查结果、答案及其局限性，如果会话仍有用则提供实时URL。使用
```
<skill-dir>/scripts/catalog-session.py stop <port>
```
停止不再需要的会话。仅当用户希望将组合notebook作为可复用的vignette进行管理时，才将其添加到
```
catalog.toml
```
中。

Running a catalog without composing

不进行组合的情况下运行目录

When the user only wants setup or verification, start the requested notebook, run all cells through

marimo-pair

, inspect one meaningful output, and report the URL. When asked to verify the whole catalog, enumerate the actual notebook files rather than assuming

catalog.toml

is exhaustive, and validate each in a disposable worktree or archive if the catalog tracks generated snapshots.

当用户仅需要设置或验证时，启动指定的notebook，通过

marimo-pair

运行所有单元格，检查一个有意义的输出，并报告URL。当要求验证整个目录时，枚举实际的notebook文件，而非假设

catalog.toml

是完整的；如果目录跟踪生成的快照，请在临时工作树或归档中验证每个notebook。