breakthrough-performance-db-setup

Breakthrough Performance DB 设置

你要为一位学生安装一个系统，只安装一次。最终状态明确且可检查：他们自己的广告支出每天都进入他们自己的 Base 副本，其中的数字与 Ads Manager 一致，并且他们的知识库中有一条笔记，告诉下周的课程这一切都在哪里。

以下所有内容都由这一句话主导：安装中的每个步骤都可能在看似成功时失败，因此工作重点不是完成步骤，而是提供证据，证明每一步确实已完成。 复制的 Base 即使工作流已禁用，看起来也和正常运行时一样。同步只拉取了 500 行中的 25 行，看起来也像正常数据。边际字段中填入平均订单价值，会导致盈亏平衡线在每个判定中都出错，方向始终相同，而且永远不会报错。这正是设置 gate 4、6、8 和运行时检查的原因。

你在产品中的位置

此技能运行在由 my-second-brain 构建的知识库中，但不随其一起提供。 它需要单独安装和更新，并且它写入知识库的所有内容都遵循它所在知识库的规则，而不是本文件的规则。

写入知识库的任何内容，都必须遵循该学生自己的 99_Meta/structure-doctrine.md，并且必须在写入时实时读取。 ⛔ 此软件包不包含该文件的副本。第 8 节规定你要写的笔记的结构，第 0 节是归档决策树，第 5 节是关于名称的规则。⛔ 绝不能依赖对第 8 节内容的记忆，也⛔ 绝不能引用这里列出的键名：该学生可能已经修改了自己的章程。

⭐ 这种不对称性很重要，因此不要过度套用上面的规则。 知识库有实时的规则来源，你要读取它。Lark 和 Meta 没有。 学生的环境中没有文件记录复制的 Base 如何运行、+field-update 会悄无声息地破坏什么，或 Meta 令牌通常会出现哪种故障，因此本软件包中的 references/ 文件完整保留了这些知识，并且是唯一的知识来源。实时读取知识库中的规则；从本软件包读取本软件包的机制。

⛔ 此技能不作任何承诺。 不要说“一个会话内即可安装”，不要估算需要多长时间，也不要声称学生结束时会拥有什么。有些学生会在 gate 1 因广告账户归代理机构所有而受阻，没有任何版本的安装流程能够解决这一问题。说明当前 gate 的要求和通过测试。⛔ 在结果尚未出现之前，绝不能替学生承诺所需时长或结果。

使用学生自己的语言。 本文件使用英语；课程不一定。根据他们发给你的内容调整语言，包括语码转换，并确保字段名称和判定用语与其看板上的写法完全一致。

Gate 0：工具链，这是一个关卡

从 Gate 2 开始的每个关卡，都会通过 lark-cli，以学生自己的身份访问学生的 Base。 Gate 2 会复制模板并从副本读取名册，Gate 4 会写入 Targets 并读回该行，Gate 5 会清空六张表并统计数量，Gate 7 会编辑同步工作流，Gate 8 会重新汇总原始行，而不经过看板自身的总计。⭐ 因此，这不是 Gate 2 的附属环节，而是其余安装步骤赖以进行的基础；如果直到 Gate 4 才发现缺少它，那么这次会话已经让学生把晚上耗在了 Gate 1 到 Gate 3 上。

三项检查，检查就是检查，而不是提问，与 Gate 1 的凭据库探测遵循同样的纪律：要确认某项功能能不能运行 ⛔，而不是询问学生认为自己是否安装了它。

1. lark-cli --version 会返回一个版本号。
2. lark-cli whoami 会返回一个用户身份，其令牌不是 needs_refresh。⚠️ 用户令牌会悄然过期（lark-lessons.md:76），之后才会在身份验证对象上显示为解析错误，看起来像脚本损坏，而不是登录失效。
3. lark-cli base +base-get --base-token <the master token in references/template-and-teaching.md> 会返回模板的信息。⭐ 这一次调用就能同时证明四件事：CLI 已安装、登录有效、权限范围可以访问 Base，并且这名学生确实能看到该模板。这与 Gate 6 的情况相同：一次 Insights 调用就能同时证明应用、Marketing API 产品、System User 和 ads_read 均已就绪。

