# DeepSeek Harness Liuren

独立的大六壬排课 MCP 插件，提供窄核心 `liuren_core_cast`、时间起课 `liuren_cast` 和古例直接起课 `liuren_classic_cast`，可用于 DeepSeek Harness 或其他 MCP 客户端。

> 当前稳定候选版为 `0.3.0-rc.2`；此前的公开 Beta 为 `0.2.0-beta.2`。
> 稳定候选范围只覆盖 `liuren_core_cast`；`liuren_cast` 和 `liuren_classic_cast`
> 仍是 Alpha/研究兼容面，不共享核心认证。见[稳定候选核心范围](docs/liuren-beta-scope.md)
> 、[RC 发布门禁](docs/stable-release-candidate.md)和[规则策略契约](docs/liuren-rule-policy.md)。
> RC2升级正式`0.3.0`的观察、P0/P1和决策条件见[RC2观察记录](docs/release-observation.md)。

1900—2100年UTC+8时间起课已将年/月柱交节与23点日柱换日分离：2024—2028使用香港天文台公布分钟，其他年份使用锁定 `sxtwl` 计算分钟。规则集和范围见[历法边界修复](docs/calendar-boundary-fix.md)。

`liuren_core_cast` 已按 22 条决策分支白名单收敛，固定日课和严格规则策略，只接受
1900—2100 年 UTC+8 时间，并移除天将/贵人、神煞、六亲、旬空与断语。涉害固定为
`liuren_daquan_exclusive_endpoints_v1`，柔日昴星固定为 `xiangshu_double_descent_v1`；它们是具名取法，不代表其他异法无效。遥克的蒿矢/弹射、唯一候选/阴阳比用四种路径均已锚定。详见
[稳定候选核心范围](docs/liuren-beta-scope.md)。

核心入口的月将、天地盘、四课和发用决策现由本项目直接构造，成功与拒绝路径均不调用 `kinliuren`。`kinliuren` 仍作为两个完整兼容入口的锁定依赖保留。

从 `0.3.0-rc.1` 起，默认 wheel 只安装稳定核心所需依赖，不再强制安装 `kinliuren`。
需要 `liuren_cast` 或 `liuren_classic_cast` 时，安装 `compatibility` extra；缺少该 extra 时，
两个兼容入口会返回明确的 `ENGINE_UNAVAILABLE`，不会影响 `liuren_core_cast`。

> 规则状态：古法直排九宗门与三传已通过 8,640 组全矩阵审计；两套已命名贵人法和十二天将通过 17,280 盘独立对照；神煞已规范为 65 个去重规则组、74 个名称，并能投影四课三传。按《神煞赋》命名的月煞规则集包含 64 个稳定规则组，唯一没有原典锚点的“闪电”只作兼容隔离；时煞、分煞、遁干落课、年命行年和断课层仍未完成。详见 [贵人天将与神煞落课审计](docs/liuren-nobleman-shensha-audit.md)、[规则审计](docs/rule-audit.md)、[全矩阵审计](docs/classic-matrix-audit.md)和[验证政策](docs/validation-policy.md)。

## 安装前准备

建议使用 Python 3.12，并安装 Git、C/C++ 编译工具和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。

| 系统 | 当前验证状态 | 编译工具 |
| --- | --- | --- |
| macOS Apple Silicon | 已验证公开 wheel 的全新 Python 3.12 安装 | `xcode-select --install` |
| Ubuntu Linux | 已验证公开 wheel 的 Python 3.12 安装；源码 CI 覆盖 Python 3.10–3.12 | `sudo apt install git build-essential python3-dev` |
| Windows + WSL2 | 推荐按 Ubuntu 步骤安装 | WSL2 内安装 Linux 编译工具 |
| Windows 原生 | 已验证公开 wheel 的 Python 3.12 安装 | Git、Visual Studio Build Tools（C++） |

macOS 可用 `brew install uv`，Windows 可用 `winget install --id=astral-sh.uv -e`。

## 方式一：直接安装发布版

当前稳定候选未发布到 PyPI，请从 GitHub Release 安装固定的 RC wheel：

```bash
uv tool install --python 3.12 \
  https://github.com/wangshuo1207/deepseek-harness-liuren/releases/download/v0.3.0-rc.2/deepseek_harness_liuren-0.3.0rc2-py3-none-any.whl
uv tool update-shell
xuanshu-liuren-doctor
```

安装过程会从固定 Git 提交编译 `sxtwl`。如果构建失败，请先确认已安装 Git 和上表所列的 C/C++ 编译工具。

## 方式二：从源码安装（Harness 推荐）

macOS、Linux 或 WSL2：

```bash
git clone https://github.com/wangshuo1207/deepseek-harness-liuren.git
cd deepseek-harness-liuren
uv python install 3.12
uv sync --locked --extra dev
uv run xuanshu-liuren-doctor
uv run python scripts/smoke_mcp.py
```

PowerShell：

```powershell
git clone https://github.com/wangshuo1207/deepseek-harness-liuren.git
Set-Location deepseek-harness-liuren
uv python install 3.12
uv sync --locked --extra dev
uv run xuanshu-liuren-doctor
uv run python scripts/smoke_mcp.py
```

PowerShell 下若不具备 C/C++ 编译环境，推荐改用 WSL2。`scripts/smoke_mcp.py` 只存在于源码仓；直接安装 wheel 时运行 doctor 即可。

`0.3.0-rc.2` wheel 若需要两个兼容入口，可在首次安装时增加锁定兼容引擎：

```bash
uv tool install --python 3.12 --with kinliuren==0.1.2.9 /path/to/deepseek_harness_liuren-0.3.0rc2-py3-none-any.whl
```

只使用稳定核心时不要增加 `--with`。`xuanshu-liuren-doctor` 会分别显示核心是否就绪以及兼容引擎是否可见。

