Agent Service Toolkit 可选依赖冒烟测试技能
一条命令在本地真实验证 Postgres/MongoDB 检查点器、AG-UI 端点和 LangFuse 追踪集成是否真正生效，无需等完整 CI。
项目自身的可选依赖冒烟测试技能，明确说明「先判断要不要跑」而不是无脑执行，考虑了成本效益。
这个 Skill 能做什么，适合哪些场景？
该技能封装了 agent-service-toolkit 仓库中的 scripts/smoke_test.sh 脚本，用于检查那些单元测试和默认 CI 覆盖不到、需要真实基础设施的可选依赖集成。它会用 Docker 启动真实依赖（如 Postgres、MongoDB、LangFuse 全栈），在宿主机上运行服务，做端到端验证后再清理环境。技能的核心价值在于防“绿色但无效”陷阱：除了 API 层测试，还会直接查询依赖本身，确认本次运行的数据确实写入了目标后端，而非静默回退到 SQLite。它还明确指导何时该跑、何时不必跑，避免不必要的容器启动成本。
技能指导代理运行 ./scripts/smoke_test.sh 并解读结果。脚本按目标（postgres、mongo、agui、langfuse、all）启动对应依赖的 Docker 容器，用 uv 在宿主机上以特定环境变量运行服务，通过 API 发起请求验证集成，然后用唯一的每轮线程 ID（SMOKE_THREAD_ID）直接查询依赖（如检查点行数、追踪条数）确认真实后端被使用。脚本还内置端口占用保护、启动失败快速报错并输出日志、针对 LangFuse 异步摄取的轮询。SKILL.md 还给出沙箱云环境的故障处理：启动 dockerd、网络白名单加 cgr.dev、用 fuser -k 8080/tcp 而非 pkill、后台运行脚本等。
- 修改了 src/memory/ 下检查点器代码或 initialize_database 的开发者，需确认 Postgres/MongoDB 持久化仍正常。
- 升级了 langgraph-checkpoint-postgres、pymongo、psycopg 等依赖版本后，想验证真实集成未被破坏的维护者。
- 改动了 src/service/agui.py 或 AG-UI 适配层的贡献者，需端到端确认 AG-UI 流式端点工作。
- 调整了 LangFuse CallbackHandler 接线或 /health 鉴权逻辑的工程师，需确认追踪数据确实到达 LangFuse。
- 准备发版前想跑一次全量信心检查（./scripts/smoke_test.sh all）的维护者。
- 在 Claude Code 云沙箱中工作的代理，需要判断某次改动是否值得花几分钟跑冒烟测试，以及如何在受限网络下绕过常见坑。
这个 Skill 有哪些优点和局限？
- 验证依赖身份而非仅 API 响应，能发现 env 未生效、静默回退 SQLite 等隐蔽 bug。
- 目标化设计，只跑受影响路径，单目标成本低。
- SKILL.md 包含详尽的沙箱/云环境故障指南（dockerd 启动、网络白名单、pkill 自杀陷阱等）。
- 有清晰的'该不该跑'决策表，避免浪费时间和 token。
- 依赖 Docker 和真实基础设施，langfuse 目标需拉取约 5GB 镜像。
- 单次运行需数分钟，不适合频繁触发。
- 仅适用于 agent-service-toolkit 这个代码库，可移植到其他仓库需要按其扩展指南重写。
- 沙箱环境需要容器镜像构建走宿主机 uv 的特殊架构，纯容器化环境不能直接照搬。
如何安装这个 Skill？
该技能位于 agent-service-toolkit 仓库的 .claude/skills/smoke-test/ 目录。将整个仓库克隆后，技能随仓库一起使用（skill 与 scripts/smoke_test.sh 同仓）：git clone https://github.com/JoshuaC215/agent-service-toolkit.git，然后 uv sync --frozen 安装依赖。若要在其他项目中复用，将 smoke-test 技能文件夹复制到你项目的 .claude/skills/ 目录即可（源文档未单独说明跨仓库安装步骤）。
如何使用这个 Skill？
在仓库根目录：先判断改动是否触及检查点器、服务启动/健康检查、AG-UI 适配或 LangFuse 追踪——大多数改动（agent 图、提示词、文档、纯客户端改动）应跳过。需要时运行：./scripts/smoke_test.sh（默认跑 postgres、mongo、agui）；单目标如 ./scripts/smoke_test.sh mongo；子集如 ./scripts/smoke_test.sh postgres agui；./scripts/smoke_test.sh langfuse（约 5GB 重栈，单独跑）；./scripts/smoke_test.sh all（全量）。绿色结束输出 '--- All smoke tests passed ---'，但仍需确认每项 '✓ verified: N …' 的依赖身份校验行存在；'✗ FAIL' 表示依赖未被真正调用，应视为真实失败。