Yida

宜搭 AI 应用开发指南

通过宜搭低代码平台实现一句话生成完整应用。所有操作通过沙箱内 openyida CLI 统一执行（已随沙箱镜像预装，禁止自行 npm install / 升级）。

运行环境与登录（本宿主必读，优先级最高）

1. 固定工作目录：所有 openyida 命令必须在 /home/ubuntu/yida-workspace 目录下执行（每条 bash 命令以 cd /home/ubuntu/yida-workspace && 开头）。该目录是持久卷：登录 cookie（.cache/cookies-*.json）、环境配置与项目产物（prd/、schema cache）都落在这里、跨会话存活。**在其它目录执行 openyida 会导致登录态丢失、产物散落，严禁。**本文其余部分提到的「项目根目录 / projectRoot / workspace 根」一律指该目录。
2. 登录流程（对话内扫码）：用户也可在「插件 → 宜搭低代码平台」详情页扫码连接（与本流程写同一份登录态）；命令报未登录 / 401 / Cookie 失效时，先建议用户去插件详情页扫码，或直接在对话内走以下流程：
   • 执行 cd /home/ubuntu/yida-workspace && openyida login --agent-qr，从返回 JSON 中取 qr_image_markdown，原样输出给用户并请其用钉钉 App 扫码确认；
   • 用户答复已扫码后，执行返回 JSON 中的 poll_command 等待登录完成；
   • 若返回 need_corp_selection，把组织列表转述给用户选择，然后按子技能 yida-login 的降级路径用 --corp-id <corpId> 完成组织选择；
   • 不要使用 openyida login --browser（沙箱无桌面浏览器），不要手动编造或写入 Cookie。
3. 登录成功后先跑任意只读命令（如 openyida env --json）验证 Cookie 可用，再做真实资源操作。

宿主能力适配

• 本宿主没有 use_skill / search_skills。下文所有「加载子技能 <技能名>」一律理解为：读取本技能目录下 references/subskills/<技能名>/README.md（用文件读取工具）。
• 每个阶段只读取当前唯一需要的一个子技能文档；禁止并发批量读取多个子技能、禁止预读未来阶段技能。
• references/ 下的其它辅助文件只能在已读取对应子技能后按需读取。
• 文中若提到 skills-index.json 或 OpenYida MCP 工具（如 select_yida_login_organization），本宿主不支持，忽略并走文档给出的降级路径。

第一步：只读预检（先于真实资源操作）

⚡ 前置门槛：确认 openyida 已安装、Node/npm 依赖达标、登录态就绪。未通过只读验证前，禁止创建应用/页面/表单或发布等任何真实资源操作。

怎么做：优先跑一次 openyida agent-capabilities --json。该命令一次返回 version、cwd、AI 工具环境、推荐工作目录、登录态摘要、commands、command count、sideEffects 和默认 fast_build 契约，避免反复 which openyida、openyida --version、openyida --help、openyida env、login --check-only。

若当前 OpenYida 版本还没有 agent-capabilities，退回跑 openyida env --json 和 openyida login --check-only --json。旧版本地 agent 不需要认识 skills-index.json，也不需要支持 agent-capabilities 才能继续执行。

👉 环境异常、登录失败等特殊分支 → references/setup-and-env.md。正常 agent-capabilities 通过时不要默认读取该 reference。

第二步：意图路由（先判断「全量搭建」还是「单一任务」）

⚡ 环境就绪后，先判断用户诉求属于哪一类，再走对应路线：从零搭一个完整应用，还是对已有资源做单点改动。选错会导致多余步骤或回退；歧义时简短确认一次即可。

完整开发流程（全量搭建）

📌 仅当第二步判定为「全量搭建」时进入；单一/增量任务请跳「技能路由」。 加载子技能 yida-app，由它负责完整应用 workflow、阶段子技能加载、关键 ID 流转、PRD 与 schema cache 约束。 用户说“按默认方案 / 不要追问 / 直接创建 / 尽快搭建”时，yida-app 选择 fast_build：创建应用、必要表单、主页面、发布并输出链接。

默认链路：fast_build 必须只做 创建应用 → 核心表单 → 主页面 → 编写主页面源码 → 发布 → 返回访问链接。不要因为应用名里有“看板 / 系统 / 管理”就升级到 deep_design 或 full_demo。

fast_build 默认加载边界：只加载 yida-app 和当前阶段必需的子技能：yida-create-app、yida-create-form-page、yida-create-page、yida-custom-page、yida-publish-page。Code Canvas 尚未全量，只有用户明确要求、已有页面为 YidaCodeCanvas，或已确认当前组织/页面支持时才加载 yida-canvas-custom-page。不要默认加载 yida-page-uiux、yida-data-source-connectors、yida-data-management、yida-nav-group、yida-dashboard，也不要默认深读 references/。

doneWhen：yida-app 发布主页面成功并输出可访问 URL。到这里默认完成；不要发布后继续 TaskCreate、重复读技能或继续规划。

optionalAfterDone：导航整理、示例数据、公开访问、截图验证、深度视觉方向、数据源/连接器深度接入、报表/大屏，只在用户明确要求或 yida-app 模式为 full_demo / deep_design 时执行。

技能路由（单一 / 增量任务）

选定 1 个最匹配的项执行。表按业务域分组，每组内既可能是子技能也可能是 CLI：

• 行名为 yida-xxx / sls-log-workbench / large-file-write 的是子技能 → 读取 references/subskills/<技能名>/README.md 后按其执行；
• 行名为 openyida xxx 并标 CLI 的无子技能文档 → 识别到诉求直接执行命令、不要去找 README。

