From bc417d00efff1180335ee4b407db554c65b9ea18 Mon Sep 17 00:00:00 2001 From: matevip Date: Sat, 2 May 2026 15:42:10 +0800 Subject: [PATCH] chore: neutralize internal references in code comments and migrations --- .gitignore | 4 ++-- mateclaw-server/pom.xml | 2 +- .../vip/mate/acp/client/AcpStdioClient.java | 8 ++++---- .../vip/mate/acp/model/AcpEndpointEntity.java | 6 +++--- .../mate/acp/service/AcpDelegationService.java | 2 +- .../java/vip/mate/agent/AgentGraphBuilder.java | 18 +++++++++--------- .../main/java/vip/mate/agent/BaseAgent.java | 2 +- .../graph/executor/ToolExecutionExecutor.java | 4 ++-- .../java/vip/mate/channel/MediaPathGuard.java | 1 - .../vip/mate/cron/model/DeliveryConfig.java | 2 +- .../vip/mate/skill/acp/AcpSkillBridge.java | 10 ++++------ .../mate/tool/builtin/ShellExecuteTool.java | 5 ++--- .../mcp/controller/McpServerController.java | 2 +- .../tool/mcp/service/McpServerService.java | 3 +-- .../h2/V47__agent_max_iterations_100.sql | 4 ++-- ...gent_max_iterations_and_agents_md_tools.sql | 2 +- .../db/migration/h2/V68__add_acp_endpoints.sql | 6 +++--- .../mysql/V47__agent_max_iterations_100.sql | 4 ++-- 18 files changed, 40 insertions(+), 45 deletions(-) diff --git a/.gitignore b/.gitignore index 04a16d35..93cd7ff0 100644 --- a/.gitignore +++ b/.gitignore @@ -99,5 +99,5 @@ CLAUDE.md # Codex CLI local artifacts .codex/ -# QwenPaw sync state (generated each run; report is intentionally tracked) -scripts/.qwenpaw-sync-state.json +# Sync tooling local state (generated each run; report is intentionally tracked) +scripts/.*-sync-state.json diff --git a/mateclaw-server/pom.xml b/mateclaw-server/pom.xml index a24982b3..47bec634 100644 --- a/mateclaw-server/pom.xml +++ b/mateclaw-server/pom.xml @@ -382,7 +382,7 @@ test - diff --git a/mateclaw-server/src/main/java/vip/mate/acp/client/AcpStdioClient.java b/mateclaw-server/src/main/java/vip/mate/acp/client/AcpStdioClient.java index f75ce8be..9162fa42 100644 --- a/mateclaw-server/src/main/java/vip/mate/acp/client/AcpStdioClient.java +++ b/mateclaw-server/src/main/java/vip/mate/acp/client/AcpStdioClient.java @@ -41,9 +41,9 @@ import java.util.function.Function; * agent graph layer. * *

Why not the official {@code acp} Python SDK: MateClaw runs on the - * JVM. The protocol is JSON-RPC 2.0 line-delimited over stdio (per the - * QwenPaw reference at {@code C:/codes/QwenPaw}); the surface we need - * for "test connection" is small enough to implement directly. + * JVM. The protocol is JSON-RPC 2.0 line-delimited over stdio; the + * surface we need for "test connection" is small enough to implement + * directly. * *

