姓名学全维报告
> 零外部依赖声明：本技能不需要任何 API Key、不访问网络、不需要数据库或账号。笔画/读音字典、五格公式与数理规则表全部内置于技能包，运行时仅用 Python 3 标准库执行本地确定性计算。
从「一个姓氏（加一个出生时刻）」到「一册可交付的姓名学报告 + 一张候选名排名榜」的全链路技能。
市面上起名工具的毛病有两处：笔画靠模型记忆（容易错），结论靠自由发挥（无法追问）。本技能把这两处都钉死：笔画与读音由内置字典查出，五格与数理由确定性脚本算出，候选名从按字义五行分类的字库里筛出来，每一步都写得出依据。
一、何时使用与调用示例
何时使用
- 用户给出姓氏（可能已有名字），要求分析姓名好坏 / 看五格数理 / 看名字吉凶
- 用户要求起名 / 取名 / 改名，尤其是希望结合生辰八字补五行
- 用户要求输出姓名学报告 / 起名报告 / 姓名分析报告
- 用户问「叫 XXX 这个名字好不好」「我家孩子缺什么，起什么名」
调用示例（照说即可）
标准调用 —— 姓 + 出生时刻 + 性别，其余全自动：
男孩，姓王，2022年农历3月12日8点出生，帮我起名并出一份姓名学报告
女孩，姓李，2023年5月20日出生，叫李慕白好不好
我姓陈，2018年9月1日中午12点生的男孩，看看现在的名字，再推荐几个新的
姓张，男孩，公历1995年5月29日5点半生，起名
描述方式随便换，都认：公历／农历、「早上八点」／「8:00」／「辰时」都能解析；农历闰月说一句「闰月」即可。只想看现有姓名不要候选名，说「只分析这个名字，不用推荐」；只要候选名，说「只要起名」。
示例输出（例一姓氏「王」· 2022 年农历三月十二 8:00 · 男，供参照）：
| 项 | 结果 |
|---|---|
| 姓 | 王（康熙 4 画 / 简体 4 画 · wáng · 阳平） |
| 四柱 | 壬寅 · 甲辰 · 乙未 · 庚辰 |
| 日主 | 乙木（印比合计 51.9%，中和）→ 喜用 火 · 土，以流通为要 |
| 五格（以推荐名「王域熙」为例） | 天格 5 · 人格 15 · 地格 25 · 外格 15 · 总格 29 |
| 三才配置 | 土土土 → 大吉 |
| 候选名前三 | 王域熙 · 王嵩焰 · 王嵩焱（各附数理 / 三才 / 五行 / 音韵评分） |
完整报告则按七步 SOP 产出：定字 → 排五格 → 查数理 → 判三才 → 论五运 → 联动八字 → 候选名排名 → 免责声明。
二、核心原则（铁律）
- 笔画与读音必须来自脚本，不得手工推算。每个字的康熙笔画、简体笔画、拼音、声调一律以
scripts/data/strokes_table.py的输出为准。脚本算错是脚本的问题，绝不可以用「记忆中的笔画表」覆盖脚本结果。确有必要修正时，用--stroke 字=笔画显式指定，并在报告中标注「手工指定」。 - 五格公式、数理吉凶、三才判定都写在规则表里，见
scripts/data/tables.py。报告中每条结论都要注明依据（数理值 + 吉凶 + 三才生克链）。 - 区分「康熙笔画」与「简体笔画」两个口径。姓名学五格通行取康熙笔画，但坊间也有用简体笔画的派别。默认走康熙（
--stroke-mode kangxi），报告必须同时列出两个口径，让用户可以对照核验。切换口径时全盘重算。 - 八字喜用神的推导口径要写明。喜用五行由内置历法引擎排四柱后，按「扶抑为主、兼顾救缺」推出：印比合计 < 45% 判身弱，喜印与比劫；> 60% 判身旺，喜食伤、财、官杀；居间判中和，以流通为要。再补入五行缺失/最弱者。报告中必须把这条推导链写出来，不得只给一个「喜用：土金」。
- 候选名必须来自内置字库，且给出理由。字库按「字义五行」分类（见
scripts/data/name_chars.py）。注意「字义五行」与「数理五行」（由笔画尾数推出）是两个不同口径，报告中要并列说明，不得混为一谈。 - 不回避不确定。字库未收录的字、读音缺失的字、笔画口径有争议的字，都要显式标注，不得静默按默认值处理。
- 报告末尾必须保留免责声明（民俗文化性质，不构成人生 / 金融 / 医疗 / 婚恋决策依据）。
三、标准工作流（SOP）
第 1 步｜收集信息
向用户确认：
- 姓（单姓或复姓）
- 名（已有名字则用于分析；只想起名可省略）
- 性别（筛选候选名字性：男名 / 女名 / 中性）
- 出生时刻（可选，但强烈建议提供——没有它就无法联动八字喜用神；公历/农历、闰月、只给「辰时」都可）
> 信息不全时一次性列出所缺项，不要逐条追问。
第 2 步｜测算
python3 "<skill_dir>/scripts/name_calc.py" \
--surname 王 --given 思远 --gender male \
--birth 2022-04-12 --time 08:00 --calendar lunar \
--count 10 --pretty
- 只分析现有姓名：给
--given，把--count设为 0 - 只想起名：不给
--given，给--count 10 - 切换笔画口径：
--stroke-mode modern - 手工指定笔画：
--stroke 慕=15（可多次） - 农历闰月：
--calendar lunar --leap
输出为结构化 JSON，含：bazi（四柱 / 日主 / 五行分布）、favor（喜用五行与推导链）、analysis（逐字笔画读音、五格、三才、五运）、candidates（候选名排名，含逐项评分明细）。
第 3 步｜按七步方法论推演
读取 references/methodology.md，逐步产出：
- 定字 —— 逐字取康熙笔画、简体笔画、拼音、声调、字义五行（附数据来源说明）
- 排五格 —— 天格 / 人格 / 地格 / 外格 / 总格，并说明每个格的取法与含义
- 查数理 —— 五格各自的八十一数理吉凶（>81 者减 80），标注别称与简断
- 判三才 —— 天人地三才五行的生克关系，逐条给出推理链（含通关化解），收敛为一个吉凶等级
- 论五运 —— 成功运 / 基础运 / 社交运 / 总运，由格与格的生克推出
- 联动八字（有出生时刻时）—— 四柱 → 五行分布 → 日主扶抑 → 喜用神 → 忌神；说明该姓名在五行上是「补」还是「耗」
- 候选名 —— 从字库筛出补益喜用五行的字，按「数理 + 三才 + 五行补益 + 音韵 + 搭配」综合评分排序，给出前 10 名及推荐理由
术语与规则速查见 references/rules-tables.md。
第 4 步｜生成 HTML 报告
- 样式与结构参照
templates/sample_report.html：完整复用其中的<style>块与 class 体系。 - 硬规定：
- 每个字的笔画、拼音、声调、字义五行必须逐字列出，并标注「康熙笔画 / 简体笔画」两个口径
- 五格必须用卡片阵列呈现，每格带数理值 + 吉凶色标 + 五行标识 + 别称 + 简断
- 三才配置必须给出完整生克链（天→人、地→人、天→地），再给结论
- 候选名必须用带评分的排行表呈现，每名列出五格数理、三才、五行补益、音韵、总分
- 内容全部替换为当前案例的数据，一节都不省略（含免责声明）。
- 输出单文件自包含 HTML（CSS 内联、无外部依赖、无 CDN），保存到用户指定路径；用户未指定时保存到工作目录的
姓名学报告-<姓名>.html。 - 交付后必须调用
present_files打开预览。
第 5 步｜交付
在对话中先给一段结论速览（逐字笔画、五格、三才、数理吉凶、喜用五行、推荐名前三），再附 HTML 报告。
四、脚本速查
| 用途 | 命令 |
|---|---|
| 分析现有姓名 | python3 scripts/name_calc.py --surname 王 --given 思远 --gender male --pretty |
| 只起名（不带八字） | python3 scripts/name_calc.py --surname 王 --gender female --count 10 |
| 起名 + 八字联动 | ... --surname 王 --gender male --birth 2022-04-12 --time 08:00 --calendar lunar --count 10 |
| 农历闰月 | ... --calendar lunar --leap |
| 简体笔画口径 | ... --stroke-mode modern |
| 手工指定笔画 | ... --stroke 慕=15 --stroke 皞=15 |
| 重建笔画/读音字典 | python3 tools/build_strokes.py（需 Unihan 数据，仅维护者使用） |
依赖已内置（data/ 与 vendor/），纯 Python，无需 pip 安装，不联网。
五、输出规范
- 语言：与用户输入语言一致（默认简体中文）
- 术语：保留传统姓名学术语（天格、人格、地格、外格、总格、三才、数理、别称、字义五行、数理五行）
- 数字：每一个数理值都要标注对应的八十一数理序号（>81 时注明归约过程）
- 可视化：五格用卡片阵列，三才用生克链 + 结构图，候选名用排行表带星级
- 免责声明：固定保留，不得删除
六、边界
- 本技能提供传统民俗文化范畴的推演演示，不具备现代科学意义上的预测效力。
- 笔画数据依据 Unicode Unihan 的康熙部首索引推导，与坊间个别《姓名学笔画表》可能有一到两画的出入；报告会同时给出简体笔画口径，并支持
--stroke手工覆盖，便于核验。 - 三才配置判定由五行生克规则推导，报告会给出完整生克链；与部分坊间《三才配置表》在个别组合上可能相差一级。
- 字库为人工整理的常用起名用字（约 250 字），非穷尽全集；库外字会标注「字义五行未收录」，此时以数理五行参与评分。
- 不做真太阳时校正；未提供出生地时，八字按北京时间处理，报告中会注明。
