企业官网建设流程全解析

Lightdash Learn 应用内课程优先级：九大实战演练的规划、交付与验证指南

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

导读

本文围绕 Lightdash 仓库中 docs/learn/walkthrough-priorities.md 所定义的Learn 应用内课程（In-app curriculum）优先级清单展开，说明 Lightdash 如何以「真实产品操作 + 一次性训练副本」的方式，通过九条已生成的实战演练（walkthrough）覆盖 9 个权限 scope，并配套交付标准、验证机制与后续排期。读完本文，你将掌握这九条演练各自要达成的可观察结果、data-tour-*标记驱动的生成式课程机制，以及如何在 CI、scope-tour smoke 与权限测试三层保障下维护这些课程不失效。

背景：课程交付策略的一次方向性调整

2026-09-09 的决策：只保留有应用内路径的 scope

walkthrough-priorities.md记录了 Lightdash 团队在 2026-09-09 由 Josh 确认的课程方向：优先覆盖已经具备应用内（in-app）操作路径的 scope。Learn 的使命是让学习者在一次性的训练副本里通过真实产品交互学会某个权限 scope，因此「阅读即认可」不再算作一个动手型 scope 的完成结果。

这一决策直接反映在课程形态上：

• 九条课程条目改用生成式应用内演练（generated in-app walkthroughs），其中七条是新增路径，两条是复用既有演练；
• 其余 21 条 scope 条目统一显示Coming Soon；
• 阅读式交付（reading delivery）已于 2026-09-10 移除。

从源码侧可以印证这一「未实现交互式交付即归为 Coming Soon」的机制：packages/frontend/src/features/learn/comingSoon.ts 中维护了COMING_SOON_SCOPES常量清单（12 个 embedding、3 个 content-as-code、2 个 promotion、validation、analytics、2 个 agent-document 类 scope），并在 scripts/scope-tours/coverage.ts 的SCOPE_DISPOSITIONS中为这些 scope 统一标记了status: 'coming-soon'，其 reason 明确写着：「Interactive delivery is not implemented. Reading lessons were removed by the product decision of 2026-09-10; future formats will be separate work.」

九条优先级课程清单（完整继承）

下表是原文档的核心内容：每一条课程所对应的权限 scope、要完成的开发工作，以及判定完成的必需结果（Required result）。注意其中几个条目成对出现（顺序号相同），因为它们的教学对象是同一功能的不同权限侧面。

可以看到，「必需结果」反复强调两件事：一是必须观察到实际产物（保存的 chart、持久化的列配置、恢复的 chart），二是仅做创建/验证/解释不算完成——这正是 2026-09-09 方向决策（动手才算数）在每一条目上的具体落地。

与 scope 注册表的对应

上述 scope 都来自 Lightdash 的权限 scope 注册表（getTrainingProjectScopes()，位于 packages/common/src/authorization/roleToScopeMapping.ts）。训练副本授予的是「项目管理员 scope 列表去掉组织级 scope 与排除项」之后的集合，而课程库（packages/frontend/src/features/learn/catalogue.ts）会为每个 trainee scope 生成一个模块：标题取自 scope 注册表的描述、分组取自注册表分组、只有存在生成演练时模块才可用。这些优先级条目正是「已有生成演练」的那一批，与generated.ts中的SCOPE_TOURS一一对应。

生成式演练：课程如何从产品自身长出来

在深入九条课程的交付细节之前，需要理解这些课程的制作方式。Lightdash 的 walkthrough 不是手工编写的步骤列表，而是从产品组件上的data-tour-*标记与文档仓库的句子中构建出来的数据。核心入口在 scripts/scope-tours/generate.ts：

• 每个被某 scope 解锁的控制，在权限检查旁同时携带data-tour-scope（所属 scope）、data-tour-step（步序）、data-tour-route（所在页面）、data-tour-label（一句话操作说明）、data-tour-docs（正文引用的文档章节）等标记；
• 生成器读取这些标记和文档仓库（LIGHTDASH_DOCS_DIR，默认指向../mintlify-docs），写出 packages/frontend/src/features/scopeTours/generated.ts：每个 scope 一个 tour，步骤正文取自被引用的文档句子，链接仅允许指向文档站点；
• 课程顺序由pnpm scope-tours:order生成到curriculum.ts；
• 完整的标记词汇表（含data-tour-via路径、data-tour-then后续点击、data-tour-return返回路径、data-tour-suggest输入建议、data-tour-busy等待面、data-tour-result结果面等）记录在 scripts/scope-tours/generate.ts 文件头部的注释中。

这种「从产品与文档生成课程」的方式带来一个关键推论：标题来自 scope 注册表，解释文字来自标记引用的文档句子，构建时没有任何内容是被凭空发明的（"Nothing is invented at build time"）。九条优先级课程同样遵循这一机制，任何一条课程在库中的标题、文案、步骤全部可由标记与文档推导出来。

优先级条目如何复用既有演练

