xdossier

把 AI 生成的 spec / ADR / 设计文档渲染成一份新人、同行、资深 reviewer 都能读的 HTML。

三档阅读模式 · 术语弹窗 · 学习检查点 · 多文档档案 · 零依赖 · 单文件 HTML。

🌐 不用安装就能体验：xianfeng92.github.io/xdossier —— 在 HTML 顶部切换「零基础 / 系统化 / 速查」三档阅读模式。

这玩意儿为什么存在

你和 AI agent 一起会生产几十份 markdown：spec、ADR、设计稿、变更说明。每一份都是 800+ 行的密文：

• 新人看不懂上下文
• 老兵不耐烦读完决策摘要前的铺垫
• 任何人想在文档之间跳转、对照都很痛

xdossier 把它们渲染成带教学层的 HTML 档案。读者自己挑档位，同一份单文件 HTML 自适应。

💡 想直观感受差别？ 打开 pedagogy demo 两个标签页，一个切到「零基础」，一个切到「速查」。同一份 HTML，空间结构会变。

你拿到的能力

• 三档阅读模式（零基础 / 系统化 / 速查）—— 在 HTML 里切换，不重渲染、不重构建。术语弹窗、前置知识卡、学习检查点、类比等，会按档位自动出现/隐藏。
• 内容类型自动识别 —— tutorial / concept / reference / course，启发式判断，零 token 成本。
• 单文件 HTML —— 双击即开、可离线、不依赖 CDN。
• 多文档 dossier 视图 —— 根据 frontmatter 里的 implements: / reviews: 或文件名前缀，把相关 spec / changes / reviews 聚成 dossier；输出单个 dossier cover，内含 SVG 关系图，并生成项目级索引。每个成员 HTML 顶部都会带回到所属 dossier 的链接。
• AI enrichment contract —— enrich 产出的 annotations 带 v0.4 合同元数据；contract / render --annotations 会校验 section 引用确实来自源 markdown，避免 AI 注解漂移后悄悄进入 HTML。
• Spec 语义块 —— 风险登记、决策矩阵、原则栅格、scope 边界、术语表、结构图，从 markdown 自动渲染，不用手写 HTML。
• 内联 SVG 图 —— ASCII 层级框图 → 带箭头的真 SVG。
• 抽栏、章节封面、对照卡 —— 让 1000 行 spec 不像砖墙。

快速开始

# npm 安装（推荐）：
npm install -g xdossier
xdossier render docs/specs/my-spec.md

# 或构建一份串起相关 specs、changes、reviews 的 dossier cover：
xdossier cover docs/

# 或本地 clone：
git clone https://github.com/xianfeng92/xdossier.git
cd xdossier
pnpm install
pnpm dev render docs/specs/my-spec.md

打开生成的 .html，点顶部档位按钮就能切。

xdossier cover docs/ 会生成项目级索引 docs/.dossier/out/index.html，以及每个 dossier 的封面 docs/.dossier/out/<dossier-id>/index.html。

AI 注解进入渲染前可以单独验合同：

xdossier enrich docs/specs/my-spec.md --out docs/specs/my-spec.annotations.json
xdossier contract docs/specs/my-spec.md --annotations docs/specs/my-spec.annotations.json
xdossier render docs/specs/my-spec.md --annotations docs/specs/my-spec.annotations.json

Claude Code 自动渲染

1. 全局安装 xdossier：

npm install -g xdossier
# 或在本地 checkout 里：
pnpm link

2. 在 .claude/settings.json 里加 PostToolUse hook：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "/Users/<you>/path/to/xdossier/hooks/post-tool-use.sh \"${tool.fileEdit.file_path}\"" }]
    }]
  }
}

# verify settings.json keys with your Claude Code version

