Jyotisha/docs/roadmap/optimization_plan_v6_2.md

# 印度占星 Skill v6.2 优化路线图

> **版本基准**: v6.1.12 (2026-06-11)
> **文档版本**: v1.0
> **原则**: 严谨、详细、不设定完成时间、优先复用开源、逐条可验证

---

## 一、当前状态总览（实事求是）

### 1.1 技法注册表状态

| 状态 | 数量 | 占比 |
|------|------|------|
| covered | 31 | 64.6% |
| partial | 17 | 35.4% |
| missing | 0（registry中） | 0% |

**但**: `feature-gap-matrix-2026.md` 与 `technique_registry.json` 存在口径差异。Registry 中标记为 covered 的部分技法（如 Shadbala、Bhava Chalit）在 gap matrix 中仍有简化项；gap matrix 中标记为 ❌ 的部分功能（如 Darakaraka、RTN）实际已在 v6.1.10 接入 full-reading。**本文档以代码实际实现为真，以 registry 为辅助参考。**

### 1.2 关键精度指标

| 模块 | 当前指标 | 目标 | 缺口 |
|------|---------|------|------|
| Yoga识别 | F1=95.22%, P=96.48%, R=93.99% | F1≥96% | FN=63条, FP=36条 |
| Chara Dasha | Sign=100%, Dur=91.67%, Overall=95.83% | Overall≥98% | Aquarius/Scorpio共主判定 |
| Shadbala | 内部不变量1200/1200通过 | 外部绝对值校准 | 无JHora对标数据 |
| Ashtakavarga | SAV=337/386校准通过 | 完整PAV+Sodhita | 缺PAV展开、Sodhita减法 |
| Vimshottari | 未正式benchmark | 与PyJHora对标 | 待建立oracle测试 |
| Transit | 340/340字段 Swiss Ephemeris匹配 | 保持100% | 无已知缺口 |

### 1.3 已知计算缺口（经代码验证）

| # | 缺口项 | 影响 | 验证状态 |
|---|--------|------|---------|
| 1 | **Prastara Ashtakavarga (PAV)** | 行运精细评分缺失 | 完全无代码 |
| 2 | **Sodhita Ashtakavarga** | AV吉凶修正层缺失 | 完全无代码 |
| 3 | **Kakshya评分** | 行星度数区间力量量化缺失 | 完全无代码 |
| 4 | **Kantaka Shani** | Sade Sati细分阶段缺失 | 仅有文档，无引擎代码 |
| 5 | **Bhava Bala** | 宫位力量计算缺失 | 完全无代码 |
| 6 | **D81/D108/D144/自定义分盘** | 精微分盘缺失 | 完全无代码 |
| 7 | **Vimshottari外部benchmark** | 大运精度未验证 | 无oracle测试 |

### 1.4 文档与代码不一致项

| 文档 | 声明 | 实际代码状态 | 修复动作 |
|------|------|-------------|---------|
| `technique-capability-matrix.md` | 不存在 | registry替代 | 删除或重定向 |
| `quick-reference-guide.md` | 引用 `birth-time-rectification-guide.md` | 文件不存在 | 修正为 `-advanced.md` |
| `quick-reference-guide.md` | 引用 `cmd_rectify` 子命令 | jyotish_engine.py中不存在 | 删除错误引用 |
| `quick-reference-guide.md` | 引用 `birth_time_rectification.py` | scripts/下不存在 | 清理引用 |
| `COVERAGE_AUDIT_REPORT.md` | v3.13.1 | 实际v6.1.12 | 文档版本需更新 |
| `SKILL.md` | 版本号v6.1.8 | 实际v6.1.12 | 更新版本号 |

---

## 二、优化原则

1. **真代码优先**: 不以文档声明为准，以 `scripts/*.py` 实际可执行代码为准。
2. **Benchmark驱动**: 任何精度优化必须有 PyJHora / Swiss Ephemeris / 公开书例作为 oracle，不接受"感觉对了"。
3. **开源复用优先**: 已有 MIT/AGPL 开源实现的，优先翻译/适配，不从零造轮子。
4. **增量验证**: 每项改动必须通过 `python3 -m py_compile` + 相关 benchmark + `pytest` 三重门禁。
5. **文档同步**: 代码变更后，同步更新 `technique_registry.json`、`SKILL.md`、`CHANGELOG.md`。
6. **诚实标注**: partial 就是 partial，不因情感因素升级为 covered；升级必须有 benchmark 证据。

---

## 三、P0 精度修复层（影响解读正确性）

> **定义**: 当前已标记为 covered 但存在已知精度缺口、可能导致解读错误的计算模块。

### P0.1 Chara Dasha 剩余 4.2% 不匹配修复

**目标**: 将 Overall 从 95.83% 提升至 ≥98%。

