faqmine

faqmine

支持队列和问题跟踪系统中总会反复出现相同的问题，每次都以措辞略有不同的独立已关闭问题出现。faqmine 会帮你找出这些重复问题。你只需提供已关闭的问题——每个问题的标题和链接，以及已有的标签——faqmine 就会将真正相同的问题分组，并根据这些分组起草常见问题解答：对于每个重复问题，列出问题文本、提问次数以及每次提问对应的链接。它不会编造答案。问题、次数和链接都原封不动地取自你提供的问题，因此无需任何人核查生成的文字，草稿就能直接进入分流流程。

两个标题的提问键相同时，就视为同一个问题。生成键时，会先将标题转为小写，再按每段连续的非字母数字字符拆分为词元，丢弃固定列表中的停用词（a、an、the、is、are、was、were、do、does、did、how、what、why、when、where、which、who、can、could、should、would、i、we、you、it、to、of、in、on、for、with、and、or、not、no、my、me、this、that、there、here），保留其余词元且每个只保留一次，将它们排序后用单个空格连接。因此，词序、大小写和标点都无关紧要：“How do I reset my password?”和“Password reset — how?”的键都是password reset，会归为一组。标题若只包含停用词和标点，则键为空，不会归入任何组。

某组达到min_count个问题后，就会生成一条常见问题解答（除非另行指定，默认为 2 个）。条目中的问题是该组中第一个问题的标题，按你提供的顺序原样呈现；其 urls 是该组的链接，顺序相同；其 labels 是该组标签的去重并集，按升序排序。条目按次数从多到少排序；次数相同则按该组第一个问题在输入中的位置排序。统计数据会报告你提供的问题数、起草的条目数、归入这些条目的问题数，以及未归组的问题数——包括未达到阈值的组中的问题和键为空的问题。

格式错误的输入——问题列表缺失或为空、列表项不是对象、title或url缺失、为空或不是字符串、labels的值不是数组或其中包含空字符串或非字符串条目，或者min_count小于 2 或不是整数——会触发验证错误，指出出错路径，且不会返回部分结果。未知的额外字段会被忽略。

CLI

npx @reneturcios/faqmine mine --input args.json
npx @reneturcios/faqmine --version

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

{
  "issues": [
    {
      "title": "How do I reset my password?",
      "url": "https://example.com/issues/1",
      "labels": ["account", "auth"]
    },
    {
      "title": "Password reset — how?",
      "url": "https://example.com/issues/2",
      "labels": ["auth"]
    },
    {
      "title": "Export to CSV fails",
      "url": "https://example.com/issues/3"
    }
  ]
}

常见问题解答草稿以 JSON 格式输出：

{
  "entries": [
    {
      "question": "How do I reset my password?",
      "count": 2,
      "urls": [
        "https://example.com/issues/1",
        "https://example.com/issues/2"
      ],
      "labels": ["account", "auth"]
    }
  ],
  "counts": {
    "issues": 3,
    "clusters": 1,
    "clustered_issues": 2,
    "unclustered": 1
  }
}

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

MCP 服务

npx -y @reneturcios/faqmine mcp

MCP 客户端配置：

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

工具

• mine_faq — 挖掘调用方提供的已关闭问题，找出重复问题并起草常见问题解答条目：问题（原样呈现的所提供问题标题）、次数以及问题链接。不会编造答案。

  • issues（数组，必填，至少 1 项）— 要挖掘的已关闭问题，按调用方提供的顺序排列；每项包含：
    • title（字符串，必填，非空）— 问题标题
    • url（字符串，必填，非空）— 问题链接
    • labels（字符串数组，可选）— 问题标签；缺省表示没有标签
  • min_count（整数，可选，至少为 2，默认值为 2）— 生成常见问题解答条目所需的最小分组规模

  返回{entries, counts}，其中entries包含每个纳入分组对应的一个{question, count, urls, labels}，counts为{issues, clusters, clustered_issues, unclustered}。

Docker

docker run -i ghcr.io/cloudcorprecords/faqmine
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/faqmine mine --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