dexin-content 0.3.0 → 0.3.1

package/README.md

@@ -10,12 +10,18 @@
 - **Collection**：集合声明、发现、批量编译与增量变化检测
 - **Diff**：Canonical JSON 序列化与对象级差异原语（Golden/Regress 管线使用）
 
+## 为内容作者
+
+- **格式规范**：[docs/content-format.md](./docs/content-format.md) —— 目录结构、front-matter、块/容器/数学语法、错误码、自检命令、投稿 SOP（§14）
+- **示例课**：[example/](./example/README.md) —— 可直接编译通过的最小内容仓样例
+- **社区投稿**：[proposals/](./proposals/README.md) —— 课程稿件投放区，PR + 门禁校验（`npm run validate:proposals`）+ 人审后迁入私有成品仓
+
 ## 目录范围
 
 dexin-content 是**通用层**：
 - `core/` 编译核心（types / compiler / parser / artifact）
 - `domains/lesson/` 内置 lesson 域 parser（其余域由宿主自行注入）
-- `cli/` flow 编排（build / package / validate / check / serve）
+- `cli/` flow 编排（`flowBuild` / `flowPackage` / `flowValidate` / `flowCheck` / `flowServe` 库 API；**CLI 子命令仅有 `build` 与 `help`**，其余 flow 经子路径作库消费）
 - `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
 
 宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
@@ -25,10 +31,6 @@ dexin-content 是**通用层**：
 > 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。
 
 ```bash
-# Gitee 源（当前发布前）
-npm install git+https://gitee.com/cuizhn/dexin-content.git
-
-# 发布到 npm 后
 npm install dexin-content
 ```
 
@@ -39,9 +41,9 @@ npm install dexin-content
 | 子路径 | 暴露内容 |
 |---|---|
 | `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
-| `./core/types` | 类型：`Inline` / `DocumentBlock` / `DocumentContent` / `DocumentIdentity` / `PositiveArtifact` / `Artifact` / `Meta` / `ParseError` / `DomainParser` / `Schema` / `ParseContext` |
+| `./core/types` | 类型：`Inline` 家族（`TextInline` / `BoldInline` / `ItalicInline` / `CodeInline` / `LinkInline` / `FormulaInline`） / `Identity` / `DocumentIdentity` / `StructuredIdentity` / `Meta` / `PositiveArtifact` / `Artifact` / `ParseError` / `ParseContext` / `Schema` / `DomainParser` / `DomainName`（LessonAST 块类型在 `./core/types/lessonAST`） |
 | `./core/compiler` | `compile`、`CompileInput`、`CompileResult`、`DomainParserRegistry` |
-| `./core/discovery` | `buildDocumentIdentity` / `normaliseRel` / `readSourceFile` / `sanitizeSourceText` / `mkLineEndingError` |
+| `./core/discovery` | `buildDocumentIdentity` / `buildStructuredIdentity` / `normaliseRel` / `readSourceFile` / `IdentityKind` / `CollectionConfig` / `SourceFile` |
 | `./core/frontmatter` | `splitFrontmatter` / `parseFrontmatter` / `validateSchema` / `projectMeta` |
 | `./store` | `ArtifactStore` 接口 + `createFsArtifactStore` / `createMemoryArtifactStore` + `ContentIndex` / `IndexEntry` |
 | `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
@@ -60,46 +62,43 @@ npm install dexin-content
 
 ## 快速示例
 
+最简用法是走 CLI（仅编译内置 lesson 域）：
+
+```bash
+# 单文件：AST 打印到 stdout，失败非零退出
+npx dexin-content build example/lessons/getting-started/hello-lesson/minimal.md --domain lesson
+
+# 整树：编译 + 按 manifest 打包 ContentPackage
+npx dexin-content build example --manifest example/content-manifest.json --out /tmp/dexin-out
+```
+
+库 API（宿主自行编排时）用内置 `lessonParser` 经 `DomainParserRegistry` 注入：
+
 ```ts
