飞书妙搭（apaas）平台的开发经验合集，供外部 AI Agent（Claude Code、Cursor 等）辅助开发时使用。
内容包括一份给 Agent 读的开发约定、一本踩坑手册，以及几个自动拦截脚本。
适用于妙搭专业版全栈应用，NestJS + Drizzle + React + Tailwind 模板。
自动拦截部分依赖 Claude Code 的 hook 机制。使用其他工具时文档部分照常可用，拦截不生效。
手册第 7 节（验证方法论）和第 8 节（shell 陷阱）不依赖妙搭平台，其余内容仅在妙搭上成立。
所有平台行为结论实测于 2026 年 8 月至 9 月。妙搭在持续更新，以下三条最可能已经变化，使用前建议自行验证一次：
- 平台 cron 最小间隔 30 分钟
- 线上日志只收集请求和触发器上下文内产生的日志
- 部署产物的 node_modules 按静态 import 裁剪
手册里写了每一条的重验方法。发现哪条失效，欢迎开 issue。
| 文件 | 说明 |
|---|---|
AGENTS.md |
给 Agent 读的开发约定。平台认知、五条工作规则、验证方法论 |
妙搭平台踩坑手册.md |
83 条经验，按情境分为 10 节 |
harness/ |
3 个拦截脚本 + 权限配置 |
scripts/db-index-audit.js |
检查 schema.ts 与真实库的索引差异 |
git clone https://github.com/Lens-lzy/miaoda-agent-kit.git
cd miaoda-agent-kit
bash install.sh /path/to/your/app_xxxxxxxx安装脚本会把文件放到对应位置，并跑一次自检确认拦截生效。之后需要在 Claude Code 里打开一次 /hooks 让配置加载。
接着告诉你的 Agent：
先读
AGENTS.md，这是妙搭平台的开发约定。遇到数据库、发版、飞书集成、定时任务、写验证脚本的时候，查妙搭平台踩坑手册.md。
不想安装的话，直接把 AGENTS.md 和 妙搭平台踩坑手册.md 交给 Agent 也可以。
三个例子，都是通用 Agent 容易判断错的地方。
发版不等于上线。 妙搭发版部署的是远端分支上已有的提交。代码只在本地改完、没有 push，发版会部署改动之前的版本，并且提示成功。完整链路是改代码、commit、push、后台发版四步。确认代码是否真的部署，用 lark-cli apps +release-get 拿到 commit_id，再 git merge-base --is-ancestor 比对。
server/database/schema.ts 是生成物。 它由 npm run gen:db-schema 生成，手写内容在下次生成时消失。Drizzle 的 introspection 表达不了条件索引和表达式索引，而这两类常常承担项目全部的业务唯一性约束。镜像里丢掉 WHERE 之后，代码读起来像全表唯一，库里实际是部分唯一。真实 DDL 应该维护在 scripts/sql/ 下。
应用收不到未登录的入站请求。 /api/ 路径下未登录请求会 302 跳 SSO，/openapi/ 路径下返回 403。飞书的事件回调 webhook 因此无法送达，接回调需要改用长连接（lark.WSClient）。
文档需要 Agent 主动去读才起作用，上下文变长之后容易被忽略。harness 里的拦截由 Claude Code 执行，不依赖 Agent 的记忆。
举例：「schema.ts 是生成物，不要手写」这条规则在原项目里以文档形式维护了三周，某次重新生成时仍然丢掉了 16 处手写的 .where(...)。改成 hook 之后不再发生。
| 操作 | 动作 | 原因 |
|---|---|---|
写 server/database/schema.ts |
拒绝 | 生成物，内容会消失 |
lsof -ti :A :B |
拒绝 | 多端口写法非法，命令报错退出，后续判断会误认为端口已清空 |
写 package.json / scripts/ 等平台托管文件 |
确认 | 会被 miaoda app sync 重写 |
git checkout <文件> |
确认 | 还原到 HEAD，会一并删除该文件所有未提交改动 |
git push --force |
确认 | 被拒时的规范做法是 rebase |
| online 环境的 DDL | 确认 | online 分支禁止 DDL |
检查类命令带 --silent |
确认 | 会静音 npm 的 "Missing script"，脚本名写错时表现为通过 |
拦截规则来自原项目实际发生过的错误。25 个用例的回归测试，含反例。实现细节见 harness/README.md。
手册第 7 节讲一类错误：检查本身没有运行，却给出了通过结论。原始记录里出现过至少六次。
| 现象 | 实际情况 |
|---|---|
npm run ts:server --silent 连续几轮全绿 |
该脚本不存在，--silent 静音了 npm 的报错 |
| 「返回 0 条，没有坏样本」 | 请求路径写错，返回 404 JSON，被当成空列表。空集合满足一切全称命题 |
| 「端口都空了」 | 命令写法非法直接报错，$(...) 展开为空 |
| 「改文案返回 200」 | 只断言了状态码没有回读，后一步的请求把前一步的写入覆盖了 |
| 榜单单测全绿 | 断言的是 SQL 文本内容，而那条 SQL 从未成功执行过 |
对应的做法是：先断言前置条件再断言结论，检查类命令不加 --silent，写入类验证做回读比对，SQL 在真库上执行一次并确认结果不全为 0。
这一节不依赖妙搭平台，用 Agent 写验证脚本时都适用。
一个妙搭项目，一个人配合 Claude Code 开发 36 天，从接手到上线前。
| 开发周期 | 36 个自然日，26 个有效工作日 |
| 净活跃时长 | 约 128 小时 |
| 产出 | 45 个页面、342 个接口、98 张数据表、4,373 个测试用例 |
| 原始记录 | 162 条 |
| 本仓库收录 | 83 条（44 个详细条目，39 条速查事实） |
剔除的 79 条是业务特有的，换项目不成立。
净活跃时长的算法：同一会话内相邻事件的间隔累加，单段超过 10 分钟按 10 分钟计。换 5 分钟阈值是 107.7 小时，15 分钟是 142.6 小时。
欢迎补充新的条目，或者指出已经失效的条目。后者同样有价值，失效条目会标注作废日期保留，不直接删除。
仓库里有 issue 模板。格式要求见 CONTRIBUTING.md，其中「代价」一栏请不要省略，它是判断一条经验是否值得遵守的依据。
收录标准：一个错误如果只能靠「下次小心点」来避免，就应该写下来。