第 1 篇｜序章 — 全栈插件全貌与阅读指南

这是一组关于"全栈插件"的文章,共 22 篇。它不教你写代码,而是讲清一套规则——让多 Agent AI 协作 + 数据研发能反复、可靠地按规矩执行的规则。拿到全部 22 篇内容,可依《复现索引》(第 22 篇)复现插件骨架。本篇是引子:给全局地图、权威数字、读法、阅读契约。读完本篇,你应知道"要不要读下去、怎么读"。

一、全栈插件是什么

一句话:一个多 Agent AI 协作系统,把"该怎么做事"编码成文件,由事件驱动机制强制加载、检查、阻断。

它覆盖四类工作面:

• • 🛠️ 通用开发:前后端代码、测试、审查、诊断、Git——15 个 agent + 一组成套开发方法论 Skill。
• • 📊 数据研发:接数仓平台,从需求口径到 SQL 开发、试跑、提交、发布、补数据、运维——规则最密集、守卫最严的一条垂直主轴。
• • 🔬 数分:数据探查、取数、归因分析、联网调研——以"读"为主的同 Skill 内四模式路由。
• • 📋 报表:数据集→做报表→解读→提取→生成前端可视化——五子模式管道。

它不是"一个更好的提示词",也不是"一套工具脚本集合",而是介于两者之间的第三种东西:方法论运行时——方法论落进文件随项目分发,事件系统在写文件/压缩/退出/调工具的时机自动触发,靠 hook 硬阻断和脚本先行来兑现纪律。这个区别是第 2 篇的主线,本篇只点亮它,不展开。

二、它解决的根本问题

人与 AI 协作时,规矩默认活在三处:当前对话上下文、人脑里的经验、偶尔粘贴的提示词。这三处都不可靠——对话压缩就蒸发,换人就丢失,提示词一次性。于是同一个"先验证再声称完成"的纪律,要反复重申、反复被违反。

全栈插件从第一性出发,把不可靠收敛成两条不信任:

• • 不信任内存:运行时状态不可信,必须落盘。对话压缩、agent 换人、进程重启都不能丢状态。
• • 不信任模型:模型会偷懒、会记错、会声称完成但没验证。所以脚本先行(确定性判断不交给 LLM)、不信任口头报告(看产出不看汇报)、验证保护(没跑验证不许退出)。

整套 22 篇,所有规则都能追溯回这两条不信任。这是全系列总纲,序章只预告,第 2 篇给出奠基四条,后续每篇展开。

三、为什么写成 22 篇规则,而非教程

两个硬要求决定了本系列的形态:

1. 1. 可复现:有人拿到全部 22 篇内容,能凭借 AI 复现插件。这要求规则讲得够清——路径、命名、数字、守卫边界、状态机都要点名,不能含糊。
2. 2. 递进:文章彼此搭建,最终讲完整个插件。不能是松散的话题集,要有一根递进主轴。

由此推出本系列的阅读契约:

• • 规则导向,不含详细代码。讲清"要怎样、为什么、违反了会怎样",而不是贴大段实现。复现者抓住规则,遇歧义从两条不信任自行推导——这恰是"讲规则不讲代码"的意义。
• • 命令/路径/工具名保留原文。它们是机器契约,改了就破坏复现。在日常指代里,数据研发的 CLI 用中文名(资产元数据 CLI、数仓 CLI、需求 CLI……),只在路径与命令字面量里保留英文原名。
• • 每篇约 2500~4500 字,结构统一:有了什么/还缺什么 → 规则(R 编号)→ 边界与红旗 → 常见合理化借口 → 本篇产出 → 承下。

序章是唯一不严格遵循这个结构的篇——它是导览。

四、全局地图:八部递进

22 篇分八部,一根主轴:

1
2
3
4
5
6
7
8
9
10
0 方法论运行时 → 1 路由 → 2 mode/Profile → 3 init门控          [能配置能路由]  └→ 4 Agent → 5 PM编排                                       [能协作]      └→ 6 Schema DAG → 7 校验 → 8 状态机/Delta                [产出可追踪]          └→ 9 三层持久化 → 10 三路写入/恢复                   [压缩不丢]              └→ 11 Hook总览 → 12 四层防线 → 13 category       [操作不越界]                  └→ 14 自进化 → 15 evidence/探针 → 16 基线     [越用越好+防回弹]                      └→ 17 冒烟                                [行为回归]                          └→ 18 数据主轴                        [垂直压力测试]                              └→ 19 横切三组件+配置体系        [补全能力域]                                  └→ 20 收口+复现索引          [C1兑现]

每部一句话:

五、权威数字快览(一眼全景)

复现时以这套数字为准(第 22 篇有校正说明):

记住这张表,读后续篇时各处冒出的数字就不会乱。

六、两种读法

从头读(1→20):适合想完整理解或复现插件的人。主轴递进,每一部建立在前一部之上,跳读会缺地基。第 2 篇是地基首章,讲"纪律为什么必须入文件";本序章是它之前的导览。

按需跳读:有问题要查时,先翻第 22 篇《复现索引》10.1~10.3——三张表把"目录→产出篇""核心铁律→篇号""复现验收清单"列全了,按问题定位到篇,再回头读该篇及它的前置篇。

七、阅读契约再确认

打开任何一篇之前,先认下四条:

1. 1. 不含详细代码;命令、路径、工具名、JSON/YAML 字段名会保留原文,那是复现契约,不是"代码"。
2. 2. 每条规则有编号(R 篇号.序号),便于跨篇引用;"边界与红旗"列违反后果,"常见合理化借口"列反驳——后两者是对抗式检查的体现。
3. 3. 数仓规范硬约束(全文贯穿,记牢):应用层统一用 ADM(非 ADS);ODS 禁跨层到 DWS/ADM;ALTER TABLE 必须先于主任务发布;dev 模式账号必须用 default;提交 ≠ 发布。
4. 4. 两条不信任是罗盘:不信任内存、不信任模型。读到任何规则觉得"为什么这么严",往这两条推,通常就通了。

八、两条不信任(总纲)

全 22 篇的根,是第 2 篇奠基四条派生出的两条不信任:

• • 不信任内存 → 状态落盘(三层持久化 + 三路写入 + PostCompact 恢复 + Loop 状态文件)。
• • 不信任模型 → 脚本先行(SQL 硬检查 / 权限 / 预检 / 基线 / 冒烟都确定性脚本)+ 不信任口头报告(看产出)+ 验证保护(无验证不退出)。

复现者抓住这两条,遇歧义自行推导,正是"讲清规则不讲代码"的意义所在。

九、下一站

序章到此。接下来20天会发布剩余文章，下一篇预告:《方法论运行时 — 为什么把纪律写进文件》,它从"提示词会蒸发"的第一性问题讲起,给出奠基四条母规则。