From 340cf543f4e651196dbaf7b65135eda16ad9ffe2 Mon Sep 17 00:00:00 2001 From: Ct201314 <1195214305@qq.com> Date: Sat, 6 Jun 2026 00:14:28 +0800 Subject: [PATCH] feat(skills): add gitlink-kb skill --- skills/gitlink-kb/SKILL.md | 105 ++++++++++++++++++ skills/gitlink-kb/references/api-reference.md | 53 +++++++++ skills/gitlink-kb/references/search.md | 40 +++++++ 3 files changed, 198 insertions(+) create mode 100644 skills/gitlink-kb/SKILL.md create mode 100644 skills/gitlink-kb/references/api-reference.md create mode 100644 skills/gitlink-kb/references/search.md diff --git a/skills/gitlink-kb/SKILL.md b/skills/gitlink-kb/SKILL.md new file mode 100644 index 0000000..659e1e8 --- /dev/null +++ b/skills/gitlink-kb/SKILL.md @@ -0,0 +1,105 @@ +--- +name: gitlink-kb +version: 1.0.0 +description: "仓库知识库问答：索引 README、docs 目录与各类 Markdown 文档，支持关键词检索、文档地图生成、FAQ 提取，让仓库沉淀的知识可被快速查询。当用户提到「文档里怎么说」「如何使用/安装/配置」「这个项目的文档」「FAQ」「常见问题」「知识库」「文档地图」「搜索文档」时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + optional_bins: ["python"] + cliHelp: "gitlink-cli repo --help" +--- + +# gitlink-kb（仓库知识库问答助手） + +**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。** +**CRITICAL — 本技能全程只读，不修改任何远程数据。** + +> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。 + +## 何时使用本技能 + +- 用户问「这个项目怎么安装/配置/使用」，希望从仓库文档里找答案 +- 想快速了解一个仓库都有哪些文档、讲了什么（文档地图） +- 想从文档中提取 FAQ / 常见问题 +- 在不克隆仓库的情况下检索文档内容 + +## 何时不使用 + +- 检索代码实现而非文档 → 用代码搜索类工具 +- 仅读取单个文件 → 用 `gitlink-repo` 的 readme/文件接口 + +## 能力概览 + +| 能力 | 说明 | +|------|------| +| 关键词检索 | 在 README + docs 等文档中检索与问题最相关的段落（支持中英文） | +| 文档地图 | 按文档归类所有标题，呈现仓库文档结构 | +| FAQ 提取 | 自动识别文档中形似问题的标题，提取问答对 | + +## 工作流：从仓库文档中查找答案 + +### 方式 A：用配套脚本（推荐） + +```bash +# 关键词/问题检索 +python scripts/kb.py --owner Gitlink --repo gitlink-cli --query "如何安装" + +# 生成文档地图 +python scripts/kb.py --owner Gitlink --repo gitlink-cli --map + +# 提取 FAQ +python scripts/kb.py --owner Gitlink --repo gitlink-cli --faq + +# JSON 输出 +python scripts/kb.py --owner Gitlink --repo gitlink-cli --query "登录" --format json +``` + +参数说明： + +| 参数 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `--owner` | string | 是* | 仓库所有者（*或用 `--slug`） | +| `--repo` | string | 是* | 仓库名称 | +| `--slug` | string | 否 | `owner/repo` 或完整 URL | +| `--ref` | string | 否 | 分支或标签，默认 master | +| `--query` | string | 否 | 检索关键词/问题 | +| `--map` | flag | 否 | 生成文档地图 | +| `--faq` | flag | 否 | 提取 FAQ | +| `--max-files` | int | 否 | 最多索引的文档数，默认 20 | +| `--format` | string | 否 | `markdown`（默认）或 `json` | +| `--output` | string | 否 | 输出文件 | + +### 方式 B：用 gitlink-cli 读取文档 + +```bash +# 读取 README +gitlink-cli repo +readme --owner Gitlink --repo gitlink-cli --ref master --format json + +# 列出 docs 目录 +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=docs&ref=master' --format json + +# 读取某个文档文件 +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=docs/guide.md&ref=master' --format json +``` + +## 检索说明 + +- 检索基于关键词命中计分，标题命中加权；中文查询会做 2-gram 切分，兼顾中英文文档。 +- 索引范围：README + `docs/`、`doc/`、`.gitlink/`、`wiki/` 等目录下的 Markdown/文本文件。 +- 这是基于规则的检索，不依赖大模型，结果可解释。 + +## API 注意事项 + +- README 通过 `readme` 接口读取，其余文档通过 `sub_entries` 接口读取内容。 +- 数据采集全程只读。 + +## 输出示例 + +参见 [`examples/`](examples/) 的真实检索结果与 FAQ。 + +## References + +- [api-reference.md](references/api-reference.md) — 采集接口、字段与输出结构 +- [search.md](references/search.md) — 索引范围、检索算法与 FAQ 提取规则 +- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则 diff --git a/skills/gitlink-kb/references/api-reference.md b/skills/gitlink-kb/references/api-reference.md new file mode 100644 index 0000000..28fa4b2 --- /dev/null +++ b/skills/gitlink-kb/references/api-reference.md @@ -0,0 +1,53 @@ +# gitlink-kb API 参考 + +> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。 + +本技能索引仓库文档所依赖的接口与字段。全程只读。 + +## 采集的接口 + +### README + +``` +GET /:owner/:repo/readme.json?ref={ref} +# 或经 gitlink-cli： +gitlink-cli repo +readme --owner --repo --ref master --format json +``` + +返回 `content` 字段。注意：GitLink 的 readme 接口虽将 `encoding` 标为 base64， +实测 `content` 多为**明文** Markdown，本技能会先探测明文特征，必要时再做 base64 解码。 + +### 列目录与读取文档 + +``` +GET /:owner/:repo/sub_entries.json?filepath={dir}&ref={ref} # 列目录 +GET /:owner/:repo/sub_entries.json?filepath={file}&ref={ref} # 读单文件（entries.content 为明文） +``` + +本技能在根目录、`docs/`、`doc/`、`.gitlink/`、`wiki/` 中查找文档文件。 + +## 使用的字段 + +| 字段 | 说明 | 用途 | +|------|------|------| +| readme `content` | README 内容 | 索引 | +| `entries[].name` | 文件名 | 筛选文档扩展名 | +| `entries[].type` | file / dir | 只索引 file | +| `entries[].content` | 单文件明文内容 | 索引正文 | + +## 输出字段（JSON） + +检索： + +```json +{"query": "如何安装", + "results": [{"doc": "README", "title": "安装", "score": 7, "snippet": "..."}]} +``` + +文档地图：`{"README": [{"title": "安装", "level": 2}, ...]}` + +FAQ：`{"faq": [{"question": "...", "answer": "...", "doc": "README"}]}` + +## 错误处理 + +沿用 gitlink-shared 错误码。某目录不存在时跳过，不中断索引。 diff --git a/skills/gitlink-kb/references/search.md b/skills/gitlink-kb/references/search.md new file mode 100644 index 0000000..dd76078 --- /dev/null +++ b/skills/gitlink-kb/references/search.md @@ -0,0 +1,40 @@ +# 索引与检索规则 + +本技能基于规则做文档检索，不依赖大模型，结果可解释。 + +## 索引范围 + +- README（经 readme 接口） +- 以下目录中的文档文件：根目录、`docs/`、`doc/`、`.gitlink/`、`wiki/` +- 文档扩展名：`.md` / `.markdown` / `.rst` / `.txt` +- 默认最多索引 20 个文档（`--max-files` 可调） + +## 文档切分 + +按 Markdown 标题（`#` ~ `######`）把文档切分为段落，每段记录：所属文档、标题、标题层级、正文。 + +## 检索算法 + +1. 把查询拆为关键词： + - 英文按 `[A-Za-z0-9_]+` 切词； + - 中文额外做 2-gram 切分（如「如何安装」→「如何」「何安」「安装」），兼顾中文无空格分词。 +2. 对每个段落计分： + - 正文 + 标题中每出现一次关键词 +1； + - 关键词命中**标题** 额外 +5（标题更能代表段落主题）。 +3. 按分数降序返回前 N 段（默认 5），附 300 字摘要。 + +## FAQ 提取 + +识别形似问题的标题并提取问答对，判定规则（命中任一）： + +- 标题含 `?` 或 `？` +- 标题以 `Q:` / `Q ` / `how` / `what` / `why` / `when` / `如何` / `怎么` / `为什么` / `是否` 开头 + +## 文档地图 + +按文档归类所有标题，保留层级缩进，呈现仓库文档的整体结构。 + +## 局限 + +- 基于关键词命中，不做语义向量检索；对同义词/近义表达的召回有限。 +- 仅索引文本类文档，不索引代码文件。