skill安装

1. 下载Skill，
2. 下载scripts文件https://docker-hub-1254257443.cos.ap-guangzhou.myqcloud.com/skill-cli/1.0.0/tpm-skill-scripts.zip
3. 将scripts文件解压到skill文件下
4. AI工具加载skill

拼装后目录结构如下

skill/
├── SKILL.md (13.12 KB) - 技能主文档
├── references/ - 参考文档目录
│   ├── add_plan_cases.md 
│   ├── add_plan_comment.md 
│   ├── create_plan.md 
│   ├── create_testcase.md 
│   ├── exe_plan_cases.md 
│   ├── export_story_cases.md 
│   ├── query_case_exes.md 
│   ├── query_plan_cases.md 
│   └── search_cases_by_link.md 
└── scripts/ - 脚本文件目录（文件解压位置）
    ├── tpm_skill_application.yaml 
    ├── tpm_skill_darwin_amd64 
    ├── tpm_skill_darwin_arm64 
    ├── tpm_skill_linux_amd64 
    └── tpm_skill_windows_amd64.exe 

TPM Skill - 测试用例管理平台工具

TPM Skill 是测试用例管理平台（TPM）面向 AI 场景的命令行工具集，旨在打通 TPM 平台与日常开发工作流。通过将平台能力封装为可供 AI 直接调用的命令，让测试用例融入编码、自测和评审的各个环节，助力测试驱动开发（TDD）。

> 当前支持的功能请参考下方 支持功能 列表，更多平台能力正在持续接入中。

🔴 参数获取规则（最高优先级）

在执行任何命令之前，必须严格遵守以下规则：

1. 所有必填参数都必须由用户明确提供，严禁使用示例值、默认值或自行推测的值
2. 如果用户的请求中缺少任何必填参数，必须先暂停操作，主动询问用户获取缺失的参数，收齐全部必填参数后再执行命令
3. -user 参数（用户ID）：如果配置文件中已保存了 auth.user，则 -user 可省略，无需询问。仅当配置文件中 auth.user 为空且用户未在命令中提供时，才需主动询问。在同一轮对话中，如果用户已经提供过用户ID，后续命令可以复用，无需重复询问
4. 业务参数（如需求ID、用例ID等）：各命令所需的业务参数请参考对应的参考文档，如果用户未提供命令所需的必填业务参数，必须主动询问
5. -output 参数（输出目录）：可选参数，用户未指定时默认为当前工作目录，无需询问

示例交互流程：
- 用户说"帮我导出需求用例"（配置文件中已有 user）→ 缺少需求ID → 主动询问："请提供需求ID"
- 用户说"帮我导出需求用例"（配置文件中无 user）→ 缺少用户ID和需求ID → 主动询问："请提供您的用户ID和需求ID"
- 用户说"导出需求ID为123456的用例"（配置文件中已有 user）→ 参数齐全 → 直接执行
- 用户说"我是zhangsan，导出需求123456的用例" → 参数齐全 → 直接执行

⚠️ Skill 加载后请先更新

加载本 Skill 时，需要检查是否需要更新。 通过版本缓存机制避免频繁重复更新：

更新检查流程

1. 读取版本缓存文件 SKILL_DIR/update_cache.txt
2. 判断是否需要更新：
   - 如果缓存文件不存在或内容为空 → 需要执行更新
   - 如果缓存文件存在，读取第一行的 Unix 时间戳，计算距当前时间的差值：
   • 超过 4 小时（14400 秒） → 需要执行更新
   • 4 小时以内 → 跳过更新，直接输出「✅ 版本缓存有效（上次更新: <缓存中的时间>），跳过更新检查」，然后继续处理用户请求
3. 如果需要执行更新，继续下方的更新流程

执行更新

