V2 shared 路线防跑偏核查

日期：2026-06-22

1. 核查结论

当前 V2 方向总体没有跑偏。

现有方案已经明确不继续维护旧 shared-ai-platform、shared-ai-platform-java、shared-ai-python-sdk、backend/vendor/shared-ai-platform-sdk 这套历史结构，并且已经把新 shared 形态收敛为：

合同产品平台
统一 AI 中台
正式 SDK
统一基础设施

本次补强了主方案中的最终工程命名，并已把当前代码目录调整为：

yuqei-contract-platform
yuqei-ai-platform
yuqei-ai-sdk-python
yuqei-infra

V2 不再采用临时混放路线。当前根目录已经按这四个最终工程组织。

2. 已核查文档

project-docs/AI合同平台V2重构版开发方案-2026-06-22.md
project-docs/AI合同平台V2与共享AI重构任务编排-2026-06-22.md
project-docs/V2旧shared资产盘点与迁移清单-2026-06-22.md
docs/adr/0001-v2-technology-stack.md
README.md
V2-README.md

3. 当前代码路线对照

目标边界	当前代码位置	当前状态
`yuqei-contract-platform`	`yuqei-contract-platform/apps/contract-web`、`yuqei-contract-platform/services/contract-api`、`yuqei-contract-platform/packages/contract-openapi`	已建立 V2 前端壳、合同 API、合同 OpenAPI；合同 API 通过 SDK 调 AI。
`yuqei-ai-platform`	`yuqei-ai-platform/services/ai-platform-api`、`yuqei-ai-platform/packages/ai-openapi`	已建立模型配置、知识文档检索、法律问答、AI run audit 的 MVP。
`yuqei-ai-sdk-python`	`yuqei-ai-sdk-python`	已有 `AiPlatformClient` 和法律问答调用闭环；后续扩展合同审查、生成、改写、履约义务提取。
`yuqei-infra`	`yuqei-infra/compose`、`yuqei-infra/docker`、`yuqei-infra/nginx`、`yuqei-infra/observability`、`yuqei-infra/backup`、`yuqei-infra/deploy`	已建立基础目录和本地 compose 底座；后续补 OpenTelemetry、备份、发布脚本和生产环境模板。

4. 旧 shared 处理状态

旧模块	当前判断	后续动作
`shared-ai-platform-java`	不作为未来主线	冻结为行为对照和接口参考；不新增 V2 功能。
`shared-ai-platform`	不作为生产 AI 中台	只保留文档、原型和数据处理经验。
`shared-ai-python-sdk`	SDK 定位有价值，但实现重做	以 `yuqei-ai-sdk-python` 为正式 SDK 主线。
`shared-java-libs`	V2 不采用 Java 主线	归档参考。
`backend/vendor/shared-ai-platform-sdk`	不应恢复	合同系统不得再内置 SDK 副本。

5. 代码核查结果

当前 main 分支已经是 V2 主线。
当前目录没有发现 backend/vendor/shared-ai-platform-sdk。
当前代码没有发现旧 shared-ai-platform、shared-ai-platform-java、shared-java-libs 的生产依赖。
yuqei-contract-platform/services/contract-api 通过 yuqei_sdk.AiPlatformClient 调用 AI 中台，没有直接写模型 provider 适配。
yuqei-ai-platform/services/ai-platform-api 正在承接模型配置、知识库检索、法律问答、AI 审计能力。
yuqei-ai-platform/packages/ai-openapi 已描述 AI 中台 API 边界。
yuqei-contract-platform/packages/contract-openapi 已声明 Contract API 只能通过 SDK/OpenAPI client 调 AI Platform。

6. 仍需注意的风险

TypeScript SDK 还没有正式实现；后续如果前端或 Node 服务确实需要直接调用 AI 中台，应新建 yuqei-ai-sdk-typescript，不要恢复 sdks/* 旧式结构。
yuqei-ai-platform/services/ai-platform-api 目前还是 MVP，知识库和审计主要是内存实现，后续必须落数据库、迁移脚本和权限。
OpenTelemetry、费用统计、模型耗时拆解还没有完成，不能把当前 MVP 当成最终可观测能力。
Temporal 或同类 durable workflow 还未接入，长流程任务需要先用清晰接口预留边界。
后续开发中只要出现“为了方便在合同 API 里直接拼 Prompt 或查知识库”的需求，必须回退到 AI 中台边界重新设计。

7. 下一步建议

继续按这条路线推进，不要再回到旧 shared 多仓结构。

优先顺序：

AI Platform 数据持久化：provider config、prompt template、knowledge document、ai run audit。
OpenAPI 生成和 SDK 契约测试，让 yuqei-ai-sdk-python 真正成为稳定调用边界。
法律审查、合同生成、条款改写、履约义务提取进入 AI 中台，而不是合同 API。
合同系统继续做企业合同主流程：工作台、合同房间、审批、台账、仓库、审计。
infra 补环境模板、健康检查、监控日志、备份和发布脚本。

4.6 KiB Raw Blame History