@lark-project/cli/skills/README.md

飞书项目插件开发工具

# Meegle Plugin Skills — 插件开发 Skill 集合

本目录包含 Meegle（飞书项目）插件开发的 Skill，由**三个** skill 组成。下面先把**每份 skill 到底要干嘛**（定位 / 目标 / 边界）讲清楚——这是后续所有改动的北极星，避免每次迭代各做各的、定位漂移。

> **实现对齐状态（2026-05）**：本 README 描述的是梳理定下的**目标定位**。已落地：代码 craft 知识独立成 `meegle-plugin-backend` skill；`meegle-plugin` 不再 Read backend skill（互不 Read）、不写后端代码（只产交接包甩出）；独立的 `backend` phase 已折叠进 feature 的 `stage=backend`（路由层 5 phase）。
> **仍待定**：`feature-overview.md` 的 `Stage Config / Stage Code` 命名（暂保留，`Stage` 是为避开 workflow 的 `Phase` checkpoint 命名空间而有意取的）；`external-backend` context 与 `config-only` 维持现状不动 —— 曾设想用"插件身份全局化 + 工作态 cache 的 local→global 解析"统一收口，但评估后认为复杂度过高、**已搁置**（设计存档见 [`PROPOSAL-global-identity-and-cache.md`](PROPOSAL-global-identity-and-cache.md)）。
> 读 SKILL.md 时以本文的定位为准、以 SKILL.md 的实际机制为执行依据，两者打架以本文为目标态。

---

## 一、三份 skill 各干嘛（定位章程）

### `meegle-plugin` —— 插件全 / 半流程编排器

**一句话**：站在**插件工程目录**里，把「新建 / 迭代一个飞书项目插件」从想法推到「可调试 / 可发布」的 workflow 编排器。它编排 `lpm` 工具链 + **前端**代码生成。

**它做**：
- 新建场景：初步澄清需求 + 定位 `app_type`（normal / ai_node / ai_field，不可逆）
- 迭代场景：在已有工程上做一个 feature
- 点位配置推送、权限申请（`lpm perm apply`）这些**前置工作**
- 完善信息、发布上线

**它不做（边界）**：
- **从不写后端代码**——任何点位的服务端那一半（webhook 收+验签 / 调 OpenAPI / 写回 / 代理）**一律产交接包甩给另一个会话**完成。后端上下文主要在业务侧，本 skill 不背。
- **不 Read `meegle-plugin-backend`**——plan 阶段评估「后端可行性」只用 `lpm perm list`（按 `app_type` 拉出有哪些 scope/OpenAPI 接口、读接口描述文案判够不够用），不查签名、不碰「怎么写」。
- 不碰 Meegle 业务数据（工作项 / 视图 / 需求 / 缺陷 → 走 `meegle` / `lark-project`）。

**5 个 phase**（路由层按 cwd 上下文 + 用户意图选；phase 间靠 `Read references/<file>.md` 推进、不重新加载 skill）：

| phase | 核心职责 | 触发场景 |
|------|---------|---------|
| `workflow` | 新插件端到端编排（Phase 0 澄清+钉站点+定 app_type → 1 搭建 → 2 feature → 3 发布） | "从零做一个 xxx 插件" |
| `create` | 只搭空壳工程骨架（`plugin.config.json` + 目录） | "只初始化插件项目骨架" |
| `feature` | 在已有工程上做一个 feature（主线见下） | "加个功能 / 点位"、"改功能"、"重新生成代码" |
| `polish` | AI 总结生成插件名称 / 描述 / 分类 | "完善插件信息"、"改名称 / 描述" |
| `publish` | 发布三步串行：update → release → publish（不可逆） | "发布"、"上线"、"release" |

> **没有独立的 `backend` phase**。后端不是平级 phase，只是 feature / workflow 末尾「需要后端时产交接包」的一步。

**feature 主线（plan → 前置 → code → 交接）**：

```
① plan      config.plan 出【前端点位配置方案】+【后端 perm 可行性早检（P5.1）】→ 初判 FE / BE / both
            ↳ 但「前端要 SDK 给不了的平台数据」型代理路由写前端时才暴露 → code.plan P3.5 / code.verify V4 允许补充识别后端那一半，识别即并进交接包（不是 plan 漏判，是 code 阶段才暴露的需求）
② 前置工作  点位配置推送 + 权限申请（lpm local-config set / lpm perm apply）
③ code      只写前端 React（纯后端形态整段跳过）
④ 交接      若需要后端 → 产交接包，甩给另一个会话（不自己写、不读 backend 知识）
```

