spring-ai

Spring AI

在修改真实的 Maven 或 Gradle Spring AI 项目之前，使用此操作技能进行检查。随附的诊断 CLI 无需联网且不依赖特定提供方：它会读取构建文件、应用配置和源代码，并报告兼容性线索、不安全的默认设置、缺少的对话 ID、流式处理前置条件、工具/MCP 边界、检索配置和可观测性风险。它绝不会发送提示词或泄露 API 密钥值。

入门检查

确认项目根目录，并确认任务是只读还是会修改配置/代码。可以进行只读诊断。在首次执行会更改状态的操作前，确认目标项目、范围和回滚路径（通常是经过审核的提交或还原操作）；CLI 本身是只读的。

运行：

python3 spring-ai/scripts/spring_ai_check.py --root /path/to/project --json

结果是稳定的 JSON，包含 status、project、facts、findings 和 errors。退出码 0 表示没有错误级别的发现；退出码 1 表示存在错误级别的发现，或 --strict 将警告提升为错误；退出码 2 表示调用无效或项目不可读。

工作流

1. 运行检查器，并将其 JSON 输出与项目修订版本一并保留。
2. 根据 references/source-index.md 中的 Spring AI 和 Spring Boot 官方文档，解决构建兼容性问题；不要仅凭传递依赖推断是否受支持。
3. 检查 ChatClient 顾问的顺序和参数。每次调用记忆顾问时，都必须提供明确的对话标识符，该标识符应基于应用的身份验证/会话边界；绝不要使用共享默认值。
4. 对于检索，在检索上下文进入提示词之前，验证文档的所有权/授权。分别测试空检索、过期数据、提供方错误和延迟。
5. 对于工具和 MCP，将模型的工具请求视为不可信的提议。授权和执行由应用负责。限制工具名称、参数、超时、重试、副作用和审计字段。根据当前项目依赖验证 MCP 传输方式和架构。
6. 对于流式处理，在完成之前将部分输出视为临时内容；测试取消、超时、断开连接和失败的完成。不要将部分流视为已提交的答案或副作用。
7. 在生产环境中，默认禁用提示词/补全内容日志记录。如果临时启用，请记录脱敏、访问、保留和回滚要求。
8. 在依赖和提供方凭据可用时，运行项目自身的测试/构建。检查器无法证明提供方连接正常、模型质量达标、RAG 正确或已具备生产就绪条件。

范围和路由

• ChatClient/顾问、Spring 配置、本地诊断和框架故障排查属于此处。
• 模型质量、评估器设计、统计比较和追踪架构属于 agent-evals-and-observability。
• 权限、回退、停用、预算和发布属于 agent-production-operations。
• 威胁建模和安全实现属于 secure-software-engineering。
• 通用 Java/Spring 应用设计属于相关工程技能。

版本说明

官方文档目前将 Spring AI 2.0.1 列为最新稳定版本线，并保留了 1.0 参考版本（1.0.9）。不同版本线的 API 各不相同：例如，当前 2.0 文档将 ToolCallingAdvisor 描述为 ChatClient 的工具循环，而 1.x 应用可能使用模型内部的工具循环。检查器会报告观察到的版本并标记不确定性；它不会重写依赖，也不会在缺少一手兼容性来源的情况下声称某个版本组合受支持。升级时，请重新检查 references/source-index.md 和发行说明。

完成

当项目的构建/配置/源代码事实、发现项、负责人路由和限制均已记录，或外部依赖（提供方凭据、不可用的构建工具、私有制品库）已明确标记为受阻时，即可停止。不要声称静态诊断已成功完成实时冒烟测试。