@yaoxiu/marketing-dsl 1.2.0 → 1.4.0

package/dist/docs/index.d.cts

@@ -0,0 +1,170 @@
+import { D as Dsl } from '../types-BgUaJUAu.cjs';
+
+/**
+ * 开发文档的数据结构。
+ *
+ * 文档正文本身就是数据（一棵块数组），不是 HTML 也不是 Markdown 字符串。
+ * 这样同一份内容既能被调试台渲染成页面，又能被 `toMarkdown` 导出成 .md，
+ * 两边永远不会不一致。
+ *
+ * 渲染方（调试台的 DocsPanel）按 `t` 分派即可，这里给出的类型就是它需要处理的全集。
+ */
+/** 提示块的语气，决定渲染时的配色 */
+type DocNoteTone = 'info' | 'warn' | 'danger';
+/** 段落：一段普通正文，允许内嵌 `` `代码` `` 和 `**加粗**` 的 Markdown 行内标记 */
+interface DocParagraphBlock {
+    t: 'p';
+    /** 正文内容 */
+    text: string;
+}
+/** 三级小标题：章节（`DocSection.title`）内部的分节标题 */
+interface DocHeadingBlock {
+    t: 'h3';
+    /** 标题文字 */
+    text: string;
+}
+/** 无序列表 */
+interface DocListBlock {
+    t: 'list';
+    /** 每一项的文字，同样允许行内 Markdown 标记 */
+    items: string[];
+}
+/** 代码块：一律按 jsonc 高亮（文档里的代码全是 DSL 配置片段，带注释） */
+interface DocCodeBlock {
+    t: 'code';
+    /** 代码正文，不含围栏 */
+    code: string;
+}
+/** 提示块：需要单独框出来的注意事项 */
+interface DocNoteBlock {
+    t: 'note';
+    /** 语气，不写按 info 处理 */
+    tone?: DocNoteTone;
+    /** 提示内容 */
+    text: string;
+}
+/** 表格 */
+interface DocTableBlock {
+    t: 'table';
+    /** 表头 */
+    head: string[];
+    /** 数据行，每行的长度应与 `head` 一致 */
+    rows: string[][];
+}
+/** 文档正文的一个块 */
+type DocBlock = DocParagraphBlock | DocHeadingBlock | DocListBlock | DocCodeBlock | DocNoteBlock | DocTableBlock;
+/** 文档的一个章节（对应页面左侧目录的一项） */
+interface DocSection {
+    /** 锚点 id，页面目录跳转用，全局唯一 */
+    id: string;
+    /** 章节标题，带序号，如 `3. stage 舞台` */
+    title: string;
+    /** 章节正文 */
+    blocks: DocBlock[];
+}
+/** 一条文档变更记录 */
+interface DocChangelogEntry {
+    /** 变更日期，`YYYY-MM-DD` */
+    date: string;
+    /** 这次改了什么，一条一句话 */
+    items: string[];
+}
+/** 文档的版本与变更信息 */
+interface DocMeta {
+    /** 最近一次更新日期，等于 `changelog[0].date` */
+    updatedAt: string;
+    /** 对应的 DSL 结构版本号，取自解释器常量 `DSL_VERSION`，不手写 */
+    dslVersion: number;
+    /** 变更记录，新的在前 */
+    changelog: DocChangelogEntry[];
+}
+
+/**
+ * 开发文档全部章节，按阅读顺序拼起来。
+ *
+ * 章节按主题拆成多个文件，只有这里决定顺序；加章节时记得同步文件里的序号，
+ * 序号是写在 `title` 里的（正文有大量「见第 N 节」的交叉引用）。
+ */
+
+/** 完整文档章节列表（0~14 节） */
+declare const sections: DocSection[];
+
+declare const meta: DocMeta;
+
+/**
+ * 调试用示例 DSL。
+ *
+ * ①② 是最小骨架，③④ 是运营 demo 真实弹窗的完整复刻，⑤⑥ 是多视图，⑦ 是换肤换布局。
+ * 后端数据源（$source）用法见 ③。
+ */
+
+/** 调试台下拉里的一条示例 */
+interface DocExample {
+    /** 下拉里显示的名字 */
+    label: string;
+    /** 唯一标识，AI 提示词按它取示例 */
+    value: string;
+    /** 示例配置本体 */
+    dsl: Dsl;
+}
+declare const examples: DocExample[];
+
+/**
+ * 把文档章节数据转成 Markdown，供页面导出下载。
+ * 章节数据本身就是唯一数据源，所以导出的 md 不会和页面上看到的不一致。
+ */
+
+/**
+ * 把整份文档导出成 Markdown。
+ *
+ * @param sections 章节数据
+ * @param meta 版本与变更记录
+ * @returns Markdown 全文
+ */
+declare function toMarkdown(sections: DocSection[], meta: DocMeta): string;
+
+/**
+ * 拼出完整的 AI 提示词。
+ *
+ * @returns 可直接粘进 AI 对话框的 Markdown 文本
+ */
+declare function buildAiPrompt(): string;
+
+/**
+ * 文档与解释器对账。
+ *
+ * 文档里的表格是人工整理的（分类、说明、关键字段），这些信息解释器里没有，
+ * 所以不能直接从常量生成。但人工维护必然会漏——解释器加了个属性，
+ * 文档不改就静默过时，运营翻文档发现不了新能力，AI 也生成不出来。
+ *
+ * 所以这里不替代人工表格，只做对账：
+ *   - 解释器有、文档没写 → 自动补一行「新增（待补充说明）」，不会消失
+ *   - 文档写了、解释器已经没有 → 标出来，提醒删掉，免得运营照着写结果被校验拦下
+ *
+ * 两种情况都在页面上直接可见，改 DSL 的人一打开文档就会看到。
+ */
+/** 对账参数 */
+interface ReconcileOptions {
+    /** 文档表格的数据行 */
+    rows: string[][];
+    /** 解释器里的真实清单（如 `NODE_TYPES`） */
+    actual: readonly string[];
+    /** 标识符在第几列，默认第 0 列 */
+    column?: number;
+    /**
+     * 标识符是否散落在单元格文本里（样式白名单那种一格塞一堆的表）。
+     * true 时按反引号提取，false 时把整格当成一个标识符。
+     */
+    inline?: boolean;
+    /** 「文档未覆盖」那一行的分类名，如 `新增节点类型` */
+    label?: string;
+}
+/**
+ * 对账并生成要追加到表格末尾的差异行。
+ *
+ * @param options 对账参数
+ * @returns 追加行；没有差异时是空数组
+ */
+declare function reconcileRows(options: ReconcileOptions): string[][];
+
+export { type DocBlock, type DocChangelogEntry, type DocCodeBlock, type DocHeadingBlock, type DocListBlock, type DocMeta, type DocNoteBlock, type DocNoteTone, type DocParagraphBlock, type DocSection, type DocTableBlock, type ReconcileOptions, buildAiPrompt, examples, meta, reconcileRows, sections, toMarkdown };

