核心链路

ZoneDSL 的工作流水线本质上是四步:

1. AI 后端流式吐出一段 markdown + zone-DSL 混排文本
2. 前端 agentChat 页把 content 拿到,交给 buildAst()
3. towxml/index.js 里的 extractZoneBlocks() 先拆出 zone 块, markdown 走 towxml 原有解析,zone 块交给 zone-dsl/toWxNodes.js 转成组件节点树
4. 页面渲染层遇到 item.isZone 派发给统一的 <zone-node> 组件, wxml 里 60+ 个 wx:elif 分支各自渲染成对应 zone 组件

Hello ZoneDSL

最短的一个 zone 组件:

::text "你好, ZoneDSL"

渲染出来就是一段正文文字。::<组件名> 就是 ZoneDSL 的核心语法。

纯 markdown 用法

ZoneDSL 不排斥 markdown——你完全可以只写 markdown,ZoneDSL 引擎会照常 把它交给 towxml(此处以小程序平台为例) 渲染,得到跟你熟悉的 markdown 一样的结果:

# 一级标题

正文段落,可以用 **加粗**、*斜体*、==高亮==、`inline code`。

- 列表项 1
- 列表项 2

| 表头 | 数值 |
| --- | --- |
| A | 1 |

加入 zone 组件

markdown 里穿插 :: 组件(前后各空一行),得到杂志式结构化输出:

# 今日热议三看点

今天有三条线索都值得看。

::magazine-cover tag="HOT SPOTS · 07.03"
  title="今日三焦点"
  bg=light

## 焦点一: 盛夏夜

正文段落...

::numbered-list "看点在哪"
  item "四姐气场碰撞"
  item "南美世界杯氛围"

切换主题

ZoneDSL 内置 12 套主题——7 套杂志系作用于 zone 组件, 5 套 markdown 接管系让纯 markdown 也整体变杂志视觉。

不写 ::theme 就是默认 editorial 暖橙风。要切主题:

::theme purple

# 我的备忘录

正文段落——现在整块内容会变成紫底黄胶囊白卡片的杂志视觉。

可用主题:editorial / literary / serious / data / serene / warm / luxe / purple / sky / pop / sage / note。详见 组件全览 · 12 主题。

1. 让 AI 学会输出 ZoneDSL 必做

ZoneDSL 的核心使用者是 AI——你的用户几乎不需要手写 DSL,而是让 AI 后端(Claude / GPT / 自研 agent)在流式输出里自动生成。所以第一件事是让 AI 学会。

推荐加载 zonedsl skill——一份 20KB 结构化提示词,写清楚了「什么时候用 / 怎么写 / 避坑清单 / 6 个模板 / 62 个组件目录」。agent 加载后会按规范输出,不用逐句 few-shot。

方式 A · Claude Code(推荐)

# 下载并解压到 skills 目录
curl -O https://<你的域名>/assets/zonedsl-skill.zip
unzip zonedsl-skill.zip -d ~/.claude/skills/

# 目录结构:
~/.claude/skills/zonedsl/
├── SKILL.md              # agent 加载时读的主文件
├── CATALOG-PRIMITIVE.md  # 按需查的组件字典
├── CATALOG-STRUCTURE.md
├── CATALOG-INTERACTIVE.md
├── CATALOG-CHART.md
└── CATALOG-PRESET.md

# Claude Code 会自动识别 skill,当用户对话触发 description 条件时激活

方式 B · Agent SDK / 自定义 agent

不用 Claude Code 的话,把 SKILL.md 内容作为 system prompt / 工具说明加载即可——skill 本质是结构化提示词,兼容任何 markdown 的 agent 框架。

// OpenAI Function Calling / Anthropic Tool Use 都可以直接注入
const systemPrompt = fs.readFileSync('./skills/zonedsl/SKILL.md', 'utf-8')
const response = await anthropic.messages.create({
  system: systemPrompt,
  // ...
})

2. 安装到你的项目

AI 学会输出后,前端需要能渲染。ZoneDSL 已拆成 npm 包:@zonedsl/core(parser) + @zonedsl/web(Web 渲染器) + @zonedsl/wechat(小程序运行时,生产验证) + @zonedsl/skill(AI 规范)。

装上开发者 skill,你不用翻文档,AI 就能替你把接入和二次开发都做了。 装完直接说「帮我把 zonedsl 接入我这个小程序」/「我要加个新组件叫 xxx」/「我要在 Web 端复刻一份」,AI 会自动查 4 处登记规范、层归属、主题变量、intent 白名单——你只用负责决策和 review 代码。

Web 安装(v1 已就绪)

npm i @zonedsl/core @zonedsl/web,或直接 <script src> 引 UMD:

<!-- CDN -->
<script src="https://unpkg.com/@zonedsl/core/dist/parser.umd.js"></script>
<script src="https://unpkg.com/@zonedsl/web/dist/zonedsl-web.umd.js"></script>
<div id="out"></div>
<script>
  ZonePlayground.mount(document.getElementById('out'), '::callout "Hello"')
</script>

流式渲染传 { streaming: true },骨架传 { skeleton: true }。注册自定义组件用 ZonePlayground.register('my-comp', fn)(parser 零改动,见 协议 §10)。

WeChat 小程序

@zonedsl/wechat(zone-node 派发组件 + towxml + 12 主题,生产验证):

// index.json
{
  "usingComponents": {
    "towxml": "@zonedsl/wechat/towxml/towxml",
    "zone-node": "@zonedsl/wechat/zone-node/index"
  }
}
// index.js
const { toAst } = require('@zonedsl/wechat')
const ast = toAst(content, { streamingSafe: true })
// <towxml nodes="{{ast}}" bindzoneaction="onZoneAction" />

3. 实现 zone-action 分发器

DSL 里 ::button intent=xxx value=yyy 点击会触发 intent,业务方在分发器里实现具体跳转(平台无关,详见 @zonedsl/core/INTENTS.md):

// Web
handleZoneAction(intent, value) {
  switch (intent) {
    case 'search': location.href = `/search?q=${value}`; break
    case 'copy': navigator.clipboard.writeText(value); break
    case 'followup': /* 填输入框 */ break
    // ... 其他 intent 按你项目实现
  }
}
// WeChat: onZoneAction(e) { const {intent,value}=e.detail; ... }