Knowledge

Knowledge 模块：一步一步教程

把本地 Markdown、HTTP 文档和 MCP 数据源转成可检索知识，再基于检索结果问答。

步骤 1：首次采集本地 Markdown

mosaic --project-state knowledge ingest \
  --source local_md \
  --path docs \
  --namespace knowledge

预期：输出包含扫描文件数与索引 chunk 数。

步骤 2：大规模文档启用增量模式

mosaic --project-state knowledge ingest \
  --source local_md \
  --path docs \
  --namespace knowledge \
  --incremental \
  --stale-after-hours 24 \
  --max-files 5000 \
  --max-file-size 524288

增量模式会复用未变化 chunk，并清理过期 chunk，适合每天重复跑。

步骤 3：采集 HTTP 文档

mosaic --project-state knowledge ingest \
  --source http \
  --url https://example.com/guide.md \
  --namespace knowledge

mosaic --project-state knowledge ingest \
  --source http \
  --url-file .mosaic/http-knowledge-urls.txt \
  --header-env "Authorization=MOSAIC_DOC_TOKEN" \
  --http-retries 3 \
  --http-retry-backoff-ms 200 \
  --continue-on-error \
  --report-out .mosaic/reports/knowledge-http-ingest.json \
  --namespace knowledge

步骤 4：采集 MCP 文档

mosaic --project-state knowledge ingest \
  --source mcp \
  --mcp-server local-mcp \
  --mcp-path docs \
  --namespace knowledge

MCP 采集会使用该 server 的 cwd 作为根目录，可选子路径。

步骤 5：先做检索质量验证

mosaic --project-state knowledge search "gateway retry" --namespace knowledge --limit 20 --min-score 4
mosaic --project-state --json knowledge search "sandbox policy" --namespace knowledge --limit 10 --min-score 6

步骤 6：基于检索问答

mosaic --project-state knowledge ask "How does retry policy work?" --namespace knowledge --top-k 8 --min-score 6
mosaic --project-state --json knowledge ask "What is the sandbox default?" --namespace knowledge --top-k 6 --min-score 6
mosaic --project-state --json knowledge ask "What is the sandbox default?" --namespace knowledge --top-k 6 --min-score 6 --references-only

knowledge ask 会先检索再拼接上下文，`--min-score` 可先过滤弱命中，`--json` 输出包含 `references` 便于追溯。

步骤 7：批量评估检索质量

mosaic --project-state --json knowledge evaluate \
  --query "gateway retry policy" \
  --query "sandbox default profile" \
  --query-file .mosaic/knowledge-eval-queries.txt \
  --namespace knowledge \
  --top-k 8 \
  --min-score 6 \
  --report-out .mosaic/reports/knowledge-eval.json

knowledge evaluate 只做检索评估：输出每条 query 命中情况，以及覆盖率、平均分、p50/p90 top score 等汇总指标。

步骤 8：基线与回归闸门

mosaic --project-state --json knowledge evaluate \
  --query "gateway retry policy" \
  --namespace knowledge \
  --history-window 20 \
  --update-baseline

mosaic --project-state --json knowledge evaluate \
  --query "gateway retry policy" \
  --namespace knowledge \
  --max-coverage-drop 0.05 \
  --max-avg-top-score-drop 1.0 \
  --fail-on-regression

默认 baseline 路径为 .mosaic/data/knowledge-eval-baselines/<namespace>.json，可用 --baseline 覆盖。

每次 evaluate 都会将趋势样本追加到 .mosaic/data/knowledge-eval-history/<namespace>.jsonl，JSON 输出会给出与上次评估的 delta 以及窗口统计。

步骤 9：超大 Markdown 数据集调优

mosaic --project-state knowledge ingest \
  --source local_md \
  --path docs \
  --namespace product \
  --incremental \
  --max-chunk-bytes 4096 \
  --chunk-overlap-bytes 384 \
  --max-content-bytes 8192 \
  --stale-after-hours 12 \
  --retain-missing

推荐策略：按业务域拆 namespace，频繁增量采集，并结合 chunk/index 参数做容量控制。

步骤 10：存储路径与可观测点

• 项目模式暂存路径：.mosaic-knowledge/sources/<namespace>/<source>/
• XDG 模式暂存路径：<xdg-root>/knowledge/sources/<namespace>/<source>/
• 检索索引与状态统计仍使用 memory namespace 存储。
• knowledge ingest --report-out 现已统一支持 local_md/http/mcp 三类 source。

步骤 11：数据集生命周期清理

mosaic --project-state --json knowledge datasets list
mosaic --project-state --json knowledge datasets list --namespace knowledge
mosaic --project-state --json knowledge datasets remove knowledge --dry-run
mosaic --project-state --json knowledge datasets remove knowledge

先用 datasets list 查看 staged sources、memory index、evaluate baseline/history，再通过 remove --dry-run 预演清理。