Yida Publish Page

发布自定义页面

资源边界：本技能只处理普通 OpenYida 页面发布；目标不明时先只读确认或询问用户。

执行边界

本技能负责三件事：确认发布目标、执行 openyida publish（包含必要编译和 Schema 写入）、给出 final 证据。新建或默认自定义页面源码先由 yida-canvas-custom-page 产出。缺少自定义页面容器时，先交给 yida-create-page 创建后再回来发布。

发布目标确认

发布前必须先解析目标页面 context；本技能优先服务已有页面：

• 用户说“优化这个页面 URL / 修改这个页面 / 重新发布 / 覆盖现有页面”并提供页面 URL、formUuid、bound page 或 workspace 中可确认的 display page 时，直接把该页面作为发布目标。
• bound page 是默认发布候选，不是强制目标；如果当前会话绑定页面 A，而用户本轮明确指定页面 B，必须先解析 B。B 有唯一 URL / display formUuid 时发布到 B；B 只有名称或描述且无法唯一匹配时先问用户。
• 只有无法解析目标页面，且用户明确要新增页面容器时，才回到 yida-create-page。
• 发布目标必须是 formType=display 的自定义页面；普通表单、流程表单、数据底表的 formUuid 不能作为 openyida publish 第三个参数。
• 多个页面候选按根技能来源优先级选择；同级冲突或无法判断页面类型时才问用户或执行只读 list-forms 确认。

严格禁止 (NEVER DO)

• 不要在未加载对应页面开发技能的情况下临时编写页面源码；使用 YidaCodeCanvas 组件实现的页面先看 yida-canvas-custom-page。
• 不要把普通 React / Next / Vite 项目源码直接发布；可发布源码必须是 OpenYida 页面源码，并放在 project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}
• 不要混用预检模式：.canvas.jsx / .canvas.tsx 不走 openyida check-page，统一执行 openyida compile <源文件> --json 让 CLI 按扩展名选择 Canvas 编译器；.oyd.jsx / .jsx / .tsx 不要当成 YidaCodeCanvas 页面发布，除非已明确确认源码就是 YidaCodeCanvas 组件源码并使用 --canvas
• 不要在平台 renderJsx / didMount 形态里手写 React Hooks；需要 Hooks 的页面应交回对应页面开发技能改成可编译的源码形态
• 不要编造 appType 和 formUuid，必须从已有记录或命令返回中获取
• 不要把普通表单、流程表单或数据底表的 formUuid 当作发布目标；除非已确认目标是自定义展示页面，否则不要用 --force 绕过保护

严格要求 (MUST DO)

• 发布前确认页面源码已通过对应页面开发技能编写：.canvas.jsx / .canvas.tsx 发布为 YidaCodeCanvas 组件；.oyd.jsx / .jsx / .tsx 发布为平台 Jsx 组件
• 平台 Jsx 组件 / oyb.jsx / renderJsx 维护源码发布前优先执行 openyida check-page <源文件路径> 和 openyida compile <源文件路径>；本技能只把它们作为发布前 guard
• 使用 YidaCodeCanvas 组件实现的页面发布前必须执行 openyida compile <源文件> --json；CLI 会自动选择 Canvas 编译器。失败时按本地校验修复处理结构化错误，不要改用 node -e、compileCanvasLocal 或 run_workspace_script 绕行
• Canvas 本地编译通过后，执行 openyida publish <源文件> <appType> <displayPageFormUuid> --canvas --health-check，由发布流程再次校验并写入 runtimeCode + importedModules
• 主题已集成的页面直接编译发布原文件；只有使用 /* @canvas-theme-provider */ 标记装配时才生成并发布 .themed.canvas.jsx。OPENYIDA_CANVAS_THEME_NOT_ASSEMBLED 表示误用了尚未装配的源文件，应先运行主题脚本再编译输出文件。
• 图标报 OPENYIDA_CANVAS_ICON_EXPORT_UNAVAILABLE 时，按 details.exportName、源码行列与建议修正 import，并重新 compile；禁止换成动态全局引用绕过。校验以 CLI 内置的宜搭运行时导出清单为准；动态名称仍需组件映射与兜底。--health-check 的发布回读不等于浏览器渲染验收，不能据此把 runtimeSmokeVerified: false 报为已通过。
• 导航报 OPENYIDA_CANVAS_NAVIGATION_INVALID 时，按 issueType 修正：local_platform 使用 local 页内模式或绑定真实平台资源；document_flex 重新提取 canvas-nav-content 并采用自然高度。发布后需实际检查各菜单、刷新/返回、滚动到页脚并回顶、窄屏展开；不能仅凭编译或回读认定通过。
• Canvas 编译和发布共用主题结构检查。出现 OPENYIDA_CANVAS_THEME_PROVIDER_INVALID 时，按报错位置调整 Provider 和业务组件的层级，再执行原命令；发布后打开实际页面检查首屏和交互。
• 使用 YidaCodeCanvas 组件实现的页面发布时，发布流程会在外层页面 didMount 注入 window.__OPENYIDA_YIDA_API__ 和 window.__OPENYIDA_UTILS__；不要在 Canvas 源码内补写 this.utils.yida.* 或根级 this.utils.*
• 推荐源码放在 project/pages/src/：使用 YidaCodeCanvas 组件实现的页面用 <页面名>.canvas.jsx / <页面名>.canvas.tsx；平台 Jsx 组件维护源码用 <页面名>.oyd.jsx / <页面名>.jsx / <页面名>.tsx
• 发布前注意 CLI 会检查 <workspace>/project/pages/src/ 与 <workspace>/projects/<id>/artifacts/ 中同名源码是否内容不一致；出现警告时必须确认实际要发布哪一份
• 发布前确认 openyida env 检测通过，登录态有效
• Canvas 页面含普通表单提交/详情入口时，沿用 openyida compile <源文件> --json 预检，并核对标准 form-open-container 片段已接入、openForm 已绑定、formOpenContainer 已挂载。不能通过添加同名空组件或忽略检查来绕过；发布后实际点击，验证 iframe、标题栏三个操作、拖拽调宽及关闭刷新。源码检查通过不代替交互验收。
• corpId 不匹配时，必须询问用户是否切换组织，不得强行发布
• 重新发布已有自定义页面时，openyida publish 会自动读取目标页面现有 Schema 并合并页面级 dataSource；不要靠 Agent 口头承诺“保留数据源”，必须使用新版 CLI 的默认保护能力
• 如果源码包含 this.dataSourceMap.，而发布输出包含 No custom page data sources to preserve，本次发布不能视为完成；说明源码依赖设计器数据源但目标页没有可保留数据源。必须回到对应页面开发技能修复源码并重新发布，或先通过 yida-data-source-connectors 创建并绑定数据源后重新发布
• 发布证据闭环：本轮只要 Write/Edit/Create 了 project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}，final 证据只认真实执行成功的 openyida publish <source> <appType> <displayPageFormUuid> 命令结果；本地文件编辑、diff、check-page、compile、compileCanvasLocal 或口头声明都不能证明远端页面已更新
• 本技能不读写 memory：发布操作通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态