-import {
-  defineCollection,
-  resolveCollections,
-  createLocalSource,
-  compileCollections,
-} from 'dexin-content/collection'
-import { createFsArtifactStore } from 'dexin-content/store'
-import { ContentQuery } from 'dexin-content/query'
-import { DomainParserRegistry } from 'dexin-content/core/compiler'
-import type {
-  DomainParser,
-  DocumentContent,
-  ParseContext,
-} from 'dexin-content/core/types'
-
-// 1) 注入你的域 parser；parser 决定中性 AST 如何映射到目标 Artifact 内容结构
-const documentParser: DomainParser = {
-  domain: 'document',
-  parse(content: DocumentContent, _ctx: ParseContext) {
-    return { version: 1, blocks: content.blocks as unknown[] }
-  },
-}
-const registry = new DomainParserRegistry()
-registry.register(documentParser)
+import { DomainParserRegistry, compile } from 'dexin-content/core/compiler'
+import { lessonParser } from 'dexin-content/domains/lesson'
+import { buildLessonIdentity } from 'dexin-content/domains/lesson'
 
-// 2) 声明集合 + 编译
-const collections = resolveCollections(
-  [defineCollection({ name: 'legal', source: 'legal', domain: 'document' })],
-  '/path/to/content/root',
+const registry = new DomainParserRegistry()
+registry.register(lessonParser)
+
+const result = compile(
+  {
+    fixture: 'getting-started/hello-lesson/minimal',
+    domain: 'lesson',
+    identity: buildLessonIdentity('minimal', 'getting-started', 'hello-lesson', 'lessons/getting-started/hello-lesson/minimal.md'),
+    source: '---\ntitle: 最小的一节课\norder: 1\n---\n\n## 这就是全部了\n',
+    file: 'lessons/getting-started/hello-lesson/minimal.md',
+  },
+  registry,
 )
-const source = createLocalSource('/path/to/content/root')
-const store = createFsArtifactStore('/path/to/artifact-store')
-await compileCollections(source, collections, registry, store)
 
-// 3) 运行时只读查询（不解析任何 Markdown）
-const query = new ContentQuery(store)
-const entry = await query.byPath('/legal/privacy')
+if (result.kind === 'error') throw result.error
+else console.log(result.artifact.content.blocks)
 ```
 
+`compile()` 永不抛异常，失败以 `{ kind: 'error', error }` 返回。域扩展由宿主注入其它 `DomainParser`。
+
 ## 开发
 
 ```bash

package/docs/content-format.md

@@ -0,0 +1,191 @@
+# 课程内容格式规范（Lesson Markdown）
+
+本仓 `example/` 下有一节按本规范写成的示例课，可直接对照（见 [example/README.md](../example/README.md)）。
+
+适用对象：为 dexinlabs 生态编写数学思维课的作者。课程正文是带 front-matter 的 Markdown，经 `dexin-content` 编译为 LessonAST。本规范以工具链代码实际行为为准（dexin-content v0.3 时代）；文中「代码」路径均相对本仓仓根。
+
+总原则：**白名单之外即报错**。编译器对块级结构 fail-fast——写了不允许的语法会编译失败而不是静默降级，这是为了让作者当场发现问题。
+
+---
+
+## 1. 目录与文件
+
+```text
+<内容仓根>/
+├── content-manifest.json        # taxonomy 骨架（courses/topics/chapters），无逐课条目
+└── lessons/
+    └── <topic>/<chapter>/<slug>.md   # 固定三层，不再递归
+```
+
+- 一课 = 一个 `.md` 文件；`<topic>/<chapter>` 目录名即二者 slug；文件名去 `.md` 即课 slug。
+- 课身份：`id = <topic>/<chapter>/<slug>`，URL path = `/` + id（`domains/lesson/identity.ts`）。
+- 新增一课 = 直接建 md 文件；只有增删 topic/chapter 才改 `content-manifest.json`。
+- `index.md` 被扫描器跳过；`lessons/` 或 topic 目录下直接放的 md 不会被扫到。
+- 文件系统排序是字母序，**不等于展示顺序**——展示顺序由 front-matter `order` 决定（§2）。
+- 编码要求：**UTF-8 无 BOM、LF 行尾**。BOM 会使 front-matter 识别失败（整文件被当成无 front-matter）；含 `\r` 的源在通用 collection 路径直接报 `LINE_ENDING_CONTAMINATION`。
+
+## 2. Front-matter
+
+以第一行精确的 `---` 开始、以单独一行 `---` 结束，中间为合法 YAML（`core/parser/frontmatter.ts`）。
+
+字段模型是 **SCHEMA-FREE**：
+
+- 所有**标量**字段（string / number / boolean）原样进入产物 `meta`；未知字段不报错。
+- **非标高量一律静默丢弃**：数组、对象、null、多行字符串等不会报错，但也拿不到——需要结构化信息时请改用正文容器（§5）。
+
+约定字段（消费方依赖，务必写）：
+
+| 字段    | 类型   | 说明                                                | 缺失后果                                      |
+| ------- | ------ | --------------------------------------------------- | --------------------------------------------- |
+| `title` | string | 课标题                                              | 打包时回退为 slug；包校验（flowValidate）报错 |
+| `order` | number | 章内展示顺序（小→大）                              | 按 0 处理，排序失效                           |
+
+## 3. 标题与分节
+
+| Markdown     | 行为                                                        |
+| ------------ | ----------------------------------------------------------- |
+| `# h1`       | **吸收丢弃**（标题已由 front-matter `title` 提供），不报错、不出现在产物中——因此不要写 |
+| `## h2`      | 映射为 heading level 1，并**新开一个 section**，其后内容归入该节 |
+| `### h3`     | level 2，留在当前 section 内                                 |
+| `#### h4`    | level 3                                                    |
+| `##### h5`   | level 4                                                    |
+| `###### h6`+ | 编译失败 `LESSON_HEADING_DEPTH_UNDEFINED`                   |
+
+第一个 h2 之前的块平铺在顶层（不包 section）。一节课建议以 h2 组织小节。规则见 `domains/lesson/parser.ts`。
+
+## 4. 块级语法
+
+产物 block 类型共 14 类（其中 `image` 暂无可用写法，见下）；作者可用的书写方式如下（`section` 由 h2 自动产生，无书写语法）：
+
+| 写法             | 产物 block                                 | 注意                                                        |
+| ---------------- | ------------------------------------------ | ----------------------------------------------------------- |
+| 普通段落         | `paragraph`                                | —                                                           |
+| `> 引用`         | `quote`                                    | 内部可放段落/列表等子块                                     |
+| 独占一行 `---`   | `divider`                                  | 与上文之间必须留空行，否则会被解析为 setext 标题下划线      |
+| `- 项` / `1. 项` | `list`                                     | **列表项内只允许一个段落**：嵌套列表、代码块等编译失败      |
+| GFM 管道表格     | `table`（headers + rows）                  | 单元格走内联规则（§7）                                      |
+| ` ```lang ` 围栏  | `code`（`lang` 可为空串）                  | —                                                           |
+| 块级数学         | `formula`（`display: true`）               | 见 §6                                                       |
+| `:::hint` 等     | `hint` / `definition` / `example` / `question` | 见 §5                                                   |
+
+**图片暂不可用**：独立图片行与行内图片都会被降级为纯文本（只剩 alt 文字），请不要写 `![...]`，等待渲染侧支持后再开放。
+
+## 5. 容器指令（教学结构的核心）
+
+开栏 `:::名称{key="value"}`，闭栏独占一行 `:::`。容器内部可嵌套任意块（含数学、列表、嵌套段落）。**合法容器只有以下 4 个**（`domains/lesson/blocks.ts`）：
+
+```markdown
+:::hint{level="tip"}
+推荐写法。level 取值：`info` | `tip` | `warning` | `danger` | `reflect`。
+缺失或非法值编译失败（`LESSON_INVALID_HINT_LEVEL`）。
+:::
+
+:::definition{term="一元一次方程"}
+含有一个未知数、且未知数次数为一的整式方程。
+:::
+
+:::example{title="解方程三步法"}
+`title` 可选。
+:::
+
+:::question{hint="先移项，再系数化为 1"}
+题干与作答要求写在容器体内（体即 prompt，可为任意块）。
+除 `hint` 外的属性会被静默丢弃——**不要写 `{title=…}`**。
+:::
+```
+
+`:::note`、`:::tip` 之类一律编译失败（`LESSON_UNKNOWN_CONTAINER`）。
+
+## 6. 数学
+
+- **行内**：`$x + 1 = 2$` → inline `math{latex}`。
+- **块级、两种等价写法**（均产出 `formula{display:true}`）：
+
+```markdown
+单行写法：独占一段、前后空行、段内无其它文字。
+
+$$ax + b = 0 \quad (a \neq 0)$$
+
+多行写法：
+
+$$
+\frac{9}{5}C + 32 = F
+$$
+```
+
+单行 `$$…$$` 若与文字同段则回落为行内数学；单个 `$` 永远不会变块级。
+
+## 7. 内联
+
+可用：`**粗体**`、`*斜体*`、`` `代码` ``、`[文字](https://url)`、行内数学、软/硬换行。
+
+避免（不报错但产出坏味道）：
+
+- 行内 HTML（如 `<b>`）：降级为字面文本；
+- 引用式链接 `[ref][id]`：会变成一个 url 为 `id` 的坏链接——请始终用行内 `[文字](url)`；
+- 图片（§4）。
+
+## 8. 明确禁止（编译失败）
+
+块级原始 HTML（`<div>`…）、脚注（`[^1]` 及定义块）、链接引用定义（`[id]: url`）、列表项内的嵌套块、h6、未知容器、非法 hint level。错误码全表见 §10。
+
+## 9. 产物结构（选读）
+
+每课编译为 Artifact：`{ fixture, domain:'lesson', identity, meta, content:{version:1, blocks} }`。`content.blocks` 即 LessonAST，节点契约见 `core/types/lessonAST.ts`（类型即文档：`Block` 联合 15 成员 = 14 类产物 block + 中性层临时节点 `container`）。
+
+## 10. 校验错误码
+
+| 错误码 | 触发 |
+| --- | --- |
+| `SCHEMA_VALIDATION_FAILED` | front-matter YAML 解析失败 |
+| `LINE_ENDING_CONTAMINATION` | 源文件含 `\r`（collection 路径） |
+| `MDAST_UNSUPPORTED_NODE` | 块级语法越出 §4/§8 白名单；列表项内嵌套块 |
+| `LESSON_HEADING_DEPTH_UNDEFINED` | h6 及更深 |
+| `LESSON_UNKNOWN_CONTAINER` | `:::` 容器名不在 4 类之内 |
+| `LESSON_INVALID_HINT_LEVEL` | hint level 非法 |
+| `COMPILER_NO_DOMAIN_PARSER` | 宿主未注册 lesson 域（工具链集成问题，与作者无关） |
+| `UNKNOWN_ERROR` | 兜底 |
+
+## 11. 自检
+
+写完后在内容仓根逐文件自检（失败 → stderr + **非零退出码**，适合 CI）：
+
+```bash
+npx dexin-content build lessons/<topic>/<chapter>/<slug>.md --domain lesson
+```
+
+省略 `--out` 时产物 AST 打印到 stdout，可肉眼核对结构；`--out <file.json>` 则落盘。
+
+目录整体编译（发布链路，非作者门禁）：
+
+```bash
+npx dexin-content build <内容仓根> --manifest content-manifest.json --out <输出目录>
+```
+
+> ⚠ 已知行为：目录模式对编译失败的文件只打印 `✗ <路径>: <错误码>` 后继续，整体退出码仍为 0。**作者/CI 门禁请以单文件模式为准**。
+
+## 12. 与宿主的关系
+
+本规范只约束「Markdown → LessonAST」这一段。产物如何打包为 ContentPackage、渲染成什么样式、进度数据如何存储，由闭源宿主（dexinlabs）决定，不在本规范范围。
+
+## 13. 已知工具链不一致（待修，不改变本规范效力）
+
+- `core/types/lessonAST.ts` 的常量 `HINT_LEVELS` 缺 `reflect`；实际校验枚举以 `domains/lesson/blocks.ts` 的 `LESSON_HINT_LEVELS`（5 级）为准。
+- 目录模式对失败文件仍 exit 0（§11）计划在后续版本提供失败计数退出。
+
+## 14. 投稿与迁入 SOP
+
+本工具链开源共建的对象是「怎么写课」（规范/示例/校验器），成品课程内容保存在**私有成品仓**，不公开。两条投稿路径：
+
+**A. 社区投稿（proposals/）**
+
+1. **撰写**：按本规范写课，放入本仓 [`proposals/<topic>/<chapter>/<slug>.md`](../proposals/README.md)，本地自检（§11）。
+2. **提 PR**：gitee 网页端编辑 Markdown 亦可；填写 PR 模板的自查与声明项。
+3. **门禁校验**：合并前必须格式全绿。投稿人本地跑 `npm run validate:proposals`（或 `npx dexin-content@latest` 逐文件，见 §11），维护者合并前复跑同一脚本。校验器 = 单文件模式编译，任一失败即非零退出。
+4. **人审**：门禁全绿后由维护者 PR review，审教学正确性与结构合理性（格式问题门禁已拦截）。
+5. **迁入（单向）**：通过后由维护者将稿件迁入私有成品仓——正式 topic/chapter/slug 以成品仓目录与 `content-manifest.json` 骨架为准（可能与投稿时不同，会在 review 中说明）——随后删除本仓 `proposals/` 中的对应文件。下次内容构建时上线。
+6. **授权**：投稿即视为原创并同意被收录评估；内容版权归作者，收录成品仓的具体授权条款在迁入前另行确认（本仓 Apache-2.0 许可证覆盖的是代码与文档，不自动覆盖课程文字内容）。
+
+**B. 签约/受雇作者**
+
+不进公共投稿区：直接对私有成品仓有写权限，以内部 PR 提交与评审。格式校验同样适用（`npx dexin-content@latest build <文件> --domain lesson`）。

package/example/README.md

@@ -0,0 +1,37 @@
+# example/ — 示例课
+
+这是按 [格式规范](../docs/content-format.md) 写成的最小内容仓样例：
+
+```text
+example/
+├── content-manifest.json                  # taxonomy 骨架（courses/topics/chapters）
+└── lessons/
+    └── getting-started/hello-lesson/
+        ├── minimal.md                     # 最小的一节课（order 1）
+        └── syntax-tour.md                 # 全部合法语法速览（order 2）
+```
+
+## 自检
+
+在本仓仓根（或任何安装了 `dexin-content` 的内容仓根）执行：
+
+```bash
+# 整树编译 + 打包（产物写到临时目录，不要写进 example/）
+npx dexin-content build example \
+  --manifest example/content-manifest.json \
+  --out /tmp/dexin-example-out
+
+# 单文件自检（AST 打印到 stdout；失败时非零退出码）
+npx dexin-content build example/lessons/getting-started/hello-lesson/syntax-tour.md --domain lesson
+```
+
+预期输出：
+
+```text
+Build complete: 2 artifacts in ...ms
+Packaged manifest.json: 2 lessons, 0 pages
+```
+
+任何 `✗ <路径>: <错误码>` 行都表示该文件编译失败，含义见 [格式规范 §10](../docs/content-format.md#10-校验错误码)。
+
+> 提示：`--out` 缺省时目录模式会把产物写进 `example/output/`。该目录被 gitignore 与打包排除，但请尽量显式指定临时输出目录，保持示例目录干净。

package/example/content-manifest.json

@@ -0,0 +1,16 @@
+{
+  "courses": [
+    { "slug": "math-thinking", "title": "数学思维", "order": 1 }
+  ],
+  "topics": [
+    { "slug": "getting-started", "title": "上手指南", "order": 1 }
+  ],
+  "chapters": [
+    {
+      "slug": "hello-lesson",
+      "title": "示例课",
+      "order": 1,
+      "topic_slug": "getting-started"
+    }
+  ]
+}

package/example/lessons/getting-started/hello-lesson/minimal.md

@@ -0,0 +1,10 @@
+---
+title: 最小的一节课
+order: 1
+---
+
+## 这就是全部了
+
+一节能编译通过的课，最少只需要：front-matter 里的 `title` 和 `order`，加正文段落。
+
+一个 h2 标题会开启一个小节，下面的内容都归入它。

package/example/lessons/getting-started/hello-lesson/syntax-tour.md

@@ -0,0 +1,74 @@
+---
+title: 语法速览
+order: 2
+---
+
+## 标题与分节
+
+`##` 开一个新小节，`###` 是小节内的次级标题，`####`、`#####` 依次更深。不要用 `#`（会被吸收）也不要用到第六级标题。
+
+### 一个三级标题
+
+它留在当前小节内，不会另起一节。
+
+## 列表
+
+- 无序列表项一
+- 无序列表项二
+
+1. 有序列表项一
+2. 有序列表项二
+
+注意：列表项内只能放一个段落，不要在列表项里再套列表或代码块。
+
+## 表格
+
+| 未知数个数 | 最高次数 | 是否一元一次 |
+| --- | --- | --- |
+| 1 | 1 | 是 |
+| 1 | 2 | 否 |
+| 2 | 1 | 否 |
+
+## 代码围栏
+
+```text
+步骤一：去分母
+步骤二：去括号
+步骤三：移项
+```
+
+## 引用
+
+> 理解优先，而非记忆步骤。
+
+---
+
+## 数学
+
+行内数学直接写在句子中，例如 $ax + b = 0$（其中 $a \neq 0$）。
+
+块级数学推荐独占一行：
+
+$$x = -\frac{b}{a}$$
+
+## 教学容器
+
+四种容器承载教学结构，闭栏统一用独占一行的 `:::`：
+
+:::definition{term="一元一次方程"}
+只含一个未知数、且未知数最高次数为 1 的整式方程。
+:::
+
+:::hint{level="tip"}
+判断是否为一元一次方程，先看化简后未知数的最高次数。
+:::
+
+:::example{title="识别方程"}
+下列哪个是一元一次方程？
+:::
+
+:::question{hint="先移项，再把系数化为 1"}
+解方程 $3x - 6 = 0$。
+:::
+
+hint 的 `level` 合法取值：`info`、`tip`、`warning`、`danger`、`reflect`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexin-content",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Open content toolchain — Markdown → LessonAST/ContentPackage compiler, CLI and validator (dexinlabs ecosystem).",
   "keywords": [
     "markdown",
@@ -33,6 +33,10 @@
     "cli/**/*.ts",
     "domains/**/*.ts",
     "bin/**",
+    "docs/**/*.md",
+    "example/README.md",
+    "example/content-manifest.json",
+    "example/lessons/**/*.md",
     "README.md",
     "LICENSE"
   ],
@@ -58,6 +62,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "runtime:check": "tsx scripts/runtime-check.ts",
+    "validate:proposals": "tsx scripts/validate-proposals.ts",
     "pack": "npm pack --dry-run",
     "build": "tsx cli/build.ts",
     "package": "tsx cli/package.ts"