按分组 +「何时选择」内联区别对号入座即可。

⚠️ 同类易错先分清：改字段结构→create-form-page｜只读 Schema→get-schema｜改数据记录→data-management｜详情页美化→form-detail；自定义页视觉方向/去AI味→page-uiux(定方向)｜token/组件实现→custom-page(design-system)；加导航先分清→平台左侧菜单分组/排序→nav-group｜页面隐藏应用导航后页面内自绘导航壳→nav-shell（必须隐藏原导航，并让导航项 URL 带 isRenderNav=false 等参数）；字段实时校验→formula｜提交后编排→integration｜跨表高级函数→business-rule；从零建流程→create-process｜改已有流程→process-rule；权限按层级：组织→corp-manager／应用→app-permission／表单→form-permission／页面分享→page-config；自定义页面选路见下方专表。

🧭 自定义页面选路（兼容优先，按顺序命中即停）：

1. 默认 → native yida-custom-page：平台全量兼容的 .oyd.jsx 链路，适合完整应用 fast_build 和未确认 Canvas 能力的组织；
2. 仅当用户明确要求 Code Canvas / 代码画布，已有页面 Schema 是 YidaCodeCanvas，或已确认当前组织/页面支持 Canvas → yida-canvas-custom-page；
3. 已有普通 .oyd.jsx 要迁到 Canvas，且目标组织支持 Canvas → yida-canvas-upgrade。

依据：Code Canvas 组件在宜搭平台侧尚未全量。native .oyd.jsx 是默认兼容链路；Canvas 代码在宿主页真实 window 中 new Function 执行，但物料只透传 code/runtimeCode/importedModules/pageType，无 this 上下文、无 dataSourceMap，this.utils.yida.* 不可用。需要实例桥或未确认 Canvas 支持时留 native。

核心规则

致命规则（FATAL，违反即失败/报错）

1. 技能加载唯一入口：执行任何子技能前，必须先读取 references/subskills/<技能名>/README.md 获取该子技能的命令与参数格式，不凭记忆猜参数格式、不跳过文档直接执行。
2. corpId 一致性检查：创建页面前对比 prd 与 .cache/cookies.json 的 corpId，不一致必须询问用户（重新登录 or 当前组织新建）。
3. 发布前本地校验：native .oyd.jsx / .jsx 页面发布前跑 openyida check-page + openyida compile；Code Canvas .canvas.jsx 不跑这两个 native 检查，改由 openyida publish 的 Canvas 编译阶段或 compileCanvasLocal 快检校验；JSON 配置写盘后先解析校验，再调用平台命令。
4. 命令输入文件禁止 shell 写入：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、cat/echo/printf/tee 加输出重定向，或把命令 stdout 重定向成业务文件。

重要规则（IMPORTANT，影响质量/性能/可维护性）

1. 按阶段加载必要技能：按意图选 1 个主技能；完整应用按阶段加载当下唯一需要的子技能，禁止并发批量读取多个 SKILL.md 或预读未来阶段技能。
2. 优先复用缓存：appType/formUuid/fieldId 优先从 .cache/<项目名>-schema.json 读，缺失再 get-schema。
3. 模板优先：复杂产物先用 openyida sample 或现有示例生成骨架，再做最小改动。
4. 配置承载优先于代码：字段/公式/联动/报表/审批/集成交给对应技能，自定义页面只做展示与胶水。
5. 数据性能优先：统计聚合用 yida-report 服务端聚合，不在前端拉全量后自行聚合。
6. 避免无效重试：失败先查登录态/组织/参数/字段 ID，无修改不连续重试超 1 次。
7. 配置分两处存：业务语义 → prd/<项目名>.md；Schema ID → .cache/<项目名>-schema.json（prd 不记 ID）。
8. 临时文件入 project .cache/：OpenYida 业务中间文件写入 <projectRoot>/.cache/openyida/<项目名或任务名>/；Schema ID 映射仍写 <projectRoot>/.cache/<项目名>-schema.json。从 workspace 根执行命令时使用 project/.cache/...，从 project 工作目录内执行时使用 .cache/...；不要写仓库根目录或系统临时目录。
9. 报表美化先问方案：用户说"优化/美化报表"时先问选原生报表(yida-report)还是 ECharts(yida-chart)。
10. 按 schema 证据选技能：先看 formType、组件树、dataSource.online；receipt/process/report 分别落到表单/流程/报表技能。
11. 官方示例范式优先：蒸馏官方示例时先理解脱敏 schema 承载方式，不凭截图/标题/视觉判断。
12. 默认完成即停止：完整应用默认以发布成功并输出 URL 为 doneWhen；UIUX、数据源深读、示例数据、导航、截图、TaskCreate 和深度设计都是 optionalAfterDone。
13. 数据查询与超长结果纪律（本宿主强约束）：data query form 必须小页拉取（--size ≤ 10）并用 --search-json 按人/时间等条件精确过滤，拿到目标记录立即停止，禁止整表翻页核对。工具结果超长会被落盘到 /workspace/.offload/、正文只留预览——禁止用 Read 整读 offload 文件（内容多为单行大 JSON，整读会把几十万字符灌回上下文，触发反复压缩、把整轮对话拖到分钟级）；需要提取时用 Grep 带精确 pattern，或 bash jq / python -c / head -c 2000 只取所需字段。同一查询失败或结果不符时先改条件，不要原样重试。

📖 每条规则的完整说明、PRD 质量门槛、临时文件路径规范、报表美化话术 → references/development-rules.md

常见问题

参考文件