@timmy_hu/chinese-kinship-title

v1.0.0

Published

3 days ago

计算中国家庭亲戚之间的正确称呼，支持多层关系链推导

0High
0Medium
0Low

timmy_hu

kinship chinese family title middleware agent tool

中国亲戚称呼计算器 (Chinese Kinship Title Calculator)

插件简介

计算中国家庭亲戚之间的正确称呼，支持多层关系链推导。涵盖父系、母系、姻亲、堂表亲等 100+ 种 亲戚关系。

示例：

爸爸的爸爸 → 爷爷
妈妈的弟弟 → 舅舅
爸爸的哥哥的老婆 → 伯母
老公的妈妈 → 婆婆
哥哥的儿子 → 侄子

适用场景

🧧 过年走亲戚不知道怎么叫人
👨‍👩‍👧‍👦 教孩子认识家庭亲戚关系
📚 学习中国家庭称谓文化
🤖 智能体需要理解和回答亲戚称呼问题
💬 聊天机器人需要处理家庭关系话题

目录结构

chinese-kinship-title/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 项目配置
├── README.md                    # 本文件
├── SKILL.md                     # 技能说明（兜底入口）
├── src/
│   ├── schemas/
│   │   └── config.schema.ts     # 配置 Schema（TypeScript 参考）
│   └── shared/
│       └── chinese-kinship-title.types.ts  # 类型定义
├── resources/
│   └── skills/
│       └── chinese-kinship-title/
│           ├── SKILL.md         # Skill 资源
│           └── skill.json       # Skill 清单
├── scripts/
│   ├── sdk-shim.js              # SDK 兼容层
│   ├── check-plugin.js          # 自检脚本
│   ├── run-skill.js             # Skill 运行脚本
│   ├── invoke-tool.js           # 工具调用脚本
│   └── package-zip.js           # Zip 打包脚本
└── examples/
    ├── skill-input.example.json # 计算称呼示例
    ├── explain-input.example.json # 解释称呼示例
    └── list-input.example.json  # 列出称呼示例

安装方式

npm 方式

# 1. 安装依赖
npm install

# 2. 运行自检
npm run check

# 3. 发布到 npm
npm publish --access public --registry https://registry.npmjs.org/

# 4. 在 XpertAI 平台安装
# 通过平台 API 或管理后台安装 @timmy_hu/chinese-kinship-title

zip 方式

# 1. 安装依赖
npm install

# 2. 运行自检
npm run check

# 3. 打包 zip
npm run package:zip

# 4. 上传到 XpertAI 平台
# 通过平台 API 或管理后台上传 chinese-kinship-title.zip

配置项说明

本插件不需要外部配置，所有称呼数据内置在代码中。

预留扩展配置（未来版本）：

dialect: 方言偏好（普通话/粤语/闽南语/客家话/吴语）
region: 地区偏好（大陆/台湾/香港/海外华人）

Agent Middleware 工具列表

本插件通过 Agent Middleware 暴露 3 个工具：

1. calculate_kinship_title（计算亲戚称呼）

描述： 计算中国家庭亲戚之间的正确称呼。输入关系链描述，返回正确的中文称呼。

输入参数：

{
  "relationshipChain": "爸爸的爸爸"
}

输出示例：

{
  "success": true,
  "input": "爸爸的爸爸",
  "title": "爷爷",
  "alternatives": ["祖父", "阿公"],
  "chain": "f.f",
  "chainExplanation": "爸爸的爸爸",
  "note": "爸爸的爸爸",
  "fullSentence": "爸爸的爸爸 是 爷爷",
  "parsedSegments": ["爸爸", "爸爸"]
}

支持的关系词：

直系：爸爸/父亲、妈妈/母亲、老公/丈夫、老婆/妻子、儿子、女儿
同辈：哥哥/兄、弟弟/弟、姐姐/姊、妹妹/妹
复合词：爷爷、奶奶、外公、姥爷、外婆、姥姥、伯父、叔叔、姑妈、舅舅、姨妈、嫂子、弟妹、姐夫、妹夫、侄子、外甥、孙子、外孙、儿媳妇、女婿、堂哥、表弟、表姐、表妹、公公、婆婆、岳父、岳母等

2. explain_kinship_title（解释亲戚称呼）

描述： 解释一个中国亲戚称呼的含义和关系链。

输入参数：

{
  "title": "舅舅"
}

输出示例：

{
  "success": true,
  "input": "舅舅",
  "title": "舅舅",
  "possibleRelationships": [
    {
      "chain": "m.ob",
      "explanation": "妈妈的哥哥",
      "note": "妈妈的哥哥",
      "fullSentence": "妈妈的哥哥 → 舅舅"
    },
    {
      "chain": "m.yb",
      "explanation": "妈妈的弟弟",
      "note": "妈妈的弟弟",
      "fullSentence": "妈妈的弟弟 → 舅舅"
    }
  ],
  "totalMatches": 2
}

