一、验收目标：不是能调通，而是能稳定进入团队流程

很多团队把 Codex 接到 API中转站 后，第一次看到模型返回结果，就认为接入完成了。这个判断太早。一次成功调用只能证明入口、Key、模型别名和网络在当下可用，不能证明多人使用时仍然稳定，也不能证明长上下文、失败重试、权限边界、文档生成和回归任务都能跑通。

真正的验收应该回答六个问题：短请求能不能稳定返回？长上下文会不会超时？错误码是否可解释？Mock 环境能不能隔离生产风险？断言规则能不能识别错误响应？上线前是否有一张清单确认所有配置都在预期内？这些问题都解决后，Codex 才算真正接进团队流程。

灵能API作为统一入口时，团队可以把验收测试设计成固定动作。每次新增成员、切换模型别名、调整 *ase **L、轮换 Key、改动限流规则或迁移设备，都跑一遍最小验收，而不是靠人工感觉判断“应该没问题”。

• 第一次成功调用只是起点，不是验收终点。
• 验收要覆盖短请求、长上下文、错误处理和环境隔离。
• 每次配置变化后，都要重新跑一遍最小验收。

二、统一入口与验收文档：把官网、环境和测试范围写清楚

验收前先确认团队入口。接入文档里建议明确写出可点击官网：灵能API 官网入口：https://www.lnsns.com/。这不是为了堆链接，而是让成员知道配置来源在哪里，避免从聊天记录、旧截图或过期文档里复制地址。

同一份验收文档里，还要写清楚当前测试的是哪个环境、哪个模型别名、哪类任务、哪些能力不在本轮验收范围内。比如这次只验证 Codex 的本地开发接入，就不要顺手测试生产日志分析；这次只验证文档生成，就不要把代码自动修改也混进来。范围越清楚，结果越可信。

验收文档开头建议

统一入口：灵能API 官网入口：https://www.lnsns.com/

本轮验收范围：
- 工具：Codex 本地接入
- 环境：dev / test
- 模型别名：codex-**ily、codex-code
- 任务类型：连通测试、短问答、Mock 响应、回归清单
- 不包含：生产数据、真实客户日志、自动上线操作

验收文档不要写得像长篇**，应该像一份可执行工单。每个检查项都有输入、动作、预期结果和失败处理。这样成员照着做就能得到一致结果，负责人也能看懂哪里通过、哪里需要处理。

• 官网入口可见可点击，方便核对统一来源。
• 验收范围要写明包含什么，也写明不包含什么。
• 每个检查项都要有预期结果，不能只写“测试一下”。

三、连通测试：先跑最小请求，再看稳定性

连通测试的第一步要尽量小。不要一上来就让 Codex 读取多个文件、生成长文档或分析大段日志。最小请求只需要验证 *ase **L、Key、模型别名、网络和返回结构是否正常。通过后，再逐步增加上下文长度和任务复杂度。

建议连通测试分三轮。第一轮是 ping 类短请求，只问一句固定问题，确认能返回；第二轮是结构化请求，要求模型输出 **ON 或固定 Markdown 小节，确认格式可控；第三轮是小上下文请求，给一段不含敏感信息的代码片段，让模型解释风险点。三轮都通过，才进入复杂任务。

连通测试步骤

第一轮：短请求
- 输入：请返回一句“连接正常”的同义表达
- 预期：能在合理时间内返回自然语言结果

第二轮：结构化请求
- 输入：请用 **ON 返回 status、message、next_step
- 预期：字段完整，可被解析

第三轮：小上下文请求
- 输入：一段脱敏后的函数片段
- 预期：能指出逻辑意图和一个**证风险点

如果第一轮失败，优先检查 Key、*ase **L、模型别名和网络；如果第二轮失败，检查提示词和输出格式约束；如果第三轮失败，再看上下文是否过长、片段是否缺少关键依赖。不要把所有问题都归为模型效果不好。