manage:CustomSql与view:ContentVerification两条被标注为「复用」——前者复用 CS-224 的 SQL Runner 保存流程，后者复用或扩展 CS-220 的验证指示器教学。复用不是简单的拷贝：交付标准要求「scope 映射只有在某条 tour 的操作与可观察结果确实能教会该 scope 时才能复用它」。这正是data-tour-covers标记存在的意义：一个交互动作若同时教多个 scope，可以用该标记声明额外覆盖的 scope（逗号/空格分隔、不允许重复），从而让一次生成服务于多条课程条目。

交付标准（Delivery criteria）

原文档定义了五条硬性交付标准，它们共同约束九条课程的开发方式：

1. 优先复用既有控件与锚点，而非新增。新增标记之前先看现有产品能否表达该步骤；scope 映射只有在某条 tour 的动作与可观察结果确实能教该 scope 时才允许复用。
2. 步骤从前端标记生成，正文来自规范文档，并遵循 skills/developing-in-lightdash 仓库技能中add-scope-walkthrough的配方（即 skills/developing-in-lightdash/SKILL.md 体系下新增演练的完整流程）。
3. 使用既有受训者权限。若发现缺路由、缺 feature flag、缺 fixture 或控件不可达，则是一个需要显式调查的依赖项，而不是绕过权限的理由。
4. 在全新的训练副本中用录制账号验证每条流程，包括可见结果、与共享源的隔离、以及副本清理。
5. 未支持的模块显示 Coming Soon，内容呈现与已验证的动手完成在覆盖率与报表中严格区分。

第 4 点中的「录制账号」指的是walkthrough-recorder@lightdash.com专用账号——用专用账号做 smoke 运行，是为了保证 smoke 不会误删某个正在使用的真人训练副本。

从源码看，第 1、2 点分别由两个工具强制：

• 生成检查器scripts/scope-tours/check.ts 会验证路径选择器是否能在前端解析到带data-tour-hint的锚点、文档锚点是否存在、句子范围是否越界、步骤标题是否超过 12 个词、正文是否超过 60 个词、输入型步骤是否带data-tour-suggest、路由是否属于已知项目路由、最后一个步骤是否为「观察型（Got it）」而非点击型等；
• 覆盖率审计scripts/scope-tours/coverage.ts 的auditCoverage会把训练 scope 全集与当前生成的 tours 做比对，输出generated/pending/coming-soon/excluded/unclassified等分类，确保每个训练副本授予的权限要么有演练、要么有显式处置（Coming Soon 或 excluded + CS 工单），任何未分类 scope 都会让审计不通过。

验证：三层防线

第一层：生成检查与覆盖率审计（CI）

CI 中的Scope walkthrough checks（见 scripts/scope-tours/check.ts 的检查规则清单）会在每次触及packages/frontend/src的 PR 上运行，捕获结构性破坏——被标记的控件被删、改名、丢失属性，或点击路径指向了不存在的锚点。与此同时，覆盖率审计的失败输出会明确指出问题属于哪一类：

• unclassified：某权限既无演练也无处置——通常是新增了 scope 或删除了某演练的标记；
• staleDispositions：已列出的 scope 现在有了演练或已不存在，应删除处置条目；
• pending/related：已登记但尚未解决的缺口，会阻塞发布。

注意 CI 有一个设计上的边界：结构性破坏能被抓到，行为性破坏抓不到。行为性破坏是指标记都在、但学习者无法通过点击高亮控件到达目标（新增了弹窗、控件被移到另一次点击之后、控件在数据加载前处于禁用态、只在某些配置下渲染）。这类问题只有第二层防线能发现。

第二层：scope-tour smoke 驱动（手工运行）

scripts/scope-tours/smoke.ts 会以学习者身份在运行中的实例上启动每条演练，并只点击演练高亮的控件（高亮环内的控件或卡片自带的按钮）来完成它。一个演练在以下情况判失败：某步骤超时无进展、Got it 打不开完成对话框、Back to library 没有落在共享训练项目的课程库、scope 不在学习者副本授予的 trainee 集合里、或者学习者在真实项目中已经持有该 scope（没有可训练的余地）。

运行方式（来自 docs/learn/maintaining-walkthroughs.md）：

SMOKE_BASE_URL=http://localhost:<frontend port> \ SMOKE_EMAIL=demo3@lightdash.com SMOKE_PASSWORD='demo_password!' \ SMOKE_SCOPES=manage:SavedChart,manage:CustomFields \ pnpm scope-tours:smoke

关键约束：

• 启动演练会删除该账号当前的训练副本，因此绝不能用正在被真人测试的账号跑 smoke；
• Enterprise 类演练（AI agent、data app）需要许可证，data app 还需要对应 feature flag，否则演练会卡在未渲染的控件上；
• 实例配置不同，演练行为可能不同，若变更依赖配置，应在相同配置下再跑一次（例如设置AUTH_GOOGLE_OAUTH2_CLIENT_ID与GOOGLE_DRIVE_API_KEY为任意非空值，会让导出菜单显示 Cloud 上才有的 Google Sheets 选项）；
• smoke 是按需手工运行、不进 CI 的：一次产品变更如果保留了所有标记但改变了点击路径，CI 依然通过，只有 smoke 能暴露它。

