# 福彩3D 分析 MCP Server · 一个生产级 Agent 工具协议实践

> 把「福彩3D 开奖分析」做成一套 **干净、可验证、可复盘** 的 MCP（Model Context Protocol）工具服务器。
> 它不是「预测神器」，而是一个用来展示 **Agent 工具协议工程能力** 的真实项目：长任务闭环执行、状态/记忆管理、评测与安全边界。

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-45%20%2B-brightgreen.svg)](src)

---

## ⚠️ 诚实声明（请先读）

- **福彩3D 是独立均匀随机序列**。在足够样本下，任何数字、和值、形态的出现频率都收敛到理论均匀分布；**没有任何选号方法能提高中奖概率**。
- 本系统的全部工具都**不预测开奖号码**。它们做的是：数据导入、统计检验、覆盖效率优化、资金风控、以及把结构化信号用你自己的大模型「翻译」成自然语言。
- 单注期望回报恒约为 **−48%**（返奖率约 52%）。长期参与的数学期望为负。**理性投注，量力而行，切勿把它当作投资。**
- 项目价值在于 **工程实践**，不在于「中奖」。下面的「三大工程支柱」才是它被设计出来的真正理由。

---

## 为什么做这个项目（以及为什么适合作为 Agent 基础设施样本）

2026-08-04 DeepSeek 发布 Harness 内测招募，一场招募帖演变成 Agent 开源生态大摸底：**769 位开发者、712 个开源仓库、合计 120 万 Stars**，评论区秒变「开源 Agent 路演」。文章点名了 Agent 走向工程化需要持续升级的三张能力版图：

1. **长任务执行能力** —— Agent 能否稳定、持续地完成多步骤、多工具协作的真实任务；
2. **上下文与记忆管理** —— 长周期任务中如何保存状态、理解历史、正确调用已有信息；
3. **评测与安全** —— 工具调用是否可验证、是否有边界、能否被放心部署。

本项目恰好是这三张版图的**具体落地样本**：

| Agent 工程方向（文章点名） | 本项目对应设计 |
|---|---|
| 长任务执行 | `import_draws → engine_sync_signal → spin_log → spin_settle → spin_experiment_report` 是一条**严格前瞻（forward-test）闭环**，Agent 先锁指纹、隔期才结算，杜绝「用未来数据回测当下」的数据泄露 |
| 状态/记忆 | 台账（`combo_ledger.json`）、前瞻日志（`spin_forward_log.json` / `qcrm_forward_log.json`）、演化状态全部落盘为确定性 JSON；指纹锁保证实验可复现 |
| 评测/安全 | 所有「信号」都对照**随机基线**做统计检验（KS / 卡方 / SPRT / Wilson 区间）；Bonferroni 校正防多次检验作弊；命中即 `ACCEPT_H0` 诚实地「未发现优于随机」；`kelly_guard` 强制预算红线 |

> 把「预测」从系统里拿掉，反而让它能通过工程审查——这正是成熟 Agent 工具该有的样子。

---

## 架构

```mermaid
flowchart LR
  LLM[你的 LLM 客户端<br/>Cherry Studio / Claude Desktop / 任意 MCP 客户端] -- MCP stdio --> S[3dcaipiao-mcp]
  subgraph 阳核[阳核 · 纯本地数学引擎（零网络）]
    S --> B[base-tools · 3D 查询/统计/回测]
    S --> P[pascal · Pascal 数论特征]
    S --> Q[qcrm · 量子混沌 / RMT 信号]
    S --> SP[spin_drive · 自旋驱动层]
    S --> SE[sum_engine · 和值函数方程]
    S --> C[combination · 胆拖/覆盖优化/风控台账]
  end
  S --> L[ai_interpret_signal · 可选 LLM 叙述层]
  C --> D[(data/ 开奖数据 + 台账 JSON)]
```

- **阳核 6 大引擎**全部为确定性本地计算（生成函数、卷积递推、RMT 随机矩阵、KS/卡方检验），**不依赖任何外部 API 即可运行**。
- **可选 LLM 叙述层** `ai_interpret_signal`：仅在用户配置了自己的大模型 API 后才联网；未配置时优雅降级为模板化解读，**绝不静默造假**。