适用场景

编写完自定义页面源码后，执行此技能将源码发布到宜搭平台。已有页面 URL / formUuid / bound page 时，默认发布到该已有页面。

触发条件

正向触发：

• "发布页面"、"上线页面"、"部署页面"
• "优化这个页面 URL"、"修改现有页面后重新发布"
• 页面源码编写完成后的下一步
• "编译发布"、"把代码发布到宜搭"

⚠️ 代码必须先完成对应页面技能规范的编写，再执行发布。原生表单页面无需此命令，创建即生效。

前台单页面入口

• 本轮业务用途已确定为前台自定义页面时，默认持久化隐藏该页的平台导航；缺少 entryMode 时按用途补齐独立入口，不要求用户提供新参数。发布前查询 get-form-config，未隐藏时执行 update-form-config <appType> <formUuid> false "<页面标题>" 并回读。用户明确保留导航或仅修改后台内容页时保留原配置；不要全局隐藏应用导航。
• publish 默认读取页面导航配置。确认 renderNav=false 后，url 和 standaloneUrl 返回干净的 /custom/<formUuid>，另保留 workbenchUrl；无须新 CLI 开关，不追加 isRenderNav=false 等导航 URL 参数。
• 缺失、无效或失败的回读不等于隐藏成功：standaloneUrl=null 时检查 navigationVerification / navigationWarning，修复配置后用 get-form-config --json 取得最新地址，不为补链接重复发布源码。确认页面类型为 display 才返回自定义页地址。
• 最终回复必须包含前台单页面链接；若无法确认，明确说明前台入口未完成，不能仅给工作台或开发后台。现有已验证的公开/分享地址保留原样，不因隐藏导航而开启公开访问。

Canvas 主题处理

• compile 和 publish 默认保留固定品牌色覆盖，在结果 warnings 中返回源码位置、字段、色值与影响；即使使用 --json 也保留告警。告警不表示品牌色已跟随应用主题。
• 三个主题参数仅用于 Canvas 页面，按下方参数表选择；普通发布无需添加主题参数。OPENYIDA_CANVAS_STRICT_THEME=1 启用严格检查，OPENYIDA_CANVAS_ALLOW_FIXED_BRAND=1 明确保留固定色覆盖。
• publish --fix-theme 显式迁移固定品牌色覆盖，可与 --strict-theme 合用，不能与 --allow-fixed-brand 合用。待迁移控件须位于已装配、已挂载的 CanvasThemeProvider 内；旁侧无关 Provider 不算主题来源。无法静态确认的动态渲染路径保留原文件，按主题开发技能手动接入；CLI 在内存中完成迁移和全部 Canvas 编译检查，通过后才写回。没有主题来源时先按主题开发技能接入，不能靠删除颜色回退到默认主题。
• 发布不等待 stdin，不自动弹出迁移询问；未指定 --fix-theme 不改写品牌色。编译错误时保留原源码。
• 迁移范围为品牌交互色覆盖；标准动态 Provider、抽屉背景/文字/圆角/阴影和 iframe 实现保持不变。迁移后检查主操作、链接、Tabs，以及实际使用的明暗主题和抽屉内外页面。

命令

openyida publish <源文件路径> <appType> <formUuid> [--health-check] [--force] [--canvas] [--compat] [--skip-lint] [--fix-theme] [--strict-theme] [--allow-fixed-brand] [--auto-nav-order] [--open|--no-open] [--json]

路径口径：从仓库根执行时，源文件用 project/pages/src/...；如果 Bash cwd 已经是 <workspace>/project，源文件用 pages/src/...，不要传 project/pages/src/... 导致查找 project/project/pages/src/...。发布失败提示源文件不存在时，先按该规则切换路径，不要自动发布另一份文件。

openyida publish 会按源码扩展名选择发布模式：.canvas.jsx / .canvas.tsx 写入 YidaCodeCanvas，并注入 yida/utils window 桥；.oyd.jsx / .jsx / .tsx 写入平台 Jsx 组件。 发布前确认源码已由对应页面开发技能完成并通过相应本地检查；本技能只把真实成功的 openyida publish 作为远端完成证据。