@lark-project/cli/skills/meegle-plugin/SKILL.md

飞书项目插件开发工具

---
name: meegle-plugin
description: |
  Meegle / 飞书项目插件开发的统一入口，覆盖插件全生命周期——创建工程、加/做/改/实现 feature、接住后端那一半的诉求（实现/补/改某点位服务端代码 → 申请 scope + 产交接包甩给后端会话）、完善信息、发布——进入后由内部 SOP 路由到对应 phase：
  - 从零做/新建一个插件/飞书项目插件开发/Meegle 插件开发（创建工程 → 配点位+写代码 → 调试 → 完善信息 → 发布上线）
  - 在已有工程上加/做/改/实现工作项 UI 元素（轻应用组件/按钮/Tab/视图/看板卡片/字段类型/表格列控件/详情页区块/排期组件 等）或它消费的平台数据；改点位展示逻辑/重新生成代码
  - 只建空壳工程/只完善插件名称描述分类/只发布上线（发布/上线/部署/release/publish）
  - 后端那一半——实现/补/改某点位服务端代码：收并验签 webhook 回调、调 Meegle OpenAPI 拿/写飞项数据、写回工作项/AI 节点/AI 字段、给前端提供 /api/proxy/* 代理、用 lpm perm 申请 OpenAPI scope；本 skill 做前置编排（申请 scope+汇总契约+产交接包甩给后端会话），「怎么写」由 meegle-plugin-backend skill 负责
  也含咨询/规划口吻——理一下流程/理一下后端流程、怎么配/怎么写/怎么实现、用哪些接口（webhook 怎么收、怎么验签、OpenAPI 用哪些）、什么时候调、能加吗/能不能开、权限怎么开通、帮我看下服务端那一半、我想搞清楚 xxx 怎么落地——落到本仓即"实现"路径，应触发本 skill 走 lpm 工具链而非通用文档查询。
  单条 CLI 命令查询/诊断走 meegle-plugin-cli；后端怎么写走 meegle-plugin-backend；业务数据（工作项/视图/需求/缺陷）走 meegle / lark-project。
metadata:
  requires:
    bins: ["npx"]
  cliHelp: "lpm --help"
---

# Meegle Plugin

> **本 skill 一次加载即完整。** phase 之间、step 之间通过 `Read references/<file>.md` 推进，
> **不要再次 `Skill(meegle-plugin)`**。被异步中断（如询问用户）后，直接从中断点继续即可。
>
> **本 skill 不主动 `task_create` / TodoWrite。** 状态追踪走 `lpm ai state get/set`（CLI 把
> `.lpm-cache/state.json` 锚定到插件根；协议见 [`references/checkpoint.md`](references/checkpoint.md)）。已有 todo 列表时只更新、不新建。
>
> 本 SKILL.md 负责 **phase 选择**（判用户意图 → 走哪个 phase）。`references/*-overview.md` 是各 phase 的理念 / 流程 / 守卫 + **该 phase 内部的 step/mode 序列**；
> 选定 phase 后 Read 对应 overview、按其序列执行——**phase 内部序列以 overview 为准，本文件 §3 只做 phase 选择 + 入口约束**。

## 0 · Always Read First

进入任何 phase 前先 Read 这两份（互不依赖，可并行 Read）：

- [`references/shared.md`](references/shared.md) — 共享规则：认证、权限不足处理、安全规则、三条根原则、全量提交约束、删除点位 gate、MCP 检索 / 缓存协议
- [`references/checkpoint.md`](references/checkpoint.md) — `.lpm-cache/state.json` 断点协议（被 workflow 编排、或需要断点续跑时遵守）

## 1 · 入口 SOP（路由）

### Step 1.1 — 断点续跑检查

跑 `lpm ai state get`（读当前目录的 checkpoint；空输出则跳过）：

- 有输出且含 `phase` / `step` → 向用户展示恢复摘要（上次到哪个 phase / step、`lastCommand` 状态、`nextStep`），等用户确认后**直接跳到该 phase**，跳过 Step 1.2 / 1.3。`lastCommandStatus="failed"` 时提示是否重试。
- 空输出 → 继续 Step 1.2。

### Step 1.2 — context 探测（确定性）

跑一条命令，按它输出的**单 token** 路由（判定逻辑在 CLI 里，这里只 pattern-match）：

```bash
lpm check context
```

| token | 动作 |
|------|------|
| `PLUGIN_PROJECT` | `context = plugin-project`（cwd 是已存在插件工程），`PLUGIN_DIR=cwd`，进 Step 1.3 |
| `BACKEND_HANDLE_CWD` | `context = external-backend`（cwd 是后端向工程——`plugin.config.json` 标了 `backendOnly`，与目录名无关），`PLUGIN_DIR=cwd`。按意图分流：**只写 / 改 handler 代码（点位已配全）→ 进 `meegle-plugin-backend` skill**（跳过 Step 1.3）；**要配 / 改点位配置 → 走 feature `stage=config`**（改点位即改数据，必经 Stage Config 护栏）|
| `NONE` | 先用一句话**复述你从用户原话里读到的需求**，再先问一个强感知问题——**这个插件要不要你自己写、自己迭代的前端界面（按钮 / Tab / 视图 / 看板卡片 / 详情页区块 / 自定义字段类型控件 等自定义界面）？** 按答案落点：<br>**① 要页面**：前端源码只活在你自管的 git 仓里，`lpm init` 只按模板 + 远端点位重建骨架、**拉不回你迭代过的前端代码**——从零新建 → `context = new-plugin`（空目录脚手架）；迭代**已有**前端插件 → **必须 `cd` 回管理该前端代码的原仓库**（`context = plugin-project`）；不在原仓就让用户切回去。<br>**② 纯服务端、不涉及页面**（webhook / OpenAPI / 写回 / AI 节点字段逻辑）：config 可从远端 `get --remote` 重建、身份锚可临时建，**任何位置可干** → `context = external-backend`，给 pluginId+secret+siteDomain 就地干：纯查 / 申请 OpenAPI scope 用 perm（token-only、不建目录）；点位已配全、只写 handler 代码 → 进 `meegle-plugin-backend` skill；**要配 / 改点位配置 → 建 config-only 工作区当身份锚（建法 + secret 见 [`feature-backend-handoff.md`](references/feature-backend-handoff.md) B2）→ `cd` 进去走 feature `stage=config`**（改数据必经 Stage Config 护栏）。⚠️ `ai_node` / `ai_field` / `listen_event` / `intercept` 整份配置都是后端用的、纯后端默认要配点位 → 默认 config-only；该纯后端插件**还没建** → 才回 `new-plugin` 用 `lpm create --app-type <无页面类型>` 建壳 |

### Step 1.3 — phase 选择

按 `context` + 用户原话查下表，**优先级从上到下、命中即停**。关键词是提示不是判定——用户措辞落在哪一行靠你在完整上下文里判断；**无把握时把这 5 个 phase 列给用户选**，不要猜。

| context | 用户意图信号 | phase |
|---------|-------------|-------|
| `plugin-project` | 在已有工程目录里又说"从零做 / 新建一个插件" | ⚠️ **拦截**：告知"当前目录已是插件工程，新插件全流程会破坏它；要在此工程上加功能用 feature，要新建请切到空目录"，等用户决定 |
| `plugin-project` | 加 / 改功能、加点位 / 按钮 / Tab / 视图 / 字段 / 控件、改现有点位逻辑 / 重新生成代码 | `feature` |
| `plugin-project` | 只补 / 改服务端那一半、纯 webhook / OpenAPI / 写回、不碰前端 | `feature`（内部走 stage=backend 产交接包）|
| `plugin-project` | 完善插件信息 / 改名称 / 改描述 / 改分类 | `polish` |
| `plugin-project` | 发布 / 上线 / 部署 / release / publish | `publish` |
| `new-plugin` | 从零做一个完整可用的插件（典型：用户描述一个功能需求） | `workflow` |
| `new-plugin` | 明确只要一个空壳工程骨架（"初始化插件项目骨架"） | `create` |

> `external-backend` context：只写 / 改 handler 代码时 Step 1.2 已进 `meegle-plugin-backend` skill（跳过本表）；要配 / 改点位配置则走 feature `stage=config`（直接进 Stage Config，同样不经本表的 phase 选择）。

**plugin-project 一律走 `feature`**：feature 内部按"碰不碰前端产物（`plugin.config.json` 的 `resources` / 点位 `entry`）"决定跑哪些 stage——
碰前端（要按钮 / 视图 / 卡片等 UI，哪怕同时要调 OpenAPI）→ 配点位 + 写前端，需要时末尾产后端交接包。
只动服务端、前端不变 → feature 直接走 `stage=backend` 产交接包（跳过 config / code）。"调 OpenAPI / webhook"措辞再强也先进 feature。

无命中 / 用户意图模糊 → 列出 `workflow / create / feature / polish / publish` 让用户选，不要默认。

### Step 1.4 — 进入 phase

按选定 phase 进入下方对应章节，先 Read 该 phase 的 `*-overview.md`（理念 / 流程 / phase 专属守卫），再按其 reference 序列执行。

显式入口：用户也可直接指定 phase（如发布场景），等价于跳过 Step 1.3 直接进对应 phase。

## 2 · 安全总纲（不可逆 / 真实数据动作——MUST 显式确认）

这些确认点贯穿所有 phase，**不可省略、不可被"看起来已确认"绕过**（详见 `references/shared.md` 根原则 3 的五类动作清单）：

- **创建插件**（`lpm create`，app_type 不可逆）→ create phase 的 plan 步骤向用户确认后才 apply。
- **推送配置到后台**（`lpm local-config set` / `update --source-type=local`）→ feature 的 config.apply A0 展示 ADDED/MODIFIED/DELETED 清单、等用户明示。
- **开通 OpenAPI scope**（`lpm perm apply`）→ feature「→ 后端那一半」的 `lpm perm` 步骤列出 scope 清单、等用户点头（仅 normal 插件；AI 应用工程不 apply）。
- **发布插件**（`lpm publish`，发布到 Meegle 市场、所有人可见、不可逆）→ publish / workflow Phase 3 / 后端那一半单独跑到 `lpm publish` 前 MUST 展示"即将发布"提示、等用户显式说"确认发布"。
- workflow 路径有**三个**独立确认点：①Phase 2 点位方案 ②Phase 2 尾本地调试确认 ③Phase 3 发布前确认。"开始 Phase 3"≠"确认发布"——是两次独立确认。从 checkpoint 恢复到发布步骤时，**仍须重新走发布前确认**，不能因 `step` 已记录就跳过。

## 3 · 各 phase

判定走哪个 phase 后 Read 对应 overview、按其序列执行（进每步前 Read 对应 reference，不预加载）。**phase 内部的 step 序列 / 守卫 / 执行细节都在 overview**；不可逆确认点见 §2。

| phase | 何时 | 入口 |
|---|---|---|
| `create` | 只建空壳工程骨架（不配点位、不写代码）| Read [`create-overview.md`](references/create-overview.md) |
| `feature` | 已有工程上加 / 改 feature（前端 / 后端 / 点位）| Read [`feature-overview.md`](references/feature-overview.md) |
| `polish` | 完善名称 / 描述 / 分类 | Read [`polish-overview.md`](references/polish-overview.md) |
| `publish` | 同步配置 + 构建 + 发布 | Read [`publish-overview.md`](references/publish-overview.md) |
| `workflow` | 从零端到端做完整插件 | Read [`workflow-overview.md`](references/workflow-overview.md) |

> **没有独立的 `backend` phase**：后端那一半不是平级 phase，只是 feature / workflow 末尾「需要后端时产交接包甩给后端会话」的一步——编排是一次 relay（A 后端就绪在 [`feature-overview.md`](references/feature-overview.md)、B 后端交接在 [`feature-backend-handoff.md`](references/feature-backend-handoff.md)）；服务端「怎么写」由接手会话召回 `meegle-plugin-backend` skill，本 skill 不 Read。坐自己后端仓直接问后端写法 → Step 1.2 的 `external-backend` 直接进 `meegle-plugin-backend` skill。