Metadata-Version: 2.4
Name: case-atlas
Version: 0.1.0
Summary: Case Atlas：AI 生成测试用例的人工审核工具
Author: Case Atlas contributors
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer<1,>=0.9
Requires-Dist: fastapi<1,>=0.100
Requires-Dist: uvicorn<1,>=0.22
Requires-Dist: filelock<4,>=3.12
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: httpx>=0.24; extra == "test"

# Case Atlas

Case Atlas 是一个面向 AI 生成测试用例的人工评审与治理工具。

AI 编码助手让创建测试变得越来越容易，却也让测试套件迅速膨胀：用例从哪里来、测试什么、是否重复、是否仍然有价值，往往没人能快速回答。传统测试报告关注“这次运行是否通过”，测试管理工具关注“测试流程是否完成”，但它们没有解决测试用例本身的价值判断问题。

Case Atlas 关注的是测试套件的长期质量：让人看懂每条用例，做出明确决策，再把决策转化为可执行的修改方案交给 AI，最后通过运行和复核确认结果。

## 它解决什么问题

AI 编码过程中生成的测试用例，质量往往无法保证，典型有三类问题：

1. **过期用例**：需求迭代后测试没有跟着更新，仍按旧版本测试——老功能可能已废弃，或交互逻辑、功能逻辑已发生较大变化；
2. **无价值用例**：AI 自认为重要的点，实际反映不了任何问题，跑了一堆特别费资源又没用的测试脚本；
3. **覆盖缺失**：该测的核心流程没有被覆盖到。

针对这三类问题，Case Atlas 首版提供以下能力：

- **看得见**：集中展示测试代码、业务意图、证据和 AI 推断（推断会明确标注；运行历史等信息需由生成 Agent 提供）。
- **审得动**：提供以单条用例为核心的评审页面，支持保留、废弃或要求修改。
- **改得准**：把人的意见整理为结构化 Markdown 变更任务，供 Agent 生成可审阅 patch。
- **能闭环**：Agent 执行后运行批次框架对应的完整验证（pytest、Vitest、Playwright、`node --test`，或 tsc/ruff/mypy 静态检查），由人复核结果，评审结论和证据持续留档。

## 总体架构

Case Atlas 由三部分组成闭环，核心特征是 **Web 评审界面零 AI 依赖、md 文件是唯一跨系统协议、文件系统即状态机**：

```text
Claude Code（通过内置 skill）
    │  执行生成 skill，按固定 schema 产出结构化待评审数据
    ↓
~/.case-atlas/pending/<批次>/  ──  case-atlas serve 拉起本地 Web 评审界面
    │                               （纯程序化输出，不调用任何模型）
    │  人工评审：逐条决策、提出新增用例需求，进度实时持久化
    ↓
评审结果 md（人给 AI 的任务书，同时是审计记录）
    │  配合执行 skill 交回 Agent 会话
    ↓
AI 受控修改（patch / 分支）→ 按批次框架运行完整验证 → 执行报告 → 人工复核
```

## 核心工作流

评审动作及其含义：

- **pass**：用例有价值，保留并纳入套件；
- **discard**：用例没有实际价值，确认后删除；不确定时可附质疑 prompt，交由 AI 判定是否删除；
- **discard-question**：暂不确定是否删除，要求 Agent 独立判断并说明理由；
- **revise**：测试意图有价值，但步骤、数据或断言需要修改，附修改意见交给 AI；
- **defer**：本轮暂不处理，导出时保持不变；
- **add**：发现覆盖缺失，以需求描述交由 AI 新增用例（独立于用例 decision）。

## 设计原则

1. **人做价值判断，AI 做分析和执行**。AI 可以解释、归类和起草方案，但不替人做最终取舍。
2. **结论必须有证据**。AI 推断与源码、运行历史、覆盖率等事实分开呈现，并保留来源和置信度。
3. **变更默认可审阅、可回滚**。删除和修改先生成 patch 或分支，不直接破坏原始代码。
4. **评审结果是结构化资产**。决策、理由、验收标准和验证结果可被编码助手读取和执行。
5. **质量不等于覆盖率**。测试价值还要结合业务风险、断言质量、稳定性、维护成本和缺陷发现能力。

## 目标用户

- 使用 Claude Code 生成或维护 pytest / Vitest / Playwright / `node --test` 测试与 tsc / ruff / mypy 静态检查的个人开发者和团队（其他 Agent 尚未在首版提供 skill）；
- 持有大型存量测试套件、希望系统治理测试质量的工程团队；
- 需要让 AI 持续维护测试，而又不希望失去人工把关的项目。