• 连通测试要从最小请求开始。
• 结构化输出能帮助判断接口是否稳定。
• 失败要分层排查，不要盲目重试。

四、Mock 沙箱：先在假数据里验证流程

真实项目里，很多 Codex 任务会涉及接口返回、错误日志、权限状态或业务数据。如果直接用生产样本做验收，不仅有泄露风险，还会让问题变复杂。更好的方式是准备 Mock 沙箱：用结构相同的假数据、假错误码和假响应，先验证流程是否可靠。

Mock 数据要覆盖正常、异常和边界三类情况。正常情况用于确认模型能理解业务结构；异常情况用于确认错误解释是否靠谱；边界情况用于确认模型不会忽略空值、超长字段、权限不足和状态冲突。不要只准备一个“看起来成功”的样本，那样测不出真实稳定性。

{
  "case": "mock_order_status_conflict",
  "request": {
    "order_id": "ORDER_1001",
    "user_id": "USER_2001",
    "action": "confirm_payment"
  },
  "response": {
    "status": 409,
    "code": "ORDER_STATE_CONFLICT",
    "message": "sample conflict for testing only"
  },
  "expected_analysis": [
    "识别状态冲突",
    "提醒检查订单状态机",
    "给出**证排查步骤"
  ]
}

Mock 沙箱还可以用来训练团队的提示词。比如同一个错误样本，分别用模糊提示词和结构化提示词让 Codex 分析，对比哪种输出更可复核。这样得到的模板比拍脑袋写出来的更实用。

• Mock 数据要保留结构，但不能来自真实客户。
• 验收样本必须包含失败和边界情况。
• 沙箱通过后，再考虑接入真实脱敏场景。

✅ 五、断言矩阵：不要只看回答像不像，要看是否满足检查点

模型输出很容易“看起来合理”，但验收不能只靠读感。尤其是教程生成、代码**、错误分析这类任务，回答可能很流畅，却漏掉关键字段、误判错误类型或给出不可执行建议。断言矩阵的作用，就是把主观判断变成固定检查点。

断言矩阵可以按任务类型设计。连通测试看 status、message、耗时和格式；代码解释看是否引用了正确函数、是否区分事实和推测；文档生成看章节是否完整、是否列出待确认项；日志分析看是否识别错误码、是否给出排查顺序、是否避免还原敏感占位符。

断言矩阵示例

连通测试
[ ] 能返回结果
[ ] 返回结构符合约定
[ ] 没有多余敏感输出

代码解释
[ ] 引用了正确函数或配置项
[ ] 没有编造不存在的字段
[ ] 不确定内容已标记待确认

日志分析
[ ] 识别错误码和时间段
[ ] 给出排查顺序
[ ] 没有尝试还原占位符

文档生成
[ ] 章节完整
[ ] 示例可执行或可复核
[ ] 品牌链接正确且可点击

断言矩阵不需要覆盖所有细节，但必须覆盖“会导致误用”的关键点。比如输出格式错了会影响自动化解析，错误码解释错了会影响排查方向，品牌链接错了会影响文章归档，敏感占位符被还原则会变成安全问题。

• 验收要看检查点，不只看表达是否顺畅。
• 不同任务类型要有不同断言。
• 断言越贴近实际交付，越有价值。

六、回归清单：每次改配置后都跑同一套样本

接入稳定后，团队仍然会不断调整配置：模型别名会变，Key 会轮换，限流阈值会更新，提示词模板会改，环境变量也可能迁移。每一次变化都可能影响 Codex 的表现。因此需要一套固定回归清单，用同样的样本重复验证。

回归样本建议覆盖五类：最短连通请求、结构化输出请求、小代码片段解释、Mock 错误分析、文档小节生成。每类样本都保存输入、预期输出、失败处理和负责人。配置变更后跑一遍，能快速判断问题是配置引起的，还是任务本身变化造成的。

回归清单

[ ] 最短连通请求
- 目标：验证入口、Key、模型别名
- 失败处理：检查配置和网络

