get-started

初始化新的 Keboola 组件

编写任何代码之前，请检查组件是否已初始化。

第 1 步：检测状态

检查是否存在现有 cookiecutter 设置的迹象：

ls src/component.py component_config/ pyproject.toml 2>/dev/null

• 如果全部存在 → 跳过初始化，立即交接给 @develop-component
• 如果缺少或仓库为空 → 继续执行以下初始化步骤

第 2 步：收集组件信息

你可能已经从对话中了解组件详情。如果没有，请询问：

• 组件名称 — 使用 kebab-case，不带类型后缀（例如 ex-salesforce，而不是 salesforce-extractor）
• 组件 ID — 使用 vendor.component-name 格式（例如 keboola.ex-salesforce）
• 类型 — extractor、writer 或 application
• 简短描述 — 用一句话说明组件的功能

命名规则：

• 名称本身不得包含“extractor”“writer”或“application”
• 使用前缀约定：提取器使用 ex-，写入器使用 wr-

第 3 步：运行 cookiecutter

# Install if missing
which cookiecutter || pip install --user cookiecutter

cookiecutter gh:keboola/cookiecutter-python-component

以交互方式运行，以便用户确认这些值。该模板会创建 src/、component_config/、tests/、.github/workflows/、Dockerfile、pyproject.toml 和 data/，并在其中生成示例文件。

第 4 步：清理和配置

# Remove the generic example files that come with the template
find data -type f -delete

# Recreate the expected directory structure
mkdir -p data/in/tables data/in/files data/out/tables data/out/files

然后创建 data/config.json，根据组件的实际功能填写合理的示例参数，而不是使用通用占位内容。如果 component_config/configSchema.json 已有内容，请读取并按照必填字段填写合理的示例值。敏感字段使用 # 前缀（例如 "#api_key"）。

第 5 步：创建初始提交

git add -A
git commit -m "feat: initialize component from cookiecutter template"

第 6 步：交接

初始化完成后，交给 @develop-component 开始实现。分享你已了解的组件用途，以便其掌握相关背景。

---

关键资源

• Cookiecutter 模板：gh:keboola/cookiecutter-python-component
• Developer Portal：https://components.keboola.com/
• 组件教程：https://developers.keboola.com/extend/component/tutorial/