# Jyotisha Web Jyotisha 是 `yinduzhanxing` 的聊天式消费者 Web 前端。它使用 Next.js App Router 提供用户与 Mastra Agent 的连续问答，同时继续复用仓库现有的 Python 印度占星计算工作流。它不生成固定报告。 ## 架构 ```text Browser -> Next.js /api/consult -> Mastra agent -> 按问题语义加载 jyotish-vedic-astrology Skill -> consultation tool -> Python /api/consultation_workflow ``` - Next.js 只负责产品界面、输入校验和结果呈现。 - Python 服务仍是星盘、分盘、时序与证据计算的事实来源。 - Skill 提供方法、路由和真实性边界；它不会替代 Python 的实际排盘计算。 - Mastra 只能基于工具返回的数据组织语言；工具失败时会明确降级，不生成虚构星位。 - Agent 回答通过 `/api/consult` 以纯文本流返回；前端在收到分片时增量渲染 Markdown，而不是等待整段回答完成。 ## 环境要求 - Node.js 20+ - Python 3.11 或 3.12（主项目代码不兼容系统自带的 Python 3.9） - OpenAI 或兼容 OpenAI Chat Completions 的第三方模型 Key。至少要配置一个可用模型；未配置时咨询入口会明确提示模型服务不可用，不会扣点或返回伪造摘要。 - Supabase 项目，用于邮箱 OTP 登录、咨询点数、一次性兑换码和账务流水。 ## 配置 ```bash cd /Users/jesse/Downloads/Copse/astrology/yinduzhanxing/frontend # 仓库不提供含占位密钥的 .env.example；请新建仅供本机使用的 .env.local $EDITOR .env.local ``` `.env.local`： ```dotenv # Python 占星计算服务 JYOTISH_API_BASE=http://127.0.0.1:5200 # 模型供应商配置加密主密钥：严格 Base64 编码的 32 字节随机值 MODEL_PROVIDER_CONFIG_ENCRYPTION_KEY= # OpenAI-compatible 自定义端点可使用任意公网 HTTPS origin；无需配置域名白名单 ``` 模型目录、供应商地址及 API key 均通过管理端配置；API key 使用上述主密钥 AES-256-GCM 加密后存入数据库。运行时不读取 `LLM_MODELS_JSON`、`LLM_BASE_URL`、`LLM_MODEL` 或供应商 API-key 环境变量。 供应商地址仍受服务端 SSRF 防护：仅允许 HTTPS、禁止用户名/密码、拒绝 localhost、内网和保留地址；域名必须解析到公网地址，请求会固定到已验证的 DNS 地址并拒绝重定向。 ## Skill 如何触发 不需要输入 `/skill` 命令。Mastra 会先把 Skill 的 `name` 和 `description` 提供给模型；当用户问题与印度占星、解盘、推运、Dasha、Transit、Nakshatra、Yoga 等语义匹配时，Agent 会按需加载完整 Skill，再调用计算工具。 例如，先在“个人资料”中保存出生信息，然后直接发送： ```text 请根据我的出生资料，分析未来一年事业发展和适合跳槽的时间窗口。 ``` 完整链路是： ```text 用户问题 -> Mastra 识别并加载 jyotish-vedic-astrology -> Agent 依据 Skill 选择工作流 -> run-jyotish-consultation -> Python consultation_workflow -> Agent 流式组织聊天回答 ``` 必须配置可用的模型 Key 才会进入这条链路。没有配置模型时，`/api/models` 返回 `503`，聊天框会停止发送；`/api/consult` 也会在预扣点数前拒绝未知或不可用模型。成功咨询始终由 Mastra Agent 生成流式回答。 仓库根目录的主 `SKILL.md` 通过 `skills/jyotish-vedic-astrology/` 这个 Mastra 兼容目录加载。该目录名必须与 Skill frontmatter 中的 `name` 一致。生产部署时需确保 `SKILL.md`、`references/`、`scripts/` 和 `assets/` 一起存在；如果目录结构不同，请设置 `JYOTISH_SKILL_PATH`。 ## 本地启动 先创建并使用项目自己的 Python 3.11/3.12 虚拟环境。这样 `pyswisseph` 会安装在 API 实际使用的解释器中，避免星盘工具因缺少 `swisseph` 降级或报错： ```bash cd /Users/jesse/Downloads/Copse/astrology/yinduzhanxing # 首次执行；把 python3.12 换成你机器上可用的 Python 3.11/3.12 python3.12 -m venv .venv .venv/bin/python -m pip install -r requirements.txt # 每次启动 API 都使用同一个虚拟环境 .venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200 ``` 如果你的终端没有 `python3.12`，请先安装或定位一个 Python 3.11+ 解释器后再创建 `.venv`；不要使用 macOS/Xcode 自带的 Python 3.9。 再启动 Web： ```bash cd /Users/jesse/Downloads/Copse/astrology/yinduzhanxing/frontend npm install npm run dev ``` 默认访问 `http://localhost:3000`。如果该端口已被占用，Next.js 会自动选择下一个可用端口。 ## 验证 ```bash npm run lint npm run build ``` ## 当前产品能力 - Supabase 邮箱 OTP 登录；未登录用户不能调用咨询接口。 - 左侧聊天 Session、每个 Session 的消息与更新时间均存储在 Supabase；切换 Session 会将该会话的最近上下文提交给 Agent。 - 出生资料与称呼位于“账户与出生资料”面板，保存后可在同一账号的所有 Session 与其他设备间复用。 - 账户、出生档案、聊天历史、点数和兑换记录均存储在 Supabase，并通过 RLS 限制为用户只能读取和修改自己的数据。 - 出生地点支持中国的国家 / 省级 / 市级 / 县区四级选择，按行政区中心坐标进行星盘计算。 - 没有每日提问次数限制。点击发送后有 2.5 秒免费撤回窗口，此时尚未调用模型或预扣点数。窗口结束后咨询开始并预扣 1 点；首个输出分片前取消会幂等退款，已经收到输出后停止会保留现有内容并正常计费，避免部分回答被无限免费获取。 - Agent 流式回答支持 Markdown 与 GFM 表格。 - 首次进入空 Session 时，Agent 会在聊天区引导填写出生资料。保存后，Mastra 中的 onboarding Agent 会按照 `jyotish-vedic-astrology` Skill 生成欢迎语和事业、关系、时运三个入门问题；结果按版本缓存到 Supabase，同一用户不会在每次刷新时重复消耗模型。每次正式回答则在同一次咨询 Agent 调用中生成三个与当前解读相关的后续问题，并随 Session 保存到 Supabase。 ## 中国出生地点数据 个人资料中的出生地点目前覆盖中国的省级、市级与县区级行政区。位置数据为行政区中心点，不是地址级定位；如需更新本地快照： ```bash cd /Users/jesse/Downloads/Copse/astrology/yinduzhanxing/frontend PATH="/opt/homebrew/bin:$PATH" npm run data:china ``` 数据来源与许可证说明见 `src/data/CHINA_LOCATION_DATA.md`。 ## Supabase 账户、点数与兑换码 ### 1. 创建项目并配置环境变量 在 Supabase 创建项目后，将 Project Settings / API 中的值写入 `.env.local`： ```dotenv NEXT_PUBLIC_SUPABASE_URL=https://PROJECT_REF.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key ADMIN_EMAILS=admin@example.com,ops@example.com ``` - `NEXT_PUBLIC_*` 只包含允许浏览器使用的项目 URL 和 anon key。 - `SUPABASE_SERVICE_ROLE_KEY` 可以绕过 RLS，只能放在服务端环境变量中，绝不能加 `NEXT_PUBLIC_`、提交到 Git 或展示给前端。 - `ADMIN_EMAILS` 是逗号分隔的管理员邮箱白名单。没有配置时普通账户仍可登录，但 `/admin/codes` 不可用。 ### 2. 执行数据库迁移 使用 Supabase CLI： ```bash npx supabase login npx supabase link --project-ref PROJECT_REF npx supabase db push ``` 也可以在 Supabase SQL Editor 中执行： ```text supabase/migrations/20260715000000_account_credits.sql supabase/migrations/20260715010000_harden_credit_rpcs.sql supabase/migrations/20260715020000_service_role_table_grants.sql supabase/migrations/20260715030000_user_profiles_chat_sessions.sql supabase/migrations/20260715040000_agent_onboarding_cache.sql supabase/migrations/20260717000000_consultation_request_lifecycle.sql supabase/migrations/20260717010000_chat_session_model.sql ``` 迁移会创建： - `profiles`：用户点数余额、称呼与出生档案。 - `chat_sessions`：用户的聊天 Session、消息、每个 Session 选用的模型和最近更新时间。 - `redemption_codes`：只保存兑换码 SHA-256 与掩码，不保存完整码。 - `credit_transactions`：兑换、预扣、退款和模型 Token 用量流水。 - `redeem_code`：一次性兑换，使用行锁保证同一码全局只成功一次，并记录兑换账户。 - `consultation_requests`：保存每次咨询的 `reserved` / `completed` / `cancelled` 结算状态。 - `begin_consultation_credit` / `complete_consultation_credit` / `cancel_consultation_credit`：仅允许服务端 `service_role` 调用，通过请求级事务锁保证预扣、完成与退款互斥且幂等。 ### 3. 配置邮箱验证码模板 在 Supabase Dashboard 的 Authentication / Email Templates 中编辑 Magic Link 模板，使用验证码而不是登录链接： ```html

