npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

khufu-kit

v0.6.0

Published

Test generation skill framework for AI IDEs, following the test pyramid methodology. Provides /khufu-doc-prd, /khufu-doc-api, /khufu-doc-adr, /khufu-doc-testcase, /khufu-harness, /khufu-test-unit, /khufu-test-integration, /khufu-test-api, and /khufu-test-

Downloads

821

Readme

Khufu

English | 简体中文

面向 AI IDE 的测试生成技能框架,遵循测试金字塔方法,并采用评估驱动开发(EDD)与规约驱动开发(SDD)。

Khufu 提供九项技能——/khufu-doc-prd、/khufu-doc-api、/khufu-doc-adr、/khufu-doc-testcase、/khufu-harness、/khufu-test-unit、/khufu-test-integration、/khufu-test-api 与 /khufu-test-e2e。它们借助 AI 智能体,为项目生成按 MVP 划分的 PRD、REST API 契约、架构决策记录、测试用例文档、项目约束资产(Harness Engineering)、单元测试、集成测试、API 测试与端到端测试。

特性

  • 测试金字塔:覆盖全部四层测试,并内置去重——上层只测下层在结构上测不到的内容
  • 评估驱动开发(EDD):生成测试之前,先定义可量化的质量标准(覆盖率、性能、正确性)。每条测试都服务于一项可度量的评估标准。内置 评估 → 验证 → 改进 反馈闭环
  • 规约驱动开发(SDD):测试用例是显式、带版本的 Markdown 规约文件(specs/<feature>/spec.v<N>.md)。支持正向生成(规约 → 测试)与反向生成(测试 → 规约)。每条测试都链回对应的规约条目
  • 生成路径:
    • 基于规约:从规约文档生成测试(/khufu-test-unit @docs/spec.md)
    • 基于代码:阅读现有实现生成测试(并自动补写回溯规约)
    • 两者一起(API 与 E2E):测试用例和实现都在时,调用目标来自真实的路由或页面,断言来自测试用例
  • 语言感知:自动识别项目语言,并推荐合适的测试框架
  • 可测试性评估(UT):将源文件评为 A/B/C——可直接测试、需要 PowerMock(标记为 fragile),或需要重构(记入 untestable-report.md)
  • H2 数据库支持(IT):为 Java 集成测试提供轻量内存数据库选项——无需 Docker,启动时间小于 5 秒,便于在 CI 中快速得到反馈
  • 共享测试数据工厂:测试数据定义一次,在 IT、API、E2E 各层复用
  • 对齐 TDD:测试遵循测试驱动开发与敏捷实践
  • 需求到 PRD:/khufu-doc-prd 追问需求描述,将其拆成多个 MVP,并在 docs/prd/ 写入一整套 PRD。项目目标、范围与术语表放在 prd-catalog.md,该文档同时链接所有 PRD;Cockburn 完全正式用例放在 prd-mvp1.md、prd-mvp2.md……;非功能性需求放在 prd-quality.md
  • PRD 到测试用例:/khufu-doc-testcase 在 docs/test-cases/ 为一份 PRD 写下对应的一份用例文档(test-cases-prd-mvp1.md……)。基本流、备选流,以及需要单独断言的业务规则,各写一条。脚本只判断命令后面的文字。没有 PRD 路径时,技能在回复里提问,不扫描、也不写文件。用户选择扫描之后,先列出文件,再次确认后才生成。prd-catalog.md 是目录,不是输入
  • PRD 质量属性到 ADR:/khufu-doc-adr 读取 prd-quality.md 与 ADR 模板,按模板要素(背景、驱动因素、备选方案、利弊、影响、确认)对每个决策做架构分析,每次只提出一个决策问题,以可上下选择的方式给出 2–3 个主流方案、推荐项与“用户自行决定”选项;宿主没有结构化提问工具时降级为带编号的纯文本提问。随后把每个确认的技术选型或架构决策写成独立的 ADR。项目已有 khufu-harness 约束资产时写入其 ADR 目录,否则写入 docs/architecture/adr/,并维护链接到全部 ADR 的目录文档
  • PRD 用例到 API 契约:/khufu-doc-api 读取 Cockburn 用例与 prd-quality.md,界定前后端界限,把每个调用点转成 RESTful 契约。它写入 docs/design/api-catalog.md 与 docs/design/api-contracts.md,包含请求/响应/错误 schema、内嵌 OpenAPI 3.0.3、逐 API 的 SLA、验收标准与可测试性说明。输出既可作为实现契约,也可作为 API 测试生成的输入
  • 代码绑定调用(API 与 E2E):已绑定的测试调用真实入口,并按测试用例断言,即便这会让当前实现失败。找不到唯一匹配的用例不生成测试,而是写入 docs/khufu/api/oracle-mismatch.md 或 docs/khufu/e2e/oracle-mismatch.md
  • 多 IDE 支持:可安装到 Claude Code、Cursor、OpenCode、Codex、Qoder 与 Trae——每个工具都按自身的技能/命令目录约定放置技能

