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

CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+### Prerequisites
+- Java 8+ (tested with Temurin 8)
+- Maven 3.9+
+- Environment variables for testing: `COZE_API_TOKEN`, `COZE_API_BASE`, etc.
+
+### Build Commands
+```bash
+# Build the entire project
+mvn clean compile
+
+# Run tests for specific module
+mvn test -pl api
+mvn test -pl example
+
+# Run specific test class
+mvn test -Dtest=com.coze.openapi.service.service.chat.ChatServiceTest -pl api
+
+# Run tests with Java 8 (required for compatibility)
+JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home mvn test
+
+# Package the SDK
+mvn clean package -DskipTests
+
+# Install to local Maven repository
+mvn clean install -DskipTests
+
+# Code formatting and linting
+mvn spotless:check
+mvn spotless:apply
+
+# Generate coverage report
+mvn jacoco:report
+```
+
+## Architecture Overview
+
+### Project Structure
+This is a multi-module Maven project with two main modules:
+- **api**: The core Coze Java SDK containing all API implementations
+- **example**: Comprehensive examples demonstrating SDK usage
+
+### Core Architecture
+The SDK follows a service-oriented architecture with these key components:
+
+#### 1. Main Entry Point (`CozeAPI`)
+- Central client class providing access to all Coze services
+- Built using Retrofit for HTTP communication
+- Supports both sync and async operations
+- Configurable via fluent builder pattern
+
+#### 2. Service Layer
+Services are organized by functional domain:
+- **ChatService**: Bot conversations and streaming chat
+- **BotService**: Bot creation, management, and publishing
+- **WorkflowService**: Workflow execution and streaming
+- **ConversationService**: Conversation management and messages
+- **DatasetService**: Knowledge base and document management
+- **FileService**: File upload and management
+- **AudioService**: Speech synthesis and transcription
+- **WorkspaceService**: Workspace operations
+- **CommerceService**: Benefit and billing management
+- **WebsocketsClient**: Real-time WebSocket communication
+
+#### 3. Authentication
+Multiple authentication methods supported:
+- **TokenAuth**: Personal access token authentication
+- **WebOAuthClient**: Web OAuth 2.0 flow
+- **JWTOAuthClient**: JWT-based OAuth for service accounts
+- **PKCEOAuthClient**: PKCE OAuth for public clients
+- **DeviceOAuthClient**: Device flow for limited-input devices
+
+#### 4. API Design Patterns
+- **Request/Response**: All API calls use strongly-typed request/response objects
+- **Pagination**: List operations return paginated results with iterator support
+- **Streaming**: Real-time streaming via RxJava Flowable
+- **WebSocket**: Real-time communication for chat, audio, and transcription
+- **Error Handling**: Custom exceptions with detailed error information
+
+### Key Technologies
+- **HTTP Client**: Retrofit 2.9.0 with OkHttp 3.14.9
+- **JSON**: Jackson 2.14.2 for serialization/deserialization
+- **Async**: RxJava2 for reactive programming
+- **JWT**: JJWT 0.11.5 for JWT token handling
+- **OAuth**: ScribeJava 8.3.1 for OAuth flows
+- **Testing**: JUnit 5.10.2 with Mockito 4.11.0
+- **Build**: Maven with Spotless for code formatting
+
+### Environment Configuration
+Required environment variables for testing:
+```bash
+# Basic API access
+export COZE_API_TOKEN="your_personal_access_token"
+export COZE_API_BASE="https://api.coze.com"  # or https://api.coze.cn for CN
+
+# Bot and workspace IDs
+export PUBLISHED_BOT_ID="your_bot_id"
+export WORKSPACE_ID="your_workspace_id"
+export USER_ID="your_user_id"
+
+# OAuth configurations (as needed)
+export COZE_WEB_OAUTH_CLIENT_ID="..."
+export COZE_WEB_OAUTH_CLIENT_SECRET="..."
+export COZE_WEB_OAUTH_REDIRECT_URI="..."
+```
+
+### Development Workflow
+1. **Setup**: Configure Java 8 and Maven
+2. **Build**: Run `mvn clean compile` to build the project
+3. **Test**: Use existing test classes as templates for new features
+4. **Format**: Run `mvn spotless:apply` before committing
+5. **Examples**: Use `/example` module for testing new features
+6. **Documentation**: Update README.md and examples for new APIs
+
+### Testing Strategy
+- Unit tests in `api/src/test/java/`
+- Integration tests use mock Retrofit services
+- Examples in `example/src/main/java/` demonstrate real usage
+- Test classes mirror service structure (e.g., `ChatServiceTest` tests `ChatService`)
+
+### Code Style
+- Google Java Format (via Spotless Maven plugin)
+- Lombok for boilerplate reduction
+- Builder pattern for complex objects
+- Fluent interfaces for service configuration

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());
   }
 }