docs: refine protocol field semantics

Author: loong10k

src/main/java/io/github/easy4j/opencode/HttpResponseMode.java

@@ -9,17 +9,17 @@
 public enum HttpResponseMode {
 
     /**
-     * blocking枚举值。
+     * 等待响应体完整读取后再返回，适用于普通同步 REST 调用。
      */
     BLOCKING,
 
     /**
-     * stream枚举值。
+     * 保持响应连接并逐段消费数据，适用于 SSE 或其他流式响应。
      */
     STREAM,
 
     /**
-     * auto枚举值。
+     * 由具体 API 根据端点类型自动选择缓冲或流式模式。
      */
     AUTO
 }

src/main/java/io/github/easy4j/opencode/OpenCodeClient.java

@@ -69,7 +69,7 @@ public class OpenCodeClient implements AutoCloseable {
      */
     private final OpenCodeSseClient sseClient;
     /**
-     * OpenCode 协议字段 {@code cli}；Java 类型为 {@code OpenCodeCli}。
+     * 本地 CLI 操作门面；CLI 子系统禁用时为 {@code null}。
      */
     private final OpenCodeCli cli;
     /**

src/main/java/io/github/easy4j/opencode/api/mapper/OpenCodeCallbackParser.java

@@ -35,7 +35,7 @@ public class OpenCodeCallbackParser {
      */
     private static final Logger log = LoggerFactory.getLogger(OpenCodeCallbackParser.class);
     /**
-     * OpenCode 协议字段 {@code MAPPER}；Java 类型为 {@code ObjectMapper}。
+     * 用于解析回调 JSON 的共享映射器，允许注释并忽略服务端新增字段。
      */
     private static final ObjectMapper MAPPER = new ObjectMapper()
             .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

src/main/java/io/github/easy4j/opencode/api/model/FileContent.java

@@ -16,7 +16,7 @@
 public class FileContent {
 
     /**
-     * OpenCode 协议中的类型判别值。
+     * 文件内容类型，例如文本或二进制。
      */
     private String type;
 

src/main/java/io/github/easy4j/opencode/api/model/FileDiff.java

@@ -21,7 +21,7 @@ public class FileDiff {
     private String path;
 
     /**
-     * OpenCode 协议字段 {@code oldPath}；Java 类型为 {@code String}。
+     * 文件重命名或移动前的旧路径；其他差异类型为空。
      */
     @JsonProperty("oldPath")
     private String oldPath;

src/main/java/io/github/easy4j/opencode/api/model/FormatterStatus.java

@@ -25,7 +25,7 @@ public class FormatterStatus {
     private Boolean enabled;
 
     /**
-     * OpenCode 协议字段 {@code command}；Java 类型为 {@code String}。
+     * 启动该格式化器时使用的命令行。
      */
     private String command;
 }

src/main/java/io/github/easy4j/opencode/api/model/LspStatus.java

@@ -27,7 +27,7 @@ public class LspStatus {
     private String name;
 
     /**
-     * OpenCode 协议字段 {@code root}；Java 类型为 {@code String}。
+     * 语言服务器绑定的项目根目录。
      */
     private String root;
 

src/main/java/io/github/easy4j/opencode/api/model/MessageInfo.java

@@ -17,7 +17,7 @@
 public class MessageInfo {
 
     /**
-     * OpenCode 协议字段 {@code info}；Java 类型为 {@code Message}。
+     * 目标消息的角色、时间和会话归属等元数据。
      */
     private Message info;
 

src/main/java/io/github/easy4j/opencode/api/model/OpenCodePath.java

@@ -16,12 +16,12 @@
 public class OpenCodePath {
 
     /**
-     * OpenCode 协议字段 {@code home}；Java 类型为 {@code String}。
+     * 当前用户的主目录路径。
      */
     private String home;
 
     /**
-     * OAuth 防重放状态值。
+     * OpenCode 持久化运行状态目录。
      */
     private String state;
 
@@ -31,17 +31,17 @@ public class OpenCodePath {
     private String config;
 
     /**
-     * OpenCode 协议字段 {@code directory}；Java 类型为 {@code String}。
+     * 当前 OpenCode Server 实例的工作目录。
      */
     private String directory;
 
     /**
-     * OpenCode 协议字段 {@code worktree}；Java 类型为 {@code String}。
+     * 当前项目工作树根目录。
      */
     private String worktree;
 
     /**
-     * OpenCode 协议字段 {@code worktreeDir}；Java 类型为 {@code String}。
+     * 服务端返回的工作树目录兼容字段。
      */
     @JsonProperty("worktree_dir")
     private String worktreeDir;

src/main/java/io/github/easy4j/opencode/api/model/Part.java

@@ -16,11 +16,11 @@
 public class Part {
 
     /**
-     * OpenCode 协议中的类型判别值。
+     * 消息片段类型，例如 {@code text}、{@code tool_use} 或 {@code tool_result}。
      */
     private String type;
     /**
-     * OpenCode 协议字段 {@code text}；Java 类型为 {@code String}。
+     * 文本类型消息片段的正文；非文本片段可能为空。
      */
     private String text;