快速开始

# 全局安装
npm install -g khufu-kit

# 在项目中初始化。工具列表没有任何预选项。
cd your-project
khufu init

# 对照 npm 上的最新版本,有更新则升级
khufu update

# 在 IDE 中使用技能(以 Claude Code 为例)
/khufu-doc-prd                # 追问需求并生成按 MVP 划分的 PRD
/khufu-doc-api                # 把 PRD 用例转成 REST API 契约
/khufu-doc-adr                # 把 PRD 质量属性转成 ADR
/khufu-doc-testcase @docs/prd/prd-mvp1.md   # 把该 PRD 生成测试用例
/khufu-harness                # 建立 / 更新项目约束资产
/khufu-test-unit              # 生成单元测试
/khufu-test-integration       # 生成集成测试
/khufu-test-api               # 生成 API 测试
/khufu-test-e2e               # 生成端到端测试

技能重命名

技能已按产物重新命名:doc-* 生成文档,test-* 生成测试代码。旧名称不再作为别名保留。升级后请重新安装,安装器会移除旧技能目录:

khufu init --force
# 或在本仓库中
bash scripts/link.sh

| 旧名称 | 新名称 | |--------|--------| | /khufu-ut | /khufu-test-unit | | /khufu-it | /khufu-test-integration | | /khufu-api | /khufu-test-api | | /khufu-e2e | /khufu-test-e2e | | /khufu-to-prd | /khufu-doc-prd | | /khufu-to-test-cases | /khufu-doc-testcase | | /khufu-adr-with-prd | /khufu-doc-adr | | /khufu-api-with-prd | /khufu-doc-api | | /khufu-harness | 保持不变 |

支持的智能体编程工具

Khufu 按各工具自己的技能/命令目录约定安装技能,因此同一条 khufu init 在所有工具中都能使用:

| 工具 | 技能/命令目录(项目内) | 全局目录 | |------|------------------------|----------| | Claude Code | .claude/skills/ | ~/.claude/skills | | Cursor | .cursor/commands/ | ~/.cursor/commands | | OpenCode | .opencode/commands/ | ~/.opencode/commands | | Codex (OpenAI) | .codex/skills/ | ~/.codex/skills | | Qoder | .qoder/skills/ | ~/.qoder/skills | | Trae | .trae/skills/ | ~/.trae/skills |

khufu init 会请你选择要安装的工具,没有任何预选项。--yes 和非交互运行不会代选工具,需要自己传入 --ide:

khufu init --ide claude,qoder,trae          # 带 --yes,或没有终端时必须传入
khufu init --ide claude --scope global      # 等同于 --global;默认范围是项目内
khufu init --ide claude --yes --force       # 跳过其余提问,并覆盖 .khufu/khufu.yaml

--yes 会直接采用检测到的语言,不再询问;检测不到语言时回退到 Java。它不会代选工具。

每个被选中的工具都会在自己的目录中收到全部九项技能(khufu-doc-prd、khufu-doc-api、khufu-doc-adr、khufu-doc-testcase、khufu-harness、khufu-test-unit、khufu-test-integration、khufu-test-api、khufu-test-e2e)。技能附带的文件会一起安装,其中包括 khufu-doc-testcase/scripts/resolve_prd_args.py,以及 khufu-doc-prd、khufu-doc-adr、khufu-doc-api 的模板。

更新

khufu update 将已安装版本与 npm 上最新发布的 khufu-kit 进行比较:

  • 若有更新版本,则执行升级(交互模式下会先询问确认)。
  • 否则提示当前已是最新版本。
khufu update       # 交互模式——升级前询问
khufu update -y    # 直接升级,不再询问

支持的语言