**技术方案**:
- 文件: `scripts/jaimini.py`
- 函数: `_resolve_chara_dasha_lord()`（已预留扩展点）
- 问题: Aquarius/Scorpio 的 Rahu/Ketu 共主动态判定当前使用传统宫主（Saturn/Mars），而 PyJHora 使用 `_stronger_planet_new()` 完整尊严比较链。
- 实现: 复制 PyJHora `_stronger_planet_new` 逻辑（尊严层级: exalted > own > friendly > neutral > enemy > debilitated；同层级比较 Shadbala 力量），在 `_resolve_chara_dasha_lord()` 中当 sign 为 Aquarius 或 Scorpio 时，动态比较 Saturn vs Rahu 或 Mars vs Ketu 的尊严，返回较强者。

**验证方法**:
- 扩展 `benchmarks/jyotish/scripts/run_chara_dasha_knrao.py`
- 10案例×12星座 = 120对基准已建立，修复后重新跑全量
- 目标: Overall ≥98%（允许 Mean/True Node 口径差异导致的固有偏差）

**开源复用**:
- PyJHora `jhora/panchanga/dhasa/jaimini_dhasa.py:_stronger_planet_new()`（AGPL，算法翻译为独立实现）

**预期效果**:
- 约 5/120 案例的 duration 差异消除
- Sign 匹配保持 100%

---

### P0.2 Yoga 引擎 FN/FP 收敛

**目标**: F1 从 95.22% 提升至 ≥96%，FN 从 63 降至 ≤50，FP 从 36 降至 ≤30。

**技术方案**:
- 文件: `scripts/yoga_engine.py`
- 当前: 60张测试图，82条可对比规则，FN=63, FP=36
- 策略: **准确率优先**，只接受来源语义明确且预验证不增加 FP 的规则优化。

**具体待分析项**（基于 v6.1.8 验证报告 `references/validation_logic_report.json`）:
1. **Thrikaala Gnana Yoga**: 当前保守口径（D9/D60 上下文已注入），需评估是否可适度放宽前提条件而不增加 FP。
2. **Dharidhra Yoga**: 方法已恢复，评估是否有剩余 FN 可归因于 Navamsa 弱势定义差异。
3. **Parannabhojana Yoga**: 与 Dharidhra 类似，检查分盘口径。
4. **Nishkapata Yoga**: BVR-205 友好星座条件已恢复，评估剩余 FN。
5. **Kapata Yoga**: v6.1.8 已评估"4宫主受凶星相位"候选会增加 FP 且无 FN 收益，保持原逻辑；若后续发现新的 FN 收益证据，重新评估。

**验证方法**:
- 运行 `scripts/validate_logic_v2.py`
- 对比 PyJHora 同案例输出（需建立 10-20 个公开名人案例的 Yoga 清单 oracle）
- 每项规则变更前后对比 FP/FN 变化

**开源复用**:
- PyJHora `jhora/panchanga/yoga.py`（参考其 Yoga 判定逻辑，AGPL 翻译）

**预期效果**:
- F1 ≥96%，FP ≤30，FN ≤50

---

### P0.3 Vimshottari Dasha 外部 Benchmark 建立

**目标**: 建立 Vimshottari 的 PyJHora oracle 基准，验证 MD/AD/PD 三层时间边界。

**技术方案**:
- 新文件: `benchmarks/jyotish/scripts/run_vimshottari_compare.py`
- 参照 `run_chara_dasha_knrao.py` 结构
- 输入: 10个公开/虚构 smoke case（与 Chara Dasha benchmark 共用样本池）
- Oracle: PyJHora `Vimsottari.get_dhasa_bhukthi(dob, tob, place, divisional_chart_factor=1)`
- 对比字段: MD主星、MD起始日期、MD结束日期、AD主星、AD起始日期、PD主星、PD起始日期

**验证方法**:
- 建立 120 对基准（10案例 × 12 字段）
- 目标: ≥95% 字段级匹配（允许时区/闰秒差异）
- 若发现系统偏差，定位至 `scripts/dasha_calculator.py` 或 `scripts/dasha_calculator_enhanced.py`

**开源复用**:
- PyJHora `jhora/panchanga/dhasa/vimsottari.py`（AGPL，算法参考）

**预期效果**:
- 明确 Vimshottari 精度等级
- 为 `technique_registry.json` 中 `vimshottari_dasha` 补充 benchmark 证据

---

### P0.4 Ashtakavarga 完整 PAV 展开表

**目标**: 实现 Prastara Ashtakavarga（行星×宫位展开表），补齐 AV 行运评分的计算基础。

**技术方案**:
- 文件: `scripts/ashtakavarga.py`（当前 v2.1）
- 新增函数: `calc_prastara_av(birth_info)`
- 算法: 基于已有 BAV（Bhinna Ashtakavarga），对每个行星在每个宫位的贡献展开为 8 个行星（含 Asc）的单独贡献标记。PyJHora `ashtakavarga.py:get_prastara_ashtakavarga()` 可直接参考。
- 输出: 7×12×8 三维矩阵（7行星 × 12宫位 × 8贡献源）

