@lark-project/cli/skills/meegle-plugin-backend/references/backend-handoff.md

飞书项目插件开发工具

# handoff：把带源事实落成交接包

「接飞书项目要哪些平台事实」齐了之后（webhook 端点来自点位配置、能调的 OpenAPI 来自 `lpm perm list`、写回 / 出入参形态来自知识 MCP），把它们落成一份**交接包** markdown——这是接后端这件事里**唯一脱离插件工程目录、持久留存**的产物：既给当前会话写代码用，也留给后续接手的人 / 另一个 agent（换机器 / 换 agent，凭这份就能继续写后端，不必重新汇总契约 / 重跑 `perm list`）。

## 写哪里 + 怎么命名

写进**后端代码目录**（你自己的后端仓 / 服务目录，跟着后端代码走，不依赖 plugin-dir 的 cache）：

```
<后端代码目录>/meegle-backend-handoff-<pluginId>-<YYYYMMDDHHmm>.md
```

插件级、不带点位 id（一个插件一份，多点位在内部分段汇总）；时间戳到分钟。

## 模板（逐段填，每条平台事实都带源）

每条事实后标它的源（MCP doc 关键词 / `lpm perm list` 的 key / schema），让接手的人能复核、不必信你一面之词。

````markdown
---
plugin: <pluginId>
siteDomain: <siteDomain>
appType: normal | ai_node | ai_field
generatedAt: <YYYY-MM-DD HH:mm>
---

# 后端接入交接包：<插件名>

> 本交接包里的**平台事实**（OpenAPI 清单、webhook 协议、写回路径）来自可验证源，已逐条标注。
> 据此写出的**后端代码不在本流程的保证范围内**——在你自己的环境里联调验证（验签过不过、OpenAPI 返不返预期、写回生不生效）。

## 业务意图
<originalRequirement 原话 + 一句话目标>

## webhook（每个端点一行）
| 端点 / 点位 | 事件 / 触发判据 | 验签要点 | 源 |
|---|---|---|---|
| … | … | … | MCP `<关键词>` / schema |

## 要调的 OpenAPI（能调清单 ∩ 本次用到）
| 用途 | 接口（中文名） | 出入参源 | perm 现状 |
|---|---|---|---|
| … | … | MCP `<关键词>` | 已开通 / 待申请(normal) / 创建时全开(AI) |

## 写回路径
<work_item_id / task_id 怎么来 → 调哪个写入接口 → 回传什么字段>

## 运行环境
- 凭据：env `<变量名>`（真值由你设进后端 env；本流程不读、不回显）
- 语言适配：Go/Java 用官方服务端 SDK；TS/Node 逐接口查文档手写（语言适配见 [`../SKILL.md`](../SKILL.md) 「用 SDK 还是手搓 HTTP」）

## 实现 checklist
- [ ] 每个 webhook 端点：接收 + 验签
- [ ] token 获取（按语言用 SDK / raw）
- [ ] 每个 OpenAPI 调用在能调清单内（`normal` 超出 = 回插件会话 `lpm perm apply` 申请；AI 应用权限全开，无此步）
- [ ] 写回按上面路径
- [ ] `/api/proxy/*`（若前端组件有）
- [ ] 联调：真 webhook url/token 指过去、产品里触发、看日志

## 交接给后端会话执行（把本 md 整份贴进后端仓的新会话）
/meegle-plugin-backend 按本交接包实现该插件的后端那一半。
- 先召回 meegle-plugin-backend skill 取知识索引
- 每个 OpenAPI 调用照「要调的 OpenAPI」段的 MCP 关键词查出入参 / 鉴权；webhook 验签照「webhook」段的源查
- 验签 / token / 出入参 / 写回每一处平台事实都带源（MCP doc）；查不到就停下问，不猜签名、不编造协议
- Go / Java 用官方服务端 SDK，TS / Node 逐接口查文档手写
- 联调通过后把公网 webhook URL 回贴给插件会话（或去插件开发者后台改），由插件会话做第 2 次 `local-config set` 替换占位地址
````

## 产出后

- **你已坐在后端仓里（external-backend 入口）**：照这份交接包写代码——每个 OpenAPI 调用对着「要调的 OpenAPI」段的能调清单 + 源；怎么写（验签 / token / 出入参 / 写回 / 代理）走 [`../SKILL.md`](../SKILL.md) 的知识索引取。
- **从插件会话甩过来（跨仓）**：这份 md 自足（带源、可复核、末尾带执行 prompt），不必重新汇总契约 / 重跑 `perm list`——在后端仓**另起一个会话**贴进来，按末尾「交接给后端会话执行」段召回 `meegle-plugin-backend` skill 落地。