Jesse_Chen
e8d201dd9a
Second batch from the staging UX audit (BUG-248..253). - css: expose the 32 palette tokens through @theme. Seven utilities including text-ink, text-danger and text-warning compiled to no CSS at all, so 30 call sites had been silently inert (BUG-248) - chat: move the composer into its own component behind a draft store, so a keystroke no longer re-renders a 2723-line component, and persist the draft across reloads (BUG-249) - chat: load gsap, react-markdown and thinking-orbs on demand. First Load JS for / drops 549.5 kB to 476.3 kB gzipped (BUG-250) - chat: route the five in-app destinations through router.push, and keep the five auth redirects and the bootstrap retry as hard loads on purpose (BUG-251) - a11y: announce reply completion, and move the live region out of the aria-busy subtree that was likely suppressing even the start announcement (BUG-252) - docs: give the 27 collided bug ids unique numbers and repair their inbound references; require search rather than a full read of a 3690-line file (BUG-253) Verified: tsc, eslint, next build, and 1592 assertions across the 199 non-database test files. Co-authored-by: Cursor <cursoragent@cursor.com>
173 lines
11 KiB
Markdown
173 lines
11 KiB
Markdown
# Jyotish Skill Agent Constraints
|
|
|
|
本文件是当前项目给协作代理、自动化助手与派生工作流的硬约束补充。它不替代 `SKILL.md`，而是把最容易被偷懒、省略、或在多窗口工作时遗失的高严谨规则单独钉死。
|
|
|
|
## 0. Production Maintenance Truth
|
|
|
|
任何部署、线上故障、域名、登录或环境变量任务，先读取 `deploy/README.md`，不要重新猜测架构。
|
|
|
|
- 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
|
|
|
|
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.
|
|
|
|
## 1. High-Rigor Override
|
|
|
|
当用户明确要求以下任一项时，必须进入高严谨模式：
|
|
|
|
- 不要凭经验泛谈
|
|
- 必须拉满三大开源参照引擎能力
|
|
- 必须提交底层原始数据
|
|
- 必须验证过去案例
|
|
- 必须避免偷工减料
|
|
|
|
进入该模式后，以下规则全部强制执行：
|
|
|
|
1. 必须尝试交叉参照 `PyJHora`、`VedAstro`、`jyotishganit`，并保持许可证边界。
|
|
2. 必须优先调用本仓原生实现，不得只用轻量包装脚本代替主链代码。
|
|
3. 涉及 timing / event / outcome，不得只看 `Vimshottari`，至少需要 `Vimshottari + Narayana Dasha` 双轨交叉。
|
|
4. 必须按问题域强制调取相关分盘：
|
|
- 事业：`D10 + A10`
|
|
- 财富：`D2 / D11`
|
|
- 婚恋：`D9 + UL`
|
|
5. 必须交付原始数据依据：度数、Dasha 边界、Shadbala / Ashtakavarga、Yoga 名称、Ayanamsa / Node mode、外部证据路径。
|
|
|
|
## 2. Functional Benefic/Malefic Hard Constraint
|
|
|
|
**强制调取 Functional Benefic / Malefic 判定（功能性吉凶星判定）。**
|
|
|
|
这条约束与 Dasha / 分盘 / 原始数据交付同级，不得省略。
|
|
|
|
执行要求：
|
|
|
|
1. 每次进入高严谨模式，必须显式判定当前 Lagna 下的 `functional benefics` 与 `functional malefics`。
|
|
2. 任何关于事业、财富、婚恋、健康、障碍、回报、应期的结论，都不得只依据自然吉凶星（natural benefic/malefic）下判断，必须叠加功能性吉凶星层。
|
|
3. 若某颗星在自然属性与功能属性之间冲突，必须在输出中说明冲突来源，并降低置信度或标记 `blocked`。
|
|
4. 若未调用功能性吉凶星判定，不得声称该次解读完成了高严谨模式。
|
|
5. Technique Audit Table 中必须出现 `Functional Benefic/Malefic` 一行，说明：
|
|
- `Used / not used / blocked`
|
|
- 关键功能吉星
|
|
- 关键功能凶星
|
|
- 对结论置信度的影响
|
|
|
|
## 3. Existing MEVG Invocation Hard Constraint
|
|
|
|
**强制执行既有 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`
|
|
4. 若无法完成外部资料采集、无法找到真实案例、网络/工具不可用、或来源之间出现重大冲突，必须写成 `blocked` 或降级置信度，不得静默跳过。
|
|
5. 只有 **纯计算 / 纯代码 / 纯项目维护** 可以豁免 MEVG，例如运行测试、检查 Git 状态、修复代码、输出未解释的原始度数或 Dasha 边界。一旦开始解释“这代表什么运势”，豁免立即失效。
|
|
|
|
## 4. Honesty Boundary
|
|
|
|
以下情况必须明确写成 `blocked` 或降级置信度：
|
|
|
|
- 外部 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: branches: [staging]` 没有路径过滤，任何改动（包括纯文档）都会跑完整构建与部署，应合并同批改动一次推送。
|
|
4. 由 quality gate 构建 digest 固定镜像并 dispatch `deploy-staging`，随后在 `https://staging.jyotisha.chat` 完成与风险相称的验收。`GET /api/health` 的 `.deployment.gitCommit` 必须等于本次 SHA，否则视为未部署。
|
|
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` 仅为镜像，其工作流已停用，不得用它验证交付状态。
|
|
|
|
## 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`.
|