Lens-lzy

Miaoda Agent Kit — AI skill for Claude Code

AI community

在飞书妙搭（apaas）上用 AI Agent 开发的避坑手册 + harness.

How to install Miaoda Agent Kit

This entry records only its repository, not the path inside it, so there is no exact command to give. Open Lens-lzy/miaoda-agent-kit and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Miaoda Agent Kit does

在飞书妙搭（apaas）上用 AI Agent 开发的避坑手册 + harness。83 条实测踩坑，一条命令接入。

Alternatives in AI

Impeccable — The design language that makes your AI harness better at design 13.9k ★
ARIS Agent Guide — For AI agents reading this repo 6.2k ★
Osaurus — Own your AI. The native macOS harness for AI agents -- any model, persistent memory, autonomous execution, cry 5.1k ★

README

miaoda-agent-kit

飞书妙搭（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`](AGENTS.md) 和 [`妙搭平台踩坑手册.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`）。

harness 拦什么

文档需要 Agent 主动去读才起作用，上下文变长之后容易被忽略。harness 里的拦截由 Claude Code 执行，不依赖 Agent 的记忆。

举例：「`schema.ts` 是生成物，不要手写」这条规则在原项目里以文档形式维护了三周，某次重新生成时仍然丢掉了 16 处手写的 `.where(...)`。改成 hook 之后不再发生。

操作	动作	原因
写 `server/database/schema.ts`	拒绝	生成物，内容会消失
`lsof -ti :A :B`	拒绝	多端口写法非法，命令报错退出，后续判断会误认为端口已清空
写 `package.json` / `scripts/` 等平台托