验证与符合性¶
验证层次¶
每次优化必须验证同一目标是否完成，且对象、权限、质量和成本语义保持正确。工具响应更快不能单独证明 Agent 任务更快；步骤更少不能单独证明结果更好。
flowchart LR
U[目标和可验证结果] --> C[合同与负例测试]
C --> B[真实页面和语义定位]
B --> I[隔离服务与正式客户端]
I --> P[独立安装和制品一致性]
P --> H[目标宿主真实任务]
H --> R[发布后任务与产物核验]各层只证明其实际覆盖范围。协议夹具不能代替真实宿主；本地浏览器不能代替内置浏览器；技术合格不能代替人工质量结论。
本仓库可执行检查¶
以下命令在仓库根目录执行，不访问业务服务：
uv run --no-project --with-requirements requirements-test.txt python scripts/validate-contracts.py
uv run --no-project --with-requirements requirements-test.txt python -m unittest discover -s tests -v
uv run --no-project --with-requirements requirements.txt mkdocs build --strict
uv run --no-project --with-requirements requirements-test.txt playwright install chromium
uv run --no-project --with-requirements requirements-test.txt python scripts/verify-site.py
已有 Chrome 时可通过 AXI_BROWSER_PATH 指定可执行文件，跳过测试浏览器安装。测试依赖只在工具管理的隔离环境中安装。
| 检查 | 实际覆盖 | 证据 |
|---|---|---|
| 合同校验 | 五类 JSON 表示、业务输入、目录引用、动作修订、批量状态与范围 | .dev/contract-validation.json |
| 行为与负例 | 未知字段、版本、恢复缺项、同键并发、进程重启、撤权、CAS、保留期、事务回滚 | unittest 实际结果 |
| 方法包 | 元数据、包内资源、引用动作及分发内容 | 合同检查与构建产物 |
| 文档站 | 项目子路径、全页链接、要求锚点、原文下载、图表、搜索、手机导航、无外部运行时请求 | .dev/site-validation.json |
参考提供方没有真实 OAuth、MCP 传输、MCP App 或 DSH 运行时。上述检查不能证明它们已接入；对应任务需在兼容性矩阵中另行提供证据。
采用方必测矩阵¶
| 维度 | 关键用例 |
|---|---|
| 发现 | 已知目标直接执行；未知入口窄查；索引版本不符；引用工具缺失 |
| 定位 | 同名资源、重复按钮、多候选、分页、对话框、深链和刷新 |
| 上下文 | 切账号、切项目、旧修订、迟到响应、失权与跨范围对象 |
| 执行 | Schema错误、前置缺失、费用不足、冲突与服务错误 |
| 恢复 | 提交应答丢失、超时、取消、原键重放、等待中换账号 |
| 视觉 | 缩放、平移、比较、键盘、窄屏、图像读取失败 |
| 降级 | 无插件、无页面级工具、注册被拒绝、无浏览器和人工接管 |
| 发版 | 索引/Skill/Schema/运行文件一致，干净安装和新会话发现 |
| 安装 | 可信来源、精确版本、依赖失败、启用范围、卸载和干净环境 |
| 身份 | 已有有效连接、拒绝、过期、刷新、缺 scope、错误受众、切账号与撤销 |
| 交互视图 | 初始化、资源版本、结果推送、工具代理、沙箱、失权与无 UI 降级 |
| 升级 | 旧合同与旧 UI、缓存失效、新权限、在途操作、回滚和远端回读 |
| 退役 | 停止新调用、未知操作核对、恢复保留、权限撤销与数据边界 |
| 结果 | 实际产物可读、质量满足、范围完整、费用独立核对 |
| 独立本地 | 阻断非loopback请求、无远程身份，依赖准备后完成声明任务；不推导宿主模型也可离线 |
| 项目与内部状态 | 对话/TTY/机器模式/Web的目录选择与默认、外部编辑、崩溃、索引重建、数据库/文件一致快照 |
| 数据位置与留存 | 无隐式上传、结果取得中断、发布unknown、临时到期、有效引用、恢复与费用保留 |
| 渐进首次使用 | 明确目标直接进入可用结果；默认位置可见可改，不强迫选运行模式；远程能力/云存储/协作按需接入 |
| 原生选择 | 宿主实际能力、少量选项/默认/自由输入、拒绝/取消/不支持、无TTY和迟到响应；选择不扩大授权 |
性能指标¶
| 指标 | 定义 |
|---|---|
| 首次定位成功率 | 第一次定位即获得正确对象与操作的任务比例 |
| 首个可用结果时间 | 从接受目标到第一个满足约定用途的结果；不等同首个响应 |
| 任务完成时间 | 到约定业务结果及必要核验完成的时间 |
| 操作准确率 | 有效且作用于正确对象的操作占全部尝试的比例 |
| 失败与恢复 | 失败、无效参数、重复副作用、重试及人工介入分别计数 |
| 交互成本 | 模型回合、工具调用、HTTP请求、浏览器动作、输入/输出量分开计数 |
| 质量与成本 | 产物缺陷、范围完成度和实际费用分别报告 |
至少区分冷启动与已有连接，固定目标、数据、模型、宿主、网络和制品。比较串行、并行及批量时核对结果一致，记录原始样本与失败；报告中位数和尾部耗时，不能只选最快一轮。没有足够样本时说明局限，不制造统计结论。
每个声明入口分别给预算和结果：CLI启动/帮助/TTY、MCP就绪/发现/调用、本地视图首屏/连续交互/持久保存、远程身份/执行/取得。模型回合、工具调用、HTTP、进程/视图启动、传输字节及SQLite/文件I/O分别记录；并行阶段按关键路径统计。预算未达或未运行如实列出，不能将本仓库静态站构建通过写成本地生产器已达性能目标。
证据记录¶
证据应当记录时间、精确制品摘要、任务范围、环境、执行命令、预期/实际结果、失败和未执行项。源码在测试期间变化使证据不再对应原候选时，必须重新冻结验证或明确标为失效。
日志只保留必要的可观察操作与脱敏数据；不得记录凭据、会话信息或无关用户内容。不要求保存模型私有推理。
符合性声明¶
符合性按任务和环境声明，不按工具数量打分。采用方应当提供以下清单：
- 明确支持的核心任务与产品边界。
- 各任务的发现、定位、执行、观察与恢复合同。
- 对应测试和目标宿主证据。
- 未支持的可选增强及其降级路径。
- 当前发布版本与尚未验证的依赖。
要求编号及来源由机器索引生成；使用采用清单模板逐项关联正例、负例和精确制品。
可以声明“某版本在某宿主完成指定任务验证”；不能仅凭文档、截图、Schema、队列接收或安装成功声称完整符合。性能目标由采用方在测量前确定，并与正确性和质量一起验收。