feature-smoke-test

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

确定测试范围

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

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 下，无需额外配置。

环境准备

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

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

默认执行方式

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

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：

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 → 代码路径 → 出错点 → 产物表现的完整链路
• 修复建议：最小改动方案，附具体文件和行号
• 回归风险：修复后需要额外验证的相关功能