2
0
Эх сурвалжийг харах

✨ (openapi): 新增 AI 对话、积分与管理统计的 v3 端点规格

由 openapi/scripts/generate.php 重新生成(lint 0 error):
- agent-traces、agent-charges(服务间)、agent-quota、credit-policy(公开)、me/reading-time
- me/agent-threads(列表、详情、改名、删除、存档)
- agent-feedback、agent-events(评价与隐式信号)
- admin/reading-stats、admin/agent-stats、admin/agent-runs(含 digest)、admin/agent-feedback

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
visuddhinanda 4 өдөр өмнө
parent
commit
5d682e761f
18 өөрчлөгдсөн 1761 нэмэгдсэн , 1 устгасан
  1. 35 1
      openapi/public/assets/protocol/main.yaml
  2. 119 0
      openapi/public/assets/protocol/resources/auto/v3-admin-agent-feedback.yaml
  3. 67 0
      openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs-digest.yaml
  4. 136 0
      openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs-run.yaml
  5. 184 0
      openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs.yaml
  6. 132 0
      openapi/public/assets/protocol/resources/auto/v3-admin-agent-stats.yaml
  7. 119 0
      openapi/public/assets/protocol/resources/auto/v3-admin-reading-stats.yaml
  8. 109 0
      openapi/public/assets/protocol/resources/auto/v3-agent-charges.yaml
  9. 60 0
      openapi/public/assets/protocol/resources/auto/v3-agent-events.yaml
  10. 33 0
      openapi/public/assets/protocol/resources/auto/v3-agent-feedback-message.yaml
  11. 106 0
      openapi/public/assets/protocol/resources/auto/v3-agent-feedback.yaml
  12. 63 0
      openapi/public/assets/protocol/resources/auto/v3-agent-quota.yaml
  13. 113 0
      openapi/public/assets/protocol/resources/auto/v3-agent-traces.yaml
  14. 48 0
      openapi/public/assets/protocol/resources/auto/v3-credit-policy.yaml
  15. 121 0
      openapi/public/assets/protocol/resources/auto/v3-me-agent-threads-thread-archive.yaml
  16. 189 0
      openapi/public/assets/protocol/resources/auto/v3-me-agent-threads-thread.yaml
  17. 76 0
      openapi/public/assets/protocol/resources/auto/v3-me-agent-threads.yaml
  18. 51 0
      openapi/public/assets/protocol/resources/auto/v3-me-reading-time.yaml

+ 35 - 1
openapi/public/assets/protocol/main.yaml

@@ -7,7 +7,7 @@ info:
 
     由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。
     响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
-  version: 2026.10.23
+  version: 2026.11.12
 servers:
   -
     url: /api
@@ -681,8 +681,34 @@ paths:
     $ref: ./resources/auto/v2-webhook.yaml
   '/v2/webhook/{webhook}':
     $ref: ./resources/auto/v2-webhook-webhook.yaml
+  /v3/admin/agent-feedback:
+    $ref: ./resources/auto/v3-admin-agent-feedback.yaml
+  /v3/admin/agent-runs:
+    $ref: ./resources/auto/v3-admin-agent-runs.yaml
+  /v3/admin/agent-runs/digest:
+    $ref: ./resources/auto/v3-admin-agent-runs-digest.yaml
+  '/v3/admin/agent-runs/{run}':
+    $ref: ./resources/auto/v3-admin-agent-runs-run.yaml
+  /v3/admin/agent-stats:
+    $ref: ./resources/auto/v3-admin-agent-stats.yaml
+  /v3/admin/reading-stats:
+    $ref: ./resources/auto/v3-admin-reading-stats.yaml
+  /v3/agent-charges:
+    $ref: ./resources/auto/v3-agent-charges.yaml
+  /v3/agent-events:
+    $ref: ./resources/auto/v3-agent-events.yaml
+  /v3/agent-feedback:
+    $ref: ./resources/auto/v3-agent-feedback.yaml
+  '/v3/agent-feedback/{message}':
+    $ref: ./resources/auto/v3-agent-feedback-message.yaml
   /v3/agent-grants:
     $ref: ./resources/auto/v3-agent-grants.yaml
+  /v3/agent-quota:
+    $ref: ./resources/auto/v3-agent-quota.yaml
+  /v3/agent-traces:
+    $ref: ./resources/auto/v3-agent-traces.yaml
+  /v3/credit-policy:
+    $ref: ./resources/auto/v3-credit-policy.yaml
   /v3/discussions:
     $ref: ./resources/auto/v3-discussions.yaml
   /v3/discussions/batch-count:
@@ -703,10 +729,18 @@ paths:
     $ref: ./resources/auto/v3-invites-invite.yaml
   /v3/me:
     $ref: ./resources/auto/v3-me.yaml
+  /v3/me/agent-threads:
+    $ref: ./resources/auto/v3-me-agent-threads.yaml
+  '/v3/me/agent-threads/{thread}':
+    $ref: ./resources/auto/v3-me-agent-threads-thread.yaml
+  '/v3/me/agent-threads/{thread}/archive':
+    $ref: ./resources/auto/v3-me-agent-threads-thread-archive.yaml
   /v3/me/reactions:
     $ref: ./resources/auto/v3-me-reactions.yaml
   '/v3/me/reactions/{reaction}':
     $ref: ./resources/auto/v3-me-reactions-reaction.yaml
