CI/CD

一、导出功能概述与核心价值 “导出自由”不是营销话术，而是一种技术解耦能力：让你专注写内容（用 Markdown），无需操心最终交付形态。它意味着——无论你今天写的是 API 文档草稿、论文笔记，还是周报初稿，只需一次保存，就能在秒级内生成结构完整、样式精准、语义无损的 PDF 归档版、可嵌入网站的 HTML 版，或供 CLI 工具链消费的纯文本版。 对比手动导出痛点，差异立现： ❌ 复制粘贴到 Word → 标题层级塌陷、代码块变乱码、数学公式消失 ❌ 用 Typora 导出 PDF → 中文缺字、页眉丢失、目录不生成 ❌ 用 Pandoc 转 HTML → 需手写模板、高亮失效、图片路径全错 本教程面向三类高频场景： ✅ 技术文档工程师：为 OpenAPI/SDK 文档构建轻量 CI 导出流水线 ✅ 学术研究者：将 Obsidian/Typora 笔记一键转为可投稿的 PDF + 网页版 ✅ 自动化报告开发者：将日志分析结果（Markdown 模板 + Jinja2 渲染）批量导出多端 我们支持三大目标格式，各司其职： PDF：用于归档、邮件分发、打印 —— 要求字体嵌入、页眉页脚、自动生成目录 HTML：用于 GitHub Pages、内部 Wiki、Notion 嵌入 —— 要求响应式、语法高亮、相对资源可访问 纯文本（.txt）：用于 grep 检索、AI 模型微调输入、Git diff 审阅 —— 要求语义降级（非简单去标签），保留标题层级与列表结构 底层采用轻量原生方案：全程基于 Python 标准库 + 经过生产验证的稳定包（markdown, weasyprint, pygments, markdown-it-py），不依赖 Node.js 或 LaTeX，避免环境臃肿。Pandoc / mdbook 等重型工具留作进阶扩展选项，本文聚焦“最小可行导出系统”。 ...

一、为什么“试用很爽，上线就崩”？——我的三次翻车现场实录 2024.03.12 上午10:23 —— CI流水线突然卡死在 claude-plugin:run 步骤。本地 npx claude-gen --component Header 三秒出结果，CI里却卡住 90 秒后被 Kubernetes OOMKilled。日志最后一行是： [claude-plugin] timeout after 60s waiting for Claude API response (retry=3) 没人想到，我们给插件配的 CLAUDE_TIMEOUT=60 是硬编码进 Dockerfile 的，而 CI 环境 DNS 解析慢了 200ms，叠加重试逻辑直接超时。更讽刺的是，本地 .env 里写了 CLAUDE_TIMEOUT=120，但插件根本没读——它只认环境变量，不读文件。 2024.04.05 下午16:47 —— 生产监控告警：useEffect dependency warning 爆发式增长。React DevTools 里一切正常，但 Sentry 报出上千条： Warning: React has detected a change in the order of Hooks called by MyDataGrid. This will lead to bugs and errors if not fixed. at MyDataGrid (src/components/MyDataGrid.tsx:42:3) at useEffect (react.development.js:2439) 翻代码才发现：Claude生成的组件里，useEffect(() => { loadData(); }, [searchTerm]) 被写成了 useEffect(() => { loadData(); }, []) —— 因为 prompt 里我只写了“加个搜索功能”，没明确说“依赖项必须包含 searchTerm”。开发时 searchTerm 恰好是全局常量，所以没报错；生产环境它是从 URL 参数动态解析的，一变就崩。 ...