datalive-design/AGENTS.md

DatAlive 低代码设计器 - Agent 指南

头号铁律：不要直接改代码

严禁直接修改项目源代码。 Agent 的工作模式：阅读 → 给出方案/代码片段 → 由用户手动落地。 未经用户明确指示前，不要使用 Edit / Write / ast_grep_replace / lsp_rename 等会改动文件的工具。 这是项目自定的最高优先级协作规则（见历史 commit 6d99132），优先级高于一切默认行为。

项目阶段（决定 Agent 期望）

• 当前仅有核心 Schema 类型定义，全部位于 src/schema/。
• src/index.ts、src/schema/index.ts 当前为空，没有运行时代码、组件、引擎、测试。
• README 中的 bun run index.ts 不会有任何输出 —— 不要尝试"运行"或"测试"项目。
• 远期路线（未实现，勿擅自引入）：React + Vite + React Router/Tanstack Router + Tanstack Query + Zustand，五大引擎（工作区 / 画布 / 渲染 / 数据 / 交互）。

工具链与命令

• 包管理：Bun（lockfile = bun.lock）。勿用 npm/pnpm/yarn。
• package.json 没有 scripts 字段，不存在 lint / test / build / typecheck 命令。
• 类型检查唯一手段：bunx tsc --noEmit（tsconfig.json 已 noEmit: true + strict 全开 + noUncheckedIndexedAccess）。
• 没有 ESLint / Prettier / Vitest / CI / pre-commit / codegen / dev server。

语言

• 注释、文档、PR/commit 信息均用中文；类型与变量用英文。新增内容请保持。
• docs/ 下文件名为中文，部分终端（PowerShell + GBK）会显示乱码 —— 用 Glob "docs/*.md" 或 Read 直接以 UTF-8 读取，不要试图通过 shell ls 解读。

Schema 架构铁律

修改 src/schema/** 前必读。这些约定在多个文件的 JSDoc 中反复强调，违反会污染整个蓝图：

1. Schema vs Store 二元分离
   • Schema 仅承载需要持久化、可导入导出的稳定配置。
   • 派生状态（isLoading / data / error）、AppMode、parentId、设计器选中态、缓存等永不进 Schema。
2. AppMode 不是 Schema 字段
   • design / preview / runtime 三态由宿主容器在运行时注入。
3. 所有可寻址实体继承 Entity (src/schema/shared/entity.ts)：id（UUID，RPC 寻址 + React key）+ label（仅 UI 展示）。
   • label 严禁出现在表达式或数据流绑定中，那里只能用 id 或 Variable.key。
4. JsonValue (src/schema/shared/json-value.ts) 是序列化铁壁。Schema 中用户可填写的纯数据字段必须用它，不要用 any / object / unknown，更不能允许 Function / Date / RegExp。
5. DynamicExpression (src/schema/shared/dynamic-expression.ts) 是统一逃生舱：type: 'code' + code: string（函数体片段，需含 return）。引擎用 new Function('context', code) 编译，注入 context: { variables, queries, event?, data? }。新增 code 模式字段一律 extends DynamicExpression。
6. 二元联合 fixed | code 模式 —— 见 RestRequest、ActionParams、Condition、Filter、QueryConfig、MutationConfig、DataSourceConfigByRest。新增可逃生字段时延续此命名与判别式。
7. null 在 REST 配置中具有显式抹除语义：RestRequestByFixed.params/headers 中的 null 表示从合并后的全局 DataSource 配置中物理删除该键，并非置空字符串。
8. 数组字段必须显式 []，不允许 undefined —— interactions / children / routes / pages / filterIds 等。引擎依赖此约定避免兜底分支。
9. 没有 MutationConfigByStatic —— 写操作必有副作用，不允许 mock 变体。
10. Action 不枚举具体类型（拒绝 ShowToast / Navigate 这类设计），统一用 target: { type, id } + method + params 的泛化 RPC 模型。
11. Variable.key 是表达式中可见的真实标识符：必须满足 /^[a-zA-Z_$][a-zA-Z0-9_$]*$/ 且全局唯一；与 label 严格区分。
12. parentId 永不持久化：组件树是嵌套结构，扁平 parentId 字典由引擎在内存中按需推导。

命名与组织约定

• 文件名 kebab-case：component-data.ts、data-source-by-rest.ts。
• 标记联合命名 <Type>By<Variant>：ComponentDataByStatic、QueryConfigByRest、FilterByCode、DataSourceConfigByRestWithCode。
• 每个 schema 域目录有自己的 index.ts barrel；跨域请从 barrel import type { ... } from '../shared'，不要写 '../shared/entity'。
• 现有域：application / component / data-source / filter / interaction / mutation / page / query / route / shared / variable。
• src/schema/index.ts 当前为空；如需新增聚合导出，请在此处汇总。

设计文档（在 docs/，修改 Schema 前对齐）

• 应用运行模式架构规范.md — AppMode 三态边界、preview 与 runtime 的同源异构差异。
• 实体生命周期引擎实现规范.md — Interaction.event 命名表（onLaunch / onLoad / onEnter / onLeave / onChange / onSuccess / onError / onSettled / onMount / onUnmount 等）以及谁挂载哪些事件。
• 设计器静态依赖分析方案.md — DynamicExpression 的 AST 解析、依赖图谱、变量重命名级联策略。
• 设计器悬浮组件架构规范.md — Modal/Drawer 不享受 Schema 特权；isOverlay 是 Component Registry 元数据，不进 Schema。
• 设计器选中与分组交互规范.md — selectedIds / activeContainerId 仅在设计态运行时 Store。

常见误区

• 不要在 Page 下新增 modals: Component[] 等"特权数组"，悬浮组件统一走 components 树。
• 不要把组件注册元数据（isOverlay / isContainer / setters）放进 Schema —— 那是物料库静态字典。
• 不要把 prefetch / polling / enabled 等查询配置复制到 Mutation，Mutation 只能命令式触发。
• 不要把 React 生命周期等价于业务生命周期 —— 全部走 Interaction，避免 Strict Mode 双调用陷阱。