--- name: app-page-builder description: 用 LessChaos App 字段作为正式数据来源，设计和生成自由布局与交互的页面源码，支持跨 App bindings、修改、保存、发布版本和回滚。用户要求看板、工作台、详情页、业务操作页或调整已有自由页面时使用；表结构和业务记录的修改分别由其他 App 技能处理。 --- # App 自由页面 AI 设计页面的布局与交互，App 字段提供正式业务数据。交付既包括页面源码，也包括明确的来源绑定和已经验证到的状态。 下文 `app_*` 是工具用途名；先从当前插件目录装载实际 Tool 定义。开始生成前读取 [Page 资源与绑定](references/page-contract.md)；布局与交互设计读取 [页面设计方法](references/page-design.md)。 ## 1. 确定页面任务与归属 从用户请求确定谁使用页面、要做什么判断或操作、归属哪个 App、是否修改已有页面。已有引用优先；缺少身份时 `app_list`。修改已有页面先 `app_page_list`、`app_page_read`，保留源码、bindings、当前 revision 和已发布版本。 自由页面可以是经营概览、业务工作台、详情流程或交互分析工具，按任务选择结构。没有指定风格时沿现有产品的组件、信息密度与主题设计。会影响指标或实际写入的歧义需要明确，普通布局选择由 Agent 决定。 完成条件：页面的主要任务、归属、来源 App 与主要交互已确定；已有页面的保留范围明确。 ## 2. 把页面元素映射为数据依赖 对每个来源 `app_definition`，核对 App、Table、Field 身份、类型和 cardinality。为每个指标、列表及动作确定：来源、记录粒度、筛选、统计方式、展示单位和交互结果。可用小范围 `app_query` 或 `app_aggregate` 验证口径，实际数据不写进源码。 给每个数据需求建立命名 binding：列表用 records，统计用 aggregate，明确业务动作才用 action。筛选、排序、分组、统计引用的字段也必须在该 binding 的 fields 中声明。每个来源都显式包含自己的 appId，同名字段跨 App 不能混用。 复杂跨来源指标先使用 `app-data-analysis` 确定粒度和匹配键，再回到页面映射。来源缺失时定位受影响区域；不得用假数据把它呈现为成功。 完成条件：页面每个数据区域和动作都有合法绑定，且能解释它如何回答用户任务。 ## 3. 生成完整源码 按页面任务组织 TS／TSX／CSS 文件，入口为非空 TSX。已有页面尽量保留用户未要求改变的区域、交互和绑定身份。组件按实际复用和数据职责拆分，避免把所有状态、取值与样式挤在入口中。 先核对宿主实际提供的 SDK 方法、依赖和执行工具，再接运行时数据与动作。`sdkVersion: 1` 只确认资源合同；它本身没有定义 `useBinding`、`app.query` 等函数，也不证明任意 npm 包可用。 当前只有源码资源工具时，可以完成展示组件、显式数据输入类型和事件接口，把未接入区域呈现为未接入状态；这些内部 props 不是宿主会自动注入数据的承诺。保存这一版源码时明确记录尚缺的数据桥接与运行验证，不自行补造 SDK、凭据、原生 IPC 或直连业务服务。 有实际运行合同后，数据与动作都经声明绑定及受控桥接；动作提交中禁止重复触发，失败保留用户输入，成功后按对应来源重读。账号和组织使用宿主提供的范围。 完成条件：文件组成完整、所有本地引用存在、每个数据与交互状态有明确处理，运行接线与尚缺部分可区分。 ## 4. 保存、诊断与修复 新 Page 使用稳定 UUID 和 `expectedRevision: null`；修改使用刚读到的页面 revision。调用 `app_page_save` 保存完整 document，再 `app_page_read` 核对版本、源码与 `issues`。 按 binding 名定位诊断，重读受影响来源定义，修正丢失字段、类型、cardinality 或非法操作。保存冲突时先重读当前 Page，将用户目标合并到最新源码；保留另一方的改动，不直接用最新 revision 强压旧 document。 资源校验通过只证明源码形状与绑定准入；有编译或预览工具时再用真实诊断修复编译和交互，不能把没有运行过写成验证通过。没有对应工具时停止于源码与绑定交付，说明运行依赖。 完成条件：正式保存回执与回读一致，绑定问题已修复或明确列出，验证结论与实际工具证据一致。 ## 5. 按用户意图管理版本 用户要求保存草稿就止于保存。用户要求发布时，用当前 revision 和已保存 version 调用 `app_page_publish`，再回读确认 `publishedVersion`；这确认发布选择，页面运行仍需相应运行时证据。 回滚先读取目标历史版本，检查当前绑定诊断，再用当前页面 revision 选择旧 version。回滚改变页面版本，不回滚业务记录。删除 Page 使用当前 revision，按用户明确的删除意图执行。 交付页面归属、pageId、实际版本、主要数据依赖、保存／发布状态，以及编译和运行是否已有证据。Tool 的 resource 只定位其实际目标，不把 App 资源链接宣称为可访问的页面预览地址。