ConfigUnit DSL 入门

ConfigUnit DSL 是 Aiko Studio 的核心配置语言——一段 JSON 同时声明：这是什么文档类型、它背后存什么数据、它用到哪些定义集。

读完这页你能：

看懂一份 ConfigUnit DSL 在描述什么
知道 dsl 与 published_dsl 的区别
写出最小可发布的 ConfigUnit

这页是入门

完整字段参考请看 ConfigUnit DSL Schema；DocType / Entity 的设计模式请看 DocType 与 Entity 设计。

一份最小 ConfigUnit 长什么样

cfg.brd-ecommerce.json

{
  "id": "cfg.brd-ecommerce",
  "name": "电商 BRD 配置单元",
  "version": "0.1.0",

  // 1. DocType - 文档结构
  "docType": {
    "id": "doctype.brd-ecommerce",
    "name": "电商 BRD",
    "chapters": [
      {
        "id": "background",
        "name": "业务背景",
        "render": "rich-text"
      },
      {
        "id": "scope",
        "name": "范围",
        "render": "form",
        "entityField": "scope"
      }
    ]
  },

  // 2. Entity - 数据字段
  "entity": {
    "id": "entity.brd-ecommerce",
    "name": "电商 BRD 实体",
    "fields": [
      {
        "name": "scope",
        "type": "object",
        "properties": {
          "in_scope":  { "type": "array", "items": { "type": "string" } },
          "out_scope": { "type": "array", "items": { "type": "string" } }
        }
      }
    ]
  },

  // 3. DefinitionSets 引用 - 共享枚举
  "definitionSets": [
    { "ref": "defs.priority" }
  ]
}

三个组成部分

DocType（文档结构）

声明一份文档由哪些章节组成。每个章节有一个 render 决定 UI 渲染方式：

`render` 值	UI 形态	典型场景
`rich-text`	富文本编辑器	业务背景、术语解释
`form`	字段表单	角色信息、配置项
`table`	表格	成功指标、风险登记
`canvas`	画布	流程图、架构图（路线图）

需要把章节的内容存到结构化字段时，加 entityField 把它绑到 Entity 的某个字段上。rich-text 章节如果没绑 entityField，内容会直接以富文本形式存在 DocumentInstance 上。

Entity（数据字段）

声明文档背后的结构化数据。字段类型支持 string / number / boolean / array / object / 引用其他 Entity。

ConfigUnit · entity 段

"entity": {
  "id": "entity.brd-ecommerce",
  "fields": [
    { "name": "title",    "type": "string",  "required": true },
    { "name": "owner",    "type": "string" },
    { "name": "priority", "type": "string",  "definitionSet": "defs.priority" },
    { "name": "scope",    "type": "object",  "properties": { ... } }
  ]
}

definitionSet 字段把这个枚举绑到团队共享的 DefinitionSet 上——值会在工作台显示为下拉选项。

DefinitionSets（共享定义集）

ConfigUnit 不在内部直接定义"优先级有哪几档"，而是引用团队级别共享的 DefinitionSet：

ConfigUnit · definitionSets 段

"definitionSets": [
  { "ref": "defs.priority" },
  { "ref": "defs.lifecycle-stage" }
]

这样多个 ConfigUnit（BRD / PRD / 技术设计）都引用同一个 defs.priority，团队改一处，所有文档生效。

DefinitionSet 自身在管理后台单独管理。

草稿与发布

ConfigUnit 有两份字段：

字段	谁读	谁写
`dsl`	管理后台编辑器	管理员当下在改的版本
`published_dsl`	工作台	点「发布」时从 `dsl` 拷过来

关键点：业务用户的工作台只读 published_dsl。所以管理员改 dsl 不会立即影响在用项目——这是个有意的安全网，避免改一半的 DSL 把全员的工作台搞崩。

发布流程：

已发布的 ConfigUnit 改字段要小心

删除 Entity 里已被使用的字段、改 DocType 章节 id，会让历史 DocumentInstance 显示错乱。详见草稿 / 发布工作流的破坏性变更检查清单（写作中）。

在管理后台编辑 DSL

入口：管理后台 → ConfigUnit 列表 → 选一个 → 编辑。

编辑器有两种视图：

DSL 视图（JSON 直编辑）—— 所有字段都能改，适合熟悉 schema 的管理员
DocTypeEditor 视图（可视化）—— 拖章节、配字段、绑实体，详见 DocType 与 Entity 设计

两个视图同步——可视化改动会实时同步到 DSL JSON，反之亦然。

一份 ConfigUnit 的生命周期

1. 管理员新建 ConfigUnit（dsl 为空）
2. 在 DocTypeEditor 拖出章节、配 Entity 字段
3. 引用 DefinitionSet
4. Preview：试创建一份 DocumentInstance 走通
5. 发布 → published_dsl 更新
6. 在 ProjectType 里关联这个 ConfigUnit
7. 业务用户在该类型项目下能新建对应 DocType 的文档

下一步

看完整字段参考：ConfigUnit DSL Schema
学怎么设计章节和实体：DocType 与 Entity 设计
学发布的安全检查：草稿 / 发布工作流

ConfigUnit DSL 入门

On this page