# api-testing

Adopt this skill: https://proskills.md/skills/other/fishzjp-qa-skills-skills-api-testing

Page: https://proskills.md/skills/other/fishzjp-qa-skills-skills-api-testing
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/api-testing/SKILL.md
size: 12349
upstream: https://github.com/fishzjp/qa-skills/blob/main/skills/api-testing/SKILL.md

````text
---
name: api-testing
slug: api-testing
displayName: API 接口测试
version: 0.9.0
description: "API testing from OpenAPI/Swagger or case schemas: parameters, boundaries, auth, idempotency, concurrency, error responses, data consistency; runnable scripts; k6 handoff. Not for: Web UI flows, manual case writing. 接口级测试：参数/边界/鉴权/幂等/并发/错误响应/数据一致性，产出脚本与结果；含 k6 压测。不用于：Web UI、手动用例。"
---

# API 测试（api-testing）

接口级测试——E2E 之外的另一条执行路径。

- **输入**：API 文档（OpenAPI/Swagger）、用例 Schema 中 `execution_model` 可自动化的接口用例、被测环境信息（base URL、账号/Token）；性能轴（类型矩阵轴 1）移交包 `专项移交_性能_*.yaml`
- **输出（落盘）**：API 测试脚本（pytest + requests，或项目既定技术栈）+ 执行分报告 `测试报告_api_{日期}.md`（命名按 `../core/report-template.md` 头注，条目按其 §3 对齐；qa 断点判据按此文件名核收）；性能承接时另产 k6 压测脚本与压测报告（`references/k6-conventions.md`）
- **边界**：Web UI 流程 → `automated-e2e-testing`；接口手动用例设计 → `test-case-writing`

## When to Use

- 给定 OpenAPI/Swagger 文档，需要产出并运行接口自动化测试
- 从用例 Schema 中筛出接口级可自动化用例，转换为 API 脚本执行
- 需要覆盖鉴权/越权、幂等、并发写、错误响应等接口层专项
- 给定性能移交包或接口清单，需要生成并运行压测脚本（k6）——按 `references/k6-conventions.md`

## When NOT to Use

- Web UI 交互流程（点击 / 页面状态）→ `automated-e2e-testing`
- 编写接口的手动测试用例 → `test-case-writing`
- 端到端流水线 → `qa` 编排
- 独立压测环境搭建与容量保障 → 运维/专项协作（agent 侧压测承接见 `references/k6-conventions.md`；外部执行场景按 `test-strategy` 的移交包）
- Mock Server 搭建 → 开发协作事项，不在本 skill 范围

## 脚手架（默认 pytest + requests，可替换为项目既定栈）

```text
api-tests/
├── conftest.py            # fixture：base_url、会话/Token、环境配置（环境变量注入，可由 .env 加载，不硬编码）
├── common/
│   └── client.py          # 统一请求封装：日志、超时、鉴权头、断言辅助
├── test_{模块}_{接口}.py   # 一个接口一个文件，test 名沿用 TC 编号
└── requirements.txt
```

```python
# common/client.py —— 统一请求封装（requests.Session 不支持 base_url，必须显式拼接）
import requests

class Client:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url.rstrip("/")
        self.s = requests.Session()
        self.s.headers.update({"Authorization": f"Bearer {token}"})

    def request(self, method: str, path: str, **kwargs):
        url = f"{self.base_url}/{path.lstrip('/')}"
        kwargs.setdefault("timeout", 10)
        return self.s.request(method, url, **kwargs)

    def get(self, path, **kw):  return self.request("GET", path, **kw)
    def post(self, path, **kw): return self.request("POST", path, **kw)
    # put / delete / patch 同理扩展

def login(user: str, password: str) -> str:
    """按项目实际登录接口实现（如 POST /login 换 token）——占位，勿直接照抄"""
    raise NotImplementedError("按项目登录接口实现")
```