检查失败时，应由学生自行运行修复步骤；浏览器部分需要往返两次：

• 如果检查 1 未找到任何内容，运行 npm install -g @larksuite/cli。⚠️ 如果机器上的 npm 前缀不在 shell 的 PATH 中，安装会成功，但二进制文件仍会显示为缺失；应先用完整路径查找，再判断安装是否失败。
• lark-cli config init --new 会通过浏览器创建并绑定 Lark 应用。⛔ 他们不必在开发者控制台手动创建应用，⛔ 也不要把他们引导到那里。
• lark-cli auth login --domain base,drive 会授予所需权限范围。除了 base，还需要 drive，因为复制 Base 会在他们的 Drive 中创建文件。
• ⭐ 引导他们操作；不要代他们操作。 这两条命令都会在浏览器步骤处暂停，只有他们本人才能完成。将第一条命令置于后台运行，从输出中取出验证 URL，并将原样打印的 URL 交给他们。⛔ 绝不要重新输入、重新编码或拼接该 URL。

⛔ 在此关或任何后续关卡，绝不要把所有者的凭据当作捷径提供。 这些凭据授权访问所有者的整个租户；无论如何都无法在不同机器之间转移，因为用户令牌存储在操作系统的钥匙串中（lark-lessons.md:70）；使用这些凭据创建的副本也会落在所有者的 Drive 中，而不是学生的 Drive 中。

⚠️ 这个关卡无法解决一种故障，明确指出这一点比反复尝试更好：租户不允许这名学生创建应用。 个人 Lark 租户由学生本人管理，学生可以自行处理；公司租户则可能会拒绝。如果 config init --new 因此无法完成，请说明具体卡在哪里，以及组织内部由谁来解除限制，然后停止。⛔ 没有任何变通办法，擅自尝试只会比坦诚停止更糟。

通过测试： 检查 3 以学生本人的身份返回了模板信息。⛔ 不是“他们说自己安装好了”。

Gate 1：完整的资格确认

这个关卡最有可能以**“不行，而且没有变通办法”**告终，因此它被放在靠前的位置，并在此完整写出，而不是放进参考文件。⛔ 但这并不是唯一可能失败的关卡：Gate 0 可能遇到租户拒绝让学生创建应用，Gate 6 可能遇到 Meta 拒绝授予访问权限；这个软件包并不承诺任何关卡都有解决办法。为最终会在 Gate 1 失败的人运行 Gate 2 到 Gate 7，只会浪费他们和你的晚上。 三项访问权限检查。 直接询问，并将答案视为有待之后确认的说法，而非事实：

1. 他们拥有自己的 Meta Business Manager。 ⛔ 由代理机构所有的账号不符合条件。学生无法创建同步所需的 System User，而且在本次会话中，无论说多少次“我去问问代理机构”，都无法解决这个问题。
2. 他们是广告账号的管理员，而不是广告投放人员或分析人员。
3. 他们有一个可以容纳 Base 的 Lark 账号。 ⭐ Gate 0 已经通过实际操作证明了这一点，因此应视为已确认，不要再问。

⭐ 检查 1 和 2 是关键条件，但依赖自我报告；在这里这样做可以接受，因为学生如果对这两项的判断有误，就会在 gate 6 实际操作时遇到障碍：创建 System User 并调用 Insights 要么成功，要么失败。Gate 1 的作用是让那些已经知道答案是否定的人及时止步。

第四项检查是检查，不是提问：探查 vault。 查找 99_Meta/structure-doctrine.md。

