feat(skills): add gitlink-kb skill
This commit is contained in:
parent
b45241dcda
commit
340cf543f4
|
|
@ -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) — 认证、全局参数、安全规则
|
||||
|
|
@ -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 <owner> --repo <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 错误码。某目录不存在时跳过，不中断索引。
|
||||
|
|
@ -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` / `如何` / `怎么` / `为什么` / `是否` 开头
|
||||
|
||||
## 文档地图
|
||||
|
||||
按文档归类所有标题，保留层级缩进，呈现仓库文档的整体结构。
|
||||
|
||||
## 局限
|
||||
|
||||
- 基于关键词命中，不做语义向量检索；对同义词/近义表达的召回有限。
|
||||
- 仅索引文本类文档，不索引代码文件。
|
||||
Loading…
Reference in New Issue