@lingya-ai/agents-sdk 0.3.0 → 0.5.0

package/dist/apis/ConversationsApi.d.ts

@@ -1,8 +1,8 @@
 /**
  * Lingya Agents OpenAPI
- * Public, tenant-scoped Agent channel API authenticated with OPENAPI-HMAC-SHA256-V1. Studio administration endpoints are not part of this contract.
+ * 本契约描述灵涯 Agents 面向可信服务端的公开渠道 API，使用 OPENAPI-HMAC-SHA256-V1 验证请求，不包含 Studio 管理接口。在线文档只展示请求，不会在浏览器中收集或保存 secret。  This contract describes the public Lingya Agents channel API for trusted servers. Requests use OPENAPI-HMAC-SHA256-V1, and Studio administration endpoints are excluded. The online reference only displays requests and never collects or stores a secret in the browser.  ## 快速开始 / Quick start  1. 读取 Configuration，确认模型和附件限制。 / Read Configuration to discover model and attachment limits.  2. 在本地固定最终 method、raw path、raw query、Content-Type 和 body 字节，再生成签名。 / Finalize method, raw path, raw query, Content-Type, and body bytes locally before signing.  3. 按业务分组调用接口；SSE 断开后使用 Events 补取。 / Call the appropriate business group and use Events for recovery after an SSE disconnect.  ## 公共错误 / Common errors  `401` 签名、时间戳或 nonce 无效；`403` 资源不属于当前渠道用户；`413` 请求体过大；`422` 参数校验失败；`429` 请求过于频繁；`500` 服务内部错误；`503` 依赖或执行服务暂不可用。  `401` invalid signature, timestamp, or nonce; `403` resource not owned by the current channel user; `413` request body too large; `422` validation failed; `429` rate limited; `500` internal error; `503` dependency or execution service unavailable.
  *
- * The version of the OpenAPI document: 0.1.2
+ * The version of the OpenAPI document: 0.1.5
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -10,7 +10,21 @@
  * Do not edit the class manually.
  */
 import * as runtime from '../runtime';