• ⭐ 你要找的是一个文件。 如果不知道他们的 vault 在哪里，可以只问这一个问题（“你的 vault 在哪里？”），然后进行探查。⛔ 不要问“你有第二大脑 vault 吗？”，因为这个问题得到的是一种看法，而你需要的是一个非存在即存在的文件。
• ⛔ 如果文件不存在，就停止安装。 明确说明：这个系统会留下一条备注，方便下周的分析无需再次询问就能找到数据库；这条备注必须归档在一条该 vault 目前还没有的规则之下；安装 vault 是一项独立的工作（my-second-brain），需要由他们自行运行。说清楚缺少什么、由谁解决，然后停止。
• ⛔ 不要退而求其次，改为写一条普通备注。 写入 vault 无法识别的格式，比不写备注更糟：vault 自身的维护流程看不到它，frontmatter guard 会拒绝或标记它，而学生此时会以为自己有一个其实并不存在的指针。

第五项是一个问题，也是人们会跳过的问题：“你的潜在客户是如何归因到具体广告的？” 不要问“你会追踪潜在客户吗？”，而要问今天到达的潜在客户是如何关联到带来他们的广告的。让他们描述实际使用的机制：每则广告各自的 WhatsApp 点击聊天链接、表单字段、落地页参数，或专用电话号码。

⛔ 在 gate 1、复制任何内容之前，就明确说明不适用的范围。 实际说出来，内容大致如下：

整个系统依赖一个文本键：<ad-id>__<YYYY-MM-DD>。每个滚动窗口、每个合格潜在客户成本数据、每个判断，都是通过这个键进行查找。到店客户无法携带 ad-id。拨打共享号码的电话无法携带 ad-id。 如果你的大多数潜在客户都是这样来的，那么这块看板的广告部分会正确，潜在客户部分却会是空的；无论迁移、公式还是之后的修复，都无法凭空生成潜在客户到达时从未记录过的键。

⭐ 要在 gate 1 说清楚这一点，否则学生会以为材料有问题。 他们不会得出“我的归因方式不适用”的结论；他们会得出系统无法工作的结论，而这时他们已经用自己的数据搭建好系统三周了。

如果漏斗不适用，就直说。 ⛔ 不要假装它适用，也⛔不要暗中扩大“对话”的定义，让他们的数据看起来符合预期。本次会话可以带他们了解现有设计，让他们自行构建潜在客户部分的变体。这是合理的做法，而且往往是正确的选择。⭐ 如果这样做，必须在学生的 vault 备注中记录实际构建的内容，因为下周的分析会读取这条备注，并假定采用的是标准结构，除非备注另有说明。操作流程见 references/vault-note.md。

Gate 2 至 10：适用规则

2. 复制模板，并由你来运行副本。 ⭐ lark-cli base +base-copy 一次调用就能完成学生原本需要手动完成的操作，使用的是他们在关卡 0 中的身份，副本会落在他们拥有的云盘中。⛔ 这并不违反“使用模板，而不是配置器”这条规则。 这条规则针对的是逐字段构建 Base：需要数百次调用，每次都可能失败。复制只需一次调用。⛔ 运行时使用的是学生自己的凭据，绝不使用所有者的凭据，因为新 Base 归创建它的令牌持有者所有，而且 API 没有参数可以改变这一点。接着，按名称解析每张表，并在运行时从他们的副本中读取名单，因为复制后 table_id 会重新生成（lark-lessons.md:706），所以任何写下来的 ID 都是等着在第二个学生那里出错的隐患。⛔ 复制时要明确传入时区。 调用不会继承时区；不带时区创建的副本，其计时器所用的时刻与模板上看到的时刻不同，因此每个学生的 07:00 都会悄悄变成其他时间。标志及其确切写法见命令说明：references/template-and-teaching.md。⛔ 通过测试项 1：他们副本的令牌不是主令牌（references/changing-the-base.md §0）。⭐ 由你来运行复制操作，会让这项检查更可靠，而非多此一举：令牌现在是作为 API 返回值传来的，而不是从学生的剪贴板上取得的。主 Base 能通过清单中的其他所有检查，因为它是健康的原始版本；只有令牌能区分两者。接下来：按名称解析全部八张表，并确认同步工作流已停用（副本会带上工作流，但会保持停用状态，lark-lessons.md:702）。⛔ 不能删除手动操作的路径。 如果调用在关卡 0 通过后失败，就把链接交给他们，让他们点击，然后从同一项测试重新接上。命令、使用条件以及它会引入的唯一一种新故障，详见references/template-and-teaching.md。

