vignette-catalog-scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scaffold a vignette catalog

搭建vignette目录

A catalog starts as a manifest and one useful notebook, not a package or pipeline. Ask for the catalog name, target path, and data surface (

rest

duckdb

pooch

, or

files

) only when they cannot be inferred.

目录最初由一份清单和一个实用的notebook构成，而非包或流水线。仅当无法推断时，才询问目录名称、目标路径和数据接口（

rest

、

duckdb

、

pooch

或

files

）。

Workflow

工作流程

Inspect the target. For a new catalog, require an absent or empty directory. For an existing repository, preserve its files and use
```
--adopt
```
.

Generate the minimum structure:

bash

<skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface>
# Existing repository:
<skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface> --adopt

The script copies real assets rather than asking the model to reproduce templates from prose.

Replace the deliberate
```
NotImplementedError
```
in
```
notebooks/nb01_orientation.py
```
with one bounded call that reaches the actual dataset. Put reusable access logic in a top-level
```
@app.function
```
, and declare its dependencies and versions in the notebook's PEP 723 block.
Fill the dataset-specific fields in
```
catalog.toml
```
: description, upstream version, cache, caveats, auth, helper names, and what the orientation notebook demonstrates. Keep dataset identifiers, API behavior, hashes, and operational caveats in this catalog rather than the shared skills.
Reconcile existing
```
README.md
```
,
```
AGENTS.md
```
,
```
.gitignore
```
, and
```
pyproject.toml
```
instead of overwriting them when adopting. The generated
```
AGENTS.md
```
contains the exact post-clone skill install commands.
Install the project skills using that documented command, open the orientation notebook through
```
vignette-catalog-compose-notebook
```
, inspect its real output, and run its
```
scripts/validate-notebook.sh
```
.

Do not add

src/

, a shared environment, workflow engine, cloud sync, or an index until repeated work demonstrates the need.

检查目标位置对于新目录，要求目标目录不存在或为空。对于已有仓库，保留其文件并使用
```
--adopt
```
参数。

生成最小结构：

bash

<skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface>
# 已有仓库：
<skill-dir>/scripts/scaffold.py <target> --name <name> --surface <surface> --adopt

该脚本会复制真实资源，而非让模型根据文本描述重现模板。

将
```
notebooks/nb01_orientation.py
```
中刻意设置的
```
NotImplementedError
```
替换为一个能连接到实际数据集的有限调用。将可复用的访问逻辑放在顶层
```
@app.function
```
中，并在notebook的PEP 723块中声明其依赖项和版本。
填写
```
catalog.toml
```
中数据集专属字段：描述、上游版本、缓存、注意事项、认证信息、辅助工具名称，以及入门指引notebook展示的内容。将数据集标识符、API行为、哈希值和操作注意事项保存在此目录中，而非共享技能里。
采用已有仓库时，协调现有的
```
README.md
```
、
```
AGENTS.md
```
、
```
.gitignore
```
和
```
pyproject.toml
```
，而非覆盖它们。生成的
```
AGENTS.md
```
包含克隆后安装技能的确切命令。
使用文档中记录的命令安装项目技能，通过
```
vignette-catalog-compose-notebook
```
打开入门指引notebook，检查其实际输出，并运行
```
scripts/validate-notebook.sh
```
。

除非重复工作表明有必要，否则不要添加

src/

目录、共享环境、工作流引擎、云同步或索引。