# 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`：

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

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

```dotenv
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 服务后，可开启完整模式：

```dotenv
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。

最短配置：

```bash
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 仓库拉取本项目，推荐先走这一条稳定入口，而不是手动拼多个底层脚本：

```bash
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：

```bash
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：

```bash
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` 条目最终指向当前仓路径。

最少要确认这一条存在：

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

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

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

3. 安装插件：

```bash
codex plugin add jyotish-vedic-astrology@personal
```

4. 检查是否已被识别：

```bash
codex plugin list
```

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

#### 本地更新 / 重装

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

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

codex plugin add jyotish-vedic-astrology@personal
```

然后重新开新线程验证。

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

```bash
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
```

先运行：

```bash
python3 scripts/diagnose_vedastro_mode.py
```

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