3. 讲解演示看板。 ⛔ 这是教学，不是考试。 绝不要问“你明白这是什么意思吗”，再根据回答决定是否继续安装。⭐ 展示一组对比，然后就停下：看板上每次对话成本最低的广告标为 KILL，最高的标为 SCALE。这个对比就是整个系统存在的理由。⛔ 不要逐一讲解其他判定；它们每周都会自行出现，并附在学生自己的广告上。这里刻意不设通过测试：下周他们会再听一遍，并且看板上展示的是他们自己的钱，那才是真正理解的时候。

4. 填写 Targets。 ⭐ 让他们说出数字，由你来填写（适用references/changing-the-base.md：检查令牌，然后读回该行）。⛔ 不要让他们自己输入：这一关要防止的错误是把订单金额填进利润率字段，而由你来操作键盘就能完全避免这种情况。根据他们的回答计算盈亏平衡点，并在填写之前征得他们同意。询问这些数字使用什么货币，并记录下来；关卡 6 没有其他来源可以获取这项信息。⭐ 一个数字填错，就会让之后的每项判定都朝同一个方向出错，因为 ROAS 的通过线就是他们的盈亏平衡点，而盈亏平衡点由利润率推算。参考文档中有两项硬性检查：毛利率大于或等于平均订单金额，结果就必然不成立；盈亏平衡 ROAS 接近 1.0，是把订单金额填进利润率字段的典型迹象。 通过测试：他们看到了由自己输入的数据计算出的盈亏平衡数值，并且认可这个结果。 5. 清除演示数据。 将六张表清空；Targets 和 Account 各保留一行。⛔ 忘记这一步会让演示行混入真实数据，导致看板上的每个数字都悄悄出错。这会修改他们的 Base，因此须遵循 references/changing-the-base.md，并通过重新列出记录、亲自统计行数来验证。⭐ 你在此处清空的广告层会在首次同步时重新填充，而不是手动填充，相应的通过测试在关卡 7；两者都在 references/template-and-teaching.md 中。

6. 获取 Meta 令牌。 ⛔ 不要硬编码点击路径。 Meta 的界面不断更名和调整，而满是过时菜单名称的技能会让学生觉得材料已经过时。运行时查找当前流程，并引导他们完成。⭐ 验证最终状态，而不是步骤：一次成功的 Insights 调用即可同时证明应用、Marketing API 产品、System User、分配和 ads_read 均已就绪，而且无论界面如何改版，这种验证方式都有效。⚠️ 但调用成功并不能证明令牌的来源。 短期用户令牌同样能通过，这也是这个关卡最常见的失败原因，往往要到几周后同步停止时才会被发现。因此还要检查有效期和来源；若失败，要明确指出缺少四个环节中的哪一个，而不是只说没有成功。相关流程，以及首次实时调用后需要进行的三项运行时检查，都在 references/meta-token-and-sync.md 中。

7. 接通同步。 替换所有占位符、启用工作流、手动运行一次，并确认之后确实有记录。⛔ 不要把占位符数量带入这个关卡：读取工作流，确认其中有多少个 HTTP 步骤；再逐个读取步骤，确认各自的情况，因为未接通的步骤会静默失败，只有对应的表会停止更新。通过测试由三项内容组成，记录只是第一项。 Ad Daily 中有记录，而不是运行状态显示绿色。广告层已重新填充，行数与关卡 5 清空时的记录数相符。并且读回 Account.sync-last-run，确认其记录的是本次运行：关卡最后才写入时间戳，因此若写入失败，本次运行看起来会完全正常，却会在下次触发时产生重复记录。⛔ 切勿把“工作流运行了”当作“数据已到达”，也切勿把“数据已到达”当作“关卡已通过”。