Each {@link AcpStdioClient} instance owns one Process. Use * try-with-resources or call {@link #close()} explicitly. @@ -51,7 +51,7 @@ import java.util.function.Function; @Slf4j public class AcpStdioClient implements AutoCloseable { - /** ACP protocol version we advertise (matches QwenPaw v1 + Zed agents). */ + /** ACP protocol version we advertise (matches v1 ACP-compatible agents). */ public static final int PROTOCOL_VERSION = 1; private final ObjectMapper mapper; diff --git a/mateclaw-server/src/main/java/vip/mate/acp/model/AcpEndpointEntity.java b/mateclaw-server/src/main/java/vip/mate/acp/model/AcpEndpointEntity.java index f90cef02..88befe46 100644 --- a/mateclaw-server/src/main/java/vip/mate/acp/model/AcpEndpointEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/acp/model/AcpEndpointEntity.java @@ -46,9 +46,9 @@ public class AcpEndpointEntity { private String envJson; /** - * call_title | call_detail | update_detail (mirrors QwenPaw - * {@code tool_parse_mode}). Drives how the wrapper renders ACP - * tool-call events into MateClaw's stream protocol. + * call_title | call_detail | update_detail (mirrors the ACP + * {@code tool_parse_mode} convention). Drives how the wrapper + * renders ACP tool-call events into MateClaw's stream protocol. */ private String toolParseMode; diff --git a/mateclaw-server/src/main/java/vip/mate/acp/service/AcpDelegationService.java b/mateclaw-server/src/main/java/vip/mate/acp/service/AcpDelegationService.java index 78d1c13e..59b4eab2 100644 --- a/mateclaw-server/src/main/java/vip/mate/acp/service/AcpDelegationService.java +++ b/mateclaw-server/src/main/java/vip/mate/acp/service/AcpDelegationService.java @@ -203,7 +203,7 @@ public class AcpDelegationService { * Extract plain text from an ACP {@code content} field. The shape * varies between agents — Zed uses {@code [{type:"text",text:"..."}]}, * some emit a single object, others nest in {@code resource.text}. - * Mirror QwenPaw's tolerant extractor. + * Tolerant extractor that handles all known shapes. */ private String extractText(JsonNode content) { if (content == null || content.isNull()) return ""; diff --git a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java index 1e8e4a09..0d49a598 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java @@ -155,7 +155,7 @@ public class AgentGraphBuilder { // the agent's bound-skill requires-model. Falls back to the // global default when no preferred provider satisfies, so the // existing "no default model" error path stays intact. - // RFC-03 Lane G1 — honor per-Agent model override when set. + // Honor per-Agent model override when set. // resolveModel() looks up entity.modelName in enabled-only models; // null / blank / unmatched silently fall back to getDefaultModel(), // preserving the legacy behavior for Agents without an override. @@ -229,7 +229,7 @@ public class AgentGraphBuilder { } // Default 100 if DB row leaves max_iterations null; clamp per-agent overrides // to the hard ceiling (BaseAgent.MAX_ITERATIONS_HARD_CEILING) so a misconfigured - // row can never push an unbounded loop. Aligned with QwenPaw's 1..100 range. + // row can never push an unbounded loop. Effective range: 1..100. int rawMaxIter = entity.getMaxIterations() != null ? entity.getMaxIterations() : 100; int maxIter = Math.max(1, Math.min(rawMaxIter, BaseAgent.MAX_ITERATIONS_HARD_CEILING)); if (maxIter != rawMaxIter) { @@ -1099,10 +1099,10 @@ public class AgentGraphBuilder { } /** - * RFC-03 Lane B1 overload — accepts a per-model read-timeout override - * (seconds). Threaded into both the sync RestClient and streaming - * WebClient so timeout behavior is consistent across blocking and - * streaming chat completions. Null falls back to the default 180s. + * Overload that accepts a per-model read-timeout override (seconds). + * Threaded into both the sync RestClient and streaming WebClient so + * timeout behavior is consistent across blocking and streaming chat + * completions. Null falls back to the default 180s. */ public OpenAiApi buildOpenAiApi(ModelProviderEntity provider, Integer readTimeoutOverride) { if (provider == null || !modelProviderService.isProviderConfigured(provider.getProviderId())) { @@ -1489,8 +1489,8 @@ public class AgentGraphBuilder { } /** - * RFC-03 Lane B1 overload — accepts a per-model read-timeout override - * (seconds). Null falls back to the default 180s. + * Overload that accepts a per-model read-timeout override (seconds). + * Null falls back to the default 180s. */ private RestClient.Builder applyHttpTimeouts(RestClient.Builder builder, Integer readTimeoutOverride) { HttpClient httpClient = HttpClient.newBuilder() @@ -1521,7 +1521,7 @@ public class AgentGraphBuilder { } /** - * RFC-03 Lane B1 overload — same per-model override semantics as + * Overload with the same per-model override semantics as * {@link #applyHttpTimeouts(RestClient.Builder, Integer)}. */ private WebClient.Builder applyHttpTimeoutsToWebClient(WebClient.Builder builder, Integer readTimeoutOverride) { diff --git a/mateclaw-server/src/main/java/vip/mate/agent/BaseAgent.java b/mateclaw-server/src/main/java/vip/mate/agent/BaseAgent.java index 2480f93b..bcbe8d38 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/BaseAgent.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/BaseAgent.java @@ -49,7 +49,7 @@ public abstract class BaseAgent { /** * Max ReAct iterations (one reasoning + action + observation step counts as one). * Default 100, hard ceiling 100 (enforced in AgentGraphBuilder so per-agent DB - * overrides cannot exceed it). Aligned with QwenPaw's _MAX_MAX_ITERATIONS. + * overrides cannot exceed it). */ public static final int MAX_ITERATIONS_HARD_CEILING = 100; protected int maxIterations = 100; diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java index 26803c79..a918bcb9 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java @@ -57,10 +57,10 @@ public class ToolExecutionExecutor { * this list. */ /** - * RFC-03 Lane A2 — defense against runaway single-response tool floods. + * Defense against runaway single-response tool floods. * *

Some models (StreamLake's kat-coder-pro-v1 has been observed - * emitting 50+ in one shot, see QwenPaw #2055) return huge {@code tool_calls} + * emitting 50+ in one shot) return huge {@code tool_calls} * batches in a single response. Without a cap, every call executes, which * can saturate downstream provider QPS, multiply approval rows, and burn * tokens. The cap is independent of {@code MAX_ITERATIONS} (which limits diff --git a/mateclaw-server/src/main/java/vip/mate/channel/MediaPathGuard.java b/mateclaw-server/src/main/java/vip/mate/channel/MediaPathGuard.java index 61598354..767c37de 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/MediaPathGuard.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/MediaPathGuard.java @@ -16,7 +16,6 @@ import java.util.Set; * checks — extension allowlist here, size cap there, no path-traversal * guard at all. The result is 8 places to keep in sync when a new file * type is supported (or when a new exploit needs a defensive patch). - * Same gap as QwenPaw #1220. * *

This guard centralizes four checks that every adapter needs: *

    diff --git a/mateclaw-server/src/main/java/vip/mate/cron/model/DeliveryConfig.java b/mateclaw-server/src/main/java/vip/mate/cron/model/DeliveryConfig.java index db1f260f..26ab3154 100644 --- a/mateclaw-server/src/main/java/vip/mate/cron/model/DeliveryConfig.java +++ b/mateclaw-server/src/main/java/vip/mate/cron/model/DeliveryConfig.java @@ -41,7 +41,7 @@ public record DeliveryConfig( * is still persisted, audit + token-usage all work — only the * agent's narrative reply is suppressed from the channel. * - *

    Use cases (QwenPaw #2452): noon health-check cron that just + *

    Use cases: noon health-check cron that just * pokes a database and writes structured output, project-weekly * report jobs that drop a file into a knowledge base, internal * pipelines that don't need an IM-visible "I did the thing" diff --git a/mateclaw-server/src/main/java/vip/mate/skill/acp/AcpSkillBridge.java b/mateclaw-server/src/main/java/vip/mate/skill/acp/AcpSkillBridge.java index 35ce9eeb..a200ec40 100644 --- a/mateclaw-server/src/main/java/vip/mate/skill/acp/AcpSkillBridge.java +++ b/mateclaw-server/src/main/java/vip/mate/skill/acp/AcpSkillBridge.java @@ -42,12 +42,10 @@ import java.util.concurrent.ConcurrentHashMap; * without manual binding. * *

    This solves the "ACP configured as skill cannot be called" - * usability bug (matches the inspiration from QwenPaw's - * {@code delegate_external_agent} pattern, but keeps MateClaw's - * skill-card affordance for endpoint discovery): the user manages - * endpoints in Settings ▸ ACP Endpoints, and a card automatically - * appears on the Skills page — no per-endpoint SKILL.md authoring - * required. + * usability bug while keeping MateClaw's skill-card affordance for + * endpoint discovery: the user manages endpoints in Settings ▸ ACP + * Endpoints, and a card automatically appears on the Skills page — + * no per-endpoint SKILL.md authoring required. * *

    Lifecycle: *