vadar/bazi_translation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move Nexa contract checker to standalone skill

Browse Source
This commit is contained in:
zfusx
2026-06-03 22:30:35 +08:00
parent cd10c418cf
commit 073d099c3b
6 changed files with 5 additions and 515 deletions
Download Patch File Download Diff File Expand all files Collapse all files
references/nexa-bazi-contract.md
-70
View File
@@ -1,70 +0,0 @@
# Nexa 八字命名契约
本文件是 Nexa 八字系统的程序员命名契约。目标不是翻译给用户看，而是让 API、JSON、prompt 变量、模块 key、测试数据和文档中的八字命理词汇保持一致。
## 适用范围
- Provider / BFF / frontend API 字段。
- JSON schema、测试 fixture、调试数据。
- Prompt 变量、Context Vault、fallback schema。
- 模块 key、SSE path、registry key。
- 代码中的函数、变量、类名和枚举名。
## 分层原则
| 层级 | 命名风格 | 示例 | 说明 |
|---|---|---|---|
| API / JSON 字段 | `snake_case` | `day_master`, `ten_god_label` | 对外和跨语言最稳定 |
| 模块 key / registry key | `snake_case` | `daily_overview`, `monthly_luck_tag` | 已发布 key 需要迁移策略 |
| Python 字段/变量 | `snake_case` | `day_master_stem` | 跟 Python 社区一致 |
| JS/TS 局部变量 | `camelCase` | `dayMasterStem` | 仅限局部代码，不用于 JSON contract |
| Type / Class / Enum | `PascalCase` | `HeavenlyStem`, `EarthlyBranch`, `TenGod` | 类型名 |
| UI 中文 | 简体中文 | `日主`, `十神`, `流日` | 面向用户 |
| 英文显示名 | 标准术语 | `Day Master`, `Ten Gods`, `Annual Luck` | 面向英文 UI/文档 |
## Nexa 推荐字段
| 中文概念 | 推荐 API/JSON 字段 | Type/Enum | 说明 |
|---|---|---|---|
| 八字命盘 | `bazi_chart` | `BaziChart` | 完整排盘结构 |
| 四柱 | `pillars` | `Pillars` | 包含 year/month/day/hour |
| 年柱 | `year_pillar` | `Pillar` | 不要写 `year_column` |
| 月柱 | `month_pillar` | `Pillar` | 不要写 `month_column` |
| 日柱 | `day_pillar` | `Pillar` | 不要写 `day_column` |
| 时柱 | `hour_pillar` | `Pillar` | 不要写 `time_column` |
| 日主 | `day_master` | `DayMaster` | 可表示完整日主，如 `辛金` |
| 日主天干 | `day_master_stem` | `HeavenlyStem` | 只表示天干，如 `辛` |
| 天干 | `heavenly_stem` | `HeavenlyStem` | JSON 字段用 snake_case |
| 地支 | `earthly_branch` | `EarthlyBranch` | JSON 字段用 snake_case |
| 藏干 | `hidden_stems` | `HiddenStem` | list 字段用复数 |
| 十神 | `ten_god` | `TenGod` | 单个十神 |
| 十神 ID | `ten_god_label` | `TenGodLabel` | 若已上线为数字 ID，可保留但要写清映射 |
| 主导十神 | `dominant_ten_god` | `TenGod` | 不要写 `dominant_deity` |
| 五行 | `element` / `five_elements` | `FiveElement` | 单个用 `element`，集合用 `five_elements` |
| 五行强度 | `element_strengths` | `ElementStrengths` | map: wood/fire/earth/metal/water |
| 喜用元素 | `favorite_element` | `FiveElement` | Nexa 内部可用 favorite；若对齐通用词表可映射为 favorable |
| 第一喜用元素 | `primary_favorite_element` | `FiveElement` | 不要写 `Primary_Favorite_Element` |
| 第二喜用元素 | `secondary_favorite_element` | `FiveElement` | 不要写 `Secondary_Favorite_Element` |
| 用神 | `useful_god` | `UsefulGod` | 高阶概念，不等同喜用元素 |
| 大运 | `luck_pillar` | `LuckPillar` | 十年运柱 |
| 流年 | `annual_luck` | `AnnualLuck` | 避免和本命年柱混淆 |
| 流月 | `monthly_luck` | `MonthlyLuck` | 月运 |
| 流日 | `daily_luck` | `DailyLuck` | 日运 |
| 流日干支 | `flow_day_ganzhi` | `StemBranch` | 若已上线可保留；新字段建议 `daily_stem_branch` |
| 合冲刑害破 | `branch_relationship` | `BranchRelationship` | 不要混用 astrology/astral 命名 |
| 合盘 | `bazi_synastry` | `BaziSynastry` | 与占星 synastry 区分时加 `bazi_` 前缀 |
## 已发布字段处理
已发布 API 或前端依赖字段不能无迁移直接改名。处理顺序：
1. 标记为 `compat`：旧字段继续读取。
2. 新增推荐字段：例如同时返回 `day_master_stem`。
3. 在文档中声明旧字段 deprecated。
4. 前端/BFF 迁移完成后，再删除旧字段。
审查时不要只说“改名”。要说明影响面：API、fixture、prompt、前端 path、SSE key、数据库列、测试断言。
## 不做向量判断
本契约用于程序员纠错，必须可重复、可解释、可进入 CI。不要用向量相似度决定字段是否违规。向量搜索最多用于发现候选混名，最终仍必须落回本契约或 `nexa-forbidden-names.md`。
references/nexa-forbidden-names.md
-38
View File
@@ -1,38 +0,0 @@
# Nexa 禁用/兼容命名表
本表供 `scripts/check_nexa_bazi_contract.py` 读取。`error` 表示新代码不应出现；`warn` 表示需要迁移或人工确认；`review` 表示可能是已发布兼容字段，改动前必须查影响面。
| severity | current | preferred | concept | reason |
|---|---|---|---|---|
| error | Day_Master | day_master | 日主 | Nexa JSON/API/prompt 字段使用 snake_case |
| error | DayMaster | day_master | 日主 | JSON/API 字段不要用 PascalCase 或拼接式 camel |
| error | DayMaster_Stem | day_master_stem | 日主天干 | mixed case 不适合接口契约 |
| error | dayMasterStem | day_master_stem | 日主天干 | JSON/API 字段使用 snake_case；JS 局部变量除外 |
| error | Primary_Favorite_Element | primary_favorite_element | 第一喜用元素 | mixed case 不适合接口契约 |
| error | Secondary_Favorite_Element | secondary_favorite_element | 第二喜用元素 | mixed case 不适合接口契约 |
| error | Favorite_Element | favorite_element | 喜用元素 | mixed case 不适合接口契约 |
| error | Element_Strengths | element_strengths | 五行强度 | mixed case 不适合接口契约 |
| error | Dominant_Deity | dominant_ten_god | 主导十神 | 十神不是 deity |
| error | dominant_deity | dominant_ten_god | 主导十神 | 十神不是 deity |
| error | deity | ten_god | 十神 | 接口字段不要用 deity 表示十神 |
| error | useGod | useful_god | 用神 | 不要把 Useful God 写成动词短语 |
| error | usefulGod | useful_god | 用神 | Nexa JSON/API 字段使用 snake_case |
| error | primary_useful_god | primary_favorite_element | 喜用元素 | 喜用元素不等同用神 |
| error | dayOwner | day_master | 日主 | 日主标准术语是 Day Master |
| error | dayLord | day_master | 日主 | 日主标准术语是 Day Master |
| error | skyStem | heavenly_stem | 天干 | 标准术语是 Heavenly Stem |
| error | groundBranch | earthly_branch | 地支 | 标准术语是 Earthly Branch |
| error | fortuneColumn | luck_pillar | 大运 | 大运是 Luck Pillar，不是 column |
| error | fortune_column | luck_pillar | 大运 | 大运是 Luck Pillar，不是 column |
| error | big_luck | luck_pillar | 大运 | 新接口使用 luck_pillar |
| error | annual_pillar | annual_luck | 流年 | 避免和本命 year_pillar 混淆 |
| error | monthly_pillar | monthly_luck | 流月 | 避免和本命 month_pillar 混淆 |
| error | daily_pillar | daily_luck | 流日 | 避免和本命 day_pillar 混淆 |
| warn | flowing_year | annual_luck | 流年 | 直译味过重，优先 annual_luck |
| warn | flowing_month | monthly_luck | 流月 | 直译味过重，优先 monthly_luck |
| warn | flowing_day | daily_luck | 流日 | 若表示干支请用 daily_stem_branch |
| warn | daily_fortune_insights | daily_luck_insights | 日运洞察模块 | 新八字模块 key 优先用 luck；已发布则兼容迁移 |
| review | key_astral_event | key_bazi_event | 今日关键八字事件 | 八字模块避免 astral；若已发布需迁移 |
| review | astral_event | bazi_event | 八字事件 | astral 属占星语境，八字事实链不要混用 |
| review | provider_visual_tags | provider_bazi_tags | Provider 标签 | 若标签全是八字来源，名称应体现 bazi |
| review | provider_visual_tag_detail | provider_bazi_tag_detail | Provider 标签详情 | 若标签全是八字来源，名称应体现 bazi |
references/nexa-naming-rules.md
-78
View File
@@ -1,78 +0,0 @@
# Nexa 八字程序员命名规则
## 最高优先级
1. JSON/API 字段使用 `snake_case`。
2. 八字体系字段不得混入占星术语，除非该模块确实属于占星产品线。
3. 十神不要翻译成 `deity`、`god`、`star` 作为接口字段。对外字段用 `ten_god`，用户文案可写中文十神名。
4. `favorite_element` 是 Nexa 喜用元素字段；`useful_god` 是用神字段。两者不要互换。
5. 已上线字段必须走兼容迁移，不做无提示破坏性重命名。
## 推荐命名
| 类别 | 推荐 | 避免 | 说明 |
|---|---|---|---|
| 日主 | `day_master` | `Day_Master`, `dayOwner`, `self_lord` | API/JSON 用 snake_case |
| 日主天干 | `day_master_stem` | `DayMaster_Stem`, `dayMasterStem` in JSON | JSON 禁止 mixed case |
| 主导十神 | `dominant_ten_god` | `Dominant_Deity`, `dominant_star` | 十神不是 deity |
| 喜用元素 | `primary_favorite_element` | `Primary_Favorite_Element`, `primary_useful_god` | 喜用元素不等同用神 |
| 五行强度 | `element_strengths` | `Element_Strengths`, `energy_strengths` | 明确是五行强度 |
| 大运 | `luck_pillar` | `fortune_column`, `big_luck` | 八字术语是 Luck Pillar |
| 流年 | `annual_luck` | `flowing_year`, `annual_pillar` | 避免和本命年柱混淆 |
| 流日 | `daily_luck` | `flow_day` when used as event concept | 若表示干支可写 `daily_stem_branch` |
| 刑冲合害 | `branch_relationship` | `astral_event` | 八字地支关系不是占星事件 |
## 模块 key
模块 key 是前后端契约，不是标题文案。命名要表达数据职责：
| 当前/候选 | 建议 | 备注 |
|---|---|---|
| `daily_overview` | 保留 | 已清晰，非术语问题 |
| `monthly_luck_tag` | 保留 | 已上线可保留 |
| `daily_luck_mantra` | 保留 | 产品文案 key，可保留 |
| `daily_fortune_insights` | `daily_luck_insights` | 新增模块建议用 luck；已上线则兼容迁移 |
| `key_astral_event` | `key_bazi_event` 或 `key_energy_event` | 八字首页避免 astral |
| `home_image_module` | 保留或改为业务中性名 | 不属于术语违规 |
## Prompt 变量
Prompt 变量也属于接口契约，不应出现临时写法：
```yaml
destiny_symbols_context:
birth_date: "1999-09-09"
day_master_stem: "辛"
primary_favorite_element: "金"
secondary_favorite_element: "水"
element_strengths:
wood: 10
fire: 35
earth: 12
metal: 22
water: 8
```
不要写：
```yaml
DayMaster_Stem: "辛"
Primary_Favorite_Element: "金"
Dominant_Deity: "七杀"
```
## 审查输出
输出必须具体到替换建议：
```text
path/file.md:14 DayMaster_Stem -> day_master_stem [error]
原因：Nexa JSON/prompt contract 使用 snake_case；日主天干字段为 day_master_stem。
```
如果是已发布字段，输出迁移提醒：
```text
key_astral_event -> key_bazi_event [review]
原因：八字模块不应使用 astral；若前端已依赖，先新增新 key 并保留旧 key 兼容。
```