# dexin-content

**Repository Path**: cuizhn/dexin-content

## Basic Information

- **Project Name**: dexin-content
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dexin-content

得心实验室的**结构化内容编译与运行时 package**。

负责与具体业务领域无关的通用内容管线：

- **Compile**：将带 frontmatter 的 Markdown 编译成中性 Content AST，再经宿主注入的 `DomainParser` 产出稳定的 PositiveArtifact
- **Store**：Artifact 与索引（ContentIndex）的 FS/Memory 抽象
- **Query**：按 id / URL path / collection / 条件过滤对 Artifact 做只读查询
- **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 编排（`flowBuild` / `flowPackage` / `flowValidate` / `flowCheck` / `flowServe` 库 API；**CLI 子命令仅有 `build` 与 `help`**，其余 flow 经子路径作库消费）
- `browser/` 浏览器宿主入口（`compileLesson`，零 Node API；见 `./compile`）
- `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）

宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。

## 安装

> 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。

```bash
npm install dexin-content
```

## 公开 API 边界

唯一公共 API 边界是 `package.json` 中 `exports` 字段。**只使用下列路径**：

| 子路径 | 暴露内容 |
|---|---|
| `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
| `./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` / `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` |
| `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
| `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
| `./core/markdown` | Markdown → 中性 AST 解析（`parseDocument` 等）；插件组可经 `setMarkdownPluginSet` 注入（浏览器宿主用） |
| `./compile` | **浏览器宿主入口**：`compileLesson(md, {file?}) → CompileResult`（静态导入 unified/remark 插件组，与 CLI 编译语义同源；零 Node API） |
| `./core/types/lessonAST` | LessonAST 类型与常量 |
| `./domains/lesson` | 内置 lesson 域：`lessonParser` / `buildLessonIdentity` / `mapBlocks` |
| `./cli/build` | `flowBuild`（目录发现 → compile → Artifact Store + index.json） |
| `./cli/package` | `flowPackage`（按 manifest 打包 ContentPackage） |
| `./cli/validate` | `flowValidate` |
| `./cli/check` | `flowCheck` |
| `./cli/serve` | `flowServe`（dev preview HTTP 服务） |

任何未列入上表的内部路径均不保证稳定。

## 快速示例

最简用法是走 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 { DomainParserRegistry, compile } from 'dexin-content/core/compiler'
import { lessonParser } from 'dexin-content/domains/lesson'
import { buildLessonIdentity } from 'dexin-content/domains/lesson'

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,
)

if (result.kind === 'error') throw result.error
else console.log(result.artifact.content.blocks)
```

`compile()` 永不抛异常，失败以 `{ kind: 'error', error }` 返回。域扩展由宿主注入其它 `DomainParser`。

## 开发

```bash
# 依赖
npm install

# 类型检查（唯一静态门禁）
npm run typecheck

# 仓内自检测（脚本自建临时 fixture，无需任何本地产物）
npm run runtime:check

# 预发布 tarball 内容检查
npm run pack
```

## License

Apache-2.0 © 得心实验室。详见 [LICENSE](./LICENSE)。