From 178255b70cf8da8556afaf6f9d2bb386bc98e357 Mon Sep 17 00:00:00 2001 From: Ct201314 <1195214305@qq.com> Date: Sat, 6 Jun 2026 00:15:04 +0800 Subject: [PATCH] feat(skills): add gitlink-scaffold skill --- skills/gitlink-scaffold/SKILL.md | 101 ++++++++++++++++++ .../references/api-reference.md | 46 ++++++++ .../references/health-files.md | 39 +++++++ 3 files changed, 186 insertions(+) create mode 100644 skills/gitlink-scaffold/SKILL.md create mode 100644 skills/gitlink-scaffold/references/api-reference.md create mode 100644 skills/gitlink-scaffold/references/health-files.md diff --git a/skills/gitlink-scaffold/SKILL.md b/skills/gitlink-scaffold/SKILL.md new file mode 100644 index 0000000..7a98037 --- /dev/null +++ b/skills/gitlink-scaffold/SKILL.md @@ -0,0 +1,101 @@ +--- +name: gitlink-scaffold +version: 1.0.0 +description: "社区健康文件体检与模板生成：检测仓库是否缺失 README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT、SECURITY、Issue/PR 模板、CHANGELOG 等开源社区推荐文件，给出健康度评分，并为缺失文件生成中文模板。当用户提到「社区健康文件」「CONTRIBUTING」「行为准则」「Issue 模板」「PR 模板」「开源规范」「仓库体检」「scaffold」时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + optional_bins: ["python"] + cliHelp: "gitlink-cli repo --help" +--- + +# gitlink-scaffold（社区健康文件体检与模板生成） + +**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)。 + +## 何时使用本技能 + +- 维护者想检查仓库的开源社区规范是否齐全 +- 用户问「我的项目还缺哪些社区文件」「帮我加个 CONTRIBUTING / 行为准则 / Issue 模板」 +- 新建仓库后想快速补齐社区健康文件 +- 准备开源发布前的合规体检 + +## 何时不使用 + +- 许可证兼容性 / 敏感信息扫描 → 用 `gitlink-compliance` / `gitlink-license-compliance` +- 仅查看仓库基本信息 → 用 `gitlink-repo` + +## 能力概览 + +| 能力 | 说明 | +|------|------| +| 健康文件体检 | 检测 README/LICENSE/CONTRIBUTING/CODE_OF_CONDUCT/SECURITY/Issue 模板/PR 模板/CHANGELOG 是否存在 | +| 健康度评分 | 按权重计算 0-100 分，标记缺失的关键文件 | +| 模板生成 | 为缺失且支持的文件生成可直接使用的中文模板 | + +## 工作流 1：仓库社区健康体检 + +### 方式 A：用配套脚本（推荐） + +```bash +# 体检并输出 Markdown 报告 +python scripts/scaffold.py --owner Gitlink --repo gitlink-cli + +# JSON 输出 +python scripts/scaffold.py --owner Gitlink --repo gitlink-cli --format json +``` + +参数说明： + +| 参数 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `--owner` | string | 是* | 仓库所有者（*或用 `--slug`） | +| `--repo` | string | 是* | 仓库名称 | +| `--slug` | string | 否 | `owner/repo` 或完整 URL | +| `--ref` | string | 否 | 分支或标签，默认 master | +| `--generate` | flag | 否 | 为缺失文件生成模板 | +| `--output-dir` | string | 否 | 模板输出目录，默认 scaffold_out | +| `--format` | string | 否 | `markdown`（默认）或 `json` | +| `--output` | string | 否 | 报告输出文件 | + +### 方式 B：用 gitlink-cli 命令检查 + +```bash +# 列出仓库根目录文件，人工核对社区文件是否齐全 +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=&ref=master' --format json + +# 检查 .gitlink / .github 目录下是否有模板 +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath=.gitlink&ref=master' --format json +``` + +## 工作流 2：生成缺失的模板 + +```bash +# 体检并为缺失文件生成模板到 out/ 目录 +python scripts/scaffold.py --owner Gitlink --repo gitlink-cli --generate --output-dir out + +# 确认模板内容后，由用户决定是否提交到仓库（写操作，需确认） +# 例如通过 gitlink-cli 的文件创建接口提交（参考 gitlink-shared 的文件操作说明） +``` + +可生成模板的文件：CONTRIBUTING、CODE_OF_CONDUCT、SECURITY、Issue 模板、PR 模板、CHANGELOG。 + +## API 注意事项 + +- 检测依赖 `sub_entries` 接口列目录；不同项目把社区文件放在根目录、`.gitlink/`、`.github/` 或 `docs/`，本工具会逐个目录查找。 +- 生成的模板仅写入本地，**提交到仓库是写操作**，需用户确认后再执行。 +- 数据采集全程只读。 + +## 输出示例 + +参见 [`examples/`](examples/)：体检报告与生成的模板文件。 + +## References + +- [api-reference.md](references/api-reference.md) — 采集接口、字段与文件提交说明 +- [health-files.md](references/health-files.md) — 健康文件清单、权重与评分规则 +- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则 diff --git a/skills/gitlink-scaffold/references/api-reference.md b/skills/gitlink-scaffold/references/api-reference.md new file mode 100644 index 0000000..301084d --- /dev/null +++ b/skills/gitlink-scaffold/references/api-reference.md @@ -0,0 +1,46 @@ +# gitlink-scaffold API 参考 + +> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。 + +本技能检测社区健康文件所依赖的接口与字段。采集只读；模板仅生成到本地。 + +## 采集的接口 + +### 列目录（检测文件是否存在） + +``` +GET /:owner/:repo/sub_entries.json?filepath={dir}&ref={ref} +# 或经 gitlink-cli： +gitlink-cli api GET /:owner/:repo/sub_entries --query 'filepath={dir}&ref=master' --format json +``` + +- 查询**目录**时，`entries` 为条目数组，每个含 `name` / `type`(file|dir) / `sha` / `size`。 +- 查询**单文件**时，`entries` 可能为单个对象（本技能已做归一化处理）。 + +本技能会在以下目录查找社区文件：根目录、`.gitlink/`、`.github/`、`docs/`。 + +## 检测的字段 + +| 字段 | 说明 | 用途 | +|------|------|------| +| `entries[].name` | 条目名 | 与候选文件名（不区分大小写）匹配 | +| `entries[].type` | file / dir | 只匹配 file | + +## 写操作（提交模板） + +把生成的模板提交到仓库属于写操作。GitLink 创建文件接口需 base64 编码内容： + +``` +gitlink-cli api POST /:owner/:repo/create_file --body '{ + "filepath": "CONTRIBUTING.md", + "content": "", + "branch": "<分支>", + "message": "docs: add CONTRIBUTING" +}' +``` + +> 注意：gitlink-shared 记录了 Create File 接口的已知问题，提交前请参考其说明，并务必征得用户确认。本技能默认只在本地生成模板。 + +## 错误处理 + +沿用 gitlink-shared 错误码。某目录不存在（404）时本技能视为该目录无文件，继续检查其他目录，不中断。 diff --git a/skills/gitlink-scaffold/references/health-files.md b/skills/gitlink-scaffold/references/health-files.md new file mode 100644 index 0000000..cde5fa8 --- /dev/null +++ b/skills/gitlink-scaffold/references/health-files.md @@ -0,0 +1,39 @@ +# 社区健康文件清单与评分 + +本技能检测 8 类开源社区推荐文件，按权重计算 0-100 健康度分。 + +## 检测清单与权重 + +| 文件 | 权重 | 关键 | 候选文件名 | 查找目录 | +|------|:----:|:----:|------------|----------| +| README | 20 | 是 | readme.md / readme.rst / readme.txt / readme | 根目录 | +| LICENSE | 20 | 是 | license / license.md / license.txt / copying | 根目录 | +| CONTRIBUTING | 15 | 否 | contributing.md / contributing.rst | 根 / .gitlink / .github / docs | +| CODE_OF_CONDUCT | 10 | 否 | code_of_conduct.md / code-of-conduct.md | 根 / .gitlink / .github / docs | +| SECURITY | 10 | 否 | security.md / security | 根 / .gitlink / .github / docs | +| Issue 模板 | 10 | 否 | issue_template.md 等 | 根 / .gitlink / .github / ISSUE_TEMPLATE | +| PR 模板 | 10 | 否 | pull_request_template.md 等 | 根 / .gitlink / .github | +| CHANGELOG | 5 | 否 | changelog.md / changes.md / history.md | 根目录 | + +健康度分 = 已具备文件的权重之和 / 总权重(100) × 100。 + +## 关键文件 + +README 与 LICENSE 标记为**关键文件**，缺失会在报告中以 ❗ 高亮，因为它们是开源项目最基本的要求（说明项目用途、明确授权）。 + +## 可生成模板的文件 + +| 文件 | 生成路径 | 模板语言 | +|------|----------|:--------:| +| CONTRIBUTING | CONTRIBUTING.md | 中文 | +| CODE_OF_CONDUCT | CODE_OF_CONDUCT.md | 中文 | +| SECURITY | SECURITY.md | 中文 | +| Issue 模板 | .gitlink/issue_template.md | 中文 | +| PR 模板 | .gitlink/pull_request_template.md | 中文 | +| CHANGELOG | CHANGELOG.md | 中文 | + +README 与 LICENSE 不自动生成模板（README 需项目特定内容；LICENSE 应由作者选择许可证）。 + +## 多目录查找说明 + +不同项目把社区文件放在不同位置（GitHub 习惯 `.github/`，GitLink 习惯 `.gitlink/`，也有放根目录或 `docs/`）。本技能逐目录查找，命中任一即视为存在，避免误报缺失。