E2E Case Lifecycle 是用于 z-code 仓库的端到端测试生命周期技能，需在仓库根目录下工作。它面向对话流程、SSH、provider 设置、UI 工作流、文件系统行为、远程运行时、认证与配置等产品面，不绑定单一领域。
一、前置阅读 在编写或迁移 E2E spec 前，需先阅读对应领域的用例目录、覆盖率矩阵与工作流文档。对话会话相关默认来源为 docs/conversation-session-case-catalog.md、docs/testing/conversation-session-e2e-coverage-matrix.md、docs/testing/conversation-session-e2e-development-workflow.md。若涉及 SSH、provider 设置、auth/config、fork、goal、fault、模型切换或远程/可回放语义，还需阅读 docs/testing/ 下对应的矩阵或 spec 文档。
二、覆盖率规划 对开放式功能变更或“应覆盖什么”的请求，先用 feature-boundary-planner，待目录/矩阵中产生已接受用例后再回到本技能。被问及测什么时：从功能规格、目录和矩阵提取状态维度；枚举组合并与用户一起剔除无效或重复用例；在写代码前把 accepted/undefined/pruned 决策写入目录或矩阵文档；仅为已接受的语义生成 E2E 代码，行为未定义时停在提问或文档更新阶段。仅路径经过某状态不算覆盖，每个覆盖用例需具备 setup、action、assertion。矩阵行只有在引用了该用例实际通过运行的产物（如 packages/desktop/.e2e-artifacts/desktop-e2e-<run-id>）时才可标为 covered；新断言从未运行不算覆盖，若被前置步骤或已知基线失败阻断，应保持 partial/failing 并写明 blocked by <baseline id 或症状>，列出未运行的断言，待有通过运行后再更新。
三、手工审查用例 新候选用例放在领域 manual-review/pending/ 目录下，对话会话为 packages/desktop/test/e2e/conversation-session/manual-review/pending/。在用户提示和 provider matcher 中使用稳定的 E2E_* 标记，优先复用 packages/desktop/test/e2e/helpers/ 下的辅助函数；高/中优先级已完成历史设置使用 buildReadonlyToolPrompt(...)，除非时序因素使工具历史适得其反。手工/捕获运行命令： ZCODE_E2E_MANUAL_REVIEW=1 pnpm --filter @zcode/desktop test:e2e -- --spec './test/e2e/conversation-session/manual-review/pending/<case>.test.ts' 手工/捕获产物是审查证据，不是最终测试契约。若反馈复现运行需要视频产物，应在应用内部录制 Electron 窗口，而非 OS 录屏：从 ../../../helpers/electron-window-recorder.js 导入 startElectronWindowRecording 和 ELECTRON_WINDOW_RECORDING_CAPTURE_MODE，在用户可见路径前开始录制，在 finally 中停止，并把 video_capture_mode: ELECTRON_WINDOW_RECORDING_CAPTURE_MODE 写入反馈 manifest；不要把 macOS Screen Recording、screencapture、QuickTime 或仅截图视频作为常规证据路径。
四、晋升 用户确认人工审查后，先做晋升试运行： pnpm --filter @zcode/desktop e2e:promote -- --spec ./test/e2e/conversation-session/manual-review/pending/<case>.test.ts --reviewed 再执行应用： pnpm --filter @zcode/desktop e2e:promote -- --spec ./test/e2e/conversation-session/manual-review/pending/<case>.test.ts --reviewed --apply 该工具会移动 spec、修正常见 helper 导入、创建 fixture/manifest 脚手架并更新覆盖率矩阵路径，但不决定请求语义。--apply 时，晋升将这些写入作为一个文件系统事务，并针对暂定正式状态运行 pnpm audit:conversation-session-coverage；仅当审计通过才保留晋升，审计失败或执行错误会恢复 pending spec、fixtures、manifest 与覆盖率矩阵并以非零退出。因此应在 spec 仍为 pending 时完成并校验规范 fixture 契约，不要依赖晋升后的脚手架。
五、Fixture 契约 默认使用用例本地数据：packages/desktop/test/e2e/fixtures/upstream/common.json 用于真正共享的辅助响应；packages/desktop/test/e2e/fixtures/upstream/<domain>/<case>.json 用于用例专属 provider 响应；packages/desktop/test/e2e/fixtures/cases/<domain>/<case>.json 用于 manifest 元数据；packages/desktop/test/e2e/fixtures/fs/<domain>/<case>/ 用于文件系统 fixture。每个请求需归类为 main、common、ignore 或 synthetic，不确定的分类由开发者审查，工具负责机械检查；不要向 provider-basic.json 新增用例专属响应。时序类型：fast-text 用于普通功能断言；controlled-stream 用于停止、排队、中断或运行窗口断言；recorded-stream 用于性能或流节奏断言；fault-stream 用于 socket、截断、限流或错误注入。每个 synthetic 请求需在 fixture 元数据和 manifest requests 中提供 syntheticReason。
六、校验
填充 fixture 后，对 pending 用例，在晋升前用规范正式目标 fixture 元数据校验当前 spec：
pnpm --filter @zcode/desktop e2e:fixture:check -- --spec ./test/e2e/conversation-session/manual-review/pending/<case>.test.ts
pending 期间 case manifest 与用例本地 provider fixture 中的 spec 字段仍保持 ./test/e2e/conversation-session/<case>.test.ts，它是规范正式目标而非当前物理路径；pending 回放仍显式传入 E2E_PROVIDER_REPLAY_FIXTURE_PATH，使普通手工审查运行仍捕获真实 provider 路径。
晋升后执行：
pnpm --filter @zcode/desktop e2e:fixture:check -- --spec ./test/e2e/conversation-session/<case>.test.ts
并证明用例不依赖旧共享 fixture：
E2E_PROVIDER_REPLAY_FIXTURE_PATH=packages/desktop/test/e2e/fixtures/upstream/common.json,packages/desktop/test/e2e/fixtures/upstream/conversation-session/<case>.json
pnpm --filter @zcode/desktop exec wdio run wdio.conf.ts --spec './test/e2e/conversation-session/<case>.test.ts'
再运行默认回放：
pnpm --filter @zcode/desktop exec wdio run wdio.conf.ts --spec './test/e2e/conversation-session/<case>.test.ts'
在加入 Docker 套件前，先在隔离回放中证明正式用例：
E2E_SPEC=./test/e2e/conversation-session/<case>.test.ts pnpm run test:e2e:container
通过后准入 Docker 对话预设：
pnpm --filter @zcode/desktop e2e:docker:admit -- --spec ./test/e2e/conversation-session/<case>.test.ts --verified --artifact packages/desktop/.e2e-artifacts/<run-id> --apply
pnpm run test:e2e:container:conversation
准入后 Docker 运行以套件为方向，单 spec 隔离 Docker 运行仅用作准入证明或失败定位；用例准入后通过匹配预设批量运行稳定兼容 spec，以复用镜像、容器启动、WDIO 入口、桌面应用构建和 agent 服务器构建。仅当需要真实捕获、故障注入、性能/时序敏感回放、全局状态污染或特殊网络/文件系统设置时，才拆分到独立预设或容器。
七、代码检查 E2E 代码改动需对最终变更运行一次： pnpm --filter @zcode/desktop typecheck:e2e pnpm typecheck pnpm lint 仅文档修改使用 AGENTS.md 中的文档检查。生命周期检查与代码检查通过后结束，仅在新编辑、失败或未解决风险后再重复或扩展，并保持上述人工审查与晋升/准入要求；若必需环境或检查被阻断，完成可执行部分并报告剩余证据，遵循根 AGENTS.md 完成规则，不要自动提交未完成验证，并将既有警告与新失败分开报告。