+  /v3/me/reading-time:
+    $ref: ./resources/auto/v3-me-reading-time.yaml
   /v3/password-resets:
     $ref: ./resources/auto/v3-password-resets.yaml
   '/v3/password-resets/{token}':

+ 119 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-agent-feedback.yaml

@@ -0,0 +1,119 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-agent-feedback.yaml
+get:
+  summary: 列出评价
+  tags:
+    - admin
+  operationId: get_api_v3_admin_agent_feedback
+  description: |-
+    最新的在前,带对应提问的摘要与自动质量指标,便于判断问题在哪。不含账号身份。
+
+    实现:`V3\AdminAgentFeedbackController@index`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: per_page
+      in: query
+      schema:
+        type: integer
+        default: 20
+      description: '每页数量,最大 100'
+    -
+      name: 'filter[rating]'
+      in: query
+      schema:
+        type: string
+        enum:
+          - '1'
+          - '-1'
+      description: '1 赞 / -1 踩'
+    -
+      name: 'filter[tag]'
+      in: query
+      schema:
+        type: string
+      description: '按标签 / 原因筛'
+    -
+      name: 'filter[has_comment]'
+      in: query
+      schema:
+        type: boolean
+      description: 只看带文字说明的
+    -
+      name: from
+      in: query
+      schema:
+        type: string
+      description: 起始日(UTC,Y-m-d)
+    -
+      name: to
+      in: query
+      schema:
+        type: string
+      description: 结束日(UTC,Y-m-d,含当天)
+    -
+      name: page
+      in: query
+      schema:
+        type: integer
+        default: 1
+      description: 页码
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                    message_id:
+                      type: string
+                    rating:
+                      type: integer
+                    tags:
+                      type: array
+                      items: { type: string }
+                    comment:
+                      type: string
+                      nullable: true
+                    asked:
+                      type: boolean
+                    client:
+                      type: string
+                      nullable: true
+                    account_type:
+                      type: string
+                    updated_at:
+                      type: string
+                    run_id:
+                      type: string
+                      nullable: true
+                    question:
+                      type: string
+                      nullable: true
+                    route:
+                      type: string
+                      nullable: true
+                    status:
+                      type: string
+                      nullable: true
+                    deep:
+                      type: boolean
+                      nullable: true
+                    latency_ms:
+                      type: integer
+                      nullable: true
+              meta:
+                $ref: '../../main.yaml#/components/schemas/PaginationMeta'
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 67 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs-digest.yaml

@@ -0,0 +1,67 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-agent-runs-digest.yaml
+get:
+  summary: 分析用的精简导出
+  tags:
+    - admin
+  operationId: get_api_v3_admin_agent_runs_digest
+  description: |-
+    区间内允许用于改进回答(improve=true)的提问,最早的在前。不带任何身份(账号、设备、IP)。
+    每条给:问题、路由与把握度、检索词、状态与耗时、工具调用序列、用户评价、隐式信号计数、
+    同一会话里下一次提问隔了几秒;`full=true` 时再带回答、证据全文与引用,供 agent 评估回答质量
+    (服务端不做质量评估)。给 wikipali 插件的 `admin digest` 与分析技能用。
+
+    实现:`V3\AdminAgentRunController@digest`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: full
+      in: query
+      schema:
+        type: boolean
+        default: false
+      description: '是否带回答、证据全文与引用(此时 limit 最大 200)'
+    -
+      name: limit
+      in: query
+      schema:
+        type: integer
+        default: '500(full 时 100)'
+      description: '最多多少条,最大 2000(full 时 200)'
+    -
+      name: from
+      in: query
+      schema:
+        type: string
+        default: '今天往前 29 天'
+      description: 起始日(UTC,Y-m-d)
+    -
+      name: to
+      in: query
+      schema:
+        type: string
+        default: 今天
+      description: 结束日(UTC,Y-m-d,含当天)
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+              meta:
+                type: object
+                properties:
+                  has_more:
+                    type: boolean
+                    description: '区间内是否还有更多(超出 limit)'
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 136 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs-run.yaml

