@lark-project/cli/skills/meegle-plugin/references/workflow-overview.md

飞书项目插件开发工具

---
name: meegle-plugin-workflow
version: 2.0.0
description: |
  Meegle 插件从零创建的完整编排（新插件全流程）：创建工程 → 配点位 + 生成代码 → 本地调试确认 → 完善信息 → 发布上线 → 输出分享链接。
  当用户说"从零做一个 xxx 插件"、"新建一个插件"、"我需要一个 xxx 插件"、"帮我做个 xxx 插件"、"飞书项目插件开发"、"Meegle 插件开发"等**整插件级别**的意图时触发。
  **仅适用于新插件场景**：入口守卫会检查当前目录是否存在 `plugin.config.json`——已存在则说明是已有插件工程，应引导用户切换到 feature phase（功能迭代）。
  存量插件加功能 → feature phase；只改插件元信息 → polish phase；只发布 → publish phase。
metadata:
  requires:
    bins: ["npx"]
  cliHelp: "lpm --help"
---

# meegle-plugin-workflow Skill（新插件全流程）

## 入口守卫（MUST — 第一步，先于任何 Read）

> 本守卫**必须在读任何 reference 或 shared 规则之前**执行——只跑一条 bash 命令，不依赖任何 skill 知识。目的就是：如果当前目录已是插件工程，直接 bail，不继续加载 Phase 0/1/create 相关内容，省 token。

```bash
test -f ./plugin.config.json && echo "EXIST" || echo "NOT_EXIST"
```

| 检查结果 | 处理 |
|---------|------|
| `NOT_EXIST` | ✅ 继续下方"最少 Read 清单" → Phase 0 → Phase 1 → … |
| `EXIST` | ⛔ **立即停下**，不得 Read 本 skill 其它 reference、不得读 shared、不得进入 Phase 0。告知用户："检测到当前目录已有插件工程（`plugin.config.json` 存在）。新插件全流程会与既有工程冲突。如果要在此插件上加功能请走 `feature phase`；如果只改元信息走 `polish phase`；如果只发布走 `publish phase`；如果确认要创建新插件请先切到空目录或删除 `plugin.config.json` 后重试。"等用户决策，不得继续 |

守卫设计理由：本 skill 的 Phase 1 会执行 `create` 创建工程，在已有 `plugin.config.json` 的目录跑会破坏既有状态。把守卫放到最前、先于任何 Read，可以避免 AI 路由误命中时仍加载一堆 create 相关 reference 浪费 token。

## 本 skill 的最少 Read 清单（守卫通过后再读）

**守卫返回 `NOT_EXIST` 之后再启动时只读 2 份**（把"立刻能跑 create 前"需要的规则读完即可）：

- 本 SKILL.md（守卫、核心理念、checkpoint 机制，已在本次 Read 中覆盖）
- Phase 0 上下文采集 → Read [`workflow-phase-0-context.md`](workflow-phase-0-context.md)

**按需延后读**（进入对应阶段前再 Read）：

- Phase 1 搭建工程 → `workflow-phase-1-scaffold.md`（Phase 0 结束、准备 create 时读）
- Phase 2 功能实现 → `workflow-phase-2-feature.md`（Phase 1 结束后读）
- Phase 3 发布上线 → `workflow-phase-3-release.md`（Phase 2 结束后读）
- 共享规则 [`shared.md`](shared.md)：全量提交、删除点位前置检查等 **Phase 2 Stage Config 开始前**再读。Phase 1 create 阶段所需的"真实数据动作显式确认"（根原则 3）已直接内联到 `create phase` 的 `create-plan.md` P3，就地执行即可。

一次性预加载全部 phase reference 会浪费 context 且多数规则用不到。

## 核心理念

**用户不需要知道"插件开发"的分步概念。** 用户说"我要做一个在看板上显示燃尽图的插件"，AI 识别这是新插件意图后，**自动跑完从创建到发布的全部流程**，把用户推到"拿到分享链接 / 可以给别人用"的完成态，不在中途停下让用户分步操作。

