feat: 初始化 skills 仓库，添加 wiki 和 todo 两个 skill
- 添加 wiki skill：文档站管理，支持向 MkDocs 文档站添加/更新技术文档 - SSH 连通性检查脚本 - 文章模板参考（标准格式：摘要→核心概念→详解→代码→陷阱→练习题） - mkdocs.yml 导航结构参考 - 添加 todo skill：任务待办管理，通过自然语言操作 MySQL 待办事项 - LRU 淘汰策略（基于 last_accessed_at） - MySQL MCP 配置指南及建表 SQL - 自然语言到 SQL 的映射规则 - 添加 README.md 说明文档
This commit is contained in:
+103
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: wiki
|
||||
description: |
|
||||
文档站管理 skill。用于向个人 MkDocs 文档站添加、更新或整理技术文档。
|
||||
当用户提到写文档、添加到文档站、整理笔记到 wiki、记录技术知识点、
|
||||
或者想把某段内容发布到文档站时，使用此 skill。
|
||||
支持用户提供主题（自动生成文档）或提供已有内容（整理后发布）。
|
||||
---
|
||||
|
||||
# 文档站管理
|
||||
|
||||
管理 MkDocs Material 文档站，支持添加和更新技术文档。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 1. SSH 连通性检查
|
||||
|
||||
在操作仓库之前，先运行 SSH 检查脚本：
|
||||
|
||||
```bash
|
||||
bash <skill-path>/scripts/check_ssh.sh
|
||||
```
|
||||
|
||||
如果检查失败，告知用户需要配置 SSH 密钥，不要继续操作。
|
||||
|
||||
### 2. 克隆仓库
|
||||
|
||||
```bash
|
||||
TMP_DIR=$(mktemp -d)
|
||||
git clone ssh://git@47.121.181.112:222/wonder/docs.git "$TMP_DIR"
|
||||
```
|
||||
|
||||
后续所有文件操作在 `$TMP_DIR` 中进行。
|
||||
|
||||
### 3. 理解用户意图
|
||||
|
||||
用户可能以不同方式使用此 skill：
|
||||
|
||||
**场景 A — 提供主题**：用户说"写一篇关于 XXX 的文章"
|
||||
- 根据主题判断应该放在哪个章节（algorithm/architecture/project/qiniu-cloud）
|
||||
- 如果章节不明确，询问用户
|
||||
- 按模板生成完整文档
|
||||
|
||||
**场景 B — 提供内容**：用户粘贴了一段文档或笔记
|
||||
- 分析内容主题，判断合适的章节
|
||||
- 整理成标准格式（参考 `references/article-template.md`）
|
||||
- 如果内容不完整，询问用户补充
|
||||
|
||||
**场景 C — 更新现有文档**：用户说"更新 XXX 文章"
|
||||
- 在仓库中找到对应文件
|
||||
- 根据用户要求更新内容
|
||||
|
||||
**场景 D — 章节不明确**：无法确定放在哪里
|
||||
- 列出当前仓库的章节结构供用户选择
|
||||
- 询问用户该内容属于哪个章节，或是否需要新建章节
|
||||
|
||||
### 4. 生成/更新文档
|
||||
|
||||
遵循 `references/article-template.md` 中的标准格式。关键要点：
|
||||
|
||||
- 使用中文撰写
|
||||
- 代码示例以 Go 为主
|
||||
- 包含 mermaid 图表辅助说明
|
||||
- 包含常见陷阱和练习题
|
||||
- 文件名使用 kebab-case
|
||||
|
||||
### 5. 更新导航
|
||||
|
||||
修改 `mkdocs.yml` 的 `nav` 字段，将新文档添加到正确位置，或根据用户指示修改已有条目。
|
||||
|
||||
参考 `references/mkdocs-nav.md` 了解当前导航结构和规范。
|
||||
|
||||
### 6. 提交并推送
|
||||
|
||||
```bash
|
||||
cd "$TMP_DIR"
|
||||
git add .
|
||||
git commit -m "docs: 添加/更新 <文档标题>"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
提交信息遵循 Conventional Commits 格式（参考全局 CLAUDE.md 规范）。
|
||||
|
||||
### 7. 清理
|
||||
|
||||
```bash
|
||||
rm -rf "$TMP_DIR"
|
||||
```
|
||||
|
||||
告知用户文档已推送，CI/CD 会自动部署。
|
||||
|
||||
## 交互原则
|
||||
|
||||
- **章节不确定时必须询问**：不要擅自决定文档位置
|
||||
- **内容不明确时必须询问**：不要编造技术内容
|
||||
- **确认用户意图**：在生成大量内容前，先确认主题和范围
|
||||
- **保持一致性**：新文档的风格应与现有文档一致
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 根据用户指示可以修改已有的 nav 条目（重命名、移动位置、删除等）
|
||||
- 如果需要新建目录，同时创建该目录的 `index.md`
|
||||
- 推送后告知用户 CI/CD 部署通常需要 1-2 分钟
|
||||
@@ -0,0 +1,123 @@
|
||||
# 文章模板
|
||||
|
||||
本文档定义了文档站的标准文章格式。生成文档时必须遵循此模板。
|
||||
|
||||
## 文件命名规范
|
||||
|
||||
- 使用 kebab-case：`cache-breakdown.md`、`bloom-filter.md`
|
||||
- 英文命名，内容用中文
|
||||
- 放入对应主题目录（algorithm/、architecture/、project/ 等）
|
||||
|
||||
## 文章结构模板
|
||||
|
||||
```markdown
|
||||
# 文章标题
|
||||
|
||||
!!! note "一句话摘要，概括本文核心内容"
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
1. **概念一** — 简要说明
|
||||
2. **概念二** — 简要说明
|
||||
3. **概念三** — 简要说明
|
||||
|
||||
## 详解
|
||||
|
||||
### 原理/机制
|
||||
|
||||
用文字和图表解释核心原理。推荐使用 mermaid 图表：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[开始] --> B[处理]
|
||||
B --> C[结束]
|
||||
```
|
||||
|
||||
### 关键参数/配置
|
||||
|
||||
| 参数 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| param1 | 描述 | value1 |
|
||||
| param2 | 描述 | value2 |
|
||||
|
||||
### 对比分析（如有）
|
||||
|
||||
| 特性 | 方案 A | 方案 B |
|
||||
|------|--------|--------|
|
||||
| 特点1 | ... | ... |
|
||||
|
||||
## 代码示例
|
||||
|
||||
```go
|
||||
// 以 Go 语言为主，注释用中文
|
||||
func example() {
|
||||
// 实现细节
|
||||
}
|
||||
```
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
!!! warning "陷阱一"
|
||||
描述常见错误及其规避方法。
|
||||
|
||||
!!! warning "陷阱二"
|
||||
描述另一个需要注意的问题。
|
||||
|
||||
## 练习题
|
||||
|
||||
??? question "题目一：xxx？"
|
||||
??? success "答案"
|
||||
解答内容。
|
||||
|
||||
??? question "题目二：xxx？"
|
||||
??? success "答案"
|
||||
解答内容。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [链接名称](URL) — 简要说明
|
||||
- [链接名称](URL) — 简要说明
|
||||
```
|
||||
|
||||
## 各部分写作要点
|
||||
|
||||
### H1 标题
|
||||
- 简洁明了，使用中文
|
||||
- 不超过 20 个字
|
||||
|
||||
### note admonition（摘要）
|
||||
- 一句话概括全文核心
|
||||
- 让读者 3 秒内判断是否需要阅读
|
||||
|
||||
### 核心概念
|
||||
- 3-5 个关键概念
|
||||
- 每个概念一句话说明
|
||||
- 有序列表
|
||||
|
||||
### 详解
|
||||
- 分小节深入讲解
|
||||
- 优先使用 mermaid 图表辅助说明（流程图、序列图、状态图）
|
||||
- 用表格做对比和参数说明
|
||||
- 代码块用于展示关键逻辑
|
||||
- 详解部分是文章主体，应占全文 60% 以上
|
||||
|
||||
### 代码示例
|
||||
- 完整可运行的 Go 代码
|
||||
- 中文注释，解释关键逻辑
|
||||
- 遵循 Go 命名规范（camelCase 变量，PascalCase 导出）
|
||||
|
||||
### 常见陷阱
|
||||
- 使用 `!!! warning` admonition
|
||||
- 每个陷阱说明：错误现象、原因、解决方案
|
||||
- 2-4 个
|
||||
|
||||
### 练习题
|
||||
- 使用 `??? question` 可折叠
|
||||
- 答案用嵌套的 `??? success "答案"`
|
||||
- 2-3 道题，覆盖文章核心知识点
|
||||
|
||||
### 相关链接
|
||||
- 外部参考链接
|
||||
- 每个链接附简要说明
|
||||
@@ -0,0 +1,121 @@
|
||||
# MkDocs 导航结构参考
|
||||
|
||||
本文档记录文档站的 mkdocs.yml 配置和导航组织规范。
|
||||
|
||||
## 导航结构
|
||||
|
||||
文档站的导航由 `mkdocs.yml` 的 `nav` 字段控制。文档本身不使用 YAML frontmatter。
|
||||
|
||||
### 当前目录结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── index.md # 首页
|
||||
├── javascripts/mathjax.js # MathJax 配置
|
||||
├── algorithm/ # 算法
|
||||
│ ├── index.md # 章节首页
|
||||
│ ├── bloom-filter.md
|
||||
│ ├── bloom-filter-deletion.md
|
||||
│ ├── counting-bloom-filter.md
|
||||
│ ├── cuckoo-filter.md
|
||||
│ ├── heavykeeper.md
|
||||
│ ├── binary-tree-traversal.md
|
||||
│ └── queue.md
|
||||
├── architecture/ # 架构
|
||||
│ ├── index.md
|
||||
│ └── cache/
|
||||
│ ├── index.md
|
||||
│ ├── cache-breakdown.md
|
||||
│ ├── cache-avalanche.md
|
||||
│ └── cache-penetration.md
|
||||
├── project/ # 项目
|
||||
│ ├── index.md
|
||||
│ ├── openapi-billing-architecture.md
|
||||
│ ├── openapi-billing-resume.md
|
||||
│ └── qdata/
|
||||
│ ├── index.md
|
||||
│ ├── architecture.md
|
||||
│ ├── data-governance-etl.md
|
||||
│ ├── deployment.md
|
||||
│ └── resume.md
|
||||
└── qiniu-cloud/ # 七牛云
|
||||
├── index.md
|
||||
├── architecture.md
|
||||
├── ansible-automation.md
|
||||
├── deployment-cicd.md
|
||||
├── security-auth-data.md
|
||||
└── resume-tech-points.md
|
||||
```
|
||||
|
||||
### nav 格式示例
|
||||
|
||||
```yaml
|
||||
nav:
|
||||
- 首页: index.md
|
||||
- 项目:
|
||||
- 项目概述: project/index.md
|
||||
- OpenAPI 计费:
|
||||
- 架构设计: project/openapi-billing-architecture.md
|
||||
- 简历亮点: project/openapi-billing-resume.md
|
||||
- qData:
|
||||
- 概述: project/qdata/index.md
|
||||
- 架构设计: project/qdata/architecture.md
|
||||
- 数据治理: project/qdata/data-governance-etl.md
|
||||
- 部署方案: project/qdata/deployment.md
|
||||
- 简历亮点: project/qdata/resume.md
|
||||
- 架构:
|
||||
- 架构概述: architecture/index.md
|
||||
- 缓存:
|
||||
- 缓存概述: architecture/cache/index.md
|
||||
- 缓存击穿: architecture/cache/cache-breakdown.md
|
||||
- 缓存雪崩: architecture/cache/cache-avalanche.md
|
||||
- 缓存穿透: architecture/cache/cache-penetration.md
|
||||
- 算法:
|
||||
- 算法概述: algorithm/index.md
|
||||
- 布隆过滤器: algorithm/bloom-filter.md
|
||||
- 布隆过滤器删除: algorithm/bloom-filter-deletion.md
|
||||
- 计数布隆过滤器: algorithm/counting-bloom-filter.md
|
||||
- 布谷鸟过滤器: algorithm/cuckoo-filter.md
|
||||
- HeavyKeeper: algorithm/heavykeeper.md
|
||||
- 二叉树遍历: algorithm/binary-tree-traversal.md
|
||||
- 队列: algorithm/queue.md
|
||||
- 七牛云:
|
||||
- 概述: qiniu-cloud/index.md
|
||||
- 架构设计: qiniu-cloud/architecture.md
|
||||
- Ansible 自动化: qiniu-cloud/ansible-automation.md
|
||||
- 部署与 CI/CD: qiniu-cloud/deployment-cicd.md
|
||||
- 安全与认证: qiniu-cloud/security-auth-data.md
|
||||
- 简历技术亮点: qiniu-cloud/resume-tech-points.md
|
||||
```
|
||||
|
||||
## 添加新文档的步骤
|
||||
|
||||
1. **确定章节**：新文档属于哪个顶级章节（algorithm/architecture/project/qiniu-cloud）？是否有子章节？
|
||||
2. **创建文件**：在对应目录下创建 `.md` 文件（kebab-case 命名）
|
||||
3. **更新 nav**：在 `mkdocs.yml` 的 `nav` 中对应位置添加条目
|
||||
4. **更新 index.md**（如需）：如果是新子章节，可能需要更新章节的 `index.md`
|
||||
|
||||
## Section Index 规范
|
||||
|
||||
每个章节目录下的 `index.md` 是该章节的首页/概述页。使用 MkDocs Material 的 `navigation.indexes` 功能：
|
||||
|
||||
```yaml
|
||||
# mkdocs.yml 中启用
|
||||
theme:
|
||||
features:
|
||||
- navigation.indexes
|
||||
```
|
||||
|
||||
`index.md` 通常包含：
|
||||
- H1 标题（章节名称）
|
||||
- 一句话概述
|
||||
- 子文章的链接表格（如有子文章）
|
||||
|
||||
## 命名规范
|
||||
|
||||
| 类型 | 规范 | 示例 |
|
||||
|------|------|------|
|
||||
| 目录名 | 小写 kebab-case | `architecture/`、`qiniu-cloud/` |
|
||||
| 文件名 | 小写 kebab-case | `cache-breakdown.md` |
|
||||
| 章节标题 | 中文 | `# 缓存击穿` |
|
||||
| nav 标签 | 中文 | `缓存击穿: architecture/cache/cache-breakdown.md` |
|
||||
Executable
+80
@@ -0,0 +1,80 @@
|
||||
#!/usr/bin/env bash
|
||||
# 检查当前环境是否有可用的 SSH 私钥，并测试到 Gitea 仓库的连通性
|
||||
# 用法: bash check_ssh.sh [host] [port]
|
||||
# 默认: 47.121.181.112:222
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
HOST="${1:-47.121.181.112}"
|
||||
PORT="${2:-222}"
|
||||
USER="git"
|
||||
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[0;33m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
echo "=== SSH 私钥检查 ==="
|
||||
|
||||
# 1. 检查 ssh-agent 中是否有加载的密钥
|
||||
if ssh-add -l 2>/dev/null | grep -q "."; then
|
||||
echo -e "${GREEN}[✓]${NC} ssh-agent 中有已加载的密钥"
|
||||
else
|
||||
echo -e "${YELLOW}[!]${NC} ssh-agent 中没有加载的密钥，将尝试使用 ~/.ssh/ 中的默认密钥"
|
||||
fi
|
||||
|
||||
# 2. 检查常见私钥文件是否存在
|
||||
FOUND_KEY=false
|
||||
for key_file in ~/.ssh/id_ed25519 ~/.ssh/id_rsa ~/.ssh/id_ecdsa ~/.ssh/id_dsa; do
|
||||
if [ -f "$key_file" ]; then
|
||||
echo -e "${GREEN}[✓]${NC} 找到私钥: $key_file"
|
||||
FOUND_KEY=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$FOUND_KEY" = false ]; then
|
||||
echo -e "${RED}[✗]${NC} 未找到任何默认 SSH 私钥（~/.ssh/id_ed25519, id_rsa, id_ecdsa, id_dsa）"
|
||||
echo ""
|
||||
echo "请生成一个新的 SSH 密钥:"
|
||||
echo " ssh-keygen -t ed25519 -C 'your_email@example.com'"
|
||||
echo ""
|
||||
echo "然后将公钥添加到 Gitea:"
|
||||
echo " cat ~/.ssh/id_ed25519.pub"
|
||||
echo " # 在 Gitea 的 Settings → SSH Keys 中添加"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 3. 测试 SSH 连通性
|
||||
echo ""
|
||||
echo "=== 测试 SSH 连通性 ==="
|
||||
echo "连接到 ${USER}@${HOST}:${PORT} ..."
|
||||
|
||||
if ssh -o StrictHostKeyChecking=accept-new \
|
||||
-o ConnectTimeout=10 \
|
||||
-o BatchMode=yes \
|
||||
-p "$PORT" \
|
||||
"${USER}@${HOST}" 2>&1 | grep -qi "welcome\|gitea\|hello\|ssh"; then
|
||||
echo -e "${GREEN}[✓]${NC} SSH 连接成功"
|
||||
exit 0
|
||||
else
|
||||
# ssh 返回非 0 但可能仍然成功（Gitea 会断开连接，返回码可能不为 0）
|
||||
# 尝试实际 git ls-remote 来验证
|
||||
if git ls-remote "ssh://${USER}@${HOST}:${PORT}/wonder/docs.git" HEAD >/dev/null 2>&1; then
|
||||
echo -e "${GREEN}[✓]${NC} SSH 认证成功（可以访问仓库）"
|
||||
exit 0
|
||||
else
|
||||
echo -e "${RED}[✗]${NC} SSH 连接失败"
|
||||
echo ""
|
||||
echo "可能的原因:"
|
||||
echo " 1. 私钥未添加到 Gitea"
|
||||
echo " 2. SSH 代理未运行"
|
||||
echo " 3. 网络不通"
|
||||
echo ""
|
||||
echo "请尝试:"
|
||||
echo " eval \$(ssh-agent -s)"
|
||||
echo " ssh-add ~/.ssh/id_ed25519"
|
||||
echo " ssh -p $PORT ${USER}@${HOST}"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
Reference in New Issue
Block a user