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

飞书项目插件开发工具

# Meegle 插件 skill 合并：能力引导和约束等价性评估

> **来源**：本次合并(7 个 `meegle-plugin-*` → 单一 `meegle-plugin`)完成后,**派遣独立(fresh-context、不携带本会话任何决策)的 subagent**(`general-purpose` / sonnet)做的对照评估。
> agent 通过 `git show HEAD:skills/meegle-plugin-*/...` 读原版,通过 working tree 读合并版,逐项给判定。
> 报告内容是 agent 的独立结论;本文件下方 §"后续修复"段记录的是评估完成后针对其指出的 2 处轻微弱化所做的优化。
>
> **生成日期**:2026-05-20

---

## 总评

> **整体等价 + 净强化**——5 处明显强化、2 处轻微弱化(都非 blocking,且**已就地优化**)、3 个值得留意的执行期风险点。
> 所有关键 HARD GATE、不可逆护栏、三条红线、checkpoint 机制、共享规则均完整保留;核心约束**无实质性丢失**。

---

## 评估范围

- **原版**:HEAD 处的 7 个 `meegle-plugin-*` skill(7 个 SKILL.md + 全部 references)
- **合并版**:working tree 的 `skills/meegle-plugin/`(1 个 router SKILL.md + 49 个 references,含 `feature-point-types/` 子树)

---

## 维度逐项

### 1. 入口守卫 / 路由判定

**原版**:7 个独立 skill,各自 description 触发(关键词匹配),每个 skill 自己有 SKILL.md 级别的入口守卫(`test -f ./plugin.config.json`)。workflow EXIST → bail;create 独立触发 EXIST → bail;feature 不在工程内 → bounce 到 workflow;backend 没工程 → bounce 到 workflow;backend 意图新 feature → bounce 到 feature。路由是二阶的:description 选 skill + 守卫再过滤。

**合并版**:统一的 `meegle-plugin` description 包含所有原 skill 的触发词。进入后 SKILL.md §1 入口 SOP 三步走:Step 1.1 读断点、Step 1.2 探测 cwd、Step 1.3 按 context + 意图查 6 行 phase 路由表。各 phase 的 overview.md 内部仍保留 phase 专属守卫。

**判定:⬆️ 轻微强化**。原版"先误命中 → bail → 用户重触发"的中间状态在合并版被 Step 1.2/1.3 一次性消除;`external-backend` 第三种 context 在路由层显式区分,原版只在 backend setup 里处理。

### 2. 不可逆动作护栏

**原版**:shared/SKILL.md 列"五类必须先确认的动作";具体执行点散落在各 skill:create plan P3、config-apply A0、backend perm Step 4、workflow phase-3-release §3.2、publish apply A3(原版**无**)、workflow SKILL.md 设计原则。

**合并版**:SKILL.md §2"安全总纲"汇总四类确认点 + workflow 路径三个独立确认点;五类动作仍在 `shared.md` 中完整保留;各对应 reference 内的护栏字面等价;**新增** W47 规则明文(从 checkpoint 恢复到发布步骤时仍须重新走确认);**新增** publish-apply A3 的"发布前确认"内联节点(原版仅在 frontmatter 声明,apply.md 里无)。

**判定:⬆️ 强化**

### 3. 三条根原则(核心理念 / 设计原则)

完整迁移到 `references/shared.md`,内容字段级等价(三条原则、五类动作、全量提交约束、删除点位前置检查、无源即停四要素话术、MCP 缓存协议、认证、安全规则、自建后端红线等均逐行保留)。SKILL.md §0 把 `shared.md` 列为 Always Read First。

**判定:✅ 等价**

### 4. 阶段 / Step 序列

- create:setup → plan → apply → verify(4 mode)
- feature:Step 1 工程守卫 → Step 2 app_type 锚定 → Stage Config → Stage Code → 需要时调 backend
- workflow:Phase 0 → Phase 1 → Phase 2 → Phase 3(线性)
- polish:analyze → generate → confirm → apply(4 mode)
- publish:pre-check → apply → verify(3 mode)
- backend:setup → contract → perm → impl → integ-test(5 step)

全部保留,在 SKILL.md §3 各 phase 小节中以 Read 序列形式内联,每个 reference 文件内容字面等价。

**判定:✅ 等价**

### 5. 关键 Gate 和 HARD 约束

