Open-source Chinese metaphysics: nine arts of divination with AI interpretation.
简体中文 · English
Guanwei — an open-source Chinese metaphysics application: eight-character Bazi, Ziwei Doushu, classical astrology, Qimen Dunjia, Liuyao, Da Liu Ren, Meihua, Xiaoliuren and Tarot — with AI-powered in-depth interpretation.
东玄为主、中西合参的玄学占卜应用：九术排盘、AI 深度解读、古籍学馆，一条链路贯通「排盘 → 解读 → 归档 → 回看」。
占问所得，仅供修身养性、怡情遣兴之用，不构成任何决策依据。
定位：自托管工具 —— 排盘与 AI 解读都跑在你自己机器上，档案与起占记录只落本地（
~/.guanwei/data）；项目方不提供托管服务，不采集任何遥测、不上报使用数据。
▶ 打开交互演示 —— 九种术数本地排盘（浏览器直接计算，零后端），八字附带完整 AI 解读示例
另有 GitHub Pages 静态演示站（首页/九术说明/古籍/学馆）。完整功能（真实排盘 + 实时 AI 解读 + 存档）请本地/云端部署（见下）。
| 类目 | 术数 |
|---|---|
| 命盘类 | 八字（子平）、紫微斗数、古典星盘（VSOP87 回归黄道） |
| 占问类 | 奇门遁甲、梅花易数、六爻、大六壬、小六壬、塔罗 |
- 出生时间支持 公历/农历双历、精确到时刻（东玄据此推时辰，星盘直接用时刻）
- 地点精确到 省市区县 → 经纬度（真太阳时校正，含 1986-1991 中国夏令时回拨）；未填地点时明示"按北京时间排盘"
- 时辰未知支持：不排时柱仅依年月日三柱论命；可依人生关键事件反推时辰（流年 × 时柱应象打分引擎）
- 盘面动态话术：排盘结果按日主×季节×旺衰×十神×五行旺缺×大运喜忌生成个性化解读，告别千篇一律的模板
- 起占结果由后端计算并持久化入库（SQLite），六爻摇卦、塔罗抽牌等交互结果同样后端定稿
- 9 术角色化解读：每术独立 persona（紫微：命盘结构 → 星曜落宫 → 十二宫 → 大限流年 → 人生阶段）；紫微已支持三步深度编排（
orchestrate: "ziwei-deep"：三次独立推理后汇总，guanwei-pro 雏形），其余八术为单轮 persona 注入 - 双轨 Schema：命盘类（原始解读/性格/原生家庭/心智模式/人生阶段/事业/爱情/财富/健康）、占问类（现状/趋势/时机）
- 盘面事实一致性约束：AI 必须逐字引用排盘数据，不得编造；后端六亲宫位事实校验 + 矛盾定向修正（宫位地支/主星/借星/生年四化）
- 解读稳定性：Step1 盘面解析缓存复用、低温采样、论断锚定（主观程度词必须有盘面依据）、去重与字数预算
- 人生经历校准：可录入命主已知人生事件，AI 解读在对应流年处呼应、且不与已知经历矛盾
- 问题-术数适配性分析（如奇门不适于问情爱）
- 流式生成 + 结构化报告卡片，可导出 Markdown / 存为 PDF
- 古籍引证：断语库
shared/core/data/duanyu.ts收录古籍原文 16 条，其中 11 条已逐字校核（reviewed）并接入 AI prompt（来源为 ctext/维基文库/时点古籍权威底本）——解读行文自然处可引用「《书·篇》：原文」并附出处；其余 5 条待校核不注入
- 古籍页（背景动画、经典原文）、学馆（九术源流与知识）
- 用户档案管理（主档案/示例档案/编辑/切换）
- 占卜历史（起占自动归档，可回看排盘与 AI 报告，可删除）
前端 React 18 + TS + Vite + Tailwind（宋式美学 UI）
后端 Express + tsx（SSE 流式 + SQLite 存储）
共享引擎 shared/core/engine/*（lunar-typescript 历法 + astronomy-engine 星历）
AI 层：多 LLM 适配（OpenAI 兼容 / Google 格式，DeepSeek / Gemini / Groq / 通义 / 自定义端点）
① 排盘：登录用户 → 前端输入 → POST /api/divine → 后端引擎计算 → SQLite 入库 → 前端渲染
② AI：点击解读 → POST /api/ai/interpret/stream(divineId) → 后端读库 → 组装 Prompt → LLM SSE 流式返回
→ 后端 parseReport 结构化匹配（清洗/映射/质量评分/六亲事实校验）→ quality=ok 才入库 → 前端 ReportView
③ 历史：GET /api/divine?username= → 档案管理页列表/详情/删除
排盘能力已封装为可被程序调用的服务（与 Web 端共用 shared/core 单一算法副本）：
MCP Server：支持三种传输，本地与国内客户端通吃——
① stdio（Claude Code / Cursor 等本地 agent）：
② HTTP / SSE（WorkBuddy / ima / Trae 等国内客户端，填 URL 即可）：
// WorkBuddy MCP 配置（type 选 sse 或 http 均可）
{ "mcpServers": { "guanwei": { "type": "http", "url": "http://127.0.0.1:3020/mcp" } } }
// 先启动服务：cd packages/guanwei-api && npm start （/mcp 为 Streamable HTTP，/mcp/sse 为旧版 SSE）agent：用观微排一个 1993-01-23 寅时的八字
→ 工具 guanwei_chart(art: "bazi", inputs: {...}) → 完整盘面
REST API（packages/guanwei-api，免费无 Key）：
cd packages/guanwei-api && npm start # http://127.0.0.1:3020/v1
curl -X POST http://127.0.0.1:3020/v1/chart -H "Content-Type: application/json" \
-d '{"art":"liuren","inputs":{"datetime":"2026-08-29T12:00:00"}}'
curl http://127.0.0.1:3020/v1/arts # 九术能力清单 + 参数 schema排盘免费（纯计算零 token）；
/v1协议与统一错误码便于本地集成与二次开发。安全默认：服务只绑
127.0.0.1并内置 per-IP 限流（默认 120 次/分，GUANWEI_API_RATE_MAX可调）、SSE 连接上限与闲置回收。 如需公网/局域网暴露：GUANWEI_API_HOST=0.0.0.0 npm start，并请自行加反向代理与更严格的网关限流。 Docker 用户可用docker compose --profile api up -d启动该服务（容器内自动置GUANWEI_API_HOST=0.0.0.0）。
默认只绑 127.0.0.1，必须显式放开：
GUANWEI_API_HOST=0.0.0.0 GUANWEI_API_RATE_MAX=60 npm start # packages/guanwei-api- 限流兜底：per-IP 桶（默认 120/分，可调）、SSE 连接上限与闲置回收、429 带
Retry-After - 只要计数、不采隐私：仅本机可读的使用计数（无 IP / 无参数 / 无载荷），
GUANWEI_API_STATS=0可完全关闭
curl http://127.0.0.1:3020/v1/stats # {"total":…, "byEndpoint":{"/v1/chart":…}, "byDay":{…}}- 公网务必在前置反代加网关鉴权（Nginx basic auth / Authelia / Cloudflare Access 等）与更严格的限流
npm i -g guanwei
guanwei setup
guanwei start打开 http://localhost:5173 即用。国内用户自动走 npmmirror 加速；升级：guanwei update。停止：guanwei stop。
💡 配置 Key（
guanwei setup）：交互式引导——选服务商 → 粘贴 Key（不回显），写进~/.guanwei/.env仅本机可读。也可一步到位：guanwei setup --key sk-你的真实Key（DeepSeek 等 5 家任选，Key 申请见下文）。 💡 不配 Key 也能启动：guanwei start直接跑，排盘/演示/古籍全部可用，仅 AI 解读不可用（页面会提示配置入口）。
docker run -d --name guanwei -p 5173:80 -e LLM_DEEPSEEK_KEY=sk-你的真实Key ghcr.io/rubyccll/guanwei:latest打开 http://localhost:5173 即用。停止：docker stop guanwei。其他服务商：-e LLM_PROVIDER=gemini -e LLM_GEMINI_KEY=sk-你的真实Key（deepseek / gemini / groq / qwen / custom 均可）。
curl -fsSL https://raw.githubusercontent.com/RubyCcll/guanwei/main/scripts/install.sh | bash
guanwei setup
guanwei start只需一步：配置你的 API Key（5 家服务商任选，DeepSeek 性价比最高）。
点击按钮 → 云端环境自动装好依赖 → 终端执行：
./scripts/setup.sh --key sk-你的真实Key预构建镜像已发布到 GitHub Container Registry（amd64 + arm64 双平台）：
./scripts/setup.sh --docker --key sk-你的真实Key # 自动配置 + 拉取镜像 + 启动
# 或手动：
# cp server/.env.example server/.env （填入 Key）
# docker compose up -d （自动拉取 GHCR 镜像）打开 http://localhost:5173 。停止：docker compose down。
镜像：ghcr.io/rubyccll/guanwei-guanwei-web / guanwei-guanwei-backend；端口冲突时 WEB_PORT=5180 API_PORT=3020 docker compose up -d 覆盖。也可直接 docker pull ghcr.io/rubyccll/guanwei-guanwei-web:latest。
./scripts/setup.sh # 交互式：选服务商 + 输入 Key
# 或一步到位：./scripts/setup.sh --key sk-你的真实Key脚本自动：安装依赖 → 写入 server/.env（Key 仅存本地）→ 启动前后端。打开 http://localhost:5173 → 缘起页注册 → 九术页起占 → 召 AI 成报告。
# ① 在【项目根目录】执行一次（全局安装 guanwei 命令，之后任意目录可用）：
npm link
# ② 不想全局安装？直接使用：./scripts/guanwei <命令>
guanwei setup # 配置 API Key（交互式：选服务商 + 粘贴 Key）
guanwei setup --key sk-xxx # 一步到位（sk-xxx 换成你的真实 Key）
guanwei start # 启动（--docker 用容器）
guanwei doctor # 环境自检（Node/配置/占位密钥/端口/依赖/版本）
guanwei update # 更新到最新版（git 增量合并，.env 等本地配置不覆盖）
guanwei check / status # 版本检查 / 状态
guanwei stop # 停止（docker 模式）
guanwei update采用 git 增量合并：只拉取远程变更、保留本地所有配置（.env等已 gitignore 文件不受影响）；检测到本地未提交修改会先提示并自动 stash 保护，更新完成后恢复。
| 服务商 | 官方入口 | 说明 |
|---|---|---|
| DeepSeek（推荐） | https://platform.deepseek.com | 性价比最高，中文好 |
| Groq | https://console.groq.com | 有免费额度 |
| Gemini | https://aistudio.google.com/apikey | 有免费额度 |
| 通义千问 | https://dashscope.console.aliyun.com/ | 国内直连 |
| 自定义端点 | 任意 OpenAI 兼容接口 | --provider custom |
注册后在对应平台创建 Key → 运行 ./scripts/setup.sh --key 你的Key（Windows 用 scripts/setup.bat --key 你的Key）即完成配置；未配置时页面会有明确引导。
npm test # 283 项测试（含九术引擎对权威库的交叉验证）
cd server && npx tsx scripts/divineStoreSmoke.ts # SQLite 存储冒烟账号与占卜记录都在一个 SQLite 库（~/.guanwei/data/guanwei.db）里，一条命令即可快照：
guanwei backup --note 升级前 # 在线快照（VACUUM INTO，服务运行中也安全）
guanwei db-list # 列出备份与其中账号/记录条数
guanwei stop && guanwei restore <备份文件> --yes # 恢复（先停服务；会自动留存当前库）- 备份默认落在
<数据目录>/backups/，同时附.json元数据（时间/版本/条数/sha256）；旧版 JSON 用户库（db.json）也会一并备份 - 恢复前会先校验备份可打开且含关键表，再留存现有库（
.pre-restore-<时间>）并挪走-wal/-shm副文件；服务仍在运行时默认拒绝（--force可强行，但恢复后请立刻重启） - 直接
cp guanwei.db在服务运行中不可靠（最近事务可能还在-wal里），请用guanwei backup
排盘结果不靠自述——九术引擎的关键算法都与外部权威实现逐项对拍，且全部可在本仓复跑（npx vitest run；未装 pyswisseph 时星历两组自动跳过）：
| 验证面 | 权威源 | 案例规模 | 断言 |
|---|---|---|---|
| 星盘行星 / 上升 / 中天 | Swiss Ephemeris（瑞士星历） | 8 时空 × 7 古典行星 | 黄经 ≤0.05°、上升/中天 ≤0.1° |
| 节气时刻（定年月柱、奇门定局、六壬月将的共同地基） | Swiss Ephemeris 太阳视黄经过宫（二分求根） | 3 年 × 24 节气 | 与历表差 ≤90 秒 |
| 八字四柱 / 胎元 / 命宫 / 身宫 / 大运 | lunar-typescript EightChar（sect2） |
10 案例（含立春分钟级边界、晚子时） | 全字段一致，大运序列对齐 |
| 紫微宫位 / 十四主星 / 辅星 / 亮度 | iztro 2.6.0 | 24 案例 × 14 星（含闰月分界、晚子时、正月初一） | 零差异 |
| 奇门阴阳遁 / 局数 / 五层盘（地盘天盘八门九星八神） | qimen-dunjia 3.1.0（拆补法） | 19 案例 × 逐宫 | 全对齐（含夜子时） |
| 六壬月将（中气定将） | Swiss Ephemeris 太阳视黄经 30° 分段 | 12 中气 × 前后 6 小时 + 全年 24 时刻 | 与过宫时刻一致 |
| 梅花体用生克 / 旺相休囚死 | 《梅花易数》卷二·体用总诀（古籍原文） | 3 则原案（观梅占 / 牡丹占 / 邻夜扣门）+ 128 组体用 + 48 项月令卦气 | 逐条一致 |
| 小六壬三宫推演（大安起月·月上起日·日上起时） | 外部教程原例题（含闰月作本月） | 3 则例题逐宫 + 六宫循环/时辰口径 | 三宫逐位一致 |
| 基础对应（五行↔方位↔颜色、六神↔方位、八卦↔五行、八门九星↔宫位、六爻六神起例、塔罗星座↔元素） | 术数通行底层口径 + 金色黎明元素体系 | 逐表全量（含六宫断辞全表） | 逐条一致 |
| 星盘宫位制（整宫 / 等宫 / 普拉西度） | Swiss Ephemeris houses_ex Placidus 宫头 |
8 时空 × 12 宫头（含南半球与高纬 59°N） | 宫头 ≤0.01°（实测最大 0.005°） |
| 大六壬起课（十干寄宫 / 贵人歌 / 九宗门三传） | 《六壬大全》卷一·入手法（四库全书本原文） | 10 干寄宫 + 10 干×昼夜贵人 + 60 日干支×12 时辰 = 720 课结构 | 逐条一致 |
| 六爻纳甲 / 世位 / 六神 | 京房八宫递变 + 上下经卦纳甲独立推导 | 64 卦 + 200 次摇卦 | 全对齐 |
交叉验证抓到过的真实缺陷（均已修复并有回归）：梅花体用生克与旺衰两表整体反向（64 组体用中 50 组吉凶判反）、六爻「宫纳甲」误用致 56/64 卦装卦错、奇门夜子时日柱少进一日、节气时刻在 1986–1991 夏令时窗口系统性偏 1 小时、六十四卦「地水师/水地比」上下卦写反、紫微亮度表整体失真。
├── src/ # 前端（页面/组件/hooks/服务）
├── server/
│ ├── src/
│ │ ├── routes/ # divine（排盘）/ ai（解读）/ users / hour（时辰反推）
│ │ └── services/ # db（统一 SQLite）/ usersStore / divineStore / promptBuilder / llmProvider / dataDir / auth
│ └── .env.example
├── shared/core/ # 前后端共用引擎（排盘算法/数据，单一副本）
├── packages/guanwei-api/# 开放 API（REST /v1 + MCP）
├── scripts/ # setup.sh / guanwei（CLI）/ guanwei-db.mjs（备份恢复）/ release.sh / preflight-release.sh / check-*.mjs
├── deploy/ # nginx 配置（Docker 部署）
├── .devcontainer/ # GitHub Codespaces 模板
├── Dockerfile.web / Dockerfile.server / docker-compose.yml
├── docs/assets/ # 对外素材（banner/截图/GIF/示例报告）
├── internal/ # 内部文档（规划/监控/SOP/草稿）——**仅本地，git 忽略，永不公开**
└── tests/ # 测试（含回归集）
| 区域 | 位置 | 是否公开 |
|---|---|---|
| 源码与测试 | src/ server/src/ shared/ packages/ tests/ scripts/ |
公开（git + npm 包） |
| 对外素材 | docs/assets/ |
公开（仅 GitHub 展示，不进 npm 包） |
| 内部文档 | internal/ |
仅本地（git 全目录忽略；请勿把内部内容放进公开区） |
| 运行时数据 | ~/.guanwei/data（GUANWEI_DATA_DIR 可覆盖） |
永不公开（物理隔离于项目树之外） |
发布前自检：./scripts/preflight-release.sh —— 依次校验仓库边界、npm 包内容（文件名 + 内容级扫描）、类型、全量测试、版本一致性；CI 与 release 流水线同样内置边界与包内容守卫。
- 鉴权：已内置 token 鉴权（
X-Guanwei-Token，30 天滚动过期）+ scrypt（随机盐）密码哈希；档案/记录/详情接口均校验归属，归属不符统一 404（不泄露资源存在性） - 默认最小暴露：后端默认只绑
127.0.0.1（容器/局域网用HOST=0.0.0.0显式放开）；开放 API 默认只绑本机并内置 per-IP 限流；CORS 默认仅本机来源 - 限流：
/api/ai30/分、起占 60/分、登录/注册 10/分、其余计算端点 120/分（GUANWEI_RATE_*可调）；反代下通过trust proxy取真实客户端 IP - 密钥：仅存于本地
server/.env（已 gitignore），仓库只提供.env.example模板；Docker 构建排除.env；发布流水线有内容级扫描（密钥形态命中即拒绝发布） - 数据隔离：运行时数据（用户档案 + 占卜记录）默认在
~/.guanwei/data，位于项目树之外——npm/Docker 构建上下文物理上取不到；scripts/check-boundary.mjs与scripts/check-package.mjs在 CI/发布前双重把关 - 统一存储：账号、占卜记录、AI 失败留档同处一个 SQLite 库（
guanwei.db，WAL +BEGIN IMMEDIATE事务），并发注册/建档不会互相覆盖；1.3.4 及更早版本遗留的 JSON 用户库（db.json）在首次启动时一次性导入（原文件保留可回滚） - 隐私：出生信息与人生经历会发送给所配置的 LLM 服务商用于生成解读；如需完全离线，请仅使用本地排盘能力（不调用
/api/ai/*） - AI 报告质量门槛：结构评分不达标不入库，自动留档供改进提示词
- 测试数据全部虚构/匿名化，不含真实用户隐私；真实案例仅存本地（git 忽略）
⚠️ 部署边界：默认配置面向「本地/内网自部署」。若需公网访问，请在前置反向代理上加网关鉴权（Nginx basic auth / Authelia / Cloudflare Access 等），并显式设置GUANWEI_ALLOWED_ORIGINS与更严格限流。
- 示例 AI 报告 PDF（虚构档案，真实管线生成）
已完成（v1.1.x）：
- ✅ 排盘精度：八字（藏干十神/旺衰拆解/用神喜忌/大运流年/神煞/胎元命宫身宫/时辰未知）、紫微（辅曜安星/生年四化/庙旺落陷/格局识别）、星盘（宫位/行星入宫/庙旺逆行）、六爻纳甲（六亲六神世应/月破旬空）、奇门（值使/暗干/八神）、六壬（贵人/十二天将）、梅花（体用旺衰）
- ✅ AI 解读：两步管线（盘面解析 → 深度报告）、盘面事实注入、画像级 Schema、多 LLM 适配、解读稳定化与去重、六亲事实校验修正、人生经历校准
- ✅ 时辰反推：依人生关键事件推演时辰（流年 × 时柱应象打分引擎）
- ✅ 盘面动态话术：排盘结果按盘面数据生成个性化解读
- ✅ 部署套件：一键配置脚本、Docker Compose（GHCR 预构建镜像）、Codespaces、guanwei CLI（启动/更新/自检）、Windows 支持
- ✅ 演示页：九术本地排盘（纯浏览器引擎）+ 八字示例报告，GitHub Pages 直接体验
- ✅ 评测闭环：接入 MingLi-Bench（160 题）建立 AI 解读评测基线，评测驱动 prompt 迭代
计划方向：
- 开放分发：MCP Server / Agent Skill / REST API（复用 shared/core 单一算法副本）
- 体验：移动端适配深化、性能优化、演示页输入表单
- 持续演进：更细致的解读和更精确的个人化设计
- 🐛 遇到问题 → 提 Bug 报告
- 💡 有想法 → 提 功能建议
- 🧑💻 想写代码 → 见 CONTRIBUTING.md（含「我想做什么 → 推荐起点」导航）
- 🌱 新手友好 → good first issue
- ⭐ 觉得不错 → 点个 Star，就是最大的支持
- 📦 发版节奏：语义化版本，见 CHANGELOG.md；发版一条命令
./scripts/release.sh <版本号>
观微 · 以术问道，观微知著。本仓库将持续迭代，欢迎 Star 与 Issue。