SMOKE_DEBUG=1会打印每步到达情况、每次页面跳转和每个改动数据的请求；SMOKE_OUT_DIR可改截图输出目录；--thumbnails参数会把动作步骤的页面快照保存到packages/frontend/src/features/learn/thumbnails/<scope>.jpg，用作课程卡片图带。

第三层：权限测试区分「组合角色」与「单独授权」

原文档特别强调：权限测试必须区分组合后的训练角色与单独的一次授权。这四条规则是课程不改变既有授权语义的底线：

• 原始验证者（verifier）可以保存并重新验证自己的内容；
• 原始删除者（deleter）可以恢复自己的内容；
• 虚拟视图更新在后端检查create:VirtualView；
• manage:ChangeCsvResults在前端门控导出选项。

也就是说，课程只负责「教会」这些权限在训练副本中的用法，而授权规则本身（packages/common/src/authorization/roleToScopeMapping.ts 中的getTrainingProjectScopes()/getTrainingProjectViewerScopes()）不被课程改动。文档原文的总结是："The curriculum does not change those authorization rules."

从 docs/learn/architecture.md 可以补充这一层的系统语义：训练权限层只增加权限、从不移除用户已有的权限；service account 与个人访问令牌永远不会获得 trainee 权限；权限按用户所属组织解析，因此用户不会在别的组织的项目上获得它。这正是「原始验证者可重新验证、原始删除者可恢复」能够成立的根本原因——训练副本只是叠加了一个 trainee 视图，没有剥夺任何既有能力。

后续工作与边界

21 条 Coming Soon 条目

课程库中其余 21 条 scope 条目目前统一显示 Coming Soon：12 个 embedding 类、3 个 content-as-code 类、2 个 promotion 类，以及 validation、analytics 和 2 个 agent-document 类 scope（完整清单见 packages/frontend/src/features/learn/comingSoon.ts）。这些条目的执行环境与访问约束需要单独的工作，新的交互式格式将作为独立工单交付——这正是 2026-09-10 移除阅读式交付后的必然结果：没有交互式实现就没有课程内容。

一个值得注意的例外是manage:DeletedContent：它原本身在优先级清单第 6 位，但当前在 scripts/scope-tours/coverage.ts 中被标记为 coming-soon，原因是其唯一可达路径是「为 Learn 新增的 Browse 菜单入口」，该入口在产品决策落地前被移除了（CS-311）。这恰好演示了「缺失入口 = 显式依赖项」的交付标准在实践中如何运作：一条课程可以因为产品侧缺少入口而被暂时撤下，而不是勉强用一个不真实的路径教学。

课程库的其余构成

九条优先课程并非课程库的全部。课程库还包含：查看与构建保存的 metrics tree、查看 AI agent、查看 data app 等条目，其前置条件包括 metrics-tree 的种子数据与复制、教学样本的保留、以及表单恢复。从 packages/frontend/src/features/learn/catalogue.ts 可见课程库的分组结构：Foundations（查看者已能做的事）排在最前，其后按 scope 注册表的 CONTENT、SHARING、EMBED、DATA、AI、PROJECT_MANAGEMENT、SPOTLIGHT、ORGANIZATION_MANAGEMENT 分组排列，每个模块还带有gate字段（enterprise / dataApps / aiAgents / softDelete），决定该模块在当前实例是否渲染——没有许可证或 flag 时模块会被库隐藏，而直接通过 URL 启动被隐藏模块的演练，会卡在一个未渲染的控件上（这是 docs/learn/architecture.md 明确记录的陷阱）。

实战要点总结

1. 判断一条课程是否完成，看「必需结果」而不是「做没做动作」：保存并看到 chart、看到验证指示器、看到编辑对验证的影响、获得改导出选项后的结果、列配置刷新后仍在、编辑虚拟视图后看到变更、删除后确认移除、恢复后 chart 回到空间——九条课程全部以可观察产物收尾。

2. 课程从产品标记与文档句子生成，维护的核心是data-tour-*属性与文档引用，而不是手写的步骤文件。修改 UI 时若动到被标记控件，要么把属性放回等价控件，要么重新生成并提交generated.ts；CI 无法捕获行为性破坏，只有pnpm scope-tours:smoke能兜底（详见 docs/learn/maintaining-walkthroughs.md）。

3. 新增一个 scope 的处置必须显式：新权限默认进入 Coming Soon（COMING_SOON_SCOPES），或给出带 CS 工单的 excluded 理由（SCOPE_DISPOSITIONS），否则覆盖率审计会报unclassified并阻塞 CI。

4. 训练副本是隔离的沙箱：副本是provisioning_source = 'training'的普通预览项目，只携带种子内容，永不携带学习者在共享项目或其他副本里的产出；识别「是不是训练副本」只看 provisioning source，而不能依赖copied_from或 upstream 链接（两者都可通过公开 API 伪造）。

5. 课程不改变授权规则：训练角色只是对既有 scope 集合做减法与叠加，验证者、删除者等原始授权在任何时候都优先于课程内容生效。

<输出文章>

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash