Inner master

.agents/skills/changelog-generator/SKILL.md

@@ -19,6 +19,14 @@ description: 通过查看当前最新版本与上一版本间的git提交记录
 
 生成内容写入到 CHANGELOG.md 文件中。
 
+## 文档与 Skill 同步约束
+
+生成变更日志后，检查版本变更内容是否涉及**用户开发使用方式**（对外暴露的 API、配置项、模板/样式/脚本/JSON 能力、CLI 参数、生命周期、内建组件、环境 API、跨端行为差异等），如涉及则必须同步更新对应的文档与 Skill：
+
+- **文档**：更新 [docs-vitepress/](docs-vitepress/) 下对应位置的 `.md`，并按 [docs-vitepress/AGENTS.md](docs-vitepress/AGENTS.md) 的归档原则与索引要求同步侧边栏、导航及目录索引。
+- **Skill**：当变更涉及**跨端输出 RN 的能力**（模板/脚本/样式/JSON 配置维度、基础组件、环境 API 在 RN 平台的支持情况、Mpx2RN 编译行为等）时，必须同步更新 [.agents/skills/mpx2rn/](.agents/skills/mpx2rn/) 下的相关知识库。
+- 仅修改内部实现、重构、测试、构建脚本而不改变对外使用方式的变更项，无需更新文档或 Skill。
+
 ## 内容示例
 
 ```markdown

.agents/skills/mpx2rn-gene/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: mpx2rn-gene
+description: Mpx 跨端输出 RN 开发适配的 Gene 表达形式——基于 Gene Evolution Protocol (GEP) 将文档导向的 Skill 蒸馏为紧凑的 Strategy Gene 集合。当用户要求对已有 Mpx 组件进行 RN 跨端适配改造、创建符合 RN 跨端兼容规范的 Mpx 组件时调用。与 mpx2rn skill 的区别：mpx2rn 提供完整文档参考，本 skill 提供紧凑的行为控制指令，适合执行阶段直接注入上下文。
+metadata:
+  version: "1.0.0"
+  author: donghongping
+  based_on: mpx2rn
+  approach: gene-evolution-protocol
+---
+
+# Mpx2RN Strategy Gene Skill
+
+本 Skill 基于 Gene Evolution Protocol (GEP) 蒸馏为 8 个领域 Gene + 1 个演化控制 Gene，每个 ~200-300 tokens，直接控制行为而非解释文档。支持 GEP 三层结构（Gene / Capsule / Event）和六步演化循环。
+
+## Gene 注册表
+
+| gene_id | 触发信号 | 文件 |
+|---------|---------|------|
+| `gene_cross_platform` | 跨平台兼容, dual-track, 原平台 | [genes/gene_cross_platform.md](genes/gene_cross_platform.md) |
+| `gene_template` | template, wx:class, wx:style, wx:ref, 基础组件 | [genes/gene_template.md](genes/gene_template.md) |
+| `gene_style_selector` | selector, 选择器, 单类, compound, pseudo | [genes/gene_style_selector.md](genes/gene_style_selector.md) |
+| `gene_style_property` | style, flex, rpx, font-weight, display-none | [genes/gene_style_property.md](genes/gene_style_property.md) |
+| `gene_script` | script, lifecycle, mpx.xxx, api-proxy, selector-api | [genes/gene_script.md](genes/gene_script.md) |
+| `gene_conditional_compile` | 条件编译, @mpx-if, @mode, __mpx_mode__ | [genes/gene_conditional_compile.md](genes/gene_conditional_compile.md) |
+| `gene_text_overflow` | text-overflow, numberOfLines, hairlineWidth | [genes/gene_text_overflow.md](genes/gene_text_overflow.md) |
+| `gene_json_config` | json, usingComponents, disableScroll, tabBar | [genes/gene_json_config.md](genes/gene_json_config.md) |
+| `gene_evolution` | 演化, evolution, capsule, event, GEP loop | [genes/gene_evolution.md](genes/gene_evolution.md) |
+
+## 调度规则
+
+### 任务一：对已有 Mpx 组件进行 RN 跨端适配改造
+
+**始终加载：** `gene_cross_platform` + `gene_conditional_compile`
+
+**按 SFC 区块顺序加载：**
+1. `<template>` → 读取 `gene_template`
+2. `<script>` → 读取 `gene_script`
+3. `<style>` → 依次读取 `gene_style_selector` → `gene_style_property` → `gene_text_overflow`
+4. `<script name="json">` / JSON 配置 → 读取 `gene_json_config`
+
+**收尾：** 编译校验 → 按错误分类回到对应 gene 修正
+
+### 任务二：从零创建符合 RN 跨端兼容的 Mpx 组件
+
+**始终加载：** `gene_cross_platform` + `gene_conditional_compile`
+
+**全部 gene 并行加载：** 编写时直接遵循所有 gene 约束
+
+**收尾：** 编译校验 → ESLint 校验
+
+### 任务三：Gene 演化（适配经验积累）
+
+**触发信号：** 编译失败 / ESLint 报错 / 用户反馈纠正 / 适配方案不生效
+
+**加载：** `gene_evolution`
+
+**GEP 六步循环：**
+1. **Scan**：定位失败根因，收集错误日志/用户反馈
+2. **Signal**：映射到具体 gene_id（如样式不兼容→`gene_style_property`）
+3. **Intent**：确定演化类型（repair / optimization / extension）
+4. **Mutate**：修改目标 Gene 的 Strategy 或 AVOID 项
+5. **Validate**：重新执行编译校验，确认修正有效
+6. **Solidify**：写回 Gene 文件 + 记录 Event（`events/`）+ 记录 Capsule（`capsules/`）
+
+### 任务四：查阅已有经验（Capsule 检索）
+
+**触发信号：** 遇到同类任务时，先查阅 `capsules/CAPSULES.md` 中是否有可参考的成功路径
+
+**加载：** 对应 Capsule 中记录的 Gene 集合
+
+## 详细参考
+
+当 gene 中的策略指令不足以解决具体问题时，查阅详细参考文档：
+
+| 参考文档 | 用途 |
+|---------|------|
+| [模板能力参考](references/rn-template-reference.md) | 基础组件属性/事件支持明细 |
+| [脚本能力参考](references/rn-script-reference.md) | 生命周期/实例方法/组合式 API 支持明细 |
+| [样式能力参考](references/rn-style-reference.md) | 样式属性逐项支持情况 |
+| [样式开发最佳实践](references/rn-style-practice.md) | 常见样式兼容方案 |
+| [环境 API 参考](references/rn-api-reference.md) | mpx.xxx API 支持情况 |
+| [JSON 配置参考](references/rn-json-reference.md) | 页面/组件 JSON 配置支持 |
+| [条件编译](references/conditional-compile.md) | 各区块条件编译语法 |
+| [单文件组件](references/single-file-component.md) | Mpx SFC 基本结构 |
+| [Capsule 注册表](capsules/CAPSULES.md) | 已验证的成功执行路径 |
+| [Event 注册表](events/EVENTS.md) | Gene 演化变更日志 |

.agents/skills/mpx2rn-gene/capsules/CAPSULES.md

@@ -0,0 +1,34 @@
+# Capsule Registry
+
+> 已验证的成功执行路径。每个 Capsule 记录一次完整的 RN 适配任务执行，供同类任务参考。
+
+## Capsule 文件模板
+
+```markdown
+<!-- GEP Capsule Object -->
+<!-- type: Capsule -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: capsule_xxx -->
+<!-- created: YYYY-MM-DD -->
+
+## 任务签名
+<!-- 简要描述任务类型和上下文 -->
+
+## 使用的 Gene 集合
+<!-- 列出本次激活的 gene_id -->
+
+## 执行轨迹
+<!-- 关键决策点和操作路径 -->
+
+## 验证结果
+<!-- 编译校验 / ESLint / 运行时验证结果 -->
+
+## 谱系
+<!-- 关联的 Event ID（如因某次 repair 而产生） -->
+```
+
+## 已注册 Capsule
+
+| capsule_id | 任务类型 | 使用的 Gene | 创建日期 | 文件 |
+|------------|---------|------------|---------|------|
+<!-- 待积累 -->

.agents/skills/mpx2rn-gene/events/EVENTS.md

@@ -0,0 +1,37 @@
+# Event Registry
+
+> 不可变的 Gene 演化日志。每个 Event 记录一次 Gene 变更，保持可审计和可追溯。
+
+## Event 文件模板
+
+```markdown
+<!-- GEP Event Object -->
+<!-- type: Event -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: evt_xxx -->
+<!-- created: YYYY-MM-DD -->
+
+## 事件类型
+<!-- repair / innovation / validation_pass / validation_fail / solidify -->
+
+## 触发信号
+<!-- 什么失败/反馈触发了本次演化 -->
+
+## 变更目标
+<!-- 源 gene_id → 修改后的 gene_id -->
+
+## 变更意图
+<!-- 为什么要做这个修改 -->
+
+## 变更 Diff
+<!-- 具体修改了哪些 Strategy / AVOID 项 -->
+
+## 验证结果
+<!-- 修改后的编译校验 / 测试结果 -->
+```
+
+## 已注册 Event
+
+| event_id | 类型 | 目标 Gene | 触发信号 | 日期 | 文件 |
+|----------|------|----------|---------|------|------|
+| evt_001 | repair + extension | gene_template, gene_script, gene_style_property | iteration-8 eval 11条失败 | 2026-05-19 | [evt_001_iter8_repair.md](evt_001_iter8_repair.md) |

.agents/skills/mpx2rn-gene/events/evt_001_iter8_repair.md

@@ -0,0 +1,45 @@
+<!-- GEP Event Object -->
+<!-- type: Event -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: evt_001 -->
+<!-- created: 2026-05-19 -->
+
+## 事件类型
+repair + extension
+
+## 触发信号
+iteration-8 eval 执行结果：mpx2rn_gene 得分 52/63（82.54%），11 条断言失败，集中在事件传参/dataset 清理、内联样式简写、非触摸 catch 事件、RN 不支持样式属性等方面。
+
+## 变更目标
+- gene_template（repair: 强化 dataset 清理与内联传参；extension: 内联样式多值简写限制、border 简写限制、enable-var）
+- gene_script（repair: 禁用 dataset 取参；extension: catch 前缀限制、条件编译隔离 API）
+- gene_style_property（extension: radial-gradient、border-style 统一、background-repeat、text-decoration-style/color）
+
+## 变更意图
+覆盖 iteration-8 中 mpx2rn_gene 相比 mpx2rn_original 的 8 分差距中可归因于 gene 策略缺失的 11 条失败项，使 gene 版在下次执行时能正确处理这些场景。
+
+## 变更 Diff
+
+### gene_template.md
+- Strategy 4: "事件传参优先使用" → "事件传参**必须**使用内联传参语法，同时移除 data-xxx 属性；脚本中禁止 e.target.dataset"
+- 新增 Strategy 7: enable-var 声明
+- 新增 Strategy 8: 内联 style/wx:style 禁止多值 margin/padding 简写，须拆分单方向
+- 新增 AVOID 11: 内联 style 中 border 简写
+- 新增 AVOID 12: 保留 data-xxx 属性传递事件参数
+
+### gene_script.md
+- 新增 Strategy 6: 禁止 e.target.dataset / e.currentTarget.dataset
+- 新增 Strategy 7: 非触摸类事件不使用 catch 前缀
+- 新增 Strategy 8: RN 不支持的 API 须条件编译隔离（setTabBarBadge/removeTabBarBadge/getUserProfile）
+- 新增 AVOID 12: e.target.dataset / e.currentTarget.dataset
+
+### gene_style_property.md
+- 新增 Strategy 7: radial-gradient 须条件编译或替换
+- 新增 Strategy 8: border-style 统一设置，不支持单边 border-xxx-style
+- 新增 Strategy 9: background-repeat 仅支持 no-repeat
+- 新增 Strategy 10: text-decoration-style/color 须条件编译隔离
+- 新增 AVOID 14: radial-gradient
+- 新增 AVOID 15: 单边 border-xxx-style
+
+## 验证结果
+待 iteration-9 执行验证。预期覆盖 t1/t6/t8/j5/j8/l4/l8/l9/c2/c7/c9 共 11 条断言。

.agents/skills/mpx2rn-gene/genes/GENES.md

@@ -0,0 +1,74 @@
+# Mpx2RN Strategy Gene Registry
+
+> 本文件是 Mpx 跨端输出 RN 开发指南的 **Gene 表达形式**——基于 Gene Evolution Protocol (GEP) 将文档导向的 Skill 蒸馏为紧凑的、面向行为控制的 Strategy Gene 集合。每个 Gene 约 200-300 tokens，提供高信号密度的控制指令而非文档解释。
+>
+> 原始文档导向的 Skill 参见 [SKILL.md](../SKILL.md)，详细参考资料在 [references/](../references/)。
+
+## Gene 注册表
+
+| gene_id | 触发关键词 | 控制摘要 | 文件 |
+|---------|-----------|---------|------|
+| `gene_cross_platform` | 跨平台兼容, dual-track, 原平台 | RN 适配不可破坏原平台——双轨保留 | [gene_cross_platform.md](gene_cross_platform.md) |
+| `gene_template` | template, wx:class, wx:style, wx:ref, 基础组件 | 模板仅用 RN 支持的组件/属性/事件 | [gene_template.md](gene_template.md) |
+| `gene_style_selector` | selector, 选择器, 单类, compound, pseudo | 选择器全部单类化 | [gene_style_selector.md](gene_style_selector.md) |
+| `gene_style_property` | style, flex, rpx, font-weight, display-none | 样式属性使用 RN 兼容方案 | [gene_style_property.md](gene_style_property.md) |
+| `gene_script` | script, lifecycle, mpx.xxx, api-proxy, selector-api | 脚本统一 mpx.xxx + RN 支持的生命周期 | [gene_script.md](gene_script.md) |
+| `gene_conditional_compile` | 条件编译, @mpx-if, @mode, __mpx_mode__ | 各区块用对应语法，最小包裹 | [gene_conditional_compile.md](gene_conditional_compile.md) |
+| `gene_text_overflow` | text-overflow, numberOfLines, hairlineWidth | 文本溢出/极细线双轨模式 | [gene_text_overflow.md](gene_text_overflow.md) |
+| `gene_json_config` | json, usingComponents, disableScroll, tabBar | JSON 配置仅用 RN 支持字段 | [gene_json_config.md](gene_json_config.md) |
+| `gene_evolution` | 演化, evolution, capsule, event, GEP loop | GEP 六步循环驱动 Gene 持续演化 | [gene_evolution.md](gene_evolution.md) |
+
+## Gene 调度逻辑
+
+### 任务一：对已有 Mpx 组件进行 RN 跨端适配改造
+
+**始终激活：** `gene_cross_platform` + `gene_conditional_compile`
+
+**按 SFC 区块顺序激活：**
+1. `<template>` → `gene_template`
+2. `<script>` → `gene_script`
+3. `<style>` → `gene_style_selector` → `gene_style_property` → `gene_text_overflow`
+4. `<json>` → `gene_json_config`
+
+**收尾：** 编译校验（`scripts/compile-validate.js`）→ 按错误分类回到对应 gene 修正
+
+### 任务二：从零创建符合 RN 跨端兼容的 Mpx 组件
+
+**始终激活：** `gene_cross_platform` + `gene_conditional_compile`
+
+**全部 gene 并行激活：** 编写时直接遵循所有 gene 约束，避免写完再改
+
+**收尾：** 编译校验 → ESLint 校验
+
+## GEP 三层结构
+
+```
+Gene（原子控制单元）→ 直接注入推理时上下文，控制行为
+  ↓ 组合
+Capsule（已验证执行路径）→ 记录成功的 gene 组合 + 执行轨迹
+  ↓ 记录
+Event（不可变演化日志）→ 记录 gene 的修正/优化/验证历史
+```
+
+### Gene 层（genes/）
+8 个领域 Gene + 1 个演化控制 Gene，直接注入推理上下文控制行为。
+
+### Capsule 层（capsules/）
+记录成功的 RN 适配执行路径。每个 Capsule 包含：任务签名、使用的 Gene 集合、关键决策点、验证结果。详见 [capsules/CAPSULES.md](../capsules/CAPSULES.md)。
+
+### Event 层（events/）
+不可变的 Gene 演化日志。每个 Event 记录一次 Gene 变更的触发信号、变更 diff 和验证结果。详见 [events/EVENTS.md](../events/EVENTS.md)。
+
+### 演化循环（GEP Loop）
+```
+失败/纠正 → Scan → Signal → Intent → Mutate → Validate → Solidify
+                                                    ↓           ↓
+                                              更新 Gene    记录 Event + Capsule
+```
+演化由 `gene_evolution` 控制，触发信号包括：编译失败、ESLint 报错、用户反馈纠正、适配方案不生效。
+
+## 扩展参考
+
+- [SKILL.md（入口）](../SKILL.md)
+- [references/（详细能力参考）](../references/)
+- [scripts/（编译校验工具）](../scripts/)

.agents/skills/mpx2rn-gene/genes/gene_conditional_compile.md

@@ -0,0 +1,25 @@
+<!-- GEP Gene Object -->
+<!-- type: Gene -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: gene_conditional_compile -->
+<!-- signals_match: 条件编译, conditional-compile, @mpx-if, @mode, __mpx_mode__, 分平台 -->
+
+<strategy-gene>
+Domain keywords: 条件编译, @mpx-if, @mode, @_mode, __mpx_mode__, 分平台处理
+Summary: 条件编译是跨端不兼容的最后手段——各区块使用对应语法，最小包裹，禁止产生空选择器
+Strategy:
+1. 条件编译是最后手段：先确认是否存在无需条件编译的跨端兼容写法
+2. 样式区块：使用 /* @mpx-if (__mpx_mode__ === ...) */ 注释语法
+3. 模板区块：使用 wx:if="{{__mpx_mode__ === ...}}" 或 @mode/@_mode 属性后缀
+4. 脚本和 JSON 区块：使用 if (__mpx_mode__ === ...) 条件语句
+5. 平台条件——原平台：__mpx_mode__ === 'wx' || 'ali' || 'web'；RN：__mpx_mode__ === 'ios' || 'android' || 'harmony'
+6. 仅最小包裹不兼容片段，不要大面积条件编译分叉
+7. 样式条件编译必须包裹整条规则（含选择器+花括号内容），不能只包裹声明块内部
+8. AVOID: 在 style 以外的区块使用 /* @mpx-if */ 注释语法（不会生效）
+9. AVOID: 样式条件编译后产物中出现空选择器
+10. AVOID: 整段代码都用条件编译分叉（仅包裹真正不兼容的最小片段）
+</strategy-gene>
+
+<references>
+- [条件编译](../references/conditional-compile.md)
+</references>

.agents/skills/mpx2rn-gene/genes/gene_cross_platform.md

@@ -0,0 +1,21 @@
+<!-- GEP Gene Object -->
+<!-- type: Gene -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: gene_cross_platform -->
+<!-- signals_match: 跨平台兼容, cross-platform, dual-track, 条件编译保留, 原平台 -->
+
+<strategy-gene>
+Domain keywords: 跨平台兼容, cross-platform, dual-track, conditional-compile, 原平台保留
+Summary: 确保 RN 适配不破坏原平台行为——所有 RN 专有写法必须通过条件编译隔离，原平台原有写法必须完整保留
+Strategy:
+1. 引入「RN 支持但原平台不支持」的写法（如 numberOfLines@ios|android|harmony、hairlineWidth）时，用条件编译将其限定在 RN 平台输出
+2. 同步用条件编译保留原平台已有写法，禁止因 RN 适配而替换或删除原平台代码
+3. 该原则贯穿 template / script / style / JSON 四个维度，每个维度的条件编译语法不同（参见 gene_conditional_compile）
+4. AVOID: 只保留 RN 一侧实现而删除原平台写法
+5. AVOID: 不加条件编译直接用 RN 专有属性替换跨端通用写法
+</strategy-gene>
+
+<references>
+- [条件编译](../references/conditional-compile.md)
+- [样式开发最佳实践 · 双轨保留](../references/rn-style-practice.md#1-像素边框极细线)
+</references>

.agents/skills/mpx2rn-gene/genes/gene_evolution.md

@@ -0,0 +1,25 @@
+<!-- GEP Gene Object -->
+<!-- type: Gene -->
+<!-- schema_version: 1.0.0 -->
+<!-- id: gene_evolution -->
+<!-- signals_match: 演化, evolution, 迭代, capsule, event, 经验积累, GEP loop, solidify -->
+
+<strategy-gene>
+Domain keywords: 演化, evolution, GEP loop, capsule, event, 迭代, 经验积累, solidify, repair
+Summary: 通过 GEP 六步循环（Scan→Signal→Intent→Mutate→Validate→Solidify）驱动 Gene 的持续演化——执行失败/用户纠正触发定向修正，成功路径记录为 Capsule
+Strategy:
+1. 演化触发信号：编译校验失败 / ESLint 报错 / 用户反馈纠正 / 适配方案不生效——任一信号触发 Scan 阶段
+2. Scan→Signal：定位失败根因，映射到具体 gene_id（如样式不兼容→gene_style_property，选择器报错→gene_style_selector）
+3. Intent→Mutate：确定演化类型（repair/optimization/extension），修改目标 Gene 的 Strategy 或 AVOID 项，保持 Gene 结构不变
+4. Validate：修改后重新执行编译校验（scripts/compile-validate.js），确认修正有效且不引入新问题
+5. Solidify：验证通过后将变更写回 Gene 文件，同时在 events/ 记录 Event（含 diff、触发信号、验证结果）
+6. 成功的完整适配路径记录为 Capsule（任务签名 + 使用的 Gene 集合 + 关键决策点 + 验证结果），存入 capsules/
+7. AVOID: 将失败历史直接追加到 Gene 文本中——先蒸馏为 AVOID 警告再合并，保持信号密度
+8. AVOID: 在单个 Gene 中组合过多经验——单一精准 Gene 效果优于多 Gene 堆积（组合 Gene 性能下降 -6.1pp）
+</strategy-gene>
+
+<references>
+- [GEP 协议参考](../../.claude/skills/skill2gene/references/gep-protocol.md)
+- [Capsule 模板](../capsules/CAPSULES.md)
+- [Event 模板](../events/EVENTS.md)
+</references>