zazi85/salon-bot-plan

# AI Chatbot 工程：预订助手的分析、审计与红队测试 (Spring AI) ## 阅读目的 大多数作品集展示的都是**可运行**的产品。这份文档集展示的是一些 更稀有且难以伪造的内容：**在产品诞生前后，是如何思考该产品的。** 本档案是构建 LLM 系统成熟方法的证明——具体来说是任何专业构建 Chatbot 的人都会关注的三件事： 1. **Guardrail（护栏）** ——不在于 prompt，而在于架构（存在于对模型不可见的 `ToolContext` 中的身份识别，在领域层进行授权而非在指令中）。 2. **Eval（评估）** ——将 Bot 的行为作为 JUnit 测试（Bot 未确认不预订、 不编造日期），并将“无 API key 运行”与“结合模型运行”分离开来。 3. **Prompt injection 与 red‑teaming** ——主动寻找设计论点（“依赖架构，而非 prompt”）悄然失效的环节。 贯穿全文的主题是：**以实证验证取代对模型的盲目信任。** 这里没有任何 技术事实是“凭记忆得出的”——每一个都经过了 JAR 反编译、实际测量或失败 测试的确认。这正是那些基于 LLM 的项目最常缺乏的态度。 ## 本文档集展示了什么（具体细节，而非空洞口号） | 实践 | 文档中的证据 | |---|---| | **以实证验证取代对模型的盲目信任** | `00-FAKTY-TECHNICZNE.md` ——关于技术栈（Spring Boot 4.1, Spring AI 2.0）的每个事实都通过 `.m2` 下的 JAR 包运行 `javap`、配置元数据或实时 API 得到了确认。直接指出：*“模型记忆中关于这些版本的知识是错误的”*。 | | **将 JAR 反编译作为 API 真相的来源** | Spring AI 2.0 的签名（`ChatClient`, `ToolContext`, `Usage`）已通过字节码验证，而非依赖文档。“`javap` 配方”允许在没有互联网的情况下确认 API。 | | **测量 Token 计数器的低估程度 — 2.76×** | `06-AUDYT-CHATBOTA.md` ——可观测性审计员**测量得出**，自带的 Token 计数器低估了实际消耗，误差达 2.76 倍；通过数学计算排除了替代假设。架构层面的结论：使用内置指标 `gen_ai.client.token.usage`，而不是自行计算。 | | **变异测试** | `00`/`01` ——在手动移除 `EXCLUDE` 约束后，并发测试失败，提示 `expected: 1 but was: 2`。这证明了测试检查的是*正确的*事物，而不仅仅是“亮绿灯”。 | | **5 名独立审计员 + 加权评分** | `06-AUDYT-CHATBOTA.md` ——五个独立的视角（3 名进行实时测试，1 名注入变异，1 名反编译 JAR）。结果按每个维度的权重汇总 → **5.7/10**。“趋同发现”（Convergent Findings，≥2 名审计员独立发现）被视为高置信度。 | | **对自身论点进行 Red‑teaming** | `07-AUDYT-PELNY.md` ——完整的待办列表，为每个漏洞提供了 `文件:行号` 证据：通过表单字段伪造身份、通过开放的 REST endpoint 枚举客户、“带有工具的 Bot 也会产生幻觉” (K1)、通过 `X‑Forwarded‑For` header 绕过速率限制（经 8/8 验证）。 | | **实验：天真的 Bot 会产生幻觉** | `04-PLAN-v2.md` §3.4 ——受控实验设计：相同的模型，相同的温度（temperature），两种架构（数据冻结在 prompt 中 vs 使用工具实时获取）。结论：一个 Bot 编造，另一个 Bot 查询数据库，而日历是独立的仲裁者。 | ## 文档地图 文档按时间顺序编号——您可以像阅读航海日志一样，将其视为对同一 问题不断深入探究的过程。 | 文件 | 角色 | 最精彩的部分 | |---|---|---| | **`00-FAKTY-TECHNICZNE.md`** | 经过实证验证的事实层（技术栈，Spring AI API，通过真实错误捕获的 JPA/Postgres 陷阱） | “这绝对不是模型记忆中的知识。” | | **`01-ANALIZA.md`** | 从目标受众（构建 Bot 的代理机构）视角对现有系统进行的分析：优势在哪，漏洞在哪 | 双重评分：作为 Java 项目得 8/10，**作为 Bot 公司的 Demo 得 4/10** | | **`04-PLAN-v2.md`** *(可选)* | 第一波 Review 后的执行计划：支柱、带估算的阶段、受控的“天真 Bot”实验 | §3.4 ——为什么天真的 Bot *必须*编造，才能让结论成立 | | **`06-AUDYT-CHATBOTA.md`** | Chatbot 审计：5 名独立审计员，加权评分 5.7/10，趋同发现 | “它守着大门，旁边却有一扇敞开的窗户。” | | **`07-AUDYT-PELNY.md`** | 完整的交接审计：带 `文件:行号` 证据的待办列表，P0–P2 优先级，确认性审计标准 | 区分：“你没看见的漏洞”（错误）与“你率先命名的边界”（成熟度） | ## 与 `salon-api` 仓库的关联 **本档案是对特定且活跃代码的审计。** 它不是一个独立的实体—— 它描述、规划并解构了一个存在于独立仓库中的系统： - **代码：** [`github.com/zazi85/salon-api`](https://github.com/zazi85/salon-api) (Spring Boot 4.1 · Java 21 · PostgreSQL 17 · Flyway · Spring AI 2.0 · Testcontainers) - **关系：** 这些文档是对该代码进行*思考*的层面——分析 (`01`)， 在其 JAR 包和数据库上验证的事实 (`00`)，其扩展计划 (`04`) 以及对其 安全性、Eval 和 Guardrail 的**两轮独立审计** (`06`, `07`)。 - **如何结合阅读：** 仓库展示了它*能运行*；而档案展示了作者 *知道它在哪崩溃*——包括其自身论点失效的环节。 后者在与 Bot 代理机构的洽谈中，比前者更有价值。 文中格式为 `文件.java:行号` 的引用指向该仓库中的代码。 ## 本档案的诞生过程（坦诚方法论） 本档案本身就是一个 **AI 辅助工程** 的产物：分析和 计划由 AI 助手生成，随后对它们进行了**由独立代理审计员（拥有独立的上下文 和独立的角色——安全、测试、可观测性、架构、Prompt）进行的多轮审计** ，其结果通过加权评分汇总。人类的贡献在于**对该 pipeline 的执导，受众的选择，决策与内容策展**： 正是作者决定，事实应通过字节码验证；审计应独立于代码作者；且趋同发现 的权重应高于单一发现。这种方法的透明度是刻意为之的：项目正是要展示这种 成熟度——*模型的编排，加上人类的判断与质量控制*。这里没有假装 LLM 系统 自我验证；而是展示了如何围绕它构建一个能够捕获其错误的流程。 *此目录中的文档基于文件 [`LICENSE`](LICENSE) 提供的许可证共享。*