**验证方法**:
- 与 PyJHora `prastara_ashtakavarga()` 对比 10 个案例
- 不变量检查: PAV 所有行求和 = BAV 对应行星值；PAV 所有列求和 = BAV 对应宫位值

**开源复用**:
- PyJHora `jhora/panchanga/ashtakavarga.py:get_prastara_ashtakavarga()`（AGPL 翻译）

**预期效果**:
- AV 行运评分从 "近似" 升级为 "精确"
- 为 `ashtakavarga` 子命令新增 `--prastara` 选项

---

### P0.5 Sodhita Ashtakavarga 实现

**目标**: 实现 Sodhita（减法）Ashtakavarga，用于修正 AV 吉凶判断。

**技术方案**:
- 文件: `scripts/ashtakavarga.py`
- 新增函数: `calc_sodhita_av(birth_info, prastara_av)`
- 算法: BPHS 标准 Sodhita 流程——从每个宫位的 BAV 中减去该宫位的 Saturn 贡献、Mars 贡献和 Sun 贡献（若结果为负则取0）。PyJHora `get_sodhita_ashtakavarga()` 可直接参考。
- 输出: 7×12 矩阵（Sodhita 后的每个行星-宫位值）

**验证方法**:
- 与 PyJHora `sodhita_ashtakavarga()` 对比
- 不变量: Sodhita AV ≤ 原始 BAV；Sodhita SAV ≤ 原始 SAV

**开源复用**:
- PyJHora `jhora/panchanga/ashtakavarga.py:get_sodhita_ashtakavarga()`（AGPL 翻译）

**预期效果**:
- 行运吉凶判断增加 Sodhita 修正层
- 为 `ashtakavarga` 子命令新增 `--sodhita` 选项

---

### P0.6 Kakshya 评分系统

**目标**: 实现 Kakshya（度数区间力量）评分，为 Transit 精确触发提供度数级量化。

**技术方案**:
- 新文件: `scripts/kakshya.py`
- 算法: 每个宫位分为 8 个 Kakshya（区间），每个区间由特定行星守护。行星落入某区间时，获得该区间守护行星的加持或削弱。PyJHora `kakshya.py` 有完整实现。
- 关键: Kakshya 区间划分基于行星平均运动速度（太阳30°、月亮15°等），非等分。

**验证方法**:
- 与 PyJHora `kakshya.get_kakshya_spurhta()` 对比 10 个案例
- 检查每个行星的 Kakshya 归属和力量值

**开源复用**:
- PyJHora `jhora/panchanga/kakshya.py`（AGPL 翻译）

**预期效果**:
- Transit 触发精度从 "星座级" 提升至 "度数区间级"
- 接入 `full-reading.modules.transit_kakshya`

---

## 四、P1 核心升级层（partial → covered）

> **定义**: 当前标记为 partial、代码已存在但有限制，经优化后可升级为 covered 的技法。

### P1.1 Shadbala 外部绝对值校准

**目标**: 将 Shadbala 从 "内部一致" 升级为 "外部绝对值可信"。

**技术方案**:
- 文件: `scripts/shadbala.py`
- 当前简化项:
  1. Nathonnata Bala: 二值化（白天/夜晚），应改为基于赤纬的比例计算
  2. Saptavargaja Bala: 部分子分盘近似，应改为调用 `varga.py` 实际分盘
  3. Chesta Bala: 速度分档近似，应改为基于真实速度比例的连续计算
  4. Drik Bala: 简化相位权重，应改为基于确切度数的相位力量公式
- 对标: PyJHora `shad_bala.py` 完整实现（AGPL，算法参考）

**具体修复步骤**:
1. **Nathonnata Bala**: 使用 Swiss Ephemeris 获取太阳赤纬，计算 `nathonnata_bala = sin(declination) * 标准化因子`，替代当前二值化。
2. **Saptavargaja Bala**: 调用 `divisional_charts_extended.py` 实际计算 D1/D2/D3/D7/D9/D10/D12，对每个分盘计算 dignity 得分后聚合，替代当前近似表。
3. **Chesta Bala**: 使用 Swiss Ephemeris 获取行星真实日运动速度（`swe.calc_ut()` 的 `speed` 字段），对照平均速度计算比例，替代当前分档。
4. **Drik Bala**: 实现完整相位力量公式——`aspect_strength = (180 - |actual_orb|) / 180 * base_strength`，对所有7行星的特殊相位和Rasi Drishti分别计算后聚合。

**验证方法**:
- 扩展 `benchmarks/jyotish/scripts/run_shadbala_invariants.py` 为 `run_shadbala_pyjhora_compare.py`
- 10案例 × 6种力量 × 7行星 = 420 个数值对比
- 目标: 与 PyJHora Shadbala 总分差异 ≤5%（因 Naisargika Bala 已对齐，主要差异应在 Chesta/Drik）
- 内部不变量保持 1200/1200 通过

