系统架构

来源适配留在边界，发布规则集中管理，展示始终共享。

分层与职责

模块	拥有的职责	不应承担的职责
Glyphweave 上游包	Typst 发现、编译、清洗和 artifacts	Markdown 处理、博客页面
`@inkstack/content`	元数据、发布规则、路径、标签、仓储纯函数	Astro 页面与主题样式
`@inkstack/theme`	token、布局、TOC、旁注、代码、灯箱、DOM 契约	读取文章目录、判断发布状态
`@inkstack/plugins`	版本化插槽、注册、配置与排序合同	沙箱、远程安装
`@inkstack/cli`	创建、迁移、校验、发布编排	第二套编译器或部署门禁
`apps/blog`	collection 适配、页面、SEO、插件组件与手册	重复定义领域发布规则

内容从哪里进入

Typst post.yaml + index.typ
  → Glyphweave 编译 → content-index / HTML / TOC / manifest / PDF
  → glyphweaveLoader → typst collection
                                      ↘
                                        posts repository
                                      ↗        ↓
Markdown / MDX + front matter                  routes / RSS / tags
  → 安全与发布预检 → glob → markup collection  ↓
                                        shared ArticleLayout
                                               ↓
                                        Astro → Pagefind → 验收

页面只通过 listPosts()、listRoutablePosts()、getPostBySlug()、renderPost() 和 listTags() 访问文章。两个 collection 均通过 Astro render(entry) 得到 Content 与 headings；页面不为不同来源复制一份 UI。

产品手册属于第三个 documentation collection，加载 content/docs/*.md。它有独立元数据和导航，不进入文章仓储、RSS、标签或创作记录。仅产品手册的正文进入文档搜索索引。

领域模型

interface PostMetadata {
  title: string
  slug: string
  description: string
  date: string
  updated?: string
  tags: string[]
  status: 'draft' | 'published' | 'archived'
  visibility: 'public' | 'unlisted' | 'private'
  language: string
  cover?: string | null
  canonicalUrl?: string | null
}

type PostSource =
  | { kind: 'typst'; pdf: boolean }
  | { kind: 'markup'; dialect: 'markdown' | 'mdx' }

来源由扩展名与 loader 决定，不将 source 加入 Markdown front matter。所有来源共享 slug 空间、日期检查、字段校验与发布矩阵。

Node 文件检查单独从 @inkstack/content/node 导出，Markdown AST 政策从 /markdown 导出。浏览器使用领域模型不会隐式引入文件系统。

渲染与共享 DOM

ArticleFrame 统一拥有文章头部、正文容器、三栏布局、目录和旁注。来源适配只在渲染边界处理；产品手册复用相同主题骨架、排版类、代码复制与 TOC，而不伪装成一篇博客文章。

结构	共享契约
页面标题	布局唯一 `h1`，正文 `h2–h4`
代码	`.gw-code-block`、toolbar、copy、pre
表格	`.gw-table-scroll`，局部滚动
数学	`.gw-math--inline` / `.gw-math--block`
图片	`data-lightbox-image`
脚注	标准 doc roles 与 `data-footnote-*`
自定义组件	`.not-prose` 样式隔离

rehypeArticleContract() 是唯一规范化实现。Markdown/MDX 处理 HAST，Typst 在加载边界规范化已清洗的 HTML。转换可重复执行，不依赖隐藏第一个标题的 CSS。

构建与数据一致性

正式顺序为内容校验、无缓存 Typst 编译、原子资源同步、Astro 静态构建、两类 Pagefind 索引、链接与产物验收。build-report.json 记录输入身份、阶段耗时与逐文件摘要。

浏览器测试和部署读取同一份 artifact，并重新核验摘要。这个合同保证“测试的文件就是上传的文件”，不承诺不同机器生成的 PDF 字节一定相同。

本地 Typst 预览在隔离源副本中调用上游构建 API；loader 只消费结果，不启动编译器。更新串行执行，失败保留上一份有效快照。资源同步使用互斥锁、所有权标记、staging 与失败回滚。

怎样扩展

新增展示优先使用插件插槽，新增手册使用维护产品文档。修改内容来源时保留仓储接口与主题 DOM 契约；修改发布规则时集中修改领域层并补齐跨来源矩阵测试。升级 Typst 或 MDX 时重新评估实验接口与信任边界。