| 原版 Gate | 合并后去向 | 状态 |
|---|---|---|
| `app_type` HARD GATE(创建后不可转) | `create-plan.md` P1.5 | ✅ 等价 |
| P3 确认模板(逐字输出 normal/ai_node/ai_field 三套) | `create-plan.md` P3 | ✅ 等价 |
| cd HARD GATE(A3 单条 bash 切 cwd + verify) | `create-apply.md` A3 | ✅ 等价 |
| PHASE1_CWD_OK / PHASE1_CWD_FAIL | `workflow-phase-1-scaffold.md` §1.1 | ✅ 等价 |
| 2.0 cwd 守卫 HARD GATE | `workflow-phase-2-feature.md` §2.0 | ✅ 等价 |
| A0 闸口(ADDED/MODIFIED 三类齐全 + 用户明示) | `feature-config-apply.md` A0 | ✅ 等价 |
| A2 删除 gate(exit 2 → 逐字转呈 → 等明示) | `feature-config-apply.md` A2 + shared.md | ✅ 等价 |
| customField vs control 选型铁律(4 步) | `feature-config-plan.md` P2.5.1 | ✅ 等价 |
| P0 HARD-GATE(写 SDK 前 peek prop_key) | `feature-code-plan.md` P0 | ✅ 等价 |
| V4(扫 fetch('/api/proxy/*') → 后端判定) | `feature-code-verify.md` V4 | ✅ 等价 |
| perm apply 前置确认(三分支) | `backend-perm.md` Step 0 + Step 4 | ✅ 等价 |
| 3.2 发布前二次确认 | `workflow-phase-3-release.md` §3.2 | ✅ 等价 |
| publish A3 发布前确认 + W47 | `publish-apply.md` A3 | ⬆️ 强化 |
| DSL 字段必须先走 MCP fallback | `feature-config-plan.md` | ✅ 等价 |

### 6. Checkpoint / state.json 机制

文件格式(phase/step/stepName/lastCommand/lastCommandStatus/nextCommand/nextStep/timestamp/context)、写入规则(running/success/failed)、恢复规则(展示摘要 + 等确认)、零号写入点(Phase 1.2、不写 app_type 避免双源)、Phase 3 完成后删除——**全部字面等价**。SKILL.md §1.1 明确先读 state.json、有则展示恢复摘要并跳过 Step 1.2/1.3。

**判定:✅ 等价**

### 7. 错误处理 / 恢复路径

`references/errors.md` 三条内容等价(slash → phase 名替换);各 reference 内失败处理表字面等价。

**判定:✅ 等价**

### 8. 跨 skill 编排契约

**原版**:workflow 通过 `调用 /meegle-plugin-<X>` slash command 跨 skill 调起 create/feature/polish/publish;create 的 `orchestrated=true` 入参跳过其 EXIST 拦截;feature 检测后端需求 → Read backend SKILL.md;backend bounce 规则文字说明。

**合并版**:跨 skill 调用全部改为 in-skill Read 序列(workflow phase-1/2/3 reference 内显式写"按序 Read create-*.md / feature-*.md / polish-*.md / publish-*.md");`orchestrated=true` 废弃;backend bounce 规则等价保留(`feature phase` / `workflow phase` 命名)。

**判定:⚠️ 轻微弱化**(形式变化,实质约束保留,执行强度变化)。原版通过 slash command 跨 skill 调用让 create 的 EXIST 拦截在编排路径下被 `orchestrated=true` 强制跳过;合并版改为文字约定,跳过行为依赖 AI 自判。**详见下方 §"后续修复" W1 项**。

### 9. feature 触发 backend 双触发点

**原版**:feature-SKILL.md 明确两个触发点(Stage Config 判 webhook 形态点位 / code-plan / code-verify 发现 `/api/proxy/*` 代理);code-verify.md V4 有"两条都查"。

**合并版**:三个地方(SKILL.md §3、feature-overview.md、feature-code-verify.md V4)都保留;feature-overview.md **新增**"丢一个就漏调后端"警告。

**判定:⬆️ 强化**

### 10. backend 三条红线

backend-overview.md "红线"章节,三条顺序、措辞、细节约束(AI 不回显真值、不去 plugin.config.json grep/decrypt pluginSecret、引用 AUTHORING.md §8.1/8.2)字面等价保留。

**判定:✅ 等价**

### 11. backend bounce 规则

backend-overview.md 守卫 bounce 规则字面等价(两条 bounce 规则、话术模板、判别要点都保留,路径引用改为 `feature phase` / `workflow phase`)。

**判定:✅ 等价**

### 12. 共享规则覆盖完整性