3. list_kinship_titles（列出所有称呼）

描述： 列出中国亲戚称呼计算器支持的所有称呼和关系。可按分类筛选。

输入参数：

{
  "category": "paternal"
}

分类选项：

all: 全部（默认）
basic: 基础关系
paternal: 父系亲属
maternal: 母系亲属
spouse: 姻亲
cousin: 堂表亲
descendant: 晚辈

输出示例：

{
  "success": true,
  "category": "paternal",
  "totalEntries": 15,
  "entries": [
    {
      "chain": "f.f",
      "title": "爷爷",
      "note": "爸爸的爸爸",
      "alternatives": ["祖父", "阿公"]
    },
    {
      "chain": "f.m",
      "title": "奶奶",
      "note": "爸爸的妈妈",
      "alternatives": ["祖母", "阿婆"]
    }
  ]
}

Skill 兜底运行说明

当平台无法直接调用 Agent Middleware Tool 时，可通过 Skill 脚本间接运行：

何时使用 SKILL.md

平台安装后 skills、mcpServers、apps 显示为空
智能体编排中未出现本插件的中间件工具
需要通过命令行直接测试插件功能

运行命令

# 计算称呼（使用示例文件）
node scripts/run-skill.js examples/skill-input.example.json

# 计算称呼（直接传入）
node scripts/run-skill.js "爸爸的爸爸"

# 计算称呼（JSON 格式）
node scripts/run-skill.js '{"action": "calculate", "relationshipChain": "妈妈的弟弟的老婆"}'

# 解释称呼
node scripts/run-skill.js examples/explain-input.example.json

# 列出称呼
node scripts/run-skill.js examples/list-input.example.json

查看输出

脚本输出标准 JSON 格式，包含 success、title、alternatives、chain、fullSentence 等字段。

错误处理

无法识别的关系词：检查拼写，使用支持的关系词
未找到对应称呼：关系链可能过于偏远，尝试缩短
输入为空：提供有效的关系链描述

scripts 目录说明

| 脚本文件 | 用途 | 命令示例 | |---------|------|---------| | sdk-shim.js | SDK 兼容层，本地运行时 mock @xpert-ai/plugin-sdk | 自动加载 | | check-plugin.js | 自检脚本，验证插件结构和导出 | npm run check | | run-skill.js | Skill 运行脚本，执行插件工具 | npm run skill:run | | invoke-tool.js | 工具调用脚本，按工具名调用 | npm run tool:invoke | | package-zip.js | Zip 打包脚本（zip 安装方式） | npm run package:zip |

版本与 API 兼容说明

Node.js: 20+
@langchain/core: ^0.3.70（使用 tool() 从 @langchain/core/tools）
@nestjs/common: ^10.0.0
reflect-metadata: ^0.2.0
zod: ^3.23.0（v3 兼容写法）
@xpert-ai/plugin-sdk: ^3.14.0（peerDependency，由平台宿主提供）

本地运行说明：

本地开发环境可能未安装 @xpert-ai/plugin-sdk
所有本地脚本（check-plugin.js、run-skill.js、invoke-tool.js）在加载插件入口前自动加载 scripts/sdk-shim.js
sdk-shim.js 提供 AgentMiddlewareStrategy、STRATEGY_META_KEY、AGENT_MIDDLEWARE_STRATEGY 的最小 mock 实现
确保本地自检和 Skill 运行不因缺少宿主 SDK 而失败

首次运行顺序

安装依赖：npm install
运行自检：npm run check（必须全部通过）
测试工具：npm run tool:invoke（查看可用工具）
测试 Skill：npm run skill:run（验证计算功能）
发布或打包：
- npm 方式：npm publish --access public --registry https://registry.npmjs.org/
- zip 方式：npm run package:zip
安装到平台：通过 XpertAI 平台 API 或管理后台安装

禁止跳过自检直接发布或上传！

入参说明

calculate_kinship_title

| 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | relationshipChain | string | 是 | 关系链描述，用"的"连接各层关系 |

explain_kinship_title

| 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | title | string | 是 | 要查询的称呼名称 |

list_kinship_titles

| 参数 | 类型 | 必填 | 默认值 | 说明 | |-----|------|-----|-------|------| | category | string | 否 | all | 分类筛选 |

返回值说明

成功响应

{
  "success": true,
  "input": "输入的原始文本",
  "title": "计算出的称呼",
  "alternatives": ["别称1", "别称2"],
  "chain": "关系链代码",
  "chainExplanation": "关系链中文解释",
  "note": "备注说明",
  "fullSentence": "完整句子",
  "parsedSegments": ["解析后的关系词数组"]
}

失败响应

{
  "success": false,
  "input": "输入的原始文本",
  "error": "错误信息",
  "suggestion": "修复建议"
}

调用示例

