Openyida

核心规则

以下规则都是执行 OpenYida 任务时必须遵守的全局边界；具体子技能可以补充更细规则，但不能覆盖这些规则。

1. OpenYida CLI 统一执行：所有宜搭资源操作通过 openyida CLI 执行；创建、修改、发布、查询都以 CLI 返回的 JSON、URL、formUuid/appType 作为证据。
2. 技能加载唯一入口：执行子技能前必须加载对应技能；单点任务按意图选 1 个主技能，完整应用由 yida-app workflow 分阶段加载当前步骤对应的子技能。
3. 真实资源先确认：写操作前解析本轮显式资源、已绑定资源上下文、workspace 配置/缓存和历史上下文；已有目标资源时默认修改、补齐或发布，只有目标缺失且意图允许创建时才加载 create 类技能。
4. corpId 一致性检查：创建或发布页面前对比 PRD/resource context 与当前 auth snapshot 的 corpId；不一致时先让用户选择重新登录或确认继续。
5. 页面源码修改必须发布闭环：只要本轮 Write/Edit/Create 了页面源码 project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}，final 前必须看到成功的 openyida publish <source> <appType> <displayPageFormUuid>；没有证据只能说“源码已修改，尚未发布”，禁止说“页面已更新 / 已重新发布 / 已上线”。
6. 发布前本地校验：平台 JSX 组件页面的 check-page / compile 归 yida-custom-page 执行；使用 YidaCodeCanvas 组件实现的自定义页面按本地快检或发布阶段校验；JSON 配置写盘后先解析校验，再调用平台命令。
7. 生成产物严禁 emoji：页面源码、.canvas.jsx 源码、表单 Schema、发布 Schema、产物文件名和路径中严禁使用 emoji；图标语义使用平台组件、图标库或已验证资源表达。
8. 输入文件用结构化写入：JSON/YAML/CSV/config/script 文件使用当前 agent 的文件写入能力创建，再把路径传给命令；严禁用 shell heredoc、cat/echo/printf/tee 或重定向生成业务文件。
9. OpenYida CLI 不吞诊断：不要给 openyida 命令加 2>/dev/null；失败时保留 stdout/stderr；遇到 DENIED 或同一命令重复失败，先换策略、改输入或重做环境确认。
10. 读取与复核用合适工具：读取或定位 workspace 文件优先用当前工具的 Read / Glob / Grep 或 rg；OpenYida CLI 已返回成功 JSON、URL、appType、formUuid 或 fieldId 时，以 CLI 结果作为证据。
11. 资源 ID 必须精确：appType、formUuid、fieldId 等应用、表单、字段 ID 必须来自 CLI/API/cache 证据并一字不差传入命令和源码；不得凭名称、截图、相似前缀或记忆补写、改写、截断。
12. 字段和 Schema 以证据为准：字段级表单操作优先交给 create-form update/add-option/bind-datasource/validation/rule 的 schema-aware 解析；页面代码、数据、流程、公式等需要字段映射时，每表单一次性执行 openyida get-schema --field-map-json 并缓存字段摘要。
13. 产品与视觉分工固定：完整应用先分析需求；首次搭建按 yida-requirement-analysis/workflow/prepare-brief.md 确认未决事项，再进入已选 Fast / Plan。两种模式共享需求分析与 PRD 契约，以下并行生成规则用于 Fast；Plan 确认当前版本后交接派生文件，直接进入 Step 3。只有 Plan 的 build-plan.html 用于方案展示，其余设计文件保持内部使用。完整应用先由 yida-requirement-analysis 整理用户需求，再由 yida-prd 与 yida-design 同时输出 prd/<项目名>/prd.md 与 prd/<项目名>/design.md，最后由 yida-app 做一致性校验；页面目标、区块、数据和交互以 PRD 为准，布局、主题、材质和状态视觉以 design.md 为准。
14. 配置优先于页面代码：字段、公式、联动、报表、审批和集成交给对应技能；自定义页面负责展示数据、放置业务入口，并串联表单、流程、报表和导航入口。
15. Canvas 运行桥统一口径：.canvas.jsx / .canvas.tsx 发布为 YidaCodeCanvas 时，外层页面 didMount 默认注入 window.__OPENYIDA_YIDA_API__ 和 window.__OPENYIDA_UTILS__。Canvas 组件内部不得直接写 this.utils.yida.*；表单/流程/表单设计 API 走 window.__OPENYIDA_YIDA_API__，toast/dialog/openPage/router.push/isMobile 等根级工具走 window.__OPENYIDA_UTILS__，且 window.__OPENYIDA_UTILS__.yida 指向同一个 yida API 桥。
16. 分页查询默认 pageSize 50：生成表单、流程、任务、成员等分页查询代码时，一般显式写 pageSize: 50 或 pageSize: '50'。除非用户明确要求小页或大页，不写 20、100 等其他值；平台上限仍是 100。
17. 数据性能优先：统计聚合用 yida-report 服务端聚合，不在前端拉全量后自行聚合。
18. 避免无效重试：失败先查登录态、组织、参数和字段 ID；无修改不连续重试超 1 次。
19. 存储路径固定：PRD、视觉契约、Schema ID 和临时文件按存储约定写入：

    类型	路径
    业务语义	prd/<项目名>/prd.md
    视觉契约	prd/<项目名>/design.md
    Schema ID	.cache/<项目名>-schema.json
    临时配置/导入数据/脚本	<projectRoot>/.cache/openyida/<项目名或任务名>/