用户全程只在三个不可逆决策点做确认：
1. **Phase 2**：AI 推荐的点位方案是否符合预期（基于 schema 分析 + 用户原始需求）
2. **Phase 2 尾**：本地预览调试后，功能是否符合要求（不 OK 会回到 Phase 2 调点位或改代码）
3. **Phase 3**：发布前二次确认（`publish` 不可逆）

## 完整流程（Phase 0 → 3，线性执行）

```
入口守卫（无 plugin.config.json）
   ↓
Phase 0 — 上下文采集
   钉死 siteDomain（CLI 硬前置；仅在对话上下文持有，不写盘）
   ↓
Phase 1 — 搭建工程，需用户确认是否新建
   create phase（auth 由 CLI stderr 兜底，用户自跑 lpm login）
   产出：plugin.config.json + 可运行骨架
   ↓
Phase 2 — 功能实现（绑定两步 + 本地调试确认）
   feature phase（Stage Config 点位配置 → Stage Code 代码生成）
   → 本地调试：`lpm start --auto`
   → 用户确认功能 OK（不 OK 则回 Phase 2 迭代）
   ↓
Phase 3 — 发布上线
   polish phase（AI 总结生成名称/描述/分类）
   → 向用户展示发布清单 → 等用户显式确认（不可逆护栏）
   → publish phase（update → release → publish）
   → 输出分享链接
```

**Phase 1.2 首次落盘，Phase 2 才理解**：Phase 0 / 1.1 仅在对话上下文持有 `siteDomain` / `pluginId` / `projectDir` / `projectRoot` / `originalRequirement`，**不落盘**；Phase 1.2（cd 到 plugin-dir 之后）一次性写入 `<plugin-dir>/.lpm-cache/state.json`，这是 state.json 的零号写入点。Phase 2 的 config.plan / code.plan 从该 state.json 读 originalRequirement。这样保证 state.json 永远只在 plugin-dir 一处、与 CLI 写的 `events.jsonl` / `schema/` / `config/` / `mcp/` 同栖一个 `.lpm-cache/`，不会出现 parent / plugin-dir 两份分裂。编排层不对原话做任何解析、不推导默认值；各 Phase 的校验在自己真正需要的数据源（schema / point-type doc / MCP）到位时才做。

> 插件形态（`app_type=normal` / `ai_node` / `ai_field`）由 create skill plan 阶段决策、`lpm create --app-type` 写入 plugin.config.json；workflow 不再中转——Phase 2/3 的子 skill 与 CLI 都直接以 plugin.config.json 为权威源读取，避免 state.json 与 plugin.config.json 双源不一致。

**Phase 2 内部委托**：config + code 的细节全在 feature phase 里，workflow 只负责触发和 checkpoint；feature phase 内部自成闭环（Stage Config → Stage Code），执行失败时回报给 workflow。

> **命名空间约定**：workflow 用 `Phase 0/1/2/3`，feature 用 `Stage Config / Stage Code`。两套命名故意不重叠，便于 checkpoint `step` 字段拼接（如 `2.config.apply` 表示 workflow Phase 2 委托给 feature 的 config.apply 子步骤）。

**Phase 3 发布护栏**：publish 是不可逆外部动作——即使在新插件全流程里，进入 publish 前也 MUST 向用户展示"即将发布到 Meegle 市场，发布后所有人可见"的确认提示，等用户显式说"确认发布"才执行。

## 各阶段详细流程

- Phase 0 → 读取 `workflow-phase-0-context.md`
- Phase 1 → 读取 `workflow-phase-1-scaffold.md`
- Phase 2 → 读取 `workflow-phase-2-feature.md`
- Phase 3 → 读取 `workflow-phase-3-release.md`

## 使用方式

本 phase 通常由 meegle-plugin 的 router 自动路由进入(见上层 [`../SKILL.md`](../SKILL.md) §1 入口 SOP)。触发本 skill 时用自然语言描述意图即可,router 会按 cwd context + 意图路由到本 phase。

