@zhgengr/tapd-test-platform

AI 测试平台（PI 扩展）：从 TAPD 拉取迭代需求 → AI 生成测试用例 → Web UI 实时过程（需安装 PI 智能体 @earendil-works/pi-coding-agent）

Packages

Package details

extensionskill

Install @zhgengr/tapd-test-platform from npm and Pi will load the resources declared by the package manifest.

npm report

$ pi install npm:@zhgengr/tapd-test-platform

Package: @zhgengr/tapd-test-platform
Version: 0.1.2
Published: Sep 4, 2026
Downloads: 351/mo · 21/wk
Author: zhgengr
License: MIT
Types: extension, skill
Size: 139.9 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "skills": [
    "scaffold/pi/skills/tapd-testcases"
  ],
  "extensions": [
    "scaffold/pi/extensions/test-platform"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

AI 测试平台（基于 PI 智能体）

目标：构建一个智能体驱动的测试平台，打通 TAPD 需求 → 测试用例 → AI 自动化测试 的链路。

当前版本实现基础功能：从 TAPD 拉取需求，并支持 TUI 命令与 Web UI 两种操作方式。

架构

┌─────────────────────────── PI 智能体（TUI）───────────────────────────┐
│  /tp-config   配置 TAPD 连接：API 请求地址 / API Token / 项目 ID          │
│  /tp-iters    查看迭代列表（可关键词过滤）                               │
│  /tp-pull     按迭代拉取需求（传迭代版本名，自动解析迭代 ID）             │
│  /tp-list     本地需求列表 / /tp-show 详情 / /tp-case 生成用例          │
│  /tp-kb       业务知识库（列出文档 / 按关键词搜索）                    │
│  /tp-web      启动 Web UI                                             │
│  工具：tapd_pull_stories / requirement_list / requirement_get            │
└──────────────┬───────────────────────────────────────┬────────────────┘
               │ 读写                                   │ 启动
               ▼                                       ▼
      data/tapd.db（SQLite）                 web/server.mjs
      （本地需求存储，node:sqlite）            （Web UI，零依赖 Node）
               ▲                                       │
               └──────────── config/tapd.json ─────────┘
                          （TAPD API 地址 + Token + 项目 ID）

.pi/extensions/test-platform/ — PI 扩展（TUI 命令 + LLM 工具）
.pi/skills/tapd-testcases/ — 「需求 → 测试用例」生成技能（智能体按需加载）
web/ — Web UI（server.mjs + index.html，纯 Node 零依赖，可独立运行）
config/tapd.json — TAPD 凭证（已 gitignore）
data/ — 需求数据与测试用例（已 gitignore）

快速开始

1. 配置 TAPD

在 PI 中运行：

/tp-config

按提示输入三项即可：

配置项	说明
API 请求地址	默认 `https://api.tapd.cn`，也可配置为网关/代理地址
API Token	用户 API Token（Bearer 认证）
项目 ID	TAPD 项目 workspace_id，作为拉取需求的默认项目

若你的网关使用其他认证格式，可在 config/tapd.json 中增加 "authHeader": "Token ${token}" 自定义认证头模板。

展示规则：拉取迭代内全部需求，按父子关系树形展示——有子需求的需求作为顶级节点，其余挂到父节点下（多级子需求自动成树，可折叠展开）。既无子需求、父需求也不在本次数据中的「独立需求」默认不在树中显示（Web UI 有开关可显示）。状态/优先级自动映射为可读值（如转测试/测试中、紧急/高/中/低，映射缓存于 data/enums.json）。可选配置："leafOnly": true 改为只拉叶子需求；"excludeNamePrefixes": ["【评审】", "编写测试用例"] 按名称前缀排除（过程性工作项不拉取）；"excludeNamePattern": "正则" 按正则排除；"excludeStatuses": ["rejected", "已拒绝"] 按状态排除（原始值或可读名称均可）

2. 拉取需求（按迭代）

/tp-iters           # 先看看有哪些迭代
/tp-pull V3.6#2     # 按迭代版本名拉取（模糊匹配，多个匹配时会列出供选择）
/tp-pull 1122001    # 也可以直接传迭代 ID

平台流程：用迭代版本名查询 TAPD 迭代列表 → 解析出迭代 ID → 按 iteration_id 拉取该迭代的需求。

也可以用自然语言驱动智能体：

「拉取 V3.6#2 迭代的需求」「看看有哪些迭代，然后拉取最新一个迭代的需求」「列出已同步的 V3.6 迭代需求中还没写用例的」

3. 查看需求

/tp-list            # 本地需求列表
/tp-list 登录       # 关键词过滤
/tp-show 123456     # 需求详情

4. 生成测试用例

/tp-case 123456

智能体读取需求详情后生成结构化测试用例（标题/优先级/前置条件/步骤/预期结果），保存到 data/testcases/。技能文件 .pi/skills/tapd-testcases/SKILL.md 定义了生成规范，可随时调整。

5. Web UI

/tp-web             # 启动，默认 http://localhost:8321
/tp-web 9000       # 指定端口
/tp-web stop       # 停止

也可以脱离 PI 独立运行：node web/server.mjs [port]

Web UI 功能：需求列表（搜索/过滤）、需求详情、一键从 TAPD 拉取、用例草稿生成。

本地联调（无真实 TAPD 凭证）

仓库内置了一个 Mock TAPD 服务，返回示例项目与需求数据：

node tests/mock-tapd.mjs          # 启动 mock，默认 9999 端口

然后 /tp-config 中 API 请求地址填 http://localhost:9999，Token 任意（mock 不校验），项目 ID 填 99887766；或直接沿用已生成的 config/tapd.json 体验完整流程。

数据存储

需求存储在 data/tapd.db（SQLite，使用 Node 内置 node:sqlite，零依赖），主表 requirements（key = workspace_id:需求ID，含名称/描述/状态/优先级/迭代/父子关系等字段，按迭代、父需求、状态建了索引），元数据（各项目最后同步时间）存 meta 表。首次启动会自动从旧版 data/requirements.json 迁移（原文件重命名为 *.imported-<时间戳> 备份）。

扩展（store.ts）与 Web 服务（web/db.mjs）共用同一数据库文件与表结构，可并发访问（WAL 模式）。

Web 列表接口为树感知分页：/api/requirements?page=1&pageSize=50 在过滤结果中按「根需求」分页，每条根需求携带其全部后代，保证父子树跨页完整（响应含 count/rootCount/page/pageSize/items）。

单条需求字段（requirements 表一行，camelCase 为 API 返回格式）：

{
  "id": "...", "name": "...", "description": "...(HTML)",
  "status": "...", "statusLabel": "转测试", "priority": "...", "priorityLabel": "高",
  "creator": "...", "owner": "...", "workspaceId": "...",
  "iterationId": "...", "iterationName": "...",
  "parentId": "...", "childrenId": "||id|id", "level": "0", "workitemTypeId": "...",
  "url": "https://www.tapd.cn/...", "syncedAt": "ISO时间"
}

同步时间记录在 meta 表（lastSync:<workspace_id> → ISO 时间）。

业务知识库（kb/）

生成测试用例需要业务知识才能合理设计场景。平台采用本地 Markdown 知识库 + AI 自动检索的方式，零额外基础设施：

知识放在项目根目录 kb/ 下的 .md 文件里（结构见 kb/README.md，写文档用 kb/模板-业务知识文档.md）。
/tp-case 生成用例时，AI 会按需求关键词检索 kb/（文件名挑选 + grep 定位），把命中的业务规则、术语、支持矩阵、历史缺陷模式融入测试设计；TODO-待确认 的内容会被跳过并向你提问。
用 /tp-kb 查看库里有哪些文档，/tp-kb <关键词> 搜索内容。
从零建库的顺序建议：术语表 → 需求里反复出现的业务规则 → 数据类型/语法支持矩阵 → 历史缺陷与逃生案例 → 优秀历史用例。
文件多（>~50 个）以后再考虑 embedding 检索升级，当前阶段目录 + 关键词足够。

安装（团队分发）

使用者

npm i -g @earendil-works/pi-coding-agent     # 前提：PI 智能体（Node >= 23.4）
pi install npm:@zhgengr/tapd-test-platform  # 安装扩展 + 技能（用户级，全局生效）

然后进入任意项目目录：

pi              # 启动 PI
/tp-config      # 配置 TAPD 连接（自动生成 config/tapd.json，含默认拉取过滤规则）
/tp-pull V3.6#2 # 按迭代拉取需求

Web UI：pi 里执行 /tp-web（扩展自带 web 服务，无需项目内任何文件）
过滤规则、leafOnly 等选项直接编辑项目里生成的 config/tapd.json
业务知识库：扩展内置基础库（/tp-kb 查看，标注 [内置]）；项目建 kb/ 目录即成为项目级覆盖层，两者合并检索

内网离线（无外网 npm registry）：

# 发布者：npm pack 产出 tgz，拷入内网
# 使用者：解压后 pi install 解压出的目录（不要加 npm: 前缀）
tar -xzf tapd-test-platform-0.1.0.tgz -C D:\packages   # 先建好 D:\packages
pi install D:\packages\package

团队统一版本：在项目里执行 pi install npm:@zhgengr/tapd-test-platform -l，会把包源写入 .pi/settings.json 并提交仓库，同事启动 pi 时会提示自动安装。

发布者（本仓库）

npm login
npm publish --access public   # scoped 包首次发布必须指定公开；prepack 自动同步 scaffold/，config/ 与 data/ 不会进包

包内容：仅 scaffold/（发布时由 prepack 自动生成：扩展 + 技能 + 内置 web/ + 内置 kb/）与 README。密钥安全：config/（含 API Token）与 data/ 通过 files 白名单排除，且 prepack 有显式检查。

后续规划

测试用例 ↔ 自动化测试代码集成（将 data/testcases/ 映射到测试组的 AI 自动化框架）
用例执行结果回传 TAPD（关联需求/缺陷）
定时同步 TAPD 需求变更，自动对新增/变更需求生成用例
Web UI 中直接触发 AI 生成用例（后台拉起 headless pi 执行 /tp-case，轮询产物文件）

参考

TAPD Open API：https://open.tapd.cn/document/api-doc/API%E6%96%87%E6%A1%A3/