Agent 知识系统与推理日志开发规范

维护者: DF 核心团队
最后更新: 2026-05-03
适用范围: 后端 Agent、知识库路由、推理日志、前端知识面板、保存经验流程

本规范记录已经落地的 Agent 知识系统、推理日志和经验提炼实现。设计背景和历史计划见 design-docs/15-agent-knowledge-reasoning-log.md；仍未完成的后续优化见 design-docs/15.2-knowledge-system-followup-improvements.md。

1. 架构概览

Agent 知识系统由三部分组成：

知识库存储在当前用户 home 下：

<user_home>/
└── knowledge/
    ├── rules/
    └── experiences/

rules 只允许扁平 .md 文件；experiences 最多允许一级子目录。所有知识文件访问必须通过 KnowledgeStore，不要在调用方直接拼接 Path(user_home) / "knowledge" / user_input。

2. 知识文件格式

知识文件是 Markdown + YAML front matter：

---
title: ROI 计算标准
tags: [finance, computation]
created: 2026-04-27
updated: 2026-04-27
source: manual
---

ROI = (revenue - cost) / cost

通用字段：

Rules 额外支持：

KnowledgeStore.write() 会在缺少 front matter 时补一个最小头部，并按 KNOWLEDGE_LIMITS 校验正文长度。

3. KnowledgeStore

典型用法：

from data_formulator.knowledge.store import KnowledgeStore

store = KnowledgeStore(user_home_path)
items = store.list_all("rules")
content = store.read("rules", "roi.md")
store.write("experiences", "cleaning/missing-values.md", content)
store.delete("experiences", "sales/quarterly-trend.md")
results = store.search("missing values", categories=["experiences"])

必须遵守：

• 只使用 rules、experiences 两个 category。
• 所有知识文件必须是 .md。
• rules 路径只能是 file.md；experiences 路径最多是 folder/file.md。
• 路径穿越、绝对路径和 symlink 逃逸由 ConfinedDir 拦截。
• 搜索结果只返回摘要，完整内容通过 read() 读取。

搜索算法

KnowledgeStore.search() 使用分词 + 多字段加权匹配。核心逻辑在 _match_score() 中，_tokenize_query() 负责将 query 拆分为关键词。

分词规则（_tokenize_query）：

• 空格分词后过滤英文停用词和长度 ≤ 2 的 ASCII 短词。
• 中英混合 token（如 "帮我分析ROI"）自动拆分为 CJK 段和 ASCII 段，各自独立参与匹配。
• 纯中文 token 保持整串，以子串方式匹配（暂不做中文分词，后续可引入 jieba）。

评分规则（_match_score）：

对 N 个 token 中的每一个，按字段命中加权（分数除以 N 以归一化）：

额外加分项（不除以 N）：

调用方式：

results = store.search(
    "分析各区域的ROI",
    categories=["rules", "experiences"],
    max_results=5,
    table_names=["sales_data", "regions"],  # 可选，用于 tag 加分
)

alwaysApply=true 的 rules 始终被搜索跳过（它们通过 system prompt 注入）。

4. Knowledge API

所有知识 API 在 py-src/data_formulator/routes/knowledge.py，Blueprint 前缀为 /api/knowledge。所有 application error 遵循统一错误协议：HTTP 200 + status: "error"。

路由通过 get_identity_id() 和 get_user_home(identity_id) 定位当前用户目录。不要让前端传入用户目录、workspace 目录或绝对路径。

5. 推理日志

ReasoningLogger 是开发调试工具，不是用户可见功能。日志写入：

DATA_FORMULATOR_HOME/
└── agent-logs/
    └── <date>/
        └── <safe_identity_id>/
            └── <session_id>-<agent_type>.jsonl

开关由 DF_AGENT_LOG 控制：

DataAgent 当前记录的主要事件：

注意：当前 on 模式仍会记录 user_question / query 等问题文本；如果新增埋点涉及 credentials、连接串、tokens 或原始数据正文，必须先脱敏或只记录摘要。

6. Agent 知识集成

路由层通过 routes/agents.py 的 _get_knowledge_store(identity_id) 创建 KnowledgeStore，并传给对应 Agent。知识不可用时必须优雅降级，不能影响原有 Agent 流程。

模式 A：Rules 系统提示词注入

适用于所有 Agent（DataAgent、DataTransformationAgent、DataRecAgent、DataLoadingAgent、InteractiveExploreAgent、ChartInsightAgent）。只把 alwaysApply != false 的 rules 注入系统提示词；非 always-apply rules 通过搜索注入。

所有 Agent 统一通过 KnowledgeStore 的两个方法完成规则注入：

• load_always_apply_rules() — 返回 [{"title":..., "body":...}] 列表，适用于需要额外处理原始数据的场景（如 DataAgent 需追踪 _injected_rules 标题）。
• format_rules_block(rules=None) — 直接返回格式化好的 prompt 块（## User Rules + ### {title}\n{body}），内部自动加载规则并处理异常；也可传入 load_always_apply_rules() 预加载结果避免二次读取。

各 Agent 典型用法：

# 简单场景（大多数 Agent）—— 一行搞定
if self._knowledge_store:
    prompt += self._knowledge_store.format_rules_block()