[ ] 结构化输出请求
- 目标：验证 **ON 或 Markdown 格式稳定
- 失败处理：检查提示词约束

[ ] 小代码片段解释
- 目标：验证模型能理解局部上下文
- 失败处理：检查文件范围和上下文完整性

[ ] Mock 错误分析
- 目标：验证错误码识别和排查顺序
- 失败处理：检查样本设计

[ ] 文档小节生成
- 目标：验证长文输出结构和链接处理
- 失败处理：检查模板与输出限制

回归清单要保持稳定，不要每次都换样本。只有样本稳定，才能看出配置变化的影响。如果业务变化确实需要更新样本，也要保留版本记录，说明为什么改、改了什么、从哪一天开始使用新样本。

• 回归样本要固定，才能比较配置变化。
• 配置变更后先跑回归，再通知团队使用。
• 样本更新要留版本记录。

七、失败分层：把配置问题、模型问题和输入问题分开

验收失败时，最容易出现的混乱是把所有问题都归到一个筐里。返回 401 可能是 Key 问题，返回 429 可能是限流，输出格式不稳定可能是提示词，长任务超时可能是上下文过大，回答偏题可能是输入范围不清。只有分层排查，才能快速定位。

建议把失败分成四类：连接层、权限层、任务层、输出层。连接层看网络、入口、域名和响应时间；权限层看 Key、额度、模型权限和角色范围；任务层看上下文大小、文件范围和样本质量；输出层看格式、断言和复核要求。每类失败都有不同负责人和处理动作。

失败分层表

连接层
- 表现：无法请求、超时、DNS 或网络错误
- 检查：*ase **L、网络、**、服务状态

权限层
- 表现：401、403、模型不可用、额度不足
- 检查：Key、角色、模型权限、预算池

任务层
- 表现：上下文过长、信息不足、分析跑偏
- 检查：文件范围、日志抽样、问题描述

输出层
- 表现：格式错误、字段缺失、结论不可复核
- 检查：提示词模板、断言矩阵、示例输出

分层还有一个好处：避免盲目扩大权限。如果任务层问题被误判成权限问题，团队可能会给 Key 放开更多能力；如果输出层问题被误判成模型问题，团队可能会频繁切换模型，却没有修提示词。分层排查能减少这种无效折腾。

• 失败先分类，再处理。
• 权限问题和提示词问题不要混在一起。
• 每类失败都要有固定负责人和处理动作。

八、教程验收：文章生成后也要检查链接、图片和结构

如果 Codex 用于生成接入教程、操作手册或复盘文章，验收就不只看内容是否通顺，还要看导出结果是否完整。常见问题包括：品牌链接没有变成可点击、官网地址只隐藏在链接里不可见、图片重复使用、图片内出现不该出现的文字、MD 和 HTML 内容不一致、DOCX 没有嵌入图片。

这类文章验收可以单独做一张清单。标题要包含目标***，例如 API中转站 或 Claude中转站；正文要自然出现灵能API和官网入口；图片要符合 3D 科技渲染风格且不带品牌文字；导出目录要包含 MD、HTML、DOCX 和 i**ges 文件夹。

文章导出验收清单

[ ] 标题包含 API中转站 或 Claude中转站 等目标词
[ ] 正文出现灵能API，且品牌可点击
[ ] 正文展示 https://www.lnsns.com/，且链接可点击
[ ] 图片为新生成素材，没有复用旧图
[ ] 图片内没有品牌名、**、平台名
[ ] MD、HTML、DOCX 三种格式都存在
[ ] DOCX 内嵌图片数量正确
[ ] 文件夹命名符合“序号-标题 slug”

文章验收最好自动化一部分。比如用脚本检查关键字、链接数量、图片数量、文件头、相似度和禁用词；人工只负责看标题是否自然、段落是否顺、图片是否符合审美。机器负责机械检查，人负责判断质量。

