diff --git a/AGENTS.md b/AGENTS.md index 08489714..efb63b36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,31 +1,156 @@ -# Jyotish Skill Agent Constraints +# Jyotisha Agent Constraints -本文件是当前项目给协作代理、自动化助手与派生工作流的硬约束补充。它不替代 `SKILL.md`，而是把最容易被偷懒、省略、或在多窗口工作时遗失的高严谨规则单独钉死。 +本文件对所有协作代理生效（Claude Code、Codex、Cursor 以及派生工作流）。它把最容易被省略、或在多窗口工作时遗失的规则钉死。`CLAUDE.md` 只补充 Claude 会话的分工，不重复这里的规则；`frontend/AGENTS.md` 是 Next.js 版本提示。 -## 0. Production Maintenance Truth +全文分两部分：**Part A** 是所有代码与文档工作的约束；**Part B** 只在输出占星解读（解盘、推运、校正解释）时生效。 -任何部署、线上故障、域名、登录或环境变量任务，先读取 `deploy/README.md`，不要重新猜测架构。 +## 0. 先读什么 -- Production domain: `https://jyotisha.chat` -- Primary source: `https://git.copse.top/root/Jyotisha.git`; GitHub upstream/mirror: `https://github.com/jesse-ux/Jyotisha.git` -- Migration target: Ubuntu VPS `118.194.235.34`; confirmed SSH port is a required deployment variable -- Target runtime: `/opt/jyotisha-production`, Compose project `jyotisha-production` -- Target secrets: `/opt/jyotisha-production/.env.production` and `.env.production.database`; never print, copy into chat, or commit -- Public edge: Caddy only; Next.js `3000` and Python API `5200` stay Docker-private -- Migration source: Spaceship DNS and Supabase project `vtvnfqmonbfuxmqkqdlc`; production target uses private PostgreSQL + Better Auth -- Capacity boundary: 2 vCPU / 4 GB RAM; use digest-pinned images, bounded DB pools, and no on-host application builds -- Cutover runbook: `docs/operations/production-server-migration-2026-08.md`; old VPS/Supabase remain rollback assets until final reconciliation +| 任务类型 | 开工前必读 | +| --- | --- | +| 任何任务 | 本文件 §1–§4；`git status -sb` 的第一行（确认分支） | +| 前端改动 | `frontend/AGENTS.md`、`frontend/DESIGN.md`、`frontend/docs/VOICE.md`、§7 | +| Bug / 报错 / 回归 | §5，并检索 `docs/BUG_HISTORY.md` | +| 部署、线上故障、域名、登录、环境变量 | `deploy/README.md`（不要重新猜架构） | +| 引擎、外部 oracle、镜像边界、远端同步、发布 | §9 与 `docs/research/pre_work_error_ledger.md` | +| 领域术语（会话、轮次、故障、评价） | `CONTEXT.md`；命名与术语表一致，见 `docs/agents/domain.md` | +| 输出占星解读 | Part B | -Deployment safety rules: +--- -1. Run `git status --short --branch` before packaging; do not overwrite unrelated dirty files. -2. Before cutover, verify the authoritative DNS still matches the documented current phase; after cutover both user and admin hosts must resolve to `118.194.235.34`. -3. The target uses Better Auth with exact user/admin origins; migrated users must sign in again by OTP. -4. After deployment, verify `/login`, logged-out `/api/account` = `401`, internal `/api/health` = `200`, and `swisseph_available = true`. -5. Never expose port `5200`, `SUPABASE_SERVICE_ROLE_KEY`, model keys, user JWTs, passwords, or SSH private keys. -6. Production deployment is manual-only in Gitea. It consumes the exact staging-gate image digests, requires matching `main`/`staging`/public-staging SHA plus the manual release gate, and never changes DNS or imports production data. GitHub production deployment is retired. +# Part A · 代码与文档工作 -## 1. High-Rigor Override +## 1. 生产与环境真相 + +- Production domain: `https://jyotisha.chat`；staging: `https://staging.jyotisha.chat` +- Primary source and the only CI/CD control plane: `https://git.copse.top/root/Jyotisha.git`（Gitea）。GitHub `https://github.com/jesse-ux/Jyotisha.git` 是只读镜像：无 workflow、Actions 已关闭，不得用它验证交付状态，也没有 GitHub Issues 流程。 +- Production host: Ubuntu VPS `118.194.235.34`，专用 `deploy` 用户，SSH 端口是部署变量；2 vCPU / 4 GB RAM，只跑 digest 固定镜像，不在主机构建。 +- Runtime: `/opt/jyotisha-production`，Compose project `jyotisha-production`，Compose 文件 `deploy/docker-compose.server.yml`。 +- Secrets: `/opt/jyotisha-production/.env.production` 与 `.env.production.database`（`0600`）；never print, copy into chat, or commit。 +- Public edge: Caddy only；Next.js `3000` 与 Python API `5200` 仅 Docker 内网。 +- Persistence: 同主机私有 PostgreSQL 17 + Better Auth。从 Supabase 的迁移已切换完成；旧 VPS 不再是部署目标，Supabase 项目按 `docs/operations/production-server-migration-2026-08.md` 作为回滚资产保留到最终对账。 +- API 容器有命名卷 `api_scratch`（chart 缓存与异步任务态）；重计算端点受 `JYOTISH_HEAVY_COMPUTE_CONCURRENCY`（默认 2）限流，饱和返回 429。 + +部署安全规则： + +1. 打包前 `git status --short --branch`；不得覆盖无关的脏文件。 +2. 部署后验证 `/login`、未登录 `/api/account` = `401`、内部 `/api/health` = `200` 且 `swisseph_available = true`；`deployment.gitCommit` 必须等于预期 SHA。 +3. 不得暴露端口 `5200`、模型 key、数据库口令、用户 JWT、SSH 私钥。 +4. 生产部署只走 Gitea 手动流程（先 `release-quality-gate`，再 dispatch `deploy-production`），复用 staging 已验收的镜像 digest；不改 DNS、不导入生产数据。 + +## 2. 分支与交付 + +分支模型：`staging` 是测试环境，`main` 是生产控制分支。所有改动先经 `staging` 验收，再提升到 `main`；不存在直接改 `main` 的路径。 + +1. 动手前 `git fetch origin --prune`，以远端 **`origin/staging`** 为基线。本地 `staging` / `main` 经常落后远端上百个提交，不得作为基线。 +2. 在独立 worktree 开发：路径 `.worktrees/<主题>-<日期>`，分支 `codex/<主题>-<日期>`（见 §3）。 +3. 交付到 staging 用快进推送 `git push origin HEAD:staging`。这会触发 Gitea `backend-quality-gate`；它的 `paths:` 过滤与 `deploy/gated-paths.txt` 逐行一致。改动**全部**落在清单之外的纯文档推送（`docs/**`、根目录 `BLOCKED.md` / `CHANGELOG*.md` / `CONTEXT.md` / `AGENTS.md` / `CLAUDE.md` / `README.md` 等）不触发门禁、不发布镜像、不部署。鼓励把文档与同批代码合并一次推送，避免 staging head 与已部署 SHA 分离。 +4. 门禁构建 digest 固定镜像并 dispatch `deploy-staging`；随后在 staging 完成与风险相称的验收。`GET /api/health` 的 `.deployment.gitCommit` 必须等于**最近一次含门禁路径改动的 staging 提交**；其后若只有纯文档提交，`deploy/is-docs-only-range.sh <该 SHA> ` 必须退出 0，否则视为未部署。 +5. 提升到 `main` **必须快进，不得 merge**。`deploy-production.yml` 强制 `main` 与 `staging` 指向同一 SHA，merge commit 会让生产部署失败。 +6. 推送后必须核对远端 SHA；远端验证失败时不得声称已交付。 +7. 不得自行提升 `main`、不改 `.gitea/workflows/**`、不动 DNS——这三件事只由产品负责人触发。 + +## 3. 工作树与多会话 + +同一台机器上经常有多个代理会话并行，主检出 `/workspace/Jyotisha` 可能被别的会话切到别的分支。 + +1. 任何 git 操作前先看 `git status -sb` 第一行确认分支；不要假设自己还在上次的分支上。 +2. 代码工作只在自己的 worktree 里做：`git worktree add -b codex/<主题>-<日期> .worktrees/<主题>-<日期> origin/staging`。 +3. 文档/任务书推 staging 时，用专门跟踪 `staging` 的 worktree（例如 `.worktrees/staging-docs`）：`git pull --ff-only origin staging` → commit → push；不要在主检出上直接 commit 到 staging。 +4. 不得在有未提交修改的工作树上切分支、stash、reset、覆盖或顺带提交别人的变更；不得 reset / rebase 别的会话的分支。误落到别人分支上的提交用 cherry-pick 搬走并告知。 +5. 两个同时改 `frontend/src/app/page.tsx` 或同一组件的轮次必须串行，任务书里写明先后。 + +## 4. 记录文件放哪 + +| 内容 | 位置 | 规则 | +| --- | --- | --- | +| 任务书、执行进度 | `docs/tasks/TASK-<主题>-<日期>.md`、`docs/tasks/PROGRESS-<主题>-<日期>.md` | 新文件只写这里，不再放仓库根目录；索引在 `docs/tasks/README.md` | +| 被环境/依赖挡住的事项 | `BLOCKED.md`（根目录） | 写清缺什么、替代证据是什么；解除后划掉而不是删除 | +| Bug 事实、根因、防复发 | `docs/BUG_HISTORY.md` | 见 §5；编号连续，开工时核对当前最大号 | +| 用户可感知的行为与 Skill 变化 | `CHANGELOG.md` | 日期 + 一句话标题 + 变更要点；Skill 版本是否 bump 写明 | +| 视觉、动效、等待态、间距 | `frontend/DESIGN.md` | 改 UI 的同一提交内更新；`CLAUDE_DESIGN.md` 是上游参照不改 | +| 文案口径 | `frontend/docs/VOICE.md` | 新文案先对照 | +| 真人验收清单 | `docs/testing/` | 自动化做不了的浏览器级验收写成可照做的条目 | +| 领域术语 | `CONTEXT.md` | 新术语先加到 glossary 再用 | + +`progress.md`、`findings.md`、`task_plan.md` 是早期实现日志，不是运行或部署说明，不再追加。 + +## 5. Bug History Workflow Hard Constraint + +任何包含"Bug、报错、失败、异常、回归、无法保存、无法删除、状态码错误、线上故障"等现象的任务，开始诊断前必须用报错原文、接口路径、状态码、模块名和用户操作强制检索，并完整读完命中的记录。该文件体量已不允许通读全文，但检索不是可选步骤，命中记录的防复发措施是否仍然存在必须逐条确认： + +- `docs/BUG_HISTORY.md` + +这份文件是产品与代码 Bug 的长期历史入口；`docs/research/pre_work_error_ledger.md` 负责基础设施、外部引擎、碎片目录与预检风险，两者不得互相替代。 + +1. 修复前必须用报错原文、接口路径、状态码、模块名和用户操作搜索历史记录，优先检查相同模块的根因与防复发措施。 +2. 若历史问题复发，必须关联原 `BUG-NNN`，说明旧测试、约束或发布门禁为何未拦住；不得把复发伪装成无关的新问题。 +3. Bug 修复必须在同一变更中更新 `docs/BUG_HISTORY.md`：补充现有记录或新增连续编号，并记录状态、现象、触发条件、根因、修复、验证、防复发、关联记录和修复版本。 +4. 若当轮只能诊断或被阻塞，也要把已确认事实写成 `investigating` 或 `blocked`，不得编造根因或提前标记 `resolved`。 +5. `resolved` 必须有与风险相称的证据：至少一个针对性回归测试；生产问题还必须有脱敏后的迁移、部署、健康检查或 smoke 证据。 +6. Bug 历史严禁写入姓名、出生资料、邮箱、用户/案例 ID、Cookie、JWT、密码、密钥、完整请求体或模型原文。 + +## 6. 代码增长冻结 + +- `scripts/jyotish_api_server.py` must not grow. New endpoints and features go in dedicated modules under `scripts/` and are thinly registered from the main file. Do not add new handler bodies, workflows, or feature branches to this file. The cap is enforced by `tests/test_api_server_growth_contract.py`（冻结时行数 + 300 行 bugfix 余量）。 +- `frontend/src/app/page.tsx` 已从 4,766 行拆到 2,000 行以下，**不得再增长**：新逻辑进 `frontend/src/hooks/`、`frontend/src/lib/` 或组件；参数式 hook 内部保持 0 个 React hook 的既定模式。 +- 不得再手写第二个聊天输入框（一律 `ChatComposer`，自有草稿走 `value`）、第二套滚动跟随（一律 `useConversationScrollAnchor` + `JumpToLatestButton`）、第二套加载动画（揭幕后不得出现 spinner / 骨架 / "正在加载"，流式生成中除外）。 + +## 7. 前端红线 + +1. `./node_modules/.bin/tsc --noEmit` 通过；`npm run lint` **0 error**（react-hooks 编译器规则会拦 effect 内同步 setState、render 写 ref 等）。 +2. `next build` 后 `/` 保持 `○ Static`；首屏 gzip 变化在 ±2% 内，超出要在进度记录里给出原因。 +3. 测试总数不得低于开工时 `origin/staging` 的实测；改任何既有断言必须写"原值 / 新值 / 原因"三栏说明，不得静默弱化。 +4. 合同测试的 fixture 必须来自真实引擎响应（golden），不得手造形状。 +5. 改 UI 的提交同时更新 `frontend/DESIGN.md`；新文案对照 `frontend/docs/VOICE.md`。 +6. 不改数据库结构的轮次不得顺带动迁移；动表的轮次必须真跑 `npm run test:db`。 +7. 不得顺手升级依赖、不得顺手修不在任务书里的 warning；发现了写进 `BLOCKED.md` 或进度记录。 + +## 8. 隐私与安全 + +1. 真实用户出生资料、姓名、邮箱、会话内容、JWT、Cookie、密钥，不得进入 skill 文件、测试、CHANGELOG、Bug 历史、任务书、进度记录或任何提交。示例只用公开名人或明确虚构数据。 +2. 不得读取、猜测或借用他人的凭据与账号做验收；没有受控账号就把该项写进 `BLOCKED.md`。 +3. 供应商地址必须经服务端 SSRF 防护；不得把任何 key 放进前端。 +4. 不得放宽置信度或验证边界，除非有外部 benchmark 证据。 + +## 9. 开工预检（引擎 / 基础设施 / 发布类任务） + +为避免多窗口、多镜像、碎片目录导致重复误判，涉及运行入口、镜像边界、外部 oracle、远端同步、适配器、发布或大规模资料治理的任务，开工前必须读取： + +- `docs/research/pre_work_error_ledger.md` + +若还涉及碎片目录或镜像仓，再读： + +- `docs/research/whole_machine_fragment_sweep_2026_07_05.md` +- `docs/research/whole_machine_fragment_sweep_round25_2026_06_25.md` + +并运行： + +- `python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45`（包含 `scripts/diagnose_external_engine_adapters.py --json`） + +要求：不得把 `.workbuddy` 镜像当作运行主仓；不得在 `git ls-remote` / fetch / push 失败时声称云端已同步；新发现的重复错误、阻塞、碎片目录、远端验证失败追加到错误台账。 + +纯前端文案或组件改动不要求跑这条预检，但 §2、§3 照常。 + +## 10. 测试分层与环境缺口 + +| 层 | 命令 | 何时必跑 | +| --- | --- | --- | +| Python 快速门 | `.venv/bin/python scripts/run_quality_gate.py --profile quick` | 任何 Python 改动 | +| Python 定向 | `.venv/bin/python -m pytest tests/.py` | 改了对应模块 | +| 前端 | `tsc --noEmit`、`npm run lint`、`npm test`、`npm run build` | 任何前端改动 | +| 数据库 | `npm run test:db --prefix frontend`（需 Docker） | 动表 | +| 发布前 | `run_quality_gate.py --profile release` | 提升 `main` 前 | + +已知环境缺口，遇到时如实写进 `BLOCKED.md` 而不是宣称通过：无 Docker（DB/部署套件阻塞，用与基线逐条一致的失败清单代替）；无登录态与 Chrome（浏览器级验收留给 `docs/testing/` 清单）；无模型凭据（真实模型输出留待部署后复核）。 + +--- + +# Part B · 解盘类任务硬约束（只在输出占星解读时生效） + +以下规则不替代 `SKILL.md` 与 `references/strict-workflow-router.md`，而是把其中最容易被省略的高严谨要求单独钉死。纯计算、纯代码、纯项目维护任务不适用。 + +## B1. High-Rigor Override 当用户明确要求以下任一项时，必须进入高严谨模式： @@ -40,137 +165,31 @@ Deployment safety rules: 1. 必须尝试交叉参照 `PyJHora`、`VedAstro`、`jyotishganit`，并保持许可证边界。 2. 必须优先调用本仓原生实现，不得只用轻量包装脚本代替主链代码。 3. 涉及 timing / event / outcome，不得只看 `Vimshottari`，至少需要 `Vimshottari + Narayana Dasha` 双轨交叉。 -4. 必须按问题域强制调取相关分盘： - - 事业：`D10 + A10` - - 财富：`D2 / D11` - - 婚恋：`D9 + UL` +4. 必须按问题域强制调取相关分盘：事业 `D10 + A10`；财富 `D2 / D11`；婚恋 `D9 + UL`。 5. 必须交付原始数据依据：度数、Dasha 边界、Shadbala / Ashtakavarga、Yoga 名称、Ayanamsa / Node mode、外部证据路径。 -## 2. Functional Benefic/Malefic Hard Constraint +## B2. Functional Benefic/Malefic Hard Constraint -**强制调取 Functional Benefic / Malefic 判定（功能性吉凶星判定）。** - -这条约束与 Dasha / 分盘 / 原始数据交付同级，不得省略。 - -执行要求： +**强制调取 Functional Benefic / Malefic 判定（功能性吉凶星判定）。** 这条约束与 Dasha / 分盘 / 原始数据交付同级，不得省略。 1. 每次进入高严谨模式，必须显式判定当前 Lagna 下的 `functional benefics` 与 `functional malefics`。 -2. 任何关于事业、财富、婚恋、健康、障碍、回报、应期的结论，都不得只依据自然吉凶星（natural benefic/malefic）下判断，必须叠加功能性吉凶星层。 +2. 任何关于事业、财富、婚恋、健康、障碍、回报、应期的结论，都不得只依据自然吉凶星下判断，必须叠加功能性吉凶星层。 3. 若某颗星在自然属性与功能属性之间冲突，必须在输出中说明冲突来源，并降低置信度或标记 `blocked`。 4. 若未调用功能性吉凶星判定，不得声称该次解读完成了高严谨模式。 -5. Technique Audit Table 中必须出现 `Functional Benefic/Malefic` 一行，说明： - - `Used / not used / blocked` - - 关键功能吉星 - - 关键功能凶星 - - 对结论置信度的影响 +5. Technique Audit Table 中必须出现 `Functional Benefic/Malefic` 一行，说明 `Used / not used / blocked`、关键功能吉星、关键功能凶星、对结论置信度的影响。 -## 3. Existing MEVG Invocation Hard Constraint +## B3. Existing MEVG Invocation Hard Constraint -**强制执行既有 MEVG 规则，不得把它当成可选增强项。** - -本节不是新增一套验证系统，而是把 `SKILL.md` 与 -`references/mandatory-verification-gate-protocol.md` 中已经存在的 MEVG -外部验证门控提升为协作代理硬约束。 - -执行要求： +**强制执行既有 MEVG 规则，不得把它当成可选增强项。** 本节不是新增一套验证系统，而是把 `SKILL.md` 与 `references/mandatory-verification-gate-protocol.md` 中已经存在的 MEVG 外部验证门控提升为协作代理硬约束。 1. 对用户提出的 **所有星盘运势类问题**、**所有有关印度占星推运的问题**，包括命盘解读、事业、财富、婚恋、健康、流年、流月、应期、事件预测、出生时间校正辅助和技法可靠性判断，必须执行 MEVG。 -2. MEVG 必须包含： - - 全球 / 全网外部资料采集 - - 真实案例参考 - - 来源分级 - - 冲突仲裁 - - 未验证声明降级 -3. 输出的 Technique Audit Table 必须出现以下两行： - - `MEVG / Global Web Evidence` - - `Real Case Calibration` +2. MEVG 必须包含：全球 / 全网外部资料采集、真实案例参考、来源分级、冲突仲裁、未验证声明降级。 +3. 输出的 Technique Audit Table 必须出现 `MEVG / Global Web Evidence` 与 `Real Case Calibration` 两行。 4. 若无法完成外部资料采集、无法找到真实案例、网络/工具不可用、或来源之间出现重大冲突，必须写成 `blocked` 或降级置信度，不得静默跳过。 -5. 只有 **纯计算 / 纯代码 / 纯项目维护** 可以豁免 MEVG，例如运行测试、检查 Git 状态、修复代码、输出未解释的原始度数或 Dasha 边界。一旦开始解释“这代表什么运势”，豁免立即失效。 +5. 只有 **纯计算 / 纯代码 / 纯项目维护** 可以豁免 MEVG（运行测试、检查 Git 状态、修复代码、输出未解释的原始度数或 Dasha 边界）。一旦开始解释"这代表什么运势"，豁免立即失效。 -## 4. Honesty Boundary +## B4. Honesty Boundary -以下情况必须明确写成 `blocked` 或降级置信度： +以下情况必须明确写成 `blocked` 或降级置信度：外部 oracle 尚未闭环；三大外部参照引擎中有一层无法合法或稳定调用；缺少分盘、Ayanamsa、Node mode 或出生精度；功能性吉凶星层未完成；双重大运或多系统结果发生实质冲突；MEVG / Global Web Evidence 或 Real Case Calibration 未完成。 -- 外部 oracle 尚未闭环 -- 三大外部参照引擎中有一层无法合法或稳定调用 -- 缺少分盘、Ayanamsa、Node mode 或出生精度 -- 功能性吉凶星层未完成 -- 双重大运或多系统结果发生实质冲突 -- MEVG / Global Web Evidence 或 Real Case Calibration 未完成 - -禁止把内部一致性伪装成“已经全球顶级精度”。 - -## 5. Pre-Work Error Ledger Hard Constraint - -为避免多窗口、多应用、多文件夹碎片导致重复误判，开工前 / 进行任何实质项目工作前必须读取： - -- `docs/research/pre_work_error_ledger.md` - -若任务涉及运行入口、镜像边界、外部 oracle、远端同步、适配器、测试验收或大规模资料治理，还必须读取： - -- `docs/research/whole_machine_fragment_sweep_2026_07_05.md` -- `docs/research/whole_machine_fragment_sweep_round25_2026_06_25.md` - -同时必须运行： - -- `python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45` - -该预检必须包含： - -- `scripts/diagnose_external_engine_adapters.py --json` - -执行要求： - -1. 不得把 `.workbuddy` 镜像当作运行主仓。 -2. 不得在 `git ls-remote` / fetch / push 等远端验证失败时声称云端已同步。 -3. 不得在未查看当前 `git status --short --branch` 时覆盖或重置本地变更。 -4. 新发现的重复错误、阻塞、碎片目录、远端验证失败，必须追加到错误台账或当轮 sweep 文档。 - -## 6. Git Branch Delivery Hard Constraint - -分支模型：`staging` 是测试环境，`main` 是生产控制分支。所有改动必须先经 -`staging` 验收，再提升到 `main`；不存在直接改 `main` 的交付路径。 - -1. 动手前必须 `git fetch origin --prune`，并以远端 **`origin/staging`** 为基线。不得基于本地 `staging` 或本地 `main`：这两个本地引用经常落后远端上百个提交，基于它们做出的分析和补丁会对不上真实代码。 -2. 在独立 worktree 中开发，路径 `.worktrees/<主题>-<日期>`，分支 `codex/<主题>-<日期>`。不得在存在未提交修改的工作树上切换分支、stash、reset、覆盖或顺带提交用户变更。 -3. 交付到 staging 用快进推送（`git push origin HEAD:staging`）。这会触发 Gitea `backend-quality-gate`；该工作流的 `push:` 触发带有与 `deploy/gated-paths.txt` 逐行一致的 `paths:` 过滤：改动**全部**落在该清单之外的纯文档推送（`docs/**`、根目录 `TASK-*.md` / `PROGRESS-*.md` / `CHANGELOG*.md` / `progress.md` / `task_plan.md` / `findings.md` / `BLOCKED.md` / `CONTEXT.md`、`AGENTS.md` 等记录文件）不触发门禁、不发布镜像、不部署；任何触及清单内路径的推送都会跑完整构建与部署。仍鼓励把文档与同批代码合并一次推送——文档单独推送虽不再取消正在运行的代码门禁，但会让 staging head 与已部署 SHA 分离，增加核对成本。 -4. 由 quality gate 构建 digest 固定镜像并 dispatch `deploy-staging`，随后在 `https://staging.jyotisha.chat` 完成与风险相称的验收。`GET /api/health` 的 `.deployment.gitCommit` 必须等于**最近一次含门禁路径改动的 staging 提交**，而不再是 staging head：若其后只有纯文档提交，`deploy/is-docs-only-range.sh <该 SHA> ` 必须退出 0（publish 与 deploy-staging 对分叉、落后或含门禁路径的 head 仍会拒绝发布）；否则视为未部署。 -5. 提升到 `main` **必须快进，不得 merge**。`.gitea/workflows/deploy-production.yml` 强制 `main` 与 `staging` 指向同一个 commit SHA；任何 merge commit 都会让生产部署以 `main and staging must identify the same reviewed release` 失败。 -6. 生产部署手动执行：先跑 `release-quality-gate`，再 dispatch `deploy-production`。它复用 staging 已验收的镜像 digest，不重新构建。 -7. 推送后必须核对远端 SHA，确认 `origin/staging`（以及提升后的 `origin/main`）确实包含目标提交；远端验证失败时不得声称已交付。 -8. GitHub `upstream` 仅为镜像：其工作流文件已从仓库删除，GitHub Actions 已在仓库设置中关闭，不得用它验证交付状态。 - -## 7. Bug History Workflow Hard Constraint - -任何包含“Bug、报错、失败、异常、回归、无法保存、无法删除、状态码错误、线上故障”等现象的任务，开始诊断前必须用报错原文、接口路径、状态码、模块名和用户操作强制检索，并完整读完命中的记录。该文件体量已不允许通读全文，但检索不是可选步骤，命中记录的防复发措施是否仍然存在必须逐条确认： - -- `docs/BUG_HISTORY.md` - -这份文件是产品与代码 Bug 的长期历史入口；`docs/research/pre_work_error_ledger.md` 继续负责基础设施、外部引擎、碎片目录与预检风险，两者不得互相替代。 - -执行要求： - -1. 修复前必须用报错原文、接口路径、状态码、模块名和用户操作搜索历史记录，优先检查相同模块的根因与防复发措施。 -2. 若历史问题复发，必须关联原 `BUG-NNN`，说明旧测试、约束或发布门禁为何未拦住；不得把复发伪装成无关的新问题。 -3. Bug 修复必须在同一变更中更新 `docs/BUG_HISTORY.md`：补充现有记录或新增连续编号，并记录状态、现象、触发条件、根因、修复、验证、防复发、关联记录和修复版本。 -4. 若当轮只能诊断或被阻塞，也要把已确认事实写成 `investigating` 或 `blocked`，不得编造根因或提前标记 `resolved`。 -5. `resolved` 必须有与风险相称的证据：至少一个针对性回归测试；生产问题还必须有脱敏后的迁移、部署、健康检查或 smoke 证据。 -6. Bug 历史严禁写入姓名、出生资料、邮箱、用户/案例 ID、Cookie、JWT、密码、密钥、完整请求体或模型原文。 - -## Agent skills - -### Issue tracker - -Issues and PRDs are tracked in this repository's GitHub Issues using the `gh` CLI. See `docs/agents/issue-tracker.md`. - -### Triage labels - -Triage uses the canonical `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, and `wontfix` labels. See `docs/agents/triage-labels.md`. - -### Domain docs - -Domain documentation uses the single-context layout. See `docs/agents/domain.md`. - -## 8. API Server Growth Freeze - -`scripts/jyotish_api_server.py` must not grow. New endpoints and features go in dedicated modules under `scripts/` and are thinly registered from the main file. Do not add new handler bodies, workflows, or feature branches to this file. The line-count cap is enforced by `tests/test_api_server_growth_contract.py` (live count at freeze plus 300 lines of bugfix slack). +禁止把内部一致性伪装成"已经全球顶级精度"。候选出生时间不得写成 confirmed；医疗、法律、投资、安全关键结论及确定性死亡/诊断/妊娠预测禁止。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..9f0e57fb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,37 @@ +@AGENTS.md + +# Claude 会话分工（CLAUDE.md） + +`AGENTS.md` 是所有代理的硬约束，上面已整体导入。本文件只写 Claude Code 会话在这个仓库里的角色、默认工作模式和验收口径。 + +## 角色 + +- **产品负责人（用户）**：非程序员。做产品决策、在真实环境实测、触发 `main` 提升与生产发布。用中文沟通；结论先行，数字进表，不要让他读代码。 +- **Claude**：产品经理 + 架构 + 验收。读代码做诊断、定方案、写任务书、事后逐项验收；只有在用户明说"直接执行 / 用 subagent 做"时才亲自改代码。 +- **coding agent（Cursor / Codex / Claude subagent）**：按任务书执行，写进度记录与 Bug 历史，推 staging。 + +## 三种工作模式 + +1. **任务书模式（默认）**：修复或改造类需求 → Claude 写 `docs/tasks/TASK-<主题>-<日期>.md` 并推到 `staging`（纯文档推送不触发门禁）→ 执行方在 `codex/<主题>-<日期>` 分支实现 → Claude 拉最新代码验收。 +2. **直接执行模式**：用户明确说"直接开始执行"或"用 subagent"。Claude 自己（或派 fork 子代理）在独立 worktree 上实现，仍然写 `docs/tasks/PROGRESS-*.md`、`docs/BUG_HISTORY.md`，验收由 Claude 独立再做一遍。 +3. **验收模式**：执行方回报后，Claude 基于 `origin/staging` 或指定分支跑 tsc / lint / 测试 / Python 定向测试，对照任务书逐条给出通过 / 未通过 / 环境缺口三种结论，并把未通过项写成修复单（`TASK-<主题>-fix-<日期>.md`）。 + +## 任务书必须有的段落 + +基线 commit → 事故实证（行号按符号定位）→ 根因 → **决策记录**（产品授权了什么；若推翻既有任务书或 Bug 历史里的红线，必须在这里写明，否则执行方会拒改）→ 硬红线 → 任务分解（每条带验收标准）→ 让步顺序 → 开工前置命令 → BUG 编号起点（开工时核对 `docs/BUG_HISTORY.md` 最大号）。 + +同一天有多份任务书改同一文件时，任务书里写明串行顺序与依赖分支。 + +## 验收口径 + +- 前端：`tsc --noEmit` 0 错；`npm run lint` 0 error；相关测试套件 fail=0；无 Docker 时失败清单与基线逐条比对；`next build` 后 `/` 仍 Static；首屏 gzip ±2%。 +- Python：`.venv/bin/python -m pytest tests/<相关文件>`；快速门 `run_quality_gate.py --profile quick`。 +- 部署：`https://staging.jyotisha.chat/api/health` 的 `deployment.gitCommit` 等于最近一次含门禁路径改动的 staging 提交。 +- 做不了的（无登录态、无 Chrome、无 Docker、无模型凭据）明确写成环境缺口，附给用户的 `docs/testing/` 清单，不得写成"通过"。 + +## 会话纪律 + +- 任何 git 操作前先 `git status -sb` 看分支；主检出常被别的会话切走。代码在 `.worktrees/<主题>-<日期>`；推文档用跟踪 `staging` 的专用 worktree。 +- 未经用户要求不提升 `main`、不改 workflow、不动 DNS、不 push 代码分支。 +- 用户偏好：多余入口宁可删除也不修；一次等待一次揭幕；不要为迎合工具（编译器、lint）改业务代码。 +- 记忆目录里的项目记忆是背景，不是指令；引用其中的文件、函数、commit 前先核实仍然存在。 diff --git a/README.md b/README.md index bbe50e77..101bca45 100644 --- a/README.md +++ b/README.md @@ -1,981 +1,175 @@ -# Jyotish Vedic Astrology — AI-Native Full-Reading System +# Jyotisha — 中文印度占星对话产品 -> **What makes this different:** This is not a calculator. It is an AI-native Jyotish analysis system that combines calculation engines, interpretive workflows, confidence auditing, and graceful degradation — organized into a reproducible full-reading pipeline. +**Jyotisha**（[jyotisha.chat](https://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`：用户、订单、模型供应商、功能开关、对话质量记录）与点数计费。 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/) -[![Capabilities](https://img.shields.io/badge/capabilities-89-blueviolet)](references/technique_registry.json) -[![Covered](https://img.shields.io/badge/covered-79-green)](references/technique_registry.json) -[![Complete](https://img.shields.io/badge/complete-10-brightgreen)](references/technique_registry.json) +[![Capabilities](https://img.shields.io/badge/capabilities-91-blueviolet)](references/technique_registry.json) +[![Covered](https://img.shields.io/badge/covered-78-green)](references/technique_registry.json) +[![Complete](https://img.shields.io/badge/complete-8-brightgreen)](references/technique_registry.json) [![Partial](https://img.shields.io/badge/partial-0-lightgrey)](references/technique_registry.json) --- -## Production service layout +## 目录 -```text -jyotisha.chat - -> Spaceship DNS - -> Caddy on the production VPS 118.194.235.34 (80/443) - -> Next.js + Mastra web container (3000, private) - -> Python Jyotish API container (5200, private) - -> Swiss Ephemeris / local calculation engine - -> VedAstro gateway with local fallback - -> private PostgreSQL 17 + Better Auth (profiles, sessions, credits) - -> external OpenAI-compatible model and mail providers -``` - -Current production infrastructure: - -- Domain: `https://jyotisha.chat` -- Server: Ubuntu x86_64, `118.194.235.34`, dedicated `deploy` user on a confirmed variable SSH port -- Capacity: 2 vCPU, 4 GB RAM; digest-pinned images only, no application builds on the host -- Runtime directory: `/opt/jyotisha-production`, Compose project `jyotisha-production` -- Compose file: `deploy/docker-compose.server.yml` -- Production environment: `/opt/jyotisha-production/.env.production` and `.env.production.database` (`0600`, never commit) -- Persistence: private PostgreSQL 17 + Better Auth on the same host -- Primary source repository and Actions control plane: `https://git.copse.top/root/Jyotisha.git`; GitHub (`https://github.com/jesse-ux/Jyotisha.git`) is a read-only mirror with no workflows - -Deployment, recovery, DNS, HTTPS, update and verification commands are documented in [`deploy/README.md`](deploy/README.md). Railway/Vercel remain optional alternatives, not the current production topology. - -## Table of Contents - -- [What Is This](#what-is-this) -- [Quick Start](#quick-start) -- [Core Workflow](#core-workflow) -- [Technique Coverage](#technique-coverage) -- [Why This Exists (Competitive Context)](#why-this-exists) -- [Honest Assessment](#honest-assessment) -- [Project Status](#project-status) -- [Development](#development) -- [Contributing](#contributing) +- [架构](#架构) +- [仓库地图](#仓库地图) +- [本地开发](#本地开发) +- [测试与门禁](#测试与门禁) +- [交付流程](#交付流程) +- [引擎与技法边界](#引擎与技法边界) +- [文档地图](#文档地图) +- [隐私与安全红线](#隐私与安全红线) - [License](#license) --- -## What Is This - -This is a **Vedic (Jyotish) astrology analysis system** designed for deep, auditable full-chart readings. It is NOT a simple ephemeris calculator — it is a multi-stage interpretive pipeline that: - -1. **Computes** divisional charts (D1/D9/D10/...) via Swiss Ephemeris -2. **Routes** 89 capability entries as a backend evidence pool (Dashas, Yogas, Shadbala, Ashtakavarga, Transits...) -3. **Routes** the analysis through strict workflow paths depending on question type (career / relationship / wealth / timing) -4. **Audits** every technique used — declaring what was called, what is complete/covered, and which limitations affect confidence -5. **Degrades gracefully** — limitations are labeled, not silently over-promising - -### Key Differentiators (vs. PyJHora / VedAstro / Maitreya) - -| Feature | This Project | PyJHora | VedAstro | Maitreya | -|---------|-------------|----------|----------|----------| -| Full-reading pipeline (one command) | ✅ | ❌ | ❌ | ❌ | -| Strict workflow router (per-question-type) | ✅ | ❌ | ❌ | ❌ | -| Technique Audit Table (confidence labeling) | ✅ | ❌ | ❌ | ❌ | -| Capability degradation (limits are explicit) | ✅ | ❌ | ❌ | ❌ | -| MEVG external verification gates | ✅ | ❌ | ❌ | ❌ | -| 89 capability entries routed as a backend evidence pool | ✅ | ✅ (50+) | ✅ (200+) | ✅ | -| Traditional algorithm benchmarked | ✅ mixed depth | ✅ | ✅ | ✅ | -| Docker / MCP Server | ✅ | ❌ | ✅ | ❌ | -| English docs / PyPI package | ✅ in progress | ✅ | ✅ | ✅ | - ---- - -## Quick Start - -### 用户不知道问什么时 - -不要让用户自己组织提示词。用户只给出生信息时，AI 应用应默认执行： - -1. 调用统一入口：`/api/consultation_workflow` 或 MCP `strict_workflow`。 -2. 先生成 `evidence_packet`、`guided_topics`、`Technique Audit Table`。 -3. 把 `guided_topics` 里的建议主题展示给用户，按优先级给出可直接点击/复制的问题。 -4. 用户选题后再进入 `strict_workflow` 做事业、婚恋、财富、健康或 timing 专题。 - -默认引导话术： +## 架构 ```text -你不用先想问题。我会先根据出生信息运行统一主链，生成证据包和系统建议主题。 -然后我会列出最值得继续看的 3-5 个方向，每个方向附数据依据、置信度和可直接提问的问题。 +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 模型与邮件供应商 ``` -如果 AI 应用只能调用一个入口，优先用： +- Next.js 负责界面、输入校验、Agent 编排（Mastra）与流式回复；Python 服务是星盘、分盘、时序与证据计算的唯一事实来源；模型不得自行重算行星位置。 +- 模型供应商与 API key 在管理端配置，AES-256-GCM 加密后存库；运行时不读供应商 key 环境变量。 +- 生产与 staging 环境的所有事实（主机、端口、密钥位置、Compose 文件、部署与恢复命令）以 [`deploy/README.md`](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 时相关测试会被跳过或阻塞，见 [测试与门禁](#测试与门禁)。 + +### 启动 ```bash -python3 scripts/vedastro_user_entrypoint.py --year YYYY --month MM --day DD --hour HH --minute mm --lat LAT --lon LON --tz TZ --question "请先生成 guided_topics 并推荐我最值得看的问题" --themes career,marriage,wealth --format markdown -``` - -普通用户 / AI 应用从云端仓库加载后，先跑这一条验收： - -```bash -python3 scripts/user_invocation_acceptance_check.py -``` - -只有输出 `"status": "pass"` 且外部引擎状态被明确标为 `available` / `partial` / `missing_dependency` 时，才继续做高严谨解盘。`VedAstro` 没有官方 `raw_response` 或 API key 时，必须保留 `official_blocked` / `local_fallback` 边界。 -``` - -### 本地 Python 环境（首次一次） - -本地 API 需要 **Python 3.11 或 3.12**，并且必须从项目自己的虚拟环境启动；`pyswisseph` 安装在该环境中。不要使用 macOS/Xcode 自带的 Python 3.9，否则会因不兼容的类型语法或缺少 `swisseph` 导致服务降级或启动失败。 - -在仓库根目录执行： - -```bash -# 将 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` 启动；不要混用系统 `python3`。服务启动后可用 `curl http://127.0.0.1:5200/api/health` 验证 `swisseph_available` 是否为 `true`。 - -若看到 `No module named swisseph`，说明 API 没有使用这个虚拟环境；重新执行上面的安装命令，再用 `.venv/bin/python` 启动。脚本入口已支持其内部 `scripts.*` 包导入，不需要通过修改 `PYTHONPATH` 绕过错误。 - -### 本地开发启动路径 - -本地开发使用当前生产链的 Next.js 前端： - -1. 先启动本地 API 服务：`.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200` -2. 安装并启动网页服务：`npm ci --prefix frontend && npm run dev --prefix frontend` -3. 打开 `http://127.0.0.1:3000`；Next.js 通过服务端 API 路由访问 Python 服务。 -4. 开发者做完整自检时运行：`.venv/bin/python scripts/run_quality_gate.py --profile quick`。 - -### VedAstro：聊天产品推荐配置 - -项目当前固定使用官方 Python SDK `vedastro==1.23.25`。首次安装依赖时必须安装到项目虚拟环境，并用同一个解释器启动后端，避免子进程落到系统 Python 后出现 `No module named vedastro`： - -```bash -.venv/bin/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 -在仓库根目录创建本机私有配置文件 `.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 +# 2. 网页 npm ci --prefix frontend -npm run dev --prefix frontend +npm run dev --prefix frontend # http://localhost:3000 ``` -网页侧使用： +前端配置写在 `frontend/.env.local`（至少 `JYOTISH_API_BASE` 与 `MODEL_PROVIDER_CONFIG_ENCRYPTION_KEY`），细节见 [`frontend/README.md`](frontend/README.md)。仓库根目录的 `.env.local` 给 Python 侧用（VedAstro 模式等），模板是 `.env.cn.example` / `.env.official.example`；VedAstro 三种模式与中国大陆 Gateway 部署边界见 [`docs/engine/vedastro-gateway.md`](docs/engine/vedastro-gateway.md)。 -- `Trust Center -> Web Professional Reading v1` -- `/api/vedastro_gateway/status` 查看当前后端策略 -- `/api/vedastro_gateway/run` 生成 VedAstro-compatible evidence packet -- `/api/professional_reading` 生成网页专业解盘包 +## 测试与门禁 -关键边界： +| 层 | 命令 | 说明 | +| --- | --- | --- | +| Python 快速门 | `.venv/bin/python scripts/run_quality_gate.py --profile quick` | 普通代码改动后必跑；`browser` / `release` / `accuracy` / `vedastro-live` 四个 profile 分别加前端、发布前、准确率、外部雷达检查 | +| Python 定向 | `.venv/bin/python -m pytest tests/.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` | -- 不要让浏览器直连 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。 +CI 只有 Gitea：推到 `staging` 触发 `backend-quality-gate`（构建 digest 固定镜像并部署 staging）；纯文档推送（`deploy/gated-paths.txt` 之外的路径）不触发门禁、不部署。生产发布是手动流程，复用 staging 已验收的镜像。 -### Codex 用户级 VedAstro + strict workflow 入口 +浏览器级验收（登录、双标签页、刷新/后退、校正全流程）目前依赖真人按 [`docs/testing/`](docs/testing/) 的清单执行；自动化环境没有登录态与 Chrome。 -如果用户在 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 -``` +`staging` 是测试环境分支，`main` 是生产控制分支，`main` 只能从 `staging` 快进。协作代理的完整硬约束在 [`AGENTS.md`](AGENTS.md)，Claude 会话的分工在 [`CLAUDE.md`](CLAUDE.md)。一轮工作的记录落点： -机器读取或交给后续 agent 处理时使用 JSON： +- 任务书与进度：`docs/tasks/`（[索引](docs/tasks/README.md)） +- 被挡住的事：`BLOCKED.md` +- Bug 事实与防复发：`docs/BUG_HISTORY.md` +- 行为与 Skill 变化：`CHANGELOG.md` +- 视觉与交互合同：`frontend/DESIGN.md`；文案口径：`frontend/docs/VOICE.md` +- 领域术语：`CONTEXT.md` -```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 -``` +## 引擎与技法边界 -这个入口会自动做四件事： +The Python engine routes the technique registry (`references/technique_registry.json`, currently 91 entries: 78 covered, 8 complete, 4 guarded, 1 comparison-only) 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. -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`。 +1. 调用统一入口 `/api/consultation_workflow`（MCP 对应 `strict_workflow`）。 +2. 先生成 `evidence_packet`、`guided_topics` 与 Technique Audit Table。 +3. 把 `guided_topics` 里的建议主题按优先级展示给用户，用户选题后再进入专题 `strict_workflow`。 -#### 作为 Codex 本地插件安装 +从云端仓库加载后先跑 `python3 scripts/user_invocation_acceptance_check.py`，只有 `"status": "pass"` 且外部引擎状态被标为 `available` / `partial` / `missing_dependency` 时才做高严谨解盘。 -本仓现在带了最小插件包装：`.codex-plugin/plugin.json`。它复用现有 `skills/` 与根目录 `mcp_server.py`，适合你把当前仓直接装进 Codex 本机环境。 +诚实边界：所有 benchmark 看板固定输出 `can_claim_global_first: false` 与 `production_tuning_allowed: false`；`covered` 不等于外部 oracle 闭环。引擎定位、八阶段流水线、技法覆盖表与自评见 [`docs/engine/README.md`](docs/engine/README.md)；准确率基线、外部 oracle 采集与看板命令见 [`docs/benchmark/README.md`](docs/benchmark/README.md)。 -1. 先把本仓登记到个人 marketplace： +## 文档地图 -```bash -python3 /.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 -``` +| 想知道 | 看 | +| --- | --- | +| 协作代理必须遵守什么 | [`AGENTS.md`](AGENTS.md) | +| Claude 会话怎么分工、任务书怎么写 | [`CLAUDE.md`](CLAUDE.md) | +| 生产/staging 怎么部署、恢复、验证 | [`deploy/README.md`](deploy/README.md)、[`docs/operations/`](docs/operations/) | +| 前端怎么配、Skill 怎么触发 | [`frontend/README.md`](frontend/README.md) | +| 视觉与交互合同、文案口径 | [`frontend/DESIGN.md`](frontend/DESIGN.md)、[`frontend/docs/VOICE.md`](frontend/docs/VOICE.md) | +| 某个 Bug 以前出没出过 | [`docs/BUG_HISTORY.md`](docs/BUG_HISTORY.md) | +| 某轮任务做了什么、为什么 | [`docs/tasks/`](docs/tasks/README.md)、[`BLOCKED.md`](BLOCKED.md) | +| 真人验收清单 | [`docs/testing/`](docs/testing/) | +| 引擎定位与技法覆盖 | [`docs/engine/README.md`](docs/engine/README.md) | +| VedAstro / Codex 插件 / 用户级入口 | [`docs/engine/vedastro-gateway.md`](docs/engine/vedastro-gateway.md) | +| 准确率、oracle、benchmark | [`docs/benchmark/README.md`](docs/benchmark/README.md) | +| Skill 方法与真相覆盖层 | [`SKILL.md`](SKILL.md)、`skills/*/SKILL.md`、`references/` | +| 引擎/基础设施历史错误台账 | [`docs/research/pre_work_error_ledger.md`](docs/research/pre_work_error_ledger.md) | +| 架构决策记录 | [`docs/adr/`](docs/adr/) | +| 早期实现日志（不是运行说明） | `progress.md`、`findings.md`、`task_plan.md`、`CHANGELOG_v6.2_to_v6.9.md` | -上面是 Codex 官方脚本的标准 marketplace 流。如果你要让 **当前仓本身** 被安装，关键不是用 scaffold 目录跑能力，而是让 `~/.agents/plugins/marketplace.json` 里的 `jyotish-vedic-astrology` 条目最终指向当前仓路径。 +## 隐私与安全红线 -最少要确认这一条存在： - -```json -{ - "name": "jyotish-vedic-astrology", - "source": { - "source": "local", - "path": "" - } -} -``` - -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 /.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \ - - -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 已闭环。 - -### 普通用户交付形态 - -| 形态 | 入口 | 命令 | 能力边界 | -|------|------|------|----------| -| Local dev | `http://127.0.0.1:3000` | `.venv/bin/python scripts/jyotish_api_server.py --host 127.0.0.1 --port 5200` + `npm run dev --prefix frontend` | Next.js 用户端与本地 Python API。 | -| Production | `https://jyotisha.chat` | `docker compose --env-file .env.production -f deploy/docker-compose.server.yml up -d --build` | Caddy 是唯一公网入口；Next.js `3000` 与 Python `5200` 仅在 Docker 网络内开放。 | -| Railway（可选） | 平台分配 URL | `deploy/railway-web.Dockerfile` + `deploy/railway-api.Dockerfile` | API 使用私有服务地址，不直接暴露 `5200`。 | - -生产部署与验收以 `deploy/README.md` 和 `deploy/docker-compose.server.yml` 为准；不要使用仓库根目录的 Compose 文件或直接映射 Python API 端口。 - -### 质量门分层 - -- quick：快速开发守门，适合普通代码/文案修改后先跑：`python3 scripts/run_quality_gate.py --profile quick` -- browser：Web 产品守门，覆盖 Next.js 测试、lint 与生产构建：`python3 scripts/run_quality_gate.py --profile browser` -- release：发布前守门，包含关键产品文件未跟踪检查、慢速 golden cases、真实案例复验与 Yoga 逻辑报告：`python3 scripts/run_quality_gate.py --profile release` -- accuracy：本地准确率守门，跳过浏览器点击重活，但强制运行真实案例复验、Dasha/Oracle 审计、Yoga 逻辑对照和本地准确率总报告：`python3 scripts/run_quality_gate.py --profile accuracy` -- vedastro-live：外部 VedAstro 雷达守门，只跑可选 live smoke，默认不依赖网络；只有配置 `VEDASTRO_API_ENDPOINT` 与 `VEDASTRO_ENABLE_NETWORK=1` 时才真正出网：`python3 scripts/run_quality_gate.py --profile vedastro-live` - -### 真实案例复验与准确率边界 - -一条命令查看本机当前技能覆盖与准确率基线： - -```bash -python3 scripts/local_accuracy_report.py --format markdown -``` - -如需给副手、CI 或后续自动化读取，使用 JSON： - -```bash -python3 scripts/local_accuracy_report.py --format json -``` - -当前总控报告会聚合 technique registry、BPHS invariants、公开人物真实案例复验、Yoga precision/recall/F1、Dasha/Shadbala oracle readiness、Ashtakoot API parity。它用于回答“本机现在能跑什么、哪些指标已经可测、哪些能力还缺外部 oracle 证据”；它不把本地回归测试包装成最终人生事件预测准确率。 - -公开人物样本复验命令：`python3 tests/run_real_case_revalidation.py`。 - -当前复验口径是公开人物样本的出生盘星座级一致率，并对部分带有来源矛盾、时区争议或边界度数的参考行标记为 controversial_reference。这个指标用于验证排盘计算是否稳定，不等同于人生事件预测准确率，也不应被当作个人命运判断的命中率。 - -### Dasha 参考差异审计 - -对照外部 PDF 或第三方软件时，先运行 Dasha 参考差异审计，而不是直接改生产常数： - -```bash -python3 scripts/dasha_reference_audit.py \ - --year YYYY --month MM --day DD \ - --hour HH --minute mm --second ss \ - --lat LAT --lon LON --tz TZ \ - --target-start-date 1986-05-18 \ - --target-source third_party_chart.pdf -``` - -该工具会输出当前 Vimshottari 起点、秒级出生时间敏感性、年长常数敏感性，以及对齐目标日期所需的 Moon sidereal longitude 偏移量。不要为单份 PDF 直接调生产常数；应先建立更大的 oracle 样本集，比较 ayanamsa、Moon sidereal longitude、Nakshatra 边界与 Vimshottari 起算口径。 - -也可以运行合并版外部 oracle 边界审计，同时查看 Dasha、外部黄经与 Shadbala 的校准状态： - -```bash -python3 scripts/oracle_boundary_audit.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json -``` - -该报告会明确标出 `production_tuning_recommended: false`：当前目标集已有外部验证行，但差异审计仍会拒绝单样本或全局倍率调参；VedAstro SDK 黄经样本已纳入 `longitude_cases`，用户盘最大差异约 26.23 角秒、D1/D9 落点一致，但这只能说明基础黄经接近，不能把当前目标集闭合夸大成生产级全局校准。 - -三方官方/外部 oracle sanity 总控命令： - -```bash -python3 scripts/external_oracle_sanity_closure.py --format markdown -``` - -该报告同时检查 VedAstro official precision sanity、PyJHora black-box artifacts、jyotishganit MIT reference layer。默认命令为非阻塞 sanity，总控质量门可运行；需要真实触发 VedAstro official full snapshot 细算时，加 `--live-official-full-snapshot`。当前允许声明的是“高严谨带 blocked 行”：PyJHora 黑盒证据与 jyotishganit 参考层可审计；VedAstro 黄经 sanity 通过但 official full snapshot 细算仍需显式 live probe 且可能因前台预算或官方快照合同 blocked，不能声称三方 fully closed。 - -外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数： - -```bash -python3 scripts/oracle_collection_queue.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --format markdown -``` - -如需给自动化或副手读取，可改用 JSON 输出： - -```bash -python3 scripts/oracle_collection_queue.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --format json -``` - -如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON： - -```bash -python3 scripts/prepare_oracle_capture_packets.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --output-dir references/oracle/artifacts/pending_packets -``` - -该命令会生成 `capture_manifest.json`、`OPERATOR_NEXT_STEPS.md` 和 5 个 `external_*.json`。这些导出包只是人工复核/再采集入口；当前主 oracle 文件的目标集状态以 closure dashboard 和 validator 输出为准。 - -如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 pending packets，可直接生成统一 blank kit： - -```bash -python3 scripts/generate_blank_oracle.py \ - --output-dir references/oracle/artifacts/first_packet_blank_kit -``` - -该命令会按当前推荐顺序导出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包草稿、`blank_oracle_kit_manifest.json` 和 `BLANK_ORACLE_KIT_NEXT_STEPS.md`。它只复制当前首包模板，不会猜测真值，也不会把本地引擎输出伪装成 external oracle。 - -填完某个 `external_*.json` 后，必须把 `status` 改为 `external_verified`，补齐 metadata、具体 `source_artifact` 文件路径以及所有 `target_placeholders`。再把该包合并回 oracle 文件： - -```bash -python3 scripts/oracle_collection_queue.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_dasha_lahiri.json \ - --format json -``` - -这一步只负责把人工填写的外部证据写回 `template_cases`；它不会自动认可证据，也不会允许生产调参。合并后仍必须重新生成 queue 并运行 validator。 - -该 JSON 的 scope 是 `external_oracle_collection_queue`。当前目标集可以出现 `external_verified` 与 `ready_for_calibration` 已闭合的状态，但 `production_tuning_allowed` 仍保持 `false`；这表示只能把外部黑盒目标值作为审计证据，不能直接用这些样本做 Dasha/Shadbala 生产调参。 - -Ashtakoot 外部合婚 oracle 使用同一个队列生成器，但独立样本文件是 `references/oracle/ashtakoot_oracle_cases.json`： - -```bash -python3 scripts/oracle_collection_queue.py \ - --oracle-file references/oracle/ashtakoot_oracle_cases.json \ - --format json -``` - -该队列同样保持 `ready_for_calibration: 0`，用于采集 `ashtakoot_36_point` 外部合婚目标值，而不是重写现有 `scripts/ashtakoot.py` 算法。每条样本要补齐 `target.total_score`、`target.varna`、`target.vashya`、`target.tara`、`target.yoni`、`target.graha_maitri`、`target.gana`、`target.bhakoot`、`target.nadi`、`target.kuja_status`，并保留 JHora/VedAstro/AstroSage 等外部截图或 API artifact。 - -每个队列任务还包含 `evidence_packet.capture_id` 草稿证据包。人工或副手录入外部真值时，必须至少填写 `tool_name`、`tool_version_or_url`、`capture_date`、`source_artifact`、`ayanamsa`、`node_mode`、`timezone`、`operator_note`，并保留截图、API 响应或 stdout 等外部 artifact；不得把本仓库本地计算输出当作 `source_artifact`。 - -外部截图和 stdout 片段统一存入 `references/oracle/artifacts/`，证据包里的 `source_artifact` 必须使用该目录下的 repo-relative 路径或明确标注的外部审阅位置。所有私人截图必须打码；不得提交私人 PDF 原件、不得提交完整出生报告，也不得提交浏览器 scratch 目录或含账号会话/cookie/token/桌面通知的截图。 - -第一条 JHora/PyJHora 黑盒证据采集按 `docs/user_jhora_capture_guide.md` 执行：优先使用 Steve Jobs 或合成样本，采集 Moon sidereal longitude、Vimshottari start date 与 Shadbala 七曜六分量，保存到 `references/oracle/artifacts/` 后再运行 evidence validator。 - -外部目标字段采用 `target_fields` + `target_placeholders` 双层结构：`target_fields` 固定记录该案例需要校验的目标，例如 `target.moon_sidereal_longitude_deg`、`target.vimshottari_start_date`、`target.shadbala_components`；当这些字段被真实外部来源填入并且证据包状态升为 `external_verified` 后，队列生成器会保留这些值，不会再把它们降级成 `draft`。这保证了“人工/JHora/PyJHora/VedAstro 采集 → JSON 填写 → 队列生成 → validator 复核”的路径可复验。 - -当外部证据包被填写回队列 JSON 后，用证据验证器做第二层防线： - -```bash -python3 scripts/oracle_evidence_validator.py \ - --queue-file /path/to/filled_external_oracle_collection_queue.json -``` - -该验证器输出 `external_oracle_evidence_validation`，会检查 `evidence_packet` 必填元数据、`target_placeholders` 是否已填、是否覆盖 `target_fields`、是否包含外部 artifact，以及是否错误使用本仓库本地引擎输出。只有状态为 `external_verified` 且证据完整的包才会进入可复核状态；通过 validator 不等于允许生产调参。 - -证据包通过 validator 之后，再运行边界差异审计，比较本地引擎与外部 Dasha/Shadbala 目标值： - -```bash -python3 scripts/oracle_boundary_audit.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json -``` - -审计报告中的 `template_comparisons` 会列出 external-verified template 的 Dasha 起点差异、Shadbala 七曜分量/总分差异、每个分量的 Rupa 容差、单位说明和 `global_scaling_check.recommendation: reject_global_scaling`，并继续保持 `production_tuning_recommended: false`，防止用单个样本或全局倍率调生产常数。 - -公开 benchmark 看板用于长期展示能力状态、oracle readiness 和“是否可宣称全球第一”的诚实边界： - -```bash -python3 scripts/public_benchmark_dashboard.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/public_jyotish_benchmark_dashboard.md -``` - -当前看板固定输出 `can_claim_global_first: false`，直到外部 oracle 样本、差异审计和长期公开 benchmark 都达到生产调参标准。 - -外部 oracle 总控 closure 看板会合并 Dasha、Shadbala 与 Tajika/Sahams 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令： - -```bash -python3 scripts/oracle_closure_master_dashboard.py \ - --dasha-oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --tajika-oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/jyotish_external_oracle_closure_master_dashboard.md -``` - -当前总控看板输出 `total_tasks: 12`、`external_verified_tasks: 12`、`can_claim_current_target_set_closure: true`，但 `can_claim_global_oracle_closure: false` 与 `production_tuning_allowed: false` 仍保持锁定。含义是当前目标集已闭合，不能夸大成全球 oracle、预测准确率或生产调参闭环。 - -Dasha 外部 oracle 最短闭环状态板用于把“大运外部真值”从 Shadbala 绝对值大包中拆出来，优先推进第一条可验证边界日期： - -```bash -python3 scripts/dasha_oracle_closure_status.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/dasha_external_oracle_closure_status.md -``` - -当前第一优先级是 `external_template_steve_jobs_dasha_lahiri`。该状态板只要求 `target.vimshottari_start_date` 和外部证据 metadata，不要求同时填完 Shadbala 七曜六分量；这样可以先完成 Dasha oracle 的第一条闭环，再单独推进 Shadbala 绝对值闭环。 - -第一条外部证据包的交互辅助命令： - -```bash -python3 scripts/first_oracle_packet_assistant.py \ - --front dasha \ - --format markdown \ - --output docs/benchmark/first_dasha_oracle_packet_assistant.md -``` - -同一个助手也支持： - -```bash -python3 scripts/first_oracle_packet_assistant.py --front tajika_sahams --format markdown --output docs/benchmark/first_tajika_oracle_packet_assistant.md -python3 scripts/first_oracle_packet_assistant.py --front shadbala --format markdown --output docs/benchmark/first_shadbala_oracle_packet_assistant.md -``` - -该助手不会生成或猜测 JHora/PyJHora 真值，只会列出当前 packet 还缺哪些字段、可用外部来源、apply 命令和 validator 命令。 - -如需先看三条硬闭环 front 的统一排序入口，而不是分别运行三个助手： - -```bash -python3 scripts/oracle_packet_assistant_index.py \ - --format markdown \ - --output docs/benchmark/first_oracle_packet_assistant_index.md -``` - -该索引会固定列出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包 case、缺失字段数、operator card 与推荐执行顺序，方便直接判断当前最短闭环路径。 - -Shadbala 外部绝对值闭环使用独立状态板，专门追踪七曜的六分量与总 Rupa： - -```bash -python3 scripts/shadbala_oracle_closure_status.py \ - --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/shadbala_external_absolute_value_closure_status.md -``` - -当前第一优先级是 `external_template_synthetic_north_china_shadbala_raman`。除了同一 oracle 行里的 `target.moon_sidereal_longitude_deg`，还必须填写 Sun/Moon/Mars/Mercury/Jupiter/Venus/Saturn 的 `sthana`、`dig`、`kala`、`chesta`、`naisargika`、`drik`、`total_rupa`；验证器会检查分量和总分，不允许用一个全局倍率把本地输出硬缩放成外部值。 - -Tajika/Sahams 年运系统使用独立的外部 oracle 队列，专门追踪 Varshaphala、太阳回归、Muntha、Year Lord、Mudda Dasha、Sahams 与 Tajika Yogas 的外部验证状态： - -```bash -python3 scripts/tajika_annual_oracle_queue.py \ - --oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --format markdown -``` - -公开年运看板可这样生成： - -```bash -python3 scripts/tajika_annual_benchmark_dashboard.py \ - --oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/tajika_sahams_annual_benchmark_dashboard.md -``` - -当前 Tajika/Sahams 看板固定输出 `can_claim_tajika_sahams_closure: false`：本地 skill 已有年运计算与解释骨架，但太阳回归精确时刻、Varsha Lagna、Muntha、Mudda Dasha、Punya/Rajya/Vivah Saham 和 Tajika Yogas 仍需 JHora/PyJHora/书例级外部证据后，才能宣称年运闭环。 - -年运第一条最短闭环状态板： - -```bash -python3 scripts/tajika_annual_closure_status.py \ - --oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --format markdown \ - --output docs/benchmark/tajika_sahams_annual_closure_status.md -``` - -如需导出可填写的年运证据包： - -```bash -python3 scripts/tajika_annual_oracle_queue.py \ - --oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --write-packet-dir references/oracle/artifacts/pending_packets \ - --format json -``` - -填完 `external_template_steve_jobs_varshaphala_1984_lahiri.json` 后，可合并回年运 oracle： - -```bash -python3 scripts/tajika_annual_oracle_queue.py \ - --oracle-file references/oracle/tajika_annual_oracle_cases.json \ - --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_varshaphala_1984_lahiri.json \ - --format json -``` - -`full-reading` 也会输出 `ai_prompt_pack`：这是给网页/app、skill 或后端 AI 代理使用的结构化 Prompt/RAG 上下文包。它不会硬编码断语，而是携带 D1/D9/Dasha/Shadbala/Ashtakavarga 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。 - -### Prerequisites - -- Python 3.11+ -- Swiss Ephemeris (`pyswisseph` or `ephem`) -- Optional: `pypdf`, `pdfplumber` (for PDF chart input) - -### Install - -```bash -# Clone the repository -git clone https://github.com/732642856/yinduzhanxing.git -cd yinduzhanxing - -# Install Python dependencies -pip install -r requirements.txt - -# Verify installation -python3 scripts/audit_capabilities.py --mode validate -# Expected: valid=true, problem_count=0 -``` - -### Minimal Full Reading (5 minutes) - -```bash -python3 scripts/jyotish_engine.py full-reading \ - --year 1990 --month 6 --day 15 \ - --hour 10 --minute 30 \ - --lat 28.6139 --lon 77.2090 --tz 5.5 \ - --age 36 \ - --transit-date 2026-06-04 -``` - -**Output:** ~45 computed modules, zero errors, complete structured reading with technique audit table. - -### Sample Output (abbreviated) - -``` -═══ FULL READING ═══ -Birth Data: 1990-06-15 10:30 (+5.5) 28.61°N 77.21°E -Lagna: Gemini Sun: Taurus Moon: Leo - -── Static Analysis ── -[✓] D1 Rashi Chart -[✓] D9 Navamsa -[✓] D10 Dasamsa -[✓] Vimshottari Dasha (120 years) -[✓] Ashtakavarga (8-point system) -[✓] Shadbala (covered — absolute Rupa totals, component invariants verified) -[✓] Yogas & Doshas -[✓] Argala (planetary interventions) -[✓] Nakshatra Advanced (Chandra Bala / Tara Bala) - -── Dynamic Timing ── -[✓] Vimshottari Dasha breakdown -[✓] Dasha Sandhi detection -[✓] Transit (true positions) -[✓] Double Transit analysis -[✓] Narayana Dasha -[✓] Solar Return / Varshaphala -[✓] Nakshatra Dasha (Ashtottari) - -── Technique Audit Table ── -✓ Vimshottari Dasha covered high confidence -✓ Ashtakavarga covered high confidence -✓ Shadbala covered absolute Rupa output; total_virupas component invariant passed -✓ Chara Dasha covered KN Rao benchmark 95.83% overall match -✓ KP Sub-Lord covered SubLord/SubSubLord + ABCD significator workflow -``` - ---- - -## Core Workflow - -### Three Input Paths - -| Path | Input | Behavior | -|------|-------|----------| -| **A: Precise birth data** | Date + time + coordinates | Full `full-reading` engine | -| **B: PDF / text chart** | Scanned chart or description | Extract → Quality Gate → route to A | -| **C: Uncertain birth time** | "Don't know my birth time" | Interactive birth time rectification | - -### Eight-Stage Pipeline - -``` -Stage -1: Question-type routing (career / relationship / wealth / timing) -Stage 0: Input routing (A / B / C) -Stage 1: (B only) PDF extraction + Quality Gate -Stage 2: Intent recognition → target house routing -Stage 3: Static analysis (10 steps) -Stage 4: Dynamic timing (7 steps) -Stage 5: Timing output (5-layer verification) -Stage 6: Remedial measures (optional) -Stage 7: Modern language packaging -Stage 8: Technique Audit Table (mandatory) -``` - -**Strict Workflow Router** (`references/strict-workflow-router.md`): -- Career questions → `career-timing-strict` -- Relationship questions → `relationship-timing-strict` -- Wealth questions → `wealth-timing-strict` -- Event timing → `event-timing-strict` -- Historical verification → `event-verification-strict` - -The AI does NOT require the user to name techniques (e.g., "Chara Dasha"). It auto-selects based on question type. - ---- - -## Technique Coverage - -Current registry count: **89 capability entries** (79 covered, 10 complete, 0 partial, 0 missing). - -These entries are a **backend evidence pool**, not a flat list of 89 user-facing -prediction sources. Ordinary users see topic-level conclusions and evidence -summaries. The question-domain router selects a small primary chain, then uses -supporting indicators only to raise/lower confidence. Audit-only and alias -entries cannot affect astrological conclusions. - -The table below lists representative high-value entries. Treat -`references/technique_registry.json` as the source of truth for the full -machine-readable registry. - -| Technique | Status | Notes | -|-----------|--------|-------| -| D1 Rashi Chart | ✅ covered | Swiss Eph base | -| D9 Navamsa | ✅ covered | | -| D10 Dasamsa | ✅ covered | | -| Vimshottari Dasha | ✅ covered | | -| Dasha Sandhi | ✅ covered | | -| Ashtakavarga | ✅ covered | BPHS/PVR calibrated | -| Argala | ✅ covered | | -| Vargottama | ✅ covered | | -| Pushkara | ✅ covered | | -| A10 / Karma Pada | ✅ covered | | -| UL / Upapada | ✅ covered | | -| Transit (true positions) | ✅ covered | | -| Double Transit | ✅ covered | | -| Nakshatra Advanced | ✅ covered | Tara Bala / Chandra Bala / Sub-Lord workflow | -| Narayana Dasha | ✅ covered | CLI and full-reading integration | -| Solar Return / Varshaphala | ✅ covered | Tajika annual-chart workflow | -| **Shadbala** | ✅ covered | **absolute Rupa component-sum output; internal invariants pass; external absolute-value oracle expansion remains open** | -| **Chara Dasha** | ✅ covered | **KN Rao benchmark: sign 100%, duration 91.67%, overall 95.83%** | -| KP Sub-Lord | ✅ covered | SubLord/SubSubLord + ABCD significator workflow | -| Bhava Chalit | ✅ covered | Sripati/Porphyry/Equal/Whole Sign/Placidus/Koch | -| Sudarshana Chakra | ✅ covered | Asc/Moon/Sun reference charts + convergence scoring | -| Tajika Yogas | ✅ complete | Annual-chart yoga set | -| Raj Yoga | ✅ covered | Rule-based detection | -| Dhana Yoga | ✅ covered | Rule-based detection | -| Pancha Mahapurusha | ✅ covered | Complete detection | -| Neecha Bhanga | ✅ complete | Debilitation cancellation workflow | -| Sade Sati | ✅ covered | Saturn pressure timing | -| Tithi Lord | ✅ complete | Lunar-day ruler workflow | -| Pancha Pakshi | ✅ complete | Five-bird system | -| Rashi Tulya Navamsa | ✅ covered | D1/D9 mapping | -| Trimshamsa D30 | ✅ covered | D30 varga support | -| Marriage Counting | ✅ complete | Bhrigu Pada marriage-counting method | -| Prashna Integration | ✅ complete | Prashna workflow integrated | -| Bhrigu Pada Dasha | ✅ complete | Pada progression workflow | -| Muhurta | ✅ covered | Panchanga / auspicious timing workflow | - -**Legend:** -- ✅ `covered` — implemented and benchmarked against authoritative sources -- ✅ `complete` — implemented with integrated workflow and validation hooks -- ✅ `covered` — implemented and available in the engine, sometimes with explicit confidence caps -- 🔶 `partial` — reserved for implemented-but-insufficiently-integrated techniques; current registry count is 0 -- ❌ `missing` — not currently present in the registry; current registry count is 0 - ---- - -## Why This Exists (Competitive Context) - -### The Landscape - -| Project | Type | Strength | Weakness | -|---------|------|----------|-----------| -| **PyJHora** | Calculation library | Strongest traditional algorithm coverage (50+ Dashas, 284 Yogas) | No interpretive pipeline; user must interpret results themselves | -| **VedAstro** | API / Web platform | 200+ endpoints, Docker, MCP Server, MIT license | Interpretive audit & confidence labeling weaker | -| **Maitreya** | Desktop software | Mature cross-platform GUI | Jyotish depth not as deep as specialized projects | -| **jyotisha** | Panchanga / calendar | Excellent Panchanga accuracy | Not a full reading system | -| **This project** | AI-native analysis system | Full pipeline + audit + degradation | Pure calculation accuracy still being benchmarked | - -### Our Position - -> **PyJHora is the calculator. VedAstro is the API platform. Maitreya is the desktop software. This project is the "AI-native Jyotish research analyst."** - -We are NOT trying to out-calculate PyJHora (it has years of lead). Our value is in: -1. Organizing calculations into a **reproducible interpretive workflow** -2. **Auditing** every technique used and declaring confidence -3. **Degrading gracefully** — confidence caps and limitations are labeled, not silently over-promising -4. Being **AI-native** — designed for integration with LLM-based analysis - ---- - -## Honest Assessment - -We believe in transparency about limitations. This is NOT a "99% accurate" system, and anyone claiming that about Jyotish is over-selling. - -### Current Accuracy Estimates (self-evaluated) - -| Dimension | Score | Notes | -|-----------|-------|-------| -| Astronomical foundation (Swiss Eph) | 8.5/10 | Depends on ayanamsa, node mode, house system | -| Traditional algorithm accuracy | 8.4/10 | Chara Dasha benchmark passed; Shadbala absolute Rupa invariants now pass; Dasha oracle expansion remains open | -| Technique coverage breadth | 9.1/10 | 65 registered techniques; broad and increasingly benchmarked | -| Reading detail depth | 9.6/10 | Possibly best among open-source projects | -| Prediction workflow rigor | 8.8/10 | Strict routing + audit table | -| Verification system | 8.2/10 | Has registry, benchmark, degradation; some verification still internal | -| Engineering maturity | 7.6/10 | Docker, PyPI config and CI exist; release artifacts still need cleanup | -| Open-source influence | 5.5/10 | Currently more of a "private high-density toolkit" | - -### What Confidence Caps Mean (Important) - -Even when a technique is labeled `covered`, it may carry a confidence or validation boundary: -- It CAN produce output -- Some components may still need broader external oracle expansion against PyJHora / JHora / canonical texts -- It should be interpreted together with cross-technique evidence -- It must NOT be the sole basis for high-confidence predictions when its limitation says so - -Examples: -- `Shadbala` (covered): absolute Rupa totals are reported directly from six component sums; internal component invariants pass and `total_rupas = total_virupas / 60`, while external absolute-value oracle expansion remains open. -- `Chara Dasha` (covered): KN Rao benchmark passes at 95.83% overall; remaining differences are documented around Aquarius/Scorpio co-lord strength arbitration. - ---- - -## Project Status - -**Current version:** `v6.9.14` - -### Recently Completed - -- `v6.9.14` — Sudarshana Chakra complete + 475 pytest cases + 65-technique registry audit PASS. -- `v6.9.13` — Bhava Chalit complete + transit trigger output normalization + Nakshatra test calibration. -- `v6.9.12` — Shadbala precision upgrade + Ashtakoot 36-point compatibility + expanded subcommands. -- `v6.9.6` — Field mapping fixes (degree→degree_in_sign + toFixed null safety); PyPI publishing config. -- `v6.9.5` — birth_info null safety + API field mapping fixes. -- `v6.9.4` — AI interpretation integration; current browser build disables direct model API keys and routes AI through server-side `/api/chat` or a backend proxy. -- `v6.9.3` — 35 Dasha systems, 405+ Yoga rules, KP complete system, Prashna, 16-factor synastry, Remedies, Sahams 36, Sudarshana, PMC, Tajika. -- `v6.1.12` — Chara Dasha KN Rao Method rewrite, PyJHora benchmark 95.83% PASS. -- `v6.1.10` — Darakaraka deep reader wired into `full-reading.modules.jaimini.darakaraka`; thematic reports now consume real DK and Rashi Tulya Navamsa evidence. -- `v6.1.9` — Public/sanitized benchmark suite, competitive research, coverage roadmap and PDF validation methodology added. -- `v6.1.8` — Yoga validation reached F1=95.22% (FP=36, FN=63); thematic reports consume real `full-reading.modules` evidence. -- `v6.1.6` — Five-system Dasha convergence wired into full-reading (Vimshottari + Chara + Yogini + Ashtottari + Kalachakra). -- `v6.0.11` — Shadbala 1200/1200 internal invariants pass; later upgraded to absolute Rupa component-sum output. - -### Actively Working On (P0) - -1. **Release hygiene** — run the release profile, keep product-critical files tracked, rebuild wheel/sdist, and align GitHub tags with source version -2. **README / package metadata sync** — keep public docs, registry counts and distribution artifacts consistent -3. **Dasha oracle expansion** — add external cases for Vimshottari start/end boundaries and configurable year-length/ayanamsa comparisons -4. **Benchmark expansion** — add more oracle cases for Shadbala, KP and annual-chart modules -5. **Frontend verification** — keep the Next.js API contracts aligned with the Python engine output - -### Next (P1) - -- Production image publishing and smoke-test docs -- English documentation examples and API tutorials -- Multi-Ayanamsa UX polish and benchmark examples（计算层已可验证切换；网页设置展示和更多外部样本仍需补齐） - ---- - -## Development - -### Running the Test Suite - -```bash -# Syntax check all scripts -python3 -m py_compile scripts/*.py - -# Capability audit (must pass with 0 problems, 0 warnings) -python3 scripts/audit_capabilities.py --mode validate - -# Next.js unit tests, lint, and production build -npm test --prefix frontend -npm run lint --prefix frontend -npm run build --prefix frontend - -# Full-reading regression test (use FICTIONAL data only) -python3 scripts/jyotish_engine.py full-reading \ - --year 1990 --month 6 --day 15 \ - --hour 10 --minute 30 \ - --lat 39.9042 --lon 116.4074 --tz 8 \ - --age 36 \ - --transit-date 2026-06-04 -``` - -### Important Rules - -1. **NEVER** put real user birth data into skill files, tests, CHANGELOG, or public repos -2. Use only: (a) public AA-rated celebrity data, (b) explicitly fictional smoke tests, (c) current-session data (never persisted) -3. Always run `git status --short --branch` before starting work -4. Always run `py_compile` + `audit_capabilities.py` + full-reading regression after modifications -5. Do NOT remove a confidence or validation boundary without external benchmark evidence -6. Do NOT refactor arbitrarily; make minimal verifiable changes - -### Directory Structure - -``` -jyotish-vedic-astrology/ -├── SKILL.md # Core entry point (Chinese) -├── README.md # This file (English) -├── CHANGELOG.md # Version history -├── requirements.txt # Python dependencies -├── references/ -│ ├── technique_registry.json # Machine-readable technique registry -│ ├── strict-workflow-router.md # Question-type routing rules -│ ├── quick-reference-guide.md # Quick reference -│ └── ... # Knowledge reference docs -├── scripts/ -│ ├── jyotish_engine.py # Main engine entry point -│ ├── audit_capabilities.py # Capability audit tool -│ ├── shadbala.py # Shadbala implementation -│ ├── dasha_calculator.py # Dasha calculations -│ └── ... # 90+ technique and orchestration scripts -└── tests/ # Test cases -``` - ---- - -## Contributing - -We welcome contributions, especially: - -1. **Benchmark data** — PyJHora / JHora output comparisons for specific techniques -2. **Traditional text verification** — checking technique implementations against BPHS, PVN Rao, BV Raman -3. **Documentation** — English docs, tutorials, example outputs -4. **Engineering** — Docker, CI, MCP Server, API layer -5. **Test cases** — fictional birth data with expected outputs - -### How to Contribute - -1. Fork the repository -2. Create a feature branch (`git checkout -b fix/chara-dasha-benchmark`) -3. Make your changes (follow the development rules above) -4. Run the full test suite -5. Commit with a clear message -6. Push and create a Pull Request - -### Philosophy - -We prioritize **truth over coverage**. It is better to have 10 well-benchmarked techniques than 50 poorly-implemented ones. If you contribute a technique, please include: -- The source text / authority it is based on -- Benchmark comparison data (if available) -- Honest assessment of limitations - ---- +1. 真实用户出生资料、邮箱、姓名、会话内容、JWT、Cookie、密钥，**不得**进入 skill 文件、测试、CHANGELOG、Bug 历史、任务书或任何提交。 +2. 测试与示例只用公开名人数据或明确虚构的数据。 +3. 端口 `5200`、模型 key、数据库口令、SSH 私钥不得暴露；生产密钥只存在服务器 `0600` 文件中。 +4. 不得放宽任何置信度或验证边界，除非有外部 benchmark 证据。 +5. 医疗、法律、投资、安全关键结论与确定性死亡/诊断/妊娠预测禁止输出。 ## License -MIT License — see [LICENSE](LICENSE) for details. +MIT，见 [LICENSE](LICENSE)。 ---- +致谢：Swiss Ephemeris、PyJHora（`naturalstupid/PyJHora`）、VedAstro（`VedAstro/VedAstro`）、BPHS、PVN Rao / KN Rao 的教学传承。 -## Acknowledgments - -- **Swiss Ephemeris** — astronomical calculation foundation -- **PyJHora** (`naturalstupid/PyJHora`) — benchmark reference for traditional algorithms -- **VedAstro** (`VedAstro/VedAstro`) — engineering and productization reference -- **BPHS (Brihat Parashara Hora Shastra)** — canonical text -- **PVN Rao / KN Rao** — traditional Jyotish teaching lineage - ---- - -## Contact & Support - -- **Issues:** [GitHub Issues](https://github.com/732642856/yinduzhanxing/issues) -- **Discussions:** [GitHub Discussions](https://github.com/732642856/yinduzhanxing/discussions) - ---- - -> **Final note:** This system is a research tool. It should NOT be used for making life-altering decisions without consulting qualified human astrologers. The techniques implemented here are complex and context-dependent; software output always benefits from human judgment. +> 本系统是研究与咨询辅助工具，不应在没有合格人类占星师参与的情况下用于改变人生的决定。 diff --git a/REPO_LAYOUT.md b/REPO_LAYOUT.md deleted file mode 100644 index 22fe0078..00000000 --- a/REPO_LAYOUT.md +++ /dev/null @@ -1,64 +0,0 @@ -# Repository Layout - -This repository mixes product code, astrology research, oracle artifacts, and local experimentation. To keep the worktree usable, follow these layout rules. - -## Core Areas - -- `/frontend/` - - current Next.js production web application -- `/deploy/` - - production container topology and operational source of truth; start with `deploy/README.md` -- `/mcp_server.py` - - adjudicator-facing MCP entrypoint -- `/scripts/` - - reusable project code and maintained tooling -- `/tests/` - - maintained regression and contract tests -- `/references/` - - durable knowledge assets, oracle cases, and frozen methodology - -## Research - -- `/docs/research/` - - active research and current audits -- `/docs/research/archive/` - - historical round notes and local draft research - -## Historical Working Logs - -- `/task_plan.md` -- `/findings.md` -- `/progress.md` - -These root files preserve earlier implementation history and may mention retired -paths or commands. They are not runtime or deployment instructions. Use -`README.md` for current local development and `deploy/README.md` for production. - -## Local Scratch - -- `/scratch/local/scripts/` - - one-off debugging scripts, temporary probes, ad hoc runners -- `/scratch/local/outputs/` - - local generated JSON, text dumps, temporary reports - -These paths are local-only and ignored by git. - -## Local Runtime Noise - -The following should stay out of normal versioned work: - -- `/.agents/` -- `/venv_vedastro/` -- `/scratch/local/` - -## Practical Rule - -Before adding a new file, decide which lifecycle it belongs to: - -1. reusable project asset -2. active research note -3. archived research -4. local scratch script -5. local generated output - -If it is category 4 or 5, do not leave it in the repo root. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md deleted file mode 100644 index 82cfbf5b..00000000 --- a/docs/agents/issue-tracker.md +++ /dev/null @@ -1,45 +0,0 @@ -# Issue tracker: GitHub - -Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. - -## Conventions - -- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. -- **Read an issue**: `gh issue view --comments`, filtering comments by `jq` and also fetching labels. -- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. -- **Comment on an issue**: `gh issue comment --body "..."` -- **Apply / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` -- **Close**: `gh issue close --comment "..."` - -Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone. - -## Pull requests as a triage surface - -**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ - -When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: - -- **Read a PR**: `gh pr view --comments` and `gh pr diff ` for the diff. -- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`). -- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. - -GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`. - -## When a skill says "publish to the issue tracker" - -Create a GitHub issue. - -## When a skill says "fetch the relevant ticket" - -Run `gh issue view --comments`. - -## Wayfinding operations - -Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. - -- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`. -- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. -- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. -- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. -- **Claim**: `gh issue edit --add-assignee @me` — the session's first write. -- **Resolve**: `gh issue comment --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md deleted file mode 100644 index b716855d..00000000 --- a/docs/agents/triage-labels.md +++ /dev/null @@ -1,15 +0,0 @@ -# Triage Labels - -The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. - -| Label in mattpocock/skills | Label in our tracker | Meaning | -| -------------------------- | -------------------- | ---------------------------------------- | -| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | -| `needs-info` | `needs-info` | Waiting on reporter for more information | -| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | -| `ready-for-human` | `ready-for-human` | Requires human implementation | -| `wontfix` | `wontfix` | Will not be actioned | - -When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. - -Edit the right-hand column to match whatever vocabulary you actually use. diff --git a/docs/benchmark/README.md b/docs/benchmark/README.md new file mode 100644 index 00000000..d586cb61 --- /dev/null +++ b/docs/benchmark/README.md @@ -0,0 +1,260 @@ +# 准确率基线、外部 Oracle 闭环与 Benchmark 看板 + +> 本文从根 README 拆出（2026-09-03），内容原样保留。这里是所有"本机现在能跑什么、哪些指标可测、哪些能力还缺外部 oracle 证据"的命令入口；看板产物就在本目录。所有看板固定输出 `can_claim_global_first: false` 与 `production_tuning_allowed: false`，直到外部样本达到生产调参标准。 + +### 真实案例复验与准确率边界 + +一条命令查看本机当前技能覆盖与准确率基线： + +```bash +python3 scripts/local_accuracy_report.py --format markdown +``` + +如需给副手、CI 或后续自动化读取，使用 JSON： + +```bash +python3 scripts/local_accuracy_report.py --format json +``` + +当前总控报告会聚合 technique registry、BPHS invariants、公开人物真实案例复验、Yoga precision/recall/F1、Dasha/Shadbala oracle readiness、Ashtakoot API parity。它用于回答“本机现在能跑什么、哪些指标已经可测、哪些能力还缺外部 oracle 证据”；它不把本地回归测试包装成最终人生事件预测准确率。 + +公开人物样本复验命令：`python3 tests/run_real_case_revalidation.py`。 + +当前复验口径是公开人物样本的出生盘星座级一致率，并对部分带有来源矛盾、时区争议或边界度数的参考行标记为 controversial_reference。这个指标用于验证排盘计算是否稳定，不等同于人生事件预测准确率，也不应被当作个人命运判断的命中率。 + +### Dasha 参考差异审计 + +对照外部 PDF 或第三方软件时，先运行 Dasha 参考差异审计，而不是直接改生产常数： + +```bash +python3 scripts/dasha_reference_audit.py \ + --year YYYY --month MM --day DD \ + --hour HH --minute mm --second ss \ + --lat LAT --lon LON --tz TZ \ + --target-start-date 1986-05-18 \ + --target-source third_party_chart.pdf +``` + +该工具会输出当前 Vimshottari 起点、秒级出生时间敏感性、年长常数敏感性，以及对齐目标日期所需的 Moon sidereal longitude 偏移量。不要为单份 PDF 直接调生产常数；应先建立更大的 oracle 样本集，比较 ayanamsa、Moon sidereal longitude、Nakshatra 边界与 Vimshottari 起算口径。 + +也可以运行合并版外部 oracle 边界审计，同时查看 Dasha、外部黄经与 Shadbala 的校准状态： + +```bash +python3 scripts/oracle_boundary_audit.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json +``` + +该报告会明确标出 `production_tuning_recommended: false`：当前目标集已有外部验证行，但差异审计仍会拒绝单样本或全局倍率调参；VedAstro SDK 黄经样本已纳入 `longitude_cases`，用户盘最大差异约 26.23 角秒、D1/D9 落点一致，但这只能说明基础黄经接近，不能把当前目标集闭合夸大成生产级全局校准。 + +三方官方/外部 oracle sanity 总控命令： + +```bash +python3 scripts/external_oracle_sanity_closure.py --format markdown +``` + +该报告同时检查 VedAstro official precision sanity、PyJHora black-box artifacts、jyotishganit MIT reference layer。默认命令为非阻塞 sanity，总控质量门可运行；需要真实触发 VedAstro official full snapshot 细算时，加 `--live-official-full-snapshot`。当前允许声明的是“高严谨带 blocked 行”：PyJHora 黑盒证据与 jyotishganit 参考层可审计；VedAstro 黄经 sanity 通过但 official full snapshot 细算仍需显式 live probe 且可能因前台预算或官方快照合同 blocked，不能声称三方 fully closed。 + +外部真值采集队列用于把缺失目标值拆成可执行任务，而不是直接调生产参数： + +```bash +python3 scripts/oracle_collection_queue.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --format markdown +``` + +如需给自动化或副手读取，可改用 JSON 输出： + +```bash +python3 scripts/oracle_collection_queue.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --format json +``` + +如需让真人或 Antigravity AI 副手直接填写证据包，可一次性导出每个 case 的 draft JSON： + +```bash +python3 scripts/prepare_oracle_capture_packets.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --output-dir references/oracle/artifacts/pending_packets +``` + +该命令会生成 `capture_manifest.json`、`OPERATOR_NEXT_STEPS.md` 和 5 个 `external_*.json`。这些导出包只是人工复核/再采集入口；当前主 oracle 文件的目标集状态以 closure dashboard 和 validator 输出为准。 + +如果只想优先准备当前最短闭环链路的三条首包，而不是一次性导出整批 pending packets，可直接生成统一 blank kit： + +```bash +python3 scripts/generate_blank_oracle.py \ + --output-dir references/oracle/artifacts/first_packet_blank_kit +``` + +该命令会按当前推荐顺序导出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包草稿、`blank_oracle_kit_manifest.json` 和 `BLANK_ORACLE_KIT_NEXT_STEPS.md`。它只复制当前首包模板，不会猜测真值，也不会把本地引擎输出伪装成 external oracle。 + +填完某个 `external_*.json` 后，必须把 `status` 改为 `external_verified`，补齐 metadata、具体 `source_artifact` 文件路径以及所有 `target_placeholders`。再把该包合并回 oracle 文件： + +```bash +python3 scripts/oracle_collection_queue.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_dasha_lahiri.json \ + --format json +``` + +这一步只负责把人工填写的外部证据写回 `template_cases`；它不会自动认可证据，也不会允许生产调参。合并后仍必须重新生成 queue 并运行 validator。 + +该 JSON 的 scope 是 `external_oracle_collection_queue`。当前目标集可以出现 `external_verified` 与 `ready_for_calibration` 已闭合的状态，但 `production_tuning_allowed` 仍保持 `false`；这表示只能把外部黑盒目标值作为审计证据，不能直接用这些样本做 Dasha/Shadbala 生产调参。 + +Ashtakoot 外部合婚 oracle 使用同一个队列生成器，但独立样本文件是 `references/oracle/ashtakoot_oracle_cases.json`： + +```bash +python3 scripts/oracle_collection_queue.py \ + --oracle-file references/oracle/ashtakoot_oracle_cases.json \ + --format json +``` + +该队列同样保持 `ready_for_calibration: 0`，用于采集 `ashtakoot_36_point` 外部合婚目标值，而不是重写现有 `scripts/ashtakoot.py` 算法。每条样本要补齐 `target.total_score`、`target.varna`、`target.vashya`、`target.tara`、`target.yoni`、`target.graha_maitri`、`target.gana`、`target.bhakoot`、`target.nadi`、`target.kuja_status`，并保留 JHora/VedAstro/AstroSage 等外部截图或 API artifact。 + +每个队列任务还包含 `evidence_packet.capture_id` 草稿证据包。人工或副手录入外部真值时，必须至少填写 `tool_name`、`tool_version_or_url`、`capture_date`、`source_artifact`、`ayanamsa`、`node_mode`、`timezone`、`operator_note`，并保留截图、API 响应或 stdout 等外部 artifact；不得把本仓库本地计算输出当作 `source_artifact`。 + +外部截图和 stdout 片段统一存入 `references/oracle/artifacts/`，证据包里的 `source_artifact` 必须使用该目录下的 repo-relative 路径或明确标注的外部审阅位置。所有私人截图必须打码；不得提交私人 PDF 原件、不得提交完整出生报告，也不得提交浏览器 scratch 目录或含账号会话/cookie/token/桌面通知的截图。 + +第一条 JHora/PyJHora 黑盒证据采集按 `docs/user_jhora_capture_guide.md` 执行：优先使用 Steve Jobs 或合成样本，采集 Moon sidereal longitude、Vimshottari start date 与 Shadbala 七曜六分量，保存到 `references/oracle/artifacts/` 后再运行 evidence validator。 + +外部目标字段采用 `target_fields` + `target_placeholders` 双层结构：`target_fields` 固定记录该案例需要校验的目标，例如 `target.moon_sidereal_longitude_deg`、`target.vimshottari_start_date`、`target.shadbala_components`；当这些字段被真实外部来源填入并且证据包状态升为 `external_verified` 后，队列生成器会保留这些值，不会再把它们降级成 `draft`。这保证了“人工/JHora/PyJHora/VedAstro 采集 → JSON 填写 → 队列生成 → validator 复核”的路径可复验。 + +当外部证据包被填写回队列 JSON 后，用证据验证器做第二层防线： + +```bash +python3 scripts/oracle_evidence_validator.py \ + --queue-file /path/to/filled_external_oracle_collection_queue.json +``` + +该验证器输出 `external_oracle_evidence_validation`，会检查 `evidence_packet` 必填元数据、`target_placeholders` 是否已填、是否覆盖 `target_fields`、是否包含外部 artifact，以及是否错误使用本仓库本地引擎输出。只有状态为 `external_verified` 且证据完整的包才会进入可复核状态；通过 validator 不等于允许生产调参。 + +证据包通过 validator 之后，再运行边界差异审计，比较本地引擎与外部 Dasha/Shadbala 目标值： + +```bash +python3 scripts/oracle_boundary_audit.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json +``` + +审计报告中的 `template_comparisons` 会列出 external-verified template 的 Dasha 起点差异、Shadbala 七曜分量/总分差异、每个分量的 Rupa 容差、单位说明和 `global_scaling_check.recommendation: reject_global_scaling`，并继续保持 `production_tuning_recommended: false`，防止用单个样本或全局倍率调生产常数。 + +公开 benchmark 看板用于长期展示能力状态、oracle readiness 和“是否可宣称全球第一”的诚实边界： + +```bash +python3 scripts/public_benchmark_dashboard.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/public_jyotish_benchmark_dashboard.md +``` + +当前看板固定输出 `can_claim_global_first: false`，直到外部 oracle 样本、差异审计和长期公开 benchmark 都达到生产调参标准。 + +外部 oracle 总控 closure 看板会合并 Dasha、Shadbala 与 Tajika/Sahams 三条硬闭环战线，给出总任务数、已验证数、第一优先级和下一条执行命令： + +```bash +python3 scripts/oracle_closure_master_dashboard.py \ + --dasha-oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --tajika-oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/jyotish_external_oracle_closure_master_dashboard.md +``` + +当前总控看板输出 `total_tasks: 12`、`external_verified_tasks: 12`、`can_claim_current_target_set_closure: true`，但 `can_claim_global_oracle_closure: false` 与 `production_tuning_allowed: false` 仍保持锁定。含义是当前目标集已闭合，不能夸大成全球 oracle、预测准确率或生产调参闭环。 + +Dasha 外部 oracle 最短闭环状态板用于把“大运外部真值”从 Shadbala 绝对值大包中拆出来，优先推进第一条可验证边界日期： + +```bash +python3 scripts/dasha_oracle_closure_status.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/dasha_external_oracle_closure_status.md +``` + +当前第一优先级是 `external_template_steve_jobs_dasha_lahiri`。该状态板只要求 `target.vimshottari_start_date` 和外部证据 metadata，不要求同时填完 Shadbala 七曜六分量；这样可以先完成 Dasha oracle 的第一条闭环，再单独推进 Shadbala 绝对值闭环。 + +第一条外部证据包的交互辅助命令： + +```bash +python3 scripts/first_oracle_packet_assistant.py \ + --front dasha \ + --format markdown \ + --output docs/benchmark/first_dasha_oracle_packet_assistant.md +``` + +同一个助手也支持： + +```bash +python3 scripts/first_oracle_packet_assistant.py --front tajika_sahams --format markdown --output docs/benchmark/first_tajika_oracle_packet_assistant.md +python3 scripts/first_oracle_packet_assistant.py --front shadbala --format markdown --output docs/benchmark/first_shadbala_oracle_packet_assistant.md +``` + +该助手不会生成或猜测 JHora/PyJHora 真值，只会列出当前 packet 还缺哪些字段、可用外部来源、apply 命令和 validator 命令。 + +如需先看三条硬闭环 front 的统一排序入口，而不是分别运行三个助手： + +```bash +python3 scripts/oracle_packet_assistant_index.py \ + --format markdown \ + --output docs/benchmark/first_oracle_packet_assistant_index.md +``` + +该索引会固定列出 `dasha`、`tajika_sahams`、`shadbala` 三条 front 的首包 case、缺失字段数、operator card 与推荐执行顺序，方便直接判断当前最短闭环路径。 + +Shadbala 外部绝对值闭环使用独立状态板，专门追踪七曜的六分量与总 Rupa： + +```bash +python3 scripts/shadbala_oracle_closure_status.py \ + --oracle-file references/oracle/dasha_shadbala_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/shadbala_external_absolute_value_closure_status.md +``` + +当前第一优先级是 `external_template_synthetic_north_china_shadbala_raman`。除了同一 oracle 行里的 `target.moon_sidereal_longitude_deg`，还必须填写 Sun/Moon/Mars/Mercury/Jupiter/Venus/Saturn 的 `sthana`、`dig`、`kala`、`chesta`、`naisargika`、`drik`、`total_rupa`；验证器会检查分量和总分，不允许用一个全局倍率把本地输出硬缩放成外部值。 + +Tajika/Sahams 年运系统使用独立的外部 oracle 队列，专门追踪 Varshaphala、太阳回归、Muntha、Year Lord、Mudda Dasha、Sahams 与 Tajika Yogas 的外部验证状态： + +```bash +python3 scripts/tajika_annual_oracle_queue.py \ + --oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --format markdown +``` + +公开年运看板可这样生成： + +```bash +python3 scripts/tajika_annual_benchmark_dashboard.py \ + --oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/tajika_sahams_annual_benchmark_dashboard.md +``` + +当前 Tajika/Sahams 看板固定输出 `can_claim_tajika_sahams_closure: false`：本地 skill 已有年运计算与解释骨架，但太阳回归精确时刻、Varsha Lagna、Muntha、Mudda Dasha、Punya/Rajya/Vivah Saham 和 Tajika Yogas 仍需 JHora/PyJHora/书例级外部证据后，才能宣称年运闭环。 + +年运第一条最短闭环状态板： + +```bash +python3 scripts/tajika_annual_closure_status.py \ + --oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --format markdown \ + --output docs/benchmark/tajika_sahams_annual_closure_status.md +``` + +如需导出可填写的年运证据包： + +```bash +python3 scripts/tajika_annual_oracle_queue.py \ + --oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --write-packet-dir references/oracle/artifacts/pending_packets \ + --format json +``` + +填完 `external_template_steve_jobs_varshaphala_1984_lahiri.json` 后，可合并回年运 oracle： + +```bash +python3 scripts/tajika_annual_oracle_queue.py \ + --oracle-file references/oracle/tajika_annual_oracle_cases.json \ + --apply-packet references/oracle/artifacts/pending_packets/external_template_steve_jobs_varshaphala_1984_lahiri.json \ + --format json +``` + +`full-reading` 也会输出 `ai_prompt_pack`：这是给网页/app、skill 或后端 AI 代理使用的结构化 Prompt/RAG 上下文包。它不会硬编码断语，而是携带 D1/D9/Dasha/Shadbala/Ashtakavarga 的证据快照、推荐检索文档和边界提示，要求大模型基于计算证据交叉验证，避免单一配置下结论。 diff --git a/docs/engine/README.md b/docs/engine/README.md new file mode 100644 index 00000000..7f81e992 --- /dev/null +++ b/docs/engine/README.md @@ -0,0 +1,322 @@ +# Jyotish 计算引擎与解读流水线（引擎层文档） + +> 本文从 2026-09-03 之前的根 README 拆出，描述 Python 引擎（`scripts/`、`references/`、`SKILL.md`）的定位、流水线、技法覆盖与诚实边界。产品层（网页、部署、协作流程）见根目录 `README.md`。正文保留原文，"Project Status"一节反映 v6.9.14 时期的状态，仅作历史参考。 + +## What Is This + +This is a **Vedic (Jyotish) astrology analysis system** designed for deep, auditable full-chart readings. It is NOT a simple ephemeris calculator — it is a multi-stage interpretive pipeline that: + +1. **Computes** divisional charts (D1/D9/D10/...) via Swiss Ephemeris +2. **Routes** 89 capability entries as a backend evidence pool (Dashas, Yogas, Shadbala, Ashtakavarga, Transits...) +3. **Routes** the analysis through strict workflow paths depending on question type (career / relationship / wealth / timing) +4. **Audits** every technique used — declaring what was called, what is complete/covered, and which limitations affect confidence +5. **Degrades gracefully** — limitations are labeled, not silently over-promising + +### Key Differentiators (vs. PyJHora / VedAstro / Maitreya) + +| Feature | This Project | PyJHora | VedAstro | Maitreya | +|---------|-------------|----------|----------|----------| +| Full-reading pipeline (one command) | ✅ | ❌ | ❌ | ❌ | +| Strict workflow router (per-question-type) | ✅ | ❌ | ❌ | ❌ | +| Technique Audit Table (confidence labeling) | ✅ | ❌ | ❌ | ❌ | +| Capability degradation (limits are explicit) | ✅ | ❌ | ❌ | ❌ | +| MEVG external verification gates | ✅ | ❌ | ❌ | ❌ | +| 89 capability entries routed as a backend evidence pool | ✅ | ✅ (50+) | ✅ (200+) | ✅ | +| Traditional algorithm benchmarked | ✅ mixed depth | ✅ | ✅ | ✅ | +| Docker / MCP Server | ✅ | ❌ | ✅ | ❌ | +| English docs / PyPI package | ✅ in progress | ✅ | ✅ | ✅ | + +--- + +### Prerequisites + +- Python 3.11+ +- Swiss Ephemeris (`pyswisseph` or `ephem`) +- Optional: `pypdf`, `pdfplumber` (for PDF chart input) + +### Install + +```bash +# Clone the repository +git clone https://github.com/732642856/yinduzhanxing.git +cd yinduzhanxing + +# Install Python dependencies +pip install -r requirements.txt + +# Verify installation +python3 scripts/audit_capabilities.py --mode validate +# Expected: valid=true, problem_count=0 +``` + +### Minimal Full Reading (5 minutes) + +```bash +python3 scripts/jyotish_engine.py full-reading \ + --year 1990 --month 6 --day 15 \ + --hour 10 --minute 30 \ + --lat 28.6139 --lon 77.2090 --tz 5.5 \ + --age 36 \ + --transit-date 2026-06-04 +``` + +**Output:** ~45 computed modules, zero errors, complete structured reading with technique audit table. + +### Sample Output (abbreviated) + +``` +═══ FULL READING ═══ +Birth Data: 1990-06-15 10:30 (+5.5) 28.61°N 77.21°E +Lagna: Gemini Sun: Taurus Moon: Leo + +── Static Analysis ── +[✓] D1 Rashi Chart +[✓] D9 Navamsa +[✓] D10 Dasamsa +[✓] Vimshottari Dasha (120 years) +[✓] Ashtakavarga (8-point system) +[✓] Shadbala (covered — absolute Rupa totals, component invariants verified) +[✓] Yogas & Doshas +[✓] Argala (planetary interventions) +[✓] Nakshatra Advanced (Chandra Bala / Tara Bala) + +── Dynamic Timing ── +[✓] Vimshottari Dasha breakdown +[✓] Dasha Sandhi detection +[✓] Transit (true positions) +[✓] Double Transit analysis +[✓] Narayana Dasha +[✓] Solar Return / Varshaphala +[✓] Nakshatra Dasha (Ashtottari) + +── Technique Audit Table ── +✓ Vimshottari Dasha covered high confidence +✓ Ashtakavarga covered high confidence +✓ Shadbala covered absolute Rupa output; total_virupas component invariant passed +✓ Chara Dasha covered KN Rao benchmark 95.83% overall match +✓ KP Sub-Lord covered SubLord/SubSubLord + ABCD significator workflow +``` + + +## Core Workflow + +### Three Input Paths + +| Path | Input | Behavior | +|------|-------|----------| +| **A: Precise birth data** | Date + time + coordinates | Full `full-reading` engine | +| **B: PDF / text chart** | Scanned chart or description | Extract → Quality Gate → route to A | +| **C: Uncertain birth time** | "Don't know my birth time" | Interactive birth time rectification | + +### Eight-Stage Pipeline + +``` +Stage -1: Question-type routing (career / relationship / wealth / timing) +Stage 0: Input routing (A / B / C) +Stage 1: (B only) PDF extraction + Quality Gate +Stage 2: Intent recognition → target house routing +Stage 3: Static analysis (10 steps) +Stage 4: Dynamic timing (7 steps) +Stage 5: Timing output (5-layer verification) +Stage 6: Remedial measures (optional) +Stage 7: Modern language packaging +Stage 8: Technique Audit Table (mandatory) +``` + +**Strict Workflow Router** (`references/strict-workflow-router.md`): +- Career questions → `career-timing-strict` +- Relationship questions → `relationship-timing-strict` +- Wealth questions → `wealth-timing-strict` +- Event timing → `event-timing-strict` +- Historical verification → `event-verification-strict` + +The AI does NOT require the user to name techniques (e.g., "Chara Dasha"). It auto-selects based on question type. + +--- + +## Technique Coverage + +Current registry count: **89 capability entries** (79 covered, 10 complete, 0 partial, 0 missing). + +These entries are a **backend evidence pool**, not a flat list of 89 user-facing +prediction sources. Ordinary users see topic-level conclusions and evidence +summaries. The question-domain router selects a small primary chain, then uses +supporting indicators only to raise/lower confidence. Audit-only and alias +entries cannot affect astrological conclusions. + +The table below lists representative high-value entries. Treat +`references/technique_registry.json` as the source of truth for the full +machine-readable registry. + +| Technique | Status | Notes | +|-----------|--------|-------| +| D1 Rashi Chart | ✅ covered | Swiss Eph base | +| D9 Navamsa | ✅ covered | | +| D10 Dasamsa | ✅ covered | | +| Vimshottari Dasha | ✅ covered | | +| Dasha Sandhi | ✅ covered | | +| Ashtakavarga | ✅ covered | BPHS/PVR calibrated | +| Argala | ✅ covered | | +| Vargottama | ✅ covered | | +| Pushkara | ✅ covered | | +| A10 / Karma Pada | ✅ covered | | +| UL / Upapada | ✅ covered | | +| Transit (true positions) | ✅ covered | | +| Double Transit | ✅ covered | | +| Nakshatra Advanced | ✅ covered | Tara Bala / Chandra Bala / Sub-Lord workflow | +| Narayana Dasha | ✅ covered | CLI and full-reading integration | +| Solar Return / Varshaphala | ✅ covered | Tajika annual-chart workflow | +| **Shadbala** | ✅ covered | **absolute Rupa component-sum output; internal invariants pass; external absolute-value oracle expansion remains open** | +| **Chara Dasha** | ✅ covered | **KN Rao benchmark: sign 100%, duration 91.67%, overall 95.83%** | +| KP Sub-Lord | ✅ covered | SubLord/SubSubLord + ABCD significator workflow | +| Bhava Chalit | ✅ covered | Sripati/Porphyry/Equal/Whole Sign/Placidus/Koch | +| Sudarshana Chakra | ✅ covered | Asc/Moon/Sun reference charts + convergence scoring | +| Tajika Yogas | ✅ complete | Annual-chart yoga set | +| Raj Yoga | ✅ covered | Rule-based detection | +| Dhana Yoga | ✅ covered | Rule-based detection | +| Pancha Mahapurusha | ✅ covered | Complete detection | +| Neecha Bhanga | ✅ complete | Debilitation cancellation workflow | +| Sade Sati | ✅ covered | Saturn pressure timing | +| Tithi Lord | ✅ complete | Lunar-day ruler workflow | +| Pancha Pakshi | ✅ complete | Five-bird system | +| Rashi Tulya Navamsa | ✅ covered | D1/D9 mapping | +| Trimshamsa D30 | ✅ covered | D30 varga support | +| Marriage Counting | ✅ complete | Bhrigu Pada marriage-counting method | +| Prashna Integration | ✅ complete | Prashna workflow integrated | +| Bhrigu Pada Dasha | ✅ complete | Pada progression workflow | +| Muhurta | ✅ covered | Panchanga / auspicious timing workflow | + +**Legend:** +- ✅ `covered` — implemented and benchmarked against authoritative sources +- ✅ `complete` — implemented with integrated workflow and validation hooks +- ✅ `covered` — implemented and available in the engine, sometimes with explicit confidence caps +- 🔶 `partial` — reserved for implemented-but-insufficiently-integrated techniques; current registry count is 0 +- ❌ `missing` — not currently present in the registry; current registry count is 0 + +--- + +## Why This Exists (Competitive Context) + +### The Landscape + +| Project | Type | Strength | Weakness | +|---------|------|----------|-----------| +| **PyJHora** | Calculation library | Strongest traditional algorithm coverage (50+ Dashas, 284 Yogas) | No interpretive pipeline; user must interpret results themselves | +| **VedAstro** | API / Web platform | 200+ endpoints, Docker, MCP Server, MIT license | Interpretive audit & confidence labeling weaker | +| **Maitreya** | Desktop software | Mature cross-platform GUI | Jyotish depth not as deep as specialized projects | +| **jyotisha** | Panchanga / calendar | Excellent Panchanga accuracy | Not a full reading system | +| **This project** | AI-native analysis system | Full pipeline + audit + degradation | Pure calculation accuracy still being benchmarked | + +### Our Position + +> **PyJHora is the calculator. VedAstro is the API platform. Maitreya is the desktop software. This project is the "AI-native Jyotish research analyst."** + +We are NOT trying to out-calculate PyJHora (it has years of lead). Our value is in: +1. Organizing calculations into a **reproducible interpretive workflow** +2. **Auditing** every technique used and declaring confidence +3. **Degrading gracefully** — confidence caps and limitations are labeled, not silently over-promising +4. Being **AI-native** — designed for integration with LLM-based analysis + +--- + +## Honest Assessment + +We believe in transparency about limitations. This is NOT a "99% accurate" system, and anyone claiming that about Jyotish is over-selling. + +### Current Accuracy Estimates (self-evaluated) + +| Dimension | Score | Notes | +|-----------|-------|-------| +| Astronomical foundation (Swiss Eph) | 8.5/10 | Depends on ayanamsa, node mode, house system | +| Traditional algorithm accuracy | 8.4/10 | Chara Dasha benchmark passed; Shadbala absolute Rupa invariants now pass; Dasha oracle expansion remains open | +| Technique coverage breadth | 9.1/10 | 65 registered techniques; broad and increasingly benchmarked | +| Reading detail depth | 9.6/10 | Possibly best among open-source projects | +| Prediction workflow rigor | 8.8/10 | Strict routing + audit table | +| Verification system | 8.2/10 | Has registry, benchmark, degradation; some verification still internal | +| Engineering maturity | 7.6/10 | Docker, PyPI config and CI exist; release artifacts still need cleanup | +| Open-source influence | 5.5/10 | Currently more of a "private high-density toolkit" | + +### What Confidence Caps Mean (Important) + +Even when a technique is labeled `covered`, it may carry a confidence or validation boundary: +- It CAN produce output +- Some components may still need broader external oracle expansion against PyJHora / JHora / canonical texts +- It should be interpreted together with cross-technique evidence +- It must NOT be the sole basis for high-confidence predictions when its limitation says so + +Examples: +- `Shadbala` (covered): absolute Rupa totals are reported directly from six component sums; internal component invariants pass and `total_rupas = total_virupas / 60`, while external absolute-value oracle expansion remains open. +- `Chara Dasha` (covered): KN Rao benchmark passes at 95.83% overall; remaining differences are documented around Aquarius/Scorpio co-lord strength arbitration. + +--- + +## Project Status + +**Current version:** `v6.9.14` + +### Recently Completed + +- `v6.9.14` — Sudarshana Chakra complete + 475 pytest cases + 65-technique registry audit PASS. +- `v6.9.13` — Bhava Chalit complete + transit trigger output normalization + Nakshatra test calibration. +- `v6.9.12` — Shadbala precision upgrade + Ashtakoot 36-point compatibility + expanded subcommands. +- `v6.9.6` — Field mapping fixes (degree→degree_in_sign + toFixed null safety); PyPI publishing config. +- `v6.9.5` — birth_info null safety + API field mapping fixes. +- `v6.9.4` — AI interpretation integration; current browser build disables direct model API keys and routes AI through server-side `/api/chat` or a backend proxy. +- `v6.9.3` — 35 Dasha systems, 405+ Yoga rules, KP complete system, Prashna, 16-factor synastry, Remedies, Sahams 36, Sudarshana, PMC, Tajika. +- `v6.1.12` — Chara Dasha KN Rao Method rewrite, PyJHora benchmark 95.83% PASS. +- `v6.1.10` — Darakaraka deep reader wired into `full-reading.modules.jaimini.darakaraka`; thematic reports now consume real DK and Rashi Tulya Navamsa evidence. +- `v6.1.9` — Public/sanitized benchmark suite, competitive research, coverage roadmap and PDF validation methodology added. +- `v6.1.8` — Yoga validation reached F1=95.22% (FP=36, FN=63); thematic reports consume real `full-reading.modules` evidence. +- `v6.1.6` — Five-system Dasha convergence wired into full-reading (Vimshottari + Chara + Yogini + Ashtottari + Kalachakra). +- `v6.0.11` — Shadbala 1200/1200 internal invariants pass; later upgraded to absolute Rupa component-sum output. + +### Actively Working On (P0) + +1. **Release hygiene** — run the release profile, keep product-critical files tracked, rebuild wheel/sdist, and align GitHub tags with source version +2. **README / package metadata sync** — keep public docs, registry counts and distribution artifacts consistent +3. **Dasha oracle expansion** — add external cases for Vimshottari start/end boundaries and configurable year-length/ayanamsa comparisons +4. **Benchmark expansion** — add more oracle cases for Shadbala, KP and annual-chart modules +5. **Frontend verification** — keep the Next.js API contracts aligned with the Python engine output + +### Next (P1) + +- Production image publishing and smoke-test docs +- English documentation examples and API tutorials +- Multi-Ayanamsa UX polish and benchmark examples（计算层已可验证切换；网页设置展示和更多外部样本仍需补齐） + +--- + +## Engine-level development checks + +### Running the Test Suite + +```bash +# Syntax check all scripts +python3 -m py_compile scripts/*.py + +# Capability audit (must pass with 0 problems, 0 warnings) +python3 scripts/audit_capabilities.py --mode validate + +# Next.js unit tests, lint, and production build +npm test --prefix frontend +npm run lint --prefix frontend +npm run build --prefix frontend + +# Full-reading regression test (use FICTIONAL data only) +python3 scripts/jyotish_engine.py full-reading \ + --year 1990 --month 6 --day 15 \ + --hour 10 --minute 30 \ + --lat 39.9042 --lon 116.4074 --tz 8 \ + --age 36 \ + --transit-date 2026-06-04 +``` + +### Important Rules + +1. **NEVER** put real user birth data into skill files, tests, CHANGELOG, or public repos +2. Use only: (a) public AA-rated celebrity data, (b) explicitly fictional smoke tests, (c) current-session data (never persisted) +3. Always run `git status --short --branch` before starting work +4. Always run `py_compile` + `audit_capabilities.py` + full-reading regression after modifications +5. Do NOT remove a confidence or validation boundary without external benchmark evidence +6. Do NOT refactor arbitrarily; make minimal verifiable changes + diff --git a/docs/engine/vedastro-gateway.md b/docs/engine/vedastro-gateway.md new file mode 100644 index 00000000..6c529063 --- /dev/null +++ b/docs/engine/vedastro-gateway.md @@ -0,0 +1,201 @@ +# 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 /.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": "" + } +} +``` + +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 /.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \ + + +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 已闭环。 diff --git a/PROGRESS-billing-pricing-20260830.md b/docs/tasks/PROGRESS-billing-pricing-20260830.md similarity index 100% rename from PROGRESS-billing-pricing-20260830.md rename to docs/tasks/PROGRESS-billing-pricing-20260830.md diff --git a/PROGRESS-chat-streaming-ux-20260901.md b/docs/tasks/PROGRESS-chat-streaming-ux-20260901.md similarity index 100% rename from PROGRESS-chat-streaming-ux-20260901.md rename to docs/tasks/PROGRESS-chat-streaming-ux-20260901.md diff --git a/PROGRESS-contract-repairs-20260901.md b/docs/tasks/PROGRESS-contract-repairs-20260901.md similarity index 100% rename from PROGRESS-contract-repairs-20260901.md rename to docs/tasks/PROGRESS-contract-repairs-20260901.md diff --git a/PROGRESS-engine-runtime-hygiene-20260901.md b/docs/tasks/PROGRESS-engine-runtime-hygiene-20260901.md similarity index 100% rename from PROGRESS-engine-runtime-hygiene-20260901.md rename to docs/tasks/PROGRESS-engine-runtime-hygiene-20260901.md diff --git a/PROGRESS-frontend-followup-20260829.md b/docs/tasks/PROGRESS-frontend-followup-20260829.md similarity index 100% rename from PROGRESS-frontend-followup-20260829.md rename to docs/tasks/PROGRESS-frontend-followup-20260829.md diff --git a/PROGRESS-frontend-interaction-20260830.md b/docs/tasks/PROGRESS-frontend-interaction-20260830.md similarity index 100% rename from PROGRESS-frontend-interaction-20260830.md rename to docs/tasks/PROGRESS-frontend-interaction-20260830.md diff --git a/PROGRESS-frontend-optimization-20260828.md b/docs/tasks/PROGRESS-frontend-optimization-20260828.md similarity index 100% rename from PROGRESS-frontend-optimization-20260828.md rename to docs/tasks/PROGRESS-frontend-optimization-20260828.md diff --git a/PROGRESS-home-split-20260901.md b/docs/tasks/PROGRESS-home-split-20260901.md similarity index 100% rename from PROGRESS-home-split-20260901.md rename to docs/tasks/PROGRESS-home-split-20260901.md diff --git a/PROGRESS-home-split-batch2-20260901.md b/docs/tasks/PROGRESS-home-split-batch2-20260901.md similarity index 100% rename from PROGRESS-home-split-batch2-20260901.md rename to docs/tasks/PROGRESS-home-split-batch2-20260901.md diff --git a/PROGRESS-home-split-batch3-20260901.md b/docs/tasks/PROGRESS-home-split-batch3-20260901.md similarity index 100% rename from PROGRESS-home-split-batch3-20260901.md rename to docs/tasks/PROGRESS-home-split-batch3-20260901.md diff --git a/PROGRESS-react-compiler-20260817.md b/docs/tasks/PROGRESS-react-compiler-20260817.md similarity index 100% rename from PROGRESS-react-compiler-20260817.md rename to docs/tasks/PROGRESS-react-compiler-20260817.md diff --git a/PROGRESS-rectification-convergence-20260830.md b/docs/tasks/PROGRESS-rectification-convergence-20260830.md similarity index 100% rename from PROGRESS-rectification-convergence-20260830.md rename to docs/tasks/PROGRESS-rectification-convergence-20260830.md diff --git a/PROGRESS-rectification-decision-authority-20260831.md b/docs/tasks/PROGRESS-rectification-decision-authority-20260831.md similarity index 100% rename from PROGRESS-rectification-decision-authority-20260831.md rename to docs/tasks/PROGRESS-rectification-decision-authority-20260831.md diff --git a/PROGRESS-report-blocked-repairs-20260902.md b/docs/tasks/PROGRESS-report-blocked-repairs-20260902.md similarity index 100% rename from PROGRESS-report-blocked-repairs-20260902.md rename to docs/tasks/PROGRESS-report-blocked-repairs-20260902.md diff --git a/PROGRESS-report-sectioned-20260830.md b/docs/tasks/PROGRESS-report-sectioned-20260830.md similarity index 100% rename from PROGRESS-report-sectioned-20260830.md rename to docs/tasks/PROGRESS-report-sectioned-20260830.md diff --git a/PROGRESS-report-skill-parity-20260901.md b/docs/tasks/PROGRESS-report-skill-parity-20260901.md similarity index 100% rename from PROGRESS-report-skill-parity-20260901.md rename to docs/tasks/PROGRESS-report-skill-parity-20260901.md diff --git a/PROGRESS-report-writer-failure-20260902.md b/docs/tasks/PROGRESS-report-writer-failure-20260902.md similarity index 100% rename from PROGRESS-report-writer-failure-20260902.md rename to docs/tasks/PROGRESS-report-writer-failure-20260902.md diff --git a/PROGRESS-unified-loading-20260902.md b/docs/tasks/PROGRESS-unified-loading-20260902.md similarity index 100% rename from PROGRESS-unified-loading-20260902.md rename to docs/tasks/PROGRESS-unified-loading-20260902.md diff --git a/docs/tasks/README.md b/docs/tasks/README.md new file mode 100644 index 00000000..7d1703ca --- /dev/null +++ b/docs/tasks/README.md @@ -0,0 +1,72 @@ +# 任务书与进度记录（docs/tasks/） + +这里存放每一轮协作的**任务书**（`TASK-<主题>-<日期>.md`）和执行方的**进度记录**（`PROGRESS-<主题>-<日期>.md`）。2026-09-03 之前它们堆在仓库根目录，已整体搬到这里；新文件一律直接写在本目录。 + +- 任务书由产品/架构侧（通常是 Claude）写，包含：基线 commit、事故实证、根因、决策记录、硬红线、任务分解、验收标准。 +- 进度记录由执行方（coding agent）写：做了什么、测试数字、偏离与原因。 +- 被环境或依赖挡住的事项写进根目录 `BLOCKED.md`；Bug 事实写进 `docs/BUG_HISTORY.md`；两者不在这里重复。 +- 纯文档改动不触发 staging 门禁（见 `deploy/gated-paths.txt`）。 + +## 索引（按主题） + +### 生时校正（rectification） + +| 任务书 | 进度 | 主题 | +| --- | --- | --- | +| `TASK-rectification-convergence-20260830.md` | `PROGRESS-rectification-convergence-20260830.md` | 收敛重构 v2 | +| `TASK-rectification-decision-authority-20260831.md` | `PROGRESS-rectification-decision-authority-20260831.md` | 决策权威归一与停止语义 | +| `TASK-rectification-billing-20260831.md` | — | run_failed 与开场问题槽为空 | +| `TASK-round2-cost-and-delivery-20260831.md` | — | 第二轮真实成本与交付物 | +| `TASK-rectification-provisional-adopt-20260901.md` | — | provisional 采用成为一等成功出口 | +| `TASK-rectification-engine-convergence-20260901.md` | — | 引擎侧相邻分钟可区分 | +| `TASK-rectification-nonterminal-exit-20260901.md` | — | 非终态轮出口统一 | +| `TASK-rectification-tails-20260901.md` | — | Round A/2 收尾 | +| `TASK-rectification-question-in-message-20260902.md` | — | 题目进消息、删问题槽 | +| `TASK-rectification-question-ownership-fix-20260902.md` | — | 选项回归服务端、fail-closed | +| `TASK-rectification-adopt-flow-20260902.md` | — | 采用流程整治 | +| `TASK-rectification-adopt-flow-fix-20260903.md` | — | 采用流程修复单（含删「用这个时间看盘」） | +| `TASK-rectification-uncertainty-stop-20260903.md` | — | 不确定度停止规则加样本下限（BUG-503） | +| `TASK-rectification-walkthrough-polish-20260902.md` | — | 首次真实走查抛光（服务端） | +| `TASK-rectification-ux-20260902.md` | — | 会话面空白假死与交互摩擦（09-03 已在新基线重启） | +| `TASK-consultation-birth-accuracy-20260901.md` | — | 咨询侧出生时间精度真值传递 | + +### 聊天主链路与首页 + +| 任务书 | 进度 | 主题 | +| --- | --- | --- | +| `TASK-chat-message-authority-20260901.md` | — | 消息服务端权威化（BUG-464） | +| `TASK-session-url-20260901.md` | — | 会话 URL 化 | +| `TASK-cloud-truth-convergence-20260901.md` | — | 本地/云端双份真相收敛 | +| `TASK-home-split-20260901.md` | `PROGRESS-home-split-20260901.md` | 拆分首页巨石组件·第一批 | +| `TASK-contract-repairs-20260901.md` | `PROGRESS-contract-repairs-20260901.md` | 孤儿契约红修复（先于第二批） | +| `TASK-home-split-batch2-20260901.md` | `PROGRESS-home-split-batch2-20260901.md` | 拆页第二批：聊天主链路 | +| `TASK-home-split-batch3-20260901.md` | `PROGRESS-home-split-batch3-20260901.md` | 拆页第三批：onboarding/profile | +| `TASK-chat-streaming-ux-20260901.md` | `PROGRESS-chat-streaming-ux-20260901.md` | 流式体验与双会话面统一 | +| `TASK-unified-loading-20260902.md` | `PROGRESS-unified-loading-20260902.md` | 首页一次等待一次揭幕（BUG-479） | +| `TASK-agent-voice-20260901.md` | — | Agent 输出语气 | + +### 个人报告 + +| 任务书 | 进度 | 主题 | +| --- | --- | --- | +| `TASK-report-sectioned-generation-20260830.md` | `PROGRESS-report-sectioned-20260830.md` | 分章节生成 | +| `TASK-report-skill-parity-20260901.md` | `PROGRESS-report-skill-parity-20260901.md` | 内容对齐 skill 解读深度 | +| `TASK-report-blocked-repairs-20260902.md` | `PROGRESS-report-blocked-repairs-20260902.md` | 全主题 blocked 修复 | +| `TASK-report-section-writer-failure-20260902.md` | `PROGRESS-report-writer-failure-20260902.md` | 写作阶段 report_schema_invalid | + +### 前端基础与工程 + +| 任务书 | 进度 | 主题 | +| --- | --- | --- | +| `TASK-frontend-optimization-20260828.md` | `PROGRESS-frontend-optimization-20260828.md` | 前端优化九条 | +| `TASK-frontend-followup-20260829.md` | `PROGRESS-frontend-followup-20260829.md` | 九条收尾 | +| `TASK-frontend-interaction-20260830.md` | `PROGRESS-frontend-interaction-20260830.md` | 交互与 UI 收尾 | +| — | `PROGRESS-react-compiler-20260817.md` | React Compiler 尝试（已回滚，结论见 BLOCKED.md） | +| `TASK-engine-runtime-hygiene-20260901.md` | `PROGRESS-engine-runtime-hygiene-20260901.md` | Python 引擎运行时治理 | +| `TASK-billing-pricing-20260830.md` | `PROGRESS-billing-pricing-20260830.md` | 计费闭环与功能级定价 | + +## 命名与归档 + +- 文件名：`TASK--.md`；同主题的修复单加 `-fix`；进度记录同名换前缀。 +- 一轮结束后不删除文件；结论沉淀到 `docs/BUG_HISTORY.md`（Bug）、`CHANGELOG.md`（行为/skill 变化）、`frontend/DESIGN.md`（视觉与交互合同）。 +- 任务书里的行号会随代码漂移，定位以符号名为准。 diff --git a/TASK-agent-voice-20260901.md b/docs/tasks/TASK-agent-voice-20260901.md similarity index 100% rename from TASK-agent-voice-20260901.md rename to docs/tasks/TASK-agent-voice-20260901.md diff --git a/TASK-billing-pricing-20260830.md b/docs/tasks/TASK-billing-pricing-20260830.md similarity index 100% rename from TASK-billing-pricing-20260830.md rename to docs/tasks/TASK-billing-pricing-20260830.md diff --git a/TASK-chat-message-authority-20260901.md b/docs/tasks/TASK-chat-message-authority-20260901.md similarity index 100% rename from TASK-chat-message-authority-20260901.md rename to docs/tasks/TASK-chat-message-authority-20260901.md diff --git a/TASK-chat-streaming-ux-20260901.md b/docs/tasks/TASK-chat-streaming-ux-20260901.md similarity index 100% rename from TASK-chat-streaming-ux-20260901.md rename to docs/tasks/TASK-chat-streaming-ux-20260901.md diff --git a/TASK-cloud-truth-convergence-20260901.md b/docs/tasks/TASK-cloud-truth-convergence-20260901.md similarity index 100% rename from TASK-cloud-truth-convergence-20260901.md rename to docs/tasks/TASK-cloud-truth-convergence-20260901.md diff --git a/TASK-consultation-birth-accuracy-20260901.md b/docs/tasks/TASK-consultation-birth-accuracy-20260901.md similarity index 100% rename from TASK-consultation-birth-accuracy-20260901.md rename to docs/tasks/TASK-consultation-birth-accuracy-20260901.md diff --git a/TASK-contract-repairs-20260901.md b/docs/tasks/TASK-contract-repairs-20260901.md similarity index 100% rename from TASK-contract-repairs-20260901.md rename to docs/tasks/TASK-contract-repairs-20260901.md diff --git a/TASK-engine-runtime-hygiene-20260901.md b/docs/tasks/TASK-engine-runtime-hygiene-20260901.md similarity index 100% rename from TASK-engine-runtime-hygiene-20260901.md rename to docs/tasks/TASK-engine-runtime-hygiene-20260901.md diff --git a/docs/tasks/TASK-frontend-followup-20260829.md b/docs/tasks/TASK-frontend-followup-20260829.md new file mode 100644 index 00000000..3b4f8ab8 --- /dev/null +++ b/docs/tasks/TASK-frontend-followup-20260829.md @@ -0,0 +1,291 @@ +# 任务书 · 前端优化九条的收尾（2026-08-29） + +复核对象：`origin/staging` @ `3198fb6b`（"perf(frontend): split chat streaming, load Inter, isolate admin CSS"）。 + +上一轮交付基本属实，我逐条实测过：`tsc --noEmit` exit 0、`eslint` 0 error、`next build` exit 0、路由模式（`/` `○ Static`、`/login` `/admin/**` 仍 `ƒ`）、admin 路由确实不再引用含 `.message-list` 的 216 KB globals chunk、`public/` 只剩 logo、Inter 走 `next/font` 并生成独立 `@font-face` chunk、星盘库 effect 已合并成单 effect 三分支。**本轮不重做这些，只收三个尾巴。** + +--- + +## 硬红线 + +1. **不得修改任何既有测试断言。** 本轮三条任务都不需要改断言 —— 如果你发现"必须改断言才能过"，那是方案错了，停下来登记 `BLOCKED.md`，不要动断言。 +2. **不得让 `error.tsx` / `not-found.tsx` 重新 import `globals.css` 或 `site-styles`。** 这两页与 admin 共享根布局段，一旦 import，admin 每条路由会重新背上约 33 KB gzip —— 上一轮 −32 KB 的成果会当场归零。`tests/site-style-isolation-contract.test.ts` 已锁这条，它必须保持绿灯且不被修改。 +3. 不得手写 `useCallback` / `useMemo`。 +4. 不得为迎合 React Compiler 改写代码；本轮不重开 React Compiler（理由见 `BLOCKED.md` 2026-08-17 记录）。 +5. 推 staging 前必须 `./node_modules/.bin/tsc --noEmit` 通过（BUG-409 防复发）。**不要用 `npx tsc`**，本仓库环境下会装到空包 `tsc@2.0.4`。 +6. 测试数不得低于基线 **2205**，且 `fail=0`、`skipped=0`（在有 Docker 的环境里跑）。 +7. 不得改 `.gitea/workflows/**`。不得在有未提交改动的工作树上切分支。不得自行把 staging 提升到 main。 + +让步顺序：功能与测试不回归 > 可验证的修复 > 代码整洁。 + +## 开工前置 + +```bash +git fetch origin --prune +git worktree add -b codex/frontend-followup-20260829 \ + ../.worktrees/frontend-followup-20260829 origin/staging +``` + +基线必须是 `origin/staging`，不是任何本地 ref。读 `pre_work_error_ledger.md`，跑 `scripts/pre_work_check.py`，读 `frontend/AGENTS.md`（Next.js 版本与你训练数据不同，写代码前先看 `node_modules/next/dist/docs/`）。改前先在 `docs/BUG_HISTORY.md` 里检索是否有同类记录。 + +--- + +## 任务 A（P0）· 根 404 / 错误页现在完全没有样式 + +### 事实 + +`src/app/not-found.tsx` 和 `src/app/error.tsx` 的 markup 是纯 Tailwind 工具类，但上一轮把 globals 从根布局段摘掉后，这两页**一条 CSS 都不加载**。构建产物实证： + +``` +.next/server/app/_not-found.html + → 只引用 3b67syn08d_z3.css（2,146 B，纯 Inter @font-face） +`min-h-svh` / `text-muted-foreground` 的定义只在 0grkt280n67e_.css（216 KB），该页不加载它 +``` + +用户看到的是浏览器默认裸 HTML：不居中、无配色、无间距，`