@@ -0,0 +1,136 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-agent-runs-run.yaml
+get:
+  summary: 查看一次提问的研究过程
+  tags:
+    - admin
+  operationId: get_api_v3_admin_agent_runs_run_
+  description: |-
+    带回答、给作答 LLM 的证据全文、计划、引用与全部步骤(LLM / 工具调用、节点事件)。
+
+    实现:`V3\AdminAgentRunController@show`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: run
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI runId(uuid)'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                  thread_id:
+                    type: string
+                    nullable: true
+                  thread_title:
+                    type: string
+                    nullable: true
+                  account_type:
+                    type: string
+                  user:
+                    type: object
+                    properties:
+                      id: { type: string }
+                      nickName: { type: string }
+                      userName: { type: string }
+                      realName: { type: string }
+                      sn: { type: integer }
+                      avatar: { type: string }
+                      roles: { type: array, items: { type: string } }
+                    nullable: true
+                  device_id:
+                    type: string
+                    nullable: true
+                  client_ip:
+                    type: string
+                    nullable: true
+                  client:
+                    type: string
+                    nullable: true
+                  app_version:
+                    type: string
+                    nullable: true
+                  question:
+                    type: string
+                  route:
+                    type: string
+                    nullable: true
+                  deep:
+                    type: boolean
+                  improve:
+                    type: boolean
+                  status:
+                    type: string
+                  latency_ms:
+                    type: integer
+                    nullable: true
+                  tokens_in:
+                    type: integer
+                    nullable: true
+                  tokens_out:
+                    type: integer
+                    nullable: true
+                  llm_calls:
+                    type: integer
+                  tool_calls:
+                    type: integer
+                  started_at:
+                    type: string
+                    nullable: true
+                  answer:
+                    type: string
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  evidence:
+                    type: string
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  plan:
+                    type: object
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  passage:
+                    type: object
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  citations:
+                    type: array
+                    items:
+                      type: object
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  error:
+                    type: string
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  model:
+                    type: string
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  prompt_version:
+                    type: string
+                    nullable: true
+                    description: 仅在部分查询口径下返回。
+                  steps:
+                    type: array
+                    items:
+                      type: object
+                      properties: { seq: { type: integer }, kind: { type: string }, name: { type: string, nullable: true }, args: { type: object, nullable: true }, result: { type: string, nullable: true }, result_chars: { type: integer, nullable: true }, tokens_in: { type: integer, nullable: true }, tokens_out: { type: integer, nullable: true }, ms: { type: integer, nullable: true }, error: { type: string, nullable: true } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 184 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-agent-runs.yaml

@@ -0,0 +1,184 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-agent-runs.yaml
+get:
+  summary: 列出提问
+  tags:
+    - admin
+  operationId: get_api_v3_admin_agent_runs
+  description: |-
+    最新的在前。提问原文对管理员可见;游客只显示设备匿名 id 与 IP。
+
+    实现:`V3\AdminAgentRunController@index`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: per_page
+      in: query
+      schema:
+        type: integer
+        default: 20
+      description: '每页数量,最大 100'
+    -
+      name: 'filter[status]'
+      in: query
+      schema:
+        type: string
+        enum:
+          - ok
+          - error
+          - cancelled
+          - denied
+      description: 运行结果
+    -
+      name: 'filter[route]'
+      in: query
+      schema:
+        type: string
+      description: '研究路径(question / term / passage / chat)'
+    -
+      name: 'filter[account_type]'
+      in: query
+      schema:
+        type: string
+        enum:
+          - user
+          - guest
+      description: 账号类型
+    -
+      name: 'filter[client]'
+      in: query
+      schema:
+        type: string
+        enum:
+          - mobile
+          - web
+      description: 客户端
+    -
+      name: 'filter[improve]'
+      in: query
+      schema:
+        type: boolean
+      description: 是否允许用于改进回答
+    -
+      name: 'filter[q]'
+      in: query
+      schema:
+        type: string
+      description: 按提问原文模糊搜索
+    -
+      name: page
+      in: query
+      schema:
+        type: integer
+        default: 1
+      description: 页码
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    run_id:
+                      type: string
+                    thread_id:
+                      type: string
+                      nullable: true
+                    thread_title:
+                      type: string
+                      nullable: true
+                    account_type:
+                      type: string
+                    user:
+                      type: object
+                      properties: { id: { type: string }, nickName: { type: string }, userName: { type: string }, realName: { type: string }, sn: { type: integer }, avatar: { type: string }, roles: { type: array, items: { type: string } } }
+                      nullable: true
+                    device_id:
+                      type: string
+                      nullable: true
+                    client_ip:
+                      type: string
+                      nullable: true
+                    client:
+                      type: string
+                      nullable: true
+                    app_version:
+                      type: string
+                      nullable: true
+                    question:
+                      type: string
+                    route:
+                      type: string
+                      nullable: true
+                    deep:
+                      type: boolean
+                    improve:
+                      type: boolean
+                    status:
+                      type: string
+                    latency_ms:
+                      type: integer
+                      nullable: true
+                    tokens_in:
+                      type: integer
+                      nullable: true
+                    tokens_out:
+                      type: integer
+                      nullable: true
+                    llm_calls:
+                      type: integer
+                    tool_calls:
+                      type: integer
+                    started_at:
+                      type: string
+                      nullable: true
+                    answer:
+                      type: string
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    evidence:
+                      type: string
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    plan:
+                      type: object
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    passage:
+                      type: object
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    citations:
+                      type: array
+                      items: { type: object }
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    error:
+                      type: string
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    model:
+                      type: string
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    prompt_version:
+                      type: string
+                      nullable: true
+                      description: 仅在部分查询口径下返回。
+                    steps:
+                      type: array
+                      items: { type: object, properties: { seq: { type: integer }, kind: { type: string }, name: { type: string, nullable: true }, args: { type: object, nullable: true }, result: { type: string, nullable: true }, result_chars: { type: integer, nullable: true }, tokens_in: { type: integer, nullable: true }, tokens_out: { type: integer, nullable: true }, ms: { type: integer, nullable: true }, error: { type: string, nullable: true } } }
+                      description: 仅在部分查询口径下返回。
+              meta:
+                $ref: '../../main.yaml#/components/schemas/PaginationMeta'
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 132 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-agent-stats.yaml

@@ -0,0 +1,132 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-agent-stats.yaml
+get:
+  summary: 'AI 对话统计'
+  tags:
+    - admin
+  operationId: get_api_v3_admin_agent_stats
+  description: |-
+    一次返回整页:指标(含上一同长区间作对比)、每日按研究路径的提问数与耗时分位数、
+    客户端分布、工具调用 Top、积分流水。结果缓存 10 分钟。
+
+    实现:`V3\AdminAgentStatsController@__invoke`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: from
+      in: query
+      schema:
+        type: string
+        default: '今天往前 29 天'
+      description: 起始日(UTC,Y-m-d)
+    -
+      name: to
+      in: query
+      schema:
+        type: string
+        default: 今天
+      description: 结束日(UTC,Y-m-d,含当天)
+    -
+      name: account_type
+      in: query
+      schema:
+        type: string
+        enum:
+          - all
+          - user
+          - guest
+        default: all
+      description: 账号类型
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  range:
+                    type: object
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      account_type: { type: string }
+                  summary:
+                    type: object
+                    properties:
+                      runs: { type: integer }
+                      deep: { type: integer }
+                      passage: { type: integer }
+                      denied: { type: integer }
+                      errors: { type: integer }
+                      cancelled: { type: integer }
+                      unchecked: { type: integer }
+                      improve: { type: integer }
+                      askers: { type: integer }
+                      askers_user: { type: integer }
+                      askers_guest: { type: integer }
+                      latency_p50_ms: { type: integer, nullable: true }
+                      latency_p95_ms: { type: integer, nullable: true }
+                      tokens_in: { type: integer }
+                      tokens_out: { type: integer }
+                      feedback_up: { type: integer }
+                      feedback_down: { type: integer }
+                      feedback_asked: { type: integer }
+                  previous:
+                    type: object
+                    properties:
+                      runs: { type: integer }
+                      deep: { type: integer }
+                      passage: { type: integer }
+                      denied: { type: integer }
+                      errors: { type: integer }
+                      cancelled: { type: integer }
+                      unchecked: { type: integer }
+                      improve: { type: integer }
+                      askers: { type: integer }
+                      askers_user: { type: integer }
+                      askers_guest: { type: integer }
+                      latency_p50_ms: { type: integer, nullable: true }
+                      latency_p95_ms: { type: integer, nullable: true }
+                      tokens_in: { type: integer }
+                      tokens_out: { type: integer }
+                      feedback_up: { type: integer }
+                      feedback_down: { type: integer }
+                      feedback_asked: { type: integer }
+                  daily:
+                    type: array
+                    items:
+                      type: object
+                      properties: { date: { type: string }, question: { type: integer }, term: { type: integer }, passage: { type: integer }, chat: { type: integer }, none: { type: integer }, denied: { type: integer }, errors: { type: integer }, latency_p50_ms: { type: integer, nullable: true }, latency_p95_ms: { type: integer, nullable: true }, feedback_up: { type: integer }, feedback_down: { type: integer } }
+                  clients:
+                    type: array
+                    items:
+                      type: object
+                      properties: { client: { type: string }, runs: { type: integer } }
+                  tools:
+                    type: array
+                    items:
+                      type: object
+                      properties: { name: { type: string }, calls: { type: integer }, errors: { type: integer }, avg_ms: { type: integer } }
+                  feedback_reasons:
+                    type: array
+                    items:
+                      type: object
+                      properties: { reason: { type: string }, count: { type: integer } }
+                  credits:
+                    type: object
+                    properties:
+                      spent_free: { type: integer }
+                      spent_earned: { type: integer }
+                      refunded: { type: integer }
+                      earned_reading: { type: integer }
+                      earned_editing: { type: integer }
+                      adjusted: { type: integer }
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 119 - 0
openapi/public/assets/protocol/resources/auto/v3-admin-reading-stats.yaml

@@ -0,0 +1,119 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-admin-reading-stats.yaml
+get:
+  summary: 阅读统计
+  tags:
+    - admin
+  operationId: get_api_v3_admin_reading_stats
+  description: |-
+    一次返回整页:指标(含上一同长区间作对比)、日活 / 月活、每日序列、热门章节、
+    三藏与根本·义注·复注分布、读经时长分布、读经积分。结果缓存 10 分钟。
+    口径:活跃读者来自阅读记录(recents,只有登录用户);读经时长只有 App;
+    章节浏览(views)含游客与搜索引擎爬虫。
+
+    实现:`V3\AdminReadingStatsController@__invoke`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: from
+      in: query
+      schema:
+        type: string
+        default: '今天往前 29 天'
+      description: 起始日(UTC,Y-m-d)
+    -
+      name: to
+      in: query
+      schema:
+        type: string
+        default: 今天
+      description: 结束日(UTC,Y-m-d,含当天)
+    -
+      name: client
+      in: query
+      schema:
+        type: string
+        enum:
+          - all
+          - web
+          - mobile
+        default: all
+      description: 客户端
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  range:
+                    type: object
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      client: { type: string }
+                  summary:
+                    type: object
+                    properties:
+                      active_readers: { type: integer }
+                      chapters_opened: { type: integer }
+                      reading_seconds: { type: integer, nullable: true }
+                      reading_users: { type: integer, nullable: true }
+                      page_views: { type: integer, nullable: true }
+                      dict_lookups: { type: integer }
+                  previous:
+                    type: object
+                    properties:
+                      active_readers: { type: integer }
+                      chapters_opened: { type: integer }
+                      reading_seconds: { type: integer, nullable: true }
+                      reading_users: { type: integer, nullable: true }
+                      page_views: { type: integer, nullable: true }
+                      dict_lookups: { type: integer }
+                  sticky:
+                    type: object
+                    properties:
+                      dau: { type: integer }
+                      mau: { type: integer }
+                  daily:
+                    type: array
+                    items:
+                      type: object
+                      properties: { date: { type: string }, readers_web: { type: integer }, readers_mobile: { type: integer }, reading_minutes: { type: integer }, page_views: { type: integer }, dict_lookups: { type: integer } }
+                  top_chapters:
+                    type: array
+                    items:
+                      type: object
+                      properties: { article_id: { type: string }, book: { type: integer }, paragraph: { type: integer }, title: { type: string }, collection: { type: string, nullable: true }, readers: { type: integer }, records: { type: integer } }
+                  pitaka_share:
+                    type: array
+                    items:
+                      type: object
+                      properties: { tag: { type: string }, records: { type: integer } }
+                  layer_share:
+                    type: array
+                    items:
+                      type: object
+                      properties: { tag: { type: string }, records: { type: integer } }
+                  duration_buckets:
+                    type: array
+                    items:
+                      type: object
+                      properties: { bucket: { type: string }, user_days: { type: integer } }
+                  reading_credits:
+                    type: object
+                    properties:
+                      credits: { type: integer }
+                      users: { type: integer }
+                      capped_user_days: { type: integer }
+                      clamped_ratio: { type: number }
+                    nullable: true
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 109 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-charges.yaml

@@ -0,0 +1,109 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-charges.yaml
+post:
+  summary: 为一次提问扣费(幂等)
+  tags:
+    - agent-charges
+  operationId: post_api_v3_agent_charges
+  description: |-
+    一次提问开始前由 agent 服务调用。先扣今日赠送,不够再扣积分余额;合计不够返回 402
+    (`type` 为 quota-exceeded,扩展字段 `reason`:insufficient 积分不足 / ip_cap 游客同 IP 超上限,
+    另带 `cost`、`free_remaining`、`earned_balance`)。
+    账号口径与 `POST /v3/agent-traces` 相同:Bearer 是透传的终端用户 token,
+    无效或缺省按游客算,此时 `device_id` 必填。按 run_id 幂等:首次 201,重复 200。
+    服务端出错、回答没生成时,写研究过程那一步会自动退回。
+
+    实现:`V3\AgentChargeController@store`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            run_id:
+              type: string
+              description: 'AG-UI runId(uuid)'
+            thread_id:
+              type: string
+              description: 'AG-UI threadId(uuid)。已经属于别的账号时 403,不扣费'
+            deep:
+              type: boolean
+              description: 是否深度思考(价格不同)
+              default: false
+            device_id:
+              type: string
+              description: '设备匿名 id(uuid)。游客必填'
+            client_ip:
+              type: string
+              description: '客户端 IP。只对游客用于同 IP 上限'
+          required:
+            - run_id
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                  cost:
+                    type: integer
+                  charged_free:
+                    type: integer
+                  charged_earned:
+                    type: integer
+                  free_remaining:
+                    type: integer
+                  earned_balance:
+                    type: integer
+                  policy_version:
+                    type: integer
+    201:
+      description: '首次扣费。响应体与 200 同形'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                  cost:
+                    type: integer
+                  charged_free:
+                    type: integer
+                  charged_earned:
+                    type: integer
+                  free_remaining:
+                    type: integer
+                  earned_balance:
+                    type: integer
+                  policy_version:
+                    type: integer
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    402:
+      description: '额度不足或游客同 IP 超上限'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
+    403:
+      description: 'thread_id 已经属于别的账号'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 60 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-events.yaml

@@ -0,0 +1,60 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-events.yaml
+post:
+  summary: 上报一条隐式信号
+  tags:
+    - agent-events
+  operationId: post_api_v3_agent_events
+  description: 实现:`V3\AgentEventController@store`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            message_id:
+              type: string
+              description: 'AG-UI 回答消息 id'
+            kind:
+              type: string
+              description: 信号
+              enum:
+                - copy
+                - citation_open
+                - regenerate
+                - ask_shown
+            device_id:
+              type: string
+              description: '设备匿名 id(uuid)。未登录时必填'
+            client:
+              type: string
+              description: 客户端
+              enum:
+                - mobile
+                - web
+          required:
+            - message_id
+            - kind
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  message_id:
+                    type: string
+                  kind:
+                    type: string
+                  created_at:
+                    type: string
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 33 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-feedback-message.yaml

@@ -0,0 +1,33 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-feedback-message.yaml
+delete:
+  summary: 撤回评价
+  tags:
+    - agent-feedback
+  operationId: delete_api_v3_agent_feedback_message_
+  description: |-
+    没评价过也返回 204(幂等)。
+
+    实现:`V3\AgentFeedbackController@destroy`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: message
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI 回答消息 id'
+    -
+      name: device_id
+      in: query
+      schema:
+        type: string
+      description: '设备匿名 id(uuid)。未登录时必填'
+  responses:
+    204:
+      description: 已撤回,无响应体
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 106 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-feedback.yaml

@@ -0,0 +1,106 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-feedback.yaml
+post:
+  summary: 评价一条回答(再次提交即更新)
+  tags:
+    - agent-feedback
+  operationId: post_api_v3_agent_feedback
+  description: |-
+    一人对一条回答只留一条:首次 201,更新 200。点赞的 tags 取 accurate / useful_citations / clear / inspiring,
+    点踩的 tags 是原因:citation_wrong / missed / off_topic / incorrect / too_long / too_academic / slow / other;
+    只有选了 other 时 comment 才会保存。asked=这条是被主动询问问出来的。
+
+    实现:`V3\AgentFeedbackController@store`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            message_id:
+              type: string
+              description: 'AG-UI 回答消息 id'
+            thread_id:
+              type: string
+              description: '会话 id(uuid)'
+            rating:
+              type: integer
+              description: '1 赞 / -1 踩(只能是这两个值)'
+            tags:
+              type: array
+              description: 点赞标签或点踩原因
+            comment:
+              type: string
+              description: '选了 other 时的文字说明,最长 1000 字'
+            asked:
+              type: boolean
+              description: 是否主动询问问出来的
+            device_id:
+              type: string
+              description: '设备匿名 id(uuid)。未登录时必填'
+            client:
+              type: string
+              description: 客户端
+              enum:
+                - mobile
+                - web
+          required:
+            - message_id
+            - rating
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  message_id:
+                    type: string
+                  rating:
+                    type: integer
+                  tags:
+                    type: array
+                    items:
+                      type: string
+                  comment:
+                    type: string
+                    nullable: true
+                  asked:
+                    type: boolean
+                  updated_at:
+                    type: string
+    201:
+      description: '首次评价。响应体与 200 同形'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  message_id:
+                    type: string
+                  rating:
+                    type: integer
+                  tags:
+                    type: array
+                    items:
+                      type: string
+                  comment:
+                    type: string
+                    nullable: true
+                  asked:
+                    type: boolean
+                  updated_at:
+                    type: string
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 63 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-quota.yaml

@@ -0,0 +1,63 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-quota.yaml
+get:
+  summary: '查看我的 AI 对话额度'
+  tags:
+    - agent-quota
+  operationId: get_api_v3_agent_quota
+  description: |-
+    可选登录:带 Bearer 看自己账号;游客带 `device_id`。登录用户读取时会顺带把今天(和昨天)
+    的读经、编辑时长结算成积分,所以读完马上就能看到到账。
+
+    实现:`V3\AgentQuotaController@__invoke`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: device_id
+      in: query
+      schema:
+        type: string
+      description: '设备匿名 id(uuid)。未登录时必填'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  account_type:
+                    type: string
+                  day:
+                    type: string
+                  resets_at:
+                    type: string
+                  policy_version:
+                    type: integer
+                  daily_free:
+                    type: integer
+                  free_used:
+                    type: integer
+                  free_remaining:
+                    type: integer
+                  earned_balance:
+                    type: integer
+                  cost:
+                    type: object
+                    properties:
+                      normal: { type: integer }
+                      deep: { type: integer }
+                  earned_today:
+                    type: object
+                    properties:
+                      reading: { type: integer }
+                      editing: { type: integer }
+                  earn:
+                    type: object
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 113 - 0
openapi/public/assets/protocol/resources/auto/v3-agent-traces.yaml

@@ -0,0 +1,113 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-agent-traces.yaml
+post:
+  summary: 写入一次提问的研究过程(幂等)
+  tags:
+    - agent-traces
+  operationId: post_api_v3_agent_traces
+  description: |-
+    请求头 `X-Agent-Service-Key` 证明调用方是 agent 服务;`Authorization: Bearer`
+    是 agent 透传的终端用户 token(可选):有效的人类 token 记到账号下,
+    没有 / 失效 / 是模型 token 都记为游客——此时 `device_id` 必填,并记 `client_ip`。
+    token 失效不拒绝,照样入库。
+    按 run_id 幂等:首次写入 201,重复提交返回已有记录 200,步骤不会重复写。
+
+    实现:`V3\AgentTraceController@store`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            run_id:
+              type: string
+              description: 'AG-UI runId(uuid)'
+            thread_id:
+              type: string
+              description: 'AG-UI threadId(uuid)'
+            device_id:
+              type: string
+              description: '设备匿名 id(uuid)。游客必填,登录用户忽略'
+            client_ip:
+              type: string
+              description: '客户端 IP。只对游客记录'
+            client:
+              type: string
+              description: 客户端
+              enum:
+                - mobile
+                - web
+            question:
+              type: string
+              description: 用户的提问
+            status:
+              type: string
+              description: 运行结果(denied=额度不足被拦下)
+              enum:
+                - ok
+                - error
+                - cancelled
+                - denied
+            improve:
+              type: boolean
+              description: 用户是否允许用于改进回答(提问那一刻的开关)
+              default: true
+            steps:
+              type: array
+              description: '每一步(LLM 调用、工具调用、节点事件),最多 500 条'
+          required:
+            - run_id
+            - thread_id
+            - question
+            - status
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                  thread_id:
+                    type: string
+                  account_type:
+                    type: string
+                  created_at:
+                    type: string
+    201:
+      description: '首次写入。响应体与 200 同形'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                  thread_id:
+                    type: string
+                  account_type:
+                    type: string
+                  created_at:
+                    type: string
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    403:
+      description: 'thread_id 已经属于别的账号'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 48 - 0
openapi/public/assets/protocol/resources/auto/v3-credit-policy.yaml

@@ -0,0 +1,48 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-credit-policy.yaml
+get:
+  summary: 查看当前的积分策略
+  tags:
+    - credit-policy
+  operationId: get_api_v3_credit_policy
+  description: |-
+    每天赠送多少、每次提问多少钱、读经和编辑怎么换积分。`version` 是生效日(YYYYMMDD),
+    也记在每笔积分流水里。「一天」按 UTC 算。
+
+    实现:`V3\CreditPolicyController@__invoke`
+  security:
+    - {  }
+    -
+      bearerAuth: []
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  version:
+                    type: integer
+                  day_timezone:
+                    type: string
+                  daily_free:
+                    type: object
+                    properties:
+                      guest: { type: integer }
+                      user: { type: integer }
+                  cost:
+                    type: object
+                    properties:
+                      normal: { type: integer }
+                      deep: { type: integer }
+                  guest_ip_daily_cap:
+                    type: integer
+                    nullable: true
+                  earn:
+                    type: object
+                    properties:
+                      reading: { type: object, properties: { credits_per_minute: { type: integer }, daily_cap: { type: integer, nullable: true } } }
+                      editing: { type: object, properties: { credits_per_minute: { type: integer }, daily_cap: { type: integer, nullable: true } } }

+ 121 - 0
openapi/public/assets/protocol/resources/auto/v3-me-agent-threads-thread-archive.yaml

@@ -0,0 +1,121 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-me-agent-threads-thread-archive.yaml
+put:
+  summary: 存档会话
+  tags:
+    - agent-threads
+  operationId: put_api_v3_me_agent_threads_thread_archive
+  description: |-
+    重复存档保留第一次的存档时间。返回更新后的会话。
+
+    实现:`V3\MeAgentThreadArchiveController@update`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: thread
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI threadId(uuid)'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  thread_id:
+                    type: string
+                  title:
+                    type: string
+                  client:
+                    type: string
+                    nullable: true
+                  archived_at:
+                    type: string
+                    nullable: true
+                  last_run_at:
+                    type: string
+                  created_at:
+                    type: string
+                  updated_at:
+                    type: string
+                  deleted_at:
+                    type: string
+                    nullable: true
+                  runs:
+                    type: array
+                    items:
+                      type: object
+                      properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'
+delete:
+  summary: 取消存档
+  tags:
+    - agent-threads
+  operationId: delete_api_v3_me_agent_threads_thread_archive
+  description: |-
+    返回更新后的会话(`archived_at` 为 null)。
+
+    实现:`V3\MeAgentThreadArchiveController@destroy`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: thread
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI threadId(uuid)'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  thread_id:
+                    type: string
+                  title:
+                    type: string
+                  client:
+                    type: string
+                    nullable: true
+                  archived_at:
+                    type: string
+                    nullable: true
+                  last_run_at:
+                    type: string
+                  created_at:
+                    type: string
+                  updated_at:
+                    type: string
+                  deleted_at:
+                    type: string
+                    nullable: true
+                  runs:
+                    type: array
+                    items:
+                      type: object
+                      properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 189 - 0
openapi/public/assets/protocol/resources/auto/v3-me-agent-threads-thread.yaml

@@ -0,0 +1,189 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-me-agent-threads-thread.yaml
+get:
+  summary: 查看一个会话
+  tags:
+    - agent-threads
+  operationId: get_api_v3_me_agent_threads_thread_
+  description: |-
+    带全部可见的问答轮次(runs),按提问先后排;被「重新生成」替换掉的轮次不返回。
+
+    实现:`V3\MeAgentThreadController@show`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: thread
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI threadId(uuid)'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  thread_id:
+                    type: string
+                  title:
+                    type: string
+                  client:
+                    type: string
+                    nullable: true
+                  archived_at:
+                    type: string
+                    nullable: true
+                  last_run_at:
+                    type: string
+                  created_at:
+                    type: string
+                  updated_at:
+                    type: string
+                  deleted_at:
+                    type: string
+                    nullable: true
+                  runs:
+                    type: array
+                    items:
+                      type: object
+                      properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'
+delete:
+  summary: 删除会话
+  tags:
+    - agent-threads
+  operationId: delete_api_v3_me_agent_threads_thread_
+  description: |-
+    软删:从我的历史里消失,服务器保留到期(默认 180 天)后彻底清除,期间用于防滥用。
+    返回软删后的会话本身(200,`deleted_at` 非空),不是 204。
+
+    实现:`V3\MeAgentThreadController@destroy`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: thread
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI threadId(uuid)'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  thread_id:
+                    type: string
+                  title:
+                    type: string
+                  client:
+                    type: string
+                    nullable: true
+                  archived_at:
+                    type: string
+                    nullable: true
+                  last_run_at:
+                    type: string
+                  created_at:
+                    type: string
+                  updated_at:
+                    type: string
+                  deleted_at:
+                    type: string
+                    nullable: true
+                  runs:
+                    type: array
+                    items:
+                      type: object
+                      properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'
+patch:
+  summary: 修改会话(目前只有标题)
+  tags:
+    - agent-threads
+  operationId: patch_api_v3_me_agent_threads_thread_
+  description: 实现:`V3\MeAgentThreadController@update`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: thread
+      in: path
+      required: true
+      schema:
+        type: string
+      description: 'AG-UI threadId(uuid)'
+  requestBody:
+    required: false
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            title:
+              type: string
+              description: '会话标题,1–255 字'
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  thread_id:
+                    type: string
+                  title:
+                    type: string
+                  client:
+                    type: string
+                    nullable: true
+                  archived_at:
+                    type: string
+                    nullable: true
+                  last_run_at:
+                    type: string
+                  created_at:
+                    type: string
+                  updated_at:
+                    type: string
+                  deleted_at:
+                    type: string
+                    nullable: true
+                  runs:
+                    type: array
+                    items:
+                      type: object
+                      properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } }
+                    description: 仅在部分查询口径下返回。
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 76 - 0
openapi/public/assets/protocol/resources/auto/v3-me-agent-threads.yaml