---

## 快速开始（三步，无需编译）

本仓库已提供**单文件打包产物** `dist/3dcaipiao.mjs`，只需 Node.js（≥18）即可运行，**无需 `npm install`**。

### 1. 在你的 MCP 客户端里「新建 → 添加 JSON」

以 Cherry Studio / Claude Desktop 为例，把下面这段加入 `mcpServers`（把路径改成你机器上的绝对路径）：

```json
{
  "mcpServers": {
    "3dcaipiao": {
      "command": "node",
      "args": ["D:/Agent/3Dcaipiao/dist/3dcaipiao.mjs"],
      "env": {
        "LLM_BASE_URL": "https://api.deepseek.com/v1",
        "LLM_API_KEY": "sk-你的密钥",
        "LLM_MODEL": "deepseek-chat"
      }
    }
  }
}
```

- 只想用本地分析引擎？**删掉整个 `env` 段即可**，45 个数学工具照常工作。
- 想用你自己的大模型做自然语言解读？二选一：
  - （推荐）在客户端 JSON 里填 `env` 的 `LLM_*`；或
  - 复制 `config.example.json` 为 `config.json`，填入 `llm.api_key`，把它放在 `dist/` 同级目录。

### 2. 让它"读懂"开奖数据

仓库已附带 100 期样例 `data/sample_3d_100期开奖数据.md`。直接让 Agent 调用：

```
import_draws  →  engine_sync_signal(budget=40)
```

`engine_sync_signal` 会一次性跑完：数据完整性、随机性（数字卡方）、和值分布（KS 检验）三大健康检查，并给出诚实结论（例如 `data_ok / randomness_ok / sum_dist_ok` 全 `true`，说明序列与理论随机分布无显著差异）。

### 3. 跑一条可追溯的前瞻实验（展示"长任务 + 记忆"）

```
spin_system_state(target_qihao="2026105")   # 锁定指纹、生成预测
spin_settle(entry_id="last", actual="3|2|1") # 隔期结算（不回测）
spin_experiment_report()                     # Wilson 95% 区间 vs 随机基线
```

这条链路完整呈现了三类工程能力：**闭环执行 / 状态落盘 / 可验证评测**。

---

## 工具总览（45+，全部 3D）

| 引擎 | 代表工具 | 做什么 |
|---|---|---|
| `base-tools` | `get_fucai3d_draw` `analyze_history` `score_numbers` `run_backtest` `monte_carlo_sim` `generate_bet_plan` `build_period_list` | 3D 开奖查询、统计检验、评分、回测、风险控制方案 |
| `pascal` | `pascal_*` | Pascal 数论特征提取（奇偶/质合/模运算模式） |
| `qcrm` | `qcrm_system_state` `qcrm_settle` `qcrm_experiment_report` | 量子混沌 / 随机矩阵（RMT）信号与严格前瞻台账 |
| `spin_drive` | `spin_field_tensor` `inflation_spectrum` `angular_momentum_cascade` `spin_orbit_coupling` `gravitational_collapse_selector` `helicity_projection` `spin_system_state` `spin_settle` `spin_experiment_report` | 自旋驱动层（宇宙自旋第一性原理的数学映射）+ 3D 前瞻闭环 |
| `sum_engine` | `sum_engine_signal` `sum_engine_candidates` `sum_engine_state` | 和值概率质量函数（生成函数/卷积递推）、KS 检验、按和值出注单 |
| `combination` | `dantuo_build` `dantuo_recommend` `coverage_optimizer` `combo_ledger_record` `combo_ledger_settle` `combo_ledger_summary` `kelly_guard` `import_draws` `engine_sync_signal` | 胆拖引擎、覆盖优化器、组合风控台账、数据导入与同步信号 |
| `llm`（可选） | `ai_interpret_signal` | 用你自己的大模型把信号转成自然语言（未配置则降级） |

> 注：本仓库为**纯福彩3D**版本（已从上游裁剪掉双色球工具并清除其中的硬编码密钥），保持单一主题、干净可发布。

---

## 工程亮点（给评审/同行看）