-import type { ConversationActivityBatchInput, ConversationActivityList, ConversationContextUsage, ConversationIds, ConversationReadReceipt, ConversationReadReceiptInput, ConversationShareCreated, ConversationShareInput, ConversationShareList, ConversationShareRevoked, ConversationStats, ConversationStatusInput, ConversationSummaryList, ConversationTitle, ConversationTitleInput } from '../models/index';
+import { type ConversationActivityBatchInput } from '../models/ConversationActivityBatchInput';
+import { type ConversationActivityList } from '../models/ConversationActivityList';
+import { type ConversationContextUsage } from '../models/ConversationContextUsage';
+import { type ConversationIds } from '../models/ConversationIds';
+import { type ConversationReadReceipt } from '../models/ConversationReadReceipt';
+import { type ConversationReadReceiptInput } from '../models/ConversationReadReceiptInput';
+import { type ConversationShareCreated } from '../models/ConversationShareCreated';
+import { type ConversationShareInput } from '../models/ConversationShareInput';
+import { type ConversationShareList } from '../models/ConversationShareList';
+import { type ConversationShareRevoked } from '../models/ConversationShareRevoked';
+import { type ConversationStats } from '../models/ConversationStats';
+import { type ConversationStatusInput } from '../models/ConversationStatusInput';
+import { type ConversationSummaryList } from '../models/ConversationSummaryList';
+import { type ConversationTitle } from '../models/ConversationTitle';
+import { type ConversationTitleInput } from '../models/ConversationTitleInput';
 export interface CreateConversationShareRequest {
     /**
      * Agent OpenAPI 渠道 UUID。 / Agent OpenAPI channel UUID.
@@ -192,12 +206,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     createConversationShareRequestOpts(requestParameters: CreateConversationShareRequest): Promise<runtime.RequestOpts>;
     /**
-     * 创建会话分享 / Create a conversation share 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 为会话创建受控的外部分享。  ### Use case Create controlled external sharing for a conversation.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 创建新的分享记录和分享码。  ### Behavior and side effects Creates a share record and share code.  ### 后续调用 安全地交付分享信息，并定期检查有效期。  ### Next step Deliver share information securely and monitor its expiry.  ### 接口摘要 创建会话分享 / Create a conversation share  ### Operation summary 创建会话分享 / Create a conversation share
      * 创建会话分享 / Create a conversation share
      */
     createConversationShareRaw(requestParameters: CreateConversationShareRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationShareCreated>>;
     /**
-     * 创建会话分享 / Create a conversation share 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 为会话创建受控的外部分享。  ### Use case Create controlled external sharing for a conversation.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 创建新的分享记录和分享码。  ### Behavior and side effects Creates a share record and share code.  ### 后续调用 安全地交付分享信息，并定期检查有效期。  ### Next step Deliver share information securely and monitor its expiry.  ### 接口摘要 创建会话分享 / Create a conversation share  ### Operation summary 创建会话分享 / Create a conversation share
      * 创建会话分享 / Create a conversation share
      */
     createConversationShare(requestParameters: CreateConversationShareRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationShareCreated>;
@@ -206,12 +220,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     deleteConversationRequestOpts(requestParameters: DeleteConversationRequest): Promise<runtime.RequestOpts>;
     /**
-     * 删除会话 / Delete a conversation 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 永久移除用户不再需要的会话。  ### Use case Permanently remove a conversation the user no longer needs.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 删除会话及其可见关联数据。  ### Behavior and side effects Deletes the conversation and its visible related data.  ### 后续调用 从本地列表和缓存中移除该会话。  ### Next step Remove the conversation from local lists and caches.  ### 接口摘要 删除会话 / Delete a conversation  ### Operation summary 删除会话 / Delete a conversation
      * 删除会话 / Delete a conversation
      */
     deleteConversationRaw(requestParameters: DeleteConversationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
     /**
-     * 删除会话 / Delete a conversation 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 永久移除用户不再需要的会话。  ### Use case Permanently remove a conversation the user no longer needs.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 删除会话及其可见关联数据。  ### Behavior and side effects Deletes the conversation and its visible related data.  ### 后续调用 从本地列表和缓存中移除该会话。  ### Next step Remove the conversation from local lists and caches.  ### 接口摘要 删除会话 / Delete a conversation  ### Operation summary 删除会话 / Delete a conversation
      * 删除会话 / Delete a conversation
      */
     deleteConversation(requestParameters: DeleteConversationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
@@ -220,12 +234,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     getConversationContextUsageRequestOpts(requestParameters: GetConversationContextUsageRequest): Promise<runtime.RequestOpts>;
     /**
-     * 读取上下文占用 / Get context usage 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 决定是否需要压缩上下文或提示容量时读取占用。  ### Use case Read context usage to decide whether to compact or warn about capacity.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 达到阈值时调用 compactConversation。  ### Next step Call compactConversation when the threshold is reached.  ### 接口摘要 读取上下文占用 / Get context usage  ### Operation summary 读取上下文占用 / Get context usage
      * 读取上下文占用 / Get context usage
      */
     getConversationContextUsageRaw(requestParameters: GetConversationContextUsageRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationContextUsage>>;
     /**
-     * 读取上下文占用 / Get context usage 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 决定是否需要压缩上下文或提示容量时读取占用。  ### Use case Read context usage to decide whether to compact or warn about capacity.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 达到阈值时调用 compactConversation。  ### Next step Call compactConversation when the threshold is reached.  ### 接口摘要 读取上下文占用 / Get context usage  ### Operation summary 读取上下文占用 / Get context usage
      * 读取上下文占用 / Get context usage
      */
     getConversationContextUsage(requestParameters: GetConversationContextUsageRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationContextUsage>;
@@ -234,12 +248,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     getConversationStatsRequestOpts(requestParameters: GetConversationStatsRequest): Promise<runtime.RequestOpts>;
     /**
-     * 读取会话统计 / Get conversation statistics 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 展示当前用户在渠道中的会话聚合统计。  ### Use case Display aggregate conversation statistics for the current user in the channel.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 用于仪表盘展示，不作为逐会话状态来源。  ### Next step Use for dashboards, not as per-conversation state.  ### 接口摘要 读取会话统计 / Get conversation statistics  ### Operation summary 读取会话统计 / Get conversation statistics
      * 读取会话统计 / Get conversation statistics
      */
     getConversationStatsRaw(requestParameters: GetConversationStatsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationStats>>;
     /**
-     * 读取会话统计 / Get conversation statistics 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 展示当前用户在渠道中的会话聚合统计。  ### Use case Display aggregate conversation statistics for the current user in the channel.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 用于仪表盘展示，不作为逐会话状态来源。  ### Next step Use for dashboards, not as per-conversation state.  ### 接口摘要 读取会话统计 / Get conversation statistics  ### Operation summary 读取会话统计 / Get conversation statistics
      * 读取会话统计 / Get conversation statistics
      */
     getConversationStats(requestParameters: GetConversationStatsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationStats>;
@@ -248,12 +262,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     getConversationTitleRequestOpts(requestParameters: GetConversationTitleRequest): Promise<runtime.RequestOpts>;
     /**
-     * 读取会话标题 / Get conversation title 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 读取自动生成或用户设置的会话标题。  ### Use case Read the generated or user-defined conversation title.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 生成中时稍后重试，或允许用户更新标题。  ### Next step Retry while generation is pending or let the user update the title.  ### 接口摘要 读取会话标题 / Get conversation title  ### Operation summary 读取会话标题 / Get conversation title
      * 读取会话标题 / Get conversation title
      */
     getConversationTitleRaw(requestParameters: GetConversationTitleRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationTitle>>;
     /**
-     * 读取会话标题 / Get conversation title 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 读取自动生成或用户设置的会话标题。  ### Use case Read the generated or user-defined conversation title.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 生成中时稍后重试，或允许用户更新标题。  ### Next step Retry while generation is pending or let the user update the title.  ### 接口摘要 读取会话标题 / Get conversation title  ### Operation summary 读取会话标题 / Get conversation title
      * 读取会话标题 / Get conversation title
      */
     getConversationTitle(requestParameters: GetConversationTitleRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationTitle>;
@@ -262,12 +276,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     listActiveConversationsRequestOpts(requestParameters: ListActiveConversationsRequest): Promise<runtime.RequestOpts>;
     /**
-     * 查询活动会话 / List active conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 快速恢复当前仍在执行的会话。  ### Use case Quickly recover conversations that are still executing.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回会话 ID。  ### Behavior and side effects Read-only and returns conversation IDs.  ### 后续调用 批量查询活动详情或重新连接 SSE。  ### Next step Batch-query activity details or reconnect SSE.  ### 接口摘要 查询活动会话 / List active conversations  ### Operation summary 查询活动会话 / List active conversations
      * 查询活动会话 / List active conversations
      */
     listActiveConversationsRaw(requestParameters: ListActiveConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationIds>>;
     /**
-     * 查询活动会话 / List active conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 快速恢复当前仍在执行的会话。  ### Use case Quickly recover conversations that are still executing.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回会话 ID。  ### Behavior and side effects Read-only and returns conversation IDs.  ### 后续调用 批量查询活动详情或重新连接 SSE。  ### Next step Batch-query activity details or reconnect SSE.  ### 接口摘要 查询活动会话 / List active conversations  ### Operation summary 查询活动会话 / List active conversations
      * 查询活动会话 / List active conversations
      */
     listActiveConversations(requestParameters: ListActiveConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationIds>;
@@ -276,12 +290,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     listConversationSharesRequestOpts(requestParameters: ListConversationSharesRequest): Promise<runtime.RequestOpts>;
     /**
-     * 查询会话分享 / List conversation shares 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 查看会话当前创建的分享记录。  ### Use case Inspect the conversation\'s current share records.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 按需创建新分享或撤销旧分享。  ### Next step Create a new share or revoke an existing one as needed.  ### 接口摘要 查询会话分享 / List conversation shares  ### Operation summary 查询会话分享 / List conversation shares
      * 查询会话分享 / List conversation shares
      */
     listConversationSharesRaw(requestParameters: ListConversationSharesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationShareList>>;
     /**
-     * 查询会话分享 / List conversation shares 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 查看会话当前创建的分享记录。  ### Use case Inspect the conversation\'s current share records.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 只读。  ### Behavior and side effects Read-only.  ### 后续调用 按需创建新分享或撤销旧分享。  ### Next step Create a new share or revoke an existing one as needed.  ### 接口摘要 查询会话分享 / List conversation shares  ### Operation summary 查询会话分享 / List conversation shares
      * 查询会话分享 / List conversation shares
      */
     listConversationShares(requestParameters: ListConversationSharesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationShareList>;
@@ -290,12 +304,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     listConversationsRequestOpts(requestParameters: ListConversationsRequest): Promise<runtime.RequestOpts>;
     /**
-     * 分页查询会话 / List conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 构建用户的分页会话列表与搜索结果。  ### Use case Build the user\'s paged conversation list and search results.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回分页记录。  ### Behavior and side effects Read-only and returns paged records.  ### 后续调用 按需读取标题、活动状态或消息。  ### Next step Read titles, activity, or messages as needed.  ### 接口摘要 分页查询会话 / List conversations  ### Operation summary 分页查询会话 / List conversations
      * 分页查询会话 / List conversations
      */
     listConversationsRaw(requestParameters: ListConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationSummaryList>>;
     /**
-     * 分页查询会话 / List conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 构建用户的分页会话列表与搜索结果。  ### Use case Build the user\'s paged conversation list and search results.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回分页记录。  ### Behavior and side effects Read-only and returns paged records.  ### 后续调用 按需读取标题、活动状态或消息。  ### Next step Read titles, activity, or messages as needed.  ### 接口摘要 分页查询会话 / List conversations  ### Operation summary 分页查询会话 / List conversations
      * 分页查询会话 / List conversations
      */
     listConversations(requestParameters: ListConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationSummaryList>;
@@ -304,12 +318,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     listUnreadConversationsRequestOpts(requestParameters: ListUnreadConversationsRequest): Promise<runtime.RequestOpts>;
     /**
-     * 查询未读会话 / List unread conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 显示存在未读完成结果的会话角标。  ### Use case Display conversations with unread completed results.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回未读会话 ID。  ### Behavior and side effects Read-only and returns unread conversation IDs.  ### 后续调用 读取消息后推进已读游标。  ### Next step Advance the read cursor after reading messages.  ### 接口摘要 查询未读会话 / List unread conversations  ### Operation summary 查询未读会话 / List unread conversations
      * 查询未读会话 / List unread conversations
      */
     listUnreadConversationsRaw(requestParameters: ListUnreadConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationIds>>;
     /**
-     * 查询未读会话 / List unread conversations 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 显示存在未读完成结果的会话角标。  ### Use case Display conversations with unread completed results.  ### 前置条件 外部用户已配置。  ### Prerequisites The external user is configured.  ### 行为与副作用 只读，返回未读会话 ID。  ### Behavior and side effects Read-only and returns unread conversation IDs.  ### 后续调用 读取消息后推进已读游标。  ### Next step Advance the read cursor after reading messages.  ### 接口摘要 查询未读会话 / List unread conversations  ### Operation summary 查询未读会话 / List unread conversations
      * 查询未读会话 / List unread conversations
      */
     listUnreadConversations(requestParameters: ListUnreadConversationsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationIds>;
@@ -318,12 +332,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     markConversationReadRequestOpts(requestParameters: MarkConversationReadRequest): Promise<runtime.RequestOpts>;
     /**
-     * 推进会话已读游标 / Mark a conversation as read 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 用户查看结果后推进会话已读位置。  ### Use case Advance a conversation\'s read position after the user views a result.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 更新已读游标，不删除消息。  ### Behavior and side effects Updates the read cursor without deleting messages.  ### 后续调用 刷新未读会话列表。  ### Next step Refresh the unread conversation list.  ### 接口摘要 推进会话已读游标 / Mark a conversation as read  ### Operation summary 推进会话已读游标 / Mark a conversation as read
      * 推进会话已读游标 / Mark a conversation as read
      */
     markConversationReadRaw(requestParameters: MarkConversationReadRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationReadReceipt>>;
     /**
-     * 推进会话已读游标 / Mark a conversation as read 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 用户查看结果后推进会话已读位置。  ### Use case Advance a conversation\'s read position after the user views a result.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 更新已读游标，不删除消息。  ### Behavior and side effects Updates the read cursor without deleting messages.  ### 后续调用 刷新未读会话列表。  ### Next step Refresh the unread conversation list.  ### 接口摘要 推进会话已读游标 / Mark a conversation as read  ### Operation summary 推进会话已读游标 / Mark a conversation as read
      * 推进会话已读游标 / Mark a conversation as read
      */
     markConversationRead(requestParameters: MarkConversationReadRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationReadReceipt>;
@@ -332,12 +346,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     queryConversationActivitiesRequestOpts(requestParameters: QueryConversationActivitiesRequest): Promise<runtime.RequestOpts>;
     /**
-     * 批量查询会话活动 / Query conversation activities 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 批量刷新多个会话的执行与未读状态。  ### Use case Refresh execution and unread state for multiple conversations in one request.  ### 前置条件 已持有最多 1000 个当前用户的会话 ID。  ### Prerequisites Up to 1000 conversation IDs for the current user are available.  ### 行为与副作用 只读，返回每个会话的活动投影。  ### Behavior and side effects Read-only and returns an activity projection per conversation.  ### 后续调用 更新列表状态并恢复必要的流。  ### Next step Update list state and recover any required streams.  ### 接口摘要 批量查询会话活动 / Query conversation activities  ### Operation summary 批量查询会话活动 / Query conversation activities
      * 批量查询会话活动 / Query conversation activities
      */
     queryConversationActivitiesRaw(requestParameters: QueryConversationActivitiesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationActivityList>>;
     /**
-     * 批量查询会话活动 / Query conversation activities 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 批量刷新多个会话的执行与未读状态。  ### Use case Refresh execution and unread state for multiple conversations in one request.  ### 前置条件 已持有最多 1000 个当前用户的会话 ID。  ### Prerequisites Up to 1000 conversation IDs for the current user are available.  ### 行为与副作用 只读，返回每个会话的活动投影。  ### Behavior and side effects Read-only and returns an activity projection per conversation.  ### 后续调用 更新列表状态并恢复必要的流。  ### Next step Update list state and recover any required streams.  ### 接口摘要 批量查询会话活动 / Query conversation activities  ### Operation summary 批量查询会话活动 / Query conversation activities
      * 批量查询会话活动 / Query conversation activities
      */
     queryConversationActivities(requestParameters: QueryConversationActivitiesRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationActivityList>;
@@ -346,12 +360,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     revokeConversationShareRequestOpts(requestParameters: RevokeConversationShareRequest): Promise<runtime.RequestOpts>;
     /**
-     * 撤销会话分享 / Revoke a conversation share 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 使不再需要的分享立即失效。  ### Use case Invalidate a share that is no longer needed.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 撤销指定分享，不删除原会话。  ### Behavior and side effects Revokes the selected share without deleting the conversation.  ### 后续调用 刷新分享列表并停止分发旧链接。  ### Next step Refresh the share list and stop distributing the old link.  ### 接口摘要 撤销会话分享 / Revoke a conversation share  ### Operation summary 撤销会话分享 / Revoke a conversation share
      * 撤销会话分享 / Revoke a conversation share
      */
     revokeConversationShareRaw(requestParameters: RevokeConversationShareRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ConversationShareRevoked>>;
     /**
-     * 撤销会话分享 / Revoke a conversation share 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 使不再需要的分享立即失效。  ### Use case Invalidate a share that is no longer needed.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 撤销指定分享，不删除原会话。  ### Behavior and side effects Revokes the selected share without deleting the conversation.  ### 后续调用 刷新分享列表并停止分发旧链接。  ### Next step Refresh the share list and stop distributing the old link.  ### 接口摘要 撤销会话分享 / Revoke a conversation share  ### Operation summary 撤销会话分享 / Revoke a conversation share
      * 撤销会话分享 / Revoke a conversation share
      */
     revokeConversationShare(requestParameters: RevokeConversationShareRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ConversationShareRevoked>;
@@ -360,12 +374,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     updateConversationStatusRequestOpts(requestParameters: UpdateConversationStatusRequest): Promise<runtime.RequestOpts>;
     /**
-     * 更新会话状态 / Update conversation status 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 归档、恢复或切换会话业务状态。  ### Use case Archive, restore, or otherwise change conversation business status.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 异步更新会话状态。  ### Behavior and side effects Updates conversation status asynchronously.  ### 后续调用 按新状态刷新会话列表。  ### Next step Refresh conversation lists using the new status.  ### 接口摘要 更新会话状态 / Update conversation status  ### Operation summary 更新会话状态 / Update conversation status
      * 更新会话状态 / Update conversation status
      */
     updateConversationStatusRaw(requestParameters: UpdateConversationStatusRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
     /**
-     * 更新会话状态 / Update conversation status 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 归档、恢复或切换会话业务状态。  ### Use case Archive, restore, or otherwise change conversation business status.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 异步更新会话状态。  ### Behavior and side effects Updates conversation status asynchronously.  ### 后续调用 按新状态刷新会话列表。  ### Next step Refresh conversation lists using the new status.  ### 接口摘要 更新会话状态 / Update conversation status  ### Operation summary 更新会话状态 / Update conversation status
      * 更新会话状态 / Update conversation status
      */
     updateConversationStatus(requestParameters: UpdateConversationStatusRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
@@ -374,12 +388,12 @@ export declare class ConversationsApi extends runtime.BaseAPI {
      */
     updateConversationTitleRequestOpts(requestParameters: UpdateConversationTitleRequest): Promise<runtime.RequestOpts>;
     /**
-     * 更新会话标题 / Update conversation title 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 保存用户编辑的会话标题。  ### Use case Save a user-edited conversation title.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 异步更新标题。  ### Behavior and side effects Updates the title asynchronously.  ### 后续调用 重新读取标题或刷新列表。  ### Next step Read the title again or refresh the list.  ### 接口摘要 更新会话标题 / Update conversation title  ### Operation summary 更新会话标题 / Update conversation title
      * 更新会话标题 / Update conversation title
      */
     updateConversationTitleRaw(requestParameters: UpdateConversationTitleRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
     /**
-     * 更新会话标题 / Update conversation title 请求会在身份验签和资源归属校验后执行；响应字段以本契约为准。 / The request runs after signature and resource-ownership validation; this contract defines the response fields.
+     * ### 使用场景 保存用户编辑的会话标题。  ### Use case Save a user-edited conversation title.  ### 前置条件 渠道凭证和外部用户已配置，目标资源属于当前用户。  ### Prerequisites Channel credentials and the external user are configured, and the target resource belongs to that user.  ### 行为与副作用 异步更新标题。  ### Behavior and side effects Updates the title asynchronously.  ### 后续调用 重新读取标题或刷新列表。  ### Next step Read the title again or refresh the list.  ### 接口摘要 更新会话标题 / Update conversation title  ### Operation summary 更新会话标题 / Update conversation title
      * 更新会话标题 / Update conversation title
      */
     updateConversationTitle(requestParameters: UpdateConversationTitleRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;