企业官网建设流程全解析

1. 测试团队的真实困境：需求文档到可执行用例之间隔着什么

如果你在测试团队待过，大概率见过这样的场景：产品丢过来一份 40 页的 PDF 需求文档，里面夹着流程图、字段表、状态机截图，Leader 说「明天出一版用例」。于是你打开 Word，一边翻文档一边复制粘贴，字段名抄错、边界值漏掉、异常分支想不全，最后评审会上被开发一句「这个场景你没覆盖」问住。

问题不在于测试同学不专业，而在于文档到用例之间是一条断裂的链路：PDF 里的表格和图片是给人看的，不是给机器读的；需求里的业务规则散落在各个章节，没有结构化；就算你用大模型帮忙，也要反复粘贴上下文，模型还会中途停下来不告诉你为什么。

这篇要解决的就是这条链路。核心思路是三层：PyMuPDF4LLMLoader 负责把 PDF 变成模型能吃的 Markdown，DeepAgents 负责编排「需求分析 → 测试点提取 → 用例编写 → 用例评审 → 用例输出」这条流水线，skills 负责把业务知识沉淀成可复用的资产。而 Claude Code 侧通过 TaoToken 统一 Key 接入，让本地编码智能体和 Python 侧的 Agent 共用一套 API 通道，不用在多个平台之间来回切 Key。

适合谁看：测试开发、QA 负责人、想把 AI 落到测试流程里的工程师。前置要求不高，会 Python 基础、能改 JSON 和 TOML 配置文件就行。下面所有配置我都会给可复制的骨架，你替换自己的路径和 Key 就能跑。

2. 前置准备：TaoToken 统一 Key 与项目目录结构

先说清楚 TaoToken 在这里扮演什么角色。它提供的是统一的模型 API 通道，你拿一个 Key，就能在 DeepAgents 的 Python 代码里、在 Claude Code 的终端里、在 CC Switch 的配置里共用同一个入口。好处很直接：不用为每个工具单独申请账号、单独管额度，切换模型时只改一个 base_url 和 model 名。

官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 API Key。API 地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置时直接填。

我建议的项目目录长这样，后面所有路径都基于这个结构：

testcase-agent/ ├── docs/ # 放需求文档 PDF │ └── requirement_v1.pdf ├── parsed/ # PyMuPDF4LLMLoader 解析后的 Markdown ├── skills/ # 业务技能目录 │ ├── requirement_analysis.md │ ├── testpoint_extract.md │ ├── case_write.md │ ├── case_review.md │ └── case_output.md ├── output/ # 生成的用例 Excel ├── agent.py # DeepAgents 主流程 └── .env # 存放 TAOTOKEN_API_KEY

.env里只放一行，别把 Key 写进代码：

TAOTOKEN_API_KEY=sk-你的实际key

注意：.env一定要加进.gitignore。我见过有人把 Key 提交到仓库，第二天额度被刷光。

依赖安装这块，PyMuPDF4LLMLoader 来自pymupdf4llm包，DeepAgents 用官方包，另外需要openai兼容客户端和pandas做 Excel 输出：

pip install pymupdf4llm deepagents openai pandas openpyxl python-dotenv

装完之后先验证一下 PyMuPDF4LLMLoader 能不能正常解析，这一步单独跑，别混在 Agent 里，出问题好定位：

import pymupdf4llm md_text = pymupdf4llm.to_markdown("docs/requirement_v1.pdf") with open("parsed/requirement_v1.md", "w", encoding="utf-8") as f: f.write(md_text) print(f"解析完成，字符数：{len(md_text)}")

跑通的话你会看到parsed/requirement_v1.md，里面的表格会转成 Markdown 表格，图片位置会保留占位。如果文档里有大量扫描件图片，纯文本解析会丢信息，这时候需要走多模态模型补图，后面第五节会讲怎么排查。

3. 可复制配置：settings.json 与 config.toml 骨架

Claude Code 侧的配置分两块：一块是settings.json，管权限、环境变量、模型通道；一块是config.toml，管 CC Switch 的多配置切换。先给settings.json骨架，放在~/.claude/settings.json（Windows 是C:\Users\你的用户名\.claude\settings.json）：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的实际key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-20250514" }, "permissions": { "allow": [ "Read", "Write", "Bash(python:*)", "Bash(pip:*)" ], "deny": [] } }

这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址，ANTHROPIC_AUTH_TOKEN填你的 Key。ANTHROPIC_MODEL是主模型，ANTHROPIC_SMALL_FAST_MODEL用于轻量任务比如文件摘要，能省额度。

然后是 CC Switch 用的config.toml，放在~/.cc-switch/config.toml。CC Switch 的作用是让你在多个配置之间一键切换，比如「日常编码用 Sonnet」「大批量用例生成用 Opus」：

