【实战经验】手搓Presentation Agent SaaS全流程：从Claude Code到部署上线，开发者必看收藏！

1. 从零手搓 Presentation Agent SaaS我踩过的坑与跑通的链路Presentation Agent 是一类把「一句话需求」变成「可演示 HTML 页面」的智能体服务它和传统 PPT 生成最大的区别在于不产出 .pptx 文件而是直接生成可部署、可分享、适配 PC 与移动端的静态网页。适合谁适合想用 Claude Code 快速验证 SaaS 产品、又不想在前端工程上耗太多时间的独立开发者也适合想理解 Agent workflow 编排的后端同学。我这次做的服务拆成三个 AgentOutline Agent 负责生成大纲Search Agent 并行收集每页素材Html Agent 再把内容渲染成演示页面。整条链路从本地调试到线上部署前后断断续续花了一两个月中间最卡脖子的不是模型能力而是 Key 通道不稳定、Token 消耗失控、以及 HTML 布局评估没有标准。下面我把可复制的配置骨架、TaoToken 接入方式、端到端验证动作和常见报错排查一次讲清楚你可以直接照着跑。2. 原问题与场景为什么 Agent 模式省了工程却带来不可控先说清楚这个 SaaS 到底在解决什么。用户输入「帮我做一个介绍 RAG 技术演进的演示」系统要输出一个能直接打开的 HTML 页面包含封面、目录、若干内容页。传统做法是前端写模板、后端填数据工程量大且不灵活Agent 做法是让模型直接生成 HTML工程代码几乎为零。但实测下来Agent 模式的问题非常集中第一信息收集阶段 Token 爆炸。Search Agent 并行跑每个子 Agent 只负责大纲的一部分缺乏全局把控会重复访问同一来源。我记录过一次内容生成消耗约 900K token其中绝大部分是输入 token因为把网页原始内容直接塞进了上下文。第二图片质量不可控。模型自己判断图片链接是否有用或者直接图片搜索结果经常出现水印图、带大量文字的图、尺寸未知导致布局截断。比如 iPhone 产品图被裁掉一半海报图直接 404。第三HTML 生成效果像开盲盒。封面页和目录页只要 prompt 调好基本能看但内容页的对齐、内容分布、配色很难稳定。没有自动化评估标准每次只能靠肉眼调 prompt迭代效率极低。第四开发效率被使用次数限制打断。Claude Code 干到一半触发限额只能等第二天继续上下文还得重新喂。这几点决定了后面所有配置都要围绕「稳定通道 可控上下文 可验证输出」来设计。3. TaoToken 前置统一 Key 与 API 通道配置在动手写 Agent 之前先把模型调用通道固定下来。我试过在多个模型供应商之间来回切最麻烦的是每个 SDK 的 base_url、鉴权头、模型名都不一样Agent 代码里到处是 if-else。后来统一走 TaoToken 的 API 通道OpenAI 兼容格式Claude Code、自研 Agent、脚本调用都能共用一套 Key。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。API 基地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接用于代码里的 base_url。拿 Key 的路径进入控制台 → API Keys → 新建密钥。建议按环境拆 Key本地调试一个、生产一个方便出问题时单独吊销。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。注意Key 只显示一次创建后立刻复制到环境变量或密钥管理服务不要硬编码进仓库。如果你主要用 Claude Code 做开发可以走 Coding Plan长期编码和 Agent 调试更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想先验证模型对话效果用模型对话页快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 专用接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。4. 可复制配置settings.json 与 config.toml 骨架这一节是全文最核心的可操作部分。Claude Code 的配置分两层全局 settings.json 管模型通道项目级 config.toml 管 Agent 运行参数。4.1 Claude Code settings.json 骨架把下面内容放到~/.claude/settings.json重点是 env 段把 base_url 和 key 指向 TaoToken 通道{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-3-5-haiku-20241022 }, permissions: { allow: [ Read, Write, Bash(git:*), Bash(python:*) ] }, includeCoAuthoredBy: false }这里ANTHROPIC_SMALL_FAST_MODEL很关键。Search Agent 里做网页内容摘要、图片相关性判断这类轻任务全部走小模型能显著压 Token 成本。大模型只留给 Outline 和 Html 生成。4.2 Agent 项目 config.toml 骨架项目根目录建config.toml把三个 Agent 的模型、工具、限额集中管理[llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY outline_model claude-sonnet-4-20250514 search_model claude-3-5-haiku-20241022 html_model claude-sonnet-4-20250514 timeout_seconds 120 max_retries 3 [outline_agent] max_tool_calls 5 output_format json_object num_topics 6 [search_agent] max_tool_calls 8 max_fetch_chars 6000 parallel_workers 3 summarize_before_return true [html_agent] max_tool_calls 3 page_width 1280 page_height 720 download_images true image_max_size_kb 300 [tools] search_provider serper fetch_enabled true几个参数是我踩坑后加的max_fetch_chars限制单页抓取长度避免原始 HTML 全量进上下文summarize_before_return让 Search Agent 先用小模型把网页内容按 query 总结再返回download_images打开后图片落地本地既保证有效又能拿到真实尺寸解决布局截断问题。4.3 环境变量与启动export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export SERPER_API_KEY你的serper密钥 python -m presentation_agent.server --config ./config.toml --port 8000启动后本地访问http://127.0.0.1:8000就能看到 Landing Page。5. 验证请求与成功结果端到端跑通一次生成配置写完必须验证通道是否真的通。分三步。第一步验证模型通道。用 curl 直接打 TaoToken 的 APIcurl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [{role: user, content: 用一句话解释什么是 Presentation Agent}] }返回里能看到content数组和正常文本说明 Key 和 base_url 都对。如果返回 401检查 Key 是否带空格返回 404检查 base_url 是否多写了/v1。第二步验证 Outline Agent 输出结构。单独跑大纲生成确认返回的是合法 JSONpython -m presentation_agent.outline \ --topic RAG 技术演进 \ --num-topics 6 \ --output ./outline.json成功时outline.json里每个子主题都有title和points字段能被 Pydantic 模型解析。这一步不通后面 Search 和 Html 全白搭。第三步端到端生成。提交一个完整任务观察日志里三个阶段依次完成python -m presentation_agent.run \ --prompt 做一个介绍 RAG 技术演进的演示 \ --out ./dist/demo.html成功结果dist/demo.html生成浏览器打开能看到封面、目录、内容页图片本地加载不依赖外链PC 和移动端宽度自适应。日志里 Search 阶段每个子 Agent 的 token 消耗应该明显低于未开摘要时的水平。6. 本篇常见错排查6.1 401 Unauthorized 或鉴权失败最常见原因是 Key 复制时带了换行或空格。用echo $TAOTOKEN_API_KEY | wc -c检查长度是否异常。另一个原因是 settings.json 里用了ANTHROPIC_API_KEY而不是ANTHROPIC_AUTH_TOKENClaude Code 走第三方通道时后者才生效。6.2 429 限流或使用次数中断Claude Code 触发限额时任务会中断。解决办法是把长任务拆成小 feature每个 feature 独立提交配合claude-monitor观察用量。生产侧则给 Agent 加max_retries和指数退避避免瞬时打满。6.3 Search Agent Token 消耗过高如果日志显示单次内容生成超过 500K token检查summarize_before_return是否为 true以及max_fetch_chars是否被调大。把网页原始内容直接作为输入是最大的浪费点先用小模型按 query 摘要再返回输入 token 能降一个量级。6.4 HTML 图片截断或 404图片不下载时外链失效和尺寸未知都会导致布局问题。打开download_images true并在 Html Agent 里读取图片真实宽高后再决定放置方式。对带水印或大量文字的图加一层多模态模型做相关性过滤。6.5 内容页布局不对齐、配色土这是 prompt 和评估标准的问题。建议在 Html Agent 的 prompt 里固定一套设计 token主色、辅色、字号阶梯、间距单位并要求所有页面复用同一套 CSS 变量。评估上先做人工 checklist再逐步替换成截图 多模态模型打分否则迭代全靠感觉。6.6 页面内容溢出或过短根因是没限制页面尺寸。在 config.toml 里固定page_width和page_heightHtml Agent 生成时按容器高度裁剪内容超出部分拆到下一页。这是内容和尺寸之间的权衡宁可多一页也不要溢出。7. 语义一致 CTA把链路固定下来再迭代整条链路跑通后你会发现真正决定成败的不是模型多强而是通道稳不稳、上下文管不管得住、输出能不能验证。我的建议是先把 TaoToken 的 Key 和 base_url 固定成项目级配置所有 Agent 共用一套通道再按环境拆 Key 做隔离。接入文档和 API Keys 页面建议收藏换模型或加工具时对照着改。如果你主要在做长期编码和 Agent 调试Coding Plan 比按量调用更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。想快速验证某个模型对 HTML 生成的效果直接用模型对话页试几轮https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。Claude Code 的专用接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后留一个我实际在用的技巧把每次生成的 outline.json、search 摘要、最终 HTML 都落盘存档按任务 ID 建目录。这样出问题时能快速定位是哪个 Agent 的输出跑偏也方便拿历史样本对比 prompt 改动前后的效果。Agent 迭代没有捷径靠的就是可复现的输入输出和稳定的通道。