Jesse_Chen
779717f48c
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P
Jyotisha — 中文印度占星对话产品
Jyotisha（jyotisha.chat）是一个面向中文用户的印度占星（Jyotish / Vedic astrology）对话产品。用户用聊天的方式提问，Agent 依据本仓的 Python 计算引擎与 Skill 方法给出带证据边界的解读。产品有三个主面：
| 产品面 | 用户做什么 | 主要代码 |
|---|---|---|
| 对话咨询 | 保存出生资料后直接提问事业、关系、时运等 | frontend/src/app/page.tsx + frontend/src/mastra/ + Python /api/consultation_workflow |
| 生时校正 | 出生时间不确定时，通过访谈式问答收窄到可信区间与代表分钟 | frontend/src/components/rectification-*、frontend/src/modules/、scripts/active_rectification_*.py |
| 个人报告 | 按主题分章生成正式报告，附证据附录 | frontend/src/components/personal-report/、skills/jyotish-personal-report/ |
另有管理后台（/admin：用户、订单、模型供应商、功能开关、对话质量记录）与点数计费。
目录
架构
jyotisha.chat
-> Spaceship DNS
-> Caddy（生产 VPS 118.194.235.34，唯一公网入口 80/443）
-> Next.js + Mastra web 容器（3000，仅 Docker 内网）
-> Python Jyotish API 容器（5200，仅 Docker 内网）
-> Swiss Ephemeris 本地计算引擎
-> VedAstro Gateway（官方/自建/本地回退）
-> 私有 PostgreSQL 17 + Better Auth（账户、会话、点数、报告）
-> 外部 OpenAI-compatible 模型与邮件供应商
- Next.js 负责界面、输入校验、Agent 编排（Mastra）与流式回复；Python 服务是星盘、分盘、时序与证据计算的唯一事实来源；模型不得自行重算行星位置。
- 模型供应商与 API key 在管理端配置，AES-256-GCM 加密后存库；运行时不读供应商 key 环境变量。
- 生产与 staging 环境的所有事实（主机、端口、密钥位置、Compose 文件、部署与恢复命令）以
deploy/README.md为准。staging 地址是https://staging.jyotisha.chat。
仓库地图
| 路径 | 内容 | 生命周期 |
|---|---|---|
frontend/ |
Next.js 16 / React 19 产品前端、Mastra Agent、API 路由、Drizzle 迁移、前端测试 | 产品代码 |
scripts/ |
Python 计算引擎、jyotish_api_server.py API 服务、校正引擎、质量门与工具脚本 |
产品代码 |
jyotish_vedic/ |
Python 包入口（CLI、engine、MCP） | 产品代码 |
skills/ |
Mastra 实际加载的 Skill 包（对话、校正、报告；含哈希锁定版本） | 产品代码 |
SKILL.md、references/ |
商业 Skill 入口与方法参照、技法注册表、oracle 样本、冻结的方法学 | 知识资产 |
contracts/ |
前后端共享的 JSON 合同 | 产品代码 |
deploy/ |
Caddy、Compose、部署/迁移/恢复脚本、gated-paths.txt |
运维事实来源 |
.gitea/workflows/ |
唯一的 CI/CD 控制面（staging 门禁、生产手动发布） | 运维 |
tests/、frontend/tests/ |
Python 与前端的回归/合同测试 | 产品代码 |
mcp_server.py |
面向裁决器的 MCP 入口 | 产品代码 |
web/ |
Python API 自带的调试页（/、/evidence、/rectification），不是产品 UI |
调试 |
docs/ |
任务书、Bug 历史、运维手册、测试清单、benchmark 看板、研究笔记 | 记录 |
benchmarks/、artifacts/ |
外部引擎对照与 e2e 采集产物 | 研究 |
scratch/local/ |
本地一次性脚本与输出，git 忽略 | 本地 |
新增文件前先判断它属于哪个生命周期：可复用的项目资产、活跃研究笔记、归档研究、本地脚本、本地输出。后两类不进仓库根目录。
本地开发
环境
- Python 3.11 或 3.12，必须用项目自己的虚拟环境（
pyswisseph装在其中；系统 Python 3.9 不可用）。 - Node.js 20+。
- 本地数据库测试需要 Docker（起临时 PostgreSQL）；没有 Docker 时相关测试会被跳过或阻塞，见 测试与门禁。
启动
# 首次：创建虚拟环境并安装引擎依赖
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
# 1. Python API（星盘计算的事实来源）
.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
curl http://127.0.0.1:5200/api/health # swisseph_available 必须为 true
# 2. 网页
npm ci --prefix frontend
npm run dev --prefix frontend # http://localhost:3000
前端配置写在 frontend/.env.local（至少 JYOTISH_API_BASE 与 MODEL_PROVIDER_CONFIG_ENCRYPTION_KEY），细节见 frontend/README.md。仓库根目录的 .env.local 给 Python 侧用（VedAstro 模式等），模板是 .env.cn.example / .env.official.example；VedAstro 三种模式与中国大陆 Gateway 部署边界见 docs/engine/vedastro-gateway.md。
测试与门禁
| 层 | 命令 | 说明 |
|---|---|---|
| Python 快速门 | .venv/bin/python scripts/run_quality_gate.py --profile quick |
普通代码改动后必跑；browser / release / accuracy / vedastro-live 四个 profile 分别加前端、发布前、准确率、外部雷达检查 |
| Python 定向 | .venv/bin/python -m pytest tests/<file>.py |
合同测试会锁 README、AGENTS.md、行数上限等 |
| 前端类型与 lint | cd frontend && ./node_modules/.bin/tsc --noEmit && npm run lint |
lint 必须 0 error（react-hooks 编译器规则已能分析首页） |
| 前端测试 | npm test --prefix frontend |
无 Docker 时 DB/部署套件会阻塞，比对失败清单与基线而不是宣称全绿 |
| 数据库测试 | npm run test:db --prefix frontend |
需要 Docker；动表的轮次必须真跑 |
| 生产构建 | npm run build --prefix frontend |
/ 必须保持 ○ Static |
CI 只有 Gitea：推到 staging 触发 backend-quality-gate（构建 digest 固定镜像并部署 staging）；纯文档推送（deploy/gated-paths.txt 之外的路径）不触发门禁、不部署。生产发布是手动流程，复用 staging 已验收的镜像。
浏览器级验收（登录、双标签页、刷新/后退、校正全流程）目前依赖真人按 docs/testing/ 的清单执行；自动化环境没有登录态与 Chrome。
交付流程
staging 是测试环境分支，main 是生产控制分支，main 只能从 staging 快进。协作代理的完整硬约束在 AGENTS.md，Claude 会话的分工在 CLAUDE.md。一轮工作的记录落点：
- 任务书与进度：
docs/tasks/（索引） - 被挡住的事：
BLOCKED.md - Bug 事实与防复发：
docs/BUG_HISTORY.md - 行为与 Skill 变化：
CHANGELOG.md - 视觉与交互合同：
frontend/DESIGN.md；文案口径：frontend/docs/VOICE.md - 领域术语：
CONTEXT.md
引擎与技法边界
The Python engine routes the technique registry (references/technique_registry.json, currently 116 entries: 79 covered, 8 complete, 25 guarded, 4 comparison-only; original badge values were 91 / 78 / 8 / 4 / 1) as a backend evidence pool, not as a flat list of user-facing prediction sources. The evidence-pool policy in scripts/capability_evidence_pool.py was written against 89 capability entries and its conclusion rules have not changed: the question-domain router selects a small primary chain (for example D10 + A10 for career, D9 + UL for relationships, D2 / D11 for wealth), uses supporting indicators only to raise or lower confidence, and every reading ends with a Technique Audit Table that says what was executed, what is blocked, and what is not applicable. Audit-only and alias entries cannot affect conclusions.
用户不知道问什么时，产品默认不反问，而是：
- 调用统一入口
/api/consultation_workflow（MCP 对应strict_workflow）。 - 先生成
evidence_packet、guided_topics与 Technique Audit Table。 - 把
guided_topics里的建议主题按优先级展示给用户，用户选题后再进入专题strict_workflow。
从云端仓库加载后先跑 python3 scripts/user_invocation_acceptance_check.py，只有 "status": "pass" 且外部引擎状态被标为 available / partial / missing_dependency 时才做高严谨解盘。
诚实边界：所有 benchmark 看板固定输出 can_claim_global_first: false 与 production_tuning_allowed: false；covered 不等于外部 oracle 闭环。引擎定位、八阶段流水线、技法覆盖表与自评见 docs/engine/README.md；准确率基线、外部 oracle 采集与看板命令见 docs/benchmark/README.md。
文档地图
| 想知道 | 看 |
|---|---|
| 协作代理必须遵守什么 | AGENTS.md |
| Claude 会话怎么分工、任务书怎么写 | CLAUDE.md |
| 生产/staging 怎么部署、恢复、验证 | deploy/README.md、docs/operations/ |
| 前端怎么配、Skill 怎么触发 | frontend/README.md |
| 视觉与交互合同、文案口径 | frontend/DESIGN.md、frontend/docs/VOICE.md |
| 某个 Bug 以前出没出过 | docs/BUG_HISTORY.md |
| 某轮任务做了什么、为什么 | docs/tasks/、BLOCKED.md |
| 真人验收清单 | docs/testing/ |
| 引擎定位与技法覆盖 | docs/engine/README.md |
| VedAstro / Codex 插件 / 用户级入口 | docs/engine/vedastro-gateway.md |
| 准确率、oracle、benchmark | docs/benchmark/README.md |
| Skill 方法与真相覆盖层 | SKILL.md、skills/*/SKILL.md、references/ |
| 引擎/基础设施历史错误台账 | docs/research/pre_work_error_ledger.md |
| 架构决策记录 | docs/adr/ |
| 早期实现日志（不是运行说明） | docs/history/ |
隐私与安全红线
- 真实用户出生资料、邮箱、姓名、会话内容、JWT、Cookie、密钥，不得进入 skill 文件、测试、CHANGELOG、Bug 历史、任务书或任何提交。
- 测试与示例只用公开名人数据或明确虚构的数据。
- 端口
5200、模型 key、数据库口令、SSH 私钥不得暴露；生产密钥只存在服务器0600文件中。 - 不得放宽任何置信度或验证边界，除非有外部 benchmark 证据。
- 医疗、法律、投资、安全关键结论与确定性死亡/诊断/妊娠预测禁止输出。
License
MIT，见 LICENSE。
致谢：Swiss Ephemeris、PyJHora（naturalstupid/PyJHora）、VedAstro（VedAstro/VedAstro）、BPHS、PVN Rao / KN Rao 的教学传承。
本系统是研究与咨询辅助工具，不应在没有合格人类占星师参与的情况下用于改变人生的决定。