• prd.md 只记录业务语义，不记录字段 ID。
• Schema ID 映射不是远端真相；CLI 返回字段不存在、重名或歧义时重新取证。
• 从 workspace 根执行命令时路径加 project/ 前缀；在 OpenYida project 工作目录内执行时使用 .cache/...。
• 不把 OpenYida 业务中间文件写到仓库根目录或系统临时目录。

20. 报表和可视化先分流：标准统计与原生报表用 yida-report；定制图表页面默认用 yida-rechart；只有明确 ECharts、维护旧 ECharts 页面或复杂 option 超出 Recharts 能力时用 yida-chart。
21. 应用主题只有一份：涉及应用蓝图、页面视觉、应用主题色、品牌色、全局换肤或 --color-brand1-* 时先读 yida-design。导航、应用框架、提交/编辑表单、记录详情和自定义页面按整体主题规则一起设计。app-theme.css 只在应用级统一配置，各类页面消费同一份主题 token。严禁在页面级重复写入、同步或向上层注入主题样式；YidaCodeCanvas 源码只在 YidaComp 内消费现有主题 token。
22. 默认完成即停止：完整应用默认以资源发布成功、轻量导航排序完成、示例数据就绪并输出一组有明确名称的应用入口与业务交付总结为 doneWhen；截图、精细导航整理和额外深读属于 optionalAfterDone，除非用户明确要求。
23. 说清楚做什么：对话、任务列表、步骤标题、进度和提问面向非技术用户。用日常用语和短句，一句话说一件事，先说结果或动作，再补必要原因。功能写谁能做什么；进度写当前动作和下一步；失败写问题、影响和处理办法；待核实的结果如实说明。文件名、路径、技能名和调用方式留在内部执行。PRD 业务说明、HTML 和消息使用功能与体验描述；接口参数、配置键值及内部 ID 留在 Agent 实施交接，遵循用户可见表达契约。交付卡片的 description 写 2-3 句业务交付总结、核验结果与剩余事项，卡片包含一组“应用访问入口”；宿主没有交付工具时，在最终回复中给出相同内容。不得把需求信息文件、PRD、视觉设计、build manifest、资源清单、Schema 或每个表单/流程/报表分别登记成用户可见交付物；不分前后台或包含业务后台时，给出经验证的业务页面入口，前台页面经 PRD 标记为 standalone 且导航配置回读通过时给独立业务入口；完整应用默认再提供开发者管理后台 adminUrl，不因云端登录方式省略；明确仅业务后台时交付业务后台与开发者管理后台，不追加前台；明确仅前台时不追加业务后台，仍交付前台与开发者管理后台两个地址。有前后台时交付前台、业务后台、开发者管理后台三个地址；不分前后台时交付系统入口与开发者管理后台。用户明确排除的入口和单页任务范围优先。
24. 任务复盘沉淀：用户多次纠正、平台接口假成功、页面骨架共性质量问题、线上回读验收方法、一次性脚本可产品化等情况，完成前判断是否需要沉淀到 CLI、测试或 skill。

常见问题见 常见问题解决方案。

参考文件

本地设计与 Canvas 编译校验失败时读取本地校验修复，按字段修复并限制无进展重试。