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.*; import static vip.mate.agent.graph.state.MateClawStateKeys.*;
/** /**
* 工具执行节点ReAct Action 阶段 * Tool-execution node (the ReAct Action phase).
* <p> * <p>
* 委托 {@link ToolExecutionExecutor} 执行工具调用支持并发执行和审批 barrier * Delegates tool-call execution to {@link ToolExecutionExecutor}, supporting
* concurrent execution and the approval barrier.
* <p> * <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 提取 * <p>B2: when a {@code load_skill} call is detected, the skill manifest's
* {@code constraints} 并写入 ProgressLedger pinned entries使约束 * {@code constraints} are extracted and written to the ProgressLedger's pinned
* 在整个对话中可见不被 LLM progress_update 覆盖不被上下文压缩裁剪 * 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 即使不主动调用 * <p>B5: after a tool call succeeds, the ProgressLedger is auto-backfilled so the
* progress_update 也能在下一轮看到已完成的工具调用记录自动记录条数有上限 * LLM sees the completed tool-call record on the next turn even without calling
* {@link ProgressLedgerService#MAX_AUTO_RECORDED}且不覆盖 LLM 已写的条目 * progress_update. Auto-recorded entries are capped
* ({@link ProgressLedgerService#MAX_AUTO_RECORDED}) and never overwrite entries
* the LLM already wrote.
* *
* @author MateClaw Team * @author MateClaw Team
*/ */

View File

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