Part 0 · 全景：你能做到什么
先看整张图——起点、三层 + 知识库、最终产品。
→
① 数据层人灌理解 → AI 建自己的库
② 工具层初始 CLI + 接口文档 → 完善 CLI
③ 决策层经验 → 判断逻辑
＋ 知识库贯穿三层，越用越懂
→
最终产出ka-data 看板
·kuaishou-cli
·strategy-agent
·啪嗒助手
AI 是引擎，你是大脑。每一步都是「你给理解/方向 → AI 干活 → 你校验」。你不需要懂代码细节，你需要懂每层该搭什么、AI 帮你干什么、怎么校验。下面一层层拆。
Part A · 三层 + 知识库（怎么搭）
关键：不是 AI 自己理解 ODPS 表，是你把理解灌输给 AI。
人是理解的源头。你把自己对 ODPS 表的理解讲给 AI——这张表是什么、字段什么口径、业务规则是什么、考核怎么算——AI 接住你的理解，才能理解 ODPS 表，并实现后续建库/取数/出看板。你的业务理解是这一层的输入，AI 是把理解落成代码的执行者。
📊
你的看板（ka-data）
自己取数、自己理解、自己看
↑AI 帮你建
🗄️
自己的数据库
事实表 + 维表 + 业务规则（你灌的口径）
↑你把理解灌给 AI
🧠
你的理解 → AI
表是什么 / 字段口径 / 业务卡片 / 考核公式
↓起点
你灌什么
表是什么（事实表/维表）、字段口径（消耗/转化/出价）、业务规则（13 张考核卡片、按日生效含历史）、考核公式（成本达成率=消耗÷Σ考核×转化）。
AI 帮你干
接收你的理解 → 生成建库脚本（事实表/维表 DDL）、写取数逻辑、出 SQL、生成看板前端。你校验数字对不对。
📦 项目示例：ka-data 看板是怎么做出来的 ▾
起点：拿到 ODPS 表（素材报表、广告组底表）——原始、看不懂、不好用。
人灌理解：车程讲清——广告组表 fact_adgroup_daily（消耗/转化/出价/标签）、素材表（无 account_id，靠 material_name LIKE 反查）、13 张考核卡片（CVR/闪购/召回UV/闲鱼，按日生效含历史）、考核公式（成本达成率=消耗÷Σ考核×转化，转化加权非平均）。
AI 帮做：建 snapshot.db（事实表/维表 DDL）、写 data_loader 取数逻辑、出 dashboard 看板前端。
踩坑：bi_conversions ~90 账户全 0（媒体口径差）、biz_name 跟素材注册走不跟 task（重派）、Hologres 桥失效毁数据（加固"源空跳过 DELETE"）。
产出：ka-data 看板（7002/7001），取数不求人、口径自己说了算。
💡产出：ka-data 看板——你自己的数据库 + 看板，取数不求人、口径你说了算。
工程给个能跑的初始 CLI，你自己用 AI 收集媒体接口文档，一点点补成全能工具。
🔧 初始 CLI → 完善 CLI 的补能力流程
初始 CLI工程给的基础
→
收集接口文档媒体开放平台
→
AI 读文档理清字段/枚举
→
封装子命令开户/建组/调价
→
验证真账户 dry-run
→
完善 CLI无所不能
能干什么
开户、建组、调价、改预算、充值、取曝光/点击/落地页链接、查报表——把媒体能干的活都收进 CLI。
AI 帮你干
读接口文档（路径/参数/枚举）、生成 CLI 子命令代码、写调用示例、帮你排错。你提供文档 + 验证。
红线：动钱的能力先 dry-run。充值/调价/改预算这类写操作，先 --dry-run 预览影响、人确认再真跑。0 预算不能传（0=不限会烧钱）。能力可以慢慢补，安全不能省。
📦 项目示例：kuaishou-cli 是怎么补出来的 ▾
起点：工程给个能取 token 的初始 CLI。
收集文档：把快手磁力引擎 MAPI 文档（312 个接口）抓下来落盘到本地，方便 AI 随时读。
AI 读文档：理清 bid_type（2=CPC/10=OCPM/12=MCB，纠正 10≠Nobid 这个常见误编）、schema_uri 调起链接、版位、出价类型。
补子命令：account budget/flows、unit list/get（含 schema_uri）、campaign、material、agent transfer（充值）——一个个补。
写操作 dry-run：充值 transfer_type=2 信用金，--dry-run 预览账户+金额，禁传 0（0=不限会烧钱）。
产出：kuaishou-cli——开户/建组/调价/充值/取链接/查报表都能调的投放工具。
💡产出：kuaishou-cli——一个你想干啥投放操作都能调的 CLI 工具。
这一层最值钱——把人脑里的经验变成系统能跑的判断。
经验结构化五要素：① 指标（消耗/成本/转化）② 阈值（达成率红线）③ 时间窗口（7/14/30 天加权）④ 状态（培养→成功→衰退→淘汰的生命周期）⑤ 归因路径（逐层拆解+排除法定位根因）。你把判断话术讲给 AI，AI 拆成这五要素落成判定逻辑。
判定规则
定一个确定性公式（加权多窗口 + 附加闸 → 几态），可解释可复现。LLM 不进核心判定，只做展示/解读（自然语言→图表、结论翻译）。
人确认闸门
pending → confirm → execute 状态机：系统推荐 + 排序，人定方向 + 拍板，系统执行。半自动边界。
知识库兜底
决策时 AI 先读知识库（业务口径/字段映射/历史决策/坑）再判，不凭空想。改了逻辑同步更新知识条目。
探索 vs 调控
两条链路：探索→沉淀（发现新成功策略入池）、监控→调控（盯在投成本，超阈值熔断）。带死区防抖。
📦 项目示例：strategy-agent 的决策层是怎么搭的 ▾
起点：把车程的投放判断经验讲给 AI。
经验结构化：拆成五要素——指标（消耗/成本/转化）、阈值（成本达成率红线、日消耗>2000&超30%熔断）、时间窗口（7d×50%+14d×30%+30d×20%加权）、状态（培养→成功→衰退→淘汰）、归因（逐层拆解+排除法）。
判定规则：judge.py 加权 OCR + 附加闸 → 4 态，确定性，LLM 不进核心判定。
人闸门：pending→confirm→execute，系统推荐+排序，人定方向+拍板。
dryrun 演练：暴露 5 个问题（conv 口径错配/bid_tool 空/N 失效/停跑误判/基线正常）→ 逐个修，再演练验证。
产出：strategy-agent（engine/server FastAPI:8100 + 执行编排 + safety 白名单/审计）。
💡产出：strategy-agent——你的经验变成的决策+执行系统，会推荐、会判定、会受控执行。
不是单独一层，是喂所有层、被所有层喂的底座。
知识库存两类：① 概念/口径/经验（业务定义、转化口径、人物角色、分析原则）进语义记忆库（可语义搜）；② 精确值（URL/路径/appCode/字段ID）落引用文件（按名/grep 取，语义库检索不到精确串）。AI 用之前先读对应的家底再答。
怎么沉淀
过程中自动抽取：数据层的表口径、工具层的接口文档、决策层的经验/坑，都进知识库。AI 自动抽 + 你审。
怎么用
AI 干活前先读家底：取数先读口径规约、调 CLI 先读接口文档、决策先读历史经验。不凭空想是这层给所有层的兜底。
💡知识库 = 越用越懂你的资产。每次反馈/纠错都进库，AI 下次就避坑。
三层搭好了，还需要一个你能 @ 就用起来的入口。
啪嗒 = 建在三层之上的交互式工作助手。它消费三层——取数（数据层）、调 CLI（工具层）、用决策（决策层）、记事复盘（知识库）——给你一个@ 就能用的钉钉入口。不用开看板、不用敲命令，群里 @ 它就行。
交互式
@ 它问数据/要分析/记待办，它先回忆你的偏好（语义库），再取数/调工具/给判断，回复你。
定时回看
日报（数据+异动诊断）、周快照（本周知识总结发群）、待办自动同步——从一次性问答变持续搭档。
💡产出：啪嗒助手——三层能力的交互入口，让你（和团队）@ 就能用上整套系统。
Part B · 想动手的人怎么起步
不用一上来造整个系统，一层一层来，每层验证。
1
数据层先起：你把对 ODPS 表的理解讲给 AI → AI 建事实表/维表/业务规则 → 出个看板。先能取数、能看数。
2
工具层跟上：基于初始 CLI，让 AI 读你收集的媒体接口文档 → 一个个补子命令（先只读查，后写操作）→ 写操作必 dry-run。
3
决策层收口：把你的判断经验讲给 AI → 拆成五要素 → 落判定规则 + 人闸门 → 跑 dryrun 演练验证。
∞
知识库 + 助手全程跟：每层过程中沉淀知识（口径/文档/坑）；最后搭个 @ 入口（啪嗒）把三层串起来用。
先读家底再答：AI 干活前先读规约/知识库，别凭空想（bid_type 编成 Nobid 就是没读文档的教训）。
安全先于功能：白名单/禁传 0/dry-run/审计是底线，动钱的能力后补也行，安全不能省。
确定性判定 + LLM 展示：核心判定用确定性规则（可解释），LLM 只做展示/解读，不进判定。
人确认闸门：系统推荐+排序，人定方向+拍板，系统执行——半自动边界。
错了就反馈改：错误是资产，反馈→改认知→改代码，下次就对了。沉默=永远错下去。
规矩交代码，风格交 prompt：硬约束写代码 100% 生效，风格/口径写 prompt 让 AI 守。
Part 7 · AI 使用小技巧
从做项目里提炼的实战技巧，+ 通用心法。（先发一版，后续我再补真实案例）点击「案例」可展开具体例子。
做产品/功能时，别一上来让 AI 写代码操作。先把产品设计/方案想清楚——要解决什么、三层怎么分、各子环节职责、取舍点。设计对了再动代码，省掉大量返工。
▾ 案例
我们做 strategy-agent 就是先出产品方案 v0.3 再动代码，dryrun 演练先于全量执行。
过程中尽可能让 AI 反问/澄清，而不是它闷头干。歧义先对齐再执行——口径/字段/范围没说清，AI 猜错了全错。
▾ 案例
「先澄清再执行」是核心原则，让 AI 问你比你告诉它更省事，问答过程本身就是在帮你想清楚。
别让 AI 凭记忆答。提问里带「先读 XX 规约/知识库」，或确认项目规约已让它默认先读。
▾ 案例
bid_type=10 被编成 Nobid（实际是 OCPM）就是没读文档的教训；读了接口文档就不编。
硬约束（白名单/禁传 0/强校验）写进代码，100% 生效，AI 想绕都绕不过；风格/口径/偏好写 prompt 让 AI 守。
▾ 案例
写进 prompt 的约束 AI 经常不听，代码层硬卡最靠谱。
5
让 AI 产出结构化（JSON），别要自由文本通用要 AI 往下流转的产出（抽取/快照/决策），让它输出 JSON 而非一段话——好解析、好落库、好验证、好对接下一步。
▾ 案例
啪嗒的快照/抽取都走 JSON，下游脚本直接 parse。
URL/路径/appCode/字段ID 这类精确串，别塞进语义记忆库（向量检索捞不到），落文件按名/grep 取；概念/口径/经验进语义库。
▾ 案例
这是踩过坑后的 SSOT 规约——精确串进错地方就检索不到。
充值/建组/调价/改预算这类写操作，永远先预览影响、人点头再真跑。
▾ 案例
0 预算传值会真烧钱（0=不限）；充值脚本永远先 --dry-run 让你确认账户+金额。
AI 答错别忍着——指出哪错，让它写进知识库/改代码，重跑验证。
▾ 案例
异动诊断方法论、Hologres 桥加固、dryrun 5 个问题逐个修，都是这回路跑出来的。错误是资产。
别只在有问题时找 AI。把盯盘/取数/复盘交给 AI 定时跑（cron），你只看结论和异常。
▾ 案例
日报/周快照/待办三条定时线，啪嗒到点自动送到眼前，从一次性问答变长期搭档。
别一次性让 AI 造整个系统。一层一层来、一个子命令一个子命令补、一个判定一个判定落，每步验证对了再下一步。
▾ 案例
三层架构的意义就在这——可以分层独立验证、独立产出。
改了逻辑/口径，同步更新知识条目，否则下次 AI 和同事都靠不住。
▾ 案例
知识库与代码不同步是常见漂移源——动代码要求更新知识，写进协作规约。
12
数据走本地快照，速度远快于访问 ODPS项目实战ODPS 在线查询慢、有限流、还有权限墙。把要用的数据定期拉到本地快照（SQLite snapshot.db），后续分析/取数都走本地，速度数量级提升、还不怕断网/限流。
▾ 案例
ka-data 的 snapshot.db 就是这么来的——每日 cron 把 ODPS 增量拉到本地，看板/分析/啪嗒都读本地，不用每次打 ODPS。
13
接口文档，用本地 qoder 批量拉取项目实战媒体开放平台的接口文档散落在各页，一个个手抄太慢还漏。用本地 qoder 批量抓取，落盘成 md，AI 随时能读、能 grep。
▾ 案例
快手 MAPI 312 个接口就是这么批量抓下来落盘的，AI 才能随时查字段/枚举，bid_type 这种映射才不会编错。
Part 8 · 团队协同（探索中的方向）
前面三层是"一个人 + AI"造；再进一步——一个产品让多人一起迭代优化，数据库是协作枢纽。
关键：数据库支持多方读取/更新/补充。把数据底座做成共享服务，多方读（reader token）、受控写（editor）、运维（admin）——读写端点物理分离、任务锁防并发覆盖、审计留痕。这样多人能并行迭代又不互相搞坏。
🗄️ 数据库多方协作
数据底座做成共享服务（FastAPI），多方读/受控写/运维分级。读写分离、任务锁防并发、审计 + 可回滚。口径配置走 git PR，合并热加载，不接受在线改。
👥 分层 owner
数据底座/上层逻辑/前端各有人管。前后端靠 API 契约解耦——做前端/后端的不需要懂数据底座，看接口文档就能对接，团队可并行。
1
git + PR：主仓 + 外部依赖仓各自 remote；main 保护、分支语义化、MR assign review；口径配置走 PR 合并后热加载。
2
授权分级：Reader（只读）/ Editor（改标签+刷新）/ Admin（合并 PR+热加载+重启）。"能改"是三个权限，物理切开。
3
env 管理：同事不跑十几 GB 数据库，配 env 指底座 owner 的共享服务；取数双路径（HTTP 优先回退 SQLite）。
4
红线：不推 main/不碰数据仓/不在线改口径/不碰凭证/写操作必 review；动钱必 dry-run。
这是探索中的方向——这套在 strategy-agent 上刚开始试，还在打磨：测试基建缺失（待办 L）、新旧服务切流未完（待办 B）、沙箱地址会变需人工通知。但方向是对的：从"一人造"到"团队一起迭代"，数据库是协作枢纽。
💡团队协同本质：把"可融合的"（代码/文档/口径走 git）和"不可融合的"（本地数据/运行态/真账户写操作）物理切开，多人能并行又不互相搞坏。