| 原版 shared 覆盖点 | 合并版去向 | 状态 |
|---|---|---|
| 三条根原则(定义 + 执行细则) | shared.md | ✅ |
| 五类必须先确认的动作 | shared.md | ✅ |
| 插件工程识别(pluginId `MII_` 前缀) | shared.md | ✅ |
| 认证(domain 分域、`--site-domain` 传参、auth 错误转呈) | shared.md | ✅ |
| 安全规则(CLI 维护文件不直接 Edit/Write、禁止输出密钥) | shared.md | ✅ |
| 自建后端红线(凭据进 env / 运行时不依赖 lark-project/lpm) | shared.md | ✅ |
| 全量提交约束 + 底线 | shared.md | ✅ |
| `local-config set` 用户确认 gate | shared.md | ✅ |
| 删除点位前置检查协议 | shared.md | ✅ |
| 无源即停(合法源 / 非法源 / 四要素强制话术 / A/B/C 三选一) | shared.md | ✅ |
| MCP 检索技巧(6 行场景表 + 搜索心法) | shared.md | ✅ |
| MCP 缓存协议(Write 到 .lpm-cache/mcp/、≤100 字回复 + peek 重访、7 天过期) | shared.md | ✅ |
| Checkpoint 判断规则 | shared.md | ✅ |
| 错误处理入口 | shared.md | ✅ |

### 13. polish phase 独立进入前置 gate

**原版**:polish-SKILL.md 文字写"前提:feature 已执行完 Stage Code",**无 bash 检查守卫**;实际由 workflow Phase 3 编排保证顺序。

**合并版**:SKILL.md §3 polish phase **新增**前置 gate(`test -d src && find src -name '*.tsx' -o -name '*.ts' | head -1`),空 → 告知用户"代码尚未就绪,先走 feature phase"并停下。被 workflow Phase 3 编排进入时可跳过。

**判定:⬆️ 强化**

### 14. 点位标准能力 doc 覆盖

完全等价的目录结构和文件集:`feature-point-types/` 子树搬迁(button/index、componentSchedule/index、context-only、control/{form-control,index,table-cell}、customField/{index,value-shape}、dashboard/index、liteAppComponent/{index,read-props,write-outputs}、shared-scenes)。SKILL.md §3 feature 和 feature-overview.md 的读取指引等价(独立目录 6 类按 index + 命中维度;Tier 0 扁平 3 类共享 context-only;intercept/listen_event 无 doc 走 MCP)。

**判定:✅ 等价**

---

## 5 处强化项汇总

1. **统一路由 SOP**(SKILL.md §1)——消除原版"先误命中→bail→重触发"中间状态
2. **`external-backend` 第三种 context 路由层显式区分**——原版只在 backend setup.md 处理
3. **feature→backend 双触发点新增"丢一个就漏调后端"显式警告**——原版无此强调
4. **publish A3 内联 W47**(checkpoint 恢复 step≥3.3 时仍 MUST 重走 3.2 确认)——原版仅散落在 workflow 设计原则
5. **polish 独立进入新增 src/ 代码就绪前置 gate**——原版无,只有 workflow 编排顺序保证

---

## 等价但形式变更项(语义不变、表述/路径变更)

- 所有跨 skill 相对路径(`../../meegle-plugin-shared/SKILL.md`)改为同目录路径(`shared.md`)
- 所有 skill 名(`meegle-plugin-feature`)改为 phase 名(`feature phase`)
- skill description 中的 `meegle-plugin-*` 调用改为 phase 名词
- `orchestrated=true` 参数废弃,改为文字约定 + router 上游 gate
- workflow phase-1/2/3 reference 内"调用 /meegle-plugin-X mode=Y"改为"按序 Read X-*.md"

---

## 2 处轻微弱化(评估时发现,**已优化**——见下方 §"后续修复")

### W1:`orchestrated=true` 废弃后,create EXIST 拦截绕过依赖 AI 自判

**位置**:原版 `meegle-plugin-workflow/references/phase-1-scaffold.md` §1.1 + `meegle-plugin-create/SKILL.md` 入口守卫

**原版**:`调用 /meegle-plugin-create mode=pipeline orchestrated=true` —— create 收到 `orchestrated=true` 参数后**显式跳过** EXIST 拦截。可编程保证。

**合并初版**:在 workflow-phase-1-scaffold.md §1.1 用文字约定"若 create reference 文件里仍残留独立调用语境下的 EXIST 拦截 prose,按本编排路径**跳过**它"。跳过行为变成"AI 读约定后自判",而不是"入参强制保证"。

**为什么算弱化**:依赖 AI 在编排路径下记住这个约定;若 create-overview.md 的 EXIST 措辞足够强,AI 可能仍执行拦截并 bail。

**严重度**:**极低**——workflow 入口守卫已先验过 NOT_EXIST,create 路径上 plugin.config.json 不存在时 EXIST 拦截天然不触发。

### W2:Phase 2"编排层不预判"与显式 backend 触发说明的内在张力

**位置**:`workflow-phase-2-feature.md` §2.1

**原版**:`把控制权直接交给 meegle-plugin-feature`(一句话,完全委托;Phase 2 不知道 feature 内部怎么处理后端)。

**合并初版**:§2.1 同段先说"编排层不预判",第 4 条又写"feature 内部两个触发点都要扫——feature-config-plan.md P5 + feature-code-verify.md V4"。**双源描述**,潜在漂移。