登录 Stellara

你的登录验证码是：

{{ .Token }}

验证码仅用于本次登录。如果不是你本人操作，请忽略这封邮件。

``` 登录页会调用 `verifyOtp({ email, token, type: "email" })` 校验验证码；不要把模板改回 `{{ .ConfirmationURL }}`。还应在 Authentication / URL Configuration 中配置本地和生产站点 URL。 ### 4. 创建第一批兑换码 1. 使用 `ADMIN_EMAILS` 中的邮箱登录。 2. 打开 `/admin/codes`。 3. 选择每个兑换码包含的点数、数量、有效期和备注。 4. 点击生成后立即复制完整码；刷新或离开页面后只会保留掩码。 相同兑换码只能兑换一次；首次兑换后会永久记录兑换账户、邮箱和时间。新注册用户默认 0 点，因此即使 demo URL 被转发，也不能在没有兑换码的情况下调用 Agent。 ## 当前线上部署 当前生产 Demo 使用 `https://jyotisha.chat`，Next.js、Mastra 和 Python API 通过 Docker Compose 部署在香港 VPS，Supabase 与模型 API 继续使用云服务。服务器、DNS、环境变量、更新和验收命令统一以 [`../deploy/README.md`](../deploy/README.md) 为准。 ## Vercel + Supabase 备选部署 以下方案只作为无服务器备选，不是当前线上拓扑。 ### Web 部署到 Vercel 将 `frontend` 作为 Vercel Root Directory，并在 Vercel Project Settings / Environment Variables 配置： ```dotenv NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... SUPABASE_SERVICE_ROLE_KEY=... ADMIN_EMAILS=... MODEL_PROVIDER_CONFIG_ENCRYPTION_KEY= JYOTISH_API_BASE=https://your-python-api.example.com ``` 模型目录及供应商 API key 仅由管理端数据库配置提供；环境只保留 `MODEL_PROVIDER_CONFIG_ENCRYPTION_KEY` 主密钥。不要把任何密钥写进浏览器代码。 ### Python 服务必须单独部署 Vercel 上的 Next.js 不能访问你电脑的 `127.0.0.1:5200`。需要把仓库根目录的 Python API 部署到可从公网 HTTPS 访问的服务，例如独立 VM、Railway、Render 或 Fly.io，然后把公开地址写入 `JYOTISH_API_BASE`。 部署完成后依次验证： ```text 1. Python 健康检查和 consultation_workflow 可访问 2. 邮箱 OTP 可以登录 3. 管理员可以生成兑换码 4. 普通账户只能兑换一次 5. 余额为 0 时不能咨询 6. 成功回答扣 1 点 7. Agent/服务端在首个输出前异常时点数退回；已有输出后异常会保留现有内容并正常计费 8. 用户在 2.5 秒撤回窗口内停止时不调用模型、不扣点 9. 撤回窗口结束后、首个输出分片前取消时点数退回 10. 用户已经收到输出后停止时保留已有内容并正常计费 11. 登录后 `/api/models` 只返回模型 ID、名称、说明、点数和默认状态，不包含 Key、端点或环境变量名 12. 不同 Session 能保存各自的模型选择；已下线模型会回退到默认模型 ``` ## Demo 防滥用边界 当前版本采用“登录 + 兑换码点数”而不是每日次数限制： - 所有咨询请求必须有有效 Supabase 登录态。 - 余额不足时服务端不会调用模型或 Python 工具。 - 兑换码一次性使用并绑定账号，数据库不保存完整码。 - 预扣和退款只允许服务端 service role 调用，且以 `request_id` 幂等。 - 服务端拦截系统提示词、Skill 原文和密钥提取请求；Agent 也被限制不得给出医疗、法律、投资等安全关键指令或确定性死亡/诊断预测。 - 这不是完整内容审核平台。正式公开投放前，可再增加登录/兑换接口速率限制、验证码防机器人和运营后台封禁能力，但不需要把产品改成“每天最多问几次”。 ## 尚未实现 - 微信/支付宝/Stripe 等真实支付与自动发码。 - 管理员禁用尚未兑换的兑换码。 - 完整的风控、审计后台和退款工单。