```python
# conftest.py 关键 fixture
import os
import pytest

from common.client import Client, login

@pytest.fixture(scope="session")
def client():
    base_url = os.environ["API_BASE_URL"]          # 环境与账号不硬编码，走环境变量
    token = login(os.environ["API_USER"], os.environ["API_PASSWORD"])
    return Client(base_url, token)
```

> 敏感信息（账号/Token/环境地址）一律环境变量注入，不进代码仓库（与 `automated-e2e-testing` 的 constants 约定一致）。

## 工作流

### 1. 输入解析与范围确认

- 从 OpenAPI 文档提取：接口清单、参数表（必填/类型/范围/默认值）、错误码、鉴权方式
- 从用例 Schema 过滤：`automation.framework: api` 的用例，以及 `execution_model: dev-collab` 且 framework 非 manual 的用例 → 转换对象（test 名沿用 TC 编号：`test_TC_05_01_写入字段读回一致`；framework: manual 的 dev-collab 用例保持手动协作，不转）
- 环境未知 → 向用户索取（base URL、账号、是否可写生产旁路环境），**不确定就问，不猜接口行为**（提问格式与裁决落盘统一按 `../core/clarify-pattern.md`，场景用「执行确认」）

### 2. 用例设计（此时加载 `../core/testing-principles.md`，方法细节 `../core/methods/data-driven.md`）

每接口一张参数矩阵（**分析过程工具，心内构建或草稿即可，不落盘为中间文件**——结论直接进用例，与 test-case-writing 的无中间文件口径一致），逐参数 × 逐属性；重点覆盖：

| 类别 | 必测点 |
|------|--------|
| 参数 | 必填缺失 / 类型错误 / 边界值（空/最值/超大，见 `../core/methods/boundary.md`） |
| 鉴权 | 无 Token / 过期 Token / 错误 Token / 越权（他人资源 id）——越权方法基线 `../core/methods/permission.md`（Role×Action×Resource 矩阵 + 垂直/水平两类越权，即类型矩阵轴 2 的执行层） |
| 幂等 | 同一业务键重复提交 → 不重复创建；重试安全 |
| 并发 | 并发写同一资源 → 无互相覆盖、无中间态 |
| 错误响应 | 每个错误码的触发条件 + 响应体结构与文案 |
| 数据一致性 | 写后读回一致；级联操作后关联数据一致 |

多参数接口的组合面按 `../core/methods/data-driven.md` 第 2 节**显式降档**执行（全组合 → 成对组合 → 风险挑选）：单参数逐属性做全；跨参数交互（跨字段规则 / 参数依赖）选档覆盖，**成对组合为默认档**；降档与被排除的组合面写进 rationale，不静默收缩。

### 3. 脚本编写

- 一个接口一个 test 文件；一条 test 只测一个点，沿用 TC 编号命名
- **输出预算纪律（防空截断）**：同类边界/参数校验用 `@pytest.mark.parametrize` 合并为一条参数化测试，禁止逐值展开重复的 test 函数或超长重复断言——单文件超过 ~250 行即应参数化收敛（生成通道有输出上限，超限会截断产生不可编译代码）
- 断言三件套：状态码 + 业务码 + 响应体关键字段（不写"只断言 200"的弱断言）
- 测试数据自建自清理（setup 创建 / teardown 删除），不依赖执行顺序；数据模板（唯一名等）先核对材料字段约束（maxLength/枚举/格式），模板总长（前缀+随机段）≤ 约束上限 −2——顶格即数据自建缺陷（实测自伤案例：唯一名模板 22 字符撞契约 maxLength 20；两个实测案例与 test-case-writing §4 各存同源副本，修订须两处同步）；**参数矩阵逐格回检跨字段业务规则**（如"使用门槛不能低于面额"）——违反规则的组合改取合法值或拆为显式负向用例，不做隐式非法组合（实测自伤案例：金额顶格 1000 配低于面额的门槛 → 400 THRESHOLD_INVALID 而用例期望 201）
- 依赖前序状态的用例显式在前置里造数，不假设库里有数据（造数模式：`../core/methods/data-factory.md`——makeX 构造器 / 造数通道三选一 / 前缀隔离）

