final class NoteChunk {
    String chunkId;       // 稳定 ID，建议 sourcePath + headingPath + hash
    String sourcePath;    // 原始 Markdown 路径，用于引用和回跳
    String titlePath;     // 标题层级，例如 AI Agent > MCP > Tool
    int startLine;        // 起始行，便于定位
    int endLine;          // 结束行，便于定位
    String content;       // chunk 正文
    String hash;          // 判断内容是否变化
    List<String> tags;    // frontmatter 或正文标签
}

# MCP 专题学习笔记
## Tool 设计原则
坏工具：run_command(command: string)
问题：权限过大、参数无边界。
## 安全边界
路径越权：resolve 后必须在白名单目录内。

final class ChunkBoundaryRule {
    int maxChars;              // 单个 chunk 最大字符数，防止上下文膨胀
    int overlapChars;          // 段落二次切分时保留少量重叠
    boolean keepTableTogether; // 表格不拆开，否则列含义会丢失
    boolean keepCodeTogether;  // 代码块不拆开，否则字段注释会丢失
    boolean includeParentPath; // 每个 chunk 附带 H1/H2/H3 路径
}

BM25 top20 + Vector top20 -> merge -> metadata filter -> rerank top5 -> context builder

final class RagTrace {
    String traceId;             // 一次问答链路 ID
    String originalQuestion;    // 用户原问题
    String rewrittenQuery;      // 检索改写后的 query
    List<String> recalledIds;   // 初召回 chunk
    List<String> rerankedIds;   // 重排后 chunk
    List<String> usedSources;   // 最终答案引用来源
    boolean refused;            // 是否拒答
    long latencyMs;             // 总耗时
}

{
  "id": "rag-mcp-001",                         // 稳定用例 ID，方便回归对比
  "question": "MCP 的 Tool 和 Resource 区别是什么？",
  "expectedSources": ["01-MCP专题学习笔记.md"], // 至少应命中的笔记或 chunk
  "mustCite": true,                             // 是否要求回答带来源
  "shouldRefuse": false,                        // 负例问题应设为 true
  "checks": ["source_hit", "faithful", "clear"]
}

{
  "query": "MCP 和 RAG 的区别",                 // 用户原始问题。
  "rewrite": ["MCP tool protocol", "RAG retrieval evidence"], // 查询改写结果，用于扩大召回。
  "topK": 8,                                  // 初召回数量，太小容易漏证据，太大增加噪声。
  "retriever": "hybrid",                      // 检索器版本：向量、关键词或混合检索。
  "rerank": "title+score",                    // 重排策略，说明最终证据如何排序。
  "selectedChunkIds": ["01-mcp-309", "02-rag-199"], // 进入最终上下文的 chunk。
  "refused": false                            // 是否因为证据不足而拒答。
}

资料能更新，检索能命中，证据能引用，答案能拒答，错误能复盘。