`xuanshu-liuren-mcp` 是由 MCP 客户端启动的 stdio 服务，在终端直接运行后安静等待输入是正常现象。

## 怎样使用

稳定候选应默认调用 `liuren_core_cast`：

- `datetime`：ISO 8601 时间，当前接受转换到引擎时区后位于 1900—2100 年的瞬间。
- `timezone`：可选，默认 `Asia/Shanghai`；核心引擎时区必须在请求时刻为 UTC+8。带偏移的
  `datetime` 会先转换到该引擎时区，因此表示同一瞬间的 `Z` 和 `+08:00` 输入结果一致。
- `question`：可选问题文本，不参与确定性排盘。

核心入口不会暴露课型、贵人口径或规则策略开关，因此调用者不能误开实验层。需要月课、时课、古例输入、天将或神煞时才使用兼容入口；这些扩展字段仍属 Alpha/研究范围。

兼容入口的 `nobleman_method=standard` 表示五干德合贵人表；`extended` 表示十干分列
流派变体，并非“更完整版”。返回的 `贵人天将校验` 会列出昼夜、贵人天地盘支、顺逆、
规则集、完整天将盘列和独立校验结果。

## 接入 DeepSeek Harness

Harness 使用 `--patch` 叠加 MCP 配置，不使用旧的 `--config`。当前锁定验收版本为
`@deepseek-ai/dsh@0.1.2-rc.1`，要求 Node.js `^22.19.0` 或 `>=24.0.0`。以下命令用
`npx` 固定版本运行，无需全局安装 `dsh`。macOS、Linux 或 WSL2：

```bash
cd /absolute/path/to/deepseek-harness-liuren
export XUANSHU_LIUREN_REPO="$PWD"
npx -y @deepseek-ai/dsh@0.1.2-rc.1 --profile web --patch "$PWD/deepseek-harness/cordis.yml" --dump-config
npx -y @deepseek-ai/dsh@0.1.2-rc.1 web --patch "$PWD/deepseek-harness/cordis.yml"
```

PowerShell：

```powershell
Set-Location C:\absolute\path\to\deepseek-harness-liuren
$env:XUANSHU_LIUREN_REPO = (Get-Location).Path
npx -y @deepseek-ai/dsh@0.1.2-rc.1 --profile web --patch "$env:XUANSHU_LIUREN_REPO\deepseek-harness\cordis.yml" --dump-config
npx -y @deepseek-ai/dsh@0.1.2-rc.1 web --patch "$env:XUANSHU_LIUREN_REPO\deepseek-harness\cordis.yml"
```

`--dump-config` 只检查最终配置，第二条命令才启动 Web 会话。首次启动需在“设置 → 模型”配置
DeepSeek API Key；密钥只保存在 Harness 自己的凭据存储中，不要写入本仓库。启动后新建会话，测试提示词：

> 必须调用 liuren_core_cast，为 2026-09-01 10:30 Asia/Shanghai 排大六壬日课，先展示摘要再解释。

运行详情出现 `mcp__xuanshu_liuren__liuren_core_cast` 即表示核心入口已被调用。`liuren_cast` 和 `liuren_classic_cast` 是兼容/研究入口，不应默认使用。

直接安装发布 wheel 后，可下载 [`cordis-installed.yml`](deepseek-harness/cordis-installed.yml)，使用不依赖源码路径的配置：

```bash
npx -y @deepseek-ai/dsh@0.1.2-rc.1 --profile web --patch ./cordis-installed.yml --dump-config
npx -y @deepseek-ai/dsh@0.1.2-rc.1 web --patch ./cordis-installed.yml
```

锁定版本已完成配置展开、运行态 MCP 工具发现，并通过 Harness 的工具执行管线实际调用
伏吟、涉害和柔日昴星三个稳定候选分支；三次返回均与冻结契约一致。无 API Key 时
headless 会在模型调用前明确返回 `MISSING_CREDENTIAL`；这不影响上述确定性工具链验收。完整证据与边界见
[DeepSeek Harness 验收记录](docs/deepseek-harness-validation.md)。

当固定引擎结果与已认证的贼克、比用或涉害规则冲突时，返回盘采用原典裁定，并在 `规则校正` 中保留引擎原始格局与原始三传；`发用校验` 会同时给出候选、涉害深度和一致性状态。

## 神煞输出口径

实盘入口（`liuren_cast`）会给出六类神煞：岁煞、季煞、月煞、日煞、旬煞、干煞。古例入口（`liuren_classic_cast`）
只给日柱和占时，未提供的类别显式标记在 `未提供`；提供 `lunar_month` 时按「正月建寅」推定月支后计算季煞与月煞。
月煞默认采用显式命名的 `liuren_shensha_fu_month_v1`：桃花/咸池、往亡、天刑、五鬼、天医、地医、血忌和月小耗均按仓库保存的《神煞赋》起例，并由十二个月静态契约锁定；同名异法不静默混入。`规范化规则.默认稳定规则组` 可直接消费，旧字段中的“闪电”因没有原典锚点仅保留在 `隔离规则组`。华盖从旧引擎日支表改为三合墓通行口径（如日支子：戌→辰）。`神煞盘位` 自动标出单一地支值命中四课上神或三传的位置；天德/月德/天赦等干支 token 明列为不可投影，不交给模型猜测。

古籍只给出“月将、占时、日干支”时，可直接调用：

> 必须调用 liuren_classic_cast，以亥将、未时、丁巳日起大六壬课。

## 说明

盘面是确定性计算结果；文字解读是模型推断。不得将结果作为医疗、法律或投资建议。版本变更见 [CHANGELOG](CHANGELOG.md)，许可证见 [LICENSE](LICENSE)。