naming-house 版本演进解析基于 CHANGELOG 看 k-skill 确定性韩文起名包的笔画来源与评分体系【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill导读本文以 packages/naming-house/CHANGELOG.md 的版本记录为骨架深入剖析 k-skill 项目中naming-house包从 0.2.0 到 0.2.1 的技术演进脉络它如何把saju-fortune的八字五行结论、hanja的标准笔画序数据、korean-stroke的谚文笔画回退以及本地显式评分权重组合成一套**确定性deterministic**的韩文起名推荐管线。读完本文你将理解每个版本变更背后的实现动机、四维评分模型的精确权重分布以及笔画数据来源Hanja 标准笔顺 vs 谚文笔画回退对最终得分和输出溯源字段的影响。一、CHANGELOG 说了什么两个版本的演进主线naming-house的版本历史非常精简仅有两个发布但恰好勾勒出该包的核心技术决策版本变更内容CHANGELOG 原文要点技术含义0.2.0新增naming-house包与技能用于基于saju 上下文、Hanja/Hangul 笔画分析与文档化评分辅助函数的确定性韩文姓名推荐确立三条数据管道八字五行、汉字笔画、谚文笔画以及本地评分器0.2.1用官方标准笔顺数据替换损坏的namefyi汉字占位逻辑使汉字候选获得逐字真实的笔画数修复笔画数据的真实性与可复现性这是 0.2.0 中hanja-stroke-order来源的实现落地从仓库现状看0.2.1 的实现证据直接对应 src/index.js 中的getHanjaStrokeProfile它不再依赖任何外部占位服务而是逐字调用hanja.getStrokes(char)获取标准笔顺字符串再以Array.from(strokeOrder).length统计笔画数。0.2.0 所承诺的确定性推荐在 src/index.js 的recommendNames排序逻辑中落实为稳定的多级排序键见下文第五节。二、包结构从 package.json 看依赖与入口packages/naming-house/package.json 定义了包的形态三个运行时依赖hanja^1.1.5标准笔顺、korean-stroke^1.1.5谚文笔画回退、saju-fortune^0.2.0八字五行上下文双入口main指向 src/index.jsCommonJS 库 APIbin.naming-house指向 src/cli.js命令行工具环境要求node 18关键词korean-name、naming、saju、stroke-count、성명학、작명定位为韩文姓名学工具。在仓库中它还以技能形式存在于 naming-house/SKILL.md通过npx -y nomadamas/k-skill0 instruct naming-house获取完整指令属于 k-skill 面向韩国用户的 utility 类技能之一。也就是说同一套推荐逻辑既可作为 npm 库/CLI 独立运行也可作为 Agent 技能被调用。三、API 概览六大导出与工具分发README.md 列出了完整导出src/index.js 末尾的module.exports与之完全一致导出职责getMissingNamingFields(input)返回缺失的必填字段按surname、birthDate、gender、candidates顺序用于 Agent 访谈式补全normalizeNamingInput(input)校验并规范化输入去空白、格式校验、preferences 归一化buildNamingContext(input)调用saju-fortune生成四柱/用神/五行走势上下文scoreNameCandidate(candidate, context, options)对单个候选打分返回四组件分数、笔画画像、解释文本recommendNames(input, options)遍历全部候选、打分、确定性排序、截断输出callNamingHouseTool(name, args)工具分发器recommend_names/score_name/interview_stateadapters暴露getHanjaStrokeProfile、getHangulStrokeProfile两个底层笔画适配器callNamingHouseTool是 CLI 与技能层共用的统一入口其内部questionForFieldsrc/index.js会针对缺失字段生成韩文追问问题如성씨를 한글로 알려주세요.这也是interview_state工具能驱动对话式收集出生信息的原因。3.1 输入校验规则可验证的硬约束从normalizeNamingInputsrc/index.js与测试用例 test/index.test.js 可以归纳出完整的校验契约surname必须是 1~3 个谚文音节HANGUL_REsurnameHanja若有值必须全为 CJK 字符birthDate必须是合法日期YYYY-MM-DD内部用 UTC 严格回验如2024-02-31会被拒绝birthTime若有值必须是合法时刻HH:mm25:00会被拒绝gender仅接受male/femalecandidates必须是非空数组每项givenName为 1~3 个谚文音节hanjaName可选全为 CJKpreferences.maxCandidates必须是 1~50 的整数超出直接抛错。四、评分模型四个组件的权重与内部算法CHANGELOG 0.2.0 强调的documented scoring helpers其完整权重表在 README.md 中给出组件分值范围含义elementBalance0-40名字五行与命理所需用神/补缺五行的匹配度strokeHarmony0-30相邻汉字笔画五行间的生克关系与整体笔画画像soundFlow0-20谚文长度、叠音、罗马字转写流畅度preferenceFit0-10偏好/避讳音节、风格标签、字义说明的匹配度总分经clamp(score, 0, 100)收敛再按excellent(85-100)、good(70-84)、fair(50-69)、weak(0-49) 分档gradeForsrc/index.js。4.1 elementBalance用神元素如何变成加分项scoreElementBalancesrc/index.js以20 分为基准起步名字五行每命中一个所需元素8 分上限 16即最多奖励两个首字五行能相生所需元素GENERATING关系如木生火4 分名字五行与所需元素构成相克OVERCOMING如木克土时每项-6 分上限 -12命中preferences.preferredElements4 分。所需元素由buildNamingContextsrc/index.js确定优先取saju.yongsin的 primary/secondary 与weakElements用神补缺逻辑并合并用户preferredElements若完全无法判断则退化为五行全取并写入balanced-saju-no-specific-needed-element限制。测试 test/index.test.js 验证了neededElements[0]一定等于yongsin.primary。4.2 strokeHarmony笔画五行生克与总格尾数scoreStrokeHarmonysrc/index.js以15 分起步相邻字符笔画五行关系相生5、比和2、相克-5、未知-2姓名总笔画数个位不为 0 或 4时3结合elementForStrokes尾数 1/2→木、3/4→火、5/6→土、7/8→金、0/9→水名字各字笔画数不重复时2若来源是谚文回退korean-stroke-hangul整体-4精度折扣。4.3 soundFlow长度、叠音与罗马字scoreSoundFlowsrc/index.js以10 分起步全名 3~4 音节4、名字两字3、无相邻叠字2、本地罗马字转写长度 3~161、命中avoidSyllables-4。其中localRomanizeKoreansrc/index.js是包内置的谚文分解转写器按初/中/终声完整映射不需要外部罗马字库。4.4 preferenceFit偏好与避讳的显式表达scorePreferenceFitsrc/index.js以5 分起步命中preferredSyllables2、风格标签匹配preferences.style2、提供meaning字义1、命中avoidSyllables-4并同步生成韩文说明如피해야 할 음절이 포함되어 감점했습니다.。五、0.2.1 的核心修复笔画数据从占位符到官方笔顺CHANGELOG 0.2.1 是本次演进的关键 commitca4c7d8用官方标准笔顺数据替换损坏的namefyi汉字占位。在 src/index.js 中getHanjaStrokeProfile的实现如下拼接姓汉与名汉组成全汉字串逐字调用hanja.getStrokes(char)取得标准笔顺字符串以字符数作为笔画数每个字生成{ char, strokes, element, source: hanja }条目element由尾数映射得出相邻字计算五行生克关系generating/overcoming/neutral/unknown任一汉字取不到笔顺时写入hanja-stroke-unavailable限制与对应 warning。测试 test/index.test.js 用同一读音、不同汉字草熙/初熙/楚熙验证了逐字真实笔画草熙→[15,10,14]、初熙→[15,8,14]、楚熙→[15,13,14]第一个 15 是姓氏鄭的笔画三个候选因此获得不同得分与排名。这直接证明了 0.2.1 修复的收益候选间的区分度来自真实的官方笔顺数据而非占位符的固定值。输出侧得分对象会携带strokeProfile.source: hanja-stroke-order与每个字符的source: hanjaREADME.md 的 Provenance 一节对此有明确约定sources数组据此追加hanja溯源标识。5.1 谚文回退路径当候选未提供hanjaName时buildStrokeProfilesrc/index.js转入getHangulStrokeProfilesrc/index.js调用korean-stroke逐字统计谚文笔画来源标记为korean-stroke-hangul并强制写入hangul-stroke-fallback-reduced-precision限制笔画精度打折。测试 test/index.test.js 验证了该路径的溯源与限制字段。六、确定性排序同样的输入永远得到同样的排名CHANGELOG 0.2.0 中的 deterministic 一词在recommendNamessrc/index.js中体现为严格的多级稳定排序键score降序elementBalance降序同分时优先五行匹配strokeHarmony降序全名按韩文localeCompare(ko)升序最后按候选原始index升序兜底。recommendNames返回{ input, context, recommendations, limitations, sources }每个推荐项带rank序号并按maxCandidates默认 10范围 1~50截断。测试 test/index.test.js 连续调用两次并断言deepEqual结果完全一致从测试层面锁定了确定性契约。七、CLI 用法不写代码也能跑推荐全局安装README.mdnpm install -g naming-house本地开发调试仓库内npm install npm run test --workspace naming-houseCLI 调用示例src/cli.js 的--tool/--input-json参数解析naming-house --tool recommend_names --input-json {surname:김,birthDate:2024-05-18,birthTime:09:20,calendar:solar,gender:female,candidates:[{givenName:서아,hanjaName:瑞雅}]}CLI 还支持细粒度参数覆盖--surname-hanja、--birth-time、--gender、--birth-city、--max-candidates、--candidate-json、--candidates-json、--given-name/--hanja-name等src/cli.js。score_name工具配合--candidate-json可单独给一个候选打分结果统一以格式化 JSON 输出到 stdout错误信息走 stderr 并设置非零退出码。CLI 测试见 test/index.test.js。八、限制与边界设计上明确不做什么README.md 的 Limitations 一节与测试共同划定了包的边界属于文化参考性建议不认证官方인명용 한자、不保证法律上的姓名合法性、不涉及 불용문자也不对命运/健康/财务/法律后果做任何承诺hanja-stroke-order是官方笔顺序列的笔画数不是《康熙字典》原形笔画数也不是81 数理四格计算农历日期不支持calendar: lunar会按saju-fortune的拒绝策略直接报错lunar calendar conversion is not supported测试见 test/index.test.js使用前须用经过验证的 만세력万年历换算为calendar: solar缺少出生时辰时saju-fortune的시주限制会透传到limitations输出测试见 test/index.test.js包以本地/全局 npm 包形式运行不提供 MCP 服务端或代理。结语从 CHANGELOG 的两行记录出发可以看到naming-house的版本演进背后是一套边界清晰、可测试、可溯源的实现0.2.0 确立了五行上下文 笔画分析 显式评分权重的确定性管线0.2.1 则把其中最关键的汉字笔画数据从占位符升级为官方笔顺真实计数并通过逐字source: hanja溯源让每次打分都可复现、可解释。如果你需要在此基础上做二次开发或验证行为建议从 src/index.js 的四个score*函数与 test/index.test.js 的 14 个测试用例入手——它们共同构成了这套分数即文档的起名系统的完整契约。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考