**开源复用**:
- PyJHora `jhora/panchanga/shad_bala.py`（AGPL 算法翻译）
- jyotishganit `components/strengths.py`（MIT，已有 clone 在 references 中）

**预期效果**:
- `technique_registry.json` 中 `shadbala` 状态从 `partial` → `covered`
- full-reading 中 Shadbala 评估置信度上限解除

---

### P1.2 Bhava Chalit 完整实现

**目标**: 实现完整的 Bhava Chalit（变动宫位）行星重新分配。

**技术方案**:
- 文件: `scripts/bhava_chalit.py`（当前只有宫位计算，无行星重分配）
- 新增函数: `assign_planets_to_chalit(birth_info, house_cusps)`
- 算法: 对每个行星，比较其经度与相邻两个宫位的宫头经度。若行星距某宫头 < 阈值的 1/3，归入该宫位；否则按常规星座归属。PyJHora `bhava_chalit_chart()` 可直接参考。
- 输出: Chalit 行星分配表 + Chalit D1 图数据

**验证方法**:
- 与 PyJHora `bhava_chalit_chart()` 对比 10 个案例
- 检查每个行星的 Chalit 宫位分配

**开源复用**:
- PyJHora `jhora/panchanga/chart.py:bhava_chalit_chart()`（AGPL 翻译）

**预期效果**:
- `technique_registry.json` 中 `bhava_chalit` 状态从 `partial` → `covered`
- full-reading 中宫位分析增加 Chalit 视角

---

### P1.3 Sudarshana Chakra 传统实现

**目标**: 实现传统 Sudarshana Chakra（三参考点盘：Lagna + Chandra + Surya）。

**技术方案**:
- 新文件: `scripts/sudarshana_chakra.py`
- 当前替代方案: D1-D9-D10 三角验证（非传统 Sudarshana）
- 算法: 以 Lagna 为第1宫绘制的 D1 图 + 以 Moon 为第1宫重新排列的图 + 以 Sun 为第1宫重新排列的图。三个图中同一宫位/行星配置的一致性用于确认事件。
- 输出: 三个参考点盘 + 一致性标记

**验证方法**:
- 建立 5 个公开名人案例的三参考点盘
- 与 PyJHora `sudarshana_chakra()` 对比行星位置

**开源复用**:
- PyJHora `jhora/panchanga/chart.py:sudarshana_chakra()`（AGPL 翻译）

**预期效果**:
- `technique_registry.json` 中 `sudarshana_chakra` 状态从 `partial` → `covered`
- full-reading 中 "传统 Sudarshana" 从缺口声明变为实际输出

---

### P1.4 Tajika Yogas 完整覆盖

**目标**: 从简化规则扩展为完整的 Tajika Yoga 检测（Itasala、Ishkavala、Etc. + Vedha 阻碍逻辑）。

**技术方案**:
- 文件: `scripts/tajika.py`
- 当前: 简化规则（约 5-6 种基础 Yoga）
- 目标: 覆盖 PyJHora 的 10 种年度 Yoga 分类 + Vedha 阻碍逻辑
- 新增函数: `_detect_tajika_yogas_complete(varshaphala_data)`
- 算法翻译: PyJHora `tajika/yogas.py`（AGPL）

**具体 Yoga 列表**:
1. Itasala（友好相位）
2. Ishkavala（单向相位）
3. Vasala（无效相位）
4. Tambira（阻碍）
5. Kambira（双重阻碍）
6. Dakshina（右向）
7. Vama（左向）
8. Ubhaya（双向）
9. Vedha（穿刺阻碍）
10. Kuta（组合）

**验证方法**:
- 与 PyJHora `tajika_yogas()` 对比 10 个年运盘
- 检查每种 Yoga 的触发条件和阻碍逻辑

**开源复用**:
- PyJHora `jhora/panchanga/tajika/yogas.py`（AGPL 翻译）

**预期效果**:
- `technique_registry.json` 中 `tajika_yogas` 状态从 `partial` → `covered`
- 年运盘格局判断从高置信度上限升级为标准应期模块

---

### P1.5 Sahams 扩展至 36 种

**目标**: 从当前的 Vivah Saham 扩展为完整的 36 种 Saham 计算。

**技术方案**:
- 文件: `scripts/tajika.py`（当前只有 `calc_vivah_saham`）
- 新增函数: `calc_all_sahams(birth_info, year_lord_data)`
- 36 种 Saham 列表（标准 Tajika 体系）:
  - Vivah（婚姻）、Karma（事业）、Paradesa（ foreign）、Bandhu（兄弟姐妹）、Putra（子女）、
  - Vidya（教育）、Arogya（健康）、Marana（死亡）、Kala（时间）、Yasha（名声）等
