651Shadow/web-to-markdown-api

# Web 到 Markdown API 将公开网页或原始 HTML 文档转换为更整洁的 Markdown，适用于 LLM 摄取、RAG pipeline 和归档工作流。 本仓库是一个 **TypeScript/Vercel serverless 参考实现**，重点关注大多数人会忽略的部分：输入验证和更安全的 fetch 行为。 ## 为什么这个项目很有用 - 将杂乱的公开页面转换为更密集的 Markdown，以适应 prompt 和 context window - 接受 `url` 或原始 HTML 输入 - 拒绝明显不安全的 fetch 目标，而不是盲目代理任何内容 - 提供易于检查、测试和扩展的小型代码库 ## 当前功能 - 通过 `url` 进行 fetch 模式 - 通过 `html` 或 `Content-Type: text/html` 直接摄取 HTML - 在 Markdown 转换前进行深度的 HTML 清理 - 提供 `base_url` 时解析相对链接 - 使用 RapidAPI proxy secret 或 admin key 进行请求身份验证 - 轻量级内存内速率限制 ## 安全态势 该 handler 目前会拦截： - localhost 和私有网络目标 - 落在私有地址上的重定向链 - URL 模式下非 HTML 的 fetch 响应 - 超大页面和 HTML payload - 未经身份验证的请求（除非 `ALLOW_UNAUTHENTICATED_DEV=true`） - 通过轻量级内存内速率限制器拦截突发请求者 这使得本仓库可以作为代码合理地发布，但**共享/公开的部署仍应设置真实的 secret 和基于部署的配额**。 ## API 结构 ### GET ``` curl -G 'https://your-api.vercel.app/' \ --data-urlencode 'url=https://example.com/article' \ -H 'x-rapidapi-proxy-secret: YOUR_SECRET' ``` ### POST JSON ``` curl -X POST 'https://your-api.vercel.app/' \ -H 'Content-Type: application/json' \ -H 'x-rapidapi-proxy-secret: YOUR_SECRET' \ -d '{"url":"https://example.com/article"}' ``` ### POST 原始 HTML ``` curl -X POST 'https://your-api.vercel.app/' \ -H 'Content-Type: text/html' \ -H 'x-rapidapi-proxy-secret: YOUR_SECRET' \ --data-binary @page.html ``` ## 本地开发 ``` npm install npm run test npm run typecheck npm run build ``` ## 环境变量 ``` RAPIDAPI_SECRET=replace-me ADMIN_SECRET=replace-me ALLOW_UNAUTHENTICATED_DEV=false RATE_LIMIT_MAX=30 RATE_LIMIT_WINDOW_MS=60000 ``` 使用 `.env.example` 作为本地起点。在共享环境中，请将 `ALLOW_UNAUTHENTICATED_DEV` 置为 `false`。 ## 验证 本仓库已通过以下方式验证： - `npm test` - `npm run typecheck` - `npm run build` ## 当前限制 - 8 秒 fetch 超时 - 免费层级模式下最大内容大小为 2MB - 仅限内存内限流 - fetch 模式仅接受解析为公共地址的 HTTP/HTTPS URL ## 未来改进建议 - 如果流量公开，则将内存内限流替换为基于部署的配额 - 围绕 Vercel handler 添加集成测试 - 仅在配置好生产环境身份验证和配额后，再添加小型的托管 Demo ## 许可证 MIT

标签：LLM数据预处理, Markdown, Serverless, Syscall, TypeScript, Web开发, 安全插件, 格式转换, 自动化攻击