### 1. 严格前瞻（Forward-Test）防数据泄露
`spin_log` / `qcrm` 台账采用**指纹锁 + 隔期结算**：预测时只写入 `target_qihao` 与指纹，结算时严格使用**未来真实开奖**比对。报告里的 `Wilson 95% 置信区间` 若包含随机基线，则结论必然是「未发现优于随机」——从源头杜绝「回测神话」。

### 2. 确定性状态与记忆
所有可变状态（台账、前瞻日志、演化状态）都是**人类可读的 JSON**，落盘到 `data/`（可用 `FUCAI3D_DATA_DIR` 环境变量重定向）。Agent 重启后状态不丢、实验可复现——这正是长周期任务「记忆管理」的最小可行实现。

### 3. 评测即安全边界
- **随机基线对照**：任何「信号」都必须过 KS / 卡方 / SPRT，明确给出 `ACCEPT_H0` / `REJECT_H0`。
- **多重检验校正**：`Bonferroni`（α' = 0.05 / 配置数）防止反复试错碰巧显著。
- **预算护栏**：`kelly_guard` 按凯利上限 + 红线（默认 ≤30 元）强制拒绝超预算/超风险方案。
- **诚实门控**：自旋纯度 < 0.5 时 `spin_yang_bridge` 返回 `COOLDOWN`，绝不编造买入信号。

### 4. 可移植的协议实现
- 单个 `.mjs` 文件打包（esbuild），**无依赖、无需联网、无需 `npm install`** 即可被任意 MCP 客户端加载。
- 工具签名全部用 Zod 校验，输出为结构化 JSON，便于 Agent 直接消费与编排。

---

## 项目结构

```
3Dcaipiao/
├── dist/
│   └── 3dcaipiao.mjs          # 单文件打包产物（直接运行，无需编译）
├── src/                        # TypeScript 源码（阳核 6 引擎 + 可选 LLM 层）
│   ├── index.ts                # 入口：注册全部 3D 工具
│   ├── base-tools.ts           # 3D 查询/统计/回测
│   ├── pascal.ts               # Pascal 数论特征
│   ├── qcrm.ts                 # 量子混沌 / RMT
│   ├── spin_drive.ts           # 自旋驱动层 + 3D 前瞻闭环
│   ├── sum_engine.ts           # 和值函数方程
│   ├── combination.ts          # 胆拖/覆盖/风控/数据导入
│   └── llm.ts                  # 可选 LLM 叙述层
├── data/
│   └── sample_3d_100期开奖数据.md   # 100 期样例数据
├── config.example.json         # 大模型配置模板（复制为 config.json 填密钥）
├── mcp-config-example.json     # 客户端「添加 JSON」示例
├── package.json
├── LICENSE
└── README.md
```

### 从源码构建（可选）
```bash
npm install
npm run bundle     # esbuild → dist/3dcaipiao.mjs
node dist/3dcaipiao.mjs
```

---

## 配置说明

| 环境变量 | 作用 | 默认 |
|---|---|---|
| `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL` | 你的可选大模型（OpenAI 兼容 `/chat/completions`） | 未设置 → 叙述层降级 |
| `FUCAI3D_DATA_DIR` | 数据/台账目录 | 包内 `data/` |
| `FUCAI3D_DATA_PATH` | 指定开奖数据文件路径 | `data/sample_3d_100期开奖数据.md` |
| `COMBO_LEDGER_PATH` / `SPIN_LOG_PATH` / `QCRM_LOG_PATH` | 各台账文件位置 | `data/` 下对应 JSON |

---

## 许可与责任

- **MIT License**。可自由使用、修改、再发布。
- 本项目为**技术演示与工程研究**用途。彩票有风险，请理性对待；作者不对任何投注结果负责。

---

## 关于本项目作为 DeepSeek Harness 内测代表仓库

本项目即作者提交给 DeepSeek Harness 内测招募（2026-08-04）的**代表开源仓库**。它不炫技、不承诺收益，而是用一个真实可运行的系统，展示 Agent 工具协议在「长任务闭环 / 状态记忆 / 评测安全」三个方向上的落地细节。欢迎同行 review、提 issue、拍砖。