# 需要追踪注入了哪些规则（DataAgent）
if self._knowledge_store:
    rules = self._knowledge_store.load_always_apply_rules()
    self._injected_rules = [r["title"] for r in rules]
    prompt += self._knowledge_store.format_rules_block(rules)

# 需要与 agent_coding_rules 合并（DataRecAgent / DataTransformationAgent）
knowledge_rules = knowledge_store.load_always_apply_rules() if knowledge_store else []
combined_rules = _combine_rules(agent_coding_rules, knowledge_rules)

模式 B：Library 知识上下文注入

适用于 DataAgent、DataLoadingAgent、InteractiveExploreAgent、ChartInsightAgent。运行时搜索相关 experiences 条目，把摘要注入上下文。KnowledgeStore.search() 自动跳过 alwaysApply=true 的 rules，避免与 system prompt 重复注入。

• DataAgent 使用 _search_relevant_knowledge(user_question, table_names) 搜索，user question 作为 query，table_names 通过 search() 的 table_names 参数独立传入以获得 tag 加分。
• DataLoadingAgent 使用最近一条用户消息作为搜索 query；无用户消息时回退到 "data loading cleaning preparation"。

模式 C：DataAgent 工具调用

DataAgent 提供两个内部工具：

• search_knowledge(query, categories?)：返回匹配条目的 category、title、path、snippet。
• read_knowledge(category, path)：读取完整 Markdown 内容。

工具错误应返回安全、简短的文本结果，并在服务端日志中记录异常类型；不要把 traceback 或内部路径返回给 LLM/用户。

7. 经验提炼

前端只在当前可见分析链的 leaf derived table 上展示“保存为经验”按钮。leaf table 的判断标准是：该表是 derived table，且没有其他未 anchored derived table 从它继续派生。

SaveExperienceButton 构建 experience_context 时，从触发保存的 leaf table 沿当前 Redux 中仍存在的链向上回溯，只收集当前可见链上的：

• dialog
• interaction
• result_summary
• execution_attempts

用户已删除的中间节点不会进入经验上下文。execution_attempts 只携带失败/修复代码的结构化摘要，不应携带失败代码或修复代码原文。

后端 /api/knowledge/distill-experience 使用前端提交的 experience_context 调用 ExperienceDistillAgent，然后写入 knowledge/experiences/。ExperienceDistillAgent 的 prompt 引导提取可复用的通用方法论，而非特定案例细节。这个端点不读取管理员推理日志。

8. 前端实现约定

相关模块：

所有用户可见文本必须走 i18n。知识系统当前使用 common.json 的 knowledge.* key，新增 key 时必须同步更新 src/i18n/locales/en/common.json 和 src/i18n/locales/zh/common.json。

跨组件刷新使用自定义事件：

window.dispatchEvent(new CustomEvent('knowledge-changed', {
    detail: { category: 'experiences' },
}));

useKnowledgeStore 监听该事件并刷新指定类别。

9. 新模块清单

添加新 Agent 或修改知识集成时：

• 明确该 Agent 需要 rules、experiences 中哪些类别。
• 在 Agent 构造函数中添加可选 knowledge_store 参数。
• 在 routes/agents.py 对应路由中传入 _get_knowledge_store(identity_id)。
• 选择集成模式：Rules 注入、上下文注入或 DataAgent 工具调用。
• 搜索失败时优雅降级，并用 logger.warning(..., exc_info=True) 记录。
• 通过 KnowledgeStore 访问知识文件，不直接操作 knowledge/ 文件系统。
• 涉及推理日志时尊重 DF_AGENT_LOG 开关，并避免记录敏感信息。
• 涉及前端文本时同步 i18n key。
• 为新行为添加聚焦测试；后端至少运行相关 pytest。

10. 测试

后端相关测试：

python -m pytest \
  tests/backend/agents/test_reasoning_logger.py \
  tests/backend/knowledge/test_knowledge_store.py \
  tests/backend/routes/test_knowledge_routes.py \
  tests/backend/agents/test_agent_knowledge_integration.py -q

前端相关流程当前主要依赖手动验证和通用 yarn test。修改 KnowledgePanel、SaveExperienceButton 或 leaf-table 逻辑时，至少手动覆盖：

• 创建、编辑、删除 rules / experiences。
• 搜索知识条目。
• 多步 DataAgent 分析后只在最终 leaf table 显示保存经验按钮。
• 删除中间 table 后，保存经验上下文不包含已删除节点。
• 经验保存成功后知识面板自动刷新。

11. 已知后续优化

以下事项尚未完全落地，不应在新代码中假定已经完成：

• KnowledgeStore.search() 仍是整串子串匹配 → 已改为分词 + 多字段加权匹配（2026-05-03）。
• test_relevant_knowledge_injected 仍允许无命中兜底，搜索注入效果需要加强测试。
• KnowledgeStore.list_all() / search() 内部仍有 Path.read_text() 风格不统一问题，安全影响低但建议改成 jail.read_text(rel)。
• 中文搜索目前保持整串子串匹配（CJK/ASCII 混合文本中的 ASCII 部分会独立拆出），后续可引入 jieba 做中文分词。
• 知识预加载（后台线程 + 0.5s 超时 + 降级）尚未实现，当前仍为同步搜索。见 design-docs/21 §4。
• 上下文预算管理（分块 token 预算 + trajectory 压缩）尚未实现。见 design-docs/21 §6。