Cognition Log 与知识反馈设计

文档维护规范

先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：module/file.py:function_name
简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在 knowhub/docs/decisions.md 另行记录

概述

每个 trace 维护一个 cognition_log.json，按时间顺序记录所有认知事件（知识查询、评估、提取、反思），为知识质量反馈和 Memory 系统的 dream 操作（详见 agent/docs/memory-plan.md）提供数据。

此文件原名 knowledge_log.json，扩展为统一事件流后更名。

Cognition Log 数据结构

位置：.trace/{trace_id}/cognition_log.json

{
  "trace_id": "trace-xxx",
  "events": [
    { "type": "query", "sequence": 42, ... },
    { "type": "evaluation", "sequence": 66, ... },
    { "type": "extraction", "sequence": 88, ... },
    { "type": "reflection", "sequence": 120, ... }
  ]
}

所有事件按 sequence 排列，保持在 trace 中的时间顺序。

事件类型

`query`：知识查询

Agent 通过 POST /api/knowledge/ask 查询知识时记录。一次查询返回 KM Agent 的整合回答及引用的各 source，作为一个整体记录。

{
  "type": "query",
  "sequence": 42,
  "goal_id": "1",
  "query": "goal 的描述文本",
  "response": "KM Agent 整合后的回答...",
  "source_ids": ["knowledge-a1b2", "knowledge-c3d4", "knowledge-e5f6"],
  "sources": [
    {"id": "knowledge-a1b2", "task": "...", "content": "...（截断500字）"},
    {"id": "knowledge-c3d4", "task": "...", "content": "..."}
  ],
  "timestamp": "2026-03-20T10:00:00"
}

写入时机：agent/trace/goal_tool.py:inject_knowledge_for_goal，POST /api/knowledge/ask 返回后。

`evaluation`：知识评估

对某次 query 中各 source 的使用效果评估。通过 query_sequence 关联到对应的 query 事件。

{
  "type": "evaluation",
  "sequence": 66,
  "query_sequence": 42,
  "trigger": "goal_completion",
  "assessments": [
    {"source_id": "knowledge-a1b2", "status": "helpful", "reason": "准确定位了问题"},
    {"source_id": "knowledge-c3d4", "status": "irrelevant", "reason": "与当前任务无关"},
    {"source_id": "knowledge-e5f6", "status": "harmful", "reason": "建议的方法已过时"}
  ],
  "timestamp": "2026-03-20T10:05:00"
}

status 可能的值：

状态	含义
`irrelevant`	知识与当前任务无关
`unused`	知识相关但未被使用
`helpful`	知识对任务有实质帮助
`harmful`	知识对任务产生负面作用
`neutral`	知识相关但无明显影响

`extraction`：知识提取

Agent 通过 reflection 侧分支将知识上传到 KnowHub 时记录。

{
  "type": "extraction",
  "sequence": 88,
  "trigger": "compression",
  "items": [
    {"knowledge_id": "knowledge-new-1", "type": "experience", "task": "...", "content": "...（截断500字）"}
  ],
  "timestamp": "2026-03-20T10:10:00"
}

写入时机：reflection 侧分支中 upload_knowledge 调用成功后。

`reflection`：记忆反思

仅 memory-bearing Agent 使用（详见 agent/docs/memory-plan.md）。Dream 操作触发的 per-trace 记忆反思。

{
  "type": "reflection",
  "sequence": 120,
  "reflected_range": [43, 120],
  "summary": "这次执行中发现用户偏好XX方向...",
  "timestamp": "2026-04-07T20:00:00"
}

写入时机：dream 操作中 per-trace 反思完成后。

评估触发机制

评估针对的是未评估的 query 事件（即存在 query 事件但没有对应 evaluation 事件的）。

判断待评估条件：查找 cognition_log 中所有 type: "query" 事件，检查是否存在 query_sequence 指向该 query 的 type: "evaluation" 事件。

触发点 1：Goal 完成

时机：Goal status 变为 completed 或 abandoned

触发逻辑（agent/trace/store.py:update_goal）：

Goal 完成
  ↓
查询 cognition_log 中未评估的 query 事件
  ↓
如果有待评估
  → 设置 trace.context["pending_knowledge_eval"] = true
  → 设置 trace.context["knowledge_eval_trigger"] = "goal_completion"
  ↓
Runner 主循环下一次迭代开头检测到标志（agent/core/runner.py:_agent_loop）
  → 清除标志
  → 将 "knowledge_eval" 加入 force_side_branch 队列

触发点 2：压缩

时机：上下文 token 数超过阈值，即将执行压缩

触发逻辑（agent/core/runner.py:_manage_context_usage）：

压缩条件触发
  ↓
查询 cognition_log 中未评估的 query 事件
  ↓