[[profiles]] name = "taotoken-sonnet" base_url = "https://taotoken.net/api" api_key = "sk-你的实际key" model = "claude-sonnet-4-20250514" [[profiles]] name = "taotoken-opus" base_url = "https://taotoken.net/api" api_key = "sk-你的实际key" model = "claude-opus-4-20250514" [active] profile = "taotoken-sonnet"

切换步骤很简单：打开 CC Switch，在配置列表里点你要用的 profile，它会自动改写settings.json里的env字段。切完在终端跑claude回车，输入/status能看到当前生效的 base_url 和 model，确认没切错。

DeepAgents 侧的模型接入用 OpenAI 兼容方式，因为 TaoToken 提供的是标准 API 通道：

import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client = OpenAI( base_url="https://taotoken.net/api", api_key=os.getenv("TAOTOKEN_API_KEY"), ) resp = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": "用一句话说明什么是等价类划分"}], ) print(resp.choices[0].message.content)

这段跑通说明你的 Key 和通道都没问题。DeepAgents 内部调用模型时，把client传进去就行，具体在下一节展开。

4. skills 落地：五个技能文件怎么写才专业

skills 是这套系统的灵魂。它不是简单的提示词，而是带业务知识的可复用资产。参考 Anthropic 官方的 skills 规范，每个技能文件应该包含：技能名、适用场景、输入输出定义、执行步骤、质量约束。下面给五个核心技能的骨架，你可以直接拿去改。

需求分析技能skills/requirement_analysis.md：

# 需求分析技能 ## 适用场景 输入一份需求文档的 Markdown，输出结构化的需求条目。 ## 输入 - 文档 Markdown 全文 ## 输出格式 每条需求包含：需求ID、需求描述、优先级、依赖关系、验收标准 ## 执行步骤 1. 按章节切分文档，识别功能模块边界 2. 提取每个模块下的功能点，合并重复描述 3. 标注需求之间的依赖（如「下单」依赖「库存扣减」） 4. 对每条需求生成可验证的验收标准 ## 质量约束 - 禁止臆造文档中不存在的需求 - 验收标准必须可量化，禁止「体验良好」这类模糊表述 - 需求ID格式：REQ-模块缩写-序号

测试点提取技能skills/testpoint_extract.md的核心是用测试方法论约束模型，不能让它随便列：

# 测试点提取技能 ## 适用场景 输入结构化需求，输出测试点清单。 ## 方法论约束 - 等价类划分：每个输入字段至少分有效/无效两类 - 边界值：数值字段取 min-1、min、min+1、max-1、max、max+1 - 状态迁移：有状态机的功能必须覆盖所有合法迁移和非法迁移 - 异常场景：网络超时、并发冲突、权限不足 ## 输出格式 | 测试点ID | 关联需求ID | 测试类型 | 测试点描述 | 优先级 |

用例编写技能skills/case_write.md要把测试点转成可执行步骤：

# 用例编写技能 ## 输出格式 | 用例ID | 关联测试点 | 前置条件 | 操作步骤 | 预期结果 | 优先级 | ## 质量约束 - 操作步骤必须具体到「点击哪个按钮、输入什么值」 - 预期结果必须可观测，禁止「系统正常」这类描述 - 每条用例只验证一个测试点

用例评审技能skills/case_review.md是最重要的一个，它的作用是对抗性检查，主动暴露用例的弱点：

# 用例评审技能 ## 评审维度 1. 覆盖度：是否覆盖所有测试点？有无遗漏的异常分支？ 2. 可执行性：步骤是否清晰？预期结果是否可验证？ 3. 冗余度：是否存在重复用例？ 4. 边界完整性：边界值是否取全？ ## 输出 - 问题清单：每条问题标注严重级别（阻塞/严重/一般） - 改进建议：针对每条问题给出具体修改方案 - 质量评分：0-100 分，低于 80 分打回重写

用例输出技能skills/case_output.md负责把结果写进 Excel：

import pandas as pd def export_cases(cases: list[dict], path: str = "output/cases.xlsx"): df = pd.DataFrame(cases) df.to_excel(path, index=False, engine="openpyxl") return path

这五个技能串起来就是一条流水线。DeepAgents 的编排逻辑是：读文档 → 调需求分析技能 → 调测试点提取技能 → 调用例编写技能 → 调用例评审技能 → 评审不通过就打回用例编写 → 通过则调输出技能。这个循环就是解决「模型中途停下来」的关键，后面第五节细说。

5. 端到端验证：一次文档到用例的完整动作

现在把前面所有东西串起来跑一次。agent.py的主流程：