示例 1：计算多层关系

node scripts/invoke-tool.js calculate_kinship_title '{"relationshipChain": "爸爸的哥哥的老婆"}'

输出：

{
  "success": true,
  "input": "爸爸的哥哥的老婆",
  "title": "伯母",
  "alternatives": ["大娘", "大妈"],
  "chain": "f.ob.w",
  "fullSentence": "爸爸的哥哥的老婆 是 伯母"
}

示例 2：解释称呼

node scripts/invoke-tool.js explain_kinship_title '{"title": "嫂子"}'

输出：

{
  "success": true,
  "input": "嫂子",
  "title": "嫂子",
  "possibleRelationships": [
    {
      "chain": "ob.w",
      "explanation": "哥哥的妻子",
      "note": "哥哥的妻子",
      "fullSentence": "哥哥的妻子 → 嫂子"
    }
  ],
  "totalMatches": 1
}

示例 3：列出母系称呼

node scripts/invoke-tool.js list_kinship_titles '{"category": "maternal"}'

常见错误和处理方式

| 错误 | 原因 | 处理方式 | |-----|------|---------| | 无法识别的关系词 | 输入了不支持的词 | 检查拼写，使用支持的关系词 | | 未找到对应称呼 | 关系链过于偏远 | 缩短关系链，或查看是否收录 | | 输入为空 | 未提供关系链 | 提供有效的关系链描述 | | Module does not export a valid XpertPlugin | 入口文件导出错误 | 检查 index.js 是否正确导出 | | middleware provider must call AgentMiddlewareStrategy | 策略装饰器未调用 | 检查 index.js 中的装饰器调用 | | @xpert-ai/plugin-sdk peerDependencies range spans multiple SDK major versions | peer 范围错误 | 使用 ^3.14.0 |

安全注意事项

✅ 本插件不访问外部 API，所有计算在本地完成
✅ 不存储用户查询历史
✅ 不涉及个人隐私信息
✅ 所有称呼数据内置在代码中，可审计
⚠️ 方言和地区差异可能导致称呼不同，本插件默认使用普通话/大陆标准
⚠️ 部分偏远关系可能未被收录，建议用户反馈补充

支持的亲戚关系范围

直系长辈

爸爸、妈妈、爷爷、奶奶、外公、外婆、曾祖父、曾祖母、太爷爷、太奶奶、太外公、太外婆

父系父辈

伯父、叔叔、姑妈、姑姑、伯母、婶婶、姑父

母系父辈

舅舅、姨妈、舅妈、姨父

同辈配偶

嫂子、弟妹、姐夫、妹夫

兄弟姐妹的孩子

侄子、侄女、外甥、外甥女

子女配偶

儿媳妇、女婿

孙辈

孙子、孙女、外孙、外孙女、曾孙、曾孙女

姻亲（丈夫方）

公公、婆婆、大伯子、小叔子、大姑子、小姑子

姻亲（妻子方）

岳父、岳母、大舅子、小舅子、大姨子、小姨子

堂亲（父系同姓）

堂哥、堂弟、堂姐、堂妹、堂嫂、堂弟妹、堂姐夫、堂妹夫

表亲（父系异姓 + 母系）

表哥、表弟、表姐、表妹、表嫂、表弟妹、表姐夫、表妹夫

下一步

在 http://10.161.48.53:3300 使用插件：

登录 XpertAI 平台
进入"插件管理"页面
找到"中国亲戚称呼计算器"插件
在智能体编排中添加"ChineseKinshipTitleMiddleware"中间件
智能体即可使用 calculate_kinship_title、explain_kinship_title、list_kinship_titles 工具

如果插件未出现在中间件列表中，可通过 Skill 脚本间接运行：

node scripts/run-skill.js "爸爸的爸爸"

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

中国亲戚称呼计算器 (Chinese Kinship Title Calculator)

插件简介

适用场景

目录结构

安装方式

npm 方式

zip 方式

配置项说明

Agent Middleware 工具列表

1. calculate_kinship_title（计算亲戚称呼）

2. explain_kinship_title（解释亲戚称呼）

3. list_kinship_titles（列出所有称呼）

Skill 兜底运行说明

何时使用 SKILL.md

运行命令

查看输出

错误处理

scripts 目录说明

版本与 API 兼容说明

首次运行顺序

入参说明

calculate_kinship_title

explain_kinship_title

list_kinship_titles

返回值说明

成功响应

失败响应

调用示例

示例 1：计算多层关系

示例 2：解释称呼

示例 3：列出母系称呼

常见错误和处理方式

安全注意事项

支持的亲戚关系范围

直系长辈

父系父辈

母系父辈

同辈配偶

兄弟姐妹的孩子

子女配偶

孙辈

姻亲（丈夫方）

姻亲（妻子方）

堂亲（父系同姓）

表亲（父系异姓 + 母系）

下一步

许可证