3. 之后 Claude Code 每次写入 docs/specs|changes|reviews/*.md，对应的 .html 会自动重新生成，父 dossier cover 也会同步刷新。不需要再记命令。

FAQ

这和带侧边栏的 Markdown viewer 有什么区别？

两个原因。（1）空间结构不同：关系图、可展开的源文档集合、固定的 dossier 返回横幅，不能简单摊平成一串 markdown block；xdossier 输出的是可以直接发给别人、也可以提交进仓库的真实 HTML。（2）单文件输出：<dossier-id>/index.html 自包含；读者不需要 clone、不需要安装工具、也不需要知道渲染上下文。

为什么不用 LLM 来做 clustering？

Clustering 必须确定、快速，而且能放进 PostToolUse hook 里每次保存都跑；这就排除了 LLM 调用。现在的算法大约 150 行，按信号打分：frontmatter implements: / reviews:（+100/+80）、文件名 stem 匹配（+60）、前缀重叠（+30）、共享子目录（+5）。达到 60 分就归入同一个 dossier。代码在 src/cover/cluster.ts。

为什么输出 HTML，而不是 wiki / Notion / Obsidian export？

xdossier 吃的是你已经有的产物（docs/ 里的 markdown），把它们变成可导航的档案，而不是逼你迁移平台。它是只读输出，不是知识库。适合这些场景：（a）source-of-truth 是提交进 git 的 markdown；（b）你想要离线友好的单文件 HTML；（c）读者里有人并不了解你常用的 wiki 工具。

站在谁的肩膀上

• thariqs/html-effectiveness —— 「AI 输出应该用 HTML 而非 Markdown」的原始论点。
• nexu-io/html-anything —— SKILL.md 协议的先驱实现。

xdossier 在它们的基础上往前走一步：artifact-first（不是 on-demand），pedagogy-first（不只是视觉），multi-document（不只是单文件）。

横向对比

| | xdossier | html-anything | markdown-viewer/skills | Marky / MacMD | |---|---|---|---|---| | 三档阅读模式 | ✅ | ❌ | ❌ | ❌ | | 术语弹窗 / 术语表 | ✅ | ❌ | ❌ | ❌ | | 多文档关系图 | ✅ | ❌ | ❌ | ❌ | | 单文件离线 HTML | ✅ | ✅ | partial | partial | | Spec/ADR 语义块 | ✅ | ❌ | partial | ❌ | | 视觉产物（slides/海报/社媒） | ❌ | ✅ | partial | ❌ | | Markdown 实时预览 | ❌ | ❌ | ❌ | ✅ |

我们不做通用「AI 转 HTML」工具。只把一件事做好：让非高阶工程师也能读懂的技术文档档案。

工作流

markdown.md  →  enrich（启发式 + 可选 LLM）  →  render-spec skill  →  单文件 HTML
       （你的 AI 写）           （annotations.json）        （模板 + CSS）          （分享 / 提交）

三层：

1. Discover —— 读 frontmatter、识别内容类型、抽 section 结构。
2. Enrich —— 生成教学注释（前置 / checkpoint / 类比），用 scaffold（零 token）或 codex / claude provider。
3. Render —— 输出单文件 HTML，CSS / JS 全内联，零外部资源。

使用场景

• AI 写的 spec → 设计感够好的 HTML 给团队。
• 设计文档档案：实习生周一能读懂，principal 周二能 5 分钟扫完。
• 多版本简历档案：5 版简历 + 改动注释，按读者档位呈现给不同 HR。
• 开源项目文档，不需要 markdown 预览插件就能体面阅读。

进度

| 组件 | 状态 | |---|---| | 单文档渲染（MVP-0） | ✅ 已实现 | | Pedagogy 层（P0/P1/P2） | ✅ 已实现 | | 多文档 dossier 视图（MVP-1） | ✅ 已实现 | | MCP server（MVP-2） | 📝 已 spec | | Claude Code session adapter | 📝 已 spec |

贡献

欢迎新 skill、新 pedagogy 元素、新渲染目标。详见 CONTRIBUTING.md。

想找个入手任务？看一眼 good first issue 标签。

License

Apache-2.0 —— 见 LICENSE。

灵感来源

Thariq Shihipar 在 2026 年 5 月指出：Claude Code 团队已经不再用 Markdown 写内部文档，而是直接写 HTML。Anthropic 给的理由是 —— HTML 自带 Markdown 没有的空间结构（侧栏、折叠、锚点导航）。xdossier 在这个基础上再往前一步：让 HTML 自带教学结构，让同一份文档既能教一个新人，又能简报给一个 senior。