glossarygen

glossarygen

项目积累名称的速度，往往快于为这些名称补充说明的速度：同一个概念在数据库层中写作 user_id，在 API 类型中写作 UserID，在文档中则写作“user id”，但没人说得清它们究竟是一个术语还是三个。glossarygen 会根据你已有的事实解决这类问题。你提供术语出现记录——每个名称都要与发现时完全一致，并注明发现位置；如果文档中有定义，也一并提供——glossarygen 就会返回一份合并后的统一词汇表：每个不同的术语对应一个条目，列出该术语出现过的所有来源，以及文档给出的定义（如果有）。它不会自行编写定义，也不会获取任何内容；它只会规范化并合并你提供的信息。

规范化遵循一套固定步骤，并按顺序执行。首先，将每一段连续的下划线或连字符替换为一个空格。然后拆分驼峰命名：在小写字母或数字后接大写字母的位置前插入空格；在一段连续大写字母的末尾、即开始一个首字母大写单词的位置前也插入空格，因此 HTTPServer 会变成 HTTP Server。随后按空白字符拆分结果，并将每个单词转换为小写；用单个空格连接这些单词，作为术语的键。因此，parseHTTPResponse 的键为 parse http response，而 user_id 和 UserID 会归入同一个键 user id，并合并为一个条目。

每个条目都会以显示形式展示术语——即将键的首字符大写，因此 parse http response 会显示为 Parse http response——并列出该术语所有出现记录中的不同来源，按升序排列，同时显示合并到该条目中的出现次数。条目的定义取自你所提供的合并记录中最先出现的定义；空字符串定义仍视为已提供，并会原样保留；如果没有任何记录提供定义，则定义为 null。条目按键排序；计数会报告你提供的出现记录数量、合并后不同术语的数量，以及其中带定义和不带定义的术语数量。

仅由分隔符组成的名称（例如 ___）规范化后不会得到任何单词，因此会产生一个注明其路径的验证错误。缺少术语列表或列表为空、出现记录不是对象、name 或 source 缺失、为空或不是字符串，以及存在但不是字符串的 definition，也都会产生验证错误。输入无效时不会生成部分词汇表。未知的额外字段会被忽略。

CLI

npx @reneturcios/glossarygen build --input args.json
npx @reneturcios/glossarygen --version

args.json 包含完整的参数对象：

{
  "terms": [
    {
      "name": "user_id",
      "source": "src/user.ts"
    },
    {
      "name": "UserID",
      "source": "docs/api.md",
      "definition": "Stable identifier for a user account."
    },
    {
      "name": "parseHTTPResponse",
      "source": "src/http.ts"
    }
  ]
}

词汇表会以 JSON 格式打印：

{
  "entries": [
    {
      "term": "Parse http response",
      "sources": ["src/http.ts"],
      "occurrences": 1,
      "definition": null
    },
    {
      "term": "User id",
      "sources": ["docs/api.md", "src/user.ts"],
      "occurrences": 2,
      "definition": "Stable identifier for a user account."
    }
  ],
  "counts": {
    "supplied": 3,
    "distinct_terms": 2,
    "with_definition": 1,
    "without_definition": 1
  }
}

退出代码：成功时为 0，运行时错误（包括输入文件无法读取或无效，以及输入无效）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/glossarygen mcp

MCP 客户端配置：

{
  "mcpServers": {
    "glossarygen": {
      "command": "npx",
      "args": ["-y", "@reneturcios/glossarygen", "mcp"]
    }
  }
}

工具

• build_glossary — 根据调用方提供的术语构建项目词汇表：对标识符名称和文档名称进行规范化并合并，每个条目都包含其来源，以及已提供的定义（如果有）。

  • terms（数组，必填，至少 1 项）— 按调用方提供的顺序排列、需要合并的术语出现记录；每项包含：
    • name（字符串，必填，不能为空）— 发现时的术语：标识符或文档短语
    • source（字符串，必填，不能为空）— 发现该术语的位置（路径或链接），并作为条目的来源原样返回
    • definition（字符串，可选）— 在文档中找到的定义

  返回 {entries, counts}，其中 entries 为每个不同的规范化术语提供一个 {term, sources, occurrences, definition}，并按术语键排序；counts 的结构为 {supplied, distinct_terms, with_definition, without_definition}。

Docker

docker run -i ghcr.io/cloudcorprecords/glossarygen
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/glossarygen build --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — Copyright (c) 2026 Rene Turcios