clawgo/docs/ekg-design.md

EKG 设计稿（Execution Knowledge Graph）

目标：在不引入重型图数据库的前提下，为 ClawGo 提供“可审计、可回放、可降错”的执行知识图谱能力，优先降低 agent 重复报错与自治死循环。

1. 范围与阶段

M1（本次实现）

• 记录执行结果事件（成功/失败/抑制）到 memory/ekg-events.jsonl
• 对错误文本做签名归一化（errsig）
• 在自治引擎中读取 advice：同任务同 errsig 连续失败达到阈值时，直接阻断重试（避免死循环）

M2（后续）

• provider/model/tool 维度的成功率建议（preferred / banned）
• channel/source 维度的策略分层

M3（后续）

• WAL + 快照（snapshot）
• WebUI 可视化（errsig 热点、抑制命中率）

---

2. 数据模型（接口草图）

type Event struct {
    Time    string `json:"time"`
    TaskID  string `json:"task_id,omitempty"`
    Session string `json:"session,omitempty"`
    Channel string `json:"channel,omitempty"`
    Source  string `json:"source,omitempty"`
    Status  string `json:"status"` // success|error|suppressed
    ErrSig  string `json:"errsig,omitempty"`
    Log     string `json:"log,omitempty"`
}

type Advice struct {
    ShouldEscalate bool     `json:"should_escalate"`
    RetryBackoffSec int     `json:"retry_backoff_sec"`
    Reason         []string `json:"reason"`
}

type SignalContext struct {
    TaskID  string
    ErrSig  string
    Source  string
    Channel string
}

---

3. 存储与性能

• 存储：memory/ekg-events.jsonl（append-only）
• 读取：仅扫描最近窗口（默认 2000 行）
• 复杂度：O(N_recent)
• 设计取舍：M1 以正确性优先，后续再加入 snapshot 与索引

---

4. 规则（M1）

• 错误签名归一化：
  • 路径归一化 <path>
  • 数字归一化 <n>
  • hex 归一化 <hex>
  • 空白压缩
• 阈值规则：
  • 若 task_id + errsig 连续 >=3 次 error，则
  • ShouldEscalate=true，自治任务进入 blocked:repeated_error_signature

---

5. 接入点

1. pkg/agent/loop.go

• 在 appendTaskAuditEvent 处同步写入 EKG 事件（与 task-audit 同步）

2. pkg/autonomy/engine.go

• 在运行结果为 error 的分支读取 EKG advice
• 命中升级条件时，直接阻断重试并标记 block reason

---

6. 风险与回滚

• 风险：阈值过低导致过早阻断
• 缓解：默认阈值 3，且仅在同 task+同 errsig 命中时触发
• 回滚：移除 advice 判断即可恢复原重试路径

---

7. 验收标准（M1）

• 能生成并追加 memory/ekg-events.jsonl
• 相同任务在相同错误签名下连续失败 3 次后，自治不再继续循环 dispatch
• make test（Docker compile）通过