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