feat(settings): add local model usage dashboard

docs/openapi.json

@@ -33554,6 +33554,100 @@
         "x-cyberagent-read-only": false
       }
     },
+    "/api/v1/usage": {
+      "get": {
+        "operationId": "getUsageStatistics",
+        "summary": "Inspect local application usage",
+        "description": "Aggregates this application's durable model terminal receipts across root agents, specialists, context compaction, and read-only fan-out; failed sent calls count and not-sent receipts are excluded. Tokens, model groups, recent Threads, sparse days, and untracked_calls use terminal receipt time. Cache tokens are input subsets; usage_reported_calls and cache_usage_reported_calls identify missing coverage. Missing provider/model identities remain empty strings. Costs use reservation settled_at independently of receipt time: known_cost_micros sums only actual priced USD settlements, unpriced_calls counts unknown-cost settlements, and untracked_calls counts receipts without a matched settlement. Reservation estimates never become known cost. Calendar dates use a fixed UTC offset; 30d includes today and the preceding 29 dates, all starts at the earliest receipt or settlement, and empty history starts today. The sparse activity_days always cover the last 182 calendar dates including today, independently of period. Collections are sorted deterministically; recent_sessions includes at most eight Threads with selected-period receipts and uses their latest receipt as last_activity_at. Unbound historical Runs contribute to totals and unassigned_calls.",
+        "tags": [
+          "System"
+        ],
+        "parameters": [
+          {
+            "name": "period",
+            "in": "query",
+            "description": "Calendar reporting period",
+            "schema": {
+              "default": "30d",
+              "enum": [
+                "today",
+                "30d",
+                "all"
+              ],
+              "type": "string"
+            }
+          },
+          {
+            "name": "utc_offset_minutes",
+            "in": "query",
+            "description": "Fixed UTC offset in minutes, without daylight-saving transitions",
+            "schema": {
+              "default": 0,
+              "maximum": 840,
+              "minimum": -840,
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful read",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/UsageStatistics"
+                    },
+                    "request_id": {
+                      "maxLength": 256,
+                      "minLength": 1,
+                      "type": "string"
+                    },
+                    "version": {
+                      "const": "api.v1",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "version",
+                    "request_id",
+                    "data"
+                  ],
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "414": {
+            "$ref": "#/components/responses/RequestTooLarge"
+          },
+          "429": {
+            "$ref": "#/components/responses/ResourceExhausted"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalError"
+          },
+          "503": {
+            "$ref": "#/components/responses/Unavailable"
+          },
+          "504": {
+            "$ref": "#/components/responses/GatewayTimeout"
+          }
+        },
+        "x-cyberagent-read-only": true
+      }
+    },
     "/api/v1/work-items/{work_item_id}": {
       "get": {
         "operationId": "getWorkItem",
@@ -72725,6 +72819,250 @@
         ],
         "type": "object"
       },
+      "UsageActivityDay": {
+        "additionalProperties": false,
+        "properties": {
+          "calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "date": {
+            "type": "string"
+          },
+          "total_tokens": {
+            "format": "int64",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "date",
+          "calls",
+          "total_tokens"
+        ],
+        "type": "object"
+      },
+      "UsageCost": {
+        "additionalProperties": false,
+        "properties": {
+          "currency": {
+            "type": "string"
+          },
+          "known_cost_micros": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "priced_calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "unpriced_calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "untracked_calls": {
+            "format": "int64",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "currency",
+          "known_cost_micros",
+          "priced_calls",
+          "unpriced_calls",
+          "untracked_calls"
+        ],
+        "type": "object"
+      },
+      "UsageDay": {
+        "additionalProperties": false,
+        "properties": {
+          "date": {
+            "type": "string"
+          },
+          "usage": {
+            "$ref": "#/components/schemas/UsageTotals"
+          }
+        },
+        "required": [
+          "date",
+          "usage"
+        ],
+        "type": "object"
+      },
+      "UsageModel": {
+        "additionalProperties": false,
+        "properties": {
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "usage": {
+            "$ref": "#/components/schemas/UsageTotals"
+          }
+        },
+        "required": [
+          "provider",
+          "model",
+          "usage"
+        ],
+        "type": "object"
+      },
+      "UsageSession": {
+        "additionalProperties": false,
+        "properties": {
+          "last_activity_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "thread_id": {
+            "maxLength": 256,
+            "minLength": 1,
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "usage": {
+            "$ref": "#/components/schemas/UsageTotals"
+          }
+        },
+        "required": [
+          "thread_id",
+          "title",
+          "last_activity_at",
+          "usage"
+        ],
+        "type": "object"
+      },
+      "UsageStatistics": {
+        "additionalProperties": false,
+        "properties": {
+          "activity_days": {
+            "items": {
+              "$ref": "#/components/schemas/UsageActivityDay"
+            },
+            "type": "array"
+          },
+          "activity_end_date": {
+            "type": "string"
+          },
+          "activity_start_date": {
+            "type": "string"
+          },
+          "cost": {
+            "$ref": "#/components/schemas/UsageCost"
+          },
+          "days": {
+            "items": {
+              "$ref": "#/components/schemas/UsageDay"
+            },
+            "type": "array"
+          },
+          "end_date": {
+            "type": "string"
+          },
+          "generated_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "models": {
+            "items": {
+              "$ref": "#/components/schemas/UsageModel"
+            },
+            "type": "array"
+          },
+          "period": {
+            "type": "string"
+          },
+          "recent_sessions": {
+            "items": {
+              "$ref": "#/components/schemas/UsageSession"
+            },
+            "type": "array"
+          },
+          "start_date": {
+            "type": "string"
+          },
+          "totals": {
+            "$ref": "#/components/schemas/UsageTotals"
+          },
+          "unassigned_calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "utc_offset_minutes": {
+            "format": "int32",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "generated_at",
+          "period",
+          "utc_offset_minutes",
+          "start_date",
+          "end_date",
+          "totals",
+          "cost",
+          "unassigned_calls",
+          "models",
+          "recent_sessions",
+          "days",
+          "activity_start_date",
+          "activity_end_date",
+          "activity_days"
+        ],
+        "type": "object"
+      },
+      "UsageTotals": {
+        "additionalProperties": false,
+        "properties": {
+          "cache_creation_tokens": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "cache_read_tokens": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "cache_usage_reported_calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "calls": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "input_tokens": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "output_tokens": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "total_tokens": {
+            "format": "int64",
+            "type": "integer"
+          },
+          "usage_reported_calls": {
+            "format": "int64",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "input_tokens",
+          "output_tokens",
+          "total_tokens",
+          "cache_read_tokens",
+          "cache_creation_tokens",
+          "calls",
+          "usage_reported_calls",
+          "cache_usage_reported_calls"
+        ],
+        "type": "object"
+      },
       "VerificationAssociationControlView": {
         "additionalProperties": false,
         "properties": {

docs/usage.md

@@ -40,6 +40,34 @@ false until that matrix is signed.
 
 ## Threads, Runs, and advanced diagnostics / Thread、Run 与高级诊断
 
+### 用量统计 / Usage
+
+在「设置 → 用量统计」查看 Universal-Code 自身的模型调用。今日、近 30 天和全部
+历史可切换 Token 总量、输入/输出/缓存明细、趋势、模型占比和最近八个会话；点击
+会话标题可回到对话。活动热图固定展示最近 26 周；悬停、点击或方向键选中格子时，
+白色边框标出当前日期，浮层显示日期和 Token 数，按 Esc 可关闭。页面沿用当前主题
+和 Mono 字体，中文与 English 即时切换。
+
+[深色页面](evidence/usage-statistics/usage-dark.png)和
+[窄屏页面](evidence/usage-statistics/usage-mobile.png)来自实际浏览器；截图中的用量为
+演示数据，用于检查图表与排版。
+
+Token 按持久化调用完成时间统计，包含主代理、子代理、并行调用、上下文压缩及
+已经产生用量的失败调用。缓存是输入 Token 的一部分；没有返回的用量和缓存明细
+会明确标注。日期按页面显示的当前 UTC 偏移划分，页面打开时每分钟更新。
+
+费用按实际结算时间统计，只展示已有完整价格记录的本地 USD 估算，并分别注明
+已定价、缺少完整计价和未记录费用的调用。未启用费用记录的历史调用不能据此推算
+真实账单。跨日结算与 Token 的日期可能不同，实际收费以供应商账单为准。
+
+`GET /api/v1/usage?period=30d&utc_offset_minutes=480` uses existing read access.
+`period` accepts `today`, `30d`, or `all`; the fixed UTC offset is in minutes.
+Only this application's durable local records are aggregated. The endpoint does
+not contact providers or inspect other applications' logs. Model token totals
+include all agent roles; cache tokens are already included in input. Costs use
+priced settlements, independently dated from call receipts. Missing usage and
+pricing remain visible through coverage counts.
+
 ### Markdown 输入与复制
 
 Web/Desktop 的输入框默认显示 Markdown 格式，支持标题、粗体、引用、列表、任务列表、