关于 agentic-dbt-pipeline
agentic-dbt-pipeline 是用于协调 dbt 分析项目的 Cursor Agent 技能，覆盖从数据发现到模型分层和报告。它要求先基于证据完成发现并征求用户决策，再开展依赖此决策的构建工作。
主要功能
- 01只读源数据发现
- 02Bronze、silver 和 gold 分层工作流
- 03语义层与项目评估
- 04文档和分析报告
- 05审批关卡与需求追踪
- 06dbt 环境、包和技能管理
适用场景
- 01建模前分析源数据结构
- 02跨分析层构建 dbt 项目
- 03业务规则不明确时暂缓模型
- 04生成文档和分析报告
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/agentic-dbt-pipeline确认已加载。
详细介绍
dbt 分析工程师
dbt 项目的全生命周期编排器。 每次收到新的／完整流水线提示词时： Agent 先以只读方式运行 discovery-requirements.md，说明它根据源数据得出的结论，并在制定任何构建计划之前询问需求。 默认完整流水线： 发现 -> 项目设置和配置 -> 源 -> 青铜层 -> 白银层 -> 黄金层 -> 语义层 -> 项目评估器 -> 文档 -> 分析洞察报告 -> 展示层建议 -> 持续集成；启用且受支持时，还包括 Agents Schema。
使用 workflow_phase: 运行单个阶段。对于新项目／完整流水线工作，项目设置和配置会自动运行，除非用户明确禁用自动设置。
安装（一个命令）： npx skills add zohaibRT/agentic-dbt-pipeline - 参见 references/install-skill.md。
首次运行时，项目设置和配置会自动安装 dbt Agent Skills 和 dbt 软件包。
本地资源填充
某些版本的 npx skills add 只会将此 SKILL.md 入口文件安装到 Agent 文件夹中。此技能有意采用多文件结构，因此在读取任何 references/、运行任何 scripts/ 或使用 project.config.yml 之前，请确认这些资源存在于此 SKILL.md 旁边：
references/
scripts/
agents/
templates/
templates/reports/09_analytics_insights/
templates/reports/10_presentation/
docs/
project.config.yml
prompt.md
.env.example
如果有任何资源缺失（包括多 Agent Windows 安装失败后不完整的 templates/ 目录树），请先从代码仓库将资源填充到已安装的技能文件夹中，再继续。将包含此 SKILL.md 的目录用作 {skill_dir}。不要将资源填充到用户的 dbt 项目根目录中。
在 Windows 上，优先使用 npx skills add zohaibRT/agentic-dbt-pipeline --agent cursor -y，以免安装程序在多个 Agent 副本之间并发创建目录。
PowerShell：
$skillDir = "<directory containing this SKILL.md>"
$tmp = Join-Path $env:TEMP ("agentic-dbt-pipeline-" + [guid]::NewGuid().ToString())
git clone --depth 1 https://github.com/zohaibRT/agentic-dbt-pipeline.git $tmp
Copy-Item -Path (Join-Path $tmp "references") -Destination $skillDir -Recurse -Force
Copy-Item -Path (Join-Path $tmp "scripts") -Destination $skillDir -Recurse -Force
Copy-Item -Path (Join-Path $tmp "agents") -Destination $skillDir -Recurse -Force
Copy-Item -Path (Join-Path $tmp "templates") -Destination $skillDir -Recurse -Force
Copy-Item -Path (Join-Path $tmp "docs") -Destination $skillDir -Recurse -Force
Copy-Item -Path (Join-Path $tmp "project.config.yml") -Destination $skillDir -Force
Copy-Item -Path (Join-Path $tmp "prompt.md") -Destination $skillDir -Force
Copy-Item -Path (Join-Path $tmp ".env.example") -Destination $skillDir -Force
Remove-Item -LiteralPath $tmp -Recurse -Force
Bash：
skill_dir="<directory containing this SKILL.md>"
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/zohaibRT/agentic-dbt-pipeline.git "$tmp"
cp -R "$tmp/references" "$skill_dir/"
cp -R "$tmp/scripts" "$skill_dir/"
cp -R "$tmp/agents" "$skill_dir/"
cp -R "$tmp/templates" "$skill_dir/"
cp -R "$tmp/docs" "$skill_dir/"
cp "$tmp/project.config.yml" "$skill_dir/"
cp "$tmp/prompt.md" "$skill_dir/"
cp "$tmp/.env.example" "$skill_dir/"
rm -rf "$tmp"
填充完成后，只从本地磁盘读取参考资料和脚本。如果因无法使用 git 或网络而导致填充失败，请停止操作并告知用户技能资源缺失，不要假装已读取引用的文件。
安装和环境反模式
避免以下常见的首次运行错误：
| 反模式 | 正确做法 |
|---|---|
预期在运行 npx skills add 后立即出现工作区 .env | .env 会在 Agent 首次于工作区运行时创建，而不是在安装技能时创建 |
在发送第一个提示词之前让用户手动复制 .env.example | Agent 会解析 .env.example，并在工作区缺少 .env 时创建它 |
为常规项目设置编辑 .agents/skills/agentic-dbt-pipeline/project.config.yml | 使用工作区 .env 设置 DBT_DOMAIN、DBT_PROFILE_NAME 和 DBT_SOURCE_SCHEMA |
在缺少 .env 或其内容仅为占位值时运行发现流程或 dbt | 立即停止；先询问所需值 |
技能文件夹中已有 .env.example，却只在工作区查找 | 还要检查 .agents/skills/agentic-dbt-pipeline/.env.example |
根据 profiles.yml、数仓架构或猜测填写 .env | 只能使用用户在聊天中提供或明确批准的值 |
先发现，再进行项目设置和配置
在进行项目设置、项目初始化或运行完整流水线之前，先阅读并执行 references/discovery-requirements.md。
Discovery 只读且以项目为导向。它可以检查架构、表、列、行数、键、关系、日期、度量和状态。其输入、报告和输出必须聚焦于源数据和分析项目，而不是环境设置。即使 dbt 项目尚未初始化，也必须在聊天摘要之前写入 reports/agent/00_discovery/discovery_report.md、reports/agent/00_discovery/requirements.md、reports/agent/00_discovery/core_profile.json、reports/agent/00_discovery/discovery_raw.json、reports/agent/00_discovery/sql_proofs/、reports/agent/PIPELINE_STATUS.md 和 reports/agent/CONTEXT_TREE.md。对于 discovery 检查点创建或更新的每个文件，包括 discovery 报告、需求、结构化 JSON 证据、基数、关系概况、discovery 批准检查清单、证明索引、SQL 证明文件、管道状态、上下文树、报告索引、需求可追溯性和下一阶段提示词，都必须使用 templates/reports/00_discovery/ 和 templates/reports/root/ 下的规范模板。模板结构应在各个项目间保持一致；内容必须根据源证据和用户批准的规则进行调整。需求文件必须记录根据源证据和业务领域推断出的需求、建议默认值、未知事项、需要用户决策的事项，以及受阻或延期的范围。discovery sql_proofs/ 文件夹必须包含可重复使用的源数据证明查询及其捕获的结果，涵盖表清单、每表行数、候选键、重要状态（例如 active/open/closed 计数）、日期范围、数值摘要，以及源数据支持的关系和基数检查。discovery_raw.json.queries_executed[] 必须关联到支持 discovery 声明的 SQL 证明文件。若源证据支持创建 Mermaid discovery 图表，则必须创建这些图表，包括可信关系存在时的实体关系图，以及其他必要的源数据清单、业务流程或 medallion 方向图。不得安装软件包、运行 codegen、创建数据仓库架构或更改配置文件。
不要假设业务领域。在 discovery 期间，应先了解源表、表之间的关系、业务流程、所需指标、数据质量规则、所需输出模型和报告需求，再提出 dbt 模型。
如果其中任何方面无法得到充分理解或证明，就不要妄加假设。应向用户询问缺失的业务含义或所需批准，并将依赖这些信息的模型、测试、指标、语义定义或展示输出延期，直到不确定性得到解决。
Discovery 完成后，应先发送一条普通助手消息，其中包含醒目的 Markdown Discovery Complete 控制面板摘要，然后再请求批准。不要仅将 discovery 结果放在原生问题卡片、批准小组件或 request_user_input 正文中。聊天摘要必须包括状态、已审查的源数据、关键发现、验证或 SQL 证明要点、已写入的报告、待决事项、建议的下一步、下一步将包含和不包含的内容，以及批准方式。然后，只有在普通 Markdown 摘要清晰显示于问题正上方时，才提出简短的原生/可点击问题。问题示例：您是否批准此 discovery 范围，并希望接下来自动运行项目设置？ 建议选项：是，继续设置。其他选项：先添加需求和告诉我需要更改的内容。如果运行环境无法保证普通摘要会清晰显示于可点击问题正上方，就不要使用可点击问题；改用以下文本备用方案：您是否批准此 discovery 范围，并希望接下来自动运行项目设置？回复 Yes 以继续，或告诉我需要更改的内容。
完成发现后，总结 Agent 根据源数据得出的结论，并询问用户是否要添加映射、指标、隐私规则、命名规则、纳入或排除的表，或优先处理的事实表／维度表等要求。用户的回复由当前工作流检查点解释，而非根据宽泛意图解释。在发现检查点，下一步允许执行的操作仅限于确认数据源，以及自动设置和配置项目。不要将用户接受发现结果视为已批准数据源、bronze/staging、silver/intermediate、gold/marts、语义层、评估器、文档、分析洞察报告、展示层、持续集成、Agents Schema、提交、推送或未来的架构切换。
发现审批关卡
发现完成后，使用 discovery-approval-checklist.md 和 requirements-traceability-matrix.md 创建 reports/agent/00_discovery/DISCOVERY_APPROVAL_CHECKLIST.md 和 reports/agent/REQUIREMENTS_TRACEABILITY_MATRIX.md。在清单决策为 APPROVED 或 APPROVED WITH CONDITIONS 之前，不要继续引导设置／构建。如果批准附带条件，请将这些条件写入 reports/agent/CONTEXT_TREE.md、AGENT_PLAN.md 和 reports/agent/REQUIREMENTS_TRACEABILITY_MATRIX.md。
项目设置与配置（发现阶段后的自动设置专用阶段）
在进行任何层的工作之前，阅读并执行 references/bootstrap.md：
- 检查／安装软件前置条件 - Python、venv、dbt-core、匹配的适配器、技能要求 - software-prerequisites.md
- 安装 dbt Agent Skills + 所有 dbt 包 - 参见 dbt-packages-and-skills.md
dbt debug- 验证连接dbt deps+ codegen - 在需要处理源或完整管道时- 确定 Git 模式 - 默认使用本地提交；仅在请求推送时使用 GitHub - github-repo-resolution.md
- 创建持续集成和 Agents Schema 工作流 - 在用户提出请求时，或当
auto_agents_schema: true且目标受支持时
用户一次性手动操作：在 profiles.yml 中填写密码；仅当请求远程推送、持续集成或 Agents Schema 同步时，才需要提供 GitHub 仓库或密钥。
如果提示词中提供了 dbt_profile_name，则将其用作 dbt 命令和生成的 dbt_project.yml 中的 {project.profile}。如果未提供，且 ~/.dbt/profiles.yml 中存在多个配置文件，则在运行 dbt 命令前询问用户要使用哪个配置文件。切勿根据第一个配置文件进行猜测。
在通过发现需求检查点后，默认自动运行项目设置与配置，这是仅执行设置的阶段。除非触发设置安全检查，否则不要单独询问是否批准设置。此阶段可以创建本地 dbt 项目脚手架，从已安装的技能或工作区安装 requirements.txt，创建包含 SQL 证明索引文件的托管 reports/agent/ 骨架，安装缺失的 dbt Agent Skills 和 dbt 包，运行 dbt debug、dbt deps、dbt parse，并编写设置报告。此阶段不批准生成源 YAML、bronze/staging 模型、silver/intermediate 模型、gold/marts 模型、语义层文件、文档变更、持续集成工作流、Agents Schema 同步、替换仓库模型、提交或推送。
如果必需的 .env 值缺失、所选配置文件存在歧义或无法通过验证、配置文件的目标架构与源架构相同且需要用户批准更改、现有项目文件将被覆盖、设置验证之外还将创建或替换仓库对象、需要凭据或密钥、明确禁用了自动项目设置，或用户明确要求手动批准设置，则停止并询问用户，然后再进行项目设置与配置。
dbt 包和 Agent 技能（必需技术栈）
阅读 references/dbt-packages-and-skills.md。
| 能力 | 安装／使用 |
|---|---|
| dbt Agent Skills | 如果缺失，项目设置会自动安装（auto_install_dbt_skills: true） |
| codegen | packages.yml + generate_source |
| dbt_utils | packages.yml - 模型／测试中的宏 |
| dbt_project_evaluator | packages.yml + dispatch + dbt build --select package:dbt_project_evaluator |
| audit_helper | packages.yml - 在重构时比较查询 |
| MetricFlow / Semantic Layer | semantic-layer-spec.md + building-dbt-semantic-layer |
| Agents Schema | agents-schema-setup.md - 当目标受支持时，将 dbt 元数据发布到 AGENTS.*，为仓库侧 Agent 提供上下文 |
安装 Agent 技能：references/install-dbt-agent-skills.md
阶段概览
步骤 0 - 加载配置
阅读 project.config.yml、skill-inputs.md、profile-listing.md、project-naming.md、schema-isolation.md、env-configuration.md、source-confirmation.md、warehouse-adapter-routing.md、skill-knowledge.md、project-knowledge.md、discovery-requirements.md、discovery-artifacts.md、discovery-status-vocabulary.md、phased-discovery.md、recommendation-and-review.md、writing-style.md、reporting-standards.md、universal-analytics-framework.md、analytics-insight-reporting.md、mermaid-diagrams.md、principal-data-engineering-standards.md、evidence-driven-dbt-process.md、layer-data-validation.md、cardinality-validation.md、kpi-definitions.md、kpi-definition-contract.md、metric-verification.md、metric-verification-checklist.md、kpi-reconciliation.md、advanced-data-engineering-review.md、phase-plan-approval.md、data-engineer-decision-gate.md、phase-completion-report.md、report-artifact-organization.md、next-phase-prompt.md 和 context-tree.md。
对于上下文窗口较小的情况，请完整阅读必需的参考资料，提取适用于当前检查点的规则并记录到阶段计划或工作笔记中，避免保留未使用的细节。最好在进入某个阶段时再加载该阶段专用的参考资料。不要跳过必需的安全参考资料，但应总结与当前检查点无关的细节后再舍弃。
相对于工作区根目录解析路径。dbt 项目根目录 = {project.root}。
加载配置后、编写发现摘要或阶段计划之前，请阅读 skill-knowledge.md 和 project-knowledge.md。使用内置技能知识，遵循可复用的 dbt、大数据、数据仓库优化、Power BI、语义、隐私和验证标准。若存在 AGENT_KNOWLEDGE.md、docs/dbt_knowledge.md、docs/business_rules.md、.agents/project_knowledge.md 和 reports/agent/CONTEXT_TREE.md 等项目知识文件，请将其用于本地或领域规则覆盖。若与提示词中的 project_rules 冲突，优先遵循 project_rules。在将聊天中的新知识持久化之前，请先征求同意。
用户提示词优先于 .env 和配置，适用于 schema、domain、分层、物化方式和提交模式。向用户询问之前，先将 .env 用于可重复使用的非敏感输入。npx skills add 不会创建工作区 .env；如果缺失，请在首次运行时创建。若全新克隆中缺少 .env，请遵循 env-configuration.md：从工作区根目录、dbt 项目根目录或已安装的技能文件夹中查找 .env.example，仅使用占位值，根据该模板在本地工作区创建安全的 .env，使用 profile-listing.md 列出可用的 dbt 配置文件，在执行发现或 dbt 命令前停止，并向用户询问 DBT_DOMAIN、DBT_PROFILE_NAME 和 DBT_SOURCE_SCHEMA。不要根据配置文件、配置文件目标 schema、数仓 schema、旧运行记录、终端输出、示例、附近的工作区或猜测来填写 .env。不要搜索代码库、检查终端输出、推断、建议或概述其他工作区或之前运行中的值。
加载 .env 后、执行任何发现操作前，立即阅读 warehouse-adapter-routing.md。从 ~/.dbt/profiles.yml 解析当前使用的 dbt 配置文件和适配器；仅使用该适配器对应的发现路径。在选定的配置文件适配器解析并告知用户之前，不要调用 AWS、Redshift、PostgreSQL、Snowflake、BigQuery、Databricks、云身份检查、数仓连接器、元数据查询或 Model Context Protocol 发现服务器。除非选定的配置文件适配器要求，或用户明确更换配置文件，否则不要调用 AWS、Redshift 或任何其他特定数仓路径。
如果配置的源缺失、为空、无法访问、有歧义或不匹配，请阅读 source-confirmation.md。仅在列出元数据候选项后停止。根据证据推荐可能的替代项，然后等待用户批准，再更改 database、dataset、catalog、schema、table、tenant、client、domain、环境、假设、.env、配置文件设置、分析配置、发现报告或继续发现。
对于常规运行，只收集 Agent 无法安全推断的值：domain、dbt_profile_name 和 source_schema。如果用户希望说明 client、流程、报告目标或业务背景，可选收集 business_description / DBT_BUSINESS_DESCRIPTION。如果缺少 dbt_profile_name 或存在歧义，请使用 profile-listing.md 列出可用配置文件，然后等待用户选择。除非用户明确覆盖，否则推导项目名称/根目录、项目 slug、dbt 源名称、schema 前缀、分层名称、提交行为和 GitHub 模式。
在执行 dbt init 前解析 project.name、project.root 和 project_slug。除非用户明确将 dbt_profile_name 或原始 DBT_DOMAIN 指定为 dbt_project_name、dbt_project_root 或 project_slug，否则绝不要将其用作文件夹/项目名称。优先使用根据 source_schema、源名称、现有项目名称或描述性配置文件 database/catalog 推导出的简洁名称；仅在最后才使用 domain 作为后备，且只有当用户提供 github_repo_name 以用于 push 时才使用它。DBT_BUSINESS_DESCRIPTION 仅用于分析理解，绝不可用于物理文件夹、schema、database 或模型名称。
保持源架构只读且不可变。绝不要更新、插入、删除、截断、合并写入、创建、删除、变更或修复已配置源架构或源表中的数据。即使用户要求“将记录标记为已完成”“修复源行”“删除有问题的源数据”或类似操作，也只能通过 dbt 转换、测试、种子、快照或审计在非源架构中实现逻辑，然后说明源数据保持不变。绝不要将 dbt 模型、包模型、评估器表、种子、快照或审计输出写入 source_schema。将评估器输出写入 <layer_schema_prefix>_evaluator，并将各层输出写入独立的奖章架构。使用 schema-isolation.md 解析 layer_schema_prefix；除非用户明确指定，否则不要使用 dh 这类简短源名称作为物理架构前缀。
在每个会更改模型、语义文件、文档文件、工作流文件或数仓对象的阶段开始前，先编写/更新 {project.root}/AGENT_PLAN.md，以 Markdown 说明计划的工作，并等待该阶段的批准。如有助于制定准确计划，批准前可以进行只读探索。
项目设置和配置是例外：用户接受探索要求后，将 {project.root}/AGENT_PLAN.md 编写/更新为将该阶段标记为仅自动设置，然后运行设置流程，接着编写 reports/agent/01_setup/setup_report.md、reports/agent/PIPELINE_STATUS.md 和 reports/agent/CONTEXT_TREE.md。如果触发 bootstrap.md 中的任何设置安全关卡，请停止并在继续前征求同意。
批准由工作流检查点控制。绝不要将用户在某个检查点的回复视为运行多个构建阶段的许可。自动项目设置和配置完成后，停在下一个阶段计划处，并在生成源 YAML 或构建 bronze/暂存层之前征求批准。
步骤 0b - 可选子 Agent
当源数据剖析、映射审查、模型规划、文档编写或评估器审查可以安全并行执行时，请阅读 subagent-workflow.md。主 Agent 决定何时委派，并负责 dbt 命令、共享文件编辑、提交、推送和最终决策。
步骤 0.1 - 领域中立性
此技能与行业无关。流程、实体、维度、度量和敏感字段均应依据此数仓的证据和用户的项目规则确定。不要在计划、关卡或脚本中硬编码行业列名、品牌或实体目录。如果不存在相关表，不要强求采用电商/医疗保健/订阅类数据结构。参考文档中的示例仅供说明。
步骤 0.2 - 安全
阅读 security-and-credentials.md。
绝不要硬编码密钥。生产环境变更前请先征求同意。
步骤 0.3 - 数据工程防护准则
在模型设计前以及最终交付前，再次阅读 data-engineering-best-practices.md 和 principal-data-engineering-standards.md。应用有关粒度、测试、增量、快照、文档、血缘、有向无环图、新鲜度、宏、包、构建流程、隐私、性能、基于状态的持续集成、契约/版本控制、SQL 风格、数仓优化、现代表格式和下游呈现的防护准则。
当发现直接标识符、敏感字段、受保护的健康信息、个人身份信息，或含义模糊、占位、缩写或命名不佳的字段时，请阅读 privacy-and-unknown-fields.md 和 reporting-coverage-requirements.md。Agent 必须推荐安全的默认做法、记录建议，并且只询问是否批准或需要哪些业务定义，而不是把整个决定留给用户。当用户选择退出隐私最小化（例如 Do NOT apply privacy minimization unless I explicitly request it）时，记录该规则，构建带有业务标签的规范化报表维度，并在有用时在展示层呈现来自 gold 的报表属性——根据本项目的证据发现字段；不要硬编码行业字段列表。不要为了“安全起见”而隐藏属性，也不要撰写声称展示层仍会避免或隐藏标识符的报告文案。关闭 Attention Board 和 KPI Gap Register 中状态为 OPEN 的隐私最小化条目；除非用户明确要求，否则仅始终排除以下类别：密钥／OTP／完整银行数据转储／国民身份证号码／PHI。
在编写面向用户的提示词、计划、报告、摘要、图表注释、演示文稿材料或最终交付内容之前，请阅读 writing-style.md 和 reporting-standards.md。除官方工具名称、命令、文件名、环境变量和代码标识符外，应使用完整表述，不要使用简写。每份报告在相关时都必须包含五大报表支柱：背景与策略、关键绩效指标、趋势分析与差异、洞察与归因、建议与后续步骤。如果某个支柱目前缺乏依据，请说明原因并标记为延期，而不是猜测。
PIPELINE_STATUS.md、阶段报告、审批清单、SQL 证据索引和最终摘要中的每个 WARN、FAIL、BLOCKED 或 SKIPPED 状态，都必须说明使用该状态的原因、证据路径、数据工程师应审查的内容、所需操作，以及该状态是否会阻止进入下一检查点。不要让非 PASS 状态成为没有解释的标签。
在编写每个阶段计划之前，请阅读 data-engineer-decision-gate.md。阶段计划必须展示 Agent 的数据工程决策、证据和审批需求；不要把粒度、键、连接、桥接表、映射、隐私、指标、物化或验证方面的选择藏在代码中。
如果 Agent 无法理解当前范围内的源表、关系、业务流程、所需指标、数据质量规则、所需输出模型或报表需求，请停止相关范围并询问，不要猜测。
在每个阶段开始前，请阅读 phased-discovery.md。只发现下一层或工作流步骤所需的内容；在初始发现或 bronze 工作期间，不要全面设计 silver／gold／语义层输出。
在编写发现摘要、阶段计划、阶段报告和最终交付内容之前，请阅读 recommendation-and-review.md。Agent 必须依据证据推荐最佳方案，说明哪些内容看起来正确、哪些尚未就绪，并明确已证实事项与不确定事项的置信度；只向数据工程师询问会影响业务的审批事项。不要让用户从头开始设计所有内容。
在创建或修改任何图表之前，请阅读 mermaid-diagrams.md。所有图表都必须使用 Mermaid 代码块，实体关系必须使用 Mermaid erDiagram，并且在将阶段标记为完成之前，必须验证每个新增或修改的 Mermaid 图表是否可见且可解析。
在构建 bronze/staging、silver/intermediate 或 gold/marts 之前，请阅读 evidence-driven-dbt-process.md、layer-data-validation.md、cardinality-validation.md、layer-verification-ledger.md 和 assumption-tests.md。每次构建完一层后，都要运行数据仓库验证查询，检查行是否存在、是否符合预期为空、粒度、键、关系、基数、行数变化、行丢失、行倍增、日期覆盖范围、状态/类别分布、度量、映射覆盖率和隐私暴露情况。将每条验证查询保存为可复用的 SQL 证明文件，放在相应阶段的 sql_proofs/ 文件夹下，并注明用途、预期结果、采集到的结果、状态和可运行的 SQL。使用 assumption-tests.md 和 templates/dbt/tests/，将已批准的假设从发现阶段或阶段报告中转化为 dbt 单体测试或通用测试。在层报告中添加 Data Verification Results、SQL Proof Files、Assumption Tests 以及基数/粒度证据，更新 reports/agent/LAYER_VERIFICATION_LEDGER.md、reports/agent/PIPELINE_STATUS.md 和 reports/agent/CONTEXT_TREE.md，向用户分享重要结果；如果本应包含数据的模型为空，或任何验证问题尚未得到解释，则应在进入下一层之前停止。
在分析洞察报告、语义层、展示层和最终交付之前，请阅读 universal-analytics-framework.md、kpi-discovery-framework.md、kpi-definitions.md、kpi-definition-contract.md、metric-verification.md、metric-verification-checklist.md、kpi-reconciliation.md 和 cardinality-validation.md。Agent 必须先构建业务流程、事实、维度、广义度量和情境指标目录，然后提出战略性关键绩效指标，并为每项指标注明业务含义、来源模型、粒度、分子、分母、筛选条件、时间字段、注意事项、验证证据、审批状态、基数证明，以及预期值与实际值的对账结果。在已验证数据所支持的范围内，尽可能创建有用的度量和情境指标，但只有与决策相关、已验证且已获批准的指标才能升级为关键绩效指标。维护 reports/agent/KPI_DEFINITION_CONTRACTS.md 和 reports/agent/METRIC_VERIFICATION_MATRIX.md；这些文件是验收门槛的输入，不是可选的摘要。不要基于含义模糊或尚未完成对账的关键绩效指标创建语义指标或展示层计算。只有在来源到最终值、粒度、基数和 SQL 证明文件均得到验证后，才能信任关键绩效指标。
在最终交付之前，请阅读 advanced-data-engineering-review.md。只有报告涵盖高级审查领域后，才算完成数据管道；这些领域包括源锁定、架构规范、分层验证、粒度、测试、数据质量、隐私、关键绩效指标、语义层、评估器、文档、分析洞察报告、展示层建议和运维。
步骤 0.5 - 确定层名称
阅读 references/dbt-project-layers.md。
对于完整的数据管道，计划交付所有模型层，但每次只构建一个获批的阶段。如果 workflow_phase 限制了范围，则只计划和构建所请求的阶段。
层角色名称和实际文件夹名称不得混用。使用默认层名称时，staging 模型放在 models/bronze/ 中，intermediate 模型放在 models/silver/ 中，事实表、维度表和报表集市放在 models/gold/ 中。除非用户明确将 models/staging/、models/intermediate/ 或 models/marts/ 配置为实际层名称，否则不要创建这些文件夹。
如果提示词、.env 或 project.config.yml 中提供了 layer_names，则使用该配置。否则使用：
- 第 1 层（
stg_*）：bronze - 第 2 层（
int_*）：silver - 第 3 层（
dim_*/fct_*/mart_*）：gold
除非用户要求使用非默认命名约定，或现有项目已经使用了不同的文件夹，否则不要询问层名称。根据 project-naming.md 确定模型文件夹路径的 project_slug。从显式配置、现有获批的 medallion schema、源 schema、项目 slug 或描述性源名称中确定 layer_schema_prefix；只有在最后才使用 domain 作为回退。仅当现有 schema 造成 Agent 无法安全解决的实际冲突时才询问。
根据 materialization-rules.md 编写 dbt_project.yml：
models:
{project.name}:
{layer_1_name}:
+schema: {layer_schema_prefix}_{layer_1_name}
+materialized: view
{layer_2_name}:
+schema: {layer_schema_prefix}_{layer_2_name}
+materialized: view
{layer_3_name}:
+schema: {layer_schema_prefix}_{layer_3_name}
+materialized: table # prod; use view for dev profile
dbt_project_evaluator:
+schema: {layer_schema_prefix}_evaluator
+materialized: table
seeds:
{project.name}:
+schema: {layer_schema_prefix}_seeds
snapshots:
{project.name}:
+schema: {layer_schema_prefix}_snapshots
vars:
dbt_project_evaluator:
staging_folder_name: {layer_1_name}
intermediate_folder_name: {layer_2_name}
marts_folder_name: {layer_3_name}
marts_prefixes: ['fct_', 'dim_', 'mart_']
other_prefixes: ['rpt_']
当 materialization_profile: prod 时，fct_* 模型使用 incremental，并在 SQL 中设置 unique_key。
强制验证
未经成功验证，绝不要将阶段标记为已完成。
在技能仓库内操作时，开始项目工作前先验证技能仓库配置：
python <installed-skill-path>/scripts/validate_config.py --root <installed-skill-path>
cd {project.root}
$dbt = "dbt" # prefer active venv/path; see validation-commands.md for fallbacks
& $dbt debug # init / profile changes only
& $dbt parse --no-partial-parse
& $dbt build --select +path:<layer_folder>
每次构建 bronze/staging、silver/intermediate 或 gold/marts 层后，都运行 layer-data-validation.md。dbt build 通过本身并不能证明该层可用。
独立验证治理
阅读 independent-verification-governance.md。
验证不能只依赖同一个 Agent 或聊天窗口。构建 Agent 将证据写入文件；全新的验证 Agent 从零开始读取仓库、dbt 工件、SQL 证明和报告。
| 层级 | 角色 |
|---|---|
| 构建 Agent | 发现、构建、SQL 证明、报告、状态文件 |
| 独立验证 Agent | agents/dbt-verifier-agent.md - 仅从磁盘进行审计 |
| 验收脚本 | python <installed-skill-path>/scripts/run_acceptance_gate.py --root <project.root> - 确定性通过/失败 |
| CI 门禁 | .github/workflows/dbt_acceptance_gate.yml |
| 人工关注事项看板 | reports/agent/HUMAN_ATTENTION_BOARD.md |
| KPI 差距登记表 | reports/agent/KPI_GAP_REGISTER.md |
| 人工签字确认 | reports/agent/HUMAN_VERIFICATION_GUIDE.md |
MCP 可以提供对仓库、文件、数据库和 dbt 命令的访问，但 MCP 不是验证者。
交互式演示报告存在时，最终交付还要求进行与确定性
scripts/validate_live_report_dom.py 分开的
LLM 引导的 Playwright MCP 审查：
- 运行确定性 Playwright（
validate_live_report_dom.py），覆盖桌面端、平板端和移动端。 - 启动交互式报告的
serve_report.py。 - 在当前 Agent 会话中使用已安装的 Playwright MCP 浏览器工具 （实际执行导航、悬停、点击、截图，而不只是静态解析 HTML）。
- 编写
reports/agent/10_presentation/LLM_PLAYWRIGHT_REVIEW.json/.md并在llm_playwright_evidence/下保存证据。 - 运行
scripts/check_llm_playwright_review.py --root <project.root> --phase final。 - 运行最终严格验收 / 独立验证。
确定性 Playwright 和 LLM Playwright MCP 审查不能相互替代。
LLM 审查通过仅代表技术层面的演示验证，不会将业务审批设为 APPROVED。如果策略要求进行审查，但 Playwright MCP 工具不可用，则将审查标记为 BLOCKED 并停止。
严格的用户交接规则
在 reports/agent/10_presentation/REPORT_HANDOFF_READINESS.json 中的
status=PASS 且 open_allowed=true 之前，绝不要告知用户打开生成的报告。
在验证交接完成之前，不要打印报告 URL、浏览器链接、
open_report.bat / open_report.sh 说明、“打开报告”、“报告已就绪”、
“演示已完成”或演示通过的信息。应改为：
已生成报告工件，但报告尚未准备好打开。 运行时和浏览器验证仍在等待完成。
演示状态：PRESENTATION_GENERATED → 运行时/浏览器/MCP/最终
验证 → VERIFIED_FOR_HANDOFF。仅生成文件、HTTP 200 或冒烟测试均不代表完成。在独立验证和验收证据就绪后，运行
scripts/check_report_handoff_readiness.py --root <project.root> --phase final。启动器必须在启动服务或打开浏览器之前，调用该脚本并传入 --require-pass。生成或验证期间不要调用 webbrowser.open。
最终交付前，运行：
python <installed-skill-path>/scripts/run_acceptance_gate.py --root <project.root>
python <installed-skill-path>/scripts/check_requirement_traceability.py --root <project.root>
python <installed-skill-path>/scripts/check_layer_proof_coverage.py --root <project.root> --phase final
python <installed-skill-path>/scripts/verify_metric_reconciliation.py --root <project.root>
python <installed-skill-path>/scripts/check_llm_playwright_review.py --root <project.root> --phase final
python <installed-skill-path>/scripts/check_report_handoff_readiness.py --root <project.root> --phase final
如果验收门禁返回 FAIL，不要声称项目已完成。生成的项目应包含 reports/agent/ACCEPTANCE_GATE_REPORT.md 和 reports/agent/ACCEPTANCE_GATE_REPORT.json。
当交接就绪状态中的 open_allowed 为 false 时，不要提供打开报告的说明。
构建工作完成后，使用 agents/dbt-verifier-agent.md 运行一个全新的验证 Agent，并编写 reports/agent/INDEPENDENT_VERIFICATION_REPORT.md 以及 .json。独立验证为 FAIL 时，禁止最终交付。
步骤 1 - 完整流水线顺序
完整流水线（默认）：
- 发现与需求 - discovery-requirements.md
- 项目设置与配置 - 仅设置，并在接受发现阶段的需求后自动执行 - bootstrap.md
- 初始化 （如果项目缺失）
- 数据源 - 完整的
packages.yml、dbt deps、代码生成、源 YAML - 暂存层 -> 中间层 -> 数据集市
- 语义层 - 基于数据集市事实表的指标
- 项目评估器 - 确认其路由到
<layer_schema_prefix>_evaluator后，运行dbt build --select package:dbt_project_evaluator - 文档 -
dbt docs generate；在用户要求或适合交互式本地运行时，使用dbt docs serve进行本地查看 - 分析洞察报告 - 在开展演示工作前，发现并记录可信的业务输出、业务流程目录、事实目录、维度目录、关键绩效指标目录、仪表板规范和报告准备情况 - analytics-insight-reporting.md
- 演示层关卡 - 在分析洞察报告之后、最终交付之前必须完成；询问用户是否需要演示层，以及要使用哪种技术。推荐默认使用 Matplotlib，Power BI 作为替代方案。如果用户批准但未指定其他技术，则默认采用 Matplotlib 可刷新的 Web 报告工作流，运行独立的
presentation_layer阶段；按需安装缺失的matplotlib/numpy/pandas前置依赖；将分析洞察目录中的每项推荐度量和关键绩效指标映射到kpi_figure_coverage.md；并在reports/agent/10_presentation/matplotlib/下构建内容丰富的本地浏览器报告，其中包括serve_report.py、report.html、彩色业务选项卡、管理层卡片、图表卡片、洞察说明、异常提示、详细信息区域、实时 SVG/HTML 或浏览器原生图表路由、SQL 验证、open_report.bat，以及通过label_dictionary.md提供的业务友好标签。交付前，使用scripts/validate_local_web_report.py验证实际的本地报告 URL；如果浏览器收到的是空响应，则不得标记为已完成。不得将 PNG 文件用作主要 Web 渲染方式；仅可将其用作可选导出文件或快照。如果用户明确选择 Power BI，则使用 Power BI Desktop 人工连接的模板工作流，创建交接文件夹和清单，等待用户保存并确认已连接的 PBIP，然后仅注入获批的度量和安全的报告元数据。 - Agents 架构 - 在启用且受支持时，于
target/manifest.json存在后，将 dbt 元数据发布到AGENTS.* - 自动化 - 持续集成工作流
- 验收关卡 + 独立验证 - 运行
python <installed-skill-path>/scripts/run_acceptance_gate.py --root <project.root>，然后按照 agents/dbt-verifier-agent.md 启动全新的验证 Agent - 高级评审、验收 + 最终摘要 - advanced-data-engineering-review.md、acceptance-checklist.md、final-delivery.md
完成项目设置和配置后，每个阶段都应遵循以下流程：针对阶段进行发现 -> Agent 建议 -> 数据工程师决策检查 -> 编写 Markdown 计划 -> 请求批准 -> 实施 -> 解析/构建 -> 数据仓库数据验证查询 -> 在托管 reports 文件夹中编写包含验证结果的阶段报告 -> 更新报告索引 -> 更新上下文树 -> 编写
reports/agent/NEXT_PHASE_PROMPT.md-> 发送一条普通助手消息，其中包含可见的 Markdown 聊天控制面板摘要，说明已完成的工作和下一步计划 -> 在该聊天消息中粘贴下一阶段提示词原文 -> 在可用时请求对所显示提示词进行交互式批准 -> 请求提交。仅当已配置非本地 GitHub 仓库或用户要求推送时，才请求推送。原生问题卡片本身并不足够；必须在可点击的批准问题之前，立即单独发送一条包含可见聊天摘要的助手消息。
步骤 2 - 数据源
阅读 packages-and-sources.md、source-profiling.md、schema-isolation.md 和 dbt-packages-and-skills.md。
packages.yml 中的五个必需包：codegen、dbt_utils、dbt_expectations、dbt_project_evaluator 和 audit_helper。使用 Codegen 生成数据源。除非明确提供，否则从 source.schema 推导 source.name；仅当数据源架构为通用名称时，才将域名作为最后的备用选项。数据源 YAML 只能写入 models/sources/，不得写入 bronze、silver 或 gold 层文件夹。不要为了消除评估器关于数据源目录的警告而将数据源 YAML 移入 bronze/staging；应记录可接受的例外情况，或在更改结构前征求同意。生成后，将配置的 source.schema 添加到数据源 YAML。在 staging 之前，分析行数、候选键、关系、重要日期、度量以及状态/代码字段。
步骤 3 - 第 1 层（staging）
阅读 staging-spec.md 和 layer-data-validation.md。仅使用 source()。不包含业务 KPI。构建后，根据源表验证 staging 行数，并分享结果。
步骤 4 - 第 2 层（intermediate）
阅读 intermediate-spec.md、mapping-seeds.md、layer-data-validation.md 和 cardinality-validation.md。仅使用 ref()。当 project_rules 包含手动映射或代码转换时，使用映射 seed 或参考表。构建后，验证行是否存在、粒度、联接、基数、行损失和行数膨胀。
步骤 5 - 第 3 层（数据集市 / 星型模式）
阅读 marts-spec.md、gold-dimension-completeness.md、evidence-driven-dbt-process.md、layer-data-validation.md、cardinality-validation.md、kpi-definitions.md、kpi-definition-contract.md、metric-verification.md、metric-verification-checklist.md 和 kpi-reconciliation.md。仅使用 ref()。根据分析过的源数据粒度和用户需求，构建适合相应领域的事实表、维度表和报告数据集市。除非明确标记为 BLOCKED/DEFERRED 并提供证明，否则只有事实表的 Gold 层是不完整的。优先采用保护隐私的维度，而不是删除所有维度。构建完成后，在上游存在数据时，验证每个事实表、维度表和报告数据集市都有数据；将意外为空的 Gold 模型视为阻塞项。在将关键绩效指标纳入 Gold 数据集市或语义指标之前，明确地定义并核对这些指标。宣布 Gold 层完整之前，运行 scripts/check_gold_star_shape.py --root <project.root>。
步骤 5b - 语义层
阅读 semantic-layer-spec.md、kpi-definitions.md、kpi-definition-contract.md、metric-verification.md、metric-verification-checklist.md、kpi-reconciliation.md 和 cardinality-validation.md。使用 building-dbt-semantic-layer 进行组合。适用于 dbt 1.10.x 的旧版规范。仅根据经过批准、受支持且已核对，并且粒度和基数均已验证的关键绩效指标定义创建语义指标。
步骤 5c - 项目评估器
阅读 project-evaluator.md。运行评估器之前，确认 dbt_project.yml 将 models: dbt_project_evaluator: +schema 路由到 <layer_schema_prefix>_evaluator，并为当前启用的 Medallion 文件夹名称设置评估器变量。不要让评估器包的表在 source_schema 中构建。查询评估器结果表时，选择特定版本的字段之前，先检查可用列。
& $dbt build --select package:dbt_project_evaluator
步骤 6 - 文档
阅读 documentation.md。运行 dbt docs generate。仅将 dbt docs serve 用作非阻塞的本地查看步骤，并在启动后报告 URL。在完整流水线中，不要在完成文档后就标记交付完成。继续进行分析洞察报告。
步骤 6a - 分析洞察报告
阅读 analytics-insight-reporting.md、report-artifact-organization.md、evidence-driven-dbt-process.md、universal-analytics-framework.md、kpi-discovery-framework.md、kpi-definition-contract.md、metric-verification-checklist.md、kpi-reconciliation.md、cardinality-validation.md、reporting-standards.md、kpi-definitions.md、metric-verification.md 和 docs/kpi_proof_standards.md。进入此阶段之前，先编写或更新 AGENT_PLAN.md，并等待批准。首先对表进行分类，然后从已验证的数据集市和语义指标中，发现并记录最有用、面向业务的输出。按照 report-artifact-organization.md 的要求，在受管理的文件夹中生成分析洞察和关键绩效指标交付物，包括 business_process_catalog.md、fact_catalog.md、dimension_catalog.md、09_analytics_insights/、09_analytics_insights/kpis/、09_analytics_insights/kpis/sql_proofs/，以及根目录中的 REPORT_INDEX.md、HUMAN_VERIFICATION_GUIDE.md、KPI_DEFINITION_CONTRACTS.md 和 METRIC_VERIFICATION_MATRIX.md。此阶段不要创建演示文稿类交付物。
Analytics 洞察报告硬性规则
- 不要编造洞察。
- 不要只因为存在数据就建议制作图表。
- 每项度量、指标、关键绩效指标和报告候选项都必须映射到经过验证的数据集市或语义指标。
- 明确区分层级：度量是原始计数、求和或平均值；指标加入时间、维度或比率背景；关键绩效指标则是与目标、阈值、指标值、风险或管理评审相关、能为决策提供依据的指标。
- 在缩小范围以确定战略关键绩效指标之前，先生成业务流程、事实、维度、广义度量和指标目录。
- 每个可视化都必须回答一个真实的业务问题。
- 未经批准，不得暴露敏感字段。
- 明确区分可信输出与不确定或暂缓的输出。
- 优先采用实用、简洁、便于业务理解的报告，而不是过多的技术表格。
- 不要硬编码某个领域的关键绩效指标、页面名称或示例值。
- 没有证据时，不要编造目标、基准、归因或建议。
- 不要将
5 key performance indicators per table应用于维度表、桥接表、参考表或审计表。 - 除非每个目录数字都附有对应的
sql_proofs/*.sql文件，否则不要发布这些数字，详见 docs/kpi_proof_standards.md。 - 最大化的含义是：在经过验证的数据支持下，尽可能提供有用的业务洞察，包括业务领域、流程、事实、维度、度量、指标、战略关键绩效指标、报告页面，以及带有证明状态的待处理机会，而不是追求仪表板数量最多或任意的目录行数。
- 不要以固定的 50+ 或 100+ 度量或指标数量为优化目标。应针对每个经过验证的业务流程实现完整的分析覆盖。当每项重要事实都具备适当的数量、价值、状态、时间、质量、细分、异常和生命周期分析，且每项已发布结果都回答了有文档记录的业务或工程问题时，覆盖才算完整。请阅读 analytics-product-completeness.md 和 reporting-coverage-requirements.md。展示前运行
python <skill>/scripts/check_analytics_coverage.py --root <project.root>及相关完整性检查脚本。 - 分别维护业务度量、情境指标、战略 KPI、数据质量指标和数据管道健康指标目录。不要在面向管理层的业务页面中放入技术模型行数。
- 创建
analytics_coverage_matrix.md、fact_coverage_contracts.md、model_classification.md和business_process_catalog.md，将其作为主要门槛。 - 根据此数据仓库的证据构建一致性维度（实体、日期、状态/标签及其他现有维度）；分类图表轴为空属于展示失败。不要编造行业特有的维度类型。
- 展示层的
kpi_figure_coverage.md必须将已发布的业务指标/KPI 标记为RENDERED、BLOCKED或DEFERRED。完整的原始字典可放在指标字典页面中。 - 实时 Matplotlib 报告的所有业务页面都必须使用业务显示名称和格式化后的值。可以包含 All Measures / All Metrics 等字典页面，但不能将其作为 snake_case ID / 原始浮点数的 SQL 转储。应根据发现的流程添加基于流程的页面，并在有数据支持时添加 Dimensions / Data Quality / Pipeline Health 页面。请参阅规则 5b–5c 和 report-page-contract.md。
- 展示层的
sql_verification/必须包含已执行的证明及捕获的结果，用于证明董事会层面的度量/指标和图表；还必须包含_proof_index.md，将标记为 RENDERED 的项目映射到相应证明。 - 对每张标记为
RENDERED的图表运行实时数据仓库 SQL，并证明报告刷新路径有效；仅 HTML 外壳返回 HTTP 200 并不代表完成。
生产分析产品完整性
分析完整性取决于对业务和工程的覆盖情况，而非目录行数的固定指标。
在分析洞察报告通过之前：
- 对每个纳入范围的模型进行分类（参见 universal-model-classification.md）。
- 创建
analytics_coverage_matrix.md，将每个重要业务流程映射到事实、维度、度量、指标、KPI、时间分析、细分、质量检查、对账、报告页和状态。 - 对每个已验证事实评估其数量、价值／数量／时长、状态／生命周期、时间趋势／周期比较、维度细分、数据质量、异常／账龄、源数据对账，以及支持的业务问题。
- 分别维护业务度量、业务背景指标、战略 KPI、数据质量指标和管道健康指标目录。
- 不要将技术模型行数、空值检查、孤立记录数和管道统计数据放入高管业务页面。
- 每个已发布的 KPI 都必须包含业务问题、所支持的决策、指标异常时的行动、负责人、定义、公式、粒度／计数键、纳入／排除的记录、日期字段／角色、维度、单位／货币／格式、聚合行为、目标或未定义目标、期望方向、验证来源、对账容差、SQL 证明，以及审批／置信度状态。
- 每个战略 KPI 都必须根据 time-intelligence-standard.md 评估时间智能；仅实现日期覆盖范围所支持的比较。
- 每个报告页都必须根据 report-page-contract.md 声明页面契约。
- 以下情况均视为呈现失败：使用原始技术名称、空白标签、原始小数比率、未标注的货币、没有周期的 KPI、不受支持的可加总总计、高管页面上的已删除记录定义、作为业务 KPI 的技术行数，以及缺少比较／问题／说明的图表。
- SQL 执行不足以完成业务验证。关键 KPI 必须经过对账并获得业务负责人批准，或明确标记为待审批。
完成此阶段后，运行 python <installed-skill-path>/scripts/validate_kpi_proofs.py --root <project.root> 和 python <installed-skill-path>/scripts/verify_metric_reconciliation.py --root <project.root>，然后在阶段报告中记录结果。对于表范围广泛的中型项目，采用与项目规模相符的目标，或在 insight_backlog.md 中记录每项未达标之处。更新 reports/agent/09_analytics_insights/analytics_insight_reporting_report.md、reports/agent/PIPELINE_STATUS.md 和 reports/agent/CONTEXT_TREE.md，然后在呈现层关卡处停止，除非用户已批准开展呈现工作。
第 6b 步 - 呈现层建议
阅读 presentation-layer.md、matplotlib-presentation-layer.md、evidence-driven-dbt-process.md、universal-analytics-framework.md、analytics-insight-reporting.md、reporting-standards.md、kpi-definitions.md、kpi-definition-contract.md、metric-verification.md 和 metric-verification-checklist.md。如果 Power BI 获得批准，还要阅读 powerbi-template.md、powerbi-thin-model-template.md、powerbi-kpi-dax-tooling.md、powerbi-official-docs.md 和 powerbi-pbip-desktop-requirements.md。完成分析洞察报告后，使用 dashboard_spec.md、business_process_catalog.md、fact_catalog.md、dimension_catalog.md、kpi_catalog.md、KPI_DEFINITION_CONTRACTS.md、METRIC_VERIFICATION_MATRIX.md、reporting_catalog.md、insight_backlog.md、reporting_readiness_scorecard.md 和 analytics_insight_report.md 作为范围契约，推荐最佳的展示层方案。在最终交付完成之前，先通过简明的证据摘要和可用时的原生可点击选项询问用户对展示层的决定：Yes - build Matplotlib refreshable web report (recommended)、Yes - prepare Power BI Desktop template handoff、No presentation layer - complete final delivery now 和 Tell me what to change first。如果用户批准展示层但未指定其他技术，默认采用 Matplotlib 可刷新的网页报告工作流：必要时安装缺少的 matplotlib、numpy 和 pandas；将每个推荐的度量、指标和关键绩效指标映射到 kpi_figure_coverage.md；将经过 SQL 验证的图表渲染为实时 Matplotlib SVG/HTML 端点，或渲染为基于刷新的 JSON 的已批准浏览器原生图表；并在 reports/agent/10_presentation/matplotlib/ 下使用 serve_report.py、report.html、彩色业务选项卡、分类的 report_pages/ 模块、管理层卡片、图表卡片、异常提示、详情部分、刷新时间戳/控件、打开启动器以及面向业务的标签，构建精美的本地浏览器报告。PNG/SVG 文件可作为可选导出文件或快照；不要将 PNG 用作主要网页渲染方式。如果用户明确选择 Power BI，则使用由用户连接数据的 Desktop 模板工作流：创建 Power BI 输出文件夹，编写表、关系、存储模式和度量值表检查清单，要求用户在 Power BI Desktop 中连接已批准的 gold 或语义数据，将 .pbip 保存到指定路径/文件名，并在进行任何 PBIP 编辑之前确认该路径。确认后，Agent 只能向已批准的度量值表中注入已批准的 DAX 度量、说明、格式字符串、显示文件夹和安全注释，然后进行验证。除非用户明确批准生成 PBIP 模式，否则不得自动生成完整的 PBIP 语义模型、源分区、Power Query M、关系或可视化内容。若需要进行 Desktop 验证，Power BI 验证必须使用 scripts/detect_powerbi_desktop.py 检测并记录目标 Desktop 版本；在有版本信息时运行适配版本的 scripts/validate_powerbi_pbip.py；并将 NewerLinguisticSchemaVersion 等版本不兼容错误视为阻塞问题。Power BI 度量必须来自 KPI_DEFINITION_CONTRACTS.md、METRIC_VERIFICATION_MATRIX.md、kpi_catalog.md、经过验证的语义指标或用户明确批准的需求；不得臆造仅供 Power BI 使用的关键绩效指标或业务逻辑。若可访问互联网且 PBIP 结构不确定，应先查阅 Microsoft Learn 官方 Power BI 项目文档，再决定结构。不得擅自改用本地 PBIP（例如 IHMS）；只有在向用户展示确切路径及将复用的内容后，才能将本地 PBIP 用作用户批准的结构参考。除非用户明确要求覆盖，否则展示层不得创建与分析洞察输出相矛盾的页面、关键绩效指标、可视化内容或业务范围。若 TMDL 在根目录中包含裸 M 步骤（例如 AddedKey = Table.AddColumn(...)）、未通过精确版本验证的区域设置/语言架构产物，或语言元数据内容类型不匹配（例如 XML 类型元数据中包含 JSON { "Version": "1.0.0" }），则不得交付 Power BI。未经批准，不得构建仪表板、报告、幻灯片、笔记本或商业智能产物。
对于完整流水线的最终交付，展示层建议和用户决策关卡是必需的。如果用户尚未回答展示问题，请将状态设为 Analytics insight reporting complete - presentation decision pending，而不是 Delivery complete。如果无法给出建议，请将其标记为 BLOCKED 或 SKIPPED，并在最终报告、流水线状态、上下文树和最终回复中提供证据。
Step 6c - 人工审查
阅读 human-review.md。在每一层完成后，总结业务假设、数据质量说明和待决事项。如果业务含义、粒度、映射、指标或敏感字段不明确，请征求批准。
此审查在实施后进行。phase-plan-approval.md 中的阶段计划审批在实施前进行。
Step 7 - Git
阅读 git-workflow.md。每次提交或推送前都要征求许可。
Step 8 - 持续集成、持续交付和 Agents Schema (按需执行)
在生成文档后，或任何会生成 target/manifest.json 的步骤后，使用 Agents Schema。编辑时不要将其视为 dbt 项目文件的替代品；应将其用作仓库侧元数据层，帮助 Agent 回答问题并理解构建的模型。
Step 9 - 最终交付摘要
在将任何完整流水线或请求的阶段标记为完成前，阅读 advanced-data-engineering-review.md、phase-completion-report.md、report-artifact-organization.md、reporting-standards.md、context-tree.md、evidence-driven-dbt-process.md、independent-verification-governance.md 和 final-delivery.md。
运行 python <installed-skill-path>/scripts/run_acceptance_gate.py --root <project.root> 并记录结果。生成的 dbt 项目无需包含技能的 scripts/ 文件夹即可运行此验收关卡；请使用已安装或已准备好的技能文件夹中的脚本，对项目根目录执行检查。请求完整交付时，还要按照 agents/dbt-verifier-agent.md 的要求运行或委派一次新的独立验证，并记录 reports/agent/INDEPENDENT_VERIFICATION_REPORT.md。
通用迭代摘要规则
每次迭代完成或受阻后，在结束回合或请求批准前，都要先在聊天窗格中输出面向用户的常规 Markdown 摘要。此要求适用于发现、项目设置与配置、阶段计划、源、青铜层/暂存层、白银层/中间层、黄金层/数据集市、语义层、项目评估器、文档、分析洞察报告、展示层决策、展示制品、持续集成、Agents Schema、修复、验证专用运行、提交、推送、回滚、受阻状态和最终交付。
只要存在匹配模板，每份生成的阶段报告、层报告、SQL 证明索引、SQL 证明文件、分析目录、展示报告、运维报告和根控制文件，都必须使用 templates/reports/ 下的规范模板。模板提供稳定的结构；Agent 必须用针对相应阶段的证据替换占位符，并在需要时保留各个章节，将其标记为 None、Not applicable、Skipped 或 Blocked。如果存在模板，不要自行设计报告结构。
阶段／检查点摘要请使用 phase-completion-report.md，任务／最终摘要请使用 final-delivery.md。任何一轮结束时，都不得只给出文件路径、提交哈希、可点击的审批控件、“完成”、“请看报告”、原生问题卡片、文件差异或隐藏的报告引用。可以使用原生／可点击的审批问题，但前提是普通聊天摘要已说明发生了什么，以及审批将允许什么操作，并且该摘要清晰显示在问题正上方。如果运行环境无法保证这一显示顺序，请使用文本备用方案，不要使用可点击的审批控件。
聊天摘要必须说明：
- 当前检查点和状态。
- 已完成、构建、变更或验证的内容。
- 验证／证明结果，包括警告、失败、跳过的检查或阻塞项。
- 已变更的文件或已编写的报告。
- 已包含的范围和未包含／已延期的范围。
- 重要说明、假设、待定决策和风险。
- 必须重复的部分：仍受阻——修复这些问题，否则这些 KPI 会继续缺失，以及 Agent 建议（接受或否决）——对于 Attention Board／Gap Register 中每一条未解决记录，说明 Agent 的具体建议、原因、接受后可解锁的 KPI，并询问“接受／否决／延期”。即使相同警告已在先前检查点中显示，也必须包含此部分。如果没有未解决记录，请写
No open KPI gaps at this checkpoint. - 当前可信的 KPI 与仍受阻的 KPI 列表（依据
KPI_GAP_REGISTER.md／已批准的契约）。 - 建议的下一步，以及审批具体将允许什么操作——并说明，除非接受或否决对应的未解决建议，否则下一个“Yes”不会解锁受阻的 KPI。
对于建模或 KPI 决策，不要在没有推荐默认选项的情况下提出开放式问题，例如“我们该怎么做？”。编写检查点聊天摘要前，请阅读 recommendation-and-review.md、kpi-gap-and-stakeholder-warnings.md 和 stakeholder-layer-and-presentation-guide.md。
完成任何请求的任务、完整流水线、阶段、修复、文档更新、演示材料、提交、推送或验证运行后，都要使用 final-delivery.md 在聊天面板中给出完整摘要。
始终以面向用户的摘要结束：先简短说明，再提供有用的详细信息：
- 简短摘要：构建了什么，以及是否通过。
- 结果：profile、domain、source、schemas、layers，以及已知的行数。
- 按层创建或变更的模型。
- 验证：dbt debug、parse、build、文档和评估器结果。
- 数据质量说明和假设。
- Git、持续集成和 Agents Schema 状态。
- 分析洞察报告状态，以及报告设计文件的链接。
- 表示层建议状态。
- 高级数据工程审查状态。
- 待定决策和建议的后续操作。
第一部分应简洁明了，让新用户能在一分钟内读懂。
故障处理
每当命令挂起、验证反复失败、缺少必需输入或 Agent 无法安全决策时，请阅读 stuck-recovery.md。
- 根据构建输出确定失败的模型／测试。
- 仅修复当前层，除非上游存在问题。
- 重新运行
dbt build --select +path:<layer_path>。 - 对于不明确的错误，请使用
troubleshooting-dbt-job-errors。 - 如果问题仍未解决，请停止并询问，同时提供当前阶段、最后执行的命令、错误信息、变更的文件、
git status和具体选项。
回滚和重做
当必须撤销已完成的阶段、以不同方式重新构建，或因粒度、映射、隐私、指标、命名、来源或呈现决策发生变化而将其标记为过时时，请阅读 phase-rollback.md。不要悄悄删除文件、删除数仓对象，或让 PIPELINE_STATUS.md / CONTEXT_TREE.md 仍声称已回滚的阶段已完成。编写回滚计划；如果涉及数仓对象或共享报告，请征求批准；更新状态/上下文文件，然后返回常规阶段计划工作流。
每个阶段结束后的下一阶段提示词
每次检查点完成或受阻后，请阅读 phase-completion-report.md、report-artifact-organization.md、human-attention-reporting.md、recommendation-and-review.md、kpi-gap-and-stakeholder-warnings.md、stakeholder-layer-and-presentation-guide.md 和 next-phase-prompt.md。更新 reports/agent/HUMAN_ATTENTION_BOARD.md，其中仅包含尚未解决的人为决策、具体的 Agent 建议（而非只提问题）、这些决策对 KPI 的影响，以及后续阶段的条件。更新 reports/agent/KPI_GAP_REGISTER.md，记录仍因缺少数据、定义不明确、隐私、单位、映射、维度或审批而受阻但可实现的 KPI，并在每个尚未解决的条目中列出 Agent 建议 / 原因 / 被否决的替代方案，以及不可能实现或超出范围的 KPI。编写或更新 reports/agent/NEXT_PHASE_PROMPT.md，其中包含推荐的下一阶段的确切提示词；编写或更新 reports/agent/REPORT_INDEX.md；然后发送一条常规助手消息，在征求批准前先显示 Markdown 聊天控制面板摘要。聊天摘要必须与 Attention Board 中尚未解决的条目保持一致；即使用户之前看过，也必须再次提醒 仍然受阻 和 Agent 建议（接受或覆盖）；说明已完成的内容、通过/有警告/失败的内容、推荐的下一步、下一阶段将包含和不包含的内容、如何批准，并在聊天中粘贴确切的下一阶段提示词。不要在聊天中粘贴完整清单或基数矩阵。不要只说提示词在 NEXT_PHASE_PROMPT.md 中。不要只显示原生问题卡片、审批控件或文件差异；面向用户的摘要必须作为单独的助手消息显示在问题正上方，以免运行看起来像是停止或被放弃。不要仅在 request_user_input 或原生问题正文中放入完整摘要。仅当运行时能够确保常规摘要直接显示在问题正上方时，才通过原生交互式问题征求批准。在 Codex 中，仅当能保证摘要按此顺序可见时，才使用 request_user_input 或当前的原生问题/审批界面；工具问题应保持简短。建议的问题：你要我按原样运行这个下一阶段提示词吗？ 建议选项：是，运行此提示词。其他选项：告诉我需要修改什么 和 暂不。如果无法使用交互式问题，或无法确保摘要直接显示在问题正上方，请使用文本回退方案：你要我按原样运行这个下一阶段提示词吗？回复“是”以继续，或告诉我需要修改什么。
当用户批准所显示的下一阶段提示词时，不要单独运行 NEXT_PHASE_PROMPT.md。首先从 next-phase-prompt.md 重新加载已批准的下一阶段上下文包：SKILL.md、prompt.md、阶段专属参考资料、AGENT_PLAN.md、reports/agent/PIPELINE_STATUS.md、reports/agent/CONTEXT_TREE.md、reports/agent/00_discovery/requirements.md（如果存在）、仅当规范文件不存在时才使用旧版 reports/agent/requirements.md、最新的相关阶段报告、reports/agent/NEXT_PHASE_PROMPT.md，以及项目知识文件（如果存在）。然后仅执行已批准的下一阶段。
诸如 Yes、Proceed、Approved、Continue、Run this prompt、Looks good 或 Go ahead 这样的自然语言批准回复，仅表示批准当前检查点所显示的下一阶段提示词。沉默绝不代表批准。如果用户更改范围、模型、关键绩效指标、隐私、架构、验证、物化或文件，则更新 AGENT_PLAN.md 和 reports/agent/NEXT_PHASE_PROMPT.md，展示修订后的提示词，并在继续前再次征求批准。
摘要模板（每个阶段结束时）
1. Plan approval status
2. Files created / updated
3. Grain / business logic
4. Data-engineering decisions and evidence
5. Agent recommendation, what looks right, what is not ready, and confidence
6. Tests / documentation added
7. Assumptions used
8. dbt debug, parse, build, and documentation results
9. Mermaid diagram verification status when diagrams were added or changed
10. Phase report path and status
11. Context tree update status
12. Next-phase prompt path and exact interactive approval question or fallback text question
13. Commit status (asked / skipped / completed / pushed to GitHub)
最终回复请使用 final-delivery.md，不要只使用阶段模板。
歧义处理 - 提示词覆盖项
workflow_phase:init | sources | staging | intermediate | marts | semantic_layer | project_evaluator | docs | analytics_insight_reporting | presentation_layer | ci | agents_schemadbt_profile_name:~/.dbt/profiles.yml中的 dbt 配置键；缺失或不明确时询问dbt_project_name:可选的显式 dbt 项目名称；否则根据源/项目信号推导dbt_project_root:可选的显式文件夹名称；否则使用dbt_project_nameproject_slug:可选的显式模型文件夹标识；否则根据源/项目信号推导domain:业务/领域背景；缺失时询问，但不要直接将其用作文件夹/架构前缀business_description:可选的普通英语业务/客户背景，用于分析洞察报告和演示规划source_schema:要通过 codegen 检查的数据仓库架构；缺失时询问source_name:可选的 dbt 源名称覆盖项；缺失时根据source_schema推导layer_schema_prefix:物理输出架构的前缀；除非显式提供，否则根据 schema-isolation.md 推导project_rules:可选的字段映射、连接、指标、排除项、隐私规则、命名规则和特殊说明。严格应用；不明确时询问。auto_bootstrap:true（默认）| false（用于自动项目设置的向后兼容配置键；避免在面向普通用户的提示词中显示此项）auto_agents_schema:true | false（本地/不支持的适配器默认 false；Snowflake、Databricks 或 BigQuery 可启用）auto_install_dbt_skills:true（默认）| falselayer_names:layer_1、layer_2、layer_3（默认：bronze、silver、gold）domain:（默认值来自project.config.yml）github_repo_name:可选的仓库标识；仅在用户要求推送且无法推断仓库时询问github_repo:完整 URL 或owner/repo（可选覆盖项）push_to_github:true | false（local-only默认 false，否则推送前询问）commit:ask | auto_yes | skip_allmaterialization_profile:prod | devregenerate_sources:true | false
一次性提示词
prompt.md - agent-context-prompt.md
不要将此技能用于
- 除非用户批准单独的
presentation_layer或 BI 交接阶段，否则不要直接构建 Power BI 仪表板、报告、幻灯片、笔记本或商业智能工件。只有在数据集市、语义层、评估器、文档和验证全部完成后，此技能才可记录分析洞察报告的输出；只有在完成分析洞察报告且获得用户批准后，才可准备适用于 Power BI 的语义输出、DAX 度量草稿、PBIP/TMDL 交接文件或经批准的 PBIP/TMDL 工件。 - 临时业务问题 ->
answering-natural-language-questions-with-dbt（直接使用该技能）