馆员Librarian

任务简报Brief

学习目标Learning goals

• 按标题切分 runbook，并保留 heading / source / chunk index。

  Split the runbook by heading and preserve heading / source / chunk index.

• 建立知识库并执行 top-k 检索，验证排序与命中。

  Build a knowledge base, run top-k retrieval and verify ordering and hits.

• 理解 scoreThreshold 为什么会把结果全部过滤掉。

  Understand why scoreThreshold can filter every result.

• 用 GenericRAGHook 把检索结果注入 Agent 的调用前阶段。

  Inject retrieved context into the agent's pre-call phase with GenericRAGHook.

核心概念Core concepts

双轨实现Build it twice

先完整跑通一条轨道，再切换重来。两条轨道写出同一种产物，方便直接对照行为。Run one track end to end, then switch and repeat. Both tracks write the same artifact so you can compare behavior directly.

from agentscope.rag import ApproxTokenChunker

sections = split_runbook()  # 每个 Section 带 heading 元数据
chunker = ApproxTokenChunker(
    ApproxTokenChunker.Parameters(chunk_size=160, overlap=20),
)
chunks = await chunker.chunk(sections)
await knowledge.insert_document(
    chunks, document_id="runbook-2026-10",
    document_metadata={"source": "lab/data/runbook.md"},
)

hits = await knowledge.search(
    ["provider rejects request with context_length_exceeded"], top_k=2)
for hit in hits:
    print(hit.score,
          hit.chunk.source,
          (hit.chunk.metadata or {}).get("heading"),
          hit.chunk.chunk_index)

python lab.py check m3
cat work/m3/citations.json

# 期望看到
# PASS CODE: AS-M3-B6NL

python lab.py check m3

SimpleKnowledge knowledge = SimpleKnowledge.builder()
        .embeddingModel(new HashEmbeddingModel())
        .embeddingStore(InMemoryStore.builder().dimensions(256).build())
        .build();

Document doc = new Document(new DocumentMetadata(
        TextBlock.builder().text(section.text()).build(),
        "runbook-2026-10", "chunk-" + section.index(),
        Map.of("heading", section.heading(), "source", "runbook.md",
               "chunk_index", section.index())));
knowledge.addDocuments(List.of(doc)).block();

List<Document> hits = knowledge.retrieve(query,
        RetrieveConfig.builder().limit(3).scoreThreshold(0.0).build())
        .block();

ReActAgent agent = ReActAgent.builder()
        .name("librarian").model(model)
        .hook(new GenericRAGHook(knowledge,
                RetrieveConfig.builder().limit(3).scoreThreshold(0.0).build()))
        .build();

cd lab/java
mvn -q -o compile exec:java -Dexec.args="check m3"

# 期望看到
# PASS CODE: AS-M3-B6NL

cd lab/java && mvn -q -o compile exec:java -Dexec.args="check m3"

Python ↔ Java 差异Python ↔ Java differences

• Python 有 KnowledgeBase + ApproxTokenChunker；Java 用 SimpleKnowledge + InMemoryStore，本关自己按标题切分。

  Python has KnowledgeBase + ApproxTokenChunker; Java uses SimpleKnowledge + InMemoryStore and splits by heading in the lab.

• Java 的 RetrieveConfig 默认阈值 0.5 会过滤掉哈希嵌入；必须显式设 0.0。Python 本关的自定义检索没有这个默认值。

  Java's RetrieveConfig defaults to 0.5, which filters hash embeddings; set 0.0 explicitly. Python's custom retrieval has no such default.

• Python 通过 knowledge.search 直接拿 hits；Java 通过 knowledge.retrieve 返回 List<Document>，引用字段从 payload 读取。

  Python gets hits from knowledge.search; Java calls knowledge.retrieve, returning List<Document> with citation fields in the payload.

常见坑Pitfalls

1. 阈值高于分数分布：所有结果被静默过滤，表现为“检索没有内容”。先打印分数分布，再定阈值。

   A threshold above the score distribution silently filters everything, looking like “no retrieval.” Print the score distribution before choosing a threshold.

2. 维度不一致：嵌入模型输出 256 维，向量库却按 1536 维建索引，入库或检索直接报错。

   Dimension mismatch: a 256-dimensional embedding against a 1536-dimensional store fails on insert or retrieval.

3. 引用只有文本：没有 source/heading/chunk_index，事故复盘时无法定位原始段落，也无法判断答案是否过期。

   Citations with text only: without source/heading/chunk_index, incident review cannot locate the original section or detect stale answers.

4. 切分粒度失衡：块太大导致召回不准，块太小导致上下文缺失。按语义标题切分通常比固定长度更稳。

   Poor chunk granularity: too large hurts precision, too small loses context. Semantic heading splits are usually more stable than fixed length.

领取通行码Claim your pass code

先运行当前轨道的 check。CLI 会打印 PASS CODE、XP 与徽章。粘贴到这里；同一关在每条轨道可各领取一次。Run the check for the current track. The CLI prints PASS CODE plus the exact XP and badge. Paste it here; the same mission can be claimed once on each track.

费曼复述Feynman recall

合上教程，用自己的话讲清机制。关键点覆盖 65%、篇幅 20%、结构 15%；60 分通过并一次性获得 20 XP。Explain the mechanism without looking. Coverage 65%, length 20%, structure 15%; 60 passes and earns +20 XP once.

间隔复习Spaced review

首次领取后会在明天安排复习。按真实感受评分，下一次间隔会自适应。After the first claim a review is scheduled for tomorrow. Rate how it felt; the next interval adapts.