| 语言 | UT 框架 | IT 框架 | API 框架 | E2E 框架 | |------|---------|---------|----------|----------| | Java | JUnit 5/4, TestNG | Spring Boot Test, Testcontainers, H2 | REST Assured, MockMvc | Playwright, Selenium | | Python | pytest, unittest | pytest + testcontainers | pytest + httpx | Playwright | | TypeScript/JS | Jest, Vitest, Mocha | Jest + Supertest | Supertest | Playwright, Cypress | | Go | testing + testify | testing + dockertest | testing + httptest | Playwright | | C# | xUnit, NUnit, MSTest | xUnit + Testcontainers | RestSharp | Playwright | | C++ | Google Test, Catch2, doctest | Google Test | pytest + httpx | Playwright, Qt Test |

初始化会从项目文件识别 Java、Python、TypeScript、JavaScript、Go、C#、C++、Rust、Ruby 和 Elixir。上表中的语言会写入框架、目录和覆盖率默认值。Rust、Ruby 和 Elixir 能被识别,交互式语言列表里也有 Rust 和 Ruby,但这三者没有框架默认值。C++ 由 CMakeLists.txt 或 xmake.lua 识别,不在手动语言列表里。

测试金字塔策略

Khufu 强制执行互不重叠的测试金字塔。每一层负责一个独立的风险维度:

| 层级 | 负责 | 不负责 | |------|------|--------| | UT | 业务逻辑、算法、校验、状态迁移 | 数据库查询、HTTP 路由、UI | | IT | 组件装配、事务边界、ORM 映射、数据库约束 | 业务逻辑细节、HTTP 状态码 | | API | 状态码、响应结构、请求头、认证/鉴权、内容协商 | 组件内部实现、数据库状态 | | E2E | 关键用户旅程、多页面流程、浏览器交互 | 边界校验、穷举错误路径 |

在某一层生成测试时,khufu 会扫描下层已有测试,并跳过不会带来新风险的场景——让测试套件保持精简、快速。

规约体系(SDD)

Khufu 把测试规约当作一等产物。每个功能对应一份带版本的 Markdown 规约:

specs/
├── UserRegistration/
│   ├── spec.v1.md        # 带版本的规约
│   ├── spec.v2.md
│   └── CHANGELOG.md      # 规约变更历史

每份规约文件包含:

# Feature: UserRegistration
- Version: 1 | Created: 2026-06-25 | Source: spec-based | Criticality: High

## Evaluation Criteria          ← EDD: defined BEFORE tests
### Correctness(正确性)
- [ ] Normal input returns User with ID
- [ ] Duplicate email throws DuplicateEmailException

## Unit Tests
### UT-USER-001: shouldCreateUser_whenValidInputGiven
- Category: happy-path | Status: implemented
- Test File: `__tests__/UserService.test.ts`
- Evaluates: Correctness — normal input returns User
**Scenario:** Given ... When ... Then ...

## Evaluation Summary           ← EDD: filled AFTER test execution
| Criteria | Target | Actual | Status |
|----------|--------|--------|--------|
| Line coverage | ≥85% | 88% | ✅ |
| Branch coverage | ≥75% | 72% | ❌ |

规约生命周期:planned → implemented → evaluated → passed(未达标项会触发重新评估)。

脆弱测试处理

对于难以用常规 mock 拆开的紧耦合代码,khufu-test-unit 提供:

  • Java 的 PowerMock / Mockito-inline 支持(静态方法、构造函数、final 类)
  • 此类测试一律标记 @Tag("fragile"),并且默认不进入 CI
  • 脆弱测试按技术债跟踪——目标是不超过测试套件的 20%
  • 不可测代码(C 级)记入 untestable-report.md,并附重构建议

配置

执行 khufu init 后,配置写在 .khufu/khufu.yaml。.khufu/installed-skills.json 记录已安装的技能。TypeScript 项目的内容如下:

ide:
  - claude
  - qoder
  - trae
language: typescript
frameworks:
  ut: jest
  it: jest
  api: supertest
  e2e: playwright
directories:
  ut: __tests__/
  it: __tests__/integration/
  api: __tests__/api/
  e2e: e2e/
coverage:
  ut:
    tool: jest
    thresholds:
      line: 80
      branch: 70
      function: 80
    formats: [lcov, html, text]
    excludes: ['**/*.d.ts', '**/index.ts', '**/*.config.*']
  it:
    tool: jest
    thresholds:
      line: 60
      branch: 50
    formats: [lcov, html]
    excludes: ['**/*.config.*']
scope: project

Java、Python、Go、C# 和 C++ 会写入各自的框架、目录和覆盖率默认值。初始化不会写入 spec、evaluation、categories 或 dataFactories。这些规则仍由 skills/_shared/ 里的技能约定执行。之后可以自行补上可选的 spec 块;测试层技能在它存在时读取 spec.directory(默认 specs/)和 spec.docsDirectory(默认 docs/khufu/)。--force 会替换已有的 .khufu/khufu.yaml。

