A · 工具架构（三层骨架）
先想清楚痛点，再谈架构。
投放运营的痛点：盯盘累（天天看数）、取数繁（口径多/表多）、操作重复（建组/调价/充值一遍遍）、经验难传（谁懂啥全在脑子里）。
一个投放工具的核心价值：把「取数 → 判断 → 执行 → 复盘」这条链自动化，把人脑里的经验变成系统可判定的逻辑。
📎 参考样例：三个项目各管一段
📊 ka-data取数底座——把投放数据落库、出看板，解决"盯盘累/取数繁"。
⚙️ strategy-agent判断+执行——在数据上跑判定、受控执行建组/调控，解决"操作重复/经验难传"。
🤖 啪嗒复盘+记事——日报/快照/待办定时回看，解决"复盘靠人记"。
💡核心命题：把"经验"变成"可判定的逻辑"，再让逻辑驱动自动执行——不是一次性问答，是持续闭环。
不管你投什么渠道、做什么工具，这三层骨架都适用。
🧠
判定 / 逻辑层
在数据上跑判定（好坏/异常/该不该调）、出推荐，人确认。LLM 只做展示，不进核心判定。
↕pending → confirm → execute（人确认的闸门）
⚙️
执行层
受控地把判定落到投放动作（建组/调价/充值），有安全闸门 + 留痕。
↕只读取数 + 受控写操作
🗄️
数据底座层
把投放数据落库（事实表 + 维表 + 业务规则），只读、口径清晰、可复算。
状态机就是人确认的闸门：系统推荐 + 排序，人决定测什么、给多少预算，系统再真实执行。三层各自独立：数据底座坏了不影响判定逻辑读历史，执行层没建好判定层也能先跑。先把数据底座 + 判定做出来，执行层后补也行——这是关键解耦。
💡三层骨架不是某个平台的专属设计，是"做投放工具"的通用范式。你做自己的工具，先搭这三层。
每层拆成子环节，每个子环节一个职责、互不越界。
🗄️ 数据底座
事实表（消耗/转化/出价/预算）+ 维表（标签/商品/素材）+ 业务规则（考核口径）。口径按日生效、含历史，不烘焙死，可复算。
⚖️ 判定算法
定一个判定公式（如加权多窗口 + 附加闸 → 几态），保持确定性，LLM 不进核心判定——判定要可解释、可复现。
🔍 探索/沉淀
给方向 → 补全 → 建实验 → 观察窗口 → 裁决 → 沉淀/淘汰。一期用规则查询复制历史最优，不必上学习模型。
🚨 监控/调控
轮询 → 阈值 → 决策 → 受控执行（暂停/降价）。带死区（容忍带内不调），避免抖动反复操作。
🔒 执行安全
白名单账户 + 禁传 0（0 预算=不限会烧钱）+ 强约束（承接页↔业务）+ 审计落盘 + dry-run 预览。
📚 知识库
把业务规则/字段/口径文档化。动代码要求同步更新知识条目，否则下次 AI/同事都靠不住。
📎 参考样例：子环节怎么落地
📊 ka-data数据底座样例：snapshot.db 事实表 + business_rules.json 13 张考核卡片（按日生效含历史），考核口径不烘焙死、按日取。
⚙️ strategy-agent判定+执行样例：judge.py 加权 OCR 判定（确定性，不进 LLM）；safety.py 白名单+禁传0+审计，pending→confirm→execute。
🤖 啪嗒复盘样例：日报跑异动诊断（逐层拆解+排除法，确定性方法论），周快照定时回看，待办自动同步。
做工具不是一步到位，刻意取舍才能落地。
| 取舍点 | 怎么取 | 为什么 |
|---|
| 看得全 vs 动不全 | 判定可以全维度，执行先小颗粒度（如 unit 级） | 执行层动太全风险大，先小步验证 |
| 安全 vs 功能 | 安全先于功能：白名单/禁传0/强约束/审计先上 | 动钱的事，出错就是真烧钱 |
| 数据底座 vs 执行层 | 先做数据底座 + 判定，执行层后补 | 底座+判定本身就有产品价值，不必等执行层 |
| 确定性 vs LLM | 核心判定用确定性规则，LLM 只做展示 | 判定要可解释可复现，LLM 会漂移 |
| 当下 vs 演进 | 预留演进：占位字段、观测记录常态化 | 一期不上 bandit，但数据先攒着，未来能升级 |
最该守的一条：安全先于功能。凡涉及真账户写操作（建组/调价/充值），白名单 + 禁传 0 + dry-run + 审计是底线，功能可以后补，安全不能省。
B · 团队协作一起做出来
不是人人都能碰所有东西——按层切，权限分级。
按层分 owner：谁管数据底座、谁管上层逻辑、谁管前端。前后端靠 API 契约解耦——做前端/后端的人不需要懂数据底座，看接口文档就能对接。
Reader只读查询
所有开发同事持有。只读 /api/*。
Editor改标签 + 触发刷新
负责运营标签的少数人。/write/*。
Admin合并口径 PR + 热加载 + 重启
数据底座 owner。/admin/*。
📎 参考样例：strategy-agent 的分工
车程（Admin）数据底座 ka-data + 口径配置 PR + 热加载 + 服务运维 + token 发放。
同事（Reader/Editor）engine 判定/执行/路由代码 + 前端 React + 知识库文档。
解耦前后端靠 openapi.json 自动发现接口，同事不需要跑 13GB 数据库。
💡"能改"不是一个权限，是三个（改口径 / 改标签 / 触发刷新）——物理切开，否则误操作炸全局。
主仓 + 外部依赖仓各自 remote，main 保护，MR review。
1
拉最新：git checkout main && git pull（绝不直接推 main）
2
建分支：git checkout -b fix/功能描述（语义化：fix/ feat/ docs/）
3
改 + 本地验证：起服务 + health 检查 + 跑相关逻辑
4
推送：git push -u origin <分支> → 网页建 MR
5
assign review：assign 给该层 owner review → 合并
口径配置只能走 git PR（考核口径/现金公式这类文件），合并后服务热加载，不接受在线 POST 改——天然有 review + 可回滚。外部依赖仓（如 CLI、前端）各自有 remote，单独 clone，主仓 .gitignore 排除它们。
同事"不能做什么"和"为什么不能"。
1. 不直接推 main
2. 不碰数据底座仓（数据归底座 owner）
3. 不在线改考核口径配置
4. 不碰凭证/依赖文件（.pylibs / tokens / odps 配置）
5. 不在代码里写死绝对路径
6. 不擅自改外部依赖仓（除非明确分配）
7. 写操作不跳确认（建组/调价/充值代码必须 review）
鉴权与写操作防护：轻量 token + 角色绑定，读写端点物理分离（/api 只读、/write 写、/admin 运维）。所有写操作统一要求：审计日志 + 可回滚 + 任务锁 + dry-run + 口径走 git。
同事不跑大数据库，配 env 指共享服务。
🔑 必配 env
数据底座服务 URL + reader token（多人协作必配）。问底座 owner 要，别自己造。
🔀 取数双路径
HTTP 优先（指共享服务），回退 SQLite（单机开发可走）。多人协作必须配 env 指共享服务。
同事不需要本地跑大数据库（十几 GB 太重），只配 env 指底座 owner 的共享服务地址。地址是沙箱会话 URL 的话重启会变，要问 owner 要新地址。真账户写操作在开发环境拿不到真 token，物理上杜绝误操作。
用编号体系标待办，已知坑写进记忆防重踩。
待办编号体系：用字母标类别/优先级（如 L=测试基建、B=服务切流），让团队对"当前最大技术债是什么"有共识。
⚠️ 协作坑
硬编码路径（要 env 化）、测试基建缺失、凭证泄露面扩大、共享数据库并发覆盖（任务单飞锁防）、沙箱地址会变需人工通知。
⚠️ 数据/代码坑
旧服务杀不掉（忽略 SIGTERM）、前端仓未提交改动、口径漂移需历史快照回归、知识库与代码不同步（动代码要更新知识条目）。
💡踩过的坑一定要写进项目记忆/知识库，下次新人/AI 进来就能避坑——不写下来等于每个新人都要重踩一遍。
1. "能改"不是一个权限，是三个改口径 / 改标签 / 触发刷新——物理切开，否则误操作炸全局。
2. 可融合的 vs 不可融合的，物理切开代码/文档/口径配置可融合（走 git）；本地数据/运行态/真账户写操作不可融合（物理隔离）。
3. 前后端靠 API 契约解耦做前端/后端的不需要懂数据底座，看接口文档就能对接，团队可并行。
4. 文档设计成"整份丢给 AI 执行"的 runbook接入指南/操作手册写成 AI 可自动执行的步骤，降低非技术同事上手门槛。
5. dev/prod 物理隔离真账户写操作在开发环境拿不到真 token，从物理上杜绝误操作——比任何"提醒"都靠谱。