dataapp-development

Keboola 应用开发

本技能涵盖 Keboola Apps（原名“Data Apps”）的完整生命周期：选择合适的应用类型、本地构建、部署和调试。它支持 Streamlit 应用和 Python/JS 应用，以及三种客户端路径（仅 MCP、具有文件系统访问权限的 Claude Code，以及 kbagent CLI）。

本技能充当路由器——不包含所有指导内容。系统会根据当前任务按需加载 references/ 文件。请先阅读下面的决策树，然后只加载所需的参考资料。

决策树

按顺序回答以下问题。每个答案都会指向相应的参考资料。

1. 任务是什么？

任务	首先查阅
从头构建新应用	references/choosing-app-type.md → 类型专属参考资料 → references/deployment-paths.md。Python/JS：先阅读 references/python-js-prod-and-drafts.md——通常已经存在生产应用
任何会调用 modify_python_js_data_app 的操作	调用前先阅读 references/python-js-prod-and-drafts.md
修改现有应用（添加功能、修复错误）	查看 references/dev-workflow.md 了解变更流程。Python/JS：继续使用该应用的草稿——references/python-js-prod-and-drafts.md
查看应用在开发模式下实际显示的内容	references/dev-workflow.md §验证在开发模式下运行的应用——在你自己的浏览器中打开预览链接
从并非刚刚克隆的克隆版本中读取、描述或推送	references/existing-clone.md
部署或重新部署	references/deployment-paths.md
调试部署或运行时问题	references/troubleshooting.md
在不同类型之间迁移现有应用	references/choosing-app-type.md + references/streamlit-apps.md + references/python-js-apps.md

2. 应用类型是什么？

如果不确定 → references/choosing-app-type.md。简要说明：

• Streamlit——适合团队只使用 Python 且界面主要由侧边栏和主面板组成的场景，构建速度最快。请阅读 references/streamlit-apps.md。
• 单个 Node 容器中的 React + Vite + Express——Python/JS 的默认方案。从 templates/react-vite-app/ 开始；浏览器加载的所有内容都会打包。请阅读 references/python-js-apps.md。
• Python + Node 组合——仅在确实需要 Python 后端时使用（机器学习模型、现有 Python 代码库）。请阅读 references/python-js-apps.md（多服务端部分）。

3. 客户端路径是什么？

references/deployment-paths.md 涵盖全部三种路径：

• 路径 A — Claude Desktop / 网页版（仅 MCP，无文件系统）： Streamlit 使用 modify_streamlit_data_app / deploy_data_app；Python/JS 使用 modify_python_js_data_app + create_python_js_data_app_git_credential + git + deploy_data_app（参见 references/python-js-prod-and-drafts.md；需要支持 git 的运行器）。
• 路径 B — Claude Code / 具有文件系统和 MCP 的本地 Agent： 在本地编辑文件，推送到应用的 git 仓库（由 Keboola 管理或由客户提供），然后通过 MCP 或 kbagent 部署。
• 路径 C — CLI Agent（kbagent）： 通过 kbagent data-app 命令组完成完整生命周期。

4. 是否涉及跨领域注意事项？

注意事项	参考资料
从 Keboola Storage 读取数据 / 写入数据（只读默认使用 DuckDB 缓存）	references/storage-access.md + references/duckdb-caching.md
保护应用安全（登录、SSO、OAuth）	references/authentication.md
降低 DWH 成本并加快只读仪表板的速度（只读应用的默认设置）	references/duckdb-caching.md
样式——默认 Keboola 调色板和页脚	references/styling-guide.md
样式——在模板基础上使用 shadcn/ui、深色模式和 ECharts	references/styling-react-bundled.md
构建仪表板类应用	references/dashboard-patterns.md
在应用中添加自然语言助手	references/kai-integration.md
源代码仓库 / 规范文档 / UI 导航	references/glossary.md

模板索引

模板	适用场景
templates/streamlit/	新建 Streamlit 应用、代码部署或 Git 部署。
templates/python-app/	新建纯 Python 的 Python/JS 应用（Flask 或类似框架）。
templates/react-vite-app/	新建 Python/JS 应用——默认模板（React + Vite + Tailwind + Express）。
templates/python-node-app/	在默认模板的 Node 服务旁添加 Python 后端。
templates/duckdb-cache/	为现有 Python 或 Node 应用添加 DuckDB 缓存模式。

需要权威的 Keboola 文档？

Keboola MCP 服务提供 docs_query 工具，用于搜索官方 Keboola Connection 文档。如果此技能的参考资料无法解答问题（例如 UI 导航细节、边缘情况、近期平台变更），请调用 docs_query 获取权威答案，不要猜测或依赖过时的记忆。

硬性规则（适用于每项任务）