• 执行更新前，如果用户在当前对话中尚未提供过用户ID，且配置文件中 auth.user 为空，必须先向用户询问用户ID
• 如果配置文件中已有 auth.user，则 -user 参数可省略
• 更新命令会自动检查是否有新版本，如果已是最新则会直接跳过，不会产生额外影响
• 更新完成后，再继续响应用户的实际需求

⚠️ 执行更新命令之前，必须先向用户输出以下温馨提示：

> 🔔 温馨提示：首次运行时，公司安全软件 iOA 可能会弹出网络访问确认窗口。如果您看到 iOA 弹窗，请点击「允许访问」即可，程序会自动重试完成操作。允许一次后，后续将不会再弹出。

# Windows（PowerShell）— 禁用进度条避免干扰，设置 UTF-8 编码避免中文乱码；通过 Tee-Object 同时输出到终端和文件
$ProgressPreference = 'SilentlyContinue'; [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; cmd /c """<可执行文件路径>"" update [-user <用户ID>]" | Tee-Object -FilePath "SKILL_DIR\update_output.txt"

# Linux / macOS（tee 同时输出到终端和文件）
<可执行文件路径> update [-user <用户ID>] | tee "SKILL_DIR/update_output.txt"

其中 SKILL_DIR 为本 Skill 目录（即 SKILL.md 所在目录）的绝对路径。上述命令会同时在终端实时显示输出（方便用户看到 iOA 提示并及时处理）并写入文件供后续读取判定。

参数说明：

🔴 更新命令执行完毕后，必须读取 SKILL_DIR/update_output.txt 文件的内容，在其中搜索以下关键词，对号入座：

📝 写入版本缓存：当判定为"更新成功"时，必须将当前 Unix 时间戳写入 SKILL_DIR/update_cache.txt（覆盖写入），格式为纯数字的 Unix 时间戳（秒），例如 1745308800。这样下次加载 Skill 时就能通过缓存判断是否跳过更新。

> 🚨 注意：http_status_code=403 的优先级最高。即使输出中同时包含"更新失败"等其他文字，只要找到 http_status_code=403 就必须判定为 iOA 拦截。

🚫 更新命令仅允许执行一次，无论结果如何，严禁再次执行。
- 🚫 禁止重复执行同一命令
- 🚫 禁止尝试执行其他命令来绕过或换参数重试
- 🚫 禁止尝试获取更多错误信息或诊断问题

🛡️ iOA 拦截处理规则

公司安全软件 iOA 会拦截未放行程序的首次联网请求，返回 HTTP 403。程序已内置自动重试机制（5 次，每次间隔 6 秒），用户在 iOA 弹窗中点击「允许访问」后即可自动恢复，允许一次后后续不再拦截。

当任何命令的输出中检测到 http_status_code=403 时，必须判定为 iOA 拦截，并执行以下规则：

1. 立即停止，禁止继续执行任何命令
2. 向用户说明情况，并提示通过以下任一方式解除拦截：
   - 检查桌面是否弹出了 iOA 安全提示窗口，点击「允许访问」
   - 或打开 iOA → 选择「安全」→ 在「软件访问详情」中调整放行
3. 需要用户处理完 iOA 拦截后主动重新发起对话

可执行文件位置

预编译的可执行文件位于本 Skill 目录下的 scripts/ 子目录中，即相对于本文件的路径为 scripts/。

> 重要提示：scripts/ 目录下共有 6 个可执行文件。某些文件浏览工具可能无法列出 .exe 文件，请勿因工具未显示而判断文件不存在。请直接根据下表中的文件名拼接完整路径使用，无需额外验证文件是否存在。

根据操作系统和架构选择对应的可执行文件（完整文件名列表）：

文件选择规则：
- Windows 系统：文件名带 windows 且以 .exe 结尾
- Linux 系统：文件名带 linux，无扩展名
- macOS 系统：文件名带 darwin，无扩展名
- 架构：amd64 对应 x86_64 / Intel 64 位，arm64 对应 ARM 64 位（如 Apple Silicon）

🔑 Token 和用户 ID 自动配置（Skill 加载时执行）

每次加载本 Skill 时，必须在执行更新命令之前，先检查 Token 和用户 ID 的配置状态并自动处理。

检查步骤

1. 读取 SKILL_DIR/scripts/tpm_skill_application.yaml 文件
2. 检查 auth.token 的值是否为空字符串 ""
3. 检查 auth.user 的值是否为空字符串 ""

场景处理

场景 A：Token 为空（首次使用）

向用户输出以下提示，并等待用户提供 Token：

> 🔑 检测到尚未配置 API 访问令牌（Token）。首次使用需要配置 Token 才能正常调用平台接口。
>
> 请提供您的 API 访问令牌，我会自动帮您保存到配置文件中，后续使用无需重复配置。

用户提供 Token 后，直接将 Token 写入配置文件：
- 文件路径：SKILL_DIR/scripts/tpm_skill_application.yaml
- 将 token: "" 替换为 token: "<用户提供的Token>"
- 写入完成后向用户确认：「✅ Token 已保存，后续使用将自动读取，无需重复配置。」

场景 B：Token 已配置（非空）

无需任何操作，直接跳过。

场景 C：用户 ID 为空

如果用户在当前对话中提供了用户 ID（例如执行 update 命令时），自动将用户 ID 持久化到配置文件：
- 文件路径：SKILL_DIR/scripts/tpm_skill_application.yaml
- 将 user: "" 替换为 user: "<用户提供的用户ID>"
- 写入完成后向用户确认：「✅ 用户 ID 已保存，后续使用无需重复输入。」

如果用户在当前对话中未提供用户 ID，暂不处理，等到首次执行命令时再询问并保存。

场景 D：用户 ID 已配置（非空）

无需任何操作，直接跳过。

> 💡 用户也可以通过命令行 -token 和 -user 参数临时传入，命令行参数优先级高于配置文件。

如何执行

1. 确定本 Skill 目录的绝对路径（即 SKILL.md 所在目录），记为 SKILL_DIR
2. 根据当前操作系统和架构，从上表中选择对应的完整文件名
3. 拼接路径：SKILL_DIR/scripts/<完整文件名>，直接执行即可

> ⚠️ Windows 执行注意事项：在 Windows 上必须使用 cmd /c 来执行，避免 PowerShell 将 stderr 输出转换为 CLIXML 格式导致显示乱码。

> 📄 输出文件规则：所有命令执行时都必须通过 Tee-Object（Windows）或 tee（Linux/macOS）将输出同时写入终端和 SKILL_DIR 下的 txt 文件。命令执行完毕后必须读取该 txt 文件内容，根据关键词判定执行结果。具体的输出文件名和判定规则请参见各命令的参考文档。

# Windows（PowerShell）— 通用格式
$ProgressPreference = 'SilentlyContinue'; [Console]::OutputEncoding = [System.Text.Encoding]::UTF8; cmd /c """<可执行文件路径>"" <命令> [参数]" | Tee-Object -FilePath "SKILL_DIR\<命令名>_output.txt"

# Linux / macOS — 通用格式
<可执行文件路径> <命令> [参数] | tee "SKILL_DIR/<命令名>_output.txt"

支持功能

使用场景

• 编码阶段 — AI 辅助开发：AI 读取导出的测试用例，理解验收标准，在编码过程中自动对齐测试要求，减少遗漏。
• 编码阶段 — 测试驱动开发：开发前先获取需求关联的测试用例，以用例为目标驱动代码实现，天然保障功能覆盖率。
• 提测前 — 开发自测验收：对照测试用例逐条自检，提前暴露问题，降低测试打回率，提升交付质量与协作效率。
• 协作阶段 — 用例评审与分享：导出的 Markdown 文件结构清晰，便于团队成员在线评审、异步沟通和知识沉淀。