github-repository-presentation

---
name: github-repository-presentation
description: 为 GitHub 仓库按统一模板编写或优化中英双语 README、项目 Description、Topics、使用说明等公开解释性文字，并规范 GitHub Release Notes 的简洁双语表达。当用户要求仓库首页、封面、技术徽章、文案或展示质量时使用；不负责 Git 提交、版本事实判定或远端发布。
---

# GitHub 仓库呈现规范（统一双语模板）

## 使命与边界

为不同仓库应用**同一套 README 结构、视觉语言和中英双语写作规则**，得到高级、克制、清晰、准确的 GitHub 页面。根据项目事实填入内容，而不是按项目类型切换模板。

- 先按需读取真实 README、入口、依赖与配置、使用方式、许可证、相关图片和版本信息；不为写文案遍历整个仓库。
- 本 Skill 主导 README、Description、Topics、公开说明的结构与文字呈现；Release Notes 只规定表达模板与可读性，版本范围、变更事实、提交与发布操作由 `git-release-hygiene` 或实际任务证据决定。
- 在获准的文件范围内可修改文档；修改 GitHub 远端 About/Topics、推送或发布必须符合明确授权和实际权限。
- 不修改业务功能，不夸大能力，不虚构命令、链接、性能、许可证、截图、版本状态、验证经历或变更数量。

## 统一文字与视觉标准

1. **双语用两个文件，不在一个文件里逐段对照**：主 `README.md` 写英文（GitHub 默认展示），`README.zh.md` 写中文；两份都在顶部放指向对方的语言切换链接（如 `[中文](README.zh.md)` / `[English](README.md)`）。两份内容完整对应、各自可独立阅读，语序和章节顺序一致。技术名、命令、文件路径、代码和既有专有名词不强行翻译。代码块各自保留一份。
2. **单一视觉系统**：采用克制、现代、专业的技术项目气质。统一标题层级、图片宽度、徽章风格、段落节奏；默认避免无意义 Emoji、营销形容词、花哨分隔线及装饰性表格。
3. **具体胜于空泛**：说明项目做什么、适用于谁、如何开始、现有限制。避免“最强”“革命性”“全面支持”等无依据表达。
4. **事实分级**：实际文件和已确认行为优先；项目自述、未验证示例、计划功能与模型推断不得混写。未知事实标注或向用户确认；不把尚未运行的命令说成已验证。
5. **同一骨架、按需减法**：README 核心部分顺序固定。配置、目录结构、扩展说明等确实不适用时可省略，不能为凑齐章节制造内容。

## README 统一模板规范

按以下顺序组织；不另外设计 A/B/C 多套风格。

1. **顶部封面图（默认必备）**：README 的首个可见主体是一张横幅封面，建议约 `2:1`，宽度适配 GitHub。封面应以简洁图形、真实产品界面或准确抽象示意传达项目内容；少字或无字，避免虚构功能界面。图像需位于仓库可访问的稳定路径，具有中英双语 `alt`。
   - **缺少封面时**：先寻找现有可用素材；若没有，提出封面设计方案并请求提供素材或授权创建。未取得可用图片前不要写失效的 `src`，也不把占位图当成最终成品。可先交付其余 README 草稿并明确封面待补。
2. **项目身份**：居中的项目名与一句话定位；当前文件用哪种语言，定位就用哪种语言，不在一行里并列两种语言。短而准确，不叠加多个口号。
3. **可点击技术栈徽章**：紧接项目定位，优先展示约 3–8 项确实使用的核心技术或依赖平台；采用风格统一的 Badge，点击后指向对应官方文档或项目主页。无依据不得添加技术，不使用 `#` 假链接；非软件项目可使用实际相关的运行环境、数据格式或技术平台，不能强造“技术栈”。
4. **其他状态徽章（可选）**：仅在信息真实且有有效目标链接时展示 License、Release、CI、Docs、Demo 等；建议少量且一致，不为装饰而堆积。
5. **简短导航（可选）**：仅在 README 较长时添加 4–7 个真实可用的章节链接，核对 GitHub 实际锚点。
6. **简介 / Overview**：用一到两段说明项目是什么、解决什么问题、适用对象与主要价值；标题按当前文件语言书写。
7. **核心特性 / Features**：按用户可感知的能力列出精炼要点，只写已实现或明确标为实验性的功能，不把开发计划列为当前能力。
8. **安装 / Installation**：给出最短可信安装路径、必要前提、可复制命令。若不需要安装，明确说明获取与使用方式，而不是编造安装命令。
9. **使用方式 / Usage**：至少展示一个适用的最小操作示例、命令或实际 UI 流程；技术细节复杂时链接到已有文档，README 不变成完整手册。
10. **配置 / Configuration（按需）**：只列关键配置和重要环境变量；不得展示真实密钥，复杂配置链接到已有文档。
11. **项目结构 / Project Structure（按需）**：只呈现帮助首次理解的核心目录；不逐文件罗列。
12. **更新与发布 / Releases（按需）**：仅提供真实 Releases 或 Changelog 入口及必要状态，不在 README 内复制完整版本历史。
13. **许可证 / License**：如有真实许可证，准确说明并链接 LICENSE；如未声明，不推断为 MIT、Apache 或其他开源许可，必要时明确“尚未声明许可证 / No license specified”。