1. 绝不要提交 .streamlit/secrets.toml 或任何包含真实凭据的文件。提交前将其添加到 .gitignore。
2. 先采用只读（RO）工作区，再考虑输入映射。 新应用默认采用 RO 工作区模式。不建议使用输入映射——请参阅 references/storage-access.md。
3. 应用必须在根路径处理 POST /。 Keboola 启动时会向 / 发送 POST 请求；React + Vite 模板会在 nginx 中响应此请求。Streamlit 原生支持此功能；Flask 需要设置 methods=["GET", "POST"]；Express 需要使用 app.all('/')。
4. Python 应用中不要使用 pip install。 基础镜像会阻止 PEP 668。使用由 pyproject.toml 驱动的 uv sync。所有 Python supervisord 命令都必须使用 uv run。
5. 绝不要在 keboola-config/supervisord/ 中声明 [program:nginx]。 Nginx 由基础镜像管理。
6. 先验证数据，再编写代码。 使用 Keboola MCP 时，先调用 get_table 和 query_data 确认架构，再编写 SQL。如果项目有语义层，先通过 search_semantic_context / get_semantic_context 检查，并依据其中的定义构建查询，而不是自行臆造计算方式。请参阅 references/dev-workflow.md。
7. 每次会话只选择一种 Keboola 路径。 在任何会修改项目的调用之前，运行两项检测（which kbagent + 扫描 mcp__*[Kk]eboola* 工具）；如果发现不止一种路径，请询问用户要使用哪一种。不要擅自选择。请参阅 references/deployment-paths.md §Pick one path per session。
8. 仅使用 MCP 的流程：将源代码直接放入工具调用。 选择 modify_streamlit_data_app 路径时，source_code 参数就是部署制品——不要预先写入本地副本。请参阅 references/deployment-paths.md Path A。
9. 本地开发凭据：尽可能预填已有信息，询问缺失信息，然后再提出代为运行。 绝不要 grep 文件系统，也不要扫描无关的环境变量来查找令牌。请参阅 references/storage-access.md §Getting the env vars for local development。
10. 空 id 表示创建。 对于空 configuration_id 会将更新切换为创建的 Keboola 工具（modify_python_js_data_app、modify_streamlit_data_app），id 是决定性因素，不是细节。发送空值前，务必在回复中说明你正在创建新资源，以及为何没有合适的现有资源。对于 Python/JS 应用，创建操作还会配置一个之后永远无法再关联的 git 仓库；而 parent_configuration_id 才会将调用设为草稿。请参阅 references/python-js-prod-and-drafts.md。
11. 启用 Storage 访问前，说明它会授予什么权限。 工作区的范围是整个项目，而非应用使用的表——应用可以读取项目 Storage 中的每张表。启用 storage_access 时，请用自己的话告知用户这一点；如果应用是 no-auth，还要再次说明任何拥有 URL 的人都能通过该应用访问数据。启用此功能没有问题，而且通常正是用户需要的；但不能默默启用。请参阅 references/storage-access.md。
12. 草稿和生产应用之间的配置不会双向同步。 它们是独立的 Storage 配置；git 合并只会迁移源代码，不会迁移其他内容。创建草稿时也不会继承任何配置——modify_python_js_data_app 只会读取父项的仓库和凭据。因此，迭代期间设置的内容（storage_access、可写表 storage、authentication_type、auto_suspend_after_seconds）只会应用于草稿；部署生产应用前，必须再次设置。最容易出问题的两项是：未设置 storage_access 时，生产应用会在请求时因 missing required env vars: WORKSPACE_ID 而失败；未设置 storage 输出映射时，应用的写入会失败，但读取仍然正常。这两种情况看起来都像是代码回归，实际并非如此。请参阅 references/python-js-prod-and-drafts.md §6。
13. 记录元数据，绝不记录数据。 应用日志可能泄露最终用户的个人身份信息（PII）。记录行数、列名、脱敏后的 SQL，以及代码由哪个分支响应——绝不要记录单元格值、行内容、响应正文或原始请求值。console.debug(`${rows.length} rows, columns: ${Object.keys(rows[0] ?? {})}`) ✓ — console.debug(rows) 或记录客户邮箱 ✗。
14. 运行时不得从 CDN 加载任何内容。 浏览器加载的每个脚本、样式表和字体，都必须在构建时打包或由应用本身提供——绝不要使用 <script src="https://cdn…">。CDN 中断、软件包遭到入侵或页面内容策略都可能从应用外部导致应用无法运行。新建的 Python/JS 应用从 templates/react-vite-app/ 开始，该模板已打包 React、Tailwind 和 Recharts。已有其他技术栈的应用继续使用原有技术栈：按其自身风格修改，不添加新的 CDN 依赖；只有得到用户同意后才迁移到该模板——如果某项改动本就会重写大部分前端，可以提出迁移建议。
15. 每个 Vite 应用都必须包含 kaiPreview()。 Keboola 的应用预览通过它判断应用是否已渲染，用户也可以通过它指示页面中的具体位置。修改现有 Vite 应用时，如果其 vite.config 不包含此函数，应在同一次改动中添加，无需告知用户，除非添加失败；旧版内联 kaiPreviewErrorHandler 不算，kaiPreview() 会取代它。请参阅 references/python-js-apps.md §Keboola's app preview。