English · 简体中文
把 AI 生成的 spec / ADR / 设计文档渲染成一份新人、同行、资深 reviewer 都能读的 HTML。
三档阅读模式 · 术语弹窗 · 学习检查点 · 多文档档案 · 零依赖 · 单文件 HTML。
🌐 不用安装就能体验：xianfeng92.github.io/xdossier —— 在 HTML 顶部切换「零基础 / 系统化 / 速查」三档阅读模式。
同一份 HTML，三种读者档位。点击查看在线 demo。
多文档视图：内联 SVG 关系图 + 一份项目级索引，把相关 spec / changes / reviews 全部串起来。
你和 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- 全局安装
xdossier：
npm install -g xdossier
# 或在本地 checkout 里：
pnpm link- 在
.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
- 之后 Claude Code 每次写入
docs/specs|changes|reviews/*.md，对应的.html会自动重新生成，父 dossier cover 也会同步刷新。不需要再记命令。
这和带侧边栏的 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） （分享 / 提交）
三层：
- Discover —— 读 frontmatter、识别内容类型、抽 section 结构。
- Enrich —— 生成教学注释（前置 / checkpoint / 类比），用 scaffold（零 token）或 codex / claude provider。
- 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 标签。
Apache-2.0 —— 见 LICENSE。
Thariq Shihipar 在 2026 年 5 月指出：Claude Code 团队已经不再用 Markdown 写内部文档，而是直接写 HTML。Anthropic 给的理由是 —— HTML 自带 Markdown 没有的空间结构（侧栏、折叠、锚点导航）。xdossier 在这个基础上再往前一步：让 HTML 自带教学结构，让同一份文档既能教一个新人，又能简报给一个 senior。