概览
Tide 是一套面向 API 自动化项目的 AI 插件工作流与确定性 Python 执行层。
它尤其适合已有 pytest 接口自动化项目：生成测试前会扫描仓库里的 API client、fixture、命名风格、认证辅助函数、断言习惯和输出目录，让生成代码尽量像团队自己补进去的测试。
为什么用 Tide
| 能力 | 价值 |
|---|
| HAR 转 pytest | 把浏览器录制的业务流程转成可收集、可运行的 pytest 接口测试。 |
| 源码感知生成 | 有后端源码或 API 定义时，利用实现细节增强业务断言。 |
| 适配已有项目 | 自动扫描测试结构、fixture、API client、命名和断言辅助函数。 |
| L1-L5 分层断言 | 从传输成功到状态变更、端到端业务结果逐层规划断言。 |
| 确定性质量门 | 校验 HAR 解析、场景结构、断言覆盖、写入范围和 pytest 输出。 |
| 多宿主支持 | 同一套核心资产同时支持 Claude Code、Codex 和 Cursor。 |
[!IMPORTANT]
Tide 默认只应写入生成测试和 .tide/ 状态文件。除非用户明确授权，不应修改业务代码、共享配置或敏感信息。
支持的宿主
| 宿主 | 用户入口 | Tide 资产 |
|---|
| Claude Code | /using-tide、/tide <har-file> | .claude-plugin/、skills/、agents/、prompts/、scripts/ |
| Codex | $using-tide、$tide <har-file> | .codex-plugin/、codex-skills/、commands/、.agents/plugins/ |
| Cursor | using-tide、tide <har-file> | .cursor/rules/、.cursor/commands/ |
宿主适配文件只负责命令语义和工具语义差异；scripts/ 下的确定性执行层由所有宿主共享。
快速开始
前置要求
- Python
3.12+
uv- 一个 pytest 接口自动化项目
- 从浏览器导出的
.har 文件
Claude Code
claude plugins marketplace add koco-co/tide
claude plugins install tide
然后在目标自动化项目里运行：
/using-tide
/tide ./recordings/api.har
本地插件开发方式：
git clone https://github.com/koco-co/tide.git ~/.claude/plugins/tide
cd ~/.claude/plugins/tide
uv sync
如果你的 Claude Code 环境需要命名空间命令：
/tide:tide ./recordings/api.har --yes --non-interactive
Codex
Tide 内置 Codex 插件元数据和技能：
.codex-plugin/plugin.json
codex-skills/tide/SKILL.md
codex-skills/using-tide/SKILL.md
commands/tide.md
commands/using-tide.md
在 Codex 中安装或重载本地 Tide 插件后，在目标项目中使用：
$using-tide
$tide ./recordings/api.har
Codex 适配层会把已安装插件根目录解析为 TIDE_PLUGIN_DIR，并从插件环境运行 Tide 脚本。目标项目的 Python 只用于执行生成后的 pytest 测试。
Cursor
Tide 内置 Cursor 规则和命令文档：
.cursor/rules/tide-core.mdc
.cursor/rules/tide-init.mdc
.cursor/commands/tide.md
.cursor/commands/using-tide.md
在 Cursor 中打开带有 Tide 规则的目标项目后运行：
using-tide
tide ./recordings/api.har
工作流
Tide 使用四波工作流。AI 负责项目理解与测试设计，脚本负责解析、规范化和验证。
| 波次 | 目标 | 典型产物 |
|---|
| 1. 准备 | 解析 HAR 并扫描项目约定。 | .tide/parsed.json、.tide/project-assets.json、.tide/convention-fingerprint.yaml |
| 2. 理解 | 识别场景、请求链路、风险点和断言机会。 | .tide/scenarios.json、.tide/generation-plan.json |
| 3. 生成 | 复用本地 helper 和风格写入 pytest 文件。 | testcases/ 或配置目录下的生成测试 |
| 4. 验证 | 运行窄范围校验并输出证据报告。 | .tide/final-pytest-output.txt、.tide/final-report.md |
典型运行方式：
# 在 AI 宿主中打开目标 pytest 自动化项目。
/using-tide
/tide ./recordings/metadata-sync.har
# 验证生成测试。
python -m pytest --collect-only testcases -q
python -m pytest testcases -q
断言模型
| 层级 | 含义 | 示例 |
|---|
| L1 | 传输成功 | HTTP 状态码、响应存在、请求完成 |
| L2 | API 契约 | code == 0、必需字段、稳定字段类型 |
| L3 | 业务响应 | 创建名称、同步状态、列表包含目标对象 |
| L4 | 状态变更 | 通过后续查询验证创建、更新、删除效果 |
| L5 | 端到端链路 | 多步骤流程到达最终可观察业务状态 |
[!NOTE]
写操作场景应包含 L4，链路场景应包含 L5。即使格式化和 pytest 收集通过，缺失必需断言层时 Tide 的断言门也必须把该次运行标记为失败。
质量门
| 质量门 | 要求 |
|---|
| 可收集性 | 生成测试通过 pytest --collect-only。 |
| 项目契合度 | import、fixture、API client、类粒度和命名遵循本地 anchor。 |
| 断言覆盖 | 每个接口包含 L1-L3；写操作包含 L4；链路场景包含 L5。 |
| 数据安全 | 不硬编码活动环境 URL、token、webhook secret、凭据或不稳定运行时 ID。 |
| 场景完整性 | scenario_id 唯一，confidence 有证据支撑。 |
| 写入范围 | 生成内容限制在批准的测试目录和 .tide/ 路径内。 |
严格运行时，Tide 会记录真实的最终 pytest 输出：
.tide/final-pytest-output.txt
没有这个文件时，不应把运行总结为成功。
配置
Tide 把目标项目状态和配置存放在 .tide/ 下。
.tide/tide-config.yaml
.tide/repo-profiles.yaml
最小 tide-config.yaml：
project:
type: existing_automation
language: python
test_framework: pytest