- 每种 Saham 的公式基于特定行星经度的加减运算，参照 PyJHora `saham.py`。

**验证方法**:
- 与 PyJHora `saham.get_saham_longitude_list()` 对比 10 个案例
- 检查每种 Saham 的经度计算

**开源复用**:
- PyJHora `jhora/panchanga/tajika/saham.py`（AGPL 翻译）

**预期效果**:
- `technique_registry.json` 中 `sahams` 状态从 `partial` → `covered`
- 年运盘增加 36 个敏感点分析

---

### P1.6 Sade Sati 完整实现（含 Kantaka Shani）

**目标**: 从简化模型升级为完整的 Sade Sati + Kantaka Shani 细分阶段。

**技术方案**:
- 新文件: `scripts/sade_sati.py`（当前逻辑分散在 `jyotish_engine.py` 或文档中）
- 当前: 土星经过月亮前后星座的简化模型
- 完整实现:
  1. **Sade Sati 三阶段**: Rising（进入前星座）→ Peak（月亮星座）→ Setting（离开后星座）
  2. **Kantaka Shani**: 土星在第1/4/8/10宫时的额外压力标记
  3. **Ashtakavarga 修正**: Sade Sati 期间 Saturn 的 BAV 贡献修正压力程度
  4. **小周期**: 每个阶段内部按 Saturn 经过的 Nakshatra 细分

**验证方法**:
- 与 PyJHora `sade_sati.get_sade_sati_dates()` 对比 10 个案例
- 验证三阶段时间边界和 Kantaka Shani 标记

**开源复用**:
- PyJHora `jhora/panchanga/transit/sade_sati.py`（AGPL 翻译）

**预期效果**:
- `technique_registry.json` 中 `sade_sati` 状态从 `partial` → `covered`
- Transit 分析中 Saturn 压力评估从近似升级为精确

---

### P1.7 Pancha Mahapurusha Yoga 完整变体

**目标**: 覆盖燃烧、逆行、受克时的 Yoga 失效条件。

**技术方案**:
- 文件: `scripts/yoga_engine.py`
- 当前: 基础规则（Ruchaka/Bhadra/Hamsa/Malavya/Shasha 在 Kendra + own/exalted）
- 缺失: 失效条件——若 Yoga 主星燃烧（combust）、逆行（retrograde）、受凶星相位/合相，则 Yoga 效力减弱或失效。
- 新增函数: `_check_yoga_validity(planet, chart_data)`
- 检查项: Combustion（距 Sun < 8-15°）、Retrograde、Malefic aspects（Saturn/Mars/Rahu）、Debilitation in Navamsa

**验证方法**:
- 选择 5 个有 Pancha Mahapurusha 但主星受克的案例
- 验证 Yoga 被正确降级或取消

**开源复用**:
- PyJHora `jhora/panchanga/yoga.py` 失效条件逻辑（AGPL 参考）

**预期效果**:
- `technique_registry.json` 中 `pancha_mahapurusha` 状态从 `partial` → `covered`
- Yoga 强度评分更准确

---

## 五、P2 覆盖扩展层（新增缺失技法）

> **定义**: 当前完全无代码实现、但属于专业 Jyotish 软件标准功能的技法。

### P2.1 高级分盘: D81/D108/D144 + 自定义 D-N

**目标**: 实现 D81（Navamsamsa）、D108、D144 和自定义分盘计算。

**技术方案**:
- 文件: `scripts/divisional_charts_extended.py`（当前已扩展至 D2-D60）
- 新增函数: `calc_d81(birth_info)`, `calc_d108(birth_info)`, `calc_d144(birth_info)`, `calc_custom_division(birth_info, n)`
- 算法: D81 = D9 的 D9；D108 = D12 的 D9；D144 = D12 的 D12。PyJHora `divisional_chart()` 支持任意 D-N。

**验证方法**:
- 与 PyJHora `divisional_chart(birth_info, divisional_chart_factor=81/108/144)` 对比
- 检查行星经度映射

**开源复用**:
- PyJHora `jhora/panchanga/chart.py:divisional_chart()`（AGPL 参考）

**预期效果**:
- 分盘覆盖从 16 种扩展至 19+ 种
- 接入 `varga-full` 子命令

---

### P2.2 Bhava Bala（宫位力量）

**目标**: 实现完整的 Bhava Bala 计算。

**技术方案**:
- 新文件: `scripts/bhava_bala.py`
- 算法: Bhava Bala = 宫位主星的 Shadbala × 宫位中行星的影响 × 宫位本身的位置因素（Kendra/Trikona/Dusthana）。PyJHora `bhava_bala.py` 有完整实现。
- 依赖: 需要先完成 P1.1（Shadbala 外部校准）。

**验证方法**:
- 与 PyJHora `bhava_bala.get_bhava_balas()` 对比 10 个案例