@@ -0,0 +1,76 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-me-agent-threads.yaml
+get:
+  summary: 列出我的会话
+  tags:
+    - agent-threads
+  operationId: get_api_v3_me_agent_threads
+  description: |-
+    最近提问的在前,不含已删除的。
+
+    实现:`V3\MeAgentThreadController@index`
+  security:
+    -
+      bearerAuth: []
+  parameters:
+    -
+      name: per_page
+      in: query
+      schema:
+        type: integer
+        default: 30
+      description: '每页数量,最大 100'
+    -
+      name: 'filter[archived]'
+      in: query
+      schema:
+        type: boolean
+      description: 只看已存档(true)或未存档(false)的;不传则全部
+    -
+      name: page
+      in: query
+      schema:
+        type: integer
+        default: 1
+      description: 页码
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    thread_id:
+                      type: string
+                    title:
+                      type: string
+                    client:
+                      type: string
+                      nullable: true
+                    archived_at:
+                      type: string
+                      nullable: true
+                    last_run_at:
+                      type: string
+                    created_at:
+                      type: string
+                    updated_at:
+                      type: string
+                    deleted_at:
+                      type: string
+                      nullable: true
+                    runs:
+                      type: array
+                      items: { type: object, properties: { run_id: { type: string }, question: { type: string }, answer: { type: string, nullable: true }, citations: { type: array, items: { type: object }, nullable: true }, deep: { type: boolean }, status: { type: string }, user_message_id: { type: string, nullable: true }, assistant_message_id: { type: string, nullable: true }, created_at: { type: string } } }
+                      description: 仅在部分查询口径下返回。
+              meta:
+                $ref: '../../main.yaml#/components/schemas/PaginationMeta'
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'

+ 51 - 0
openapi/public/assets/protocol/resources/auto/v3-me-reading-time.yaml

@@ -0,0 +1,51 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-me-reading-time.yaml
+post:
+  summary: 上报一段读经时长
+  tags:
+    - reading-time
+  operationId: post_api_v3_me_reading_time
+  description: |-
+    客户端在阅读器前台、且最近有滚动或翻页时计时,每 5 分钟或切后台时上报一次。
+    服务端按墙钟时间核减(当天计入的不超过距上次上报经过的时间),单日不超过 24 小时;
+    断网补报可带 `day`,最多 2 天前。返回这一天累计计入的秒数。
+
+    实现:`V3\MeReadingTimeController@store`
+  security:
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            seconds:
+              type: integer
+              description: 这段的读经秒数,1–900
+            day:
+              type: string
+              description: '归属的 UTC 日(Y-m-d),缺省为今天。断网补报用'
+          required:
+            - seconds
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  day:
+                    type: string
+                  seconds:
+                    type: integer
+                  updated_at:
+                    type: string
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'