vignette-catalog-scaffold

搭建 vignette 目录

目录从清单和一个实用的 notebook 开始，而不是从软件包或流水线开始。 只有在无法推断时，才询问目录名称、目标路径和数据接口（rest、duckdb、pooch 或 files）。

工作流

1. 检查目标。 对于新目录，要求目标目录不存在或为空。 对于现有仓库，保留其文件并使用 --adopt。 询问一次要采用哪些可选约定，除非用户或现有仓库策略已指定这些选项：标准数据布局和工作约定、包含索引 notebook 的输出摘要，以及已提交的会话快照。 在第 5 步说明这些选项；可以任意组合，也可以都不选，并在应用前等待答复。

2. 生成最小结构：

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

   脚本会复制真实资源，而不是要求模型根据文字描述重新生成模板。

3. 将 notebooks/nb01_orientation.py 中特意保留的 NotImplementedError 替换为一次范围明确、能访问实际数据集的调用。 将可复用的访问逻辑放在顶层 @app.function 中，并在 notebook 的 PEP 723 区块中声明其依赖项和版本。

4. 在 catalog.toml 中填写数据集专属字段：描述、上游版本、缓存、注意事项、身份验证、辅助函数名称，以及概览 notebook 所演示的内容。 将数据集标识符、API 行为、哈希值和运维注意事项保留在此目录中，而不是共享技能中。

5. 在采用现有仓库时，应协调现有的 README.md、AGENTS.md、.gitignore 和 pyproject.toml，而不是覆盖它们。 生成的 AGENTS.md 包含精确的克隆后技能安装命令。 在数据集约定中记录已选择和未选择的约定，包括路径和快照策略，并据此调整 .gitignore。

   • 如果选中，请使用标准的数据布局和协作约定：受保护的输入放在 data/raw/ 和 data/external/，可复现的共享准备结果放在 data/interim/，每项分析的工作区放在 data/processed/<analysis>/。 数据从 raw/external 流向 interim，再流向 processed；分析也可以直接读取输入。 切勿手动编辑输入或共享中间结果；应修改准备笔记本或辅助程序，然后重新生成中间结果。 仅在需要时创建目录。 在目录的 AGENTS.md 中记录协作约定，并链接现有清单条目或文档，而不是重复其内容。 列出输入来源、可用时的版本或哈希，以及检索辅助程序或命令。 列出用于重建每项共享中间结果的笔记本或命令，或说明无需重建；标明每项分析的输入和输出路径。 说明协作者如何检索和共享输出，或如何在本地复现；如适用，还要说明由谁协调共享输入或准备流程的变更。 仅与用户确认缺失的信息，并在完成设置前，通过一个范围有限的示例验证文档中记录的检索和重建流程。 共享必须保留其他协作者的输出和仅存于本地的工作；设置本身不授权上传或替换共享数据。
   • 如果选中，请添加输出摘要和索引：每项保存了输出的分析都要写入一个 summary.json，其中包含 description、numbers（名称／值对象）和 files（含仓库相对 path 与 caption 的对象）。 使用标准布局时，将文件放在 data/processed/<analysis>/summary.json；否则记录选定的输出路径。 创建 notebooks/index.py，用于发现并显示这些封装，同时允许集合为空。 如果输出被忽略，则将这些封装及其父目录加入允许列表，以便全新检出后也能发现它们；输出文件不可用时应妥善处理，不要导致失败。
   • 如果选中，请提交会话快照：将 marimo 快照保存在 notebooks/__marimo__/，用于审阅或浏览输出，并在验证时使用 --write 刷新。 否则，让快照保持忽略状态。

6. 使用文档记录的命令安装项目技能，通过 vignette-catalog-compose-notebook 打开导览笔记本，检查其实际输出，并运行其 scripts/validate-notebook.sh。

使用现有的目录辅助程序和笔记本进行检索与准备。 仅当项目需求要求时，才添加 src/、共享环境、工作流引擎或云同步。