mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 19:23:42 +08:00
47 lines
1.9 KiB
Java
47 lines
1.9 KiB
Java
package vip.mate.tool;
|
|
|
|
import java.lang.annotation.ElementType;
|
|
import java.lang.annotation.Retention;
|
|
import java.lang.annotation.RetentionPolicy;
|
|
import java.lang.annotation.Target;
|
|
|
|
/**
|
|
* Marks a {@link org.springframework.ai.tool.annotation.Tool}-annotated method
|
|
* as <b>not safe to run concurrently with itself or with other tools that
|
|
* touch the same state</b>.
|
|
*
|
|
* <p>Read by {@link vip.mate.tool.ToolConcurrencyRegistry} at startup. The
|
|
* registry returns {@code true} from
|
|
* {@link ToolConcurrencyRegistry#isUnsafe(String)} for marked tools, which
|
|
* causes {@code ToolExecutionExecutor} to execute them in their own batch
|
|
* (no parallelism, no overlap with the surrounding safe batch).</p>
|
|
*
|
|
* <p>Use cases:</p>
|
|
* <ul>
|
|
* <li>File writes / edits ({@code WriteFileTool}, {@code EditFileTool})</li>
|
|
* <li>Shell command execution ({@code ShellExecuteTool})</li>
|
|
* <li>Stateful workspace mutations ({@code WorkspaceMemoryTool}, {@code SkillManageTool})</li>
|
|
* <li>Persistent operations on shared resources ({@code CronJobTool}, {@code DatasourceTool})</li>
|
|
* <li>Long-running generative tools where API rate limits forbid parallel calls
|
|
* ({@code ImageGenerateTool}, {@code VideoGenerateTool})</li>
|
|
* </ul>
|
|
*
|
|
* <p>Read-only and idempotent tools should remain unannotated; they will be
|
|
* batched together for parallel execution by the executor.</p>
|
|
*
|
|
* <p>For MCP-provided tools the executor will eventually consult the
|
|
* {@code annotations.readOnlyHint} field from the MCP {@code Tool} schema;
|
|
* that integration is tracked as a Phase 4 follow-up. Until then MCP tools
|
|
* default to safe (their pre-existing behavior).</p>
|
|
*/
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
@Target(ElementType.METHOD)
|
|
public @interface ConcurrencyUnsafe {
|
|
|
|
/**
|
|
* Optional human-readable reason. Surfaced in startup logs to help
|
|
* operators audit which tools have been marked unsafe.
|
|
*/
|
|
String value() default "";
|
|
}
|