ZEWE — 結構化命盤 AI 研究展示

獨立研究原型｜React + TypeScript × 結構化命盤 × deterministic 三合四正 × LLM grounding

English version · 系統架構 · 公開 System Prompt · 線上產品

Important

作品背景：這是我約一個月完成的研究型前端作品。 我想驗證的不是「AI 能不能講得像命理師」，而是能否把一個容易被 LLM 幻覺污染的領域，拆成可驗證的資料、可重現的關係演算法、受限的工具呼叫與可閱讀的對話體驗。

Note

線上產品： zewe.life　｜　此 repository 是可公開檢視的前端作品集；不含正式後端、帳號資料、API key、Firebase 或部署設定。

Warning

不是權威命理服務。 本專案僅供研究、技術展示與娛樂使用，請勿視為醫療、法律、財務或人生決策建議。

專案介紹

ZEWE 是我約一個月完成的獨立研究型前端作品，不是把 LLM 偽裝成會自行排盤的工具。正式流程會先由 server 驗證命盤資料；前端則以程式固定計算三合四正，AI 只根據已提供的宮位切片與受限工具結果解讀。因此模型不能自行猜星曜、宮位、流年或三合四正關係。

這份作品集著重於 React 介面設計、結構化 domain data、deterministic relation logic、可追問的聊天 UX，以及公開可檢視的 System Prompt 資料邊界。命理規則採使用者指定的倪海廈取向作為研究參照，並明確記錄午夜換日規則；不宣稱任何師承或權威性。

為什麼不是直接把八字交給 AI 計算紫微斗數？

核心取捨：把 LLM 從「計算器」降為「有證據的解讀層」。 直接把八字或出生資料以自然語言交給模型，模型必須自行處理農曆／時區／真太陽時／子時換日、排星、宮位與三合四正；即使文字看似合理，計算過程也難以重現或審核。ZEWE 則先建立確定的資料契約，再交給模型做語言解讀。

直接把八字／出生資料交給 LLM	ZEWE 的結構化流程
模型自行推估換日、時區、真太陽時、排星與宮位關係	計算引擎／server 先驗證出生資料，輸出版本化的 profile、palaces、relations
同一題可能受 prompt、對話歷史或模型版本影響，難以重現	三合四正以固定 index 公式產生並有 unit test；相同輸入取得相同結構化脈絡
AI 容易把不在資料裡的星曜、宮位或流年補成「看似合理」的答案	System Prompt 限制 AI 只能引用傳入的宮位切片；本命不使用計算工具，流運最多一個驗證結果
為了補足資訊而反覆長 prompt，增加 token、延遲與錯誤面積	只傳送本題需要的精簡資料切片，前端明示回答依據與可追問範圍

這不是在宣稱命理內容必然正確，而是在展示一個可維護的 AI engineering 觀點：以 deterministic domain tool 建立 ground truth，以 schema 與 prompt policy 限縮模型，以 UI 把資料來源與推論範圍呈現給使用者。

工程考量與設計決策

我考量的問題	工程決策	展示的技術能力
命盤內容若讓 LLM 自行排算，答案即使流暢也無法驗證	先由計算服務建立 schema 化命盤，再把必要的 profile、palaces、relations 傳給模型	LLM grounding、資料契約、責任邊界設計
三合四正若靠 prompt 敘述，很容易算錯或前後不一致	以十二宮 index 的模運算固定產生主宮、對宮與兩個三合宮，並以 unit test 保護	Deterministic algorithm、TypeScript、Vitest
時區、真太陽時與子時換日會影響後續資料	把輸入正規化與規則判定留在計算層；UI 僅呈現校正狀態與可追溯資料	Domain modelling、資料正規化、產品誠實性
流運題目若任由模型反覆呼叫工具，會變慢也難控制成本	本命題不呼叫計算工具；時間型題目最多接受一個 server 驗證結果	Tool policy、延遲／token 控制、可預期 UX
AI 回覆時間較長時，使用者容易以為系統卡住	把進度、最終回覆與建議追問分開；建議問題帶入可編輯輸入框，不自動送出	Streaming-ready UX、interaction design、使用者掌控權
公開研究展示不能洩漏正式環境或使用者資料	示範資料採合成 fixture，公開範圍文件化，並以 CI 驗證型別、關係演算法與 build	Privacy by design、文件化、CI/CD 基礎

技術專業摘要

• React + TypeScript 前端工程：可存取的表單標籤、鍵盤 focus、行動版版面與 prefers-reduced-motion。
• Deterministic domain logic：src/lib/chartRelations.ts 以固定公式計算三合四正，並由 Vitest 覆蓋核心關係與邊界。
• LLM grounding / prompt engineering：公開 System Prompt 定義資料來源、不可推測事項、本命與流運的工具上限，以及輸出中的建議追問結構。
• 結構化資料介面：不是傳一大段命盤文字，而是以 compact context 將焦點宮、對宮、三合宮與必要 profile 切片交給模型。
• 長時間 AI 互動設計：以狀態、回答、可修改的追問分層，讓使用者知道等待什麼、也能保有發問主導權。
• 可交付性：MIT License、公開範圍、架構文件、單元測試與 GitHub Actions 全部一併放入 repo。

