Jyotisha/docs/engine/vedastro-gateway.md

VedAstro Gateway、用户级入口与 Codex 插件

本文从根 README 拆出（2026-09-03），内容原样保留：VedAstro 官方/自建/本地回退三种模式的配置、中国大陆 Gateway 部署边界、scripts/vedastro_user_entrypoint.py 用户级入口，以及把本仓装成 Codex 本地插件的步骤。

VedAstro：聊天产品推荐配置

项目当前固定使用官方 Python SDK vedastro==1.23.25。首次安装依赖时必须安装到项目虚拟环境，并用同一个解释器启动后端，避免子进程落到系统 Python 后出现 No module named vedastro：

.venv/bin/pip install -r requirements.txt
.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200

在仓库根目录创建本机私有配置文件 .env.local。聊天场景推荐先使用下面的快速官方证据模式：

VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
VEDASTRO_ENABLE_NETWORK=1
VEDASTRO_TIMEOUT_SECONDS=20
VEDASTRO_GATEWAY_REQUIRE_OFFICIAL_RAW_RESPONSE=1

# 聊天快速模式：保留 Dasha / Chara Dasha / Shadbala / Ashtakavarga，
# 不执行 10 行星 + 12 宫位的逐项 fan-out。
VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=0

# 免费公共模式下 SearchEvents 范围扫描耗时长且容易限流，
# 聊天请求中默认关闭，避免同步阻塞流式回复。
VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=0

VEDASTRO_CACHE_TTL_SECONDS=604800
VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=604800
VEDASTRO_GATEWAY_QUEUE_ENABLED=1
VEDASTRO_FREE_TIER_QUEUE=1
VEDASTRO_FAIL_OPEN_LOCAL=1
VEDASTRO_FULL_CATALOG_SAMPLE_LIMIT=0

# 没有 key 时可先使用官方公共/免费模式；不要把 key 放到前端。
# VEDASTRO_API_KEY=your_vedastro_key

该文件已被 .gitignore 忽略；scripts/jyotish_api_server.py、scripts/vedastro_service_adapter.py、scripts/run_quality_gate.py 会自动加载它。VedAstro 子进程默认复用启动后端的 sys.executable；如需指定独立解释器，可设置 VEDASTRO_PYTHON_BIN=/absolute/path/to/python。

快速模式仍会取得 VedAstro 官方原始响应，并让 Gateway 在存在 official_raw_response 时闭合为 official_verified；D1/D9 等基础盘继续由本地 Swiss Ephemeris 负责。它只关闭高延迟 fan-out 与 SearchEvents 范围扫描，不等于关闭 VedAstro。

获得稳定 API key，或把 Gateway 指向自建 VedAstro 服务后，可开启完整模式：

VEDASTRO_API_KEY=your_vedastro_key
VEDASTRO_FULL_SNAPSHOT_FANOUT_ENABLED=1
VEDASTRO_RANGE_SCAN_NETWORK_ENABLED=1

完整模式会增加外部请求数量和首包等待时间，更适合后台任务、预计算或非实时专业解盘，不建议直接放在聊天首轮的同步关键路径。运行 .venv/bin/python scripts/diagnose_vedastro_mode.py 可检查当前模式；通过 /api/vedastro_gateway/status 查看 Gateway 的实际配置和 readiness。

AI/vibe coding 推荐入口：Cline 接本仓 MCP，Aider 负责低成本小改，Dyad 只做前端原型。运行 python3 scripts/print_cline_mcp_config.py 生成 Cline MCP 配置；详情见 docs/vibe_coding_setup.md。

中国大陆用户：VedAstro Gateway 模式

普通中国大陆用户不需要、也不应该让浏览器直连 VedAstro。推荐部署方式是：网页只访问你自己的本地或云端后端；后端通过 VedAstro Gateway 统一管理 self-host、official upstream、TTL/cache、free-tier queue 和 local fallback。

最短配置：

cp .env.cn.example .env.local
.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200
npm ci --prefix frontend
npm run dev --prefix frontend

网页侧使用：

• Trust Center -> Web Professional Reading v1
• /api/vedastro_gateway/status 查看当前后端策略
• /api/vedastro_gateway/run 生成 VedAstro-compatible evidence packet
• /api/professional_reading 生成网页专业解盘包

关键边界：

