导入与发布

预检、迁移、预览与受保护发布，每一步都有清晰的状态边界。

交互式导入

inkstack import /path/article.md
inkstack import /path/article.typ --pdf

向导先询问 slug、标题和摘要，再展示迁移清单，最后确认写入。slug 必须是小写连字符形式，且不能与任意来源的已有文章重复。导入默认生成 draft，不会立即公开。

批处理需要提供元数据并明确确认：

inkstack import /path/article.md \
  --slug article-note --description "文章摘要" \
  --tags "工程,笔记" --yes

已有 front matter 可提供标题、日期、摘要等；文章原有语言优先于站点默认语言，private 可见性不会被自动转换成 public。--dry-run 仅生成迁移计划，不写入文章。

默认允许资源根为源文件所在目录。图片在其他子目录时，可明确扩大允许范围：

inkstack import /path/project/notes/article.md \
  --slug article-note --description "文章摘要" \
  --resource-root /path/project --dry-run

本地资源经过 realpath 检查，symlink 指向允许根之外时也会失败。迁移到文章 assets/ 的文件以 SHA-256 内容摘要命名，相同内容去重；引用被重写，不再依赖原始图片目录。

类型	自动处理
Markdown inline / reference 图片	解析 AST，迁移并重写引用，支持编码空格
Markdown cover	迁移本地封面路径
Typst 静态文件函数	迁移图片、读取文件和 bibliography
Typst 本地 import / include	递归迁移 `.typ`，重写依赖；环依赖拒绝
Markdown HTTPS 图片	保留外链并提醒，不自动下载
MDX、Typst 动态资源	不自动执行或猜测，需人工审查

正文上限 5 MiB，每个资源 20 MiB，最多 200 个文件、总量 100 MiB。HTTP 与危险协议拒绝；Typst 文件资源同时拒绝 HTTPS URL。外链图片仍可能失效，离线可用需事先保存到资源根。

非公开内容在生产编译前被隔离，不只是从列表隐藏。unlisted 是“知道链接可访问”，不是鉴权保护。private 是不输出到这个公开站点，不是私有阅读器。

inkstack publish article-note

只发布非 private 草稿。CLI 变更元数据后执行校验和完整构建；失败恢复原元数据。这一步只在本地，不操作 Git，也不让网站上线。

需要创建发布 PR 时：

inkstack publish article-note --submit

--submit 要求当前在 main、gh auth 有效，且没有文章目录之外的未提交修改。它创建发布分支，只提交当前文章及资源，然后 push 并创建 PR。不强推 main、不自动合并，也不绕过 CI。

如果 commit 已成功但网络提交失败，该分支和 commit 会保留以便重试；不要把已经保留的工作重置掉。PR 检查通过并合并后，主 CI 才上传验收过的同一份产物。

查看 GitHub Actions 的部署 job 是否成功，再检查站点内容。build-report.json 的摘要应与构建、浏览器验收、部署上传一致。发布失败时线上保留上一份可用版本。流程实现与回滚边界详见部署与运维。