import os from dotenv import load_dotenv from openai import OpenAI import pymupdf4llm load_dotenv() client = OpenAI(base_url="https://taotoken.net/api", api_key=os.getenv("TAOTOKEN_API_KEY")) def load_skill(name: str) -> str: with open(f"skills/{name}.md", encoding="utf-8") as f: return f.read() def call_model(system: str, user: str) -> str: resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": system}, {"role": "user", "content": user}, ], temperature=0.2, ) return resp.choices[0].message.content def run_pipeline(pdf_path: str): md = pymupdf4llm.to_markdown(pdf_path) requirements = call_model(load_skill("requirement_analysis"), md) testpoints = call_model(load_skill("testpoint_extract"), requirements) cases = call_model(load_skill("case_write"), testpoints) for attempt in range(3): review = call_model(load_skill("case_review"), cases) if "评分：9" in review or "评分：100" in review: break cases = call_model(load_skill("case_write"), f"{cases}\n\n评审意见：{review}") return cases if __name__ == "__main__": result = run_pipeline("docs/requirement_v1.pdf") print(result[:500])

跑之前确认三件事：.env里的 Key 有效、docs/requirement_v1.pdf存在、skills/下五个文件都在。然后执行：

python agent.py

成功的话你会看到终端打印出用例的 Markdown 表格，前几行类似：

| 用例ID | 关联测试点 | 前置条件 | 操作步骤 | 预期结果 | 优先级 | |--------|-----------|---------|---------|---------|--------| | TC-001 | TP-001 | 用户已登录 | 在搜索框输入有效关键词，点击搜索 | 返回匹配结果列表 | P0 |

如果评审技能打了低分，你会看到它自动重试，最多三轮。这就是解决「模型中途停下来」的核心机制：用钩子函数判断是否完成，而不是让模型自己决定什么时候停。原来的问题是模型生成到一半就返回了，你不知道它是完成了还是被截断了。现在通过评审技能的评分作为终止条件，评分达标才停，不达标就带着评审意见重新生成。

验证模型通道是否正常，可以单独跑一次对话测试，在 Claude Code 里输入/status看配置，或者直接访问模型对话页面确认 Key 有效。

6. 常见报错排查：从 401 到解析乱码

报错一：401 Unauthorized。九成是 Key 填错或者 base_url 写成了带路径的形式。检查settings.json里的ANTHROPIC_BASE_URL是不是https://taotoken.net/api，末尾不要加/v1或斜杠。DeepAgents 侧检查OpenAI(base_url=...)是否一致。

报错二：PyMuPDF4LLMLoader 解析出来是乱码。大概率是 PDF 用了非标准字体编码。先确认文档不是扫描件，用pymupdf4llm.to_markdown(path, page_chunks=True)分页看哪一页出问题。如果是扫描件，纯文本解析拿不到内容，需要走多模态模型对图片做 OCR，把图片单独抽出来喂给支持视觉的模型。

报错三：模型生成到一半停了。这是最常见的。原因通常是没设终止条件，模型自己判断「差不多了」就返回。解决办法就是第五节那个评审循环，用评分作为钩子。另外检查max_tokens是否设得太小，默认可能只有 1024，长用例会被截断，建议设到 4096 以上。

报错四：CC Switch 切换后不生效。切完必须重启 Claude Code 终端，settings.json是启动时读的。另外确认 CC Switch 写入的路径和你实际用的路径一致，Windows 和 macOS 的.claude目录位置不同。

报错五：Excel 输出中文乱码。pandas.to_excel默认用 openpyxl，中文没问题。如果乱码，检查是不是用了to_csv且没指定encoding="utf-8-sig"。

报错六：DeepAgents 调用超时。长文档处理时单次请求可能超过 60 秒。给client.chat.completions.create加timeout=120，或者把文档分块处理，每块单独跑流水线再合并。

排查顺序建议：先单独验证 Key 和通道（跑第 3 节那段对话测试），再验证解析（跑第 2 节那段 PyMuPDF4LLMLoader），最后跑完整流水线。分层定位比一上来就跑全流程快得多。

7. 把 Key 管好，把技能沉淀下来

这套系统跑通之后，真正值钱的不是代码，是skills/目录里那五个文件。它们承载的是你们团队的测试方法论和业务知识，模型可以换、通道可以换，但技能文件是长期资产。建议每跑一批用例，就把评审发现的新问题反哺回技能文件，比如发现某类边界值总被漏掉，就在测试点提取技能里加一条约束。

Key 管理上，TaoToken 的统一通道让你只需要维护一个 Key，Claude Code 和 DeepAgents 共用。如果你要长期跑编码和 Agent 任务，可以了解下 Coding Plan 的额度方案；日常验证模型效果，直接用模型对话页面测就行；接入过程中遇到配置问题，接入文档里有各语言的示例。

最后留一个实用技巧：把agent.py里的run_pipeline包一层命令行参数，支持传入 PDF 路径和输出路径，这样你可以在 CI 里定时跑，需求文档一更新就自动生成用例草稿，人工只需要做评审和补充。测试同学的时间应该花在思考「还有什么场景没覆盖」，而不是花在复制粘贴上。