From 9f28498b97b94abf6f881227de3ac707672d40a5 Mon Sep 17 00:00:00 2001
From: MerCry <jiong1114>
Date: Tue, 10 Mar 2026 12:12:34 +0800
Subject: [PATCH] docs: add v0.9.0 retrieval embedding strategy spec
 [AC-DOCS-V0.9]

---
 .../openapi.provider.yaml                     | 196 ++++++++++++++++++
 .../requirements.md                           |   1 -
 2 files changed, 196 insertions(+), 1 deletion(-)
 create mode 100644 spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml

diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml
new file mode 100644
index 0000000..36cb31e
--- /dev/null
+++ b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml
@@ -0,0 +1,196 @@
+openapi: "3.0.3"
+info:
+  title: "AI Service Retrieval Strategy API"
+  version: "0.1.0"
+  description: "检索与嵌入策略配置/查询/验证接口"
+  x-contract-level: "L1"
+servers:
+  - url: "/"
+paths:
+  /strategy/retrieval/current:
+    get:
+      summary: "获取当前检索策略"
+      operationId: getCurrentRetrievalStrategy
+      tags:
+        - RetrievalStrategy
+      responses:
+        "200":
+          description: "当前策略"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetrievalStrategyStatus"
+      x-requirements:
+        - AC-AISVC-RES-01
+  /strategy/retrieval/switch:
+    post:
+      summary: "切换检索策略"
+      operationId: switchRetrievalStrategy
+      tags:
+        - RetrievalStrategy
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RetrievalStrategySwitchRequest"
+      responses:
+        "200":
+          description: "切换结果"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetrievalStrategySwitchResponse"
+      x-requirements:
+        - AC-AISVC-RES-02
+        - AC-AISVC-RES-03
+        - AC-AISVC-RES-05
+  /strategy/retrieval/validate:
+    post:
+      summary: "验证策略一致性"
+      operationId: validateRetrievalStrategy
+      tags:
+        - RetrievalStrategy
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RetrievalStrategyValidationRequest"
+      responses:
+        "200":
+          description: "校验结果"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetrievalStrategyValidationResponse"
+      x-requirements:
+        - AC-AISVC-RES-04
+        - AC-AISVC-RES-06
+        - AC-AISVC-RES-08
+  /strategy/retrieval/rollback:
+    post:
+      summary: "回退策略"
+      operationId: rollbackRetrievalStrategy
+      tags:
+        - RetrievalStrategy
+      responses:
+        "200":
+          description: "回退结果"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetrievalStrategyRollbackResponse"
+      x-requirements:
+        - AC-AISVC-RES-07
+components:
+  schemas:
+    RetrievalStrategyStatus:
+      type: object
+      required:
+        - active_strategy
+        - react_mode
+        - rollout
+      properties:
+        active_strategy:
+          type: string
+          description: "当前策略"
+          enum: ["default", "enhanced"]
+        react_mode:
+          type: string
+          description: "ReAct 模式"
+          enum: ["react", "non_react"]
+        rollout:
+          $ref: "#/components/schemas/RolloutConfig"
+    RolloutConfig:
+      type: object
+      required:
+        - mode
+      properties:
+        mode:
+          type: string
+          enum: ["off", "percentage", "allowlist"]
+        percentage:
+          type: number
+          minimum: 0
+          maximum: 100
+        allowlist:
+          type: array
+          items:
+            type: string
+    RetrievalStrategySwitchRequest:
+      type: object
+      required:
+        - target_strategy
+      properties:
+        target_strategy:
+          type: string
+          enum: ["default", "enhanced"]
+        react_mode:
+          type: string
+          enum: ["react", "non_react"]
+        rollout:
+          $ref: "#/components/schemas/RolloutConfig"
+        reason:
+          type: string
+    RetrievalStrategySwitchResponse:
+      type: object
+      required:
+        - previous
+        - current
+      properties:
+        previous:
+          $ref: "#/components/schemas/RetrievalStrategyStatus"
+        current:
+          $ref: "#/components/schemas/RetrievalStrategyStatus"
+    RetrievalStrategyValidationRequest:
+      type: object
+      required:
+        - strategy
+      properties:
+        strategy:
+          type: string
+          enum: ["default", "enhanced"]
+        react_mode:
+          type: string
+          enum: ["react", "non_react"]
+        checks:
+          type: array
+          items:
+            type: string
+            enum: ["metadata_consistency", "embedding_prefix", "rrf_config", "performance_budget"]
+    RetrievalStrategyValidationResponse:
+      type: object
+      required:
+        - passed
+        - results
+      properties:
+        passed:
+          type: boolean
+        results:
+          type: array
+          items:
+            $ref: "#/components/schemas/ValidationResult"
+    ValidationResult:
+      type: object
+      required:
+        - check
+        - passed
+      properties:
+        check:
+          type: string
+        passed:
+          type: boolean
+        message:
+          type: string
+    RetrievalStrategyRollbackResponse:
+      type: object
+      required:
+        - current
+        - rollback_to
+      properties:
+        current:
+          $ref: "#/components/schemas/RetrievalStrategyStatus"
+        rollback_to:
+          $ref: "#/components/schemas/RetrievalStrategyStatus"
+
diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md
index 2eb3fbb..1e3724d 100644
--- a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md
+++ b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md
@@ -67,4 +67,3 @@ source:
 | AC-AISVC-RES-06 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 校验结果 |
 | AC-AISVC-RES-07 | /strategy/retrieval/rollback | POST | rollbackRetrievalStrategy | 回退 |
 | AC-AISVC-RES-08 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 性能阈值 |
-