### `meegle-plugin-backend` —— 后端开发知识（被召回）

**一句话**：纯后端「怎么写」的知识参考——webhook 接收+验签 / token 获取 / OpenAPI 出入参签名 / 写回工作项·AI 节点·AI 字段 / `/api/proxy/*` 代理 / `lpm perm list` token-only 查能调清单。

**性质**：**facts-free 代码 craft + 带源事实**。平台事实（要调哪些 OpenAPI / 签名 / scope / 验签 / 写回）逐条带源、可验证；据此写出的代码跑在沙盒外、`lpm` 不校验、无 `tsc`/`build` 反馈环，由接手者在自己环境联调自验。**不编排流程、不规定顺序**。

**谁召回它**：
- **接手会话（主路径）**：坐在自己后端仓里，拿着 `meegle-plugin` 产的交接包，召回它查「怎么写」、写代码、联调。
- 用户在后端仓直接问「webhook 怎么验签 / 这接口出入参啥样 / 这 app 能调哪些 OpenAPI」也直接命中它。
- **`meegle-plugin` 自己不召回它**——职责切干净：编排在 `meegle-plugin`，代码 craft 在这里，互不 Read。

### `meegle-plugin-cli` —— 原子化 CLI 命令 + 诊断

**一句话**：单条 `lpm` 命令参考 + 状态诊断（启动调试 / 构建 / 同步配置 / 查看配置 / 申请权限 / 报错排查）。**只服务插件工程自身的脚手架 / 配置 / 构建 / 调试 / 发布，不操作 Meegle 业务数据**。多步编排（发布 / 点位配置 / 代码生成）由 `meegle-plugin` 的 phase 直接处理，不经过本 skill。

---

## 二、路由分工

```
用户指令
  │
  ├─ 插件开发全生命周期（创建 / 加点位 / 写前端 / 完善信息 / 发布）—— 站在插件工程目录
  │     └─→ meegle-plugin          ── SKILL.md §1 入口 SOP 按 cwd + 意图路由到 phase：
  │            ├─ 从零做一个完整插件（"我需要一个 xxx 插件"）   → phase=workflow（端到端 create→feature→polish→publish）
  │            ├─ 只创建空壳工程骨架                            → phase=create
  │            ├─ 在已有工程加 / 改点位 + 前端代码              → phase=feature（需后端时末尾产交接包甩出）
  │            ├─ 完善名称 / 描述 / 分类                        → phase=polish
  │            └─ 发布 / 上线                                   → phase=publish
  │
  ├─ 后端那一半「怎么写」（webhook 验签 / OpenAPI 出入参 / 写回 / 代理）—— 坐在自己的后端仓里
  │     └─→ meegle-plugin-backend  ── 被交接包召回，或用户直接问后端写法时命中（不依赖插件工程目录）
  │
  └─ 原子 CLI 操作 / 单命令诊断（"启动调试" / "构建" / "同步配置" / "当前状态" / "报错排查"）
        └─→ meegle-plugin-cli      ── 单条 lpm 命令 + 状态诊断
```

### 分水岭

- **插件开发编排 + 前端那一半（配点位 / 写前端 / 完善信息 / 发布……）** → `meegle-plugin`
- **后端那一半「怎么写」（webhook / OpenAPI / 写回 / 代理）** → `meegle-plugin-backend`（在你自己的后端仓里召回；`meegle-plugin` 产的交接包是入口）
- **只跑一条原子 `lpm` 命令 / 诊断一个报错** → `meegle-plugin-cli`
- **Meegle 业务数据查询（工作项 / 视图 / 仪表盘 / 需求 / 缺陷）** → `meegle` / `lark-project`（不归本目录）

`meegle-plugin` 的每个 phase 各有**前置守卫**（见 `SKILL.md` §1 / §2 与各 `*-overview.md`）：
- 在已有工程目录里说"从零做新插件" → 拦截（避免破坏既有工程）
- cwd 不是插件工程却要"加功能" → 引导走 workflow（新插件全流程）
- 创建插件 / 推送配置 / 开通 scope / 发布等**不可逆 / 真实数据动作** → 执行前 MUST 显式确认