**开源复用**:
- PyJHora `jhora/panchanga/bhava_bala.py`（AGPL 翻译）

**预期效果**:
- 宫位分析增加力量量化层
- 为 `shadbala` 子命令新增 `--bhava` 选项

---

### P2.3 额外 Dasha 系统（Dwisaptati / Shattrimsa / Dwadashottari 等）

**目标**: 实现 3-5 种常用条件性 Dasha 系统。

**技术方案**:
- 优先级排序（按实用性和开源可复用性）:
  1. **Dwisaptati Sama Dasha**（72年周期，适用于特定 Tithi 条件）
  2. **Shattrimsa Sama Dasha**（36年周期）
  3. **Dwadashottari Dasha**（112年周期，适用于特定 Nakshatra 条件）
  4. **Sthira Dasha**（固定宫位 Dasha）
- 新文件: `scripts/dwisaptati_dasha.py`, `scripts/shattrimsa_dasha.py`, `scripts/dwadashottari_dasha.py`, `scripts/sthira_dasha.py`
- 每种 Dasha 的实现模式参照现有 `ashtottari_dasha.py` / `kalachakra_dasha.py` 结构。

**验证方法**:
- 与 PyJHora 对应 Dasha 模块对比时间边界
- 条件性 Dasha 需验证触发条件判断

**开源复用**:
- PyJHora `jhora/panchanga/dhasa/*.py`（AGPL 翻译）

**预期效果**:
- Dasha 系统从 7 种扩展至 10+ 种
- 五系统 Convergence 升级为多系统 Convergence

---

### P2.4 分盘中 Yoga 识别

**目标**: 在 D9/D10/D60 等分盘中运行 Yoga 引擎。

**技术方案**:
- 文件: `scripts/yoga_engine.py`
- 当前: Yoga 引擎只接收 D1 数据
- 修改: `detect()` 函数增加 `divisional_chart_data` 参数，在分盘数据中运行相同的 Yoga 规则
- 新增函数: `detect_in_varga(birth_info, varga_name, varga_data)`
- 调用点: `jyotish_engine.py` 的 `varga-full` 子命令中，对每个分盘计算 Yoga

**验证方法**:
- 选择 5 个公开案例，在 D9 中检测 Yoga
- 与 PyJHora 分盘 Yoga 对比

**开源复用**:
- PyJHora `jhora/panchanga/yoga.py`（AGPL 参考其分盘 Yoga 调用方式）

**预期效果**:
- full-reading 中 `modules.varga_full.*.yogas` 输出分盘 Yoga
- 技法覆盖度地图中 "分盘中 Yoga 识别" 从 ❌ 变为 ✅

---

### P2.5 Transit 精确触发搜索

**目标**: 实现精确到度分的 Transit 触发搜索。

**技术方案**:
- 新文件: `scripts/transit_search.py`
- 功能: 给定时间窗口和目标配置（如 "Saturn 合相 Moon"），搜索精确发生日期。
- 算法: 在给定窗口内逐日计算 Transit 行星位置，使用二分法逼近精确合相/相位时刻。
- 输入: 本命盘 + 起始日期 + 结束日期 + 目标配置
- 输出: 精确触发日期列表 + 度数误差

**验证方法**:
- 搜索已知天文事件（如 Saturn 回归），与 NASA/JPL 数据对比
- 验证精确日期误差 < 1 天

**开源复用**:
- Swiss Ephemeris `swe.calc_ut()`（已有）
- PyJHora `transit.py`（AGPL 参考）

**预期效果**:
- Transit 预测从 "月份级" 提升至 "日期级"
- 为 `transit` 子命令新增 `--search` 选项

---

## 六、P3 质量提升层（文档、测试、CI）

### P3.1 文档与代码一致性审计

**目标**: 消除所有文档与实际代码的不一致。

**具体任务**:
1. 更新 `SKILL.md` 版本号 v6.1.8 → v6.1.12
2. 更新 `COVERAGE_AUDIT_REPORT.md` 版本号 v3.13.1 → v6.1.12
3. 修正 `quick-reference-guide.md` 错误引用（3处）
4. 清理 `docs/roadmap/jyotish_technique_coverage_map.md` 中已修复的 ❌ 标记（Darakaraka、RTN、Chara Dasha 等）
5. 统一 `technique_registry.json` 与 `feature-gap-matrix-2026.md` 的口径

**验证方法**:
- 运行 `scripts/audit_capabilities.py --mode validate`
- 人工检查 3 个关键文档的版本号和引用

---

### P3.2 Benchmark 体系扩展

**目标**: 为每个 covered/partial 技法建立可复跑的 benchmark。

**已有 Benchmark**（12轮）:
- Round 1: 本地基线
- Round 2: Swiss Ephemeris 扩展对比
- Round 3: PyJHora 对比
- Round 4: Node Mode 对比
- Round 5: Arudha/A10 对比
- Round 6: Ashtakavarga 对比
- Round 6b: Ashtakavarga 表仲裁
- Round 6c: Ashtakavarga 书例
- Round 7: Chara Dasha 对比
- Round 8: Transit 真实过境对比
- Round 9: Shadbala 不变量
- Round 10: 解释回归

