feat(core): GenAI for Beginners 课程借鉴 P2 九项落地

P1 (PR HKUDS#183) 之上的 P2 候选 9 项，全部纯机制、独立模块：

- A6 工具调用轨迹 trace 链: core/observability/trace.py (TraceSpan/TraceChain, 推理片段+参数+结果可查询, JSONL)
- A7 工具语义发现: core/agent_runtime/tools/semantic_hint.py (未命中工具名给语义候选, 接入 registry not-found)
- C4 few-shot 工具说明: EditTool description 加输入到调用到输出示例 (lesson 04 show-and-tell)
- D3 记忆来源元数据: memory_retrieval.compose_memory_injection 带 created_at 时间戳可溯源 (lesson 08/14)
- E2 groundedness 抽查: core/loop/groundedness.py (答案句子 vs 证据 token 覆盖, 可选 LLM-as-judge)
- E3 MCP 供应链审计: core/mcp/audit.py (server 声明清单 + 风险清单 + allowlist 状态)
- E4 LLMOps 指标聚合: core/observability/llmops.py (Quality/Harm/Honesty/Cost/Latency 五维)
- F1 SLM 路由: core/loop/slm_routing.py (按子任务类别 SLM/LLM, env DEEPCODE_SLM_MODEL)
- A9 顺序链 builder: core/loop/sequential_builder.py (SequentialChain + 前序结果占位符传递)

新增 59 项测试 (9 个新测试文件); P1+P2 合计 110 测试全绿; 对 upstream 0 新失败 (基线 12 个 Windows 环境失败 pre-existing)。

Author: DeepCodeClone

core/agent_runtime/tools/registry.py

@@ -82,13 +82,20 @@ def prepare_call(
 
         tool = self._tools.get(name)
         if not tool:
-            return (
-                None,
-                params,
-                (
-                    f"Error: Tool '{name}' not found. Available: {', '.join(self.tool_names)}"
-                ),
-            )
+            # P2-A7: semantic candidates for a hallucinated/misremembered name
+            # (lesson 17 Taskweaver plugin discovery). Execution still requires
+            # the exact registered name + permission engine — the hint only
+            # helps the model recover.
+            try:
+                from core.agent_runtime.tools.semantic_hint import build_miss_message
+
+                message = build_miss_message(name, self.tool_names)
+            except Exception:  # noqa: BLE001 - hint must never break the call
+                message = (
+                    f"Error: Tool '{name}' not found. "
+                    f"Available: {', '.join(self.tool_names)}"
+                )
+            return (None, params, message)
 
         cast_params = tool.cast_params(params)
         errors = tool.validate_params(cast_params)
@@ -112,8 +119,8 @@ async def execute(self, name: str, params: dict[str, Any]) -> Any:
             if isinstance(result, str) and result.startswith("Error"):
                 return result + _HINT
             return result
-        except Exception as e:
-            return f"Error executing {name}: {str(e)}" + _HINT
+        except Exception as e:  # noqa: BLE001 - tool failures are errors-as-data
+            return f"Error executing {name}: {e!s}" + _HINT
 
     @property
     def tool_names(self) -> list[str]:
@@ -150,7 +157,7 @@ async def aclose(self) -> None:
         for name, stack in list(self._owned_server_stacks.items()):
             try:
                 await asyncio.wait_for(stack.aclose(), timeout=timeout_s)
-            except asyncio.TimeoutError:
+            except TimeoutError:
                 errors.append(
                     TimeoutError(
                         f"MCP server '{name}' close timed out after {timeout_s:g}s"
@@ -162,7 +169,7 @@ async def aclose(self) -> None:
                 self._owned_server_stacks.pop(name, None)
         try:
             await asyncio.wait_for(self._exit_stack.aclose(), timeout=timeout_s)
-        except asyncio.TimeoutError:
+        except TimeoutError:
             errors.append(
                 TimeoutError(
                     f"ToolRegistry exit stack close timed out after {timeout_s:g}s"

core/agent_runtime/tools/semantic_hint.py

@@ -0,0 +1,82 @@
+"""P2-A7 (GenAI lesson 17): tool-name miss semantic candidates.
+
+Taskweaver stores plugins as embeddings and lets the LLM *semantically
+search* for the right plugin when the tool count grows. DeepCode routes tools
+by exact name; when the model hallucinates or misremembers a name, the
+registry returns "not found". This module adds the cheap first step: given the
+missed name and the available tool names, suggest the closest candidates by
+token-overlap similarity (no LLM, no embeddings — pure static scoring).
+
+Design guard (lesson 13): semantic discovery is only a *hint* fed back to the
+model as an error message; execution still requires the exact registered name
+plus the permission engine. It never widens the callable surface.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from difflib import SequenceMatcher
+
+_WORD = re.compile(r"[a-z0-9]+")
+
+
+def _tokens(name: str) -> set[str]:
+    return set(_WORD.findall(str(name).lower()))
+
+
+def _name_similarity(a: str, b: str) -> float:
+    """Combined token-overlap + sequence similarity in [0, 1]."""
+    ta, tb = _tokens(a), _tokens(b)
+    if ta and tb:
+        overlap = len(ta & tb) / max(len(ta | tb), 1)
+    else:
+        overlap = 0.0
+    seq = SequenceMatcher(None, a.lower(), b.lower()).ratio()
+    return max(overlap, seq * 0.8)
+
+
+def suggest_tools(
+    missed_name: str,
+    available: Iterable[str],
+    *,
+    top_k: int = 3,
+    min_similarity: float = 0.35,
+) -> list[str]:
+    """Candidates for a missed tool name, best first (empty when none close).
+
+    ``min_similarity`` guards against suggesting unrelated tools; below it the
+    caller should just report "not found" without noise (lesson 17: don't
+    widen the surface with guesses).
+    """
+    scored = [
+        (candidate, _name_similarity(missed_name, candidate))
+        for candidate in available
+        if candidate != missed_name
+    ]
+    scored = [(name, score) for name, score in scored if score >= min_similarity]
+    scored.sort(key=lambda pair: pair[1], reverse=True)
+    return [name for name, _score in scored[:top_k]]
+
+
+def build_miss_message(
+    missed_name: str,
+    available: Iterable[str],
+    *,
+    top_k: int = 3,
+    min_similarity: float = 0.35,
+) -> str:
+    """Error-message helper: "not found" + semantic candidates (if any)."""
+    candidates = suggest_tools(
+        missed_name, available, top_k=top_k, min_similarity=min_similarity
+    )
+    if not candidates:
+        return f"Tool '{missed_name}' not found."
+    return (
+        f"Tool '{missed_name}' not found. Did you mean one of: "
+        + ", ".join(candidates)
+        + "?"
+    )
+
+
+__all__ = ["build_miss_message", "suggest_tools"]

core/harness/tools/files.py

@@ -229,7 +229,13 @@ def description(self) -> str:
         return (
             "Edit a file by replacing old_string with new_string. Matching is "
             "resilient to whitespace/indentation drift; provide enough context "
-            f"for old_string to be unique, or set replace_all.{scope}"
+            "for old_string to be unique, or set replace_all.\n"
+            "Example: file src/a.py contains 'def old(x): return 1'; call "
+            'edit(file_path="src/a.py", old_string="def old(x): return 1", '
+            'new_string="def new(x): return 2") to replace it. '
+            "Use replace_all=true when the same snippet appears multiple times "
+            "and all occurrences should change."
+            f"{scope}"
         )
 
     async def execute(self, **kwargs: Any) -> Any:

core/loop/groundedness.py

@@ -0,0 +1,155 @@
+"""P2-E2 (GenAI lessons 13/14): groundedness spot-check.
+
+Lesson 13 lists *output validation* among the four security-testing methods;
+lesson 14's Honesty/groundedness metric asks "does the answer follow from the
+supplied evidence?". This module provides a pure-mechanism spot-check: split a
+final answer into sentences, and for each sentence that makes an evidential
+claim, verify it is *supported* by the retrieved/injected evidence text.
+
+Scoring (no LLM): a sentence is ``supported`` when a substantial fraction of
+its content tokens appear in the evidence; ``unsupported`` when it claims
+specific facts absent from the evidence. Optionally a caller can supply an
+LLM-as-judge callable for paraphrase-tolerant judgement (``judge_fn``) — the
+module stays mechanism-only by default.
+
+Deliberately a *spot-check*: run on a sample or on critical decisions, never
+on every turn (lesson 14: cost control).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+_STOPWORDS = frozenset(
+    {
+        "the", "a", "an", "and", "or", "but", "is", "are", "was", "were",
+        "to", "of", "in", "on", "for", "with", "at", "by", "from", "as",
+        "that", "this", "it", "its", "we", "our", "you", "your", "i", "me",
+        "my", "be", "been", "being", "have", "has", "had", "do", "does",
+        "did", "will", "would", "can", "could", "should", "not", "no",
+        "yes", "so", "if", "then", "than", "there", "here", "which", "who",
+        "when", "where", "why", "how", "all", "any", "both", "each", "few",
+        "more", "most", "other", "some", "such", "only", "own", "same",
+    }
+)
+
+_SENTENCE = re.compile(
+    r"(?<!\w\.\w.)(?<![A-Z][a-z]\.)(?<=\.|\?|\!)\s+(?=[A-Z0-9])"
+)
+_WORD = re.compile(r"[a-z0-9']+")
+
+_SUPPORT_THRESHOLD = 0.5  # fraction of content tokens present in evidence
+_MIN_SENTENCE_TOKENS = 2  # ignore fragments like "42" or "Done."
+
+
+def _content_tokens(text: str) -> set[str]:
+    return {
+        w
+        for w in _WORD.findall(str(text).lower())
+        if w not in _STOPWORDS and len(w) > 1
+    }
+
+
+def _split_sentences(text: str) -> list[str]:
+    """Split on sentence boundaries, keeping 'src/parser.py.' intact.
+
+    Uses a lookbehind-boundary split (period/question/exclamation followed by
+    whitespace + capital) instead of a naive character class, so dotted paths
+    and abbreviations do not fragment into fake sentences.
+    """
+    parts = re.split(_SENTENCE, str(text))
+    return [p.strip() for p in parts if p.strip()]
+
+
+@dataclass
+class GroundednessVerdict:
+    """One sentence's support verdict."""
+
+    sentence: str
+    supported: bool
+    coverage: float
+    reason: str = ""
+
+
+@dataclass
+class GroundednessReport:
+    """Aggregate spot-check over an answer against its evidence."""
+
+    answer: str
+    evidence: str
+    verdicts: list[GroundednessVerdict] = field(default_factory=list)
+
+    @property
+    def supported_ratio(self) -> float:
+        if not self.verdicts:
+            return 0.0
+        return sum(1 for v in self.verdicts if v.supported) / len(self.verdicts)
+
+    def unsupported_sentences(self) -> list[GroundednessVerdict]:
+        return [v for v in self.verdicts if not v.supported]
+
+
+def check_groundedness(
+    answer: str,
+    evidence: str,
+    *,
+    threshold: float = _SUPPORT_THRESHOLD,
+    judge_fn: Callable[[str, str], bool] | None = None,
+) -> GroundednessReport:
+    """Split ``answer`` into sentences and judge each against ``evidence``.
+
+    ``judge_fn(sentence, evidence) -> bool`` lets a caller plug an
+    LLM-as-judge for paraphrase-tolerant checks; when absent the default
+    token-coverage heuristic runs (pure mechanism, zero cost).
+    """
+    answer = str(answer or "")
+    evidence = str(evidence or "")
+    evidence_tokens = _content_tokens(evidence)
+    report = GroundednessReport(answer=answer, evidence=evidence)
+
+    for sentence in _split_sentences(answer):
+        if judge_fn is not None:
+            try:
+                supported = bool(judge_fn(sentence, evidence))
+            except Exception:  # noqa: BLE001 - judge failure is a soft miss
+                supported = False
+            report.verdicts.append(
+                GroundednessVerdict(
+                    sentence=sentence,
+                    supported=supported,
+                    coverage=1.0 if supported else 0.0,
+                    reason="judge_fn" if supported else "judge_fn (failed or false)",
+                )
+            )
+            continue
+        tokens = _content_tokens(sentence)
+        if len(tokens) < _MIN_SENTENCE_TOKENS:
+            continue  # non-evidential fragment (e.g. a bare number)
+        present = sum(1 for t in tokens if t in evidence_tokens)
+        coverage = present / len(tokens)
+        supported = coverage >= threshold
+        report.verdicts.append(
+            GroundednessVerdict(
+                sentence=sentence,
+                supported=supported,
+                coverage=round(coverage, 3),
+                reason=(
+                    f"{present}/{len(tokens)} content tokens in evidence"
+                    if supported
+                    else (
+                        f"only {present}/{len(tokens)} content tokens in "
+                        "evidence; facts may be fabricated"
+                    )
+                ),
+            )
+        )
+    return report
+
+
+__all__ = [
+    "GroundednessReport",
+    "GroundednessVerdict",
+    "check_groundedness",
+]

core/loop/memory_retrieval.py

@@ -70,8 +70,11 @@ def compose_memory_injection(
     """Render accepted entries as a numbered, data-bounded injection block.
 
     Each entry becomes one ``<untrusted-data>`` block carrying the P1-3
-    restrict clause (reference only, never instructions) plus its source
-    metadata (``source_key`` / ``source`` when present) for traceability.
+    restrict clause (reference only, never instructions) plus traceable
+    metadata — source key, source layer, and creation timestamp when present
+    (P2-D3, lessons 08/14: retrieved results carry locators so answers can be
+    grounded and attributed). Entries are numbered ``[n]``; the model may cite
+    ``[n]`` to attribute a claim to a specific memory.
     Empty when nothing clears the threshold — the caller then uses
     :func:`no_memory_statement` instead of injecting weak matches.
     """
@@ -82,7 +85,11 @@ def compose_memory_injection(
         if not content:
             continue
         source = entry.get("source_key") or entry.get("source") or "memory"
-        header = f"[{index}] (from {source})"
+        created_at = entry.get("created_at") or entry.get("timestamp")
+        header = f"[{index}] (from {source}"
+        if created_at:
+            header += f", at {created_at}"
+        header += ")"
         blocks.append(f"{header}\n{render_data_block(content)}")
     return "\n\n".join(blocks)