### 4. 运行与结果

报告条目与统计口径以 `../core/report-template.md` 为唯一来源（含机读摘要片段，收尾时加载），保证可直接拼装进 `qa` 收尾的最终报告：

```bash
pytest api-tests/ -v --tb=short          # 全量
pytest api-tests/test_coupon_create.py   # 单文件
```

- 失败用例先分辨：被测系统 Bug / 环境问题 / 用例自身错误——**不自行假设**，环境问题与预期歧义列出来问用户（提问格式同上，`../core/clarify-pattern.md`）
- 失败 ≥3 条时升级为**批量分流**：先按 `../core/triage.md` 四分类定类（A 真缺陷 / B 资产问题〔B1 产品预期变更・B2 用例自身错误〕/ C 环境与依赖故障 / D 不稳定），仅 A 类进入下方 Bug 记录流程，替换单条逐个分辨
- **流水线运行**：以 headless 模式进入 PR 冒烟 / 夜间任务时，检查点降级为未决项、产物按规范落盘、退出码分离基建故障与真缺陷——三条约定见 `../core/pipeline-integration.md`（此时加载）
- **结构覆盖补充证据（可选）**：有被测服务代码且测试环境可插桩（Python 服务 `coverage run` 启动；JVM 服务 JaCoCo agent）时，接口用例跑完取**被测服务的行/分支覆盖率**作为补充 E3 证据——只用于发现**零覆盖/极低覆盖的接口与分支**（漏测信号，转补用例或策略升档），不作为追高的虚荣指标；无插桩条件直接跳过，不阻塞交付
- 发现的 Bug：证据（请求/响应原文、时间戳）按 `../core/report-template.md` §3 记录条目，根因分析移交 `bug-analysis`

### 5. 交付

脚本路径 + 运行统计（§2 执行统计：P0/P1/P2 × 通过/失败/阻塞/未执行，按 `../core/report-template.md`）+ Bug 条目 + 遗留问题清单 + （有插桩时）结构覆盖摘要：零覆盖/低覆盖接口清单。

## 契约与 schema 一致性（类型矩阵轴 10 执行层）

轴 10 决策 include 时按本节执行（决策与档位来自 test-strategy 的 type_scope，本节只管执行形态）；报告回收走 report-template §7 表，执行方列如实填写。

### 两层形态（分工不互替）

| 层 | 对象 | 做法 |
|---|---|---|
| schema 一致性 | 响应体 vs OpenAPI 定义逐字段（类型/必填/枚举） | Schemathesis 一条命令接入：`schemathesis run openapi.yaml --base-url $API_BASE_URL`；或手写 jsonschema 断言并入现有 test 文件 |
| 结构级负向 fuzzing | 结构鲁棒性（类型错位 / 超长 / 格式畸变） | Schemathesis 自动生成非法输入。与 §2 参数矩阵分工：**矩阵管业务语义组合，fuzzing 管结构鲁棒性** |

### 概念边界

- schema 校验 ≠ 消费者契约：schema 只验"响应符合定义"，契约验"消费者-提供者允许的交互集合"
- Pact 式消费者驱动契约的启用判据：多消费者微服务且字段演进频繁——单系统项目 schema 一致性即可，不上契约框架
- 契约执行物按 type_scope 进执行策略裁决（脚本型消费方式）；mock/沙箱依赖不可得按矩阵 R5 记 blocked

### 执行纪律

- fuzzing 发现的 5xx / 未定义错误码视为候选缺陷，逐条归因（与 §4 失败分辨同流程），不自动记 Bug
- schema 校验全过 ≠ 契约没问题：字段语义变更（结构未变）schema 层不可见，语义回归靠业务用例