## 项目状态

当前仓库已提供首版可运行实现：文件系统持久化、CLI、仅回环监听的本地 Web 评审界面、事务化 Markdown 导出，以及 Claude Code 生成/执行 skill 模板。数据契约支持以下验证框架（批次 manifest 的 `project.framework`）：`pytest`、`vitest`、`playwright`、`node-test`（各测试框架收集的用例）、`tsc`、`ruff`、`mypy`（静态检查的当前发现）、`catalog`（项目自维护清单/登记表定义的验证用例）；生成/执行 skill 首版只覆盖 claude-code。测试代码的发现、删改增和最终验证仍由 Agent 在用户明确确认后完成。

## 运行时边界

- 运行数据只写入 `~/.case-atlas/`（可用 `CASE_ATLAS_HOME` 隔离）；批次使用 UTF-8
  JSON/JSONL。显式执行 `install-skill` 时，另会在用户级 `~/.claude/skills/` 写入两个
  skill 模板（不在目标项目内写任何文件）；导出时还会在当前工作目录生成评审 Markdown。
- Web 服务只监听 `127.0.0.1`，不调用模型、遥测或外部网络，也不使用数据库或前端构建链。
- CLI 不读取或修改用户项目测试代码；导出的 Markdown 是交给执行 Agent 的唯一跨系统协议。

## 快速开始

```bash
pip install case-atlas
case-atlas init
case-atlas install-skill claude-code
# 生成 skill 通常会自动创建批次；需要空批次时可手工执行：
# case-atlas new-batch --project "$PWD"
case-atlas serve
```

请在包含测试或静态检查配置的项目根目录执行上述命令，并确保 `case-atlas` 已安装到当前
Python 环境；运行生成/执行 skill 还需要可用的 Claude Code 会话。`install-skill` 只会在
用户级 `~/.claude/skills/case-atlas-{generate,execute}/SKILL.md` 创建或更新 skill，
目标项目内不写入任何文件，也不会修改测试代码。安装后，
在 Claude Code 会话中运行生成 skill，并先选择全量或增量发现范围；skill 会创建批次、
写入用例并运行最多三次 `validate` 自检。CLI 不会替 Agent 发现、删除或修改测试。

通常不需要手工先运行 `new-batch`：生成 skill 会为本次会话创建批次。只有在需要准备
空批次或调试批次文件时，才直接运行 `case-atlas new-batch`；该命令只创建 Case Atlas
自己的文件，不会读取项目测试。

生成 skill 会把符合契约的验证用例（按批次框架：pytest / vitest / playwright / node-test 的测试用例，tsc / ruff / mypy 的当前发现，或清单条目）写入 Case Atlas 根目录的 `pending/`（默认根目录为
`~/.case-atlas/`，也可用 `CASE_ATLAS_HOME` 隔离）。在本地页面完成评审后，CLI 或页面导出
`case-atlas-review-<batch_id>.md`；该文件同时保存到当前目录和配置的 `exports_dir`（默认
为根目录下的 `exports/`），原始批次随后进入只读归档。Web 服务只监听 `127.0.0.1`，不
使用数据库、模型 API 或外部静态资源。

常用命令：

- `case-atlas validate <batch_id>`：检查批次数据契约；
- `case-atlas list`：查看 pending 批次和评审进度；
- `case-atlas export <batch_id>`：在所有用例有决策后导出并归档。

评审时可对每条用例选择 `pass`、`discard`、`discard-question`、`revise` 或
`defer`；`discard` 需要二次确认，后两种质疑/修改动作必须填写 prompt。新增需求在
页面的 add 区登记。只有所有用例都有决策（包括 `defer`）时才能导出；导出会拒绝覆盖
已有同名 Markdown。将生成的 Markdown 路径交给执行 skill，确认计划后 Agent 才会在新
分支或 patch 中执行删改增并运行批次框架对应的完整验证。

通过页面/API 添加的新增需求会在批次内使用 `a001`、`a002`……这样的 ID；删除后序号不会
复用，以便导出的评审记录和后续执行报告保持可追溯。`validate` 也支持对 `exported/` 中的只读归档批次
进行复核，但归档批次不能再写入决策或新增需求。

更多命令、数据位置、故障处理和安全边界见 [`docs/usage.md`](docs/usage.md)。

## 这个项目最终想达成什么

让测试从“AI 批量生成的一堆文件”变成“人理解并认可、AI 持续维护、能够真实覆盖项目功能的质量资产”。