架构

skills/
├── _shared/
│   ├── mode-selection.md              # 基于规约 vs 基于代码
│   ├── language-detection.md          # 语言与 khufu.yaml
│   ├── framework-selector.md          # 按语言 × 层级选择框架
│   ├── directory-resolver.md          # 测试目录解析
│   ├── coverage-config.md             # 覆盖率工具配置
│   ├── compilation-verification.md    # 编译生成的测试
│   ├── test-execution-verification.md # 运行生成的测试
│   ├── evaluation-framework.md        # EDD 方法
│   ├── test-pyramid-strategy.md       # 分层去重规则
│   ├── spec-sync.md                   # 跳过已经生成过的场景
│   ├── spec-doc-scanner.md            # 读取 docs/khufu 执行记录
│   ├── spec-doc-generator.md          # 写入 docs/khufu 执行记录
│   ├── test-data-factories.md         # 共享数据工厂模式
│   ├── report-template.md             # 统一报告生成
│   ├── parallel-execution.md          # 把生成工作分给子代理
│   └── oracle-binding.md              # 代码绑定调用,测试用例锁定断言
├── khufu-doc-prd/
│   ├── SKILL.md                       # PRD 集:目录、MVP 用例、质量需求
│   └── assets/                        # PRD、用例与质量需求模板
├── khufu-doc-api/
│   ├── SKILL.md                       # 由 PRD 用例生成 REST API 契约
│   ├── assets/                        # API 目录、契约、REST 与 SLA 模板
│   └── references/                    # RESTful API 设计原则
├── khufu-doc-adr/
│   ├── SKILL.md                       # 由 PRD 质量属性生成 ADR
│   └── assets/                        # ADR 与 ADR 目录模板
├── khufu-doc-testcase/
│   ├── SKILL.md                       # 由 PRD 生成 docs/test-cases
│   └── scripts/resolve_prd_args.py    # 判断本次调用是否给出了 PRD 路径
├── khufu-harness/SKILL.md             # 约束资产生成器
├── khufu-test-unit/SKILL.md           # 单元测试生成器
├── khufu-test-integration/SKILL.md    # 集成测试生成器
├── khufu-test-api/SKILL.md            # API 测试生成器
└── khufu-test-e2e/SKILL.md            # 端到端测试生成器

khufu-test-unit、khufu-test-integration、khufu-test-api 和 khufu-test-e2e 通过 Read 工具读取 _shared/。共享逻辑只定义一次。khufu-harness、khufu-doc-prd、khufu-doc-testcase、khufu-doc-adr 和 khufu-doc-api 走各自的流程。

开发

在本仓库中开发

一条命令把技能软链接到位,Claude Code 会直接从工作区加载它们:

git clone https://github.com/agiledon/khufu.git
cd khufu
npm install
npm run build
npm run setup    # 为本地开发创建软链接

setup 会做这些事:

  • 将 skills/_shared/ 软链接到项目根目录的 _shared/(这样技能文件里的 Read _shared/... 引用才能正确解析)
  • 将每个 skills/khufu-*/ 软链接到 .claude/skills/khufu-*/(Claude Code 从 .claude/skills/ 加载技能)
  • 替换先前 khufu init 留下的过期副本

设置完成后,直接编辑 skills/ 下的任意文件,改动立即生效——无需重新构建,也无需再复制一次。

npm test         # 运行 khufu 自身的测试
npm run dev      # 监听模式(tsc --watch)

从本地源码安装到其他项目

用 npm link 把本地 khufu CLI 注册为全局命令,再在目标项目中初始化:

# 第 1 步:从源码构建 khufu-kit
cd /path/to/khufu-kit
npm install
npm run build
npm link                    # 全局注册 khufu 命令

# 第 2 步:安装到你的项目
cd /path/to/your-project
khufu init                  # 写入 .khufu/khufu.yaml,并把技能安装到所选 IDE 的技能/命令目录

修改 khufu-kit 源码后,这样获取更新:

cd /path/to/khufu-kit
npm run build               # 重新编译 TypeScript
# khufu 命令会自动使用更新后的构建产物(npm link)

用完后取消全局链接:

cd /path/to/khufu-kit
npm unlink -g khufu-kit

也可以用本地路径直接 npm install(不注册全局链接):

cd /path/to/your-project
npm install /path/to/khufu-kit
npx khufu init

许可证

MIT