**为什么算弱化**:编排层承担了部分 feature 子阶段的内部逻辑判断。若 feature V4 逻辑将来调整、§2.1 第 4 条没同步,出现版本漂移。

**严重度**:**极低**——目前两处描述一致,不构成实际执行风险,只是潜在维护风险。

---

## 后续修复(评估完成后就地优化)

### 针对 W1 — `create-overview.md` 入口守卫节重写

把"被 workflow 编排时跳过本守卫"的文字约定改为**显式说明守卫执行权由 router 接管**:

> **入口守卫执行权已由 router 接管(合并后)**:本 phase 是 `meegle-plugin` skill 的 create 子阶段。
> router(`../SKILL.md`) 的 §1 入口 SOP **已先验过**当前目录的 `plugin.config.json` 存在性(Step 1.2)、
> 并据此 + 用户意图路由到本 phase(Step 1.3)——`create phase` 只在两种情况进入:
> (a) `NOT_EXIST` + 用户要"空壳工程"(包括被 workflow 编排进入)
> (b) 显式 `phase=create` 入口
>
> 情况 (a) 下,plugin.config.json 不存在,下方 EXIST 拦截天然不触发。
> 情况 (b) 下,本 phase 仍按下方 EXIST 守卫保护。
>
> **简言之**:在合并路径下,你 Read 到本文件时 router 已做过等价或更上层的 gate;
> 下方守卫保留作**显式 phase=create + EXIST 兜底**和**独立读者(人类参考)**的语义注解。

**效果**:跳过条件从"AI 读约定自判"变为"由 router 上游 gate 显式保证"——逻辑闭合,不再依赖 AI 在编排路径下记住约定。

### 针对 W2 — `workflow-phase-2-feature.md` §2.1 第 4 条精简

把"两个触发点都要扫——P5 + V4"的具体判定从编排层移除,改为指向 feature 子阶段的权威源:

> 4. **需要后端那一半**:feature 子阶段会在其 reference 里自决(触发判据 = `feature-config-plan.md` 和 `feature-code-verify.md` 的权威源,**编排层不复述、不替它判**)。任一触发命中 → 按 feature 的指引进 backend 子阶段(按序 Read `backend-overview.md` → `backend-setup.md` → `backend-contract.md` → `backend-perm.md` → `backend-impl.md` → `backend-integ-test.md`),跑完再回到 Phase 2 完成态

**效果**:触发条件保持单一权威源(在 feature 子阶段),编排层只声明"feature 自决 + 触发后的下游路径",消除双源漂移风险。Read 序列保留以方便 AI 知道下游怎么走。

### 验证

修复后:
- 核心测试 52/52 通过(release/publish/install-skills/skill-triggers-regression/v2 services 等)
- `meegle-plugin/` 内 0 个失效 link
- 0 个 `/meegle-plugin-*` slash command 残留(合并彻底)

---

## 3 个执行期风险点(留意,非弱化)

1. **"不要 Skill()"是软约束**——弱 AI 误判重入 = 丢上下文。SKILL.md 顶部 Note 已明确,但靠 AI 遵守;原版跨 skill 边界有天然隔离。

2. **Step 1.3 无把握时列 6 phase 让用户选**——比原版"误命中后 skill 自己 bail"更依赖用户主动判断(更透明,但用户认知负担略高)。

3. **49 个 reference 平铺,命名约定是执行正确性的前提**——重命名某文件而 SKILL.md / overview.md 的 Read 路径未同步会**静默 404**。原版跨目录结构隔离更清晰。

---

## 复测建议

1. **workflow 编排路径下 create 的 EXIST 行为**:在已有 `plugin.config.json` 目录,不带参数触发 `meegle-plugin` 并说"从零做一个新插件" → 验证 Step 1.2/1.3 正确拦截,而不是让 create-overview.md 的 EXIST 守卫也拦一次。
2. **feature → backend 双触发点覆盖**:测试一个带 webhook 形态点位 + 代理路由的 feature,验证 P5 和 V4 都被识别并正确进入 backend。
3. **checkpoint 恢复时 publish 护栏**:从 phase=3.3 断点恢复,验证 SKILL.md §2 的 W47 规则和 workflow-phase-3-release.md §3.3 前置的"回 3.2 重新确认"被正确执行(不因 step 已记录而跳过)。

---

## 文件清单(本评估涉及)

- 原版(HEAD):`skills/meegle-plugin-{shared,create,feature,polish,publish,workflow,backend}/`
- 合并版(working tree):`skills/meegle-plugin/`(SKILL.md + 49 references)
- 评估相关文档(planning + 契约 + 评估):
  - `skills/MERGE_PLAN.md` — 合并方案
  - `skills/MERGE_CAPABILITY_LEDGER.md` — 能力台账(合并契约)
  - `skills/MERGE_EQUIVALENCE_EVAL.md` — 本文件