#**排版约定**：一个主封面；`<h1>` 仅用于项目标题，章节用 `##`；居中只用于首页头部，正文左对齐；图片用仓库相对路径并适配窄屏；重要命令与链接必须可核对，不输出伪造徽章、无效锚点或占位符成品。

### README 固定结构示意（槽位须替换为真实值）

````markdown
<!-- README.md（英文主文件） -->

<p align="center">
  <img src="cover.png" alt="Cover description" width="100%">
</p>

<h1 align="center">Project Name</h1>
<p align="center">One precise English tagline.</p>
<p align="center"><a href="README.zh.md">中文</a></p>

## Overview
English overview.

## Features
- English feature description.

## Installation
```bash
# A real, verified command
```

## Usage
Minimal usage in English.

## License
State the actual license status.
````

````markdown
<!-- README.zh.md（中文文件；结构与英文版一一对应） -->

<p align="center">
  <img src="cover.png" alt="封面说明" width="100%">
</p>

<h1 align="center">项目名称</h1>
<p align="center">一句准确的中文定位。</p>
<p align="center"><a href="README.md">English</a></p>

## 简介
中文简介。

## 核心特性
- 中文功能说明。

## 安装
```bash
# 真实、经核查的命令
```

## 使用方式
中文最小使用说明。

## 许可证
根据仓库真实许可状态说明。
````

## 其他解释性文字

- **Description**：使用一条精炼的中英双语介绍，优先保证准确和自然；遵守 GitHub 字符上限。若双语信息确实无法在限制内准确表达，向用户提出取舍而不是自行改成单语或截断。
- **Topics**：只使用真实领域、用途和生态关键词；遵守 GitHub 当前格式与数量约束。Topics 本质是检索标签，不要求硬译成中英两套。
- **补充文档**：写明适用语言，或同样提供两个文件互链；侧重读者真实操作，不重复 README 全文。
- **PR、Changelog、Release Notes**：使用完整中文版 + 完整英文版两个独立段落，不逐句对照；具体变更归属、Git 证据、版本判定与发布流程以 `git-release-hygiene` 为准。

## Release Notes 双语排版约束

**完整中文版在前，完整英文版在后，两个独立段落**：不逐句对照、不左右并列。GitHub 已有版本标题时正文不再重复大标题。

1. **结构**：`## 中文` 与 `## English` 各写完整一份，类别、条目数和事实完全一致。
2. **变更数量**：中文用 `新增/优化/修复`，英文用 `Added/Improved/Fixed`；计数单位是归并后、面向用户的变更事项，不是代码行数、文件数或 Commit 数。
3. **具体变化**：突出用户可感知变化，不贴实现细节、长日志或逐条 Commit；无相应变化的组直接省略。
4. **重要提醒**：不兼容变更、必要迁移、已知风险必须在两种语言里都写明；无证据时不得宣称“无破坏性变更”。
5. **事实不足**：版本范围、数量无法核实时标明待核实，不编造数字与日期，不把草稿说成已发布。

### Release Notes 固定结构示意

````markdown
## 中文
本次更新主要……。
**变更概览**：新增 X 项 · 优化 Y 项 · 修复 Z 项
**新增** / **优化** / **修复**（仅保留有内容的类别）
- 中文事项。
<!-- 必要时增加 **重要说明** -->

## English
This release focuses on ... .
**Summary**: Added X · Improved Y · Fixed Z
**Added** / **Improved** / **Fixed** (only non-empty groups)
- English item.
<!-- Add **Important Notes** only when needed -->
````

`X/Y/Z` 仅为槽位；最终只保留有变更且计数可核实的类别，版本与日期用已确认信息。

## 完成前核对

- README 是否从真实、可访问的项目封面开始？技术栈徽章是否真实且可点击？
- 是否沿用唯一固定骨架，且 `README.md` 与 `README.zh.md` 互链、内容完整对应、没有虚构或多余填充？
- 安装、使用、许可证、重要链接和视觉素材是否与工作区事实相符？未知项是否明确处理？
- Description、Topics 与 README 是否保持一致？
- Release Notes、CHANGELOG 与 PR 描述是否为「完整中文段 + 完整英文段」，而不是逐句对照？数量是否真实、是否保留必要升级警示？
- 是否仅执行了本次授权的文件改动和远端操作？交付时是否准确说明未验证与未执行事项？