![象绎：中西术数合参引擎](assets/github/xiangyi-hero.png)

# 象绎 XIANGYI

> **先定其象，再绎其意。**

[简体中文](README.md) · [English](README_EN.md)

一个本地运行、中文优先、依据可追溯的中西术数合参工具。它以确定性程序完成排盘，让
Codex 只解释已经计算出的事实，并把不同体系之间的一致、分歧与不确定性如实呈现。

![Python 3.12](https://img.shields.io/badge/Python-3.12-345995?style=flat-square)
![Node 24](https://img.shields.io/badge/Node.js-24_LTS-3c873a?style=flat-square)
![MCP stdio](https://img.shields.io/badge/MCP-stdio-b68d40?style=flat-square)
![Local first](https://img.shields.io/badge/运行方式-Local--first-234e52?style=flat-square)

## 为什么做象绎

当八字、紫微、星盘和卦象给出不同侧面的信息时，工具不应把分歧藏进一段听起来笃定的回答。

象绎选择另一条路：**先确认输入，再计算事实；先展示依据，再提供解释。** 模型不能自行补算
干支、星位、宫位或日期，也不能把传统术数包装成科学概率。用户看到的不只是结论，还包括它
来自哪个引擎、采用什么设置、落在哪段时间，以及哪些事实彼此冲突。

## 当前能力

| 场景 | 能力 | 实现方式 |
| --- | --- | --- |
| 本命 | 八字、紫微斗数、西方本命盘 | `lunar-typescript`、`iztro`、外部 Horosa provider |
| 事件 | 手工六爻、投币换算、可复算系统起卦 | 本地 `HMAC-SHA256-v1`，模型不参与随机过程 |
| 时间 | 大运／大限、年度、月份及受限的日期点查 | 半开区间 `[start, end)` 与明确精度门禁 |
| 资料 | 本地知识导入、检索、出处与校勘状态 | SQLite FTS5 trigram，无向量数据库 |
| 解释 | 事实引用、资料引用、冲突披露、安全审计 | 结构化 `ReadingDraft` 与 `AuditResult` |
| 接口 | JSON CLI 与本地 stdio MCP | 同一领域核心、同一 Pydantic 契约 |

## 工作方式

```mermaid
flowchart LR
    A[咨询输入] --> B[prepare 规范化]
    B --> C{用户确认}
    C -->|已确认| D[确定性引擎]
    C -->|有缺失或歧义| B
    D --> E[CalculationBundle]
    K[本地知识库] --> F[Codex 依据化解释]
    E --> F
    F --> G[audit 审计]
    G -->|通过| H[事实报告与可逆建议]
    G -->|仍失败| I[仅输出事实报告]

    D --- D1[八字／紫微 TypeScript]
    D --- D2[Horosa 西方占星]
    D --- D3[本地易经起卦]
```

一次可信的最小闭环是：

1. `prepare` 返回规范化输入、方法设置和确认摘要。
2. 用户确认出生信息、时区、经纬度、历法与流派边界。
3. `natal`、`event` 或 `timing` 调用确定性引擎。
4. Codex 根据事实与最多 5 条本地资料生成结构化解释。
5. `audit` 检查事实引用、时间精度、冲突和高风险内容。
6. 审计失败两次后停止发挥，只保留计算事实。

## 与普通 AI 算命工具的区别

- **模型不排盘**：历法、星位、宫位、卦象和时间边界都由程序计算。
- **不猜输入**：未知时辰不会默认为子时，城市名不会被模型猜成经纬度。
- **冲突不平均**：多个体系不做神秘的数值加权；体系冲突时总评只能是“混合”。
- **判断有出处**：每项解释必须绑定事实 ID、资料 ID，或明确标记为模型推论。
- **默认不留档**：普通咨询不写 `runs.db`，不记录原始提示，不发送遥测。
- **建议可撤回**：只提供低风险、可逆、保留用户自主权的行动建议。

## 快速开始

环境要求：macOS arm64、Python 3.12、Node.js 24 LTS、[`uv`](https://docs.astral.sh/uv/)。

```bash
source ~/.nvm/nvm.sh
nvm use

uv sync --locked
npm ci --prefix engines/chinese-ts
npm run build --prefix engines/chinese-ts

uv run suanming doctor
```

项目通过 `.python-version` 与 `.nvmrc` 固定开发运行时。`doctor` 会检查 Python、Node、SQLite
FTS5、中文引擎、Horosa、来源清单和本地端点。

## JSON CLI

业务命令从 stdin 接收一个 JSON 对象，stdout 只输出 JSON；诊断只写 stderr。

```bash
request='{"kind":"event","as_of_date":"2026-09-01","event":{"question":"未来三个月推进这个项目的节奏如何？","asked_at":"2026-09-01T12:00:00+08:00","tzid":"Asia/Shanghai","horizon_start":"2026-09-01","horizon_end":"2026-12-01","casting_mode":"manual","manual_lines":[7,8,6,9,7,8]}}'

printf '%s' "$request" | uv run suanming prepare
```

`prepare` 返回 `confirmation_digest`。用户确认后，在同一对象加入 `confirmed=true` 与该摘要，
再交给对应计算命令。任何输入变化都会令旧摘要失效。

```text
suanming prepare
suanming natal
suanming event
suanming timing
suanming knowledge import|search
suanming audit
suanming run save|get|delete
suanming doctor
```

统一状态只有：`ok`、`needs_input`、`partial`、`error`。

## Codex MCP

MCP 默认使用本地 stdio，不开放公网端口。请在项目根目录执行：

```bash
PROJECT_DIR="$(pwd)"
codex mcp add xiangyi -- uv --directory "$PROJECT_DIR" run suanming-mcp
codex mcp get xiangyi
```

服务暴露 9 个 facade tools：

```text
prepare_consultation   calculate_natal     calculate_event
calculate_timing       search_knowledge    audit_reading
save_run               get_run             delete_run
```

只有 `save_run` 和 `delete_run` 会改变咨询存储；删除还需要显式确认。

## Horosa 西方占星

Horosa 作为项目外部 provider 使用，不进入本仓库，也不嵌套第二套 MCP 行为。象绎调用其固定版本
JSON CLI，并在启动检查中执行上游 doctor。provider 不可用时会返回清晰的部分结果，不会由模型
手工补盘。

macOS 标准发现位置：

```text
~/Library/Application Support/suanming/providers/horosa-skill/horosa-skill
```

也可以通过 `SUANMING_HOROSA_DIR` 指向包含 `pyproject.toml` 的内层目录。普通计算会关闭 Horosa
结果持久化与 trace。审核过的 commit、runtime 版本和 SHA-256 记录在
[`sources.lock.json`](sources.lock.json)。

## 输出契约

- `CalculationBundle`：规范输入、设置、provider、事实、警告与规范哈希。
- `TimeWindow`：时间范围、层级、父周期、评级、支持事实与冲突事实。
- `ReadingDraft`：判断文本、事实 ID、资料 ID、推论类型与可逆建议。
- `AuditResult`：无依据判断、矛盾、来源、时间精度与安全问题。

评级只使用：`有利 / 偏有利 / 混合 / 偏挑战 / 挑战`。`input_confidence`、
`method_confidence` 与 `agreement` 描述输入和方法状态，不代表事件概率，也不代表术数获得科学验证。

公开 JSON Schema 位于 [`schemas/`](schemas/)。

## 本地数据与隐私

象绎隔离使用两个 SQLite 数据库：

- `knowledge.db`：用户主动导入的本地资料、来源与全文检索。
- `runs.db`：只有明确执行 `save` 后才创建，文件权限为 `0600`。

默认咨询不保存出生资料，不创建 `runs.db`，不发送遥测或远程同步。天纪语料只允许用户从本地
固定 commit 主动导入；未决校勘内容会被隔离，不能作为最终引文。

## 安全边界

象绎是传统文化娱乐与自我反思工具，不宣称能够科学预测未来。它不会提供：

- 死亡、疾病诊断、手术、怀孕、胎儿性别或确定性灾祸判断；
- 替代医疗、法律、投资、婚姻等高风险专业决策的建议；
- 利用恐惧、宿命论或绝对化措辞限制用户自主权的结论。

## 开发与验证

```bash
uv run ruff check .
uv run pytest -q
npm test --prefix engines/chinese-ts
uv run python scripts/export_schemas.py --check
uv lock --check
uv build
```

测试覆盖节气边界、闰月、DST、晚子时、十二时辰、紫微固定快照、易经动爻、规范哈希、知识库
隔离、隐私、审计与 MCP 契约。

## 路线图

- [x] Python 领域核心与 JSON CLI
- [x] 八字、紫微与本地易经确定性引擎
- [x] Horosa 西方本命盘外部 provider
- [x] 本地 stdio MCP 与 9 个 facade tools
- [ ] 天纪语料的用户导入体验与引用浏览
- [ ] 用户授权的远程易经 provider
- [ ] Vedic JSON provider
- [ ] 太阳回归、次限推进等更多时间技术

## 上游与许可

所有上游项目都记录固定 commit、许可、用途与再分发门禁，详见
[`sources.lock.json`](sources.lock.json)。许可状态不明确的代码或语料不得进入发布包。

当前仓库暂未附带开源许可证；公开可读不等于授予复制、修改或再分发权利。若未来商业化、
对外分发或提供在线服务，必须重新完成许可证、隐私、内容责任与 Corresponding Source 审核。

---

**象绎不替你决定命运。它把传统体系中的“象”计算清楚，让你在看见依据与边界之后，自己作出选择。**