• 不要让浏览器直连 VedAstro，也不要把 VEDASTRO_API_KEY 放进前端。
• VEDASTRO_CACHE_TTL_SECONDS 和 VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS 用于缓存官方或自建服务结果。
• VEDASTRO_GATEWAY_QUEUE_ENABLED=1 / VEDASTRO_FREE_TIER_QUEUE=1 用于把昂贵或被限流的外部请求排队。
• 如果 VedAstro 官方或自建服务不可达，VEDASTRO_FAIL_OPEN_LOCAL=1 会保持本地 Jyotish 引擎继续输出，并在 Technique Audit Table 里降级标注。
• Gateway 不会默认声称跑完 641 项；它只把 capability catalog、dynamic selection、cache/queue/fallback 状态作为证据边界交给 strict workflow。

Codex 用户级 VedAstro + strict workflow 入口

如果用户在 Codex 窗口从云端 Git 仓库拉取本项目，推荐先走这一条稳定入口，而不是手动拼多个底层脚本：

python3 scripts/vedastro_user_entrypoint.py \
  --year YYYY --month MM --day DD --hour HH --minute mm \
  --lat LAT --lon LON --tz TZ \
  --question "事业机会什么时候出现" \
  --themes career,marriage,wealth \
  --reference-date 2026-07-02 \
  --format markdown

机器读取或交给后续 agent 处理时使用 JSON：

python3 scripts/vedastro_user_entrypoint.py \
  --year YYYY --month MM --day DD --hour HH --minute mm \
  --lat LAT --lon LON --tz TZ \
  --question "事业机会什么时候出现" \
  --themes career,health,education,property,children,migration,prashna \
  --reference-date 2026-07-02 \
  --format json

这个入口会自动做四件事：

1. 读取 .env.local 并诊断当前是 official_extended 还是 fast_local_fallback。
2. 启动 official_full_capability_catalog，给 VedAstro 官方能力目录生成 domain / execution_policy / adjudicator_use / confidence_role / blocked_reason。
3. 按 --themes 做动态选择，避免把健康、教育、房产、子女、迁移、Prashna 等非三大主题塞进 general。
4. 触发 strict workflow 合同摘要，输出 primary route、可用 route、cache/TTL/free-tier queue 策略和 honesty boundary。

边界必须保留：这个入口不会把 641 项全部当作已执行。它先做官方能力目录分类和主题选择；能自动执行的进入证据层，需要第二人资料、用户文本、校时画像或官方网络预算的方法会保持 needs_user_context、needs_user_text、needs_rectification_profile 或 blocked。

作为 Codex 本地插件安装

本仓现在带了最小插件包装：.codex-plugin/plugin.json。它复用现有 skills/ 与根目录 mcp_server.py，适合你把当前仓直接装进 Codex 本机环境。

1. 先把本仓登记到个人 marketplace：

python3 <home>/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py \
  jyotish-vedic-astrology \
  --path ~/.codex/plugins \
  --marketplace-path ~/.agents/plugins/marketplace.json \
  --marketplace-name personal \
  --with-marketplace

上面是 Codex 官方脚本的标准 marketplace 流。如果你要让 当前仓本身 被安装，关键不是用 scaffold 目录跑能力，而是让 ~/.agents/plugins/marketplace.json 里的 jyotish-vedic-astrology 条目最终指向当前仓路径。

最少要确认这一条存在：

{
  "name": "jyotish-vedic-astrology",
  "source": {
    "source": "local",
    "path": "<repo>"
  }
}

2. 若本机还没把 personal marketplace 接进 Codex：

codex plugin marketplace add ~/.agents/plugins/marketplace.json

3. 安装插件：

codex plugin add jyotish-vedic-astrology@personal

4. 检查是否已被识别：

codex plugin list

5. 开一个新线程再测试。Codex 只会在新线程里重新拾取新装的 skills / MCP。

本地更新 / 重装

当你改了 .codex-plugin/plugin.json、skills/ 或 mcp_server.py：

python3 <home>/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  <repo>

codex plugin add jyotish-vedic-astrology@personal

然后重新开新线程验证。

推荐的 official extended .env.local 示例：

VEDASTRO_API_ENDPOINT=https://api.vedastro.org/api
VEDASTRO_ENABLE_NETWORK=1
VEDASTRO_TIMEOUT_SECONDS=20
VEDASTRO_CACHE_TTL_SECONDS=600
VEDASTRO_OFFICIAL_FULL_SNAPSHOT_CACHE_TTL_SECONDS=600
VEDASTRO_FREE_TIER_QUEUE=1
# 可选
# VEDASTRO_API_KEY=sk_live_xxx

先运行：

python3 scripts/diagnose_vedastro_mode.py

若仍显示 fast_local_fallback，用户级入口仍可运行，但解盘必须把 VedAstro official 证据写成 blocked/降级，不能声称 official extended 已闭环。