Jesse_Chen
8db71aaf81
- README.md is now the product/repo front door (architecture, repo map, local dev, test tiers, delivery flow, doc map). Engine positioning, VedAstro/Codex setup and the oracle/benchmark command reference move verbatim to docs/engine/README.md, docs/engine/vedastro-gateway.md and docs/benchmark/README.md. Capability badges realigned with the registry (91/78/8/0); tests/test_readme_badges.py was red on staging. - AGENTS.md: Part A (environment truth, delivery, worktrees, record placement, bug workflow, growth freeze, frontend red lines, privacy, pre-work check, test tiers) and Part B (reading-rigor constraints). GitHub issue-tracker/triage boilerplate removed: GitHub is a read-only mirror. All strings locked by tests/ are preserved. - CLAUDE.md added: roles, three working modes, task-brief sections, acceptance criteria, session discipline; imports AGENTS.md. - 50 tracked TASK-*/PROGRESS-* files and 3 never-committed briefs move to docs/tasks/ with an index; REPO_LAYOUT.md merged into README. Docs-only change (no gated path touched). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0193vBv6w5MV2cifdTUu9H5P
202 lines
8.4 KiB
Markdown
202 lines
8.4 KiB
Markdown
# 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 已闭环。
|