1. 测试团队的真实困境需求文档到可执行用例之间隔着什么如果你在测试团队待过大概率见过这样的场景产品丢过来一份 40 页的 PDF 需求文档里面夹着流程图、字段表、状态机截图Leader 说「明天出一版用例」。于是你打开 Word一边翻文档一边复制粘贴字段名抄错、边界值漏掉、异常分支想不全最后评审会上被开发一句「这个场景你没覆盖」问住。问题不在于测试同学不专业而在于文档到用例之间是一条断裂的链路PDF 里的表格和图片是给人看的不是给机器读的需求里的业务规则散落在各个章节没有结构化就算你用大模型帮忙也要反复粘贴上下文模型还会中途停下来不告诉你为什么。这篇要解决的就是这条链路。核心思路是三层PyMuPDF4LLMLoader 负责把 PDF 变成模型能吃的 MarkdownDeepAgents 负责编排「需求分析 → 测试点提取 → 用例编写 → 用例评审 → 用例输出」这条流水线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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_KEYsk-你的实际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, encodingutf-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.jsonWindows 是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_urlhttps://taotoken.net/api, api_keyos.getenv(TAOTOKEN_API_KEY), ) resp client.chat.completions.create( modeldeepseek-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、min1、max-1、max、max1 - 状态迁移有状态机的功能必须覆盖所有合法迁移和非法迁移 - 异常场景网络超时、并发冲突、权限不足 ## 输出格式 | 测试点ID | 关联需求ID | 测试类型 | 测试点描述 | 优先级 |用例编写技能skills/case_write.md要把测试点转成可执行步骤# 用例编写技能 ## 输出格式 | 用例ID | 关联测试点 | 前置条件 | 操作步骤 | 预期结果 | 优先级 | ## 质量约束 - 操作步骤必须具体到「点击哪个按钮、输入什么值」 - 预期结果必须可观测禁止「系统正常」这类描述 - 每条用例只验证一个测试点用例评审技能skills/case_review.md是最重要的一个它的作用是对抗性检查主动暴露用例的弱点# 用例评审技能 ## 评审维度 1. 覆盖度是否覆盖所有测试点有无遗漏的异常分支 2. 可执行性步骤是否清晰预期结果是否可验证 3. 冗余度是否存在重复用例 4. 边界完整性边界值是否取全 ## 输出 - 问题清单每条问题标注严重级别阻塞/严重/一般 - 改进建议针对每条问题给出具体修改方案 - 质量评分0-100 分低于 80 分打回重写用例输出技能skills/case_output.md负责把结果写进 Excelimport pandas as pd def export_cases(cases: list[dict], path: str output/cases.xlsx): df pd.DataFrame(cases) df.to_excel(path, indexFalse, engineopenpyxl) return path这五个技能串起来就是一条流水线。DeepAgents 的编排逻辑是读文档 → 调需求分析技能 → 调测试点提取技能 → 调用例编写技能 → 调用例评审技能 → 评审不通过就打回用例编写 → 通过则调输出技能。这个循环就是解决「模型中途停下来」的关键后面第五节细说。5. 端到端验证一次文档到用例的完整动作现在把前面所有东西串起来跑一次。agent.py的主流程import os from dotenv import load_dotenv from openai import OpenAI import pymupdf4llm load_dotenv() client OpenAI(base_urlhttps://taotoken.net/api, api_keyos.getenv(TAOTOKEN_API_KEY)) def load_skill(name: str) - str: with open(fskills/{name}.md, encodingutf-8) as f: return f.read() def call_model(system: str, user: str) - str: resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: system}, {role: user, content: user}, ], temperature0.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_chunksTrue)分页看哪一页出问题。如果是扫描件纯文本解析拿不到内容需要走多模态模型对图片做 OCR把图片单独抽出来喂给支持视觉的模型。报错三模型生成到一半停了。这是最常见的。原因通常是没设终止条件模型自己判断「差不多了」就返回。解决办法就是第五节那个评审循环用评分作为钩子。另外检查max_tokens是否设得太小默认可能只有 1024长用例会被截断建议设到 4096 以上。报错四CC Switch 切换后不生效。切完必须重启 Claude Code 终端settings.json是启动时读的。另外确认 CC Switch 写入的路径和你实际用的路径一致Windows 和 macOS 的.claude目录位置不同。报错五Excel 输出中文乱码。pandas.to_excel默认用 openpyxl中文没问题。如果乱码检查是不是用了to_csv且没指定encodingutf-8-sig。报错六DeepAgents 调用超时。长文档处理时单次请求可能超过 60 秒。给client.chat.completions.create加timeout120或者把文档分块处理每块单独跑流水线再合并。排查顺序建议先单独验证 Key 和通道跑第 3 节那段对话测试再验证解析跑第 2 节那段 PyMuPDF4LLMLoader最后跑完整流水线。分层定位比一上来就跑全流程快得多。7. 把 Key 管好把技能沉淀下来这套系统跑通之后真正值钱的不是代码是skills/目录里那五个文件。它们承载的是你们团队的测试方法论和业务知识模型可以换、通道可以换但技能文件是长期资产。建议每跑一批用例就把评审发现的新问题反哺回技能文件比如发现某类边界值总被漏掉就在测试点提取技能里加一条约束。Key 管理上TaoToken 的统一通道让你只需要维护一个 KeyClaude Code 和 DeepAgents 共用。如果你要长期跑编码和 Agent 任务可以了解下 Coding Plan 的额度方案日常验证模型效果直接用模型对话页面测就行接入过程中遇到配置问题接入文档里有各语言的示例。最后留一个实用技巧把agent.py里的run_pipeline包一层命令行参数支持传入 PDF 路径和输出路径这样你可以在 CI 里定时跑需求文档一更新就自动生成用例草稿人工只需要做评审和补充。测试同学的时间应该花在思考「还有什么场景没覆盖」而不是花在复制粘贴上。
