miniapp-ray-common

name	miniapp-ray-common
id	miniapp-ray-common
description	面向 Ray 小程序开发提供以索引为先的文档导航与实现约束，在用户进行页面或 UI 搭建、组件封装与改造、Ray API 与设备能力集成、生命周期与路由、图片转代码、多语言与样式、或排障与升级时使用；实现前须依据 references/ray/INDEX.md 与路由文档定位能力，禁止虚构 API 与生命周期钩子。

RayCommonDevelopSkill

概述 {#description}

本技能是 Ray 小程序开发的「地图」：主文件只负责分区、导航与强约束，细节一律下沉到 references/。工作流为先选区、再读 references/ray/INDEX.md（Section | Key | Title）与对应 references/router/task-*.md，每次仅打开 1 个入口索引与 1～2 个目标文档，不足再增量追加；禁止跳过索引猜测 API、生命周期或组件属性。输出须区分 文档确认（来自当前已读文档）与 经验推断（文档未覆盖时的保守假设）。同步脚本 scripts/index.js 不再生成 _meta.json，导航以 INDEX.md 与目录内文件为准。

适用场景 {#scene}

• A 区（页面 / UI）：新建页面、弹窗、表单、列表、设置页、布局或界面改造。先读 references/router/task-ui.md；常查 references/ray/framework/page.md、references/ray/component/**、smart-ui skill。
• B 区（组件封装 / 改造）：抽组件、改组件、复用与规范结构。先读 references/router/task-component.md；常查 references/ray/framework/component.md、smart-ui skill、references/ray/component/**。
• C 区（Ray API / 设备能力）：调用 Ray API、连接通信、上传下载、监听事件。先读 references/router/task-api.md；经 references/ray/INDEX.md 定位到 references/ray/api/<key>/ 下对应 *.md / *.mdx。
• D 区（生命周期 / 路由 / Framework）：页面生命周期、路由、事件、样式、混合开发、插件、渲染机制。先读 references/router/task-framework.md；常查 references/ray/framework/*.md。
• E 区（图片转代码）：截图、草图、设计稿还原为 Ray 页面或组件。先读 references/router/task-image-to-code.md；常查 smart-ui skill、references/ray/component/**、references/rules/tag-mapping.md。
• F 区（i18n / 样式 / 版本）：多语言、CSS Modules、Less、smart-ui 版本对齐。先读 references/router/task-style-i18n.md；常查 references/rules/i18n.md、references/ray/framework/css.md。
• G 区（排障 / 升级 / 兼容）：报错、版本兼容、升级迁移、文档冲突。先读 references/router/task-debug.md；常查 references/ray/guide/**、references/rules/anti-hallucination.md。

选区：多区并存时只选一个主区（按最终产物判断，不按关键词数量）；其余为次区，主区完成后再按需补读。示例：设置页带开关与输入框 → A；表单抽成组件 → B；P2P 下载 → C；onLoad / 路由参数 → D；按图还原 → E；全文案 i18n → F；升级后不兼容 → G。

搭配使用 {#cusage}

• ** smart-ui-skill **：Smart UI 组件库 skill，配合使用可快速搭建符合设计规范的页面和组件，提升开发效率和界面一致性。

工作流程 {#workflow}

1. 读主区对应的 references/router/task-*.md。
2. 按路由指引打开 references/ray/INDEX.md，用 Section（如 api、component、framework、guide）与 Key 拼出路径，再读具体 *.md / *.mdx。
3. 命中后最多再读 1～2 个文档；仍不足则沿同区增量扩展，禁止跨区乱读或一次性扫完整个 references/。

须配合阅读的规则文件：references/rules/tag-mapping.md（标签映射、禁止小写 HTML 标签）、references/rules/i18n.md（多语言与 Strings.getLang）、references/rules/anti-hallucination.md（防幻觉与未命中处理）、references/rules/output-contract.md（输出格式与引用说明）。

默认协议：UI 优先 smart-ui，无法满足再退回 Ray 原生组件；页面默认 /pages，组件默认 /components；涉及文案时补读 references/rules/i18n.md；文档未命中须明确说明「未在文档中找到」，不得静默猜测。

注意事项 {#tip}

• 禁止使用小写 HTML 标签（如 div、span）。
• 禁止混入 wx.*、my.* 等非 Ray 业务 API。
• 禁止虚构 Ray 生命周期、Ray API、smart-ui 的 props 或事件。
• 禁止在未通过索引定位前批量加载大量 references 文档。
• 禁止在业务代码中硬编码中文文案。