## Common Mistakes

| 错误 | 后果 | 正确做法 |
|------|------|---------|
| 只断言状态码不断言业务码与响应体 | Bug 漏检（200 但业务失败） | 状态码 + 业务码 + 关键字段三件套 |
| 硬编码环境地址与账号 | 无法跨环境运行、泄露敏感信息 | 环境变量注入 |
| 测试间共享可变状态 | 顺序依赖、偶发失败 | 自建数据 + 自清理，每条独立 |
| 重复提交不测幂等 | 重复创建类 Bug 上线 | 同业务键重复请求必测 |
| 失败一律记为 Bug | 误报污染报告 | 先归因（系统/环境/用例），歧义问用户 |
| 无权限/越权只测前端表现 | 后端未拦截的越权漏检 | 直接调接口测鉴权（无 Token/过期/他人 id） |
| 多参数接口逐值全展开或随手抽样 | 组合爆炸截断 / 参数交互缺陷静默漏测 | 按降档策略显式选档（全组合 → 成对 → 风险挑选），降档留痕 |
| Schema 用例带占位符/虚构入口仍直接翻成脚本 | 幻觉脚本：能跑通但测的不是真实接口 | 转换前过 `../core/executability.md` 红线闸门，补不了的暂缓进遗留清单 |
| schema 校验全过就当契约没问题 | 字段语义变更（结构未变）漏检 | schema 只验结构；语义回归靠业务用例（见「契约与 schema 一致性」节） |
````

## File: README.md
upstream: https://github.com/fishzjp/qa-skills/blob/main/README.md

````text
[简体中文](./README.md) | [English](./README.en.md)

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./assets/hero-dark.png">
    <img src="./assets/hero.png" alt="QA Skills —— 知识 × 工具 × 决策的测试工程 Skill 框架：十轴类型决策矩阵与完整测试流水线" width="800">
  </picture>
</p>

<h1 align="center">qa-skills</h1>

<p align="center"><strong>让 AI 像资深测试工程师一样工作。</strong></p>

<p align="center">面向 AI 编程 Agent 的测试工程 Skill 框架。<br>从需求澄清、风险决策，到可执行用例、自动化与测试报告。</p>

<p align="center">
  <a href="https://github.com/fishzjp/qa-skills/actions/workflows/ci.yml"><img src="https://github.com/fishzjp/qa-skills/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="./skills/"><img src="https://img.shields.io/badge/skills-12-blue" alt="Skills"></a>
  <a href="https://www.skills.sh/fishzjp/qa-skills"><img src="https://img.shields.io/badge/skills.sh-npx%20skills%20add-black" alt="Install via skills.sh"></a>
  <a href="https://github.com/fishzjp/qa-skills/releases"><img src="https://img.shields.io/badge/release-%E5%A2%9E%E7%9B%8A%E7%9F%A9%E9%98%B5%E5%BF%AB%E7%85%A7-orange" alt="Release gain matrix"></a>
  <a href="https://github.com/fishzjp/qa-skills/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
</p>

---

把测试方法、流程与产出标准装进你的 Agent：**13 个测试 skill + 一个共享知识库 `core/`**。可以跑完整流水线，也可以只写用例、审查、测接口或治理 flaky 测试。先看[五组真实产出对照](./examples/)，了解安装前后的区别。

