1. 需求文档拆测试点为什么总在重复劳动一份 Markdown 需求文档丢过来产品说「下周要评审测试用例」你打开文档几十个功能点、上百条业务规则一条条读、一条条拆拆完还要回头核对有没有漏。这个动作本身不难难的是它重复、耗时、还容易漏。尤其是需求文档里写了「验证消息最多 100 个字符」这种边界人眼扫过去很容易只写一条正常流程把边界和异常场景漏掉。我这次要落地的场景很具体用 Codex 的 Skill 能力把一份 Markdown 需求文档自动拆成结构化测试点输出一份可评审的 Markdown 测试文档。核心工具是 Codex 的 Skill 机制加上 TaoToken 提供的统一 Key 接入让 Codex 能稳定调用模型完成需求语义分析。适合谁适合需要快速产出测试用例的研发和测试同学尤其是那种需求文档已经写成 Markdown、但测试用例还靠手工整理的团队。整条链路分三段第一段是 TaoToken 的 Key 和 config.toml 配置让 Codex 能跑起来第二段是 Skill 的目录结构和触发配置让 Codex 知道「遇到需求文档该干什么」第三段是实际跑一遍拿一份需求文档生成测试点再检查结果对不对。下面按这个顺序来每一步都给可复制的配置和命令。2. TaoToken 前置统一 Key 接入 Codex 的 config.toml 骨架Codex 要调用模型得有一个稳定的接入点。TaoToken 提供的是统一 Key一个 Key 可以走多个模型省得你在不同平台之间来回切。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里直接写这个就行。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 后面要写进 Codex 的 config.toml所以别弄丢。如果你还没决定用哪个模型可以先到 https://taotoken.net/models 看一眼模型列表选一个适合做长文本分析的需求文档动辄几千字上下文长度要够。Codex 的配置文件在用户目录下的.codex/config.toml。Windows 是C:\Users\你的用户名\.codex\config.tomlmacOS 和 Linux 是~/.codex/config.toml。如果文件不存在手动建一个。骨架长这样# ~/.codex/config.toml model claude-sonnet-4-5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat这里有几个点要说明。model填你要用的模型名具体支持哪些以模型列表页为准。base_url必须是https://taotoken.net/api不要加斜杠结尾也不要带 UTM。env_key是环境变量名Codex 会从这个环境变量里读 Key而不是把 Key 明文写在 config.toml 里这样更安全。接着设置环境变量。Windows PowerShell$env:TAOTOKEN_API_KEY 你的APIKey想永久生效就写进用户环境变量[Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的APIKey, User)macOS / Linuxexport TAOTOKEN_API_KEY你的APIKey echo export TAOTOKEN_API_KEY你的APIKey ~/.zshrc配完之后在终端跑一下 Codex看能不能正常对话。如果报 401多半是 Key 没读到或者写错了如果报连接超时检查base_url是不是写成了带 UTM 的地址。这一步过了再往下做 Skill。3. Skill 目录结构与触发配置Codex 的 Skill 本质是一个目录里面有一个SKILL.md作为入口加上references/放规则和模板scripts/放辅助脚本。Codex 扫描 Skill 目录时读的是SKILL.md里的描述判断当前任务该不该触发这个 Skill。我们要做的 Skill 叫requirement-testcase-generator目录结构如下requirement-testcase-generator/ ├── SKILL.md ├── references/ │ ├── test-document-template.md │ ├── scenario-types.md │ └── field-definitions.md └── scripts/ ├── extract_document.py ├── check_coverage.py └── render_markdown.pySKILL.md是核心它要写清楚三件事这个 Skill 什么时候用、执行流程是什么、输出格式长什么样。触发配置就藏在「什么时候用」这段描述里。Codex 会根据用户输入和这段描述的匹配度决定是否加载 Skill。所以描述里要出现「需求文档」「测试点」「Markdown」这些关键词用户说「根据这个需求文档生成测试点」时才能命中。SKILL.md的头部用 YAML front matter 写元信息--- name: requirement-testcase-generator description: 读取用户上传的 Markdown 需求文档拆解功能模块生成结构化测试点输出 Markdown 测试文档。当用户提供需求文档并要求生成测试点、测试用例或测试文档时使用。 --- # requirement-testcase-generator ## 使用场景 用户提供一份软件需求文档Markdown 格式要求生成功能测试点或测试文档。 ## 执行流程 1. 读取需求文档提取需求正文。 2. 分析功能模块、用户操作、业务规则、输入条件、输出结果、异常情况。 3. 按功能模块拆分测试点标注场景类型正常/异常/边界/参数校验。 4. 为每个测试点生成预期结果建立需求追踪关系。 5. 检查需求覆盖情况输出未覆盖清单。 6. 渲染为 Markdown 测试文档。 ## 输出格式 参考 references/test-document-template.md。 ## 约束 - 测试点必须基于需求文档生成不得编造需求中不存在的功能。 - 需求未明确描述时标注「需求未明确描述」。references/scenario-types.md定义场景分类标准比如正常场景对应主流程异常场景对应需求中明确写的失败处理边界场景对应上下限值参数校验对应必填项和格式要求。references/field-definitions.md定义测试点字段测试点编号、所属模块、需求来源、场景类型、前置条件、输入条件、操作步骤、预期结果、备注。scripts/里的 Python 脚本负责确定性工作。extract_document.py读文档提取文本check_coverage.py核对需求条目和测试点的对应关系render_markdown.py按模板渲染最终文档。脚本不参与语义判断语义分析交给模型按SKILL.md的规则做。安装 Skill 有两种方式。第一种是直接把整个目录复制到 Codex 的 skills 目录Windows 是C:\Users\你的用户名\.codex\skillsmacOS 是~/.codex/skills。第二种是在 Codex 对话里说「帮我安装这个路径下的 Skill路径你的Skill目录绝对路径」Codex 会自己处理。装完可以问一句「列一下你现在有哪些 Skill」确认requirement-testcase-generator在列表里。4. 可复制配置需求文档示例与生成动作配置好了拿一份需求文档试。这里用一份简化版的网页聊天系统需求文档Markdown 格式存成requirements.md# 网页版聊天系统需求文档 ## 1. 用户管理 ### UR-001 用户注册 用户打开注册页面输入用户名和密码提交注册。注册成功后跳转登录页面。 用户名不能重复。 ### UR-002 用户登录 用户输入用户名和密码提交登录。验证通过进入主页面。 账号已在其他位置登录时不允许重复在线。 ## 2. 好友管理 ### FR-001 搜索用户 用户输入用户名关键字系统按用户名模糊匹配显示匹配用户。 搜索结果不包含当前用户自己已是好友的用户不出现。 ### FR-002 发送好友申请 用户对非好友用户发起好友申请可填写验证消息验证消息最多 100 个字符。 目标用户在线时实时收到申请不在线时保存后续登录可查看。 ## 3. 消息管理 ### MSG-001 查看历史消息 用户选择会话加载该会话历史消息按时间顺序展示。 消息包含消息 ID、发送者、所属会话、消息内容、消息时间。 ### MSG-002 发送消息 用户输入消息内容点击发送。消息保存到服务器关联当前会话。 消息正文最多 2048 个字符。空输入不发送。把这份文档拖进 Codex 对话框或者说清楚文件路径然后发指令请根据这个需求文档将功能点拆分为测试点生成一篇 Markdown 格式的测试文档并告知我生成的文档存放位置。Codex 会加载requirement-testcase-generatorSkill按SKILL.md的流程走。执行过程中你能看到它分步骤先读文档再分析模块再拆测试点最后渲染文档。生成的测试文档大概长这样# 网页版聊天系统功能测试点 ## 1. 文档概述 本文档基于《网页版聊天系统需求文档》生成功能测试点覆盖用户管理、好友管理、消息管理。 ## 2. 功能模块与测试点 | 测试点编号 | 所属模块 | 需求来源 | 场景类型 | 操作步骤 | 预期结果 | 备注 | | --- | --- | --- | --- | --- | --- | --- | | TC-001 | 用户管理 | UR-001 | 正常 | 输入未注册用户名和密码提交注册 | 注册成功跳转登录页面 | | | TC-002 | 用户管理 | UR-001 | 异常 | 输入已注册用户名提交注册 | 需求未明确描述 | 文档仅说明用户名不能重复 | | TC-003 | 用户管理 | UR-002 | 正常 | 输入正确用户名密码提交登录 | 验证通过进入主页面 | | | TC-004 | 用户管理 | UR-002 | 异常 | 账号已在其他位置登录再次提交登录 | 提示登录失败不允许重复在线 | | | TC-005 | 好友管理 | FR-001 | 正常 | 输入关键字搜索 | 显示匹配用户 | | | TC-006 | 好友管理 | FR-001 | 正常 | 搜索包含自己的关键字 | 结果不包含自己 | | | TC-007 | 好友管理 | FR-002 | 边界 | 输入 100 字符验证消息提交申请 | 申请正常提交 | | | TC-008 | 好友管理 | FR-002 | 边界 | 输入超过 100 字符验证消息 | 需求未明确描述 | 文档仅定义上限 | | TC-009 | 消息管理 | MSG-001 | 正常 | 选择会话查看历史消息 | 按时间顺序展示含消息 ID 等字段 | | | TC-010 | 消息管理 | MSG-002 | 正常 | 输入非空消息点击发送 | 消息保存关联当前会话 | | | TC-011 | 消息管理 | MSG-002 | 参数校验 | 空输入框点击发送 | 不发送消息 | | | TC-012 | 消息管理 | MSG-002 | 边界 | 输入 2048 字符消息发送 | 消息可发送并保存 | | | TC-013 | 消息管理 | MSG-002 | 边界 | 输入 2049 字符消息发送 | 需求未明确描述 | 文档仅定义上限 | ## 3. 需求覆盖情况 共 6 条需求已覆盖 6 条未覆盖 0 条。注意 TC-002、TC-008、TC-013 这几条需求文档里只写了「用户名不能重复」「最多 100 个字符」「最多 2048 个字符」没写超限或重复时具体怎么处理。Skill 的处理方式是标注「需求未明确描述」而不是自己编一个「提示用户名已存在」出来。这一点很关键测试点必须能追溯到需求编造出来的测试点评审时会被打回来。5. 验证请求与结果检查清单生成完文档别急着交付按下面这份清单过一遍。这份清单也是我实际跑的时候用来抓问题的。第一检查文档能不能打开、有没有乱码。生成的 Markdown 用 UTF-8 编码如果打开是乱码多半是render_markdown.py写文件时没指定编码。在脚本里写文件要显式加encodingutf-8with open(output_path, w, encodingutf-8) as f: f.write(content)第二检查测试点编号是否连续、有没有重复。编号断了说明中间有测试点被覆盖或丢失重复说明渲染逻辑有问题。第三逐条核对需求来源。每个测试点的「需求来源」字段必须能在需求文档里找到对应条目。如果出现需求文档里根本没有的编号说明模型编造了需求要回去检查SKILL.md的约束描述够不够强。第四检查场景类型覆盖。正常、异常、边界、参数校验四类需求里明确写了异常处理的测试点里要有对应的异常场景。比如 UR-002 写了「账号已在其他位置登录时不允许重复在线」那测试点里就该有一条异常场景对应它。第五检查边界值。需求里出现的数字上限比如 100 字符、2048 字符测试点里应该有「等于上限」和「超过上限」两条。超过上限那条如果需求没写处理方式预期结果应该是「需求未明确描述」而不是编一个提示文案。第六检查需求覆盖情况。文档末尾的覆盖统计要和实际测试点数量对得上。如果统计说覆盖 6 条但实际只找到 5 条需求的测试点说明覆盖检查脚本的逻辑有问题。第七跑一遍check_coverage.py看输出的coverage.json里未覆盖清单是不是空的。如果有未覆盖需求要么是模型漏拆了要么是需求本身不可测试两种情况都要人工确认。6. 常见报错排查报错一Codex 提示找不到 Skill。先确认 Skill 目录放对了位置。Windows 是C:\Users\你的用户名\.codex\skills\requirement-testcase-generator注意是 skills 目录下直接放 Skill 文件夹不是再套一层。放好后重启 Codex或者问一句「列一下你现在有哪些 Skill」确认加载。如果还是没有检查SKILL.md的 front matter 格式name和description必须存在冒号后面要有空格。报错二模型返回 401 或 403。这是 Key 的问题。先确认环境变量TAOTOKEN_API_KEY在当前终端能读到echo $TAOTOKEN_API_KEYWindows PowerShell 用echo $env:TAOTOKEN_API_KEY。如果为空说明环境变量没设上或者设了但没重启终端。如果 Key 有值还是 401去 https://taotoken.net/api-keys 确认 Key 没过期、没被删。另外检查config.toml里的env_key是不是写成了TAOTOKEN_API_KEY大小写要一致。报错三连接超时或 base_url 报错。检查base_url是不是https://taotoken.net/api不要带 UTM 参数不要带结尾斜杠。如果之前复制官网地址时把 UTM 一起复制进去了改成纯 API 地址。报错四生成的文档是空的或者只有标题。多半是extract_document.py没读到文档内容。检查传给脚本的文件路径对不对文档是不是真的 Markdown 格式。如果文档是.docx或.pdfextract_document.py需要额外的解析库比如python-docx或pdfplumber在scripts/requirements.txt里加上依赖再装一遍。报错五测试点里出现需求文档没有的功能。这是约束没生效。回去改SKILL.md把约束写得更硬「测试点必须基于需求文档生成需求文档未描述的功能、操作、规则、输入输出或异常情况不得自行编造。需求描述缺失或模糊时标注『需求未明确描述』。」改完重新跑一遍对比前后输出。报错六覆盖检查说 100% 覆盖但明显有需求没测到。检查check_coverage.py的匹配逻辑。如果它只是简单比对需求编号字符串而测试点的「需求来源」字段格式不统一有的写UR-001有的写UR-001, UR-002匹配就会出错。统一格式或者在脚本里做拆分匹配。7. 把 Skill 用起来从单次生成到长期编码单次生成测试点只是起点。如果你经常要做这件事可以把 Skill 固化下来配合 Coding Plan 长期用。Coding Plan 适合那种需要反复调用模型、做代码生成和 Agent 任务的场景入口在 https://taotoken.net/coding-plan 。配置方式和单次调用一样都是走统一 Key只是用量和计费模式不同。实际用的时候有几个经验可以分享。需求文档的格式越规范生成的测试点质量越高。如果需求文档里功能模块标题清晰、需求条目有编号Skill 拆出来的测试点结构也会更整齐。反过来如果需求文档是一大段散文模型得先帮你梳理结构拆出来的测试点可能就需要多轮调整。另外生成的测试点不是终点是起点。它帮你把「读需求、拆功能、列场景」这个重复动作自动化了但测试点的优先级、执行顺序、和现有用例的合并还是得人来判断。我试过拿生成的测试点和手工整理的对比正常场景和边界场景基本能覆盖异常场景偶尔会漏尤其是需求文档里异常处理写得比较隐晦的时候。所以生成完重点看异常场景那部分人工补一补。如果你想把 Skill 分享给团队把整个目录提交到 Git 仓库就行。团队成员拉下来放到自己的.codex/skills目录配好自己的 TaoToken Key就能用同一套规则生成测试点。规则统一了不同人拆出来的测试点结构也一致评审的时候省事。最后一步验证模型对话是否正常。打开 https://taotoken.net/models 选一个模型在 Codex 里发一句「你好确认一下连接」能正常回复就说明整条链路通了。接入文档在 https://taotoken.net/doc 配置细节和参数说明都在里面遇到问题先翻文档。