docs(agent): fix stale ledger-guard comment and translate ActionNode javadoc

- ProgressLedgerService.upsert: the reserved-prefix guard rejects the write; the
  comment said 'strip the prefix and continue', which no longer matches. Rewrite
  it to describe the actual reject behavior.
- ActionNode: translate the class javadoc (including the B2 pinned-constraints and
  B5 auto-backfill notes) to English per code style.
This commit is contained in:
matevip 2026-07-06 11:52:59 +08:00
parent e4dd08b5f4
commit 15f134a35e
2 changed files with 16 additions and 11 deletions

View File

@ -19,19 +19,24 @@ import java.util.concurrent.CancellationException;
import static vip.mate.agent.graph.state.MateClawStateKeys.*;
/**
* 工具执行节点ReAct Action 阶段
* Tool-execution node (the ReAct Action phase).
* <p>
* 委托 {@link ToolExecutionExecutor} 执行工具调用支持并发执行和审批 barrier
* Delegates tool-call execution to {@link ToolExecutionExecutor}, supporting
* concurrent execution and the approval barrier.
* <p>
* 支持 forced_replay 阶段当审批通过后的重放调用到达时跳过 ToolGuard 检查直接执行
* Supports the forced_replay phase: when an approved replay call arrives, it
* skips the ToolGuard check and executes directly.
*
* <p>B2: 当检测到 {@code load_skill} 调用时 skill manifest 提取
* {@code constraints} 并写入 ProgressLedger pinned entries使约束
* 在整个对话中可见不被 LLM progress_update 覆盖不被上下文压缩裁剪
* <p>B2: when a {@code load_skill} call is detected, the skill manifest's
* {@code constraints} are extracted and written to the ProgressLedger's pinned
* entries, so the constraints stay visible for the whole conversation never
* overwritten by the LLM's progress_update, never trimmed by context compression.
*
* <p>B5: 工具调用成功后自动回填 ProgressLedger LLM 即使不主动调用
* progress_update 也能在下一轮看到已完成的工具调用记录自动记录条数有上限
* {@link ProgressLedgerService#MAX_AUTO_RECORDED}且不覆盖 LLM 已写的条目
* <p>B5: after a tool call succeeds, the ProgressLedger is auto-backfilled so the
* LLM sees the completed tool-call record on the next turn even without calling
* progress_update. Auto-recorded entries are capped
* ({@link ProgressLedgerService#MAX_AUTO_RECORDED}) and never overwrite entries
* the LLM already wrote.
*
* @author MateClaw Team
*/

View File

@ -127,8 +127,8 @@ public class ProgressLedgerService {
}
// Guard reserved prefixes the LLM must not overwrite Java-managed
// entries (auto-recorded tool calls or pinned skill constraints).
// Strip the prefix and continue with the remainder so the LLM's
// progress_update still lands, just under a non-reserved key.
// Reject the write so the caller re-issues progress_update under a
// non-reserved key instead of clobbering a system-managed entry.
if (key.startsWith(ProgressLedger.AUTO_RECORDED_PREFIX) || key.startsWith("pin_")) {
throw new IllegalArgumentException(
"step key prefix '" + ProgressLedger.AUTO_RECORDED_PREFIX