**待建立 Benchmark**:
- Round 11: Vimshottari Dasha 精度（P0.3）
- Round 12: Shadbala 外部绝对值（P1.1）
- Round 13: Yoga FN/FP 收敛（P0.2）
- Round 14: PAV + Sodhita AV（P0.4-P0.5）
- Round 15: Bhava Chalit 精度（P1.2）
- Round 16: Tajika Yogas 完整覆盖（P1.4）

**验证方法**:
- 每个新 benchmark 脚本需通过 `pytest` 集成测试
- benchmark 输出保存至 `benchmarks/jyotish/outputs/` 和 `reports/`

---

### P3.3 CI/CD 质量门禁完善

**目标**: 建立自动化的 pre-commit 质量门禁。

**已有门禁**:
- `.pre-commit-config.yaml`: ruff 格式化
- `scripts/run_quality_gate.py`: compile/json/audit/pytest

**待添加门禁**:
1. **benchmark 回归测试**: 每次 commit 前自动跑关键 benchmark（Chara Dasha、Ashtakavarga、Transit），确保无精度退化。
2. **technique_registry 一致性检查**: 自动验证 registry 中引用的文件路径和命令确实存在。
3. **文档版本号同步检查**: 自动验证 `SKILL.md` / `CHANGELOG.md` / `README.md` 的版本号一致。

**验证方法**:
- 在 `.github/workflows/` 中添加 GitHub Actions workflow
- 测试: 故意提交一个破坏 Chara Dasha 的改动，验证 CI 拦截

---

### P3.4 开源项目持续监控

**目标**: 建立机制，定期扫描新出现的 Jyotish 开源项目，评估可复用性。

**当前已知项目库**:
- PyJHora (AGPL) — 算法参考金标准
- jyotishganit (MIT) — 已有 clone， strengths.py 可复用
- dashaflow (MIT) — 已适配合盘功能
- VedicAstro (MIT) — 完整 KP 系统
- vedic-calc (AGPL) — KP+Tajika+Prashna+Ashtakavarga
- vedic-astro-skills (MIT) — AI 解读 6 个 skill
- panchanga_api (开源) — 19 端点 REST API
- CNWU16/vedic-astro-skills (MIT, 161⭐) — AI 解读
- diliprk/VedicAstro (MIT, 63⭐) — 完整 KP
- rishi-ai-mcp — Sade Sati+Muhurtha+MCP 接入

**待监控渠道**:
- GitHub Topics: `jyotish`, `vedic-astrology`, `panchanga`
- PyPI 新包: `jyotish*`, `panchanga*`, `dasha*`
- arXiv: 印度占星相关算法论文

**验证方法**:
- 每季度手动或自动化扫描一次
- 新发现项目评估: 许可证、技术栈、可复用模块、精度声明

---

## 七、开源复用地图

| 目标模块 | 最佳开源来源 | 许可证 | 复用方式 | 当前状态 |
|----------|-------------|--------|---------|---------|
| Chara Dasha 共主判定 | PyJHora `_stronger_planet_new` | AGPL | 算法翻译 | 待执行 P0.1 |
| Vimshottari benchmark | PyJHora `vimsottari.py` | AGPL | 算法参考 | 待执行 P0.3 |
| PAV/Sodhita AV | PyJHora `ashtakavarga.py` | AGPL | 算法翻译 | 待执行 P0.4-P0.5 |
| Kakshya | PyJHora `kakshya.py` | AGPL | 算法翻译 | 待执行 P0.6 |
| Shadbala 完整版 | PyJHora `shad_bala.py` | AGPL | 算法翻译 | 待执行 P1.1 |
| jyotishganit strengths | jyotishganit `components/strengths.py` | MIT | 直接复用/适配 | 已有 clone |
| Bhava Chalit | PyJHora `chart.py` | AGPL | 算法翻译 | 待执行 P1.2 |
| Sudarshana Chakra | PyJHora `chart.py` | AGPL | 算法翻译 | 待执行 P1.3 |
| Tajika Yogas | PyJHora `tajika/yogas.py` | AGPL | 算法翻译 | 待执行 P1.4 |
| Sahams 36种 | PyJHora `tajika/saham.py` | AGPL | 算法翻译 | 待执行 P1.5 |
| Sade Sati 完整 | PyJHora `transit/sade_sati.py` | AGPL | 算法翻译 | 待执行 P1.6 |
| 高级分盘 D81+ | PyJHora `chart.py` | AGPL | 算法参考 | 待执行 P2.1 |
| Bhava Bala | PyJHora `bhava_bala.py` | AGPL | 算法翻译 | 待执行 P2.2 |
| 额外 Dasha | PyJHora `dhasa/*.py` | AGPL | 算法翻译 | 待执行 P2.3 |
| 分盘 Yoga | PyJHora `yoga.py` | AGPL | 算法参考 | 待执行 P2.4 |
| Transit 搜索 | PyJHora `transit.py` | AGPL | 算法参考 | 待执行 P2.5 |
| KP 完整系统 | VedicAstro (diliprk) | MIT | 直接复用/适配 | 未开始 |
| Prashna 完整 | vedic-calc (atolat) | AGPL | 算法参考 | 未开始 |

