guanwei

v1.3.5

Published

9 hours ago

观微 Guanwei · 九术排盘与 AI 深度解读（八字/紫微/星盘/奇门/六爻/六壬/梅花/小六壬/塔罗）

0High
0Medium
0Low

rubycheng

chinese-astrology bazi ziwei qimen tarot divination metaphysics llm ai typescript

观微 · 以术问道

占问所得，仅供修身养性、怡情遣兴之用，不构成任何决策依据。

定位：自托管工具 —— 排盘与 AI 解读都跑在你自己机器上，档案与起占记录只落本地（~/.guanwei/data）；项目方不提供托管服务，不采集任何遥测、不上报使用数据。

▶️ 立即体验（无需注册 · 无需配置 · 无需 API Key）

另有 GitHub Pages 静态演示站（首页/九术说明/古籍/学馆）。完整功能（真实排盘 + 实时 AI 解读 + 存档）请本地/云端部署（见下）。

🖼️ 界面预览

✨ 功能

九术排盘（确定性历法计算，前后端单一算法副本）

| 类目 | 术数 | |---|---| | 命盘类 | 八字（子平）、紫微斗数、古典星盘（VSOP87 回归黄道） | | 占问类 | 奇门遁甲、梅花易数、六爻、大六壬、小六壬、塔罗 |

出生时间支持 公历/农历双历、精确到时刻（东玄据此推时辰，星盘直接用时刻）
地点精确到 省市区县 → 经纬度（真太阳时校正，含 1986-1991 中国夏令时回拨）；未填地点时明示"按北京时间排盘"
时辰未知支持：不排时柱仅依年月日三柱论命；可依人生关键事件反推时辰（流年 × 时柱应象打分引擎）
盘面动态话术：排盘结果按日主×季节×旺衰×十神×五行旺缺×大运喜忌生成个性化解读，告别千篇一律的模板
起占结果由后端计算并持久化入库（SQLite），六爻摇卦、塔罗抽牌等交互结果同样后端定稿

AI 深度解读

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= → 档案管理页列表/详情/删除

🤖 开放分发（v1.3.0 · 程序化调用排盘）

排盘能力已封装为可被程序调用的服务（与 Web 端共用 shared/core 单一算法副本）：

MCP Server：支持三种传输，本地与国内客户端通吃——

① stdio（Claude Code / Cursor 等本地 agent）：

// claude_desktop_config.json
{ "mcpServers": { "guanwei": { "command": "npx", "args": ["tsx", "packages/guanwei-api/src/mcp.ts"], "cwd": "/你的/guanwei路径" } } }

② 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 一行安装（推荐，国内几秒装完）

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 一行启动（免装 Node，最省心）

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 一键安装（源码方式，备用）

curl -fsSL https://raw.githubusercontent.com/RubyCcll/guanwei/main/scripts/install.sh | bash
guanwei setup
guanwei start

详细方式（Codespaces / Compose / 本地 Node）

只需一步：配置你的 API Key（5 家服务商任选，DeepSeek 性价比最高）。

方式四：GitHub Codespaces（零本地安装，云端一键）

点击按钮 → 云端环境自动装好依赖 → 终端执行：

./scripts/setup.sh --key sk-你的真实Key

方式五：Docker Compose（多容器）

预构建镜像已发布到 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。

方式六：本地 Node.js（≥ 22.13.0，需 node:sqlite 内置支持）

./scripts/setup.sh                    # 交互式：选服务商 + 输入 Key
# 或一步到位：./scripts/setup.sh --key sk-你的真实Key

脚本自动：安装依赖 → 写入 server/.env（Key 仅存本地）→ 启动前后端。打开 http://localhost:5173 → 缘起页注册 → 九术页起占 → 召 AI 成报告。

🖥️ 观微 CLI（启动 / 更新 / 自检一条命令）

# ① 在【项目根目录】执行一次（全局安装 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 保护，更新完成后恢复。

🔑 获取 API Key（5 家服务商任选）

| 服务商 | 官方入口 | 说明 | |---|---|---| | 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                 # 278 项测试（含九术引擎对权威库的交叉验证）
cd server && npx tsx scripts/divineStoreSmoke.ts   # SQLite 存储冒烟

🔬 与权威实现的交叉验证

排盘结果不靠自述——九术引擎的关键算法都与外部权威实现逐项对拍，且全部可在本仓复跑（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 时刻 | 与过宫时刻一致 | | 六爻纳甲 / 世位 / 六神 | 京房八宫递变 + 上下经卦纳甲独立推导 | 64 卦 + 200 次摇卦 | 全对齐 |

交叉验证抓到过的真实缺陷（均已修复并有回归）：六爻「宫纳甲」误用致 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）/ 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/ai 30/分、起占 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 <版本号>

📄 License

MIT

观微 · 以术问道，观微知著。本仓库将持续迭代，欢迎 Star 与 Issue。