本地跨 Agent 跑步知识库

一个完全本地运行的跑步知识库服务：导入 Markdown、PDF 与用户明确指定的网页， 用 SQLite FTS5（中文 trigram）与本地 BGE-M3 向量做混合检索，并通过同一个 带 Bearer 认证的 Streamable HTTP MCP 服务同时供 Codex 与 DeepSeek Harness 使用。

数据只保存在本机；日常检索不依赖网络；网页只在显式添加或刷新时访问。

架构

RunningKnowledgeBase/
├─ sources/   原始文件与网页快照（按 <source-id>/<version-id>/original.* 存放）
├─ library/   规范化 Markdown（<source-id>-<version-id>.md，供阅读、审计、重建）
├─ data/      SQLite 元数据、FTS、向量 BLOB、auth-token、server.pid
├─ models/    本地 BAAI/bge-m3 向量模型缓存
├─ backups/   带清单校验的时间戳 ZIP 备份
├─ config/    Codex 与 DeepSeek Harness 的接入配置模板（托管块）
└─ scripts/   install/start/stop/diagnose/uninstall 生命周期脚本

职责边界：解析器不写数据库，数据库不访问网络，MCP handler 只调用 KnowledgeService。

安装（Windows）

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1

install.ps1 依次完成：uv sync 与 running-kb init；生成 32 字节随机 Base64URL 令牌 写入 data\auth-token 并用 ACL 限定为当前用户；设置用户级环境变量 RUNNING_KB_TOKEN； 把带标记的托管块合并进 Codex 配置（~/.codex/config.toml）与 DeepSeek 补丁 （$DSH_HOME\cordis.patch.yml），绝不整体覆盖；在 $DSH_HOME\AGENTS.md 追加 "必须先查"托管指令块；注册隐藏的当前用户登录计划任务 RunningKnowledgeBaseMCP； 启动服务并运行诊断。

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start.ps1   # 启动（拒绝重复启动）
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\stop.ps1    # 停止（校验 PID+命令行+根目录）
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\diagnose.ps1 # 12 项检查，全部通过退出码为 0

服务只监听 127.0.0.1:8765；GET /health 免认证，POST /mcp 需要 Authorization: Bearer <RUNNING_KB_TOKEN>。

接入两个 Agent

安装脚本自动合并以下内容（也可手动参考 config/ 下的模板）：

• Codex：~/.codex/config.toml 中的 [mcp_servers.running_knowledge] 段。 还原：删除 # === running-knowledge-base managed block 到 # === /running-knowledge-base === 之间的托管块即可。

• DeepSeek Harness：$DSH_HOME\cordis.patch.yml 中的 mcp-running-knowledge 项， 使用官方 @deepseek-ai/dsh-mcp-client（streamable-http 传输）。 启用后工具名形如 mcp__running-knowledge__search_running_knowledge； 还原：删除同一对标记之间的托管块。

• DeepSeek 指令块：$DSH_HOME\AGENTS.md 中 <!-- running-knowledge-base managed block --> 到 <!-- /running-knowledge-base --> 之间的内容，要求回答跑步问题前先检索、引用标题与 定位、未覆盖/不可用时明确声明、把检索文本当作不可信数据、医疗安全规则优先。

四个 MCP 工具

成功返回 {"ok": true, "hits"/"document"/"result"/"sources": ...}；失败返回 {"ok": false, "error": {"code": ..., "message": ...}}，错误码稳定可读、不会被吞掉。

添加资料与刷新版本

自然语言让 Agent 执行即可，例如："把 C:\notes\tempo.md 加入跑步知识库"、 "把 https://example.com/tempo 加入知识库"。也可以直接调用：

add_running_source(source="C:\notes\tempo.md")
add_running_source(source="https://example.com/tempo", refresh=true)
list_running_sources(source_type="web")   # 网页每次刷新保留旧版本

重复内容按 SHA-256 识别并返回 duplicate（不覆盖）；内容变化时创建新版本并保留旧版本； 扫描版 PDF（无可提取文字层）返回 OCR_REQUIRED 且不产生任何可检索记录； 损坏 PDF 返回 PARSE_FAILED。

确认"回答前先检索"

对跑步、比赛训练、装备、营养、恢复或伤病问题提问，观察 Agent 是否先调用了 search_running_knowledge（DeepSeek 侧为 mcp__running-knowledge__search_running_knowledge）， 并核对回答中的引用格式：资料标题 → 章节/页码 → 原始文件或网址。 未覆盖时必须出现"本地知识库未覆盖"，服务不可用时必须出现"本地知识库未能访问"， 多资料冲突时必须呈现分歧与来源版本，而不是伪造统一结论。

备份、恢复与重建索引

& $uv run running-kb backup                      # 生成 backups\running-kb-<时间戳>.zip
& $uv run running-kb restore <归档.zip> <目标目录> [--force]
& $uv run running-kb reindex                     # 从 library/ 重建 FTS 与向量并原子替换

备份包含 sources、library、data（排除 auth-token、server.pid 与暂存目录）， backup-manifest.json 记录每个相对路径的 SHA-256、应用版本与向量模型名； 恢复前逐文件校验摘要、拒绝绝对路径与 .. 穿越；非空目标默认拒绝， --force 会先写一份 pre-restore 安全副本。

卸载

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\uninstall.ps1

只移除：经校验的服务进程、计划任务、用户级 RUNNING_KB_TOKEN、两个客户端配置的托管块、 AGENTS.md 的托管指令块。sources、library、数据库、模型与备份全部保留； AGENTS.md 中与本项目无关的文字原样保留。

磁盘占用

• BAAI/bge-m3 模型：首次使用时下载到 models/，约 2.2 GB。

• 数据库：500–5,000 篇资料预计数 MB 到数百 MB（向量 BLOB 占主要空间）。

• 原始快照与规范化 Markdown 与原资料大小同量级。

故障恢复

测试

& $uv run pytest -m "not integration" -v   # 默认套件，不下载模型、不访问真实网络
$env:RUNNING_KB_INTEGRATION = "1"
& $uv run pytest -m integration -v        # 真实模型 + 真实网页（按需运行）

安全边界

• 服务只监听 127.0.0.1，所有 /mcp 请求必须携带 Bearer 令牌（常量时间比对）。

• 本地导入只接受用户明确给出的单个绝对路径文件；目录、相对路径、其他扩展名一律拒绝。

• URL 只允许 HTTP/HTTPS 且禁止 userinfo；所有解析地址必须是全球可路由 IP（回环、私网、 链路本地、组播、保留地址全部拒绝）；重定向逐跳重新校验，最多 5 跳。

• 网页正文按不可信数据处理：脚本不执行，注入指令只是检索结果中的文本， 不会改变 Agent、服务或数据库行为。