> **AGPL 复用原则**: 不直接复制代码到 MIT 仓库。阅读 AGPL 代码理解算法，用独立代码重新实现。在注释中标注算法来源和许可证。

---

## 八、验证策略总览

### 8.1 三层验证体系

| 层级 | 方法 | 适用 | 工具 |
|------|------|------|------|
| **L1 单元测试** | pytest + 不变量检查 | 每个函数 | `pytest tests/` |
| **L2 Benchmark** | PyJHora oracle 对比 | 每个核心模块 | `benchmarks/jyotish/scripts/` |
| **L3 集成验证** | full-reading 端到端 | 每次版本发布 | `scripts/jyotish_engine.py full-reading` |

### 8.2 Benchmark 通过标准

| 模块 | 通过标准 | 当前 | 目标 |
|------|---------|------|------|
| Chara Dasha | Overall ≥95% | 95.83% ✅ | ≥98% |
| Ashtakavarga | SAV=337/386 | ✅ | 保持 |
| Shadbala | 内部1200/1200 + 外部≤5%差异 | 内部✅ 外部❌ | 外部✅ |
| Transit | 340/340 Swiss匹配 | ✅ | 保持 |
| Yoga | F1 ≥95% | 95.22% ✅ | ≥96% |
| Vimshottari | 待建立 | — | ≥95% |

### 8.3 版本发布检查清单

- [ ] 所有 P0 任务 benchmark 通过
- [ ] `pytest tests/` 全通过
- [ ] `scripts/audit_capabilities.py --mode validate` 无错误
- [ ] `scripts/run_quality_gate.py` 无错误
- [ ] `SKILL.md` / `CHANGELOG.md` / `README.md` 版本号一致
- [ ] technique_registry.json 与实际代码状态一致
- [ ] GitHub 仓库已 push

---

## 九、诚实的能力评估

### 当前真实排名（纯技术，第8名左右）

| 排名 | 项目 | 领先点 |
|------|------|--------|
| 1 | PyJHora (AGPL) | 30+ Dasha、完整Shadbala、1000+ Yoga、全分盘 |
| 2 | vedic-calc (AGPL) | KP+Tajika+Prashna+Ashtakavarga 完整 |
| 3 | VedicAstro (MIT) | 完整KP系统、结构化数据 |
| 4 | jyotishganit (MIT) | 干净架构、完整测试 |
| 5 | panchanga-api (开源) | 19端点REST、300+ Yogas |
| 6 | dashaflow (MIT) | 多Dasha流、合盘 |
| 7 | vedic-astro-skills (MIT) | AI解读、6个skill |
| **8** | **yinduzhanxing (MIT)** | **中文AI解读层、技法审计系统、Yoga F1=95.22%、Chara Dasha 95.83%** |
| 9+ | 其他小项目 | — |

### 独特价值（不可替代性）

1. **中文AI解读层**: 全球唯一以中文为母语的 Jyotish AI 解读系统，覆盖从入门到专业的完整工作流。
2. **技法审计系统**: technique_registry + audit_capabilities + benchmark 的三层验证体系，确保每次解读的技法调用透明可审计。
3. **Yoga 精度**: F1=95.22% 在开源项目中属于第一梯队（PyJHora 未公开 Yoga 精度数据，但规则数更多）。
4. **模块化设计**: `jyotish_engine.py` 30+ 子命令 + `full-reading` 47 模块，结构清晰。

### 真实差距

1. **Dasha 系统**: 7种 vs PyJHora 30+ 种，差距显著。
2. **Shadbala 外部校准**: 内部一致但无绝对值对标，不能声称"完整"。
3. **分盘变体**: 只实现标准算法，无 Hora 6 变体、D3 4 变体等。
4. **Tajika 高级功能**: 缺 Panchavargiya Bala、Harsha Bala、完整 Sahams。
5. **Prashna 深度**: 缺 Sphuta、Trisphuta、数字选盘。
6. **社区与生态**: 0 Stars（GitHub），无外部贡献者，与 PyJHora 等成熟项目差距巨大。

---

*本文档基于 v6.1.12 代码实际状态编制，所有文件路径、函数名、指标均经过验证。优化方案按 P0→P1→P2→P3 顺序执行，不设定完成时间，以 benchmark 通过为唯一验收标准。*