亲手拈星入宫，在仪式中觉察当下。
紫微知道系列中的开源卡牌占卜工具：以水墨仪式亲手抽牌布阵，AI 把星辰语言翻译成可觉察的人生线索。
- 项目名称：Ziwei Draw（紫微知道 · 拈星）。
- 规范仓库：github.com/ziweiknows/ziwei-card。
- 实现位置与技术栈：Web 应用位于项目根目录，使用 React 19、TypeScript 5.7 和 Vite 6，通过
iztro获取紫微斗数星曜与庙陷数据，以@dnd-kit实现自由拖放布位，以 Framer Motion 驱动水墨动画。 - 开源许可：Copyright (C) 2026 ruijayfeng。本项目按 GNU GPL v3 或更高版本 发布。
紫微知道（Ziwei Knows）由四款平级、互补的开源产品组成。它们服务不同的探索方式，不要求账号、命盘或数据互通。
| 产品 | 适合什么需求 | 访问 |
|---|---|---|
| Ziwei Chart | 想准确排盘、浏览十二宫、流年、合盘和长期趋势。 | 在线体验 · GitHub |
| Ziwei Chat | 已有命盘，想围绕事业、关系、财富或近况继续追问。 | 在线体验 · GitHub |
| ZATI | 不想先填写出生信息，想通过行为选择探索人格原型。 | 在线体验 · GitHub |
Ziwei Draw 当前产品 |
想通过亲手抽牌布阵的仪式感，获得当下问题的觉察视角。 | 即将上线 · GitHub |
想先看清完整盘面和趋势，使用 Ziwei Chart；想围绕具体问题追问命盘，使用 Ziwei Chat；想从行为倾向开始认识自己，探索 ZATI；想通过仪式感在当下获得觉察，打开 Ziwei Draw。
Ziwei Draw 是紫微知道系列中的卡牌占卜产品。它不同于传统命盘工具——你不用输入生辰八字，而是带着一个当下关心的问题，亲手摇签定天干、搓洗牌堆、凭念切牌、从扇形牌背中拈出星曜，再自由拖入十二宫位。
每一张牌的意义不由牌本身决定，而由「哪颗星 × 落入哪个宫位 × 亮度如何 × 是否被四化击中」共同构成。翻牌后，三方四正连线在你眼前画出星曜之间的呼应网；AI 解盘师再把这些星辰语言翻译成可觉察的人生线索。
它不替你算命，而是让你在仪式中看见自己。
| 能力 | 说明 |
|---|---|
| 十阶仪式 | 静心设问 → 选阵 → 摇签定干 → 净手洗牌 → 凭念切牌 → 抽牌 → 布位 → 翻牌 → 飞星 → 解盘，每一步都有水墨动效与停顿。 |
| 亲手布位 | 拖拽星曜卡牌放入任意宫位，自由决定哪颗星落哪一宫。宫位呼吸高亮，hover 实时预览亮度变化。 |
| 水墨七态 | 庙旺利陷以墨色浓淡表现——浓墨饱满、淡墨枯笔、陷则飞白散墨。不是冷冰冰的标签，是视觉可感的深度。 |
| 天干四化 | 摇签落出天干令牌，系统按 iztro 锁定四颗化星（禄权科忌）。化忌先行解读，是每局的戏剧核心。 |
| 三方四正飞星 | 命财官三合、命迁对冲——连线逐条画出，化忌冲对宫时对宫同步震动。叙事网，不是逐牌孤立。 |
| AI 解盘 | 可接入兼容 OpenAI/Anthropic 接口的模型，默认指向豆包 Ark。AI 按七步推理协议输出结构化解读，禁绝对断语。 |
| 混合降级 | 翻牌即见规则释义（离线、零延迟）；AI 解读为深度按钮。AI 不可用时自动降级为规则模板，绝不白屏。 |
| 水墨留白 | 宣纸底色、墨色星宿、克制留白。动效为墨韵晕开，非霓虹辉光。PC 优先，键盘可达。 |
静心设问 → 选阵 → 摇签定干 → 净手洗牌 → 凭念切牌 → 抽牌 → 布位 → 翻牌 → 飞星 → 解盘
| 阶 | 名称 | 玩家做什么 | 系统做什么 |
|---|---|---|---|
| 0 | 静心设问 | 输入问题或选主题（事业/感情/财运/抉择/全观） | 推荐牌阵 |
| 1 | 选阵 | 从三宫三主题 + 十二宫全阵中选 | 展示阵图、牌数、难度 |
| 2 | 摇签定干 | 点击签筒摇晃，落出天干签与长生签 | 按干锁定四化；长生定全局气数基调 |
| 3 | 净手洗牌 | 按住牌堆搓洗，轨迹/时长注入心念 | 用动作熵重洗牌序 |
| 4 | 凭念切牌 | 在牌叠某处点下切开 | 切点成为新牌顶，从此处起抽 |
| 5 | 抽牌 | 扇形牌背点抽 N 张（= 阵位数） | 已切牌序；hover 浮起；抽满收束 |
| 6 | 布位 | 手牌拖入/点放任意宫位，可互换/取回 | 宫位呼吸高亮 + hover 实时亮度预览；弹簧吸附 |
| 7 | 翻牌 | 逐张点击/空格，或一键全翻 | 3D 翻转；显庙陷墨色 + 四化徽记；即时规则释义 |
| 8 | 飞星 | 观看三方四正连线逐条画出 | 点亮会照/冲照线；化忌冲对宫高亮 |
| 9 | 解盘 | 点「请 AI 解盘」；文与牌双向联动 | AI 按协议输出结构化解读；支持保存/重开 |
快捷模式可自动定干、跳过洗切，直进抽牌。全程可返回上一步。
- 庙旺利陷即牌面深度：亮度由星 × 地支查表（iztro），非随机。水墨以墨色浓淡表七态。
- 牌与阵位相遇才产生意义：单张牌无绝对吉凶，「何星入何宫」是最小意义单位。
- 三方四正即叙事网：宫位会照/冲照是真实星理（命财官 = 寅午戌三合），连线即剧情。
- 四化由天干派生：非随机贴标签。化忌是戏眼，先行解读。
- 亲手布局即拥有感：扇形抽牌、自由拖放、3D 翻牌，仪式是产品本身。
- 水墨留白：宣纸底、墨色星宿、克制留白。光效为墨色辉光，非霓虹。
- PC 优先：大屏舞台、鼠标 hover 零成本预览、键盘可达。
产品开发中，界面预览将在 MVP 完成后更新。
- Node.js ≥ 18
- pnpm（推荐）或 npm
# 克隆仓库
git clone https://github.com/ziweiknows/ziwei-card.git
cd ziwei-card
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
# 构建生产版本
pnpm buildZiwei Draw 支持多种模型接口协议，在设置页配置四项即可：
| 配置项 | 说明 |
|---|---|
| Base URL | 模型 API 地址 |
| API Key | 你的 API 密钥（仅保存在浏览器本地） |
| 模型 | 模型名称 |
| 接口协议 | 自动识别（OpenAI 兼容 / Anthropic 兼容 / Responses API），也可手动指定 |
默认提供方：豆包 Ark（doubao-seed-evolving），通过 Responses API 调用。也可接入 DeepSeek、Claude、OpenAI 等兼容接口。
模型 API Key 仅保存在当前浏览器 localStorage，浏览器直发模型服务，不经过本项目服务器。
src/
├── app/ # 路由、App 壳、布局
├── stages/ # 仪式各阶段组件
├── components/
│ ├── card/ # 卡牌（牌背、牌面、3D 翻转、墨色亮度）
│ ├── board/ # 牌阵舞台、宫位 Drop Zone、三方四正连线
│ ├── hand/ # 扇形牌堆、手牌区
│ └── reading/ # AI 解读面板，文-牌联动高亮
├── data/ # 14 主星定义、牌阵配置、十二长生、亮度映射
├── domain/ # 四化派生、三方四正计算、洗牌种子、降级模板
├── ai/ # Provider 接口、系统提示词、模型适配器
├── store/ # Zustand 状态管理
└── docs/ # 游戏设计文档与架构契约
- 星曜亮度：运行时按「星 × 地支宫」查 iztro
STARS_INFO表，不硬编码、不随机生成。 - 四化派生：按天干令牌读 iztro
heavenlyStems[stem].mutagen，不由模型自行推断。 - 三方四正：固定地支盘（命宫 = 寅），三合 +4/+8（模 12），对冲 +6（模 12），与真实星理一致。
- AI 只做「结构化牌面的组合与翻译」，不补全未传入的星/宫/四化。
- 推理按七步协议执行：定调 → 化忌先行 → 其余三化 → 三方四正成局 → 逐宫分论 → 综合 → 自省心法。
- 禁绝对断语（「一定会」「命中注定」「大凶」），化忌必给成长课题，落陷必给自处之道。
- 越界问题（医/法/具体投资）不决断，转专业人士。
- 14 主星卡牌，单星单卡
- 4 种牌阵（事业三宫 / 感情三宫 / 抉择三宫 / 十二宫全阵）
- 固定地支盘，自由拖放布位
- 规则释义 + AI 解盘，混合降级
- 本地存档（localStorage）
Ziwei Draw 是一款以传统文化为表达形式的自我觉察工具，不构成命理预测、心理诊断、医疗建议或投资指导。所有解读均为「此局提示」「值得留意」级别的视角参考，请结合自身判断使用。
欢迎通过 Issue 和 Pull Request 参与共建。详情见 CONTRIBUTING.md（即将添加）。
紫微知道由 Jay Feng（@ruijayfeng） 创立并主要开发。
Copyright (C) 2026 ruijayfeng. Licensed under GNU GPL v3.