zzx-coder
/
gitlink-cli
forked from Gitlink/gitlink-cli
0
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 8 Wiki Activity

feat(faq): 将生成的faq内容组织重构为真正的Q&A知识库 #23

Merged
mengcheng merged 5 commits from mc_branch into master 2026-07-02 14:57:56 +08:00
Conversation 0 Commits 5 Files Changed 9 +518 -412
9 changed files with 518 additions and 412 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

235
skills/gitlink-faq/SKILL.md
View File

@ -1,35 +1,45 @@
---
name: gitlink-faq
version: 1.3.0
description: "Issue 知识库：从项目 Issue 自动分类（Bug/功能请求/使用问题），按类型归纳聚类，生成结构化知识库发布到 Wiki；增量更新已有知识库；检测新 Issue 是否与已有问题重复。当用户需要整理 Issue、归纳 Issue、总结常见问题/Bug、建立知识库、更新知识库、检查重复 Issue、查重时触发。通用 Issue 操作（创建/查看/更新/关闭/评论等）请使用 gitlink-issue skill。"
version: 2.0.0
description: "Issue 知识库（即 FAQ、常见问题）：从项目 Issue 提取问题与答案，合并同类 Issue，生成结构化 FAQ 发布到 Wiki。注意——用户说的「知识库」「FAQ」「常见问题」都是指这个 skill，这三个词是同义词。触发场景：整理 Issue、归纳 Issue、生成/建立/更新/刷新知识库、生成 FAQ、总结常见问题、检查重复 Issue、查重。通用 Issue 操作（创建/查看/更新/关闭/评论等）请使用 gitlink-issue skill。"
metadata:
requires:
bins: ["gitlink-cli"]
cliHelp: "gitlink-cli issue --help"
---
# gitlink-faq（Issue 知识库）
# gitlink-faq（Issue 知识库 / FAQ）
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 写入/删除操作前，务必先确认用户意图。默认 dry-run 预览，用户确认后再执行。**
**CRITICAL — 只读操作（`issue +list`、`issue +view`、`wiki +view`）自动连续执行，不要逐个请求用户确认。数据采集和分析阶段一气呵成，仅在最终写入步骤前暂停确认。**
**CRITICAL — 全流程自动执行，不要中途停下来问用户。从采集数据到发布 Wiki 一气呵成，最后告诉用户结果即可。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)
## 核心概念
**「知识库」=「FAQ」=「常见问题」——这三个词是同一个东西。** 用户不管说哪个，都指的是这个 skill。
FAQ 知识库是一个 **"问题 → 答案"** 的集合，从项目 Issue 中提取真实用户遇到的问题和对应的解决方案。与统计分析报告不同，知识库的重点在于：
- **收集 Issue 内容**：从 subject（标题）+ description（描述）+ journals（评论讨论）中提取问题和答案
- **合并同类问题**：多个 Issue 描述的是同一个问题 → 合并为一条 FAQ，综合各方讨论给出完整答案
- **按主题归类**：用主题标签（安装配置、CLI 命令、API 等）组织，方便检索
- **可追溯来源**：每条 FAQ 附来源 Issue 编号，方便查看原始讨论
## 运行模式
| 模式 | 说明 | 典型触发语 | 需要认证 |
|------|------|------------|----------|
| **模式 A：Issue 归纳** | 采集全部 Issue → 按类型分类 → 主题聚类 → 生成结构化知识库发布到 Wiki | "整理 Issue""归纳关闭的 Issue""总结项目问题""建立知识库""分析 Issue" | 是（发布 Wiki 需写入） |
| **模式 B：重复检测** | 对指定 Issue，在知识库和历史 Issue 中查找相似项，判断是否重复 | "查重""有没有类似的 Issue""这个是不是有人报过" | 否（仅读取；评论需认证） |
| **模式 C：Wiki 增量更新** | 读取已有 Wiki 页面 → 拉取新 Issue → 分类合并到现有知识库结构 → 更新 Wiki | "把这个 Issue 加到知识库""更新 Wiki 页面""补充到知识库里""同步最新 Issue 到 Wiki" | 是（读取+写入 Wiki） |
| **模式 A：生成/刷新 FAQ** | 采集全部 Issue → 提取 Q&A → 合并同类问题 → 按主题归类 → 发布 Wiki | "整理 Issue""归纳 Issue""总结常见问题""生成 FAQ""建立知识库""刷新知识库""更新知识库""生成知识库" | 是（发布 Wiki 需写入） |
| **模式 B：查找与查重** | 对指定 Issue/关键词，在知识库和历史 Issue 中查找相似项，判断是否重复 | "查重""有没有类似的 Issue""这个是不是有人报过""知识库里有没有" | 否（仅读取；评论需认证） |
| **模式 C：增量更新** | 读取已有 Wiki 页面 → 拉取新 Issue → 提取 Q&A 合并到现有知识库 → 更新 Wiki | "把这个 Issue 加到知识库""补充到知识库""同步到知识库""更新 FAQ""更新知识库" | 是（读取+写入 Wiki） |
---
## 模式 A：Issue 归纳（6 步）
## 模式 A：生成/刷新 FAQ 知识库（6 步）
当用户说 **"整理 Issue"、"归纳已关闭 Issue"、"总结项目问题"、"建立知识库"** 等时，执行以下流程。
当用户说 **"整理 Issue"、"归纳 Issue"、"总结常见问题"、"生成 FAQ"、"建立知识库"、"刷新知识库"、"更新知识库"** 等时，执行以下流程。**记住：「知识库」=「FAQ」，用户说知识库就是在让你执行这个 skill。**
### 第 1 步：采集全部 Issue
@ -45,7 +55,7 @@ gitlink-cli issue +list --state closed --limit 100 --format json
采集量策略参见 [`references/gitlink-faq-collect.md`](references/gitlink-faq-collect.md)。
### 第 2 步：筛选 + 读取详情（依靠 description）
### 第 2 步：筛选 + 读取详情
先按标题粗筛，仅排除：
- 标题含 `[test]` / `测试` 的纯测试 Issue
@ -57,123 +67,114 @@ gitlink-cli issue +list --state closed --limit 100 --format json
gitlink-cli issue +view --number N --format json
```
提取字段：`subject`（标题）、`description`（描述）。
提取字段：`subject`（标题）、`description`（描述）、`comment_journals_count`（评论数）。
**description 是核心分析源**：
- 部分 Issue 的 description 非常详细（含复现步骤、环境信息、修复建议）
- description 的质量直接决定分析深度
- description 的质量直接决定能提取出什么质量的 Q&A
- `comment_journals_count` 数值可参考（表示讨论热度），但实际评论内容无法通过 API 获取（见下方 API 限制）
每批 20-30 个，尽量覆盖所有非测试 Issue。
### 第 3 步：Issue 类型分类
### 第 3 步：从每个 Issue 提取 Q&A 对
对每条 Issue，AI 根据 (subject + description) 判断类型。**不要因为"缺少 journals"或"状态未关闭"而排除 Issue**——是否有分析价值取决于内容本身，不是状态。
对每条 Issue，AI 根据 (subject + description) 提取"问题 → 答案"对。
| 类型 | 判断依据 | 纳入条件 | 分析价值 |
|------|----------|----------|----------|
| **Bug 报告** | 描述异常行为、报错、与预期不符 | description 非空 或 subject 明确描述症状 | 高频 Bug = 模块质量信号 |
| **功能请求** | 建议新增能力、改进体验 | 保留。高频请求反映用户需求 | 用户需求优先级 |
| **使用问题** | 不知道怎么用、配置不清楚 | 保留。即使未回复也是需求信号 | 文档/体验改进方向 |
| **其他** | 不属于以上三类 | 标题无实质内容则忽略 | 低 |
**提取规则**：
**输出**：每条 Issue 带上类型标签。
**宽松原则**：宁可多留一条低价值的，也别漏掉一条有洞察的。不确定类型的归入"其他"而非丢弃。
### 第 4 步：按类型分别聚类
将同类型的 Issue 按语义相似度聚类。不同类型聚类维度不同：
| 类型 | 聚类维度 | 聚类目标 |
| 字段 | 提取来源 | 提取方法 |
|------|----------|----------|
| Bug 报告 | 按**出问题的模块/功能**归类 | 找出"哪个模块 Bug 最多"、"同类 Bug 的共同根因" |
| 功能请求 | 按**请求的功能领域**归类 | 找出"用户最想要什么能力"、"哪些增强呼声最高" |
| 使用问题 | 按**操作场景**归类 | 传统 Q&A：提炼"问题 → 答案" |
| **Q（问题）** | subject + description 开头部分 | 提炼 Issue 要解决的核心问题，用一句话表达 |
| **A（答案）** | description 后半部分 + journals（如有） | 提取解决方案、workaround、配置方法、官方回复等 |
**Bug 聚类输出**：
**不同 Issue 类型的 Q&A 转换**：
```json
{
"module": "Issue 数据显示",
"bug_count": 4,
"pattern": "CLI 返回数据与网页端不一致、字段缺失",
"affected_issues": [5, 7, 15, 18],
"typical_symptom": "issue +view / pr +view 返回结果缺少关键字段或与网页端不一致"
}
```
| Issue 原始类型 | Q 示例 | A 提取策略 |
|---------------|--------|------------|
| Bug 报告 | "为什么执行 xxx 命令后出现 yyy 错误？" | 从 description 提取修复方法/workaround；如无则写"暂未找到解决方案" |
| 功能请求 | "能否支持 xxx 功能？" | 从 description/journals 提取当前状态（已支持/规划中/不支持+替代方案） |
| 使用问题 | "如何配置/使用 xxx？" | 从 description 提取操作步骤；从 journals 提取维护者回复 |
**功能请求聚类输出**：
**宽松原则**：宁可多留一条不完美的 Q&A，也别漏掉一条有价值的。不确定答案质量的标注"待确认"而非丢弃。
```json
{
"feature_area": "API 能力增强",
"request_count": 3,
"pattern": "希望 API 支持更多查询/操作能力",
"affected_issues": [9, 14, 21],
"common_ask": "支持按序号查询 Issue、读取仓库文件、返回完整时间字段"
}
```
### 第 4 步：合并同类问题
**使用问题聚类输出**（仅当同类 ≥2 条时生成 Q&A）：
多个 Issue 描述的是同一个问题 → 合并为一条 FAQ 条目。
```json
{
"topic": "安装配置",
"question": "gitlink-cli 安装后无法运行怎么办？",
"answer": "检查 PATH、确认平台支持，详见安装文档",
"source_issues": [16, 20]
}
```
合并判断标准：
- 两个 Issue 的 subject 高度相似（同义表述）
- 两个 Issue 描述的症状/需求一致
- 两个 Issue 的根因/答案相同
### 第 5 步：生成知识库文档
合并后的 FAQ 条目：
- **Q**：综合多个 Issue 提炼一个清晰的问题
- **A**：综合各方描述和讨论给出最完整的答案
- **来源**：列出所有相关 Issue 编号
按以下结构组织 Markdown：
详细合并逻辑参见 [`references/gitlink-faq-cluster.md`](references/gitlink-faq-cluster.md)。
### 第 5 步：按主题归类 + 生成 FAQ 文档
将 Q&A 条目按**主题标签**归类。每个标签有对应图标，生成文档时章节标题必须带图标。标签体系：
| 图标 | 主题标签 | 适用范围 |
|------|----------|----------|
| 🔧 | `安装配置` | 安装、登录、认证、Token 配置、代理设置 |
| 💻 | `CLI 命令` | 命令使用、参数、输出格式、交互行为 |
| 🔗 | `API 与集成` | API 调用、Webhook、CI/CD 集成 |
| 📊 | `数据显示` | 数据不一致、字段缺失、展示错误 |
| 🖥️ | `平台兼容` | 操作系统兼容、环境依赖 |
| ⚡ | `性能` | 响应慢、超时、资源占用 |
| 💡 | `功能请求` | 用户希望新增或改进的功能 |
| 📦 | `其他` | 不属于以上类别 |
> 一个 Q&A 条目可以打多个标签。
按以下结构组织 Markdown（**注意章节标题前必须带图标**）：
```markdown
# 📊 Issue 知识库
# 📖 {项目} FAQ 知识库
> 自动生成 | 数据来源：已关闭 Issue（{N} 条）
> 更新时间：{DATE}
> 自动生成 | 收录 {N} 个问题 | 更新时间：{DATE}
> 项目：{OWNER}/{REPO}
## 🐛 Bug 高频模块
## 🔧 安装配置
### {模块名}（{N} 个 Bug）
- **典型症状**: ...
- **涉及 Issue**: #A, #B, #C
- **已知修复**: ...（如有）
## 💡 功能请求热度
### {功能领域}（{N} 个请求）
- **用户期望**: ...
- **涉及 Issue**: #D, #E, #F
## 📖 常见使用问题
### Q: {问题}？
### Q1: {问题}？
**A:** {答案}
> 来源: #G, #H
> 📎 来源: [#N]({链接}), [#M]({链接})
## 💻 CLI 命令
### Q2: {问题}？
**A:** {答案}
> 📎 来源: [#N]({链接})
...
```
根据实际数据量，若某类型 Issue 过少（<2 条），该章节可省略或合并到"其他"。
完整模板参见 [`examples/faq-template.md`](examples/faq-template.md)。
文档模板参见 [`examples/faq-template.md`](examples/faq-template.md)。
生成原则参见 [`references/gitlink-faq-generate.md`](references/gitlink-faq-generate.md)。
完成后保存为 `./issue-knowledge-base.md`，展示给用户预览。
完成后保存为 `./issue-faq.md`，然后直接进入第 6 步发布，不需要等用户确认。
### 第 6 步：发布到 Wiki
用户确认后：
直接发布，不要询问用户：
```bash
# 首次创建
gitlink-cli wiki +create --title "Issue-知识库" --file ./issue-knowledge-base.md
# 先检查 Wiki 页面是否已存在
gitlink-cli wiki +view --title "Issue-知识库" --format json
# 后续更新
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md
# 如果存在（返回内容）→ 用 update；如果 404 → 用 create
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md
# 或
gitlink-cli wiki +create --title "Issue-知识库" --file ./issue-faq.md
```
发布完成后给用户反馈：发布了多少条 FAQ、Wiki 页面标题。
---
## 模式 B：Issue 查找与查重
@ -220,9 +221,9 @@ gitlink-cli issue +view --number N --format json
- 维护者有无回复/解决方案
- 相关度判定
### 第 5 步：执行操作（仅查重+用户确认后）
### 第 5 步：执行操作（自动）
如果是查重场景且判定高度重复，用户确认后执行：
如果判定高度重复，直接添加评论引导用户，不要询问：
```bash
# 添加评论（使用 Issue ID，参见 gitlink-issue skill）
@ -238,9 +239,9 @@ gitlink-cli issue +batch-label --label duplicate --numbers N,M
## 模式 C：Wiki 增量更新
当用户说 **"把这个 Issue 加到知识库里"、"更新 Wiki 页面"、"补充到知识库"、"同步最新 Issue 到 Wiki"** 等时执行。
当用户说 **"把这个 Issue 加到知识库里"、"更新 FAQ"、"更新知识库"、"补充到知识库"、"同步到知识库"** 等时执行。
**核心思路**：不是重新生成整个知识库，而是读取现有 Wiki 内容 → 拉取新 Issue → 分类合并 → 更新 Wiki。
**核心思路**：不是重新生成整个知识库，而是读取现有 Wiki 内容 → 拉取新 Issue → 提取 Q&A → 合并到现有结构 → 更新 Wiki。
### 第 1 步：读取现有 Wiki
@ -267,35 +268,38 @@ gitlink-cli issue +view --number N --format json
| "把关于 XX 的 Issue 补充进去" | 先按关键词搜索（同模式 B 第 2-3 步），找到匹配 Issue 后逐个读详情 |
| "把最近新增的 Issue 同步到 Wiki" | 用户未指定具体编号时，才拉全量列表，对比 Wiki 中已有的编号做差集 |
### 第 3 步：分类新 Issue
### 第 3 步：从新 Issue 提取 Q&A
### 第 4 步：合并到现有知识库结构
同模式 A 第 3 步，从每个新 Issue 提取"问题 → 答案"对。
将新 Issue 按类型归入现有章节：
### 第 4 步：合并到现有知识库
- **Bug**：归入"Bug 高频模块"，若属于已有模块则追加，否则新建模块条目
- **功能请求**：归入"功能请求热度"，若属于已有领域则合并，否则新建领域条目
- **使用问题**：归入"常见使用问题"，新建 Q&A 条目
将新 Q&A 条目归入现有主题分类：
- **已存在同类问题**：合并到已有 Q&A 条目，更新答案和来源列表
- **全新问题**：在对应主题章节下新建 Q&A 条目
合并时更新：
- Issue 计数（总数、各类型数量）
- 收录问题计数
- 更新时间
- 受影响的 `-- 涉及 Issue` 列表
- 来源 Issue 列表
### 第 5 步：生成合并后的文档并预览
### 第 5 步：生成合并后的文档
将合并后的完整 Markdown 展示给用户预览，标注新增/变更的部分（可用 `[NEW]` 标记）。
将合并后的完整 Markdown 保存为 `./issue-faq.md`，标注新增/变更的部分（可用 `[NEW]` 标记）。
### 第 6 步：更新 Wiki
用户确认后：
直接更新，不要询问用户：
```bash
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md
```
**CRITICAL**：必须用 `wiki +update`（不是 `+create`），因为页面已存在。
发布完成后给用户反馈：新增了多少条 FAQ、更新了多少条已有条目。
---
## 命令速查
@ -326,20 +330,21 @@ gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base
## 注意事项
- **先分类再聚类**：不同 Issue 类型不能混在一起聚类（Bug 和功能请求本质不同）
- **所有结论必须有来源**：Bug 模式、功能热度、Q&A 答案都必须来自实际 Issue，不编造
- **数据不足时如实说明**：某类型 < 2 条时不强行归纳，标注"暂无足够数据"
- **从 Issue 提取，不编造**：Q&A 的 Q 和 A 都必须来自实际 Issue 的 subject/description/journals，不凭空编造
- **合并优于罗列**：多个 Issue 问同一个问题 → 合并为一条 FAQ，而不是罗列多条相似条目
- **答案有据可查**：每条 FAQ 必须附来源 Issue 编号
- **数据不足时如实说明**：无法提取答案的 Issue 标注"待确认"，不强行写答案
- **评论语气友好**：重复检测是帮助用户，不是指责
- **用户确认优先**：所有写入操作前先预览
- **全自动执行**：触发后从头到尾自动完成，不中途询问用户，最后告知结果即可
## References
- [gitlink-faq-collect](references/gitlink-faq-collect.md) — Issue 数据采集
- [gitlink-faq-cluster](references/gitlink-faq-cluster.md) — 分类+聚类算法
- [gitlink-faq-generate](references/gitlink-faq-generate.md) — 知识库文档生成
- [gitlink-faq-collect](references/gitlink-faq-collect.md) — Issue 数据采集与 Q&A 提取
- [gitlink-faq-cluster](references/gitlink-faq-cluster.md) — 同类问题合并逻辑
- [gitlink-faq-generate](references/gitlink-faq-generate.md) — FAQ 知识库文档生成
- [gitlink-faq-detect](references/gitlink-faq-detect.md) — 重复检测逻辑
- [gitlink-faq-publish](references/gitlink-faq-publish.md) — Wiki 发布
- [weekly-faq-refresh-workflow](examples/weekly-faq-refresh-workflow.md) — 定期刷新示例
- [duplicate-detection-demo](examples/duplicate-detection-demo.md) — 重复检测示例
- [faq-template](examples/faq-template.md) — 文档模板
- [faq-template](examples/faq-template.md) — FAQ 文档模板
- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证和全局参数

6
skills/gitlink-faq/examples/duplicate-detection-demo.md
View File

@ -33,8 +33,8 @@ gitlink-cli issue +view --number 312 --format json
### Step 3: 获取对比数据
```bash
# 获取 FAQ
gitlink-cli wiki +view --title "FAQ" --format json
# 获取 FAQ 知识库
gitlink-cli wiki +view --title "Issue-知识库" --format json
# 获取已关闭 Issue
gitlink-cli issue +list --state closed --limit 100 --format json
@ -90,7 +90,7 @@ C. 仅查看，不操作
```bash
gitlink-cli issue +comment --number 312 --body "你好！检测到你的问题与已有内容高度相似：
- 📖 [FAQ - Q3: 登录失败或提示 401 错误](wiki/FAQ)
- 📖 [FAQ - Q3: 登录失败或提示 401 错误](wiki/Issue-知识库)
- 🔗 Issue #142: 登录页面显示空白（浏览器缓存问题）
- 🔗 Issue #205: 无法登录，页面无响应（DNS 解析问题）

145
skills/gitlink-faq/examples/faq-template.md
View File

@ -1,86 +1,95 @@
# 📊 Issue 知识库
# 📖 {项目名} FAQ 知识库
> 自动生成 | 数据来源：已关闭 Issue（{N} 条有效）
> 更新时间：{DATE}
> 自动生成 | 收录 {N} 个问题 | 更新时间：{DATE}
> 项目：{OWNER}/{REPO}
>
> 本知识库从项目 Issue 中自动提取，将用户遇到的实际问题与解决方案整理为 FAQ。如果你遇到问题，先在下面查找；如果没有找到答案，欢迎提交新 Issue。
---
## 📂 概览
## 🔧 安装配置
| 类型 | 数量 | 聚类数 |
|------|------|--------|
| 🐛 Bug 报告 | {BUG_COUNT} | {BUG_CLUSTER_COUNT} 个模块 |
| 💡 功能请求 | {FEATURE_COUNT} | {FEATURE_CLUSTER_COUNT} 个领域 |
| 📖 使用问题 | {QUESTION_COUNT} | {QUESTION_CLUSTER_COUNT} 个主题 |
### Q1: {用一句话描述用户遇到的问题/想实现的目标}？
---
**A:** {从 Issue description 和评论讨论中提取的解决方案、操作步骤、workaround 或官方回复}
## 🐛 Bug 高频模块
> 📎 来源: [#{编号}]({链接})
### {模块名}（{N} 个 Bug）🔥🔥
**典型症状**: {一句话描述这类 Bug 的共同表现}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})
**已知修复**: {如有统一修复方案则写，无则写"部分已单独修复，详见表中 Issue"}
---
### {模块名}（{N} 个 Bug）🔥
**典型症状**: ...
**涉及 Issue**: ...
**已知修复**: ...
---
> 如无高频 Bug（均 < 2 条），本章标注"暂无高频 Bug 模式，Bug 报告较分散"。
---
## 💡 功能请求热度
### {功能领域}（{N} 个请求）🔥🔥🔥
**用户期望**: {一句话总结用户想要什么}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})
---
### {功能领域}（{N} 个请求）🔥
**用户期望**: ...
**涉及 Issue**: ...
---
> 如无热门功能请求，本章标注"暂无集中的功能请求"。
---
## 📖 常见使用问题
### Q{N}: {问题}？
### Q2: {问题}？
**A:** {答案}
> 📎 来源 Issue: [#{编号}]({链接}), [#{编号}]({链接})
### Q{N}: {问题}？
**A:** {答案}
> 📎 来源 Issue: [#{编号}]({链接})
> 📎 来源: [#{编号}]({链接}), [#{编号}]({链接})
---
> 如无常见使用问题，本章标注"暂无常见使用问题"。
## 💻 CLI 命令
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---
## 🔗 API 与集成
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---
## 📊 数据显示
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---
## 🖥️ 平台兼容
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---
## ⚡ 性能
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---
## 💡 功能请求
### Q{序号}: 能否支持 {功能描述}？
**A:** {当前状态：已支持/开发中/暂不支持。如暂不支持，说明替代方案或原因}
> 📎 来源: [#{编号}]({链接})
---
## 📦 其他
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接})
---

68
skills/gitlink-faq/examples/weekly-faq-refresh-workflow.md
View File

@ -1,19 +1,19 @@
# 每周刷新 Issue 知识库示例
# 每周刷新 FAQ 知识库示例
> 端到端演示：定期归纳已关闭 Issue，更新知识库 Wiki。
> 端到端演示：定期从 Issue 提取 Q&A，更新知识库 Wiki。
## 场景
gitlink-cli 项目维护者，本周关闭了 20 个 Issue，想更新知识库。
gitlink-cli 项目维护者，本周关闭了 20 个 Issue，想更新 FAQ 知识库。
## 完整对话流程
### 触发
```
用户: 帮我整理这周关闭的 Issue，更新知识库
用户: 帮我整理这周关闭的 Issue，更新 FAQ
AI: 好的，先采集最近关闭的 Issue。
AI: 好的，先采集最近的 Issue。
```
### Step 1-2: 采集 + 筛选
@ -23,48 +23,48 @@ gitlink-cli issue +list --state closed --limit 100 --format json
```
```
AI 采集到 20 个已关闭 Issue：
- 排除 5 个测试 Issue
- 剩余 15 个有效 Issue，读取详情中...
AI 采集到 20 个 Issue：
- 排除 3 个测试 Issue
- 剩余 17 个有效 Issue，读取详情并提取 Q&A 中...
```
### Step 3-4: 分类 + 聚类
### Step 3-4: 提取 Q&A + 合并同类问题
```
AI 展示分析结果：
📊 Issue 分类结果（共 15 条有效）
📖 从 17 个 Issue 中提取了 12 条 FAQ（已合并 5 组同类问题）
类型分布：
| 类型 | 数量 | 占比 |
|------|------|------|
| 🐛 Bug 报告 | 8 | 53% |
| 💡 功能请求 | 5 | 33% |
| 📖 使用问题 | 2 | 13% |
## 安装配置
### Q1: 安装 gitlink-cli 后运行报 command not found 怎么办？
**A:** 将 ~/.local/bin 加入 PATH...
> 📎 来源: #16, #20
───────────────
### Q2: 如何配置企业代理？
**A:** 设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量...
> 📎 来源: #42
🐛 Bug 高频模块：
| 模块 | Bug 数 | 典型症状 |
|------|--------|----------|
| Issue/PR 数据展示 | 4 | view 命令返回字段与网页不一致 |
| 命令执行 | 2 | 特定参数下命令静默失败 |
| 平台兼容 | 2 | Windows 下行为异常 |
## CLI 命令
### Q3: issue +view 返回的 JSON 缺少部分字段？
**A:** 这是已知的 API 版本差异，部分字段需要特定 API 版本才返回...
> 📎 来源: #5, #7, #15
💡 功能请求热度：
| 领域 | 请求数 | 用户期望 |
|------|--------|----------|
| API 查询增强 | 3 | 支持更丰富的查询和字段返回 |
### Q4: pr +list 在 Windows 下输出乱码？
**A:** 设置终端编码为 UTF-8：chcp 65001...
> 📎 来源: #33
📖 使用问题（2 条）：
- 安装后如何配置环境变量？
- API 命令占位符怎么用？
## API 与集成
### Q5: 能否支持在 CI 中使用 Token 认证？
**A:** 已支持。设置 GITLINK_TOKEN 环境变量即可...
> 📎 来源: #28
...
```
### Step 5: 生成并确认
```
AI 生成知识库 Markdown，展示前几段预览...
AI 生成 FAQ Markdown，展示预览...
用户: 可以，发布到 Wiki
@ -74,12 +74,12 @@ AI: 好的，更新 Wiki 页面...
### Step 6: 发布
```bash
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md
```
```
AI: ✅ 知识库已更新！
AI: ✅ FAQ 知识库已更新！
- Wiki 页面: Issue-知识库
- 本次新增: 15 条 Issue → 6 个聚类
- 本次新增: 17 条 Issue → 12 条 FAQ（合并 5 组同类问题）
- 下次建议: 2 周后刷新
```

186
skills/gitlink-faq/references/gitlink-faq-cluster.md
View File

@ -1,114 +1,140 @@
# gitlink-faq 分类与聚类
# gitlink-faq 同类问题合并
> 本文档说明 AI 如何对 Issue 先分类（Bug/功能请求/使用问题），再在同一类型内聚类。
> 本文档说明如何判断多个 Issue 描述的是同一个问题，以及如何将它们合并为一条 FAQ 条目。
## 分析前提
**聚类仅基于 `subject` + `description` 两个字段**。GitLink API 不支持读取 Issue 评论（journals），无法获取讨论/解决方案。但优秀的 description 往往包含：复现步骤、环境信息、修复建议、详细场景描述——这些都是高质量聚类的基础。
## 两步流程
## 合并流程
```
┌─────────────────────────────────────────┐
│ Step 1: 类型分类 │
│ 每条 Issue → AI 判断类型 │
│ Bug / Feature Request / Usage Question │
│ 不确定的归入"其他"但保留，不丢弃 │
│ Step 1: Q&A 提取完成 │
│ 每条 Issue → {Q, A, confidence} │
└──────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────┐
│ Step 2: 类型内聚类 │
│ Bug → 按出问题的模块分类 │
│ Feature → 按功能领域分类 │
│ Usage → 按操作场景分类 │
│ Step 2: 相似度判断 │
│ 比较 Q 的语义相似度 │
│ 比较 A 的答案是否一致 │
└──────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────┐
│ Step 3: 合并 │
│ 同一问题 → 综合 Q + 综合 A + 合并来源 │
│ 不同问题 → 各自保留 │
└──────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────┐
│ Step 4: 按主题标签归类 │
│ 为每条 FAQ 打上主题标签 │
└─────────────────────────────────────────┘
```
## Step 1: 类型分类
## Step 1: 相似度判断
### 分类 Prompt
### 判断 Prompt
```
你正在分析一个项目的已关闭 Issue。请对每条 Issue 判断它属于以下哪种类型：
你正在判断两个 Issue 是否描述的是同一个问题，是否应该合并为一条 FAQ。
类型定义：
- bug: 描述异常行为、报错、行为与预期不符、数据缺失/错误
- feature: 建议新增功能、增强现有能力、改进体验
- question: 不知道如何使用、配置不清楚、询问是否支持某能力
- other: 不属于以上三类（如测试、讨论、公告）
## Issue A
Q: {Q_A}
A: {A_A}
返回 JSON 数组：
[{
"issue_number": N,
"subject": "标题",
"type": "bug|feature|question|other",
## Issue B
Q: {Q_B}
A: {A_B}
请判断它们是否属于同一问题：
- **same**：描述的是同一个问题，只是表述不同（应合并）
- **related**：涉及同一主题但具体问题不同（不合并，但可放同一主题下）
- **different**：完全不同的问题
返回 JSON：
{
"level": "same|related|different",
"reason": "一句话判断依据"
}]
```
### 分类规则
| 类型 | 判断信号 | 反例（容易误判） |
|------|----------|-----------------|
| **bug** | 含"报错""不生效""异常""不一致""缺失""无法"等 | "希望能 xx"是 feature 不是 bug |
| **feature** | 含"希望""建议""能否支持""加一个""要是能"等 | "xx 不支持"可能是 question |
| **question** | 含"怎么""如何""能不能""是否支持"等，且是咨询性质 | "xx 报错怎么办"→ 先确认是不是 bug |
| **other** | 标题含"test""测试""讨论""收集"等 | 不确定时归为 other |
## Step 2: 类型内聚类
### Bug 聚类
按**出问题的模块/组件/功能**归类，找出高频 Bug 模式。
聚类维度：
- 影响的是哪个命令/接口（如 `issue +view`、`pr +list`、`api` 命令）
- 问题类型是否相同（数据显示错误 ×4 / 命令执行失败 ×2 / 平台兼容 ×1）
- Bug 之间是否存在共同根因
输出格式：
```json
{
"module": "Issue/PR 数据展示",
"bug_count": 4,
"pattern": "CLI 返回数据字段与网页端不一致或字段缺失",
"affected_issues": [5, 7, 15, 18],
"typical_symptom": "使用 view 命令查看详情时，部分字段（如关闭时间、描述等）缺失或与网页端不一致"
}
```
### 功能请求聚类
### 合并判断标准
按**请求的功能领域**归类，找出用户需求热度。
| 判断 | 条件 | 处理 |
|------|------|------|
| **same（合并）** | 两个 Issue 的症状/需求一致，答案也一致或互补 | 合并为一条 FAQ |
| **related（相邻）** | 同一主题但具体问题不同 | 不合并，放在同一主题标签下相邻排列 |
| **different（独立）** | 完全无关 | 各自独立 |
聚类维度：
- 请求的是哪个能力方向（API 增强 / 命令扩展 / 平台支持）
- 是否指向同一个需求的不同表述
- 是否有用户点赞/讨论热度叠加
### 合并判断示例
输出格式：
```
✅ 合并：
Issue #16: Q="安装后运行报 command not found？" A="加入 PATH"
Issue #20: Q="gitlink-cli 命令找不到？" A="检查 PATH 配置"
→ 同一问题，表述不同，合并
❌ 不合并：
Issue #16: Q="安装后运行报 command not found？" A="加入 PATH"
Issue #42: Q="如何配置代理？" A="设置 HTTP_PROXY"
→ 都是安装配置主题，但是不同的问题
```
## Step 2: 合并规则
### 合并后的 Q（问题）
- 选择表述更清晰、更完整的那个 Q
- 如果各有优劣，综合提炼一个新的 Q
### 合并后的 A（答案）
- 优先采用 confidence 更高的 A
- 如果两个 A 互补（各有信息），合并为更完整的答案
- 标注"综合自 Issue #A 和 #B 的讨论"
### 合并后的来源
- 列出所有相关 Issue 编号
- 按编号排序
### 合并示例
```json
// 合并前：3 条独立条目
[
{ "issue": 16, "Q": "安装后运行报 command not found？", "A": "加入 PATH", "confidence": "high" },
{ "issue": 20, "Q": "gitlink-cli 命令找不到？", "A": "检查 ~/.local/bin 在 PATH 中", "confidence": "high" },
{ "issue": 35, "Q": "终端提示 command not found: gitlink-cli", "A": "暂未找到解决方案", "confidence": "low" }
]
// 合并后：1 条 FAQ
{
"feature_area": "API 查询能力增强",
"request_count": 3,
"pattern": "用户希望 API 支持更丰富的查询和操作",
"affected_issues": [9, 14, 21],
"common_ask": "支持按序号查询、返回完整时间字段、读取仓库文件"
"Q": "安装 gitlink-cli 后运行报 command not found 怎么办？",
"A": "将 ~/.local/bin 加入 PATH 环境变量。\\nLinux/Mac: export PATH=$PATH:~/.local/bin\\nWindows: 将 %USERPROFILE%\\.local\\bin 加入系统 PATH",
"confidence": "high",
"sources": [16, 20, 35],
"labels": ["安装配置"]
}
```
### 使用问题聚类（传统 Q&A）
## Step 3: 按主题标签归类
与传统 FAQ 一致：按操作场景归类，提炼"问题 → 答案"。
合并完成后，为每条 FAQ 打上主题标签。每个标签有对应图标，生成文档时章节标题必须带图标。标签体系：
仅当同类 ≥ 2 条时生成 Q&A 条目。
| 图标 | 主题标签 | 适用范围 | 关键词信号 |
|------|----------|----------|------------|
| 🔧 | `安装配置` | 安装、登录、认证、Token、代理、环境变量 | install, auth, login, token, proxy, config, setup |
| 💻 | `CLI 命令` | 命令使用、参数、输出格式、交互 | command, flag, option, output, format |
| 🔗 | `API 与集成` | API 调用、Webhook、CI/CD | api, webhook, ci, cd, integration |
| 📊 | `数据显示` | 数据不一致、字段缺失、展示 | data, field, display, missing, mismatch |
| 🖥️ | `平台兼容` | OS 兼容、环境依赖 | windows, linux, macos, platform, compatibility |
| ⚡ | `性能` | 响应慢、超时、资源 | slow, timeout, performance, memory |
| 💡 | `功能请求` | 用户希望新增/改进 | 希望、能否、建议、支持 |
| 📦 | `其他` | 不属于以上 | — |
## 批次合并
> 一条 FAQ 可以打多个标签。例如一个 Bug 既是 CLI 命令问题又是数据显示问题，就打两个标签。
多批次处理后的合并规则：
## 排序规则
1. 同类型的相同模块/领域 → 合并，更新 issue_count
2. 跨类型的关联 Issue 标注引用（如一个 Bug 可能由某个 Feature Request 修复）
3. 最终按 `bug_count` / `request_count` 降序排列
同一主题标签内的 FAQ 条目按以下顺序排列：
1. 合并来源多的在前（反映问题更常见）
2. 同等数量按 confidence 高的在前
3. 同等 confidence 按 Issue 编号升序

110
skills/gitlink-faq/references/gitlink-faq-collect.md
View File

@ -1,6 +1,6 @@
# gitlink-faq 数据采集
# gitlink-faq 数据采集与 Q&A 提取
> 本文档详细说明 FAQ 生成时 Issue 数据的采集策略和参数。
> 本文档详细说明如何采集 Issue 数据，以及如何从 Issue 中提取"问题 → 答案"对。
## 数据源
@ -8,66 +8,115 @@
|------|------|------|
| Issue 列表（open） | `issue +list --state open --limit 100 --format json` | 仍开放的 Issue |
| Issue 列表（closed） | `issue +list --state closed --limit 100 --format json` | 已关闭的 Issue |
| Issue 详情 | `issue +view --number N --format json` | 含标题、描述、journals（评论历史） |
| Issue 详情 | `issue +view --number N --format json` | 含标题、描述、comment_journals_count（评论数） |
> **关键认知**：GitLink 平台很多已解决的 Issue 不会被及时设为"关闭"状态，存在延迟甚至从未更改状态。因此必须**同时采集 open 和 closed 两份列表**，合并去重后才能得到完整的可分析 Issue 集合。用 `issue +view` 读取的 `journals`（评论讨论历史）比 `status` 字段更能判断一个 Issue 是否"已解决"。
> **关键认知**：GitLink 平台很多已解决的 Issue 不会被及时设为"关闭"状态。因此必须**同时采集 open 和 closed 两份列表**，合并去重后才能得到完整的 Issue 集合。
## 筛选策略
### 有价值 vs 无价值 Issue
采集后需筛选。注意：GitLink API **不支持读取 Issue 评论（journals）**，筛选只能基于 subject + description。
采集后需筛选。注意：GitLink API **不支持读取 Issue 评论（journals）**，提取只能基于 subject + description。
**宽松筛选原则**（只排除明确无价值的）：
| 类型 | 是否纳入 | 原因 |
|------|----------|------|
| 有 description 的 Issue | ✅ 纳入 | description 可能非常详细 |
| 仅有标题无 description | ✅ 纳入 | 标题本身有价值信息 |
| 功能请求 | ✅ 纳入 | 反映用户需求优先级 |
| 有 description 的 Issue | ✅ 纳入 | description 可能包含详细的复现步骤和解决方案 |
| 仅有标题无 description | ✅ 纳入 | 标题本身承载了问题信息 |
| 功能请求 | ✅ 纳入 | 可转为"能否支持 xx？"格式的 FAQ |
| 标题含 `[test]`/`测试` | ❌ 排除 | 纯测试数据 |
| 标题为空或纯占位符 | ❌ 排除 | 无有效信息 |
> 不再排除"功能请求"和"仅有标题"的 Issue。没有评论数据的情况下，最大化保留所有可分析的 Issue。
> **宽松吸纳**：宁可多留一条低质量的，也别漏掉一条有答案的。
### 分批采集
## 分批采集
```
Issue 总量 采集策略
───────── ─────────
< 20 全部采集，逐个读详情（含 journals）
< 20 全部采集，逐个读详情
20-50 全部采集，按标题粗筛后读重点 Issue 详情
50-100 分批采集（每批50），先按标题粗筛
50-100 分批采集（每批 50），先按标题粗筛
> 100 取最近活跃的 100 个，优先高参与度的
```
### 参与度筛选
优先采集"高参与度"的 Issue（更有分析价值）：
- **journals 非空**（有人讨论过）——这是最重要的筛选信号，空 journals 的 Issue 分析价值极低
- journals 中包含维护者回复（优先提取作为答案/修复方案）
- 评论数量 ≥ 2
优先采集"高参与度"的 Issue（更有可能提取到完整答案）：
- `comment_journals_count ≥ 2`（有人讨论过，答案可能来自讨论）
- journals 中包含维护者回复（优先作为答案来源）
- description 中包含"解决""修复""方案""workaround"等关键词
### API 限制：无法读取评论
## Q&A 提取方法
`issue +view` 只返回 `comment_journals_count`（评论数），不返回评论内容。`GET /v1/.../issues/{N}/journals` 端点返回 HTML 而非 JSON，无法通过 API 获取评论正文。
这是整个流程的核心：从每条 Issue 的 `subject` + `description` 中提取"问题（Q）→ 答案（A）"。
因此分析只能基于 `subject` + `description` 两个字段。这也是筛选规则放宽的原因——没有评论作为补充信息，凭标题和描述能分析到的内容更有限，需要尽可能保留更多 Issue 来保证覆盖度。
### 提取 Prompt
```
你正在从项目 Issue 中提取 FAQ 知识库条目。请对每条 Issue 提取 Q&A 对。
## Issue 数据
编号: {number}
标题: {subject}
描述: {description}
评论数: {comment_journals_count}
## 提取规则
1. Q（问题）：用一句话概括这个 Issue 要解决的核心问题。用中文表述，以问号结尾。
2. A（答案）：从 description 中提取解决方案、操作步骤、配置方法、workaround 或官方回复。
- 如果 description 明确描述了解决方法 → 直接提取
- 如果 description 仅有问题描述无解决方案 → A 写"暂未找到解决方案，详见 Issue 讨论"
- 如果 Issue 是功能请求 → A 写当前状态（已支持/开发中/不支持）和替代方案
- 如果 description 为 null 或只有图片 → A 写"Description 无文本内容，无法提取答案"
返回 JSON：
{
"issue_number": N,
"Q": "一句话问题？",
"A": "答案内容",
"confidence": "high|medium|low"
}
```
### 不同类型 Issue 的提取策略
| Issue 实际类型 | Q 模板 | A 提取来源 | 示例 |
|---------------|--------|------------|------|
| Bug 报告 | "为什么出现 xxx 错误/异常？" | description 中的修复步骤、workaround | "为什么执行 gitlink-cli issue +view 返回数据与网页端不一致？" |
| Bug 报告（无修复） | "遇到 xxx 问题怎么办？" | "暂未找到解决方案，详见 Issue 讨论" | |
| 功能请求 | "能否支持 xxx？" | description/journals 中的状态说明 | "能否支持按 Issue 序号查询？" |
| 使用问题 | "如何配置/使用 xxx？" | description 中的步骤说明 | "如何在 CI 环境中配置 gitlink-cli？" |
| 使用问题（无回复） | "xxx 怎么处理？" | "暂未找到解决方案，详见 Issue 讨论" | |
### 答案质量标注
| 标注 | 条件 |
|------|------|
| `high` | description 明确描述了解决方案、修复方法或有维护者回复 |
| `medium` | 有部分相关信息但不够完整，或需要结合其他 Issue |
| `low` | description 只有问题描述，无解决方案；或 description 为空 |
## 输出数据格式
采集后整理为以下结构供聚类使用：
采集提取后整理为以下结构供合并归类使用：
```json
[
{
"number": 142,
"subject": "安装后运行报 command not found",
"description": "按照 README 安装后，终端输入 gitlink-cli 提示...",
"labels": ["bug", "installation"],
"issue_number": 142,
"Q": "安装 gitlink-cli 后运行报 command not found 怎么办？",
"A": "将 ~/.local/bin 加入 PATH 环境变量。Linux/Mac 执行: export PATH=$PATH:~/.local/bin。Windows 将 %USERPROFILE%\\.local\\bin 加入系统 PATH。",
"confidence": "high",
"journal_count": 5,
"last_comment_author": "maintainer",
"resolution": "需要将 ~/.local/bin 加入 PATH"
"labels": ["安装配置"]
},
{
"issue_number": 158,
"Q": "issue +view 命令返回的 JSON 缺少部分字段？",
"A": "暂未找到解决方案，详见 Issue 讨论",
"confidence": "low",
"journal_count": 2,
"labels": ["CLI 命令", "数据显示"]
}
]
```
@ -75,7 +124,6 @@ Issue 总量 采集策略
## API 注意事项
- `issue +list` 的 `--limit` 最大 200，超出需分页（`--page` 参数）
- **`--state` 参数不可靠**：与 PR 列表类似，`--state` 参数可能不严格过滤列表（返回数据中 `closed_count` 才是真实统计）。必须同时拉取 open 和 closed 两份列表并合并去重。
- `issue +view` 的 `journals` 字段包含完整评论历史，是判断解决过程的关键
- `journals` 中的 `body` 字段是评论的纯文本内容，`author.login` 是评论者
- **`--state` 参数不可靠**：与 PR 列表类似，必须同时拉取 open 和 closed 两份列表并合并去重
- **`issue +view` 不返回 journals 内容**：只有 `comment_journals_count`（评论数量），无法通过 API 读取实际评论。`GET /v1/.../issues/{N}/journals` 返回 HTML 而非 JSON。分析只能依靠 `subject` + `description`。
- 大量请求时建议用 `--debug` 查看实际请求 URL，确认分页参数正确

162
skills/gitlink-faq/references/gitlink-faq-generate.md
View File

@ -1,98 +1,116 @@
# gitlink-faq 文档生成
> 如何将分类+聚类结果组织为结构化知识库 Markdown。
> 如何将提取合并后的 Q&A 条目组织为结构化 FAQ 知识库 Markdown。
## 生成原则
- **按类型分章节**：Bug → 功能请求 → 使用问题，每章独立
- **按热度排序**：同类内 Issue 数量多的排在前面
- **数据不足时省略**：某类型 < 2 条时标注"暂无足够数据"，不强行展开
- **来源可追溯**：每条结论后附来源 Issue 编号
- **纯 Q&A 格式**：每个条目是"问题 → 答案 + 来源"，不做统计分析
- **按主题归类**：用主题标签组织章节，不用 Bug/Feature/Question 分类
- **答案有据可查**：每条 FAQ 附来源 Issue 编号
- **数据不足时如实说明**：某主题标签下无条目时省略该章节
- **不编造答案**：无法提取答案的标注"待确认"，不强行写
## 文档结构
参考 [`examples/faq-template.md`](../examples/faq-template.md)。
```markdown
# 📊 Issue 知识库
# 📖 {项目名} FAQ 知识库
> 自动生成 | 数据来源：已关闭 Issue（{N} 条有效）
> 更新时间：{DATE}
> 自动生成 | 收录 {N} 个问题 | 更新时间：{DATE}
> 项目：{OWNER}/{REPO}
>
> 本知识库从项目 Issue 中自动提取，将用户遇到的实际问题与解决方案整理为 FAQ。
## 📂 概览
## {主题标签 1}
| 类型 | 数量 | 聚类数 |
|------|------|--------|
| 🐛 Bug 报告 | {N} | {M} 个模块 |
| 💡 功能请求 | {N} | {M} 个领域 |
| 📖 使用问题 | {N} | {M} 个主题 |
---
## 🐛 Bug 高频模块
### {模块名}（{N} 个 Bug）
**典型症状**: {描述}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})
**已知修复**: {如有则写，无则写"暂未统一修复"}
### {模块名}（{N} 个 Bug）
...
> 如该类 < 2 条，标注"暂无高频 Bug 模式"。
---
## 💡 功能请求热度
### {功能领域}（{N} 个请求）🔥
**用户期望**: {一句话总结}
**涉及 Issue**: [#{编号}]({链接}), [#{编号}]({链接})
### {功能领域}（{N} 个请求）
...
> 如该类 < 2 条，标注"暂无热门功能请求"。
---
## 📖 常见使用问题
### Q{N}: {问题}？
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源 Issue: [#{编号}]({链接}), [#{编号}]({链接})
> 📎 来源: [#{编号}]({链接})
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接}), [#{编号}]({链接})
## {主题标签 2}
...
> 如该类 < 2 条，标注"暂无常见使用问题"。
---
> 💡 本文档由 gitlink-faq 自动生成，建议每 1-2 周更新一次。
```
## 热度标注
## 章节生成规则
| Issue 数 | 热度 |
|----------|------|
| ≥ 5 | 🔥🔥🔥 高频 |
| 3-4 | 🔥🔥 常见 |
| 2 | 🔥 偶发 |
| 1 | 不纳入（标注为单次事件） |
- 按主题标签分组，每个标签一个 `##` 二级标题，**标题前必须带对应图标**（如 `## 🔧 安装配置`）
- 标签内有 ≥ 1 条 FAQ 即生成该章节
- 标签内无条目则省略该章节
- 章节排列顺序及图标：🔧 安装配置 → 💻 CLI 命令 → 🔗 API 与集成 → 📊 数据显示 → 🖥️ 平台兼容 → ⚡ 性能 → 💡 功能请求 → 📦 其他
## 答案/解决状态标注
## Q&A 条目格式
对于 Bug 和功能请求，标注其当前状态：
### 标准格式
| 状态 | 标注 | 条件 |
|------|------|------|
| ✅ 已修复/已实现 | 绿色标记 | Issue 关闭且 journals 中有修复记录 |
| 🔧 部分修复 | 黄色标记 | 有修复但不完整 |
| ❓ 状态不明 | 无标记 | journals 为空或无明确解决记录 |
```markdown
### Q{序号}: {问题}？
**A:** {答案}
> 📎 来源: [#{编号}]({链接}), [#{编号}]({链接})
```
### 序号规则
- 全局递增编号（跨所有主题标签），如 Q1, Q2, Q3...
- 方便引用和检索
### 答案质量标注（可选）
当答案 confidence 为 `low` 时，可在答案中标注：
```markdown
**A:** 暂未找到明确解决方案，详见 Issue 讨论。⚠️ 待确认
```
## 答案编写规范
### DO（应该做的）
- ✅ 答案具体可操作：给出明确的命令、配置、步骤
- ✅ 综合多个来源：合并多个 Issue 的讨论得出完整答案
- ✅ 标注适用范围：如果答案只适用于特定平台/版本，明确说明
- ✅ 引用原始讨论：来源链接让用户可以查看完整上下文
### DON'T（不应该做的）
- ❌ 不编造答案：没有就是没有，写"待确认"
- ❌ 不做统计分析：不写"XX 模块有 N 个 Bug"
- ❌ 不写长篇大论：答案简洁直接，一两段即可
- ❌ 不假设用户背景：用通俗语言，避免术语黑话
## 功能请求类 FAQ 的特殊处理
功能请求类 Issue 转为 FAQ 时，答案应说明**当前状态**而非"应该怎么做"：
```markdown
### Q{N}: 能否支持 xxx 功能？
**A:** 该功能目前已在 v2.1 中支持，使用 `gitlink-cli xxx --flag` 即可。
> 📎 来源: [#{编号}]({链接})
```
或：
```markdown
### Q{N}: 能否支持 xxx 功能？
**A:** 该功能目前暂不支持。替代方案：可以先通过 yyy 方式实现类似效果。详见 Issue 讨论。
> 📎 来源: [#{编号}]({链接})
```
## 输出文件
生成的 Markdown 保存为 `./issue-faq.md`，展示给用户预览，确认后发布到 Wiki。

15
skills/gitlink-faq/references/gitlink-faq-publish.md
View File

@ -9,18 +9,18 @@
```bash
gitlink-cli wiki +create \
--title "Issue-知识库" \
--file ./issue-knowledge-base.md \
--message "自动生成：从已关闭 Issue 归纳分类"
--file ./issue-faq.md \
--message "自动生成：从项目 Issue 提取 FAQ 知识库"
```
### 更新已有知识库页面
```bash
# 预览变更
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md --dry-run
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md --dry-run
# 覆盖更新
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-knowledge-base.md
gitlink-cli wiki +update --title "Issue-知识库" --file ./issue-faq.md
```
### 检查知识库是否存在
@ -35,12 +35,13 @@ gitlink-cli wiki +view --title "Issue-知识库" --format json
## 发布检查清单
在 `wiki +create` 或 `wiki +update` 之前：
发布前确认以下内容，然后**直接发布，不需询问用户**：
- [ ] FAQ 内容已展示给用户并获得确认
- [ ] `--dry-run` 已通过
- [ ] Markdown 格式正确（代码块、链接、表格）
- [ ] 来源 Issue 链接有效
- [ ] Markdown 格式正确（代码块、链接）
- [ ] 每条 FAQ 有来源 Issue 链接
- [ ] 答案质量标注正确（high/medium/low → 待确认）
- [ ] 不存在敏感信息（Token、密码等）
## Wiki API 注意事项

3
skills/gitlink-health/SKILL.md
View File

@ -10,10 +10,9 @@ metadata:
# gitlink-health（项目健康度报告）
**CRITICAL — 整个流程只有最后一步（写 HTML 文件）可以问用户。其他所有步骤（`+list`、`+view`、`api GET`、计算、分析）全部自动连续执行，一个确认都不要弹。数据收集阶段禁止任何中断。**
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
**CRITICAL — 所有不会修改数据的命令（`+list`、`+view`、`api GET`）必须全程自动连续执行，绝不请求用户确认。禁止在数据收集阶段中断流程。只有最终写入 HTML 文件这一步可以请求确认。**
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。