如果有待评估
  → 设置 trace.context["knowledge_eval_trigger"] = "compression"
  → 侧分支队列：["reflection", "knowledge_eval", "compression"]（启用知识提取时）
  →            或 ["knowledge_eval", "compression"]（未启用时）
  → 返回"需要进入侧分支"信号，暂缓压缩

压缩会删除消息历史，必须在压缩前完成评估。

触发点 3：任务结束（兜底）

时机：主路径无工具调用，Agent 即将结束

触发逻辑（agent/core/runner.py:_agent_loop）：

任务即将结束
  ↓
查询 cognition_log 中未评估的 query 事件
  ↓
如果有待评估
  → 设置 trace.context["knowledge_eval_trigger"] = "task_completion"
  → 将 ["knowledge_eval"] 加入 force_side_branch 队列
  → continue（不 break，下一轮执行评估）

侧分支评估流程

侧分支类型

复用 SideBranchContext 机制，类型 "knowledge_eval"（agent/trace/models.py:Message.branch_type）。

评估 Prompt 结构

完整实现：agent/core/runner.py:_build_knowledge_eval_prompt

你是知识评估助手。请评估以下知识查询结果在本次任务执行中的实际效果。

## 当前任务（Mission）       ← trace.task
## 当前 Goal                ← goal_tree.current 的 description
## 待评估知识查询            ← 未评估的 query 事件列表
  对每个 query：展示 query 文本、整合回答、各 source 的 id/task/content
## 评估要求                  ← 按 source_id 逐一评估
## 评估分类                  ← 5 个 status 选项
## 输出格式                  ← JSON

Prompt 中不包含消息历史。LLM 依据对话上下文中已有的执行过程作出判断。

评估输出格式

LLM 直接输出 JSON：

{
  "evaluations": [
    {
      "query_sequence": 42,
      "assessments": [
        {"source_id": "knowledge-a1b2", "status": "helpful", "reason": "..."},
        {"source_id": "knowledge-c3d4", "status": "irrelevant", "reason": "..."}
      ]
    }
  ]
}

即时写入

每次 LLM 回复后立即解析，三种策略降级：整体 JSON → `json 代码块 → 正则裸对象。

解析成功 → 为每个 query 写入对应的 evaluation 事件到 cognition_log。解析失败记日志，不中断。

数据流

知识查询（agent/trace/goal_tool.py:inject_knowledge_for_goal）
  ↓
POST /api/knowledge/ask → KM Agent 整合回答
  ↓
写入 cognition_log: type="query"（含 response + source_ids）
  ↓
  ┌─────────────────────────────────────────────┐
  │  触发点 A：Goal 完成（goal_completion）       │
  │  触发点 B：压缩执行前（compression）          │
  │  触发点 C：任务自然结束（task_completion）    │
  └─────────────────────────────────────────────┘
  ↓
Runner 进入 knowledge_eval 侧分支
  ↓
LLM 按 query 维度、逐 source 评估，输出 JSON
  ↓
写入 cognition_log: type="evaluation"（含 assessments per source）
  ↓
侧分支退出 → 恢复主路径

                    ···

知识提取（reflection 侧分支中 upload_knowledge 成功后）
  ↓
写入 cognition_log: type="extraction"

                    ···

Dream 触发（memory-bearing Agent，详见 agent/docs/memory-plan.md）
  ↓
读取 cognition_log 全部事件 → per-trace 记忆反思
  ↓
写入 cognition_log: type="reflection"

与现有系统的集成点

集成位置	文件	说明
知识查询时写 log	`agent/trace/goal_tool.py:inject_knowledge_for_goal`	`goal(focus=...)` 触发 ask → 写入 `query` 事件
Goal 完成时设置标志	`agent/trace/store.py:update_goal`	设置 `trace.context["pending_knowledge_eval"]`
主循环检测标志	`agent/core/runner.py:_agent_loop`	每轮迭代开头检测，触发 `["knowledge_eval"]`
压缩前触发评估	`agent/core/runner.py:_manage_context_usage`	压缩前检查 pending，先评估再压缩
任务结束兜底	`agent/core/runner.py:_agent_loop`	退出前检查 pending，强制触发评估
侧分支类型	`agent/trace/models.py:Message.branch_type`	Literal 中包含 `"knowledge_eval"`
即时写入评估	`agent/core/runner.py:_agent_loop`	解析 JSON 后写入 `evaluation` 事件
知识提取记录	`agent/core/runner.py`	reflection 侧分支中 upload 成功后写入 `extraction` 事件
记忆反思记录	dream 操作	per-trace 反思后写入 `reflection` 事件
Log 文件管理	`agent/trace/store.py`	待重构：从 entries[] 改为 events[]

cognition-log-plan.md 9.7 KB История Исходник