feat: establish v0.70 platform milestone

openapi/openapi.yaml

@@ -1,12 +1,41 @@
 openapi: 3.1.0
 info:
   title: 数据采集终端—云端系统 API
-  version: 0.68.0
+  version: 0.70.0
   description: 工程框架、SaaS核心业务、设备v2能力协商与智能体启动状态查询、首次通话就绪与最低固件门禁、背景资料准备失败闭环、活动通话授权撤回安全停止、语音内容闭环、终端终稿补传、批量设备遥测、录音上传队列、隐私对账、固件、双轨录音、状态事件、具体资源分享、受控运营配置、Agent组合组件引用、质量证据门禁、运营自定义版本族投放、新通话运行时冻结与供应商启动传递、带并发版本校验的配置投放暂停恢复、带严重度和验收证据门禁的联调问题闭环、含阻断告警定位、当前主机健康及生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警与模拟服务强制条件的发布候选技术验收快照、绑定候选版本与构建摘要并按业务时区生成的可审计试点日/周运行证据、可审计且不生成正式告警的接收器联通测试、外部依赖预检台账、证书到期清单，以及带价格版本冻结、供应商用量去重和硬额度控制的费用治理接口。
 servers:
   - url: http://localhost:58080
     description: 本地开发
 paths:
+  /internal/v1/tools/memory-search:
+    post:
+      operationId: searchInCallMemory
+      tags: [internal-tools]
+      security: [{ memoryToolBearer: [] }]
+      description: 仅供已绑定到当前s2s_hybrid通话的语音智能体调用；租户、长者、任务和有效期来自服务端签名令牌，请求正文不能指定这些边界。
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/MemoryToolSearchRequest' } } }
+      responses:
+        '200': { description: 受控长度的已确认记忆；Embedding临时不可用时返回degraded=true和空列表, content: { application/json: { schema: { $ref: '#/components/schemas/MemoryToolSearchResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '409': { $ref: '#/components/responses/ConflictError' }
+        '429': { description: 单通话记忆工具调用过于频繁 }
+        '503': { description: 记忆检索依赖暂时不可用, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+  /api/v1/ops/content-quality:
+    get:
+      operationId: getOpsContentQuality
+      tags: [operations]
+      security: [{ oidcBearer: [] }]
+      parameters:
+        - $ref: '#/components/parameters/RequiredTenantSelectionHeader'
+        - { name: model_ref, in: query, required: false, schema: { type: string, maxLength: 200 } }
+        - { name: prompt_version, in: query, required: false, schema: { type: string, maxLength: 80 } }
+      responses:
+        '200': { description: 按生成模型和提示词版本聚合的候选确认、修改、拒绝和质量问题类型, content: { application/json: { schema: { $ref: '#/components/schemas/ContentQualityListResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
   /api/v1/ops/config-versions:
     get:
       operationId: listOpsConfigVersions
@@ -611,6 +640,25 @@ paths:
         '400': { $ref: '#/components/responses/ValidationError' }
         '401': { $ref: '#/components/responses/AuthenticationError' }
         '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/ops/usage-overview:
+    get:
+      operationId: getOpsUsageOverview
+      tags: [operations, billing]
+      description: 运营人员查看客户组织整体通话时长与已核价费用，可按家庭和设备逐级筛选；不返回转写、录音或供应商内部编号。
+      security: [{ oidcBearer: [] }]
+      parameters:
+        - $ref: '#/components/parameters/RequiredTenantSelectionHeader'
+        - { name: from, in: query, required: true, schema: { type: string, format: date-time } }
+        - { name: to, in: query, required: true, schema: { type: string, format: date-time } }
+        - { name: timezone, in: query, required: false, schema: { type: string, default: Asia/Shanghai } }
+        - { name: household_id, in: query, required: false, schema: { type: string, format: uuid } }
+        - { name: device_id, in: query, required: false, schema: { type: string, format: uuid } }
+      responses:
+        '200': { description: 指定范围的通话时长、活动日、设备拆分、最近通话和可用费用汇总, content: { application/json: { schema: { $ref: '#/components/schemas/UsageOverviewResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { $ref: '#/components/responses/NotFoundError' }
   /api/v1/ops/alert-routing-policies:
     get:
       operationId: listOpsAlertRoutingPolicies
@@ -1047,6 +1095,23 @@ paths:
         '401': { $ref: '#/components/responses/AuthenticationError' }
         '403': { $ref: '#/components/responses/AccessDeniedError' }
         '409': { $ref: '#/components/responses/ConflictError' }
+  /api/v1/households/{id}/usage-overview:
+    get:
+      operationId: getFamilyUsageOverview
+      tags: [household, billing]
+      description: 家庭成员查看自己家庭的通话时长与已核价费用，可进一步筛选该家庭设备；服务端始终按登录成员关系限定家庭范围。
+      security: [{ oidcBearer: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
+        - { name: from, in: query, required: true, schema: { type: string, format: date-time } }
+        - { name: to, in: query, required: true, schema: { type: string, format: date-time } }
+        - { name: timezone, in: query, required: false, schema: { type: string, default: Asia/Shanghai } }
+        - { name: device_id, in: query, required: false, schema: { type: string, format: uuid } }
+      responses:
+        '200': { description: 当前家庭及可选设备范围内的通话时长与可用费用汇总, content: { application/json: { schema: { $ref: '#/components/schemas/UsageOverviewResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
         '412': { $ref: '#/components/responses/VersionConflictError' }
         '428': { $ref: '#/components/responses/PreconditionRequiredError' }
   /api/v1/households/{id}/invitations:
@@ -1362,6 +1427,95 @@ paths:
         '409':
           description: 绑定码无效、过期、撤销、用于其他目标，或设备已有有效绑定
           content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } }
+  /api/v1/ops/devices:
+    get:
+      operationId: listOpsDevices
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      description: 仅独立operator账号可读取；返回租户内全部设备及当前家庭、长者归属，不返回密钥明文。
+      responses:
+        '200': { description: 运维设备清单, content: { application/json: { schema: { $ref: '#/components/schemas/OpsDeviceListResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+    post:
+      operationId: createOpsDevice
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      description: 自动生成设备UUID和256位随机HMAC密钥；密钥明文仅在本响应出现一次。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CreateOpsDeviceRequest' } } } }
+      responses:
+        '201': { description: 设备及一次性密钥, content: { application/json: { schema: { $ref: '#/components/schemas/CreateOpsDeviceResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/ops/device-assignment-options:
+    get:
+      operationId: listOpsDeviceAssignmentOptions
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 可选家庭和长者, content: { application/json: { schema: { $ref: '#/components/schemas/OpsDeviceAssignmentOptionListResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/ops/devices/{id}:
+    parameters:
+      - { $ref: '#/components/parameters/ResourceID' }
+      - { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }
+    patch:
+      operationId: updateOpsDevice
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/IfMatchHeader' }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/UpdateOpsDeviceRequest' } } } }
+      responses:
+        '200': { description: 更新后的设备, content: { application/json: { schema: { $ref: '#/components/schemas/OpsDeviceResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '412': { $ref: '#/components/responses/VersionConflictError' }
+    delete:
+      operationId: deleteOpsDevice
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/IfMatchHeader' }]
+      description: 可审计软删除；吊销设备与凭据并关闭当前绑定，保留历史记录。
+      responses:
+        '200': { description: 已吊销设备, content: { application/json: { schema: { $ref: '#/components/schemas/OpsDeviceResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '412': { $ref: '#/components/responses/VersionConflictError' }
+  /api/v1/ops/devices/{id}/credentials/rotate:
+    parameters:
+      - { $ref: '#/components/parameters/ResourceID' }
+      - { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }
+    post:
+      operationId: rotateOpsDeviceCredential
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 轮换并只返回一次新密钥；旧密钥在事务提交后立即失效。
+      responses:
+        '201': { description: 一次性新密钥, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceCredentialIssueResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { description: 设备不存在, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+  /api/v1/ops/devices/{id}/claims:
+    parameters:
+      - { $ref: '#/components/parameters/ResourceID' }
+      - { $ref: '#/components/parameters/RequiredTenantSelectionHeader' }
+    post:
+      operationId: issueOpsDeviceClaim
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 为已登记且尚未绑定的设备生成24小时有效的一次性绑定码；旧的未使用绑定码同时撤销，明文仅在本响应出现一次。
+      responses:
+        '201': { description: 一次性设备绑定码, content: { application/json: { schema: { $ref: '#/components/schemas/DeviceClaimIssueResponse' } } } }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { description: 设备不存在, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '409': { description: 设备已绑定、已隔离或已吊销, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
   /api/v1/devices:
     get:
       operationId: listManagedDevices
@@ -1384,6 +1538,44 @@ paths:
           content: { application/json: { schema: { $ref: '#/components/schemas/ManagedDeviceResponse' } } }
         '401': { $ref: '#/components/responses/AuthenticationError' }
         '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/devices/{id}/binding-impact:
+    parameters: [{ $ref: '#/components/parameters/ResourceID' }]
+    get:
+      operationId: getDeviceBindingImpact
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 在解绑或转移前重新检查活动通话、未完成设备命令和进行中固件任务；返回当前绑定编号供正式操作做并发校验。
+      parameters:
+        - { name: action, in: query, required: true, schema: { type: string, enum: [unbind, transfer] } }
+        - { name: target_subject_id, in: query, required: false, schema: { type: string, format: uuid } }
+      responses:
+        '200':
+          description: 当前影响范围；allowed为false时不得提交绑定变更
+          headers: { Cache-Control: { schema: { type: string, const: no-store } } }
+          content: { application/json: { schema: { $ref: '#/components/schemas/DeviceBindingImpactResponse' } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/devices/{id}/binding-change:
+    parameters: [{ $ref: '#/components/parameters/ResourceID' }]
+    post:
+      operationId: changeDeviceBinding
+      tags: [device-management]
+      security: [{ oidcBearer: [] }]
+      description: 基于影响检查返回的绑定编号执行受控解绑或转移。旧绑定保留审计历史；转移会创建新的有效绑定。
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/ChangeDeviceBindingRequest' } } }
+      responses:
+        '200':
+          description: 绑定关系已变更
+          content: { application/json: { schema: { $ref: '#/components/schemas/DeviceBindingChangeResponse' } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409':
+          description: 影响范围存在阻断项，或当前绑定已在检查后发生变化
+          content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } }
   /api/v1/devices/{id}/presence:
     parameters: [{ $ref: '#/components/parameters/ResourceID' }]
     get:
@@ -1833,6 +2025,30 @@ paths:
         '409': { description: 缺少来源、缺少个性化记忆授权或审核状态冲突, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
         '412': { $ref: '#/components/responses/VersionConflictError' }
         '428': { $ref: '#/components/responses/PreconditionRequiredError' }
+  /api/v1/stories/{id}/facts/{fact_id}:
+    parameters:
+      - $ref: '#/components/parameters/ResourceID'
+      - { name: fact_id, in: path, required: true, schema: { type: string, format: uuid } }
+    patch:
+      operationId: updateFactCandidate
+      tags: [content-review]
+      security: [{ oidcBearer: [] }]
+      description: 单独编辑、确认、拒绝或停用一条事实候选；来源话轮和陈述依据不可由客户端改写。
+      parameters: [{ $ref: '#/components/parameters/IfMatchHeader' }]
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/UpdateFactCandidateRequest' } } }
+      responses:
+        '200':
+          description: 返回更新后的事实候选
+          headers: { ETag: { $ref: '#/components/headers/StrongETag' } }
+          content: { application/json: { schema: { $ref: '#/components/schemas/FactCandidateResponse' } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { $ref: '#/components/responses/AuthenticationError' }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '409': { description: 故事或事实候选状态不允许当前操作, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '412': { $ref: '#/components/responses/VersionConflictError' }
+        '428': { $ref: '#/components/responses/PreconditionRequiredError' }
   /api/v1/stories/{id}/reject:
     parameters: [{ $ref: '#/components/parameters/ResourceID' }]
     post:
@@ -1943,7 +2159,7 @@ paths:
         content: { application/json: { schema: { $ref: '#/components/schemas/CreatePrivacyRequest' } } }
       responses:
         '202':
-          description: 数据访问或主体删除申请已受理并进入后台处理；DELETE 会立即冻结主体。
+          description: 请求已受理。ACCESS和DELETE进入后台处理；CORRECTION与CONSENT_WITHDRAWAL在受理事务中完成并返回COMPLETED。
           content: { application/json: { schema: { $ref: '#/components/schemas/PrivacyRequestResponse' } } }
         '200':
           description: 幂等重放，返回原隐私请求。
@@ -2681,6 +2897,11 @@ components:
     oidcBearer:
       type: openIdConnect
       openIdConnectUrl: http://localhost:58180/realms/voice-local/.well-known/openid-configuration
+    memoryToolBearer:
+      type: http
+      scheme: bearer
+      bearerFormat: signed-conversation-token
+      description: Worker在启动s2s_hybrid任务时签发的短期令牌，固定绑定通话和供应商任务。
     deviceSignature:
       type: apiKey
       in: header
@@ -3897,6 +4118,82 @@ components:
       properties:
         request_id: { type: string }
         data: { $ref: '#/components/schemas/CostSummary' }
+    UsageOverviewScope:
+      type: object
+      additionalProperties: false
+      required: [tenant_id, tenant_name]
+      properties:
+        tenant_id: { type: string, format: uuid }
+        tenant_name: { type: string }
+        household_id: { type: string, format: uuid }
+        household_name: { type: string }
+        device_id: { type: string, format: uuid }
+        device_name: { type: string }
+    UsageOverviewDay:
+      type: object
+      additionalProperties: false
+      required: [date, duration_ms, conversation_count, cost_micros]
+      properties:
+        date: { type: string, format: date }
+        duration_ms: { type: integer, format: int64, minimum: 0 }
+        conversation_count: { type: integer, minimum: 0 }
+        cost_micros: { type: integer, format: int64, minimum: 0 }
+    UsageOverviewDevice:
+      type: object
+      additionalProperties: false
+      required: [id, name, household_id, household_name, duration_ms, conversation_count, cost_micros]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        household_id: { type: string, format: uuid }
+        household_name: { type: string }
+        duration_ms: { type: integer, format: int64, minimum: 0 }
+        conversation_count: { type: integer, minimum: 0 }
+        cost_micros: { type: integer, format: int64, minimum: 0 }
+    UsageOverviewConversation:
+      type: object
+      additionalProperties: false
+      required: [id, household_id, household_name, device_id, device_name, subject_name, status, started_at, duration_ms, cost_micros]
+      properties:
+        id: { type: string, format: uuid }
+        household_id: { type: string, format: uuid }
+        household_name: { type: string }
+        device_id: { type: string, format: uuid }
+        device_name: { type: string }
+        subject_name: { type: string }
+        status: { type: string }
+        started_at: { type: string, format: date-time }
+        ended_at: { type: string, format: date-time }
+        duration_ms: { type: integer, format: int64, minimum: 0 }
+        cost_micros: { type: integer, format: int64, minimum: 0 }
+    UsageOverview:
+      type: object
+      additionalProperties: false
+      required: [from, to, timezone, scope, total_duration_ms, today_duration_ms, conversation_count, average_duration_ms, active_days, current_streak_days, longest_streak_days, cost_micros, currency, cost_available, daily, devices, recent_conversations]
+      properties:
+        from: { type: string, format: date-time }
+        to: { type: string, format: date-time }
+        timezone: { type: string }
+        scope: { $ref: '#/components/schemas/UsageOverviewScope' }
+        total_duration_ms: { type: integer, format: int64, minimum: 0 }
+        today_duration_ms: { type: integer, format: int64, minimum: 0 }
+        conversation_count: { type: integer, minimum: 0 }
+        average_duration_ms: { type: integer, format: int64, minimum: 0 }
+        active_days: { type: integer, minimum: 0 }
+        current_streak_days: { type: integer, minimum: 0 }
+        longest_streak_days: { type: integer, minimum: 0 }
+        cost_micros: { type: integer, format: int64, minimum: 0 }
+        currency: { type: string, description: 没有已核价费用时为空字符串。 }
+        cost_available: { type: boolean }
+        daily: { type: array, items: { $ref: '#/components/schemas/UsageOverviewDay' } }
+        devices: { type: array, items: { $ref: '#/components/schemas/UsageOverviewDevice' } }
+        recent_conversations: { type: array, items: { $ref: '#/components/schemas/UsageOverviewConversation' } }
+    UsageOverviewResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/UsageOverview' }
     AlertCategory:
       type: string
       enum: [BUSINESS, TECHNICAL, SECURITY, COST]
@@ -4302,13 +4599,14 @@ components:
           items: { type: string }
     Account:
       type: object
-      required: [user_id, tenant_id, tenant_name, policy_version, platform_role, display_name, household_memberships]
+      required: [user_id, tenant_id, tenant_name, policy_version, platform_role, account_kind, display_name, household_memberships]
       properties:
         user_id: { type: string, format: uuid }
         tenant_id: { type: string, format: uuid }
         tenant_name: { type: string }
         policy_version: { type: string }
         platform_role: { type: string, enum: [customer, ops_viewer, ops_operator, ops_approver, ops_admin] }
+        account_kind: { type: string, enum: [customer, operator], description: 家庭账号和运维账号的强制身份边界。 }
         display_name: { type: string }
         household_memberships:
           type: array
@@ -4475,6 +4773,11 @@ components:
           type: array
           maxItems: 8
           items: { type: string, minLength: 1, maxLength: 50 }
+        avoided_topics:
+          type: array
+          maxItems: 8
+          description: 不希望智能体主动提及的话题；长者主动提及时先简短共情并自然转向，紧急安全响应不受此限制。
+          items: { type: string, minLength: 1, maxLength: 50 }
     ConversationReadinessCheck:
       type: object
       additionalProperties: false
@@ -4590,9 +4893,10 @@ components:
     ManagedDevice:
       type: object
       additionalProperties: false
-      required: [id, household_id, subject_id, subject_name, model, status, desired_revision, bound_at, registered_at, version]
+      required: [id, binding_id, household_id, subject_id, subject_name, model, status, desired_revision, bound_at, registered_at, version]
       properties:
         id: { type: string, format: uuid }
+        binding_id: { type: string, format: uuid, description: 当前有效绑定编号；解绑或转移时用于并发校验。 }
         household_id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
         subject_name: { type: string }
@@ -4608,6 +4912,158 @@ components:
         bound_at: { type: string, format: date-time }
         registered_at: { type: string, format: date-time }
         version: { type: integer, format: int64, minimum: 1 }
+    OpsDevice:
+      type: object
+      additionalProperties: false
+      required: [id, tenant_id, model, status, credential_status, key_version, registered_at, updated_at, version]
+      properties:
+        id: { type: string, format: uuid }
+        tenant_id: { type: string, format: uuid }
+        model: { type: string, minLength: 1, maxLength: 120 }
+        hardware_revision: { type: string, maxLength: 80 }
+        status: { type: string, enum: [registered, quarantined, revoked] }
+        minimum_security_version: { type: string, maxLength: 80 }
+        minimum_firmware_version: { type: string, maxLength: 80 }
+        household_id: { type: string, format: uuid }
+        household_name: { type: string }
+        subject_id: { type: string, format: uuid }
+        subject_name: { type: string }
+        credential_status: { type: string, enum: [active, revoked, missing] }
+        key_version: { type: integer, format: int64, minimum: 0 }
+        last_reported_at: { type: string, format: date-time }
+        registered_at: { type: string, format: date-time }
+        updated_at: { type: string, format: date-time }
+        version: { type: integer, format: int64, minimum: 1 }
+    OpsDeviceAssignmentOption:
+      type: object
+      additionalProperties: false
+      required: [household_id, household_name, subject_id, subject_name]
+      properties:
+        household_id: { type: string, format: uuid }
+        household_name: { type: string }
+        subject_id: { type: string, format: uuid }
+        subject_name: { type: string }
+    CreateOpsDeviceRequest:
+      type: object
+      additionalProperties: false
+      required: [model]
+      properties:
+        model: { type: string, minLength: 1, maxLength: 120 }
+        hardware_revision: { type: string, maxLength: 80 }
+        minimum_security_version: { type: string, maxLength: 80 }
+        minimum_firmware_version: { type: string, maxLength: 80 }
+        household_id: { type: string, format: uuid }
+        subject_id: { type: string, format: uuid }
+    UpdateOpsDeviceRequest:
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        model: { type: string, minLength: 1, maxLength: 120 }
+        hardware_revision: { type: string, maxLength: 80 }
+        minimum_security_version: { type: string, maxLength: 80 }
+        minimum_firmware_version: { type: string, maxLength: 80 }
+        status: { type: string, enum: [registered, quarantined] }
+        household_id: { type: string, format: uuid }
+        subject_id: { type: string, format: uuid }
+    DeviceCredentialIssue:
+      type: object
+      additionalProperties: false
+      required: [device_id, secret, key_version, issued_at]
+      properties:
+        device_id: { type: string, format: uuid }
+        secret: { type: string, pattern: '^[0-9a-f]{64}$', description: 仅本响应返回一次。 }
+        key_version: { type: integer, format: int64, minimum: 1 }
+        issued_at: { type: string, format: date-time }
+    DeviceClaimIssue:
+      type: object
+      additionalProperties: false
+      required: [device_id, claim_code, issued_at, expires_at]
+      properties:
+        device_id: { type: string, format: uuid }
+        claim_code: { type: string, minLength: 16, maxLength: 128, writeOnly: true, description: 仅本响应返回一次。 }
+        issued_at: { type: string, format: date-time }
+        expires_at: { type: string, format: date-time }
+    OpsDeviceResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/OpsDevice' }
+    OpsDeviceListResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { type: object, required: [items], properties: { items: { type: array, items: { $ref: '#/components/schemas/OpsDevice' } } } }
+    OpsDeviceAssignmentOptionListResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { type: object, required: [items], properties: { items: { type: array, items: { $ref: '#/components/schemas/OpsDeviceAssignmentOption' } } } }
+    CreateOpsDeviceResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { type: object, required: [device, credential], properties: { device: { $ref: '#/components/schemas/OpsDevice' }, credential: { $ref: '#/components/schemas/DeviceCredentialIssue' }, claim: { $ref: '#/components/schemas/DeviceClaimIssue' } } }
+    DeviceCredentialIssueResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/DeviceCredentialIssue' }
+    DeviceClaimIssueResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/DeviceClaimIssue' }
+    DeviceBindingImpact:
+      type: object
+      additionalProperties: false
+      required: [device_id, binding_id, action, source_household_id, source_subject_id, source_subject_name, pending_command_count, active_firmware_task_count, allowed, blockers, evaluated_at]
+      properties:
+        device_id: { type: string, format: uuid }
+        binding_id: { type: string, format: uuid }
+        action: { type: string, enum: [unbind, transfer] }
+        source_household_id: { type: string, format: uuid }
+        source_subject_id: { type: string, format: uuid }
+        source_subject_name: { type: string }
+        target_household_id: { type: string, format: uuid }
+        target_subject_id: { type: string, format: uuid }
+        target_subject_name: { type: string }
+        active_conversation_id: { type: string, format: uuid }
+        pending_command_count: { type: integer, minimum: 0 }
+        active_firmware_task_count: { type: integer, minimum: 0 }
+        allowed: { type: boolean }
+        blockers:
+          type: array
+          items: { type: string, enum: [target_subject_required, active_conversation, pending_device_commands, active_firmware_task] }
+        evaluated_at: { type: string, format: date-time }
+    ChangeDeviceBindingRequest:
+      type: object
+      additionalProperties: false
+      required: [action, expected_binding_id, reason, acknowledged]
+      properties:
+        action: { type: string, enum: [unbind, transfer] }
+        expected_binding_id: { type: string, format: uuid }
+        target_subject_id: { type: string, format: uuid, description: action为transfer时必填。 }
+        reason: { type: string, minLength: 3, maxLength: 300 }
+        acknowledged: { type: boolean, const: true }
+    DeviceBindingChangeResult:
+      type: object
+      additionalProperties: false
+      required: [device_id, action, previous_binding_id, changed_at]
+      properties:
+        device_id: { type: string, format: uuid }
+        action: { type: string, enum: [unbind, transfer] }
+        previous_binding_id: { type: string, format: uuid }
+        binding_id: { type: string, format: uuid }
+        household_id: { type: string, format: uuid }
+        subject_id: { type: string, format: uuid }
+        changed_at: { type: string, format: date-time }
     DevicePresence:
       type: object
       additionalProperties: false
@@ -5027,7 +5483,7 @@ components:
       additionalProperties: false
       required: [claim_code, household_id, subject_id]
       properties:
-        claim_code: { type: string, minLength: 16, maxLength: 128, writeOnly: true }
+        claim_code: { type: string, minLength: 16, maxLength: 128, writeOnly: true, description: 设备屏幕显示或维护端生成的一次性绑定码；不能填写设备公开UUID。 }
         household_id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
     DeviceClaimResult:
@@ -5175,6 +5631,18 @@ components:
         source_turn_ids: { type: array, minItems: 1, items: { type: string, format: uuid } }
         status: { type: string, enum: [CANDIDATE, CONFIRMED, REJECTED, SUPERSEDED] }
         version: { type: integer, format: int64, minimum: 1 }
+    UpdateFactCandidateRequest:
+      type: object
+      additionalProperties: false
+      minProperties: 2
+      required: [reason]
+      properties:
+        fact_type: { type: string, minLength: 1, maxLength: 64 }
+        content: { type: string, minLength: 1, maxLength: 4000 }
+        sensitivity: { type: string, enum: [normal, sensitive, high] }
+        status: { type: string, enum: [CANDIDATE, CONFIRMED, REJECTED, SUPERSEDED] }
+        error_type: { $ref: '#/components/schemas/ContentErrorType' }
+        reason: { type: string, minLength: 1, maxLength: 500 }
     Story:
       type: object
       additionalProperties: false
@@ -5200,7 +5668,7 @@ components:
     CuratedMemory:
       type: object
       additionalProperties: false
-      required: [id, subject_id, content, source_refs, status, sensitivity, version_no, version, confirmed_by, confirmed_at, index_status, created_at, updated_at]
+      required: [id, subject_id, content, source_refs, status, sensitivity, version_no, version, confirmed_by, confirmed_at, index_status, provider_index_status, created_at, updated_at]
       properties:
         id: { type: string, format: uuid }
         subject_id: { type: string, format: uuid }
@@ -5215,6 +5683,8 @@ components:
         change_reason: { type: string, maxLength: 500 }
         index_status: { type: string, enum: [PENDING, ACTIVE, STALE, FAILED, DELETED] }
         last_index_error: { type: string }
+        provider_index_status: { type: string, enum: [DISABLED, PENDING, ACTIVE, STALE, FAILED, DELETED] }
+        provider_index_error: { type: string }
         created_at: { type: string, format: date-time }
         updated_at: { type: string, format: date-time }
     ReviseStoryRequest:
@@ -5223,12 +5693,14 @@ components:
       required: [content, reason]
       properties:
         content: { type: string, minLength: 1, maxLength: 50000 }
+        error_type: { $ref: '#/components/schemas/ContentErrorType' }
         reason: { type: string, minLength: 1, maxLength: 500 }
     StoryDecisionRequest:
       type: object
       additionalProperties: false
       required: [reason]
       properties:
+        error_type: { $ref: '#/components/schemas/ContentErrorType' }
         reason: { type: string, minLength: 1, maxLength: 500 }
     UpdateMemoryRequest:
       type: object
@@ -5237,10 +5709,72 @@ components:
       properties:
         content: { type: string, minLength: 1, maxLength: 50000 }
         status: { type: string, enum: [ACTIVE, DISABLED] }
+        error_type: { $ref: '#/components/schemas/ContentErrorType' }
         reason: { type: string, minLength: 1, maxLength: 500 }
       anyOf:
         - required: [content]
         - required: [status]
+    ContentErrorType:
+      type: string
+      enum: [PERSON_ERROR, TIME_ERROR, PLACE_ERROR, RELATION_ERROR, OVER_INFERENCE, KEY_POINT_OMISSION, DUPLICATE_CONTENT, UNNATURAL_EXPRESSION, SENSITIVE_INFORMATION]
+    ContentQualitySummary:
+      type: object
+      additionalProperties: false
+      required: [model_ref, prompt_version, story_candidates, fact_candidates, confirmed, edited, rejected, disabled, error_types]
+      properties:
+        model_ref: { type: string }
+        prompt_version: { type: string }
+        story_candidates: { type: integer, format: int64, minimum: 0 }
+        fact_candidates: { type: integer, format: int64, minimum: 0 }
+        confirmed: { type: integer, format: int64, minimum: 0 }
+        edited: { type: integer, format: int64, minimum: 0 }
+        rejected: { type: integer, format: int64, minimum: 0 }
+        disabled: { type: integer, format: int64, minimum: 0 }
+        error_types: { type: object, additionalProperties: { type: integer, format: int64, minimum: 0 } }
+    ContentQualityListData:
+      type: object
+      additionalProperties: false
+      required: [items]
+      properties: { items: { type: array, items: { $ref: '#/components/schemas/ContentQualitySummary' } } }
+    ContentQualityListResponse:
+      type: object
+      additionalProperties: false
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/ContentQualityListData' }
+    MemoryToolSearchRequest:
+      type: object
+      additionalProperties: false
+      required: [query]
+      properties:
+        query: { type: string, minLength: 1, maxLength: 500 }
+        limit: { type: integer, minimum: 1, maximum: 5, default: 3 }
+    MemoryToolResult:
+      type: object
+      additionalProperties: false
+      required: [memory_id, memory_version_id, version_no, content, source_refs, relevance]
+      properties:
+        memory_id: { type: string, format: uuid }
+        memory_version_id: { type: string, format: uuid }
+        version_no: { type: integer, format: int64, minimum: 1 }
+        content: { type: string, maxLength: 241 }
+        source_refs: { type: array, items: { type: object, additionalProperties: true } }
+        relevance: { type: number }
+    MemoryToolSearchData:
+      type: object
+      additionalProperties: false
+      required: [items, degraded]
+      properties:
+        items: { type: array, maxItems: 5, items: { $ref: '#/components/schemas/MemoryToolResult' } }
+        degraded: { type: boolean }
+    MemoryToolSearchResponse:
+      type: object
+      additionalProperties: false
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/MemoryToolSearchData' }
     PrivacyCategory:
       type: string
       enum: [profile, consents, device_bindings, conversations, transcripts, summaries, stories, memories]
@@ -5249,7 +5783,7 @@ components:
       additionalProperties: false
       required: [request_type, scope]
       properties:
-        request_type: { type: string, enum: [ACCESS, DELETE] }
+        request_type: { type: string, enum: [ACCESS, CORRECTION, CONSENT_WITHDRAWAL, DELETE] }
         scope:
           type: object
           additionalProperties: false
@@ -5258,9 +5792,34 @@ components:
               type: array
               uniqueItems: true
               items: { $ref: '#/components/schemas/PrivacyCategory' }
+            consent_types:
+              type: array
+              minItems: 1
+              uniqueItems: true
+              items: { $ref: '#/components/schemas/ConsentType' }
+            corrections:
+              type: object
+              additionalProperties: false
+              minProperties: 1
+              properties:
+                preferred_name: { type: string, minLength: 1, maxLength: 120 }
+                language: { type: string, minLength: 2, maxLength: 20 }
+                timezone: { type: string, minLength: 1, maxLength: 100 }
+                profile_data: { type: object, additionalProperties: true }
+                conversation_preferences: { type: object, additionalProperties: true }
         reason: { type: string, minLength: 1, maxLength: 500, description: DELETE申请必填；正文不会持久化，仅保存摘要。 }
         confirmation: { type: string, minLength: 1, maxLength: 120, description: DELETE申请必填，必须与当前主体称呼完全一致且不会持久化。 }
       allOf:
+        - if:
+            properties: { request_type: { const: CORRECTION } }
+          then:
+            properties:
+              scope: { required: [corrections] }
+        - if:
+            properties: { request_type: { const: CONSENT_WITHDRAWAL } }
+          then:
+            properties:
+              scope: { required: [consent_types] }
         - if:
             properties: { request_type: { const: DELETE } }
           then:
@@ -5864,6 +6423,18 @@ components:
       properties:
         request_id: { type: string }
         data: { $ref: '#/components/schemas/ManagedDevice' }
+    DeviceBindingImpactResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/DeviceBindingImpact' }
+    DeviceBindingChangeResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/DeviceBindingChangeResult' }
     DeviceClaimResponse:
       type: object
       required: [request_id, data]
@@ -6062,6 +6633,12 @@ components:
       properties:
         request_id: { type: string }
         data: { $ref: '#/components/schemas/Story' }
+    FactCandidateResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/FactCandidate' }
     StoryListResponse:
       type: object
       required: [request_id, data]