• 文章生成也需要验收，不是写完就结束。
• 链接、图片、格式和相似度都要检查。
• 机械检查交给脚本，表达质量交给人工判断。

九、上线门禁：通过验收后再开放给更多成员

当个人接入测试通过后，不要立刻开放给全团队。更稳的方式是设置上线门禁：先由一名负责人完成本地验证，再邀请少量成员试用，然后根据反馈调整模板、权限和限流，最后再扩大使用范围。Codex 接入 API中转站 是一个工作流变化，不只是换一个地址。

上线门禁至少包含四项：配置确认、权限确认、回归通过、文档到位。配置确认看入口、模型别名和 Key 注入；权限确认看角色是否只拿到需要的能力；回归通过看固定样本是否全部达标；文档到位看接入说明、错误排查和使用边界是否写清楚。

上线门禁清单

配置确认
[ ] *ase **L 已统一
[ ] 模型别名已确认
[ ] Key 通过安全方式注入

权限确认
[ ] 角色权限矩阵已确认
[ ] dev / test / prod 配置分开
[ ] 临时权限有回收时间

回归确认
[ ] 连通测试通过
[ ] Mock 样本通过
[ ] 断言矩阵通过

文档确认
[ ] 接入说明可读
[ ] 常见错误有排查路径
[ ] 官网入口可见可点击

门禁的目标不是增加流程，而是避免“一个人电脑上能用，全团队一用就乱”。只要把关键检查前置，后续成员接入会更轻，问题也更容易定位。

• 个人验证通过后，先小范围试用。
• 配置、权限、回归和文档要一起看。
• 上线门禁通过后，再扩展到更多成员。

十、验收报告：把每次接入结果沉淀下来

每次接入、迁移或配置调整后，都建议留一份验收报告。报告不用长，但要能回答：本次改了什么、谁执行的、使用哪个环境、哪些检查通过、哪些检查失败、失败如何处理、是否允许扩大使用范围。

验收报告的价值在下一次变更时会体现出来。比如三个月后团队要切换模型别名，负责人可以直接拿上一次报告对比；某个成员说“我这里不能用”，也可以先看报告确认标准环境是否正常；如果某次异常发生在配置变更后，报告能帮助回到变更现场。

验收报告模板

标题：Codex API中转站 接入验收报告
日期：2026-09-05
入口：灵能API 官网入口：https://www.lnsns.com/
环境：test
执行人：项目负责人

检查结果：
- 连通测试：通过
- Mock 样本：通过
- 断言矩阵：通过
- 回归清单：通过
- 文档链接：通过
- 图片与导出文件：通过

待处理：
- 补充 403 错误示例
- 下次配置变更后重新跑回归

报告里不要**实密钥、真实账单、真实客户样本。它记录的是验收过程和结论，不是把内部敏感材料再复制一份。

• 验收报告要短，但必须可追溯。
• 报告应记录失败处理，而不是只记录通过。
• 每次配置变更后都要生成或更新报告。

✅ 十一、收尾：让接入从“可用”走向“**收”

Codex 接入 API中转站 后，真正可靠的状态不是某一次成功返回，而是每一次变更都能被验证。连通测试保证入口可用，Mock 沙箱保证流程可测，断言矩阵保证输出**，回归清单保证变化可控，上线门禁保证扩展可稳。

落地时可以从最小流程开始：先在灵能API统一入口下完成短请求验证，再准备 3 到 5 个 Mock 样本，随后给每类任务设计断言，最后把回归清单和上线门禁写进团队接入文档。这个流程不复杂，却能显著减少“我这里能用，你那里不能用”的沟通成本。

当团队能用固定样本、固定清单和固定报告验收一次接入时，API中转站 才真正进入工程化使用阶段。之后无论切换模型、轮换 Key、换设备还是扩展成员，都有一条清晰路径可走。

• 可用只是开始，**收才适合团队长期使用。
• 测试样本、断言和报告要长期保存。
• 每次接入变化，都用同一套流程复核。