8. 对账，这是一道关卡，而不是一个请求。 ⛔ 用“是”回答“匹配吗？”并不构成证据。你没有亲眼观察到比较过程，而这个系统可能出现的每种故障（键值中多出空格、公式绑定到错误对象、汇总字段静默返回零）都会给出看似合理的数字，而不是错误。⭐ 让证据流向你：由你指定日期范围，学生报告 Ads Manager 的数值，令牌独立拉取同一日期范围的 Insights，然后由你亲自汇总原始 Ad Daily 记录，而不是通过 Base 自己的汇总字段，因为这些汇总字段本身也是待测试对象之一。 三方比对。详情见 references/reconciliation-and-handover.md。

9. 编写保险库笔记。 在业务区的 01_Assets/IT-Systems/ 中创建一条 it-system 笔记，记录 Base 的指针，以及下周的会议原本还需要询问的一切信息。若只有一个业务区，就直接使用；若有两个或更多，则询问一次由哪个业务区管理此广告账户。⛔ Meta 令牌绝不能写入笔记。 完整规范（包括 frontmatter、写入前读取规则和归档日志行）见 references/vault-note.md。 10. 交接。 内容要简短，并按阅读顺序展开，而不是介绍功能：先确认同步是否及时，再判断团队能否接收更多潜在客户，最后才给出结论。⛔ 学生若先读 SCALE 并据此行动，就会把钱投入一个无人跟进的漏斗中。这里只在此处说明两项注意事项，别处不再提及：在工作流中，任何拥有该 Base 编辑权限的人都能读取 Meta 令牌；以及第 6 个关卡运行时检查得出的时区和货币信息。参见 references/reconciliation-and-handover.md。

按需加载本技能的其余内容

何时	阅读
第 2 至第 5 个关卡，Lark 部分	references/template-and-teaching.md
第 6 和第 7 个关卡，Meta 部分	references/meta-token-and-sync.md
第 8 和第 10 个关卡	references/reconciliation-and-handover.md
第 9 个关卡，任何写入保险库的内容	references/vault-note.md
任何关卡中对学生 Base 的任何更改	references/changing-the-base.md

⛔ 在需要的关卡按需加载。 如果一个会话在开始前就读完全部五份文件，那么它还没运行第一个关卡，就已经把上下文耗在了整个安装流程上。

铁律

• ⛔ Meta 令牌绝不能进入保险库，包括任何笔记、示例或引用的错误消息。它只存放在工作流占位符中，本技能涉及的其他任何位置都不能存放。
• ⛔ 对学生 Base 的每项更改都必须遵循 references/changing-the-base.md，包括其中的 §1a。 该文件区分了三种更改，只有一种需要满足四项条件：填写第 7 个关卡的占位符属于安装时配置；对已运行的 Base 进行迁移时，必须满足全部四项条件（在此包中声明、与此包一同进行版本管理、记录在保险库笔记中，并且能够检测是否已应用）；学生自有变体不满足前两项条件，而是必须留下书面记录，并始终按未知结构处理。⛔ 不要把四项条件套用到所有三种更改上：那样会禁止安装，也会禁止本技能明确允许协助构建的变体。判断标准是：下一个会话仅凭本技能和那份笔记，能否说清该 Base 的结构。如果不能，你做的就是临时发挥，而临时发挥会让学生的副本无法诊断。
• ⛔ 写入可能已存在的任何保险库路径前，先读取。 frontmatter 防护只监控新建文件：fm-guard-hook.sh:346 会直接放行已存在的路径，并附有注释 "an edit, not a birth; this guard watches births"；fm-guard-hook.sh:369 则表明 Edit 甚至不在匹配范围内。因此，第二次安装运行时若盲目写入笔记，就会悄无声息地替换整个文件，且没有任何机制可以阻止。
• ⛔ 保险库笔记必须通过 Write 工具写入，绝不能通过 Bash 写入。 防护可以读取 Write 操作并检查其中的 frontmatter；但它无法读取 heredoc 的内容，而且它的正则表达式也会拦截 >>。通过 shell 写入笔记会绕过唯一能检查其结构的防护。
• ⛔ 退出代码绝不能作为证据，ok: true 也绝不能作为证据。 读回你写入的内容，统计你清理的数量，并将结果与预期进行比较。

