chore: prepare v1.0.0 release

Author: leosin

.ai/PRD.md

@@ -1,7 +1,7 @@
 # Directus Schema Kit 产品需求
 
 > 状态：当前实现基线  
-> 当前里程碑：Manifest V3  
+> 当前里程碑：Manifest V1
 > 包：`@deeptimes/directus-schema-kit`
 
 ## 产品定位
@@ -37,7 +37,7 @@ DSK 的目标是让 Directus 数据模型具备代码审查、类型约束、可
 - 严格类型的 `collection()`、`collectionGroup()`、`defineSchema()` 和 `field.*()` DSL。
 - M2O、O2M、M2M、M2A、Translations、File、Image、Files 关系 blueprint。
 - Markdown、Tags、Code、Toggle 等 Directus interface helper。
-- Manifest V3：扁平、确定性、完整展开，并携带源码 SHA-256 摘要。
+- Manifest V1：扁平、确定性、完整展开，并携带源码 SHA-256 摘要。
 - 离线校验重复定义、主键、关系完整性、引用和源码新鲜度。
 
 ### Plan 与 Apply
@@ -84,7 +84,7 @@ DSK 的目标是让 Directus 数据模型具备代码审查、类型约束、可
 ## 验收标准
 
 - `init` 不覆盖已有文件，`--dry-run` 不写入，非 Directus 项目不生成工作区。
-- `build` 生成字节级稳定、无 secret、通过 JSON Schema 校验的 Manifest V3。
+- `build` 生成字节级稳定、无 secret、通过 JSON Schema 校验的 Manifest V1。
 - `validate` 能发现重复定义、无效关系、缺失引用和过期 Manifest。
 - 首次 Apply 可建立完整 Schema；第二次 Plan 不存在可执行差异。
 - 八类关系在 Directus 11.17.4 + SQLite 完成构建、校验、应用和幂等测试。

.ai/README.md

@@ -16,4 +16,4 @@
 - 产品决策、实现约束、测试策略和待办放在 `.ai/`。
 - 安装、使用、CLI 和公开格式说明放在 [`docs/`](../docs/README.md)。
 - 已由代码、测试或 Git 历史表达的过程信息不在文档中重复维护。
-- 当前“V3”指 Manifest 格式版本；npm 包版本以 `package.json` 为准。
+- 当前 Manifest 格式版本为 V1；npm 包版本以 `package.json` 为准。

.ai/development.md

@@ -9,7 +9,7 @@
 | Directus | 11.17.4 |
 | 数据库 | SQLite |
 | 包管理器 | pnpm 11.5.2 |
-| Manifest | V3 |
+| Manifest | V1 |
 
 Directus 12.0.2 只完成结构评估，不能标记为正式支持。
 
@@ -60,6 +60,6 @@ pnpm check:release
 - Plan Engine 是纯函数，网络读取和写入使用分离 Adapter。
 - 未声明的实例资源不会被推断为删除；白名单外差异默认 conflict。
 - Apply 遇到任一 conflict/dangerous 全量阻断，写入串行且不伪装为事务。
-- Manifest V3 移除 modules；所有定义全局组合，`source` 只用于定位。
+- Manifest V1 不包含 modules；所有定义全局组合，`source` 只用于定位。
 - 复合关系必须展开为完整 junction、字段和 relations；不得用单 alias 模拟。
 - 普通 Schema apply 永不删除；系统资源删除和 Clear 使用不同的显式授权路径。

.ai/schema-authoring.md

@@ -1,6 +1,6 @@
 # Schema 编写规则
 
-本文档面向使用 Codex/AI 为 Directus 项目编写 DSK schema 的场景。目标是让生成的 `dsk/schemas/*.ts` 稳定符合项目 DSL、Directus 规范和 Manifest V3 执行边界，避免 AI 自行发明 API 或产生 schema 漂移。
+本文档面向使用 Codex/AI 为 Directus 项目编写 DSK schema 的场景。目标是让生成的 `dsk/schemas/*.ts` 稳定符合项目 DSL、Directus 规范和 Manifest V1 执行边界，避免 AI 自行发明 API 或产生 schema 漂移。
 
 ## 开始前必须阅读
 

README.md

@@ -49,4 +49,4 @@ pnpm dsk clear --confirm
 
 `build` 会执行可信的项目 TypeScript 源码；后续 `plan/apply` 执行层只允许消费 `dsk/generated/manifest.json`。
 
