Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification
# Conflicts: # .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.i18n.yaml # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/cookbook/extension-cookbook.i18n.yaml # docs/cookbook/extension-cookbook.md # docs/cookbook/extension-cookbook.zh.md # docs/core-data-structures/llm-streaming.i18n.yaml # docs/core-data-structures/session.i18n.yaml # docs/defensive-patterns.i18n.yaml # packages/acp/acp/README.i18n.yaml # packages/client/runtime/README.i18n.yaml # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-goal/README.i18n.yaml # packages/compact/compact-basic/README.i18n.yaml # packages/context/README.i18n.yaml # packages/context/README.md # packages/context/README.zh.md # packages/context/session-reference/README.i18n.yaml # packages/context/session-reference/README.md # packages/context/session-reference/README.zh.md # packages/context/tmux-context/README.i18n.yaml # packages/core/session/README.i18n.yaml # packages/core/session/README.md # packages/core/session/README.zh.md # packages/goal/command-goal/README.i18n.yaml # packages/goal/goal-session/README.i18n.yaml # packages/goal/goal-session/README.zh.md # packages/guard/README.i18n.yaml # packages/guard/README.md # packages/guard/README.zh.md # packages/guard/repeat-tool-guard/README.i18n.yaml # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/plan/plan-mode/README.i18n.yaml # packages/sdk/sdk-client/README.i18n.yaml # packages/sdk/sdk-client/README.md # packages/sdk/sdk-client/README.zh.md # packages/session-persistence/session-persistence/README.i18n.yaml # packages/subagent/subagent-dsh-sdk/README.i18n.yaml # python/sdk/README.i18n.yaml
This commit is contained in:
_Kerman
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/guard/README.md
|
||||
README.md: 9b41efa619b049c8ce35b3b48a5284c3c63d14c7
|
||||
README.zh.md: 67371448d6788971acf94ad5577ac88c0ae7a734
|
||||
README.md: 8da2f2ddcc1432e7963e600b35549f5e26121af2
|
||||
README.zh.md: aa8b5bd1f7d10d90d1dc84d07a7aad81bfb4259c
|
||||
|
||||
@@ -2,10 +2,8 @@
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Behavioral guard plugins that watch the agent loop for unproductive patterns and nudge the model back on course. A single **product** package — there is no interface/implementation seam here, because a guard is a self-contained consumer of existing core seams (`tools/post-execute`, `agent/pre-step`, `agent/status`), not a swappable capability.
|
||||
Behavioral guard plugins watch the agent loop for unproductive patterns and nudge the model back on course. A guard is a self-contained consumer of core seams, not a swappable capability.
|
||||
|
||||
| Package | Role | ctx key |
|
||||
|---|---|---|
|
||||
| `repeat-tool-guard/` | Advisory reminders when an agent loops on identical tool calls | (listens on `ctx.tools`' waterfalls) |
|
||||
|
||||
Reminders travel as `additionalContexts` on the `tools/post-execute` decision; the agent loop appends them as logged plugin-sourced `user/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.
|
||||
| [`repeat-tool-guard/`](repeat-tool-guard/README.md) | Advisory reminders for repeated tool calls | listens on tool and agent events |
|
||||
|
||||
@@ -1,11 +1,9 @@
|
||||
# guard/：循环健康 guard 家族
|
||||
# guard/ — 循环卫生 guard 家族
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
这组行为 guard 插件会监视 agent loop（智能体循环）中的低效模式，并提醒模型调整方向。这里只有一个**产品**包（package），不设接口／实现 seam：guard 是现有核心 seam（`tools/post-execute`、`agent/pre-step`、`agent/status`）的自包含消费方，并非可替换能力。
|
||||
行为 guard 插件监视 agent loop（智能体循环）中的无效模式，并推动模型回到正轨。guard 是 core seam 的自包含消费方，而非可替换能力。
|
||||
|
||||
| 包 | 职责 | ctx 键 |
|
||||
| 包 | 职责 | ctx key |
|
||||
|---|---|---|
|
||||
| `repeat-tool-guard/` | 当 agent 对完全相同的工具调用反复循环时给出提示 | （监听 `ctx.tools` 的 waterfall，即瀑布式事件） |
|
||||
|
||||
提示以 `additionalContexts` 形式附在 `tools/post-execute` 决策中传递；agent loop 会在该步骤的工具结果之后，将其追加为有日志记录、来源为插件的 `user/message` 事件（参见[工具包](../core/tools)）。因此，guard 告诉模型的所有内容都能从会话日志中重建。
|
||||
| [`repeat-tool-guard/`](repeat-tool-guard/README.md) | 针对重复工具调用的建议性提醒 | 监听工具和 agent 事件 |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/guard/repeat-tool-guard/README.md
|
||||
README.md: 0f67c0e062ebf3963727afa2a8539e3f08a1b6a6
|
||||
README.zh.md: 9869e45244b9bacca5416e476ae193375691dfbf
|
||||
README.md: 4d7b24b1188d021a82ed87b0c721fa539a4e5f0b
|
||||
README.zh.md: b332d579d10af1a55d0bf75207452ae7d15bb7c9
|
||||
|
||||
@@ -34,10 +34,6 @@ The chain key is `(tool name, canonical arguments)` — canonicalization is a de
|
||||
|
||||
Reminders ride the post-execute decision's `additionalContexts` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as an injected `user/message` after the step's tool results, which the session renders as a plain synthetic user message — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and prepends its reminder to the downstream decision's context array (both variants — a blocked call still gets the nudge); every entry retains its own source and metadata.
|
||||
|
||||
## Testing
|
||||
|
||||
Unit suites drive a real agent loop against a mock adapter (no network) and cover the chain semantics above to per-file 100%. The snapshot tier owns the transcript surface: a scripted-replay scenario repeats a call five times and pins both reminder tiers (gentle at 3, detailed at 5) as injected `user/message`s in the ACP transcript.
|
||||
|
||||
## Model Experience
|
||||
|
||||
### First-threshold context message
|
||||
|
||||
@@ -34,10 +34,6 @@
|
||||
|
||||
提醒通过 post-execute 决策中的 `additionalContexts`（来源为 `{kind: 'plugin', plugin: 'repeat-tool-guard'}`）传递，绝不替换 `content`；用于审计的 `tool/result` 事件仍保留工具自己的输出。循环会缓冲这段上下文，并在该步骤的工具结果之后将其作为注入的 `user/message` 追加；会话会将它渲染为普通的合成用户消息。因此，提醒对模型可见、带有来源归属，并且无需增加会话事件即可从会话日志重建。guard 始终通过 `next()` 委派，并将自己的提醒放在下游决策的上下文数组之前（两种结果都适用：被阻止的调用也会收到提醒）；每个条目保留自己的来源和元数据。
|
||||
|
||||
## 测试
|
||||
|
||||
单元测试使用 mock 适配器（无网络）驱动真实 agent loop，并对上述链语义实现逐文件 100% 覆盖率。快照层负责 transcript（文本记录）接口：脚本化回放场景会将同一调用重复 5 次，并在 ACP（Agent Client Protocol）的 transcript 中固定两个提醒层级，即第 3 次的温和提醒和第 5 次的详细提醒；二者均为注入的 `user/message`。
|
||||
|
||||
## 模型体验
|
||||
|
||||
### 首个阈值的上下文消息
|
||||
|
||||
Reference in New Issue
Block a user