feat: Add usage field support to workflow interfaces

- Add usage field to workflow run interface (RunWorkflowResp, WorkflowRunResult)
- Add usage field to workflow stream_run interface (WorkflowEventMessage)
- Add usage field to workflow get history interface (WorkflowRunHistory)
- Update test cases to verify usage field functionality
- Follow same pattern as existing ChatUsage class
- Align with Python and Go SDK implementations

Usage field provides token consumption information:
- token_count: Total tokens used
- input_count: Tokens used for input
- output_count: Tokens used for output

Fixes: Support for usage field in workflow APIs as per API documentation

Author: chyroc

.gitignore

@@ -39,4 +39,8 @@ replay_pid*
 
 # BlueJ files
 *.ctxt
-**/target
+**/target
+
+# ai
+.serena/
+CLAUDE.md

api/pom.xml

@@ -43,7 +43,7 @@
     </parent>
 
     <artifactId>coze-api</artifactId>
-    <version>0.4.1</version>
+    <version>0.5.0</version>
 
     <scm>
         <connection>scm:git:git://github.com/coze-dev/coze-java.git</connection>

api/src/main/java/com/coze/openapi/client/workflows/run/RunWorkflowResp.java

@@ -1,5 +1,6 @@
 package com.coze.openapi.client.workflows.run;
 
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.coze.openapi.client.common.BaseResponse;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
@@ -36,4 +37,8 @@ public class RunWorkflowResp extends BaseResponse<String> {
 
   @JsonProperty("cost")
   private String cost;
+
+  /** Token usage information for the workflow execution. */
+  @JsonProperty("usage")
+  private ChatUsage usage;
 }

api/src/main/java/com/coze/openapi/client/workflows/run/model/WorkflowEventMessage.java