-详细文档从 [文档首页](docs/README.md) 开始，也可直接查看 [快速开始](docs/quick-start.md)、[CLI 参考](docs/cli-reference.md)、[Schema DSL](docs/schema-dsl.md)、[Manifest V3](docs/manifest.md) 和 [兼容性](docs/compatibility.md)。
+详细文档从 [文档首页](docs/README.md) 开始，也可直接查看 [快速开始](docs/quick-start.md)、[CLI 参考](docs/cli-reference.md)、[Schema DSL](docs/schema-dsl.md)、[Manifest V1](docs/manifest.md) 和 [兼容性](docs/compatibility.md)。

docs/README.md

@@ -1,6 +1,6 @@
 # Directus Schema Kit 文档
 
-DSK 使用 TypeScript DSL 声明 Directus Schema，通过 Manifest V3 校验和规划差异，再将安全变更应用到本地开发实例。
+DSK 使用 TypeScript DSL 声明 Directus Schema，通过 Manifest V1 校验和规划差异，再将安全变更应用到本地开发实例。
 
 ## 开始使用
 
@@ -10,12 +10,13 @@ DSK 使用 TypeScript DSL 声明 Directus Schema，通过 Manifest V3 校验和
 
 ## 设计与约束
 
-- [Manifest V3](./manifest.md)：生成格式、执行边界和旧版本迁移。
+- [Manifest V1](./manifest.md)：生成格式和执行边界。
+- [AI Schema 编写规则](./ai-schema-authoring.md)：让 Codex/AI 在业务项目中稳定编写 DSK schema 的提示词和约束。
 - [兼容性](./compatibility.md)：认证环境、字段类型和关系支持范围。
 - [安全边界](./security.md)：连接限制、危险操作和凭证保护。
 
 ## 版本说明
 
-文档中的 V3 指 Manifest 格式版本，不代表 npm 包主版本。实际包版本以安装结果或 `dsk --version` 为准。
+文档中的 Manifest V1 指 Manifest 格式版本，不代表 npm 包主版本。实际包版本以安装结果或 `dsk --version` 为准。
 
 当前正式认证环境为 Node.js 22+、Directus 11.17.4 和 SQLite。Directus 12.x 尚未正式认证。

docs/ai-schema-authoring.md

@@ -0,0 +1,53 @@
+# AI Schema 编写规则
+
+本文档用于放入业务 Directus 项目，约束 Codex/AI 使用 DSK 编写 `dsk/schemas/*.ts`、`dsk/resources/*.ts` 和 `dsk/seeds/**/*.json`。
+
+## 开始前
+
+让 AI 写 schema 前，应要求它先阅读：
+
+1. 当前业务项目的 `dsk/` 目录。
+2. 当前业务项目已有的 `.ai/` 规则文档。
+3. DSK 文档中的 [Schema DSL](./schema-dsl.md)。
+4. DSK 文档中的 [Manifest V1](./manifest.md)。
+
+## 必须遵守
+
+- 只从 `@deeptimes/directus-schema-kit` 导入公开 API。
+- 不手写、不编辑 `dsk/generated/manifest.json`。
+- 文件名只用于组织源码，不代表 Directus namespace。
+- collection 名在整个项目中全局唯一。
+- 一个 collection 只能在一个文件中完整定义。
+- 关系优先使用 `relation.*` blueprint。
+- `field.audit()` 在 `fields` 数组中必须写作 `...field.audit()`。
+- `plan`、`apply` 和 `clear` 始终基于完整 Manifest，不按文件局部执行。
+- 普通 `apply` 不做删除、字段类型迁移、collection 重命名或存量数据迁移。
+
+## 命名约定
+
+- collection 和 field 使用小写 `snake_case`。
+- 业务 collection 默认使用复数名，例如 `articles`、`products`。
+- 业务 collection 禁止使用 `directus_` 前缀。
+- 主键使用 `id`。
+- 内容状态字段使用 `status`。
+- 手动排序字段使用 `sort`。
+- 审计字段使用 `...field.audit()`。
+- 业务时间字段使用 `date_` 前缀。
+- 用户关系字段使用 `user_` 前缀。
+- 布尔字段使用 `is_` 前缀。
+
+## 禁止
+
+- 发明 DSK 未公开的 helper、字段类型或导入路径。
+- 把 Directus interface/display/special 当成数据库类型。
+- 声明或修改 `directus_*` 系统 collection。
+- 用 `created_at`、`updated_at`、`created_by`、`updated_by` 替代 Directus 标准审计字段。
+- 用 JSON 数组保存文件 ID 或多用户 ID。
+- 硬编码 Directus role、policy、user 等系统资源 UUID。
+- 声明 Flow、Operation、Dashboard、Panel，当前版本不支持。
+
+## 推荐提示词
+
+```text
+你正在为 Directus 项目编写 DSK schema。开始前必须阅读当前项目 .ai/、dsk/ 和 DSK 的 docs/schema-dsl.md、docs/manifest.md。不要手写 Manifest，不要修改 dsk/generated/manifest.json。所有 relation 优先使用 relation.* blueprint。修改后运行 pnpm dsk build 和 pnpm dsk validate；如果涉及真实实例差异，再运行 pnpm dsk plan。
+```

