宜搭应用开发指南

在执行宜搭应用/页面/审批流等任务前先确认环境与登录态，再根据用户需求和已解析的 app/page/form/process 等上下文资源，分析任务属于完整搭建、已有资源补齐还是单点任务，并加载对应子技能执行。

步骤模版（进行时展示给用户看的步骤）

完整应用搭建时，直接使用对应模式的步骤名称。

Plan 模式

1. 需求识别与分析
2. 设计功能和页面
3. 确认搭建方案
4. 创建应用
5. 搭建表单与审批流
6. 准备示例数据
7. 准备页面图片
8. 搭建业务页面
9. 发布页面与配置导航
10. 检查功能并交付

Fast 模式

1. 需求识别与分析
2. 设计功能和页面
3. 创建应用
4. 搭建表单与审批流
5. 准备示例数据
6. 准备页面图片
7. 搭建业务页面
8. 发布页面与配置导航
9. 检查功能并交付

按本轮范围选用步骤：已有应用时省略“创建应用”，无需示例数据或图片时省略对应步骤，并重新编号。

每项待办对应一个阶段，直接使用上方短标题。创建应用、表单、数据、图片、页面和发布分别展示。执行中保持标题与列表顺序稳定，完成后标记完成并保留记录。图片准备与表单、页面搭建可同时进行，列表顺序仅用于展示。业务细节写在进度消息中，任务编号、命令、路径、授权依据和耗时写入内部执行记录；用户要求的耗时统计集中放入报告。素材采集与应用创建同时进行时，进度描述统一为“素材采集&应用创建”；单独进行时使用对应阶段名称。图片数量、用途及任务详情归入内部执行记录。

执行步骤

Step 1：环境与登录态确认

完整应用首轮需求澄清先按 yida-app 进入需求分析，只读取提问必需的需求材料，不以环境、登录或资源预检阻塞首问。需求澄清完成后，需要核验资源或准备执行时，再执行 openyida agent-capabilities --summary-json，确认 OpenYida、Node/npm、登录态和工作目录可用。openyida agent-capabilities --json 是完整能力信息，只在命令契约排障、manifest 差异诊断或深度调试时使用；不要把完整能力信息放进常规完整搭建链路。workdir 对应完整能力信息里的 active.projectRoot。

如果快照显示 builder_path.interactive_login.mode=caller_open_url，说明 CLI 已把浏览器归属交给 Agent。执行 openyida login --no-browser 后，Agent 必须优先调用当前宿主的沙箱浏览器 / 内置 Browser 打开 CLI 输出的授权 URL 一次；只有没有浏览器工具或工具调用失败时，才让用户手动打开链接。

未完成环境与登录态确认前，不创建应用、页面、表单，不发布页面。环境异常、登录失败、env token 注入和 openyida copy 初始化见 环境准备与登录检测。

核心判断：

Step 2：解析资源上下文

任何写操作前先解析目标 app/page/form/process。按本轮显式资源、外部绑定资源、workspace cache/config、会话历史的顺序选择目标；同级冲突或目标不明才询问用户。

执行 Step 2 时必须读取 资源上下文与补齐判定，并按其中规则解析目标资源。已有 app 默认复用，不执行 yida-create-app；已有 app 但没有任何页面时，进入完整应用补齐；PRD 不需要页面时，不强制创建自定义页面。

核心判断：

Step 3：意图识别

意图识别只决定入口，不展开执行细节。完整搭建 / 补齐加载 yida-app 后按其 workflow 执行；单点任务只选 1 个主技能，不升级成完整搭建。

Step 4：加载子技能并执行

如果当前 AI 工具提供 use_skill / search_skills，必须用 use_skill("<技能名>", "<本阶段目的>") 加载技能，不用 Read / read_file / cat 直接读取 SKILL.md 路径。如果当前工具没有 use_skill / search_skills，按 skills/<技能名>/SKILL.md 定位当前阶段要执行的子技能文档。

单点任务按意图选 1 个主技能；完整应用由 yida-app workflow 分阶段推进，每一步加载当前步骤对应的子技能。skills-index.json 只给能读取索引的工具辅助匹配，不作为运行前置。执行边界见下方核心规则。

技能路由表

这张表给人工 fallback 和人审使用：先按用户任务命中一个大类目录，再在该目录内选定 1 个最匹配的子技能。机器索引和精排方法见 路由补充说明。

大类目录

高频分歧

索引精排方法和无独立子技能的 CLI 见 路由补充说明。

核心规则

以下规则都是执行 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 编译校验失败时读取本地校验修复，按字段修复并限制无进展重试。