skycurtain
973f74d0d8
- 将文档标题和结构重定向为 Agent 协作指南，强调“严禁直接改代码”的铁律 - 清晰定义当前项目阶段：仅有核心 Schema 类型定义，无运行时代码 - 详细说明工具链（Bun）、语言（中文注释）和 Schema 架构铁律 - 列出设计文档位置和常见误区，以指导后续开发决策
71 lines
6.0 KiB
Markdown
71 lines
6.0 KiB
Markdown
# 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 双调用陷阱。
|