安装时需要判断的事项

这个模板有三点事实，否则每一点都可能让你耗上一个下午：

• NOW() 在公式中会冻结；TODAY() 不会（依据此模板的实测结果，见 lark-lessons.md:180-181）。⭐ 这就是为什么此看板上的每个滚动窗口都是实时公式，而同步过程完全不做计算：它只写入原始行，由看板负责运算。⛔ 因此，绝不要通过向过时的窗口写入数字来“修复”它。窗口并没有过时，而写入固定值就是一个永不过期的谎言。
• 链接字段的名称若与其指向的表相同，它会悄无声息地解析为整张表（lark-lessons.md:95）。它会返回每一行的值，并将它们拼接成一个字符串，不会报错，而且每一行都会显示相同的值，看起来像是数据问题，而不是架构问题。如果你在这里创建或重命名字段，⛔ 绝不要将它命名为某张表的名称。
• 跨表汇总会静默地漏掉数据。 同步写入的行不会自动关联到链接字段，因此通过链接字段进行的汇总会悄悄漏掉这些行（lark-lessons.md:680）；将公式列用作 FILTER 结果列时，返回结果会是空的，而不是报错（lark-lessons.md:222）。两者返回的数字都看似合理，只是偏小。⭐ 这正是第 8 道门槛要重新汇总原始 Ad Daily 行，而不信任看板自身总数的原因：被测试的恰恰就是这些总数。

已经定案，不再重新讨论

记录在此，避免任何会话再次占用学生的时间，争论已经做出的决定：

• ⛔ 模板按当前状态发布。 不重新设计、不扩展架构、不制作第二个模板、不拆分 A/C、不提供电商变体，也不添加模式标记。这些方案都已考虑过，也都已被否决。提出添加其中任何一项，属于产品决策，而非会话决策。
• ⚠️ 版本标记原本也在这份清单中，但现在不再是了。 产品负责人于 2026-08-24 推翻了这一项，这就是本行所指的决策路线，而模板现在也包含 Account.template-version。⛔ 使用它之前，请先阅读 references/changing-the-base.md §1 中的三个条款：这些条款完全不将它纳入架构决策。⛔ 这一变更不构成推翻上述清单中其他决定的先例。
• ⛔ 此技能绝不修改任何人的 vault 原则，也绝不提议添加 type: 来为其笔记腾出位置。那是 vault 所有者的事务，由他们使用自己的 vault 工具处理。
• ⛔ 此技能绝不编辑模板 Base 本身，只编辑学生自己的副本。读取模板没有问题，第 0 道门槛的第三项检查就是这么做的；⛔ changing-the-base.md §0 的存在，就是为了阻止写入模板。
• ⛔ 副本必须使用学生的凭证运行，否则就不运行。 此事已定：由会话执行复制，而不是让学生点击；而且绝不使用所有者的身份进行复制。提出以任何形式封装并交付所有者凭证，既不是会话决策，也不是产品决策。
• ⭐ 安装是交付成果，而 vault 笔记能让成果延续下去。 一个连接完善却没有笔记的 Base，是学生无法解释的系统；下周的会话就不得不通过盘问重新发现一切。