feat(agent): 技能用量 - 按用户运行日志统计检索与读取 (#590)

backend/internal/handler/agent.go

@@ -24,6 +24,21 @@ func RegisterAgentRoutes(r *gin.RouterGroup, svc *service.Service) {
 		capabilities := service.CloudAgentCapabilitySetInfo()
 		ok(c, gin.H{"version": 2, "permissionModes": []string{"read_only", "request_approval", "auto"}, "contextScopes": []string{"canvas"}, "skills": true, "writeTools": true, "billing": "fixed_request", "maxHistoryPairs": 10, "maxHistoryBytes": 64000, "maxSteps": 0, "tools": service.CloudAgentSupportedToolNames(), "capabilitySetVersion": capabilities.Version, "capabilitySetHash": capabilities.Hash, "nodeTypes": capabilities.Nodes})
 	})
+	// Skill usage is derived from the caller's own journal receipts, so it stays
+	// read-only and never exposes another user's runs.
+	r.GET("/agent/skills/usage", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		view, err := svc.CloudAgentSkillUsage(user.ID)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		ok(c, view)
+	})
 	// Profiles are durable preference data, not an authorization surface. The
 	// service validates scope ownership and the compiler injects the effective
 	// layers only after the code-level policy has been fixed.

backend/internal/handler/api_test.go

@@ -23,6 +23,7 @@ func TestRegisterCanvasAPIExposesOpenAPIAndProjects(t *testing.T) {
 		"POST /api/tasks/:id/recover-media": false,
 		"GET /api/resources":                false,
 		"GET /api/skills/presets":           false,
+		"GET /api/agent/skills/usage":       false,
 	}
 	for _, route := range router.Routes() {
 		key := route.Method + " " + route.Path

backend/internal/handler/openapi.yaml

@@ -412,6 +412,15 @@ paths:
       responses:
         "200":
           description: 信封 data 包含 version、permissionModes、contextScopes、skills、writeTools、billing、maxHistoryPairs、maxSteps、maxHistoryBytes、capabilitySetVersion、capabilitySetHash、nodeTypes、tools；maxHistoryPairs 为跨轮保留的用户对话轮数，maxSteps 为 0 表示无固定模型调用上限，历史仍受 maxHistoryBytes 限制
+  /agent/skills/usage:
+    get:
+      tags: [agent]
+      summary: 读取当前用户技能的使用统计（由运行日志聚合，只读）
+      responses:
+        "200":
+          description: 信封 data 含 scannedRuns、searchCalls 与按启用次数降序的 skills；每个技能含 runsEnabled、searchHits、readCalls、readFailures、entryReads、cardReads 与 topCards（最多 5 条最热卡路径）。统计仅覆盖调用方本人最近的运行，且不含任何技能正文
+        "401":
+          description: 未登录
   /agent/profile:
     get:
       tags: [agent]