**显式入口**(高级用法 / 调试 / 断点续跑):触发本 skill 时显式说 `phase=workflow` 或 `phase=workflow phase=<N>`,可跳过 router 的 phase 选择,直接进入指定 step。

可用 phase:
- 默认:新插件端到端全流程(推荐,默认跑到发布)
- `phase=1` — 仅 Phase 1(搭建工程)
- `phase=2` — 仅 Phase 2(功能实现 + 本地调试)
- `phase=3` — 仅 Phase 3(发布上线)

## 进度追踪（Checkpoint 机制）

读写命令 / 更新协议（执行前后字段写法）/ 恢复语义（success 跳过 · failed 重试 · running 重跑）见 [`checkpoint.md`](checkpoint.md)（权威源）。workflow 在协议之外的特有约定：

- **首次写入时机**：Phase 0 / 1.1 不写盘（plugin-dir 未创建 / cwd 未切到位）；首次写入在 Phase 1.2（PHASE1_CWD_OK 通过后），把 `siteDomain` / `pluginId` / `projectDir` / `projectRoot` / `originalRequirement` 一次性落盘（详见 [`workflow-phase-1-scaffold.md`](workflow-phase-1-scaffold.md) 1.2）。create skill 不写 state.json，状态归属 workflow。
- **Phase 3 发布成功** → 删除 `.lpm-cache/state.json`（流程已完成）。
- **恢复摘要**：workflow 启动时读 checkpoint，有内容则先向用户展示摘要再续跑：
  ```
  📍 上次执行到 Phase {phase} — {stepName}
     最后完成：`{lastCommand}`（{lastCommandStatus}）
     下一步：{nextStep} → `{nextCommand}`
  继续吗？
  ```
- 被 workflow 调用的子 skill（feature / publish 等）同样更新此文件；独立调用时不强制。`.lpm-cache/` 应进 `.gitignore`（git 化指引见 [`publish-verify.md`](publish-verify.md) V3）。

## cwd 锚定规则

`context.projectRoot`（Phase 1.2 落盘的绝对路径）是插件工程目录的唯一权威锚点。Phase 1/2/3 全程每条 `lpm` 命令都带 `--cwd "<context.projectRoot>"` 前缀（[`shared.md` 执行约定](shared.md) 是唯一权威源）——CLI 执行前 chdir 到插件根，`plugin.config.json` 与 `.lpm-cache` 都按它解析，下游 dispatcher 子进程继承该 cwd。不依赖 shell 跨命令保留 cwd，也不依赖"上次 cd 进去了"。

- lpm 报"非插件目录"等错 → 当前命令漏了 `--cwd`，补上 `--cwd "<context.projectRoot>"` 重跑（`projectRoot` 在对话上下文里，断点恢复时用 `lpm --cwd "<projectRoot>" ai state get` 拿）
- 写 / 读 checkpoint 走 `lpm ai state set` / `get`（路径由 CLI 锚定，见 [`checkpoint.md`](checkpoint.md)）

## 关键设计原则

1. **新插件推到底**：默认跑到发布完成、输出分享链接——用户进来时的心智是"我要一个能用的 xxx 插件"，不中途停下让用户手动进下一步
2. **不可逆动作显式确认**：Phase 3 publish 前必须用户显式同意，这是唯一不可省略的护栏
3. **延迟填充**：插件名称/描述/分类在发布前（Phase 3 polish）由 AI 基于实际功能总结生成，不在 Phase 1 创建时问用户
4. **快速到调试**：Phase 2 尾部强制引导本地调试，让用户在发布前通过真实预览确认功能
5. **容错兜底**：每个 Phase 失败不影响已完成的步骤，可从 `.lpm-cache/state.json` 断点继续
6. **精确恢复**：checkpoint 文件记录每一步 CLI 操作状态，中断后能告知用户确切进度