[官网与能力导航](https://fishzjp.github.io/qa-skills/) · [快速开始](#快速开始) · [选择 skill](#选择-skill) · [工作原理](#工作原理) · [兼容性与边界](#兼容性与边界) · [实测效果](#实测效果) · [文档导航](#文档导航)

## 快速开始

### 1. 安装全部 skill

通过 [skills.sh](https://skills.sh) 从 GitHub 安装（需要符合 skills CLI 要求的 Node.js 提供 `npx`，当前实测 Node.js 24，无需登录 npm）：

```bash
npx skills add fishzjp/qa-skills --skill '*'
```

按安装器提示选择宿主与安装范围。**保留 `--skill '*'`：`core/` 是必需的共享依赖，不是独立触发的 skill。** 单装某个 skill 而不带 `core/` 会使相对路径引用断开；补救时重新执行上面的全量安装命令。

<details>
<summary><strong>其他安装方式、升级与卸载</strong></summary>

**仓库安装脚本**（需要 Git 与 Bash）：

```bash
git clone https://github.com/fishzjp/qa-skills.git
cd qa-skills
./install.sh                 # 交互选择宿主目录
```

明确知道目标目录时可指定路径，目录不存在会自动创建：

```bash
./install.sh --target ~/.agents/skills
```

请先确认宿主会读取该目录。`./install.sh --auto` 只选择**已有**目录中的首个候选，依次为 `~/.agents/skills`、`~/.claude/skills`、`~/.codex/skills`、`~/.dsh/skills`、本仓库 `.claude/skills`；没有候选时会退出。

| 安装方式 | 升级 | 卸载 |
|------|------|------|
| skills.sh | 重跑全量安装命令 | 使用 skills.sh 的移除功能，按其提示选择条目 |
| `install.sh` 拷贝 | `git pull` 后重跑原安装命令 | `./uninstall.sh --target <原安装目录>` |
| `install.sh --target <目录> --link` 软链 | `git pull` 即更新内容；保留仓库原路径 | 同上；卸载前保留源仓库 |

软链安装的 `qa-skills.VERSION` 是安装时快照，`git pull` 不会重写它；要刷新标记可重跑安装脚本。

**DeepSeek Harness（dsh）**：克隆仓库后，直接安装到 dsh 的技能目录：

```bash
./install.sh --target ~/.dsh/skills
```

升级时 `git pull` 后重跑同一命令。项目已停止通过 npm 插件包分发；已有插件用户请先用 dsh 的插件管理器移除旧插件，再按上述方式安装，避免重复装载。

**手动复制**：把 `skills/` 下全部一级目录复制到宿主 skills 目录，保持各 skill 与 `core/` 同级；已有同名目录时先核对归属，避免覆盖其他内容。手动复制不生成版本标记。

</details>

### 固定版本、升级与回退

默认命令跟随 GitHub 源，不等于锁定最新 Release。需要可重复安装时，使用 Git tag（以下 v0.9.0 是已发布的历史版本，不包含 main 后续修复）：

```bash
git clone --branch v0.9.0 --depth 1 https://github.com/fishzjp/qa-skills.git qa-skills-stable
cd qa-skills-stable
./install.sh --target ~/.agents/skills
```

切换版本：在完整克隆中 `git fetch --tags`，执行 `git switch --detach <已发布-tag-或完整-commit>`，再重跑安装器；回退同理。先保存本地改动，确认该版本的安装脚本与目标目录归属兼容。旧版没有新安装器的恢复能力。

当前安装器先全量预检、暂存，再替换；可处理的复制/替换失败会恢复原内容和版本标记。**多目录切换不是整组原子操作，安装时请暂停宿主读取**。断电或 SIGKILL 无法触发回滚；出现 `.qa-skills.lock` 或 `.qa-skills.txn.*` 时，先检查其中 pid 是否仍运行，保留事务目录并按 [恢复说明](./RELEASING.md#安装失败恢复--installation-recovery)处理，不要直接删除备份。已有本框架目录会整体替换，本地自定义请在仓库分支维护。

### 2. 检查安装与装载

从克隆仓库运行文件级检查（使用宿主的实际目录，skills.sh 安装也适用）：

```bash
python3 scripts/verify_install.py ~/.agents/skills
```

请从与安装版本相同的 tag/commit 运行校验器。该检查验证完整单元、辅助文件与 core 引用，不调用模型，也不能证明宿主已装载或输出质量。

安装目标应包含下方[技能清单](#选择-skill)中的目录及 `core/`，例如 `qa/SKILL.md` 与 `core/executability.md`。**只有仓库 `install.sh` 会额外写入 `qa-skills.VERSION`（版本、commit、安装方式与来源）**，其他方式不能用该文件判断成功与否。

按宿主要求刷新技能或新开会话，试一句“请使用 test-strategy，为这个需求制定测试策略”。从宿主的装载记录确认 `test-strategy/SKILL.md` 及所需 `core/` 文件已读取；没有装载记录时，可要求 Agent 列出实际读取的文件路径。仅目录存在不代表触发已成功。

### 3. 提供输入，开始测试

第一次使用可先走 [会议室预约练习](./examples/first-task/README.md)：无需运行环境，包含完整输入、阶段请求和人工验收清单。

在被测项目中对 Agent 说：

```text
帮我测试这个需求：优惠券到期后自动结束。
需求：<替换为你的 PRD 路径>
代码：当前仓库；回归对比基线：main
先完成需求分析和测试策略，列出需要我确认的问题。
```

需求可以是文字、PRD、接口文档或已有用例。提供代码可补充实现证据；只有文档时会保留待确认项。进入执行阶段前，还需要可访问的测试环境、测试账号与运行工具：Web E2E 使用 Playwright，API 测试使用 Python / pytest 等，压测按需使用 k6。**安装 skill 不会同时安装这些工具或被测系统。**

完整流程会在需求澄清、执行策略、Bug 定性与预算裁决处等待你确认。只需要一步时，直接使用下面对应的请求。

## 选择 skill

| 你的需求 | Skill | 主要产出 |
|------|------|------|
| “帮我完整测试这个需求” | [qa](./skills/qa/SKILL.md) | 阶段编排、流水线状态与最终测试报告 |
| “梳理这份需求，有疑问先问我” | [requirement-analysis](./skills/requirement-analysis/SKILL.md) | 需求模型、范围与澄清记录 |
| “这个功能应该怎么测，哪些不测” | [test-strategy](./skills/test-strategy/SKILL.md) | 风险图、十类测试决策 `type_scope`、专项移交包 |
| “根据 PRD / 代码写测试用例” | [test-case-writing](./skills/test-case-writing/SKILL.md) | markmap 用例 + 机器可读 Schema |
| “审查这份已有用例” | [test-case-review](./skills/test-case-review/SKILL.md) | 覆盖与可执行性审查、修订文件和记录 |
| “把用例转成 Web 自动化并执行” | [automated-e2e-testing](./skills/automated-e2e-testing/SKILL.md) | Playwright 工程、执行结果与缺陷证据 |
| “根据 OpenAPI 测这些接口” | [api-testing](./skills/api-testing/SKILL.md) | API 测试脚本、执行结果；按需 k6 移交 |
| “文档不全，先探索这个系统” | [exploratory-testing](./skills/exploratory-testing/SKILL.md) | charter、探索笔记、风险与测试想法 |
| “定位这个已确认 Bug 的根因” | [bug-analysis](./skills/bug-analysis/SKILL.md) | 根因、影响、证据与回归建议 |
| “这次改动应该回归哪些用例” | [regression-testing](./skills/regression-testing/SKILL.md) | diff → 功能 → 用例的分级回归清单 |
| “用例时好时坏，重跑绿了能信吗” | [test-reliability](./skills/test-reliability/SKILL.md) | flaky 取证、隔离与重试策略、套件健康度 |
| “沉淀 / 读取这个项目的测试经验” | [qa-memory](./skills/qa-memory/SKILL.md) | 项目 `.qa/` 知识库、索引与校验结果 |
| “测这个 AI 功能（LLM / prompt / agent / RAG）” | [ai-system-testing](./skills/ai-system-testing/SKILL.md) | 风险建模、评测集与 rubric、容错断言、judge 校准、prompt 回归与注入面移交包 |

`core/` 是以上 skill 共用的方法、模板与脚本，完整索引见 [core/SKILL.md](./skills/core/SKILL.md)，无需单独调用。

## 工作原理

**阶段产出保存为文件，后续阶段按文件衔接。** 流水线中断后，在新会话中提供产物目录，让 `qa` 根据阶段完成判据续跑。

```text
PRD / 代码 ──（文档不足时先探索）
   ↓ requirement-analysis
需求模型.md                         ⏸ 澄清
   ↓ test-strategy
测试策略.md + type_scope            ⏸ 预算（触及裁决条件时）
   ↓ test-case-writing → test-case-review
测试用例_markmap.md + schema.yaml   ⏸ 执行策略
   ↓ Playwright / API / 手动执行
执行记录 + 缺陷证据                  ⏸ Bug 定性
   ↓ bug-analysis / regression-testing（按需）
Bug 条目 / 回归清单 → 测试报告
```

- **可执行的用例**：写清前置条件、操作入口、步骤、可判定结果与异步时限。标准见 [executability.md](./skills/core/executability.md)，完整产物见[用例示例](./examples/test-cases_with-skills.md)。
- **有证据的范围决策**：证据分级 E0–E4；风险评级附依据，十个测试类型逐一决定纳入、深度或排除，记录在可校验的 `type_scope` 中。
- **按需装载**：SKILL.md 保留触发边界与工作流，方法和模板放在 `core/`、`references/` 中。宿主支持子会话时按阶段隔离上下文；否则用顺序会话与文件衔接，具体遵循效果仍需在该宿主验证。
- **跨会话知识**：阶段状态留在产物文件中；可复用的项目经验由 `qa-memory` 管理，避免与流水线状态混写。

<details>
<summary><strong>渲染用例脑图与装载项目知识库</strong></summary>

**脑图**：`测试用例_markmap.md` 可用 [VS Code Markmap 扩展](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode) 预览，或运行 `npx markmap-cli 测试用例_markmap.md` 生成 HTML。

**项目知识库**：`qa-memory` 在被测项目维护 `.qa/INDEX.md` 与主题条目，skill 触发时主动读取。要让宿主在后续会话发现索引，可在其项目指令文件加入入口：

| 宿主支持的入口 | 配置 |
|------|------|
| `AGENTS.md` | 写明“测试任务开始时先读取 `.qa/INDEX.md`，再按需读取相关条目” |
| Claude Code 的 `CLAUDE.md` | 加入 `@.qa/INDEX.md`，或经现有 `@AGENTS.md` 导入链装载 |
| Aider | 在 `.aider.conf.yml` 配置 `read: .qa/INDEX.md`，或启动时加 `--read` |
| 其他宿主 | 按该宿主的项目指令机制配置，或由 skill 触发时读取 |

这些入口依赖宿主的文件发现与读取行为，不等于自动展开所有 Markdown 链接。入口自举会先展示改动、经你确认再写；知识条目按 [memory_validate.py](./skills/qa-memory/scripts/memory_validate.py) 的校验结果处理。

</details>

## 兼容性与边界

产品以 Markdown 指令、相对路径引用与按需运行的辅助脚本分发。安装器支持 Bash 3.2+；公开脚本支持 Python 3.9–3.14，CI 抽测 Linux 3.9/3.12/3.14 与 macOS 3.12。原生 Windows 暂未覆盖，建议 WSL；宿主路径仍需单独验证。宿主需要支持 skill 发现、文件读取；实际执行还需要终端或浏览器工具。

| 宿主 / 方式 | 目录或载体 | 已有验证的范围 |
|------|------|------|
| Claude Code | `~/.claude/skills/` 或项目 `.claude/skills/` | 主要适配对象；安装形态有实测记录 |
| 共享目录 | `~/.agents/skills/` | 安装脚本优先候选；是否
````
