diff --git a/docs/feishu/development_guide.md b/docs/feishu/development_guide.md
new file mode 100644
index 0000000..fd337f5
--- /dev/null
+++ b/docs/feishu/development_guide.md
@@ -0,0 +1,330 @@
+# 飞书 Bot 开发经验总结
+
+基于 `lark-oapi` Python SDK 的实战经验，涵盖接收消息、发送消息、文件上传、WebSocket 长连接等。
+
+---
+
+## 1. SDK 初始化
+
+```python
+import lark_oapi as lark
+
+client = (
+    lark.Client.builder()
+    .app_id(APP_ID)
+    .app_secret(APP_SECRET)
+    .log_level(lark.LogLevel.WARNING)
+    .build()
+)
+```
+
+`client` 是全局单例，线程安全，可在模块级别创建。
+
+---
+
+## 2. 接收消息：WebSocket 长连接模式
+
+飞书推荐使用 WebSocket 长连接（而非 HTTP 回调），省去公网暴露和回调验证。
+
+### 2.1 事件注册
+
+```python
+from lark_oapi.api.im.v1 import P2ImMessageReceiveV1
+
+handler = (
+    lark.EventDispatcherHandler.builder("", "")  # 加密 key 和验证 token，长连接模式留空
+    .register_p2_im_message_receive_v1(on_message)  # 注册消息回调
+    .build()
+)
+```
+
+### 2.2 启动 WebSocket 客户端
+
+```python
+ws_client = lark.ws.Client(
+    APP_ID,
+    APP_SECRET,
+    event_handler=handler,
+    log_level=lark.LogLevel.INFO,
+)
+ws_client.start()  # 阻塞调用
+```
+
+### 2.3 关键坑点：事件循环
+
+`lark_oapi.ws.client` 在 import 时捕获当前事件循环。如果你的主程序用了 `asyncio`（如 uvicorn），
+必须在 WebSocket 线程中创建新的事件循环并替换：
+
+```python
+import lark_oapi.ws.client as _lark_ws_client
+
+thread_loop = asyncio.new_event_loop()
+asyncio.set_event_loop(thread_loop)
+_lark_ws_client.loop = thread_loop  # 关键：替换 SDK 内部持有的 loop
+```
+
+### 2.4 断线重连
+
+`ws_client.start()` 在连接断开时会直接返回（不抛异常），需要自己包裹重连循环：
+
+```python
+backoff = 1.0
+while True:
+    try:
+        ws_client.start()
+    except Exception:
+        pass
+    time.sleep(backoff)
+    backoff = min(backoff * 2, 60.0)
+```
+
+### 2.5 解析收到的消息
+
+```python
+def on_message(data: P2ImMessageReceiveV1):
+    event = data.event
+    message = event.message
+    sender = event.sender
+
+    chat_id = message.chat_id          # 会话 ID（群/私聊）
+    msg_type = message.message_type    # "text", "image", "file", ...
+    content = json.loads(message.content)  # 消息内容是 JSON 字符串
+    text = content.get("text", "")
+
+    # 发送者信息
+    open_id = sender.sender_id.open_id  # 用户唯一标识
+```
+
+**注意**：
+- `message.content` 是 JSON 字符串，不是纯文本，需要 `json.loads`
+- 群聊中 @bot 的消息会包含 `@xxx` 前缀，需要用正则清除：`re.sub(r"@\S+\s*", "", text)`
+- 飞书遇到网络问题会在 ~60s 内重发相同消息，需要做**去重**（按 `(user_id, content)` + 时间窗口）
+
+---
+
+## 3. 发送消息
+
+所有发送都通过 `client.im.v1.message.create`，通过 `msg_type` 和 `content` 区分消息类型。
+
+### 3.1 `receive_id_type` 的选择
+
+| 值 | 含义 | 用途 |
+|---|---|---|
+| `"chat_id"` | 会话 ID | 回复到当前会话（群聊或私聊） |
+| `"open_id"` | 用户 open_id | 主动私聊某个用户（如通知） |
+| `"user_id"` | 用户 user_id | 同上，另一种 ID 体系 |
+
+**经验**：回复消息用 `chat_id`，主动推送通知用 `open_id`。
+
+### 3.2 发送纯文本
+
+```python
+content = json.dumps({"text": "Hello"}, ensure_ascii=False)
+request = (
+    CreateMessageRequest.builder()
+    .receive_id_type("chat_id")
+    .request_body(
+        CreateMessageRequestBody.builder()
+        .receive_id(chat_id)
+        .msg_type("text")
+        .content(content)
+        .build()
+    )
+    .build()
+)
+response = client.im.v1.message.create(request)
+```
+
+### 3.3 发送卡片消息（Markdown）
+
+卡片消息是飞书中展示富文本的主要方式。`msg_type` 为 `"interactive"`，content 为卡片 JSON。
+
+#### JSON 2.0 Markdown 卡片（推荐）
+
+```python
+card = {
+    "schema": "2.0",
+    "body": {
+        "elements": [
+            {
+                "tag": "markdown",
+                "content": "**粗体** *斜体* `code`\n- 列表项\n```python\nprint('hello')\n```",
+            }
+        ]
+    }
+}
+content = json.dumps(card, ensure_ascii=False)
+# msg_type = "interactive"
+```
+
+#### JSON 1.0 卡片（旧版，带标题栏）
+
+```python
+card = {
+    "config": {"wide_screen_mode": True},
+    "header": {
+        "title": {"tag": "plain_text", "content": "标题"},
+        "template": "turquoise",  # 标题栏颜色
+    },
+    "elements": [
+        {"tag": "div", "text": {"tag": "lark_md", "content": "**markdown** 内容"}},
+    ],
+}
+```
+
+**JSON 1.0 vs 2.0 的区别**：
+- 1.0 用 `lark_md` tag + `div` 容器，2.0 直接用 `markdown` tag
+- 2.0 支持标准 CommonMark，1.0 有较多语法限制
+- 2.0 支持表格、标题（`# ## ###`），1.0 不支持
+- 需要标题栏时用 1.0 的 `header`；纯内容展示用 2.0 更简洁
+
+### 3.4 发送文件
+
+两步流程：先上传文件获取 `file_key`，再发送文件消息。
+
+```python
+from lark_oapi.api.im.v1 import CreateFileRequest, CreateFileRequestBody
+
+# Step 1: 上传
+with open(path, "rb") as f:
+    req = (
+        CreateFileRequest.builder()
+        .request_body(
+            CreateFileRequestBody.builder()
+            .file_type("stream")  # "stream", "opus", "mp4", "pdf", "doc", "xls", "ppt"
+            .file_name(file_name)
+            .file(f)
+            .build()
+        )
+        .build()
+    )
+    resp = client.im.v1.file.create(req)
+    file_key = resp.data.file_key
+
+# Step 2: 发送
+content = json.dumps({"file_key": file_key}, ensure_ascii=False)
+# msg_type = "file"
+```
+
+---
+
+## 4. Markdown 语法速查（JSON 2.0 卡片）
+
+JSON 2.0 支持标准 CommonMark（除 HTMLBlock），外加飞书扩展语法。
+
+### 标准语法
+
+| 效果 | 语法 |
+|---|---|
+| 粗体 | `**text**` |
+| 斜体 | `*text*` |
+| 删除线 | `~~text~~` |
+| 行内代码 | `` `code` `` |
+| 代码块 | ` ```python\ncode\n``` ` |
+| 链接 | `[text](url)` |
+| 图片 | `![alt](image_key)` |
+| 有序列表 | `1. item` (4 空格缩进为子项) |
+| 无序列表 | `- item` |
+| 引用 | `> text` |
+| 标题 | `# ~ ######` (1-6 级) |
+| 分割线 | `---` 或 `<hr>` |
+| 表格 | 标准 Markdown 表格语法 |
+
+### 飞书扩展语法
+
+| 效果 | 语法 |
+|---|---|
+| @某人 | `<at id=open_id></at>` |
+| @所有人 | `<at id=all></at>` |
+| 彩色文本 | `<font color='red'>红色</font>` |
+| 标签 | `<text_tag color='blue'>标签</text_tag>` |
+| 飞书表情 | `:DONE:` `:THUMBSUP:` |
+| 带图标链接 | `<link icon='chat_outlined' url='...'>文本</link>` |
+| 电话链接 | `[显示文本](tel://号码)` (仅移动端) |
+
+### 特殊字符转义
+
+Markdown 特殊字符（`* ~ > < [ ] ( ) # : + " '` 等）需要 HTML 实体转义才能原样显示：
+
+| 字符 | 转义 |
+|---|---|
+| `*` | `&#42;` |
+| `<` | `&#60;` |
+| `>` | `&#62;` |
+| `~` | `&sim;` |
+| `` ` `` | `&#96;` |
+
+完整对照参考 [HTML 转义标准](https://www.w3school.com.cn/charsets/ref_html_8859.asp)。
+
+---
+
+## 5. 长消息处理
+
+飞书单条文本消息有长度限制（约 4000 字符），卡片消息整体 JSON 约 28KB。超长内容需要拆分：
+
+```python
+MAX_TEXT_LEN = 3900
+
+def split_message(text: str) -> list[str]:
+    """在换行符处分割，避免截断代码块或段落中间。"""
+    if len(text) <= MAX_TEXT_LEN:
+        return [text]
+    parts = []
+    remaining = text
+    while remaining:
+        if len(remaining) <= MAX_TEXT_LEN:
+            parts.append(remaining)
+            break
+        chunk = remaining[:MAX_TEXT_LEN]
+        last_newline = chunk.rfind("\n")
+        if last_newline > MAX_TEXT_LEN // 2:
+            chunk = remaining[:last_newline + 1]
+        parts.append(chunk)
+        remaining = remaining[len(chunk):]
+    return parts
+```
+
+多段发送时加 `await asyncio.sleep(0.3)` 避免飞书限流。
+
+---
+
+## 6. 异步兼容
+
+`lark-oapi` 的 SDK 方法全是同步的（阻塞 I/O），在 asyncio 环境中需要用 `run_in_executor`：
+
+```python
+loop = asyncio.get_running_loop()
+response = await loop.run_in_executor(
+    None,
+    lambda: client.im.v1.message.create(request),
+)
+```
+
+---
+
+## 7. 错误处理
+
+所有 API 调用检查 `response.success()`：
+
+```python
+if not response.success():
+    logger.error("code=%s msg=%s", response.code, response.msg)
+```
+
+常见错误码：
+- **权限不足**：机器人未添加到群聊，或未开通对应 API 权限
+- **receive_id 无效**：ID 类型与 `receive_id_type` 不匹配
+- **内容过长**：消息体超出限制
+
+---
+
+## 8. 实用模式总结
+
+| 场景 | msg_type | 发送函数 |
+|---|---|---|
+| 系统通知、短消息 | `text` | `send_text` |
+| LLM/AI 回复（含代码、列表） | `interactive` | `send_markdown` (JSON 2.0 卡片) |
+| 结构化信息（带标题栏） | `interactive` | `send_card` (JSON 1.0 卡片) |
+| 文件传输 | `file` | `send_file` (先上传再发送) |
+| 主动推送给用户 | 同上 | `receive_id_type="open_id"` |
+| 回复当前会话 | 同上 | `receive_id_type="chat_id"` |