tuner-testkit

发行名 tuner-testkit，导入名 tuner_testkit。给被测系统（SUT）测试仓提供公共运行库与 CLI（db / API / Web UI / 录制 / mock），以及 Cursor/git DNA（rules、skills、hooks）。

业务资产（page/api objects、action words、features）留在各项目仓的 packages/ 与 tests/，不进本包。平台发新版本后，下游用 uv 按需升级，不必再整树拷贝运行库。

标准作业流程

1. 工具域：只装核心 kit（能 tuner-init 即可）

uv tool install 和业务仓 .venv 是两套环境。下游在 tool 域只装默认 wheel，用来拿 tuner-init / tuner-dna；不要在 tool 域打开 [db] / [api] 等 extra。

uv tool install tuner-testkit

入口命令是 tuner-init、tuner-dna 等（tuner-*），没有 tuner-testkit 这个 script。tuner-dump-ddl、tuner-recorder 等依赖 extra 的 CLI，请在业务仓用 uv run … 跑，走该仓 .venv。

2. 初始化测试仓

tuner-init scaffold ../my-sut-tests
cd ../my-sut-tests
uv sync

scaffold 会铺六层目录、写入依赖 tuner-testkit[db,api] 的 pyproject.toml，并执行一次 tuner-dna sync（把 .cursor/、docs/spec/、tools/git-hooks/ 放进项目树）。可在任意目录运行，不必先有测试仓。不要用 tuner-testkit init repo。

uv sync 把 db / api 装进业务仓 .venv，不是 tool 域。已有项目仓则在该仓根目录：

uv add "tuner-testkit[db,api]>=4.0.0"
uv sync

Web UI / 合录等按需再加 extra：

uv add "tuner-testkit[web-ui]"
uv add "tuner-testkit[recorder]"

测 kit 全能力（平台狗食仓等）一次打开全部能力 extra：

uv add "tuner-testkit[all]"
uv sync

3. 开始写业务

在项目仓里写，不要改 site-packages 里的 kit：

代码里 from tuner_testkit.db import … / from tuner_testkit.page_test import …。密钥只放本机 config/env_local.py 或环境变量（TUNER_ENV、TUNER_DB_<ALIAS>_*），不要提交。

录制产物同样写到项目仓 packages/，不会写进 venv。

4. 获取 PyPI 上的更新

平台发新版本后，下游从 PyPI：tuner-testkit 取 wheel，不要再拷本仓源码。tool 域和业务仓 .venv 是两份安装，两边都要升，再铺 DNA。

先看当前装的是哪一版、PyPI 最新是哪一版：

uv tool list                          # tool 域里的 tuner-testkit
cd ../my-sut-tests
uv pip show tuner-testkit             # 业务仓 .venv

发行说明见 docs/changelog/FRAMEWORK.md 与该版本的 docs/changelog/TEMPLATE-*.md。

① tool 域（只升核心 CLI）

uv tool upgrade tuner-testkit

升的是 tuner-init / tuner-dna 所在环境。这里仍然不要加 [db] / [api]。尚未 uv tool install 过则先执行第 1 节。

② 业务仓 .venv（升运行库 + extras）

在项目仓根目录改依赖并同步 lock。保留你原来打开的 extra（普通仓 [db,api]，狗食/全能力仓 [all]）：

# 钉到某一发行版（推荐，和团队 lock 一致）
uv add "tuner-testkit[db,api]==4.3.0"

# 或只抬下限，让解析器选允许范围内的最新
# uv add "tuner-testkit[db,api]>=4.3.0"

uv sync

已经写过 >=4.0.0、只想把 lock 里的 kit 升到 PyPI 最新：

uv lock --upgrade-package tuner-testkit
uv sync

只改 pyproject.toml 里的版本再 uv lock / uv sync 也可以。一个 wheel 不能「只升 web-ui、钉死旧 db」。

③ 同步 DNA 并提交

uv add / uv sync 只更新 site-packages 里的运行库。Cursor 读的是项目树里的 .cursor/、docs/spec/、tools/git-hooks/，必须再铺一层：

tuner-dna sync
tuner-dna check
git add -A && git commit

tuner-dna check 核对项目树 DNA 是否与当前 PATH 上那份 kit 一致。建议先 uv tool upgrade，再 sync，避免 CLI 还是旧包、.venv 已是新包。

其他 AI IDE：DNA 以 Cursor 布局为源，tuner-dna sync --ide claude,agents（或 all）把 skills 渲染到 .claude/skills/ / .agents/skills/、subagents 到 .claude/agents/，并生成 CLAUDE.md（@AGENTS.md + always-on 规则内联 + 路径规则清单）。 tuner-dna targets 列出各目标落点；hooks.json 不跨工具翻译。目录约定随各工具文档变动，用前核对。

新仓第一次仍用第 2 节的 tuner-init scaffold（会写依赖并做一次 tuner-dna sync），不是每次发版都重新 scaffold。

[phone-ui] 为预留空 extra，4.0 未实现。

extras

CLI 与 python -m tuner_testkit.… 等价，例如 tuner-recorder、tuner-page-recorder、tuner-api-recorder、tuner-mock-server。依赖 extra 的命令在业务仓用 uv run tuner-dump-ddl / uv run tuner-recorder。

安全

不得把 token、cookie、Authorization、密码、session 写入仓库（含 capture 与 api_objects）。凭证只允许运行时注入。

本仓库（平台源码）

克隆后在仓库根目录开发 kit 本身：

uv venv
uv sync --extra all

uv sync --extra dev 与 --extra all 等价（dev 只是引用 [all]）。

本仓是平台仓，不是 workspace。dogfood/ 是用 tuner-init scaffold dogfood --no-ai 生成的 workspace 示范 （被测系统 = 平台本身，uv workspace 成员，共用 .venv）：路线图在 dogfood/assets/domain-notes/platform/roadmap.md， 验收活文档在 dogfood/tests/features/。见 dogfood/README.md。

6.0.0 发行说明（一条用例一个文件）见 docs/changelog/TEMPLATE-6.0.0.md；5.3.1 发行说明（已回答提问归档）见 docs/changelog/TEMPLATE-5.3.1.md；5.3.0 发行说明（功能用例集 assets/testcases/）见 docs/changelog/TEMPLATE-5.3.0.md；5.2.0 发行说明（work task / 测试设计 / 证据附件）见 docs/changelog/TEMPLATE-5.2.0.md；5.1.0 发行说明（工作台 / meta stamp / --json）见 docs/changelog/TEMPLATE-5.1.0.md；5.0.0（Plane Job 协议退场、tuner-workspace）见 TEMPLATE-5.0.0.md；4.3.0 见 TEMPLATE-4.3.0.md；3.x → 4.x 迁移见 TEMPLATE-4.0.0.md。平台能力地图见 INDEX.md。