内容
# 波扎尔语料库 MCP
用于从 Zoltan Pozsar PDF 语料库中构建本地、源引用的知识库的 Rust 工具，通过只读 MCP 服务器公开，生成离线跨资产市场环境快照，并编写顾问就绪的环境。
该项目不包括实时市场数据摄入、交易信号、回测、投资组合管理、经纪人适配器、交易所适配器或执行代码。市场环境是离线的，仅基于文件。
## 为什么选择波扎尔
Zoltan Pozsar 的工作很重要，因为它将宏观经济学与资产负债表基础设施联系起来，而资产负债表基础设施通常驱动市场：抵押品、回购、欧元美元、FX 掉期、储备、影子银行、安全资产和商品链接货币。他的著作有助于研究流动性如何通过金融系统流动，以及为什么压力可能出现在标准宏观指标所涵盖的范围之外。
该项目将该语料库转化为本地、源引用的研究层，以便代理和分析师可以检索宏观或流动性问题背后的原始段落，而不是依赖无来源的摘要。
## 功能
- 在 `docs/` 中显现本地 PDF
- 从 PDF 中提取页面级文本
- 将提取的页面与源元数据分块
- 使用确定性宏观/流动性主题标记块
- 在 `data/knowledge/` 下编写可复制的工件
- 使用 `corpus inspect` 验证生成的语料库工件
- 运行只读 MCP 服务器进行源引用语料库搜索
- 为未来的矢量索引准备 Qdrant 兼容的负载
- 从本地价格 CSV 文件构建确定性市场环境 JSON
- 构建将语料库流动性信号与市场环境相结合的确定性顾问快照
- 从顾问快照构建确定性顾问策略 JSON，而不产生交易建议
## 仓库布局
```text
crates/
advisor-core/ 离线顾问快照合成逻辑
advisor-policy/ 确定性顾问策略评估逻辑
pozsar-kb/ 核心语料库库：显现、提取、切分、主题、检查
corpus-cli/ 用于构建和检查生成的语料库工件的 CLI
market-context/ 离线跨资产市场环境库
pozsar-mcp/ 生成的语料块上的只读 MCP 服务器
docs/ 源地图、使用文档和忽略的下载 PDF
data/knowledge/ 生成的语料库工件；被 git 忽略
data/market/ 本地/样本市场 CSV 输入和生成的 JSON 环境
data/advisor/ 生成的顾问快照和策略工件
```
## 本地 PDF 输入
该仓库不重新分发波扎尔 PDF。`docs/` 中的 PDF 文件被 git 忽略，并从发布存档中排除。用户通过 [docs/SOURCE_MAP.md](docs/SOURCE_MAP.md) 和 `Zoltan-Pozsar-Bibliography.html` 中记录的公共源链接下载文档。
`corpus download-sources` 可以重建本地 PDF 集，`corpus verify-sources` 在语料库生成之前检查本地 PDF 哈希和源 URL。
详见 [docs/README.md](docs/README.md)。
## 新克隆安装和运行
有关更短的引导路径和原始 MCP 演示搜索，请参阅 [docs/QUICKSTART.md](docs/QUICKSTART.md)。
从一个新的克隆：
```bash
git clone <repo-url>
cd zp_base
cargo build --workspace
cargo run -p corpus-cli -- download-sources --docs docs --source-map docs/SOURCE_MAP.md
cargo run -p corpus-cli -- verify-sources --docs docs --bibliography Zoltan-Pozsar-Bibliography.html --source-map docs/SOURCE_MAP.md
cargo run -p corpus-cli -- build --docs docs --out data/knowledge
cargo run -p corpus-cli -- inspect --out data/knowledge
cargo build --release -p pozsar-mcp
target/release/pozsar-mcp --version
```
使用生成的块工件运行 MCP 服务器：
```bash
POZSAR_CHUNKS_JSONL="$PWD/data/knowledge/chunks/pozsar_chunks.jsonl" \
target/release/pozsar-mcp
```
MCP 服务器使用标准输入/输出，因此此命令等待 MCP 客户端而不是打印交互式提示。
## 构建语料库
首先下载本地 PDF 语料库：
```bash
cargo run -p corpus-cli -- download-sources --docs docs --source-map docs/SOURCE_MAP.md
```
```bash
cargo run -p corpus-cli -- build --docs docs --out data/knowledge
```
这会写入：
```text
data/knowledge/manifest.json
data/knowledge/extracted_pages.jsonl
data/knowledge/chunks/pozsar_chunks.jsonl
```
## 检查语料库
```bash
cargo run -p corpus-cli -- inspect --out data/knowledge
```
检查命令报告文档/页面/块计数、空页面、无块页面、验证问题和主题分布。如果发现验证问题，它会以非零退出。
## 构建市场环境
从本地 CSV 文件生成离线市场环境快照：
```bash
cargo run -p corpus-cli -- market-context \
--prices data/market/sample_prices.csv \
--out data/market/context.json
```
输入 CSV 列：
```csv
date,symbol,close
2026-06-24,BTC,101000
2026-06-25,BTC,103000
```
输出包括每种资产的回报、20 个观测周期的趋势、年化波动率、回撤和确定性的跨资产制度摘要。这是仅限本地的市场环境，不会产生交易建议。
## 获取实时市场环境
通过 Yahoo 兼容的 CSV 适配器获取实时历史收盘价，将它们标准化为 `date,symbol,close`，重用现有的市场环境计算，并以健康侧车的形式写入相同的离线 `MarketContext` JSON 格式：
```bash
cargo run -p corpus-cli -- fetch-market-context \
--provider yahoo \
--assets BTC,ETH,SPY,QQQ,GLD,TLT,DXY \
--lookback 60 \
--out data/market/context.json
```
该命令打印新鲜度、缺失资产、陈旧价格和历史不足的健康报告。如果发现阻止健康问题的健康问题，它会以非零退出。MCP 和顾问工具仍然只使用生成的 `context.json`；它们不会直接获取实时数据。
生成的文件：
```text
data/market/context.json
data/market/context.health.json
```
## 构建顾问快照
将语料库流动性证据与本地市场环境快照相结合：
```bash
cargo run -p corpus-cli -- advisor-snapshot \
--chunks data/knowledge/chunks/pozsar_chunks.jsonl \
--market-context data/market/context.json \
--market-health data/market/context.health.json \
--question "抵押品稀缺对跨资产流动性有何影响？" \
--assets BTC,ETH,SPY,QQQ,GLD,TLT,DXY \
--themes collateral,dollar_liquidity,repo \
--out data/advisor/snapshot.json
```
输出包括源引用的流动性信号、市场环境、每种资产的宏观/市场对齐和综合制度标签，例如 `macro_tightening_market_risk_on`。这是未来顾问层的确定性环境，而不是交易建议。
如果提供 `--market-health`，其 `as_of` 必须与市场环境 `as_of` 匹配；否则，陈旧或不匹配的健康侧车将被拒绝。
## 构建顾问策略
将顾问快照转换为确定性资产评估：
```bash
cargo run -p corpus-cli -- advisor-policy \
--snapshot data/advisor/snapshot.json \
--out data/advisor/policy.json
```
策略输出包括每种资产的立场、信心、驱动因素、风险和所需检查。它仅限于环境：不发出交易建议、仓位调整或执行指令。
## 验证 PDF 源
```bash
cargo run -p corpus-cli -- verify-sources \
--docs docs \
--bibliography Zoltan-Pozsar-Bibliography.html \
--source-map docs/SOURCE_MAP.md
```
验证器比较本地忽略的 `docs/*.pdf` 文件与参考文献中的直接 PDF 链接，检查每个源映射 URL 和 SHA-256 哈希，并在不匹配时以非零退出。
## 评估检索
对块工件运行固定测试的黄金查询检查：
```bash
cargo run -p corpus-cli -- eval-search \
--chunks data/knowledge/chunks/pozsar_chunks.jsonl \
--cases eval/fixtures/pozsar_eval.json \
--limit 5 \
--tool research-question \
--format text \
--fail-fast \
--output data/eval/research-question-report.json
```
评估命令报告每个用例的通过/失败、返回的引用、预期的引用排名、缺失的引用、类别摘要和汇总计数。使用 `--tool search` 测试原始本地搜索或 `--tool research-question` 测试研究包路径。使用 `--format json` 进行 CI 或机器可读回归工件。使用 `--output <path>` 将报告写入磁盘，同时仅将输出路径和摘要打印到标准输出。使用 `--fail-fast` 在第一个失败用例后停止。如果任何预期的引用缺失或排名太低，则以非零退出。
评估用例可以包括可选的 `max_rank`，要求每个预期的引用出现在该排名之前：
```json
{
"name": "collateral dollar liquidity",
"category": "dollar_liquidity",
"notes": "核心流动性管道查询；应早期显示安全资产过剩。",
"query": "collateral dollar liquidity",
"themes": ["collateral"],
"expected_citations": ["The_Safe_Asset_Glut.pdf:7"],
"max_rank": 3
}
```
## 运行 MCP 服务器
默认情况下，MCP 服务器读取 `data/knowledge/chunks/pozsar_chunks.jsonl`：
```bash
cargo run -p pozsar-mcp
```
指向另一个块工件或市场环境快照：
```bash
POZSAR_CHUNKS_JSONL=/path/to/pozsar_chunks.jsonl \
POZSAR_MARKET_CONTEXT_JSON=/path/to/context.json \
cargo run -p pozsar-mcp
```
可用的 MCP 工具：
- `get_pozsar_kb_status`
- `list_pozsar_docs`
- `list_pozsar_themes`
- `search_pozsar_kb`
- `explain_pozsar_search`
- `read_pozsar_source`
- `read_pozsar_page_context`
- `answer_pozsar_research_question`
- `extract_pozsar_liquidity_signals`
- `get_pozsar_advisor_snapshot`
- `get_pozsar_advisor_policy`
搜索结果以 `file_name:page` 格式包含引用。
在构建发布二进制和本地工件后，运行原始 MCP 顾问快照演示：
```bash
scripts/demo-mcp-advisor.sh
```
有关 Claude Desktop 和 Codex 配置示例、工具参数和响应形状，请参阅 [docs/MCP.md](docs/MCP.md)。
在不启动标准输入/输出服务器的情况下，检查 MCP 二进制版本：
```bash
cargo run -p pozsar-mcp -- --version
```
在 `dist/` 下创建一个发布压缩包：
```bash
scripts/package-release.sh
```
使用构建的语料库对软件包进行烟雾测试：
```bash
scripts/smoke-package.sh \
dist/pozsar-corpus-mcp-0.1.0-<target>.tar.gz \
data/knowledge/chunks/pozsar_chunks.jsonl
```
有关示例 MCP 提示和评估报告，请参阅 [docs/EXAMPLES.md](docs/EXAMPLES.md)。
有关完整的维护人员发布流程，请参阅 [RELEASE.md](RELEASE.md)。
在公共发布之前，请完成 [docs/PUBLICATION_CHECKLIST.md](docs/PUBLICATION_CHECKLIST.md)，尤其是 PDF 重新分发审查。
## 许可证
该项目的源代码和文档根据 MIT 许可证分发；请参阅 [LICENSE](LICENSE)。
波扎尔 PDF 不由该仓库或发布包分发。用户从 [docs/SOURCE_MAP.md](docs/SOURCE_MAP.md) 中列出的公共源 URL 下载文档，这些文档仍然受其原始出版商的条款约束。
## 开发检查
```bash
cargo fmt --all --check
cargo check --workspace
cargo test --workspace
```
## Git 策略
跟踪：
- Rust 工作区源
- `Cargo.lock`
- `LICENSE` 和 `CHANGELOG.md`
- README 文件
- 源映射和参考文献文件，用于重建 PDF
- 测试和小型固定装置
忽略：
- `target/`
- `data/knowledge/`
- `dev_docs/`
- `docs/*.pdf`
- 本地环境/日志文件