@@ -2,6 +2,7 @@
 
 import java.util.Map;
 
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.coze.openapi.service.utils.Utils;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
@@ -41,6 +42,10 @@ public class WorkflowEventMessage {
   @JsonProperty("ext")
   private Map<String, Object> ext;
 
+  /** Token usage information for the workflow execution. */
+  @JsonProperty("usage")
+  private ChatUsage usage;
+
   public static WorkflowEventMessage fromJson(String data) {
     return Utils.fromJson(data, WorkflowEventMessage.class);
   }

api/src/main/java/com/coze/openapi/client/workflows/run/model/WorkflowRunHistory.java

@@ -1,5 +1,6 @@
 package com.coze.openapi.client.workflows.run.model;
 
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import lombok.AllArgsConstructor;
@@ -87,4 +88,8 @@ public class WorkflowRunHistory {
    */
   @JsonProperty("debug_url")
   private String debugUrl;
+
+  /** Token usage information for the workflow execution. */
+  @JsonProperty("usage")
+  private ChatUsage usage;
 }

api/src/main/java/com/coze/openapi/client/workflows/run/model/WorkflowRunResult.java

@@ -1,5 +1,6 @@
 package com.coze.openapi.client.workflows.run.model;
 
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 import lombok.AllArgsConstructor;
@@ -29,4 +30,8 @@ public class WorkflowRunResult {
    */
   @JsonProperty("execute_id")
   private String executeID;
+
+  /** Token usage information for the workflow execution. */
+  @JsonProperty("usage")
+  private ChatUsage usage;
 }

api/src/test/java/com/coze/openapi/service/service/workflow/WorkFlowRunServiceTest.java

@@ -15,6 +15,7 @@
 
 import com.coze.openapi.api.WorkflowRunAPI;
 import com.coze.openapi.api.WorkflowRunHistoryAPI;
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.coze.openapi.client.workflows.run.RunWorkflowReq;
 import com.coze.openapi.client.workflows.run.RunWorkflowResp;
 import com.coze.openapi.client.workflows.run.model.WorkflowEvent;
@@ -53,7 +54,7 @@ public class WorkFlowRunServiceTest {
           + "\n"
           + "id: 5\n"
           + "event: Message\n"
-          + "data: {\"content\":\"{\\\"output\\\":\\\"为什么小明要带一把尺子去看电影？因为他听说电影很长，怕坐不下！\\\"}\",\"cost\":\"0.00\",\"node_is_finish\":true,\"node_seq_id\":\"0\",\"node_title\":\"\",\"token\":1230}\n"
+          + "data: {\"content\":\"{\\\"output\\\":\\\"为什么小明要带一把尺子去看电影？因为他听说电影很长，怕坐不下！\\\"}\",\"cost\":\"0.00\",\"node_is_finish\":true,\"node_seq_id\":\"0\",\"node_title\":\"\",\"token\":1230,\"usage\":{\"token_count\":1230,\"input_count\":615,\"output_count\":615}}\n"
           + "\n"
           + "id: 0\n"
           + "event: Error\n"
@@ -104,7 +105,11 @@ void parseStreamEventTest() {
             5,
             event ->
                 event.getEvent().equals(WorkflowEventType.MESSAGE)
-                    && event.getMessage().getToken().equals(1230))
+                    && event.getMessage().getToken().equals(1230)
+                    && event.getMessage().getUsage() != null
+                    && event.getMessage().getUsage().getTokenCount() == 1230
+                    && event.getMessage().getUsage().getInputCount() == 615
+                    && event.getMessage().getUsage().getOutputCount() == 615)
         .assertValueAt(
             9,
             event ->
@@ -123,13 +128,16 @@ void testCreate() throws Exception {
 
     RunWorkflowReq req = RunWorkflowReq.builder().workflowID(workflowID).build();
 
+    ChatUsage usage = ChatUsage.builder().tokenCount(100).inputCount(50).outputCount(50).build();
+
     RunWorkflowResp baseResponse =
         RunWorkflowResp.builder()
             .code(0)
             .msg("success")
             .executeID(executeID)
             .logID(Utils.TEST_LOG_ID)
             .data("data")
+            .usage(usage)
             .build();
 
     // 创建 mock Call 对象
@@ -143,6 +151,10 @@ void testCreate() throws Exception {
     // 验证结果
     assertNotNull(result);
     assertEquals(executeID, result.getExecuteID());
+    assertNotNull(result.getUsage());
+    assertEquals(100, result.getUsage().getTokenCount());
+    assertEquals(50, result.getUsage().getInputCount());
+    assertEquals(50, result.getUsage().getOutputCount());
   }
 
   @Test

api/src/test/java/com/coze/openapi/service/service/workflow/WorkflowRunHistoryServiceTest.java

@@ -15,6 +15,7 @@
 import org.mockito.MockitoAnnotations;
 
 import com.coze.openapi.api.WorkflowRunHistoryAPI;
+import com.coze.openapi.client.chat.model.ChatUsage;
 import com.coze.openapi.client.common.BaseResponse;
 import com.coze.openapi.client.workflows.run.RetrieveRunHistoryReq;
 import com.coze.openapi.client.workflows.run.RetrieveRunHistoryResp;
@@ -44,10 +45,14 @@ void testRetrieve() throws Exception {
     RetrieveRunHistoryReq req =
         RetrieveRunHistoryReq.builder().workflowID(workflowId).executeID(executeId).build();
 
+    ChatUsage usage1 = ChatUsage.builder().tokenCount(150).inputCount(75).outputCount(75).build();
+
+    ChatUsage usage2 = ChatUsage.builder().tokenCount(200).inputCount(100).outputCount(100).build();
+
     List<WorkflowRunHistory> histories =
         Arrays.asList(
-            WorkflowRunHistory.builder().executeID("node1").build(),
-            WorkflowRunHistory.builder().executeID("node2").build());
+            WorkflowRunHistory.builder().executeID("node1").usage(usage1).build(),
+            WorkflowRunHistory.builder().executeID("node2").usage(usage2).build());
 
     BaseResponse<List<WorkflowRunHistory>> baseResponse =
         BaseResponse.<List<WorkflowRunHistory>>builder()
@@ -71,5 +76,13 @@ void testRetrieve() throws Exception {
     assertEquals(2, result.getHistories().size());
     assertEquals("node1", result.getHistories().get(0).getExecuteID());
     assertEquals(Utils.TEST_LOG_ID, result.getLogID());
+    assertNotNull(result.getHistories().get(0).getUsage());
+    assertEquals(150, result.getHistories().get(0).getUsage().getTokenCount());
+    assertEquals(75, result.getHistories().get(0).getUsage().getInputCount());
+    assertEquals(75, result.getHistories().get(0).getUsage().getOutputCount());
+    assertNotNull(result.getHistories().get(1).getUsage());
+    assertEquals(200, result.getHistories().get(1).getUsage().getTokenCount());
+    assertEquals(100, result.getHistories().get(1).getUsage().getInputCount());
+    assertEquals(100, result.getHistories().get(1).getUsage().getOutputCount());
   }
 }

example/pom.xml

@@ -16,7 +16,7 @@
         <dependency>
             <groupId>com.coze</groupId>
             <artifactId>coze-api</artifactId>
-            <version>0.4.1</version>
+            <version>0.5.0</version>
         </dependency>
     </dependencies>
 </project>