测试、兼容与准确率

不同检查证明不同能力。单元测试通过、受控 MCP 往返成功、真实客户端调用和模型语义正确不能合并为一个“全部场景通过”。

兼容范围

项目	约束 / 验证方式
库运行时	Node.js ≥20.0.0，ESM
持续集成	Linux、Windows、macOS × Node 20.0.0 / 24.x
Codex	支持 CLI 与 Desktop 用户级 stdio MCP 注册，实际宿主分别手动验收
API SDK	可选 openai peer `>=6.49.0 <7`
OpenAI / xAI	显式选择支持任务格式的模型，各路径独立联调
本文档站构建	Node 24.x，独立 website 依赖；不提高库的运行版本

最新执行证据查看 GitHub CI。矩阵定义不等于每次运行成功，应检查你测试的精确提交。

确定性检查

在源码根目录执行：

npm ci
npm run typecheck
npm run lint
npm test
npm run build
npm run smoke:validation
npm run smoke:release
npm run smoke:package
npm run smoke:installation
npm run smoke:maintenance

覆盖输入与输出契约、字段选择、Schema、来源、错误、并发、任务令牌、容量、取消、安装迁移和恢复等逻辑。打包测试安装实际 tarball，再检查公共入口和 MCP 服务。smoke:release 校验发布范围判定与发布证据契约，运行它不会发布包，也不代表已经获得真实验收。

文档维护还会执行以下检查（website 构建需要 Node 24.x）：

npm ci --prefix website
npm run docs:check
npm --prefix website run check:examples
npm run docs:build
npm --prefix website run check:rendered

check:examples 检查站点与根 README 的 JavaScript 示例，包含响应契约检查：完整公共类型与源码对照、文档 JSON 按公共类型校验，并用实际构建包和 MCP SDK 核对四种状态、全局与局部要求、七类动作、显式上下文、业务字段的省略/空值/嵌套、部分字段语义、部分结果与工具封装。可以单独运行 npm --prefix website run check:responses；它同样需要先构建根包。候选使用受控材料，这些检查验证文档与接口一致，不测模型语义准确率。

无密钥 MCP 链路

npm run test:mcp

真实 SDK 客户端连接独立 stdio 服务进程，运行 18 组协议与资源场景，候选是受控数据。该脚本启动 evaluations/mcp-protocol-server.mjs，调用与正式服务共用的 serveIntentMcp，验证工具交接与校验链路；它不启动正式 CLI 文件、不调用真实模型，也不启动真实 Codex 客户端。

检查	入口与覆盖	证据边界
`test:mcp`	专用服务入口，18 组协议与资源场景	受控候选、真实 SDK/stdio；不等于正式 CLI 启动验证
`smoke:package`	安装实际 tarball，启动正式 MCP CLI，检查工具和 prepare/cancel	验证打包与启动，不表示全部模型场景覆盖
`smoke:installation` / `smoke:maintenance`	实际安装、诊断、修复与清理；探查配置指向的入口	不启动真实 Codex CLI/Desktop，不测语义准确率
目标客户端验收	用户实际 Codex CLI 与 Desktop，分别保存工具往返	安装诊断或测试服务不能替代
API 语义验收	明确的 OpenAI、xAI 模型实际生成与独立评审	SDK 受控 fetch 不能替代

真实语义与准确率

当前没有可作为生产指标的真实模型意图识别准确率。 不能用单元测试通过率、结构合法率或助手自评率替代它。

评测材料包括默认 95 条展开用例（89 条语义变体、6 条语言材料）和补充 24 条，总计 119 条；补充中包含原输入重测，不能把每条都称为独立新样本。来源和评审方法见评测工具。

真实评测按以下步骤执行：

冻结输入、Schema、预期语义和 Prompt/源码版本。
OpenAI、xAI 与目标 Codex 路径分别实际生成候选，保存原始工具往返和结果。
独立逐例评审动作、对象、否定、确认、条件、上下文、值和来源；有分歧时人工裁决。
单列未执行与未裁决样本，报告已裁决请求的完整语义通过率、动作 precision/recall、状态和字段正确率。
关键场景重复请求以测稳定性，修复前后的错误都保留。使用新的领域材料作留出集。