docs/compatibility.md

@@ -14,7 +14,7 @@ Directus 12.0.2 官方类型中的字段常量、关系类型和 Relation Meta 
 | 项目 | 支持范围 |
 | --- | --- |
 | Node.js | 22+ |
-| Manifest | V3 |
+| Manifest | V1 |
 | 操作系统 | CI 使用 Linux；日常开发支持 macOS |
 
 ## Field Type 映射

docs/manifest.md

@@ -1,10 +1,10 @@
-# Manifest V3
+# Manifest V1
 
 `dsk/generated/manifest.json` 是 `build` 的确定性输出，也是 plan/apply 唯一执行输入。
 
 顶层字段：
 
-- `manifestVersion`：当前生成版本为 3；旧版本需要重新执行 build。
+- `manifestVersion`：当前生成版本为 1；不兼容的 Manifest 需要重新执行 build。
 - `generator`：包名与版本。
 - `source`：源码摘要和参与构建的文件；每项定义使用 `source` 定位来源文件。
 - `collections`、`fields`、`relations`：完全展开的 Schema。
@@ -14,17 +14,17 @@ Manifest 不包含函数、解析后的 secret 或生成时间戳。`plan/apply`
 
 ## 扁平模型
 
-V3 移除 modules。所有 Schema 文件编译到全局唯一的 collections、fields 和 relations；定义上的 `source` 仅用于定位源码。V3 继续允许 M2A 的 `related_collection: null` 并完整保存 Relation Meta。M2M、Files、Translations 和 M2A blueprint 在 build 时展开，Manifest 中不保留 blueprint。
+Manifest V1 不包含 modules。所有 Schema 文件编译到全局唯一的 collections、fields 和 relations；定义上的 `source` 仅用于定位源码。Manifest V1 允许 M2A 的 `related_collection: null` 并完整保存 Relation Meta。M2M、Files、Translations 和 M2A blueprint 在 build 时展开，Manifest 中不保留 blueprint。
 
 复合关系的两条 junction relations 必须通过 `meta.junction_field` 互相引用。缺少反向引用时 Directus Studio 会把 alias 误判为 O2M，并报告 M2M/M2A Interface 不可用；validate 会拒绝这种不完整结构。
 
 创建顺序固定为 collection（含 junction）→ 非 alias 字段 → relation → alias 字段。关系目标、删除策略、junction 结构和 M2A allowed collections 的变化属于 dangerous；当前仅 `meta.sort_field` 属于可安全更新。
 
-## 从旧 Manifest 迁移
+## 重新生成 Manifest
 
 - 原 `field.m2o()` 无需修改。
-- 将 `defineModule({ id, version, dependsOn, cleanupCollections, ... })` 改为 `defineSchema({ ... })`，删除模块字段。
+- 如果项目内存在早期实验 Manifest，将 Schema DSL 保持为 `defineSchema({ ... })` 或公开 DSL 导出。
 - 如果项目仍使用 `.dsk/`，将 config、seeds 和 generated 移入 `dsk/`，并更新配置中的相对路径。
-- 重新执行 `dsk build` 生成 V3；V1/V2 Manifest 不再供 validate/plan/apply 读取。
+- 重新执行 `dsk build` 生成 Manifest V1；validate/plan/apply 只读取当前版本 Manifest。
 - 未知版本会明确报错并提示重新 build，不会尝试猜测结构。
 - 旧项目若用单一 alias 字段模拟 M2M/M2A，应改用对应 `relation.*`，由 build 生成完整资源。

docs/quick-start.md

@@ -35,9 +35,11 @@ dsk/
   resources/
   seeds/
   generated/manifest.json
+.ai/
+  directus-schema-kit.md
 ```
 
-人工维护 `schemas/`、`resources/`、`seeds/` 和 `config.json`；`generated/manifest.json` 由 `build` 生成，不要手工修改。
+人工维护 `schemas/`、`resources/`、`seeds/`、`config.json` 和 `.ai/directus-schema-kit.md`；`generated/manifest.json` 由 `build` 生成，不要手工修改。
 
 首次 Apply 后再次执行：