execution-log.md 21 KB
变更执行日志 — Spring AI Alibaba 供应商适配层与 DashScope 原生接入
本文件持续记录提案、实现、验证和审查证据。变更已于 2026-07-11 归档。
时间线
| 时间 | 阶段 | 事件 | 备注 |
|---|---|---|---|
| 2026-07-10 | Research | 读取根 AGENTS.md、code-copilot/AGENTS.md、全部规则、相关知识和变更模板 |
以根规则和实际 POM 为最高事实来源 |
| 2026-07-10 | Research | 核对 Forge AI 插件调用链 | 当前固定使用 OpenAiApi/OpenAiChatModel/OpenAiChatOptions |
| 2026-07-10 | Research | 核对 Spring AI Alibaba 主仓库 1.1.2.3 |
Spring AI 1.1.2、Boot 3.5.8；Agent Framework 建立在 Spring AI 上 |
| 2026-07-10 | Research | 核对 Spring AI Extensions 1.1.2.3 |
Spring AI 1.1.2、Boot 3.5.10；确认 DashScope Core/Starter 分层及动态 Builder API |
| 2026-07-10 | Decision | 选择核心 spring-ai-alibaba-dashscope，不使用 Starter |
避免默认自动配置读取全局 API Key，与租户数据库动态配置冲突 |
| 2026-07-10 | Decision | 新增显式 adapter_code |
不再依据 providerType 或 URL 猜协议；历史数据保持 Compatible |
| 2026-07-10 | Proposal | 创建 Spec、Tasks、Test Spec 和本日志 | 等待 HARD-GATE 最终确认 |
| 2026-07-10 | Proposal Check | 检查模板章节、8 个 Task、引用路径、占位符、尾随空格和未跟踪文件空白错误 | 修正路径缩写、更新缺失 Adapter 保留语义、tenantId 来源和 EOF 多余空行 |
| 2026-07-10 | Reader Test 1 | 独立读者检查 Spec/Task/Test 一致性 | 发现连接测试 one-of、URL 双向校验、强制离线调用测试、after-commit 缓存和迁移/回退 5 项缺口，暂不 PASS |
| 2026-07-10 | Proposal Fix 1 | 按读者意见修订四份文档 | 五项缺口均已补充业务规则、任务、测试场景和回退前置检查，等待复审 |
| 2026-07-10 | Reader Test 2 | 复审第一轮修订 | 原 5 项关闭；发现 Registry 校验顺序和 DTO null/blank 语义 2 项高风险缺口 |
| 2026-07-10 | Proposal Fix 2 | 固定 Registry 唯一入口与 null/blank 分层语义 | 增加选择→校验→创建测试，以及新增默认/更新保留/blank 拒绝三类测试 |
| 2026-07-10 | Reader Test 3 | 最终只读复审 | PASS，无剩余阻断或高风险项 |
| 2026-07-10 | HARD-GATE | 用户执行 /apply spring-ai-alibaba-provider-adapter |
Spec/Test Spec 状态切换为 apply，进入实现阶段 |
| 2026-07-10 | Git 环境检查 | 尝试创建 feature/spring-ai-alibaba-provider-adapter |
沙箱禁止写入 .git/refs，保留当前 main 工作树继续实现；Task 级 commit 将记录为环境跳过项 |
| 2026-07-10 | Git 环境恢复 | 权限放开后创建 feature/spring-ai-alibaba-provider-adapter |
已切换到独立 feature 分支；前述 Git 跳过限制解除 |
| 2026-07-10 | Apply 基线 | 运行 AI 插件 dependency tree 与 AiInvocationResolverTest |
变更前仅 Spring AI 1.1.2；测试 2/2 通过，确认 -Penable-tests 生效 |
| 2026-07-10 | Task 1 | 导入 Spring AI/Extensions/Alibaba 三个 BOM并增加 DashScope Core | dependency tree 收敛：Spring AI 1.1.2、DashScope 1.1.2.3；AI 插件 reactor compile SUCCESS，未引入 Starter |
| 2026-07-10 | Task 2 Red | 仅新增 AiProviderAdapterCodeTest 后执行定向测试 |
testCompile 按预期失败：AiProviderAdapterCode 尚不存在，Red 证据成立 |
| 2026-07-10 | Task 2 Green | 实现 Adapter Code、实体字段和 V1.0.17 迁移 |
定向测试 2/2 通过；全迁移 placeholder 扫描无输出；字段/字典防重复静态检查通过 |
| 2026-07-10 | Task 3 Red | 新增 Registry、URL Policy、Compatible/Native Adapter 测试后执行定向测试 | testCompile 按预期失败：SPI/Registry/两个 Adapter 尚不存在，Red 证据成立 |
| 2026-07-10 | Task 3 Green | 实现通用运行参数、Adapter SPI/Registry、URL Policy 和两类 ChatModel | 4 个测试类共 12 tests 全部通过；Registry 顺序、失败关闭、DashScope maxToken 和 ToolCalling Options 已覆盖 |
| 2026-07-10 | Task 4 Red | 新增 Cache、事务后失效及 Native Resolver 回归测试 | testCompile 按预期失败：旧 Cache 签名仍依赖 OpenAiChatOptions，Scheduler 尚不存在，Red 证据成立 |
| 2026-07-10 | Task 4 Green | Cache 改用租户安全结构化键并统一委托 Registry；同步/流式调用使用通用运行参数 | 首次补充分支测试发现 Mockito 严格模式的无效桩，调整测试桩作用域后定向 12 tests 全部通过 |
| 2026-07-10 | Task 4 Commit | 提交 ebaaac44 |
代码提交成功；提交后统计上传 Hook 因网络超时失败，不影响本地提交 |
| 2026-07-10 | Task 5 Red | 新增 SecretMasker 和供应商生命周期服务测试 | testCompile 按预期失败：DTO、安全 VO 和密钥工具尚不存在，Red 证据成立 |
| 2026-07-10 | Task 5 Green | 引入 Save/Test DTO、安全 VO、密钥脱敏、严格 one-of 测试和 Registry 连接测试 | 补齐 blank Adapter、DB 失败、未保存配置测试后共 16 tests 全部通过；分页/默认查询迁入 Mapper XML |
| 2026-07-10 | Task 5 Commit | 提交 d46c7e3c |
代码提交成功；提交后统计上传 Hook 再次因网络超时失败，不影响本地提交 |
| 2026-07-10 | Task 6 | 改造活动供应商页面与 API 请求 | 增加字典驱动连接协议、受控 Native URL 联动、仅 ID 测试请求；新增/测试 POST 与更新 PUT 均启用请求加密 |
| 2026-07-10 | Task 6 Commit | 提交 f82a24ae |
代码提交成功；提交后统计上传 Hook 第三次因网络超时失败，不影响本地提交 |
| 2026-07-10 | Task 7 Native 离线回归 | 新增 AiClientImplTest，真实 Cache 经 Mock Registry/Fake ChatModel 运行 |
首轮同步通过、流式输出通过，但异步 doFinally 落库断言发生竞态；改为 Mockito timeout 后 2 tests 全部通过 |
| 2026-07-10 | Task 7 全量验证 | AI 插件测试、AI/Admin package、Flyway 静态检查、Node 20 前端构建 | AI 44 tests 全过；AI 24 模块与 Admin 35 模块 package 成功；前端生产构建成功 |
| 2026-07-10 | Spec Compliance Review | 对照 Spec、Tasks、Test Spec 与实现逐项检查 | PASS；功能、接口、数据、安全和范围边界均符合 Spec |
| 2026-07-10 | Code Quality Review | 检查 Adapter、生命周期、缓存、事务与密钥边界 | 发现活动事务未启用同步时可能提前清缓存；改为 fail-closed 并增加回归测试，同时修正 Controller 既有大括号格式 |
| 2026-07-10 | Review 修复复验 | 运行 AI 插件完整测试 | 45 tests 全过，24 模块 reactor BUILD SUCCESS；未启动服务 |
| 2026-07-10 | Task 8 | 回填战略方案、阶段路线图、Spec/Task/Test 和长期记忆 | 明确 Alibaba 增强层、依赖基线、核心模块、显式协议路由、阶段边界与旧应用回退前置条件；状态进入 review |
| 2026-07-11 | /review 独立复审 |
不采信既有 PASS 报告，从 origin/main..HEAD 重新检查 Spec 与真实代码 |
Spec Compliance PASS；Code Quality PASS；无 Critical/Important，记录 2 项非阻断加固建议 |
| 2026-07-11 | 运行缺陷 Red | 新增权威默认模型、无默认模型失败和安全诊断测试 | Java 17 下 testCompile 按预期失败，缺少 Mapper 方法、Service 解析方法和诊断类型；系统默认 Java 8 的首次环境失败不计入代码 Red |
| 2026-07-11 | 运行缺陷 Green | ai_model 启用默认模型成为权威来源，删除通用 GPT 兜底并增加安全状态码/错误码日志 |
4 个目标测试类 21 tests 全过；gpt-3.5-turbo 生产代码扫描无输出 |
| 2026-07-11 | 管理端重构 | 修复双分页、上传 accept、响应式弹窗、API Key 编辑和模型设默认，并按用户参考图收敛为左列表右配置页签 | 用户否决首轮过度设计后，删除大标题/统计卡/英文装饰/渐变/引导，改为克制配置工作台 |
| 2026-07-11 | 增量验收 | AI 插件完整测试、Admin 主应用装配、Vue ESLint、Node 20 build、Playwright 登录后检查真实页面 | AI 51 tests 全过；Admin 35 模块 package 成功；前端 8485 modules build；1440/1024/375 无页面横向溢出，重复点击保持选中，console errors=0；5173 测试服务已停止 |
技术决策
| 决策 | 选择 | 放弃的方案 | 原因 |
|---|---|---|---|
| 框架主干 | 保留 Spring AI，叠加 Alibaba | 删除 Spring AI 全量重写 | Alibaba 复用 Spring AI ChatModel/ChatClient 抽象 |
| DashScope 接入 | 核心模型模块 + 动态 Adapter | Starter 全局自动配置 | Forge 是多租户数据库动态凭据模式 |
| 路由键 | adapter_code |
providerType、URL 推断 |
历史存在 alibaba/dashscope 和 Compatible/Native 差异 |
| 历史行为 | 全部回填 openai_compatible |
自动升级为 Native | 避免上线即改变协议、请求地址和计费路径 |
| 失败策略 | Fail-closed | 跨 Adapter 自动重试 | 避免重复请求、重复计费和隐藏配置错误 |
| API Key | 脱敏回显 + 同值保留 | 明文返回、固定值覆盖 | 满足安全规则并保护更新链路 |
| 缓存事务边界 | after-commit；事务同步异常 fail-closed | 活动事务中立即失效 | 避免提交前重新缓存旧配置或回滚后误清理 |
| 旧应用回退 | 先清理 Native 配置再部署旧版本 | 直接回退应用 | 旧代码无法识别 dashscope_native，会误用原生 URL |
踩坑记录
| 问题 | 原因 | 解决方案 | 沉淀？ |
|---|---|---|---|
| 官方根 README 示例版本落后于 release | README 仍出现 1.1.2.0/1.1.2.1 |
以 release POM/BOM 1.1.2.3 为依赖事实 |
已沉淀到 pitfalls 104 |
| DashScope Starter 可能无配置即装配 | 两层条件均 matchIfMissing=true |
Forge 只依赖 core model，不引入 Starter | 已沉淀到 decisions 16 / pitfalls 104 |
阿里供应商类型存在 alibaba/dashscope 两种历史值 |
多份初始化 SQL 不一致 | 路由独立为 adapter_code，不依赖品牌类型 |
已沉淀到 decisions 16 |
| Compatible 与 Native 地址不可混用 | API Path 协议不同 | Adapter 显式校验，历史配置不自动切换 | 已沉淀到 decisions 16 / pitfalls 104 |
| 缓存失效方法无调用者 | 更新/删除链路未接入 Cache | 事务成功后按 tenant/provider 主动清理 | 已由实现和测试固化 |
| ID 测试与临时配置混合会形成密钥边界歧义 | DTO 未定义互斥模式时可能加载持久密钥后接受请求字段覆盖 | 定义严格 one-of；混合请求在模型构建前拒绝 | 已由实现和测试固化 |
| 旧应用无法识别 Native Adapter | 旧代码会把原生 Base URL 当 OpenAI Compatible 使用 | 回退前检查 Native 记录并先切回 Compatible URL | 已沉淀到 decisions 16 / pitfalls 104 |
知识发现
- Spring AI Alibaba 依赖关系：Alibaba Agent Framework 与 Extensions 都建立在 Spring AI
1.1.2上，迁移应采用增强叠加而不是替换 Spring AI。 - 动态供应商配置：多租户数据库凭据场景优先直接构建模型核心类，避免默认全局 Starter Bean。
- 协议与品牌解耦：供应商品牌不能稳定表达 API 协议，尤其同一厂商同时提供原生和 OpenAI Compatible 接口。
Spec-Code 偏差记录
| 偏差点 | Spec 预期 | 实际情况 | 处理方式 |
|---|---|---|---|
| 事务同步异常分支 | 更新/删除在事务成功后失效缓存，回滚不清理 | 审查发现实际事务已激活但同步未启用时原实现会立即清理 | 改为抛 BusinessException 失败关闭，并增加第 45 个测试 |
| 公网 DashScope 验证 | 有环境密钥时可选执行 | AI_DASHSCOPE_API_KEY 未设置 |
按 Test Spec 跳过；离线同步/流式/reasoningContent 必跑项已通过 |
验证记录
| 时间 | 变更范围 | 命令 | 结果 | 警告/跳过 | 服务清理 |
|---|---|---|---|---|---|
| 2026-07-10 | Proposal 文档 | rg 占位符/尾随空格扫描；test -f 关键路径；git diff --no-index --check /dev/null <file> |
本地静态检查通过 | 文件未跟踪，使用 --no-index --check 逐文件检查 |
无服务启动 |
| 2026-07-10 | Reader Test 1 | 新上下文 Agent 只读检查四份提案文档 | 未通过；5 项意见已全部修订，复审中 | 无业务代码或服务验证 | 无服务启动 |
| 2026-07-10 | Reader Test 2-3 | 新上下文 Agent 复审修订文档 | 第二轮补 2 项高风险语义；第三轮 PASS | 本轮仅文档检查 | 无服务启动 |
| 2026-07-10 | Proposal 最终静态复验 | git status --short、git diff --name-only、git diff --check、四文件逐一 git diff --no-index --check、尾随空格扫描、关键源码/vendor/文档路径检查、Flyway 版本序列检查 |
全部通过；当前最高迁移为 V1.0.16，计划使用 V1.0.17 无版本冲突 |
仅文档变更，未执行 Maven、前端构建或公网模型调用 | 无服务启动 |
| 2026-07-10 | Task 4 定向回归 | mvn -Penable-tests -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am test -Dtest=ChatClientCacheTest,AiProviderCacheEvictionSchedulerTest,AiInvocationResolverTest -Dsurefire.failIfNoSpecifiedTests=false |
12 tests，Failures/Errors/Skipped 均为 0；reactor BUILD SUCCESS | 首轮补充用例因 Mockito UnnecessaryStubbingException 失败，修正为 lenient 公共桩后复跑通过 |
无服务启动 |
| 2026-07-10 | Task 5 定向回归 | mvn -Penable-tests -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am test -Dtest=AiProviderSecretMaskerTest,AiProviderServiceTest -Dsurefire.failIfNoSpecifiedTests=false；xmllint --noout .../AiProviderMapper.xml |
16 tests，Failures/Errors/Skipped 均为 0；Mapper XML 语法通过 | JVM CDS 与 commons-logging classpath 警告待全量验证统一记录；测试构造器适配和 URL fixture 修正后复跑通过 | 无服务启动 |
| 2026-07-10 | Task 6 前端静态检查 | pnpm exec eslint --fix src/api/ai.js src/views/ai/provider-model.vue；git diff --check |
ESLint 退出码 0，diff whitespace 检查通过；旧 provider.vue 无改动 |
当前系统 Node 为 v26.0.0；规定的 Node v20.19.0 生产构建留到 Task 7 |
无服务启动 |
| 2026-07-10 | Native 统一调用链 | mvn -Penable-tests -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am test -Dtest=AiClientImplTest -Dsurefire.failIfNoSpecifiedTests=false |
2 tests，Failures/Errors/Skipped 均为 0；验证 Native 同步、流式、reasoningContent 和最终会话内容 |
首轮因 Reactor doFinally 异步时序导致验证过早，改为 timeout(2000) 等待后复跑通过 |
无服务启动 |
| 2026-07-10 | AI 插件全量测试 | mvn -Penable-tests -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am test |
44 tests，Failures/Errors/Skipped 均为 0；24 模块 reactor BUILD SUCCESS | JVM CDS、spring-jcl/commons-logging 既有 classpath 警告 | 无服务启动 |
| 2026-07-10 | AI 插件打包 | mvn -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am package -DskipTests |
24 模块 reactor BUILD SUCCESS，生成 AI 插件 Jar | 按命令显式跳过测试；部分既有模块有 deprecated/unchecked 编译警告 | 无服务启动 |
| 2026-07-10 | Admin 主应用装配 | mvn -pl forge-admin-server -am package -DskipTests |
35 模块 reactor BUILD SUCCESS，Spring Boot repackage 成功 | 按命令显式跳过测试；既有模块有 deprecated/unchecked 编译警告 | 无服务启动 |
| 2026-07-10 | Flyway 静态验收 | rg -n '\$\{[^}]+\}' forge-server/db/migration；rg 检查 V1.0.17 字段/字典/tenant；xmllint --noout AiProviderMapper.xml |
placeholder 扫描无输出；迁移含 information_schema、NOT EXISTS 语义、tenant_id=1 和仅 NULL/blank 回填；XML 合法 |
未提供隔离 dev 数据库，未对用户本地库执行迁移；forge_schema_history 实库验证跳过 |
无服务启动 |
| 2026-07-10 | 前端生产构建 | source ~/.nvm/nvm.sh、nvm use 20.19.0、pnpm build |
Node v20.19.0；8485 modules transformed；Vite build SUCCESS，耗时 1m23s |
既有 UserSelectModal 重名、动态/静态 import、CSS // 注释和 bundle 体积警告 |
无服务启动 |
| 2026-07-10 | 可选公网 DashScope | 检查 AI_DASHSCOPE_API_KEY 是否存在 |
环境变量未设置，按 Test Spec 明确跳过真实同步/流式调用 | 不把无凭据/未调用写成通过；无费用产生 | 无服务启动 |
| 2026-07-10 | Review 修复复验 | mvn -Penable-tests -pl forge-framework/forge-plugin-parent/forge-plugin-ai -am test |
45 tests，Failures/Errors/Skipped 均为 0；24 模块 reactor BUILD SUCCESS | JVM CDS 与 spring-jcl/commons-logging 既有警告；无新增阻断 | 无服务启动 |
| 2026-07-10 | Task 8 静态收尾 | git diff --check；未跟踪路线图 git diff --no-index --check；test -f 路径检查；rg 状态/陈旧描述/未完成项检查 |
已跟踪差异无 whitespace 错误；路线图检查仅返回 no-index 差异码且无错误输出；关键路径存在；Spec/Test 均为 review，Task/Test 无未完成项 | 未执行外部写入或服务启动 | 无服务启动 |
| 2026-07-11 | /review 独立验证 |
AI 插件 -Penable-tests -am test；AI dependency:tree；Node 20.19.0 pnpm build；xmllint；Flyway placeholder/Starter/diff 扫描 |
45 tests、24 模块 reactor BUILD SUCCESS；Spring AI 1.1.2、DashScope Core 1.1.2.3；8485 modules、Vite build SUCCESS；静态检查通过 |
保留 JVM CDS、commons-logging、UserSelectModal、import/CSS/bundle 既有警告；公网 API Key/隔离 dev 库缺失项未扩展执行 | 无服务启动 |
| 2026-07-11 | 默认模型与页面增量 | Java 17 AI 定向/完整测试；mvn -pl forge-admin-server -am package -DskipTests；xmllint AiModelMapper.xml；Node 20 ESLint/build；Playwright 真实登录与页面检查 |
定向 21 tests、完整 51 tests、AI 24 模块 reactor、Admin 35 模块 package、ESLint、8485 modules build 均成功；真实页面 3 个视口无横向溢出，选择交互稳定，控制台无错误 | 未执行付费公网模型调用；沿用既有 Vite 构建警告；用户现有 8580 服务未停止 | Playwright 临时 5173 Vite 已停止 |
| 2026-07-11 | 最终静态收尾 | git diff --check；xmllint --noout .../AiModelMapper.xml；生产代码扫描 gpt-3.5-turbo；git status --short |
diff 和 XML 检查通过；GPT 通用兜底扫描无匹配；UI Skill 运行产生的 __pycache__ 已清理 |
工作区仍包含用户原有文档、vendor、Skill、.DS_Store 等改动，均未覆盖或清理 |
无服务启动 |
| 2026-07-11 | 供应商页面二次收敛 | 删除页面内导航文字；新增供应商改为列表标题栏图标按钮；模型名称与编码拆列；默认模型改为行内开关并保留当前默认标记；操作列只保留编辑/删除；页面上边距收紧 | 代码调整完成；切换其他模型时复用既有模型更新接口，关闭当前默认时阻止产生无默认模型配置 | 用户明确要求本轮不继续测试，由用户本地验收；未把中断的构建记录为通过 | 构建进程已停止，无服务启动 |
| 2026-07-11 | /archive 归档 |
核对四份变更文档、长期记忆、Review 结论、验证证据和跳过项；执行 git diff --check |
状态更新为 done；知识已沉淀到 decisions 16、pitfalls 104、preferences 10；归档路径固定为日期前缀目录 | 最终 UI 微调由用户自行验收；公网 DashScope/Flyway 实库验证继续按环境条件跳过；未推送 | 无服务启动 |
代码质量备忘
- Adapter Registry 必须检测重复 code，避免 Spring Bean 增加后静默覆盖；
AiClientImpl、ChatClientCache、AiProviderService最终不应包含具体供应商模型构造；- 缓存键和移除日志禁止出现 API Key 或可逆凭据；
- 连接测试异常必须清理供应商 SDK 可能携带的敏感请求信息后再返回；
- 活动供应商页面是
provider-model.vue，旧provider.vue不在本次扩展范围； - Maven 发布依赖与本地 vendor 源码必须保持相同 release，不使用 vendor 目录作为生产源码依赖。
Review 结论
- Spec Compliance：PASS；
- Code Quality：PASS，事务同步异常边缘分支已修复并复验；
- 安全与依赖：PASS，未发现密钥泄漏，未引入 DashScope Starter；
- 保留警告：JVM CDS、commons-logging、既有 deprecated/unchecked Java 警告和既有 Vite 组件/import/CSS/bundle 警告均不阻断；
- 保留跳过项：未提供
AI_DASHSCOPE_API_KEY，未执行付费公网模型调用；未提供隔离 dev 数据库，未实跑 Flyway； - 服务清理：本变更未启动后端或前端服务；
- 当前状态：done，已归档、未推送。
2026-07-11 独立复审补充
- 未发现 Critical 或 Important 问题；
- 非阻断建议 1：后续迁移可对已存在的
adapter_code列继续校验类型、默认值和 nullability，覆盖非标准半迁移数据库； - 非阻断建议 2：未来新增 Adapter 时，可把
testConnection的配置校验和网络调用放到不同异常边界，确保任何自定义 Adapter 的网络异常都统一安全化； - 最终结论为 Spec Compliance PASS / Code Quality PASS，已完成
/archive。