dltHub AI Harness 是 dlt-hub 发布的 AI 编码助手工具包集合，用于让 AI 助手按照分步工作流构建基于 dlt 的数据管道。dlt（data load tool）是一个开源 Python 库，用于从 API 和数据库加载数据到仓库或湖仓；dltHub 是构建在 dlt 之上的付费平台，为编码代理增加转换、数据质量检查、托管运行时、托管数据应用和 AI 工作区等功能。该工具包可原样使用，也可 fork 并针对自有技术栈定制。
主要能力与工作流：
- 支持迭代式数据工程流程。第一阶段是摄取（ingestion），第二阶段是转换（transformation）。每个阶段重复“构建（本地开发）—探索并验证已加载数据—重复直至管道可用”的循环；随后进入“运行（生产）”：将摄取或转换管道部署到生产，并通过基于已加载数据的 数据应用 提供洞察。两个阶段之间还有一个循环：转换与 serving 层的洞察反馈到摄取阶段。
- 工具包按用途分为构建工具包与运行工具包。构建工具包覆盖摄取（REST API、SQL）、转换和数据质量；运行工具包覆盖部署和探索。REST API 工具包由 dltHub 上下文支持，包含超过 9,700 个源定义，代理可查询这些定义以在写代码前找到经过验证的连接器。新用户可以从快速入门工具包开始，获得从数据到仪表盘的引导式端到端运行。
- 每个工具包含有技能、命令、规则、代理和 MCP 服务器，并由一个工作流串联，告诉助手在每个步骤运行哪个技能以及如何使用 MCP 服务器。所有工具包依赖 init 来提供共享规则、机密处理和 MCP 服务器；使用 dlthub ai CLI 时 init 会作为依赖自动安装，使用 Claude 市场时需单独安装 init 插件。
MCP 服务器：
- dlt-workspace-mcp（本地，由 dlthub ai init 安装）暴露数据检查工具（list_tables、preview_table、execute_sql_query、get_row_counts、get_table_schema、export_schema、get_local_pipeline_state）、机密工具（secrets_view_redacted、secrets_update_fragment）以及工具包发现（list_toolkits、toolkit_info）。
- dltHub 上下文（远程）提供 search_dlthub_sources，供 find-source 技能搜索 9,700+ REST API 源定义，并在写代码前返回经过验证的连接器和参考链接。 借助 MCP 服务器，助手可以回答“加载了哪些表？”或“展示 schema”等问题，无需手动粘贴输出。
使用方式：
- 新项目（推荐）：运行 dlthub-init，该命令非交互式，编码助手可代为运行；它会固定 dlt[hub] 版本并运行 uv sync。
- 现有项目：在同一位置运行 dlthub-init，它会合并 pyproject.toml、保留 secrets.toml 并向 .gitignore 添加缺失行，然后固定 dlt[hub] 并运行 uv sync。
- 手动步骤（回退方案）：如果 dlthub-init 不可用，或希望自己执行每一步。
- 所有 dlthub ai 命令使用 uv run dlthub ... 语法；若全局安装或处于已激活虚拟环境，可省略 uv run 直接调用 dlthub，建议使用 uv。
- dlthub ai init 会从环境变量和配置文件检测编码助手，并将技能、规则和 MCP 服务器安装到该工具的正确位置。
- 针对不同助手有注意事项：Claude Code 需在 CLAUDE.md 添加安全凭证处理内容；Cursor 需在 Cursor 设置 > MCP 手动启用 dlt-workspace-mcp 服务器，并在 .cursor/rules/security.mdc 添加安全规则；Codex 将命令和规则转换为技能与 AGENTS.md，且运行在严格沙箱中，可考虑开启网络访问，并在 AGENTS.md 添加安全规则。
- 首次入门（想试用或学习 dltHub）：自行运行 dlthub-start，它会创建 playground 工作区，不适用于生产或真实项目；该命令需在真实终端运行，会要求身份认证，不能在 ! 模式使用。代理驱动的设置应使用前面的 dlthub-init。
- 浏览与安装工具包：若未安装 dlthub，先执行新项目或现有项目步骤；不确定需要哪些工具包时可全部安装。
- 启动 harness：使用各工具包提供的示例提示词启动工作流。Claude Code 通过终端 claude 启动新会话，安装后需重启；Cursor 打开项目并使用聊天面板（Cmd+L），自动识别已安装的技能和规则；Codex 通过 codex 启动 CLI 或使用 UI 中的 Codex 聊天，设置后需重启以让 MCP 服务器生效。
- Claude Code 市场插件（早期访问）：插件对工具包的链接不如 dlthub ai toolkit install，首次尝试建议用首次入门路径；插件路径适用于从 Claude Code 内部用 bootstrap 工具包设置的项目。插件仅在新会话激活，需用 claude 重启。
- dlthub ai CLI：初始化项目规则、机密技能和忽略文件，并为代理配置 dlt MCP 服务器；其工具包安装命令会将技能、规则、命令和 MCP 配置复制到项目的代理配置目录（.claude/、.cursor/、.agents/ 等）；机密管理命令允许助手检查和更新 dlt 存储在 TOML 文件中的凭证，而无需读取原始机密值；MCP 服务器命令启动本地服务器，将 dltHub 工作区（管道、schema、表、机密）暴露为助手可调用的工具。
适用场景： 适合使用 Claude Code、Cursor、Codex 等 AI 编码助手、希望以结构化工作流构建数据摄取与转换管道的开发者，尤其是需要 REST API 或 SQL 数据加载、数据质量检查、部署和数据应用展示，并希望代理在写代码前查找验证连接器的场景。新用户可通过快速入门工具包获得引导式端到端体验。
限制： dltHub AI Harness 已针对 Claude Code、Cursor 和 Codex 测试，其他 AI 编码助手也可使用。Codex 不支持命令和规则，安装器会将其转换为技能和 AGENTS.md，且运行在严格沙箱中，可能需要开启网络访问。Claude Code 插件为早期访问，对工具包的链接不如 CLI 安装方式。dlthub-start 创建的 playground 工作区仅用于试用或学习，不可用于生产或真实项目。dltHub 是付费平台，本项目采用 dltHub AI Harness License。