package/dist/docs/index.d.ts

@@ -0,0 +1,170 @@
+import { D as Dsl } from '../types-BgUaJUAu.js';
+
+/**
+ * 开发文档的数据结构。
+ *
+ * 文档正文本身就是数据（一棵块数组），不是 HTML 也不是 Markdown 字符串。
+ * 这样同一份内容既能被调试台渲染成页面，又能被 `toMarkdown` 导出成 .md，
+ * 两边永远不会不一致。
+ *
+ * 渲染方（调试台的 DocsPanel）按 `t` 分派即可，这里给出的类型就是它需要处理的全集。
+ */
+/** 提示块的语气，决定渲染时的配色 */
+type DocNoteTone = 'info' | 'warn' | 'danger';
+/** 段落：一段普通正文，允许内嵌 `` `代码` `` 和 `**加粗**` 的 Markdown 行内标记 */
+interface DocParagraphBlock {
+    t: 'p';
+    /** 正文内容 */
+    text: string;
+}
+/** 三级小标题：章节（`DocSection.title`）内部的分节标题 */
+interface DocHeadingBlock {
+    t: 'h3';
+    /** 标题文字 */
+    text: string;
+}
+/** 无序列表 */
+interface DocListBlock {
+    t: 'list';
+    /** 每一项的文字，同样允许行内 Markdown 标记 */
+    items: string[];
+}
+/** 代码块：一律按 jsonc 高亮（文档里的代码全是 DSL 配置片段，带注释） */
+interface DocCodeBlock {
+    t: 'code';
+    /** 代码正文，不含围栏 */
+    code: string;
+}
+/** 提示块：需要单独框出来的注意事项 */
+interface DocNoteBlock {
+    t: 'note';
+    /** 语气，不写按 info 处理 */
+    tone?: DocNoteTone;
+    /** 提示内容 */
+    text: string;
+}
+/** 表格 */
+interface DocTableBlock {
+    t: 'table';
+    /** 表头 */
+    head: string[];
+    /** 数据行，每行的长度应与 `head` 一致 */
+    rows: string[][];
+}
+/** 文档正文的一个块 */
+type DocBlock = DocParagraphBlock | DocHeadingBlock | DocListBlock | DocCodeBlock | DocNoteBlock | DocTableBlock;
+/** 文档的一个章节（对应页面左侧目录的一项） */
+interface DocSection {
+    /** 锚点 id，页面目录跳转用，全局唯一 */
+    id: string;
+    /** 章节标题，带序号，如 `3. stage 舞台` */
+    title: string;
+    /** 章节正文 */
+    blocks: DocBlock[];
+}
+/** 一条文档变更记录 */
+interface DocChangelogEntry {
+    /** 变更日期，`YYYY-MM-DD` */
+    date: string;
+    /** 这次改了什么，一条一句话 */
+    items: string[];
+}
+/** 文档的版本与变更信息 */
+interface DocMeta {
+    /** 最近一次更新日期，等于 `changelog[0].date` */
+    updatedAt: string;
+    /** 对应的 DSL 结构版本号，取自解释器常量 `DSL_VERSION`，不手写 */
+    dslVersion: number;
+    /** 变更记录，新的在前 */
+    changelog: DocChangelogEntry[];
+}
+
+/**
+ * 开发文档全部章节，按阅读顺序拼起来。
+ *
+ * 章节按主题拆成多个文件，只有这里决定顺序；加章节时记得同步文件里的序号，
+ * 序号是写在 `title` 里的（正文有大量「见第 N 节」的交叉引用）。
+ */
+
+/** 完整文档章节列表（0~14 节） */
+declare const sections: DocSection[];
+
+declare const meta: DocMeta;
+
+/**
+ * 调试用示例 DSL。
+ *
+ * ①② 是最小骨架，③④ 是运营 demo 真实弹窗的完整复刻，⑤⑥ 是多视图，⑦ 是换肤换布局。
+ * 后端数据源（$source）用法见 ③。
+ */
+
+/** 调试台下拉里的一条示例 */
+interface DocExample {
+    /** 下拉里显示的名字 */
+    label: string;
+    /** 唯一标识，AI 提示词按它取示例 */
+    value: string;
+    /** 示例配置本体 */
+    dsl: Dsl;
+}
+declare const examples: DocExample[];
+
+/**
+ * 把文档章节数据转成 Markdown，供页面导出下载。
+ * 章节数据本身就是唯一数据源，所以导出的 md 不会和页面上看到的不一致。
+ */
+
+/**
+ * 把整份文档导出成 Markdown。
+ *
+ * @param sections 章节数据
+ * @param meta 版本与变更记录
+ * @returns Markdown 全文
+ */
+declare function toMarkdown(sections: DocSection[], meta: DocMeta): string;
+
+/**
+ * 拼出完整的 AI 提示词。
+ *
+ * @returns 可直接粘进 AI 对话框的 Markdown 文本
+ */
+declare function buildAiPrompt(): string;
+
+/**
+ * 文档与解释器对账。
+ *
+ * 文档里的表格是人工整理的（分类、说明、关键字段），这些信息解释器里没有，
+ * 所以不能直接从常量生成。但人工维护必然会漏——解释器加了个属性，
+ * 文档不改就静默过时，运营翻文档发现不了新能力，AI 也生成不出来。
+ *
+ * 所以这里不替代人工表格，只做对账：
+ *   - 解释器有、文档没写 → 自动补一行「新增（待补充说明）」，不会消失
+ *   - 文档写了、解释器已经没有 → 标出来，提醒删掉，免得运营照着写结果被校验拦下
+ *
+ * 两种情况都在页面上直接可见，改 DSL 的人一打开文档就会看到。
+ */
+/** 对账参数 */
+interface ReconcileOptions {
+    /** 文档表格的数据行 */
+    rows: string[][];
+    /** 解释器里的真实清单（如 `NODE_TYPES`） */
+    actual: readonly string[];
+    /** 标识符在第几列，默认第 0 列 */
+    column?: number;
+    /**
+     * 标识符是否散落在单元格文本里（样式白名单那种一格塞一堆的表）。
+     * true 时按反引号提取，false 时把整格当成一个标识符。
+     */
+    inline?: boolean;
+    /** 「文档未覆盖」那一行的分类名，如 `新增节点类型` */
+    label?: string;
+}
+/**
+ * 对账并生成要追加到表格末尾的差异行。
+ *
+ * @param options 对账参数
+ * @returns 追加行；没有差异时是空数组
+ */
+declare function reconcileRows(options: ReconcileOptions): string[][];
+
+export { type DocBlock, type DocChangelogEntry, type DocCodeBlock, type DocHeadingBlock, type DocListBlock, type DocMeta, type DocNoteBlock, type DocNoteTone, type DocParagraphBlock, type DocSection, type DocTableBlock, type ReconcileOptions, buildAiPrompt, examples, meta, reconcileRows, sections, toMarkdown };