dexin-content 0.2.1 → 0.3.1

package/cli/main.ts

@@ -1,207 +1,197 @@
-#!/usr/bin/env tsx
-// ─────────────────────────────────────────────────────────────
-// dexin-content CLI main entry
-//
-// Modes:
-//   Single-file:  tsx cli/main.ts build <file.md> --domain lesson --out <path>
-//   Directory:    tsx cli/main.ts build <dir> --out <dir> [--manifest <path>]
-// ─────────────────────────────────────────────────────────────
-
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { resolve, isAbsolute, dirname, basename } from 'node:path'
-
-import { DomainParserRegistry, compile } from '../core/compiler/compiler'
-import type { CompileInput } from '../core/compiler/compiler'
-import { lessonParser, buildLessonIdentity } from '../domains/lesson/index'
-import { documentParser, buildDocumentIdentity } from '../domains/document/index'
-import { flowBuild } from './build'
-import { flowPackage } from './package'
-
-type CmdArgs = Record<string, string | boolean>
-
-function parseArgs(argv: string[]): { command: string; args: CmdArgs; positionals: string[] } {
-  const command = argv[0] ?? ''
-  const positionals: string[] = []
-  const args: CmdArgs = {}
-  for (let i = 1; i < argv.length; i++) {
-    const a = argv[i]
-    if (a.startsWith('--')) {
-      const key = a.slice(2)
-      const next = argv[i + 1]
-      if (next && !next.startsWith('--')) {
-        args[key] = next; i++
-      } else {
-        args[key] = true
-      }
-    } else {
-      positionals.push(a)
-    }
-  }
-  return { command, args, positionals }
-}
-
-function printHelp() {
-  console.log(`dexin-content CLI — Independent content compilation tool
-
-Usage:
-  dexin-content <command> [options]   (npm bin; or locally: npx tsx cli/main.ts)
-
-Commands:
-  build    Compile markdown to artifacts
-  help     Show this help
-
-Build modes:
-  Single-file:
-    dexin-content build <file.md> --domain <lesson|document> --out <path>
-
-  Directory tree:
-    dexin-content build <dir> --out <dir> [--manifest <path>] [--lessons <dir>] [--documents <dir>]
-
-Options:
-  --domain <name>      Domain parser (lesson | document). Required for single-file mode.
-  --out <path>         Output path (file for single, directory for batch).
-  --manifest <path>    Content manifest JSON for packaging.
-  --lessons <dir>      Relative path to lessons directory (default: lessons).
-  --documents <dir>   Relative path to documents directory.
-`)
-}
-
-async function runSingleFile(filePath: string, domain: string, outPath?: string) {
-  const absPath = isAbsolute(filePath) ? filePath : resolve(filePath)
-  if (!existsSync(absPath)) {
-    console.error(`Error: file not found: ${absPath}`)
-    process.exit(1)
-  }
-
-  const source = await readFile(absPath, 'utf-8')
-  const relPath = basename(absPath)
-
-  const registry = new DomainParserRegistry()
-  registry.register(lessonParser)
-  registry.register(documentParser)
-
-  let identity: any
-  let fixture: string
-
-  if (domain === 'lesson') {
-    // Try to parse lesson identity from parent directories
-    const parent = dirname(absPath)
-    const grandParent = dirname(parent)
-    const topicSlug = basename(grandParent)
-    const chapterSlug = basename(parent)
-    const lessonSlug = basename(absPath).replace(/\.md$/, '')
-    fixture = `${topicSlug}/${chapterSlug}/${lessonSlug}`
-    identity = buildLessonIdentity(lessonSlug, topicSlug, chapterSlug, relPath)
-  } else if (domain === 'document') {
-    const slug = basename(absPath).replace(/\.md$/, '')
-    fixture = slug
-    identity = buildDocumentIdentity(slug, relPath)
-  } else {
-    console.error(`Error: unknown domain '${domain}'`)
-    process.exit(1)
-  }
-
-  const input: CompileInput = {
-    fixture,
-    domain,
-    identity,
-    source,
-    file: relPath
-  }
-
-  const result = compile(input, registry)
-
-  if (result.kind === 'error') {
-    const err = result.error
-    console.error(`Compile error: ${err?.code ?? 'UNKNOWN'} — ${err?.message ?? err}`)
-    process.exit(1)
-  }
-
-  const output = JSON.stringify(result.artifact, null, 2) + '\n'
-
-  if (outPath) {
-    const absOut = isAbsolute(outPath) ? outPath : resolve(outPath)
-    await mkdir(dirname(absOut), { recursive: true })
-    await writeFile(absOut, output, 'utf-8')
-    console.log(`Compiled ${fixture} → ${absOut}`)
-  } else {
-    process.stdout.write(output)
-  }
-}
-
-async function runDirectory(rootDir: string, args: CmdArgs) {
-  const root = isAbsolute(rootDir) ? rootDir : resolve(rootDir)
-  if (!existsSync(root)) {
-    console.error(`Error: directory not found: ${root}`)
-    process.exit(1)
-  }
-
-  const outDirRaw = args.out as string | undefined
-  const outDir = outDirRaw
-    ? (isAbsolute(outDirRaw) ? outDirRaw : resolve(outDirRaw))
-    : resolve(root, 'output', 'flow')
-
-  const registry = new DomainParserRegistry()
-  registry.register(lessonParser)
-  registry.register(documentParser)
-
-  const lessonResult = await flowBuild({
-    root,
-    lessonsDir: args.lessons as string | undefined,
-    documentDir: args.documents as string | undefined,
-    outDir,
-    domain: {
-      lesson: lessonParser,
-      document: documentParser,
-      buildLessonIdentity
-    }
-  })
-
-  console.log(`Build complete: ${lessonResult.compiled} artifacts in ${lessonResult.durationMs}ms`)
-
-  if (args.manifest) {
-    const manifestPath = isAbsolute(args.manifest as string)
-      ? args.manifest as string
-      : resolve(args.manifest as string)
-    const pkg = await flowPackage({
-      storeDir: outDir,
-      manifestPath,
-      outFile: resolve(outDir, 'manifest.json')
-    })
-    console.log(`Packaged manifest.json: ${pkg.lessons.length} lessons, ${pkg.pages.length} pages`)
-  }
-}
-
-// ── Main ──────────────────────────────────────────────────
-
-const { command, args, positionals } = parseArgs(process.argv.slice(2))
-
-if (command === 'help' || !command) {
-  printHelp()
-  process.exit(0)
-}
-
-if (command === 'build') {
-  const target = positionals[0]
-  if (!target) {
-    console.error('Error: missing target. Usage: build <file.md | directory>')
-    process.exit(1)
-  }
-
-  const isFile = target.endsWith('.md')
-  if (isFile) {
-    const domain = args.domain as string | undefined
-    if (!domain) {
-      console.error('Error: --domain required for single-file mode')
-      process.exit(1)
-    }
-    await runSingleFile(target, domain, args.out as string | undefined)
-  } else {
-    await runDirectory(target, args)
-  }
-} else {
-  console.error(`Unknown command: ${command}`)
-  printHelp()
-  process.exit(1)
-}
+#!/usr/bin/env tsx
+// ─────────────────────────────────────────────────────────────
+// dexin-content CLI main entry
+//
+// Modes:
+//   Single-file:  tsx cli/main.ts build <file.md> --domain lesson --out <path>
+//   Directory:    tsx cli/main.ts build <dir> --out <dir> [--manifest <path>]
+// ─────────────────────────────────────────────────────────────
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, isAbsolute, dirname, basename } from 'node:path'
+
+import { DomainParserRegistry, compile } from '../core/compiler/compiler'
+import type { CompileInput } from '../core/compiler/compiler'
+import { lessonParser, buildLessonIdentity } from '../domains/lesson/index'
+import { flowBuild } from './build'
+import { flowPackage } from './package'
+
+type CmdArgs = Record<string, string | boolean>
+
+function parseArgs(argv: string[]): { command: string; args: CmdArgs; positionals: string[] } {
+  const command = argv[0] ?? ''
+  const positionals: string[] = []
+  const args: CmdArgs = {}
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next && !next.startsWith('--')) {
+        args[key] = next; i++
+      } else {
+        args[key] = true
+      }
+    } else {
+      positionals.push(a)
+    }
+  }
+  return { command, args, positionals }
+}
+
+function printHelp() {
+  console.log(`dexin-content CLI — Independent content compilation tool
+
+Usage:
+  dexin-content <command> [options]   (npm bin; or locally: npx tsx cli/main.ts)
+
+Commands:
+  build    Compile markdown to artifacts
+  help     Show this help
+
+Build modes:
+  Single-file:
+    dexin-content build <file.md> --domain lesson --out <path>
+
+  Directory tree:
+    dexin-content build <dir> --out <dir> [--manifest <path>] [--lessons <dir>]
+
+Options:
+  --domain <name>      Domain parser (lesson). Required for single-file mode.
+  --out <path>         Output path (file for single, directory for batch).
+  --manifest <path>    Content manifest JSON for packaging.
+  --lessons <dir>      Relative path to lessons directory (default: lessons).
+`)
+}
+
+async function runSingleFile(filePath: string, domain: string, outPath?: string) {
+  const absPath = isAbsolute(filePath) ? filePath : resolve(filePath)
+  if (!existsSync(absPath)) {
+    console.error(`Error: file not found: ${absPath}`)
+    process.exit(1)
+  }
+
+  const source = await readFile(absPath, 'utf-8')
+  const relPath = basename(absPath)
+
+  const registry = new DomainParserRegistry()
+  registry.register(lessonParser)
+
+  let identity: any
+  let fixture: string
+
+  if (domain === 'lesson') {
+    // Try to parse lesson identity from parent directories
+    const parent = dirname(absPath)
+    const grandParent = dirname(parent)
+    const topicSlug = basename(grandParent)
+    const chapterSlug = basename(parent)
+    const lessonSlug = basename(absPath).replace(/\.md$/, '')
+    fixture = `${topicSlug}/${chapterSlug}/${lessonSlug}`
+    identity = buildLessonIdentity(lessonSlug, topicSlug, chapterSlug, relPath)
+  } else {
+    console.error(`Error: unknown domain '${domain}'`)
+    process.exit(1)
+  }
+
+  const input: CompileInput = {
+    fixture,
+    domain,
+    identity,
+    source,
+    file: relPath
+  }
+
+  const result = compile(input, registry)
+
+  if (result.kind === 'error') {
+    const err = result.error
+    console.error(`Compile error: ${err?.code ?? 'UNKNOWN'} — ${err?.message ?? err}`)
+    process.exit(1)
+  }
+
+  const output = JSON.stringify(result.artifact, null, 2) + '\n'
+
+  if (outPath) {
+    const absOut = isAbsolute(outPath) ? outPath : resolve(outPath)
+    await mkdir(dirname(absOut), { recursive: true })
+    await writeFile(absOut, output, 'utf-8')
+    console.log(`Compiled ${fixture} → ${absOut}`)
+  } else {
+    process.stdout.write(output)
+  }
+}
+
+async function runDirectory(rootDir: string, args: CmdArgs) {
+  const root = isAbsolute(rootDir) ? rootDir : resolve(rootDir)
+  if (!existsSync(root)) {
+    console.error(`Error: directory not found: ${root}`)
+    process.exit(1)
+  }
+
+  const outDirRaw = args.out as string | undefined
+  const outDir = outDirRaw
+    ? (isAbsolute(outDirRaw) ? outDirRaw : resolve(outDirRaw))
+    : resolve(root, 'output', 'flow')
+
+  const registry = new DomainParserRegistry()
+  registry.register(lessonParser)
+
+  const lessonResult = await flowBuild({
+    root,
+    lessonsDir: args.lessons as string | undefined,
+    outDir,
+    domain: {
+      lesson: lessonParser,
+      buildLessonIdentity
+    }
+  })
+
+  console.log(`Build complete: ${lessonResult.compiled} artifacts in ${lessonResult.durationMs}ms`)
+
+  if (args.manifest) {
+    const manifestPath = isAbsolute(args.manifest as string)
+      ? args.manifest as string
+      : resolve(args.manifest as string)
+    const pkg = await flowPackage({
+      storeDir: outDir,
+      manifestPath,
+      outFile: resolve(outDir, 'manifest.json')
+    })
+    console.log(`Packaged manifest.json: ${pkg.lessons.length} lessons, ${pkg.pages.length} pages`)
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+const { command, args, positionals } = parseArgs(process.argv.slice(2))
+
+if (command === 'help' || !command) {
+  printHelp()
+  process.exit(0)
+}
+
+if (command === 'build') {
+  const target = positionals[0]
+  if (!target) {
+    console.error('Error: missing target. Usage: build <file.md | directory>')
+    process.exit(1)
+  }
+
+  const isFile = target.endsWith('.md')
+  if (isFile) {
+    const domain = args.domain as string | undefined
+    if (!domain) {
+      console.error('Error: --domain required for single-file mode')
+      process.exit(1)
+    }
+    await runSingleFile(target, domain, args.out as string | undefined)
+  } else {
+    await runDirectory(target, args)
+  }
+} else {
+  console.error(`Unknown command: ${command}`)
+  printHelp()
+  process.exit(1)
+}

package/core/artifact/store.ts

@@ -73,7 +73,7 @@ const defaultFsOps: FsOps = {
 
 /**
  * File-system Artifact Store.
- * Layout: <baseDir>/index.json + <baseDir>/lessons/<id>.json
+ * Layout: <baseDir>/index.json + <baseDir>/content/<id>.json
  * Docs are serialised via toCanonicalJSON (2-space, key-lexicographic,
  * LF, trailing newline) to match golden candidate form.
  */
@@ -82,7 +82,7 @@ export function createFsArtifactStore (
   fsOps: FsOps = defaultFsOps
 ): ArtifactStore {
   const idxPath = () => `${baseDir}/index.json`
-  const docPath = (id: string) => `${baseDir}/lessons/${id}.json`
+  const docPath = (id: string) => `${baseDir}/content/${id}.json`
 
   return {
     async writeIndex (index) {

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 与打包排除，但请尽量显式指定临时输出目录，保持示例目录干净。