输入拒绝不混入意图识别准确率分母；部分字段正确也不能算完整请求通过。计划中的通过率目标是验收门槛，不能写成已测准确率。

独立语义验收逐一记录展开后的 id/variant 键，例如 S-62/omitted 和 S-62/empty 分别评审。使用验收清单时，reviews.semantics.reviewedCaseKeys 必须包含全部 113 个语义键，reviews.multilingual.reviewedCaseKeys 必须包含全部 6 个语言键，不能只记录父用例编号，也不能以重复记录补足数量。

版本发布检查

推送与 package.json 版本完全一致的稳定版本 tag（例如 v1.0.2）会触发 npm 发布。自动流程验证版本匹配、该精确提交在 main 分支上的完整 CI，重新执行类型、代码、单元、MCP、安装维护和打包检查，然后发布带 provenance 的 npm 包，并创建包含安装包与 SHA-256 校验和的 GitHub Release。

后续版本按候选提交与已发布稳定版本的实际差异决定是否需要真实验收，不仅看版本号：

改动范围	发布要求
仅安装维护、站点/README 文档、版本号或发布与确定性测试工具	完整 CI、自动化回归和安装包检查通过即可发布
意图识别、业务提取、API/公开契约、Prompt、语言规则、Bridge/MCP、Codex 模型指引、运行依赖或构建行为	以上检查通过，并提供真实验收清单
未知文件、无法确认已发布基线或无法读取差异	要求真实验收清单

版本元数据豁免仅允许 package.json 的 version，以及 lockfile 顶层与根包的同步 version 变化；依赖、导出、脚本和 Node 约束变化不在此范围。基线必须是仓库中已发布的稳定 GitHub Release，tag 对应版本且位于候选提交的历史中；未发布 tag、草稿和预发布不能作为基线。比较累计差异，并同时检查重命名前的路径。

需要真实验收的版本，先按评测文档完成 OpenAI、xAI、Codex CLI/Desktop、语义、多语言与语言注册表评审，再运行 Review Release Evidence 工作流。清单必须绑定候选提交、版本、完整用例键与发布输入摘要。将工作流 run ID 和清单 SHA-256 填入 npm-release 环境的 RELEASE_EVIDENCE_RUN_ID、RELEASE_EVIDENCE_SHA256；发布流程下载并核验该 artifact。

安装维护与文档发布无需上述验收变量。真实模型和客户端验证仍用于评估实际行为与语义准确率；这类版本已发布不表示已经完成真实验收。

需要保存独立验收记录时，可以手动运行仓库中的 Review Release Evidence 工作流。scripts/check-release.mjs 和从源码执行 npm publish 的 prepublishOnly 仍校验外部验收清单；tag 发布工作流直接发布经过检查的 tarball。

API 评测命令

设置 INTENT_PROVIDER、INTENT_MODEL 和对应 INTENT_OPENAI_KEY 或 INTENT_XAI_KEY 后执行：

npm run evaluate
npm run evaluate -- --languages
npm run evaluate -- --all --repeat 5

这些命令会实际请求模型并产生费用。结果的 semanticReview 初始为 pending，退出码 0 不代表独立语义验收通过。Codex 需要按客户端流程保存真实往返，API runner 不能替代它。

响应耗时

npm run build
node evaluations/benchmark-mcp.mjs

基准记录受控候选下的启动、冷请求和预热后的 MCP 响应，排除了模型生成、网络和客户端调度。真实端到端延迟应在目标模型下记录每阶段耗时、parse 总耗时、p50/p95、修复率和费用，按模型和路径分组。

结果保存

评测产物默认放在项目同级 intent-runtime-results/runs/，每次使用新运行目录。可用 INTENT_EVALUATION_DIR 指定其他项目外路径。报告、真实业务材料、凭据和运行日志不进入源码仓库或公开文档站。

#测试、兼容与准确率

#兼容范围

#确定性检查

#无密钥 MCP 链路

#真实语义与准确率

#版本发布检查

#API 评测命令

#响应耗时

#结果保存