> **认证由 CLI 统一负责**：用户自行执行 `lpm login`（见接入文档）。skill 调 CLI 遇 auth 报错时，AI 逐字转呈 stderr 指引，由用户完成授权后重试。

---

## 三、目录结构

```
skills/
├── meegle-plugin/                    ← 编排 + 前端那一半：插件全生命周期（SKILL.md 内部 SOP 路由到 phase）
│   ├── SKILL.md                      （唯一路由层：§1 入口 SOP 按 cwd context + 意图选 phase）
│   └── references/
│       ├── shared.md                 ★ 共享规则（认证 / 安全 / 工具职责 / 插件工程识别 / 三条根原则 / 全量提交约束 / 删除点位 gate / MCP 检索协议）
│       ├── checkpoint.md             （.lpm-cache/state.json 断点续跑协议）
│       ├── errors.md                 （权限不足等错误处理）
│       ├── source-attribution.md     （前端不写 source 注释的说明 / reviewer 审计用）
│       ├── create-{overview,setup,plan,apply,verify}.md          （phase=create 创建工程骨架）
│       ├── feature-overview.md       （phase=feature 入口 + app_type 锚定）
│       ├── feature-config-{plan,apply}.md                        （feature 点位声明）
│       ├── feature-code-{setup,plan,apply,verify}.md             （feature 前端 React）
│       ├── feature-point-types/      （点位标准能力 doc）
│       │   ├── context-only.md       （configuration / page / view 合并扁平速查）
│       │   ├── shared-scenes.md      ★ 跨点位共享场景（详情页表单共享上下文）
│       │   └── liteAppComponent/ · dashboard/ · button/ · componentSchedule/ · control/ · customField/（各有 index.md + 维度子文件）· ai_node/（仅 card.md，前端面只在开节点卡片时存在，无 index.md）
│       ├── polish-{overview,analyze,generate,confirm,apply}.md   （phase=polish 名称/描述/分类）
│       ├── publish-{overview,pre-check,apply,verify}.md          （phase=publish 同步+构建+发布）
│       └── workflow-{overview,phase-0-context,phase-1-scaffold,phase-2-feature,phase-3-release}.md  （phase=workflow 端到端编排）
├── meegle-plugin-backend/            ← 后端那一半「怎么写」的知识参考（被交接包召回；不依赖插件工程目录）
│   ├── SKILL.md                      （知识索引：每类后端知识从哪取、哪些带源可验）
│   └── references/
│       └── backend-handoff.md        （交接包格式：把带源事实落成一份 md 交给接手会话）
└── meegle-plugin-cli/                ← 原子命令 + 诊断（单条 lpm 命令；不碰业务数据）
    ├── SKILL.md                      （路由表 + A/B 速查表；前置 Read meegle-plugin/references/shared.md）
    └── references/
        ├── commands.md               （原子命令参考）
        └── diagnose.md               （状态诊断 + 报错排查）
```

---

## 四、公共依赖

共享规则集中在 [`meegle-plugin/references/shared.md`](meegle-plugin/references/shared.md)，含：
- 插件工程识别规则（`plugin.config.json` + `MII_` 前缀）+ 执行约定（`lpm --cwd <绝对路径>` 锚定插件根）
- 统一认证（由 CLI 按 siteDomain 分域管理）
- 安全规则（禁止输出密钥、全量提交约束、删除点位确认协议、不可逆动作前确认）
- 无源即停通则（AI 输出每一项有业务语义的内容必须可溯源到合法信息源）
- Checkpoint 协议见 [`meegle-plugin/references/checkpoint.md`](meegle-plugin/references/checkpoint.md)（workflow 进度追踪 + 断点续跑）

`meegle-plugin` 在 §0「Always Read First」读 `shared.md` + `checkpoint.md`；`meegle-plugin-cli` 执行前同样先 Read `meegle-plugin/references/shared.md`。`meegle-plugin-backend` **不依赖** `shared.md`——它自足，「查不到即停、绝不编造」「凭据走 env」等规则写在它自己的 SKILL.md 里（它跑在你自己的后端仓、读不到本目录）。

---

## 写 / 改 skill 前先看

- [`AUTHORING.md`](AUTHORING.md) — 编写原则（正确性第一 / 校验归 CLI / 跨 OS / 多 agent / 弱 AI 友好 / 正向表达 / 引用 AI 可达 / 不写 changelog）+ `lpm ai peek` / `lpm ai checkpoint` 等工具公式