核心技術流程

flowchart LR
    A["出生資料 UI"] --> B["輸入正規化"]
    B --> C["私有計算服務"]
    C --> D["驗證後的本命盤"]
    C --> E["最多一個流運驗證結果"]
    D --> F["Compact structured context"]
    E --> F
    F --> G["System Prompt + LLM"]
    G --> H["狀態、解讀與建議追問"]
    H --> I["可編輯的使用者輸入"]

Loading

計算層負責可重現的資料；模型層負責自然語言；介面層負責讓使用者看見範圍與證據。完整契約請見 系統架構。

本機執行與品質驗證

npm install
npm run dev
npm run lint
npm test
npm run build

公開 repo 導覽

路徑	內容與責任
src/components/	可存取的出生資料輸入、十二宮互動圖與聊天解盤介面
src/lib/chartRelations.ts	三合四正固定關係公式與型別定義
src/lib/chartRelations.test.ts	主宮、對宮、三合與 index 邊界的單元測試
src/data/	僅供展示的合成命盤 fixture，不含真實使用者資料
prompts/ZEWE_SYSTEM_PROMPT.md	與後端資料契約對齊的公開 System Prompt
docs/	架構、公開範圍與工程決策說明
public/screenshots/	本 README 顯示的產品截圖

畫面預覽

手機版起始流程：出生資料、性別與真太陽時校正選項。

解盤對話：回答引用結構化命盤範圍，並提供可編輯的建議追問。

---

English Version

A one-month personal R&D prototype exploring how a conversational AI interface can stay grounded in structured, deterministic Zi Wei Dou Shu chart data.

Interview takeaway: rather than asking an LLM to calculate a chart from free-form Bazi or birth data, ZEWE treats the model as a grounded interpretation layer. A deterministic calculation service verifies the input and produces a compact, versioned chart contract; the model may interpret only that evidence.

Why this exists

ZEWE is an independent research case study, not a claim of supernatural prediction. The frontend turns a birth-chart workflow into an inspectable product experience:

• a mobile-first birth-input flow with an optional true-solar-time flag;
• an interactive twelve-palace chart with deterministic 三合四正 highlighting;
• a chat-oriented analysis surface with visible structured-data boundaries;
• follow-up suggestions that move into the editable input instead of auto-sending;
• clear loading, status, keyboard, focus, and reduced-motion states.

The production product is available at zewe.life. This repository is intentionally a safe, self-contained frontend showcase: it has no production backend, user data, Firebase configuration, OAuth material, API key, or deployment secret.

Technical decisions worth reviewing

Concern	Design in this showcase
Model hallucination	The UI visualizes only a server-verified chart contract; the model is instructed to use supplied relations, never reconstruct a chart from prose.
三合四正	src/lib/chartRelations.ts computes target, opposite, and two trine indexes deterministically and is covered by unit tests.
Prompt / data boundary	The public prompt documents the exact trust boundary: structured natal data first; at most one server tool result for a transit query.
Long-running AI UX	The chat surface separates progress/status from final content and keeps suggested follow-up questions editable.
Privacy	The demo uses synthetic chart data only. Production credentials and identity services are intentionally excluded.

Run locally

npm install
npm run dev

Useful checks:

npm run lint
npm test
npm run build

Repository map

src/
  components/      Accessible input, chart, and conversation UI
  data/            Synthetic chart fixture only
  lib/             Deterministic 三合四正 relation logic + tests
public/screenshots/ Curated product screenshots shown in this README
prompts/           Public, backend-aligned system prompt
docs/              Architecture, scope, and integration contract

Production integration boundary

The deployed system keeps calculation and model access on the server. The browser sends normalized birth input and a user question; the server produces a compact structured context such as profile, palaces, main, opposite, and trines. For transit questions it may return one verified calculation result. The LLM receives that data plus the system prompt; it is not trusted to calculate a chart, invent palace relationships, or expand to extra periods.

See docs/ARCHITECTURE.md for the full contract.

Scope and disclaimer

This is a one-month independent research/prototyping exercise in UI design, deterministic domain tools, and LLM grounding. It is for curiosity and entertainment only — please do not treat it as fact, diagnosis, legal/financial advice, or a substitute for professional judgment.

The interpretive configuration references the user-specified Ni Hai Xia-oriented conventions: a midnight date boundary for late/early 子時 and no Flying Stars extrapolation. It does not claim endorsement, lineage, or authority from any person or school.

License

MIT