🤖
09 · AI 施工手册
给 AI 和 Austin 的操作经验，团队成员不用看
这份管什么AI 动手改 Lark / Shopify / 发报告 / 装追踪 / 驱动浏览器时的能力边界与踩过的坑
谁要看Austin（以及每次开工的 AI）
和 01–08 的区别那 8 份是「人照着干活」的 SOP，这份是「AI 照着施工」的技术约束
凭证去哪查中台「🔑 API Key」与「🔐 账号与凭证」表，本手册刻意不写任何路径与 ID
🚨红线速查
五条最贵的教训，每一条都真花过钱或真出过错。赶时间只看这一节。
① Lark 自动化绝不替人记账
「点按钮自动新增财务流水」实测跑出半空坏记录：配置界面里引用芯片明明都在，运行时部分字段解析为空，收支类型空掉导致净额把 −1 算成 +1，直接写错账。三重致命＝自动化内部状态 API 读不到、坏了不报错、坏的方式是往账本写错数。
→ 自动化只用来「提醒人去记」，绝不用来「替人记」。账错比账缺更糟。
② curl 验不了 Shopify 前台
curl（无 cookie ＋ 类爬虫 UA）会被喂另一份缓存副本，可能几小时不更新。曾经连续 90 分钟显示旧口径、误判两轮、白做两次无效的强制 purge——最后浏览器一测，新文案一直都在，客户从没看到过旧内容。
→ 唯一可信＝真实浏览器跑页面内 JS 读 document.body.innerText。curl 只能查后台 API 的真实内容。
③ 限制权限 scope 根本不保护数据
以为「不给订单/客户权限」就安全了。真相：光 write_themes 就能借 Liquid 读全部订单客户数据 ＋ 注入盗刷脚本，完全绕过 API 权限闸。
→ 真防线是「只改草稿主题 ＋ 上线前 Austin 审 diff 后亲手发布」，是工作流纪律，权限配置替代不了。
④ 像素装没装，curl 和网络监控都会骗你
Shopify 像素跑在沙盒 worker 里，抓 HTML 和监控网络请求都会假阴性——明明装好了判定成没装（当天在 GA4 上被骗过一次）。
→ 只认页面内 JS typeof gtag / fbq / clarity ＋ 后台状态双向印证。
⑤ 含凭证和本机路径的报告绝不外发
本机路径、凭证位置、安全清单——三者任一出现，报告就只走「生成 HTML ＋ 本地打开」两步，跳过公网发布。
→ 团队手册里永远不写任何 ID / 密码 / 账号，一律指向中台凭证表。本手册自己就是按这条脱敏后才发出来的。
🗂️Lark Base
动任何表结构之前先读这节。多轮实测推翻过好几个「以为不行」的结论。
能力边界（现行结论）
| 能不能 | 做什么 |
|---|
| ✅ API 能干 | 建表 / 改表名 / 删表 · 加改删字段 · 读写删记录 · 建视图与改视图（含隐藏列、筛选）· 表单视图 · 公式列 · 查找引用列 |
| ❌ 只能 UI 点 | 汇总列 · 视图分组 · 页脚求和 · 表单的字段配置 · 侧边栏文件夹与表顺序 · 字段左右顺序 · 看板/画册视图的显示列与分组 · 建在公式列上的筛选 |
能力不足时先怀疑启动参数，不是权限
早期「不能加改删字段、不能建视图」的根因是 MCP 启动只加载了两个默认 preset，不是 Bot 权限缺失。在启动参数里补上字段/记录/表/视图的增删改接口、重启即可，不用去后台改权限。
公式列与查找引用列的破解法
直接创建公式字段会失败——因为建表那一刻字段 ID 还没生成，公式引用不了。但有两条路绕开：
| 要什么 | 怎么做 |
|---|
| 新建公式列 | 先建一个普通文本字段，再把它 update 成公式类型并传公式表达式，立即生效 |
| 改已有公式列 | 直接 update，传公式表达式即可 |
| 查找引用列 | 类型本身建不了，但读一个 UI 建好的看它内部就是一条公式 → 把那条公式塞进公式列，行为完全等价、纯 API 零 UI |
公式内部引用按字段 ID 不是按字段名——这就是早期用大括号写字段名全部失效的根因。也因为按 ID 绑定，字段改名不会破公式。
建表施工规范
建表顺序＝主键 → 前置普通列 → 关联列 → 引用公式列 → 其余列
API 加字段只能追加到最后一列，而列的左右顺序是视图属性、API 调不了。按这个顺序建，字段一次排到位、零手工拖动。关联列一律放表尾（双向关联本来就该在尾部，两件事对齐后补挂关联永不破坏顺序）。
| 场景 | 规矩 |
|---|
| 要加 ≥3 个字段 | 直接重建表，别逐个加 |
| 但哪些表不能重建 | 重建的真正代价不是数据，是公式列 / 表单视图 / 筛选视图 / 附件这四样搬不动。四样占全的表（如财务流水）永久豁免 |
| 删字段前 | 必须先列一遍字段核对 ID 和名字——凭返回顺序猜着删会删错（踩过，删错两个要重建补数据） |
| 字段命名 | 别带括号。「金额(原币)」会被公式解析器当成函数调用报错 |
| 改选项名 | 传原选项 ID 就地改，现有数据零丢失 |
| 改双向关联的名字 | 会互相覆盖 → 必须改两次：先改反向列，再回头改正向列，最后核对两边 |
容易静默失败的写法
| 场景 | 正确写法 | 错了会怎样 |
|---|
| 字段描述 | 传对象 {"text": "…"} | 传字符串 → 整表创建失败 |
| 关联字段写值 | 记录 ID 的字符串数组 | 传对象 → 转换失败报错 |
| 视图筛选（单选） | 选项 ID 的 JSON 字符串 | 传选项名或裸数组 → 报错 |
| 评分（⭐）字段 | 用数字 1–5 代替 | 直接建评分类型 → 请求体错误 |
改视图属性是整体替换
改「隐藏列」会连带清空筛选条件；而公式列上的筛选 API 又写不回去 → 凡是筛选建在公式列上的视图，绝对不能再用 API 改它的属性，否则筛选没了还补不回来。
正确顺序＝先用 API 建视图并设好隐藏列，最后才去浏览器补公式列的筛选。
产品行为认知（影响方案设计）
| 现象 | 怎么用 |
|---|
| 记录展开卡片只列当前视图的可见字段，竖排一列 | 治「字段太多」的正解＝按视图砍列，展开卡片跟着变干净。人工改数据一律「悬停行 → 查看 → 竖着填」，永远不用横向拖表格。字段多不是问题，视图不砍列才是问题 |
| 表单只能新建记录，不能改已有记录 | 数据由程序抓入的表不能用表单，会造成重复记录。表单只适合「人工从零录一笔」 |
| 表单可按条件显示题目 | 长表单不会变长——把可选关联挂进流程的正解 |
| 看板视图的显示列和分组都只能 UI 点 | 要两次手工才能用 → 除非拖卡片改状态收益够大，否则用表格＋筛选更划算 |
| 右键菜单里没有「复制记录」 | 「复制上月那行改个日期」这种省事办法在这里不成立 |
内嵌文档（docx）
| 坑 | 说明 |
|---|
| 上限 10 份 | 满了以后侧边栏「新建 → 文档」直接变灰不报错 |
| 「移除文档」≠ 删除 | 只是从 Base 移出，文档本身留在云盘 → 要腾位置可安全移出旧的 |
| 新建的文档 Bot 没有写权限 | Bot 对 Base 的权限只覆盖数据表，文档是独立文件不继承 → 每建一份新文档都要在「分享」里把 Bot 加为可编辑 |
| 文档标题 API 改不了 | 只能在页面上打字。而且侧边栏名字和文档标题是两个独立的东西，要分别改 |
| 正文可全 API 排版 | 有一次性灌整棵树的接口（含表格单元格内容），比逐块写快几十倍。覆盖重写＝先清空再灌 |
| 建不了的块 | 流程图。标题/正文/列表/代码/引用/待办/高亮块/分割线/分栏/图片/表格都能建 |
🛍️Shopify
改站或搭团队工具之前读这节。五个团队分发的坑都翻过车。
令牌：唯一正确的拿法
项目根目录有一个 chmod 600 的凭证文件（路径与内容见中台「🔑 API Key」表），用它换出来的就是可直连 Admin API 的令牌——不需要另建店铺自定义应用，这个误解耽误过一整轮。
| 坑 | 解法 |
|---|
| 本机 python 缺根证书，请求直接失败 | 一律用 curl 发请求，python 只做 JSON 解析 |
| 读不存在的文件时返回空 body | JSON 解析会炸，要 try 住 |
| 令牌 24 小时过期 | 每次开工重换。「昨天能用今天不行」优先查令牌链路，别先怀疑权限 |
| 密钥泄露风险 | 只走标准输入管道，不进命令行参数（命令行明文会进历史记录） |
MCP 写不了线上主题，补权限永远无解
写线上主题文件会被拦，提示「禁止写线上店面的主题文件」。这不是 Shopify 权限问题——拦截发生在请求到达 Shopify 之前，是连接器服务端自带的护栏。实证：把应用权限扩到全量 184 个 scope 之后照拦不误。
→ 解法＝用自己的令牌 curl 直连，全链路实测可写。以后遇到「主题改不动」直接走这条，不要再手改、也不要建新应用。
改文案时的三类隐蔽盲区
常规关键词扫描抓不到，改完前台还是旧的多半是它们。
| # | 藏在哪 |
|---|
| ① | 主题布局文件里的 JSON-LD 结构化数据（FAQ schema 曾漏网 4 处） |
| ② | 主页 meta 描述的真身在一个 snippet 变量里，不在后台偏好设置页 |
| ③ | 每个页面/产品的 SEO 描述是独立 metafield，与正文完全分离——查询里没有 seo 字段，必须查 metafields。改完正文前台仍显示旧口径，基本就是它 |
🔴 团队分发的五个坑
① 成员的界面禁出网，本地 MCP 必死
成员跑连接检查报 fetch failed，而 owner 端一切正常、门票也注入了。根因＝成员用的云沙箱禁止出网。
→ 给非技术成员的工具一律走远程 MCP（HTTP 端点），不要用本地进程。成员端零本地依赖，对任何沙箱和防火墙免疫。
② 建应用 ≠ 装到店
远程通道通了却报「应用未安装」；之前「实测可用」吃的是首次令牌的缓存，24 小时过期后露馅。建完必须走「安装应用」到店铺，验收要看后台「安装：1」，不能只测一次接口就算通。
③ 令牌 24 小时过期（同上）
④ 限制权限不等于保护数据（见红线速查 ③）
⑤ 插件怎么送到没有 GitHub 的成员手上
不是「连桌面版到 GitHub 就同步插件」（那只喂代码上下文、不装插件），也不用内嵌令牌那套。正解＝owner 在组织后台把私有仓接成插件市场并设为自动同步，中心化处理鉴权，成员零 GitHub、零令牌、零配置。同步约 30 分钟延迟。
凭证不落地成员侧：后端保险箱
密钥存服务端，服务端换令牌并代理接口，代码里硬白名单只放行主题/页面/产品/图片，订单、客户、折扣、结账一律拒绝。插件只是瘦代理，带一张门票调后端。实测三态齐全：白名单内放行 ✓ 订单被拒 ✓ 无门票被拒 ✓。
这套模式领途插件已经在用——PawChibi 重建时照抄，不要重新设计。密钥只线下私传，绝不进聊天窗口或 git。收回权限＝轮换密钥 / 卸应用 ＋ 移除员工账号 ＋ diff 线上主题查后门。
后台操作细节
| 事项 | 说明 |
|---|
| 应用配置是版本化的 | 改权限范围要发新版本才生效；店铺侧自动生效，无需手动重授权 |
| 凭证页的「轮换」 | 会作废旧密钥，非必要别碰 |
| 创建版本页断网会丢表单 | 权限文本框被清空并报格式错。重填技巧＝先只读收集全部权限名，再直接写文本框（批量点勾选框会被本机安全分类器拦，读和填文本框不会） |
| 店铺后台的「应用开发」页是空的 | 已迁到开发者后台，别在店铺后台找令牌入口 |
📤报告发布
出任何报告之前读这节。三步缺一不可。
交付三步
| # | 做什么 | 为什么 |
|---|
| 1 | 必须生成 HTML | 最终产出不能只在对话里给 markdown |
| 2 | 必须打开浏览器 | 终端里的本地文件链接点不开，只给链接等于没给 |
| 3 | 默认出公网分享链接 | 不用每次问。除非命中「不外发」清单 |
首页索引是自动生成的，它读两样东西
<title> 标签 → 索引里显示的标题；class="report-meta" 元素的文本 → 索引里显示的日期。
→ 写报告 HTML 时这两样必须有，否则索引里会显示成文件名 ＋ 空日期。排序按文件修改时间新→旧。
同链接覆盖（版本卫生硬要求）
改内容＝改同名文件后重新部署，链接绝不变。不开新版本页、不加日期后缀、不留 v1/v2，团队打开永远是最新。已在用这条规矩的：8 份团队手册、进度总控台、本手册。
🔒 四类绝不外发
| 内容 | 怎么办 |
|---|
| 本机路径 | 走「生成 HTML ＋ 本地打开」两步，跳过公网发布，文末标一句说明 |
| 凭证信息（令牌、密钥、密码的值或位置） |
| 安全清单（权限边界、防线设计、可攻击面） |
| 机密但要给外部看的（客户物料） | 单独开一个发布项目，随机后缀 ＋ noindex，不要混进常规域名 |
另外：HTML 正文里永远不写 Austin 的名字（对话里要称呼，文件正文不写），也不写任何 ID / 密码 / 账号（指向中台凭证表即可）。
精致页六标准
内部报告同样适用——朴素样式被明确反馈过「排版特别丑」。
| # | 要素 |
|---|
| 1 | 顶部结论卡一眼定调（先结论后理由） |
| 2 | 数字仪表盘（几个关键数字并排） |
| 3 | 吸顶跳转目录 |
| 4 | 彩色卡片分区，急事视觉最重 |
| 5 | 表格 / 时间轴代替长文 |
| 6 | 深浅色 ＋ 手机自适配 |
给 Austin 的报告，正文自检三条
① 有没有讲人话——一眼拿到结论，不绕（对外文案除外）②每处英文有没有配中文语境参考——不必逐字直译，要的是「这话在中文里什么意思」③能画图的地方有没有画图。
讲人话 ≠ 省略风险：风险、限制、代价照说，可放折叠或附录，但不能没有。
📊数据追踪
装或验任何追踪工具之前读这节。团队版说明见 07 手册，这里是技术约束。
判重：看不同 ID 的数量，不看脚本数量
Meta 正常就有 2 个脚本，Clarity 正常也有 2 个。看到两个就以为重复安装、动手删，会把正常装配删坏。判断重复的唯一依据是出现了几个不同的 ID。
🔴 装应用时三个「推销分叉」必须选最小项
| 工具 | 必须选 | 不能选 | 选错的后果 |
|---|
| Meta | 仅限广告 | 店铺和广告 | 会开 FB 店铺 → 客户站内结账绕过定制向导 → 订单没照片 ＝ 废单 |
| Meta 数据档位 | 增强 | 最大化 | 增强已含 CAPI；最大化只是多交客户个人数据 |
| Clarity | Clarity only | Brand Agents | AI 购物机器人与手艺人调性冲突 |
通则：onboarding 里凡是「要不要顺便打开 XX」的分叉，默认选最小项。扩档随时能加，装错了要拆很麻烦。
安装通道的硬约束
| 约束 | 说明 |
|---|
| Admin API 没有像素相关权限 | 像素这件事接口碰不了 |
| 手工塞配置块会被静默丢弃 | 不报错，就是不生效，最难查 |
| → 结论 | 像素安装只能走浏览器或官方应用，这是极少数「必须开浏览器」的正当场景 |
| Clarity 最后一步 | 必须去主题编辑器打开 App embed 并保存，否则脚本根本不注入 |
搜索控制台
| 事项 | 说明 |
|---|
| 资源类型 | 选网域类型，DNS 验证，一劳永逸覆盖全子域 |
| 刚提交时的「异常」 | 「无法抓取」和「无 robots.txt」都是占位状态不是故障，刷新即正常 |
| 出数时间 | 需要 48 小时，别当天判定失败 |
三方像素盖不到的洞：定制向导
同页 JS 切换步骤不换 URL 的流程，三方像素全是黑箱——五步向导原本中间三步完全看不见。补法＝在唯一的步骤切换出口打点，同时打给三家，全部 try/catch 包裹、每步每会话去重。
⚠️ 改动带埋点的文件后必须重跑追踪健康自检——埋点代码混在业务逻辑里，改文案时极易被误删。
🖱️浏览器
驱动任何网页后台之前读这节。跨平台通用，平台特定的坑在上面各节。
坐标为什么会点错（两个根因）
| 根因 | 表现 | 解法 |
|---|
| 截图被缩放 | 视口宽大于截图宽时整体缩放。迷惑性在于外层大目标可能碰巧命中，但密集控件区整体偏移 | 把窗口调到截图 1:1 |
| 动画没结束就截图 | 浮层淡入中途的位置和最终位置差 25–30px | 展开后等 1.5–2 秒再截图取坐标 |
跨域 iframe：辅助功能树看不见
嵌在页面里的第三方应用是跨域 iframe，读不到里面的内容、拿不到元素引用 → 引用点击整套不可用，只能靠截图＋坐标，而坐标又受上面两条影响。
兜底：键盘导航万能
用 JS 让 iframe 获得焦点之后，Tab / Shift+Tab / Enter / 空格 / 方向键全部能进去。下拉框用「输入选项首词直接跳选」。这条比坐标点击稳得多，iframe 场景优先用它。
浮层与菜单
| 坑 | 怎么办 |
|---|
| 右键菜单第一次常常不响应 | 稳妥前奏＝左键点目标 → 等 → 右键 → 等 → 截图确认菜单真的开了 → 再点 |
| 菜单没开时后续点击会乱落 | 绝不要把右键和后续点击塞进同一批操作，可能误触别的东西 |
| 相邻两个下拉横向重叠 | 点在重叠段会命中错的 → 点右边那个就往右半边点，或先关掉前一个 |
| 选项多的下拉 | 优先用搜索框输入过滤，比按坐标点稳 |
🛑 这几类不要用脚本硬磕
| 操作 | 为什么 | 怎么办 |
|---|
| 拖拽（调列顺序、拖侧边栏、拖卡片） | 坐标一漂就破坏结构，且难回滚 | 直接留给人 |
| 多层 hover 菜单 | 实测成功率极低（某场景试 5 次成 1 次） | 人手 3 分钟的事，及早交回 |
| 原生文件上传弹窗 | 系统级窗口，脚本够不着 | 必须人工 |
| 批量点勾选框 | 会被本机安全分类器拦 | 改成读取标签 ＋ 直接写文本框 |
判断何时放弃的标准
如果这件事人手点 3 分钟能完成，而脚本已经试了两三轮还没稳定，就交回去。硬磕的成本远高于收益，而且中途乱点可能造成真实破坏。
提高成功率的杂项
| 做法 | 原因 |
|---|
| 保存优先点最外层的保存按钮 | 外层 DOM 的点击始终最可靠 |
| 改完配置记得点保存 | 只关面板不保存 → 改动不生效，然后你会以为是别处出了问题 |
| 侧边栏能折叠就折叠 | 常能腾出 300px，宽表格场景很有用 |
| 能用深链就别一层层点 | 很多后台子页面有稳定网址，直接跳过去比点导航稳 |
什么时候根本不该开浏览器
先问「有没有 API」——有就绝不开浏览器改。浏览器只在两种情况下是正当选择：① 这件事根本没有 API（像素安装、支付设置、授权、拖拽）；② 验收——看渲染结果，或验证客户实际看到什么（这一条上浏览器是唯一可信通道）。
用浏览器做 API 能做的事，是慢、易误操作、且不可回滚的三重亏。