# Feature Smoke Test

> 针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。

- Skill: `moonshotai/feature-smoke-test` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add moonshotai/feature-smoke-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moonshotai/feature-smoke-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: moonshotai (https://skillmd.com/u/moonshotai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/moonshotai/feature-smoke-test

---


冒烟测试是运行时验证，不是写完 prompt 或读完代码就结束。必须实际执行、实际检查产物。

## 确定测试范围

动手之前，先从代码变更推断功能边界：

```sh
git diff main --name-only
git diff main --stat
```

根据变更文件集合，明确写下：

- 被测的功能边界
- 用户可感知的行为变化
- 运行前的准备工作和运行后的清理工作
- 能够证明成功或失败的证据

如果功能涉及状态、异步、审批流或时序敏感逻辑，默认认为单条 prompt 不够。

## 先读事实来源

读取定义该功能真实行为的最小文件集合：

- 面向用户的文档、changelog 或设计笔记
- 暴露该功能的 agent prompt 或 tool prompt
- 实现层入口
- 已有测试——当测试比文档更准确地描述行为时优先看测试

不要信任过时的 prompt 示例。先从代码或当前文档重建真实的工具接口。

## 制定最小测试计划

默认覆盖三个场景：

1. 正常路径
2. 边界条件、非法输入或容量极限
3. 中断、重试、清理或恢复

每个场景记录：

- `目标`
- `前置准备`
- `prompt 策略`
- `成功信号`
- `失败信号`
- `需要检查的产物`

如果功能存在竞态条件，必须显式标注时序。用长时间运行的命令或刻意的等待来制造时序窗口，不要用"快速再跑一个"这种模糊说法。

## 优先使用多轮 prompt

默认采用多轮流程：

1. 探索轮：让 agent 在阅读事实来源后复述当前真实接口
2. 执行轮：只执行一个场景
3. 观察轮：只读取输出、工具状态和产物文件，不扩大范围
4. 清理轮：停止、回滚或关闭有状态资源

仅对无状态的简单功能使用单轮 prompt。

多轮测试时，每一轮单独调用 CLI，在两轮之间检查上一轮的输出和产物，再决定下一轮的 prompt。不要把多轮 prompt 一次性塞进 stdin——那是盲写，无法根据上一轮结果调整。

测试时，显式要求 agent 先列举当前可用的工具，不要臆造历史工具名。可复用的 prompt 模板见 `references/prompt-patterns.md`。

## 以非交互模式隔离运行 CLI

使用 `/tmp` 下的一次性目录作为 `--work-dir`，实现 session 隔离。CLI 的 session 路径由 `~/.kimi/sessions/<md5(work_dir)>/` 决定，不同的 work-dir 自动产生独立的 session 命名空间，不会污染正常项目的 session。认证状态保留在 `~/.kimi` 下，无需额外配置。

### 环境准备

```sh
SMOKE_DIR="$(mktemp -d /tmp/kimi-smoke-XXXXXX)"
```

如果功能需要仓库上下文（读取代码、git 信息等），把仓库文件复制或软链到 `SMOKE_DIR`。如果功能会编辑文件，绝不要用活跃仓库作为 work-dir。

### 默认执行方式

绝大多数场景使用这个模式：

```sh
uv run python -m kimi_cli.cli \
  --print \
  --prompt "你的测试 prompt" \
  --work-dir "$SMOKE_DIR"
echo "exit_code=$?"
```

`--print` 会自动启用 `--yolo`（自动批准所有操作），适合无人值守的冒烟测试。

执行后**必须先检查退出码**：非零表示 CLI 本身崩溃或超时，应优先排查进程级错误，再看 session 产物。

### 备选执行模式

当默认方式不满足需求时，按需选用：

- **长 prompt**：通过 stdin 传入——`cat <<'PROMPT' | uv run python -m kimi_cli.cli --print --input-format text --work-dir "$SMOKE_DIR"`
- **结构化输出**：加 `--output-format stream-json`，输出逐行 JSON，便于程序化解析
- **只看最终结果**：用 `--quiet`，等价于 `--print --output-format text --final-message-only`

### 注意事项

- 运行过程中记录这些路径：`SMOKE_DIR`、最终 session 目录（可通过 `inspect_session.py` 定位）、功能特定的输出文件。

## 刻意执行

执行过程中维护一份简短的运行日志：

- 使用的完整 prompt
- 关键的工具调用或命令
- 功能产生的 task id、输出路径或审批 id
- 时序敏感时记录时间戳

不要仅凭 assistant 的最终文本推断正确性。运行时文件和工具结果才是事实来源。

## 检查 session 产物

首先检查：

- `~/.kimi/sessions/.../context.jsonl`
- `~/.kimi/sessions/.../wire.jsonl`
- 功能创建的 session 级文件

使用 `scripts/inspect_session.py` 查找并汇总最新 session：

```sh
uv run python .agents/skills/feature-smoke-test/scripts/inspect_session.py --share-dir ~/.kimi
```

脚本退出码含义：0 = 正常汇总，1 = session 目录缺失或无法解析。

如果功能会创建后台任务、通知或附属文件，直接检查这些文件，不要只依赖模型摘要。

## 汇报结论

将结果分为三类：

- **已确认**的行为
- **与预期不符**的行为
- **仍有歧义**、需要更确定性复现的行为

对于每个 bug 或回归，记录：

- 触发它的 prompt
- 精确的 session 路径
- 证明它的产物路径
- 能推导出的最小复现步骤

## 问题探查

当发现与预期不符的行为时，不要停在报告层面。启动并行探查流程定位根因：

### 探查策略

针对每个发现的问题，**同时启动多个独立的探查方向**（使用 Agent 工具并行执行）。根据问题的具体表现自行判断最有价值的探查角度，常见方向包括但不限于：

- 从触发问题的入口沿调用链追踪实际执行路径
- 检查输入数据经过各处理阶段后的变化
- 检查持久化状态（session 文件、后台任务、通知记录等）是否一致
- 运行相关单元测试和集成测试，确认测试是否覆盖了出问题的路径

不必机械地覆盖所有方向。根据 session 产物中的具体异常信号，选择最可能命中根因的 2-3 个方向并行展开。

### 探查输出

每条探查方向独立汇报：

- 探查的具体方向和范围
- 发现的事实（附文件路径和行号）
- 该方向的结论：已定位根因 / 已排除 / 需要进一步调查

### 综合定位

汇总所有探查结果后，输出：

- **根因**：一句话总结问题的本质原因
- **证据链**：从触发 prompt → 代码路径 → 出错点 → 产物表现的完整链路
- **修复建议**：最小改动方案，附具体文件和行号
- **回归风险**：修复后需要额外验证的相关功能